sourcecode 3.8.0__py3-none-any.whl → 4.0.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.8.0"
+__version__ = "4.0.0"

sourcecode/cache.py

@@ -354,6 +354,7 @@ def status(repo_root: Path) -> dict[str, Any]:
             "cores": 0, "snapshots": 0, "views": 0, "cas_blobs": 0,
             "total_size_bytes": 0, "total_size_mb": 0.0,
             "current_git_head": current_head,
+            "stores": _store_breakdown(repo_root, 0),
             **ris_fields,
         }
     cores = list(cache_d.glob("core-*.json.gz"))
@@ -371,10 +372,57 @@ def status(repo_root: Path) -> dict[str, Any]:
         "total_size_bytes": total_bytes,
         "total_size_mb": round(total_bytes / (1024 * 1024), 2),
         "current_git_head": current_head,
+        # C3-36: `CAS blobs: 0`, `Total size: 0.1 MB` immediately after an 89-second
+        # warm of 3 342 files. Every figure above was true and described one store
+        # of three — the warm's output mostly lands in the shared CIR and the parse
+        # cache, which this command never counted. A status that reports a third of
+        # the state reads as a warm that did nothing.
+        "stores": _store_breakdown(repo_root, total_bytes),
         **ris_fields,
     }
 
 
+def _store_breakdown(repo_root: Path, core_bytes: int) -> "dict[str, Any]":
+    """What a warm actually populated, by store. Best-effort per store: a store
+    that cannot be inspected is reported as unavailable, never as empty."""
+    out: "dict[str, Any]" = {
+        "core": {
+            "cache_dir": str(cache_dir(repo_root)),
+            "bytes": core_bytes,
+            "scope": "this repository",
+            "holds": "core snapshots, rendered views and their CAS blobs",
+        },
+    }
+    try:
+        from sourcecode.context_cache import ContextCache  # noqa: PLC0415
+
+        ctx = ContextCache.for_repo(repo_root).stats()
+        out["shared_cir"] = {
+            "cache_dir": ctx["cache_dir"],
+            "entries": ctx["contexts"],
+            "bytes": ctx["bytes_stored"],
+            "scope": "this repository",
+            "holds": "the shared Canonical IR that explain/impact/posture reuse",
+        }
+    except Exception:
+        out["shared_cir"] = {"available": False}
+    try:
+        from sourcecode import parse_cache as _pc  # noqa: PLC0415
+
+        out["parse"] = {
+            **_pc.store_stats(),
+            "holds": "per-file parses, content-addressed across every repository",
+        }
+    except Exception:
+        out["parse"] = {"available": False}
+    out["note"] = (
+        "`cache warm` populates all of these; the core store alone is a third of "
+        "the answer, and reading it as the whole is how a completed warm looks like "
+        "an empty cache."
+    )
+    return out
+
+
 def clear(repo_root: Path, *, clear_ris: bool = False) -> int:
     """Delete cache files for *repo_root*.  Returns the number of files removed.
 

sourcecode/cache_model.py

@@ -131,6 +131,13 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "builds — the parse it used to repeat for itself. `--diff` compares two profile "
                  "sets over that one IR, so the second side costs the resolution only.",
                  "10.1 s → 1.6 s"),
+    CommandCache("risk", ("cir", "parse"), "shared", False,
+                 "Composes what the audit, impact-chain and the posture already answer, so it "
+                 "pays each of their costs once over the shared CIR a warm builds — one parse "
+                 "for the whole composition, and the reachability query is cached per symbol "
+                 "within the run.",
+                 "not measured on the battery yet — the composition is bounded by the "
+                 "`spring-audit` + `impact-chain` costs listed here, not by new analysis"),
     CommandCache("endpoints", ("ris", "parse"), "shared", False,
                  "Recomputes the endpoint surface on every run, over a parse a warm has already "
                  "paid for. Until 3.7.0 the extractor parsed every file itself instead of reading "

sourcecode/cli.py

@@ -183,7 +183,7 @@ COMMAND_TIERS: "tuple[tuple[str, str, tuple[str, ...]], ...]" = (
         "cache", "auth", "mcp", "telemetry",
     )),
     ("experimental", "shape may change in a minor — do not gate CI on it", (
-        "posture", "archetype",
+        "risk", "posture", "archetype",
     )),
     # `retrieve` publishes 15+ intents whose answers the other commands already
     # give better: measured on the battery, `security-surface` merely re-states
@@ -5475,11 +5475,21 @@ def validation_cmd(
     # The payload carries the same note, so a pipeline loses nothing.
     if _note:
         _notice(f"Note: {_note}")
+    # C2-15: the console said "0 body endpoints, 1179 gaps" over a payload carrying
+    # `body_endpoints_in_code: 1201` — it printed the *declared-constraint* count
+    # under the *code-surface* name, so the one line most readers see stated the
+    # opposite of the answer. Both axes are named, in their own units.
+    _declared = _summary.get("endpoints_with_body", 0)
+    _in_code = _summary.get("body_endpoints_in_code")
+    _bodies = (
+        f"{_in_code} body endpoints in code, {_declared} with a declared constraint "
+        f"surface" if _in_code is not None
+        else f"{_declared} routes with a declared constraint surface"
+    )
     _emit_command_output(
         output, output_path, copy,
         success_msg=f"Validation surface written to {output_path} "
-        f"({_summary.get('endpoints_with_body', 0)} body endpoints, "
-        f"{_summary.get('gaps', 0)} gaps)",
+        f"({_bodies}, {_summary.get('gaps', 0)} gaps)",
     )
 
     from sourcecode.mcp_nudge import nudge_mcp_if_needed as _nudge
@@ -6308,11 +6318,13 @@ def _render_gate_coverage_section(result: "SpringAuditResult") -> list[str]:  #
     gc = (result.security_posture or {}).get("gate_coverage")
     if not gc:
         return []
-    not_covered = gc.get("endpoints_not_carrying_gate", gc.get("not_carrying_gate", 0))
+    not_covered = gc.get("endpoints_not_carrying_gate", 0)
     gates = ", ".join(f"`{g}`" for g in gc.get("gate_annotations", [])) or "the detected gate"
     # One unit, named: these are endpoints, not handler methods. The two counts differ
     # (one method can serve several mappings) and must never be summed together.
-    total = gc.get("endpoints_total", gc.get("total_controller_handlers", 0))
+    # C2-14: read only the explicit keys — falling back to the retired aliases is how
+    # a name that lies about its unit survives its own removal.
+    total = gc.get("endpoints_total", 0)
     lines: list[str] = ["", "---", ""]
     if not_covered == 0:
         _gated = gc.get("endpoints_carrying_gate", total)
@@ -6326,7 +6338,6 @@ def _render_gate_coverage_section(result: "SpringAuditResult") -> list[str]:  #
             lines.append(f"✅ **Gate coverage** — all {total} endpoints carry {gates}.")
         return lines
 
-    covered = gc.get("possibly_filter_covered", 0)
     _standard = gc.get("endpoints_standard_guarded", 0)
     lines.append(
         f"🔓 **Gate coverage** — {not_covered} of {total} endpoints do not carry "
@@ -6338,9 +6349,18 @@ def _render_gate_coverage_section(result: "SpringAuditResult") -> list[str]:  #
             f"standard guard, {not_covered} on neither — the three sum to {total}._"
         )
     if gc.get("reconstructed_filter_patterns"):
+        # C1-20: the split, not the total. "N match a filter pattern" is the sentence
+        # a reader turns into "N are covered", and in the field the filters doing the
+        # matching were CORS, headers and logging.
+        _auth = gc.get("filter_covered_authenticating", 0)
+        _gap = gc.get("filter_gap_non_authenticating", 0)
+        _unknown = gc.get("filter_authentication_unknown", 0)
         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._"
+            f"_{_auth} are covered by a servlet filter that authenticates; {_gap} match "
+            f"only filters that do not check the caller (CORS, headers, logging and the "
+            f"like); {_unknown} match a filter whose implementation is not in this "
+            f"repository; {gc.get('no_matching_filter_pattern', 0)} match no pattern at "
+            f"all. Filter-chain order is not reconstructed._"
         )
     lines += ["", "<details>", "<summary>Handlers without the gate</summary>", ""]
     lines += [
@@ -6840,6 +6860,74 @@ def verify_cmd(
         raise typer.Exit(code=report.exit_code)
 
 
+@app.command("risk")
+def risk_cmd(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository path (default: current directory).",
+    ),
+    limit: int = typer.Option(
+        50, "--limit", help="How many composed risks to publish (highest first)."
+    ),
+    min_band: str = typer.Option(
+        "low",
+        "--min-band",
+        help="Floor on the composed band: critical | high | medium | low.",
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Write the report to a file instead of stdout."
+    ),
+    format: str = typer.Option("json", "--format", "-f", help="Output format: json or yaml."),
+) -> None:
+    """[EXPERIMENTAL] What each defect actually costs, once reach and access are in it.
+
+    \b
+    The other commands answer one axis each, correctly, and leave the composition
+    to the reader. In the field, one class was `medium` in `spring-audit`,
+    `medium/5.0` in `impact-chain`, `coverage_unknown → permit_all` in `posture`,
+    and executed a stored procedure that mutates the database. Composed, that is
+    unauthenticated write access under the release build; separately, it was two
+    commands saying "medium".
+
+    \b
+      severity_effective = defect_severity × reachability × auth_verdict × write_effect
+
+    \b
+    No new analysis: every factor is read from the command that already publishes
+    it, and every row publishes its four factors with the authority each came
+    from, so a reader can disagree with one and keep the rest. An axis that could
+    not be measured is `unknown`, multiplies by 1.0, and is named in `blind_axes`.
+
+    \b
+    Examples:
+      ask risk .
+      ask risk . --min-band high
+      ask risk . --limit 10 -o risk.json
+    """
+    from sourcecode.risk import build_risk
+
+    path = _admit_path(path)
+    if min_band not in ("critical", "high", "medium", "low"):
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"--min-band expects critical | high | medium | low (got {min_band!r}).",
+            hint="Example: --min-band high",
+            expected="critical|high|medium|low",
+        )
+        raise typer.Exit(code=1)
+
+    data = build_risk(path, limit=limit, min_band=min_band)
+    _emit_command_output(
+        _serialize_dict(data, format),
+        output_path,
+        False,
+        success_msg=(
+            f"risk written to {output_path} ({data['shown']} of "
+            f"{data['total_defects']} defects composed)"
+        ),
+    )
+
+
 @app.command("posture")
 def posture_cmd(
     path: Path = typer.Argument(
@@ -9969,6 +10057,20 @@ def cache_status_cmd(
         typer.echo(f"Views:       {stats['views']}")
         typer.echo(f"CAS blobs:   {stats['cas_blobs']}")
         typer.echo(f"Total size:  {stats['total_size_mb']} MB")
+        # C3-36: the three lines above describe ONE of the three stores a warm
+        # fills. Printed alone after an 89 s warm they read as "nothing was
+        # cached", which is the opposite of what happened.
+        _stores = stats.get("stores") or {}
+        for _label, _key in (("Shared CIR", "shared_cir"), ("Parse cache", "parse")):
+            _store = _stores.get(_key) or {}
+            if not _store or _store.get("available") is False:
+                typer.echo(f"{_label + ':':<13}unavailable")
+                continue
+            _mb = round(_store.get("bytes", 0) / (1024 * 1024), 2)
+            _scope = " (shared across repositories)" if _store.get("scope") == "shared" else ""
+            typer.echo(
+                f"{_label + ':':<13}{_store.get('entries', 0)} entries, {_mb} MB{_scope}"
+            )
         # RIS section
         if stats.get("ris_exists"):
             _stale_tag = " [STALE]" if stats.get("ris_is_stale") else ""
@@ -10326,7 +10428,7 @@ HELP_PANELS: "tuple[tuple[str, tuple[str, ...]], ...]" = (
         "cache", "auth", "mcp", "telemetry", "baseline",
     )),
     ("Experimental — shape may change", (
-        "archetype", "retrieve",
+        "risk", "archetype", "retrieve",
     )),
 )
 

sourcecode/confidence_analyzer.py

@@ -343,9 +343,14 @@ class ConfidenceAnalyzer:
                 gaps.append(AnalysisGap(
                     area="testing",
                     reason=(
+                        # C1-19: "Java files" here has always meant the non-test ones
+                        # — the denominator of a test ratio cannot include the tests.
+                        # Unqualified, it read as a third file count contradicting
+                        # `migrate-check.java_files_scanned` (which counts them all).
                         f"Backend test coverage critical: {len(_java_tests)} test files "
-                        f"for {len(_java_prod)} Java files "
-                        f"({_ratio:.1%}) — {_java_test_facts.basis}"
+                        f"for {len(_java_prod)} non-test Java files "
+                        f"(of {len(_java_all)} Java files, {_ratio:.1%}) — "
+                        f"{_java_test_facts.basis}"
                     ),
                     impact="high",
                 ))

sourcecode/defect_identity.py

@@ -93,6 +93,25 @@ def assign_defect_ids(findings: "Iterable[SpringFinding]") -> None:
         finding.defect_id = make_defect_id(category, kind, symbol)
 
 
+def _witness_sites(witnesses: "list[SpringFinding]") -> "dict[str, Any]":
+    """The distinct places this defect was observed, when the witnesses record one."""
+    sites: "list[dict[str, Any]]" = []
+    seen: "set[tuple[str, Any]]" = set()
+    for finding in witnesses:
+        site = (finding.evidence or {}).get("call_site")
+        if not isinstance(site, dict):
+            continue
+        key = (str(site.get("source_file") or ""), site.get("line"))
+        if key in seen:
+            continue
+        seen.add(key)
+        sites.append(site)
+    if not sites:
+        return {}
+    sites.sort(key=lambda s: (str(s.get("source_file") or ""), s.get("line") or 0))
+    return {"witness_sites": sites, "distinct_site_count": len(sites)}
+
+
 def group_by_defect(findings: "list[SpringFinding]") -> list[dict[str, Any]]:
     """One row per defect, most severe first, each naming its witnesses.
 
