codedocent 0.3.0__tar.gz → 0.4.0__tar.gz

{codedocent-0.3.0 → codedocent-0.4.0}/PKG-INFO

@@ -1,20 +1,12 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.1
 Name: codedocent
-Version: 0.3.0
+Version: 0.4.0
 Summary: Code visualization for non-programmers
-License-Expression: MIT
+License: MIT
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-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
+License-File: LICENSE
 
 # codedocent
 
@@ -24,6 +16,21 @@ Dynamic: license-file
 
 A docent is a guide who explains things to people who aren't experts. Codedocent does that for code.
 
+## The problem
+
+You're staring at a codebase you didn't write — maybe thousands of files across dozens of directories — and you need to understand what it does. Reading every file isn't realistic. You need a way to visualize the code structure, get a high-level map of what's where, and drill into the parts that matter without losing context.
+
+Codedocent parses the codebase into a navigable, visual block structure and explains each piece in plain English. It's an AI code analysis tool that runs entirely on your machine — no API keys, no cloud, no data leaving your laptop. Point it at any codebase and get a structural overview you can explore interactively, understand quickly, and share as a static HTML file.
+
+## Who this is for
+
+- **Developers onboarding onto an unfamiliar codebase** — get oriented in minutes instead of days
+- **Non-programmers** (managers, designers, PMs) who need to understand what code does without reading it
+- **Solo developers inheriting legacy code** — map out the structure before making changes
+- **Code reviewers** who want a high-level overview before diving into details
+- **Security reviewers** who need a structural map of an application
+- **Students** learning to read and navigate real-world codebases
+
 ## What you see
 
 Nested, color-coded blocks representing directories, files, classes, and functions — the entire structure of a codebase laid out visually. Each block shows a plain English summary, a pseudocode translation, and quality warnings (green/yellow/red). Click any block to drill down; breadcrumbs navigate you back up. You can export code from any block or paste replacement code back into the source file. All AI runs locally through Ollama — nothing leaves your machine.
@@ -49,6 +56,10 @@ codedocent --gui                   # graphical launcher
 
 Parses code structure with tree-sitter, scores quality with static analysis, and sends individual blocks to a local Ollama model for plain English summaries and pseudocode. Interactive mode analyzes on click — typically 1-2 seconds per block. Full mode analyzes everything upfront into a self-contained HTML file you can share.
 
+## Why local
+
+All AI processing runs through Ollama on your machine. Your code is never uploaded, transmitted, or stored anywhere external. No API keys, no accounts, no cloud services. This matters when you're working with proprietary code, client projects, or anything you can't share — codedocent works fully air-gapped. The `--no-ai` mode removes the AI dependency entirely while keeping the structural visualization and quality scoring.
+
 ## Supported languages
 
 Full AST parsing for Python and JavaScript/TypeScript (functions, classes, methods, imports). File-level detection for 23 extensions including C, C++, Rust, Go, Java, Ruby, PHP, Swift, Kotlin, Scala, HTML, CSS, and config formats.

{codedocent-0.3.0 → codedocent-0.4.0}/README.md

@@ -6,6 +6,21 @@
 
 A docent is a guide who explains things to people who aren't experts. Codedocent does that for code.
 
+## The problem
+
+You're staring at a codebase you didn't write — maybe thousands of files across dozens of directories — and you need to understand what it does. Reading every file isn't realistic. You need a way to visualize the code structure, get a high-level map of what's where, and drill into the parts that matter without losing context.
+
+Codedocent parses the codebase into a navigable, visual block structure and explains each piece in plain English. It's an AI code analysis tool that runs entirely on your machine — no API keys, no cloud, no data leaving your laptop. Point it at any codebase and get a structural overview you can explore interactively, understand quickly, and share as a static HTML file.
+
+## Who this is for
+
+- **Developers onboarding onto an unfamiliar codebase** — get oriented in minutes instead of days
+- **Non-programmers** (managers, designers, PMs) who need to understand what code does without reading it
+- **Solo developers inheriting legacy code** — map out the structure before making changes
+- **Code reviewers** who want a high-level overview before diving into details
+- **Security reviewers** who need a structural map of an application
+- **Students** learning to read and navigate real-world codebases
+
 ## What you see
 
 Nested, color-coded blocks representing directories, files, classes, and functions — the entire structure of a codebase laid out visually. Each block shows a plain English summary, a pseudocode translation, and quality warnings (green/yellow/red). Click any block to drill down; breadcrumbs navigate you back up. You can export code from any block or paste replacement code back into the source file. All AI runs locally through Ollama — nothing leaves your machine.
