sourcecode 3.6.0__tar.gz → 3.7.0__tar.gz

{sourcecode-3.6.0 → sourcecode-3.7.0}/CHANGELOG.md

@@ -1,5 +1,144 @@
 # Changelog
 
+## [3.7.0] — 2026-08-01
+
+**The exit-code contract and the C3 surface block.** Seven rows closed: the two the field named
+as blocking for CI (exit codes over correct answers), the fourth and fifth appearance of a
+curated list beside real data, and three surfaces that published a promise the payload did not
+keep.
+
+Minor and not patch, because a pipeline can see the difference: `plan` exits 1 where it exited 0
+over a target it never resolved (C3-29), `ask <cmd> | head` exits 0 where a correct run used to
+exit non-zero (C3-28), `--output FILE` carries the whole answer where it was silently trimmed
+(C3-17), `--agent` publishes sections it used to omit (C3-10), and a path-shaped target that was
+refused as ambiguous now resolves (C3-35).
+
+### Fixed
+
+- **A broken output pipe is no longer a failed run** (C3-28, **exit code changes for
+  `ask <cmd> | head`**). `ask repo-ir . --force | head -c 100` returned the correct bytes and
+  exit 1; under `set -e` that stops a pipeline with no error anywhere to explain it — the field
+  named it one of two blockers for CI. One authority now says what a closed stream means
+  (`pipe_contract.py`, installed at the entry point): **a broken output stream changes nothing
+  except where the remaining bytes go.** The descriptor is redirected to the null device on the
+  first broken write and the command finishes and exits on its own terms.
+  - **It does not overwrite the command's own verdict.** `ask impact <ambiguous target> | head`
+    still exits 1, because a consumer that stopped reading has no opinion about whether the
+    analysis resolved its target.
+  - Redirecting before the shutdown flush is what keeps Python from printing
+    `Exception ignored in: <_io.TextIOWrapper …>` and exiting 120 — the same defect wearing a
+    different number.
+  - **The wrapper covers `.buffer`, which is the whole fix**: payloads are written as bytes
+    through `sys.stdout.buffer` at the single emit seam, so a text-only wrapper sits beside the
+    one write this exists for. Measured: with the text wrapper alone, nothing changed.
+  - Only visible above a pipe buffer, which is why it looked intermittent: `endpoints` on a
+    small repository exits 0 either way, `repo-ir` on the same repository did not.
+
+- **An unresolved target has one exit code across every command** (C3-29, **`plan` now exits 1
+  where it exited 0**). `plan <unknown> <repo>` ran to completion, emitted a plan-shaped payload
+  of zeros with `resolution: "not_found"` and exited **0**, while `impact` on the same input
+  exited 1 — so a gate could not tell "nothing to review" from "I never found what you asked
+  about". One authority (`target_admission.py`), four commands rebound (`impact`,
+  `impact-chain`, `plan`, `explain`), and the two other copies of the same literal set
+  (`compare`, `change_plan`) now read it instead of restating it.
+  - **Ambiguity is the same fact, and it was not in the field report.** A target matching
+    several classes returns `ambiguous_path`, empty results and a message asking for the full
+    FQN — the command declined to answer — and `impact` exited **0** on it. Measured on a
+    purpose-built two-class fixture, since no battery repository carries the shape.
+  - Unresolved is **1, not 2**: 2 is reserved by the `verify` family for a run that could not
+    look, and this run looked. Partial and expanded resolutions stay 0 — they are answers about
+    the target the caller named.
+  - `plan`'s `Note:` on stderr is gone with it: the payload already carries the statement, and
+    a successful-looking run should not be narrating on stderr (the `plan` half of C3-34).
+
+- **`--help` reaches inside command groups** (C4-7). `ask cache model` — what a warm buys each
+  command, per layer, including the commands it buys nothing for — appeared in no help text at
+  all: the root catalogue was generated (C4-1/C4-2) but the Cache and Auth blocks under it were
+  three lines somebody typed by hand. The blocks are now built from the registered groups, so a
+  subcommand is listed the moment it is registered; a group too large to name in full (`retrieve`,
+  29 parked intents) publishes its **exact count** and a pointer, never silence. The battery
+  fails if a subcommand of a listed group is missing, or if a collapsed group's count drifts.
+
+- **A successful run says nothing on stderr — measured over the commands, not over a list**
+  (C3-34, the `repo-ir` half). `ask repo-ir . --force` wrote an 82-byte size advisory on a run
+  that exited 0 with the IR on stdout, which PowerShell 5.1 raises as a `NativeCommandError`.
+  The advisory is terminal-gated now, like every other notice, and so is the `--exclude`
+  directory warning and the output-budget trim warning found beside it.
+  - **The list was the defect.** `tests/test_stderr_purity_matrix.py` enumerated 13 commands by
+    hand for the fourth time in three releases; the rows are now **discovered from the CLI**,
+    with every command either driven or carrying a written reason it cannot be. Nine more
+    commands are driven as a result, `cache` subcommands included.
+  - The `repo-ir` row builds a repository large enough for the advisory to actually fire and
+    **asserts it fired**, because a row that never reaches the branch proves nothing.
+
+- **`--output FILE` is no longer trimmed to an agent's context window** (C3-17). The payload
+  budget exists because a context window is finite — it is a constraint on **stdout**. Written
+  to a file it cut the answer anyway, dropped `key_dependencies` entirely, and the note
+  explaining the cut advised `--output`, the flag already in use. Two of six call sites had the
+  rule and four did not (`prepare-context`, `modernize`, the cached-view rebuild, and `impact`
+  in part), so it now lives in one seam (`cli._apply_budget`) and a battery fails if a seventh
+  call site decides for itself.
+  - **The cache had the same defect one layer down**, found while field-checking the seam:
+    `prepare-context` stored the document *after* trimming, so the first stdout run poisoned the
+    cache and every later `--output FILE` hit received a stdout-sized answer. The cache stores
+    the analysis now and the budget is applied per run — measured on alfresco-community-repo:
+    stdout 5 files, cache hit to a file 26.
+  - **`--full` says what it does.** It raises the caps (boundaries and DTO mappers in full,
+    `file_relevance` to 40); it never removed them — under `--agent --full` the file list stayed
+    capped at 40 of 710 while the flag's help promised "remove truncation limits".
+
+- **`--agent` cannot publish less than `--compact`** (C3-10). `--compact` documents
+  `security_surface` "when custom security annotations detected" and closes with "use `--agent`
+  for maximum signal", while `--agent` was assembled from its own hand-written list of sections:
+  measured on BroadleafCommerce it omitted `deployment` and `language_version` outright, and
+  nothing stopped the security surface going the same way. Both views now read one authority
+  (`serializer.JAVA_SPRING_SECTIONS`), and the battery fails on any section `--compact` publishes
+  that `--agent` does not.
+
+- **A path that names one file resolves to that file** (C3-35). Every resolver reduced a
+  path-shaped target to its basename before anything looked at it, so
+  `ask impact src/main/java/com/a/Service.java` answered `ambiguous_path` and offered
+  `com.a.Service` **and** `com.b.Service` — being more specific made the answer worse. A path is
+  matched against the `source_file` each symbol came from, strongest tier first (exact, then
+  module-relative, then parent-relative), and nested types collapse to the type the file is about
+  (on eureka, `DiscoveryClient.java` declares its outer class and five inner ones). One authority
+  in `target_admission`, because three graphs answer target questions — the repo IR, and the CIR
+  that `explain` and `impact-chain` read, both of which used to answer `not_found` for a path.
+  Parity checked on eureka: by path and by name give byte-identical `stats`.
+
+- **`verify-edit` stops paying for a diff it has already proved empty** (C3-32). It computed the
+  change set and then built the HEAD CIR *and* the working CIR unconditionally — on a clean tree
+  the second is the first by construction. Measured on a clean ofbiz-framework: **5.9 s -> 1.7 s**
+  warm. The shortcut is taken only when git actually answered: a failed `git diff` also returns an
+  empty list, and reading that as "nothing changed" would trade dead cost for a false green.
+
+- **`spring-audit --compact`** (C3-31). The one analysis command with no summary mode: 1.99 MB for
+  14 findings in the field, *"a context overflow against an LLM with no filter in between"*. The
+  weight is not the findings — on BroadleafCommerce `security_posture.endpoints` is 113 KB of a
+  178 KB report, and the counts it supports are published beside it. `--compact` caps that list and
+  `findings` to their top 5, ordered by what asks something of the reader (`probably_exposed`
+  first; most severe first), and recomputes nothing: **178 KB -> 25 KB with every count
+  identical**. A flag changes how much is emitted, never the shape (C2-10) — each list stays a list
+  and the totals live in a `*_cap` sibling that exists only when the cap bit.
+
+
+### Documentation
+
+- **Field evaluation #6 of 3.5.0 recorded** (`.planning/FIELD-EVAL-6-2026-08-01.md`, defect
+  ledger, development roadmap). Full 27-command catalogue, repository left byte-identical,
+  scored 8/10. Every reported defect was re-measured on 3.6.0 before it was written down: two
+  do not reproduce (one closed here as C3-15, one by the 3.5.0 admission authority) and the
+  re-measurement found two the evaluation did not report.
+- **New rows**: C1-18 (profile population differs per command, and the narrower one is what an
+  agent reads) · C3-28/C3-29 (**exit codes that lie over correct answers** — a broken pipe
+  exits non-zero on a successful run, `plan` exits 0 on a target it did not resolve while
+  `impact` exits 1) · C3-30 (`verify --init`) · C3-31…C3-34 · C4-7 (`cache model` in no help
+  panel) · P-4 (`baseline` history nobody automated) · CL-7 (non-coverage: no dataflow, no
+  secrets outside Java/YAML, filter order not reconstructed) · CL-8 (`posture --diff` answers
+  conditionally because the profile is decided outside the repository).
+- **The executive roadmap gains what the product does *not* do**, published beside the
+  capabilities, and the evaluation table is current through eval #6.
+
 ## [3.6.0] — 2026-08-01
 
 **The P0 block and the C1/C2 backlog.** Nine rows closed, three closed by measurement alone

{sourcecode-3.6.0 → sourcecode-3.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 3.6.0
+Version: 3.7.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

{sourcecode-3.6.0 → sourcecode-3.7.0}/pyproject.toml

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

{sourcecode-3.6.0 → sourcecode-3.7.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__ = "3.6.0"
+__version__ = "3.7.0"

{sourcecode-3.6.0 → sourcecode-3.7.0}/src/sourcecode/change_plan.py

@@ -88,7 +88,11 @@ def build_change_plan(
     resolution = blast.get("resolution", "not_found")
 
     # Unresolvable target → return a plan-shaped resolution notice (never crash).
-    if resolution in ("not_found", "ambiguous_path") or not blast.get("matched_fqns"):
+    # The set of resolutions that means "never found it" is one fact, and the CLI
+    # reads the same one to decide the exit code (C3-29).
+    from sourcecode.target_admission import is_unresolved
+
+    if is_unresolved(resolution) or not blast.get("matched_fqns"):
         return {
             "schema": CHANGE_PLAN_SCHEMA,
             "target": target,