@sun-asterisk/sungen 3.2.35 → 3.3.0-alpha.10

package/src/contract/normalize-contract-step.ts

@@ -0,0 +1,74 @@
+/**
+ * One parsed Gherkin step → one contract step (DOS-14.1). The step was already parsed by the
+ * existing GherkinParser (ParsedStep: parent scope, state clause, data table, nth); this re-reads
+ * its sentence with references and values masked, as the StepMapper's matcher does
+ * (`maskRefsForMatching`) so a NAME can never read as grammar — and keeps what it masked:
+ *
+ *   `User see [Status] text with {{s}} in [Job Row] row with {{t}}`
+ *     → {kind: assert, verb: 'see [] text with {}', target: {ref: 'Status', parent: 'row [Job Row] with {{t}}'},
+ *        matcher: 'equals', expected: '{{s}}'}
+ *
+ * The verb keeps every word and number of the sentence, so two steps with equal contract steps are
+ * the same sentence up to case and spacing: an exact match is never a guess. `{{var}}` stays a
+ * variable (never resolved), a literal loses only its quotes.
+ */
+import type { ParsedStep } from '../generators/gherkin-parser';
+import { extractParentScopeClause } from '../generators/gherkin-parser/parent-scope-clause';
+import type { ContractStep, ContractTarget } from './contract-schema';
+import { assertShapeOf } from './assertion-matcher-vocabulary';
+
+export type StepBucket = 'given' | 'when' | 'then';
+
+/** Quoted literal · `{{var}}` · `<outline placeholder>` · `[Reference]`, left to right. */
+const TOKEN = /"[^"]*"|\{\{[^}]*\}\}|<[^>\s][^>]*>|\[[^\]]*\]/g;
+
+function parentOf(text: string): { parent?: string; body: string } {
+  const { clause } = extractParentScopeClause(text);
+  if (!clause) return { body: text };
+  const tail = clause.valueRef !== undefined ? ` with {{${clause.valueRef}}}` : clause.valueText !== undefined ? ` with "${clause.valueText}"` : '';
+  return { parent: `${clause.type} [${clause.ref.trim()}]${tail}`, body: clause.remainingText };
+}
+
+export function normalizeContractStep(step: ParsedStep, bucket: StepBucket): ContractStep {
+  const { parent, body } = parentOf(step.text);
+  const refs: string[] = [];
+  const values: string[] = [];
+  const masked = body.replace(TOKEN, (tok) => {
+    if (tok.startsWith('[')) { refs.push(tok.slice(1, -1).trim()); return '[]'; }
+    values.push(tok.startsWith('"') ? tok.slice(1, -1) : tok);
+    return '{}';
+  });
+  const verb = masked.replace(/^\s*user\s+/i, '').replace(/\s+/g, ' ').replace(/\s*[.:]\s*$/, '').trim().toLowerCase();
+  const kind = bucket === 'then' ? 'assert' : 'action';
+
+  let target: ContractTarget | undefined;
+  if (refs.length) target = { ref: refs[0], ...(refs.length > 1 ? { also: refs.slice(1) } : {}) };
+  else if (kind === 'assert' && /^expect\b/.test(verb) && values.length) target = { ref: values.shift()! };
+  if (target && parent) target.parent = parent;
+  if (target && step.nth && step.nth > 0) target.nth = step.nth;
+
+  const joined = values.length ? values.join(' | ') : undefined;
+  const table = step.dataTable ? [step.dataTable.headers, ...step.dataTable.rows.map((r) => r.cells)] : undefined;
+  const out: ContractStep = { kind, verb };
+  if (target) out.target = target;
+  if (kind === 'action') {
+    if (joined !== undefined) out.value = joined;
+  } else {
+    const shape = assertShapeOf(verb, step.state);
+    out.matcher = shape.matcher;
+    if (joined !== undefined) out.expected = joined;
+    if (shape.negated) out.negated = true;
+  }
+  if (table) out.table = table;
+  return out;
+}
+
+/** Given/When/Then for every step of one block, And/But inheriting the last primary keyword. */
+export function bucketsOf(steps: ParsedStep[]): StepBucket[] {
+  let last: StepBucket = 'given';
+  return steps.map((s) => {
+    const kw = s.keyword.trim().toLowerCase();
+    if (kw === 'given' || kw === 'when' || kw === 'then') last = kw;
+    return last;
+  });
+}

package/src/contract/normalize-feature-steps.ts

