all-hands-cli 0.1.15 → 0.1.16

package/.allhands/harness/src/commands/complexity.ts

@@ -1,7 +1,7 @@
 /**
  * Complexity command - Get complexity metrics for files or directories.
  *
- * Uses ctags to count symbols for broader language support.
+ * Provides line counts and estimated token counts for source files.
  *
  * Command:
  *   ah complexity <path>  - Get complexity metrics
@@ -17,15 +17,11 @@ import {
   CommandResult,
 } from "../lib/base-command.js";
 import { getProjectRoot } from "../lib/git.js";
-import {
-  checkCtagsAvailable,
-  generateCtagsIndex,
-  getFileSymbols,
-} from "../lib/ctags.js";
+
+const SOURCE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs", ".java", ".swift", ".rb", ".kt"];
 
 /**
  * Get complexity metrics for a file or directory.
- * Uses ctags to count symbols instead of AST parsing.
  */
 async function complexity(pathArg: string): Promise<CommandResult> {
   const projectRoot = getProjectRoot();
@@ -41,70 +37,27 @@ async function complexity(pathArg: string): Promise<CommandResult> {
     };
   }
 
-  // Check ctags availability
-  const ctagsCheck = checkCtagsAvailable();
-  if (!ctagsCheck.available) {
-    return {
-      success: false,
-      error: `ctags_unavailable: ${ctagsCheck.error}`,
-    };
-  }
-
   const stat = statSync(absolutePath);
 
   if (stat.isFile()) {
-    // Single file complexity
     const content = readFileSync(absolutePath, "utf-8");
     const lines = content.split("\n").length;
 
-    // Get symbols via ctags
-    const { index } = generateCtagsIndex(projectRoot, { target: relativePath });
-    const symbols = getFileSymbols(index, relativePath);
-
-    const functions = symbols.filter(
-      (s) => s.kind === "function" || s.kind === "method"
-    ).length;
-    const classes = symbols.filter((s) => s.kind === "class").length;
-    const interfaces = symbols.filter(
-      (s) => s.kind === "interface" || s.kind === "type"
-    ).length;
-
-    // Count imports/exports with regex (simple heuristic)
-    const importMatches = content.match(/^import\s/gm);
-    const exportMatches = content.match(/^export\s/gm);
-
     return {
       success: true,
       data: {
         path: relativePath,
         type: "file",
-        metrics: {
-          lines,
-          functions,
-          classes,
-          interfaces,
-          imports: importMatches?.length || 0,
-          exports: exportMatches?.length || 0,
-          total_symbols: symbols.length,
-        },
+        metrics: { lines },
         estimated_tokens: Math.ceil(lines * 10),
       },
     };
   }
 
   // Directory complexity
-  const { index, entryCount } = generateCtagsIndex(projectRoot, {
-    target: relativePath,
-  });
-
-  // Aggregate stats
   let totalLines = 0;
-  let totalFunctions = 0;
-  let totalClasses = 0;
-  let totalInterfaces = 0;
   let fileCount = 0;
 
