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/__init__.py +3 -0
- mapwright/__main__.py +3 -0
- mapwright/analyze.py +809 -0
- mapwright/brief.py +208 -0
- mapwright/cli.py +596 -0
- mapwright/concepts.py +190 -0
- mapwright/config.py +204 -0
- mapwright/connect.py +337 -0
- mapwright/export.py +42 -0
- mapwright/firestore.py +168 -0
- mapwright/flow.py +238 -0
- mapwright/hooks.py +111 -0
- mapwright/ignore.py +248 -0
- mapwright/infra.py +253 -0
- mapwright/mcp.py +153 -0
- mapwright/noise.py +80 -0
- mapwright/redact.py +39 -0
- mapwright/render.py +428 -0
- mapwright/routes_js.py +282 -0
- mapwright/server.py +388 -0
- mapwright/titles.py +111 -0
- mapwright/track.py +715 -0
- mapwright/ui/app.css +277 -0
- mapwright/ui/app.js +1025 -0
- mapwright/ui/icons.svg +73 -0
- mapwright/ui/index.html +35 -0
- mapwright/ui/mark.svg +1 -0
- mapwright/ui/vendor/mermaid.LICENSE +21 -0
- mapwright/ui/vendor/mermaid.min.js +2029 -0
- mapwright_agent-0.2.0.dist-info/METADATA +179 -0
- mapwright_agent-0.2.0.dist-info/RECORD +34 -0
- mapwright_agent-0.2.0.dist-info/WHEEL +4 -0
- mapwright_agent-0.2.0.dist-info/entry_points.txt +3 -0
- mapwright_agent-0.2.0.dist-info/licenses/LICENSE +21 -0
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)
|