keygraph 0.2.0__py3-none-any.whl

keygraph/infer.py

@@ -0,0 +1,344 @@
+"""Relation inference: declared foreign keys plus naming, role, shared-key-name and polymorphic heuristics."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from .model import Schema, Table, type_family, type_length
+
+DEFAULT_ROLE_WORDS = {
+    "created", "updated", "deleted", "modified", "approved", "rejected", "assigned", "owner",
+    "parent", "original", "old", "new", "prev", "previous", "next", "source", "target", "from",
+    "to", "main", "primary", "default", "related", "linked", "buyer", "requested", "last", "first",
+}
+USER_LIKE = ["user", "users", "account", "accounts", "admin", "admins", "staff", "employee",
+             "employees", "member", "members", "person", "people", "operator", "operators"]
+BY_ROLES = {"created_by", "updated_by", "deleted_by", "modified_by", "approved_by", "rejected_by",
+            "assigned_by", "author", "creator", "owner", "editor", "assignee", "approver",
+            "reviewer", "requester", "updater"}
+SELF_ROLES = {"parent", "prev", "previous", "next", "original", "root", "master", "superseded"}
+POLY_SUFFIXES = ("type", "class", "table", "kind")
+
+
+@dataclass
+class Options:
+    min_confidence: float = 0.3
+    top_k: int = 3
+    prefixes: list[str] = field(default_factory=list)
+    aliases: dict[str, str] = field(default_factory=dict)  # stem -> table ref
+    role_aliases: dict[str, list[str]] = field(default_factory=dict)  # role stem -> table names
+    role_words: set[str] = field(default_factory=lambda: set(DEFAULT_ROLE_WORDS))
+    auto_prefixes: bool = True
+
+
+def singular(w: str) -> str:
+    if w.endswith("ies") and len(w) > 4:
+        return w[:-3] + "y"
+    if w.endswith(("sses", "xes", "ches", "shes", "zes")):
+        return w[:-2]
+    if w.endswith("s") and not w.endswith("ss") and len(w) > 3:
+        return w[:-1]
+    return w
+
+
+def plural(w: str) -> str:
+    if w.endswith("y") and len(w) > 2 and w[-2] not in "aeiou":
+        return w[:-1] + "ies"
+    if w.endswith(("s", "x", "z", "ch", "sh")):
+        return w + "es"
+    return w + "s"
+
+
+def forms(w: str) -> set[str]:
+    s = singular(w)
+    return {w, s, plural(s), plural(w) if not w.endswith("s") else w}
+
+
+def snake(name: str) -> str:
+    n = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "_", name)
+    return n.lower()
+
+
+def extract_stem(col: str) -> str | None:
+    n = snake(col)
+    if n == "id":
+        return None
+    if n.endswith("_id") and len(n) > 3:
+        return n[:-3]
+    if n.endswith("id") and len(n) > 4 and n[-3].isalpha() and "_" not in n:
+        return n[:-2]
+    return None
+
+
+def _ref(opts_ref: str, schema: Schema, prefer_schema: str) -> str | None:
+    if opts_ref in schema.tables:
+        return opts_ref
+    hits = [t for t in schema.tables if t.split(".", 1)[1] == opts_ref]
+    same = [t for t in hits if t.startswith(prefer_schema + ".")]
+    if same:
+        return same[0]
+    return hits[0] if len(hits) == 1 else None
+
+
+def _is_indexed_leading(t: Table, cols: list[str]) -> str | None:
+    n = len(cols)
+    for ix in t.indexes:
+        if len(ix.columns) >= n and set(ix.columns[:n]) == set(cols):
+            return ix.name
+    return None
+
+
+def cardinality(t: Table, cols: list[str]) -> str:
+    s = set(cols)
+    if t.primary_key and set(t.primary_key) == s:
+        return "one-to-one"
+    if any(set(u) == s for u in t.unique_keys):
+        return "one-to-one"
+    return "many-to-one"
+
+
+def target_key(t: Table, stem: str, colname: str):
+    pk = t.primary_key
+    if len(pk) == 1:
+        return pk, "primary key", 0.08
+    for u in t.unique_keys:
+        if len(u) == 1 and (u[0].lower() in (colname.lower(), "id", stem + "_id")):
+            return u, "unique key", 0.03
+    if not pk and not t.unique_keys:
+        return None
+    for u in ([pk] if pk else []) + t.unique_keys:
+        if len(u) > 1 and u[0].lower() == colname.lower() and t.column(u[0]):
+            return [u[0]], "leading column of a composite key (partial; join may fan out)", -0.25
+    return None
+
+
+class Inferer:
+    def __init__(self, schema: Schema, opts: Options):
+        self.s = schema
+        self.o = opts
+        self.lookup: dict[str, list[tuple[str, str]]] = {}
+        self.suffix_lookup: dict[str, list[str]] = {}
+        self.pkname: dict[str, list[str]] = {}
+        self._index()
+
+    def _auto_prefixes(self) -> dict[str, set[str]]:
+        out: dict[str, set[str]] = {}
+        if not self.o.auto_prefixes:
+            return out
+        for sch in {t.schema for t in self.s.tables.values()}:
+            names = [t.name for t in self.s.tables.values() if t.schema == sch]
+            cnt: dict[str, int] = {}
+            for n in names:
+                if "_" in n:
+                    cnt[n.split("_", 1)[0]] = cnt.get(n.split("_", 1)[0], 0) + 1
+            out[sch] = {p + "_" for p, c in cnt.items() if c >= max(4, int(0.1 * len(names)))}
+        return out
+
+    def _index(self) -> None:
+        auto = self._auto_prefixes()
+        for t in self.s.tables.values():
+            name = t.name.lower()
+            variants = {name: ""}
+            for p in list(self.o.prefixes) + sorted(auto.get(t.schema, ())):
+                if name.startswith(p.lower()) and len(name) > len(p):
+                    variants.setdefault(name[len(p):], p)
+            for v, pref in variants.items():
+                for f in forms(v):
+                    self.lookup.setdefault(f, []).append((t.id, pref))
+            parts = name.split("_")
+            for i in range(1, len(parts)):
+                suf = "_".join(parts[i:])
+                if len(suf) >= 3:
+                    for f in forms(suf):
+                        self.suffix_lookup.setdefault(f, []).append(t.id)
+            pk = t.primary_key
+            if len(pk) == 1 and pk[0].lower() != "id":
+                self.pkname.setdefault(pk[0].lower(), []).append(t.id)
+
+    # --- candidate generation -------------------------------------------------
+    def _add(self, cands: dict, tid: str, base: float, reason: str) -> None:
+        cur = cands.get(tid)
+        if cur is None:
+            cands[tid] = {"base": base, "reasons": [reason]}
+        else:
+            cur["base"] = max(cur["base"], base)
+            if reason not in cur["reasons"]:
+                cur["reasons"].append(reason)
+
+    def candidates(self, t: Table, colname: str, stem: str) -> dict:
+        c: dict = {}
+        words = stem.split("_")
+        for key in ["_".join(words[i:]) for i in range(len(words))]:
+            ref = self.o.aliases.get(key)
+            if ref:
+                tid = _ref(ref, self.s, t.schema)
+                if tid:
+                    self._add(c, tid, 0.9, f"alias '{key}' -> {tid} (user override)")
+        if stem in self.o.role_aliases or stem in BY_ROLES or stem.endswith("_by"):
+            names = list(self.o.role_aliases.get(stem, [])) + USER_LIKE
+            for nm in names:
+                tid = _ref(nm, self.s, t.schema)
+                if tid:
+                    self._add(c, tid, 0.65, f"role column '{colname}' reads as a user reference; mapped to {tid}")
+                    break
+        if words[0] in SELF_ROLES and (len(words) == 1 or any(
+                tid == t.id for f in forms("_".join(words[1:])) for tid, _ in self.lookup.get(f, []))):
+            self._add(c, t.id, 0.8 if words[0] == "parent" else 0.7,
+                      f"self-reference: '{colname}' points at this table's own key")
+        for f in forms(stem):
+            for tid, pref in self.lookup.get(f, []):
+                self._add(c, tid, 0.72 if not pref else 0.68,
+                          f"column name '{colname}' matches table name"
+                          + (f" (prefix '{pref}' stripped)" if pref else ""))
+        for i in range(1, len(words)):
+            rest = "_".join(words[i:])
+            allrole = all(w in self.o.role_words for w in words[:i])
+            for f in forms(rest):
+                for tid, pref in self.lookup.get(f, []):
+                    self._add(c, tid, 0.60 if allrole else 0.50,
+                              f"role prefix '{'_'.join(words[:i])}' stripped, '{rest}' matches table name")
+        for tid in self.pkname.get(colname.lower(), []):
+            if tid != t.id:
+                self._add(c, tid, 0.70, f"column name '{colname}' equals the primary key name of {tid}")
+        if not c:
+            tails = {tid for f in forms(stem) for tid in self.suffix_lookup.get(f, []) if tid.startswith(t.schema + ".")}
+            if len(tails) == 1:  # several tail matches is noise (e.g. every '*_users' table), so none is kept
+                tid = next(iter(tails))
+                self._add(c, tid, 0.35, f"'{stem}' matches the tail of table name {tid} (weak)")
+        c.pop(t.id, None) if not any("self-reference" in r for r in c.get(t.id, {}).get("reasons", [])) else None
+        return c
+
+    # --- scoring --------------------------------------------------------------
+    def score(self, t: Table, colname: str, stem: str, tid: str, cand: dict):
+        tt = self.s.tables[tid]
+        tk = target_key(tt, stem, colname)
+        if not tk:
+            return None
+        tcols, tdesc, tboost = tk
+        fc, tc = t.column(colname), tt.column(tcols[0])
+        ev = list(cand["reasons"])
+        conf = cand["base"]
+        ff, tf = type_family(fc.type if fc else ""), type_family(tc.type if tc else "")
+        if ff == "unknown" or tf == "unknown":
+            pass
+        elif ff == tf:
+            conf += 0.10
+            ev.append(f"compatible types ({ff} ~ {tf})")
+            if ff == "string" and type_length(fc.type) and type_length(fc.type) == type_length(tc.type):
+                conf += 0.03
+        elif {ff, tf} <= {"int", "decimal", "float", "bool"}:
+            conf -= 0.15
+            ev.append(f"loosely compatible types ({ff} vs {tf})")
+        else:
+            conf -= 0.35
+            ev.append(f"type mismatch ({fc.type} vs {tc.type})")
+        ix = _is_indexed_leading(t, [colname])
+        if ix:
+            conf += 0.07
+            ev.append(f"source column is the leading column of index '{ix}'")
+        conf += tboost
+        ev.append(f"target is the {tdesc} of {tid}: {','.join(tcols)}")
+        if t.schema == tt.schema:
+            conf += 0.05
+        else:
+            conf -= 0.10
+            ev.append("cross-schema match")
+        return {"to": tid, "to_columns": tcols, "confidence": conf, "evidence": ev,
+                "partial": tboost < 0}
+
+    def run(self) -> list[dict]:
+        edges: list[dict] = []
+        poly_cols: dict[str, list[dict]] = {}
+        unresolved: dict[str, list[str]] = {}
+        for t in self.s.tables.values():
+            declared_from = {c for fk in t.foreign_keys for c in fk.columns}
+            colnames = {c.name.lower() for c in t.columns}
+            for col in t.columns:
+                if col.name in declared_from:
+                    continue
+                stem = extract_stem(col.name)
+                if stem is None:
+                    continue
+                base = snake(col.name)[:-3] if snake(col.name).endswith("_id") else stem
+                pol = [base + "_" + s for s in POLY_SUFFIXES if (base + "_" + s) in colnames]
+                if pol:
+                    poly_cols.setdefault(t.id, []).append(
+                        {"id_column": col.name, "type_column": next(c.name for c in t.columns if c.name.lower() == pol[0]),
+                         "note": "polymorphic: the type column decides the target table; no single target"})
+                    continue
+                scored = []
+                for tid, cand in self.candidates(t, col.name, stem).items():
+                    r = self.score(t, col.name, stem, tid, cand)
+                    if r:
+                        scored.append(r)
+                if scored and any(r["to"].split(".")[0] == t.schema for r in scored):
+                    scored = [r for r in scored if r["to"].split(".")[0] == t.schema] or scored
+                scored.sort(key=lambda r: (-r["confidence"], r["to"]))
+                scored = scored[: self.o.top_k]
+                amb = len(scored) >= 2 and scored[0]["confidence"] - scored[1]["confidence"] < 0.12
+                kept = 0
+                for r in scored:
+                    if amb:
+                        r["confidence"] -= 0.10
+                        r["evidence"].append(f"ambiguous: {len(scored)} candidate targets within a close score")
+                    r["confidence"] = round(max(0.05, min(0.95, r["confidence"])), 2)
+                    if r["confidence"] < self.o.min_confidence:
+                        continue
+                    kept += 1
+                    edges.append({
+                        "kind": "inferred", "status": "inferred", "from": t.id, "from_columns": [col.name],
+                        "to": r["to"], "to_columns": r["to_columns"], "confidence": r["confidence"],
+                        "cardinality": "many-to-many" if r["partial"] else cardinality(t, [col.name]),
+                        "ambiguous": amb, "evidence": r["evidence"],
+                    })
+                if not kept:
+                    unresolved.setdefault(t.id, []).append(col.name)
+        self.polymorphic, self.unresolved = poly_cols, unresolved
+        return edges
+
+
+def declared_edges(schema: Schema, warnings: list[str]) -> list[dict]:
+    out = []
+    for t in schema.tables.values():
+        for fk in t.foreign_keys:
+            tid = f"{fk.ref_schema or t.schema}.{fk.ref_table}"
+            if tid not in schema.tables:
+                warnings.append(f"declared FK {t.id}({','.join(fk.columns)}) references unknown table {tid}")
+                continue
+            out.append({
+                "kind": "declared", "status": "declared", "from": t.id, "from_columns": list(fk.columns),
+                "to": tid, "to_columns": list(fk.ref_columns), "confidence": 1.0,
+                "cardinality": cardinality(t, list(fk.columns)), "ambiguous": False,
+                "evidence": [f"declared foreign key {fk.name or ''}".strip()], "constraint": fk.name or "",
+            })
+    return out
+
+
+def redundant_indexes(t: Table) -> list[dict]:
+    """Indexes that add nothing: a strict prefix of a longer index, or a duplicate of an equal one."""
+    out = []
+    ixs = [ix for ix in t.indexes if not ix.approximate]
+
+    def rank(ix):
+        return (0 if ix.primary else 1 if ix.unique else 2, ix.name)
+
+    for a in ixs:
+        if a.primary:
+            continue
+        la = len(a.columns)
+        for b in ixs:
+            if a is b or a.columns != b.columns[:la]:
+                continue
+            if len(b.columns) == la:
+                if rank(b) >= rank(a):
+                    continue
+                reason = "duplicate of another index on the same columns"
+            else:
+                if a.unique:
+                    continue
+                reason = "prefix of a longer index"
+            out.append({"index": a.name, "columns": a.columns, "covered_by": b.name,
+                        "covered_by_columns": b.columns, "reason": reason})
+            break
+    return out

keygraph/mcp_server.py

@@ -0,0 +1,147 @@
+"""MCP server: keygraph's read-only queries as tools for any MCP client.
+
+Each tool returns the same JSON as the matching `keygraph <command> --json`, except `areas`, which wraps the
+CLI's list as {"areas": [...]} (MCP tools return objects). Nothing here runs SQL or
+touches a database: it reads graph.json and keygraph.db from a built output directory.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ResourceError, ToolError
+
+from . import query as Q
+from . import search as S
+from .cli import area_result, describe_result, load_graph, path_result
+from .context import ContextDB
+from .docs_out import table_file
+from .graph import Graph
+
+INSTRUCTIONS = """keygraph maps the keys of a database and the relations between its tables. Everything is read-only
+and deterministic: it answers from a prebuilt graph and never queries the database.
+Start with `search` (find tables by business meaning) or `areas`, then `describe` a table, and use `path` before writing
+any multi-table JOIN. Relations are either declared foreign keys (confidence 1.0) or inferred from names and key shapes;
+inferred relations carry a confidence and the evidence behind it, so check anything below about 0.8 (and every fan-out
+hop, where one row becomes many) with a small SELECT. Value profiles are sampled, may be stale, and never contain raw
+values for PII columns. Table names resolve leniently, but when a bare name exists in several schemas, give schema.table."""
+
+
+MAX_DEPTH = 3  # neighbors beyond 3 hops returns most of a large graph
+
+
+def build_server(dir: str | Path) -> MCPServer:
+    """Create the server for a built output directory (does not start it)."""
+    out = Path(dir)
+    load_graph(out)  # fail early with a clear message when nothing was built
+    cache: dict = {}
+
+    def graph() -> Graph:
+        """The graph, reloaded only when graph.json changed (the directory may be rebuilt while we serve)."""
+        stamp = (out / "graph.json").stat().st_mtime_ns
+        if cache.get("stamp") != stamp:
+            cache["stamp"], cache["g"] = stamp, load_graph(out)
+        return cache["g"]
+
+    def run(fn, *a, **kw):
+        try:
+            return fn(*a, **kw)
+        except (ValueError, KeyError) as exc:  # unknown/ambiguous table, bad reference: tell the agent how to fix it
+            raise ToolError(str(exc.args[0] if isinstance(exc, KeyError) and exc.args else exc)) from None
+
+    srv = MCPServer("keygraph", instructions=INSTRUCTIONS)
+
+    @srv.tool()
+    def search(query: str, limit: int = 10) -> dict:
+        """Find tables by business meaning ("monthly revenue", "in transit", a status label). Use this first when you
+        do not know which table holds something, then describe the top hit. Returns ranked tables with the reason each matched (names, business
+        concepts, synonyms, metrics, notes, documented code labels), grain, primary key and pitfalls when known.
+        Matches on profiled values never expose PII."""
+        g = graph()
+        with ContextDB(out / "keygraph.db", g, readonly=True) as ctx:
+            return run(S.search, g, ctx, query, limit)
+
+    @srv.tool()
+    def describe(table: str) -> dict:
+        """Everything known about one table: keys and indexes, columns, business context (grain, pitfalls, code
+        meanings) and its relations grouped by role (parent, child, lookup, audit...) with confidence. Use it
+        before querying a table you have not seen. Give schema.table when the bare name exists in several schemas."""
+        return run(describe_result, out, graph(), table, True)
+
+    @srv.tool()
+    def keys(table: str) -> dict:
+        """Primary key, unique keys and every index of a table, in column order. Use it before filtering a big
+        table: filter on the leading column of an index so the query stays fast."""
+        return run(Q.keys, graph(), table)
+
+    @srv.tool()
+    def explain(column_ref: str) -> dict:
+        """What one column (schema.table.column) references and what references it, with the evidence for each
+        relation. Inferred relations carry a confidence and evidence lines; declared foreign keys are 1.0."""
+        return run(Q.explain, graph(), column_ref)
+
+    @srv.tool()
+    def path(from_table: str, to_table: str, max_hops: int = 4, min_confidence: float = 0.6, k: int = 3,
+             include_mirrors: bool = False) -> dict:
+        """Ranked join paths between two tables, each hop with its columns, confidence, evidence, fan-out warnings
+        and a ready JOIN ... ON snippet. Use it before writing any join across more than one table. Inferred hops
+        are guesses (check evidence, verify with a small SELECT when confidence is below 0.8 or a hop fans out).
+        Paths avoid hub tables as stepping stones and mirror schemas (copies of another schema) unless
+        include_mirrors is true."""
+        return run(path_result, graph(), from_table, to_table, max_hops, min_confidence, k, include_mirrors)
+
+    @srv.tool()
+    def neighbors(table: str, depth: int = 1) -> dict:
+        """Tables directly (depth 1) or transitively (depth 2 or 3; larger values are capped at 3) related to a table,
+        with the relation kind and confidence. It has no confidence filter: weak inferred relations are included, so
+        read each confidence. Use it to see what a table connects to when you do not have a target table in mind."""
+        return run(Q.neighbors, graph(), table, max(1, min(int(depth), MAX_DEPTH)), 0.0)
+
+    @srv.tool()
+    def areas(include_mirrors: bool = False) -> dict:
+        """The business areas: clusters of related tables (for example Ordering, Catalog, Payments), with size and
+        most connected tables. Use it to get an overview of an unfamiliar database. Mirror schemas are left out
+        unless include_mirrors is true. Returns {"areas": [...]}, the list the CLI prints with --json."""
+        return {"areas": run(Q.list_areas, graph(), include_mirrors=include_mirrors)}
+
+    @srv.tool()
+    def area(name_or_table: str, include_mirrors: bool = False) -> dict:
+        """One area in detail: its tables with grain, the relations inside it, neighbouring areas and hub labels.
+        Give an area id, an area name (any case) or a table that belongs to it."""
+        return run(area_result, out, graph(), name_or_table, include_mirrors, True)
+
+    @srv.tool()
+    def profile_summary(table: str) -> dict:
+        """Stored value profiles for the columns of a table: null rate, distinct count, ranges, top values, recency and
+        pattern hints, each with when and how it was sampled. Profiles are sampled and may be stale. PII columns never
+        include raw values, only counts, length and pattern. This reads stored results only and never queries the
+        database; columns is empty when the table was not profiled."""
+        g = graph()
+        t = run(g.resolve, table)
+        with ContextDB(out / "keygraph.db", g, readonly=True) as ctx:
+            prefix = t + "."
+            cols = {k[len(prefix):]: v for k, v in ctx.load_profiles().items() if k.startswith(prefix)}
+        return {"table": t, "columns": cols}
+
+    def _read(rel: str) -> str:
+        p = (out / rel).resolve()
+        if out.resolve() not in p.parents or not p.is_file():
+            raise ResourceError(f"no page {rel}")
+        return p.read_text(encoding="utf-8")
+
+    @srv.resource("keygraph://areas/index", mime_type="text/markdown")
+    def areas_index() -> str:
+        """Markdown index of all business areas."""
+        return _read("areas/index.md")
+
+    @srv.resource("keygraph://tables/{id}", mime_type="text/markdown")
+    def table_page(id: str) -> str:
+        """Markdown page for one table (schema.table): area, grain, keys and indexes, columns and relations."""
+        try:
+            t = graph().resolve(id)
+        except ValueError as exc:
+            raise ResourceError(str(exc)) from None
+        return _read("tables/" + table_file(t))
+
+    return srv

