@sun-asterisk/sungen 3.2.34 → 3.3.0-alpha.2

package/src/graph/nodes/unit-design-nodes.ts

@@ -0,0 +1,89 @@
+/**
+ * Design-stage unit nodes — rows 1–6 of the OES-10.2 parity table, in the order and with the exact
+ * words `deriveSteps` used (frozen in tests/graph/fixtures/legacy-derive-steps.ts).
+ *
+ *   1 unit.no-source         no spec and no viewpoint → blocked; cuts BEFORE even `sungen update`
+ *   2 unit.assets-drift      AI assets from another build → `sungen update` (first, it voids the rest)
+ *   3 unit.viewpoint-missing no test-viewpoint.md → blocked, does not cut
+ *   4 unit.flow-contract     a flow without flow-contract.yaml → blocked, cuts
+ *   5 unit.no-scenarios      zero scenarios → create-test, cuts
+ *   6 unit.flow-inventory    a flow contract without `flows:` → add it, re-audit
+ */
+import { ALL_KINDS, UnitNodeDecl, unitKindDir } from '../node-decl';
+import { updateChannelFlag } from '../../cli/project-sungen-invocation';
+
+const design = (unit: string): string => `/sungen:create-test ${unit}`;
+
+export const UNIT_DESIGN_NODES: readonly UnitNodeDecl[] = [
+  {
+    id: 'unit.no-source', title: 'Write a source to generate from', actor: 'human', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: [], blocking: true, rank: 10, gates: [], produces: ['requirements/spec.md'],
+    active: () => true,
+    satisfied: (s) => s.hasSpec || s.hasViewpoint,
+    step: (s) => ({
+      kind: 'blocked',
+      command: `write qa/${unitKindDir(s.kind)}/${s.unit}/requirements/spec.md`,
+      because: 'the unit has neither a spec nor a test-viewpoint, so there is nothing to generate FROM — generation without a source invents behaviour',
+    }),
+  },
+  {
+    // Stale AI assets come FIRST: a HARD RULE added to `create-test` reaches nobody until `sungen update`
+    // runs, and upgrading the package alone does not refresh them (#620).
+    id: 'unit.assets-drift', title: 'Refresh the AI commands and skills', actor: 'ai', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.no-source'], blocking: false, rank: 20, gates: [], produces: ['.claude/', '.github/', '.agents/'],
+    active: () => true,
+    satisfied: (s) => !s.assetsDrift,
+    step: (s) => ({
+      kind: 'do',
+      command: `sungen update${updateChannelFlag(s.assetsDrift!.runningVersion)}`,   // keep the channel (#939)
+      because: `this project's AI commands/skills were written by sungen ${s.assetsDrift!.recordedVersion} and you are running ${s.assetsDrift!.runningVersion} — upgrading the package does NOT refresh them, so any rule added since ${s.assetsDrift!.recordedVersion} is not in effect for the next run`,
+    }),
+  },
+  {
+    // The yardstick `atomicLedger` and `traceability` are measured against; it can go missing from a
+    // unit that already HAS a spec, which unit.no-source never sees.
+    id: 'unit.viewpoint-missing', title: 'Restore the test viewpoint', actor: 'human', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.no-source'], blocking: false, rank: 30, gates: [], produces: ['requirements/test-viewpoint.md'],
+    active: () => true,
+    satisfied: (s) => s.hasViewpoint,
+    step: (s) => ({
+      kind: 'blocked',
+      command: s.kind === 'flow'
+        ? `sungen add-flow --flow ${s.unit} --path <start-url>    # repairs the missing scaffold; never overwrites`
+        : `write qa/screens/${s.unit}/requirements/test-viewpoint.md`,
+      because: 'requirements/test-viewpoint.md is missing — it is the yardstick `atomicLedger` and `traceability` are measured against, and four sensors read it, so the audit reports VIEWPOINT-MISSING and those axes are excluded. A flow contract does not substitute: it declares the use case, the viewpoint declares the claims',
+    }),
+  },
+  {
+    id: 'unit.flow-contract', title: 'Author the flow contract', actor: 'human', granularity: 'unit',
+    appliesTo: ['flow'], requires: ['unit.no-source'], blocking: true, rank: 40, gates: [], produces: ['requirements/flow-contract.yaml'],
+    active: () => true,
+    satisfied: (s) => s.hasContract,
+    step: (s) => ({
+      kind: 'blocked',
+      command: `author requirements/flow-contract.yaml, then ${design(s.unit)}`,
+      because: 'a flow with no contract is scored as a generic screen against page-type themes a journey cannot have (FLOW-CONTRACT-MISSING)',
+    }),
+  },
+  {
+    id: 'unit.no-scenarios', title: 'Generate the scenarios', actor: 'ai', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.no-source', 'unit.flow-contract'], blocking: true, rank: 50,
+    gates: ['journey.phase-create'], produces: ['features/<unit>.feature'],
+    active: () => true,
+    satisfied: (s) => s.scenarioCount !== 0,
+    step: (s) => ({ kind: 'do', command: design(s.unit), because: 'no scenarios exist yet' }),
+  },
+  {
+    // Without the inventory, coverage is per PHASE, and a phase counts as covered once one scenario
+    // carries it — so the number cannot show a missing flow.
+    id: 'unit.flow-inventory', title: 'Declare the flow inventory', actor: 'ai', granularity: 'unit',
+    appliesTo: ['flow'], requires: ['unit.no-scenarios'], blocking: false, rank: 60, gates: [], produces: ['requirements/flow-contract.yaml'],
+    active: () => true,
+    satisfied: (s) => s.hasFlowInventory,
+    step: (s) => ({
+      kind: 'do',
+      command: `add \`flows:\` to requirements/flow-contract.yaml, then sungen audit --screen ${s.unit}`,
+      because: 'without the inventory, coverage is measured per PHASE — and a phase counts as covered as soon as one scenario carries it, so the number cannot tell you a flow is missing',
+    }),
+  },
+];