@@ -137,6 +156,11 @@ def group_by_defect(findings: "list[SpringFinding]") -> list[dict[str, Any]]:
             "rule_ids": sorted({f.pattern_id for f in witnesses}),
             "witness_count": len(witnesses),
             "witnesses": [f.id for f in witnesses],
+            # C2-16: witnesses of one defect are all located at the symbol that
+            # carries the remedy, so several of them print the same line and read
+            # as duplicates. Where each was actually observed is listed here, and
+            # a count of distinct sites so "N witnesses" can be checked against it.
+            **_witness_sites(witnesses),
         })
     rows.sort(key=lambda r: (SEVERITY_RANK.get(r["severity"], 9), r["symbol"]))
     return rows

sourcecode/environment_resolution.py

@@ -209,7 +209,7 @@ def collect_signals(root: Path) -> list[Signal]:
         if _PROPERTY_KEY not in text and _ENV_KEY not in text:
             continue
         try:
-            rel = str(path.relative_to(root))
+            rel = path.relative_to(root).as_posix()
         except ValueError:
             rel = str(path)
         lines = text.splitlines()

sourcecode/filter_surface.py

@@ -38,6 +38,117 @@ _QUOTED_RE = re.compile(r'"([^"]*)"')
 _MEMBER_RE = re.compile(r"(urlPatterns|value)\s*=", re.DOTALL)
 
 
