@shanyucoder/flowgrid 0.1.5 → 0.1.8

package/engines/shared/resolve-flowgrid-context.mjs

@@ -0,0 +1,176 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { ENV_TESTS_DOC, resolveTestsDocsRoot } from './flowgrid-tests-docs.mjs';
+
+export const ENV_DOCS_ROOT = 'FLOWGRID_DOCS_ROOT';
+export const ENV_PROJECT_ROOT = 'FLOWGRID_PROJECT_ROOT';
+export const ENV_E2E_ROOT = 'FLOWGRID_E2E_ROOT';
+
+/**
+ * @param {string} [cwd]
+ * @returns {object | null}
+ */
+export function loadFlowgridConfig(cwd = process.cwd()) {
+  const configPath = path.join(path.resolve(cwd), '.flowgrid', 'config.json');
+  if (!fs.existsSync(configPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string | null | undefined} relOrAbs
+ * @param {string} baseDir
+ * @returns {string | null}
+ */
+function resolveHubPath(relOrAbs, baseDir) {
+  if (!relOrAbs || typeof relOrAbs !== 'string' || !relOrAbs.trim()) return null;
+  const trimmed = relOrAbs.trim();
+  if (path.isAbsolute(trimmed)) return path.resolve(trimmed);
+  return path.resolve(baseDir, trimmed);
+}
+
+/**
+ * Docs hub pointer from config (FE lane first, then BE).
+ * @param {object | null | undefined} config
+ */
+export function docsRootFromConfig(config) {
+  if (!config || config.type === 'Document') return null;
+  const rel = config.frontend?.docsRoot ?? config.backend?.docsRoot ?? null;
+  return rel || null;
+}
+
+/**
+ * Tests-docs hub pointer from config.
+ * @param {object | null | undefined} config
+ */
+export function testsRootFromConfig(config) {
+  if (!config || config.type === 'Test') return null;
+  const rel = config.frontend?.testsRoot ?? config.backend?.testsRoot ?? null;
+  return rel || null;
+}
+
+/**
+ * E2e automation root from config.
+ * @param {object | null | undefined} config
+ */
+export function e2eRootFromConfig(config) {
+  if (!config) return null;
+  const rel = config.frontend?.e2eRoot ?? config.backend?.e2eRoot ?? null;
+  return rel || null;
+}
+
+/**
+ * Strip hub path flags from argv for downstream engines.
+ * @param {string[]} argv
+ * @returns {{ argv: string[]; docsRoot: string | null; testsDocs: string | null; e2eRoot: string | null; projectRoot: string | null }}
+ */
+export function extractFlowgridPathFlags(argv, baseDir = process.cwd()) {
+  const out = [];
+  let docsRoot = null;
+  let testsDocs = null;
+  let e2eRoot = null;
+  let projectRoot = null;
+  const cwd = path.resolve(baseDir);
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--docs-root' && argv[i + 1]) {
+      docsRoot = path.resolve(cwd, argv[++i]);
+      continue;
+    }
+    if (arg === '--tests-docs' && argv[i + 1]) {
+      testsDocs = path.resolve(cwd, argv[++i]);
+      continue;
+    }
+    if (arg === '--e2e-root' && argv[i + 1]) {
+      e2eRoot = path.resolve(cwd, argv[++i]);
+      continue;
+    }
+    if (arg === '--project-root' && argv[i + 1]) {
+      projectRoot = path.resolve(cwd, argv[++i]);
+      continue;
+    }
+    out.push(arg);
+  }
+
+  return { argv: out, docsRoot, testsDocs, e2eRoot, projectRoot };
+}
+
+/**
+ * Resolve docs hub absolute path.
+ * Priority: CLI --docs-root → FLOWGRID_DOCS_ROOT → config frontend|backend.docsRoot → Document type = cwd.
+ *
+ * @param {{ cwd?: string; config?: object | null; argv?: string[]; env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {{ docsRoot: string | null; argv: string[]; projectRoot: string }}
+ */
+export function resolveFlowgridContext(opts = {}) {
+  const cwd = path.resolve(opts.cwd ?? process.cwd());
+  const env = opts.env ?? process.env;
+  const config = opts.config !== undefined ? opts.config : loadFlowgridConfig(cwd);
+  const extracted = extractFlowgridPathFlags(opts.argv ?? [], cwd);
+
+  const projectRoot = extracted.projectRoot
+    ?? (env[ENV_PROJECT_ROOT] ? path.resolve(env[ENV_PROJECT_ROOT]) : cwd);
+
+  let docsRoot = extracted.docsRoot;
+  if (!docsRoot && env[ENV_DOCS_ROOT]) {
+    docsRoot = path.resolve(env[ENV_DOCS_ROOT]);
+  }
+  if (!docsRoot && config?.type === 'Document') {
+    docsRoot = projectRoot;
+  }
+  if (!docsRoot) {
+    const rel = docsRootFromConfig(config);
+    docsRoot = resolveHubPath(rel, projectRoot);
+  }
+
+  let testsDocs = extracted.testsDocs ?? resolveTestsDocsRoot(null);
+  if (!testsDocs) {
+    const rel = testsRootFromConfig(config);
+    testsDocs = resolveHubPath(rel, projectRoot);
+  }
+
+  let e2eRoot = extracted.e2eRoot;
+  if (!e2eRoot && env[ENV_E2E_ROOT]) {
+    e2eRoot = path.resolve(env[ENV_E2E_ROOT]);
+  }
+  if (!e2eRoot) {
+    const rel = e2eRootFromConfig(config);
+    e2eRoot = resolveHubPath(rel, projectRoot);
+  }
+
+  return {
+    projectRoot,
+    docsRoot,
+    testsDocs,
+    e2eRoot,
+    argv: extracted.argv,
+    config,
+  };
+}
+
+/**
+ * @param {{ cwd?: string; config?: object | null; argv?: string[]; env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {string | null}
+ */
+export function resolveDocsRoot(opts = {}) {
+  return resolveFlowgridContext(opts).docsRoot;
+}
+
+/**
+ * Apply resolved hub env for child processes (only sets when value known).
+ * @param {ReturnType<typeof resolveFlowgridContext>} ctx
+ * @param {NodeJS.ProcessEnv} [base]
+ */
+export function flowgridContextToEnv(ctx, base = {}) {
+  const env = { ...base };
+  if (ctx.docsRoot) env[ENV_DOCS_ROOT] = ctx.docsRoot;
+  if (ctx.testsDocs) env[ENV_TESTS_DOC] = ctx.testsDocs;
+  if (ctx.e2eRoot) env[ENV_E2E_ROOT] = ctx.e2eRoot;
+  env[ENV_PROJECT_ROOT] = ctx.projectRoot;
+  return env;
+}

