sourcecode 2.5.8__tar.gz → 2.5.11__tar.gz

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

@@ -1,5 +1,94 @@
 # Changelog
 
+## [2.5.11] — 2026-07-17
+
+**Two ways a tool can lie by omission: analyze the wrong repository without
+saying so, and refute a claim without saying so.** Both closed here. Also lands
+ADR-0005, which ratifies the Evidence Reconciliation Layer as infrastructure and
+records — with measurements — which of its "missing pieces" were never needed.
+
+### Fixed
+
+- **`ask <path> <subcommand>` silently analyzed the current directory instead
+  (P2-G)** (`cli.py`): the argument preprocessor popped the first positional into
+  a path that only the top-level `main` reads. Every subcommand declares its own
+  `path = Argument(".")`, so a leading path before a subcommand was not
+  misparsed — it was **discarded**, and the subcommand fell back to the CWD.
+  `ask spaghetti-api endpoints` reported **1077 endpoints from every repo in the
+  parent directory** (the real surface was 7), exit 0, no warning — an agent
+  consuming that JSON could not tell it was reading someone else's code. Now
+  refused: exit 2, empty stdout, naming the correct invocation. Reordering cannot
+  be guessed (`impact <symbol> <path>` has no free slot). The false-positive
+  guard (an option *value* that happens to match a subcommand name, e.g.
+  `--files endpoints`) is covered. The test suite was itself a victim: four tests
+  invoked the wrong-order form and passed while analyzing atlas-cli — they
+  asserted only "valid JSON", which any repo produces. Corrected to assert an
+  artifact only the intended fixture yields.
+
+- **Refuted architecture claims were pruned silently (INV-F1-4)**
+  (`architecture_analyzer.py`, `reconciliation.py`): three reconciliation rules
+  (`layer_language_coherence`, `composition_runtime_split`,
+  `layer_code_attestation`) were consumed through name-only projections that
+  discarded the finding's explanation. The analyzer dropped a layer or rejected a
+  pattern and told the reader nothing — ofbiz showed fewer modules, jobrunr's
+  "fullstack" vanished, keycloak's foreign `view` layer disappeared, each without
+  a trace. A reader could not distinguish *"this repo has no architecture"* from
+  *"we refuted the architecture claim"* — the exact distinction the analyzer's
+  degrade-to-N/A discipline exists to preserve. Refutations that shape the
+  reported result now surface in `limitations`, prefixed *"Architecture claim
+  refuted on evidence: …"*. Scoped to avoid noise: the winning pattern's pruned
+  layers, the runtime-split contradiction that removed a contender, and every
+  pruning in the fallback paths (which run only when nothing else qualified).
+
+### Added
+
+- **ADR-0005 — Evidence Reconciliation Layer (F-1)**
+  (`docs/architecture/adr/0005-evidence-reconciliation.md`): the layer's contract,
+  invariants and limits. Ratifies the contract as **data** (immutable views +
+  pure-function rules + `ReconciliationFinding`) and **rejects** the proposed
+  provider protocol — an ABC spanning the six consumers would constrain nothing.
+  Documents that the "precursors" slated for migration (the Confidence envelope,
+  `coverage_confidence`, `zero_result_reason`, readiness N/A) are single-view
+  mechanisms that must stay out of F-1, and that pipelines — not commands — are
+  the unit of coverage (`onboard`/`review-pr`/`fix-bug` inherit reconciliation
+  from `prepare_context`).
+
+## [2.5.9] — 2026-07-17
+
+**A silently dead fast path.** The backlog carried the `entry_points`
+list-vs-dict drift as a schema tidiness item. It was not: the drift had disabled
+a feature, quietly, on exactly the repositories that feature exists for.
+
+### Fixed
+
+- **RIS stored `entry_points` in whichever shape it was handed
+  (P2-F-RESIDUE(b))** (`ris.py`): `agent_view` emits that key in two shapes under
+  one `schema_version` — `{"bootstrap": [path…], "security": […],
+  "controllers": {counts}}` when a bootstrap entry point is detected, otherwise
+  `[{"path": …, "kind": …}, …]`. RIS copied either one verbatim into
+  `structural_map["entrypoints"]`, a key its readers treat as a list of path
+  **strings**: they slice it, then guard `isinstance(fp, str)`.
+
+  Both shapes broke it, measured against the real function:
+
+  | shape | result |
+  |---|---|
+  | dict (Spring, …) | `entrypoints[:10]` → `KeyError: slice(None, 10, None)`. `prepare_context._try_ris_fast_path` wraps its whole body in `except Exception: return None`, so **the RIS fast path was silently dead on Java/Spring repos** — falling back to full analysis with no warning. |
+  | list of dicts (everything else) | `isinstance(fp, str)` is false for every item → **zero entry-point files recovered**, silently. |
+
+  The fast path therefore recovered entry points for **no repository at all**,
+  and a bare `except` kept it quiet. `_entrypoint_paths()` now normalizes either
+  shape — plus plain path lists and junk — to the paths RIS promises. Only
+  `bootstrap`/`security` carry paths, so the `controllers` count summary cannot
+  leak into the list.
+
+  The public shape drift is deliberately untouched: unifying it changes a
+  documented `schema_version` and belongs in its own release. RIS's contract now
+  holds whichever shape it is handed, which is what its readers depend on.
+
+3 new tests; suite `3466 passed, 5 skipped, 1 deselected` (the deselection is a
+pre-existing `file_chunker` failure unrelated to this work).
+
 ## [2.5.8] — 2026-07-17
 
 **A count must name what it counted.** 2.5.7 taught the headline to say *"Polyglot

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

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

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

