codebeacon 0.1.2__py3-none-any.whl

codebeacon/common/filters.py

@@ -0,0 +1,170 @@
+"""Edge and node filters for graph cleanup.
+
+Three main filters applied after Pass-2 symbol resolution:
+1. filter_build_artifacts() — Remove nodes from build output dirs
+2. filter_cross_language() — Remove spurious Java↔TS/TSX import edges
+3. filter_cross_service() — Remove false cross-service edges (preserve calls_api, shares_db_entity)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from codebeacon.common.types import Edge, Node
+
+# Build artifact directories to exclude (checked against any path segment)
+_ARTIFACT_DIRS: frozenset[str] = frozenset({
+    "target", "build", "dist", "node_modules", ".next", ".nuxt",
+    "out", "output", "__pycache__", ".gradle", "vendor",
+    "bin", "obj", ".dart_tool", ".build", ".cache",
+})
+
+# Java/Kotlin file extensions
+_JAVA_EXTS: frozenset[str] = frozenset({".java", ".kt", ".kts"})
+# TypeScript/JavaScript file extensions
+_TS_EXTS: frozenset[str] = frozenset({".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"})
+
+# Relations to always preserve regardless of filter logic
+_PRESERVE_RELATIONS: frozenset[str] = frozenset({"calls_api", "shares_db_entity"})
+
+# Import-type relations that cross-service/cross-language filters operate on
+_IMPORT_RELATIONS: frozenset[str] = frozenset({"imports", "imports_from"})
+
+# Shared library directory markers (heuristic)
+_SHARED_MARKERS: frozenset[str] = frozenset({
+    "shared", "common", "lib", "libs", "core", "utils", "util", "commons", "base",
+})
+
+
+def filter_build_artifacts(
+    nodes: list[Node],
+    edges: list[Edge],
+) -> tuple[list[Node], list[Edge]]:
+    """Remove nodes whose source_file is inside a build artifact directory.
+
+    Also removes any edges that reference removed node IDs.
+
+    Returns:
+        (clean_nodes, clean_edges)
+    """
+    artifact_ids: set[str] = set()
+    clean_nodes: list[Node] = []
+
+    for node in nodes:
+        parts = Path(node.source_file).parts
+        if any(part in _ARTIFACT_DIRS for part in parts):
+            artifact_ids.add(node.id)
+        else:
+            clean_nodes.append(node)
+
+    clean_edges = [
+        e for e in edges
+        if e.source not in artifact_ids and e.target not in artifact_ids
+    ]
+    return clean_nodes, clean_edges
+
+
+def filter_cross_language(
+    edges: list[Edge],
+    nodes: dict[str, Node],
+) -> list[Edge]:
+    """Remove spurious cross-language import edges (e.g. Java class importing a TS file).
+
+    Preserves:
+    - calls_api, shares_db_entity (cross-service HTTP/DB)
+    - Non-import relations (calls, injects, etc.)
+
+    Args:
+        edges: list of all edges
+        nodes: node_id → Node mapping
+    """
+    result: list[Edge] = []
+    for edge in edges:
+        if edge.relation in _PRESERVE_RELATIONS:
+            result.append(edge)
+            continue
+
+        if edge.relation not in _IMPORT_RELATIONS:
+            result.append(edge)
+            continue
+
+        src_node = nodes.get(edge.source)
+        tgt_node = nodes.get(edge.target)
+        if not src_node or not tgt_node:
+            result.append(edge)
+            continue
+
+        src_ext = Path(src_node.source_file).suffix.lower()
+        tgt_ext = Path(tgt_node.source_file).suffix.lower()
+
+        src_java = src_ext in _JAVA_EXTS
+        src_ts = src_ext in _TS_EXTS
+        tgt_java = tgt_ext in _JAVA_EXTS
+        tgt_ts = tgt_ext in _TS_EXTS
+
+        # Java/Kotlin ↔ TypeScript/JavaScript import is always spurious
+        if (src_java and tgt_ts) or (src_ts and tgt_java):
+            continue
+
+        result.append(edge)
+    return result
+
+
+def filter_cross_service(
+    edges: list[Edge],
+    nodes: dict[str, Node],
+    service_roots: dict[str, str],  # node_id → service/project name
+) -> list[Edge]:
+    """Remove false cross-service import edges caused by name collisions.
+
+    For example: front-pms/Button ↔ front-pvms/Button should NOT be linked.
+
+    Preserved:
+    - calls_api, shares_db_entity (intentional cross-service connections)
+    - Non-import relations (calls, injects — kept for cross-service analysis)
+    - Edges to shared library nodes (heuristic: path contains 'shared', 'common', etc.)
+    - Edges where service affiliation is unknown
+
+    Args:
+        edges: list of all edges
+        nodes: node_id → Node mapping
+        service_roots: node_id → project/service name
+    """
+    result: list[Edge] = []
+    for edge in edges:
+        if edge.relation in _PRESERVE_RELATIONS:
+            result.append(edge)
+            continue
+
+        if edge.relation not in _IMPORT_RELATIONS:
+            result.append(edge)
+            continue
+
+        src_svc = service_roots.get(edge.source)
+        tgt_svc = service_roots.get(edge.target)
+
+        # Unknown affiliation → keep (conservative)
+        if not src_svc or not tgt_svc:
+            result.append(edge)
+            continue
+
+        # Same service → always keep
+        if src_svc == tgt_svc:
+            result.append(edge)
+            continue
+
+        # Different service import: check if target is a shared library
+        tgt_node = nodes.get(edge.target)
+        if tgt_node and _is_shared_lib(tgt_node.source_file):
+            result.append(edge)
+            continue
+
+        # Different service import to non-shared target → drop (likely false edge)
+
+    return result
+
+
+def _is_shared_lib(file_path: str) -> bool:
+    """Heuristic: is this file in a shared/common/lib directory?"""
+    parts = {p.lower() for p in Path(file_path).parts}
+    return bool(parts & _SHARED_MARKERS)

codebeacon/common/symbols.py

@@ -0,0 +1,121 @@
+"""Global symbol table for two-pass DI resolution (Pass 2).
+
+SymbolTable:
+  - Pass 1: receives all extracted nodes, builds class_name → file_path + implements/extends maps
+  - Pass 2: resolves UnresolvedRef objects → concrete Edge objects
+
+Resolution priority:
+  1. Interface → Impl mapping (Spring Boot @Service/@Component implements chain)
+  2. Direct class name match
+  3. Unresolved → return None
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from codebeacon.common.types import Edge, Node, UnresolvedRef
+
+
+class SymbolTable:
+    """Manages global symbol mappings for cross-file dependency resolution."""
+
+    def __init__(self) -> None:
+        # class_name → [file_path, ...]  (multiple definitions possible in monorepo)
+        self._class_map: dict[str, list[str]] = {}
+        # interface_name → [impl_class_name, ...]
+        self._implements_map: dict[str, list[str]] = {}
+        # All known node IDs
+        self._node_ids: set[str] = set()
+
+    def build(self, nodes: list[Node]) -> None:
+        """Build symbol maps from a flat list of all extracted nodes.
+
+        Must be called after all Pass-1 extraction is complete.
+        """
+        for node in nodes:
+            self._node_ids.add(node.id)
+
+            label = node.label
+            if label not in self._class_map:
+                self._class_map[label] = []
+            if node.id not in self._class_map[label]:
+                self._class_map[label].append(node.id)
+
+            # Register implements/extends relationships from metadata
+            meta = node.metadata or {}
+            for iface in meta.get("implements", []):
+                self._implements_map.setdefault(iface, [])
+                if label not in self._implements_map[iface]:
+                    self._implements_map[iface].append(label)
+            for parent in meta.get("extends", []):
+                self._implements_map.setdefault(parent, [])
+                if label not in self._implements_map[parent]:
+                    self._implements_map[parent].append(label)
+
+    def resolve_ref(self, ref: UnresolvedRef) -> Optional[Edge]:
+        """Attempt to resolve a single UnresolvedRef into a concrete Edge.
+
+        Returns None if resolution fails.
+        """
+        target_name = ref.ref_name
+
+        # Step 1: Try interface → impl mapping (Spring Boot / Laravel / Angular pattern)
+        impls = self._implements_map.get(target_name)
+        if impls:
+            chosen = impls[0]
+            if len(impls) > 1:
+                for impl in impls:
+                    if impl.endswith("Impl") or impl.endswith("Implementation"):
+                        chosen = impl
+                        break
+            target_name = chosen
+
+        # Step 2: Direct class match
+        if target_name not in self._class_map:
+            return None
+
+        # _class_map now stores node IDs; pick same-project target when possible
+        target_node_ids = self._class_map[target_name]
+        target_id = target_node_ids[0]
+        source_project = ref.source_node_id.split("::")[0] if "::" in ref.source_node_id else ""
+        for nid in target_node_ids:
+            if nid.startswith(source_project + "::"):
+                target_id = nid
+                break
+
+        is_interface_resolved = target_name != ref.ref_name
+        return Edge(
+            source=ref.source_node_id,
+            target=target_id,
+            relation="injects",
+            confidence="INFERRED" if is_interface_resolved else "EXTRACTED",
+            confidence_score=0.8 if is_interface_resolved else 1.0,
+            source_file=ref.source_node_id,
+        )
+
+    def resolve_all(
+        self, unresolved: list[UnresolvedRef]
+    ) -> tuple[list[Edge], list[UnresolvedRef]]:
+        """Resolve all UnresolvedRefs.
+
+        Returns:
+            (resolved_edges, still_unresolved) tuple.
+        """
+        resolved: list[Edge] = []
+        still_unresolved: list[UnresolvedRef] = []
+        for ref in unresolved:
+            edge = self.resolve_ref(ref)
+            if edge is not None:
+                resolved.append(edge)
+            else:
+                still_unresolved.append(ref)
+        return resolved, still_unresolved
+
+    def known_classes(self) -> set[str]:
+        """Return the set of all known class/type names."""
+        return set(self._class_map.keys())
+
+    def known_node_ids(self) -> set[str]:
+        """Return all registered node IDs."""
+        return set(self._node_ids)

