sourcecode 2.6.10__py3-none-any.whl → 3.0.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__ = "2.6.10"
+__version__ = "3.0.0"

sourcecode/archetype.py

@@ -604,12 +604,23 @@ class ArchetypeClassifier:
             # Gini alone labeling a REST API an "engine") — is a single point of view and
             # must not read as high confidence (field-eval Fase 0).
             distinct_signals = len({e.signal for e in top.evidence if e.contribution > 0})
+            # Diversity by COUNT is satisfiable while one signal carries the
+            # verdict: an audited repo was labelled "engine" at high confidence on
+            # 1.500 of a 1.504 score — a fan-in Gini alone, with the second signal
+            # contributing 0.3%. Counting it as two views is a fiction, so a label
+            # whose top signal supplies almost all of its score cannot be "high"
+            # however many other signals nominally touch it.
+            _contributions = sorted(
+                (e.contribution for e in top.evidence if e.contribution > 0), reverse=True
+            )
+            top_signal_share = (_contributions[0] / top.score) if _contributions else 1.0
             if (
                 confident_enough
                 and rel_margin >= 0.4
                 and mass_backed
                 and graph_backed
                 and distinct_signals >= 2
+                and top_signal_share <= 0.8
             ):
                 confidence = "high"
             elif confident_enough and rel_margin >= 0.25 and mass_backed:

sourcecode/cache.py

@@ -75,11 +75,52 @@ SCHEMA_VERSION: str = "2"
 #: Bump to invalidate all L1 core caches (independent of snapshot version).
 CORE_SCHEMA_VERSION: str = "1"
 
-#: Bump when analysis logic or output schema changes — NOT on every package release.
-#: This is the stable part of the L1 core cache key.  Package version bumps (patch,
-#: minor) must NOT bump this value unless the cached data format actually changed.
+#: Manual override for invalidating all L1 core caches. Rarely needed now that the
+#: key carries :func:`analyzer_fingerprint`; kept as an escape hatch for cases the
+#: fingerprint cannot see (a changed dependency, a corrected cache format).
+#: Package version bumps must NOT bump this value.
 ANALYZER_CACHE_VERSION: str = "1"
 
+
+def analyzer_fingerprint() -> str:
+    """Content hash of the analysis code, memoised for the process.
+
+    A cache key built only from the repository state and a hand-maintained version
+    constant cannot notice that the analyzer itself changed. That discipline failed
+    exactly as designed-by-humans disciplines do: five consecutive fixes to analysis
+    logic shipped without anyone bumping ``ANALYZER_CACHE_VERSION``, so an upgraded
+    install kept serving pre-fix results from cache on an unchanged commit — the
+    fixes looked inert until the user cleared the cache by hand.
+
+    Hashing file *content* (not mtime) keeps the key stable across reinstalls and
+    identical checkouts on different machines, so caches stay shareable. Any edit to
+    any module invalidates every entry: over-invalidation costs a re-analysis,
+    under-invalidation reports facts the current code would not produce.
+
+    Falls back to the package version when the source is unreadable (zipimport,
+    frozen builds) — degraded, never wrong-by-silence.
+    """
+    global _ANALYZER_FINGERPRINT
+    if _ANALYZER_FINGERPRINT is not None:
+        return _ANALYZER_FINGERPRINT
+    digest = hashlib.sha256()
+    try:
+        pkg_root = Path(__file__).resolve().parent
+        sources = sorted(pkg_root.rglob("*.py"))
+        if not sources:
+            raise OSError("no analyzer sources found")
+        for src in sources:
+            digest.update(src.relative_to(pkg_root).as_posix().encode("utf-8"))
+            digest.update(src.read_bytes())
+        _ANALYZER_FINGERPRINT = digest.hexdigest()[:12]
+    except Exception:
+        from sourcecode import __version__ as _pkg_version
+        _ANALYZER_FINGERPRINT = f"pkg-{_pkg_version}"
+    return _ANALYZER_FINGERPRINT
+
+
+_ANALYZER_FINGERPRINT: Optional[str] = None
+
 #: Fields eligible for CAS deduplication (applied to top-level JSON dict keys).
 _CAS_FIELDS: frozenset[str] = frozenset([
     "file_paths",

sourcecode/caller_metrics.py

@@ -40,3 +40,22 @@ CALLER_METRIC_RECONCILIATION: str = (
     "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."
 )
+
+
+# Cycle / tangle metrics come from TWO different graphs. Both are correct; they
+# answer different questions, and without saying so the pair reads as one command
+# contradicting another (external audit 2026-07-25: modernize reported 15 cyclic
+# tangles while retrieve subsystem-coupling reported import_cycles: 0).
+CYCLE_METRIC_RECONCILIATION: str = (
+    "Cycle metrics differ across commands BY DESIGN. modernize.cross_module_tangles "
+    "is computed over the SYMBOL dependency graph, aggregated to subsystem packages: "
+    "coupling_type=cyclic means two subsystems reference each other (a 2-cycle "
+    "between package groups). The module-graph metrics (import_cycles, cyclic_density, "
+    "scc_mass — used by archetype and the subsystem-coupling retrieval intent) are "
+    "computed over the MODULE/DIRECTORY graph, are bounded for cost (node/edge caps), "
+    "and count strongly-connected components among modules. A repo can therefore "
+    "show mutual package-level coupling (tangles > 0) with no module-level SCC "
+    "(import_cycles = 0): the coupling exists between package groups inside the same "
+    "module. Neither number invalidates the other — read tangles for decomposition "
+    "risk and import_cycles for module-graph topology."
+)