codebread 1.0.6__py3-none-any.whl → 1.1.0__py3-none-any.whl

codebread/__init__.py

@@ -2,17 +2,30 @@
 from __future__ import annotations
 
 import os
+import re
 
 
 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.
+    A source checkout (pyproject.toml sitting next to the package) wins:
+    an editable `pip install -e .` freezes its metadata at install time,
+    so after a version bump importlib.metadata keeps reporting the old
+    number until you reinstall. Wheel installs have no pyproject.toml
+    beside them and fall through to their own (always correct) metadata.
+    No toml parser needed for one `version = "..."` line — keeps the
+    zero-dependency promise.
     """
+    root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    try:
+        with open(os.path.join(root, "pyproject.toml"), encoding="utf-8") as f:
+            text = f.read()
+        if re.search(r"""^name\s*=\s*["']codebread["']""", text, re.M):
+            m = re.search(r"""^version\s*=\s*["']([^"']+)["']""", text, re.M)
+            if m:
+                return m.group(1)
+    except OSError:
+        pass
     try:
         from importlib.metadata import PackageNotFoundError, version
         try:
@@ -21,15 +34,6 @@ def _read_version() -> str:
             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"
 
 

codebread/cli.py

@@ -37,6 +37,11 @@ def main(argv=None) -> int:
                         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("--md", nargs="?", const="", metavar="OUT.md",
+                        help="also write an AI context brief (Markdown) - a "
+                             "compact map of the project an assistant can read "
+                             "instead of every file. Default: CODEBREAD.md in "
+                             "the scanned folder")
     parser.add_argument("--no-open", action="store_true",
                         help="don't auto-open the browser")
     parser.add_argument("--no-serve", action="store_true",
@@ -89,6 +94,14 @@ def main(argv=None) -> int:
             print(f"[codebread] {graph['stats']['warnings']} warning(s) - "
                   f"they are shown as badges in the UI, nothing was hidden.")
 
+    from .context import export_markdown, to_markdown
+    graph["contextMd"] = to_markdown(graph)  # powers the report's "Copy for AI" / download
+    if args.md is not None:
+        default_dir = graph.get("meta", {}).get("root") or os.getcwd()
+        if not os.path.isdir(default_dir):  # --load of a graph scanned elsewhere
+            default_dir = os.getcwd()
+        p = export_markdown(graph, args.md or os.path.join(default_dir, "CODEBREAD.md"))
+        print(f"[codebread] AI context brief written to {p}")
     if args.json:
         p = export_json(graph, args.json)
         print(f"[codebread] Graph JSON written to {p}")

codebread/context.py

@@ -0,0 +1,170 @@
+"""AI context brief: the whole graph as compact Markdown.
+
+An assistant that reads every source file to learn a project burns tokens
+on code it doesn't need. This brief gives it the map instead: what each
+file does, its functions, routes, tables, and who calls whom. It reads
+it once, then opens only the files that matter for the task.
+"""
+from __future__ import annotations
+
+import os
+from collections import Counter, defaultdict
+from typing import Dict, Iterable
+
+LAYER_ORDER = ["frontend", "backend", "database", "config", "unknown"]
+LAYER_NAME = {"frontend": "Frontend", "backend": "Backend", "database": "Database",
+              "config": "Config", "unknown": "Unclassified"}
+FNS_PER_FILE = 40   # ponytail: hard cap keeps huge files from flooding the brief
+LIST_CAP = 8
+
+
+def _short(items: Iterable[str], cap: int = LIST_CAP) -> str:
+    items = list(dict.fromkeys(items))  # dedupe, keep order
+    more = f" (+{len(items) - cap} more)" if len(items) > cap else ""
+    return ", ".join(items[:cap]) + more
+
+
+def to_markdown(graph: Dict) -> str:
+    nodes = {n["id"]: n for n in graph.get("nodes", [])}
+    edges = [e for e in graph.get("edges", [])
+             if e["kind"] != "contains" and e["source"] in nodes and e["target"] in nodes]
+    meta, stats = graph.get("meta", {}), graph.get("stats", {})
+    files = sorted((n for n in nodes.values() if n["kind"] == "file"), key=lambda n: n["file"])
+    tables = sorted((n for n in nodes.values() if n["kind"] == "table"), key=lambda n: n["label"])
+    fns = defaultdict(list)
+    for n in nodes.values():
+        if n["kind"] in ("function", "method") and n.get("file"):
+            fns[n["file"]].append(n)
+    for fl in fns.values():
+        fl.sort(key=lambda n: n.get("line") or 0)
+    out_e, in_e = defaultdict(list), defaultdict(list)
+    for e in edges:
+        out_e[e["source"]].append(e)
+        in_e[e["target"]].append(e)
+
+    def ref(nid: str, here: str = "") -> str:
+        n = nodes[nid]
+        if n["kind"] in ("function", "method"):
+            return f"`{n['label']}()`" if n.get("file") == here else f"`{n.get('file')}:{n['label']}()`"
+        if n["kind"] == "table":
+            return f"`{n['label']}` (table)"
+        return f"`{n.get('file') or n['label']}`"
+
+    def owner(nid: str) -> str:
+        n = nodes[nid]
+        return n["id"] if n["kind"] in ("file", "table") else (n.get("file") or n["id"])
+
+    name = meta.get("name") or "project"
+    L = [f"# {name}: codebase context", "",
+         f"> Generated by CodeBread {meta.get('version', '')} on {str(meta.get('scannedAt', ''))[:10]}. "
+         "This is a map of the whole project: what each file does, its functions, and how "
+         "they connect. Read it first and open source files only when you need exact code.", ""]
+
+    # ---- at a glance
+    langs = Counter(f.get("language") or "?" for f in files)
+    layers = Counter(f.get("layer") or "unknown" for f in files)
+
+    def layer_rank(k: str) -> int:
+        return LAYER_ORDER.index(k) if k in LAYER_ORDER else len(LAYER_ORDER)
+
+    L += ["## At a glance", "",
+          f"- {stats.get('files', len(files))} files, {stats.get('functions', 0)} functions, "
+          f"{stats.get('tables', len(tables))} tables, {stats.get('connections', len(edges))} connections",
+          "- Languages: " + ", ".join(f"{k} ({v})" for k, v in langs.most_common()),
+          "- Layers: " + ", ".join(f"{LAYER_NAME.get(k, k)} ({v})"
+                                   for k, v in sorted(layers.items(), key=lambda kv: layer_rank(kv[0]))),
+          ""]
+
+    # ---- entry points
+    routes = sorted(((r["method"], r["path"], fn) for fl in fns.values() for fn in fl
+                     for r in fn.get("routes") or []), key=lambda x: (x[1], x[0]))
+    if routes:
+        L += ["## HTTP routes", "", "| Method | Path | Handler |", "|---|---|---|"]
+        L += [f"| {m} | `{p}` | `{fn['file']}:{fn['label']}()` |" for m, p, fn in routes]
+        L.append("")
+
+    # ---- data model
+    if tables:
+        L += ["## Database tables", ""]
+        for t in tables:
+            bits = []
+            if t.get("fields"):
+                bits.append("fields: " + _short(t["fields"], 15))
+            if t.get("model"):
+                bits.append(f"model `{t['model']}`")
+            users = [ref(e["source"]) for e in in_e[t["id"]]]
+            if users:
+                bits.append("used by " + _short(users))
+            where = f" in `{t['file']}`" if t.get("file") else ""
+            L.append(f"- **{t['label']}**{where}" + (": " + "; ".join(bits) if bits else ""))
+        L.append("")
+
+    # ---- files, grouped by layer
+    L += ["## Files", ""]
+    by_layer = defaultdict(list)
+    for f in files:
+        by_layer[f.get("layer") or "unknown"].append(f)
+    for layer in sorted(by_layer, key=layer_rank):
+        L += [f"### {LAYER_NAME.get(layer, layer)}", ""]
+        for f in by_layer[layer]:
+            path = f["file"]
+            members = [f["id"]] + [fn["id"] for fn in fns.get(path, [])]
+            talks = [ref(owner(e["target"])) for m in members for e in out_e[m]
+                     if owner(e["target"]) != f["id"]]
+            heard = [ref(owner(e["source"])) for m in members for e in in_e[m]
+                     if owner(e["source"]) != f["id"]]
+            L.append(f"#### `{path}` ({f.get('language', '?')}, {f.get('loc', 0)} lines)")
+            if talks:
+                L.append("Uses: " + _short(talks))
+            if heard:
+                L.append("Used by: " + _short(heard))
+            if f.get("warnings"):
+                L.append("Warnings: " + "; ".join(f["warnings"][:3]))
+            fl = fns.get(path, [])
+            for fn in fl[:FNS_PER_FILE]:
+                params = ", ".join(fn.get("params") or [])
+                cls = f"{fn['parentClass']}." if fn.get("parentClass") else ""
+                line = f"- `{cls}{fn['label']}({params})` L{fn.get('line', '?')}"
+                if fn.get("description"):
+                    line += f": {fn['description']}"
+                calls = [ref(e["target"], path) for e in out_e[fn["id"]] if e["kind"] != "db"]
+                tbls = [nodes[e["target"]]["label"] for e in out_e[fn["id"]] if e["kind"] == "db"]
+                callers = [ref(e["source"], path) for e in in_e[fn["id"]]]
+                extra = []
+                if calls:
+                    extra.append("calls " + _short(calls))
+                if tbls and not fn.get("description"):  # descriptions already name their tables
+                    extra.append("tables " + _short(tbls))
+                if callers:
+                    extra.append("called by " + _short(callers))
+                if fn.get("cycle"):
+                    extra.append("in a call cycle")
+                elif fn.get("orphan"):
+                    extra.append("no callers found")
+                if extra:
+                    line += " | " + "; ".join(extra)
+                L.append(line)
+            if len(fl) > FNS_PER_FILE:
+                L.append(f"- … {len(fl) - FNS_PER_FILE} more functions")
+            L.append("")
+
+    # ---- things to be careful about
+    notes = []
+    for c in graph.get("cycles", [])[:20]:
+        notes.append("Call cycle: " + " → ".join(f"`{x}()`" for x in c["labels"] + c["labels"][:1]))
+    for w in graph.get("warnings", [])[:20]:
+        notes.append(f"Warning in `{w.get('path', '')}`: {w.get('message', '')}")
+    obf = [f["file"] for f in files if f.get("obfuscation")]
+    if obf:
+        notes.append("Obfuscated code in: " + _short(f"`{p}`" for p in obf))
+    if notes:
+        L += ["## Watch out", ""] + [f"- {n}" for n in notes] + [""]
+
+    return "\n".join(L).rstrip() + "\n"
+
+
+def export_markdown(graph: Dict, out_path: str) -> str:
+    out_path = os.path.abspath(out_path)
+    with open(out_path, "w", encoding="utf-8") as f:
+        f.write(to_markdown(graph))
+    return out_path