sourcecode 2.4.0__py3-none-any.whl → 2.5.0__py3-none-any.whl

sourcecode/retrieval/steps_graph.py

@@ -0,0 +1,248 @@
+"""GRAPH-analysis pack step handlers (Fase 11).
+
+Three intents (EXECUTION_PATHS_THROUGH, TRANSACTIONS_REACHING, SUBSYSTEM_COUPLING)
+expressed purely as compositions of these projection steps. NO new analyzer: every step
+reuses an engine already wired into the shared `KnowledgeContext`.
+
+* Execution paths → `spring_impact.run_impact_chain` (the SAME Spring-aware call-chain
+  engine the `impact-chain` command uses — multi-hop caller reachability with TX/SEC
+  enrichment). Distinct from BLAST_RADIUS, which uses the structural repo_ir engine.
+* Transactions reaching → the caller reachability from run_impact_chain ∩ the
+  `SpringSemanticModel.tx_index` boundaries.
+* Subsystem coupling → the module graph summary (hubs / cycles / orphans, from
+  `GraphAnalyzer`) + the repo_ir subsystem partition.
+
+The two symbol-scoped intents reuse the impact pack's `ResolveTarget` head (cross-pack step
+reuse). No step opens source or parses.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sourcecode.retrieval.query import (
+    CollectGraphEvidence,
+    ResolveExecutionPaths,
+    ResolveSubsystemCoupling,
+    ResolveTransactionsReaching,
+    Step,
+)
+from sourcecode.retrieval.result import (
+    Explanation,
+    KnowledgeEntity,
+    Observation,
+    Provenance,
+    RetrievalEvidence,
+)
+from sourcecode.retrieval.steps import (
+    SLOT_CONFIDENCE,
+    SLOT_ENTITIES,
+    SLOT_EVIDENCE,
+    SLOT_EXPLANATION,
+    SLOT_OBSERVATIONS,
+    SLOT_PROVENANCE,
+)
+from sourcecode.retrieval.steps_impact import SLOT_TARGET
+
+if TYPE_CHECKING:
+    from sourcecode.retrieval.runtime import StepContext, StepRegistry
+
+SLOT_SERVICES = "graph_services"
+_MODULE_PREFIX = "module:"
+
+
+# ── execution paths (spring_impact.run_impact_chain) ─────────────────────────────
+def resolve_execution_paths(step: Step, ctx: "StepContext") -> None:
+    """The multi-hop caller reachability through the target symbol, from run_impact_chain.
+    Reuses the impact pack's ResolveTarget for the symbol."""
+    assert isinstance(step, ResolveExecutionPaths)
+    result = _impact_chain(ctx)
+    entities = [
+        KnowledgeEntity(identity=fqn, kind="execution_path", score=0.0, attributes={"reach": "direct"})
+        for fqn in result.direct_callers
+    ] + [
+        KnowledgeEntity(identity=fqn, kind="execution_path", score=0.0, attributes={"reach": "indirect"})
+        for fqn in result.indirect_callers
+    ]
+    ctx.put(SLOT_ENTITIES, entities)
+    ctx.put(
+        SLOT_OBSERVATIONS,
+        [
+            Observation(name="direct_callers", value=len(result.direct_callers), detail="run_impact_chain"),
+            Observation(name="indirect_callers", value=len(result.indirect_callers), detail="run_impact_chain"),
+            Observation(name="endpoints_affected", value=len(result.endpoints_affected), detail="run_impact_chain"),
+            Observation(name="risk_level", value=result.risk_level, detail="run_impact_chain"),
+            Observation(name="risk_score", value=result.risk_score, detail="run_impact_chain"),
+        ],
+    )
+    ctx.put(
+        SLOT_EXPLANATION,
+        Explanation(
+            winner=result.symbol,
+            score=float(result.risk_score or 0.0),
+            confidence=result.confidence,
+            top_contributions=(),
+            runner_up=None,
+            engine_explanation=result.explanation or "",  # verbatim engine text
+        ),
+    )
+    ctx.put(SLOT_CONFIDENCE, result.confidence)
+    _add_service(ctx, "run_impact_chain")
+
+
+# ── transactions reaching (impact chain callers ∩ tx_index) ──────────────────────
+def resolve_transactions_reaching(step: Step, ctx: "StepContext") -> None:
+    """The @Transactional boundaries whose enclosing class can reach the target through the
+    call chain. Reuses run_impact_chain (reachability) + the tx boundary index."""
+    assert isinstance(step, ResolveTransactionsReaching)
+    result = _impact_chain(ctx)
+    caller_classes = {_enclosing_class(c) for c in result.direct_callers} | {
+        _enclosing_class(c) for c in result.indirect_callers
+    }
+    boundaries = [
+        b for b in ctx.knowledge.spring_model.tx_index.all_declared
+        if _enclosing_class(b.symbol) in caller_classes
+    ]
+    ctx.put(
+        SLOT_ENTITIES,
+        [
+            KnowledgeEntity(
+                identity=b.symbol,
+                kind="transaction_reaching",
+                score=0.0,
+                attributes={
+                    "propagation": b.propagation,
+                    "read_only": b.read_only,
+                    "confidence": b.confidence,
+                },
+            )
+            for b in boundaries
+        ],
+    )
+    ctx.put(
+        SLOT_EVIDENCE,
+        [
+            RetrievalEvidence(
+                signal="transactional",
+                detail=f"@Transactional({b.propagation}) reaches {result.symbol}",
+                weight=1.0,
+                strength=1.0,
+                mass=1.0,
+                contribution=1.0,
+                provider="SpringSemanticModel + run_impact_chain",
+                source_file=b.source_file or None,
+            )
+            for b in boundaries
+        ],
+    )
+    ctx.put(
+        SLOT_OBSERVATIONS,
+        [
+            Observation(name="reaching_transactions", value=len(boundaries), detail="tx ∩ callers"),
+            Observation(name="caller_classes", value=len(caller_classes), detail="run_impact_chain"),
+        ],
+    )
+    ctx.put(SLOT_CONFIDENCE, "high" if boundaries else "low")
+    _add_service(ctx, "run_impact_chain")
+    _add_service(ctx, "SpringSemanticModel")
+
+
+# ── subsystem coupling (module graph summary + subsystems) ───────────────────────
+def resolve_subsystem_coupling(step: Step, ctx: "StepContext") -> None:
+    """Coupling structure of the repository: the module graph's hub / cycle / orphan
+    summary + the subsystem partition. Reuses the built module graph and repo_ir."""
+    assert isinstance(step, ResolveSubsystemCoupling)
+    mg = ctx.knowledge.module_graph
+    if mg is None:
+        summary = None
+        hubs: list = []
+    else:
+        summary = mg.summary
+        hubs = list(getattr(summary, "hubs", []) or [])
+    entities = [
+        KnowledgeEntity(
+            identity=_node_path(h), kind="coupling_hub", score=0.0, attributes={"role": "hub"}
+        )
+        for h in hubs
+    ]
+    ctx.put(SLOT_ENTITIES, entities)
+    subsystems = ctx.knowledge.repo_ir.get("subsystems", []) or []
+    obs = [Observation(name="subsystems", value=len(subsystems), detail="repo_ir partition")]
+    if summary is not None:
+        obs += [
+            Observation(name="hubs", value=len(hubs), detail="module graph hubs"),
+            Observation(name="import_cycles", value=getattr(summary, "cycle_count", 0), detail="module graph"),
+            Observation(name="orphans", value=len(getattr(summary, "orphans", []) or []), detail="module graph"),
+            Observation(name="nodes", value=getattr(summary, "node_count", 0), detail="module graph"),
+            Observation(name="edges", value=getattr(summary, "edge_count", 0), detail="module graph"),
+        ]
+    ctx.put(SLOT_OBSERVATIONS, obs)
+    ctx.put(SLOT_CONFIDENCE, "high" if summary is not None else "low")
+    _add_service(ctx, "GraphAnalyzer(module_graph)")
+    _add_service(ctx, "build_repo_ir(subsystems)")
+
+
+# ── terminal evidence (generic across the pack) ──────────────────────────────────
+def collect_graph_evidence(step: Step, ctx: "StepContext") -> None:
+    """Assemble confidence, provenance, and (unless a resolve step already set a richer
+    one) a default explanation. GENERIC across the graph pack."""
+    assert isinstance(step, CollectGraphEvidence)
+    confidence = ctx.get(SLOT_CONFIDENCE, "medium")
+    if not ctx.has(SLOT_EXPLANATION):
+        ctx.put(
+            SLOT_EXPLANATION,
+            Explanation(
+                winner=None,
+                score=0.0,
+                confidence=confidence,
+                top_contributions=(),
+                runner_up=None,
+                engine_explanation="",
+            ),
+        )
+    ctx.put(
+        SLOT_PROVENANCE,
+        Provenance(
+            services=tuple(ctx.get(SLOT_SERVICES, [])),
+            signals_used=("call_chain", "tx_index", "module_graph", "subsystems"),
+            signals_missing=(),
+            knowledge_source="spring_impact + SpringSemanticModel + module graph",
+        ),
+    )
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────────
+def _impact_chain(ctx: "StepContext"):
+    from sourcecode.spring_impact import run_impact_chain
+
+    target = ctx.require(SLOT_TARGET)
+    return run_impact_chain(
+        ctx.knowledge.context_graph.cir,
+        target,
+        root=ctx.knowledge.root,
+        model=ctx.knowledge.spring_model,
+    )
+
+
+def _enclosing_class(symbol: str) -> str:
+    return symbol.split("#", 1)[0]
+
+
+def _node_path(node_id) -> str:
+    if not node_id:
+        return ""
+    return node_id[len(_MODULE_PREFIX):] if node_id.startswith(_MODULE_PREFIX) else node_id
+
+
+def _add_service(ctx: "StepContext", name: str) -> None:
+    services = list(ctx.get(SLOT_SERVICES, []))
+    if name not in services:
+        services.append(name)
+    ctx.put(SLOT_SERVICES, services)
+
+
+def register_graph_steps(registry: "StepRegistry") -> None:
+    """Register the GRAPH-analysis handlers (the sanctioned extension seam)."""
+    registry.register(ResolveExecutionPaths.kind, resolve_execution_paths)
+    registry.register(ResolveTransactionsReaching.kind, resolve_transactions_reaching)
+    registry.register(ResolveSubsystemCoupling.kind, resolve_subsystem_coupling)
+    registry.register(CollectGraphEvidence.kind, collect_graph_evidence)

