@cleocode/core 2026.4.30 → 2026.4.31

package/src/code/parser.ts

@@ -1,17 +1,16 @@
 /**
- * Tree-sitter AST parser — query execution engine for code analysis.
+ * Tree-sitter AST parser — native Node bindings query execution engine.
  *
- * 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.
+ * Uses the tree-sitter native Node module to parse source files in-process,
+ * executing S-expression query patterns directly against the AST without
+ * spawning a subprocess or writing temp files.
  *
- * @task T149
+ * @task T509
  */
 
-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 { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { relative } from 'node:path';
 import type {
   BatchParseResult,
   CodeSymbol,
@@ -21,51 +20,187 @@ import type {
 import { detectLanguage, type TreeSitterLanguage } from '../lib/tree-sitter-languages.js';
 
 // ---------------------------------------------------------------------------
-// Tree-sitter CLI resolution
+// Native module loading (CommonJS interop via createRequire)
 // ---------------------------------------------------------------------------
 
-/** Whether tree-sitter is available on this system. */
-let _treeSitterAvailable: boolean | null = null;
+/** ESM-safe require for loading native tree-sitter addons. */
+const _require = createRequire(import.meta.url);
 
-/** Check if tree-sitter CLI is available and executable. Cached after first call. */
-export function isTreeSitterAvailable(): boolean {
-  if (_treeSitterAvailable !== null) return _treeSitterAvailable;
+/**
+ * Load a native module via require, returning null on failure.
+ *
+ * @param id - Module specifier (e.g. "tree-sitter" or "tree-sitter-rust")
+ */
+function tryRequire(id: string): unknown {
   try {
-    const bin = resolveTreeSitterBin();
-    // Verify the binary actually runs (broken symlinks pass existsSync)
-    execFileSync(bin, ['--version'], { timeout: 5000, stdio: 'pipe' });
-    _treeSitterAvailable = true;
+    return _require(id) as unknown;
   } catch {
-    _treeSitterAvailable = false;
+    return null;
   }
-  return _treeSitterAvailable;
 }
 
-/** Resolve the tree-sitter CLI binary from node_modules. */
-function resolveTreeSitterBin(): string {
-  // Also check platform-specific binary extension for Windows
-  const ext = process.platform === 'win32' ? '.exe' : '';
-  const binName = `tree-sitter${ext}`;
-  const candidates = [
-    join(process.cwd(), 'packages', 'core', 'node_modules', '.bin', binName),
-    join(process.cwd(), 'node_modules', '.bin', binName),
-    // npm global install paths
-    join(process.cwd(), 'node_modules', 'tree-sitter-cli', binName),
-  ];
-  // Also try without extension (npm .cmd shim on Windows)
-  if (ext) {
-    candidates.push(
-      join(process.cwd(), 'packages', 'core', 'node_modules', '.bin', 'tree-sitter'),
-      join(process.cwd(), 'node_modules', '.bin', 'tree-sitter'),
+// ---------------------------------------------------------------------------
+// Parser singleton — lazy-loaded on first use
+// ---------------------------------------------------------------------------
+
+/** The Parser constructor from the tree-sitter native module. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ParserConstructor = new () => NativeParser;
+
+/** Minimal shape of the native tree-sitter Parser instance. */
+interface NativeParser {
+  setLanguage(lang: unknown): void;
+  parse(source: string): NativeTree;
+}
+
+/** Minimal shape of the parsed Tree. */
+interface NativeTree {
+  rootNode: SyntaxNode;
+}
+
+/** Minimal shape of a tree-sitter SyntaxNode. */
+interface SyntaxNode {
+  type: string;
+  text: string;
+  startPosition: { row: number; column: number };
+  endPosition: { row: number; column: number };
+  children: SyntaxNode[];
+  namedChildren: SyntaxNode[];
+  childForFieldName(fieldName: string): SyntaxNode | null;
+}
+
+/** Minimal shape of a Query capture result. */
+interface QueryCapture {
+  name: string;
+  node: SyntaxNode;
+}
+
+/** Minimal shape of the native Query class. */
+interface NativeQueryConstructor {
+  new (language: unknown, pattern: string): NativeQuery;
+}
+
+/** Minimal shape of a constructed Query instance. */
+interface NativeQuery {
+  captures(node: SyntaxNode): QueryCapture[];
+}
+
+/** The native Parser constructor (null if module unavailable). */
+let _ParserClass: ParserConstructor | null = null;
+
+/** The native Query constructor (null if module unavailable). */
+let _QueryClass: NativeQueryConstructor | null = null;
+
+/** Singleton parser instance, reused across calls. */
+let _parserInstance: NativeParser | null = null;
+
+/** Whether availability has been probed. */
+let _availabilityChecked = false;
+
+/** Whether the native tree-sitter module loaded successfully. */
+let _available = false;
+
+/**
+ * Probe and cache tree-sitter native module availability.
+ *
+ * Loads the tree-sitter native module once and caches the result.
+ * Subsequent calls return the cached value with no I/O.
+ *
+ * @returns True if the native module loaded successfully
+ */
+export function isTreeSitterAvailable(): boolean {
+  if (_availabilityChecked) return _available;
+  _availabilityChecked = true;
+
+  const mod = tryRequire('tree-sitter');
+  if (mod === null) {
+    _available = false;
+    return false;
+  }
+
+  // tree-sitter exports the Parser class directly
+  _ParserClass = mod as ParserConstructor;
+
+  // The Query class lives on the Parser namespace
+  const parserWithQuery = mod as { Query?: NativeQueryConstructor };
+  _QueryClass = parserWithQuery.Query ?? null;
+
+  _available = _ParserClass !== null && _QueryClass !== null;
+  return _available;
+}
+
+/**
+ * Get (or create) the singleton Parser instance.
+ *
+ * @throws {Error} If tree-sitter native module is not available
+ */
+function getParser(): NativeParser {
+  if (_parserInstance) return _parserInstance;
+  if (!isTreeSitterAvailable() || _ParserClass === null) {
+    throw new Error(
+      'tree-sitter native module not available. ' +
+        'Run: pnpm install (tree-sitter is a bundled dependency)',
     );
   }
-  for (const p of candidates) {
-    if (existsSync(p)) return p;
+  _parserInstance = new _ParserClass();
+  return _parserInstance;
+}
+
+// ---------------------------------------------------------------------------
+// Grammar registry — language identifier → loaded grammar object
+// ---------------------------------------------------------------------------
+
+/** Cache of loaded grammar objects, keyed by language identifier. */
+const _grammarCache = new Map<string, unknown>();
+
+/**
+ * Describe how each grammar package exports its language object.
+ *
+ * Most packages export a single object via `module.exports = language`.
+ * tree-sitter-typescript exports `{ typescript, tsx }`.
+ * tree-sitter-php (not used here) exports `{ php, php_only }`.
+ */
+interface GrammarSpec {
+  /** npm package name. */
+  pkg: string;
+  /** Property to read from the module exports (undefined = use exports directly). */
+  prop?: string;
+}
+
+const GRAMMAR_SPECS: Record<string, GrammarSpec> = {
+  typescript: { pkg: 'tree-sitter-typescript', prop: 'typescript' },
+  tsx: { pkg: 'tree-sitter-typescript', prop: 'tsx' },
+  javascript: { pkg: 'tree-sitter-javascript' },
+  python: { pkg: 'tree-sitter-python' },
+  go: { pkg: 'tree-sitter-go' },
+  rust: { pkg: 'tree-sitter-rust' },
+  java: { pkg: 'tree-sitter-java' },
+  c: { pkg: 'tree-sitter-c' },
+  cpp: { pkg: 'tree-sitter-cpp' },
+  ruby: { pkg: 'tree-sitter-ruby' },
+};
+
+/**
+ * Load and cache a grammar for the given language key.
+ *
+ * @param langKey - Language key matching a {@link GRAMMAR_SPECS} entry
+ * @returns The grammar object, or null if the package is not installed
+ */
+function loadGrammar(langKey: string): unknown {
+  if (_grammarCache.has(langKey)) return _grammarCache.get(langKey) ?? null;
+
+  const spec = GRAMMAR_SPECS[langKey];
+  if (!spec) return null;
+
+  const mod = tryRequire(spec.pkg);
+  if (mod === null) {
+    _grammarCache.set(langKey, null);
+    return null;
   }
-  throw new Error(
-    'tree-sitter CLI not found. Code analysis features (cleo code outline/search/unfold) ' +
-      'require tree-sitter. Install with: npm install tree-sitter-cli',
-  );
+
+  const grammar = spec.prop ? (mod as Record<string, unknown>)[spec.prop] : mod;
+  _grammarCache.set(langKey, grammar ?? null);
+  return grammar ?? null;
 }
 
 // ---------------------------------------------------------------------------
@@ -177,55 +312,95 @@ function captureToKind(capture: string): CodeSymbolKind {
 }
 
 // ---------------------------------------------------------------------------
-// Output parsing
+// Query cache — avoid re-compiling patterns for repeated parses
 // ---------------------------------------------------------------------------
 
+/** Cache of compiled Query objects, keyed by `<langKey>:<queryKey>`. */
+const _queryCache = new Map<string, NativeQuery>();
+
 /**
- * Parse tree-sitter query output into CodeSymbol objects.
+ * Get or compile a tree-sitter Query for the given language and pattern.
  *
- * 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)
- * ```
+ * @param grammar - The loaded grammar object (language)
+ * @param langKey - Key used for cache lookup
+ * @param pattern - S-expression query pattern string
+ * @returns Compiled Query instance, or null on compilation failure
  */
-function parseQueryOutput(output: string, filePath: string, language: string): CodeSymbol[] {
+function getQuery(grammar: unknown, langKey: string, pattern: string): NativeQuery | null {
+  const cacheKey = langKey;
+  if (_queryCache.has(cacheKey)) return _queryCache.get(cacheKey) ?? null;
+
+  if (_QueryClass === null) return null;
+
+  try {
+    const query = new _QueryClass(grammar, pattern);
+    _queryCache.set(cacheKey, query);
+    return query;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Capture processing — convert Query captures to CodeSymbol objects
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert tree-sitter query captures into CodeSymbol objects.
+ *
+ * The query patterns use two capture groups per match:
+ * - `@definition.<kind>` — the enclosing declaration node with line range
+ * - `@name` — the identifier node containing the symbol's text
+ *
+ * tree-sitter's Query.captures() returns captures in document order within
+ * each match. Because definition nodes enclose the name node, the definition
+ * capture appears first, then the name capture for the same match.
+ *
+ * We pair consecutive `definition.*` + `name` captures to build symbols.
+ *
+ * @param captures - Raw captures from Query.captures()
+ * @param filePath - Relative file path for the symbol record
+ * @param language - Language identifier for the symbol record
+ * @returns Extracted CodeSymbol objects
+ */
+function captureToSymbols(
+  captures: QueryCapture[],
+  filePath: string,
+  language: string,
+): CodeSymbol[] {
   const symbols: CodeSymbol[] = [];
-  const lines = output.split('\n');
 
-  let currentName = '';
-  let currentKind: CodeSymbolKind = 'function';
-  let endLine = 0;
+  let i = 0;
+  while (i < captures.length) {
+    const cap = captures[i]!;
 
-  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;
-    }
+    if (cap.name.startsWith('definition.')) {
+      const kindSuffix = cap.name.slice('definition.'.length);
+      const kind = captureToKind(kindSuffix);
+      // tree-sitter rows are 0-based; convert to 1-based line numbers
+      const startLine = cap.node.startPosition.row + 1;
+      const endLine = cap.node.endPosition.row + 1;
 
-    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 = '';
+      // The matching @name capture should immediately follow
+      const nameCap = captures[i + 1];
+      if (nameCap && nameCap.name === 'name') {
+        const nameText = nameCap.node.text;
+        if (nameText) {
+          symbols.push({
+            name: nameText,
+            kind,
+            startLine,
+            endLine,
+            filePath,
+            language,
+          });
+        }
+        i += 2;
+        continue;
+      }
     }
+
+    i++;
   }
 
   return symbols;
@@ -236,7 +411,12 @@ function parseQueryOutput(output: string, filePath: string, language: string): C
 // ---------------------------------------------------------------------------
 
 /**
- * Parse a single file and extract code symbols.
+ * Parse a single file and extract code symbols using the native tree-sitter
+ * Node module.
+ *
+ * Loads the grammar for the detected language, sets it on the shared parser
+ * singleton, runs the compiled Query against the AST, and converts captures
+ * into CodeSymbol objects.
  *
  * @param filePath - Absolute or relative path to source file
  * @param projectRoot - Project root for relative path computation
@@ -256,6 +436,18 @@ export function parseFile(filePath: string, projectRoot?: string): ParseResult {
     };
   }
 
+  if (!isTreeSitterAvailable()) {
+    return {
+      filePath: relPath,
+      language,
+      symbols: [],
+      errors: [
+        'tree-sitter native module not available. ' +
+          'Run: pnpm install (tree-sitter is a bundled dependency)',
+      ],
+    };
+  }
+
   const queryKey = queryKeyForLanguage(language);
   const pattern = QUERY_PATTERNS[queryKey];
   if (!pattern) {
@@ -267,34 +459,54 @@ export function parseFile(filePath: string, projectRoot?: string): ParseResult {
     };
   }
 
-  const tmpDir = mkdtempSync(join(tmpdir(), 'cleo-ts-'));
-  const queryFile = join(tmpDir, 'query.scm');
+  const grammar = loadGrammar(language);
+  if (!grammar) {
+    return {
+      filePath: relPath,
+      language,
+      symbols: [],
+      errors: [`Grammar package not installed for ${language}`],
+    };
+  }
+
+  let source: string;
+  try {
+    source = readFileSync(filePath, 'utf-8');
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { filePath: relPath, language, symbols: [], errors: [`Failed to read file: ${msg}`] };
+  }
 
   try {
-    writeFileSync(queryFile, pattern);
-    const bin = resolveTreeSitterBin();
+    const parser = getParser();
+    parser.setLanguage(grammar);
+    const tree = parser.parse(source);
 
-    const output = execFileSync(bin, ['query', queryFile, filePath], {
-      encoding: 'utf-8',
-      timeout: 30000,
-      maxBuffer: 10 * 1024 * 1024, // 10MB
-    });
+    const query = getQuery(grammar, queryKey, pattern);
+    if (!query) {
+      return {
+        filePath: relPath,
+        language,
+        symbols: [],
+        errors: [`Failed to compile query for ${language}`],
+      };
+    }
 
-    const symbols = parseQueryOutput(output, relPath, language);
+    const captures = query.captures(tree.rootNode);
+    const symbols = captureToSymbols(captures, 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).
+ * Files are parsed individually; the parser singleton is reused across all
+ * files. Grammar loading is cached so each grammar is loaded at most once
+ * per process.
  *
  * @param filePaths - Array of file paths to parse
  * @param projectRoot - Project root for relative path computation
@@ -305,25 +517,13 @@ export function batchParse(filePaths: string[], projectRoot?: string): BatchPars
   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));
-    }
+    results.push(parseFile(fp, root));
   }
 
   const totalSymbols = results.reduce((sum, r) => sum + r.symbols.length, 0);

package/src/hooks/handlers/__tests__/hook-automation-e2e.test.ts

@@ -30,6 +30,11 @@ vi.mock('../memory-bridge-refresh.js', () => ({
   maybeRefreshMemoryBridge: vi.fn(),
 }));
 
+// T527: Mock session-grade to prevent real DB access in handleSessionEnd
+vi.mock('../../../sessions/session-grade.js', () => ({
+  gradeSession: vi.fn().mockResolvedValue(undefined),
+}));
+
 // ---------------------------------------------------------------------------
 // Handler imports — after mock setup
 // ---------------------------------------------------------------------------
@@ -99,10 +104,10 @@ describe('hook automation E2E', () => {
   });
 
   // -------------------------------------------------------------------------
-  // 1. SessionStart dispatches and brain handler fires (bridge refresh)
+  // 1. SessionStart — refreshes memory bridge (no observeBrain write per T527)
   // -------------------------------------------------------------------------
   describe('SessionStart', () => {
-    it('fires brain observation on session start', async () => {
+    it('does not write a brain observation on session start (T527)', async () => {
       await handleSessionStart(PROJECT_ROOT, {
         timestamp: TIMESTAMP,
         sessionId: 'ses-e2e-1',
@@ -111,16 +116,8 @@ describe('hook automation E2E', () => {
         agent: 'claude-sonnet',
       });
 
-      expect(observeBrainMock).toHaveBeenCalledTimes(1);
-      expect(observeBrainMock).toHaveBeenCalledWith(
-        PROJECT_ROOT,
-        expect.objectContaining({
-          title: 'Session start: E2E Session',
-          type: 'discovery',
-          sourceSessionId: 'ses-e2e-1',
-          sourceType: 'agent',
-        }),
-      );
+      // T527: session start no longer writes a duplicate brain observation
+      expect(observeBrainMock).not.toHaveBeenCalled();
     });
 
     it('triggers memory bridge refresh after session start', async () => {
@@ -136,10 +133,10 @@ describe('hook automation E2E', () => {
   });
 
   // -------------------------------------------------------------------------
-  // 2. SessionEnd dispatches and brain handler fires (summarization + bridge)
+  // 2. SessionEnd — refreshes memory bridge (no observeBrain write per T527)
   // -------------------------------------------------------------------------
   describe('SessionEnd', () => {
-    it('fires brain observation on session end', async () => {
+    it('does not write a brain observation on session end (T527)', async () => {
       await handleSessionEnd(PROJECT_ROOT, {
         timestamp: TIMESTAMP,
         sessionId: 'ses-e2e-2',
@@ -147,29 +144,8 @@ describe('hook automation E2E', () => {
         tasksCompleted: ['T166', 'T168'],
       });
 
-      expect(observeBrainMock).toHaveBeenCalledTimes(1);
-      expect(observeBrainMock).toHaveBeenCalledWith(
-        PROJECT_ROOT,
-        expect.objectContaining({
-          title: 'Session end: ses-e2e-2',
-          type: 'change',
-          sourceSessionId: 'ses-e2e-2',
-          sourceType: 'agent',
-        }),
-      );
-    });
-
-    it('includes task list in session end observation text', async () => {
-      await handleSessionEnd(PROJECT_ROOT, {
-        timestamp: TIMESTAMP,
-        sessionId: 'ses-e2e-tasks',
-        duration: 600,
-        tasksCompleted: ['T100', 'T101'],
-      });
-
-      const callText = observeBrainMock.mock.calls[0][1].text as string;
-      expect(callText).toContain('T100');
-      expect(callText).toContain('T101');
+      // T527: session end no longer writes a duplicate brain observation
+      expect(observeBrainMock).not.toHaveBeenCalled();
     });
 
     it('triggers memory bridge refresh after session end', async () => {
@@ -536,8 +512,8 @@ describe('hook automation E2E', () => {
   // 11. Dedup: PostToolUse doesn't double-capture what session-hooks handles
   // -------------------------------------------------------------------------
   describe('dedup (no double-capture)', () => {
-    it('PostToolUse and SessionEnd are separate calls — no overlap', async () => {
-      // Simulate a session ending after a task completes
+    it('PostToolUse fires brain observation; SessionEnd does not (T527)', async () => {
+      // Simulate a task completing then a session ending
       await handleToolComplete(PROJECT_ROOT, {
         timestamp: TIMESTAMP,
         taskId: 'T168',
@@ -545,6 +521,8 @@ describe('hook automation E2E', () => {
         status: 'done',
       });
 
+      // PostToolUse (handleToolComplete) should have fired once
+      expect(observeBrainMock).toHaveBeenCalledTimes(1);
       observeBrainMock.mockClear();
 
       await handleSessionEnd(PROJECT_ROOT, {
@@ -554,12 +532,8 @@ describe('hook automation E2E', () => {
         tasksCompleted: ['T168'],
       });
 
-      // Each handler fires exactly once — no double-capture for the same event
-      expect(observeBrainMock).toHaveBeenCalledTimes(1);
-      expect(observeBrainMock).toHaveBeenCalledWith(
-        PROJECT_ROOT,
-        expect.objectContaining({ title: 'Session end: ses-dedup' }),
-      );
+      // T527: session end no longer writes a duplicate brain observation
+      expect(observeBrainMock).not.toHaveBeenCalled();
     });
 
     it('work-capture does not fire when captureWork is disabled (default)', async () => {