codedocent 1.0.2__tar.gz → 1.0.3__tar.gz

{codedocent-1.0.2/codedocent.egg-info → codedocent-1.0.3}/PKG-INFO

@@ -1,12 +1,20 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: codedocent
-Version: 1.0.2
+Version: 1.0.3
 Summary: Code visualization for non-programmers
 License: MIT
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Provides-Extra: dev
 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
 
@@ -87,6 +95,16 @@ codedocent /path/to/code --cloud groq      # use Groq
 codedocent /path/to/code --cloud custom --endpoint https://my-llm/v1/chat/completions
 ```
 
+## GUI launcher
+
+![GUI launcher with folder picker, AI backend toggle, model dropdown, and mode selector](https://raw.githubusercontent.com/clanker-lover/codedocent/main/docs/screenshots/gui-launcher.png)
+
+If you prefer clicking over typing, `codedocent --gui` opens a graphical launcher. Pick a folder, choose your AI backend (cloud or local Ollama), select a model, and choose a mode — Interactive, Full export, Text tree, or Architecture. Hit Go.
+
+```bash
+codedocent --gui
+```
+
 ## How it works
 
 Parses code structure with tree-sitter, scores quality with static analysis, and sends individual blocks to a cloud AI provider or 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. Architecture mode builds a dependency graph from import statements and renders it as a zoomable D3 visualization.

codedocent-1.0.2/PKG-INFO → codedocent-1.0.3/README.md

@@ -1,13 +1,3 @@
-Metadata-Version: 2.1
-Name: codedocent
-Version: 1.0.2
-Summary: Code visualization for non-programmers
-License: MIT
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Provides-Extra: dev
-License-File: LICENSE
-
 # codedocent
 
 **Code visualization for non-programmers.**
@@ -87,6 +77,16 @@ codedocent /path/to/code --cloud groq      # use Groq
 codedocent /path/to/code --cloud custom --endpoint https://my-llm/v1/chat/completions
 ```
 
+## GUI launcher
+
+![GUI launcher with folder picker, AI backend toggle, model dropdown, and mode selector](https://raw.githubusercontent.com/clanker-lover/codedocent/main/docs/screenshots/gui-launcher.png)
+
+If you prefer clicking over typing, `codedocent --gui` opens a graphical launcher. Pick a folder, choose your AI backend (cloud or local Ollama), select a model, and choose a mode — Interactive, Full export, Text tree, or Architecture. Hit Go.
+
+```bash
+codedocent --gui
+```
+
 ## How it works
 
 Parses code structure with tree-sitter, scores quality with static analysis, and sends individual blocks to a cloud AI provider or 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. Architecture mode builds a dependency graph from import statements and renders it as a zoomable D3 visualization.

{codedocent-1.0.2 → codedocent-1.0.3}/codedocent/graph.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import ast
 import os
 import sys
 from dataclasses import dataclass, field
@@ -389,9 +390,11 @@ def get_module_graph(root: CodeNode, project_root: str) -> dict:
                 imp, fnode.filepath, project_files, project_modules_top,
             )
             if resolved is None:
-                # External dependency
+                # External dependency (skip stdlib)
                 if not imp.is_relative:
-                    external_deps.add(imp.module.split(".")[0])
+                    top = imp.module.split(".")[0]
+                    if top not in _get_stdlib_modules():
+                        external_deps.add(top)
                 continue
             if resolved != fnode.filepath:
                 key = (fnode.filepath, resolved)
@@ -582,6 +585,30 @@ def get_file_dependencies(
     }
 
 
+# ---------------------------------------------------------------------------
+# Docstring extraction
+# ---------------------------------------------------------------------------
+
+
+def _extract_module_docstring(source: str) -> str:
+    """Extract the module-level docstring from Python source.
+
+    Returns the first line of the docstring, truncated to 80 characters.
+    Returns an empty string if no docstring is found.
+    """
+    try:
+        tree = ast.parse(source)
+        docstring = ast.get_docstring(tree)
+        if docstring:
+            first_line = docstring.split("\n")[0].strip()
+            if len(first_line) > 80:
+                return first_line[:77] + "..."
+            return first_line
+    except SyntaxError:
+        pass
+    return ""
+
+
 # ---------------------------------------------------------------------------
 # Context export
 # ---------------------------------------------------------------------------
