harnery 0.35.0 → 0.36.0

package/src/lazy-commands.ts

@@ -0,0 +1,294 @@
+import { type Command, Option, type ParseOptions } from "commander";
+
+const lazyState = Symbol("harnery.lazy-command-state");
+
+export interface LazyCommandDefinition {
+  /** Commander signature, including any top-level positional arguments. */
+  command: string;
+  description: string;
+  aliases?: readonly string[];
+  hidden?: boolean;
+  /** Preserve the `[options]` marker in root help without loading the implementation. */
+  hasOptions?: boolean;
+}
+
+export interface LazyCommandBundle {
+  commands: readonly LazyCommandDefinition[];
+  load(program: Command): void | Promise<void>;
+}
+
+type LoadStatus = "placeholder" | "loading" | "loaded";
+
+interface RegisteredBundle {
+  readonly definition: LazyCommandBundle;
+  readonly placeholders: Map<string, Command>;
+  status: LoadStatus;
+}
+
+interface LazyCommandState {
+  readonly bundles: RegisteredBundle[];
+  readonly byName: Map<string, RegisteredBundle>;
+  readonly hooks: Map<string, Array<(program: Command) => void | Promise<void>>>;
+  readonly originalParse: Command["parse"];
+  readonly originalParseAsync: Command["parseAsync"];
+}
+
+/**
+ * Add lightweight top-level command placeholders whose implementations load
+ * immediately before Commander parses the selected command.
+ */
+export function registerLazyCommandBundles(
+  program: Command,
+  definitions: readonly LazyCommandBundle[],
+): Command {
+  const state = stateFor(program);
+  for (const definition of definitions) {
+    const registered: RegisteredBundle = {
+      definition,
+      placeholders: new Map(),
+      status: "placeholder",
+    };
+    for (const metadata of definition.commands) {
+      const name = commandName(metadata.command);
+      const claimedNames = [name, ...(metadata.aliases ?? [])];
+      for (const claimedName of claimedNames) {
+        if (state.byName.has(claimedName) || findCommand(program, claimedName)) {
+          throw new Error(`Cannot register lazy command "${claimedName}": name already exists`);
+        }
+      }
+
+      const placeholder = program
+        .command(metadata.command, { hidden: metadata.hidden === true })
+        .description(metadata.description);
+      for (const alias of metadata.aliases ?? []) placeholder.alias(alias);
+      if (metadata.hasOptions) {
+        placeholder.addOption(new Option("--__lazy-command-placeholder").hideHelp());
+      }
+
+      registered.placeholders.set(name, placeholder);
+      for (const claimedName of claimedNames) state.byName.set(claimedName, registered);
+    }
+    state.bundles.push(registered);
+  }
+  return program;
+}
+
+/** Load one top-level command by canonical name or alias. */
+export async function loadLazyCommand(
+  program: Command,
+  name: string,
+): Promise<Command | undefined> {
+  const state = getState(program);
+  const bundle = state?.byName.get(name);
+  if (!state || !bundle) return findCommand(program, name);
+  await loadBundle(program, state, bundle);
+  return findCommand(program, name);
+}
+
+/** Materialize every remaining lazy bundle, for whole-tree discovery and completion. */
+export async function loadAllLazyCommands(program: Command): Promise<Command> {
+  const state = getState(program);
+  if (!state) return program;
+  for (const bundle of state.bundles) await loadBundle(program, state, bundle);
+  return program;
+}
+
+/** Run a host hook after a named lazy command becomes concrete. */
+export async function onLazyCommandLoaded(
+  program: Command,
+  name: string,
+  hook: (program: Command) => void | Promise<void>,
+): Promise<void> {
+  const state = getState(program);
+  const bundle = state?.byName.get(name);
+  if (!state || !bundle || bundle.status === "loaded") {
+    await hook(program);
+    return;
+  }
+  const hooks = state.hooks.get(name) ?? [];
+  hooks.push(hook);
+  state.hooks.set(name, hooks);
+}
+
+function stateFor(program: Command): LazyCommandState {
+  const existing = getState(program);
+  if (existing) return existing;
+
+  const originalParse = program.parse;
+  const originalParseAsync = program.parseAsync;
+  const state: LazyCommandState = {
+    bundles: [],
+    byName: new Map(),
+    hooks: new Map(),
+    originalParse,
+    originalParseAsync,
+  };
+  Object.defineProperty(program, lazyState, { value: state });
+
+  program.parseAsync = async function lazyParseAsync(
+    argv?: readonly string[],
+    parseOptions?: ParseOptions,
+  ): Promise<Command> {
+    const selected = selectedCommand(program, state, argv, parseOptions);
+    if (selected) await loadBundle(program, state, selected);
+    return originalParseAsync.call(this, argv, parseOptions);
+  };
+
+  program.parse = function lazyParse(
+    argv?: readonly string[],
+    parseOptions?: ParseOptions,
+  ): Command {
+    const selected = selectedCommand(program, state, argv, parseOptions);
+    if (selected && selected.status !== "loaded") {
+      throw new Error(
+        `Command "${selected.definition.commands[0]?.command ?? "unknown"}" loads asynchronously; use parseAsync()`,
+      );
+    }
+    return originalParse.call(this, argv, parseOptions);
+  };
+
+  return state;
+}
+
+function getState(program: Command): LazyCommandState | undefined {
+  return (program as Command & { [lazyState]?: LazyCommandState })[lazyState];
+}
+
+async function loadBundle(
+  program: Command,
+  state: LazyCommandState,
+  bundle: RegisteredBundle,
+): Promise<void> {
+  if (bundle.status === "loaded" || bundle.status === "loading") return;
+  bundle.status = "loading";
+
+  const positions = new Map<string, number>();
+  for (const [name, placeholder] of bundle.placeholders) {
+    const index = program.commands.indexOf(placeholder);
+    if (index >= 0) positions.set(name, index);
+  }
+  for (const placeholder of [...bundle.placeholders.values()].sort(
+    (a, b) => program.commands.indexOf(b) - program.commands.indexOf(a),
+  )) {
+    const index = program.commands.indexOf(placeholder);
+    if (index >= 0) mutableCommands(program).splice(index, 1);
+  }
+
+  const commandsBefore = new Set(program.commands);
+  try {
+    await bundle.definition.load(program);
+    for (const metadata of bundle.definition.commands) {
+      const name = commandName(metadata.command);
+      const concrete = program.commands.find(
+        (candidate) => !commandsBefore.has(candidate) && candidate.name() === name,
+      );
+      if (!concrete) {
+        throw new Error(`Lazy command loader did not register "${name}"`);
+      }
+    }
+
+    restoreCommandOrder(program, bundle, positions);
+    bundle.status = "loaded";
+    for (const metadata of bundle.definition.commands) {
+      const name = commandName(metadata.command);
+      for (const hook of state.hooks.get(name) ?? []) await hook(program);
+      state.hooks.delete(name);
+    }
+  } catch (error) {
+    for (let index = program.commands.length - 1; index >= 0; index--) {
+      if (!commandsBefore.has(program.commands[index]!)) mutableCommands(program).splice(index, 1);
+    }
+    restorePlaceholders(program, bundle, positions);
+    bundle.status = "placeholder";
+    throw error;
+  }
+}
+
+function restoreCommandOrder(
+  program: Command,
+  bundle: RegisteredBundle,
+  positions: ReadonlyMap<string, number>,
+): void {
+  const ordered = bundle.definition.commands
+    .map((metadata) => {
+      const name = commandName(metadata.command);
+      const command = findCommand(program, name);
+      const position = positions.get(name);
+      return command && position !== undefined ? { command, position } : undefined;
+    })
+    .filter((entry): entry is { command: Command; position: number } => entry !== undefined)
+    .sort((a, b) => a.position - b.position);
+
+  for (const { command } of ordered) {
+    const index = program.commands.indexOf(command);
+    if (index >= 0) mutableCommands(program).splice(index, 1);
+  }
+  for (const { command, position } of ordered) {
+    mutableCommands(program).splice(Math.min(position, program.commands.length), 0, command);
+  }
+}
+
+function restorePlaceholders(
+  program: Command,
+  bundle: RegisteredBundle,
+  positions: ReadonlyMap<string, number>,
+): void {
+  const ordered = [...bundle.placeholders]
+    .map(([name, command]) => ({ command, position: positions.get(name) }))
+    .filter(
+      (entry): entry is { command: Command; position: number } => entry.position !== undefined,
+    )
+    .sort((a, b) => a.position - b.position);
+  for (const { command, position } of ordered) {
+    mutableCommands(program).splice(Math.min(position, program.commands.length), 0, command);
+  }
+}
+
+function selectedCommand(
+  program: Command,
+  state: LazyCommandState,
+  argv: readonly string[] | undefined,
+  parseOptions: ParseOptions | undefined,
+): RegisteredBundle | undefined {
+  const args = userArguments(argv ?? process.argv, parseOptions?.from);
+  for (let index = 0; index < args.length; index++) {
+    const token = args[index]!;
+    if (token === "--") return undefined;
+    if (token.startsWith("-")) {
+      const option = findRootOption(program, token);
+      if (option?.required || (option?.optional && !args[index + 1]?.startsWith("-"))) index++;
+      continue;
+    }
+    if (token === "help") return state.byName.get(args[index + 1] ?? "");
+    return state.byName.get(token);
+  }
+  return undefined;
+}
+
+function userArguments(
+  argv: readonly string[],
+  from: ParseOptions["from"] | undefined,
+): readonly string[] {
+  if (from === "user") return argv;
+  if (from === "electron") return argv.slice(1);
+  return argv.slice(2);
+}
+
+function findRootOption(program: Command, token: string): Option | undefined {
+  const flag = token.includes("=") ? token.slice(0, token.indexOf("=")) : token;
+  return program.options.find((option) => option.short === flag || option.long === flag);
+}
+
+function findCommand(program: Command, name: string): Command | undefined {
+  return program.commands.find(
+    (candidate) => candidate.name() === name || candidate.aliases().includes(name),
+  );
+}
+
+function mutableCommands(program: Command): Command[] {
+  return program.commands as Command[];
+}
+
+function commandName(signature: string): string {
+  return signature.trim().split(/[\s|]/, 1)[0] ?? signature;
+}

