mapping-codebases · diff
v0.8.0 to v0.9.0
30 added, 90 removed. Audit A to A.
---
name: mapping-codebases
- description: Generate navigable code maps for unfamiliar codebases. Extracts exports/imports via AST (tree-sitter) to create _MAP.md files per directory showing classes, functions, methods with signatures and line numbers. Use when exploring repositories, understanding project structure, analyzing unfamiliar code, or before modifications. Triggers on "map this codebase", "explore repo", "understand structure", "what does this project contain", or when starting work on an unfamiliar repository.
+ description: DEPRECATED — superseded by tree-sitting. This skill generated persistent _MAP.md files; tree-sitting does the same AST extraction at runtime (~700ms for 250 files) with no artifact to write, commit, or keep in sync. Use tree-sitting for "map this codebase", "explore repo", "understand structure", or any code navigation task. The final working version is archived at release mapping-codebases-v0.8.0.
metadata:
- version: 0.8.0
+ version: 0.9.0
---
- # Mapping Codebases
-
- Generate `_MAP.md` files providing hierarchical code structure views. Maps show function signatures, class methods, imports, and line numbers—enabling API understanding without reading full source files.
-
- ## Installation
-
- ```bash
- uv venv /home/claude/.venv
- uv pip install tree-sitter-language-pack --python /home/claude/.venv/bin/python
- ```
-
- **Bundled parsers**: The skill includes pre-built parsers for all 11 supported languages (Python, JavaScript, TypeScript, TSX, Go, Rust, Ruby, Java, C, HTML, Markdown) in `parsers/`. These are used automatically when the tree-sitter-language-pack runtime download fails (e.g., in proxied environments). No network access needed for supported languages.
-
- ## Generate Maps
-
- ```bash
- /home/claude/.venv/bin/python /mnt/skills/user/mapping-codebases/scripts/codemap.py /path/to/repo --skip tests,.github,locale
- ```
-
- Common skip patterns: `tests,.github,.husky,locale,migrations,__snapshots__,coverage,target,docs`
-
- ## Navigate Via Maps
-
- After generating maps, use them for navigation—read `_MAP.md` files, not source files directly.
-
- **Workflow:**
- 1. Read root `_MAP.md` for high-level structure
- 2. Follow subdirectory links to drill into relevant areas
- 3. Use function signatures and class methods to understand APIs
- 4. Read full source only when implementation details are needed
-
- **Maps reveal without reading source:**
- - All public functions with signatures: `def record_attempt(subtask_id, session, success, approach, error=None)` :200
- - Class structure with methods: `RecoveryManager` → `classify_failure()`, `is_circular_fix()`, `rollback_to_commit()`
- - Import relationships showing module dependencies
- - Line numbers for direct navigation
-
- **Anti-pattern:** Reading files directory-by-directory. Use maps to find what you need, then read only the specific file/lines required.
-
- ## Map Contents
+ # Mapping Codebases (deprecated)
- Each `_MAP.md` includes:
- - Directory statistics (file/subdirectory counts)
- - Subdirectory links for hierarchical navigation
- - Per-file: imports preview, symbol hierarchy with (C)lass/(m)ethod/(f)unction markers
- - Function signatures (Python, TypeScript, Go, Rust, Ruby, C)
- - Line ranges (`:42-85` format) showing symbol start and end lines
- - Doc comments — first-line summaries from docstrings, JSDoc, Doxygen, `///`, `#` comments
- - Constants and defines (`pub const`, `#define`, `export const`, Go `const`)
- - Enum variants as children of enum symbols (C)
- - Markdown files: h1/h2 heading ToC
- - Other files section (JSON, YAML, configs)
+ Use [tree-sitting](../tree-sitting/SKILL.md) instead.
- Example:
- ```markdown
- # services/
- *Files: 4 | Subdirectories: 0*
+ ## Why
- ## Files
+ This skill wrote `_MAP.md` files to disk — a persisted symbol inventory per
+ directory, generated once and read many times. That tradeoff made sense when
+ scanning was expensive. It isn't: tree-sitting parses a 250-file repo in about
+ 700ms and answers queries against the in-memory AST in under a millisecond.
- ### recovery.py
- > Imports: `json, subprocess, dataclasses, datetime, enum`...
- - **FailureType** (C) :24-38
- - **RecoveryManager** (C) :43-510 — Manages error recovery strategies.
- - **__init__** (m) `(self, spec_dir: Path, project_dir: Path)` :55-72
- - **classify_failure** (m) `(self, error: str, subtask_id: str)` :137-198 — Classify an error into a FailureType.
- - **record_attempt** (m) `(subtask_id, session, success, approach, error=None)` :200-240
- - **is_circular_fix** (m) `(self, subtask_id: str, current_approach: str)` :242-280
- - **get_recovery_hints** (m) `(self, subtask_id: str)` :495-510
- ```
+ A persisted map costs what a runtime scan does not — it goes stale, it needs
+ regenerating, it gets committed, and it must be excluded from every other tool
+ that walks the tree. Nothing was gained for that.
- ## Commands
+ ## Replacement commands
```bash
- # Generate maps
- /home/claude/.venv/bin/python /mnt/skills/user/mapping-codebases/scripts/codemap.py /path/to/repo
-
- # Skip directories
- /home/claude/.venv/bin/python /mnt/skills/user/mapping-codebases/scripts/codemap.py /path/to/repo --skip tests,.github
+ TREESIT=/mnt/skills/user/tree-sitting/scripts/treesit.py
- # Clean maps
- /home/claude/.venv/bin/python /mnt/skills/user/mapping-codebases/scripts/codemap.py /path/to/repo --clean
+ # Was: codemap.py /path/to/repo → root orientation
+ python3 $TREESIT /path/to/repo
- # Dry run
- /home/claude/.venv/bin/python /mnt/skills/user/mapping-codebases/scripts/codemap.py /path/to/repo -n
+ # Was: reading every _MAP.md in the tree → full inventory
+ python3 $TREESIT /path/to/repo --depth=-1 --detail=sparse
- # Verbose (debug output)
- /home/claude/.venv/bin/python /mnt/skills/user/mapping-codebases/scripts/codemap.py /path/to/repo -v
+ # Was: grepping _MAP.md for a symbol → direct lookup
+ python3 $TREESIT /path/to/repo --no-tree 'find:parse_input'
```
- Default skips: `.git`, `node_modules`, `__pycache__`, `.venv`, `venv`, `dist`, `build`, `.next`
-
- ## Supported Languages
-
- Python, JavaScript, TypeScript, TSX, Go, Rust, Ruby, Java, C, HTML, Markdown.
+ ## The archived version
- ## Limitations
+ The last working release is
+ [mapping-codebases-v0.8.0](https://github.com/oaustegard/claude-skills/releases/tag/mapping-codebases-v0.8.0)
+ (2026-03-31). It carries `scripts/codemap.py` and the eleven bundled
+ `parsers/*.so` grammars. The release is the snapshot; nothing in this directory
+ reproduces it.
- - Doc comments extracted as first-line summaries (not full descriptions)
- - Signatures: Python (full), TypeScript/Go/Rust/Ruby/C (params + return types), Java (not extracted)
- - Markdown: h1/h2 headings only
- - Private symbols (`_prefix`) excluded from top-level exports
+ Note that v0.8.0 ships a latent bug: `codemap.py:1216` calls an unimported
+ `get_parser()` inside a `try` swallowed by a bare `except Exception`, so HTML
+ inline-JavaScript symbol extraction silently returned nothing. It will not be
+ fixed.