codebread 1.0.2__py3-none-any.whl → 1.0.4__py3-none-any.whl

codebread/__init__.py

@@ -1,3 +1,36 @@
 """CodeBread — slice open a codebase and see its internal structure."""
+from __future__ import annotations
 
-__version__ = "1.0.2"
+import os
+
+
+def _read_version() -> str:
+    """Single source of truth: pyproject.toml's [project] version.
+
+    Installed packages get it from the wheel's own metadata (always in
+    sync with what was actually published). Running from a source
+    checkout without installing falls back to reading pyproject.toml
+    directly — no parser dependency needed for one `version = "..."`
+    line, keeping the zero-dependency promise intact.
+    """
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+        try:
+            return version("codebread")
+        except PackageNotFoundError:
+            pass
+    except ImportError:
+        pass
+    try:
+        root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        with open(os.path.join(root, "pyproject.toml"), encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line.startswith("version"):
+                    return line.split("=", 1)[1].strip().strip("\"'")
+    except OSError:
+        pass
+    return "0.0.0+unknown"
+
+
+__version__ = _read_version()

codebread/server.py

@@ -7,7 +7,7 @@ import socket
 import threading
 import webbrowser
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
-from typing import Dict
+from typing import Dict, Optional
 
 WEB_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "web")
 WEB_ROOT = os.path.realpath(WEB_DIR)
@@ -21,7 +21,30 @@ MIME = {".html": "text/html; charset=utf-8",
         ".ico": "image/x-icon"}
 
 
-def _free_port(preferred: int) -> int:
+def safe_web_path(rel: str) -> Optional[str]:
+    """Resolve a request path against WEB_DIR and return it only if the
+    *resolved* result is still inside WEB_DIR, else None.
+
+    String-prefix checks on `rel` alone aren't enough: on Windows,
+    os.path.join(WEB_DIR, "C:/some/file") silently discards WEB_DIR because
+    the second argument is drive-absolute, which would otherwise let a
+    request read any file on disk. Kept as a standalone function so the
+    traversal guard has a direct regression test, not just cli/browser use.
+    """
+    full = os.path.realpath(os.path.join(WEB_DIR, rel))
+    try:
+        inside = os.path.commonpath([full, WEB_ROOT]) == WEB_ROOT
+    except ValueError:
+        inside = False  # e.g. different drives on Windows
+    return full if inside else None
+
+
+def _free_port(preferred: int) -> Optional[int]:
+    """Find a bindable port near `preferred`, or None if none was free.
+    `preferred == 0` means "let the OS pick" and always succeeds — must
+    return that as a distinct value from "no port found", since 0 is a
+    falsy int and `if not port:` would otherwise treat a successful
+    OS-assigned bind as failure."""
     for port in [preferred] + list(range(preferred + 1, preferred + 30)):
         with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
             try:
@@ -29,12 +52,10 @@ def _free_port(preferred: int) -> int:
                 return port
             except OSError:
                 continue
-    return 0
+    return None
 
 
-def serve(graph: Dict, port: int = 8137, open_browser: bool = True) -> None:
-    data_bytes = json.dumps(graph, ensure_ascii=False).encode("utf-8")
-
+def _make_handler(data_bytes: bytes):
     class Handler(BaseHTTPRequestHandler):
         def do_GET(self):
             path = self.path.split("?")[0]
@@ -46,17 +67,8 @@ def serve(graph: Dict, port: int = 8137, open_browser: bool = True) -> None:
                 self._file(path.lstrip("/"))
 
         def _file(self, rel: str):
-            # Resolve against WEB_DIR and verify the *result* is still inside
-            # it. String-prefix checks on `rel` alone aren't enough: on
-            # Windows, os.path.join(WEB_DIR, "C:/some/file") silently
-            # discards WEB_DIR because the second argument is drive-absolute,
-            # which would otherwise let a request read any file on disk.
-            full = os.path.realpath(os.path.join(WEB_DIR, rel))
-            try:
-                inside = os.path.commonpath([full, WEB_ROOT]) == WEB_ROOT
-            except ValueError:
-                inside = False  # e.g. different drives on Windows
-            if not inside:
+            full = safe_web_path(rel)
+            if full is None:
                 self.send_error(403)
                 return
             if not os.path.isfile(full):
