sourcecode 3.7.0__py3-none-any.whl → 3.8.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__ = "3.8.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_model.py

@@ -124,16 +124,18 @@ 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("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 +160,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 +185,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,