keygraph/mirrors.py

@@ -0,0 +1,109 @@
+"""Mirror schemas: a schema whose tables duplicate another schema's tables (a BI or reporting copy, a replica
+loaded under another name). Their tables would double every area, hub count and join path, so keygraph marks
+them and keeps them out of areas, hubs and path search unless asked for."""
+
+from __future__ import annotations
+
+from keygraph.graph import Graph
+
+MIRROR_SHARE = 0.8
+
+
+def _copies(a: frozenset, b: frozenset | None) -> bool:
+    """Two tables of the same name are copies when their column-name sets match or one contains the other
+    (a reporting copy often adds a load timestamp or drops a wide column)."""
+    return b is not None and (a == b or a <= b or b <= a)
+
+
+def _structure(graph: Graph, schema: str, tables: set[str]) -> int:
+    """How much a schema's copy of `tables` looks like a source database: secondary indexes, plus relations among
+    those tables (declared count three times; role columns such as created_by_id do not count). A reporting copy
+    usually keeps the columns but drops the keys."""
+    from keygraph.hubs import is_role_column
+    ids = {f"{schema}.{t}" for t in tables}
+    ix = sum(1 for t in ids for i in graph.nodes[t]["indexes"] if not i["primary"])
+    rel = sum(3 if e["kind"] == "declared" else 1 for e in graph.edges
+              if e["from"] in ids and e["to"] in ids and e["from"] != e["to"] and not any(is_role_column(c) for c in e["from_columns"]))
+    return ix + rel
+
+
+def _original(graph: Graph, by: dict, a: str, b: str, common: set[str]) -> tuple[str, str, bool]:
+    """Which of two schemas sharing `common` tables is the source: (original, reason, close call?).
+    (a) the one with clearly more keys and relations on the shared tables, (b) then the one with fewer tables
+    the other lacks (a copy tends to add load or log tables), (c) then the larger, (d) then the name."""
+    sa, sb = _structure(graph, a, common), _structure(graph, b, common)
+    if max(sa, sb) >= 2 and max(sa, sb) >= 1.25 * min(sa, sb) + 1:
+        return (a if sa > sb else b), f"keys and relations ({max(sa, sb)} vs {min(sa, sb)})", False
+    ea, eb = len(by[a]) - len(common), len(by[b]) - len(common)
+    if ea != eb:
+        return (a if ea < eb else b), f"fewer extra tables ({min(ea, eb)} vs {max(ea, eb)}); keys and relations look alike", True
+    if len(by[a]) != len(by[b]):
+        return (a if len(by[a]) > len(by[b]) else b), "size; keys, relations and extra tables look alike", True
+    return min(a, b), "name only; the two schemas look alike", True
+
+
+def detect_mirrors(graph: Graph, share: float = MIRROR_SHARE, min_tables: int = 2,
+                   force: dict[str, str] | None = None, never: set[str] | frozenset = frozenset(),
+                   warnings: list[str] | None = None) -> dict[str, str]:
+    """{mirror schema: original schema}. Two schemas are a mirror pair when at least `share` of one schema's tables
+    are copies (same name, see _copies) of the other's. Which side is the source is guessed by _original; a schema
+    is marked a mirror only when it is the copy and at least `share` of its own tables are copies. A close guess, a
+    `force` ({mirror: original}, from a context file) that disagrees with the guess, or a forced pair naming an
+    unknown schema adds a line to `warnings`. `never` lists schemas that are never mirrors."""
+    warn = warnings.append if warnings is not None else (lambda _m: None)
+    by: dict[str, dict[str, frozenset]] = {}
+    for n in graph.nodes.values():
+        by.setdefault(n["schema"], {})[n["table"]] = frozenset(c["name"] for c in n["columns"])
+
+    def common(x: str, y: str) -> set[str]:
+        return {t for t, cols in by[x].items() if _copies(cols, by[y].get(t))}
+
+    guess: dict[str, str] = {}
+    why: dict[str, str] = {}
+    seen: set[frozenset] = set()
+    for s in sorted(by, key=lambda x: (-len(by[x]), x)):
+        if len(by[s]) < min_tables:
+            continue
+        cands = [(len(common(s, o)), o) for o in by if o != s]
+        hits, o = max(cands, default=(0, None))
+        if o is None or hits / len(by[s]) < share or frozenset((s, o)) in seen:
+            continue
+        seen.add(frozenset((s, o)))
+        shared = common(s, o)
+        orig, reason, close = _original(graph, by, s, o, shared)
+        copy = o if orig == s else s
+        if len(common(copy, orig)) / len(by[copy]) < share:
+            warn(f"mirror guess: {orig} and {copy} share {len(shared)} tables and {orig} looks like the source "
+                 f"({reason}), but {copy} is not mostly copies, so neither is marked a mirror; confirm with mirrors.yaml")
+            continue
+        guess[copy], why[copy] = orig, reason
+        if close:
+            warn(f"mirror guess: {copy} copies {orig} (decided by {reason}) — confirm with mirrors.yaml")
+    out = {m: o for m, o in guess.items() if m not in never}
+    for m, o in (force or {}).items():
+        if m not in by or o not in by or m == o:
+            warn(f"mirrors.yaml: '{m}: {o}' ignored: unknown schema" if (m not in by or o not in by) else f"mirrors.yaml: '{m}: {o}' ignored")
+            continue
+        if guess.get(o) == m or (m in guess and guess[m] != o):
+            g = f"{o} copies {m}" if guess.get(o) == m else f"{m} copies {guess[m]}"
+            warn(f"mirror guess: mirrors.yaml says {m} copies {o}, which disagrees with the guess ({g}, by {why.get(o) or why.get(m)}); using mirrors.yaml")
+        out.pop(o, None) if out.get(o) == m else None
+        out[m] = o
+    for m in list(out):  # an original is never itself a mirror: follow chains to the root
+        root, hops = out[m], 0
+        while root in out and hops < len(out):
+            root, hops = out[root], hops + 1
+        out[m] = root
+    return dict(sorted((m, o) for m, o in out.items() if m != o))
+
+
+def mark_mirrors(graph: Graph, mirrors: dict[str, str]) -> None:
+    for n in graph.nodes.values():
+        n.pop("mirror_of", None)
+        if n["schema"] in mirrors:
+            n["mirror_of"] = mirrors[n["schema"]]
+    graph.data["mirrors"] = dict(sorted(mirrors.items()))
+
+
+def mirror_tables(graph: Graph) -> set[str]:
+    return {t for t, n in graph.nodes.items() if n.get("mirror_of")}