sourcecode 4.16.0__tar.gz → 4.17.0__tar.gz

{sourcecode-4.16.0 → sourcecode-4.17.0}/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 ## [Unreleased]
 
+## [4.17.0] — 2026-08-10
+
+**The Part 1 queues of field evaluations #20 and #21, and the first three
+capabilities behind them.** Eval #20 is the first audit of a repository this
+product does not model — Keycloak, 8 204 Java files, Quarkus + JAX-RS,
+`spring_detected: false` in all six audited modules, 47 invocations under
+`ASK_READONLY=1` — and it split the product cleanly in two: every structural axis
+worked alone, and the axes that guess produced 86 `high` findings with zero true
+positives. Eval #21 is the seventh measurement of `saint-server`, and its
+contribution is a partition rather than a defect.
+
+**Fixed in this release:**
+
+- **`audit-report` had no deadline at all (C3-89).** It composes the whole of
+  `risk` and did so with no `PhasedRun`, no `stop_when` and no checkpoint: the
+  field measured 2 265 s under `ASK_MAX_ANALYSIS_SECONDS=300`, killed by hand
+  with nothing to show. Bound to the same authority `risk` is bound to, and a cut
+  bundle declares it **before the signature covers it** — including when the cut
+  arrived through `--from-risk`.
+- **`risk` was still not bounded, and now the walks ask (C3-88).** C3-85's naming
+  answered which one held the time on the first run: `reading HTTP-input query
+  sinks`, still on screen at 1,4 min under a 5 s budget. Every walk of the
+  composition now asks the deadline, a skipped walk degrades its axis to
+  `unknown` rather than shrinking a count, and the walk itself runs only when it
+  can change an answer. Measured: jobrunr 15,7 → **4,1 s** with an identical
+  payload; `keycloak/services` over ten minutes → **10,2 s under a 5 s budget**,
+  PARTIAL published.
+- **A gate is one the repository declares (C3-90).** `@NoCache` and
+  `@APIResponses` were being read as Keycloak's authorization gates by coverage
+  and specificity alone. `spring-audit keycloak/services`: **86 findings, all
+  `high`, all false → 0**, with the hedged posture verdict untouched.
+- **And a route is protected by one too (C3-93).** The same wide list decided the
+  per-endpoint verdict, which is the reassurance side and the worse one: **366 of
+  593 endpoints `protected_custom`** on a caching hint. Now **0**.
+- **A bypass claim needs something to bypass (C3-91).** Self-invocation and
+  private/final non-interception are properties of a proxy; where nothing
+  proxies, the two rules are silent, and where something does, the finding names
+  the enforcement model it assumed instead of asserting a framework.
+- **A family says which of its walks the count belongs to (C3-92).** The name was
+  computed, used for `_partial`, and dropped on the way to the screen.
+- **The answer says whether its axes model this repository (CL-19).** Six axes
+  returned the shape of an answer and none added them up; `stack_fit` does, from
+  the flag the payload already carries.
+- **`ask schema <unknown>` lists everything the argument accepts (C4-22).**
+
+**New in this release:**
+
+- **`--config <path>` / `ASK_CONFIG` (F-AX).** The repository's declaration may
+  live outside the repository, so an auditor under `--no-write` can declare data
+  labels and custom security annotations without touching somebody else's tree —
+  the case eval #20 executed, and the one where four commands were unreachable by
+  construction.
+- **The fit statement reaches `posture` and `risk` (F-AY)**, over one
+  `spring_detected` authority that replaced two independent computations.
+- **A truncated answer breaks the consumer that did not ask (F-AV).** On a cut
+  run `total_defects` becomes `total_defects_floor`, and `--ci` exits **75** —
+  neither the pass, nor "found something", nor "refused". Asked for in three
+  consecutive rounds and deliberately kept out of three correction queues,
+  because it changes a published contract.
+
+**Measured and not fixed:** eval #21 reports ten performance regressions on
+4.16.0. The 4.15.0 → 4.16.0 diff is 282 lines and contains **no analysis change**
+— emission, budget binding and payload keys — and an A/B on BroadleafCommerce is
+flat on the four worst-reported commands (`validation` 8,52 → 8,28 s, `endpoints`
+2,09 → 2,24 s, `migrate-check` 7,79 → 7,51 s, `posture --diff` 4,00 → 4,08 s).
+Third consecutive in-house A/B to come back flat; the row (C3-76e) stays open on
+the Windows runner, which is now the highest-value item on the capability list.
+
+
 ## [4.16.0] — 2026-08-10
 
 **The Part 1 queue of field evaluation #19 — three rows, one commit each — and

