seam-code 0.3.0__py3-none-any.whl

seam/analysis/steer.py

@@ -0,0 +1,282 @@
+"""Truncation-steer generator for seam_impact output (E4).
+
+LEAF MODULE — pure function over plain dicts. Imports only stdlib (typing).
+No database access, no config import, no IO, never raises.
+Mirrors the leaf discipline of seam/analysis/byte_budget.py and
+seam/analysis/relevance.py.
+
+WHY this module exists (the usability gap it closes):
+  When seam_impact drops entries — via the per-tier count cap or the E1-FULL
+  byte ceiling — the response carries 'truncated' and 'byte_capped' counts that
+  are honest but inert. An agent knows entries were dropped but must guess the
+  remedy (raise the limit? bump max_bytes? narrow the query?). The information
+  needed to act is known at trim time but discarded.
+
+  generate_steer() receives the already-computed trim metadata and returns a
+  flat list of ready-to-act prose hints — e.g.:
+    "Raise limit to 17 to see 12 more WILL_BREAK upstream dependents."
+    "Pass max_bytes=0 for the full untrimmed blast radius."
+  Each hint is a complete, actionable sentence. The list is ABSENT (not empty-
+  and-present) when nothing was trimmed — so presence is the "there is more"
+  signal and absence is unambiguous.
+
+  When the byte ceiling drops ALL entries (the anti-false-safe case), the steer
+  always includes an explicit warning that the blast radius was trimmed to nothing
+  and this is NOT "no dependents" — it must not let an agent conclude the symbol
+  is safe to delete when its dependents were merely dropped.
+
+Steer content rules (from E4 spec):
+  (a) Count-cap drops → suggest the smallest `limit` that would reveal them:
+      risk_summary[dir][tier] is the minimum (current kept count + omitted count).
+      Emits one hint per direction+tier that has count-cap omissions.
+  (b) Byte-ceiling drops → suggest raising or zeroing `max_bytes`.
+      Emits one hint covering the total byte-ceiling drop.
+  (c) All-trimmed (entries lists all empty, risk_summary non-empty) → explicit
+      anti-false-safe line. Emitted BEFORE the byte-ceiling remedy hint.
+  (d) Both caps fired → both hints without double-counting. Count-cap portion =
+      truncated[dir][tier] - byte_capped_portion_per_tier. Since byte_capped.omitted
+      is a total (not per-direction/tier), we output the two remedies separately:
+      count-cap hints first, then the byte-ceiling hint.
+
+Null-contract:
+  `byte_capped=None` means the byte ceiling did not fire (same null-contract as
+  the handler's _apply_byte_ceiling usage). An empty {} byte_capped is handled
+  defensively (treated as not-fired).
+
+Never raises. On any exception returns [].
+"""
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Default tier/direction priority. These are DEFAULTS only — the handler injects the
+# canonical impact.py TIER_* constants via the tier_order/direction_order params so the
+# names have a single source of truth (the leaf stays standalone-testable without
+# importing impact.py, preserving leaf discipline). Order matters: highest priority
+# first (WILL_BREAK before MAY_NEED_TESTING) for DISPLAY; the byte-portion deduction
+# walks this reversed (least-valuable first) to mirror fit_to_byte_budget's trim order.
+_DEFAULT_TIER_ORDER = ("WILL_BREAK", "LIKELY_AFFECTED", "MAY_NEED_TESTING")
+_DEFAULT_DIRECTION_ORDER = ("upstream", "downstream")
+
+
+def generate_steer(
+    *,
+    truncated: dict[str, dict[str, int]],
+    byte_capped: dict[str, int] | None,
+    risk_summary: dict[str, dict[str, int]],
+    limit: int,
+    max_bytes: int,
+    tier_order: tuple[str, ...] = _DEFAULT_TIER_ORDER,
+    direction_order: tuple[str, ...] = _DEFAULT_DIRECTION_ORDER,
+) -> list[str]:
+    """Generate actionable truncation-steer hints from seam_impact trim metadata.
+
+    Called by handle_seam_impact AFTER per-tier capping and byte-ceiling trimming
+    have both run. Returns a flat list of ready-to-act prose strings. Returns []
+    (empty, never None) when nothing was trimmed or on any internal error.
+
+    Args:
+        truncated:   The merged per-direction/tier omitted count map.
+                     {direction: {tier: count}}. Includes BOTH count-cap and
+                     byte-ceiling drops (additive, as in the handler). May be {}.
+        byte_capped: The byte_capped metadata dict {"limit": int, "omitted": int}
+                     when the byte ceiling fired and dropped ≥1 entry, or None
+                     when the ceiling did not fire (unlimited or nothing trimmed).
+        risk_summary: The honest pre-cap total per direction+tier.
+                      {direction: {tier: count}}. Used to compute the suggested
+                      limit value (minimum that reveals all omitted entries).
+        limit:        The per-tier count cap that was applied (SEAM_IMPACT_MAX_RESULTS
+                      or the per-call override). Used in hint phrasing.
+        max_bytes:    The byte budget that was applied (SEAM_IMPACT_MAX_BYTES or the
+                      per-call override). Used in hint phrasing. 0 = unlimited.
+        tier_order:   Risk tiers in DISPLAY (highest-priority-first) order. Injected by
+                      the handler from impact.py's TIER_* constants (single source of truth).
+        direction_order: Directions in display order. Injected by the handler.
+
+    Returns:
+        list[str]: Prose hint lines. Empty list when nothing to say.
+                   Never raises — any exception returns [].
+    """
+    try:
+        return _generate_steer_impl(
+            truncated=truncated,
+            byte_capped=byte_capped,
+            risk_summary=risk_summary,
+            limit=limit,
+            max_bytes=max_bytes,
+            tier_order=tier_order,
+            direction_order=direction_order,
+        )
+    except Exception:
+        # Safety net: never break the read path. Empty steer is always safe.
+        # Logged (matching _apply_byte_ceiling's failure precedent) so a malformed-input
+        # bug that silently drops the steer — including the all-trimmed anti-false-safe
+        # warning generated inside this path — is observable rather than invisible.
+        logger.warning("seam_impact steer generation failed; omitting next_actions", exc_info=True)
+        return []
+
+
+def _total_risk(risk_summary: Any) -> int:
+    """Sum all counts in risk_summary. Returns 0 on malformed input."""
+    if not isinstance(risk_summary, dict):
+        return 0
+    total = 0
+    for dir_map in risk_summary.values():
+        if not isinstance(dir_map, dict):
+            continue
+        for count in dir_map.values():
+            if isinstance(count, int):
+                total += count
+    return total
+
+
+def _total_truncated(truncated: Any) -> int:
+    """Sum all counts in truncated. Returns 0 on malformed input."""
+    if not isinstance(truncated, dict):
+        return 0
+    total = 0
+    for dir_map in truncated.values():
+        if not isinstance(dir_map, dict):
+            continue
+        for count in dir_map.values():
+            if isinstance(count, int):
+                total += count
+    return total
+
+
+def _is_all_trimmed(
+    truncated: dict[str, dict[str, int]],
+    byte_capped: dict[str, int] | None,
+    risk_summary: dict[str, dict[str, int]],
+) -> bool:
+    """Return True when the byte ceiling dropped ALL entries (entries shown == 0).
+
+    All-trimmed means: risk_summary is non-empty (there ARE real dependents)
+    AND total truncated == total risk_summary (every entry was dropped).
+    We only flag this when byte_capped is present (the ceiling fired), because
+    all-entries-count-capped is a normal use case (the count cap is opt-in at
+    limit=0), while all-entries-byte-capped is the dangerous false-safe case.
+    """
+    if not byte_capped or not isinstance(byte_capped, dict):
+        return False
+    byte_omitted = byte_capped.get("omitted", 0)
+    if not isinstance(byte_omitted, int) or byte_omitted <= 0:
+        return False
+    total_risk = _total_risk(risk_summary)
+    total_trunc = _total_truncated(truncated)
+    # All-trimmed: every entry that exists in risk_summary was dropped.
+    return total_risk > 0 and total_trunc >= total_risk
+
+
+def _generate_steer_impl(
+    *,
+    truncated: dict[str, dict[str, int]],
+    byte_capped: dict[str, int] | None,
+    risk_summary: dict[str, dict[str, int]],
+    limit: int,
+    max_bytes: int,
+    tier_order: tuple[str, ...],
+    direction_order: tuple[str, ...],
+) -> list[str]:
+    """Inner implementation — only called when input types are validated by caller.
+
+    Separated from the public function so the try/except wraps the whole body.
+    """
+    # Validate core inputs are dicts to avoid TypeErrors below.
+    if not isinstance(truncated, dict):
+        return []
+    if not isinstance(risk_summary, dict):
+        return []
+
+    # Early exit: nothing was trimmed at all.
+    byte_capped_clean = byte_capped if isinstance(byte_capped, dict) else None
+    byte_omitted = 0
+    if byte_capped_clean:
+        raw_omitted = byte_capped_clean.get("omitted", 0)
+        byte_omitted = raw_omitted if isinstance(raw_omitted, int) else 0
+
+    total_trunc = _total_truncated(truncated)
+    if total_trunc == 0 and byte_omitted == 0:
+        return []
+
+    hints: list[str] = []
+
+    # ── (c) All-trimmed-to-nothing warning (must come first — most critical) ──
+    if _is_all_trimmed(truncated, byte_capped_clean, risk_summary):
+        hints.append(
+            "WARNING: The blast radius was trimmed to nothing by the byte ceiling. "
+            "This is NOT 'no dependents' — dependents exist but were omitted. "
+            "Pass max_bytes=0 for the full untrimmed blast radius before concluding "
+            "this symbol is safe to delete."
+        )
+        # After the all-trimmed warning, still emit the max_bytes remedy below
+        # (it is the actionable fix). Skip count-cap hints since the byte ceiling
+        # dominated and the count cap is irrelevant here.
+        if byte_capped_clean:
+            byte_limit = byte_capped_clean.get("limit", max_bytes)
+            if not isinstance(byte_limit, int):
+                byte_limit = max_bytes
+            hints.append(
+                f"Pass max_bytes=0 (currently {byte_limit}) for the full untrimmed blast radius."
+            )
+        return hints
+
+    # ── (a) Count-cap hints — one per direction+tier with count-cap omissions ──
+    # truncated[dir][tier] is the MERGED omitted count (count-cap drops + byte-ceiling
+    # drops, additive). The two have DIFFERENT remedies — count-cap drops are revealed by
+    # raising `limit`, byte-ceiling drops only by raising `max_bytes` — so attributing a
+    # byte-dropped entry to the count cap yields a hint ("Raise limit to N") that, when
+    # followed, does NOT reveal the entry (the agent re-queries, sees the same truncation,
+    # and may wrongly conclude the dependent is phantom).
+    #
+    # The count-cap portion is computable EXACTLY from risk_summary and limit, with no
+    # byte-drop data: the per-tier count cap keeps min(entries, limit), so it drops
+    # max(risk - limit, 0) from each tier (the cap is the SAME limit for every tier). This
+    # is exact — a tier that was NOT count-capped (risk <= limit) but byte-dropped yields
+    # portion == 0 and gets NO 'raise limit' hint, only the byte remedy below. (This is why
+    # we do not split the global byte_capped.omitted scalar across tiers — that scalar
+    # cannot say which tiers it came from, whereas max(risk - limit, 0) is exact.)
+    if limit > 0:  # limit == 0 (unlimited) ⇒ no count-cap drops anywhere
+        for direction in direction_order:
+            dir_risk = risk_summary.get(direction, {})
+            if not isinstance(dir_risk, dict):
+                continue
+            dir_trunc = truncated.get(direction, {})
+            if not isinstance(dir_trunc, dict):
+                dir_trunc = {}
+            for tier in tier_order:
+                merged = dir_trunc.get(tier, 0)
+                if not isinstance(merged, int) or merged <= 0:
+                    continue  # nothing omitted from this tier at all
+                risk = dir_risk.get(tier, 0)
+                if not isinstance(risk, int):
+                    risk = 0
+                # Exact count-cap drop; clamp to merged (can't exceed the total omitted).
+                portion = min(max(risk - limit, 0), merged)
+                if portion <= 0:
+                    continue  # this tier's omissions were ALL byte-ceiling drops
+                # Suggest the minimum limit that reveals every entry in this tier
+                # (risk = limit + portion when portion > 0, so this equals `risk`). Clamp
+                # to never suggest a value <= the current limit (which would tell the agent
+                # to LOWER the cap and HIDE entries).
+                suggested_limit = max(risk, limit + portion)
+                hints.append(
+                    f"Raise limit to {suggested_limit} to see {portion} more "
+                    f"{tier} {direction} dependents "
+                    f"(currently capped at {limit})."
+                )
+
+    # ── (b) Byte-ceiling hint ─────────────────────────────────────────────────
+    if byte_omitted > 0 and byte_capped_clean:
+        byte_limit = byte_capped_clean.get("limit", max_bytes)
+        if not isinstance(byte_limit, int):
+            byte_limit = max_bytes
+        hints.append(
+            f"Pass max_bytes=0 (currently {byte_limit}) for the full "
+            f"untrimmed blast radius ({byte_omitted} "
+            f"{'entry' if byte_omitted == 1 else 'entries'} trimmed by byte ceiling)."
+        )
+
+    return hints