+#: Published Servlet / Spring Security / JAAS vocabulary by which a filter
+#: *establishes* a caller identity. Recorded as evidence for a verdict; never a
+#: predicate over a client's own class name (VAI) — `AuthFilter` proves nothing and
+#: `M3FiltroSeguridad` is not less of an authenticator for being called that.
+_ESTABLISHES_IDENTITY = (
+    "SecurityContextHolder",
+    "setAuthentication",
+    "AuthenticationManager",
+    "AuthenticationProvider",
+    "UsernamePasswordAuthenticationToken",
+    "PreAuthenticatedAuthenticationToken",
+    "AbstractAuthenticationProcessingFilter",
+    "AuthenticationEntryPoint",
+    ".authenticate(",
+    "request.login(",
+    "getUserPrincipal(",
+)
+
+#: Vocabulary by which a filter *reads a credential* off the request.
+_READS_CREDENTIAL = (
+    '"Authorization"',
+    "HttpHeaders.AUTHORIZATION",
+    "AUTHORIZATION",
+    "Bearer ",
+    "parseClaimsJws",
+    "parseSignedClaims",
+    "JWTVerifier",
+    "verifyToken",
+    "validateToken",
+    "getSession(false)",
+)
+
+#: Vocabulary by which a filter *refuses* a request it did not authenticate. Alone
+#: this is not authentication — a rate limiter refuses too — so it only counts
+#: alongside a credential read.
+_REFUSES = (
+    "SC_UNAUTHORIZED",
+    "SC_FORBIDDEN",
+    "sendError(401",
+    "sendError(403",
+    "setStatus(401",
+    "setStatus(403",
+    "AccessDeniedException",
+)
+
+#: The three verdicts. Named after what was established, not after a confidence
+#: level, because "unknown" here is a specific thing: the implementation was never
+#: read, so nothing was ruled in or out.
+AUTHENTICATES = "authenticates"
+DOES_NOT_AUTHENTICATE = "does_not_authenticate"
+AUTHENTICATION_UNKNOWN = "unknown"
+
+
+def authentication_verdict(source: str) -> "tuple[str, list[str]]":
+    """Does this filter implementation authenticate the caller, and on what evidence?
+
+    C1-20. A pattern match tells you a filter *runs* on a path; it says nothing about
+    what the filter does there. In the field, three filters matched 2 635 endpoints
+    with `/*`, `/api/*` and `/api/v1/*` — and they were CORS, header and logging
+    filters. The reassurance was entirely in the reader's head.
+
+    Two independent ways to answer yes, both structural:
+      * the filter establishes an identity (it touches the security context, an
+        authentication manager, or a principal); or
+      * it reads a credential off the request **and** refuses requests over it.
+
+    A body we could not read is `unknown`, never `does_not_authenticate` — the whole
+    point is to stop absence of evidence from being published as evidence.
+    """
+    if not source:
+        return AUTHENTICATION_UNKNOWN, []
+    seen_identity = [tok for tok in _ESTABLISHES_IDENTITY if tok in source]
+    seen_credential = [tok for tok in _READS_CREDENTIAL if tok in source]
+    seen_refusal = [tok for tok in _REFUSES if tok in source]
+    if seen_identity:
+        return AUTHENTICATES, sorted(set(seen_identity + seen_credential))
+    if seen_credential and seen_refusal:
+        return AUTHENTICATES, sorted(set(seen_credential + seen_refusal))
+    return DOES_NOT_AUTHENTICATE, sorted(set(seen_credential + seen_refusal))
+
+
+@dataclass(frozen=True)
+class FilterDeclaration:
+    """One declared servlet filter: what it is mapped to, and what it does there."""
+
+    name: str
+    source: str
+    patterns: "tuple[str, ...]"
+    authenticates: str = AUTHENTICATION_UNKNOWN
+    evidence: "tuple[str, ...]" = ()
+    implementation_file: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        out: dict = {
+            "filter": self.name,
+            "declared_in": self.source,
+            "patterns": sorted(self.patterns),
+            "authenticates": self.authenticates,
+        }
+        if self.evidence:
+            out["evidence"] = list(self.evidence)
+        if self.implementation_file:
+            out["implementation_file"] = self.implementation_file
+        if self.authenticates == AUTHENTICATION_UNKNOWN:
+            out["reason"] = (
+                "the implementation class was not found in this repository, so nothing "
+                "was ruled in or out"
+            )
+        return out
+
+
 @dataclass
 class FilterSurface:
     """Reconstructed servlet filter URL patterns + their provenance."""
