sourcecode 3.2.0__py3-none-any.whl → 3.2.2__py3-none-any.whl

sourcecode/prepare_context.py

@@ -1090,20 +1090,20 @@ class TaskContextBuilder:
     def _try_ris_fast_path(self, task_name: str, spec: "TaskSpec") -> Optional[TaskOutput]:
         """Return TaskOutput from a warm RIS without running the full scan.
 
-        Only activated for onboard/explain when git HEAD matches stored RIS.
+        Only activated for onboard/explain when the stored RIS describes the tree
+        on disk — the same freshness authority every cache layer keys on, not the
+        committed HEAD (which served this fast path through uncommitted edits).
         Falls through (returns None) on any error or cache miss.
         """
         try:
-            import subprocess as _sp
             from sourcecode.ris import load_ris as _lris
+            from sourcecode.ris import _tree_signature as _ris_sig
             _ris = _lris(self.root)
             if _ris is None or not _ris.compact_summary:
                 return None
-            _r = _sp.run(
-                ["git", "-C", str(self.root), "rev-parse", "--short", "HEAD"],
-                capture_output=True, text=True, timeout=2,
-            )
-            if _r.returncode != 0 or _r.stdout.strip() != _ris.git_head:
+            _stored_sig = (_ris.metadata or {}).get("tree_signature") or ""
+            _current_sig = _ris_sig(self.root)
+            if not _stored_sig or not _current_sig or _stored_sig != _current_sig:
                 return None
 
             compact = _ris.compact_summary
@@ -1905,17 +1905,46 @@ class TaskContextBuilder:
                 for p in test_set
             } | {Path(p).stem for p in test_set}
             _untested_changed = [f for f in _changed_src if Path(f).stem not in _test_stems]
-            _test_risk_level = (
-                "high" if len(_untested_changed) > 3
-                else "medium" if _untested_changed
-                else "low"
-            )
+            # A diff that changes no source file has not been assessed for test
+            # coverage — it is not low risk. Reported as `low`, a documentation-only
+            # diff in a repository with no tests at all read as "covered", which is
+            # the traffic light inverted where a reviewer relies on it (ADR-0008 R9:
+            # `unknown` where the honest answer is unknown, never a manufactured
+            # best case).
+            if not _changed_src:
+                _test_risk_level = "unknown"
+                _test_risk_basis = (
+                    "no source files changed in this diff — test coverage risk "
+                    "not assessed"
+                )
+            else:
+                _test_risk_level = (
+                    "high" if len(_untested_changed) > 3
+                    else "medium" if _untested_changed
+                    else "low"
+                )
+                _test_risk_basis = (
+                    f"{len(_untested_changed)} of {len(_changed_src)} changed source "
+                    f"files have no matching test file by stem"
+                )
             _pr_test_coverage_risk = {
                 "changed_files_without_tests": _untested_changed[:10],
                 "risk_level": _test_risk_level,
                 "epistemic_level": "INFERRED (LOW CONFIDENCE)",
-                "basis": f"{len(_untested_changed)} changed source files have no matching test file by stem",
+                "basis": _test_risk_basis,
+                "changed_source_files": len(_changed_src),
             }
