sourcecode 2.6.1__py3-none-any.whl → 2.6.2__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__ = "2.6.1"
+__version__ = "2.6.2"

sourcecode/archetype.py

@@ -599,7 +599,18 @@ class ArchetypeClassifier:
             # winner barely above the evidence floor is "undetermined-ish" and must
             # not read as high/medium however lonely it is.
             confident_enough = top.score >= _MIN_CONFIDENT_SCORE
-            if confident_enough and rel_margin >= 0.4 and mass_backed and graph_backed:
+            # Signal diversity: "high" requires the label to be backed by MORE THAN ONE
+            # distinct signal. A lone dominant signal — however strong (e.g. a fan-in
+            # 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})
+            if (
+                confident_enough
+                and rel_margin >= 0.4
+                and mass_backed
+                and graph_backed
+                and distinct_signals >= 2
+            ):
                 confidence = "high"
             elif confident_enough and rel_margin >= 0.25 and mass_backed:
                 confidence = "medium"

sourcecode/cli.py

@@ -160,10 +160,11 @@ def _build_help_text() -> str:
     text = f"""\
 [bold]ASK Engine[/bold]  [dim]· CLI: ask[/dim]   {plan_badge}
 
-Persistent structural context and ultra-fast repeated analysis for AI coding agents.
+Deterministic Java/Spring semantics and reusable structural context for AI coding agents.
 
-Cache warms on first scan; every subsequent call returns pre-built context in milliseconds.
-Cold scan: 2–10s depending on repo size. Warm cache: 0.3–0.6s.
+Cache warms on first scan; later calls reuse pre-built context instead of rescanning.
+Scan and warm time scale with repo size — small repos in seconds, large repos (thousands
+of files) in minutes. Semantic analysis itself is sub-second; repo indexing dominates.
 
 [bold]Primary usage:[/bold]
   ask --compact                  high-signal summary (~2,500–4,000 tokens)
@@ -725,6 +726,31 @@ DOCS_DEPTH_CHOICES = ["module", "symbols", "full"]
 # ── Module-level constants ─────────────────────────────────────────────────────
 _FREE_TIER_NODE_CAP: int = 50  # graph/semantic node cap — applies only to large repos on free tier
 _JAVA_MIN_SCAN_DEPTH: int = 12  # Maven src/main/java/<pkg>/<module>/File depth floor
+_LARGE_REPO_ADVISORY_FILES: int = 3000  # cold-scan advisory threshold (files); honest expectation-setting, not a speed claim
+
+
+def _cold_scan_advisory_message(
+    file_tree: dict,
+    *,
+    file_count: Optional[int] = None,
+) -> Optional[str]:
+    """Return the large-repo cold-scan advisory line, or ``None`` when the repo is
+    below :data:`_LARGE_REPO_ADVISORY_FILES`.
+
+    Honest expectation-setting (field-eval Fase 3, item E): it states the *shape* of
+    the cost — cold analysis scales with repo size, cached afterwards — and never
+    asserts a duration the tool cannot keep. Pure and TTY-agnostic: the caller owns
+    the ``sys.stderr.isatty()`` gate so this never reaches stdout (JSON) or an agent.
+    """
+    if file_count is None:
+        from sourcecode.tree_utils import flatten_file_tree as _flatten_ft
+        file_count = sum(1 for _p in _flatten_ft(file_tree) if Path(_p).suffix)
+    if file_count < _LARGE_REPO_ADVISORY_FILES:
+        return None
+    return (
+        f"[scan] large repository (~{file_count:,} files) — cold analysis scales with "
+        "repo size and may take a while; the result is cached, so later runs are fast."
+    )
 _JVM_STACKS: frozenset[str] = frozenset({"java", "kotlin", "scala", "groovy"})
 _IMPACT_PRIORITY_THRESHOLDS: list[tuple[float, str]] = [
     (0.60, "high"),
@@ -762,7 +788,7 @@ def _print_welcome_plain(tier: str) -> None:
     """Plain-text welcome — fallback when rich is unavailable."""
     lines = ["", f"  ASK Engine {__version__}   ·   {tier}   ·   CLI: ask",
              "  Actionable Software Knowledge Engine", "",
-             "  AI coding-agent context, instant.", "", "  Get started:"]
+             "  Deep Java/Spring semantics for AI coding agents.", "", "  Get started:"]
     for cmd, desc in _WELCOME_CMDS:
         lines.append(f"    {cmd.ljust(34)}{desc}")
     lines.append("")
@@ -812,7 +838,7 @@ def _print_welcome() -> None:
     t.append(_WELCOME_ENGINE, style="bold dim cyan")
     t.append("   Actionable Software Knowledge\n", style="dim")
 
-    t.append("\nAI coding-agent context, instant.\n\n", style="white")
+    t.append("\nDeep Java/Spring semantics for AI coding agents.\n\n", style="white")
 
     for cmd, desc in _WELCOME_CMDS:
         t.append("▸ ", style="cyan")
@@ -1483,23 +1509,60 @@ def main(
             # Step 1: try L1 to obtain the core_hash needed for L2 key
             _l1_result = _cache_mod.read_core(target, _core_key)
 
-            # P1-A: --env-map misses L1 when base (em=False) exists.
-            # Try the base key so env analysis can be injected lazily (<1 s)
-            # instead of triggering a 17 s full rescan.
+            # Additive overlays (--env-map / --git-context) miss L1 because they sit in
+            # the core key, yet neither changes the semantic core — env walks config
+            # files, git walks history; both only ATTACH a block. So when the base
+            # (em=False,gc=False) core exists, reuse it and inject the overlay lazily
+            # (<1 s each) instead of triggering a full rescan. (--changed-only is a
+            # different subsystem and is handled separately.)
+            # Try candidate bases that differ from the current flags only by having
+            # some subset of the requested overlays OFF, fewest flips first — so the
+            # RICHEST already-cached core wins (e.g. with --compact --git-context, the
+            # plain --compact core has em=True,gc=False, so we flip only gc and keep em).
+            # Injecting a flag whose base already has it ON would corrupt the reuse, so
+            # we inject exactly the overlays we flipped to land the hit.
             _l1_needs_env_inject = False
-            if _l1_result is None and env_map:
-                _base_flags = _core_flags_str.replace(",em=True,", ",em=False,")
-                _base_h8 = _hashlib.sha256(_base_flags.encode()).hexdigest()[:8]
+            _l1_needs_git_inject = False
+            if _l1_result is None and (env_map or git_context):
                 _sha_prefix = _git_sha if _git_sha else "nogit"
-                _base_key = f"{_sha_prefix}-{_base_h8}"
-                _base_result = _cache_mod.read_core(target, _base_key)
-                if _base_result is not None:
-                    _l1_result = _base_result
-                    _l1_needs_env_inject = True
+                _flippable = []
+                if git_context:
+                    _flippable.append("gc")   # inject git is cheap + additive
+                if env_map:
+                    _flippable.append("em")
+                # non-empty subsets, ascending size (fewest flips = richest base first)
+                import itertools as _it
+                _subsets = [
+                    s for n in range(1, len(_flippable) + 1)
+                    for s in _it.combinations(_flippable, n)
+                ]
+                for _subset in _subsets:
+                    _bf = _core_flags_str
+                    if "gc" in _subset:
+                        _bf = _bf.replace(",gc=True,", ",gc=False,")
+                    if "em" in _subset:
+                        _bf = _bf.replace(",em=True,", ",em=False,")
+                    _bk = f"{_sha_prefix}-{_hashlib.sha256(_bf.encode()).hexdigest()[:8]}"
+                    _br = _cache_mod.read_core(target, _bk)
+                    if _br is not None:
+                        _l1_result = _br
+                        _l1_needs_git_inject = "gc" in _subset
+                        _l1_needs_env_inject = "em" in _subset
+                        break
 
             if _l1_result is not None:
                 _core_dict_l1, _core_hash = _l1_result
                 _view_key = f"{_core_hash}-{_view_h}"
+                # On the lazy-inject path the core is a REUSED base whose _core_hash is
+                # shared with the base's overlay-free view — suffix the view key with the
+                # injected overlays so the injected body never collides with (or is served
+                # from) the base view. Non-inject runs keep their exact historical key, so
+                # existing cached views stay valid (no cross-version churn).
+                if _l1_needs_git_inject or _l1_needs_env_inject:
+                    _view_key = (
+                        f"{_view_key}-ov:gc{int(_l1_needs_git_inject)}"
+                        f"em{int(_l1_needs_env_inject)}"
+                    )
 
                 # Step 2: try L2 (exact view match).
                 # Skip L2 for --changed-only: the stored view is a previous
@@ -1553,6 +1616,23 @@ def main(
                                         ]
                             except Exception:
                                 pass  # env inject failed — continue without env data
+                        # P-gc: inject git context when a gc=False base L1 was reused.
+                        # GitAnalyzer walks history only — typically <1 s. Reuses the
+                        # serializer's own compact shaping (no duplication/drift).
+                        if _rebuilt is not None and _l1_needs_git_inject and compact:
+                            try:
+                                from types import SimpleNamespace as _NS_gc
+                                from sourcecode.git_analyzer import GitAnalyzer as _GitA_gc
+                                from sourcecode.serializer import _compact_git_context as _cgc
+                                _gc_obj = _GitA_gc().analyze(
+                                    target, depth=git_depth, days=git_days
+                                )
+                                _gc_block = _cgc(_NS_gc(git_context=_gc_obj))
+                                if _gc_block:
+                                    _rebuilt = dict(_rebuilt)
+                                    _rebuilt["git_context"] = _gc_block
+                            except Exception:
+                                pass  # git inject failed — continue without git data
                         if _rebuilt is not None:
                             # Apply redaction
                             if not no_redact:
@@ -1729,6 +1809,17 @@ def main(
     # 2. Filter .env and *.secret entries from file tree (SEC-02, all levels)
     file_tree = filter_sensitive_files(raw_tree, redactor)
     perf.stop("discovery", _perf_discovery)
+
+    # Cold-scan advisory (honest expectation-setting, NOT a speed claim). A cache
+    # hit short-circuits above (line ~1647) before this scan, so reaching here means
+    # a cold run: the full parse+analysis below scales with repo size. On a large
+    # repo, warn once on the TTY so the wait is expected — never on stdout (JSON) and
+    # never for agents/pipes. This does not assert a duration; it states the shape.
+    if sys.stderr.isatty() and not no_cache:
+        _advisory = _cold_scan_advisory_message(file_tree)
+        if _advisory:
+            typer.echo(_advisory, err=True)
+
     _perf_detection = perf.start()
     detector = ProjectDetector(build_default_detectors())
     workspace_analysis = WorkspaceAnalyzer().analyze(target, manifests)
@@ -5295,22 +5386,23 @@ def _render_spring_audit_github_comment(result: "SpringAuditResult", min_severit
         lines.append("")
 
     if not visible:
+        # No findings at/above severity — but a gate-coverage escape set (a separate
+        # signal, not a "finding") may still be worth surfacing before the footer.
         lines.append(f"_No findings at or above `{min_severity}` severity._")
-        return "\n".join(lines)
-
-    lines += [
-        "| Sev | Pattern | File | Symbol | Title |",
-        "|-----|---------|------|--------|-------|",
-    ]
-    for f in sorted(visible, key=lambda x: (SEVERITY_ORDER.get(x.severity, 3), x.source_file)):
-        icon = _ICONS.get(f.severity, "")
-        label = _LABELS.get(f.severity, f.severity.upper())
-        short_file = f.source_file.split("/")[-1] if "/" in f.source_file else f.source_file
-        short_sym = f.symbol.split(".")[-1] if "." in f.symbol else f.symbol
-        title_escaped = f.title.replace("|", "\\|")
-        lines.append(f"| {icon} {label} | `{f.pattern_id}` | `{short_file}` | `{short_sym}` | {title_escaped} |")
+    else:
+        lines += [
+            "| Sev | Pattern | File | Symbol | Title |",
+            "|-----|---------|------|--------|-------|",
+        ]
+        for f in sorted(visible, key=lambda x: (SEVERITY_ORDER.get(x.severity, 3), x.source_file)):
+            icon = _ICONS.get(f.severity, "")
+            label = _LABELS.get(f.severity, f.severity.upper())
+            short_file = f.source_file.split("/")[-1] if "/" in f.source_file else f.source_file
+            short_sym = f.symbol.split(".")[-1] if "." in f.symbol else f.symbol
+            title_escaped = f.title.replace("|", "\\|")
+            lines.append(f"| {icon} {label} | `{f.pattern_id}` | `{short_file}` | `{short_sym}` | {title_escaped} |")
 
-    lines.append("")
+        lines.append("")
 
     if visible:
         lines.append("<details>")
@@ -5327,6 +5419,8 @@ def _render_spring_audit_github_comment(result: "SpringAuditResult", min_severit
             lines.append("")
         lines.append("</details>")
 
+    lines += _render_gate_coverage_section(result)
+
     lines += [
         "",
         f"_Generated by [sourcecode](https://github.com/sourcecode-ai/sourcecode) · "
@@ -5335,6 +5429,57 @@ def _render_spring_audit_github_comment(result: "SpringAuditResult", min_severit
     return "\n".join(lines)
 
 
+_GATE_COVERAGE_RENDER_CAP = 25
+
+
+def _render_gate_coverage_section(result: "SpringAuditResult") -> list[str]:  # type: ignore[name-defined]
+    """Human-readable gate-coverage block: the controller handlers that do NOT carry
+    the auto-detected custom authorization gate — the escape set the JSON already
+    computes, surfaced so a reviewer sees it at a glance. Never says "unsecured": a
+    handler a servlet filter pattern covers is marked "possibly filter-covered", and the
+    unmatched ones are flagged for review, not condemned."""
+    gc = (result.security_posture or {}).get("gate_coverage")
+    if not gc:
+        return []
+    not_covered = gc.get("not_carrying_gate", 0)
+    gates = ", ".join(f"`{g}`" for g in gc.get("gate_annotations", [])) or "the detected gate"
+    total = gc.get("total_controller_handlers", 0)
+    lines: list[str] = ["", "---", ""]
+    if not_covered == 0:
+        lines.append(f"✅ **Gate coverage** — all {total} controller handlers carry {gates}.")
+        return lines
+
+    covered = gc.get("possibly_filter_covered", 0)
+    lines.append(
+        f"🔓 **Gate coverage** — {not_covered} of {total} controller handlers do not carry "
+        f"{gates}."
+    )
+    if gc.get("reconstructed_filter_patterns"):
+        lines.append(
+            f"_{covered} of those match a reconstructed servlet filter pattern "
+            f"(possibly filter-covered); {gc.get('no_matching_filter_pattern', 0)} match none._"
+        )
+    lines += ["", "<details>", "<summary>Handlers without the gate</summary>", ""]
+    lines += [
+        "| Method | Path | Filter pattern | Policy |",
+        "|--------|------|----------------|--------|",
+    ]
+    handlers = gc.get("handlers_without_gate", [])
+    for h in handlers[:_GATE_COVERAGE_RENDER_CAP]:
+        method = (h.get("method") or "").replace("|", "\\|")
+        path = (h.get("path") or "").replace("|", "\\|")
+        fpat = h.get("filter_pattern_match")
+        fcell = f"`{fpat}`" if fpat else "—"
+        policy = (h.get("policy") or "").replace("|", "\\|")
+        lines.append(f"| {method} | `{path}` | {fcell} | {policy} |")
+    if len(handlers) > _GATE_COVERAGE_RENDER_CAP:
+        lines.append(f"| … | _+{len(handlers) - _GATE_COVERAGE_RENDER_CAP} more_ | | |")
+    lines += ["", "</details>", ""]
+    if gc.get("note"):
+        lines.append(f"> {gc['note']}")
+    return lines
+
+
 @app.command("spring-audit")
 def spring_audit_cmd(
     path: Path = typer.Argument(
@@ -5804,7 +5949,14 @@ def impact_chain_cmd(
 
     _prog = Progress()
     _prog.start(f"analyzing impact ({len(file_list)} files)")
-    cir = ContextGraph.build(file_list, target).cir
+    # Reuse the shared context-cache CIR (same entry `cache warm` and `explain` use) so
+    # a warmed repo skips the expensive Java parse. Best-effort — any fault falls back to
+    # a fresh build, exactly as explain does, so impact-chain never breaks.
+    from sourcecode import context_cache as _ctxcache
+    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)
 
     if query_type == "events":
@@ -8215,6 +8367,22 @@ def cache_clear_cmd(
     typer.echo(f"Removed {removed} file(s).", err=True)
 
 
+def _warm_shared_cir(target: Path):
+    """Pre-populate the shared Canonical IR in the context cache (the entry explain and
+    other knowledge commands reuse). Returns the KnowledgeLookup, or None on any fault —
+    warming is best-effort and never fails the warm command."""
+    try:
+        from sourcecode.repository_ir import find_java_files as _fjf
+        from sourcecode import context_cache as _ctxcache
+        files = _fjf(target)
+        if not files:
+            return None
+        _cir, look = _ctxcache.get_or_build_cir(_resolve_repo_root(target), target, files)
+        return look
+    except Exception:
+        return None
+
+
 @cache_app.command("warm")
 def cache_warm_cmd(
     path: Path = typer.Argument(Path("."), help="Repository path to warm (default: current directory)"),
@@ -8245,6 +8413,18 @@ def cache_warm_cmd(
             typer.echo(result.stderr.strip(), err=True)
         raise typer.Exit(code=result.returncode)
 
+    # Also pre-populate the shared Canonical IR (context cache) — a DIFFERENT cache from
+    # the L1/L2 core cache warmed above. explain (and, going forward, other knowledge
+    # commands) reuse this CIR; without warming it here, the first explain rebuilds the
+    # expensive Java parse despite a "warm" cache (field-eval: explain MISS after warm).
+    _look = _warm_shared_cir(target)
+    if _look is not None:
+        typer.echo(
+            f"Shared CIR {'reused' if _look.hit else 'built'} "
+            "(explain/impact reuse this).",
+            err=True,
+        )
+
 
 @cache_app.command("freshness")
 def cache_freshness_cmd(
@@ -8386,6 +8566,23 @@ def _stderr_is_interactive() -> bool:
         return False
 
 
+def _force_utf8_streams() -> None:
+    """Force UTF-8 on stdout AND stderr so Unicode characters (em-dash, arrows, box
+    drawing) survive on Windows where the default console codec is cp1252 (BUG-1).
+
+    stderr matters as much as stdout: progress/warn/gap status text is emitted there,
+    and a cp1252 encoder turned its em-dashes into the replacement char (field-eval).
+    Best-effort and idempotent — a stream without ``reconfigure`` (already wrapped, or a
+    test buffer) is skipped silently.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            try:
+                stream.reconfigure(encoding="utf-8")
+            except Exception:
+                pass
+
+
 def main_entry() -> None:
     """CLI entry point for both the canonical ``ask`` command and the deprecated
     ``sourcecode`` compat alias — one implementation, no duplication.
@@ -8395,13 +8592,7 @@ def main_entry() -> None:
     can consume them as positional arguments (which would prevent subcommand
     routing for tokens like 'version' or 'config').
     """
