@mcoda/core 0.1.9 → 0.1.12

package/dist/services/docs/alignment/DocAlignmentGraph.d.ts

@@ -0,0 +1,23 @@
+import { DocArtifactKind, DocArtifactVariant } from "../DocgenRunContext.js";
+export type DocAlignmentArtifactKind = DocArtifactKind | "rfp" | "telemetry";
+export interface DocAlignmentNode {
+    artifact: DocAlignmentArtifactKind;
+    section: string;
+    variant?: DocArtifactVariant;
+}
+export interface DocAlignmentRule {
+    id: string;
+    description: string;
+    sources: DocAlignmentNode[];
+    targets: DocAlignmentNode[];
+    tags?: string[];
+}
+export declare class DocAlignmentGraph {
+    private rules;
+    constructor(rules: DocAlignmentRule[]);
+    static createDefault(): DocAlignmentGraph;
+    listRules(): DocAlignmentRule[];
+    getRule(ruleId: string): DocAlignmentRule | undefined;
+    getImpactedSections(ruleId: string): DocAlignmentNode[];
+}
+//# sourceMappingURL=DocAlignmentGraph.d.ts.map

package/dist/services/docs/alignment/DocAlignmentGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocAlignmentGraph.d.ts","sourceRoot":"","sources":["../../../../src/services/docs/alignment/DocAlignmentGraph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAE7E,MAAM,MAAM,wBAAwB,GAAG,eAAe,GAAG,KAAK,GAAG,WAAW,CAAC;AAE7E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,wBAAwB,CAAC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAyDD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,KAAK,CAAgC;gBAEjC,KAAK,EAAE,gBAAgB,EAAE;IAIrC,MAAM,CAAC,aAAa,IAAI,iBAAiB;IAIzC,SAAS,IAAI,gBAAgB,EAAE;IAI/B,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAIrD,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE;CASxD"}

package/dist/services/docs/alignment/DocAlignmentGraph.js

@@ -0,0 +1,78 @@
+const DEFAULT_RULES = [
+    {
+        id: "consent-model",
+        description: "Consent and minimization policies propagate across docs.",
+        sources: [{ artifact: "rfp", section: "Consent & Minimization" }],
+        targets: [
+            { artifact: "pdr", section: "Ownership & Consent Flow" },
+            { artifact: "sds", section: "Policy & Telemetry" },
+            { artifact: "openapi", variant: "primary", section: "Security Schemes" },
+            { artifact: "openapi", variant: "admin", section: "Security Schemes" },
+            { artifact: "telemetry", section: "Consent Metadata" },
+        ],
+    },
+    {
+        id: "api-prefix",
+        description: "Canonical API prefixes should align across docs and specs.",
+        sources: [
+            { artifact: "pdr", section: "Interfaces / APIs" },
+            { artifact: "sds", section: "Interface Contracts" },
+        ],
+        targets: [
+            { artifact: "pdr", section: "Interfaces / APIs" },
+            { artifact: "sds", section: "Interface Contracts" },
+            { artifact: "openapi", variant: "primary", section: "Paths" },
+            { artifact: "openapi", variant: "admin", section: "Paths" },
+        ],
+    },
+    {
+        id: "terminology",
+        description: "Canonical terminology and naming conventions stay aligned.",
+        sources: [{ artifact: "rfp", section: "Definitions" }],
+        targets: [
+            { artifact: "pdr", section: "Terminology" },
+            { artifact: "sds", section: "Terminology" },
+            { artifact: "sql", section: "Schema" },
+            { artifact: "openapi", variant: "primary", section: "Schemas" },
+            { artifact: "openapi", variant: "admin", section: "Schemas" },
+        ],
+    },
+];
+const nodeKey = (node) => {
+    return `${node.artifact}:${node.variant ?? ""}:${node.section}`;
+};
+const sortNodes = (nodes) => {
+    return nodes.slice().sort((a, b) => {
+        const artifactDiff = a.artifact.localeCompare(b.artifact);
+        if (artifactDiff !== 0)
+            return artifactDiff;
+        const variantDiff = (a.variant ?? "").localeCompare(b.variant ?? "");
+        if (variantDiff !== 0)
+            return variantDiff;
+        return a.section.localeCompare(b.section);
+    });
+};
+export class DocAlignmentGraph {
+    constructor(rules) {
+        this.rules = new Map(rules.map((rule) => [rule.id, rule]));
+    }
+    static createDefault() {
+        return new DocAlignmentGraph(DEFAULT_RULES);
+    }
+    listRules() {
+        return Array.from(this.rules.values());
+    }
+    getRule(ruleId) {
+        return this.rules.get(ruleId);
+    }
+    getImpactedSections(ruleId) {
+        const rule = this.rules.get(ruleId);
+        if (!rule)
+            return [];
+        const deduped = new Map();
+        for (const node of rule.targets) {
+            deduped.set(nodeKey(node), node);
+        }
+        return sortNodes(Array.from(deduped.values()));
+    }
+}

