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.
package/ReadMe.md CHANGED
@@ -388,11 +388,20 @@ Progress is saved in `.opencode/rag_db/doc-mode-progress.json`, so later session
388
388
 
389
389
  On by default. When `wikiMode.enabled` is `true`, the plugin injects a wiki-maintainer system prompt. The agent builds and maintains a persistent knowledge wiki in `.opencode/wiki/`: interlinked markdown pages that synthesize knowledge from the codebase, docs, and conversations.
390
390
 
391
+ Two read-only agent tools make the mechanical wiki questions one-call answers instead of grep sweeps (registered when `wikiMode.tools` is `true`, the default):
392
+
393
+ | Tool | Purpose |
394
+ |---|---|
395
+ | `wiki_graph` | Link-graph queries: backlinks, outlinks, neighborhood, orphans, dangling links, overview — rebuilt from the files on every call, so it is never stale |
396
+ | `wiki_lint` | Deterministic health report: git-verified staleness (`sourceRefs` committed after `lastReviewed`), dead refs, uncommitted drift, structure, frontmatter and `index.md` coverage |
397
+
398
+ The same engine backs a provider-free CLI (`opencode-rag wiki status/graph/lint`) and the `/wiki` slash command:
399
+
391
400
  | Command | Action |
392
401
  |---|---|
393
- | `/wiki` | Show wiki status (page count, subdirectories, index and log presence, latest log entry) |
402
+ | `/wiki` | Show wiki status (recursive page count, directories, index and log presence, graph health, latest log entry) |
394
403
  | `/wiki seed` | Generate the initial wiki from the README, file structure, and code patterns |
395
- | `/wiki lint` | Health-check for orphan pages, stale source references, contradictions, and missing cross-links |
404
+ | `/wiki lint` | Inject the computed deterministic report, then the agent handles judgment checks (contradictions, concepts lacking a page) and fixes findings |
396
405
 
397
406
  The agent maintains the pages during normal coding sessions; you do not write them yourself. The wiki lives in `.opencode/`, so it is git-trackable and every edit is a diff. See the [plugin docs](doc/plugin.md#6-wiki-mode--slash-command-wiki).
398
407
 
@@ -18,3 +18,4 @@ export { registerEvalTuneCommand } from "./eval-tuner.js";
18
18
  export { registerDescribeImageCommand } from "./describe-image.js";
19
19
  export { registerDecideCommand } from "./decide.js";
20
20
  export { registerQuirkCommand } from "./quirk.js";
21
+ export { registerWikiCommand } from "./wiki.js";
@@ -18,4 +18,5 @@ export { registerEvalTuneCommand } from "./eval-tuner.js";
18
18
  export { registerDescribeImageCommand } from "./describe-image.js";
19
19
  export { registerDecideCommand } from "./decide.js";
20
20
  export { registerQuirkCommand } from "./quirk.js";
21
+ export { registerWikiCommand } from "./wiki.js";
21
22
  //# sourceMappingURL=index.js.map
@@ -7,6 +7,7 @@ import { getRuntimeDir, getVersionFile, readVersionFile, setupRuntime, } from ".
7
7
  import { compareVersions, getCurrentVersion, installLatestUpdate } from "../../core/version-check.js";
8
8
  import { bestAvailablePackageManager, globalUninstallCommand } from "../../core/package-manager.js";
9
9
  import { globalConfigPath, loadWorkspaceRawConfig, migrateLegacyProjectConfig, findConfigFile, projectConfigPath, } from "../../core/config.js";
10
+ import { readGitignoreExclusions, mergeExclusionLists } from "../../core/gitignore-exclusions.js";
10
11
  import { createPrompter } from "../prompt.js";
11
12
  import { hasExplicitSetupFlags, answersFromFlags, runSetupWizard, } from "../wizard/flow.js";
12
13
  import { buildConfigPatch, findShadowingProviderKeys, readJsonObjectSafe, removeConfigPaths, writeConfigPatch, } from "../wizard/apply.js";
@@ -385,6 +386,40 @@ async function runSetup(rawOptions) {
385
386
  configPath,
386
387
  workspacePlugin: pluginMode === "workspace",
387
388
  });
