chapterhouse 0.3.18 → 0.3.20

package/dist/wiki/fix.js

@@ -0,0 +1,335 @@
+import { statSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { resolveWikiRelativePath } from "../paths.js";
+import { parseWikiFrontmatter } from "./frontmatter.js";
+import { ensureWikiStructure, listPages, readPage, writePage } from "./fs.js";
+import { loadTaxonomy } from "./taxonomy.js";
+const DEFAULT_FIXES = [
+    "frontmatter-backfill",
+    "tag-normalize",
+    "autostub-mark",
+];
+const KNOWN_FIELD_ORDER = [
+    "title",
+    "summary",
+    "updated",
+    "tags",
+    "autostub",
+    "confidence",
+    "contested",
+    "contradictions",
+    "related",
+];
+export function fixWiki(options = {}) {
+    ensureWikiStructure();
+    const dryRun = options.dryRun ?? true;
+    const enabledFixes = new Set(options.fixes?.length ? options.fixes : DEFAULT_FIXES);
+    const pathFilter = options.pathGlob ? compileGlob(options.pathGlob) : undefined;
+    const allowedTags = enabledFixes.has("tag-normalize") ? loadTaxonomy() : [];
+    const canonicalTags = new Map(allowedTags.map((tag) => [normalizeTagKey(tag), tag]));
+    const reports = [];
+    const diffs = [];
+    let changedFiles = 0;
+    const pages = listPages()
+        .filter(isFixablePage)
+        .filter((path) => !pathFilter || pathFilter.test(path))
+        .sort();
+    for (const path of pages) {
+        const content = readPage(path);
+        if (!content)
+            continue;
+        const parsedResult = parseWikiFrontmatter(content);
+        if (parsedResult.parsed.metadata.autofix === false) {
+            continue;
+        }
+        const nextFrontmatter = cloneFrontmatter(parsedResult.parsed);
+        const body = parsedResult.body;
+        const changes = [];
+        let unknownTagsForFile = [];
+        if (enabledFixes.has("frontmatter-backfill")) {
+            let addedTitle = false;
+            let addedSummary = false;
+            let addedUpdated = false;
+            let addedAutostub = false;
+            if (!nextFrontmatter.title?.trim()) {
+                nextFrontmatter.title = inferTitle(path, body);
+                addedTitle = true;
+            }
+            if (!nextFrontmatter.summary?.trim()) {
+                const summary = inferSummary(body);
+                nextFrontmatter.summary = summary.text;
+                addedSummary = true;
+                if (summary.shouldMarkAutostub && nextFrontmatter.autostub !== true && nextFrontmatter.autostub === undefined) {
+                    nextFrontmatter.autostub = true;
+                    addedAutostub = true;
+                }
+            }
+            if (!nextFrontmatter.updated?.trim()) {
+                nextFrontmatter.updated = formatDate(statSync(resolveWikiRelativePath(path)).mtime);
+                addedUpdated = true;
+            }
+            const details = [
+                ...(addedTitle ? ["title"] : []),
+                ...(addedSummary ? ["summary"] : []),
+                ...(addedUpdated ? ["updated"] : []),
+                ...(addedAutostub ? ["autostub"] : []),
+            ];
+            if (details.length > 0) {
+                changes.push({ rule: "frontmatter-backfill", details });
+            }
+        }
+        if (enabledFixes.has("tag-normalize") && nextFrontmatter.tags?.length) {
+            const normalizedTags = [];
+            const details = [];
+            const unknownTags = [];
+            for (const tag of nextFrontmatter.tags) {
+                const normalized = canonicalTags.get(normalizeTagKey(tag));
+                if (normalized) {
+                    normalizedTags.push(normalized);
+                    if (normalized !== tag) {
+                        details.push(`${tag} -> ${normalized}`);
+                    }
+                }
+                else {
+                    normalizedTags.push(tag);
+                    unknownTags.push(tag);
+                }
+            }
+            if (details.length > 0) {
+                nextFrontmatter.tags = normalizedTags;
+                changes.push({ rule: "tag-normalize", details });
+            }
+            unknownTagsForFile = uniqueStrings(unknownTags);
+        }
+        if (enabledFixes.has("autostub-mark") && nextFrontmatter.autostub !== true && isStubBody(body)) {
+            nextFrontmatter.autostub = true;
+            changes.push({ rule: "autostub-mark", details: ["autostub"] });
+        }
+        if (changes.length === 0 && unknownTagsForFile.length === 0) {
+            continue;
+        }
+        const fileReport = {
+            path,
+            changes,
+        };
+        if (unknownTagsForFile.length > 0) {
+            fileReport.unknownTags = unknownTagsForFile;
+        }
+        reports.push(fileReport);
+        if (changes.length === 0) {
+            continue;
+        }
+        changedFiles += 1;
+        const nextContent = renderPage(nextFrontmatter, body);
+        if (dryRun) {
+            diffs.push(renderUnifiedDiff(path, content, nextContent));
+            continue;
+        }
+        writePage(path, nextContent);
+        for (const change of changes) {
+            const logType = logTypeForRule(change.rule);
+            if (logType) {
+                options.logAction?.(logType, path);
+            }
+        }
+    }
+    return {
+        dryRun,
+        scannedFiles: pages.length,
+        changedFiles,
+        files: reports,
+        diff: dryRun ? diffs.join("\n") : "",
+    };
+}
+function cloneFrontmatter(frontmatter) {
+    return {
+        ...frontmatter,
+        tags: frontmatter.tags ? [...frontmatter.tags] : undefined,
+        contradictions: frontmatter.contradictions ? [...frontmatter.contradictions] : undefined,
+        related: frontmatter.related ? [...frontmatter.related] : undefined,
+        metadata: { ...frontmatter.metadata },
+    };
+}
+function inferTitle(path, body) {
+    const heading = firstHeading(body);
+    if (heading) {
+        return stripMarkdown(heading);
+    }
+    return titleFromPath(path);
+}
+function inferSummary(body) {
+    const lines = body.split("\n");
+    const headingIndex = lines.findIndex((line) => /^#\s+/.test(line.trim()));
+    const startIndex = headingIndex >= 0 ? headingIndex + 1 : 0;
+    const paragraph = [];
+    for (let index = startIndex; index < lines.length; index += 1) {
+        const line = lines[index]?.trim() ?? "";
+        if (!line) {
+            if (paragraph.length > 0)
+                break;
+            continue;
+        }
+        if (line.startsWith("#")) {
+            if (paragraph.length > 0)
+                break;
+            continue;
+        }
+        paragraph.push(line);
+    }
+    const summary = stripMarkdown(paragraph.join(" ")).trim();
+    if (!summary) {
+        return {
+            text: "(no summary yet)",
+            shouldMarkAutostub: true,
+        };
+    }
+    return {
+        text: truncate(summary, 200),
+        shouldMarkAutostub: false,
+    };
+}
+function firstHeading(body) {
+    for (const rawLine of body.split("\n")) {
+        const match = rawLine.trim().match(/^#\s+(.+)$/);
+        if (match) {
+            return match[1].trim();
+        }
+    }
+    return undefined;
+}
+function titleFromPath(path) {
+    const file = basename(path, ".md");
+    const stem = file === "index" ? basename(dirname(path)) : file;
+    return stem
+        .split(/[-_]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+}
+function stripMarkdown(value) {
+    return value
+        .replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1")
+        .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+        .replace(/[`*_~>#]/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function truncate(value, maxLength) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return value.slice(0, maxLength).trimEnd();
+}
+function formatDate(date) {
+    return date.toISOString().slice(0, 10);
+}
+function normalizeTagKey(tag) {
+    return tag.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+function isStubBody(body) {
+    const meaningfulLines = body
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+    return meaningfulLines.length < 10;
+}
+function renderPage(frontmatter, body) {
+    const lines = ["---"];
+    for (const field of KNOWN_FIELD_ORDER) {
+        const value = frontmatter[field];
+        if (value === undefined)
+            continue;
+        lines.push(formatFrontmatterLine(field, value));
+    }
+    for (const [key, value] of Object.entries(frontmatter.metadata)) {
+        lines.push(formatFrontmatterLine(key, value));
+    }
+    lines.push("---");
+    const normalizedBody = body.replace(/^\n+/, "");
+    if (!normalizedBody) {
+        return `${lines.join("\n")}\n`;
+    }
+    return `${lines.join("\n")}\n\n${normalizedBody.endsWith("\n") ? normalizedBody : `${normalizedBody}\n`}`;
+}
+function formatFrontmatterLine(key, value) {
+    if (Array.isArray(value)) {
+        return `${key}: [${value.map(formatInlineValue).join(", ")}]`;
+    }
+    if (typeof value === "boolean") {
+        return `${key}: ${value ? "true" : "false"}`;
+    }
+    return `${key}: ${formatScalar(value)}`;
+}
+function formatInlineValue(value) {
+    return /^[A-Za-z0-9_./()-]+$/.test(value) ? value : formatScalar(value);
+}
+function formatScalar(value) {
+    if (value === "" || /[:#[\]{}'",]|^\s|\s$/.test(value)) {
+        return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    }
+    return value;
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function renderUnifiedDiff(path, before, after) {
+    const beforeLines = splitLines(before);
+    const afterLines = splitLines(after);
+    const beforeCount = beforeLines.length;
+    const afterCount = afterLines.length;
+    const diffLines = [
+        `--- a/${path}`,
+        `+++ b/${path}`,
+        `@@ -1,${beforeCount} +1,${afterCount} @@`,
+        ...beforeLines.map((line) => `-${line}`),
+        ...afterLines.map((line) => `+${line}`),
+    ];
+    return diffLines.join("\n");
+}
+function splitLines(content) {
+    return content.endsWith("\n")
+        ? content.slice(0, -1).split("\n")
+        : content.split("\n");
+}
+function compileGlob(pattern) {
+    let regex = "^";
+    for (let index = 0; index < pattern.length; index += 1) {
+        const char = pattern[index];
+        const next = pattern[index + 1];
+        if (char === "*" && next === "*") {
+            regex += ".*";
+            index += 1;
+            continue;
+        }
+        if (char === "*") {
+            regex += "[^/]*";
+            continue;
+        }
+        if (char === "?") {
+            regex += "[^/]";
+            continue;
+        }
+        regex += escapeRegex(char);
+    }
+    regex += "$";
+    return new RegExp(regex);
+}
+function escapeRegex(value) {
+    return value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+}
+function logTypeForRule(rule) {
+    switch (rule) {
+        case "frontmatter-backfill":
+            return "fix-frontmatter";
+        case "tag-normalize":
+            return "fix-tags";
+        case "autostub-mark":
+            return "fix-autostub";
+        default:
+            return undefined;
+    }
+}
+function isFixablePage(path) {
+    return !path.startsWith("pages/_meta/") && path !== "pages/index.md";
+}
+//# sourceMappingURL=fix.js.map

package/dist/wiki/fix.test.js

@@ -0,0 +1,350 @@
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync, utimesSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+const repoRoot = process.cwd();
+const sandboxRoot = join(repoRoot, ".test-work", `wiki-fix-${process.pid}`);
+process.env.CHAPTERHOUSE_HOME = sandboxRoot;
+process.env.CHAPTERHOUSE_AGENT_NAME = "wiki-fix-test-agent";
+async function loadModules() {
+    const nonce = `${Date.now()}-${Math.random()}`;
+    const fix = await import(new URL(`./fix.js?case=${nonce}`, import.meta.url).href);
+    const wikiFs = await import(new URL(`./fs.js?case=${nonce}`, import.meta.url).href);
+    return { fix, wikiFs };
+}
+function resetSandbox() {
+    mkdirSync(join(repoRoot, ".test-work"), { recursive: true });
+    rmSync(sandboxRoot, { recursive: true, force: true });
+}
+function wikiPath(relativePath) {
+    return join(sandboxRoot, ".chapterhouse", "wiki", ...relativePath.split("/"));
+}
+function setMtime(relativePath, isoDate) {
+    const timestamp = new Date(`${isoDate}T12:00:00.000Z`);
+    utimesSync(wikiPath(relativePath), timestamp, timestamp);
+}
+test.beforeEach(() => {
+    resetSandbox();
+});
+test.after(() => {
+    rmSync(sandboxRoot, { recursive: true, force: true });
+});
+test("fixWiki dry-run previews frontmatter backfills, tag normalization, and autostub marking without writing files", async () => {
+    const { fix, wikiFs } = await loadModules();
+    wikiFs.ensureWikiStructure();
+    wikiFs.writePage("pages/projects/alpha/index.md", `# Alpha Project
+
+Alpha project **launch** notes for the team.
+
+## Details
+
+One
+Two
+Three
+Four
+Five
+Six
+Seven
+Eight
+`);
+    wikiFs.writePage("pages/projects/empty/index.md", `# Empty Page
+`);
+    wikiFs.writePage("pages/projects/bravo/index.md", `---
+title: Bravo
+summary: Bravo deployment notes
+updated: 2026-05-10
+tags: [Run Book, Mystery]
+---
+
+# Bravo
+
+Deployment notes with enough body to avoid the stub marker.
+
+## Steps
+
+One
+Two
+Three
+Four
+Five
+Six
+Seven
+Eight
+`);
+    wikiFs.writePage("pages/projects/stub/index.md", `---
+title: Stub Page
+summary: Tiny page
+updated: 2026-05-10
+---
+
+# Stub Page
+
+Tiny.
+`);
+    wikiFs.writePage("pages/_meta/taxonomy.md", `## Process
+- runbook
+`);
+    setMtime("pages/projects/alpha/index.md", "2026-01-02");
+    setMtime("pages/projects/empty/index.md", "2026-01-03");
+    const beforeAlpha = wikiFs.readPage("pages/projects/alpha/index.md");
+    const beforeEmpty = wikiFs.readPage("pages/projects/empty/index.md");
+    const beforeBravo = wikiFs.readPage("pages/projects/bravo/index.md");
+    const beforeStub = wikiFs.readPage("pages/projects/stub/index.md");
+    const report = fix.fixWiki({ dryRun: true });
+    assert.equal(report.dryRun, true);
+    assert.equal(report.changedFiles, 4);
+    const alpha = report.files.find((entry) => entry.path === "pages/projects/alpha/index.md");
+    const empty = report.files.find((entry) => entry.path === "pages/projects/empty/index.md");
+    const bravo = report.files.find((entry) => entry.path === "pages/projects/bravo/index.md");
+    const stub = report.files.find((entry) => entry.path === "pages/projects/stub/index.md");
+    assert.deepEqual(alpha?.changes, [
+        { rule: "frontmatter-backfill", details: ["title", "summary", "updated"] },
+    ]);
+    assert.deepEqual(empty?.changes, [
+        { rule: "frontmatter-backfill", details: ["title", "summary", "updated", "autostub"] },
+    ]);
+    assert.deepEqual(bravo?.changes, [
+        { rule: "tag-normalize", details: ["Run Book -> runbook"] },
+    ]);
+    assert.deepEqual(bravo?.unknownTags, ["Mystery"]);
+    assert.deepEqual(stub?.changes, [
+        { rule: "autostub-mark", details: ["autostub"] },
+    ]);
+    assert.match(report.diff, /--- a\/pages\/projects\/alpha\/index\.md/);
+    assert.match(report.diff, /title: Alpha Project/);
+    assert.match(report.diff, /summary: Alpha project launch notes for the team\./);
+    assert.match(report.diff, /updated: 2026-01-02/);
+    assert.match(report.diff, /summary: \(no summary yet\)/);
+    assert.match(report.diff, /tags: \[runbook, Mystery\]/);
+    assert.match(report.diff, /autostub: true/);
+    assert.equal(wikiFs.readPage("pages/projects/alpha/index.md"), beforeAlpha);
+    assert.equal(wikiFs.readPage("pages/projects/empty/index.md"), beforeEmpty);
+    assert.equal(wikiFs.readPage("pages/projects/bravo/index.md"), beforeBravo);
+    assert.equal(wikiFs.readPage("pages/projects/stub/index.md"), beforeStub);
+});
+test("fixWiki applies changes, logs each applied rule, and is idempotent on the second run", async () => {
+    const { fix, wikiFs } = await loadModules();
+    wikiFs.ensureWikiStructure();
+    wikiFs.writePage("pages/projects/alpha/index.md", `# Alpha Project
+
+Alpha project launch notes for the team.
+
+## Details
+
+One
+Two
+Three
+Four
+Five
+Six
+Seven
+Eight
+`);
+    wikiFs.writePage("pages/projects/bravo/index.md", `---
+title: Bravo
+summary: Bravo deployment notes
+updated: 2026-05-10
+tags: [Run Book]
+---
+
+# Bravo
+
+Deployment notes with enough body to avoid the stub marker.
+
+## Steps
+
+One
+Two
+Three
+Four
+Five
+Six
+Seven
+Eight
+`);
+    wikiFs.writePage("pages/projects/stub/index.md", `---
+title: Stub Page
+summary: Tiny page
+updated: 2026-05-10
+---
+
+# Stub Page
+
+Tiny.
+`);
+    wikiFs.writePage("pages/_meta/taxonomy.md", `## Process
+- runbook
+`);
+    setMtime("pages/projects/alpha/index.md", "2026-01-02");
+    const logEntries = [];
+    const firstReport = fix.fixWiki({
+        dryRun: false,
+        logAction: (type, path) => logEntries.push(`${type}:${path}`),
+    });
+    assert.equal(firstReport.dryRun, false);
+    assert.equal(firstReport.changedFiles, 3);
+    assert.equal(firstReport.diff, "");
+    assert.match(wikiFs.readPage("pages/projects/alpha/index.md") ?? "", /title: Alpha Project/);
+    assert.match(wikiFs.readPage("pages/projects/alpha/index.md") ?? "", /updated: 2026-01-02/);
+    assert.match(wikiFs.readPage("pages/projects/bravo/index.md") ?? "", /tags: \[runbook\]/);
+    assert.match(wikiFs.readPage("pages/projects/stub/index.md") ?? "", /autostub: true/);
+    assert.deepEqual(logEntries, [
+        "fix-frontmatter:pages/projects/alpha/index.md",
+        "fix-tags:pages/projects/bravo/index.md",
+        "fix-autostub:pages/projects/stub/index.md",
+    ]);
+    const secondReport = fix.fixWiki({
+        dryRun: false,
+        logAction: (type, path) => logEntries.push(`${type}:${path}`),
+    });
+    assert.equal(secondReport.changedFiles, 0);
+    assert.equal(secondReport.diff, "");
+    assert.deepEqual(logEntries, [
+        "fix-frontmatter:pages/projects/alpha/index.md",
+        "fix-tags:pages/projects/bravo/index.md",
+        "fix-autostub:pages/projects/stub/index.md",
+    ]);
+});
+test("fixWiki respects fix toggles, path globs, autofix false, and pages/_meta skips", async () => {
+    const { fix, wikiFs } = await loadModules();
+    wikiFs.ensureWikiStructure();
+    wikiFs.writePage("pages/projects/match/index.md", `---
+title: Match
+summary: Match notes
+updated: 2026-05-10
+tags: [Run Book]
+---
+
+# Match
+
+Long enough body.
+
+## Details
+
+One
+Two
+Three
+Four
+Five
+Six
+Seven
+Eight
+`);
+    wikiFs.writePage("pages/projects/skip/index.md", `---
+title: Skip
+summary: Skip notes
+updated: 2026-05-10
+tags: [Run Book]
+autofix: false
+---
+
+# Skip
+
+Long enough body.
+
+## Details
+
+One
+Two
+Three
+Four
+Five
+Six
+Seven
+Eight
+`);
+    wikiFs.writePage("pages/people/alice/index.md", `---
+title: Alice
+summary: Alice notes
+updated: 2026-05-10
+tags: [Run Book]
+---
+
+# Alice
+
+Long enough body.
+
+## Details
+
+One
+Two
+Three
+Four
+Five
+Six
+Seven
+Eight
+`);
+    wikiFs.writePage("pages/_meta/manual.md", `---
+title: Manual
+summary: System page
+updated: 2026-05-10
+tags: [Run Book]
+---
+
+# Manual
+`);
+    wikiFs.writePage("pages/_meta/taxonomy.md", `## Process
+- runbook
+`);
+    const beforeSkip = wikiFs.readPage("pages/projects/skip/index.md");
+    const beforePeople = wikiFs.readPage("pages/people/alice/index.md");
+    const beforeMeta = wikiFs.readPage("pages/_meta/manual.md");
+    const report = fix.fixWiki({
+        dryRun: true,
+        fixes: ["tag-normalize"],
+        pathGlob: "pages/projects/**",
+    });
+    assert.equal(report.changedFiles, 1);
+    assert.deepEqual(report.files.map((entry) => entry.path), ["pages/projects/match/index.md"]);
+    assert.deepEqual(report.files[0]?.changes.map((change) => change.rule), ["tag-normalize"]);
+    assert.doesNotMatch(report.diff, /pages\/projects\/skip\/index\.md/);
+    assert.doesNotMatch(report.diff, /pages\/people\/alice\/index\.md/);
+    assert.doesNotMatch(report.diff, /pages\/_meta\/manual\.md/);
+    assert.equal(wikiFs.readPage("pages/projects/skip/index.md"), beforeSkip);
+    assert.equal(wikiFs.readPage("pages/people/alice/index.md"), beforePeople);
+    assert.equal(wikiFs.readPage("pages/_meta/manual.md"), beforeMeta);
+});
+test("fixWiki flags unmatched tags even when there is nothing to rewrite", async () => {
+    const { fix, wikiFs } = await loadModules();
+    wikiFs.ensureWikiStructure();
+    wikiFs.writePage("pages/projects/mystery/index.md", `---
+title: Mystery
+summary: Mystery notes
+updated: 2026-05-10
+tags: [Mystery]
+---
+
+# Mystery
+
+Long enough body.
+
+## Details
+
+One
+Two
+Three
+Four
+Five
+Six
+Seven
+Eight
+`);
+    wikiFs.writePage("pages/_meta/taxonomy.md", `## Process
+- runbook
+`);
+    const report = fix.fixWiki({
+        dryRun: true,
+        fixes: ["tag-normalize"],
+    });
+    assert.equal(report.changedFiles, 0);
+    assert.equal(report.diff, "");
+    assert.deepEqual(report.files, [
+        {
+            path: "pages/projects/mystery/index.md",
+            changes: [],
+            unknownTags: ["Mystery"],
+        },
+    ]);
+});
+//# sourceMappingURL=fix.test.js.map