package/dist/services/docs/alignment/DocAlignmentPatcher.d.ts

@@ -0,0 +1,19 @@
+import { DocAlignmentGraph } from "./DocAlignmentGraph.js";
+import type { DocgenRunContext } from "../DocgenRunContext.js";
+import type { ReviewGateResult } from "../review/ReviewTypes.js";
+import type { ReviewReportDelta } from "../review/ReviewReportSchema.js";
+export interface DocAlignmentPatchInput {
+    runContext: DocgenRunContext;
+    gateResults: ReviewGateResult[];
+    dryRun?: boolean;
+}
+export interface DocAlignmentPatchResult {
+    deltas: ReviewReportDelta[];
+    warnings: string[];
+}
+export declare class DocAlignmentPatcher {
+    private graph;
+    constructor(graph?: DocAlignmentGraph);
+    apply(input: DocAlignmentPatchInput): Promise<DocAlignmentPatchResult>;
+}
+//# sourceMappingURL=DocAlignmentPatcher.d.ts.map

package/dist/services/docs/alignment/DocAlignmentPatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocAlignmentPatcher.d.ts","sourceRoot":"","sources":["../../../../src/services/docs/alignment/DocAlignmentPatcher.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAsC,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACnG,OAAO,KAAK,EAAE,gBAAgB,EAAe,MAAM,0BAA0B,CAAC;AAC9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAGzE,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAqGD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,KAAK,CAAoB;gBAErB,KAAK,CAAC,EAAE,iBAAiB;IAI/B,KAAK,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC;CAiJ7E"}

package/dist/services/docs/alignment/DocAlignmentPatcher.js

