@mcoda/core 0.1.8 → 0.1.11

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

@@ -0,0 +1,266 @@
+import { promises as fs } from "node:fs";
+import { extractOpenApiPaths, findOpenApiPathLine, normalizeOpenApiPath, } from "../../../openapi/OpenApiService.js";
+const ISSUE_SEVERITY = {
+    doc_missing_openapi: "high",
+    openapi_missing_docs: "medium",
+};
+const RELEVANT_HEADING = /\b(interfaces?|api(?:s)?|endpoints?|routes?|contracts?)\b/i;
+const EXAMPLE_HEADING = /example|sample/i;
+const PATH_PATTERN = /\/[A-Za-z0-9._~{}-]+(?:\/[A-Za-z0-9._~{}-]+)*/g;
+const URL_PATTERN = /https?:\/\/[^\s)]+/g;
+const isFenceLine = (line) => /^```|^~~~/.test(line.trim());
+const isRelevantHeading = (title) => RELEVANT_HEADING.test(title);
+const isExampleHeading = (title) => EXAMPLE_HEADING.test(title);
+const sanitizePath = (candidate) => {
+    let cleaned = candidate.trim();
+    cleaned = cleaned.replace(/^[`"'\\[(]+/, "");
+    cleaned = cleaned.replace(/[`"',.;:!?]+$/g, "");
+    cleaned = cleaned.replace(/[\]\)}]+$/g, "");
+    return cleaned;
+};
+const extractPathsFromLine = (line) => {
+    const results = [];
+    const urls = line.match(URL_PATTERN) ?? [];
+    for (const url of urls) {
+        try {
+            const parsed = new URL(url);
+            if (parsed.pathname && parsed.pathname !== "/") {
+                results.push(parsed.pathname);
+            }
+        }
+        catch {
+            // ignore invalid URLs
+        }
+    }
+    const scrubbed = line.replace(URL_PATTERN, " ");
+    const matches = scrubbed.matchAll(PATH_PATTERN);
+    for (const match of matches) {
+        const candidate = sanitizePath(match[0] ?? "");
+        if (!candidate || candidate === "/" || candidate.startsWith("//"))
+            continue;
+        results.push(candidate);
+    }
+    return results;
+};
+const extractDocEndpoints = async (record) => {
+    const entries = [];
+    const notes = [];
+    try {
+        const content = await fs.readFile(record.path, "utf8");
+        const lines = content.split(/\r?\n/);
+        let inFence = false;
+        let capture = false;
+        let sectionLevel = 0;
+        let skipExample = false;
+        let skipLevel = 0;
+        let currentHeading;
+        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 headingMatch = trimmed.match(/^(#{1,6})\s+(.*)$/);
+            if (headingMatch) {
+                const level = headingMatch[1]?.length ?? 0;
+                if (skipExample && level <= skipLevel) {
+                    skipExample = false;
+                }
+                const title = headingMatch[2]?.trim() ?? "";
+                currentHeading = title || undefined;
+                const relevant = isRelevantHeading(title);
+                if (relevant) {
+                    capture = true;
+                    sectionLevel = level;
+                    skipExample = isExampleHeading(title);
+                    skipLevel = skipExample ? level : 0;
+                    continue;
+                }
+                if (capture && level <= sectionLevel) {
+                    capture = false;
+                }
+                if (capture && isExampleHeading(title)) {
+                    skipExample = true;
+                    skipLevel = level;
+                }
+                continue;
+            }
+            if (!capture || skipExample || !trimmed)
+                continue;
+            const candidates = extractPathsFromLine(line);
+            for (const candidate of candidates) {
+                const normalized = normalizeOpenApiPath(candidate);
+                if (!normalized || normalized === "/")
+                    continue;
+                entries.push({
+                    path: candidate,
+                    normalized,
+                    lineNumber: i + 1,
+                    heading: currentHeading,
+                    record,
+                });
+            }
+        }
+    }
+    catch (error) {
+        notes.push(`Unable to read doc ${record.path}: ${error.message ?? String(error)}`);
+    }
+    return { entries, notes };
+};
+const extractOpenApiEndpoints = async (records) => {
+    const entries = [];
+    const notes = [];
+    for (const record of records) {
+        try {
+            const raw = await fs.readFile(record.path, "utf8");
+            const result = extractOpenApiPaths(raw);
+            if (result.errors.length > 0) {
+                notes.push(...result.errors.map((error) => `${record.path}: ${error}`));
+            }
+            for (const entry of result.paths) {
+                const normalized = normalizeOpenApiPath(entry);
+                if (!normalized || normalized === "/")
+                    continue;
+                const lineNumber = findOpenApiPathLine(raw, entry) ?? 1;
+                entries.push({
+                    path: entry,
+                    normalized,
+                    lineNumber,
+                    record,
+                });
+            }
+        }
+        catch (error) {
+            notes.push(`Unable to read OpenAPI spec ${record.path}: ${error.message ?? String(error)}`);
+        }
+    }
+    return { entries, notes };
+};
+const dedupeByNormalized = (entries) => {
+    const seen = new Set();
+    const result = [];
+    for (const entry of entries) {
+        if (seen.has(entry.normalized))
+            continue;
+        seen.add(entry.normalized);
+        result.push(entry);
+    }
+    return result;
+};
+const summarizePaths = (label, entries) => {
+    if (entries.length === 0)
+        return undefined;
+    const preview = entries.slice(0, 5).map((entry) => entry.path).join(", ");
+    const suffix = entries.length > 5 ? ` (+${entries.length - 5} more)` : "";
+    return `${label} (${entries.length}): ${preview}${suffix}`;
+};
+const buildIssue = (input) => {
+    const { issueType, entry } = input;
+    let message = "";
+    let remediation = "";
+    switch (issueType) {
+        case "doc_missing_openapi":
+            message = `Endpoint "${entry.path}" appears in docs but is missing from OpenAPI.`;
+            remediation = "Add the endpoint to OpenAPI or remove it from the interface list.";
+            break;
+        case "openapi_missing_docs":
+            message = `OpenAPI endpoint "${entry.path}" is not mentioned in docs interface/API sections.`;
+            remediation = "Document the endpoint in the Interfaces/API sections.";
+            break;
+        default:
+            message = `OpenAPI coverage issue detected for ${entry.path}.`;
+            remediation = "Align doc interface lists with OpenAPI.";
+    }
+    return {
+        id: `gate-openapi-endpoint-coverage-${entry.record.kind}-${issueType}-${entry.lineNumber}`,
+        gateId: "gate-openapi-endpoint-coverage",
+        severity: ISSUE_SEVERITY[issueType],
+        category: "api",
+        artifact: entry.record.kind,
+        message,
+        remediation,
+        location: {
+            kind: "line_range",
+            path: entry.record.path,
+            lineStart: entry.lineNumber,
+            lineEnd: entry.lineNumber,
+            excerpt: entry.path,
+        },
+        metadata: {
+            issueType,
+            normalizedPath: entry.normalized,
+            heading: entry.heading,
+        },
+    };
+};
+export const runOpenApiCoverageGate = async (input) => {
+    const issues = [];
+    const notes = [];
+    const docRecords = [input.artifacts.pdr, input.artifacts.sds].filter((record) => Boolean(record));
+    const openapiRecords = input.artifacts.openapi ?? [];
+    if (docRecords.length === 0 && openapiRecords.length === 0) {
+        return {
+            gateId: "gate-openapi-endpoint-coverage",
+            gateName: "OpenAPI Endpoint Coverage",
+            status: "skipped",
+            issues,
+            notes: ["No PDR/SDS or OpenAPI artifacts available for endpoint coverage checks."],
+        };
+    }
+    if (docRecords.length === 0) {
+        notes.push("No PDR/SDS artifacts available for endpoint coverage checks.");
+    }
+    if (openapiRecords.length === 0) {
+        notes.push("No OpenAPI artifacts available for endpoint coverage checks.");
+    }
+    const docResults = await Promise.all(docRecords.map((record) => extractDocEndpoints(record)));
+    const docEntries = docResults.flatMap((result) => result.entries);
+    docResults.forEach((result) => notes.push(...result.notes));
+    const openapiResult = await extractOpenApiEndpoints(openapiRecords);
+    const openapiEntries = openapiResult.entries;
+    notes.push(...openapiResult.notes);
+    if (docEntries.length === 0 && openapiEntries.length === 0) {
+        return {
+            gateId: "gate-openapi-endpoint-coverage",
+            gateName: "OpenAPI Endpoint Coverage",
+            status: "skipped",
+            issues,
+            notes: notes.length > 0 ? notes : ["No endpoints detected in docs or OpenAPI."],
+        };
+    }
+    const uniqueDocEntries = dedupeByNormalized(docEntries);
+    const uniqueOpenapiEntries = dedupeByNormalized(openapiEntries);
+    const openapiSet = new Set(uniqueOpenapiEntries.map((entry) => entry.normalized));
+    const docSet = new Set(uniqueDocEntries.map((entry) => entry.normalized));
+    const docMissing = uniqueDocEntries.filter((entry) => !openapiSet.has(entry.normalized));
+    const openapiMissing = uniqueOpenapiEntries.filter((entry) => !docSet.has(entry.normalized));
+    for (const entry of docMissing) {
+        issues.push(buildIssue({ issueType: "doc_missing_openapi", entry }));
+    }
+    for (const entry of openapiMissing) {
+        issues.push(buildIssue({ issueType: "openapi_missing_docs", entry }));
+    }
+    const docSummary = summarizePaths("Doc endpoints missing in OpenAPI", docMissing);
+    if (docSummary)
+        notes.push(docSummary);
+    const openapiSummary = summarizePaths("OpenAPI endpoints missing in docs", openapiMissing);
+    if (openapiSummary)
+        notes.push(openapiSummary);
+    const status = issues.length > 0 ? "fail" : "pass";
+    return {
+        gateId: "gate-openapi-endpoint-coverage",
+        gateName: "OpenAPI Endpoint Coverage",
+        status,
+        issues,
+        notes: notes.length > 0 ? notes : undefined,
+        metadata: {
+            docPathCount: uniqueDocEntries.length,
+            openapiPathCount: uniqueOpenapiEntries.length,
+            docMissingCount: docMissing.length,
+            openapiMissingCount: openapiMissing.length,
+        },
+    };
+};

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"OpenApiSchemaSanityGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/OpenApiSchemaSanityGate.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAe,MAAM,mBAAmB,CAAC;AAGlE,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,uBAAuB,CAAC;CACpC;AA2BD,eAAO,MAAM,0BAA0B,GACrC,OAAO,4BAA4B,KAClC,OAAO,CAAC,gBAAgB,CAwC1B,CAAC"}

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

@@ -0,0 +1,59 @@
+import { promises as fs } from "node:fs";
+import { validateOpenApiSchemaContent } from "../../../openapi/OpenApiService.js";
+const buildIssue = (input) => {
+    const excerpt = input.error.length > 120 ? `${input.error.slice(0, 117)}...` : input.error;
+    return {
+        id: `gate-openapi-schema-sanity-${input.index + 1}`,
+        gateId: "gate-openapi-schema-sanity",
+        severity: "high",
+        category: "api",
+        artifact: "openapi",
+        message: input.error,
+        remediation: "Fix OpenAPI schema errors and regenerate the spec.",
+        location: {
+            kind: "line_range",
+            path: input.record.path,
+            lineStart: 1,
+            lineEnd: 1,
+            excerpt,
+        },
+        metadata: { recordPath: input.record.path },
+    };
+};
+export const runOpenApiSchemaSanityGate = async (input) => {
+    const records = input.artifacts.openapi ?? [];
+    if (records.length === 0) {
+        return {
+            gateId: "gate-openapi-schema-sanity",
+            gateName: "OpenAPI Schema Sanity",
+            status: "skipped",
+            issues: [],
+            notes: ["No OpenAPI artifacts available for schema sanity checks."],
+        };
+    }
+    const issues = [];
+    const notes = [];
+    for (const record of records) {
+        try {
+            const content = await fs.readFile(record.path, "utf8");
+            const result = validateOpenApiSchemaContent(content);
+            if (result.errors.length > 0) {
+                result.errors.forEach((error, index) => {
+                    issues.push(buildIssue({ record, error, index }));
+                });
+            }
+        }
+        catch (error) {
+            notes.push(`Unable to read OpenAPI spec ${record.path}: ${error.message ?? String(error)}`);
+        }
+    }
+    const status = issues.length === 0 ? "pass" : "fail";
+    return {
+        gateId: "gate-openapi-schema-sanity",
+        gateName: "OpenAPI Schema Sanity",
+        status,
+        issues,
+        notes: notes.length > 0 ? notes : undefined,
+        metadata: { issueCount: issues.length, artifactCount: records.length },
+    };
+};

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"OpenQuestionsGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/OpenQuestionsGate.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAA+B,MAAM,mBAAmB,CAAC;AAElF,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,uBAAuB,CAAC;CACpC;AAuLD,eAAO,MAAM,oBAAoB,GAC/B,OAAO,sBAAsB,KAC5B,OAAO,CAAC,gBAAgB,CA+C1B,CAAC"}

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

@@ -0,0 +1,200 @@
+import { promises as fs } from "node:fs";
+const OPTIONAL_HINTS = [
+    "optional",
+    "nice to have",
+    "future",
+    "later",
+    "explore",
+    "could",
+    "might",
+    "maybe",
+];
+const REQUIRED_HINTS = [
+    "must",
+    "required",
+    "need to decide",
+    "decision",
+    "blocker",
+    "blocking",
+    "critical",
+    "tbd",
+    "to be determined",
+];
+const IMPLICIT_PATTERNS = [
+    /\?$/,
+    /\bshould we\b/i,
+    /\bneeds? decision\b/i,
+    /\bdecide (whether|if|on)\b/i,
+    /\bto be determined\b/i,
+    /\btbd\b/i,
+    /\bopen question\b/i,
+];
+const isFenceLine = (line) => /^```|^~~~/.test(line.trim());
+const isExampleHeading = (heading) => /example|sample/i.test(heading);
+const isOpenQuestionsHeading = (heading) => /open (questions?|issues?|items?)|unresolved questions?/i.test(heading);
+const RESOLVED_HINTS = [/^\s*resolved[:\]]/i, /^\s*decision:/i, /\[resolved\]/i];
+const isResolvedLine = (line) => RESOLVED_HINTS.some((pattern) => pattern.test(line.trim()));
+const normalizeQuestion = (text) => text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim();
+const classifyRequired = (text, inOpenSection) => {
+    const lower = text.toLowerCase();
+    if (lower.includes("[optional]"))
+        return false;
+    if (lower.includes("[required]"))
+        return true;
+    if (OPTIONAL_HINTS.some((hint) => lower.includes(hint)))
+        return false;
+    if (REQUIRED_HINTS.some((hint) => lower.includes(hint)))
+        return true;
+    return inOpenSection;
+};
+const resolveTarget = (text, record) => {
+    const lower = text.toLowerCase();
+    if (/(openapi|endpoint|api|route)/i.test(lower))
+        return "openapi";
+    if (/(schema|database|sql|table)/i.test(lower))
+        return "sql";
+    if (/(deploy|deployment|k8s|kubernetes|docker|infra)/i.test(lower))
+        return "deployment";
+    return record.kind;
+};
+const buildIssue = (question) => {
+    const severity = question.required ? "high" : "low";
+    const message = question.required
+        ? `Open question requires resolution: ${question.text}`
+        : `Optional exploration: ${question.text}`;
+    const remediation = question.required
+        ? `Resolve this decision in ${question.target}.`
+        : `Consider addressing this question in ${question.target}.`;
+    return {
+        id: `gate-open-questions-${question.record.kind}-${question.lineNumber}`,
+        gateId: "gate-open-questions",
+        severity,
+        category: "open_questions",
+        artifact: question.record.kind,
+        message,
+        remediation,
+        location: {
+            kind: "line_range",
+            path: question.record.path,
+            lineStart: question.lineNumber,
+            lineEnd: question.lineNumber,
+            excerpt: question.text,
+        },
+        metadata: {
+            question: question.text,
+            normalized: question.normalized,
+            required: question.required,
+            target: question.target,
+            heading: question.heading,
+        },
+    };
+};
+const cleanQuestionText = (line) => {
+    const trimmed = line.trim();
+    const withoutBullet = trimmed.replace(/^[-*+]\s+/, "").replace(/^\d+\.\s+/, "");
+    return withoutBullet.trim();
+};
+const isImplicitQuestion = (line) => IMPLICIT_PATTERNS.some((pattern) => pattern.test(line.trim()));
+const extractQuestions = async (record) => {
+    const notes = [];
+    try {
+        const content = await fs.readFile(record.path, "utf8");
+        const lines = content.split(/\r?\n/);
+        const questions = [];
+        let inFence = false;
+        let allowSection = false;
+        let inOpenSection = 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;
+                inOpenSection = currentHeading ? isOpenQuestionsHeading(currentHeading) : false;
+                continue;
+            }
+            if (inFence || allowSection)
+                continue;
+            if (isResolvedLine(trimmed))
+                continue;
+            const explicitQuestion = inOpenSection;
+            const implicitQuestion = !inOpenSection && isImplicitQuestion(trimmed);
+            if (!explicitQuestion && !implicitQuestion)
+                continue;
+            const questionText = cleanQuestionText(trimmed);
+            if (!questionText)
+                continue;
+            const normalized = normalizeQuestion(questionText);
+            if (!normalized)
+                continue;
+            questions.push({
+                text: questionText,
+                normalized,
+                required: classifyRequired(questionText, inOpenSection),
+                target: resolveTarget(questionText, record),
+                record,
+                lineNumber: i + 1,
+                heading: currentHeading,
+            });
+        }
+        return { questions, notes };
+    }
+    catch (error) {
+        notes.push(`Unable to scan ${record.path}: ${error.message ?? String(error)}`);
+        return { questions: [], notes };
+    }
+};
+export const runOpenQuestionsGate = async (input) => {
+    const records = [input.artifacts.pdr, input.artifacts.sds].filter((record) => Boolean(record));
+    if (records.length === 0) {
+        return {
+            gateId: "gate-open-questions",
+            gateName: "Open Questions Extraction",
+            status: "skipped",
+            issues: [],
+            notes: ["No PDR/SDS artifacts available for open question extraction."],
+        };
+    }
+    const notes = [];
+    const extracted = [];
+    for (const record of records) {
+        const result = await extractQuestions(record);
+        extracted.push(...result.questions);
+        notes.push(...result.notes);
+    }
+    const seen = new Set();
+    const unique = [];
+    for (const question of extracted) {
+        if (seen.has(question.normalized))
+            continue;
+        seen.add(question.normalized);
+        unique.push(question);
+    }
+    const issues = unique.map(buildIssue);
+    const requiredCount = unique.filter((q) => q.required).length;
+    const optionalCount = unique.length - requiredCount;
+    const status = requiredCount > 0 ? "fail" : optionalCount > 0 ? "warn" : "pass";
+    return {
+        gateId: "gate-open-questions",
+        gateName: "Open Questions Extraction",
+        status,
+        issues,
+        notes: notes.length > 0 ? notes : undefined,
+        metadata: {
+            questionCount: unique.length,
+            requiredCount,
+            optionalCount,
+        },
+    };
+};

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"PdrInterfacesGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/PdrInterfacesGate.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAe,MAAM,mBAAmB,CAAC;AAGlE,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,uBAAuB,CAAC;CACpC;AAmFD,eAAO,MAAM,oBAAoB,GAC/B,OAAO,sBAAsB,KAC5B,OAAO,CAAC,gBAAgB,CAqG1B,CAAC"}