@markstanden/opencode-docs-plugin 0.6.2 → 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.2",
+    "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/index.ts

@@ -2370,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": [...] }`). */
@@ -2646,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. */
@@ -2722,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,
             ),