@sun-asterisk/sungen 3.2.14 → 3.2.16-beta.1

package/src/exporters/matrix/build.ts

@@ -0,0 +1,294 @@
+/**
+ * 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, parseManualComments } from '../scenario-merger';
+import {
+  extractAuthRole,
+  extractPriority,
+  extractTestcaseType,
+  splitVpAndName,
+} from '../feature-parser';
+import { getCasesDatasetRows, resolveResultVariants } from '../result-variants';
+import { substituteTestDataVars } from '../test-data-resolver';
+import { scenarioFingerprint, combinedFingerprint, mapContentFingerprint } from './fingerprint';
+import {
+  CoverageVariant,
+  DeliveryItem,
+  DeliveryMap,
+  ItemResult,
+  MatrixDisposition,
+  MatrixLayer,
+  MatrixModel,
+  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}: ${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}: ${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;
+}
+
+/**
+ * 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, testData, results } = inputs;
+  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]?$/, '');
+
+    // Manual procedure comes from the parsed comment block; auto from Gherkin buckets.
+    const manual = mode === 'manual' && m.feature.comments?.length
+      ? parseManualComments(m.feature.comments)
+      : null;
+    // A pure-render check (Given + Then only) is triggered by the page load itself —
+    // that IS its action, not a Gate-D executability gap.
+    const rawTrigger = manual ? manual.steps.map((s) => s.text) : m.feature.rawWhenSteps;
+    const triggerSteps = rawTrigger.length > 0 ? rawTrigger : ['(on page load)'];
+    const oracleSteps = m.resolvedExpected.map((s) => s.text);
+
+    const preconditionProfile = [
+      authRole ?? '-',
+      m.feature.extendsName ?? '-',
+      ...m.feature.rawGivenSteps.map(normalizeShape),
+    ].join(' | ');
+    const precondition = [
+      ...(authRole ? [authRole === 'no-auth' ? 'Not authenticated' : `Authenticated as ${authRole}`] : []),
+      ...m.feature.rawGivenSteps,
+    ];
+
+    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: triggerSteps.map(normalizeShape),
+      oracleShape: oracleSteps.map(normalizeShape),
+      preconditionProfile,
+      precondition,
+      procedureProfile: deriveProcedureProfile(m),
+    };
+
+    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}`);
+        variants.push({
+          ...base,
+          ref: `${vpId}#${label}`,
+          caseLabel: label,
+          title: `${category1} — ${label}`,
+          condition: label,
+          data: resolveDataPairs(m.feature.referencedVars, testData, row),
+          trigger: triggerSteps.map((s) => substituteTestDataVars(s, { ...(testData ?? {}), ...rowAsStrings(row) })),
+          oracle: oracleSteps.map((s) => substituteTestDataVars(s, { ...(testData ?? {}), ...rowAsStrings(row) })),
+          fingerprint: scenarioFingerprint(m.feature, row),
+          result: resultByLabel.get(label),
+        });
+      });
+    } else {
+      variants.push({
+        ...base,
+        ref: vpId,
+        title: category1,
+        condition: category1,
+        data: resolveDataPairs(m.feature.referencedVars, testData),
+        trigger: triggerSteps.map((s) => substituteTestDataVars(s, testData ?? {})),
+        oracle: oracleSteps.map((s) => substituteTestDataVars(s, testData ?? {})),
+        fingerprint: scenarioFingerprint(m.feature),
+        result: resolveResultVariants(m, results ?? null, testData ?? undefined)[0]?.result,
+      });
+    }
+  }
+  return variants;
+}
+
+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);
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Item assembly + roll-up
+// ---------------------------------------------------------------------------
+
+function classifyResult(r: PlaywrightResult | undefined): 'passed' | 'failed' | 'blocked' | 'notRun' {
+  if (!r) return 'notRun';
+  if (r.status === 'passed') return 'passed';
+  if (r.status === 'failed' || r.status === 'timedOut') return 'failed';
+  if (r.status === 'interrupted') return 'blocked';
+  return 'notRun'; // skipped / unknown
+}
+
+/** Derived parent result — precedence: failed → blocked → not_run → partial → passed. */
+export function rollUp(variants: CoverageVariant[]): { result: ItemResult; counts: DeliveryItem['resultCounts'] } {
+  const counts = { passed: 0, failed: 0, blocked: 0, notRun: 0 };
+  for (const v of variants) counts[classifyResult(v.result)]++;
+  const run = counts.passed + counts.failed + counts.blocked;
+  let result: ItemResult;
+  if (counts.failed > 0) result = 'failed';
+  else if (counts.blocked > 0) result = 'blocked';
+  else if (run === 0) result = 'not_run';
+  else if (counts.notRun > 0) result = 'partial';
+  else result = 'passed';
+  return { result, counts };
+}
+
+/**
+ * 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 triggerShapes = new Set(groupVariants.map((v) => v.triggerShape.join(' ; ')));
+    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: first?.priority ?? 'Normal',
+      mode: first?.mode ?? 'auto',
+      layers: Array.from(new Set(groupVariants.flatMap((v) => v.layers))),
+      traces: Array.from(new Set(groupVariants.flatMap((v) => v.traces))),
+      precondition: first?.precondition ?? [],
+      trigger: triggerShapes.size === 1 ? (first?.trigger ?? []) : ['(per variant)'],
+      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 ?? '',
+  }));
+
+  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,
+    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

@@ -0,0 +1,124 @@
+/**
+ * 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 { 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;
+  resultsPath: string | null;
+  mapFile: string;
+}
+
+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(),
+  });
+  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(),
+  });
+  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);
+  }
+  writeDeliveryMap(paths.mapFile, map);
+  return { findings: model.findings.filter((f) => f.severity !== 'error'), approved };
+}
+
+/** Render + write both artifacts. Caller has already enforced the gate policy. */
+export async function writeMatrixDeliverables(paths: MatrixTargetPaths, model: MatrixModel): Promise<{ csvPath: string; xlsxPath: string }> {
+  const csvPath = writeCsv(paths.cwd, paths.unit, renderMatrixCsv(model));
+  const wb = renderMatrixXlsx(model, getPackageVersion());
+  const xlsxPath = await writeXlsx(paths.cwd, paths.unit, wb);
+  return { csvPath, xlsxPath };
+}

