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,194 @@
1
+ from __future__ import annotations
2
+
3
+ import copy
4
+ import re
5
+ from pathlib import Path
6
+
7
+ from .io import DataError, load_yaml
8
+
9
+
10
+ GENERIC_TOKENS = {"id", "code", "no", "type", "time", "name", "info", "created", "updated"}
11
+
12
+
13
+ def _column_id(qualified: str) -> str:
14
+ return f"column:{qualified}"
15
+
16
+
17
+ def _tokens(name: str) -> set[str]:
18
+ return {
19
+ token for token in re.split(r"[_\W]+", name.lower())
20
+ if token and token not in GENERIC_TOKENS
21
+ }
22
+
23
+
24
+ def _find_column(graph: dict, qualified: str) -> dict | None:
25
+ for column in graph["columns"]:
26
+ if column["qualified"] == qualified:
27
+ return column
28
+ return None
29
+
30
+
31
+ def _find_table(graph: dict, qualified: str) -> dict | None:
32
+ for table in graph["tables"]:
33
+ if table["qualified"] == qualified:
34
+ return table
35
+ return None
36
+
37
+
38
+ def _add_column(graph: dict, table_name: str, name: str, column_type: str = "",
39
+ comment: str = "") -> dict:
40
+ table = _find_table(graph, table_name)
41
+ if not table:
42
+ raise DataError(f"table not found for new column: {table_name}")
43
+ if _find_column(graph, f"{table_name}.{name}"):
44
+ raise DataError(f"column already exists: {table_name}.{name}")
45
+ column = {
46
+ "id": _column_id(f"{table_name}.{name}"),
47
+ "kind": "column",
48
+ "name": name,
49
+ "qualified": f"{table_name}.{name}",
50
+ "table": table_name,
51
+ "database": table["database"],
52
+ "type": column_type,
53
+ "pk": False,
54
+ "unique": False,
55
+ "comment": comment,
56
+ "proposed": True,
57
+ }
58
+ graph["columns"].append(column)
59
+ table["columns"].append(column)
60
+ return column
61
+
62
+
63
+ def _collisions(graph: dict, column: dict, limit: int = 6) -> list[dict]:
64
+ new_tokens = _tokens(column["name"])
65
+ if not new_tokens:
66
+ return []
67
+ found = []
68
+ for other in graph["columns"]:
69
+ if other["qualified"] == column["qualified"]:
70
+ continue
71
+ tokens = _tokens(other["name"])
72
+ shared = new_tokens & tokens
73
+ if not shared:
74
+ continue
75
+ same_table = other["table"] == column["table"]
76
+ same_database = other["database"] == column["database"]
77
+ jaccard = len(shared) / len(new_tokens | tokens)
78
+ if not same_table and not same_database and jaccard < 0.5:
79
+ continue
80
+ found.append(
81
+ {
82
+ "qualified": other["qualified"],
83
+ "name": other["name"],
84
+ "shared": sorted(shared),
85
+ "jaccard": round(jaccard, 2),
86
+ "same_table": same_table,
87
+ "same_database": same_database,
88
+ "comment": other.get("comment", ""),
89
+ }
90
+ )
91
+ found.sort(key=lambda item: (not item["same_table"], not item["same_database"], -item["jaccard"]))
92
+ return found[:limit]
93
+
94
+
95
+ def _table_of(column_id: str) -> str:
96
+ return column_id.split(":", 1)[-1].rsplit(".", 1)[0]
97
+
98
+
99
+ def analyze(graph: dict, delta: dict) -> dict:
100
+ changes = delta.get("changes") or {}
101
+ changed: dict[str, dict] = {}
102
+ proposed_edges: list[dict] = []
103
+
104
+ for item in changes.get("add_columns") or []:
105
+ column = _add_column(
106
+ graph,
107
+ item["table"],
108
+ item["column"],
109
+ item.get("type", ""),
110
+ item.get("comment", ""),
111
+ )
112
+ changed[column["qualified"]] = {"action": "add", "severity": "info"}
113
+
114
+ for item in changes.get("remove_columns") or []:
115
+ qualified = item if isinstance(item, str) else item["column"]
116
+ if not _find_column(graph, qualified):
117
+ raise DataError(f"column not found: {qualified}")
118
+ changed[qualified] = {"action": "remove", "severity": "breaking"}
119
+
120
+ for item in changes.get("analyze_columns") or []:
121
+ qualified = item if isinstance(item, str) else item["column"]
122
+ if not _find_column(graph, qualified):
123
+ raise DataError(f"column not found: {qualified}")
124
+ changed[qualified] = {"action": "analyze", "severity": "breaking"}
125
+
126
+ for edge in changes.get("add_edges") or []:
127
+ src = edge["src"] if edge["src"].startswith("column:") else f"column:{edge['src']}"
128
+ dst = edge["dst"] if edge["dst"].startswith("column:") else f"column:{edge['dst']}"
129
+ if not _find_column(graph, src.split(":", 1)[-1]) or not _find_column(graph, dst.split(":", 1)[-1]):
130
+ raise DataError(f"edge endpoint not found: {src} -> {dst}")
131
+ entry = {
132
+ "src": src,
133
+ "dst": dst,
134
+ "kind": edge.get("kind", "reads"),
135
+ "confidence": float(edge.get("confidence", 0.8)),
136
+ "method": "proposed",
137
+ "evidence": {"file": "delta", "snippet": edge.get("reason", "")},
138
+ }
139
+ graph["edges"].append(entry)
140
+ proposed_edges.append(entry)
141
+
142
+ affected: set[str] = set()
143
+ statements: dict[str, dict] = {}
144
+ tables: set[str] = set()
145
+ for qualified, meta in changed.items():
146
+ tables.add(qualified.rsplit(".", 1)[0])
147
+ node_id = _column_id(qualified)
148
+ for edge in graph["edges"]:
149
+ if edge["kind"] not in {"fk", "join", "value_overlap"}:
150
+ continue
151
+ if edge["src"] != node_id and edge["dst"] != node_id:
152
+ continue
153
+ other = edge["dst"] if edge["src"] == node_id else edge["src"]
154
+ other_q = other.split(":", 1)[-1]
155
+ affected.add(other_q)
156
+ tables.add(other_q.rsplit(".", 1)[0])
157
+ for statement in graph["statements"]:
158
+ if qualified in statement["columns"]:
159
+ statements[statement["id"]] = statement
160
+ for column in statement["columns"]:
161
+ tables.add(column.rsplit(".", 1)[0])
162
+
163
+ collisions: dict[str, list[dict]] = {}
164
+ for qualified, meta in changed.items():
165
+ if meta["action"] != "add":
166
+ continue
167
+ column = _find_column(graph, qualified)
168
+ if column:
169
+ collisions[qualified] = _collisions(graph, column)
170
+
171
+ for column in affected:
172
+ tables.add(column.rsplit(".", 1)[0])
173
+ for items in collisions.values():
174
+ for item in items:
175
+ tables.add(item["qualified"].rsplit(".", 1)[0])
176
+
177
+ return {
178
+ "name": delta.get("name") or "proposed change",
179
+ "description": delta.get("description", ""),
180
+ "delta": delta,
181
+ "changed": changed,
182
+ "affected": sorted(affected),
183
+ "collisions": collisions,
184
+ "statements": list(statements.values()),
185
+ "tables": sorted(tables),
186
+ "proposed_edges": proposed_edges,
187
+ "graph": graph,
188
+ }
189
+
190
+
191
+ def analyze_file(graph: dict, plan_path: Path) -> dict:
192
+ if not plan_path.exists():
193
+ raise DataError(f"plan not found: {plan_path}")
194
+ return analyze(copy.deepcopy(graph), load_yaml(plan_path))
@@ -0,0 +1,44 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ from pathlib import Path
5
+
6
+ import yaml
7
+
8
+
9
+ class DataError(Exception):
10
+ """Invalid input data (schema, relations, entities, delta)."""
11
+
12
+
13
+ def load_json(path: Path) -> dict:
14
+ try:
15
+ return json.loads(path.read_text(encoding="utf-8"))
16
+ except FileNotFoundError as exc:
17
+ raise DataError(f"file not found: {path}") from exc
18
+ except json.JSONDecodeError as exc:
19
+ raise DataError(f"invalid json: {path}: {exc}") from exc
20
+
21
+
22
+ def load_yaml_text(text: str, source: str = "<inline>") -> dict:
23
+ """Parse YAML handed over by a client instead of read from a file."""
24
+ try:
25
+ return yaml.safe_load(text) or {}
26
+ except yaml.YAMLError as exc:
27
+ raise DataError(f"invalid yaml: {source}: {exc}") from exc
28
+
29
+
30
+ def load_yaml(path: Path) -> dict:
31
+ try:
32
+ return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
33
+ except FileNotFoundError as exc:
34
+ raise DataError(f"file not found: {path}") from exc
35
+ except yaml.YAMLError as exc:
36
+ raise DataError(f"invalid yaml: {path}: {exc}") from exc
37
+
38
+
39
+ def write_json(path: Path, payload: dict) -> None:
40
+ path.parent.mkdir(parents=True, exist_ok=True)
41
+ path.write_text(
42
+ json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
43
+ encoding="utf-8",
44
+ )
@@ -0,0 +1,241 @@
1
+ """MCP server: expose schema-impact-map to AI coding clients.
2
+
3
+ The server speaks the Model Context Protocol over stdio, so clients such as
4
+ Claude Code, Codex, ZCode and WorkBuddy can call the tool provider. The MCP SDK
5
+ is optional, install it with::
6
+
7
+ pip install "schema-impact-map[mcp]"
8
+
9
+ Every tool is read-only with respect to the ledger and never touches a database:
10
+ it reads a data directory, parses SQL text, and writes at most one static HTML
11
+ file that the caller asked for.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import copy
17
+ import sys
18
+ from pathlib import Path
19
+
20
+ from . import __version__
21
+ from .build import CONFIG_FILE, build_from_dir
22
+ from .impact import analyze
23
+ from .io import DataError, load_yaml, load_yaml_text
24
+ from .render import write_html
25
+
26
+ SERVER_NAME = "schema-impact-map"
27
+
28
+ INSTRUCTIONS = """\
29
+ Schema Impact Map answers one question: if this column changes, what breaks?
30
+
31
+ Workflow:
32
+ 1. `check` the ledger (dangling relations, unknown entity members, unexplained *_id columns).
33
+ 2. `impact` a plan to get the changed columns, affected columns, naming collisions and
34
+ affected SQL statements.
35
+ 3. `render` only when the user wants a page they can open or share.
36
+
37
+ `data_dir` points at a ledger folder: schema-impact-map.yaml + schema.json +
38
+ entities.yaml + rules.yaml + sql/ (see examples/shop in the repository).
39
+ All tools read local files only; no database connection, no credentials, no uploads."""
40
+
41
+ PLAN_HINT = (
42
+ "Pass either a path to a plan YAML file or the YAML itself, for example:\n"
43
+ "name: Review customer key\n"
44
+ "changes:\n"
45
+ " analyze_columns:\n"
46
+ " - crm.customers.id"
47
+ )
48
+
49
+
50
+ def _stats(graph: dict) -> dict:
51
+ return dict(graph.get("stats") or {})
52
+
53
+
54
+ def _data_dir(value: str) -> Path:
55
+ path = Path(value).expanduser()
56
+ if not path.exists():
57
+ raise DataError(f"data directory not found: {value}")
58
+ if not path.is_dir():
59
+ raise DataError(f"not a directory: {value}")
60
+ if not (path / CONFIG_FILE).exists():
61
+ raise DataError(
62
+ f"{value} has no {CONFIG_FILE}; point data_dir at a ledger folder "
63
+ "(the repository ships one in examples/shop)"
64
+ )
65
+ return path
66
+
67
+
68
+ def _plan(plan: str) -> dict:
69
+ text = (plan or "").strip()
70
+ if not text:
71
+ raise DataError(f"no plan given; {PLAN_HINT}")
72
+ path = Path(text).expanduser()
73
+ if "\n" not in text and len(text) < 260 and path.is_file():
74
+ return load_yaml(path)
75
+ if "\n" in text or ":" in text:
76
+ return load_yaml_text(text)
77
+ raise DataError(f"plan not found: {text}; {PLAN_HINT}")
78
+
79
+
80
+ def _summary(changed: int, affected: int, collisions: int, statements: int) -> str:
81
+ return (
82
+ f"{changed} changed / {affected} affected / "
83
+ f"{collisions} collisions / {statements} SQL"
84
+ )
85
+
86
+
87
+ def build_graph(data_dir: str = ".") -> dict:
88
+ """Build the schema graph for a ledger folder and report its size.
89
+
90
+ Use this first to confirm that ``data_dir`` is a real ledger. Returns the
91
+ database/table/column/edge counts plus any ``check`` errors.
92
+ """
93
+ try:
94
+ graph = build_from_dir(_data_dir(data_dir))
95
+ except DataError as exc:
96
+ return {"ok": False, "error": str(exc)}
97
+ return {
98
+ "ok": bool(graph["check"]["ok"]),
99
+ "stats": _stats(graph),
100
+ "errors": list(graph["check"]["errors"]),
101
+ }
102
+
103
+
104
+ def check(data_dir: str = ".") -> dict:
105
+ """Validate the ledger before trusting an impact result.
106
+
107
+ Reports every declared relation that points at a missing column, every entity
108
+ member that does not exist, and every ``*_id`` column that no relation or
109
+ entity explains.
110
+ """
111
+ try:
112
+ graph = build_from_dir(_data_dir(data_dir))
113
+ except DataError as exc:
114
+ return {"ok": False, "error": str(exc)}
115
+ errors = list(graph["check"]["errors"])
116
+ return {
117
+ "ok": not errors,
118
+ "errors": errors,
119
+ "stats": _stats(graph),
120
+ }
121
+
122
+
123
+ def impact(data_dir: str = ".", plan: str = "") -> dict:
124
+ """Analyse what a proposed schema change touches. Nothing is written to disk.
125
+
126
+ ``plan`` is a plan YAML file path or the YAML text itself (see the module
127
+ instructions). Returns changed columns, affected columns, naming collisions,
128
+ affected SQL statements and tables.
129
+ """
130
+ try:
131
+ graph = build_from_dir(_data_dir(data_dir))
132
+ payload = analyze(copy.deepcopy(graph), _plan(plan))
133
+ except DataError as exc:
134
+ return {"ok": False, "error": str(exc)}
135
+
136
+ collisions = {
137
+ qualified: [
138
+ {
139
+ "column": item["qualified"],
140
+ "shared_tokens": item["shared"],
141
+ "same_table": item["same_table"],
142
+ "same_database": item["same_database"],
143
+ }
144
+ for item in items
145
+ ]
146
+ for qualified, items in payload["collisions"].items()
147
+ }
148
+ statements = [
149
+ {
150
+ "file": Path(statement["file"]).name,
151
+ "name": statement["name"],
152
+ "columns": statement["columns"],
153
+ }
154
+ for statement in payload["statements"]
155
+ ]
156
+ changed = [
157
+ {"column": qualified, **meta} for qualified, meta in payload["changed"].items()
158
+ ]
159
+ affected = list(payload["affected"])
160
+ collision_count = sum(len(items) for items in collisions.values())
161
+ return {
162
+ "ok": True,
163
+ "name": payload["name"],
164
+ "summary": _summary(len(changed), len(affected), collision_count, len(statements)),
165
+ "changed": changed,
166
+ "affected": affected,
167
+ "collisions": collisions,
168
+ "statements": statements,
169
+ "tables": payload["tables"],
170
+ }
171
+
172
+
173
+ def render(
174
+ data_dir: str = ".",
175
+ plan: str | None = None,
176
+ out: str = "site/schema-impact-map.html",
177
+ focus: str | None = None,
178
+ ) -> dict:
179
+ """Write one self-contained HTML page: the map, or the impact map when a plan is given.
180
+
181
+ ``out`` is written relative to the current working directory. Returns the path
182
+ and whether impact highlighting was applied, so the caller can open or link it.
183
+ """
184
+ try:
185
+ graph = build_from_dir(_data_dir(data_dir))
186
+ target = Path(out).expanduser()
187
+ if plan:
188
+ payload = analyze(copy.deepcopy(graph), _plan(plan))
189
+ write_html(target, payload["graph"], payload, focus=focus or next(iter(payload["changed"]), None))
190
+ return {
191
+ "ok": True,
192
+ "out": str(target),
193
+ "mode": "impact",
194
+ "name": payload["name"],
195
+ "summary": _summary(
196
+ len(payload["changed"]),
197
+ len(payload["affected"]),
198
+ sum(len(items) for items in payload["collisions"].values()),
199
+ len(payload["statements"]),
200
+ ),
201
+ }
202
+ write_html(target, graph, focus=focus)
203
+ return {
204
+ "ok": True,
205
+ "out": str(target),
206
+ "mode": "map",
207
+ "stats": _stats(graph),
208
+ }
209
+ except DataError as exc:
210
+ return {"ok": False, "error": str(exc)}
211
+
212
+
213
+ def create_server():
214
+ """Build the MCP server; imported lazily so the CLI works without the extra."""
215
+ from mcp.server.mcpserver import MCPServer
216
+
217
+ server = MCPServer(
218
+ name=SERVER_NAME,
219
+ version=__version__,
220
+ instructions=INSTRUCTIONS,
221
+ )
222
+ for tool in (build_graph, check, impact, render):
223
+ server.add_tool(tool)
224
+ return server
225
+
226
+
227
+ def main() -> int:
228
+ try:
229
+ server = create_server()
230
+ except ModuleNotFoundError:
231
+ print(
232
+ 'The MCP server needs the optional dependency: '
233
+ 'pip install "schema-impact-map[mcp]"',
234
+ file=sys.stderr,
235
+ )
236
+ return 1
237
+ try:
238
+ server.run("stdio")
239
+ except KeyboardInterrupt: # client closed the pipe
240
+ return 0
241
+ return 0