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

package/src/exporters/matrix/gates.ts

@@ -0,0 +1,284 @@
+/**
+ * Deterministic quality gates for the Test Case & Coverage Matrix
+ * (docs/spec/delivery-coverage-matrix-spec.md §6).
+ *
+ * Severity behavior:
+ *   error   → blocks any render
+ *   review  → blocks the official render; `--preview` renders with a DRAFT watermark
+ *   warning → prints + renders
+ *
+ * The gates recompute every signature part from the .feature — the map is never
+ * trusted for derivable facts, only for the semantic fields (target/intent/oracle).
+ */
+
+import { splitVpAndName, extractTestcaseType } from '../feature-parser';
+import { CoverageVariant, MatrixFinding, MAX_VARIANTS_PER_ITEM } from './types';
+import { expandMapRef, BuildInputs } from './build';
+
+export interface GateContext {
+  inputs: BuildInputs;
+  variants: CoverageVariant[];
+  variantsByVp: Map<string, CoverageVariant[]>;
+}
+
+export function runGates(ctx: GateContext): MatrixFinding[] {
+  const findings: MatrixFinding[] = [];
+  gateASource(ctx, findings);
+  gateBMapping(ctx, findings);
+  gateCAggregation(ctx, findings);
+  gateDExecutability(ctx, findings);
+  gateEDrift(ctx, findings);
+  gateGReviewState(ctx, findings);
+  return findings;
+}
+
+// --- Gate A — source quality ------------------------------------------------
+
+function gateASource(ctx: GateContext, findings: MatrixFinding[]): void {
+  const { feature, merged } = ctx.inputs;
+
+  if (feature.backgroundWhenSteps.length > 0 || feature.backgroundThenSteps.length > 0) {
+    findings.push({
+      gate: 'A', severity: 'error',
+      message: 'Background contains When/Then steps — setup only; move the action/oracle into scenarios',
+    });
+  }
+
+  const seen = new Map<string, number>();
+  for (const m of merged) {
+    const { vpId } = splitVpAndName(m.feature.name);
+    if (!vpId) {
+      findings.push({
+        gate: 'A', severity: 'error', ref: m.feature.name,
+        message: `scenario "${m.feature.name}" has no VP-id prefix — matrix variants must be addressable`,
+      });
+      continue;
+    }
+    seen.set(vpId, (seen.get(vpId) ?? 0) + 1);
+
+    const isManual = extractTestcaseType(m.feature.tags) === 'Manual';
+    if (m.resolvedExpected.length === 0) {
+      findings.push({
+        gate: 'A', severity: 'error', ref: vpId,
+        message: isManual
+          ? `manual scenario ${vpId} has no observable oracle (no Then steps and no Observable/Oracle comment lines)`
+          : `scenario ${vpId} has no Then step — a variant without an observable oracle cannot be delivered`,
+      });
+    }
+  }
+  for (const [vpId, n] of seen) {
+    if (n > 1) findings.push({ gate: 'A', severity: 'error', ref: vpId, message: `duplicate VP-id ${vpId} (${n} scenarios)` });
+  }
+}
+
+// --- Gate B — mapping completeness -------------------------------------------
+
+function gateBMapping(ctx: GateContext, findings: MatrixFinding[]): void {
+  const { map } = ctx.inputs;
+  const { variants, variantsByVp } = ctx;
+
+  // Where each derived variant landed: 0 → unmapped, >1 → double-mapped.
+  const owners = new Map<string, string[]>();
+  for (const g of map.groups) {
+    for (const ref of g.variants) {
+      const expanded = expandMapRef(ref, variantsByVp);
+      if (expanded.length === 0) {
+        findings.push({
+          gate: 'B', severity: 'error', ref: g.id,
+          message: `group ${g.id} references ${ref} which matches no scenario/@cases row in the .feature`,
+        });
+        continue;
+      }
+      for (const v of expanded) {
+        const list = owners.get(v.ref) ?? [];
+        list.push(g.id);
+        owners.set(v.ref, list);
+      }
+    }
+  }
+
+  for (const [ref, groups] of owners) {
+    if (groups.length > 1) {
+      findings.push({
+        gate: 'B', severity: 'error', ref,
+        message: `variant ${ref} belongs to ${groups.length} groups (${groups.join(', ')}) — exactly one required`,
+      });
+    }
+  }
+
+  for (const v of variants) {
+    const grouped = owners.has(v.ref);
+    const disposed = v.vpId in map.dispositions;
+    if (!grouped && !disposed) {
+      findings.push({
+        gate: 'B', severity: 'error', ref: v.ref,
+        message: `variant ${v.ref} is in no group and has no disposition — 100% source disposition is required`,
+      });
+    }
+    if (grouped && disposed) {
+      findings.push({
+        gate: 'B', severity: 'error', ref: v.ref,
+        message: `variant ${v.ref} is grouped AND disposed (${map.dispositions[v.vpId].as}) — pick one`,
+      });
+    }
+  }
+
+  for (const vpId of Object.keys(map.dispositions)) {
+    if (!variantsByVp.has(vpId)) {
+      findings.push({
+        gate: 'B', severity: 'warning', ref: vpId,
+        message: `disposition for ${vpId} matches no scenario (stale entry?)`,
+      });
+    }
+  }
+}
+
+// --- Gate C — aggregation safety ---------------------------------------------
+
+function gateCAggregation(ctx: GateContext, findings: MatrixFinding[]): void {
+  const { map } = ctx.inputs;
+  const { variantsByVp } = ctx;
+
+  for (const g of map.groups) {
+    const vs = g.variants.flatMap((ref) => expandMapRef(ref, variantsByVp));
+    if (vs.length <= 1) continue;
+
+    // Approval IS the QA confirmation of the heuristic parts (oracle family,
+    // precondition equivalence, sequence safety) — once approved AND unchanged
+    // (fingerprints intact), only the hard signature checks keep firing. A
+    // drifted variant re-opens the heuristics (Gate E flips the item to
+    // proposed at the same time).
+    const stale = vs.some((v) => {
+      const stamped = map.fingerprints[v.ref] ?? map.fingerprints[v.vpId];
+      return !stamped || stamped !== v.fingerprint;
+    });
+    const heuristicsConfirmed = g.review === 'approved' && !stale;
+
+    // Hard signature parts — recomputed, never trusted from the map. ERROR on mismatch.
+    const hard: Array<[string, (v: CoverageVariant) => string]> = [
+      ['execution mode', (v) => v.mode],
+      ['test layer', (v) => [...v.layers].sort().join('+')],
+      ['priority', (v) => v.priority],
+    ];
+    for (const [label, keyOf] of hard) {
+      const distinct = new Set(vs.map(keyOf));
+      if (distinct.size > 1) {
+        findings.push({
+          gate: 'C', severity: 'error', ref: g.id,
+          message: `group ${g.id} mixes ${label}s (${[...distinct].join(' vs ')}) — mandatory split`,
+        });
+      }
+    }
+
+    // Heuristic signature parts — REVIEW_REQUIRED (equivalence was inferred, not declared).
+    const preProfiles = new Set(vs.map((v) => v.preconditionProfile));
+    if (!heuristicsConfirmed && preProfiles.size > 1) {
+      findings.push({
+        gate: 'C', severity: 'review', ref: g.id,
+        message: `group ${g.id} variants have different precondition profiles — confirm the grouping is safe or split`,
+      });
+    }
+    const oracleShapes = new Set(vs.map((v) => v.oracleShape.join(' ; ')));
+    if (!heuristicsConfirmed && oracleShapes.size > 1) {
+      findings.push({
+        gate: 'C', severity: 'review', ref: g.id,
+        message: `group ${g.id} variants assert different oracle shapes (${oracleShapes.size} shapes) — confirm they are one oracle family`,
+      });
+    }
+    if (!heuristicsConfirmed && vs.some((v) => v.procedureProfile === 'sequence')) {
+      findings.push({
+        gate: 'C', severity: 'review', ref: g.id,
+        message: `group ${g.id} contains a sequence-sensitive scenario — ordered flows stay solo items unless QA confirms`,
+      });
+    }
+
+    if (vs.length > MAX_VARIANTS_PER_ITEM) {
+      findings.push({
+        gate: 'C', severity: 'warning', ref: g.id,
+        message: `group ${g.id} has ${vs.length} variants (> ${MAX_VARIANTS_PER_ITEM}) — consider splitting for reviewability`,
+      });
+    }
+  }
+}
+
+// --- Gate D — manual executability -------------------------------------------
+
+function gateDExecutability(ctx: GateContext, findings: MatrixFinding[]): void {
+  const { map, testData, feature } = ctx.inputs;
+  const { variantsByVp } = ctx;
+
+  for (const g of map.groups) {
+    const vs = g.variants.flatMap((ref) => expandMapRef(ref, variantsByVp));
+    for (const v of vs) {
+      const hasPrecondition = v.precondition.length > 0 || feature.backgroundGivenSteps.length > 0;
+      if (!hasPrecondition) {
+        findings.push({
+          gate: 'D', severity: 'error', ref: v.ref,
+          message: `${v.ref}: no precondition (no Background, auth tag, or Given) — a tester cannot establish the start state`,
+        });
+      }
+      if (v.trigger.length === 0) {
+        findings.push({
+          gate: 'D', severity: 'error', ref: v.ref,
+          message: `${v.ref}: no action/trigger (no When steps${v.mode === 'manual' ? ' and no Setup/Action comment lines' : ''})`,
+        });
+      }
+      // Oracle emptiness is Gate A (source) — not repeated here.
+    }
+  }
+
+  // Every {{var}} must resolve — data the tester cannot obtain is not executable.
+  for (const [vpId, vs] of variantsByVp) {
+    const scenario = ctx.inputs.merged.find((m) => splitVpAndName(m.feature.name).vpId === vpId);
+    if (!scenario) continue;
+    for (const varName of scenario.feature.referencedVars) {
+      const inRows = vs.some((v) => v.caseLabel !== undefined); // dataset rows carry their own columns
+      if (!inRows && (!testData || !(varName in testData))) {
+        findings.push({
+          gate: 'D', severity: 'error', ref: vpId,
+          message: `${vpId}: {{${varName}}} does not resolve in test-data — the variant is not reproducible`,
+        });
+      }
+    }
+  }
+}
+
+// --- Gate E — drift (stale approval) ------------------------------------------
+
+function gateEDrift(ctx: GateContext, findings: MatrixFinding[]): void {
+  const { map } = ctx.inputs;
+  const { variantsByVp } = ctx;
+
+  for (const g of map.groups) {
+    if (g.review !== 'approved') continue; // proposed groups are already under review
+    for (const ref of g.variants) {
+      const vs = expandMapRef(ref, variantsByVp);
+      for (const v of vs) {
+        const stamped = map.fingerprints[v.ref] ?? map.fingerprints[v.vpId];
+        if (!stamped) {
+          findings.push({
+            gate: 'E', severity: 'review', ref: g.id,
+            message: `group ${g.id}: ${v.ref} has no stamped fingerprint — run \`sungen delivery --approve\` after review`,
+          });
+        } else if (stamped !== v.fingerprint) {
+          findings.push({
+            gate: 'E', severity: 'review', ref: g.id,
+            message: `group ${g.id}: ${v.ref} changed since approval (fingerprint drift) — re-review the grouping`,
+          });
+        }
+      }
+    }
+  }
+}
+
+// --- Gate G — review state -----------------------------------------------------
+
+function gateGReviewState(ctx: GateContext, findings: MatrixFinding[]): void {
+  const proposed = ctx.inputs.map.groups.filter((g) => g.review !== 'approved');
+  if (proposed.length > 0) {
+    findings.push({
+      gate: 'G', severity: 'review',
+      message: `${proposed.length} group(s) still \`proposed\` (${proposed.slice(0, 5).map((g) => g.id).join(', ')}${proposed.length > 5 ? ', …' : ''}) — approve them or render with --preview`,
+    });
+  }
+}