package/src/lib/docs-lint.ts

@@ -1,8 +1,10 @@
 import { existsSync as __existsSyncForDocs } from "node:fs";
 import { resolve as __resolveForDocs } from "node:path";
 import { hasYamlStatus } from "./docs-frontmatter.ts";
-import { initDocsMetadataAuditContext, runDocsMetadataAudit } from "./docs-metadata-audit.ts";
-import { sh } from "./exec.ts";
+import {
+  auditDocsMetadataRepository,
+  initDocsMetadataAuditContext,
+} from "./docs-metadata-audit.ts";
 
 // Module-level docs context, initialized by initDocsContext() before any
 // other function in this file is called. Consumers pass repo metadata
@@ -34,8 +36,13 @@ function isSubmoduleInitialized(name: string): boolean {
   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,
+  type DocsRepositorySource,
+  type DocsRepositoryView,
+} from "./docs-repository-view.ts";
 
 /**
  * Documentation linter. Enforces the docs directory-layout + naming contract.
@@ -58,6 +65,7 @@ export interface Violation {
 export interface LintOpts {
   fast?: boolean;
   repo?: string; // limit to one submodule or "." for parent
+  source?: DocsRepositorySource;
 }
 
 /** Files allowed at a submodule root level. Includes:
@@ -145,15 +153,9 @@ function getTargetRepos(opts: LintOpts): { name: string; path: string; isSubmodu
   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: string): Promise<string[]> {
-  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: DocsRepositoryView): string[] {
+  return view.trackedPaths
     .filter((f) => f.endsWith(".md"))
     .filter(
       (f) =>
@@ -164,19 +166,9 @@ async function findMarkdownFiles(root: string): Promise<string[]> {
     );
 }
 
-/** Read first N lines of a file for header inspection */
-function readHead(path: string, lines = 20): string {
-  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: string): boolean {
-  const head = readHead(path, 10);
+function isDeclaredMonolith(content: string): boolean {
+  const head = content.split("\n").slice(0, 10).join("\n");
   return /INTENTIONAL-MONOLITH/i.test(head);
 }
 
@@ -192,10 +184,14 @@ export function hasStatusHeader(path: string): boolean {
 // --- Individual checks ---
 
 /** Entry tier files exist at the repo root */
-function checkEntryTier(repoName: string, repoPath: string, isSubmodule: boolean): Violation[] {
+function checkEntryTier(
+  repoName: string,
+  view: DocsRepositoryView,
+  isSubmodule: boolean,
+): Violation[] {
   const violations: Violation[] = [];
   // README.md is required for any repo
-  if (!existsSync(join(repoPath, "README.md"))) {
+  if (!view.has("README.md")) {
     violations.push({
       severity: "error",
       repo: repoName,
@@ -205,7 +201,7 @@ function checkEntryTier(repoName: string, repoPath: string, isSubmodule: boolean
     });
   }
   // 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,
@@ -218,14 +214,9 @@ function checkEntryTier(repoName: string, repoPath: string, isSubmodule: boolean
 }
 
 /** No forbidden root-level files */
-function checkRootAllowlist(repoName: string, repoPath: string): Violation[] {
+function checkRootAllowlist(repoName: string, view: DocsRepositoryView): Violation[] {
   const violations: Violation[] = [];
-  let entries: string[];
-  try {
-    entries = readdirSync(repoPath);
-  } catch {
-    return violations;
-  }
+  const entries = view.directFileNames(".");
   for (const entry of entries) {
     if (!entry.endsWith(".md")) continue;
     if (ROOT_FILE_ALLOWLIST.has(entry)) continue;
@@ -257,27 +248,13 @@ function checkRootAllowlist(repoName: string, repoPath: string): Violation[] {
  * 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: string, repoPath: string): Violation[] {
+function checkDocsRootAllowlist(repoName: string, view: DocsRepositoryView): Violation[] {
   const violations: Violation[] = [];
   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: string[];
-  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: boolean;
-    try {
-      isFile = statSync(join(docsDir, entry)).isFile();
-    } catch {
-      continue;
-    }
-    if (!isFile) continue;
     if (!(entry.endsWith(".md") || entry.endsWith(".json"))) continue;
     if (allow.has(entry)) continue;
     violations.push({
@@ -383,13 +360,14 @@ function checkChangelogNames(repoName: string, _repoPath: string, files: string[
 }
 
 /** Intentional monoliths >30KB need a declaration banner */
-function checkMonolithDeclaration(
+async function checkMonolithDeclaration(
   repoName: string,
-  repoPath: string,
+  view: DocsRepositoryView,
   files: string[],
-): Violation[] {
+): Promise<Violation[]> {
   const violations: Violation[] = [];
   const SIZE_THRESHOLD = 30 * 1024;
+  const candidatePaths: string[] = [];
   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).
@@ -399,15 +377,17 @@ function checkMonolithDeclaration(
     if (rel.startsWith("docs/audits/")) continue;
     if (rel.startsWith("docs/issues/")) continue;
     if (rel.startsWith("docs/changelogs/")) continue;
-    const full = join(repoPath, rel);
-    let size: number;
-    try {
-      size = statSync(full).size;
-    } catch {
-      continue;
-    }
+    const size = await view.byteLength(rel);
+    if (size === null) continue;
     if (size < SIZE_THRESHOLD) continue;
-    if (isDeclaredMonolith(full)) continue;
+    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",
       repo: repoName,
@@ -426,30 +406,31 @@ export async function runLint(opts: LintOpts): Promise<Violation[]> {
   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 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 = await findMarkdownFiles(path);
+    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,
+        });
+      }
     }
   }
 

package/src/lib/docs-metadata-audit.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { parseFrontmatter } from "./docs-frontmatter.ts";
 import { isManagedDocsMetadataFile, managedDocsMetadataType } from "./docs-metadata-managed.ts";
@@ -9,7 +9,11 @@ import {
   isDocsMetadataV2,
   validateDocsMetadataV2,
 } from "./docs-metadata-v2.ts";
-import { sh } from "./exec.ts";
+import {
+  createDocsRepositoryView,
+  type DocsRepositorySource,
+  type DocsRepositoryView,
+} from "./docs-repository-view.ts";
 
 let REPO_ROOT = "";
 let SUBMODULES: readonly string[] = [];
@@ -24,6 +28,7 @@ export function initDocsMetadataAuditContext(opts: {
 
 export interface DocsMetadataAuditOpts {
   repo?: string;
+  source?: DocsRepositorySource;
 }
 
 export type DocsMetadataAuditState = "valid" | "invalid" | "legacy" | "missing";
@@ -40,20 +45,12 @@ function isInitializedRepo(path: string): boolean {
   return existsSync(join(path, ".git"));
 }
 
-async function trackedMarkdownFiles(repoPath: string): Promise<string[]> {
-  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: string, repoPath: string, path: string): DocsMetadataAuditRow | null {
-  let content: string;
-  try {
-    content = readFileSync(join(repoPath, path), "utf8");
-  } catch {
+function auditFile(
+  repoName: string,
+  path: string,
+  content: string | undefined,
+): DocsMetadataAuditRow | null {
+  if (content === undefined) {
     return {
       repo: repoName,
       path: join(repoName === "(root)" ? "" : repoName, path),
@@ -105,6 +102,17 @@ function auditFile(repoName: string, repoPath: string, path: string): DocsMetada
   };
 }
 
+export async function auditDocsMetadataRepository(
+  repoName: string,
+  view: DocsRepositoryView,
+): Promise<DocsMetadataAuditRow[]> {
+  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 is DocsMetadataAuditRow => row !== null);
+}
+
 export async function runDocsMetadataAudit(
   opts: DocsMetadataAuditOpts,
 ): Promise<DocsMetadataAuditRow[]> {
@@ -120,11 +128,8 @@ export async function runDocsMetadataAudit(
 
   const rows: DocsMetadataAuditRow[] = [];
   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));