sourcecode 1.35.1__py3-none-any.whl → 1.35.3__py3-none-any.whl

sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.35.1"
+__version__ = "1.35.3"

sourcecode/canonical_ir.py

@@ -20,8 +20,11 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Optional
 
+from sourcecode.cir_graphs import ImplementationGraph, InjectionGraph
 from sourcecode.repository_ir import (
     build_repo_ir,
+)
+from sourcecode.repository_ir import (
     compute_blast_radius as _compute_blast_radius,
 )
 
@@ -78,7 +81,7 @@ class CanonicalSecurity:
     @classmethod
     def from_policy_dict(
         cls, d: dict, *, source_scope: str = "method"
-    ) -> "CanonicalSecurity":
+    ) -> CanonicalSecurity:
         """Build from the policy dict emitted by _route_security_from_sym."""
         return cls(
             policy=d.get("policy", ""),
@@ -165,6 +168,15 @@ class CanonicalRepositoryIR:
     endpoints: list[CanonicalEndpoint]                        # canonical endpoint list
     security_index: dict[str, CanonicalSecurity]              # handler_symbol → security
     metadata: dict[str, Any]                                  # stats, gaps, subsystems, etc.
+    # Derived graph indices — built from dependencies at CIR construction time.
+    # CH-001: interface → implementation(s) lookup
+    implementation_graph: ImplementationGraph = field(
+        default_factory=ImplementationGraph, repr=False, compare=False
+    )
+    # CH-002: DI injection dependency → dependents + field/constructor lifting
+    injection_graph: InjectionGraph = field(
+        default_factory=InjectionGraph, repr=False, compare=False
+    )
     # Raw IR dict retained for projections that need full IR fields
     # (e.g. project_blast_radius delegates to compute_blast_radius)
     _raw_ir: dict = field(default_factory=dict, repr=False, compare=False)
@@ -339,6 +351,11 @@ def ir_dict_to_canonical(
         IR_SCHEMA_VERSION, files, symbols, endpoints, call_graph
     )
 
+    # Derived graph indices built from dependency edges
+    known_symbols: set[str] = set(symbols)
+    impl_graph = ImplementationGraph.build(dependencies, known_symbols)
+    inj_graph = InjectionGraph.build(dependencies)
+
     return CanonicalRepositoryIR(
         schema_version=IR_SCHEMA_VERSION,
         cir_hash=cir_hash,
@@ -350,6 +367,8 @@ def ir_dict_to_canonical(
         endpoints=endpoints,
         security_index=security_index,
         metadata=metadata,
+        implementation_graph=impl_graph,
+        injection_graph=inj_graph,
         _raw_ir=ir,
     )
 

sourcecode/cir_graphs.py

@@ -0,0 +1,186 @@
+"""cir_graphs.py — Derived graph indices built from CanonicalRepositoryIR.
+
+ImplementationGraph (CH-001): interface → implementation(s) lookup.
+InjectionGraph     (CH-002): DI dependency → dependents lookup, with field/constructor lifting.
+
+Both are built from cir.dependencies (implements + injects edges) and are keyed to
+known CIR symbols only.  External interfaces (java.io.Serializable, etc.) are excluded.
+
+Architecture constraint: these classes depend only on CIR data.  They must never import
+from spring_model, spring_impact, or any semantic layer.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# ---------------------------------------------------------------------------
+# ImplementationGraph — CH-001
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ImplementationGraph:
+    """Maps interface FQNs to their in-repo implementing classes, and vice-versa.
+
+    Built from implements edges where BOTH ends are known CIR symbols (internal
+    interface/class pairs).  External framework interfaces are excluded.
+    """
+    _impl_of: dict[str, list[str]] = field(default_factory=dict)
+    _ifaces_of: dict[str, list[str]] = field(default_factory=dict)
+
+    # ---------------------------------------------------------------------------
+    # Queries
+    # ---------------------------------------------------------------------------
+
+    def implementations_of(self, interface_fqn: str) -> list[str]:
+        """Return FQNs of classes that implement interface_fqn (in-repo only)."""
+        return self._impl_of.get(interface_fqn, [])
+
+    def interfaces_of(self, class_fqn: str) -> list[str]:
+        """Return FQNs of in-repo interfaces implemented by class_fqn."""
+        return self._ifaces_of.get(class_fqn, [])
+
+    def primary_implementation(self, interface_fqn: str) -> str | None:
+        """Return the single implementation if unambiguous, else None.
+
+        A single implementation is unambiguous by definition.
+        Multiple implementations are ambiguous — callers must decide.
+        @Primary detection is not yet implemented (requires annotation data in CIR).
+        """
+        impls = self._impl_of.get(interface_fqn, [])
+        return impls[0] if len(impls) == 1 else None
+
+    def has_implementations(self, interface_fqn: str) -> bool:
+        return bool(self._impl_of.get(interface_fqn))
+
+    # ---------------------------------------------------------------------------
+    # Builder
+    # ---------------------------------------------------------------------------
+
+    @classmethod
+    def build(
+        cls,
+        dependencies: list[dict],
+        known_symbols: set[str],
+    ) -> ImplementationGraph:
+        """Build from CIR dependencies list, restricting to known in-repo symbols.
+
+        Args:
+            dependencies:  cir.dependencies — list of edge dicts with 'from'/'to'/'type'
+            known_symbols: set(cir.symbols) — only in-repo FQNs
+
+        Excludes implements edges where the interface (to_fqn) is NOT in known_symbols
+        (e.g. java.io.Serializable, org.springframework.* framework interfaces).
+        Includes edges where the implementing class (from_fqn) is NOT in known_symbols
+        only when the interface IS known — this handles partial-parse edge cases.
+        """
+        impl_of: dict[str, list[str]] = {}
+        ifaces_of: dict[str, list[str]] = {}
+
+        for edge in dependencies:
+            if edge.get("type") != "implements":
+                continue
+            from_fqn = (edge.get("from") or "").strip()
+            to_fqn = (edge.get("to") or "").strip()
+            if not from_fqn or not to_fqn:
+                continue
+            # Only track when the interface is an in-repo symbol
+            if to_fqn not in known_symbols:
+                continue
+            # Ignore malformed FQNs (e.g. generic type fragments like "Long>")
+            if ">" in to_fqn or "<" in to_fqn:
+                continue
+            if ">" in from_fqn or "<" in from_fqn:
+                continue
+
+            if from_fqn not in impl_of.get(to_fqn, []):
+                impl_of.setdefault(to_fqn, []).append(from_fqn)
+            if to_fqn not in ifaces_of.get(from_fqn, []):
+                ifaces_of.setdefault(from_fqn, []).append(to_fqn)
+
+        return cls(_impl_of=impl_of, _ifaces_of=ifaces_of)
+
+
+# ---------------------------------------------------------------------------
+# InjectionGraph — CH-002
+# ---------------------------------------------------------------------------
+
+@dataclass
+class InjectionGraph:
+    """Maps DI injection edges to class-level dependency relationships.
+
+    Resolves field FQN and constructor FQN injectors to their enclosing class,
+    enabling BFS traversal to continue past injection boundaries.
+
+    Injects edge forms:
+      constructor: ClassName#<init> → DependencyFQN
+      field:       ClassName#fieldName → DependencyFQN
+      lombok:      ClassName → DependencyFQN   (already class-level)
+    """
+    _deps_of: dict[str, list[str]] = field(default_factory=dict)
+    _dependents_of: dict[str, list[str]] = field(default_factory=dict)
+    # Maps field/constructor FQN → enclosing class FQN
+    _injector_to_class: dict[str, str] = field(default_factory=dict)
+
+    # ---------------------------------------------------------------------------
+    # Queries
+    # ---------------------------------------------------------------------------
+
+    def dependencies_of(self, class_fqn: str) -> list[str]:
+        """Return service FQNs injected into class_fqn (de-duplicated, sorted)."""
+        return self._deps_of.get(class_fqn, [])
+
+    def dependents_of(self, service_fqn: str) -> list[str]:
+        """Return class FQNs that inject service_fqn (class-level, de-duplicated)."""
+        return self._dependents_of.get(service_fqn, [])
+
+    def class_of_injector(self, injector_fqn: str) -> str | None:
+        """Resolve a field/constructor FQN to its enclosing class.
+
+        Returns None if injector_fqn is not a known injection site.
+        """
+        return self._injector_to_class.get(injector_fqn)
+
+    # ---------------------------------------------------------------------------
+    # Builder
+    # ---------------------------------------------------------------------------
+
+    @classmethod
+    def build(cls, dependencies: list[dict]) -> InjectionGraph:
+        """Build from CIR dependencies list.
+
+        Args:
+            dependencies: cir.dependencies — list of edge dicts with 'from'/'to'/'type'
+        """
+        deps_of: dict[str, list[str]] = {}
+        dependents_of: dict[str, list[str]] = {}
+        injector_to_class: dict[str, str] = {}
+
+        for edge in dependencies:
+            if edge.get("type") != "injects":
+                continue
+            from_fqn = (edge.get("from") or "").strip()
+            to_fqn = (edge.get("to") or "").strip()
+            if not from_fqn or not to_fqn:
+                continue
+
+            # Resolve injector to class level
+            if "#" in from_fqn:
+                class_fqn = from_fqn.rsplit("#", 1)[0]
+                injector_to_class[from_fqn] = class_fqn
+            else:
+                class_fqn = from_fqn
+
+            # Build class → [dep, ...] and service → [class, ...] indices
+            deps = deps_of.setdefault(class_fqn, [])
+            if to_fqn not in deps:
+                deps.append(to_fqn)
+
+            dependents = dependents_of.setdefault(to_fqn, [])
+            if class_fqn not in dependents:
+                dependents.append(class_fqn)
+
+        return cls(
+            _deps_of=deps_of,
+            _dependents_of=dependents_of,
+            _injector_to_class=injector_to_class,
+        )

sourcecode/cli.py

@@ -225,6 +225,8 @@ _SUBCOMMANDS: frozenset[str] = frozenset(
         "cold-start",
         # Spring semantic audit
         "spring-audit",
+        # Spring impact chain
+        "impact-chain",
     }
 )
 
@@ -3879,6 +3881,189 @@ def spring_audit_cmd(
                 typer.echo("✓ copied to clipboard", err=True)
 
 
+# ── Spring Impact Chain ───────────────────────────────────────────────────────
+
+
+@app.command("impact-chain")
+def impact_chain_cmd(
+    symbol: str = typer.Argument(
+        ...,
+        help=(
+            "Symbol to query: FQN, class name, or Class#method. "
+            "Examples: OrderService, com.example.OrderService#placeOrder"
+        ),
+    ),
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository root (default: current directory)",
+    ),
+    depth: int = typer.Option(
+        4,
+        "--depth",
+        help="Indirect caller BFS depth (1–8, default: 4).",
+        min=1,
+        max=8,
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o",
+        help="Write output to a file instead of stdout.",
+    ),
+    format: str = typer.Option(
+        "json", "--format", "-f",
+        help="Output format: json (default) or yaml.",
+        show_default=True,
+    ),
+    copy: bool = typer.Option(
+        False, "--copy", "-c",
+        help="Copy output to clipboard after a successful run.",
+    ),
+    query_type: str = typer.Option(
+        "impact", "--type", "-t",
+        help="Query type: impact (default) or events.",
+        show_default=True,
+    ),
+) -> None:
+    """Spring impact-chain: systemic blast radius of a symbol with TX/SEC enrichment.
+
+    \b
+    Given a symbol (class or method), returns:
+      - direct_callers      — symbols that directly call the target
+      - indirect_callers    — transitive callers (BFS up to --depth hops)
+      - endpoints_affected  — HTTP endpoints reachable through the call chain
+      - transaction_boundary — @Transactional semantics on the target (if any)
+      - security_surfaces   — per-endpoint security policy + SEC findings
+      - impact_findings     — TX/SEC audit findings touching the call chain
+      - risk_level          — critical | high | medium | low
+
+    \b
+    With --type events, returns event topology:
+      - publishers          — FQNs that publish the event class
+      - consumers           — listeners with TX phase metadata
+      - event_graph         — publisher → event → consumer edges (BFS ≤ 2)
+      - transaction_context — AFTER_COMMIT consumers, BEFORE_COMMIT risks
+      - risk_level          — high | medium | low
+
+    \b
+    Consumes SpringSemanticModel — zero duplicate CIR traversals.
+    JAVA/SPRING ONLY.
+
+    \b
+    Examples:
+      sourcecode impact-chain OrderService .
+      sourcecode impact-chain com.example.OrderService#placeOrder /path/to/repo
+      sourcecode impact-chain PaymentService . --depth 6 --output impact.json
+    """
+    import json as _json
+
+    from sourcecode.repository_ir import find_java_files
+    from sourcecode.canonical_ir import build_canonical_ir
+    from sourcecode.spring_model import SpringSemanticModel
+    from sourcecode.spring_impact import run_impact_chain
+    from sourcecode.spring_findings import SpringAuditResult
+
+    _VALID_TYPES = ("impact", "events")
+    if query_type not in _VALID_TYPES:
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"Invalid --type '{query_type}'. Valid values: {', '.join(_VALID_TYPES)}",
+            flag="--type",
+            value=query_type,
+            valid_values=list(_VALID_TYPES),
+            hint="Use --type impact (default) or --type events.",
+            expected="impact | events",
+        )
+        raise typer.Exit(code=1)
+
+    target = path.resolve()
+    if not target.exists() or not target.is_dir():
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"'{target}' is not a valid directory.",
+            path=str(target),
+            hint="Pass an existing repository directory.",
+            expected="A directory path.",
+        )
+        raise typer.Exit(code=1)
+
+    if format not in ("json", "yaml"):
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"Invalid format '{format}'.",
+            hint="format must be: json or yaml.",
+            expected="json | yaml",
+        )
+        raise typer.Exit(code=1)
+
+    file_list = find_java_files(target)
+    if not file_list:
+        data: dict = {
+            "schema_version": "1.0",
+            "symbol": symbol,
+            "resolution": "not_found",
+            "analysis_warnings": ["No Java files found in repository — Spring analysis requires Java source."],
+            "risk_level": "unknown",
+            "confidence": "low",
+            "metadata": {},
+        }
+        output = _serialize_dict(data, format)
+        if output_path is not None:
+            output_path.write_text(output, encoding="utf-8")
+            typer.echo("Impact chain written to " + str(output_path), err=True)
+        else:
+            sys.stdout.buffer.write(output.encode("utf-8"))
+            sys.stdout.buffer.write(b"\n")
+            sys.stdout.buffer.flush()
+        return
+
+    cir = build_canonical_ir(file_list, target)
+    _model = SpringSemanticModel.build(cir)
+
+    if query_type == "events":
+        from sourcecode.spring_event_topology import run_event_topology
+        evt_result = run_event_topology(cir, symbol, model=_model)
+        data = evt_result.to_dict()
+        output = _serialize_dict(data, format)
+        if output_path is not None:
+            output_path.write_text(output, encoding="utf-8")
+            typer.echo(
+                f"Event topology written to {output_path} "
+                f"(risk: {evt_result.risk_level}, "
+                f"{evt_result.metadata.get('publisher_count', 0)} publishers, "
+                f"{evt_result.metadata.get('consumer_count', 0)} consumers)",
+                err=True,
+            )
+        else:
+            sys.stdout.buffer.write(output.encode("utf-8"))
+            sys.stdout.buffer.write(b"\n")
+            sys.stdout.buffer.flush()
+            if copy:
+                if _copy_to_clipboard(output):
+                    typer.echo("✓ copied to clipboard", err=True)
+        return
+
+    result = run_impact_chain(cir, symbol, depth=depth, root=target, model=_model)
+
+    data = result.to_dict()
+    output = _serialize_dict(data, format)
+
+    if output_path is not None:
+        output_path.write_text(output, encoding="utf-8")
+        typer.echo(
+            f"Impact chain written to {output_path} "
+            f"(risk: {result.risk_level}, "
+            f"{len(result.direct_callers)} direct callers, "
+            f"{len(result.endpoints_affected)} endpoints)",
+            err=True,
+        )
+    else:
+        sys.stdout.buffer.write(output.encode("utf-8"))
+        sys.stdout.buffer.write(b"\n")
+        sys.stdout.buffer.flush()
+        if copy:
+            if _copy_to_clipboard(output):
+                typer.echo("✓ copied to clipboard", err=True)
+
+
 # ── Enterprise Workflow Commands ──────────────────────────────────────────────
 #
 # These are the five canonical enterprise workflows.  Each is a thin wrapper

sourcecode/mcp/server.py

@@ -649,6 +649,46 @@ def get_spring_audit(repo_path: str = ".", scope: str = "all") -> dict:
         )
 
 
+@mcp.tool()
+def get_impact_chain(repo_path: str = ".", symbol: str = "", depth: int = 4) -> dict:
+    """Spring impact-chain: systemic blast radius of a symbol with TX/SEC semantic enrichment. JAVA/SPRING ONLY.
+
+    Do NOT call this on non-Java repositories — it will return resolution=not_found.
+
+    Maps to: sourcecode impact-chain <symbol> <repo_path> [--depth <depth>]
+    Returns: ImpactChainResult with schema_version, symbol, resolution,
+             direct_callers, indirect_callers, endpoints_affected,
+             transaction_boundary (propagation/isolation/read_only),
+             security_surfaces (per-endpoint policy + finding IDs),
+             impact_findings (TX-001..005 + SEC-001..003 findings in call chain),
+             analysis_warnings, risk_level, confidence, metadata.
+
+    symbol: FQN, class name, or Class#method. Examples:
+            "OrderService", "com.example.OrderService#placeOrder"
+    repo_path: absolute path to the Java repository (default: current working directory).
+    depth: BFS depth for indirect caller traversal (1–8, default: 4).
+    """
+    _raw = repo_path
+    try:
+        if not isinstance(repo_path, str):
+            return _err("repo_path must be a string", "INVALID_ARGUMENT")
+        if not isinstance(symbol, str) or not symbol.strip():
+            return _err("symbol must be a non-empty string", "INVALID_ARGUMENT")
+        if not isinstance(depth, int) or depth < 1 or depth > 8:
+            return _err("depth must be an integer between 1 and 8", "INVALID_ARGUMENT")
+        repo_path = _normalize_repo_path(repo_path)
+        _path_err = _check_repo_path(repo_path)
+        if _path_err is not None:
+            return _path_err
+        args = ["impact-chain", symbol.strip(), repo_path, "--depth", str(depth)]
+        return _execute(args)
+    except Exception as exc:
+        return _err(
+            f"Internal error: {type(exc).__name__}: {exc} — repo_path recibido: {_raw}",
+            "INTERNAL_ERROR",
+        )
+
+
 @mcp.tool()
 def get_module_context(repo_path: str = ".", module: str = "") -> dict:
     """Compact analysis of a specific module or subdirectory within a repository.

sourcecode/repository_ir.py

@@ -239,7 +239,7 @@ _LOMBOK_CTOR_ANNOTATIONS: frozenset[str] = frozenset({
 })
 
 # Transaction annotations whose args must be captured for semantic analysis.
-_TX_ANNOTATIONS: frozenset[str] = frozenset({"@Transactional"})
+_TX_ANNOTATIONS: frozenset[str] = frozenset({"@Transactional", "@TransactionalEventListener"})
 
 # Combined set used in _extract_symbols annotation-value capture.
 _CAPTURE_ANN_ARGS: frozenset[str] = (
@@ -307,7 +307,9 @@ _SPRING_OTHER: frozenset[str] = frozenset({
     "@PutMapping", "@DeleteMapping", "@PatchMapping", "@Autowired",
     "@Inject", "@Value", "@Qualifier", "@EnableWebSecurity",
     "@SpringBootApplication", "@EnableAutoConfiguration",
-    "@EventListener", "@Async", "@Scheduled", "@Cacheable", "@CacheEvict",
+    "@EventListener", "@TransactionalEventListener",
+    "@KafkaListener", "@RabbitListener",
+    "@Async", "@Scheduled", "@Cacheable", "@CacheEvict",
     # CDI / Jakarta EE
     "@ApplicationScoped", "@RequestScoped", "@SessionScoped", "@Dependent",
     "@Named", "@Produces", "@Consumes",
@@ -1101,16 +1103,21 @@ def _build_relations(
                 ))
 
     # Event flow edges — listens_to_event and publishes_event.
-    # Spring: method with @EventListener → resolved event parameter type(s).
+    # Spring: method with @EventListener or @TransactionalEventListener → resolved event type(s).
+    _LISTENER_ANNOTATIONS: frozenset[str] = frozenset({
+        "@EventListener", "@TransactionalEventListener",
+    })
     for sym in symbols:
-        if sym.type == "method" and "@EventListener" in sym.annotations:
+        if sym.type == "method" and (sym.annotations and
+                any(a in _LISTENER_ANNOTATIONS for a in sym.annotations)):
+            ann = next(a for a in sym.annotations if a in _LISTENER_ANNOTATIONS)
             for imp_fqn in sym.imports_used:
                 edges.append(RelationEdge(
                     from_symbol=sym.symbol,
                     to_symbol=imp_fqn,
                     type="listens_to_event",
                     confidence="high",
-                    evidence={"type": "annotation", "value": "@EventListener"},
+                    evidence={"type": "annotation", "value": ann},
                 ))
 
     _class_syms = [s for s in symbols if s.type in ("class", "interface") and "#" not in s.symbol]