package/src/exporters/matrix/map-loader.ts

@@ -0,0 +1,142 @@
+/**
+ * Delivery Map loader — `qa/<kind>/<unit>/delivery/<unit>.map.yaml`.
+ *
+ * Structural validation only (shape, required fields, enum values, duplicate ids).
+ * Semantic validation against the .feature is the gates' job (gates.ts) — the loader
+ * never reads the feature.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { DeliveryMap, MapCategory, MapDisposition, MapGroup, ReviewState } from './types';
+
+const CATEGORIES: MapCategory[] = ['normal', 'abnormal', 'security', 'nfr'];
+const REVIEW_STATES: ReviewState[] = ['proposed', 'approved'];
+const DISPOSITIONS = ['excluded', 'blocked', 'covered_elsewhere', 'accepted_risk'];
+
+export interface MapLoadResult {
+  map: DeliveryMap | null;
+  /** Structural problems — any entry blocks the matrix path (fix the file first). */
+  errors: string[];
+}
+
+/** Path of the map file for a unit directory (qa/<kind>/<screen>) + feature basename. */
+export function mapFilePath(unitDir: string, featureBaseName: string): string {
+  return path.join(unitDir, 'delivery', `${featureBaseName}.map.yaml`);
+}
+
+export function loadDeliveryMap(file: string): MapLoadResult {
+  if (!fs.existsSync(file)) return { map: null, errors: [] };
+  const errors: string[] = [];
+  let raw: unknown;
+  try {
+    raw = parseYaml(fs.readFileSync(file, 'utf-8'));
+  } catch (e) {
+    return { map: null, errors: [`map YAML does not parse: ${e instanceof Error ? e.message : e}`] };
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { map: null, errors: ['map root must be a YAML mapping'] };
+  }
+  const doc = raw as Record<string, unknown>;
+
+  const groups: MapGroup[] = [];
+  const seenIds = new Set<string>();
+  const rawGroups = doc.groups;
+  if (!Array.isArray(rawGroups) || rawGroups.length === 0) {
+    errors.push('map has no `groups` list');
+  } else {
+    rawGroups.forEach((g, i) => {
+      if (!g || typeof g !== 'object') { errors.push(`groups[${i}] is not a mapping`); return; }
+      const grp = g as Record<string, unknown>;
+      const where = `groups[${i}]${typeof grp.id === 'string' ? ` (${grp.id})` : ''}`;
+      for (const field of ['id', 'target', 'intent', 'oracle'] as const) {
+        if (typeof grp[field] !== 'string' || !(grp[field] as string).trim()) {
+          errors.push(`${where}: missing/empty \`${field}\``);
+        }
+      }
+      if (!CATEGORIES.includes(grp.category as MapCategory)) {
+        errors.push(`${where}: \`category\` must be one of ${CATEGORIES.join(' | ')}`);
+      }
+      const review = (grp.review ?? 'proposed') as ReviewState;
+      if (!REVIEW_STATES.includes(review)) {
+        errors.push(`${where}: \`review\` must be proposed | approved`);
+      }
+      const variants = grp.variants;
+      if (!Array.isArray(variants) || variants.length === 0 || variants.some((v) => typeof v !== 'string' || !v.trim())) {
+        errors.push(`${where}: \`variants\` must be a non-empty list of VP refs`);
+      }
+      const id = String(grp.id ?? '');
+      if (id) {
+        if (seenIds.has(id)) errors.push(`duplicate group id \`${id}\``);
+        seenIds.add(id);
+      }
+      groups.push({
+        id,
+        target: String(grp.target ?? ''),
+        intent: String(grp.intent ?? ''),
+        oracle: String(grp.oracle ?? ''),
+        category: grp.category as MapCategory,
+        review,
+        variants: Array.isArray(variants) ? variants.map(String) : [],
+      });
+    });
+  }
+
+  const dispositions: Record<string, MapDisposition> = {};
+  if (doc.dispositions !== undefined) {
+    if (!doc.dispositions || typeof doc.dispositions !== 'object' || Array.isArray(doc.dispositions)) {
+      errors.push('`dispositions` must be a mapping of VP-id → { as, reason }');
+    } else {
+      for (const [vpId, d] of Object.entries(doc.dispositions as Record<string, unknown>)) {
+        const dd = (d && typeof d === 'object' ? d : {}) as Record<string, unknown>;
+        if (!DISPOSITIONS.includes(String(dd.as))) {
+          errors.push(`dispositions.${vpId}: \`as\` must be one of ${DISPOSITIONS.join(' | ')}`);
+        }
+        dispositions[vpId] = { as: dd.as as MapDisposition['as'], reason: dd.reason ? String(dd.reason) : undefined };
+      }
+    }
+  }
+
+  const fingerprints: Record<string, string> = {};
+  if (doc.fingerprints && typeof doc.fingerprints === 'object' && !Array.isArray(doc.fingerprints)) {
+    for (const [k, v] of Object.entries(doc.fingerprints as Record<string, unknown>)) {
+      fingerprints[k] = String(v);
+    }
+  }
+
+  const map: DeliveryMap = {
+    version: Number(doc.version ?? 1),
+    unit: String(doc.unit ?? ''),
+    formNo: doc.form_no !== undefined ? String(doc.form_no) : undefined,
+    groups,
+    dispositions,
+    fingerprints,
+  };
+  return { map: errors.length > 0 ? null : map, errors };
+}
+
+/**
+ * Write the map back (used by `--approve` to flip review states + stamp fingerprints).
+ * Field order is kept stable so approve-diffs stay minimal and reviewable.
+ */
+export function writeDeliveryMap(file: string, map: DeliveryMap): void {
+  const doc: Record<string, unknown> = {
+    version: map.version,
+    unit: map.unit,
+    ...(map.formNo !== undefined ? { form_no: map.formNo } : {}),
+    groups: map.groups.map((g) => ({
+      id: g.id,
+      target: g.target,
+      intent: g.intent,
+      oracle: g.oracle,
+      category: g.category,
+      review: g.review,
+      variants: g.variants,
+    })),
+    ...(Object.keys(map.dispositions).length > 0 ? { dispositions: map.dispositions } : {}),
+    ...(Object.keys(map.fingerprints).length > 0 ? { fingerprints: map.fingerprints } : {}),
+  };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, stringifyYaml(doc, { lineWidth: 0 }), 'utf-8');
+}

