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

sourcecode/retrieval/query.py

@@ -0,0 +1,484 @@
+"""KnowledgeQuery — the declarative, serializable plan and its step algebra
+(design §4.4, §5.4).
+
+A `KnowledgeQuery` is a side-effect-free VALUE describing *what* to retrieve, never *how
+the result is computed*. Steps are the closed vocabulary of retrieval operations; each is
+pure data (a `kind` + parameters) carrying **no execution logic** — all execution logic
+lives in the Query Plan Runtime's step handlers. Because a step is data, a plan is:
+
+* **serializable** — `to_dict()` / `from_dict()` round-trip (register/log/replay);
+* **inspectable** — `describe()` lists the step names without running anything;
+* **CLI-independent** — the same plan value is submitted from CLI, MCP, IDE, API.
+
+Adding an intent is declaring a new plan over these steps; the Runtime is untouched.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, ClassVar
+
+from sourcecode.retrieval.request import RetrievalIntent
+
+
+class Step:
+    """Marker base for a declarative retrieval operation. Frozen data, no behaviour.
+
+    `kind` is the stable, serializable discriminator the Runtime dispatches on; it is
+    decoupled from the Python class name so the wire form survives refactors."""
+
+    __slots__ = ()
+    kind: ClassVar[str] = "step"
+
+    def params(self) -> dict[str, Any]:
+        """The step's parameters as a plain, serializable dict."""
+        return {}
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"kind": self.kind, "params": self.params()}
+
+    @classmethod
+    def from_params(cls, params: dict[str, Any]) -> "Step":
+        """Rebuild a step from its serialized params. Overridden by parameterized steps."""
+        return cls()
+
+
+@dataclass(frozen=True)
+class Characterize(Step):
+    """Reuse `ArchetypeClassifier`; select one archetype `dimension`
+    (``software_archetype`` | ``architectural_style`` | …). Single responsibility:
+    obtain the dimension's scored candidates + evidence + graph metrics."""
+
+    kind: ClassVar[str] = "characterize"
+    dimension: str
+
+    def params(self) -> dict[str, Any]:
+        return {"dimension": self.dimension}
+
+    @classmethod
+    def from_params(cls, params: dict[str, Any]) -> "Characterize":
+        return cls(dimension=params["dimension"])
+
+
+@dataclass(frozen=True)
+class RankByScore(Step):
+    """Order the selected candidates by their EXISTING engine score (no new scoring).
+    Single responsibility: ranking."""
+
+    kind: ClassVar[str] = "rank_by_score"
+
+
+@dataclass(frozen=True)
+class CollectEvidence(Step):
+    """Gather the winning candidate's evidence + graph-topology observations into typed
+    structures. Single responsibility: evidence/observation assembly."""
+
+    kind: ClassVar[str] = "collect_evidence"
+
+
+@dataclass(frozen=True)
+class BuildResult(Step):
+    """Assemble the final typed `KnowledgeResult` from the shared context. A plan MUST
+    terminate in this step. Single responsibility: result construction. GENERIC — reused
+    by every pack; it reads only generic result slots, never a pack's internals."""
+
+    kind: ClassVar[str] = "build_result"
+
+
+# ── IMPACT pack steps (Fase 5) ───────────────────────────────────────────────────
+# All reuse existing engines; none extracts or re-derives knowledge.
+@dataclass(frozen=True)
+class ResolveTarget(Step):
+    """Bind the request's symbol/file anchor to the impact target token. Single
+    responsibility: pick the target from the resolved anchors."""
+
+    kind: ClassVar[str] = "resolve_target"
+
+
+@dataclass(frozen=True)
+class ComputeBlastRadius(Step):
+    """Reuse `repository_ir.compute_blast_radius` over the acquired repo IR. Produces the
+    single blast-radius dict every projection step reads. Single responsibility: run the
+    impact engine once."""
+
+    kind: ClassVar[str] = "compute_blast_radius"
+    max_depth: int = 4
+
+    def params(self) -> dict[str, Any]:
+        return {"max_depth": self.max_depth}
+
+    @classmethod
+    def from_params(cls, params: dict[str, Any]) -> "ComputeBlastRadius":
+        return cls(max_depth=int(params.get("max_depth", 4)))
+
+
+@dataclass(frozen=True)
+class ResolveDependents(Step):
+    """Project direct + indirect callers from the blast dict into entities."""
+
+    kind: ClassVar[str] = "resolve_dependents"
+
+
+@dataclass(frozen=True)
+class ResolveEndpoints(Step):
+    """Project affected endpoints from the blast dict into entities."""
+
+    kind: ClassVar[str] = "resolve_endpoints"
+
+
+@dataclass(frozen=True)
+class ResolveIntegrations(Step):
+    """Reuse `SemanticIntegrationEngine`; keep integrations whose owner is in the blast
+    cone. Single responsibility: scope integrations to the impact."""
+
+    kind: ClassVar[str] = "resolve_integrations"
+
+
+@dataclass(frozen=True)
+class ResolveTransactions(Step):
+    """Project transactional boundaries touched from the blast dict into entities."""
+
+    kind: ClassVar[str] = "resolve_transactions"
+
+
+@dataclass(frozen=True)
+class ResolveModules(Step):
+    """Project cross-module impact from the blast dict into entities."""
+
+    kind: ClassVar[str] = "resolve_modules"
+
+
+@dataclass(frozen=True)
+class RankByRisk(Step):
+    """Order the impacted entities using the engine's OWN direct/indirect classification
+    (no new score). Single responsibility: deterministic risk ordering."""
+
+    kind: ClassVar[str] = "rank_by_risk"
+
+
+@dataclass(frozen=True)
+class CollectImpactEvidence(Step):
+    """Assemble confidence, explanation (engine text passthrough), provenance, and
+    risk observations from the blast dict. GENERIC across all impact intents."""
+
+    kind: ClassVar[str] = "collect_impact_evidence"
+
+
+# ── TRANSACTIONS & SECURITY pack steps (Fase 6) ──────────────────────────────────
+# All project outputs of existing engines (Spring tx/security/validation, endpoint
+# model); none analyzes source or re-derives knowledge.
+@dataclass(frozen=True)
+class ResolveTransactionFlow(Step):
+    """Project the @Transactional boundary index (`SpringSemanticModel.tx_index`) into
+    entities. Single responsibility: the transactional boundary map."""
+
+    kind: ClassVar[str] = "resolve_transaction_flow"
+
+
+@dataclass(frozen=True)
+class ResolveTransactionEntrypoints(Step):
+    """Project the transactional boundaries that sit at the API surface (enclosing class
+    is a controller). Reuses tx_index × endpoint model."""
+
+    kind: ClassVar[str] = "resolve_transaction_entrypoints"
+
+
+@dataclass(frozen=True)
+class ResolvePropagation(Step):
+    """Project boundaries by propagation + the propagation-risk tx audit findings
+    (TX-002/003/004). Reuses tx_index + `run_tx_audit`."""
+
+    kind: ClassVar[str] = "resolve_propagation"
+
+
+@dataclass(frozen=True)
+class ResolveSecuritySurface(Step):
+    """Project the security audit findings (`run_security_audit`) into entities."""
+
+    kind: ClassVar[str] = "resolve_security_surface"
+
+
+@dataclass(frozen=True)
+class ResolveSecurityChain(Step):
+    """Project the security findings scoped to a target (its symbol / related symbols /
+    enclosing class). Reuses `run_security_audit`."""
+
+    kind: ClassVar[str] = "resolve_security_chain"
+
+
+@dataclass(frozen=True)
+class ResolveValidationPoints(Step):
+    """Project the request-body validation surface (`build_validation_surface`)."""
+
+    kind: ClassVar[str] = "resolve_validation_points"
+
+
+@dataclass(frozen=True)
+class RankByCriticality(Step):
+    """Order entities by the engines' OWN severity + confidence (no new score). Single
+    responsibility: deterministic criticality ordering. GENERIC across tx/security."""
+
+    kind: ClassVar[str] = "rank_by_criticality"
+
+
+@dataclass(frozen=True)
+class CollectSecurityEvidence(Step):
+    """Assemble confidence, provenance, and observations from the domain result (evidence
+    rows are attached by the resolve steps). GENERIC across all tx/security intents."""
+
+    kind: ClassVar[str] = "collect_security_evidence"
+
+
+# ── INTERFACES & INTEGRATIONS pack steps (Fase 7) ────────────────────────────────
+# All project already-indexed knowledge (endpoint model, integration engine, event
+# graph); none analyzes source or re-derives knowledge. Whole-repo inventories.
+@dataclass(frozen=True)
+class ResolveEndpointInventory(Step):
+    """Project the whole endpoint model (`SpringSemanticModel.endpoint_index`) into
+    entities. Single responsibility: the repository's HTTP surface."""
+
+    kind: ClassVar[str] = "resolve_endpoint_inventory"
+
+
+@dataclass(frozen=True)
+class ResolveIntegrationInventory(Step):
+    """Reuse `SemanticIntegrationEngine`; project EVERY detected integration (no cone
+    filter — the whole-repo counterpart of the impact pack's ResolveIntegrations)."""
+
+    kind: ClassVar[str] = "resolve_integration_inventory"
+
+
+@dataclass(frozen=True)
+class ResolveEventTopology(Step):
+    """Project the Spring event graph (`SpringSemanticModel.event_graph`): one entity per
+    event type with its publishers and listeners. Single responsibility: event topology."""
+
+    kind: ClassVar[str] = "resolve_event_topology"
+
+
+@dataclass(frozen=True)
+class CollectInterfaceEvidence(Step):
+    """Assemble confidence, provenance, and observations from the resolve step's output
+    (evidence rows are attached by the resolve steps). GENERIC across the interfaces/
+    integrations pack."""
+
+    kind: ClassVar[str] = "collect_interface_evidence"
+
+
+# ── SUBSYSTEMS & DEPENDENCIES pack steps (Fase 8) ────────────────────────────────
+# All project already-built knowledge (the repo_ir subsystem partition, the module
+# graph); none analyzes source or re-derives knowledge.
+@dataclass(frozen=True)
+class ResolveScope(Step):
+    """Bind the request's subsystem/module/package anchor to a scope token. Single
+    responsibility: pick the scope. Shared by the anchored structure intents."""
+
+    kind: ClassVar[str] = "resolve_scope"
+
+
+@dataclass(frozen=True)
+class ResolveSubsystemInventory(Step):
+    """Project the repo_ir subsystem partition into entities. Single responsibility: the
+    repository's subsystem map."""
+
+    kind: ClassVar[str] = "resolve_subsystem_inventory"
+
+
+@dataclass(frozen=True)
+class ResolveSubsystemMembers(Step):
+    """Project the member symbols of the scoped subsystem. Reuses the repo_ir partition."""
+
+    kind: ClassVar[str] = "resolve_subsystem_members"
+
+
+@dataclass(frozen=True)
+class ResolveModuleDependents(Step):
+    """Project modules that depend ON the scope (reverse module-graph edges)."""
+
+    kind: ClassVar[str] = "resolve_module_dependents"
+
+
+@dataclass(frozen=True)
+class ResolveModuleDependencies(Step):
+    """Project modules the scope DEPENDS ON (forward module-graph edges)."""
+
+    kind: ClassVar[str] = "resolve_module_dependencies"
+
+
+@dataclass(frozen=True)
+class ResolveTypeDependents(Step):
+    """Project the type-level dependents of a target symbol from the repo_ir reverse graph
+    (imports / implements / injects / contained_in edges). Reuses the impact pack's
+    ResolveTarget to bind the symbol."""
+
+    kind: ClassVar[str] = "resolve_type_dependents"
+
+
+@dataclass(frozen=True)
+class CollectStructureEvidence(Step):
+    """Assemble confidence, provenance, and explanation from the resolve step's output.
+    GENERIC across the subsystems/dependencies pack."""
+
+    kind: ClassVar[str] = "collect_structure_evidence"
+
+
+# ── ENDPOINT & CALL deep-dive pack steps (Fase 10) ───────────────────────────────
+# All project already-built knowledge (validation surface, endpoint model, security
+# audit, call adjacency), scoped to an anchor; none analyzes source or re-derives.
+@dataclass(frozen=True)
+class ResolveEndpointRef(Step):
+    """Bind the request's endpoint/path/symbol anchor to a reference token. Shared head of
+    the endpoint-scoped intents."""
+
+    kind: ClassVar[str] = "resolve_endpoint_ref"
+
+
+@dataclass(frozen=True)
+class ResolveEndpointContract(Step):
+    """Project the request/validation contract of the referenced endpoint(s) from
+    `build_validation_surface`. Single responsibility: one endpoint's contract."""
+
+    kind: ClassVar[str] = "resolve_endpoint_contract"
+
+
+@dataclass(frozen=True)
+class ResolveEndpointSecurity(Step):
+    """Project the effective security of the referenced endpoint(s): the endpoint model's
+    CanonicalSecurity + the security-audit findings on the handler."""
+
+    kind: ClassVar[str] = "resolve_endpoint_security"
+
+
+@dataclass(frozen=True)
+class ResolveCallNeighborhood(Step):
+    """Project the forward callees + reverse callers of the target symbol from the call
+    adjacency. Reuses the impact pack's ResolveTarget to bind the symbol."""
+
+    kind: ClassVar[str] = "resolve_call_neighborhood"
+
+
+@dataclass(frozen=True)
+class CollectEndpointEvidence(Step):
+    """Assemble confidence, provenance, and explanation from the resolve step's output.
+    GENERIC across the endpoint/call deep-dive pack."""
+
+    kind: ClassVar[str] = "collect_endpoint_evidence"
+
+
+# ── GRAPH-analysis pack steps (Fase 11) ──────────────────────────────────────────
+# All project already-built knowledge (the Spring call-chain engine, the tx index, the
+# module graph summary); none analyzes source or re-derives knowledge.
+@dataclass(frozen=True)
+class ResolveExecutionPaths(Step):
+    """Project the multi-hop caller reachability through the target symbol from
+    `run_impact_chain`. Reuses the impact pack's ResolveTarget to bind the symbol."""
+
+    kind: ClassVar[str] = "resolve_execution_paths"
+
+
+@dataclass(frozen=True)
+class ResolveTransactionsReaching(Step):
+    """Project the @Transactional boundaries whose class can reach the target through the
+    call chain (run_impact_chain callers ∩ tx_index)."""
+
+    kind: ClassVar[str] = "resolve_transactions_reaching"
+
+
+@dataclass(frozen=True)
+class ResolveSubsystemCoupling(Step):
+    """Project the repository's coupling structure: module-graph hubs / cycles / orphans +
+    the subsystem partition."""
+
+    kind: ClassVar[str] = "resolve_subsystem_coupling"
+
+
+@dataclass(frozen=True)
+class CollectGraphEvidence(Step):
+    """Assemble confidence, provenance, and explanation from the resolve step's output.
+    GENERIC across the graph-analysis pack."""
+
+    kind: ClassVar[str] = "collect_graph_evidence"
+
+
+# ── step (de)serialization registry ─────────────────────────────────────────────
+# Maps the wire `kind` back to its Step class. New steps register here; the Runtime
+# dispatches by `kind`, this table only reconstructs a plan from its serialized form.
+_STEP_TYPES: dict[str, type[Step]] = {
+    Characterize.kind: Characterize,
+    RankByScore.kind: RankByScore,
+    CollectEvidence.kind: CollectEvidence,
+    BuildResult.kind: BuildResult,
+    # IMPACT pack
+    ResolveTarget.kind: ResolveTarget,
+    ComputeBlastRadius.kind: ComputeBlastRadius,
+    ResolveDependents.kind: ResolveDependents,
+    ResolveEndpoints.kind: ResolveEndpoints,
+    ResolveIntegrations.kind: ResolveIntegrations,
+    ResolveTransactions.kind: ResolveTransactions,
+    ResolveModules.kind: ResolveModules,
+    RankByRisk.kind: RankByRisk,
+    CollectImpactEvidence.kind: CollectImpactEvidence,
+    # TRANSACTIONS & SECURITY pack
+    ResolveTransactionFlow.kind: ResolveTransactionFlow,
+    ResolveTransactionEntrypoints.kind: ResolveTransactionEntrypoints,
+    ResolvePropagation.kind: ResolvePropagation,
+    ResolveSecuritySurface.kind: ResolveSecuritySurface,
+    ResolveSecurityChain.kind: ResolveSecurityChain,
+    ResolveValidationPoints.kind: ResolveValidationPoints,
+    RankByCriticality.kind: RankByCriticality,
+    CollectSecurityEvidence.kind: CollectSecurityEvidence,
+    # INTERFACES & INTEGRATIONS pack
+    ResolveEndpointInventory.kind: ResolveEndpointInventory,
+    ResolveIntegrationInventory.kind: ResolveIntegrationInventory,
+    ResolveEventTopology.kind: ResolveEventTopology,
+    CollectInterfaceEvidence.kind: CollectInterfaceEvidence,
+    # SUBSYSTEMS & DEPENDENCIES pack
+    ResolveScope.kind: ResolveScope,
+    ResolveSubsystemInventory.kind: ResolveSubsystemInventory,
+    ResolveSubsystemMembers.kind: ResolveSubsystemMembers,
+    ResolveModuleDependents.kind: ResolveModuleDependents,
+    ResolveModuleDependencies.kind: ResolveModuleDependencies,
+    ResolveTypeDependents.kind: ResolveTypeDependents,
+    CollectStructureEvidence.kind: CollectStructureEvidence,
+    # ENDPOINT & CALL deep-dive pack
+    ResolveEndpointRef.kind: ResolveEndpointRef,
+    ResolveEndpointContract.kind: ResolveEndpointContract,
+    ResolveEndpointSecurity.kind: ResolveEndpointSecurity,
+    ResolveCallNeighborhood.kind: ResolveCallNeighborhood,
+    CollectEndpointEvidence.kind: CollectEndpointEvidence,
+    # GRAPH-analysis pack
+    ResolveExecutionPaths.kind: ResolveExecutionPaths,
+    ResolveTransactionsReaching.kind: ResolveTransactionsReaching,
+    ResolveSubsystemCoupling.kind: ResolveSubsystemCoupling,
+    CollectGraphEvidence.kind: CollectGraphEvidence,
+}
+
+
+def step_from_dict(data: dict[str, Any]) -> Step:
+    kind = data.get("kind")
+    step_cls = _STEP_TYPES.get(kind)
+    if step_cls is None:
+        raise KeyError(f"unknown step kind {kind!r}")
+    return step_cls.from_params(data.get("params") or {})
+
+
+@dataclass(frozen=True)
+class KnowledgeQuery:
+    """An ordered, declarative plan bound to the intent it serves. Holds no graph
+    handle and runs nothing."""
+
+    intent: RetrievalIntent
+    steps: tuple[Step, ...]
+
+    def describe(self) -> tuple[str, ...]:
+        """The plan as an ordered tuple of step class names — printable/explainable
+        without executing anything."""
+        return tuple(type(s).__name__ for s in self.steps)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"intent": self.intent.value, "steps": [s.to_dict() for s in self.steps]}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "KnowledgeQuery":
+        intent = RetrievalIntent(data["intent"])
+        steps = tuple(step_from_dict(s) for s in data.get("steps", ()))
+        return cls(intent=intent, steps=steps)

