sourcecode 2.5.19__py3-none-any.whl → 2.5.20__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.19"
+__version__ = "2.5.20"

sourcecode/architectural_delta.py

@@ -0,0 +1,147 @@
+"""architectural_delta.py — D1 Architectural Delta (before/after outcome measurement).
+
+Engineering Decision Support, Part B / D1. ASK measures repository *state*; this
+module measures the *engineering outcome* of a change by diffing two already-built
+canonical IR snapshots and reporting the DELTAS — files, symbols, endpoints,
+dependency edges, HTTP-surface set changes, and per-symbol fan-in shifts.
+
+Discipline (moat line): every number here is MEASURED and derived from the CIR
+alone. This layer computes deltas and stops — it never opines "better/worse",
+never assigns ROI, and never classifies a change as breaking/non-breaking (that is
+D2's contract-diff, a distinct axis). A reviewer reads the deltas and decides.
+
+Determinism: `extract_metrics` reads only the CIR; `diff_metrics` is a pure
+function of two metric snapshots. Same two snapshots → byte-identical delta.
+
+Increment scope (D1-a): counts + HTTP-surface set delta + fan-in shifts. Import
+cycles and blast-radius deltas are deferred to a later increment (heavier compute,
+own metric extractor) — omitted here rather than approximated.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sourcecode.canonical_ir import CanonicalRepositoryIR
+
+# Frozen schema tag — versioned like perf-baseline-v1 so consumers can pin it.
+ARCH_DELTA_SCHEMA: str = "architectural-delta-v1"
+
+# Cap on the length of any per-item list in the payload (added/removed endpoints,
+# fan-in shifts). The counts are always exact; the lists are a bounded sample.
+_LIST_CAP: int = 50
+
+# reverse_graph edge types that are NOT a dependency. `contained_in` is pure
+# structural membership (a class "contains" its own methods/ctor) — counting it
+# would make every class report a fan-in equal to its own member count (a
+# controller nobody calls would read as fan-in 2). Every other type
+# (calls/injects/extends/implements/imports/returns/instantiates/references) is a
+# genuine reverse dependency and IS counted.
+_FAN_IN_EXCLUDE_EDGE_TYPES: frozenset[str] = frozenset({"contained_in"})
+
+
+def _fan_in_map(cir: "CanonicalRepositoryIR") -> dict[str, int]:
+    """symbol FQN → distinct reverse-dependant count, from the reverse graph.
+
+    reverse_graph is target → {edge_type → [dependant_fqn, ...]}. Fan-in is the
+    number of unique dependants across all DEPENDENCY edge types (a dependant that
+    both calls and injects a target counts once); structural containment is
+    excluded (see `_FAN_IN_EXCLUDE_EDGE_TYPES`)."""
+    out: dict[str, int] = {}
+    for target, by_type in (cir.reverse_graph or {}).items():
+        deps: set[str] = set()
+        for edge_type, dep_list in (by_type or {}).items():
+            if edge_type in _FAN_IN_EXCLUDE_EDGE_TYPES:
+                continue
+            deps.update(dep_list or ())
+        out[target] = len(deps)
+    return out
+
+
+@dataclass(frozen=True)
+class ArchMetrics:
+    """A deterministic architectural snapshot extracted from one CIR."""
+
+    cir_hash: str
+    file_count: int
+    symbol_count: int
+    endpoint_count: int
+    dependency_edge_count: int
+    endpoints: frozenset[tuple[str, str]]   # (METHOD, path) — the HTTP contract surface
+    fan_in: dict[str, int]                   # symbol FQN → distinct caller count
+
+
+def extract_metrics(cir: "CanonicalRepositoryIR") -> ArchMetrics:
+    """Project a CIR into its measured architectural metrics. Reads the CIR only."""
+    endpoints = frozenset(
+        (str(ep.method).upper(), str(ep.path)) for ep in (cir.endpoints or [])
+    )
+    return ArchMetrics(
+        cir_hash=cir.cir_hash,
+        file_count=len(cir.files or []),
+        symbol_count=len(cir.symbols or []),
+        endpoint_count=len(cir.endpoints or []),
+        dependency_edge_count=len(cir.dependencies or []),
+        endpoints=endpoints,
+        fan_in=_fan_in_map(cir),
+    )
+
+
+def _count_block(base: int, head: int) -> dict:
+    return {"base": base, "head": head, "delta": head - base}
+
+
+def diff_metrics(base: ArchMetrics, head: ArchMetrics) -> dict:
+    """Pure diff of two snapshots → the frozen architectural-delta-v1 payload.
+
+    Deterministic: added/removed endpoints are sorted; fan-in shifts are ranked by
+    magnitude then symbol name. Lists are capped; counts are exact."""
+    added = sorted(f"{m} {p}" for (m, p) in (head.endpoints - base.endpoints))
+    removed = sorted(f"{m} {p}" for (m, p) in (base.endpoints - head.endpoints))
+
+    # Fan-in shifts: any symbol whose distinct-caller count changed (present in
+    # either snapshot; absent = 0). Ranked by |delta| desc, then FQN asc.
+    shifts: list[dict] = []
+    for sym in set(base.fan_in) | set(head.fan_in):
+        b = base.fan_in.get(sym, 0)
+        h = head.fan_in.get(sym, 0)
+        if b != h:
+            shifts.append({"symbol": sym, "base": b, "head": h, "delta": h - b})
+    shifts.sort(key=lambda s: (-abs(s["delta"]), s["symbol"]))
+
+    return {
+        "schema": ARCH_DELTA_SCHEMA,
+        "base_cir_hash": base.cir_hash,
+        "head_cir_hash": head.cir_hash,
+        "totals": {
+            "files": _count_block(base.file_count, head.file_count),
+            "symbols": _count_block(base.symbol_count, head.symbol_count),
+            "endpoints": _count_block(base.endpoint_count, head.endpoint_count),
+            "dependency_edges": _count_block(
+                base.dependency_edge_count, head.dependency_edge_count
+            ),
+        },
+        "endpoint_surface": {
+            "added_count": len(added),
+            "removed_count": len(removed),
+            "added": added[:_LIST_CAP],
+            "removed": removed[:_LIST_CAP],
+        },
+        "fan_in_shifts": {
+            "changed_count": len(shifts),
+            "shifts": shifts[:_LIST_CAP],
+        },
+        "provenance": (
+            "architectural_delta (D1): measured deltas derived from the CIR of two "
+            "snapshots. No breaking/non-breaking classification (D2), no verdict, "
+            "no ROI — the reviewer weighs the numbers."
+        ),
+    }
+
+
+def architectural_delta(
+    base_cir: "CanonicalRepositoryIR", head_cir: "CanonicalRepositoryIR"
+) -> dict:
+    """Convenience: extract both snapshots and diff them."""
+    return diff_metrics(extract_metrics(base_cir), extract_metrics(head_cir))

sourcecode/change_plan.py

@@ -0,0 +1,195 @@
+"""change_plan.py — D3 Architectural planning artifact (no code generation).
+
+Engineering Decision Support, Part B / D3. Given a change target, emits a
+deterministic, code-free PLAN: what a change to that symbol touches — the affected
+components (reverse-dependency closure), the tests that cover them, the endpoints
+whose contract is in scope, the rollback surface (files involved), and a review
+checklist. All of it is a PROJECTION of the graph + endpoint surface + test-path
+membership.
+
+Moat boundary (roadmap): this lists what to REVIEW; it emits no code, no
+implementation sequence beyond dependency depth, and no recommendation. Every item
+is a deterministic consequence of the model — "these components depend on X", not
+"you should change X this way". The engineer/agent decides and writes.
+
+Determinism: reads the CIR only; a bounded reverse-BFS with a fixed node cap and a
+stable ordering → same repo + same target → same plan.
+
+Reuse: target resolution + the endpoint blast come from `project_blast_radius`
+(the same machinery `impact-chain`/`pr-impact` use, so the plan is consistent with
+them). The affected-component / test / rollback views are derived from an uncapped
+(node-bounded) reverse-dependency closure over the SAME reverse graph, using the
+canonical `_all_callers_from_rg` traversal (skips structural containment + imports,
+normalizes DI-injection owners).
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sourcecode.canonical_ir import project_blast_radius
+from sourcecode.repository_ir import _all_callers_from_rg
+from sourcecode.security_posture import _graph_nodes
+from sourcecode.path_filters import is_test_path
+
+if TYPE_CHECKING:
+    from sourcecode.canonical_ir import CanonicalRepositoryIR
+
+CHANGE_PLAN_SCHEMA: str = "change-plan-v1"
+
+_LIST_CAP: int = 100
+# Safety bound on the reverse closure so a hub target cannot blow up the traversal.
+_NODE_CAP: int = 4000
+
+
+def _dependents_closure(
+    reverse_graph: dict, seeds: list[str], max_depth: int, node_cap: int
+) -> dict[str, int]:
+    """Bounded reverse-dependency closure: dependant FQN → shallowest depth.
+
+    BFS over the reverse graph via the canonical `_all_callers_from_rg` traversal
+    (so containment/imports are excluded and DI owners normalized, exactly as
+    blast-radius/impact-chain compute reach). Seeds themselves are removed."""
+    affected: dict[str, int] = {}
+    seen: set[str] = set(seeds)
+    queue: list[tuple[str, int]] = [(s, 0) for s in seeds]
+    while queue and len(affected) < node_cap:
+        fqn, depth = queue.pop(0)
+        if depth >= max_depth:
+            continue
+        for dep in _all_callers_from_rg(fqn, reverse_graph):
+            if dep not in seen:
+                seen.add(dep)
+                affected[dep] = depth + 1
+                queue.append((dep, depth + 1))
+    for s in seeds:
+        affected.pop(s, None)
+    return affected
+
+
+def _node_meta(cir: "CanonicalRepositoryIR") -> dict[str, dict]:
+    """fqn → {file, role, kind} for every graph node."""
+    out: dict[str, dict] = {}
+    for n in _graph_nodes(cir):
+        fqn = n.get("fqn")
+        if fqn:
+            out[str(fqn)] = {
+                "file": str(n.get("source_file") or ""),
+                "role": str(n.get("role") or "other"),
+                "kind": str(n.get("symbol_kind") or n.get("type") or ""),
+            }
+    return out
+
+
+def build_change_plan(
+    cir: "CanonicalRepositoryIR", target: str, *, max_depth: int = 4
+) -> dict:
+    """Build the deterministic change plan for `target` over `cir`."""
+    blast = project_blast_radius(cir, target, max_depth=max_depth)
+    resolution = blast.get("resolution", "not_found")
+
+    # Unresolvable target → return a plan-shaped resolution notice (never crash).
+    if resolution in ("not_found", "ambiguous_path") or not blast.get("matched_fqns"):
+        return {
+            "schema": CHANGE_PLAN_SCHEMA,
+            "target": target,
+            "resolution": resolution,
+            "message": blast.get("message", f"Target {target!r} not found."),
+            "candidates": blast.get("candidates", []),
+            "affected_components": {"count": 0, "components": []},
+            "covering_tests": {"count": 0, "tests": []},
+            "affected_endpoints": {"count": 0, "endpoints": []},
+            "rollback_surface": {"file_count": 0, "files": []},
+            "review_checklist": [],
+        }
+
+    seeds = list(blast["matched_fqns"])
+    meta = _node_meta(cir)
+    affected = _dependents_closure(cir.reverse_graph or {}, seeds, max_depth, _NODE_CAP)
+
+    prod: list[dict] = []
+    tests: list[dict] = []
+    files: set[str] = set()
+    for fqn, depth in affected.items():
+        m = meta.get(fqn, {})
+        f = m.get("file", "")
+        files.add(f)
+        entry = {"symbol": fqn, "role": m.get("role", "other"),
+                 "file": f, "depth": depth}
+        if is_test_path(f):
+            tests.append({"symbol": fqn, "file": f})
+        else:
+            prod.append(entry)
+    # Seed files are part of the rollback surface too (the target is being changed).
+    for s in seeds:
+        files.add(meta.get(s, {}).get("file", ""))
+    files.discard("")
+
+    prod.sort(key=lambda e: (e["depth"], e["symbol"]))
+    tests.sort(key=lambda e: e["symbol"])
+
+    endpoints_affected = blast.get("endpoints_affected", []) or []
+    ep_strings = sorted(
+        f"{e.get('method', '')} {e.get('path', '')}".strip()
+        for e in endpoints_affected if isinstance(e, dict)
+    )
+
+    rollback_files = sorted(files)
+
+    # Review checklist — structural facts phrased as review items, never advice.
+    checklist: list[str] = []
+    checklist.append(
+        f"Review {len(prod)} affected production component(s) reachable from the change."
+    )
+    if ep_strings:
+        checklist.append(
+            f"Re-verify the contract of {len(ep_strings)} endpoint(s) in the blast radius."
+        )
+    if tests:
+        checklist.append(
+            f"Run {len(tests)} covering test symbol(s) that reach the change."
+        )
+    else:
+        checklist.append(
+            "No covering tests reach the change — no existing test exercises this blast radius."
+        )
+    checklist.append(f"Rollback touches {len(rollback_files)} file(s).")
+    modules = blast.get("cross_module_impact") or []
+    if modules:
+        checklist.append(f"Change spans {len(modules)} module/subsystem(s).")
+    sec = blast.get("security_surface_affected") or []
+    if sec:
+        checklist.append(
+            f"{len(sec)} secured endpoint(s) in scope — re-check authorization."
+        )
+    txn = blast.get("transactional_boundaries_touched") or []
+    if txn:
+        checklist.append(f"{len(txn)} transactional boundary/boundaries in scope.")
+
+    return {
+        "schema": CHANGE_PLAN_SCHEMA,
+        "target": target,
+        "resolution": resolution,
+        "matched_symbols": sorted(seeds),
+        "affected_components": {
+            "count": len(prod),
+            "components": prod[:_LIST_CAP],
+        },
+        "covering_tests": {
+            "count": len(tests),
+            "tests": tests[:_LIST_CAP],
+        },
+        "affected_endpoints": {
+            "count": len(ep_strings),
+            "endpoints": ep_strings[:_LIST_CAP],
+        },
+        "rollback_surface": {
+            "file_count": len(rollback_files),
+            "files": rollback_files[:_LIST_CAP],
+        },
+        "review_checklist": checklist,
+        "provenance": (
+            "change_plan (D3): deterministic projection of the reverse-dependency "
+            "graph + endpoint surface + test-path membership. Lists what to review; "
+            "emits no code, no sequence beyond dependency depth, no recommendation."
+        ),
+    }

