sourcecode 4.17.0__tar.gz → 4.18.0__tar.gz

{sourcecode-4.17.0 → sourcecode-4.18.0}/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 ## [Unreleased]
 
+## [4.18.0] — 2026-08-10
+
+**A field battery over the test repositories, run against 4.17.0 and aimed first
+at where the time goes.** Three defects, all found by measuring rather than by
+reading: one answer that was silently about the wrong repository, and two scans
+that could not finish. `risk` on BroadleafCommerce (2 985 files) did not return in
+twenty minutes and now returns a complete answer in **68 s**.
+
+**Fixed in this release:**
+
+- **A run bounded to a subdirectory answered for the whole repository (C3-94).**
+  The shared Java parse was keyed on the worktree alone, so a run over a
+  subdirectory stored its subset under the repository-wide key and the next
+  repository-wide command read it. Measured on openmrs-core: `explain WebUtil
+  <repo>/web` left a **42-file / 382-symbol** CIR where the repository has 861 and
+  11 605, and `impact-chain` then answered from it — reporting 861 files beside
+  382 symbols, and dropping from `confidence: high` to `low` with no input change.
+  The analysed set is now part of the key; a repository-wide run owns the shared
+  entry and a bounded run keys on its own, so bounded runs are **cached** instead
+  of being exempt. The rule lived in one call site and four others wrote the key
+  unguarded; it now lives in the cache, behind one door.
+- **Naming the enclosing type backtracked exponentially (C3-95).** Two scanners
+  carried the same ambiguous pattern — a whitespace branch inside a starred group,
+  followed by another starred whitespace group. Measured: **13 ms** for 200 leading
+  spaces on one line, 1,17 s for 800, **10,1 s for 1 600**. Now linear: 0,06 ms at
+  1 600 and 0,76 ms at 20 000. `scan_security_configuration` on BroadleafCommerce
+  **3,34 s → 1,53 s**, same findings.
+- **`risk` could not finish, inside a regex no budget can interrupt (C3-96).**
+  `_java_methods` runs a method pattern over every source, and that pattern let the
+  same whitespace be consumed in three places at once. A catastrophic match runs in
+  CPython's C regex engine, which never returns to the interpreter — so the
+  deadline C3-87 installed is not read, and neither is a Ctrl-C. Rewritten so every
+  separator is consumed once, with the matches asserted **identical** over 1 771
+  files: eureka **142,35 s → 2,10 s**, jobrunr 29,38 s → 1,75 s, openmrs-core
+  35,25 s → 11,11 s, and `risk` on BroadleafCommerce **>20 min (killed) → 68 s**,
+  15 of 15 defects composed.
+
+**Not claimed by this release:** routing `spring-audit` and `risk` onto the shared
+parse is a correctness change, not a measured speed-up — the per-file parse cache
+already absorbed most of it, and the A/B on openmrs-core and BroadleafCommerce
+came out inside the noise. The residual cost of the method scan is polynomial, not
+linear, and `migrate-check` and `endpoints` still gain nothing from a warm; both
+are open in `.planning/ROADMAP-FIELD-BATTERY-2026-08-10.md`.
+
 ## [4.17.0] — 2026-08-10
 
 **The Part 1 queues of field evaluations #20 and #21, and the first three