package/src/graph/nodes/unit-execution-nodes.ts

@@ -0,0 +1,77 @@
+/**
+ * Execution-stage unit nodes — rows 11–15 (+13b from phase 01) of the OES-10.2 parity table, with the
+ * exact words of the frozen oracle.
+ *
+ *   11  unit.selectors  non-api, no selectors or a placeholder file → run-test, cuts
+ *   12  unit.compile    not compiled → `sungen generate`, cuts
+ *   13  unit.run        never run → run-test, cuts
+ *   13b unit.triage     results with failures → `sungen triage`, before delivery, does not cut —
+ *                       with test-case states it keeps only the reds no case accounts for; tc.triage
+ *                       takes the rest (phase 05)
+ *   14  unit.deliver    no deliverable → delivery
+ *   15  unit.extend     always → optional create-test (the end of the path)
+ */
+import { ALL_KINDS, UnitNodeDecl } from '../node-decl';
+import { attributedReds, unattributedReds } from './test-case-nodes';
+
+const TRIAGE_TAIL = 'classify each (known defect, test defect, environment, product candidate) before exporting or extending: an unexplained red in the deliverable is a finding nobody has judged';
+
+export const UNIT_EXECUTION_NODES: readonly UnitNodeDecl[] = [
+  {
+    // A scaffolded selector file exists but resolves nothing; treating it as done makes a run look further along.
+    id: 'unit.selectors', title: 'Generate selectors from the live page', actor: 'ai', granularity: 'unit',
+    appliesTo: ['screen', 'flow'], requires: ['unit.gate-fail'], blocking: true, rank: 110, gates: [], produces: ['selectors/<unit>.yaml'],
+    active: () => true,
+    satisfied: (s) => s.hasSelectors && !s.selectorsArePlaceholder,
+    step: (s) => ({
+      kind: 'do',
+      command: `/sungen:run-test ${s.unit}`,
+      because: s.hasSelectors
+        ? 'the selector file is still a placeholder, so nothing resolves against a live page'
+        : 'no selectors exist yet — run-test generates them from the live page, compiles and auto-fixes',
+    }),
+  },
+  {
+    id: 'unit.compile', title: 'Compile the suite', actor: 'deterministic', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.gate-fail', 'unit.selectors'], blocking: true, rank: 120, gates: [], produces: ['specs/generated/<unit>/'],
+    active: () => true,
+    satisfied: (s) => s.compiled,
+    step: (s) => ({ kind: 'do', command: `sungen generate --${s.kind === 'flow' ? 'flow' : 'screen'} ${s.unit}`, because: 'the suite has not been compiled to a spec yet' }),
+  },
+  {
+    id: 'unit.run', title: 'Run the compiled suite', actor: 'ai', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.compile'], blocking: true, rank: 130, gates: ['journey.phase-run'], produces: ['specs/generated/<unit>/<unit>-test-result.json'],
+    active: () => true,
+    satisfied: (s) => s.hasResults,
+    step: (s) => ({ kind: 'do', command: `/sungen:run-test ${s.unit}`, because: 'the compiled spec has never been run, so every case is Pending' }),
+  },
+  {
+    // Reds are classified before they are exported or built on; the steps after it still follow.
+    id: 'unit.triage', title: 'Classify the failed scenarios', actor: 'deterministic', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.run'], blocking: false, rank: 135, gates: [], produces: ['.sungen/triage/<unit>.json'],
+    active: () => true,
+    satisfied: (s) => !(unattributedReds(s) > 0),
+    step: (s) => ({
+      kind: 'do',
+      command: `sungen triage --${s.kind === 'api' ? 'api' : 'screen'} ${s.unit}`,
+      because: attributedReds(s) > 0
+        ? `${unattributedReds(s)} failed result(s) in the latest run match no test case of the .feature (a renamed scenario, an @cases row or a title the .feature does not show) — ${TRIAGE_TAIL}`
+        : `${s.failedCount} scenario(s) failed in the latest run — ${TRIAGE_TAIL}`,
+    }),
+  },
+  {
+    id: 'unit.deliver', title: 'Export the deliverable', actor: 'ai', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.run'], blocking: false, rank: 140, gates: ['journey.phase-deliver', 'decision.in-run'],
+    produces: ['qa/deliverables/<unit>-testcases.xlsx'],
+    active: () => true,
+    satisfied: (s) => s.hasDeliverable,
+    step: (s) => ({ kind: 'do', command: `/sungen:delivery ${s.unit}`, because: 'results exist but have not been exported to the Test Case & Coverage Matrix' }),
+  },
+  {
+    id: 'unit.extend', title: 'Extend coverage', actor: 'ai', granularity: 'unit',
+    appliesTo: ALL_KINDS, requires: ['unit.run'], blocking: false, rank: 150, gates: [], produces: ['features/<unit>.feature'],
+    active: () => true,
+    satisfied: () => false,
+    step: (s) => ({ kind: 'optional', command: `/sungen:create-test ${s.unit}`, because: 'extend coverage — the next tier, or the flows the inventory still lists as pending' }),
+  },
+];