{sourcecode-2.5.8 → sourcecode-2.5.11}/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.8"
+__version__ = "2.5.11"

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

@@ -5,9 +5,8 @@ from pathlib import Path
 from typing import Literal, Optional
 
 from sourcecode.reconciliation import (
-    incoherent_layers,
-    pattern_contradicted,
-    unattested_layers,
+    reconcile_architecture_evidence,
+    reconcile_code_modules,
 )
 
 from sourcecode.schema import (
@@ -280,6 +279,13 @@ class ArchitectureAnalyzer:
     ) -> ArchitectureAnalysis:
         limitations: list[str] = []
         evidence: list[dict] = []
+        # INV-F1-4: reconciliation rules that refute a layer/pattern must not
+        # apply their verdict silently — a pruned layer or a rejected pattern is
+        # a positively-detected contradiction the reader is entitled to see, or
+        # "no architecture" becomes indistinguishable from "we refuted the
+        # architecture claim". `_detect_layers` and its helpers append the
+        # findings' sink-neutral detail here; drained into `limitations` below.
+        self._refutations: list[str] = []
 
         # Step 1: filter paths
         filtered = self._filter_paths(sm.file_paths)
@@ -482,6 +488,17 @@ class ArchitectureAnalyzer:
                     "confidence": "low",
                 })
 
