sourcecode 4.2.0__py3-none-any.whl → 4.3.0__py3-none-any.whl

sourcecode/data_labels.py

@@ -0,0 +1,200 @@
+"""data_labels.py — what the repository's owner says is sensitive, declared once.
+
+Nothing in Java says that `Person.dni` is a national identifier and `Person.id` is
+a surrogate key. A tool that guessed from the name would be guessing (and would be
+guessing in one language, about one naming convention, which is exactly the
+vendor-agnostic rule this product holds itself to: names are evidence, never the
+branch). So the label is **declared**, and everything downstream is measured.
+
+The declaration lives beside the other repository-specific semantics the analyzer
+accepts — `sourcecode.config.json`, next to `customSecurityAnnotations`::
+
+    {
+      "dataLabels": [
+        {
+          "label": "pii",
+          "types": ["com.example.domain.Person"],
+          "fields": ["com.example.domain.Account#iban"],
+          "note": "GDPR art. 4(1) — identifies a natural person"
+        }
+      ]
+    }
+
+`types` labels a type outright; `fields` labels one member, and the type that
+declares it becomes a seed too, because a route that returns the type can return
+the member. Both forms accept a fully-qualified name or the simple name as written
+in the source.
+
+Best-effort loading, with one difference from `security_config`: a declaration this
+module could not use is **returned as a problem**, never dropped in silence. A label
+that was ignored because of a typo would otherwise read as "nothing sensitive is
+exposed", which is the worst possible false answer for the question being asked.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+#: The same file the custom security annotations are declared in.
+CONFIG_FILENAME = "sourcecode.config.json"
+
+#: The key under which labels are declared.
+CONFIG_KEY = "dataLabels"
+
+
+@dataclass(frozen=True)
+class DataLabel:
+    """One declared label and the types/members it applies to."""
+
+    label: str
+    types: tuple[str, ...] = ()
+    fields: tuple[str, ...] = ()
+    note: str = ""
+
+    @property
+    def seed_types(self) -> tuple[str, ...]:
+        """Every type this label reaches into: declared types, plus the types that
+        declare a labelled field. A member cannot leave a process without the type
+        that holds it, so the type is the unit the graph is walked on — stated here
+        rather than left implicit, because it is also the reason the answer
+        over-reports a route that maps the type and drops the member."""
+        owners = [f.split("#", 1)[0].strip() for f in self.fields if "#" in f]
+        seen: list[str] = []
+        for name in [*self.types, *owners]:
+            if name and name not in seen:
+                seen.append(name)
+        return tuple(seen)
+
+    def to_dict(self) -> dict:
+        return {
+            "label": self.label,
+            "types": list(self.types),
+            "fields": list(self.fields),
+            "note": self.note,
+        }
+
+
+@dataclass(frozen=True)
+class LabelDeclaration:
+    """Everything the configuration said, including what could not be used."""
+
+    labels: tuple[DataLabel, ...] = ()
+    problems: tuple[dict, ...] = ()
+    config_file: Optional[str] = None
+    declared: bool = False  # the key was present, whatever it contained
+
+    def to_dict(self) -> dict:
+        return {
+            "config_file": self.config_file,
+            "declared": self.declared,
+            "labels": [label.to_dict() for label in self.labels],
+            "problems": [dict(p) for p in self.problems],
+        }
+
+
+def _problem(where: str, reason: str, detail: str = "") -> dict:
+    out = {"declaration": where, "reason": reason}
+    if detail:
+        out["detail"] = detail
+    return out
+
+
+def load_labels(root: Optional[Path]) -> LabelDeclaration:
+    """Read `<root>/sourcecode.config.json` and return the declared labels.
+
+    Never raises. An absent file is not a problem — it is a repository that has
+    declared nothing, and the caller says so in the words of the question.
+    """
+    if root is None:
+        return LabelDeclaration()
+    cfg_path = Path(root) / CONFIG_FILENAME
+    try:
+        if not cfg_path.is_file():
+            return LabelDeclaration(config_file=None)
+        data = json.loads(cfg_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return LabelDeclaration(
+            config_file=str(cfg_path),
+            problems=(_problem(CONFIG_FILENAME, "unreadable", f"{type(exc).__name__}: {exc}"),),
+        )
+
+    if not isinstance(data, dict) or CONFIG_KEY not in data:
+        return LabelDeclaration(config_file=str(cfg_path))
+
+    raw = data.get(CONFIG_KEY)
+    if not isinstance(raw, list):
+        return LabelDeclaration(
+            config_file=str(cfg_path),
+            declared=True,
+            problems=(
+                _problem(
+                    CONFIG_KEY, "not_a_list",
+                    f"expected a list of label declarations, found {type(raw).__name__}",
+                ),
+            ),
+        )
+
+    labels: list[DataLabel] = []
+    problems: list[dict] = []
+    for index, item in enumerate(raw):
+        where = f"{CONFIG_KEY}[{index}]"
+        if not isinstance(item, dict):
+            problems.append(_problem(where, "not_an_object"))
+            continue
+        name = str(item.get("label") or "").strip()
+        if not name:
+            problems.append(_problem(where, "no_label", "every declaration needs a `label`"))
+            continue
+        types = _string_list(item.get("types"), where, "types", problems)
+        fields = _string_list(item.get("fields"), where, "fields", problems)
+        bad_fields = [f for f in fields if "#" not in f]
+        fields = tuple(f for f in fields if "#" in f)
+        for bad in bad_fields:
+            problems.append(
+                _problem(
+                    f"{where}.fields", "not_a_member_reference",
+                    f"{bad!r}: a field is written Type#member — a bare type belongs in `types`",
+                )
+            )
+        if not types and not fields:
+            problems.append(
+                _problem(where, "nothing_labelled", f"{name!r} names neither a type nor a field")
+            )
+            continue
+        labels.append(
+            DataLabel(
+                label=name, types=types, fields=fields,
+                note=str(item.get("note") or "").strip(),
+            )
+        )
+
+    return LabelDeclaration(
+        labels=tuple(labels), problems=tuple(problems),
+        config_file=str(cfg_path), declared=True,
+    )
+
+
+def _string_list(
+    value: object, where: str, key: str, problems: list[dict]
+) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        value = [value]
+    if not isinstance(value, list):
+        problems.append(
+            _problem(f"{where}.{key}", "not_a_list", f"found {type(value).__name__}")
+        )
+        return ()
+    out: list[str] = []
+    for entry in value:
+        name = str(entry).strip() if isinstance(entry, (str, int)) else ""
+        if not name:
+            problems.append(_problem(f"{where}.{key}", "empty_entry"))
+            continue
+        if name not in out:
+            out.append(name)
+    return tuple(out)

sourcecode/dynamic_argument_surface.py

@@ -40,15 +40,22 @@ def dynamic_argument_surface(
 ) -> tuple[DynamicArgument, ...]:
     """Every call-site argument of `shape` across the repository, ordered by
     (owner, occurrence, arg_index). Default "concat" = arguments assembled by
