feat(ts-sdk): batch outputs (JSON/HTML/CSV) + family-aware CLI with non-interactive mode

[adnanrhussain]

Summary

Stacked on #152. Adds the output projections and the CLI flow for the family-adapter batch tool, making the math-standards-alignment family reachable end-to-end.

What changed

Outputs (WS4)

• renderOutputs(familyId, output, meta) dispatches per family → { csv, json, html }.
• Standards family: joinable JSON (per-item verdicts with full per-component detail + each row's original columns), flat CSV (roll-ups + aligned_ratio, per-component detail as embedded JSON), and a self-contained HTML verdict browser (per-item aligned/total, expandable per-component reasoning/feedback, filter by standard/grade/status/text). Verdicts only — aggregate flag-rate/coverage is downstream interpretation.
• Generic formatAsJSON for the text-complexity family.

CLI (WS5)

• Family → member selection (--family, --evaluator id[,id...], repeatable; interactive multiselect otherwise).
• --model <shortcode|provider:model> (shortcodes: haiku, opus) — also fixes the missing --model alias.
• Credential resolution driven by the family's requiredKeys, including the always-required platform key for standards (--platform-api-key / PLATFORM_API_KEY).
• -y/--yes (and auto when no TTY) → non-interactive: never prompts, errors on missing input. Writes results.csv + results.json + results.html.

Validation

• 386 unit tests pass; typecheck + lint clean; tsup build bundles the HTML template.
• Mutation tested with Stryker: standards-output.ts at 93% on covered code (11 survivors), output.ts at 100%. Line coverage was 100% before this pass and hid real gaps — CSV quote/comma/newline escaping and every HTML </>/&/U+2028 escape were executed but unasserted, so a mutant removing them survived. injectReportData is extracted so the template-corruption guard is reachable without corrupting the real template. The remaining survivors are equivalent mutants (redundant !== null guards already covered by totalCount > 0) and toLocaleString date-format options, where asserting an exact locale string would be brittle.
• End-to-end on the real Grade 4–5 corpus (2,738 items) via a throwaway JSONL→CSV converter (kept out of the package): CLI parsed the real CSV, mapped aliases (ccss_standard→statementCode), resolved family/member, passed the row limit; on a 3-row slice with dummy keys it drove the full path to a real Knowledge Graph 401, proving request construction + per-row error isolation (3/3 errored, no whole-run abort) + all three outputs written with joinable originalRow. Successful-verdict path needs live keys.

Review fixes

• Report payload no longer acts as a String.replace pattern. It was passed as the replacement
  string, so $$/$&/$`/$' in row data were substitution patterns: $$x^2$$ in a question
  rendered as $x^2$, and $' spliced the template tail — including the closing </script> — into the
  inline script, defeating the escaping applied to the payload immediately above. Now a replacer function.
• --evaluator selection drives credential requirements. requiredKeys ignored the selected members,
  so running only grade-level-appropriateness (Google) still demanded an OpenAI key and blocked an
  otherwise valid non-interactive run. QTC now unions each selected member's defaultProviders.
• Outputs read canonical columns instead of re-deriving them. toRow used a hand-rolled, case-sensitive
  alias list that disagreed with the family's ColumnSpec (missing statement_code/standard, inventing
  item_id), so headers the CLI accepts on input were dropped from the reports. BatchResult now carries
  the normalized columns, item_id is a declared alias, and the source-row fallback matches
  case-insensitively against the spec's own aliases.

Not included

• The throwaway Bloomy JSONL→CSV converter (one-off, uncommitted by design).

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Adds family-aware batch output rendering (CSV/JSON/HTML) and extends the batch CLI to support evaluator families, member selection, model shortcodes, platform key resolution, and a non-interactive mode—making the math-standards-alignment family runnable end-to-end.

Changes:

• Introduces renderOutputs() dispatching per-family output projections (standards: specialized CSV/JSON/HTML; others: existing formatters + new generic JSON).
• Adds standards verdict browser HTML template + standards-specific output formatting utilities.
• Updates CLI + arg parsing to support --family, --evaluator, --model shortcodes/provider:model, --platform-api-key, and --yes non-interactive flow.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
sdks/typescript/tests/unit/batch/output.test.ts	Adds unit tests for standards-family JSON/CSV/HTML projections and generic JSON for text-complexity.
sdks/typescript/tests/unit/batch/cli-args.test.ts	Adds tests for new CLI flags and resolveModel() behavior.
sdks/typescript/src/batch/README.md	Updates documentation for families, required columns/keys, and new CLI usage modes.
sdks/typescript/src/batch/output.ts	Adds renderOutputs() to select standards vs generic projections.
sdks/typescript/src/batch/index.ts	Exposes formatAsJSON, renderOutputs, and OutputBundle from the batch module.
sdks/typescript/src/batch/formatters.ts	Adds formatAsJSON() for generic machine-readable results (text-complexity).
sdks/typescript/src/batch/families/standards-report.html	Introduces self-contained HTML verdict browser template for standards results.
sdks/typescript/src/batch/families/standards-output.ts	Adds standards-specific CSV/JSON/HTML projection implementation and HTML injection.
sdks/typescript/src/batch/cli.ts	Refactors CLI to be family/member aware, support non-interactive mode, resolve required keys, and write 3 outputs.
sdks/typescript/src/batch/cli-args.ts	Adds parsing for new flags and implements MODEL_SHORTCODES + resolveModel().

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.