@shahmarasy/prodo 0.1.4 → 0.1.6

package/dist/core/terminology.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTermMap = buildTermMap;
+exports.checkTermReconciliation = checkTermReconciliation;
+const markdown_1 = require("./markdown");
+function normalizeTerm(term) {
+    return term
+        .toLowerCase()
+        .replace(/[^a-z0-9\u00c0-\u024f\s]/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function extractBoldTerms(body) {
+    const matches = body.match(/\*\*([^*]+)\*\*/g) ?? [];
+    return matches
+        .map((m) => m.replace(/\*\*/g, "").trim())
+        .filter((t) => t.length > 2 && t.length < 60);
+}
+function buildTermMap(normalizedBrief, loadedArtifacts) {
+    const termMap = new Map();
+    function addTerm(term, source, definition) {
+        const normalized = normalizeTerm(term);
+        if (!normalized || normalized.length < 2)
+            return;
+        const existing = termMap.get(normalized);
+        if (existing) {
+            existing.sources.push(source);
+            if (definition && !existing.definition) {
+                existing.definition = definition;
+            }
+        }
+        else {
+            termMap.set(normalized, {
+                term,
+                normalizedTerm: normalized,
+                definition,
+                sources: [source]
+            });
+        }
+    }
+    addTerm(normalizedBrief.product_name, { artifactType: "brief", file: "brief.md" });
+    for (const goal of normalizedBrief.goals) {
+        addTerm(goal, { artifactType: "brief", file: "brief.md" }, goal);
+    }
+    for (const feature of normalizedBrief.core_features) {
+        addTerm(feature, { artifactType: "brief", file: "brief.md" }, feature);
+    }
+    for (const constraint of normalizedBrief.constraints) {
+        addTerm(constraint, { artifactType: "brief", file: "brief.md" }, constraint);
+    }
+    for (const contract of normalizedBrief.contracts.goals) {
+        addTerm(contract.text, { artifactType: "brief", file: "brief.md" }, contract.text);
+    }
+    for (const contract of normalizedBrief.contracts.core_features) {
+        addTerm(contract.text, { artifactType: "brief", file: "brief.md" }, contract.text);
+    }
+    for (const contract of normalizedBrief.contracts.constraints) {
+        addTerm(contract.text, { artifactType: "brief", file: "brief.md" }, contract.text);
+    }
+    for (const artifact of loadedArtifacts) {
+        const sections = (0, markdown_1.parseMarkdownSections)(artifact.doc.body);
+        for (const section of sections) {
+            if (section.level === 2) {
+                addTerm(section.heading, {
+                    artifactType: artifact.type,
+                    file: artifact.file,
+                    heading: section.heading
+                });
+            }
+        }
+        const boldTerms = extractBoldTerms(artifact.doc.body);
+        for (const boldTerm of boldTerms) {
+            addTerm(boldTerm, { artifactType: artifact.type, file: artifact.file });
+        }
+    }
+    return termMap;
+}
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] = a[i - 1] === b[j - 1]
+                ? dp[i - 1][j - 1]
+                : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        }
+    }
+    return dp[m][n];
+}
+function sharesStem(a, b) {
+    const wordsA = a.split(/\s+/).filter((w) => w.length > 3);
+    const wordsB = b.split(/\s+/).filter((w) => w.length > 3);
+    for (const wa of wordsA) {
+        for (const wb of wordsB) {
+            const shorter = Math.min(wa.length, wb.length);
+            const prefix = Math.min(4, shorter);
+            if (wa.slice(0, prefix) === wb.slice(0, prefix) && wa !== wb) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function checkTermReconciliation(termMap) {
+    const issues = [];
+    const entries = Array.from(termMap.values()).filter((e) => e.sources.length > 0 && e.normalizedTerm.length > 3);
+    for (let i = 0; i < entries.length; i++) {
+        for (let j = i + 1; j < entries.length; j++) {
+            const a = entries[i];
+            const b = entries[j];
+            if (a.normalizedTerm === b.normalizedTerm)
+                continue;
+            const dist = levenshtein(a.normalizedTerm, b.normalizedTerm);
+            const maxLen = Math.max(a.normalizedTerm.length, b.normalizedTerm.length);
+            const ratio = dist / maxLen;
+            const isSimilar = (ratio < 0.25 && maxLen > 5) || sharesStem(a.normalizedTerm, b.normalizedTerm);
+            if (isSimilar) {
+                const aTypes = [...new Set(a.sources.map((s) => s.artifactType))];
+                const bTypes = [...new Set(b.sources.map((s) => s.artifactType))];
+                const crossDoc = aTypes.some((t) => !bTypes.includes(t)) || bTypes.some((t) => !aTypes.includes(t));
+                if (crossDoc) {
+                    issues.push({
+                        level: "warning",
+                        code: "term_inconsistency",
+                        check: "terminology",
+                        message: `Similar terms used across documents: "${a.term}" (${aTypes.join(", ")}) vs "${b.term}" (${bTypes.join(", ")})`,
+                        suggestion: "Standardize terminology across all artifacts to avoid ambiguity."
+                    });
+                }
+            }
+        }
+    }
+    return issues;
+}

package/dist/core/tracing.d.ts

@@ -0,0 +1,21 @@
+import { type NormalizedBrief } from "./normalized-brief";
+import type { ArtifactDoc, ArtifactType, ValidationIssue } from "./types";
+type LoadedArtifact = {
+    type: ArtifactType;
+    file: string;
+    doc: ArtifactDoc;
+};
+export type TraceEntry = {
+    contractId: string;
+    contractText: string;
+    category: "goals" | "core_features" | "constraints";
+    references: Array<{
+        artifactType: ArtifactType;
+        file: string;
+        line: string;
+    }>;
+};
+export type TraceMap = Map<string, TraceEntry>;
+export declare function buildTraceMap(normalizedBrief: NormalizedBrief, loadedArtifacts: LoadedArtifact[]): TraceMap;
+export declare function checkRequirementCompleteness(traceMap: TraceMap, normalizedBrief: NormalizedBrief, presentArtifactTypes: ArtifactType[]): ValidationIssue[];
+export {};

package/dist/core/tracing.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTraceMap = buildTraceMap;
+exports.checkRequirementCompleteness = checkRequirementCompleteness;
+const markdown_1 = require("./markdown");
+function buildTraceMap(normalizedBrief, loadedArtifacts) {
+    const traceMap = new Map();
+    function registerContracts(items, category) {
+        for (const item of items) {
+            traceMap.set(item.id, {
+                contractId: item.id,
+                contractText: item.text,
+                category,
+                references: []
+            });
+        }
+    }
+    registerContracts(normalizedBrief.contracts.goals, "goals");
+    registerContracts(normalizedBrief.contracts.core_features, "core_features");
+    registerContracts(normalizedBrief.contracts.constraints, "constraints");
+    for (const artifact of loadedArtifacts) {
+        const tagged = (0, markdown_1.taggedLinesByContract)(artifact.doc.body);
+        for (const { contractId, line } of tagged) {
+            const entry = traceMap.get(contractId);
+            if (entry) {
+                entry.references.push({
+                    artifactType: artifact.type,
+                    file: artifact.file,
+                    line
+                });
+            }
+        }
+    }
+    return traceMap;
+}
+function checkRequirementCompleteness(traceMap, normalizedBrief, presentArtifactTypes) {
+    const issues = [];
+    if (presentArtifactTypes.length === 0)
+        return issues;
+    for (const [contractId, entry] of traceMap) {
+        if (entry.references.length === 0) {
+            issues.push({
+                level: "warning",
+                code: "untraced_requirement",
+                check: "tracing",
+                message: `Contract ${contractId} ("${truncate(entry.contractText, 60)}") is not referenced in any generated artifact.`,
+                suggestion: `Ensure [${contractId}] tag appears in at least one artifact body.`
+            });
+        }
+    }
+    const hasPrd = presentArtifactTypes.includes("prd");
+    if (hasPrd) {
+        for (const [contractId, entry] of traceMap) {
+            if (entry.category === "goals") {
+                const inPrd = entry.references.some((r) => r.artifactType === "prd");
+                if (!inPrd && entry.references.length > 0) {
+                    issues.push({
+                        level: "warning",
+                        code: "goal_missing_in_prd",
+                        check: "tracing",
+                        message: `Goal ${contractId} appears in downstream artifacts but is not traced in the PRD.`,
+                        suggestion: `Add [${contractId}] tag to the PRD to maintain traceability.`
+                    });
+                }
+            }
+        }
+    }
+    return issues;
+}
+function truncate(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    return `${text.slice(0, maxLength - 3)}...`;
+}

package/dist/core/types.d.ts

@@ -0,0 +1,35 @@
+export declare const CORE_ARTIFACT_TYPES: readonly ["prd", "workflow", "wireframe", "stories", "techspec"];
+export declare const ARTIFACT_TYPES: readonly ["prd", "workflow", "wireframe", "stories", "techspec"];
+export type CoreArtifactType = (typeof CORE_ARTIFACT_TYPES)[number];
+export type ArtifactType = CoreArtifactType | string;
+export type ArtifactDoc = {
+    frontmatter: Record<string, unknown>;
+    body: string;
+};
+export type ContractCoverage = {
+    goals: string[];
+    core_features: string[];
+    constraints: string[];
+};
+export type ValidationIssue = {
+    level: "error" | "warning";
+    code: string;
+    check?: "schema" | "tag_coverage" | "semantic_consistency" | "contract_relevance" | "terminology" | "tracing" | "cross_reference";
+    artifactType?: ArtifactType;
+    file?: string;
+    field?: string;
+    message: string;
+    suggestion?: string;
+};
+export type GenerateResult = {
+    body: string;
+    frontmatter?: Record<string, unknown>;
+};
+export type ProviderSchemaHint = {
+    artifactType: ArtifactType | "normalize" | "semantic_consistency" | "contract_relevance";
+    requiredHeadings: string[];
+    requiredContracts: Array<keyof ContractCoverage>;
+};
+export type LLMProvider = {
+    generate: (prompt: string, inputContext: Record<string, unknown>, schemaHint: ProviderSchemaHint) => Promise<GenerateResult>;
+};

package/dist/core/types.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ARTIFACT_TYPES = exports.CORE_ARTIFACT_TYPES = void 0;
+exports.CORE_ARTIFACT_TYPES = ["prd", "workflow", "wireframe", "stories", "techspec"];
+exports.ARTIFACT_TYPES = exports.CORE_ARTIFACT_TYPES;

package/dist/core/utils.d.ts

@@ -0,0 +1,7 @@
+export declare function ensureDir(dirPath: string): Promise<void>;
+export declare function fileExists(filePath: string): Promise<boolean>;
+export declare function readJsonFile<T>(filePath: string): Promise<T>;
+export declare function timestampSlug(date?: Date): string;
+export declare function artifactFileStamp(date?: Date): string;
+export declare function listFilesSortedByMtime(dirPath: string): Promise<string[]>;
+export declare function isPathInside(parentDir: string, candidatePath: string): boolean;

package/dist/core/utils.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureDir = ensureDir;
+exports.fileExists = fileExists;
+exports.readJsonFile = readJsonFile;
+exports.timestampSlug = timestampSlug;
+exports.artifactFileStamp = artifactFileStamp;
+exports.listFilesSortedByMtime = listFilesSortedByMtime;
+exports.isPathInside = isPathInside;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+async function ensureDir(dirPath) {
+    await promises_1.default.mkdir(dirPath, { recursive: true });
+}
+async function fileExists(filePath) {
+    try {
+        await promises_1.default.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readJsonFile(filePath) {
+    const raw = await promises_1.default.readFile(filePath, "utf8");
+    return JSON.parse(raw);
+}
+function timestampSlug(date = new Date()) {
+    return date.toISOString().replace(/[:.]/g, "-");
+}
+function pad2(value) {
+    return String(value).padStart(2, "0");
+}
+function artifactFileStamp(date = new Date()) {
+    const year = date.getFullYear();
+    const month = pad2(date.getMonth() + 1);
+    const day = pad2(date.getDate());
+    const hour = pad2(date.getHours());
+    const minute = pad2(date.getMinutes());
+    const second = pad2(date.getSeconds());
+    return `${year}${month}${day}-${hour}${minute}${second}`;
+}
+async function listFilesSortedByMtime(dirPath) {
+    const exists = await fileExists(dirPath);
+    if (!exists)
+        return [];
+    const entries = await promises_1.default.readdir(dirPath);
+    const withStats = await Promise.all(entries.map(async (name) => {
+        const fullPath = node_path_1.default.join(dirPath, name);
+        const stat = await promises_1.default.stat(fullPath);
+        return { fullPath, mtimeMs: stat.mtimeMs, isFile: stat.isFile() };
+    }));
+    return withStats
+        .filter((entry) => entry.isFile)
+        .sort((a, b) => b.mtimeMs - a.mtimeMs)
+        .map((entry) => entry.fullPath);
+}
+function isPathInside(parentDir, candidatePath) {
+    const parent = node_path_1.default.resolve(parentDir);
+    const child = node_path_1.default.resolve(candidatePath);
+    const relative = node_path_1.default.relative(parent, child);
+    return relative === "" || (!relative.startsWith("..") && !node_path_1.default.isAbsolute(relative));
+}

package/dist/core/validate.d.ts

@@ -0,0 +1,10 @@
+import type { ValidationIssue } from "./types";
+export type ValidateResult = {
+    pass: boolean;
+    reportPath: string;
+    issues: ValidationIssue[];
+};
+export declare function runValidate(cwd: string, options: {
+    strict?: boolean;
+    report?: string;
+}): Promise<ValidateResult>;

package/dist/core/validate.js

@@ -0,0 +1,226 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runValidate = runValidate;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const gray_matter_1 = __importDefault(require("gray-matter"));
+const artifact_registry_1 = require("./artifact-registry");
+const consistency_1 = require("./consistency");
+const errors_1 = require("./errors");
+const output_index_1 = require("./output-index");
+const paths_1 = require("./paths");
+const template_resolver_1 = require("./template-resolver");
+const utils_1 = require("./utils");
+const validator_1 = require("./validator");
+function sidecarPath(filePath) {
+    const parsed = node_path_1.default.parse(filePath);
+    return node_path_1.default.join(parsed.dir, `${parsed.name}.artifact.json`);
+}
+async function loadArtifactDoc(filePath) {
+    const sidecar = sidecarPath(filePath);
+    if (await (0, utils_1.fileExists)(sidecar)) {
+        const payload = await (0, utils_1.readJsonFile)(sidecar);
+        return {
+            frontmatter: payload.frontmatter ?? {},
+            body: typeof payload.body === "string" ? payload.body : ""
+        };
+    }
+    const raw = await promises_1.default.readFile(filePath, "utf8");
+    const parsed = (0, gray_matter_1.default)(raw);
+    return {
+        frontmatter: parsed.data,
+        body: parsed.content
+    };
+}
+async function loadLatestArtifacts(cwd) {
+    const defs = await (0, artifact_registry_1.listArtifactDefinitions)(cwd);
+    const loaded = [];
+    for (const def of defs) {
+        const type = def.name;
+        const active = await (0, output_index_1.getActiveArtifactPath)(cwd, type);
+        const fallback = async () => {
+            const files = await (0, utils_1.listFilesSortedByMtime)((0, paths_1.outputDirPath)(cwd, type, def.output_dir));
+            return files[0];
+        };
+        const latest = active ?? (await fallback());
+        if (!latest)
+            continue;
+        const parsed = await loadArtifactDoc(latest);
+        loaded.push({
+            type,
+            file: latest,
+            doc: parsed
+        });
+    }
+    return loaded;
+}
+async function listHtmlFiles(dir) {
+    if (!(await (0, utils_1.fileExists)(dir)))
+        return [];
+    const entries = await promises_1.default.readdir(dir, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".html"))
+        .map((entry) => node_path_1.default.join(dir, entry.name));
+}
+function formatIssue(issue) {
+    const location = issue.file ? ` (${issue.file})` : "";
+    const field = issue.field ? ` [${issue.field}]` : "";
+    const check = issue.check ? ` [${issue.check}]` : "";
+    const fix = issue.suggestion ? `\n  Suggestion: ${issue.suggestion}` : "";
+    return `- [${issue.level.toUpperCase()}] ${issue.code}${check}${field}: ${issue.message}${location}${fix}`;
+}
+async function writeReport(targetPath, issues) {
+    const status = issues.some((issue) => issue.level === "error") ? "FAIL" : "PASS";
+    const schemaIssues = issues.filter((issue) => issue.check === "schema");
+    const coverageIssues = issues.filter((issue) => issue.check === "tag_coverage");
+    const relevanceIssues = issues.filter((issue) => issue.check === "contract_relevance");
+    const semanticIssues = issues.filter((issue) => issue.check === "semantic_consistency");
+    const gate = (set) => (set.some((issue) => issue.level === "error") ? "FAIL" : "PASS");
+    const content = [
+        "# Prodo Validation Report",
+        "",
+        `Status: **${status}**`,
+        `Generated at: ${new Date().toISOString()}`,
+        "",
+        "## Gate Results",
+        `- Schema pass: ${gate(schemaIssues)}`,
+        `- Tag coverage pass: ${gate(coverageIssues)}`,
+        `- Contract relevance pass: ${gate(relevanceIssues)}`,
+        `- Semantic consistency pass: ${gate(semanticIssues)}`,
+        "",
+        "## Findings",
+        issues.length === 0 ? "- No issues found." : issues.map(formatIssue).join("\n"),
+        ""
+    ].join("\n");
+    await (0, utils_1.ensureDir)(node_path_1.default.dirname(targetPath));
+    await promises_1.default.writeFile(targetPath, content, "utf8");
+}
+async function runValidate(cwd, options) {
+    const normalizedPath = (0, paths_1.normalizedBriefPath)(cwd);
+    if (!(await (0, utils_1.fileExists)(normalizedPath))) {
+        throw new errors_1.UserError("Missing `.prodo/briefs/normalized-brief.json`. Run `prodo-init` and create it first.");
+    }
+    const normalizedBrief = await (0, utils_1.readJsonFile)(normalizedPath);
+    const loaded = await loadLatestArtifacts(cwd);
+    const issues = [];
+    for (const artifact of loaded) {
+        const template = await (0, template_resolver_1.resolveTemplate)({
+            cwd,
+            artifactType: artifact.type
+        });
+        const headings = template ? (0, template_resolver_1.extractRequiredHeadingsFromTemplate)(template.content) : [];
+        const schemaCheck = await (0, validator_1.validateSchema)(cwd, artifact.type, artifact.doc, headings);
+        issues.push(...schemaCheck.issues.map((issue) => ({ ...issue, file: artifact.file })));
+        if (artifact.type === "workflow") {
+            const ext = node_path_1.default.extname(artifact.file).toLowerCase();
+            if (ext !== ".md") {
+                issues.push({
+                    level: "error",
+                    code: "workflow_markdown_missing",
+                    check: "schema",
+                    artifactType: artifact.type,
+                    file: artifact.file,
+                    message: "Workflow explanation artifact must be Markdown (.md).",
+                    suggestion: "Regenerate workflow so explanation is written to .md."
+                });
+            }
+            const mmdPath = node_path_1.default.join(node_path_1.default.dirname(artifact.file), `${node_path_1.default.parse(artifact.file).name}.mmd`);
+            if (!(await (0, utils_1.fileExists)(mmdPath))) {
+                issues.push({
+                    level: "error",
+                    code: "workflow_mermaid_missing",
+                    check: "schema",
+                    artifactType: artifact.type,
+                    file: artifact.file,
+                    message: "Workflow Mermaid companion file (.mmd) is missing.",
+                    suggestion: "Regenerate workflow so markdown and .mmd are produced as a pair."
+                });
+            }
+            else {
+                const mmdRaw = await promises_1.default.readFile(mmdPath, "utf8");
+                const mermaidLike = /(^|\n)\s*flowchart\s+/i.test(mmdRaw) || /(^|\n)\s*graph\s+/i.test(mmdRaw);
+                if (!mermaidLike) {
+                    issues.push({
+                        level: "error",
+                        code: "workflow_mermaid_invalid",
+                        check: "schema",
+                        artifactType: artifact.type,
+                        file: mmdPath,
+                        message: "Workflow Mermaid file is invalid or prose-only.",
+                        suggestion: "Ensure .mmd file contains valid Mermaid diagram syntax."
+                    });
+                }
+            }
+        }
+        if (artifact.type === "wireframe") {
+            const ext = node_path_1.default.extname(artifact.file).toLowerCase();
+            if (ext !== ".md") {
+                issues.push({
+                    level: "error",
+                    code: "wireframe_markdown_missing",
+                    check: "schema",
+                    artifactType: artifact.type,
+                    file: artifact.file,
+                    message: "Wireframe explanation artifact must be Markdown (.md).",
+                    suggestion: "Regenerate wireframe so explanation is written to .md."
+                });
+            }
+            const htmlPath = node_path_1.default.join(node_path_1.default.dirname(artifact.file), `${node_path_1.default.parse(artifact.file).name}.html`);
+            if (!(await (0, utils_1.fileExists)(htmlPath))) {
+                issues.push({
+                    level: "error",
+                    code: "wireframe_html_missing",
+                    check: "schema",
+                    artifactType: artifact.type,
+                    file: artifact.file,
+                    message: "Wireframe HTML companion file is missing.",
+                    suggestion: "Regenerate wireframe so markdown and .html are produced as a pair."
+                });
+            }
+            else {
+                const htmlRaw = await promises_1.default.readFile(htmlPath, "utf8");
+                const htmlLooksValid = /<!doctype html>/i.test(htmlRaw) || /<html[\s>]/i.test(htmlRaw);
+                if (!htmlLooksValid) {
+                    issues.push({
+                        level: "error",
+                        code: "wireframe_html_invalid",
+                        check: "schema",
+                        artifactType: artifact.type,
+                        file: htmlPath,
+                        message: "Wireframe output is not valid HTML content.",
+                        suggestion: "Ensure wireframe companion HTML contains a valid document structure."
+                    });
+                }
+            }
+            const htmlFiles = await listHtmlFiles(node_path_1.default.dirname(artifact.file));
+            if (htmlFiles.length < 1) {
+                issues.push({
+                    level: "error",
+                    code: "wireframe_screens_missing",
+                    check: "schema",
+                    artifactType: artifact.type,
+                    file: artifact.file,
+                    message: "Wireframe must include at least one HTML screen artifact.",
+                    suggestion: "Regenerate wireframe to create paired .md and .html screen files."
+                });
+            }
+        }
+    }
+    issues.push(...(await (0, consistency_1.checkConsistency)(cwd, loaded, normalizedBrief)));
+    if (options.strict) {
+        for (const issue of issues) {
+            if (issue.level === "warning")
+                issue.level = "error";
+        }
+    }
+    const finalReportPath = options.report ? node_path_1.default.resolve(cwd, options.report) : (0, paths_1.reportPath)(cwd);
+    if (!(0, utils_1.isPathInside)(node_path_1.default.join(cwd, "product-docs"), finalReportPath)) {
+        throw new errors_1.UserError("Validation report must be inside `product-docs/`.");
+    }
+    await writeReport(finalReportPath, issues);
+    const pass = !issues.some((issue) => issue.level === "error");
+    return { pass, reportPath: finalReportPath, issues };
+}

package/dist/core/validator.d.ts

@@ -0,0 +1,5 @@
+import type { ArtifactDoc, ArtifactType, ValidationIssue } from "./types";
+export declare function validateSchema(cwd: string, artifactType: ArtifactType, doc: ArtifactDoc, requiredHeadingsOverride?: string[]): Promise<{
+    issues: ValidationIssue[];
+    requiredHeadings: string[];
+}>;

package/dist/core/validator.js

@@ -0,0 +1,76 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSchema = validateSchema;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const _2020_1 = __importDefault(require("ajv/dist/2020"));
+const ajv_formats_1 = __importDefault(require("ajv-formats"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const markdown_1 = require("./markdown");
+const paths_1 = require("./paths");
+const ajv = new _2020_1.default({ allErrors: true, strict: false });
+(0, ajv_formats_1.default)(ajv);
+async function resolveSchema(cwd, artifactType) {
+    const raw = await promises_1.default.readFile((0, paths_1.schemaPath)(cwd, artifactType), "utf8");
+    return js_yaml_1.default.load(raw);
+}
+function requiredHeadingsFromSchema(schema) {
+    if (!Array.isArray(schema.x_required_headings))
+        return [];
+    return schema.x_required_headings.filter((item) => typeof item === "string");
+}
+async function validateSchema(cwd, artifactType, doc, requiredHeadingsOverride) {
+    const schema = await resolveSchema(cwd, artifactType);
+    const requiredHeadings = requiredHeadingsOverride && requiredHeadingsOverride.length > 0
+        ? requiredHeadingsOverride
+        : requiredHeadingsFromSchema(schema);
+    const workingSchema = { ...schema };
+    delete workingSchema.x_required_headings;
+    const validate = ajv.compile(workingSchema);
+    const valid = validate(doc);
+    const issues = [];
+    if (!valid && validate.errors) {
+        for (const err of validate.errors) {
+            issues.push({
+                level: "error",
+                code: "schema_validation_failed",
+                check: "schema",
+                artifactType,
+                field: err.instancePath || err.schemaPath,
+                message: `Schema validation error: ${err.message ?? "unknown error"}`,
+                suggestion: "Adjust the generated content to satisfy schema requirements."
+            });
+        }
+    }
+    const sections = (0, markdown_1.sectionTextMap)(doc.body);
+    for (const heading of requiredHeadings) {
+        if (!doc.body.includes(heading)) {
+            issues.push({
+                level: "error",
+                code: "missing_required_heading",
+                check: "schema",
+                artifactType,
+                field: heading,
+                message: `Required section missing: ${heading}`,
+                suggestion: "Regenerate or manually edit the artifact to include all required headings."
+            });
+            continue;
+        }
+        const content = sections.get(heading) ?? "";
+        const isPlaceholder = /(tbd|to be defined|i don't know|unknown|n\/a)/i.test(content);
+        if (content.trim().length < 20 || isPlaceholder) {
+            issues.push({
+                level: "error",
+                code: "weak_required_heading_content",
+                check: "schema",
+                artifactType,
+                field: heading,
+                message: `Section has weak or placeholder content: ${heading}`,
+                suggestion: "Replace placeholders with concrete, actionable details."
+            });
+        }
+    }
+    return { issues, requiredHeadings };
+}