harnery 0.35.0 → 0.37.0

package/dist/lib/coord-root-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coord-root-id.d.ts","sourceRoot":"","sources":["../../src/lib/coord-root-id.ts"],"names":[],"mappings":"AAIA,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AAEpD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGhD;AAED,wBAAgB,mBAAmB,CACjC,IAAI,GAAE,MAAM,GAAG,MAAyB,EACxC,QAAQ,SAAU,GACjB,MAAM,CAGR"}

package/dist/lib/coord-root-id.js

@@ -0,0 +1,17 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { DEFAULT_WEB_PORT } from "./local-file-url.js";
+/** Local-only endpoint used to prove that a dashboard serves the caller's repo. */
+export const COORD_ROOT_ID_PATH = "/api/coord-root";
+/**
+ * Opaque identity for a canonical coordination root. The path stays local;
+ * only its digest crosses the dashboard boundary.
+ */
+export function coordRootId(root) {
+    const canonical = realpathSync(root);
+    return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+export function localCoordRootIdUrl(port = DEFAULT_WEB_PORT, protocol = "http:") {
+    const portPart = String(port) === "" ? "" : `:${port}`;
+    return `${protocol}//127.0.0.1${portPart}${COORD_ROOT_ID_PATH}`;
+}

package/dist/lib/docs-lint.d.ts

@@ -4,6 +4,7 @@ export declare function initDocsContext(opts: {
     extraExcludedPrefixes?: readonly string[];
     docsRootAllowlist?: readonly string[];
 }): void;
+import { type DocsRepositorySource } from "./docs-repository-view.js";
 /**
  * Documentation linter. Enforces the docs directory-layout + naming contract.
  *
@@ -22,6 +23,7 @@ export interface Violation {
 export interface LintOpts {
     fast?: boolean;
     repo?: string;
+    source?: DocsRepositorySource;
 }
 /** Detect whether a file carries lifecycle status in leading YAML frontmatter. */
 export declare function hasStatusHeader(path: string): boolean;

package/dist/lib/docs-lint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-lint.d.ts","sourceRoot":"","sources":["../../src/lib/docs-lint.ts"],"names":[],"mappings":"AAeA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GAAG,IAAI,CAMP;AAaD;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA0HD,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMrD;AA0OD,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAiClE"}
+{"version":3,"file":"docs-lint.d.ts","sourceRoot":"","sources":["../../src/lib/docs-lint.ts"],"names":[],"mappings":"AAiBA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GAAG,IAAI,CAMP;AAYD,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,2BAA2B,CAAC;AAEnC;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AA0GD,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMrD;AA8ND,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAkClE"}

package/dist/lib/docs-lint.js

@@ -1,8 +1,7 @@
 import { existsSync as __existsSyncForDocs } from "node:fs";
 import { resolve as __resolveForDocs } from "node:path";
 import { hasYamlStatus } from "./docs-frontmatter.js";
-import { initDocsMetadataAuditContext, runDocsMetadataAudit } from "./docs-metadata-audit.js";
-import { sh } from "./exec.js";
+import { auditDocsMetadataRepository, initDocsMetadataAuditContext, } from "./docs-metadata-audit.js";
 // Module-level docs context, initialized by initDocsContext() before any
 // other function in this file is called. Consumers pass repo metadata
 // + an optional list of extra excluded path prefixes for project-specific
@@ -24,8 +23,9 @@ function submodulePath(name) {
 function isSubmoduleInitialized(name) {
     return __existsSyncForDocs(__resolveForDocs(REPO_ROOT, name, ".git"));
 }
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { basename, join } from "node:path";
+import { createDocsRepositoryView, } from "./docs-repository-view.js";
 /** Files allowed at a submodule root level. Includes:
  *  - In-repo conventions: README.md, CLAUDE.md, LLM-BRIEFING.md, AGENTS.md
  *  - GitHub OSS conventions: CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md,
@@ -104,16 +104,9 @@ function getTargetRepos(opts) {
     }
     return all;
 }
-/** List all tracked .md files in the given repo via `git ls-files`.
- * Returns paths relative to the repo root. Automatically skips node_modules,
- * vendor, .venv, dbt_packages, build/ etc. because they're gitignored.
- */
-async function findMarkdownFiles(root) {
-    const result = await sh('git ls-files --cached "**/*.md" "*.md"', { cwd: root });
-    if (result.exitCode !== 0 || !result.stdout)
-        return [];
-    return result.stdout
-        .split("\n")
+/** Select tracked Markdown from the coherent repository view. */
+function findMarkdownFiles(view) {
+    return view.trackedPaths
         .filter((f) => f.endsWith(".md"))
         .filter((f) => 
     // Framework dirs are excluded at any depth, not just repo root;
@@ -121,19 +114,9 @@ async function findMarkdownFiles(root) {
     !EXCLUDED_PREFIXES.some((p) => f.startsWith(p) || f.includes(`/${p}`)) &&
         !EXTRA_EXCLUDED_PREFIXES.some((p) => f.startsWith(p) || f.includes(`/${p}`)));
 }
-/** Read first N lines of a file for header inspection */
-function readHead(path, lines = 20) {
-    try {
-        const content = readFileSync(path, "utf8");
-        return content.split("\n").slice(0, lines).join("\n");
-    }
-    catch {
-        return "";
-    }
-}
 /** Detect whether a file declares itself an intentional monolith */
-function isDeclaredMonolith(path) {
-    const head = readHead(path, 10);
+function isDeclaredMonolith(content) {
+    const head = content.split("\n").slice(0, 10).join("\n");
     return /INTENTIONAL-MONOLITH/i.test(head);
 }
 /** Detect whether a file carries lifecycle status in leading YAML frontmatter. */
@@ -147,10 +130,10 @@ export function hasStatusHeader(path) {
 }
 // --- Individual checks ---
 /** Entry tier files exist at the repo root */
-function checkEntryTier(repoName, repoPath, isSubmodule) {
+function checkEntryTier(repoName, view, isSubmodule) {
     const violations = [];
     // README.md is required for any repo
-    if (!existsSync(join(repoPath, "README.md"))) {
+    if (!view.has("README.md")) {
         violations.push({
             severity: "error",
             repo: repoName,
@@ -160,7 +143,7 @@ function checkEntryTier(repoName, repoPath, isSubmodule) {
         });
     }
     // CLAUDE.md required for submodules (primary LLM context)
-    if (isSubmodule && !existsSync(join(repoPath, "CLAUDE.md"))) {
+    if (isSubmodule && !view.has("CLAUDE.md")) {
         violations.push({
             severity: "error",
             repo: repoName,
@@ -172,15 +155,9 @@ function checkEntryTier(repoName, repoPath, isSubmodule) {
     return violations;
 }
 /** No forbidden root-level files */
-function checkRootAllowlist(repoName, repoPath) {
+function checkRootAllowlist(repoName, view) {
     const violations = [];
-    let entries;
-    try {
-        entries = readdirSync(repoPath);
-    }
-    catch {
-        return violations;
-    }
+    const entries = view.directFileNames(".");
     for (const entry of entries) {
         if (!entry.endsWith(".md"))
             continue;
@@ -214,32 +191,15 @@ function checkRootAllowlist(repoName, repoPath) {
  * a no-op unless the host supplies `docsRootAllowlist`. Parent-repo only:
  * submodule `docs/` roots have their own entry tiers, not this one.
  */
-function checkDocsRootAllowlist(repoName, repoPath) {
+function checkDocsRootAllowlist(repoName, view) {
     const violations = [];
     if (DOCS_ROOT_ALLOWLIST.length === 0)
         return violations; // opt-in
     if (repoName !== "(root)")
         return violations; // parent repo only
     const allow = new Set(DOCS_ROOT_ALLOWLIST);
-    const docsDir = join(repoPath, "docs");
-    let entries;
-    try {
-        entries = readdirSync(docsDir);
-    }
-    catch {
-        return violations; // no docs/ dir — nothing to check
-    }
+    const entries = view.directFileNames("docs");
     for (const entry of entries) {
-        // Subdirs are the intended home for topic docs; only loose files matter.
-        let isFile;
-        try {
-            isFile = statSync(join(docsDir, entry)).isFile();
-        }
-        catch {
-            continue;
-        }
-        if (!isFile)
-            continue;
         if (!(entry.endsWith(".md") || entry.endsWith(".json")))
             continue;
         if (allow.has(entry))
@@ -354,9 +314,10 @@ function checkChangelogNames(repoName, _repoPath, files) {
     return violations;
 }
 /** Intentional monoliths >30KB need a declaration banner */
-function checkMonolithDeclaration(repoName, repoPath, files) {
+async function checkMonolithDeclaration(repoName, view, files) {
     const violations = [];
     const SIZE_THRESHOLD = 30 * 1024;
+    const candidatePaths = [];
     for (const rel of files) {
         // Only flag top-level docs/ files, not per-repo entry tier (LLM-BRIEFING
         // files are monoliths by convention, no banner needed).
@@ -372,17 +333,20 @@ function checkMonolithDeclaration(repoName, repoPath, files) {
             continue;
         if (rel.startsWith("docs/changelogs/"))
             continue;
-        const full = join(repoPath, rel);
-        let size;
-        try {
-            size = statSync(full).size;
-        }
-        catch {
+        const size = await view.byteLength(rel);
+        if (size === null)
             continue;
-        }
         if (size < SIZE_THRESHOLD)
             continue;
-        if (isDeclaredMonolith(full))
+        candidatePaths.push(rel);
+    }
+    const texts = await view.readTexts(candidatePaths);
+    for (const rel of candidatePaths) {
+        const content = texts.get(rel);
+        if (content === undefined || isDeclaredMonolith(content))
+            continue;
+        const size = await view.byteLength(rel);
+        if (size === null)
             continue;
         violations.push({
             severity: "warning",
@@ -399,27 +363,28 @@ export async function runLint(opts) {
     const violations = [];
     const repos = getTargetRepos(opts);
     for (const { name, path, isSubmodule } of repos) {
-        violations.push(...checkEntryTier(name, path, isSubmodule));
-        violations.push(...checkRootAllowlist(name, path));
-        violations.push(...checkDocsRootAllowlist(name, path));
-        const files = await findMarkdownFiles(path);
+        const view = await createDocsRepositoryView(path, opts.source ?? "worktree");
+        violations.push(...checkEntryTier(name, view, isSubmodule));
+        violations.push(...checkRootAllowlist(name, view));
+        violations.push(...checkDocsRootAllowlist(name, view));
+        const files = findMarkdownFiles(view);
         violations.push(...checkNamingConvention(name, path, files));
         violations.push(...checkDatedDirs(name, path, files));
         violations.push(...checkChangelogNames(name, path, files));
         if (!opts.fast) {
-            violations.push(...checkMonolithDeclaration(name, path, files));
+            violations.push(...(await checkMonolithDeclaration(name, view, files)));
         }
-    }
-    const metadataRows = await runDocsMetadataAudit({ repo: opts.repo });
-    for (const row of metadataRows) {
-        for (const issue of row.issues.filter((entry) => entry.severity === "error")) {
-            violations.push({
-                severity: "error",
-                repo: row.repo,
-                path: row.path,
-                rule: `metadata-v2:${issue.code}`,
-                message: issue.field ? `${issue.field}: ${issue.message}` : issue.message,
-            });
+        const metadataRows = await auditDocsMetadataRepository(name, view);
+        for (const row of metadataRows) {
+            for (const issue of row.issues.filter((entry) => entry.severity === "error")) {
+                violations.push({
+                    severity: "error",
+                    repo: row.repo,
+                    path: row.path,
+                    rule: `metadata-v2:${issue.code}`,
+                    message: issue.field ? `${issue.field}: ${issue.message}` : issue.message,
+                });
+            }
         }
     }
     return violations;

package/dist/lib/docs-metadata-audit.d.ts

@@ -1,10 +1,12 @@
 import { type DocsMetadataProfile, type DocsMetadataValidationIssue } from "./docs-metadata-v2.js";
+import { type DocsRepositorySource, type DocsRepositoryView } from "./docs-repository-view.js";
 export declare function initDocsMetadataAuditContext(opts: {
     repoRoot: string;
     submodules: readonly string[];
 }): void;
 export interface DocsMetadataAuditOpts {
     repo?: string;
+    source?: DocsRepositorySource;
 }
 export type DocsMetadataAuditState = "valid" | "invalid" | "legacy" | "missing";
 export interface DocsMetadataAuditRow {
@@ -14,6 +16,7 @@ export interface DocsMetadataAuditRow {
     profile: DocsMetadataProfile | null;
     issues: DocsMetadataValidationIssue[];
 }
+export declare function auditDocsMetadataRepository(repoName: string, view: DocsRepositoryView): Promise<DocsMetadataAuditRow[]>;
 export declare function runDocsMetadataAudit(opts: DocsMetadataAuditOpts): Promise<DocsMetadataAuditRow[]>;
 export declare function auditDocsMetadataText(content: string, path: string): DocsMetadataAuditRow | null;
 //# sourceMappingURL=docs-metadata-audit.d.ts.map

package/dist/lib/docs-metadata-audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-metadata-audit.d.ts","sourceRoot":"","sources":["../../src/lib/docs-metadata-audit.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EAIjC,MAAM,uBAAuB,CAAC;AAM/B,wBAAgB,4BAA4B,CAAC,IAAI,EAAE;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B,GAAG,IAAI,CAGP;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhF,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,sBAAsB,CAAC;IAC9B,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC,MAAM,EAAE,2BAA2B,EAAE,CAAC;CACvC;AAuED,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAqBjC;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAiChG"}
+{"version":3,"file":"docs-metadata-audit.d.ts","sourceRoot":"","sources":["../../src/lib/docs-metadata-audit.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EAIjC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACxB,MAAM,2BAA2B,CAAC;AAKnC,wBAAgB,4BAA4B,CAAC,IAAI,EAAE;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B,GAAG,IAAI,CAGP;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhF,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,sBAAsB,CAAC;IAC9B,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC,MAAM,EAAE,2BAA2B,EAAE,CAAC;CACvC;AA+DD,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAMjC;AAED,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAkBjC;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAiChG"}

package/dist/lib/docs-metadata-audit.js

@@ -1,9 +1,9 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { parseFrontmatter } from "./docs-frontmatter.js";
 import { isManagedDocsMetadataFile, managedDocsMetadataType } from "./docs-metadata-managed.js";
 import { docsMetadataProfileForType, isDocsMetadataV2, validateDocsMetadataV2, } from "./docs-metadata-v2.js";
-import { sh } from "./exec.js";
+import { createDocsRepositoryView, } from "./docs-repository-view.js";
 let REPO_ROOT = "";
 let SUBMODULES = [];
 export function initDocsMetadataAuditContext(opts) {
@@ -13,21 +13,8 @@ export function initDocsMetadataAuditContext(opts) {
 function isInitializedRepo(path) {
     return existsSync(join(path, ".git"));
 }
-async function trackedMarkdownFiles(repoPath) {
-    const result = await sh('git ls-files --cached "**/*.md" "*.md"', { cwd: repoPath });
-    if (result.exitCode !== 0 || !result.stdout.trim())
-        return [];
-    return result.stdout
-        .trim()
-        .split("\n")
-        .filter((path) => path.endsWith(".md"));
-}
-function auditFile(repoName, repoPath, path) {
-    let content;
-    try {
-        content = readFileSync(join(repoPath, path), "utf8");
-    }
-    catch {
+function auditFile(repoName, path, content) {
+    if (content === undefined) {
         return {
             repo: repoName,
             path: join(repoName === "(root)" ? "" : repoName, path),
@@ -76,6 +63,13 @@ function auditFile(repoName, repoPath, path) {
         ],
     };
 }
+export async function auditDocsMetadataRepository(repoName, view) {
+    const files = view.trackedPaths.filter((path) => path.endsWith(".md"));
+    const texts = await view.readTexts(files);
+    return files
+        .map((path) => auditFile(repoName, path, texts.get(path)))
+        .filter((row) => row !== null);
+}
 export async function runDocsMetadataAudit(opts) {
     const targets = [
         { name: "(root)", path: REPO_ROOT },
@@ -87,12 +81,8 @@ export async function runDocsMetadataAudit(opts) {
         throw new Error(`Unknown repository: ${opts.repo}`);
     const rows = [];
     for (const target of selected) {
-        const files = await trackedMarkdownFiles(target.path);
-        for (const path of files) {
-            const row = auditFile(target.name, target.path, path);
-            if (row)
-                rows.push(row);
-        }
+        const view = await createDocsRepositoryView(target.path, opts.source ?? "worktree");
+        rows.push(...(await auditDocsMetadataRepository(target.name, view)));
     }
     return rows.sort((a, b) => a.path.localeCompare(b.path));
 }

package/dist/lib/docs-metadata-sync.d.ts

@@ -6,6 +6,7 @@ export interface DocsMetadataSyncOpts {
     repo?: string;
     files?: string[];
     check?: boolean;
+    cached?: boolean;
     reviewed?: boolean;
     now?: string;
 }

package/dist/lib/docs-metadata-sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-metadata-sync.d.ts","sourceRoot":"","sources":["../../src/lib/docs-metadata-sync.ts"],"names":[],"mappings":"AAWA,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B,GAAG,IAAI,CAGP;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACtD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAyED,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAyJhC"}
+{"version":3,"file":"docs-metadata-sync.d.ts","sourceRoot":"","sources":["../../src/lib/docs-metadata-sync.ts"],"names":[],"mappings":"AAYA,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B,GAAG,IAAI,CAGP;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACtD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAqFD,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAkKhC"}

package/dist/lib/docs-metadata-sync.js

@@ -4,6 +4,7 @@ import { dump as dumpYaml, JSON_SCHEMA } from "js-yaml";
 import { parseFrontmatter } from "./docs-frontmatter.js";
 import { managedDocsMetadataType } from "./docs-metadata-managed.js";
 import { isDocsMetadataV2, validateDocsMetadataV2 } from "./docs-metadata-v2.js";
+import { createDocsRepositoryView } from "./docs-repository-view.js";
 import { sh } from "./exec.js";
 let REPO_ROOT = "";
 let SUBMODULES = [];
@@ -25,16 +26,24 @@ function targets(repo) {
         throw new Error(`Unknown repository: ${repo}`);
     return selected;
 }
-async function changedFiles(target, explicit) {
-    if (explicit.length > 0)
-        return explicit;
-    const result = await sh("git diff --cached --name-only --diff-filter=ACMR -- '*.md'", {
-        cwd: target.path,
-    });
+async function gitMarkdownPaths(target, command) {
+    const result = await sh(command, { cwd: target.path });
     if (result.exitCode !== 0)
-        throw new Error(result.stderr || "git diff failed");
+        throw new Error(result.stderr || `${command} failed`);
     return result.stdout.split("\n").filter(Boolean);
 }
+async function changedFiles(target, explicit, check) {
+    if (explicit.length > 0)
+        return explicit;
+    const staged = await gitMarkdownPaths(target, "git diff --cached --name-only --diff-filter=ACMR -- '*.md'");
+    if (check)
+        return staged;
+    const [unstaged, untracked] = await Promise.all([
+        gitMarkdownPaths(target, "git diff --name-only --diff-filter=ACMR -- '*.md'"),
+        gitMarkdownPaths(target, "git ls-files --others --exclude-standard -- '*.md'"),
+    ]);
+    return [...new Set([...staged, ...unstaged, ...untracked])];
+}
 async function headContent(target, path) {
     const result = await sh(`git show HEAD:${JSON.stringify(path)}`, { cwd: target.path });
     return result.exitCode === 0 ? result.stdout : null;
@@ -73,14 +82,23 @@ function addDays(value, days) {
     return date.toISOString().replace(".000Z", "Z");
 }
 export async function runDocsMetadataSync(opts) {
+    if (opts.cached && !opts.check) {
+        throw new Error("--cached requires --check because Git index validation is read-only");
+    }
     const now = opts.now ?? new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
     const rows = [];
     for (const target of targets(opts.repo)) {
-        for (const path of await changedFiles(target, opts.files ?? [])) {
+        const paths = await changedFiles(target, opts.files ?? [], opts.check ?? false);
+        const cachedView = opts.cached ? await createDocsRepositoryView(target.path, "index") : null;
+        const cachedTexts = cachedView ? await cachedView.readTexts(paths) : null;
+        for (const path of paths) {
             const full = join(target.path, path);
-            if (!existsSync(full))
+            if (cachedView ? !cachedView.has(path) : !existsSync(full))
                 continue;
-            const currentText = readFileSync(full, "utf8");
+            const currentText = cachedView ? cachedTexts?.get(path) : readFileSync(full, "utf8");
+            if (currentText === undefined) {
+                throw new Error(`Git index content could not be read for ${path}`);
+            }
             const current = parseFrontmatter(currentText);
             if (!managedDocsMetadataType(path, current.data, current.raw !== null))
                 continue;

package/dist/lib/docs-repository-view.d.ts

@@ -0,0 +1,22 @@
+export type DocsRepositorySource = "worktree" | "index";
+/**
+ * One coherent repository view for documentation commands.
+ *
+ * Worktree mode preserves the interactive commands' existing behavior. Index
+ * mode reads both path membership and file bytes through Git, so a pre-commit
+ * hook validates the exact index Git handed to it. During a path-scoped commit,
+ * Git exposes its temporary partial-commit index through GIT_INDEX_FILE; the
+ * view deliberately inherits that environment instead of rediscovering the
+ * shared working tree.
+ */
+export interface DocsRepositoryView {
+    readonly root: string;
+    readonly source: DocsRepositorySource;
+    readonly trackedPaths: readonly string[];
+    has(path: string): boolean;
+    directFileNames(directory: string): string[];
+    readTexts(paths: readonly string[]): Promise<Map<string, string>>;
+    byteLength(path: string): Promise<number | null>;
+}
+export declare function createDocsRepositoryView(root: string, source?: DocsRepositorySource): Promise<DocsRepositoryView>;
+//# sourceMappingURL=docs-repository-view.d.ts.map

package/dist/lib/docs-repository-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-repository-view.d.ts","sourceRoot":"","sources":["../../src/lib/docs-repository-view.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,OAAO,CAAC;AAOxD;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7C,SAAS,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAClD;AAkHD,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,oBAAiC,GACxC,OAAO,CAAC,kBAAkB,CAAC,CAwE7B"}

package/dist/lib/docs-repository-view.js

@@ -0,0 +1,185 @@
+import { spawn } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { exec } from "./exec.js";
+function normalize(path) {
+    return path.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+function trackedPathList(stdout) {
+    return stdout.split("\0").map(normalize).filter(Boolean);
+}
+async function worktreePaths(root) {
+    const result = await exec(["git", "ls-files", "--cached", "-z"], { cwd: root, trim: false });
+    if (result.exitCode !== 0) {
+        // Worktree lint historically supports non-repository fixtures and simply
+        // has no tracked-file checks to run there. Index mode remains strict.
+        return [];
+    }
+    return trackedPathList(result.stdout);
+}
+async function indexEntries(root) {
+    const result = await exec(["git", "ls-files", "--cached", "--stage", "-z"], {
+        cwd: root,
+        trim: false,
+    });
+    if (result.exitCode !== 0) {
+        throw new Error(result.stderr || "git ls-files --stage failed");
+    }
+    const entries = new Map();
+    for (const record of result.stdout.split("\0").filter(Boolean)) {
+        const tab = record.indexOf("\t");
+        if (tab === -1)
+            throw new Error(`invalid git ls-files --stage record: ${record}`);
+        const [mode, oid, stageText] = record.slice(0, tab).split(" ");
+        const path = normalize(record.slice(tab + 1));
+        const stage = Number.parseInt(stageText ?? "", 10);
+        if (!mode || !oid || !Number.isInteger(stage)) {
+            throw new Error(`invalid git ls-files --stage record for ${path}`);
+        }
+        if (stage !== 0) {
+            throw new Error(`cannot validate an index with unmerged entry: ${path}`);
+        }
+        entries.set(path, { oid, stage });
+    }
+    return entries;
+}
+function parseBatch(stdout, requested) {
+    const blobs = new Map();
+    let offset = 0;
+    for (const oid of requested) {
+        const newline = stdout.indexOf(0x0a, offset);
+        if (newline === -1)
+            throw new Error(`git cat-file omitted the header for ${oid}`);
+        const header = stdout.subarray(offset, newline).toString("utf8");
+        offset = newline + 1;
+        const [reportedOid, type, sizeText] = header.split(" ");
+        const size = Number.parseInt(sizeText ?? "", 10);
+        if (reportedOid !== oid || type !== "blob" || !Number.isInteger(size) || size < 0) {
+            throw new Error(`git cat-file returned an invalid blob header for ${oid}: ${header}`);
+        }
+        const end = offset + size;
+        if (end > stdout.length)
+            throw new Error(`git cat-file truncated blob ${oid}`);
+        blobs.set(oid, stdout.subarray(offset, end));
+        offset = end;
+        if (stdout[offset] !== 0x0a)
+            throw new Error(`git cat-file omitted the separator for ${oid}`);
+        offset += 1;
+    }
+    return blobs;
+}
+function readIndexBlobs(root, oids) {
+    const unique = [...new Set(oids)];
+    if (unique.length === 0)
+        return Promise.resolve(new Map());
+    return new Promise((resolveResult, rejectResult) => {
+        const process = spawn("git", ["cat-file", "--batch"], {
+            cwd: root,
+            env: { ...globalThis.process.env },
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        const stdout = [];
+        const stderr = [];
+        const timer = setTimeout(() => process.kill(), 30_000);
+        process.stdout.on("data", (chunk) => stdout.push(chunk));
+        process.stderr.on("data", (chunk) => stderr.push(chunk));
+        process.on("error", (error) => {
+            clearTimeout(timer);
+            rejectResult(error);
+        });
+        process.on("close", (code) => {
+            clearTimeout(timer);
+            if (code !== 0) {
+                rejectResult(new Error(Buffer.concat(stderr).toString("utf8").trim() || "git cat-file failed"));
+                return;
+            }
+            try {
+                resolveResult(parseBatch(Buffer.concat(stdout), unique));
+            }
+            catch (error) {
+                rejectResult(error);
+            }
+        });
+        process.stdin.end(`${unique.join("\n")}\n`);
+    });
+}
+function directIndexFiles(paths, directory) {
+    const normalizedDirectory = normalize(directory).replace(/\/$/, "");
+    return paths
+        .filter((path) => normalize(dirname(path)) === normalizedDirectory)
+        .map((path) => basename(path));
+}
+export async function createDocsRepositoryView(root, source = "worktree") {
+    if (source === "worktree") {
+        const trackedPaths = await worktreePaths(root);
+        return {
+            root,
+            source,
+            trackedPaths,
+            has: (path) => existsSync(join(root, path)),
+            directFileNames: (directory) => {
+                try {
+                    return readdirSync(join(root, directory)).filter((entry) => {
+                        try {
+                            return statSync(join(root, directory, entry)).isFile();
+                        }
+                        catch {
+                            return false;
+                        }
+                    });
+                }
+                catch {
+                    return [];
+                }
+            },
+            readTexts: async (paths) => {
+                const texts = new Map();
+                for (const path of paths) {
+                    try {
+                        texts.set(path, readFileSync(join(root, path), "utf8"));
+                    }
+                    catch {
+                        // The caller decides whether a missing tracked path is a finding.
+                    }
+                }
+                return texts;
+            },
+            byteLength: async (path) => {
+                try {
+                    return statSync(join(root, path)).size;
+                }
+                catch {
+                    return null;
+                }
+            },
+        };
+    }
+    const entries = await indexEntries(root);
+    const trackedPaths = [...entries.keys()];
+    const textCache = new Map();
+    const loadTexts = async (paths) => {
+        const wanted = [...new Set(paths.map(normalize))].filter((path) => entries.has(path));
+        const missing = wanted.filter((path) => !textCache.has(path));
+        const oids = missing.map((path) => entries.get(path).oid);
+        const blobs = await readIndexBlobs(root, oids);
+        for (const path of missing) {
+            const blob = blobs.get(entries.get(path).oid);
+            if (blob)
+                textCache.set(path, blob.toString("utf8"));
+        }
+        return new Map(wanted.flatMap((path) => (textCache.has(path) ? [[path, textCache.get(path)]] : [])));
+    };
+    return {
+        root,
+        source,
+        trackedPaths,
+        has: (path) => entries.has(normalize(path)),
+        directFileNames: (directory) => directIndexFiles(trackedPaths, directory),
+        readTexts: loadTexts,
+        byteLength: async (path) => {
+            const normalized = normalize(path);
+            const text = (await loadTexts([normalized])).get(normalized);
+            return text === undefined ? null : Buffer.byteLength(text, "utf8");
+        },
+    };
+}