@@ -637,20 +664,33 @@ def export_module_md(
     if graph is None:
         return None
 
+    # Build filepath -> docstring lookup for Purpose column
+    docstrings: dict[str, str] = {}
+    for node in graph["nodes"]:
+        if node["node_type"] == "external":
+            continue
+        fnode = _find_file_node(root, node["id"])
+        if fnode and fnode.source and fnode.language == "python":
+            docstrings[node["id"]] = _extract_module_docstring(fnode.source)
+
     mod_name = os.path.basename(module_path)
     lines = [f"# Module: {mod_name}\n"]
 
     # Files table
     lines.append("## Files\n")
-    lines.append("| File | Lines | Quality |")
-    lines.append("|------|-------|---------|")
+    lines.append("| File | Lines | Quality | Purpose |")
+    lines.append("|------|-------|---------|---------|")
     for node in graph["nodes"]:
         if node["node_type"] == "external":
             continue
         quality_label = {"clean": "OK", "complex": "Complex", "warning": "Warning"}.get(
             node["quality"], "OK"
         )
-        lines.append(f"| {node['name']} | {node['line_count']} | {quality_label} |")
+        purpose = docstrings.get(node["id"], "") or "\u2014"
+        lines.append(
+            f"| {node['name']} | {node['line_count']} "
+            f"| {quality_label} | {purpose} |"
+        )
 
     # Internal dependencies
     internal_edges = [

codedocent-1.0.2/README.md → codedocent-1.0.3/codedocent.egg-info/PKG-INFO

@@ -1,3 +1,21 @@
+Metadata-Version: 2.4
+Name: codedocent
+Version: 1.0.3
+Summary: Code visualization for non-programmers
+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
+
 # codedocent
 
 **Code visualization for non-programmers.**
@@ -77,6 +95,16 @@ codedocent /path/to/code --cloud groq      # use Groq
 codedocent /path/to/code --cloud custom --endpoint https://my-llm/v1/chat/completions
 ```
 
+## GUI launcher
+
+![GUI launcher with folder picker, AI backend toggle, model dropdown, and mode selector](https://raw.githubusercontent.com/clanker-lover/codedocent/main/docs/screenshots/gui-launcher.png)
+
+If you prefer clicking over typing, `codedocent --gui` opens a graphical launcher. Pick a folder, choose your AI backend (cloud or local Ollama), select a model, and choose a mode — Interactive, Full export, Text tree, or Architecture. Hit Go.
+
+```bash
+codedocent --gui
+```
+
 ## How it works
 
 Parses code structure with tree-sitter, scores quality with static analysis, and sends individual blocks to a cloud AI provider or 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. Architecture mode builds a dependency graph from import statements and renders it as a zoomable D3 visualization.

{codedocent-1.0.2 → codedocent-1.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codedocent"
-version = "1.0.2"
+version = "1.0.3"
 description = "Code visualization for non-programmers"
 license = {text = "MIT"}
 readme = "README.md"

{codedocent-1.0.2 → codedocent-1.0.3}/tests/test_graph.py

@@ -9,6 +9,7 @@ import pytest
 from codedocent.graph import (
     ImportInfo,
     _extract_full_imports,
+    _extract_module_docstring,
     _resolve_import,
     _find_modules,
     _aggregate_quality,
@@ -408,6 +409,14 @@ class TestGetModuleGraph:
         graph = get_module_graph(root, "/tmp/project")
         assert "pytest" in graph["external"]
 
+    def test_stdlib_excluded_from_external_deps(self):
+        """Stdlib modules should not appear in external dependencies."""
+        root = _make_multi_module_tree()
+        graph = get_module_graph(root, "/tmp/project")
+        stdlib_names = {"os", "sys", "json", "pathlib", "collections", "re"}
+        for dep in graph["external"]:
+            assert dep not in stdlib_names, f"stdlib module '{dep}' in external deps"
+
     def test_module_stats(self):
         root = _make_multi_module_tree()
         graph = get_module_graph(root, "/tmp/project")
@@ -485,6 +494,45 @@ class TestGetFileGraph:
                 assert gn["node_id"] in lookup
 
 
+# ---------------------------------------------------------------------------
+# Docstring extraction tests
+# ---------------------------------------------------------------------------
+
+
+class TestExtractModuleDocstring:
+    """Tests for _extract_module_docstring."""
+
+    def test_extracts_triple_double_quote_docstring(self):
+        source = '"""Parse source files into a tree."""\nimport os\n'
+        assert _extract_module_docstring(source) == "Parse source files into a tree."
+
+    def test_extracts_triple_single_quote_docstring(self):
+        source = "'''Helper utilities for scanning.'''\nimport sys\n"
+        assert _extract_module_docstring(source) == "Helper utilities for scanning."
+
+    def test_returns_empty_for_no_docstring(self):
+        source = "import os\nx = 1\n"
+        assert _extract_module_docstring(source) == ""
+
+    def test_returns_first_line_of_multiline(self):
+        source = '"""First line.\n\nMore detail here.\n"""\nimport os\n'
+        assert _extract_module_docstring(source) == "First line."
+
+    def test_truncates_long_docstring(self):
+        long_text = "A" * 100
+        source = f'"""{long_text}"""\n'
+        result = _extract_module_docstring(source)
+        assert len(result) <= 80
+        assert result.endswith("...")
+
+    def test_returns_empty_for_syntax_error(self):
+        source = "def foo(:\n"
+        assert _extract_module_docstring(source) == ""
+
+    def test_returns_empty_for_empty_source(self):
+        assert _extract_module_docstring("") == ""
+
+
 # ---------------------------------------------------------------------------
 # Context export tests
 # ---------------------------------------------------------------------------
@@ -511,6 +559,16 @@ class TestExportArchitectureMd:
         md = export_architecture_md(root, "/tmp/project")
         assert "pytest" in md
 
+    def test_excludes_stdlib_from_external_deps(self):
+        """Stdlib modules like os, sys should not appear in External Dependencies."""
+        root = _make_multi_module_tree()
+        md = export_architecture_md(root, "/tmp/project")
+        # The test tree includes files that import os/sys but those are stdlib
+        for line in md.splitlines():
+            if line.startswith("- "):
+                dep = line[2:].strip()
+                assert dep not in ("os", "sys", "json", "pathlib")
+
 
 class TestExportModuleMd:
     """Tests for export_module_md."""
@@ -522,6 +580,12 @@ class TestExportModuleMd:
         assert "# Module: codedocent" in md
         assert "## Files" in md
 
+    def test_contains_purpose_column(self):
+        root = _make_multi_module_tree()
+        md = export_module_md(root, "/tmp/project", "codedocent")
+        assert md is not None
+        assert "| File | Lines | Quality | Purpose |" in md
+
     def test_returns_none_for_invalid_module(self):
         root = _make_multi_module_tree()
         result = export_module_md(root, "/tmp/project", "nonexistent")
@@ -534,6 +598,42 @@ class TestExportModuleMd:
         assert "parser.py" in md
         assert "server.py" in md
 
+    def test_shows_docstring_in_purpose(self):
+        """Files with module docstrings should show them in the Purpose column."""
+        init_node = _make_file_node(
+            name="__init__.py",
+            filepath="mypkg/__init__.py",
+            source='"""My package init."""\n',
+            node_id="init",
+        )
+        core_node = _make_file_node(
+            name="core.py",
+            filepath="mypkg/core.py",
+            source='"""Core business logic for the app."""\nimport os\nx = 1\n',
+            node_id="core",
+        )
+        nodc_node = _make_file_node(
+            name="utils.py",
+            filepath="mypkg/utils.py",
+            source="import os\nx = 1\n",
+            node_id="utils",
+        )
+        dir_node = _make_dir_node(
+            name="mypkg",
+            children=[init_node, core_node, nodc_node],
+            filepath="/tmp/project/mypkg",
+        )
+        root = _make_dir_node(
+            name="project",
+            children=[dir_node],
+            filepath="/tmp/project",
+        )
+        md = export_module_md(root, "/tmp/project", "mypkg")
+        assert md is not None
+        assert "Core business logic for the app" in md
+        # utils.py has no docstring -> em dash
+        assert "\u2014" in md
+
 
 # ---------------------------------------------------------------------------
 # File dependency lookup tests

{codedocent-1.0.2 → codedocent-1.0.3}/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