Extracts import/dependency relationships from a code repository via AST parsing, and automatically generates three types of diagrams:
- Architecture Diagram — dependency relationships at the module/directory level
- Flowchart — import call chains at the file level
- Org Chart — hierarchical structure of directories/files
Supported languages: Python, JavaScript, TypeScript, Go, Java
Output formats: Mermaid text (.mmd) or SVG images (requires mmdc)
Usage
Basic usage: analyze the entire project
python3 scripts/analyze_codebase.py /path/to/project
Outputs three Mermaid diagrams to stdout and also writes them to the .mmd file in the current directory.
Specify diagram type
# 仅生成架构图
python3 scripts/analyze_codebase.py /path/to/project --type architecture
# 仅生成流程图
python3 scripts/analyze_codebase.py /path/to/project --type flowchart
# 仅生成组织架构图
python3 scripts/analyze_codebase.py /path/to/project --type org
Specify output directory and format
# 输出到指定目录
python3 scripts/analyze_codebase.py /path/to/project --output /tmp/diagrams
# 输出 SVG(需要 mmdc)
python3 scripts/analyze_codebase.py /path/to/project --format svg
# 同时输出 Mermaid 和 SVG
python3 scripts/analyze_codebase.py /path/to/project --format both
Output JSON analysis results
python3 scripts/analyze_codebase.py /path/to/project --json
Parameter description
| Parameter | Description |
|---|---|
directory |
Code directory to analyze (required) |
--type, -t |
Diagram type:architecture、flowchart、org、all(default all) |
--output, -o |
Output directory (defaults to current directory) |
--format, -f |
Output format:mermaid、svg、both(default mermaid) |
--max-files |
Maximum number of files to scan (default 500) |
--max-depth |
Maximum depth of the org chart (default 4) |
--json |
Output analysis results in JSON format |
How it works
- Scan phase: recursively traverse directories, skipping
node_modules、.git、__pycache__, etc. - Parse phase:
- Python files use the
astmodule to parseimportandfrom ... importstatements - JS/TS files use regex to match
import、require、export from - Go files use regex to match
importstatements - Java files use regex to match
importstatements
- Python files use the
- Resolve internal dependencies: map import paths to actual files within the project
- Generate diagrams: convert dependency relationships into Mermaid diagram syntax
- Render (optional): call
mmdc(Mermaid CLI) to render.mmdto SVG
Use cases
- Quickly understand the module structure of an unfamiliar project
- Visualize dependency relationships during code review
- Create architecture diagrams for technical documentation
- Discover circular dependencies or excessive coupling
- Structural analysis before project refactoring
Dependencies
- Python 3.7+ (standard library, no additional installation required)
- SVG output requires
@mermaid-js/mermaid-cli(optional)
Notes
- Only analyzes static import relationships; does not track dynamic imports
- For large projects, it is recommended to use
--max-filesto limit the scan scope - Mermaid diagrams may be difficult to render when there are too many nodes; it is recommended to use
--typeto view them separately