@coralai/sps-cli 0.50.24 → 0.51.0

package/dist/core/wiki/linter.js

@@ -0,0 +1,280 @@
+/**
+ * @module        core/wiki/linter
+ * @description   Wiki lint：orphan / dead link / frontmatter gap / stale 检查
+ *
+ * @layer         core
+ *
+ * doc-28 §10 wiki check 的代码实现。纯函数（除文件 mtime 读取）：给一组 Page +
+ * manifest，返一份 Report。
+ *
+ * 四类问题：
+ *   - orphan       — 页未被任何其他页 related[] 或 body wikilink 引用
+ *   - dead-link    — wikilink 指向不存在的 page
+ *   - fm-gap       — frontmatter 缺关键字段（其实 zod schema 已校验，这里防漏）
+ *   - stale        — manifest 里 source 的 hash 跟当前文件不一致（content drift）
+ *
+ * 不做：
+ *   - 自动修复（删 dead link、合并 orphan）—— 安全交给人决定
+ *   - 跨项目检查
+ */
+import { existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { tryHashFile } from './manifest.js';
+export function lintWiki(input) {
+    const issues = [];
+    issues.push(...checkOrphans(input.pages));
+    issues.push(...checkDeadLinks(input.pages));
+    issues.push(...checkFrontmatterGaps(input.pages));
+    issues.push(...checkStaleSources(input.manifest, input.repoDir));
+    return summarize(issues);
+}
+// ─── Orphan detection ────────────────────────────────────────────
+/**
+ * Orphan = page that nobody links to (via frontmatter related[] OR body wikilink).
+ *
+ * A solo page can still be valuable (e.g. just-written lesson) — orphan is **warn**,
+ * not error.
+ */
+export function checkOrphans(pages) {
+    const ids = new Set(pages.map((p) => p.pageId));
+    const refCount = new Map();
+    for (const id of ids)
+        refCount.set(id, 0);
+    for (const p of pages) {
+        // related[] is wikilinks "[[Page Name]]" — strip brackets and check both
+        // bare-title and "type/title" forms against ids.
+        for (const link of p.frontmatter.related) {
+            const target = resolveLinkToId(link, ids);
+            if (target)
+                refCount.set(target, (refCount.get(target) ?? 0) + 1);
+        }
+        // Body wikilinks
+        for (const link of extractBodyWikilinks(p.body)) {
+            const target = resolveLinkToId(`[[${link}]]`, ids);
+            if (target)
+                refCount.set(target, (refCount.get(target) ?? 0) + 1);
+        }
+    }
+    const out = [];
+    for (const [pageId, count] of refCount) {
+        if (count === 0) {
+            out.push({
+                kind: 'orphan',
+                severity: 'warn',
+                pageId,
+                message: `Page "${pageId}" is not referenced by any other page.`,
+            });
+        }
+    }
+    return out;
+}
+// ─── Dead-link detection ─────────────────────────────────────────
+/**
+ * Dead link = wikilink "[[X]]" where X (resolved) is not in the page set.
+ *
+ * Errors for related[] (frontmatter); warnings for body links (in-flight writing).
+ */
+export function checkDeadLinks(pages) {
+    const ids = new Set(pages.map((p) => p.pageId));
+    const out = [];
+    for (const p of pages) {
+        for (const link of p.frontmatter.related) {
+            if (!resolveLinkToId(link, ids)) {
+                out.push({
+                    kind: 'dead-link',
+                    severity: 'error',
+                    pageId: p.pageId,
+                    target: link,
+                    message: `frontmatter related: "${link}" does not resolve to any page.`,
+                });
+            }
+        }
+        for (const link of extractBodyWikilinks(p.body)) {
+            if (!resolveLinkToId(`[[${link}]]`, ids)) {
+                out.push({
+                    kind: 'dead-link',
+                    severity: 'warn',
+                    pageId: p.pageId,
+                    target: link,
+                    message: `body wikilink: "[[${link}]]" does not resolve.`,
+                });
+            }
+        }
+    }
+    return out;
+}
+// ─── Frontmatter gap detection ───────────────────────────────────
+/**
+ * Catches missing soft-required fields the zod schema can't enforce
+ * (e.g. empty title, empty TL;DR, all default tags). Schema-level errors
+ * are caught at parse time — this is a content sniff.
+ */
+export function checkFrontmatterGaps(pages) {
+    const out = [];
+    for (const p of pages) {
+        const fm = p.frontmatter;
+        if (!fm.title.trim()) {
+            out.push({
+                kind: 'fm-gap',
+                severity: 'error',
+                pageId: p.pageId,
+                target: 'title',
+                message: 'frontmatter title is empty.',
+            });
+        }
+        if (fm.tags.length === 0) {
+            out.push({
+                kind: 'fm-gap',
+                severity: 'warn',
+                pageId: p.pageId,
+                target: 'tags',
+                message: 'frontmatter tags is empty (page won\'t match any skill).',
+            });
+        }
+        if (!hasTLDR(p.body)) {
+            out.push({
+                kind: 'fm-gap',
+                severity: 'warn',
+                pageId: p.pageId,
+                target: 'body',
+                message: 'body has no `## TL;DR` section (search/preview will use fallback).',
+            });
+        }
+    }
+    return out;
+}
+// ─── Stale source detection ──────────────────────────────────────
+/**
+ * Compare manifest's stored sha256 against current file hash on disk.
+ * Mismatch = source has drifted since last ingest → its derived pages may be stale.
+ *
+ * Files that don't exist on disk anymore are flagged as 'stale' too (they should
+ * be removed from manifest via finalize).
+ */
+export function checkStaleSources(manifest, repoDir) {
+    const out = [];
+    for (const [path, entry] of Object.entries(manifest.sources)) {
+        const abs = resolve(repoDir, path);
+        if (!existsSync(abs)) {
+            out.push({
+                kind: 'stale',
+                severity: 'warn',
+                pageId: null,
+                target: path,
+                message: `Source "${path}" no longer exists. Run \`sps wiki update <project> --finalize\` to clean.`,
+            });
+            continue;
+        }
+        const currentHash = tryHashFile(abs);
+        if (currentHash && currentHash !== entry.sha256) {
+            // Best effort: include affected pages
+            const affected = entry.pages.length > 0 ? ` (affects: ${entry.pages.join(', ')})` : '';
+            out.push({
+                kind: 'stale',
+                severity: 'warn',
+                pageId: null,
+                target: path,
+                message: `Source "${path}" has changed since ingest${affected}.`,
+            });
+        }
+    }
+    return out;
+}
+// ─── Helpers ──────────────────────────────────────────────────────
+/**
+ * Resolve a "[[X]]" or "[[type/X]]" wikilink against the known pageId set.
+ *
+ * Strategy:
+ *   - "[[type/X]]" → look up exact pageId
+ *   - "[[X]]" → look up any pageId ending with "/X" (any type matches)
+ *
+ * Returns the resolved pageId, or null if unresolvable.
+ */
+export function resolveLinkToId(wikilink, ids) {
+    const m = wikilink.match(/^\[\[([^[\]]+)\]\]$/);
+    if (!m)
+        return null;
+    const target = m[1].trim();
+    if (target.includes('/')) {
+        return ids.has(target) ? target : null;
+    }
+    // No prefix — find any pageId whose title matches
+    for (const id of ids) {
+        const slash = id.lastIndexOf('/');
+        if (slash >= 0 && id.slice(slash + 1) === target)
+            return id;
+    }
+    return null;
+}
+const BODY_LINK_RE = /\[\[([^[\]]+)\]\]/g;
+export function extractBodyWikilinks(body) {
+    const out = [];
+    for (const m of body.matchAll(BODY_LINK_RE)) {
+        out.push(m[1].trim());
+    }
+    return out;
+}
+const TLDR_RE = /^##\s+TL;DR\b/m;
+function hasTLDR(body) {
+    return TLDR_RE.test(body);
+}
+function summarize(issues) {
+    const counts = {
+        orphan: 0,
+        'dead-link': 0,
+        'fm-gap': 0,
+        stale: 0,
+    };
+    let errorCount = 0;
+    let warnCount = 0;
+    for (const i of issues) {
+        counts[i.kind] += 1;
+        if (i.severity === 'error')
+            errorCount += 1;
+        else
+            warnCount += 1;
+    }
+    return { issues: [...issues], counts, errorCount, warnCount };
+}
+// ─── Mtime helper (used by status command) ────────────────────────
+/**
+ * Compare source mtime vs page mtime. Returns paths whose source is newer.
+ *
+ * Best-effort — file mtime precision varies (ext4 ns vs HFS+ 1s); we use a
+ * 60s threshold to avoid false positives.
+ */
+export function findOutdatedPages(manifest, pages, repoDir, thresholdMs = 60_000) {
+    const out = [];
+    const pageMtimeById = new Map();
+    for (const p of pages) {
+        try {
+            pageMtimeById.set(p.pageId, statSync(p.filePath).mtime);
+        }
+        catch {
+            // ignore
+        }
+    }
+    for (const [sourcePath, entry] of Object.entries(manifest.sources)) {
+        if (entry.pages.length === 0)
+            continue;
+        let sourceMtime;
+        try {
+            sourceMtime = statSync(resolve(repoDir, sourcePath)).mtime;
+        }
+        catch {
+            continue;
+        }
+        const outdated = [];
+        for (const pid of entry.pages) {
+            const pmtime = pageMtimeById.get(pid);
+            if (!pmtime)
+                continue;
+            if (sourceMtime.getTime() - pmtime.getTime() > thresholdMs)
+                outdated.push(pid);
+        }
+        if (outdated.length > 0)
+            out.push({ sourcePath, pageIds: outdated, sourceMtime });
+    }
+    return out;
+}
+//# sourceMappingURL=linter.js.map

package/dist/core/wiki/linter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"linter.js","sourceRoot":"","sources":["../../../src/core/wiki/linter.ts"],"names":[],"mappings":"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"}