@@ -78,12 +90,26 @@ def serve(graph: Dict, port: int = 8137, open_browser: bool = True) -> None:
         def log_message(self, fmt, *args):  # keep the console clean
             pass
 
-    port = _free_port(port)
-    if not port:
+    return Handler
+
+
+def build_server(graph: Dict, port: int = 8137) -> Optional[ThreadingHTTPServer]:
+    """Bind a ready-to-serve ThreadingHTTPServer, or None if no port was
+    free. Split out from `serve()` so tests (and other embedders) can start
+    and cleanly `.shutdown()` a server instead of blocking forever."""
+    data_bytes = json.dumps(graph, ensure_ascii=False).encode("utf-8")
+    bound_port = _free_port(port)
+    if bound_port is None:
+        return None
+    return ThreadingHTTPServer(("127.0.0.1", bound_port), _make_handler(data_bytes))
+
+
+def serve(graph: Dict, port: int = 8137, open_browser: bool = True) -> None:
+    server = build_server(graph, port)
+    if server is None:
         print("[codebread] No free port found near 8137 — aborting serve.")
         return
-    server = ThreadingHTTPServer(("127.0.0.1", port), Handler)
-    url = f"http://127.0.0.1:{port}/"
+    url = f"http://127.0.0.1:{server.server_port}/"
     print(f"[codebread] Serving at {url}  (Ctrl+C to stop)")
     if open_browser:
         threading.Timer(0.4, lambda: webbrowser.open(url)).start()

codebread/web/app.js

@@ -348,36 +348,61 @@ function visibleEdges() {
 }
 
 /* ---------------- DOM (re)build ---------------- */
