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

package/src/exporters/matrix/build.ts

@@ -34,6 +34,7 @@ import {
   MAX_VARIANTS_PER_ITEM,
 } from './types';
 import { runGates } from './gates';
+import { CATALOG_GATE_RULES, GateRules } from '../../harness/gates/resolve-rule';
 import { capabilityRegistry } from '../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 
@@ -96,6 +97,7 @@ function resolveDataPairs(
   vars: string[],
   testData: Record<string, string> | null,
   row?: Record<string, unknown>,
+  runtimeVars: Set<string> = new Set(),
 ): string[] {
   const pairs: string[] = [];
   if (row) {
@@ -107,7 +109,10 @@ function resolveDataPairs(
   for (const v of vars) {
     const val = row && v in row ? undefined : testData?.[v]; // row columns already listed
     // Credential-named refs (`accounts.0.password`) render `***` — this column is read outside the run.
-    if (val !== undefined) pairs.push(`${v}: ${displayValue(maskCredentialValue(v, val))}`);
+    // A value may embed a var the scenario captures at run time (`Total ({{stat}})`) or a
+    // dataset column — expanded with the same vars as the cells, so both columns agree (#879).
+    const scope = row ? { ...(testData ?? {}), ...rowAsStrings(row) } : (testData ?? {});
+    if (val !== undefined) pairs.push(`${v}: ${displayValue(maskCredentialValue(v, expandValue(String(val), scope, runtimeVars, new Set([v]))))}`);
   }
   return pairs;
 }
@@ -124,6 +129,8 @@ export interface BuildInputs {
   specText?: string;
   /** apis.yaml endpoint catalog (api units) — renders `@api:` calls as request blocks. */
   apiCatalog?: Record<string, ApiCatalogEntry>;
+  /** The unit's gate rules (catalog + gate-overrides, OES-11.2); the catalog alone when absent. */
+  gateRules?: GateRules;
 }
 
 /**
@@ -136,6 +143,10 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
   // 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);
+  // Display cells expand from the RAW values, per scenario — with its row and its runtime vars —
+  // in the runtime's order (captured var > row column > test-data key). The pre-resolved copy above
+  // only serves row discovery and result matching, which render nothing (#879).
+  const rawTestData = inputs.testData ?? {};
   const apiCatalog = inputs.apiCatalog ?? {};
   const variants: CoverageVariant[] = [];
 
@@ -305,14 +316,14 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
       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) });
+        const cells = renderCells({ ...rawTestData, ...rowAsStrings(row) });
         variants.push({
           ...base,
           ref: `${vpId}#${label}`,
           caseLabel: label,
           title: `${category1} — ${label}`,
           condition: label,
-          data: resolveDataPairs(m.feature.referencedVars, testData, row),
+          data: resolveDataPairs(m.feature.referencedVars, rawTestData, row, runtimeVars),
           trigger: cells.trigger,
           oracle: cells.oracle,
           precondition: cells.precondition,
@@ -322,13 +333,13 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
         });
       });
     } else {
-      const cells = renderCells(testData ?? {});
+      const cells = renderCells(rawTestData);
       variants.push({
         ...base,
         ref: vpId,
         title: category1,
         condition: category1,
-        data: resolveDataPairs(m.feature.referencedVars, testData),
+        data: resolveDataPairs(m.feature.referencedVars, rawTestData, undefined, runtimeVars),
         trigger: cells.trigger,
         oracle: cells.oracle,
         precondition: cells.precondition,
@@ -360,9 +371,9 @@ function substituteDisplayVars(
     if (isCapture && /\bas\s+$/i.test(text.slice(0, offset))) return m;
     // A value the test produces at run time has no static form — name it so the
     // tester knows to compare against what the earlier step captured.
-    if (runtimeVars.has(key) || runtimeVars.has(key.split(/[.[]/)[0])) return `the captured ${key}`;
+    if (isRuntimeVar(key, runtimeVars)) return `the captured ${key}`;
     if (!(key in vars)) return m; // unknown stays literal → Gate D flags it
-    return displayValue(vars[key]);
+    return displayValue(expandValue(vars[key], vars, runtimeVars, new Set([key])));
   });
   // A dynamic token written straight into a step (`{{$uuid}}`) never reaches
   // displayValue — name it here so the same wording covers both routes.
@@ -432,12 +443,45 @@ export function computeRequirements(
   });
 }
 
-/** Resolve one level of {{key}} cross-references inside test-data VALUES. */
+const isRuntimeVar = (key: string, runtimeVars: Set<string>): boolean =>
+  runtimeVars.has(key) || runtimeVars.has(key.split(/[.[]/)[0]);
+
+/**
+ * Expand the `{{refs}}` inside a test-data VALUE the way the runtime's `interpolate()` does
+ * (specs/generated/test-data.ts): recursively, depth-capped against reference cycles, and a var
+ * the scenario captures at run time is named, not looked up. An unknown ref (or a cycle) stays
+ * literal, so Gate D still refuses it; a nested value renders through displayValue, as it did
+ * when this resolved one level (an empty one reads `(empty)`).
+ *
+ * Delivery used to resolve ONE level, before any scenario's runtime vars were known: both
+ * `heading_expected: "Total ({{stat}})"` with `remember … as {{stat}}`, and a plain chain
+ * (`a: "{{b}}"`, `b: "x {{c}}"`), left a token that blocked the export of a suite the runtime
+ * runs fine (#879).
+ */
+function expandValue(
+  value: string, vars: Record<string, string>, runtimeVars: Set<string>,
+  expanding: ReadonlySet<string> = new Set(), depth = 0,
+): string {
+  if (depth > 10 || !value.includes('{{')) return value;
+  return value.replace(/\{\{\s*([^}\s]+)\s*\}\}/g, (m, key: string) => {
+    if (isRuntimeVar(key, runtimeVars)) return `the captured ${key}`;
+    const v = vars[key];
+    // A key already being expanded is a cycle: keep the token (Gate D names it) instead of
+    // re-entering — `a: "{{a}}{{a}}"` doubled per level and exhausted the heap.
+    if (v === undefined || v === null || expanding.has(key)) return m;
+    return displayValue(expandValue(String(v), vars, runtimeVars, new Set([...expanding, key]), depth + 1));
+  });
+}
+
+/**
+ * Pre-resolve test-data cross-references before any scenario is known — every static level.
+ * A runtime var is not known yet and stays a token here; each scenario's cells expand it.
+ */
 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;
+    out[k] = typeof v === 'string' && v.includes('{{') ? renderDynamicTokens(expandValue(v, testData, new Set(), new Set([k]))) : v;
   }
   return out;
 }
