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

sourcecode/retrieval/steps_intf.py

@@ -0,0 +1,247 @@
+"""INTERFACES & INTEGRATIONS pack step handlers (Fase 7).
+
+Three whole-repo inventory intents (ENDPOINT_INVENTORY, INTEGRATION_INVENTORY,
+EVENT_TOPOLOGY) 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.
+
+* Endpoints    → `SpringSemanticModel.endpoint_index` (the SAME index the `endpoints` /
+  SEC audit path uses).
+* Integrations → `SemanticIntegrationEngine.detect()` — the whole-repo counterpart of the
+  impact pack's cone-scoped `ResolveIntegrations` (same engine, no cone filter).
+* Events       → `SpringSemanticModel.event_graph` (publishers / listeners per event).
+
+No step opens source or parses: the ContextGraph / SpringSemanticModel are acquired once by
+the shared `KnowledgeContext`; steps only read them. Ordering is deterministic (by
+identity). The terminal `CollectInterfaceEvidence` is generic across the pack.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sourcecode.retrieval.query import (
+    CollectInterfaceEvidence,
+    ResolveEndpointInventory,
+    ResolveEventTopology,
+    ResolveIntegrationInventory,
+    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 _integration_evidence
+
+if TYPE_CHECKING:
+    from sourcecode.retrieval.runtime import StepContext, StepRegistry
+
+SLOT_SERVICES = "intf_services"
+
+
+# ── endpoints (SpringSemanticModel.endpoint_index) ───────────────────────────────
+def resolve_endpoint_inventory(step: Step, ctx: "StepContext") -> None:
+    assert isinstance(step, ResolveEndpointInventory)
+    index = ctx.knowledge.spring_model.endpoint_index
+    endpoints = [ep for eps in index.by_controller.values() for ep in eps]
+    endpoints.sort(key=_endpoint_id)
+    ctx.put(SLOT_ENTITIES, [_endpoint_entity(ep) for ep in endpoints])
+    ctx.put(SLOT_EVIDENCE, [_endpoint_evidence(ep) for ep in endpoints])
+    ctx.put(
+        SLOT_OBSERVATIONS,
+        [
+            Observation(name="endpoints", value=len(endpoints), detail="endpoint_index"),
+            Observation(
+                name="controllers",
+                value=len(index.by_controller),
+                detail="endpoint_index controllers",
+            ),
+        ],
+    )
+    ctx.put(SLOT_CONFIDENCE, "high" if endpoints else "medium")
+    _add_service(ctx, "SpringSemanticModel")
+
+
+# ── integrations (SemanticIntegrationEngine — whole repo, no cone) ───────────────
+def resolve_integration_inventory(step: Step, ctx: "StepContext") -> None:
+    assert isinstance(step, ResolveIntegrationInventory)
+    from sourcecode.semantic_integration_engine import SemanticIntegrationEngine
+
+    integrations = SemanticIntegrationEngine(ctx.knowledge.context_graph).detect()
+    integrations = sorted(integrations, key=lambda i: (i.kind, i.client, i.target or ""))
+    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,
+                    "basis": i.basis,
+                },
+            )
+            for i in integrations
+        ],
+    )
+    ctx.put(SLOT_EVIDENCE, [_integration_evidence(i) for i in integrations])
+    ctx.put(SLOT_OBSERVATIONS, _kind_histogram(integrations, key=lambda i: i.kind, label="integration"))
+    ctx.put(SLOT_CONFIDENCE, "high" if integrations else "medium")
+    _add_service(ctx, "SemanticIntegrationEngine")
+
+
+# ── events (SpringSemanticModel.event_graph) ─────────────────────────────────────
+def resolve_event_topology(step: Step, ctx: "StepContext") -> None:
+    assert isinstance(step, ResolveEventTopology)
+    eg = ctx.knowledge.spring_model.event_graph
+    event_types = sorted(eg.event_types)
+    entities = [
+        KnowledgeEntity(
+            identity=et,
+            kind="event_type",
+            score=0.0,
+            attributes={
+                "publishers": list(eg.publishers_of(et)),
+                "listeners": list(eg.listeners_of(et)),
+                "publisher_count": len(eg.publishers_of(et)),
+                "listener_count": len(eg.listeners_of(et)),
+            },
+        )
+        for et in event_types
+    ]
+    ctx.put(SLOT_ENTITIES, entities)
+    ctx.put(
+        SLOT_EVIDENCE,
+        [
+            RetrievalEvidence(
+                signal="event",
+                detail=f"{et}: {len(eg.publishers_of(et))} pub / {len(eg.listeners_of(et))} sub",
+                weight=1.0,
+                strength=1.0,
+                mass=1.0,
+                contribution=1.0,
+                provider="SpringSemanticModel.event_graph",
+            )
+            for et in event_types
+        ],
+    )
+    ctx.put(
+        SLOT_OBSERVATIONS,
+        [
+            Observation(name="event_types", value=len(event_types), detail="event_graph"),
+            Observation(name="event_edges", value=eg.total_edges, detail="event_graph total edges"),
+        ],
+    )
+    ctx.put(SLOT_CONFIDENCE, "high" if event_types else "medium")
+    _add_service(ctx, "SpringSemanticModel")
+
+
+# ── terminal evidence (generic across the pack) ──────────────────────────────────
+def collect_interface_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, CollectInterfaceEvidence)
+    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", "integration_engine", "event_graph"),
+            signals_missing=(),
+            knowledge_source="SpringSemanticModel + SemanticIntegrationEngine",
+        ),
+    )
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────────
+def _endpoint_id(ep) -> str:
+    return ep.handler_symbol or f"{ep.method or ''} {ep.path or ''}".strip()
+
+
+def _endpoint_entity(ep) -> KnowledgeEntity:
+    return KnowledgeEntity(
+        identity=_endpoint_id(ep),
+        kind="endpoint",
+        score=0.0,
+        attributes={
+            "method": ep.method or "",
+            "path": ep.path or "",
+            "controller_class": ep.controller_class or "",
+            "handler_symbol": ep.handler_symbol or "",
+            "security": _security_summary(ep.security),
+        },
+    )
+
+
+def _endpoint_evidence(ep) -> RetrievalEvidence:
+    return RetrievalEvidence(
+        signal="endpoint",
+        detail=f"{ep.method or ''} {ep.path or ''}".strip(),
+        weight=1.0,
+        strength=1.0,
+        mass=1.0,
+        contribution=1.0,
+        provider="SpringSemanticModel.endpoint_index",
+        source_file=ep.source_file or None,
+    )
+
+
+def _security_summary(security) -> dict:
+    """Compact, JSON-safe projection of the endpoint's CanonicalSecurity (no new
+    analysis — just the engine's own fields)."""
+    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 []),
+    }
+
+
+def _kind_histogram(items, *, key, label: str) -> list:
+    hist: dict[str, int] = {}
+    for it in items:
+        k = key(it)
+        hist[k] = hist.get(k, 0) + 1
+    return [
+        Observation(name=f"{label}_{k}", value=n, detail=f"{label} count")
+        for k, n in sorted(hist.items())
+    ]
+
+
+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_intf_steps(registry: "StepRegistry") -> None:
+    """Register the INTERFACES & INTEGRATIONS handlers (the sanctioned extension seam)."""
+    registry.register(ResolveEndpointInventory.kind, resolve_endpoint_inventory)
+    registry.register(ResolveIntegrationInventory.kind, resolve_integration_inventory)
+    registry.register(ResolveEventTopology.kind, resolve_event_topology)
+    registry.register(CollectInterfaceEvidence.kind, collect_interface_evidence)