@@ -45,6 +156,10 @@ class FilterSurface:
     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)
+    # Per-filter records. `patterns` above stays the flat union it always was, so
+    # every existing consumer keeps working; the split C1-20 needs is per filter,
+    # because the question is not "is a filter here" but "does *that* filter check".
+    filters: list[FilterDeclaration] = field(default_factory=list)
 
     def is_empty(self) -> bool:
         return not self.patterns
@@ -60,10 +175,45 @@ class FilterSurface:
                 return pat
         return None
 
+    def matching_filters(self, path: Optional[str]) -> "list[FilterDeclaration]":
+        """Every declared filter whose patterns cover ``path``, in a stable order."""
+        if not path:
+            return []
+        return [
+            f for f in sorted(self.filters, key=lambda d: (d.name, d.source))
+            if any(_servlet_pattern_matches(p, path) for p in f.patterns)
+        ]
+
+    def authenticating_pattern(self, path: Optional[str]) -> Optional[str]:
+        """The pattern of the first filter covering ``path`` that authenticates."""
+        for f in self.matching_filters(path):
+            if f.authenticates != AUTHENTICATES:
+                continue
+            for pat in sorted(f.patterns):
+                if _servlet_pattern_matches(pat, path):
+                    return pat
+        return None
+
+    def coverage_verdict(self, path: Optional[str]) -> str:
+        """How this path stands relative to the *authenticating* filter surface:
+        `authenticates`, `unknown` (a filter covers it whose body we never read), or
+        `does_not_authenticate` (covered only by filters that demonstrably do not).
+        A path no pattern covers returns `does_not_authenticate` — the caller keeps
+        that case separate as "no matching pattern"."""
+        matched = self.matching_filters(path)
+        if any(f.authenticates == AUTHENTICATES for f in matched):
+            return AUTHENTICATES
+        if any(f.authenticates == AUTHENTICATION_UNKNOWN for f in matched):
+            return AUTHENTICATION_UNKNOWN
+        return DOES_NOT_AUTHENTICATE
+
     def to_dict(self) -> dict:
         return {
             "patterns": sorted(self.patterns),
             "provenance": {k: sorted(v) for k, v in sorted(self.provenance.items())},
+            "filters": [
+                f.to_dict() for f in sorted(self.filters, key=lambda d: (d.name, d.source))
+            ],
         }
 
 