sourcecode/cli.py

@@ -235,6 +235,10 @@ _SUBCOMMANDS: frozenset[str] = frozenset(
         "spring-audit",
         # Request-body validation surface
         "validation",
+        # D1 architectural delta (before/after outcome measurement)
+        "delta",
+        # D2 contract-break detection
+        "contract-diff",
         # Spring impact chain
         "impact-chain",
         # PR blast-radius report
@@ -4620,6 +4624,263 @@ def validation_cmd(
     _nudge()
 
 
+# ── D1 Architectural Delta ────────────────────────────────────────────────────
+
+
+@app.command("delta")
+def delta_cmd(
+    base: Path = typer.Argument(
+        ...,
+        help="Repository checkout of the BEFORE state (base).",
+    ),
+    head: Path = typer.Argument(
+        ...,
+        help="Repository checkout of the AFTER state (head).",
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o",
+        help="Write output to a file instead of stdout.",
+    ),
+    format: str = typer.Option(
+        "json", "--format", "-f",
+        help="Output format: json (default) or yaml.",
+        show_default=True,
+    ),
+    copy: bool = typer.Option(
+        False, "--copy", "-c",
+        help="Copy output to system clipboard after a successful run.",
+    ),
+) -> None:
+    """Measure the architectural OUTCOME of a change: diff two checkouts.
+
+    \b
+    Builds the canonical IR for each checkout and reports the measured DELTAS —
+    files, symbols, endpoints, dependency edges, the HTTP-surface set change
+    (added/removed routes), and per-symbol fan-in shifts (e.g. "fan-in on
+    QueryController 14→3").
+
+    \b
+    This layer measures and stops. It emits no verdict, no ROI, and no
+    breaking/non-breaking classification (that is a separate contract-diff) — a
+    reviewer weighs the numbers. Deterministic: same two checkouts → same delta.
+
+    \b
+    Examples:
+      ask delta ./before ./after
+      ask delta /tmp/base-worktree /tmp/head-worktree -o delta.json
+    """
+    _enforce_format("delta", format)
+
+    for label, target in (("base", base), ("head", head)):
+        if not target.exists() or not target.is_dir():
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                f"'{target}' ({label}) is not a valid directory.",
+                path=str(target),
+                hint="Pass two existing repository checkouts: ask delta <base> <head>.",
+                expected="A directory path for each of base and head.",
+            )
+            raise typer.Exit(code=1)
+
+    from sourcecode.context_graph import ContextGraph
+    from sourcecode.architectural_delta import architectural_delta
+
+    _prog = Progress()
+    _prog.start("building base IR")
+    _base_cir = ContextGraph.build_from_root(base.resolve()).cir
+    _prog.update("building head IR")
+    _head_cir = ContextGraph.build_from_root(head.resolve()).cir
+    _prog.update("diffing snapshots")
+    data = architectural_delta(_base_cir, _head_cir)
+    _prog.finish()
+
+    _t = data["totals"]
+    output = _serialize_dict(data, format)
+    _emit_command_output(
+        output, output_path, copy,
+        success_msg=(
+            f"Architectural delta written to {output_path} "
+            f"(Δfiles {_t['files']['delta']:+d}, Δsymbols {_t['symbols']['delta']:+d}, "
+            f"Δendpoints {_t['endpoints']['delta']:+d}, "
+            f"{data['fan_in_shifts']['changed_count']} fan-in shifts)"
+        ),
+    )
+
+
+# ── D2 Contract-Break Detection ───────────────────────────────────────────────
+
+
+@app.command("contract-diff")
+def contract_diff_cmd(
+    base: Path = typer.Argument(
+        ...,
+        help="Repository checkout of the BEFORE state (base).",
+    ),
+    head: Path = typer.Argument(
+        ...,
+        help="Repository checkout of the AFTER state (head).",
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o",
+        help="Write output to a file instead of stdout.",
+    ),
+    format: str = typer.Option(
+        "json", "--format", "-f",
+        help="Output format: json (default) or yaml.",
+        show_default=True,
+    ),
+    copy: bool = typer.Option(
+        False, "--copy", "-c",
+        help="Copy output to system clipboard after a successful run.",
+    ),
+) -> None:
+    """Did this change break the public contract? Diff two checkouts.
+
+    \b
+    Projects the public contract (HTTP endpoints + public method signatures) for
+    each checkout and classifies every structural delta:
+      * breaking    — a removed endpoint/method, or a changed signature
+      * additive    — a new endpoint/method (backward compatible)
+      * non_breaking — reserved for constraint-loosening analysis (not yet emitted)
+
+    \b
+    Structural only: a changed signature is flagged breaking because the shape
+    differs — behavioural equivalence is NOT claimed. No ROI, no quality verdict.
+    Deterministic: same two checkouts → same result.
+
+    \b
+    Examples:
+      ask contract-diff ./before ./after
+      ask contract-diff /tmp/base-worktree /tmp/head-worktree -o contract.json
+    """
+    _enforce_format("contract-diff", format)
+
+    for label, target in (("base", base), ("head", head)):
+        if not target.exists() or not target.is_dir():
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                f"'{target}' ({label}) is not a valid directory.",
+                path=str(target),
+                hint="Pass two existing repository checkouts: ask contract-diff <base> <head>.",
+                expected="A directory path for each of base and head.",
+            )
+            raise typer.Exit(code=1)
+
+    from sourcecode.context_graph import ContextGraph
+    from sourcecode.contract_diff import contract_diff as _contract_diff
+
+    _prog = Progress()
+    _prog.start("building base IR")
+    _base_cir = ContextGraph.build_from_root(base.resolve()).cir
+    _prog.update("building head IR")
+    _head_cir = ContextGraph.build_from_root(head.resolve()).cir
+    _prog.update("diffing contracts")
+    data = _contract_diff(_base_cir, _head_cir)
+    _prog.finish()
+
+    _s = data["summary"]
+    output = _serialize_dict(data, format)
+    _emit_command_output(
+        output, output_path, copy,
+        success_msg=(
+            f"Contract diff written to {output_path} "
+            f"(status: {data['contract_status']}; "
+            f"{_s['breaking']} breaking, {_s['additive']} additive)"
+        ),
+    )
+
+
+# ── D3 Change Plan ────────────────────────────────────────────────────────────
+
+
+@app.command("plan")
+def plan_cmd(
+    target: str = typer.Argument(
+        ...,
+        help="Change target: class name (simple or FQN) or file path. "
+             "Examples: UserService, org.example.UserService, UserService.java",
+    ),
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository root to analyze (default: current directory).",
+    ),
+    depth: int = typer.Option(
+        4, "--depth",
+        help="Reverse-dependency BFS depth (default: 4).",
+        min=1, max=8,
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o",
+        help="Write output to a file instead of stdout.",
+    ),
+    format: str = typer.Option(
+        "json", "--format", "-f",
+        help="Output format: json (default) or yaml.",
+        show_default=True,
+    ),
+    copy: bool = typer.Option(
+        False, "--copy", "-c",
+        help="Copy output to system clipboard after a successful run.",
+    ),
+) -> None:
+    """Plan a change: what to review to implement a change to a target (no code).
+
+    \b
+    Projects a deterministic, code-free plan from the dependency graph:
+      * affected components — the reverse-dependency closure of the target
+      * covering tests      — existing tests that reach the change
+      * affected endpoints  — routes whose contract is in the blast radius
+      * rollback surface    — the files a change/rollback touches
+      * review checklist     — structural review items (facts, not advice)
+
+    \b
+    Emits no code and no implementation sequence beyond dependency depth. Every
+    item is a deterministic consequence of the model. Deterministic: same repo +
+    target → same plan.
+
+    \b
+    Examples:
+      ask plan UserService .
+      ask plan org.example.OrderService ./repo --depth 3
+    """
+    _enforce_format("plan", format)
+
+    target_dir = path.resolve()
+    if not target_dir.exists() or not target_dir.is_dir():
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"'{target_dir}' is not a valid directory.",
+            path=str(target_dir),
+            hint="Pass an existing repository directory: ask plan <target> <path>.",
+            expected="A directory path.",
+        )
+        raise typer.Exit(code=1)
+
+    from sourcecode.context_graph import ContextGraph
+    from sourcecode.change_plan import build_change_plan
+
+    _prog = Progress()
+    _prog.start("building IR")
+    _cir = ContextGraph.build_from_root(target_dir).cir
+    _prog.update("planning change")
+    data = build_change_plan(_cir, target, max_depth=depth)
+    _prog.finish()
+
+    if data.get("resolution") in ("not_found", "ambiguous_path"):
+        typer.echo(f"Note: {data.get('message', 'target not resolved')}", err=True)
+
+    output = _serialize_dict(data, format)
+    _emit_command_output(
+        output, output_path, copy,
+        success_msg=(
+            f"Change plan written to {output_path} "
+            f"({data['affected_components']['count']} components, "
+            f"{data['covering_tests']['count']} covering tests, "
+            f"{data['affected_endpoints']['count']} endpoints)"
+        ),
+    )
+
+
 # ── Spring Semantic Audit ─────────────────────────────────────────────────────
 
 

