@mcoda/core 0.1.8 → 0.1.11

package/dist/services/docs/review/ReviewTypes.d.ts

@@ -0,0 +1,76 @@
+import { DocArtifactKind } from "../DocgenRunContext.js";
+export type ReviewSeverity = "blocker" | "high" | "medium" | "low" | "info";
+export type ReviewIssueCategory = "structure" | "content" | "consistency" | "completeness" | "compliance" | "terminology" | "open_questions" | "api" | "sql" | "deployment" | "decision" | "other";
+export type ReviewIssueLocation = {
+    kind: "heading";
+    heading: string;
+    path?: string;
+} | {
+    kind: "line_range";
+    path: string;
+    lineStart: number;
+    lineEnd: number;
+    excerpt?: string;
+};
+export interface ReviewIssue {
+    id: string;
+    gateId: string;
+    severity: ReviewSeverity;
+    category: ReviewIssueCategory;
+    artifact: DocArtifactKind;
+    message: string;
+    remediation: string;
+    location: ReviewIssueLocation;
+    metadata?: Record<string, unknown>;
+}
+export type ReviewGateStatus = "pass" | "warn" | "fail" | "skipped";
+export interface ReviewGateResult {
+    gateId: string;
+    gateName: string;
+    status: ReviewGateStatus;
+    issues: ReviewIssue[];
+    notes?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface ReviewDecision {
+    id: string;
+    summary: string;
+    rationale: string;
+    decidedAt: string;
+    relatedIssueIds?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface ReviewFix {
+    issueId: string;
+    summary: string;
+    appliedAt: string;
+    metadata?: Record<string, unknown>;
+}
+export type ReviewOutcomeStatus = "pass" | "warn" | "fail";
+export interface ReviewSummary {
+    status: ReviewOutcomeStatus;
+    issueCount: number;
+    severityCounts: Record<ReviewSeverity, number>;
+    gateCounts: Record<ReviewGateStatus, number>;
+}
+export interface ReviewOutcome {
+    version: 1;
+    generatedAt: string;
+    gateResults: ReviewGateResult[];
+    issues: ReviewIssue[];
+    remainingOpenItems: ReviewIssue[];
+    fixesApplied: ReviewFix[];
+    decisions: ReviewDecision[];
+    summary: ReviewSummary;
+}
+export declare const sortIssues: (issues: ReviewIssue[]) => ReviewIssue[];
+export declare const flattenIssues: (gateResults: ReviewGateResult[]) => ReviewIssue[];
+export declare const summarizeGateResults: (gateResults: ReviewGateResult[]) => ReviewSummary;
+export declare const aggregateReviewOutcome: (input: {
+    gateResults: ReviewGateResult[];
+    remainingOpenItems?: ReviewIssue[];
+    fixesApplied?: ReviewFix[];
+    decisions?: ReviewDecision[];
+    generatedAt?: string;
+}) => ReviewOutcome;
+//# sourceMappingURL=ReviewTypes.d.ts.map

package/dist/services/docs/review/ReviewTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReviewTypes.d.ts","sourceRoot":"","sources":["../../../../src/services/docs/review/ReviewTypes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;AAE5E,MAAM,MAAM,mBAAmB,GAC3B,WAAW,GACX,SAAS,GACT,aAAa,GACb,cAAc,GACd,YAAY,GACZ,aAAa,GACb,gBAAgB,GAChB,KAAK,GACL,KAAK,GACL,YAAY,GACZ,UAAU,GACV,OAAO,CAAC;AAEZ,MAAM,MAAM,mBAAmB,GAC3B;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GACD;IACE,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEN,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,EAAE,eAAe,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAEpE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,CAAC,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,kBAAkB,EAAE,WAAW,EAAE,CAAC;IAClC,YAAY,EAAE,SAAS,EAAE,CAAC;IAC1B,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,OAAO,EAAE,aAAa,CAAC;CACxB;AAuCD,eAAO,MAAM,UAAU,GAAI,QAAQ,WAAW,EAAE,KAAG,WAAW,EAU7D,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,aAAa,gBAAgB,EAAE,KAAG,WAAW,EAM1E,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,aAAa,gBAAgB,EAAE,KAAG,aAiBtE,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,OAAO;IAC5C,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,kBAAkB,CAAC,EAAE,WAAW,EAAE,CAAC;IACnC,YAAY,CAAC,EAAE,SAAS,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,KAAG,aAsBH,CAAC"}

package/dist/services/docs/review/ReviewTypes.js

@@ -0,0 +1,94 @@
+const severityOrder = {
+    blocker: 0,
+    high: 1,
+    medium: 2,
+    low: 3,
+    info: 4,
+};
+const gateStatusOrder = {
+    fail: 0,
+    warn: 1,
+    pass: 2,
+    skipped: 3,
+};
+const emptySeverityCounts = () => ({
+    blocker: 0,
+    high: 0,
+    medium: 0,
+    low: 0,
+    info: 0,
+});
+const emptyGateCounts = () => ({
+    pass: 0,
+    warn: 0,
+    fail: 0,
+    skipped: 0,
+});
+const locationKey = (location) => {
+    if (location.kind === "heading") {
+        return `${location.path ?? ""}#${location.heading}`;
+    }
+    return `${location.path}:${location.lineStart}-${location.lineEnd}`;
+};
+export const sortIssues = (issues) => {
+    return issues.slice().sort((a, b) => {
+        const severityDiff = severityOrder[a.severity] - severityOrder[b.severity];
+        if (severityDiff !== 0)
+            return severityDiff;
+        const gateDiff = a.gateId.localeCompare(b.gateId);
+        if (gateDiff !== 0)
+            return gateDiff;
+        const artifactDiff = a.artifact.localeCompare(b.artifact);
+        if (artifactDiff !== 0)
+            return artifactDiff;
+        return locationKey(a.location).localeCompare(locationKey(b.location));
+    });
+};
+export const flattenIssues = (gateResults) => {
+    const collected = [];
+    for (const result of gateResults) {
+        collected.push(...result.issues);
+    }
+    return collected;
+};
+export const summarizeGateResults = (gateResults) => {
+    const gateCounts = emptyGateCounts();
+    const severityCounts = emptySeverityCounts();
+    let status = "pass";
+    let issueCount = 0;
+    for (const gate of gateResults) {
+        gateCounts[gate.status] = (gateCounts[gate.status] ?? 0) + 1;
+        if (gate.status === "fail")
+            status = "fail";
+        if (gate.status === "warn" && status === "pass")
+            status = "warn";
+        for (const issue of gate.issues) {
+            issueCount += 1;
+            severityCounts[issue.severity] = (severityCounts[issue.severity] ?? 0) + 1;
+        }
+    }
+    return { status, issueCount, severityCounts, gateCounts };
+};
+export const aggregateReviewOutcome = (input) => {
+    const gateResults = input.gateResults.slice().sort((a, b) => {
+        const statusDiff = gateStatusOrder[a.status] - gateStatusOrder[b.status];
+        if (statusDiff !== 0)
+            return statusDiff;
+        return a.gateId.localeCompare(b.gateId);
+    });
+    const issues = sortIssues(flattenIssues(gateResults));
+    const remainingOpenItems = sortIssues(input.remainingOpenItems ?? []);
+    const fixesApplied = (input.fixesApplied ?? []).slice().sort((a, b) => a.issueId.localeCompare(b.issueId));
+    const decisions = (input.decisions ?? []).slice().sort((a, b) => a.decidedAt.localeCompare(b.decidedAt));
+    const summary = summarizeGateResults(gateResults);
+    return {
+        version: 1,
+        generatedAt: input.generatedAt ?? new Date().toISOString(),
+        gateResults,
+        issues,
+        remainingOpenItems,
+        fixesApplied,
+        decisions,
+        summary,
+    };
+};

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"AdminOpenApiSpecGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/AdminOpenApiSpecGate.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAe,MAAM,mBAAmB,CAAC;AAGlE,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,uBAAuB,CAAC;CACpC;AA+BD,eAAO,MAAM,uBAAuB,GAClC,OAAO,yBAAyB,KAC/B,OAAO,CAAC,gBAAgB,CAuF1B,CAAC"}

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

@@ -0,0 +1,93 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { findAdminSurfaceMentions } from "../../../openapi/OpenApiService.js";
+const buildIssue = (input) => {
+    return {
+        id: `gate-admin-openapi-spec-${input.index + 1}`,
+        gateId: "gate-admin-openapi-spec",
+        severity: "high",
+        category: "api",
+        artifact: input.record.kind,
+        message: "Admin surface referenced without a matching admin OpenAPI spec.",
+        remediation: "Generate or provide an admin OpenAPI spec for the referenced admin surface.",
+        location: {
+            kind: "line_range",
+            path: input.record.path,
+            lineStart: input.line,
+            lineEnd: input.line,
+            excerpt: input.excerpt,
+        },
+        metadata: {
+            heading: input.heading,
+            recordPath: input.record.path,
+        },
+    };
+};
+export const runAdminOpenApiSpecGate = async (input) => {
+    const records = [input.artifacts.pdr, input.artifacts.sds].filter((record) => Boolean(record));
+    if (records.length === 0) {
+        return {
+            gateId: "gate-admin-openapi-spec",
+            gateName: "Admin OpenAPI Spec",
+            status: "skipped",
+            issues: [],
+            notes: ["No PDR/SDS artifacts available for admin surface checks."],
+        };
+    }
+    const notes = [];
+    const mentions = [];
+    for (const record of records) {
+        try {
+            const content = await fs.readFile(record.path, "utf8");
+            const found = findAdminSurfaceMentions(content);
+            for (const mention of found) {
+                mentions.push({
+                    record,
+                    line: mention.line,
+                    excerpt: mention.excerpt,
+                    heading: mention.heading,
+                });
+            }
+        }
+        catch (error) {
+            notes.push(`Unable to scan ${record.path} for admin surfaces: ${error.message ?? String(error)}`);
+        }
+    }
+    if (mentions.length === 0) {
+        return {
+            gateId: "gate-admin-openapi-spec",
+            gateName: "Admin OpenAPI Spec",
+            status: "pass",
+            issues: [],
+            notes: notes.length > 0 ? notes : undefined,
+            metadata: { mentionCount: 0 },
+        };
+    }
+    const openapiRecords = input.artifacts.openapi ?? [];
+    const hasAdminSpec = openapiRecords.some((record) => record.variant === "admin" || /admin/i.test(path.basename(record.path)));
+    if (hasAdminSpec) {
+        return {
+            gateId: "gate-admin-openapi-spec",
+            gateName: "Admin OpenAPI Spec",
+            status: "pass",
+            issues: [],
+            notes: notes.length > 0 ? notes : undefined,
+            metadata: { mentionCount: mentions.length, hasAdminSpec: true },
+        };
+    }
+    const issues = mentions.map((mention, index) => buildIssue({
+        record: mention.record,
+        line: mention.line,
+        excerpt: mention.excerpt,
+        heading: mention.heading,
+        index,
+    }));
+    return {
+        gateId: "gate-admin-openapi-spec",
+        gateName: "Admin OpenAPI Spec",
+        status: "fail",
+        issues,
+        notes: notes.length > 0 ? notes : undefined,
+        metadata: { mentionCount: mentions.length, hasAdminSpec: false },
+    };
+};

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"ApiPathConsistencyGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/ApiPathConsistencyGate.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAA+B,MAAM,mBAAmB,CAAC;AAGlF,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,uBAAuB,CAAC;CACpC;AAqOD,eAAO,MAAM,yBAAyB,GACpC,OAAO,2BAA2B,KACjC,OAAO,CAAC,gBAAgB,CAgI1B,CAAC"}

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

