opencode-rag-plugin 2.13.4 → 2.13.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,286 @@
1
+ /**
2
+ * @fileoverview Builds the wiki link graph: pages, resolved links, backlinks,
3
+ * orphans, dangling targets, and index coverage.
4
+ *
5
+ * The graph is computed ON DEMAND from the `.md` files — the files are the
6
+ * single source of truth and a wiki is small (protocol: focused pages), so a
7
+ * full scan costs milliseconds and the graph can never be stale. A
8
+ * process-local cache keyed by an (path, mtime, size) fingerprint skips the
9
+ * re-read until something actually changed.
10
+ *
11
+ * Orphan semantics follow the wiki protocol: `index.md` and `log.md` are
12
+ * bookkeeping, not cross-references — links FROM them do not count as inbound
13
+ * evidence, and they are never reported as orphans themselves. Index coverage
14
+ * is reported separately (`uncataloged`).
15
+ */
16
+ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
17
+ import * as path from "node:path";
18
+ import { normalizePageId, pageBasename, parseWikiPage } from "./page-parse.js";
19
+ /** Bookkeeping pages: excluded from orphan analysis and inbound counting. */
20
+ export const NON_CONTENT_PAGE_IDS = new Set(["index", "log"]);
21
+ /** Recursively collect `.md` files under `dir`, sorted for stable output. */
22
+ function collectMarkdownFiles(dir, limit) {
23
+ const files = [];
24
+ let truncated = false;
25
+ const walk = (current) => {
26
+ if (truncated)
27
+ return;
28
+ for (const entry of readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
29
+ const full = path.join(current, entry.name);
30
+ if (entry.isDirectory()) {
31
+ walk(full);
32
+ if (truncated)
33
+ return;
34
+ }
35
+ else if (entry.isFile() && /\.md$/i.test(entry.name)) {
36
+ files.push(full);
37
+ if (files.length >= limit) {
38
+ truncated = true;
39
+ return;
40
+ }
41
+ }
42
+ }
43
+ };
44
+ walk(dir);
45
+ return { files, truncated };
46
+ }
47
+ /**
48
+ * Resolve a raw link target against the page set.
49
+ * Order: exact id → unique basename. Case-insensitive on both.
50
+ *
51
+ * @param raw - The link target as written.
52
+ * @param idIndex - Map of normalized id → id.
53
+ * @param basenameIndex - Map of lowercased basename → ids with that basename.
54
+ * @returns The resolved page id, or undefined when dangling.
55
+ */
56
+ export function resolveLinkTarget(raw, idIndex, basenameIndex) {
57
+ const id = normalizePageId(raw);
58
+ if (id.length === 0)
59
+ return undefined;
60
+ const exact = idIndex.get(id);
61
+ if (exact)
62
+ return exact;
63
+ const byBase = basenameIndex.get(pageBasename(id));
64
+ if (byBase && byBase.length === 1)
65
+ return byBase[0];
66
+ return undefined;
67
+ }
68
+ /** Fingerprint of the current file set: relPath|mtimeMs|size, sorted. */
69
+ function fingerprint(files, wikiDir) {
70
+ return files
71
+ .map((f) => `${path.relative(wikiDir, f).replace(/\\/g, "/")}|${statSync(f).mtimeMs}|${statSync(f).size}`)
72
+ .sort()
73
+ .join(";");
74
+ }
75
+ const graphCache = new Map();
76
+ const EMPTY_GRAPH = {
77
+ wikiDir: "",
78
+ exists: false,
79
+ pages: new Map(),
80
+ orphans: [],
81
+ dangling: [],
82
+ uncataloged: [],
83
+ indexEntriesMissingFile: [],
84
+ pagesMissingFrontmatter: [],
85
+ frontmatterIssues: [],
86
+ truncated: false,
87
+ pageCount: 0,
88
+ };
89
+ /**
90
+ * Build the wiki graph, reading every page.
91
+ *
92
+ * @param wikiDir - Absolute path of the wiki root (`.opencode/wiki`).
93
+ * @param options - Scan limits.
94
+ * @returns The graph snapshot; `exists: false` when the directory is absent.
95
+ */
96
+ export function buildWikiGraph(wikiDir, options = {}) {
97
+ const maxPages = Math.max(1, options.maxPages ?? 500);
98
+ if (!existsSync(wikiDir)) {
99
+ return { ...EMPTY_GRAPH, wikiDir };
100
+ }
101
+ const { files, truncated } = collectMarkdownFiles(wikiDir, maxPages);
102
+ if (files.length === 0) {
103
+ return { ...EMPTY_GRAPH, wikiDir, exists: true, truncated };
104
+ }
105
+ const parsedPages = [];
106
+ for (const absPath of files) {
107
+ let content;
108
+ try {
109
+ content = readFileSync(absPath, "utf-8");
110
+ }
111
+ catch {
112
+ continue; // unreadable file: skip; the lint layer cannot invent content
113
+ }
114
+ parsedPages.push({ absPath, parsed: parseWikiPage(content) });
115
+ }
116
+ const relOf = (abs) => path.relative(wikiDir, abs).replace(/\\/g, "/");
117
+ const idOf = (abs) => normalizePageId(relOf(abs));
118
+ // Two ids can only collide via case (filesystems aside): first wins.
119
+ const idIndex = new Map();
120
+ const basenameIndex = new Map();
121
+ const nodes = new Map();
122
+ for (const { absPath, parsed } of parsedPages) {
123
+ const id = idOf(absPath);
124
+ if (id.length === 0 || nodes.has(id))
125
+ continue;
126
+ idIndex.set(id, id);
127
+ const base = pageBasename(id);
128
+ const list = basenameIndex.get(base) ?? [];
129
+ list.push(id);
130
+ basenameIndex.set(base, list);
131
+ const rel = relOf(absPath);
132
+ nodes.set(id, {
133
+ id,
134
+ relPath: rel,
135
+ absPath,
136
+ title: parsed.frontmatter.title ?? parsed.headingTitle ?? base,
137
+ parsed,
138
+ isContent: !NON_CONTENT_PAGE_IDS.has(id) && !id.startsWith("templates/"),
139
+ outbound: [],
140
+ unresolved: [],
141
+ inbound: [],
142
+ cataloged: false,
143
+ });
144
+ }
145
+ // Pass 1: resolve links.
146
+ const edges = [];
147
+ const dangling = [];
148
+ const indexEntriesMissingFile = [];
149
+ for (const node of nodes.values()) {
150
+ for (const link of node.parsed.links) {
151
+ const target = resolveLinkTarget(link.target, idIndex, basenameIndex);
152
+ if (!target || target === node.id) {
153
+ const entry = { fromId: node.id, raw: link.target, target: normalizePageId(link.target) };
154
+ if (target === node.id)
155
+ continue; // self-link: not dangling, just noise we ignore
156
+ dangling.push(entry);
157
+ if (node.id === "index")
158
+ indexEntriesMissingFile.push(entry);
159
+ continue;
160
+ }
161
+ node.outbound.push(target);
162
+ edges.push({ from: node.id, to: target });
163
+ }
164
+ }
165
+ // Pass 2: backlinks (content pages only contribute inbound evidence),
166
+ // index cataloging (index.md's OUTBOUND marks pages cataloged).
167
+ for (const { from, to } of edges) {
168
+ const toNode = nodes.get(to);
169
+ if (!toNode)
170
+ continue;
171
+ if (from === "index")
172
+ toNode.cataloged = true;
173
+ if (from === "index" || from === "log")
174
+ continue;
175
+ if (!toNode.inbound.includes(from))
176
+ toNode.inbound.push(from);
177
+ }
178
+ const orphans = [];
179
+ const uncataloged = [];
180
+ const pagesMissingFrontmatter = [];
181
+ const frontmatterIssues = [];
182
+ for (const node of nodes.values()) {
183
+ if (!node.isContent)
184
+ continue;
185
+ if (node.inbound.length === 0)
186
+ orphans.push(node.id);
187
+ if (!node.cataloged)
188
+ uncataloged.push(node.id);
189
+ if (!node.parsed.frontmatter.present)
190
+ pagesMissingFrontmatter.push(node.id);
191
+ for (const issue of node.parsed.frontmatter.issues) {
192
+ frontmatterIssues.push({ id: node.id, message: issue.message });
193
+ }
194
+ }
195
+ for (const node of nodes.values())
196
+ node.inbound.sort();
197
+ orphans.sort();
198
+ uncataloged.sort();
199
+ return {
200
+ wikiDir,
201
+ exists: true,
202
+ pages: nodes,
203
+ orphans,
204
+ dangling,
205
+ uncataloged,
206
+ indexEntriesMissingFile,
207
+ pagesMissingFrontmatter,
208
+ frontmatterIssues,
209
+ truncated,
210
+ pageCount: nodes.size,
211
+ };
212
+ }
213
+ /**
214
+ * Cached wrapper around {@link buildWikiGraph}: returns the cached graph while
215
+ * the (path, mtime, size) fingerprint of the file set is unchanged, so
216
+ * repeated tool calls in one session cost one disk read.
217
+ *
218
+ * @param wikiDir - Absolute path of the wiki root.
219
+ * @param options - Scan limits (part of the cache key).
220
+ * @returns The graph snapshot.
221
+ */
222
+ export function getWikiGraph(wikiDir, options = {}) {
223
+ const maxPages = Math.max(1, options.maxPages ?? 500);
224
+ if (!existsSync(wikiDir)) {
225
+ graphCache.delete(wikiDir);
226
+ return { ...EMPTY_GRAPH, wikiDir };
227
+ }
228
+ const { files } = collectMarkdownFiles(wikiDir, maxPages);
229
+ const fp = fingerprint(files, wikiDir);
230
+ const hit = graphCache.get(wikiDir);
231
+ if (hit && hit.fp === fp && hit.maxPages === maxPages)
232
+ return hit.graph;
233
+ const graph = buildWikiGraph(wikiDir, { maxPages });
234
+ graphCache.set(wikiDir, { fp, maxPages, graph });
235
+ return graph;
236
+ }
237
+ /**
238
+ * BFS neighborhood of a page over both edge directions.
239
+ *
240
+ * @param graph - The wiki graph.
241
+ * @param pageId - Normalized id of the center page.
242
+ * @param depth - Hops to expand (1–3).
243
+ * @returns Page ids within `depth` hops, center excluded, sorted.
244
+ */
245
+ export function graphNeighbors(graph, pageId, depth) {
246
+ const seen = new Set([pageId]);
247
+ let frontier = [pageId];
248
+ const max = Math.min(3, Math.max(1, depth));
249
+ for (let d = 0; d < max; d++) {
250
+ const next = [];
251
+ for (const id of frontier) {
252
+ const node = graph.pages.get(id);
253
+ if (!node)
254
+ continue;
255
+ for (const n of [...node.outbound, ...node.inbound]) {
256
+ if (!seen.has(n)) {
257
+ seen.add(n);
258
+ next.push(n);
259
+ }
260
+ }
261
+ }
262
+ frontier = next;
263
+ if (frontier.length === 0)
264
+ break;
265
+ }
266
+ seen.delete(pageId);
267
+ return [...seen].sort();
268
+ }
269
+ /**
270
+ * Find the page a user-facing `page` argument refers to.
271
+ * Accepts an exact id or a unique basename (mirrors link resolution),
272
+ * case-insensitively, with or without the `.opencode/wiki/` prefix.
273
+ *
274
+ * @param graph - The wiki graph.
275
+ * @param page - User-provided page reference.
276
+ * @returns The matching node, or undefined when unknown or ambiguous.
277
+ */
278
+ export function findPage(graph, page) {
279
+ const id = normalizePageId(page);
280
+ const exact = graph.pages.get(id);
281
+ if (exact)
282
+ return exact;
283
+ const matches = [...graph.pages.values()].filter((n) => pageBasename(n.id) === pageBasename(id));
284
+ return matches.length === 1 ? matches[0] : undefined;
285
+ }
286
+ //# sourceMappingURL=graph.js.map
@@ -0,0 +1,48 @@
1
+ import { type WikiGraph, type WikiGraphOptions } from "./graph.js";
2
+ import { type StalenessResult } from "./staleness.js";
3
+ /** Options for a lint pass. */
4
+ export interface WikiLintOptions extends WikiGraphOptions {
5
+ /** Max commits in the single git-log walk (staleness). Default 500. */
6
+ maxCommits?: number;
7
+ /** Injected clock (tests). */
8
+ nowMs?: number;
9
+ }
10
+ /** The full deterministic health report for one wiki. */
11
+ export interface WikiLintReport {
12
+ wikiDir: string;
13
+ exists: boolean;
14
+ pageCount: number;
15
+ contentPages: number;
16
+ truncated: boolean;
17
+ orphans: string[];
18
+ dangling: WikiGraph["dangling"];
19
+ uncataloged: string[];
20
+ indexEntriesMissingFile: WikiGraph["indexEntriesMissingFile"];
21
+ pagesMissingFrontmatter: string[];
22
+ frontmatterIssues: {
23
+ id: string;
24
+ message: string;
25
+ }[];
26
+ staleness: StalenessResult;
27
+ /** Total deterministic findings (a page can carry several). */
28
+ findingCount: number;
29
+ }
30
+ /**
31
+ * Run the deterministic lint pass.
32
+ *
33
+ * @param wikiDir - Absolute path to `.opencode/wiki`.
34
+ * @param cwd - Workspace root (sourceRefs resolve against it).
35
+ * @param options - Limits.
36
+ * @returns The report; `exists: false` when there is no wiki yet.
37
+ */
38
+ export declare function lintWiki(wikiDir: string, cwd: string, options?: WikiLintOptions): WikiLintReport;
39
+ /**
40
+ * Render a lint report as compact markdown (agent/tool output).
41
+ *
42
+ * @param report - The computed report.
43
+ * @param cap - Max items per section (default 25).
44
+ * @returns Markdown report; a short "no wiki" text when the wiki is absent.
45
+ */
46
+ export declare function formatLintReport(report: WikiLintReport, cap?: number): string;
47
+ /** JSON-safe plain object of a report (CLI `--json`). */
48
+ export declare function lintReportToJson(report: WikiLintReport): Record<string, unknown>;
@@ -0,0 +1,134 @@
1
+ /**
2
+ * @fileoverview Deterministic wiki health report — the computed half of
3
+ * `/wiki lint`. Everything here is machine-decidable (graph structure,
4
+ * frontmatter, git-vs-lastReviewed); the judgment checks (contradictions,
5
+ * "important concepts lacking a page") stay the agent's job and are listed
6
+ * as such in the report footer.
7
+ */
8
+ import * as path from "node:path";
9
+ import { getWikiGraph } from "./graph.js";
10
+ import { computeStaleness, formatPageStaleness, stalenessCounts, } from "./staleness.js";
11
+ /**
12
+ * Run the deterministic lint pass.
13
+ *
14
+ * @param wikiDir - Absolute path to `.opencode/wiki`.
15
+ * @param cwd - Workspace root (sourceRefs resolve against it).
16
+ * @param options - Limits.
17
+ * @returns The report; `exists: false` when there is no wiki yet.
18
+ */
19
+ export function lintWiki(wikiDir, cwd, options = {}) {
20
+ const graph = getWikiGraph(wikiDir, { maxPages: options.maxPages });
21
+ if (!graph.exists) {
22
+ const staleness = { pages: [], notes: [] };
23
+ return {
24
+ wikiDir,
25
+ exists: false,
26
+ pageCount: 0,
27
+ contentPages: 0,
28
+ truncated: false,
29
+ orphans: [],
30
+ dangling: [],
31
+ uncataloged: [],
32
+ indexEntriesMissingFile: [],
33
+ pagesMissingFrontmatter: [],
34
+ frontmatterIssues: [],
35
+ staleness,
36
+ findingCount: 0,
37
+ };
38
+ }
39
+ const staleness = computeStaleness(graph, cwd, { maxCommits: options.maxCommits, nowMs: options.nowMs });
40
+ const counts = stalenessCounts(staleness);
41
+ const contentPages = [...graph.pages.values()].filter((p) => p.isContent).length;
42
+ const findingCount = graph.orphans.length +
43
+ graph.dangling.length +
44
+ graph.uncataloged.length +
45
+ graph.pagesMissingFrontmatter.length +
46
+ graph.frontmatterIssues.length +
47
+ counts.stale +
48
+ counts["missing-refs"];
49
+ return {
50
+ wikiDir,
51
+ exists: true,
52
+ pageCount: graph.pageCount,
53
+ contentPages,
54
+ truncated: graph.truncated,
55
+ orphans: graph.orphans,
56
+ dangling: graph.dangling,
57
+ uncataloged: graph.uncataloged,
58
+ indexEntriesMissingFile: graph.indexEntriesMissingFile,
59
+ pagesMissingFrontmatter: graph.pagesMissingFrontmatter,
60
+ frontmatterIssues: graph.frontmatterIssues,
61
+ staleness,
62
+ findingCount,
63
+ };
64
+ }
65
+ /** Cap list rendering so the report stays token-lean. */
66
+ function cappedList(items, cap) {
67
+ const shown = items.slice(0, cap).map((i) => `\`${i}\``).join(", ");
68
+ return items.length > cap ? `${shown} (+${items.length - cap} more)` : shown;
69
+ }
70
+ /**
71
+ * Render a lint report as compact markdown (agent/tool output).
72
+ *
73
+ * @param report - The computed report.
74
+ * @param cap - Max items per section (default 25).
75
+ * @returns Markdown report; a short "no wiki" text when the wiki is absent.
76
+ */
77
+ export function formatLintReport(report, cap = 25) {
78
+ if (!report.exists) {
79
+ return `No wiki at \`${report.wikiDir}\`. Run \`/wiki seed\` to generate the initial pages.`;
80
+ }
81
+ const lines = [];
82
+ lines.push(`**Wiki lint** — ${report.pageCount} pages (${report.contentPages} content)` +
83
+ (report.truncated ? " _(scan hit the page cap)_" : ""));
84
+ lines.push(`Deterministic findings: **${report.findingCount}**`);
85
+ lines.push("");
86
+ const stalePages = report.staleness.pages.filter((p) => p.state === "stale");
87
+ const missingPages = report.staleness.pages.filter((p) => p.state === "missing-refs");
88
+ const unknownPages = report.staleness.pages.filter((p) => p.state === "unknown");
89
+ lines.push(`- **Stale pages** (sourceRefs changed after lastReviewed): ${stalePages.length}`);
90
+ for (const p of stalePages.slice(0, cap))
91
+ lines.push(...formatPageStaleness(p));
92
+ if (stalePages.length > cap)
93
+ lines.push(` _(… +${stalePages.length - cap} more pages)_`);
94
+ lines.push(`- **Dead sourceRefs** (file no longer exists): ${missingPages.length}`);
95
+ for (const p of missingPages.slice(0, cap))
96
+ lines.push(...formatPageStaleness(p));
97
+ lines.push(`- **Pages missing lastReviewed** (cannot judge staleness): ${unknownPages.length}`);
98
+ if (unknownPages.length > 0)
99
+ lines.push(` ${cappedList(unknownPages.map((p) => p.id), cap)}`);
100
+ lines.push(`- **Orphans** (no inbound link from a content page): ${report.orphans.length}`);
101
+ if (report.orphans.length > 0)
102
+ lines.push(` ${cappedList(report.orphans, cap)}`);
103
+ lines.push(`- **Dangling links** (resolve to no page): ${report.dangling.length}`);
104
+ for (const d of report.dangling.slice(0, cap))
105
+ lines.push(` \`${d.fromId}\` → [[${d.raw}]]`);
106
+ if (report.dangling.length > cap)
107
+ lines.push(` _(… +${report.dangling.length - cap} more)_`);
108
+ lines.push(`- **Uncataloged** (content page not linked from index.md): ${report.uncataloged.length}`);
109
+ if (report.uncataloged.length > 0)
110
+ lines.push(` ${cappedList(report.uncataloged, cap)}`);
111
+ if (report.indexEntriesMissingFile.length > 0) {
112
+ lines.push(`- **index.md entries with no file**: ${report.indexEntriesMissingFile.length}`);
113
+ for (const d of report.indexEntriesMissingFile.slice(0, cap))
114
+ lines.push(` index.md → [[${d.raw}]]`);
115
+ }
116
+ lines.push(`- **Pages without frontmatter**: ${report.pagesMissingFrontmatter.length}`);
117
+ if (report.pagesMissingFrontmatter.length > 0)
118
+ lines.push(` ${cappedList(report.pagesMissingFrontmatter, cap)}`);
119
+ if (report.frontmatterIssues.length > 0) {
120
+ lines.push(`- **Frontmatter issues**: ${report.frontmatterIssues.length}`);
121
+ for (const i of report.frontmatterIssues.slice(0, cap))
122
+ lines.push(` \`${i.id}\`: ${i.message}`);
123
+ }
124
+ for (const note of report.staleness.notes)
125
+ lines.push(`_Note:_ ${note}`);
126
+ lines.push("");
127
+ lines.push("_Judgment checks the tool cannot compute — do these as the agent:_ contradictions between pages; concepts mentioned in 3+ pages without their own page; pages that lost their reason to exist.");
128
+ return lines.join("\n");
129
+ }
130
+ /** JSON-safe plain object of a report (CLI `--json`). */
131
+ export function lintReportToJson(report) {
132
+ return JSON.parse(JSON.stringify({ ...report, wikiDirRel: path.basename(path.dirname(report.wikiDir)) }));
133
+ }
134
+ //# sourceMappingURL=lint.js.map
@@ -0,0 +1,97 @@
1
+ /**
2
+ * @fileoverview Parses wiki pages — frontmatter, `[[wikilinks]]`, titles.
3
+ *
4
+ * Pure functions over strings: no filesystem access here (scanning lives in
5
+ * `graph.ts`). The frontmatter reader is deliberately minimal — the wiki
6
+ * protocol (built-in `wikiMode.systemPrompt`) defines exactly four keys, so a
7
+ * purpose-built parser beats a YAML dependency.
8
+ *
9
+ * Link extraction ignores fenced code blocks and inline code spans: the wiki
10
+ * protocol and doc-style pages quote literal `[[wiki/page-name]]` examples,
11
+ * and counting those as links would poison every orphan/dangling report.
12
+ */
13
+ /** A single `[[target]]`, `[[target|alias]]` or `[[target#anchor]]` link. */
14
+ export interface WikiLink {
15
+ /** Text inside the brackets, as written (e.g. `wiki/plugin#usage`). */
16
+ raw: string;
17
+ /** Link target without alias/anchor, trimmed (e.g. `wiki/plugin`). */
18
+ target: string;
19
+ /** Optional `#section` suffix. */
20
+ anchor?: string;
21
+ /** Optional `|display text` suffix. */
22
+ alias?: string;
23
+ }
24
+ /** One problem found while parsing a page's frontmatter block. */
25
+ export interface FrontmatterIssue {
26
+ key?: string;
27
+ message: string;
28
+ }
29
+ /** Frontmatter of a wiki page, parsed against the four protocol keys. */
30
+ export interface ParsedFrontmatter {
31
+ /** Whether a `---` delimited block was present at the top of the file. */
32
+ present: boolean;
33
+ title?: string;
34
+ tags: string[];
35
+ sourceRefs: string[];
36
+ /** Raw `lastReviewed` value as written (kept for display). */
37
+ lastReviewedRaw?: string;
38
+ /** Parsed `lastReviewed` as epoch milliseconds, or undefined when unparseable. */
39
+ lastReviewedMs?: number;
40
+ /** Parse problems (missing/placeholder date, duplicate key, unknown shape). */
41
+ issues: FrontmatterIssue[];
42
+ }
43
+ /** A parsed wiki page: metadata, links, and the first H1 title if any. */
44
+ export interface ParsedWikiPage {
45
+ frontmatter: ParsedFrontmatter;
46
+ /** Best display title: frontmatter title → first `# heading` → file name. */
47
+ headingTitle?: string;
48
+ /** Links in document order, fenced code and inline code excluded. */
49
+ links: WikiLink[];
50
+ /** Number of inbound/outbound-relevant non-empty links (diagnostics). */
51
+ wordCount: number;
52
+ }
53
+ /**
54
+ * Normalize a path or link target for comparison: posix separators, no
55
+ * `.md`/`.markdown` suffix, no leading `.opencode/wiki/`, `wiki/` or `./`
56
+ * prefix, lowercased. `entities/plugin.md`, `wiki/entities/plugin` and
57
+ * `.opencode/wiki/entities/plugin` all normalize to `entities/plugin`.
58
+ *
59
+ * @param target - A path or wikilink target.
60
+ * @returns The normalized page id, or an empty string when nothing remains.
61
+ */
62
+ export declare function normalizePageId(target: string): string;
63
+ /**
64
+ * Extract the basename of a normalized page id (`entities/plugin` → `plugin`).
65
+ *
66
+ * @param pageId - A normalized page id.
67
+ * @returns The last path segment.
68
+ */
69
+ export declare function pageBasename(pageId: string): string;
70
+ /**
71
+ * Parse the YAML frontmatter block of a wiki page.
72
+ *
73
+ * Accepts only the protocol keys (`title`, `tags`, `sourceRefs`,
74
+ * `lastReviewed`); other keys are ignored. Handles scalar values, inline
75
+ * arrays, comma lists, and `- item` block lists. Does NOT enforce the
76
+ * protocol — missing frontmatter is a finding for the lint layer, not an
77
+ * error here.
78
+ *
79
+ * @param content - Full page content (CRLF normalized internally).
80
+ * @returns Parsed frontmatter; `present: false` when the block is absent.
81
+ */
82
+ export declare function parseFrontmatter(content: string): ParsedFrontmatter;
83
+ /**
84
+ * Extract wikilinks from page content, skipping fenced code blocks (``` /
85
+ * ~~~) and inline backtick spans.
86
+ *
87
+ * @param content - Full page content.
88
+ * @returns Links in document order.
89
+ */
90
+ export declare function parseWikiLinks(content: string): WikiLink[];
91
+ /**
92
+ * Parse a wiki page from its raw content.
93
+ *
94
+ * @param content - The full file content.
95
+ * @returns Frontmatter, best title, links, and a rough word count.
96
+ */
97
+ export declare function parseWikiPage(content: string): ParsedWikiPage;