@mcoda/core 0.1.8 → 0.1.11

package/dist/services/docs/patch/DocPatchEngine.js

@@ -0,0 +1,331 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { buildDocInventory } from "../DocInventory.js";
+const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown"]);
+const YAML_EXTENSIONS = new Set([".yaml", ".yml", ".json"]);
+const inferFormat = (filePath) => {
+    const ext = path.extname(filePath).toLowerCase();
+    if (MARKDOWN_EXTENSIONS.has(ext))
+        return "markdown";
+    if (YAML_EXTENSIONS.has(ext))
+        return "yaml";
+    return "text";
+};
+const normalizeHeading = (value) => {
+    return value
+        .toLowerCase()
+        .replace(/[`*_]/g, "")
+        .replace(/[^a-z0-9\s-]/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+};
+const parseHeadingLine = (line) => {
+    const match = line.match(/^\s{0,3}(#{1,6})\s+(.+?)\s*$/);
+    if (!match)
+        return undefined;
+    const level = match[1].length;
+    const text = match[2].replace(/\s+#*\s*$/, "").trim();
+    return { level, text };
+};
+const splitLines = (content) => {
+    const hadTrailingNewline = content.endsWith("\n");
+    const lines = content.split(/\r?\n/);
+    if (hadTrailingNewline && lines.length && lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    return { lines, hadTrailingNewline };
+};
+const joinLines = (lines, hadTrailingNewline) => {
+    const joined = lines.join("\n");
+    if (hadTrailingNewline)
+        return `${joined}\n`;
+    return joined;
+};
+const trimEmptyLines = (lines) => {
+    let start = 0;
+    let end = lines.length;
+    while (start < end && lines[start]?.trim() === "")
+        start += 1;
+    while (end > start && lines[end - 1]?.trim() === "")
+        end -= 1;
+    return lines.slice(start, end);
+};
+const normalizeLineRange = (lineStart, lineEnd, totalLines) => {
+    if (!Number.isFinite(lineStart) || !Number.isFinite(lineEnd))
+        return undefined;
+    if (lineStart < 1 || lineEnd < 1)
+        return undefined;
+    if (lineStart > lineEnd)
+        return undefined;
+    if (totalLines === 0)
+        return undefined;
+    const start = Math.max(1, Math.min(totalLines, Math.floor(lineStart)));
+    const end = Math.max(1, Math.min(totalLines, Math.floor(lineEnd)));
+    if (start > end)
+        return undefined;
+    return { start, end };
+};
+const removeRange = (lines, startIdx, endIdx) => {
+    const next = lines.slice(0, startIdx).concat(lines.slice(endIdx + 1));
+    while (startIdx > 0 && startIdx < next.length && next[startIdx] === "" && next[startIdx - 1] === "") {
+        next.splice(startIdx, 1);
+    }
+    if (next[0] === "")
+        next.shift();
+    return next;
+};
+const findHeadingIndex = (lines, heading) => {
+    const target = normalizeHeading(heading);
+    for (let i = 0; i < lines.length; i += 1) {
+        const parsed = parseHeadingLine(lines[i] ?? "");
+        if (!parsed)
+            continue;
+        if (normalizeHeading(parsed.text) === target) {
+            return { index: i, level: parsed.level };
+        }
+    }
+    return undefined;
+};
+const findSectionRange = (lines, headingIndex, headingLevel) => {
+    let end = lines.length;
+    for (let i = headingIndex + 1; i < lines.length; i += 1) {
+        const parsed = parseHeadingLine(lines[i] ?? "");
+        if (!parsed)
+            continue;
+        if (parsed.level <= headingLevel) {
+            end = i;
+            break;
+        }
+    }
+    return { start: headingIndex, end };
+};
+const withSectionSpacing = (lines, insertAt, sectionLines) => {
+    const needsLeadingBlank = insertAt > 0 && (lines[insertAt - 1]?.trim() ?? "") !== "";
+    const needsTrailingBlank = insertAt < lines.length && (lines[insertAt]?.trim() ?? "") !== "";
+    const padded = sectionLines.slice();
+    if (needsLeadingBlank)
+        padded.unshift("");
+    if (needsTrailingBlank)
+        padded.push("");
+    return padded;
+};
+const buildSectionLines = (heading, content, level) => {
+    const headingLevel = Math.min(6, Math.max(1, level ?? 2));
+    const headingLine = `${"#".repeat(headingLevel)} ${heading.trim()}`;
+    const bodyLines = trimEmptyLines(content.split(/\r?\n/));
+    const lines = [headingLine];
+    lines.push("");
+    if (bodyLines.length > 0) {
+        lines.push(...bodyLines);
+    }
+    return lines;
+};
+const resolvePreferred = (artifacts) => ({
+    pdrPath: artifacts.pdr?.path,
+    sdsPath: artifacts.sds?.path,
+});
+const applyReplaceSection = (lines, op, format, filePath) => {
+    if (op.location.path && path.resolve(op.location.path) !== path.resolve(filePath)) {
+        return { lines, step: { operation: op, applied: false, reason: "location path mismatch" } };
+    }
+    if (op.location.kind === "heading") {
+        if (format !== "markdown") {
+            return { lines, step: { operation: op, applied: false, reason: "heading replace requires markdown" } };
+        }
+        const headingMatch = findHeadingIndex(lines, op.location.heading);
+        if (!headingMatch) {
+            const appended = lines.slice();
+            const sectionLines = buildSectionLines(op.location.heading, op.content, op.headingLevel);
+            appended.push(...withSectionSpacing(appended, appended.length, sectionLines));
+            return {
+                lines: appended,
+                step: {
+                    operation: op,
+                    applied: true,
+                    reason: "heading not found; appended section",
+                    range: { lineStart: Math.max(1, appended.length - sectionLines.length + 1), lineEnd: appended.length },
+                },
+            };
+        }
+        const { start, end } = findSectionRange(lines, headingMatch.index, headingMatch.level);
+        const replacement = buildSectionLines(lines[headingMatch.index] ?? op.location.heading, op.content, headingMatch.level)
+            .map((line, idx) => (idx === 0 ? lines[headingMatch.index] ?? line : line));
+        const nextLines = lines.slice(0, start).concat(replacement, lines.slice(end));
+        return {
+            lines: nextLines,
+            step: {
+                operation: op,
+                applied: true,
+                range: { lineStart: start + 1, lineEnd: start + replacement.length },
+            },
+        };
+    }
+    const range = normalizeLineRange(op.location.lineStart, op.location.lineEnd, lines.length);
+    if (!range) {
+        return { lines, step: { operation: op, applied: false, reason: "invalid line range" } };
+    }
+    const bodyLines = trimEmptyLines(op.content.split(/\r?\n/));
+    const replacement = bodyLines.length > 0 ? bodyLines : [""];
+    const nextLines = lines
+        .slice(0, range.start - 1)
+        .concat(replacement, lines.slice(range.end));
+    return {
+        lines: nextLines,
+        step: {
+            operation: op,
+            applied: true,
+            range: { lineStart: range.start, lineEnd: range.start + replacement.length - 1 },
+        },
+    };
+};
+const applyInsertSection = (lines, op, format, filePath) => {
+    if (format !== "markdown") {
+        return { lines, step: { operation: op, applied: false, reason: "insert requires markdown" } };
+    }
+    const sectionLines = buildSectionLines(op.heading, op.content, op.headingLevel);
+    const position = op.position ?? "append";
+    let insertAt = lines.length;
+    if (position !== "append" && op.location) {
+        if (op.location.path && path.resolve(op.location.path) !== path.resolve(filePath)) {
+            return { lines, step: { operation: op, applied: false, reason: "location path mismatch" } };
+        }
+        if (op.location.kind === "heading") {
+            const headingMatch = findHeadingIndex(lines, op.location.heading);
+            if (headingMatch) {
+                if (position === "before") {
+                    insertAt = headingMatch.index;
+                }
+                else {
+                    const range = findSectionRange(lines, headingMatch.index, headingMatch.level);
+                    insertAt = range.end;
+                }
+            }
+        }
+        else {
+            const range = normalizeLineRange(op.location.lineStart, op.location.lineEnd, lines.length);
+            if (range) {
+                insertAt = position === "before" ? range.start - 1 : range.end;
+            }
+        }
+    }
+    const padded = withSectionSpacing(lines, insertAt, sectionLines);
+    const nextLines = lines.slice(0, insertAt).concat(padded, lines.slice(insertAt));
+    return {
+        lines: nextLines,
+        step: {
+            operation: op,
+            applied: true,
+            range: { lineStart: insertAt + 1, lineEnd: insertAt + padded.length },
+        },
+    };
+};
+const applyRemoveBlock = (lines, op, format, filePath) => {
+    if (op.location.path && path.resolve(op.location.path) !== path.resolve(filePath)) {
+        return { lines, step: { operation: op, applied: false, reason: "location path mismatch" } };
+    }
+    if (op.location.kind === "heading") {
+        if (format !== "markdown") {
+            return { lines, step: { operation: op, applied: false, reason: "heading remove requires markdown" } };
+        }
+        const headingMatch = findHeadingIndex(lines, op.location.heading);
+        if (!headingMatch) {
+            return { lines, step: { operation: op, applied: false, reason: "heading not found" } };
+        }
+        const range = findSectionRange(lines, headingMatch.index, headingMatch.level);
+        const nextLines = removeRange(lines, range.start, range.end - 1);
+        return {
+            lines: nextLines,
+            step: {
+                operation: op,
+                applied: true,
+                range: { lineStart: range.start + 1, lineEnd: range.end },
+            },
+        };
+    }
+    const range = normalizeLineRange(op.location.lineStart, op.location.lineEnd, lines.length);
+    if (!range) {
+        return { lines, step: { operation: op, applied: false, reason: "invalid line range" } };
+    }
+    const nextLines = removeRange(lines, range.start - 1, range.end - 1);
+    return {
+        lines: nextLines,
+        step: {
+            operation: op,
+            applied: true,
+            range: { lineStart: range.start, lineEnd: range.end },
+        },
+    };
+};
+export class DocPatchEngine {
+    async apply(input) {
+        const { runContext, patches, dryRun } = input;
+        const results = [];
+        const warnings = [];
+        let changedAny = false;
+        for (const patch of patches) {
+            const format = patch.format ?? inferFormat(patch.path);
+            let content = "";
+            let steps = [];
+            let hadTrailingNewline = false;
+            let lines = [];
+            try {
+                content = await fs.readFile(patch.path, "utf8");
+                const split = splitLines(content);
+                lines = split.lines;
+                hadTrailingNewline = split.hadTrailingNewline;
+            }
+            catch (error) {
+                const message = `Doc patch skipped for ${patch.path}: ${error.message ?? String(error)}`;
+                warnings.push(message);
+                steps = patch.operations.map((operation) => ({
+                    operation,
+                    applied: false,
+                    reason: "failed to read file",
+                }));
+                results.push({ path: patch.path, format, changed: false, steps });
+                continue;
+            }
+            for (const operation of patch.operations) {
+                let outcome;
+                if (operation.type === "replace_section") {
+                    outcome = applyReplaceSection(lines, operation, format, patch.path);
+                }
+                else if (operation.type === "insert_section") {
+                    outcome = applyInsertSection(lines, operation, format, patch.path);
+                }
+                else if (operation.type === "remove_block") {
+                    outcome = applyRemoveBlock(lines, operation, format, patch.path);
+                }
+                if (!outcome)
+                    continue;
+                steps.push(outcome.step);
+                if (outcome.step.applied) {
+                    lines = outcome.lines;
+                }
+            }
+            const nextContent = joinLines(lines, hadTrailingNewline);
+            const changed = nextContent !== content;
+            changedAny = changedAny || changed;
+            if (!dryRun && changed) {
+                await fs.writeFile(patch.path, nextContent, "utf8");
+            }
+            results.push({ path: patch.path, format, changed, steps });
+        }
+        if (!dryRun && changedAny) {
+            try {
+                const updatedArtifacts = await buildDocInventory({
+                    workspace: runContext.workspace,
+                    preferred: resolvePreferred(runContext.artifacts),
+                });
+                runContext.artifacts = updatedArtifacts;
+            }
+            catch (error) {
+                warnings.push(`Doc inventory refresh failed: ${error.message ?? String(error)}`);
+            }
+        }
+        if (warnings.length > 0) {
+            runContext.warnings.push(...warnings);
+        }
+        return { results, updatedArtifacts: runContext.artifacts, warnings };
+    }
+}

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

@@ -0,0 +1,16 @@
+export interface GlossaryEntry {
+    key: string;
+    term: string;
+    description: string;
+    aliases?: string[];
+}
+export interface GlossaryData {
+    version: 1;
+    entries: GlossaryEntry[];
+    canonicalPhrases: Record<string, string>;
+}
+export declare const loadGlossary: (overridePath?: string) => GlossaryData;
+export declare const getGlossaryEntry: (key: string, glossary?: GlossaryData) => GlossaryEntry | undefined;
+export declare const formatGlossaryForPrompt: (glossary?: GlossaryData) => string;
+export declare const GLOSSARY_PROMPT_SNIPPET: string;
+//# sourceMappingURL=Glossary.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Glossary.d.ts","sourceRoot":"","sources":["../../../../src/services/docs/review/Glossary.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAkBD,eAAO,MAAM,YAAY,GAAI,eAAe,MAAM,KAAG,YAYpD,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,EAAE,WAAW,YAAY,KAAG,aAAa,GAAG,SAGvF,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAI,WAAW,YAAY,KAAG,MASjE,CAAC;AAEF,eAAO,MAAM,uBAAuB,QAA4B,CAAC"}

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

@@ -0,0 +1,47 @@
+import glossaryFallback from "./glossary.json" with { type: "json" };
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+const DEFAULT_GLOSSARY_PATH = fileURLToPath(new URL("./glossary.json", import.meta.url));
+let cachedGlossary = null;
+let cachedPath = null;
+const normalizeGlossary = (data) => {
+    const version = data?.version === 1 ? 1 : 1;
+    const entries = Array.isArray(data?.entries)
+        ? data.entries.filter((entry) => entry && typeof entry.term === "string")
+        : [];
+    const canonicalPhrases = data?.canonicalPhrases && typeof data.canonicalPhrases === "object"
+        ? data.canonicalPhrases
+        : {};
+    return { version, entries, canonicalPhrases };
+};
+export const loadGlossary = (overridePath) => {
+    const glossaryPath = overridePath || process.env.MCODA_GLOSSARY_PATH || DEFAULT_GLOSSARY_PATH;
+    if (cachedGlossary && cachedPath === glossaryPath)
+        return cachedGlossary;
+    try {
+        const raw = fs.readFileSync(glossaryPath, "utf8");
+        cachedGlossary = normalizeGlossary(JSON.parse(raw));
+        cachedPath = glossaryPath;
+    }
+    catch {
+        cachedGlossary = normalizeGlossary(glossaryFallback);
+        cachedPath = DEFAULT_GLOSSARY_PATH;
+    }
+    return cachedGlossary;
+};
+export const getGlossaryEntry = (key, glossary) => {
+    const resolved = glossary ?? loadGlossary();
+    return resolved.entries.find((entry) => entry.key === key);
+};
+export const formatGlossaryForPrompt = (glossary) => {
+    const resolved = glossary ?? loadGlossary();
+    if (!resolved.entries.length)
+        return "Glossary: (no entries loaded).";
+    const lines = ["Glossary (canonical terminology):"];
+    for (const entry of resolved.entries) {
+        const alias = entry.aliases && entry.aliases.length > 0 ? ` Aliases: ${entry.aliases.join(", ")}.` : "";
+        lines.push(`- ${entry.term}: ${entry.description}.${alias}`.trim());
+    }
+    return lines.join("\n");
+};
+export const GLOSSARY_PROMPT_SNIPPET = formatGlossaryForPrompt();

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

@@ -0,0 +1,3 @@
+import { type ReviewReport } from "./ReviewReportSchema.js";
+export declare const renderReviewReport: (input: ReviewReport) => string;
+//# sourceMappingURL=ReviewReportRenderer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReviewReportRenderer.d.ts","sourceRoot":"","sources":["../../../../src/services/docs/review/ReviewReportRenderer.ts"],"names":[],"mappings":"AACA,OAAO,EAAyB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AA+BnF,eAAO,MAAM,kBAAkB,GAAI,OAAO,YAAY,KAAG,MA+GxD,CAAC"}

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

@@ -0,0 +1,133 @@
+import { normalizeReviewReport } from "./ReviewReportSchema.js";
+import { sortIssues } from "./ReviewTypes.js";
+const ARTIFACT_ORDER = ["pdr", "sds", "openapi", "sql", "deployment"];
+const statusLabel = (status) => status.toUpperCase();
+const formatLocation = (issue) => {
+    const location = issue.location;
+    if (location.kind === "heading") {
+        return location.heading ? `Heading: ${location.heading}` : "Heading: (unspecified)";
+    }
+    return `Lines ${location.lineStart}-${location.lineEnd}`;
+};
+const formatIssueLine = (issue) => {
+    const location = formatLocation(issue);
+    return `- (${issue.severity}) [${issue.gateId}] ${issue.message} (${location}) -> ${issue.remediation}`;
+};
+const sortArtifacts = (artifacts) => {
+    return artifacts.slice().sort((a, b) => {
+        const ai = ARTIFACT_ORDER.indexOf(a);
+        const bi = ARTIFACT_ORDER.indexOf(b);
+        if (ai === -1 && bi === -1)
+            return a.localeCompare(b);
+        if (ai === -1)
+            return 1;
+        if (bi === -1)
+            return -1;
+        return ai - bi;
+    });
+};
+export const renderReviewReport = (input) => {
+    const report = normalizeReviewReport(input);
+    const lines = [];
+    lines.push("# Docgen Review Report");
+    lines.push("");
+    lines.push(`- Generated: ${report.generatedAt}`);
+    lines.push(`- Iteration: ${report.iteration.current}/${report.iteration.max} (${report.iteration.status})`);
+    lines.push(`- Status: ${statusLabel(report.status)}`);
+    lines.push(`- Total issues: ${report.summary.issueCount}`);
+    lines.push("");
+    lines.push("## Summary");
+    lines.push(`- Status: ${statusLabel(report.summary.status)}`);
+    lines.push(`- Issues: ${report.summary.issueCount} (blocker: ${report.summary.severityCounts.blocker}, high: ${report.summary.severityCounts.high}, medium: ${report.summary.severityCounts.medium}, low: ${report.summary.severityCounts.low}, info: ${report.summary.severityCounts.info})`);
+    lines.push(`- Gates: fail: ${report.summary.gateCounts.fail}, warn: ${report.summary.gateCounts.warn}, pass: ${report.summary.gateCounts.pass}, skipped: ${report.summary.gateCounts.skipped}`);
+    lines.push("");
+    if (report.metadata?.iterationReports?.length) {
+        lines.push("## Prior Iterations");
+        for (const entry of report.metadata.iterationReports) {
+            lines.push(`- ${entry}`);
+        }
+        lines.push("");
+    }
+    lines.push("## Gate Summary");
+    if (report.gateResults.length === 0) {
+        lines.push("- None");
+    }
+    else {
+        const sortedGates = report.gateResults.slice().sort((a, b) => a.gateId.localeCompare(b.gateId));
+        for (const gate of sortedGates) {
+            lines.push(`- ${statusLabel(gate.status)} ${gate.gateId} (${gate.issues.length} issues)`);
+        }
+    }
+    lines.push("");
+    lines.push("## Issues by Artifact");
+    if (report.issues.length === 0) {
+        lines.push("- None");
+    }
+    else {
+        const grouped = new Map();
+        for (const issue of sortIssues(report.issues)) {
+            const current = grouped.get(issue.artifact) ?? [];
+            current.push(issue);
+            grouped.set(issue.artifact, current);
+        }
+        const artifacts = sortArtifacts(Array.from(grouped.keys()));
+        for (const artifact of artifacts) {
+            lines.push(`### ${artifact}`);
+            for (const issue of grouped.get(artifact) ?? []) {
+                lines.push(formatIssueLine(issue));
+            }
+            lines.push("");
+        }
+    }
+    lines.push("## Fixes Applied");
+    if (report.fixesApplied.length === 0) {
+        lines.push("- None");
+    }
+    else {
+        const fixes = report.fixesApplied.slice().sort((a, b) => a.issueId.localeCompare(b.issueId));
+        for (const fix of fixes) {
+            lines.push(`- ${fix.issueId}: ${fix.summary}`);
+        }
+    }
+    lines.push("");
+    lines.push("## Remaining Open Items");
+    if (report.remainingOpenItems.length === 0) {
+        lines.push("- None");
+    }
+    else {
+        for (const issue of sortIssues(report.remainingOpenItems)) {
+            lines.push(formatIssueLine(issue));
+        }
+    }
+    lines.push("");
+    lines.push("## Decisions");
+    if (report.decisions.length === 0) {
+        lines.push("- None");
+    }
+    else {
+        const decisions = report.decisions.slice().sort((a, b) => a.decidedAt.localeCompare(b.decidedAt));
+        for (const decision of decisions) {
+            const related = decision.relatedIssueIds?.length
+                ? ` (issues: ${decision.relatedIssueIds.join(", ")})`
+                : "";
+            lines.push(`- ${decision.summary}: ${decision.rationale}${related}`);
+        }
+    }
+    lines.push("");
+    lines.push("## Cross-Document Deltas");
+    if (report.deltas.length === 0) {
+        lines.push("- None");
+    }
+    else {
+        const deltas = report.deltas.slice().sort((a, b) => {
+            const artifactDiff = sortArtifacts([a.artifact, b.artifact])[0] === a.artifact ? -1 : 1;
+            if (a.artifact === b.artifact)
+                return a.path.localeCompare(b.path);
+            return artifactDiff;
+        });
+        for (const delta of deltas) {
+            lines.push(`- ${delta.artifact}: ${delta.path} -> ${delta.summary}`);
+        }
+    }
+    return lines.join("\n");
+};

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

