codebase-mapping

Codebase Mapping

Maps repository structure and dependencies to enable targeted architectural analysis.

Quick Start

Generate a structural map:

python scripts/map_codebase.py /path/to/repo --output structure.json

Process

1. Clone or access the target repository
2. Generate file tree excluding noise (node_modules, pycache, .git, etc.)
3. Parse imports to build dependency graph
4. Identify entry points (main.py, index.ts, setup.py, pyproject.toml)
5. Detect boundaries - package structure and public APIs

Output Artifacts

The skill produces:

• file_tree.txt - Annotated directory structure
• dependencies.json - Import graph in adjacency list format
• entry_points.md - Identified entry points with descriptions
• module_map.md - Package boundaries and public interfaces

Key Patterns to Identify

Entry Point Detection

Look for these patterns:

• Python: if __name__ == "__main__", setup.py, pyproject.toml
• Node: package.json main/bin fields, index.js
• Frameworks: app.py (Flask), manage.py (Django), main.ts (Nest)

Dependency Classification

Classify imports as:

• External: Third-party packages (from package manager)
• Internal: Project modules (relative imports)
• Standard: Language standard library

Noise Exclusion

Always exclude:

node_modules/
__pycache__/
.git/
.venv/
venv/
dist/
build/
*.egg-info/
.mypy_cache/
.pytest_cache/

Integration with Other Skills

This skill provides the foundation for:

• data-substrate-analysis → Focus on types.py, models.py
• execution-engine-analysis → Focus on runner files
• control-loop-extraction → Focus on agent.py, loop files
• component-model-analysis → Focus on base classes

Example Output

## Repository: langchain

### Structure Summary
- 342 Python modules across 28 packages
- Primary entry: langchain/__init__.py
- Core packages: agents, chains, llms, tools

### Key Files for Analysis
- Types: langchain/schema.py, langchain/types.py
- Execution: langchain/agents/executor.py
- Tools: langchain/tools/base.py