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 +11 -2
- package/dist/cli/commands/index.d.ts +1 -0
- package/dist/cli/commands/index.js +1 -0
- package/dist/cli/commands/setup.js +35 -0
- package/dist/cli/commands/wiki.d.ts +11 -0
- package/dist/cli/commands/wiki.js +166 -0
- package/dist/cli/index.js +2 -1
- package/dist/core/config.d.ts +12 -0
- package/dist/core/config.js +7 -8
- package/dist/core/gitignore-exclusions.d.ts +22 -0
- package/dist/core/gitignore-exclusions.js +148 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +4 -0
- package/dist/indexer/git-diff.d.ts +25 -0
- package/dist/indexer/git-diff.js +47 -0
- package/dist/opencode/wiki-tools.d.ts +25 -0
- package/dist/opencode/wiki-tools.js +224 -0
- package/dist/plugin.js +81 -9
- package/dist/web/config-schema.js +7 -0
- package/dist/wiki/graph.d.ts +114 -0
- package/dist/wiki/graph.js +286 -0
- package/dist/wiki/lint.d.ts +48 -0
- package/dist/wiki/lint.js +134 -0
- package/dist/wiki/page-parse.d.ts +97 -0
- package/dist/wiki/page-parse.js +231 -0
- package/dist/wiki/staleness.d.ts +52 -0
- package/dist/wiki/staleness.js +184 -0
- package/package.json +2 -2
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,
|
|
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` |
|
|
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.
|
package/dist/core/config.d.ts
CHANGED
|
@@ -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
|
}
|
package/dist/core/config.js
CHANGED
|
@@ -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
|
-
"
|
|
311
|
-
"
|
|
312
|
-
"
|
|
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). */
|
package/dist/indexer/git-diff.js
CHANGED
|
@@ -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`
|