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

sourcecode/architectural_baseline.py

@@ -136,6 +136,19 @@ def _fan_in_from_stored(value: Any) -> dict[str, int]:
     return {}
 
 
+def _comparability_env() -> dict:
+    """The environment fields a delta actually depends on (C3-68).
+
+    A baseline is comparable to another when the platform and the tool agree;
+    the CPU model, the core count and a hash of the hostname change none of
+    that. `--record-env` restores the full set for someone benchmarking runs
+    against each other on one machine.
+    """
+    import sys as _sys
+
+    return {"os": _sys.platform, "tool_version": TOOL_VERSION, "recorded": "comparability_only"}
+
+
 def build_baseline(
     cir: "CanonicalRepositoryIR",
     *,
@@ -145,6 +158,7 @@ def build_baseline(
     captured_at: str | None = None,
     env: dict | None = None,
     tool_version: str | None = None,
+    record_env: bool = False,
 ) -> dict:
     """Freeze a CIR's measured architectural metrics into a baseline artifact.
 
@@ -168,6 +182,21 @@ def build_baseline(
             "files": m.file_count,
             "symbols": m.symbol_count,
             "endpoints": m.endpoint_count,
+            # C1-37: this artefact's declared purpose is to be a replayable
+            # fingerprint, and it disagreed with itself — `totals.endpoints`
+            # 3 574 against `len(endpoint_surface)` 3 538 on the field
+            # repository. Neither figure was wrong: `endpoints` counts handler
+            # mappings and `endpoint_surface` is the set of distinct
+            # (METHOD, path) contract pairs, so 36 routes are declared by more
+            # than one handler. Two facts, two names, and the invariant the
+            # battery can actually hold.
+            "endpoint_contract_pairs": len(m.endpoints),
+            "endpoints_unit": (
+                "handler mappings declared in the repository; "
+                "`endpoint_contract_pairs` counts the distinct (METHOD, path) "
+                "pairs those mappings expose, which is what `endpoint_surface` "
+                "lists and what a diff compares"
+            ),
             "dependency_edges": m.dependency_edge_count,
             "import_cycles": len(m.cycles),
         },
@@ -175,7 +204,16 @@ def build_baseline(
         "endpoint_surface": endpoints,
         "fan_in": _fan_in_to_list(m.fan_in),
         "import_cycles": cycles,
-        "env": env if env is not None else collect_env(),
+        # C3-68: this artefact is written inside the work tree, so what it
+        # records is what a `git add -A` publishes. `hostname_hash`, `cpu` and
+        # `cores` describe the developer's machine and affect nothing a delta
+        # compares — from a tool whose own `ask config` says telemetry is off.
+        # The default is now the two fields that DO decide comparability; the
+        # rest is opt-in per capture.
+        "env": (
+            env if env is not None
+            else (collect_env() if record_env else _comparability_env())
+        ),
         "provenance": (
             "architectural_baseline (D5): a measured structural fingerprint of one "
             "CIR, persisted per ref. Metric content is a pure function of the repo "
@@ -319,9 +357,50 @@ def _baseline_filename(baseline: dict) -> str:
     return f"{safe}.json"
 
 
+#: What `.ask/` gets the moment it is created, and why.
+#:
+#: C3-68: `baseline capture` writes into the work tree and nothing protected it.
+#: The field verified `grep -nE "^\.ask|sourcecode" .gitignore` → no matches, so
+#: a `git add -A` commits the artefact — which carries a machine fingerprint and
+#: a 14 587-entry structural inventory of the code. A self-confined
+#: `.ask/.gitignore` is the honest form: it never touches the user's own
+#: `.gitignore`, and it stops applying the moment they delete the directory.
+_ASK_DIR_GITIGNORE = (
+    "# Written by `ask` the first time it created this directory.\n"
+    "# These are local analysis artefacts: a structural inventory of your code\n"
+    "# and, if you asked for it, the machine that measured it. Nothing here\n"
+    "# belongs in a commit. Delete this file to version them deliberately.\n"
+    "*\n"
+)
+
+
+def protect_ask_dir(out_dir: Path) -> None:
+    """Give a freshly created `.ask/` its own `.gitignore` (C3-68).
+
+    Best-effort and never overwriting: a user who edited it decided something,
+    and a tool that re-imposes its default on every run is worse than one that
+    never wrote it.
+    """
+    try:
+        ask_dir = Path(out_dir)
+        while ask_dir.name and ask_dir.name != ".ask":
+            if ask_dir.parent == ask_dir:
+                return
+            ask_dir = ask_dir.parent
+        if ask_dir.name != ".ask":
+            return
+        marker = ask_dir / ".gitignore"
+        if not marker.exists():
+            ask_dir.mkdir(parents=True, exist_ok=True)
+            marker.write_text(_ASK_DIR_GITIGNORE, encoding="utf-8")
+    except OSError:
+        return
+
+
 def write_baseline(baseline: dict, out_dir: Path) -> Path:
     """Write `baseline` as deterministic JSON under `out_dir`; return the file path."""
     out_dir.mkdir(parents=True, exist_ok=True)
+    protect_ask_dir(out_dir)
     path = out_dir / _baseline_filename(baseline)
     path.write_text(
         json.dumps(baseline, sort_keys=True, indent=2) + "\n", encoding="utf-8"

sourcecode/cache_model.py

@@ -202,10 +202,17 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "`refactor`, `fix-bug` and `generate-tests` cache their own answer, but a warm does "
                  "not run them, so their first call pays full price; `delta` and `review-pr` are "
                  "diff-dependent and never cached.",
-                 "onboard 6.5 s → 0.3 s · refactor 7.7 s → 7.7 s (0.3 s on repeat) · "
-                 "generate-tests 12.4 s → 11.0 s (0.3 s on repeat)"),
-    CommandCache("onboard", ("task", "ris"), "answer", True, "Shorthand for `prepare-context onboard`.",
-                 "6.5 s → 0.3 s"),
+                 "onboard 6.5 s → 0.3 s with a warm — but a second run with NO warm recomputes "
+                 "(10.2 s → 9.4 s at 5 486 files; C1-40) · refactor 7.7 s → 7.7 s (0.3 s on "
+                 "repeat) · generate-tests 12.4 s → 11.0 s (0.3 s on repeat)"),
+    CommandCache("onboard", ("task", "ris"), "answer", False,
+                 "Shorthand for `prepare-context onboard`. A warm stores its answer; the command "
+                 "does NOT store its own, so a second run without a warm pays full price. C1-40: "
+                 "the field read `repeat cached` here, ran it twice with no warm, and measured "
+                 "56 s then 23,5 s — this row said it would be a hit.",
+                 "with a warm: 6.5 s → 0.3 s (2 000 files) · 10.2 s → 0.7 s (5 486 files). "
+                 "WITHOUT a warm, a second identical run: 10.2 s → 9.4 s (5 486 files) — "
+                 "no answer hit"),
     CommandCache("explain", ("cir",), "shared", False, "Serves from the shared CIR a warm builds.",
                  "9.8 s → 1.6 s"),
     CommandCache("export", ("parse",), "shared", False, "", "8.8 s → 3.7 s"),

sourcecode/change_plan.py

@@ -93,17 +93,31 @@ def build_change_plan(
     from sourcecode.target_admission import is_unresolved
 
     if is_unresolved(resolution) or not blast.get("matched_fqns"):
+        # C1-39: this is a well-formed `change-plan-v1`, not an error envelope,
+        # so an agent reads its fields — and every cost used to be `0`. Nothing
+        # was measured, and `0` is the answer to a different question. The
+        # product already gets this right elsewhere (`data-exposure` answers
+        # `answered: false` rather than measuring nothing and publishing a
+        # confident zero); this is the same rule, one level up.
+        _not_measured = {
+            "answered": False,
+            "reason": f"target {target!r} did not resolve — nothing was measured",
+        }
         return {
             "schema": CHANGE_PLAN_SCHEMA,
             "target": target,
             "resolution": resolution,
             "message": blast.get("message", f"Target {target!r} not found."),
             "candidates": blast.get("candidates", []),
-            "affected_components": {"count": 0, "components": []},
-            "covering_tests": {"count": 0, "tests": []},
-            "affected_endpoints": {"count": 0, "endpoints": []},
-            "rollback_surface": {"file_count": 0, "files": []},
+            "affected_components": {"count": None, "components": [], **_not_measured},
+            "covering_tests": {"count": None, "tests": [], **_not_measured},
+            "affected_endpoints": {"count": None, "endpoints": [], **_not_measured},
+            "rollback_surface": {"file_count": None, "files": [], **_not_measured},
             "review_checklist": [],
+            "how_to_read": (
+                "Every cost here is `null`, not `0`: the target did not resolve, so "
+                "nothing was measured. A zero would say the change is free."
+            ),
         }
 
     seeds = list(blast["matched_fqns"])
@@ -148,10 +162,21 @@ def build_change_plan(
         checklist.append(
             f"Re-verify the contract of {len(ep_strings)} endpoint(s) in the blast radius."
         )
+    # C1-39, second half: on a repository with no test source root at all — the
+    # field one had 0 test files for 3 337 non-test Java sources — "0 covering
+    # tests" reads as *the change is safe* when it means *there are no tests*.
+    _has_test_root = any(
+        is_test_path(str(m.get("file") or "")) for m in meta.values()
+    )
     if tests:
         checklist.append(
             f"Run {len(tests)} covering test symbol(s) that reach the change."
         )
+    elif not _has_test_root:
+        checklist.append(
+            "Covering tests were not measured: this repository has no test source "
+            "root, so `covering_tests.count` is null rather than 0."
+        )
     else:
         checklist.append(
             "No covering tests reach the change — no existing test exercises this blast radius."
@@ -178,10 +203,20 @@ def build_change_plan(
             "count": len(prod),
             "components": prod[:_LIST_CAP],
         },
-        "covering_tests": {
-            "count": len(tests),
-            "tests": tests[:_LIST_CAP],
-        },
+        "covering_tests": (
+            {
+                "count": len(tests),
+                "tests": tests[:_LIST_CAP],
+                "answered": True,
+            }
+            if _has_test_root else
+            {
+                "count": None,
+                "tests": [],
+                "answered": False,
+                "reason": "no test source root in this repository — nothing to measure",
+            }
+        ),
         "affected_endpoints": {
             "count": len(ep_strings),
             "endpoints": ep_strings[:_LIST_CAP],