From a30639244608c0bf2d786f594c715173f366bed0 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
<161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Wed, 20 May 2026 03:34:22 +0000
Subject: [PATCH] docs: finalize v1.0.0 with README, changelog, and CI/CD
infrastructure
- Added comprehensive README.md with badges, screenshots, and project detection table.
- Created CHANGELOG.md following Keep a Changelog format.
- Set up GitHub issue templates and PR template.
- Implemented PyPI publishing workflow (.github/workflows/publish.yml).
- Generated high-fidelity screenshots of terminal, MD, and HTML outputs.
- Updated pyproject.toml with professional PyPI metadata (classifiers, keywords, URLs).
- Added asset generation scripts and maintenance guide in docs/screenshots/.
Co-authored-by: erensh27 <244986440+erensh27@users.noreply.github.com>
---
.github/ISSUE_TEMPLATE/bug_report.md | 30 ++++
.github/ISSUE_TEMPLATE/feature_request.md | 20 +++
.github/PULL_REQUEST_TEMPLATE.md | 14 ++
.github/workflows/publish.yml | 43 +++++
CHANGELOG.md | 17 ++
CODEMAPPR.html | 203 ++++++++++++++++++++++
CODEMAPPR.md | 87 ++++++++++
README.md | 108 +++++++++++-
capture_screenshots.py | 73 ++++++++
docs/screenshots/DEMO.html | 203 ++++++++++++++++++++++
docs/screenshots/DEMO.md | 87 ++++++++++
docs/screenshots/README_SCREENSHOTS.md | 20 +++
docs/screenshots/format-all.png | Bin 0 -> 220783 bytes
docs/screenshots/format_all_output.html | 118 +++++++++++++
docs/screenshots/html-export.png | Bin 0 -> 202301 bytes
docs/screenshots/markdown-export.png | Bin 0 -> 103105 bytes
docs/screenshots/md_preview.html | 87 ++++++++++
docs/screenshots/terminal-view.png | Bin 0 -> 180065 bytes
docs/screenshots/terminal_output.html | 104 +++++++++++
generate_terminal_html.py | 24 +++
pyproject.toml | 12 ++
21 files changed, 1243 insertions(+), 7 deletions(-)
create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md
create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md
create mode 100644 .github/PULL_REQUEST_TEMPLATE.md
create mode 100644 .github/workflows/publish.yml
create mode 100644 CHANGELOG.md
create mode 100644 CODEMAPPR.html
create mode 100644 CODEMAPPR.md
create mode 100644 capture_screenshots.py
create mode 100644 docs/screenshots/DEMO.html
create mode 100644 docs/screenshots/DEMO.md
create mode 100644 docs/screenshots/README_SCREENSHOTS.md
create mode 100644 docs/screenshots/format-all.png
create mode 100644 docs/screenshots/format_all_output.html
create mode 100644 docs/screenshots/html-export.png
create mode 100644 docs/screenshots/markdown-export.png
create mode 100644 docs/screenshots/md_preview.html
create mode 100644 docs/screenshots/terminal-view.png
create mode 100644 docs/screenshots/terminal_output.html
create mode 100644 generate_terminal_html.py
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..ffb00eb
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,30 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Run '...'
+2. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Environment (please complete the following information):**
+ - OS: [e.g. macOS, Ubuntu]
+ - Python Version: [e.g. 3.9]
+ - CodeMappr Version: [e.g. 1.0.0]
+
+**Additional context**
+Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000..11fc491
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..8beab1b
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,14 @@
+## Description
+Describe your changes in detail.
+
+## Related Issue
+Fixes # (issue)
+
+## Checklist:
+- [ ] My code follows the style guidelines of this project
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+- [ ] I have updated the CHANGELOG.md
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
new file mode 100644
index 0000000..67d72db
--- /dev/null
+++ b/.github/workflows/publish.yml
@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+on:
+ push:
+ tags:
+ - 'v*'
+
+jobs:
+ test:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: '3.9'
+ - name: Install dependencies
+ run: |
+ python -m pip install --upgrade pip
+ pip install . pytest
+ - name: Run tests
+ run: pytest
+
+ publish:
+ needs: test
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ id-token: write
+ steps:
+ - uses: actions/checkout@v4
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: '3.9'
+ - name: Build package
+ run: |
+ python -m pip install build
+ python -m build
+ - name: Publish to PyPI
+ uses: pypa/gh-action-pypi-publish@release/v1
+ with:
+ password: ${{ secrets.PYPI_API_TOKEN }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..d5dbe4d
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-05-20
+### Added
+- Core scanning engine with `.gitignore` support and manual path traversal.
+- Heuristic-based project type and language stack detection for 20+ project types.
+- Architectural explainer mapping directory structures to their purpose.
+- Rich terminal dashboard featuring project profile, architecture summary, and directory tree.
+- Markdown export (`CODEMAPPR.md`) with ASCII directory trees.
+- Interactive HTML export (`CODEMAPPR.html`) with dark theme and collapsible trees.
+- CLI flags for recursion depth (`--depth`), custom ignore patterns (`--ignore`), and multiple output formats (`--format`).
+- Comprehensive test suite and GitHub Actions CI workflow.
+- Standardized documentation and PyPI-ready metadata.
diff --git a/CODEMAPPR.html b/CODEMAPPR.html
new file mode 100644
index 0000000..c2cc618
--- /dev/null
+++ b/CODEMAPPR.html
@@ -0,0 +1,203 @@
+
+
+
+
+
+ CodeMappr Report โ app
+
+
+
+
+
+
CodeMappr Report โ app
+
Generated on 2026-05-20 03:28:28 by CodeMappr v1.0.0
+
+
+
+
+
Project Profile
+
+
Type
Python Package/Library
+
Stack
HTML, Python
+
Framework
โ
+
Files
45
+
Directories
9
+
Size
2.2 MB
+
Confidence
medium
+
+
+
+
+
Key Structure
+
+
docs
Project documentation
tests
Test suite
+
+
+
+
+
+
Architecture Summary
+
This project is a Python Package/Library application developed in HTML, Python. It consists of 45 files across 9 directories. The codebase structure suggests it follows standard conventions for Python Package/Library development.
+
+
+
+
+
Entry Points
+
+
+
+
+
+
Notable Files
+
+ pyproject.toml.gitignoreREADME.mdLICENSE
+
+
+
+
+
+
Directory Tree
+
+
โผ ๐ app
โผ ๐ .github
โผ ๐ ISSUE_TEMPLATE
๐ bug_report.md
๐ feature_request.md
โผ ๐ workflows
โ๏ธ publish.yml
โ๏ธ test.yml
๐ PULL_REQUEST_TEMPLATE.md
โผ ๐ codemappr
๐ __init__.py
๐ cli.py
๐ detector.py
๐ display.py
๐ explainer.py
๐ exporter.py
๐ models.py
๐ walker.py
โผ ๐ codemappr.egg-info
๐ PKG-INFO
๐ SOURCES.txt
๐ dependency_links.txt
๐ entry_points.txt
๐ requires.txt
๐ top_level.txt
โผ ๐ docs
โผ ๐ screenshots
๐ DEMO.html
๐ DEMO.md
๐ README_SCREENSHOTS.md
๐ format-all.png
๐ format_all_output.html
๐ html-export.png
๐ markdown-export.png
๐ md_preview.html
๐ terminal-view.png
๐ terminal_output.html
โผ ๐ tests
๐ __init__.py
๐ conftest.py
๐ test_detector.py
๐ test_explainer.py
๐ test_exporters.py
๐ test_models.py
๐ test_walker.py
๐ .gitignore
๐ CHANGELOG.md
๐ CODEMAPPR.html
๐ CODEMAPPR.md
๐ LICENSE
๐ README.md
๐ capture_screenshots.py
๐ generate_terminal_html.py
โ๏ธ pyproject.toml
+
+
+
+
+
+
+
+
+
diff --git a/CODEMAPPR.md b/CODEMAPPR.md
new file mode 100644
index 0000000..887363f
--- /dev/null
+++ b/CODEMAPPR.md
@@ -0,0 +1,87 @@
+# CodeMappr Report โ app
+> Generated on 2026-05-20 03:28:28 by CodeMappr v1.0.0
+
+## Project Profile
+| Field | Value |
+| :--- | :--- |
+| Type | Python Package/Library |
+| Stack | HTML, Python |
+| Framework | โ |
+| Files | 45 |
+| Directories | 9 |
+| Size | 2.2 MB |
+
+## Architecture Summary
+This project is a Python Package/Library application developed in HTML, Python. It consists of 45 files across 9 directories. The codebase structure suggests it follows standard conventions for Python Package/Library development.
+
+## Folder Structure
+| Folder | Purpose |
+| :--- | :--- |
+| docs | Project documentation |
+| tests | Test suite |
+
+## Entry Points
+
+## Notable Files
+- pyproject.toml
+- .gitignore
+- README.md
+- LICENSE
+
+## Directory Tree
+```text
+๐ app
+โโโ ๐ .github
+โ โโโ ๐ ISSUE_TEMPLATE
+โ โ โโโ ๐ bug_report.md
+โ โ โโโ ๐ feature_request.md
+โ โโโ ๐ PULL_REQUEST_TEMPLATE.md
+โ โโโ ๐ workflows
+โ โโโ ๐ publish.yml
+โ โโโ ๐ test.yml
+โโโ ๐ .gitignore
+โโโ ๐ CHANGELOG.md
+โโโ ๐ CODEMAPPR.html
+โโโ ๐ CODEMAPPR.md
+โโโ ๐ LICENSE
+โโโ ๐ README.md
+โโโ ๐ capture_screenshots.py
+โโโ ๐ codemappr
+โ โโโ ๐ __init__.py
+โ โโโ ๐ cli.py
+โ โโโ ๐ detector.py
+โ โโโ ๐ display.py
+โ โโโ ๐ explainer.py
+โ โโโ ๐ exporter.py
+โ โโโ ๐ models.py
+โ โโโ ๐ walker.py
+โโโ ๐ codemappr.egg-info
+โ โโโ ๐ PKG-INFO
+โ โโโ ๐ SOURCES.txt
+โ โโโ ๐ dependency_links.txt
+โ โโโ ๐ entry_points.txt
+โ โโโ ๐ requires.txt
+โ โโโ ๐ top_level.txt
+โโโ ๐ docs
+โ โโโ ๐ screenshots
+โ โโโ ๐ DEMO.html
+โ โโโ ๐ DEMO.md
+โ โโโ ๐ README_SCREENSHOTS.md
+โ โโโ ๐ format-all.png
+โ โโโ ๐ format_all_output.html
+โ โโโ ๐ html-export.png
+โ โโโ ๐ markdown-export.png
+โ โโโ ๐ md_preview.html
+โ โโโ ๐ terminal-view.png
+โ โโโ ๐ terminal_output.html
+โโโ ๐ generate_terminal_html.py
+โโโ ๐ pyproject.toml
+โโโ ๐ tests
+ โโโ ๐ __init__.py
+ โโโ ๐ conftest.py
+ โโโ ๐ test_detector.py
+ โโโ ๐ test_explainer.py
+ โโโ ๐ test_exporters.py
+ โโโ ๐ test_models.py
+ โโโ ๐ test_walker.py
+```
\ No newline at end of file
diff --git a/README.md b/README.md
index 791dcfc..7609503 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,109 @@
-# CodeMappr
+# CodeMappr ๐บ๏ธ
+> Instantly understand any codebase. One command.
-Instantly understand any codebase.
+
+
+
+
+
-## Installation
+## What is CodeMappr?
+CodeMappr is a powerful CLI tool designed to give you an instant, high-level understanding of any codebase. Whether you're jumping into a new repository for the first time or documenting an existing one, CodeMappr scans the directory structure, detects the project type, identifies the language stack, and summarizes the architecture in seconds.
+
+Unlike many other tools, CodeMappr works entirely offline and requires no API keys. It uses heuristic-based signals to identify over 20 different project types and supports universal language detection. With three distinct output formatsโinteractive Terminal dashboard, portable Markdown, and a beautiful dark-themed HTML reportโCodeMappr is the perfect companion for every developer's toolkit.
+
+## Demo
+
+**Screenshot 1 โ Terminal View**
+
+
+**Screenshot 2 โ Markdown Export**
+
+
+**Screenshot 3 โ HTML Export**
+
+
+**Screenshot 4 โ All formats at once**
+
+## Installation
```bash
-pip install .
+pip install codemappr
```
-## Usage
-
+## Quick Start
```bash
-codemappr scan .
+# Scan current directory
+codemappr scan
+
+# Scan a specific path
+codemappr scan /path/to/project
+
+# Export as markdown
+codemappr scan --format md
+
+# Export as HTML
+codemappr scan --format html
+
+# Export everything at once
+codemappr scan --format all
+
+# Limit depth
+codemappr scan --depth 3
+
+# Ignore patterns
+codemappr scan --ignore ".cache,temp"
```
+
+## Output Formats
+
+### Terminal
+A rich, color-coded dashboard displayed directly in your terminal, featuring panels for project profiles, architectural summaries, and a styled directory tree.
+
+### Markdown
+A portable `CODEMAPPR.md` file perfect for inclusion in pull requests, project documentation, or sharing via GitHub/GitLab.
+
+### HTML
+A standalone, interactive `CODEMAPPR.html` report with a dark theme and collapsible directory trees for deep exploration of large codebases.
+
+## Supported Project Types
+
+| Project Type | Detection Signals |
+|--------------|-------------------|
+| **Monorepo** | Presence of `packages/`, `apps/`, or `libs/` with multiple project configs. |
+| **React/Next.js** | `package.json` with `next` or `react` dependencies, or `next.config.js`. |
+| **Vue.js** | `vue.config.js` or presence of `.vue` files (e.g., `App.vue`). |
+| **Angular** | `angular.json` configuration file and standard `src/app` structure. |
+| **Node.js API** | `package.json` with entry points like `index.js`, `server.js`, or `app.js`. |
+| **Python Django** | `manage.py` script along with `settings.py` and `urls.py`. |
+| **Python FastAPI/Flask** | `main.py` or `app.py` with corresponding framework dependencies. |
+| **Python Package/Library** | Presence of `pyproject.toml` or `setup.py`. |
+| **Rust** | `Cargo.toml` manifest file. |
+| **Go** | `go.mod` module file. |
+| **Java/Spring** | `pom.xml` (Maven) or `build.gradle` (Gradle) files. |
+| **Android** | Presence of `AndroidManifest.xml`. |
+| **Flutter/Dart** | `pubspec.yaml` manifest file. |
+| **Ruby on Rails** | `Gemfile` plus `config/routes.rb` and standard `app/` directory. |
+| **PHP/Laravel** | `composer.json` and the `artisan` CLI tool. |
+| **Docker-based** | Presence of `Dockerfile` or `docker-compose.yml`. |
+| **Data Science/ML** | `.ipynb` notebooks or `notebooks/` directory with DS libraries (pandas, etc.). |
+| **Static Site** | Presence of a root `index.html` without heavy framework signals. |
+| **Generic Python** | Fallback for projects primarily using `.py` files. |
+| **Generic JS/TS** | Fallback for projects primarily using `.js` or `.ts` files. |
+
+## Roadmap
+- **v1.0.0** โ Core scanning, detection, terminal + export
+- **v2.0.0** ๐ File relationship map
+- **v3.0.0** ๐ Structural diff / changelog
+
+## Contributing
+We welcome contributions! To contribute:
+1. Fork the repository.
+2. Create a new branch for your feature or bugfix.
+3. Ensure all tests pass by running `pytest`.
+4. Submit a pull request with a detailed description of your changes.
+
+All new features should be accompanied by relevant tests and documentation updates.
+
+## License
+MIT
diff --git a/capture_screenshots.py b/capture_screenshots.py
new file mode 100644
index 0000000..db66d05
--- /dev/null
+++ b/capture_screenshots.py
@@ -0,0 +1,73 @@
+import os
+from playwright.sync_api import sync_playwright
+
+def capture_screenshots():
+ with sync_playwright() as p:
+ browser = p.chromium.launch(headless=True)
+ context = browser.new_context(viewport={"width": 1200, "height": 1000})
+ page = context.new_page()
+
+ # 1. Terminal View
+ # Use file path for the generated terminal HTML
+ html_path = os.path.abspath("docs/screenshots/terminal_output.html")
+ page.goto(f"file://{html_path}")
+ page.wait_for_timeout(1000)
+ # Find the element that contains the terminal output
+ # Rich HTML usually has a
or similar
+ container = page.locator("body")
+ container.screenshot(path="docs/screenshots/terminal-view.png")
+ print("Captured terminal-view.png")
+
+ # 2. Markdown Export
+ # First generate the MD
+ os.system("codemappr scan . --format md --output docs/screenshots/DEMO.md")
+ # To "view" it rendered, we could use a library, but maybe we can just show the terminal confirmation for now?
+ # Actually, let's try to render it simply or just take a screenshot of the terminal confirming it.
+ # The prompt says: "Capture the terminal confirmation message + open the generated CODEMAPPR.md rendered in a markdown viewer or GitHub preview."
+ # Rendering MD in headless env is tricky without a server.
+ # I'll create a simple HTML wrapper to show the MD content.
+ with open("docs/screenshots/DEMO.md", "r") as f:
+ md_content = f.read()
+
+ md_html = f"
{md_content}
"
+ with open("docs/screenshots/md_preview.html", "w") as f:
+ f.write(md_html)
+
+ page.goto(f"file://{os.path.abspath('docs/screenshots/md_preview.html')}")
+ page.screenshot(path="docs/screenshots/markdown-export.png")
+ print("Captured markdown-export.png")
+
+ # 3. HTML Export
+ os.system("codemappr scan . --format html --output docs/screenshots/DEMO.html")
+ page.goto(f"file://{os.path.abspath('docs/screenshots/DEMO.html')}")
+ page.wait_for_timeout(1000)
+ page.screenshot(path="docs/screenshots/html-export.png", full_page=True)
+ print("Captured html-export.png")
+
+ # 4. All formats
+ # We need to capture the terminal output for this one.
+ # Similar to terminal-view but specifically for the 'all' command output.
+ # I'll use a simplified version.
+ from rich.console import Console
+ from typer.testing import CliRunner
+ from codemappr.cli import app
+ import codemappr.cli
+ import codemappr.display
+
+ console = Console(record=True, width=100, force_terminal=True)
+ codemappr.cli.console = console
+ codemappr.display.console = console
+ runner = CliRunner()
+ runner.invoke(app, ["scan", ".", "--format", "all"])
+ console.save_html("docs/screenshots/format_all_output.html")
+
+ page.goto(f"file://{os.path.abspath('docs/screenshots/format_all_output.html')}")
+ # Wait for content to be sure
+ page.wait_for_timeout(1000)
+ page.screenshot(path="docs/screenshots/format-all.png", full_page=True)
+ print("Captured format-all.png")
+
+ browser.close()
+
+if __name__ == "__main__":
+ capture_screenshots()
diff --git a/docs/screenshots/DEMO.html b/docs/screenshots/DEMO.html
new file mode 100644
index 0000000..0f77764
--- /dev/null
+++ b/docs/screenshots/DEMO.html
@@ -0,0 +1,203 @@
+
+
+
+
+
+ CodeMappr Report โ app
+
+
+
+
+
+
CodeMappr Report โ app
+
Generated on 2026-05-20 03:28:26 by CodeMappr v1.0.0
+
+
+
+
+
Project Profile
+
+
Type
Python Package/Library
+
Stack
HTML, Python
+
Framework
โ
+
Files
45
+
Directories
9
+
Size
2.2 MB
+
Confidence
medium
+
+
+
+
+
Key Structure
+
+
docs
Project documentation
tests
Test suite
+
+
+
+
+
+
Architecture Summary
+
This project is a Python Package/Library application developed in HTML, Python. It consists of 45 files across 9 directories. The codebase structure suggests it follows standard conventions for Python Package/Library development.