@mcoda/core 0.1.8 → 0.1.11

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

@@ -0,0 +1,159 @@
+import { promises as fs } from "node:fs";
+import { extractOpenApiPaths } from "../../../openapi/OpenApiService.js";
+const isFenceLine = (line) => /^```|^~~~/.test(line.trim());
+const buildIssue = (input) => ({
+    id: input.id,
+    gateId: "gate-pdr-interfaces-pipeline",
+    severity: "high",
+    category: "completeness",
+    artifact: "pdr",
+    message: input.message,
+    remediation: input.remediation,
+    location: input.path
+        ? {
+            kind: "line_range",
+            path: input.path,
+            lineStart: input.line ?? 1,
+            lineEnd: input.line ?? 1,
+            excerpt: input.message,
+        }
+        : { kind: "heading", heading: "PDR", path: input.path },
+    metadata: input.metadata,
+});
+const extractSection = (lines, headingMatch) => {
+    let inFence = false;
+    let capture = false;
+    let startLine = 0;
+    const collected = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? "";
+        const trimmed = line.trim();
+        if (isFenceLine(trimmed)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const heading = trimmed.match(/^#{1,6}\s+(.*)$/);
+        if (heading) {
+            const title = heading[1]?.trim() ?? "";
+            if (headingMatch.test(title)) {
+                capture = true;
+                startLine = i + 1;
+                continue;
+            }
+            if (capture)
+                break;
+        }
+        if (capture) {
+            if (trimmed)
+                collected.push(trimmed);
+        }
+    }
+    if (!capture || collected.length === 0)
+        return capture ? { content: [], line: startLine } : undefined;
+    return { content: collected, line: startLine };
+};
+const hasApiPaths = (lines) => lines.some((line) => /\b(GET|POST|PUT|PATCH|DELETE)\b/i.test(line) || /\/[a-zA-Z0-9]/.test(line));
+const mentionsLandingZones = (lines) => lines.some((line) => /landing zone|staging|raw|warehouse|lake/i.test(line));
+const mentionsNormalizationOwner = (lines) => lines.some((line) => /owner|steward|responsible|ownership|govern/i.test(line));
+const loadOpenApiPaths = async (records) => {
+    for (const record of records) {
+        try {
+            const raw = await fs.readFile(record.path, "utf8");
+            const { paths } = extractOpenApiPaths(raw);
+            if (paths.length > 0)
+                return paths;
+        }
+        catch {
+            // ignore parse issues here; OpenAPI gate handles validation.
+        }
+    }
+    return [];
+};
+export const runPdrInterfacesGate = async (input) => {
+    const pdr = input.artifacts.pdr;
+    if (!pdr) {
+        return {
+            gateId: "gate-pdr-interfaces-pipeline",
+            gateName: "PDR Interfaces & Pipeline",
+            status: "skipped",
+            issues: [],
+            notes: ["No PDR artifact available for interface/pipeline validation."],
+        };
+    }
+    const issues = [];
+    const notes = [];
+    try {
+        const content = await fs.readFile(pdr.path, "utf8");
+        const lines = content.split(/\r?\n/);
+        const interfacesSection = extractSection(lines, /interfaces?/i);
+        const pipelineSection = extractSection(lines, /pipeline|data flow/i);
+        if (!interfacesSection) {
+            issues.push(buildIssue({
+                id: "gate-pdr-interfaces-pipeline-missing-interfaces",
+                message: "PDR is missing an Interfaces section.",
+                remediation: "Add an Interfaces section listing system interfaces and APIs.",
+                path: pdr.path,
+                metadata: { issueType: "missing_interfaces" },
+            }));
+        }
+        if (!pipelineSection) {
+            issues.push(buildIssue({
+                id: "gate-pdr-interfaces-pipeline-missing-pipeline",
+                message: "PDR is missing a data pipeline model section.",
+                remediation: "Add a Pipeline/Data Flow section describing ingestion, normalization, and storage.",
+                path: pdr.path,
+                metadata: { issueType: "missing_pipeline" },
+            }));
+        }
+        if (interfacesSection && input.artifacts.openapi.length > 0) {
+            const openapiPaths = await loadOpenApiPaths(input.artifacts.openapi);
+            const hasPaths = hasApiPaths(interfacesSection.content);
+            if (openapiPaths.length > 0 && !hasPaths) {
+                issues.push(buildIssue({
+                    id: "gate-pdr-interfaces-pipeline-openapi-mismatch",
+                    message: "PDR interfaces section does not list any API paths while OpenAPI exists.",
+                    remediation: "List the primary API endpoints in the PDR Interfaces section.",
+                    path: pdr.path,
+                    line: interfacesSection.line,
+                    metadata: { issueType: "interfaces_missing_paths", openapiCount: openapiPaths.length },
+                }));
+            }
+        }
+        if (pipelineSection) {
+            if (!mentionsLandingZones(pipelineSection.content)) {
+                issues.push(buildIssue({
+                    id: "gate-pdr-interfaces-pipeline-missing-landing-zones",
+                    message: "Pipeline section does not describe data landing zones or storage tiers.",
+                    remediation: "Include raw/staging/warehouse landing zones in the pipeline description.",
+                    path: pdr.path,
+                    line: pipelineSection.line,
+                    metadata: { issueType: "missing_landing_zones" },
+                }));
+            }
+            if (!mentionsNormalizationOwner(pipelineSection.content)) {
+                issues.push(buildIssue({
+                    id: "gate-pdr-interfaces-pipeline-missing-ownership",
+                    message: "Pipeline section does not name ownership for normalization rules.",
+                    remediation: "Specify who owns or governs normalization rules in the pipeline model.",
+                    path: pdr.path,
+                    line: pipelineSection.line,
+                    metadata: { issueType: "missing_ownership" },
+                }));
+            }
+        }
+    }
+    catch (error) {
+        notes.push(`Unable to read PDR ${pdr.path}: ${error.message ?? String(error)}`);
+    }
+    const status = issues.length === 0 ? "pass" : "fail";
+    return {
+        gateId: "gate-pdr-interfaces-pipeline",
+        gateName: "PDR Interfaces & Pipeline",
+        status,
+        issues,
+        notes: notes.length ? notes : undefined,
+        metadata: { issueCount: issues.length },
+    };
+};

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

@@ -0,0 +1,8 @@
+import { DocgenArtifactInventory } from "../../DocgenRunContext.js";
+import { ReviewGateResult } from "../ReviewTypes.js";
+export interface PdrOpenQuestionsGateInput {
+    artifacts: DocgenArtifactInventory;
+    enabled: boolean;
+}
+export declare const runPdrOpenQuestionsGate: (input: PdrOpenQuestionsGateInput) => Promise<ReviewGateResult>;
+//# sourceMappingURL=PdrOpenQuestionsGate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PdrOpenQuestionsGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/PdrOpenQuestionsGate.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAEvF,OAAO,EAAE,gBAAgB,EAAe,MAAM,mBAAmB,CAAC;AAElE,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,uBAAuB,CAAC;IACnC,OAAO,EAAE,OAAO,CAAC;CAClB;AAgFD,eAAO,MAAM,uBAAuB,GAClC,OAAO,yBAAyB,KAC/B,OAAO,CAAC,gBAAgB,CA+D1B,CAAC"}

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

@@ -0,0 +1,129 @@
+import { promises as fs } from "node:fs";
+import { loadGlossary } from "../Glossary.js";
+const GENERIC_QUESTION_PATTERNS = [
+    /what is the timeline/i,
+    /who are the stakeholders/i,
+    /what are the risks/i,
+    /what is the scope/i,
+    /what are the requirements/i,
+    /how will we measure success/i,
+    /what is the budget/i,
+    /what are the next steps/i,
+];
+const isFenceLine = (line) => /^```|^~~~/.test(line.trim());
+const buildIssue = (input) => ({
+    id: input.id,
+    gateId: "gate-pdr-open-questions-quality",
+    severity: "medium",
+    category: "open_questions",
+    artifact: "pdr",
+    message: input.message,
+    remediation: input.remediation,
+    location: {
+        kind: "line_range",
+        path: input.record.path,
+        lineStart: input.line,
+        lineEnd: input.line,
+        excerpt: input.excerpt,
+    },
+    metadata: input.metadata,
+});
+const extractOpenQuestionLines = (lines) => {
+    const results = [];
+    let inFence = false;
+    let inSection = false;
+    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 heading = trimmed.match(/^#{1,6}\s+(.*)$/);
+        if (heading) {
+            const title = heading[1]?.trim() ?? "";
+            if (/open questions?|open issues?|unresolved questions?/i.test(title)) {
+                inSection = true;
+            }
+            else if (inSection) {
+                inSection = false;
+            }
+            continue;
+        }
+        if (!inSection)
+            continue;
+        const question = trimmed.replace(/^[-*+]\s+/, "").replace(/^\d+\.\s+/, "");
+        if (!question)
+            continue;
+        results.push({ text: question, line: i + 1 });
+    }
+    return results;
+};
+const containsDomainTerm = (text, domainTerms) => {
+    const lower = text.toLowerCase();
+    return domainTerms.some((term) => term && lower.includes(term));
+};
+export const runPdrOpenQuestionsGate = async (input) => {
+    if (!input.enabled) {
+        return {
+            gateId: "gate-pdr-open-questions-quality",
+            gateName: "PDR Open Questions Quality",
+            status: "skipped",
+            issues: [],
+            notes: ["Open question quality gate disabled."],
+        };
+    }
+    const pdr = input.artifacts.pdr;
+    if (!pdr) {
+        return {
+            gateId: "gate-pdr-open-questions-quality",
+            gateName: "PDR Open Questions Quality",
+            status: "skipped",
+            issues: [],
+            notes: ["No PDR artifact available for open question quality checks."],
+        };
+    }
+    const issues = [];
+    const notes = [];
+    const glossary = loadGlossary();
+    const domainTerms = glossary.entries
+        .flatMap((entry) => [entry.term, ...(entry.aliases ?? [])])
+        .map((term) => term.toLowerCase());
+    try {
+        const content = await fs.readFile(pdr.path, "utf8");
+        const lines = content.split(/\r?\n/);
+        const questions = extractOpenQuestionLines(lines);
+        for (const question of questions) {
+            const isGeneric = GENERIC_QUESTION_PATTERNS.some((pattern) => pattern.test(question.text));
+            if (!isGeneric)
+                continue;
+            if (containsDomainTerm(question.text, domainTerms))
+                continue;
+            issues.push(buildIssue({
+                id: `gate-pdr-open-questions-quality-${question.line}`,
+                message: `Generic open question lacks project-specific context: ${question.text}`,
+                remediation: "Replace with a question tied to the project domain (use glossary terms).",
+                record: pdr,
+                line: question.line,
+                excerpt: question.text,
+                metadata: { issueType: "generic_question" },
+            }));
+        }
+    }
+    catch (error) {
+        notes.push(`Unable to read PDR ${pdr.path}: ${error.message ?? String(error)}`);
+    }
+    const status = issues.length === 0 ? "pass" : "fail";
+    return {
+        gateId: "gate-pdr-open-questions-quality",
+        gateName: "PDR Open Questions Quality",
+        status,
+        issues,
+        notes: notes.length ? notes : undefined,
+        metadata: { issueCount: issues.length },
+    };
+};

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"PdrOwnershipGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/PdrOwnershipGate.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAEvF,OAAO,EAAE,gBAAgB,EAAe,MAAM,mBAAmB,CAAC;AAElE,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,uBAAuB,CAAC;CACpC;AAuFD,eAAO,MAAM,mBAAmB,GAC9B,OAAO,qBAAqB,KAC3B,OAAO,CAAC,gBAAgB,CAoH1B,CAAC"}

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

