qa-engineer 0.10.0 → 0.12.0

package/packages/engine/bin/qa-engine.mjs

@@ -25,6 +25,7 @@ import path from 'node:path';
 
 import * as junit from '../lib/analysis/junit.mjs';
 import * as har from '../lib/analysis/har.mjs';
+import * as network from '../lib/analysis/network.mjs';
 import * as discovery from '../lib/analysis/discovery.mjs';
 import * as diffGuard from '../lib/analysis/diff-guard.mjs';
 import * as redaction from '../lib/analysis/redaction.mjs';
@@ -33,6 +34,11 @@ import * as taxonomy from '../lib/analysis/taxonomy.mjs';
 import * as contextModule from '../lib/analysis/context.mjs';
 import * as branding from '../lib/analysis/branding.mjs';
 import * as reportHtml from '../lib/analysis/report-html.mjs';
+import * as markdownExport from '../lib/report/export/markdown.mjs';
+import * as machineExport from '../lib/report/export/machine.mjs';
+import * as bundleExport from '../lib/report/export/bundle.mjs';
+import * as artifacts from '../lib/artifacts/manager.mjs';
+import { SchemaError } from '../lib/report/core/normalize.mjs';
 import * as diagnostics from '../lib/diagnostics/engine.mjs';
 import {
   InternalContractError, validateAnalysisResult, validateExecutionResultMin, validateDiagnosis,
@@ -43,13 +49,16 @@ import * as junitFrameworks from '../lib/frameworks/junit-frameworks.mjs';
 const USAGE = `usage: qa-engine <tool> <subcommand> [args]
 
   analysis     parse artifacts, classify errors, validate contracts, diff-guard,
-               read .qa/context.md, render an HTML report, print the footer
+              read .qa/context.md, render a report, print the footer
+  artifacts    check that the evidence a result points at is really on disk
   diagnostics  root cause, timeline, priority, repair plans, release readiness
   playwright   normalize a Playwright report or summarize a trace
 
 analysis subcommands
   junit <report.xml>                        normalized {tests, executed}
   har <file.har> [--slow-ms N]              redacted network summary
+  network <file.har> [--slow-ms N]          the report's network block: totals,
+            [--large-bytes N]               per-endpoint timings, and an issue flag
   discover [--root DIR] [--path P ...]      artifacts found, by state
   diff-guard <diff-file>                    {issues, safe} — safe:false blocks a change
   redact <file>                             the file's text with secrets masked
@@ -57,8 +66,25 @@ analysis subcommands
   classify "<message>" [--http-status N]    {classification, confidence, reason}
   context [--root DIR] [--path P]           parsed, schema-checked project context
   report-html <result.json> [--out FILE]    a self-contained HTML report
+            [--embed] [--mode M]           --embed inlines images as data URIs
+                                            M: full executive developer artifact
+                                            (artifact = body only, for an embedding host)
+  report-export <result.json> --format F    F: html markdown sarif junit csv json bundle
+            [--out FILE] [--embed]
+            [--mode M]
+  report-bundle <result.json> [--out DIR]   a portable folder — index.html + assets/ —
+            [--zip] [--zip-out FILE]        with every link verified to resolve inside
+            [--mode M] [--force]            it. The canonical local output.
+  report-schema [--out FILE]                the canonical producer-neutral contract
+  report-versions                           schema / theme / renderer versions in force
   branding [--format html|markdown|text]    the exact footer bytes for a report
 
+artifacts subcommands
+  verify <result.json> [--base-dir D]       {ok, stats, missing}; exit 1 when a file
+            [--out-dir D]                  a finding points at is not there
+  scan <directory> [--root D]               every file found, with size and type
+  hash <file>                               the file's SHA-256
+
 diagnostics subcommands
   diagnose --execution-result P [--analysis-result P]
   plan-repairs --diagnosis P
@@ -71,7 +97,11 @@ playwright subcommands
 
 examples
   qa-engine analysis junit test-results/results.xml
-  qa-engine analysis report-html qa-artifacts/explore-result.json --out report.html
+  qa-engine artifacts verify qa-artifacts/explore-R/explore-result.json
+  qa-engine analysis report-html qa-artifacts/explore-R/explore-result.json \\
+    --out qa-artifacts/explore-R/explore-report.html
+  qa-engine analysis report-export qa-artifacts/explore-R/explore-result.json \\
+    --format sarif --out qa-artifacts/explore-R/findings.sarif
   qa-engine diagnostics report --execution-result qa-artifacts/run.json
 `;
 
@@ -99,8 +129,15 @@ function readJson(file) {
   return JSON.parse(fs.readFileSync(file, 'utf8'));
 }
 
-/** Flags, parsed the way the Python argparse CLIs accepted them. */
-function parseFlags(argv, { repeatable = [] } = {}) {
+/**
+ * Flags, parsed the way the Python argparse CLIs accepted them.
+ *
+ * `boolean` names matter: without them a switch consumes the token after it, so
+ * `--embed --out report.html` set `embed` to `"--out"` and left the output path as a
+ * stray positional. The report then went to stdout and the flag did nothing — a
+ * failure that looks like the feature is broken rather than the parser.
+ */
+function parseFlags(argv, { repeatable = [], boolean = [] } = {}) {
   const flags = {};
   const positional = [];
   for (let index = 0; index < argv.length; index += 1) {
@@ -111,6 +148,10 @@ function parseFlags(argv, { repeatable = [] } = {}) {
     }
     const [name, inline] = token.slice(2).split('=', 2);
     const camel = name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    if (boolean.includes(camel)) {
+      flags[camel] = inline === undefined ? true : inline !== 'false' && inline !== '0';
+      continue;
+    }
     const value = inline !== undefined ? inline : argv[++index];
     if (repeatable.includes(camel)) {
       flags[camel] = [...(flags[camel] ?? []), value];
@@ -126,9 +167,24 @@ function parseFlags(argv, { repeatable = [] } = {}) {
 // everywhere handed `context` an array and it failed on "path must be a string".
 const REPEATABLE = { discover: ['path'] };
 
+// Switches that take no value. Declared per subcommand so `--embed --out f.html` reads
+// as two flags rather than one flag whose value is the word "--out".
+const BOOLEAN = {
+  'report-html': ['embed'],
+  'report-export': ['embed'],
+  // `--zip` is a switch and `--zip-out` carries the path. One flag doing both would
+  // need a third parser mode that guesses from the next token, and a guess here writes
+  // the archive to a filename taken from an unrelated flag.
+  'report-bundle': ['force', 'zip', 'markdown'],
+  branding: ['metadata'],
+};
+
 function analysis(argv) {
   const [subcommand, ...rest] = argv;
-  const { flags, positional } = parseFlags(rest, { repeatable: REPEATABLE[subcommand] ?? [] });
+  const { flags, positional } = parseFlags(rest, {
+    repeatable: REPEATABLE[subcommand] ?? [],
+    boolean: BOOLEAN[subcommand] ?? [],
+  });
 
   switch (subcommand) {
     case 'junit':
@@ -141,6 +197,18 @@ function analysis(argv) {
       emit(har.parseHar(positional[0], { slowMs: Number(flags.slowMs ?? 1000) }));
       return 0;
 
+    case 'network': {
+      // The report contract's `network` block, ready to paste into a result and
+      // validate. `har` gives the raw entries; this gives the counted, flagged,
+      // report-shaped answer, so no skill has to count requests by eye.
+      requirePositional(positional, 1, 'network <file.har>');
+      const options = {};
+      if (flags.slowMs !== undefined) options.slowMs = Number(flags.slowMs);
+      if (flags.largeBytes !== undefined) options.largeBytes = Number(flags.largeBytes);
+      emit(network.analyzeHar(positional[0], options));
+      return 0;
+    }
+
     case 'discover':
       emit(discovery.discover({ root: flags.root ?? '.', explicit: flags.path ?? null }));
       return 0;
@@ -187,9 +255,22 @@ function analysis(argv) {
 
     case 'report-html': {
       requirePositional(positional, 1, 'report-html <result.json>');
-      const document = reportHtml.renderFile(positional[0], { title: flags.title ?? null });
-      if (flags.out) {
-        fs.writeFileSync(flags.out, document);
+      // The output path is handed to the renderer, not just used to write the file:
+      // every evidence href is computed relative to it. Rendering to stdout falls back
+      // to the result's own directory, which is where a report normally lands.
+      const outPath = flags.out ? path.resolve(flags.out) : null;
+      const document = reportHtml.renderFile(positional[0], {
+        title: flags.title ?? null,
+        outPath,
+        // --embed inlines every image as a data URI, producing one file that survives
+        // being forwarded without its screenshots folder.
+        embed: flags.embed === true,
+        // --mode picks the audience: full, executive, developer, or artifact (the
+        // body-only rendering a host page supplies its own <head> for).
+        mode: flags.mode ?? 'full',
+      });
+      if (outPath) {
+        fs.writeFileSync(outPath, document);
         emit({ written: flags.out, bytes: document.length });
       } else {
         process.stdout.write(document);
@@ -197,6 +278,52 @@ function analysis(argv) {
       return 0;
     }
 
+    case 'report-export': {
+      requirePositional(positional, 1, 'report-export <result.json> --format <format>');
+      return reportExport(positional[0], flags);
+    }
+
+    case 'report-bundle': {
+      requirePositional(positional, 1, 'report-bundle <result.json> [--out DIR]');
+      const file = path.resolve(positional[0]);
+      const summary = bundleExport.writeBundle(readJson(file), {
+        resultPath: file,
+        outDir: flags.out ? path.resolve(flags.out) : undefined,
+        mode: flags.mode ?? 'full',
+        zip: flags.zipOut ?? flags.zip === true,
+        markdown: flags.markdown !== false,
+        force: flags.force === true,
+      });
+      emit(summary);
+      return 0;
+    }
+
+    case 'report-schema': {
+      // Any agent can fetch the canonical contract and validate against it before it
+      // hands anything over. Emitting it from the engine rather than documenting it in
+      // prose is what keeps the schema an agent writes to and the schema the renderer
+      // reads the same object.
+      const schema = readJson(
+        new URL('../lib/report/schemas/qa-report.schema.json', import.meta.url).pathname,
+      );
+      if (flags.out) {
+        fs.writeFileSync(flags.out, `${JSON.stringify(schema, null, 2)}\n`);
+        emit({ written: flags.out });
+      } else {
+        process.stdout.write(`${JSON.stringify(schema, null, 2)}\n`);
+      }
+      return 0;
+    }
+
+    case 'report-versions':
+      // What this renderer is: schema it reads, theme it paints, code that did it.
+      emit({
+        ...reportHtml.versionStamp(),
+        supportedContracts: reportHtml.supportedContracts(),
+        supportedModes: reportHtml.supportedModes(),
+      });
+      return 0;
+
     case 'branding':
       // Written to stdout verbatim, not as JSON: the caller embeds these exact
       // bytes in a rendered report.
@@ -209,6 +336,97 @@ function analysis(argv) {
   }
 }
 
+// Every non-HTML rendering of a validated result. Text formats go to stdout or a file
+// verbatim; JSON formats are emitted through the same sorted serializer as everything
+// else, so a diff of two runs is a diff of the findings and not of key ordering.
+const EXPORT_FORMATS = {
+  html: { text: true, render: (result, options) => reportHtml.render(result, options) },
+  markdown: { text: true, render: (result, options) => markdownExport.renderMarkdown(result, options) },
+  md: { text: true, render: (result, options) => markdownExport.renderMarkdown(result, options) },
+  sarif: { text: false, render: (result, options) => machineExport.renderSarif(result, options) },
+  junit: { text: true, render: (result, options) => machineExport.renderJUnit(result, options) },
+  csv: { text: true, render: (result, options) => machineExport.renderCsv(result, options) },
+  json: { text: false, render: (result) => result },
+  bundle: { text: false, render: (result, options) => machineExport.bundleManifest(result, options) },
+};
+
+function reportExport(file, flags) {
+  const format = String(flags.format ?? 'markdown').toLowerCase();
+  const exporter = EXPORT_FORMATS[format];
+  if (!exporter) {
+    throw new UsageError(
+      `unknown export format '${format}'; expected one of: ${Object.keys(EXPORT_FORMATS).sort().join(', ')}`,
+    );
+  }
+
+  const result = readJson(file);
+  const outPath = flags.out ? path.resolve(flags.out) : null;
+  const rendered = exporter.render(result, {
+    resultPath: path.resolve(file),
+    outPath,
+    embed: flags.embed === true,
+    mode: flags.mode ?? 'full',
+  });
+  const body = exporter.text ? rendered : `${JSON.stringify(rendered, sortedReplacer(), 2)}\n`;
+
+  if (outPath) {
+    fs.writeFileSync(outPath, body);
+    emit({ written: flags.out, format, bytes: body.length });
+  } else {
+    process.stdout.write(body);
+  }
+  return 0;
+}
+
+/**
+ * The artifact tool group: does the evidence this result points at actually exist?
+ *
+ * Separate from `analysis` because it answers a question about the *filesystem* rather
+ * than about a document, and because a skill runs it at a different moment — after
+ * capture and before rendering, as the gate that stops a report full of broken images
+ * from being written at all.
+ */
+function artifactsCommand(argv) {
+  const [subcommand, ...rest] = argv;
+  const { flags, positional } = parseFlags(rest);
+
+  switch (subcommand) {
+    case 'verify': {
+      requirePositional(positional, 1, 'verify <result.json>');
+      const file = path.resolve(positional[0]);
+      const report = artifacts.verify(readJson(file), {
+        baseDir: flags.baseDir ? path.resolve(flags.baseDir) : path.dirname(file),
+        outDir: flags.outDir ? path.resolve(flags.outDir) : undefined,
+      });
+      emit(report);
+      // Exit 1, matching `validate`: the document was readable and did not hold up.
+      return report.ok ? 0 : 1;
+    }
+
+    case 'scan': {
+      requirePositional(positional, 1, 'scan <directory>');
+      const found = artifacts.scan(positional[0], { root: flags.root ?? positional[0] });
+      emit({
+        directory: positional[0],
+        count: found.length,
+        empty: found.filter((entry) => entry.empty).length,
+        bytes: found.reduce((sum, entry) => sum + entry.bytes, 0),
+        files: found,
+      });
+      return 0;
+    }
+
+    case 'hash': {
+      requirePositional(positional, 1, 'hash <file>');
+      emit({ path: positional[0], sha256: artifacts.hashFile(path.resolve(positional[0])) });
+      return 0;
+    }
+
+    default:
+      throw new UsageError(`unknown artifacts subcommand: ${subcommand ?? '(none)'}`);
+  }
+}
+
 function diagnosticsCommand(argv) {
   const [subcommand, ...rest] = argv;
   const { flags } = parseFlags(rest);
@@ -306,6 +524,7 @@ export function main(argv = process.argv.slice(2)) {
   const [tool, ...rest] = argv;
   try {
     if (tool === 'analysis') return analysis(rest);
+    if (tool === 'artifacts') return artifactsCommand(rest);
     if (tool === 'diagnostics') return diagnosticsCommand(rest);
     if (tool === 'playwright') return playwrightCommand(rest);
     process.stderr.write(USAGE);
@@ -314,6 +533,11 @@ export function main(argv = process.argv.slice(2)) {
     if (error instanceof junit.MalformedArtifact) return fail('malformed-artifact', error.message);
     if (error instanceof contextModule.MalformedContext) return fail('malformed-context', error.message);
     if (error instanceof reportHtml.ReportError) return fail('report-error', error.message);
+    // The non-HTML exporters go through the normalizer directly, so its refusals
+    // surface here rather than wrapped as a ReportError.
+    if (error instanceof SchemaError) return fail('schema-error', error.message);
+    if (error instanceof bundleExport.BundleError) return fail('bundle-error', error.message);
+    if (error instanceof artifacts.ArtifactError) return fail('artifact-error', error.message);
     if (error instanceof branding.BrandingError) return fail('branding-error', error.message);
     if (error instanceof InternalContractError) return fail('invalid-payload', error.message);
     if (error instanceof UsageError) return fail('usage-error', error.message);

package/packages/engine/lib/analysis/har.mjs

@@ -36,6 +36,16 @@ export function parseHarData(data, { slowMs = 1000, label = '<input>' } = {}) {
       durationMs: toMillis(item?.time, label),
       requestHeaders: redactHeaders(request.headers ?? []),
       responseHeaders: redactHeaders(response.headers ?? []),
+      // Three facts a report needs that a summary of failures cannot supply: how big
+      // the response was, when it started relative to the others, and whether the
+      // server said anything about caching. All three are read straight from the HAR
+      // — none is inferred — and all three are absent from many HARs, which is why
+      // each has an explicit "unknown" rather than a plausible zero.
+      bytes: bodyBytes(response),
+      startedAt: typeof item.startedDateTime === 'string' ? item.startedDateTime : null,
+      cacheControl: headerValue(response.headers, 'cache-control'),
+      etag: headerValue(response.headers, 'etag'),
+      resourceType: typeof item._resourceType === 'string' ? item._resourceType : null,
     };
   });
 
@@ -58,6 +68,30 @@ export function parseHar(path, { slowMs = 1000 } = {}) {
   return parseHarData(data, { slowMs, label: path });
 }
 
+/**
+ * Response body size in bytes, or null when the HAR does not say.
+ *
+ * `content.size` is the decoded size and `bodySize` the bytes on the wire; either is
+ * `-1` when the producer did not record it. Null rather than 0, because "we do not
+ * know how big this was" and "this response was empty" are different findings and a
+ * report that conflates them invents a fact.
+ */
+function bodyBytes(response) {
+  for (const candidate of [response?.content?.size, response?.bodySize]) {
+    const number = Number(candidate);
+    if (Number.isFinite(number) && number >= 0) return Math.trunc(number);
+  }
+  return null;
+}
+
+/** A header's value, case-insensitively, or null. */
+function headerValue(headers, name) {
+  if (!Array.isArray(headers)) return null;
+  const wanted = name.toLowerCase();
+  const found = headers.find((header) => String(header?.name ?? '').toLowerCase() === wanted);
+  return found ? String(found.value ?? '') : null;
+}
+
 /** A status that is absent or unreadable is 0 — "no response", which is a failure. */
 function toInt(value) {
   const number = Number(value);

package/packages/engine/lib/analysis/network.mjs

@@ -0,0 +1,237 @@
+// Turning a HAR into the report's `network` block.
+//
+// ## Why this exists
+//
+// `qa-explore` claimed an API dimension and backed it with forty-eight lines of prose
+// telling the model what to look for. The model then counted requests by eye, decided
+// which were slow, and judged which were duplicates — three things a model is bad at
+// and a parser is perfect at. The pack's founding rule is that deterministic code owns
+// facts and the model owns explanation; for this dimension the model owned both.
+//
+// So the counting moves here. What comes out is the `network` block of the report
+// contract, ready to validate: totals, per-endpoint timings and sizes, and a flag on
+// each endpoint saying what is wrong with it. The model's job becomes what it is
+// actually good at — deciding whether a duplicate request *matters* to this product,
+// and writing the finding.
+//
+// ## Facts, and inferences that are labelled as such
+//
+// Two different kinds of claim come out of a HAR, and conflating them is how a report
+// starts asserting things it cannot support:
+//
+//   fact       count, status, duration, byte size, start offset, header presence.
+//              Read directly. If the HAR does not record it, the answer is null, never
+//              a plausible zero.
+//   inference  duplicate, polling, n+1, uncached. Derived by a stated rule, over a
+//              stated threshold, and every one is reported with the evidence that
+//              triggered it so a reader can disagree.
+//
+// Nothing here decides severity. A duplicated analytics beacon and a duplicated payment
+// request are the same shape in a HAR and wildly different findings, and only something
+// that understands the product can tell them apart.
+
+import { parseHar, parseHarData } from './har.mjs';
+
+/** Defaults, all overridable, all reported back in the output so a reader sees them. */
+export const DEFAULTS = Object.freeze({
+  slowMs: 1000,
+  // 512 KB. Below this a payload is rarely the thing worth reporting; above it, on a
+  // mobile connection, it is.
+  largeBytes: 512 * 1024,
+  // Three or more identical requests at a regular cadence reads as polling rather than
+  // as a burst of duplicates. Two is a double-submit; ten evenly spaced is a timer.
+  pollingMinimum: 3,
+  // Requests to the same path shape within this window look like one screen's worth of
+  // work, which is what makes an N+1 visible rather than just "a busy session".
+  nPlusOneWindowMs: 2000,
+  nPlusOneMinimum: 4,
+});
+
+/** The path portion of a URL, without query or fragment. */
+function pathOf(url) {
+  const text = String(url ?? '');
+  const withoutScheme = text.includes('://') ? text.slice(text.indexOf('://') + 3) : text;
+  const slash = withoutScheme.indexOf('/');
+  const rest = slash === -1 ? '/' : withoutScheme.slice(slash);
+  return rest.split('?')[0].split('#')[0] || '/';
+}
+
+/**
+ * A path with its identifier segments replaced, so `/users/41` and `/users/42` collapse.
+ *
+ * This is what makes an N+1 detectable. The rule is deliberately narrow — numeric
+ * segments, UUIDs, and long hex strings — because a looser one collapses genuinely
+ * different endpoints and reports an N+1 that is not there.
+ */
+export function templatePath(url) {
+  return pathOf(url)
+    .split('/')
+    .map((segment) => {
+      if (/^\d+$/.test(segment)) return ':id';
+      if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(segment)) return ':uuid';
+      if (/^[0-9a-f]{16,}$/i.test(segment)) return ':hash';
+      return segment;
+    })
+    .join('/');
+}
+
+/** Milliseconds from the first request, or null when the HAR has no timestamps. */
+function startOffsets(entries) {
+  const times = entries.map((entry) => {
+    const parsed = entry.startedAt ? Date.parse(entry.startedAt) : Number.NaN;
+    return Number.isFinite(parsed) ? parsed : null;
+  });
+  const known = times.filter((value) => value !== null);
+  if (known.length === 0) return times.map(() => null);
+  const origin = Math.min(...known);
+  return times.map((value) => (value === null ? null : value - origin));
+}
+
+/**
+ * Is this response cacheable and uncached?
+ *
+ * Only asked of static assets, and only when the server said nothing at all. A 200 for
+ * a script with neither `Cache-Control` nor `ETag` is a real finding; the same absence
+ * on a JSON API response usually is not, because that response is often meant to be
+ * fresh every time. Guessing on the second produces noise that trains a reader to
+ * ignore the whole section.
+ */
+function looksUncached(entry) {
+  if (entry.status !== 200) return false;
+  if (entry.cacheControl || entry.etag) return false;
+  const path = pathOf(entry.url).toLowerCase();
+  return /\.(js|mjs|css|png|jpe?g|gif|webp|avif|svg|woff2?|ttf|eot|ico)$/.test(path);
+}
+
+/** Evenly spaced repeats read as a timer rather than as a burst. */
+function looksLikePolling(offsets, minimum) {
+  const known = offsets.filter((value) => value !== null).sort((a, b) => a - b);
+  if (known.length < minimum) return false;
+  const gaps = known.slice(1).map((value, index) => value - known[index]);
+  if (gaps.length < 2) return false;
+  const mean = gaps.reduce((sum, gap) => sum + gap, 0) / gaps.length;
+  if (mean < 250) return false; // a burst, not a poll
+  // Within 35% of the mean gap, every time: a scheduler, not a user.
+  return gaps.every((gap) => Math.abs(gap - mean) <= mean * 0.35);
+}
+
+/**
+ * Build the contract's `network` block from parsed HAR entries.
+ *
+ * Exported separately from the file-reading path so a caller that already has entries —
+ * a browser adapter capturing them live, say — can use the same analysis without
+ * writing a HAR to disk first.
+ */
+export function analyzeEntries(entries, options = {}) {
+  const config = { ...DEFAULTS, ...options };
+  const offsets = startOffsets(entries);
+  const enriched = entries.map((entry, index) => ({ ...entry, startedMs: offsets[index] }));
+
+  // Group by what actually identifies a call: the method and the full URL. Two GETs of
+  // the same path with different query strings are different requests, and collapsing
+  // them would report a duplicate that is not one.
+  const groups = new Map();
+  for (const entry of enriched) {
+    const key = `${entry.method} ${entry.url}`;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(entry);
+  }
+
+  // N+1: many calls to one path *shape* inside a short window.
+  const byTemplate = new Map();
+  for (const entry of enriched) {
+    const key = `${entry.method} ${templatePath(entry.url)}`;
+    if (!byTemplate.has(key)) byTemplate.set(key, []);
+    byTemplate.get(key).push(entry);
+  }
+  const nPlusOne = new Set();
+  for (const [key, group] of byTemplate) {
+    if (group.length < config.nPlusOneMinimum) continue;
+    // Distinct URLs, or it is a duplicate rather than an N+1.
+    if (new Set(group.map((entry) => entry.url)).size < config.nPlusOneMinimum) continue;
+    const known = group.map((entry) => entry.startedMs).filter((value) => value !== null);
+    if (known.length > 1 && Math.max(...known) - Math.min(...known) > config.nPlusOneWindowMs) continue;
+    nPlusOne.add(key);
+  }
+
+  const endpoints = [];
+  for (const [, group] of groups) {
+    const first = group[0];
+    const durations = group.map((entry) => entry.durationMs).filter((value) => Number.isFinite(value));
+    const sizes = group.map((entry) => entry.bytes).filter((value) => value !== null);
+    const worstStatus = group.reduce(
+      (worst, entry) => (statusRank(entry.status) > statusRank(worst) ? entry.status : worst),
+      first.status,
+    );
+    const slowest = durations.length > 0 ? Math.max(...durations) : 0;
+    const bytes = sizes.length > 0 ? Math.max(...sizes) : null;
+    const templateKey = `${first.method} ${templatePath(first.url)}`;
+
+    // One flag per endpoint, worst first: a failing request that is also slow is
+    // reported as failing, because that is what the reader must act on.
+    let issue;
+    if (worstStatus === 0 || worstStatus >= 400) issue = 'failed';
+    else if (slowest >= config.slowMs) issue = 'slow';
+    else if (looksLikePolling(group.map((entry) => entry.startedMs), config.pollingMinimum)) issue = 'polling';
+    else if (group.length > 1) issue = 'duplicate';
+    else if (nPlusOne.has(templateKey)) issue = 'n-plus-one';
+    else if (bytes !== null && bytes >= config.largeBytes) issue = 'large-payload';
+    else if (looksUncached(first)) issue = 'uncached';
+
+    endpoints.push({
+      method: first.method,
+      url: first.url,
+      ...(Number.isFinite(worstStatus) ? { status: worstStatus } : {}),
+      durationMs: slowest,
+      ...(bytes !== null ? { bytes } : {}),
+      count: group.length,
+      ...(first.startedMs !== null ? { startedMs: first.startedMs } : {}),
+      ...(issue ? { issue } : {}),
+    });
+  }
+
+  // Worst first, then slowest: the order a reader wants without sorting anything.
+  endpoints.sort(
+    (a, b) => issueRank(a.issue) - issueRank(b.issue) || (b.durationMs ?? 0) - (a.durationMs ?? 0),
+  );
+
+  const totalBytes = enriched.reduce((sum, entry) => sum + (entry.bytes ?? 0), 0);
+  const anySizes = enriched.some((entry) => entry.bytes !== null);
+
+  return {
+    totalRequests: enriched.length,
+    failedRequests: enriched.filter((entry) => entry.status === 0 || entry.status >= 400).length,
+    slowRequests: enriched.filter((entry) => entry.durationMs >= config.slowMs).length,
+    // Requests beyond the first for each identical call — the count of *wasted* calls,
+    // not the count of endpoints that were repeated.
+    duplicateRequests: [...groups.values()].reduce((sum, group) => sum + (group.length - 1), 0),
+    ...(anySizes ? { totalBytes } : {}),
+    slowThresholdMs: config.slowMs,
+    endpoints,
+  };
+}
+
+function statusRank(status) {
+  if (status === 0) return 3;
+  if (status >= 500) return 2;
+  if (status >= 400) return 1;
+  return 0;
+}
+
+const ISSUE_ORDER = ['failed', 'slow', 'n-plus-one', 'duplicate', 'polling', 'large-payload', 'uncached'];
+function issueRank(issue) {
+  const index = ISSUE_ORDER.indexOf(issue);
+  return index === -1 ? ISSUE_ORDER.length : index;
+}
+
+/** Analyze a HAR file on disk. Returns the contract's `network` block. */
+export function analyzeHar(path, options = {}) {
+  const parsed = parseHar(path, { slowMs: options.slowMs ?? DEFAULTS.slowMs });
+  return analyzeEntries(parsed.entries, options);
+}
+
+/** Analyze already-parsed HAR JSON, for a caller holding the document in memory. */
+export function analyzeHarData(data, options = {}) {
+  const parsed = parseHarData(data, { slowMs: options.slowMs ?? DEFAULTS.slowMs });
+  return analyzeEntries(parsed.entries, options);
+}