sourcecode 2.5.7__py3-none-any.whl → 2.5.11__py3-none-any.whl

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.7"
+__version__ = "2.5.11"

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/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/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(

sourcecode/ris.py

@@ -29,7 +29,7 @@ import subprocess
 from dataclasses import asdict, dataclass
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Optional
+from typing import Any, Optional
 
 RIS_SCHEMA_VERSION: str = "1.0"
 _RIS_FILENAME: str = "ris.json.gz"
@@ -107,9 +107,46 @@ def save_ris(repo_root: Path, ris: RepositoryIntelligenceSnapshot) -> None:
 # Data extraction from L1 core_dict
 # ---------------------------------------------------------------------------
 
+def _entrypoint_paths(raw: Any) -> list[str]:
+    """Normalize agent_view's `entry_points` to the file paths RIS promises.
+
+    `structural_map["entrypoints"]` is consumed as a list of path STRINGS (it is
+    sliced, and every reader guards with `isinstance(fp, str)`), but agent_view
+    emits that key in two different shapes under one schema_version:
+
+        {"bootstrap": [path, …], "security": […], "controllers": {counts}}
+            when a bootstrap/security entry point was detected (Spring, …)
+        [{"path": …, "kind": …}, …]
+            otherwise
+
+    Storing either verbatim broke BOTH readers: the dict raised `KeyError` on
+    `entrypoints[:10]` — swallowed by a bare `except Exception`, silently
+    disabling the RIS fast path on exactly the Java/Spring repos it exists for —
+    and the list of dicts recovered zero paths, because a dict is not a `str`.
+
+    The shape drift itself is a separate schema question; normalizing here keeps
+    RIS's own contract true whichever shape it is handed, including plain paths.
+    """
+    if isinstance(raw, dict):
+        # Only bootstrap/security carry paths; `controllers` is a count summary.
+        out: list[str] = []
+        for key in ("bootstrap", "security"):
+            out.extend(p for p in (raw.get(key) or []) if isinstance(p, str))
+        return out
+    if isinstance(raw, list):
+        out = []
+        for item in raw:
+            if isinstance(item, str):
+                out.append(item)
+            elif isinstance(item, dict) and isinstance(item.get("path"), str):
+                out.append(item["path"])
+        return out
+    return []
+
+
 def _extract_structural_map(agent_data: dict) -> dict:
     """Extract structural map from agent_view output."""
-    entry_points = agent_data.get("entry_points", [])
+    entry_points = _entrypoint_paths(agent_data.get("entry_points", []))
 
     layers = []
     domains = []

{sourcecode-2.5.7.dist-info → sourcecode-2.5.11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.5.7
+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.7.dist-info → sourcecode-2.5.11.dist-info}/RECORD

@@ -1,7 +1,7 @@
-sourcecode/__init__.py,sha256=AYI3dPxhkPPbI6cutQ3CdTcxsveWkRyIzUZMCY7lfFs,308
+sourcecode/__init__.py,sha256=dNBAjvpTNkiFYDXqXdJjx0saZlNREwHXUuF1drsfGuo,309
 sourcecode/adaptive_scanner.py,sha256=XffluXKzJUXrMtjEiAOnSNPZnztdIcts17T9ouHeID0,10521
 sourcecode/archetype.py,sha256=d7yoN6Tj4OBj-VgSMPEKg4WF9H8FypnZ5A6AkUh5oIE,34484
-sourcecode/architecture_analyzer.py,sha256=1CEIeFtuxdzeFaeUtA5QuDmFkb5eilUK8zRmk9tcDxc,55644
+sourcecode/architecture_analyzer.py,sha256=Bv6OYeAdK88PvHZuryO6CkR6NLJMUqvLy9WkGsw1Fa4,59072
 sourcecode/architecture_summary.py,sha256=oBkjx7hZxmpdKLt4EracjRKHJFOGuPTd6SadTyPxY7Q,29568
 sourcecode/ast_extractor.py,sha256=FEsYTsMCXbJfSYQZRk1k-I-PjUNGnKqO1IxMftsgA5U,51351
 sourcecode/cache.py,sha256=1V3vsaODAa2UBJAC0xpvxpmRdriCezQx5Q8JCcfgziE,31892
@@ -10,7 +10,7 @@ sourcecode/caller_metrics.py,sha256=HG8RCOkpzzsEGdnMRob6byrwjoj5__t0TEsBj4yR7ks,
 sourcecode/canonical_ir.py,sha256=5hLAhhSpXNOdZAvPt-J-rXccJE6M3A6gVhmhU0Tym6Y,29269
 sourcecode/cir_graphs.py,sha256=9G0HHj1kw2325IDyzo2OpX73BNswEckecf4MZUXB4JM,12078
 sourcecode/classifier.py,sha256=9olDN5joeKHcwG9vf73X-t_son16hLVNib0rBbqk1vc,18865
-sourcecode/cli.py,sha256=46Chp0JsEWD_j0HUWOx4tOhrsXSWgWV8JhL5G8SyW4I,322078
+sourcecode/cli.py,sha256=mlMgyRukRoHXYdAYHBN4z06LszwdRo0QLdhs0KYtup8,323804
 sourcecode/code_notes_analyzer.py,sha256=EJemNCNc9Dn-1RZYu-aNbK0ELzmsyC4s6FdHi3XyNEI,9392
 sourcecode/confidence_analyzer.py,sha256=KCRg8B4WH15LpOB7oYhE4dD5nou9Xi48RT3vpaO6Ar4,20868
 sourcecode/context_cache.py,sha256=maws79rLKDwyZ7c9Q2LwlIxqZHRFlaKzErtO3mglWoA,25036
@@ -51,13 +51,13 @@ sourcecode/pr_impact.py,sha256=dCDVw83EDbyVf6F9ZmEQmsFz8ruVH7d4mpeKQCIZHM0,16805
 sourcecode/prepare_context.py,sha256=PYygAKL_jwz8gGElgM9mroUSih18UKSSjv08ndfl4aA,222877
 sourcecode/progress.py,sha256=qn30sWaHOkjTgXsSBmiPkz7Rsbwc5oSlIe6JNEMYp_k,3149
 sourcecode/ranking_engine.py,sha256=ZAucq_YX2KkWUuAZf4P0lhtQ_38vEFnUhuGtSZd1S0E,12970
-sourcecode/reconciliation.py,sha256=Ulmo4cNgeBnS1KxWv7kKFkXkwgJaQ70P0x6zC4F0I_I,26342
+sourcecode/reconciliation.py,sha256=NSGWsRQ-5l50aO_6YErDlu1kEbQB8zDtVf58h_Ro15c,26984
 sourcecode/redactor.py,sha256=SB4hwIvg8h-hvcqKcDWaZvA-aSyn-at-BIRwa0tUv5E,3227
 sourcecode/relevance_scorer.py,sha256=0AgEt4KrV73nioMqBgjhGjtY7L2C7L7cSyKtj3IKcrw,9408
 sourcecode/rename_refactor.py,sha256=h6dNFlB9aZ_3q6heeHBkgXQeXaT03nvPSsYH6P8qxFg,12965
 sourcecode/repo_classifier.py,sha256=FG1vaWKdWXsWdl-S8hjVMiTqcwgaRXkDyvK4rPcOGtQ,22681
 sourcecode/repository_ir.py,sha256=F6lRgPoP8oTtnGpRgjoLw-dlxZRXH7XOcehtcNwufEY,309550
-sourcecode/ris.py,sha256=aG2D4159gtpg968yD3PylYbIXhGFOwIlFBI0DSr84yY,20412
+sourcecode/ris.py,sha256=Hw8TakTQ6hku-Abf2k8954NwkrH_sP73_8wVH8x5khc,22079
 sourcecode/runtime_classifier.py,sha256=uTAD6BDCiBLUZEDRfqk718kM4RTT_vAbfkcOI2_Xx58,18432
 sourcecode/scanner.py,sha256=WdOQ78mMzjR1NjmKTlbxdgwinnCTfAhxCVLBEFQiFHU,8899
 sourcecode/schema.py,sha256=aHNXDf8LGyUC8ZDE_VS9kiskC2-Oswhi_WnpdGy6HDw,24897
@@ -137,8 +137,8 @@ sourcecode/telemetry/consent.py,sha256=LIAO9ohJZF8OuZwM4u1VWtALlYfTCCKq4wV3Vwc7i
 sourcecode/telemetry/events.py,sha256=LtzYfaX9Ilckj5PTvAcTpDa9mLqDsYPDUiDkRa58piY,2580
 sourcecode/telemetry/filters.py,sha256=NHa5T-6DaZduQPFuC34jOqHWQgSizM-Ygq8aZ4j19ng,5834
 sourcecode/telemetry/transport.py,sha256=4gGHsq0WeY9VywEZXA3vUxykfiYnw9uuqfjAAec7F8o,1681
-sourcecode-2.5.7.dist-info/METADATA,sha256=WZPw6sppRfqGy5VxcYxS97BHKScBppWAW2UI8eD_TIM,10851
-sourcecode-2.5.7.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-2.5.7.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
-sourcecode-2.5.7.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-2.5.7.dist-info/RECORD,,
+sourcecode-2.5.11.dist-info/METADATA,sha256=6j_zA5-pJ01V4qnmyhPDb3FtyvH5bqAccNhHVP6tO5s,10852
+sourcecode-2.5.11.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-2.5.11.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
+sourcecode-2.5.11.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-2.5.11.dist-info/RECORD,,