opencode-rag-plugin 2.13.5 → 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,231 @@
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
+ /**
14
+ * Normalize a path or link target for comparison: posix separators, no
15
+ * `.md`/`.markdown` suffix, no leading `.opencode/wiki/`, `wiki/` or `./`
16
+ * prefix, lowercased. `entities/plugin.md`, `wiki/entities/plugin` and
17
+ * `.opencode/wiki/entities/plugin` all normalize to `entities/plugin`.
18
+ *
19
+ * @param target - A path or wikilink target.
20
+ * @returns The normalized page id, or an empty string when nothing remains.
21
+ */
22
+ export function normalizePageId(target) {
23
+ let id = target.trim().replace(/\\/g, "/");
24
+ id = id.replace(/\.(md|markdown)$/i, "");
25
+ id = id.replace(/^\.\//, "");
26
+ id = id.replace(/^(\.opencode\/)?wiki\//i, "");
27
+ id = id.replace(/\/+$/, "").replace(/^\/+/, "");
28
+ return id.toLowerCase();
29
+ }
30
+ /**
31
+ * Extract the basename of a normalized page id (`entities/plugin` → `plugin`).
32
+ *
33
+ * @param pageId - A normalized page id.
34
+ * @returns The last path segment.
35
+ */
36
+ export function pageBasename(pageId) {
37
+ const idx = pageId.lastIndexOf("/");
38
+ return idx >= 0 ? pageId.slice(idx + 1) : pageId;
39
+ }
40
+ /** Strip surrounding single/double quotes and whitespace from a scalar value. */
41
+ function unquote(value) {
42
+ const v = value.trim();
43
+ if (v.length >= 2 && ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))) {
44
+ return v.slice(1, -1).trim();
45
+ }
46
+ return v;
47
+ }
48
+ /** Parse an inline `[a, b, c]` array or a comma-separated scalar into items. */
49
+ function splitList(value) {
50
+ const inner = /^\[(.*)\]$/.exec(value)?.[1] ?? value;
51
+ return inner
52
+ .split(",")
53
+ .map((s) => unquote(s))
54
+ .filter((s) => s.length > 0);
55
+ }
56
+ /**
57
+ * Parse `lastReviewed` leniently: bare `YYYY-MM-DD`, optional time, or any
58
+ * string `Date.parse` accepts. Placeholder values like `<date>` (copied from
59
+ * the protocol template by seeding agents) are reported, not parsed.
60
+ */
61
+ function parseReviewDate(raw) {
62
+ const v = unquote(raw);
63
+ if (v.length === 0)
64
+ return { issue: "lastReviewed is empty" };
65
+ if (/^<.*>$/.test(v))
66
+ return { issue: `lastReviewed is an unreplaced placeholder ("${v}")` };
67
+ const m = /^(\d{4})-(\d{2})-(\d{2})(?:[T ]\d{2}:\d{2}(?::\d{2})?(?:Z|[+-]\d{2}:?\d{2})?)?$/.exec(v);
68
+ if (!m) {
69
+ const fallback = Date.parse(v);
70
+ return Number.isFinite(fallback)
71
+ ? { ms: fallback }
72
+ : { issue: `lastReviewed is not a date ("${v}")` };
73
+ }
74
+ const ms = Date.parse(m[0].includes("T") ? m[0] : `${m[0]}T00:00:00`);
75
+ return Number.isFinite(ms) ? { ms } : { issue: `lastReviewed is not a real date ("${v}")` };
76
+ }
77
+ /**
78
+ * Parse the YAML frontmatter block of a wiki page.
79
+ *
80
+ * Accepts only the protocol keys (`title`, `tags`, `sourceRefs`,
81
+ * `lastReviewed`); other keys are ignored. Handles scalar values, inline
82
+ * arrays, comma lists, and `- item` block lists. Does NOT enforce the
83
+ * protocol — missing frontmatter is a finding for the lint layer, not an
84
+ * error here.
85
+ *
86
+ * @param content - Full page content (CRLF normalized internally).
87
+ * @returns Parsed frontmatter; `present: false` when the block is absent.
88
+ */
89
+ export function parseFrontmatter(content) {
90
+ const text = content.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
91
+ const result = { present: false, tags: [], sourceRefs: [], issues: [] };
92
+ const lines = text.split("\n");
93
+ if (lines[0]?.trim() !== "---")
94
+ return result;
95
+ result.present = true;
96
+ let end = -1;
97
+ for (let i = 1; i < lines.length; i++) {
98
+ const t = lines[i].trim();
99
+ if (t === "---" || t === "...") {
100
+ end = i;
101
+ break;
102
+ }
103
+ }
104
+ if (end < 0) {
105
+ result.issues.push({ message: "frontmatter block is never closed" });
106
+ end = lines.length;
107
+ }
108
+ const seen = new Set();
109
+ let currentListKey;
110
+ let pendingList = [];
111
+ const flushPending = () => {
112
+ if (currentListKey && pendingList.length > 0) {
113
+ if (currentListKey === "tags")
114
+ result.tags = pendingList.slice();
115
+ else if (currentListKey === "sourceRefs")
116
+ result.sourceRefs = pendingList.slice();
117
+ }
118
+ pendingList = [];
119
+ currentListKey = undefined;
120
+ };
121
+ for (let i = 1; i < end; i++) {
122
+ const line = lines[i];
123
+ const itemMatch = /^\s+-\s+(.*)$/.exec(line);
124
+ if (itemMatch && currentListKey) {
125
+ pendingList.push(unquote(itemMatch[1]));
126
+ continue;
127
+ }
128
+ flushPending();
129
+ const kv = /^([A-Za-z][\w-]*):[ \t]*(.*)$/.exec(line);
130
+ if (!kv)
131
+ continue;
132
+ const key = kv[1];
133
+ const value = kv[2].trim();
134
+ if (seen.has(key))
135
+ result.issues.push({ key, message: `duplicate key "${key}" (last one wins)` });
136
+ seen.add(key);
137
+ switch (key) {
138
+ case "title":
139
+ result.title = unquote(value) || undefined;
140
+ break;
141
+ case "tags":
142
+ case "sourceRefs": {
143
+ if (value.length === 0) {
144
+ // Block list may follow: collect `- item` lines until the next key.
145
+ currentListKey = key;
146
+ pendingList = [];
147
+ }
148
+ else if (value === "[]") {
149
+ // explicit empty list
150
+ }
151
+ else {
152
+ const items = splitList(value);
153
+ if (key === "tags")
154
+ result.tags = items;
155
+ else
156
+ result.sourceRefs = items;
157
+ }
158
+ break;
159
+ }
160
+ case "lastReviewed": {
161
+ result.lastReviewedRaw = unquote(value);
162
+ const parsed = parseReviewDate(value);
163
+ if (parsed.ms !== undefined)
164
+ result.lastReviewedMs = parsed.ms;
165
+ if (parsed.issue)
166
+ result.issues.push({ key, message: parsed.issue });
167
+ break;
168
+ }
169
+ default:
170
+ break; // unknown keys are legal, just not protocol keys
171
+ }
172
+ }
173
+ flushPending();
174
+ return result;
175
+ }
176
+ /**
177
+ * Extract wikilinks from page content, skipping fenced code blocks (``` /
178
+ * ~~~) and inline backtick spans.
179
+ *
180
+ * @param content - Full page content.
181
+ * @returns Links in document order.
182
+ */
183
+ export function parseWikiLinks(content) {
184
+ const text = content.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
185
+ const links = [];
186
+ let inFence = false;
187
+ for (const line of text.split("\n")) {
188
+ if (/^\s*(```|~~~)/.test(line)) {
189
+ inFence = !inFence;
190
+ continue;
191
+ }
192
+ if (inFence)
193
+ continue;
194
+ // Drop inline code spans so `[[wiki/example]]` in prose is not a link.
195
+ const scrubbed = line.replace(/`[^`\n]*`/g, "");
196
+ for (const m of scrubbed.matchAll(/\[\[([^\][\n]+)\]\]/g)) {
197
+ const raw = m[1].trim();
198
+ if (raw.length === 0)
199
+ continue;
200
+ const [targetPart, ...aliasParts] = raw.split("|");
201
+ const alias = aliasParts.length > 0 ? aliasParts.join("|").trim() : undefined;
202
+ const [target, ...anchorParts] = (targetPart ?? "").split("#");
203
+ const anchor = anchorParts.length > 0 ? anchorParts.join("#").trim() : undefined;
204
+ const targetClean = (target ?? "").trim();
205
+ if (targetClean.length === 0)
206
+ continue;
207
+ links.push({ raw, target: targetClean, anchor, alias });
208
+ }
209
+ }
210
+ return links;
211
+ }
212
+ /**
213
+ * Parse a wiki page from its raw content.
214
+ *
215
+ * @param content - The full file content.
216
+ * @returns Frontmatter, best title, links, and a rough word count.
217
+ */
218
+ export function parseWikiPage(content) {
219
+ const frontmatter = parseFrontmatter(content);
220
+ const links = parseWikiLinks(content);
221
+ const body = frontmatter.present ? content.replace(/^---[\s\S]*?\n---/, "") : content;
222
+ const h1 = /^#\s+(.+)$/m.exec(body);
223
+ const wordCount = body.split(/\s+/).filter((w) => w.length > 0).length;
224
+ return {
225
+ frontmatter,
226
+ headingTitle: h1?.[1]?.trim(),
227
+ links,
228
+ wordCount,
229
+ };
230
+ }
231
+ //# sourceMappingURL=page-parse.js.map
@@ -0,0 +1,52 @@
1
+ import type { WikiGraph } from "./graph.js";
2
+ /** Refs that move with every release and carry no page-specific signal. */
3
+ export declare const LOW_SIGNAL_REFS: ReadonlySet<string>;
4
+ /** Permitted staleness states of a single sourceRef. */
5
+ export type SourceRefState = "fresh" | "changed" | "dirty" | "missing" | "low-signal" | "unchecked";
6
+ /** One page's sourceRef evaluated against git + disk. */
7
+ export interface SourceRefStatus {
8
+ /** Ref as written in the frontmatter. */
9
+ ref: string;
10
+ state: SourceRefState;
11
+ /** Newest commit touching the ref (unix seconds), when known. */
12
+ touchedAt?: number;
13
+ }
14
+ /** Staleness verdict for one wiki page. */
15
+ export interface PageStaleness {
16
+ /** Normalized page id. */
17
+ id: string;
18
+ /** Raw lastReviewed value as written, if any. */
19
+ lastReviewedRaw?: string;
20
+ /** Parsed review date (epoch ms), if parseable. */
21
+ lastReviewedMs?: number;
22
+ /** Overall state: stale > missing > unchecked-lastReviewed > fresh. */
23
+ state: "fresh" | "stale" | "missing-refs" | "unknown";
24
+ refs: SourceRefStatus[];
25
+ }
26
+ /** Options for the staleness pass. */
27
+ export interface StalenessOptions {
28
+ /** Max commits walked by the single `git log` (default 500, like the prototype). */
29
+ maxCommits?: number;
30
+ /** Page count cap already applied by the graph layer (unused here). */
31
+ nowMs?: number;
32
+ }
33
+ /** Result of a staleness pass over a wiki graph. */
34
+ export interface StalenessResult {
35
+ /** Per-page verdicts (content pages only). */
36
+ pages: PageStaleness[];
37
+ /** Human-readable caveats: not a git repo, history truncated, git failed. */
38
+ notes: string[];
39
+ }
40
+ /**
41
+ * Compute staleness for every content page in the graph.
42
+ *
43
+ * @param graph - Built wiki graph (pages carry their parsed frontmatter).
44
+ * @param cwd - Workspace root — the base sourceRefs resolve against.
45
+ * @param options - Walk limits.
46
+ * @returns Per-page verdicts plus operational notes.
47
+ */
48
+ export declare function computeStaleness(graph: WikiGraph, cwd: string, options?: StalenessOptions): StalenessResult;
49
+ /** Count helper for summary lines. */
50
+ export declare function stalenessCounts(result: StalenessResult): Record<PageStaleness["state"], number>;
51
+ /** Format one page's staleness for markdown output. */
52
+ export declare function formatPageStaleness(page: PageStaleness): string[];
@@ -0,0 +1,184 @@
1
+ /**
2
+ * @fileoverview Wiki staleness: `sourceRefs` vs git reality.
3
+ *
4
+ * A page is STALE when any file sourceRef was committed after the page's
5
+ * `lastReviewed`, MISSING when the ref no longer exists (a real defect, not
6
+ * staleness), DIRTY when the ref has uncommitted changes, and LOW-SIGNAL when
7
+ * only refs that churn with every release (AGENTS.md, README.md, LICENSE)
8
+ * moved — following the rules the repo's own `wiki-lint.cjs` prototype
9
+ * measured: day-granular review cutoff, low-signal churn reported separately,
10
+ * dead refs kept distinct from drift.
11
+ *
12
+ * Cost model: the git walk is ONE bounded `git log` for the whole wiki (the
13
+ * oldest review date sets the window), plus the standard working-tree diff —
14
+ * not one spawn per sourceRef.
15
+ */
16
+ import { existsSync } from "node:fs";
17
+ import * as path from "node:path";
18
+ import { getRepoRoot, getWorkingTreeChanges, getFileTouchTimestamps, } from "../indexer/git-diff.js";
19
+ /** Refs that move with every release and carry no page-specific signal. */
20
+ export const LOW_SIGNAL_REFS = new Set(["agents.md", "readme.md", "license"]);
21
+ /** Classify a sourceRef: url-ish refs can't be git-checked. */
22
+ function classifyRef(ref) {
23
+ return /^[a-z][a-z0-9+.-]*:\/\//i.test(ref) ? "url" : "file";
24
+ }
25
+ /** Normalize a repo path (posix, from git) for comparison. */
26
+ function norm(p) {
27
+ return p.replace(/\\/g, "/").toLowerCase();
28
+ }
29
+ /** Convert a repo-root-relative path to workspace-relative posix, or null. */
30
+ function repoToWorkspace(repoRoot, cwd, repoRel) {
31
+ const abs = path.resolve(repoRoot, repoRel);
32
+ const rel = path.relative(cwd, abs);
33
+ if (rel.startsWith("..") || path.isAbsolute(rel))
34
+ return null;
35
+ return rel.replace(/\\/g, "/");
36
+ }
37
+ /**
38
+ * Compute staleness for every content page in the graph.
39
+ *
40
+ * @param graph - Built wiki graph (pages carry their parsed frontmatter).
41
+ * @param cwd - Workspace root — the base sourceRefs resolve against.
42
+ * @param options - Walk limits.
43
+ * @returns Per-page verdicts plus operational notes.
44
+ */
45
+ export function computeStaleness(graph, cwd, options = {}) {
46
+ const notes = [];
47
+ const nowMs = options.nowMs ?? Date.now();
48
+ const maxCommits = options.maxCommits ?? 500;
49
+ const contentPages = [...graph.pages.values()].filter((p) => p.isContent);
50
+ // Window: one day before the oldest review date (all we need to compare).
51
+ const reviewDates = contentPages
52
+ .map((p) => p.parsed.frontmatter.lastReviewedMs)
53
+ .filter((d) => typeof d === "number");
54
+ const windowStartMs = reviewDates.length > 0
55
+ ? Math.min(...reviewDates) - 24 * 3600_000
56
+ : nowMs - 90 * 24 * 3600_000; // no dates at all: last quarter
57
+ const sinceIso = new Date(windowStartMs).toISOString().slice(0, 10);
58
+ const repoRoot = getRepoRoot(cwd);
59
+ let touchByWorkspacePath = null;
60
+ if (repoRoot) {
61
+ const logResult = getFileTouchTimestamps(cwd, sinceIso, maxCommits);
62
+ if (logResult) {
63
+ touchByWorkspacePath = new Map();
64
+ for (const [repoRel, ts] of logResult.timestamps) {
65
+ const wsRel = repoToWorkspace(repoRoot, cwd, repoRel);
66
+ if (wsRel === null)
67
+ continue;
68
+ const existing = touchByWorkspacePath.get(wsRel.toLowerCase());
69
+ if (existing === undefined || ts > existing)
70
+ touchByWorkspacePath.set(wsRel.toLowerCase(), ts);
71
+ }
72
+ if (logResult.truncated) {
73
+ notes.push(`git history walk hit the ${maxCommits}-commit cap — older changes may be unreported`);
74
+ }
75
+ }
76
+ else {
77
+ notes.push("git log walk failed — staleness falls back to disk-existence checks only");
78
+ }
79
+ }
80
+ else {
81
+ notes.push("workspace is not a git repository — staleness falls back to disk-existence checks only");
82
+ }
83
+ // Uncommitted drift counts too: a modified/untracked source is unreviewed.
84
+ const dirtySet = new Set();
85
+ if (repoRoot) {
86
+ const wt = getWorkingTreeChanges(cwd);
87
+ if (wt) {
88
+ for (const list of [wt.changedFiles, wt.untrackedFiles]) {
89
+ for (const repoRel of list) {
90
+ const wsRel = repoToWorkspace(repoRoot, cwd, repoRel);
91
+ if (wsRel)
92
+ dirtySet.add(wsRel.toLowerCase());
93
+ }
94
+ }
95
+ }
96
+ }
97
+ const pages = [];
98
+ for (const page of contentPages) {
99
+ const fm = page.parsed.frontmatter;
100
+ const cutoff = fm.lastReviewedMs !== undefined
101
+ ? Math.floor((fm.lastReviewedMs + 24 * 3600_000 - 1) / 1000) // day-granular: review day counts as reviewed
102
+ : undefined;
103
+ const refs = [];
104
+ let staleCount = 0;
105
+ let missingCount = 0;
106
+ let lowSignalHits = 0;
107
+ for (const raw of fm.sourceRefs) {
108
+ if (classifyRef(raw) === "url") {
109
+ refs.push({ ref: raw, state: "unchecked" });
110
+ continue;
111
+ }
112
+ const refPath = raw.replace(/\\/g, "/").replace(/^\.\//, "");
113
+ const key = norm(refPath);
114
+ const absRef = path.isAbsolute(refPath) ? refPath : path.resolve(cwd, refPath);
115
+ if (!existsSync(absRef)) {
116
+ refs.push({ ref: raw, state: "missing" });
117
+ missingCount++;
118
+ continue;
119
+ }
120
+ const isLowSignal = LOW_SIGNAL_REFS.has(key);
121
+ const dirty = dirtySet.has(key);
122
+ const touched = touchByWorkspacePath?.get(key);
123
+ const moved = (touched !== undefined && cutoff !== undefined && touched > cutoff) || dirty;
124
+ if (moved && isLowSignal) {
125
+ refs.push({ ref: raw, state: "low-signal", touchedAt: touched });
126
+ lowSignalHits++;
127
+ }
128
+ else if (moved) {
129
+ refs.push({ ref: raw, state: dirty && !(touched !== undefined && cutoff !== undefined && touched > cutoff) ? "dirty" : "changed", touchedAt: touched });
130
+ staleCount++;
131
+ }
132
+ else {
133
+ refs.push({ ref: raw, state: "fresh", touchedAt: touched });
134
+ }
135
+ }
136
+ const state = staleCount > 0 ? "stale"
137
+ : missingCount > 0 ? "missing-refs"
138
+ : fm.lastReviewedMs === undefined ? "unknown"
139
+ : "fresh";
140
+ pages.push({
141
+ id: page.id,
142
+ lastReviewedRaw: fm.lastReviewedRaw,
143
+ lastReviewedMs: fm.lastReviewedMs,
144
+ state,
145
+ refs,
146
+ });
147
+ }
148
+ const flagged = pages.filter((p) => p.state === "stale" || p.state === "missing-refs").length;
149
+ const lowSignalOnly = pages.filter((p) => p.state === "fresh" && p.refs.some((r) => r.state === "low-signal")).length;
150
+ if (lowSignalOnly > 0) {
151
+ notes.push(`${lowSignalOnly} page(s) moved only through low-signal refs (AGENTS.md/README.md/LICENSE) — intentionally not flagged`);
152
+ }
153
+ notes.unshift(`${flagged} of ${pages.length} content page(s) flagged`);
154
+ if (!touchByWorkspacePath) {
155
+ // existence-only mode already announced via the notes above
156
+ }
157
+ pages.sort((a, b) => a.id.localeCompare(b.id));
158
+ return { pages, notes };
159
+ }
160
+ /** Count helper for summary lines. */
161
+ export function stalenessCounts(result) {
162
+ const counts = { fresh: 0, stale: 0, "missing-refs": 0, unknown: 0 };
163
+ for (const p of result.pages)
164
+ counts[p.state]++;
165
+ return counts;
166
+ }
167
+ /** Format one page's staleness for markdown output. */
168
+ export function formatPageStaleness(page) {
169
+ const lines = [];
170
+ const date = page.lastReviewedRaw ?? "(none)";
171
+ lines.push(`- \`${page.id}\` — ${page.state.toUpperCase()} (lastReviewed ${date})`);
172
+ for (const r of page.refs) {
173
+ if (r.state === "fresh" || r.state === "low-signal" || r.state === "unchecked")
174
+ continue;
175
+ const when = r.touchedAt ? new Date(r.touchedAt * 1000).toISOString().slice(0, 10) : undefined;
176
+ lines.push(` ${r.state}: ${r.ref}${when ? ` (commit ${when})` : ""}`);
177
+ }
178
+ const low = page.refs.filter((r) => r.state === "low-signal");
179
+ if (low.length > 0) {
180
+ lines.push(` (low-signal churn: ${low.map((r) => r.ref).join(", ")})`);
181
+ }
182
+ return lines;
183
+ }
184
+ //# sourceMappingURL=staleness.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-rag-plugin",
3
- "version": "2.13.5",
3
+ "version": "2.13.6",
4
4
  "description": "OpenCode plugin for local-first RAG-based semantic code search",
5
5
  "type": "module",
6
6
  "main": "./dist/plugin-entry.js",