qa-engineer 0.9.1 → 0.10.0

package/skills/qa-run/references/deterministic-tooling.md

@@ -17,7 +17,7 @@ resolves its own location. There is nothing to set up and no shell features are
 involved:
 
 ```bash
-python3 <skill-dir>/scripts/qa_tool.py <tool> <subcommand> [args]
+node <skill-dir>/scripts/qa-tool.mjs <tool> <subcommand> [args]
 ```
 
 `<skill-dir>` is wherever the host installed this skill — usually
@@ -25,19 +25,21 @@ python3 <skill-dir>/scripts/qa_tool.py <tool> <subcommand> [args]
 whichever exists.
 
 ```bash
-python3 .agents/skills/qa-run/scripts/qa_tool.py analysis junit test-results/results.xml
+node .agents/skills/qa-run/scripts/qa-tool.mjs analysis junit test-results/results.xml
 ```
 
-That line is identical in bash, zsh, PowerShell, and cmd.exe. **On Windows, use
-`python` if `python3` is not on PATH** — that is the only platform difference.
+That line is identical in bash, zsh, PowerShell, and cmd.exe, with no platform
+difference at all: it runs under the same Node the user already had to install the
+pack.
 
-An earlier version of this contract used a shell recipe
-(`QA_LIB="$(ls -d … | head -1)"` with a `PYTHONPATH=` prefix). It was POSIX-only,
-so on Windows every deterministic call failed, each skill fell back to its manual
-path, and the user silently got guesswork while believing the tooling had run.
-Never reintroduce a shell-dependent invocation.
+Two earlier versions of this contract failed the same way. The first was a shell
+recipe (`QA_LIB="$(ls -d … | head -1)"` with a `PYTHONPATH=` prefix), POSIX-only, so
+on Windows every deterministic call failed and each skill fell back to guesswork
+while appearing to have run its tooling. The second was portable but needed a Python
+interpreter the user never agreed to install. Never reintroduce a shell-dependent
+invocation, and never add a runtime the install did not already require.
 
-If `qa_tool.py` is missing, the engine is not installed: say so, recommend
+If `qa-tool.mjs` is missing, the engine is not installed: say so, recommend
 `qa repair`, use the skill's documented fallback, and mark the result degraded.
 
 Every tool writes JSON to stdout. Exit `0` means success; exit `1` means an
@@ -45,33 +47,35 @@ invalid contract; exit `2` means unreadable input, a malformed artifact, or a
 payload that failed its seam contract, and the JSON body carries `error` and
 `detail`. Treat a non-zero exit as missing evidence, never as a value to guess.
 
-Standard-library Python 3.8+ only — nothing to install.
+Dependency-free Node — nothing to install beyond the Node that ran `npx`.
 
-## 2. Analysis core — `qa_tool.py analysis`
+## 2. Analysis core — `qa-tool.mjs analysis`
 
 Framework-agnostic parsing, redaction, and validation.
 
 | Subcommand | Invocation | Returns |
 | --- | --- | --- |