@@ -0,0 +1,93 @@
+/**
+ * A unit's `.feature` files → its contract scenarios (DOS-14.1, 14.2), through the existing
+ * GherkinParser — no second parser.
+ *
+ *   which scenarios  every automated one: not `@manual` (scenario or feature), not `@deferred:flow`,
+ *                    not a `@steps:` block or a `@beforeAll/@afterEach/@afterAll` hook
+ *   steps            Background + the `@extend:` base's Given/When (the compiler's own rule) + its own
+ *   id               the title's leading ID (`VP-LOGIN-001`), as the harness reads it; a title with no
+ *                    ID is locked by its name, so renaming it reads as removing it
+ *   implementation   `@free` → free, `@impl:code` → impl:code, otherwise compiled — scenario or feature tag
+ *   hash             contractHash(implementation, steps); the scenario name is not in it
+ *
+ * A file that does not parse throws: an unreadable contract is never an empty one.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { GherkinParser, ParsedScenario, ParsedStep } from '../generators/gherkin-parser';
+import { isIdLike } from '../harness/parse';
+import { featureFilesFor } from '../harness/unit-paths';
+import { contractHash } from './contract-hash';
+import type { ContractScenario, ContractStep, Implementation } from './contract-schema';
+import { bucketsOf, normalizeContractStep } from './normalize-contract-step';
+
+const EXCLUDED = (tags: string[]): boolean => tags.some((t) => /^@manual\b/i.test(t) || /^@deferred:flow$/i.test(t));
+
+function implementationOf(tags: string[]): Implementation {
+  if (tags.some((t) => /^@free$/i.test(t))) return 'free';
+  if (tags.some((t) => /^@impl:code$/i.test(t))) return 'impl:code';
+  return 'compiled';
+}
+
+function idOf(name: string): { id: string; hasId: boolean } {
+  const lead = name.match(/^\s*([A-Za-z][A-Za-z0-9.-]*)/)?.[1];
+  return lead && isIdLike(lead) ? { id: lead.toUpperCase(), hasId: true } : { id: name.replace(/\s+/g, ' ').trim(), hasId: false };
+}
+
+/** Only Given→When of an `@extend` base: its Then (and the And/But after it) stay with the base. */
+const extendPart = (steps: ParsedStep[]): ParsedStep[] => steps.filter((_, i) => bucketsOf(steps)[i] !== 'then');
+
+const normalizeBlock = (steps: ParsedStep[]): ContractStep[] => {
+  const buckets = bucketsOf(steps);
+  return steps.map((s, i) => normalizeContractStep(s, buckets[i]));
+};
+
+/** 1-based line of each step, searched in order from line index `from` — for messages only (0 = not found). */
+function stepLines(lines: string[], from: number, steps: ParsedStep[]): number[] {
+  let at = Math.max(from, 0);
+  return steps.map((s) => {
+    const i = lines.findIndex((l, n) => n >= at && l.trim().endsWith(s.text.trim()));
+    if (i >= 0) at = i + 1;
+    return i + 1;
+  });
+}
+
+const HEADER = /^\s*(?:Scenario|Scenario Outline|Scenario Template|Example):/;
+const OUTLINE = /^\s*Scenario (?:Outline|Template):/;
+const headerLine = (lines: string[], name: string): number => lines.findIndex((l) => HEADER.test(l) && l.includes(name.trim()));
+
+export function scenariosOfFeatureFile(file: string): ContractScenario[] {
+  const feature = new GherkinParser().parseFeatureFile(file);
+  const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
+  const base = new Map<string, ParsedScenario>();
+  for (const sc of feature.scenarios) if (sc.stepsName) base.set(sc.stepsName, sc);
+  const background = feature.background?.steps ?? [];
+  const out: ContractScenario[] = [];
+  for (const sc of feature.scenarios) {
+    const tags = [...(feature.tags ?? []), ...(sc.tags ?? [])];
+    if (sc.stepsName || sc.hookType || EXCLUDED(tags)) continue;
+    const baseScenario = sc.extendsName ? base.get(sc.extendsName) : undefined;
+    const extended = extendPart(baseScenario?.steps ?? []);
+    const steps = [...normalizeBlock(background), ...normalizeBlock(extended), ...normalizeBlock(sc.steps)];
+    const implementation = implementationOf(tags);
+    const { id, hasId } = idOf(sc.name);
+    const header = headerLine(lines, sc.name);
+    const sourceLines = [
+      ...stepLines(lines, 0, background),
+      ...stepLines(lines, baseScenario ? headerLine(lines, baseScenario.name) : 0, extended),
+      ...stepLines(lines, header, sc.steps),
+    ];
+    const outline = header >= 0 && OUTLINE.test(lines[header]);
+    out.push({ id, implementation, steps, hash: contractHash(implementation, steps), source: { file, name: sc.name, hasId, lines: sourceLines, outline } });
+  }
+  return out;
+}
+
+/** Every contract scenario of a unit, in `featureFilesFor` order. Missing feature files contribute nothing. */
+export function loadContractScenarios(unitDir: string, unit: string): ContractScenario[] {
+  return featureFilesFor(unitDir, unit).filter((f) => fs.existsSync(f)).flatMap(scenariosOfFeatureFile);
+}
+
+/** Feature files that make up a unit's contract input (for the inputs hash). */
+export const contractFeatureFiles = (unitDir: string, unit: string): string[] =>
+  featureFilesFor(unitDir, unit).filter((f) => fs.existsSync(f)).map((f) => path.resolve(f));

package/src/contract/oracle-strength.ts

