sourcecode 3.0.0__tar.gz → 3.1.1__tar.gz

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

@@ -1,5 +1,129 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+
+- **`migrate-check --blast-radius` states the regression scope behind each blocker.** The
+  finding list says what must change; a migration plan is built around what has to be
+  re-tested when that change lands. Each affected product file now resolves to the types
+  it declares and runs through the same caller traversal `impact-chain` uses, so the
+  block reports the HTTP endpoints whose call path passes through it, ranked. Measured on
+  BroadleafCommerce: 62.3% of the request surface (137 of 220 endpoints) runs through a
+  file with a finding, and 52 of the 166 affected files carry all of it. Implemented as a
+  rule over the existing IR — no new detector, ~3 ms per affected file on top of an IR
+  build shared with `impact-chain` / `explain` through the context cache.
+  - Reach is regression scope, never build breakage: a `javax→jakarta` finding fails
+    compilation whether or not any endpoint reaches it, and the payload says so.
+  - Unresolved is not zero — a file whose declared types the IR never resolved is listed
+    in `files_unresolved` with reach *unknown*.
+  - A repository the IR resolves no endpoints in (alfresco's webscript framework,
+    openmrs-core) gets `request_surface_share: null` and a note that ranking fell back to
+    caller counts, never a manufactured `0.0`.
+  - Opt-in and additive: without the flag the report is byte-identical to before, and the
+    key is absent rather than `null`.
+
+## [3.1.1] — 2026-07-28
+
+Documentation only; no behaviour changed.
+
+- **`contracts.md` gains an enforcement-maturity section**: which contract kinds have been
+  run against real code and with what result, the one false block found and fixed (a
+  fully-qualified security annotation reading as no guard, 3.1.0), and what is still
+  unproven — the GitHub Actions workflow has never run in a hosted runner. Plus a
+  three-week rollout that starts advisory (`--fail-on never`), because a contract whose
+  first act is blocking a merge gets deleted.
+- **`migrate-check.md` documents the output-size guard** added in 3.1.0: the measured
+  sizes that motivated it, the emitted `OUTPUT_TOO_LARGE` payload, and the four ways past
+  it in the order worth trying.
+- Doc-accuracy tests cover the new claims: the rollout flags exist, every documented
+  contract kind is implemented, and the quoted guard hint is the one the code emits.
+
+## [3.1.0] — 2026-07-28
+
+**Posture answers about requests, not only about beans.** Milestone M4 of the strategic
+roadmap: the conditional-resolution kernel now decides `@ConditionalOnProperty` from the
+repository's own configuration, and the request chain a profile set activates is read down
+to per-endpoint access — with the rule that decided each endpoint cited by file and line.
+Plus the field-defect queue: a fully-qualified annotation was invisible to the whole IR,
+`@Bean` bodies were skipped by every body scan, the custom-gate label disagreed across
+three surfaces, the parse cache served pre-fix parses, and `migrate-check` emitted 900KB
+to stdout.
+
+### Added
+
+- **`posture` resolves `@ConditionalOnProperty`** against the properties the repository's
+  own configuration sets under the same profile set — `application.yml` /
+  `application.properties`, the `application-{profile}` filename convention, and
+  multi-document `spring.config.activate.on-profile`. A profile-activated document
+  outranks an unconditional one. Previously every property condition was reported
+  unresolved, which on a property-driven repository was most of the answer.
+- **`posture --property key=value`** (repeatable) states a deployment value the
+  repository's files do not carry; it outranks every file. Measured on jobrunr's Spring
+  Boot starter: `--property jobrunr.database.type=mem` turns 4 undecided storage
+  auto-configurations into 1 active and 3 inactive, each citing the value that decided it.
+- **`properties` block in the payload** — which configuration files were read, how many
+  keys resolved, which keys nobody could decide, and which values the caller supplied.
+- **`posture` resolves what the active filter chain permits, per endpoint.** The
+  authorization DSL of the chain configuration a profile set activates
+  (`requestMatchers` / `antMatchers` / `mvcMatchers` / `anyRequest` and the access method
+  that decides them) is read in declaration order, and each endpoint is resolved against
+  the first rule that matches it — `endpoints.effective_access`, with the deciding rule's
+  file and line cited for every stated endpoint. HTTP methods on a rule are honoured.
+- **`posture --diff` states the endpoint-level security delta** (`endpoint_access`): the
+  requests two profile sets decide differently, with the count that require no
+  authentication on one side and do on the other. Bean-level movement was the previous
+  answer; this is the one a reviewer acts on.
+
+### Fixed
+
+- **A fully-qualified annotation is the same annotation.** `@a.b.Foo` and `@Foo` are one
+  annotation to the compiler, but the IR stored the qualified token and matched a
+  simple-name vocabulary against it. A controller written as
+  `@org.springframework.web.bind.annotation.RestController` produced **zero endpoints**,
+  and a handler guarded with `@jakarta.annotation.security.RolesAllowed` read as carrying
+  no guard — which an endpoint-security contract then reported as a violation on a
+  guarded endpoint. Found by field-testing `require_endpoint_security` on
+  spring-petclinic. A/B on six battery repos: endpoint and security counts unchanged, so
+  this recovers a blind spot without widening any claim.
+- **The parse cache keys on the analyzer, not only on the file.** It was described as
+  content-addressed and never stale, but the content it addressed was the source file
+  alone: after any change to symbol extraction, an updated install kept serving pre-fix
+  parses for every unchanged file, so a shipped fix read as inert until the cache was
+  cleared by hand — exactly the failure the whole-CIR cache was fixed for. The key now
+  carries `analyzer_fingerprint()`.
+- **`migrate-check` guards its output size**, the way `repo-ir` already did. A default
+  run emitted 909KB on openmrs and 702KB on keycloak (~227K and ~175K tokens) straight to
+  stdout — past every context window it is meant to be pasted into, and only discovered
+  after the wait. Over ~50K estimated tokens it now stops with `OUTPUT_TOO_LARGE` naming
+  the four ways out (`--compact`, `--min-severity high`, `--output`, `--force`), and warns
+  from ~10K. Writing to a file is exempt; `--compact` on openmrs is 23KB.
+- **The custom-gate label agrees across every surface.** A repository whose authorization
+  runs through its own annotation read `custom_annotation_based` from `endpoints`,
+  `unknown` from `spring-audit`, and `evidence_absent` from `retrieve endpoint-security`
+  — same repo, same evidence, three answers. The gate predicate was applied to the
+  `endpoints` surface only; the assembled surface every CIR consumer reads never saw it,
+  so those endpoints arrived carrying no security policy at all. It is now applied once,
+  at the seam all surfaces share, and the inferred gate is named in
+  `security_model_detail.custom_spi_detected`. Measured on the battery: no repository's
+  model changed — the declared-in-repo discriminator still rejects library annotations.
+- **`@Bean` method bodies are scanned like any other body.** `@Bean` classifies a symbol
+  as `bean` rather than `method`, and every body-level scan — literal facts, body facts,
+  guard clauses, intra-class call edges — filtered on `method`. A configuration class's
+  own body was therefore invisible, which is precisely where datasource URLs, directory
+  URIs and client base paths are written. Measured on a clean cache: spring-petclinic
+  recovered 67 → 128 literal atoms across 23 → 36 owners; jobrunr gained 20 body-fact
+  owners. A `@Bean` method is also a call target now (a configuration wiring one bean
+  from another calls it by name).
+- **Conditions are ANDed the way Spring ANDs them.** A bean excluded by its `@Profile` is
+  now `inactive` even when another condition on it is undecided; it was reported
+  unresolved, which hid a bean that provably does not register.
+
+Unresolved stays first-class: a key no configuration source sets, a `${…}` placeholder,
+two documents disagreeing at the same precedence, and arguments the parser does not read
+are each reported unresolved with the key named — `matchIfMissing` is *reported*, never
+applied, because a key absent from the repository is not a key absent from the deployment.
+
 ## [3.0.0] — 2026-07-28
 
 **One answer per question, a contract around every answer, and a gate that can be

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 3.0.0
+Version: 3.1.1
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -139,7 +139,7 @@ The system map: module graph, dependency views, REST surface, per-class summarie
 → [reference](docs/USER_GUIDE.md#core-commands)
 
 ### 4 · Migration & Modernization
-Is this codebase ready to upgrade? Per-dimension readiness (Jakarta / Spring Boot / JDK / Hibernate), located blockers, and an effort estimate.
+Is this codebase ready to upgrade? Per-dimension readiness (Jakarta / Spring Boot / JDK / Hibernate), located blockers, an effort estimate, and — with `--blast-radius` — the endpoints whose call path runs through each blocker, so the re-test plan is ordered by regression scope.
 `ask migrate-check` · `ask modernize`
 → [migrate-check reference](docs/migrate-check.md) · [MODERNIZATION.md](docs/MODERNIZATION.md)
 
@@ -233,7 +233,7 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 |-----|----------------|
 | [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) |
+| [posture.md](docs/posture.md) | What a profile set actually wires — down to which endpoints its filter chain permits — 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-3.0.0 → sourcecode-3.1.1}/README.md