-| `junit` | `python3 <skill-dir>/scripts/qa_tool.py analysis junit <report.xml>` | `{tests: {...}, executed: [...]}` normalized counts and per-test outcomes |
-| `har` | `python3 <skill-dir>/scripts/qa_tool.py analysis har <file.har> [--slow-ms N]` | Redacted request/response summary, failures, slow calls |
-| `discover` | `python3 <skill-dir>/scripts/qa_tool.py analysis discover [--root DIR] [--path P]` | Artifacts found, by type, with presence flags |
-| `diff-guard` | `python3 <skill-dir>/scripts/qa_tool.py analysis diff-guard <diff-file>` | `{issues: [...], safe: bool}` — `safe:false` blocks the change |
-| `redact` | `python3 <skill-dir>/scripts/qa_tool.py analysis redact <file>` | The file's text with credentials masked |
-| `validate` | `python3 <skill-dir>/scripts/qa_tool.py analysis validate <instance.json> <schema.json>` | `{valid: bool, errors: [...]}`; exit 1 when invalid |
-| `classify` | `python3 <skill-dir>/scripts/qa_tool.py analysis classify "<error message>" [--http-status N]` | `{classification, confidence, reason}` from the shared taxonomy |
-| `context` | `python3 <skill-dir>/scripts/qa_tool.py analysis context [--root DIR] [--path .qa/context.md]` | The parsed, schema-validated project context as JSON |
-
-## 3. Diagnostic engine — `qa_tool.py diagnostics`
+| `junit` | `node <skill-dir>/scripts/qa-tool.mjs analysis junit <report.xml>` | `{tests: {...}, executed: [...]}` normalized counts and per-test outcomes |
+| `har` | `node <skill-dir>/scripts/qa-tool.mjs analysis har <file.har> [--slow-ms N]` | Redacted request/response summary, failures, slow calls |
+| `discover` | `node <skill-dir>/scripts/qa-tool.mjs analysis discover [--root DIR] [--path P]` | Artifacts found, by type, with presence flags |
+| `diff-guard` | `node <skill-dir>/scripts/qa-tool.mjs analysis diff-guard <diff-file>` | `{issues: [...], safe: bool}` — `safe:false` blocks the change |
+| `redact` | `node <skill-dir>/scripts/qa-tool.mjs analysis redact <file>` | The file's text with credentials masked |
+| `validate` | `node <skill-dir>/scripts/qa-tool.mjs analysis validate <instance.json> <schema.json>` | `{valid: bool, errors: [...]}`; exit 1 when invalid |
+| `classify` | `node <skill-dir>/scripts/qa-tool.mjs analysis classify "<error message>" [--http-status N]` | `{classification, confidence, reason}` from the shared taxonomy |
+| `context` | `node <skill-dir>/scripts/qa-tool.mjs analysis context [--root DIR] [--path .qa/context.md]` | The parsed, schema-validated project context as JSON |
+| `report-html` | `node <skill-dir>/scripts/qa-tool.mjs analysis report-html <result.json> [--out report.html]` | The result rendered as one self-contained HTML report — every required field, footer included. Run it instead of writing HTML |
+| `branding` | `node <skill-dir>/scripts/qa-tool.mjs analysis branding --format markdown\|html\|text` | The exact attribution footer bytes for a **rendered** report (never for a JSON artifact) |
+
+## 3. Diagnostic engine — `qa-tool.mjs diagnostics`
 
 One engine, consumed by the diagnostic skills. Reasoning lives here once.
 
 | Subcommand | Invocation | Returns |
 | --- | --- | --- |
-| `diagnose` | `python3 <skill-dir>/scripts/qa_tool.py diagnostics diagnose --execution-result <path> [--analysis-result <path>]` | `{entries: [...], timeline: [...], recommendations: [...]}` |
-| `plan-repairs` | `python3 <skill-dir>/scripts/qa_tool.py diagnostics plan-repairs --diagnosis <path>` | `{plans: [...]}` — one plan per entry, escalations included |
-| `summarize` | `python3 <skill-dir>/scripts/qa_tool.py diagnostics summarize --execution-result <path> --diagnosis <path>` | `{totals, byClassification, topPriority, releaseReadiness}` |
-| `report` | `python3 <skill-dir>/scripts/qa_tool.py diagnostics report --execution-result <path> [--analysis-result <path>]` | `{diagnosis, plans, summary}` — all three in one call |
+| `diagnose` | `node <skill-dir>/scripts/qa-tool.mjs diagnostics diagnose --execution-result <path> [--analysis-result <path>]` | `{entries: [...], timeline: [...], recommendations: [...]}` |
+| `plan-repairs` | `node <skill-dir>/scripts/qa-tool.mjs diagnostics plan-repairs --diagnosis <path>` | `{plans: [...]}` — one plan per entry, escalations included |
+| `summarize` | `node <skill-dir>/scripts/qa-tool.mjs diagnostics summarize --execution-result <path> --diagnosis <path>` | `{totals, byClassification, topPriority, releaseReadiness}` |
+| `report` | `node <skill-dir>/scripts/qa-tool.mjs diagnostics report --execution-result <path> [--analysis-result <path>]` | `{diagnosis, plans, summary}` — all three in one call |
 
 **Inputs.** `--execution-result` takes a `qa-run` execution result, or the minimal
 subset (`tests` counts plus `executed[]` entries carrying `status`).