{sourcecode-4.17.0 → sourcecode-4.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.17.0
+Version: 4.18.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.17.0-blue)
+![Version](https://img.shields.io/badge/version-4.18.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -126,7 +126,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.17.0 — and, on a build that has aged,
+ask version                    # ask 4.18.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.17.0 → sourcecode-4.18.0}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.17.0-blue)
+![Version](https://img.shields.io/badge/version-4.18.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -88,7 +88,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.17.0 — and, on a build that has aged,
+ask version                    # ask 4.18.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.17.0 → sourcecode-4.18.0}/pyproject.toml

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

{sourcecode-4.17.0 → sourcecode-4.18.0}/src/sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "4.17.0"
+__version__ = "4.18.0"

{sourcecode-4.17.0 → sourcecode-4.18.0}/src/sourcecode/cli.py

@@ -8285,14 +8285,20 @@ def spring_audit_cmd(
     )
     _stopped_early: Optional[str] = None
 
+    from sourcecode import context_cache as _ctxcache
+
     phase = f"auditing {len(file_list)} Java files"
     with _expensive_analysis_scope("spring-audit", target, phase):
         _prog = Progress()
         _prog.start(phase)
         try:
-            cir = ContextGraph.build(
-                file_list, target, progress=_work_sink(_prog)
-            ).cir
+            # The parse is ~89 % of this command's wall clock (measured: 8,54 s of
+            # 9,53 s on a 1 303-file repository) and it is the same parse the other
+            # knowledge commands share, so it is fetched rather than rebuilt — which
+            # is what makes a warm worth anything here (cold == warm before C3-94).
+            cir = _ctxcache.shared_cir(
+                target, file_list, progress=_work_sink(_prog)
+            )
             # C3-85: the stretch between the last `linking` tick and the first rule
             # tick reports nothing, and what stays on the line is `n/n` — a counter
             # that finished, reading as a stage still running. Measured on keycloak
@@ -9966,7 +9972,7 @@ def _migration_blast_radius(
         from sourcecode.spring_model import SpringSemanticModel
 
         try:
-            cir, _ = _ctxcache.get_or_build_cir(_resolve_repo_root(target), target, file_list)
+            cir = _ctxcache.shared_cir(target, file_list)
         except Exception:
             cir = ContextGraph.build(file_list, target).cir
         model = SpringSemanticModel.build(cir)
@@ -10520,10 +10526,7 @@ def impact_chain_cmd(
     # 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,
-            progress=_work_sink(_prog),
-        )
+        cir = _ctxcache.shared_cir(target, file_list, progress=_work_sink(_prog))
     except Exception:
         cir = ContextGraph.build(file_list, target, progress=_work_sink(_prog)).cir
     _model = SpringSemanticModel.build(cir)
@@ -10849,11 +10852,13 @@ def explain_cmd(
         )
         raise typer.Exit(code=1)
 
-    # AI Context Cache — operates at the *knowledge* level: it caches the
-    # reusable Canonical IR (the expensive Java parse), keyed only by knowledge
-    # state, not by command. explain then derives its answer cheaply from that
-    # shared CIR. The same cached CIR is reused for free by any other command.
-    # Provider-agnostic and best-effort: any fault degrades to a fresh build.
+    # AI Context Cache — operates at the *knowledge* level: it caches the reusable
+    # Canonical IR (the expensive Java parse), keyed by knowledge state and by the
+    # analysed set, not by command. explain then derives its answer cheaply from
+    # that shared CIR, and any other command over the same files reuses it for
+    # free. Provider-agnostic and best-effort: any fault degrades to a fresh build.
+    # This call site keeps the lower-level entry point because it reports the
+    # lookup (`_cc_look`); `shared_cir` is the same door without the receipt.
     _prog = Progress()
     _prog.start(f"explaining {class_name} ({len(file_list)} files)")
     _cc_look = None

{sourcecode-4.17.0 → sourcecode-4.18.0}/src/sourcecode/context_cache.py

@@ -651,6 +651,33 @@ class KnowledgeLookup:
         return f"Context cache: MISS  (build {self.build_ms:.0f}ms)"
 
 
+def analysed_set_signature(root: Path, file_list: list[str]) -> str:
+    """Fingerprint of *what was analysed*: the scope root and the exact file set.
+
+    The shared CIR is keyed on knowledge state, and until C3-94 "knowledge state"
+    was read as the worktree alone — which is only half of it. A run bounded to a
+    subdirectory parses a *subset* of the same worktree, and the resulting CIR is
+    a different artifact answering a different question. Keyed on the worktree
+    alone, both artifacts collided on one entry: measured on a 861-file repository,
+    ``explain WebUtil <repo>/web`` stored a 42-file / 382-symbol CIR under the
+    repo-wide key, and the next repo-wide command read it and answered about 3 % of
+    the repository — silently, because the reader passes its own ``file_paths`` to
+    ``ir_dict_to_canonical`` and the reconstructed CIR then reports 861 files
+    beside 382 symbols.
+
+    So the analysed set is stated, not hoped for. The scope path and the file list
+    are both in it: two roots can yield the same file count, and a caller that
+    filters its list (tests in or out) is asking about a different population than
+    one that does not.
+    """
+    payload = "".join([
+        str(root.resolve()),
+        str(len(file_list)),
+        hashlib.sha256("\n".join(sorted(file_list)).encode("utf-8")).hexdigest(),
+    ])
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:16]
+
+
 def get_or_build_cir(
     repo_root: Path,
     root: Path,
@@ -662,11 +689,19 @@ def get_or_build_cir(
     """Return ``(CanonicalRepositoryIR, KnowledgeLookup)``, caching the CIR.
 
     This is the knowledge-level entry point. It caches the **reusable** raw IR
-    (the expensive Java parse) keyed only by knowledge state — not by command —
-    so every command that needs a CIR shares one cache entry. On a hit the full
-    CIR is rebuilt cheaply from the cached raw IR via ``ir_dict_to_canonical``,
-    skipping the parse entirely. Best-effort: any cache fault falls back to a
-    fresh build.
+    (the expensive Java parse) keyed by knowledge state and by the analysed set —
+    not by command — so every command that parses the same files shares one cache
+    entry. On a hit the full CIR is rebuilt cheaply from the cached raw IR via
+    ``ir_dict_to_canonical``, skipping the parse entirely. Best-effort: any cache
+    fault falls back to a fresh build.
+
+    A **repo-wide** run (``root`` is ``repo_root``) owns the scope-free entry —
+    the one :func:`peek_cir` reads without knowing any file list, which is why
+    that key must stay free of one. Every **bounded** run keys on its own analysed
+    set instead, so it can neither read nor overwrite the repo-wide answer. Either
+    way the entry carries the analysed signature it was built from and a reader
+    whose set does not match rebuilds: the key prevents the collision, the check
+    makes the prevention verifiable rather than assumed (C3-94).
 
     `progress` is the (done, total, stage) sink the caller's heartbeat reads
     (C3-56). It reaches only the *building* paths, which is the honest place for
@@ -684,14 +719,23 @@ def get_or_build_cir(
         cir = build_canonical_ir(file_list, root, since=since, progress=progress)
         return cir, KnowledgeLookup(hit=False, enabled=False)
 
-    key = cache.knowledge_key(SCOPE_JAVA_CIR, options={"since": since} if since else None)
+    analysed = analysed_set_signature(root, file_list)
+    options: dict[str, Any] = {"since": since} if since else None
+    if root.resolve() != repo_root.resolve():
+        # A bounded run: its own entry, never the repo-wide one.
+        options = dict(options or {})
+        options["analysed"] = analysed
+    key = cache.knowledge_key(SCOPE_JAVA_CIR, options=options)
 
     t0 = time.perf_counter()
     cached = cache.get(key)
     lookup_ms = (time.perf_counter() - t0) * 1000
     if cached is not None:
         raw = cached.payload.get("raw_ir")
-        if isinstance(raw, dict):
+        stored = (cached.metadata or {}).get("analysed_set")
+        # An entry written before C3-94 carries no signature; it cannot be shown to
+        # describe this analysed set, so it is not served as if it did.
+        if isinstance(raw, dict) and stored == analysed:
             try:
                 cir = ir_dict_to_canonical(raw, file_paths=file_list)
                 if not validate_canonical_ir(cir):
@@ -708,6 +752,8 @@ def get_or_build_cir(
                 "scope": SCOPE_JAVA_CIR,
                 "cir_hash": cir.cir_hash,
                 "schema_version": cir.schema_version,
+                "analysed_set": analysed,
+                "analysed_root": str(root.resolve()),
                 "file_count": len(cir.files),
                 "symbol_count": len(cir.symbols),
             },
@@ -725,6 +771,41 @@ def get_or_build_cir(
     return cir, KnowledgeLookup(hit=False, enabled=True, build_ms=build_ms)
 
 
+def repo_root_of(root: Path) -> Path:
+    """The enclosing git root, or *root* itself outside a repository."""
+    candidate = root.resolve()
+    while True:
+        if (candidate / ".git").exists():
+            return candidate
+        if candidate.parent == candidate:
+            return root.resolve()
+        candidate = candidate.parent
+
+
+def shared_cir(
+    root: Path,
+    file_list: list[str],
+    *,
+    since: Optional[str] = None,
+    progress: "Optional[Callable[[int, int, str], None]]" = None,
+) -> Any:
+    """The Java CIR for *root*, from the shared knowledge cache.
+
+    The one door for a command that needs the repository parse and does not care
+    where it comes from: it resolves the enclosing repository itself, so a caller
+    holds no opinion about cache scope — the reason each call-site that built its
+    own CIR was one more place for the scope rule to be got wrong (C3-94).
+
+    Best-effort by construction: `get_or_build_cir` degrades to a fresh build on
+    any cache fault, so the answer never depends on the cache being there.
+    """
+    cir, _lookup = get_or_build_cir(
+        repo_root_of(root), Path(root).resolve(), file_list,
+        since=since, progress=progress,
+    )
+    return cir
+
+
 def peek_cir(
     repo_root: Path,
     *,
@@ -755,6 +836,12 @@ def peek_cir(
     raw = cached.payload.get("raw_ir")
     if not isinstance(raw, dict):
         return None
+    # The caller is promised the *repo-wide* CIR, so the entry has to say it is one.
+    # C3-94 makes the key unreachable to bounded runs; this re-reads the fact from
+    # the entry rather than inferring it from the key, and treats an entry written
+    # before that guarantee (no recorded root) as a miss.
+    if (cached.metadata or {}).get("analysed_root") != str(repo_root.resolve()):
+        return None
     try:
         cir = ir_dict_to_canonical(raw, file_paths=None)
         # validate_canonical_ir returns a LIST of problems — empty means valid.

{sourcecode-4.17.0 → sourcecode-4.18.0}/src/sourcecode/identity_fallback.py

@@ -81,11 +81,6 @@ _METHOD_RE = re.compile(
     re.MULTILINE,
 )
 
-_TYPE_RE = re.compile(
-    r"^[ \t]*(?:public|final|abstract|static|\s)*\s*(?:class|interface|enum)\s+(?P<name>\w+)",
-    re.MULTILINE,
-)
-
 #: Returns that are not an identity even inside an absence branch: re-dispatch,
 #: constants and the empty-optional answers, which are refusals in disguise.
 _NON_IDENTITY_RETURNS = re.compile(
@@ -126,13 +121,12 @@ class IdentityFallback:
 
 def _enclosing_type(source: str, offset: int) -> str:
     """The type declared closest above `offset`. Nested types resolve to the nearest
-    enclosing declaration, which is the one a reader would name."""
-    name = ""
-    for m in _TYPE_RE.finditer(source):
-        if m.start() > offset:
-            break
-        name = m.group("name")
-    return name
+    enclosing declaration, which is the one a reader would name.
+
+    Thin alias of the one authority (C3-95) — see `source_text.enclosing_type`."""
+    from sourcecode.source_text import enclosing_type
+
+    return enclosing_type(source, offset, "")
 
 
 def _method_body(source: str, brace_index: int) -> str:

{sourcecode-4.17.0 → sourcecode-4.18.0}/src/sourcecode/posture.py

@@ -1109,27 +1109,22 @@ def _repo_root_of(root: Path) -> Path:
 
 
 def shared_cir(root: Path, files: "list[str]"):
-    """The Java CIR for *root*, from the shared knowledge cache when it is safe.
+    """The Java CIR for *root*, from the shared knowledge cache.
 
     `posture` built its own CIR on every run — the same parse `explain`,
     `impact-chain` and `cache warm` already share — so the one command the
     product differentiates on was the one a warm could not help (C3-25).
 
-    Poison-safe by the same rule `peek_cir` documents: the shared knowledge key
-    is repo-wide and carries no scope, so a run bounded to a subdirectory
-    neither reads it (it describes more than this run's scope) nor writes it (it
-    would store a truncated CIR under the repo-wide key). Those runs keep their
-    own unshared build.
+    Poison-safety used to live here: the shared key was repo-wide and carried no
+    scope, so a run bounded to a subdirectory had to keep its own unshared build
+    or it would store a truncated CIR under the repo-wide key. C3-94 moved that
+    rule into the cache itself — a bounded run now keys on its own analysed set —
+    so the bounded case is cached too instead of paying for the parse every time,
+    and this function is the thin alias of the one authority it left behind.
     """
-    from sourcecode.context_graph import ContextGraph
+    from sourcecode.context_cache import shared_cir as _shared_cir
 
-    repo_root = _repo_root_of(root)
-    if repo_root != root:
-        return ContextGraph.build(files, root).cir
-    from sourcecode.context_cache import get_or_build_cir
-
-    cir, _lookup = get_or_build_cir(repo_root, root, files)
-    return cir
+    return _shared_cir(root, files)
 
 
 def _posture(

{sourcecode-4.17.0 → sourcecode-4.18.0}/src/sourcecode/risk.py

@@ -150,10 +150,30 @@ _URL_PATTERN_RE = re.compile(
     re.IGNORECASE,
 )
 _HTTP_INPUT_ANNOTATION_RE = re.compile(r"@(RequestParam|PathVariable|RequestBody)\b")
+#: C3-96. Three of this pattern's groups used to let the same whitespace be
+#: consumed in more than one place — `(?:\s*@…\s*)*`, `\s*(?:public|…)?\s*`, and
+#: `[\w<>\[\].?,\s]+\s+`, whose character class contains the `\s` the following
+#: `\s+` also matches. Each run of whitespace can then be split between the two in
+#: many ways, and on text that never completes a signature the engine tries them
+#: all: `_java_methods` runs this over **every** source, and a repository-wide
+#: `risk` on a 2 985-file repository did not finish in 20 minutes — inside the C
+#: regex engine, where no signal, budget or Ctrl-C can reach it (C3-87's deadline
+#: is checked between stages, and this never returns to one).
+#:
+#: Rewritten so every separator is consumed once: each modifier takes its own
+#: trailing whitespace, and the return type is tokens joined by explicit
+#: separators instead of one class that contains the separator too.
+#:
+#: The **same** language, deliberately, including the part that reads like a bug:
+#: the old class matched whitespace alone, so a bare `if (cond) {` was admitted as
+#: a method named `if`. Those pseudo-methods carry propagation through control-flow
+#: blocks in the walk below, so dropping them is a change to what `risk` finds, not
+#: a speed-up — which is why the type stays optional here and the question of
+#: whether it should is left to its own increment, with its own field measurement.
 _JAVA_METHOD_RE = re.compile(
-    r"(?P<ann>(?:\s*@[\w.]+(?:\([^;{}]*?\))?\s*)*)"
-    r"(?P<sig>\s*(?:public|protected|private)?\s*(?:static\s+)?"
-    r"[\w<>\[\].?,\s]+\s+(?P<name>[A-Za-z_$][\w$]*)\s*"
+    r"(?P<ann>(?:@[\w.]+(?:\([^;{}]*?\))?\s*)*)"
+    r"(?P<sig>(?:(?:public|protected|private)\s+)?(?:static\s+)?"
+    r"(?:[\w<>\[\].?,]+(?:\s+[\w<>\[\].?,]+)*\s+|\s{2,})(?P<name>[A-Za-z_$][\w$]*)\s*"
     r"\((?P<params>[^)]*)\)\s*)\{",
     re.MULTILINE,
 )
@@ -797,7 +817,7 @@ class RiskComposer:
         profiles: "Optional[set[str]]" = None,
         progress: "Optional[Callable[..., Any]]" = None,
     ) -> None:
-        from sourcecode.canonical_ir import build_canonical_ir
+        from sourcecode.context_cache import shared_cir
         from sourcecode.repository_ir import extract_java_endpoints, find_java_files
         from sourcecode.security_posture import (
             endpoint_security_surface,
@@ -808,8 +828,11 @@ class RiskComposer:
         from sourcecode.spring_tx_analyzer import run_tx_audit
 
         self.root = Path(root).resolve()
-        self.cir = cir if cir is not None else build_canonical_ir(
-            find_java_files(self.root), self.root
+        # The parse is ~80 % of this command's wall clock (measured: 12,45 s of
+        # 15,64 s on a 1 303-file repository) and it is the same parse `posture`,
+        # `explain` and `cache warm` already share — so it is fetched, not rebuilt.
+        self.cir = cir if cir is not None else shared_cir(
+            self.root, find_java_files(self.root)
         )
         self.model = SpringSemanticModel.build(self.cir)
 

{sourcecode-4.17.0 → sourcecode-4.18.0}/src/sourcecode/security_config_scan.py

@@ -249,14 +249,10 @@ def _line_of(source: str, index: int) -> int:
 
 
 def _enclosing_type(source: str, offset: int, fallback: str) -> str:
-    name = fallback
-    for m in re.finditer(
-        r"^[ \t]*(?:public|final|abstract|static|\s)*\s*(?:class|interface|enum)\s+(?P<n>\w+)",
-        source[:offset],
-        re.MULTILINE,
-    ):
-        name = m.group("n")
-    return name
+    """Thin alias of the one authority (C3-95) — see `source_text.enclosing_type`."""
+    from sourcecode.source_text import enclosing_type
+
+    return enclosing_type(source, offset, fallback)
 
 
 def _scan_java(source: str, rel: str) -> "list[SecurityConfigObservation]":

{sourcecode-4.17.0 → sourcecode-4.18.0}/src/sourcecode/source_text.py

@@ -30,6 +30,7 @@ other.
 from __future__ import annotations
 
 import re
+from typing import Optional
 
 #: Java/C-family lexical tokens, in precedence order. String and character
 #: literals are matched **first** so that a `//` or `/*` living inside one — as in
@@ -84,6 +85,70 @@ def blank_hash_comments(source: str) -> str:
     return _HASH_COMMENT_LINE.sub(lambda m: _blank(m.group(0)), source)
 
 
+#: The one authority for "a type is declared here", used by every scanner that has
+#: to name the type enclosing a match it found in raw text.
+#:
+#: C3-95. Two modules kept their own copy, and both were written as
+#: ``(?:public|final|abstract|static|\s)*\s*`` — a whitespace branch inside a
+#: starred group followed by another starred whitespace group. Every run of spaces
+#: can then be split between the two in exponentially many ways, and on a line that
+#: never reaches `class` the engine tries them all before failing: measured at
+#: 13 ms for 200 leading spaces, 1,17 s for 800 and **10,1 s for 1 600** — one line,
+#: one file. A generated or reformatted source is enough to hang a scan that is
+#: supposed to take seconds, and `spring-audit` and `risk` both run this scan.
+#:
+#: Written so each modifier must consume its own trailing whitespace, the group is
+#: unambiguous and the match is linear. It accepts the same declarations: the
+#: modifier list is wider than the original (which silently rejected
+#: `private`/`protected`/`sealed`), and the separator is still any whitespace, so a
+#: modifier on its own line still binds to the declaration below it.
+JAVA_TYPE_DECLARATION = re.compile(
+    r"^[ \t]*"
+    r"(?:(?:public|protected|private|final|abstract|static|sealed|non-sealed)\s+)*"
+    r"(?:class|interface|enum|record)\s+(?P<name>\w+)",
+    re.MULTILINE,
+)
+
+
+def type_declarations(source: str) -> "list[tuple[int, str]]":
+    """``(offset, name)`` of every type declared in *source*, in source order."""
+    return [(m.start(), m.group("name")) for m in JAVA_TYPE_DECLARATION.finditer(source)]
+
+
+def enclosing_type(source: str, offset: int, fallback: str = "") -> str:
+    """Name of the type declared closest above *offset*, else *fallback*.
+
+    Nested types resolve to the nearest enclosing declaration, which is the one a
+    reader would name. Callers ask this once per observation and a file can carry
+    many, so the scan of a given source is memoised: the previous shape sliced
+    ``source[:offset]`` and re-scanned it per call, which is a copy and a walk of
+    the whole prefix for every finding in the file.
+
+    At the boundary the two prior copies disagreed, and this one keeps
+    ``identity_fallback``'s rule: the nearest declaration **at or above** the
+    offset. Slicing the prefix dropped a declaration that straddled the offset, so
+    a match on the declaration's own line was attributed to the type above it or to
+    the fallback. Every real observation sits strictly after its declaration, which
+    is why the field results are unchanged either way.
+    """
+    global _DECL_MEMO
+    memo_key = (len(source), hash(source))
+    if _DECL_MEMO is None or _DECL_MEMO[0] != memo_key:
+        _DECL_MEMO = (memo_key, type_declarations(source))
+    name = fallback
+    for start, declared in _DECL_MEMO[1]:
+        if start > offset:
+            break
+        name = declared
+    return name
+
+
+#: One entry: callers sweep a file's findings together, so the next question is
+#: almost always about the same source. Holding one keeps the memo from becoming a
+#: second copy of every file the process ever read.
+_DECL_MEMO: "Optional[tuple[tuple[int, int], list[tuple[int, str]]]]" = None
+
+
 def commented_spans(source: str, *, xml: bool) -> "list[tuple[int, int]]":
     """`(start, end)` offsets of every comment — what was switched off, not what runs.