melchizedek-agents 0.9.0

package/dist/lib/wiki/lint.js

@@ -0,0 +1,267 @@
+/**
+ * lib/wiki/lint.ts — producer-side health checks for the bundle.
+ *
+ * WHY this file exists:
+ *   OKF consumers MUST tolerate broken links, missing indexes, unknown
+ *   fields — the spec is forgiving on purpose. A PRODUCER that leans on
+ *   that forgiveness rots: links dangle, pages orphan, indexes lag their
+ *   directories. This is Karpathy's "lint" operation from the LLM-wiki
+ *   pattern, run as code instead of vibes. It is also the gate every write
+ *   passes through: `wiki_save` refuses drafts whose errors would degrade
+ *   the bundle.
+ *
+ *   Severity doctrine:
+ *     error   — violates OKF conformance or the profile's hard rules;
+ *               blocks wiki_save and fails `wiki:build --check`.
+ *     warning — the bundle works but is decaying (broken link, orphan,
+ *               stale doc, index gap). Surfaced, never blocking.
+ *     info    — style guidance (relative links, unknown type).
+ *
+ *   The private-closure rule is the publishing invariant: documents outside
+ *   /private/ must never link into it, so exporting the bundle minus the
+ *   private subtree can never produce a dangling reference the producer
+ *   didn't choose. Extra `forbiddenPatterns` (names that must not appear in
+ *   public docs) are supplied BY THE CALLER — this public module does not
+ *   itself know any private vocabulary.
+ */
+import { posix } from 'node:path';
+import { CONCEPT_TYPES, isStale, LOG_ENTRY_RE, } from "./format.js";
+import { docsInDirectory, lookupTarget, resolveLinkTarget, } from "./vault.js";
+function report(findings) {
+    const errors = findings.filter((f) => f.severity === 'error').length;
+    const warnings = findings.filter((f) => f.severity === 'warning').length;
+    return { findings, errors, warnings, ok: errors === 0 };
+}
+function todayIso() {
+    return new Date().toISOString().slice(0, 10);
+}
+// ── Per-document rules ───────────────────────────────────────────────────────
+const KNOWN_TYPES = new Set(CONCEPT_TYPES);
+/**
+ * Rules that need only the document itself (+ the vault for link targets).
+ * Used both by lintVault and by the wiki_save gate on unsaved drafts.
+ */
+export function lintDoc(vault, doc, options = {}) {
+    const findings = [];
+    const today = options.today ?? todayIso();
+    for (const issue of doc.fmIssues) {
+        findings.push({
+            severity: 'error',
+            rule: 'frontmatter',
+            docPath: doc.bundlePath,
+            message: issue,
+        });
+    }
+    for (const wl of doc.parsed.wikilinks) {
+        findings.push({
+            severity: 'error',
+            rule: 'wikilink-syntax',
+            docPath: doc.bundlePath,
+            line: wl.line,
+            message: `[[${wl.target}]] is not an OKF link — use [Title](/path/doc.md)`,
+        });
+    }
+    for (const marker of doc.parsed.unclosedMarkers) {
+        findings.push({
+            severity: 'error',
+            rule: 'unclosed-marker',
+            docPath: doc.bundlePath,
+            line: marker.line,
+            message: `wiki:${marker.kind} marker never closes`,
+        });
+    }
+    for (const link of doc.parsed.links) {
+        const resolved = resolveLinkTarget(doc.bundlePath, link.target);
+        if (resolved.kind === 'escapes-bundle') {
+            findings.push({
+                severity: 'error',
+                rule: 'link-escapes-bundle',
+                docPath: doc.bundlePath,
+                line: link.line,
+                message: `link target leaves the bundle: ${link.target}`,
+            });
+            continue;
+        }
+        if (resolved.kind !== 'internal')
+            continue;
+        if (!link.isImage && !vault.docs.has(resolved.bundlePath)) {
+            if (lookupTarget(vault, resolved.bundlePath) === null) {
+                findings.push({
+                    severity: 'warning',
+                    rule: 'broken-link',
+                    docPath: doc.bundlePath,
+                    line: link.line,
+                    message: `target does not exist in the bundle: ${link.target}`,
+                });
+            }
+        }
+        if (!doc.isPrivate && resolved.bundlePath.startsWith('/private/')) {
+            findings.push({
+                severity: 'error',
+                rule: 'private-closure',
+                docPath: doc.bundlePath,
+                line: link.line,
+                message: `public document links into /private/: ${link.target}`,
+            });
+        }
+        if (!link.target.startsWith('/') && !link.isImage) {
+            findings.push({
+                severity: 'info',
+                rule: 'relative-link',
+                docPath: doc.bundlePath,
+                line: link.line,
+                message: `prefer bundle-absolute links: ${resolved.bundlePath}`,
+            });
+        }
+    }
+    if (doc.kind === 'concept' && doc.fm) {
+        if (!KNOWN_TYPES.has(doc.fm.type)) {
+            findings.push({
+                severity: 'info',
+                rule: 'unknown-type',
+                docPath: doc.bundlePath,
+                message: `type "${doc.fm.type}" is not in the profile vocabulary (allowed, but check for a near-miss)`,
+            });
+        }
+        if (isStale(doc.fm, today)) {
+            findings.push({
+                severity: 'warning',
+                rule: 'stale',
+                docPath: doc.bundlePath,
+                message: `stale since ${doc.fm.stale_after} — re-verify or update`,
+            });
+        }
+    }
+    if (doc.kind === 'log') {
+        const lines = doc.parsed.raw.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            if (lines[i].startsWith('## ') && !LOG_ENTRY_RE.test(lines[i])) {
+                findings.push({
+                    severity: 'warning',
+                    rule: 'log-format',
+                    docPath: doc.bundlePath,
+                    line: i + 1,
+                    message: 'log entry must be "## [YYYY-MM-DD] <op> | <summary>"',
+                });
+            }
+        }
+    }
+    if (!doc.isPrivate && options.forbiddenPatterns) {
+        for (const pattern of options.forbiddenPatterns) {
+            const match = doc.parsed.raw.match(pattern);
+            if (match) {
+                findings.push({
+                    severity: 'error',
+                    rule: 'forbidden-term',
+                    docPath: doc.bundlePath,
+                    message: `public document mentions a private name: "${match[0]}"`,
+                });
+            }
+        }
+    }
+    return findings;
+}
+// ── Bundle-wide rules ────────────────────────────────────────────────────────
+function lintIndexCoverage(vault) {
+    const findings = [];
+    const directories = new Set(['/']);
+    for (const doc of vault.docs.values()) {
+        const dir = posix.dirname(doc.bundlePath);
+        directories.add(dir === '/' ? '/' : `${dir}/`);
+    }
+    for (const dir of directories) {
+        const indexPath = posix.join(dir, 'index.md');
+        const index = vault.docs.get(indexPath);
+        if (!index) {
+            findings.push({
+                severity: 'warning',
+                rule: 'missing-index',
+                docPath: indexPath,
+                message: `directory ${dir} has no index.md (progressive disclosure gap)`,
+            });
+            continue;
+        }
+        // Every concept in the directory should be linked from its index; a
+        // private annex directory may be listed from the root but never the
+        // reverse (the closure rule handles direction).
+        const listed = new Set();
+        for (const link of index.parsed.links) {
+            const resolved = resolveLinkTarget(indexPath, link.target);
+            if (resolved.kind === 'internal') {
+                const target = lookupTarget(vault, resolved.bundlePath);
+                listed.add(target ? target.bundlePath : resolved.bundlePath);
+            }
+        }
+        for (const doc of docsInDirectory(vault, dir)) {
+            if (doc.kind !== 'concept')
+                continue;
+            if (index.isPrivate === doc.isPrivate && !listed.has(doc.bundlePath)) {
+                findings.push({
+                    severity: 'warning',
+                    rule: 'index-coverage',
+                    docPath: indexPath,
+                    message: `${doc.bundlePath} is not listed in its directory index`,
+                });
+            }
+        }
+    }
+    // Root index should declare the spec version it targets.
+    const root = vault.docs.get('/index.md');
+    if (root && !root.parsed.frontmatter?.okf_version) {
+        findings.push({
+            severity: 'info',
+            rule: 'okf-version',
+            docPath: '/index.md',
+            message: 'root index.md should declare okf_version in frontmatter',
+        });
+    }
+    return findings;
+}
+function lintOrphans(vault) {
+    const inbound = new Set();
+    for (const doc of vault.docs.values()) {
+        for (const link of doc.parsed.links) {
+            const resolved = resolveLinkTarget(doc.bundlePath, link.target);
+            if (resolved.kind !== 'internal')
+                continue;
+            const target = lookupTarget(vault, resolved.bundlePath);
+            if (target && target.bundlePath !== doc.bundlePath) {
+                inbound.add(target.bundlePath);
+            }
+        }
+    }
+    const findings = [];
+    for (const doc of vault.docs.values()) {
+        if (doc.kind !== 'concept')
+            continue;
+        if (!inbound.has(doc.bundlePath)) {
+            findings.push({
+                severity: 'warning',
+                rule: 'orphan',
+                docPath: doc.bundlePath,
+                message: 'no document links here — connect it or reconsider it',
+            });
+        }
+    }
+    return findings;
+}
+// ── Entry points ─────────────────────────────────────────────────────────────
+export function lintVault(vault, options = {}) {
+    const findings = [];
+    for (const doc of vault.docs.values()) {
+        findings.push(...lintDoc(vault, doc, options));
+    }
+    findings.push(...lintIndexCoverage(vault));
+    findings.push(...lintOrphans(vault));
+    findings.sort((a, b) => a.docPath === b.docPath
+        ? (a.line ?? 0) - (b.line ?? 0)
+        : a.docPath.localeCompare(b.docPath));
+    return report(findings);
+}
+export function formatLintReport(result) {
+    if (result.findings.length === 0)
+        return 'lint: clean — no findings.';
+    const lines = result.findings.map((f) => `${f.severity.toUpperCase().padEnd(7)} ${f.rule.padEnd(20)} ${f.docPath}${f.line ? `:${f.line}` : ''} — ${f.message}`);
+    lines.push(`lint: ${result.errors} error(s), ${result.warnings} warning(s), ${result.findings.length - result.errors - result.warnings} info.`);
+    return lines.join('\n');
+}

