feat: add symbols tool — file symbol tree with line numbers (#546)

* feat: add symbols tool — file symbol tree with line numbers

Add a new `symbols` command that lists all symbols (functions, structs,
classes, constants, enums, traits, impl blocks, type aliases, etc.) in
files as a table of contents with line numbers and nesting.

Rust implementation uses tree-sitter AST parsing with a new
`is_symbol_node()` trait method (broader than `is_acceptable_parent`)
and recursive descent for nested symbols (methods inside impl/class).

Full pipeline: CLI subcommand → Node.js wrapper → Vercel AI SDK tool →
agent registration (schema, system prompt, predefined prompts).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: address symbols tool review feedback

- Refactor processor.rs extract_all_symbols_from_file to delegate to
  symbols::extract_symbols, eliminating duplicate AST traversal logic
- Fix Vercel tool to return full result array instead of only first element
- Add escapeString for file paths in symbols.js matching extract.js pattern

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: address Visor review feedback on symbols tool

- Extract depth limit to named constant MAX_SYMBOL_DEPTH with docs
- Pre-allocate Vec capacity in collect_symbols and format_symbols_text
- Simplify Vercel tool return: always result[0] (schema takes single file)
- Return consistent JSON for empty results instead of plain string
- Improve symbolsSchema description to mention hierarchical nesting
- Include stdout preview in JSON parse error messages
- Clarify processor.rs legacy wrapper documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: buger

README.md

@@ -204,6 +204,7 @@ Direct access to Probe's search, query, and extract tools—without the agent la
 - `search` - Semantic code search with Elasticsearch-style queries
 - `query` - AST-based structural pattern matching
 - `extract` - Extract code blocks by line number or symbol name
+- `symbols` - List all symbols in a file (functions, classes, constants) with line numbers
 
 ---
 
@@ -287,6 +288,24 @@ probe extract src/main.rs:10-50
 go test | probe extract
 ```
 
+#### Symbols Command
+
+```bash
+probe symbols <FILES> [OPTIONS]
+```
+
+**Examples:**
+```bash
+# List symbols in a file
+probe symbols src/main.rs
+
+# JSON output for programmatic use
+probe symbols src/main.rs --format json
+
+# Multiple files
+probe symbols src/main.rs src/lib.rs
+```
+
 #### Query Command (AST Patterns)
 
 ```bash
@@ -333,7 +352,7 @@ console.log(agent.getTokenUsage());
 **Direct functions:**
 
 ```javascript
-import { search, extract, query } from '@probelabs/probe';
+import { search, extract, query, symbols } from '@probelabs/probe';
 
 // Semantic search
 const results = await search({
@@ -348,6 +367,11 @@ const code = await extract({
   format: 'markdown'
 });
 
+// List symbols in a file
+const fileSymbols = await symbols({
+  files: ['src/auth.ts']
+});
+
 // AST pattern query
 const matches = await query({
   pattern: 'async function $NAME($$$)',
@@ -461,6 +485,7 @@ Full documentation available at [probelabs.com/probe](https://probelabs.com/prob
 ### Probe CLI
 - [Search Command](./docs/probe-cli/search.md) - Elasticsearch-style semantic search
 - [Extract Command](./docs/probe-cli/extract.md) - Extract code blocks with full AST context
+- [Symbols Command](./docs/probe-cli/symbols.md) - List all symbols in files with line numbers
 - [Query Command](./docs/probe-cli/query.md) - AST-based structural pattern matching
 - [CLI Reference](./docs/probe-cli/cli-reference.md) - Complete command-line reference
 

docs/index.md

@@ -37,6 +37,7 @@ Pick a path based on what you need to do.
 |----------|-------------|
 | [Search](./probe-cli/search.md) | Semantic code search and query syntax |
 | [Extract](./probe-cli/extract.md) | Block extraction by line, range, symbol, or stdin/diff |
+| [Symbols](./probe-cli/symbols.md) | File symbol tree / table of contents with line numbers |
 | [Query](./probe-cli/query.md) | AST-grep structural search |
 | [CLI Reference](./probe-cli/cli-reference.md) | Command matrix and options |
 

docs/probe-agent/protocols/acp.md

@@ -150,7 +150,8 @@ Initialize the ACP connection.
       "tools": [
         { "name": "search", "kind": "search" },
         { "name": "query", "kind": "query" },
-        { "name": "extract", "kind": "extract" }
+        { "name": "extract", "kind": "extract" },
+        { "name": "symbols", "kind": "symbols" }
       ],
       "sessionManagement": true,
       "streaming": true,
@@ -458,6 +459,22 @@ Session state changed.
 }
 ```
 
+### symbols
+
+```json
+{
+  "name": "symbols",
+  "description": "List all symbols in a file with line numbers and nesting",
+  "kind": "symbols",
+  "inputSchema": {
+    "properties": {
+      "file": { "type": "string", "description": "Path to the file to list symbols from" }
+    },
+    "required": ["file"]
+  }
+}
+```
+
 ### delegate
 
 ```json

docs/probe-agent/protocols/mcp-integration.md

@@ -107,7 +107,7 @@ The Probe MCP server:
 - Implements the Model Context Protocol specification
 - Uses stdio for communication with AI editors
 - Automatically downloads and manages the Probe binary
-- Provides three main tools: search_code, query_code, and extract_code
+- Provides tools: search_code, query_code, extract_code, and symbols_code
 - Handles tool execution and error reporting
 
 ## Available Tools
@@ -216,6 +216,26 @@ Extract code blocks from files based on file paths and optional line numbers.
 }
 ```
 
+### symbols_code
+
+List all symbols (functions, classes, structs, constants, etc.) in a file. Returns a hierarchical tree with line numbers.
+
+#### Parameters
+
+| Parameter | Type | Description | Required |
+|-----------|------|-------------|----------|
+| `path` | string | Absolute path to the directory | Yes |
+| `file` | string | File path to list symbols from | Yes |
+
+#### Example
+
+```json
+{
+  "path": "/path/to/your/project",
+  "file": "src/main.rs"
+}
+```
+
 ## Integration with AI Assistants
 
 Once configured, you can ask your AI assistant to search your codebase with natural language queries. The AI will translate your request into appropriate Probe commands and display the results.

docs/probe-agent/protocols/mcp-server.md

@@ -195,6 +195,21 @@ The extract_code tool supports the following parameters:
 - `contextLines`: Number of context lines to include (default: 0)
 - `format`: Output format (default: "json")
 
+### symbols_code
+
+List all symbols in a file — functions, classes, structs, constants, etc. with line numbers and nesting.
+
+```json
+{
+  "path": "/path/to/your/project",
+  "file": "src/main.rs"
+}
+```
+
+The symbols_code tool supports the following parameters:
+- `path`: The base directory
+- `file`: Path to the file to list symbols from
+
 ## Using Probe with AI Assistants
 
 Once configured, you can ask your AI assistant to search your codebase with natural language queries. The AI will translate your request into appropriate Probe commands and display the results.

docs/probe-agent/protocols/mcp.md

@@ -47,6 +47,7 @@ When running as an MCP server, Probe exposes these tools:
 | `search` | Semantic code search with Elasticsearch syntax |
 | `query` | AST-based structural queries |
 | `extract` | Extract code blocks from files |
+| `symbols` | List all symbols in a file (TOC with line numbers) |
 | `listFiles` | List files in directory |
 | `searchFiles` | Find files by name pattern |
 
@@ -105,6 +106,24 @@ When running as an MCP server, Probe exposes these tools:
 }
 ```
 
+**symbols**
+```json
+{
+  "name": "symbols",
+  "description": "List all symbols in a file with line numbers",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "file": {
+        "type": "string",
+        "description": "Path to the file to list symbols from"
+      }
+    },
+    "required": ["file"]
+  }
+}
+```
+
 ---
 
 ## AI Editor Integration

docs/probe-agent/sdk/api-reference.md

@@ -359,6 +359,22 @@ const code = await extract(
 
 ---
 
+### symbols()
+
+List all symbols in a file — functions, classes, structs, constants, etc. with line numbers and nesting.
+
+```javascript
+const fileSymbols = await symbols({
+  files: ['src/auth.ts'],
+  cwd: './project',
+  allowTests: false
+}): Promise<FileSymbols[]>
+```
+
+**Returns** an array of `FileSymbols` objects, each containing a `file` path and `symbols` array with nested `SymbolNode` entries.
+
+---
+
 ### grep()
 
 Ripgrep-style search.
@@ -383,13 +399,14 @@ const results = await grep({
 ```javascript
 import { tools } from '@probelabs/probe';
 
