sourcecode 2.5.3__py3-none-any.whl → 2.5.5__py3-none-any.whl

sourcecode/reconciliation.py

@@ -0,0 +1,346 @@
+"""reconciliation.py — Evidence Reconciliation Layer (F-1).
+
+Cross-validates independent evidence views BEFORE a result is narrated:
+
+    evidence views  →  consistency rules  →  positively-detected contradictions
+
+Each analyzer (call graph, endpoint index, …) is treated as an evidence
+provider whose view may be incomplete. A reconciliation rule fires only on a
+*provable* self-contradiction between two views — never on absence alone —
+and its output downgrades confidence and names the gap instead of letting the
+narrative assert an answer the evidence does not support.
+
+Rules are pure functions over frozensets of symbols: no I/O, no parsing, no
+framework-name branching (annotation tables come from the open-standard
+declarative sets in repository_ir — VAI-safe). New rules append to the
+registry of the relevant query surface; consumers surface each finding as a
+blind spot + warning.
+
+Rule registry (impact queries):
+    endpoint_coverage — a class in the call chain declares HTTP handler
+        methods (Spring MVC / JAX-RS verb annotations) but the endpoint index
+        modeled NO route for it. The call graph and the endpoint index are
+        contradicting each other; `endpoints_affected` under-reports real HTTP
+        exposure (e.g. JAX-RS sub-resource locator chains the route extractor
+        cannot compose). First shipped instance of F-1 (SIM-2, keycloak
+        simulacro 2026-07-16).
+
+Rule registry (extraction):
+    parse_coverage — a scanned Java file provably declares a type (masked
+        source matches a type-declaration keyword) but symbol extraction
+        produced NOTHING for it. The file inventory and the symbol index are
+        contradicting each other; every symbol in that file is silently
+        invisible to the graph, callers and endpoints (P1-E: legal-Java
+        declarations the regex extractor cannot bind, e.g. `public class\n
+        Name` split across lines, Unicode type identifiers).
+
+Rule registry (architecture):
+    layer_language_coherence — a directory-name-matched layer holds NO file in
+        the runtime that carries the rest of the claimed pattern, while being
+        owned by a DIFFERENT runtime. The layer table and the file-language
+        census are contradicting each other: the "architecture" spans two
+        subsystems (SIM-3: keycloak's "MVC … view layer" was a React SPA, zero
+        Java files, sitting beside a 1088-file Java model).
+
+Never raises. Empty evidence → no findings.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ReconciliationFinding:
+    """One positively-detected contradiction between two evidence views."""
+    rule: str                 # stable rule id, e.g. "endpoint_coverage"
+    symbols: tuple[str, ...]  # symbols the contradiction is anchored to
+    detail: str               # one-sentence human/agent-readable statement
+
+    def to_dict(self) -> dict:
+        return {
+            "rule": self.rule,
+            "symbols": list(self.symbols),
+            "detail": self.detail,
+        }
+
+
+def http_handler_classes(cir) -> frozenset[str]:
+    """Classes with at least one method carrying an HTTP handler annotation.
+
+    Independent evidence of "this class serves HTTP" derived straight from the
+    per-symbol annotation facts — deliberately NOT derived from the endpoint
+    index, so the two views can be reconciled against each other.
+    """
+    from sourcecode.repository_ir import _ENDPOINT_ANNOTATIONS
+
+    raw = getattr(cir, "_raw_ir", None) or {}
+    nodes = (raw.get("graph") or {}).get("nodes") or []
+    out: set[str] = set()
+    for node in nodes:
+        if not isinstance(node, dict):
+            continue
+        fqn = node.get("fqn") or ""
+        if "#" not in fqn:
+            continue
+        anns = node.get("annotations") or []
+        if any(a in _ENDPOINT_ANNOTATIONS for a in anns):
+            out.add(fqn.split("#", 1)[0])
+    return frozenset(out)
+
+
+def _rule_endpoint_coverage(
+    chain_classes: frozenset[str],
+    handler_classes: frozenset[str],
+    modeled_classes: frozenset[str],
+) -> list[ReconciliationFinding]:
+    """Chain class declares HTTP handlers but the endpoint index has no route for it.
+
+    Fires only on total absence from the index (extractor could not model ANY
+    route for a class that provably declares handlers). A class that IS in the
+    index but contributes only a subset of its endpoints to a query is the
+    intentional method-precision rule, not a contradiction — never flagged.
+    """
+    unmapped = sorted((chain_classes & handler_classes) - modeled_classes)
+    if not unmapped:
+        return []
+    return [
+        ReconciliationFinding(
+            rule="endpoint_coverage",
+            symbols=tuple(unmapped),
+            detail=(
+                f"{len(unmapped)} class(es) in the call chain declare HTTP handler "
+                "methods but the endpoint index modeled no route for them — "
+                "endpoints_affected under-reports real HTTP exposure."
+            ),
+        )
+    ]
+
+
+def reconcile_impact_evidence(
+    *,
+    chain_classes: frozenset[str],
+    handler_classes: frozenset[str],
+    modeled_classes: frozenset[str],
+) -> list[ReconciliationFinding]:
+    """Run all impact-query reconciliation rules. Never raises.
+
+    Args:
+        chain_classes:   classes of every seed + caller in the resolved chain.
+        handler_classes: classes with HTTP-handler annotation evidence
+                         (from http_handler_classes(cir)).
+        modeled_classes: classes the endpoint index has ≥1 route for
+                         (endpoint_index.controller_fqns).
+    """
+    findings: list[ReconciliationFinding] = []
+    try:
+        findings.extend(
+            _rule_endpoint_coverage(chain_classes, handler_classes, modeled_classes)
+        )
+    except Exception:
+        pass
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# Extraction-time reconciliation (file inventory × symbol index)
+# ---------------------------------------------------------------------------
+
+# A type-declaration keyword followed by the start of an identifier. Applied to
+# COMMENT/STRING-MASKED source only, so `/* class Ghost */` and "class" inside
+# a string literal never match. `record` is a contextual keyword; requiring a
+# following identifier keeps `record = ...` assignments out, and the rule is
+# only ever consulted for files that yielded zero symbols — where a stray
+# match would still be pointing at real, unmodeled Java.
+_TYPE_DECL_RE = re.compile(r"\b(?:class|interface|enum|record)\s+\w")
+
+
+def declares_java_type(masked_source: str) -> bool:
+    """True if comment/string-masked Java source declares a type.
+
+    The caller masks (repository_ir._mask_java) so this stays a pure text
+    predicate with no parsing dependency.
+    """
+    return bool(_TYPE_DECL_RE.search(masked_source))
+
+
+def _rule_parse_coverage(
+    type_decl_files: frozenset[str],
+    extracted_files: frozenset[str],
+) -> list[ReconciliationFinding]:
+    """File declares a type but symbol extraction produced nothing for it.
+
+    Fires only on total extraction absence for the file — a file that yielded
+    at least one symbol is never flagged (partial member loss is a different,
+    weaker signal this rule does not claim to detect).
+    """
+    lost = sorted(type_decl_files - extracted_files)
+    if not lost:
+        return []
+    return [
+        ReconciliationFinding(
+            rule="parse_coverage",
+            symbols=tuple(lost),
+            detail=(
+                f"{len(lost)} Java file(s) declare a type but produced no symbols — "
+                "their classes and methods are invisible to the graph, callers and "
+                "endpoints."
+            ),
+        )
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Architecture reconciliation (layer table × file-language census)
+# ---------------------------------------------------------------------------
+
+# Source extension → RUNTIME FAMILY. Grouping by runtime, not by extension, is
+# what makes the rule correct: a Kotlin `view/` beside Java `model/` is ONE
+# system (same runtime, direct interop) and must not be called a contradiction,
+# while a TypeScript `view/` beside them is a separate program. Extensions
+# absent here (.html/.ftl/.jsp/.css/.xml …) are deliberately unmapped: a
+# template or asset carries no runtime of its own, so it can never contradict a
+# claim — that carve-out is what keeps a genuine Spring-MVC `templates/` view
+# layer intact.
+_RUNTIME_FAMILY: dict[str, str] = {
+    ".java": "jvm", ".kt": "jvm", ".kts": "jvm", ".scala": "jvm", ".groovy": "jvm",
+    ".js": "js", ".jsx": "js", ".ts": "js", ".tsx": "js", ".mjs": "js", ".cjs": "js",
+    ".py": "python",
+    ".go": "go",
+    ".rs": "rust",
+    ".rb": "ruby",
+    ".cs": "dotnet",
+    ".php": "php",
+    ".swift": "swift",
+}
+
+# Patterns that describe REPO COMPOSITION rather than one program's internal
+# architecture — their layers are SUPPOSED to span runtimes, so the coherence
+# rule must never fire on them. (mvc/layered/onion/hexagonal/clean are claims
+# about a single program and must hold together in one runtime.)
+_CROSS_RUNTIME_PATTERNS: frozenset[str] = frozenset({
+    "fullstack", "microservices", "monorepo",
+})
+
+
+def runtime_census(layer_files: dict[str, list[str]]) -> dict[str, dict[str, int]]:
+    """{layer -> {runtime_family -> file count}} — the language evidence view.
+
+    Files whose extension carries no runtime (templates, assets, config) are
+    simply absent from the census; a layer made only of them yields {}.
+    """
+    out: dict[str, dict[str, int]] = {}
+    for layer, files in layer_files.items():
+        counts: dict[str, int] = {}
+        for f in files:
+            fam = _RUNTIME_FAMILY.get(Path(str(f)).suffix.lower())
+            if fam:
+                counts[fam] = counts.get(fam, 0) + 1
+        out[layer] = counts
+    return out
+
+
+def _rule_layer_language_coherence(
+    pattern: str,
+    census: dict[str, dict[str, int]],
+    repo_runtimes: dict[str, int],
+) -> list[ReconciliationFinding]:
+    """A claimed layer is owned by a different runtime than the repo it describes.
+
+    The dominant runtime is taken from the WHOLE repo, not from the matched
+    layers: which directories happen to match a keyword table is exactly the
+    thing under suspicion, so it cannot also be the arbiter. (Measured: on a
+    Java backend beside a React SPA, layer-local dominance can invert — the SPA
+    out-matches the backend's one matched layer and the JAVA layer gets flagged.)
+
+    A layer is INCOHERENT iff it holds ZERO files of the repo's runtime AND at
+    least one file of another — it is a different program, not a facet of this
+    one. A layer with no runtime files at all (templates, assets) is never
+    flagged: it does not contradict, it just does not attest.
+
+    Silent for cross-runtime patterns, whose layers are meant to span runtimes.
+    """
+    if pattern in _CROSS_RUNTIME_PATTERNS or len(census) < 2:
+        return []
+    if len(repo_runtimes) < 2:
+        return []  # single-runtime repo — nothing to contradict
+
+    dominant = max(sorted(repo_runtimes), key=lambda f: repo_runtimes[f])
+
+    incoherent = sorted(
+        layer for layer, counts in census.items()
+        if not counts.get(dominant) and any(counts.values())
+    )
+    if not incoherent:
+        return []
+    return [
+        ReconciliationFinding(
+            rule="layer_language_coherence",
+            symbols=tuple(incoherent),
+            detail=(
+                f"{len(incoherent)} layer(s) of the '{pattern}' claim hold no "
+                f"{dominant} file while the rest of the pattern is {dominant} — "
+                "the claim spans two separate programs, so it does not describe "
+                "one architecture."
+            ),
+        )
+    ]
+
+
+def reconcile_architecture_evidence(
+    *,
+    pattern: str,
+    layer_files: dict[str, list[str]],
+    repo_files: "list[str]",
+) -> list[ReconciliationFinding]:
+    """Run architecture reconciliation rules. Never raises.
+
+    Args:
+        pattern:     candidate pattern name (e.g. "mvc").
+        layer_files: {layer -> files matched for that layer}.
+        repo_files:  every source file considered — supplies the repo's own
+                     runtime, the arbiter of which layers belong to the claim.
+    """
+    findings: list[ReconciliationFinding] = []
+    try:
+        repo_runtimes = runtime_census({"_repo": list(repo_files)})["_repo"]
+        findings.extend(
+            _rule_layer_language_coherence(
+                pattern, runtime_census(layer_files), repo_runtimes
+            )
+        )
+    except Exception:
+        pass
+    return findings
+
+
+def incoherent_layers(
+    pattern: str, layer_files: dict[str, list[str]], repo_files: "list[str]"
+) -> frozenset[str]:
+    """Layer names the coherence rule rejects for `pattern` (convenience view)."""
+    out: set[str] = set()
+    for f in reconcile_architecture_evidence(
+        pattern=pattern, layer_files=layer_files, repo_files=repo_files
+    ):
+        out.update(f.symbols)
+    return frozenset(out)
+
+
+def reconcile_extraction_evidence(
+    *,
+    type_decl_files: frozenset[str],
+    extracted_files: frozenset[str],
+) -> list[ReconciliationFinding]:
+    """Run extraction-time reconciliation rules. Never raises.
+
+    Args:
+        type_decl_files: files whose masked source declares a Java type.
+        extracted_files: files symbol extraction produced ≥1 symbol for.
+    """
+    findings: list[ReconciliationFinding] = []
+    try:
+        findings.extend(_rule_parse_coverage(type_decl_files, extracted_files))
+    except Exception:
+        pass
+    return findings