sourcecode 2.6.10__tar.gz → 3.0.0__tar.gz

{sourcecode-2.6.10 → sourcecode-3.0.0}/CHANGELOG.md

@@ -1,5 +1,176 @@
 # Changelog
 
+## [3.0.0] — 2026-07-28
+
+**One answer per question, a contract around every answer, and a gate that can be
+switched on.** Driven by the strategic re-triage of the 2.7.0 field audit: ten reported
+defects collapsed into four root-cause kernels — scope & identity, evidence admission,
+presentation contract, conditional resolution — and the flagship enforcement feature was
+built on top of the kernels rather than beside them.
+
+### Breaking
+
+- **`pr-impact` defaults to JSON.** It was the only machine-consumable command defaulting
+  to text, while being the one command a pipeline gates on (`--fail-on`, exit codes).
+  `--format text` restores the previous output.
+- **`endpoints --by-controller` keys are controller FQNs, not simple class names.** The
+  function documented FQN grouping and grouped by simple name, so two controllers sharing
+  a name in different packages became one entry: keycloak reported 120 groups for 123
+  controller classes, and three of them listed another package's routes as their own.
+
+### Added
+
+- **Executable contracts.** A repository declares its invariants in `.ask/contracts.yml`
+  — forbidden edges, endpoint-security requirements, and forbidden finding classes from
+  the transaction/security analyzers that already ship — and `ask verify` gates on them.
+  Baseline-relative by default (`--capture-baseline`, `--fail-on new|any|never`): a
+  codebase adopting contracts already violates them, and a gate that fails on all of it
+  is switched off the same afternoon. Exit codes match `verify-edit` (0 pass, 1 blocked,
+  2 unverified). Violation identity excludes source position, so moving code is not a new
+  violation. GitHub Actions workflow and generic CI recipes in
+  [docs/contracts.md](docs/contracts.md); the older `.ask/verify-rules.json` keeps working.
+- **`ask posture --profile` / `--diff`** *(experimental)*. Profile *detection* shipped in 2.7.0 with
+  nothing consuming it. This resolves which conditional beans a profile set actually
+  wires — full `@Profile` semantics including `!`, `&`, `|` and parentheses — and reports
+  what each side of a `--diff` wires that the other does not, including the
+  security-configuration slice ("prod configures the request chain; dev activates no
+  security configuration"). A bean gated by a condition the analyzer does not evaluate is
+  reported as **unresolved**, never assumed active and never assumed absent. On a
+  repository that gates beans on properties most of the answer will be "unresolved" —
+  that is the honest shape of what ships, and why the command is marked experimental.
+  See [docs/posture.md](docs/posture.md).
+- **A response envelope on every JSON payload.** `_meta` carries
+  `envelope_version`, `tool_version`, `command`, `scope` (path, repo root, and the prefix
+  every path in the payload is relative to), `run_id`, and the `inputs` the id is computed
+  over. `run_id` carries no timestamp, so two runs on an unchanged tree are byte-identical
+  and any change to the analyzer, the commit, the working tree or the repository
+  configuration changes it. MCP inherits it.
+- **A published output contract.** `ask schema envelope-v1` prints the JSON Schema the
+  installed version emits, with the compatibility policy stated inside it. A conformance
+  battery validates real command output against it.
+- **`--base` as an alias for `--since`**, and `-f` for `--format` on `review-pr` and
+  `verify-edit`. Additive: every existing spelling still works.
+- **Endpoint admission classes.** The endpoint surface publishes `by_source` and
+  `semantic_model_endpoints`, so the totals from `endpoints`, `spring-audit` and
+  `retrieve endpoint-inventory` reconcile instead of contradicting each other.
+
+### Fixed
+
+- **`--changed-only` reported `file_paths: []` on every run.** It filtered a key the
+  compact view never emits, so the one file-level surface of the changed-only envelope was
+  always empty — next to a non-empty `changed_files` proving otherwise. Both the cold and
+  the warm-cache paths had the same dead filter. The warm path also claimed
+  `cache_source: L2_view` for content that came from the L1 rebuild.
+- **Three commands answered "how many endpoints?" with three numbers.** Broadleaf
+  225/220/220, openmrs 1/0/0, JobRunr 12/0/0. The difference is xml-mapped controllers and
+  router-DSL routes, which the semantic model does not index; `spring-audit` explained it
+  as "multi-prefix routes that collapse", which was measurably not the cause.
+- **`impact` and `impact-chain` scored risk on incomparable scales.** `impact` bounds the
+  score to [0,100); `impact-chain` returned an unbounded total whose caller term was capped
+  at 20, flattening symbols whose caller counts differ by an order of magnitude (keycloak
+  printed 86.0 for two symbols and 1844.0 for a third). Both now use the same knee
+  compression, with the knee on the critical band edge — zero risk-level changes across a
+  16-symbol A/B — and publish `risk_score_raw` for ranking.
+- **`review-pr` announced roles its own evidence gate had rejected.** A repository whose
+  only change was a string helper named `NameMapper.java` reported "1 MyBatis mapper(s) —
+  risk areas: persistence" while the file's own record said `artifact_type: source`. One
+  admission seam now serves the summary, the risk areas, the review-order ranking and the
+  per-file records. Aligning them exposed the gate rejecting true positives too:
+  persistence evidence knew JPA but not MyBatis/JDBC, and controller evidence knew Spring
+  MVC but not JAX-RS — keycloak's entire 676-endpoint surface.
+
+## [2.7.0] — 2026-07-26
+
+**The analyzer reads facts it had been walking past, and stops spending the context budget
+it exists to save.** Driven by an external audit of 2.6.10 and validated by a field battery
+across eleven real repositories plus an A/B against the previous release.
+
+### Added
+
+- **Deployment prefix.** Neither `server.servlet.context-path` nor `spring.mvc.servlet.path`
+  was read anywhere, so an app deployed under `/app-server/api` was inventoried as `/v1/x` —
+  every URL wrong by the same constant, which is what makes the error invisible. Endpoints
+  now carry `effective_path` alongside the mapping-relative `path`, plus a
+  `deployment_prefix` block with per-source provenance. A value carrying a placeholder, or
+  declared only under a profile, is recorded but never imposed on every route.
+- **Two unread profile signals.** Profile names came from one signal — the
+  `application-{profile}.yml` filename convention. Multi-document activation
+  (`spring.config.activate.on-profile`) and `@Profile` on beans are read now, and
+  `profile_conditional_beans` says WHICH beans each profile switches — routinely the
+  security filter chain.
+- **A repo's own authorization gate on the endpoint surface.** Custom-gate detection fed
+  only the `spring-audit` posture block; every other surface reported `policy: none_detected`
+  for each endpoint of a repo whose authorization runs entirely through its own annotation.
+  Such endpoints now carry `policy: custom_gate_inferred` with the annotation as evidence,
+  and the model becomes `custom_annotation_based`. Coverage and specificity alone were
+  measured to be insufficient for a per-endpoint claim — they select caching and
+  documentation annotations — so the claim additionally requires an in-repo `@interface`
+  declaration. Structural, no name matching.
+- **`explain --limit`** (default 50), capping the list sections with the truncation and the
+  exact total stated in `warnings`. `--limit 0` restores the full lists.
+
+### Fixed
+
+- **Cross-file `String` constants were not folded.** `@RequestMapping(Routes.BASE)` resolved
+  to nothing and "nothing" was emitted as the empty path, collapsing every handler of a
+  controller onto `GET /`. A repo-wide constant table is built from the pass the assembler
+  already runs; a name declared twice with different values is dropped, not guessed; what
+  still cannot be resolved is published as `path_resolution: "unresolved"` with the
+  expression, instead of a fabricated `/`. On keycloak this recovers three real endpoints
+  (`AuthZen.EVALUATION_PATH`, `AdapterConstants.K_LOGOUT`) with no route newly unresolved.
+- **Types whose name sits on the line after the keyword** (`public class\n  Name {`) were
+  not extracted.
+- **Hibernate rewrite snippets quoted literal-blanked source**, emitting
+  `em.createNamedQuery("")` — dropping the query name, the one datum that makes the target
+  actionable.
+- **Confidence described the lookup, not the answer.** `retrieve endpoint-security` graded
+  "high" whenever the reference resolved, so an endpoint with no policy and no finding came
+  back maximally confident about nothing. It is high only when evidence attaches, and an
+  explicit `evidence_absent` observation says which case it is.
+- **Archetype counted signal diversity by cardinality**, which one dominant signal satisfies
+  trivially. "High" now also requires the top signal to supply at most 80% of the label's
+  score.
+- **Cycle counts read as one command contradicting another** (`modernize` 15 tangles vs
+  `subsystem-coupling` 0 import cycles). Both are right and measure different graphs; a
+  shared reconciliation note now travels with both numbers.
+- **`auth status` reported `pro: false`** while every Pro command ran under the
+  early-adoption unlock. It now reports the gating in force (`pro_gating`, `pro_effective`,
+  `pro_reason`).
+- **`transaction-entrypoints` counted only `@Transactional` declared ON a controller**, so a
+  repo with 129 boundaries reported 1 entrypoint. Boundaries reachable from a controller
+  within 3 call hops are reported alongside, each labelled with its `entrypoint_basis`.
+  Rows that a signature-free FQN made indistinguishable (overloads) collapse with the count
+  kept as `occurrences`; rows that differ in any attribute stay separate.
+- **`integration-inventory` said nothing four times**: identity keyed on
+  (kind, target-or-client) produced byte-identical rows. Rows collapse with `occurrences`,
+  and a null target carries the reason it is null. On Broadleaf: 9 rows → 4.
+- **`cache warm <subdir>` warmed the whole monorepo**, populating a cache for a different
+  target than `ask <subdir>` reads. It warms exactly the path given and says so when that
+  differs from the git root.
+- **`migrate-check --compact` shipped an empty `headline_blocker`**, forcing the reader back
+  into the full report. It names the weakest applicable axis, or says "none" /
+  "none_applicable". The guard against asserting a framework blocker without version
+  evidence is preserved.
+- **`impact-chain` enumerations were unbounded.** Lists are capped; every total stays exact
+  in `metadata` and `truncated_lists`.
+- **The profile signal was gated on the env-var scan**: a repo that declares profiles but
+  reads no environment variable published nothing about them — the exact shape the profile
+  signals were added for.
+
+### Changed
+
+- **`export --c4` omits the code level (C4 level 4) by default.** It enumerates every symbol
+  per directory and dominated the export: keycloak 18.6 MB → 2.5 MB, Broadleaf 9.7 MB →
+  1.1 MB. The omission is explicit in the payload (`included: false` with the reason and the
+  directory count) and `--c4-code` restores it.
+
+### Notes
+
+- Validated before release: full suite (3,869 passed), eleven repositories × eight commands
+  with no crash and valid JSON throughout, output identical across `PYTHONHASHSEED` values
+  on cold caches, and an A/B against 2.6.10 in which every difference maps to a change listed
+  above.
+
 ## [2.6.10] — 2026-07-25
 
 **Identical runs now produce identical output.** Found by a field battery across twelve

{sourcecode-2.6.10 → sourcecode-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.6.10
+Version: 3.0.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
@@ -232,6 +232,8 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 | Doc | What it covers |
 |-----|----------------|
 | [USER_GUIDE.md](docs/USER_GUIDE.md) | Full command reference, flags, output schema, workflows |
+| [contracts.md](docs/contracts.md) | Declare invariants in `.ask/contracts.yml`, enforce them in the edit loop and in CI |
+| [posture.md](docs/posture.md) | What a profile set actually wires, and what could not be decided (experimental) |
 | [migrate-check.md](docs/migrate-check.md) | Migration rule catalogue (MIG-001..043) + Hibernate stratification |
 | [MODERNIZATION.md](docs/MODERNIZATION.md) | The modernization product: assess → understand → plan → execute |
 | [PRODUCT_TIERS.md](docs/PRODUCT_TIERS.md) | Free vs Pro, pricing model |

{sourcecode-2.6.10 → sourcecode-3.0.0}/README.md

@@ -194,6 +194,8 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 | Doc | What it covers |
 |-----|----------------|
 | [USER_GUIDE.md](docs/USER_GUIDE.md) | Full command reference, flags, output schema, workflows |
+| [contracts.md](docs/contracts.md) | Declare invariants in `.ask/contracts.yml`, enforce them in the edit loop and in CI |
+| [posture.md](docs/posture.md) | What a profile set actually wires, and what could not be decided (experimental) |
 | [migrate-check.md](docs/migrate-check.md) | Migration rule catalogue (MIG-001..043) + Hibernate stratification |
 | [MODERNIZATION.md](docs/MODERNIZATION.md) | The modernization product: assess → understand → plan → execute |
 | [PRODUCT_TIERS.md](docs/PRODUCT_TIERS.md) | Free vs Pro, pricing model |

{sourcecode-2.6.10 → sourcecode-3.0.0}/pyproject.toml

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

{sourcecode-2.6.10 → sourcecode-3.0.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__ = "2.6.10"
+__version__ = "3.0.0"

{sourcecode-2.6.10 → sourcecode-3.0.0}/src/sourcecode/archetype.py

@@ -604,12 +604,23 @@ class ArchetypeClassifier:
             # Gini alone labeling a REST API an "engine") — is a single point of view and
             # must not read as high confidence (field-eval Fase 0).
             distinct_signals = len({e.signal for e in top.evidence if e.contribution > 0})
+            # Diversity by COUNT is satisfiable while one signal carries the
+            # verdict: an audited repo was labelled "engine" at high confidence on
+            # 1.500 of a 1.504 score — a fan-in Gini alone, with the second signal
+            # contributing 0.3%. Counting it as two views is a fiction, so a label
+            # whose top signal supplies almost all of its score cannot be "high"
+            # however many other signals nominally touch it.
+            _contributions = sorted(
+                (e.contribution for e in top.evidence if e.contribution > 0), reverse=True
+            )
+            top_signal_share = (_contributions[0] / top.score) if _contributions else 1.0
             if (
                 confident_enough
                 and rel_margin >= 0.4
                 and mass_backed
                 and graph_backed
                 and distinct_signals >= 2
+                and top_signal_share <= 0.8
             ):
                 confidence = "high"
             elif confident_enough and rel_margin >= 0.25 and mass_backed:

{sourcecode-2.6.10 → sourcecode-3.0.0}/src/sourcecode/cache.py

@@ -75,11 +75,52 @@ SCHEMA_VERSION: str = "2"
 #: Bump to invalidate all L1 core caches (independent of snapshot version).
 CORE_SCHEMA_VERSION: str = "1"
 
-#: Bump when analysis logic or output schema changes — NOT on every package release.
-#: This is the stable part of the L1 core cache key.  Package version bumps (patch,
-#: minor) must NOT bump this value unless the cached data format actually changed.
+#: Manual override for invalidating all L1 core caches. Rarely needed now that the
+#: key carries :func:`analyzer_fingerprint`; kept as an escape hatch for cases the
+#: fingerprint cannot see (a changed dependency, a corrected cache format).
+#: Package version bumps must NOT bump this value.
 ANALYZER_CACHE_VERSION: str = "1"
 
+
+def analyzer_fingerprint() -> str:
+    """Content hash of the analysis code, memoised for the process.
+
+    A cache key built only from the repository state and a hand-maintained version
+    constant cannot notice that the analyzer itself changed. That discipline failed
+    exactly as designed-by-humans disciplines do: five consecutive fixes to analysis
+    logic shipped without anyone bumping ``ANALYZER_CACHE_VERSION``, so an upgraded
+    install kept serving pre-fix results from cache on an unchanged commit — the
+    fixes looked inert until the user cleared the cache by hand.
+
+    Hashing file *content* (not mtime) keeps the key stable across reinstalls and
+    identical checkouts on different machines, so caches stay shareable. Any edit to
+    any module invalidates every entry: over-invalidation costs a re-analysis,
+    under-invalidation reports facts the current code would not produce.
+
+    Falls back to the package version when the source is unreadable (zipimport,
+    frozen builds) — degraded, never wrong-by-silence.
+    """
+    global _ANALYZER_FINGERPRINT
+    if _ANALYZER_FINGERPRINT is not None:
+        return _ANALYZER_FINGERPRINT
+    digest = hashlib.sha256()
+    try:
+        pkg_root = Path(__file__).resolve().parent
+        sources = sorted(pkg_root.rglob("*.py"))
+        if not sources:
+            raise OSError("no analyzer sources found")
+        for src in sources:
+            digest.update(src.relative_to(pkg_root).as_posix().encode("utf-8"))
+            digest.update(src.read_bytes())
+        _ANALYZER_FINGERPRINT = digest.hexdigest()[:12]
+    except Exception:
+        from sourcecode import __version__ as _pkg_version
+        _ANALYZER_FINGERPRINT = f"pkg-{_pkg_version}"
+    return _ANALYZER_FINGERPRINT
+
+
+_ANALYZER_FINGERPRINT: Optional[str] = None
+
 #: Fields eligible for CAS deduplication (applied to top-level JSON dict keys).
 _CAS_FIELDS: frozenset[str] = frozenset([
     "file_paths",

{sourcecode-2.6.10 → sourcecode-3.0.0}/src/sourcecode/caller_metrics.py

@@ -40,3 +40,22 @@ CALLER_METRIC_RECONCILIATION: str = (
     "references or DI-interface resolution). The top-level impact.direct_callers array "
     "may be truncated for output size — use stats.direct_caller_count for the true total."
 )
+
+
+# Cycle / tangle metrics come from TWO different graphs. Both are correct; they
+# answer different questions, and without saying so the pair reads as one command
+# contradicting another (external audit 2026-07-25: modernize reported 15 cyclic
+# tangles while retrieve subsystem-coupling reported import_cycles: 0).
+CYCLE_METRIC_RECONCILIATION: str = (
+    "Cycle metrics differ across commands BY DESIGN. modernize.cross_module_tangles "
+    "is computed over the SYMBOL dependency graph, aggregated to subsystem packages: "
+    "coupling_type=cyclic means two subsystems reference each other (a 2-cycle "
+    "between package groups). The module-graph metrics (import_cycles, cyclic_density, "
+    "scc_mass — used by archetype and the subsystem-coupling retrieval intent) are "
+    "computed over the MODULE/DIRECTORY graph, are bounded for cost (node/edge caps), "
+    "and count strongly-connected components among modules. A repo can therefore "
+    "show mutual package-level coupling (tangles > 0) with no module-level SCC "
+    "(import_cycles = 0): the coupling exists between package groups inside the same "
+    "module. Neither number invalidates the other — read tangles for decomposition "
+    "risk and import_cycles for module-graph topology."
+)