package/src/graph/test-case-identity.ts

@@ -0,0 +1,75 @@
+/**
+ * Which test cases a unit holds, read off its `.feature` files (DOS-11.1): one per runnable scenario
+ * — `@steps` bases, hooks and the scaffold sample are not test cases (as in delivery).
+ *
+ *   id      the scenario's VP-id (the exporters' format-tolerant SCENARIO_ID); without one,
+ *           `T-<hash8>` of file + title, flagged `unstableId` (a rename changes it)
+ *   lines   the scenario block, its tag lines included, up to the line before the next block
+ *   mocked  verified against a declared mock (`@mock` / `@network`, or a mock step) — Pass (Mocked)
+ */
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { isHookScenario, isSampleScaffoldScenario, isStepsBaseScenario, parseFeatureMetadata, splitVpAndName } from '../exporters/feature-parser';
+import { featureFilesFor } from '../harness/unit-paths';
+
+export interface FeatureCase {
+  id: string;
+  unstableId?: true;
+  title: string;
+  absFile: string;
+  /** The feature's basename — result files are named after it. */
+  featureBase: string;
+  lines: [number, number];
+  tags: string[];
+  mocked: boolean;
+}
+
+const SCENARIO_LINE = /^\s*Scenario(?: Outline)?:\s*(.*?)\s*$/;
+const ENDS_BLOCK = /^\s*(?:Rule|Background):/;
+/** Blank lines and the next block's section marker are not part of a scenario. */
+const TRAILER = /^\s*(?:#\s*-{2,}\s*Section:.*)?$/i;
+/** Literal twin of the mock grammar (exporters/matrix/build.ts detectMocked), without loading drivers. */
+const MOCK_TAGS = ['@mock', '@network'];
+const MOCK_STEP = /\[[^\]]+\]\s+mock\s+(?:is\s+active|called\s+(?:\{\{[^}]+\}\}|\d+)\s+times?)\b/i;
+
+/** 1-based [first, last] line of every Scenario block, in file order. */
+function scenarioBlocks(lines: string[]): Array<{ title: string; range: [number, number] }> {
+  const starts: Array<{ title: string; first: number; at: number }> = [];
+  lines.forEach((line, i) => {
+    const m = line.match(SCENARIO_LINE);
+    if (!m) return;
+    let first = i;
+    while (first > 0 && /^\s*@/.test(lines[first - 1])) first--;
+    starts.push({ title: m[1], first, at: i });
+  });
+  return starts.map((b, k) => {
+    let end = k + 1 < starts.length ? starts[k + 1].first : lines.length;   // exclusive
+    for (let j = b.at + 1; j < end; j++) if (ENDS_BLOCK.test(lines[j])) { end = j; break; }
+    while (end - 1 > b.at && TRAILER.test(lines[end - 1])) end--;
+    return { title: b.title, range: [b.first + 1, end] as [number, number] };
+  });
+}
+
+export function featureCases(unitDir: string, unit: string): FeatureCase[] {
+  const out: FeatureCase[] = [];
+  for (const absFile of featureFilesFor(unitDir, unit).filter((f) => fs.existsSync(f))) {
+    const meta = parseFeatureMetadata(absFile);
+    const blocks = scenarioBlocks(fs.readFileSync(absFile, 'utf8').split(/\r?\n/));
+    const used = new Set<number>();
+    for (const sc of meta.scenarios) {
+      const at = blocks.findIndex((b, i) => !used.has(i) && b.title === sc.name);
+      if (at >= 0) used.add(at);
+      if (isStepsBaseScenario(sc) || isHookScenario(sc) || isSampleScaffoldScenario(sc)) continue;
+      const vpId = splitVpAndName(sc.name).vpId;
+      const rel = path.basename(absFile);
+      const id = vpId ?? `T-${createHash('sha1').update(`${rel}\n${sc.name}`).digest('hex').slice(0, 8)}`;
+      out.push({
+        id, ...(vpId ? {} : { unstableId: true as const }), title: sc.name, absFile, featureBase: path.basename(absFile, '.feature'),
+        lines: at >= 0 ? blocks[at].range : [1, 1], tags: sc.tags,
+        mocked: sc.tags.some((t) => MOCK_TAGS.some((m) => t === m || t.startsWith(`${m}:`))) || sc.orderedSteps.some((s) => MOCK_STEP.test(s.text)),
+      });
+    }
+  }
+  return out;
+}

