sourcecode 3.0.0__py3-none-any.whl → 3.1.0__py3-none-any.whl

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.0"

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

sourcecode/cli.py

@@ -6112,6 +6112,13 @@ def posture_cmd(
         "--diff",
         help="Compare two profile sets: --diff dev:prod (each side comma-separated).",
     ),
+    property_overrides: Optional[list[str]] = typer.Option(
+        None,
+        "--property",
+        "-D",
+        help="State a deployment property: --property jobrunr.dashboard.enabled=true "
+             "(repeatable; outranks the repository's own configuration).",
+    ),
     output_path: Optional[Path] = typer.Option(
         None, "--output", "-o", help="Write the report to a file instead of stdout."
     ),
@@ -6125,10 +6132,11 @@ def posture_cmd(
     which are not, and which conditions this analyzer could not evaluate.
 
     \b
-    EXPERIMENTAL: `@Profile` is resolved completely; every other condition
-    (`@ConditionalOnProperty` and the rest of the `@Conditional*` family) is
-    named and reported unresolved, never decided. On a repository that gates
-    beans on properties, most of the answer will be "unresolved".
+    EXPERIMENTAL: `@Profile` is resolved completely, and `@ConditionalOnProperty`
+    is resolved against the properties this repository's configuration sets under
+    the same profile set (state the rest with --property). Every other condition
+    (the remaining `@Conditional*` family) is named and reported unresolved,
+    never decided.
 
     \b
     Unresolved is a first-class outcome. A bean whose registration depends on a
@@ -6140,12 +6148,34 @@ def posture_cmd(
       ask posture . --profile prod
       ask posture . --profile prod,metrics
       ask posture . --diff dev:prod
+      ask posture . --profile prod --property app.security.enabled=true
     """
     from sourcecode.posture import build_posture, diff_posture
 
     def _parse_set(raw: str) -> set:
         return {p.strip() for p in raw.split(",") if p.strip()}
 
+    overrides: dict = {}
+    for item in property_overrides or []:
+        if "=" not in item:
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                f"--property needs key=value (got {item!r}).",
+                hint="Example: --property jobrunr.dashboard.enabled=true",
+                expected="key=value",
+            )
+            raise typer.Exit(code=1)
+        key, _, value = item.partition("=")
+        if not key.strip():
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                f"--property needs a key before '=' (got {item!r}).",
+                hint="Example: --property jobrunr.dashboard.enabled=true",
+                expected="key=value",
+            )
+            raise typer.Exit(code=1)
+        overrides[key.strip()] = value.strip()
+
     if diff:
         if ":" not in diff:
             _emit_error_json(
@@ -6156,9 +6186,9 @@ def posture_cmd(
             )
             raise typer.Exit(code=1)
         left_raw, right_raw = diff.split(":", 1)
-        data = diff_posture(path, _parse_set(left_raw), _parse_set(right_raw))
+        data = diff_posture(path, _parse_set(left_raw), _parse_set(right_raw), overrides)
     else:
-        data = build_posture(path, _parse_set(profile) if profile else set())
+        data = build_posture(path, _parse_set(profile) if profile else set(), overrides)
 
     _emit_command_output(
         _serialize_dict(data, format),
@@ -6231,6 +6261,10 @@ def migrate_check_cmd(
         None, "--ref",
         help="Label for a --snapshot capture (e.g. a version or sprint tag).",
     ),
+    force: bool = typer.Option(
+        False, "--force",
+        help="Emit to stdout even when the report exceeds the output-size guard.",
+    ),
 ) -> None:
     """Spring Boot 2→3 migration readiness: detect javax→jakarta namespace blockers.
 
@@ -6349,6 +6383,30 @@ def migrate_check_cmd(
         _snap_path = write_snapshot(_snap, _history_dir)
         _snapshot_note = f"; snapshot → {_snap_path}"
 
+    # Output-size guard, same contract as repo-ir. A default migrate-check run on
+    # a large repository emits ~900KB (~227K tokens) — larger than any context
+    # window it is meant to be pasted into, and the caller only learns that after
+    # the wait. Writing to a file is exempt: the size is the point of a file.
+    _mig_tokens_est = len(output.encode("utf-8")) // 4
+    if output_path is None and not force and _mig_tokens_est > 50_000:
+        _emit_error_json(
+            "OUTPUT_TOO_LARGE",
+            f"Estimated output is ~{_mig_tokens_est // 1000}K tokens — too large for "
+            "most LLM context windows.",
+            hint=(
+                "Use --compact (bounded decision summary, same report), "
+                "--min-severity high to drop low-severity findings, "
+                "--output FILE to save to disk, or --force to bypass this guard."
+            ),
+            expected="Output under 50K estimated tokens.",
+        )
+        raise typer.Exit(1)
+    if output_path is None and _mig_tokens_est > 10_000:
+        sys.stderr.write(
+            f"[migrate-check] ~{_mig_tokens_est // 1000}K tokens — "
+            "use --compact or --output FILE for smaller output.\n"
+        )
+
     _total = report.summary.get("total_findings", 0)
     _emit_command_output(
         output, output_path, copy,

sourcecode/parse_cache.py

@@ -9,9 +9,12 @@ This cache stores the output of ``_extract_symbols`` — ``(package, imports, sy
 keyed by a content hash of ``(rel_path, capture_signature, source)``. Properties that
 make it safe:
 
-  * **Content-addressed ⇒ never stale.** The key *is* the content; a changed file yields
-    a different key and misses (re-parses), it never serves an old parse. There is no
-    invalidation to get wrong — unlike a signature-keyed cache.
+  * **Content-addressed ⇒ never stale.** The key *is* the content — the file's bytes AND
+    the analyzer's own source (``analyzer_fingerprint``). A changed file or a changed
+    extractor yields a different key and misses (re-parses); it never serves an old
+    parse. There is no invalidation to get wrong — unlike a signature-keyed cache.
+    (The analyzer half was missing until a field test caught a shipped extractor fix
+    reading as inert: the parse was right in process and stale on disk.)
   * **Correctness never depends on it.** A miss, a corrupt entry, or an unwritable dir all
     degrade to "parse it" — the CIR is byte-identical whether the cache hit or missed
     (proven by the cir_hash-equivalence test, not assumed).
@@ -35,7 +38,10 @@ from sourcecode.context_cache import _atomic_write, _base_dir
 if TYPE_CHECKING:
     from sourcecode.repository_ir import SymbolRecord
 
-_CACHE_SUBDIR = "parse-cache-v1"  # bump when the SymbolRecord shape or extractor changes
+#: The key carries `analyzer_fingerprint()`, so an extractor change invalidates
+#: entries by itself — this constant only needs a bump for something the source
+#: hash cannot see (a changed dependency, a corrected on-disk format).
+_CACHE_SUBDIR = "parse-cache-v1"
 
 
 def is_enabled() -> bool:
@@ -50,12 +56,25 @@ def _cache_root() -> Path:
 
 def file_key(rel_path: str, source: str, capture_sig: str) -> str:
     """Content hash of everything ``_extract_symbols`` depends on. Two identical inputs
-    ⇒ same key (reuse); any change ⇒ different key (miss, re-parse)."""
+    ⇒ same key (reuse); any change ⇒ different key (miss, re-parse).
+
+    "Everything" includes the EXTRACTOR. Keying on the file's bytes alone made this
+    cache content-addressed with respect to the input and blind to the code reading
+    it: after a fix to symbol extraction, an updated install kept serving pre-fix
+    parses for every unchanged file, and the fix looked inert until the cache was
+    cleared by hand. That is the same failure the whole-CIR cache was fixed for; the
+    ``_CACHE_SUBDIR`` comment asking a human to bump a constant is exactly the
+    discipline that fails. The analyzer fingerprint makes it structural instead.
+    """
+    from sourcecode.cache import analyzer_fingerprint
+
     h = hashlib.sha256()
     h.update(rel_path.encode("utf-8", "replace"))
     h.update(b"\x00")
     h.update(capture_sig.encode("utf-8", "replace"))
     h.update(b"\x00")
+    h.update(analyzer_fingerprint().encode("utf-8", "replace"))
+    h.update(b"\x00")
     h.update(source.encode("utf-8", "replace"))
     return h.hexdigest()[:32]