@sun-asterisk/sungen 3.3.0-alpha.8 → 3.3.0-alpha.9

package/src/contract/trace/trace-freshness.ts

@@ -0,0 +1,110 @@
+/**
+ * Is a trace newer than the contract it is asked to prove? (DOS-14.6: a trace older than the
+ * `.feature` or the lock is refused.) Judged by CONTENT, never by file time alone (#967): a `touch`,
+ * a checkout or a fresh clone changes no byte, so it stales nothing; an edit after the run always does.
+ *
+ *   schema 2 record   the reporter hashed every `.feature` and `contracts.lock.yaml` under `qa/` when
+ *                     the run started. Each of the unit's contract files must hash NOW to what the run
+ *                     saw: one that changed since, or did not exist yet, is newer than the trace → stale
+ *   schema 1 record   an older reporter recorded no content, so the files are dated against the run's
+ *                     start (the record's `startedAt`): one last written before it is older than the run;
+ *                     one written after it still is when git holds it unchanged and the commit that last
+ *                     changed it is an ancestor of HEAD committed before the run started (its bytes ARE
+ *                     that commit's). Anything else — edited, uncommitted, untracked, committed after the
+ *                     run started, no git, git failed or slow — is stale: fail closed.
+ *
+ * Limit of the schema-1 path: a commit time is what the committer's clock (or GIT_COMMITTER_DATE) said,
+ * so a backdated commit passes the time check — time-based checks cannot see through that. Schema 2
+ * compares content and retires this path: re-running the free tests once with the current reporter is
+ * the remedy.
+ */
+import { execFileSync } from 'child_process';
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { lockPathFor } from '../contracts-lock-file';
+import { contractFeatureFiles } from '../normalize-feature-steps';
+import type { RunRecord } from './trace-run-record';
+
+interface ContractFile { rel: string; sha: string; mtimeMs: number }
+interface LastCommit { sha: string; ms: number }
+/** A unit's contract as it is NOW — its `.feature` files and lock, read once per verdict. */
+export interface UnitContract {
+  projectRoot: string;
+  files: ContractFile[];
+  /** Schema 1 only, asked of git at most once: project path → the last commit that changed each file git holds unchanged. */
+  committed?: Map<string, LastCommit> | null;
+  /** Schema 1 only: commit → is it an ancestor of HEAD (asked once per commit). */
+  ancestors?: Map<string, boolean>;
+}
+
+/** Inside the Claude Code guard too: a slow git leaves a schema-1 trace stale rather than the hook waiting. */
+const GIT_TIMEOUT_MS = 2_000;
+const posix = (p: string): string => p.split(path.sep).join('/');
+
+export function unitContract(projectRoot: string, unit: { name: string; dir: string }): UnitContract {
+  const root = path.resolve(projectRoot);
+  const lock = path.resolve(lockPathFor(unit.dir));
+  const files = [...(fs.existsSync(lock) ? [lock] : []), ...contractFeatureFiles(unit.dir, unit.name)].map((abs) => {
+    let sha = 'unreadable';   // never equal to a recorded sha256: an unreadable contract file is stale
+    let mtimeMs = Number.POSITIVE_INFINITY;
+    try { sha = createHash('sha256').update(fs.readFileSync(abs)).digest('hex'); mtimeMs = fs.statSync(abs).mtimeMs; } catch { /* stale */ }
+    return { rel: posix(path.relative(root, abs)), sha, mtimeMs };
+  });
+  return { projectRoot: root, files };
+}
+
+function git(cwd: string, args: string[]): string | null {
+  try { return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 }).toString('utf8'); } catch { return null; }
+}
+
+/**
+ * Each contract file git holds unchanged → the last commit (first-parent history, merges included)
+ * that changed it, with its committer time. Two git calls for the whole unit; null when git cannot say.
+ * Paths are passed as literal pathspecs: no glob or `:(magic)` reading of a unit's file names.
+ */
+function committedTimes(c: UnitContract): Map<string, LastCommit> | null {
+  if (c.committed !== undefined) return c.committed;
+  const rels = c.files.map((f) => f.rel);
+  const changed = git(c.projectRoot, ['--literal-pathspecs', 'diff', '--name-only', '--relative', '-z', 'HEAD', '--', ...rels]);
+  const log = git(c.projectRoot, ['-c', 'core.quotePath=false', '--literal-pathspecs', 'log', '--first-parent', '-m', '-n', '500', '--format=%x01%H %ct', '--name-only', '--relative', '--', ...rels]);
+  if (changed === null || log === null) return (c.committed = null);
+  const dirty = new Set(changed.split('\0').filter(Boolean));
+  const times = new Map<string, LastCommit>();
+  let at: LastCommit | null = null;
+  for (const raw of log.split('\n')) {
+    const line = raw.trim();
+    if (raw.startsWith('\x01')) {
+      const [sha, ct] = raw.slice(1).trim().split(' ');
+      at = /^[0-9a-f]{40,64}$/.test(sha ?? '') && Number(ct) > 0 ? { sha, ms: Number(ct) * 1000 } : null;
+    } else if (line && at && !times.has(line) && !dirty.has(line)) times.set(line, at);
+  }
+  return (c.committed = times);
+}
+
+/** Is `sha` an ancestor of HEAD? First-parent history says so already; asserted, never assumed. */
+function isAncestorOfHead(c: UnitContract, sha: string): boolean {
+  if (!c.ancestors) c.ancestors = new Map();
+  if (!c.ancestors.has(sha)) c.ancestors.set(sha, git(c.projectRoot, ['merge-base', '--is-ancestor', sha, 'HEAD']) !== null);
+  return c.ancestors.get(sha)!;
+}
+
+/** Why a trace bound to `record` is older than the unit's contract — null when it is not. */
+export function staleReason(c: UnitContract, record: RunRecord): string | null {
+  if (record.contract) {
+    const f = c.files.find((x) => record.contract![x.rel] !== x.sha);
+    if (!f) return null;
+    const why = record.contract[f.rel] === undefined ? 'it did not exist when the run started' : 'its content changed after the run';
+    return `the trace is older than ${f.rel}: ${why} (stale) — re-run the test`;
+  }
+  const runStart = Date.parse(record.startedAt);   // unreadable → nothing is "before the run": stale
+  const late = c.files.filter((f) => !(f.mtimeMs <= runStart));
+  if (!late.length) return null;
+  const committed = committedTimes(c);
+  const vouched = (rel: string): boolean => {
+    const last = committed?.get(rel);
+    return !!last && last.ms <= runStart && isAncestorOfHead(c, last.sha);
+  };
+  const f = late.find((x) => !vouched(x.rel));
+  return f ? `the trace is older than ${f.rel}: it was written after the run, and no commit from before the run holds its bytes (stale) — re-run the test` : null;
+}