-    string/additive concatenation. Pure `ContextGraph` query — reads no source."""
-    owners = graph.symbols(kind="method") + graph.symbols(kind="constructor")
+    string/additive concatenation. Pure `ContextGraph` query — reads no source.
+
+    The owner population is the body-fact layer's own, never a selection of symbol
+    kinds. This surface used to enumerate `kind="method"` plus `kind="constructor"`
+    nodes, and a request handler is a `kind="endpoint"` node: **every controller body
+    in every repository was outside the surface**, silently and with no blind-spot
+    note, which is precisely where a query assembled from request-scoped values
+    lives. Bodies are keyed by owner, so owners are read from the bodies.
+    """
     out: list[DynamicArgument] = []
-    for s in sorted(owners, key=lambda n: n.fqn):
-        for inv in graph.invocations_in(s.fqn):
+    for owner in graph.body_owners():
+        for inv in graph.invocations_in(owner):
             for idx, sh in enumerate(inv.arg_shapes):
                 if sh == shape:
                     out.append(DynamicArgument(
-                        owner_fqn=s.fqn, call=inv.callee, arg_index=idx,
+                        owner_fqn=owner, call=inv.callee, arg_index=idx,
                         shape=sh, occurrence=inv.occurrence,
                     ))
     return tuple(out)