+            if not test_set:
+                # The repository declares no test sources at all: "has a matching
+                # test file by stem" cannot mean anything here, and a `low` would
+                # be read as coverage.
+                _pr_test_coverage_risk["repository_has_test_sources"] = False
+                if _test_risk_level == "low":
+                    _pr_test_coverage_risk["risk_level"] = "unknown"
+                    _pr_test_coverage_risk["basis"] = (
+                        "repository declares no test sources — coverage of the "
+                        "changed files cannot be assessed"
+                    )
 
             # Pre-classify changed files once — reused for hotspots, order, and runtime/build split
             _pr_changed_cls: dict[str, dict] = {
@@ -3331,19 +3360,15 @@ class TaskContextBuilder:
             return [f for _, _, f in scored[:15]]
 
     def _is_test(self, path: str) -> bool:
-        name = Path(path).name.lower()
-        return (
-            name.startswith("test_")
-            or name.endswith("_test.py")
-            or name.endswith(".test.ts")
-            or name.endswith(".spec.ts")
-            or "/tests/" in path
-            or "/test/" in path
-            or "/spec/" in path
-            or (name.endswith("test.java") and name != "test.java")
-            or name.endswith("tests.java")
-            or (name.startswith("test") and name.endswith(".java") and len(name) > 9)
-        )
+        """Delegates to the one authority (ADR-0008 R1).
+
+        This used to match `/test/` anywhere in the path, so production code in
+        a package named `test` under `src/main` counted as a test — inflating
+        coverage in the one direction a reviewer must not be misled about.
+        """
+        from sourcecode.test_sources import is_test_path
+
+        return is_test_path(path)
 
     def _is_source(self, path: str) -> bool:
         return Path(path).suffix.lower() in _SOURCE_EXTENSIONS

sourcecode/reference_facts.py

@@ -0,0 +1,307 @@
+"""reference_facts.py — one authority for "is this type referenced anywhere?".
+
+A static call-graph answers "who calls this class" for the calls it can see. It
+cannot see a class a framework instantiates by reflection, wires by name from
+XML, discovers through the service-loader, or dispatches into because of an
+annotation. Those are not edge cases in a Spring/Jakarta repository: they are how
+the entry points work.
+
+So this question has **three** answers, not two:
+
+  * ``referenced``                   — the graph carries an incoming edge, or
+                                       another source file names the type
+  * ``unknown_framework_dispatch``   — no static caller, but the type carries a
+                                       dispatch signal (published annotation,
+                                       entry-point signature, or its name wired
+                                       from a configuration file). Whether it runs
+                                       is not decidable here
+  * ``no_static_callers``            — no incoming edge and no dispatch signal
+                                       found. Still **not** "dead code": it is the
+                                       absence of evidence, stated as such
+
+The previous shape of this fact had two consequences the field caught. It counted
+only types with **no edges in either direction**, while calling the result "zero
+static callers" — a class that calls something but is called by nothing was never
+examined. And when nothing survived that narrower filter it published ``0``, which
+reads as "there is no unreferenced code here" rather than "nothing was found by a
+check that cannot see framework dispatch" (ADR-0008 R9, R5-R8: the count comes
+from the measurement, never from the length of a truncated list).
+
+VAI: annotation and configuration names appear only as published open-standard
+DATA (Jakarta / Spring / Java SE vocabulary), the same class of table as the
+security-posture matchers. Nothing branches on a project, vendor or product name,
+and a name found in configuration is recorded as evidence of a possible wire —
+never as proof that a class is alive.
+"""
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+#: Statuses, in the order a reader cares about them. `unknown_framework_dispatch`
+#: sits between the two decided answers because that is what it means.
+REFERENCED = "referenced"
+UNKNOWN_DISPATCH = "unknown_framework_dispatch"
+NO_STATIC_CALLERS = "no_static_callers"
+STATUSES: tuple[str, ...] = (REFERENCED, UNKNOWN_DISPATCH, NO_STATIC_CALLERS)
+
+#: Published signatures and annotations that mean "a framework calls this, not
+#: your code". DATA: a table of open-standard names, extended without changing
+#: any logic. A hit makes the answer *unknown*, never "alive".
+_DYNAMIC_ENTRY_SIGNATURE_RE = re.compile(
+    r"\(\s*DispatchContext\b"                        # service-engine service
+    r"|HttpServletRequest\s+\w+\s*,\s*HttpServletResponse"  # event / servlet handler
+    r"|\bpublic\s+static\s+void\s+main\s*\("         # JVM entry point
+    r"|@(?:Scheduled|PostConstruct|PreDestroy|EventListener|Bean|"
+    r"RequestMapping|GetMapping|PostMapping|PutMapping|DeleteMapping|PatchMapping|"
+    r"Path|GET|POST|Provider|ApplicationScoped|Singleton|"
+    # Stereotypes and persistence: the container instantiates these itself, so a
+    # static call-graph is the wrong instrument to declare them unused.
+    r"Component|Service|Repository|Controller|RestController|ControllerAdvice|"
+    r"Configuration|SpringBootApplication|Aspect|Entity|Embeddable|"
+    r"MappedSuperclass|Converter|WebServlet|WebFilter|WebListener)\b"
+)
+
+#: Configuration formats where a framework wires a class by name.
+_CONFIG_REF_EXTS: frozenset = frozenset({".xml", ".properties", ".yml", ".yaml", ".groovy"})
+_SKIP_DIRS: frozenset = frozenset({".git", "build", "out", "target", "node_modules", ".gradle"})
+_SCAN_MAX_FILES: int = 12000
+_SCAN_MAX_BYTES: int = 256 * 1024
+
+
+@dataclass(frozen=True)
+class TypeReference:
+    """One type's reference status, with the evidence that produced it."""
+
+    fqn: str
+    status: str
+    basis: str
+    type: str = ""
+    role: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "fqn": self.fqn,
+            "type": self.type,
+            "role": self.role,
+            "status": self.status,
+            "basis": self.basis,
+        }
+
+
+@dataclass(frozen=True)
+class ReferenceFacts:
+    """Every type examined, partitioned into the three answers.
+
+    `by_status` sums to `classes_examined` — the partition is the point. Counts
+    are computed here, so no consumer can derive one from a list it truncated
+    for display.
+    """
+
+    classes_examined: int = 0
+    by_status: "dict[str, int]" = field(default_factory=dict)
+    entries: "tuple[TypeReference, ...]" = ()
+
+    def of_status(self, status: str) -> "list[TypeReference]":
+        return [e for e in self.entries if e.status == status]
+
+    def count(self, status: str) -> int:
+        return int(self.by_status.get(status, 0))
+
+    @property
+    def statement(self) -> str:
+        """What the numbers mean, in the words that keep them honest."""
+        unknown = self.count(UNKNOWN_DISPATCH)
+        none_found = self.count(NO_STATIC_CALLERS)
+        if not self.classes_examined:
+            return "no class or interface declarations were examined"
+        if none_found == 0 and unknown:
+            return (
+                f"no type is without a caller AND without a dispatch signal; "
+                f"{unknown} type(s) have no static caller but carry one, so whether "
+                "they are reachable is not decidable from source"
+            )
+        return (
+            f"{none_found} type(s) have no static caller and no dispatch signal "
+            f"found; {unknown} more have no static caller but carry one. Neither "
+            "group is confirmed dead code"
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "classes_examined": self.classes_examined,
+            **{s: self.count(s) for s in STATUSES},
+            "statement": self.statement,
+            "note": (
+                "A partition of every class/interface declaration: the three counts "
+                "sum to classes_examined. `no_static_callers` means no incoming edge "
+                "and no dispatch signal was found — absence of evidence, not evidence "
+                "of dead code. `unknown_framework_dispatch` means a framework may "
+                "invoke it (annotation, entry-point signature, or a name wired from "
+                "configuration) and a static call-graph cannot decide."
+            ),
+        }
+
+
+def _read(path: str, limit: int = _SCAN_MAX_BYTES) -> str:
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as handle:
+            return handle.read(limit)
+    except OSError:
+        return ""
+
+
+#: Identifiers, and `Outer.Nested` qualified references. Two fixed patterns whose
+#: hits are intersected with the candidate names — an alternation over the
+#: candidates instead is 7× slower on a 6 000-type repository and answers the same.
+_IDENTIFIER_RE = re.compile(r"[A-Za-z_$][A-Za-z0-9_$]*")
+_QUALIFIED_TYPE_RE = re.compile(r"\b[A-Z][A-Za-z0-9_$]*\.[A-Z][A-Za-z0-9_$]*")
+
+
+def _scan_repository(
+    root: Path, simple_names: "set[str]", nested: "dict[str, tuple[str, str]]"
+) -> "tuple[dict[str, str], dict[str, str]]":
+    """One walk, two questions — `(config-wired names, nested types other code names)`.
+
+    Both scans need the whole tree, and walking it twice doubled the cost of the
+    command's slowest step for no answer that a single pass cannot give.
+
+    Names are matched whole-word, never as substrings: `Order` appearing inside
+    `OrderItemImpl` is not a wire, and treating it as one silently marks a
+    live-looking class dispatched. A type naming itself proves nothing, so its own
+    source file is skipped.
+    """
+    config_hits: dict[str, str] = {}
+    nested_hits: dict[str, str] = {}
+    pending = set(simple_names)
+    by_qualified: dict[str, list[str]] = {}
+    for fqn, (qualified, _own) in nested.items():
+        by_qualified.setdefault(qualified, []).append(fqn)
+
+    scan_config = bool(pending)
+    scan_java = bool(by_qualified)
+    if not scan_config and not scan_java:
+        return config_hits, nested_hits
+
+    scanned = 0
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in _SKIP_DIRS]
+        for filename in filenames:
+            is_java = filename.endswith(".java")
+            is_config = os.path.splitext(filename)[1].lower() in _CONFIG_REF_EXTS
+            if not ((is_java and scan_java) or (is_config and scan_config)):
+                continue
+            if scanned >= _SCAN_MAX_FILES:
+                break
+            full = os.path.join(dirpath, filename)
+            text = _read(full)
+            scanned += 1
+            if not text:
+                continue
+            rel = os.path.relpath(full, root).replace("\\", "/")
+            if is_config and scan_config:
+                for hit in set(_IDENTIFIER_RE.findall(text)) & pending:
+                    pending.discard(hit)
+                    config_hits[hit] = rel
+                scan_config = bool(pending)
+            if is_java and scan_java:
+                for hit in set(_QUALIFIED_TYPE_RE.findall(text)) & set(by_qualified):
+                    for fqn in by_qualified[hit]:
+                        if fqn not in nested_hits and nested[fqn][1] != rel:
+                            nested_hits[fqn] = rel
+                scan_java = len(nested_hits) < len(nested)
+            if not scan_config and not scan_java:
+                return config_hits, nested_hits
+        if scanned >= _SCAN_MAX_FILES:
+            break
+    return config_hits, nested_hits
+
+
+def analyze_type_references(nodes: "list[dict]", root: Path) -> ReferenceFacts:
+    """The reference status of every class/interface node, and why.
+
+    `nodes` is the graph's node list; only class and interface declarations are
+    examined, because a method with no callers is a different question.
+    """
+    root = Path(root)
+    types = [n for n in nodes or [] if n.get("type") in ("class", "interface") and n.get("fqn")]
+    if not types:
+        return ReferenceFacts(0, {s: 0 for s in STATUSES}, ())
+
+    entries: list[TypeReference] = []
+    candidates: list[dict] = []
+    for node in types:
+        if int(node.get("in_degree") or 0) > 0:
+            entries.append(TypeReference(
+                fqn=str(node["fqn"]), status=REFERENCED,
+                basis="incoming edge in the call-graph",
+                type=str(node.get("type") or ""), role=str(node.get("role") or "other"),
+            ))
+        else:
+            candidates.append(node)
+
+    # 1. A dispatch signal in the type's own source.
+    dispatch_basis: dict[str, str] = {}
+    for node in candidates:
+        source = node.get("source_file")
+        if not source:
+            continue
+        text = _read(str(root / str(source)))
+        if text and _DYNAMIC_ENTRY_SIGNATURE_RE.search(text):
+            dispatch_basis[str(node["fqn"])] = (
+                f"a framework-dispatch annotation or entry-point signature in {source}"
+            )
+
+    # 2. The type's name wired from a configuration file, and 3. a nested type
+    #    another source names as `Outer.Nested` — both answered in one walk.
+    by_simple: dict[str, list[dict]] = {}
+    nested_candidates: dict[str, tuple[str, str]] = {}
+    for node in candidates:
+        fqn = str(node["fqn"])
+        if fqn in dispatch_basis:
+            continue
+        simple = fqn.rsplit(".", 1)[-1]
+        if simple:
+            by_simple.setdefault(simple, []).append(node)
+        parts = fqn.split(".")
+        if len(parts) >= 2 and parts[-2][:1].isupper():
+            nested_candidates[fqn] = (
+                f"{parts[-2]}.{parts[-1]}",
+                str(node.get("source_file") or "").replace("\\", "/"),
+            )
+    config_hits, nested_hits = _scan_repository(root, set(by_simple), nested_candidates)
+    for simple, config_file in config_hits.items():
+        for node in by_simple.get(simple, []):
+            dispatch_basis[str(node["fqn"])] = f"named in {config_file}"
+
+    for node in candidates:
+        fqn = str(node["fqn"])
+        common = {
+            "fqn": fqn,
+            "type": str(node.get("type") or ""),
+            "role": str(node.get("role") or "other"),
+        }
+        if fqn in nested_hits:
+            entries.append(TypeReference(
+                status=REFERENCED,
+                basis=f"named as a qualified nested type in {nested_hits[fqn]}",
+                **common,
+            ))
+        elif fqn in dispatch_basis:
+            entries.append(TypeReference(
+                status=UNKNOWN_DISPATCH, basis=dispatch_basis[fqn], **common,
+            ))
+        else:
+            entries.append(TypeReference(
+                status=NO_STATIC_CALLERS,
+                basis="no incoming edge, and no dispatch signal was found",
+                **common,
+            ))
+
+    entries.sort(key=lambda e: (STATUSES.index(e.status), e.fqn))
+    counts = {status: sum(1 for e in entries if e.status == status) for status in STATUSES}
+    return ReferenceFacts(
+        classes_examined=len(types), by_status=counts, entries=tuple(entries),
+    )

