@cleocode/core 2026.3.74 → 2026.4.0

package/src/code/outline.ts

@@ -0,0 +1,214 @@
+/**
+ * smart_outline — file structural skeleton via tree-sitter.
+ *
+ * Parses a source file and returns all top-level and nested symbols
+ * with signatures only (bodies collapsed). This gives agents a ~1-2K
+ * token overview of a file vs ~12K for a full Read.
+ *
+ * @task T151
+ */
+
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import type { CodeSymbol } from '@cleocode/contracts';
+import { detectLanguage } from '../lib/tree-sitter-languages.js';
+import { parseFile } from './parser.js';
+
+/** A symbol node in the outline tree, with optional children. */
+export interface OutlineNode {
+  /** Symbol name. */
+  name: string;
+  /** Symbol kind (function, class, method, etc.). */
+  kind: string;
+  /** Start line (1-based). */
+  startLine: number;
+  /** End line (1-based). */
+  endLine: number;
+  /** Signature line(s) — the declaration without the body. */
+  signature: string;
+  /** Whether this symbol is exported. */
+  exported: boolean;
+  /** Nested symbols (methods inside classes, etc.). */
+  children: OutlineNode[];
+}
+
+/** Result of generating a smart outline for a file. */
+export interface SmartOutlineResult {
+  /** Source file path (relative). */
+  filePath: string;
+  /** Detected language. */
+  language: string;
+  /** Top-level symbol tree. */
+  symbols: OutlineNode[];
+  /** Estimated token count for this outline. */
+  estimatedTokens: number;
+  /** Parse errors (non-fatal). */
+  errors: string[];
+}
+
+/**
+ * Extract the signature line(s) from source for a symbol.
+ *
+ * Reads the opening lines of the symbol declaration up to the first
+ * opening brace or colon (for Python). This gives context without
+ * the full implementation body.
+ */
+function extractSignature(
+  lines: string[],
+  startLine: number,
+  endLine: number,
+  language: string,
+): string {
+  const start = Math.max(0, startLine - 1); // 1-based to 0-based
+  const end = Math.min(lines.length, endLine);
+
+  // For short symbols (< 3 lines), return the whole thing
+  if (end - start <= 3) {
+    return lines.slice(start, end).join('\n');
+  }
+
+  // Find the signature boundary (opening brace, colon for Python)
+  const sigLines: string[] = [];
+  for (let i = start; i < end && sigLines.length < 5; i++) {
+    const line = lines[i]!;
+    sigLines.push(line);
+
+    if (language === 'python') {
+      if (line.trimEnd().endsWith(':')) break;
+    } else {
+      if (line.includes('{')) break;
+    }
+  }
+
+  const bodyLines = end - start - sigLines.length;
+  if (bodyLines > 0) {
+    sigLines.push(`  // ... ${bodyLines} lines`);
+  }
+
+  return sigLines.join('\n');
+}
+
+/**
+ * Build a tree from flat symbols by nesting methods inside their parent classes.
+ */
+function buildTree(symbols: CodeSymbol[], lines: string[], language: string): OutlineNode[] {
+  const nodes: OutlineNode[] = [];
+  const classNodes = new Map<string, OutlineNode>();
+
+  // First pass: create all nodes
+  for (const sym of symbols) {
+    const node: OutlineNode = {
+      name: sym.name,
+      kind: sym.kind,
+      startLine: sym.startLine,
+      endLine: sym.endLine,
+      signature: extractSignature(lines, sym.startLine, sym.endLine, language),
+      exported: sym.exported ?? false,
+      children: [],
+    };
+
+    if (
+      sym.kind === 'class' ||
+      sym.kind === 'struct' ||
+      sym.kind === 'impl' ||
+      sym.kind === 'trait'
+    ) {
+      classNodes.set(sym.name, node);
+      nodes.push(node);
+    } else if (sym.kind === 'method' && sym.parent) {
+      const parent = classNodes.get(sym.parent);
+      if (parent) {
+        parent.children.push(node);
+      } else {
+        nodes.push(node);
+      }
+    } else {
+      // Check if this symbol is nested inside a class by line range
+      let nested = false;
+      for (const [, classNode] of classNodes) {
+        if (sym.startLine >= classNode.startLine && sym.endLine <= classNode.endLine) {
+          classNode.children.push(node);
+          nested = true;
+          break;
+        }
+      }
+      if (!nested) nodes.push(node);
+    }
+  }
+
+  return nodes;
+}
+
+/** Estimate token count for an outline (rough: ~4 chars per token). */
+function estimateTokens(nodes: OutlineNode[]): number {
+  let chars = 0;
+  for (const node of nodes) {
+    chars += node.signature.length + node.name.length + node.kind.length + 20; // overhead
+    chars += estimateTokens(node.children);
+  }
+  return Math.ceil(chars / 4);
+}
+
+/**
+ * Generate a smart outline for a source file.
+ *
+ * Returns a tree of symbols with signatures only (bodies collapsed),
+ * suitable for giving agents a quick structural overview.
+ *
+ * @param filePath - Absolute path to source file
+ * @param projectRoot - Project root for relative path computation
+ * @returns Smart outline result with symbol tree and token estimate
+ */
+export function smartOutline(filePath: string, projectRoot?: string): SmartOutlineResult {
+  const root = projectRoot ?? process.cwd();
+  const relPath = relative(root, filePath);
+  const language = detectLanguage(filePath);
+
+  if (!language) {
+    return {
+      filePath: relPath,
+      language: 'unknown',
+      symbols: [],
+      estimatedTokens: 0,
+      errors: ['Unsupported language'],
+    };
+  }
+
+  // Parse the file for symbols
+  const parseResult = parseFile(filePath, root);
+  if (parseResult.errors.length > 0 && parseResult.symbols.length === 0) {
+    return {
+      filePath: relPath,
+      language,
+      symbols: [],
+      estimatedTokens: 0,
+      errors: parseResult.errors,
+    };
+  }
+
+  // Read source lines for signature extraction
+  let lines: string[];
+  try {
+    lines = readFileSync(filePath, 'utf-8').split('\n');
+  } catch (err) {
+    return {
+      filePath: relPath,
+      language,
+      symbols: [],
+      estimatedTokens: 0,
+      errors: [`Failed to read file: ${err instanceof Error ? err.message : String(err)}`],
+    };
+  }
+
+  // Build symbol tree with signatures
+  const tree = buildTree(parseResult.symbols, lines, language);
+  const estimatedTokens = estimateTokens(tree);
+
+  return {
+    filePath: relPath,
+    language,
+    symbols: tree,
+    estimatedTokens,
+    errors: parseResult.errors,
+  };
+}