{sourcecode-4.16.0 → sourcecode-4.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.16.0
+Version: 4.17.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.16.0-blue)
+![Version](https://img.shields.io/badge/version-4.17.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -126,7 +126,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.16.0 — and, on a build that has aged,
+ask version                    # ask 4.17.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.16.0 → sourcecode-4.17.0}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.16.0-blue)
+![Version](https://img.shields.io/badge/version-4.17.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -88,7 +88,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.16.0 — and, on a build that has aged,
+ask version                    # ask 4.17.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.16.0 → sourcecode-4.17.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "4.16.0"
+version = "4.17.0"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-4.16.0 → sourcecode-4.17.0}/src/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.16.0"
+__version__ = "4.17.0"

{sourcecode-4.16.0 → sourcecode-4.17.0}/src/sourcecode/audit_report.py

@@ -12,9 +12,10 @@ import hmac
 import json
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, Callable, Optional
 
 from sourcecode import __version__
+from sourcecode.partial_contract import floor_counts, read_count
 
 AUDIT_REPORT_SCHEMA = "audit-report-v1"
 
@@ -40,14 +41,30 @@ def build_audit_report(
     sign_key: Optional[bytes] = None,
     risk_limit: int = 10,
     risk_payload: Optional[dict[str, Any]] = None,
+    progress: "Optional[Callable[..., Any]]" = None,
+    checkpoint: "Optional[Callable[[str, dict], None]]" = None,
+    partial_status: "Optional[Callable[..., dict]]" = None,
 ) -> dict[str, Any]:
-    """Build the buyer-readable audit bundle from existing command payloads."""
+    """Build the buyer-readable audit bundle from existing command payloads.
+
+    C3-89. This command composes the whole of `risk`, and for four releases it did
+    so with none of the three arguments above — no observer carrying the deadline,
+    no checkpoint, no `partial_status` — while `cli` built no `PhasedRun` for it
+    either. The operator's budget therefore did not exist here at all: the field
+    measured **2 265 s under `ASK_MAX_ANALYSIS_SECONDS=300`** (7,55×), CPU-bound in
+    one worker, with no `partial` and no answer. C3-87 bound the second consumer of
+    that fact and moved the composition of the `_partial` keys into
+    `PhasedRun.status` so the third would get it by construction; this is the third.
+    """
     from sourcecode.posture import build_posture
 
     root = Path(root).resolve()
     if risk_payload is None:
         from sourcecode.risk import build_risk
-        risk = build_risk(root, limit=risk_limit, min_band="low", profiles=profiles)
+        risk = build_risk(
+            root, limit=risk_limit, min_band="low", profiles=profiles,
+            progress=progress, checkpoint=checkpoint, partial_status=partial_status,
+        )
         risk_source = "computed"
     else:
         risk = risk_payload
@@ -65,8 +82,10 @@ def build_audit_report(
         "summary": {
             "risk_model": risk.get("model"),
             "risk_source": risk_source,
-            "total_defects": risk.get("total_defects"),
-            "total_findings": risk.get("total_findings"),
+            # F-AV: read under either spelling, and republished under the one
+            # the bundle's own `summary.partial` already qualifies.
+            "total_defects": read_count(risk, "total_defects"),
+            "total_findings": read_count(risk, "total_findings"),
             "risk_bands": risk.get("by_band", {}),
             "top_risks_shown": len(top_risks),
             "endpoint_access": access.get("summary", {}),
@@ -85,6 +104,28 @@ def build_audit_report(
             "non_coverage": (risk.get("non_coverage") or {}).get("items", []),
         },
     }
+    # C3-89. A bundle whose evidence was cut says so **before** it is signed, and
+    # says it where a reader of the summary sees it — a signature over a truncated
+    # payload that does not declare the truncation is the worst artifact this
+    # product can produce. The keys come from `risk` itself, whichever way it
+    # arrived: a `--from-risk` file that was cut carries its own `_partial`, and
+    # packaging it silently would launder a floor into a verdict (C2-31's rule).
+    if risk.get("partial"):
+        unsigned["summary"]["partial"] = True
+        floor_counts(unsigned["summary"], True)  # F-AV, on the bundle too
+        unsigned["summary"]["counts_are_floor"] = True
+        unsigned["summary"]["counts_basis"] = (
+            "The risk evidence in this bundle was stopped by the analysis budget. "
+            "`total_defects` and `risk_bands` count what the families that ran "
+            "measured, and are a floor over the repository."
+        )
+        _risk_partial = risk.get("_partial")
+        if isinstance(_risk_partial, dict):
+            unsigned["_partial"] = dict(_risk_partial)
+            unsigned["_partial"]["command"] = "audit-report"
+            unsigned["_partial"]["cut_in"] = "risk"
+            if risk_source == "from-risk":
+                unsigned["_partial"]["cut_in"] = "the `--from-risk` payload"
     from sourcecode.provenance import build_evidence_manifest
     unsigned["evidence_manifest"] = build_evidence_manifest(
         unsigned,
@@ -117,7 +158,8 @@ def render_markdown(report: dict[str, Any]) -> str:
         f"- Repository: `{repo}`",
         f"- ASK version: `{(report.get('tool') or {}).get('version', '')}`",
         f"- Profile set: `{profile}`",
-        f"- Total defects: `{summary.get('total_defects')}`",
+        f"- Total defects: `{read_count(summary, 'total_defects')}`"
+        + ("  **(floor — this run was cut short)**" if summary.get("partial") else ""),
         f"- Risk bands: `{summary.get('risk_bands')}`",
         f"- Endpoint access: `{summary.get('endpoint_access')}`",
         "",

{sourcecode-4.16.0 → sourcecode-4.17.0}/src/sourcecode/cli.py

@@ -24,6 +24,8 @@ from sourcecode.output_encoding import json_ensure_ascii as _json_ensure_ascii
 from sourcecode.output_encoding import set_ascii_fallback
 from sourcecode.phased_run import WHY_BUDGET as _WHY_BUDGET
 from sourcecode.phased_run import PhasedRun
+from sourcecode.partial_contract import PARTIAL_EXIT_CODE as _PARTIAL_EXIT
+from sourcecode.partial_contract import read_count as _read_count
 from sourcecode import perf
 from sourcecode.caller_metrics import (
     CALLER_METRIC_RECONCILIATION,
@@ -238,6 +240,16 @@ def _writes_help_block() -> str:
         lines.append(f"  {name.ljust(width)}  {what}")
     lines.append("")
     lines.append("  --no-write (ASK_READONLY=1) refuses all of it and says so on stderr.")
+    # F-AX: the other half of an audit that may not write — where the repository's
+    # own declaration is allowed to live.
+    lines.append(
+        "  --config <path> (ASK_CONFIG) reads the repository's declaration from "
+        "outside it,"
+    )
+    lines.append(
+        "                  so labels and custom security annotations can be "
+        "declared without writing."
+    )
     return "\n".join(lines)
 
 
@@ -746,7 +758,7 @@ def _preprocess_args(args: list[str]) -> list[str]:
 
 def _preprocess_argv() -> None:
     """Apply _preprocess_args to sys.argv in-place (used by main_entry)."""
-    modified = _preprocess_args(_apply_no_write(sys.argv[1:]))
+    modified = _preprocess_args(_apply_external_config(_apply_no_write(sys.argv[1:])))
     sys.argv = sys.argv[:1] + modified
 
 
@@ -2045,6 +2057,57 @@ NO_WRITE_OPTION_HELP = (
 NO_WRITE_FLAG = "--no-write"
 
 
+#: The one help string for `--config` (F-AX).
+CONFIG_OPTION_HELP = (
+    "Read this repository's declaration (data labels, custom security "
+    "annotations) from <path> instead of <repo>/sourcecode.config.json — so an "
+    "auditor can declare without writing into somebody else's tree. Env: "
+    "ASK_CONFIG."
+)
+
+#: Handled before the parser, for `--no-write`'s reason: a declaration honoured
+#: by some commands and not others is worse than none, because the reader cannot
+#: tell which answer used it.
+CONFIG_FLAG = "--config"
+
+
+def _apply_external_config(argv: "list[str]") -> "list[str]":
+    """Consume `--config <path>`, putting the declaration in force. Never raises.
+
+    F-AX. Under `ASK_READONLY=1` the only way to declare anything used to be a
+    file inside the analysed tree, which left `data-exposure`, the `Verified`
+    upgrade for a custom gate, and everything downstream of them unreachable by
+    construction for the exact user this mode exists for — the auditor of
+    somebody else's repository.
+    """
+    if CONFIG_FLAG not in argv:
+        return argv
+    out: "list[str]" = []
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        if token != CONFIG_FLAG:
+            out.append(token)
+            index += 1
+            continue
+        value = argv[index + 1] if index + 1 < len(argv) else ""
+        if not value or value.startswith("-"):
+            print(
+                f"error: {CONFIG_FLAG} needs a path to a declaration file.\n"
+                f"       use: ask {CONFIG_FLAG} ./declarations.json <command> …",
+                file=sys.stderr,
+            )
+            raise SystemExit(2)
+        try:
+            from sourcecode import declarations
+
+            declarations.set_config_path(value)
+        except Exception:
+            pass
+        index += 2
+    return out
+
+
 def _apply_no_write(argv: "list[str]") -> "list[str]":
     """Consume `--no-write` from *argv*, putting the mode in force. Never raises."""
     if NO_WRITE_FLAG not in argv:
@@ -8395,8 +8458,23 @@ def spring_audit_cmd(
     else:
         output = _serialize_dict(data, format)
 
-    _total = combined.summary.get("total_findings", 0)
+    # F-AV: our own readers ask for the count under either spelling — the break
+    # is meant for a consumer that never asked whether the run finished.
+    _total = _read_count(combined.summary, "total_findings") or 0
     _partial_msg = " — PARTIAL, budget exhausted" if _stopped_early else ""
+    # CL-19: the payload carries `stack_fit`, and the person who most needs it is
+    # the one who will read the counts and stop. Said once, on stderr, so piped
+    # output stays byte-identical.
+    if not combined.spring_detected:
+        _notice(
+            "[ask] stack fit: no Spring detected in this scope. The access, "
+            "transaction and "
+            "Boot-readiness axes model Spring semantics and are NOT measuring "
+            "this repository — read their answers as `unknown`, never as `none`. "
+            "The structural axes (call graph, endpoint census, coupling, JDK "
+            "inventory) answer here as they do anywhere. See `stack_fit` in the "
+            "payload."
+        )
     _emit_command_output(
         output, output_path, copy,
         success_msg=(
@@ -8411,8 +8489,10 @@ def spring_audit_cmd(
 
     if ci and _stopped_early:
         # A gate on incomplete evidence must not read as a pass — the same rule
-        # `pr-impact` holds for UNKNOWN.
-        raise typer.Exit(code=1)
+        # `pr-impact` holds for UNKNOWN. F-AV: and it must not read as a *failure*
+        # either, because "the gate found something" and "the gate did not finish"
+        # call for different pipeline decisions. 75 is neither 0, 1 nor 2.
+        raise typer.Exit(code=_PARTIAL_EXIT)
     if ci and combined.findings:
         raise typer.Exit(code=1)
 
@@ -8962,7 +9042,7 @@ def risk_cmd(
         copy,
         success_msg=(
             f"risk written to {output_path} ({data['shown']} of "
-            f"{data['total_defects']} defects composed)"
+            f"{_read_count(data, 'total_defects')} defects composed)"
             # C3-87: the terminal says it too. A reader who never opens the payload
             # must not take a truncated ranking for the repository's risk.
             + (" — PARTIAL, budget exhausted" if data.get("partial") else "")
@@ -9256,26 +9336,58 @@ def audit_report_cmd(
             )
             raise typer.Exit(code=1)
 
-    _prog = Progress()
-    _prog.start("packaging audit evidence")
-    try:
-        data = build_audit_report(
-            path, profiles=_profile_set(profile), sign_key=key_bytes,
-            risk_payload=risk_payload,
-        )
-    finally:
-        _prog.stop()
+    # C3-89: this command composes the whole of `risk`, and it did so with no
+    # deadline of any kind — no `PhasedRun`, no `stop_when` on the observers, no
+    # checkpoint. The field measured 2 265 s under a 300 s budget, CPU-bound in one
+    # worker, killed by hand with nothing to show. `risk` was bound in 4.16.0
+    # (C3-87) and the composition of the `_partial` keys moved into
+    # `PhasedRun.status` precisely so the next consumer would inherit it; this is
+    # that consumer. The phases are `risk`'s own (it is the analysis being run)
+    # plus this command's packaging step.
+    _phase = "packaging audit evidence"
+    _budget = _analysis_budget("audit-report")
+    _run = PhasedRun(
+        command="audit-report",
+        root=path,
+        phases=["audit", "compose", "bundle"],
+        output_path=output_path,
+        budget_seconds=_budget.get("configured_max_seconds"),
+        budget_source=_budget.get("configured_source"),
+        writer=_safe_write_file,
+    )
+    with _expensive_analysis_scope("audit-report", path, _phase):
+        _prog = Progress()
+        _prog.start(_phase)
+        try:
+            data = build_audit_report(
+                path, profiles=_profile_set(profile), sign_key=key_bytes,
+                risk_payload=risk_payload,
+                progress=lambda stage, unit="rule families": _rule_pass_progress(
+                    _prog, stage, unit, stop_when=_run.exhausted
+                ),
+                checkpoint=_run.checkpoint,
+                partial_status=lambda **cut: _run.status(_WHY_BUDGET, **cut),
+            )
+        finally:
+            _prog.stop()
     output = render_markdown(data) if fmt == "markdown" else _serialize_dict(data, fmt)
+    _summary = data.get("summary") if isinstance(data.get("summary"), dict) else {}
     _emit_command_output(
         output,
         output_path,
         copy,
-        success_msg=f"audit report written to {output_path}",
+        success_msg=f"audit report written to {output_path}"
+        # The terminal says it too, for the same reason `risk` does: a signed
+        # bundle that was cut must not be read as the repository's audit.
+        + (" — PARTIAL, budget exhausted" if _summary.get("partial") else ""),
         # A signed artifact cannot be mutated after signing. The report carries
         # tool/version metadata itself, and `signature.payload_sha256` is over
         # the exact JSON payload the user receives.
         stamp_envelope=False,
     )
+    # The complete bundle is written; the checkpoint that stood in for it must not
+    # outlive it (C3-77's invariant, as `risk` applies it).
+    _run.discard_checkpoint()
 
 
 @app.command("migrate-recipe")
@@ -11782,7 +11894,15 @@ def schema_cmd(
     # through the command that already answers "what shape does this release
     # produce?" rather than a command of its own.
     names = available_schemas()
-    if name == "facts-v1":
+    # C4-22: one authority for *what this argument accepts*. The registry names
+    # itself (`registry_version`), so the listing, the dispatch below and the
+    # rejection all read the same value — the field's audit was told
+    # `available: ["envelope-v1"]` by a rejection that knew only half of what the
+    # very next line accepts, and concluded that was the whole published surface.
+    registries = [str(load_registry().get("registry_version") or "")]
+    registries = [r for r in registries if r]
+    accepted = list(names) + registries
+    if name in registries:
         _emit_command_output(
             json.dumps(load_registry(), indent=2, ensure_ascii=False),
             output_path,
@@ -11797,7 +11917,7 @@ def schema_cmd(
             # answers have a single authority. Both are contracts this release
             # carries, listed apart because they are not the same kind of thing.
             json.dumps(
-                {"schemas": names, "registries": ["facts-v1"]},
+                {"schemas": names, "registries": registries},
                 indent=2, ensure_ascii=False,
             ),
             output_path,
@@ -11810,10 +11930,14 @@ def schema_cmd(
     except FileNotFoundError:
         _emit_error_json(
             INVALID_INPUT_CODE,
-            f"No published schema named '{name}'.",
-            available=names,
-            hint="Run `ask schema` to list published schemas.",
-            expected="A published schema name.",
+            f"'{name}' is not a published schema or registry.",
+            available=accepted,
+            hint=(
+                "Run `ask schema` to list them: "
+                + ", ".join(accepted)
+                + "."
+            ),
+            expected="One of: " + " | ".join(accepted),
         )
         raise typer.Exit(code=1)
     # A schema document describes the envelope; stamping one into it would put
@@ -11871,8 +11995,17 @@ def config_cmd(
     _answer.say(f"Telemetry: {'enabled' if is_enabled() else 'disabled'} (off by default; opt-in)")
     _answer.say("")
 
-    _declaration_path = _repo / CONFIG_FILENAME
+    # F-AX: the declaration may sit outside the analysed tree, and *which* file
+    # answered is the first thing this command exists to say.
+    from sourcecode.declarations import config_path as _config_path, is_external
+
+    _declaration_path = _config_path(_repo) or (_repo / CONFIG_FILENAME)
     _answer.say(f"Repository: {_repo}")
+    if is_external():
+        _answer.say(
+            "Declared with --config / ASK_CONFIG — read from outside the "
+            "repository, which is unchanged by this run."
+        )
     if not _declaration_path.is_file():
         _answer.say(f"Declaration: none at {_declaration_path}")
         _answer.say(

{sourcecode-4.16.0 → sourcecode-4.17.0}/src/sourcecode/data_exposure.py

@@ -40,6 +40,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any, Optional
 
 from sourcecode.data_labels import DataLabel, LabelDeclaration, load_labels
+from sourcecode.declarations import source_note as _declaration_source
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
     from sourcecode.canonical_ir import CanonicalRepositoryIR
@@ -139,7 +140,10 @@ def build_data_exposure(
 
     payload: dict = {
         "schema_version": SCHEMA_VERSION,
-        "declaration": decl.to_dict(),
+        # F-AX: which file answered. A declaration read from outside the analysed
+        # tree is the auditor's case, and a payload that does not say so leaves
+        # the reader unable to reproduce the answer.
+        "declaration": {**decl.to_dict(), "source": _declaration_source()},
         "profiles": sorted(profiles) if profiles else None,
     }
 

{sourcecode-4.16.0 → sourcecode-4.17.0}/src/sourcecode/data_labels.py

@@ -39,7 +39,9 @@ from pathlib import Path
 from typing import Optional
 
 #: The same file the custom security annotations are declared in.
-CONFIG_FILENAME = "sourcecode.config.json"
+#: F-AX: the name lives in `declarations`, which also decides *where* it is
+#: looked for. Re-exported so existing importers keep working.
+from sourcecode.declarations import CONFIG_FILENAME  # noqa: E402,F401
 
 #: The key under which labels are declared.
 CONFIG_KEY = "dataLabels"
@@ -108,9 +110,14 @@ def load_labels(root: Optional[Path]) -> LabelDeclaration:
     Never raises. An absent file is not a problem — it is a repository that has
     declared nothing, and the caller says so in the words of the question.
     """
-    if root is None:
+    # F-AX: the path is resolved by one authority, so `--config <external>` is
+    # honoured identically here and in `security_config` — a declaration that
+    # applied to one loader and not the other would be worse than none.
+    from sourcecode.declarations import config_path
+
+    cfg_path = config_path(root)
+    if cfg_path is None:
         return LabelDeclaration()
-    cfg_path = Path(root) / CONFIG_FILENAME
     try:
         if not cfg_path.is_file():
             return LabelDeclaration(config_file=None)

sourcecode-4.17.0/src/sourcecode/declarations.py

@@ -0,0 +1,81 @@
+"""declarations.py — where this repository's declaration lives. One authority.
+
+`sourcecode.config.json` is what a repository declares **about itself**: the data
+labels `data-exposure` refuses to invent, and the custom security annotations
+`spring-audit` and `posture` will not guess. Two loaders read it, and until this
+module each of them resolved the path itself, from its own copy of the filename.
+
+**F-AX.** The path also has to be allowed to sit *outside* the analysed tree. The
+use case is not hypothetical — it is the one field evaluation #20 executed: an
+auditor running over somebody else's repository under `ASK_READONLY=1`, who found
+four commands unreachable **by construction**, because the only way to declare
+anything was to write a file into a tree they had been told not to touch:
+
+    "bajo restricción read-only, cuatro comandos son inalcanzables por
+     construcción. Falta un modo --config-from <ruta externa>."
+
+So the resolution order is: an explicit `--config <path>` (or `ASK_CONFIG`),
+then `<root>/sourcecode.config.json`. The override is a whole-process decision
+like `--no-write` — a declaration that applied to some commands and not others
+would be worse than none, because the reader could not tell which answer used it.
+
+Nothing here reads or parses the file. It answers one question: *which path*.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+#: The name a repository's own declaration has when it lives in the repository.
+CONFIG_FILENAME = "sourcecode.config.json"
+
+#: The environment channel, equal in force to the flag (the `ASK_READONLY`
+#: precedent): a CI job declares once, in the environment, for every command.
+ENV_CONFIG = "ASK_CONFIG"
+
+_OVERRIDE: "Optional[Path]" = None
+
+
+def set_config_path(path: "Optional[Path | str]") -> None:
+    """Point every loader at *path* for the rest of this process. Never raises."""
+    global _OVERRIDE
+    _OVERRIDE = Path(str(path)).expanduser() if path else None
+
+
+def override() -> "Optional[Path]":
+    """The declared external path, from the flag or the environment, or None."""
+    if _OVERRIDE is not None:
+        return _OVERRIDE
+    raw = os.environ.get(ENV_CONFIG, "").strip()
+    return Path(raw).expanduser() if raw else None
+
+
+def config_path(root: "Optional[Path]") -> "Optional[Path]":
+    """Where this run's declaration is, whether or not it exists.
+
+    Returns None only when there is no candidate at all — no override and no
+    root — so a caller can distinguish *"nothing was declared"* from *"the file
+    it would have been in is absent"*, which is the distinction `ask config`
+    prints and `data-exposure` refuses on.
+    """
+    external = override()
+    if external is not None:
+        return external
+    if root is None:
+        return None
+    return Path(root) / CONFIG_FILENAME
+
+
+def is_external() -> bool:
+    """True when the declaration in force comes from outside the analysed tree."""
+    return override() is not None
+
+
+def source_note() -> str:
+    """One clause naming where the declaration came from, for a payload or a line."""
+    external = override()
+    if external is None:
+        return f"<repo>/{CONFIG_FILENAME}"
+    return f"{external} (declared with --config / {ENV_CONFIG})"

{sourcecode-4.16.0 → sourcecode-4.17.0}/src/sourcecode/mcp/orchestrator.py

@@ -794,7 +794,9 @@ def run_migrate_flow_impl(repo_path: str, min_severity: str = "low") -> dict[str
                 headline[key] = report[key]
         _summary = report.get("summary", {})
         if isinstance(_summary, dict):
-            headline["total_findings"] = _summary.get("total_findings")
+            from sourcecode.partial_contract import read_count as _read_count
+
+            headline["total_findings"] = _read_count(_summary, "total_findings")
             headline["affected_files"] = _summary.get("affected_files")
             headline["by_severity"] = _summary.get("by_severity")
             headline["by_target"] = _summary.get("by_target") or _summary.get("by_rule")