sourcecode/ris.py

@@ -258,6 +258,7 @@ def _build_from_core(
                 1.0 if agent_data else (0.5 if compact_data else 0.0)
             ),
             "partial": not bool(agent_data),
+            "tree_signature": _tree_signature(repo_root),
         },
     )
 
@@ -295,6 +296,7 @@ def maybe_update_ris(repo_root: Path, core_dict: dict, git_head: str) -> None:
                     "snapshot_source": "existing_snapshot_system",
                     "confidence": float(1.0 if agent_data else (0.5 if compact_data else 0.0)),
                     "partial": not bool(agent_data),
+                    "tree_signature": _tree_signature(repo_root),
                 },
             )
             save_ris(repo_root, updated)
@@ -433,6 +435,21 @@ def _current_git_head(repo_root: Path) -> str:
     return ""
 
 
+def _tree_signature(repo_root: Path) -> str:
+    """Tree state this snapshot describes — the one freshness authority.
+
+    Stored in ``metadata["tree_signature"]`` at write time so staleness compares
+    the tree the RIS was built from against the tree on disk now. HEAD alone
+    called a snapshot fresh while uncommitted edits made it describe nothing.
+    """
+    try:
+        from sourcecode.cache import worktree_signature
+
+        return worktree_signature(repo_root)
+    except Exception:
+        return ""
+
+
 def _has_uncommitted_changes(repo_root: Path) -> bool:
     """Return True if working tree has staged or unstaged changes to tracked files.
 
@@ -465,8 +482,17 @@ def get_cold_start_context(repo_root: Path) -> dict:
             return {"status": "no_ris"}
 
         current_head = _current_git_head(repo_root)
-        stale = bool(current_head and ris.git_head and current_head != ris.git_head)
         uncommitted = _has_uncommitted_changes(repo_root)
+        # Staleness is about the tree the snapshot describes, not the commit it was
+        # taken at: with HEAD alone a snapshot stayed `stale: false` through every
+        # uncommitted edit. Snapshots written before the signature existed fall back
+        # to the pair of facts that were available then.
+        _stored_sig = (ris.metadata or {}).get("tree_signature") or ""
+        _current_sig = _tree_signature(repo_root)
+        if _stored_sig and _current_sig:
+            stale = _stored_sig != _current_sig
+        else:
+            stale = bool(current_head and ris.git_head and current_head != ris.git_head) or uncommitted
 
         endpoints = ris.api_surface.get("endpoints", [])
         _is_java = (

sourcecode/serializer.py

@@ -564,19 +564,30 @@ def _spring_profiles_context(sm: "SourceMap") -> "Optional[dict[str, Any]]":
     # profile is routinely the security filter chain.
     _declared: list[str] = []
     _conditional: dict[str, list[str]] = {}
+    _conditional_beans: list[dict[str, Any]] = []
     _root = getattr(sm.metadata, "analyzed_path", None)
     if _root:
         try:
             from sourcecode.spring_profiles import (
-                conditional_beans_from_sources,
+                conditional_beans_from_sources_detailed,
                 profiles_from_config,
             )
 
-            # One source pass: the bean map's keys ARE the annotation-declared
-            # profile names, so there is no second scan for the name list.
-            _conditional = conditional_beans_from_sources(
+            # One source pass, one fact: every rendering below is a projection
+            # of this list, so the map cannot disagree with the expressions
+            # (ADR-0008 R1). The keys ARE the annotation-declared profile
+            # names, so there is no second scan for the name list either.
+            _beans = conditional_beans_from_sources_detailed(
                 Path(_root), list(sm.file_paths or [])
             )
+            _conditional_beans = [b.to_dict() for b in _beans]
+            _by_profile: dict[str, set[str]] = {}
+            for _bean in _beans:
+                for _token in _bean.profiles:
+                    _by_profile.setdefault(_token.strip(), set()).add(_bean.symbol)
+            _conditional = {
+                _p: sorted(_names) for _p, _names in sorted(_by_profile.items())
+            }
             _declared = sorted(set(
                 profiles_from_config(Path(_root))
                 + [p.lstrip("!").strip() for p in _conditional]
@@ -619,6 +630,19 @@ def _spring_profiles_context(sm: "SourceMap") -> "Optional[dict[str, Any]]":
         result["declared_in_code_or_config"] = _declared
         if _conditional:
             result["profile_conditional_beans"] = _conditional
+        if _conditional_beans:
+            # The map above buckets by token, so `@Profile("a & !b")` appears
+            # under both `a` and `!b` with the operator lost. This list keeps
+            # the expression as written — it is what `ask posture` resolves,
+            # and the only rendering here that can be read as a condition.
+            result["conditional_beans"] = _conditional_beans
+            result["conditional_beans_note"] = (
+                "Symbols carrying @Profile, with the expression as written. "
+                "A symbol listed under a token is conditional on that token as "
+                "written — '!m3' means active when m3 is ABSENT. Whether a bean "
+                "is actually wired under a given profile set is resolved by "
+                "`ask posture --profile <set>`, which is the authority."
+            )
         result["detection_basis"] = [
             "application-{profile} file naming",
             "spring.config.activate.on-profile / spring.profiles in config documents",
@@ -2211,11 +2235,14 @@ def agent_view(sm: SourceMap, *, full: bool = False) -> dict[str, Any]:
         if sm.code_notes_summary.adr_count > 0:
             signals["adrs"] = sm.code_notes_summary.adr_count
 
-    has_tests = any(
-        "/test" in p or "/tests" in p or "/spec" in p or p.startswith("test")
-        for p in sm.file_paths
-    )
-    if has_tests:
+    # One authority for "does this repository have tests" (ADR-0008 R1). The
+    # substring rule this replaces answered `true` for a repository whose
+    # production code lives in a package called `test`, contradicting the
+    # `analysis_gaps` block of the same document.
+    from sourcecode.test_sources import analyze_test_sources
+
+    _test_facts = analyze_test_sources(list(sm.file_paths or []))
+    if _test_facts.has_tests:
         signals["has_tests"] = True
 
     # Semantic hotspots (populated when --semantics was passed)