codebread 1.0.3__tar.gz → 1.0.4__tar.gz

{codebread-1.0.3/codebread.egg-info → codebread-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebread
-Version: 1.0.3
+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">
@@ -238,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:
@@ -251,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.
 
@@ -271,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.3/PKG-INFO → codebread-1.0.4/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.4
-Name: codebread
-Version: 1.0.3
-Summary: Interactive codebase analyzer & visualizer — slice open a project and see how it's wired together.
-Author: Danial Irsyad
-License: MIT
-Keywords: codebase,analyzer,visualizer,call-graph,architecture
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Provides-Extra: full
-Requires-Dist: pathspec>=0.11; extra == "full"
-Dynamic: license-file
-
 <p align="center">
   <img src="https://cdn.jsdelivr.net/gh/honow48-tech/CodeBread@main/assets/logo-wordmark.png" alt="CodeBread" width="360">
 </p>
@@ -22,7 +8,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">
@@ -238,12 +225,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:
@@ -251,13 +256,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.
 
@@ -271,8 +276,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.4/codebread/__init__.py

@@ -0,0 +1,36 @@
+"""CodeBread — slice open a codebase and see its internal structure."""
+from __future__ import annotations
+
+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-1.0.3 → codebread-1.0.4}/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-1.0.3/README.md → codebread-1.0.4/codebread.egg-info/PKG-INFO

@@ -1,3 +1,19 @@
+Metadata-Version: 2.4
+Name: codebread
+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
+Keywords: codebase,analyzer,visualizer,call-graph,architecture
+Requires-Python: >=3.9
+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">
   <img src="https://cdn.jsdelivr.net/gh/honow48-tech/CodeBread@main/assets/logo-wordmark.png" alt="CodeBread" width="360">
 </p>
@@ -8,7 +24,8 @@
 </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">
@@ -224,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:
@@ -237,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.
 
@@ -257,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.3 → codebread-1.0.4}/codebread.egg-info/SOURCES.txt

@@ -24,4 +24,13 @@ codebread/parsers/javascript_parser.py
 codebread/parsers/python_parser.py
 codebread/web/app.js
 codebread/web/index.html
-codebread/web/style.css
+codebread/web/style.css
+tests/test_analyzer.py
+tests/test_config_parser.py
+tests/test_connections.py
+tests/test_generic_parser.py
+tests/test_javascript_parser.py
+tests/test_python_parser.py
+tests/test_scanner.py
+tests/test_server.py
+tests/test_version.py

{codebread-1.0.3 → codebread-1.0.4}/codebread.egg-info/requires.txt

@@ -1,3 +1,6 @@
 
 [full]
 pathspec>=0.11
+
+[test]
+pytest>=7