@@ -0,0 +1,222 @@
+import crypto from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { DocAlignmentGraph } from "./DocAlignmentGraph.js";
+import { DocPatchEngine } from "../patch/DocPatchEngine.js";
+const API_PREFIX_GATE = "gate-api-path-consistency";
+const TERMINOLOGY_GATE = "gate-terminology-normalization";
+const hashContent = (content) => crypto.createHash("sha256").update(content).digest("hex");
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const isLineRange = (issue) => issue.location.kind === "line_range";
+const findArtifactRecord = (runContext, filePath) => {
+    const normalized = path.resolve(filePath);
+    const { artifacts } = runContext;
+    if (artifacts.pdr && path.resolve(artifacts.pdr.path) === normalized)
+        return artifacts.pdr;
+    if (artifacts.sds && path.resolve(artifacts.sds.path) === normalized)
+        return artifacts.sds;
+    if (artifacts.sql && path.resolve(artifacts.sql.path) === normalized)
+        return artifacts.sql;
+    for (const record of artifacts.openapi) {
+        if (path.resolve(record.path) === normalized)
+            return record;
+    }
+    for (const record of artifacts.blueprints) {
+        if (path.resolve(record.path) === normalized)
+            return record;
+    }
+    return undefined;
+};
+const collectIssues = (gateResults, gateId) => gateResults.flatMap((result) => (result.gateId === gateId ? result.issues : []));
+const metadataString = (value) => typeof value === "string" && value.trim().length > 0 ? value : undefined;
+const buildApiPrefixReplacement = (issue, line) => {
+    const metadata = (issue.metadata ?? {});
+    const issueType = metadataString(metadata.issueType);
+    if (issueType !== "prefix_mismatch")
+        return undefined;
+    const expectedPrefix = metadataString(metadata.expectedPrefix) ?? metadataString(metadata.canonicalPrefix);
+    const actualPrefix = metadataString(metadata.actualPrefix);
+    if (!expectedPrefix || !actualPrefix)
+        return undefined;
+    if (!line.includes(actualPrefix))
+        return undefined;
+    const excerpt = isLineRange(issue) ? metadataString(issue.location.excerpt) : undefined;
+    let nextLine = line;
+    if (excerpt && line.includes(excerpt)) {
+        const updated = excerpt.replace(actualPrefix, expectedPrefix);
+        if (updated !== excerpt) {
+            nextLine = line.replace(excerpt, updated);
+        }
+    }
+    else {
+        nextLine = line.replace(actualPrefix, expectedPrefix);
+    }
+    if (nextLine === line)
+        return undefined;
+    return {
+        nextLine,
+        summary: `Aligned API prefix to ${expectedPrefix}`,
+    };
+};
+const buildTerminologyReplacement = (issue, line) => {
+    const metadata = (issue.metadata ?? {});
+    const alias = metadataString(metadata.alias);
+    const canonicalTerm = metadataString(metadata.canonicalTerm);
+    if (!alias || !canonicalTerm)
+        return undefined;
+    const pattern = new RegExp(`\\b${escapeRegExp(alias)}\\b`, "i");
+    if (!pattern.test(line))
+        return undefined;
+    const nextLine = line.replace(pattern, canonicalTerm);
+    if (nextLine === line)
+        return undefined;
+    return {
+        nextLine,
+        summary: `Replaced \"${alias}\" with \"${canonicalTerm}\"`,
+    };
+};
+const isRuleTarget = (graph, ruleId, record) => {
+    if (!record)
+        return false;
+    const nodes = graph.getImpactedSections(ruleId);
+    return nodes.some((node) => node.artifact === record.kind &&
+        (node.variant ? node.variant === record.variant : true));
+};
+export class DocAlignmentPatcher {
+    constructor(graph) {
+        this.graph = graph ?? DocAlignmentGraph.createDefault();
+    }
+    async apply(input) {
+        const warnings = [];
+        const summariesByPath = new Map();
+        const issuesByPath = new Map();
+        const apiIssues = collectIssues(input.gateResults, API_PREFIX_GATE);
+        const terminologyIssues = collectIssues(input.gateResults, TERMINOLOGY_GATE);
+        const queueIssue = (issue, ruleId) => {
+            if (!isLineRange(issue))
+                return;
+            const record = findArtifactRecord(input.runContext, issue.location.path);
+            if (!isRuleTarget(this.graph, ruleId, record))
+                return;
+            const existing = issuesByPath.get(issue.location.path);
+            if (existing) {
+                existing.push(issue);
+            }
+            else {
+                issuesByPath.set(issue.location.path, [issue]);
+            }
+        };
+        for (const issue of apiIssues) {
+            queueIssue(issue, "api-prefix");
+        }
+        for (const issue of terminologyIssues) {
+            queueIssue(issue, "terminology");
+        }
+        if (issuesByPath.size === 0) {
+            return { deltas: [], warnings: [] };
+        }
+        const patches = [];
+        const beforeChecksums = new Map();
+        for (const [filePath, issues] of issuesByPath.entries()) {
+            let content = "";
+            try {
+                content = await fs.readFile(filePath, "utf8");
+            }
+            catch (error) {
+                warnings.push(`Alignment patch skipped for ${filePath}: ${error.message ?? String(error)}`);
+                continue;
+            }
+            beforeChecksums.set(filePath, hashContent(content));
+            const lines = content.split(/\r?\n/);
+            const operations = [];
+            const lineReplacements = new Map();
+            for (const issue of issues) {
+                if (!isLineRange(issue))
+                    continue;
+                const lineIndex = issue.location.lineStart - 1;
+                if (lineIndex < 0 || lineIndex >= lines.length)
+                    continue;
+                const lineState = lineReplacements.get(lineIndex);
+                const line = lineState?.line ?? lines[lineIndex] ?? "";
+                let replacement;
+                if (issue.gateId === API_PREFIX_GATE) {
+                    replacement = buildApiPrefixReplacement(issue, line);
+                }
+                else if (issue.gateId === TERMINOLOGY_GATE) {
+                    replacement = buildTerminologyReplacement(issue, line);
+                }
+                if (!replacement)
+                    continue;
+                if (!summariesByPath.has(filePath)) {
+                    summariesByPath.set(filePath, new Set());
+                }
+                summariesByPath.get(filePath)?.add(replacement.summary);
+                const nextSummaries = lineState?.summaries ?? new Set();
+                nextSummaries.add(replacement.summary);
+                lineReplacements.set(lineIndex, { line: replacement.nextLine, summaries: nextSummaries });
+            }
+            const sortedLineEntries = Array.from(lineReplacements.entries()).sort((a, b) => a[0] - b[0]);
+            for (const [lineIndex, lineState] of sortedLineEntries) {
+                const lineNumber = lineIndex + 1;
+                operations.push({
+                    type: "replace_section",
+                    location: {
+                        kind: "line_range",
+                        path: filePath,
+                        lineStart: lineNumber,
+                        lineEnd: lineNumber,
+                    },
+                    content: lineState.line,
+                });
+            }
+            if (operations.length > 0) {
+                patches.push({ path: filePath, operations });
+            }
+        }
+        if (patches.length === 0) {
+            return { deltas: [], warnings };
+        }
+        const engine = new DocPatchEngine();
+        const applyResult = await engine.apply({
+            runContext: input.runContext,
+            patches,
+            dryRun: input.dryRun ?? input.runContext.flags.dryRun,
+        });
+        const deltas = [];
+        for (const result of applyResult.results) {
+            if (!result.changed)
+                continue;
+            let afterContent = "";
+            try {
+                afterContent = await fs.readFile(result.path, "utf8");
+            }
+            catch (error) {
+                warnings.push(`Alignment patch wrote ${result.path} but could not read it: ${error.message ?? String(error)}`);
+                continue;
+            }
+            const beforeChecksum = beforeChecksums.get(result.path);
+            const afterChecksum = hashContent(afterContent);
+            const record = findArtifactRecord(input.runContext, result.path);
+            if (!record) {
+                warnings.push(`Alignment patch applied to ${result.path} but no artifact record was found.`);
+                continue;
+            }
+            const summarySet = summariesByPath.get(result.path);
+            const summary = summarySet && summarySet.size > 0
+                ? Array.from(summarySet.values()).join("; ")
+                : "Alignment patch applied.";
+            deltas.push({
+                artifact: record.kind,
+                path: result.path,
+                summary,
+                beforeChecksum,
+                afterChecksum,
+            });
+        }
+        const combinedWarnings = warnings.slice();
+        if (applyResult.warnings?.length) {
+            combinedWarnings.push(...applyResult.warnings);
+        }
+        return { deltas, warnings: combinedWarnings };
+    }
+}

