codebread 1.0.0__py3-none-any.whl

codebread/__init__.py

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

codebread/analyzer.py

@@ -0,0 +1,84 @@
+"""Orchestrates: scan -> parse -> classify -> connect -> graph dict."""
+from __future__ import annotations
+
+import datetime
+import os
+import sys
+from typing import Callable, Dict, Optional
+
+from . import __version__
+from .classifier import classify
+from .connections import build_graph
+from .parsers import parse_file
+from .scanner import read_text, scan
+
+
+def analyze(root: str,
+            progress: Optional[Callable[[str], None]] = None) -> Dict:
+    """Run the full pipeline on `root` and return the graph dict."""
+    say = progress or (lambda msg: None)
+    root = os.path.abspath(root)
+
+    say(f"Scanning {root} ...")
+    result = scan(root)
+    files_meta = result["files"]
+    warnings = result["warnings"]
+    say(f"  found {len(files_meta)} scannable files")
+
+    parsed = []
+    unsupported = {}
+    for i, meta in enumerate(files_meta, 1):
+        text, err = read_text(meta["abspath"])
+        info = parse_file(meta["path"], text, meta["language"])
+        if err:
+            info.warnings.append(err)
+        info.layer = classify(info, text)
+        if info.parsed or info.language in ("html", "css"):
+            info.source = text if len(text) <= 300_000 else \
+                text[:300_000] + "\n… (truncated)"
+        parsed.append(info)
+        for w in info.warnings:
+            if w.startswith("Unsupported:"):
+                unsupported.setdefault(meta["language"], 0)
+                unsupported[meta["language"]] += 1
+            warnings.append({"path": meta["path"], "message": w})
+        if i % 50 == 0:
+            say(f"  parsed {i}/{len(files_meta)} files")
+
+    for lang, count in sorted(unsupported.items()):
+        say(f"  note: {count} file(s) in {lang} - no parser available, "
+            f"shown as unsupported in the UI")
+
+    say("Mapping connections ...")
+    _annotate_tree(result["tree"], {f.path: f for f in parsed})
+    graph = build_graph(parsed, result["tree"], warnings)
+    graph["meta"] = {
+        "root": root,
+        "name": os.path.basename(root) or root,
+        "scannedAt": datetime.datetime.now().isoformat(timespec="seconds"),
+        "version": __version__,
+    }
+    s = graph["stats"]
+    say(f"Done: {s['files']} files, {s['functions']} functions, "
+        f"{s['tables']} tables, {s['connections']} connections, "
+        f"{s['warnings']} warnings")
+    return graph
+
+
+def _annotate_tree(node: Dict, by_path: Dict) -> None:
+    """Copy layer/warning info onto tree nodes for the sidebar."""
+    if node.get("type") == "file":
+        info = by_path.get(node.get("path"))
+        if info is not None:
+            node["layer"] = info.layer
+            node["nFunctions"] = len(info.functions)
+            if info.warnings and "warning" not in node:
+                node["warning"] = "parse"
+        return
+    layers = set()
+    for child in node.get("children", []):
+        _annotate_tree(child, by_path)
+        if child.get("layer") and child["layer"] not in ("unknown", None):
+            layers.add(child["layer"])
+    if len(layers) == 1:
+        node["layer"] = layers.pop()

codebread/classifier.py

