@mcoda/core 0.1.9 → 0.1.12

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

@@ -0,0 +1,261 @@
+import { promises as fs } from "node:fs";
+const DEFAULT_ALLOWLIST = ["for example", "example only", "sample data", "sample payload"];
+const SEVERITY_RANK = {
+    blocker: 4,
+    high: 3,
+    medium: 2,
+    low: 1,
+    info: 0,
+};
+const DEFAULT_PATTERNS = [
+    {
+        id: "placeholder.tbd",
+        label: "TBD placeholder",
+        type: "placeholder",
+        pattern: /\bTBD\b/i,
+        severity: "blocker",
+    },
+    {
+        id: "placeholder.tbc",
+        label: "TBC placeholder",
+        type: "placeholder",
+        pattern: /\bTBC\b/i,
+        severity: "blocker",
+    },
+    {
+        id: "placeholder.fixme",
+        label: "FIXME placeholder",
+        type: "placeholder",
+        pattern: /\bFIXME\b/i,
+        severity: "high",
+    },
+    {
+        id: "placeholder.todo",
+        label: "TODO placeholder",
+        type: "placeholder",
+        pattern: /\bTODO\b/,
+        severity: "high",
+    },
+    {
+        id: "placeholder.lorem",
+        label: "Lorem ipsum placeholder",
+        type: "placeholder",
+        pattern: /\blorem ipsum\b/i,
+        severity: "high",
+    },
+    {
+        id: "placeholder.placeholder",
+        label: "Placeholder text",
+        type: "placeholder",
+        pattern: /\bplaceholder\b/i,
+        severity: "medium",
+    },
+    {
+        id: "placeholder.tobe",
+        label: "To be decided placeholder",
+        type: "placeholder",
+        pattern: /\bto be (decided|determined|filled)\b/i,
+        severity: "high",
+    },
+    {
+        id: "template.restaurant",
+        label: "Restaurant template artifact",
+        type: "template_artifact",
+        pattern: /\brestaurant\b/i,
+        severity: "high",
+    },
+    {
+        id: "template.menu_items",
+        label: "Menu items template artifact",
+        type: "template_artifact",
+        pattern: /\bmenu items?\b/i,
+        severity: "medium",
+    },
+    {
+        id: "template.reservation",
+        label: "Reservation template artifact",
+        type: "template_artifact",
+        pattern: /\btable reservation(s)?\b/i,
+        severity: "medium",
+    },
+    {
+        id: "template.voting",
+        label: "Voting template artifact",
+        type: "template_artifact",
+        pattern: /\b(voting|election|ballot)\b/i,
+        severity: "high",
+    },
+    {
+        id: "template.food_delivery",
+        label: "Food delivery template artifact",
+        type: "template_artifact",
+        pattern: /\bfood delivery\b/i,
+        severity: "medium",
+    },
+];
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const buildAllowlist = (allowlist) => {
+    const combined = [...DEFAULT_ALLOWLIST, ...(allowlist ?? [])];
+    return combined.map((entry) => new RegExp(escapeRegExp(entry), "i"));
+};
+const buildCustomPatterns = (denylist) => {
+    if (!denylist || denylist.length === 0)
+        return [];
+    return denylist.map((entry, index) => ({
+        id: `custom.placeholder.${index + 1}`,
+        label: `Custom placeholder: ${entry}`,
+        type: "placeholder",
+        pattern: new RegExp(escapeRegExp(entry), "i"),
+        severity: "high",
+    }));
+};
+const collectRecords = (artifacts) => {
+    const records = [];
+    if (artifacts.pdr)
+        records.push(artifacts.pdr);
+    if (artifacts.sds)
+        records.push(artifacts.sds);
+    if (artifacts.sql)
+        records.push(artifacts.sql);
+    if (artifacts.openapi?.length)
+        records.push(...artifacts.openapi);
+    if (artifacts.blueprints?.length)
+        records.push(...artifacts.blueprints);
+    return records;
+};
+const isFenceLine = (line) => /^```|^~~~/.test(line.trim());
+const isExampleHeading = (heading) => /example|sample/i.test(heading);
+const selectHighestSeverity = (candidates) => {
+    let chosen = candidates[0];
+    for (const candidate of candidates.slice(1)) {
+        if (SEVERITY_RANK[candidate.severity] > SEVERITY_RANK[chosen.severity]) {
+            chosen = candidate;
+        }
+    }
+    return chosen;
+};
+const buildIssue = (input) => {
+    const match = input.line.match(input.pattern.pattern);
+    const excerpt = input.line.trim();
+    const message = `${input.pattern.label} detected${match ? ` (${match[0]})` : ""}.`;
+    const remediation = input.pattern.type === "placeholder"
+        ? "Replace placeholders with concrete content."
+        : "Replace unrelated template artifacts with project-specific content.";
+    return {
+        id: `gate-placeholder-artifacts-${input.record.kind}-${input.pattern.id}-${input.lineNumber}`,
+        gateId: "gate-placeholder-artifacts",
+        severity: input.pattern.severity,
+        category: "content",
+        artifact: input.record.kind,
+        message,
+        remediation,
+        location: {
+            kind: "line_range",
+            path: input.record.path,
+            lineStart: input.lineNumber,
+            lineEnd: input.lineNumber,
+            excerpt,
+        },
+        metadata: {
+            placeholderType: input.pattern.type,
+            patternId: input.pattern.id,
+            patternLabel: input.pattern.label,
+            matchedText: match ? match[0] : undefined,
+            heading: input.heading,
+        },
+    };
+};
+export const runPlaceholderArtifactGate = async (input) => {
+    const allowlist = buildAllowlist(input.allowlist);
+    const patterns = [...DEFAULT_PATTERNS, ...buildCustomPatterns(input.denylist)];
+    const records = collectRecords(input.artifacts);
+    const issues = [];
+    const notes = [];
+    if (records.length === 0) {
+        return {
+            gateId: "gate-placeholder-artifacts",
+            gateName: "Placeholder Artifacts",
+            status: "skipped",
+            issues,
+            notes: ["No artifacts available for placeholder scanning."],
+        };
+    }
+    for (const record of records) {
+        let content;
+        try {
+            content = await fs.readFile(record.path, "utf8");
+        }
+        catch (error) {
+            notes.push(`Placeholder scan skipped for ${record.path}: ${error.message}`);
+            continue;
+        }
+        const lines = content.split(/\r?\n/);
+        let inFence = false;
+        let allowSection = false;
+        let currentHeading;
+        for (let i = 0; i < lines.length; i += 1) {
+            const line = lines[i] ?? "";
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            if (isFenceLine(trimmed)) {
+                inFence = !inFence;
+                continue;
+            }
+            const headingMatch = trimmed.match(/^#{1,6}\s+(.*)$/);
+            if (headingMatch) {
+                currentHeading = headingMatch[1]?.trim() || undefined;
+                allowSection = currentHeading ? isExampleHeading(currentHeading) : false;
+            }
+            if (inFence || allowSection)
+                continue;
+            if (allowlist.some((pattern) => pattern.test(line)))
+                continue;
+            const matches = [];
+            for (const pattern of patterns) {
+                if (!pattern.pattern.test(line))
+                    continue;
+                matches.push(pattern);
+            }
+            if (matches.length === 0)
+                continue;
+            const grouped = new Map();
+            for (const match of matches) {
+                const existing = grouped.get(match.type);
+                if (existing) {
+                    existing.push(match);
+                }
+                else {
+                    grouped.set(match.type, [match]);
+                }
+            }
+            const typeOrder = ["placeholder", "template_artifact"];
+            for (const type of typeOrder) {
+                const candidates = grouped.get(type);
+                if (!candidates || candidates.length === 0)
+                    continue;
+                const selected = selectHighestSeverity(candidates);
+                issues.push(buildIssue({
+                    record,
+                    pattern: selected,
+                    line,
+                    lineNumber: i + 1,
+                    heading: currentHeading,
+                }));
+            }
+        }
+    }
+    const status = issues.length > 0 ? "fail" : "pass";
+    return {
+        gateId: "gate-placeholder-artifacts",
+        gateName: "Placeholder Artifacts",
+        status,
+        issues,
+        notes: notes.length > 0 ? notes : undefined,
+        metadata: {
+            scannedArtifacts: records.length,
+            patternCount: patterns.length,
+            allowlistCount: allowlist.length,
+        },
+    };
+};

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

@@ -0,0 +1,6 @@
+import { ReviewGateResult } from "../ReviewTypes.js";
+export interface RfpConsentGateInput {
+    rfpPath?: string;
+}
+export declare const runRfpConsentGate: (input: RfpConsentGateInput) => Promise<ReviewGateResult>;
+//# sourceMappingURL=RfpConsentGate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RfpConsentGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/RfpConsentGate.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAA+B,MAAM,mBAAmB,CAAC;AAElF,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAoDD,eAAO,MAAM,iBAAiB,GAC5B,OAAO,mBAAmB,KACzB,OAAO,CAAC,gBAAgB,CAmG1B,CAAC"}

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

@@ -0,0 +1,127 @@
+import { promises as fs } from "node:fs";
+import { loadGlossary } from "../Glossary.js";
+const OVERBROAD_PATTERNS = [
+    /\bstore all interactions\b/i,
+    /\bcollect everything\b/i,
+    /\bretain everything\b/i,
+    /\bstore all data\b/i,
+    /\blog everything\b/i,
+    /\bkeep all records\b/i,
+    /\bfull data retention\b/i,
+];
+const MINIMIZATION_HINTS = [
+    /\bdata minimization\b/i,
+    /\bminimi[sz]e data\b/i,
+    /\blimit retention\b/i,
+    /\bcollect only\b/i,
+    /\bminimum necessary\b/i,
+];
+const ANON_HINTS = [/\banonymous\b/i, /\banon token\b/i, /\bno identifiers\b/i];
+const IDENT_HINTS = [/\bidentified\b/i, /\buser id\b/i, /\baccount id\b/i, /\bnon-anonymous\b/i];
+const isFenceLine = (line) => /^```|^~~~/.test(line.trim());
+const buildIssue = (input) => ({
+    id: input.id,
+    gateId: "gate-rfp-consent-contradictions",
+    severity: input.severity,
+    category: "compliance",
+    artifact: "pdr",
+    message: input.message,
+    remediation: input.remediation,
+    location: {
+        kind: "line_range",
+        path: input.path,
+        lineStart: input.line,
+        lineEnd: input.line,
+        excerpt: input.excerpt,
+    },
+    metadata: input.metadata,
+});
+export const runRfpConsentGate = async (input) => {
+    if (!input.rfpPath) {
+        return {
+            gateId: "gate-rfp-consent-contradictions",
+            gateName: "RFP Consent & Minimization",
+            status: "skipped",
+            issues: [],
+            notes: ["No RFP path provided for consent/minimization validation."],
+        };
+    }
+    const issues = [];
+    const notes = [];
+    const glossary = loadGlossary();
+    const consentPhrase = glossary.canonicalPhrases?.consent_flow ?? "consent flow";
+    const anonymityPhrase = glossary.canonicalPhrases?.anonymity ?? "anonymous vs identified handling";
+    try {
+        const content = await fs.readFile(input.rfpPath, "utf8");
+        const lines = content.split(/\r?\n/);
+        let inFence = false;
+        let anonLine;
+        let identLine;
+        const minimizationDeclared = lines.some((line) => MINIMIZATION_HINTS.some((pattern) => pattern.test(line)));
+        for (let i = 0; i < lines.length; i += 1) {
+            const rawLine = lines[i] ?? "";
+            const trimmed = rawLine.trim();
+            if (!trimmed)
+                continue;
+            if (isFenceLine(trimmed)) {
+                inFence = !inFence;
+                continue;
+            }
+            if (inFence)
+                continue;
+            if (anonLine === undefined && ANON_HINTS.some((pattern) => pattern.test(trimmed))) {
+                anonLine = i + 1;
+            }
+            if (identLine === undefined && IDENT_HINTS.some((pattern) => pattern.test(trimmed))) {
+                identLine = i + 1;
+            }
+            const overbroadMatch = OVERBROAD_PATTERNS.find((pattern) => pattern.test(trimmed));
+            if (overbroadMatch) {
+                const severity = minimizationDeclared ? "high" : "medium";
+                issues.push(buildIssue({
+                    id: `gate-rfp-consent-contradictions-overbroad-${i + 1}`,
+                    message: "Over-broad data retention statement conflicts with minimization goals.",
+                    remediation: `Align retention language with ${consentPhrase} and explicit minimization scope.`,
+                    severity,
+                    path: input.rfpPath,
+                    line: i + 1,
+                    excerpt: trimmed,
+                    metadata: {
+                        issueType: "overbroad_statement",
+                        minimizationDeclared,
+                        pattern: overbroadMatch.source,
+                    },
+                }));
+            }
+        }
+        if (anonLine !== undefined && identLine !== undefined) {
+            const line = Math.min(anonLine, identLine);
+            issues.push(buildIssue({
+                id: "gate-rfp-consent-contradictions-anon-ident",
+                message: "RFP mentions both anonymous and identified handling without clarifying boundaries.",
+                remediation: `Clarify ${anonymityPhrase} and reconcile consent requirements with minimization constraints.`,
+                severity: "high",
+                path: input.rfpPath,
+                line,
+                excerpt: lines[line - 1] ?? "",
+                metadata: {
+                    issueType: "anon_ident_contradiction",
+                    anonymousLine: anonLine,
+                    identifiedLine: identLine,
+                },
+            }));
+        }
+    }
+    catch (error) {
+        notes.push(`Unable to read RFP at ${input.rfpPath}: ${error.message ?? String(error)}`);
+    }
+    const status = issues.length === 0 ? "pass" : "fail";
+    return {
+        gateId: "gate-rfp-consent-contradictions",
+        gateName: "RFP Consent & Minimization",
+        status,
+        issues,
+        notes: notes.length ? notes : undefined,
+        metadata: { issueCount: issues.length },
+    };
+};

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

