@shahmarasy/prodo 0.1.4 → 0.1.6

package/dist/core/clean.d.ts

@@ -0,0 +1,10 @@
+export type CleanOptions = {
+    cwd: string;
+    dryRun?: boolean;
+    log?: (message: string) => void;
+};
+export type CleanResult = {
+    removedPaths: string[];
+    preservedPaths: string[];
+};
+export declare function runClean(options: CleanOptions): Promise<CleanResult>;

package/dist/core/clean.js

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runClean = runClean;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const paths_1 = require("./paths");
+const utils_1 = require("./utils");
+const REMOVABLE_DIRS = [
+    "product-docs"
+];
+const REMOVABLE_PRODO_SUBDIRS = [
+    "state",
+    "briefs"
+];
+const PRESERVED_PRODO_FILES = [
+    "settings.json",
+    "hooks.yml",
+    "config.json"
+];
+async function runClean(options) {
+    const { cwd, dryRun = false, log = console.log } = options;
+    const result = { removedPaths: [], preservedPaths: [] };
+    for (const dir of REMOVABLE_DIRS) {
+        const fullPath = node_path_1.default.join(cwd, dir);
+        if (await (0, utils_1.fileExists)(fullPath)) {
+            if (dryRun) {
+                log(`[Dry Run] Would remove: ${fullPath}`);
+            }
+            else {
+                await promises_1.default.rm(fullPath, { recursive: true, force: true });
+                log(`Removed: ${fullPath}`);
+            }
+            result.removedPaths.push(fullPath);
+        }
+    }
+    const prodo = (0, paths_1.prodoPath)(cwd);
+    for (const subdir of REMOVABLE_PRODO_SUBDIRS) {
+        const fullPath = node_path_1.default.join(prodo, subdir);
+        if (await (0, utils_1.fileExists)(fullPath)) {
+            if (dryRun) {
+                log(`[Dry Run] Would remove: ${fullPath}`);
+            }
+            else {
+                await promises_1.default.rm(fullPath, { recursive: true, force: true });
+                log(`Removed: ${fullPath}`);
+            }
+            result.removedPaths.push(fullPath);
+        }
+    }
+    const briefPath = node_path_1.default.join(cwd, "brief.md");
+    if (await (0, utils_1.fileExists)(briefPath)) {
+        result.preservedPaths.push(briefPath);
+    }
+    for (const file of PRESERVED_PRODO_FILES) {
+        const fullPath = node_path_1.default.join(prodo, file);
+        if (await (0, utils_1.fileExists)(fullPath)) {
+            result.preservedPaths.push(fullPath);
+        }
+    }
+    const preservedDirs = ["templates", "schemas", "prompts", "commands", "presets"];
+    for (const dir of preservedDirs) {
+        const fullPath = node_path_1.default.join(prodo, dir);
+        if (await (0, utils_1.fileExists)(fullPath)) {
+            result.preservedPaths.push(fullPath);
+        }
+    }
+    if (result.preservedPaths.length > 0 && !dryRun) {
+        log(`Preserved: ${result.preservedPaths.length} file(s)/dir(s)`);
+    }
+    return result;
+}

package/dist/core/consistency.d.ts

@@ -0,0 +1,8 @@
+import type { ArtifactDoc, ArtifactType, ValidationIssue } from "./types";
+type LoadedArtifact = {
+    type: ArtifactType;
+    file: string;
+    doc: ArtifactDoc;
+};
+export declare function checkConsistency(cwd: string, loadedArtifacts: LoadedArtifact[], normalizedBrief: Record<string, unknown>): Promise<ValidationIssue[]>;
+export {};

package/dist/core/consistency.js