@@ -0,0 +1,102 @@
+"""Score-based Frontend / Backend / Database / Config classifier.
+
+Combines framework import signatures, folder naming conventions, file
+extensions/patterns, and extracted facts (routes, DB models). Ambiguous
+files stay "unknown" (shown as Unclassified) rather than guessing wrong.
+"""
+from __future__ import annotations
+
+import os
+import re
+from typing import Dict
+
+from .models import FileInfo
+
+FRONTEND_IMPORTS = re.compile(
+    r"^(react|react-dom|next|vue|@vue|nuxt|@angular|svelte|solid-js|preact|"
+    r"jquery|axios|@tanstack|redux|zustand|styled-components|@mui|antd|"
+    r"tailwindcss|three|d3)($|/)", re.IGNORECASE)
+BACKEND_IMPORTS = re.compile(
+    r"^(express|koa|fastify|hapi|@nestjs|flask|django|fastapi|starlette|"
+    r"bottle|tornado|sanic|aiohttp|gin|echo|fiber|laravel|symfony|rails|"
+    r"sinatra|spring|springframework|gorilla|net/http|http\.server|"
+    r"microsoft\.aspnetcore)($|/|\.)", re.IGNORECASE)
+DB_IMPORTS = re.compile(
+    r"^(sqlalchemy|django\.db|peewee|tortoise|pymongo|motor|redis|psycopg2?|"
+    r"mysql|sqlite3|mongoose|prisma|@prisma|sequelize|typeorm|knex|pg|"
+    r"mongodb|gorm|database/sql|entityframework|dapper|activerecord)"
+    r"($|/|\.)", re.IGNORECASE)
+
+FRONTEND_DIRS = {"client", "frontend", "front", "components", "pages", "views",
+                 "ui", "www", "public", "static", "assets", "layouts", "hooks",
+                 "styles", "templates", "screens", "widgets"}
+BACKEND_DIRS = {"server", "backend", "back", "api", "routes", "controllers",
+                "middleware", "services", "handlers", "endpoints", "resolvers",
+                "views_api", "rest", "graphql", "app"}
+DB_DIRS = {"models", "model", "db", "database", "migrations", "schema",
+           "schemas", "entities", "repositories", "orm", "prisma", "sql"}
+
+FRONTEND_EXTS = {".jsx", ".tsx", ".vue", ".svelte", ".html", ".htm",
+                 ".css", ".scss", ".sass", ".less"}
+
+
+def classify(info: FileInfo, raw_text: str = "") -> str:
+    if info.language == "config":
+        return "config"
+    if info.language in ("markdown", "text"):
+        return "unknown"
+    if info.language == "sql":
+        return "database"
+
+    score: Dict[str, float] = {"frontend": 0.0, "backend": 0.0,
+                               "database": 0.0}
+
+    ext = os.path.splitext(info.path)[1].lower()
+    if ext in FRONTEND_EXTS:
+        score["frontend"] += 2.5
+    if info.language in ("vue", "svelte"):
+        score["frontend"] += 2.0
+
+    parts = [p.lower() for p in info.path.split("/")[:-1]]
+    for p in parts:
+        if p in FRONTEND_DIRS:
+            score["frontend"] += 1.5
+        if p in BACKEND_DIRS:
+            score["backend"] += 1.5
+        if p in DB_DIRS:
+            score["database"] += 2.0
+
+    for imp in info.imports:
+        if FRONTEND_IMPORTS.match(imp):
+            score["frontend"] += 2.0
+        if BACKEND_IMPORTS.match(imp):
+            score["backend"] += 2.5
+        if DB_IMPORTS.match(imp):
+            score["database"] += 2.0
+
+    # extracted facts are strong signals
+    n_routes = len(info.routes) + sum(len(f.routes) for f in info.functions)
+    if n_routes:
+        score["backend"] += 2.0 + min(n_routes, 5) * 0.4
+    if info.tables:
+        score["database"] += 2.0 + min(len(info.tables), 5) * 0.6
+    n_api = len(info.api_calls) + sum(len(f.api_calls) for f in info.functions)
+    if n_api and score["backend"] < 1.0:
+        score["frontend"] += 1.0  # things that *call* APIs lean frontend
+    n_db = sum(len(f.db_refs) for f in info.functions)
+    if n_db:
+        score["database"] += min(n_db, 4) * 0.5
+        score["backend"] += 0.5
+
+    if raw_text and info.language in ("javascript", "typescript"):
+        if re.search(r"\bdocument\.|window\.|useState\(|useEffect\(",
+                     raw_text):
+            score["frontend"] += 1.5
+        if re.search(r"process\.env|require\(['\"]fs['\"]\)|__dirname",
+                     raw_text):
+            score["backend"] += 0.8
+
+    best = max(score, key=lambda k: score[k])
+    if score[best] < 1.5:
+        return "unknown"
+    return best