package/src/graph/test-case-results.ts

@@ -0,0 +1,90 @@
+/**
+ * What has happened to each test case: its result, whether that result still describes the
+ * scenario, and the triage verdict on it — all read off files that already exist (DOS-11.1).
+ *
+ *   result   final attempt across every result file of its feature (`<base>-test-result[.<os>][.<env>].json`)
+ *            and every `@cases` row (`<title> — <label>`): any red → failed; else any pass → passed
+ *   stale    the run manifest (`sungen changed`) selects the scenario: its steps/tags, a selector or a
+ *            test-data key it uses, or a project input changed since the recorded run
+ *   triage   the rows of `.sungen/triage/<unit>.json` for the case, only when that triage is not
+ *            older than the case's result files (a re-run voids it)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadPlaywrightReport } from '../exporters/playwright-report-parser';
+import type { PlaywrightResult } from '../exporters/types';
+import { buildRunManifest, readRunManifest, selectChanged } from '../harness/run-manifest';
+import { readTriageReport } from '../harness/triage-unit';
+import type { TriageClass } from '../harness/triage';
+import type { FeatureCase } from './test-case-identity';
+import type { TestCaseResult, TestCaseState } from './test-case-state-shape';
+import { generatedDirs, RESULT_FILE } from './unit-artifact-probes';
+
+const RED = new Set<PlaywrightResult['status']>(['failed', 'timedOut', 'interrupted']);
+/** The class a case shows when its rows disagree: what needs a human first. */
+const TRIAGE_PRECEDENCE: TriageClass[] = ['product-candidate', 'unclassified', 'test-defect', 'environment', 'known-defect', 'blocked-capability', 'flaky'];
+
+export interface CaseOutcome { result: TestCaseResult; failedResults: number; resultFiles: string[]; stale?: string; triage?: TestCaseState['triage'] }
+
+const ownsTitle = (key: string, title: string): boolean => key === title || key.endsWith(` > ${title}`)
+  || key.startsWith(`${title} — `) || key.includes(` > ${title} — `);
+const rowOwns = (scenario: string, title: string): boolean => scenario === title || scenario.startsWith(`${title} — `);
+const mtime = (f: string): number => { try { return fs.statSync(f).mtimeMs; } catch { return 0; } };
+
+/** Every result file of each feature, with its parsed report (read once per file). */
+function resultsByFeature(projectRoot: string, unit: string, unitId: string): Map<string, Array<{ file: string; report: Map<string, PlaywrightResult> }>> {
+  const dirs = [...new Set([...generatedDirs(projectRoot, unit), path.join(projectRoot, 'specs', 'generated', unitId)])];
+  const out = new Map<string, Array<{ file: string; report: Map<string, PlaywrightResult> }>>();
+  for (const d of dirs) {
+    let names: string[] = [];
+    try { names = fs.readdirSync(d).filter((f) => RESULT_FILE.test(f)).sort(); } catch { continue; }
+    for (const name of names) {
+      const report = loadPlaywrightReport(path.join(d, name));
+      if (!report) continue;                               // unreadable = unknown, never red
+      const base = name.replace(RESULT_FILE, '');
+      out.set(base, [...(out.get(base) ?? []), { file: path.join(d, name), report }]);
+    }
+  }
+  return out;
+}
+
+/** Scenarios `sungen changed` would re-run. No baseline, or one that cannot be read, claims nothing. */
+function staleReasons(projectRoot: string, unitDir: string, unit: string): Record<string, string> {
+  const before = readRunManifest(projectRoot, unit);
+  if (!before || typeof before.scenarios !== 'object' || !before.selectorKeys || !before.dataKeys) return {};
+  try { return selectChanged(before, buildRunManifest(projectRoot, unitDir, unit)).reasons; } catch { return {}; }
+}
+
+/** The triage rows, shape-checked: the report is a file anyone can edit. */
+function triageRows(projectRoot: string, unitId: string): { at: number; rows: Array<{ scenario: string; class: TriageClass; ruleId: string }> } {
+  const report = readTriageReport(projectRoot, unitId);
+  const rows = Array.isArray(report?.rows)
+    ? report!.rows.filter((r) => r && typeof r.scenario === 'string' && TRIAGE_PRECEDENCE.includes(r.class)) : [];
+  return { at: report && typeof report.generatedAt === 'string' ? Date.parse(report.generatedAt) : NaN, rows };
+}
+
+export function caseOutcomes(projectRoot: string, unitDir: string, unit: string, unitId: string, cases: FeatureCase[]): CaseOutcome[] {
+  const byFeature = resultsByFeature(projectRoot, unit, unitId);
+  const stale = staleReasons(projectRoot, unitDir, unit);
+  const triage = triageRows(projectRoot, unitId);
+  return cases.map((c) => {
+    const statuses: PlaywrightResult['status'][] = [];
+    const files: string[] = [];
+    for (const { file, report } of byFeature.get(c.featureBase) ?? []) {
+      const mine = [...report.entries()].filter(([key]) => ownsTitle(key, c.title)).map(([, r]) => r.status);
+      if (mine.length) { statuses.push(...mine); files.push(file); }
+    }
+    const result: TestCaseResult = statuses.some((s) => RED.has(s)) ? 'failed'
+      : statuses.includes('passed') ? 'passed' : statuses.includes('skipped') ? 'skipped' : 'never-run';
+    const out: CaseOutcome = {
+      result, failedResults: statuses.filter((st) => RED.has(st)).length,
+      resultFiles: files.map((f) => path.relative(projectRoot, f).split(path.sep).join('/')),
+    };
+    if (result !== 'never-run' && stale[c.title]) out.stale = stale[c.title];
+    const current = !Number.isNaN(triage.at) && files.every((f) => mtime(f) <= triage.at);
+    const rows = current ? triage.rows.filter((r) => rowOwns(r.scenario, c.title)) : [];
+    const worst = TRIAGE_PRECEDENCE.find((cls) => rows.some((r) => r.class === cls));
+    if (worst) out.triage = { class: worst, ruleId: rows.find((r) => r.class === worst)!.ruleId };
+    return out;
+  });
+}

