cg-code-graph 0.10.1__py3-none-any.whl

codegraph/parity_structure.py

@@ -0,0 +1,307 @@
+"""`cg parity --structure` (#93): pairs symbols whose names do not match by what they use, and learns per-project
+rename rules from the pairs found. See docs/parity.md, "Matching by structure".
+
+Each still-missing source symbol and each unmatched target symbol gets a feature set from its declaration span and
+its outgoing edges:
+
+  l10n:<key>   localization keys (`Localizations.creatingAccount`, `L10n.actionCancel`, `R.string.creating_account`,
+               `BitwardenString.x`, `CommonStrings.x`), case and `_` folded so the two platforms' keys meet
+  str:<text>   string literals of 5 to 80 characters (URL paths, analytics events, keys), leading `/` dropped
+  http:<path>  HTTP endpoints the code calls (HTTP_CALLS), path parameters folded to `{}`
+  sym:<target> symbols it calls / instantiates / navigates to that are already paired (the source side is
+               rewritten to the target's name, so a call to a paired API on both sides is a shared feature)
+  call:<name>  the names of the members it calls (two words or more)
+  w:<stem>     the stemmed content words of its own name
+
+A pair is accepted when it shares a use (any feature but w:) and either two uses or two name words, its IDF-weighted
+cosine is at least MIN_SCORE, both symbols are each other's best candidate, the runner-up scores below MARGIN times
+the best, and category, UI-ness and architecture role agree (`compatible`). Learned rules come from the
+non-exact type pairs: a word tail (`Coordinator` -> `Navigation`) or head (`BW` -> `Bitwarden`) rewrite seen at least
+MIN_SUPPORT times, two thirds of the time for that source tail, is applied to the remaining missing types and
+top-level symbols. Every match carries its evidence; name matches are left as they are."""
+from __future__ import annotations
+
+import math
+import re
+import sqlite3
+from collections import Counter, defaultdict
+from pathlib import Path
+
+MIN_SCORE = 0.3
+MIN_SHARED = 2
+MARGIN = 0.8                 # the runner-up must score below MARGIN * best
+MIN_SUPPORT = 2
+MAX_DF = 40
+PREVIEW = re.compile(r"Preview")           # Compose @Preview functions / PreviewParameterProviders, SwiftUI previews                  # features shared by more symbols than this do not propose candidates
+L10N = re.compile(r"\b(?:Localizations|L10n|R\.string|BitwardenString|CommonStrings|[A-Z]\w*Strings)\.([A-Za-z_]\w*)")
+STR = re.compile(r'"((?:[^"\\\n]|\\.){5,80})"')
+EDGE_KINDS = ("CALLS", "INSTANTIATES", "NAVIGATES_TO", "HTTP_CALLS", "USES_VALUE", "REFERENCES_FN", "USES_TYPE")
+
+
+UI_WORDS = {"view", "screen", "sheet", "page", "fragment", "activity", "controller", "vc", "content", "dialog", "card",
+            "row", "cell", "button", "item", "items", "field", "list", "menu", "toolbar", "banner"}
+# role words of an architecture: a type ending in one only pairs with a type ending in the same group
+ROLES = [{"processor", "viewmodel", "vm"}, {"coordinator", "navigation", "navigator", "route", "destination", "router"},
+         {"state"}, {"action"}, {"effect", "event"}, {"request", "api", "service", "client", "response", "json"},
+         {"repository", "manager", "service", "store", "source"}, {"model", "json", "data", "type", "option"}]
+ROLE_OF = defaultdict(set)
+for _i, _g in enumerate(ROLES):
+    for _w in _g:
+        ROLE_OF[_w].add(_i)
+
+
+def _role(fq: str) -> set:
+    ws = _words(_short(fq))
+    if len(ws) >= 2 and ws[-2:] == ["view", "model"]:
+        return ROLE_OF["viewmodel"]
+    return ROLE_OF.get(ws[-1], set()) if ws else set()
+
+
+def is_ui(fq: str, sym: dict, members: dict) -> bool:
+    ws = _words(_short(fq))
+    return bool(sym.get("composable") or "body" in members.get(fq, {}) or (ws and ws[-1] in UI_WORDS and ws[-2:] != ["view", "model"]))
+
+
+def compatible(fq, sc, tq, tc, s_ui, t_ui) -> bool:
+    """Same category (a SwiftUI view type also meets a @Composable function), the same UI-ness for types and
+    top-level symbols, and no clash of architecture roles (`Coordinator` vs `State`)."""
+    if sc != tc and not ({sc, tc} == {"type", "func"} and s_ui and t_ui):
+        return False
+    if "type" in (sc, tc) and s_ui != t_ui:
+        return False
+    if sc == tc == "type":
+        a, b = _role(fq), _role(tq)
+        if a and b and not (a & b):
+            return False
+    return True
+
+
+STOP = {"handle", "click", "clicked", "tap", "tapped", "pressed", "get", "set", "is", "on", "did", "will", "the", "to",
+        "for", "with", "and", "of", "default", "impl", "internal", "receive", "result", "update", "show", "new", "bitwarden"}
+STOP |= UI_WORDS | {w for g in ROLES for w in g} | {"view", "model"}
+
+
+def _stem(w: str) -> str:
+    for suf in ("ments", "ment", "ings", "ing", "ions", "ion", "ers", "er", "ed", "es", "s", "e"):
+        if w.endswith(suf) and len(w) - len(suf) >= 4:
+            w = w[: -len(suf)]
+            break
+    return w[:-1] if w.endswith("e") and len(w) > 4 else w
+
+
+def name_words(fq: str) -> set:
+    """The stemmed content words of a name (role, UI and event words left out): `DeviceManagementProcessor` and
+    `ManageDevicesViewModel` share `devic` and `manag`."""
+    return {"w:" + _stem(w) for w in _words(_short(fq)) if w not in STOP and len(w) > 2}
+
+
+def _fold(s: str) -> str:
+    return re.sub(r"[_\W]", "", s).lower()
+
+
+def _words(name: str) -> list[str]:
+    return [w.lower() for w in re.findall(r"[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z0-9]+|[A-Z]+", name or "")]
+
+
+class Side:
+    """One graph: its symbols' spans, outgoing edges and source lines."""
+
+    def __init__(self, G: dict):
+        self.G = G
+        c = sqlite3.connect(G["db"])
+        c.row_factory = sqlite3.Row
+        self.root = G["root"]
+        self.lines = G["lines_of"]
+        self.fqn_of, self.span = {}, {}
+        self.by_file = defaultdict(list)
+        for r in c.execute("SELECT id, fqn, name, file, line, end_line FROM nodes WHERE file IS NOT NULL AND line IS NOT NULL"):
+            self.fqn_of[r["id"]] = (r["fqn"] or r["name"] or "").replace(".Companion.", ".")
+            self.by_file[r["file"]].append((r["line"], r["end_line"] or r["line"], r["id"]))
+            self.span[r["id"]] = (r["file"], r["line"], r["end_line"] or r["line"])
+        self.out = defaultdict(list)
+        q = f"SELECT src, dst, kind FROM edges WHERE kind IN ({','.join('?' * len(EDGE_KINDS))})"
+        for r in c.execute(q, EDGE_KINDS):
+            self.out[r["src"]].append((r["dst"], r["kind"]))
+        self.http = {r["id"]: (r["name"] or r["id"]) for r in c.execute("SELECT id, name FROM nodes WHERE kind='http'")}
+        c.close()
+
+    def text(self, file: str, a: int, b: int) -> str:
+        if file not in self.lines:
+            try:
+                self.lines[file] = (Path(self.root) / file).read_text(encoding="utf-8", errors="replace").splitlines()
+            except OSError:
+                self.lines[file] = []
+        return "\n".join(self.lines[file][a - 1:b])
+
+    def features(self, sym: dict, rename) -> set:
+        file, a, b = self.span.get(sym["id"], (sym["file"], sym["line"], sym["line"]))
+        f = set()
+        if file and a:
+            src = self.text(file, a, b)
+            f |= {"l10n:" + _fold(m) for m in L10N.findall(src)}
+            for m in STR.findall(src):
+                s = m.strip().lstrip("/")
+                if len(s) >= 5 and re.search(r"[A-Za-z]{3}", s) and not re.search(r"\\\(|\$\{|%[@sd]", s):
+                    f.add("str:" + re.sub(r"\s+", " ", s.lower()))
+            for la, lb, nid in self.by_file.get(file, ()):
+                if a <= la <= b:
+                    for dst, kind in self.out.get(nid, ()):
+                        if kind == "HTTP_CALLS" or dst in self.http:
+                            p = re.sub(r"\{[^}]*\}|(?<=/):\w+", "{}", self.http.get(dst, dst).split(" ")[-1])
+                            f.add("http:" + p.lstrip("/").lower())
+                            continue
+                        dq = self.fqn_of.get(dst)
+                        t = rename(dq)
+                        if t:
+                            f.add("sym:" + t)
+                        # the called member's own name (two words or more): `getDevices` on an AuthService and on
+                        # an AuthRepository is the same call even when the owners are not paired
+                        nm = _short(dq or "").split("(")[0]
+                        if kind == "CALLS" and len(_words(nm)) >= 2:
+                            f.add("call:" + re.sub(r"^(get|fetch|load)(?=[a-z])", "", _fold(nm)))
+        return f
+
+
+def match(S: dict, T: dict, out: dict, sym_of: dict, cat_of: dict, t_syms: dict, t_cat: dict, learn: bool = True) -> dict:
+    ui_s = {fq: is_ui(fq, sym, S["members"]) for fq, sym in sym_of.items()}
+    ui_t = {fq: is_ui(fq, sym, T["members"]) for fq, sym in t_syms.items()}
+    S["_ui"], T["_ui"] = ui_s, ui_t
+    """Adds `learned` and `structure` matches to `out` (rows moved out of `missing`). `sym_of` / `cat_of`: source fqn
+    -> symbol / category for every compared source symbol; `t_syms` / `t_cat` the same for the target."""
+    used = {r["target"] for r in out["matched"]}
+    rules: list = []
+    if learn:
+        rules = _learn(out["matched"], cat_of)
+        _apply_rules(rules, out, sym_of, cat_of, t_syms, t_cat, used)
+    _structure(S, T, out, sym_of, cat_of, t_syms, t_cat, used)
+    if learn:
+        more = [r for r in _learn(out["matched"], cat_of) if r["from"] not in {x["from"] for x in rules}]
+        if more:
+            _apply_rules(more, out, sym_of, cat_of, t_syms, t_cat, used)
+            rules += more
+    return {"rules": rules}
+
+
+def _short(fq: str) -> str:
+    return fq.rsplit(".", 1)[-1]
+
+
+def _learn(matched: list, cat_of: dict) -> list:
+    """Word tail / head rewrites from the non-exact type and top-level pairs."""
+    seen, total = Counter(), Counter()
+    for r in matched:
+        if r.get("confidence") in ("exact", "moved", None) or cat_of.get(r["symbol"]) not in ("type", "func", "const"):
+            continue
+        if r["symbol"].count(".") != r["target"].count(".") and "." in r["symbol"]:
+            continue
+        sw, tw = _words(_short(r["symbol"])), _words(_short(r["target"]))
+        p = 0
+        while p < min(len(sw), len(tw)) and sw[p] == tw[p]:
+            p += 1
+        q = 0
+        while q < min(len(sw), len(tw)) - p and sw[-1 - q] == tw[-1 - q]:
+            q += 1
+        if p and not q and 0 < len(sw) - p <= 2 and 0 < len(tw) - p <= 2:
+            k = ("tail", " ".join(sw[p:]), " ".join(tw[p:]))
+        elif q and not p and 0 < len(sw) - q <= 2 and 0 < len(tw) - q <= 2:
+            k = ("head", " ".join(sw[:len(sw) - q]), " ".join(tw[:len(tw) - q]))
+        else:
+            continue
+        seen[k] += 1
+        total[(k[0], k[1])] += 1
+    out = []
+    for (where, a, b), n in seen.most_common():
+        if n >= MIN_SUPPORT and n * 3 >= total[(where, a)] * 2 and not any(x["at"] == where and x["from"] == a for x in out):
+            out.append({"at": where, "from": a, "to": b, "support": n})
+    return out
+
+
+def _apply_rules(rules, out, sym_of, cat_of, t_syms, t_cat, used):
+    if not rules:
+        return
+    t_ix = defaultdict(list)
+    for fq in t_syms:
+        if fq not in used:
+            t_ix[(t_cat[fq], " ".join(_words(_short(fq))))].append(fq)
+    keep = []
+    for row in out["missing"]:
+        fq = row["symbol"]
+        sw = " ".join(_words(_short(fq)))
+        hit = None
+        if "owner_matched" not in row:
+            for r in rules:
+                if r["at"] == "tail" and sw.endswith(" " + r["from"]):
+                    want = sw[: -len(r["from"])] + r["to"]
+                elif r["at"] == "head" and sw.startswith(r["from"] + " "):
+                    want = r["to"] + sw[len(r["from"]):]
+                else:
+                    continue
+                c = [t for t in t_ix.get((cat_of.get(fq), want), ()) if t not in used]
+                if len(c) == 1:
+                    hit = (c[0], r)
+                    break
+        if hit:
+            used.add(hit[0])
+            r = hit[1]
+            out["matched"].append(dict(row, target=hit[0], confidence="learned",
+                                       evidence=[f"rule {r['at']} {r['from']!r} -> {r['to']!r} (seen {r['support']}x)"]))
+        else:
+            keep.append(row)
+    out["missing"] = keep
+
+
+def _structure(S, T, out, sym_of, cat_of, t_syms, t_cat, used):
+    sS, sT = Side(S), Side(T)
+    pairs = {r["symbol"]: r["target"] for r in out["matched"]}
+    src_f, rows = {}, {r["symbol"]: r for r in out["missing"]}
+    for row in out["missing"]:
+        sym = sym_of.get(row["symbol"])
+        if sym is not None:
+            src_f[row["symbol"]] = sS.features(sym, lambda x: pairs.get(x)) | name_words(row["symbol"])
+    tgt_f = {fq: sT.features(sym, lambda x: x) | name_words(fq) for fq, sym in t_syms.items()
+             if fq not in used and not PREVIEW.search(_short(fq))}
+    src_f = {fq: f for fq, f in src_f.items() if not PREVIEW.search(_short(fq))}
+    df = Counter()
+    for fs in list(src_f.values()) + list(tgt_f.values()):
+        df.update(fs)
+    n = max(1, len(src_f) + len(tgt_f))
+    w = {f: math.log(1 + n / c) for f, c in df.items()}
+    inv = defaultdict(list)
+    for fq, fs in tgt_f.items():
+        for f in fs:
+            if df[f] <= MAX_DF:
+                inv[f].append(fq)
+
+    def score(a, b):
+        sh = a & b
+        nw = sum(1 for f in sh if not f.startswith("w:"))
+        # what they use must carry the match: two shared uses, or one use and two shared name words
+        if nw < 1 or (nw < MIN_SHARED and len(sh) - nw < 2):
+            return 0.0, sh
+        return sum(w[f] for f in sh) / math.sqrt(sum(w[f] for f in a) * sum(w[f] for f in b)), sh
+
+    best_s = {}
+    for fq, fs in src_f.items():
+        member = "owner_matched" in rows[fq]
+        cands = {t for f in fs if df[f] <= MAX_DF for t in inv.get(f, ())
+                 if (t_cat.get(t) == cat_of.get(fq) if member else
+                     compatible(fq, cat_of.get(fq), t, t_cat.get(t), S["_ui"].get(fq), T["_ui"].get(t)))}
+        scored = sorted(((score(fs, tgt_f[t]), t) for t in cands), key=lambda x: -x[0][0])
+        if scored and scored[0][0][0] >= MIN_SCORE and (len(scored) == 1 or scored[1][0][0] < MARGIN * scored[0][0][0]):
+            best_s[fq] = (scored[0][1], scored[0][0][0], scored[0][0][1])
+    # mutual best: no other source symbol scores higher for the same target
+    by_t = defaultdict(list)
+    for fq, (t, sc, sh) in best_s.items():
+        by_t[t].append((sc, fq))
+    keep = []
+    for row in out["missing"]:
+        fq = row["symbol"]
+        got = best_s.get(fq)
+        if got and max(by_t[got[0]])[1] == fq and got[0] not in used:
+            t, sc, sh = got
+            used.add(t)
+            ev = sorted(sh, key=lambda f: -w[f])[:6]
+            out["matched"].append(dict(row, target=t, confidence="structure", score=round(sc, 2), evidence=ev))
+        else:
+            keep.append(row)
+    out["missing"] = keep

