ast-index Documentation

The changed command provides a summary of files changed relative to a base (Git or Arc). It is cache-independent and does not require an index rebuild.

Key Features:

• Automatic Base Detection: Without --base, it tries origin/HEAD, origin/main, origin/master, main, master, or trunk (for Arc).
• Structured Output: Use --format json for machine-readable results.
• Scope: The current working directory defines the scope; paths are relative to the repository root.

Warning: changed reports file statuses (Added, Modified, etc.), not specific code/symbol changes. Use raw git diff or arc diff for patch hunks.

# Compare against a specific base
ast-index changed --base origin/develop

# Get JSON output for scripts
ast-index --format json changed --base origin/develop --timeout-ms 30000

# Verbose output (shows root, scope, and timing)
ast-index changed --verbose

When indexing WSDL (.wsdl) and XSD (.xsd) files, ast-index maps XML elements to specific symbol kinds. This allows you to search for services, operations, and types using the appropriate command types.

### WSDL Elements
| WSDL Element | Symbol Kind | Example |
|--------------|-------------|---------|
| `<service name="...">` | Interface | `UserService` → Interface |
| `<portType name="...">` | Interface | `UserPortType` → Interface |
| `<operation name="...">` | Function | `getUser` → Function |
| `<binding name="...">` | Class | `UserBinding` → Class |
| `<message name="...">` | Class | `GetUserRequest` → Class |
| `<import location="...">` | Import | `types.xsd` → Import |

### XSD Elements
| XSD Element | Symbol Kind | Example |
|-------------|-------------|---------|
| `<complexType name="...">` | Class | `UserType` → Class |
| `<simpleType name="...">` | Class | `StatusType` → Class |
| `<element name="...">` | Property | `userId` → Property |
| `<attribute name="...">` | Property | `version` → Property |
| `<import schemaLocation="...">` | Import | `common.xsd` → Import |

The .claude/rules/ast-index.md file is a critical configuration that guides how an AI agent interacts with your code. It should contain instructions to:

1. Always use ast-index first for code search tasks.
2. Avoid duplicating results from grep if ast-index has already provided the answer.
3. Only use grep or standard search when ast-index returns no results, when searching for regex patterns, searching for string literals inside code, or searching within comments.

# ast-index Rules

## Mandatory Search Rules

1. **ALWAYS use ast-index FIRST** for any code search task
2. **NEVER duplicate results** — if ast-index found usages/implementations, that IS the complete answer
3. **DO NOT run grep "for completeness"** after ast-index returns results
4. **Use grep/Search ONLY when:**
   - ast-index returns empty results
   - Searching for regex patterns (ast-index uses literal match)
   - Searching for string literals inside code (`"some text"`)
   - Searching in comments content

The indexer recognizes patterns specific to popular web frameworks:

React

• Functional Components: Indexed as [class] (e.g., const UserCard: FC<Props> = ... becomes UserCard [class]).
• Hooks: Indexed as [function] (e.g., function useUser() ... becomes useUser [function]).
• forwardRef: Components using forwardRef are indexed as [class].

Vue 3 (Composition API)

• Extracts the <script> section.
• Indexes interface Props as [interface].
• Indexes const declarations (like ref or computed) as [constant].

Svelte

• Indexes export let as [property] (exported props).
• Indexes standard functions in <script> as [function].

NestJS & Angular

• Decorators: Indexed as [annotation] (e.g., @Controller, @Injectable, @Component, @Module, @Get).
• Classes: Indexed as [class] (e.g., UserController, UserComponent).
• Methods: Indexed as [function] (e.g., findOne, ngOnInit).

The database consists of 15 base tables and one FTS5 virtual table (symbols_fts).

Core Tables

• files: Stores file identity using (root_path, path). path is relative to the root, and root_path is the absolute normalized path. Freshness is tracked via mtime and size.
• symbols: Contains code declarations. Key columns include name, qualified_name, kind, line, and file_id.
• modules: Represents logical modules/packages.
• refs: Stores code references. Note that refs.name is a string and does not point to a specific symbols.id to remain language-agnostic.
• inheritance: Maps child symbols to a parent_name (string-based).
• subtrees: Manages attached project roots, mapping original_path to a canonical_path used in files.root_path.

Platform-Specific Tables

• Android: resources, resource_usages, and xml_usages.
• iOS: ios_assets, ios_asset_usages, and storyboard_usages.

Metadata

The metadata table is a string-to-string store. Common keys include:

• project_root: Used for cache ownership and migrations.
• last_update_at: Unix timestamp (ms) of the last file-index update.
• no_ignore: 1 if ignored files were included.
• bypass_size_check: Persistent opt-in for bypassing file size caps.