@@ -101,7 +101,7 @@ The system map: module graph, dependency views, REST surface, per-class summarie
 → [reference](docs/USER_GUIDE.md#core-commands)
 
 ### 4 · Migration & Modernization
-Is this codebase ready to upgrade? Per-dimension readiness (Jakarta / Spring Boot / JDK / Hibernate), located blockers, and an effort estimate.
+Is this codebase ready to upgrade? Per-dimension readiness (Jakarta / Spring Boot / JDK / Hibernate), located blockers, an effort estimate, and — with `--blast-radius` — the endpoints whose call path runs through each blocker, so the re-test plan is ordered by regression scope.
 `ask migrate-check` · `ask modernize`
 → [migrate-check reference](docs/migrate-check.md) · [MODERNIZATION.md](docs/MODERNIZATION.md)
 
@@ -195,7 +195,7 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 |-----|----------------|
 | [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) |
+| [posture.md](docs/posture.md) | What a profile set actually wires — down to which endpoints its filter chain permits — 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-3.0.0 → sourcecode-3.1.1}/pyproject.toml

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

{sourcecode-3.0.0 → sourcecode-3.1.1}/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.0.0"
+__version__ = "3.1.1"

sourcecode-3.1.1/src/sourcecode/chain_rules.py

@@ -0,0 +1,289 @@
+"""chain_rules.py — the path rules a security filter chain declares.
+
+`posture` could say *which* chain configuration a profile activates, never what
+that chain permits. "Under `prod` the security configuration is active" is a fact
+about a bean; "under `prod`, `POST /admin/**` requires ROLE_ADMIN and `/health` is
+open to anyone" is a fact about the request, and only the second one is what a
+reviewer is asking.
+
+This is an EXTRACTOR: it reads Java source for the published `HttpSecurity`
+authorization DSL (`requestMatchers` / `antMatchers` / `mvcMatchers` /
+`anyRequest`, followed by the access method that decides them) and returns the
+rules **in declaration order**, because Spring applies the first one that matches
+and any other order would answer a different question.
+
+What it deliberately does not do: evaluate `access(...)` expressions, follow
+matchers built by a helper method, or read matchers passed as constructed
+objects. Those are recorded as rules whose decision is *not evaluated*, so the
+caller reports the endpoint undecided rather than silently open.
+
+VAI: only the published Spring Security DSL vocabulary appears. Path patterns and
+role names are DATA — carried as evidence, never branched on.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+#: Published matcher methods that introduce a rule.
+_MATCHER_METHODS = ("requestMatchers", "antMatchers", "mvcMatchers", "regexMatchers")
+_ANY_REQUEST = "anyRequest"
+
+#: Published access methods → the decision they express. `access`/`hasIpAddress`
+#: are listed so the rule is SEEN; their verdict is that they were not evaluated.
+_ACCESS_DECISIONS = {
+    "permitAll": "permit_all",
+    "denyAll": "deny_all",
+    "authenticated": "authenticated",
+    "fullyAuthenticated": "authenticated",
+    "rememberMe": "authenticated",
+    "anonymous": "anonymous",
+    "hasRole": "role_required",
+    "hasAnyRole": "role_required",
+    "hasAuthority": "role_required",
+    "hasAnyAuthority": "role_required",
+    "access": "not_evaluated",
+    "hasIpAddress": "not_evaluated",
+}
+
+_QUOTED_RE = re.compile(r'"([^"]*)"')
+_HTTP_METHOD_RE = re.compile(r"\bHttpMethod\s*\.\s*([A-Z]+)\b")
+_MATCHER_CALL_RE = re.compile(
+    r"\.\s*(" + "|".join(_MATCHER_METHODS + (_ANY_REQUEST,)) + r")\s*\("
+)
+_ACCESS_CALL_RE = re.compile(
+    r"\s*\.\s*(" + "|".join(_ACCESS_DECISIONS) + r")\s*\("
+)
+
+
+@dataclass(frozen=True)
+class AccessRule:
+    """One `matcher → access` pair, positioned in the order Spring applies it."""
+
+    patterns: "tuple[str, ...]"          # empty → anyRequest (matches everything)
+    methods: "tuple[str, ...]"           # empty → any HTTP method
+    decision: str
+    authorities: "tuple[str, ...]" = ()
+    source_file: str = ""
+    line: int = 0
+    order: int = 0
+    matcher: str = ""                    # the DSL method that declared it
+
+    @property
+    def is_any_request(self) -> bool:
+        """`anyRequest()` — the catch-all, and the only patternless rule that
+        Spring resolves. A matcher call with no readable pattern is a different
+        thing entirely: see `paths_unknown`."""
+        return self.matcher == _ANY_REQUEST
+
+    @property
+    def paths_unknown(self) -> bool:
+        """A matcher whose paths this parser could not read. It may cover any
+        request, so nothing after it can be concluded from the rules alone."""
+        return self.matcher != _ANY_REQUEST and not self.patterns
+
+    def to_dict(self) -> dict:
+        out: dict = {
+            "matcher": self.matcher,
+            "patterns": (
+                ["**"] if self.is_any_request
+                else (list(self.patterns) or ["(paths this parser could not read)"])
+            ),
+            "decision": self.decision,
+            "source_file": self.source_file,
+            "line": self.line,
+        }
+        if self.methods:
+            out["methods"] = list(self.methods)
+        if self.authorities:
+            out["authorities"] = list(self.authorities)
+        return out
+
+
+def _balanced(text: str, open_index: int) -> "tuple[str, int]":
+    """(body, index after ')') for the parenthesis opening at `open_index`.
+
+    String literals are respected so a `)` inside a pattern does not close the
+    call early. Returns ("", -1) when the call is not balanced in this file.
+    """
+    depth = 0
+    i = open_index
+    in_string = False
+    escaped = False
+    while i < len(text):
+        char = text[i]
+        if in_string:
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == '"':
+                in_string = False
+        elif char == '"':
+            in_string = True
+        elif char == "(":
+            depth += 1
+        elif char == ")":
+            depth -= 1
+            if depth == 0:
+                return text[open_index + 1:i], i + 1
+        i += 1
+    return "", -1
+
+
+def rules_from_source(source: str, source_file: str = "") -> "list[AccessRule]":
+    """Every authorization rule in one file, in declaration order."""
+    rules: list[AccessRule] = []
+    position = 0
+    while True:
+        match = _MATCHER_CALL_RE.search(source, position)
+        if match is None:
+            break
+        matcher = match.group(1)
+        body, after = _balanced(source, match.end() - 1)
+        if after < 0:
+            break
+        access = _ACCESS_CALL_RE.match(source, after)
+        if access is None:
+            # A matcher whose access method is not adjacent (chained through a
+            # variable, or a form this parser does not read). Recorded so the
+            # caller knows the path is governed by something it could not read.
+            position = after
+            patterns = tuple(p for p in _QUOTED_RE.findall(body) if p)
+            if matcher != _ANY_REQUEST and not patterns:
+                continue
+            rules.append(AccessRule(
+                patterns=() if matcher == _ANY_REQUEST else patterns,
+                methods=tuple(sorted(set(_HTTP_METHOD_RE.findall(body)))),
+                decision="not_evaluated",
+                source_file=source_file,
+                line=source.count("\n", 0, match.start()) + 1,
+                order=len(rules),
+                matcher=matcher,
+            ))
+            continue
+        method_name = access.group(1)
+        access_body, access_end = _balanced(source, access.end() - 1)
+        position = access_end if access_end > 0 else after
+        patterns = tuple(p for p in _QUOTED_RE.findall(body) if p)
+        if matcher != _ANY_REQUEST and not patterns:
+            # `requestMatchers(new AntPathRequestMatcher(...))` and friends: the
+            # rule exists, its paths are not literals in this call.
+            rules.append(AccessRule(
+                patterns=(), methods=(), decision="not_evaluated",
+                source_file=source_file,
+                line=source.count("\n", 0, match.start()) + 1,
+                order=len(rules), matcher=matcher,
+            ))
+            continue
+        rules.append(AccessRule(
+            patterns=() if matcher == _ANY_REQUEST else patterns,
+            methods=tuple(sorted(set(_HTTP_METHOD_RE.findall(body)))),
+            decision=_ACCESS_DECISIONS[method_name],
+            authorities=tuple(_QUOTED_RE.findall(access_body)),
+            source_file=source_file,
+            line=source.count("\n", 0, match.start()) + 1,
+            order=len(rules),
+            matcher=matcher,
+        ))
+    return rules
+
+
+def extract_chain_rules(
+    root: Path, java_files: "Optional[list[str]]" = None
+) -> "dict[str, list[AccessRule]]":
+    """`{repo-relative file: rules in declaration order}`. Never raises."""
+    root = Path(root)
+    if java_files is None:
+        try:
+            from sourcecode.repository_ir import find_java_files
+
+            java_files = find_java_files(root)
+        except Exception:
+            java_files = []
+    out: dict[str, list[AccessRule]] = {}
+    for rel in java_files or []:
+        try:
+            source = (root / rel).read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        # Cheap pre-check: the DSL always names one of these methods.
+        if not any(name in source for name in _MATCHER_METHODS + (_ANY_REQUEST,)):
+            continue
+        rules = rules_from_source(source, rel)
+        if rules:
+            out[rel] = rules
+    return out
+
+
+def ant_matches(pattern: str, path: str) -> bool:
+    """Spring Ant path semantics: `?` one char, `*` one segment, `**` many.
+
+    A trailing `/**` also matches the base path itself, as Spring's matcher does
+    (`/admin/**` covers `/admin`).
+    """
+    if not pattern or not path:
+        return False
+    if pattern == path:
+        return True
+    regex = _ant_regex(pattern)
+    if regex.match(path):
+        return True
+    if pattern.endswith("/**"):
+        return _ant_regex(pattern[:-3] or "/").match(path) is not None
+    return False
+
+
+_ANT_CACHE: "dict[str, re.Pattern]" = {}
+
+
+def _ant_regex(pattern: str) -> "re.Pattern":
+    cached = _ANT_CACHE.get(pattern)
+    if cached is not None:
+        return cached
+    out: list[str] = ["^"]
+    i = 0
+    while i < len(pattern):
+        char = pattern[i]
+        if pattern.startswith("**", i):
+            out.append(".*")
+            i += 2
+        elif char == "*":
+            out.append("[^/]*")
+            i += 1
+        elif char == "?":
+            out.append("[^/]")
+            i += 1
+        else:
+            out.append(re.escape(char))
+            i += 1
+    out.append("$")
+    compiled = re.compile("".join(out))
+    _ANT_CACHE[pattern] = compiled
+    return compiled
+
+
+def rule_matches(rule: AccessRule, method: str, path: str) -> bool:
+    """Does this rule govern `method path`? Method-less rules cover every method."""
+    if rule.methods and method and method.upper() not in rule.methods:
+        return False
+    if rule.is_any_request:
+        return True
+    return any(ant_matches(pattern, path) for pattern in rule.patterns)
+
+
+def first_matching_rule(
+    rules: "list[AccessRule]", method: str, path: str
+) -> "Optional[AccessRule]":
+    """The rule Spring would apply: the first declared one that matches."""
+    for rule in rules:
+        if rule.paths_unknown:
+            # A rule whose paths could not be read may cover this request, and
+            # everything after it is only reachable if it does not. Stopping here
+            # is what keeps a later `permitAll` from being reported as the answer.
+            return rule
+        if rule_matches(rule, method, path):
+            return rule
+    return None