sourcecode/contract_diff.py

@@ -0,0 +1,186 @@
+"""contract_diff.py — D2 Compatibility & behavioural-contract break detection.
+
+Engineering Decision Support, Part B / D2. A change that COMPILES can still break
+the public contract — a removed endpoint, a renamed public method, a changed
+signature. This module projects a `public-contract` view from two CIR snapshots
+and classifies each structural delta as breaking / additive (with a `non_breaking`
+bucket reserved for the D2-b constraint-loosening analysis).
+
+Honesty boundary (roadmap): this reports STRUCTURAL contract deltas only. It does
+NOT prove behavioural equivalence — a "signature changed" is flagged breaking
+because the shape differs, not because we proved a caller breaks; and a `non_breaking`
+verdict is never invented from a structural change we cannot prove is safe. It is a
+diff, not a semantic-compatibility prover.
+
+Determinism: `extract_public_contract` reads the CIR only; `diff_contract` is a
+pure function of two contract snapshots; same two snapshots → byte-identical output.
+
+Contract surface (increment D2-a):
+  * endpoints        — the HTTP surface, keyed (METHOD, path); value = handler
+                       signature. The route IS the contract, so a handler rename
+                       with an identical signature is NOT a contract change.
+  * public methods   — public, non-test methods/constructors, keyed by FQN; value
+                       = signature. Endpoint handlers are excluded here (their
+                       contract is the route, already covered above — no double count).
+
+Deferred to D2-b: validation-constraint tightening/loosening (the source of most
+real `non_breaking` verdicts) and parameter optionalization. The `non_breaking`
+bucket is declared now so consumers can rely on the taxonomy; it is populated when
+that analysis lands.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from sourcecode.path_filters import is_test_path
+from sourcecode.security_posture import _graph_nodes
+
+if TYPE_CHECKING:
+    from sourcecode.canonical_ir import CanonicalRepositoryIR
+
+CONTRACT_DIFF_SCHEMA: str = "contract-diff-v1"
+
+_LIST_CAP: int = 50
+
+# Callable member kinds that form the public API surface. `endpoint` is excluded
+# on purpose — an HTTP handler's contract is its ROUTE (covered by the endpoint
+# surface), not its Java FQN, so listing it here too would double-report.
+_API_METHOD_KINDS: frozenset[str] = frozenset({"method", "constructor"})
+
+
+@dataclass(frozen=True)
+class PublicContract:
+    """The externally-observable contract projected from one CIR."""
+
+    # (METHOD, path) → handler signature string, e.g. "(String)->String"
+    endpoints: dict[tuple[str, str], str]
+    # public method/ctor FQN → signature string
+    public_methods: dict[str, str]
+
+
+def _node_signatures(cir: "CanonicalRepositoryIR") -> dict[str, str]:
+    """fqn → signature for every graph node (used to resolve handler signatures)."""
+    return {
+        str(n.get("fqn")): str(n.get("signature") or "")
+        for n in _graph_nodes(cir)
+        if n.get("fqn")
+    }
+
+
+def extract_public_contract(cir: "CanonicalRepositoryIR") -> PublicContract:
+    """Project a CIR into its public contract. Reads the CIR only."""
+    sig_by_fqn = _node_signatures(cir)
+
+    endpoints: dict[tuple[str, str], str] = {}
+    for ep in (cir.endpoints or []):
+        key = (str(ep.method).upper(), str(ep.path))
+        endpoints[key] = sig_by_fqn.get(ep.handler_symbol, "")
+
+    public_methods: dict[str, str] = {}
+    for n in _graph_nodes(cir):
+        if n.get("type") != "method":
+            continue
+        if n.get("symbol_kind") not in _API_METHOD_KINDS:
+            continue
+        if "public" not in (n.get("modifiers") or []):
+            continue
+        if is_test_path(str(n.get("source_file") or "")):
+            continue
+        fqn = str(n.get("fqn") or "")
+        if fqn:
+            public_methods[fqn] = str(n.get("signature") or "")
+
+    return PublicContract(endpoints=endpoints, public_methods=public_methods)
+
+
+def _finding(element_type: str, ident: str, change: str,
+             base_sig: str, head_sig: str, classification: str) -> dict:
+    out: dict = {
+        "element": element_type,
+        "id": ident,
+        "change": change,
+        "classification": classification,
+    }
+    if base_sig or head_sig:
+        out["base_signature"] = base_sig
+        out["head_signature"] = head_sig
+    return out
+
+
+def diff_contract(base: PublicContract, head: PublicContract) -> dict:
+    """Pure diff of two contracts → the frozen contract-diff-v1 payload.
+
+    Classification (structural, conservative):
+      removed            → breaking   (the element is gone)
+      signature_changed  → breaking   (shape differs; behavioural compat NOT claimed)
+      added              → additive   (backward-compatible addition)
+    `non_breaking` stays empty until the D2-b constraint-loosening analysis lands.
+    """
+    breaking: list[dict] = []
+    additive: list[dict] = []
+    non_breaking: list[dict] = []  # reserved (D2-b)
+
+    # --- endpoints (keyed by METHOD path) ---
+    b_eps, h_eps = base.endpoints, head.endpoints
+    for key in b_eps.keys() - h_eps.keys():
+        breaking.append(_finding("endpoint", f"{key[0]} {key[1]}", "removed", "", "", "breaking"))
+    for key in h_eps.keys() - b_eps.keys():
+        additive.append(_finding("endpoint", f"{key[0]} {key[1]}", "added", "", "", "additive"))
+    for key in b_eps.keys() & h_eps.keys():
+        if b_eps[key] != h_eps[key]:
+            breaking.append(_finding(
+                "endpoint", f"{key[0]} {key[1]}", "signature_changed",
+                b_eps[key], h_eps[key], "breaking",
+            ))
+
+    # --- public methods (keyed by FQN) ---
+    b_m, h_m = base.public_methods, head.public_methods
+    for fqn in b_m.keys() - h_m.keys():
+        breaking.append(_finding("method", fqn, "removed", "", "", "breaking"))
+    for fqn in h_m.keys() - b_m.keys():
+        additive.append(_finding("method", fqn, "added", "", "", "additive"))
+    for fqn in b_m.keys() & h_m.keys():
+        if b_m[fqn] != h_m[fqn]:
+            breaking.append(_finding(
+                "method", fqn, "signature_changed", b_m[fqn], h_m[fqn], "breaking",
+            ))
+
+    breaking.sort(key=lambda f: (f["element"], f["change"], f["id"]))
+    additive.sort(key=lambda f: (f["element"], f["change"], f["id"]))
+
+    # Repo-level structural status: a measured fact (≥1 breaking change exists),
+    # not an ROI/quality opinion. "breaking" > "additive" > "unchanged".
+    if breaking:
+        status = "breaking"
+    elif additive:
+        status = "additive"
+    else:
+        status = "unchanged"
+
+    return {
+        "schema": CONTRACT_DIFF_SCHEMA,
+        "contract_status": status,
+        "summary": {
+            "breaking": len(breaking),
+            "additive": len(additive),
+            "non_breaking": len(non_breaking),
+        },
+        "breaking": breaking[:_LIST_CAP],
+        "additive": additive[:_LIST_CAP],
+        "non_breaking": non_breaking,
+        "provenance": (
+            "contract_diff (D2): STRUCTURAL public-contract diff of two CIR "
+            "snapshots (endpoints + public methods). A signature change is flagged "
+            "breaking because the shape differs — behavioural equivalence is NOT "
+            "claimed. non_breaking (constraint loosening / param optionalization) "
+            "is reserved for D2-b. No ROI, no quality verdict."
+        ),
+    }
+
+
+def contract_diff(
+    base_cir: "CanonicalRepositoryIR", head_cir: "CanonicalRepositoryIR"
+) -> dict:
+    """Convenience: extract both contracts and diff them."""
+    return diff_contract(extract_public_contract(base_cir), extract_public_contract(head_cir))

sourcecode/format_contract.py

@@ -29,6 +29,8 @@ FORMAT_REGISTRY: "dict[str, tuple[str, ...]]" = {
     "endpoints": ("json", "yaml"),
     "export": ("json", "yaml"),
     "validation": ("json", "yaml"),
+    "delta": ("json", "yaml"),
+    "contract-diff": ("json", "yaml"),
     "impact-chain": ("json", "yaml"),
     "pr-impact": ("text", "json"),
     "migrate-check": ("json", "text"),

sourcecode/repository_ir.py

@@ -190,6 +190,13 @@ _STATIC_FINAL_STR_RE = re.compile(
     r'(?:public|protected|private)?\s*static\s+final\s+String\s+(\w+)\s*=\s*"([^"]*)"'
 )
 
+# Full right-hand side up to the terminating ';' — captures concat/const-ref
+# expressions (`"/{" + DB_PATH_PARAM_NAME + "}/query/v2"`) the literal-only
+# regex above truncates. Resolved by _resolve_const_concat in _collect_file_constants.
+_STATIC_FINAL_STR_DECL_RE = re.compile(
+    r'(?:public|protected|private)?\s*static\s+final\s+String\s+(\w+)\s*=\s*([^;]+);'
+)
+
 _ENDPOINT_ANNOTATIONS: frozenset[str] = frozenset({
     # Spring MVC
     "@GetMapping", "@PostMapping", "@PutMapping", "@DeleteMapping",
@@ -3127,14 +3134,35 @@ def _collect_file_constants(source: str) -> dict[str, str]:
     if 'static final String' not in source:
         return {}
     # Scan only candidate lines (skips full-source regex over 100KB files).
-    # Running _STATIC_FINAL_STR_RE over the whole source is O(source_size) due to
-    # optional modifier group backtracking; per-line match is far cheaper.
-    constants: dict[str, str] = {}
+    # Running the regex over the whole source is O(source_size) due to optional
+    # modifier group backtracking; per-line match is far cheaper.
+    #
+    # F3: a constant value may itself be a concat / constant-ref expression
+    # (`ROOT_PATH = "/{" + DB_PATH_PARAM_NAME + "}/query/v2"`). Capturing only the
+    # first string literal truncates it (`/{`) and collapses every composed
+    # @Path built on it. Capture the full RHS, then fold via _resolve_const_concat
+    # to a fixpoint so constants defined in terms of earlier/later constants resolve.
+    raw: dict[str, str] = {}
     for line in source.splitlines():
         if 'static' in line and 'final' in line and 'String' in line and '=' in line and '"' in line:
-            m = _STATIC_FINAL_STR_RE.search(line)
+            m = _STATIC_FINAL_STR_DECL_RE.search(line)
             if m:
-                constants[m.group(1)] = m.group(2)
+                raw[m.group(1)] = m.group(2).strip()
+
+    constants: dict[str, str] = {}
+    # Fixpoint: each pass resolves any raw expr whose referenced constants are
+    # now known. Bounded by the number of constants (chains resolve one hop/pass).
+    for _ in range(len(raw) + 1):
+        progress = False
+        for name, expr in raw.items():
+            if name in constants:
+                continue
+            val = _resolve_const_concat(expr, constants)
+            if val is not None:
+                constants[name] = val
+                progress = True
+        if len(constants) == len(raw) or not progress:
+            break
     return constants
 
 

{sourcecode-2.5.19.dist-info → sourcecode-2.5.20.dist-info}/METADATA

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

@@ -1,6 +1,7 @@
-sourcecode/__init__.py,sha256=lv_mMr5Y5s1U1_CJa-6pkjbnlCz4lXMFrxs9SHb4qJs,309
+sourcecode/__init__.py,sha256=1cAIVnSZ0uksrKFoCUTDgBevYywvPmcJwO80o39gmwI,309
 sourcecode/adaptive_scanner.py,sha256=yJBKjNpkY6bpueYJ2YnRezen3sYZDecEt7WaaNWdqug,9466
 sourcecode/archetype.py,sha256=d7yoN6Tj4OBj-VgSMPEKg4WF9H8FypnZ5A6AkUh5oIE,34484
+sourcecode/architectural_delta.py,sha256=jzlY1HFXAemewk_xnuD5Y2YnkxCUqfneWcMfvTTnyfE,6312
 sourcecode/architecture_analyzer.py,sha256=GFc4ek-s1IHWM7pl-0L32WahZ93AmDgrAMcOuBKA5Dk,61463
 sourcecode/architecture_summary.py,sha256=BVVRHd952cjRhjHnR6CPrvKgaa-tdM16l-pBi1yDCPs,32395
 sourcecode/ast_extractor.py,sha256=ZwHN3Y0iRp2gpv3t5Nm5uvX7Xw1KtULCJPZqKpZQRAE,51255
@@ -8,15 +9,17 @@ sourcecode/cache.py,sha256=1V3vsaODAa2UBJAC0xpvxpmRdriCezQx5Q8JCcfgziE,31892
 sourcecode/call_surface.py,sha256=fiqYfHooxN1fX9oQoysq1LS3LoZcobhyUNjAGEZKpwk,4148
 sourcecode/caller_metrics.py,sha256=HG8RCOkpzzsEGdnMRob6byrwjoj5__t0TEsBj4yR7ks,2574
 sourcecode/canonical_ir.py,sha256=LdP_Ri3rl0M5p-MY0ypVvQwhq1WuUF1FmaHid7zyzEg,29807
+sourcecode/change_plan.py,sha256=MNgNyu4zrLGvBBaXPwyCh-T2ZGaUQX3Hm4W87uuhZ3w,7750
 sourcecode/cir_graphs.py,sha256=9G0HHj1kw2325IDyzo2OpX73BNswEckecf4MZUXB4JM,12078
 sourcecode/classifier.py,sha256=JBzPwSSrDG-tUHAbcKB678HRbjLpD-ohzbzzO62mgpo,20114
-sourcecode/cli.py,sha256=QH7K8Uw19z5o7eXFPvVcC8ZA1KNUHS0bVL_IdOYC2CQ,324702
+sourcecode/cli.py,sha256=BfgF0cHLzBISeAJWbbggS9ZFG-6FchHP54xVXAYX6rs,334366
 sourcecode/code_notes_analyzer.py,sha256=EJemNCNc9Dn-1RZYu-aNbK0ELzmsyC4s6FdHi3XyNEI,9392
 sourcecode/confidence_analyzer.py,sha256=vnbPI-20FnHdjO6STxHW8fbaxmB4A7y58io63ibFZjc,21586
 sourcecode/context_cache.py,sha256=maws79rLKDwyZ7c9Q2LwlIxqZHRFlaKzErtO3mglWoA,25036
 sourcecode/context_graph.py,sha256=i2kOX3XiaCqcR20ojbUnqoX-hJbMyLNYc7rl-n15bwE,46426
 sourcecode/context_scorer.py,sha256=QpChSpsmaAYz91rXA4Ue5xzQmNz_ZboZN09YOHScq1U,14679
 sourcecode/context_summarizer.py,sha256=cI2TZMvEhl0BEma12VtPaX6z03ZVBAetVzuK5GaCOvg,6852
+sourcecode/contract_diff.py,sha256=M4v2lY6QWwdtNqMAAavtAIJQfyzydw0lHnnPi_Q2Keg,7751
 sourcecode/contract_model.py,sha256=nRxJKPMs1VHwFTa8AVXhGmaLjti3Lr2sjHDpWgv1bfE,3917
 sourcecode/contract_pipeline.py,sha256=KfSgNkebcL5bYx3TDzEnvPLcTgm_JifJOAqqR8-0zb4,29774
 sourcecode/coverage_parser.py,sha256=X9scuUWxacahYTrTBGea2Ku-sf-WCVcnc9OEB35_3IU,19340
@@ -32,7 +35,7 @@ sourcecode/evidence_provider.py,sha256=GSSL44JEaouO5AHks2sB3d1YvC9xIKIld1yBYxZpX
 sourcecode/explain.py,sha256=HnHWVTNNf9fzeR3FP-A-eXKeKZvBcUEuODgIO3rJQkQ,22312
 sourcecode/file_chunker.py,sha256=3vkM3mDQ5eE_yTPvUgjyjpGFBIjkW6_mrBmIbrylnA8,16444
 sourcecode/file_classifier.py,sha256=A0fEABqtfVu1MfoaxnPAvGpZgneGgVXlJDhT74NYXxE,15314
-sourcecode/format_contract.py,sha256=1cTNqwP8geA2hbQoBHUPgX3_vSh3l8guJT_jmgEnFF8,3466
+sourcecode/format_contract.py,sha256=G2e7alugMEZXHtzbW4VMEjPciHlA1OaeLIt60a77jWA,3536
 sourcecode/fqn_utils.py,sha256=XLU7zDkNBXz_RZkIUNfpPmp1nekWtqP-fxV92tDV1vg,2158
 sourcecode/git_analyzer.py,sha256=JStxTQXNjBWi_wLdwhsZs9mT-v50cSJIz4Agzn6Kh9I,13362
 sourcecode/graph_analyzer.py,sha256=lp0eB1PWC20BYF-GpPhAyegRpKrUKgOmXZIcZSIX_Ks,65777
@@ -57,7 +60,7 @@ 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=2Za5B4ar0iqPkdlHHttmhcHO4ErTXmg8TyOY3tAO2CA,312842
+sourcecode/repository_ir.py,sha256=NwPEyYaDyJihLuyfIx-aIpZpY5OIXlJhvLS7QEnf-u0,314200
 sourcecode/ris.py,sha256=Hw8TakTQ6hku-Abf2k8954NwkrH_sP73_8wVH8x5khc,22079
 sourcecode/runtime_classifier.py,sha256=uTAD6BDCiBLUZEDRfqk718kM4RTT_vAbfkcOI2_Xx58,18432
 sourcecode/scanner.py,sha256=z3CV0rcGunu0Y8mpNgp07wI7nxT0pxw1BkXRRtI0Rpo,9609
@@ -138,8 +141,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.19.dist-info/METADATA,sha256=m52i-fTO7exXgHCc5tUJyv2ne4dBOOAtKThagdx4dSo,10852
-sourcecode-2.5.19.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-2.5.19.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
-sourcecode-2.5.19.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-2.5.19.dist-info/RECORD,,
+sourcecode-2.5.20.dist-info/METADATA,sha256=9dtf9qcmo6vo4bdkBGYGcRLAoSocKyRQoQ0ivpxbcTs,10852
+sourcecode-2.5.20.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-2.5.20.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
+sourcecode-2.5.20.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-2.5.20.dist-info/RECORD,,