harnery 0.0.1 → 0.2.0

package/src/commands/callers.ts

@@ -0,0 +1,363 @@
+import { spawn } from "node:child_process";
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+
+/**
+ * `harn callers <symbol>`: find references to a symbol across the monorepo with
+ * kind classification (call / import / type / decl / ref). Thin wrapper over
+ * grep -rnw with post-filtering: declarations + single-line comments are
+ * filtered out by default, and lines starting with " * " (multi-line comment
+ * continuation) are dropped. Inherent text-based-search limitations: multi-line
+ * string literals and block-comment interiors aren't excluded.
+ */
+
+interface CallersOpts {
+  repo?: string;
+  allRepos?: boolean;
+  lang?: string;
+  includeDecl?: boolean;
+  includeComments?: boolean;
+  limit?: string;
+  json?: boolean;
+}
+
+interface Caller {
+  repo: string;
+  file: string;
+  line: number;
+  kind: "call" | "import" | "decl" | "type" | "ref";
+  text: string;
+}
+
+interface CallersResult {
+  symbol: string;
+  repos: { name: string; cwd: string }[];
+  callers: Caller[];
+  by_kind: Record<string, number>;
+  total: number;
+  truncated: boolean;
+  elapsed_ms: number;
+}
+
+const DEFAULT_EXCLUDE_DIRS = [
+  ".git",
+  ".cache",
+  "node_modules",
+  "dist",
+  "build",
+  "out",
+  ".next",
+  "vendor",
+  "__pycache__",
+  ".venv",
+  "tmp",
+  "tmp-files",
+  "coverage",
+  ".parcel-cache",
+  ".turbo",
+  ".harnery",
+];
+
+// (no file-name excludes by default).
+const DEFAULT_EXCLUDE_FILES: string[] = [];
+
+const LANG_GLOBS: Record<string, string[]> = {
+  ts: ["*.ts", "*.tsx"],
+  js: ["*.js", "*.jsx", "*.mjs", "*.cjs"],
+  py: ["*.py"],
+  php: ["*.php"],
+  rb: ["*.rb"],
+  go: ["*.go"],
+  rs: ["*.rs"],
+};
+
+export function registerCallersCommand(
+  program: Command,
+  emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
+  program
+    .command("callers <symbol>")
+    .description(
+      "Find references to a symbol across the monorepo with kind classification " +
+        "(call / import / type / decl / ref). Heuristic: filters out declarations + " +
+        "single-line comments by default; opt back in with --include-decl / --include-comments.",
+    )
+    .option("--repo <name>", "Scope to one submodule (`.` = parent repo root)")
+    .option("--all-repos", "Search parent + every submodule")
+    .option("--lang <lang>", `File type preset (${Object.keys(LANG_GLOBS).join(", ")})`)
+    .option("--include-decl", "Include the declaration line(s) too")
+    .option("--include-comments", "Include matches in single-line comments")
+    .option("--limit <n>", "Truncate output to N matches total", "500")
+    .option("--json", "Structured JSON envelope")
+    .action(async (symbol: string, opts: CallersOpts) => {
+      try {
+        const result = await runCallers(symbol, opts, context);
+        if (opts.json) {
+          emit.config({ format: "json" });
+          emit.data(result);
+          return;
+        }
+        emit.text(`${renderCallers(result)}\n`);
+      } catch (err) {
+        emit.error({ code: "callers_failed", message: (err as Error).message });
+        process.exit(1);
+      }
+    });
+}
+
+async function runCallers(
+  symbol: string,
+  opts: CallersOpts,
+  context: HarneryProgramContext | undefined,
+): Promise<CallersResult> {
+  if (!/^[A-Za-z_$][\w$]*$/.test(symbol)) {
+    throw new Error(`symbol must be a valid identifier (got: ${symbol})`);
+  }
+
+  const started = Date.now();
+  const repos = resolveRepos(opts, context);
+  const limit = opts.limit ? Number.parseInt(opts.limit, 10) : 500;
+
+  const allCallers: Caller[] = [];
+  let truncated = false;
+
+  for (const repo of repos) {
+    if (allCallers.length >= limit) {
+      truncated = true;
+      break;
+    }
+    const remaining = limit - allCallers.length;
+    const found = await grepInRepo(symbol, opts, repo, remaining);
+    if (found.truncated) truncated = true;
+    allCallers.push(...found.callers);
+  }
+
+  const by_kind: Record<string, number> = {};
+  for (const c of allCallers) {
+    by_kind[c.kind] = (by_kind[c.kind] || 0) + 1;
+  }
+
+  return {
+    symbol,
+    repos: repos.map((r) => ({ name: r.name, cwd: r.cwd })),
+    callers: allCallers,
+    by_kind,
+    total: allCallers.length,
+    truncated,
+    elapsed_ms: Date.now() - started,
+  };
+}
+
+function resolveRepos(
+  opts: CallersOpts,
+  context: HarneryProgramContext | undefined,
+): { name: string; cwd: string }[] {
+  const repoRoot = context?.repoRoot;
+  const submodules = context?.submodules;
+  if (opts.allRepos) {
+    if (!repoRoot || !submodules) {
+      throw new Error("--all-repos requires harnery to be configured with repoRoot + submodules");
+    }
+    const out: { name: string; cwd: string }[] = [{ name: "parent", cwd: repoRoot }];
+    for (const name of submodules) out.push({ name, cwd: `${repoRoot}/${name}` });
+    return out;
+  }
+  if (opts.repo) {
+    if (opts.repo === "." || opts.repo === "parent") {
+      if (!repoRoot) {
+        throw new Error('--repo "." requires harnery to be configured with repoRoot');
+      }
+      return [{ name: "parent", cwd: repoRoot }];
+    }
+    if (!submodules || !repoRoot) {
+      throw new Error(
+        `--repo "${opts.repo}" requires harnery to be configured with repoRoot + submodules`,
+      );
+    }
+    const found = submodules.find((n) => n === opts.repo);
+    if (!found) {
+      throw new Error(`unknown repo "${opts.repo}". Valid: parent (.), ${submodules.join(", ")}`);
+    }
+    return [{ name: found, cwd: `${repoRoot}/${found}` }];
+  }
+  return [{ name: "cwd", cwd: process.cwd() }];
+}
+
+function grepInRepo(
+  symbol: string,
+  opts: CallersOpts,
+  repo: { name: string; cwd: string },
+  limit: number,
+): Promise<{ callers: Caller[]; truncated: boolean }> {
+  const args: string[] = ["-rnw", "--color=never", "-I", "-E"];
+  for (const d of DEFAULT_EXCLUDE_DIRS) args.push(`--exclude-dir=${d}`);
+  for (const f of DEFAULT_EXCLUDE_FILES) args.push(`--exclude=${f}`);
+  const langGlobs = opts.lang ? LANG_GLOBS[opts.lang] : undefined;
+  if (opts.lang && !langGlobs) {
+    throw new Error(`unknown --lang "${opts.lang}". Valid: ${Object.keys(LANG_GLOBS).join(", ")}`);
+  }
+  if (langGlobs) for (const g of langGlobs) args.push(`--include=${g}`);
+  args.push("--", symbol, ".");
+
+  return new Promise((resolveP, reject) => {
+    const proc = spawn("grep", args, { cwd: repo.cwd, stdio: ["ignore", "pipe", "pipe"] });
+    const callers: Caller[] = [];
+    let buffer = "";
+    let stderr = "";
+    let truncated = false;
+
+    proc.stdout.setEncoding("utf8");
+    proc.stdout.on("data", (chunk: string) => {
+      if (truncated) return;
+      buffer += chunk;
+      let nl = buffer.indexOf("\n");
+      while (nl >= 0) {
+        const line = buffer.slice(0, nl);
+        buffer = buffer.slice(nl + 1);
+        if (line.length !== 0) {
+          const parsed = parseCallerLine(line, symbol, opts, repo.name);
+          if (parsed) callers.push(parsed);
+          if (callers.length >= limit) {
+            truncated = true;
+            proc.kill("SIGTERM");
+            return;
+          }
+        }
+        nl = buffer.indexOf("\n");
+      }
+    });
+    proc.stderr.setEncoding("utf8");
+    proc.stderr.on("data", (chunk: string) => {
+      stderr += chunk;
+    });
+    proc.on("error", reject);
+    proc.on("close", (code) => {
+      if (buffer.length > 0 && !truncated) {
+        const parsed = parseCallerLine(buffer, symbol, opts, repo.name);
+        if (parsed) callers.push(parsed);
+      }
+      if (code !== null && code !== 0 && code !== 1 && !truncated) {
+        reject(new Error(`grep exited ${code}: ${stderr.trim() || "(no stderr)"}`));
+        return;
+      }
+      resolveP({ callers, truncated });
+    });
+  });
+}
+
+function parseCallerLine(
+  line: string,
+  symbol: string,
+  opts: CallersOpts,
+  repoName: string,
+): Caller | null {
+  const firstColon = line.indexOf(":");
+  if (firstColon < 0) return null;
+  const after = line.slice(firstColon + 1);
+  const secondColon = after.indexOf(":");
+  if (secondColon < 0) return null;
+  const lineNum = Number.parseInt(after.slice(0, secondColon), 10);
+  if (!Number.isFinite(lineNum)) return null;
+
+  const file = line.slice(0, firstColon).replace(/^\.\//, "");
+  const text = after.slice(secondColon + 1);
+
+  if (!opts.includeComments) {
+    if (/^\s*(\/\/|#|--)/.test(text)) return null;
+  }
+  if (/^\s*\*[\s/]/.test(text)) return null; // /* multi-line comment continuation
+
+  const kind = classifyMatch(text, symbol);
+  if (kind === "decl" && !opts.includeDecl) return null;
+
+  return { repo: repoName, file, line: lineNum, kind, text };
+}
+
+function classifyMatch(text: string, symbol: string): Caller["kind"] {
+  const sym = escapeRegex(symbol);
+
+  if (
+    new RegExp(
+      `^\\s*(export\\s+)?(async\\s+)?(function|class|interface|type|enum|namespace)\\s+${sym}\\b`,
+    ).test(text)
+  ) {
+    return "decl";
+  }
+  if (new RegExp(`^\\s*(export\\s+)?(const|let|var)\\s+${sym}\\b`).test(text)) return "decl";
+  if (
+    new RegExp(`^\\s*(public|private|protected)\\s+(static\\s+)?function\\s+${sym}\\b`).test(text)
+  ) {
+    return "decl";
+  }
+  if (new RegExp(`^\\s*(async\\s+)?def\\s+${sym}\\b`).test(text)) return "decl";
+  if (new RegExp(`^\\s*class\\s+${sym}\\b`).test(text)) return "decl";
+
+  if (/^\s*(import\b|from\b|use\s+|require\s*\(|include\s|require_once\s)/.test(text)) {
+    return "import";
+  }
+
+  if (new RegExp(`\\b${sym}\\s*\\(`).test(text)) return "call";
+
+  if (
+    new RegExp(
+      `(:\\s*${sym}\\b|extends\\s+${sym}\\b|implements\\s+${sym}\\b|as\\s+${sym}\\b|<${sym}[>\\s,])`,
+    ).test(text)
+  ) {
+    return "type";
+  }
+
+  return "ref";
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function renderCallers(r: CallersResult): string {
+  const lines: string[] = [];
+
+  if (r.total === 0) {
+    lines.push(`callers · ${r.symbol}: no matches`);
+    return lines.join("\n");
+  }
+
+  const summary = Object.entries(r.by_kind)
+    .sort((a, b) => b[1] - a[1])
+    .map(([k, n]) => `${k}=${n}`)
+    .join(", ");
+  lines.push(`callers · ${r.symbol} (${r.total} total: ${summary}, ${r.elapsed_ms}ms)`);
+
+  const byRepo = new Map<string, Caller[]>();
+  for (const c of r.callers) {
+    if (!byRepo.has(c.repo)) byRepo.set(c.repo, []);
+    byRepo.get(c.repo)!.push(c);
+  }
+
+  const showRepoHeader = byRepo.size > 1;
+
+  for (const [repo, callers] of byRepo) {
+    if (showRepoHeader) {
+      lines.push("");
+      lines.push(`── ${repo} (${callers.length}) ──`);
+    }
+    let lastFile = "";
+    for (const c of callers) {
+      if (c.file !== lastFile) {
+        lines.push("");
+        lines.push(`  ${c.file}`);
+        lastFile = c.file;
+      }
+      const kindLabel = `[${c.kind}]`.padEnd(8);
+      const snippet = c.text.trim().slice(0, 100);
+      lines.push(`    L${c.line.toString().padEnd(5)} ${kindLabel} ${snippet}`);
+    }
+  }
+
+  if (r.truncated) {
+    lines.push("");
+    lines.push("(truncated; pass --limit to widen)");
+  }
+
+  return lines.join("\n");
+}

package/src/commands/completion.ts

@@ -0,0 +1,193 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import {
+  type CompletionContextLookup,
+  generateBash,
+  generateFish,
+  generateZsh,
+  walkProgram,
+} from "../lib/completion/index.ts";
+
+const noopProviderRunner = async (): Promise<string[]> => [];
+const noopLookup: CompletionContextLookup = () => undefined;
+
+/**
+ * `harn completion`: emit / install shell completion scripts.
+ *
+ *   harn completion bash | zsh | fish    → write generated script to stdout
+ *   harn completion install [--shell ...] → install to the conventional location
+ *
+ * And the hidden internal entry point:
+ *
+ *   harn __complete <provider> -- <partial>
+ *     Called by the generated shell scripts at tab-time for dynamic-value
+ *     completion. Returns newline-separated candidate values. Empty exit
+ *     code 0 even on errors (don't disrupt the user's tab).
+ */
+export function registerCompletionCommand(
+  program: Command,
+  _emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
+  const lookup = context?.completionLookup ?? noopLookup;
+  const runProvider = context?.completionRunner ?? noopProviderRunner;
+  const root = program
+    .command("completion")
+    .description(
+      "Shell tab-completion. Emit a script per shell or install to the standard location.",
+    );
+
+  root
+    .command("bash")
+    .description("Emit bash completion script to stdout")
+    .action(() => {
+      const out = generateBash(walkProgram(program, lookup), program.name());
+      process.stdout.write(out); // raw bytes: shell completion scripts must be unframed (consumer evals stdout).
+    });
+
+  root
+    .command("zsh")
+    .description("Emit zsh completion script to stdout")
+    .action(() => {
+      const out = generateZsh(walkProgram(program, lookup), program.name());
+      process.stdout.write(out); // raw bytes: shell completion scripts must be unframed (consumer evals stdout).
+    });
+
+  root
+    .command("fish")
+    .description("Emit fish completion script to stdout")
+    .action(() => {
+      const out = generateFish(walkProgram(program, lookup), program.name());
+      process.stdout.write(out); // raw bytes: shell completion scripts must be unframed (consumer evals stdout).
+    });
+
+  root
+    .command("install")
+    .description("Write completion script to the conventional location for the chosen shell")
+    .option("--shell <name>", "bash | zsh | fish (default: auto-detect from $SHELL)")
+    .option("--path <file>", "Override destination path")
+    .option("--print-path", "Print the destination path and exit (no write)")
+    .action(async (opts: InstallOpts) => {
+      await installCompletion(program, opts, lookup);
+    });
+
+  // Hidden internal entry: shells call this at tab-time. `hidden: true` so
+  // `harn --help` doesn't surface it.
+  const hidden = program
+    .command("__complete <provider> [partial]", { hidden: true })
+    .description("Internal: dynamic-value completion callback for the shell")
+    .allowExcessArguments(true)
+    .action(async (provider: string, partial: string | undefined) => {
+      try {
+        const values = await runProvider(provider, partial ?? "");
+        for (const v of values) {
+          process.stdout.write(`${v}\n`); // lint-ok-emission: shell callback; newline-delimited raw values is the contract with compgen/_describe/fish.
+        }
+      } catch {
+        // Swallow errors silently: failure during tab completion should not
+        // break the user's shell.
+      }
+    });
+  // Keep TS happy that the variable is used.
+  void hidden;
+}
+
+interface InstallOpts {
+  shell?: string;
+  path?: string;
+  printPath?: boolean;
+}
+
+async function installCompletion(
+  program: Command,
+  opts: InstallOpts,
+  lookup: CompletionContextLookup,
+): Promise<void> {
+  const shell = opts.shell ?? detectShell();
+  if (!shell) {
+    process.stderr.write("Could not auto-detect shell. Pass --shell bash|zsh|fish explicitly.\n"); // lint-ok-emission: install error; stderr keeps stdout clean for --print-path piping.
+    process.exit(1);
+  }
+
+  const destination = opts.path ?? defaultInstallPath(shell, program.name());
+  if (opts.printPath) {
+    process.stdout.write(`${destination}\n`); // lint-ok-emission: --print-path is meant to be piped (e.g., dest=$(harn completion install --print-path)).
+    return;
+  }
+
+  let content: string;
+  switch (shell) {
+    case "bash":
+      content = generateBash(walkProgram(program, lookup), program.name());
+      break;
+    case "zsh":
+      content = generateZsh(walkProgram(program, lookup), program.name());
+      break;
+    case "fish":
+      content = generateFish(walkProgram(program, lookup), program.name());
+      break;
+    default:
+      process.stderr.write(`Unknown shell: ${shell}\n`); // lint-ok-emission: install-time error, see above.
+      process.exit(1);
+  }
+
+  mkdirSync(dirname(destination), { recursive: true });
+  writeFileSync(destination, content);
+  process.stderr.write(`Installed ${shell} completion to ${destination}\n`); // lint-ok-emission: install progress; stderr keeps stdout clean.
+
+  // Hint how to activate.
+  printActivationHint(shell, destination);
+}
+
+function detectShell(): string | null {
+  const shellPath = process.env.SHELL ?? "";
+  if (shellPath.endsWith("/bash")) return "bash";
+  if (shellPath.endsWith("/zsh")) return "zsh";
+  if (shellPath.endsWith("/fish")) return "fish";
+  return null;
+}
+
+function defaultInstallPath(shell: string, binName: string): string {
+  const home = process.env.HOME ?? "";
+  switch (shell) {
+    case "bash": {
+      // bash-completion v2 user-level location.
+      const xdg = process.env.XDG_DATA_HOME ?? resolve(home, ".local/share");
+      return resolve(xdg, `bash-completion/completions/${binName}`);
+    }
+    case "zsh": {
+      // Common $fpath user location. zsh auto-loads from ~/.zsh/completions if
+      // it's in $fpath.
+      return resolve(home, `.zsh/completions/_${binName}`);
+    }
+    case "fish": {
+      // Fish auto-loads everything in ~/.config/fish/completions/.
+      return resolve(home, `.config/fish/completions/${binName}.fish`);
+    }
+    default:
+      return resolve(home, `.${binName}-completion.${shell}`);
+  }
+}
+
+function printActivationHint(shell: string, path: string): void {
+  switch (shell) {
+    case "bash":
+      if (existsSync(resolve(process.env.HOME ?? "", ".bashrc"))) {
+        const bashHint = `\nTo activate now in this shell: source "${path}"\nNew shells will pick it up automatically if bash-completion is enabled.\nIf completions don't fire in new shells, add this to ~/.bashrc:\n  [ -f "${path}" ] && source "${path}"\n`;
+        process.stderr.write(bashHint); // lint-ok-emission: post-install activation hint; stderr keeps stdout clean.
+      }
+      break;
+    case "zsh": {
+      const zshHint = `\nTo activate now: autoload -U compinit && compinit\nMake sure ${resolve(path, "..")} is in your $fpath. Add to ~/.zshrc:\n  fpath=(${resolve(path, "..")} $fpath)\n  autoload -U compinit && compinit\n`;
+      process.stderr.write(zshHint); // lint-ok-emission: post-install activation hint; stderr keeps stdout clean.
+      break;
+    }
+    case "fish": {
+      const fishHint = `\nFish auto-loads completions from ${resolve(path, "..")}. New shells pick it up.\nTo activate now: source "${path}"\n`;
+      process.stderr.write(fishHint); // lint-ok-emission: post-install activation hint; stderr keeps stdout clean.
+      break;
+    }
+  }
+}