codebeacon/common/types.py

@@ -0,0 +1,98 @@
+"""Core data types for codebeacon. All dataclasses use slots=True for memory efficiency."""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass(slots=True)
+class Node:
+    id: str
+    label: str
+    type: str            # "class", "method", "entity", "route", "component"
+    source_file: str
+    line: int
+    metadata: dict       # framework-specific extras
+
+
+@dataclass(slots=True)
+class Edge:
+    source: str
+    target: str
+    relation: str        # "imports", "calls", "injects", "calls_api", "shares_db_entity"
+    confidence: str      # "EXTRACTED", "INFERRED", "UNRESOLVED"
+    confidence_score: float
+    source_file: str
+
+
+@dataclass(slots=True)
+class UnresolvedRef:
+    source_node_id: str
+    ref_type: str        # "autowired", "depends", "inject", "import"
+    ref_name: str        # "AlertService", "get_db"
+    framework: str
+
+
+@dataclass(slots=True)
+class LocalExtractResult:
+    file_path: str
+    nodes: list          # list[Node]
+    unresolved: list     # list[UnresolvedRef]
+    imports: list        # list[str] - raw import statements
+
+
+@dataclass(slots=True)
+class RouteInfo:
+    method: str          # "GET", "POST", "PUT", "DELETE", "PATCH", "ANY"
+    path: str            # "/api/users/{id}"
+    handler: str         # "UserController.getUser"
+    source_file: str
+    line: int
+    framework: str
+    prefix: str = ""     # accumulated prefix from router.use() / Blueprint / etc.
+    tags: list = field(default_factory=list)  # ["auth", "db", "cache"]
+
+
+@dataclass(slots=True)
+class ServiceInfo:
+    name: str            # "UserService"
+    class_name: str
+    source_file: str
+    line: int
+    framework: str
+    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.
+
+
+@dataclass(slots=True)
+class EntityInfo:
+    name: str            # "User"
+    table_name: str      # "users" or "" if not explicit
+    source_file: str
+    line: int
+    framework: str       # "jpa", "django-orm", "sqlalchemy", "eloquent", "ef-core", "gorm", "active-record", "diesel", "sea-orm"
+    fields: list = field(default_factory=list)    # list[dict]: {"name", "type", "annotations"}
+    relations: list = field(default_factory=list) # list[dict]: {"type": "hasMany", "target": "Order"}
+
+
+@dataclass(slots=True)
+class ComponentInfo:
+    name: str            # "UserCard"
+    source_file: str
+    line: int
+    framework: str       # "react", "vue", "svelte", "angular"
+    props: list = field(default_factory=list)     # list[str] - prop names
+    hooks: list = field(default_factory=list)     # list[str] - used hooks/composables
+    imports: list = field(default_factory=list)   # list[str] - imported component names
+    is_page: bool = False                          # true if this is a route-level page component
+    route_path: str = ""                           # Next.js/Nuxt/SvelteKit derived route path
+
+
+@dataclass(slots=True)
+class ProjectInfo:
+    name: str
+    path: str
+    framework: str       # detected framework
+    language: str        # primary language
+    signature_file: str  # the file that triggered detection (pom.xml, package.json, etc.)
+    is_multi: bool = False

