bizmap 0.3.10__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.
bizmap/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """BizMap: deterministic business-rule and data-lineage mapper."""
2
+
3
+ __version__ = "0.3.10"
bizmap/cli.py ADDED
@@ -0,0 +1,402 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import sys
5
+ from pathlib import Path
6
+
7
+ import click
8
+
9
+ from bizmap import __version__
10
+ from bizmap.graph import Graph
11
+ from bizmap.impact import compute_impact, render_markdown
12
+ from bizmap.mermaid import DEFAULT_LIMIT, render_mermaid
13
+ from bizmap.registry import graph_from_json, merge_graphs
14
+ from bizmap.report import build_report, format_report
15
+ from bizmap.scan import relink_merged_graph, scan_path, scan_paths
16
+ from bizmap.why import format_why
17
+
18
+
19
+ @click.group()
20
+ @click.version_option(__version__, prog_name="bizmap")
21
+ def main() -> None:
22
+ """BizMap — deterministic business-rule and data-lineage mapper.
23
+
24
+ No AI, no tokens, no accounts. SQL, routes, jobs, and comments only.
25
+ """
26
+
27
+
28
+ @main.command("scan")
29
+ @click.argument("path", nargs=-1, type=click.Path(exists=True, file_okay=False, path_type=Path))
30
+ @click.option(
31
+ "--out",
32
+ "out_path",
33
+ type=click.Path(dir_okay=False, path_type=Path),
34
+ default=Path("bizmap.graph.json"),
35
+ show_default=True,
36
+ help="Write the lineage graph JSON here.",
37
+ )
38
+ @click.option(
39
+ "--mermaid",
40
+ "mermaid_flag",
41
+ is_flag=True,
42
+ help="Also write a Mermaid flowchart next to the JSON (entrypoint→table rollup; joint scans include cross-service calls_http).",
43
+ )
44
+ @click.option(
45
+ "--mermaid-focus",
46
+ "mermaid_focus",
47
+ default=None,
48
+ help="Restrict the Mermaid diagram to one table and its neighborhood.",
49
+ )
50
+ @click.option(
51
+ "--mermaid-limit",
52
+ "mermaid_limit",
53
+ type=int,
54
+ default=DEFAULT_LIMIT,
55
+ show_default=True,
56
+ help="Max nodes in the Mermaid diagram.",
57
+ )
58
+ @click.option(
59
+ "--expand-star",
60
+ "expand_star",
61
+ is_flag=True,
62
+ help="Expand SELECT * to every schema column (off by default; table-level otherwise).",
63
+ )
64
+ @click.option(
65
+ "--rules",
66
+ "rules_dirs",
67
+ type=click.Path(exists=True, path_type=Path),
68
+ multiple=True,
69
+ help="Extra YAML detector-rule files or directories (repeatable).",
70
+ )
71
+ @click.option(
72
+ "--config",
73
+ "config_path",
74
+ type=click.Path(exists=True, dir_okay=False, path_type=Path),
75
+ default=None,
76
+ help="Path to bizmap.yaml (default: scan root, then git toplevel).",
77
+ )
78
+ @click.option(
79
+ "--exclude",
80
+ "exclude_globs",
81
+ multiple=True,
82
+ help="Exclude glob (repeatable); merged with bizmap.yaml exclude.",
83
+ )
84
+ @click.option(
85
+ "--profile",
86
+ "profile_flag",
87
+ is_flag=True,
88
+ help="Print phase timings (parse, resolve, sql, propagate) to stderr.",
89
+ )
90
+ def scan_cmd(
91
+ path: Path,
92
+ out_path: Path,
93
+ mermaid_flag: bool,
94
+ mermaid_focus: str | None,
95
+ mermaid_limit: int,
96
+ expand_star: bool,
97
+ rules_dirs: tuple[Path, ...],
98
+ config_path: Path | None,
99
+ exclude_globs: tuple[str, ...],
100
+ profile_flag: bool,
101
+ ) -> None:
102
+ """Scan one or more codebases and write bizmap.graph.json."""
103
+ if not path:
104
+ raise click.UsageError("missing scan path")
105
+ roots = [Path(p) for p in path]
106
+ if len(roots) == 1:
107
+ graph = scan_path(
108
+ roots[0],
109
+ extra_rules=list(rules_dirs) or None,
110
+ expand_star=True if expand_star else None,
111
+ config=config_path,
112
+ exclude=list(exclude_globs) or None,
113
+ profile=profile_flag,
114
+ )
115
+ else:
116
+ graph = scan_paths(
117
+ roots,
118
+ extra_rules=list(rules_dirs) or None,
119
+ expand_star=True if expand_star else None,
120
+ config=config_path,
121
+ exclude=list(exclude_globs) or None,
122
+ profile=profile_flag,
123
+ )
124
+ payload = graph.to_dict()
125
+ out_path.parent.mkdir(parents=True, exist_ok=True)
126
+ out_path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
127
+ click.echo(
128
+ f"wrote {out_path} ({len(payload['nodes'])} nodes, {len(payload['edges'])} edges)"
129
+ )
130
+ for warning in graph.attrs.get("warnings") or []:
131
+ click.echo(warning)
132
+ unresolved = graph.attrs.get("unresolved_http") or []
133
+ if unresolved:
134
+ keys: list[str] = []
135
+ seen: set[str] = set()
136
+ reason_counts: dict[str, int] = {}
137
+ for item in unresolved:
138
+ reason = str(item.get("reason") or "target_not_scanned")
139
+ reason_counts[reason] = reason_counts.get(reason, 0) + 1
140
+ for key in item.get("keys") or []:
141
+ if key not in seen:
142
+ seen.add(key)
143
+ keys.append(str(key))
144
+ order = ("target_not_scanned", "base_unknown", "path_dynamic", "client_unknown")
145
+ reason_bits = [f"{name}={reason_counts[name]}" for name in order if name in reason_counts]
146
+ for name, count in sorted(reason_counts.items()):
147
+ if name not in order:
148
+ reason_bits.append(f"{name}={count}")
149
+ if reason_bits:
150
+ click.echo("HTTP unmatched by reason: " + ", ".join(reason_bits))
151
+ suffix = f" ({', '.join(keys)})" if keys else ""
152
+ click.echo(f"{len(unresolved)} unresolved HTTP calls{suffix}")
153
+ if mermaid_flag or mermaid_focus:
154
+ mmd_path = out_path.with_suffix(".mmd")
155
+ mmd_path.write_text(
156
+ render_mermaid(graph, focus=mermaid_focus, limit=mermaid_limit),
157
+ encoding="utf-8",
158
+ )
159
+ click.echo(f"wrote {mmd_path}")
160
+
161
+
162
+ @main.command("why")
163
+ @click.argument("column")
164
+ @click.option(
165
+ "--graph",
166
+ "graph_path",
167
+ type=click.Path(exists=True, dir_okay=False, path_type=Path),
168
+ default=Path("bizmap.graph.json"),
169
+ show_default=True,
170
+ help="Graph JSON produced by `bizmap scan`.",
171
+ )
172
+ def why_cmd(column: str, graph_path: Path) -> None:
173
+ """Print who writes/reads TABLE.COLUMN and what triggers those functions."""
174
+ try:
175
+ data = json.loads(graph_path.read_text(encoding="utf-8"))
176
+ except json.JSONDecodeError as exc:
177
+ raise click.ClickException(f"invalid graph JSON: {exc}") from exc
178
+ graph = Graph.from_dict(data)
179
+ try:
180
+ text = format_why(graph, column)
181
+ except ValueError as exc:
182
+ raise click.ClickException(str(exc)) from exc
183
+ click.echo(text, nl=False)
184
+ if text.startswith("unknown column"):
185
+ sys.exit(1)
186
+
187
+
188
+ @main.command("report")
189
+ @click.argument("path", nargs=-1, type=click.Path(exists=True, file_okay=False, path_type=Path))
190
+ @click.option(
191
+ "--graph",
192
+ "graph_path",
193
+ type=click.Path(dir_okay=False, path_type=Path),
194
+ default=Path("bizmap.graph.json"),
195
+ show_default=True,
196
+ help="Graph JSON to report on (ignored when PATH roots are given).",
197
+ )
198
+ @click.option("--redact", is_flag=True, help="Replace every name/URL/key with a salted hash.")
199
+ @click.option(
200
+ "--salt",
201
+ default=None,
202
+ envvar="BIZMAP_REDACT_SALT",
203
+ help="Salt for --redact hashes (env BIZMAP_REDACT_SALT). Same salt = comparable runs.",
204
+ )
205
+ @click.option(
206
+ "--salt-file",
207
+ "salt_file",
208
+ type=click.Path(dir_okay=False, path_type=Path),
209
+ default=None,
210
+ help="Read the --redact salt from this file, creating a random one on first use. "
211
+ "Keeps redacted runs comparable without putting the salt on the command line.",
212
+ )
213
+ @click.option("--json", "as_json", is_flag=True, help="Print the report as JSON.")
214
+ @click.option("--limit", type=int, default=20, show_default=True, help="Max rows per list.")
215
+ @click.option(
216
+ "--config",
217
+ "config_path",
218
+ type=click.Path(exists=True, dir_okay=False, path_type=Path),
219
+ default=None,
220
+ help="bizmap.yaml for PATH scans.",
221
+ )
222
+ def report_cmd(
223
+ path: tuple[Path, ...],
224
+ graph_path: Path,
225
+ redact: bool,
226
+ salt: str | None,
227
+ salt_file: Path | None,
228
+ as_json: bool,
229
+ limit: int,
230
+ config_path: Path | None,
231
+ ) -> None:
232
+ """Coverage report: entrypoints reaching data, HTTP links, unresolved reasons.
233
+
234
+ Pass PATH roots to scan in memory (nothing written), or read --graph.
235
+ With --redact the output contains counts and hashes only, so it can be
236
+ shared from a private codebase.
237
+ """
238
+ if path:
239
+ graph = (
240
+ scan_paths(list(path), config=config_path)
241
+ if len(path) > 1
242
+ else scan_path(path[0], config=config_path)
243
+ )
244
+ data = graph.to_dict()
245
+ else:
246
+ if not graph_path.exists():
247
+ raise click.UsageError(f"{graph_path} not found; run `bizmap scan` or pass PATH roots")
248
+ try:
249
+ data = json.loads(graph_path.read_text(encoding="utf-8"))
250
+ except json.JSONDecodeError as exc:
251
+ raise click.ClickException(f"invalid graph JSON: {exc}") from exc
252
+ if redact and not salt and salt_file is not None:
253
+ import secrets
254
+
255
+ if salt_file.exists():
256
+ salt = salt_file.read_text(encoding="utf-8").strip()
257
+ if not salt:
258
+ import os
259
+
260
+ salt = secrets.token_hex(16)
261
+ salt_file.parent.mkdir(parents=True, exist_ok=True)
262
+ # private from the first byte: 0600, never world/group readable
263
+ fd = os.open(salt_file, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
264
+ with os.fdopen(fd, "w", encoding="utf-8") as fh:
265
+ fh.write(salt + "\n")
266
+ os.chmod(salt_file, 0o600)
267
+ click.echo(
268
+ f"note: wrote a new redaction salt to {salt_file}; keep it private and reuse it",
269
+ err=True,
270
+ )
271
+ if redact and not salt:
272
+ import secrets
273
+
274
+ salt = secrets.token_hex(16)
275
+ click.echo(
276
+ "note: random salt for this run, so hashes differ between runs; "
277
+ "use --salt-file PATH (or --salt / BIZMAP_REDACT_SALT) to compare runs",
278
+ err=True,
279
+ )
280
+ rep = build_report(data, redact=redact, salt=salt or "")
281
+ if as_json:
282
+ click.echo(json.dumps(rep, indent=2, sort_keys=True))
283
+ else:
284
+ click.echo(format_report(rep, limit=limit), nl=False)
285
+
286
+
287
+ @main.command("impact")
288
+ @click.option(
289
+ "--graph",
290
+ "graph_path",
291
+ type=click.Path(exists=True, dir_okay=False, path_type=Path),
292
+ default=Path("bizmap.graph.json"),
293
+ show_default=True,
294
+ help="Graph JSON of the changed code (scan of the PR head).",
295
+ )
296
+ @click.option(
297
+ "--diff",
298
+ "diff_path",
299
+ type=click.Path(dir_okay=False, allow_dash=True, path_type=Path),
300
+ default="-",
301
+ show_default=True,
302
+ help="Unified diff (`git diff base...head`); `-` reads stdin.",
303
+ )
304
+ @click.option(
305
+ "--prefix",
306
+ default=".",
307
+ show_default=True,
308
+ help="Scanned directory relative to the git root (the path given to `bizmap scan`).",
309
+ )
310
+ @click.option(
311
+ "--repo-root",
312
+ type=click.Path(file_okay=False, path_type=Path),
313
+ default=Path("."),
314
+ show_default=True,
315
+ help="Checkout the diff paths are relative to (read for changed .sql files).",
316
+ )
317
+ @click.option("--json", "as_json", is_flag=True, help="Print the impact as JSON.")
318
+ @click.option("--limit", type=int, default=40, show_default=True, help="Max nodes in the diagram.")
319
+ @click.option("--max-rows", type=int, default=50, show_default=True, help="Max table rows (functions with impact).")
320
+ @click.option(
321
+ "--max-chars",
322
+ type=int,
323
+ default=60000,
324
+ show_default=True,
325
+ help="Hard cap on the Markdown size (GitHub comments stop at 65,536).",
326
+ )
327
+ @click.option("--details-url", default=None, help="Link shown when rows are cut (e.g. the workflow run).")
328
+ def impact_cmd(
329
+ graph_path: Path,
330
+ diff_path: Path,
331
+ prefix: str,
332
+ repo_root: Path,
333
+ as_json: bool,
334
+ limit: int,
335
+ max_rows: int,
336
+ max_chars: int,
337
+ details_url: str | None,
338
+ ) -> None:
339
+ """Map a diff onto the graph: changed functions → entrypoints and data.
340
+
341
+ Prints Markdown with a Mermaid diagram (for a PR comment), or JSON.
342
+ """
343
+ try:
344
+ graph = graph_from_json(json.loads(graph_path.read_text(encoding="utf-8")))
345
+ except json.JSONDecodeError as exc:
346
+ raise click.ClickException(f"invalid graph JSON: {exc}") from exc
347
+ diff_text = sys.stdin.read() if str(diff_path) == "-" else diff_path.read_text(encoding="utf-8")
348
+ result = compute_impact(graph, diff_text, prefix=prefix, repo_root=repo_root)
349
+ if result.hint:
350
+ click.echo(f"warning: {result.hint}", err=True)
351
+ for warning in result.warnings:
352
+ click.echo(f"warning: {warning}", err=True)
353
+ if as_json:
354
+ click.echo(json.dumps(result.to_dict(), indent=2, sort_keys=True))
355
+ else:
356
+ click.echo(
357
+ render_markdown(
358
+ graph, result, limit=limit, max_rows=max_rows, max_chars=max_chars, details_url=details_url
359
+ ),
360
+ nl=False,
361
+ )
362
+
363
+
364
+ @main.group("registry")
365
+ def registry_grp() -> None:
366
+ """Merge and query cross-repo lineage graphs."""
367
+
368
+
369
+ @registry_grp.command("merge")
370
+ @click.argument("graphs", nargs=-1, type=click.Path(exists=True, dir_okay=False, path_type=Path))
371
+ @click.option(
372
+ "--out",
373
+ "out_path",
374
+ type=click.Path(dir_okay=False, path_type=Path),
375
+ default=Path("bizmap.graph.json"),
376
+ show_default=True,
377
+ help="Write the merged graph JSON here.",
378
+ )
379
+ def registry_merge_cmd(graphs: tuple[Path, ...], out_path: Path) -> None:
380
+ """Merge graph JSON files into one registry graph with repo-qualified ids."""
381
+ if not graphs:
382
+ raise click.UsageError("missing graph JSON paths")
383
+ loaded = []
384
+ for path in graphs:
385
+ try:
386
+ data = json.loads(path.read_text(encoding="utf-8"))
387
+ except json.JSONDecodeError as exc:
388
+ raise click.ClickException(f"{path}: invalid graph JSON: {exc}") from exc
389
+ loaded.append(graph_from_json(data))
390
+ merged = merge_graphs(loaded)
391
+ services: dict = dict(merged.attrs.get("services") or {})
392
+ for graph in loaded:
393
+ for k, v in (graph.attrs.get("services") or {}).items():
394
+ services.setdefault(k, v)
395
+ merged.attrs["services"] = services
396
+ relink_merged_graph(merged, services)
397
+ payload = merged.to_dict()
398
+ out_path.parent.mkdir(parents=True, exist_ok=True)
399
+ out_path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
400
+ click.echo(
401
+ f"wrote {out_path} ({len(payload['nodes'])} nodes, {len(payload['edges'])} edges)"
402
+ )
@@ -0,0 +1 @@
1
+ """Language analyzers driven by YAML detector rules."""