@markstanden/opencode-docs-plugin 0.6.2 → 0.9.0

package/CONVENTION.md

@@ -36,6 +36,19 @@ are RepoContext. A repo adds other local roots in
 `.opencode/docs-lakes.json`; a personal or managed base file lists the
 machine, global and wiki lakes.
 
+Lakes are named, and several per class are supported. A root nested inside
+another lake's root belongs to the **narrowest enclosing lake**: the outer lake
+skips it, search returns the inner lake's entry, a bare `read` resolves there,
+and `add` writes to the deepest writable knowledge lake. Nesting is decided on
+real paths, so reaching one root through a symlink cannot defeat containment.
+Two lakes that do not nest holding the same relative path stay a refusal —
+pass `lake`. Near-twin checks apply inside one lake and never pair across the
+nesting boundary.
+
+Lake notes — a missing root, or a root outside version control — are computed
+per call, not captured at startup: create, remove or version a root and the
+next `check`, `search` and help reflect it without a restart.
+
 The excluded areas — never scanned, never validated in a knowledge lake — are
 `plans/` (scratch, gitignored, deleted when the work lands), `requirements/`
 and `wiki/` (vendored mirrors). The wiki profile has no such exclusions; only

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,12 +173,64 @@ 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 is decided on real paths: every configured root is resolved through
+symlinks, junctions and mapped drives before the comparison, so the two
+declarations may reach the tree by different routes and the nested doc is
+still indexed once.
+
+A doc belongs to the **narrowest enclosing lake**. With nested roots, `search`
+returns the inner lake's entry and a bare `read` resolves to it; `add` writes
+to the deepest writable knowledge lake, so an outer read-only wrapper never
+hijacks the write. Two lakes that do not nest holding the same relative path
+stay a refusal — pass `lake`. Near-twin checks apply inside one lake and never
+pair across the nesting boundary.
+
+```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
 tree. Create the directory deliberately. Area folders beneath an existing root
 are still created on write.
 
+Root and git notes are computed per call, not captured at startup: a root that
+appears, disappears or gains a git checkout is reflected by the next `check`,
+`search` and help without a restart.
+
 `maxDocLines` (default 200, `0` disables) is a **soft** note on a long doc, not a
 refusal. `perLakeQuota` (default 3, `0` disables) is the per-source result
 reservation.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@markstanden/opencode-docs-plugin",
-    "version": "0.6.2",
+    "version": "0.9.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

@@ -2227,8 +2227,12 @@ export interface Lake extends LakeSpec {
      * existing root; throws when the root is absent rather than creating it.
      */
     write: (path: string, contents: string) => void;
-    /** Environment notes for `check` (missing root, unversioned root). */
-    notes: readonly string[];
+    /**
+     * Legacy seam notes only. Real lakes compute their environment notes at
+     * call time — a root that appears, disappears or gains a git checkout is
+     * re-probed on the next `check`, `search` and help, never captured here.
+     */
+    notes?: readonly string[];
     /** Whether `check` should verify relative links; false for the legacy seam. */
     linkCheck: boolean;
 }
@@ -2314,7 +2318,6 @@ export function createLake(
     };
     return {
         ...spec,
-        notes: unversionedNote(spec.root, spec.name),
         linkCheck: true,
         collect: () =>
             collectDocs(spec.root, (paths) => fallbackDates(spec.root, paths), {
@@ -2346,18 +2349,27 @@ export function createLake(
 
 /**
  * Build every configured lake, each aware of the others so a nested root is
- * collected once.
+ * collected once. Nesting is decided on real paths, so a symlinked root cannot
+ * defeat containment: the skip paths handed to the walker are re-anchored
+ * under the collecting lake's configured root.
  * @param specs The configured lakes.
  * @returns The runtime lakes.
  */
 export function createLakes(specs: readonly LakeSpec[]): Lake[] {
-    return specs.map((spec) =>
-        createLake(spec, {
-            skip: specs
-                .filter((other) => other !== spec)
-                .map((other) => other.root),
-        }),
-    );
+    const realRoots = specs.map((spec) => realPathOf(spec.root));
+    return specs.map((spec, index) => {
+        const own = realRoots[index] ?? spec.root;
+        const skip = specs.flatMap((other, otherIndex) => {
+            if (otherIndex === index) {
+                return [];
+            }
+            const otherRoot = realRoots[otherIndex] ?? other.root;
+            return otherRoot !== own && isUnder(otherRoot, own)
+                ? [join(spec.root, relative(own, otherRoot))]
+                : [];
+        });
+        return createLake(spec, { skip });
+    });
 }
 
 /** The lake classes the configuration accepts. */
@@ -2370,6 +2382,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 +2660,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 +2742,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,
             ),
@@ -2811,6 +2831,44 @@ function findLake(lakes: readonly Lake[], name: string): Lake | undefined {
     return lakes.find((lake) => lake.name === name);
 }
 
+/**
+ * The environment notes for one lake, probed at call time. Legacy seams keep
+ * their captured notes; every real lake re-probes, so a root that appears,
+ * disappears or gains a git checkout is reported by the next surface that
+ * looks — `check`, `search` and help never disagree with a stale capture.
+ * @param lake The lake to describe.
+ * @returns The note lines.
+ */
+function lakeNotes(lake: Lake): readonly string[] {
+    return lake.root === ""
+        ? (lake.notes ?? [])
+        : unversionedNote(lake.root, lake.name);
+}
+
+/** Whether a lake root is absent, probed at call time. */
+function lakeMissing(lake: Lake): boolean {
+    return lake.root !== "" && !existsSync(lake.root);
+}
+
+/**
+ * How many knowledge lakes enclose a lake — the nesting depth used to pick the
+ * narrowest owner of a path and the deepest writable target for `add`. Wiki
+ * lakes never enclose anything.
+ * @param lake The lake to measure.
+ * @param lakes The configured lakes.
+ * @returns The number of enclosing knowledge lakes.
+ */
+function nestingDepth(lake: Lake, lakes: readonly Lake[]): number {
+    const root = realPathOf(lake.root);
+    return lakes.filter((other) => {
+        if (other === lake || other.profile === "wiki") {
+            return false;
+        }
+        const otherRoot = realPathOf(other.root);
+        return otherRoot !== root && isUnder(root, otherRoot);
+    }).length;
+}
+
 /** The lake `add` writes to, or the refusal reason. */
 function writableLake(
     lakes: readonly Lake[],
@@ -2828,14 +2886,34 @@ function writableLake(
         }
         return lake;
     }
-    return (
-        lakes.find((lake) => lake.class === "repo" && lake.writable) ??
-        lakes.find((lake) => lake.profile === "knowledge" && lake.writable) ?? {
+    // The narrowest writable knowledge lake wins: with nested roots the inner
+    // lake owns the file, so an outer read-only lake must not hijack the write.
+    const repos = lakes.filter(
+        (lake) => lake.class === "repo" && lake.writable,
+    );
+    const pool =
+        repos.length > 0
+            ? repos
+            : lakes.filter(
+                  (lake) => lake.profile === "knowledge" && lake.writable,
+              );
+    if (pool.length === 0) {
+        return {
             reason:
                 `${REFUSE} no writable knowledge lake is configured; ` +
                 "add a repo, machine, or global lake.",
+        };
+    }
+    let target = pool[0] as Lake;
+    let depth = nestingDepth(target, lakes);
+    for (const candidate of pool.slice(1)) {
+        const candidateDepth = nestingDepth(candidate, lakes);
+        if (candidateDepth > depth) {
+            target = candidate;
+            depth = candidateDepth;
         }
-    );
+    }
+    return target;
 }
 
 /** Qualify a path with its lake when more than one lake is configured. */
@@ -2879,9 +2957,8 @@ function searchDocs(
     const missing = runtime.lakes
         .filter(
             (lake) =>
-                lake.root !== "" &&
                 (lakeName === undefined || lakeName === lake.name) &&
-                !existsSync(lake.root),
+                lakeMissing(lake),
         )
         .map((lake) => missingRootNote(lake.root, lake.name));
     return {
@@ -2914,7 +2991,7 @@ function checkLakes(
         }
         const entries = lake.collect();
         return {
-            content: checkDocs(entries, lake.read, lake.notes, {
+            content: checkDocs(entries, lake.read, lakeNotes(lake), {
                 maxDocLines: runtime.maxDocLines,
                 ...(lake.linkCheck ? { exists: lake.exists } : {}),
             }),
@@ -2928,7 +3005,7 @@ function checkLakes(
     const reports = knowledge.map((lake) => {
         const entries = lake.collect();
         checked += entries.length;
-        const report = checkDocs(entries, lake.read, lake.notes, {
+        const report = checkDocs(entries, lake.read, lakeNotes(lake), {
             maxDocLines: runtime.maxDocLines,
             ...(lake.linkCheck ? { exists: lake.exists } : {}),
         });
@@ -3056,14 +3133,26 @@ function uniqueHolder(
     if (holders.length === 0) {
         return { reason: `No doc at ${path}.` };
     }
-    if (holders.length > 1) {
-        return {
-            reason:
-                `${REFUSE} ${path} exists in multiple lakes ` +
-                `(${holders.map((lake) => lake.name).join(", ")}); pass lake.`,
-        };
+    if (holders.length === 1) {
+        return holders[0] as Lake;
+    }
+    // Nested lakes both hold an inner path: the narrowest enclosing lake owns
+    // it. Non-nested holders tie on depth, which stays a documented refusal —
+    // never a silent pick by collection order.
+    const deepest = holders.map((lake) => ({
+        lake,
+        depth: nestingDepth(lake, holders),
+    }));
+    const max = Math.max(...deepest.map((item) => item.depth));
+    const winners = deepest.filter((item) => item.depth === max);
+    if (winners.length === 1) {
+        return winners[0]?.lake as Lake;
     }
-    return holders[0] as Lake;
+    return {
+        reason:
+            `${REFUSE} ${path} exists in multiple lakes ` +
+            `(${holders.map((lake) => lake.name).join(", ")}); pass lake.`,
+    };
 }
 
 /** Read one doc, resolving a `lake:path` prefix or the unique match. */
@@ -3114,7 +3203,7 @@ function lakeInfo(lakes: readonly Lake[]): LakeInfo[] {
         root: lake.root,
         writable: lake.writable,
         validated: lake.profile === "knowledge",
-        missing: lake.root !== "" && !existsSync(lake.root),
+        missing: lakeMissing(lake),
     }));
 }