package/engines/spec/lib/audit-api-gaps.mjs

@@ -2,7 +2,7 @@
 
 /**
  * audit-api-gaps.mjs
- * Zero-dependency static audit script for FlowGrid API Contracts (backend-api.bundle.yaml, backend-api-integration.yaml).
+ * Zero-dependency static audit for API contracts — target SSOT: `01-backend-spec.yaml` (legacy bundle-with-spec.api still parseable).
  * Ensures 100% adherence to API payload rules, SLA, async events, and resilience policies.
  */
 

package/engines/spec/lib/audit-bundle-gaps.mjs

@@ -13,13 +13,15 @@
  * pageType: list | create | detail | admin-crud | auth | change-password | public | not-found | error
  * If --type is omitted, script auto-detects from codegen.profile or design.shell.tag.
  *
- * Output: JSON with gaps[] (missing required) + confirms[] (optional, agent must ask member).
- * UX affordance checks (flowgrid-ux-common) merge in with category "ux" and codes UX_* / CONFIRM_UX_*.
+ * Output: JSON with gaps[] (missing required) + confirms[] (optional wizard) + warnings[] (quality — never blocks split).
+ * UX affordance: category "ux" (UX_* / CONFIRM_UX_*). DB tables: category "db" (CONFIRM_DB_*).
  */
 
 import fs from 'fs';
 import path from 'path';
+import { parse } from 'yaml';
 import { auditUxAffordance } from './audit-ux-affordance.mjs';
