sourcecode 3.0.0__tar.gz → 3.1.0__tar.gz

{sourcecode-3.0.0 → sourcecode-3.1.0}/CHANGELOG.md

@@ -1,5 +1,90 @@
 # Changelog
 
+## [3.1.0] — 2026-07-28
+
+**Posture answers about requests, not only about beans.** Milestone M4 of the strategic
+roadmap: the conditional-resolution kernel now decides `@ConditionalOnProperty` from the
+repository's own configuration, and the request chain a profile set activates is read down
+to per-endpoint access — with the rule that decided each endpoint cited by file and line.
+Plus the field-defect queue: a fully-qualified annotation was invisible to the whole IR,
+`@Bean` bodies were skipped by every body scan, the custom-gate label disagreed across
+three surfaces, the parse cache served pre-fix parses, and `migrate-check` emitted 900KB
+to stdout.
+
+### Added
+
+- **`posture` resolves `@ConditionalOnProperty`** against the properties the repository's
+  own configuration sets under the same profile set — `application.yml` /
+  `application.properties`, the `application-{profile}` filename convention, and
+  multi-document `spring.config.activate.on-profile`. A profile-activated document
+  outranks an unconditional one. Previously every property condition was reported
+  unresolved, which on a property-driven repository was most of the answer.
+- **`posture --property key=value`** (repeatable) states a deployment value the
+  repository's files do not carry; it outranks every file. Measured on jobrunr's Spring
+  Boot starter: `--property jobrunr.database.type=mem` turns 4 undecided storage
+  auto-configurations into 1 active and 3 inactive, each citing the value that decided it.
+- **`properties` block in the payload** — which configuration files were read, how many
+  keys resolved, which keys nobody could decide, and which values the caller supplied.
+- **`posture` resolves what the active filter chain permits, per endpoint.** The
+  authorization DSL of the chain configuration a profile set activates
+  (`requestMatchers` / `antMatchers` / `mvcMatchers` / `anyRequest` and the access method
+  that decides them) is read in declaration order, and each endpoint is resolved against
+  the first rule that matches it — `endpoints.effective_access`, with the deciding rule's
+  file and line cited for every stated endpoint. HTTP methods on a rule are honoured.
+- **`posture --diff` states the endpoint-level security delta** (`endpoint_access`): the
+  requests two profile sets decide differently, with the count that require no
+  authentication on one side and do on the other. Bean-level movement was the previous
+  answer; this is the one a reviewer acts on.
+
+### Fixed
+
+- **A fully-qualified annotation is the same annotation.** `@a.b.Foo` and `@Foo` are one
+  annotation to the compiler, but the IR stored the qualified token and matched a
+  simple-name vocabulary against it. A controller written as
+  `@org.springframework.web.bind.annotation.RestController` produced **zero endpoints**,
+  and a handler guarded with `@jakarta.annotation.security.RolesAllowed` read as carrying
+  no guard — which an endpoint-security contract then reported as a violation on a
+  guarded endpoint. Found by field-testing `require_endpoint_security` on
+  spring-petclinic. A/B on six battery repos: endpoint and security counts unchanged, so
+  this recovers a blind spot without widening any claim.
+- **The parse cache keys on the analyzer, not only on the file.** It was described as
+  content-addressed and never stale, but the content it addressed was the source file
+  alone: after any change to symbol extraction, an updated install kept serving pre-fix
+  parses for every unchanged file, so a shipped fix read as inert until the cache was
+  cleared by hand — exactly the failure the whole-CIR cache was fixed for. The key now
+  carries `analyzer_fingerprint()`.
+- **`migrate-check` guards its output size**, the way `repo-ir` already did. A default
+  run emitted 909KB on openmrs and 702KB on keycloak (~227K and ~175K tokens) straight to
+  stdout — past every context window it is meant to be pasted into, and only discovered
+  after the wait. Over ~50K estimated tokens it now stops with `OUTPUT_TOO_LARGE` naming
+  the four ways out (`--compact`, `--min-severity high`, `--output`, `--force`), and warns
+  from ~10K. Writing to a file is exempt; `--compact` on openmrs is 23KB.
+- **The custom-gate label agrees across every surface.** A repository whose authorization
+  runs through its own annotation read `custom_annotation_based` from `endpoints`,
+  `unknown` from `spring-audit`, and `evidence_absent` from `retrieve endpoint-security`
+  — same repo, same evidence, three answers. The gate predicate was applied to the
+  `endpoints` surface only; the assembled surface every CIR consumer reads never saw it,
+  so those endpoints arrived carrying no security policy at all. It is now applied once,
+  at the seam all surfaces share, and the inferred gate is named in
+  `security_model_detail.custom_spi_detected`. Measured on the battery: no repository's
+  model changed — the declared-in-repo discriminator still rejects library annotations.
+- **`@Bean` method bodies are scanned like any other body.** `@Bean` classifies a symbol
+  as `bean` rather than `method`, and every body-level scan — literal facts, body facts,
+  guard clauses, intra-class call edges — filtered on `method`. A configuration class's
+  own body was therefore invisible, which is precisely where datasource URLs, directory
+  URIs and client base paths are written. Measured on a clean cache: spring-petclinic
+  recovered 67 → 128 literal atoms across 23 → 36 owners; jobrunr gained 20 body-fact
+  owners. A `@Bean` method is also a call target now (a configuration wiring one bean
+  from another calls it by name).
+- **Conditions are ANDed the way Spring ANDs them.** A bean excluded by its `@Profile` is
+  now `inactive` even when another condition on it is undecided; it was reported
+  unresolved, which hid a bean that provably does not register.
+
+Unresolved stays first-class: a key no configuration source sets, a `${…}` placeholder,
+two documents disagreeing at the same precedence, and arguments the parser does not read
+are each reported unresolved with the key named — `matchIfMissing` is *reported*, never
+applied, because a key absent from the repository is not a key absent from the deployment.
+
 ## [3.0.0] — 2026-07-28
 
 **One answer per question, a contract around every answer, and a gate that can be

{sourcecode-3.0.0 → sourcecode-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 3.0.0
+Version: 3.1.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

{sourcecode-3.0.0 → sourcecode-3.1.0}/pyproject.toml

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

{sourcecode-3.0.0 → sourcecode-3.1.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__ = "3.0.0"
+__version__ = "3.1.0"

sourcecode-3.1.0/src/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-3.0.0 → sourcecode-3.1.0}/src/sourcecode/cli.py

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

{sourcecode-3.0.0 → sourcecode-3.1.0}/src/sourcecode/parse_cache.py

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