-  // Find source files and count lines
   const countDir = (dir: string): void => {
     const entries = readdirSync(dir);
     for (const entry of entries) {
@@ -115,7 +68,7 @@ async function complexity(pathArg: string): Promise<CommandResult> {
         countDir(fullPath);
       } else {
         const ext = extname(entry);
-        if ([".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs", ".java"].includes(ext)) {
+        if (SOURCE_EXTENSIONS.includes(ext)) {
           fileCount++;
           const content = readFileSync(fullPath, "utf-8");
           totalLines += content.split("\n").length;
@@ -126,34 +79,13 @@ async function complexity(pathArg: string): Promise<CommandResult> {
 
   countDir(absolutePath);
 
-  // Count symbol types from index
-  for (const fileMap of Array.from(index.values())) {
-    for (const entries of Array.from(fileMap.values())) {
-      for (const entry of entries) {
-        if (entry.kind === "function" || entry.kind === "method") {
-          totalFunctions++;
-        } else if (entry.kind === "class") {
-          totalClasses++;
-        } else if (entry.kind === "interface" || entry.kind === "type") {
-          totalInterfaces++;
-        }
-      }
-    }
-  }
-
   return {
     success: true,
     data: {
       path: relativePath,
       type: "directory",
       file_count: fileCount,
-      metrics: {
-        lines: totalLines,
-        functions: totalFunctions,
-        classes: totalClasses,
-        interfaces: totalInterfaces,
-        total_symbols: entryCount,
-      },
+      metrics: { lines: totalLines },
       estimated_tokens: Math.ceil(totalLines * 10),
     },
   };

package/.allhands/harness/src/commands/docs.ts

@@ -1,8 +1,8 @@
 /**
  * Documentation commands - validation and reference finalization.
  *
- * Uses ctags for symbol lookup (instead of AST parsing) for broader language support
- * and simpler implementation.
+ * Symbols in refs are author-provided labels. Staleness is detected via
+ * file-level git blob hashes.
  *
  * Commands:
  *   ah docs validate [--path <path>]  - Validate all refs in docs/
@@ -19,15 +19,10 @@ import {
   executeCommand,
   parseContext,
 } from "../lib/base-command.js";
-import {
-  checkCtagsAvailable,
-  findSymbolInFile,
-  generateCtagsIndex,
-} from "../lib/ctags.js";
 import {
   batchGetBlobHashes,
   findMarkdownFiles,
-  isCodeFile,
+  REF_PATTERN,
   validateDocsAsync,
 } from "../lib/docs-validation.js";
 import { getProjectRoot } from "../lib/git.js";
@@ -44,15 +39,6 @@ async function validate(docsPath: string, options?: { useCache?: boolean }): Pro
     ? docsPath
     : join(projectRoot, docsPath);
 
-  // Check ctags availability first
-  const ctagsCheck = checkCtagsAvailable();
-  if (!ctagsCheck.available) {
-    return {
-      success: false,
-      error: `ctags_unavailable: ${ctagsCheck.error}`,
-    };
-  }
-
   const excludePaths = EXCLUDED_DOC_PATHS.map((p) => join(projectRoot, p));
 
   // Run validation (with optional caching)
@@ -261,25 +247,7 @@ function finalizeSingleFile(
       continue;
     }
 
-    // For non-code files (markdown, yaml, json, etc.), treat symbol as a label (no ctags lookup)
-    if (!isCodeFile(placeholder.file)) {
-      const fullRef = `[ref:${placeholder.file}:${placeholder.symbol}:${hashResult.hash}]`;
-      finalizedContent = finalizedContent.replaceAll(placeholder.match, fullRef);
-      replacements.push({ from: placeholder.match, to: fullRef });
-      continue;
-    }
-
-    // For code files with symbol refs, verify symbol exists via ctags
-    const entry = findSymbolInFile(absoluteFilePath, placeholder.symbol, projectRoot);
-    if (!entry) {
-      errors.push({
-        placeholder: placeholder.match,
-        reason: `Symbol '${placeholder.symbol}' not found in ${placeholder.file}`,
-      });
-      continue;
-    }
-
-    // Create full ref
+    // Symbol is an author-provided label — produce the full ref with hash directly
     const fullRef = `[ref:${placeholder.file}:${placeholder.symbol}:${hashResult.hash}]`;
     finalizedContent = finalizedContent.replaceAll(placeholder.match, fullRef);
     replacements.push({ from: placeholder.match, to: fullRef });
@@ -371,18 +339,6 @@ async function finalize(docsPath: string, options?: { refresh?: boolean }): Prom
     };
   }
 
-  // Check ctags availability
-  const ctagsCheck = checkCtagsAvailable();
-  if (!ctagsCheck.available) {
-    return {
-      success: false,
-      error: `ctags_unavailable: ${ctagsCheck.error}`,
-    };
-  }
-
-  // Generate ctags index for symbol lookup
-  generateCtagsIndex(projectRoot);
-
   // Determine if path is a file or directory
   const excludePaths = EXCLUDED_DOC_PATHS.map((p) => join(projectRoot, p));
   const stat = statSync(absolutePath);

package/.allhands/harness/src/lib/docs-validation.ts

@@ -2,11 +2,11 @@
  * Documentation validation utilities.
  *
  * Validates references in documentation files against the actual codebase
- * using ctags for symbol lookup and git for staleness detection.
+ * using git blob hashes for staleness detection.
  *
  * Reference formats:
- *   [ref:file:symbol:hash] - Symbol reference (validated via ctags)
- *   [ref:file::hash]       - File-only reference (no symbol validation)
+ *   [ref:file:symbol:hash] - Symbol reference (symbol is an author-provided label)
+ *   [ref:file::hash]       - File-only reference
  *
  * Where hash = git blob hash (content-addressable, stable across merges/rebases)
  */
@@ -14,40 +14,8 @@
 import { spawnSync } from "child_process";
 import { createHash } from "crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
-import { extname, join, relative } from "path";
+import { join, relative } from "path";
 import matter from "gray-matter";
-import { CtagsIndex, generateCtagsIndex, generateCtagsIndexAsync, lookupSymbol } from "./ctags.js";
-
-/**
- * File extensions that ctags can process (programming languages).
- * Files with other extensions are treated as non-code where symbols are just labels.
- */
-const CODE_EXTENSIONS = new Set([
-  ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",  // TypeScript/JavaScript
-  ".py", ".pyw",                                   // Python
-  ".go",                                           // Go
-  ".rs",                                           // Rust
-  ".java",                                         // Java
-  ".rb",                                           // Ruby
-  ".c", ".cpp", ".cc", ".cxx", ".h", ".hpp",      // C/C++
-  ".cs",                                           // C#
-  ".php",                                          // PHP
-  ".kt", ".kts",                                   // Kotlin
-  ".swift",                                        // Swift
-  ".scala",                                        // Scala
-  ".lua",                                          // Lua
-  ".sh", ".bash", ".zsh",                         // Shell scripts
-  ".vim",                                          // Vim script
-  ".el",                                           // Emacs Lisp
-]);
-
-/**
- * Check if a file is a code file that ctags can process.
- */
-export function isCodeFile(filePath: string): boolean {
-  const ext = extname(filePath).toLowerCase();
-  return CODE_EXTENSIONS.has(ext);
-}
 
 /**
  * Validation cache for faster repeated validation runs.
@@ -484,13 +452,11 @@ export function findMarkdownFiles(dir: string, excludeReadme = false, excludePat
 /**
  * Validate a single reference.
  * @param ref - The parsed reference to validate
- * @param ctagsIndex - The ctags index for symbol lookup
  * @param projectRoot - The project root directory
  * @param hashCache - Optional pre-fetched hash map for performance
  */
 export function validateRef(
   ref: ParsedRef,
-  ctagsIndex: CtagsIndex,
   projectRoot: string,
   hashCache?: Map<string, { hash: string; success: boolean }>
 ): ValidatedRef {
@@ -525,49 +491,12 @@ export function validateRef(
     };
   }
 
-  // File-only reference: just check hash
-  if (ref.isFileOnly) {
-    if (currentHash !== ref.hash) {
-      return {
-        ...ref,
-        state: "stale",
-        reason: "File has been modified",
-        currentHash,
-      };
-    }
-    return { ...ref, state: "valid" };
-  }
-
-  // Non-code files (markdown, yaml, json, etc.): treat symbol as label, just check hash
-  if (!isCodeFile(ref.file)) {
-    if (currentHash !== ref.hash) {
-      return {
-        ...ref,
-        state: "stale",
-        reason: "File has been modified",
-        currentHash,
-      };
-    }
-    return { ...ref, state: "valid" };
-  }
-
-  // Code file symbol reference: check symbol exists via ctags
-  const entries = lookupSymbol(ctagsIndex, ref.file, ref.symbol!);
-
-  if (entries.length === 0) {
-    return {
-      ...ref,
-      state: "invalid",
-      reason: `Symbol '${ref.symbol}' not found in ${ref.file}`,
-    };
-  }
-
-  // Check hash staleness (using file-level hash for ctags approach)
+  // Check hash staleness (symbols are author-provided labels, not verified)
   if (currentHash !== ref.hash) {
     return {
       ...ref,
       state: "stale",
-      reason: "File has been modified since reference was created",
+      reason: "File has been modified",
       currentHash,
     };
   }
@@ -581,7 +510,7 @@ export function validateRef(
 export function validateDocs(
   docsPath: string,
   projectRoot: string,
-  options?: { ctagsIndex?: CtagsIndex; useCache?: boolean; excludePaths?: string[] }
+  options?: { useCache?: boolean; excludePaths?: string[] }
 ): ValidationResult {
   // Initialize result
   const result: ValidationResult = {
@@ -627,11 +556,6 @@ export function validateDocs(
     refFileHashes: {},
   };
 
-  // Generate ctags index (or use provided one)
-  const ctagsIndex =
-    options?.ctagsIndex ||
-    generateCtagsIndex(projectRoot).index;
-
   // Helper to get/create doc file entry
   const getDocEntry = (docFile: string): DocFileIssues => {
     if (!result.by_doc_file[docFile]) {
@@ -759,7 +683,7 @@ export function validateDocs(
 
   // Validate each reference (using cached hashes)
   for (const ref of allRefs) {
-    const validated = validateRef(ref, ctagsIndex, projectRoot, hashCache);
+    const validated = validateRef(ref, projectRoot, hashCache);
 
     if (validated.state === "valid") {
       result.valid_count++;
@@ -856,52 +780,12 @@ export function validateDocs(
 
 /**
  * Validate all documentation in a directory (async version).
- *
- * Identical to validateDocs but uses generateCtagsIndexAsync to avoid
- * blocking the event loop during ctags execution.
+ * Kept async for API compatibility. Delegates directly to validateDocs.
  */
 export async function validateDocsAsync(
   docsPath: string,
   projectRoot: string,
-  options?: { ctagsIndex?: CtagsIndex; useCache?: boolean; excludePaths?: string[] }
+  options?: { useCache?: boolean; excludePaths?: string[] }
 ): Promise<ValidationResult> {
-  // If a ctags index was provided, delegate to the sync version directly
-  if (options?.ctagsIndex) {
-    return validateDocs(docsPath, projectRoot, options);
-  }
-
-  // Generate ctags index asynchronously
-  const ctagsResult = await generateCtagsIndexAsync(projectRoot);
-
-  // If ctags is unavailable or failed, run validation with the empty map
-  // (to prevent a sync fallback that would also fail), then strip out the
-  // symbol-ref invalids that are false positives from the empty index.
-  if (!ctagsResult.success) {
-    const baseResult = validateDocs(docsPath, projectRoot, {
-      ...options,
-      ctagsIndex: ctagsResult.index, // empty map — avoids sync fallback
-    });
-    // Remove symbol-ref invalid entries (they're false positives from empty index)
-    const symbolInvalidCount = baseResult.invalid.filter((i) =>
-      i.reason.startsWith("Symbol '")
-    ).length;
-    baseResult.invalid = baseResult.invalid.filter(
-      (i) => !i.reason.startsWith("Symbol '")
-    );
-    // Also strip from per-doc entries
-    for (const entry of Object.values(baseResult.by_doc_file)) {
-      entry.invalid = entry.invalid.filter(
-        (i) => !i.reason.startsWith("Symbol '")
-      );
-    }
-    baseResult.invalid_count -= symbolInvalidCount;
-    baseResult.message = `ctags unavailable: ${ctagsResult.error ?? "unknown error"} — symbol ref validation skipped`;
-    return baseResult;
-  }
-
-  // Delegate to sync validateDocs with the pre-built index
-  return validateDocs(docsPath, projectRoot, {
-    ...options,
-    ctagsIndex: ctagsResult.index,
-  });
+  return validateDocs(docsPath, projectRoot, options);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "all-hands-cli",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Agentic harness for model-first software development",
   "type": "module",
   "bin": {

package/.allhands/harness/src/lib/__tests__/ctags.test.ts

@@ -1,244 +0,0 @@
-/**
- * Tests for ctags utilities.
- *
- * Note: These tests require universal-ctags to be installed.
- * Tests are skipped if ctags is not available.
- */
-
-import { describe, expect, it, beforeAll } from "vitest";
-import { join } from "path";
-import { writeFileSync, mkdirSync, rmSync, existsSync } from "fs";
-import {
-  checkCtagsAvailable,
-  generateCtagsIndex,
-  lookupSymbol,
-  searchSymbol,
-  getFileSymbols,
-  generateFileCtags,
-  findSymbolInFile,
-  CtagsIndex,
-} from "../ctags.js";
-
-// Check if ctags is available for tests
-const ctagsCheck = checkCtagsAvailable();
-const hasCtagsInstalled = ctagsCheck.available;
-
-describe("checkCtagsAvailable", () => {
-  it("returns availability status", () => {
-    const result = checkCtagsAvailable();
-    expect(result).toHaveProperty("available");
-
-    if (result.available) {
-      expect(result.version).toBeDefined();
-    } else {
-      expect(result.error).toBeDefined();
-    }
-  });
-});
-
-// Skip remaining tests if ctags not installed
-describe.skipIf(!hasCtagsInstalled)("ctags with installed ctags", () => {
-  const testDir = join(process.cwd(), ".test-ctags-temp");
-  const testFile = join(testDir, "test-sample.ts");
-
-  const sampleCode = `
-// Test TypeScript file for ctags tests
-
-export class MyClass {
-  private value: number;
-
-  constructor(value: number) {
-    this.value = value;
-  }
-
-  getValue(): number {
-    return this.value;
-  }
-
-  setValue(newValue: number): void {
-    this.value = newValue;
-  }
-}
-
-export interface MyInterface {
-  name: string;
-  age: number;
-}
-
-export function myFunction(arg: string): string {
-  return arg.toUpperCase();
-}
-
-export const MY_CONSTANT = 42;
-
-type MyType = string | number;
-`;
-
-  beforeAll(() => {
-    // Create test directory and file
-    if (existsSync(testDir)) {
-      rmSync(testDir, { recursive: true });
-    }
-    mkdirSync(testDir, { recursive: true });
-    writeFileSync(testFile, sampleCode, "utf-8");
-
-    return () => {
-      // Cleanup
-      if (existsSync(testDir)) {
-        rmSync(testDir, { recursive: true });
-      }
-    };
-  });
-
-  describe("generateFileCtags", () => {
-    it("generates ctags for a single file", () => {
-      const result = generateFileCtags(testFile, testDir);
-
-      expect(result.success).toBe(true);
-      expect(result.entries.length).toBeGreaterThan(0);
-
-      // Should find known symbols
-      const symbolNames = result.entries.map((e) => e.name);
-      expect(symbolNames).toContain("MyClass");
-      expect(symbolNames).toContain("myFunction");
-    });
-
-    it("returns error for non-existent file", () => {
-      const result = generateFileCtags(join(testDir, "nonexistent.ts"), testDir);
-
-      expect(result.success).toBe(false);
-      expect(result.error).toBeDefined();
-    });
-
-    it("includes symbol metadata", () => {
-      const result = generateFileCtags(testFile, testDir);
-      expect(result.success).toBe(true);
-
-      const classEntry = result.entries.find((e) => e.name === "MyClass");
-      expect(classEntry).toBeDefined();
-      expect(classEntry!.kind).toBe("class");
-      expect(classEntry!.line).toBeGreaterThan(0);
-    });
-  });
-
-  describe("generateCtagsIndex", () => {
-    it("generates index for directory", () => {
-      const result = generateCtagsIndex(testDir);
-
-      expect(result.success).toBe(true);
-      expect(result.entryCount).toBeGreaterThan(0);
-      expect(result.index.size).toBeGreaterThan(0);
-    });
-
-    it("indexes symbols by file and name", () => {
-      const { index, success } = generateCtagsIndex(testDir);
-      expect(success).toBe(true);
-
-      // The file path should be relative to cwd
-      const relPath = "test-sample.ts";
-      const fileMap = index.get(relPath);
-      expect(fileMap).toBeDefined();
-
-      // Should have MyClass
-      const myClass = fileMap!.get("MyClass");
-      expect(myClass).toBeDefined();
-      expect(myClass!.length).toBeGreaterThan(0);
-    });
-  });
-
-  describe("lookupSymbol", () => {
-    let index: CtagsIndex;
-
-    beforeAll(() => {
-      const result = generateCtagsIndex(testDir);
-      index = result.index;
-    });
-
-    it("finds symbol in specific file", () => {
-      const entries = lookupSymbol(index, "test-sample.ts", "MyClass");
-
-      expect(entries.length).toBeGreaterThan(0);
-      expect(entries[0].name).toBe("MyClass");
-    });
-
-    it("returns empty array for non-existent symbol", () => {
-      const entries = lookupSymbol(index, "test-sample.ts", "NonExistent");
-      expect(entries).toHaveLength(0);
-    });
-
-    it("returns empty array for non-existent file", () => {
-      const entries = lookupSymbol(index, "nonexistent.ts", "MyClass");
-      expect(entries).toHaveLength(0);
-    });
-  });
-
-  describe("searchSymbol", () => {
-    let index: CtagsIndex;
-
-    beforeAll(() => {
-      const result = generateCtagsIndex(testDir);
-      index = result.index;
-    });
-
-    it("finds symbol across all files", () => {
-      const results = searchSymbol(index, "MyClass");
-
-      expect(results.length).toBeGreaterThan(0);
-      expect(results[0].name).toBe("MyClass");
-      expect(results[0].file).toBeDefined();
-    });
-
-    it("returns empty for non-existent symbol", () => {
-      const results = searchSymbol(index, "NonExistent");
-      expect(results).toHaveLength(0);
-    });
-  });
-
-  describe("getFileSymbols", () => {
-    let index: CtagsIndex;
-
-    beforeAll(() => {
-      const result = generateCtagsIndex(testDir);
-      index = result.index;
-    });
-
-    it("returns all symbols in a file", () => {
-      const symbols = getFileSymbols(index, "test-sample.ts");
-
-      expect(symbols.length).toBeGreaterThan(0);
-
-      // Should include class, function, interface
-      const names = symbols.map((s) => s.name);
-      expect(names).toContain("MyClass");
-      expect(names).toContain("myFunction");
-    });
-
-    it("returns symbols sorted by line number", () => {
-      const symbols = getFileSymbols(index, "test-sample.ts");
-
-      for (let i = 1; i < symbols.length; i++) {
-        expect(symbols[i].line).toBeGreaterThanOrEqual(symbols[i - 1].line);
-      }
-    });
-
-    it("returns empty for non-existent file", () => {
-      const symbols = getFileSymbols(index, "nonexistent.ts");
-      expect(symbols).toHaveLength(0);
-    });
-  });
-
-  describe("findSymbolInFile", () => {
-    it("finds symbol in file", () => {
-      const entry = findSymbolInFile(testFile, "MyClass", testDir);
-
-      expect(entry).not.toBeNull();
-      expect(entry!.name).toBe("MyClass");
-      expect(entry!.kind).toBe("class");
-    });
-
-    it("returns null for non-existent symbol", () => {
-      const entry = findSymbolInFile(testFile, "NonExistent", testDir);
-      expect(entry).toBeNull();
-    });
-  });
-});

package/.allhands/harness/src/lib/ctags.ts

@@ -1,497 +0,0 @@
-/**
- * Ctags utilities for symbol lookup and validation.
- *
- * Uses universal-ctags to generate a symbol index for fast O(1) lookups.
- * This enables documentation reference validation without AST parsing.
- */
-
-import { spawn, spawnSync } from "child_process";
-import { existsSync } from "fs";
-
-/**
- * Single ctags entry representing a symbol in a file.
- */
-export interface CtagsEntry {
-  name: string;
-  path: string;
-  line: number;
-  kind: string;
-  signature?: string;
-}
-
-/**
- * Indexed ctags data for O(1) lookups.
- * Structure: Map<file, Map<symbol, CtagsEntry[]>>
- * Multiple entries per symbol possible (overloads, same name in different scopes).
- */
-export type CtagsIndex = Map<string, Map<string, CtagsEntry[]>>;
-
-/**
- * Common paths where universal-ctags might be installed.
- * Checked in order before falling back to PATH.
- */
-const CTAGS_PATHS = [
-  "/opt/homebrew/bin/ctags", // macOS ARM homebrew
-  "/usr/local/bin/ctags", // macOS Intel homebrew / Linux
-  "/usr/bin/ctags", // System PATH (may be BSD ctags)
-  "ctags", // Fall back to PATH
-];
-
-/** Cached path to universal-ctags binary */
-let cachedCtagsPath: string | null = null;
-
-/**
- * Find the universal-ctags binary, checking common paths first.
- */
-function findUniversalCtags(): { path: string; version: string } | null {
-  for (const ctagsPath of CTAGS_PATHS) {
-    // Skip absolute paths that don't exist
-    if (ctagsPath.startsWith("/") && !existsSync(ctagsPath)) {
-      continue;
-    }
-
-    const result = spawnSync(ctagsPath, ["--version"], { encoding: "utf-8" });
-
-    if (result.status !== 0) {
-      continue;
-    }
-
-    const output = result.stdout || "";
-    if (output.includes("Universal Ctags") || output.includes("universal-ctags")) {
-      const versionMatch = output.match(/Universal Ctags\s+([\d.]+)/i);
-      const version = versionMatch ? versionMatch[1] : "unknown";
-      return { path: ctagsPath, version };
-    }
-  }
-
-  return null;
-}
-
-/**
- * Get the path to universal-ctags (cached).
- */
-export function getCtagsPath(): string | null {
-  if (cachedCtagsPath !== null) {
-    return cachedCtagsPath;
-  }
-
-  const found = findUniversalCtags();
-  if (found) {
-    cachedCtagsPath = found.path;
-    return cachedCtagsPath;
-  }
-
-  return null;
-}
-
-/**
- * Check if ctags (universal-ctags) is available.
- */
-export function checkCtagsAvailable(): { available: boolean; version?: string; error?: string; path?: string } {
-  const found = findUniversalCtags();
-
-  if (!found) {
-    return {
-      available: false,
-      error:
-        "Universal Ctags not found. Install with: brew install universal-ctags\n" +
-        "Note: The BSD ctags that ships with macOS is not compatible.",
-    };
-  }
-
-  cachedCtagsPath = found.path;
-
-  return {
-    available: true,
-    version: found.version,
-    path: found.path,
-  };
-}
-
-/**
- * Parse a single line of ctags JSON output.
- */
-function parseCtagsLine(line: string): CtagsEntry | null {
-  try {
-    const entry = JSON.parse(line);
-
-    // Skip ptag entries (pseudo-tags with metadata)
-    if (entry._type === "ptag") {
-      return null;
-    }
-
-    if (entry._type !== "tag" || !entry.name || !entry.path) {
-      return null;
-    }
-
-    return {
-      name: entry.name,
-      path: entry.path,
-      line: entry.line || 0,
-      kind: entry.kind || "unknown",
-      signature: entry.signature,
-    };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Generate a ctags index for a directory.
- *
- * Uses ctags with JSON output format for reliable parsing.
- * Excludes common non-source directories.
- */
-export function generateCtagsIndex(
-  cwd: string,
-  options?: {
-    /** Additional exclude patterns */
-    exclude?: string[];
-    /** Specific file or directory to index (relative to cwd) */
-    target?: string;
-  }
-): { index: CtagsIndex; success: boolean; error?: string; entryCount: number } {
-  const check = checkCtagsAvailable();
-  if (!check.available) {
-    return {
-      index: new Map(),
-      success: false,
-      error: check.error,
-      entryCount: 0,
-    };
-  }
-
-  const excludes = [
-    "node_modules",
-    ".git",
-    "dist",
-    "build",
-    ".next",
-    "coverage",
-    "__pycache__",
-    ".venv",
-    "venv",
-    ...(options?.exclude || []),
-  ];
-
-  const args = [
-    "-R",
-    "--output-format=json",
-    "--fields=+nKS", // +n=line number, +K=kind, +S=signature
-    "-o",
-    "-", // Output to stdout
-  ];
-
-  // Add exclude patterns
-  for (const exclude of excludes) {
-    args.push(`--exclude=${exclude}`);
-  }
-
-  // Add target if specified, otherwise index current directory
-  const target = options?.target || ".";
-  args.push(target);
-
-  const ctagsPath = getCtagsPath()!;
-  const result = spawnSync(ctagsPath, args, {
-    encoding: "utf-8",
-    cwd,
-    maxBuffer: 50 * 1024 * 1024, // 50MB buffer for large repos
-  });
-
-  if (result.status !== 0) {
-    return {
-      index: new Map(),
-      success: false,
-      error: `ctags failed: ${result.stderr || "unknown error"}`,
-      entryCount: 0,
-    };
-  }
-
-  // Parse JSON output into index
-  const index: CtagsIndex = new Map();
-  let entryCount = 0;
-
-  const lines = result.stdout.split("\n");
-  for (const line of lines) {
-    if (!line.trim()) continue;
-
-    const entry = parseCtagsLine(line);
-    if (!entry) continue;
-
-    entryCount++;
-
-    // Get or create file map
-    let fileMap = index.get(entry.path);
-    if (!fileMap) {
-      fileMap = new Map();
-      index.set(entry.path, fileMap);
-    }
-
-    // Get or create symbol array
-    let symbols = fileMap.get(entry.name);
-    if (!symbols) {
-      symbols = [];
-      fileMap.set(entry.name, symbols);
-    }
-
-    symbols.push(entry);
-  }
-
-  return { index, success: true, entryCount };
-}
-
-/**
- * Look up a symbol in a specific file.
- *
- * Returns all matching entries (may have multiple for overloads).
- */
-export function lookupSymbol(
-  index: CtagsIndex,
-  filePath: string,
-  symbolName: string
-): CtagsEntry[] {
-  const fileMap = index.get(filePath);
-  if (!fileMap) {
-    return [];
-  }
-
-  return fileMap.get(symbolName) || [];
-}
-
-/**
- * Look up a symbol in any file (for searching).
- *
- * Returns all matching entries across all files.
- */
-export function searchSymbol(
-  index: CtagsIndex,
-  symbolName: string
-): Array<CtagsEntry & { file: string }> {
-  const results: Array<CtagsEntry & { file: string }> = [];
-
-  for (const [file, fileMap] of index) {
-    const entries = fileMap.get(symbolName);
-    if (entries) {
-      for (const entry of entries) {
-        results.push({ ...entry, file });
-      }
-    }
-  }
-
-  return results;
-}
-
-/**
- * Get all symbols in a file.
- */
-export function getFileSymbols(index: CtagsIndex, filePath: string): CtagsEntry[] {
-  const fileMap = index.get(filePath);
-  if (!fileMap) {
-    return [];
-  }
-
-  const symbols: CtagsEntry[] = [];
-  for (const entries of fileMap.values()) {
-    symbols.push(...entries);
-  }
-
-  // Sort by line number
-  return symbols.sort((a, b) => a.line - b.line);
-}
-
-/**
- * Generate ctags for a single file (faster for format-reference command).
- */
-export function generateFileCtags(
-  filePath: string,
-  cwd: string
-): { entries: CtagsEntry[]; success: boolean; error?: string } {
-  if (!existsSync(filePath)) {
-    return { entries: [], success: false, error: "File not found" };
-  }
-
-  const check = checkCtagsAvailable();
-  if (!check.available) {
-    return { entries: [], success: false, error: check.error };
-  }
-
-  const args = [
-    "--output-format=json",
-    "--fields=+nKS",
-    "-o",
-    "-",
-    filePath,
-  ];
-
-  const ctagsPath = getCtagsPath()!;
-  const result = spawnSync(ctagsPath, args, {
-    encoding: "utf-8",
-    cwd,
-    maxBuffer: 10 * 1024 * 1024, // 10MB buffer
-  });
-
-  if (result.status !== 0) {
-    return {
-      entries: [],
-      success: false,
-      error: `ctags failed: ${result.stderr || "unknown error"}`,
-    };
-  }
-
-  const entries: CtagsEntry[] = [];
-  const lines = result.stdout.split("\n");
-
-  for (const line of lines) {
-    if (!line.trim()) continue;
-
-    const entry = parseCtagsLine(line);
-    if (entry) {
-      entries.push(entry);
-    }
-  }
-
-  return { entries, success: true };
-}
-
-/**
- * Find a specific symbol in a file (convenience function).
- * Uses single-file ctags for efficiency.
- */
-export function findSymbolInFile(
-  filePath: string,
-  symbolName: string,
-  cwd: string
-): CtagsEntry | null {
-  const { entries, success } = generateFileCtags(filePath, cwd);
-  if (!success) {
-    return null;
-  }
-
-  // Return first match (usually there's only one)
-  return entries.find((e) => e.name === symbolName) || null;
-}
-
-/**
- * Generate a ctags index asynchronously (non-blocking).
- *
- * Same behavior as generateCtagsIndex but uses spawn instead of spawnSync,
- * keeping the event loop free during the ctags process.
- */
-export async function generateCtagsIndexAsync(
-  cwd: string,
-  options?: {
-    /** Additional exclude patterns */
-    exclude?: string[];
-    /** Specific file or directory to index (relative to cwd) */
-    target?: string;
-  }
-): Promise<{ index: CtagsIndex; success: boolean; error?: string; entryCount: number }> {
-  const check = checkCtagsAvailable();
-  if (!check.available) {
-    return {
-      index: new Map(),
-      success: false,
-      error: check.error,
-      entryCount: 0,
-    };
-  }
-
-  const excludes = [
-    "node_modules",
-    ".git",
-    "dist",
-    "build",
-    ".next",
-    "coverage",
-    "__pycache__",
-    ".venv",
-    "venv",
-    ...(options?.exclude || []),
-  ];
-
-  const args = [
-    "-R",
-    "--output-format=json",
-    "--fields=+nKS",
-    "-o",
-    "-",
-  ];
-
-  for (const exclude of excludes) {
-    args.push(`--exclude=${exclude}`);
-  }
-
-  const target = options?.target || ".";
-  args.push(target);
-
-  const ctagsPath = getCtagsPath()!;
-
-  return new Promise((resolve) => {
-    const child = spawn(ctagsPath, args, {
-      cwd,
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-
-    const chunks: Buffer[] = [];
-    let stderrOutput = "";
-
-    child.stdout?.on("data", (data: Buffer) => {
-      chunks.push(data);
-    });
-
-    child.stderr?.on("data", (data: Buffer) => {
-      stderrOutput += data.toString();
-    });
-
-    child.on("close", (code) => {
-      if (code !== 0) {
-        resolve({
-          index: new Map(),
-          success: false,
-          error: `ctags failed: ${stderrOutput || "unknown error"}`,
-          entryCount: 0,
-        });
-        return;
-      }
-
-      const stdout = Buffer.concat(chunks).toString("utf-8");
-      const index: CtagsIndex = new Map();
-      let entryCount = 0;
-
-      const lines = stdout.split("\n");
-      for (const line of lines) {
-        if (!line.trim()) continue;
-
-        const entry = parseCtagsLine(line);
-        if (!entry) continue;
-
-        entryCount++;
-
-        let fileMap = index.get(entry.path);
-        if (!fileMap) {
-          fileMap = new Map();
-          index.set(entry.path, fileMap);
-        }
-
-        let symbols = fileMap.get(entry.name);
-        if (!symbols) {
-          symbols = [];
-          fileMap.set(entry.name, symbols);
-        }
-
-        symbols.push(entry);
-      }
-
-      resolve({ index, success: true, entryCount });
-    });
-
-    child.on("error", (err) => {
-      resolve({
-        index: new Map(),
-        success: false,
-        error: `ctags spawn error: ${err.message}`,
-        entryCount: 0,
-      });
-    });
-  });
-}