sourcecode/retrieval/steps_impact.py

@@ -0,0 +1,293 @@
+"""IMPACT-pack step handlers (Fase 5).
+
+Five intents (BLAST_RADIUS, AFFECTED_ENDPOINTS, AFFECTED_INTEGRATIONS,
+TRANSACTION_BOUNDARIES, CROSS_MODULE_IMPACT) expressed purely as compositions of these
+reusable steps. Maximal reuse: every intent shares `ResolveTarget → ComputeBlastRadius →
+… → CollectImpactEvidence → BuildResult`; only the single projection step differs.
+
+All logic REUSES existing engines and recomputes nothing new:
+* `ComputeBlastRadius` calls `repository_ir.compute_blast_radius` over the acquired repo IR
+  — the SAME engine the legacy `impact` command uses, so results are identical.
+* Four of the five projections read that ONE blast dict (callers / endpoints / tx
+  boundaries / cross-module are all already computed by the engine).
+* `ResolveIntegrations` additionally reuses `SemanticIntegrationEngine`, scoped to the
+  blast cone.
+
+No step opens source or parses: the repo IR / ContextGraph are acquired once by the shared
+`KnowledgeContext` (the acquisition boundary), and steps only read them.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sourcecode.retrieval.errors import StepContractError
+from sourcecode.retrieval.query import (
+    CollectImpactEvidence,
+    ComputeBlastRadius,
+    RankByRisk,
+    ResolveDependents,
+    ResolveEndpoints,
+    ResolveIntegrations,
+    ResolveModules,
+    ResolveTarget,
+    ResolveTransactions,
+    Step,
+)
+from sourcecode.retrieval.result import (
+    Explanation,
+    KnowledgeEntity,
+    Observation,
+    Provenance,
+    RetrievalEvidence,
+)
+from sourcecode.retrieval.steps import (
+    SLOT_CONFIDENCE,
+    SLOT_ENTITIES,
+    SLOT_EVIDENCE,
+    SLOT_EXPLANATION,
+    SLOT_OBSERVATIONS,
+    SLOT_PROVENANCE,
+)
+
+if TYPE_CHECKING:
+    from sourcecode.retrieval.runtime import StepContext, StepRegistry
+
+# impact-specific slots
+SLOT_TARGET = "impact_target"
+SLOT_BLAST = "blast_radius"
+SLOT_SERVICES = "impact_services"
+
+_TARGET_ANCHOR_KINDS = ("symbol", "file")
+
+
+# ── shared knowledge-producing steps ─────────────────────────────────────────────
+def resolve_target(step: Step, ctx: "StepContext") -> None:
+    """Pick the impact target from the request's symbol/file anchor. The token is passed
+    to the blast engine, which does its own (legacy-identical) resolution."""
+    assert isinstance(step, ResolveTarget)
+    anchor = next((a for a in ctx.anchors if a.anchor.kind in _TARGET_ANCHOR_KINDS), None)
+    if anchor is None:
+        raise StepContractError("impact intents require a 'symbol' or 'file' anchor")
+    target = anchor.identities[0] if anchor.identities else anchor.anchor.raw
+    ctx.put(SLOT_TARGET, target)
+
+
+def compute_blast_radius(step: Step, ctx: "StepContext") -> None:
+    """Run `repository_ir.compute_blast_radius` once over the acquired repo IR. Every
+    projection step reads the resulting blast dict."""
+    assert isinstance(step, ComputeBlastRadius)
+    from sourcecode.repository_ir import compute_blast_radius as _compute_blast_radius
+
+    target = ctx.require(SLOT_TARGET)
+    blast = _compute_blast_radius(ctx.knowledge.repo_ir, target, max_depth=step.max_depth)
+    ctx.put(SLOT_BLAST, blast)
+    _add_service(ctx, "compute_blast_radius")
+
+
+# ── projection steps (each reads the ONE blast dict) ─────────────────────────────
+def resolve_dependents(step: Step, ctx: "StepContext") -> None:
+    blast = ctx.require(SLOT_BLAST)
+    entities = [
+        KnowledgeEntity(identity=fqn, kind="dependent", score=0.0, attributes={"reach": "direct"})
+        for fqn in blast.get("direct_callers", [])
+    ] + [
+        KnowledgeEntity(identity=fqn, kind="dependent", score=0.0, attributes={"reach": "indirect"})
+        for fqn in blast.get("indirect_callers", [])
+    ]
+    ctx.put(SLOT_ENTITIES, entities)
+
+
+def resolve_endpoints(step: Step, ctx: "StepContext") -> None:
+    blast = ctx.require(SLOT_BLAST)
+    ctx.put(
+        SLOT_ENTITIES,
+        [
+            KnowledgeEntity(
+                identity=ep.get("handler") or f"{ep.get('method', '')} {ep.get('path', '')}".strip(),
+                kind="endpoint",
+                score=0.0,
+                attributes={"method": ep.get("method", ""), "path": ep.get("path", "")},
+            )
+            for ep in blast.get("endpoints_affected", [])
+        ],
+    )
+
+
+def resolve_transactions(step: Step, ctx: "StepContext") -> None:
+    blast = ctx.require(SLOT_BLAST)
+    ctx.put(
+        SLOT_ENTITIES,
+        [
+            KnowledgeEntity(identity=fqn, kind="transaction_boundary", score=0.0)
+            for fqn in blast.get("transactional_boundaries_touched", [])
+        ],
+    )
+
+
+def resolve_modules(step: Step, ctx: "StepContext") -> None:
+    blast = ctx.require(SLOT_BLAST)
+    ctx.put(
+        SLOT_ENTITIES,
+        [
+            KnowledgeEntity(
+                identity=m.get("module", ""),
+                kind="module",
+                score=0.0,
+                attributes={k: v for k, v in m.items() if k != "module"},
+            )
+            for m in blast.get("cross_module_impact", [])
+        ],
+    )
+
+
+def resolve_integrations(step: Step, ctx: "StepContext") -> None:
+    """Reuse `SemanticIntegrationEngine`; keep only integrations declared by a type inside
+    the blast cone (matched target ∪ direct ∪ indirect callers)."""
+    assert isinstance(step, ResolveIntegrations)
+    from sourcecode.semantic_integration_engine import SemanticIntegrationEngine
+
+    blast = ctx.require(SLOT_BLAST)
+    cone = (
+        set(blast.get("matched_fqns", []))
+        | set(blast.get("direct_callers", []))
+        | set(blast.get("indirect_callers", []))
+    )
+    integrations = SemanticIntegrationEngine(ctx.knowledge.context_graph).detect()
+    _add_service(ctx, "SemanticIntegrationEngine")
+    ctx.put(
+        SLOT_ENTITIES,
+        [
+            KnowledgeEntity(
+                identity=f"{i.kind}:{i.target or i.client}",
+                kind="integration",
+                score=0.0,
+                attributes={"integration_kind": i.kind, "client": i.client, "target": i.target},
+            )
+            for i in integrations
+            if i.client in cone
+        ],
+    )
+    # integration evidence carries the declaring site (relpath:line) via the engine
+    ctx.put(
+        SLOT_EVIDENCE,
+        [
+            _integration_evidence(i)
+            for i in integrations
+            if i.client in cone
+        ],
+    )
+
+
+# ── ranking + terminal-evidence steps ────────────────────────────────────────────
+def rank_by_risk(step: Step, ctx: "StepContext") -> None:
+    """Order impacted entities using the engine's OWN direct/indirect classification — no
+    new score is computed. Deterministic: direct before indirect, then identity."""
+    assert isinstance(step, RankByRisk)
+    entities = ctx.get(SLOT_ENTITIES, [])
+    order = {"direct": 0, "indirect": 1}
+    ctx.put(
+        SLOT_ENTITIES,
+        sorted(entities, key=lambda e: (order.get(e.attributes.get("reach"), 2), e.identity)),
+    )
+
+
+def collect_impact_evidence(step: Step, ctx: "StepContext") -> None:
+    """GENERIC across all impact intents: set confidence, explanation (engine text
+    passthrough — no synthesized prose), provenance, and risk observations from the blast
+    dict. Reuses the engine's own risk/confidence; computes nothing new."""
+    assert isinstance(step, CollectImpactEvidence)
+    blast = ctx.require(SLOT_BLAST)
+    confidence = blast.get("confidence_level", "low")
+    ctx.put(SLOT_CONFIDENCE, confidence)
+    # B3: evidence parity — projections other than ResolveIntegrations produce entities but
+    # no evidence rows (the blast engine yields FQNs, not source spans). Emit one grounded-
+    # as-far-as-possible evidence row per entity so `evidence` mirrors `entities` and every
+    # hit is auditable. No span is fabricated: source_file stays None where the engine gives
+    # none (the same honest convention the archetype signals use).
+    if not ctx.has(SLOT_EVIDENCE):
+        ctx.put(
+            SLOT_EVIDENCE,
+            [
+                RetrievalEvidence(
+                    signal=e.kind,
+                    detail=e.identity,
+                    weight=1.0,
+                    strength=1.0,
+                    mass=1.0,
+                    contribution=1.0,
+                    provider="compute_blast_radius",
+                    source_file=None,
+                    source_line=None,
+                )
+                for e in ctx.get(SLOT_ENTITIES, [])
+            ],
+        )
+    ctx.put(
+        SLOT_OBSERVATIONS,
+        [
+            Observation(name="risk_score", value=blast.get("risk_score", 0.0), detail="compute_blast_radius"),
+            Observation(name="risk_level", value=blast.get("risk_level", "unknown"), detail="compute_blast_radius"),
+            Observation(name="confidence_score", value=blast.get("confidence_score", 0.0), detail="compute_blast_radius"),
+            Observation(name="resolution", value=blast.get("resolution", ""), detail="target resolution"),
+        ],
+    )
+    ctx.put(
+        SLOT_EXPLANATION,
+        Explanation(
+            winner=blast.get("target"),
+            score=float(blast.get("risk_score", 0.0)),
+            confidence=confidence,
+            top_contributions=(),
+            runner_up=None,
+            engine_explanation=blast.get("explanation", ""),  # verbatim engine text
+        ),
+    )
+    ctx.put(
+        SLOT_PROVENANCE,
+        Provenance(
+            services=tuple(ctx.get(SLOT_SERVICES, [])),
+            signals_used=("reverse_graph", "route_surface", "subsystems"),
+            signals_missing=(),
+            knowledge_source="repo IR (build_repo_ir)",
+        ),
+    )
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────────
+def _add_service(ctx: "StepContext", name: str) -> None:
+    services = list(ctx.get(SLOT_SERVICES, []))
+    if name not in services:
+        services.append(name)
+    ctx.put(SLOT_SERVICES, services)
+
+
+def _integration_evidence(i) -> RetrievalEvidence:
+    file = line = None
+    if i.evidence and ":" in i.evidence:
+        f, _, ln = i.evidence.rpartition(":")
+        file = f or None
+        line = int(ln) if ln.isdigit() else None
+    return RetrievalEvidence(
+        signal=f"integration_{i.kind}",
+        detail=f"{i.client} → {i.target or i.kind} ({i.basis})",
+        weight=1.0,
+        strength=1.0,
+        mass=1.0,
+        contribution=1.0,
+        provider="SemanticIntegrationEngine",
+        source_file=file,
+        source_line=line,
+    )
+
+
+def register_impact_steps(registry: "StepRegistry") -> None:
+    """Register the IMPACT-pack handlers into a registry (the sanctioned extension seam)."""
+    registry.register(ResolveTarget.kind, resolve_target)
+    registry.register(ComputeBlastRadius.kind, compute_blast_radius)
+    registry.register(ResolveDependents.kind, resolve_dependents)
+    registry.register(ResolveEndpoints.kind, resolve_endpoints)
+    registry.register(ResolveIntegrations.kind, resolve_integrations)
+    registry.register(ResolveTransactions.kind, resolve_transactions)
+    registry.register(ResolveModules.kind, resolve_modules)
+    registry.register(RankByRisk.kind, rank_by_risk)
+    registry.register(CollectImpactEvidence.kind, collect_impact_evidence)