sourcecode 3.7.0__py3-none-any.whl → 4.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__ = "3.7.0"
+__version__ = "4.0.0"

sourcecode/archetype.py

@@ -175,8 +175,13 @@ class _Features:
     module_count: int
     concept_mass: dict[str, float]        # concept → fraction of source files
     entry_kinds: dict[str, int]
-    endpoint_total: int
-    endpoint_share: float                 # endpoints per source file
+    # `None` when the endpoint surface was NOT measured (no root to read, or the
+    # extraction failed). It used to be 0, which is a different claim: a score
+    # that reads "no HTTP surface" off an unknown one refutes `api-first` and
+    # actively supports `worker`, so an unmeasured repository was classified as
+    # if it exposed nothing (I-3/R9, inside a score).
+    endpoint_total: "Optional[int]"
+    endpoint_share: "Optional[float]"     # endpoints per source file
     packaging: Optional[str]
     frameworks: set[str]
     graph_hubs: list[str]
@@ -250,7 +255,11 @@ class ArchetypeClassifier:
             signals_missing=f.signals_missing,
             generated_from=(
                 f"{f.total_files} source files, {f.module_count} modules, "
-                f"{f.endpoint_total} endpoints"
+                + (
+                    f"{f.endpoint_total} endpoints"
+                    if f.endpoint_total is not None
+                    else "endpoint surface not measured"
+                )
             ),
             graph_metrics=f.graph_metrics,
         )
@@ -299,8 +308,10 @@ class ArchetypeClassifier:
             missing.append("entry_points")
 
         endpoint_total = self._endpoint_count(root)
-        endpoint_share = (endpoint_total / total) if total else 0.0
-        if root is not None:
+        endpoint_share = (
+            (endpoint_total / total) if (endpoint_total is not None and total) else None
+        )
+        if endpoint_total is not None:
             used.append("endpoints")
         else:
             missing.append("endpoints")
@@ -519,21 +530,31 @@ class ArchetypeClassifier:
         # api-first: HTTP surface must be significant relative to size. Ramp so a
         # rounding-error surface cannot win: 0 below 0.5 endpoints/100 files, linear
         # to full strength at >=2/100 files. (neo4j: 18/5600 = 0.32/100 -> 0.)
-        density = f.endpoint_share * 100
-        api_strength = max(0.0, min(1.0, (density - 0.5) / 1.5)) if f.endpoint_total else 0.0
-        add("api-first", "endpoint_density",
-            f"{f.endpoint_total} endpoints over {f.total_files} files "
-            f"({density:.2f}/100 files)",
-            3.0, api_strength, 1.0)
+        if f.endpoint_share is None:
+            # Unmeasured, not zero: contribute nothing and say which axis is blind.
+            add("api-first", "endpoint_density",
+                "endpoint surface not measured — this dimension is scored without it",
+                3.0, 0.0, 0.0)
+        else:
+            density = f.endpoint_share * 100
+            api_strength = max(0.0, min(1.0, (density - 0.5) / 1.5)) if f.endpoint_total else 0.0
+            add("api-first", "endpoint_density",
+                f"{f.endpoint_total} endpoints over {f.total_files} files "
+                f"({density:.2f}/100 files)",
+                3.0, api_strength, 1.0)
         cli_entries = f.entry_kinds.get("cli", 0)
         add("cli", "cli_entry_points", f"{cli_entries} CLI entry point(s); cli mass ≈ {cm['cli']:.0%}",
             2.5, 1.0 if cli_entries else (1.0 if cm["cli"] > 0.05 else 0.0), max(cm["cli"], 0.2))
         add("daemon", "server_bootstrap",
             f"server/bootstrap entries: {f.entry_kinds.get('server',0)+f.entry_kinds.get('bootstrap',0)}",
             2.0, 1.0 if ("server" in f.entry_kinds or "bootstrap" in f.entry_kinds) else 0.0, 0.5)