package/dist/core/wiki/log.d.ts

@@ -0,0 +1,24 @@
+export type LogAction = 'ingest' | 'write' | 'update' | 'lint' | 'init' | 'add' | 'delete';
+export interface LogEntry {
+    action: LogAction;
+    /** 时间戳；缺省 now */
+    timestamp?: string;
+    /** Source 路径或 page id 或简短描述 */
+    target: string;
+    /** 一句话描述（≤ 100 字符） */
+    message: string;
+    /** 受影响的 page id 列表（可选） */
+    pages?: readonly string[];
+}
+/**
+ * 在 log.md 顶部插入一条 entry。
+ *
+ * - 文件不存在：创建带 header
+ * - 已有内容：保留最近 MAX_ENTRIES 条（旧的截掉）
+ */
+export declare function appendLog(repoDir: string, entry: LogEntry): void;
+/**
+ * 读 log.md 全文。文件不存在返默认 header。
+ */
+export declare function readLog(repoDir: string): string;
+//# sourceMappingURL=log.d.ts.map

package/dist/core/wiki/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../../src/core/wiki/log.ts"],"names":[],"mappings":"AA+BA,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;AAE3F,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,SAAS,CAAC;IAClB,iBAAiB;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI,CAwChE;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ/C"}

package/dist/core/wiki/log.js

