mapwright-agent 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.
mapwright/connect.py ADDED
@@ -0,0 +1,337 @@
1
+ """Connect Mapwright to coding agents: write (or remove) the MCP server entry, and hooks where the
2
+ agent supports them, in each tool's own config file.
3
+
4
+ Existing config is merged, never replaced: a file that is not valid JSON is left alone and the
5
+ call fails with a message. A copy of every file is saved under ~/.mapwright/backups before it is
6
+ changed.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import json
12
+ import os
13
+ import re
14
+ import shlex
15
+ import shutil
16
+ import sys
17
+ import time
18
+ from pathlib import Path
19
+
20
+ from . import config
21
+
22
+ NAME = "mapwright"
23
+
24
+
25
+ def server_command() -> tuple[str, list[str]]:
26
+ exe = shutil.which("mapwright")
27
+ if exe:
28
+ return "mapwright", ["mcp"]
29
+ return sys.executable, ["-m", "mapwright", "mcp"]
30
+
31
+
32
+ def hook_command(agent: str) -> str:
33
+ exe = shutil.which("mapwright")
34
+ return f"mapwright hook {agent}" if exe else f'"{sys.executable}" -m mapwright hook {agent}'
35
+
36
+
37
+ def hook_command_with_home(agent: str, home: str | None = None) -> str:
38
+ cmd = hook_command(agent)
39
+ if not home:
40
+ return cmd
41
+ if sys.platform.startswith("win"): # best effort: cmd.exe form
42
+ return f'cmd /d /c "set MAPWRIGHT_HOME={home}&& {cmd}"'
43
+ return f"MAPWRIGHT_HOME={shlex.quote(home)} {cmd}"
44
+
45
+
46
+ def _vscode_user_dir() -> Path:
47
+ if sys.platform == "darwin":
48
+ return Path.home() / "Library/Application Support/Code/User"
49
+ if sys.platform.startswith("win"):
50
+ return Path(os.environ.get("APPDATA", Path.home())) / "Code/User"
51
+ return Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / "Code/User"
52
+
53
+
54
+ def _cc_dir() -> Path:
55
+ return Path(os.environ.get("MAPWRIGHT_CLAUDE_DIR", Path.home() / ".claude"))
56
+
57
+
58
+ # target id: title, website hint, {scope: (path factory, format)}
59
+ TARGETS: dict[str, dict] = {
60
+ "claude-code": {"title": "Claude Code", "how": "MCP server + hooks (prompts, edits, turn ends)",
61
+ "scopes": {"project": lambda r: Path(r) / ".mcp.json", "user": lambda r: Path(os.environ.get("MAPWRIGHT_CLAUDE_JSON", Path.home() / ".claude.json"))},
62
+ "format": "mcpServers"},
63
+ "cursor": {"title": "Cursor", "how": "MCP server", "format": "mcpServers",
64
+ "scopes": {"project": lambda r: Path(r) / ".cursor/mcp.json", "user": lambda r: Path.home() / ".cursor/mcp.json"}},
65
+ "vscode": {"title": "VS Code (Copilot agent mode)", "how": "MCP server (+ the Mapwright extension for the map inside the editor)", "format": "servers",
66
+ "scopes": {"project": lambda r: Path(r) / ".vscode/mcp.json", "user": lambda r: _vscode_user_dir() / "mcp.json"}},
67
+ "windsurf": {"title": "Windsurf", "how": "MCP server", "format": "mcpServers",
68
+ "scopes": {"user": lambda r: Path.home() / ".codeium/windsurf/mcp_config.json"}},
69
+ "opencode": {"title": "opencode", "how": "MCP server", "format": "opencode",
70
+ "scopes": {"project": lambda r: Path(r) / "opencode.json", "user": lambda r: Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / "opencode/opencode.json"}},
71
+ "codex": {"title": "Codex CLI", "how": "MCP server", "format": "toml",
72
+ "scopes": {"user": lambda r: Path(os.environ.get("CODEX_HOME", Path.home() / ".codex")) / "config.toml"}},
73
+ "gemini": {"title": "Gemini CLI", "how": "MCP server", "format": "mcpServers",
74
+ "scopes": {"project": lambda r: Path(r) / ".gemini/settings.json", "user": lambda r: Path.home() / ".gemini/settings.json"}},
75
+ "claude-desktop": {"title": "Claude Desktop", "how": "MCP server (map and steps; no file edits of its own)", "format": "mcpServers",
76
+ "scopes": {"user": lambda r: (Path.home() / "Library/Application Support/Claude/claude_desktop_config.json") if sys.platform == "darwin"
77
+ else Path(os.environ.get("APPDATA", Path.home() / ".config")) / "Claude/claude_desktop_config.json"}},
78
+ }
79
+ MANUAL = {
80
+ "cline": ("Cline / Roo Code", "Open the extension's MCP settings (\"Configure MCP Servers\") and add the JSON below under mcpServers."),
81
+ "zed": ("Zed", "Add to settings.json under \"context_servers\": {\"mapwright\": {\"command\": {\"path\": CMD, \"args\": ARGS}}}."),
82
+ "jetbrains": ("JetBrains AI Assistant / Junie", "Settings → Tools → AI Assistant → Model Context Protocol → Add, then paste the JSON below."),
83
+ "any": ("Any other agent", "Any MCP client: add the JSON below. No MCP at all: run `mapwright watch` in the project; changes are tracked from the files."),
84
+ }
85
+
86
+
87
+ def snippet(target: str = "any", root: str | None = None, home: str | None = None) -> str:
88
+ cmd, args = server_command()
89
+ env = {"MAPWRIGHT_HOME": str(home)} if home else None
90
+ if target == "vscode":
91
+ return json.dumps({"servers": {NAME: _entry("vscode", cmd, args, env)}}, indent=2)
92
+ if target == "opencode":
93
+ return json.dumps({"mcp": {NAME: _entry("opencode", cmd, args, env)}}, indent=2)
94
+ if target == "codex":
95
+ text = f'[mcp_servers.{NAME}]\ncommand = "{cmd}"\nargs = {json.dumps(args)}\n'
96
+ if env:
97
+ text += f"\n[mcp_servers.{NAME}.env]\nMAPWRIGHT_HOME = {json.dumps(env['MAPWRIGHT_HOME'])}\n"
98
+ return text
99
+ if target == "zed":
100
+ c = {"path": cmd, "args": args}
101
+ if env:
102
+ c["env"] = env
103
+ return json.dumps({"context_servers": {NAME: {"command": c}}}, indent=2)
104
+ return json.dumps({"mcpServers": {NAME: _entry("mcpServers", cmd, args, env)}}, indent=2)
105
+
106
+
107
+ def _entry(fmt: str, cmd: str, args: list[str], env: dict | None) -> dict:
108
+ if fmt == "vscode":
109
+ e = {"type": "stdio", "command": cmd, "args": args}
110
+ if env:
111
+ e["env"] = env
112
+ elif fmt == "opencode":
113
+ e = {"type": "local", "command": [cmd, *args], "enabled": True}
114
+ if env:
115
+ e["environment"] = env
116
+ else:
117
+ e = {"command": cmd, "args": args}
118
+ if env:
119
+ e["env"] = env
120
+ return e
121
+
122
+
123
+ def _backup(path: Path) -> None:
124
+ if path.exists():
125
+ dest = config.home() / "backups" / f"{path.name}.{time.strftime('%Y%m%d-%H%M%S')}.{abs(hash(str(path))) % 10000}"
126
+ dest.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
127
+ shutil.copy2(path, dest)
128
+
129
+
130
+ def _load(path: Path) -> dict:
131
+ if not path.exists() or not path.read_text().strip():
132
+ return {}
133
+ try:
134
+ data = json.loads(path.read_text())
135
+ except ValueError as e:
136
+ raise ValueError(f"{path} is not plain JSON ({e.msg}); add the entry by hand: `mapwright connect --print`") from e
137
+ if not isinstance(data, dict):
138
+ raise ValueError(f"{path} does not hold a JSON object")
139
+ return data
140
+
141
+
142
+ def _save(path: Path, data: dict) -> None:
143
+ path.parent.mkdir(parents=True, exist_ok=True)
144
+ _backup(path)
145
+ tmp = path.with_name(path.name + ".mapwright.tmp")
146
+ tmp.write_text(json.dumps(data, indent=2) + "\n")
147
+ os.replace(tmp, path)
148
+
149
+
150
+ _TOML_BLOCK = re.compile(r"(?ms)^\[mcp_servers\.mapwright\]\n.*?(?=^\[(?!mcp_servers\.mapwright\.)|\Z)")
151
+
152
+
153
+ def _hooks_path(scope: str, root: str) -> Path:
154
+ return (Path(root) / ".claude/settings.local.json") if scope == "project" else _cc_dir() / "settings.json"
155
+
156
+
157
+ _OWN_DIRS = {".claude", ".cursor", ".vscode", ".gemini"}
158
+
159
+
160
+ def _remove_file(path: Path) -> None:
161
+ """Back up, then delete a config file that uninstall left with nothing in it; drop its directory if that is empty too."""
162
+ _backup(path)
163
+ path.unlink()
164
+ if path.parent.name in _OWN_DIRS and path.parent != Path.home():
165
+ try:
166
+ path.parent.rmdir()
167
+ except OSError:
168
+ pass
169
+
170
+
171
+ def _claude_hooks(path: Path, on: bool, home: str | None = None) -> None:
172
+ data = _load(path)
173
+ hooks = data.get("hooks") or {}
174
+ for ev in list(hooks):
175
+ hooks[ev] = [m for m in hooks[ev] if not any("mapwright" in (h.get("command") or "") for h in m.get("hooks", []))]
176
+ if not hooks[ev]:
177
+ del hooks[ev]
178
+ if on:
179
+ cmd = hook_command_with_home("claude-code", home)
180
+ entry = lambda matcher=None: {**({"matcher": matcher} if matcher else {}), "hooks": [{"type": "command", "command": cmd, "timeout": 10}]} # noqa: E731
181
+ hooks.setdefault("UserPromptSubmit", []).append(entry())
182
+ hooks.setdefault("PostToolUse", []).append(entry("Write|Edit|MultiEdit|NotebookEdit|Bash"))
183
+ hooks.setdefault("Stop", []).append(entry())
184
+ if hooks:
185
+ data["hooks"] = hooks
186
+ else:
187
+ data.pop("hooks", None)
188
+ if not on and not data:
189
+ _remove_file(path)
190
+ else:
191
+ _save(path, data)
192
+
193
+
194
+ def install(target: str, scope: str = "project", root: str | None = None, home: str | None = None) -> list[str]:
195
+ """Returns the files written. With home, the MCP server and the Claude Code hooks run with MAPWRIGHT_HOME=home."""
196
+ home = os.path.abspath(str(home)) if home else None
197
+ root = root or os.getcwd()
198
+ spec = TARGETS.get(target)
199
+ if not spec:
200
+ raise ValueError(f"unknown target {target}; one of: {', '.join(TARGETS)}")
201
+ if scope not in spec["scopes"]:
202
+ raise ValueError(f"{spec['title']} supports scope: {', '.join(spec['scopes'])}")
203
+ path = spec["scopes"][scope](root)
204
+ cmd, args = server_command()
205
+ env = {"MAPWRIGHT_HOME": home} if home else None
206
+ written = [str(path)]
207
+ if target == "claude-code" and scope == "user" and _claude_cli_add(cmd, args, home):
208
+ pass # `claude mcp add -s user` wrote it
209
+ elif spec["format"] == "toml":
210
+ text = path.read_text() if path.exists() else ""
211
+ block = snippet("codex", home=home)
212
+ text = _TOML_BLOCK.sub(block, text) if _TOML_BLOCK.search(text) else (text.rstrip() + "\n\n" if text.strip() else "") + block
213
+ path.parent.mkdir(parents=True, exist_ok=True)
214
+ _backup(path)
215
+ path.write_text(text)
216
+ else:
217
+ data = _load(path)
218
+ if spec["format"] == "servers":
219
+ data.setdefault("servers", {})[NAME] = _entry("vscode", cmd, args, env)
220
+ elif spec["format"] == "opencode":
221
+ data.setdefault("$schema", "https://opencode.ai/config.json")
222
+ data.setdefault("mcp", {})[NAME] = _entry("opencode", cmd, args, env)
223
+ else:
224
+ entry = _entry("mcpServers", cmd, args, env)
225
+ if target == "claude-code" and scope == "project":
226
+ entry = {"type": "stdio", **entry}
227
+ data.setdefault("mcpServers", {})[NAME] = entry
228
+ _save(path, data)
229
+ if target == "claude-code":
230
+ hp = _hooks_path(scope, root)
231
+ _claude_hooks(hp, True, home)
232
+ written.append(str(hp))
233
+ return written
234
+
235
+
236
+ def _claude_cli_add(cmd: str, args: list[str], home: str | None = None) -> bool:
237
+ """User scope for Claude Code: let its own CLI edit ~/.claude.json when it is installed."""
238
+ import subprocess
239
+ exe = shutil.which("claude")
240
+ if not exe or os.environ.get("MAPWRIGHT_CLAUDE_JSON"):
241
+ return False
242
+ subprocess.run([exe, "mcp", "remove", "-s", "user", NAME], capture_output=True, timeout=30)
243
+ r = subprocess.run([exe, "mcp", "add", "-s", "user", *(["-e", f"MAPWRIGHT_HOME={home}"] if home else []), NAME, "--", cmd, *args], capture_output=True, timeout=30)
244
+ return r.returncode == 0
245
+
246
+
247
+ def uninstall(target: str, scope: str = "project", root: str | None = None) -> list[str]:
248
+ root = root or os.getcwd()
249
+ spec = TARGETS.get(target)
250
+ if not spec or scope not in spec["scopes"]:
251
+ raise ValueError(f"unknown target or scope: {target} {scope}")
252
+ path = spec["scopes"][scope](root)
253
+ changed = []
254
+ if path.exists():
255
+ if spec["format"] == "toml":
256
+ text = path.read_text()
257
+ if _TOML_BLOCK.search(text):
258
+ rest = _TOML_BLOCK.sub("", text).rstrip()
259
+ if rest:
260
+ _backup(path)
261
+ path.write_text(rest + "\n")
262
+ else:
263
+ _remove_file(path)
264
+ changed.append(str(path))
265
+ else:
266
+ data = _load(path)
267
+ key = {"servers": "servers", "opencode": "mcp"}.get(spec["format"], "mcpServers")
268
+ if NAME in (data.get(key) or {}):
269
+ del data[key][NAME]
270
+ if not data[key]:
271
+ del data[key]
272
+ # opencode's $schema is added by install() itself, so it alone counts as empty
273
+ leftover = {"$schema": "https://opencode.ai/config.json"} if spec["format"] == "opencode" else {}
274
+ if data == leftover:
275
+ _remove_file(path)
276
+ else:
277
+ _save(path, data)
278
+ changed.append(str(path))
279
+ if target == "claude-code":
280
+ hp = _hooks_path(scope, root)
281
+ if hp.exists() and "mapwright" in hp.read_text():
282
+ _claude_hooks(hp, False)
283
+ changed.append(str(hp))
284
+ return changed
285
+
286
+
287
+ def status(root: str | None = None) -> list[dict]:
288
+ """Every target, with what is connected and whether the tool looks installed."""
289
+ root_given = bool(root)
290
+ root = root or os.getcwd()
291
+ bins = {"claude-code": "claude", "cursor": "cursor", "vscode": "code", "windsurf": "windsurf", "opencode": "opencode",
292
+ "codex": "codex", "gemini": "gemini", "claude-desktop": None}
293
+ dirs = {"claude-code": _cc_dir(), "cursor": Path.home() / ".cursor", "vscode": _vscode_user_dir(), "windsurf": Path.home() / ".codeium/windsurf",
294
+ "opencode": Path.home() / ".config/opencode", "codex": Path.home() / ".codex", "gemini": Path.home() / ".gemini",
295
+ "claude-desktop": TARGETS["claude-desktop"]["scopes"]["user"]("").parent}
296
+ out = []
297
+ for tid, spec in TARGETS.items():
298
+ scopes = {}
299
+ for scope, fn in spec["scopes"].items():
300
+ if scope == "project" and not root_given:
301
+ scopes[scope] = {"path": None, "connected": False}
302
+ continue
303
+ path = fn(root)
304
+ try:
305
+ scopes[scope] = {"path": str(path), "connected": path.exists() and re.search(r'["\[.]mapwright["\]]|mcp_servers\.mapwright', path.read_text()) is not None}
306
+ except OSError:
307
+ scopes[scope] = {"path": str(path), "connected": False}
308
+ installed = bool(bins.get(tid) and shutil.which(bins[tid])) or dirs[tid].exists()
309
+ out.append({"id": tid, "title": spec["title"], "how": spec["how"], "installed": installed, "scopes": scopes,
310
+ "snippet": snippet(tid if tid in ("vscode", "opencode", "codex") else "any")})
311
+ for mid, (title, how) in MANUAL.items():
312
+ out.append({"id": mid, "title": title, "how": how, "installed": None, "scopes": {}, "manual": True,
313
+ "snippet": snippet(mid if mid == "zed" else "any")})
314
+ return out
315
+
316
+
317
+ AGENTS_MD = """<!-- mapwright:start -->
318
+ ## Project map (Mapwright)
319
+ This project is tracked by Mapwright. To save tokens and stay accurate:
320
+ - Start with the `map` tool (or `mapwright brief`) instead of listing and opening files to learn the structure.
321
+ - Use `find` / `symbol` to locate code and see callers and callees before reading a file.
322
+ - After each meaningful change, call `step` with a short title. Changed files and design deltas are computed for you.
323
+ - Keep the plan in `todo`; mark items done with the symbol or file you changed as evidence.
324
+ - `claim` a mechanism (see `catalog`) only for code that implements it; claims are checked.
325
+ <!-- mapwright:end -->
326
+ """
327
+
328
+
329
+ def write_agents_md(root: str, filename: str = "AGENTS.md") -> str:
330
+ path = Path(root) / filename
331
+ text = path.read_text() if path.exists() else ""
332
+ if "<!-- mapwright:start -->" in text:
333
+ text = re.sub(r"(?s)<!-- mapwright:start -->.*?<!-- mapwright:end -->\n?", AGENTS_MD, text)
334
+ else:
335
+ text = (text.rstrip() + "\n\n" if text.strip() else "") + AGENTS_MD
336
+ path.write_text(text)
337
+ return str(path)
mapwright/export.py ADDED
@@ -0,0 +1,42 @@
1
+ """Export the map as plain files: MAP.md (renders on GitHub and in most Markdown viewers), one
2
+ .mmd file per diagram, and the steps and verification as JSON."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import json
7
+ import time
8
+ from pathlib import Path
9
+
10
+ from . import brief, render
11
+ from .server import Daemon, file_rows
12
+
13
+
14
+ def export(p, out: str) -> str:
15
+ dest = Path(out)
16
+ (dest / "diagrams").mkdir(parents=True, exist_ok=True)
17
+ p.ensure()
18
+ v = p.verify()
19
+ steps = p.steps()
20
+ md = [f"# {p.name}: project map", "",
21
+ f"Generated by Mapwright on {time.strftime('%Y-%m-%d %H:%M')} from {len(p.cache)} files and {len(steps)} steps. "
22
+ "Built by static analysis; nothing was executed.", "", "## Summary", "", "```text", brief.project_brief(p, 6000), "```", ""]
23
+ for kind, title in render.KINDS.items():
24
+ d = Daemon.diagram(None, p, kind, {"step": "live"}) # type: ignore[arg-type]
25
+ (dest / "diagrams" / f"{kind}.mmd").write_text(d["mermaid"] + "\n")
26
+ md += [f"## {title}", ""] + ([f"_{d['note']}_", ""] if d.get("note") else []) + ["```mermaid", d["mermaid"], "```", ""]
27
+ md += ["## Steps", "", "| # | When | Title | Source | Files | + / − | Check |", "|---|---|---|---|---|---|---|"]
28
+ for s in steps:
29
+ sm = s["summary"]
30
+ md.append(f"| {s['n']} | {time.strftime('%m-%d %H:%M', time.localtime(s['ts']))} | {render.label(s['title'], 80)} | {s['source']} | "
31
+ f"{sm['files']} | +{sm['added']} −{sm['removed']} | {render.label(s.get('title_check', 'ok'), 60)} |")
32
+ md += ["", "## Todos", ""] + [f"- [{'x' if t['status'] == 'done' else ' '}] **{t['id']}** {t['text']}"
33
+ + (f" — {'verified' if t.get('verified') else 'unverified'}: {t.get('reason')}" if t["status"] == "done" else "")
34
+ for t in v["todos"]] + ["", "## Verification", ""]
35
+ md += [f"- ⚠ {x['text']}" for x in v["problems"]] or ["Every claim, note, link and finished todo checks out against the code."]
36
+ (dest / "MAP.md").write_text("\n".join(md) + "\n")
37
+ (dest / "steps.json").write_text(json.dumps(steps, indent=1))
38
+ (dest / "verification.json").write_text(json.dumps({k: v[k] for k in ("todos", "claims", "notes", "links", "problems")}, indent=1, default=str))
39
+ return str(dest / "MAP.md")
40
+
41
+
42
+ __all__ = ["export", "file_rows"]
mapwright/firestore.py ADDED
@@ -0,0 +1,168 @@
1
+ """Firestore (and Cloud Storage) security rules plus collection usage in JS/TS code, as 'tables' of kind firestore.
2
+
3
+ A collection is keyed "firestore:users/{id}/notes" (every wildcard becomes {id}) so it never collides with an
4
+ SQL table. Rules give the allowed operations and an abbreviated condition; code usage (collection(db,'x'),
5
+ doc(db,'x',id), db.collection('x'), collectionGroup) adds collections the rules do not mention and lets the
6
+ Logic view link functions to the collections they touch. A subcollection carries a relation to its parent.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import re
12
+
13
+ _RULE_TOKEN = re.compile(
14
+ r"match\s+(/\S*)\s*\{|allow\s+([a-z][a-z,\s]*?)\s*(?::\s*if\s+([^;]*?))?\s*;|function\s+\w+\s*\([^)]*\)\s*\{|[{}]", re.S)
15
+ _WILD = re.compile(r"\{[^}]*\}")
16
+ _ID = "{id}"
17
+
18
+
19
+ def _abbr(cond: str | None, n: int = 70) -> str:
20
+ c = " ".join((cond or "true").split())
21
+ return c if len(c) <= n else c[: n - 1] + "…"
22
+
23
+
24
+ def key_of(path: str, prefix: str = "firestore") -> str:
25
+ return f"{prefix}:{_WILD.sub(_ID, path.strip('/'))}"
26
+
27
+
28
+ def _entry(path: str, line: int, source: str, kind_prefix: str) -> dict:
29
+ segs = path.strip("/").split("/")
30
+ cols = []
31
+ if len(segs) > 2: # users/{uid}/notes -> relation to users
32
+ parent = "/".join(segs[:-2])
33
+ cols.append({"name": segs[-2].strip("{}").split("=")[0] or "id", "type": "ref", "pk": False, "fk": key_of(parent, kind_prefix)})
34
+ return {"name": key_of(path, kind_prefix), "path": path.strip("/"), "line": line, "columns": cols, "source": source,
35
+ "kind": "firestore" if kind_prefix == "firestore" else "storage", "ops": {}}
36
+
37
+
38
+ def analyze_rules(rel: str, text: str) -> dict:
39
+ out = {"lang": "rules", "id": rel, "loc": text.count("\n") + 1, "imports": [], "classes": [], "tables": [], "functions": [],
40
+ "routes": [], "raw_imports": []}
41
+ storage = "firebase.storage" in text or rel.endswith("storage.rules")
42
+ prefix = "storage" if storage else "firestore"
43
+ clean = re.sub(r"//[^\n]*", lambda m: " " * len(m.group(0)), text)
44
+ stack: list[str | None] = [] # the collection path owned by each open block, None for other braces
45
+ base: list[str] = [] # composed path prefix at each open block
46
+ tables: dict[str, dict] = {}
47
+ cur_path = ""
48
+ for m in _RULE_TOKEN.finditer(clean):
49
+ tok = m.group(0)
50
+ if m.group(1):
51
+ segs = [s for s in m.group(1).strip("/").split("/") if s]
52
+ full = (base[-1] if base else "").split("/") if base and base[-1] else []
53
+ if segs[:1] == ["databases"] and len(segs) >= 3 and segs[2] == "documents":
54
+ segs = segs[3:]
55
+ elif segs[:1] == ["b"] and len(segs) >= 3 and segs[2] == "o":
56
+ segs = segs[3:]
57
+ full = []
58
+ path = "/".join([*full, *segs])
59
+ base.append(path)
60
+ stack.append(path or None)
61
+ elif m.group(2):
62
+ if not stack or not stack[-1]:
63
+ continue
64
+ segs = stack[-1].split("/")
65
+ while segs and segs[-1].startswith("{") and (len(segs) % 2 == 0 or storage or segs[-1].endswith("=**}")):
66
+ segs.pop()
67
+ path = "/".join(segs)
68
+ if not path:
69
+ continue
70
+ t = tables.get(path)
71
+ if t is None:
72
+ line = clean.count("\n", 0, m.start()) + 1
73
+ t = tables[path] = _entry(path, line, "firestore rules" if not storage else "storage rules", prefix)
74
+ ops = [o.strip() for o in m.group(2).replace("\n", " ").split(",") if o.strip()]
75
+ for o in ops:
76
+ t["ops"][o] = (t["ops"][o] + " | " if o in t["ops"] else "") + _abbr(m.group(3))
77
+ elif tok.startswith("function"):
78
+ stack.append(None)
79
+ base.append(base[-1] if base else "")
80
+ elif tok == "{":
81
+ stack.append(None)
82
+ base.append(base[-1] if base else "")
83
+ elif tok == "}":
84
+ if stack:
85
+ stack.pop()
86
+ base.pop()
87
+ out["tables"] = list(tables.values())
88
+ return out
89
+
90
+
91
+ # ---------------------------------------------------------------- usage in code
92
+ _DBISH = r"(?:\w*(?:db|Db|DB|irestore|tore)|firestore\(\)|getFirestore\([^)]*\))"
93
+ _STRARG = r"""(?:'[^'\n]*'|"[^"\n]*"|`[^`\n]*`)"""
94
+ _MODULAR = re.compile(r"(?<![\w$.])(collectionGroup|collection|doc)\(\s*" + _DBISH + r"\s*,\s*([^()]*(?:\([^()]*\)[^()]*)*)\)")
95
+ _CHAIN = re.compile(r"(?<![\w$])" + _DBISH + r"\s*\.(collectionGroup|collection)\(\s*(" + _STRARG + r")\s*\)((?:\s*\.doc\([^()]*\)\s*\.collection\(\s*" + _STRARG + r"\s*\))*)")
96
+ _SUB = re.compile(r"\.doc\([^()]*\)\s*\.collection\(\s*(" + _STRARG + r")\s*\)")
97
+
98
+
99
+ def _segments(args: str) -> list[str] | None:
100
+ segs = []
101
+ for a in re.split(r",(?![^()]*\))", args):
102
+ a = a.strip()
103
+ if not a:
104
+ continue
105
+ m = re.fullmatch(r"""'([^']*)'|"([^"]*)"|`([^`]*)`""", a)
106
+ if m:
107
+ s = next(g for g in m.groups() if g is not None)
108
+ segs += [re.sub(r"\$\{[^}]*\}", _ID, p) or _ID for p in s.strip("/").split("/")]
109
+ else:
110
+ segs.append(_ID)
111
+ return segs or None
112
+
113
+
114
+ def find_usage(text: str) -> list[tuple[str, int]]:
115
+ """(collection path, line) for each statically known Firestore collection used in the text."""
116
+ out = []
117
+ line_of = lambda pos: text.count("\n", 0, pos) + 1 # noqa: E731
118
+ for m in _MODULAR.finditer(text):
119
+ segs = _segments(m.group(2))
120
+ if not segs or segs[0] == _ID:
121
+ continue
122
+ if m.group(1) == "doc":
123
+ segs = segs[:-1] if len(segs) % 2 == 0 else segs
124
+ elif m.group(1) != "collectionGroup" and len(segs) % 2 == 0:
125
+ continue
126
+ if segs and segs[0] != _ID:
127
+ out.append(("/".join(segs), line_of(m.start())))
128
+ for m in _CHAIN.finditer(text):
129
+ first = _segments(m.group(2))
130
+ if not first or first[0] == _ID:
131
+ continue
132
+ segs = list(first)
133
+ out.append(("/".join(segs), line_of(m.start())))
134
+ for sm in _SUB.finditer(m.group(3)):
135
+ segs += _segments(sm.group(1)) or []
136
+ segs.insert(len(segs) - 1, _ID)
137
+ out.append(("/".join(segs), line_of(m.start())))
138
+ return out
139
+
140
+
141
+ def usage_tables(text: str) -> list[dict]:
142
+ seen: dict[str, dict] = {}
143
+ for path, line in find_usage(text):
144
+ if path not in seen:
145
+ seen[path] = _entry(path, line, "firestore (code)", "firestore")
146
+ return list(seen.values())
147
+
148
+
149
+ def function_refs(usages: list[tuple[str, int]], functions: list[dict]) -> None:
150
+ """Record on each JS function the collection keys used inside its line range."""
151
+ for path, line in usages:
152
+ inside = [f for f in functions if f["line"] <= line <= f["end"]]
153
+ if inside:
154
+ f = min(inside, key=lambda f: f["end"] - f["line"])
155
+ k = key_of(path)
156
+ if k not in f.setdefault("fs_refs", []):
157
+ f["fs_refs"].append(k)
158
+
159
+
160
+ def merge(old: dict, new: dict, rel: str) -> None:
161
+ """Fold a second description of the same collection into the first; rules beat code usage."""
162
+ if "rules" in new.get("source", "") and "rules" not in old.get("source", ""):
163
+ keep = {k: v for k, v in old.items() if k in ("file",)}
164
+ also = [old["file"], *old.get("also_in", [])]
165
+ old.clear()
166
+ old.update({**new, **keep, "file": rel, "also_in": also})
167
+ elif rel != old.get("file") and rel not in old.get("also_in", []):
168
+ old.setdefault("also_in", []).append(rel)