package/src/exporters/matrix/fingerprint.ts

@@ -0,0 +1,49 @@
+/**
+ * Canonical scenario fingerprints for the Delivery Map drift detector (Gate E).
+ *
+ * A fingerprint hashes what changes the MEANING of a variant: sorted tags + ordered
+ * step text (+ the dataset row for a @cases variant). Formatting, comments, and
+ * scenario order do NOT change it. `--approve` stamps these into the map; a later
+ * mismatch drops the group back to review (stale grouping).
+ */
+
+import * as crypto from 'crypto';
+import { ScenarioMetadata } from '../types';
+
+/** Stable stringify: objects get sorted keys so row column order can't shift the hash. */
+function canonical(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`).join(',')}}`;
+}
+
+function sha1(text: string): string {
+  return 'sha1:' + crypto.createHash('sha1').update(text, 'utf-8').digest('hex');
+}
+
+/**
+ * Fingerprint one scenario. Tags are sorted (order is presentation); steps keep
+ * their order (order is meaning). Manual scenarios include their procedure
+ * comments — for them the comments ARE the test.
+ */
+export function scenarioFingerprint(sc: ScenarioMetadata, datasetRow?: Record<string, unknown>): string {
+  const body = canonical({
+    tags: [...sc.tags].sort(),
+    steps: sc.orderedSteps.map((s) => `${s.bucket}:${s.text}`),
+    comments: sc.tags.some((t) => t === '@manual' || t.startsWith('@manual:')) ? (sc.comments ?? []) : [],
+    row: datasetRow ?? null,
+  });
+  return sha1(body);
+}
+
+/** Fingerprint of the whole source (all variants) — manifest `sourceFingerprint`. */
+export function combinedFingerprint(parts: string[]): string {
+  return sha1(canonical([...parts].sort()));
+}
+
+/** Fingerprint of the map's semantic content (groups + dispositions, not stamps). */
+export function mapContentFingerprint(groups: unknown, dispositions: unknown): string {
+  return sha1(canonical({ groups, dispositions }));
+}