chapterhouse 0.6.0 → 0.8.0

package/dist/wiki/lint.js

@@ -1,451 +0,0 @@
-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, validateProjectRulesFrontmatter, 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 validationOptions = allowedTags.length > 0 ? { allowedTags } : undefined;
-            if (isProjectRulesPage(path)) {
-                const validation = validateProjectRulesFrontmatter(content, validationOptions);
-                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.",
-                    });
-                }
-                for (const warning of validation.warnings) {
-                    issues.push({
-                        rule: warning.rule,
-                        severity: "warning",
-                        path,
-                        message: warning.message,
-                        suggestion: "Remove the unknown key or add it to the project-rules schema before relying on it.",
-                    });
-                }
-            }
-            else {
-                const validation = validateWikiFrontmatter(content, validationOptions);
-                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 isProjectRulesPage(path) {
-    return /^pages\/projects\/[^/]+\/rules\.md$/.test(path);
-}
-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