@@ -31,6 +46,10 @@ codedocent --gui                   # graphical launcher
 
 Parses code structure with tree-sitter, scores quality with static analysis, and sends individual blocks to a local Ollama model for plain English summaries and pseudocode. Interactive mode analyzes on click — typically 1-2 seconds per block. Full mode analyzes everything upfront into a self-contained HTML file you can share.
 
+## Why local
+
+All AI processing runs through Ollama on your machine. Your code is never uploaded, transmitted, or stored anywhere external. No API keys, no accounts, no cloud services. This matters when you're working with proprietary code, client projects, or anything you can't share — codedocent works fully air-gapped. The `--no-ai` mode removes the AI dependency entirely while keeping the structural visualization and quality scoring.
+
 ## Supported languages
 
 Full AST parsing for Python and JavaScript/TypeScript (functions, classes, methods, imports). File-level detection for 23 extensions including C, C++, Rust, Go, Java, Ruby, PHP, Swift, Kotlin, Scala, HTML, CSS, and config formats.

{codedocent-0.3.0 → codedocent-0.4.0}/codedocent/quality.py

@@ -1,19 +1,9 @@
-"""Quality scoring: complexity, line counts, and parameter checks."""
+"""Quality scoring: complexity and parameter checks."""
 
 from __future__ import annotations
 
-import os
-
 from codedocent.parser import CodeNode
 
-# Quality scoring thresholds: (yellow_threshold, red_threshold)
-# yellow = "complex", red = "warning"
-LINE_THRESHOLDS: dict[str, tuple[int, int]] = {
-    "function": (50, 100),
-    "method": (50, 100),
-    "file": (500, 1000),
-    "class": (300, 600),
-}
 PARAM_THRESHOLD = 5
 
 
@@ -82,17 +72,17 @@ def _score_radon(node: CodeNode) -> tuple[str, str | None]:
         if blocks:
             worst = max(b.complexity for b in blocks)
             rank = cc_rank(worst)
-            if rank in ("A", "B"):
+            if rank in ("A", "B", "C"):
                 return "clean", None
-            if rank == "C":
+            if rank == "D":
                 return (
                     "complex",
-                    f"Moderate complexity (grade {rank},"
+                    f"High complexity (grade {rank},"
                     f" score {worst})",
                 )
             return (
                 "warning",
-                f"High complexity (grade {rank},"
+                f"Severe complexity (grade {rank},"
                 f" score {worst})",
             )
     except (ImportError, AttributeError, SyntaxError):  # nosec B110
@@ -101,44 +91,6 @@ def _score_radon(node: CodeNode) -> tuple[str, str | None]:
     return "clean", None
 
 
-def _is_exempt_file(node: CodeNode) -> bool:
-    """Check if a file node should skip line-count scoring.
-
-    HTML templates and test files are naturally long, so line count
-    does not indicate poor quality for these file types.
-    """
-    if node.node_type != "file":
-        return False
-    if node.language == "html":
-        return True
-    if node.language is None and node.name.endswith(".html"):
-        return True
-    if os.path.basename(node.name).startswith("test_"):
-        return True
-    return False
-
-
-def _score_line_count(node: CodeNode) -> tuple[str, str | None]:
-    """Score based on line-count thresholds (two-tier: yellow/red)."""
-    if _is_exempt_file(node):
-        return "clean", None
-    thresholds = LINE_THRESHOLDS.get(node.node_type)
-    if thresholds and node.line_count:
-        yellow, red = thresholds
-        if node.line_count > red:
-            return (
-                "warning",
-                f"This {node.node_type} is"
-                f" {node.line_count} lines long",
-            )
-        if node.line_count > yellow:
-            return (
-                "complex",
-                f"Long {node.node_type}: {node.line_count} lines",
-            )
-    return "clean", None
-
-
 def _score_param_count(node: CodeNode) -> tuple[str, str | None]:
     """Score based on parameter count."""
     if node.node_type in ("function", "method"):