@@ -0,0 +1,169 @@
+import { promises as fs } from "node:fs";
+import { getGlossaryEntry, loadGlossary } from "../Glossary.js";
+const isFenceLine = (line) => /^```|^~~~/.test(line.trim());
+const extractSection = (lines, headingMatch) => {
+    let inFence = false;
+    let capture = false;
+    let startLine = 0;
+    const collected = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? "";
+        const trimmed = line.trim();
+        if (isFenceLine(trimmed)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const heading = trimmed.match(/^#{1,6}\s+(.*)$/);
+        if (heading) {
+            const title = heading[1]?.trim() ?? "";
+            if (headingMatch.test(title)) {
+                capture = true;
+                startLine = i + 1;
+                continue;
+            }
+            if (capture)
+                break;
+        }
+        if (capture && trimmed)
+            collected.push(trimmed);
+    }
+    if (!capture)
+        return undefined;
+    return { content: collected, line: startLine };
+};
+const buildIssue = (input) => ({
+    id: input.id,
+    gateId: "gate-pdr-ownership-consent-flow",
+    severity: "high",
+    category: "completeness",
+    artifact: "pdr",
+    message: input.message,
+    remediation: input.remediation,
+    location: input.path
+        ? {
+            kind: "line_range",
+            path: input.path,
+            lineStart: input.line ?? 1,
+            lineEnd: input.line ?? 1,
+            excerpt: input.message,
+        }
+        : { kind: "heading", heading: "PDR", path: input.path },
+    metadata: input.metadata,
+});
+const mentionsOwnership = (lines) => lines.some((line) => /owner|steward|responsible|approval/i.test(line));
+const mentionsCachePolicy = (lines) => lines.some((line) => /policy|cache rules?|governance|approval/i.test(line));
+const mentionsConsentTtl = (lines) => lines.some((line) => /ttl|time[- ]to[- ]live|expiration|expiry/i.test(line));
+const mentionsConsentRevoke = (lines) => lines.some((line) => /revoke|revocation|invalidate|rotation/i.test(line));
+const mentionsCanonicalConsentToken = (lines, canonical) => lines.some((line) => line.toLowerCase().includes(canonical.toLowerCase()));
+const mentionsAlias = (lines, aliases) => {
+    for (const alias of aliases) {
+        if (lines.some((line) => line.toLowerCase().includes(alias.toLowerCase()))) {
+            return alias;
+        }
+    }
+    return undefined;
+};
+export const runPdrOwnershipGate = async (input) => {
+    const pdr = input.artifacts.pdr;
+    if (!pdr) {
+        return {
+            gateId: "gate-pdr-ownership-consent-flow",
+            gateName: "PDR Ownership & Consent Flow",
+            status: "skipped",
+            issues: [],
+            notes: ["No PDR artifact available for ownership/consent validation."],
+        };
+    }
+    const issues = [];
+    const notes = [];
+    const glossary = loadGlossary();
+    const consentEntry = getGlossaryEntry("consent_token", glossary);
+    const canonicalConsent = consentEntry?.term ?? "consent token";
+    const consentAliases = consentEntry?.aliases ?? [];
+    try {
+        const content = await fs.readFile(pdr.path, "utf8");
+        const lines = content.split(/\r?\n/);
+        const ownershipSection = extractSection(lines, /ownership|governance|policy/i);
+        const consentSection = extractSection(lines, /consent|token issuance|installation/i);
+        if (!ownershipSection) {
+            issues.push(buildIssue({
+                id: "gate-pdr-ownership-consent-flow-missing-ownership",
+                message: "PDR is missing an ownership/governance section.",
+                remediation: "Add a section stating ownership of policy changes and cache rules.",
+                path: pdr.path,
+                metadata: { issueType: "missing_ownership_section" },
+            }));
+        }
+        else {
+            if (!mentionsOwnership(ownershipSection.content) || !mentionsCachePolicy(ownershipSection.content)) {
+                issues.push(buildIssue({
+                    id: "gate-pdr-ownership-consent-flow-vague-ownership",
+                    message: "Ownership section does not specify policy/cache rule owners.",
+                    remediation: "Name the policy owner responsible for cache rules and approvals.",
+                    path: pdr.path,
+                    line: ownershipSection.line,
+                    metadata: { issueType: "vague_ownership" },
+                }));
+            }
+        }
+        if (!consentSection) {
+            issues.push(buildIssue({
+                id: "gate-pdr-ownership-consent-flow-missing-consent",
+                message: "PDR is missing a consent flow section.",
+                remediation: "Add a consent flow summary covering issuance, TTL, and revocation.",
+                path: pdr.path,
+                metadata: { issueType: "missing_consent_flow" },
+            }));
+        }
+        else {
+            if (!mentionsConsentTtl(consentSection.content)) {
+                issues.push(buildIssue({
+                    id: "gate-pdr-ownership-consent-flow-missing-ttl",
+                    message: "Consent flow section does not mention token TTL/expiration.",
+                    remediation: "Specify TTL or expiration behavior for the consent token.",
+                    path: pdr.path,
+                    line: consentSection.line,
+                    metadata: { issueType: "missing_ttl" },
+                }));
+            }
+            if (!mentionsConsentRevoke(consentSection.content)) {
+                issues.push(buildIssue({
+                    id: "gate-pdr-ownership-consent-flow-missing-revoke",
+                    message: "Consent flow section does not mention revocation behavior.",
+                    remediation: "Describe how consent tokens can be revoked or invalidated.",
+                    path: pdr.path,
+                    line: consentSection.line,
+                    metadata: { issueType: "missing_revoke" },
+                }));
+            }
+            if (consentEntry) {
+                const usesCanonical = mentionsCanonicalConsentToken(consentSection.content, canonicalConsent);
+                const alias = mentionsAlias(consentSection.content, consentAliases);
+                if (!usesCanonical && alias) {
+                    issues.push(buildIssue({
+                        id: "gate-pdr-ownership-consent-flow-noncanonical-term",
+                        message: `Consent flow uses non-canonical term "${alias}" instead of "${canonicalConsent}".`,
+                        remediation: `Replace "${alias}" with "${canonicalConsent}" to align with glossary terms.`,
+                        path: pdr.path,
+                        line: consentSection.line,
+                        metadata: { issueType: "noncanonical_term", alias, canonicalConsent },
+                    }));
+                }
+            }
+        }
+    }
+    catch (error) {
+        notes.push(`Unable to read PDR ${pdr.path}: ${error.message ?? String(error)}`);
+    }
+    const status = issues.length === 0 ? "pass" : "fail";
+    return {
+        gateId: "gate-pdr-ownership-consent-flow",
+        gateName: "PDR Ownership & Consent Flow",
+        status,
+        issues,
+        notes: notes.length ? notes : undefined,
+        metadata: { issueCount: issues.length },
+    };
+};

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

@@ -0,0 +1,10 @@
+import { DocgenArtifactInventory } from "../../DocgenRunContext.js";
+import { ReviewGateResult } from "../ReviewTypes.js";
+export type PlaceholderArtifactType = "placeholder" | "template_artifact";
+export interface PlaceholderArtifactGateInput {
+    artifacts: DocgenArtifactInventory;
+    allowlist?: string[];
+    denylist?: string[];
+}
+export declare const runPlaceholderArtifactGate: (input: PlaceholderArtifactGateInput) => Promise<ReviewGateResult>;
+//# sourceMappingURL=PlaceholderArtifactGate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PlaceholderArtifactGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/PlaceholderArtifactGate.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAA+B,MAAM,mBAAmB,CAAC;AAElF,MAAM,MAAM,uBAAuB,GAAG,aAAa,GAAG,mBAAmB,CAAC;AAE1E,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,uBAAuB,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AA8LD,eAAO,MAAM,0BAA0B,GACrC,OAAO,4BAA4B,KAClC,OAAO,CAAC,gBAAgB,CAmG1B,CAAC"}