@markstanden/opencode-docs-plugin 0.6.0 → 0.8.0

package/README.md

@@ -89,7 +89,21 @@ The simplest setup uses `root` — one repo lake:
 
 `root` expands `~`, resolves a relative path against the location, and defaults
 to `<location>/docs`. A blank value counts as unset. `root` declares a **repo**
-lake; for a personal or global lake, use `lakes` with the class instead.
+lake; for a personal or global lake, use `lakes` with the class instead. Its
+name follows the root folder unless you set the `name` option beside it:
+
+```jsonc
+{
+    "plugins": [
+        {
+            "package": "@markstanden/opencode-docs-plugin",
+            "options": { "root": "documentation", "name": "doclake" },
+        },
+    ],
+}
+```
+
+`name` only applies to `root`; inside `lakes`, set it on the entry.
 
 For several lakes, list them inline, in a base file, or both. The base file is
 usually a personal or managed file; the repo file adds local lakes:
@@ -159,6 +173,47 @@ Lake paths never follow symlinks: a symlinked doc is skipped by search and
 `check`, refused by `read`, and refused by `add`. The configured `root` itself
 may be a symlink; the content beneath it must be real.
 
+A lake root nested inside another lake's root is indexed once. The outer lake
+skips the nested root, so the doc is returned by the inner lake only — never
+twice, and never under both roots. Class and writability make no difference: a
+writable repo lake may sit inside a larger read-only wiki lake, and search,
+`read` and `add` all resolve to the writable inner lake. The outer lake's class
+only decides its own profile and defaults; `repo`, `machine`, `global` and
+`wiki` all skip a nested root the same way.
+
+The skip compares the configured roots as written, so reach the tree the same
+way from both declarations. If one lake names the real directory and the other
+reaches it through a symlink, junction or mapped drive, the two paths never
+match and the nested doc is indexed twice.
+
+```jsonc
+{
+    "plugins": [
+        {
+            "package": "@markstanden/opencode-docs-plugin",
+            "options": {
+                "lakes": [
+                    {
+                        "class": "wiki",
+                        "root": "~/reference-wiki",
+                        "name": "wiki",
+                    },
+                    {
+                        "class": "repo",
+                        "root": "~/reference-wiki/work/docs",
+                        "name": "work",
+                    },
+                ],
+            },
+        },
+    ],
+}
+```
+
+`class` is one of `repo`, `machine`, `global` or `wiki`; `root` and `name` are
+strings, and `writable` is a boolean that is fixed `false` for `wiki`. Do not
+add `root` alongside `lakes` — they are mutually exclusive.
+
 A missing lake root is flagged, never created. The lake stays dormant until the
 directory exists: `search` appends a note naming the lake and path, `help` marks
 it `— missing`, and `add` refuses with the path rather than bootstrapping a

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@markstanden/opencode-docs-plugin",
-    "version": "0.6.0",
+    "version": "0.8.0",
     "type": "module",
     "description": "OpenCode V2 plugin: a `docs` tool and `/docs` command over configurable knowledge lakes (repo, machine, global and read-only wiki), nested README.md search, and the writing convention they share",
     "repository": {
@@ -21,6 +21,7 @@
     },
     "scripts": {
         "test": "node --test 'tests/**/*.test.ts'",
+        "test:coverage": "mkdir -p coverage && node --test --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=coverage/lcov.info 'tests/**/*.test.ts'",
         "test:watch": "node --test --watch 'tests/**/*.test.ts'",
         "typecheck": "tsc --noEmit"
     },

package/src/SKILL.md

@@ -21,14 +21,16 @@ means two docs; one omnibus doc is out of place everywhere.
 
 A **blank `search`** lists recent docs, one line each; a **`search`** ranks
 them, falling back to `Closest matches` and matching terms as **substrings** —
-so a typo finds nothing and terms under `MIN_TERM_LENGTH` (3) are ignored.
-`help` lists the lakes and ranking.
+so a typo finds nothing. Terms shorter than `MIN_TERM_LENGTH` (3) are dropped
+when longer terms exist; otherwise all query terms are kept. `help` lists the
+lakes and ranking.
 
 Open the match with `read`: the root-relative path, or `lake:path` when several
 lakes exist. A README result is `instructions:path` and opens with the built-in
 `read`. Consult matching docs before a broad grep; a tie ranks repo,