@@ -162,7 +114,7 @@ def _score_quality(
     warnings: list[str] = []
     quality = "clean"
 
-    for scorer in (_score_radon, _score_line_count, _score_param_count):
+    for scorer in (_score_radon, _score_param_count):
         label, warning = scorer(node)
         quality = _worst_quality(quality, label)
         if warning:

{codedocent-0.3.0 → codedocent-0.4.0}/codedocent/server.py

@@ -21,6 +21,9 @@ from codedocent.renderer import LANGUAGE_COLORS, DEFAULT_COLOR, NODE_ICONS
 IDLE_TIMEOUT = 300  # 5 minutes
 IDLE_CHECK_INTERVAL = 30  # seconds
 MAX_BODY_SIZE = 10 * 1024 * 1024  # 10 MB
+_TEMPLATES_DIR = os.path.realpath(
+    os.path.join(os.path.dirname(__file__), "templates"),
+)
 
 
 def _node_to_dict(node: CodeNode, include_source: bool = False) -> dict:
@@ -179,18 +182,31 @@ def _execute_replace(  # pylint: disable=too-many-return-statements
     if node_id not in _Handler.node_lookup:
         return (404, {"success": False, "error": "Unknown node ID"})
     node = _Handler.node_lookup[node_id]
-    if node.node_type in ("directory", "file"):
+    if node.node_type == "directory":
         return (
             400,
             {"success": False,
-             "error": "Cannot replace directory/file blocks"},
+             "error": "Cannot replace directory blocks"},
         )
     new_source = body.get("source", "")
     if not isinstance(new_source, str):
         return (400, {"success": False, "error": "source must be a string"})
+    if len(new_source.encode("utf-8")) > 1_000_000:
+        return (
+            400,
+            {"success": False, "error": "Replacement too large (max 1MB)"},
+        )
     abs_path = _resolve_filepath(node, _Handler.cache_dir)
     real_path = os.path.realpath(abs_path)
     real_root = os.path.realpath(_Handler.cache_dir)
+    if real_path == _TEMPLATES_DIR or real_path.startswith(
+        _TEMPLATES_DIR + os.sep,
+    ):
+        return (
+            400,
+            {"success": False,
+             "error": "Cannot replace tool template files"},
+        )
     inside = real_path == real_root or real_path.startswith(
         real_root + os.sep,
     )

{codedocent-0.3.0 → codedocent-0.4.0}/codedocent/templates/interactive.html

@@ -671,18 +671,16 @@ function cdCreateCodeActions(bodyEl, nodeId, nodeType, nodeName, filepath, langu
     });
     actions.appendChild(btnAI);
 
