Code Analysis Tools
Relevant source files
The following files were used as context for generating this wiki page:
Code Analysis Tools within this project constitute a multi-layered system designed to provide deep structural understanding, pattern recognition, and semantic mapping of codebases. These tools enable AI agents to perform autonomous "Discovery + Analysis" phases, which are essential for generating accurate work plans, performing safe refactoring, and maintaining architectural consistency.
The system orchestrates low-level utilities (such as LSP, AST-grep, and Bash) with specialized high-level agents like explore and librarian. This combination allows for both local codebase introspection and external reference lookup, ensuring that implementation decisions are grounded in existing patterns and official documentation.
Core Analysis Components
The project utilizes a tiered approach to code analysis, ranging from raw text search to advanced language-aware semantic queries.
1. Language Server Protocol (LSP) Tools
LSP tools provide precise, compiler-verified information about symbols, definitions, and references. These are considered the "ground truth" for semantic analysis.
- LspGotoDefinition: Locates the primary definition of a symbol.
- LspFindReferences: Maps all usages of a symbol across the workspace to assess the impact of changes.
- LspDocumentSymbols: Provides a hierarchical outline of a specific file.
- LspWorkspaceSymbols: Enables workspace-wide search for specific classes, interfaces, or functions.
- LspDiagnostics: Retrieves current errors and warnings to establish a baseline before modifications.
Sources: src/features/builtin-commands/templates/refactor.ts:133-146, src/features/builtin-commands/templates/init-deep.ts:109-122
2. AST-Grep (Structural Analysis)
AST-grep is used for structural pattern matching, allowing agents to find code based on its syntax tree rather than just text strings.
- ast_grep_search: Identifies structural patterns (e.g., "all functions with three arguments").
- ast_grep_replace: Executes dry-run or actual structural refactoring based on defined rewrites.
Sources: src/features/builtin-commands/templates/refactor.ts:150-166
3. Bash & Grep (Structural & Textual)
Bash-based tools are used for high-speed directory analysis and simple string matching.
- Directory Depth Analysis: Calculates project complexity based on file counts and nesting levels.
- Grep: Used for rapid text-based pattern discovery across specific file extensions.
Sources: src/features/builtin-commands/templates/init-deep.ts:88-100
Analysis Orchestration Workflow
The project follows a specific workflow for codebase exploration, often triggered by commands like /init-deep or /refactor.
This diagram illustrates the concurrent execution of different analysis tools to minimize latency during the discovery phase.
Sources: src/features/builtin-commands/templates/init-deep.ts:21-36
Complexity Scoring Matrix
During the analysis of directories, a scoring matrix is applied to determine which areas require detailed documentation or specialized attention.
| Factor | Weight | High Threshold | Source |
|---|---|---|---|
| File count | 3x | >20 | bash |
| Subdir count | 2x | >5 | bash |
| Symbol density | 2x | >30 symbols | LSP |
| Reference centrality | 3x | >20 refs | LSP |
| Module boundary | 2x | index.ts / __init__.py | bash |
Sources: src/features/builtin-commands/templates/init-deep.ts:134-145
Specialized Analysis Agents
High-level analysis is delegated to specialized subagents that use the core tools described above.
Explore Agent (Contextual Grep)
The explore agent acts as a peer tool for "Contextual Grep." It is used for multi-angle search, discovering cross-layer patterns, and exploring unfamiliar module structures. It is typically fired in parallel to minimize blocking the main session.
Usage Examples:
- Finding similar implementations to maintain consistency.
- Identifying architectural patterns and module organization.
Sources: src/agents/sisyphus.ts:250-258, src/features/builtin-commands/templates/refactor.ts:105-129
Librarian Agent (Reference Grep)
The librarian agent focuses on external resources. It searches official documentation, Open Source Software (OSS) examples, and library internals to provide context that does not exist within the local codebase.
Sources: sisyphus-prompt.md:120-135
Git History Analysis
For tasks involving version control, specialized history analysis is performed to detect project-specific conventions.
The git-master skill performs parallel context gathering from the current state and history to determine the appropriate commit strategy.
Sources: src/features/builtin-skills/skills/git-master.ts:71-87, src/features/builtin-skills/skills/git-master.ts:101-135
Refactoring Discovery Strategy
When a refactor command is issued, the system follows an "Intent Gate" and mandatory exploration phase to build a "Definitive Codemap."
Verification Strategy Analysis
A critical part of the analysis is the "Test Assessment," which determines the risk level of the operation.
| Coverage Level | Strategy |
|---|---|
| HIGH (>80%) | Run existing tests after each step |
| MEDIUM (50-80%) | Run tests + add safety assertions |
| LOW (<50%) | Propose adding tests first |
| NONE | Block aggressive refactoring |
Sources: src/features/builtin-commands/templates/refactor.ts:245-256
Conclusion
Code Analysis Tools in this repository are not merely utility functions but are integrated into a sophisticated orchestration framework. By combining the precision of LSP with the structural pattern matching of AST-grep and the semantic reasoning of specialized agents, the system ensures that any codebase modification is preceded by a comprehensive understanding of its structure, dependencies, and history.