schema-impact-map 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,3 @@
1
+ """Schema Impact Map: relational schema map with impact highlighting."""
2
+
3
+ __version__ = "0.2.0"
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())
@@ -0,0 +1,340 @@
1
+ from __future__ import annotations
2
+
3
+ from pathlib import Path
4
+
5
+ from .io import DataError, load_json, load_yaml
6
+ from .sql import parse_sql_files
7
+
8
+ CONFIG_FILE = "schema-impact-map.yaml"
9
+
10
+
11
+ def _column_id(qualified: str) -> str:
12
+ return f"column:{qualified}"
13
+
14
+
15
+ def _table_id(qualified: str) -> str:
16
+ return f"table:{qualified}"
17
+
18
+
19
+ def _database_id(name: str) -> str:
20
+ return f"database:{name}"
21
+
22
+
23
+ def _edge_priority(kind: str) -> int:
24
+ return {"fk": 3, "value_overlap": 2, "join": 1}.get(kind, 0)
25
+
26
+
27
+ class Builder:
28
+ def __init__(self, data_dir: Path):
29
+ self.data_dir = data_dir
30
+ self.config = load_yaml(data_dir / CONFIG_FILE)
31
+ self.schema = load_json(data_dir / self.config.get("schema", "schema.json"))
32
+ self.entities_cfg = load_yaml(data_dir / self.config.get("entities", "entities.yaml"))
33
+ self.rules = load_yaml(data_dir / self.config.get("rules", "rules.yaml"))
34
+ self.dialect = self.config.get("dialect", "mysql")
35
+ self.default_database = self.config.get(
36
+ "default_database",
37
+ self.schema["databases"][0]["name"],
38
+ )
39
+ self.tables: dict[str, dict] = {}
40
+ self.columns: dict[str, dict] = {}
41
+ self.databases: dict[str, dict] = {}
42
+ self.errors: list[str] = []
43
+
44
+ # ---------------------------------------------------------------- load
45
+
46
+ def load_schema(self) -> None:
47
+ for database in self.schema.get("databases", []):
48
+ db_name = database["name"]
49
+ self.databases[db_name] = {
50
+ "id": _database_id(db_name),
51
+ "kind": "database",
52
+ "name": db_name,
53
+ "comment": database.get("comment", ""),
54
+ }
55
+ for table in database.get("tables", []):
56
+ qualified = f"{db_name}.{table['name']}"
57
+ columns = []
58
+ for raw in table.get("columns", []):
59
+ column = {
60
+ "id": _column_id(f"{qualified}.{raw['name']}"),
61
+ "kind": "column",
62
+ "name": raw["name"],
63
+ "qualified": f"{qualified}.{raw['name']}",
64
+ "table": qualified,
65
+ "database": db_name,
66
+ "type": raw.get("type", ""),
67
+ "pk": bool(raw.get("pk", False)),
68
+ "unique": bool(raw.get("unique", False)),
69
+ "comment": raw.get("comment", ""),
70
+ }
71
+ columns.append(column)
72
+ self.columns[column["qualified"]] = column
73
+ table_entry = {
74
+ "id": _table_id(qualified),
75
+ "kind": "table",
76
+ "name": table["name"],
77
+ "qualified": qualified,
78
+ "database": db_name,
79
+ "comment": table.get("comment", ""),
80
+ "rows": table.get("rows", 0),
81
+ "columns": columns,
82
+ }
83
+ self.tables[qualified] = table_entry
84
+ self.databases[db_name].setdefault("tables", []).append(table_entry["id"])
85
+
86
+ # ---------------------------------------------------------------- edges
87
+
88
+ def _is_key(self, qualified: str) -> bool:
89
+ column = self.columns.get(qualified)
90
+ if not column:
91
+ return False
92
+ # only a single-column PK / single-column UNIQUE key is a parent key;
93
+ # one column of a composite key is not
94
+ table = self.tables.get(column["table"], {})
95
+ if column["pk"] and sum(1 for c in table.get("columns", []) if c["pk"]) == 1:
96
+ return True
97
+ return column["unique"]
98
+
99
+ def _orient(self, left: str, right: str) -> tuple[str, str]:
100
+ """Return ``(child, parent)``."""
101
+ left_key, right_key = self._is_key(left), self._is_key(right)
102
+ if right_key and not left_key:
103
+ return left, right
104
+ if left_key and not right_key:
105
+ return right, left
106
+ left_name = left.rsplit(".", 1)[-1]
107
+ right_name = right.rsplit(".", 1)[-1]
108
+ if left_name == "id" and right_name != "id":
109
+ return right, left
110
+ if right_name == "id" and left_name != "id":
111
+ return left, right
112
+ return left, right
113
+
114
+ def _add_relation(self, relations: dict, child: str, parent: str, kind: str,
115
+ confidence: float, method: str, evidence: dict | None) -> None:
116
+ for qualified in (child, parent):
117
+ if qualified not in self.columns:
118
+ self.errors.append(f"relation references unknown column: {qualified}")
119
+ return
120
+ key = (child, parent)
121
+ existing = relations.get(key)
122
+ incoming = {
123
+ "child": child,
124
+ "parent": parent,
125
+ "kind": kind,
126
+ "confidence": confidence,
127
+ "method": method,
128
+ "evidence": evidence,
129
+ }
130
+ if not existing:
131
+ relations[key] = incoming
132
+ return
133
+ # keep the strongest evidence per child->parent and merge the methods
134
+ if _edge_priority(kind) > _edge_priority(existing["kind"]):
135
+ existing.update(incoming)
136
+ elif kind == "fk" and "sql_join" not in existing["method"]:
137
+ existing["method"] = f"{existing['method']}+sql_join"
138
+ existing["confidence"] = 1.0
139
+ elif kind == "join" and existing["kind"] == "fk":
140
+ existing["confidence"] = 1.0
141
+ if "sql_join" not in existing["method"]:
142
+ existing["method"] = f"{existing['method']}+sql_join"
143
+ evidence = existing.get("evidence")
144
+ if evidence and isinstance(evidence, list):
145
+ if incoming["evidence"] and incoming["evidence"] not in evidence:
146
+ evidence.append(incoming["evidence"])
147
+ elif evidence and incoming["evidence"]:
148
+ existing["evidence"] = [evidence, incoming["evidence"]]
149
+ elif incoming["evidence"]:
150
+ existing["evidence"] = incoming["evidence"]
151
+
152
+ def build_relations(self, statements: list[dict]) -> list[dict]:
153
+ relations: dict[tuple[str, str], dict] = {}
154
+
155
+ for raw in self.schema.get("relations", []):
156
+ self._add_relation(
157
+ relations,
158
+ raw["child"],
159
+ raw["parent"],
160
+ kind="fk" if raw.get("method") == "ddl_fk" else raw.get("kind", "value_overlap"),
161
+ confidence=float(raw.get("confidence", 1.0)),
162
+ method=raw.get("method", "declared"),
163
+ evidence={"file": "schema.json", "snippet": raw.get("note", "")},
164
+ )
165
+
166
+ for statement in statements:
167
+ for join in statement.get("joins", []):
168
+ child, parent = self._orient(join["left"], join["right"])
169
+ self._add_relation(
170
+ relations,
171
+ child,
172
+ parent,
173
+ kind="join",
174
+ confidence=0.9,
175
+ method="sql_join",
176
+ evidence={"file": statement["file"], "snippet": join["snippet"]},
177
+ )
178
+
179
+ edges = []
180
+ for relation in relations.values():
181
+ edges.append(
182
+ {
183
+ "src": _column_id(relation["child"]),
184
+ "dst": _column_id(relation["parent"]),
185
+ "kind": relation["kind"],
186
+ "confidence": relation["confidence"],
187
+ "method": relation["method"],
188
+ "evidence": relation["evidence"],
189
+ }
190
+ )
191
+ return edges
192
+
193
+ # ---------------------------------------------------------------- entities
194
+
195
+ def build_entities(self) -> tuple[list[dict], list[dict]]:
196
+ entities: list[dict] = []
197
+ edges: list[dict] = []
198
+ for name, spec in (self.entities_cfg.get("entities") or {}).items():
199
+ canonical = spec.get("canonical")
200
+ aliases = spec.get("aliases") or []
201
+ keys = spec.get("alternate_keys") or []
202
+ members = []
203
+ for column, role in [
204
+ (canonical, "canonical"),
205
+ *[(item, "alias") for item in aliases],
206
+ *[(item, "key") for item in keys],
207
+ ]:
208
+ if not column:
209
+ continue
210
+ if column not in self.columns:
211
+ self.errors.append(f"entity {name} references unknown column: {column}")
212
+ continue
213
+ members.append({"column": column, "role": role})
214
+ edges.append(
215
+ {
216
+ "src": _column_id(column),
217
+ "dst": f"entity:{name}",
218
+ "kind": "same_entity",
219
+ "confidence": 1.0,
220
+ "method": "human",
221
+ "evidence": {"file": "entities.yaml", "snippet": f"{role}: {column}"},
222
+ }
223
+ )
224
+ edges.append(
225
+ {
226
+ "src": f"entity:{name}",
227
+ "dst": _column_id(column),
228
+ "kind": "represents",
229
+ "confidence": 1.0,
230
+ "method": "human",
231
+ "evidence": {"file": "entities.yaml", "snippet": f"{role}: {column}"},
232
+ }
233
+ )
234
+ entities.append(
235
+ {
236
+ "id": f"entity:{name}",
237
+ "kind": "entity",
238
+ "name": name,
239
+ "title": spec.get("title", name),
240
+ "canonical": canonical,
241
+ "members": members,
242
+ }
243
+ )
244
+ return entities, edges
245
+
246
+ # ---------------------------------------------------------------- check
247
+
248
+ def check(self, tables: list[dict], entities: list[dict], edges: list[dict]) -> dict:
249
+ errors = list(self.errors)
250
+ warnings: list[str] = []
251
+ members = {
252
+ member["column"]
253
+ for entity in entities
254
+ for member in entity.get("members", [])
255
+ }
256
+ related = set()
257
+ for edge in edges:
258
+ if edge["kind"] in {"fk", "join", "value_overlap"}:
259
+ related.add(edge["src"].split(":", 1)[-1])
260
+ related.add(edge["dst"].split(":", 1)[-1])
261
+
262
+ ignored = set((self.rules.get("ignore_columns") or {}).keys())
263
+ patterns = self.rules.get("relation_patterns") or ["*_id"]
264
+ orphans = []
265
+ for table in tables:
266
+ for column in table["columns"]:
267
+ if not any(
268
+ column["name"].endswith(pattern.lstrip("*")) if pattern.startswith("*")
269
+ else column["name"] == pattern
270
+ for pattern in patterns
271
+ ):
272
+ continue
273
+ if column["name"] in ignored:
274
+ continue
275
+ if column["qualified"] in members or column["qualified"] in related:
276
+ continue
277
+ orphans.append(column["qualified"])
278
+
279
+ for qualified in orphans:
280
+ errors.append(f"unresolved relation column: {qualified}")
281
+
282
+ return {
283
+ "ok": not errors,
284
+ "errors": errors,
285
+ "warnings": warnings,
286
+ "orphans": orphans,
287
+ }
288
+
289
+ # ---------------------------------------------------------------- build
290
+
291
+ def build(self) -> dict:
292
+ self.load_schema()
293
+ sql_dir = self.data_dir / self.config.get("sql", "sql")
294
+ statements = parse_sql_files(
295
+ sql_dir,
296
+ self.dialect,
297
+ self.tables,
298
+ self.default_database,
299
+ )
300
+ relation_edges = self.build_relations(statements)
301
+ entities, entity_edges = self.build_entities()
302
+ edges = relation_edges + entity_edges
303
+
304
+ # node list: database / table / column / entity
305
+ tables = sorted(self.tables.values(), key=lambda table: table["qualified"])
306
+ columns = sorted(self.columns.values(), key=lambda column: column["qualified"])
307
+ check = self.check(tables, entities, edges)
308
+ graph = {
309
+ "version": 1,
310
+ "name": self.config.get("name", self.data_dir.name),
311
+ "instance": self.schema.get("instance", "demo"),
312
+ "databases": sorted(self.databases.values(), key=lambda item: item["name"]),
313
+ "tables": [
314
+ {
315
+ **table,
316
+ "columns": sorted(table["columns"], key=lambda c: c["name"]),
317
+ }
318
+ for table in tables
319
+ ],
320
+ "columns": columns,
321
+ "entities": entities,
322
+ "edges": edges,
323
+ "statements": statements,
324
+ "check": check,
325
+ "stats": {
326
+ "databases": len(self.databases),
327
+ "tables": len(tables),
328
+ "columns": len(columns),
329
+ "edges": len(edges),
330
+ "statements": len(statements),
331
+ "entities": len(entities),
332
+ },
333
+ }
334
+ return graph
335
+
336
+
337
+ def build_from_dir(data_dir: Path) -> dict:
338
+ if not data_dir.exists():
339
+ raise DataError(f"data directory not found: {data_dir}")
340
+ return Builder(data_dir).build()
@@ -0,0 +1,160 @@
1
+ from __future__ import annotations
2
+
3
+ import argparse
4
+ import sys
5
+ from pathlib import Path
6
+
7
+ from . import __version__
8
+ from .build import build_from_dir
9
+ from .impact import analyze_file
10
+ from .io import DataError, write_json
11
+ from .render import write_html
12
+
13
+
14
+ DEFAULT_DATA = Path("examples/shop")
15
+ DEFAULT_OUT = Path("site")
16
+
17
+
18
+ def _build(data: Path) -> dict:
19
+ graph = build_from_dir(data)
20
+ if not graph["check"]["ok"]:
21
+ for error in graph["check"]["errors"]:
22
+ print(f" ! {error}", file=sys.stderr)
23
+ raise DataError(f"{len(graph['check']['errors'])} data check error(s)")
24
+ return graph
25
+
26
+
27
+ def _print_stats(graph: dict) -> None:
28
+ stats = graph["stats"]
29
+ print(
30
+ f"graph: {stats['databases']} databases / {stats['tables']} tables / "
31
+ f"{stats['columns']} columns / {stats['edges']} edges / "
32
+ f"{stats['statements']} SQL statements"
33
+ )
34
+
35
+
36
+ def cmd_build(args) -> int:
37
+ graph = _build(args.data)
38
+ _print_stats(graph)
39
+ out = args.out / "graph.json"
40
+ write_json(out, graph)
41
+ print(f"-> {out}")
42
+ return 0
43
+
44
+
45
+ def cmd_map(args) -> int:
46
+ graph = _build(args.data)
47
+ _print_stats(graph)
48
+ write_html(args.out, graph, focus=args.focus)
49
+ print(f"-> {args.out}")
50
+ return 0
51
+
52
+
53
+ def cmd_impact(args) -> int:
54
+ graph = _build(args.data)
55
+ payload = analyze_file(graph, args.plan)
56
+ write_html(args.out, payload["graph"], payload, focus=next(iter(payload["changed"]), None))
57
+ print(
58
+ f"impact: {len(payload['changed'])} changed / "
59
+ f"{len(payload['affected'])} affected / "
60
+ f"{sum(len(v) for v in payload['collisions'].values())} collisions / "
61
+ f"{len(payload['statements'])} SQL"
62
+ )
63
+ print(f"-> {args.out}")
64
+ return 0
65
+
66
+
67
+ def cmd_check(args) -> int:
68
+ graph = _build(args.data)
69
+ check = graph["check"]
70
+ if check["ok"]:
71
+ print(f"PASS: {len(graph['tables'])} tables, {len(graph['columns'])} columns, "
72
+ f"{len(graph['edges'])} edges")
73
+ return 0
74
+ print(f"FAIL: {len(check['errors'])} error(s)")
75
+ for error in check["errors"]:
76
+ print(f" - {error}")
77
+ return 1
78
+
79
+
80
+ def cmd_demo(args) -> int:
81
+ graph = _build(args.data)
82
+ _print_stats(graph)
83
+ args.out.mkdir(parents=True, exist_ok=True)
84
+ write_json(args.out / "graph.json", graph)
85
+ write_html(args.out / "index.html", graph)
86
+ print(f"-> {args.out / 'index.html'}")
87
+
88
+ impact_plan = args.data / "plans" / "customer-key.yaml"
89
+ if impact_plan.exists():
90
+ payload = analyze_file(graph, impact_plan)
91
+ write_html(args.out / "impact.html", payload["graph"], payload,
92
+ focus=next(iter(payload["changed"]), None))
93
+ write_json(args.out / "impact.json", payload)
94
+ print(f"-> {args.out / 'impact.html'}")
95
+
96
+ refund_plan = args.data / "plans" / "add-refund-status.yaml"
97
+ if refund_plan.exists():
98
+ payload = analyze_file(graph, refund_plan)
99
+ write_html(args.out / "impact-refund.html", payload["graph"], payload,
100
+ focus=next(iter(payload["changed"]), None))
101
+ print(f"-> {args.out / 'impact-refund.html'}")
102
+ return 0
103
+
104
+
105
+ def cmd_mcp(args) -> int:
106
+ from .mcp import main as serve_mcp
107
+
108
+ return serve_mcp()
109
+
110
+
111
+ def build_parser() -> argparse.ArgumentParser:
112
+ parser = argparse.ArgumentParser(
113
+ prog="schema-impact-map",
114
+ description="Interactive relational schema map with impact highlighting.",
115
+ )
116
+ parser.add_argument("--version", action="version", version=f"schema-impact-map {__version__}")
117
+ sub = parser.add_subparsers(dest="command", required=True)
118
+
119
+ build = sub.add_parser("build", help="build graph JSON from a data directory")
120
+ build.add_argument("--data", type=Path, default=DEFAULT_DATA)
121
+ build.add_argument("--out", type=Path, default=Path("dist"))
122
+ build.set_defaults(func=cmd_build)
123
+
124
+ map_cmd = sub.add_parser("map", help="render the interactive schema map")
125
+ map_cmd.add_argument("--data", type=Path, default=DEFAULT_DATA)
126
+ map_cmd.add_argument("--out", type=Path, default=Path("site/map.html"))
127
+ map_cmd.add_argument("--focus", help="column to focus initially")
128
+ map_cmd.set_defaults(func=cmd_map)
129
+
130
+ impact = sub.add_parser("impact", help="render a plan-impact map")
131
+ impact.add_argument("--data", type=Path, default=DEFAULT_DATA)
132
+ impact.add_argument("--plan", type=Path, required=True)
133
+ impact.add_argument("--out", type=Path, default=Path("site/impact.html"))
134
+ impact.set_defaults(func=cmd_impact)
135
+
136
+ check = sub.add_parser("check", help="validate the demo data / ledger")
137
+ check.add_argument("--data", type=Path, default=DEFAULT_DATA)
138
+ check.set_defaults(func=cmd_check)
139
+
140
+ demo = sub.add_parser("demo", help="build graph + map + impact pages for the demo")
141
+ demo.add_argument("--data", type=Path, default=DEFAULT_DATA)
142
+ demo.add_argument("--out", type=Path, default=DEFAULT_OUT)
143
+ demo.set_defaults(func=cmd_demo)
144
+
145
+ sub.add_parser(
146
+ "mcp",
147
+ help="serve the MCP tools over stdio for Claude Code, Codex, ZCode or WorkBuddy",
148
+ ).set_defaults(func=cmd_mcp)
149
+
150
+ return parser
151
+
152
+
153
+ def main(argv: list[str] | None = None) -> int:
154
+ parser = build_parser()
155
+ args = parser.parse_args(argv)
156
+ try:
157
+ return int(args.func(args))
158
+ except DataError as exc:
159
+ print(f"error: {exc}", file=sys.stderr)
160
+ return 1