sourcecode 2.5.12__tar.gz → 2.5.13__tar.gz

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

@@ -1,5 +1,37 @@
 # Changelog
 
+## [2.5.13] — 2026-07-18
+
+**Test-fixture endpoints no longer pollute the production API 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 flat as production API surface with no scope qualifier. This
+inflated endpoint counts and injected phantom attack surface into security exploration,
+the exact task the endpoint command is meant to serve, with no warning. This is 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.
+
 ## [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.13}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "2.5.12"
+version = "2.5.13"
 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.13}/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.13"

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

@@ -120,6 +120,54 @@ 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
+
+
 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.13}/src/sourcecode/repository_ir.py

@@ -5584,7 +5584,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 +5753,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 +5779,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 +5804,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 +5940,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: