sourcecode 2.0.1__py3-none-any.whl → 2.2.0__py3-none-any.whl

sourcecode/__init__.py

@@ -1,3 +1,7 @@
-"""sourcecode — Deterministic codebase context maps for AI coding agents."""
+"""ASK Engine (CLI: ``ask``) — Deterministic codebase context maps for AI coding agents.
 
-__version__ = "2.0.1"
+ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode`` is
+the legacy compatibility alias and the Python/PyPI package name. See
+docs/PRODUCT_IDENTITY.md (normative)."""
+
+__version__ = "2.2.0"

sourcecode/caller_metrics.py

@@ -0,0 +1,42 @@
+"""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.
+"""
+
+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."
+)