@sungen/driver-ui 3.2.35 → 3.3.0-alpha.10

package/src/trace-identity/trace-run-record-reporter.ts

@@ -0,0 +1,131 @@
+/**
+ * Playwright reporter that records sungen's own RUN RECORD for trace conformance (DOS-14.6, G5).
+ *
+ * A Playwright trace carries no run id and no hash of the code that produced it, so a good trace of
+ * another test — or of the same test before the code was weakened — could be swapped in. This
+ * reporter writes, next to the traces it vouches for (`<outputDir>/sungen-run-record[.shard-i-of-n].json`):
+ *
+ *   runId        SUNGEN_RUN_ID when set (one id across CI shards), else a fresh UUID
+ *   specs        sha256 of every test file at run START (the code that ran)
+ *   contract     sha256 of every `.feature` and `contracts.lock.yaml` under `qa/` at run START (schema 2,
+ *                #967): the contract the run saw. A trace proves a contract only while those bytes still
+ *                hold — compared by content, so a touch, a checkout or a fresh clone stales nothing
+ *   attempts     per test attempt: testId, retry, status, window, and the sha256 of its trace.zip
+ *   report       where the JSON reporter wrote its report — traces are mapped THROUGH that report
+ *                (merge-reports renames trace files; their content, and so the sha256, stays)
+ *
+ * The outputDir is wiped at the start of every Playwright run, so a record and its traces always
+ * come from the same run. Enable it for free / impl:code tests together with `trace: 'on'`, in a
+ * config with its OWN outputDir — the compiled suite clears `test-results/` on every run (#941):
+ *
+ *   outputDir: 'test-results-free',
+ *   reporter: [['json', { outputFile: 'test-results-free/results.json' }],
+ *              ['@sungen/driver-ui/dist/trace-identity/trace-run-record-reporter.js']],
+ *   (the compiled file — Playwright does not transpile TypeScript inside node_modules; `prepack` builds it)
+ *   use: { trace: 'on' },
+ */
+import type { FullConfig, Reporter, Suite, TestCase, TestResult } from '@playwright/test/reporter';
+import { createHash, randomUUID } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+interface AttemptRecord {
+  testId: string; file: string; title: string; retry: number; status: string;
+  startTime: string; duration: number; trace: { sha256: string } | null;
+}
+
+const sha256File = (file: string): string | null => {
+  try { return createHash('sha256').update(fs.readFileSync(file)).digest('hex'); } catch { return null; }
+};
+const posix = (p: string): string => p.split(path.sep).join('/');
+const isContractFile = (name: string): boolean => name.endsWith('.feature') || name === 'contracts.lock.yaml';
+
+/**
+ * sha256 of every contract file under `<root>/qa` — each `*.feature` and `contracts.lock.yaml` — keyed
+ * by its posix path from `root`, sorted. Dot-directories, node_modules and symlinks are not followed.
+ */
+export function contractContent(root: string): Record<string, string> {
+  const found: Array<[string, string]> = [];
+  const walk = (dir: string): void => {
+    let entries: fs.Dirent[];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) { if (!e.name.startsWith('.') && e.name !== 'node_modules') walk(full); continue; }
+      const sha = e.isFile() && isContractFile(e.name) ? sha256File(full) : null;
+      if (sha) found.push([posix(path.relative(root, full)), sha]);
+    }
+  };
+  walk(path.join(root, 'qa'));
+  return Object.fromEntries(found.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+
+class TraceRunRecordReporter implements Reporter {
+  private config?: FullConfig;
+  private root = process.cwd();
+  private runId = process.env.SUNGEN_RUN_ID || randomUUID();
+  private startedAt = new Date().toISOString();
+  private specs: Record<string, string> = {};
+  private contract: Record<string, string> = {};
+  private results: Array<{ test: TestCase; result: TestResult }> = [];
+
+  printsToStdio(): boolean { return false; }
+
+  onBegin(config: FullConfig, suite: Suite): void {
+    this.config = config;
+    if (config.configFile) this.root = path.dirname(config.configFile);
+    this.contract = contractContent(this.root);
+    for (const test of suite.allTests()) {
+      const rel = this.rel(test.location.file);
+      if (this.specs[rel] === undefined) this.specs[rel] = sha256File(test.location.file) ?? '';
+    }
+  }
+
+  onTestEnd(test: TestCase, result: TestResult): void {
+    this.results.push({ test, result });
+  }
+
+  async onEnd(): Promise<void> {
+    if (!this.config) return;
+    const attempts: AttemptRecord[] = this.results.map(({ test, result }) => {
+      const trace = result.attachments.find((a) => a.name === 'trace' && a.path);
+      const sha = trace?.path ? sha256File(trace.path) : null;
+      return {
+        testId: test.id, file: this.rel(test.location.file), title: test.title, retry: result.retry, status: result.status,
+        startTime: result.startTime.toISOString(), duration: result.duration, trace: sha ? { sha256: sha } : null,
+      };
+    });
+    const shard = this.config.shard;
+    const record = {
+      schema: 2, tool: 'sungen-trace-run-record', runId: this.runId, startedAt: this.startedAt,
+      playwrightVersion: this.config.version, shard: shard ? `${shard.current}/${shard.total}` : null,
+      report: this.jsonReportPath(), specs: this.specs, contract: this.contract, attempts,
+    };
+    const outDir = this.config.projects[0]?.outputDir ?? path.join(this.root, 'test-results');
+    const name = shard ? `sungen-run-record.shard-${shard.current}-of-${shard.total}.json` : 'sungen-run-record.json';
+    try {
+      fs.mkdirSync(outDir, { recursive: true });
+      fs.writeFileSync(path.join(outDir, name), JSON.stringify(record, null, 2));
+    } catch (e) {
+      // A missing record makes every free / impl:code test `unproven` — say so instead of hiding it.
+      console.error(`[sungen] could not write the trace run record: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+
+  /** The JSON reporter's output file, as the reporter itself resolves it (option, then env). */
+  private jsonReportPath(): string | null {
+    const json = this.config?.reporter.find(([name]) => name === 'json');
+    const opt = json && typeof (json[1] as { outputFile?: unknown })?.outputFile === 'string' ? (json[1] as { outputFile: string }).outputFile : undefined;
+    const fromEnv = process.env.PLAYWRIGHT_JSON_OUTPUT_FILE
+      ?? (process.env.PLAYWRIGHT_JSON_OUTPUT_NAME ? path.join(process.env.PLAYWRIGHT_JSON_OUTPUT_DIR ?? '', process.env.PLAYWRIGHT_JSON_OUTPUT_NAME) : undefined);
+    const chosen = opt ? path.resolve(this.root, opt) : fromEnv ? path.resolve(process.cwd(), fromEnv) : undefined;
+    return chosen ? this.rel(chosen) : null;
+  }
+
+  private rel(file: string): string {
+    const r = path.relative(this.root, file);
+    return posix(r.startsWith('..') || path.isAbsolute(r) ? path.basename(file) : r);
+  }
+}
+
+export default TraceRunRecordReporter;