@@ -99,7 +103,7 @@ contract names:
 
 This mapping is not busywork: the strictness is what stops a skill from shipping a
 result whose shape nobody checked. Validate before completion —
-`python3 <skill-dir>/scripts/qa_tool.py analysis validate <result.json> <schema.json>` — and fix the
+`node <skill-dir>/scripts/qa-tool.mjs analysis validate <result.json> <schema.json>` — and fix the
 result, never the claim.
 
 ## 4. Framework adapters
@@ -109,11 +113,11 @@ a `--framework` flag.
 
 | Adapter | Invocation | Returns |
 | --- | --- | --- |
-| Playwright report | `python3 <skill-dir>/scripts/qa_tool.py playwright report <results.json>` | The same `{tests, executed}` shape as `junit` |
-| Playwright trace | `python3 <skill-dir>/scripts/qa_tool.py playwright trace <trace.zip>` | Actions, console/network counts, errors, classification |
+| Playwright report | `node <skill-dir>/scripts/qa-tool.mjs playwright report <results.json>` | The same `{tests, executed}` shape as `junit` |
+| Playwright trace | `node <skill-dir>/scripts/qa-tool.mjs playwright trace <trace.zip>` | Actions, console/network counts, errors, classification |
 
 For Selenium, Cypress, and WebdriverIO, normalize through
-`qa_tool.py analysis junit` — those adapters have no richer artifact than JUnit, and
+`qa-tool.mjs analysis junit` — those adapters have no richer artifact than JUnit, and
 the skill says so rather than implying trace-grade depth.
 
 ## 5. Reporting what ran

package/skills/qa-run/references/evidence-and-reporting.md

@@ -27,17 +27,42 @@ Any skill that reaches a conclusion — a detected fact, a chosen strategy, a cl
 | Confidence | Calibrated per rule 4; omitted rather than invented when the skill did not weigh alternatives |
 | Recommendations | The next action, named concretely — often the next command and the artifact to feed it |
 
+## Rendering the HTML report
+
+**Never type the HTML.** When a skill's result conforms to a contract the renderer
+supports, the HTML report is generated from that artifact:
+
+```bash
+node <SKILL_DIR>/scripts/qa-tool.mjs analysis report-html <result.json> --out <report.html>
+```
+
+The reason is not tidiness. A hand-written report is a second, lossy copy of the
+artifact, and it loses exactly what the reader needs: the first live `/qa-explore`
+run wrote findings whose `actual`, `expected`, and `fixDirection` were all required,
+all present in the JSON, and all absent from the page — collapsed into one sentence
+that left the reader to guess what correct behaviour would have been. The renderer
+cannot make that mistake, because the fields are in its template.
+
+What the renderer guarantees per finding: severity, the defect, **what happens
+now**, **what should happen instead**, how to reproduce it, the fix direction, and
+every evidence entry — plus the attribution footer, in one self-contained file with
+no external assets.
+
+Run `qa-tool.mjs analysis report-html --help` for the supported contracts. For an
+artifact it does not support, write the HTML by hand from the contract's fields —
+and render **every** field a reader needs, in that order.
+
 ## Attribution on rendered reports
 
 A report a person opens carries a product attribution footer, the way a Lighthouse
 or Allure report does. It is rendered, never typed: the exact bytes come from the
 bundled analysis toolkit, so every report is identical and a wording change is a