+import { auditDbTables, resolveBackendSpecForBundle } from './audit-db-tables.mjs';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -111,6 +113,7 @@ function hasMutationActions(rawText) {
 function auditBundleContent(rawText, filePath, pageType) {
   const gaps = [];
   const confirms = [];
+  const warnings = [];
 
   function addGap(code, severity, fieldPath, message, suggestedFix) {
     gaps.push({ code, severity, type: 'gap', path: fieldPath, message, suggestedFix });
@@ -127,6 +130,17 @@ function auditBundleContent(rawText, filePath, pageType) {
     });
   }
 
+  function addWarning(code, fieldPath, message, suggestedFix) {
+    warnings.push({
+      code,
+      type: 'warning',
+      category: 'quality',
+      path: fieldPath,
+      message,
+      suggestedFix
+    });
+  }
+
   // =========================================================================
   // ALL PAGES — Required fields
   // =========================================================================
@@ -528,6 +542,51 @@ function auditBundleContent(rawText, filePath, pageType) {
   const uxGaps = gaps.filter((g) => g.category === 'ux').length;
   const uxConfirms = confirms.filter((c) => c.category === 'ux').length;
 
+  // =========================================================================
+  // Quality warnings (non-blocking — does not affect totalGaps for structure)
+  // =========================================================================
+
+  if (!has(rawText, 'successMetrics:')) {
+    addWarning(
+      'WARN_NO_SUCCESS_METRICS',
+      'successMetrics',
+      'successMetrics not declared — add when PO has measurable or qualitative targets.',
+      'Declare successMetrics: | with 1–3 bullets (see bundle-authoring.md).'
+    );
+  }
+
+  if (!has(rawText, 'nonGoals:')) {
+    addWarning(
+      'WARN_NO_NON_GOALS',
+      'nonGoals',
+      'nonGoals not declared — clarify out-of-scope for this screen/phase.',
+      'Declare nonGoals: | with explicit non-scope bullets.'
+    );
+  }
+
+  const placeholderCue = /\[[^\]]{8,}\]/;
+  if (has(rawText, 'summary:') && placeholderCue.test(rawText)) {
+    addWarning(
+      'WARN_SUMMARY_PLACEHOLDER',
+      'summary',
+      'Summary or related prose still contains bracket placeholders `[...]`.',
+      'Replace template brackets with real Vietnamese business copy before stakeholder sign-off.'
+    );
+  }
+
+  if (
+    has(rawText, 'messages:') &&
+    has(rawText, 'required:') &&
+    !hasAny(rawText, ['Trường này', 'bắt buộc', 'không được để trống', 'Vui lòng'])
+  ) {
+    addWarning(
+      'WARN_VALIDATION_MSG_GENERIC',
+      'design.sections',
+      'Validation messages may still use generic English — prefer explicit Vietnamese copy per field.',
+      'Set messages.* on each validated field (see bundle-authoring.md).'
+    );
+  }
+
   // =========================================================================
   // Result
   // =========================================================================
@@ -537,13 +596,15 @@ function auditBundleContent(rawText, filePath, pageType) {
     detectedType: pageType,
     totalGaps: gaps.length,
     totalConfirms: confirms.length,
+    totalWarnings: warnings.length,
     uxAffordanceGaps: uxGaps,
     uxAffordanceConfirms: uxConfirms,
     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,
-    confirms
+    confirms,
+    warnings
   };
 }
 
@@ -579,4 +640,32 @@ if (!fs.existsSync(targetFile)) {
 const rawText = fs.readFileSync(targetFile, 'utf8');
 const pageType = typeArg || detectPageType(rawText);
 const report = auditBundleContent(rawText, targetFile, pageType);
+
+try {
+  const bundle = parse(rawText);
+  const backendResolved = resolveBackendSpecForBundle(targetFile, null);
+  const backendText =
+    backendResolved && fs.existsSync(backendResolved)
+      ? fs.readFileSync(backendResolved, 'utf8')
+      : '';
+  const dbReport = auditDbTables({
+    bundle,
+    backendText,
+    backendSpecFound: !!(backendResolved && fs.existsSync(backendResolved)),
+    filePath: targetFile,
+  });
+  report.confirms.push(...dbReport.confirms);
+  report.warnings.push(...dbReport.warnings);
+  report.totalConfirms = report.confirms.length;
+  report.totalWarnings = report.warnings.length;
+  report.dbTables = {
+    tables: dbReport.tables,
+    bindingCount: dbReport.bindings?.length ?? 0,
+    dbConfirms: dbReport.confirms?.length ?? 0,
+    backendSpec: backendResolved ? path.relative(process.cwd(), backendResolved) : null,
+  };
+} catch {
+  // YAML parse errors are handled elsewhere; skip DB pass
+}
+
 console.log(JSON.stringify(report, null, 2));