@@ -114,18 +264,56 @@ def _patterns_from_webfilter(source: str) -> list[str]:
 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] = []
+    return [pat for _name, pats in _mappings_from_web_xml(xml_path) for pat in pats]
+
+
+def _local(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1]
+
+
+def _child_text(elem: "ET.Element", name: str) -> str:
+    for child in elem.iter():
+        if _local(child.tag) == name and (child.text or "").strip():
+            return child.text.strip()
+    return ""
+
+
+def _mappings_from_web_xml(xml_path: Path) -> "list[tuple[str, list[str]]]":
+    """``(filter-name, url-patterns)`` per ``<filter-mapping>``. The name is what
+    correlates a mapping with the class that implements it (C1-20): without it, a
+    pattern is anonymous and every filter looks like every other filter."""
+    out: "list[tuple[str, 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":
+        if _local(elem.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())
+        patterns = [
+            child.text.strip()
+            for child in elem.iter()
+            if _local(child.tag) == "url-pattern" and (child.text or "").strip()
+        ]
+        if patterns:
+            out.append((_child_text(elem, "filter-name"), patterns))
+    return out
+
+
+def _filter_classes_from_web_xml(xml_path: Path) -> "dict[str, str]":
+    """``<filter>`` declarations: filter-name → filter-class."""
+    out: "dict[str, str]" = {}
+    try:
+        root = ET.parse(str(xml_path)).getroot()
+    except Exception:
+        return out
+    for elem in root.iter():
+        if _local(elem.tag) != "filter":
+            continue
+        name = _child_text(elem, "filter-name")
+        klass = _child_text(elem, "filter-class")
+        if name and klass:
+            out[name] = klass
     return out
 
 