package/src/contract/trace/trace-identity-resolution.ts

@@ -51,13 +51,16 @@ export function identityRequestsFor(trace: ParsedTrace): TraceIdentityRequest[]
 }
 
 /** Ask the driver about every not-yet-cached target of these traces; rewrite the cache. */
-export async function resolveWithDriver(projectRoot: string, traces: ParsedTrace[], resolver: TraceIdentityResolver): Promise<{ asked: number; resolver: string; blockedRequests: number }> {
+/** `keys`: every target of the given traces (cached or asked) — what the caller reports on. */
+export async function resolveWithDriver(projectRoot: string, traces: ParsedTrace[], resolver: TraceIdentityResolver): Promise<{ asked: number; resolver: string; blockedRequests: number; keys: string[] }> {
   const { cache } = readIdentityCache(projectRoot);
   // The cache is project-wide (every unit's traces): answers are only ever ADDED, never pruned here.
   const keep = new Map<string, CachedIdentity>(cache.entries);
+  const all = traces.flatMap(identityRequestsFor);
+  const keys = [...new Set(all.map((req) => req.key))];
   const requests = new Map<string, TraceIdentityRequest>();
-  for (const req of traces.flatMap(identityRequestsFor)) if (!keep.has(req.key)) requests.set(req.key, req);
-  if (!requests.size) return { asked: 0, resolver: cache.resolver, blockedRequests: 0 };
+  for (const req of all) if (!keep.has(req.key)) requests.set(req.key, req);
+  if (!requests.size) return { asked: 0, resolver: cache.resolver, blockedRequests: 0, keys };
   const answer = await resolver({ requests: [...requests.values()] });
   if (!answer || !Array.isArray(answer.results)) throw new Error('the trace identity resolver returned no results');
   if (!TRUSTED_RESOLVER.test(String(answer.resolver)) || typeof answer.browser !== 'string' || !answer.browser) {
@@ -70,5 +73,5 @@ export async function resolveWithDriver(projectRoot: string, traces: ParsedTrace
     keep.set(key, { ...rest, browser: answer.browser.slice(0, 100) });
   }
   writeIdentityCache(projectRoot, answer.resolver, keep);
-  return { asked: requests.size, resolver: String(answer.resolver), blockedRequests: Number(answer.blockedRequests) || 0 };
+  return { asked: requests.size, resolver: String(answer.resolver), blockedRequests: Number(answer.blockedRequests) || 0, keys };
 }

package/src/contract/trace/trace-run-record.ts

@@ -8,6 +8,10 @@
  * own outputDir (#941) — or `<project>/test-results/sungen-run-record*.json` (one per run or shard).
  * Playwright wipes its outputDir at the start of every run, so a record and its traces share a
  * lifetime; the free run has its own so the compiled suite's next run cannot delete its traces.
+ *
+ * Schema 2 (#967) adds `contract`: the sha256 of every `.feature` and `contracts.lock.yaml` under `qa/`
+ * when the run started — what trace freshness compares by content. Schema 1 (an older reporter) has
+ * none; its traces are dated instead (trace-freshness.ts).
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -24,10 +28,13 @@ export interface RunRecord {
   shard: string | null;
   report: string | null;
   specs: Record<string, string>;
+  /** Schema 2: project path → sha256 of each contract file at run start. null: schema 1 (no content recorded). */
+  contract: Record<string, string> | null;
   attempts: RunRecordAttempt[];
 }
 
-const TOP = new Set(['schema', 'tool', 'runId', 'startedAt', 'playwrightVersion', 'shard', 'report', 'specs', 'attempts']);
+const TOP_V1: ReadonlySet<string> = new Set(['schema', 'tool', 'runId', 'startedAt', 'playwrightVersion', 'shard', 'report', 'specs', 'attempts']);
+const TOP_V2: ReadonlySet<string> = new Set([...TOP_V1, 'contract']);
 const ATTEMPT = new Set(['testId', 'file', 'title', 'retry', 'status', 'startTime', 'duration', 'trace']);
 const SHA = /^[0-9a-f]{64}$/;
 const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
@@ -65,16 +72,25 @@ export function readRunRecord(file: string, text?: string): RunRecord {
   let raw: unknown;
   try { raw = JSON.parse(text ?? fs.readFileSync(file, 'utf8')); } catch (e) { throw new Error(`not readable JSON (${(e as Error).message.split('\n')[0]})`); }
   if (!isObj(raw)) throw new Error('not an object');
-  const extra = Object.keys(raw).find((k) => !TOP.has(k));
+  if (raw.tool === 'sungen-trace-run-record' && typeof raw.schema === 'number' && raw.schema > 2) {
+    // A newer driver-ui wrote it (mixed versions): say what to upgrade, not just "not a record".
+    throw new Error(`record schema ${raw.schema} is newer than this sungen — upgrade @sun-asterisk/sungen (core before or together with driver-ui)`);
+  }
+  const keys = raw.schema === 2 ? TOP_V2 : raw.schema === 1 ? TOP_V1 : null;
+  if (!keys || raw.tool !== 'sungen-trace-run-record') throw new Error('not a sungen run record (schema 1 or 2)');
+  const extra = Object.keys(raw).find((k) => !keys.has(k));
   if (extra) throw new Error(`unknown key "${extra}"`);
-  if (raw.schema !== 1 || raw.tool !== 'sungen-trace-run-record') throw new Error('not a sungen run record (schema 1)');
   if (typeof raw.runId !== 'string' || !raw.runId || typeof raw.startedAt !== 'string' || typeof raw.playwrightVersion !== 'string') throw new Error('runId, startedAt and playwrightVersion must be strings');
   if (raw.shard !== null && typeof raw.shard !== 'string') throw new Error('shard must be a string or null');
   if (raw.report !== null && typeof raw.report !== 'string') throw new Error('report must be a string or null');
   if (!isObj(raw.specs) || !Object.values(raw.specs).every((v) => typeof v === 'string' && (v === '' || SHA.test(v)))) throw new Error('specs must map files to sha256');
+  if (raw.schema === 2 && !(isObj(raw.contract) && Object.values(raw.contract).every((v) => typeof v === 'string' && SHA.test(v)))) {
+    throw new Error('contract must map contract files to sha256 (schema 2)');
+  }
   if (!Array.isArray(raw.attempts)) throw new Error('attempts must be a list');
   return {
     file, runId: raw.runId, startedAt: raw.startedAt, playwrightVersion: raw.playwrightVersion, shard: raw.shard as string | null,
-    report: raw.report as string | null, specs: raw.specs as Record<string, string>, attempts: raw.attempts.map(attemptOf),
+    report: raw.report as string | null, specs: raw.specs as Record<string, string>,
+    contract: raw.schema === 2 ? raw.contract as Record<string, string> : null, attempts: raw.attempts.map(attemptOf),
   };
 }

package/src/orchestrator/templates/ai-src/commands/create-test.md

@@ -111,7 +111,10 @@ terminal (`script`, `expect`, a pty wrapper), and never edit `contracts.lock.yam
 traces, write their Gherkin with `sungen contract derive --screen <name>` — deterministic, it writes
 `features/<name>.free.feature` with every scenario tagged `@free @proposed`. Do not author those
 steps yourself; you may name the scenarios and suggest VP-ids. A `@proposed` scenario is not
-counted by the audit until a QA approves it (`sungen contract approve --screen <name>`).
+counted by the audit until a QA approves it (`sungen contract approve --screen <name>`). When
+two recorded tests claim one ID, `sungen contract derive` exits `1`, names both tests and writes
+nothing: stop and ask the QA to give each test its own ID (its title's leading ID, or its `@tag`).
+Never rename a test's ID — or a scenario's — yourself to get past it.
 
 ## Platform detection (do this FIRST)