sourcecode 2.5.11__tar.gz → 2.5.13__tar.gz

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

@@ -1,5 +1,86 @@
 # 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
+lands the reconciliation gap-fixes accumulated since 2.5.11 and completes INV-F1-4 across
+every surface that narrates an architectural result — the layer's last open honesty debt.
+No new rule, no widened heuristic; the frozen core (`reconciliation.py`) was not touched.
+
+### Fixed
+
+- **INV-F1-4 closed across the narrating surfaces** (`architecture_analyzer.py`,
+  `prepare_context.py`): `036eaa9` made the producer record every architecture refutation on
+  `arch.limitations`, but only the serializer surface transported them — `prepare-context`/
+  onboard computed the analysis and threw the refutations away, so ofbiz's pruned modules and
+  a refuted layered claim vanished silently there. onboard now runs the analysis once (a
+  single owned `sm.architecture`) and carries the refutation lines into `limitations`, the
+  same sink the serializer uses. A reader can distinguish *"no architecture"* from *"claim
+  refuted"* on every narrating surface. One ownership model governs which surface shows,
+  degrades, or only transports a refutation (ADR-0005 §6.5).
+
+- **Directory contamination that manufactured phantom refutations** (`architecture_analyzer.py`):
+  `flatten_file_tree` emits directory nodes, so `sm.file_paths` carried entries like
+  `src/main` that `_detect_layers` counted as jvm-less module members — a directory holding
+  all the Java transitively read as "no jvm code" and was refuted (petclinic phantom
+  `orchestration`; the directory half of `data`). The layer census now drops ancestor
+  (directory) paths; leaf files, including template view-layers, are untouched. Side effect:
+  pattern detection on the previously-polluted input is corrected (petclinic → `mvc`).
+
+- **The web-pattern cross-check is now an F-1 rule (gap #4)** (`reconciliation.py`,
+  `architecture_summary.py`): `_qualify_web_pattern` was an ad-hoc `if`; it is now the seventh
+  rule, `web_pattern_endpoint_attestation`. The migration fixed a latent lie — the gate
+  degraded at `high < 5`, so a repo with 1–4 real controllers reported *"no HTTP controllers
+  detected"*. The honest predicate is `high == 0` (provable absence), and the authority is
+  Java-file coverage (`stack == "java"`), not the JVM family.
+
+- **A reconciliation rule that raises can no longer read as "no contradiction" (gap #2)**
+  (`reconciliation.py` and all six consumers): each entry point wraps rules per-rule; an
+  exception yields an execution-error finding routed to a surfaced channel, never silence.
+
+- **JVM checks gate on the runtime family, reconciled to one source (gap #3)**
+  (`reconciliation.py`, `classifier.py`): `stack_runtime_family` is the single owner; the two
+  incomplete `{java,kotlin}` copies are gone. The mvc/rest-api authority gate is separately
+  corrected to Java-file coverage, fixing a Kotlin/Scala/Groovy false-negation (INV-F1-1).
+
+### Documentation
+
+- **ADR-0005 marked Accepted & FROZEN.** Seven rules, six invariants closed, ownership model
+  ratified (§6.5), freeze & re-open conditions recorded (§10). Stale "six rules" / "INV-F1-4
+  violated" text removed. Closure report and surface-integration map in `.planning/`.
+
 ## [2.5.11] — 2026-07-17
 
 **Two ways a tool can lie by omission: analyze the wrong repository without

{sourcecode-2.5.11 → sourcecode-2.5.13}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "2.5.11"
+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.11 → 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.11"
+__version__ = "2.5.13"

{sourcecode-2.5.11 → sourcecode-2.5.13}/src/sourcecode/architecture_analyzer.py

@@ -286,6 +286,11 @@ class ArchitectureAnalyzer:
         # architecture claim". `_detect_layers` and its helpers append the
         # findings' sink-neutral detail here; drained into `limitations` below.
         self._refutations: list[str] = []
+        # Gap #2 (fail-open): a reconciliation rule that could not be evaluated
+        # is NOT a clean result — surfaced here as its own limitation, never as a
+        # refutation and never silently, so an unverified pattern cannot ship as
+        # confirmed.
+        self._reconciliation_errors: list[str] = []
 
         # Step 1: filter paths
         filtered = self._filter_paths(sm.file_paths)
@@ -498,6 +503,14 @@ class ArchitectureAnalyzer:
                 continue
             _seen.add(_detail)
             limitations.append(f"Architecture claim refuted on evidence: {_detail}")
+        # Fail-open sink: a rule that could not run is surfaced distinctly — the
+        # pattern it would have checked is reported UNVERIFIED, never certified.
+        _seen_err: set[str] = set()
+        for _detail in self._reconciliation_errors:
+            if _detail in _seen_err:
+                continue
+            _seen_err.add(_detail)
+            limitations.append(f"Architecture reconciliation could not run: {_detail}")
 
         return ArchitectureAnalysis(
             requested=True,
@@ -644,6 +657,24 @@ class ArchitectureAnalyzer:
         return domains
 
     def _detect_layers(self, paths: list[str]) -> tuple[str, list[ArchitectureLayer]]:
+        # Drop directory ENTRIES. `flatten_file_tree` emits every node — files AND
+        # the directories above them — so `sm.file_paths` carries `src`, `src/main`,
+        # `src/main/java/.../model` … A directory is not a file: counting it as a
+        # layer/module member makes it read as jvm-less in `runtime_census` (it holds
+        # no file OF ITS OWN, only children), and a directory that transitively holds
+        # all the Java is then refuted as "no jvm code" — the demonstrated
+        # contamination (petclinic phantom `orchestration` = `src/main`; the
+        # directory half of `data` = `.../model`). A path that is an ancestor of
+        # another path in the set is such an entry; leaf files (incl. template
+        # view-layers) are never ancestors and are kept untouched.
+        _norm = [p.replace("\\", "/") for p in paths]
+        _ancestors: set[str] = set()
+        for _p in _norm:
+            _segs = _p.split("/")
+            for _k in range(1, len(_segs)):
+                _ancestors.add("/".join(_segs[:_k]))
+        paths = [p for p, n in zip(paths, _norm) if n not in _ancestors]
+
         # Exclude non-source paths (tests, benchmarks, docs, tooling, vendored assets)
         # from layer scoring. Also exclude anything under a `resources/` segment: in
         # Maven/Gradle layouts `src/main/resources/**` is bundled config/assets — e.g.
@@ -721,6 +752,11 @@ class ArchitectureAnalyzer:
             for _f in reconcile_architecture_evidence(
                 pattern=pattern_name, layer_files=_layer_paths, repo_files=source_paths
             ):
+                if _f.error:
+                    # A rule that could not run is surfaced always (not tied to
+                    # whether this candidate wins) and never as a refutation.
+                    self._reconciliation_errors.append(_f.detail)
+                    continue
                 _refs.append(_f.detail)
                 if _f.rule == "composition_runtime_split":
                     # A claim that IS a runtime split must show one: JobRunr, a JVM
@@ -922,6 +958,9 @@ class ArchitectureAnalyzer:
         # pruning here directly shapes the returned result (fewer layers, or a
         # drop below 2 that falls through to flat/unknown) — surface it.
         for _f in reconcile_code_modules(layer_files=non_empty, repo_files=paths):
+            if _f.error:
+                self._reconciliation_errors.append(_f.detail)
+                continue
             for _bad in _f.symbols:
                 non_empty.pop(_bad, None)
             self._refutations.append(_f.detail)
@@ -957,6 +996,9 @@ class ArchitectureAnalyzer:
         # eureka "images" (five PNGs). The real modules survive untouched.
         # INV-F1-4: same as the layered path — surface each refuted module.
         for _f in reconcile_code_modules(layer_files=meaningful, repo_files=paths):
+            if _f.error:
+                self._reconciliation_errors.append(_f.detail)
+                continue
             for _bad in _f.symbols:
                 meaningful.pop(_bad, None)
             self._refutations.append(_f.detail)

{sourcecode-2.5.11 → sourcecode-2.5.13}/src/sourcecode/architecture_summary.py

@@ -210,23 +210,38 @@ class ArchitectureSummarizer:
         # welds a foreign runtime's framework onto the primary's label. Drop what
         # the claimed stack does not attest, and never let the TYPE label — which
         # those same frameworks drove — survive its own evidence (P2-F).
-        from sourcecode.reconciliation import type_claim_unattested, unattested_frameworks
+        from sourcecode.reconciliation import (
+            has_execution_error,
+            reconcile_headline_evidence,
+            type_claim_unattested,
+        )
 
-        foreign = unattested_frameworks(primary.stack, sm.project_type, sm.stacks)
-        attested = [name for name in fw_names if name not in foreign]
-        dropped = [name for name in fw_names if name in foreign]
-        if dropped and not attested and type_claim_unattested(
+        _headline_findings = reconcile_headline_evidence(
             claimed_stack=primary.stack, project_type=sm.project_type, stacks=sm.stacks
-        ):
-            return self._describe_foreign_evidence(sm, stack_label, runtime, dropped)
-        fw_names = attested
+        )
+        if has_execution_error(_headline_findings):
+            # Fail-open guard (gap #2): the attestation rule could not run, and
+            # this prose surface has no gap channel to warn on. Rather than assert
+            # an unverified weld ("C#/.NET … using JAX-RS"), withhold the framework
+            # clause — the claim is not made when its check did not execute.
+            fw_names = []
+        else:
+            foreign = frozenset(s for f in _headline_findings for s in f.symbols)
+            attested = [name for name in fw_names if name not in foreign]
+            dropped = [name for name in fw_names if name in foreign]
+            if dropped and not attested and type_claim_unattested(
+                claimed_stack=primary.stack, project_type=sm.project_type, stacks=sm.stacks
+            ):
+                return self._describe_foreign_evidence(sm, stack_label, runtime, dropped)
+            fw_names = attested
 
         fw_str = f" using {', '.join(fw_names)}" if fw_names else ""
         if runtime:
             # BUG #4: never assert "rest api" in the headline unless the endpoints
-            # command actually backs it (Java/Kotlin only — that is where we have an
-            # authoritative extractor). Degrade to a qualified, consistent phrasing.
-            if sm.project_type == "api" and primary.stack in {"java", "kotlin"}:
+            # command actually backs it. Authority is Java ONLY: extract_java_endpoints
+            # reads *.java and is blind to .kt — a Kotlin REST API would otherwise
+            # degrade to "only 0 endpoints detected" over routes it cannot see.
+            if sm.project_type == "api" and primary.stack == "java":
                 total, high = self._endpoint_support()
                 if high < _MIN_REST_ENDPOINTS_FOR_LABEL:
                     plural = "s" if total != 1 else ""
@@ -310,23 +325,62 @@ class ArchitectureSummarizer:
 
     def _qualify_web_pattern(self, arch: Any, arch_line: str, sm: SourceMap) -> str:
         """BUG #1 (Jenkins field test): the "mvc" pattern is a directory-name
-        heuristic (dirs matching controller/model/view keywords). On a Java/Kotlin
-        repo, do not assert "MVC pattern with ... view layers" in prose when the
+        heuristic (dirs matching controller/model/view keywords). On a JVM repo,
+        do not assert "MVC pattern with ... view layers" in prose when the
         canonical endpoint extractor finds no HTTP controllers in the same run —
         Jenkins (Stapler web framework) matches model/view-ish dirs but declares
-        zero Spring MVC controllers. Cross-check against `endpoints` and degrade to
-        a consistent, non-committal phrasing instead of a categorical MVC claim."""
+        zero Spring MVC controllers.
+
+        This is a reconciliation rule (layer table × endpoint index), so the
+        judgement lives in F-1 (`reconcile_web_pattern_evidence`), not as an
+        ad-hoc `if` here (ADR-0005 §6.2/§8.4). The honest predicate is ZERO
+        modeled controllers, not `< 5`: with the old threshold, 1–4 real
+        controllers still degraded to the categorical "no HTTP controllers
+        detected" — a false statement. One controller backs the MVC claim; only
+        an empty index contradicts it.
+
+        **Authority = Java only.** The extractor (`extract_java_endpoints`) reads
+        `*.java`; it is blind to `.kt`/`.scala`/`.groovy`. So zero controllers is
+        a contradiction ONLY for a Java-primary repo. On Kotlin/Scala/Groovy an
+        empty index is the extractor's blindness, not absence of controllers —
+        degrading there asserted "no HTTP controllers detected" over real `.kt`
+        routes (INV-F1-1: never fire on absence of evidence). Gating the rule on
+        the JVM *family* was wrong; the boundary is the extractor's file coverage."""
+        from sourcecode.reconciliation import (
+            has_execution_error,
+            reconcile_web_pattern_evidence,
+        )
+
         if not arch_line or arch.pattern not in ("mvc", "spring_mvc_layered"):
             return arch_line
         primary = next((s for s in sm.stacks if s.primary), sm.stacks[0] if sm.stacks else None)
-        if primary is None or primary.stack not in {"java", "kotlin"}:
-            return arch_line
         _total, high = self._endpoint_support()
-        if high >= _MIN_REST_ENDPOINTS_FOR_LABEL:
-            return arch_line
-        # No controller backing → the MVC/view claim is unverified. Report the
-        # directory-derived layers without the framework label or the "view" claim.
+        # The endpoint extractor reads .java only — it is authoritative for a
+        # Java-primary repo, blind elsewhere.
+        _authoritative = bool(primary) and primary.stack == "java"
+        _findings = reconcile_web_pattern_evidence(
+            pattern=arch.pattern,
+            endpoint_evidence_authoritative=_authoritative,
+            modeled_endpoint_count=high,
+        )
         layer_names = [l.name for l in arch.layers[:4] if l.name != "view"] if arch.layers else []
+        if has_execution_error(_findings):
+            # Fail-open guard (gap #2): the cross-check could not run. Withhold the
+            # categorical MVC label AND the "no controllers" claim (both unverified);
+            # report only the directory-derived layers, or nothing.
+            if layer_names:
+                return (
+                    f"Layered code organization ({', '.join(layer_names)}; "
+                    "directory-based — endpoint cross-check unavailable)."
+                )
+            return ""
+        if not _findings:
+            # Non-Java (extractor blind), not a web pattern, or ≥1 controller backs
+            # the claim → keep. On Kotlin/Scala/Groovy the MVC label stays
+            # unverified rather than falsely negated.
+            return arch_line
+        # Contradiction: zero modeled controllers. Degrade — the claim is
+        # directory names, not routes; the "no HTTP controllers" wording is TRUE.
         if layer_names:
             return (
                 f"Layered code organization ({', '.join(layer_names)}; "

{sourcecode-2.5.11 → sourcecode-2.5.13}/src/sourcecode/classifier.py

@@ -207,7 +207,7 @@ class TypeClassifier:
         # structured codebase (e.g. JobRunr: core + per-framework adapter modules).
         # This is checked BEFORE the weak `bin/`-directory CLI heuristic so a build
         # output / wrapper `bin/` dir does not mislabel a library as a CLI.
-        if stack_names & {"java", "kotlin", "scala"} and self._is_multi_module(file_tree):
+        if stack_names & _JVM_STACKS and self._is_multi_module(file_tree):
             return "library"
 
         # Weak CLI heuristic: a top-level bin/ directory (only when nothing stronger).

{sourcecode-2.5.11 → sourcecode-2.5.13}/src/sourcecode/confidence_analyzer.py

@@ -120,6 +120,20 @@ class ConfidenceAnalyzer:
                 project_type=sm.project_type,
                 stacks=sm.stacks,
             ):
+                if _rf.error:
+                    # Fail-open guard (gap #2): the stack-attestation rule could
+                    # not run. Never let that read as "primary attests every
+                    # framework" — record it as an anomaly + gap, not silence.
+                    anomalies.append(
+                        "Stack/framework attestation could not be evaluated — "
+                        "primary-stack attribution is UNVERIFIED"
+                    )
+                    gaps.append(AnalysisGap(
+                        area="framework_stack_attestation",
+                        reason=_rf.detail,
+                        impact="medium",
+                    ))
+                    continue
                 anomalies.append(
                     f"{', '.join(_rf.symbols)} declared by another runtime, not by the "
                     f"{_primary.stack} primary stack"

{sourcecode-2.5.11 → 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.11 → sourcecode-2.5.13}/src/sourcecode/prepare_context.py

@@ -1249,6 +1249,17 @@ class TaskContextBuilder:
                 [ws.path for ws in workspace_analysis.workspaces],
             )
 
+        # F-1 single-ownership (ADR-0005 §INV-F1-4): run the architecture analysis
+        # ONCE, here, and keep it on sm.architecture — the single owned analysis.
+        # ArchitectureSummarizer/ContextSummarizer reuse it instead of each computing
+        # (and discarding) a private copy, and its refutations are transported into
+        # `limitations` below (surface #3, F1-SURFACE-INTEGRATION-2026-07-18).
+        from sourcecode.architecture_analyzer import ArchitectureAnalyzer as _ArchAnalyzer
+        try:
+            sm.architecture = _ArchAnalyzer().analyze(self.root, sm)
+        except Exception:
+            sm.architecture = None
+
         project_summary = ProjectSummarizer(self.root).generate(sm)
         architecture_summary = ArchitectureSummarizer(self.root).generate(sm)
 
@@ -1306,6 +1317,19 @@ class TaskContextBuilder:
         key_dependencies: list[dict[str, Any]] = []
         limitations: list[str] = []
 
+        # INV-F1-4 transport: this surface narrates the architecture, so it must
+        # carry the owner's refutations — the same lines surface #1 (serializer)
+        # emits. Only the F-1 refutation / execution-error lines (their fixed
+        # prefixes); pattern-inference notes stay out of the onboard surface. The
+        # analysis is the single owned one (sm.architecture) — no re-run, no re-judge.
+        if sm.architecture is not None:
+            for _arch_lim in (sm.architecture.limitations or []):
+                if _arch_lim.startswith((
+                    "Architecture claim refuted on evidence:",
+                    "Architecture reconciliation could not run:",
+                )):
+                    limitations.append(_arch_lim)
+
         if spec.enable_dependencies:
             from dataclasses import asdict
             from sourcecode.dependency_analyzer import DependencyAnalyzer