{"id":37079455,"url":"https://github.com/stochastic-sisyphus/code-cartographer","last_synced_at":"2026-01-14T09:36:57.531Z","repository":{"id":288500843,"uuid":"968325634","full_name":"stochastic-sisyphus/code-cartographer","owner":"stochastic-sisyphus","description":"Deep Multilayer Static Analyzer for Python Projects","archived":false,"fork":false,"pushed_at":"2025-11-13T05:54:08.000Z","size":515,"stargazers_count":2,"open_issues_count":7,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-05T20:35:24.126Z","etag":null,"topics":["code-analysis","code-review","codebase-analysis","static-analysis"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/code-cartographer","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stochastic-sisyphus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-17T22:18:34.000Z","updated_at":"2025-10-13T02:16:20.000Z","dependencies_parsed_at":"2025-05-06T23:22:09.580Z","dependency_job_id":"c1c1f6dd-079d-4b8f-bbe2-7adde2815451","html_url":"https://github.com/stochastic-sisyphus/code-cartographer","commit_stats":null,"previous_names":["stochastic-sisyphus/code-cartographer"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/stochastic-sisyphus/code-cartographer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stochastic-sisyphus%2Fcode-cartographer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stochastic-sisyphus%2Fcode-cartographer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stochastic-sisyphus%2Fcode-cartographer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stochastic-sisyphus%2Fcode-cartographer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stochastic-sisyphus","download_url":"https://codeload.github.com/stochastic-sisyphus/code-cartographer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stochastic-sisyphus%2Fcode-cartographer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28416120,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:38:59.149Z","status":"ssl_error","status_checked_at":"2026-01-14T08:38:43.588Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-analysis","code-review","codebase-analysis","static-analysis"],"created_at":"2026-01-14T09:36:57.055Z","updated_at":"2026-01-14T09:36:57.525Z","avatar_url":"https://github.com/stochastic-sisyphus.png","language":"Python","readme":"# Code Cartographer  \n\n## Automated Deep Multilayer Code Analysis and Optimization for Large Scale Codebases \n\n---\n\nAs a masochist, I am never satisfied with a project until I reach perfection.  \nTo me, perfection is so far beyond running correctly or achieving 0 problems across all files in a directory.  \nAlthough I've never actually achieved the elusive \"perfect\" finish line in any project ever, so I can't be sure about the definition.\nIt's also just what happens when you're experimenting. When you're deep in research, you're iterating in a vacuum; by the time something works, you've rewritten it five times. Therefore, I unsurprisingly constantly have at least a few iterations of the same project on my local machine that I'm actively making more refinements to at all times.  \nThis can cause confusion (shocker!), especially because I am reluctant to push or publish incomplete or \"inadequate\" code. I also have a fear of being perceived—and what's more vulnerable than my code?\n\u003e *\"For when your code is too chaotic for flake8 and too personal for git push.\"*\n\nJust like that, a vicious cycle is born.  \nAn unproductive, deeply confusing, memory-consuming vicious cycle.\n\nUnfortunately the cycle is **much** harder to follow when there are dozens of moving parts in dozens of subfolders, each with (dozens) of lengthy scripts. You could feed your directory setup as context in an attempt to gain some clarity, but that's a gamble that backfires 9 times out of 10. Has any LLM ever in all of human history actually internalized any tree structure to assist you in reorganizing a repo? Yeah, I didn't think so. Not for me either. So if a vicious cycle is now my daily routine, at a certain point I decided to give myself the illusion of respite, however brief. This has given me solace at least once. Enjoy!\n\n---\n\n# Code Cartographer\n\u003e\n\u003e *\"If Git is for branches, this is for forks of forks.\"*\n\n---\n\n## Features\n\n- **Full file and definition level metadata**  \n  Class/function blocks, line counts, docstrings, decorators, async flags, calls, type hints\n\n- **Intelligent Code Normalization**  \n  Standardizes variable names, function signatures, and code structure for better comparison\n\n- **Advanced Variant Detection \u0026 Merging**  \n  Automatically identifies and merges similar code blocks with semantic analysis\n\n- **Auto-patching System**  \n  Safely applies merged variants with automatic backup creation\n\n- **Function/class SHA-256 hashes**  \n  Detects variants, clones, and partial rewrites across versions\n\n- **Cyclomatic complexity \u0026 maintainability index analysis (via `radon`)**  \n  Flags \"at-risk\" code with CC \u003e 10 or MI \u003c 65\n\n- **Auto-generated LLM refactor prompts**  \n  Variant grouping, inline diffs, rewrite guidance\n\n- **Internal dependency graph**  \n  Outputs a Graphviz `.dot` of all intra-project imports\n\n- **Markdown summary**  \n  Skimmable digest with risk flags and structure\n\n- **Interactive Dashboard**  \n  Visual analysis of code complexity, variants, and dependencies\n\n- **CLI flexibility**  \n  Exclusion patterns, Git SHA tagging, output formatting, variant merging controls\n\n---\n\n## Setup \u0026 Installation\n\n### Prerequisites\n\n- Python 3.8+\n- (Optional) Graphviz for dependency visualization\n\n### Installation\n\nYou can install code-cartographer directly from PyPI:\n\n```bash\npip install code-cartographer\n```\n\nFor development installation:\n\n1. **Clone the Repository**\n\n```bash\ngit clone https://github.com/stochastic-sisyphus/code-cartographer.git\ncd code-cartographer\n```\n\n2. **Create Virtual Environment**\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n```\n\n3. **Install in Development Mode**\n\n```bash\npip install -e \".[dev]\"\n```\n\n---\n\n## Usage Guide\n\n### Quick Start\n\nThe code-cartographer package provides tools for analyzing Python codebases:\n\n```python\nfrom code_cartographer import ProjectAnalyzer, VariantAnalyzer\n\n# Initialize analyzers\nproject_analyzer = ProjectAnalyzer(\"/path/to/your/project\")\nvariant_analyzer = VariantAnalyzer()\n\n# Run analysis\nanalysis_results = project_analyzer.analyze()\nvariant_results = variant_analyzer.analyze(analysis_results)\n\n# Generate reports\nproject_analyzer.generate_markdown(\"analysis.md\")\nproject_analyzer.generate_dependency_graph(\"dependencies.dot\")\n```\n\n### Advanced Usage\n\n#### 1. Deep Code Analysis\n\n```python\nfrom code_cartographer import ProjectAnalyzer\n\nanalyzer = ProjectAnalyzer(\n    project_dir=\"/path/to/project\",\n    exclude_patterns=[\"tests/.*\", \"build/.*\"]\n)\n\n# Run analysis\nresults = analyzer.analyze()\n\n# Generate reports\nanalyzer.generate_markdown(\"summary.md\")\nanalyzer.generate_dependency_graph(\"deps.dot\")\n```\n\n#### 2. Code Variant Analysis\n\n```python\nfrom code_cartographer import VariantAnalyzer\n\n# Initialize analyzer with custom settings\nanalyzer = VariantAnalyzer(\n    root=\"/path/to/project\",\n    semantic_threshold=0.8,  # 80% similarity required\n    min_lines=5  # Minimum lines for variant consideration\n)\n\n# Run analysis\nresults = analyzer.analyze()\n\n# Apply merged variants (with automatic backups)\nanalyzer.apply_merged_variants(backup=True)\n```\n\n#### 3. CLI Variant Management\n\n```bash\n# Analyze and merge variants with backups\ncode-cartographer variants -d /path/to/project --apply-merges\n\n# Analyze and merge variants without backups\ncode-cartographer variants -d /path/to/project --apply-merges --no-backup\n\n# Analyze with custom similarity threshold\ncode-cartographer variants -d /path/to/project --semantic-threshold 0.9\n```\n\n---\n\n## Output Structure\n\nAfter analysis, you'll find:\n\n```\nanalyzed-project/\n├── analysis.md         # Human-readable summary\n├── dependencies.dot    # Dependency graph (if Graphviz is installed)\n└── variants.md        # Code variant analysis report\n```\n\n### Key Metrics\n\n- Code complexity metrics\n- Import dependencies\n- Function/class definitions\n- Documentation coverage\n- Code variants and duplicates\n- Semantic similarity scores\n\n---\n\n## Best Practices\n\n### 1. Regular Analysis\n\n```python\nfrom code_cartographer import ProjectAnalyzer\nimport datetime\n\n# Add to your analysis pipeline\nanalyzer = ProjectAnalyzer(\".\")\nresults = analyzer.analyze()\ndate_str = datetime.datetime.now().strftime(\"%Y%m%d\")\nanalyzer.generate_markdown(f\"analysis-{date_str}.md\")\n```\n\n### 2. Large Projects\n\n```python\nfrom code_cartographer import ProjectAnalyzer\n\n# Analyze specific directories with exclusions\nanalyzer = ProjectAnalyzer(\n    \"src\",\n    exclude_patterns=[\n        \"tests/.*\",\n        \"docs/.*\",\n        \"*.pyc\",\n        \"__pycache__/.*\"\n    ]\n)\nresults = analyzer.analyze()\n```\n\n---\n\n## Troubleshooting\n\n### Memory Issues\n\n- Reduce analysis scope using exclude patterns\n- Process directories sequentially for large projects\n- Use the similarity threshold in VariantAnalyzer to limit comparisons\n\n### Performance Tips\n\n- Focus analysis on specific directories\n- Use appropriate similarity thresholds\n- Leverage code normalization options\n\n### Common Issues\n\n- Ensure Python 3.8+ is being used\n- Check file permissions for output directories\n- Verify Graphviz installation for dependency graphs\n\n---\n\n## Author Notes\n\nThis tool exists to reconcile broken, duplicated, or ghost-forked Python projects.\nIt helps you detect what's salvageable, refactor what's duplicated, and visualize the mess you made.\n\nWhether you're dealing with:\n\n- Fragmented directories\n- Local edits lost to time\n- Abandoned branches and reanimated scripts\n\nThis is for you.\nOr at least, for the version of you that still wants to fix it.\n\n\u003e *\"Structured remorse for unstructured code.\"*\n\n---\n\n## License\n\nMIT License. See LICENSE file for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstochastic-sisyphus%2Fcode-cartographer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstochastic-sisyphus%2Fcode-cartographer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstochastic-sisyphus%2Fcode-cartographer/lists"}