Library API: Assertion object model + run_issue_tests reporting API

[gaurav]

Stacked on #95 (base branch is library-packaging), which is itself stacked on #67. This is the second of two follow-up PRs making the GitHub-issue test framework usable as a library; see #67 for how they relate. Review #95 first.

This PR gives downstream tools (the Babel pipeline and Babel Explorer) a clean object model and a pytest-independent way to run issue tests and report results.

Changes

• GitHubIssueTest → Assertion (back-compat alias kept). Stop storing the live PyGitHub Issue; capture the few fields actually used (issue_id, url, state) as plain strings at construction, so the object is picklable and trivial to build in tests/other tools. Adds name/is_known accessors and run(), which yields (param_set, TestResult) pairs (running one param_set at a time so every result is attributable to its source; the cached clients dedupe the network calls).
• babel_validation/runner.py: run_issue_tests() / run_assertions() returning IssueReport + ResultRecord. The library now owns the expectation rules — open issue ⇒ expected-fail (all-pass ⇒ closeable), closed issue ⇒ expected-pass (any-fail ⇒ reopened) — instead of burying them in the pytest test.
• babel_validation/__init__.py: export the public surface (Assertion, GitHubIssuesTestCases, run_issue_tests, run_assertions, IssueReport, ResultRecord, CachedNodeNorm, CachedNameRes, TestResult, TestStatus).
• tests/github_issues/test_github_issues.py: now a thin adapter that maps an IssueReport onto pytest outcomes (xfail/subtests/skip/fail) — behavior unchanged.
• tests/github_issues/test_runner.py: offline unit tests for the runner with fake services, also exercising the public import surface.
• README: "Use as a library" section with the Explorer (run_issue_tests) and Babel (parse + custom executor) usage examples.

Two consumer use-cases this enables

• Babel Explorer (Streamlit): "run all issue tests from repo X against NodeNorm Y / NameRes Z and report which passed/failed + messages" → run_issue_tests(...) → IssueReports.
• Babel pipeline: fetch Assertions and run them against local DuckDB/JSON with a custom executor (reads assertion/param_sets), to flag closeable/reopened issues before data reaches NodeNorm.

Verification

• uv run pytest -m unit → green (57 passed: 49 existing + 8 new runner tests).
• uv build ships babel_validation/runner.py and the populated __init__; from babel_validation import Assertion, run_issue_tests works.

Follow-up ideas (out of scope; tracked separately)

Library-usability improvements identified during this work, deliberately left out of these PRs:

• Ship a py.typed marker so consumers get type-checking #97 — ship a py.typed marker so consumers get type-checking
• Make CachedNodeNorm/CachedNameRes caches scopable and timeouts configurable for long-lived consumers #98 — make service caches scopable and request timeouts configurable for long-lived consumers (e.g. the Streamlit app)
• Tag versioned releases so downstream tools can pin babel-validation #99 — tag versioned releases so downstream tools can pin a version instead of a commit SHA
• Optionally factor BabelTest parsing out from GitHub fetching (futureproofing) #100 — (futureproofing, low priority) optionally factor BabelTest parsing out from GitHub fetching, for if/when tests move off GitHub or into another format

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR evolves the GitHub-issue-driven test framework into a more library-friendly API by introducing a picklable Assertion object model and a pytest-independent execution/reporting layer (run_assertions / run_issue_tests) that downstream tools can consume.

Changes:

• Introduces Assertion (with a back-compat alias) that stores only plain issue metadata and provides a run() method yielding per-param_set results.
• Adds babel_validation.runner with IssueReport/ResultRecord plus orchestration helpers for library consumers, and rewires pytest to act as a thin adapter.
• Exposes a public import surface via babel_validation.__init__, adds offline runner unit tests, and documents library usage in the README.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/github_issues/test_system.py	Updates a test comment to reflect Assertion rename.
tests/github_issues/test_runner.py	Adds offline unit coverage for the new runner/reporting layer and public API imports.
tests/github_issues/test_github_issues.py	Refactors pytest integration into a thin adapter over run_assertions.
src/babel_validation/sources/github/github_issues_test_cases.py	Introduces Assertion, stops retaining live PyGitHub Issue, and adds run() for per-param-set execution.
src/babel_validation/runner.py	Adds pytest-independent execution/reporting API (IssueReport, ResultRecord, run_*).
src/babel_validation/init.py	Defines and exports the library’s public API surface.
README.md	Adds “Use as a library” documentation and examples.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.