sourcecode 2.5.12__tar.gz → 2.5.15__tar.gz

{sourcecode-2.5.12 → sourcecode-2.5.15}/CHANGELOG.md

@@ -1,5 +1,139 @@
 # Changelog
 
+## [2.5.15] — 2026-07-19
+
+**Bootstrap detection recovers the real entry point on multi-`main` repos, without
+noise.** Post-F1 field validation (neo4j) found the compact `bootstrap` was name-gated
+to `*Application.java` / `*Main.java`: neo4j's real server entry `Neo4jCommunity.java`
+(a `main()` in a differently-named class) was invisible, so a client CLI `Main.java` was
+reported as the sole bootstrap and the repo's 31 `main()` methods were hidden.
+
+### Fixed
+
+- **`main()`-bearing classes are recovered regardless of filename, comment-aware, and
+  the bootstrap list is ordered/capped/counted** (`detectors/java.py`, `serializer.py`,
+  `path_filters.py`): the annotation scan (which already reads each candidate file) now
+  also emits an `application` entry when a file declares a real `main(String[])` or a
+  bootstrap annotation — after stripping comments, so a `main()` / `@SpringBootApplication`
+  shown in a **javadoc example** is never mistaken for an entry (fixed Broadleaf
+  `*AutoConfiguration` false positives). `_bootstrap_structured` then: excludes entries
+  classified `auxiliary`/`development`; excludes mains in **example/demo modules**
+  (new structural `is_example_module_path`, e.g. `eureka-examples/`) and **test-fixture
+  modules** (`is_test_fixture_module_path`, e.g. `eureka-test-utils/`) — filtered here,
+  not in the detector, because workspace sub-scans prefix the module name onto the path
+  only after detection; orders deployment-annotated entries first; caps the list at 10;
+  and adds a `bootstrap_note` reporting the true count when more than one entry exists.
+  Measured (fleet): neo4j surfaces `Neo4jCommunity.java` with note "11 application entry
+  points detected; showing 10"; Broadleaf false positives 7 → 0; eureka's example/
+  test-util mains dropped (5 → 1); petclinic / spaghetti / openmrs unchanged (single
+  bootstrap). Full-output A/B confirms the change is confined to the entry-point surface —
+  no drift in stacks, architecture, or confidence. Residual real tool/CLI mains in library
+  packages (e.g. jobrunr's `DatabaseCreator`) are reported honestly with the count, as they
+  cannot be distinguished from deployment mains without name heuristics. Suite: 3521 passed.
+
+## [2.5.14] — 2026-07-18
+
+**One authority decides the primary stack; every surface transports its choice.**
+Post-F1 field validation found a polyglot repo (Confluent `examples`: 1 C# file vs 86
+Java files) labelled `.NET` as primary. Root cause was not one coin flip but several:
+`primary` was chosen by `max()` over `(priority, confidence, manifest)` — which **ties**
+for two manifest-detected API stacks, so **list order** decided — and then re-derived
+independently in more than one place (the classifier marked `stacks[].primary`; the
+summarizer re-selected for the `project_summary` prose; the serializer / architecture
+summary invented a `stacks[0]` fallback when the flag was absent). These agreed only by
+sharing the same arbitrary order, so they could — and did — disagree once the input
+changed.
+
+### Fixed
+
+- **Single primary-stack authority with an evidence-weighted tiebreaker**
+  (`classifier.py`, `cli.py`, `summarizer.py`): a new `select_primary_stack(stacks,
+  project_type, file_paths)` is the ONE decider. It keeps the existing
+  `(priority, confidence, manifest)` ordering and adds **source-file volume as the last
+  tuple element** — a pure tiebreaker that decides only when the prior three tie, so a
+  1-file .NET example never outranks 86 Java files, and stacks that already differ are
+  never reordered. It marks exactly one instance `primary=True` (all others `False`) over
+  the final assembled root+workspace set. `TypeClassifier.enrich` now delegates to it (the
+  old `_select_primary_stack` name-returning helper is removed), and the main compact path
+  re-runs it after workspace stacks are appended. The summarizer's independent
+  `_select_summary_primary_stack` is deleted — the prose now reads the same `stack.primary`
+  flag as `architecture_summary`, `stacks[].primary` and `confidence_analyzer`. The
+  extension table shared by confidence enrichment and the tiebreaker was hoisted to one
+  constant (`_STACK_EXTENSIONS`) so the two never diverge. Fleet A/B (12 repos): only
+  `examples` changes (primary `dotnet`→`java`; architecture `C#/.NET`→`Java … JAX-RS`;
+  summary `Stack: Dotnet`→`Stack: Java … 80 Java classes`; the previously-emitted false
+  "polyglot / two programs" anomaly correctly disappears because Java genuinely attests the
+  API surface). All 11 other repos are byte-identical. Suite: 3508 passed, 5 skipped.
+
+## [2.5.13] — 2026-07-18
+
+**"Production endpoint" is now a single definition across every user-facing surface.**
+Post-F1 field validation (neo4j, keycloak) found that a JAX-RS / Spring resource shipping
+under `src/main` of a test-utility module — a dummy web service, an Arquillian test-harness
+resource — was reported as production API surface, and that different commands disagreed on
+what counted: `endpoints` / `validation` derived their view one way while `impact`,
+`impact-chain`, `pr-impact`, `review-pr` and `spring-audit` derived theirs from the raw
+`route_surface`, so the same repo had two definitions of "exposed endpoint" depending on the
+command. This release unifies them: every user-facing surface now consumes the same
+production-endpoint view (test scaffolding excluded), while `route_surface` remains the RAW
+structural evidence by design — full and unfiltered — consumed only by `repo-ir`. The
+under-modelling that motivated this (test fixtures counted as HTTP exposure, inflating
+endpoint counts, blast radius, risk scores and security analysis) was the one defect the
+post-F1 review classified as blocking.
+
+### Fixed
+
+- **Endpoints from test-fixture / test-utility modules are excluded from the production
+  surface** (`repository_ir.py`, `path_filters.py`): a new structural, name-agnostic
+  helper `is_test_fixture_module_path` flags a module directory segment that carries a
+  delimited `test` token *together* with an infrastructure word (`util(s)`, `fixture(s)`,
+  `support`, `framework`, `kit`, `harness`, `tools`, `helper(s)`, `mock(s)`, `stub(s)`,
+  `dummy`) — e.g. `server-test-utils`, `foo-testkit`, `bar-test-support` — or a known
+  test-module segment (`testsuite`, `integration-arquillian`, `test-framework`). Requiring
+  both tokens in the *same* segment keeps legitimate `utils` / `support` / `tools` packages
+  from ever matching. `extract_java_endpoints` traces each endpoint back to its declaring
+  module and, when it is a test fixture, drops it from `endpoints` / `total` /
+  `no_security_signal` and the security-model heuristics. The exclusion is **transparent,
+  not silent**: excluded entries are preserved in a `test_util_endpoints` bucket with a
+  `scope: "test_util"` tag, a `test_util_excluded` count, and an explanatory `notes` entry.
+  Measured: neo4j 18 → 14 production (4 dummy `DummyThirdPartyWebService` endpoints moved to
+  the bucket); keycloak 775 → 673 production (102 Arquillian/test-framework harness
+  endpoints excluded). Control repos unchanged (spaghetti-api 7, petclinic 17, eureka 18,
+  Broadleaf 225). `is_test_or_fixture_path` and the migrate-check blocking count it feeds are
+  deliberately untouched — the new helper is narrower and wired only into endpoint
+  extraction.
+
+- **One production-endpoint definition across every CIR consumer** (`repository_ir.py`,
+  `canonical_ir.py`, `endpoint_metrics.py`): the fix above only reached the `endpoints` /
+  `validation` surface; `impact-chain`, `pr-impact`, `review-pr` and `spring-audit` derive
+  their HTTP surface from the canonical `cir.endpoints`, which is built from the RAW
+  `route_surface` and did **not** inherit the test-fixture exclusion — so those commands
+  still counted test scaffolding as production exposure (e.g. keycloak's 102 Arquillian
+  endpoints inflating blast radius / risk score / SEC analysis). `build_repo_ir` now tags
+  test-fixture routes with `scope="test_util"` on `route_surface`, and `ir_dict_to_canonical`
+  excludes tagged routes when building `cir.endpoints` — the same place the pre-existing
+  FQN dynamic-admin filter already reconciles the CIR surface with the `endpoints` command.
+  `route_surface` itself is left **raw and complete** (the tag is additive) so `repo-ir`
+  keeps full evidence; the divergence is documented in `ENDPOINT_SURFACE_RECONCILIATION`.
+  No heuristic, scoring, risk or reconciliation logic was changed — the four consumers change
+  only because they now receive a coherent `cir.endpoints`. Measured: keycloak
+  `cir.endpoints` / `spring-audit.endpoints_analyzed` 775 → 673 (route_surface stays 775);
+  neo4j 18 → 14 (route_surface stays 18); Broadleaf/petclinic/spaghetti/eureka unchanged
+  (0 test_util routes). Zero test-fixture controllers leak into `cir.endpoints` on any repo.
+
+- **The legacy `impact` command now shares the same production-endpoint definition**
+  (`repository_ir.py`): `impact` reads `route_surface` directly via `compute_blast_radius`
+  rather than through `cir.endpoints`, so it was the last user surface still counting test
+  fixtures as HTTP exposure. `compute_blast_radius` now skips `scope=="test_util"` routes when
+  building `endpoints_affected`. The change is a single guard at the consumption point: the
+  blast-radius algorithm, caller selection, risk formula, security surface and the FQN-admin
+  handling are all unchanged — the endpoint list simply no longer includes test scaffolding.
+  Validated by A/B (stash) diff: `impact TestingOIDCEndpointsApplicationResource` on keycloak
+  went from 28 endpoints_affected (all test) / risk 87 to 0 / risk 3 with `direct_callers`
+  unchanged (1 → 1); `impact CatalogServiceImpl` on Broadleaf is **byte-identical** before and
+  after (54 endpoints, 5 FQN-shaped paths preserved, 30 callers). "Production endpoint" is now
+  a single definition across every user-facing command.
+
 ## [2.5.12] — 2026-07-18
 
 **F-1 (the Evidence Reconciliation Layer) is closed and its rule core frozen.** This release

{sourcecode-2.5.12 → sourcecode-2.5.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.5.12
+Version: 2.5.15
 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-2.5.12 → sourcecode-2.5.15}/pyproject.toml

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

{sourcecode-2.5.12 → sourcecode-2.5.15}/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__ = "2.5.12"
+__version__ = "2.5.15"

{sourcecode-2.5.12 → sourcecode-2.5.15}/src/sourcecode/canonical_ir.py

@@ -398,9 +398,17 @@ def ir_dict_to_canonical(
     # real REST surface. The CIR endpoint list feeds `spring-audit` (endpoints_analyzed),
     # `impact` and `validation`; it must apply the SAME filter so its count reconciles
     # with `endpoints` instead of being silently inflated by those pseudo-routes.
+    # Endpoints declared in a test-fixture / test-utility module are tagged
+    # scope="test_util" on route_surface by build_repo_ir. They are excluded from the
+    # canonical endpoint list for the same reason as the FQN filter above: the CIR
+    # surface feeds impact-chain, pr-impact, review-pr and spring-audit, and test
+    # scaffolding is not production HTTP exposure. route_surface itself keeps them
+    # (raw evidence); only this canonical projection drops them.
     _seen_ids: set[str] = set()
     raw_endpoints: list[CanonicalEndpoint] = []
     for r in route_surface:
+        if r.get("scope") == "test_util":
+            continue
         if _FQN_PATH_RE.search(r.get("path", "") or ""):
             continue
         ep = _route_to_canonical_endpoint(r)

{sourcecode-2.5.12 → sourcecode-2.5.15}/src/sourcecode/classifier.py

@@ -37,6 +37,26 @@ _WEB_FRAMEWORKS = {"Next.js", "React", "Vue", "Svelte", "Vite", "Flutter", "Phoe
 _CLI_FRAMEWORKS = {"Typer", "Cobra", "Clap"}
 _API_STACKS = {"python", "go", "java", "php", "ruby", "dotnet", "kotlin", "scala"}
 
+# Source-file extensions per stack — single table shared by the confidence
+# enrichment (_count_extension_hits) and the primary-stack evidence tiebreaker
+# (select_primary_stack). Kept in one place so the two never diverge.
+_STACK_EXTENSIONS: dict[str, tuple[str, ...]] = {
+    "python": (".py",),
+    "nodejs": (".js", ".ts", ".tsx"),
+    "go": (".go",),
+    "rust": (".rs",),
+    "java": (".java",),
+    "php": (".php",),
+    "ruby": (".rb",),
+    "dart": (".dart",),
+    "dotnet": (".cs", ".fs"),
+    "elixir": (".ex", ".exs"),
+    "kotlin": (".kt", ".kts"),
+    "scala": (".scala",),
+    "terraform": (".tf",),
+    "cpp": (".c", ".cc", ".cpp", ".cxx", ".hpp", ".h"),
+}
+
 # Center-of-gravity gate for the "api" decision (neo4j field test).
 # The historical rule was pure PRESENCE: any API framework on the classpath →
 # project_type="api". That mislabels a large engine/platform that merely exposes a
@@ -63,6 +83,59 @@ _API_SURFACE_ENTRY_KINDS = frozenset({
 ConfidenceLevel = Literal["high", "medium", "low"]
 
 
+def _primary_ext_hits(stack_name: str, file_paths: Sequence[str]) -> int:
+    exts = _STACK_EXTENSIONS.get(stack_name, ())
+    if not exts:
+        return 0
+    return sum(1 for p in file_paths if p.endswith(exts))
+
+
+def select_primary_stack(
+    stacks: Sequence[StackDetection],
+    project_type: str | None,
+    file_paths: Sequence[str] | None = None,
+) -> list[StackDetection]:
+    """Single authority for which stack is primary.
+
+    Marks exactly ONE stack instance ``primary=True`` (all others ``False``) on the
+    FINAL assembled stack set (root + workspace stacks). Selection order:
+    ``(priority, confidence, manifest, source-file volume)``. The volume component is
+    a pure tiebreaker — it decides only when the prior three tie (e.g. a polyglot repo
+    where a Java and a .NET stack are both manifest-detected API stacks), so a 1-file
+    .NET example never outranks 86 Java files. Being last, it never reorders stacks
+    that already differ on the earlier components.
+
+    This is the ONLY place a primary decision is made. Every consumer must read
+    ``stack.primary`` — none may re-select or invent a ``stacks[0]`` fallback.
+    """
+    stack_list = list(stacks)
+    if not stack_list:
+        return stack_list
+    paths = list(file_paths or [])
+
+    def sort_key(stack: StackDetection) -> tuple[int, int, int, int]:
+        score = {"low": 0, "medium": 1, "high": 2}.get(stack.confidence, 0)
+        manifest_weight = 1 if stack.manifests else 0
+        priority = 0
+        # Backend server-side stacks with manifest evidence outrank frontend stacks
+        # in fullstack projects (e.g. Java+Spring wins over nodejs+Angular).
+        if (project_type in {"fullstack", "api"}
+                and stack.stack in _API_STACKS
+                and stack.manifests):
+            priority = 4
+        elif (project_type in {"webapp", "fullstack"} and stack.stack in {"nodejs", "elixir"}
+              or project_type == "api" and stack.stack in _API_STACKS
+              or project_type == "cli" and any(
+                  framework.name in _CLI_FRAMEWORKS for framework in stack.frameworks
+              )
+              or project_type == "cli" and stack.stack in {"cpp", "dotnet"}):
+            priority = 3
+        return (priority, score, manifest_weight, _primary_ext_hits(stack.stack, paths))
+
+    winner = max(stack_list, key=sort_key)
+    return [replace(s, primary=(s is winner)) for s in stack_list]
+
+
 class TypeClassifier:
     """Clasifica project_type y enriquece stacks con confianza/primary."""
 
@@ -74,15 +147,12 @@ class TypeClassifier:
     ) -> tuple[list[StackDetection], str | None]:
         enriched = [self._enrich_stack(file_tree, stack, entry_points) for stack in stacks]
         project_type = self._classify_project_type(file_tree, enriched, entry_points)
-        primary_stack = self._select_primary_stack(enriched, project_type)
-
-        final_stacks: list[StackDetection] = []
-        primary_assigned = False
-        for stack in enriched:
-            is_primary = stack.stack == primary_stack and not primary_assigned
-            if is_primary:
-                primary_assigned = True
-            final_stacks.append(replace(stack, primary=is_primary))
+        # Delegate to the single primary-stack authority. enrich only ever sees the
+        # ROOT stacks; the authority runs again at model finalization over the full
+        # root+workspace set (that call is the one consumers read).
+        final_stacks = select_primary_stack(
+            enriched, project_type, flatten_file_tree(file_tree)
+        )
         return final_stacks, project_type
 
     def _enrich_stack(
@@ -371,50 +441,8 @@ class TypeClassifier:
                 has_api = True
         return has_web and has_api
 
-    def _select_primary_stack(
-        self, stacks: Sequence[StackDetection], project_type: str | None
-    ) -> str | None:
-        if not stacks:
-            return None
-
-        def sort_key(stack: StackDetection) -> tuple[int, int, int]:
-            score = {"low": 0, "medium": 1, "high": 2}.get(stack.confidence, 0)
-            manifest_weight = 1 if stack.manifests else 0
-            priority = 0
-            # Backend server-side stacks with manifest evidence outrank frontend stacks
-            # in fullstack projects (e.g. Java+Spring wins over nodejs+Angular).
-            if (project_type in {"fullstack", "api"}
-                    and stack.stack in _API_STACKS
-                    and stack.manifests):
-                priority = 4
-            elif (project_type in {"webapp", "fullstack"} and stack.stack in {"nodejs", "elixir"}
-                  or project_type == "api" and stack.stack in _API_STACKS
-                  or project_type == "cli" and any(
-                      framework.name in _CLI_FRAMEWORKS for framework in stack.frameworks
-                  )
-                  or project_type == "cli" and stack.stack in {"cpp", "dotnet"}):
-                priority = 3
-            return (priority, score, manifest_weight)
-
-        return max(stacks, key=sort_key).stack
-
     def _count_extension_hits(self, file_tree: dict[str, Any], stack: str) -> int:
-        extensions = {
-            "python": (".py",),
-            "nodejs": (".js", ".ts", ".tsx"),
-            "go": (".go",),
-            "rust": (".rs",),
-            "java": (".java",),
-            "php": (".php",),
-            "ruby": (".rb",),
-            "dart": (".dart",),
-            "dotnet": (".cs", ".fs"),
-            "elixir": (".ex", ".exs"),
-            "kotlin": (".kt", ".kts"),
-            "scala": (".scala",),
-            "terraform": (".tf",),
-            "cpp": (".c", ".cc", ".cpp", ".cxx", ".hpp", ".h"),
-        }.get(stack, ())
+        extensions = _STACK_EXTENSIONS.get(stack, ())
         return sum(1 for path in flatten_file_tree(file_tree) if path.endswith(extensions))
 
     def _score_to_confidence(self, score: int) -> ConfidenceLevel:

{sourcecode-2.5.12 → sourcecode-2.5.15}/src/sourcecode/cli.py

@@ -1965,6 +1965,13 @@ def main(
         analyzer_fingerprints=_fingerprints,
         traversal_topology=_topology.as_dict(),
     )
+    # Single primary-stack authority over the FINAL assembled set (root + workspace
+    # stacks). enrich marked the root stacks; workspace stacks were appended after,
+    # so re-run the one authority here — idempotent — so every consumer of sm.stacks
+    # reads a coherent primary flag.
+    from sourcecode.classifier import select_primary_stack as _select_primary_stack
+    from sourcecode.tree_utils import flatten_file_tree as _flatten_ft
+    stacks = _select_primary_stack(stacks, project_type, _flatten_ft(file_tree))
     sm = SourceMap(
         metadata=metadata,
         file_tree=file_tree,

{sourcecode-2.5.12 → sourcecode-2.5.15}/src/sourcecode/detectors/java.py

@@ -67,6 +67,16 @@ _BOOTSTRAP_ANNOTATION_RE = re.compile(
     r'EnableAutoConfiguration|SpringBootConfiguration)\b'
     r'|\bextends\s+SpringBootServletInitializer\b'
 )
+# Comment strippers — a main()/bootstrap annotation inside a javadoc example or a
+# comment is NOT an entry point (e.g. Broadleaf's *AutoConfiguration classes whose
+# javadoc shows `public static void main` and mentions @SpringBootApplication).
+# Detection of bootstrap entries must run on de-commented source.
+_BLOCK_COMMENT_RE = re.compile(r'/\*.*?\*/', re.DOTALL)
+_LINE_COMMENT_RE = re.compile(r'//[^\n]*')
+
+
+def _strip_java_comments(source: str) -> str:
+    return _LINE_COMMENT_RE.sub(' ', _BLOCK_COMMENT_RE.sub(' ', source))
 
 # --- Keycloak / Quarkus SPI ---
 # Matches "implements EventListenerProvider" or "implements Foo, EventListenerProvider, Bar"
@@ -533,12 +543,21 @@ class JavaDetector(AbstractDetector):
         _other_files = [p for p in _non_test if "Controller" not in p]
         scan_candidates = _ctrl_files + _other_files[:max(0, _MAX_JAVA_ENTRY_SCAN - len(_ctrl_files))]
 
+        # Paths already emitted as application entries by the name-gated step-1 scan,
+        # so the annotation scan (which now also recovers main()-bearing files) does
+        # not list the same bootstrap twice.
+        _app_paths = {ep.path for ep in entry_points if ep.kind == "application"}
         annotation_eps: list[EntryPoint] = []
         for rel_path in scan_candidates:
             if len(annotation_eps) >= _MAX_ANNOTATION_ENTRY_POINTS:
                 break
             abs_path = context.root / rel_path
-            annotation_eps.extend(self._scan_java_file_for_entry_points(abs_path, rel_path))
+            for _ep in self._scan_java_file_for_entry_points(abs_path, rel_path):
+                if _ep.kind == "application":
+                    if _ep.path in _app_paths:
+                        continue
+                    _app_paths.add(_ep.path)
+                annotation_eps.append(_ep)
         entry_points.extend(annotation_eps)
 
         # 3. web.xml servlet/filter declarations
@@ -611,6 +630,7 @@ class JavaDetector(AbstractDetector):
             content = abs_path.read_text(encoding="utf-8", errors="replace")
         except OSError:
             return None
+        content = _strip_java_comments(content)
         if _BOOTSTRAP_ANNOTATION_RE.search(content):
             return "bootstrap_annotation"
         if _MAIN_METHOD_RE.search(content):
@@ -678,6 +698,20 @@ class JavaDetector(AbstractDetector):
                 and "ControllerAdvice" not in content
                 and not any(ann in content for ann in _CUSTOM_SECURITY_ANNOTATIONS)
                 and not has_jax_rs and not has_cdi and not has_spi):
+            # Not a controller/security/DI file — but it may still be an application
+            # entry point. The name-gated step-1 scan only reads *Application.java /
+            # *Main.java, so a real main(String[]) in a differently-named class (e.g.
+            # neo4j's Neo4jCommunity.java server bootstrap) would otherwise be invisible,
+            # leaving a client CLI named Main.java as the sole reported bootstrap. Reuse
+            # the content already read here; strip comments first so a main()/annotation
+            # in a javadoc example is never mistaken for a real entry point.
+            _decommented = _strip_java_comments(content)
+            if _BOOTSTRAP_ANNOTATION_RE.search(_decommented):
+                return [EntryPoint(path=rel_path, stack="java", kind="application",
+                                   source="bootstrap_annotation")]
+            if _MAIN_METHOD_RE.search(_decommented):
+                return [EntryPoint(path=rel_path, stack="java", kind="application",
+                                   source="main_method")]
             return []
 
         if _REST_CONTROLLER_RE.search(content):

{sourcecode-2.5.12 → sourcecode-2.5.15}/src/sourcecode/endpoint_metrics.py

@@ -30,7 +30,10 @@ ENDPOINT_SURFACE_RECONCILIATION: str = (
     "handler after inheritance projection and JAX-RS sub-resource-locator composition. "
     "It is NOT the canonical API surface — it still contains framework dynamic-admin "
     "routes whose path is a Java FQN (e.g. /org.broadleafcommerce...), which the "
-    "`endpoints` command excludes. Endpoint counts differ across commands BY DESIGN "
+    "`endpoints` command excludes, and endpoints from test-fixture / test-utility "
+    "modules (tagged scope=\"test_util\"), which the canonical CIR surface excludes so "
+    "impact-chain / pr-impact / spring-audit do not report test scaffolding as "
+    "production HTTP exposure. Endpoint counts differ across commands BY DESIGN "
     "and are not contradictory; expected ordering for one repo is "
     "repo-ir.route_surface (raw, includes FQN-shaped framework routes) >= "
     "endpoints.total (canonical REST/API surface, FQN-shaped routes filtered out) >= "

{sourcecode-2.5.12 → sourcecode-2.5.15}/src/sourcecode/path_filters.py

@@ -120,6 +120,85 @@ def is_test_or_fixture_path(path: str) -> bool:
     return False
 
 
+# Infrastructure words that, combined with a delimited "test" token in the same
+# directory segment, identify a module whose code is test scaffolding even though
+# it lives under src/main (e.g. "server-test-utils", "foo-testkit"). Kept narrow
+# on purpose: the "test" token must be present in the SAME segment, so packages
+# named "utils"/"support"/"tools" alone never match.
+_TEST_INFRA_TOKENS = frozenset({
+    "util", "utils", "fixture", "fixtures", "support",
+    "framework", "kit", "harness", "tools", "tool",
+    "helper", "helpers", "mock", "mocks", "stub", "stubs", "dummy",
+})
+
+# Glued (non-hyphenated) test-fixture module suffixes.
+_TEST_INFRA_SUFFIXES = (
+    "testutils", "testutil", "testkit", "testfixtures", "testfixture",
+    "testsupport", "testframework", "testharness", "testtools",
+    "testhelpers", "testmocks", "teststubs",
+)
+
+
+def is_test_fixture_module_path(path: str) -> bool:
+    """Return True when *path* belongs to a test-fixture / test-utility MODULE.
+
+    Structural, name-agnostic: a directory segment must contain a hyphen/underscore
+    -delimited ``test`` token together with an infrastructure word (util(s),
+    fixture(s), support, framework, kit, harness, tools, helper(s), mock(s),
+    stub(s), dummy) — e.g. ``server-test-utils``, ``foo-testkit``,
+    ``bar-test-support`` — or match a known test-module segment outright.
+
+    This is deliberately NARROWER than :func:`is_test_or_fixture_path`: it targets
+    modules that ship HTTP resources, JAX-RS ``@Path`` fixtures, or dummy
+    controllers under ``src/main`` so they are not misreported as production API
+    surface. Requiring both tokens in one segment keeps legitimate ``utils`` /
+    ``support`` / ``tools`` packages from ever matching.
+    """
+    norm = path.replace("\\", "/").lower()
+    parts = norm.split("/")
+    for part in parts[:-1]:  # skip the filename
+        bare = part.rstrip("/")
+        if bare in _TEST_MODULE_SEGMENTS:
+            return True
+        if bare.endswith(_TEST_INFRA_SUFFIXES):
+            return True
+        toks = bare.replace("_", "-").split("-")
+        if "test" in toks and any(t in _TEST_INFRA_TOKENS for t in toks):
+            return True
+    return False
+
+
+_EXAMPLE_MODULE_TOKENS = frozenset({
+    "example", "examples", "demo", "demos", "sample", "samples", "showcase",
+})
+
+
+def is_example_module_path(path: str) -> bool:
+    """Return True when *path* is inside an example/demo MODULE directory.
+
+    Structural: a directory segment above the source root carries a hyphen/underscore
+    -delimited example/demo token (e.g. ``eureka-examples/src/main/java/...``). Package
+    components below the source root (``io/confluent/examples/...``) are NOT matched —
+    only a module directory is a functional role; a package of the same name is not.
+    """
+    norm = path.replace("\\", "/").lower()
+    # Prepend "/" so a relative path ("src/main/...") matches the same boundary as an
+    # absolute one; without this the head-truncation silently failed and package
+    # components below the source root (e.g. ".../samples/petclinic/...") false-matched.
+    probe = "/" + norm
+    head = norm
+    for root in ("/src/main/", "/src/test/", "/src/"):
+        idx = probe.find(root)
+        if idx >= 0:
+            head = probe[:idx]
+            break
+    for seg in head.split("/"):
+        toks = seg.replace("_", "-").split("-")
+        if any(t in _EXAMPLE_MODULE_TOKENS for t in toks):
+            return True
+    return False
+
+
 def is_vendor_path(path: str) -> bool:
     """Return True when *path* is inside a vendored / third-party directory.
 

{sourcecode-2.5.12 → sourcecode-2.5.15}/src/sourcecode/repository_ir.py

@@ -25,7 +25,10 @@ from typing import Any, Iterable, Optional
 from sourcecode.caller_metrics import CALLER_METRIC_RECONCILIATION
 from sourcecode.endpoint_metrics import ENDPOINT_SURFACE_RECONCILIATION
 from sourcecode.fqn_utils import normalize_owner_fqn as _normalize_owner_fqn
-from sourcecode.path_filters import is_test_path as _is_test_path
+from sourcecode.path_filters import (
+    is_test_path as _is_test_path,
+    is_test_fixture_module_path as _is_test_fixture_module_path,
+)
 from sourcecode.security_config import (
     CustomSecuritySpec,
     capture_markers as _capture_markers,
@@ -4176,6 +4179,23 @@ def _assemble(
     _route_surface = _build_route_surface(
         sorted_syms, route_diffs, extends_map=_extends_map, custom_security=custom_security
     )
+    # Tag routes that originate in a test-fixture / test-utility module (dummy web
+    # services, JAX-RS @Path fixtures shipped under src/main of a *-test-utils /
+    # testsuite / test-framework module). route_surface stays RAW evidence — nothing
+    # is dropped here; the tag lets the CIR endpoint projection (ir_dict_to_canonical)
+    # exclude them so every CIR consumer (impact-chain, pr-impact, review-pr,
+    # spring-audit) shares one production-endpoint definition with the `endpoints`
+    # command, while repo-ir can still see the full surface. Mirrors the scope tag
+    # applied in extract_java_endpoints.
+    _rs_fqn_file = {
+        s.symbol: (s.source_file or s.declaring_file)
+        for s in sorted_syms
+        if s.type in ("class", "interface")
+    }
+    for _r in _route_surface:
+        _rf = _rs_fqn_file.get(_r.get("effective_class", ""), "")
+        if _rf and _is_test_fixture_module_path(_rf):
+            _r["scope"] = "test_util"
     _analysis_gaps = _compute_analysis_gaps(
         sorted_syms, spring_summary, _route_surface, sorted_rels,
         unparsed_type_files=unparsed_type_files,
@@ -5584,7 +5604,7 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
     """
     import re as _re
     from typing import Any as _Any
-    from sourcecode.path_filters import is_test_path
+    from sourcecode.path_filters import is_test_path, is_test_fixture_module_path
 
     _EXTENDS_FROM_SIG = _re.compile(r'\bextends\s+(\w+)')
 
@@ -5753,6 +5773,16 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
     endpoint_warnings = _recovery["warnings"]
     _openapi_spec_path = _recovery["spec_path"]
 
+    # Map each declared class/interface FQN to its source file so an endpoint can be
+    # traced back to the MODULE that ships it. Used to flag endpoints that originate
+    # in a test-fixture / test-utility module (dummy web services, JAX-RS @Path
+    # fixtures) living under src/main — these are not production API surface.
+    _fqn_to_file: dict[str, str] = {
+        s.symbol: (s.source_file or s.declaring_file)
+        for s in all_symbols
+        if s.type in ("class", "interface")
+    }
+
     endpoints: list[dict] = []
     for route in routes:
         handler = (
@@ -5769,6 +5799,9 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
             "handler": handler,
             "return_type": route.get("return_type", "void"),
         }
+        _src = _fqn_to_file.get(route.get("effective_class", ""), "")
+        if _src and is_test_fixture_module_path(_src):
+            entry["scope"] = "test_util"
         # Use security_annotations already extracted by _build_route_surface
         # via the canonical _route_security_from_sym extractor.
         security_info = route.get("security_annotations")
@@ -5791,6 +5824,14 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
     )
     endpoints = [e for e in endpoints if not _FQN_PATH_RE.search(e.get("path", ""))]
 
+    # Partition test-fixture/test-utility endpoints out of the production surface.
+    # They ship under src/main of a *-test-utils / *-testkit / test-framework module
+    # (dummy web services, JAX-RS @Path fixtures) and must not be reported as, or
+    # counted with, the real API surface — but they are preserved in their own bucket
+    # so nothing is silently dropped and the exclusion is auditable.
+    _test_util_endpoints = [e for e in endpoints if e.get("scope") == "test_util"]
+    endpoints = [e for e in endpoints if e.get("scope") != "test_util"]
+
     # "no_security_signal" = no recognized security annotation at method OR class level.
     # Note: repos may use framework-level security (e.g. Keycloak itself) with no
     # per-endpoint annotations — this count reflects annotation-based coverage only.
@@ -5919,6 +5960,16 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
         # Keep legacy field name for backward compat, now means same as no_security_signal
         "undocumented": no_security_signal,
     }
+    # Surface test-fixture endpoints excluded from the production surface above.
+    # Reported separately (not hidden) so the exclusion is transparent and auditable.
+    if _test_util_endpoints:
+        result["test_util_endpoints"] = _test_util_endpoints
+        result["test_util_excluded"] = len(_test_util_endpoints)
+        result.setdefault("notes", []).append(
+            f"{len(_test_util_endpoints)} endpoint(s) from test-fixture/test-utility "
+            f"module(s) under src/main were excluded from the production surface "
+            f"(see test_util_endpoints)."
+        )
     # Surface incomplete-endpoint warnings (interface-defined controllers) only when
     # present, to keep output backward-compatible for the common case.
     if endpoint_warnings:
@@ -6366,6 +6417,12 @@ def compute_blast_radius(
 
     endpoints_affected: list[dict] = []
     for ep in route_surface:
+        # Test-fixture routes (tagged by build_repo_ir) are not production HTTP
+        # exposure — skip them so the legacy `impact` command shares the single
+        # production-endpoint definition used by the CIR surfaces. Nothing else about
+        # blast-radius selection changes; FQN-admin routes are untouched.
+        if ep.get("scope") == "test_util":
+            continue
         ep_class = ep.get("effective_class") or ep.get("controller") or ep.get("class") or ""
         ep_symbol = ep.get("symbol") or ""
         ep_handler = (