package/src/graph/test-case-satisfied.ts

@@ -0,0 +1,55 @@
+/**
+ * When a test case generates work, and which (DOS-11.2).
+ *
+ *   exempt — satisfied, no work: `@manual` (a human executes it), `@requires:<cap>` (waits on a
+ *            capability the QA has not enabled), `@known-defect` (a recorded product defect),
+ *            `@deferred:flow` (owned and automated by its flow — the contract excludes it too),
+ *            triage `blocked-capability`. Any other `@deferred:*` is NOT exempt.
+ *   trigger — what the case needs otherwise, first match wins:
+ *            never run → run · result older than the scenario (run manifest) → rerun-stale ·
+ *            red with no current triage, or left `unclassified` by it → triage (a classification
+ *            is still owed) · triaged product-candidate → a QA decision
+ * A pass — Pass (Mocked) included — needs nothing. A red triaged test-defect / environment has been
+ * judged; the triage report and the deliverable carry it (no P0 node — a P1 follow-up).
+ */
+import type { TestCaseState } from './test-case-state-shape';
+
+export type TestCaseExemption = 'manual' | 'requires' | 'known-defect' | 'deferred' | 'blocked-capability';
+export type TestCaseNeed = 'run' | 'rerun-stale' | 'triage' | 'product-candidate';
+
+const tagged = (tc: TestCaseState, tag: string): boolean => tc.tags.some((t) => t === tag || t.startsWith(`${tag}:`));
+
+/** Why the case is satisfied regardless of its result, or null when it is not exempt. */
+export function exemptionOf(tc: TestCaseState): TestCaseExemption | null {
+  if (tagged(tc, '@manual')) return 'manual';
+  if (tc.tags.some((t) => t.startsWith('@requires:'))) return 'requires';
+  if (tagged(tc, '@known-defect')) return 'known-defect';
+  if (tc.tags.some((t) => /^@deferred:flow$/i.test(t))) return 'deferred';
+  if (tc.triage?.class === 'blocked-capability') return 'blocked-capability';
+  return null;
+}
+
+/** What the case would need if it were not exempt. */
+export function triggerOf(tc: TestCaseState): TestCaseNeed | null {
+  if (tc.result === 'never-run') return 'run';
+  if (tc.stale) return 'rerun-stale';
+  if (tc.result === 'failed') {
+    if (!tc.triage || tc.triage.class === 'unclassified') return 'triage';
+    if (tc.triage.class === 'product-candidate') return 'product-candidate';
+  }
+  return null;
+}
+
+export function testCaseNeed(tc: TestCaseState): TestCaseNeed | null {
+  return exemptionOf(tc) ? null : triggerOf(tc);
+}
+
+/** One word for `--case`: why the case asks for nothing, or what it needs. */
+export function testCaseStatusLabel(tc: TestCaseState): string {
+  const exempt = exemptionOf(tc);
+  if (exempt) return `satisfied (${exempt})`;
+  const need = triggerOf(tc);
+  if (need) return `needs ${need}`;
+  if (tc.result === 'passed') return tc.mocked ? 'satisfied (Pass (Mocked))' : 'satisfied (passed)';
+  return tc.triage ? `satisfied (triaged ${tc.triage.class})` : `satisfied (${tc.result})`;
+}