+/* Incremental: only the nodes/edges that actually entered or left the
+   visible set touch the DOM. A full teardown+rebuild here would mean every
+   single click in a large, densely-linked graph re-creates *everything*
+   already on screen (elements + listeners) just to add one more node —
+   that's the "too many links = lag" complaint this replaced. */
 function rebuild() {
-  nodesG.innerHTML = ""; edgesG.innerHTML = "";
-  S.elNodes.clear(); S.elEdges.clear();
-  S.drawnEdges = [];
+  const newEdges = visibleEdges();
+  const newEdgeKeys = new Set(newEdges.map(edgeKey));
 
-  for (const e of visibleEdges()) {
+  for (const { key } of S.drawnEdges) {
+    if (newEdgeKeys.has(key)) continue;
+    const els = S.elEdges.get(key);
+    if (!els) continue;
+    els.vis.remove(); els.hit.remove();
+    S.elEdges.delete(key);
+  }
+
+  const drawnEdges = [];
+  for (const e of newEdges) {
     const key = edgeKey(e);
-    const vis = document.createElementNS(SVGNS, "path");
-    vis.setAttribute("class", "edge k-" + e.kind + (e.cycle ? " cycle" : ""));
-    const hit = document.createElementNS(SVGNS, "path");
-    hit.setAttribute("class", "edge-hit");
-    hit.addEventListener("mousemove", (ev) => showEdgeTooltip(e, ev));
-    hit.addEventListener("mouseleave", hideTooltip);
-    hit.addEventListener("contextmenu", (ev) => {
-      ev.preventDefault(); ev.stopPropagation();
-      onEdgeContextMenu(e, ev);
-    });
-    edgesG.appendChild(vis); edgesG.appendChild(hit);
-    S.elEdges.set(key, { vis, hit });
-    S.drawnEdges.push({ edge: e, key });
+    let els = S.elEdges.get(key);
+    if (!els) {
+      const vis = document.createElementNS(SVGNS, "path");
+      vis.setAttribute("class", "edge k-" + e.kind + (e.cycle ? " cycle" : ""));
+      const hit = document.createElementNS(SVGNS, "path");
+      hit.setAttribute("class", "edge-hit");
+      hit.addEventListener("mousemove", (ev) => showEdgeTooltip(e, ev));
+      hit.addEventListener("mouseleave", hideTooltip);
+      hit.addEventListener("contextmenu", (ev) => {
+        ev.preventDefault(); ev.stopPropagation();
+        onEdgeContextMenu(e, ev);
+      });
+      edgesG.appendChild(vis); edgesG.appendChild(hit);
+      els = { vis, hit };
+      S.elEdges.set(key, els);
+    }
+    drawnEdges.push({ edge: e, key });
   }
+  S.drawnEdges = drawnEdges;
 
+  for (const [id, g] of S.elNodes) {
+    const n = S.nodesById.get(id);
+    if (S.visible.has(id) && n && passesFilter(n)) continue;
+    g.remove();
+    S.elNodes.delete(id);
+  }
   for (const id of S.visible) {
     const n = S.nodesById.get(id);
-    if (!n || !passesFilter(n)) continue;
+    if (!n || !passesFilter(n) || S.elNodes.has(id)) continue;
     ensurePos(id);
     const g = makeNodeEl(n);
     nodesG.appendChild(g);
     S.elNodes.set(id, g);
   }
+
   applyHighlight();
   updatePositions();
   renderMinimap();

{codebread-1.0.2.dist-info → codebread-1.0.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebread
-Version: 1.0.2
+Version: 1.0.4
 Summary: Interactive codebase analyzer & visualizer — slice open a project and see how it's wired together.
 Author: Danial Irsyad
 License: MIT
@@ -10,6 +10,8 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: full
 Requires-Dist: pathspec>=0.11; extra == "full"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
 Dynamic: license-file
 
 <p align="center">
@@ -22,7 +24,8 @@ Dynamic: license-file
 </p>
 
 <p align="center">
-  <img alt="version" src="https://img.shields.io/badge/version-1.0.2-2dd4bf">
+  <a href="https://pypi.org/project/codebread/"><img alt="PyPI" src="https://img.shields.io/pypi/v/codebread?color=2dd4bf&label=version"></a>
+  <a href="https://github.com/honow48-tech/CodeBread/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/honow48-tech/CodeBread/actions/workflows/ci.yml/badge.svg"></a>
   <img alt="python" src="https://img.shields.io/badge/python-3.9%2B-0284c7">
   <img alt="deps" src="https://img.shields.io/badge/required%20dependencies-none-2dd4bf">
   <img alt="license" src="https://img.shields.io/badge/license-MIT-8b5cf6">
@@ -164,14 +167,38 @@ the map already scanned.
 
 ## Language support
 
-| Language | Parser | Extracted |
-|---|---|---|
-| Python | stdlib `ast` (precise) | functions, classes, params/annotations, docstrings, Flask/FastAPI/Django routes, SQLAlchemy/Django models, raw SQL, `requests`/`httpx` calls |
-| JavaScript / TypeScript / JSX / TSX / Vue / Svelte | structural regex + brace matching | functions, arrow fns, classes, Express/Nest/Fastify routes, `fetch`/`axios` calls, Mongoose/Prisma/Sequelize/Knex/TypeORM, raw SQL |
-| Java, C#, Go, PHP, Ruby | structural regex | functions/methods, classes, Spring/ASP.NET/Laravel/Rails/Gin routes, raw SQL |
-| SQL | regex | `CREATE TABLE` schemas with columns |
-| Config (`.env`, json/yaml/toml/ini, settings.py…) | key scan | DB connection settings — **credentials always masked** |
-| Anything else (Rust, Kotlin, Swift, C/C++…) | — | shown in the UI as "⚠ Unsupported — parsing skipped", never silently dropped |
+Parser used per language, then exactly what gets extracted — checked feature
+by feature against the actual parser code, not a marketing table:
+
+| Language | Parser | Functions / methods | Classes / structs | Backend routes | Outgoing API calls | ORM / DB models | Raw SQL | Call graph | Page-nav links |
+|---|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| Python | stdlib `ast` (precise) | ✅ | ✅ | ✅ Flask / FastAPI / Django | ✅ `requests` / `httpx` / `aiohttp` / `urllib` | ✅ SQLAlchemy / Django / peewee / tortoise | ✅ | ✅ | – |
+| JavaScript / TypeScript / JSX / TSX | regex + brace matching | ✅ | ✅ | ✅ Express / Fastify / Koa / NestJS | ✅ `fetch` / `axios` | ✅ Mongoose / Prisma / Sequelize / Knex / TypeORM | ✅ | ✅ | – |
+| Vue / Svelte | regex, `<script>` block only¹ | ✅ | ✅ | ✅ (same as JS) | ✅ (same as JS) | ✅ (same as JS) | ✅ | ✅ | – |
+| Java | regex | ✅ | ✅ | ✅ Spring `@*Mapping` | – | – | ✅ | ✅ | – |
+| C# | regex | ✅ | ✅ | ✅ ASP.NET `[Http*]` | – | – | ✅ | ✅ | – |
+| Go | regex | ✅ | ✅ (structs) | ✅ Gin / net-http style | – | – | ✅ | ✅ | – |
+| PHP | regex | ✅ | ✅ | ✅ Laravel `Route::` | – | – | ✅ | ✅ | ✅ |
+| Ruby | regex | ✅ | ✅ | ✅ Rails / Sinatra | – | – | ✅ | ✅ | ✅ |
+| SQL (`.sql` files) | regex | – | – | – | – | ✅ `CREATE TABLE` schemas + columns | ✅ | – | – |
+| Config (`.env`, json/yaml/toml/ini/xml…)² | key scan | – | – | – | – | – | – | – | – |
+| Anything else (Rust, Kotlin, Swift, C/C++, Scala, Elixir, Erlang, Lua, R, Perl, Dart, Zig…) | – | – | – | – | – | – | – | – | – |
+
+Unsupported languages still show up in the Explorer tree with an
+"⚠ Unsupported — parsing skipped" badge — never silently dropped — they just
+have no functions/edges to draw.
+
+¹ Vue/Svelte only parse the `<script>` block — template-only bindings
+(`@click`, `v-on`, Svelte reactive markup) aren't extracted.
+² Config-format files get a DB-connection-settings scan instead of code
+extraction — **credentials always masked**, see [export.py](codebread/export.py)-embedded
+source too. Files like `settings.py` or `config.js` are parsed as their real
+language (full extraction above), not this bucket — only non-code formats
+(json/yaml/toml/ini/`.env`/xml/properties) land here.
+
+Only Python's `ast`-based parser captures real parameter type annotations,
+return types, and docstrings — every regex-based parser above extracts
+parameter *names* only.
 
 ## How it classifies layers
 
@@ -214,12 +241,30 @@ codebread/
   server.py                ← stdlib local web server
   export.py                ← JSON + single-file HTML export
   web/                     ← the UI (vanilla JS + SVG, zero dependencies)
+tests/                     ← pytest suite + per-language fixture corpus
 assets/                    ← logo (.svg source + .png for the README —
                                GitHub blocks same-repo SVG <img> embeds)
 ```
 
 ---
 
+## Testing
+
+```bash
+pip install -e ".[full,test]"
+pytest -q
+```
+
+The suite covers every parser (a small fixture file per language under
+`tests/fixtures/`), the connection/graph builder (call resolution,
+API↔route matching, DB edges, orphan + cycle detection), the scanner
+(`.gitignore` handling, language detection), the local server (including a
+regression test for the path-traversal fix), and an end-to-end analyze
+pass — including a regression test that secrets in scanned `.env` files
+never leak into an exported graph. CI (`.github/workflows/ci.yml`) runs it
+on every push/PR across the minimum and latest supported Python versions,
+and the PyPI release workflow won't publish if it fails.
+
 ## Roadmap
 
 Already done as of v1.0:
@@ -227,13 +272,13 @@ Already done as of v1.0:
 - [x] Orphaned-function and circular-dependency detection
 - [x] Diff mode between two scans
 - [x] Focus mode, orbit layout, right-click actions, minimap, breadcrumb
+- [x] Automated test suite + CI
 
 Not yet, but planned:
 
 - [ ] "Explain this function" — a plain-language AI summary button
 - [ ] More precise multi-language parsing (currently structural regex for
       everything but Python)
-- [ ] An automated test suite
 
 Have an idea? Open an issue.
 
@@ -247,8 +292,12 @@ but contributions are genuinely welcome:
   or UI polish. Keep the zero-dependency philosophy: the core tool should
   keep running on nothing but the Python standard library, and the UI
   should keep running on vanilla JS with no build step.
-- No formal test suite yet, so please describe how you manually verified a
-  change in your PR.
+- Run `pytest -q` before opening a PR (see [Testing](#testing) above); add
+  a fixture + test case under `tests/` for new parser behavior where you
+  can.
+
+Security issue instead? See [SECURITY.md](SECURITY.md) rather than a
+public issue.
 
 ## License
 

{codebread-1.0.2.dist-info → codebread-1.0.4.dist-info}/RECORD

@@ -1,4 +1,4 @@
-codebread/__init__.py,sha256=InwUkpEmPv-mS3-33Vu1RXBTw1Zm4tYbe9RB4DAsW5s,97
+codebread/__init__.py,sha256=mwaD5s8k8q32ofSXrl6_tMjBJk0U1U2lrxwP3PPNtCs,1215
 codebread/analyzer.py,sha256=tCsV0Cwi1l-If5zbNLbMtsuKW3o-rl8mekNG-B7MXpY,3234
 codebread/classifier.py,sha256=jehD-XQ80CP_O4x9YRi4JQqzd4AaHxKpzI83wLG1yvM,4067
 codebread/cli.py,sha256=AMvwk29cOJDjsI-I07pCGbqogdtq1Y6HWnT52FHYyLs,4072
@@ -8,17 +8,17 @@ codebread/export.py,sha256=rKYmzuSEXYDrgcItnhdyXI_lo0LN2PSoMe0hYElzU88,1512
 codebread/languages.py,sha256=SKHy9v7QPreWZG6FbuX3B0-kq1jqVn-rmwNqJ9ESFqo,4494
 codebread/models.py,sha256=Sw2PJW63dKyl5RpWwfY2ZvCJLYttmjoQg4O5H5DtLgM,4214
 codebread/scanner.py,sha256=bEXSaoENmJ-C_oabj2IF1aWs9-LaIqMc80xXQvo7-eg,8020
-codebread/server.py,sha256=H3kUXJaH8FkExNUwdwSD2HxBMceC_24o6pVSjJjFh8g,3543
+codebread/server.py,sha256=Uh7L2n0pumpt1UNSlC1mvcjg6yBl1LAxTmbz9cmsilA,4597
 codebread/parsers/__init__.py,sha256=ovsvmXGClshiUlDdx6mkBmRu8__OZIqYos6-1eLb9eM,2285
 codebread/parsers/generic_parser.py,sha256=lz-wLsmQYERoDRM27lhEP3cvNYbomHfA--VI_3LmJ5E,11966
 codebread/parsers/javascript_parser.py,sha256=lVIlydQ3--Owd78816XIM77NntfQ97DeLzYvPrjd5GE,15916
 codebread/parsers/python_parser.py,sha256=QnhCLx01bKYLYqav33cI27qbEQNPUiXnS5uN7cb8poQ,11671
-codebread/web/app.js,sha256=P1zpCHNMyczAuLWL9zM5htl9E3wG3jJdpZ6orLhixTM,65672
+codebread/web/app.js,sha256=bsm7cpji0mJrnpr0TPNhsL6w2bQw4RMwA8lS_T57G1s,66567
 codebread/web/index.html,sha256=6YqjC_wO3pfqyG_11uIhvRM16Wagu2l8eSOs1FNc-UY,8693
 codebread/web/style.css,sha256=fiq1bC-I1bC6-6MxRn0blQwGOjO_fdClPrhf5W7zqPw,23729
-codebread-1.0.2.dist-info/licenses/LICENSE,sha256=okINupIvMgiuOlvMVpsM9DT5jb6QQmKBd--yfZq4bjc,1070
-codebread-1.0.2.dist-info/METADATA,sha256=zWaglNGGhQUvXpPnyXwNdS_a6Og2jdIFhWImFNlGvAY,11367
-codebread-1.0.2.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-codebread-1.0.2.dist-info/entry_points.txt,sha256=ItG61aUP1YTvA_zA-jlUshBc5BPpJDpCyVnsyaxNXKA,49
-codebread-1.0.2.dist-info/top_level.txt,sha256=KctFB7UQb4tN9YotaJD95GuHWIQuoO5VqyLdo_gEswQ,10
-codebread-1.0.2.dist-info/RECORD,,
+codebread-1.0.4.dist-info/licenses/LICENSE,sha256=okINupIvMgiuOlvMVpsM9DT5jb6QQmKBd--yfZq4bjc,1070
+codebread-1.0.4.dist-info/METADATA,sha256=KY847kSXgZNds5HE-a9UJdGXazfY1nhrWW661_1lIjg,14262
+codebread-1.0.4.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+codebread-1.0.4.dist-info/entry_points.txt,sha256=ItG61aUP1YTvA_zA-jlUshBc5BPpJDpCyVnsyaxNXKA,49
+codebread-1.0.4.dist-info/top_level.txt,sha256=KctFB7UQb4tN9YotaJD95GuHWIQuoO5VqyLdo_gEswQ,10
+codebread-1.0.4.dist-info/RECORD,,