codedocent 0.1.0__tar.gz

codedocent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codedocent-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: codedocent
+Version: 0.1.0
+Summary: Code visualization for non-programmers
+License-Expression: MIT
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: tree-sitter>=0.23
+Requires-Dist: tree-sitter-language-pack>=0.13
+Requires-Dist: radon>=6.0
+Requires-Dist: pathspec>=0.11
+Requires-Dist: jinja2>=3.1
+Requires-Dist: ollama>=0.4
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file

codedocent-0.1.0/README.md

@@ -0,0 +1,163 @@
+# codedocent
+
+**Code visualization for non-programmers.**
+
+A docent is a guide who explains things to people who aren't experts. Codedocent does that for code.
+
+> Google Translate for code → human understanding.
+
+---
+
+## What it does
+
+Codedocent takes any codebase and turns it into a visual, navigable map that anyone can read — no programming knowledge required.
+
+Every piece of code becomes a **block** that shows:
+- A **plain English explanation** of what it does
+- A **pseudocode translation** (simplified logic, not real syntax)
+- **Quality warnings** with explanatory text (complexity, line count, parameter count)
+- The **actual source code** (hidden by default, expandable)
+
+Blocks are **nested** — directories contain files, files contain classes, classes contain functions. Click to drill down. Breadcrumbs to navigate back up. Color-coded by language.
+
+### Code actions
+
+Every analyzed block gets a toolbar with one-click actions:
+
+| Button | What it does |
+|--------|-------------|
+| **Show Code** | Expand/collapse the source code inline |
+| **Export Code** | Copy raw source to clipboard |
+| **Copy for AI** | Copy source wrapped in a markdown code fence with context (block name, file path) — ready to paste into an AI assistant |
+| **Replace Code** | Open an editor to paste modified code back into the source file |
+
+**Replace Code** (available on functions, methods, and classes) lets you paste fixed or improved code — from an AI assistant, a code review, or your own edits — directly back into the original file. A `.bak` backup is created automatically before any write. The UI shows a confirmation step with success/error feedback, and all cached analysis is cleared so the block can be re-analyzed with the new code.
+
+## Who it's for
+
+You understand systems. You can read a schematic. You just can't read Python.
+
+Codedocent is for project managers, founders, designers, analysts, auditors — anyone who needs to understand what a codebase does without learning to code.
+
+## Quick start
+
+### Requirements
+
+- Python 3.10+
+- [Ollama](https://ollama.com) installed and running
+- A model pulled (e.g., `ollama pull gemma3:4b`)
+
+### Install
+```bash
+git clone https://github.com/clanker-lover/codedocent.git
+cd codedocent
+pip install -e .
+```
+
+### Run
+
+**Interactive mode** (recommended) — instant load, AI analyzes each block on click:
+```bash
+codedocent /path/to/any/codebase
+```
+
+Your browser opens automatically. Click any block to drill down and trigger AI analysis.
+
+**Full analysis mode** — analyzes everything upfront, outputs a static HTML file:
+```bash
+codedocent /path/to/any/codebase --full
+```
+
+**Text mode** — quick tree overview, no AI:
+```bash
+codedocent /path/to/any/codebase --text
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--full` | Analyze everything upfront, output static HTML |
+| `--text` | Print text tree to terminal (no browser) |
+| `--no-ai` | Skip AI summaries, show structure only |
+| `--model MODEL` | Ollama model to use (default: `qwen3:14b`) |
+| `--port PORT` | Port for interactive server (default: auto) |
+| `--workers N` | Parallel AI workers for `--full` mode (default: 1) |
+| `--output FILE` | Output filename for `--full` mode |
+
+## Supported languages
+
+Codedocent detects **23 file extensions** across these languages. Python and JavaScript/TypeScript get full AST parsing (functions, classes, methods, imports). All other languages get file-level analysis.
+
+| Full parsing | File-level detection |
+|-------------|---------------------|
+| Python (.py) | C / C++ (.c, .cpp, .h, .hpp) |
+| JavaScript (.js) | Rust (.rs) |
+| TypeScript (.ts, .tsx) | Go (.go) |
+| | Java (.java) |
+| | Ruby (.rb) |
+| | PHP (.php) |
+| | Swift (.swift) |
+| | Kotlin (.kt) |
+| | Scala (.scala) |
+| | HTML / CSS |
+| | Config files (JSON, YAML, TOML) |
+
+## How it works
+
+**Interactive mode** starts a local server and opens your browser. The code tree loads instantly. When you click a block, it calls Ollama to analyze just that node — typically 1-2 seconds with a 4B model.
+
+**Full mode** analyzes every node in priority order (directories → files → functions), with an optional `--workers` flag for parallel AI requests. Outputs a self-contained HTML file you can share.
+
+All AI runs locally via Ollama. No data leaves your machine.
+
+## AI models
+
+Codedocent works with any model from the [Ollama library](https://ollama.com/library).
+
+## Quality indicators
+
+Each block shows a quality badge based on static analysis, with warnings that explain *why* — not just colored dots.
+
+| Badge | Meaning |
+|-------|---------|
+| 🟢 Clean | Low complexity, no warnings |
+| 🟡 Complex | Moderate complexity, long functions, or many parameters |
+| 🔴 Warning | High complexity or very long code |
+
+Warnings roll up through the tree: a file inherits the worst quality of its functions, and a directory inherits the worst quality of its files. Each level shows a count of problematic children (e.g., "Contains 2 high-risk functions"). Quality scoring works for all supported languages — Python files also get [radon](https://radon.readthedocs.io/) cyclomatic complexity analysis.
+
+## Architecture
+
+```
+codedocent/
+├── cli.py          Command-line interface and entry point
+├── scanner.py      File discovery with .gitignore support
+├── parser.py       AST parsing via tree-sitter
+├── analyzer.py     AI summaries, quality scoring, caching
+├── editor.py       Code replacement with backup safety
+├── renderer.py     HTML generation (static + interactive)
+├── server.py       Local server for interactive mode
+└── templates/
+    └── interactive.html   Single-page app UI
+```
+
+## Current status
+
+- Scanner, parser, renderer, analyzer, editor, server, CLI — all built and tested
+- Interactive navigation with lazy AI analysis
+- Static HTML full-analysis mode with parallel workers
+- Code actions — Show Code, Export Code, Copy for AI, Replace Code
+- Code replacement with `.bak` backup and cache invalidation
+- Quality scoring with two-tier thresholds and warning rollup across the tree
+- pip-installable package with `codedocent` CLI entry point
+- 75 tests passing
+- Code quality: pylint 10/10, bandit/flake8/mypy all clean
+
+## License
+
+MIT
+
+## Contributing
+
+This project is in active early development. Issues and ideas welcome.

codedocent-0.1.0/codedocent/__init__.py

@@ -0,0 +1 @@
+"""codedocent — code visualization for non-programmers."""

codedocent-0.1.0/codedocent/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running codedocent as `python3 -m codedocent`."""
+from codedocent.cli import main
+
+main()