sourcecode/retrieval/request.py

@@ -0,0 +1,94 @@
+"""Retrieval input model — the engine's typed contract (design §5.1, §9).
+
+The engine's public input is a **typed** `RetrievalRequest`, never a natural-language
+string. Natural language → typed intent is the consumer's job, strictly upstream and
+outside this boundary. This is what keeps the engine deterministic, offline, and free of
+every prohibition (no LLM, no embeddings, no text search).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class RetrievalIntent(Enum):
+    """The catalogue of typed questions the engine can answer.
+
+    An OPEN set. Phase 2 ships exactly one member; each future capability is a new
+    member here + a plan in `QueryPlanner` + (usually) a trivial resolver strategy —
+    the `KnowledgeExecutor` is unchanged when the plan composes existing steps.
+    """
+
+    ARCHITECTURAL_CORE = "architectural-core"
+    ARCHITECTURAL_STYLE = "architectural-style"
+    DEPLOYMENT_SHAPE = "deployment-shape"
+    PRIMARY_INTERFACE = "primary-interface"
+    # IMPACT pack (Fase 5)
+    BLAST_RADIUS = "blast-radius"
+    AFFECTED_ENDPOINTS = "affected-endpoints"
+    AFFECTED_INTEGRATIONS = "affected-integrations"
+    TRANSACTION_BOUNDARIES = "transaction-boundaries"
+    CROSS_MODULE_IMPACT = "cross-module-impact"
+    # TRANSACTIONS & SECURITY pack (Fase 6)
+    TRANSACTION_FLOW = "transaction-flow"
+    TRANSACTION_ENTRYPOINTS = "transaction-entrypoints"
+    TRANSACTION_PROPAGATION = "transaction-propagation"
+    SECURITY_SURFACE = "security-surface"
+    SECURITY_CHAIN = "security-chain"
+    VALIDATION_POINTS = "validation-points"
+    # INTERFACES & INTEGRATIONS pack (Fase 7)
+    ENDPOINT_INVENTORY = "endpoint-inventory"
+    INTEGRATION_INVENTORY = "integration-inventory"
+    EVENT_TOPOLOGY = "event-topology"
+    # SUBSYSTEMS & DEPENDENCIES pack (Fase 8)
+    SUBSYSTEM_INVENTORY = "subsystem-inventory"
+    SUBSYSTEM_MEMBERS = "subsystem-members"
+    MODULE_DEPENDENTS = "module-dependents"
+    MODULE_DEPENDENCIES = "module-dependencies"
+    TYPE_DEPENDENTS = "type-dependents"
+    # ENDPOINT & CALL deep-dive pack (Fase 10)
+    ENDPOINT_CONTRACT = "endpoint-contract"
+    ENDPOINT_SECURITY = "endpoint-security"
+    CALL_NEIGHBORHOOD = "call-neighborhood"
+    # GRAPH-analysis pack (Fase 11)
+    EXECUTION_PATHS_THROUGH = "execution-paths-through"
+    TRANSACTIONS_REACHING = "transactions-reaching"
+    SUBSYSTEM_COUPLING = "subsystem-coupling"
+
+
+@dataclass(frozen=True)
+class RetrievalAnchor:
+    """A typed pointer into the knowledge graph — NEVER free text to be searched.
+
+    `kind` selects the *structured* index used to bind `raw` to graph identities
+    (a simple type name → FQN via `types_by_simple`, a tech token → integration
+    scheme enum, …). It is not a substring query.
+    """
+
+    kind: str  # "symbol" | "package" | "module" | "tech" | "file" | "subsystem"
+    raw: str
+
+
+@dataclass(frozen=True)
+class RetrievalOptions:
+    """Presentation/shape knobs. They tune *what is returned*, never *how it is
+    computed* — the plan owns computation.
+
+    `limit` caps the number of entities in the result (applied by the terminal BuildResult
+    step, which records an `entities_truncated` observation when it bites). ``0`` means
+    unbounded — the default, so an unset option never silently drops engine-faithful
+    results. `min_confidence` and `include_evidence_text` are RESERVED (documented in
+    ADR-retrieval-v1): declared for the stable option surface, not yet enforced."""
+
+    limit: int = 0  # 0 = unbounded (engine-faithful); >0 caps the entity count
+    min_confidence: str | None = None  # RESERVED — "low" | "medium" | "high"
+    include_evidence_text: bool = False  # RESERVED — opt-in lazy B-3 text grounding
+
+
+@dataclass(frozen=True)
+class RetrievalRequest:
+    """A complete, typed knowledge query submitted by any consumer."""
+
+    intent: RetrievalIntent
+    anchors: tuple[RetrievalAnchor, ...] = ()
+    options: RetrievalOptions = field(default_factory=RetrievalOptions)