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

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/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)

sourcecode/spring_profiles.py

@@ -153,18 +153,58 @@ _TYPE_AFTER_ANN_RE = re.compile(
     r"\b(?:class|interface|enum|record)\s+(?P<name>[A-Za-z_$][\w$]*)"
 )
 
+# What may stand between `@Profile(...)` and the type declaration it annotates:
+# further annotations and modifiers, nothing else. Anything beyond this means
+# the annotation belongs to a member, not to the type.
+_ANNOTATED_TYPE_RE = re.compile(
+    r"\A(?:\s|//[^\n]*\n|/\*.*?\*/"
+    r"|@[\w.]+(?:\s*\((?:[^()]|\([^()]*\))*\))?"
+    r"|public|protected|private|static|final|abstract|strictfp|sealed|non-sealed)*"
+    r"\s*(?:class|interface|enum|record)\s+(?P<name>[A-Za-z_$][\w$]*)",
+    re.DOTALL,
+)
 
-def conditional_beans_from_sources(
+# The member an annotation sits on, when it is not a type: the declared name of
+# the next method or field.
+_MEMBER_AFTER_ANN_RE = re.compile(
+    r"\A(?:\s|//[^\n]*\n|/\*.*?\*/"
+    r"|@[\w.]+(?:\s*\((?:[^()]|\([^()]*\))*\))?"
+    r"|public|protected|private|static|final|abstract|synchronized|native|transient|volatile|default"
+    r"|<[^<>]*>|[\w.$]+(?:\s*<[^<>]*>)?(?:\s*\[\s*\])*)*?"
+    r"\s(?P<name>[A-Za-z_$][\w$]*)\s*[(=;]",
+    re.DOTALL,
+)
+
+
+def _enclosing_type_name(text: str, pos: int, fallback: str) -> str:
+    """Name of the type declaration that encloses ``pos``."""
+    last = None
+    for m in _TYPE_AFTER_ANN_RE.finditer(text, 0, pos):
+        last = m
+    return last.group("name") if last else fallback
+
+
+def conditional_beans_from_sources_detailed(
     root: Path, file_paths: "Optional[list[str]]" = None
-) -> "dict[str, list[str]]":
-    """`{profile: [TypeName, …]}` for types carrying `@Profile`.
+) -> "list[ProfileConditionalBean]":
+    """`@Profile` symbols and the expression each one declares, from sources.
+
+    The single derivation of this fact for callers that hold no CIR;
+    :func:`profile_conditional_beans` is the same fact read from the IR, and
+    both must agree — a symbol this reports under a profile must be a symbol
+    `posture` resolves the same way.
 
-    Which beans a profile switches is the fact worth reporting — a profile list
-    alone does not tell a reader that one profile swaps the security filter
-    chain. Used where no CIR is in scope; `profile_conditional_beans` is the
-    exact, IR-based version.
+    **Attribution rule (the defect this exists to prevent):** a `@Profile` is
+    attributed to the declaration it actually annotates. Only annotations and
+    modifiers may stand between it and a type declaration; anything else means
+    the annotation sits on a member, which is then reported as ``Type#member``.
+    The previous scan searched for the *next* type declaration anywhere ahead
+    and fell back to the file name, so a `@Profile("m3")` on a `@Bean` method
+    inside `DevSecurityConfig` was reported as `DevSecurityConfig` being
+    conditional on `m3` — the exact opposite of its class-level
+    `@Profile("!m3")`, in the same document, contradicting `posture`.
     """
-    out: dict[str, set[str]] = {}
+    beans: list[ProfileConditionalBean] = []
     try:
         paths = (
             [Path(root) / p for p in file_paths if p.endswith(".java")]
@@ -172,7 +212,7 @@ def conditional_beans_from_sources(
             else list(Path(root).rglob("*.java"))
         )
     except Exception:
-        return {}
+        return []
     for path in paths[:20000]:
         try:
             text = path.read_text(encoding="utf-8", errors="ignore")
@@ -180,11 +220,51 @@ def conditional_beans_from_sources(
             continue
         if "@Profile" not in text:
             continue
+        try:
+            rel = str(path.relative_to(Path(root)))
+        except Exception:
+            rel = str(path)
         for match in _PROFILE_ANN_RE.finditer(text):
-            type_match = _TYPE_AFTER_ANN_RE.search(text, match.end())
-            name = type_match.group("name") if type_match else path.stem
-            for token in _split_profile_expression(match.group("args")):
-                out.setdefault(token.strip(), set()).add(name)
+            tail = text[match.end():match.end() + 4000]
+            type_match = _ANNOTATED_TYPE_RE.match(tail)
+            if type_match:
+                symbol = type_match.group("name")
+            else:
+                member_match = _MEMBER_AFTER_ANN_RE.match(tail)
+                if not member_match:
+                    # Neither a type nor a readable member: report nothing
+                    # rather than attribute the annotation to a guess.
+                    continue
+                owner = _enclosing_type_name(text, match.start(), path.stem)
+                symbol = f"{owner}#{member_match.group('name')}"
+            args = match.group("args")
+            names = _split_profile_expression(args)
+            if not names:
+                continue
+            beans.append(ProfileConditionalBean(
+                symbol=symbol,
+                profiles=tuple(names),
+                source_file=rel,
+                expression=args.strip(),
+            ))
+    beans.sort(key=lambda b: (b.symbol, b.profiles))
+    return beans
+
+
+def conditional_beans_from_sources(
+    root: Path, file_paths: "Optional[list[str]]" = None
+) -> "dict[str, list[str]]":
+    """`{profile: [symbol, …]}` — a projection of
+    :func:`conditional_beans_from_sources_detailed`.
+
+    Kept as the map shape published in the signals payload. It loses the
+    operators (`"a & !b"` appears under `a` and under `!b`), which is why the
+    detailed list carries `expression` and is what a reader should consume.
+    """
+    out: dict[str, set[str]] = {}
+    for bean in conditional_beans_from_sources_detailed(root, file_paths):
+        for token in bean.profiles:
+            out.setdefault(token.strip(), set()).add(bean.symbol)
     return {profile: sorted(names) for profile, names in sorted(out.items())}