@@ -0,0 +1,39 @@
+import { type ReviewDecision, type ReviewFix, type ReviewGateResult, type ReviewIssue, type ReviewOutcomeStatus, type ReviewSummary } from "./ReviewTypes.js";
+import { DocArtifactKind } from "../DocgenRunContext.js";
+export interface ReviewReportIteration {
+    current: number;
+    max: number;
+    status: "in_progress" | "completed" | "max_iterations";
+}
+export interface ReviewReportDelta {
+    artifact: DocArtifactKind;
+    path: string;
+    summary: string;
+    beforeChecksum?: string;
+    afterChecksum?: string;
+}
+export interface ReviewReportV1 {
+    version: 1;
+    generatedAt: string;
+    iteration: ReviewReportIteration;
+    status: ReviewOutcomeStatus;
+    summary: ReviewSummary;
+    gateResults: ReviewGateResult[];
+    issues: ReviewIssue[];
+    remainingOpenItems: ReviewIssue[];
+    fixesApplied: ReviewFix[];
+    decisions: ReviewDecision[];
+    deltas: ReviewReportDelta[];
+    metadata?: {
+        commandName?: string;
+        commandRunId?: string;
+        jobId?: string;
+        projectKey?: string;
+        iterationReports?: string[];
+    };
+}
+export type ReviewReport = ReviewReportV1;
+export declare const normalizeReviewReport: (report: ReviewReport) => ReviewReportV1;
+export declare const validateReviewReport: (report: ReviewReport) => ReviewReportV1;
+export declare const serializeReviewReport: (report: ReviewReport) => string;
+//# sourceMappingURL=ReviewReportSchema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReviewReportSchema.d.ts","sourceRoot":"","sources":["../../../../src/services/docs/review/ReviewReportSchema.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAEnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,aAAa,GAAG,WAAW,GAAG,gBAAgB,CAAC;CACxD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,eAAe,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,CAAC,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,qBAAqB,CAAC;IACjC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,OAAO,EAAE,aAAa,CAAC;IACvB,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,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE;QACT,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;KAC7B,CAAC;CACH;AAED,MAAM,MAAM,YAAY,GAAG,cAAc,CAAC;AAoB1C,eAAO,MAAM,qBAAqB,GAAI,QAAQ,YAAY,KAAG,cAa5D,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,QAAQ,YAAY,KAAG,cAY3D,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,QAAQ,YAAY,KAAG,MAG5D,CAAC"}

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

