sourcecode 3.0.0__py3-none-any.whl → 3.1.1__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.1"

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),
@@ -6171,6 +6201,65 @@ def posture_cmd(
 # ── Spring Boot Migration Check ───────────────────────────────────────────────
 
 
+def _migration_blast_radius(
+    target: Path,
+    file_list: list[str],
+    report: "object",
+    depth: int,
+) -> dict:
+    """Resolve the regression scope behind the migration findings (--blast-radius).
+
+    Reuses the shared context-cache CIR — the same one `impact-chain`, `explain` and
+    `cache warm` use — so a warmed repository skips the Java parse. Every failure mode
+    degrades to a block that says what could not be computed; it never fabricates reach
+    and never breaks the scan that already succeeded.
+    """
+    from sourcecode.migration_blast import compute_migration_blast, SCHEMA_VERSION
+
+    _depth = max(1, min(int(depth), 8))
+    findings = list(getattr(report, "findings", []) or [])
+
+    def _degraded(reason: str) -> dict:
+        return {
+            "schema_version": SCHEMA_VERSION,
+            "depth": _depth,
+            "status": "unavailable",
+            "endpoints_in_repo": 0,
+            "endpoints_reached": 0,
+            "request_surface_share": None,
+            "files_analyzed": 0,
+            "files_on_request_path": 0,
+            "files_off_request_path": 0,
+            "files_unresolved": [],
+            "files": [],
+            "files_omitted": 0,
+            "notes": [reason],
+        }
+
+    if not file_list:
+        return _degraded(
+            "No Java sources in this repository — there is no call graph to traverse, "
+            "so no regression scope can be attributed."
+        )
+
+    try:
+        from sourcecode import context_cache as _ctxcache
+        from sourcecode.context_graph import ContextGraph
+        from sourcecode.spring_model import SpringSemanticModel
+
+        try:
+            cir, _ = _ctxcache.get_or_build_cir(_resolve_repo_root(target), target, file_list)
+        except Exception:
+            cir = ContextGraph.build(file_list, target).cir
+        model = SpringSemanticModel.build(cir)
+        return compute_migration_blast(cir, model, findings, depth=_depth)
+    except Exception as exc:  # pragma: no cover - defensive
+        return _degraded(
+            f"Blast radius unavailable: {type(exc).__name__} while building the "
+            "repository IR. The migration findings above are unaffected."
+        )
+
+
 @app.command("migrate-check")
 def migrate_check_cmd(
     path: Path = typer.Argument(
@@ -6231,6 +6320,22 @@ 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.",
+    ),
+    blast_radius: bool = typer.Option(
+        False, "--blast-radius",
+        help=(
+            "Rank affected product files by the HTTP endpoints whose call path runs "
+            "through them (regression scope), using the same caller traversal as "
+            "impact-chain. Builds the repository IR — slower than a plain scan."
+        ),
+    ),
+    depth: int = typer.Option(
+        4, "--depth",
+        help="Caller BFS depth for --blast-radius (1-8, default: 4).",
+    ),
 ) -> None:
     """Spring Boot 2→3 migration readiness: detect javax→jakarta namespace blockers.
 
@@ -6332,6 +6437,9 @@ def migrate_check_cmd(
     if _file_limitations:
         report.limitations.extend(_file_limitations)
 
+    if blast_radius:
+        report.blast_radius = _migration_blast_radius(target, file_list, report, depth)
+
     if format == "text":
         output = report.to_text(min_severity=min_severity)
     else:
@@ -6349,6 +6457,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/migrate_check.py

@@ -1402,6 +1402,11 @@ class MigrationReport:
     # exposure map, call-chain detection, upgrade-vs-rewrite verdict). Attached
     # by run_migrate_check; None when not computed.
     hibernate: Optional["HibernateStratification"] = None
+    # Regression scope behind the findings: the endpoints whose call path runs
+    # through each affected file (migration_blast.compute_migration_blast).
+    # Opt-in — attached by the CLI under --blast-radius; None when not computed,
+    # and then absent from the payload so the default report stays byte-identical.
+    blast_radius: Optional[dict] = None
 
     def finalize(self) -> "MigrationReport":
         if not self.generated_at:
@@ -1682,7 +1687,7 @@ class MigrationReport:
         return self
 
     def to_dict(self) -> dict:
-        return {
+        d: dict = {
             "schema_version": self.schema_version,
             "generated_at": self.generated_at,
             "repo_id": self.repo_id,
@@ -1718,6 +1723,11 @@ class MigrationReport:
             "limitations": self.limitations,
             "metadata": self.metadata,
         }
+        # Additive and opt-in: the key appears only when --blast-radius computed it,
+        # so a default run emits exactly the payload it emitted before.
+        if self.blast_radius is not None:
+            d["blast_radius"] = self.blast_radius
+        return d
 
     def to_compact_dict(self, top_n: int = _COMPACT_TOP_N) -> dict:
         """Bounded, decision-grade projection of `to_dict()`.
@@ -1754,6 +1764,11 @@ class MigrationReport:
                 if isinstance(h.get(_col), list):
                     h[_col] = _cap_collection(h[_col], top_n)
             compact["hibernate"] = h
+        blast = full.get("blast_radius")
+        if isinstance(blast, dict) and isinstance(blast.get("files"), list):
+            b = dict(blast)
+            b["files"] = _cap_collection(b["files"], top_n)
+            compact["blast_radius"] = b
         return compact
 
     def to_text(self, min_severity: str = "low") -> str:
@@ -1802,6 +1817,12 @@ class MigrationReport:
             lines.append(self.hibernate.to_text())
             lines.append("")
 
+        if self.blast_radius is not None:
+            from sourcecode.migration_blast import render_blast_text
+
+            lines.append(render_blast_text(self.blast_radius))
+            lines.append("")
+
         if not visible:
             lines.append("No findings at or above selected severity.")
             return "\n".join(lines)