@shanyucoder/flowgrid 0.1.0

package/engines/spec/lib/audit-e2e-coverage.mjs

@@ -0,0 +1,381 @@
+#!/usr/bin/env node
+
+/**
+ * audit-e2e-coverage.mjs
+ * Cross-check testcase YAML (tests-docs hub) vs Playwright under --e2e-root.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { parse } from 'yaml';
+import { resolveTestsDocsRoot } from '../../shared/flowgrid-tests-docs.mjs';
+
+const TC_ID_PATTERN = /^TC-[A-Z0-9][A-Z0-9-]*$/;
+const DESCRIBE_TC_RE = /test\.describe\s*\(\s*['"](TC-[^'"]+)['"]/g;
+
+function isTcYamlName(name) {
+  return /^TC-.+\.ya?ml$/i.test(name);
+}
+
+function walkFiles(root, onFile) {
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (e.name === 'node_modules' || e.name === '.git' || e.name === 'dist') continue;
+        stack.push(full);
+      } else if (e.isFile()) {
+        onFile(full, e.name);
+      }
+    }
+  }
+}
+
+/**
+ * @param {string} testsRoot
+ */
+export function scanPlaywrightTests(testsRoot) {
+  const specFiles = [];
+  const tcIdToFiles = new Map();
+
+  function linkTc(tcId, fileRec) {
+    if (!TC_ID_PATTERN.test(tcId)) return;
+    const list = tcIdToFiles.get(tcId) ?? [];
+    if (!list.includes(fileRec)) list.push(fileRec);
+    tcIdToFiles.set(tcId, list);
+  }
+
+  walkFiles(testsRoot, (full, name) => {
+    if (!/\.(spec|e2e)\.(t|j)sx?$/i.test(name)) return;
+    const text = fs.readFileSync(full, 'utf8');
+    const rec = { path: full, name, text };
+    specFiles.push(rec);
+
+    const base = name.replace(/\.(spec|e2e)\.(t|j)sx?$/i, '');
+    if (TC_ID_PATTERN.test(base)) {
+      linkTc(base, rec);
+    }
+    const pathTail = full.replace(/\\/g, '/');
+    for (const m of pathTail.matchAll(/\/(TC-[A-Z0-9][A-Z0-9-]*)\.(spec|e2e)\./gi)) {
+      linkTc(m[1], rec);
+    }
+
+    DESCRIBE_TC_RE.lastIndex = 0;
+    let dm;
+    while ((dm = DESCRIBE_TC_RE.exec(text)) !== null) {
+      linkTc(dm[1], rec);
+    }
+  });
+
+  const referencedTcIds = new Set(tcIdToFiles.keys());
+
+  return {
+    specFiles,
+    specFileCount: specFiles.length,
+    tcIdToFiles,
+    referencedTcIds,
+    combinedTextFor(tcId) {
+      const files = tcIdToFiles.get(tcId) ?? [];
+      return files.map((f) => f.text).join('\n');
+    },
+    isTcCovered(tcId) {
+      return (tcIdToFiles.get(tcId)?.length ?? 0) > 0;
+    },
+  };
+}
+
+/**
+ * @param {string} casesRoot
+ * @param {{ screen?: string }} [filter]
+ * @returns {Array<{ path: string; id: string; screen: string | null; matrix: Array<Record<string, unknown>> }>}
+ */
+export function collectTcDocuments(casesRoot, filter = {}) {
+  const docs = [];
+  walkFiles(casesRoot, (full, name) => {
+    if (!isTcYamlName(name)) return;
+    const raw = fs.readFileSync(full, 'utf8');
+    let data;
+    try {
+      data = parse(raw);
+    } catch {
+      return;
+    }
+    if (!data || typeof data !== 'object') return;
+    const id = typeof data.id === 'string' ? data.id : null;
+    if (!id || !TC_ID_PATTERN.test(id)) return;
+    const screen = data.refs?.screen ?? null;
+    if (filter.screen && screen !== filter.screen) return;
+    const matrix = Array.isArray(data.testMatrix) ? data.testMatrix : [];
+    docs.push({ path: full, id, screen, matrix, raw });
+  });
+  return docs;
+}
+
+/**
+ * @param {string} tcFilePath
+ */
+export function loadTcDocument(tcFilePath) {
+  const raw = fs.readFileSync(tcFilePath, 'utf8');
+  const data = parse(raw);
+  const id = data?.id;
+  if (!id || !TC_ID_PATTERN.test(id)) {
+    throw new Error(`Not a valid TC artifact: missing id TC-* in ${tcFilePath}`);
+  }
+  return {
+    path: path.resolve(tcFilePath),
+    id,
+    screen: data.refs?.screen ?? null,
+    matrix: Array.isArray(data.testMatrix) ? data.testMatrix : [],
+    raw,
+  };
+}
+
+function addGap(gaps, code, severity, fieldPath, message, suggestedFix) {
+  gaps.push({
+    code,
+    severity,
+    path: fieldPath,
+    message,
+    suggestedFix,
+    category: 'e2e-coverage',
+  });
+}
+
+/**
+ * @param {{ tcDocuments: Array<{ path: string; id: string; screen: string | null; matrix: unknown[] }>; e2eRoot: string; strict?: boolean; strictMatrix?: boolean }} opts
+ */
+export function auditE2eCoverage(opts) {
+  const { tcDocuments, e2eRoot, strict = false, strictMatrix = false } = opts;
+  const pw = scanPlaywrightTests(e2eRoot);
+  const gaps = [];
+  const missingInPlaywright = [];
+  const matrixRowsUncovered = [];
+  const orphanTestCases = [];
+  const documentedIds = new Set();
+
+  for (const doc of tcDocuments) {
+    documentedIds.add(doc.id);
+    if (!pw.isTcCovered(doc.id)) {
+      missingInPlaywright.push({ tcId: doc.id, tcPath: doc.path, screen: doc.screen });
+      addGap(
+        gaps,
+        'E2E_TC_MISSING',
+        strict ? 'critical' : 'warning',
+        doc.path,
+        `No Playwright spec references testcase ${doc.id} (test.describe or *${doc.id}.spec.ts under tests root).`,
+        `Add tests/e2e/**/${doc.id}.spec.ts or test.describe('${doc.id}', …) after testcase:gen.`,
+      );
+      continue;
+    }
+
+    const specBlob = pw.combinedTextFor(doc.id);
+    for (let i = 0; i < doc.matrix.length; i++) {
+      const row = doc.matrix[i];
+      const caseId = typeof row.caseId === 'string' ? row.caseId : null;
+      const facet = typeof row.facet === 'string' ? row.facet : '';
+      const desc = typeof row.description === 'string' ? row.description : '';
+      const descSnippet = desc.slice(0, 48).trim();
+
+      let rowCovered = false;
+      if (caseId && specBlob.includes(caseId)) {
+        rowCovered = true;
+      } else if (facet && specBlob.includes(facet)) {
+        rowCovered = true;
+      } else if (descSnippet.length >= 12 && specBlob.includes(descSnippet)) {
+        rowCovered = true;
+      } else if (!caseId && !strictMatrix && doc.matrix.length > 0) {
+        rowCovered = true;
+      }
+
+      if (!rowCovered) {
+        const entry = {
+          tcId: doc.id,
+          tcPath: doc.path,
+          rowIndex: i,
+          caseId,
+          facet,
+        };
+        matrixRowsUncovered.push(entry);
+        if (caseId) {
+          orphanTestCases.push({
+            kind: 'matrix_caseId',
+            tcId: doc.id,
+            caseId,
+            tcPath: doc.path,
+          });
+        }
+        const sev =
+          strictMatrix || strict ? 'critical' : caseId ? 'warning' : 'info';
+        addGap(
+          gaps,
+          caseId ? 'E2E_MATRIX_CASE_MISSING' : 'E2E_MATRIX_ROW_WEAK',
+          sev,
+          `${doc.path}#testMatrix[${i}]`,
+          caseId
+            ? `testMatrix caseId "${caseId}" not referenced in Playwright for ${doc.id}.`
+            : `testMatrix facet "${facet}" not referenced in Playwright for ${doc.id}.`,
+          caseId
+            ? `Add test title/comment referencing ${caseId}, or split matrix row into generated test.`
+            : `Reference facet "${facet}" or caseId in spec, or use --strict-matrix only when each row has caseId in codegen.`,
+        );
+      }
+    }
+  }
+
+  const orphanSpecs = [];
+  for (const tcId of pw.referencedTcIds) {
+    if (!documentedIds.has(tcId)) {
+      const files = (pw.tcIdToFiles.get(tcId) ?? []).map((f) => f.path);
+      orphanSpecs.push({ tcId, files });
+      addGap(
+        gaps,
+        'E2E_ORPHAN_SPEC',
+        'warning',
+        files[0] ?? e2eRoot,
+        `Playwright references ${tcId} but no matching TC-*.yaml was scanned.`,
+        `Remove stale spec or add cases/**/${tcId}.yaml; re-run testcase:gen from SSOT.`,
+      );
+    }
+  }
+
+  const criticalGaps = gaps.filter((g) => g.severity === 'critical').length;
+  const warningGaps = gaps.filter((g) => g.severity === 'warning').length;
+  const infoGaps = gaps.filter((g) => g.severity === 'info').length;
+
+  return {
+    kind: 'audit-e2e',
+    e2eRoot: path.resolve(e2eRoot),
+    tcDocumentCount: tcDocuments.length,
+    playwrightSpecCount: pw.specFileCount,
+    missingInPlaywright,
+    matrixRowsUncovered,
+    orphanTestCases,
+    orphanSpecs,
+    gaps,
+    totalGaps: gaps.length,
+    criticalGaps,
+    warningGaps,
+    infoGaps,
+  };
+}
+
+function parseCliArgs(argv) {
+  let e2eRoot = null;
+  let testsDocs = null;
+  let screen = null;
+  let strict = false;
+  let strictMatrix = false;
+  const tcFiles = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--e2e-root' && argv[i + 1]) {
+      e2eRoot = path.resolve(process.cwd(), argv[++i]);
+    } else if (a === '--tests-docs' && argv[i + 1]) {
+      testsDocs = path.resolve(process.cwd(), argv[++i]);
+    } else if (a === '--screen' && argv[i + 1]) {
+      screen = argv[++i];
+    } else if (a === '--strict') {
+      strict = true;
+      strictMatrix = true;
+    } else if (a === '--strict-matrix') {
+      strictMatrix = true;
+    } else if (a === '--help' || a === '-h') {
+      return { help: true };
+    } else if (!a.startsWith('-')) {
+      tcFiles.push(path.resolve(process.cwd(), a));
+    }
+  }
+
+  return { e2eRoot, testsDocs, screen, strict, strictMatrix, tcFiles };
+}
+
+function printUsage() {
+  console.log(
+    [
+      'Usage: node engines/spec/lib/audit-e2e-coverage.mjs --e2e-root <playwright-dir> [options]',
+      '       flowgrid audit e2e --e2e-root <dir> --tests-docs <tests-hub> [--screen W-*]',
+      '       flowgrid audit e2e --e2e-root <dir> <TC-*.yaml> [more…]',
+      '',
+      'Options:',
+      '  --tests-docs   Tests hub (TC YAML); or set FLOWGRID_TESTS_DOC',
+      '  --screen W-*   Filter TC docs by refs.screen',
+      '  --strict       Treat missing TC spec + matrix gaps as critical',
+      '  --strict-matrix  Require each testMatrix row signal in Playwright text',
+    ].join('\n'),
+  );
+}
+
+// CLI
+const cliArgv = process.argv.slice(2);
+if (cliArgv.length === 0) {
+  printUsage();
+  process.exit(0);
+}
+
+const parsed = parseCliArgs(cliArgv);
+if (parsed.help) {
+  printUsage();
+  process.exit(0);
+}
+
+if (!parsed.e2eRoot) {
+  console.error(JSON.stringify({ error: '--e2e-root is required (Playwright specs directory)' }));
+  process.exit(1);
+}
+
+if (!fs.existsSync(parsed.e2eRoot)) {
+  console.error(JSON.stringify({ error: `e2e-root not found: ${parsed.e2eRoot}` }));
+  process.exit(1);
+}
+
+let tcDocuments = [];
+try {
+  if (parsed.tcFiles.length) {
+    for (const f of parsed.tcFiles) {
+      if (!fs.existsSync(f)) {
+        console.error(JSON.stringify({ error: `TC file not found: ${f}` }));
+        process.exit(1);
+      }
+      tcDocuments.push(loadTcDocument(f));
+    }
+  } else {
+    const testsDocs = parsed.testsDocs ?? resolveTestsDocsRoot();
+    if (!testsDocs) {
+      console.error(
+        JSON.stringify({
+          error: 'Provide --tests-docs, FLOWGRID_TESTS_DOC, or explicit TC-*.yaml paths',
+        }),
+      );
+      process.exit(1);
+    }
+    if (!fs.existsSync(testsDocs)) {
+      console.error(JSON.stringify({ error: `tests-docs not found: ${testsDocs}` }));
+      process.exit(1);
+    }
+    tcDocuments = collectTcDocuments(testsDocs, { screen: parsed.screen ?? undefined });
+  }
+} catch (err) {
+  console.error(JSON.stringify({ error: String(err.message ?? err) }));
+  process.exit(1);
+}
+
+const report = auditE2eCoverage({
+  tcDocuments,
+  e2eRoot: parsed.e2eRoot,
+  strict: parsed.strict,
+  strictMatrix: parsed.strictMatrix,
+});
+if (parsed.testsDocs ?? resolveTestsDocsRoot()) {
+  report.testsDocs = parsed.testsDocs ?? resolveTestsDocsRoot();
+}
+
+console.log(JSON.stringify(report, null, 2));