@@ -0,0 +1,47 @@
+import { summarizeGateResults, } from "./ReviewTypes.js";
+const ensureString = (value, label) => {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`Review report validation failed: ${label} must be a non-empty string.`);
+    }
+};
+const ensureNumber = (value, label) => {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+        throw new Error(`Review report validation failed: ${label} must be a number.`);
+    }
+};
+const ensureArray = (value, label) => {
+    if (!Array.isArray(value)) {
+        throw new Error(`Review report validation failed: ${label} must be an array.`);
+    }
+};
+export const normalizeReviewReport = (report) => {
+    if (report.version !== 1) {
+        throw new Error(`Unsupported review report version: ${report.version}`);
+    }
+    return {
+        ...report,
+        issues: report.issues ?? [],
+        remainingOpenItems: report.remainingOpenItems ?? [],
+        fixesApplied: report.fixesApplied ?? [],
+        decisions: report.decisions ?? [],
+        deltas: report.deltas ?? [],
+        summary: report.summary ?? summarizeGateResults(report.gateResults ?? []),
+    };
+};
+export const validateReviewReport = (report) => {
+    const normalized = normalizeReviewReport(report);
+    ensureString(normalized.generatedAt, "generatedAt");
+    ensureNumber(normalized.iteration?.current, "iteration.current");
+    ensureNumber(normalized.iteration?.max, "iteration.max");
+    ensureArray(normalized.gateResults, "gateResults");
+    ensureArray(normalized.issues, "issues");
+    ensureArray(normalized.remainingOpenItems, "remainingOpenItems");
+    ensureArray(normalized.fixesApplied, "fixesApplied");
+    ensureArray(normalized.decisions, "decisions");
+    ensureArray(normalized.deltas, "deltas");
+    return normalized;
+};
+export const serializeReviewReport = (report) => {
+    const validated = validateReviewReport(report);
+    return JSON.stringify(validated, null, 2);
+};