PyPI - sourcecode - Versions diffs - 4.1.0__tar.gz → 4.2.0__tar.gz - Mend

sourcecode 4.1.0tar.gz → 4.2.0tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (206) hide show

{sourcecode-4.1.0 → sourcecode-4.2.0}/CHANGELOG.md RENAMED Viewed

@@ -2,6 +2,159 @@
 ## [Unreleased]
+## [4.2.0] — 2026-08-03
+Minor, not a patch, by this project's own criterion: two published figures move
+and a verdict changes, so a pipeline reading either can change colour.
+`posture --resolve-environments` answers `NOT DECIDED IN THIS REPOSITORY` where
+it answered `artefacts_disagree` on a repository whose build properties nothing
+consumes (C1-22), and `ask risk` publishes defects where it published findings,
+so `total_defects` and `by_band` move (C1-23) — 20 → 15 on BroadleafCommerce.
+`risk` also drops `rule_id` for `rule_ids`: it is in the `experimental` tier,
+whose published promise is exactly that its shape may change in a minor.
+Field evaluation #9 (8/10, same 3 337-file monolith as #6–#8) opened nine rows
+and this release closes seven of them. The two left open are open on purpose:
+`C3-39` needs a Windows runner before it needs a fix, and `P-7` is a pricing
+decision. Every complaint was re-measured against HEAD before a row was written
+— five reproduced, one was half false, one was not reproducible here, and one
+was a capability that already shipped.
+### Added
+- **`ask posture --diff-ref <base>:<head>` and `--since <ref>` — one profile set,
+  two git refs** (roadmap M10.5 item 1). `--diff` holds the tree fixed and moves
+  the profile set; this holds the profile set fixed and moves the tree, which is
+  the question a pull request asks: *does this change what a client can reach
+  without authenticating?* `--since` compares a ref with the working tree,
+  uncommitted edits included. Both refs are read with `git archive`: nothing is
+  written to the repository, no worktree is created and the index is not touched.
+  `docs/posture.md` had declared this as the one requested extension with no
+  feature behind it.
+- **`--fail-on opened|any|never` — the gate half.** Default `never`, so no
+  invocation that worked yesterday changes colour today; `opened` exits 1 when a
+  request a readable rule leaves reachable unauthenticated was not one before.
+  The payload is emitted before the exit code, because a red pipeline with no
+  statement of what opened is a gate nobody keeps. It requires a ref comparison —
+  gating a single run would gate on pre-existing debt, which is `spring-audit --ci`.
+- **`endpoint_request_identity` registered as a fact** (ADR-0008 R11,
+  `sourcecode.canonical_ir:request_identity`). The comparison unit is the request
+  (`METHOD path`), not the endpoint id, which carries the controller FQN and the
+  handler symbol and therefore changes when a handler moves between classes
+  without the URL changing. `contract_diff` re-derived the same identity and now
+  binds to the authority. Path-variable patterns are deliberately **not**
+  normalised: `{id:.*}` and `{id:[^0-9].*}` are different URLs to a caller, and
+  one field repository moved 93 requests with exactly that edit in a single commit.
+### Added
+- **`ask endpoints --compact` — the census instead of the rows** (C2-22, field
+  evaluation #9). Asked how exposed a repository was, the command answered with
+  1.9 MB of JSON for 3 574 endpoints and no summary mode, and the evaluator
+  aggregated it by hand. Every answer now carries an `exposure` block — counts by
+  method, by security policy, by controller and by first path area — and
+  `--compact` returns it without the rows, declaring what it dropped. Two rules
+  it obeys against itself: the census is measured over the population the filters
+  chose and never over what `--limit` left rendered, and every ranked rollup
+  states its own total when it cuts. Measured on BroadleafCommerce: 95 KB → 11 KB,
+  every count unchanged. (The other half of the complaint is recorded as false:
+  `spring-audit` has shipped `--compact`, `--min-severity` and `--scope` for
+  releases.)
+- **NC-007 — the endpoint population is declared** (CL-12, field evaluation #9).
+  `endpoints` projects Spring handler mappings; a servlet declared in `web.xml`
+  or registered as a `ServletRegistrationBean` is reachable over HTTP and is in
+  no part of that model. Six published non-coverage rows are exactly what let a
+  reader treat the list as the whole HTTP surface, and the evaluation lost a
+  monitoring console that way — at a path behind the credential the same run
+  reported as SEC-007. The row is published in the `endpoints` payload and inside
+  `posture.endpoints`, because the reader who counts open requests is reading
+  `posture`. Admission of a servlet surface is deliberately **not** in this
+  change: it is a second population and merging it into `endpoints.total` would
+  move a published count and every ratio keyed on it.
+### Fixed
+- **A reach figure that did not name its scope** (C2-23, field evaluation #9).
+  `risk` reported `endpoints_reached: 1` for a symbol whose class `impact-chain`
+  said reached 8 — both correct, both documented, in two payloads, so reconciling
+  them cost the reader three unit notes. Each row now carries
+  `endpoints_reached_basis`: what the figure is a reach *of* (a defect sits at the
+  symbol that carries the remedy, so a method-level defect walks from the method)
+  and, where that is narrower than a class, the command that answers the wider
+  question. The relationship is asserted by measurement rather than stated in
+  prose.
+- **The remedy registry now follows the status, not only the limitation** (C4-13,
+  field evaluation #9 — the sixth appearance of the C4 shape). The evaluation met
+  `verify`'s `contract_count: 0` → `unverified` → exit 2 under a read-only
+  constraint, concluded the command was unusable and asked for a `--dry-run` that
+  shipped in 3.7.0. The state named one next move and the reader could not take
+  it. `Remedy` gained `also` (the further options an answer needs — a remedy is an
+  invocation, not a flag), the new entry is `ask verify . --init --dry-run`, and
+  the `unverified` reason names both forms. The guard grew with it: every option
+  of an invocation must be accepted by the command it names, and the README check
+  matches a line carrying the command with all of its options, so a front page
+  that lists `--init` and omits `--dry-run` fails the build.
+- **The hub-class guard contradicted the payload beside it** (C2-21, field
+  evaluation #9). It printed *"symbol has > 500 direct callers"* while the same
+  run published 215 of them on openmrs-core's `Context`: the guard trips on
+  caller **reference sites** (method-level keys included) and the payload
+  publishes caller **classes**, so the stated reason was checkably false while
+  the decision was right. `caller_reach.bfs_callers` now returns the population it
+  read, and the warning names it with its unit next to the class count it takes
+  from `caller_metrics.caller_classes` — *"792 caller reference sites … exceed the
+  cap of 500 … The 215 direct caller classes this run publishes stay exact"*.
+- **`ask risk` ranked findings under the label `spring-audit` deduplicates**
+  (C1-23, field evaluation #9). One SEC-004 appeared three times for three call
+  sites in one class and `by_band` was an observation census under a defect
+  label — measured on BroadleafCommerce, 20 rows over 15 distinct `defect_id`
+  beside `spring-audit`'s own 15 defects / 20 findings. `build_risk` now iterates
+  `defect_identity.group_by_defect`, so one row is one thing to fix and both
+  commands report the same count (asserted against each other, not against a
+  literal). Nothing is dropped: `witness_count` and `witness_sites` carry where
+  each observation was seen, `total_findings` publishes the census under its own
+  name, and `rule_id` becomes **`rule_ids`** because one defect can be witnessed
+  by TX-001 and TX-006 at once and a singular field would have to pick one.
+  `severity` is the strongest across the witnesses, and
+  `factors.defect_severity.basis` says so.
+- **A Maven build property was published as a runtime activation** (C1-22, field
+  evaluation #9 — the row it called the most expensive in its report). Two
+  `<properties>` entries setting `spring.profiles.active` made
+  `posture --resolve-environments` answer `artefacts_disagree` — *"different
+  deployments, pick one"* — on a repository where **nothing activates a profile at
+  run time**. The honest verdict, which the command already implements, is
+  `NOT DECIDED IN THIS REPOSITORY`: the default set applies and the permissive
+  profile wins, which is exactly where that audit's most severe finding lived. The
+  command turned a fail-open into a deployment ambiguity, in the scenario it is
+  sold for. A build property is now admitted as an activation only when a resource
+  in the repository consumes it (`@spring.profiles.active@`, or
+  `${spring.profiles.active}` where the build declares its resources filtered).
+  Unconsumed, the value is kept — it is still the profile set a build of it would
+  produce, so the worst case keeps ranking it — and carries the reason it decides
+  nothing, beside a `build_properties_not_consumed` count. The positive control is
+  half the battery: before this, the case where the property genuinely does decide
+  produced the identical verdict, which is how the defect stayed invisible. No
+  movement on the field repositories.
+- **A rule that disappeared was reported as protection gained.** Found by the
+  negative control, not in the field: delete a security configuration and every
+  request it decided goes `permit_all` → undecided, which a two-bucket
+  opened/closed split published as *"2 requests no longer reachable
+  unauthenticated"*. Four buckets now: `opened` and `closed` (attributable to the
+  change), `no_longer_decided` (coverage lost) and `now_open_previously_undecided`
+  (our reading moved, not necessarily the system — it never turns a gate red on
+  its own). Requests undecided on either side are counted in
+  `access_not_decided_either_side`, the delta publishes `direction`, and
+  `gate.reading` states the floor (I-8).
+- **`git_checkout` no longer offers a remedy half its callers do not have.** The
+  not-a-repository message told every caller to "pass two checkouts positionally";
+  `posture` takes none. The message states the fact and each command supplies its
+  own hint.
 ## [4.1.0] — 2026-08-03
 Minor, not a patch, and the criterion is this project's own: a new rule can trip

{sourcecode-4.1.0 → sourcecode-4.2.0}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.1.0
+Version: 4.2.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
@@ -156,6 +156,10 @@ ask posture /path/to/repo --resolve-environments
 # writing it, and populate .ask/contracts.yml from the measurement instead of by hand.
 ask verify /path/to/repo --init
+# Same derivation under a read-only constraint: prints what it would declare and
+# writes nothing — the form an audit of somebody else's repository can run.
+ask verify /path/to/repo --init --dry-run
 # What each defect actually costs once reach, access and write effect are in it:
 # severity × reachability × auth_verdict × write_effect, ordered, every factor traceable.
 ask risk /path/to/repo
@@ -230,6 +234,9 @@ What a profile set **actually wires**: which conditional beans register, which d
 `ask posture` · `ask posture --diff dev:prod` · `ask posture --property k=v`
 → [posture.md](docs/posture.md)
+**`--diff-ref` makes it a gate instead of a report.** `--diff` moves the profile set; `--diff-ref origin/main:HEAD` (or `--since origin/main`, which compares a ref with the working tree) moves the *tree* under one profile set and answers *did this branch open an endpoint*. `--fail-on opened` exits 1 when it did. Both refs are read with `git archive` — nothing is written to the repository. The comparison is keyed on the request (`METHOD path`), counts requests only one side serves, and never reports a rule that disappeared as protection gained.
+`ask posture . --since origin/main --fail-on opened`
 **`--resolve-environments` carries it past the edge of the repository.** Every answer above
 is conditional on a profile set, and which set runs is decided by the deployment. This flag
 reads every artefact in the tree that can set `spring.profiles.active` — Maven/Gradle,
@@ -354,6 +361,13 @@ Two more boundaries worth stating in the same voice:
 | **Applying a migration — nothing here edits source.** | This is the diagnosis layer: it measures what must change and what each change would reach. Rewriting code is an execution problem with an established executor, and duplicating it would mean maintaining a second, worse one. | OpenRewrite. `migrate-check` publishes the recipe each finding carries (`recipes[]`), which is the input that executor takes. |
 | **What the process environment sets at start-up — the profile set, properties and secrets a container is given.** | Nothing in a repository can observe the environment of a process that has not started. A value read from a file here is the default the repository ships, never a guarantee of what runs. | `ask posture --resolve-environments` reads every artefact in the repository that names the profile set, says when none of them decides it, and ranks the admissible sets by what each leaves open. |
+And one about the endpoint surface itself:
+| Not covered | Why | What answers it |
+|---|---|---|
+| **HTTP surface that is not a Spring handler mapping — a servlet declared in `web.xml` or registered as a `ServletRegistrationBean`, a container-level mapping, a static console mounted by a library.** | The endpoint population is projected from the Spring route model: one entry per handler mapping. A servlet is reachable over HTTP and is not in that model, so it is absent from `endpoints`, from the access verdicts derived from it, and from every ratio keyed on the total. Merging a second population into that count would move a published figure and every ratio with it, so the population is declared before it is widened. | Read the deployment descriptors for `<servlet-mapping>` entries and the Spring configuration for `ServletRegistrationBean` beans. Field evaluation #9 found a monitoring console mounted this way, behind a credential `ask spring-audit` did report (SEC-007) at a path nothing here listed. |
 **Positioning.** Until an executor ships, this is the **diagnosis layer**: it measures what
 must change, what each change reaches, and what a gate should block — and it removes none of
 it. Field evaluation scored it 7/10 as a report generator and 5.5/10 as a development tool,

{sourcecode-4.1.0 → sourcecode-4.2.0}/README.md RENAMED Viewed

@@ -118,6 +118,10 @@ ask posture /path/to/repo --resolve-environments
 # writing it, and populate .ask/contracts.yml from the measurement instead of by hand.
 ask verify /path/to/repo --init
+# Same derivation under a read-only constraint: prints what it would declare and
+# writes nothing — the form an audit of somebody else's repository can run.
+ask verify /path/to/repo --init --dry-run
 # What each defect actually costs once reach, access and write effect are in it:
 # severity × reachability × auth_verdict × write_effect, ordered, every factor traceable.
 ask risk /path/to/repo
@@ -192,6 +196,9 @@ What a profile set **actually wires**: which conditional beans register, which d
 `ask posture` · `ask posture --diff dev:prod` · `ask posture --property k=v`
 → [posture.md](docs/posture.md)
+**`--diff-ref` makes it a gate instead of a report.** `--diff` moves the profile set; `--diff-ref origin/main:HEAD` (or `--since origin/main`, which compares a ref with the working tree) moves the *tree* under one profile set and answers *did this branch open an endpoint*. `--fail-on opened` exits 1 when it did. Both refs are read with `git archive` — nothing is written to the repository. The comparison is keyed on the request (`METHOD path`), counts requests only one side serves, and never reports a rule that disappeared as protection gained.
+`ask posture . --since origin/main --fail-on opened`
 **`--resolve-environments` carries it past the edge of the repository.** Every answer above
 is conditional on a profile set, and which set runs is decided by the deployment. This flag
 reads every artefact in the tree that can set `spring.profiles.active` — Maven/Gradle,
@@ -316,6 +323,13 @@ Two more boundaries worth stating in the same voice:
 | **Applying a migration — nothing here edits source.** | This is the diagnosis layer: it measures what must change and what each change would reach. Rewriting code is an execution problem with an established executor, and duplicating it would mean maintaining a second, worse one. | OpenRewrite. `migrate-check` publishes the recipe each finding carries (`recipes[]`), which is the input that executor takes. |
 | **What the process environment sets at start-up — the profile set, properties and secrets a container is given.** | Nothing in a repository can observe the environment of a process that has not started. A value read from a file here is the default the repository ships, never a guarantee of what runs. | `ask posture --resolve-environments` reads every artefact in the repository that names the profile set, says when none of them decides it, and ranks the admissible sets by what each leaves open. |
+And one about the endpoint surface itself:
+| Not covered | Why | What answers it |
+|---|---|---|
+| **HTTP surface that is not a Spring handler mapping — a servlet declared in `web.xml` or registered as a `ServletRegistrationBean`, a container-level mapping, a static console mounted by a library.** | The endpoint population is projected from the Spring route model: one entry per handler mapping. A servlet is reachable over HTTP and is not in that model, so it is absent from `endpoints`, from the access verdicts derived from it, and from every ratio keyed on the total. Merging a second population into that count would move a published figure and every ratio with it, so the population is declared before it is widened. | Read the deployment descriptors for `<servlet-mapping>` entries and the Spring configuration for `ServletRegistrationBean` beans. Field evaluation #9 found a monitoring console mounted this way, behind a credential `ask spring-audit` did report (SEC-007) at a path nothing here listed. |
 **Positioning.** Until an executor ships, this is the **diagnosis layer**: it measures what
 must change, what each change reaches, and what a gate should block — and it removes none of
 it. Field evaluation scored it 7/10 as a report generator and 5.5/10 as a development tool,

{sourcecode-4.1.0 → sourcecode-4.2.0}/pyproject.toml RENAMED Viewed

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

{sourcecode-4.1.0 → sourcecode-4.2.0}/src/sourcecode/__init__.py RENAMED Viewed

@@ -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.1.0"
+__version__ = "4.2.0"

{sourcecode-4.1.0 → sourcecode-4.2.0}/src/sourcecode/caller_reach.py RENAMED Viewed

@@ -127,13 +127,21 @@ def bfs_callers(
     max_depth: int,
     impl_graph: object | None = None,
     method_scoped: bool = False,
-) -> tuple[list[str], list[str], bool, int]:
+) -> tuple[list[str], list[str], bool, int, int]:
     """Walk the reverse graph from *seed_fqns*.
-    Returns ``(direct, indirect, was_truncated, self_excluded)``. ``direct`` is
-    depth 1 — the callers of the seeds themselves; ``indirect`` is depth 2 and
-    beyond, up to *max_depth*. ``was_truncated`` says the hub-class guard capped
-    the walk, which makes the result a floor.
+    Returns ``(direct, indirect, was_truncated, self_excluded, guard_population)``.
+    ``direct`` is depth 1 — the callers of the seeds themselves; ``indirect`` is
+    depth 2 and beyond, up to *max_depth*. ``was_truncated`` says the hub-class
+    guard capped the walk, which makes the result a floor.
+    ``guard_population`` is the number the guard actually read: unique caller
+    **reference sites**, method-level keys included, before anything is
+    normalised to a class. It is returned rather than left implicit because the
+    figure the payload publishes is the class count, and a message that names
+    the cap without naming its own population contradicts the payload beside it —
+    measured on openmrs-core, *"symbol has > 500 direct callers"* printed next to
+    `direct_caller_count: 215` (C2-21).
     A class's own members are members, not external callers, so they are dropped
     and counted (BUG #2 — leaving them in inflated a blast radius ~12×). For a
@@ -170,7 +178,8 @@ def bfs_callers(
             if etype not in SKIP_EDGE_TYPES:
                 unique_direct.update(c for c in fqn_list if not _is_self_reference(c))
-    effective_depth = 1 if len(unique_direct) > CALLER_CAP else max_depth
+    guard_population = len(unique_direct)
+    effective_depth = 1 if guard_population > CALLER_CAP else max_depth
     if effective_depth < max_depth:
         was_truncated = True
@@ -202,4 +211,4 @@ def bfs_callers(
                 else:
                     _add_caller(caller, depth)
-    return direct, indirect, was_truncated, self_excluded
+    return direct, indirect, was_truncated, self_excluded, guard_population

{sourcecode-4.1.0 → sourcecode-4.2.0}/src/sourcecode/canonical_ir.py RENAMED Viewed

@@ -115,6 +115,30 @@ class CanonicalSecurity:
 # CanonicalEndpoint
 # ---------------------------------------------------------------------------
+def request_identity(method: str, path: str) -> str:
+    """The identity of the **request**, not of the handler that serves it.
+    An endpoint `id` identifies a handler: it carries the controller FQN and the
+    handler symbol, so moving a mapping to another class produces a different
+    `id` for the same URL. That is the right identity inside one tree and the
+    wrong one across two — a comparison keyed on it reports every refactored
+    handler as one endpoint removed and another added, and the reader asking
+    "did this change what a caller can reach" has to subtract the noise by hand.
+    Two states of one repository — `contract-diff` between refs, `posture
+    --diff-ref` — compare what a client can call, which is METHOD + path. One
+    authority for it, because two spellings of one identity is how two commands
+    come to disagree about the same endpoint (ADR-0008 R11).
+    Note what this deliberately does *not* do: it does not normalise path
+    variable names or inline regexes. `/{id:.*}` and `/{id:[^0-9].*}` are
+    different URLs to a client, and equating them would hide a real change in
+    the surface — measured on a fleet repository where exactly that edit moved
+    93 requests.
+    """
+    return f"{str(method).upper()} {path}"
 @dataclass
 class CanonicalEndpoint:
     """Canonical endpoint entity — single source of truth for REST endpoint data.
@@ -159,6 +183,11 @@ class CanonicalEndpoint:
         """Deterministic endpoint ID — stable across formatting/body changes."""
         return f"{method}:{path}:{controller_class}:{handler_symbol}"
+    @property
+    def request_key(self) -> str:
+        """This endpoint's request identity — see `request_identity`."""
+        return request_identity(self.method, self.path)
 # ---------------------------------------------------------------------------
 # CanonicalRepositoryIR

sourcecode 4.1.0__tar.gz → 4.2.0__tar.gz

sourcecode 4.1.0tar.gz → 4.2.0tar.gz