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

sourcecode/retrieval/planner.py

@@ -0,0 +1,297 @@
+"""QueryPlanner — translate a ResolvedIntent into a declarative KnowledgeQuery
+(design §4.3). It PLANS only: it never executes and never reads the graph.
+
+One entry per intent in the plan registry. Adding an intent adds a plan builder here
+(plus the enum member and a resolver strategy); the executor is untouched whenever the
+plan is composed of existing steps — which is the Phase-2 extensibility contract.
+"""
+from __future__ import annotations
+
+from typing import Callable
+
+from sourcecode.retrieval.errors import UnknownIntentError
+from sourcecode.retrieval.query import (
+    BuildResult,
+    Characterize,
+    CollectEvidence,
+    CollectImpactEvidence,
+    ComputeBlastRadius,
+    KnowledgeQuery,
+    RankByRisk,
+    RankByScore,
+    ResolveDependents,
+    ResolveEndpoints,
+    ResolveIntegrations,
+    ResolveModules,
+    ResolvePropagation,
+    ResolveSecurityChain,
+    ResolveSecuritySurface,
+    ResolveTarget,
+    ResolveTransactionEntrypoints,
+    ResolveTransactionFlow,
+    ResolveTransactions,
+    ResolveValidationPoints,
+    RankByCriticality,
+    CollectSecurityEvidence,
+    ResolveEndpointInventory,
+    ResolveIntegrationInventory,
+    ResolveEventTopology,
+    CollectInterfaceEvidence,
+    ResolveScope,
+    ResolveSubsystemInventory,
+    ResolveSubsystemMembers,
+    ResolveModuleDependents,
+    ResolveModuleDependencies,
+    ResolveTypeDependents,
+    CollectStructureEvidence,
+    ResolveEndpointRef,
+    ResolveEndpointContract,
+    ResolveEndpointSecurity,
+    ResolveCallNeighborhood,
+    CollectEndpointEvidence,
+    ResolveExecutionPaths,
+    ResolveTransactionsReaching,
+    ResolveSubsystemCoupling,
+    CollectGraphEvidence,
+    Step,
+)
+from sourcecode.retrieval.request import RetrievalIntent
+from sourcecode.retrieval.resolution import ResolvedIntent
+
+
+class QueryPlanner:
+    """Maps `ResolvedIntent → KnowledgeQuery`."""
+
+    def __init__(self) -> None:
+        # Both architecture intents share ONE plan shape, differing only in the archetype
+        # dimension — the clearest demonstration that a new intent is a new *plan*, not
+        # new runtime. Adding a further intent is another entry here; nothing else.
+        self._plans: dict[RetrievalIntent, Callable[[ResolvedIntent], KnowledgeQuery]] = {
+            RetrievalIntent.ARCHITECTURAL_CORE: lambda r: self._characterization_plan(
+                r, "software_archetype"
+            ),
+            RetrievalIntent.ARCHITECTURAL_STYLE: lambda r: self._characterization_plan(
+                r, "architectural_style"
+            ),
+            RetrievalIntent.DEPLOYMENT_SHAPE: lambda r: self._characterization_plan(
+                r, "deployment_shape"
+            ),
+            RetrievalIntent.PRIMARY_INTERFACE: lambda r: self._characterization_plan(
+                r, "primary_interface"
+            ),
+            # IMPACT pack — each intent is a distinct COMPOSITION of shared steps. The
+            # projection step (in the middle) is the only difference between four of them.
+            RetrievalIntent.BLAST_RADIUS: lambda r: self._impact_plan(
+                r, ResolveDependents(), rank=True
+            ),
+            RetrievalIntent.AFFECTED_ENDPOINTS: lambda r: self._impact_plan(r, ResolveEndpoints()),
+            RetrievalIntent.AFFECTED_INTEGRATIONS: lambda r: self._impact_plan(
+                r, ResolveIntegrations()
+            ),
+            RetrievalIntent.TRANSACTION_BOUNDARIES: lambda r: self._impact_plan(
+                r, ResolveTransactions()
+            ),
+            RetrievalIntent.CROSS_MODULE_IMPACT: lambda r: self._impact_plan(r, ResolveModules()),
+            # TRANSACTIONS & SECURITY pack — each intent is a projection step + the shared
+            # RankByCriticality → CollectSecurityEvidence → BuildResult tail. SECURITY_CHAIN
+            # additionally reuses the impact pack's ResolveTarget (cross-pack step reuse).
+            RetrievalIntent.TRANSACTION_FLOW: lambda r: self._txsec_plan(r, ResolveTransactionFlow()),
+            RetrievalIntent.TRANSACTION_ENTRYPOINTS: lambda r: self._txsec_plan(
+                r, ResolveTransactionEntrypoints()
+            ),
+            RetrievalIntent.TRANSACTION_PROPAGATION: lambda r: self._txsec_plan(r, ResolvePropagation()),
+            RetrievalIntent.SECURITY_SURFACE: lambda r: self._txsec_plan(r, ResolveSecuritySurface()),
+            RetrievalIntent.SECURITY_CHAIN: lambda r: self._txsec_plan(
+                r, ResolveSecurityChain(), target=True
+            ),
+            RetrievalIntent.VALIDATION_POINTS: lambda r: self._txsec_plan(r, ResolveValidationPoints()),
+            # INTERFACES & INTEGRATIONS pack — whole-repo inventories. Each intent is a
+            # single projection step + the shared CollectInterfaceEvidence → BuildResult
+            # tail. No target, no ranking (inventories are deterministically ordered).
+            RetrievalIntent.ENDPOINT_INVENTORY: lambda r: self._interface_plan(
+                r, ResolveEndpointInventory()
+            ),
+            RetrievalIntent.INTEGRATION_INVENTORY: lambda r: self._interface_plan(
+                r, ResolveIntegrationInventory()
+            ),
+            RetrievalIntent.EVENT_TOPOLOGY: lambda r: self._interface_plan(r, ResolveEventTopology()),
+            # SUBSYSTEMS & DEPENDENCIES pack — inventory is whole-repo; members/dependents/
+            # dependencies are scoped, prepending the shared ResolveScope. Each intent is a
+            # single projection + the shared CollectStructureEvidence → BuildResult tail.
+            RetrievalIntent.SUBSYSTEM_INVENTORY: lambda r: self._structure_plan(
+                r, ResolveSubsystemInventory()
+            ),
+            RetrievalIntent.SUBSYSTEM_MEMBERS: lambda r: self._structure_plan(
+                r, ResolveSubsystemMembers(), scope=True
+            ),
+            RetrievalIntent.MODULE_DEPENDENTS: lambda r: self._structure_plan(
+                r, ResolveModuleDependents(), scope=True
+            ),
+            RetrievalIntent.MODULE_DEPENDENCIES: lambda r: self._structure_plan(
+                r, ResolveModuleDependencies(), scope=True
+            ),
+            # TYPE_DEPENDENTS is symbol-scoped: it reuses the impact pack's ResolveTarget
+            # head (cross-pack step reuse) instead of ResolveScope.
+            RetrievalIntent.TYPE_DEPENDENTS: lambda r: self._structure_plan(
+                r, ResolveTypeDependents(), head=ResolveTarget()
+            ),
+            # ENDPOINT & CALL deep-dive pack — endpoint-scoped intents bind via the shared
+            # ResolveEndpointRef; call-neighborhood reuses the impact pack's ResolveTarget.
+            RetrievalIntent.ENDPOINT_CONTRACT: lambda r: self._endpoint_plan(
+                r, ResolveEndpointContract(), head=ResolveEndpointRef()
+            ),
+            RetrievalIntent.ENDPOINT_SECURITY: lambda r: self._endpoint_plan(
+                r, ResolveEndpointSecurity(), head=ResolveEndpointRef()
+            ),
+            RetrievalIntent.CALL_NEIGHBORHOOD: lambda r: self._endpoint_plan(
+                r, ResolveCallNeighborhood(), head=ResolveTarget()
+            ),
+            # GRAPH-analysis pack — the symbol-scoped intents reuse the impact pack's
+            # ResolveTarget head; subsystem-coupling is whole-repo.
+            RetrievalIntent.EXECUTION_PATHS_THROUGH: lambda r: self._graph_plan(
+                r, ResolveExecutionPaths(), head=ResolveTarget()
+            ),
+            RetrievalIntent.TRANSACTIONS_REACHING: lambda r: self._graph_plan(
+                r, ResolveTransactionsReaching(), head=ResolveTarget()
+            ),
+            RetrievalIntent.SUBSYSTEM_COUPLING: lambda r: self._graph_plan(
+                r, ResolveSubsystemCoupling()
+            ),
+        }
+
+    def plan(self, resolved: ResolvedIntent) -> KnowledgeQuery:
+        builder = self._plans.get(resolved.intent)
+        if builder is None:
+            raise UnknownIntentError(f"no plan for intent {resolved.intent!r}")
+        return builder(resolved)
+
+    # ── plans ────────────────────────────────────────────────────────────────────
+    @staticmethod
+    def _characterization_plan(resolved: ResolvedIntent, dimension: str) -> KnowledgeQuery:
+        """Characterize one archetype dimension, rank candidates by the engine's own
+        scores, collect the winning evidence + graph-topology observations, and build the
+        typed result. Pure composition of existing capabilities."""
+        return KnowledgeQuery(
+            intent=resolved.intent,
+            steps=(
+                Characterize(dimension=dimension),
+                RankByScore(),
+                CollectEvidence(),
+                BuildResult(),
+            ),
+        )
+
+    @staticmethod
+    def _impact_plan(
+        resolved: ResolvedIntent, projection: Step, *, rank: bool = False
+    ) -> KnowledgeQuery:
+        """Resolve the target, run the blast engine ONCE, project the requested slice,
+        (optionally rank by risk), collect evidence, build the result. Every impact intent
+        is this shape with a different `projection` step — the reuse the pack demonstrates."""
+        middle: tuple[Step, ...] = (projection, RankByRisk()) if rank else (projection,)
+        return KnowledgeQuery(
+            intent=resolved.intent,
+            steps=(
+                ResolveTarget(),
+                ComputeBlastRadius(),
+                *middle,
+                CollectImpactEvidence(),
+                BuildResult(),
+            ),
+        )
+
+    @staticmethod
+    def _txsec_plan(
+        resolved: ResolvedIntent, projection: Step, *, target: bool = False
+    ) -> KnowledgeQuery:
+        """Project a transactions/security question from an existing engine, rank by the
+        engine's own criticality, collect evidence, build the result. Every tx/security
+        intent is this shape with a different `projection`; `target=True` prepends the
+        shared ResolveTarget for scoped intents (SECURITY_CHAIN)."""
+        head: tuple[Step, ...] = (ResolveTarget(),) if target else ()
+        return KnowledgeQuery(
+            intent=resolved.intent,
+            steps=(
+                *head,
+                projection,
+                RankByCriticality(),
+                CollectSecurityEvidence(),
+                BuildResult(),
+            ),
+        )
+
+    @staticmethod
+    def _interface_plan(resolved: ResolvedIntent, projection: Step) -> KnowledgeQuery:
+        """Project a whole-repo interfaces/integrations inventory from an existing engine,
+        collect evidence, build the result. Every intent in the pack is this shape with a
+        different `projection` — the reuse the pack demonstrates."""
+        return KnowledgeQuery(
+            intent=resolved.intent,
+            steps=(
+                projection,
+                CollectInterfaceEvidence(),
+                BuildResult(),
+            ),
+        )
+
+    @staticmethod
+    def _structure_plan(
+        resolved: ResolvedIntent,
+        projection: Step,
+        *,
+        scope: bool = False,
+        head: Step | None = None,
+    ) -> KnowledgeQuery:
+        """Project a subsystems/dependencies question from the repo_ir subsystem partition
+        or the module graph, collect evidence, build the result. `scope=True` prepends the
+        shared ResolveScope; `head` supplies an explicit binding step (e.g. the impact
+        pack's ResolveTarget for the symbol-scoped TYPE_DEPENDENTS)."""
+        head_steps: tuple[Step, ...]
+        if head is not None:
+            head_steps = (head,)
+        elif scope:
+            head_steps = (ResolveScope(),)
+        else:
+            head_steps = ()
+        return KnowledgeQuery(
+            intent=resolved.intent,
+            steps=(
+                *head_steps,
+                projection,
+                CollectStructureEvidence(),
+                BuildResult(),
+            ),
+        )
+
+    @staticmethod
+    def _graph_plan(
+        resolved: ResolvedIntent, projection: Step, *, head: Step | None = None
+    ) -> KnowledgeQuery:
+        """Project a graph-analysis question from an existing engine (Spring call chain,
+        tx index, module graph), collect evidence, build the result. `head` supplies the
+        symbol binder (ResolveTarget) for the scoped intents; subsystem-coupling has none."""
+        head_steps: tuple[Step, ...] = (head,) if head is not None else ()
+        return KnowledgeQuery(
+            intent=resolved.intent,
+            steps=(
+                *head_steps,
+                projection,
+                CollectGraphEvidence(),
+                BuildResult(),
+            ),
+        )
+
+    @staticmethod
+    def _endpoint_plan(resolved: ResolvedIntent, projection: Step, *, head: Step) -> KnowledgeQuery:
+        """Bind an endpoint/symbol reference, project the scoped contract / security / call
+        neighborhood from an existing engine, collect evidence, build the result. Every
+        intent in the pack is this shape with a different `head` binder + `projection`."""
+        return KnowledgeQuery(
+            intent=resolved.intent,
+            steps=(
+                head,
+                projection,
+                CollectEndpointEvidence(),
+                BuildResult(),
+            ),
+        )