codegraph/payload.py

@@ -0,0 +1,321 @@
+"""Payload / field contract check between a client endpoint and the backend route it matched.
+
+Inputs (all from the graphs, no execution):
+  client  HTTP_CALLS edge attrs: body_keys [{key,type,line,file,model?}], response_models [{model,path,line}],
+          response_keys [{key,path,line,cast,coalesce}], status_checks [{op,v,line}], trailing_slash;
+          model class attrs json_from / json_to (key, field, type, cast, nullable, required, ref, many), enum_values.
+  server  route attrs: request {schemas:[{class,location}], keys:[...]}, response {schemas:[{class,status}],
+          shapes:[{status, keys: shape}]} (django/shapes.py), trailing_slash, framework, auth;
+          schema class attrs schema_fields (name/json, type, nullable, required, ref, many, choices).
+
+Issue kinds: trailing_slash, request_missing_required, request_unknown_field, request_case_mismatch,
+request_type, request_nullability, request_body_missing, response_missing_key, response_case_mismatch,
+response_type, response_nullability, response_enum_values, status_code. Severity: high (likely runtime
+failure), medium, low, info. Every issue carries file:line on both sides when known.
+"""
+from __future__ import annotations
+
+import re
+
+DART_KIND = {"String": "str", "int": "int", "double": "float", "num": "number", "bool": "bool", "List": "list", "Iterable": "list",
+             "Set": "list", "Map": "dict", "DateTime": "datetime", "dynamic": "any", "Object": "any", "Uri": "str", "Duration": "any"}
+SERVER_KIND = {"str": "str", "int": "int", "float": "float", "number": "number", "decimal": "decimal", "bool": "bool", "uuid": "str",
+               "datetime": "str", "date": "str", "time": "str", "duration": "any", "list": "list", "dict": "dict", "json": "any",
+               "file": "str", "model": "any", "any": "any", "null": "null", "email": "str", "url": "str", "fk": "int",
+               "m2m": "list", "bytes": "str", "enum": "str"}
+
+
+def norm_key(k: str) -> str:
+    return re.sub(r"[_\-]", "", k).lower()
+
+
+def dart_kind(t: str | None, enums: set[str] | None = None) -> tuple[str | None, bool]:
+    if not t:
+        return None, False
+    nullable = t.strip().endswith("?") or t.strip() in ("dynamic", "Object?")
+    base = re.sub(r"<.*", "", t.strip().rstrip("?")).split(".")[-1]
+    if enums and base in enums:
+        return "enum", nullable
+    return DART_KIND.get(base, "object" if base[:1].isupper() else None), nullable
+
+
+def compatible(client: str | None, server: str | None, cast: str | None = None) -> bool:
+    if not client or not server or client in ("any",) or server in ("any", "null"):
+        return True
+    if client == server:
+        return True
+    if client == "number" and server in ("int", "float", "decimal", "number"):
+        return True
+    if client == "float" and server in ("int", "number", "decimal"):
+        return not (cast and cast.rstrip("?") == "double")  # `as double` on a JSON int throws on the Dart VM
+    if client == "int" and server == "number":
+        return True
+    if client in ("str", "datetime", "enum") and server in ("str", "decimal", "enum"):
+        return True
+    if client == "object" and server in ("dict",):
+        return True
+    if client == "list" and server == "list":
+        return True
+    return False
+
+
+class Checker:
+    def __init__(self, fe_nodes: dict, be_nodes: dict, fe_name: str, be_name: str):
+        self.fe, self.be = fe_nodes, be_nodes  # id -> attrs
+        self.fe_name, self.be_name = fe_name, be_name
+        self.enums = {nid.split("#")[-1] for nid, a in fe_nodes.items() if a.get("enum_values")}
+
+    def at(self, side: str, file, line) -> str | None:
+        if not file:
+            return None
+        return f"{self.fe_name if side == 'fe' else self.be_name}/{file}:{line}"
+
+    # ---------------------------------------------------------------- server shapes
+    def schema_shape(self, qual: str, depth=0) -> dict:
+        a = self.be.get(f"class:{qual}") or {}
+        out = {}
+        for fd in a.get("schema_fields") or []:
+            ch = self.schema_shape(fd["ref"], depth + 1) if fd.get("ref") and depth < 5 else None
+            out[fd.get("json") or fd["name"]] = {"type": fd.get("type"), "nullable": fd.get("nullable"), "required": fd.get("required"),
+                                                 "many": fd.get("many"), "children": ch, "line": fd.get("line"), "file": fd.get("file"),
+                                                 "choices": fd.get("choices"), "read_only": fd.get("read_only"), "schema": qual,
+                                                 "default": fd.get("has_default") or fd.get("default")}
+        return out
+
+    def success_shapes(self, ra: dict, errors: bool = False) -> list[dict]:
+        resp = ra.get("response") or {}
+        out = []
+        for s in resp.get("shapes") or []:
+            st = s.get("status")
+            if errors or st is None or (isinstance(st, int) and 200 <= st < 300):
+                out.append({"keys": s["keys"], "file": s.get("file"), "line": s.get("line"), "status": st})
+        for sc in resp.get("schemas") or []:
+            st = sc.get("status")
+            if errors or st is None or (isinstance(st, int) and 200 <= st < 300):
+                sh = self.schema_shape(sc["class"])
+                if sc.get("many"):
+                    sh = {"[]": {"type": "list", "many": True, "children": sh}}
+                out.append({"keys": sh, "file": None, "line": None, "status": st, "schema": sc["class"]})
+        return out
+
+    @staticmethod
+    def at_path(shape: dict, path: str | None):
+        if not path:
+            return shape
+        cur = shape
+        for part in path.split("."):
+            many = part.endswith("[]")
+            part = part[:-2] if many else part
+            if part:
+                v = cur.get(part) if isinstance(cur, dict) else None
+                if not v:
+                    return None
+                cur = v.get("children")
+            elif "[]" in cur:
+                cur = cur["[]"].get("children")
+            if cur is None:
+                return None
+        return cur
+
+    # ---------------------------------------------------------------- checks
+    def check(self, ep: str, route_id: str, ra: dict, call: dict) -> list[dict]:
+        issues = []
+        base = {"endpoint": ep, "route": route_id, "client_at": call.get("at"), "server_at": self.at("be", ra.get("_file"), ra.get("_line"))}
+
+        def add(kind, sev, msg, **kw):
+            issues.append({**base, "kind": kind, "severity": sev, "message": msg, **kw})
+
+        # trailing slash
+        cts, rts = call.get("trailing_slash"), ra.get("trailing_slash")
+        if cts is not None and rts is not None and bool(cts) != bool(rts):
+            method = ra.get("method", "")
+            fw = ra.get("framework")
+            sev = "high" if fw == "ninja" or method not in ("GET", "HEAD") else "medium"
+            add("trailing_slash", sev, f"client URL {'has' if cts else 'lacks'} a trailing slash, route `{ra.get('uri')}` "
+                f"{'has' if rts else 'does not'}; "
+                + ("django-ninja does not redirect: 404" if fw == "ninja" else
+                   "APPEND_SLASH cannot redirect a " + method + " (RuntimeError in DEBUG, 404/405 otherwise)" if method not in ("GET", "HEAD")
+                   else "GET is redirected (301) by APPEND_SLASH"), url=call.get("url"))
+        issues += self.check_request(ra, call, add)
+        issues_resp = self.check_response(ra, call, add)
+        issues += issues_resp
+        # status codes
+        statuses = {s.get("status") for s in (ra.get("response") or {}).get("shapes") or []} | \
+                   {s.get("status") for s in (ra.get("response") or {}).get("schemas") or []}
+        ok = {s for s in statuses if isinstance(s, int) and 200 <= s < 300}
+        for sc in call.get("status_checks") or []:
+            if sc.get("v") == 200 and sc.get("op") in ("==", "!=") and ok and 200 not in ok and None not in statuses:
+                add("status_code", "high", f"client treats status {sc['op']} 200 as {'success' if sc['op'] == '==' else 'failure'}, "
+                    f"server success responses use {sorted(ok)}", client_check=self.at("fe", sc.get("file"), sc.get("line")))
+        return issues
+
+    def check_request(self, ra, call, add):
+        req = ra.get("request") or {}
+        fields = {}
+        for sc in req.get("schemas") or []:
+            if sc.get("location") in ("body", "form", None):
+                for k, v in self.schema_shape(sc["class"]).items():
+                    if not v.get("read_only"):
+                        fields[k] = dict(v, partial=sc.get("partial"))
+        for k in req.get("keys") or []:
+            if k.get("location") in ("body", "form"):
+                fields.setdefault(k["name"], {"type": None, "required": not k.get("optional"), "line": k.get("line"), "file": k.get("file")})
+        body = call.get("body_keys") or []
+        if not fields:
+            return []
+        if not body:
+            req_fields = [k for k, v in fields.items() if v.get("required") and not v.get("partial")]
+            if req_fields and not call.get("body_opaque"):
+                add("request_body_missing", "high", f"client sends no JSON body; server requires {req_fields}",
+                    server_field=self.at("be", fields[req_fields[0]].get("file"), fields[req_fields[0]].get("line")))
+            return []
+        ck = {b["key"]: b for b in body}
+        out_n = 0
+        for k, v in fields.items():
+            if k in ck:
+                b = ck[k]
+                kind, nullable = dart_kind(b.get("type"), self.enums)
+                sk = SERVER_KIND.get(v.get("type") or "", None)
+                if not compatible(kind, sk):
+                    add("request_type", "medium", f"`{k}`: client sends {b.get('type')}, server expects {v.get('type')}",
+                        key=k, client_field=self.at("fe", b.get("file"), b.get("line")), server_field=self.at("be", v.get("file"), v.get("line")))
+                if nullable and v.get("nullable") is False:
+                    sev = "medium" if b.get("conditional") else "high"  # unconditional key: an explicit null reaches validation
+                    add("request_nullability", sev, f"`{k}`: client value is nullable ({b.get('type')}), server field is not nullable"
+                        + ("" if b.get("conditional") else " -> a null value fails validation (422)"),
+                        key=k, client_field=self.at("fe", b.get("file"), b.get("line")), server_field=self.at("be", v.get("file"), v.get("line")))
+                continue
+            close = [c for c in ck if norm_key(c) == norm_key(k)]
+            if close:
+                add("request_case_mismatch", "high", f"client sends `{close[0]}`, server field is `{k}`", key=k,
+                    client_field=self.at("fe", ck[close[0]].get("file"), ck[close[0]].get("line")),
+                    server_field=self.at("be", v.get("file"), v.get("line")))
+            elif v.get("required") and not v.get("partial") and not v.get("default"):
+                add("request_missing_required", "high", f"server requires `{k}` ({v.get('type')}); client body has {sorted(ck)}", key=k,
+                    client_field=self.at("fe", body[0].get("file"), body[0].get("line")), server_field=self.at("be", v.get("file"), v.get("line")))
+        for c, b in ck.items():
+            if c not in fields and not any(norm_key(c) == norm_key(k) for k in fields):
+                add("request_unknown_field", "medium", f"client sends `{c}`, which the server schema does not declare (ignored/dropped)",
+                    key=c, client_field=self.at("fe", b.get("file"), b.get("line")))
+        return []
+
+    def check_response(self, ra, call, add):
+        shapes = self.success_shapes(ra)
+        if not shapes:
+            return []
+        merged: dict = {}
+        for s in shapes:
+            for k, v in (s["keys"] or {}).items():
+                if k not in merged:
+                    merged[k] = v
+                elif v.get("children") and not merged[k].get("children"):
+                    merged[k] = v
+        # top-level keys read directly
+        for rk in call.get("response_keys") or []:
+            sh = self.at_path(merged, rk.get("path"))
+            if sh is None:
+                continue
+            if rk["key"] not in sh:
+                close = [k for k in sh if norm_key(k) == norm_key(rk["key"])]
+                if close:
+                    add("response_case_mismatch", "high", f"client reads `{rk['key']}`, server sends `{close[0]}`", key=rk["key"],
+                        client_field=self.at("fe", rk.get("file"), rk.get("line")))
+                else:
+                    add("response_missing_key", "medium" if rk.get("coalesce") else "high",
+                        f"client reads `{rk['key']}`{' at ' + rk['path'] if rk.get('path') else ''}; no success response of the route has it "
+                        f"(server keys: {sorted(sh)[:12]})", key=rk["key"], client_field=self.at("fe", rk.get("file"), rk.get("line")),
+                        server_shape=[self.at("be", s.get("file"), s.get("line")) for s in shapes if s.get("file")][:4])
+        by_model: dict[str, list] = {}
+        for rm in call.get("response_models") or []:
+            if rm.get("path") not in [x.get("path") for x in by_model.get(rm["model"], [])]:
+                by_model.setdefault(rm["model"], []).append(rm)
+        err_merged: dict = {}
+        for s in self.success_shapes(ra, errors=True):
+            for k, v in (s["keys"] or {}).items():
+                err_merged.setdefault(k, v)
+        for mid, rms in by_model.items():
+            ma = self.fe.get(mid) or {}
+            if not ma.get("json_from"):
+                continue
+            if re.search(r"(Error|Failure|Exception|Problem)", mid.split("#")[-1]):
+                merged_ = err_merged  # error envelopes are parsed on non-2xx / success=false branches
+            else:
+                merged_ = merged
+            # the same model parsed at several JSON paths (`body['x']` with a fallback to `body`): judge the best-fitting one
+            best = None
+            for rm in rms:
+                path = rm.get("path")
+                sh = self.at_path(merged_, path) if path is not None else None
+                how = "path"
+                if sh is None and path is None:
+                    cands = [("", merged_)] + [(k, v.get("children")) for k, v in merged_.items() if v.get("children")]
+                    bo, pick = 0, None
+                    for p_, c_ in cands:
+                        o = len({x["key"] for x in ma["json_from"]} & set(c_ or {}))
+                        if o > bo:
+                            bo, pick = o, (p_, c_)
+                    if pick is None:
+                        continue
+                    path, sh, how = pick[0], pick[1], "best-overlap"
+                if sh is None:
+                    continue
+                tmp = []
+                self.compare_model(mid, ma, sh, path, lambda kind, sev, msg, **kw: tmp.append((kind, sev, msg, kw)), how, depth=0)
+                score = (sum(1 for t in tmp if t[1] == "high"), len(tmp))
+                if best is None or score < best[0]:
+                    best = (score, tmp, path)
+            if best:
+                alt = [r.get("path") for r in rms if r.get("path") != best[2]]
+                for kind, sev, msg, kw in best[1]:
+                    add(kind, sev, msg, **kw, **({"other_paths_parsed": alt} if alt else {}))
+        return []
+
+    def compare_model(self, mid, ma, sh, path, add, how, depth):
+        mname = mid.split("#")[-1]
+        for f in ma.get("json_from") or []:
+            k = f["key"]
+            loc = {"model": mname, "path": path or "", "key": k, "client_field": self.at("fe", f.get("file"), f.get("line")), "match": how}
+            v = sh.get(k)
+            if v is None:
+                close = [x for x in sh if norm_key(x) == norm_key(k)]
+                if close:
+                    add("response_case_mismatch", "high", f"{mname}.fromJson reads `{k}`, server sends `{close[0]}`",
+                        server_field=self.at("be", sh[close[0]].get("file"), sh[close[0]].get("line")), **loc)
+                else:
+                    tolerant = f.get("nullable") or f.get("coalesce") or f.get("default")
+                    add("response_missing_key", "low" if tolerant else "high",
+                        f"{mname}.fromJson reads `{k}` ({f.get('cast') or f.get('type')}); the server response{' at ' + path if path else ''} "
+                        f"has no such key" + (" (client tolerates null)" if tolerant else " -> cast of null fails"), **loc)
+                continue
+            sat = self.at("be", v.get("file"), v.get("line"))
+            ck, cnull = dart_kind(f.get("cast") or f.get("type"), self.enums)
+            if f.get("cast") is None and f.get("type"):
+                ck, cnull = dart_kind(f.get("type"), self.enums)
+            sk = SERVER_KIND.get(v.get("type") or "", None)
+            if ck == "object" and f.get("ref") and v.get("children") and depth < 4:
+                ra = self.fe.get(f["ref"]) or {}
+                self.compare_model(f["ref"], ra, v["children"], (path + "." if path else "") + k + ("[]" if f.get("many") else ""),
+                                   add, how, depth + 1)
+                continue
+            if f.get("many") and f.get("ref") and v.get("children") and depth < 4:
+                ra = self.fe.get(f["ref"]) or {}
+                self.compare_model(f["ref"], ra, v["children"], (path + "." if path else "") + k + "[]", add, how, depth + 1)
+                continue
+            if not compatible(ck if not f.get("many") else "list", sk, f.get("cast")):
+                add("response_type", "medium" if v.get("type") in ("fk", "model") or v.get("type") is None else "high", f"{mname}.`{k}`: client expects {f.get('cast') or f.get('type')}, server sends {v.get('type')}",
+                    server_field=sat, **loc)
+            snull = bool(v.get("nullable")) or v.get("type") == "null"
+            if snull and f.get("nullable") is False and not f.get("coalesce") and not f.get("default"):
+                add("response_nullability", "high", f"{mname}.`{k}`: server may send null, client reads it as non-nullable "
+                    f"{f.get('cast') or f.get('type')}", server_field=sat, **loc)
+            # enum values
+            if ck == "enum" and v.get("choices"):
+                en = re.sub(r"<.*", "", (f.get("type") or "").rstrip("?")).split(".")[-1]
+                ev = next((a.get("enum_values") for nid, a in self.fe.items() if nid.endswith("#" + en) and a.get("enum_values")), None)
+                if ev:
+                    cvals = {e["wire"] for e in ev}
+                    svals = {c if not isinstance(c, (list, tuple)) else c[0] for c in v["choices"]}
+                    if cvals != svals:
+                        add("response_enum_values", "high" if svals - cvals else "low",
+                            f"{mname}.`{k}` enum {en}: client values {sorted(cvals)}, server choices {sorted(map(str, svals))}",
+                            server_field=sat, **loc)