sourcecode 2.5.18__tar.gz → 2.5.20__tar.gz

{sourcecode-2.5.18 → sourcecode-2.5.20}/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## [2.5.20] — 2026-07-21
+
+**Engineering Decision Support — Part A, F3: JAX-RS composed-path canonicalization.**
+Composed `@Path` templates built on a constant whose own value is a concatenation
+(`ROOT_PATH = "/{" + DB_PATH_PARAM_NAME + "}/query/v2"`) produced malformed endpoint
+paths — the class prefix collapsed to `/{`, yielding `/{`, `/{/tx`, `/{/tx/{txId}`.
+Correct endpoint identity is the key of every impact / blast-radius / delta decision,
+so a malformed path corrupts each of them. A pure extraction-correctness fix (no new
+inference). Full suite (3545 passed, 5 skipped) with zero control-repo drift.
+
+### Fixed
+
+- **F3 — `_collect_file_constants` now folds concat / constant-ref constant values.**
+  The collector captured only the FIRST string literal of a `static final String`
+  declaration (`_STATIC_FINAL_STR_RE`), so a constant defined as an expression
+  (`"/{" + DB_PATH_PARAM_NAME + "}/query/v2"`) was stored truncated as `/{`. Every
+  `@Path(SomeResource.ROOT_PATH)` class prefix built on it then collapsed, and each
+  composed method path inherited the collapse. The collector now captures the full
+  right-hand side (`_STATIC_FINAL_STR_DECL_RE`, up to `;`) and resolves it through
+  the existing `_resolve_const_concat`, iterating to a fixpoint so a constant defined
+  in terms of another (in either declaration order) resolves. Inline method-level
+  concat (`@Path("tx/{" + TX_ID_PATH_PARAM_NAME + "}")`) already resolved via
+  `_resolve_ann_path_expr`; this was the one remaining gap. Measured on neo4j
+  (`QueryResource`): 8 malformed paths → canonical (`/{databaseName}/query/v2`,
+  `/{databaseName}/query/v2/tx/{txId}/commit`). Fleet A/B: neo4j corrected, the other
+  7 control repos byte-identical — the fix only ever *completes* a truncated value,
+  never rewrites a literal one.
+
+## [2.5.19] — 2026-07-20
+
+**Engineering Decision Support — Part A, F2: manual validation (guard clauses) is
+now a recognised validation source.** A repo that validates request bodies with
+hand-written null/empty guards instead of Bean Validation was reported as having no
+validation — a confirmed false negative. F2 reuses the β `GuardClause` atom already
+in the Semantic IR rather than adding a parallel extractor. Full suite (3542 passed,
+5 skipped) confirms confinement.
+
+### Fixed
+
+- **F2 — β guard-clause extraction now covers endpoint-kind handler bodies.**
+  `_extract_guard_facts` scanned only `symbol_kind in {method, constructor}`; an
+  annotation-classified handler (`@PostMapping …`) surfaces as `symbol_kind="endpoint"`,
+  so **every guard living in a handler body was silently dropped** — the β atom
+  existed, its coverage did not. The scan now includes endpoint-kind symbols (the same
+  `_scan_guard_clauses`, widened to a kind it skipped). This also lets the impact
+  engine see handler-entry guards it was previously blind to (measured: additive
+  behavioural notes only, each backed by a real atom — e.g. keycloak 34 handler types
+  gain a "null/empty guard" note; petclinic unchanged).
+
+### Added
+
+- **F2 — `manual_validation` request-body pattern in `validation_inference`.** When no
+  Bean Validation is present but body handlers guard their input with null/empty β
+  guard clauses that early-exit, the `validation` command now classifies
+  `manual_validation` (Likely) with a per-endpoint `manual_guard` finding, instead of
+  the old `no_validation_detected`. Scoped to `null_check`/`empty_check`: β's `other`
+  test kind lumps range checks with non-validation guards (availability, memoization,
+  preconditions), so counting it would inflate false positives — range validation is an
+  honest, documented under-report. Bean validation still takes repo-level precedence; a
+  handler that both `@Valid`-s and hand-guards is bean-validated, not manual.
+
+### Validation (real-repo field check)
+
+- **True positive** — eureka `ApplicationResource#addInstance` (POST) validates its
+  request body with an `isBlank(...)` / `== null` guard cascade; previously reported as
+  unvalidated, now `manual_validation`.
+- **True negative preserved** — neo4j stays `no_validation_detected`: its handler guards
+  are database-availability checks (`if (isDatabaseNotAvailable(db)) return`, β
+  `other`), which the `other`-exclusion correctly refuses to call input validation.
+- **No drift** — petclinic stays `bean_validation_active`, jobrunr stays
+  `no_validation_detected`.
+
 ## [2.5.18] — 2026-07-20
 
 **Engineering Decision Support — Part A, F1: standalone OpenAPI specs now reach the

{sourcecode-2.5.18 → sourcecode-2.5.20}/PKG-INFO

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

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

{sourcecode-2.5.18 → sourcecode-2.5.20}/src/sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "2.5.18"
+__version__ = "2.5.20"

sourcecode-2.5.20/src/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-2.5.20/src/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."
+        ),
+    }