@recallnet/remark-lint-docs-reachability 0.2.2 → 0.2.4

package/README.md

@@ -2,6 +2,56 @@
 
 Flags in-scope Markdown documents that are not reachable from policy-defined roots.
 
+## Install
+
+```bash
+npm install -D remark @recallnet/remark-lint-docs-reachability
+```
+
+## Use
+
+```js
+import { remark } from "remark";
+import remarkLintDocsReachability from "@recallnet/remark-lint-docs-reachability";
+
+await remark()
+  .use(remarkLintDocsReachability, {
+    cwd: process.cwd(),
+    policyPath: "./docs/docs-policy.json",
+  })
+  .process({
+    path: "docs/architecture/cache.md",
+    value: "# Cache\n",
+  });
+```
+
+## What It Checks
+
+- all in-scope Markdown files matched by `in_scope_paths`
+- graph roots declared by docs policy
+- repo-local Markdown links between in-scope docs
+- policy allowlists for roots, legacy docs, and orphan exclusions
+
+The rule reports messages such as:
+
+```text
+Document is not reachable from policy roots: docs/architecture/orphan.md
+```
+
+## Options
+
+- `cwd`
+  Repository root used to resolve the docs policy and scan in-scope docs.
+- `policyPath`
+  Path to the docs policy file relative to `cwd`.
+  Defaults to `docs/docs-policy.json`.
+
+## Notes
+
+- External links are ignored. Reachability is only about repo-owned docs.
+- Missing local link targets are ignored here; link correctness belongs to `remark-validate-links`.
+- Broken symlinks outside the docs graph are skipped instead of crashing the scan.
+
 This package intentionally complements:
 
 - `remark-validate-links` for link validity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recallnet/remark-lint-docs-reachability",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Remark plugin that flags markdown docs not reachable from policy roots.",
   "license": "MIT",
   "type": "module",
@@ -27,7 +27,7 @@
   "dependencies": {
     "remark": "^15.0.1",
     "remark-frontmatter": "^5.0.0",
-    "@recallnet/docs-governance-policy": "0.2.2"
+    "@recallnet/docs-governance-policy": "0.2.3"
   },
   "publishConfig": {
     "access": "public"

package/src/index.js

@@ -170,6 +170,8 @@ export function buildReachabilityReport(options = {}) {
 }
 
 export default function remarkLintDocsReachability(options = {}) {
+  let cachedReport = null;
+
   return (_tree, file) => {
     const cwd = options.cwd ? resolve(options.cwd) : process.cwd();
     const filePath = file.path ? normalizePath(relative(cwd, file.path)) : "";
@@ -178,7 +180,10 @@ export default function remarkLintDocsReachability(options = {}) {
       return;
     }
 
-    const report = buildReachabilityReport({ cwd, policyPath: options.policyPath });
+    // @context decision !high [verified:2026-03-27] — Cache the reachability report for the lifetime of one remark process.
+    // remark invokes this rule once per file, but the orphan graph is repo-global. Rebuilding it per file turned 100-doc hooks into dozens of redundant full-doc parses.
+    cachedReport ??= buildReachabilityReport({ cwd, policyPath: options.policyPath });
+    const report = cachedReport;
     if (report.orphanDocuments.includes(filePath)) {
       file.message(`Document is not reachable from policy roots: ${filePath}`, {
         ruleId: RULE_ID,