package/src/exporters/matrix/render-csv.ts

@@ -0,0 +1,71 @@
+/**
+ * Flat CSV rendering of the matrix — same model as the workbook, one row per
+ * delivery item (`Level: item`) followed by its variant rows (`Level: variant`),
+ * so downstream pipelines can re-derive both views from one file.
+ */
+
+import { statusToTestResult, formatExecutedDate } from '../playwright-report-parser';
+import { MatrixModel } from './types';
+
+const HEADERS = [
+  'Level', 'ID', 'Target', 'Test Intent / Condition', 'Category', 'Priority',
+  'Precondition', 'Coverage / Test Data', 'Action / Trigger', 'Expected (Oracle)',
+  'Mode', 'Trace', 'Result', 'Executed Date', 'Note',
+];
+
+function esc(value: string): string {
+  if (/[",\n]/.test(value)) return `"${value.replace(/"/g, '""')}"`;
+  return value;
+}
+
+export function renderMatrixCsv(model: MatrixModel): string {
+  const BOM = '\ufeff'; // Excel compatibility (Vietnamese/Japanese content)
+  const lines: string[] = [];
+  lines.push(`# Test Case & Coverage Matrix — ${model.unit}`);
+  lines.push(`# delivery items: ${model.manifest.itemCount} · coverage variants: ${model.manifest.variantCount} · state: ${model.manifest.approvalState}`);
+  lines.push(HEADERS.map(esc).join(','));
+
+  for (const item of model.items) {
+    const single = item.variants.length === 1;
+    const only = single ? item.variants[0] : undefined;
+    lines.push([
+      'item',
+      item.id,
+      item.target,
+      item.intent,
+      item.category,
+      item.priority,
+      item.precondition.join('\n'),
+      single ? only!.data.join('\n') : `${item.variants.length} variants`,
+      item.trigger.join('\n'),
+      item.oracle,
+      item.mode === 'manual' ? 'Manual' : 'Auto',
+      item.traces.join(' '),
+      item.result,
+      single ? formatExecutedDate(only!.result?.startTime) : '',
+      item.review === 'proposed' ? 'REVIEW REQUIRED' : '',
+    ].map(esc).join(','));
+
+    if (!single) {
+      for (const v of item.variants) {
+        lines.push([
+          'variant',
+          v.ref,
+          '',
+          v.condition,
+          '', '',
+          '',
+          v.data.join('\n'),
+          v.trigger.join('\n'),
+          v.oracle.join('\n'),
+          v.mode === 'manual' ? 'Manual' : 'Auto',
+          v.traces.join(' '),
+          v.result ? statusToTestResult(v.result.status) : 'Pending',
+          formatExecutedDate(v.result?.startTime),
+          v.result?.error ? String(v.result.error).slice(0, 200) : '',
+        ].map(esc).join(','));
+      }
+    }
+  }
+  return BOM + lines.join('\n') + '\n';
+}