package/src/graph/test-case-state-shape.ts

@@ -0,0 +1,62 @@
+/**
+ * The shape of one test case's state (DOS-11.1) — facts read off files that already exist, never a
+ * stored record. `testCaseStates()` (test-case-states.ts) builds it; `test-case-satisfied.ts` decides
+ * whether it generates work; the test-case nodes turn the unsatisfied ones into steps.
+ */
+import type { ScenarioClass } from '../contract/contract-schema';
+import type { TriageClass } from '../harness/triage';
+
+/** DOS-12.1 confidence labels: EXTRACTED 0.9–1.0 · INFERRED 0.5–0.89 · AMBIGUOUS < 0.5. */
+export type ConfidenceLabel = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
+
+/** An audit finding pinned to the scenario it names, in the shared trace vocabulary (DOS-12.1). */
+export interface LocatedFinding {
+  code: string;
+  text: string;
+  /** `repo@SHA:path#Lx-Ly` — SHA is `worktree` when git is absent or the file differs from HEAD. */
+  citation: string;
+  confidence: { label: ConfidenceLabel; score: number };
+}
+
+export type TestCaseResult = 'passed' | 'failed' | 'skipped' | 'never-run';
+
+/** The case in the contract verdict `sungen contract check` rebuilds (DOS-14.4–14.6) — attached on read. */
+export interface TestCaseContract {
+  class: ScenarioClass;
+  /** Its first finding, as the check prints it. */
+  detail?: string;
+  /** A trace step acts on a target whose identity is only `low` — `contract check --trace` can resolve it. */
+  lowIdentity?: true;
+  /** Its lock entry is not what QA approved and committed (contract.lock-uncommitted). */
+  uncommitted?: true;
+}
+
+export interface TestCaseState {
+  /** The scenario's VP-id; `T-<hash8>` of file + title when it carries none (`unstableId`). */
+  id: string;
+  unstableId?: true;
+  title: string;
+  /** Project-relative, `/`-separated path of the `.feature`. */
+  file: string;
+  /** 1-based first and last line of the scenario block (its tags included). */
+  lines: [number, number];
+  /** Feature and scenario tags. */
+  tags: string[];
+  /** Final-attempt outcome across every result file and variant: any red is `failed`. */
+  result: TestCaseResult;
+  /** Red final attempts this case accounts for — one per result file, variant and `@cases` row. */
+  failedResults?: number;
+  /** Verified against a declared mock — a pass is Pass (Mocked), not Pass (Real). */
+  mocked: boolean;
+  /** Result files that carry this case, project-relative. */
+  resultFiles: string[];
+  /** Set when the scenario changed after the run that produced its result (run manifest). */
+  stale?: string;
+  /** The current `sungen triage` row for a red case — absent when triage has not judged this result. */
+  triage?: { class: TriageClass; ruleId: string };
+  /** Spec anchors the case was generated from (manifest), and whether they moved since. */
+  anchors: Array<{ anchor: string; change: 'keep' | 'regenerate' | 'retire' | 'unknown' }>;
+  findings: LocatedFinding[];
+  /** Its class in the rebuilt contract verdict; absent outside the contract (@manual, no scenario id) or unread. */
+  contract?: TestCaseContract;
+}

