@mcoda/core 0.1.8 → 0.1.11

package/dist/services/docs/review/gates/SqlRequiredTablesGate.js

@@ -0,0 +1,273 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+const FEATURE_DEFINITIONS = [
+    {
+        key: "data_exports",
+        label: "data exports",
+        matchers: ["data export", "export job", "export artifact", "dataset export"],
+        requiredTables: ["data_export_jobs", "data_export_artifacts"],
+    },
+    {
+        key: "rights_policies",
+        label: "rights policies",
+        matchers: ["rights policy", "rights policies"],
+        requiredTables: ["rights_policies"],
+    },
+    {
+        key: "admin_audit",
+        label: "admin audit logs",
+        matchers: ["admin audit", "audit admin", "admin audit log"],
+        requiredTables: ["admin_audit_log"],
+    },
+    {
+        key: "event_outbox",
+        label: "event outbox",
+        matchers: ["event outbox", "outbox", "event bus", "message bus", "pub sub"],
+        requiredTables: ["event_outbox"],
+    },
+];
+const CREATE_TABLE_PATTERN = /\\bcreate\\s+table\\s+(?:if\\s+not\\s+exists\\s+)?([`\"\\[]?[A-Za-z0-9_]+[`\"\\]]?)/i;
+const isFenceLine = (line) => /^```|^~~~/.test(line.trim());
+const normalizeDocLine = (line) => line
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim();
+const stripSqlComments = (line, state) => {
+    let working = line;
+    if (state.inBlockComment) {
+        const end = working.indexOf("*/");
+        if (end === -1)
+            return "";
+        working = working.slice(end + 2);
+        state.inBlockComment = false;
+    }
+    let blockStart = working.indexOf("/*");
+    while (blockStart !== -1) {
+        const blockEnd = working.indexOf("*/", blockStart + 2);
+        if (blockEnd === -1) {
+            working = working.slice(0, blockStart);
+            state.inBlockComment = true;
+            break;
+        }
+        working = `${working.slice(0, blockStart)} ${working.slice(blockEnd + 2)}`;
+        blockStart = working.indexOf("/*", blockStart);
+    }
+    const lineComment = working.indexOf("--");
+    if (lineComment !== -1) {
+        working = working.slice(0, lineComment);
+    }
+    return working.trim();
+};
+const collectFeatureMatches = async (records) => {
+    const matches = {
+        data_exports: [],
+        rights_policies: [],
+        admin_audit: [],
+        event_outbox: [],
+    };
+    for (const record of records) {
+        try {
+            const content = await fs.readFile(record.path, "utf8");
+            const lines = content.split(/\\r?\\n/);
+            let inFence = false;
+            lines.forEach((line, index) => {
+                const trimmed = line.trim();
+                if (isFenceLine(trimmed)) {
+                    inFence = !inFence;
+                    return;
+                }
+                if (inFence)
+                    return;
+                const normalized = normalizeDocLine(line);
+                if (!normalized)
+                    return;
+                for (const feature of FEATURE_DEFINITIONS) {
+                    if (feature.matchers.some((matcher) => normalized.includes(matcher))) {
+                        matches[feature.key].push({
+                            record,
+                            line: index + 1,
+                            excerpt: trimmed.slice(0, 140),
+                        });
+                    }
+                }
+            });
+        }
+        catch {
+            // ignore missing doc reads; handled by gate notes
+        }
+    }
+    return matches;
+};
+const normalizeTableName = (value) => value.replace(/[`\"\\[]|\\]$/g, "").toLowerCase();
+const stripSqlCommentsFromRaw = (raw) => raw.replace(/--.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, " ");
+const collectTableNamesFromRaw = (raw) => {
+    const tables = new Set();
+    const sanitized = stripSqlCommentsFromRaw(raw);
+    const pattern = /\bcreate\s+table\s+(?:if\s+not\s+exists\s+)?([`"\[]?[A-Za-z0-9_]+[`"\]]?)/gi;
+    let match;
+    while ((match = pattern.exec(sanitized)) !== null) {
+        if (match[1])
+            tables.add(normalizeTableName(match[1]));
+    }
+    return tables;
+};
+const collectBadRightsPolicyFk = (lines) => {
+    const results = [];
+    const state = { inBlockComment: false };
+    lines.forEach((line, index) => {
+        const code = stripSqlComments(line, state);
+        if (!code)
+            return;
+        if (/\\brights_policies_id\\b/i.test(code)) {
+            results.push({ line: index + 1, excerpt: code.trim().slice(0, 140) });
+        }
+    });
+    return results;
+};
+const collectBadRightsPolicyFkFromRaw = (raw) => {
+    const results = [];
+    const pattern = /\brights_policies_id\b/gi;
+    let match;
+    while ((match = pattern.exec(raw)) !== null) {
+        const prefix = raw.slice(0, match.index);
+        const line = prefix.split(/\r?\n/).length;
+        const lineText = raw.split(/\r?\n/)[line - 1] ?? raw.slice(match.index);
+        results.push({ line, excerpt: lineText.trim().slice(0, 140) });
+    }
+    return results;
+};
+const formatEvidence = (matches) => {
+    if (matches.length === 0)
+        return undefined;
+    const preview = matches
+        .slice(0, 2)
+        .map((match) => `${path.basename(match.record.path)}:${match.line}`)
+        .join(", ");
+    const suffix = matches.length > 2 ? ` (+${matches.length - 2} more)` : "";
+    return `${preview}${suffix}`;
+};
+const buildIssue = (input) => ({
+    id: input.id,
+    gateId: "gate-sql-required-tables",
+    severity: "high",
+    category: "sql",
+    artifact: "sql",
+    message: input.message,
+    remediation: input.remediation,
+    location: {
+        kind: "line_range",
+        path: input.record.path,
+        lineStart: input.line ?? 1,
+        lineEnd: input.line ?? 1,
+        excerpt: input.message,
+    },
+    metadata: input.metadata,
+});
+export const runSqlRequiredTablesGate = async (input) => {
+    const sql = input.artifacts.sql;
+    if (!sql) {
+        return {
+            gateId: "gate-sql-required-tables",
+            gateName: "SQL Required Tables",
+            status: "skipped",
+            issues: [],
+            notes: ["No SQL artifact available for required table validation."],
+        };
+    }
+    const docRecords = [input.artifacts.sds, input.artifacts.pdr].filter((record) => Boolean(record));
+    if (docRecords.length === 0) {
+        return {
+            gateId: "gate-sql-required-tables",
+            gateName: "SQL Required Tables",
+            status: "skipped",
+            issues: [],
+            notes: ["No SDS/PDR artifacts available for SQL requirement detection."],
+        };
+    }
+    const notes = [];
+    const issues = [];
+    const featureMatches = await collectFeatureMatches(docRecords);
+    const activeFeatures = FEATURE_DEFINITIONS.filter((feature) => featureMatches[feature.key].length > 0);
+    if (activeFeatures.length === 0) {
+        return {
+            gateId: "gate-sql-required-tables",
+            gateName: "SQL Required Tables",
+            status: "pass",
+            issues: [],
+            notes: ["No feature-driven SQL requirements detected in docs."],
+        };
+    }
+    let raw;
+    try {
+        raw = await fs.readFile(sql.path, "utf8");
+    }
+    catch (error) {
+        return {
+            gateId: "gate-sql-required-tables",
+            gateName: "SQL Required Tables",
+            status: "pass",
+            issues: [],
+            notes: [`Unable to read SQL schema ${sql.path}: ${error.message ?? String(error)}`],
+        };
+    }
+    const lines = raw.split(/\\r?\\n/);
+    const tables = collectTableNamesFromRaw(raw);
+    const hasOutbox = Array.from(tables).some((name) => name.includes("outbox"));
+    const hasAdminAudit = tables.has("admin_audit_log") || tables.has("admin_audit_logs");
+    for (const feature of activeFeatures) {
+        const evidence = formatEvidence(featureMatches[feature.key]);
+        for (const table of feature.requiredTables) {
+            if (feature.key === "event_outbox") {
+                if (hasOutbox)
+                    continue;
+            }
+            else if (feature.key === "admin_audit") {
+                if (hasAdminAudit)
+                    continue;
+            }
+            else if (tables.has(table)) {
+                continue;
+            }
+            const message = evidence
+                ? `SQL schema is missing required table \"${table}\" for ${feature.label} (referenced at ${evidence}).`
+                : `SQL schema is missing required table \"${table}\" for ${feature.label}.`;
+            issues.push(buildIssue({
+                id: `gate-sql-required-tables-${feature.key}-${table}`,
+                message,
+                remediation: `Add the ${table} table to the SQL schema.`,
+                record: sql,
+                metadata: { issueType: "missing_table", feature: feature.key, table, evidence },
+            }));
+        }
+    }
+    const shouldCheckRightsFk = featureMatches.rights_policies.length > 0 || tables.has("rights_policies");
+    if (shouldCheckRightsFk) {
+        const badFks = collectBadRightsPolicyFk(lines);
+        const fkHits = badFks.length > 0 ? badFks : collectBadRightsPolicyFkFromRaw(raw);
+        for (const bad of fkHits) {
+            issues.push(buildIssue({
+                id: `gate-sql-required-tables-rights-policy-fk-${bad.line}`,
+                message: "SQL schema uses \"rights_policies_id\"; use \"rights_policy_id\" for FK columns.",
+                remediation: "Rename FK columns to rights_policy_id and update references.",
+                record: sql,
+                line: bad.line,
+                metadata: { issueType: "fk_naming", expected: "rights_policy_id", found: "rights_policies_id" },
+            }));
+        }
+    }
+    if (issues.length === 0) {
+        const features = activeFeatures.map((feature) => feature.label).join(", ");
+        notes.push(`SQL requirement checks passed for: ${features}.`);
+    }
+    return {
+        gateId: "gate-sql-required-tables",
+        gateName: "SQL Required Tables",
+        status: issues.length > 0 ? "fail" : "pass",
+        issues,
+        notes: notes.length > 0 ? notes : undefined,
+        metadata: {
+            featureCount: activeFeatures.length,
+            tableCount: tables.size,
+        },
+    };
+};

package/dist/services/docs/review/gates/SqlSyntaxGate.d.ts

@@ -0,0 +1,7 @@
+import { DocgenArtifactInventory } from "../../DocgenRunContext.js";
+import { ReviewGateResult } from "../ReviewTypes.js";
+export interface SqlSyntaxGateInput {
+    artifacts: DocgenArtifactInventory;
+}
+export declare const runSqlSyntaxGate: (input: SqlSyntaxGateInput) => Promise<ReviewGateResult>;
+//# sourceMappingURL=SqlSyntaxGate.d.ts.map

package/dist/services/docs/review/gates/SqlSyntaxGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SqlSyntaxGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/SqlSyntaxGate.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAA+B,MAAM,mBAAmB,CAAC;AAElF,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,uBAAuB,CAAC;CACpC;AAkMD,eAAO,MAAM,gBAAgB,GAC3B,OAAO,kBAAkB,KACxB,OAAO,CAAC,gBAAgB,CAgC1B,CAAC"}

package/dist/services/docs/review/gates/SqlSyntaxGate.js

@@ -0,0 +1,203 @@
+import { promises as fs } from "node:fs";
+const STATEMENT_START = /^(create|alter|drop|insert|update|delete|select|with|pragma|begin|commit|rollback|end|vacuum|analyze|attach|detach)\b/i;
+const CLAUSE_START = /^(from|where|join|left|right|inner|outer|on|group|order|limit|offset|union|values|set|returning)\b/i;
+const CONTINUATION_START = /^(,|\)|constraint\b|primary\b|foreign\b|unique\b|check\b|references\b|index\b|key\b|generated\b|as\b|collate\b|not\b|null\b)/i;
+const COLUMN_DEF = /^(?:`[^`]+`|"[^"]+"|\[[^\]]+]|[A-Za-z_][\w$]*)(?:\s+[A-Za-z_][\w$]*)(?:\s*\([^)]*\))?/i;
+const TYPE_KEYWORDS = /\b(bigint|int|integer|smallint|tinyint|serial|bigserial|uuid|text|varchar|char|character|boolean|bool|date|timestamp|timestamptz|datetime|time|json|jsonb|blob|real|double|float|numeric|decimal|money|bytea)\b/i;
+const CONSTRAINT_KEYWORDS = /\b(primary|foreign|references|unique|check|default|collate|generated|identity)\b/i;
+const NULL_KEYWORDS = /\bnot\s+null\b|\bnull\b/i;
+const ISSUE_SEVERITY = {
+    empty: "high",
+    prose: "medium",
+    syntax: "high",
+    unterminated: "high",
+};
+const stripComments = (line, state) => {
+    let working = line;
+    if (state.inBlockComment) {
+        const end = working.indexOf("*/");
+        if (end === -1)
+            return "";
+        working = working.slice(end + 2);
+        state.inBlockComment = false;
+    }
+    let blockStart = working.indexOf("/*");
+    while (blockStart !== -1) {
+        const blockEnd = working.indexOf("*/", blockStart + 2);
+        if (blockEnd === -1) {
+            working = working.slice(0, blockStart);
+            state.inBlockComment = true;
+            break;
+        }
+        working = `${working.slice(0, blockStart)} ${working.slice(blockEnd + 2)}`;
+        blockStart = working.indexOf("/*", blockStart);
+    }
+    const lineComment = working.indexOf("--");
+    if (lineComment !== -1) {
+        working = working.slice(0, lineComment);
+    }
+    return working.trim();
+};
+const countParens = (line) => {
+    const stripped = line
+        .replace(/'[^']*'/g, "")
+        .replace(/"[^"]*"/g, "")
+        .replace(/\[[^\]]*]/g, "");
+    return {
+        open: (stripped.match(/\(/g) ?? []).length,
+        close: (stripped.match(/\)/g) ?? []).length,
+    };
+};
+const isSqlLine = (line, inStatement) => {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return true;
+    if (STATEMENT_START.test(trimmed))
+        return true;
+    if (!inStatement)
+        return false;
+    if (CLAUSE_START.test(trimmed))
+        return true;
+    if (CONTINUATION_START.test(trimmed))
+        return true;
+    if (trimmed === ");" || trimmed === ")" || trimmed === "," || trimmed === ";")
+        return true;
+    const normalized = trimmed.replace(/[;,)]\s*$/, "").trim();
+    if (COLUMN_DEF.test(normalized)) {
+        return TYPE_KEYWORDS.test(normalized) || CONSTRAINT_KEYWORDS.test(normalized) || NULL_KEYWORDS.test(normalized);
+    }
+    return false;
+};
+const validateSqlContent = (raw) => {
+    const errors = [];
+    if (!raw || !raw.trim()) {
+        return [{ line: 1, type: "empty", message: "SQL schema is empty." }];
+    }
+    const lines = raw.split(/\r?\n/);
+    const state = { inBlockComment: false, inStatement: false, statementStart: 0, parenDepth: 0 };
+    for (let index = 0; index < lines.length; index += 1) {
+        const lineNumber = index + 1;
+        const rawLine = lines[index] ?? "";
+        const code = stripComments(rawLine, state);
+        if (!code)
+            continue;
+        const trimmed = code.trim();
+        const isStart = STATEMENT_START.test(trimmed);
+        if (!state.inStatement && !isStart) {
+            errors.push({
+                line: lineNumber,
+                type: "prose",
+                message: "Non-SQL content detected.",
+                excerpt: trimmed.slice(0, 140),
+            });
+            continue;
+        }
+        if (state.inStatement && !isSqlLine(trimmed, true)) {
+            errors.push({
+                line: lineNumber,
+                type: "prose",
+                message: "Non-SQL content detected inside a statement.",
+                excerpt: trimmed.slice(0, 140),
+            });
+        }
+        if (!state.inStatement && isStart) {
+            state.inStatement = true;
+            state.statementStart = lineNumber;
+        }
+        const parenCount = countParens(code);
+        state.parenDepth += parenCount.open - parenCount.close;
+        if (state.parenDepth < 0) {
+            errors.push({
+                line: lineNumber,
+                type: "syntax",
+                message: "Unexpected closing parenthesis in SQL statement.",
+                excerpt: trimmed.slice(0, 140),
+            });
+            state.parenDepth = 0;
+        }
+        if (code.includes(";") && state.parenDepth > 0) {
+            errors.push({
+                line: lineNumber,
+                type: "syntax",
+                message: "Statement terminates before closing all parentheses.",
+                excerpt: trimmed.slice(0, 140),
+            });
+        }
+        if (code.includes(";") && state.parenDepth <= 0) {
+            state.inStatement = false;
+            state.statementStart = 0;
+            state.parenDepth = 0;
+        }
+    }
+    if (state.inStatement) {
+        errors.push({
+            line: state.statementStart || lines.length,
+            type: "unterminated",
+            message: `SQL statement starting at line ${state.statementStart} is missing a terminating semicolon.`,
+        });
+    }
+    if (state.parenDepth > 0) {
+        errors.push({
+            line: lines.length,
+            type: "syntax",
+            message: "SQL statement has unbalanced parentheses.",
+        });
+    }
+    return errors;
+};
+const buildIssue = (issue, record) => {
+    const remediation = issue.type === "prose"
+        ? "Remove prose and keep only SQL statements or comments."
+        : "Fix the SQL syntax and ensure statements terminate with semicolons.";
+    return {
+        id: `gate-sql-syntax-prose-${issue.type}-${issue.line}`,
+        gateId: "gate-sql-syntax-prose",
+        severity: ISSUE_SEVERITY[issue.type],
+        category: "sql",
+        artifact: record.kind,
+        message: issue.message,
+        remediation,
+        location: {
+            kind: "line_range",
+            path: record.path,
+            lineStart: issue.line,
+            lineEnd: issue.line,
+            excerpt: issue.excerpt ?? issue.message,
+        },
+        metadata: {
+            issueType: issue.type,
+        },
+    };
+};
+export const runSqlSyntaxGate = async (input) => {
+    const record = input.artifacts.sql;
+    if (!record) {
+        return {
+            gateId: "gate-sql-syntax-prose",
+            gateName: "SQL Syntax & Prose",
+            status: "skipped",
+            issues: [],
+            notes: ["No SQL artifacts available for syntax validation."],
+        };
+    }
+    let raw;
+    try {
+        raw = await fs.readFile(record.path, "utf8");
+    }
+    catch (error) {
+        return {
+            gateId: "gate-sql-syntax-prose",
+            gateName: "SQL Syntax & Prose",
+            status: "pass",
+            issues: [],
+            notes: [`Unable to read SQL schema ${record.path}: ${error.message ?? String(error)}`],
+        };
+    }
+    const issues = validateSqlContent(raw).map((issue) => buildIssue(issue, record));
+    return {
+        gateId: "gate-sql-syntax-prose",
+        gateName: "SQL Syntax & Prose",
+        status: issues.length > 0 ? "fail" : "pass",
+        issues,
+    };
+};

package/dist/services/docs/review/gates/TerminologyNormalizationGate.d.ts

@@ -0,0 +1,9 @@
+import { DocgenArtifactInventory } from "../../DocgenRunContext.js";
+import { GlossaryData } from "../Glossary.js";
+import { ReviewGateResult } from "../ReviewTypes.js";
+export interface TerminologyNormalizationGateInput {
+    artifacts: DocgenArtifactInventory;
+    glossary?: GlossaryData;
+}
+export declare const runTerminologyNormalizationGate: (input: TerminologyNormalizationGateInput) => Promise<ReviewGateResult>;
+//# sourceMappingURL=TerminologyNormalizationGate.d.ts.map

package/dist/services/docs/review/gates/TerminologyNormalizationGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TerminologyNormalizationGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/TerminologyNormalizationGate.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,YAAY,EAAgB,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAA+B,MAAM,mBAAmB,CAAC;AAElF,MAAM,WAAW,iCAAiC;IAChD,SAAS,EAAE,uBAAuB,CAAC;IACnC,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AA2MD,eAAO,MAAM,+BAA+B,GAC1C,OAAO,iCAAiC,KACvC,OAAO,CAAC,gBAAgB,CA0E1B,CAAC"}