chapterhouse 0.3.15 → 0.3.17

package/dist/wiki/index-manager.js

@@ -5,9 +5,11 @@ import { existsSync, statSync } from "fs";
 import { join } from "path";
 import { WIKI_DIR } from "../paths.js";
 import { readIndexFile, writeIndexFile, listPages, readPage } from "./fs.js";
+import { parseWikiFrontmatter } from "./frontmatter.js";
 import { normalizeWikiPath } from "./path-utils.js";
 import { entityCategories, FLAT_CATEGORIES } from "./topic-structure.js";
 const INDEX_PATH = join(WIKI_DIR, "index.md");
+const ACTION_LOG_PAGE_RE = /^pages\/_meta\/log(?:-\d{4})?\.md$/;
 // mtime-based cache so per-message context injection doesn't re-parse on every turn.
 let cache;
 function invalidateCache() {
@@ -73,7 +75,7 @@ export function parseIndex() {
     }
     // Self-heal: if index is empty/corrupted but pages exist on disk, rebuild from disk.
     if (entries.length === 0) {
-        const pages = listPages();
+        const pages = listPages().filter((path) => !isActionLogPage(path));
         if (pages.length > 0) {
             const rebuilt = rebuildIndexFromPages();
             cache = { mtimeMs, size, entries: rebuilt };
@@ -83,43 +85,20 @@ export function parseIndex() {
     cache = { mtimeMs, size, entries };
     return entries;
 }
-/** Parse YAML frontmatter (very simple — supports key: value and key: [a, b]). */
-function parseFrontmatter(content) {
-    const m = content.match(/^---\s*\n([\s\S]*?)\n---/);
-    if (!m)
-        return {};
-    const out = {};
-    for (const line of m[1].split("\n")) {
-        const idx = line.indexOf(":");
-        if (idx <= 0)
-            continue;
-        const key = line.slice(0, idx).trim();
-        let value = line.slice(idx + 1).trim();
-        if (typeof value === "string" && value.startsWith("[") && value.endsWith("]")) {
-            value = value.slice(1, -1).split(",").map((s) => s.trim()).filter(Boolean);
-        }
-        else if (typeof value === "string") {
-            value = value.replace(/^['"]|['"]$/g, "");
-        }
-        out[key] = value;
-    }
-    return out;
-}
 /** Build (or refresh) an IndexEntry by reading the page from disk. */
 export function buildIndexEntryForPage(path, fallback) {
     const normalizedPath = normalizeWikiPath(path);
     const content = readPage(normalizedPath);
     if (!content)
         return undefined;
-    const fm = parseFrontmatter(content);
-    const title = (typeof fm.title === "string" && fm.title) || fallback?.title || basenameTitle(normalizedPath);
-    const tags = Array.isArray(fm.tags) ? fm.tags : (fallback?.tags ?? []);
-    const updated = (typeof fm.updated === "string" && fm.updated) || fallback?.updated;
-    // Summary heuristic: existing summary if provided, else first non-frontmatter
-    // non-heading content line trimmed to 160 chars.
-    let summary = fallback?.summary?.trim() || "";
+    const { parsed: fm, body } = parseWikiFrontmatter(content);
+    const title = fm.title || fallback?.title || basenameTitle(normalizedPath);
+    const tags = fm.tags ?? fallback?.tags ?? [];
+    const updated = fm.updated || fallback?.updated;
+    // Compliant pages treat frontmatter summary as canonical. Legacy pages fall back
+    // to the first non-frontmatter, non-heading content line.
+    let summary = fm.summary?.trim() || fallback?.summary?.trim() || "";
     if (!summary) {
-        const body = content.replace(/^---[\s\S]*?---\s*/, "");
         for (const raw of body.split("\n")) {
             const line = raw.trim();
             if (!line || line.startsWith("#") || line.startsWith("<!--"))
@@ -149,7 +128,7 @@ function basenameTitle(path) {
 }
 /** Rebuild every index entry from on-disk pages. Preserves section if known. */
 export function rebuildIndexFromPages() {
-    const pages = listPages();
+    const pages = listPages().filter((path) => !isActionLogPage(path));
     const previous = new Map();
     // Try to keep section assignments by re-parsing the (possibly-corrupted) index without recursion.
     try {
@@ -288,6 +267,9 @@ function writeIndexInternal(entries) {
     }
     writeIndexFile(lines.join("\n"));
 }
+function isActionLogPage(path) {
+    return ACTION_LOG_PAGE_RE.test(path);
+}
 /** Add or update an entry in the index. Upserts by path. */
 export function addToIndex(entry) {
     const normalizedEntry = { ...entry, path: normalizeWikiPath(entry.path) };

package/dist/wiki/index-manager.test.js

@@ -43,14 +43,14 @@ test("parseIndex reads sections, summaries, tags, and updated dates", async () =
         },
     ]);
 });
-test("buildIndexEntryForPage derives title, metadata, and a trimmed summary from page content", async () => {
+test("buildIndexEntryForPage treats frontmatter summary as the canonical index summary", async () => {
     const { indexManager, wikiFs } = await loadModules();
-    wikiFs.writePage("pages/shared/runbooks/deploy.md", `---\ntitle: Deploy Runbook\ntags: [ops, release]\nupdated: 2026-05-04\n---\n\n# Deploy\n\n${"Deploy carefully ".repeat(20)}\n`);
+    wikiFs.writePage("pages/shared/runbooks/deploy.md", `---\ntitle: Deploy Runbook\nsummary: Production deployment checklist\ntags: [ops, release]\nupdated: 2026-05-04\n---\n\n# Deploy\n\n${"Deploy carefully ".repeat(20)}\n`);
     const entry = indexManager.buildIndexEntryForPage("pages/shared/runbooks/deploy.md");
     assert.deepEqual(entry, {
         path: "pages/shared/runbooks/deploy.md",
         title: "Deploy Runbook",
-        summary: `${("Deploy carefully ".repeat(20)).trim().slice(0, 157)}…`,
+        summary: "Production deployment checklist",
         section: "Knowledge",
         tags: ["ops", "release"],
         updated: "2026-05-04",

package/dist/wiki/lint.js

@@ -0,0 +1,424 @@
+import { accessSync, constants as fsConstants, existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { config } from "../config.js";
+import { WIKI_DIR } from "../paths.js";
+import { parseIndex } from "./index-manager.js";
+import { listPages, listSources, readPage } from "./fs.js";
+import { parseWikiFrontmatter, validateWikiFrontmatter } from "./frontmatter.js";
+import { ACTION_LOG_PATH } from "./log-manager.js";
+import { TAXONOMY_PATH, loadTaxonomy, parseTaxonomyTags } from "./taxonomy.js";
+const DEFAULT_STALE_OVERRIDES = {
+    decisions: "never",
+    "feature-ideas": 90,
+    conversations: "never",
+    default: 180,
+};
+const DEFAULT_OPTIONS = {
+    requireUpdated: true,
+    requireFrontmatter: true,
+    disallowSkippedHeadingLevels: true,
+    pageWarnLines: 300,
+    pageErrorLines: 800,
+    prematureBodyChars: 100,
+    autostubExtraLines: 10,
+    reportDeadTags: true,
+    surfaceContestedFirst: true,
+    staleOverrides: DEFAULT_STALE_OVERRIDES,
+};
+const SPECIAL_META_PAGE_RE = /^pages\/_meta\/(?:taxonomy|log(?:-\d{4})?)\.md$/;
+const LEGACY_DATE_STAMP_RE = /^(?:Logged|Updated):\s*\d{4}-\d{2}-\d{2}\b/m;
+export function lintWiki(options = {}) {
+    const staleOverrides = {
+        ...DEFAULT_STALE_OVERRIDES,
+        ...(options.staleOverrides ?? {}),
+    };
+    const resolved = {
+        ...DEFAULT_OPTIONS,
+        ...options,
+        staleOverrides,
+    };
+    const actionLogIssues = lintActionLog();
+    const indexEntries = parseIndex();
+    const pages = listPages().filter((path) => path !== ACTION_LOG_PATH).sort();
+    const sources = listSources();
+    const indexPaths = new Set(indexEntries.map((entry) => entry.path));
+    const issues = [...actionLogIssues];
+    let allowedTags = [];
+    try {
+        allowedTags = loadTaxonomy();
+    }
+    catch (error) {
+        issues.push({
+            rule: "frontmatter-shape",
+            severity: "error",
+            path: TAXONOMY_PATH,
+            message: error instanceof Error ? error.message : String(error),
+            suggestion: "Fix pages/_meta/taxonomy.md so it only contains '## Group' headings and '- tag' bullets.",
+        });
+    }
+    for (const path of pages.filter((page) => !indexPaths.has(page) && !isSpecialMetaPage(page))) {
+        issues.push({
+            rule: "orphan-page",
+            severity: "warning",
+            path,
+            message: "Page exists on disk but is missing from the wiki index.",
+            suggestion: "Rebuild the index or add the page entry explicitly.",
+        });
+    }
+    for (const entry of indexEntries.filter((candidate) => !readPage(candidate.path))) {
+        issues.push({
+            rule: "missing-page",
+            severity: "warning",
+            path: entry.path,
+            message: `Index entry points to a page that does not exist on disk: ${entry.title}`,
+            suggestion: "Delete the stale index entry or restore the page.",
+        });
+    }
+    issues.push(...lintIndexIntegrity(pages));
+    for (const path of pages) {
+        const content = readPage(path);
+        if (!content)
+            continue;
+        const { parsed, body } = parseWikiFrontmatter(content);
+        const autostub = parsed.autostub === true;
+        const specialMetaPage = isSpecialMetaPage(path);
+        if (resolved.surfaceContestedFirst && (parsed.contested === true || parsed.confidence === "low")) {
+            const state = parsed.contested === true && parsed.confidence === "low"
+                ? "contested and low confidence"
+                : parsed.contested === true
+                    ? "contested"
+                    : "low confidence";
+            issues.push({
+                rule: "contested-review",
+                severity: "info",
+                path,
+                message: `Page is marked ${state} and should be reviewed first.`,
+            });
+        }
+        if (resolved.requireFrontmatter && !specialMetaPage) {
+            const validation = validateWikiFrontmatter(content, allowedTags.length > 0 ? { allowedTags } : undefined);
+            if (!validation.valid) {
+                issues.push({
+                    rule: "frontmatter-shape",
+                    severity: "error",
+                    path,
+                    message: validation.errors.map((error) => error.message).join(" "),
+                    suggestion: "Rewrite the page frontmatter to match the canonical wiki shape before the next update.",
+                });
+            }
+        }
+        if (resolved.requireUpdated && !autostub && !specialMetaPage && !parsed.updated && !LEGACY_DATE_STAMP_RE.test(body)) {
+            issues.push({
+                rule: "missing-updated",
+                severity: "warning",
+                path,
+                message: "Page does not declare an updated date stamp.",
+                suggestion: "Add 'updated: YYYY-MM-DD' to the frontmatter.",
+            });
+        }
+        const staleThreshold = staleThresholdForPath(path, resolved.staleOverrides);
+        if (!autostub && staleThreshold !== "never" && isPageOlderThan(path, staleThreshold)) {
+            issues.push({
+                rule: "stale-page",
+                severity: "warning",
+                path,
+                message: `Page has not been touched in more than ${staleThreshold} days.`,
+                suggestion: "Refresh the page or archive it if the information is no longer active.",
+            });
+        }
+        if (!autostub && !specialMetaPage && resolved.disallowSkippedHeadingLevels) {
+            const headingIssue = lintHeadingDepth(path, body);
+            if (headingIssue)
+                issues.push(headingIssue);
+        }
+        if (isDecisionMisfile(path)) {
+            issues.push({
+                rule: "decision-misfile",
+                severity: "error",
+                path,
+                message: "decisions.md must live under an entity directory.",
+                suggestion: "Move this page to pages/<entity-category>/<topic>/decisions.md.",
+            });
+        }
+        if (!autostub && !specialMetaPage) {
+            const lineCount = content.split("\n").length;
+            if (lineCount > resolved.pageErrorLines) {
+                issues.push({
+                    rule: "page-size",
+                    severity: "error",
+                    path,
+                    message: `Page is ${lineCount} lines long, which exceeds the ${resolved.pageErrorLines}-line error threshold.`,
+                    suggestion: "Split the page into focused sub-pages or archive older material.",
+                });
+            }
+            else if (lineCount > resolved.pageWarnLines) {
+                issues.push({
+                    rule: "page-size",
+                    severity: "warning",
+                    path,
+                    message: `Page is ${lineCount} lines long, which exceeds the ${resolved.pageWarnLines}-line warning threshold.`,
+                    suggestion: "Consider splitting this page before it becomes unwieldy.",
+                });
+            }
+        }
+        if (!autostub && !specialMetaPage && bodyVisibleCharCount(body) <= resolved.prematureBodyChars) {
+            issues.push({
+                rule: "premature-page",
+                severity: "info",
+                path,
+                message: `Page body is too small to justify its own page (${bodyVisibleCharCount(body)} chars).`,
+                suggestion: "Fold the content into a parent page until there is enough material to stand alone.",
+            });
+        }
+        if (autostub && autostubExtraLines(body) > resolved.autostubExtraLines) {
+            issues.push({
+                rule: "autostub-not-flipped",
+                severity: "info",
+                path,
+                message: "Page has grown past stub size but still declares autostub: true.",
+                suggestion: "Remove autostub: true once the page becomes a real page.",
+            });
+        }
+    }
+    if (resolved.reportDeadTags) {
+        issues.push(...lintDeadTaxonomyEntries(pages));
+    }
+    return {
+        pageCount: pages.length,
+        sourceCount: sources.length,
+        issues: sortIssues(issues),
+    };
+}
+export function renderWikiLintReport(report) {
+    const sections = [
+        `Wiki health report (${report.pageCount} pages, ${report.sourceCount} sources):`,
+    ];
+    if (report.issues.length === 0) {
+        sections.push("\n✅ No issues found. Index and pages are in sync.");
+        sections.push("\n**Suggestions**: Look for pages that should link to each other, topics mentioned but lacking their own page, and stale content that needs updating.");
+        return sections.join("\n");
+    }
+    const contested = report.issues.filter((issue) => issue.rule === "contested-review");
+    const general = report.issues.filter((issue) => issue.rule !== "contested-review");
+    if (contested.length > 0) {
+        sections.push("\n**Review first**:");
+        for (const issue of contested) {
+            sections.push(formatIssueLine(issue));
+        }
+    }
+    if (general.length > 0) {
+        sections.push("\n**Issues**:");
+        for (const issue of general) {
+            sections.push(formatIssueLine(issue));
+        }
+    }
+    sections.push("\n**Suggestions**: Look for pages that should link to each other, topics mentioned but lacking their own page, and stale content that needs updating.");
+    return sections.join("\n");
+}
+function lintIndexIntegrity(pages) {
+    const issues = [];
+    const entityCategories = new Set(config.wikiEntityCategories);
+    const dirsWithFacets = new Set();
+    const dirsWithIndex = new Set();
+    for (const path of pages) {
+        const match = path.match(/^pages\/([^/]+)\/([^/]+)\/([^/]+)\.md$/);
+        if (!match)
+            continue;
+        const [, category, topic, page] = match;
+        if (!entityCategories.has(category))
+            continue;
+        const dirPath = `pages/${category}/${topic}`;
+        if (page === "index") {
+            dirsWithIndex.add(dirPath);
+        }
+        else {
+            dirsWithFacets.add(dirPath);
+        }
+    }
+    for (const dirPath of [...dirsWithFacets].sort()) {
+        if (!dirsWithIndex.has(dirPath)) {
+            issues.push({
+                rule: "index-integrity",
+                severity: "error",
+                path: dirPath,
+                message: "Entity directory has facet pages but no index.md overview page.",
+                suggestion: `Add ${dirPath}/index.md so the topic has a canonical overview page.`,
+            });
+        }
+    }
+    return issues;
+}
+function lintHeadingDepth(path, body) {
+    const headings = body
+        .split("\n")
+        .map((line) => line.match(/^(#{1,6})\s+(.+)$/))
+        .filter((match) => match !== null);
+    if (headings.length === 0)
+        return undefined;
+    const firstLevel = headings[0][1].length;
+    if (firstLevel !== 1) {
+        return {
+            rule: "heading-depth",
+            severity: "warning",
+            path,
+            message: "Page headings must start with a single '#' title heading.",
+            suggestion: "Start the page with '# Title' before any deeper sections.",
+        };
+    }
+    let previousLevel = firstLevel;
+    for (const heading of headings.slice(1)) {
+        const level = heading[1].length;
+        if (level > previousLevel + 1) {
+            return {
+                rule: "heading-depth",
+                severity: "warning",
+                path,
+                message: `Heading depth skips from h${previousLevel} to h${level}.`,
+                suggestion: "Add the missing intermediate heading level or flatten the structure.",
+            };
+        }
+        previousLevel = level;
+    }
+    return undefined;
+}
+function lintDeadTaxonomyEntries(pages) {
+    const taxonomyContent = readPage(TAXONOMY_PATH);
+    if (!taxonomyContent) {
+        return [];
+    }
+    let overrideTags;
+    try {
+        overrideTags = parseTaxonomyTags(taxonomyContent);
+    }
+    catch {
+        return [];
+    }
+    const usedTags = new Set();
+    for (const path of pages) {
+        const content = readPage(path);
+        if (!content)
+            continue;
+        const { parsed } = parseWikiFrontmatter(content);
+        for (const tag of parsed.tags ?? []) {
+            usedTags.add(tag.toLowerCase());
+        }
+    }
+    return overrideTags
+        .filter((tag) => !usedTags.has(tag.toLowerCase()))
+        .sort()
+        .map((tag) => ({
+        rule: "dead-taxonomy-entry",
+        severity: "info",
+        path: TAXONOMY_PATH,
+        message: `Tag '${tag}' is declared in the taxonomy but unused by any page.`,
+        suggestion: `Remove '${tag}' from pages/_meta/taxonomy.md or tag a page with it.`,
+    }));
+}
+function staleThresholdForPath(path, overrides) {
+    if (path.startsWith("pages/conversations/")) {
+        return overrides.conversations ?? "never";
+    }
+    if (path.endsWith("/decisions.md")) {
+        return overrides.decisions ?? "never";
+    }
+    if (path.endsWith("/feature-ideas.md")) {
+        return overrides["feature-ideas"] ?? 90;
+    }
+    return overrides.default ?? 180;
+}
+function isPageOlderThan(path, ageInDays) {
+    const stats = statSync(join(WIKI_DIR, path));
+    const ageMs = Date.now() - stats.mtime.getTime();
+    return ageMs > ageInDays * 24 * 60 * 60 * 1000;
+}
+function lintActionLog() {
+    const fullPath = join(WIKI_DIR, ACTION_LOG_PATH);
+    if (!existsSync(fullPath)) {
+        return [{
+                rule: "action-log",
+                severity: "error",
+                path: ACTION_LOG_PATH,
+                message: "The wiki action log is missing.",
+                suggestion: "Restore pages/_meta/log.md so wiki operations keep an append-only audit trail.",
+            }];
+    }
+    try {
+        const stats = statSync(fullPath);
+        if (!stats.isFile()) {
+            return [{
+                    rule: "action-log",
+                    severity: "error",
+                    path: ACTION_LOG_PATH,
+                    message: "The wiki action log path exists but is not a writable file.",
+                    suggestion: "Replace pages/_meta/log.md with a regular writable Markdown file.",
+                }];
+        }
+        accessSync(fullPath, fsConstants.W_OK);
+        return [];
+    }
+    catch (error) {
+        return [{
+                rule: "action-log",
+                severity: "error",
+                path: ACTION_LOG_PATH,
+                message: error instanceof Error
+                    ? `The wiki action log is not writable: ${error.message}`
+                    : "The wiki action log is not writable.",
+                suggestion: "Fix permissions on pages/_meta/log.md so wiki operations can append to it.",
+            }];
+    }
+}
+function isDecisionMisfile(path) {
+    if (!path.endsWith("/decisions.md")) {
+        return false;
+    }
+    return !config.wikiEntityCategories.some((category) => {
+        const expectedPrefix = `pages/${category}/`;
+        return path.startsWith(expectedPrefix) && path.split("/").length === 4;
+    });
+}
+function isSpecialMetaPage(path) {
+    return SPECIAL_META_PAGE_RE.test(path);
+}
+function bodyVisibleCharCount(body) {
+    const visible = body
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith("#"))
+        .join(" ")
+        .trim();
+    return visible.length;
+}
+function autostubExtraLines(body) {
+    const meaningfulLines = body
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+    return Math.max(0, meaningfulLines.length - 1);
+}
+function sortIssues(issues) {
+    const severityRank = {
+        error: 0,
+        warning: 1,
+        info: 2,
+    };
+    return [...issues].sort((left, right) => {
+        if (left.rule === "contested-review" && right.rule !== "contested-review")
+            return -1;
+        if (right.rule === "contested-review" && left.rule !== "contested-review")
+            return 1;
+        const severityDelta = severityRank[left.severity] - severityRank[right.severity];
+        if (severityDelta !== 0)
+            return severityDelta;
+        const pathDelta = (left.path ?? "").localeCompare(right.path ?? "");
+        if (pathDelta !== 0)
+            return pathDelta;
+        return left.rule.localeCompare(right.rule);
+    });
+}
+function formatIssueLine(issue) {
+    const path = issue.path ?? "-";
+    const suggestion = issue.suggestion ? `\n  suggestion: ${issue.suggestion}` : "";
+    return `- ${issue.severity} | ${issue.rule} | ${path} | ${issue.message}${suggestion}`;
+}
+//# sourceMappingURL=lint.js.map