-instructions, global, machine, wiki. Excluded areas: `plans/`, `requirements/`
-and `wiki/`.
+instructions, global, machine, wiki. Knowledge lakes exclude `plans/`,
+`requirements/` and `wiki/` at the root; wiki lakes exclude only
+dot-directories and `node_modules`.
 
 ## Record it
 

package/src/index.ts

@@ -250,9 +250,77 @@ function splitKeywords(value: string): string[] {
         .filter((keyword) => keyword !== "");
 }
 
-/** Whether a line opens or closes a fenced code block. */
-function isFence(line: string): boolean {
-    return line.trimStart().startsWith("```");
+/**
+ * An open fenced code block: the opener's delimiter character and run length.
+ * The length and character are remembered so a shorter or different-character
+ * run inside the block cannot close it.
+ */
+interface Fence {
+    readonly char: "`" | "~";
+    readonly length: number;
+}
+
+/**
+ * The supported Markdown fence subset: a backtick or tilde run of three or
+ * more, indented by at most three spaces. A backtick opener's info string may
+ * not contain a backtick. Four-space indentation is an indented code block, not
+ * a fence, and is not modelled; nor are tab-indented fences or the full
+ * CommonMark block grammar.
+ * @param line One source line.
+ * @returns The opened fence, or null when the line is not an opener.
+ */
+function fenceOpener(line: string): Fence | null {
+    const match = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+    if (match === null) {
+        return null;
+    }
+    const run = match[1] ?? "";
+    const info = line.slice(match[0].length);
+    const char = run[0] as Fence["char"];
+    if (char === "`" && info.includes("`")) {
+        return null;
+    }
+    return { char, length: run.length };
+}
+
+/**
+ * Whether a line closes `fence`: the same delimiter character, a run at least
+ * as long as the opener, and nothing after it but spaces or tabs.
+ * @param line One source line.
+ * @param fence The open fence.
+ * @returns True when the line closes the block.
+ */
+function closesFence(line: string, fence: Fence): boolean {
+    const match = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(line);
+    if (match === null) {
+        return false;
+    }
+    const run = match[1] ?? "";
+    return run.startsWith(fence.char) && run.length >= fence.length;
+}
+
+/**
+ * The body's lines outside fenced code blocks, fence delimiters included in
+ * neither. An unclosed fence keeps every remaining line inside the block.
+ * @param body Doc body, front-matter already stripped.
+ * @returns Source lines with fenced blocks removed.
+ */
+function outsideFenceLines(body: string): string[] {
+    const lines: string[] = [];
+    let fence: Fence | null = null;
+    for (const line of body.split("\n")) {
+        if (fence === null) {
+            const opener = fenceOpener(line);
+            if (opener !== null) {
+                fence = opener;
+                continue;
+            }
+            lines.push(line);
+        } else if (closesFence(line, fence)) {
+            fence = null;
+        }
+    }
+    return lines;
 }
 
 /** Drop an ATX heading's trailing `#` decoration (and any trailing spaces). */
@@ -279,19 +347,11 @@ interface BodyScan {
 function scanBody(body: string): BodyScan {
     const headings: string[] = [];
     const spans: string[] = [];
-    let fenced = false;
-    for (const line of body.split("\n")) {
-        if (isFence(line)) {
-            fenced = !fenced;
-            continue;
-        }
-        if (fenced) {
-            continue;
-        }
+    for (const line of outsideFenceLines(body)) {
         const heading = /^(#{2,3})\s+/.exec(line);
         if (heading !== null) {
             const text = stripTrailingHashes(
-                line.slice(heading[0].length).replace(/`/g, ""),
+                line.slice(heading[0].length).replaceAll("`", ""),
             ).trim();
             if (text !== "") {
                 headings.push(text);
@@ -358,18 +418,7 @@ function plainProse(text: string): string {
 
 /** The body with fenced code blocks removed. */
 function withoutFences(body: string): string {
-    const lines: string[] = [];
-    let fenced = false;
-    for (const line of body.split("\n")) {
-        if (isFence(line)) {
-            fenced = !fenced;
-            continue;
-        }
-        if (!fenced) {
-            lines.push(line);
-        }
-    }
-    return lines.join("\n");
+    return outsideFenceLines(body).join("\n");
 }
 
 /** Block prefixes that are never a wiki summary. */
@@ -752,6 +801,20 @@ export function rankDocs(
     };
 }
 
+/** The provenance prefix for a result: instructions, non-primary lake, or none. */
+function resultPrefix(
+    entry: DocEntry,
+    primaryLake: string | undefined,
+): string {
+    if (entry.class === "instructions") {
+        return "instructions";
+    }
+    if (entry.lake !== "" && entry.lake !== primaryLake) {
+        return entry.lake;
+    }
+    return "";
+}
+
 /**
  * Render matched docs as `path — Area — date` lines with the summary indented
  * beneath; a non-primary lake is prefixed `lake:` so provenance is clear. A
@@ -782,12 +845,8 @@ export function render(
             );
             const meta = parts.join(" — ");
             const head = meta === "" ? entry.path : `${entry.path} — ${meta}`;
-            const labelled =
-                entry.class === "instructions"
-                    ? `instructions:${head}`
-                    : entry.lake !== "" && entry.lake !== options.primaryLake
-                      ? `${entry.lake}:${head}`
-                      : head;
+            const prefix = resultPrefix(entry, options.primaryLake);
+            const labelled = prefix === "" ? head : `${prefix}:${head}`;
             return entry.summary === ""
                 ? labelled
                 : `${labelled}\n  ${entry.summary}`;
@@ -824,7 +883,7 @@ export function explainRanking(): string {
         "How docs search ranks:",
         `- Fields weighted: title ${FIELD_WEIGHTS.title} > path ${FIELD_WEIGHTS.path} > keywords ${FIELD_WEIGHTS.keywords} > identifiers ${FIELD_WEIGHTS.identifiers} > area ${FIELD_WEIGHTS.area} > summary ${FIELD_WEIGHTS.summary} > wiki prose ${FIELD_WEIGHTS.text}.`,
         `- Each term scores its best field as weight × quality; quality is exact > prefix > substring.`,
-        `- Terms shorter than MIN_TERM_LENGTH (${MIN_TERM_LENGTH}) are ignored unless they are the whole query.`,
+        `- Terms shorter than MIN_TERM_LENGTH (${MIN_TERM_LENGTH}) are dropped when longer terms exist; otherwise all query terms are kept.`,
         "- Search covers every configured lake and nested project `README.md` files, honouring `.gitignore` (dependency and build directories are skipped when the project is not in git). READMEs are searchable only: `add` and `check` ignore them, and their results are prefixed `instructions:` so they read with the built-in `read` tool.",
         `- Each source reserves up to ${DEFAULT_PER_LAKE_QUOTA} results (configurable), then leftover slots fill by score. Every call returns at most MAX_RESULTS (${MAX_RESULTS}), best matches first, then the most recently edited; anything cut is counted as "… and N more not shown."`,
         "- Class precedence on a tie: repo > instructions > global > machine > wiki.",
@@ -945,7 +1004,7 @@ export function gitDates(
         return dates;
     }
     const result = spawnSync(
-        "git",
+        "git", // NOSONAR: portable git lookup; cwd is trusted local config, not model input.
         // `--relative` keeps the output paths root-relative to `cwd`; without
         // it a lake rooted at `<repo>/docs` maps `docs/foo.md` while the
         // requested paths are `foo.md`, silently falling back to mtimes.
@@ -1059,6 +1118,22 @@ function skipDirectory(
     return directory === root && excluded.includes(item.name);
 }
 
+/**
+ * Code-unit string order, matching the default sort but stated explicitly.
+ * @param a Left string.
+ * @param b Right string.
+ * @returns Negative, zero or positive in code-unit order.
+ */
+function compareText(a: string, b: string): number {
+    if (a < b) {
+        return -1;
+    }
+    if (a > b) {
+        return 1;
+    }
+    return 0;
+}
+
 /**
  * Walk a lake root, returning its `.md` paths relative to the root. Dot
  * directories are skipped (which drops `.git` and `.attachments`), as are
@@ -1106,7 +1181,7 @@ export function collectDocPaths(
     if (existsSync(root)) {
         walk(root);
     }
-    return paths.sort();
+    return paths.sort(compareText);
 }
 
 /**
@@ -1221,7 +1296,7 @@ export function readmePaths(
         .filter(
             (path) => !skip.some((root) => isUnder(join(location, path), root)),
         )
-        .sort();
+        .sort(compareText);
 }
 
 /**
@@ -1230,7 +1305,7 @@ export function readmePaths(
  */
 function gitReadmePaths(location: string): string[] | undefined {
     const result = spawnSync(
-        "git",
+        "git", // NOSONAR: portable git lookup; cwd is trusted local config, not model input.
         ["ls-files", "-z", "--cached", "--others", "--exclude-standard"],
         { cwd: location, encoding: "utf8", maxBuffer: 16 * 1024 * 1024 },
     );
@@ -1616,9 +1691,11 @@ export const CLAIM_SECTIONS = [
  * @returns True when a claim-section heading is present.
  */
 export function hasClaimSection(body: string): boolean {
-    const claims = CLAIM_SECTIONS.map((section) => section.toLowerCase());
+    const claims = new Set(
+        CLAIM_SECTIONS.map((section) => section.toLowerCase()),
+    );
     return scanBody(body).headings.some((heading) =>
-        claims.includes(heading.toLowerCase()),
+        claims.has(heading.toLowerCase()),
     );
 }
 
@@ -1698,7 +1775,7 @@ function nearTwinPairs(
         const query = identityQuery(doc.title, doc.keywords);
         const others = entries.filter((other) => other.path !== doc.path);
         for (const twin of nearTwins(query, doc.area, others)) {
-            const key = [doc.path, twin.path].sort().join("\n");
+            const key = [doc.path, twin.path].sort(compareText).join("\n");
             if (!pairs.has(key)) {
                 pairs.set(key, [doc, twin]);
             }
@@ -1732,26 +1809,47 @@ function resolveLink(from: string, target: string): string | null {
     return stack.join("/");
 }
 
+/** An inline link's destination and the index of its closing `)`. */
+interface InlineLink {
+    readonly destination: string | undefined;
+    readonly end: number;
+}
+
+/**
+ * Parse an inline `[text](target)` link starting at `start`.
+ * @param line One source line.
+ * @param start Index of the opening `[`.
+ * @returns The destination and closing index, or null when the link is incomplete.
+ */
+function inlineLinkAt(line: string, start: number): InlineLink | null {
+    const close = line.indexOf("](", start + 1);
+    if (close === -1) {
+        return null;
+    }
+    const end = line.indexOf(")", close + 2);
+    if (end === -1) {
+        return null;
+    }
+    const destination = line
+        .slice(close + 2, end)
+        .trim()
+        .split(/\s+/)[0];
+    return { destination, end };
+}
+
 /** Inline `[text](target)` destinations on one line; images are skipped. */
 function inlineTargets(line: string): string[] {
     const targets: string[] = [];
     let index = 0;
     while (index < line.length) {
         if (line[index] === "[" && line[index - 1] !== "!") {
-            const close = line.indexOf("](", index + 1);
-            if (close !== -1) {
-                const end = line.indexOf(")", close + 2);
-                if (end !== -1) {
-                    const destination = line
-                        .slice(close + 2, end)
-                        .trim()
-                        .split(/\s+/)[0];
-                    if (destination !== undefined && destination !== "") {
-                        targets.push(destination);
-                    }
-                    index = end + 1;
-                    continue;
+            const link = inlineLinkAt(line, index);
+            if (link !== null) {
+                if (link.destination !== undefined && link.destination !== "") {
+                    targets.push(link.destination);
                 }
+                index = link.end + 1;
+                continue;
             }
         }
         index += 1;
@@ -1768,15 +1866,7 @@ function inlineTargets(line: string): string[] {
  */
 export function markdownTargets(body: string): string[] {
     const targets: string[] = [];
-    let fenced = false;
-    for (const line of body.split("\n")) {
-        if (isFence(line)) {
-            fenced = !fenced;
-            continue;
-        }
-        if (fenced) {
-            continue;
-        }
+    for (const line of outsideFenceLines(body)) {
         targets.push(...inlineTargets(line));
         const reference = /^\s*\[[^\]]+\]:\s*(\S+)/.exec(line);
         if (reference?.[1] !== undefined) {
@@ -1962,7 +2052,8 @@ export function checkDocs(
     if (advisory.length === 0) {
         return head;
     }
-    return `${head}\n\nNotes:\n${advisory.map((note) => `- ${note}`).join("\n")}`;
+    const noteLines = advisory.map((note) => `- ${note}`).join("\n");
+    return `${head}\n\nNotes:\n${noteLines}`;
 }
 
 /** The built-in tools the miss-nudge watches: content searches, both miss-prone. */
@@ -2279,6 +2370,8 @@ export const REPO_LAKES_FILE = ".opencode/docs-lakes.json";
 export interface DocsPluginOptions {
     /** The single repo-lake override; mutually exclusive with `lakes`. */
     root?: unknown;
+    /** The `root` lake's name; defaults to the root folder name. Needs `root`. */
+    name?: unknown;
     /** Base lake declarations, merged after `lakesFile` and the repo file. */
     lakes?: unknown;
     /** A JSON file of base lakes (`{ "lakes": [...] }`). */
@@ -2359,13 +2452,20 @@ function readLakesJson(
             { cause: error },
         );
     }
-    const lakes = Array.isArray(parsed)
-        ? parsed
-        : typeof parsed === "object" && parsed !== null && "lakes" in parsed
-          ? (parsed as { lakes: unknown }).lakes
-          : undefined;
+    let lakes: unknown;
+    if (Array.isArray(parsed)) {
+        lakes = parsed;
+    } else if (
+        typeof parsed === "object" &&
+        parsed !== null &&
+        "lakes" in parsed
+    ) {
+        lakes = (parsed as { lakes: unknown }).lakes;
+    } else {
+        lakes = undefined;
+    }
     if (!Array.isArray(lakes)) {
-        throw new Error(
+        throw new TypeError(
             `docs plugin ${label} must contain a "lakes" array: ${path}.`,
         );
     }
@@ -2435,7 +2535,7 @@ function lakeRootOf(
         return join(location, "docs");
     }
     if (typeof entry.root !== "string") {
-        throw new Error(
+        throw new TypeError(
             `docs plugin ${lakeClass} lake root must be a string, ` +
                 `got ${JSON.stringify(entry.root)}.`,
         );
@@ -2456,12 +2556,14 @@ function lakeNameOf(
     lakeClass: LakeClass,
 ): string {
     const derived = slugify(basename(root)) || lakeClass;
-    const name =
-        entry.name === undefined
-            ? derived
-            : typeof entry.name === "string"
-              ? entry.name.trim()
-              : "";
+    let name: string;
+    if (entry.name === undefined) {
+        name = derived;
+    } else if (typeof entry.name === "string") {
+        name = entry.name.trim();
+    } else {
+        name = "";
+    }
     if (!LAKE_NAME.test(name)) {
         throw new Error(
             `docs plugin lake name must match ${LAKE_NAME}, ` +
@@ -2488,8 +2590,7 @@ function lakeWritableOf(
                 `got ${JSON.stringify(entry.writable)}.`,
         );
     }
-    const writable =
-        entry.writable === undefined ? lakeClass !== "wiki" : entry.writable;
+    const writable = entry.writable ?? lakeClass !== "wiki";
     if (lakeClass === "wiki" && writable) {
         throw new Error(
             `docs plugin lake '${name}' is a wiki lake and cannot be writable.`,
@@ -2547,6 +2648,12 @@ function assertLakesOptions(options: DocsPluginOptions): void {
                 "use 'root' for one repo lake or 'lakes' for the full list.",
         );
     }
+    if (options.name !== undefined && options.root === undefined) {
+        throw new Error(
+            "docs plugin option 'name' names the 'root' lake; " +
+                "set 'name' inside a 'lakes' entry instead.",
+        );
+    }
 }
 
 /** Map raw lake entries from a file to specs. */
@@ -2623,7 +2730,7 @@ export function resolveLakes(
     if (options.root !== undefined) {
         specs.push(
             lakeSpecFrom(
-                { class: "repo", root: options.root },
+                { class: "repo", root: options.root, name: options.name },
                 location,
                 false,
             ),
@@ -3046,6 +3153,51 @@ const TWIN_DESCRIPTION =
     "docs; `read` returns a matched doc verbatim; `add` writes through a typed " +
     "DTO; `check` validates the lakes.";
 
+/**
+ * Run one resolved `docs` request against the runtime.
+ * @param runtime The resolved lakes and seams.
+ * @param input The typed tool input.
+ * @returns The tool result.
+ */
+function executeRequest(runtime: Runtime, input: DocsInput): Result {
+    const request = resolveRequest(input);
+    if (request.verb === "add") {
+        const result = addDoc(runtime, request.add, request.lake);
+        return {
+            content: result.content,
+            metadata: { written: result.written },
+        };
+    }
+    if (request.verb === "check") {
+        const result = checkLakes(runtime, request.lake);
+        return {
+            content: result.content,
+            metadata: { checked: result.checked },
+        };
+    }
+    if (request.verb === "read") {
+        const result = readDoc(runtime, request.read, request.lake);
+        return {
+            content: result.content,
+            metadata: { read: result.read },
+        };
+    }
+    if (request.verb === "help") {
+        return {
+            content: helpText(lakeInfo(runtime.lakes)),
+            metadata: { count: 0, omitted: 0 },
+        };
+    }
+    const result = searchDocs(runtime, request.search, request.lake);
+    return {
+        content: result.content,
+        metadata: {
+            count: result.count,
+            omitted: result.omitted,
+        },
+    };
+}
+
 /**
  * Build the `docs` tool from its dependencies.
  *
@@ -3087,43 +3239,8 @@ export function createDocsTool(
         options: codemode
             ? { namespace: "docs", codemode: true }
             : { codemode: false },
-        async execute(input) {
-            const request = resolveRequest(input);
-            if (request.verb === "add") {
-                const result = addDoc(runtime, request.add, request.lake);
-                return {
-                    content: result.content,
-                    metadata: { written: result.written },
-                };
-            }
-            if (request.verb === "check") {
-                const result = checkLakes(runtime, request.lake);
-                return {
-                    content: result.content,
-                    metadata: { checked: result.checked },
-                };
-            }
-            if (request.verb === "read") {
-                const result = readDoc(runtime, request.read, request.lake);
-                return {
-                    content: result.content,
-                    metadata: { read: result.read },
-                };
-            }
-            if (request.verb === "help") {
-                return {
-                    content: helpText(lakeInfo(runtime.lakes)),
-                    metadata: { count: 0, omitted: 0 },
-                };
-            }
-            const result = searchDocs(runtime, request.search, request.lake);
-            return {
-                content: result.content,
-                metadata: {
-                    count: result.count,
-                    omitted: result.omitted,
-                },
-            };
+        execute(input) {
+            return Promise.resolve(executeRequest(runtime, input));
         },
     };
 }
@@ -3213,7 +3330,7 @@ export function resolveRoot(
         return join(locationDirectory, "docs");
     }
     if (typeof configured !== "string") {
-        throw new Error(
+        throw new TypeError(
             `docs plugin option 'root' must be a non-empty string path, ` +
                 `got ${JSON.stringify(configured)}.`,
         );
@@ -3264,9 +3381,11 @@ export function unversionedNote(
     if (!existsSync(root)) {
         return [missingRootNote(root, lake)];
     }
-    const probe = spawnSync("git", ["rev-parse", "--show-toplevel"], {
-        cwd: root,
-    });
+    const probe = spawnSync(
+        "git", // NOSONAR: portable git lookup; cwd is trusted local config.
+        ["rev-parse", "--show-toplevel"],
+        { cwd: root },
+    );
     if (probe.status === 0) {
         return [];
     }