sourcecode 3.5.0__tar.gz → 3.7.0__tar.gz

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

@@ -1,5 +1,310 @@
 # 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
+(C1-17, C2-11, and C2-12 as stated did not reproduce). `migrate-check` stops billing work a
+declared dependency already did, stops billing a Hibernate rewrite to another vendor's provider,
+and stops assuming a single destination — `--target-jdk 11 --keep-boot` takes MIG-001 from 85 to 0
+on openmrs-core.
+
+Two patterns from 3.5.0 repeat, and both are worth carrying forward. **The reported symptom keeps
+being narrower than the defect**: C1-10 was one rule and was also an evidence rule admitting JPA as
+proof of Hibernate; C2-1 was a `why` trail and was also the ranking key underneath it. **And a
+curated list beside real data keeps being the cause** — C2-3's trim schedule named sections the
+payload does not have while the weight sat in two it never mentions, the third appearance of the
+C4-1 shape in two releases.
+
+**Minor, not patch**: blocking counts move (C1-10), reach-derived counts become nullable (C1-13),
+`compare`'s ranking can move (C2-1), `migrate-check.findings` keeps one type across `--compact`
+(C2-10), and two commands that wrote their confirmation to stderr now write it to stdout (C3-18).
+
+### Added
+
+- **`migrate-check --target-jdk N` and `--keep-boot`** (C1-15, P0 gate 2). Asked about a JDK move,
+  the answer was `headline_blocker: boot3_migration` with fix hints sending a developer to migrate
+  481 `javax.persistence` imports they never planned to touch; nothing could say "JDK 11, keep Boot
+  2.7". The route is filtered over the `migration_target` vocabulary every rule already carried.
+  Measured on openmrs-core with `--target-jdk 11 --keep-boot`: **MIG-001 85 → 0**, blocking 114 → 0,
+  headline `hibernate_rewrite` → `none_applicable`. Narrowing is not silencing — `metadata.route`
+  publishes the target and every excluded axis, and a `limitations` entry states what was left out
+  and that it is unresolved, not fixed. **The default is unchanged**: no flags means every axis at
+  once.
+
+- **`spring-audit` findings carry `first_line`** (C2-4), from the `SourceSpan` index the IR already
+  records. `null` where the symbol has no recorded span, never 0.
+
+### Changed
+
+- **`migrate-check` reconciles findings with the build it already read** (C1-10, P0 gate 1,
+  **blocking counts move**). `MIG-021` fired as blocking while `javax.xml.bind:jaxb-api:2.3.1` sat
+  in the same `pom.xml`. A rule now declares the coordinates that satisfy it; a satisfied finding
+  gets `mitigated_by` and `code_context: "dependency_satisfied"`, leaving `blocking_count` exactly
+  as test scope does, and its hint stops saying "add this dependency". `satisfied_by` is empty for
+  every rule whose remedy is a source change.
+  - **The Hibernate axis now needs Hibernate evidence.** It billed 45.6 days to a repository whose
+    declared provider was EclipseLink because a bare `javax.persistence` import counted as proof —
+    that proves JPA, not Hibernate. A declared competing provider refutes the inference, and only
+    the inference: a repository carrying both coordinates keeps direct evidence. An inference from
+    a JPA import alone now reports `medium`, not `high`.
+  - Battery: `blocking_count` identical on all six repositories.
+
+- **A capped blast radius answers `unknown`, not `0`** (C1-13, **reach-derived counts become
+  nullable**). A hub capped at `depth=1` reported `endpoints_affected_count: 0` for a walk that
+  never looked. Under the cap a reach-derived zero becomes `null`, named in
+  `stats.unknown_under_cap`. A **non-zero** count under the cap stays a number — it is a floor — and
+  an **uncapped** run keeps its measured zero.
+
+- **`compare` ranks on measurements, not on rendered rows** (C1-13/C2-1, **ranking may move**).
+  Three of the seven cost fields were `len()` of a display list, so the ordering was computed over
+  however many rows the renderer had decided to show. Capped magnitudes are declared in
+  `cost_floor_fields` beside `cost`, never inside it.
+
+- **`impact.endpoints_affected[]` gains `controller_class` and `handler_symbol`** (C2-12), the names
+  `impact-chain` already uses. Grouping by controller needed a different key per command on payloads
+  one run produces. Original keys kept as aliases.
+
+- **`effort_breakdown.affected_files` is now `blocking_affected_files`** (C1-14, alias kept). It
+  named a different population from `summary.affected_files` — 264 against 265 on openmrs-core — and
+  the shared name was the whole of the contradiction. Both carry a `_basis`.
+
+### Fixed
+
+- **The payload budget cuts where the bytes are** (C2-3). `_TRIM_SCHEDULE` is a hand-written list of
+  key names: on a 1 222-file `review-pr` diff it trimmed 1 733 KB → 1 732 KB against a 97 KB budget,
+  walking to `execution_paths` while every byte sat in `changed_files` and `runtime_changes`, which
+  it does not mention. Once the schedule is exhausted the remaining cut is chosen by measuring which
+  list is largest. Measured on that payload shape: **566 KB → 71 KB**.
+
+- **`ask verify` no longer passes with zero contracts declared** (C3-15, **behaviour change for
+  pipelines**). It returned `pass` + exit 0 on a repository that declared nothing — a green light
+  for having verified nothing. `evaluate_repo` returns before it even builds the CIR when no
+  contracts exist, so no code was read and no contract was checked: the same standing as a
+  repository that could not be analysed, and now reported the same way — **`unverified`, exit 2**,
+  with the reason stated. Exit 2 and not 1 because the published contract reserves 1 for
+  violations found and 2 for a run that could not verify. Asserted under every `--fail-on` choice:
+  `never` suppresses violations from blocking, it does not turn a run that verified nothing into a
+  verified one. This is C3-22 in different clothes — there a typo in `$DIR` made the gate
+  permanently green, here a repository that never adopted contracts did.
+
+- **A command that writes its answer to a file now confirms on stdout, not stderr** (C3-18,
+  **behaviour change for scripts reading stderr**). `repo-ir`, `modernize`, `export` and
+  `cold-start` wrote the "written to" confirmation to stderr while the payload went to the file
+  and stdout stayed empty, so `ask repo-ir -o ir.json > log.txt` captured **nothing** and
+  PowerShell 5.1 raised `NativeCommandError` over a run that succeeded. Measured on
+  spring-petclinic before the fix: stdout 0 bytes, stderr 155. C3-26 set this rule in 3.5.0 for
+  `cache warm`/`cache clear`; these four were missed because the stderr battery listed its
+  commands **by hand**. The `--output` rows are now discovered from the CLI.
+
+- **Usage errors emit the JSON envelope for a pipeline** (C3-4). The interception was patched onto
+  `click.UsageError.show`, which Typer never calls when `rich_markup_mode` is set — it is, for the
+  help panels — so **no usage error had been emitting an envelope at all** and `ask <cmd>
+  --badflag` answered automation with a rich text box. Split by audience: a pipeline gets the
+  envelope, a person at a terminal keeps the `Usage:` line and the pointer to `--help`.
+
+- **A flag no longer changes the type of a key** (C2-10, **breaking for `--compact` consumers**).
+  `migrate-check.findings` was a bare array in full output and a
+  `{total, shown, omitted, items}` object under `--compact` — the same key, two types. A consumer
+  iterating `findings` broke silently on a flag it did not pass: nothing errored, the loop simply
+  ran over the four keys of a summary object instead of over the findings.
+  - `findings` is a **list in both modes**. The counts moved to a `findings_cap` sibling that
+    exists **only when a cap actually bit**, and it carries the I-8 `display_list` statement of
+    what the cut changed and what stayed exact.
+  - **Five collections had it, not one**: top-level `findings`, `hibernate.rewrite_targets`,
+    `hibernate.findings`, `hibernate.critical_call_chains`, `hibernate.golden_sql_hotspots`, and
+    `blast_radius.files`.
+  - **Half of C2-13 falls out of the same fix.** `migrate-check.findings` is now the bare array
+    `spring-audit.findings` always was — one word, one type, one parser, measured across all
+    three payloads. The `schema_version` fragmentation is the half that stays open.
+  - Enforced rather than documented: `tests/test_flag_shape_stability.py` walks both payloads key
+    by key and fails on any type that moves. The same walk covers the root command's `--compact`
+    and `--agent`, which were **measured clean** while fixing this and are locked so they stay
+    clean.
+
+- **A misplaced global flag is told where that flag lives** (C3-4). `ask spring-audit --full`
+  answered "No such option: --full" about a flag the tool does have — it is declared on the root
+  command. The flag is looked up on the root command, so every global flag typed after every
+  subcommand is covered and no flag name is written into the check; a genuinely unknown flag earns
+  no hint, asserted.
+
+- **`repo-ir` states the output cost before it is paid** (C3-18). The advisory ran after the IR was
+  built, serialized and written — the whole bill settled. It now runs off the file count before the
+  build starts, as a **band** (10.8–27.9 KB per Java file) rather than a point: the per-file cost
+  spreads 2.6× across sampled repositories with how densely the code cross-references, and
+  publishing a midpoint as one figure is the C1-12 defect. The band is asserted to bracket what
+  those repositories actually produced.
+
+- **A capped `file_relevance` list says what was cut, measured** (C3-20). The hint published the
+  *budget* as the number of files shown — on spring-petclinic, "Showing top 40/176" beside a list
+  of **25** — fired even when nothing had been cut, and advised `--full` while `--full` was active.
+  Two constraints trim the list (a visibility threshold and a per-category cap of half the budget)
+  and the sentence knew about neither. Now: nothing unless a cap really bit, the figure is what was
+  shown against the population it samples, a flag is named only when it would change the answer,
+  and the I-8 `display_list` block sits beside it.
+
+- **`--no-cache` on a subcommand says what it does** (C3-5). Six commands claimed "always reads
+  fresh source (no snapshot cache)" while `ask cache model` records them reading `ris`, `cir` and
+  `parse`. One string now, stating the reason it is a no-op: since C1-9 every layer keys on the
+  exact tree state and the parse layer is content-addressed, so there is no staleness to bypass.
+  The flag stays accepted so scripts do not break, and is real on `ask --no-cache` (root).
+
+- **`--output <file>` now returns the whole answer, which is what its own note promised**
+  (C2-2, first M8 increment). Measured on `org.broadleafcommerce.common.money.Money`: the file
+  held **30 of 134** caller classes and **50 of 1 302** indirect callers — the same sample stdout
+  gets — while the payload told the reader *"use `--output` for the full list"*.
+  - **The recorded cause was wrong, and fixing what was recorded would not have worked.** The
+    file carried no `_budget_note` at all: the caps were applied at *construction*, inside
+    `compute_blast_radius`, before any output flag was consulted. No option could have returned
+    the full list.
+  - A cap is now a **rendering** parameter (`list_limit`) and never a measurement one — every
+    `stats.*_count` is taken over the full population either way (ADR-0008 R5-R8). `--output`
+    renders unbounded; stdout keeps the sample and names the total; and the note only claims a
+    cap that actually bit, with the I-8 `display_list` effect block beside it.
+  - The output budget is skipped for a file as well. `--agent` and `--compact` already did this;
+    `impact` was the one that did not.
+  - Same rule for `impact-chain`, with one qualification: an **explicit `--limit` still wins**.
+    A default is not a request; a typed flag is (`_flag_was_given`, off Click's parameter source).
+  - The USER_GUIDE now states the rule where a reader meets it, beside the `impact` output.
+
 ## [3.5.0] — 2026-07-31
 
 **M7.7 "Robustness floor" — the axis field evaluation #5 scored 4/10.** Ten pieces, and the

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 3.5.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.5.0 → sourcecode-3.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "3.5.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.5.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.5.0"
+__version__ = "3.7.0"

{sourcecode-3.5.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,