sourcecode/format_contract.py

@@ -44,6 +44,7 @@ FORMAT_REGISTRY: "dict[str, tuple[str, ...]]" = {
     "impact-chain": ("json", "yaml"),
     "pr-impact": ("json", "text"),
     "migrate-check": ("json", "text"),
+    "migrate-recipe": ("json", "yaml"),
     "spring-audit": ("json", "yaml", "github-comment"),
     "explain": ("text", "json"),
     "prepare-context": ("json", "github-comment"),

sourcecode/non_coverage.py

@@ -179,6 +179,51 @@ NON_COVERAGE: tuple[NonCoverage, ...] = (
             "here listed."
         ),
     ),
+    NonCoverage(
+        id="NC-008",
+        surface="data_exposure",
+        not_covered=(
+            "Whether a labelled member actually leaves the process on a given "
+            "route — field-level dataflow through mappers, DTOs, serializers and "
+            "projections."
+        ),
+        why=(
+            "Exposure here is measured at TYPE granularity over the same call "
+            "reach every other command walks: a route reaches the labelled type, "
+            "or its signature names it. Whether the mapping in between keeps the "
+            "labelled member is a dataflow question, and answering it by "
+            "approximation would put a confident `no` on a route that does leak. "
+            "So `call_reach` is published as a supremum and says so."
+        ),
+        instead=(
+            "Read the mapping on the routes this answer ranks first — they are the "
+            "ones worth a human — and label the DTO too if it carries the member, "
+            "which makes the route `signature` instead of `call_reach`."
+        ),
+    ),
+    NonCoverage(
+        id="NC-009",
+        surface="client_usage",
+        not_covered=(
+            "Whether a route is called from outside this repository — another "
+            "service, a mobile app, a partner, a cron job, or a client whose URL "
+            "is assembled at run time."
+        ),
+        why=(
+            "The join reads the TypeScript/JavaScript checked in beside the server "
+            "and only the call shapes whose verb and path are written at the call "
+            "site. That is a floor on who calls a route and can never be a ceiling: "
+            "the repository cannot observe consumers it does not contain. So a route "
+            "with no call site here is published as a candidate for deletion, never "
+            "as dead API."
+        ),
+        instead=(
+            "Access logs or an API gateway answer who really calls a route. The "
+            "opposite direction is decisive without them: a client call matching no "
+            "route is a request this repository's own front end makes and its server "
+            "does not serve."
+        ),
+    ),
 )
 
 

sourcecode/openrewrite_recipe.py