@@ -0,0 +1,328 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkConsistency = checkConsistency;
+const node_path_1 = __importDefault(require("node:path"));
+const artifact_registry_1 = require("./artifact-registry");
+const markdown_1 = require("./markdown");
+const normalized_brief_1 = require("./normalized-brief");
+const providers_1 = require("../providers");
+const terminology_1 = require("./terminology");
+const tracing_1 = require("./tracing");
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string");
+}
+function readCoverage(frontmatter) {
+    const coverage = frontmatter.contract_coverage;
+    return {
+        goals: asStringArray(coverage?.goals),
+        core_features: asStringArray(coverage?.core_features),
+        constraints: asStringArray(coverage?.constraints)
+    };
+}
+async function checkMissingArtifacts(cwd, loadedArtifacts) {
+    const expectedTypes = await (0, artifact_registry_1.listArtifactTypes)(cwd);
+    const present = new Set(loadedArtifacts.map((item) => item.type));
+    const missing = expectedTypes.filter((type) => !present.has(type));
+    if (missing.length === 0)
+        return [];
+    return [
+        {
+            level: "warning",
+            code: "missing_artifacts",
+            check: "schema",
+            message: `Some artifacts are missing from outputs: ${missing.join(", ")}`,
+            suggestion: "Run the corresponding prodo-* commands before final validation."
+        }
+    ];
+}
+async function checkContractCoverage(cwd, loaded, normalizedBrief) {
+    const issues = [];
+    const normalized = (0, normalized_brief_1.parseNormalizedBriefOrThrow)(normalizedBrief);
+    const expected = (0, normalized_brief_1.contractIds)(normalized.contracts);
+    for (const artifact of loaded) {
+        const def = await (0, artifact_registry_1.getArtifactDefinition)(cwd, artifact.type);
+        const coverage = readCoverage(artifact.doc.frontmatter);
+        for (const key of def.required_contracts) {
+            const missing = expected[key].filter((id) => !coverage[key].includes(id));
+            if (missing.length === 0)
+                continue;
+            issues.push({
+                level: "error",
+                code: "missing_contract_coverage",
+                check: "tag_coverage",
+                artifactType: artifact.type,
+                file: artifact.file,
+                field: `frontmatter.contract_coverage.${key}`,
+                message: `Artifact is missing required contract IDs for ${key}: ${missing.join(", ")}`,
+                suggestion: "Regenerate artifact and include explicit contract tags such as [G1], [F2], [C1]."
+            });
+        }
+    }
+    return issues;
+}
+function checkUpstreamReferences(loaded) {
+    const issues = [];
+    const filesByName = new Set(loaded.map((item) => node_path_1.default.normalize(item.file)));
+    for (const artifact of loaded) {
+        const upstream = artifact.doc.frontmatter.upstream_artifacts;
+        if (!Array.isArray(upstream))
+            continue;
+        for (const rawItem of upstream) {
+            if (typeof rawItem !== "string")
+                continue;
+            const resolved = node_path_1.default.normalize(node_path_1.default.resolve(node_path_1.default.dirname(artifact.file), rawItem));
+            if (!filesByName.has(resolved)) {
+                issues.push({
+                    level: "error",
+                    code: "broken_upstream_reference",
+                    check: "schema",
+                    artifactType: artifact.type,
+                    file: artifact.file,
+                    field: "frontmatter.upstream_artifacts",
+                    message: `Referenced upstream artifact not found: ${rawItem}`,
+                    suggestion: "Regenerate this artifact or update upstream_artifacts paths to existing outputs."
+                });
+            }
+        }
+    }
+    return issues;
+}
+// taggedLinesByContract is now imported from ./markdown
+function parseJsonObject(raw, fallback) {
+    const trimmed = raw.trim();
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const candidate = fenced ? fenced[1] : trimmed;
+    try {
+        return JSON.parse(candidate);
+    }
+    catch {
+        return fallback;
+    }
+}
+function hasEnglishLeak(body) {
+    const markers = [" the ", " and ", " with ", " user ", " should ", " must "];
+    const normalized = ` ${body.toLowerCase().replace(/\s+/g, " ")} `;
+    return markers.filter((item) => normalized.includes(item)).length >= 2;
+}
+function checkLanguageConsistency(loaded) {
+    const issues = [];
+    const languages = new Set();
+    for (const artifact of loaded) {
+        const lang = String((artifact.doc.frontmatter.language ?? "")).toLowerCase();
+        if (lang)
+            languages.add(lang);
+        if (lang.startsWith("tr") && hasEnglishLeak(artifact.doc.body)) {
+            issues.push({
+                level: "error",
+                code: "language_mixed_content",
+                check: "schema",
+                artifactType: artifact.type,
+                file: artifact.file,
+                message: "Artifact contains mixed language content while target language is Turkish.",
+                suggestion: "Regenerate artifact with strict Turkish output."
+            });
+        }
+    }
+    if (languages.size > 1) {
+        issues.push({
+            level: "error",
+            code: "language_inconsistent_across_artifacts",
+            check: "schema",
+            message: "Artifacts have inconsistent language settings.",
+            suggestion: "Regenerate artifacts so all frontmatter.language values match."
+        });
+    }
+    return issues;
+}
+async function checkContractRelevance(loaded, normalizedBrief) {
+    const normalized = (0, normalized_brief_1.parseNormalizedBriefOrThrow)(normalizedBrief);
+    const contractMap = new Map();
+    for (const item of normalized.contracts.goals)
+        contractMap.set(item.id, item.text);
+    for (const item of normalized.contracts.core_features)
+        contractMap.set(item.id, item.text);
+    for (const item of normalized.contracts.constraints)
+        contractMap.set(item.id, item.text);
+    const provider = (0, providers_1.createProvider)();
+    const issues = [];
+    for (const artifact of loaded) {
+        const taggedLines = (0, markdown_1.taggedLinesByContract)(artifact.doc.body);
+        for (const tagged of taggedLines) {
+            const contractText = contractMap.get(tagged.contractId);
+            if (!contractText) {
+                issues.push({
+                    level: "error",
+                    code: "unknown_contract_tag",
+                    check: "contract_relevance",
+                    artifactType: artifact.type,
+                    file: artifact.file,
+                    field: tagged.contractId,
+                    message: `Unknown contract tag used: ${tagged.contractId}`,
+                    suggestion: "Use only contract IDs that exist in normalized brief contracts."
+                });
+                continue;
+            }
+            const response = await provider.generate("Evaluate if tagged line semantically matches contract text.", {
+                contract_id: tagged.contractId,
+                contract_text: contractText,
+                context_text: tagged.line
+            }, {
+                artifactType: "contract_relevance",
+                requiredHeadings: [],
+                requiredContracts: []
+            });
+            const verdict = parseJsonObject(response.body, {});
+            const relevant = Boolean(verdict.relevant);
+            if (!relevant) {
+                issues.push({
+                    level: "error",
+                    code: "irrelevant_contract_tag_usage",
+                    check: "contract_relevance",
+                    artifactType: artifact.type,
+                    file: artifact.file,
+                    field: tagged.contractId,
+                    message: `Tag ${tagged.contractId} does not match nearby content semantically.`,
+                    suggestion: verdict.reason ?? "Rewrite the tagged sentence so it clearly addresses the referenced contract."
+                });
+            }
+        }
+    }
+    return issues;
+}
+async function checkSemanticPairs(loaded) {
+    const byType = new Map();
+    for (const artifact of loaded)
+        byType.set(artifact.type, artifact);
+    const pairs = [
+        ["prd", "stories"],
+        ["workflow", "techspec"],
+        ["workflow", "wireframe"]
+    ];
+    const provider = (0, providers_1.createProvider)();
+    const issues = [];
+    for (const [leftType, rightType] of pairs) {
+        const left = byType.get(leftType);
+        const right = byType.get(rightType);
+        if (!left || !right)
+            continue;
+        const result = await provider.generate("Compare paired artifacts semantically and return contradictions.", {
+            pair: {
+                left_type: leftType,
+                left_file: left.file,
+                left_coverage: readCoverage(left.doc.frontmatter),
+                left_body: left.doc.body,
+                right_type: rightType,
+                right_file: right.file,
+                right_coverage: readCoverage(right.doc.frontmatter),
+                right_body: right.doc.body
+            }
+        }, {
+            artifactType: "semantic_consistency",
+            requiredHeadings: [],
+            requiredContracts: []
+        });
+        const parsed = parseJsonObject(result.body, { issues: [] });
+        for (const item of parsed.issues ?? []) {
+            issues.push({
+                level: (item.level === "warning" ? "warning" : "error"),
+                code: typeof item.code === "string" ? item.code : "semantic_inconsistency",
+                check: "semantic_consistency",
+                file: typeof item.file === "string" ? item.file : left.file,
+                field: typeof item.contract_id === "string" ? item.contract_id : undefined,
+                message: typeof item.message === "string"
+                    ? item.message
+                    : `Semantic mismatch between ${leftType} and ${rightType}.`,
+                suggestion: typeof item.suggestion === "string"
+                    ? item.suggestion
+                    : `Align ${leftType} and ${rightType} decisions and regenerate.`
+            });
+        }
+    }
+    return issues;
+}
+function checkCrossReferences(loadedArtifacts) {
+    const issues = [];
+    const artifactTypeNames = new Set(loadedArtifacts.map((a) => a.type));
+    const sectionsByType = new Map();
+    for (const artifact of loadedArtifacts) {
+        const sections = (0, markdown_1.parseMarkdownSections)(artifact.doc.body);
+        const headingSet = new Set(sections.map((s) => s.headingKey));
+        sectionsByType.set(artifact.type, headingSet);
+    }
+    const crossRefPattern = /(?:see|refer to|as (?:defined|described|specified) in)\s+(prd|workflow|wireframe|stories|techspec)(?:\s+(?:section\s+)?[""]?([^"".,)\n]+)[""]?)?/gi;
+    for (const artifact of loadedArtifacts) {
+        const matches = artifact.doc.body.matchAll(crossRefPattern);
+        for (const match of matches) {
+            const refType = match[1].toLowerCase();
+            const refSection = match[2]?.trim();
+            if (!artifactTypeNames.has(refType)) {
+                issues.push({
+                    level: "warning",
+                    code: "broken_cross_reference",
+                    check: "cross_reference",
+                    artifactType: artifact.type,
+                    file: artifact.file,
+                    message: `Cross-reference to "${refType}" but that artifact does not exist.`,
+                    suggestion: `Generate the ${refType} artifact or remove the cross-reference.`
+                });
+                continue;
+            }
+            if (refSection) {
+                const targetSections = sectionsByType.get(refType);
+                if (targetSections) {
+                    const normalizedRef = refSection.toLowerCase().replace(/[^a-z0-9\s]/g, " ").replace(/\s+/g, " ").trim();
+                    const found = [...targetSections].some((s) => s.includes(normalizedRef) || normalizedRef.includes(s));
+                    if (!found) {
+                        issues.push({
+                            level: "warning",
+                            code: "broken_cross_reference",
+                            check: "cross_reference",
+                            artifactType: artifact.type,
+                            file: artifact.file,
+                            message: `Cross-reference to "${refType} section ${refSection}" but that section was not found.`,
+                            suggestion: `Verify the section name or update the cross-reference.`
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return issues;
+}
+async function checkConsistency(cwd, loadedArtifacts, normalizedBrief) {
+    const baseIssues = [
+        ...(await checkMissingArtifacts(cwd, loadedArtifacts)),
+        ...(await checkContractCoverage(cwd, loadedArtifacts, normalizedBrief)),
+        ...checkUpstreamReferences(loadedArtifacts),
+        ...checkLanguageConsistency(loadedArtifacts)
+    ];
+    const relevanceIssues = await checkContractRelevance(loadedArtifacts, normalizedBrief);
+    const semanticIssues = await checkSemanticPairs(loadedArtifacts);
+    const crossRefIssues = checkCrossReferences(loadedArtifacts);
+    let terminologyIssues = [];
+    let tracingIssues = [];
+    try {
+        const parsed = (0, normalized_brief_1.parseNormalizedBriefOrThrow)(normalizedBrief);
+        const termMap = (0, terminology_1.buildTermMap)(parsed, loadedArtifacts);
+        terminologyIssues = (0, terminology_1.checkTermReconciliation)(termMap);
+        const traceMap = (0, tracing_1.buildTraceMap)(parsed, loadedArtifacts);
+        const presentTypes = loadedArtifacts.map((a) => a.type);
+        tracingIssues = (0, tracing_1.checkRequirementCompleteness)(traceMap, parsed, presentTypes);
+    }
+    catch {
+        // normalized brief parse failed — skip terminology/tracing (other checks will catch it)
+    }
+    return [
+        ...baseIssues,
+        ...relevanceIssues,
+        ...semanticIssues,
+        ...crossRefIssues,
+        ...terminologyIssues,
+        ...tracingIssues
+    ];
+}

package/dist/core/constants.d.ts

@@ -0,0 +1,7 @@
+import type { ContractCoverage } from "./types";
+export declare const PRODO_DIR = ".prodo";
+export declare const DEFAULT_STATUS = "draft";
+export declare function defaultOutputDir(artifactType: string): string;
+export declare function defaultRequiredHeadings(artifactType: string): string[];
+export declare function defaultUpstreamByArtifact(artifactType: string): string[];
+export declare function defaultRequiredContractsByArtifact(artifactType: string): Array<keyof ContractCoverage>;

package/dist/core/constants.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STATUS = exports.PRODO_DIR = void 0;
+exports.defaultOutputDir = defaultOutputDir;
+exports.defaultRequiredHeadings = defaultRequiredHeadings;
+exports.defaultUpstreamByArtifact = defaultUpstreamByArtifact;
+exports.defaultRequiredContractsByArtifact = defaultRequiredContractsByArtifact;
+exports.PRODO_DIR = ".prodo";
+exports.DEFAULT_STATUS = "draft";
+const CORE_OUTPUT_DIR_BY_ARTIFACT = {
+    prd: "prd",
+    workflow: "workflows",
+    wireframe: "wireframes",
+    stories: "stories",
+    techspec: "techspec"
+};
+const CORE_REQUIRED_HEADINGS = {
+    prd: ["## Problem", "## Goals", "## Scope", "## Requirements"],
+    workflow: [
+        "## Flow Purpose",
+        "## Actors",
+        "## Preconditions",
+        "## Main Flow",
+        "## Edge Cases",
+        "## Postconditions"
+    ],
+    wireframe: [
+        "## Screen Purpose",
+        "## Primary Actor",
+        "## Main Sections",
+        "## Fields/Inputs",
+        "## Actions/Buttons",
+        "## States/Messages",
+        "## Notes"
+    ],
+    stories: ["## User Stories", "## Acceptance Criteria"],
+    techspec: ["## Architecture", "## Data Model", "## APIs", "## Risks"]
+};
+const CORE_UPSTREAM_BY_ARTIFACT = {
+    prd: [],
+    workflow: ["prd"],
+    wireframe: ["prd", "workflow"],
+    stories: ["prd"],
+    techspec: ["prd", "stories"]
+};
+const CORE_REQUIRED_CONTRACTS_BY_ARTIFACT = {
+    prd: ["goals", "core_features"],
+    workflow: ["core_features"],
+    wireframe: ["core_features"],
+    stories: ["core_features"],
+    techspec: ["core_features", "constraints"]
+};
+function defaultOutputDir(artifactType) {
+    return CORE_OUTPUT_DIR_BY_ARTIFACT[artifactType] ?? `${artifactType}s`;
+}
+function defaultRequiredHeadings(artifactType) {
+    return CORE_REQUIRED_HEADINGS[artifactType] ?? ["## Summary", "## Details"];
+}
+function defaultUpstreamByArtifact(artifactType) {
+    return CORE_UPSTREAM_BY_ARTIFACT[artifactType] ?? [];
+}
+function defaultRequiredContractsByArtifact(artifactType) {
+    return CORE_REQUIRED_CONTRACTS_BY_ARTIFACT[artifactType] ?? ["core_features"];
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class UserError extends Error {
+    constructor(message: string);
+}

package/dist/core/errors.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserError = void 0;
+class UserError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UserError";
+    }
+}
+exports.UserError = UserError;

package/dist/core/fix.d.ts

@@ -0,0 +1,31 @@
+import type { ArtifactType, ValidationIssue } from "./types";
+import { type ValidateResult } from "./validate";
+export type FixProposal = {
+    targets: ArtifactType[];
+    issues: ValidationIssue[];
+    issuesByArtifact: Map<ArtifactType, ValidationIssue[]>;
+    initialReport: ValidateResult;
+};
+export type FixOptions = {
+    cwd: string;
+    agent?: string;
+    strict?: boolean;
+    report?: string;
+    dryRun?: boolean;
+    log?: (message: string) => void;
+};
+export type FixResult = {
+    proposal: FixProposal;
+    applied: boolean;
+    finalPass: boolean;
+    reportPath: string;
+    backupDir?: string;
+};
+export declare function resolveFixTargets(cwd: string, artifactTypes: ArtifactType[], issues: Array<{
+    artifactType?: ArtifactType;
+}>): Promise<ArtifactType[]>;
+export declare function buildFixProposal(options: FixOptions): Promise<FixProposal>;
+export declare function createBackup(cwd: string, targets: ArtifactType[]): Promise<string>;
+export declare function restoreBackup(cwd: string, backupDir: string): Promise<void>;
+export declare function applyFix(cwd: string, proposal: FixProposal, options: FixOptions): Promise<FixResult>;
+export declare function runFix(options: FixOptions): Promise<FixResult>;