@sun-asterisk/sungen 3.2.20-beta.5 → 3.2.21-beta.1

package/src/exporters/matrix/export.ts

@@ -8,6 +8,7 @@
  */
 
 import * as fs from 'fs';
+import { loadApiCatalog } from '../api-catalog-loader';
 import { parseFeatureMetadata } from '../feature-parser';
 import { parseSpecFile } from '../spec-parser';
 import { loadTestData } from '../test-data-resolver';
@@ -23,11 +24,18 @@ import { buildMatrix, deriveVariants } from './build';
 import { renderMatrixXlsx } from './render-xlsx';
 import { renderMatrixCsv } from './render-csv';
 import { DeliveryMap, MatrixFinding, MatrixModel } from './types';
+import { ApiCatalogEntry } from '../types';
 
 export interface MatrixTargetPaths {
   cwd: string;
   /** Feature basename — names the deliverable files. */
   unit: string;
+  /** Unit kind — 'api' loads the endpoint catalog so cells render request blocks.
+   *  Optional for back-compat: absent means non-api (no catalog). */
+  kind?: 'screen' | 'flow' | 'api';
+  /** Area/screen directory name (differs from `unit` for sub-features) — keys the
+   *  unit-level apis.yaml path. Defaults to `unit`. */
+  area?: string;
   /** Display label (flow/… prefix for flows). */
   label: string;
   featureFile: string;
@@ -45,6 +53,11 @@ function readSpecText(paths: MatrixTargetPaths): string {
     : '';
 }
 
+/** apis.yaml endpoint catalog for an api unit ({} for screen/flow — loader no-ops). */
+function catalogFor(paths: MatrixTargetPaths): Record<string, ApiCatalogEntry> {
+  return loadApiCatalog(paths.cwd, paths.kind ?? 'screen', paths.area ?? paths.unit);
+}
+
 export interface MatrixLoadResult {
   model?: MatrixModel;
   map?: DeliveryMap;
@@ -75,6 +88,7 @@ export function loadMatrixModel(paths: MatrixTargetPaths): MatrixLoadResult {
     map,
     transformerVersion: getPackageVersion(),
     specText: readSpecText(paths),
+    apiCatalog: catalogFor(paths),
   });
   // Perf verdict (#569): budgets are config (qa/perf.yaml), samples are the run's
   // per-test durations. Advisory — reported here because delivery is where runs
@@ -106,15 +120,17 @@ export function approveMatrix(paths: MatrixTargetPaths, groupIds?: string[]): {
   const merged = mergeFeatureAndSpec(feature, spec);
   const testData = fs.existsSync(paths.testDataFile) ? loadTestData(paths.testDataFile, process.env.SUNGEN_ENV ?? null) : null;
 
+  const apiCatalog = catalogFor(paths);
   const model = buildMatrix({
     unit: paths.unit, feature, merged, testData, results: null, map,
     transformerVersion: getPackageVersion(),
     specText: readSpecText(paths),
+    apiCatalog,
   });
   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 variants = deriveVariants({ feature, merged, testData, results: null, apiCatalog });
   const byRef = new Map(variants.map((v) => [v.ref, v] as const));
   const byVp = new Map<string, typeof variants>();
   for (const v of variants) {

package/src/exporters/matrix/gates.ts

@@ -248,7 +248,13 @@ function gateDExecutability(ctx: GateContext, findings: MatrixFinding[]): void {
   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 || bucketTexts(feature.backgroundOrderedSteps, 'given').length > 0;
+      // An api-first variant (`@api:` calls, no UI steps) legitimately has no UI start
+      // state — the request blocks in its trigger (Method/API/Header/Body) carry
+      // everything a tester needs. Demanding a Background/Given here blocked 100% of
+      // api-first units (field report 3.2.19).
+      const hasPrecondition = v.precondition.length > 0
+        || bucketTexts(feature.backgroundOrderedSteps, 'given').length > 0
+        || v.apiCalls > 0;
       if (!hasPrecondition) {
         findings.push({
           gate: 'D', severity: 'error', ref: v.ref,

package/src/exporters/matrix/types.ts

@@ -98,6 +98,11 @@ export interface CoverageVariant {
   /** Variables this scenario produces at RUN TIME (`remember … as {{v}}`, capability
    *  bindings) — they never exist in test-data, so Gate D must not demand them. */
   runtimeVars: string[];
+  /** Count of `@api:<name>` invocations. An api-first variant's start state lives in
+   *  its request blocks (Method/API/Header/Body), so Gate D's precondition demand is
+   *  waived when this is > 0 — requiring a Background/Given blocked EVERY api-first
+   *  unit (field report 3.2.19). */
+  apiCalls: number;
   /** Condition summary: differentiating dimension shown on the sub-row. */
   condition: string;
   /** Resolved data pairs (test-data values / dataset-row columns), `key: value` lines. */

package/src/harness/script-check.ts

@@ -43,7 +43,10 @@ export function extractTestBlocks(specSrc: string): { title: string; body: strin
   const lines = specSrc.split('\n');
   const blocks: { title: string; body: string[] }[] = [];
   for (let i = 0; i < lines.length; i++) {
-    const m = lines[i].match(/\btest(?:\.(?:only|skip|fixme))?\(\s*(['"`])([^'"`]+)\1/);
+    // Same escape-aware title match as extractTestTitles — with `[^'"`]+` a
+    // quote-bearing title extracted truncated (or not at all), missed the
+    // automatedTitles lookup, and silently dropped out of the BYPASS scan.
+    const m = lines[i].match(/\btest(?:\.(?:only|skip|fixme))?\(\s*(['"`])((?:\\.|(?!\1).)+)\1/);
     if (!m) continue;
     let depth = 0, started = false;
     const body: string[] = [];
@@ -52,7 +55,7 @@ export function extractTestBlocks(specSrc: string): { title: string; body: strin
       body.push(lines[j]);
       if (started && depth <= 0) break;
     }
-    blocks.push({ title: m[2].trim(), body });
+    blocks.push({ title: unescapeJsLiteral(m[2]).trim(), body });
   }
   return blocks;
 }
@@ -104,13 +107,24 @@ function extractTestTitles(specSrc: string): string[] {
   // Count real test cases only. Web/Playwright specs use test(...) (+ .only/.skip/.fixme);
   // mobile/Appium specs use mocha it(...) (#429 — matching only test() reported EVERY mobile
   // scenario as MISSING). Exclude describe / hooks (not test cases).
+  // The content match is escape-aware and excludes ONLY the actual delimiter (same
+  // pattern as spec-parser.ts): the old `[^'"`]+` class truncated a title at its
+  // escaped same-quote (`lottery\'s` → EXTRA `lottery\` + the real title MISSING)
+  // and dropped a title containing an other-quote (`the "x" case`) entirely — so
+  // in-sync specs of quote-bearing scenarios failed the CI gate (field report 3.2.19).
   const titles: string[] = [];
-  const re = /\b(?:test|it)(?:\.(?:only|skip|fixme))?\(\s*(['"`])([^'"`]+)\1/g;
+  const re = /\b(?:test|it)(?:\.(?:only|skip|fixme))?\(\s*(['"`])((?:\\.|(?!\1).)+)\1/g;
   let m: RegExpExecArray | null;
-  while ((m = re.exec(specSrc))) titles.push(m[2].trim());
+  while ((m = re.exec(specSrc))) titles.push(unescapeJsLiteral(m[2]).trim());
   return titles;
 }
 
+/** Undo the compiler's escapeQuotes escaping (\' \\ \n \r \t) so extracted titles
+ *  compare against the raw scenario names from the .feature. */
+function unescapeJsLiteral(s: string): string {
+  return s.replace(/\\(.)/g, (_m, c: string) => (c === 'n' ? '\n' : c === 'r' ? '\r' : c === 't' ? '\t' : c));
+}
+
 function normalize(src: string): string {
   return src
     .split('\n')

package/src/harness/spec-coverage.ts

@@ -90,14 +90,19 @@ export function parseSpecClauses(specPath: string): { frs: FrClause[]; valRows:
   }
 
   // Validation Rules table: a row carries a Constraint, a Trigger cell, and (often) a code.
+  // A "Trigger" column alone is NOT enough to claim the table (#578): a screen-STATES table
+  // ("State ID | Trigger | URL/heading oracle | …") uses Trigger for the user action that
+  // enters the state, and reading it as validation rows invented three gate-relevant
+  // TRIGGER-UNCOVERED gaps on a real spec. The table must also name a Constraint/Rule/
+  // Validation column — the thing a validation row is ABOUT.
   const valRows: ValRow[] = [];
   let cTrigger = -1, cConstraint = -1, cCode = -1, inTable = false;
   for (const raw of lines) {
     const line = raw.trim();
-    if (line.startsWith('|') && /\btrigger\b/i.test(line) && cTrigger < 0) {
+    if (line.startsWith('|') && /\btrigger\b/i.test(line) && /\b(constraint|rule|validation)\b/i.test(line) && cTrigger < 0) {
       const cells = line.split('|').map((c) => c.trim());
       cTrigger = cells.findIndex((c) => /^trigger$/i.test(c));
-      cConstraint = cells.findIndex((c) => /constraint/i.test(c));
+      cConstraint = cells.findIndex((c) => /constraint|rule|validation/i.test(c));
       cCode = cells.findIndex((c) => /code/i.test(c));
       inTable = cTrigger >= 0;
       continue;