+        # `event_no_http` needs the absence of HTTP as a MEASURED fact: firing it
+        # on an unmeasured surface is how an unknown became evidence for `worker`.
+        _no_http_known = f.endpoint_total == 0
         add("worker", "event_no_http",
-            f"event mass ≈ {cm['event']:.0%}, endpoints={f.endpoint_total}",
-            1.5, 1.0 if (cm["event"] > 0.05 and f.endpoint_total == 0) else 0.0, max(cm["event"], 0.1))
+            f"event mass ≈ {cm['event']:.0%}, endpoints="
+            + (str(f.endpoint_total) if f.endpoint_total is not None else "not measured"),
+            1.5, 1.0 if (cm["event"] > 0.05 and _no_http_known) else 0.0, max(cm["event"], 0.1))
         lib_strength = 1.0 if (f.packaging == "jar" and not f.entry_kinds) else 0.3
         add("library", "consumed_as_dependency",
             f"packaging={f.packaging}, entry kinds={list(f.entry_kinds) or 'none'}",
@@ -666,12 +687,18 @@ class ArchetypeClassifier:
         return head if tail else ""
 
     @staticmethod
-    def _endpoint_count(root: Optional[Path]) -> int:
+    def _endpoint_count(root: Optional[Path]) -> "Optional[int]":
+        """The measured endpoint count, or None when it was not measured.
+
+        Both failure modes — no root to read, and an extraction that raised —
+        return None rather than 0, because every consumer below treats 0 as the
+        measured statement "this repository exposes no HTTP surface".
+        """
         if root is None:
-            return 0
+            return None
         try:
             from sourcecode.repository_ir import extract_java_endpoints
             data = extract_java_endpoints(root)
             return int(data.get("total", len(data.get("endpoints", []))))
         except Exception:
-            return 0
+            return None

sourcecode/cache.py

@@ -354,6 +354,7 @@ def status(repo_root: Path) -> dict[str, Any]:
             "cores": 0, "snapshots": 0, "views": 0, "cas_blobs": 0,
             "total_size_bytes": 0, "total_size_mb": 0.0,
             "current_git_head": current_head,
+            "stores": _store_breakdown(repo_root, 0),
             **ris_fields,
         }
     cores = list(cache_d.glob("core-*.json.gz"))
@@ -371,10 +372,57 @@ def status(repo_root: Path) -> dict[str, Any]:
         "total_size_bytes": total_bytes,
         "total_size_mb": round(total_bytes / (1024 * 1024), 2),
         "current_git_head": current_head,
+        # C3-36: `CAS blobs: 0`, `Total size: 0.1 MB` immediately after an 89-second
+        # warm of 3 342 files. Every figure above was true and described one store
+        # of three — the warm's output mostly lands in the shared CIR and the parse
+        # cache, which this command never counted. A status that reports a third of
+        # the state reads as a warm that did nothing.
+        "stores": _store_breakdown(repo_root, total_bytes),
         **ris_fields,
     }
 
 
+def _store_breakdown(repo_root: Path, core_bytes: int) -> "dict[str, Any]":
+    """What a warm actually populated, by store. Best-effort per store: a store
+    that cannot be inspected is reported as unavailable, never as empty."""
+    out: "dict[str, Any]" = {
+        "core": {
+            "cache_dir": str(cache_dir(repo_root)),
+            "bytes": core_bytes,
+            "scope": "this repository",
+            "holds": "core snapshots, rendered views and their CAS blobs",
+        },
+    }
+    try:
+        from sourcecode.context_cache import ContextCache  # noqa: PLC0415
+
+        ctx = ContextCache.for_repo(repo_root).stats()
+        out["shared_cir"] = {
+            "cache_dir": ctx["cache_dir"],
+            "entries": ctx["contexts"],
+            "bytes": ctx["bytes_stored"],
+            "scope": "this repository",
+            "holds": "the shared Canonical IR that explain/impact/posture reuse",
+        }
+    except Exception:
+        out["shared_cir"] = {"available": False}
+    try:
+        from sourcecode import parse_cache as _pc  # noqa: PLC0415
+
+        out["parse"] = {
+            **_pc.store_stats(),
+            "holds": "per-file parses, content-addressed across every repository",
+        }
+    except Exception:
+        out["parse"] = {"available": False}
+    out["note"] = (
+        "`cache warm` populates all of these; the core store alone is a third of "
+        "the answer, and reading it as the whole is how a completed warm looks like "
+        "an empty cache."
+    )
+    return out
+
+
 def clear(repo_root: Path, *, clear_ris: bool = False) -> int:
     """Delete cache files for *repo_root*.  Returns the number of files removed.
 

sourcecode/cache_model.py

@@ -124,16 +124,25 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "`--compact` is what a warm stores by default; `--agent` needs `cache warm --agent`. "
                  "`--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)"),
+                 "--compact 13.3 s cold → 0.3 s warm (cold re-measured on 3.7.0: was 19.3 s, C3-6); "
+                 "--agent --full --env-map --depth 20 34.7 s → 33.9 s (no gain)"),
     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.",
-                 "2.8 s → 2.9 s"),
+    CommandCache("risk", ("cir", "parse"), "shared", False,
+                 "Composes what the audit, impact-chain and the posture already answer, so it "
+                 "pays each of their costs once over the shared CIR a warm builds — one parse "
+                 "for the whole composition, and the reachability query is cached per symbol "
+                 "within the run.",
+                 "not measured on the battery yet — the composition is bounded by the "
+                 "`spring-audit` + `impact-chain` costs listed here, not by new analysis"),
+    CommandCache("endpoints", ("ris", "parse"), "shared", False,
+                 "Recomputes the endpoint surface on every run, over a parse a warm has already "
+                 "paid for. Until 3.7.0 the extractor parsed every file itself instead of reading "
+                 "the shared parse cache, and a warm measurably bought it nothing (C3-6).",
+                 "3.3 s → 1.4 s (re-measured on 3.7.0; was 2.8 s → 2.9 s)"),
     CommandCache("spring-audit", ("ris", "parse"), "shared", False,
                  "Recomputes every run, but over a parse a warm has already paid for.",
                  "8.8 s → 3.7 s"),
@@ -158,8 +167,8 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "1.1 s → 2.3 s (slower)"),
     CommandCache("plan", ("parse",), "shared", False, "", "9.3 s → 3.8 s"),
     CommandCache("compare", ("parse",), "shared", False, ""),
-    CommandCache("delta", (), "none", False, "Analyses two checkouts; neither is the tree the cache describes."),
-    CommandCache("contract-diff", (), "none", False, "Analyses two checkouts."),
+    CommandCache("delta", (), "none", False, "Analyses two states — two checkouts, or two refs materialised into temporary trees; neither is the tree the cache describes."),
+    CommandCache("contract-diff", (), "none", False, "Analyses two states (checkouts or refs); neither is the tree the cache describes."),
     CommandCache("fix-bug", ("task",), "none", True,
                  "Shorthand for `prepare-context fix-bug`; caches its own answer, which a warm never runs."),
     CommandCache("rename-class", (), "none", False, ""),
@@ -183,6 +192,7 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "Reads the RIS a warm rebuilds — that is all it does. Without one it answers "
                  "`no_ris` instead of a snapshot.",
                  "0.2 s either way"),
+    CommandCache("trend", (), "none", False, "Reads stored baseline artifacts from disk; analyses no source, so no cache layer applies. Same command as `baseline trend`."),
     CommandCache("baseline", ("parse",), "shared", False, "`capture`/`diff`/`trend` over architectural metrics.",
                  "capture 8.7 s → 3.6 s"),
     CommandCache("retrieve", ("cir", "parse"), "shared", False,