@@ -463,6 +507,7 @@ function rowAsStrings(row: Record<string, unknown>): Record<string, string> {
  * as blocked), which silently skewed the derived parent result.
  */
 export function variantState(v: CoverageVariant): VariantState {
+  if (v.manualState) return v.manualState;   // a carried Manual result (#891)
   const r = v.result;
   if (!r) return 'Pending';
   switch (r.status) {
@@ -552,7 +597,7 @@ export function buildMatrix(inputs: BuildInputs): MatrixModel {
     variantsByVp.set(v.vpId, list);
   }
 
-  const findings = runGates({ inputs, variants, variantsByVp });
+  const findings = runGates({ inputs, variants, variantsByVp, rules: inputs.gateRules });
   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) => {
@@ -618,22 +663,21 @@ export function buildMatrix(inputs: BuildInputs): MatrixModel {
   // 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);
+  // Gate R levels come from the catalog like every other matrix gate (OES-11.2); `off` drops the finding.
+  const gateR = (rule: string, message: string): void => {
+    const { severity } = (inputs.gateRules ?? CATALOG_GATE_RULES).resolve(rule);
+    if (severity !== 'off') findings.push({ gate: 'R', severity, message });
+  };
   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`,
-    });
+    gateR('matrix.gate-r.requirement-gap', `${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`,
-    });
+    gateR('matrix.gate-r.covered-unbacked', `${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);

package/src/exporters/matrix/carry-manual-results.ts

@@ -19,7 +19,8 @@
 
 import * as fs from 'fs';
 import * as ExcelJS from 'exceljs';
-import { MatrixModel } from './types';
+import { MatrixModel, VariantState } from './types';
+import { rollUp } from './build';
 import { HEADER_ROW, RESULT_COL } from './render-testcase-sheet';
 
 const MANUAL_SHEET = 'Manual';
@@ -169,6 +170,70 @@ function resetNote(prior: CarriedCell[]): ExcelJS.CellValue {
   return own ? `${header}\n${own}` : header;
 }
 
+/**
+ * What happens to each Manual variant's prior row: `carry` its cells, or `reset` it to Pending
+ * because the procedure changed since the result was recorded. A row with nothing recorded has
+ * no entry. The ONE decision both the model (totals, #891) and the workbook cells read.
+ */
+export function planManualCarry(model: MatrixModel, prior: PriorManualResults | null): Map<string, 'carry' | 'reset'> {
+  const plan = new Map<string, 'carry' | 'reset'>();
+  if (!prior) return plan;
+  for (const v of model.items.flatMap((i) => i.variants)) {
+    if (v.mode !== 'manual') continue;
+    const before = prior.rows.get(v.ref);
+    if (!before || isUntouched(before.cells)) continue;
+    const stamped = prior.stamps?.get(v.ref);
+    // Only a recorded result is a claim about the procedure. A row with no result (a
+    // blocker note, or one already reset) is carried as-is, so a second procedure
+    // change does not stack a second marker on it.
+    const hasResult = !['', 'Pending'].includes(cellText(before.cells[0].value));
+    plan.set(v.ref, stamped !== undefined && stamped !== v.fingerprint && hasResult ? 'reset' : 'carry');
+  }
+  return plan;
+}
+
+/** A typed Result → its state word, case-insensitively (Excel's COUNTIF ignores case too). */
+const STATE_BY_LOWER = new Map<string, VariantState>(
+  (['Passed', 'Failed', 'Blocked', 'Pending', 'N/A'] as VariantState[]).map((s) => [s.toLowerCase(), s]),
+);
+
+/**
+ * Put the carried Manual results into the MODEL, before anything is rendered or counted.
+ *
+ * The workbook's totals, Overview and group roll-ups are formulas with a cached result computed
+ * from the model, and the CSV and the CLI summary read the model too. Carrying only the cells
+ * after rendering left all of them counting the recorded Manual results as Pending: a preview
+ * of the file, and the CLI, reported "5 Pending" for cases the tester had run (#891).
+ * A reset row counts as Pending, as its cell reads. A Result that is not a state word (a tester's
+ * "OK") counts as Pending too; the cell keeps the text, and its date still reaches the CSV.
+ * Idempotent: every Manual variant's carried fields are cleared first, so the result depends only
+ * on `prior`.
+ */
+export function applyManualCarry(model: MatrixModel, prior: PriorManualResults | null): void {
+  const plan = planManualCarry(model, prior);
+  for (const item of model.items) {
+    let touched = false;
+    for (const v of item.variants) {
+      if (v.mode !== 'manual') continue;
+      if (v.manualState !== undefined || v.manualDate !== undefined) touched = true;
+      delete v.manualState;
+      delete v.manualDate;
+      const decision = plan.get(v.ref);
+      if (!decision) continue;
+      touched = true;
+      if (decision === 'reset') { v.manualState = 'Pending'; continue; }
+      const [result, date] = prior!.rows.get(v.ref)!.cells.map((c) => cellText(c.value));
+      if (date) v.manualDate = date;
+      v.manualState = STATE_BY_LOWER.get(result.toLowerCase()) ?? 'Pending';
+    }
+    if (touched) {
+      const { result, counts } = rollUp(item.variants);
+      item.result = result;
+      item.resultCounts = counts;
+    }
+  }
+}
+
 /**
  * Carry `prior` into the freshly rendered `wb`, then stamp every manual variant's fingerprint.
  * Only the Manual sheet's variant sub-rows are touched.
@@ -178,6 +243,7 @@ export function carryManualResults(
   model: MatrixModel,
   prior: PriorManualResults | null,
 ): ManualCarryReport {
+  const plan = planManualCarry(model, prior);
   const report: ManualCarryReport = { carried: 0, unchecked: 0, reset: [], notPlaced: [], duplicates: prior?.duplicates ?? [] };
   const fingerprints = new Map(
     model.items.flatMap((i) => i.variants).filter((v) => v.mode === 'manual').map((v) => [v.ref, v.fingerprint]),
@@ -190,14 +256,11 @@ export function carryManualResults(
       const before = prior.rows.get(ref);
       if (!before) continue;
       placed.add(ref);
-      if (isUntouched(before.cells)) continue;
+      const decision = plan.get(ref);
+      if (!decision) continue;
 
       const stamped = prior.stamps?.get(ref);
-      // Only a recorded result is a claim about the procedure. A row with no result (a
-      // blocker note, or one already reset) is carried as-is, so a second procedure
-      // change does not stack a second marker on it.
-      const hasResult = !['', 'Pending'].includes(cellText(before.cells[0].value));
-      if (stamped !== undefined && stamped !== fingerprints.get(ref) && hasResult) {
+      if (decision === 'reset') {
         row.getCell(RESULT_COL).value = 'Pending';
         row.getCell(CARRIED_COLS[NOTE_INDEX]).value = resetNote(before.cells);
         report.reset.push(ref);

package/src/exporters/matrix/export.ts

@@ -17,7 +17,8 @@ import { mergeFeatureAndSpec } from '../scenario-merger';
 import { getPackageVersion } from '../package-info';
 import { writeCsv } from '../csv-exporter';
 import { deliverableXlsxPath, writeXlsx } from '../xlsx-exporter';
-import { carryManualResults, ManualCarryReport, readPriorManualResults } from './carry-manual-results';
+import { applyManualCarry, carryManualResults, ManualCarryReport, PriorManualResults, readPriorManualResults } from './carry-manual-results';
+export { readPriorManualResults } from './carry-manual-results';
 import { loadPerfConfig, perfVerdict } from '../../harness/perf';
 import { loadDeliveryMap, writeDeliveryMap } from './map-loader';
 import { mapContentFingerprint } from './fingerprint';
@@ -27,6 +28,7 @@ import { renderMatrixCsv } from './render-csv';
 import { DeliveryMap, MatrixFinding, MatrixModel } from './types';
 import { ApiCatalogEntry } from '../types';
 import { RunEnvironment } from '../run-environment';
+import { GateRules } from '../../harness/gates/resolve-rule';
 
 export interface MatrixTargetPaths {
   cwd: string;
@@ -49,6 +51,8 @@ export interface MatrixTargetPaths {
   mapFile: string;
   /** Executor + environment of the run (#850) — absent for gates-only callers (inspect, approve). */
   runEnv?: RunEnvironment;
+  /** The unit's gate rules (catalog + gate-overrides) — absent means the catalog alone. */
+  gateRules?: GateRules;
 }
 
 function readSpecText(paths: MatrixTargetPaths): string {
@@ -93,6 +97,7 @@ export function loadMatrixModel(paths: MatrixTargetPaths): MatrixLoadResult {
     transformerVersion: getPackageVersion(),
     specText: readSpecText(paths),
     apiCatalog: catalogFor(paths),
+    gateRules: paths.gateRules,
   });
   model.runEnv = paths.runEnv;
   // Perf verdict (#569): budgets are config (qa/perf.yaml), samples are the run's
@@ -131,6 +136,7 @@ export function approveMatrix(paths: MatrixTargetPaths, groupIds?: string[]): {
     transformerVersion: getPackageVersion(),
     specText: readSpecText(paths),
     apiCatalog,
+    gateRules: paths.gateRules,
   });
   const blocking = model.findings.filter((f) => f.severity === 'error');
   if (blocking.length > 0) return { findings: blocking, approved: [] };
@@ -168,12 +174,21 @@ export async function writeMatrixDeliverables(
   paths: MatrixTargetPaths,
   model: MatrixModel,
   format: MatrixFormat = 'xlsx',
+  /** The prior workbook's Manual results, when the caller already read them; read here if absent. */
+  priorRead?: PriorManualResults | null,
 ): Promise<{ csvPath?: string; xlsxPath?: string; manualCarry?: ManualCarryReport }> {
   const out: { csvPath?: string; xlsxPath?: string; manualCarry?: ManualCarryReport } = {};
   const xlsx = format === 'xlsx' || format === 'both';
   // Read the workbook about to be overwritten BEFORE writing anything, so the tester's Manual
   // results survive (#756) and a refusal leaves no half-written target behind.
-  const prior = xlsx ? await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit)) : null;
+  // A CSV-only export overwrites no workbook, so an unreadable one is no reason to refuse it — but a
+  // readable one still holds the Manual results the CSV should show.
+  const prior = priorRead !== undefined ? priorRead
+    : xlsx ? await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit))
+      : await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit)).catch(() => null);
+  // Into the model first: the CSV, every cached total and roll-up, and the caller's summary
+  // all read it (#891).
+  applyManualCarry(model, prior);
   if (format === 'csv' || format === 'both') {
     out.csvPath = writeCsv(paths.cwd, paths.unit, renderMatrixCsv(model));
   }