@workflow-cannon/workspace-kit 0.17.0 → 0.24.0

package/dist/modules/documentation/runtime-render-support.js

@@ -0,0 +1,36 @@
+export function resolveExpectedDocFamily(docType) {
+    if (docType.includes("runbooks/") || docType.startsWith("runbooks/"))
+        return "runbook";
+    if (docType.includes("workbooks/") || docType.startsWith("workbooks/"))
+        return "workbook";
+    return "rules";
+}
+export function renderTemplate(templateContent) {
+    const output = templateContent.replace(/\{\{\{([\s\S]*?)\}\}\}/g, (_match, instructionText) => {
+        const normalized = instructionText.trim().split("\n")[0] ?? "template instructions";
+        return `Generated content based on instruction: ${normalized}`;
+    });
+    return { output, unresolvedBlocks: output.includes("{{{") };
+}
+export function validateSectionCoverage(templateContent, output) {
+    const issues = [];
+    const sectionRegex = /^##\s+(.+)$/gm;
+    const expectedSections = [...templateContent.matchAll(sectionRegex)].map((match) => match[1]);
+    for (const section of expectedSections) {
+        if (!output.includes(`## ${section}`)) {
+            issues.push({ check: "section-coverage", message: `Missing required section: ${section}`, resolved: false });
+        }
+    }
+    return issues;
+}
+export function detectConflicts(aiOutput, humanOutput) {
+    const conflicts = [];
+    if (`${aiOutput}\n${humanOutput}`.includes("CONFLICT:")) {
+        conflicts.push({
+            source: "generated-output",
+            reason: "Generated output flagged a conflict marker",
+            severity: "stop"
+        });
+    }
+    return conflicts;
+}

package/dist/modules/documentation/runtime.js