@@ -0,0 +1,278 @@
+"""openrewrite_recipe.py — the report, in the form the executor takes.
+
+Field evaluation #4, on a repository with 585 blockers and an estimated 357
+person-days: *"con 585 bloqueantes jakarta y 357 días estimados, el informe muere en
+un cajón; el codemod se convierte en PRs."* The findings already name the recipe that
+fixes each one — 296 of 309 on openmrs-core, 144 of 170 on BroadleafCommerce — and a
+reader still had to copy them out of a JSON payload by hand into a file OpenRewrite
+can run.
+
+So this module emits that file. **It does not rewrite anything**, and that is a
+position, not a gap (`NC-005`): OpenRewrite is the executor this product recommends,
+and a second, worse migration engine is the one way to lose to it. What is built here
+is its *input* — a declarative composite recipe naming exactly the recipes this
+repository's findings named, plus the invocation that runs it.
+
+Three rules the output holds itself to:
+
+* **Only recipes a finding named.** The recipe list is derived from the report, never
+  from a catalogue of what OpenRewrite can do. A recipe nobody's finding asked for
+  would rewrite code nobody measured.
+* **The remainder is published beside it.** Every blocking finding with no recipe is
+  listed as manual work, because "run this and you are done" is the failure mode a
+  585-blocker report cannot afford twice.
+* **Artifact coordinates are derived from the recipe's own package**, and a recipe
+  whose package maps to no known artifact is reported rather than silently dropped —
+  an invocation missing one coordinate fails at the executor with a message nobody
+  can act on.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+SCHEMA_VERSION = "openrewrite-plan-v1"
+
+#: Default name of the emitted recipe, and of the file it is written to.
+DEFAULT_RECIPE_NAME = "ask.MigrationFromMeasuredFindings"
+DEFAULT_FILENAME = "rewrite.yml"
+
+#: Recipe package prefix → the artifact that publishes it. Derived from the recipe id
+#: itself, because that is the only thing the finding carries; a prefix that is not in
+#: this table is published under `unknown_artifacts` rather than guessed, since a
+#: missing coordinate makes the whole invocation fail at the executor.
+_ARTIFACT_BY_PREFIX: "tuple[tuple[str, str], ...]" = (
+    ("org.openrewrite.java.migrate.", "org.openrewrite.recipe:rewrite-migrate-java:LATEST"),
+    ("org.openrewrite.java.spring.", "org.openrewrite.recipe:rewrite-spring:LATEST"),
+    ("org.openrewrite.java.testing.", "org.openrewrite.recipe:rewrite-testing-frameworks:LATEST"),
+    ("org.openrewrite.hibernate.", "org.openrewrite.recipe:rewrite-hibernate:LATEST"),
+    ("org.openrewrite.maven.", ""),   # core, shipped with the plugin
+    ("org.openrewrite.java.", ""),    # core java recipes
+)
+
+
+@dataclass(frozen=True)
+class RecipePlan:
+    """A composite recipe built from measured findings, and how to run it."""
+
+    recipe_name: str
+    recipes: tuple[str, ...]
+    artifacts: tuple[str, ...]
+    unknown_artifacts: tuple[str, ...]
+    covered_findings: int
+    total_findings: int
+    report_blocking_count: int
+    manual_findings: tuple[dict, ...]
+    population: str
+    build_tool: str
+    document: str
+    invocation: str
+
+    @property
+    def statement(self) -> str:
+        if not self.recipes:
+            return (
+                f"None of the {self.total_findings} findings in this population carries "
+                "an OpenRewrite recipe, so there is no recipe to write and nothing to "
+                "run. All of it is manual work, listed under `manual_remainder` — which "
+                "is an answer, not an empty result."
+            )
+        return (
+            f"{self.covered_findings} of {self.total_findings} findings name a recipe; "
+            f"this document runs those and nothing else. The {len(self.manual_findings)} "
+            "left are listed under `manual_remainder` and no recipe applies to them. "
+            "Nothing here edits source: the executor does, and only when you run the "
+            "invocation."
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "schema_version": SCHEMA_VERSION,
+            "recipe_name": self.recipe_name,
+            "recipes": list(self.recipes),
+            "recipe_artifacts": list(self.artifacts),
+            "unknown_recipe_artifacts": list(self.unknown_artifacts),
+            "coverage": {
+                "findings_with_a_recipe": self.covered_findings,
+                "findings_considered": self.total_findings,
+                "findings_left_manual": len(self.manual_findings),
+                "population": self.population,
+                # Published beside it because it is the figure `migrate-check`
+                # headlines, and it counts something narrower: two populations under
+                # one name is the defect this project keeps finding in its own output.
+                "report_blocking_count": self.report_blocking_count,
+                "report_blocking_count_unit": (
+                    "critical + high findings in product code — `migrate-check`'s "
+                    "headline figure, a subset of the population above"
+                ),
+                "basis": (
+                    "counted over the population named above, from the same "
+                    "`openrewrite_recipe` field `migrate-check` publishes per finding"
+                ),
+            },
+            "manual_remainder": [dict(row) for row in self.manual_findings],
+            "build_tool": self.build_tool,
+            "document": self.document,
+            "filename": DEFAULT_FILENAME,
+            "invocation": self.invocation,
+            "statement": self.statement,
+        }
+
+
+def detect_build_tool(root: Path) -> str:
+    """`maven` | `gradle` | `unknown`, from what the repository actually declares."""
+    root = Path(root)
+    if (root / "pom.xml").is_file():
+        return "maven"
+    for name in ("build.gradle", "build.gradle.kts", "settings.gradle", "settings.gradle.kts"):
+        if (root / name).is_file():
+            return "gradle"
+    return "unknown"
+
+
+def artifact_for(recipe: str) -> Optional[str]:
+    """The artifact coordinate publishing `recipe`, "" for core, None when unknown."""
+    for prefix, artifact in _ARTIFACT_BY_PREFIX:
+        if recipe.startswith(prefix):
+            return artifact
+    return None
+
+
+def _yaml_document(recipe_name: str, recipes: "tuple[str, ...]", *, covered: int,
+                   total: int, manual: int) -> str:
+    lines = [
+        "# Generated by `ask migrate-recipe` from measured findings — do not hand-edit;",
+        "# re-run the command after the code changes and the list changes with it.",
+        f"# {covered} of {total} findings name a recipe. The other {manual} are",
+        "# manual work and are listed in the command's `manual_remainder`.",
+        "---",
+        "type: specs.openrewrite.org/v1beta/recipe",
+        f"name: {recipe_name}",
+        "displayName: Migration recipes named by measured findings",
+        "description: >",
+        "  Every recipe in this list was named by a finding in this repository. It is not",
+        "  a catalogue of what OpenRewrite can do: a recipe nobody's finding asked for",
+        "  would rewrite code nobody measured.",
+        "recipeList:",
+    ]
+    lines += [f"  - {recipe}" for recipe in recipes]
+    return "\n".join(lines) + "\n"
+
+
+def _invocation(build_tool: str, recipe_name: str, artifacts: "tuple[str, ...]",
+                *, recipe_count: int = 1) -> str:
+    if recipe_count == 0:
+        # Measured on BroadleafCommerce: 25 blocking findings in product code and not
+        # one of them carries a recipe. Printing a runnable command for an empty
+        # recipe list would hand the reader a green executor run that changes
+        # nothing and reads as "the migration is automated".
+        return (
+            "# Nothing to run: no finding in the population carries an OpenRewrite "
+            "recipe, so there is no recipe to execute. The work is in "
+            "`manual_remainder`."
+        )
+    coordinates = ",".join(a for a in artifacts if a)
+    if build_tool == "maven":
+        cmd = (
+            "mvn -U org.openrewrite.maven:rewrite-maven-plugin:run "
+            f"-Drewrite.activeRecipes={recipe_name}"
+        )
+        if coordinates:
+            cmd += f" -Drewrite.recipeArtifactCoordinates={coordinates}"
+        return cmd
+    if build_tool == "gradle":
+        return (
+            "# add to build.gradle: plugins { id(\"org.openrewrite.rewrite\") }\n"
+            f"# rewrite {{ activeRecipe(\"{recipe_name}\") }}\n"
+            + ("# dependencies { rewrite(\"" + "\"); rewrite(\"".join(
+                a for a in artifacts if a) + "\") }\n" if coordinates else "")
+            + "gradle rewriteRun"
+        )
+    return (
+        "# No Maven or Gradle build was found at this path, so the invocation cannot "
+        "be written for you. Run the recipe with the OpenRewrite CLI or add the "
+        "plugin to whatever builds this repository."
+    )
+
+
+def build_plan(
+    report: Any,
+    root: Path,
+    *,
+    recipe_name: str = DEFAULT_RECIPE_NAME,
+    include_hygiene: bool = False,
+) -> RecipePlan:
+    """Turn a `MigrationReport` into the recipe document its findings named.
+
+    The population is the **blocking** findings by default, not every main-context
+    one. Measured on openmrs-core: the wider set pulls in `JavaTimeAPIs`, a hygiene
+    recipe that rewrites `java.util.Date` across the repository — real work, and not
+    work anybody asked for while migrating to Boot 3. A migration recipe that also
+    modernises date handling is a diff nobody can review as one thing.
+    `--include-hygiene` opts into it, exactly as `migrate-check` does.
+    """
+    from sourcecode.migrate_check import _BEST_PRACTICE_TARGETS
+
+    findings = [
+        f for f in getattr(report, "findings", []) or []
+        if getattr(f, "code_context", "main") == "main"
+        and (include_hygiene
+             or getattr(f, "migration_target", "") not in _BEST_PRACTICE_TARGETS)
+    ]
+    recipes = sorted({
+        str(f.openrewrite_recipe) for f in findings
+        if getattr(f, "openrewrite_recipe", None)
+    })
+    manual = [
+        {
+            "rule_id": getattr(f, "rule_id", ""),
+            "severity": getattr(f, "severity", ""),
+            "title": getattr(f, "title", ""),
+            "source_file": getattr(f, "source_file", ""),
+            "first_line": getattr(f, "first_line", 0),
+            "fix_hint": getattr(f, "fix_hint", ""),
+        }
+        for f in findings
+        if not getattr(f, "openrewrite_recipe", None)
+    ]
+    artifacts: list[str] = []
+    unknown: list[str] = []
+    for recipe in recipes:
+        artifact = artifact_for(recipe)
+        if artifact is None:
+            unknown.append(recipe)
+        elif artifact and artifact not in artifacts:
+            artifacts.append(artifact)
+
+    covered = len(findings) - len(manual)
+    build_tool = detect_build_tool(root)
+    population = (
+        "findings in product code at or above the severity floor of this run, "
+        "advisory hygiene included (--include-hygiene)"
+        if include_hygiene else
+        "findings in product code at or above the severity floor of this run, with "
+        "the advisory hygiene bucket excluded — a migration diff that also modernises "
+        "date handling cannot be reviewed as one change"
+    )
+    return RecipePlan(
+        recipe_name=recipe_name,
+        recipes=tuple(recipes),
+        artifacts=tuple(sorted(artifacts)),
+        unknown_artifacts=tuple(unknown),
+        covered_findings=covered,
+        total_findings=len(findings),
+        manual_findings=tuple(manual),
+        report_blocking_count=int(getattr(report, "blocking_count", 0) or 0),
+        population=population,
+        build_tool=build_tool,
+        document=_yaml_document(
+            recipe_name, tuple(recipes),
+            covered=covered, total=len(findings), manual=len(manual),
+        ),
+        invocation=_invocation(
+            build_tool, recipe_name, tuple(sorted(artifacts)),
+            recipe_count=len(recipes),
+        ),
+    )

sourcecode/posture.py

@@ -883,6 +883,38 @@ _OPEN_BY_RULE = frozenset({"permit_all", "anonymous"})
 _UNDECIDED_ACCESS = frozenset({"no_rule_matched", "undecided"})
 
 
+def endpoint_access_under(
+    root: Path,
+    profiles: "Optional[set[str]]" = None,
+    *,
+    cir: "Optional[Any]" = None,
+    properties: "Optional[dict[str, str]]" = None,
+) -> "dict[str, str]":
+    """`endpoint_id` → the access decision this profile set produces.
+
+    The per-endpoint half of `build_posture`, published for the consumers that
+    need the decision rather than the report — `ask risk` and `ask enrich` weigh
+    it as their access axis. One producer for the resolution, so a composed row
+    and a `posture` run can never disagree about the same profile set.
+    """
+    return _posture(root, profiles, properties, cir=cir)[1]
+
+
+def access_verdict(decision: str) -> str:
+    """A profile-resolved decision, in the vocabulary the risk composition weighs.
+
+    `no_rule_matched` is **not** open: no rule this analyzer could read matched the
+    request, which is unknown coverage. Folding the two together is the confident
+    security falsehood `posture` exists to prevent, and this function is where that
+    distinction is kept for every consumer at once.
+    """
+    if decision in _OPEN_BY_RULE:
+        return "open"
+    if decision in _UNDECIDED_ACCESS:
+        return "unknown"
+    return "protected"
+
+
 def resolve_environments(
     root: Path,
     properties: "Optional[dict[str, str]]" = None,

sourcecode/repository_ir.py

@@ -1243,6 +1243,17 @@ def _extract_symbols(
                         # from the graph instead of re-reading controller source.
                         if "@Valid" in _params_str or "@Validated" in _params_str:
                             pending_ann_values["_validated_params"] = _params_str.strip()
+                        # The handler's own parameter list, captured for request
+                        # handlers only. `validation_inference` approximated the
+                        # body surface by the verb — POST/PUT/PATCH — and declared
+                        # that "no IR atom exposes" the parameters, so a handler
+                        # taking no arguments at all counted as a body endpoint
+                        # accepting an unvalidated body. An empty string is the
+                        # answer "no parameters"; the key is absent when the list
+                        # spans lines and was not resolved, which is not the same
+                        # thing and must not be read as one.
+                        if any(a in _ENDPOINT_ANNOTATIONS for a in pending_anns):
+                            pending_ann_values["_handler_params"] = _params_str.strip()
                         # Phase 3.2: annotation-member default. In Java grammar a
                         # post-paren `default X;` exists ONLY on @interface members
                         # (`String message() default "...";`) — interface default
@@ -2267,6 +2278,16 @@ def _type_tokens(expr: str) -> tuple[Optional[str], list[str]]:
     return outer, args
 
 
+#: Symbol kinds whose DECLARATION carries types — the class-scope counterpart of
+#: `_BODY_OWNER_KINDS`. A request handler is classified `endpoint` and a factory
+#: method `bean` at emission, never `method`, so a surface that enumerated methods
+#: alone could not see the signature of a single controller handler in the
+#: repository: `structural_references_to_type("Customer")` returned services and
+#: entities and no route at all, which reads as "no endpoint accepts or returns
+#: this type". Same shape as the F.4-1 body-surface seam, one scope up.
+_SIGNATURE_MEMBER_KINDS: "frozenset[str]" = frozenset({"method", "endpoint", "bean"})
+
+
 def _extract_class_type_refs(symbols: list[SymbolRecord]) -> dict[str, list[dict]]:
     """Class-structure TypeReference atoms per class FQN (Semantic IR P-A, class
     scope). Pure projection over already-extracted symbols — reads NO source, adds
@@ -2276,15 +2297,15 @@ def _extract_class_type_refs(symbols: list[SymbolRecord]) -> dict[str, list[dict
     by_class: dict[str, list[tuple[str, str, str, str]]] = {}   # cls -> (member, kind, context, type)
     for s in symbols:
         kind = s.symbol_kind
-        if kind == "method":
+        if kind in _SIGNATURE_MEMBER_KINDS:
             cls = _enclosing_class(s.symbol)
             ro, _ = _type_tokens(s.return_type)
             if ro and ro != "void":
-                by_class.setdefault(cls, []).append((s.symbol, "method", "return_type", ro))
+                by_class.setdefault(cls, []).append((s.symbol, kind, "return_type", ro))
             for p in s.param_types:
                 po, _ = _type_tokens(p)
                 if po:
-                    by_class.setdefault(cls, []).append((s.symbol, "method", "param_type", po))
+                    by_class.setdefault(cls, []).append((s.symbol, kind, "param_type", po))
         elif kind == "constructor":
             cls = _enclosing_class(s.symbol)
             for p in s.param_types: