@sun-asterisk/sungen 3.2.16-beta.7 → 3.2.17

package/src/exporters/matrix/build.ts

@@ -1,503 +0,0 @@
-/**
- * Build the matrix model: derive atomic coverage variants from the merged
- * feature/spec view, assemble delivery items per the Delivery Map, attach
- * per-variant Playwright results, and roll parents up (derived only — Gate F
- * is structural: there is no independent parent result input).
- */
-
-import { FeatureMetadata, PlaywrightResult } from '../types';
-import { MergedScenario } from '../scenario-merger';
-import {
-  extractAuthRole,
-  extractPriority,
-  extractTestcaseType,
-  splitVpAndName,
-} from '../feature-parser';
-import { getCasesDatasetRows, resolveResultVariants } from '../result-variants';
-import { classifyManualComments, renderAction, renderExpected, renderPrecondition, renderSetupInstruction } from './wording';
-import { scenarioFingerprint, combinedFingerprint, mapContentFingerprint } from './fingerprint';
-import {
-  CoverageVariant,
-  DeliveryItem,
-  DeliveryMap,
-  ItemResult,
-  VariantState,
-  MatrixDisposition,
-  MatrixLayer,
-  MatrixModel,
-  RequirementCoverage,
-  MAX_VARIANTS_PER_ITEM,
-} from './types';
-import { runGates } from './gates';
-
-// ---------------------------------------------------------------------------
-// Variant derivation
-// ---------------------------------------------------------------------------
-
-/** Collapse `{{var}}` placeholders so data values become parameters, not shape. */
-function normalizeShape(text: string): string {
-  return text.replace(/\{\{[^}]*\}\}/g, '{{*}}').replace(/\s+/g, ' ').trim();
-}
-
-function deriveLayers(tags: string[]): MatrixLayer[] {
-  const layers = new Set<MatrixLayer>(['ui']);
-  if (tags.some((t) => t === '@api' || t.startsWith('@api:') || t === '@requires:api')) layers.add('api');
-  if (tags.some((t) => t.startsWith('@query') || t === '@requires:db')) layers.add('db');
-  return Array.from(layers);
-}
-
-/** 'simple' single G*→W*→T* pass; 'sequence' when the flow re-enters Given/When after a Then. */
-function deriveProcedureProfile(m: MergedScenario): 'simple' | 'sequence' | 'manual' {
-  if (extractTestcaseType(m.feature.tags) === 'Manual') return 'manual';
-  const order = m.feature.orderedSteps.map((s) => s.bucket);
-  let seenThen = false;
-  for (const bucket of order) {
-    if (bucket === 'then') seenThen = true;
-    else if (seenThen) return 'sequence'; // action/setup after an assertion → ordered flow
-  }
-  return 'simple';
-}
-
-function manualReason(tags: string[]): string | undefined {
-  const t = tags.find((x) => x.startsWith('@manual:'));
-  return t ? t.slice('@manual:'.length) : undefined;
-}
-
-/** Resolve `{{var}}` refs of a scenario into display `key: value` pairs. */
-function resolveDataPairs(
-  vars: string[],
-  testData: Record<string, string> | null,
-  row?: Record<string, unknown>,
-): string[] {
-  const pairs: string[] = [];
-  if (row) {
-    for (const [k, v] of Object.entries(row)) {
-      if (k.startsWith('__') || k === 'case' || k === 'name' || k === 'label') continue;
-      pairs.push(`${k}: ${displayValue(String(v))}`);
-    }
-  }
-  for (const v of vars) {
-    const val = row && v in row ? undefined : testData?.[v]; // row columns already listed
-    if (val !== undefined) pairs.push(`${v}: ${displayValue(val)}`);
-  }
-  return pairs;
-}
-
-export interface BuildInputs {
-  unit: string;
-  feature: FeatureMetadata;
-  merged: MergedScenario[];
-  testData: Record<string, string> | null;
-  results: Map<string, PlaywrightResult> | null;
-  map: DeliveryMap;
-  transformerVersion: string;
-  /** requirements/spec.md content — source of the requirement-id inventory (FR/TR/NFR). */
-  specText?: string;
-}
-
-/**
- * Derive every atomic coverage variant of the unit (one per scenario, or one per
- * `@cases` dataset row). Exported separately so the gates + the map-proposal
- * support tooling see the same universe the builder does.
- */
-export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' | 'testData' | 'results'>): CoverageVariant[] {
-  const { merged, results } = inputs;
-  // Test-data values may cross-reference other keys (email_padded: " {{valid_email}} ") —
-  // resolve one level so display cells never leak a template token (review B-04).
-  const testData = resolveCrossRefs(inputs.testData);
-  const variants: CoverageVariant[] = [];
-
-  for (const m of merged) {
-    const { vpId, category1 } = splitVpAndName(m.feature.name);
-    if (!vpId) continue; // Gate A reports it — no variant can be addressed without a VP-id
-    const tags = m.feature.tags;
-    const mode = extractTestcaseType(tags) === 'Manual' ? 'manual' : 'auto';
-    const authRole = extractAuthRole(tags);
-    const vpCategory = vpId.replace(/^VP-/, '').replace(/-\d+[a-zA-Z]?$/, '');
-    const procedureProfile = deriveProcedureProfile(m);
-
-    // Manual scenarios: the `# Tester verifies:` block is classified into structured
-    // fields — Setup → precondition (review B-02), Action → trigger, Observable →
-    // expected, Oracle → verification method. Labels never remain inside prose.
-    const manual = mode === 'manual' && m.feature.comments?.length
-      ? classifyManualComments(m.feature.comments)
-      : null;
-
-    // Raw (pre-wording) step texts — these feed shapes + Gate C, never the cells.
-    const rawTrigger = manual ? manual.actions : m.feature.rawWhenSteps;
-    const rawOracle = manual
-      ? (manual.expected.length > 0 ? manual.expected : m.feature.rawThenSteps)
-      : m.resolvedExpected.filter((s) => s.bucket === 'then').map((s) => s.text);
-
-    const preconditionProfile = [
-      authRole ?? '-',
-      m.feature.extendsName ?? '-',
-      ...m.feature.rawGivenSteps.map(normalizeShape),
-      ...(manual?.preconditions ?? []).map(normalizeShape),
-    ].join(' | ');
-    // Display precondition = auth state + Background Given (shared start state) +
-    // the scenario's own Given steps + manual Setup lines — deduplicated (a manual
-    // scenario often repeats the Background navigation as its own Given).
-    const precondition = Array.from(new Set([
-      ...(authRole ? [authRole === 'no-auth' ? 'The user is signed out.' : `The user is signed in as ${authRole}.`] : []),
-      ...inputs.feature.backgroundGivenSteps.map(renderPrecondition),
-      ...m.feature.rawGivenSteps.map(renderPrecondition),
-      ...(manual?.preconditions ?? []).map((t) => renderSetupInstruction(t)),
-    ]));
-
-    const base = {
-      vpId,
-      vpCategory,
-      priority: extractPriority(tags),
-      mode: mode as 'auto' | 'manual',
-      manualReason: manualReason(tags),
-      layers: deriveLayers(tags),
-      traces: tags.filter((t) => t.startsWith('@spec:')).map((t) => t.slice('@spec:'.length)),
-      triggerShape: rawTrigger.map(normalizeShape),
-      oracleShape: rawOracle.map(normalizeShape),
-      preconditionProfile,
-      precondition,
-      procedureProfile,
-      verification: manual?.verification.map((t) => sentenceOf(t)) ?? [],
-    };
-
-    /** Render the display cells for one data context (vars resolved first). */
-    const renderCells = (vars: Record<string, string>): { trigger: string[]; oracle: string[]; precondition: string[]; verification: string[] } => {
-      const sub = (s: string): string => substituteDisplayVars(s, vars);
-      const preconditionOut = precondition.map(sub);
-      const verificationOut = base.verification.map(sub);
-      if (procedureProfile === 'sequence' && !manual) {
-        // Ordered flow (review B-03): keep the event order — actions stay numbered in
-        // the trigger, mid-flow assertions render inline as "Verify:", and only the
-        // FINAL Then block becomes the expected result.
-        const steps = m.feature.orderedSteps;
-        let lastActionIdx = -1;
-        steps.forEach((s, i) => { if (s.bucket !== 'then') lastActionIdx = i; });
-        const trigger: string[] = [];
-        const oracle: string[] = [];
-        steps.forEach((s, i) => {
-          if (i > lastActionIdx) oracle.push(renderExpected(sub(s.text)));           // trailing Then block
-          else if (s.bucket === 'then') trigger.push(`Verify: ${renderExpected(sub(s.text))}`);
-          else if (s.bucket === 'when') trigger.push(renderAction(sub(s.text)));
-          // leading given steps already live in the precondition
-        });
-        return { trigger, oracle, precondition: preconditionOut, verification: verificationOut };
-      }
-      const trigger = rawTrigger.map((s) => renderAction(sub(s)));
-      const oracle = rawOracle.map((s) => renderExpected(sub(s)));
-      return {
-        // A pure-render check (Given + Then only) is checked on page load — say so
-        // in words instead of a placeholder token (review §10.3).
-        trigger: trigger.length > 0 ? trigger : ['No action — the state is checked on page load.'],
-        oracle,
-        precondition: preconditionOut,
-        verification: verificationOut,
-      };
-    };
-
-    const rows = getCasesDatasetRows(m, testData ?? undefined);
-    if (rows) {
-      // One variant per dataset row; results matched per row label by the shared resolver.
-      const resultVariants = resolveResultVariants(m, results ?? null, testData ?? undefined);
-      const resultByLabel = new Map(resultVariants.map((rv) => [rv.nameSuffix.replace(/^ — /, ''), rv.result]));
-      rows.forEach((row, i) => {
-        const label = String(row.case ?? row.name ?? row.label ?? `row ${i + 1}`);
-        const cells = renderCells({ ...(testData ?? {}), ...rowAsStrings(row) });
-        variants.push({
-          ...base,
-          ref: `${vpId}#${label}`,
-          caseLabel: label,
-          title: `${category1} — ${label}`,
-          condition: label,
-          data: resolveDataPairs(m.feature.referencedVars, testData, row),
-          trigger: cells.trigger,
-          oracle: cells.oracle,
-          precondition: cells.precondition,
-          verification: cells.verification,
-          fingerprint: scenarioFingerprint(m.feature, row),
-          result: resultByLabel.get(label),
-        });
-      });
-    } else {
-      const cells = renderCells(testData ?? {});
-      variants.push({
-        ...base,
-        ref: vpId,
-        title: category1,
-        condition: category1,
-        data: resolveDataPairs(m.feature.referencedVars, testData),
-        trigger: cells.trigger,
-        oracle: cells.oracle,
-        precondition: cells.precondition,
-        verification: cells.verification,
-        fingerprint: scenarioFingerprint(m.feature),
-        result: resolveResultVariants(m, results ?? null, testData ?? undefined)[0]?.result,
-      });
-    }
-  }
-  return variants;
-}
-
-/**
- * Display substitution for matrix cells. Unlike the legacy exporter's
- * substituteTestDataVars (which keeps EMPTY values literal for the Steps
- * column), an empty value is a legitimate test input here (an intentionally
- * empty field) — it renders as `(empty)` so the tester sees the intent and no
- * `{{token}}` survives into the deliverable (Gate D would reject it).
- */
-function substituteDisplayVars(text: string, vars: Record<string, string>): string {
-  return text.replace(/\{\{\s*([^}\s]+)\s*\}\}/g, (m, key: string) => {
-    if (!(key in vars)) return m; // unknown stays literal → Gate D flags it
-    return displayValue(vars[key]);
-  });
-}
-
-/**
- * Make invisible test data VISIBLE instead of losing it (review GAP-04):
- * '' → (empty) · whitespace-only → (N spaces) · padded → quoted verbatim.
- * The canonical value is never changed — only its presentation.
- */
-export function displayValue(v: string): string {
-  if (v === '') return '(empty)';
-  if (/^\s+$/.test(v)) return `(${v.length} space${v.length > 1 ? 's' : ''})`;
-  if (v !== v.trim()) return `"${v}"`;
-  return v;
-}
-
-function sentenceOf(text: string): string {
-  const s = text.trim();
-  if (!s) return s;
-  const cap = s.charAt(0).toUpperCase() + s.slice(1);
-  return /[.!?…]$/.test(cap) ? cap : `${cap}.`;
-}
-
-/**
- * Requirement inventory ∪ traces → coverage table. Ids are scanned from the spec
- * text (FR-/TR-/NFR-<n>); map overrides win over the derived covered/gap status.
- */
-export function computeRequirements(
-  specText: string,
-  map: DeliveryMap,
-  items: DeliveryItem[],
-): RequirementCoverage[] {
-  const ids: string[] = [];
-  const seen = new Set<string>();
-  for (const m of specText.matchAll(/\b(?:FR|TR|NFR)-\d+\b/g)) {
-    if (!seen.has(m[0])) { seen.add(m[0]); ids.push(m[0]); }
-  }
-  // Overrides may reference ids the spec text doesn't list (e.g. a shared catalog).
-  for (const id of Object.keys(map.requirements ?? {})) {
-    if (!seen.has(id)) { seen.add(id); ids.push(id); }
-  }
-  if (ids.length === 0) return [];
-
-  return ids.map((id) => {
-    const traced = items.filter((it) => it.variants.some((v) => v.traces.includes(id)));
-    const override = (map.requirements ?? {})[id];
-    return {
-      id,
-      status: override?.status ?? (traced.length > 0 ? 'covered' : 'gap'),
-      items: traced.map((it) => it.id),
-      variantCount: traced.reduce((a, it) => a + it.variants.filter((v) => v.traces.includes(id)).length, 0),
-      note: override?.note ?? '',
-    };
-  });
-}
-
-/** Resolve one level of {{key}} cross-references inside test-data VALUES. */
-function resolveCrossRefs(testData: Record<string, string> | null): Record<string, string> | null {
-  if (!testData) return null;
-  const out: Record<string, string> = {};
-  for (const [k, v] of Object.entries(testData)) {
-    out[k] = typeof v === 'string' && v.includes('{{') ? substituteDisplayVars(v, testData) : v;
-  }
-  return out;
-}
-
-function rowAsStrings(row: Record<string, unknown>): Record<string, string> {
-  const out: Record<string, string> = {};
-  for (const [k, v] of Object.entries(row)) {
-    out[k] = String(v);
-    out[`row.${k}`] = String(v); // steps reference dataset columns as {{row.<col>}}
-  }
-  return out;
-}
-
-// ---------------------------------------------------------------------------
-// Item assembly + roll-up
-// ---------------------------------------------------------------------------
-
-/**
- * The exact word rendered in a variant's Result cell. This is the SINGLE
- * vocabulary both the renderers and the parent's COUNTIF roll-up use — the
- * legacy exporter's statusToTestResult disagreed on two statuses (`skipped`
- * showed N/A but counted as not-run; `interrupted` showed Pending but counted
- * as blocked), which silently skewed the derived parent result.
- */
-export function variantState(v: CoverageVariant): VariantState {
-  const r = v.result;
-  if (!r) return 'Pending';
-  switch (r.status) {
-    case 'passed': return 'Passed';
-    case 'failed':
-    case 'timedOut': return 'Failed';
-    case 'interrupted': return 'Blocked';
-    case 'skipped': return 'N/A';
-    default: return 'Pending';
-  }
-}
-
-const STATE_TO_COUNT: Record<VariantState, keyof DeliveryItem['resultCounts']> = {
-  Passed: 'passed', Failed: 'failed', Blocked: 'blocked', Pending: 'notRun', 'N/A': 'na',
-};
-
-/**
- * Derived parent result — precedence failed → blocked → all-N/A → not_run →
- * partial → passed. `N/A` variants leave the denominator (an intentionally
- * skipped case must not make the parent look incomplete).
- */
-export function rollUp(variants: CoverageVariant[]): { result: ItemResult; counts: DeliveryItem['resultCounts'] } {
-  const counts = { passed: 0, failed: 0, blocked: 0, notRun: 0, na: 0 };
-  for (const v of variants) counts[STATE_TO_COUNT[variantState(v)]]++;
-  const effective = variants.length - counts.na;
-  let result: ItemResult;
-  if (counts.failed > 0) result = 'failed';
-  else if (counts.blocked > 0) result = 'blocked';
-  else if (effective === 0) result = 'na';
-  else if (counts.passed === 0) result = 'not_run';
-  else if (counts.passed === effective) result = 'passed';
-  else result = 'partial';
-  return { result, counts };
-}
-
-/** Longest shared leading run of steps — hoisted onto the parent row. */
-function commonPrefix(lists: string[][]): number {
-  if (lists.length === 0) return 0;
-  let n = 0;
-  while (lists.every((l) => l.length > n) && new Set(lists.map((l) => l[n])).size === 1) n++;
-  return n;
-}
-
-/**
- * Expand one map variant ref to concrete variant refs:
- * a bare VP-id whose scenario has a dataset means ALL its rows.
- */
-export function expandMapRef(ref: string, variantsByVp: Map<string, CoverageVariant[]>): CoverageVariant[] {
-  if (ref.includes('#')) {
-    const [vp] = ref.split('#');
-    return (variantsByVp.get(vp) ?? []).filter((v) => v.ref === ref);
-  }
-  return variantsByVp.get(ref) ?? [];
-}
-
-export function buildMatrix(inputs: BuildInputs): MatrixModel {
-  const { unit, map, transformerVersion } = inputs;
-  const variants = deriveVariants(inputs);
-
-  const variantsByVp = new Map<string, CoverageVariant[]>();
-  for (const v of variants) {
-    const list = variantsByVp.get(v.vpId) ?? [];
-    list.push(v);
-    variantsByVp.set(v.vpId, list);
-  }
-
-  const findings = runGates({ inputs, variants, variantsByVp });
-  const stale = new Set(findings.filter((f) => f.gate === 'E' && f.ref).map((f) => f.ref as string));
-
-  const items: DeliveryItem[] = map.groups.map((g) => {
-    const groupVariants = g.variants.flatMap((ref) => expandMapRef(ref, variantsByVp));
-    const { result, counts } = rollUp(groupVariants);
-    const first = groupVariants[0];
-    const modes = new Set(groupVariants.map((v) => v.mode));
-    const commonPre = (first?.precondition ?? []).filter((line) =>
-      groupVariants.every((v) => v.precondition.includes(line)));
-    // Steps every variant starts with belong on the parent once; each variant
-    // renders only its remaining steps (review: the shared prefix was repeated
-    // on every child while the parent cell sat empty).
-    const prefixLen = commonPrefix(groupVariants.map((v) => v.trigger));
-    // Item priority = highest variant priority (per-variant priorities stay visible).
-    const priorityRank: Record<string, number> = { High: 0, Normal: 1, Low: 2 };
-    const priority = groupVariants
-      .map((v) => v.priority)
-      .sort((a, b) => (priorityRank[a] ?? 1) - (priorityRank[b] ?? 1))[0] ?? 'Normal';
-    return {
-      id: g.id,
-      target: g.target,
-      intent: g.intent,
-      oracle: g.oracle,
-      category: g.category,
-      // A stale (drifted) group presents as proposed regardless of its stored state.
-      review: stale.has(g.id) ? 'proposed' : g.review,
-      priority,
-      mode: modes.size > 1 ? 'mixed' : (first?.mode ?? 'auto'),
-      layers: Array.from(new Set(groupVariants.flatMap((v) => v.layers))),
-      traces: Array.from(new Set(groupVariants.flatMap((v) => v.traces))),
-      dimensions: g.dimensions,
-      // Only the preconditions COMMON to every variant belong on the parent —
-      // copying the first variant's setup mis-states the start state of the
-      // others (review GAP-03). Variant-specific lines render as the sub-row's
-      // precondition delta.
-      precondition: commonPre,
-      preconditionDeltas: Object.fromEntries(groupVariants.map((v) =>
-        [v.ref, v.precondition.filter((line) => !commonPre.includes(line))])),
-      triggerDeltas: Object.fromEntries(groupVariants.map((v) =>
-        [v.ref, v.trigger.slice(prefixLen)])),
-      trigger: (first?.trigger ?? []).slice(0, prefixLen),
-      variants: groupVariants,
-      result,
-      resultCounts: counts,
-    };
-  });
-
-  const dispositions: MatrixDisposition[] = Object.entries(map.dispositions).map(([vpId, d]) => ({
-    vpId,
-    title: variantsByVp.get(vpId)?.[0]?.title ?? '',
-    as: d.as,
-    reason: d.reason ?? '',
-  }));
-
-  // Requirement coverage (review §6): the requirement-id inventory comes from
-  // requirements/spec.md; @spec: traces mark `covered`; the map's `requirements:`
-  // section carries the reviewed overrides (partially_covered / not_applicable / …).
-  const requirements = computeRequirements(inputs.specText ?? '', map, items);
-  const gaps = requirements.filter((r) => r.status === 'gap');
-  if (gaps.length > 0) {
-    findings.push({
-      gate: 'R', severity: 'warning',
-      message: `${gaps.length} requirement id(s) with no coverage or disposition: ${gaps.map((g) => g.id).join(', ')} — trace them, or record a status in the map \`requirements:\` section`,
-    });
-  }
-  // A `covered` claim with no traced variant is prose, not traceability: nothing
-  // detects it when the proving scenario is later changed or deleted. Either tag
-  // the scenario that proves it (`@spec:<id>`) or say where it IS covered.
-  const unbacked = requirements.filter((r) => r.status === 'covered' && r.items.length === 0);
-  if (unbacked.length > 0) {
-    findings.push({
-      gate: 'R', severity: 'warning',
-      message: `${unbacked.length} requirement id(s) declared \`covered\` with no variant tracing to them: ${unbacked.map((r) => r.id).join(', ')} — add \`@spec:<id>\` to the scenario that proves each, or use covered_elsewhere / partially_covered with a named reference`,
-    });
-  }
-
-  const variantCount = items.reduce((a, i) => a + i.variants.length, 0);
-  const approved = items.every((i) => i.review === 'approved')
-    && !findings.some((f) => f.severity === 'error' || f.severity === 'review');
-
-  return {
-    unit,
-    formNo: map.formNo ?? 'BM-2-901-13',
-    items,
-    dispositions,
-    requirements,
-    findings,
-    manifest: {
-      unit,
-      transformerVersion,
-      sourceFingerprint: combinedFingerprint(variants.map((v) => v.fingerprint)),
-      mapFingerprint: mapContentFingerprint(map.groups, map.dispositions),
-      approvalState: approved ? 'approved' : 'draft',
-      itemCount: items.length,
-      variantCount,
-      thresholds: { maxVariantsPerItem: MAX_VARIANTS_PER_ITEM },
-    },
-  };
-}

package/src/exporters/matrix/export.ts

@@ -1,149 +0,0 @@
-/**
- * Matrix export orchestration — the piece `sungen delivery` calls.
- *
- * Composes the existing parsing seams (feature-parser, spec-parser, test-data,
- * playwright report) with the map loader, builder, gates, and renderers. All
- * inputs arrive as resolved paths so the CLI's discovery logic stays the single
- * owner of unit-kind layout rules.
- */
-
-import * as fs from 'fs';
-import { parseFeatureMetadata } from '../feature-parser';
-import { parseSpecFile } from '../spec-parser';
-import { loadTestData } from '../test-data-resolver';
-import { loadPlaywrightReport } from '../playwright-report-parser';
-import { mergeFeatureAndSpec } from '../scenario-merger';
-import { getPackageVersion } from '../package-info';
-import { writeCsv } from '../csv-exporter';
-import { writeXlsx } from '../xlsx-exporter';
-import { loadDeliveryMap, writeDeliveryMap } from './map-loader';
-import { mapContentFingerprint } from './fingerprint';
-import { buildMatrix, deriveVariants } from './build';
-import { renderMatrixXlsx } from './render-xlsx';
-import { renderMatrixCsv } from './render-csv';
-import { DeliveryMap, MatrixFinding, MatrixModel } from './types';
-
-export interface MatrixTargetPaths {
-  cwd: string;
-  /** Feature basename — names the deliverable files. */
-  unit: string;
-  /** Display label (flow/… prefix for flows). */
-  label: string;
-  featureFile: string;
-  testDataFile: string;
-  specFile: string;
-  /** requirements/spec.md — the requirement-id inventory for coverage (optional). */
-  specMdFile?: string;
-  resultsPath: string | null;
-  mapFile: string;
-}
-
-function readSpecText(paths: MatrixTargetPaths): string {
-  return paths.specMdFile && fs.existsSync(paths.specMdFile)
-    ? fs.readFileSync(paths.specMdFile, 'utf-8')
-    : '';
-}
-
-export interface MatrixLoadResult {
-  model?: MatrixModel;
-  map?: DeliveryMap;
-  /** No map file → the caller prints the guidance path (AI proposal or --legacy). */
-  mapMissing?: boolean;
-  /** Structural map problems (bad YAML/shape) — fix the file before anything else. */
-  mapErrors: string[];
-}
-
-export function loadMatrixModel(paths: MatrixTargetPaths): MatrixLoadResult {
-  const { map, errors } = loadDeliveryMap(paths.mapFile);
-  if (!map) {
-    return errors.length === 0 ? { mapMissing: true, mapErrors: [] } : { mapErrors: errors };
-  }
-
-  const feature = parseFeatureMetadata(paths.featureFile);
-  const spec = parseSpecFile(paths.specFile);
-  const merged = mergeFeatureAndSpec(feature, spec);
-  const testData = fs.existsSync(paths.testDataFile) ? loadTestData(paths.testDataFile, process.env.SUNGEN_ENV ?? null) : null;
-  const results = paths.resultsPath ? loadPlaywrightReport(paths.resultsPath) : null;
-
-  const model = buildMatrix({
-    unit: paths.unit,
-    feature,
-    merged,
-    testData,
-    results,
-    map,
-    transformerVersion: getPackageVersion(),
-    specText: readSpecText(paths),
-  });
-  return { model, map, mapErrors: [] };
-}
-
-export const hasErrors = (f: MatrixFinding[]): boolean => f.some((x) => x.severity === 'error');
-export const hasReview = (f: MatrixFinding[]): boolean => f.some((x) => x.severity === 'review');
-
-/**
- * Stamp fingerprints + flip groups to `approved` (all groups, or just `groupIds`).
- * Refuses when gate ERRORs remain — an invalid map must not be frozen as approved.
- * Returns the findings so the caller reports what blocked or what was approved.
- */
-export function approveMatrix(paths: MatrixTargetPaths, groupIds?: string[]): { findings: MatrixFinding[]; approved: string[] } {
-  const { map, errors } = loadDeliveryMap(paths.mapFile);
-  if (!map) throw new Error(errors.length > 0 ? `map is invalid:\n  - ${errors.join('\n  - ')}` : `no delivery map at ${paths.mapFile}`);
-
-  const feature = parseFeatureMetadata(paths.featureFile);
-  const spec = parseSpecFile(paths.specFile);
-  const merged = mergeFeatureAndSpec(feature, spec);
-  const testData = fs.existsSync(paths.testDataFile) ? loadTestData(paths.testDataFile, process.env.SUNGEN_ENV ?? null) : null;
-
-  const model = buildMatrix({
-    unit: paths.unit, feature, merged, testData, results: null, map,
-    transformerVersion: getPackageVersion(),
-    specText: readSpecText(paths),
-  });
-  const blocking = model.findings.filter((f) => f.severity === 'error');
-  if (blocking.length > 0) return { findings: blocking, approved: [] };
-
-  const variants = deriveVariants({ feature, merged, testData, results: null });
-  const byRef = new Map(variants.map((v) => [v.ref, v] as const));
-  const byVp = new Map<string, typeof variants>();
-  for (const v of variants) {
-    const list = byVp.get(v.vpId) ?? [];
-    list.push(v);
-    byVp.set(v.vpId, list);
-  }
-
-  const approved: string[] = [];
-  for (const g of map.groups) {
-    if (groupIds && groupIds.length > 0 && !groupIds.includes(g.id)) continue;
-    for (const ref of g.variants) {
-      const expanded = ref.includes('#') ? [byRef.get(ref)].filter(Boolean) : (byVp.get(ref) ?? []);
-      for (const v of expanded) map.fingerprints[(v as NonNullable<typeof expanded[number]>).ref] = (v as NonNullable<typeof expanded[number]>).fingerprint;
-    }
-    g.review = 'approved';
-    approved.push(g.id);
-  }
-  // Freeze the reviewed map semantics as well (GAP-09) — computed AFTER the
-  // review flips so re-running approve on an unchanged map is idempotent.
-  map.fingerprints.__map__ = mapContentFingerprint(map.groups, map.dispositions);
-  writeDeliveryMap(paths.mapFile, map);
-  return { findings: model.findings.filter((f) => f.severity !== 'error'), approved };
-}
-
-export type MatrixFormat = 'xlsx' | 'csv' | 'both';
-
-/** Render + write the requested format(s). Caller has already enforced the gate policy. */
-export async function writeMatrixDeliverables(
-  paths: MatrixTargetPaths,
-  model: MatrixModel,
-  format: MatrixFormat = 'xlsx',
-): Promise<{ csvPath?: string; xlsxPath?: string }> {
-  const out: { csvPath?: string; xlsxPath?: string } = {};
-  if (format === 'csv' || format === 'both') {
-    out.csvPath = writeCsv(paths.cwd, paths.unit, renderMatrixCsv(model));
-  }
-  if (format === 'xlsx' || format === 'both') {
-    const wb = renderMatrixXlsx(model, getPackageVersion());
-    out.xlsxPath = await writeXlsx(paths.cwd, paths.unit, wb);
-  }
-  return out;
-}