codebread/cli.py

@@ -0,0 +1,106 @@
+"""CodeBread command line interface."""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from . import __version__
+
+BANNER = r"""
+   ___         _     ___                  _
+  / __|___  __| |___| _ )_ _ ___ __ _ __| |
+ | (__/ _ \/ _` / -_) _ \ '_/ -_) _` / _` |
+  \___\___/\__,_\___|___/_| \___\__,_\__,_|  v{v}
+  slice open a codebase and see how it's wired
+"""
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="codebread",
+        description="Interactive codebase analyzer & visualizer. Scans a "
+                    "project, extracts every function/class, maps frontend "
+                    "-> backend -> database connections, and opens an "
+                    "interactive graph in your browser.")
+    parser.add_argument("--path", "-p",
+                        help="root folder to scan (prompted if omitted)")
+    parser.add_argument("--load", metavar="GRAPH.json",
+                        help="serve a previously exported graph JSON "
+                             "instead of re-scanning")
+    parser.add_argument("--diff", nargs=2, metavar=("OLD.json", "NEW.json"),
+                        help="compare two saved graph JSON exports and "
+                             "print what changed, then exit")
+    parser.add_argument("--port", type=int, default=8137,
+                        help="local server port (default: 8137)")
+    parser.add_argument("--json", metavar="OUT.json",
+                        help="also export the full graph as JSON")
+    parser.add_argument("--html", metavar="OUT.html",
+                        help="also export a self-contained static HTML file")
+    parser.add_argument("--no-open", action="store_true",
+                        help="don't auto-open the browser")
+    parser.add_argument("--no-serve", action="store_true",
+                        help="scan + export only, don't start the server")
+    parser.add_argument("--version", action="version",
+                        version=f"codebread {__version__}")
+    args = parser.parse_args(argv)
+
+    print(BANNER.format(v=__version__))
+
+    from .export import export_html, export_json, load_json
+
+    if args.diff:
+        old_path, new_path = args.diff
+        for p in (old_path, new_path):
+            if not os.path.isfile(p):
+                print(f"error: {p} not found", file=sys.stderr)
+                return 2
+        from .diff import compute_diff, format_diff_report
+        report = format_diff_report(compute_diff(load_json(old_path), load_json(new_path)))
+        print(report)
+        return 0
+
+    if args.load:
+        if not os.path.isfile(args.load):
+            print(f"error: {args.load} not found", file=sys.stderr)
+            return 2
+        graph = load_json(args.load)
+        print(f"[codebread] Loaded saved graph: {args.load}")
+    else:
+        root = args.path
+        if not root:
+            try:
+                root = input("Path to the project to analyze: ").strip().strip('"')
+            except (EOFError, KeyboardInterrupt):
+                print()
+                return 1
+        if not root:
+            print("error: no path given", file=sys.stderr)
+            return 2
+        root = os.path.expanduser(root)
+        if not os.path.isdir(root):
+            print(f"error: not a folder: {root}", file=sys.stderr)
+            return 2
+
+        from .analyzer import analyze
+        graph = analyze(root, progress=lambda m: print(f"[codebread] {m}"))
+
+        if graph["stats"]["warnings"]:
+            print(f"[codebread] {graph['stats']['warnings']} warning(s) - "
+                  f"they are shown as badges in the UI, nothing was hidden.")
+
+    if args.json:
+        p = export_json(graph, args.json)
+        print(f"[codebread] Graph JSON written to {p}")
+    if args.html:
+        p = export_html(graph, args.html)
+        print(f"[codebread] Static HTML written to {p}")
+
+    if not args.no_serve:
+        from .server import serve
+        serve(graph, port=args.port, open_browser=not args.no_open)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())