-const { searchTool, queryTool, extractTool } = tools;
+const { searchTool, queryTool, extractTool, symbolsTool } = tools;
 
 // For Vercel AI SDK
 const toolSet = {
   search: searchTool({ defaultPath: './src' }),
   query: queryTool({ defaultPath: './src' }),
-  extract: extractTool({ defaultPath: './src' })
+  extract: extractTool({ defaultPath: './src' }),
+  symbols: symbolsTool({ defaultPath: './src' })
 };
 ```
 

docs/probe-agent/sdk/tools-reference.md

@@ -8,7 +8,7 @@ ProbeAgent provides a comprehensive set of tools that the AI can use to interact
 
 | Category | Tools | Description |
 |----------|-------|-------------|
-| **Search & Query** | search, query, extract | Find and retrieve code |
+| **Search & Query** | search, query, extract, symbols | Find and retrieve code |
 | **File Operations** | edit, create, listFiles, searchFiles | Modify and explore files |
 | **Execution** | bash | Run shell commands |
 | **Analysis** | analyze_all, readMedia | Comprehensive analysis |
@@ -202,6 +202,39 @@ Extract code blocks from files by location or symbol.
 
 ---
 
+### symbols
+
+List all symbols (functions, classes, structs, constants, etc.) in a file. Returns a hierarchical tree with line numbers — like a table of contents for code files.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file` | string | Yes | Path to the file to list symbols from |
+
+**Example AI Usage:**
+```xml
+<symbols>
+  <file>src/auth/login.ts</file>
+</symbols>
+```
+
+**Response format (JSON):**
+```json
+{
+  "file": "src/auth/login.ts",
+  "symbols": [
+    { "name": "loginUser", "kind": "function", "line": 5, "end_line": 25, "signature": "async function loginUser(email: string, password: string)" },
+    { "name": "AuthService", "kind": "class", "line": 27, "end_line": 80, "signature": "class AuthService", "children": [
+      { "name": "constructor", "kind": "method", "line": 28, "end_line": 35, "signature": "constructor()" },
+      { "name": "validate", "kind": "method", "line": 37, "end_line": 50, "signature": "validate(token: string): boolean" }
+    ]}
+  ]
+}
+```
+
+---
+
 ## File Operation Tools
 
 ### edit