@@ -0,0 +1,80 @@
+/**
+ * How a changed assertion compares to the approved one on the same target (DOS-14.4).
+ *
+ * Every rule is written for POSITIVE checks, from the approved check A to the new check B:
+ *   weakened      expected value dropped · a data-table row removed or a cell changed · a shorter
+ *                 literal under `contains` · a lower rung on the ladder (conservative)
+ *   strengthened  B implies A, with the same expected value, on the same element (IMPLICATION, never
+ *                 rung): equals ⇒ contains · all:X ⇒ X · url ⇒ url-contains · title ⇒ title-contains
+ *   review        anything else — it blocks delivery until QA re-approves it
+ * Nothing implies `visible`: a text or count check passes on a hidden element, and a state (enabled,
+ * checked, empty, focused, selected, loading, sorted…) says nothing about visibility either.
+ *
+ * Under a NEGATION the direction reverses — `not P` proves `not Q` exactly when Q ⇒ P — so the same
+ * rules run with A and B swapped: `does not see [Toast]` → `does not see [Toast] with text {{x}}` is
+ * a weakening (a visible toast with other text now passes). A negation added or removed is a flip.
+ */
+import { sameJson } from './contract-hash';
+import type { ContractStep } from './contract-schema';
+import { matcherStrength } from './assertion-matcher-vocabulary';
+
+export { assertShapeOf, matcherStrength } from './assertion-matcher-vocabulary';
+export type { AssertShape } from './assertion-matcher-vocabulary';
+
+const IMPLIES: Record<string, readonly string[]> = { equals: ['contains'], url: ['url-contains'], title: ['title-contains'] };
+
+/** Does a passing `now` check prove the `was` check (both positive)? */
+export function impliesMatcher(now: string | undefined, was: string | undefined): boolean {
+  if (!now || !was || now === was) return false;
+  if (was.startsWith('all:') && !now.startsWith('all:')) return false;
+  const n = now.replace(/^all:/, '');
+  const w = was.replace(/^all:/, '');
+  return n === w || (IMPLIES[n] ?? []).includes(w);
+}
+
+const CONNECTORS = new Set(['with', 'has', 'have', 'contains', 'contain', 'includes', 'include', 'is', 'matches', 'in', 'to', 'and']);
+const elementType = (verb: string): string => {
+  const m = verb.match(/\[\] ([\w-]+)/);
+  return m && !CONNECTORS.has(m[1]) ? m[1] : '';
+};
+const isLiteral = (v: string | undefined): v is string => v !== undefined && !/\{\{|<[^>]+>/.test(v);
+const baseOf = (m: string | undefined): string => (m ?? '').replace(/^all:/, '');
+const rowsOf = (t: string[][] | undefined): string[] => (t ?? []).map((r) => JSON.stringify(r));
+const TEXT = new Set(['equals', 'contains']);
+
+/** x ⇒ y for two positive LITERAL text checks (equals / contains); null when they are not both that. */
+function literalImplies(x: ContractStep, y: ContractStep): boolean | null {
+  const bx = baseOf(x.matcher);
+  const by = baseOf(y.matcher);
+  if (!isLiteral(x.expected) || !isLiteral(y.expected) || !TEXT.has(bx) || !TEXT.has(by)) return null;
+  return by === 'equals' ? bx === 'equals' && x.expected === y.expected : x.expected.includes(y.expected);
+}
+
+export type AssertComparison = { class: 'strengthened' | 'review' | 'oracle-weakened'; detail: string };
+
+const show = (s: ContractStep): string => `${s.negated ? 'not ' : ''}${s.matcher ?? '?'}${s.expected !== undefined ? ` "${s.expected}"` : ''}`;
+
+/** Two assertions on the same target that are NOT identical. */
+export function compareAsserts(locked: ContractStep, current: ContractStep): AssertComparison {
+  const change = `${show(locked)} → ${show(current)}`;
+  const weak = (why: string): AssertComparison => ({ class: 'oracle-weakened', detail: `${why}: ${change}` });
+  const review = (why: string): AssertComparison => ({ class: 'review', detail: `${why}: ${change}` });
+  if (!!locked.negated !== !!current.negated) return weak('negation flipped');
+  const neg = locked.negated === true;
+  const [a, b] = neg ? [current, locked] : [locked, current];
+  const sa = matcherStrength(a.matcher);
+  const sb = matcherStrength(b.matcher);
+  if (sa === null || sb === null) return review(`the ladder cannot judge "${locked.verb}" → "${current.verb}"`);
+  if (a.expected !== undefined && b.expected === undefined) return weak(neg ? 'a value was added to a negated check' : 'expected value dropped');
+  if (a.table) {
+    const kept = new Set(rowsOf(b.table));
+    const lost = rowsOf(a.table).filter((r) => !kept.has(r)).length;
+    if (lost) return weak(`${lost} data-table row(s) ${neg ? 'added to a negated check' : 'removed or changed'}`);
+  }
+  if (literalImplies(a, b) === true && literalImplies(b, a) === false) return weak(neg ? 'a longer literal under a negated check' : 'a shorter literal under contains');
+  if (sb < sa) return weak('weaker check');
+  if (a.expected !== undefined && b.expected !== a.expected) return review('expected value changed');
+  const sameElement = sameJson(a.target, b.target) && elementType(a.verb) === elementType(b.verb) && rowsOf(a.table).length === rowsOf(b.table).length;
+  if (sameElement && impliesMatcher(b.matcher, a.matcher)) return { class: 'strengthened', detail: `stronger check: ${change}` };
+  return review('changed, and the new check does not prove the approved one');
+}

package/src/contract/project-contract-blockers.ts

@@ -0,0 +1,38 @@
+/**
+ * Which units' contracts hold a delivery back — for the Claude Code guard (OES-12.3, DOS-14.4).
+ *
+ * HEAD is read once (one `git ls-tree`, bounded by the caller's timeout). A unit with no lock in the
+ * working tree AND none in HEAD has no contract to break and is skipped without parsing anything.
+ * Every other unit gets its verdict rebuilt by buildContractVerdict — the same function `contract
+ * check` runs — and anything but `pass` blocks. Its trace part gets the guard's ~3 s at most:
+ * SUNGEN_TRACE_VERDICT_BUDGET_MS can shorten that here, never lengthen it (#926). A lock deleted from the working tree still counts
+ * while HEAD holds it. If git FAILS in a checkout that has .git while a delivered unit has a lock,
+ * this throws (GitUnavailableError): the guard asks rather than calling an unverifiable lock clean.
+ */
+import * as fs from 'fs';
+import { buildContractVerdict, ContractUnit, VerdictValue } from './build-contract-verdict';
+import { guardTraceBudgetMs } from './build-trace-conformance';
+import { CLI_GIT_TIMEOUT_MS, GitUnavailableError, headSnapshot, posixRel } from './contract-git';
+import { HARD_CLASSES } from './contract-schema';
+import { lockPathFor } from './contracts-lock-file';
+
+export interface ContractBlocker { unit: string; verdict: Exclude<VerdictValue, 'pass'>; headline: string }
+
+export function contractBlockers(projectRoot: string, units: ContractUnit[], opts: { gitTimeoutMs?: number } = {}): ContractBlocker[] {
+  const unique = [...new Map(units.map((u) => [u.dir, u])).values()];
+  const snap = headSnapshot(projectRoot, opts.gitTimeoutMs ?? CLI_GIT_TIMEOUT_MS);
+  const hasWorkingLock = (u: ContractUnit): boolean => fs.existsSync(lockPathFor(u.dir));
+  if (snap.error && unique.some(hasWorkingLock)) throw new GitUnavailableError(snap.error);
+  const out: ContractBlocker[] = [];
+  for (const unit of unique) {
+    if (!hasWorkingLock(unit) && !snap.blobs?.has(posixRel(projectRoot, lockPathFor(unit.dir)))) continue;
+    const v = buildContractVerdict(projectRoot, unit, { snapshot: snap, traceBudgetMs: guardTraceBudgetMs() });
+    if (v.verdict === 'pass') continue;
+    const worst = v.scenarios.find((s) => HARD_CLASSES.has(s.class)) ?? v.scenarios.find((s) => s.class === 'hash-changed');
+    const headline = worst
+      ? `${worst.id} ${worst.class}${worst.findings[0] ? ` (${worst.findings[0].detail})` : ''}`
+      : `${v.uncommitted.length} lock entr${v.uncommitted.length === 1 ? 'y is' : 'ies are'} not what QA approved and committed (${v.uncommitted[0]?.id} ${v.uncommitted[0]?.change})`;
+    out.push({ unit: unit.name, verdict: v.verdict, headline });
+  }
+  return out;
+}

package/src/contract/record-contract-approval.ts

@@ -0,0 +1,110 @@
+/**
+ * What an approval writes, once a human has confirmed it (DOS-14.3, DOS-14.4, takumi T5):
+ *
+ *   1. the secret guard over the exact lock text — a hit writes nothing at all
+ *   2. a `contract-approval` decision listing every approved scenario id + hash (and the removals)
+ *   3. the lock: each approved entry `humanApproved: true`, `decisionId` = that decision, and
+ *      `approvedAt` = its `valid_from` — the pair `contract check` cross-checks (M1)
+ *
+ * The decision goes first: a crash between the two leaves a record without a lock entry, never an
+ * entry pointing at nothing. Only `sungen contract approve` calls this after its TTY confirmation;
+ * the confirmation itself lives there (approve-contract.ts).
+ *
+ * `--accept-opaque` (#923, accept-opaque-steps.ts) writes the same kind of decision for ONE scenario,
+ * listing it at its hash WITH the opaque steps QA accepted (step + sha); its lock entry is rewritten to
+ * point at that decision and carries the same list, which verify-approval-decisions.ts cross-checks.
+ */
+import * as path from 'path';
+import { appendDecision } from '../decisions/append-decision';
+import { isValidScope } from '../decisions/decision-file';
+import type { JsonValue } from '../decisions/decision-schema';
+import { gitUserName } from '../decisions/decision-source';
+import { AcceptedOpaqueStep, ContractLock, ContractScenario, LOCK_SCHEMA } from './contract-schema';
+import { lockEntryFor, lockPathFor, serializeLock, writeLockFile } from './contracts-lock-file';
+import { assertNoLockSecrets } from './lock-secret-guard';
+
+export interface ApprovalWrite {
+  projectRoot: string;
+  unitDir: string;
+  unit: string;
+  approve: ContractScenario[];
+  removed: string[];
+  reason?: string;
+  lock: ContractLock | null;
+}
+
+export const DEFAULT_APPROVAL_REASON = 'QA reviewed the normalized Gherkin contract';
+export const DEFAULT_OPAQUE_REASON = 'QA reviewed the opaque step(s) sungen cannot compare';
+
+export interface OpaqueAcceptanceWrite {
+  projectRoot: string;
+  unitDir: string;
+  unit: string;
+  /** The scenario as it reads now — its hash equals its approved lock entry's. */
+  scenario: ContractScenario;
+  accepted: AcceptedOpaqueStep[];
+  reason?: string;
+  lock: ContractLock;
+}
+
+/** The decision scope of a unit directory (`screens/login`, `api/flows/pay`…). */
+export function scopeOfUnitDir(projectRoot: string, unitDir: string): string {
+  const scope = path.relative(path.join(projectRoot, 'qa'), unitDir).split(path.sep).join('/');
+  if (!isValidScope(scope)) throw new Error(`${unitDir} is not a unit directory under qa/ (screens|flows|api/<unit>, api/flows/<flow>)`);
+  return scope;
+}
+
+export function nextLock(w: ApprovalWrite, decisionId: string, approvedAt: string): ContractLock {
+  const scenarios = { ...(w.lock?.scenarios ?? {}) };
+  for (const id of w.removed) delete scenarios[id];
+  for (const sc of w.approve) scenarios[sc.id] = lockEntryFor(sc, decisionId, approvedAt);
+  return { schema: LOCK_SCHEMA, scenarios };
+}
+
+/** Throws LockSecretError when the lock this approval would write carries a sensitive value. */
+export function checkApprovalSecrets(w: ApprovalWrite): void {
+  assertNoLockSecrets(w.approve, serializeLock(nextLock(w, 'D-0000000000000000', new Date().toISOString())));
+}
+
+export function recordContractApproval(w: ApprovalWrite): { decisionId: string; lock: ContractLock } {
+  const scope = scopeOfUnitDir(w.projectRoot, w.unitDir);
+  checkApprovalSecrets(w);
+  const payload: Record<string, JsonValue> = {
+    unit: w.unit,
+    scenarios: w.approve.map((s) => ({ id: s.id, hash: s.hash, implementation: s.implementation })),
+    removed: w.removed,
+  };
+  const decision = appendDecision(w.projectRoot, scope, {
+    kind: 'contract-approval', anchors: [], visibility: 'internal', valid_from: new Date().toISOString(), payload,
+    text: `Approved the Test Contract of ${w.unit}: ${[...w.approve.map((s) => s.id), ...w.removed.map((id) => `-${id}`)].join(', ')}`,
+    reason: w.reason?.trim() || DEFAULT_APPROVAL_REASON,
+    source: { by: gitUserName(w.projectRoot), where: 'cli' },
+  });
+  const lock = nextLock(w, decision.entry.id, decision.entry.valid_from);
+  writeLockFile(lockPathFor(w.unitDir), lock);
+  return { decisionId: decision.entry.id, lock };
+}
+
+function lockWithAcceptance(w: OpaqueAcceptanceWrite, decisionId: string, approvedAt: string): ContractLock {
+  const entry = { ...lockEntryFor(w.scenario, decisionId, approvedAt), acceptedOpaque: w.accepted.map((a) => ({ step: a.step, sha: a.sha })) };
+  return { schema: LOCK_SCHEMA, scenarios: { ...w.lock.scenarios, [w.scenario.id]: entry } };
+}
+
+export function recordOpaqueAcceptance(w: OpaqueAcceptanceWrite): { decisionId: string; lock: ContractLock } {
+  const scope = scopeOfUnitDir(w.projectRoot, w.unitDir);
+  assertNoLockSecrets([w.scenario], serializeLock(lockWithAcceptance(w, 'D-0000000000000000', new Date().toISOString())));
+  const sc = w.scenario;
+  const accepted = w.accepted.map((a) => ({ step: a.step, sha: a.sha }));
+  const payload: Record<string, JsonValue> = {
+    unit: w.unit, scenarios: [{ id: sc.id, hash: sc.hash, implementation: sc.implementation, acceptedOpaque: accepted }], removed: [],
+  };
+  const decision = appendDecision(w.projectRoot, scope, {
+    kind: 'contract-approval', anchors: [], visibility: 'internal', valid_from: new Date().toISOString(), payload,
+    text: `Accepted the reviewed opaque step(s) ${[...new Set(accepted.map((a) => a.step))].join(', ')} of ${sc.id} (${w.unit})`,
+    reason: w.reason?.trim() || DEFAULT_OPAQUE_REASON,
+    source: { by: gitUserName(w.projectRoot), where: 'cli' },
+  });
+  const lock = lockWithAcceptance(w, decision.entry.id, decision.entry.valid_from);
+  writeLockFile(lockPathFor(w.unitDir), lock);
+  return { decisionId: decision.entry.id, lock };
+}

package/src/contract/render-free-gherkin.ts

@@ -0,0 +1,118 @@
+/**
+ * A trace's intent steps → Gherkin steps, deterministically (DOS-14.8): the same trace and the same
+ * identities give the same text, byte for byte. No LLM is involved — naming a scenario or suggesting
+ * a VP-id is left to the user (or an agent) and never touches the steps or the hash.
+ *
+ *   keywords   first step `Given`; the next action `When`, later actions `And`; a check after an
+ *              action `Then`, after a check `And`; an action after a check `When`
+ *   drops      a click on an element immediately followed by a fill of the SAME element (a focus click)
+ *   opaque     `User see opaque check "<source line>"` / `User do opaque step "<GET /api/x>"`, with a
+ *              `# opaque at <file>:<line>` comment — kept verbatim, always reviewed by a human
+ *   low        `# identity low: <why>` above any step whose target is not proven
+ *   safety     secrets typed into credential fields are redacted everywhere; machine paths scrubbed
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { displayPath, scrubKnownSecrets, scrubMachinePaths } from './field-semantic-redaction';
+import { normalizeShownText, TestDataIndex } from './data-normalize';
+import { renderTarget, sameTarget } from './render-trace-target';
+import { actionSentence, assertSentence, sensitiveStep } from './render-trace-sentence';
+import type { TargetFacts, TargetIdentity } from './trace/target-identity';
+import { isPageLevel } from './trace/trace-identity-resolution';
+import type { IntentStep } from './trace/trace-steps';
+
+export const CONTROL_CHARS = /[\u0000-\u001f\u007f\u2028\u2029]/g;
+/** Text from a trace or report shown in one line of a finding: control characters dropped, at most `max` characters. */
+export function clip(s: string, max = 120): string {
+  const t = s.replace(CONTROL_CHARS, '');
+  return t.length > max ? `${t.slice(0, max - 1)}\u2026` : t;
+}
+
+export interface ResolvedTarget { identity: TargetIdentity; facts?: TargetFacts }
+export interface RenderedStep {
+  keyword: 'Given' | 'When' | 'Then' | 'And';
+  sentence: string;
+  kind: 'action' | 'assert';
+  /** The outermost `test.step` title (impl:code compares group by group). */
+  group?: string;
+  low?: string;
+  opaque?: { verbatim: string; where?: string };
+}
+export interface RenderContext { index: TestDataIndex; projectRoot: string; specFile?: string; secrets: Set<string> }
+
+function whereOf(step: IntentStep, ctx: RenderContext): { where?: string; line?: string } {
+  const loc = step.location;
+  if (!loc?.file) return {};
+  const own = ctx.specFile && (loc.file === ctx.specFile || loc.file.endsWith(`/${ctx.specFile}`) || path.basename(loc.file) === path.basename(ctx.specFile));
+  const file = own ? ctx.specFile! : displayPath(loc.file, ctx.projectRoot);
+  let line: string | undefined;
+  if (own) {
+    try { line = fs.readFileSync(path.join(ctx.projectRoot, ctx.specFile!), 'utf8').split(/\r?\n/)[loc.line - 1]?.trim(); } catch { line = undefined; }
+  }
+  return { where: `${file}:${loc.line}`, line };
+}
+
+const quoteVerbatim = (s: string): string => `"${normalizeShownText(s).replace(/"/g, "'").replace(/\s+/g, ' ').trim()}"`;
+
+function keywordFor(kind: 'action' | 'assert', prev: RenderedStep[]): RenderedStep['keyword'] {
+  const last = prev[prev.length - 1];
+  if (!last) return 'Given';
+  if (kind === 'assert') return last.kind === 'assert' ? 'And' : 'Then';
+  if (last.kind === 'assert') return 'When';
+  return prev.length === 1 && last.keyword === 'Given' ? 'When' : 'And';
+}
+
+export function renderTraceSteps(steps: IntentStep[], targets: Map<string, ResolvedTarget>, ctx: RenderContext): RenderedStep[] {
+  const out: RenderedStep[] = [];
+  steps.forEach((step, i) => {
+    const t = step.callId ? targets.get(step.callId) : undefined;
+    const next = steps[i + 1];
+    if (step.method === 'click' && next && (next.method === 'fill' || next.method === 'type') && sameTarget(t?.identity, next.callId ? targets.get(next.callId)?.identity : undefined)) return;
+    const group = step.group[0];
+    if (step.kind === 'opaque-assert' || step.kind === 'opaque-action') {
+      const { where, line } = whereOf(step, ctx);
+      const verbatim = step.kind === 'opaque-action' && /^[A-Z]+ /.test(step.verbatim ?? '') ? step.verbatim! : line || step.verbatim || step.method;
+      const kind = step.kind === 'opaque-assert' ? 'assert' : 'action';
+      const sentence = kind === 'assert' ? `User see opaque check ${quoteVerbatim(verbatim)}` : `User do opaque step ${quoteVerbatim(verbatim)}`;
+      out.push({ keyword: keywordFor(kind, out), sentence, kind, ...(group ? { group } : {}), opaque: { verbatim, ...(where ? { where } : {}) } });
+      return;
+    }
+    const target = isPageLevel(step) ? { text: '' } : renderTarget(t?.identity, t?.facts, typeof step.params.selector === 'string' ? step.params.selector : undefined);
+    const kind = step.kind === 'assert' ? 'assert' : 'action';
+    const sentence = kind === 'assert' ? assertSentence(step, target.text) : actionSentence(step, target.text, ctx, sensitiveStep(step, t?.facts, t?.identity.name));
+    out.push({ keyword: keywordFor(kind, out), sentence, kind, ...(group ? { group } : {}), ...(target.low ? { low: target.low } : {}) });
+  });
+  // Control characters (terminal escapes, BEL, line separators) would corrupt or spoof a Gherkin line.
+  const clean = (s: string): string => scrubMachinePaths(scrubKnownSecrets(s, ctx.secrets), ctx.projectRoot).replace(CONTROL_CHARS, '');
+  return out.map((s) => ({
+    ...s, sentence: clean(s.sentence), ...(s.low ? { low: clean(s.low) } : {}),
+    ...(s.opaque ? { opaque: { verbatim: clean(s.opaque.verbatim), ...(s.opaque.where ? { where: clean(s.opaque.where) } : {}) } } : {}),
+  }));
+}
+
+/** The Gherkin lines of one scenario's steps, with their comments. */
+export function stepLines(steps: RenderedStep[]): string[] {
+  const lines: string[] = [];
+  for (const s of steps) {
+    if (s.opaque) lines.push(`    # opaque${s.opaque.where ? ` at ${s.opaque.where}` : ''} — compared by a human, never automatically`);
+    if (s.low) lines.push(`    # identity low: ${s.low}`);
+    lines.push(`    ${s.keyword} ${s.sentence}`);
+  }
+  return lines;
+}
+
+export interface FreeScenarioBlock { id: string; title: string; tags: string[]; comments: string[]; steps: RenderedStep[] }
+
+export function scenarioBlockText(b: FreeScenarioBlock): string {
+  return [`  ${b.tags.join(' ')}`, `  Scenario: ${b.title}`, ...b.comments.map((c) => `    # ${c}`), ...stepLines(b.steps)].join('\n');
+}
+
+export const FREE_FEATURE_HEADER = [
+  '# Derived by `sungen contract derive` from Playwright traces — deterministic, no LLM.',
+  '# These steps are the contract; the Playwright test is the implementation. Each scenario stays a',
+  '# proposal (not counted by the audit) until QA approves it: sungen contract approve --screen <unit>',
+];
+
+export function freeFeatureText(unit: string, blocks: string[]): string {
+  return [...FREE_FEATURE_HEADER.map((l) => l.replace('<unit>', unit)), `Feature: ${unit} (free tests)`, '', ...blocks.flatMap((b) => [b, ''])].join('\n');
+}

package/src/contract/render-trace-sentence.ts

@@ -0,0 +1,98 @@
+/**
+ * One trace intent step → one sungen Gherkin sentence (without its keyword), in the documented
+ * forms the contract normalizer reads (DOS-14.1): `fill [T] field with {{v}}`, `see [T] heading
+ * with text "x"`, `see the url matches "re"`, `do not see [T] dialog`, `see [T] checkbox is checked`…
+ * A check outside that vocabulary still renders (verbatim expression words) and normalizes to the
+ * `unknown` matcher — which the ladder never calls `match` unless the sentence is identical.
+ */
+import { normalizeShownText, normalizeValue, TestDataIndex } from './data-normalize';
+import { isSensitiveTarget, REDACTED } from './field-semantic-redaction';
+import type { IntentStep } from './trace/trace-steps';
+
+export interface SentenceContext {
+  index: TestDataIndex;
+  /** Raw values typed into credential fields — scrubbed from everything written. */
+  secrets: Set<string>;
+}
+
+const str = (v: unknown): string => (typeof v === 'string' ? v : v === undefined || v === null ? '' : String(v));
+const quote = (v: string): string => `"${v.replace(/"/g, "'").replace(/\r?\n/g, '\\n')}"`;
+
+/** A value as the step writes it: a whole `{{ref}}` bare, anything else quoted. */
+function valueText(raw: string, ctx: SentenceContext, sensitive: boolean): string {
+  const ref = ctx.index.byValue.get(raw);
+  if (ref) return `{{${ref}}}`;
+  if (sensitive) { if (raw) ctx.secrets.add(raw); return REDACTED; }
+  const v = normalizeValue(raw, ctx.index);
+  return /^\{\{[^}]+\}\}$/.test(v) ? v : quote(v);
+}
+
+function pathOf(url: string): string {
+  try { const u = new URL(url); return /^https?:$/.test(u.protocol) ? `${u.pathname}${u.search}` : url; } catch { return url; }
+}
+
+function selectValues(params: Record<string, unknown>): string {
+  const opts = Array.isArray(params.options) ? params.options : [];
+  return opts.map((o) => (o && typeof o === 'object' ? str((o as Record<string, unknown>).valueOrLabel ?? (o as Record<string, unknown>).value ?? (o as Record<string, unknown>).label ?? (o as Record<string, unknown>).index) : str(o))).join(' | ');
+}
+
+export function actionSentence(step: IntentStep, target: string, ctx: SentenceContext, sensitive: boolean): string {
+  const p = step.params;
+  switch (step.method) {
+    case 'goto': return `User is on [${pathOf(normalizeShownText(str(p.url)))}] page`;
+    case 'fill': return `User fill ${target} with ${valueText(str(p.value), ctx, sensitive)}`;
+    case 'type': return `User fill ${target} with ${valueText(str(p.text), ctx, sensitive)}`;
+    case 'click': case 'tap': return `User click ${target}`;
+    case 'dblclick': return `User double click ${target}`;
+    case 'check': return `User check ${target}`;
+    case 'uncheck': return `User uncheck ${target}`;
+    case 'hover': return `User hover ${target}`;
+    case 'selectOption': return `User select ${target} with ${valueText(selectValues(p), ctx, false)}`;
+    case 'press': return `User press ${quote(str(p.key))} on ${target}`;
+    case 'setInputFiles': {
+      const files = Array.isArray(p.payloads) ? p.payloads.map((x) => str((x as Record<string, unknown>)?.name)) : Array.isArray(p.localPaths) ? p.localPaths.map((x) => str(x).split(/[\\/]/).pop() ?? '') : [];
+      return `User fill ${target.replace(/\] \S+/, '] uploader')} with ${quote(files.join(' | '))}`;
+    }
+    case 'keyboardPress': return `User press ${quote(str(p.key))} key`;
+    default: return `User type ${valueText(str(p.text), ctx, false)} on the keyboard`;
+  }
+}
+
+interface Expected { kind: 'text' | 'regex' | 'none'; value: string }
+function expectedOf(p: Record<string, unknown>): Expected {
+  const list = Array.isArray(p.expectedText) ? (p.expectedText as Array<Record<string, unknown>>) : [];
+  if (list.length && list.every((e) => typeof e?.regexSource === 'string')) return { kind: 'regex', value: list.map((e) => str(e.regexSource)).join(' | ') };
+  if (list.length) return { kind: 'text', value: list.map((e) => str(e.string ?? e.regexSource)).join(' | ') };
+  if (typeof p.expectedNumber === 'number') return { kind: 'text', value: String(p.expectedNumber) };
+  return { kind: 'none', value: '' };
+}
+
+const STATES: Record<string, string> = { 'to.be.checked': 'checked', 'to.be.enabled': 'enabled', 'to.be.disabled': 'disabled', 'to.be.focused': 'focused', 'to.be.empty': 'empty', 'to.be.editable': 'editable', 'to.be.attached': 'attached' };
+
+export function assertSentence(step: IntentStep, target: string): string {
+  const p = step.params;
+  const expr = str(p.expression);
+  const not = p.isNot === true;
+  const e = expectedOf(p);
+  const shown = (v: string): string => quote(normalizeShownText(v));
+  if (expr === 'to.have.url' || expr === 'to.have.title') {
+    const subject = expr === 'to.have.url' ? 'url' : 'title';
+    return `User see the ${subject} ${e.kind === 'regex' ? (not ? 'does not match' : 'matches') : not ? 'is not' : 'is'} ${shown(e.value)}`;
+  }
+  if (expr === 'to.be.visible') return not ? `User do not see ${target}` : `User see ${target}`;
+  if (expr === 'to.be.hidden') return not ? `User see ${target}` : `User see ${target} is hidden`;
+  if (STATES[expr]) return `User see ${target} is ${not ? 'not ' : ''}${STATES[expr]}`;
+  if (expr === 'to.have.text' || expr === 'to.contain.text') {
+    if (e.kind === 'regex') return `User see ${target} ${not ? 'does not match' : 'matches'} ${shown(e.value)}`;
+    if (expr === 'to.contain.text') return `User see ${target} ${not ? 'does not contain' : 'contains'} ${shown(e.value)}`;
+    return `User see ${target} ${not ? 'does not have text' : 'with text'} ${shown(e.value)}`;
+  }
+  if (expr === 'to.have.value' || expr === 'to.have.values') return `User see ${target} ${not ? 'does not have value' : 'has value'} ${shown(e.value)}`;
+  if (expr === 'to.have.count') return `User see ${target} ${not ? 'does not have' : 'has'} ${shown(e.value)} items`;
+  const words = expr.replace(/^to\./, '').replace(/\./g, ' ').replace(/^have /, 'has ').replace(/^be /, 'is ');
+  return `User see ${target} ${not ? 'not ' : ''}${words}${e.kind === 'none' ? '' : ` ${shown(e.value)}`}`;
+}
+
+/** The value typed into a credential field is sensitive even when the field's name is not. */
+export const sensitiveStep = (step: IntentStep, facts: Parameters<typeof isSensitiveTarget>[0], name?: string): boolean =>
+  (step.method === 'fill' || step.method === 'type') && isSensitiveTarget(facts, name);