package/dist/services/docs/patch/DocPatchEngine.d.ts

@@ -0,0 +1,57 @@
+import type { DocgenArtifactInventory, DocgenRunContext } from "../DocgenRunContext.js";
+import type { ReviewIssueLocation } from "../review/ReviewTypes.js";
+export type DocPatchFormat = "markdown" | "yaml" | "text";
+export type DocPatchPosition = "after" | "before" | "append";
+export type ReplaceSectionOperation = {
+    type: "replace_section";
+    location: ReviewIssueLocation;
+    content: string;
+    headingLevel?: number;
+};
+export type InsertSectionOperation = {
+    type: "insert_section";
+    heading: string;
+    content: string;
+    location?: ReviewIssueLocation;
+    position?: DocPatchPosition;
+    headingLevel?: number;
+};
+export type RemoveBlockOperation = {
+    type: "remove_block";
+    location: ReviewIssueLocation;
+};
+export type DocPatchOperation = ReplaceSectionOperation | InsertSectionOperation | RemoveBlockOperation;
+export interface DocPatchRequest {
+    path: string;
+    format?: DocPatchFormat;
+    operations: DocPatchOperation[];
+}
+export interface DocPatchPlanStep {
+    operation: DocPatchOperation;
+    applied: boolean;
+    reason?: string;
+    range?: {
+        lineStart: number;
+        lineEnd: number;
+    };
+}
+export interface DocPatchResult {
+    path: string;
+    format: DocPatchFormat;
+    changed: boolean;
+    steps: DocPatchPlanStep[];
+}
+export interface DocPatchApplyInput {
+    runContext: DocgenRunContext;
+    patches: DocPatchRequest[];
+    dryRun?: boolean;
+}
+export interface DocPatchApplyResult {
+    results: DocPatchResult[];
+    updatedArtifacts?: DocgenArtifactInventory;
+    warnings: string[];
+}
+export declare class DocPatchEngine {
+    apply(input: DocPatchApplyInput): Promise<DocPatchApplyResult>;
+}
+//# sourceMappingURL=DocPatchEngine.d.ts.map

package/dist/services/docs/patch/DocPatchEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocPatchEngine.d.ts","sourceRoot":"","sources":["../../../../src/services/docs/patch/DocPatchEngine.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAC1D,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE7D,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,iBAAiB,CAAC;IACxB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,mBAAmB,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GACzB,uBAAuB,GACvB,sBAAsB,GACtB,oBAAoB,CAAC;AAEzB,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,UAAU,EAAE,iBAAiB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,iBAAiB,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAChD;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;IAC3C,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA8RD,qBAAa,cAAc;IACnB,KAAK,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;CA2ErE"}