sourcecode 2.6.2__py3-none-any.whl → 2.6.3__py3-none-any.whl

sourcecode/verify_rules.py

@@ -0,0 +1,304 @@
+"""verify-edit Fase V5 — custom domain rules (the wide, defensive moat).
+
+The generic axes (contract / @Transactional / security / bean-wiring) encode Spring
+runtime semantics that a competitor could, with effort, replicate. This module lets a
+*client* declare invariants of THEIR codebase and have ``verify-edit`` enforce them —
+"no RestController touches a JPA DAO directly", "every /payroll endpoint requires role
+X". Those rules live in the client's repo and no external tool knows them; that is what
+makes the moat inreplicable.
+
+Discipline (roadmap §7):
+
+  * **VAI (Vendor-Agnostic Inference).** Our evaluator NEVER branches on a proprietary
+    name. A selector reasons purely by *structure* — has-annotation, fqn-matches-regex,
+    symbol-kind, modifier, source-file-matches. The concrete names ("RestController",
+    "DaoJpa", "/payroll") arrive as config **data**; they are the client's evidence,
+    never a hardcoded ``if fqn == "com.acme.Foo"`` in this code.
+  * **Determinism.** ``evaluate`` is a pure function of the CIR. Violation ids are stable
+    so the verdict layer can diff HEAD vs working and report only what the edit *added*.
+  * **Zero-config over the existing graph.** No rules file ⇒ no rules ⇒ nothing blocks.
+    Rules run against the CIR that is already built; no new extraction.
+
+Rule file (repo-root ``.ask/verify-rules.json``, fallback ``.sourcecode/verify-rules.json``):
+
+    {
+      "rules": [
+        {
+          "id": "no-controller-to-dao",
+          "description": "REST controllers must not touch a JPA DAO directly",
+          "kind": "forbidden_edge",
+          "edge_type": "injects",
+          "from": {"annotation": "@RestController"},
+          "to":   {"fqn": ".*DaoJpa$"}
+        },
+        {
+          "id": "payroll-needs-role",
+          "description": "every /payroll endpoint requires the PAYROLL role",
+          "kind": "require_endpoint_security",
+          "path": "^/payroll",
+          "require": {"role": "PAYROLL"}
+        }
+      ]
+    }
+"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+RULES_SCHEMA = "verify-rules-v1"
+_RULE_FILES = (".ask/verify-rules.json", ".sourcecode/verify-rules.json")
+_EDGE_KIND = "forbidden_edge"
+_ENDPOINT_KIND = "require_endpoint_security"
+_KINDS = (_EDGE_KIND, _ENDPOINT_KIND)
+
+
+class RulesError(ValueError):
+    """The rules file exists but is malformed — verify-edit reports *unverified*, never
+    a silent pass (a broken ruleset must not read as "no violations")."""
+
+
+# ── selector: a pure structural predicate over one graph node ────────────────────
+@dataclass(frozen=True)
+class Selector:
+    """Matches a graph node by structure only. Every present clause must hold (AND).
+    An empty selector matches every node. Names are data, never branched on by kind."""
+
+    annotation: Optional[str] = None       # node.annotations contains this (exact, e.g. "@RestController")
+    fqn: Optional[str] = None              # regex, fully matched against node fqn
+    symbol_kind: Optional[str] = None      # exact node symbol_kind (class|interface|method|field)
+    modifier: Optional[str] = None         # node.modifiers contains this (e.g. "public")
+    source_file: Optional[str] = None      # regex, searched against node source_file
+    _fqn_re: Any = None
+    _sf_re: Any = None
+
+    @classmethod
+    def from_dict(cls, d: Any, *, where: str) -> "Selector":
+        if d is None:
+            return cls()
+        if not isinstance(d, dict):
+            raise RulesError(f"{where}: selector must be an object, got {type(d).__name__}")
+        known = {"annotation", "fqn", "symbol_kind", "modifier", "source_file"}
+        unknown = set(d) - known
+        if unknown:
+            raise RulesError(f"{where}: unknown selector field(s) {sorted(unknown)}")
+        try:
+            fqn_re = re.compile(d["fqn"]) if d.get("fqn") else None
+            sf_re = re.compile(d["source_file"]) if d.get("source_file") else None
+        except re.error as exc:
+            raise RulesError(f"{where}: invalid regex ({exc})") from exc
+        return cls(
+            annotation=d.get("annotation"),
+            fqn=d.get("fqn"),
+            symbol_kind=d.get("symbol_kind"),
+            modifier=d.get("modifier"),
+            source_file=d.get("source_file"),
+            _fqn_re=fqn_re,
+            _sf_re=sf_re,
+        )
+
+    def is_empty(self) -> bool:
+        return not any((self.annotation, self.fqn, self.symbol_kind, self.modifier, self.source_file))
+
+    def matches(self, node: dict) -> bool:
+        if self.annotation is not None and self.annotation not in (node.get("annotations") or []):
+            return False
+        if self._fqn_re is not None and not self._fqn_re.fullmatch(node.get("fqn") or ""):
+            return False
+        if self.symbol_kind is not None and (node.get("symbol_kind") or "") != self.symbol_kind:
+            return False
+        if self.modifier is not None and self.modifier not in (node.get("modifiers") or []):
+            return False
+        if self._sf_re is not None and not self._sf_re.search(node.get("source_file") or ""):
+            return False
+        return True
+
+
+@dataclass(frozen=True)
+class Violation:
+    rule_id: str
+    subject: str          # the offending symbol / endpoint id
+    detail: str
+
+    @property
+    def id(self) -> str:
+        """Stable across runs, so the verdict layer can diff HEAD vs working."""
+        return f"{self.rule_id}::{self.subject}"
+
+    def to_dict(self) -> dict:
+        return {"rule_id": self.rule_id, "subject": self.subject, "detail": self.detail}
+
+
+# ── rules ────────────────────────────────────────────────────────────────────────
+@dataclass(frozen=True)
+class ForbiddenEdgeRule:
+    """No edge of ``edge_type`` may go from a node matching ``from_sel`` to a node
+    matching ``to_sel``. Reasons over the CIR edge list — structure, not names."""
+
+    id: str
+    description: str
+    edge_type: str
+    from_sel: Selector
+    to_sel: Selector
+
+    def evaluate(self, cir: Any) -> list[Violation]:
+        nodes = {n.get("fqn"): n for n in _nodes(cir) if n.get("fqn")}
+        owner = _owner_type_map(cir)  # member fqn → declaring type fqn
+        out: list[Violation] = []
+        for e in cir.call_graph:
+            if e.get("type") != self.edge_type:
+                continue
+            src, dst = e.get("from"), e.get("to")
+            fn, tn = nodes.get(src), nodes.get(dst)
+            if fn is None or tn is None:
+                continue  # an endpoint of the edge is outside the graph — cannot judge
+            if self._endpoint_matches(self.from_sel, fn, nodes, owner) and \
+               self._endpoint_matches(self.to_sel, tn, nodes, owner):
+                out.append(Violation(
+                    self.id, f"{src} -{self.edge_type}-> {dst}",
+                    f"forbidden {self.edge_type} edge {src} → {dst}",
+                ))
+        return out
+
+    @staticmethod
+    def _endpoint_matches(sel: Selector, node: dict, nodes: dict, owner: dict) -> bool:
+        """Selector matches an edge endpoint iff it matches that node OR the type that
+        declares it. Edges are recorded at member granularity (a field's ``injects``, a
+        method's ``calls``) but client invariants are usually stated at type granularity
+        ("no RestController touches a DAO"), so the annotation/kind on the owning class
+        must count. Purely structural — the owner is resolved via ``contained_in``."""
+        if sel.matches(node):
+            return True
+        owner_fqn = owner.get(node.get("fqn"))
+        owner_node = nodes.get(owner_fqn) if owner_fqn else None
+        return owner_node is not None and sel.matches(owner_node)
+
+
+@dataclass(frozen=True)
+class RequireEndpointSecurityRule:
+    """Every endpoint whose path matches ``path_re`` must carry the required policy
+    and/or role. A missing/weaker policy on a matched endpoint is a violation."""
+
+    id: str
+    description: str
+    path_re: Any
+    require_policy: Optional[str]
+    require_role: Optional[str]
+
+    def evaluate(self, cir: Any) -> list[Violation]:
+        out: list[Violation] = []
+        for ep in cir.endpoints:
+            if not self.path_re.search(ep.path or ""):
+                continue
+            sec = ep.security
+            missing: list[str] = []
+            if self.require_policy is not None and (sec is None or sec.policy != self.require_policy):
+                got = repr(sec.policy) if sec else "None"
+                missing.append(f"policy={self.require_policy!r} (got {got})")
+            if self.require_role is not None and (sec is None or self.require_role not in (sec.effective_roles or [])):
+                missing.append(f"role={self.require_role!r}")
+            if missing:
+                out.append(Violation(
+                    self.id, ep.id,
+                    f"endpoint {ep.method} {ep.path} missing required {', '.join(missing)}",
+                ))
+        return out
+
+
+Rule = Any  # ForbiddenEdgeRule | RequireEndpointSecurityRule
+
+
+def _nodes(cir: Any) -> list[dict]:
+    return cir._raw_ir.get("graph", {}).get("nodes", []) or []
+
+
+def _owner_type_map(cir: Any) -> dict[str, str]:
+    """member fqn → declaring type fqn, from ``contained_in`` edges (field/method → class).
+    Lets a type-level selector match an edge endpoint recorded at member granularity."""
+    return {e["from"]: e["to"] for e in cir.call_graph
+            if e.get("type") == "contained_in" and e.get("from") and e.get("to")}
+
+
+# ── loading / parsing ────────────────────────────────────────────────────────────
+def _rule_from_dict(d: Any, idx: int) -> Rule:
+    where = f"rule[{idx}]"
+    if not isinstance(d, dict):
+        raise RulesError(f"{where}: must be an object")
+    rid = d.get("id")
+    if not rid or not isinstance(rid, str):
+        raise RulesError(f"{where}: missing string 'id'")
+    kind = d.get("kind")
+    if kind not in _KINDS:
+        raise RulesError(f"{where} ({rid}): 'kind' must be one of {list(_KINDS)}, got {kind!r}")
+    desc = d.get("description") or ""
+
+    if kind == _EDGE_KIND:
+        edge_type = d.get("edge_type")
+        if not edge_type or not isinstance(edge_type, str):
+            raise RulesError(f"{where} ({rid}): forbidden_edge needs a string 'edge_type'")
+        from_sel = Selector.from_dict(d.get("from"), where=f"{where} ({rid}).from")
+        to_sel = Selector.from_dict(d.get("to"), where=f"{where} ({rid}).to")
+        if from_sel.is_empty() and to_sel.is_empty():
+            raise RulesError(f"{where} ({rid}): 'from' and 'to' cannot both be empty (would ban all edges)")
+        return ForbiddenEdgeRule(rid, desc, edge_type, from_sel, to_sel)
+
+    # require_endpoint_security
+    path = d.get("path")
+    if not path or not isinstance(path, str):
+        raise RulesError(f"{where} ({rid}): require_endpoint_security needs a string 'path' regex")
+    try:
+        path_re = re.compile(path)
+    except re.error as exc:
+        raise RulesError(f"{where} ({rid}): invalid 'path' regex ({exc})") from exc
+    req = d.get("require")
+    if not isinstance(req, dict) or not (req.get("policy") or req.get("role")):
+        raise RulesError(f"{where} ({rid}): 'require' must set at least one of 'policy' / 'role'")
+    return RequireEndpointSecurityRule(rid, desc, path_re, req.get("policy"), req.get("role"))
+
+
+def parse_rules(raw: Any) -> list[Rule]:
+    """Parse an already-decoded rules document into rule objects. Raises RulesError
+    on any malformation (duplicate ids included) so the axis degrades to *unverified*."""
+    if not isinstance(raw, dict) or "rules" not in raw:
+        raise RulesError("rules file must be an object with a 'rules' array")
+    rules_raw = raw["rules"]
+    if not isinstance(rules_raw, list):
+        raise RulesError("'rules' must be an array")
+    rules = [_rule_from_dict(d, i) for i, d in enumerate(rules_raw)]
+    seen: set[str] = set()
+    for r in rules:
+        if r.id in seen:
+            raise RulesError(f"duplicate rule id {r.id!r}")
+        seen.add(r.id)
+    return rules
+
+
+def rules_path(root: Path) -> Optional[Path]:
+    for rel in _RULE_FILES:
+        p = root / rel
+        if p.is_file():
+            return p
+    return None
+
+
+def load_rules(root: Path) -> list[Rule]:
+    """Load the repo's custom rules. Absent file ⇒ ``[]`` (zero-config, nothing blocks).
+    Present-but-broken ⇒ RulesError (caller degrades to unverified — never a silent pass)."""
+    p = rules_path(Path(root))
+    if p is None:
+        return []
+    try:
+        raw = json.loads(p.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise RulesError(f"could not read {p}: {exc}") from exc
+    return parse_rules(raw)
+
+
+def evaluate_all(rules: list[Rule], cir: Any) -> list[Violation]:
+    out: list[Violation] = []
+    for r in rules:
+        out.extend(r.evaluate(cir))
+    return out

{sourcecode-2.6.2.dist-info → sourcecode-2.6.3.dist-info}/METADATA

@@ -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.dist-info → sourcecode-2.6.3.dist-info}/RECORD

@@ -1,4 +1,4 @@
-sourcecode/__init__.py,sha256=Xl4vKr6-4l-yWpoN7FzgqDyXd54m2LAMPUtDWX2CdD0,308
+sourcecode/__init__.py,sha256=inJYWLATw0hWFueMieZTLMVFkMV-j2YjHCR5sz3Dlh0,308
 sourcecode/adaptive_scanner.py,sha256=yJBKjNpkY6bpueYJ2YnRezen3sYZDecEt7WaaNWdqug,9466
 sourcecode/archetype.py,sha256=UrmiONHfqLl7UfGzjECoQBO28hcM_1rvzn0hCt0EtjU,35033
 sourcecode/architectural_baseline.py,sha256=7QzJri4pbL3nzAn9gNutZW6mZR8HHD6H2C2H1EEwYPE,17904
@@ -13,7 +13,7 @@ sourcecode/canonical_ir.py,sha256=LdP_Ri3rl0M5p-MY0ypVvQwhq1WuUF1FmaHid7zyzEg,29
 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=kivJiIF7Rw-Eal-3_m2CG5E9i66UUuOLLyquLgUM0N0,359485
+sourcecode/cli.py,sha256=vlr2fQDesPFaSGa6qLhG6GP7xWU6F-u0U_qjc03r14M,362994
 sourcecode/code_notes_analyzer.py,sha256=EJemNCNc9Dn-1RZYu-aNbK0ELzmsyC4s6FdHi3XyNEI,9392
 sourcecode/compare.py,sha256=jdePg0dNCxFpysiTGMsROL5XABLjy_zVUgVeySvdb0o,7514
 sourcecode/confidence_analyzer.py,sha256=vnbPI-20FnHdjO6STxHW8fbaxmB4A7y58io63ibFZjc,21586
@@ -52,6 +52,7 @@ sourcecode/metrics_analyzer.py,sha256=m0ENgtqKeBL17kUIK3fmGkgo7UfXBNHxCMj0H_Y5K7
 sourcecode/migrate_check.py,sha256=hsKNwipl-bSqRsYqG1O_CLbXpMlqtnN-Bif3hpHpnjg,108676
 sourcecode/openapi_surface.py,sha256=BTt0K-woZbkbWTN77IkqeBm_Okag9owR0848fmot8sk,16207
 sourcecode/output_budget.py,sha256=Js9yUlfQtPhqBl9R6wn_9UHVjjJc3GtLcqyfjf5t50Q,9869
+sourcecode/parse_cache.py,sha256=EB2Eb23S3Z2UlyUIPetXv-Tu-1niB6eWVThmraLCyyA,5505
 sourcecode/path_filters.py,sha256=qPKO7kRmVp2y9zjLNSuAVCbcpZrIInHE4QulLUlzPFI,10412
 sourcecode/perf.py,sha256=GAcEoouPIlPMCQIcHNToxK6K3WdIR-lj9aFg4prOYJI,9743
 sourcecode/pr_comment_renderer.py,sha256=KmcjMruhR44gjzMDJwjBSkWP9QEvh8xWBLyxzxoRbj0,14542
@@ -64,7 +65,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=9ZGRWy8g4_PH_XvdCm6i1UOHYX-qO3sxxodXytf3m0Q,320870
+sourcecode/repository_ir.py,sha256=wD6ODf8nNijDIh01FWyPoY1jplpPLWvfKl_5rAvLVMQ,322680
 sourcecode/ris.py,sha256=Hw8TakTQ6hku-Abf2k8954NwkrH_sP73_8wVH8x5khc,22079
 sourcecode/runtime_classifier.py,sha256=uTAD6BDCiBLUZEDRfqk718kM4RTT_vAbfkcOI2_Xx58,18432
 sourcecode/scanner.py,sha256=z3CV0rcGunu0Y8mpNgp07wI7nxT0pxw1BkXRRtI0Rpo,9609
@@ -88,6 +89,8 @@ sourcecode/tree_utils.py,sha256=8GAkIfQAsvtEudIeW1l4ooH_oRtrWR8cpJQJsEa_Pfw,2093
 sourcecode/type_usage_surface.py,sha256=51IrKRQoIoRnlsiDjHnqpJBn2rc6E59aRhgS0HTzAF0,4428
 sourcecode/validation_inference.py,sha256=KN3tEBQzxNinwlo7buer6lx5Kqdn71JAs_wuu44McfU,17475
 sourcecode/validation_surface.py,sha256=A0-FVswL__XOcw92wvIwghwLq5AWtIm2kzO3RjEb1b4,27325
+sourcecode/verify_edit.py,sha256=LFk5CRste11GwNUTUrTGxoQpmQhy4Qoqd7NdhGq1weA,26190
+sourcecode/verify_rules.py,sha256=y7MXrjGDVed0uTY5P6hcP6AwvFGADDQ4uKanJfO9z5E,13273
 sourcecode/version_check.py,sha256=CHp6ZxTIfo8kyHPCBgJA1uFC0xQCoXMuuOfrW8QTL8o,4942
 sourcecode/workspace.py,sha256=X_6NmNnitvT3_38V-JDChydo_sR68s249hLFlrQskU0,8271
 sourcecode/detectors/__init__.py,sha256=A0AACJFF6HWf_RgatNtWu3PUzstcKtIGM9f1PoFcJug,1987
@@ -113,7 +116,7 @@ sourcecode/detectors/terraform.py,sha256=cxORPR_zVLOJpHlh4e9JnFpkQsn_UnqMMom5yG6
 sourcecode/detectors/tooling.py,sha256=8CKbtxwQoABP-WyBRNmdAmHDOvAH57AR1cF4UKuWEdQ,2074
 sourcecode/mcp/__init__.py,sha256=XU4HfRGbdid8wdUA0x_4f7uKZD1z3mv_XUY_WU_T9Mw,179
 sourcecode/mcp/orchestrator.py,sha256=diVoQgn24QmgPL3Ev8Sp6hsvh02OqY3MktHXOzrlodo,36525
-sourcecode/mcp/registry.py,sha256=DyREJve47GnajFYgPORmzQjH1Qi2ZzE5twvQpPXMghI,65821
+sourcecode/mcp/registry.py,sha256=OCUCRLPRM176FCw850rF7dNh74f5Zj0h3a9lpxrf8mI,68171
 sourcecode/mcp/runner.py,sha256=RGimCwhLyHxjCvH7q72y12HWEnATXZLC-NBWhkzlu0I,2852
 sourcecode/mcp/server.py,sha256=yCp1YmmZ4hQE7KIHC8XcdxnToYCwSe9vxp4E-YMzVg0,63713
 sourcecode/mcp/onboarding/__init__.py,sha256=sj2PWqEBmMc4zBNkomg89WtL0M6S7A9yb7_wAuSWNP4,66
@@ -145,8 +148,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.6.2.dist-info/METADATA,sha256=7dMltG6Rgrg_RmRX5tEh13LJZIYv1ouwALVAcjHHY2I,10851
-sourcecode-2.6.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-2.6.2.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
-sourcecode-2.6.2.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-2.6.2.dist-info/RECORD,,
+sourcecode-2.6.3.dist-info/METADATA,sha256=83aYwUnc4szlY7QK1pyjw5suiM3HMkRKeRznWyPzd20,10851
+sourcecode-2.6.3.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-2.6.3.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
+sourcecode-2.6.3.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-2.6.3.dist-info/RECORD,,