package/dist/lib/wiki/markdown.d.ts

@@ -0,0 +1,127 @@
+/**
+ * lib/wiki/markdown.ts — structural markdown: one node model, two directions.
+ *
+ * WHY this file exists:
+ *   The wiki needs to READ markdown structurally (frontmatter, headings,
+ *   links, fenced code, edit markers — enough to lint, graph, and navigate)
+ *   and to WRITE it structurally (docs assembled from typed parts, so links
+ *   and frontmatter are correct by construction). Both directions share the
+ *   shapes in this file.
+ *
+ *   Deliberately NOT a CommonMark AST. A full parser (remark/unified) would
+ *   add a dependency tree to a repo that has none for markdown, to answer
+ *   questions we don't ask — inline emphasis, HTML blocks, tables-as-trees.
+ *   The wiki's questions are structural: what does this doc declare, where
+ *   are its sections, what does it link to, which regions are machine-owned.
+ *   ~300 lines answer all of them with zero new dependencies
+ *   (wiki/decisions/0002). Frontmatter YAML goes through the same `yaml`
+ *   package the syndicate loader already uses.
+ *
+ *   Editing is SURGICAL, never a re-serialise of the whole document: the
+ *   parse keeps line positions, and edits splice exact line ranges (a fill
+ *   slot's interior, a generated block's interior, a log insertion point).
+ *   Prose the machine doesn't own is never reflowed.
+ *
+ * Marker grammar (HTML comments — invisible in rendered markdown):
+ *   <!-- wiki:generated section="<id>" source="<path>" -->…<!-- /wiki:generated -->
+ *     Machine-owned region; `wiki:build` rewrites its interior. `source`
+ *     names the repo truth it derives from.
+ *   <!-- wiki:fill slot="<id>" -->…<!-- /wiki:fill -->
+ *     Prose slot. Structural builds leave its interior alone; the LLM pass
+ *     (lib/wiki/fill.ts) replaces it while it still holds a TODO sentinel.
+ */
+export interface Heading {
+    depth: number;
+    text: string;
+    slug: string;
+    /** 1-based line number in the document. */
+    line: number;
+}
+export interface LinkRef {
+    text: string;
+    /** Target exactly as written (before bundle resolution). */
+    target: string;
+    line: number;
+    isImage: boolean;
+}
+export interface Fence {
+    startLine: number;
+    /** Closing-fence line; equals the last doc line when unclosed. */
+    endLine: number;
+    lang: string;
+}
+export interface FillSlot {
+    id: string;
+    /** Line of the opening marker. */
+    startLine: number;
+    /** Line of the closing marker. */
+    endLine: number;
+    /** Interior text between the markers (without the marker lines). */
+    content: string;
+}
+export interface GeneratedBlock {
+    id: string;
+    source?: string;
+    startLine: number;
+    endLine: number;
+    content: string;
+}
+export interface ParsedDoc {
+    raw: string;
+    /** YAML text between the `---` fences, or null when absent. */
+    frontmatterRaw: string | null;
+    /** Parsed YAML mapping; null when absent or unparseable. */
+    frontmatter: Record<string, unknown> | null;
+    /** YAML parse failure, when the block exists but will not parse. */
+    frontmatterError?: string;
+    /** 1-based line where the body (after any frontmatter block) begins. */
+    bodyStartLine: number;
+    headings: Heading[];
+    links: LinkRef[];
+    /** `[[wikilink]]` occurrences — not OKF; lint rejects them. */
+    wikilinks: Array<{
+        target: string;
+        line: number;
+    }>;
+    fences: Fence[];
+    slots: FillSlot[];
+    generated: GeneratedBlock[];
+    /** Marker lines that opened but never closed (lint surfaces these). */
+    unclosedMarkers: Array<{
+        kind: 'fill' | 'generated';
+        line: number;
+    }>;
+}
+/** Sentinel left in an unfilled slot; the fill pass replaces it. */
+export declare const TODO_SENTINEL = "_TODO(fill):";
+export declare function slotIsUnfilled(slot: FillSlot): boolean;
+/** GitHub-style anchor slug — for addressing sections by name. */
+export declare function slugify(text: string): string;
+export declare function parseDoc(raw: string): ParsedDoc;
+export interface SectionSlice {
+    heading: Heading;
+    /** 1-based inclusive line range, heading line included. */
+    startLine: number;
+    endLine: number;
+    text: string;
+}
+/** The section under the heading whose slug or text matches (case-insensitive). */
+export declare function sectionSlice(doc: ParsedDoc, nameOrSlug: string): SectionSlice | null;
+export declare function emitFrontmatter(fm: Record<string, unknown>): string;
+export declare function emitDoc(fm: Record<string, unknown>, body: string): string;
+export declare function heading(depth: number, text: string): string;
+export declare function mdLink(text: string, target: string): string;
+export declare function table(headers: string[], rows: string[][]): string;
+export declare function bulletList(items: string[]): string;
+export declare function fillSlot(id: string, content?: string, hint?: string): string;
+export declare function generatedBlock(id: string, source: string, content: string): string;
+/** Splice `content` between a slot's markers. Null when the slot is absent. */
+export declare function setSlotContent(raw: string, slotId: string, content: string): string | null;
+/** Splice `content` between a generated block's markers. Null when absent. */
+export declare function setGeneratedContent(raw: string, blockId: string, content: string): string | null;
+/**
+ * Insert a log entry newest-first: after the preamble (everything before the
+ * first `## [` entry), before existing entries. log.md stays chronologically
+ * scannable from the top — the profile's reading order for recency.
+ */
+export declare function insertLogEntry(raw: string, entry: string): string;