+        # INV-F1-4 sink: surface every refutation that shaped the returned
+        # result. Prefix frames it as a refutation; the detail (unchanged) states
+        # the contradiction, keeping it sink-neutral (INV-F1-5). Dedup: the
+        # layered→modular fallthrough can refute the same directory twice.
+        _seen: set[str] = set()
+        for _detail in self._refutations:
+            if _detail in _seen:
+                continue
+            _seen.add(_detail)
+            limitations.append(f"Architecture claim refuted on evidence: {_detail}")
+
         return ArchitectureAnalysis(
             requested=True,
             pattern=pattern,
@@ -665,6 +682,13 @@ class ArchitectureAnalyzer:
         best_priority = -1
         best_matched: dict[str, list[str]] = {}
         best_layer_files: dict[str, set[int]] = {}
+        # INV-F1-4: refutations that fired while assembling each candidate. Only
+        # those that shaped the RETURNED result are surfaced (below): the winning
+        # pattern's pruned layers, or — when no classical pattern qualifies — the
+        # contradictions that removed the contenders. A refutation of a candidate
+        # that lost on score anyway is not what the reader is being misled about.
+        cand_refutations: dict[str, list[str]] = {}
+        contradiction_details: list[str] = []
 
         for pattern_name, layer_keys in LAYER_PATTERNS.items():
             matched: dict[str, list[str]] = {}
@@ -692,16 +716,29 @@ class ArchitectureAnalyzer:
             # template/asset-only layers are untouched, so a real Spring-MVC
             # `templates/` view survives.
             _layer_paths = {k: [source_paths[i] for i in v] for k, v in layer_files.items()}
-            for _bad in incoherent_layers(pattern_name, _layer_paths, source_paths):
-                matched.pop(_bad, None)
-                layer_files.pop(_bad, None)
-
-            # A claim that IS a runtime split must show one: JobRunr, a JVM
-            # library, read "Fullstack with frontend, backend layers" off a
-            # `dashboard/ui/model/` package of 16 Java files. Nothing to prune —
-            # the pattern itself is what the evidence contradicts.
-            if pattern_contradicted(pattern_name, _layer_paths, source_paths):
+            _refs: list[str] = []
+            _split_contradicted = False
+            for _f in reconcile_architecture_evidence(
+                pattern=pattern_name, layer_files=_layer_paths, repo_files=source_paths
+            ):
+                _refs.append(_f.detail)
+                if _f.rule == "composition_runtime_split":
+                    # A claim that IS a runtime split must show one: JobRunr, a JVM
+                    # library, read "Fullstack with frontend, backend layers" off a
+                    # `dashboard/ui/model/` package of 16 Java files. Nothing to
+                    # prune — the pattern itself is what the evidence contradicts.
+                    _split_contradicted = True
+                else:
+                    # layer_language_coherence: drop the layers owned by a
+                    # different runtime; template/asset-only layers are untouched,
+                    # so a real Spring-MVC `templates/` view survives.
+                    for _bad in _f.symbols:
+                        matched.pop(_bad, None)
+                        layer_files.pop(_bad, None)
+            if _split_contradicted:
+                contradiction_details.extend(_refs)
                 continue
+            cand_refutations[pattern_name] = _refs
 
             # A pattern with unmet required keys cannot qualify (e.g. mvc needs a view).
             required = _PATTERN_REQUIRED_KEYS.get(pattern_name)
@@ -717,6 +754,10 @@ class ArchitectureAnalyzer:
                 best_layer_files = layer_files
 
         if best_score >= 2:
+            # The reported pattern is the one whose refutations misled the reader
+            # if left silent (keycloak's dropped `view` layer). Contradictions of
+            # OTHER, losing candidates did not shape this result — omit them.
+            self._refutations.extend(cand_refutations.get(best_pattern, []))
             layer_confidence: Literal["high", "medium", "low"] = "medium" if best_score >= 3 else "low"
             layers: list[ArchitectureLayer] = []
             for layer_key, matched_dirs in best_matched.items():
@@ -729,6 +770,11 @@ class ArchitectureAnalyzer:
                 ))
             return best_pattern, layers
 
+        # No classical pattern qualified. If a contender was removed by a runtime
+        # split contradiction (jobrunr's "fullstack"), that is why — and the
+        # eventual fallthrough result would otherwise look like a silent absence.
+        self._refutations.extend(contradiction_details)
+
         # 2. Spring domain-module detection (petclinic-style: deep common prefix + feature dirs)
         spring_result = self._detect_spring_domain_modules(source_paths)
         if spring_result is not None:
@@ -872,8 +918,13 @@ class ArchitectureAnalyzer:
         # Architecture with orchestration, data layers" rested on ONE directory
         # entry plus a settings.gradle, with 47 Java files visible and ignored.
         # A logical code layer that holds no code of this repo is not one.
