sourcecode 2.7.0__tar.gz → 3.0.0__tar.gz

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

@@ -1,5 +1,84 @@
 # 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

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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "2.7.0"
+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.7.0 → 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.7.0"
+__version__ = "3.0.0"

{sourcecode-2.7.0 → 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",