How stochastic-sisyphus/code-cartographer works
Project type and purpose
• Code Cartographer is a Python-based, CLI-driven static analysis tool for Python codebases.
• It provides deep multilayer analysis (complexity, variants, hashes), generates reports (Markdown, Graphviz), and offers an interactive dashboard via HTML templates.
File structure
• Top level:
• .github/workflows/publish.yml (CI/CD for PyPI)
• pyproject.toml, requirements.txt, setup files (packaging & dependencies)
• code_cartographer/cli.py (entry point), core/ (analysis engine), templates/ (dashboard UI)
• guide.md, README.md, LICENSE (documentation)
• tests/ (unit tests for analyzers)
• Key directories:
• code_cartographer/core/ holds the Analyzer classes (analyzer.py, variant_analyzer.py)
• templates/ has Jinja2 HTML templates for the interactive dashboard
• CLI serves as orchestrator and exposes commands
README for additional insights
• Core components: ProjectAnalyzer, VariantAnalyzer
• Outputs: Markdown summary (analysis.md, variants.md), Graphviz dependency graph (*.dot), interactive HTML dashboard
• External tools: Radon (complexity), Graphviz, Jinja2, LLM prompts
a. Main components
1. CLI Layer (code-cartographer commands)
2. Core Analysis Engine
• ProjectAnalyzer
• VariantAnalyzer
• Normalization & hashing module
• Complexity & maintainability metrics (Radon integration)
3. Data Model & Storage
• AST & metadata objects (classes/functions, docstrings, complexity scores)
• Variant groupings, semantic similarity results
4. Output Generators
• Markdown report generator
• Graphviz .dot generator (dependency graph)
• Jinja2 HTML dashboard renderer
5. Template Layer (templates/dashboard.html.j2)
6. External Services
• Radon library
• Graphviz binary (for rendering .dot files)
• Optionally an LLM API for refactor prompt generation
b. Relationships & interactions
• CLI Layer → invokes → Core Analysis Engine
• Core Engine → produces → intermediate Data Model
• Data Model → fed into → Output Generators
• Output Generators → write → files (Markdown, .dot, HTML)
• Template Layer ← used by ← HTML generator
• Core Engine ↔ calls → Radon & Semantic Analysis libraries
• .dot files → rendered by → Graphviz
c. Architectural patterns & principles
• Layered architecture: separation of CLI, processing engine, output layer
• Single responsibility: analyzers focus on code metrics, variant analyzers focus on semantic merging
• Extensibility: template-driven dashboard, plugin-like CLI flags for thresholds & exclusions
• Data flow is uni-directional (analysis → model → report)
d. Relevant technologies & libraries
• Python 3.8+
• Click or argparse (in cli.py) for command-line interface
• Radon for complexity & maintainability
• Jinja2 for HTML templating
• Graphviz for dependency visualization
• LLM prompt generation (internal module, optional API)