sourcecode 3.3.0__py3-none-any.whl → 3.5.0__py3-none-any.whl

sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "3.3.0"
+__version__ = "3.5.0"

sourcecode/archetype.py

@@ -30,6 +30,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Optional
 
+from sourcecode.degradation import analysis_limiter as _analysis_limiter
 from sourcecode.graph_evidence import GraphEvidence, GraphEvidenceProvider, GraphEvidenceResult
 from sourcecode.schema import SourceMap
 from sourcecode.tree_utils import flatten_file_tree
@@ -157,6 +158,9 @@ class ArchetypeAnalysis:
             },
             "signals_used": self.signals_used,
             "signals_missing": self.signals_missing,
+            # I-8: the names alone say nothing about what the classification lost.
+            # Same authority the review-pr limiter uses, so both read alike.
+            "analysis_limiter": _analysis_limiter(self.signals_missing),
             "generated_from": self.generated_from,
             "graph_metrics": {k: round(v, 4) for k, v in self.graph_metrics.items()},
         }

sourcecode/cache_model.py

@@ -125,10 +125,11 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "`--env-map`, `--depth N` and `--exclude` change the *analysis*, so they miss the "
                  "warmed core and rescan — this is the 171 s the field measured after a 103 s warm.",
                  "--compact 17.7 s → 0.3 s; --agent --full --env-map --depth 20 34.7 s → 33.9 s (no gain)"),