@@ -1,436 +1,13 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
-import { dirname, resolve, sep } from "node:path";
-import { readdir } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
-function isPathWithinRoot(path, root) {
-    return path === root || path.startsWith(`${root}${sep}`);
-}
-function parseDefaultValue(fileContent, key, fallback) {
-    const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const regex = new RegExp(`\\\`${escaped}\\\`[^\\n]*default:\\s*\\\`([^\\\`]+)\\\``);
-    const match = fileContent.match(regex);
-    return match?.[1] ?? fallback;
-}
-async function loadRuntimeConfig(workspacePath) {
-    const runtimeSourceRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
-    const sourceRoots = [workspacePath, runtimeSourceRoot];
-    let sourceRoot = workspacePath;
-    let configContent;
-    for (const candidateRoot of sourceRoots) {
-        const candidate = resolve(candidateRoot, "src/modules/documentation/config.md");
-        if (!existsSync(candidate)) {
-            continue;
-        }
-        configContent = await readFile(candidate, "utf8");
-        sourceRoot = candidateRoot;
-        break;
-    }
-    if (!configContent) {
-        return {
-            aiRoot: "/.ai",
-            humanRoot: "docs/maintainers",
-            templatesRoot: "src/modules/documentation/templates",
-            instructionsRoot: "src/modules/documentation/instructions",
-            schemasRoot: "src/modules/documentation/schemas",
-            maxValidationAttempts: 3,
-            sourceRoot
-        };
-    }
-    const aiRoot = parseDefaultValue(configContent, "sources.aiRoot", "/.ai");
-    const humanRoot = parseDefaultValue(configContent, "sources.humanRoot", "docs/maintainers");
-    const templatesRoot = parseDefaultValue(configContent, "sources.templatesRoot", "src/modules/documentation/templates");
-    const instructionsRoot = parseDefaultValue(configContent, "sources.instructionsRoot", "src/modules/documentation/instructions");
-    const schemasRoot = parseDefaultValue(configContent, "sources.schemasRoot", "src/modules/documentation/schemas");
-    const maxValidationAttemptsRaw = parseDefaultValue(configContent, "generation.maxValidationAttempts", "3");
-    const maxValidationAttempts = Number.parseInt(maxValidationAttemptsRaw, 10);
-    return {
-        aiRoot,
-        humanRoot,
-        templatesRoot,
-        instructionsRoot,
-        schemasRoot,
-        maxValidationAttempts: Number.isFinite(maxValidationAttempts) ? maxValidationAttempts : 3,
-        sourceRoot
-    };
-}
-function parseAiRecordLine(line) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#"))
-        return null;
-    const parts = trimmed.split("|");
-    // Record format is `type|token|token...`. Ignore non-record markdown lines.
-    if (parts.length < 2)
-        return null;
-    const type = parts[0] ?? "";
-    if (!type)
-        return null;
-    const positional = [];
-    const kv = {};
-    for (const token of parts.slice(1)) {
-        if (!token)
-            continue;
-        const idx = token.indexOf("=");
-        if (idx >= 0) {
-            const k = token.slice(0, idx).trim();
-            const v = token.slice(idx + 1).trim();
-            if (!k)
-                continue;
-            kv[k] = v;
-        }
-        else {
-            positional.push(token);
-        }
-    }
-    return { type, positional, kv, raw: line };
-}
-function isAllowedMetaDoc(doc) {
-    return (doc === "rules" ||
-        doc === "runbook" ||
-        doc === "workbook" ||
-        doc === "generator" ||
-        doc === "map" ||
-        doc === "workflows" ||
-        doc === "commands" ||
-        doc === "decisions" ||
-        doc === "glossary" ||
-        doc === "observed" ||
-        doc === "planned" ||
-        doc === "checks" ||
-        doc === "manifest");
-}
-function validateAiSchema(aiOutput, ctx) {
-    const issues = [];
-    const lines = aiOutput.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
-    if (lines.length === 0) {
-        return [
-            {
-                check: "schema",
-                message: "AI output is empty",
-                resolved: false,
-            }
-        ];
-    }
-    const metaLine = lines[0];
-    const meta = parseAiRecordLine(metaLine);
-    if (!meta || meta.type !== "meta") {
-        return [
-            {
-                check: "schema",
-                message: "AI output must start with a meta record",
-                resolved: false,
-            }
-        ];
-    }
-    const v = meta.kv["v"];
-    const doc = meta.kv["doc"];
-    const truth = meta.kv["truth"];
-    const st = meta.kv["st"];
-    if (v !== "1") {
-        issues.push({
-            check: "schema",
-            message: "AI meta schemaVersion must be v=1",
-            resolved: false,
-        });
-    }
-    if (!doc || !isAllowedMetaDoc(doc)) {
-        issues.push({
-            check: "schema",
-            message: `Unsupported meta.doc '${doc ?? ""}'`,
-            resolved: false,
-        });
-    }
-    if (!truth || truth.length === 0) {
-        issues.push({
-            check: "schema",
-            message: "AI meta.truth is required",
-            resolved: false,
-        });
-    }
-    if (!st || st.length === 0) {
-        issues.push({
-            check: "schema",
-            message: "AI meta.st is required",
-            resolved: false,
-        });
-    }
-    if (ctx.expectedDoc && doc && ctx.expectedDoc !== doc) {
-        issues.push({
-            check: "schema",
-            message: `meta.doc '${doc}' does not match expected doc family for '${ctx.expectedDoc}'`,
-            resolved: !ctx.strict,
-        });
-    }
-    const requireActiveRecords = st === "active";
-    const allowedTypes = new Set([
-        // Global ai record families used across .ai/*.
-        "project",
-        "stack",
-        "prio",
-        "ref",
-        "rule",
-        "check",
-        "path",
-        "role",
-        "has",
-        "xhas",
-        "deps",
-        "xdeps",
-        "module",
-        "wf",
-        "cmd",
-        "decision",
-        "term",
-        "observed",
-        "planned",
-        "map",
-        // Runbooks
-        "runbook",
-        "intent",
-        "chain",
-        "artifact",
-        "state",
-        "transition",
-        "promotion",
-        "rollback",
-        // Workbooks
-        "workbook",
-        "scope",
-        "command",
-        "config",
-        "cadence",
-        "guardrail",
-    ]);
-    const presentByType = {};
-    const missingRequired = [];
-    for (const line of lines.slice(1)) {
-        const rec = parseAiRecordLine(line);
-        if (!rec)
-            continue;
-        presentByType[rec.type] = true;
-        if (!allowedTypes.has(rec.type)) {
-            issues.push({
-                check: "schema",
-                message: `Unknown AI record type '${rec.type}'`,
-                resolved: !ctx.strict,
-            });
-            continue;
-        }
-        // Minimal record-level validation for current runbook/workbook families.
-        if (rec.type === "ref") {
-            const p = rec.kv["path"];
-            const n = rec.kv["name"];
-            if (!p || !n) {
-                issues.push({
-                    check: "schema",
-                    message: "ref records require both 'name' and 'path'",
-                    resolved: !ctx.strict,
-                });
-            }
-            else {
-                const abs = resolve(ctx.workspacePath, p);
-                const ok = existsSync(abs);
-                if (!ok) {
-                    issues.push({
-                        check: "schema",
-                        message: `ref.path does not exist: '${p}'`,
-                        resolved: !ctx.strict,
-                    });
-                }
-            }
-            continue;
-        }
-        if (rec.type === "rule") {
-            const rid = rec.positional[0];
-            const lvl = rec.positional[1] ?? rec.kv["lvl"];
-            const directive = (() => {
-                // rule lines can be either:
-                // rule|RID|lvl|scope|directive|...
-                // or the scope can be omitted:
-                // rule|RID|lvl|directive|...
-                const nonKey = rec.positional.slice(2);
-                return nonKey[nonKey.length - 1];
-            })();
-            if (!rid || !/^R\d{3,}$/.test(rid)) {
-                issues.push({
-                    check: "schema",
-                    message: "rule records require RID formatted like R### or R####",
-                    resolved: !ctx.strict,
-                });
-            }
-            if (!lvl || !["must", "must_not", "should", "may"].includes(lvl)) {
-                issues.push({
-                    check: "schema",
-                    message: `rule lvl is invalid: '${lvl ?? ""}'`,
-                    resolved: !ctx.strict,
-                });
-            }
-            if (!directive || directive.length < 2) {
-                issues.push({
-                    check: "schema",
-                    message: "rule directive cannot be empty",
-                    resolved: !ctx.strict,
-                });
-            }
-            continue;
-        }
-        if (rec.type === "runbook") {
-            if (!rec.kv["name"] || !rec.kv["scope"]) {
-                issues.push({
-                    check: "schema",
-                    message: "runbook records require at least name and scope",
-                    resolved: !ctx.strict,
-                });
-            }
-            continue;
-        }
-        if (rec.type === "workbook") {
-            if (!rec.kv["name"]) {
-                issues.push({
-                    check: "schema",
-                    message: "workbook records require 'name'",
-                    resolved: !ctx.strict,
-                });
-            }
-            continue;
-        }
-        if (rec.type === "chain") {
-            const step = rec.kv["step"];
-            const command = rec.kv["command"];
-            const expect = rec.kv["expect_exit"];
-            if (!step || !command || expect === undefined) {
-                issues.push({
-                    check: "schema",
-                    message: "chain records require step, command, and expect_exit",
-                    resolved: !ctx.strict,
-                });
-            }
-            continue;
-        }
-        if (rec.type === "transition") {
-            if (!rec.kv["from"] || !rec.kv["to"] || !rec.kv["requires"]) {
-                issues.push({
-                    check: "schema",
-                    message: "transition records require from, to, requires",
-                    resolved: !ctx.strict,
-                });
-            }
-            continue;
-        }
-        if (rec.type === "state") {
-            if (!rec.kv["name"]) {
-                issues.push({
-                    check: "schema",
-                    message: "state records require name",
-                    resolved: !ctx.strict,
-                });
-            }
-            continue;
-        }
-        if (rec.type === "artifact") {
-            if (!rec.kv["path"] || !rec.kv["schema"]) {
-                issues.push({
-                    check: "schema",
-                    message: "artifact records require path and schema",
-                    resolved: !ctx.strict,
-                });
-            }
-            continue;
-        }
-        if (rec.type === "command") {
-            if (!rec.kv["name"]) {
-                issues.push({
-                    check: "schema",
-                    message: "command records require name",
-                    resolved: !ctx.strict,
-                });
-            }
-            continue;
-        }
-        if (rec.type === "config") {
-            if (!rec.kv["key"]) {
-                issues.push({
-                    check: "schema",
-                    message: "config records require key",
-                    resolved: !ctx.strict,
-                });
-            }
-            continue;
-        }
-    }
-    // Per-doc required record sets.
-    if (requireActiveRecords) {
-        if (doc === "runbook") {
-            if (!presentByType["runbook"])
-                missingRequired.push("runbook| record");
-            if (!presentByType["rule"] && !presentByType["chain"])
-                missingRequired.push("at least one rule| or chain| record");
-        }
-        if (doc === "workbook") {
-            if (!presentByType["workbook"])
-                missingRequired.push("workbook| record");
-            if (!presentByType["command"])
-                missingRequired.push("at least one command| record");
-            if (!presentByType["config"])
-                missingRequired.push("at least one config| record");
-        }
-        if (doc === "rules") {
-            if (!presentByType["rule"] && !presentByType["check"])
-                missingRequired.push("at least one rule| or check| record");
-        }
-    }
-    if (missingRequired.length > 0) {
-        issues.push({
-            check: "schema",
-            message: `Missing required AI records for doc family '${doc}': ${missingRequired.join(", ")}`,
-            resolved: !ctx.strict,
-        });
-    }
-    return issues;
-}
-function autoResolveAiSchema(aiOutput) {
-    if (aiOutput.startsWith("meta|v=")) {
-        return aiOutput;
-    }
-    return `meta|v=1|doc=rules|truth=canonical|st=draft\n\n${aiOutput}`;
-}
-function renderTemplate(templateContent) {
-    const output = templateContent.replace(/\{\{\{([\s\S]*?)\}\}\}/g, (_match, instructionText) => {
-        const normalized = instructionText.trim().split("\n")[0] ?? "template instructions";
-        return `Generated content based on instruction: ${normalized}`;
-    });
-    return {
-        output,
-        unresolvedBlocks: output.includes("{{{")
-    };
-}
-function validateSectionCoverage(templateContent, output) {
-    const issues = [];
-    const sectionRegex = /^##\s+(.+)$/gm;
-    const expectedSections = [...templateContent.matchAll(sectionRegex)].map((match) => match[1]);
-    for (const section of expectedSections) {
-        if (!output.includes(`## ${section}`)) {
-            issues.push({
-                check: "section-coverage",
-                message: `Missing required section: ${section}`,
-                resolved: false
-            });
-        }
-    }
-    return issues;
-}
-function detectConflicts(aiOutput, humanOutput) {
-    const conflicts = [];
-    const combined = `${aiOutput}\n${humanOutput}`;
-    if (combined.includes("CONFLICT:")) {
-        conflicts.push({
-            source: "generated-output",
-            reason: "Generated output flagged a conflict marker",
-            severity: "stop"
-        });
-    }
-    return conflicts;
-}
+import { dirname, resolve } from "node:path";
+import { parseAiDocument } from "./parser.js";
+import { normalizeDocument } from "./normalizer.js";
+import { renderDocument } from "./renderer.js";
+import { autoResolveAiSchema, validateAiSchema } from "./validator.js";
+import { isPathWithinRoot, loadRuntimeConfig } from "./runtime-config.js";
+import { detectConflicts, renderTemplate, resolveExpectedDocFamily, validateSectionCoverage } from "./runtime-render-support.js";
+import { runGenerateAllDocuments } from "./runtime-batch.js";
 export async function generateDocument(args, ctx) {
     const documentType = args.documentType;
     if (!documentType) {
@@ -522,13 +99,6 @@ export async function generateDocument(args, ctx) {
         filesRead.push(schemaPath);
         await readFile(schemaPath, "utf8");
     }
-    function resolveExpectedDocFamily(docType) {
-        if (docType.includes("runbooks/") || docType.startsWith("runbooks/"))
-            return "runbook";
-        if (docType.includes("workbooks/") || docType.startsWith("workbooks/"))
-            return "workbook";
-        return "rules";
-    }
     const expectedDoc = resolveExpectedDocFamily(documentType);
     // Default AI output for draft generation. When AI files already exist and overwriteAi is false,
     // we validate and preserve the existing AI surface content instead of using this stub.
@@ -580,6 +150,19 @@ export async function generateDocument(args, ctx) {
             }
         };
     }