-one-file edit.
+one-file edit. `report-html` already embeds it; for any other rendering, ask for it:
 
 ```bash
-PYTHONPATH="$QA_LIB" python3 -m qa_analysis.cli branding --format html
-PYTHONPATH="$QA_LIB" python3 -m qa_analysis.cli branding --format markdown
-PYTHONPATH="$QA_LIB" python3 -m qa_analysis.cli branding --format text
+node <SKILL_DIR>/scripts/qa-tool.mjs analysis branding --format markdown
+node <SKILL_DIR>/scripts/qa-tool.mjs analysis branding --format html
+node <SKILL_DIR>/scripts/qa-tool.mjs analysis branding --format text
 ```
 
 Append the output as the last element of the rendered document: `html` inside

package/skills/qa-run/scripts/qa-tool.mjs

@@ -0,0 +1,126 @@
+// synced-from: shared/tooling/qa-tool.mjs — do not edit; edit the source and run: node scripts/sync-shared.mjs --write
+// The launcher every skill invokes to reach the deterministic engine.
+//
+// A skill's SKILL.md documents exactly one command shape:
+//
+//     node <SKILL_DIR>/scripts/qa-tool.mjs <tool> <subcommand> [args]
+//
+// and this file finds the engine, wherever it happens to be. That indirection
+// exists because the pack is installed three different ways and the engine lands in
+// a different place each time:
+//
+//   1. `qa install` bundles the engine into the skill, at ./lib/. Offline, fastest,
+//      and pinned to the version that was installed.
+//   2. `npx skills add <owner>/<repo>` — or any generic file copier — copies the
+//      skill directory out of git and bundles nothing. The engine is then resolved
+//      from node_modules if the project happens to depend on the pack.
+//   3. Neither: fall back to `npx qa-engineer`, which fetches the published package
+//      on first use and is served from the npm cache afterwards.
+//
+// Because this file is committed rather than generated, path 2 works at all — which
+// is what makes the pack installable by the wider Agent Skills ecosystem. The
+// command a skill runs never changes; only where the engine came from does.
+//
+// Exit codes pass through unchanged: 0 success, 1 an invalid contract, 2 unreadable
+// input or bad usage.
+//
+// No shebang: the synced copies carry a provenance marker on line one, which would
+// sit above it and stop the kernel seeing it anyway. Every documented invocation is
+// `node qa-tool.mjs …`, which needs none.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+const USAGE = `usage: node qa-tool.mjs <tool> <subcommand> [args]
+
+  analysis     parse artifacts, classify errors, validate contracts, diff-guard,
+               read .qa/context.md, render an HTML report, print the footer
+  diagnostics  root cause, timeline, priority, repair plans, release readiness
+  playwright   normalize a Playwright report or summarize a trace
+
+  --where      print how the engine was resolved, and stop
+
+examples:
+  node qa-tool.mjs analysis junit test-results/results.xml
+  node qa-tool.mjs analysis report-html qa-artifacts/explore-result.json --out report.html
+  node qa-tool.mjs diagnostics report --execution-result qa-artifacts/run.json
+`;
+
+/**
+ * Where the engine is, and how we found it.
+ *
+ * Ordered by cost: a bundled copy needs no resolution and no network, a
+ * node_modules copy needs no network, and npx needs both on first use. Reporting
+ * *which* one answered matters when a skill degrades — "the engine is missing" and
+ * "the engine is being fetched" are different problems.
+ */
+function resolveEngine() {
+  const bundled = path.join(here, 'lib', 'bin', 'qa-engine.mjs');
+  if (fs.existsSync(bundled)) return { kind: 'bundled', command: [process.execPath, bundled] };
+
+  for (const base of candidateModuleRoots()) {
+    const installed = path.join(base, 'qa-engineer', 'packages', 'engine', 'bin', 'qa-engine.mjs');
+    if (fs.existsSync(installed)) {
+      return { kind: 'node_modules', command: [process.execPath, installed] };
+    }
+  }
+
+  return {
+    kind: 'npx',
+    command: [npxCommand(), '--yes', 'qa-engineer', 'engine'],
+  };
+}
+
+/** node_modules directories worth checking, nearest first. */
+function candidateModuleRoots() {
+  const roots = [];
+  let dir = here;
+  for (let depth = 0; depth < 12; depth += 1) {
+    roots.push(path.join(dir, 'node_modules'));
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  if (process.cwd() !== here) roots.push(path.join(process.cwd(), 'node_modules'));
+  return roots;
+}
+
+// `npx` is a shell script on POSIX and a .cmd shim on Windows; spawnSync needs the
+// exact name, and `shell: true` would put user-supplied arguments through a shell.
+function npxCommand() {
+  return process.platform === 'win32' ? 'npx.cmd' : 'npx';
+}
+
+function main(argv) {
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    process.stdout.write(USAGE);
+    return argv.length === 0 ? 2 : 0;
+  }
+
+  const engine = resolveEngine();
+
+  if (argv[0] === '--where') {
+    process.stdout.write(`${JSON.stringify({ resolved: engine.kind, command: engine.command }, null, 2)}\n`);
+    return 0;
+  }
+
+  const [program, ...prefix] = engine.command;
+  const run = spawnSync(program, [...prefix, ...argv], { stdio: 'inherit' });
+
+  if (run.error) {
+    // Say which path was tried and what to do, because a skill's fallback prose
+    // cannot diagnose this and the user is the one who has to fix it.
+    const advice = engine.kind === 'npx'
+      ? 'the engine is not bundled and npx is unavailable — run `npx qa-engineer install` in this project, or install Node 18+'
+      : `could not execute ${program}`;
+    process.stderr.write(`qa-tool: ${advice}\n${run.error.message}\n`);
+    return 2;
+  }
+  return run.status ?? 2;
+}
+
+process.exitCode = main(process.argv.slice(2));

package/shared/analysis/lib/qa_analysis/__init__.py

@@ -1,11 +0,0 @@
-"""qa_analysis — the pack's deterministic analysis core.
-
-Framework-agnostic tooling shared by every diagnostic skill: redaction,
-the evidence and finding model, the failure taxonomy, artifact discovery,
-format parsers (JUnit, HAR), contract validation, and the diff guard.
-
-Standard library only. Knows nothing about any test framework; framework
-specifics live in shared/frameworks/<name>/lib and depend on this package.
-"""
-
-__version__ = "0.1.0"

package/shared/analysis/lib/qa_analysis/branding.py

@@ -1,175 +0,0 @@
-"""Product attribution for human-readable reports.
-
-One renderer, one metadata file, three output formats. Every report the pack
-produces for a human ends with the same footer, and changing it means editing
-`branding.json` — nothing else.
-
-## Why this is code and not a string in each skill
-
-A footer typed by a model is a footer that drifts: the tagline gains a word, the
-URL loses a scheme, one report says "Developed by" and the next says "Built by".
-Rendering it deterministically makes every report byte-identical, and makes a
-change to the branding a one-file edit that CI can verify
-(`scripts/check-branding.mjs` fails if any branding string is hardcoded elsewhere).
-
-## What gets a footer, and what must not
-
-Attribution belongs on documents a person reads. It is noise — or worse, a parsing
-hazard — anywhere else.
-
-| Branded | Not branded |
-| --- | --- |
-| HTML reports | JSON and YAML artifacts (`qa-artifacts/*.json`) |
-| PDF reports | CLI stdout, progress output, `--json` output |
-| Rendered Markdown reports meant for people | Markdown written for machine consumption |
-| Generated documentation | Log files, API responses |
-| Evaluation and audit report renderings | The system under test, and anything in a user's own source tree |
-
-The rule behind the table: **if a program will parse it, it gets no footer.** A
-contract artifact is an interface, and appending prose to an interface breaks it.
-
-## Formats
-
-- `footer_html()` — a `<footer>` element with inline styling (so a standalone
-  report file needs no external stylesheet) and the author's site as a link that
-  opens in a new tab with `rel="noopener noreferrer"`.
-- `footer_markdown()` — a thematic break, the four lines, the site as a link.
-- `footer_text()` — rule-separated plain text for PDF writers and terminals-of-last-resort.
-  A PDF library that supports hyperlinks should link the URL; one that does not
-  renders this as-is, which is why the URL appears in full rather than as anchor text.
-
-Standard library only, like the rest of `qa_analysis`.
-"""
-
-import html
-import json
-import pathlib
-
-_METADATA_PATH = pathlib.Path(__file__).resolve().parent / "branding.json"
-
-# The visual width of the plain-text rules. Wide enough to frame the four lines,
-# narrow enough to survive an 80-column terminal or a PDF margin.
-_RULE_WIDTH = 60
-
-_ALLOWED_SCHEMES = ("https://", "http://")
-
-
-class BrandingError(ValueError):
-    """Raised when the branding metadata is missing or unusable."""
-
-
-def metadata():
-    """The branding metadata, as a dict. Read fresh so a change needs no reinstall."""
-    try:
-        with open(_METADATA_PATH, "r", encoding="utf-8") as handle:
-            data = json.load(handle)
-    except (OSError, json.JSONDecodeError) as exc:
-        raise BrandingError(f"could not read branding metadata at {_METADATA_PATH}: {exc}") from exc
-
-    required = ("projectName", "tagline", "author", "website", "attributionPrefix", "authorPrefix")
-    missing = [key for key in required if not data.get(key)]
-    if missing:
-        raise BrandingError(f"branding metadata is missing: {', '.join(missing)}")
-    if not data["website"].startswith(_ALLOWED_SCHEMES):
-        # A footer is rendered into HTML, so a non-http scheme here would be an
-        # injection vector rather than a typo.
-        raise BrandingError(
-            f"branding website must start with http:// or https://, got {data['website']!r}"
-        )
-    return data
-
-
-def _lines(data):
-    """The four footer lines, in order, as plain strings."""
-    return [
-        f"{data['attributionPrefix']} {data['projectName']}",
-        data["tagline"],
-        f"{data['authorPrefix']} {data['author']}",
-        data["website"],
-    ]
-
-
-def footer_text(width=_RULE_WIDTH):
-    """Rule-separated plain text. Used for PDF and any non-markup rendering."""
-    data = metadata()
-    rule = "-" * width
-    body = "\n".join(line.center(width).rstrip() for line in _lines(data))
-    return f"{rule}\n{body}\n{rule}\n"
-
-
-def footer_markdown():
-    """A thematic break and the four lines, with the site as a link."""
-    data = metadata()
-    return (
-        "---\n\n"
-        f"<sub>{data['attributionPrefix']} **{data['projectName']}** — "
-        f"{data['tagline']}<br>\n"
-        f"{data['authorPrefix']} "
-        f"[{data['author']}]({data['website']})</sub>\n"
-    )
-
-
-def footer_html(class_name="qa-pack-attribution"):
-    """A self-contained `<footer>`: inline styles, muted, centered, small.
-
-    The author's site opens in a new tab. `rel="noopener noreferrer"` is not
-    optional — a report may be opened from anywhere, and a new tab that can reach
-    back into `window.opener` is a real hazard.
-    """
-    data = metadata()
-    site = html.escape(data["website"], quote=True)
-    project = html.escape(data["projectName"])
-    tagline = html.escape(data["tagline"])
-    author = html.escape(data["author"])
-    attribution_prefix = html.escape(data["attributionPrefix"])
-    author_prefix = html.escape(data["authorPrefix"])
-    css_class = html.escape(class_name, quote=True)
-
-    return (
-        f'<footer class="{css_class}" style="margin-top:2.5rem;padding-top:1rem;'
-        'border-top:1px solid rgba(128,128,128,0.25);font-size:0.75rem;line-height:1.6;'
-        'color:#6b7280;text-align:center;font-family:system-ui,-apple-system,'
-        'Segoe UI,Roboto,sans-serif;">\n'
-        f'  <div>{attribution_prefix} <strong>{project}</strong></div>\n'
-        f'  <div>{tagline}</div>\n'
-        f'  <div>{author_prefix} '
-        f'<a href="{site}" target="_blank" rel="noopener noreferrer" '
-        'style="color:inherit;text-decoration:underline;">'
-        f'{author}</a></div>\n'
-        '</footer>\n'
-    )
-
-
-_RENDERERS = {
-    "html": footer_html,
-    "markdown": footer_markdown,
-    "md": footer_markdown,
-    "text": footer_text,
-    "txt": footer_text,
-    "pdf": footer_text,  # what a PDF writer embeds when it cannot render markup
-}
-
-FORMATS = ("html", "markdown", "text")
-
-
-def footer(fmt="text"):
-    """Render the footer in `fmt`. Raises BrandingError on an unknown format."""
-    renderer = _RENDERERS.get(fmt.lower())
-    if renderer is None:
-        raise BrandingError(
-            f"unknown branding format {fmt!r}; expected one of: {', '.join(FORMATS)}"
-        )
-    return renderer()
-
-
-def append_to(document, fmt="markdown"):
-    """Return `document` with the footer appended, idempotently.
-
-    Idempotence matters: a report assembled in stages, or regenerated over its own
-    output, must not accumulate footers.
-    """
-    rendered = footer(fmt)
-    if rendered.strip() and rendered.strip() in document:
-        return document
-    separator = "" if document.endswith("\n") else "\n"
-    return f"{document}{separator}\n{rendered}"

package/shared/analysis/lib/qa_analysis/cli.py

@@ -1,129 +0,0 @@
-"""Unified CLI for the analysis core.
-
-Every analyzer is reachable as a subcommand that writes JSON to stdout, so the
-toolkit is usable from a shell, from CI, and (once bundled) by a skill. Exit
-code 0 on success, 2 on a malformed artifact or bad usage.
-
-Usage:
-  python -m qa_analysis.cli junit <path>
-  python -m qa_analysis.cli har <path> [--slow-ms N]
-  python -m qa_analysis.cli discover [--root DIR] [--path P ...]
-  python -m qa_analysis.cli diff-guard <diff-file>
-  python -m qa_analysis.cli redact <file>
-  python -m qa_analysis.cli validate <instance.json> <schema.json>
-  python -m qa_analysis.cli classify "<error message>" [--http-status N]
-  python -m qa_analysis.cli context [--root DIR] [--path .qa/context.md]
-  python -m qa_analysis.cli branding [--format html|markdown|text]
-"""
-
-import argparse
-import json
-import pathlib
-import sys
-
-from . import junit, har, discovery, diff_guard, redaction, contracts, taxonomy
-from . import branding as branding_module
-from . import context as context_module
-from .context import MalformedContext
-from .junit import MalformedArtifact
-
-_SCHEMA_DIR_CANDIDATES = (
-    # Repository layout: shared/analysis/lib/qa_analysis -> shared/analysis/schemas
-    pathlib.Path(__file__).resolve().parents[2] / "schemas",
-    # Bundled layout: package data travels with the package.
-    pathlib.Path(__file__).resolve().parent / "schemas",
-)
-
-
-def _context_schema():
-    """The context contract, in whichever layout this package is running from."""
-    for base in _SCHEMA_DIR_CANDIDATES:
-        candidate = base / "context.schema.json"
-        if candidate.is_file():
-            return contracts.load_schema(candidate)
-    return None
-
-
-def _emit(obj):
-    json.dump(obj, sys.stdout, indent=2, sort_keys=True)
-    sys.stdout.write("\n")
-
-
-def main(argv=None):
-    parser = argparse.ArgumentParser(prog="qa-analysis", description="Deterministic QA analysis toolkit")
-    sub = parser.add_subparsers(dest="command", required=True)
-
-    p = sub.add_parser("junit"); p.add_argument("path")
-    p = sub.add_parser("har"); p.add_argument("path"); p.add_argument("--slow-ms", type=int, default=1000)
-    p = sub.add_parser("discover"); p.add_argument("--root", default="."); p.add_argument("--path", action="append", default=[])
-    p = sub.add_parser("diff-guard"); p.add_argument("path")
-    p = sub.add_parser("redact"); p.add_argument("path")
-    p = sub.add_parser("validate"); p.add_argument("instance"); p.add_argument("schema")
-    p = sub.add_parser("classify"); p.add_argument("message"); p.add_argument("--http-status", type=int, default=None)
-    p = sub.add_parser("context"); p.add_argument("--root", default="."); p.add_argument("--path", default=None)
-    p = sub.add_parser("branding")
-    p.add_argument("--format", default="text", choices=list(branding_module.FORMATS) + ["pdf", "md", "txt"])
-    p.add_argument("--metadata", action="store_true", help="emit the branding metadata as JSON instead")
-
-    args = parser.parse_args(argv)
-
-    try:
-        if args.command == "junit":
-            _emit(junit.parse_junit(args.path))
-        elif args.command == "har":
-            _emit(har.parse_har(args.path, slow_ms=args.slow_ms))
-        elif args.command == "discover":
-            result = discovery.discover(root=args.root, explicit=args.path or None)
-            _emit({k: [a.to_dict() if hasattr(a, "to_dict") else a for a in v] for k, v in result.items()})
-        elif args.command == "diff-guard":
-            with open(args.path, "r", encoding="utf-8") as handle:
-                issues = diff_guard.check_diff(handle.read())
-            _emit({"issues": issues, "safe": not any(i["severity"] == "high" for i in issues)})
-        elif args.command == "redact":
-            with open(args.path, "r", encoding="utf-8") as handle:
-                sys.stdout.write(redaction.redact_text(handle.read()))
-        elif args.command == "validate":
-            with open(args.instance, "r", encoding="utf-8") as handle:
-                instance = json.load(handle)
-            ok, errors = contracts.validate(instance, contracts.load_schema(args.schema))
-            _emit({"valid": ok, "errors": errors})
-            return 0 if ok else 1
-        elif args.command == "classify":
-            classification, confidence, reason = taxonomy.classify(args.message, http_status=args.http_status)
-            _emit({"classification": classification, "confidence": confidence, "reason": reason})
-        elif args.command == "context":
-            path = args.path or str(pathlib.Path(args.root) / ".qa" / "context.md")
-            schema = _context_schema()
-            parsed = context_module.parse_file(path, schema=schema)
-            _emit({
-                "path": path,
-                "context": parsed["context"],
-                "valid": parsed["valid"],
-                "errors": parsed["errors"],
-                "schemaChecked": schema is not None,
-            })
-            return 0 if parsed["valid"] else 1
-        elif args.command == "branding":
-            # Written to stdout verbatim, not as JSON: the caller pastes this into
-            # a rendered report, so it must be the exact bytes to embed.
-            if args.metadata:
-                _emit(branding_module.metadata())
-            else:
-                sys.stdout.write(branding_module.footer(args.format))
-    except branding_module.BrandingError as exc:
-        _emit({"error": "branding-error", "detail": str(exc)})
-        return 2
-    except MalformedContext as exc:
-        _emit({"error": "malformed-context", "detail": str(exc)})
-        return 2
-    except MalformedArtifact as exc:
-        _emit({"error": "malformed-artifact", "detail": str(exc)})
-        return 2
-    except (OSError, json.JSONDecodeError) as exc:
-        _emit({"error": "io-error", "detail": str(exc)})
-        return 2
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())