@@ -0,0 +1,107 @@
+/**
+ * @module        core/wiki/log
+ * @description   Wiki .log.md：操作时间序列（per-instance，gitignored）
+ *
+ * @layer         core
+ *
+ * 借鉴 claude-obsidian 的 wiki/log.md：每次 ingest / write / lint 在文件
+ * 顶部追加一条事件，便于 Worker / 用户回看 "最近 wiki 怎么变的"。
+ *
+ * 实现选择：
+ *   - 新条目**顶部追加**（最新在最前），方便 Worker 默认读前几条就看到 latest
+ *   - hard cap 500 条（~5000 行），超过截尾——log 不是 audit，旧条目用 git/hot.md 找
+ *   - frontmatter 固定（type=meta），不需要解析
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { wikiLogFile } from '../../shared/wikiPaths.js';
+const HEADER = `---
+type: meta
+title: Wiki Operation Log
+---
+
+# Wiki Operation Log
+
+`;
+const MAX_ENTRIES = 500;
+/**
+ * 在 log.md 顶部插入一条 entry。
+ *
+ * - 文件不存在：创建带 header
+ * - 已有内容：保留最近 MAX_ENTRIES 条（旧的截掉）
+ */
+export function appendLog(repoDir, entry) {
+    const path = wikiLogFile(repoDir);
+    const ts = entry.timestamp ?? new Date().toISOString();
+    const block = renderEntry({ ...entry, timestamp: ts });
+    let existing;
+    if (existsSync(path)) {
+        try {
+            existing = readFileSync(path, 'utf-8');
+        }
+        catch {
+            existing = HEADER;
+        }
+    }
+    else {
+        existing = HEADER;
+        mkdirSync(dirname(path), { recursive: true });
+    }
+    // 拆 header + 旧 entries
+    const headerEnd = existing.indexOf('# Wiki Operation Log\n');
+    let header;
+    let entries;
+    if (headerEnd === -1) {
+        header = HEADER;
+        entries = '';
+    }
+    else {
+        const afterHeader = existing.indexOf('\n', headerEnd) + 1;
+        header = existing.slice(0, afterHeader + 1);
+        entries = existing.slice(afterHeader + 1);
+    }
+    // 拆现有 entries（按 ## 开头分组），去除可能的 trailing whitespace
+    const oldBlocks = entries.split(/(?=^## )/m).filter((b) => b.trim().length > 0);
+    // 顶部插入新 block
+    const updatedBlocks = [block, ...oldBlocks];
+    // cap 数量
+    const truncated = updatedBlocks.slice(0, MAX_ENTRIES);
+    const final = header + truncated.join('') + (truncated.length === MAX_ENTRIES ? '\n…（older entries truncated）\n' : '');
+    writeFileSync(path, final, { encoding: 'utf-8', mode: 0o644 });
+}
+/**
+ * 读 log.md 全文。文件不存在返默认 header。
+ */
+export function readLog(repoDir) {
+    const path = wikiLogFile(repoDir);
+    if (!existsSync(path))
+        return HEADER;
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch {
+        return HEADER;
+    }
+}
+// ─── Render ───────────────────────────────────────────────────────
+/**
+ * 单条 log entry 渲染：
+ *
+ * ```md
+ * ## 2026-04-27T18:30:00Z · update · src/X.ts
+ * 增量 ingest：3 个文件改动
+ * - Pages: [[modules/X]], [[lessons/Stop Hook Race]]
+ * ```
+ */
+function renderEntry(entry) {
+    const lines = [];
+    lines.push(`## ${entry.timestamp} · ${entry.action} · ${entry.target}`);
+    lines.push(entry.message.trim());
+    if (entry.pages && entry.pages.length > 0) {
+        const wikilinks = entry.pages.map((p) => `[[${p}]]`).join(', ');
+        lines.push(`- Pages: ${wikilinks}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+//# sourceMappingURL=log.js.map

package/dist/core/wiki/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../../../src/core/wiki/log.ts"],"names":[],"mappings":"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"}

package/dist/core/wiki/manifest.d.ts

@@ -0,0 +1,59 @@
+import { type Manifest, type ManifestEntry, type SourceDiff } from './types.js';
+/**
+ * 读 manifest 文件。
+ * 文件不存在 / 损坏 / schema 不合法 → 返 EMPTY_MANIFEST（同时调 onWarn 报告）。
+ *
+ * 不 throw —— manifest 只是性能优化，损坏时退化为全量重 ingest 即可。
+ */
+export declare function readManifest(manifestPath: string, onWarn?: (msg: string) => void): Manifest;
+/**
+ * 写 manifest 文件。原子替换（temp + rename），避免读到半截。
+ */
+export declare function writeManifest(manifestPath: string, manifest: Manifest): void;
+/**
+ * 计算文件 sha256 hex。文件不存在或读失败 → throw（调用方决定是否兜底）。
+ *
+ * 大文件友好：用 buffer reads 而不是一次性读到内存——但 wiki 源文件
+ * 一般 < 1 MB，readFileSync 已经够。如果将来要 ingest 大 PDF，再换 streaming。
+ */
+export declare function hashFile(filePath: string): string;
+/**
+ * 同上但是宽松：失败时返 null（用于 lint / 增量扫描）。
+ */
+export declare function tryHashFile(filePath: string): string | null;
+export interface DiffInputSource {
+    /** Path relative to repo root (e.g. "src/X.ts" 或 ".raw/y.pdf") */
+    readonly path: string;
+    /** Pre-computed hash (caller responsibility) */
+    readonly hash: string;
+}
+/**
+ * 比较"当前发现的源 + 它们的 hash"和 manifest 里记录的状态。
+ *
+ * - added：current 里有，manifest 里没
+ * - changed：两边都有但 hash 不同
+ * - removed：manifest 里有，current 里没（源被删了）
+ * - unchanged：两边都有且 hash 相同
+ *
+ * 纯函数，无 I/O。
+ */
+export declare function diffSources(current: readonly DiffInputSource[], manifest: Manifest): SourceDiff;
+/**
+ * 标记一个 source 已 ingest 过。返回新 manifest（不修改原对象）。
+ *
+ * 用途：每次 ingest 一个 source 后调一次。如果 path 已存在，覆盖；否则添加。
+ */
+export declare function recordIngest(manifest: Manifest, path: string, entry: ManifestEntry): Manifest;
+/**
+ * 删除一个 source 的记录（被删除时用）。返回新 manifest。
+ */
+export declare function removeFromManifest(manifest: Manifest, path: string): Manifest;
+/**
+ * 检查 source 文件 mtime > 它所派生的 page 中任何一个的 updated 字段。
+ * 用于 lint：标 stale page。
+ *
+ * 这是 best-effort —— 跨文件系统 mtime 精度不一致（macOS HFS+ 1s，
+ * Linux ext4 ns）。差几秒不算 stale。
+ */
+export declare function isSourceStale(sourcePath: string, pageMtime: Date | null): boolean;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/core/wiki/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/core/wiki/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,aAAa,EAElB,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAIpB;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,YAAY,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAC7B,QAAQ,CA0BV;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAQ5E;AAID;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAID,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,QAAQ,EAAE,QAAQ,GACjB,UAAU,CA8BZ;AAID;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,aAAa,GACnB,QAAQ,CAOV;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAS7E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CASjF"}

package/dist/core/wiki/manifest.js

@@ -0,0 +1,180 @@
+/**
+ * @module        core/wiki/manifest
+ * @description   Wiki 增量索引：源文件 hash 跟踪表（.manifest.json）
+ *
+ * @layer         core
+ *
+ * 作用：每次 `sps wiki update` 时比 hash，决定哪些 source 需要重新 ingest——
+ *      避免每次都让 Worker 重读全部源文件。
+ *
+ * 设计要点（doc-28 §5 + §8）：
+ *   - 文件位置：`<repo>/wiki/.manifest.json`（gitignored）
+ *   - 每台机一份；不同 dev 的 manifest 不互相覆盖
+ *   - 源路径用相对 repo 根目录（"src/X.ts" / ".raw/pdfs/y.pdf"）
+ *   - hash 用 sha256，文件级原子单位（不切分到行/段）
+ *   - 跟 zod schema 校验过——损坏的 manifest 当作 EMPTY 重建，不阻塞 update
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { EMPTY_MANIFEST, ManifestSchema, } from './types.js';
+// ─── 文件 I/O ─────────────────────────────────────────────────────
+/**
+ * 读 manifest 文件。
+ * 文件不存在 / 损坏 / schema 不合法 → 返 EMPTY_MANIFEST（同时调 onWarn 报告）。
+ *
+ * 不 throw —— manifest 只是性能优化，损坏时退化为全量重 ingest 即可。
+ */
+export function readManifest(manifestPath, onWarn) {
+    if (!existsSync(manifestPath))
+        return EMPTY_MANIFEST;
+    let raw;
+    try {
+        raw = readFileSync(manifestPath, 'utf-8');
+    }
+    catch (err) {
+        onWarn?.(`manifest read failed (${manifestPath}): ${errMsg(err)}`);
+        return EMPTY_MANIFEST;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        onWarn?.(`manifest JSON parse failed (${manifestPath}): ${errMsg(err)} — treating as empty`);
+        return EMPTY_MANIFEST;
+    }
+    const result = ManifestSchema.safeParse(parsed);
+    if (!result.success) {
+        onWarn?.(`manifest schema invalid (${manifestPath}): ${result.error.issues
+            .map((i) => `${i.path.join('.')}:${i.message}`)
+            .join('; ')} — treating as empty`);
+        return EMPTY_MANIFEST;
+    }
+    return result.data;
+}
+/**
+ * 写 manifest 文件。原子替换（temp + rename），避免读到半截。
+ */
+export function writeManifest(manifestPath, manifest) {
+    const validated = ManifestSchema.parse(manifest); // 写入前最后一道校验
+    const text = JSON.stringify(validated, null, 2) + '\n';
+    // node:fs writeFileSync 已经是原子的（POSIX rename semantics）—— 但为防止 partial
+    // write 在 crash 场景留半截文件，用 .tmp + rename。
+    const tmpPath = manifestPath + '.tmp';
+    writeFileSync(tmpPath, text, { encoding: 'utf-8', mode: 0o644 });
+    renameSync(tmpPath, manifestPath);
+}
+// ─── Hash 计算 ────────────────────────────────────────────────────
+/**
+ * 计算文件 sha256 hex。文件不存在或读失败 → throw（调用方决定是否兜底）。
+ *
+ * 大文件友好：用 buffer reads 而不是一次性读到内存——但 wiki 源文件
+ * 一般 < 1 MB，readFileSync 已经够。如果将来要 ingest 大 PDF，再换 streaming。
+ */
+export function hashFile(filePath) {
+    const buf = readFileSync(filePath);
+    return createHash('sha256').update(buf).digest('hex');
+}
+/**
+ * 同上但是宽松：失败时返 null（用于 lint / 增量扫描）。
+ */
+export function tryHashFile(filePath) {
+    try {
+        return hashFile(filePath);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 比较"当前发现的源 + 它们的 hash"和 manifest 里记录的状态。
+ *
+ * - added：current 里有，manifest 里没
+ * - changed：两边都有但 hash 不同
+ * - removed：manifest 里有，current 里没（源被删了）
+ * - unchanged：两边都有且 hash 相同
+ *
+ * 纯函数，无 I/O。
+ */
+export function diffSources(current, manifest) {
+    const currentMap = new Map(current.map((s) => [s.path, s.hash]));
+    const manifestPaths = new Set(Object.keys(manifest.sources));
+    const added = [];
+    const changed = [];
+    const unchanged = [];
+    for (const [path, hash] of currentMap) {
+        const entry = manifest.sources[path];
+        if (!entry) {
+            added.push(path);
+        }
+        else if (entry.sha256 !== hash) {
+            changed.push(path);
+        }
+        else {
+            unchanged.push(path);
+        }
+    }
+    const removed = [];
+    for (const path of manifestPaths) {
+        if (!currentMap.has(path))
+            removed.push(path);
+    }
+    return {
+        added: added.sort(),
+        changed: changed.sort(),
+        removed: removed.sort(),
+        unchanged: unchanged.sort(),
+    };
+}
+// ─── 更新 manifest（in-place pure，返回新 manifest） ───────────────
+/**
+ * 标记一个 source 已 ingest 过。返回新 manifest（不修改原对象）。
+ *
+ * 用途：每次 ingest 一个 source 后调一次。如果 path 已存在，覆盖；否则添加。
+ */
+export function recordIngest(manifest, path, entry) {
+    const sources = { ...manifest.sources, [path]: entry };
+    return {
+        ...manifest,
+        updated_at: new Date().toISOString(),
+        sources,
+    };
+}
+/**
+ * 删除一个 source 的记录（被删除时用）。返回新 manifest。
+ */
+export function removeFromManifest(manifest, path) {
+    if (!(path in manifest.sources))
+        return manifest;
+    const { [path]: _removed, ...rest } = manifest.sources;
+    void _removed;
+    return {
+        ...manifest,
+        updated_at: new Date().toISOString(),
+        sources: rest,
+    };
+}
+/**
+ * 检查 source 文件 mtime > 它所派生的 page 中任何一个的 updated 字段。
+ * 用于 lint：标 stale page。
+ *
+ * 这是 best-effort —— 跨文件系统 mtime 精度不一致（macOS HFS+ 1s，
+ * Linux ext4 ns）。差几秒不算 stale。
+ */
+export function isSourceStale(sourcePath, pageMtime) {
+    if (!pageMtime)
+        return false;
+    try {
+        const sourceMtime = statSync(sourcePath).mtime;
+        // 超过 60s 才算改过——避免精度问题误报
+        return sourceMtime.getTime() - pageMtime.getTime() > 60_000;
+    }
+    catch {
+        return false; // source 不存在 = 不算 stale，归 lint 别的检查
+    }
+}
+// ─── helpers ──────────────────────────────────────────────────────
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=manifest.js.map