sourcecode 2.7.0__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.7.0"
+__version__ = "3.0.0"

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",