@@ -0,0 +1,308 @@
+import { promises as fs } from "node:fs";
+import { extractOpenApiPaths, normalizeOpenApiPath } from "../../../openapi/OpenApiService.js";
+const ISSUE_SEVERITY = {
+    prefix_mismatch: "high",
+    doc_missing_openapi: "high",
+    openapi_missing_docs: "medium",
+};
+const PREFIX_HINTS = new Set(["api", "apis", "internal", "public", "private", "admin"]);
+const VERSION_PATTERN = /^v\d+(?:\.\d+)?$/i;
+const PATH_PATTERN = /\/[A-Za-z0-9._~{}-]+(?:\/[A-Za-z0-9._~{}-]+)*/g;
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const isFenceLine = (line) => /^```|^~~~/.test(line.trim());
+const isExampleHeading = (heading) => /example|sample/i.test(heading);
+const sanitizePath = (candidate) => {
+    let cleaned = candidate.trim();
+    cleaned = cleaned.replace(/^[`"']+/, "");
+    cleaned = cleaned.replace(/[`"'\])},.;:!?]+$/g, "");
+    return cleaned;
+};
+const derivePrefix = (value) => {
+    const normalized = normalizeOpenApiPath(value);
+    const segments = normalized.split("/").filter(Boolean);
+    if (segments.length === 0)
+        return "/";
+    const first = segments[0]?.toLowerCase();
+    const second = segments[1]?.toLowerCase();
+    if (first && PREFIX_HINTS.has(first)) {
+        if (second && VERSION_PATTERN.test(second)) {
+            return `/${first}/${second}`;
+        }
+        return `/${first}`;
+    }
+    if (first && VERSION_PATTERN.test(first)) {
+        return `/${first}`;
+    }
+    return "/";
+};
+const selectCanonicalPrefix = (paths) => {
+    if (paths.length === 0)
+        return undefined;
+    const counts = new Map();
+    for (const entry of paths) {
+        counts.set(entry.prefix, (counts.get(entry.prefix) ?? 0) + 1);
+    }
+    const sorted = Array.from(counts.entries()).sort((a, b) => {
+        if (b[1] !== a[1])
+            return b[1] - a[1];
+        if (b[0].length !== a[0].length)
+            return b[0].length - a[0].length;
+        return a[0].localeCompare(b[0]);
+    });
+    return sorted[0]?.[0];
+};
+const buildIssue = (input) => {
+    const { issueType, entry, canonicalPrefix, expectedPrefix, actualPrefix } = input;
+    let message = "";
+    let remediation = "";
+    switch (issueType) {
+        case "prefix_mismatch":
+            message = `Expected API prefix "${expectedPrefix}" but found "${actualPrefix}" in ${entry.path}.`;
+            remediation = `Align endpoints to use the canonical prefix "${canonicalPrefix}".`;
+            break;
+        case "doc_missing_openapi":
+            message = `Endpoint "${entry.path}" appears in docs but is not present in OpenAPI.`;
+            remediation = "Update OpenAPI paths or remove/adjust the docs endpoint list.";
+            break;
+        case "openapi_missing_docs":
+            message = `OpenAPI endpoint "${entry.path}" is not described in docs.`;
+            remediation = "Add this endpoint to PDR/SDS interface sections.";
+            break;
+        default:
+            message = `API path consistency issue detected for ${entry.path}.`;
+            remediation = "Align docs and OpenAPI paths.";
+    }
+    return {
+        id: `gate-api-path-consistency-${entry.record.kind}-${issueType}-${entry.lineNumber}`,
+        gateId: "gate-api-path-consistency",
+        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,
+            canonicalPrefix,
+            expectedPrefix,
+            actualPrefix,
+            normalizedPath: entry.normalized,
+            heading: entry.heading,
+        },
+    };
+};
+const dedupeByNormalized = (entries) => {
+    const seen = new Set();
+    const result = [];
+    for (const entry of entries) {
+        const key = `${entry.record.kind}:${entry.normalized}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(entry);
+    }
+    return result;
+};
+const extractDocPaths = async (record) => {
+    const notes = [];
+    try {
+        const content = await fs.readFile(record.path, "utf8");
+        const lines = content.split(/\r?\n/);
+        const paths = [];
+        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;
+            const matches = line.matchAll(PATH_PATTERN);
+            for (const match of matches) {
+                const candidate = sanitizePath(match[0]);
+                if (!candidate || candidate === "/" || candidate.startsWith("//"))
+                    continue;
+                const normalized = normalizeOpenApiPath(candidate);
+                if (!normalized || normalized === "/")
+                    continue;
+                paths.push({
+                    path: candidate,
+                    normalized,
+                    prefix: derivePrefix(normalized),
+                    lineNumber: i + 1,
+                    heading: currentHeading,
+                    record,
+                });
+            }
+        }
+        return { paths, notes };
+    }
+    catch (error) {
+        notes.push(`Unable to scan ${record.path}: ${error.message ?? String(error)}`);
+        return { paths: [], notes };
+    }
+};
+const findOpenApiLine = (lines, target) => {
+    const escaped = escapeRegExp(target);
+    const pattern = new RegExp(`^\\s*['"]?${escaped}['"]?\\s*:`);
+    for (let i = 0; i < lines.length; i += 1) {
+        if (pattern.test(lines[i] ?? "")) {
+            return i + 1;
+        }
+    }
+    return undefined;
+};
+const extractOpenApiRecords = async (records) => {
+    const notes = [];
+    const paths = [];
+    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((err) => `${record.path}: ${err}`));
+            }
+            const lines = raw.split(/\r?\n/);
+            for (const entry of result.paths) {
+                const normalized = normalizeOpenApiPath(entry);
+                if (!normalized || normalized === "/")
+                    continue;
+                const lineNumber = findOpenApiLine(lines, entry) ?? 1;
+                paths.push({
+                    path: entry,
+                    normalized,
+                    prefix: derivePrefix(normalized),
+                    lineNumber,
+                    record,
+                });
+            }
+        }
+        catch (error) {
+            notes.push(`Unable to read OpenAPI spec ${record.path}: ${error.message ?? String(error)}`);
+        }
+    }
+    return { paths, notes };
+};
+export const runApiPathConsistencyGate = async (input) => {
+    const issues = [];
+    const notes = [];
+    const docRecords = [input.artifacts.pdr, input.artifacts.sds].filter((record) => Boolean(record));
+    const openapiCandidates = input.artifacts.openapi ?? [];
+    const primaryOpenapi = openapiCandidates.filter((record) => record.variant !== "admin");
+    const openapiRecords = primaryOpenapi.length > 0 ? primaryOpenapi : openapiCandidates;
+    if (docRecords.length === 0 && openapiRecords.length === 0) {
+        return {
+            gateId: "gate-api-path-consistency",
+            gateName: "API Path Consistency",
+            status: "skipped",
+            issues,
+            notes: ["No PDR/SDS or OpenAPI artifacts available for path consistency checks."],
+        };
+    }
+    const docPathResults = await Promise.all(docRecords.map((record) => extractDocPaths(record)));
+    const docPaths = docPathResults.flatMap((result) => result.paths);
+    docPathResults.forEach((result) => notes.push(...result.notes));
+    const openapiResult = await extractOpenApiRecords(openapiRecords);
+    const openapiPaths = openapiResult.paths;
+    notes.push(...openapiResult.notes);
+    if (openapiRecords.length === 0) {
+        notes.push("OpenAPI spec not found; canonical prefix derived from docs.");
+    }
+    if (docPaths.length === 0 && openapiPaths.length === 0) {
+        return {
+            gateId: "gate-api-path-consistency",
+            gateName: "API Path Consistency",
+            status: "skipped",
+            issues,
+            notes: notes.length > 0 ? notes : ["No API endpoints detected in docs or OpenAPI."],
+        };
+    }
+    const uniqueDocPaths = dedupeByNormalized(docPaths);
+    const uniqueOpenapiPaths = dedupeByNormalized(openapiPaths);
+    const canonicalPrefix = selectCanonicalPrefix(uniqueOpenapiPaths.length > 0 ? uniqueOpenapiPaths : uniqueDocPaths);
+    if (!canonicalPrefix) {
+        return {
+            gateId: "gate-api-path-consistency",
+            gateName: "API Path Consistency",
+            status: "skipped",
+            issues,
+            notes: notes.length > 0 ? notes : ["Unable to determine canonical API prefix."],
+        };
+    }
+    for (const entry of uniqueDocPaths) {
+        if (entry.prefix !== canonicalPrefix) {
+            issues.push(buildIssue({
+                issueType: "prefix_mismatch",
+                entry,
+                canonicalPrefix,
+                expectedPrefix: canonicalPrefix,
+                actualPrefix: entry.prefix,
+            }));
+        }
+    }
+    for (const entry of uniqueOpenapiPaths) {
+        if (entry.prefix !== canonicalPrefix) {
+            issues.push(buildIssue({
+                issueType: "prefix_mismatch",
+                entry,
+                canonicalPrefix,
+                expectedPrefix: canonicalPrefix,
+                actualPrefix: entry.prefix,
+            }));
+        }
+    }
+    if (uniqueOpenapiPaths.length > 0) {
+        const openapiSet = new Set(uniqueOpenapiPaths.map((entry) => entry.normalized));
+        for (const entry of uniqueDocPaths) {
+            if (!openapiSet.has(entry.normalized)) {
+                issues.push(buildIssue({
+                    issueType: "doc_missing_openapi",
+                    entry,
+                    canonicalPrefix,
+                }));
+            }
+        }
+    }
+    if (uniqueDocPaths.length > 0) {
+        const docSet = new Set(uniqueDocPaths.map((entry) => entry.normalized));
+        for (const entry of uniqueOpenapiPaths) {
+            if (!docSet.has(entry.normalized)) {
+                issues.push(buildIssue({
+                    issueType: "openapi_missing_docs",
+                    entry,
+                    canonicalPrefix,
+                }));
+            }
+        }
+    }
+    const status = issues.length > 0 ? "fail" : "pass";
+    return {
+        gateId: "gate-api-path-consistency",
+        gateName: "API Path Consistency",
+        status,
+        issues,
+        notes: notes.length > 0 ? notes : undefined,
+        metadata: {
+            canonicalPrefix,
+            docPathCount: uniqueDocPaths.length,
+            openapiPathCount: uniqueOpenapiPaths.length,
+        },
+    };
+};

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"BuildReadyCompletenessGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/BuildReadyCompletenessGate.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAA+B,MAAM,mBAAmB,CAAC;AAElF,MAAM,WAAW,+BAA+B;IAC9C,SAAS,EAAE,uBAAuB,CAAC;IACnC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAmMD,eAAO,MAAM,6BAA6B,GACxC,OAAO,+BAA+B,KACrC,OAAO,CAAC,gBAAgB,CAyJ1B,CAAC"}