@shanyucoder/flowgrid 0.1.4 → 0.1.8

package/engines/spec/lib/audit-db-tables.mjs

@@ -0,0 +1,529 @@
+#!/usr/bin/env node
+
+/**
+ * audit-db-tables.mjs — design db bindings vs entities / optional 01-backend-spec.
+ * Emits confirms[] (CONFIRM_DB_*) for /spec and /grill-* AskQuestion wizard; optional warnings[] for agent-only hints.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse } from 'yaml';
+
+function walkDesignNodes(nodes, visitor, ctx = {}) {
+  for (const node of nodes || []) {
+    visitor(node, ctx);
+    walkDesignNodes(node.items, visitor, { ...ctx, sectionId: node.id ?? ctx.sectionId });
+    walkDesignNodes(node.sections, visitor, { ...ctx, sectionId: node.id ?? ctx.sectionId });
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} bundle Parsed bundle YAML
+ * @returns {{ bindings: Array<Record<string, unknown>>, tables: Set<string> }}
+ */
+export function collectDesignDbBindings(bundle) {
+  const bindings = [];
+  const tables = new Set();
+  const design = bundle.design ?? {};
+  const tree = design.sections?.length ? design.sections : design.zones ?? [];
+
+  walkDesignNodes(tree, (node, ctx) => {
+    const db = node.db;
+    const bindField = node.bind?.field != null ? String(node.bind.field).trim() : '';
+    const hasDb = db && typeof db === 'object';
+    const schema = hasDb && db.schema != null ? String(db.schema).trim() : '';
+    const field = hasDb && db.field != null ? String(db.field).trim() : '';
+    const row = {
+      path: node.id ? `design.${ctx.sectionId ? `${ctx.sectionId}.` : ''}${node.id}` : 'design.sections',
+      label: node.label || node.name || node.id || '',
+      schema,
+      field,
+      bindField,
+      required: !!(node.validation?.required),
+      enumMapping: hasDb ? db.enumMapping : undefined,
+      hasDbBlock: hasDb,
+    };
+    if (hasDb || bindField || node.validation?.required) {
+      bindings.push(row);
+    }
+    if (schema) tables.add(schema);
+  });
+
+  const listColumns =
+    bundle.gen?.ui?.list?.columns ??
+    bundle.spec?.ui?.list?.columns ??
+    design.ui?.list?.columns ??
+    [];
+  for (const col of listColumns) {
+    if (!col || typeof col !== 'object') continue;
+    const db = col.db;
+    const hasDb = db && typeof db === 'object';
+    const schema = hasDb && db.schema != null ? String(db.schema).trim() : '';
+    const field = hasDb && db.field != null ? String(db.field).trim() : '';
+    bindings.push({
+      path: `spec.ui.list.columns.${col.key ?? '?'}`,
+      label: col.title || col.key || '',
+      schema,
+      field,
+      bindField: col.key != null ? String(col.key) : '',
+      required: false,
+      enumMapping: hasDb ? db.enumMapping : undefined,
+      source: 'list-column',
+      hasDbBlock: hasDb,
+      sortable: !!col.sortable,
+    });
+    if (schema) tables.add(schema);
+  }
+
+  return { bindings, tables };
+}
+
+function normalizeTableKey(name) {
+  return String(name)
+    .trim()
+    .toLowerCase()
+    .replace(/-/g, '_');
+}
+
+/**
+ * @param {string} backendText
+ * @returns {Map<string, { entityName: string, fields: Set<string> }>}
+ */
+export function indexBackendEntities(backendText) {
+  const map = new Map();
+  if (!backendText) return map;
+
+  let doc;
+  try {
+    doc = parse(backendText);
+  } catch {
+    return map;
+  }
+
+  for (const mod of doc.modules ?? []) {
+    for (const ent of mod.entities ?? []) {
+      const table = ent.table ?? ent.name;
+      if (!table) continue;
+      const key = normalizeTableKey(table);
+      const fields = new Set((ent.fields ?? []).map((f) => String(f.name).toLowerCase()));
+      const altKey = ent.name ? normalizeTableKey(ent.name) : key;
+      map.set(key, { entityName: ent.name ?? table, fields });
+      if (altKey !== key) map.set(altKey, { entityName: ent.name ?? table, fields });
+    }
+  }
+  return map;
+}
+
+function entityNamesFromSpec(bundle) {
+  const ents = bundle.spec?.entities ?? bundle.design?.entities ?? [];
+  if (!Array.isArray(ents)) return new Set();
+  return new Set(
+    ents
+      .map((e) => (typeof e === 'string' ? e : e?.name ?? e?.table ?? ''))
+      .filter(Boolean)
+      .map((n) => normalizeTableKey(n)),
+  );
+}
+
+const DEBT_OPTION = 'Log as Tech Debt (Pending)';
+
+/**
+ * @param {{
+ *   bundle?: Record<string, unknown>,
+ *   bundleText?: string,
+ *   backendText?: string,
+ *   backendSpecFound?: boolean,
+ *   filePath?: string,
+ * }} input
+ */
+export function auditDbTables(input = {}) {
+  const warnings = [];
+  const confirms = [];
+  const filePath = input.filePath ?? '';
+
+  function addWarning(code, fieldPath, message, suggestedFix) {
+    warnings.push({
+      code,
+      type: 'warning',
+      category: 'db',
+      path: fieldPath,
+      message,
+      suggestedFix,
+    });
+  }
+
+  function addConfirm(code, fieldPath, question, options, defaultRecommend = 0, patchHint = '') {
+    confirms.push({
+      code,
+      type: 'confirm',
+      category: 'db',
+      path: fieldPath,
+      question,
+      options,
+      defaultRecommend,
+      ...(patchHint ? { patchHint } : {}),
+    });
+  }
+
+  let bundle = input.bundle;
+  if (!bundle && input.bundleText) {
+    try {
+      bundle = parse(input.bundleText);
+    } catch {
+      addConfirm(
+        'CONFIRM_DB_PARSE',
+        filePath,
+        'Bundle YAML failed DB audit parse — how to proceed?',
+        [
+          '(Recommended) Fix YAML syntax in bundle, then re-run audit spec',
+          'Pause authoring until file is valid',
+          DEBT_OPTION,
+        ],
+        0,
+      );
+      return {
+        file: filePath,
+        totalWarnings: 0,
+        totalConfirms: confirms.length,
+        warnings,
+        confirms,
+        bindings: [],
+        tables: [],
+      };
+    }
+  }
+
+  if (!bundle) {
+    return {
+      file: filePath,
+      totalWarnings: 0,
+      totalConfirms: 0,
+      warnings: [],
+      confirms: [],
+      bindings: [],
+      tables: [],
+    };
+  }
+
+  const { bindings, tables } = collectDesignDbBindings(bundle);
+  const tableList = [...tables];
+  const partialDb = bindings.filter((b) => b.hasDbBlock && ((b.schema && !b.field) || (!b.schema && b.field)));
+  const persistedWithoutDb = bindings.filter(
+    (b) => b.required && (!b.schema || !b.field) && b.bindField,
+  );
+  const withFullDb = bindings.filter((b) => b.schema && b.field);
+  const listColsNoDb = bindings.filter(
+    (b) => b.source === 'list-column' && b.bindField && !b.schema && (b.sortable || b.label),
+  );
+
+  if (partialDb.length === 1) {
+    const b = partialDb[0];
+    addConfirm(
+      'CONFIRM_DB_PARTIAL_BINDING',
+      b.path,
+      `Incomplete db on "${b.label || b.bindField}": schema="${b.schema}" field="${b.field}". How to fix?`,
+      [
+        '(Recommended) Set both db.schema and db.field per db-erd.md + 01-backend-spec',
+        'Field is UI-only / computed — remove db block and document #derived-data',
+        DEBT_OPTION,
+      ],
+      0,
+      'design.sections[].db',
+    );
+  } else if (partialDb.length > 1) {
+    const ids = partialDb.map((b) => b.bindField || b.path).join(', ');
+    addConfirm(
+      'CONFIRM_DB_PARTIAL_BINDING',
+      'design.sections',
+      `${partialDb.length} controls have partial db bindings (${ids}). Batch fix strategy?`,
+      [
+        '(Recommended) Patch each control with full schema+field from ERD before split',
+        'Mark non-persisted fields as #derived-data and remove partial db',
+        DEBT_OPTION,
+      ],
+      0,
+    );
+  }
+
+  if (persistedWithoutDb.length === 1) {
+    const b = persistedWithoutDb[0];
+    addConfirm(
+      'CONFIRM_DB_REQUIRED_MAPPING',
+      b.path,
+      `Required field "${b.bindField}" has no db.schema/db.field — where is it stored?`,
+      [
+        `(Recommended) Add db: { schema, field } aligned with common/db-erd.md`,
+        'Not persisted on this screen — relax validation.required or document #derived-data',
+        DEBT_OPTION,
+      ],
+      0,
+    );
+  } else if (persistedWithoutDb.length > 1) {
+    const ids = persistedWithoutDb.map((b) => b.bindField).join(', ');
+    addConfirm(
+      'CONFIRM_DB_REQUIRED_MAPPING',
+      'design.sections',
+      `${persistedWithoutDb.length} required fields lack db mapping: ${ids}.`,
+      [
+        '(Recommended) Map all to tables/columns on bundle + spec.entities subset',
+        'Split screen scope — some fields are computed (#derived-data)',
+        DEBT_OPTION,
+      ],
+      0,
+    );
+  }
+
+  const bindToDb = new Map();
+  const conflicts = [];
+  for (const b of withFullDb) {
+    if (!b.bindField) continue;
+    const sig = `${b.schema}.${b.field}`;
+    const prev = bindToDb.get(b.bindField);
+    if (prev && prev !== sig) {
+      conflicts.push({ bindField: b.bindField, prev, sig, path: b.path });
+    } else {
+      bindToDb.set(b.bindField, sig);
+    }
+  }
+  if (conflicts.length === 1) {
+    const c = conflicts[0];
+    addConfirm(
+      'CONFIRM_DB_BIND_CONFLICT',
+      c.path,
+      `bind.field "${c.bindField}" maps to both ${c.prev} and ${c.sig}. Which is correct?`,
+      [
+        `(Recommended) Keep ${c.sig} — rename other control bind.field`,
+        `Keep ${c.prev} — fix the conflicting control`,
+        DEBT_OPTION,
+      ],
+      0,
+    );
+  } else if (conflicts.length > 1) {
+    addConfirm(
+      'CONFIRM_DB_BIND_CONFLICT',
+      'design.sections[].bind.field',
+      `${conflicts.length} bind.field keys map to multiple DB columns. Resolve naming?`,
+      [
+        '(Recommended) One bind.field per DB column; split payload keys per table',
+        'Document composite DTO on 01 — align api-update with nested object',
+        DEBT_OPTION,
+      ],
+      0,
+    );
+  }
+
+  const entityNames = entityNamesFromSpec(bundle);
+  const persistedCount = withFullDb.length;
+
+  if (persistedCount >= 2 && entityNames.size === 0) {
+    addConfirm(
+      'CONFIRM_DB_SPEC_ENTITIES',
+      'spec.entities',
+      `Screen maps ${persistedCount} column(s) across ${tableList.length || 1} table(s) but spec.entities is empty. Declare entity subset?`,
+      [
+        `(Recommended) Fill spec.entities[] from db-erd (${tableList.join(', ') || 'see ERD'})`,
+        'Single aggregate only — one entity entry covering primary table',
+        DEBT_OPTION,
+      ],
+      0,
+      'spec.entities',
+    );
+  }
+
+  if (tableList.length >= 2) {
+    const missing = tableList.filter((t) => !entityNames.has(normalizeTableKey(t)));
+    if (entityNames.size > 0 && missing.length > 0) {
+      addConfirm(
+        'CONFIRM_DB_MULTI_TABLE_ENTITIES',
+        'spec.entities',
+        `Tables on screen: ${tableList.join(', ')}. spec.entities may miss: ${missing.join(', ')}.`,
+        [
+          '(Recommended) Add entity row per missing table (name + short description)',
+          'Secondary table is join-only — document under design.dataModel.tables role join',
+          DEBT_OPTION,
+        ],
+        0,
+      );
+    }
+    if (!bundle.design?.dataModel?.tables?.length) {
+      addConfirm(
+        'CONFIRM_DB_MULTI_TABLE_OVERVIEW',
+        'design.dataModel.tables',
+        `This screen uses ${tableList.length} tables (${tableList.join(', ')}). Add per-table role for reviewers?`,
+        [
+          '(Recommended) Add design.dataModel.tables[] (read-write / read / join) — tpl-screen-data-model.md',
+          'Rely on ir/generated/data-model.md only after split (no YAML overview)',
+          DEBT_OPTION,
+        ],
+        0,
+        'design.dataModel',
+      );
+    }
+  }
+
+  if (listColsNoDb.length > 0) {
+    const keys = listColsNoDb.map((b) => b.bindField).join(', ');
+    addConfirm(
+      'CONFIRM_DB_LIST_COLUMN_STORAGE',
+      'spec.ui.list.columns',
+      `List columns [${keys}] have no db binding — stored in DB or computed?`,
+      [
+        '(Recommended) Add columns[].db.schema+field when sort/filter/search hits DB',
+        'Computed/display-only — tag #derived-data in data-model/derived-data.md',
+        DEBT_OPTION,
+      ],
+      0,
+    );
+  }
+
+  const backendIndex = indexBackendEntities(input.backendText ?? '');
+  const beTableMiss = [];
+  const beFieldMiss = [];
+  if (backendIndex.size > 0 && withFullDb.length > 0) {
+    for (const b of withFullDb) {
+      const ent = backendIndex.get(normalizeTableKey(b.schema));
+      if (!ent) {
+        beTableMiss.push(b);
+        continue;
+      }
+      if (!ent.fields.has(b.field.toLowerCase())) {
+        beFieldMiss.push({ ...b, entityName: ent.entityName });
+      }
+    }
+  }
+
+  if (beTableMiss.length > 0) {
+    const schemas = [...new Set(beTableMiss.map((b) => b.schema))].join(', ');
+    addConfirm(
+      'CONFIRM_DB_BE_TABLE_DRIFT',
+      'api/01-backend-spec.yaml',
+      `Design db.schema [${schemas}] not found on 01 modules[].entities.table/name.`,
+      [
+        '(Recommended) /api-update — add entity with matching table on 01',
+        '(Recommended) Fix design db.schema to match existing 01 entity.table',
+        DEBT_OPTION,
+      ],
+      0,
+    );
+  }
+
+  if (beFieldMiss.length > 0) {
+    const sample = beFieldMiss
+      .slice(0, 4)
+      .map((b) => `${b.schema}.${b.field}`)
+      .join(', ');
+    addConfirm(
+      'CONFIRM_DB_BE_FIELD_DRIFT',
+      'api/01-backend-spec.yaml',
+      `Design columns not on 01 entity fields (e.g. ${sample}${beFieldMiss.length > 4 ? ', …' : ''}).`,
+      [
+        '(Recommended) Add fields to 01 entities[].fields via /api-update',
+        'Fix design db.field to match 01 field names',
+        DEBT_OPTION,
+      ],
+      0,
+    );
+  } else if (
+    withFullDb.length > 0 &&
+    backendIndex.size === 0 &&
+    input.backendSpecFound === false
+  ) {
+    addConfirm(
+      'CONFIRM_DB_BE_SPEC_MISSING',
+      'api/01-backend-spec.yaml',
+      'Design has db mappings but no sibling 01-backend-spec for audit cross-check.',
+      [
+        '(Recommended) Run /api-spec or /api-update to author 01, then re-audit',
+        'Continue design-only — defer BE until grill-dev',
+        DEBT_OPTION,
+      ],
+      1,
+    );
+  }
+
+  if (persistedCount === 0 && bindings.some((b) => b.required && b.bindField)) {
+    addWarning(
+      'WARN_DB_NO_BINDINGS_YET',
+      'design.sections',
+      'Required form fields exist but no complete db.schema+db.field yet.',
+      'Complete db bindings or confirm #derived-data via CONFIRM_DB_* wizard.',
+    );
+  }
+
+  return {
+    file: filePath,
+    totalWarnings: warnings.length,
+    totalConfirms: confirms.length,
+    warnings,
+    confirms,
+    bindings: withFullDb,
+    tables: tableList,
+  };
+}
+
+export function resolveBackendSpecForBundle(bundlePath, explicitPath) {
+  if (explicitPath) return path.resolve(process.cwd(), explicitPath);
+  const dir = path.dirname(path.resolve(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;
+}
+
+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 };
+}
+
+const isMain =
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+if (isMain) {
+  if (args.length === 0) {
+    console.log(
+      'Usage: node audit-db-tables.mjs <bundle.yaml> [--backend-spec path/to/01-backend-spec.yaml]',
+    );
+    process.exit(0);
+  }
+  const { bundlePath, backendSpec } = parseArgs(args);
+  const resolved = path.resolve(process.cwd(), bundlePath);
+  const bundleText = fs.readFileSync(resolved, 'utf8');
+  const backendResolved = resolveBackendSpecForBundle(resolved, backendSpec);
+  const backendText =
+    backendResolved && fs.existsSync(backendResolved)
+      ? fs.readFileSync(backendResolved, 'utf8')
+      : '';
+  const report = auditDbTables({
+    bundleText,
+    backendText,
+    filePath: resolved,
+  });
+  console.log(JSON.stringify(report, null, 2));
+}