@@ -0,0 +1,7 @@
+import { ReviewGateResult } from "../ReviewTypes.js";
+export interface RfpDefinitionGateInput {
+    rfpPath?: string;
+    allowlist?: string[];
+}
+export declare const runRfpDefinitionGate: (input: RfpDefinitionGateInput) => Promise<ReviewGateResult>;
+//# sourceMappingURL=RfpDefinitionGate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RfpDefinitionGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/RfpDefinitionGate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAe,MAAM,mBAAmB,CAAC;AAElE,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAkFD,eAAO,MAAM,oBAAoB,GAC/B,OAAO,sBAAsB,KAC5B,OAAO,CAAC,gBAAgB,CA8G1B,CAAC"}

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

@@ -0,0 +1,173 @@
+import { promises as fs } from "node:fs";
+const DEFAULT_ALLOWLIST = [
+    "api",
+    "http",
+    "https",
+    "tls",
+    "oauth",
+    "sso",
+    "jwt",
+    "cli",
+    "ui",
+    "sdk",
+    "db",
+    "sql",
+    "rest",
+    "graphql",
+];
+const isFenceLine = (line) => /^```|^~~~/.test(line.trim());
+const normalizeTerm = (term) => term
+    .replace(/[`*_]/g, "")
+    .replace(/\(.*\)/g, "")
+    .replace(/[^a-zA-Z0-9\s-]/g, " ")
+    .toLowerCase()
+    .trim();
+const extractDefinitionTerm = (line) => {
+    const trimmed = line.trim();
+    const bullet = trimmed.replace(/^[-*+]\s+/, "");
+    const boldMatch = bullet.match(/\*\*([^*]+)\*\*/);
+    if (boldMatch)
+        return boldMatch[1]?.trim();
+    const backtickMatch = bullet.match(/`([^`]+)`/);
+    if (backtickMatch)
+        return backtickMatch[1]?.trim();
+    const colonMatch = bullet.match(/^([A-Za-z][A-Za-z0-9 _-]{1,40})\s*:/);
+    if (colonMatch)
+        return colonMatch[1]?.trim();
+    return undefined;
+};
+const extractReferencedTerms = (line) => {
+    const terms = [];
+    const boldMatches = line.matchAll(/\*\*([^*]+)\*\*/g);
+    for (const match of boldMatches) {
+        if (match[1])
+            terms.push(match[1]);
+    }
+    const codeMatches = line.matchAll(/`([^`]+)`/g);
+    for (const match of codeMatches) {
+        if (match[1])
+            terms.push(match[1]);
+    }
+    return terms;
+};
+const buildIssue = (input) => ({
+    id: input.id,
+    gateId: "gate-rfp-definition-coverage",
+    severity: "medium",
+    category: "compliance",
+    artifact: "pdr",
+    message: `Undefined term referenced in RFP: ${input.term}.`,
+    remediation: `Add a definition for \"${input.term}\" in the RFP Definitions section.`,
+    location: {
+        kind: "line_range",
+        path: input.path,
+        lineStart: input.line,
+        lineEnd: input.line,
+        excerpt: input.excerpt,
+    },
+    metadata: {
+        issueType: input.issueType,
+        term: input.term,
+    },
+});
+export const runRfpDefinitionGate = async (input) => {
+    if (!input.rfpPath) {
+        return {
+            gateId: "gate-rfp-definition-coverage",
+            gateName: "RFP Definition Coverage",
+            status: "skipped",
+            issues: [],
+            notes: ["No RFP path provided for definition coverage validation."],
+        };
+    }
+    const allowlist = new Set([...DEFAULT_ALLOWLIST, ...(input.allowlist ?? [])].map((item) => normalizeTerm(item)));
+    const issues = [];
+    const notes = [];
+    try {
+        const content = await fs.readFile(input.rfpPath, "utf8");
+        const lines = content.split(/\r?\n/);
+        let inFence = false;
+        let inDefinitions = false;
+        let definitionsHeadingLevel = 0;
+        const definedTerms = new Set();
+        const referencedTerms = [];
+        for (let i = 0; i < lines.length; i += 1) {
+            const line = lines[i] ?? "";
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            if (isFenceLine(trimmed)) {
+                inFence = !inFence;
+                continue;
+            }
+            if (inFence)
+                continue;
+            const headingMatch = trimmed.match(/^(#{1,6})\s+(.*)$/);
+            if (headingMatch) {
+                const level = headingMatch[1]?.length ?? 0;
+                const heading = headingMatch[2]?.trim() ?? "";
+                if (/definitions|glossary/i.test(heading)) {
+                    inDefinitions = true;
+                    definitionsHeadingLevel = level;
+                }
+                else if (inDefinitions && level <= definitionsHeadingLevel) {
+                    inDefinitions = false;
+                }
+                continue;
+            }
+            if (inDefinitions) {
+                const term = extractDefinitionTerm(trimmed);
+                if (term) {
+                    definedTerms.add(normalizeTerm(term));
+                }
+                continue;
+            }
+            const refs = extractReferencedTerms(trimmed);
+            if (refs.length > 0) {
+                for (const ref of refs) {
+                    const normalized = normalizeTerm(ref);
+                    if (!normalized || allowlist.has(normalized))
+                        continue;
+                    referencedTerms.push({ term: ref, line: i + 1, excerpt: trimmed });
+                }
+            }
+        }
+        const reported = new Set();
+        for (const ref of referencedTerms) {
+            const normalized = normalizeTerm(ref.term);
+            if (!normalized || definedTerms.has(normalized) || reported.has(normalized))
+                continue;
+            reported.add(normalized);
+            issues.push(buildIssue({
+                id: `gate-rfp-definition-coverage-${normalized}`,
+                term: ref.term,
+                path: input.rfpPath,
+                line: ref.line,
+                excerpt: ref.excerpt,
+                issueType: "undefined_term",
+            }));
+        }
+        if (definedTerms.size === 0 && referencedTerms.length > 0) {
+            issues.push(buildIssue({
+                id: "gate-rfp-definition-coverage-missing-section",
+                term: "Definitions section",
+                path: input.rfpPath,
+                line: referencedTerms[0]?.line ?? 1,
+                excerpt: referencedTerms[0]?.excerpt ?? "",
+                issueType: "missing_definitions_section",
+            }));
+        }
+    }
+    catch (error) {
+        notes.push(`Unable to read RFP at ${input.rfpPath}: ${error.message ?? String(error)}`);
+    }
+    const status = issues.length === 0 ? "pass" : "fail";
+    return {
+        gateId: "gate-rfp-definition-coverage",
+        gateName: "RFP Definition Coverage",
+        status,
+        issues,
+        notes: notes.length ? notes : undefined,
+        metadata: { issueCount: issues.length },
+    };
+};

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"SdsAdaptersGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/SdsAdaptersGate.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAe,MAAM,mBAAmB,CAAC;AAElE,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,uBAAuB,CAAC;CACpC;AA2GD,eAAO,MAAM,kBAAkB,GAC7B,OAAO,oBAAoB,KAC1B,OAAO,CAAC,gBAAgB,CAoH1B,CAAC"}