-        for _bad in unattested_layers(non_empty, paths):
-            non_empty.pop(_bad, None)
+        # INV-F1-4: this path only runs when no classical pattern won, so a
+        # 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):
+            for _bad in _f.symbols:
+                non_empty.pop(_bad, None)
+            self._refutations.append(_f.detail)
         if len(non_empty) >= 2:
             return "layered", [
                 ArchitectureLayer(name=k, pattern="layered", files=v, confidence="low")
@@ -904,8 +955,11 @@ class ArchitectureAnalyzer:
         # count alone let build and asset directories be reported as modules —
         # ofbiz "docker, framework, runtime, gradle", neo4j "packaging",
         # eureka "images" (five PNGs). The real modules survive untouched.
-        for _bad in unattested_layers(meaningful, paths):
-            meaningful.pop(_bad, None)
+        # INV-F1-4: same as the layered path — surface each refuted module.
+        for _f in reconcile_code_modules(layer_files=meaningful, repo_files=paths):
+            for _bad in _f.symbols:
+                meaningful.pop(_bad, None)
+            self._refutations.append(_f.detail)
         if len(meaningful) >= 2:
             return "modular", [
                 ArchitectureLayer(name=k, pattern="modular", files=v, confidence="low")

{sourcecode-2.5.8 → sourcecode-2.5.11}/src/sourcecode/cli.py

@@ -7,7 +7,7 @@ import sys
 import threading
 import time
 from pathlib import Path
-from typing import Any, Optional, cast
+from typing import Any, NoReturn, Optional, cast
 
 import typer
 
@@ -293,6 +293,30 @@ _OPTIONS_WITH_VALUE: frozenset[str] = frozenset({
 })
 
 
+def _reject_path_before_subcommand(path_token: str, subcommand: str) -> "NoReturn":
+    """Refuse `ask <path> <subcommand>` instead of silently scanning the CWD.
+
+    `_detected_path` is only read by the root analysis: a subcommand takes its own
+    `path` Argument, which defaults to the current directory. So the path token in
+    `ask spaghetti-api endpoints` was swallowed here and the subcommand ran against
+    the CWD — from a directory of checkouts that is every repository at once.
+    Measured: it answered with 1077 endpoints from keycloak, neo4j and eureka
+    instead of spaghetti-api's 7, exit code 0, no warning.
+
+    A wrong answer that looks right is the one failure this tool must not produce,
+    and the token order cannot be repaired by guessing: subcommands disagree about
+    where a path sits (`impact-chain <symbol> <path>`), so there is no slot to move
+    it to. Name the correct command and stop.
+    """
+    print(
+        f"error: path '{path_token}' comes before the '{subcommand}' subcommand, "
+        f"so it would be ignored and the current directory scanned instead.\n"
+        f"       use: ask {subcommand} {path_token}",
+        file=sys.stderr,
+    )
+    raise SystemExit(2)
+
+
 def _preprocess_args(args: list[str]) -> list[str]:
     """Extract a repository path token from an args list and store it in _detected_path.
 
@@ -300,6 +324,8 @@ def _preprocess_args(args: list[str]) -> list[str]:
     Correctly skips option values (e.g. ``yaml`` in ``--format yaml``).
     If the first non-flag, non-value positional token is a known subcommand name,
     args are returned unchanged so Click can dispatch the subcommand.
+    A path token followed by a subcommand is rejected — see
+    ``_reject_path_before_subcommand``.
     """
     result = list(args)
     skip_next = False
@@ -315,11 +341,17 @@ def _preprocess_args(args: list[str]) -> list[str]:
                 skip_next = True
             continue
         if arg in _SUBCOMMANDS:
+            if _path_index >= 0:
+                # A path already claimed a slot, so this subcommand can only be
+                # the wrong-order form: the path would be dropped and the CWD
+                # scanned in its place.
+                _reject_path_before_subcommand(result[_path_index], arg)
             return result  # known subcommand — leave for Click to dispatch
+        if _path_index >= 0:
+            continue  # a later positional is the subcommand's own business
         # First genuine positional: treat as repository path
         _set_detected_path(arg)
         _path_index = i
-        break
     if _path_index >= 0:
         result.pop(_path_index)
     return result

{sourcecode-2.5.8 → sourcecode-2.5.11}/src/sourcecode/reconciliation.py

@@ -374,21 +374,38 @@ def _rule_composition_runtime_split(
     ]
 
 
+def reconcile_code_modules(
+    *, layer_files: dict[str, list[str]], repo_files: "list[str]"
+) -> list[ReconciliationFinding]:
+    """Run the code-module attestation rule. Never raises.
+
+    Returns the findings (name AND detail), so a consumer can both prune the
+    refuted layers and SURFACE why — INV-F1-4: a rule that is applied silently
+    replaces one dishonesty with another.
+
+    Args:
+        layer_files: {claimed module -> its files}.
+        repo_files:  every source file, supplying the repo's own runtime.
+    """
+    try:
+        repo_runtimes = runtime_census({"_repo": list(repo_files)})["_repo"]
+        return _rule_layer_code_attestation(runtime_census(layer_files), repo_runtimes)
+    except Exception:
+        return []
+
+
 def unattested_layers(
     layer_files: dict[str, list[str]], repo_files: "list[str]"
 ) -> frozenset[str]:
     """Layers holding no code of the repo's runtime (convenience view).
 
-    For consumers claiming code modules / logical code layers. Never raises.
+    Names only; consumers that must also surface the contradiction use
+    `reconcile_code_modules` instead. Never raises.
     """
-    try:
-        repo_runtimes = runtime_census({"_repo": list(repo_files)})["_repo"]
-        out: set[str] = set()
-        for f in _rule_layer_code_attestation(runtime_census(layer_files), repo_runtimes):
-            out.update(f.symbols)
-        return frozenset(out)
-    except Exception:
-        return frozenset()
+    out: set[str] = set()
+    for f in reconcile_code_modules(layer_files=layer_files, repo_files=repo_files):
+        out.update(f.symbols)
+    return frozenset(out)
 
 
 def reconcile_architecture_evidence(