sourcecode 2.6.2__py3-none-any.whl → 2.6.5__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.6.2"
+__version__ = "2.6.5"

sourcecode/cli.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import hashlib
 import json
+import difflib
 import os
 import sys
 import threading
@@ -254,6 +255,8 @@ _SUBCOMMANDS: frozenset[str] = frozenset(
         "explain",
         # Spring Boot 2→3 migration readiness
         "migrate-check",
+        # In-loop semantic diff gate (working tree vs HEAD)
+        "verify-edit",
         # Native file rename (BLOCKER-A)
         "rename-class",
         # Large file semantic chunking (BLOCKER-B)
@@ -329,6 +332,54 @@ def _reject_path_before_subcommand(path_token: str, subcommand: str) -> "NoRetur
     raise SystemExit(2)
 
 
+def _reject_unknown_command(token: str) -> "NoReturn":
+    """Refuse a first positional that is neither a known subcommand nor a real path.
+
+    `ask` accepts a bare repository path (`ask ./repo`) as an implicit scan, so a
+    mistyped subcommand used to be swallowed as a path and then surfaced a
+    misleading error naming the *wrong* token — `ask spring-audi` complained the
+    directory 'spring-audi' did not exist, and `ask notacommand /tmp` complained
+    'No such command /tmp' (the path, not the typo). Name the token the user
+    actually got wrong, and suggest the closest real commands.
+    """
+    matches = difflib.get_close_matches(token, sorted(_SUBCOMMANDS), n=3, cutoff=0.6)
+    first = f"error: '{token}' is not a known command"
+    if matches:
+        first += f". Did you mean: {', '.join(matches)}?"
+    else:
+        first += " and is not an existing directory to scan."
+    print(
+        first + "\n       run 'ask --help' to list commands, or pass an existing "
+        "repository path.",
+        file=sys.stderr,
+    )
+    raise SystemExit(2)
+
+
+def _has_trailing_nonsubcommand_positional(args: list[str], after: int) -> bool:
+    """True when a bare positional that is NOT a subcommand appears after index
+    ``after`` (options and the values they consume are skipped).
+
+    The implicit scan (`ask <path>`) owns exactly one positional, and a valid
+    invocation with two positionals always starts with a subcommand. So a first
+    non-subcommand positional followed by another non-subcommand positional —
+    `ask notacommand /tmp` — is malformed: the user meant a command. A trailing
+    token that IS a subcommand is left for ``_reject_path_before_subcommand``."""
+    skip_next = False
+    for arg in args[after + 1:]:
+        if skip_next:
+            skip_next = False
+            continue
+        if arg.startswith("-"):
+            if arg.split("=")[0] in _OPTIONS_WITH_VALUE and "=" not in arg:
+                skip_next = True
+            continue
+        if arg in _SUBCOMMANDS:
+            return False  # wrong-order path/subcommand — handled elsewhere
+        return True
+    return False
+
+
 def _preprocess_args(args: list[str]) -> list[str]:
     """Extract a repository path token from an args list and store it in _detected_path.
 
@@ -361,7 +412,13 @@ def _preprocess_args(args: list[str]) -> list[str]:
             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
+        # First genuine positional. `ask` treats it as the repository path to scan
+        # (existence is validated downstream, not here). But if it is followed by
+        # another non-subcommand positional, the one-path scan cannot own both —
+        # `ask notacommand /tmp` — so the user meant a command: name the token they
+        # got wrong instead of swallowing it and erroring on the next one.
+        if _has_trailing_nonsubcommand_positional(result, i):
+            _reject_unknown_command(arg)
         _set_detected_path(arg)
         _path_index = i
     if _path_index >= 0:
@@ -1276,11 +1333,23 @@ def main(
     _raw_path_input = _get_detected_path()
     target = Path(_raw_path_input).resolve()
     if not target.exists():
+        # A non-existent path that closely matches a command name is almost always a
+        # mistyped subcommand (`ask spring-audi`) swallowed as an implicit-scan path,
+        # not a real directory. Point at the likely command instead of only the path.
+        _cmd_matches = difflib.get_close_matches(
+            _raw_path_input, sorted(_SUBCOMMANDS), n=3, cutoff=0.6
+        )
+        _hint = "Pass an existing repository directory."
+        if _cmd_matches:
+            _hint = (
+                f"If you meant a command, try: {', '.join('ask ' + m for m in _cmd_matches)}. "
+                "Otherwise pass an existing repository directory."
+            )
         _emit_error_json(
             INVALID_INPUT_CODE,
             f"Directory '{_raw_path_input}' does not exist.",
             path=_raw_path_input,
-            hint="Pass an existing repository directory.",
+            hint=_hint,
             expected="An existing directory path.",
         )
         raise typer.Exit(code=1)
@@ -5526,7 +5595,7 @@ def spring_audit_cmd(
         help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
     ),
 ) -> None:
-    """Spring semantic audit: TX anomalies (TX-001..005) + security surface (SEC-001..003).
+    """Spring semantic audit: TX anomalies (TX-001..006) + security surface (SEC-001..003).
 
     \b
     Detects:
@@ -5535,6 +5604,7 @@ def spring_audit_cmd(
       TX-003  readOnly=true boundary propagating to write operation
       TX-004  NOT_SUPPORTED/NEVER within active TX chain
       TX-005  Exception swallowing inside @Transactional
+      TX-006  Self-invocation of @Transactional sibling (proxy bypass)
       SEC-001 Unsecured endpoint in annotation_based security model
       SEC-002 CVE-2025-41248: @PreAuthorize on inherited method from generic supertype
       SEC-003 @Transactional on @Controller/@RestController (TX in wrong layer)
@@ -5678,6 +5748,85 @@ def spring_audit_cmd(
         raise typer.Exit(code=1)
 
 
+# ── verify-edit: in-loop semantic diff gate ───────────────────────────────────
+
+
+@app.command("verify-edit")
+def verify_edit_cmd(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository path (default: current directory). Diffs the working tree vs HEAD.",
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Write the verdict JSON to a file instead of stdout."
+    ),
+    format: str = typer.Option("json", "--format", help="Output format: json."),
+    ci: bool = typer.Option(
+        True,
+        "--ci/--no-ci",
+        help="Exit non-zero on a broken/unverified verdict (default on — for gates and hooks).",
+    ),
+    install_hook: Optional[str] = typer.Option(
+        None,
+        "--install-hook",
+        help="Install a git hook (pre-commit|pre-push) that runs this gate, then exit. Does not verify.",
+    ),
+) -> None:
+    """Semantic diff gate: did the working-tree edits change runtime behavior?
+
+    Deterministic, in-loop verdict over the diff of the working tree against HEAD:
+    public contract, @Transactional proxy boundary, security surface, bean wiring,
+    custom domain rules, and blast radius. Built for the agent write-loop (MCP) and
+    git hooks. Only regressions the edit INTRODUCED (vs HEAD) block — pre-existing
+    debt never fails an unrelated commit.
+
+    Custom rules: drop a `.ask/verify-rules.json` at the repo root to enforce your own
+    invariants (e.g. "no @RestController injects a *DaoJpa", "every /payroll endpoint
+    requires role X"). They gate the same way as the built-in axes.
+
+    Exit codes (with --ci, the default): 0 = pass, 1 = break (a blocking axis proved
+    a regression), 2 = unverified (a blocking axis could not be computed — never a
+    silent pass) or the path is not a git repository.
+
+    Examples:
+      ask verify-edit                       # verify the current working tree
+      ask verify-edit /path/to/repo
+      ask verify-edit --no-ci               # always exit 0 (report only)
+      ask verify-edit --install-hook pre-commit
+    """
+    from sourcecode import verify_edit as _ve
+
+    if install_hook is not None:
+        try:
+            _hook_path = _ve.install_git_hook(path, install_hook)
+        except _ve.VerifyEditError as exc:
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                str(exc),
+                hint=f"Choose a hook type: {' | '.join(_ve.HOOK_TYPES)}. The repo must be a git repository.",
+            )
+            raise typer.Exit(code=2)
+        typer.echo(f"Installed verify-edit {install_hook} hook: {_hook_path}", err=True)
+        typer.echo(f"It runs `ask verify-edit --ci` and blocks on a break; bypass with git --no-verify.", err=True)
+        return
+
+    try:
+        v = _ve.verify_edit(path)
+    except _ve.VerifyEditError as exc:
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            str(exc),
+            hint="verify-edit needs a git repository with a HEAD commit (it diffs the working tree vs HEAD).",
+        )
+        raise typer.Exit(code=2 if ci else 0)
+
+    output = _serialize_dict(v.to_dict(), format)
+    _emit_command_output(output, output_path, False,
+                         success_msg=f"verify-edit verdict written to {output_path}")
+    if ci and v.exit_code != 0:
+        raise typer.Exit(code=v.exit_code)
+
+
 # ── Spring Boot Migration Check ───────────────────────────────────────────────
 
 

sourcecode/mcp/registry.py

@@ -1269,6 +1269,7 @@ _MCP_HIDDEN_CANONICAL_TOOLS: frozenset[str] = frozenset({
     "spring_audit",       # curated: repo_path + scope + min_severity only (strips output_path/format/copy)
     "impact_chain",       # curated: repo_path + symbol + depth + query_type with choices
     "migrate_check",      # curated: repo_path + min_severity only (strips output_path/format/copy/ci)
+    "verify_edit",        # curated: repo_path only (report-only --no-ci; strips output_path/format/ci)
     # MCP self-management (an agent is not the MCP client admin)
     "mcp_init",
     "mcp_serve",
@@ -1450,7 +1451,54 @@ min_severity: "low" (default) | "medium" | "high" | "critical" — filter thresh
         docstring_override=_MIGRATE_CHECK_DOC,
     )
 
-    return [spring_audit, impact_chain, migrate_check]
+    _VERIFY_EDIT_DOC = """\
+Semantic diff gate: did the working-tree edits change runtime behavior? JAVA/SPRING.
+
+When to call: right AFTER editing Java source, BEFORE proposing a commit — the
+in-loop guardrail. Deterministic verdict over the diff of the working tree vs HEAD.
+
+Report-only over MCP: it ALWAYS returns the verdict payload (never errors on a
+break) so you can read the result and auto-correct. Read `verdict`:
+  "pass"       — no runtime-behavior regression proven; safe to proceed.
+  "break"      — a blocking axis proved a regression; fix before committing. See
+                 `axes` + `reasons`.
+  "unverified" — an axis could not be computed (e.g. parse failure); do not treat
+                 as safe.
+
+Axes (each a diff HEAD→working):
+  contract_broken     — public API removed / visibility-downgraded / signature changed
+  tx_boundary_changed — @Transactional now on a private/final method = silent CGLIB
+                        proxy bypass (TX ignored at runtime)
+  security_delta      — a new security finding the edit introduced
+  new_orphan_bean     — a bean that lost all its injection wiring
+  blast_radius        — informational: entry points reached by the changed files
+
+Needs a git repository with a HEAD commit (it diffs the working tree vs HEAD).
+"""
+
+    verify_edit = _alias_spec(
+        "verify_edit",
+        "Semantic diff gate over working-tree vs HEAD: contract / TX / security / bean-wiring. JAVA/SPRING.",
+        ("verify-edit",),
+        (
+            ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True,
+                          help="Absolute path to the git repository (default: current directory)."),
+        ),
+        # Report-only: --no-ci so the tool always returns the verdict JSON (a break is
+        # data for the agent, not a command failure that would surface as an error).
+        lambda inputs: [
+            "verify-edit",
+            str(inputs.get("repo_path", ".")),
+            "--no-ci",
+            "--format", "json",
+        ],
+        supported_targets=("repo_path",),
+        unsupported_targets=("file_path",),
+        validator=validate_repo_path,
+        docstring_override=_VERIFY_EDIT_DOC,
+    )
+
+    return [spring_audit, impact_chain, migrate_check, verify_edit]
 
 
 @lru_cache(maxsize=1)

sourcecode/parse_cache.py

@@ -0,0 +1,138 @@
+"""Content-addressed per-file parse cache (verify-edit Fase V4 — sub-second loop).
+
+The bottleneck, measured: on a 1-file edit in a large repo, ``build_repo_ir`` re-parses
+*every* file, and per-file symbol extraction dominates the working-tree CIR build (~85%
+of warm time; ~1.0s of 1.16s at 4.8k symbols). Yet the parse of an unchanged file is a
+**pure function of its bytes** — so it can be memoised across builds.
+
+This cache stores the output of ``_extract_symbols`` — ``(package, imports, symbols)`` —
+keyed by a content hash of ``(rel_path, capture_signature, source)``. Properties that
+make it safe:
+
+  * **Content-addressed ⇒ never stale.** The key *is* the content; a changed file yields
+    a different key and misses (re-parses), it never serves an old parse. There is no
+    invalidation to get wrong — unlike a signature-keyed cache.
+  * **Correctness never depends on it.** A miss, a corrupt entry, or an unwritable dir all
+    degrade to "parse it" — the CIR is byte-identical whether the cache hit or missed
+    (proven by the cir_hash-equivalence test, not assumed).
+  * **Isolated from the whole-CIR cache.** Its own directory tree; it can never poison the
+    ``java-cir`` knowledge entry that ``explain``/``impact``/``review-pr`` share.
+
+Deserialisation was measured at ~5× cheaper than re-parsing (38ms vs 197ms for 4.8k
+symbols), so the round-trip is a real win, not a wash.
+"""
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import json
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+from sourcecode.context_cache import _atomic_write, _base_dir
+
+if TYPE_CHECKING:
+    from sourcecode.repository_ir import SymbolRecord
+
+_CACHE_SUBDIR = "parse-cache-v1"  # bump when the SymbolRecord shape or extractor changes
+
+
+def is_enabled() -> bool:
+    """On unless explicitly disabled (shares the context-cache kill switch). Correctness
+    is identical either way; this only trades disk for CPU."""
+    return os.environ.get("SOURCECODE_CONTEXT_CACHE_DISABLE", "") not in ("1", "true", "yes")
+
+
+def _cache_root() -> Path:
+    return _base_dir() / _CACHE_SUBDIR
+
+
+def file_key(rel_path: str, source: str, capture_sig: str) -> str:
+    """Content hash of everything ``_extract_symbols`` depends on. Two identical inputs
+    ⇒ same key (reuse); any change ⇒ different key (miss, re-parse)."""
+    h = hashlib.sha256()
+    h.update(rel_path.encode("utf-8", "replace"))
+    h.update(b"\x00")
+    h.update(capture_sig.encode("utf-8", "replace"))
+    h.update(b"\x00")
+    h.update(source.encode("utf-8", "replace"))
+    return h.hexdigest()[:32]
+
+
+def _path_for(key: str) -> Path:
+    # Shard by the first 2 hex chars so no single directory grows unbounded.
+    return _cache_root() / key[:2] / f"{key}.json"
+
+
+def get(key: str) -> "Optional[tuple[str, list[str], list[SymbolRecord]]]":
+    """Return the cached ``(package, imports, symbols)`` for *key*, or None on any miss.
+    Best-effort: a missing file, unreadable bytes, or a decode/shape error all read as a
+    miss (the caller then parses) — never an exception."""
+    if not is_enabled():
+        return None
+    from sourcecode.repository_ir import SymbolRecord
+
+    p = _path_for(key)
+    try:
+        raw = p.read_bytes()
+    except OSError:
+        return None
+    try:
+        d = json.loads(raw)
+        pkg = d["p"]
+        imports = list(d["i"])
+        symbols = [SymbolRecord(**sd) for sd in d["s"]]
+    except (ValueError, KeyError, TypeError):
+        return None  # corrupt or shape-drifted entry — treat as absent, will rebuild
+    return pkg, imports, symbols
+
+
+def put(key: str, package: str, imports: list[str], symbols: "list[SymbolRecord]") -> None:
+    """Store a parse result. Best-effort and side-effect-free on failure: caching is a
+    performance aid, never a correctness dependency."""
+    if not is_enabled():
+        return
+    try:
+        payload = {
+            "p": package,
+            "i": list(imports),
+            "s": [dataclasses.asdict(s) for s in symbols],
+        }
+        data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        p = _path_for(key)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        _atomic_write(p, data)
+    except Exception:
+        pass  # unwritable / serialisation fault — silently skip; correctness unaffected
+
+
+# ── generic JSON blob (V4b: the per-file *body-fact* bundle) ─────────────────────
+# The Pass-2 fact extractors (body/literal/guard/field-type/…) are, like symbol
+# extraction, pure functions of the file's bytes, so their combined output is memoised
+# under the SAME content key with a distinct suffix. Values are already plain JSON dicts
+# (atomic-fact IR), so no dataclass reconstruction is needed. Same best-effort contract:
+# a miss/corrupt entry recomputes; the CIR is byte-identical either way.
+def _blob_path(key: str) -> Path:
+    return _cache_root() / key[:2] / f"{key}.blob.json"
+
+
+def get_blob(key: str) -> Optional[dict]:
+    if not is_enabled():
+        return None
+    try:
+        return json.loads(_blob_path(key).read_bytes())
+    except (OSError, ValueError):
+        return None
+
+
+def put_blob(key: str, data: dict) -> None:
+    if not is_enabled():
+        return
+    try:
+        raw = json.dumps(data, ensure_ascii=False).encode("utf-8")
+        p = _blob_path(key)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        _atomic_write(p, raw)
+    except Exception:
+        pass

sourcecode/repository_ir.py

@@ -14,6 +14,7 @@ No inference, approximation, or heuristics.
 
 from __future__ import annotations
 
+import hashlib
 import random
 import re
 import subprocess
@@ -2097,6 +2098,21 @@ def _extract_body_facts(
             receiver, callee = m.group(1), m.group(2)
             if callee in _CALL_KEYWORDS:
                 continue
+            if receiver is None:
+                # A chained/qualified call — `expr().foo()`, `getBean().foo()`,
+                # `a.b().foo()` — leaves the receiver group empty because the
+                # receiver is not a bare identifier. It must NOT be mistaken for an
+                # unqualified self-call: if the callee is immediately preceded by '.'
+                # the call is qualified (goes through whatever the preceding
+                # expression returns, e.g. a Spring proxy), so mark it as a
+                # non-self expression receiver. (openmrs OrderServiceImpl routes
+                # REQUIRES_NEW through Context.getOrderService()....() precisely to
+                # keep the proxy — that is correct code, not a self-invocation.)
+                j = m.start() - 1
+                while j >= 0 and body[j] in " \t\r\n":
+                    j -= 1
+                if j >= 0 and body[j] == ".":
+                    receiver = "<expr>"
             resolved: Optional[str] = None
             if receiver in (None, "this") and callee in sib:
                 cands = [f for f in sib[callee] if f != caller.symbol]
@@ -4968,6 +4984,15 @@ def build_repo_ir(
         custom_security = _load_custom_security(root)
     _custom_sec_tuple = tuple(custom_security)
     _extra_capture = _capture_markers(custom_security)
+    # V4: content-addressed per-file parse cache. The symbol extraction of an unchanged
+    # file is a pure function of its bytes (+ the capture markers), so it is memoised
+    # across builds — a 1-file edit re-parses 1 file, not the whole repo. The cache never
+    # changes the result (a miss just re-parses); the capture signature keys entries so a
+    # different custom-security config cannot serve a parse produced under another.
+    from sourcecode import parse_cache as _pc
+    _capture_sig = hashlib.sha256(
+        repr(sorted(_extra_capture)).encode("utf-8", "replace")
+    ).hexdigest()[:16] if _extra_capture else "-"
 
     all_symbols: list[SymbolRecord] = []
     all_relations: list[RelationEdge] = []
@@ -5029,9 +5054,15 @@ def build_repo_ir(
         _meta_files_read += 1
         _meta_lines_read += source.count("\n") + (1 if source and not source.endswith("\n") else 0)
         _meta_chars_read += len(source)
-        package, symbols, raw_imports = _extract_symbols(
-            source, rel_path, extra_capture=_extra_capture
-        )
+        _pkey = _pc.file_key(rel_path, source, _capture_sig)
+        _cached = _pc.get(_pkey)
+        if _cached is not None:
+            package, raw_imports, symbols = _cached
+        else:
+            package, symbols, raw_imports = _extract_symbols(
+                source, rel_path, extra_capture=_extra_capture
+            )
+            _pc.put(_pkey, package, raw_imports, symbols)
         all_symbols.extend(symbols)
         # P1-E (parse-coverage reconciliation): a file that declares a type but
         # yielded zero symbols is silently invisible to the graph. Record the
@@ -5060,15 +5091,33 @@ def build_repo_ir(
             pkg_type_map=_same_pkg_map,
         )
         if emit_body_facts:
-            _bf, _sf = _extract_body_facts(symbols, source, rel_path)
-            _all_body_facts.update(_bf)
-            _all_span_facts.update(_sf)
-            _all_literal_facts.update(_extract_literal_facts(symbols, source))
-            _all_guard_facts.update(_extract_guard_facts(symbols, source))
-            _all_class_type_refs.update(_extract_class_type_refs(symbols))
-            _all_annotation_arg_values.update(_parse_annotation_arg_values(symbols))
-            _f_imports = _file_import_map(source)
-            _all_field_types.update(_extract_field_types(source, imports=_f_imports))
+            # V4b: the per-file body-fact extractors are pure functions of the file's
+            # bytes, so their combined output is memoised under the same content key.
+            # A warm hit skips all of them; the CIR is byte-identical (equivalence test).
+            _fkey = _pc.file_key(rel_path, source, _capture_sig)
+            _blob = _pc.get_blob(_fkey)
+            if _blob is None:
+                _bf, _sf = _extract_body_facts(symbols, source, rel_path)
+                _f_imports = _file_import_map(source)
+                _blob = {
+                    "body": _bf,
+                    "span": _sf,
+                    "literal": _extract_literal_facts(symbols, source),
+                    "guard": _extract_guard_facts(symbols, source),
+                    "ctref": _extract_class_type_refs(symbols),
+                    "annarg": _parse_annotation_arg_values(symbols),
+                    "ftypes": _extract_field_types(source, imports=_f_imports),
+                    "fimports": _f_imports,
+                }
+                _pc.put_blob(_fkey, _blob)
+            _f_imports = _blob["fimports"]
+            _all_body_facts.update(_blob["body"])
+            _all_span_facts.update(_blob["span"])
+            _all_literal_facts.update(_blob["literal"])
+            _all_guard_facts.update(_blob["guard"])
+            _all_class_type_refs.update(_blob["ctref"])
+            _all_annotation_arg_values.update(_blob["annarg"])
+            _all_field_types.update(_blob["ftypes"])
             # Every type declared in this file resolves simple names through this
             # file's imports — the fact `_static_typed_call_edges` needs to bind a
             # `Type.method(...)` receiver to a type (P1-A's rule, applied to statics).

sourcecode/spring_impact.py

@@ -1036,7 +1036,7 @@ class ImpactOrchestrator:
                 )
             else:
                 warnings.append(
-                    f"Self-referential exclusion (BUG #2): {self_excluded} member(s) of the "
+                    f"Self-referential exclusion: {self_excluded} member(s) of the "
                     f"analyzed class were dropped from callers — a class's own methods are "
                     f"members, not external callers (they do not count toward blast radius)."
                 )