-    CommandCache("posture", ("parse",), "shared", False,
-                 "Resolves the conditional bean graph on every run; a warm saves it the Java parse, "
-                 "which is the smaller half of its work.",
-                 "24.5 s → 19.3 s"),
+    CommandCache("posture", ("cir", "parse"), "shared", False,
+                 "Resolves the conditional bean graph on every run, over the shared CIR a warm "
+                 "builds — the parse it used to repeat for itself. `--diff` compares two profile "
+                 "sets over that one IR, so the second side costs the resolution only.",
+                 "10.1 s → 1.6 s"),
     CommandCache("endpoints", ("ris", "parse"), "none", False,
                  "Recomputes the endpoint surface on every run and refreshes the RIS endpoint index. "
                  "Measured: a warm buys it nothing.",

sourcecode/caller_metrics.py

@@ -1,44 +1,151 @@
-"""Single source of truth for the caller / fan-in metric reconciliation note.
-
-Three commands report a "how many things reference this class" number, each
-derived from a different graph projection. Read side by side they can look
-contradictory (e.g. 215 vs 103 for the same class) — they are not. They count
-different populations:
-
-    modernize.in_degree  >=  explain.incoming_callers  ~=  impact.stats.direct_caller_count
-
-- ``modernize.in_degree`` counts graph *edges* (all edge types, symbol level, not
-  deduplicated per class) — a blast-radius ranking weight, always the largest, and
-  not a count of classes.
-- ``explain.incoming_callers`` and ``impact.stats.direct_caller_count`` both count
-  *distinct dependent classes*. They normally match and are always the same order
-  of magnitude, but can differ by a small margin because each includes a slightly
-  different edge set (import-only references, DI-interface resolution). The
-  truncated ``impact.direct_callers`` array is a display sample, not the count.
-
-Empirically verified across repositories (Broadleaf ExtensionManager: 215 / 103 /
-103; petclinic entities & repositories: equal; occasional margin-of-one divergence
-on classes with import-only references). The strict-equality claim was deliberately
-NOT made — the note asserts only the robust ordering and the "same distinct-class
-metric" relationship.
-
-Every command that emits one of these numbers references this same string so the
-explanation can never drift or contradict itself between commands.
+"""The authority for "how many things reference this class" (ADR-0008, R11-R14).
+
+Several commands publish such a number. They are not the same number, and the
+gap is not a rounding margin: measured on `org.broadleafcommerce.common.money.Money`
+(BroadleafCommerce, one version, one machine) the product published **four**
+figures — 1 868, 673, 418 and 151 — under names that all read as fan-in. Field
+evaluation #5 asked the only question that matters about that: *"¿el blast radius
+son 484 o 611 clases?"*
+
+The previous version of this module promised a relationship in prose:
+`modernize.in_degree >= explain.incoming_callers ~= impact.stats.direct_caller_count`,
+with `in_degree` *"always the largest of the three"* and the other two differing
+*"by a small margin"*. Measurement falsified both halves — `impact-chain` was not
+in the relationship at all and was 2,8× the figure declared always-largest, and
+the *"small margin"* was 177 %. A published relationship is a contract, so this
+module no longer publishes prose: it publishes a **registry of figures**, each
+with its unit and its edge population, and the note is *generated* from it. What
+the battery can assert is what the registry says, which is why it cannot drift
+again.
+
+Two of the four figures were also wrong about their own unit, and that is the
+defect underneath the divergence:
+
+- `impact.stats.direct_caller_count` counted caller **symbols** — 418, of which
+  346 were method-level — while its own note called them distinct classes. The
+  same class was counted once per method that touches the target. As classes:
+  **134**.
+- `explain.incoming_callers` deduplicated by **simple name**, collapsing 186
+  distinct classes into 151 and silently dropping 35 of them (the identity rule
+  that made `by_controller` keys FQNs applies here too).
+
+With both fixed, the residual difference is a *declared* one: `impact` excludes
+`imports` edges from a blast radius (an import is not a runtime dependency,
+FP-001) and `explain` includes them, so `explain` counts a superset. That is a
+fact about populations, stated per figure, not a promise about magnitudes.
 """
+from __future__ import annotations
+
+from typing import Iterable
+
+from sourcecode.fqn_utils import normalize_owner_fqn
+
+#: Unit tags. Two figures are comparable only if both agree.
+UNIT_CLASSES = "distinct_classes"
+UNIT_SYMBOLS = "caller_symbols"
+UNIT_EDGES = "graph_edges"
+
+#: Population tags — *which* references were admitted, not how they were counted.
+POP_REFERENCES_WITH_IMPORTS = "references_including_imports"
+POP_REFERENCES_NO_IMPORTS = "references_excluding_imports"
+POP_ALL_EDGES = "all_incoming_edges"
+POP_TRANSITIVE_CHAIN = "transitive_chain"
+
+
+def caller_classes(symbols: Iterable[str], *, exclude: Iterable[str] = ()) -> set[str]:
+    """The distinct classes behind a set of caller symbols — the fan-in unit.
+
+    A caller list mixes granularities: `pkg.Utils`, `pkg.Utils#getMoney`,
+    `pkg.Utils.field`. Counting it raw answers "how many references" and calls
+    it "how many classes". This is the one place that normalisation happens.
+    """
+    excluded = {normalize_owner_fqn(e) for e in exclude}
+    out: set[str] = set()
+    for sym in symbols:
+        if not sym:
+            continue
+        owner = normalize_owner_fqn(sym)
+        if owner and owner not in excluded:
+            out.add(owner)
+    return out
+
+
+def caller_class_count(symbols: Iterable[str], *, exclude: Iterable[str] = ()) -> int:
+    """``len(caller_classes(...))`` — the number a fan-in figure may publish."""
+    return len(caller_classes(symbols, exclude=exclude))
+
+
+#: Every published fan-in figure, with what it counts. A figure that is not here
+#: is not allowed to be emitted (asserted by `tests/test_fan_in_authority.py`).
+FAN_IN_FIGURES: tuple[dict[str, str], ...] = (
+    {
+        "key": "explain.incoming_callers_count",
+        "unit": UNIT_CLASSES,
+        "population": POP_REFERENCES_WITH_IMPORTS,
+        "means": "distinct classes that reference this class, imports included",
+    },
+    {
+        "key": "impact.stats.direct_caller_count",
+        "unit": UNIT_CLASSES,
+        "population": POP_REFERENCES_NO_IMPORTS,
+        "means": "distinct classes that call or depend on this class; import-only "
+                 "references are excluded from a blast radius",
+    },
+    {
+        "key": "impact.stats.direct_caller_symbol_count",
+        "unit": UNIT_SYMBOLS,
+        "population": POP_REFERENCES_NO_IMPORTS,
+        "means": "the same population counted as reference sites (methods and "
+                 "fields), which is what the risk score weighs",
+    },
+    {
+        "key": "impact-chain.metadata.chain_classes_total",
+        "unit": UNIT_CLASSES,
+        "population": POP_TRANSITIVE_CHAIN,
+        "means": "every class in the call chain, direct AND transitive — a reach "
+                 "figure, not fan-in; unbounded above by any direct-caller count",
+    },
+    {
+        "key": "impact-chain.metadata.direct_caller_count",
+        "unit": UNIT_CLASSES,
+        "population": POP_REFERENCES_NO_IMPORTS,
+        "means": "distinct classes calling the target at depth 1",
+    },
+    {
+        "key": "modernize.in_degree",
+        "unit": UNIT_EDGES,
+        "population": POP_ALL_EDGES,
+        "means": "incoming graph edges at symbol level, not deduplicated to "
+                 "classes — a ranking weight, never a count of classes",
+    },
+)
+
+
+def _render_reconciliation() -> str:
+    lines = [
+        "Fan-in figures differ across commands because they count different "
+        "things. Each figure below states its unit and the references it admits; "
+        "two figures are comparable only when both match. No ordering between "
+        "units is promised — an earlier version of this note promised one and "
+        "measurement falsified it."
+    ]
+    for fig in FAN_IN_FIGURES:
+        lines.append(f"{fig['key']} [{fig['unit']}] = {fig['means']}.")
+    lines.append(
+        "Any list of callers in the payload may be truncated for output size and "
+        "is a display sample: read the *_count fields, never len() of the array."
+    )
+    return " ".join(lines)
+
+
+CALLER_METRIC_RECONCILIATION: str = _render_reconciliation()
 
-CALLER_METRIC_RECONCILIATION: str = (
-    "Fan-in / caller counts differ across commands BY DESIGN and are not "
-    "contradictory. For the same class the expected relationship is: "
-    "modernize.in_degree >= explain.incoming_callers ~= impact.stats.direct_caller_count. "
-    "modernize.in_degree = raw count of ALL incoming graph edges (imports, injects, "
-    "extends/implements, references, annotations), counted at symbol level and NOT "
-    "deduplicated per class — a blast-radius ranking weight, not a count of classes; "
-    "it is always the largest of the three. explain.incoming_callers and "
-    "impact.stats.direct_caller_count both count DISTINCT dependent classes "
-    "(deduplicated to class level); they normally match but can differ by a small "
-    "margin because each includes a slightly different edge set (e.g. import-only "
-    "references or DI-interface resolution). The top-level impact.direct_callers array "
-    "may be truncated for output size — use stats.direct_caller_count for the true total."
+#: Kept for the payload key that was `callers_total` before it was named for what
+#: it counts. Consumers reading the old key get the same number and this note.
+CALLERS_TOTAL_DEPRECATION: str = (
+    "metadata.callers_total is the size of the whole call chain (direct + "
+    "transitive), not a fan-in count; it is superseded by "
+    "metadata.chain_classes_total and metadata.direct_caller_count."
 )
 
 

sourcecode/caller_reach.py

@@ -0,0 +1,205 @@
+"""What a change to a symbol reaches backwards — one traversal, one edge population.
+
+Fan-in *counting* has an authority (`caller_metrics`). What it counts did not:
+two traversals walked the reverse graph, and they disagreed about both which
+edges are a dependency and which nodes have any.
+
+Measured on `org.broadleafcommerce.common.money.Money` (BroadleafCommerce, one
+version, one machine), the divergence landed on the blast-radius axis as a
+false zero: `impact` published ``endpoints_affected_count: 0`` while
+`impact-chain` returned 21 endpoints across 2 controllers for the same symbol
+at the same depth. `impact` reached 241 classes and **no controller at all**;
+`impact-chain` reached 441 and found them. Two causes, both in the traversal:
+
+- **Callers of a class live on its method keys.** ``reverse_graph`` stores the
+  callers of ``Foo#doWork`` under ``"Foo#doWork"``, never under ``"Foo"``. The
+  older traversal looked up the exact key only, so every time the walk enqueued
+  a class-level node — which is what a DI ``injects`` edge normalises to — the
+  chain terminated there. That is why the indirect reach was 125 symbols instead
+  of 1 442, and why no controller was ever reached: the controller is two DI
+  hops past the point where the walk stopped.
+- **The two edge populations were different, while a comment claimed they were
+  the same.** The older set skipped ``contained_in`` and ``imports`` and said it
+  was *"consistent with spring_impact._SKIP_EDGE_TYPES"*; that set also skips
+  ``implements`` and ``extends``, because an implementor does not call an
+  interface by virtue of implementing it (CH-006: on a 43-implementor interface
+  this turned a leaf endpoint into 42 false direct callers). So one traversal
+  under-reached while admitting false callers.
+
+This module is the single authority for the reach fact. Both `impact` and
+`impact-chain` walk it, so they agree by construction rather than by review.
+Counting the result is still `caller_metrics`' job: reach produces symbols, and
+a symbol is not a class.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from sourcecode.fqn_utils import normalize_owner_fqn
+
+#: Edge types excluded from caller reach — the one definition.
+#:
+#: ``contained_in`` — structural membership (method → enclosing class), not a call.
+#: ``imports`` — a type reference, not a runtime call (FP-001). Including it chains
+#: through DTOs and entities that merely name the type.
+#: ``implements`` / ``extends`` — CH-006: the reverse edge on an interface lists its
+#: implementors, and an implementor does not *call* the interface by implementing
+#: it. The interface→impl expansion that IS wanted flows through the
+#: `ImplementationGraph` indices below, not through these edges.
+SKIP_EDGE_TYPES: frozenset[str] = frozenset(
+    {"contained_in", "imports", "implements", "extends"}
+)
+
+#: Hub-class guard: above this many unique direct callers, deep BFS is O(n^depth).
+CALLER_CAP = 500
+
+
+def class_method_index(
+    reverse_graph: dict[str, dict[str, list[str]]],
+) -> dict[str, list[str]]:
+    """``{class FQN: [its method-level reverse-graph keys]}``.
+
+    The index that makes a class-level node traversable at all. Built once per
+    walk; every lookup after that is O(1).
+    """
+    index: dict[str, list[str]] = {}
+    for key in reverse_graph:
+        if "#" in key:
+            index.setdefault(key.split("#")[0], []).append(key)
+    return index
+
+
+def edges_for(
+    fqn: str,
+    reverse_graph: dict[str, dict[str, list[str]]],
+    index: Optional[dict[str, list[str]]] = None,
+    impl_graph: object | None = None,
+) -> list[tuple[str, list[str]]]:
+    """Every ``(edge type, callers)`` pair that belongs to *fqn*.
+
+    For a class-level FQN that includes the entries stored under its method keys
+    and, when an `ImplementationGraph` is supplied, the reverse edges of the
+    interfaces it implements — callers inject the interface, not the
+    implementation, so the DI boundary is crossed here or not at all.
+    """
+    edges: list[tuple[str, list[str]]] = list((reverse_graph.get(fqn) or {}).items())
+    if "#" in fqn:
+        return edges
+    idx = class_method_index(reverse_graph) if index is None else index
+    for method_key in idx.get(fqn, []):
+        edges.extend((reverse_graph.get(method_key) or {}).items())
+    if impl_graph is not None:
+        for iface in impl_graph.interfaces_of(fqn):  # type: ignore[attr-defined]
+            edges.extend((reverse_graph.get(iface) or {}).items())
+            for method_key in idx.get(iface, []):
+                edges.extend((reverse_graph.get(method_key) or {}).items())
+    return edges
+
+
+def callers_of(
+    fqn: str,
+    reverse_graph: dict[str, dict[str, list[str]]],
+    index: Optional[dict[str, list[str]]] = None,
+    impl_graph: object | None = None,
+) -> list[str]:
+    """The callers of *fqn*: reach edges only, injection sites normalised, ordered.
+
+    An ``injects`` edge names the injection *site* (``pkg.Class.field``,
+    ``pkg.Class#<init>``), not a caller; the owning class is what depends on the
+    target, and it is what the walk has to continue from (CH-002).
+    """
+    callers: list[str] = []
+    seen: set[str] = set()
+    for edge_type, fqn_list in edges_for(fqn, reverse_graph, index, impl_graph):
+        if edge_type in SKIP_EDGE_TYPES:
+            continue
+        for caller in fqn_list:
+            normalized = normalize_owner_fqn(caller) if edge_type == "injects" else caller
+            if normalized not in seen:
+                seen.add(normalized)
+                callers.append(normalized)
+    return callers
+
+
+def bfs_callers(
+    seed_fqns: list[str],
+    reverse_graph: dict[str, dict[str, list[str]]],
+    max_depth: int,
+    impl_graph: object | None = None,
+    method_scoped: bool = False,
+) -> tuple[list[str], list[str], bool, int]:
+    """Walk the reverse graph from *seed_fqns*.
+
+    Returns ``(direct, indirect, was_truncated, self_excluded)``. ``direct`` is
+    depth 1 — the callers of the seeds themselves; ``indirect`` is depth 2 and
+    beyond, up to *max_depth*. ``was_truncated`` says the hub-class guard capped
+    the walk, which makes the result a floor.
+
+    A class's own members are members, not external callers, so they are dropped
+    and counted (BUG #2 — leaving them in inflated a blast radius ~12×). For a
+    *method*-scoped query the only true self-reference is the seed method calling
+    itself: a different method of the same class is a legitimate caller, and
+    applying the class rule there produced a false "0 callers / isolated" for
+    every private helper (P0-IMPACT-01).
+    """
+    visited: set[str] = set(seed_fqns)
+    direct: list[str] = []
+    indirect: list[str] = []
+    was_truncated = False
+
+    seed_classes: set[str] = {normalize_owner_fqn(s) for s in seed_fqns}
+    seed_set: set[str] = set(seed_fqns)
+    self_excluded = 0
+
+    def _is_self_reference(caller: str) -> bool:
+        if method_scoped:
+            return caller in seed_set  # only genuine recursion of a seed method
+        return normalize_owner_fqn(caller) in seed_classes
+
+    index = class_method_index(reverse_graph)
+
+    def _edges(fqn: str) -> list[tuple[str, list[str]]]:
+        return edges_for(fqn, reverse_graph, index, impl_graph)
+
+    # Hub-class guard on the UNIQUE direct caller set, not the raw sum per seed:
+    # interface expansion adds many method-level seeds that share callers, and
+    # counting those twice tripped the guard on symbols that never needed it.
+    unique_direct: set[str] = set()
+    for seed in seed_fqns:
+        for etype, fqn_list in _edges(seed):
+            if etype not in SKIP_EDGE_TYPES:
+                unique_direct.update(c for c in fqn_list if not _is_self_reference(c))
+
+    effective_depth = 1 if len(unique_direct) > CALLER_CAP else max_depth
+    if effective_depth < max_depth:
+        was_truncated = True
+
+    queue: list[tuple[str, int]] = [(s, 0) for s in seed_fqns]
+
+    def _add_caller(caller: str, depth: int) -> None:
+        nonlocal self_excluded
+        if caller in visited:
+            return
+        if _is_self_reference(caller):
+            visited.add(caller)
+            self_excluded += 1
+            return
+        visited.add(caller)
+        (direct if depth == 0 else indirect).append(caller)
+        if depth + 1 < effective_depth:
+            queue.append((caller, depth + 1))
+
+    while queue:
+        fqn, depth = queue.pop(0)
+        if depth >= effective_depth:
+            continue
+        for etype, fqn_list in _edges(fqn):
+            if etype in SKIP_EDGE_TYPES:
+                continue
+            for caller in fqn_list:
+                if etype == "injects":
+                    _add_caller(normalize_owner_fqn(caller), depth)
+                else:
+                    _add_caller(caller, depth)
+
+    return direct, indirect, was_truncated, self_excluded