codebeacon 0.6.1__tar.gz → 0.6.2__tar.gz

{codebeacon-0.6.1 → codebeacon-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebeacon
-Version: 0.6.1
+Version: 0.6.2
 Summary: Source code AST analysis tool for AI context generation — unified multi-framework knowledge graph
 Project-URL: Homepage, https://github.com/codebeacon/codebeacon
 Project-URL: Repository, https://github.com/codebeacon/codebeacon

codebeacon-0.6.2/codebeacon/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.6.2"

{codebeacon-0.6.1 → codebeacon-0.6.2}/codebeacon/common/safety.py

@@ -18,6 +18,7 @@ Three concerns:
 
 from __future__ import annotations
 
+import hashlib
 import re
 import subprocess
 from pathlib import Path
@@ -69,6 +70,38 @@ def escape_frontmatter_value(value: object) -> str:
     return text
 
 
+def cap_filename(name: str, limit: int = 200) -> str:
+    """Cap a filename stem to ``limit`` UTF-8 *bytes*, collision-safely.
+
+    A single path component is capped at 255 bytes by every mainstream
+    filesystem, so a node label long enough to overflow that — roughly 85 CJK
+    characters at 3 bytes each, or 255 ASCII — makes ``Path.write_text`` raise
+    ``OSError`` (ENAMETOOLONG) and aborts the *entire* obsidian / wiki export,
+    not just the one note. We cap to 200 bytes to leave headroom for the
+    trailing ``.md`` and any ``_N`` dedup suffix the caller appends.
+
+    Two properties matter:
+
+    * The budget is counted in **bytes**, not characters, so multi-byte scripts
+      (CJK, emoji) cannot slip past a character-count guard.
+    * When truncation actually happens we append ``_<sha1[:8]>`` of the original
+      name, so two labels sharing a long common prefix
+      (``"z"*250 + "_ALPHA"`` vs ``"z"*250 + "_BETA"``) still resolve to
+      distinct files instead of silently colliding.
+
+    Truncation slices the UTF-8 byte string and decodes with ``"ignore"`` so a
+    multi-byte character straddling the cut is dropped rather than producing
+    mojibake. Short names are returned untouched. Mirrors graphify 690b4e5.
+    """
+    encoded = name.encode("utf-8")
+    if len(encoded) <= limit:
+        return name
+    digest = hashlib.sha1(name.encode("utf-8")).hexdigest()[:8]
+    keep = max(limit - 9, 0)  # room for "_" + 8 hex chars
+    truncated = encoded[:keep].decode("utf-8", "ignore")
+    return f"{truncated}_{digest}"
+
+
 def git_head(repo_path: str | Path) -> str:
     """Return the full HEAD commit SHA for ``repo_path``, or "" if not a repo.
 

{codebeacon-0.6.1 → codebeacon-0.6.2}/codebeacon/common/types.py

@@ -62,6 +62,8 @@ class ServiceInfo:
     methods: list = field(default_factory=list)    # list[str] - method names
     dependencies: list = field(default_factory=list)  # list[str] - injected type names (unresolved)
     annotations: list = field(default_factory=list)   # list[str] - @Service, @Injectable, etc.
+    implements: list = field(default_factory=list)    # list[str] - implemented interface names
+    extends: list = field(default_factory=list)       # list[str] - superclass names
 
 
 @dataclass(slots=True)

{codebeacon-0.6.1 → codebeacon-0.6.2}/codebeacon/export/obsidian.py

@@ -33,7 +33,7 @@ from typing import Any
 
 import networkx as nx
 
-from codebeacon.common.safety import escape_frontmatter_value, sanitize_label
+from codebeacon.common.safety import cap_filename, escape_frontmatter_value, sanitize_label
 
 
 # ── Regexes ────────────────────────────────────────────────────────────────────
@@ -402,9 +402,18 @@ def _reverse_relation(relation: str) -> str:
 
 
 def _safe_note_name(label: str) -> str:
-    """Convert node label to a safe filename stem (no path separators)."""
+    """Convert node label to a safe filename stem (no path separators).
+
+    The byte cap (via ``cap_filename``) prevents a very long label — or an 85+
+    character CJK class name — from overflowing the 255-byte filesystem limit
+    and crashing ``_step1_generate_notes`` with ENAMETOOLONG. Because every
+    wikilink target is generated through this same function, the note's
+    filename and the links pointing at it stay byte-for-byte consistent even
+    after truncation.
+    """
     # Replace characters that confuse Obsidian wikilinks
-    return re.sub(r'[/\\#^|[\]]', "_", label).strip()
+    cleaned = re.sub(r'[/\\#^|[\]]', "_", label).strip()
+    return cap_filename(cleaned)
 
 
 # ── Step 2: Fix broken wikilinks ──────────────────────────────────────────────

{codebeacon-0.6.1 → codebeacon-0.6.2}/codebeacon/extract/queries/angular.scm

@@ -191,3 +191,21 @@
 (import_statement
   source: (string) @import.path
 ) @import.decl
+
+; ── Class heritage: extends / implements ─────────────────────────────────────
+; Feeds SymbolTable._implements_map so an interface-typed dependency resolves to
+; the @Injectable class that implements it. One match is emitted per heritage
+; type (multiple implements → multiple matches); the interpreter folds them
+; back per class. Validated against tree-sitter-typescript:
+;   class_heritage → extends_clause(value:) + implements_clause(type_identifier)
+(class_declaration
+  name: (type_identifier) @service.heritage_class
+  (class_heritage
+    (extends_clause
+      value: (identifier) @service.extends
+    )?
+    (implements_clause
+      (type_identifier) @service.implements
+    )?
+  )
+) @service.with_heritage

{codebeacon-0.6.1 → codebeacon-0.6.2}/codebeacon/extract/queries/nestjs.scm

@@ -181,3 +181,21 @@
 (import_statement
   source: (string) @import.path
 ) @import.decl
+
+; ── Class heritage: extends / implements ─────────────────────────────────────
+; Feeds SymbolTable._implements_map so an interface-typed provider resolves to
+; the @Injectable class that implements it. One match is emitted per heritage
+; type (multiple implements → multiple matches); the interpreter folds them
+; back per class. Validated against tree-sitter-typescript:
+;   class_heritage → extends_clause(value:) + implements_clause(type_identifier)
+(class_declaration
+  name: (type_identifier) @service.heritage_class
+  (class_heritage
+    (extends_clause
+      value: (identifier) @service.extends
+    )?
+    (implements_clause
+      (type_identifier) @service.implements
+    )?
+  )
+) @service.with_heritage

{codebeacon-0.6.1 → codebeacon-0.6.2}/codebeacon/extract/services.py

@@ -137,6 +137,38 @@ def _nid(file_path: str, name: str) -> str:
     return f"{file_path}::{name}"
 
 
+def _collect_heritage(matches: list) -> dict[str, tuple[list[str], list[str]]]:
+    """Collect ``class_name → (extends, implements)`` from heritage captures.
+
+    The ``@service.with_heritage`` query pattern (TS frameworks) emits one match
+    per heritage type, so a class with ``implements IFoo, OnInit`` produces two
+    matches that both carry ``@service.heritage_class``. We fold them back into
+    per-class lists, de-duplicating while preserving declaration order. Feeds the
+    structured ``ServiceInfo.extends`` / ``.implements`` fields that
+    ``SymbolTable`` reads for interface→implementation DI resolution.
+    """
+    extends: dict[str, list[str]] = {}
+    implements: dict[str, list[str]] = {}
+    for _idx, caps in matches:
+        if "service.heritage_class" not in caps:
+            continue
+        cname = node_text(caps["service.heritage_class"][0])
+        for node in caps.get("service.extends", []):
+            val = node_text(node)
+            bucket = extends.setdefault(cname, [])
+            if val and val not in bucket:
+                bucket.append(val)
+        for node in caps.get("service.implements", []):
+            val = node_text(node)
+            bucket = implements.setdefault(cname, [])
+            if val and val not in bucket:
+                bucket.append(val)
+    return {
+        cname: (extends.get(cname, []), implements.get(cname, []))
+        for cname in set(extends) | set(implements)
+    }
+
+
 def _interpret_noop(
     file_path: str, matches: list, framework: str,
 ) -> tuple[list[ServiceInfo], list[UnresolvedRef]]:
@@ -183,6 +215,11 @@ def _interpret_spring_boot(
                 if start <= cls.start_byte <= end:
                     if iface not in info.annotations:
                         info.annotations.append(f"implements:{iface}")
+                    # Structured field too: SymbolTable reads metadata["implements"]
+                    # (not the annotation string) to drive interface→impl DI
+                    # resolution. The annotation is kept for the wiki display.
+                    if iface not in info.implements:
+                        info.implements.append(iface)
                     break
 
         # @Autowired field injection
@@ -304,6 +341,16 @@ def _interpret_nestjs(
                     framework="nestjs",
                 ))
 
+    # Attach class heritage (extends / implements) so interface-typed providers
+    # resolve to their implementing service via SymbolTable._implements_map.
+    heritage = _collect_heritage(matches)
+    for svc in services.values():
+        ext, impl = heritage.get(svc.name, ([], []))
+        if ext:
+            svc.extends = ext
+        if impl:
+            svc.implements = impl
+
     return list(services.values()), unresolved
 
 
@@ -475,6 +522,10 @@ def _interpret_aspnet(
             )
             if iface:
                 svc.annotations.append(f"implements:{iface}")
+                # Structured field drives interface→impl DI resolution; the C#
+                # base_list's first identifier is conventionally the interface
+                # (IFoo) when a class registers via AddScoped<IFoo, FooImpl>().
+                svc.implements.append(iface)
             services.append(svc)
 
         if "di.generic_registration" in caps and "di.service_type" in caps and "di.impl_type" in caps:
@@ -635,6 +686,16 @@ def _interpret_angular(
                     framework="angular",
                 ))
 
+    # Attach class heritage (extends / implements) so interface-typed providers
+    # resolve to their implementing service via SymbolTable._implements_map.
+    heritage = _collect_heritage(matches)
+    for svc in services.values():
+        ext, impl = heritage.get(svc.name, ([], []))
+        if ext:
+            svc.extends = ext
+        if impl:
+            svc.implements = impl
+
     return list(services.values()), unresolved
 
 

{codebeacon-0.6.1 → codebeacon-0.6.2}/codebeacon/graph/build.py

@@ -62,6 +62,18 @@ def build_graph(
             service_roots, claimed_ids,
         )
 
+    # Rewrite file-path-keyed UnresolvedRef sources onto their final node IDs.
+    # The per-file extractors mint ``UnresolvedRef.source_node_id`` as
+    # ``f"{file_path}::{name}"`` (see extract/services.py::_nid), but graph nodes
+    # are keyed ``project::name``. Left unrewritten, the resolved injects edge
+    # carries a source the graph has never heard of and gets silently dropped by
+    # ``_build_nx_graph``. Spring/NestJS survive that drop because they *also*
+    # stage the dependency on ``svc.dependencies`` (which _ingest_wave re-emits
+    # with the correct id), but FastAPI ``Depends()``, Laravel ``bind()`` and
+    # ASP.NET ``AddScoped<>`` only ever emit the file-path form — so their DI
+    # edges vanished entirely until this remap.
+    _remap_unresolved_sources(all_nodes, all_unresolved)
+
     # Cross-file declaration merge. When the same symbol appears in multiple
     # files (Swift `extension Foo`, C# partial classes, Ruby reopened classes),
     # the per-file extractor emits one Node per file. NetworkX collapses them
@@ -142,6 +154,8 @@ def _ingest_wave(
                 "methods": svc.methods,
                 "dependencies": svc.dependencies,
                 "annotations": svc.annotations,
+                "implements": svc.implements,
+                "extends": svc.extends,
                 "framework": svc.framework,
                 "project": project_name,
             },
@@ -258,6 +272,64 @@ def _disambiguate_decl(
     return disambiguated, f"{name} ({hint})"
 
 
+# ── UnresolvedRef source remap ────────────────────────────────────────────────
+
+def _bare_name(node_id: str) -> str:
+    """Recover a declaration's plain name from its graph node ID.
+
+    Node IDs are ``project::Name`` or, for directory-disambiguated collisions,
+    ``project::hint/Name`` — so the trailing path segment after the last ``::``
+    and ``/`` is the original symbol name. Route IDs carry extra ``::`` segments
+    but are never DI sources, so the (harmless) value they yield never matches a
+    real ``ref_name``.
+    """
+    return node_id.rsplit("::", 1)[-1].rsplit("/", 1)[-1]
+
+
+def _remap_unresolved_sources(
+    all_nodes: list[Node], all_unresolved: list[UnresolvedRef]
+) -> None:
+    """Point each UnresolvedRef at a real graph node ID, in place.
+
+    Two lookup tables are built from the finalized node set:
+
+    * ``by_file_name`` — ``(source_file, bare_name) → node_id``. This is the
+      exact case: the injecting class is declared in the same file the
+      extractor stamped onto the ref (Spring, NestJS, FastAPI).
+    * ``by_name`` — ``bare_name → node_id``. The fallback for binding-style DI
+      where the ref's file is the *registration site* (a Laravel ServiceProvider
+      or an ASP.NET ``Startup``) but the intended source node is the
+      implementation class declared elsewhere.
+
+    A ref whose ``source_node_id`` already names a live node (the
+    ``project::Name`` form that ``_ingest_wave`` emits from ``svc.dependencies``)
+    is left untouched, so this never disturbs edges that already resolve. A ref
+    that matches nothing is also left as-is and will drop exactly as it did
+    before — no regression, only recovery.
+    """
+    node_ids = {n.id for n in all_nodes}
+    by_file_name: dict[tuple[str, str], str] = {}
+    by_name: dict[str, list[str]] = {}
+    for n in all_nodes:
+        bare = _bare_name(n.id)
+        by_file_name.setdefault((n.source_file, bare), n.id)
+        by_name.setdefault(bare, []).append(n.id)
+
+    for ref in all_unresolved:
+        sid = ref.source_node_id
+        if sid in node_ids:
+            continue  # already a valid graph node id
+        file_part, sep, name_part = sid.rpartition("::")
+        if not sep or not name_part:
+            continue
+        new_id = by_file_name.get((file_part, name_part))
+        if new_id is None:
+            candidates = by_name.get(name_part)
+            new_id = candidates[0] if candidates else None
+        if new_id is not None:
+            ref.source_node_id = new_id
+
+
 # ── Cross-file declaration merge ──────────────────────────────────────────────
 
 def _merge_cross_file_decls(nodes: list[Node]) -> list[Node]:
@@ -271,7 +343,7 @@ def _merge_cross_file_decls(nodes: list[Node]) -> list[Node]:
     """
     _LIST_KEYS = (
         "fields", "methods", "dependencies", "annotations",
-        "relations", "props", "hooks",
+        "relations", "props", "hooks", "implements", "extends",
     )
     first: dict[str, Node] = {}
     for node in nodes:

{codebeacon-0.6.1 → codebeacon-0.6.2}/codebeacon/graph/cluster.py

@@ -24,25 +24,53 @@ def cluster(G: nx.DiGraph) -> dict[str, int]:
     """Detect communities in the graph.
 
     Returns:
-        node_id → community_id mapping (community IDs are consecutive integers
-        starting from 0).
+        node_id → community_id mapping. Community IDs are consecutive integers
+        starting from 0, assigned by a *stable total order* (see
+        :func:`_relabel_stable`) so that an identical graph always yields an
+        identical mapping regardless of which backend ran or the order it
+        happened to enumerate communities in.
     """
     if G.number_of_nodes() == 0:
         return {}
 
-    result = _try_graspologic(G)
-    if result is not None:
-        return result
+    for backend in (_try_graspologic, _try_leidenalg, _try_louvain):
+        result = backend(G)
+        if result is not None:
+            return _relabel_stable(result)
 
-    result = _try_leidenalg(G)
-    if result is not None:
-        return result
+    return _relabel_stable(_connected_components(G))
 
-    result = _try_louvain(G)
-    if result is not None:
-        return result
 
-    return _connected_components(G)
+def _relabel_stable(communities: dict[str, int]) -> dict[str, int]:
+    """Reassign community IDs deterministically from the raw partition.
+
+    The Leiden / Louvain / connected-component backends each label communities
+    in whatever order they happen to enumerate them — an order that is *not*
+    stable across runs when several communities share the same size. Two scans
+    of an unchanged graph could therefore hand the same grouping different
+    integer IDs, churning 77–88% of ``beacon.json`` lines on a no-op rescan and
+    drowning real diffs (graphify measured exactly this before f5f3a1c).
+
+    We break that by imposing a total order on the communities themselves:
+    largest first, ties broken by the lexicographically-sorted tuple of member
+    node IDs. Equal groupings are bytewise-identical inputs to the sort, so they
+    always receive the same ID. The ``str()`` coercion keeps the comparison
+    well-defined even if a backend hands back non-string node keys.
+    """
+    members: dict[int, list[str]] = {}
+    for node, cid in communities.items():
+        members.setdefault(cid, []).append(node)
+
+    ordered = sorted(
+        members.values(),
+        key=lambda nodes: (-len(nodes), tuple(sorted(map(str, nodes)))),
+    )
+
+    relabeled: dict[str, int] = {}
+    for new_cid, nodes in enumerate(ordered):
+        for node in nodes:
+            relabeled[node] = new_cid
+    return relabeled
 
 
 def apply_communities(G: nx.DiGraph, communities: dict[str, int]) -> None:

{codebeacon-0.6.1 → codebeacon-0.6.2}/codebeacon/wiki/generator.py

@@ -27,6 +27,7 @@ from typing import Any
 
 import networkx as nx
 
+from codebeacon.common.safety import cap_filename
 from codebeacon.wiki import templates
 
 
@@ -54,8 +55,15 @@ def _is_controller(label: str, annotations: list[str]) -> bool:
 
 
 def _safe_filename(label: str) -> str:
-    """Strip characters that are unsafe in filenames."""
-    return "".join(c if c.isalnum() or c in "-_." else "_" for c in label)
+    """Strip filename-unsafe characters, then cap the stem to a safe byte length.
+
+    The byte cap stops a pathologically long class label (or an 85+ character
+    CJK name) from overflowing the 255-byte filesystem limit and crashing the
+    whole wiki write with ENAMETOOLONG. ``cap_filename`` keeps long-prefix
+    labels distinct via a hash suffix, so two capped names never collide.
+    """
+    cleaned = "".join(c if c.isalnum() or c in "-_." else "_" for c in label)
+    return cap_filename(cleaned)
 
 
 def node_to_wiki_path(G: nx.DiGraph, node_id: str) -> str | None:

{codebeacon-0.6.1 → codebeacon-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codebeacon"
-version = "0.6.1"
+version = "0.6.2"
 description = "Source code AST analysis tool for AI context generation — unified multi-framework knowledge graph"
 readme = "README.md"
 license = { text = "MIT" }