seam/analysis/synthesis.py

@@ -0,0 +1,253 @@
+"""Edge-synthesis engine — pure function, no DB access, deterministic, never raises.
+
+LAYER: leaf — imports only stdlib + synthesis_channels. No DB access.
+
+This module implements whole-graph edge synthesis: given the already-extracted symbols,
+edges, and per-file source text, it synthesizes additional edges that a parser cannot see
+(dynamic dispatch, interface dispatch, observer callbacks, etc.) and returns them as a list
+of edge-like dicts ready for persistence.
+
+Channels implemented:
+  A2 — interface-override (this module): for each concrete class C that has an
+       extends/implements edge to a base/interface B, link every method of B to every
+       same-name method of C as a synthesized 'call' edge. Deliberate OVER-APPROXIMATION.
+       Direct subtypes only (one hop). Bounded by fanout_cap.
+
+  A1a — closure-collection (synthesis_channels.py): collection field iterated + element
+        invoked, paired with sites that append a closure to the same field (cross-file).
+        Emit dispatcher → appended-callback as synthesized call edge.
+        CRITICAL NEGATIVE: iteration without element invocation → no edge emitted.
+
+  A1b — event-emitter (synthesis_channels.py): registrar verbs (on[A-Z][A-Za-z]*, subscribe,
+        addListener, addEventListener, register, watch, listen, addCallback) paired with
+        dispatcher verbs (emit, trigger, notify, dispatch, fire, publish, flush), keyed
+        by event-string literal. Only NAMED handlers produce edges.
+
+Design rules (shared with clustering.py):
+  - Public function synthesize_edges() is PURE: no side effects, deterministic output.
+  - Never raises: all internal errors degrade to "no edge emitted" (same contract as
+    parsers: conservatism over explosions). The caller (synthesis_index.py) handles errors.
+  - Cap-bounded: fanout_cap limits edges per base-method/field/event to prevent explosions.
+  - Pairing by string names only — no node IDs, no graph DB. Mirrors how the rest of
+    Seam stores edges: source/target are plain symbol name strings.
+"""
+
+import logging
+from typing import Any
+
+from seam.analysis.synthesis_channels import (
+    run_closure_collection_channel,
+    run_event_emitter_channel,
+)
+
+logger = logging.getLogger(__name__)
+
+# Channel identifier for the interface-override synthesis.
+# Stored verbatim in edges.synthesized_by for provenance tracing.
+_CHANNEL_INTERFACE_OVERRIDE = "interface-override"
+
+# Inheritance edge kinds that trigger A2 override fan-out.
+_INHERITANCE_KINDS = frozenset({"extends", "implements"})
+
+
+def synthesize_edges(
+    symbols: list[dict[str, Any]],
+    edges: list[dict[str, Any]],
+    *,
+    file_sources: dict[str, str],
+    fanout_cap: int,
+) -> list[dict[str, Any]]:
+    """Synthesize dynamic-dispatch edges from the whole-graph symbol and edge data.
+
+    This is the main entry point for the synthesis engine. It is PURE: it reads
+    from the supplied in-memory data structures and returns a list of new edge dicts,
+    never touching the database or raising any exception.
+
+    Args:
+        symbols:      List of symbol dicts from the DB (must have 'name' and 'kind' keys).
+        edges:        List of edge dicts from the DB (must have 'source', 'target', 'kind').
+        file_sources: Dict mapping file path → source text (reserved for A1 channels;
+                      the A2 channel does not use source text but accepts it for a stable
+                      API so slice 2 can add channels without changing this signature).
+        fanout_cap:   Maximum synthesized edges per base-method across all implementations.
+                      0 = unlimited (no cap applied).
+
+    Returns:
+        List of edge-like dicts, each with keys:
+          source, target, kind, confidence, synthesized_by
+        (and sentinel values for file/line since synthesized edges are not file-scoped).
+
+    Never raises: any internal error degrades to returning whatever edges were built
+    before the error occurred, and logs a warning.
+    """
+    result: list[dict[str, Any]] = []
+
+    # A2: interface-override channel (symbol/edge-graph based, no source text needed).
+    try:
+        result.extend(_run_a2_interface_override(symbols, edges, fanout_cap))
+    except Exception as exc:  # noqa: BLE001
+        logger.warning(
+            "synthesis: A2 interface-override channel failed (%s: %s) — "
+            "no edges from this channel",
+            type(exc).__name__,
+            exc,
+        )
+
+    # A1a: closure-collection channel (source-text based).
+    try:
+        result.extend(run_closure_collection_channel(symbols, file_sources, fanout_cap))
+    except Exception as exc:  # noqa: BLE001
+        logger.warning(
+            "synthesis: closure-collection channel failed (%s: %s) — "
+            "no edges from this channel",
+            type(exc).__name__,
+            exc,
+        )
+
+    # A1b: event-emitter channel (source-text based).
+    try:
+        result.extend(run_event_emitter_channel(symbols, file_sources, fanout_cap))
+    except Exception as exc:  # noqa: BLE001
+        logger.warning(
+            "synthesis: event-emitter channel failed (%s: %s) — "
+            "no edges from this channel",
+            type(exc).__name__,
+            exc,
+        )
+
+    return result
+
+
+def _run_a2_interface_override(
+    symbols: list[dict[str, Any]],
+    edges: list[dict[str, Any]],
+    fanout_cap: int,
+) -> list[dict[str, Any]]:
+    """A2 channel: interface/base→implementation method fan-out.
+
+    Algorithm (one hop, no transitive walk, deliberate over-approximation):
+
+    1. Build a set of all symbol names that are methods (kind='method').
+       Symbol names for methods follow the 'ClassName.methodName' qualified pattern.
+
+    2. For each symbol with an 'extends' or 'implements' edge pointing to a base B,
+       the source of that edge is the concrete class C (C extends/implements B).
+
+    3. For each method B.m of base B that exists in the symbol table,
+       check if C.m also exists. If so, emit:
+         source=B.m, target=C.m, kind='call', confidence='INFERRED',
+         synthesized_by='interface-override'
+
+    4. Apply fanout_cap: if fanout_cap > 0, cap at most fanout_cap implementations
+       per base method (i.e. at most fanout_cap edges per source='B.m').
+
+    WHY over-approximation: correctly resolving which implementation runs at a given
+    call site would require type inference, MRO, or runtime analysis. Seam's synthesis
+    contract is: emit ALL plausible dispatch targets (conservative on false negatives),
+    with a cap to prevent graph explosions. An agent querying seam_impact sees ALL
+    implementations — which is the right default for blast-radius analysis.
+
+    WHY one-hop only: if C extends B extends A, this channel emits B.m→C.m and A.m→B.m
+    separately (via their respective direct inheritance edges) — both are emitted in the
+    same pass because both are direct inheritance edges in the edges table. No transitive
+    walk is required to achieve this; the direct-edge scan naturally covers all levels.
+    """
+    # ── Step 1: Build symbol lookup structures ────────────────────────────────
+    # method_names: set of all qualified method names 'ClassName.methodName'.
+    # class_methods: maps class/interface name → set of bare method names.
+    method_names: set[str] = set()
+    class_methods: dict[str, set[str]] = {}
+
+    for sym in symbols:
+        try:
+            name = sym.get("name", "")
+            kind = sym.get("kind", "")
+            if not name or not kind:
+                continue
+            if kind == "method" and "." in name:
+                method_names.add(name)
+                cls, bare = name.split(".", 1)
+                class_methods.setdefault(cls, set()).add(bare)
+        except Exception:  # noqa: BLE001
+            # Malformed symbol dict — skip silently (never-raise contract).
+            continue
+
+    # ── Step 2: Build inheritance map: subclass → set of direct bases ─────────
+    # sub_to_bases: maps 'ConcreteClass' → {'IBase1', 'IBase2', ...}
+    sub_to_bases: dict[str, set[str]] = {}
+
+    for edge in edges:
+        try:
+            kind = edge.get("kind", "")
+            if kind not in _INHERITANCE_KINDS:
+                continue
+            src = edge.get("source", "")
+            tgt = edge.get("target", "")
+            if not src or not tgt:
+                continue
+            sub_to_bases.setdefault(src, set()).add(tgt)
+        except Exception:  # noqa: BLE001
+            continue
+
+    # ── Step 3: Synthesize override call edges ────────────────────────────────
+    # For each (concrete_class, base) pair from inheritance edges,
+    # for each method of base, check if concrete_class also has that method.
+    # Track per-base-method emission count to enforce fanout_cap.
+
+    # base_method_count: base_method_name → number of synth edges emitted so far
+    base_method_count: dict[str, int] = {}
+    result: list[dict[str, Any]] = []
+
+    # Sort for determinism (same graph → same edges, same order).
+    for sub_cls in sorted(sub_to_bases):
+        bases = sorted(sub_to_bases[sub_cls])
+        for base in bases:
+            base_bare_methods = class_methods.get(base, set())
+            if not base_bare_methods:
+                continue  # Base has no indexed methods — skip.
+
+            sub_bare_methods = class_methods.get(sub_cls, set())
+            if not sub_bare_methods:
+                continue  # Concrete class has no methods — skip.
+
+            # Emit an edge for each method name shared between base and subclass.
+            for bare_method in sorted(base_bare_methods):
+                if bare_method not in sub_bare_methods:
+                    continue  # No matching implementation in subclass — skip.
+
+                base_method_name = f"{base}.{bare_method}"
+                impl_method_name = f"{sub_cls}.{bare_method}"
+
+                # Apply fanout_cap per base method.
+                if fanout_cap > 0:
+                    current_count = base_method_count.get(base_method_name, 0)
+                    if current_count >= fanout_cap:
+                        logger.debug(
+                            "synthesis: A2 fanout_cap=%d reached for %s — skipping %s",
+                            fanout_cap,
+                            base_method_name,
+                            impl_method_name,
+                        )
+                        continue
+                    base_method_count[base_method_name] = current_count + 1
+
+                result.append({
+                    "source": base_method_name,
+                    "target": impl_method_name,
+                    "kind": "call",
+                    "confidence": "INFERRED",
+                    "synthesized_by": _CHANNEL_INTERFACE_OVERRIDE,
+                    # Synthesized edges are not file-scoped. The bridge (index_synthesis)
+                    # stores them under the synthetic ':synthesis:' file row and supplies
+                    # file_id + line at persist time — the leaf emits neither sentinel.
+                    "line": 0,
+                })
+
+    logger.debug(
+        "synthesis: A2 interface-override channel emitted %d edges "
+        "(%d subclass→base pairs, %d base methods checked)",
+        len(result),
+        sum(len(v) for v in sub_to_bases.values()),
+        len(base_method_count),
+    )
+    return result