package/src/code/parser.ts

@@ -0,0 +1,299 @@
+/**
+ * Tree-sitter AST parser — query execution engine for code analysis.
+ *
+ * Resolves grammar paths from node_modules, writes S-expression query
+ * patterns to temp files, executes tree-sitter CLI, and parses output
+ * into structured CodeSymbol objects.
+ *
+ * @task T149
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, relative } from 'node:path';
+import type {
+  BatchParseResult,
+  CodeSymbol,
+  CodeSymbolKind,
+  ParseResult,
+} from '@cleocode/contracts';
+import { detectLanguage, type TreeSitterLanguage } from '../lib/tree-sitter-languages.js';
+
+// ---------------------------------------------------------------------------
+// Tree-sitter CLI resolution
+// ---------------------------------------------------------------------------
+
+/** Resolve the tree-sitter CLI binary from node_modules. */
+function resolveTreeSitterBin(): string {
+  const candidates = [
+    join(process.cwd(), 'packages', 'core', 'node_modules', '.bin', 'tree-sitter'),
+    join(process.cwd(), 'node_modules', '.bin', 'tree-sitter'),
+  ];
+  for (const p of candidates) {
+    if (existsSync(p)) return p;
+  }
+  throw new Error('tree-sitter CLI not found. Run: pnpm add -F @cleocode/core tree-sitter-cli');
+}
+
+// ---------------------------------------------------------------------------
+// S-expression query patterns per language family
+// ---------------------------------------------------------------------------
+
+/** Query patterns that match function/method/class/type declarations. */
+const QUERY_PATTERNS: Record<string, string> = {
+  // TypeScript / JavaScript
+  typescript: `
+(function_declaration name: (identifier) @name) @definition.function
+(method_definition name: (property_identifier) @name) @definition.method
+(class_declaration name: (type_identifier) @name) @definition.class
+(interface_declaration name: (type_identifier) @name) @definition.interface
+(type_alias_declaration name: (type_identifier) @name) @definition.type
+(enum_declaration name: (identifier) @name) @definition.enum
+(lexical_declaration (variable_declarator name: (identifier) @name)) @definition.variable
+(export_statement (function_declaration name: (identifier) @name)) @definition.function
+(export_statement (class_declaration name: (type_identifier) @name)) @definition.class
+(arrow_function) @definition.function
+`,
+  javascript: `
+(function_declaration name: (identifier) @name) @definition.function
+(method_definition name: (property_identifier) @name) @definition.method
+(class_declaration name: (identifier) @name) @definition.class
+(lexical_declaration (variable_declarator name: (identifier) @name)) @definition.variable
+(export_statement (function_declaration name: (identifier) @name)) @definition.function
+(export_statement (class_declaration name: (identifier) @name)) @definition.class
+(arrow_function) @definition.function
+`,
+  // Python
+  python: `
+(function_definition name: (identifier) @name) @definition.function
+(class_definition name: (identifier) @name) @definition.class
+(decorated_definition (function_definition name: (identifier) @name)) @definition.function
+(decorated_definition (class_definition name: (identifier) @name)) @definition.class
+`,
+  // Go
+  go: `
+(function_declaration name: (identifier) @name) @definition.function
+(method_declaration name: (field_identifier) @name) @definition.method
+(type_declaration (type_spec name: (type_identifier) @name)) @definition.type
+`,
+  // Rust
+  rust: `
+(function_item name: (identifier) @name) @definition.function
+(impl_item type: (type_identifier) @name) @definition.impl
+(struct_item name: (type_identifier) @name) @definition.struct
+(enum_item name: (type_identifier) @name) @definition.enum
+(trait_item name: (type_identifier) @name) @definition.trait
+(type_item name: (type_identifier) @name) @definition.type
+(mod_item name: (identifier) @name) @definition.module
+`,
+  // Ruby
+  ruby: `
+(method name: (identifier) @name) @definition.method
+(class name: (constant) @name) @definition.class
+(module name: (constant) @name) @definition.module
+(singleton_method name: (identifier) @name) @definition.method
+`,
+  // Java / C / C++
+  java: `
+(method_declaration name: (identifier) @name) @definition.method
+(class_declaration name: (identifier) @name) @definition.class
+(interface_declaration name: (identifier) @name) @definition.interface
+(enum_declaration name: (identifier) @name) @definition.enum
+`,
+  c: `
+(function_definition declarator: (function_declarator declarator: (identifier) @name)) @definition.function
+(struct_specifier name: (type_identifier) @name) @definition.struct
+(enum_specifier name: (type_identifier) @name) @definition.enum
+(type_definition declarator: (type_identifier) @name) @definition.type
+`,
+  cpp: `
+(function_definition declarator: (function_declarator declarator: (qualified_identifier) @name)) @definition.function
+(function_definition declarator: (function_declarator declarator: (identifier) @name)) @definition.function
+(class_specifier name: (type_identifier) @name) @definition.class
+(struct_specifier name: (type_identifier) @name) @definition.struct
+(enum_specifier name: (type_identifier) @name) @definition.enum
+(namespace_definition name: (identifier) @name) @definition.module
+`,
+};
+
+/** Map language to query pattern key. */
+function queryKeyForLanguage(lang: TreeSitterLanguage): string {
+  if (lang === 'tsx') return 'typescript';
+  return lang;
+}
+
+/** Map capture name suffix to CodeSymbolKind. */
+function captureToKind(capture: string): CodeSymbolKind {
+  const map: Record<string, CodeSymbolKind> = {
+    function: 'function',
+    method: 'method',
+    class: 'class',
+    interface: 'interface',
+    type: 'type',
+    enum: 'enum',
+    variable: 'variable',
+    constant: 'constant',
+    module: 'module',
+    import: 'import',
+    export: 'export',
+    struct: 'struct',
+    trait: 'trait',
+    impl: 'impl',
+  };
+  return map[capture] ?? 'function';
+}
+
+// ---------------------------------------------------------------------------
+// Output parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse tree-sitter query output into CodeSymbol objects.
+ *
+ * tree-sitter query output format (one match per block):
+ * ```
+ * path/to/file.ts
+ *   pattern: 0
+ *   capture: 0 - name, start: (5, 9), end: (5, 20), text: `parseFile`
+ *   capture: 1 - definition.function, start: (5, 0), end: (15, 1)
+ * ```
+ */
+function parseQueryOutput(output: string, filePath: string, language: string): CodeSymbol[] {
+  const symbols: CodeSymbol[] = [];
+  const lines = output.split('\n');
+
+  let currentName = '';
+  let currentKind: CodeSymbolKind = 'function';
+  let endLine = 0;
+
+  for (const line of lines) {
+    const nameMatch = line.match(
+      /capture: \d+ - name, start: \(\d+, \d+\), end: \(\d+, \d+\)(?:, text: `([^`]+)`)?/,
+    );
+    if (nameMatch) {
+      currentName = nameMatch[1] ?? '';
+      continue;
+    }
+
+    const defMatch = line.match(
+      /capture: \d+ - definition\.(\w+), start: \((\d+), \d+\), end: \((\d+), \d+\)/,
+    );
+    if (defMatch && currentName) {
+      currentKind = captureToKind(defMatch[1]!);
+      const defStart = Number.parseInt(defMatch[2]!, 10) + 1;
+      endLine = Number.parseInt(defMatch[3]!, 10) + 1;
+
+      symbols.push({
+        name: currentName,
+        kind: currentKind,
+        startLine: defStart,
+        endLine,
+        filePath,
+        language,
+      });
+      currentName = '';
+    }
+  }
+
+  return symbols;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a single file and extract code symbols.
+ *
+ * @param filePath - Absolute or relative path to source file
+ * @param projectRoot - Project root for relative path computation
+ * @returns Parse result with symbols and any errors
+ */
+export function parseFile(filePath: string, projectRoot?: string): ParseResult {
+  const root = projectRoot ?? process.cwd();
+  const relPath = relative(root, filePath);
+  const language = detectLanguage(filePath);
+
+  if (!language) {
+    return {
+      filePath: relPath,
+      language: 'unknown',
+      symbols: [],
+      errors: ['Unsupported language'],
+    };
+  }
+
+  const queryKey = queryKeyForLanguage(language);
+  const pattern = QUERY_PATTERNS[queryKey];
+  if (!pattern) {
+    return {
+      filePath: relPath,
+      language,
+      symbols: [],
+      errors: [`No query pattern for ${language}`],
+    };
+  }
+
+  const tmpDir = mkdtempSync(join(tmpdir(), 'cleo-ts-'));
+  const queryFile = join(tmpDir, 'query.scm');
+
+  try {
+    writeFileSync(queryFile, pattern);
+    const bin = resolveTreeSitterBin();
+
+    const output = execFileSync(bin, ['query', queryFile, filePath], {
+      encoding: 'utf-8',
+      timeout: 30000,
+      maxBuffer: 10 * 1024 * 1024, // 10MB
+    });
+
+    const symbols = parseQueryOutput(output, relPath, language);
+    return { filePath: relPath, language, symbols, errors: [] };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { filePath: relPath, language, symbols: [], errors: [msg] };
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Batch-parse multiple files, grouping by language for efficiency.
+ *
+ * Files with the same language share a single query pattern file
+ * but each file is parsed individually (tree-sitter CLI limitation).
+ *
+ * @param filePaths - Array of file paths to parse
+ * @param projectRoot - Project root for relative path computation
+ * @returns Aggregated results with per-file breakdowns
+ */
+export function batchParse(filePaths: string[], projectRoot?: string): BatchParseResult {
+  const root = projectRoot ?? process.cwd();
+  const results: ParseResult[] = [];
+  const skipped: string[] = [];
+
+  // Group files by language
+  const byLanguage = new Map<string, string[]>();
+  for (const fp of filePaths) {
+    const lang = detectLanguage(fp);
+    if (!lang) {
+      skipped.push(relative(root, fp));
+      continue;
+    }
+    const key = queryKeyForLanguage(lang);
+    const group = byLanguage.get(key) ?? [];
+    group.push(fp);
+    byLanguage.set(key, group);
+  }
+
+  // Parse each group
+  for (const [_queryKey, files] of byLanguage) {
+    for (const fp of files) {
+      results.push(parseFile(fp, root));
+    }
+  }
+
+  const totalSymbols = results.reduce((sum, r) => sum + r.symbols.length, 0);
+  return { results, skipped, totalSymbols };
+}

package/src/code/search.ts

@@ -0,0 +1,173 @@
+/**
+ * smart_search — cross-codebase symbol search via tree-sitter.
+ *
+ * Walks a directory tree, batch-parses code files by language, and
+ * matches symbols against a query string with relevance scoring.
+ *
+ * @task T152
+ */
+
+import { readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import type { CodeSymbol } from '@cleocode/contracts';
+import { detectLanguage, type TreeSitterLanguage } from '../lib/tree-sitter-languages.js';
+import { batchParse } from './parser.js';
+
+/** A search result with relevance score. */
+export interface SmartSearchResult {
+  /** The matched symbol. */
+  symbol: CodeSymbol;
+  /** Relevance score (higher = better match). */
+  score: number;
+  /** How the query matched (exact, substring, fuzzy, path). */
+  matchType: 'exact' | 'substring' | 'fuzzy' | 'path';
+}
+
+/** Options for smart_search. */
+export interface SmartSearchOptions {
+  /** Maximum results to return (default: 20). */
+  maxResults?: number;
+  /** Glob-like file pattern filter (e.g. "*.ts", "src/**"). */
+  filePattern?: string;
+  /** Restrict to specific language. */
+  language?: TreeSitterLanguage;
+  /** Root directory to search (default: cwd). */
+  rootDir?: string;
+}
+
+/**
+ * Walk a directory tree and collect source files.
+ *
+ * Respects common ignore patterns (node_modules, dist, .git, etc.)
+ * and optionally filters by file pattern and language.
+ */
+function collectSourceFiles(dir: string, options: SmartSearchOptions): string[] {
+  const IGNORE_DIRS = new Set([
+    'node_modules',
+    'dist',
+    '.git',
+    '.cleo',
+    'target',
+    '__pycache__',
+    '.next',
+    '.nuxt',
+    'build',
+    'coverage',
+    '.turbo',
+    '.cache',
+  ]);
+
+  const files: string[] = [];
+
+  function walk(currentDir: string): void {
+    let entries: { isDirectory(): boolean; isFile(): boolean; name: string }[];
+    try {
+      entries = readdirSync(currentDir, { withFileTypes: true, encoding: 'utf-8' }) as {
+        isDirectory(): boolean;
+        isFile(): boolean;
+        name: string;
+      }[];
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (!IGNORE_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+          walk(join(currentDir, entry.name));
+        }
+      } else if (entry.isFile()) {
+        const fullPath = join(currentDir, entry.name);
+        const lang = detectLanguage(entry.name);
+        if (!lang) continue;
+
+        // Language filter
+        if (options.language && lang !== options.language) continue;
+
+        // File pattern filter (simple glob: *.ext or dir/**)
+        if (options.filePattern) {
+          const relPath = relative(dir, fullPath);
+          if (options.filePattern.startsWith('*.')) {
+            const ext = options.filePattern.slice(1);
+            if (!entry.name.endsWith(ext)) continue;
+          } else if (!relPath.includes(options.filePattern.replace('/**', ''))) {
+            continue;
+          }
+        }
+
+        files.push(fullPath);
+      }
+    }
+  }
+
+  walk(dir);
+  return files;
+}
+
+/**
+ * Score a symbol against a query string.
+ *
+ * Scoring: exact name match (10) > substring in name (5) >
+ * path match (3) > fuzzy (1).
+ */
+function scoreSymbol(
+  symbol: CodeSymbol,
+  query: string,
+): { score: number; matchType: SmartSearchResult['matchType'] } {
+  const q = query.toLowerCase();
+  const name = symbol.name.toLowerCase();
+  const path = symbol.filePath.toLowerCase();
+
+  // Exact name match
+  if (name === q) return { score: 10, matchType: 'exact' };
+
+  // Substring in name
+  if (name.includes(q)) return { score: 5, matchType: 'substring' };
+
+  // Path match
+  if (path.includes(q)) return { score: 3, matchType: 'path' };
+
+  // Fuzzy: all query chars appear in order in the name
+  let qi = 0;
+  for (let ni = 0; ni < name.length && qi < q.length; ni++) {
+    if (name[ni] === q[qi]) qi++;
+  }
+  if (qi === q.length) return { score: 1, matchType: 'fuzzy' };
+
+  return { score: 0, matchType: 'fuzzy' };
+}
+
+/**
+ * Search for symbols across a codebase.
+ *
+ * Walks the directory tree, batch-parses source files, and returns
+ * symbols matching the query ranked by relevance score.
+ *
+ * @param query - Search string to match against symbol names and paths
+ * @param options - Search options (maxResults, filePattern, language, rootDir)
+ * @returns Ranked array of search results
+ */
+export function smartSearch(query: string, options: SmartSearchOptions = {}): SmartSearchResult[] {
+  const rootDir = options.rootDir ?? process.cwd();
+  const maxResults = options.maxResults ?? 20;
+
+  // Collect and parse source files
+  const files = collectSourceFiles(rootDir, options);
+  const parsed = batchParse(files, rootDir);
+
+  // Score all symbols
+  const results: SmartSearchResult[] = [];
+  for (const fileResult of parsed.results) {
+    for (const symbol of fileResult.symbols) {
+      const { score, matchType } = scoreSymbol(symbol, query);
+      if (score > 0) {
+        results.push({ symbol, score, matchType });
+      }
+    }
+  }
+
+  // Sort by score descending, then by name
+  results.sort((a, b) => b.score - a.score || a.symbol.name.localeCompare(b.symbol.name));
+
+  return results.slice(0, maxResults);
+}