tsa-structure

name: tsa-structure version: 2.0.0 description: | Structural analysis of one file — classes, methods, exports, common patterns, semantic classification of a diff. Returns the file's shape without reading the file body.

Use when:

• "What classes and methods does X file have"
• "Show me a table / outline of "
• "Run query: find all decorated functions in file X"
• "Is this diff a refactor or a behavior change" (semantic classification)
• "Find patterns like singleton / factory in this code"

Replaces: reading the whole file (~20k tokens for big files) with structural views (200-1000 tokens). allowed-tools: - mcp__tree-sitter-analyzer__structure - mcp__tree-sitter-analyzer__search - mcp__tree-sitter-analyzer__health - mcp__tree-sitter-analyzer__edit - Bash - Read

tsa-structure — File shape without the file body

Tool routing

Procedure

File outline (most common)

structure action=analyze file_path="tree_sitter_analyzer/health_scorer.py"
# returns: {classes: [...], functions: [...], imports: [...]}

For a markdown-formatted table:

uv run tree-sitter-analyzer <file> --table full

Custom tree-sitter query

When you need something the built-in tools don't surface:

search action=query file_path="..." query_key="class"
# OR
search action=query file_path="..." query_string="(decorated_definition) @decorated"

--list-queries (CLI) shows all built-in queries available per language.

Diff classification

edit action=classify file_path="..." before_hash="abc" after_hash="def"
# returns: {classification: "refactor|feature|bugfix|test|docs|chore", confidence: 0.92}

Useful for PR descriptions and CHANGELOG categorization.

Pattern detection

health action=patterns file_path="..." patterns=["singleton", "factory", "observer"]

CLI equivalents

uv run tree-sitter-analyzer <file> --table full           # outline
uv run tree-sitter-analyzer <file> --query-key class      # built-in query
uv run tree-sitter-analyzer <file> --query-string "(...)" # custom query
uv run tree-sitter-analyzer <file> --code-patterns
uv run tree-sitter-analyzer --semantic-classify           # edit action=classify

Anti-patterns

• DON'T read the whole file just to find "what classes are in it" — use the structure tool
• DON'T write a custom tree-sitter query when structure action=analyze covers it
• DON'T use edit action=classify on huge multi-purpose commits — split them first