-    # Force UTF-8 on stdout so Unicode characters (arrows, etc.) survive on
-    # Windows where the default console codec is cp1252 (BUG-1).
-    if hasattr(sys.stdout, "reconfigure"):
-        try:
-            sys.stdout.reconfigure(encoding="utf-8")
-        except Exception:
-            pass
+    _force_utf8_streams()
     # Deprecation notice when invoked through the legacy `sourcecode` alias.
     # One line, and only on an interactive terminal — pipes/agents that still call
     # `sourcecode` keep clean stderr (error envelopes are JSON on stderr), so the

sourcecode/context_cache.py

@@ -620,6 +620,46 @@ def get_or_build_cir(
     return cir, KnowledgeLookup(hit=False, enabled=True, build_ms=build_ms)
 
 
+def peek_cir(
+    repo_root: Path,
+    *,
+    since: Optional[str] = None,
+) -> Optional[Any]:
+    """Return the shared ``CanonicalRepositoryIR`` **only if already cached**.
+
+    Get-only sibling of :func:`get_or_build_cir`: it never builds and never
+    writes. A caller that holds only a *bounded scope* of the repo (e.g. the
+    review-pr git-first path) must use this — routing a scoped build through
+    ``get_or_build_cir`` would store a truncated CIR under the repo-wide
+    knowledge key and poison every command that reads it. On a hit the caller
+    gets the full repo-wide CIR for free (O(1) reconstruction from raw IR); on
+    a miss it gets ``None`` and keeps its own scoped build, unshared.
+
+    The reconstructed CIR is left repo-consistent (``file_paths=None`` derives
+    the file list from the cached nodes, not from any caller scope).
+    """
+    from sourcecode.canonical_ir import ir_dict_to_canonical, validate_canonical_ir
+
+    cache = ContextCache.for_repo(repo_root)
+    if not cache.enabled:
+        return None
+    key = cache.knowledge_key(SCOPE_JAVA_CIR, options={"since": since} if since else None)
+    cached = cache.get(key)
+    if cached is None:
+        return None
+    raw = cached.payload.get("raw_ir")
+    if not isinstance(raw, dict):
+        return None
+    try:
+        cir = ir_dict_to_canonical(raw, file_paths=None)
+        # validate_canonical_ir returns a LIST of problems — empty means valid.
+        if not validate_canonical_ir(cir):
+            return cir
+    except Exception:
+        pass  # corrupt/incompatible payload — treat as miss
+    return None
+
+
 # ---------------------------------------------------------------------------
 # Module-level observability helper
 # ---------------------------------------------------------------------------

sourcecode/filter_surface.py

@@ -0,0 +1,173 @@
+"""filter_surface.py — servlet filter URL-pattern reconstruction (Fase 2).
+
+Reconstructs the URL patterns that servlet filters are mapped to, from the two
+**deterministic** sources the platform declares them in:
+
+  1. ``@WebFilter(urlPatterns=… / value=…)`` annotation arguments in ``.java``;
+  2. ``web.xml`` ``<filter-mapping><url-pattern>`` entries.
+
+This is an EXTRACTOR (it reads source / XML), deliberately separate from the
+Knowledge-Layer ``security_posture`` module (which never opens source). Its output
+is a set of servlet URL patterns that the security posture then crosses against the
+endpoint surface, so an endpoint that does NOT carry a per-method gate can still be
+reported as *possibly covered* by a filter whose pattern matches its path — rather
+than being over-flagged.
+
+**Explicit scope (a measured limitation, not a bug).** Three further pattern sources
+are NOT reconstructed here and are declared to the caller: Spring
+``FilterRegistrationBean.addUrlPatterns()``, the ``HttpSecurity``/``requestMatchers``
+DSL, and AspectJ ``@Aspect`` pointcuts (which are not URL patterns at all). Absence of
+a reconstructed pattern therefore never proves an endpoint is unprotected — it means
+"no *declarative servlet* pattern matched"; the caller frames it as review, never as
+"unsecured".
+"""
+from __future__ import annotations
+
+import re
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+# @WebFilter(...) argument block. We capture the whole paren body and pull quoted
+# tokens from the urlPatterns/value members (both are the servlet-standard members).
+_WEBFILTER_RE = re.compile(r"@WebFilter\s*\((?P<body>[^)]*)\)", re.DOTALL)
+_QUOTED_RE = re.compile(r'"([^"]*)"')
+# urlPatterns=… or value=… member (either names the patterns). If neither member
+# name is present, a bare @WebFilter("/x") uses value implicitly → all quoted tokens.
+_MEMBER_RE = re.compile(r"(urlPatterns|value)\s*=", re.DOTALL)
+
+
+@dataclass
+class FilterSurface:
+    """Reconstructed servlet filter URL patterns + their provenance."""
+
+    patterns: list[str] = field(default_factory=list)
+    # pattern → list of human-readable sources (filter class / web.xml) — evidence only
+    provenance: dict[str, list[str]] = field(default_factory=dict)
+
+    def is_empty(self) -> bool:
+        return not self.patterns
+
+    def matching_pattern(self, path: Optional[str]) -> Optional[str]:
+        """The first reconstructed servlet pattern that covers ``path`` (servlet
+        matching semantics), or None. Deterministic: patterns are checked in sorted
+        order so the result is stable."""
+        if not path:
+            return None
+        for pat in sorted(self.patterns):
+            if _servlet_pattern_matches(pat, path):
+                return pat
+        return None
+
+    def to_dict(self) -> dict:
+        return {
+            "patterns": sorted(self.patterns),
+            "provenance": {k: sorted(v) for k, v in sorted(self.provenance.items())},
+        }
+
+
+def _servlet_pattern_matches(pattern: str, path: str) -> bool:
+    """Servlet-spec URL-pattern match (SRV.12.2), the semantics @WebFilter / web.xml
+    use — NOT Ant globbing:
+
+      * ``/*``            → matches every path (catch-all);
+      * ``/prefix/*``     → path-prefix: the prefix itself or anything under it;
+      * ``*.ext``         → extension match on the final path segment;
+      * exact string      → equality.
+
+    ``/`` (the default-servlet mapping) is treated as exact — it does not blanket
+    every path here, to avoid over-claiming coverage.
+    """
+    if not pattern:
+        return False
+    p = path if path.startswith("/") else "/" + path
+    if pattern == "/*":
+        return True
+    if pattern.endswith("/*"):
+        prefix = pattern[:-2]  # "/api/*" → "/api"
+        return p == prefix or p.startswith(prefix + "/")
+    if pattern.startswith("*."):
+        return p.rsplit("/", 1)[-1].endswith(pattern[1:])  # "*.do" → endswith ".do"
+    return p == pattern
+
+
+def _patterns_from_webfilter(source: str) -> list[str]:
+    """Servlet URL patterns declared in ``@WebFilter(...)`` annotations in one file."""
+    out: list[str] = []
+    for m in _WEBFILTER_RE.finditer(source):
+        body = m.group("body")
+        if not body.strip():
+            continue
+        # If the body names urlPatterns=/value=, take quoted tokens AFTER that member;
+        # else (bare @WebFilter("/x")) take all quoted tokens. servletNames are not URL
+        # patterns, but they are rare and never start with '/'/'*', so filtering by shape
+        # keeps them out.
+        mem = _MEMBER_RE.search(body)
+        segment = body[mem.end():] if mem else body
+        for tok in _QUOTED_RE.findall(segment):
+            if tok and (tok.startswith("/") or tok.startswith("*.")):
+                out.append(tok)
+    return out
+
+
+def _patterns_from_web_xml(xml_path: Path) -> list[str]:
+    """Servlet URL patterns from ``<filter-mapping><url-pattern>`` in one web.xml.
+    Namespace-agnostic; never raises on malformed XML (returns what it parsed)."""
+    out: list[str] = []
+    try:
+        root = ET.parse(str(xml_path)).getroot()
+    except Exception:
+        return out
+    for elem in root.iter():
+        tag = elem.tag.rsplit("}", 1)[-1]  # strip any namespace
+        if tag != "filter-mapping":
+            continue
+        for child in elem.iter():
+            if child.tag.rsplit("}", 1)[-1] == "url-pattern" and (child.text or "").strip():
+                out.append(child.text.strip())
+    return out
+
+
+def build_filter_surface(
+    root: Path, java_files: Optional[list[str]] = None
+) -> FilterSurface:
+    """Reconstruct the declarative servlet filter surface under ``root``.
+
+    ``java_files`` are repo-relative ``.java`` paths (as ``find_java_files`` yields);
+    when omitted they are discovered. web.xml files are located by glob. Best-effort:
+    an unreadable file is skipped, never fatal.
+    """
+    surface = FilterSurface()
+
+    if java_files is None:
+        try:
+            from sourcecode.repository_ir import find_java_files
+            java_files = find_java_files(root)
+        except Exception:
+            java_files = []
+
+    def _add(pattern: str, source: str) -> None:
+        if pattern not in surface.provenance:
+            surface.patterns.append(pattern)
+            surface.provenance[pattern] = []
+        if source not in surface.provenance[pattern]:
+            surface.provenance[pattern].append(source)
+
+    for rel in java_files:
+        abs_path = root / rel
+        try:
+            src = abs_path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        if "@WebFilter" not in src:
+            continue
+        for pat in _patterns_from_webfilter(src):
+            _add(pat, f"@WebFilter:{rel}")
+
+    for xml_path in sorted(root.rglob("web.xml")):
+        rel = xml_path.relative_to(root).as_posix()
+        for pat in _patterns_from_web_xml(xml_path):
+            _add(pat, f"web.xml:{rel}")
+
+    return surface

sourcecode/migrate_check.py

@@ -2155,6 +2155,16 @@ def run_migrate_check(
         },
     )
 
+    # Stamp the shared, path-stable repo identity (the id the cache subsystem keys on)
+    # so migrate-check no longer emits an empty repo_id while every other command emits
+    # one. migrate-check is deliberately cir-free (its speed advantage), so it uses the
+    # cache repo_id rather than building a CanonicalIR just to hash it.
+    try:
+        from sourcecode.cache import repo_id as _repo_id
+        report.repo_id = _repo_id(root)
+    except Exception:
+        pass
+
     try:
         import subprocess as _sub
         _r = _sub.run(