+    // Build normalized model now to keep parser/validator/normalizer wiring exercised.
+    const normalized = normalizeDocument(parseAiDocument(aiOutput));
+    void renderDocument(normalized, {
+        id: "runtime-preview",
+        version: 1,
+        docType: expectedDoc,
+        target: documentType,
+        profile: expectedDoc === "runbook" ? "runbook" : expectedDoc === "workbook" ? "workbook" : "core",
+        sections: [
+            { id: "meta", source: "meta", renderer: "renderMetaSection" },
+            { id: "rules", source: "rules", renderer: "renderRuleSection" }
+        ]
+    });
     let humanOutput = `# ${documentType}\n\nGenerated without template.`;
     if (templateFound) {
         const rendered = renderTemplate(templateContent);
@@ -686,76 +269,5 @@ export async function generateDocument(args, ctx) {
     };
 }
 export async function generateAllDocuments(args, ctx) {
-    const config = await loadRuntimeConfig(ctx.workspacePath);
-    const templatesDir = resolve(config.sourceRoot, config.templatesRoot);
-    async function listTemplateFiles(dir, baseDir) {
-        const entries = await readdir(dir, { withFileTypes: true });
-        const files = [];
-        for (const entry of entries) {
-            const absPath = resolve(dir, entry.name);
-            if (entry.isDirectory()) {
-                files.push(...(await listTemplateFiles(absPath, baseDir)));
-                continue;
-            }
-            if (!entry.isFile() || !entry.name.endsWith(".md")) {
-                continue;
-            }
-            const relPath = absPath.slice(baseDir.length + 1).split("\\").join("/");
-            files.push(relPath);
-        }
-        return files;
-    }
-    let templateFiles = [];
-    try {
-        templateFiles = (await listTemplateFiles(templatesDir, templatesDir)).sort();
-    }
-    catch {
-        return {
-            ok: false,
-            results: [],
-            summary: {
-                total: 0,
-                succeeded: 0,
-                failed: 1,
-                skipped: 0,
-                timestamp: new Date().toISOString()
-            }
-        };
-    }
-    const results = [];
-    let succeeded = 0;
-    let failed = 0;
-    let skipped = 0;
-    const batchOptions = {
-        ...args.options,
-        overwriteAi: args.options?.overwriteAi ?? false,
-        overwriteHuman: args.options?.overwriteHuman ?? true,
-        strict: args.options?.strict ?? false,
-    };
-    for (const templateFile of templateFiles) {
-        const result = await generateDocument({ documentType: templateFile, options: batchOptions }, ctx);
-        results.push(result);
-        if (result.ok) {
-            if (result.evidence.filesWritten.length > 0) {
-                succeeded++;
-            }
-            else {
-                skipped++;
-            }
-        }
-        else {
-            failed++;
-        }
-    }
-    return {
-        ok: failed === 0,
-        results,
-        summary: {
-            total: templateFiles.length,
-            succeeded,
-            failed,
-            skipped,
-            timestamp: new Date().toISOString()
-        }
-    };
+    return runGenerateAllDocuments(args, ctx, generateDocument);
 }