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

sourcecode/retrieval/steps.py

@@ -0,0 +1,242 @@
+"""Step handlers — the reusable, single-responsibility execution units (Fase 4 §3).
+
+Each handler is a pure procedure over `(step, StepContext)`: it reads knowledge and/or
+prior slots, and writes its output into the shared blackboard (or the terminal result).
+Handlers are the ONLY place execution logic lives; steps themselves are inert data and
+intents are declarative plans. A handler:
+
+* reuses ONLY existing engines/providers — never a new engine, never a re-parse;
+* never touches the parser or source directly;
+* passes results to later steps through named blackboard slots.
+
+Fase 4 implements exactly the four handlers the two architecture intents need
+(`ARCHITECTURAL_CORE`, `ARCHITECTURAL_STYLE`). Both intents reuse the SAME handlers — they
+differ only in the `Characterize` dimension parameter, which is the proof that a new intent
+is a new *plan*, not new *runtime*. Steps for other catalogue intents (Resolve, BlastRadius,
+Transactions, Endpoints, Integrations, …) are deliberately NOT built here.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sourcecode.retrieval.errors import UnknownDimensionError
+from sourcecode.retrieval.query import (
+    BuildResult,
+    Characterize,
+    CollectEvidence,
+    RankByScore,
+    Step,
+)
+from sourcecode.retrieval.result import (
+    Explanation,
+    KnowledgeEntity,
+    KnowledgeResult,
+    Observation,
+    Provenance,
+    RetrievalEvidence,
+)
+
+if TYPE_CHECKING:
+    from sourcecode.retrieval.runtime import StepContext, StepRegistry
+
+# ── blackboard slot keys ─────────────────────────────────────────────────────────
+# Generic result slots — read by the GENERIC BuildResult; written by any pack.
+SLOT_ENTITIES = "entities"
+SLOT_EVIDENCE = "evidence"
+SLOT_OBSERVATIONS = "observations"
+SLOT_CONFIDENCE = "confidence"
+SLOT_EXPLANATION = "explanation"
+SLOT_PROVENANCE = "provenance"
+# Archetype-pack slots.
+SLOT_DIMENSION = "dimension_result"
+SLOT_GRAPH_METRICS = "graph_metrics"
+SLOT_SIGNALS_USED = "signals_used"
+SLOT_SIGNALS_MISSING = "signals_missing"
+SLOT_KNOWLEDGE_SOURCE = "knowledge_source"
+
+
+# ── handlers ─────────────────────────────────────────────────────────────────────
+def characterize(step: Step, ctx: "StepContext") -> None:
+    """Reuse `ArchetypeClassifier`; select the requested archetype dimension. Writes the
+    dimension result, graph metrics, and signal provenance to the blackboard."""
+    assert isinstance(step, Characterize)
+    from sourcecode.archetype import ArchetypeClassifier
+
+    analysis = ArchetypeClassifier().analyze(
+        ctx.knowledge.source_map,
+        root=ctx.knowledge.root,
+        module_graph=ctx.knowledge.module_graph,
+    )
+    dim = analysis.dimensions.get(step.dimension)
+    if dim is None:
+        raise UnknownDimensionError(f"archetype has no dimension {step.dimension!r}")
+    ctx.put(SLOT_DIMENSION, dim)
+    ctx.put(SLOT_GRAPH_METRICS, dict(analysis.graph_metrics))
+    ctx.put(SLOT_SIGNALS_USED, tuple(analysis.signals_used))
+    ctx.put(SLOT_SIGNALS_MISSING, tuple(analysis.signals_missing))
+    ctx.put(SLOT_KNOWLEDGE_SOURCE, analysis.generated_from)
+
+
+def rank_by_score(step: Step, ctx: "StepContext") -> None:
+    """Order the dimension's candidates by their EXISTING engine scores (no new score).
+    Emits ranked `KnowledgeEntity`s."""
+    dim = ctx.require(SLOT_DIMENSION)
+    ranked = sorted(dim.candidates, key=lambda c: (-c.score, c.label))
+    ctx.put(
+        SLOT_ENTITIES,
+        [
+            KnowledgeEntity(
+                identity=c.label,
+                kind=f"{dim.dimension}_candidate",
+                score=c.score,
+                attributes={"is_primary": c.label == dim.primary},
+            )
+            for c in ranked
+            if c.score > 0
+        ],
+    )
+
+
+def collect_evidence(step: Step, ctx: "StepContext") -> None:
+    """Assemble the winning candidate's evidence + graph-topology observations AND the
+    generic confidence/explanation/provenance slots the shared BuildResult consumes.
+    Reuses values already computed; recomputes nothing."""
+    dim = ctx.require(SLOT_DIMENSION)
+    graph_metrics = ctx.require(SLOT_GRAPH_METRICS)
+    winner = _winner(dim)
+    runner = _runner_up(dim)
+    evidence = [
+        RetrievalEvidence(
+            signal=e.signal,
+            detail=e.detail,
+            weight=e.weight,
+            strength=e.strength,
+            mass=e.mass,
+            contribution=e.contribution,
+            provider="ArchetypeClassifier",
+        )
+        for e in sorted(
+            (winner.evidence if winner is not None else []),
+            key=lambda e: e.contribution,
+            reverse=True,
+        )
+    ]
+    ctx.put(SLOT_EVIDENCE, evidence)
+    ctx.put(
+        SLOT_OBSERVATIONS,
+        [
+            Observation(
+                name=k,
+                value=round(v, 4),
+                detail="module-graph topology metric (GraphEvidenceProvider)",
+            )
+            for k, v in sorted(graph_metrics.items())
+        ],
+    )
+    ctx.put(SLOT_CONFIDENCE, dim.confidence)
+    ctx.put(
+        SLOT_EXPLANATION,
+        Explanation(
+            winner=dim.primary,
+            score=(winner.score if winner is not None else 0.0),
+            confidence=dim.confidence,
+            top_contributions=tuple((e.signal, e.contribution) for e in evidence[:3]),
+            runner_up=(runner.label if runner is not None else None),
+            engine_explanation=dim.explanation,
+        ),
+    )
+    ctx.put(
+        SLOT_PROVENANCE,
+        Provenance(
+            services=("ArchetypeClassifier", "GraphEvidenceProvider"),
+            signals_used=ctx.get(SLOT_SIGNALS_USED, ()),
+            signals_missing=ctx.get(SLOT_SIGNALS_MISSING, ()),
+            knowledge_source=ctx.get(SLOT_KNOWLEDGE_SOURCE, ""),
+        ),
+    )
+
+
+def build_result(step: Step, ctx: "StepContext") -> None:
+    """GENERIC terminal step: assemble the typed `KnowledgeResult` from the generic result
+    slots any pack populated. Knows nothing about a specific intent — this is why one
+    BuildResult serves every pack (design §4.5).
+
+    Applies the request's `limit` option (B4): when set (>0) and it bites, the entity tuple
+    is capped and an `entities_truncated` observation records the total. `limit == 0`
+    (the default) is unbounded, so engine-faithful results are never silently dropped."""
+    default_expl = Explanation(
+        winner=None,
+        score=0.0,
+        confidence=ctx.get(SLOT_CONFIDENCE, "low"),
+        top_contributions=(),
+        runner_up=None,
+        engine_explanation="",
+    )
+    default_prov = Provenance(services=(), signals_used=(), signals_missing=(), knowledge_source="")
+    entities = tuple(ctx.get(SLOT_ENTITIES, []))
+    observations = list(ctx.get(SLOT_OBSERVATIONS, []))
+    limit = getattr(ctx.options, "limit", 0)
+    if limit and len(entities) > limit:
+        observations.append(
+            Observation(
+                name="entities_truncated",
+                value=len(entities),
+                detail=f"limit={limit}; returned first {limit} of {len(entities)}",
+            )
+        )
+        entities = entities[:limit]
+    ctx.set_result(
+        KnowledgeResult(
+            intent=ctx.intent.value,
+            entities=entities,
+            evidence=tuple(ctx.get(SLOT_EVIDENCE, [])),
+            confidence=ctx.get(SLOT_CONFIDENCE, "low"),
+            observations=tuple(observations),
+            explanation=ctx.get(SLOT_EXPLANATION, default_expl),
+            provenance=ctx.get(SLOT_PROVENANCE, default_prov),
+            query=tuple(t.step for t in ctx.trace) + (type(step).__name__,),
+        )
+    )
+
+
+# ── registry wiring ──────────────────────────────────────────────────────────────
+def default_registry() -> "StepRegistry":
+    """The default step registry: the arch handlers + the IMPACT-pack handlers. The
+    registry is the sanctioned extension seam — adding a pack registers its handlers here;
+    the Runtime engine (`runtime.py`) is unchanged. Adding an intent that composes already
+    registered steps needs no change even here."""
+    from sourcecode.retrieval.runtime import StepRegistry
+    from sourcecode.retrieval.steps_endpoint import register_endpoint_steps
+    from sourcecode.retrieval.steps_graph import register_graph_steps
+    from sourcecode.retrieval.steps_impact import register_impact_steps
+    from sourcecode.retrieval.steps_intf import register_intf_steps
+    from sourcecode.retrieval.steps_struct import register_struct_steps
+    from sourcecode.retrieval.steps_txsec import register_txsec_steps
+
+    registry = StepRegistry()
+    registry.register(Characterize.kind, characterize)
+    registry.register(RankByScore.kind, rank_by_score)
+    registry.register(CollectEvidence.kind, collect_evidence)
+    registry.register(BuildResult.kind, build_result)
+    register_impact_steps(registry)
+    register_txsec_steps(registry)
+    register_intf_steps(registry)
+    register_struct_steps(registry)
+    register_endpoint_steps(registry)
+    register_graph_steps(registry)
+    return registry
+
+
+# ── helpers over the reused DimensionResult ─────────────────────────────────────
+def _winner(dim) -> object:
+    if dim.primary is None:
+        return None
+    return next((c for c in dim.candidates if c.label == dim.primary), None)
+
+
+def _runner_up(dim) -> object:
+    ranked = sorted(dim.candidates, key=lambda c: (-c.score, c.label))
+    for c in ranked:
+        if c.label != dim.primary and c.score > 0:
+            return c
+    return None

sourcecode/retrieval/steps_endpoint.py

@@ -0,0 +1,311 @@
+"""ENDPOINT & CALL deep-dive pack step handlers (Fase 10).
+
+Three anchored intents (ENDPOINT_CONTRACT, ENDPOINT_SECURITY, CALL_NEIGHBORHOOD)
+expressed purely as compositions of these projection steps. NO new analyzer: every step
+reuses an engine already wired into the shared `KnowledgeContext` and projects its
+already-computed output, scoped to the requested anchor.
+
+* Contract     → `build_validation_surface` (the SAME engine `validation-points` uses),
+  scoped to one endpoint.
+* Security     → `SpringSemanticModel.endpoint_index` (per-endpoint `CanonicalSecurity`)
+  + `run_security_audit` findings scoped to the handler.
+* Neighborhood → `SpringSemanticModel.call_adj` (forward callees + derived reverse callers
+  of the target symbol).
+
+Endpoint intents bind an `endpoint` / `symbol` reference via the shared `ResolveEndpointRef`
+step; CALL_NEIGHBORHOOD reuses the impact pack's `ResolveTarget` (cross-pack step reuse).
+No step opens source or parses.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sourcecode.retrieval.errors import StepContractError
+from sourcecode.retrieval.query import (
+    CollectEndpointEvidence,
+    ResolveCallNeighborhood,
+    ResolveEndpointContract,
+    ResolveEndpointRef,
+    ResolveEndpointSecurity,
+    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_ENDPOINT_REF = "endpoint_ref"
+SLOT_SERVICES = "endpoint_services"
+_REF_ANCHOR_KINDS = ("endpoint", "symbol", "path")
+
+
+# ── shared endpoint-reference binding step ───────────────────────────────────────
+def resolve_endpoint_ref(step: Step, ctx: "StepContext") -> None:
+    """Bind the request's endpoint/symbol/path anchor to a reference token, matched
+    structurally against the endpoint model / validation surface downstream."""
+    assert isinstance(step, ResolveEndpointRef)
+    anchor = next((a for a in ctx.anchors if a.anchor.kind in _REF_ANCHOR_KINDS), None)
+    if anchor is None:
+        raise StepContractError(
+            "endpoint intents require an 'endpoint', 'path', or 'symbol' anchor"
+        )
+    ctx.put(SLOT_ENDPOINT_REF, anchor.identities[0] if anchor.identities else anchor.anchor.raw)
+
+
+# ── contract (build_validation_surface, scoped) ──────────────────────────────────
+def resolve_endpoint_contract(step: Step, ctx: "StepContext") -> None:
+    assert isinstance(step, ResolveEndpointContract)
+    from sourcecode.validation_surface import build_validation_surface
+
+    ref = ctx.require(SLOT_ENDPOINT_REF)
+    surface = build_validation_surface(ctx.knowledge.root, graph=ctx.knowledge.context_graph)
+    endpoints = surface.get("endpoints", []) or []
+    matched = [ep for ep in endpoints if _endpoint_matches(ep, ref)]
+    ctx.put(
+        SLOT_ENTITIES,
+        [
+            KnowledgeEntity(
+                identity=_endpoint_id(ep),
+                kind="endpoint_contract",
+                score=0.0,
+                attributes={k: v for k, v in ep.items() if k not in ("source_file",)},
+            )
+            for ep in matched
+        ],
+    )
+    ctx.put(
+        SLOT_EVIDENCE,
+        [
+            RetrievalEvidence(
+                signal="endpoint_contract",
+                detail=_endpoint_id(ep),
+                weight=1.0,
+                strength=1.0,
+                mass=1.0,
+                contribution=1.0,
+                provider="build_validation_surface",
+                source_file=ep.get("source_file"),
+            )
+            for ep in matched
+        ],
+    )
+    ctx.put(
+        SLOT_OBSERVATIONS,
+        [Observation(name="matched_endpoints", value=len(matched), detail=f"ref={ref!r}")],
+    )
+    ctx.put(SLOT_CONFIDENCE, "high" if matched else "low")
+    _add_service(ctx, "build_validation_surface")
+
+
+# ── security (endpoint_index + run_security_audit, scoped) ───────────────────────
+def resolve_endpoint_security(step: Step, ctx: "StepContext") -> None:
+    assert isinstance(step, ResolveEndpointSecurity)
+    ref = ctx.require(SLOT_ENDPOINT_REF)
+    index = ctx.knowledge.spring_model.endpoint_index
+    endpoints = [ep for eps in index.by_controller.values() for ep in eps]
+    matched = [ep for ep in endpoints if _canonical_endpoint_matches(ep, ref)]
+    handlers = {ep.handler_symbol for ep in matched if ep.handler_symbol}
+    findings = [f for f in _security_findings(ctx) if _finding_on_handler(f, handlers)]
+    ctx.put(
+        SLOT_ENTITIES,
+        [
+            KnowledgeEntity(
+                identity=ep.handler_symbol or f"{ep.method or ''} {ep.path or ''}".strip(),
+                kind="endpoint_security",
+                score=0.0,
+                attributes={
+                    "method": ep.method or "",
+                    "path": ep.path or "",
+                    "security": _security_summary(ep.security),
+                    "findings": [f.pattern_id for f in findings if _finding_on_handler(f, {ep.handler_symbol})],
+                },
+            )
+            for ep in matched
+        ],
+    )
+    ctx.put(
+        SLOT_EVIDENCE,
+        [
+            RetrievalEvidence(
+                signal=f.pattern_id,
+                detail=f.title,
+                weight=1.0,
+                strength=1.0,
+                mass=1.0,
+                contribution=1.0,
+                provider=f"audit:{f.category}",
+                source_file=getattr(f, "source_file", "") or None,
+            )
+            for f in findings
+        ],
+    )
+    ctx.put(
+        SLOT_OBSERVATIONS,
+        [
+            Observation(name="matched_endpoints", value=len(matched), detail=f"ref={ref!r}"),
+            Observation(name="security_findings", value=len(findings), detail="run_security_audit"),
+        ],
+    )
+    ctx.put(SLOT_CONFIDENCE, "high" if matched else "low")
+    _add_service(ctx, "SpringSemanticModel")
+    _add_service(ctx, "run_security_audit")
+
+
+# ── call neighborhood (SpringSemanticModel.call_adj) ─────────────────────────────
+def resolve_call_neighborhood(step: Step, ctx: "StepContext") -> None:
+    """Forward callees + derived reverse callers of the target symbol. Reads the built
+    call adjacency directly; reuses the impact pack's ResolveTarget for the symbol."""
+    assert isinstance(step, ResolveCallNeighborhood)
+    target = ctx.require(SLOT_TARGET)
+    adjacency = ctx.knowledge.spring_model.call_adj.adjacency
+    matched_keys = [k for k in adjacency if _sym_matches(k, target)]
+    callees: dict[str, int] = {}
+    for k in matched_keys:
+        for callee in adjacency.get(k, []) or []:
+            callees[callee] = callees.get(callee, 0) + 1
+    callers: dict[str, int] = {}
+    for caller, callee_list in adjacency.items():
+        hits = sum(1 for c in (callee_list or []) if _sym_matches(c, target))
+        if hits and caller not in matched_keys:
+            callers[caller] = hits
+    entities = [
+        KnowledgeEntity(
+            identity=fqn, kind="callee", score=0.0, attributes={"direction": "out", "count": n}
+        )
+        for fqn, n in sorted(callees.items())
+    ] + [
+        KnowledgeEntity(
+            identity=fqn, kind="caller", score=0.0, attributes={"direction": "in", "count": n}
+        )
+        for fqn, n in sorted(callers.items())
+    ]
+    ctx.put(SLOT_ENTITIES, entities)
+    ctx.put(
+        SLOT_OBSERVATIONS,
+        [
+            Observation(name="matched_symbols", value=len(matched_keys), detail=f"target={target!r}"),
+            Observation(name="callees", value=len(callees), detail="forward call edges"),
+            Observation(name="callers", value=len(callers), detail="reverse call edges"),
+        ],
+    )
+    ctx.put(SLOT_CONFIDENCE, "high" if matched_keys else "low")
+    _add_service(ctx, "SpringSemanticModel")
+
+
+# ── terminal evidence (generic across the pack) ──────────────────────────────────
+def collect_endpoint_evidence(step: Step, ctx: "StepContext") -> None:
+    """Assemble confidence, a structured explanation (no synthesized prose), and
+    provenance from what the resolve step produced. GENERIC across the pack."""
+    assert isinstance(step, CollectEndpointEvidence)
+    confidence = ctx.get(SLOT_CONFIDENCE, "medium")
+    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=("endpoint_index", "validation_surface", "security_audit", "call_adj"),
+            signals_missing=(),
+            knowledge_source="SpringSemanticModel + validation/security engines",
+        ),
+    )
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────────
+def _security_findings(ctx: "StepContext") -> list:
+    from sourcecode.spring_security_audit import run_security_audit
+
+    return run_security_audit(
+        ctx.knowledge.context_graph.cir, root=ctx.knowledge.root, model=ctx.knowledge.spring_model
+    ).findings
+
+
+def _endpoint_id(ep: dict) -> str:
+    return (
+        ep.get("handler")
+        or f"{ep.get('method', '')} {ep.get('path', '')}".strip()
+        or ep.get("path", "")
+        or "?"
+    )
+
+
+def _ref_matches(path: str, handler: str, ref: str) -> bool:
+    """A path ref (starts with '/') matches the endpoint's path exactly (trailing slash
+    normalized); anything else is a handler symbol match. No substring matching — that
+    would let '/' match every endpoint."""
+    if ref.startswith("/"):
+        return path.rstrip("/") == ref.rstrip("/")
+    return ref == handler or _sym_matches(handler, ref)
+
+
+def _endpoint_matches(ep: dict, ref: str) -> bool:
+    return _ref_matches(ep.get("path", "") or "", ep.get("handler", "") or "", ref)
+
+
+def _canonical_endpoint_matches(ep, ref: str) -> bool:
+    return _ref_matches(ep.path or "", ep.handler_symbol or "", ref)
+
+
+def _finding_on_handler(f, handlers: set) -> bool:
+    sym = getattr(f, "symbol", "") or ""
+    return any(sym == h or (h and (sym.startswith(h) or h.startswith(sym))) for h in handlers if h)
+
+
+def _sym_matches(fqn: str, target: str) -> bool:
+    if not fqn:
+        return False
+    if fqn == target or fqn.endswith("." + target) or fqn.endswith("#" + target):
+        return True
+    simple = fqn.rsplit("#", 1)[0].rsplit(".", 1)[-1]
+    return simple == target
+
+
+def _security_summary(security) -> dict:
+    if security is None:
+        return {}
+    return {
+        "policy": getattr(security, "policy", None),
+        "source_scope": getattr(security, "source_scope", None),
+        "effective_roles": list(getattr(security, "effective_roles", []) or []),
+        "expression": getattr(security, "expression", "") or "",
+    }
+
+
+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_endpoint_steps(registry: "StepRegistry") -> None:
+    """Register the ENDPOINT & CALL deep-dive handlers (the sanctioned extension seam)."""
+    registry.register(ResolveEndpointRef.kind, resolve_endpoint_ref)
+    registry.register(ResolveEndpointContract.kind, resolve_endpoint_contract)
+    registry.register(ResolveEndpointSecurity.kind, resolve_endpoint_security)
+    registry.register(ResolveCallNeighborhood.kind, resolve_call_neighborhood)
+    registry.register(CollectEndpointEvidence.kind, collect_endpoint_evidence)