-    if (nodeType === 'function' || nodeType === 'method' || nodeType === 'class') {
-        var btnReplace = document.createElement('button');
-        btnReplace.className = 'cd-code-btn';
-        btnReplace.textContent = 'Replace Code';
-        btnReplace.addEventListener('click', function(e) {
-            e.stopPropagation();
-            ensureSource(function(source) {
-                cdShowReplacePanel(bodyEl, nodeId, source, pre, btnShow);
-            });
+    var btnReplace = document.createElement('button');
+    btnReplace.className = 'cd-code-btn';
+    btnReplace.textContent = 'Replace Code';
+    btnReplace.addEventListener('click', function(e) {
+        e.stopPropagation();
+        ensureSource(function(source) {
+            cdShowReplacePanel(bodyEl, nodeId, source, pre, btnShow);
         });
-        actions.appendChild(btnReplace);
-    }
+    });
+    actions.appendChild(btnReplace);
 
     var childrenEl = bodyEl.querySelector('.cd-node__children');
     if (childrenEl) {

{codedocent-0.3.0 → codedocent-0.4.0}/codedocent.egg-info/PKG-INFO

@@ -1,20 +1,12 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.1
 Name: codedocent
-Version: 0.3.0
+Version: 0.4.0
 Summary: Code visualization for non-programmers
-License-Expression: MIT
+License: MIT
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-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
+License-File: LICENSE
 
 # codedocent
 
@@ -24,6 +16,21 @@ Dynamic: license-file
 
 A docent is a guide who explains things to people who aren't experts. Codedocent does that for code.
 
+## The problem
+
+You're staring at a codebase you didn't write — maybe thousands of files across dozens of directories — and you need to understand what it does. Reading every file isn't realistic. You need a way to visualize the code structure, get a high-level map of what's where, and drill into the parts that matter without losing context.
+
+Codedocent parses the codebase into a navigable, visual block structure and explains each piece in plain English. It's an AI code analysis tool that runs entirely on your machine — no API keys, no cloud, no data leaving your laptop. Point it at any codebase and get a structural overview you can explore interactively, understand quickly, and share as a static HTML file.
+
+## Who this is for
+
+- **Developers onboarding onto an unfamiliar codebase** — get oriented in minutes instead of days
+- **Non-programmers** (managers, designers, PMs) who need to understand what code does without reading it
+- **Solo developers inheriting legacy code** — map out the structure before making changes
+- **Code reviewers** who want a high-level overview before diving into details
+- **Security reviewers** who need a structural map of an application
+- **Students** learning to read and navigate real-world codebases
+
 ## What you see
 
 Nested, color-coded blocks representing directories, files, classes, and functions — the entire structure of a codebase laid out visually. Each block shows a plain English summary, a pseudocode translation, and quality warnings (green/yellow/red). Click any block to drill down; breadcrumbs navigate you back up. You can export code from any block or paste replacement code back into the source file. All AI runs locally through Ollama — nothing leaves your machine.
@@ -49,6 +56,10 @@ codedocent --gui                   # graphical launcher
 
 Parses code structure with tree-sitter, scores quality with static analysis, and sends individual blocks to a local Ollama model for plain English summaries and pseudocode. Interactive mode analyzes on click — typically 1-2 seconds per block. Full mode analyzes everything upfront into a self-contained HTML file you can share.
 
+## Why local
+
+All AI processing runs through Ollama on your machine. Your code is never uploaded, transmitted, or stored anywhere external. No API keys, no accounts, no cloud services. This matters when you're working with proprietary code, client projects, or anything you can't share — codedocent works fully air-gapped. The `--no-ai` mode removes the AI dependency entirely while keeping the structural visualization and quality scoring.
+
 ## Supported languages
 
 Full AST parsing for Python and JavaScript/TypeScript (functions, classes, methods, imports). File-level detection for 23 extensions including C, C++, Rust, Go, Java, Ruby, PHP, Swift, Kotlin, Scala, HTML, CSS, and config formats.

{codedocent-0.3.0 → codedocent-0.4.0}/pyproject.toml

@@ -4,9 +4,9 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codedocent"
-version = "0.3.0"
+version = "0.4.0"
 description = "Code visualization for non-programmers"
-license = "MIT"
+license = {text = "MIT"}
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [

{codedocent-0.3.0 → codedocent-0.4.0}/tests/test_analyzer.py

@@ -157,8 +157,8 @@ def test_quality_complex_branchy():
 
     node = _make_func_node(name="decide", source=source)
     quality, warnings = _score_quality(node)
-    assert quality in ("complex", "warning")
-    assert warnings is not None
+    assert quality == "clean"
+    assert warnings is None
 
 
 def test_directory_summary_no_ai():
@@ -243,22 +243,6 @@ def test_strip_think_tags():
     assert "SUMMARY: hello" in result
 
 
-def test_long_function_warning():
-    from codedocent.quality import _score_quality
-
-    # 56-line function
-    lines = ["def long_func():"]
-    for i in range(55):
-        lines.append(f"    x = {i}")
-    source = "\n".join(lines) + "\n"
-
-    node = _make_func_node(name="long_func", source=source)
-    node.line_count = 56
-    quality, warnings = _score_quality(node)
-    assert warnings is not None
-    assert any("Long function" in w for w in warnings)
-
-
 def test_many_params_warning():
     from codedocent.quality import _score_quality
 
@@ -410,93 +394,6 @@ def test_garbage_response_fallback(mock_ollama, tmp_path):
 # ---------------------------------------------------------------------------
 
 
-def test_quality_function_yellow_tier():
-    from codedocent.quality import _score_quality
-
-    # 60-line function (above 50 yellow, below 100 red)
-    lines = ["def long_func():"]
-    for i in range(59):
-        lines.append(f"    x = {i}")
-    source = "\n".join(lines) + "\n"
-
-    node = _make_func_node(name="long_func", source=source)
-    node.line_count = 60
-    quality, warnings = _score_quality(node)
-    assert quality == "complex"
-    assert warnings is not None
-    assert any("60 lines" in w for w in warnings)
-
-
-def test_quality_function_red_tier():
-    from codedocent.quality import _score_quality
-
-    # 110-line function (above 100 red)
-    lines = ["def very_long_func():"]
-    for i in range(109):
-        lines.append(f"    x = {i}")
-    source = "\n".join(lines) + "\n"
-
-    node = _make_func_node(name="very_long_func", source=source)
-    node.line_count = 110
-    quality, warnings = _score_quality(node)
-    assert quality == "warning"
-    assert warnings is not None
-    assert any("110 lines" in w for w in warnings)
-
-
-def test_quality_file_yellow_tier():
-    from codedocent.quality import _score_quality
-
-    # 550-line file (above 500 yellow, below 1000 red)
-    lines = [f"x_{i} = {i}" for i in range(550)]
-    source = "\n".join(lines) + "\n"
-
-    node = _make_file_node(name="big.py", source=source)
-    node.line_count = 550
-    quality, warnings = _score_quality(node)
-    assert quality == "complex"
-    assert warnings is not None
-    assert any("550 lines" in w for w in warnings)
-
-
-def test_quality_file_red_tier():
-    from codedocent.quality import _score_quality
-
-    # 1100-line file (above 1000 red)
-    lines = [f"x_{i} = {i}" for i in range(1100)]
-    source = "\n".join(lines) + "\n"
-
-    node = _make_file_node(name="huge.py", source=source)
-    node.line_count = 1100
-    quality, warnings = _score_quality(node)
-    assert quality == "warning"
-    assert warnings is not None
-    assert any("1100 lines" in w for w in warnings)
-
-
-def test_quality_class_yellow_tier():
-    from codedocent.quality import _score_quality
-
-    # 311-line class (above 300 yellow, below 600 red)
-    lines = ["class BigClass:"]
-    for i in range(310):
-        lines.append(f"    x_{i} = {i}")
-    source = "\n".join(lines) + "\n"
-
-    node = CodeNode(
-        name="BigClass",
-        node_type="class",
-        language="python",
-        filepath="test.py",
-        start_line=1,
-        end_line=311,
-        source=source,
-        line_count=311,
-    )
-    quality, warnings = _score_quality(node)
-    assert quality == "complex"
-
-
 def test_quality_rollup_to_file():
     from codedocent.quality import _rollup_quality
 
@@ -544,42 +441,6 @@ def test_quality_directory_returns_none():
     assert warnings is None
 
 
-# ---------------------------------------------------------------------------
-# Phase 8: Exempt HTML templates and test files from line-count scoring
-# ---------------------------------------------------------------------------
-
-
-def test_quality_html_file_exempt_from_line_count():
-    from codedocent.quality import _score_quality
-
-    node = _make_file_node(name="base.html", lang="html", source="<div></div>\n")
-    node.line_count = 1500
-    quality, warnings = _score_quality(node)
-    assert quality == "clean"
-    assert warnings is None
-
-
-def test_quality_test_file_exempt_from_line_count():
-    from codedocent.quality import _score_quality
-
-    node = _make_file_node(name="test_foo.py", lang="python", source="x = 1\n")
-    node.line_count = 600
-    quality, warnings = _score_quality(node)
-    assert quality == "clean"
-    assert warnings is None
-
-
-def test_quality_regular_python_file_still_scored():
-    from codedocent.quality import _score_quality
-
-    node = _make_file_node(name="app.py", lang="python", source="x = 1\n")
-    node.line_count = 600
-    quality, warnings = _score_quality(node)
-    assert quality == "complex"
-    assert warnings is not None
-    assert any("600 lines" in w for w in warnings)
-
-
 # ---------------------------------------------------------------------------
 # Batch 2: Security audit fixes 8-16
 # ---------------------------------------------------------------------------
@@ -655,3 +516,69 @@ def test_radon_syntax_error_returns_clean():
     )
     quality, warnings = _score_quality(node)
     assert quality == "clean"
+
+
+# ---------------------------------------------------------------------------
+# Security fixes: replace endpoint guards
+# ---------------------------------------------------------------------------
+
+
+def test_replace_rejects_oversized_payload():
+    """Fix 1: payloads over 1 MB are rejected with 400 (byte-size)."""
+    from codedocent.server import _execute_replace, _Handler
+
+    node = _make_func_node(name="target", source="def target():\n    pass\n")
+    node.node_id = "test_node_001"
+    _Handler.node_lookup = {"test_node_001": node}
+    _Handler.cache_dir = "/tmp/test_proj"
+
+    giant = "x" * 1_000_001
+    status, result = _execute_replace("test_node_001", {"source": giant})
+    assert status == 400
+    assert "too large" in result["error"]
+
+
+def test_replace_rejects_template_filepath():
+    """Fix 3: files inside codedocent's templates dir are rejected."""
+    from codedocent.server import _execute_replace, _Handler, _TEMPLATES_DIR
+
+    for name in ("interactive.html", "base.html"):
+        tmpl_path = os.path.join(_TEMPLATES_DIR, name)
+        node = _make_file_node(name=name, source="<html></html>\n")
+        node.filepath = tmpl_path
+        node.node_id = "tmpl_node_001"
+        _Handler.node_lookup = {"tmpl_node_001": node}
+        _Handler.cache_dir = _TEMPLATES_DIR
+
+        status, result = _execute_replace(
+            "tmpl_node_001", {"source": "<p>hacked</p>"},
+        )
+        assert status == 400
+        assert "Cannot replace tool template files" in result["error"]
+
+
+def test_replace_accepts_file_node(tmp_path):
+    """Happy-path: file-level replace succeeds end-to-end."""
+    from codedocent.server import _execute_replace, _Handler
+
+    original = "x = 1\ny = 2\n"
+    replacement = "x = 10\ny = 20\nz = 30\n"
+
+    target = tmp_path / "test.py"
+    target.write_text(original, encoding="utf-8")
+
+    node = _make_file_node(name="test.py", source=original)
+    node.filepath = str(target)
+    node.node_id = "file_node_001"
+    _Handler.node_lookup = {"file_node_001": node}
+    _Handler.cache_dir = str(tmp_path)
+    _Handler.root = _make_dir_node(
+        name="proj", children=[node], filepath=str(tmp_path),
+    )
+
+    status, result = _execute_replace(
+        "file_node_001", {"source": replacement},
+    )
+    assert status == 200
+    assert result["success"] is True
+    assert target.read_text(encoding="utf-8") == replacement

{codedocent-0.3.0 → codedocent-0.4.0}/codedocent.egg-info/requires.txt

@@ -1,9 +1,9 @@
-tree-sitter>=0.23
-tree-sitter-language-pack>=0.13
-radon>=6.0
-pathspec>=0.11
 jinja2>=3.1
 ollama>=0.4
+pathspec>=0.11
+radon>=6.0
+tree-sitter-language-pack>=0.13
+tree-sitter>=0.23
 
 [dev]
 pytest>=7.0