codebeacon/config.py

@@ -0,0 +1,144 @@
+"""codebeacon.yaml loader and validator."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+
+@dataclass
+class ProjectConfig:
+    name: str
+    path: str
+    type: str = "auto"  # framework type or "auto" for detection
+
+
+@dataclass
+class OutputConfig:
+    dir: str = ".codebeacon"
+    wiki: bool = True
+    obsidian: bool = True
+    graph_html: bool = True
+    context_map_targets: list = field(default_factory=lambda: ["CLAUDE.md", ".cursorrules", "AGENTS.md"])
+
+
+@dataclass
+class WaveConfig:
+    auto: bool = True
+    chunk_size: int = 300
+    max_parallel: int = 5
+
+
+@dataclass
+class SemanticConfig:
+    enabled: bool = False
+
+
+@dataclass
+class CodebeaconConfig:
+    version: int
+    projects: list  # list[ProjectConfig]
+    output: OutputConfig = field(default_factory=OutputConfig)
+    wave: WaveConfig = field(default_factory=WaveConfig)
+    semantic: SemanticConfig = field(default_factory=SemanticConfig)
+    config_file: str = ""  # path to the loaded yaml file
+
+
+def load_config(path: str | Path) -> CodebeaconConfig:
+    """Load and validate codebeacon.yaml from the given path."""
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"Config file not found: {path}")
+
+    with open(path) as f:
+        raw = yaml.safe_load(f)
+
+    if not isinstance(raw, dict):
+        raise ValueError(f"Invalid config file: {path}")
+
+    version = raw.get("version", 1)
+    if version != 1:
+        raise ValueError(f"Unsupported config version: {version}. Expected 1.")
+
+    projects_raw = raw.get("projects", [])
+    if not isinstance(projects_raw, list) or not projects_raw:
+        raise ValueError("Config must contain at least one project under 'projects:'")
+
+    projects = []
+    for p in projects_raw:
+        if "name" not in p or "path" not in p:
+            raise ValueError(f"Project entry missing 'name' or 'path': {p}")
+        # Resolve path relative to config file location
+        proj_path = p["path"]
+        if not os.path.isabs(proj_path):
+            proj_path = str(path.parent / proj_path)
+        projects.append(ProjectConfig(
+            name=p["name"],
+            path=proj_path,
+            type=p.get("type", "auto"),
+        ))
+
+    output_raw = raw.get("output", {})
+    context_map = output_raw.get("context_map", {})
+    output = OutputConfig(
+        dir=output_raw.get("dir", ".codebeacon"),
+        wiki=output_raw.get("wiki", True),
+        obsidian=output_raw.get("obsidian", True),
+        graph_html=output_raw.get("graph_html", True),
+        context_map_targets=context_map.get("targets", ["CLAUDE.md", ".cursorrules", "AGENTS.md"]),
+    )
+
+    wave_raw = raw.get("wave", {})
+    wave = WaveConfig(
+        auto=wave_raw.get("auto", True),
+        chunk_size=wave_raw.get("chunk_size", 300),
+        max_parallel=wave_raw.get("max_parallel", 5),
+    )
+
+    semantic_raw = raw.get("semantic", {})
+    semantic = SemanticConfig(
+        enabled=semantic_raw.get("enabled", False),
+    )
+
+    return CodebeaconConfig(
+        version=version,
+        projects=projects,
+        output=output,
+        wave=wave,
+        semantic=semantic,
+        config_file=str(path),
+    )
+
+
+def find_config(start_dir: str | Path) -> Optional[Path]:
+    """Search for codebeacon.yaml starting from start_dir."""
+    start_dir = Path(start_dir)
+    candidates = [
+        start_dir / "codebeacon.yaml",
+        start_dir / "codebeacon.yml",
+    ]
+    for c in candidates:
+        if c.exists():
+            return c
+    return None
+
+
+def generate_config(projects: list, output_dir: str, config_path: str | Path) -> None:
+    """Write an auto-generated codebeacon.yaml for multi-project scans."""
+    config_path = Path(config_path)
+    data = {
+        "version": 1,
+        "projects": [
+            {"name": p.name, "path": p.path, "type": p.framework}
+            for p in projects
+        ],
+        "output": {"dir": output_dir},
+        "wave": {"auto": True, "chunk_size": 300, "max_parallel": 5},
+        "semantic": {"enabled": False},
+    }
+    with open(config_path, "w") as f:
+        yaml.dump(data, f, default_flow_style=False, allow_unicode=True, sort_keys=False)