sourcecode 2.6.2__tar.gz → 2.6.3__tar.gz

{sourcecode-2.6.2 → sourcecode-2.6.3}/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## [2.6.3] — 2026-07-24
+
+**`ask verify-edit` — the in-loop semantic diff gate lands (the read-context → write-loop
+verification pivot), plus a content-addressed parse cache and one field-test correctness
+fix.** New user-facing capability; no change to any existing command's contract. Suite:
+**3731 passed, 5 skipped, 1 deselected** (the deselected chunker test is a pre-existing
+external-fixture flake).
+
+### Added
+
+- **`ask verify-edit` — a deterministic, in-loop semantic diff gate.** Verdict over the
+  diff of the working tree against HEAD, built for the agent write-loop and CI. Each axis
+  is a diff over two Canonical IRs (working vs a throwaway `git worktree` checkout of
+  HEAD), reporting only regressions the edit **introduced** — pre-existing debt never
+  fails an unrelated commit:
+  - `contract_broken` — a public symbol removed, its visibility downgraded, or (when
+    unambiguous) its signature changed.
+  - `tx_boundary_changed` — a `@Transactional` proxy boundary broken (e.g. a
+    `@Transactional` method flipped `public` → `private` → a silently inert CGLIB proxy).
+  - `security_delta` — a security-posture finding the edit introduced.
+  - `new_orphan_bean` — a bean that lost all its injection wiring.
+  - `custom_rule_violated` — the client's own invariants, declared in
+    `.ask/verify-rules.json` (below).
+  - plus an informational `blast_radius` (entry points reachable from the changed files).
+
+  Exit codes under `--ci` (default): `0` pass, `1` break, `2` unverified (a blocking axis
+  could not be computed — never a silent pass). JSON verdict to stdout, prose to stderr.
+- **Custom domain rules (`.ask/verify-rules.json`).** Declare invariants of *your*
+  codebase and have `verify-edit` enforce them — `forbidden_edge` ("no `@RestController`
+  injects a `*DaoJpa`") and `require_endpoint_security` ("every `/payroll` endpoint
+  requires role X"). Selectors reason by structure (annotation / fqn-regex / kind /
+  modifier / source-file); the concrete names are config data, never branched on in the
+  engine. Zero-config: no rules file ⇒ nothing to enforce; a malformed ruleset degrades
+  to *unverified*, never a silent pass.
+- **MCP tool `verify_edit`** (report-only) so an agent can call the gate after each edit,
+  and **`ask verify-edit --install-hook pre-commit|pre-push`** to install a git hook that
+  runs the same binary and blocks on a break (bypass with `git --no-verify`).
+- **Content-addressed per-file parse cache.** Symbol extraction and the body-fact bundle
+  of an unchanged file are pure functions of its bytes, so they are memoised by a content
+  hash — a 1-file edit re-parses 1 file, not the whole repo. It **never changes the
+  result** (a miss just re-parses; the CIR is byte-identical whether the cache is cold,
+  warm, or disabled) and it accelerates every CIR consumer, not only `verify-edit`.
+  Measured on a 1076-file repo: the working-CIR build drops ~59% warm.
+
+### Fixed
+
+- **`verify-edit` contract axis no longer false-breaks on overloaded methods** (found in
+  a field-test of a real repo with a clean tree). An fqn carries no signature, so
+  overloaded methods/constructors share one id across several graph nodes; the axis now
+  aggregates visibility per fqn as *any overload public* instead of picking an
+  order-dependent representative, so a public name that also has a non-public overload no
+  longer reads as a downgrade on an unchanged tree.
+
 ## [2.6.2] — 2026-07-23
 
 **Field-eval Fase 3 — cache reuse (C) + cold-scan honesty (E). No

{sourcecode-2.6.2 → sourcecode-2.6.3}/PKG-INFO

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

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

{sourcecode-2.6.2 → sourcecode-2.6.3}/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.6.2"
+__version__ = "2.6.3"

{sourcecode-2.6.2 → sourcecode-2.6.3}/src/sourcecode/cli.py

@@ -254,6 +254,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)
@@ -5678,6 +5680,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-2.6.2 → sourcecode-2.6.3}/src/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-2.6.3/src/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-2.6.2 → sourcecode-2.6.3}/src/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
@@ -4968,6 +4969,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 +5039,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 +5076,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).