389
+ // --- .gitignore -> indexing exclusions ---
390
+ // Paths git ignores (build output, binaries, caches) must never be
391
+ // embedded; instead of asking users to maintain two lists, merge the
392
+ // gitignore patterns into the workspace config. Additive and idempotent:
393
+ // existing entries (and their order) are preserved, only missing
394
+ // patterns are appended. Requires a re-index to take effect.
395
+ try {
396
+ if (existsSync(path.join(cwd, ".gitignore")) && existsSync(configPath)) {
397
+ const derived = readGitignoreExclusions(cwd);
398
+ const rawCfg = readJsonObjectSafe(configPath);
399
+ const indexingSection = rawCfg.indexing;
400
+ const current = indexingSection && typeof indexingSection === "object" && !Array.isArray(indexingSection)
401
+ ? indexingSection
402
+ : {};
403
+ const existingDirs = Array.isArray(current.excludeDirs) ? current.excludeDirs : [];
404
+ const existingFiles = Array.isArray(current.excludeFiles) ? current.excludeFiles : [];
405
+ const mergedDirs = mergeExclusionLists(existingDirs, derived.dirs);
406
+ const mergedFiles = mergeExclusionLists(existingFiles, derived.files);
407
+ const added = mergedDirs.length - existingDirs.length + mergedFiles.length - existingFiles.length;
408
+ if (added > 0) {
409
+ if (writeConfigPatch(configPath, { indexing: { excludeDirs: mergedDirs, excludeFiles: mergedFiles } })) {
410
+ console.log(`\n ${c.updated("Merged:")} ${c.value(String(added))} .gitignore exclusion(s) into ${c.file(configLabel)}`);
411
+ console.log(` ${c.dim("Run `opencode-rag index` to apply the new exclusions to the index.")}`);
412
+ }
413
+ else {
414
+ console.log(` ${c.warn("Could not merge .gitignore exclusions.")} Check permissions for ${c.file(configPath)}.`);
415
+ }
416
+ }
417
+ }
418
+ }
419
+ catch (err) {
420
+ // A failed migration must not fail setup - it is a convenience merge.
421
+ console.log(` ${c.warn("Skipped .gitignore exclusion merge:")} ${err.message}`);
422
+ }
388
423
  if (!options.skipHealthCheck) {
389
424
  const health = await runWorkspaceHealthCheck(cwd, prompter, { autoPull: answers?.recommended === true });
390
425
  await offerHealthRepairs({
@@ -0,0 +1,11 @@
1
+ /**
2
+ * @fileoverview Wiki command — structure and health reports over
3
+ * `.opencode/wiki/` (status, graph, lint).
4
+ *
5
+ * Provider-free by design: the wiki tools need no store and no embedder, so
6
+ * these commands resolve config for limits only and never touch the vector
7
+ * store — `wiki lint` works on an un-indexed workspace.
8
+ */
9
+ import type { Command } from "commander";
10
+ /** Shared preamble: register the `wiki` command. */
11
+ export declare function registerWikiCommand(program: Command): void;
@@ -0,0 +1,166 @@
1
+ import * as fs from "node:fs";
2
+ import * as path from "node:path";
3
+ import { c, logCliError, logCliInfo } from "../format.js";
4
+ import { loadWorkspaceConfig } from "../../core/config.js";
5
+ import { getWikiGraph, findPage, graphNeighbors } from "../../wiki/graph.js";
6
+ import { lintWiki, formatLintReport } from "../../wiki/lint.js";
7
+ /** Resolve the workspace + wiki dir, honoring --dir. */
8
+ function resolveWikiContext(options) {
9
+ const cwd = path.resolve(options.dir ?? process.cwd());
10
+ let maxPages = 500;
11
+ try {
12
+ const cfg = loadWorkspaceConfig(cwd);
13
+ maxPages = cfg.wikiMode?.maxPages ?? maxPages;
14
+ }
15
+ catch {
16
+ // unreadable config: defaults; the wiki itself is plain files
17
+ }
18
+ return { cwd, wikiDir: path.join(cwd, ".opencode", "wiki"), maxPages };
19
+ }
20
+ /** Shared preamble: register the `wiki` command. */
21
+ export function registerWikiCommand(program) {
22
+ const wikiCmd = program
23
+ .command("wiki")
24
+ .description("Wiki structure and health (status, graph, lint) — no store, no embedder required");
25
+ const logFilePath = (options) => path.join(path.resolve(options.dir ?? process.cwd()), ".opencode", "opencode-rag.log");
26
+ wikiCmd
27
+ .command("status")
28
+ .description("Page count, structure health, latest log entry")
29
+ .option("--dir <path>", "workspace root (default: cwd)")
30
+ .action((options) => {
31
+ try {
32
+ const { wikiDir, maxPages } = resolveWikiContext(options);
33
+ const graph = getWikiGraph(wikiDir, { maxPages });
34
+ if (!graph.exists) {
35
+ logCliInfo(logFilePath(options), "wiki status", `\nNo wiki at .opencode/wiki/ — run \`/wiki seed\` (or seed pages by hand).`);
36
+ return;
37
+ }
38
+ const contentPages = [...graph.pages.values()].filter((n) => n.isContent).length;
39
+ const logPath = path.join(wikiDir, "log.md");
40
+ let lastLog = "";
41
+ if (fs.existsSync(logPath)) {
42
+ const entries = fs.readFileSync(logPath, "utf-8").split("\n").filter((l) => l.startsWith("## ["));
43
+ lastLog = entries[entries.length - 1] ?? "";
44
+ }
45
+ logCliInfo(logFilePath(options), "wiki status", `\n${c.heading("Wiki")} ${c.dim(wikiDir)}`);
46
+ logCliInfo(logFilePath(options), "wiki status", ` ${c.label("Pages:")} ${c.num(graph.pageCount)} (${contentPages} content)${graph.truncated ? ` ${c.warn("(page cap hit — floors only)")}` : ""}`);
47
+ logCliInfo(logFilePath(options), "wiki status", ` ${c.label("Index:")} ${fs.existsSync(path.join(wikiDir, "index.md")) ? "yes" : "no"}`);
48
+ logCliInfo(logFilePath(options), "wiki status", ` ${c.label("Health:")} orphans ${graph.orphans.length}, dangling ${graph.dangling.length}, uncataloged ${graph.uncataloged.length}, missing frontmatter ${graph.pagesMissingFrontmatter.length}`);
49
+ if (lastLog)
50
+ logCliInfo(logFilePath(options), "wiki status", ` ${c.label("Latest log:")} ${lastLog}`);
51
+ }
52
+ catch (err) {
53
+ logCliError(logFilePath(options), "wiki status", `wiki status failed: ${err.message}`, err);
54
+ process.exit(1);
55
+ }
56
+ });
57
+ wikiCmd
58
+ .command("graph")
59
+ .description("Link-graph queries: overview, backlinks, outlinks, neighbors, orphans, dangling")
60
+ .option("--dir <path>", "workspace root (default: cwd)")
61
+ .option("--page <page>", "page id or unique basename (required for backlinks/outlinks/neighbors)")
62
+ .option("--mode <mode>", "overview | backlinks | outlinks | neighbors | orphans | dangling", "overview")
63
+ .option("--depth <n>", "neighbors mode hop count (1-3)", "1")
64
+ .action((options) => {
65
+ try {
66
+ const { wikiDir, maxPages } = resolveWikiContext(options);
67
+ const graph = getWikiGraph(wikiDir, { maxPages });
68
+ if (!graph.exists) {
69
+ logCliInfo(logFilePath(options), "wiki graph", `\nNo wiki at .opencode/wiki/.`);
70
+ return;
71
+ }
72
+ const mode = String(options.mode ?? "overview").toLowerCase();
73
+ const log = (line) => logCliInfo(logFilePath(options), "wiki graph", line);
74
+ const lineFor = (id) => {
75
+ const node = graph.pages.get(id);
76
+ return ` - ${id}${node ? ` (in ${node.inbound.length}, out ${node.outbound.length})` : ""}`;
77
+ };
78
+ if (mode === "orphans" || mode === "dangling") {
79
+ const items = mode === "orphans" ? graph.orphans : graph.dangling.map((d) => `${d.fromId} -> [[${d.raw}]]`);
80
+ log(`\n${c.heading(mode)}: ${items.length}`);
81
+ for (const item of items)
82
+ log(` - ${item}`);
83
+ return;
84
+ }
85
+ if (mode === "backlinks" || mode === "outlinks" || mode === "neighbors") {
86
+ if (!options.page) {
87
+ logCliError(logFilePath(options), "wiki graph", `--mode ${mode} requires --page <page>`);
88
+ process.exit(1);
89
+ }
90
+ const node = findPage(graph, options.page);
91
+ if (!node) {
92
+ logCliError(logFilePath(options), "wiki graph", `no wiki page matches "${options.page}"`);
93
+ process.exit(1);
94
+ }
95
+ log(`\n${c.heading(node.title)} ${c.dim(node.id)}`);
96
+ if (mode !== "outlinks") {
97
+ log(` ${c.label("Backlinks:")}`);
98
+ for (const i of node.inbound)
99
+ log(lineFor(i));
100
+ }
101
+ if (mode !== "backlinks") {
102
+ log(` ${c.label("Outlinks:")}`);
103
+ for (const i of node.outbound)
104
+ log(lineFor(i));
105
+ for (const d of node.unresolved)
106
+ log(` ${c.warn(`dangling -> [[${d.target}]]`)}`);
107
+ }
108
+ if (mode === "neighbors") {
109
+ const depth = Math.min(3, Math.max(1, Number(options.depth ?? 1)));
110
+ for (const n of graphNeighbors(graph, node.id, depth))
111
+ log(lineFor(n));
112
+ }
113
+ return;
114
+ }
115
+ // overview
116
+ log(`\n${c.heading("Wiki overview")}`);
117
+ log(` ${c.label("Pages:")} ${c.num(graph.pageCount)}${graph.truncated ? ` ${c.warn("(page cap hit)")}` : ""}`);
118
+ log(` ${c.label("Orphans:")} ${graph.orphans.length} | ${c.label("Dangling:")} ${graph.dangling.length} | ${c.label("Uncataloged:")} ${graph.uncataloged.length}`);
119
+ for (const [id, node] of [...graph.pages.entries()].sort()) {
120
+ log(` ${id} ${c.dim(`(in ${node.inbound.length}, out ${node.outbound.length})`)}`);
121
+ }
122
+ }
123
+ catch (err) {
124
+ logCliError(logFilePath(options), "wiki graph", `wiki graph failed: ${err.message}`, err);
125
+ process.exit(1);
126
+ }
127
+ });
128
+ wikiCmd
129
+ .command("lint")
130
+ .description("Deterministic health report: git-verified staleness, structure, frontmatter, index coverage")
131
+ .option("--dir <path>", "workspace root (default: cwd)")
132
+ .option("--json", "machine-readable report on stdout")
133
+ .option("--stale-days <n>", "also list pages unreviewed for more than n days")
134
+ .option("--max-commits <n>", "cap on the git-history walk (default 500)")
135
+ .action((options) => {
136
+ try {
137
+ const { cwd, wikiDir, maxPages } = resolveWikiContext(options);
138
+ const report = lintWiki(wikiDir, cwd, {
139
+ maxPages,
140
+ maxCommits: options.maxCommits ? Number(options.maxCommits) : undefined,
141
+ });
142
+ if (options.json) {
143
+ // JSON goes to stdout raw so it pipes; no color codes.
144
+ const staleDays = options.staleDays ? Number(options.staleDays) : undefined;
145
+ const aging = staleDays
146
+ ? report.staleness.pages.filter((p) => p.state === "fresh" && p.lastReviewedMs !== undefined &&
147
+ p.lastReviewedMs < Date.now() - staleDays * 24 * 3600_000).map((p) => p.id)
148
+ : [];
149
+ process.stdout.write(JSON.stringify({ ...report, aging }, null, 2) + "\n");
150
+ return;
151
+ }
152
+ if (!report.exists) {
153
+ logCliInfo(logFilePath(options), "wiki lint", `\nNo wiki at .opencode/wiki/ — run \`/wiki seed\`.`);
154
+ return;
155
+ }
156
+ for (const line of formatLintReport(report).split("\n")) {
157
+ logCliInfo(logFilePath(options), "wiki lint", line);
158
+ }
159
+ }
160
+ catch (err) {
161
+ logCliError(logFilePath(options), "wiki lint", `wiki lint failed: ${err.message}`, err);
162
+ process.exit(1);
163
+ }
164
+ });
165
+ }
166
+ //# sourceMappingURL=wiki.js.map
package/dist/cli/index.js CHANGED
@@ -15,7 +15,7 @@ import { realpathSync } from "node:fs";
15
15
  import { basename, dirname } from "node:path";
16
16
  import { fileURLToPath } from "node:url";
17
17
  import { getPackageMetadata } from "./helpers.js";
18
- import { registerIndexCommand, registerQueryCommand, registerClearCommand, registerStatusCommand, registerListCommand, registerShowCommand, registerDumpCommand, registerClickHouseCommand, registerUiCommand, registerMcpCommand, registerSetupCommand, registerUpdateCommand, registerEvalSessionsCommand, registerEvalAnalyzeCommand, registerEvalCompareCommand, registerEvalGateCommand, registerEvalDecideCommand, registerEvalTuneCommand, registerDescribeImageCommand, registerDecideCommand, registerQuirkCommand, } from "./commands/index.js";
18
+ import { registerIndexCommand, registerQueryCommand, registerClearCommand, registerStatusCommand, registerListCommand, registerShowCommand, registerDumpCommand, registerClickHouseCommand, registerUiCommand, registerMcpCommand, registerSetupCommand, registerUpdateCommand, registerEvalSessionsCommand, registerEvalAnalyzeCommand, registerEvalCompareCommand, registerEvalGateCommand, registerEvalDecideCommand, registerEvalTuneCommand, registerDescribeImageCommand, registerDecideCommand, registerQuirkCommand, registerWikiCommand, } from "./commands/index.js";
19
19
  /**
20
20
  * The top-level Commander program instance that defines the `opencode-rag` CLI.
21
21
  *
@@ -59,6 +59,7 @@ registerEvalDecideCommand(program);
59
59
  registerEvalTuneCommand(program);
60
60
  registerClickHouseCommand(program);
61
61
  registerQuirkCommand(program);
62
+ registerWikiCommand(program);
62
63
  // ── Auto-run detection ──────────────────────────────────────────
63
64
  /**
64
65
  * Determine whether the CLI should auto-run for the current module.
@@ -353,6 +353,18 @@ export interface DocumentationModeConfig {
353
353
  export interface WikiModeConfig {
354
354
  /** Whether wiki mode is enabled. */
355
355
  enabled: boolean;
356
+ /**
357
+ * Whether the agent tools (`wiki_graph`, `wiki_lint`) are registered.
358
+ * `false` keeps the system-prompt protocol and the `/wiki` slash command
359
+ * but hides the tools (for agents that should not touch the wiki graph).
360
+ */
361
+ tools: boolean;
362
+ /**
363
+ * Safety cap on wiki pages scanned per tool call. Exceeding it truncates
364
+ * the scan and every report says so — a wiki past this size is a signal to
365
+ * split or prune, and counts become floors, never silent lies.
366
+ */
367
+ maxPages: number;
356
368
  /** System prompt for the wiki maintainer agent. */
357
369
  systemPrompt: string;
358
370
  }
@@ -268,12 +268,14 @@ export const DEFAULT_CONFIG = {
268
268
  },
269
269
  wikiMode: {
270
270
  enabled: true,
271
+ tools: true,
272
+ maxPages: 500,
271
273
  systemPrompt: "You are a wiki maintainer for this codebase. You incrementally build and maintain " +
272
274
  "a persistent knowledge wiki at `.opencode/wiki/` — a structured, interlinked collection " +
273
275
  "of markdown files that synthesizes knowledge from the codebase, documentation, and your conversations.\n\n" +
274
276
  "## Three layers\n\n" +
275
277
  "- **Raw sources**: code, docs, READMEs (immutable — read with `search_semantic`, `get_file_skeleton`, `find_usages`, `read`)\n" +
276
- "- **Wiki**: `.opencode/wiki/*.md` (you own this layer — create, update, and maintain ALL pages)\n" +
278
+ "- **Wiki**: `.opencode/wiki/*.md` (you own this layer — create, update, and maintain ALL pages; answer link/health questions with `wiki_graph`/`wiki_lint`, never grep)\n" +
277
279
  "- **Schema**: this prompt (the protocol you follow)\n\n" +
278
280
  "## Wiki layout\n\n" +
279
281
  "`.opencode/wiki/`\n" +
@@ -302,17 +304,14 @@ export const DEFAULT_CONFIG = {
302
304
  "6. Append to `log.md`: `## [date] ingest | page title`\n\n" +
303
305
  "### Query (when the user asks a question)\n" +
304
306
  "1. Read `index.md` first to find relevant wiki pages\n" +
305
- "2. Read those pages with the `read` tool\n" +
307
+ "2. Read those pages with the `read` tool; `wiki_graph` backlinks finds related pages\n" +
306
308
  "3. If the wiki is insufficient, use `search_semantic` for code-level retrieval\n" +
307
309
  "4. Synthesize an answer citing wiki pages where possible\n" +
308
310
  "5. If the answer produced valuable analysis, file it back as a new wiki page\n\n" +
309
311
  "### Lint (periodically, or when `/wiki lint` is invoked)\n" +
310
- "Check for:\n" +
311
- "- Orphan pages with no inbound `[[links]]`\n" +
312
- "- Stale pages whose `sourceRefs` files changed since `lastReviewed`\n" +
313
- "- Contradictions between pages\n" +
314
- "- Important concepts mentioned but lacking their own page\n" +
315
- "Append findings to `log.md`.\n\n" +
312
+ "Run `wiki_lint` first — it computes orphans, stale `sourceRefs` (git vs `lastReviewed`), dangling links, frontmatter and index coverage. " +
313
+ "Then what it cannot: contradictions, concepts lacking a page. " +
314
+ "Append findings to `log.md` and re-lint.\n\n" +
316
315
  "### Seed (when `/wiki seed` is invoked)\n" +
317
316
  "Generate initial wiki from existing sources:\n" +
318
317
  "1. Read README and top-level docs for project overview → create overview page\n" +
@@ -0,0 +1,22 @@
1
+ export interface GitignoreExclusions {
2
+ /** Patterns for `indexing.excludeDirs`. */
3
+ dirs: string[];
4
+ /** Patterns for `indexing.excludeFiles`. */
5
+ files: string[];
6
+ }
7
+ /**
8
+ * Parse `.gitignore` content into matcher-compatible exclusion patterns.
9
+ * Results are de-duplicated (case-insensitively) and sorted for stable output.
10
+ */
11
+ export declare function parseGitignoreExclusions(content: string): GitignoreExclusions;
12
+ /**
13
+ * Read `<workspaceDir>/.gitignore` and parse it. Returns empty lists when the
14
+ * file does not exist or cannot be read.
15
+ */
16
+ export declare function readGitignoreExclusions(workspaceDir: string): GitignoreExclusions;
17
+ /**
18
+ * Append `derived` patterns to an existing exclusion list, preserving the
19
+ * existing entries and their order. Comparison is case-insensitive, matching
20
+ * the matcher's own nocase behaviour.
21
+ */
22
+ export declare function mergeExclusionLists(existing: unknown[], derived: string[]): string[];
@@ -0,0 +1,148 @@
1
+ // Translate workspace `.gitignore` exclusion patterns into the
2
+ // `indexing.excludeDirs` / `indexing.excludeFiles` vocabulary of
3
+ // `createExcludeMatcher` (see `exclude.ts`), so `opencode-rag setup` can keep
4
+ // the indexer out of exactly the trees git already ignores.
5
+ //
6
+ // Mapping rules (documented subset of gitignore - anything else is skipped):
7
+ // - Comments, blank lines and `!` negations are skipped (negations cannot be
8
+ // expressed as exclusions).
9
+ // - Directory-shaped patterns like `foo/`, `/foo/`, `**/foo/`, `**/foo/**`,
10
+ // `**/foo/*` become the plain basename `foo`, which `createExcludeMatcher`
11
+ // matches at any depth - the gitignore any-depth forms map exactly,
12
+ // root-anchored `/foo/` becomes slightly broader (any depth), which is the
13
+ // safer direction.
14
+ // - Multi-segment patterns like `/playwright/.cache/` stay as rooted relative
15
+ // paths (`playwright/.cache`); the matcher anchors them to the workspace
16
+ // root.
17
+ // - A pattern ending in `/*` or `/**` describes the CONTENTS of a directory,
18
+ // which pruning the directory achieves identically.
19
+ // - Single-segment patterns that look like files (contain a dot) go to the
20
+ // file bucket (`*.bin`, `package-lock.json`); ambiguous ones (no dot, no
21
+ // trailing slash) go to BOTH buckets because git matches them against files
22
+ // and directories alike.
23
+ // - Escapes (`\#`, `\!`) are unescaped; other backslash handling is not
24
+ // implemented - unusual gitignore syntax is skipped, not mis-imported.
25
+ //
26
+ // NOTE: keep this header in line comments - gitignore examples contain the
27
+ // `*` + `/` sequence which would close a block comment prematurely.
28
+ import { existsSync, readFileSync } from "node:fs";
29
+ import path from "node:path";
30
+ const GLOB_MAGIC = /[*?[\]{}]/;
31
+ /**
32
+ * Parse `.gitignore` content into matcher-compatible exclusion patterns.
33
+ * Results are de-duplicated (case-insensitively) and sorted for stable output.
34
+ */
35
+ export function parseGitignoreExclusions(content) {
36
+ const dirs = new Map(); // lowercased key -> original
37
+ const files = new Map();
38
+ const put = (bucket, pattern) => {
39
+ const key = pattern.toLowerCase();
40
+ if (!bucket.has(key))
41
+ bucket.set(key, pattern);
42
+ };
43
+ for (const rawLine of content.split(/\r?\n/)) {
44
+ let line = rawLine.trim();
45
+ if (!line || line.startsWith("#"))
46
+ continue;
47
+ if (line.startsWith("!"))
48
+ continue; // negation: not expressible
49
+ if (line.startsWith("\\#") || line.startsWith("\\!")) {
50
+ line = line.slice(1); // escaped first char is literal
51
+ }
52
+ const dirHint = line.endsWith("/");
53
+ if (dirHint)
54
+ line = line.slice(0, -1);
55
+ // Strip root anchors and any-depth markers around the core.
56
+ let anyDepth = false;
57
+ if (line.startsWith("**/")) {
58
+ anyDepth = true;
59
+ line = line.slice(3);
60
+ }
61
+ else if (line.startsWith("/")) {
62
+ // Root-anchored. As a single segment this becomes a plain basename
63
+ // (any depth); multi-segment cores keep their rooted path form.
64
+ line = line.slice(1);
65
+ }
66
+ // Trailing content markers: `name/**` and `name/*` describe the subtree.
67
+ let subtreeOnly = false;
68
+ if (line.endsWith("/**") || line.endsWith("/*")) {
69
+ subtreeOnly = true;
70
+ line = line.replace(/\/\*\*?$/, "");
71
+ }
72
+ if (!line)
73
+ continue;
74
+ const isDir = dirHint || anyDepth || subtreeOnly || line.endsWith("**");
75
+ const hasSep = line.includes("/");
76
+ if (!hasSep) {
77
+ if (isDir) {
78
+ put(dirs, line);
79
+ }
80
+ else if (GLOB_MAGIC.test(line) || line.includes(".")) {
81
+ // `*.bin`, `Thumbs.db`, `package-lock.json` -> file bucket
82
+ put(files, line);
83
+ }
84
+ else {
85
+ // Ambiguous (e.g. `node_modules` without slash): git matches files
86
+ // AND directories - mirror that by adding to both buckets.
87
+ put(dirs, line);
88
+ put(files, line);
89
+ }
90
+ }
91
+ else {
92
+ const core = line.replace(/\/\*\*$/, "");
93
+ if (isDir) {
94
+ put(dirs, core);
95
+ }
96
+ else if (GLOB_MAGIC.test(core)) {
97
+ put(files, core);
98
+ }
99
+ else {
100
+ // Anchored, slash-containing, glob-free path (e.g. `a/b/c`): git
101
+ // matches it against files and directories alike -> both buckets.
102
+ put(dirs, core);
103
+ put(files, core);
104
+ }
105
+ }
106
+ }
107
+ const sorted = (m) => [...m.values()].sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
108
+ return { dirs: sorted(dirs), files: sorted(files) };
109
+ }
110
+ /**
111
+ * Read `<workspaceDir>/.gitignore` and parse it. Returns empty lists when the
112
+ * file does not exist or cannot be read.
113
+ */
114
+ export function readGitignoreExclusions(workspaceDir) {
115
+ try {
116
+ const gitignorePath = path.join(workspaceDir, ".gitignore");
117
+ if (!existsSync(gitignorePath))
118
+ return { dirs: [], files: [] };
119
+ return parseGitignoreExclusions(readFileSync(gitignorePath, "utf-8"));
120
+ }
121
+ catch {
122
+ return { dirs: [], files: [] };
123
+ }
124
+ }
125
+ /**
126
+ * Append `derived` patterns to an existing exclusion list, preserving the
127
+ * existing entries and their order. Comparison is case-insensitive, matching
128
+ * the matcher's own nocase behaviour.
129
+ */
130
+ export function mergeExclusionLists(existing, derived) {
131
+ const out = [];
132
+ const seen = new Set();
133
+ const add = (value) => {
134
+ const key = value.toLowerCase();
135
+ if (seen.has(key))
136
+ return;
137
+ seen.add(key);
138
+ out.push(value);
139
+ };
140
+ for (const entry of existing) {
141
+ if (typeof entry === "string" && entry.trim())
142
+ add(entry.trim());
143
+ }
144
+ for (const entry of derived)
145
+ add(entry);
146
+ return out;
147
+ }
148
+ //# sourceMappingURL=gitignore-exclusions.js.map
package/dist/index.d.ts CHANGED
@@ -24,6 +24,10 @@ export { loadConfig, loadConfigLayers, loadWorkspaceConfig, resolveConfigPaths,
24
24
  export { createBackgroundIndexer, deriveWatcherHealth, readWatcherState, discoverWatcherStates } from "./watcher.js";
25
25
  export type { WatcherStatus, ObservedWatcher } from "./watcher.js";
26
26
  export { createWatchIgnore } from "./indexer.js";
27
+ export { getWikiGraph, buildWikiGraph, findPage, graphNeighbors, resolveLinkTarget, NON_CONTENT_PAGE_IDS, type WikiGraph, type WikiPageNode, type WikiGraphOptions, type DanglingLink } from "./wiki/graph.js";
28
+ export { lintWiki, formatLintReport, type WikiLintReport, type WikiLintOptions } from "./wiki/lint.js";
29
+ export { computeStaleness, stalenessCounts, formatPageStaleness, LOW_SIGNAL_REFS, type StalenessResult, type PageStaleness, type SourceRefStatus, type StalenessOptions } from "./wiki/staleness.js";
30
+ export { parseWikiPage, parseWikiLinks, parseFrontmatter, normalizePageId, pageBasename, type ParsedWikiPage, type ParsedFrontmatter, type WikiLink } from "./wiki/page-parse.js";
27
31
  export { ImageChunker, createImageVisionProvider, resolveOnDemandImageConfig, getMimeType, SUPPORTED_IMAGE_EXTENSIONS } from "./chunker/image.js";
28
32
  export { DescriptionCache } from "./core/desc-cache.js";
29
33
  export type { RagConfig, DescriptionConfig, ImageDescriptionConfig, ImageDescriptionOnDemandConfig, DecisionConfig } from "./core/config.js";
package/dist/index.js CHANGED
@@ -21,6 +21,10 @@ export { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "./retriever/conte
21
21
  export { loadConfig, loadConfigLayers, loadWorkspaceConfig, resolveConfigPaths, configuredSections, findGlobalConfigFile, globalConfigPath, DEFAULT_CONFIG } from "./core/config.js";
22
22
  export { createBackgroundIndexer, deriveWatcherHealth, readWatcherState, discoverWatcherStates } from "./watcher.js";
23
23
  export { createWatchIgnore } from "./indexer.js";
24
+ export { getWikiGraph, buildWikiGraph, findPage, graphNeighbors, resolveLinkTarget, NON_CONTENT_PAGE_IDS } from "./wiki/graph.js";
25
+ export { lintWiki, formatLintReport } from "./wiki/lint.js";
26
+ export { computeStaleness, stalenessCounts, formatPageStaleness, LOW_SIGNAL_REFS } from "./wiki/staleness.js";
27
+ export { parseWikiPage, parseWikiLinks, parseFrontmatter, normalizePageId, pageBasename } from "./wiki/page-parse.js";
24
28
  export { ImageChunker, createImageVisionProvider, resolveOnDemandImageConfig, getMimeType, SUPPORTED_IMAGE_EXTENSIONS } from "./chunker/image.js";
25
29
  export { DescriptionCache } from "./core/desc-cache.js";
26
30
  /**
@@ -33,6 +33,31 @@ export declare function getChangedFilesSince(cwd: string, fromCommit: string): G
33
33
  * @returns An array of untracked file paths (relative to repo root).
34
34
  */
35
35
  export declare function getUntrackedFiles(cwd: string): string[];
36
+ /**
37
+ * Commit-touch timestamps derived from ONE bounded `git log` walk.
38
+ * Used by wiki staleness: instead of one `git log -1` per sourceRef (N
39
+ * spawns), a single history walk since the oldest review date answers
40
+ * "which files changed, and when" for every page at once.
41
+ */
42
+ export interface FileTouchTimestamps {
43
+ /** File path (posix, relative to the repo root) → newest commit unix seconds. */
44
+ timestamps: Map<string, number>;
45
+ /** Commits actually walked (for truncation reporting). */
46
+ commitCount: number;
47
+ /** True when `maxCommits` was hit — the map may miss older touches. */
48
+ truncated: boolean;
49
+ }
50
+ /**
51
+ * Map each file touched since `sinceIso` to the timestamp of its newest
52
+ * commit, in a single `git log --name-only` walk.
53
+ *
54
+ * @param cwd - A path inside the repository.
55
+ * @param sinceIso - ISO date lower bound (validated `YYYY-MM-DD…` only, so a
56
+ * crafted value can never inject git options via argv).
57
+ * @param maxCommits - Upper bound on walked commits.
58
+ * @returns The touch map, or `null` when git fails or the input is invalid.
59
+ */
60
+ export declare function getFileTouchTimestamps(cwd: string, sinceIso: string, maxCommits: number): FileTouchTimestamps | null;
36
61
  /** Result of comparing the working tree against HEAD. */
37
62
  export interface WorkingTreeChanges {
38
63
  /** Modified/renamed tracked files (unstaged + staged but not committed). */
@@ -95,6 +95,53 @@ export function getUntrackedFiles(cwd) {
95
95
  return [];
96
96
  }
97
97
  }
98
+ /**
99
+ * Map each file touched since `sinceIso` to the timestamp of its newest
100
+ * commit, in a single `git log --name-only` walk.
101
+ *
102
+ * @param cwd - A path inside the repository.
103
+ * @param sinceIso - ISO date lower bound (validated `YYYY-MM-DD…` only, so a
104
+ * crafted value can never inject git options via argv).
105
+ * @param maxCommits - Upper bound on walked commits.
106
+ * @returns The touch map, or `null` when git fails or the input is invalid.
107
+ */
108
+ export function getFileTouchTimestamps(cwd, sinceIso, maxCommits) {
109
+ if (!/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/.test(sinceIso))
110
+ return null;
111
+ if (!Number.isInteger(maxCommits) || maxCommits < 1 || maxCommits > 20000)
112
+ return null;
113
+ try {
114
+ const raw = execFileSync("git", [
115
+ "-c", "core.quotePath=false",
116
+ "log",
117
+ `--since=${sinceIso}`,
118
+ `--max-count=${maxCommits}`,
119
+ "--name-only",
120
+ "--pretty=format:%x1f%ct",
121
+ ], { cwd, encoding: "utf-8", timeout: 15000, maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
122
+ const timestamps = new Map();
123
+ let commitCount = 0;
124
+ let currentTs = 0;
125
+ for (const line of raw.split(/\r?\n/)) {
126
+ if (line.startsWith("\x1f")) {
127
+ currentTs = Number(line.slice(1).trim());
128
+ commitCount++;
129
+ continue;
130
+ }
131
+ const file = line.trim();
132
+ if (file.length === 0 || currentTs === 0)
133
+ continue;
134
+ const existing = timestamps.get(file);
135
+ // --since walks newest-first: first touch wins; max() is belt-and-braces.
136
+ if (existing === undefined || currentTs > existing)
137
+ timestamps.set(file, currentTs);
138
+ }
139
+ return { timestamps, commitCount, truncated: commitCount >= maxCommits };
140
+ }
141
+ catch {
142
+ return null;
143
+ }
144
+ }
98
145
  /**
99
146
  * Detect uncommitted working-tree changes by comparing against HEAD.
100
147
  * Uses `git diff-index` for tracked file modifications, `git diff --diff-filter=D`