package/engines/spec/lib/audit-fe-be-alignment.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+
+/**
+ * audit-fe-be-alignment.mjs
+ * Cross-check FE bundle design actions (apiRef) vs sibling 01-backend-spec.yaml endpoints.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+function extractApiRefsFromBundle(rawText) {
+  const refs = new Set();
+  for (const m of rawText.matchAll(/apiRef:\s*["']?([\w.-]+)["']?/g)) {
+    refs.add(m[1]);
+  }
+  for (const m of rawText.matchAll(/apiRefs:\s*\n([\s\S]*?)(?:\n\S|\n\s*\w+:\s*[^\s])/g)) {
+    const block = m[1];
+    for (const line of block.split('\n')) {
+      const item = line.match(/^\s*-\s*["']?([\w.-]+)["']?/);
+      if (item) refs.add(item[1]);
+    }
+  }
+  return [...refs];
+}
+
+function extractEndpointActions(backendText) {
+  const actions = new Set();
+  for (const m of backendText.matchAll(/action:\s*["']?([\w.-]+)["']?/g)) {
+    actions.add(m[1]);
+  }
+  for (const m of backendText.matchAll(/\bid:\s*["']?([\w.-]+)["']?/g)) {
+    if (backendText.includes('endpoints:')) actions.add(m[1]);
+  }
+  return [...actions];
+}
+
+function resolveBackendSpec(bundlePath, explicitPath) {
+  if (explicitPath) return path.resolve(process.cwd(), explicitPath);
+  const dir = path.dirname(bundlePath);
+  const candidates = [];
+  const walk = (start, depth) => {
+    if (depth > 4) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(start, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = path.join(start, e.name);
+      if (e.isDirectory()) {
+        if (e.name === 'api' || e.name.match(/^\d+$/)) walk(full, depth + 1);
+      } else if (e.name === '01-backend-spec.yaml') {
+        candidates.push(full);
+      }
+    }
+  };
+  walk(dir, 0);
+  walk(path.join(dir, 'api'), 0);
+  return candidates[0] ?? null;
+}
+
+export function auditFeBeAlignment(bundleText, backendText, meta = {}) {
+  const gaps = [];
+  const bundlePath = meta.bundlePath ?? '';
+  const backendPath = meta.backendPath ?? '';
+
+  function addGap(code, severity, fieldPath, message, suggestedFix) {
+    gaps.push({ code, severity, path: fieldPath, message, suggestedFix, category: 'fe-be' });
+  }
+
+  const apiRefs = extractApiRefsFromBundle(bundleText);
+  const hasActions = bundleText.includes('executionContract:') || bundleText.includes('apiRef:');
+
+  if (hasActions && apiRefs.length === 0) {
+    addGap(
+      'FEBE_MISSING_APIREF',
+      'warning',
+      'design.actions[].executionContract.apiRef',
+      'Bundle declares actions but no apiRef values were found.',
+      'Set executionContract.apiRef to match 01-backend-spec endpoint action id.',
+    );
+  }
+
+  if (!backendText) {
+    if (apiRefs.length > 0) {
+      addGap(
+        'FEBE_MISSING_BACKEND_SPEC',
+        'critical',
+        'api/01-backend-spec.yaml',
+        'Bundle references API but no 01-backend-spec.yaml found (pass --backend-spec).',
+        'Author /api-update on docs hub, then re-run audit with --backend-spec path.',
+      );
+    }
+    return {
+      file: bundlePath,
+      backendSpec: backendPath || null,
+      totalGaps: gaps.length,
+      gaps,
+    };
+  }
+
+  const endpointActions = extractEndpointActions(backendText);
+  const endpointSet = new Set(endpointActions.map((a) => a.toLowerCase()));
+
+  for (const ref of apiRefs) {
+    const hit =
+      endpointSet.has(ref.toLowerCase()) ||
+      backendText.includes(ref) ||
+      backendText.includes(ref.replace(/\./g, '/'));
+    if (!hit) {
+      addGap(
+        'FEBE_APIREF_UNMAPPED',
+        'warning',
+        `design.apiRef.${ref}`,
+        `Bundle apiRef "${ref}" not found on 01-backend-spec (action/id/path).`,
+        `Add endpoint with action: ${ref} or align bundle apiRef after /api-update.`,
+      );
+    }
+  }
+
+  if (backendText.includes('endpoints:') && apiRefs.length === 0 && hasActions) {
+    addGap(
+      'FEBE_ENDPOINTS_NO_FE_REFS',
+      'info',
+      'api.endpoints',
+      'Backend spec defines endpoints but bundle has no apiRef linkage.',
+      'Wire design.actions[].executionContract.apiRef to endpoint action ids.',
+    );
+  }
+
+  return {
+    file: bundlePath,
+    backendSpec: backendPath,
+    apiRefs,
+    endpointActions,
+    totalGaps: gaps.length,
+    criticalGaps: gaps.filter((g) => g.severity === 'critical').length,
+    warningGaps: gaps.filter((g) => g.severity === 'warning').length,
+    infoGaps: gaps.filter((g) => g.severity === 'info').length,
+    gaps,
+  };
+}
+
+function parseArgs(argv) {
+  let backendSpec = null;
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--backend-spec' && argv[i + 1]) {
+      backendSpec = argv[++i];
+    } else {
+      positional.push(argv[i]);
+    }
+  }
+  return { bundlePath: positional[0], backendSpec };
+}
+
+// CLI
+const args = process.argv.slice(2);
+if (args.length === 0) {
+  console.log(
+    'Usage: node audit-fe-be-alignment.mjs <bundle.yaml> [--backend-spec path/to/01-backend-spec.yaml]',
+  );
+  process.exit(0);
+}
+
+const { bundlePath: argBundle, backendSpec } = parseArgs(args);
+const resolvedBundle = path.resolve(process.cwd(), argBundle);
+if (!fs.existsSync(resolvedBundle)) {
+  console.error(JSON.stringify({ error: `File not found: ${resolvedBundle}` }));
+  process.exit(1);
+}
+const bundleText = fs.readFileSync(resolvedBundle, 'utf8');
+const backendResolved = resolveBackendSpec(resolvedBundle, backendSpec);
+const backendText =
+  backendResolved && fs.existsSync(backendResolved)
+    ? fs.readFileSync(backendResolved, 'utf8')
+    : '';
+const report = auditFeBeAlignment(bundleText, backendText, {
+  bundlePath: resolvedBundle,
+  backendPath: backendResolved,
+});
+console.log(JSON.stringify(report, null, 2));