sourcecode/retrieval/steps_struct.py

@@ -0,0 +1,338 @@
+"""SUBSYSTEMS & DEPENDENCIES pack step handlers (Fase 8).
+
+Four intents (SUBSYSTEM_INVENTORY, SUBSYSTEM_MEMBERS, MODULE_DEPENDENTS,
+MODULE_DEPENDENCIES) expressed purely as compositions of these projection steps. NO new
+analyzer: every step reuses knowledge already built into the shared `KnowledgeContext`.
+
+* Subsystems  → `repo_ir['subsystems']` (the SAME subsystem partition the `impact` /
+  cross-module engine uses).
+* Dependencies → the module graph (`SourceMap.module_graph`, built by `GraphAnalyzer` —
+  the SAME graph the `archetype` / graph commands use). Dependents/dependencies are the
+  reverse/forward edges of a scope, read directly off the built graph.
+
+The two dependency intents are ANCHORED: a shared `ResolveScope` step binds the request's
+subsystem / module / package anchor to a scope token, which the projection step matches
+against the graph's OWN node ids (a structural membership filter over the built index —
+never a fuzzy text scan of source). Cycle *enumeration* is intentionally NOT here: the
+graph engine only counts import cycles, so surfacing the members would require new
+analysis — out of scope for a reuse-only pack.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sourcecode.retrieval.errors import StepContractError
+from sourcecode.retrieval.query import (
+    CollectStructureEvidence,
+    ResolveModuleDependencies,
+    ResolveModuleDependents,
+    ResolveScope,
+    ResolveSubsystemInventory,
+    ResolveSubsystemMembers,
+    ResolveTypeDependents,
+    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_SCOPE = "structure_scope"
+SLOT_SERVICES = "structure_services"
+_SCOPE_ANCHOR_KINDS = ("subsystem", "module", "package")
+_MODULE_PREFIX = "module:"
+
+
+# ── shared scope-binding step (anchored intents) ─────────────────────────────────
+def resolve_scope(step: Step, ctx: "StepContext") -> None:
+    """Bind the request's subsystem/module/package anchor to a scope token. The token is
+    matched structurally against the subsystem partition / graph node ids downstream."""
+    assert isinstance(step, ResolveScope)
+    anchor = next((a for a in ctx.anchors if a.anchor.kind in _SCOPE_ANCHOR_KINDS), None)
+    if anchor is None:
+        raise StepContractError(
+            "subsystem/dependency intents require a 'subsystem', 'module', or 'package' anchor"
+        )
+    ctx.put(SLOT_SCOPE, anchor.identities[0] if anchor.identities else anchor.anchor.raw)
+
+
+# ── subsystems (repo_ir['subsystems']) ───────────────────────────────────────────
+def resolve_subsystem_inventory(step: Step, ctx: "StepContext") -> None:
+    assert isinstance(step, ResolveSubsystemInventory)
+    subsystems = ctx.knowledge.repo_ir.get("subsystems", []) or []
+    ordered = sorted(subsystems, key=lambda s: (-int(s.get("member_count", 0)), s.get("label", "")))
+    ctx.put(
+        SLOT_ENTITIES,
+        [
+            KnowledgeEntity(
+                identity=s.get("label", "") or s.get("package_prefix", ""),
+                kind="subsystem",
+                score=0.0,
+                attributes={
+                    "package_prefix": s.get("package_prefix", ""),
+                    "member_count": s.get("member_count", 0),
+                    "summary": s.get("summary", ""),
+                },
+            )
+            for s in ordered
+        ],
+    )
+    ctx.put(
+        SLOT_OBSERVATIONS,
+        [Observation(name="subsystems", value=len(ordered), detail="repo_ir subsystem partition")],
+    )
+    ctx.put(SLOT_CONFIDENCE, "high" if ordered else "medium")
+    _add_service(ctx, "build_repo_ir(subsystems)")
+
+
+def resolve_subsystem_members(step: Step, ctx: "StepContext") -> None:
+    """The member symbols of the subsystem named by the scope anchor. Reuses the repo_ir
+    subsystem partition; matches the scope against the subsystem label / package prefix."""
+    assert isinstance(step, ResolveSubsystemMembers)
+    scope = ctx.require(SLOT_SCOPE)
+    subsystems = ctx.knowledge.repo_ir.get("subsystems", []) or []
+    matched = [s for s in subsystems if _subsystem_matches(s, scope)]
+    members = [(s, m) for s in matched for m in (s.get("members", []) or [])]
+    ctx.put(
+        SLOT_ENTITIES,
+        [
+            KnowledgeEntity(
+                identity=m,
+                kind="subsystem_member",
+                score=0.0,
+                attributes={"subsystem": s.get("label", ""), "package_prefix": s.get("package_prefix", "")},
+            )
+            for s, m in members
+        ],
+    )
+    ctx.put(
+        SLOT_OBSERVATIONS,
+        [
+            Observation(name="matched_subsystems", value=len(matched), detail=f"scope={scope!r}"),
+            Observation(name="members", value=len(members), detail="subsystem members"),
+        ],
+    )
+    ctx.put(SLOT_CONFIDENCE, "high" if members else "low")
+    _add_service(ctx, "build_repo_ir(subsystems)")
+
+
+# ── dependencies (SourceMap.module_graph) ────────────────────────────────────────
+def resolve_module_dependents(step: Step, ctx: "StepContext") -> None:
+    """Modules that depend ON the scope: sources of edges whose target is in the scope.
+    Reads the built module graph directly (reverse edges)."""
+    assert isinstance(step, ResolveModuleDependents)
+    _project_edges(ctx, incoming=True)
+
+
+def resolve_module_dependencies(step: Step, ctx: "StepContext") -> None:
+    """Modules the scope DEPENDS ON: targets of edges whose source is in the scope.
+    Reads the built module graph directly (forward edges)."""
+    assert isinstance(step, ResolveModuleDependencies)
+    _project_edges(ctx, incoming=False)
+
+
+def _project_edges(ctx: "StepContext", *, incoming: bool) -> None:
+    scope = ctx.require(SLOT_SCOPE)
+    mg = ctx.knowledge.module_graph
+    if mg is None:
+        raise StepContractError("module graph unavailable (name-mass-only acquisition)")
+    scope_nodes = _match_nodes(mg, scope)
+    relation = "dependent" if incoming else "dependency"
+    hits: dict[str, set] = {}
+    for e in mg.edges:
+        source, target = getattr(e, "source", None), getattr(e, "target", None)
+        kind = getattr(e, "kind", "") or ""
+        if incoming and target in scope_nodes and source not in scope_nodes:
+            hits.setdefault(source, set()).add(kind)
+        elif not incoming and source in scope_nodes and target not in scope_nodes:
+            hits.setdefault(target, set()).add(kind)
+    ordered = sorted(hits.items(), key=lambda kv: _node_path(kv[0]))
+    ctx.put(
+        SLOT_ENTITIES,
+        [
+            KnowledgeEntity(
+                identity=_node_path(node),
+                kind="module",
+                score=0.0,
+                attributes={"relation": relation, "via": sorted(k for k in kinds if k)},
+            )
+            for node, kinds in ordered
+        ],
+    )
+    ctx.put(
+        SLOT_EVIDENCE,
+        [
+            RetrievalEvidence(
+                signal=f"module_{relation}",
+                detail=f"{_node_path(node)} ({', '.join(sorted(k for k in kinds if k))})",
+                weight=1.0,
+                strength=1.0,
+                mass=1.0,
+                contribution=1.0,
+                provider="GraphAnalyzer(module_graph)",
+                source_file=_node_path(node),
+            )
+            for node, kinds in ordered
+        ],
+    )
+    ctx.put(
+        SLOT_OBSERVATIONS,
+        [
+            Observation(name="scope_nodes", value=len(scope_nodes), detail=f"scope={scope!r}"),
+            Observation(name=f"{relation}s", value=len(ordered), detail="module graph edges"),
+        ],
+    )
+    ctx.put(SLOT_CONFIDENCE, "high" if scope_nodes else "low")
+    _add_service(ctx, "GraphAnalyzer(module_graph)")
+
+
+# ── type dependents (repo_ir reverse graph) ──────────────────────────────────────
+def resolve_type_dependents(step: Step, ctx: "StepContext") -> None:
+    """The type-level dependents of the target symbol: the reverse-graph edges
+    (imports / implements / injects / contained_in) that point AT the target. Reuses the
+    repo_ir reverse graph and the impact pack's ResolveTarget (cross-pack step reuse)."""
+    assert isinstance(step, ResolveTypeDependents)
+    target = ctx.require(SLOT_TARGET)
+    reverse = ctx.knowledge.repo_ir.get("reverse_graph", {}) or {}
+    matched = {k: v for k, v in reverse.items() if _type_matches(k, target)}
+    dependents: dict[str, set] = {}
+    for edges in matched.values():
+        for edge_kind, fqns in (edges or {}).items():
+            for fqn in fqns or []:
+                dependents.setdefault(fqn, set()).add(edge_kind)
+    ordered = sorted(dependents.items(), key=lambda kv: kv[0])
+    ctx.put(
+        SLOT_ENTITIES,
+        [
+            KnowledgeEntity(
+                identity=fqn,
+                kind="type_dependent",
+                score=0.0,
+                attributes={"relation": "dependent", "via": sorted(kinds)},
+            )
+            for fqn, kinds in ordered
+        ],
+    )
+    ctx.put(
+        SLOT_EVIDENCE,
+        [
+            RetrievalEvidence(
+                signal="type_dependent",
+                detail=f"{fqn} ({', '.join(sorted(kinds))})",
+                weight=1.0,
+                strength=1.0,
+                mass=1.0,
+                contribution=1.0,
+                provider="build_repo_ir(reverse_graph)",
+            )
+            for fqn, kinds in ordered
+        ],
+    )
+    ctx.put(
+        SLOT_OBSERVATIONS,
+        [
+            Observation(name="matched_types", value=len(matched), detail=f"target={target!r}"),
+            Observation(name="dependents", value=len(ordered), detail="reverse graph edges"),
+        ],
+    )
+    ctx.put(SLOT_CONFIDENCE, "high" if matched else "low")
+    _add_service(ctx, "build_repo_ir(reverse_graph)")
+
+
+# ── terminal evidence (generic across the pack) ──────────────────────────────────
+def collect_structure_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, CollectStructureEvidence)
+    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=("subsystems", "module_graph"),
+            signals_missing=(),
+            knowledge_source="repo IR (subsystems) + module graph (GraphAnalyzer)",
+        ),
+    )
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────────
+def _subsystem_matches(subsystem: dict, scope: str) -> bool:
+    label = (subsystem.get("label", "") or "").lower()
+    prefix = (subsystem.get("package_prefix", "") or "").lower()
+    s = scope.lower()
+    return s == label or s == prefix or s in label or s in prefix
+
+
+def _type_matches(key: str, target: str) -> bool:
+    """Match a reverse-graph type key against the target symbol: exact FQN, or the target
+    is the key's simple name / a dotted suffix. Structural, over the built index."""
+    if key == target:
+        return True
+    simple = key.rsplit(".", 1)[-1]
+    return target == simple or key.endswith("." + target)
+
+
+def _normalize_scope(scope: str) -> str:
+    """A package token (dotted) becomes a path fragment so it matches the graph's
+    file-path node ids; a raw path fragment is used as-is."""
+    return scope.replace(".", "/") if "/" not in scope and "." in scope else scope
+
+
+def _match_nodes(mg, scope: str) -> set:
+    frag = _normalize_scope(scope).lower()
+    return {
+        getattr(n, "id", None)
+        for n in mg.nodes
+        if frag in _node_path(getattr(n, "id", None)).lower()
+    }
+
+
+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_struct_steps(registry: "StepRegistry") -> None:
+    """Register the SUBSYSTEMS & DEPENDENCIES handlers (the sanctioned extension seam)."""
+    registry.register(ResolveScope.kind, resolve_scope)
+    registry.register(ResolveSubsystemInventory.kind, resolve_subsystem_inventory)
+    registry.register(ResolveSubsystemMembers.kind, resolve_subsystem_members)
+    registry.register(ResolveModuleDependents.kind, resolve_module_dependents)
+    registry.register(ResolveModuleDependencies.kind, resolve_module_dependencies)
+    registry.register(ResolveTypeDependents.kind, resolve_type_dependents)
+    registry.register(CollectStructureEvidence.kind, collect_structure_evidence)