package/src/graph/test-case-states.ts

@@ -0,0 +1,84 @@
+/**
+ * `testCaseStates(projectRoot, unit)` — the state of every test case of a unit, a PURE function of
+ * files that already exist, evaluated whenever it is read (DOS-11.1, red-team #9): no state file, no
+ * facet registry, nothing written. A step interrupted yesterday is recomputed today, not remembered.
+ *
+ *   identity   .feature                       test-case-identity.ts
+ *   outcome    results · run manifest · triage test-case-results.ts
+ *   anchors    .sungen/manifest/<unit>.json — the spec anchors each scenario came from, and their drift
+ *   findings   the audit's findings, located on the case they name (locate-finding.ts, DOS-12.1)
+ *
+ * The audit's findings are taken only from a report that counts (verifyAuditReport): a stale or
+ * untrusted report locates nothing. A caller that already verified the report passes its findings.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { resolveUnitCandidates } from '../cli/resolve-unit';
+import { auditCounts, verifyAuditReport } from '../harness/gates/audit-report-verification';
+import { diffManifest, Manifest } from '../harness/manifest';
+import { reportSlug } from '../harness/unit-paths';
+import { gitCitationContext, locateFindings } from './locate-finding';
+import { caseOutcomes } from './test-case-results';
+import { featureCases } from './test-case-identity';
+import type { TestCaseState } from './test-case-state-shape';
+
+export interface TestCaseStateOptions {
+  /** The unit's directory, when the caller has resolved it already. */
+  unitDir?: string;
+  /** The findings of an audit report the caller verified; read through verifyAuditReport otherwise. */
+  auditFindings?: string[];
+}
+
+type Anchor = TestCaseState['anchors'][number];
+
+/** scenario title → its anchors, with the change `diffManifest` reports (unknown when it cannot say). */
+function anchorsByScenario(projectRoot: string, unitDir: string, unit: string): Map<string, Anchor[]> {
+  const out = new Map<string, Anchor[]>();
+  let manifest: Manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(projectRoot, '.sungen', 'manifest', `${reportSlug(unit)}.json`), 'utf8'));
+  } catch { return out; }
+  if (!manifest || !Array.isArray(manifest.entries)) return out;
+  let changes: Map<string, Anchor['change']> = new Map();
+  try {
+    changes = new Map(diffManifest(unitDir, unit, manifest).scenarios.map((s) => [`${s.scenario}\n${s.section}`, s.change]));
+  } catch { /* a pending migration or an unreadable spec — the drift is unknown */ }
+  for (const e of manifest.entries) {
+    if (!e || typeof e.scenario !== 'string' || typeof e.section !== 'string') continue;
+    out.set(e.scenario, [...(out.get(e.scenario) ?? []), { anchor: e.section, change: changes.get(`${e.scenario}\n${e.section}`) ?? 'unknown' }]);
+  }
+  return out;
+}
+
+function verifiedFindings(projectRoot: string, unit: string): string[] {
+  const v = verifyAuditReport(projectRoot, unit);
+  const findings = auditCounts(v) ? v.report?.findings : undefined;
+  return Array.isArray(findings) ? findings.filter((f): f is string => typeof f === 'string') : [];
+}
+
+export function testCaseStates(projectRoot: string, unit: string, opts: TestCaseStateOptions = {}): TestCaseState[] {
+  const found = resolveUnitCandidates(unit, projectRoot);
+  const unitDir = opts.unitDir ?? (found.length === 1 ? found[0].dir : undefined);
+  if (!unitDir || !fs.existsSync(unitDir)) return [];
+  const unitId = found.find((f) => f.dir === unitDir)?.unitId ?? unit;
+  const cases = featureCases(unitDir, unit);
+  if (!cases.length) return [];
+  const outcomes = caseOutcomes(projectRoot, unitDir, unit, unitId, cases);
+  const anchors = anchorsByScenario(projectRoot, unitDir, unit);
+  const findings = opts.auditFindings ?? verifiedFindings(projectRoot, unit);
+  const located = findings.length
+    ? locateFindings(findings, cases, gitCitationContext(projectRoot, [...new Set(cases.map((c) => c.absFile))]))
+    : new Map();
+  return cases.map((c, i) => ({
+    id: c.id,
+    ...(c.unstableId ? { unstableId: true as const } : {}),
+    title: c.title,
+    file: path.relative(projectRoot, c.absFile).split(path.sep).join('/'),
+    lines: c.lines,
+    tags: c.tags,
+    mocked: c.mocked,
+    ...outcomes[i],
+    anchors: anchors.get(c.title) ?? [],
+    findings: located.get(i) ?? [],
+  }));
+}