{codebread-1.0.3 → codebread-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codebread"
-version = "1.0.3"
+version = "1.0.4"
 description = "Interactive codebase analyzer & visualizer — slice open a project and see how it's wired together."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -15,6 +15,7 @@ dependencies = []
 
 [project.optional-dependencies]
 full = ["pathspec>=0.11"]
+test = ["pytest>=7"]
 
 [project.scripts]
 codebread = "codebread.cli:main"
@@ -24,3 +25,6 @@ include = ["codebread*"]
 
 [tool.setuptools.package-data]
 codebread = ["web/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

codebread-1.0.4/tests/test_analyzer.py

@@ -0,0 +1,71 @@
+import json
+import os
+
+from codebread.analyzer import analyze
+
+
+def _write(root, rel_path, content):
+    full = os.path.join(root, rel_path)
+    os.makedirs(os.path.dirname(full), exist_ok=True)
+    with open(full, "w", encoding="utf-8") as f:
+        f.write(content)
+
+
+def test_analyze_end_to_end_small_project(tmp_path):
+    root = str(tmp_path)
+    _write(root, "app.py", (
+        "from flask import Flask\n"
+        "app = Flask(__name__)\n\n"
+        "@app.route('/users')\n"
+        "def list_users():\n"
+        "    return get_users()\n\n"
+        "def get_users():\n"
+        "    return []\n"
+    ))
+    _write(root, "frontend/main.js", (
+        "async function loadUsers() {\n"
+        "  const res = await fetch('/users');\n"
+        "  return res.json();\n"
+        "}\n"
+    ))
+
+    graph = analyze(root)
+
+    assert graph["stats"]["files"] == 2
+    assert graph["stats"]["functions"] >= 3
+    assert graph["meta"]["name"] == os.path.basename(root)
+    # the graph must be JSON-serializable end to end (what --json/server ship)
+    json.dumps(graph)
+
+
+def test_analyze_never_leaks_env_secrets_into_exported_graph(tmp_path):
+    root = str(tmp_path)
+    _write(root, ".env", (
+        "DATABASE_URL=postgres://admin:hunter2@db.example.com:5432/prod\n"
+        "API_KEY=sk-abcdef123456\n"
+        "DEBUG=true\n"
+    ))
+    _write(root, "app.py", "def hello():\n    return 'hi'\n")
+
+    graph = analyze(root)
+    dumped = json.dumps(graph)
+
+    assert "hunter2" not in dumped
+    assert "sk-abcdef123456" not in dumped
+    # non-secret content should still be visible (regression against
+    # over-redaction hiding everything)
+    assert "DEBUG=true" in dumped
+
+
+def test_analyze_handles_syntax_errors_without_crashing(tmp_path):
+    root = str(tmp_path)
+    _write(root, "broken.py", "def broken(:\n    pass\n")
+
+    graph = analyze(root)
+    assert graph["stats"]["warnings"] >= 1
+
+
+def test_analyze_empty_directory(tmp_path):
+    graph = analyze(str(tmp_path))
+    assert graph["stats"]["files"] == 0
+    assert graph["nodes"] == []

codebread-1.0.4/tests/test_config_parser.py

@@ -0,0 +1,36 @@
+from codebread.models import FileInfo
+from codebread.parsers.generic_parser import parse_config
+
+
+def _parse(text):
+    info = FileInfo(path=".env", language="config")
+    parse_config(info, text)
+    return info
+
+
+def test_secret_keys_are_masked_in_summary():
+    info = _parse("PASSWORD=hunter2\nAPI_KEY=sk-live-abc123\n")
+    joined = "\n".join(info.db_config)
+    assert "hunter2" not in joined
+    assert "sk-live-abc123" not in joined
+    assert "masked" in joined
+
+
+def test_db_url_credentials_masked_but_host_kept():
+    info = _parse("DATABASE_URL=postgres://admin:hunter2@db.example.com:5432/prod\n")
+    joined = "\n".join(info.db_config)
+    assert "hunter2" not in joined
+    assert "db.example.com" in joined
+
+
+def test_non_db_non_secret_keys_ignored():
+    info = _parse("DEBUG=true\nPORT=8080\n")
+    assert info.db_config == []
+
+
+def test_comments_and_blank_lines_skipped():
+    info = _parse("# PASSWORD=shouldnotmatch\n\nPASSWORD=realsecret\n")
+    joined = "\n".join(info.db_config)
+    assert "shouldnotmatch" not in joined
+    assert "realsecret" not in joined  # masked either way
+    assert joined.count("PASSWORD") == 1

codebread-1.0.4/tests/test_connections.py

@@ -0,0 +1,96 @@
+from codebread.connections import build_graph
+from codebread.models import ApiCall, DbRef, FileInfo, FunctionInfo, Route, TableInfo
+
+
+def _fn(name, calls=None, routes=None, api_calls=None, db_refs=None, line=1):
+    return FunctionInfo(
+        name=name, line=line, end_line=line + 5,
+        calls=calls or [], routes=routes or [],
+        api_calls=api_calls or [], db_refs=db_refs or [],
+    )
+
+
+def build(files):
+    return build_graph(files, tree={}, warnings=[])
+
+
+def test_same_file_call_edge():
+    f = FileInfo(path="app.py", language="python", layer="backend",
+                 functions=[_fn("main", calls=["helper"]), _fn("helper", line=10)])
+    g = build([f])
+    call_edges = [e for e in g["edges"] if e["kind"] == "call"]
+    assert any(e["source"].endswith("::main@1") and e["target"].endswith("::helper@10")
+               for e in call_edges)
+
+
+def test_cross_file_call_resolves_unique_name():
+    a = FileInfo(path="app.py", language="python", layer="backend",
+                 functions=[_fn("main", calls=["fetch_user"])])
+    b = FileInfo(path="utils.py", language="python", layer="backend",
+                 functions=[_fn("fetch_user", line=1)])
+    g = build([a, b])
+    call_edges = [e for e in g["edges"] if e["kind"] == "call"]
+    assert any(e["target"] == "utils.py::fetch_user@1" for e in call_edges)
+
+
+def test_api_call_matches_route_despite_param_syntax_difference():
+    frontend = FileInfo(path="frontend.js", language="javascript", layer="frontend",
+                        api_calls=[ApiCall(method="GET", url="/api/users/:id")])
+    backend = FileInfo(path="backend.py", language="python", layer="backend",
+                       functions=[_fn("get_user",
+                                     routes=[Route(method="GET", path="/api/users/<id>")])])
+    g = build([frontend, backend])
+    api_edges = [e for e in g["edges"] if e["kind"] == "api"]
+    assert len(api_edges) == 1
+    assert api_edges[0]["target"] == "backend.py::get_user@1"
+
+
+def test_db_edge_links_function_to_table():
+    models = FileInfo(path="models.py", language="python", layer="database",
+                      tables=[TableInfo(name="users", model="User")])
+    backend = FileInfo(path="backend.py", language="python", layer="backend",
+                       functions=[_fn("get_user",
+                                     db_refs=[DbRef(table="User", op="query", via="orm")])])
+    g = build([models, backend])
+    db_edges = [e for e in g["edges"] if e["kind"] == "db"]
+    assert len(db_edges) == 1
+    assert db_edges[0]["target"] == "table::users"
+
+
+def test_include_edge_resolves_python_import():
+    idx = FileInfo(path="index.py", language="python", layer="backend",
+                   imports=["helperlib"])
+    lib = FileInfo(path="helperlib.py", language="python", layer="backend")
+    g = build([idx, lib])
+    include_edges = [e for e in g["edges"] if e["kind"] == "include"]
+    assert any(e["source"] == "index.py" and e["target"] == "helperlib.py"
+               for e in include_edges)
+
+
+def test_orphan_detection_respects_entry_names():
+    f = FileInfo(path="app.py", language="python", layer="backend",
+                 functions=[_fn("main"), _fn("never_called", line=10)])
+    g = build([f])
+    by_label_line = {(n["label"], n.get("line")): n for n in g["nodes"]
+                     if n["kind"] == "function"}
+    assert not by_label_line[("main", 1)].get("orphan")
+    assert by_label_line[("never_called", 10)].get("orphan") is True
+
+
+def test_cycle_detection_flags_both_functions_and_reports_cycle():
+    f = FileInfo(path="cycle.py", language="python", layer="backend",
+                 functions=[_fn("a", calls=["b"]), _fn("b", calls=["a"], line=10)])
+    g = build([f])
+    fn_nodes = [n for n in g["nodes"] if n["kind"] == "function"]
+    assert all(n.get("cycle") for n in fn_nodes)
+    assert g["stats"]["cycles"] == 1
+    assert len(g["cycles"]) == 1
+
+
+def test_stats_counts_are_consistent():
+    f = FileInfo(path="app.py", language="python", layer="backend",
+                 functions=[_fn("main", calls=["helper"]), _fn("helper", line=10)])
+    g = build([f])
+    assert g["stats"]["files"] == 1
+    assert g["stats"]["functions"] == 2
+    assert g["stats"]["connections"] == len(g["edges"])

codebread-1.0.4/tests/test_generic_parser.py

@@ -0,0 +1,104 @@
+from conftest import read_fixture
+
+from codebread.models import FileInfo
+from codebread.parsers.generic_parser import (parse_generic, parse_sql,
+                                               redact_secrets)
+
+
+def _parse(language, *fixture_parts):
+    info = FileInfo(path="/".join(fixture_parts), language=language)
+    parse_generic(info, read_fixture(*fixture_parts), language)
+    return info
+
+
+def test_java_functions_class_and_route():
+    info = _parse("java", "java", "UserController.java")
+    names = {f.name for f in info.functions}
+    assert {"getUser", "createUser"} <= names
+    by_name = {f.name: f for f in info.functions}
+    assert by_name["getUser"].routes[0].method == "GET"
+    assert by_name["getUser"].routes[0].path == "/users/{id}"
+
+
+def test_java_raw_sql_detected():
+    info = _parse("java", "java", "UserController.java")
+    by_name = {f.name: f for f in info.functions}
+    assert any(r.table == "users" and r.op == "insert"
+               for r in by_name["createUser"].db_refs)
+
+
+def test_csharp_functions_and_route():
+    info = _parse("csharp", "csharp", "UsersController.cs")
+    names = {f.name for f in info.functions}
+    assert {"GetUser", "CreateUser"} <= names
+    by_name = {f.name: f for f in info.functions}
+    assert by_name["GetUser"].routes[0].method == "GET"
+
+
+def test_go_functions_and_struct():
+    info = _parse("go", "go", "sample.go")
+    names = {f.name for f in info.functions}
+    assert {"getUser", "createUser", "main"} <= names
+    # structs are extracted as classes via a separate pass in analyzer/UI —
+    # parse_generic itself doesn't record "class" nodes for Go, only imports
+    # and functions, so we just check the struct's type line didn't get
+    # mistaken for a function.
+    assert "User" not in names
+
+
+def test_go_raw_sql_detected():
+    info = _parse("go", "go", "sample.go")
+    by_name = {f.name: f for f in info.functions}
+    assert any(r.table == "users" and r.op == "insert"
+               for r in by_name["createUser"].db_refs)
+
+
+def test_php_functions_route_and_page_link():
+    info = _parse("php", "php", "users.php")
+    names = {f.name for f in info.functions}
+    assert {"find", "render_user_page"} <= names
+    assert any(r.method == "GET" and r.path == "/users/{id}"
+               for r in info.routes)
+    assert "dashboard.php" in info.links
+
+
+def test_php_import_extracted():
+    info = _parse("php", "php", "users.php")
+    assert "db.php" in info.imports
+
+
+def test_ruby_functions_and_route():
+    info = _parse("ruby", "ruby", "users_controller.rb")
+    names = {f.name for f in info.functions}
+    assert {"show", "create", "helper_method"} <= names
+    assert any(r.method == "GET" and r.path == "/users/:id"
+               for r in info.routes)
+
+
+def test_sql_create_table_schema():
+    info = FileInfo(path="schema.sql", language="sql")
+    parse_sql(info, read_fixture("sql", "schema.sql"))
+    by_name = {t.name: t for t in info.tables}
+    assert set(by_name) == {"users", "orders"}
+    assert set(by_name["users"].fields) >= {"id", "name", "email"}
+    # constraint lines must not be mistaken for columns
+    assert "FOREIGN" not in by_name["orders"].fields
+
+
+def test_redact_secrets_masks_password_and_url_creds():
+    text = (
+        "DATABASE_URL=postgres://admin:hunter2@db.example.com:5432/prod\n"
+        "API_KEY=sk-abcdef123456\n"
+        "DEBUG=true\n"
+    )
+    out = redact_secrets(text)
+    assert "hunter2" not in out
+    assert "sk-abcdef123456" not in out
+    assert "DEBUG=true" in out
+    assert "db.example.com" in out  # non-secret parts stay readable
+
+
+def test_redact_secrets_preserves_line_count():
+    text = "A=1\nB=2\nPASSWORD=x\nC=3\n"
+    out = redact_secrets(text)
+    assert len(out.splitlines()) == len(text.splitlines())

codebread-1.0.4/tests/test_javascript_parser.py

@@ -0,0 +1,82 @@
+from conftest import read_fixture
+
+from codebread.models import FileInfo
+from codebread.parsers.javascript_parser import parse_javascript
+
+
+def _parse_express():
+    info = FileInfo(path="server.js", language="javascript")
+    parse_javascript(info, read_fixture("javascript", "sample_express.js"), "javascript")
+    return info
+
+
+def _parse_ts():
+    info = FileInfo(path="app.ts", language="typescript")
+    parse_javascript(info, read_fixture("javascript", "sample_types.ts"), "typescript")
+    return info
+
+
+def _parse_vue():
+    info = FileInfo(path="Counter.vue", language="vue")
+    parse_javascript(info, read_fixture("vue", "sample.vue"), "vue")
+    return info
+
+
+def test_extracts_functions_and_class_method():
+    info = _parse_express()
+    names = {f.name for f in info.functions}
+    assert {"fetchExternalProfile", "getUser", "createUser", "getById"} <= names
+    by_name = {f.name: f for f in info.functions}
+    assert by_name["getById"].parent_class == "UserService"
+    assert by_name["getById"].kind == "method"
+
+
+def test_extracts_mongoose_model():
+    info = _parse_express()
+    assert len(info.tables) == 1
+    table = info.tables[0]
+    assert table.model == "User"
+    assert set(table.fields) >= {"name", "email"}
+
+
+def test_extracts_route_attached_to_named_handler():
+    info = _parse_express()
+    all_routes = list(info.routes)
+    for f in info.functions:
+        all_routes.extend(f.routes)
+    methods_paths = {(r.method, r.path) for r in all_routes}
+    assert ("GET", "/users/:id") in methods_paths
+    assert ("POST", "/users") in methods_paths
+
+
+def test_extracts_fetch_api_call():
+    info = _parse_express()
+    by_name = {f.name: f for f in info.functions}
+    calls = by_name["fetchExternalProfile"].api_calls
+    assert len(calls) == 1
+    assert calls[0].method == "GET"
+    assert "api.example.com" in calls[0].url
+
+
+def test_extracts_orm_usage_and_raw_sql():
+    info = _parse_express()
+    by_name = {f.name: f for f in info.functions}
+    assert any(r.table == "User" for r in by_name["getUser"].db_refs)
+    assert any(r.table == "users" and r.via == "sql" and r.op == "insert"
+               for r in by_name["createUser"].db_refs)
+
+
+def test_typescript_type_annotations_dont_break_extraction():
+    info = _parse_ts()
+    names = {f.name for f in info.functions}
+    assert {"getUserName", "double", "greet"} <= names
+    by_name = {f.name: f for f in info.functions}
+    assert by_name["greet"].parent_class == "Greeter"
+
+
+def test_vue_script_setup_functions_extracted_and_template_excluded():
+    info = _parse_vue()
+    names = {f.name for f in info.functions}
+    assert {"increment", "logChange"} <= names
+    # template-only content shouldn't leak in as a function name
+    assert "button" not in names

codebread-1.0.4/tests/test_python_parser.py

@@ -0,0 +1,59 @@
+from conftest import read_fixture
+
+from codebread.models import FileInfo
+from codebread.parsers.python_parser import parse_python
+
+
+def _parse():
+    info = FileInfo(path="app.py", language="python")
+    parse_python(info, read_fixture("python", "sample_flask.py"))
+    return info
+
+
+def test_extracts_functions():
+    info = _parse()
+    names = {f.name for f in info.functions}
+    assert {"fetch_remote_profile", "get_user", "create_user"} <= names
+
+
+def test_extracts_orm_model():
+    info = _parse()
+    assert len(info.tables) == 1
+    table = info.tables[0]
+    assert table.name == "users"
+    assert table.model == "User"
+    assert set(table.fields) >= {"id", "name"}
+
+
+def test_extracts_routes():
+    info = _parse()
+    by_name = {f.name: f for f in info.functions}
+    assert by_name["get_user"].routes[0].method == "GET"
+    assert by_name["get_user"].routes[0].path == "/users/<int:user_id>"
+    assert by_name["create_user"].routes[0].method == "POST"
+
+
+def test_extracts_outgoing_api_call():
+    info = _parse()
+    by_name = {f.name: f for f in info.functions}
+    calls = by_name["fetch_remote_profile"].api_calls
+    assert len(calls) == 1
+    assert calls[0].method == "GET"
+    assert "/profiles/" in calls[0].url
+
+
+def test_extracts_orm_query_and_raw_sql():
+    info = _parse()
+    by_name = {f.name: f for f in info.functions}
+    get_refs = by_name["get_user"].db_refs
+    assert any(r.table == "User" and r.via == "orm" for r in get_refs)
+    create_refs = by_name["create_user"].db_refs
+    assert any(r.table == "users" and r.via == "sql" and r.op == "insert"
+               for r in create_refs)
+
+
+def test_syntax_error_is_reported_not_raised():
+    info = FileInfo(path="broken.py", language="python")
+    parse_python(info, "def broken(:\n    pass\n")
+    assert info.functions == []
+    assert any("syntax error" in w.lower() for w in info.warnings)

codebread-1.0.4/tests/test_scanner.py

@@ -0,0 +1,84 @@
+import os
+
+from codebread.languages import detect_language, looks_binary
+from codebread.scanner import scan
+
+
+def _write(root, rel_path, content=""):
+    full = os.path.join(root, rel_path)
+    os.makedirs(os.path.dirname(full), exist_ok=True)
+    with open(full, "w", encoding="utf-8") as f:
+        f.write(content)
+    return full
+
+
+def test_scan_respects_gitignore(tmp_path):
+    root = str(tmp_path)
+    _write(root, ".gitignore", "ignored.py\nbuild/\n")
+    _write(root, "keep.py", "def f(): pass\n")
+    _write(root, "ignored.py", "def g(): pass\n")
+    _write(root, "build/output.py", "def h(): pass\n")
+
+    result = scan(root)
+    paths = {f["path"] for f in result["files"]}
+    assert "keep.py" in paths
+    assert "ignored.py" not in paths
+    assert "build/output.py" not in paths
+
+
+def test_scan_skips_known_noise_dirs(tmp_path):
+    root = str(tmp_path)
+    _write(root, "app.py", "def f(): pass\n")
+    _write(root, "node_modules/pkg/index.js", "module.exports = {};\n")
+    _write(root, ".git/HEAD", "ref: refs/heads/main\n")
+
+    result = scan(root)
+    paths = {f["path"] for f in result["files"]}
+    assert "app.py" in paths
+    assert not any(p.startswith("node_modules/") for p in paths)
+    assert not any(p.startswith(".git/") for p in paths)
+
+
+def test_scan_flags_oversized_files_as_warning(tmp_path):
+    root = str(tmp_path)
+    big = "x = 1\n" * 200_000  # comfortably over the 1MB default cap
+    _write(root, "huge.py", big)
+
+    result = scan(root, max_file_kb=1)
+    assert any(w["path"] == "huge.py" for w in result["warnings"])
+    assert not any(f["path"] == "huge.py" for f in result["files"])
+
+
+def test_detect_language_env_files_are_config():
+    assert detect_language(".env") == "config"
+    assert detect_language(".env.production") == "config"
+
+
+def test_detect_language_settings_py_stays_python():
+    # CONFIG_BASENAMES includes settings.py, but it should still be parsed
+    # as real Python (full extraction), not routed into the generic
+    # config-key-scan bucket.
+    assert detect_language("settings.py") == "python"
+
+
+def test_detect_language_common_extensions():
+    assert detect_language("app.py") == "python"
+    assert detect_language("component.tsx") == "typescript"
+    assert detect_language("main.go") == "go"
+    assert detect_language("style.css") == "css"
+
+
+def test_looks_binary_by_extension():
+    assert looks_binary("photo.png") is True
+
+
+def test_looks_binary_by_null_byte(tmp_path):
+    p = tmp_path / "weird.dat"
+    p.write_bytes(b"\x00\x01\x02binary-ish")
+    assert looks_binary(str(p)) is True
+
+
+def test_looks_binary_false_for_text(tmp_path):
+    p = tmp_path / "note.unknownext"
+    p.write_text("just plain text", encoding="utf-8")
+    assert looks_binary(str(p)) is False

codebread-1.0.4/tests/test_server.py

@@ -0,0 +1,83 @@
+import os
+import threading
+import urllib.error
+import urllib.request
+
+import pytest
+
+from codebread.server import WEB_DIR, build_server, safe_web_path
+
+
+def test_safe_web_path_allows_files_inside_web_dir():
+    resolved = safe_web_path("app.js")
+    assert resolved is not None
+    assert os.path.isfile(resolved)
+
+
+def test_safe_web_path_blocks_relative_traversal():
+    assert safe_web_path("../../../../Windows/win.ini") is None
+
+
+@pytest.mark.skipif(os.name != "nt",
+                    reason="drive-absolute os.path.join discard is an "
+                           "ntpath-only quirk; on POSIX there's no drive "
+                           "letter so the path safely stays under WEB_DIR")
+def test_safe_web_path_blocks_windows_drive_absolute_traversal():
+    # The bug this locks in: os.path.join(WEB_DIR, "C:/x") on Windows
+    # discards WEB_DIR entirely because the second arg is drive-absolute.
+    drive = os.path.splitdrive(WEB_DIR)[0] or "C:"
+    assert safe_web_path(f"{drive}/Windows/win.ini") is None
+
+
+def test_safe_web_path_blocks_unc_style_path():
+    assert safe_web_path("//server/share/file.txt") is None
+
+
+def test_build_server_with_port_zero_lets_os_assign_a_port():
+    # Regression: port 0 ("let the OS pick") is a falsy int, and an earlier
+    # version of _free_port() returned 0 for both "OS-assigned" and "no
+    # free port found", so `if not port:` treated a successful bind as
+    # failure.
+    server = build_server({"nodes": [], "edges": [], "tree": {}, "stats": {}}, port=0)
+    try:
+        assert server is not None
+        assert server.server_port > 0
+    finally:
+        if server is not None:
+            server.server_close()
+
+
+@pytest.fixture
+def live_server():
+    server = build_server({"nodes": [], "edges": [], "tree": {}, "stats": {}}, port=0)
+    assert server is not None
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        yield f"http://127.0.0.1:{server.server_port}"
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=5)
+
+
+def test_live_server_serves_legit_asset(live_server):
+    with urllib.request.urlopen(f"{live_server}/app.js") as resp:
+        assert resp.status == 200
+        assert len(resp.read()) > 0
+
+
+def test_live_server_serves_data_json(live_server):
+    with urllib.request.urlopen(f"{live_server}/data.json") as resp:
+        assert resp.status == 200
+
+
+@pytest.mark.skipif(os.name != "nt",
+                    reason="drive-absolute os.path.join discard is an "
+                           "ntpath-only quirk; on POSIX the request just "
+                           "404s as a normal missing file under WEB_DIR")
+def test_live_server_rejects_drive_absolute_traversal(live_server):
+    drive = os.path.splitdrive(WEB_DIR)[0] or "C:"
+    with pytest.raises(urllib.error.HTTPError) as exc:
+        urllib.request.urlopen(f"{live_server}/{drive}/Windows/win.ini")
+    assert exc.value.code == 403

codebread-1.0.4/tests/test_version.py

@@ -0,0 +1,14 @@
+import re
+
+import codebread
+
+
+def test_version_is_a_plain_semver_like_string():
+    assert re.match(r"^\d+\.\d+\.\d+", codebread.__version__)
+
+
+def test_version_is_not_the_unresolved_fallback():
+    # "0.0.0+unknown" only happens if codebread is neither installed nor
+    # runnable from a checkout with a readable pyproject.toml — shouldn't
+    # happen in this repo's own test environment.
+    assert codebread.__version__ != "0.0.0+unknown"

codebread-1.0.3/codebread/__init__.py

@@ -1,3 +0,0 @@
-"""CodeBread — slice open a codebase and see its internal structure."""
-
-__version__ = "1.0.2"