@@ -154,20 +342,63 @@ def build_filter_surface(
         if source not in surface.provenance[pattern]:
             surface.provenance[pattern].append(source)
 
+    # Simple name → repo-relative path, so a `<filter-class>` in web.xml can be read
+    # for what it actually does. Ambiguous simple names (two classes, one name) are
+    # dropped rather than guessed: the wrong body would produce a confident verdict
+    # about the wrong filter, which is the failure this row exists to remove.
+    by_simple_name: "dict[str, Optional[str]]" = {}
     for rel in java_files:
-        abs_path = root / rel
+        stem = rel.rsplit("/", 1)[-1][: -len(".java")] if rel.endswith(".java") else ""
+        if not stem:
+            continue
+        by_simple_name[stem] = None if stem in by_simple_name else rel
+
+    def _read(rel: Optional[str]) -> str:
+        if not rel:
+            return ""
         try:
-            src = abs_path.read_text(encoding="utf-8", errors="replace")
+            return (root / rel).read_text(encoding="utf-8", errors="replace")
         except OSError:
-            continue
+            return ""
+
+    for rel in java_files:
+        src = _read(rel)
         if "@WebFilter" not in src:
             continue
-        for pat in _patterns_from_webfilter(src):
+        patterns = _patterns_from_webfilter(src)
+        if not patterns:
+            continue
+        for pat in patterns:
             _add(pat, f"@WebFilter:{rel}")
+        verdict, evidence = authentication_verdict(src)
+        surface.filters.append(FilterDeclaration(
+            name=rel.rsplit("/", 1)[-1][: -len(".java")],
+            source=f"@WebFilter:{rel}",
+            patterns=tuple(patterns),
+            authenticates=verdict,
+            evidence=tuple(evidence),
+            implementation_file=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}")
+        classes = _filter_classes_from_web_xml(xml_path)
+        for name, patterns in _mappings_from_web_xml(xml_path):
+            for pat in patterns:
+                _add(pat, f"web.xml:{rel}")
+            klass = classes.get(name, "")
+            impl = by_simple_name.get(klass.rsplit(".", 1)[-1]) if klass else None
+            body = _read(impl)
+            verdict, evidence = (
+                authentication_verdict(body) if body else (AUTHENTICATION_UNKNOWN, [])
+            )
+            surface.filters.append(FilterDeclaration(
+                name=klass or name or "(unnamed filter-mapping)",
+                source=f"web.xml:{rel}",
+                patterns=tuple(patterns),
+                authenticates=verdict,
+                evidence=tuple(evidence),
+                implementation_file=impl,
+            ))
 
     return surface