package/src/graph/unit-artifact-probes.ts

@@ -0,0 +1,77 @@
+/**
+ * What a unit holds on disk, probed cheaply for `readUnitState` and `testCaseStates` (moved out of
+ * harness/next-step.ts unchanged). Every path here is legitimately absent at some point in a unit's
+ * life — the resolver exists to report exactly that — so nothing throws on a missing file.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { featureFilesFor } from '../harness/unit-paths';
+import { readTextFile } from '../harness/read-text';
+import { loadPlaywrightReport } from '../exporters/playwright-report-parser';
+
+/** `<f>-test-result[.<os>][.<env>].json` — a mobile run writes the OS into the name, an env run the env (#868). */
+export const RESULT_FILE = /-test-result(?:\.[^.]+)*\.json$/;
+
+export const readIfExists = (p: string): string => (fs.existsSync(p) ? readTextFile(p) : '');
+
+export function countScenarios(unitDir: string, unit: string): number {
+  let n = 0;
+  for (const f of featureFilesFor(unitDir, unit)) {
+    n += (readIfExists(f).match(/^\s*Scenario(?: Outline)?:/gm) ?? []).length;
+  }
+  return n;
+}
+
+/**
+ * Does the selector text resolve at least one element? A scaffold resolves none: the web one holds
+ * only the `page` route, the mobile one only header comments. Matching the WORD "placeholder" was
+ * wrong both ways (#868): it flagged a real file whose key names an input's placeholder text, and
+ * missed both scaffolds, which never contain it.
+ */
+export function hasResolvedSelector(selectorText: string): boolean {
+  let doc: unknown;
+  try { doc = parseYaml(selectorText); } catch { return selectorText.trim().length >= 40; }
+  if (!doc || typeof doc !== 'object') return false;
+  // A real cell, not a marker left to be filled in. Numbers count (an id or index can be numeric).
+  const real = (v: unknown): boolean => (typeof v === 'string' || typeof v === 'number')
+    && String(v).trim() !== '' && !/^(?:todo|tbd|placeholder|replace me)$/i.test(String(v).trim());
+  return Object.values(doc as Record<string, unknown>).some((e) => {
+    if (!e || typeof e !== 'object') return false;
+    const { type, value, name, locator } = e as { type?: unknown; value?: unknown; name?: unknown; locator?: unknown };
+    // Every SelectorEntry shape: a CSS `locator`, or a non-page `type` with a value or a role name.
+    return real(locator) || (typeof type === 'string' && type !== 'page' && (real(value) || real(name)));
+  });
+}
+
+/** Where a unit's compiled spec and result files live. */
+export function generatedDirs(projectRoot: string, unit: string): string[] {
+  return [
+    path.join(projectRoot, 'specs', 'generated', 'flows', unit),
+    path.join(projectRoot, 'specs', 'generated', unit),
+  ];
+}
+
+export function isCompiled(projectRoot: string, unit: string): boolean {
+  return generatedDirs(projectRoot, unit).some((d) => {
+    try { return fs.readdirSync(d).some((f) => f.endsWith('.spec.ts')); } catch { return false; }
+  });
+}
+
+export function unitResultFiles(projectRoot: string, unit: string): string[] {
+  return generatedDirs(projectRoot, unit).flatMap((d) => {
+    try { return fs.readdirSync(d).filter((f) => RESULT_FILE.test(f)).map((f) => path.join(d, f)); } catch { return []; }
+  });
+}
+
+/** Final attempts that failed across the result files. An unreadable report counts nothing: "unknown" is never red. */
+export function countFailedResults(resultFiles: string[]): number {
+  return resultFiles.reduce((n, f) => n + [...(loadPlaywrightReport(f)?.values() ?? [])]
+    .filter((r) => r.status === 'failed' || r.status === 'timedOut' || r.status === 'interrupted').length, 0);
+}
+
+export function hasDeliverableFor(projectRoot: string, slug: string): boolean {
+  try {
+    return fs.readdirSync(path.join(projectRoot, 'qa', 'deliverables')).some((f) => f.startsWith(`${slug}-`));
+  } catch { return false; }                                    // nothing exported yet
+}