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/flow.py ADDED
@@ -0,0 +1,238 @@
1
+ """Control flow of one function as a flowchart, built from its syntax tree.
2
+
3
+ Python is parsed with `ast`. JS/TS gets a lighter outline (branches, loops and calls in order),
4
+ because there is no parser in the standard library. Each node carries the source line it stands
5
+ for, so clicking a box in the UI jumps to that line.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import ast
11
+ import re
12
+
13
+ MAX_NODES = 70
14
+
15
+
16
+ def _short(node, n: int = 46) -> str:
17
+ try:
18
+ text = ast.unparse(node)
19
+ except Exception:
20
+ text = type(node).__name__
21
+ text = " ".join(text.split())
22
+ return text if len(text) <= n else text[: n - 1] + "…"
23
+
24
+
25
+ def _lab(text: str) -> str:
26
+ text = re.sub(r"[\"`<>{}\[\]|#;\\]", " ", text)
27
+ return " ".join(text.split()) or " "
28
+
29
+
30
+ class _Builder:
31
+ def __init__(self):
32
+ self.lines: list[str] = []
33
+ self.nodes: dict[str, dict] = {}
34
+ self.n = 0
35
+ self.truncated = False
36
+ self.loops: list[tuple[str, list[str]]] = [] # (head id, break exits)
37
+
38
+ def node(self, shape: str, label: str, line: int | None, cls: str = "") -> str:
39
+ self.n += 1
40
+ nid = f"f{self.n}"
41
+ label = _lab(label)
42
+ wrap = {"box": ('["', '"]'), "cond": ('{"', '"}'), "term": ('(["', '"])'), "loop": ('{{"', '"}}'),
43
+ "io": ('[/"', '"/]'), "sub": ('[["', '"]]')}[shape]
44
+ self.lines.append(f" {nid}{wrap[0]}{label}{wrap[1]}" + (f":::{cls}" if cls else ""))
45
+ self.nodes[nid] = {"line": line, "label": label}
46
+ return nid
47
+
48
+ def edge(self, a: str, b: str, label: str = "") -> None:
49
+ self.lines.append(f" {a} -->|{_lab(label)}| {b}" if label else f" {a} --> {b}")
50
+
51
+ def link_all(self, srcs: list[tuple[str, str]], dst: str) -> None:
52
+ for s, lab in srcs:
53
+ self.edge(s, dst, lab)
54
+
55
+ def block(self, stmts: list, entry: list[tuple[str, str]]) -> list[tuple[str, str]]:
56
+ """Lay out a statement list; returns the open exits [(node id, edge label)]."""
57
+ cur = entry
58
+ run: list = []
59
+
60
+ def flush():
61
+ nonlocal cur, run
62
+ if run:
63
+ text = "; ".join(_short(s, 30) for s in run[:2]) + (f" (+{len(run) - 2})" if len(run) > 2 else "")
64
+ nid = self.node("io" if any(_is_io(s) for s in run) else "box", text, run[0].lineno)
65
+ self.link_all(cur, nid)
66
+ cur = [(nid, "")]
67
+ run = []
68
+
69
+ for st in stmts:
70
+ if not cur:
71
+ break # unreachable after return/raise/break
72
+ if self.n > MAX_NODES:
73
+ self.truncated = True
74
+ flush()
75
+ nid = self.node("box", "… more", st.lineno, "muted")
76
+ self.link_all(cur, nid)
77
+ return [(nid, "")]
78
+ if isinstance(st, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
79
+ flush()
80
+ nid = self.node("sub", f"def {st.name}" if not isinstance(st, ast.ClassDef) else f"class {st.name}", st.lineno)
81
+ self.link_all(cur, nid)
82
+ cur = [(nid, "")]
83
+ elif isinstance(st, ast.If):
84
+ flush()
85
+ c = self.node("cond", _short(st.test) + "?", st.lineno)
86
+ self.link_all(cur, c)
87
+ yes = self.block(st.body, [(c, "yes")])
88
+ no = self.block(st.orelse, [(c, "no")]) if st.orelse else [(c, "no")]
89
+ cur = yes + no
90
+ elif isinstance(st, (ast.For, ast.AsyncFor, ast.While)):
91
+ flush()
92
+ head = self.node("loop", ("for " + _short(st.target, 16) + " in " + _short(st.iter, 22)) if not isinstance(st, ast.While)
93
+ else "while " + _short(st.test), st.lineno)
94
+ self.link_all(cur, head)
95
+ self.loops.append((head, []))
96
+ body = self.block(st.body, [(head, "each" if not isinstance(st, ast.While) else "true")])
97
+ for s, lab in body:
98
+ self.edge(s, head, lab or "next")
99
+ _, breaks = self.loops.pop()
100
+ done = [(head, "done")]
101
+ if st.orelse:
102
+ done = self.block(st.orelse, done)
103
+ cur = done + breaks
104
+ elif isinstance(st, ast.Try) or type(st).__name__ == "TryStar":
105
+ flush()
106
+ t = self.node("box", "try", st.lineno)
107
+ self.link_all(cur, t)
108
+ ok = self.block(st.body, [(t, "")])
109
+ outs = []
110
+ for h in st.handlers:
111
+ e = self.node("cond", "except " + (_short(h.type, 28) if h.type else "any"), h.lineno, "warn")
112
+ self.edge(t, e, "error")
113
+ outs += self.block(h.body, [(e, "")])
114
+ if st.orelse:
115
+ ok = self.block(st.orelse, ok)
116
+ cur = ok + outs
117
+ if st.finalbody:
118
+ fin = self.node("box", "finally", st.finalbody[0].lineno)
119
+ self.link_all(cur, fin)
120
+ cur = self.block(st.finalbody, [(fin, "")])
121
+ elif isinstance(st, (ast.With, ast.AsyncWith)):
122
+ flush()
123
+ w = self.node("box", "with " + ", ".join(_short(i.context_expr, 24) for i in st.items), st.lineno)
124
+ self.link_all(cur, w)
125
+ cur = self.block(st.body, [(w, "")])
126
+ elif type(st).__name__ == "Match":
127
+ flush()
128
+ m = self.node("cond", "match " + _short(st.subject), st.lineno)
129
+ self.link_all(cur, m)
130
+ outs = []
131
+ for case in st.cases:
132
+ outs += self.block(case.body, [(m, _short(case.pattern, 18))])
133
+ cur = outs
134
+ elif isinstance(st, ast.Return):
135
+ flush()
136
+ r = self.node("term", "return " + (_short(st.value) if st.value else ""), st.lineno, "ret")
137
+ self.link_all(cur, r)
138
+ self.edge(r, "fEnd")
139
+ cur = []
140
+ elif isinstance(st, ast.Raise):
141
+ flush()
142
+ r = self.node("term", "raise " + (_short(st.exc, 36) if st.exc else ""), st.lineno, "err")
143
+ self.link_all(cur, r)
144
+ cur = []
145
+ elif isinstance(st, ast.Break):
146
+ flush()
147
+ if self.loops:
148
+ self.loops[-1][1].extend((s, lab or "break") for s, lab in cur)
149
+ cur = []
150
+ elif isinstance(st, ast.Continue):
151
+ flush()
152
+ if self.loops:
153
+ for s, lab in cur:
154
+ self.edge(s, self.loops[-1][0], lab or "continue")
155
+ cur = []
156
+ elif isinstance(st, ast.Expr) and isinstance(st.value, ast.Constant) and isinstance(st.value.value, str):
157
+ continue # docstring
158
+ else:
159
+ run.append(st)
160
+ if len(run) >= 3 or _is_io(st):
161
+ flush()
162
+ flush()
163
+ return cur
164
+
165
+
166
+ def _is_io(st) -> bool:
167
+ if not isinstance(st, (ast.Expr, ast.Assign, ast.AnnAssign, ast.AugAssign)):
168
+ return False
169
+ text = _short(st, 200).lower()
170
+ return bool(re.search(r"\b(await|open|print|write|read|send|fetch|request|execute|commit|query|get|post|put|save|delete|emit|publish|log\w*)\(", text))
171
+
172
+
173
+ STYLE = [" classDef ret stroke:#57965C,stroke-width:2px", " classDef err stroke:#DB5C5C,stroke-width:2px",
174
+ " classDef warn stroke:#E5A13E,stroke-width:1.5px", " classDef muted stroke-dasharray:4 3"]
175
+
176
+
177
+ def python_flow(text: str, line: int) -> dict | None:
178
+ """Flowchart for the function that starts at `line`. None if it cannot be found or parsed."""
179
+ try:
180
+ tree = ast.parse(text)
181
+ except (SyntaxError, ValueError, RecursionError):
182
+ return None
183
+ fn = next((n for n in ast.walk(tree) if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef)) and n.lineno == line), None)
184
+ if fn is None:
185
+ return None
186
+ b = _Builder()
187
+ args = ", ".join(a.arg for a in fn.args.args if a.arg not in ("self", "cls"))
188
+ start = b.node("term", f"{'async ' if isinstance(fn, ast.AsyncFunctionDef) else ''}{fn.name}({args})", fn.lineno, "ret")
189
+ exits = b.block(fn.body, [(start, "")])
190
+ b.lines.insert(0, ' fEnd(["end"])')
191
+ b.nodes["fEnd"] = {"line": getattr(fn, "end_lineno", fn.lineno), "label": "end"}
192
+ b.link_all(exits, "fEnd")
193
+ return {"mermaid": "flowchart TD\n" + "\n".join(b.lines + STYLE), "nodes": b.nodes, "truncated": b.truncated,
194
+ "kind": "flowchart", "lang": "python"}
195
+
196
+
197
+ _JS_STEP = re.compile(r"^\s*(?:\}\s*)?(if|else if|else|for|while|switch|case|try|catch|finally|return|throw|await)\b(.*)$")
198
+
199
+
200
+ def js_outline(text: str, line: int, end: int) -> dict:
201
+ """A lighter flow for JS/TS: branches, loops, returns and calls in source order."""
202
+ b = _Builder()
203
+ lines = text.splitlines()[line - 1:end]
204
+ head = lines[0].strip() if lines else "function"
205
+ start = b.node("term", head[:46], line, "ret")
206
+ prev = [(start, "")]
207
+ stack: list[str] = []
208
+ for i, raw in enumerate(lines[1:], start=line + 1):
209
+ if b.n > MAX_NODES:
210
+ b.truncated = True
211
+ break
212
+ m = _JS_STEP.match(raw)
213
+ s = raw.strip()
214
+ if m:
215
+ kw, rest = m.group(1), m.group(2).strip().rstrip("{").strip()
216
+ if kw in ("if", "else if", "while", "switch"):
217
+ nid = b.node("cond", f"{kw} {rest}"[:46], i)
218
+ elif kw == "for":
219
+ nid = b.node("loop", f"for {rest}"[:46], i)
220
+ elif kw in ("return", "throw"):
221
+ nid = b.node("term", f"{kw} {rest}"[:46], i, "ret" if kw == "return" else "err")
222
+ elif kw in ("catch",):
223
+ nid = b.node("cond", f"catch {rest}"[:46], i, "warn")
224
+ else:
225
+ nid = b.node("box", f"{kw} {rest}"[:46], i)
226
+ b.link_all(prev, nid)
227
+ prev = [(nid, "")]
228
+ if kw in ("if", "for", "while"):
229
+ stack.append(nid)
230
+ elif re.search(r"\w\s*\(", s) and not s.startswith(("//", "*", "/*")) and len(s) > 3:
231
+ nid = b.node("io" if re.search(r"\b(await|fetch|query|save|send|write|emit)\b", s) else "box", s[:46], i)
232
+ b.link_all(prev, nid)
233
+ prev = [(nid, "")]
234
+ b.lines.insert(0, ' fEnd(["end"])')
235
+ b.nodes["fEnd"] = {"line": end, "label": "end"}
236
+ b.link_all(prev, "fEnd")
237
+ return {"mermaid": "flowchart TD\n" + "\n".join(b.lines + STYLE), "nodes": b.nodes, "truncated": b.truncated,
238
+ "kind": "outline", "lang": "js"}
mapwright/hooks.py ADDED
@@ -0,0 +1,111 @@
1
+ """Hook client: agents report prompts, tool calls and turn ends here (Claude Code command hooks,
2
+ the opencode plugin, or anything that can run a command with JSON on stdin).
3
+
4
+ It never blocks the agent and never prints to stdout: whatever goes wrong, it exits 0. A turn end
5
+ closes a step by itself when the auto-step setting allows it, so steps happen even if the agent
6
+ never calls the `step` tool.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import json
12
+ import os
13
+ import re
14
+ import sys
15
+
16
+ WRITE_TOOLS = {"Write", "Edit", "MultiEdit", "NotebookEdit", "write", "edit", "patch", "apply_patch", "multiedit", "create_file",
17
+ "str_replace_editor", "replace_in_file", "write_to_file"}
18
+
19
+
20
+ def _files(ti: dict) -> list[str]:
21
+ out = []
22
+ for k in ("file_path", "path", "notebook_path", "filePath", "target_file"):
23
+ v = ti.get(k)
24
+ if isinstance(v, str) and v:
25
+ out.append(v)
26
+ return out[:20]
27
+
28
+
29
+ _READ_ONLY = {"ls", "cat", "head", "tail", "grep", "egrep", "fgrep", "rg", "ag", "find", "fd", "pwd", "echo", "printf", "wc", "which",
30
+ "whoami", "date", "env", "printenv", "tree", "stat", "file", "du", "df", "diff", "sort", "uniq", "cut", "tr", "less",
31
+ "more", "type", "realpath", "dirname", "basename", "test", "true", "sleep", "jq", "node_version", "ps", "id", "uname"}
32
+ _GIT_READ = {"status", "diff", "log", "show", "branch", "rev-parse", "ls-files", "blame", "remote", "describe", "config", "grep", "shortlog"}
33
+ _WRITING = re.compile(r"(?<![<=>&|0-9])>{1,2}(?![&>])|\btee\b|\s-delete\b|\s-exec\b|\s-i\b|\bsed\s+-[a-z]*i|\bxargs\b|\$\(|`")
34
+
35
+
36
+ def read_only_bash(cmd: str) -> bool:
37
+ """True when a shell command only looks at things (cheap heuristic: every `;`/`&&`/`||`/`|`-separated
38
+ part starts with a known read-only program, and there is no redirect, tee, in-place edit or substitution)."""
39
+ if not cmd or _WRITING.search(cmd):
40
+ return False
41
+ for part in re.split(r"&&|\|\||;|\||\n", cmd):
42
+ words = part.split()
43
+ while words and re.match(r"^[A-Za-z_][A-Za-z0-9_]*=", words[0]):
44
+ words = words[1:]
45
+ if not words:
46
+ continue
47
+ prog = os.path.basename(words[0])
48
+ if prog == "git":
49
+ rest = [w for w in words[1:] if not w.startswith("-")]
50
+ if not rest or rest[0] not in _GIT_READ:
51
+ return False
52
+ elif prog not in _READ_ONLY:
53
+ return False
54
+ return True
55
+
56
+
57
+ def handle(agent: str, payload: dict) -> None:
58
+ from .track import open_project
59
+ cwd = payload.get("cwd") or payload.get("directory") or os.getcwd()
60
+ if not os.path.isdir(cwd):
61
+ return
62
+ home = os.path.realpath(os.path.expanduser("~"))
63
+ if os.path.realpath(cwd) in (home, "/"):
64
+ return # never track a whole home directory
65
+ from . import config
66
+ config.set_start(cwd) # a project-local home is found from the payload cwd (MAPWRIGHT_HOME still wins)
67
+ ev = payload.get("hook_event_name") or payload.get("event") or ""
68
+ if ev == "SubagentStop":
69
+ return # a subagent finishing is not the end of the user's turn
70
+ p = open_project(cwd)
71
+ session = payload.get("session_id") or payload.get("sessionID") or payload.get("sessionId") or ""
72
+ if ev in ("UserPromptSubmit", "prompt"):
73
+ p.record("prompt", text=payload.get("prompt") or payload.get("text") or "", agent=agent, session=session)
74
+ elif ev in ("PostToolUse", "tool"):
75
+ tool = str(payload.get("tool_name") or payload.get("tool") or "")
76
+ ti = payload.get("tool_input") if isinstance(payload.get("tool_input"), dict) else payload.get("args") or {}
77
+ is_shell = tool.lower() in ("bash", "shell", "run_terminal_cmd", "execute_command")
78
+ if is_shell and read_only_bash(str(ti.get("command") or ti.get("cmd") or "")):
79
+ return
80
+ if tool in WRITE_TOOLS or is_shell or tool.startswith("mcp__"):
81
+ root = p.root + "/"
82
+ files = [os.path.relpath(f, p.root) if os.path.isabs(f) and f.startswith(root) else f for f in _files(ti)]
83
+ p.record("tool", tool=tool, files=files, agent=agent, session=session)
84
+ elif ev in ("Stop", "SessionEnd", "turn_end", "idle"):
85
+ if payload.get("stop_hook_active") or payload.get("agent_id") or payload.get("agent_type"):
86
+ return # a Stop re-fired by a Stop hook, or one that comes from inside a subagent
87
+ final = ev == "SessionEnd"
88
+ with p.locked(): # record + step as one unit: concurrent hook processes cannot interleave
89
+ p.record("turn_end", agent=agent, session=session)
90
+ p.maybe_auto_step(session=str(session), final=final)
91
+
92
+
93
+ def main(argv: list[str] | None = None) -> int:
94
+ argv = sys.argv[1:] if argv is None else argv
95
+ agent = argv[0] if argv else "claude-code"
96
+ try:
97
+ payload = json.loads(sys.stdin.read() or "{}")
98
+ if isinstance(payload, dict):
99
+ handle(agent, payload)
100
+ except Exception as e: # a hook must never break the agent
101
+ try:
102
+ from . import config
103
+ with open(config.home() / "hook-errors.log", "a") as fh:
104
+ fh.write(f"{type(e).__name__}: {e}\n")
105
+ except Exception:
106
+ pass
107
+ return 0
108
+
109
+
110
+ if __name__ == "__main__":
111
+ raise SystemExit(main())
mapwright/ignore.py ADDED
@@ -0,0 +1,248 @@
1
+ """Ignore handling: a stdlib-only gitignore matcher plus suggestions for bulky generated/data folders.
2
+
3
+ `Matcher` combines .git/info/exclude, the root and nested .gitignore files (when `respect_gitignore`)
4
+ and the user's `ignore` setting (gitignore patterns; plain names match at any depth). It holds no
5
+ module state, so concurrent scans of different projects do not interfere.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import os
11
+ import re
12
+ from collections import Counter
13
+
14
+ DATA_EXT = {".json", ".jsonl", ".ndjson", ".csv", ".tsv", ".parquet", ".pdf", ".png", ".jpg", ".jpeg", ".gif", ".webp",
15
+ ".svg", ".avif", ".ico", ".bin", ".dat", ".xml", ".txt", ".md", ".mp3", ".mp4", ".webm", ".woff", ".woff2",
16
+ ".ttf", ".zip", ".gz", ".map", ".html", ".xlsx", ".sqlite", ".db"}
17
+ GENERATED_NAMES = {"storybook-static", "__generated__", ".docusaurus", ".angular", ".expo", ".vercel", ".netlify",
18
+ "generated", "_next", ".astro", ".yarn", ".pnpm-store", "playwright-report", "test-results"}
19
+ SKIP_SURVEY = {".git", "node_modules", ".venv", "venv", "__pycache__", ".mapwright", "dist", "build", ".next", "out", "coverage",
20
+ "target", ".tox", "site-packages"}
21
+
22
+
23
+ def _translate(pat: str) -> str:
24
+ out, i, n = [], 0, len(pat)
25
+ while i < n:
26
+ ch = pat[i]
27
+ if pat.startswith("**", i):
28
+ j = i + 2
29
+ while j < n and pat[j] == "*":
30
+ j += 1
31
+ at_start = i == 0 or pat[i - 1] == "/"
32
+ if at_start and j < n and pat[j] == "/":
33
+ out.append("(?:.*/)?")
34
+ i = j
35
+ i += 1
36
+ continue
37
+ out.append(".*")
38
+ i = j
39
+ continue
40
+ if ch == "*":
41
+ out.append("[^/]*")
42
+ elif ch == "?":
43
+ out.append("[^/]")
44
+ elif ch == "[":
45
+ j = i + 1
46
+ if j < n and pat[j] in "!^":
47
+ j += 1
48
+ if j < n and pat[j] == "]":
49
+ j += 1
50
+ while j < n and pat[j] != "]":
51
+ j += 1
52
+ if j >= n:
53
+ out.append(r"\[")
54
+ else:
55
+ body = pat[i + 1:j]
56
+ neg = body[:1] in ("!", "^")
57
+ if neg:
58
+ body = body[1:]
59
+ body = body.replace("\\", "\\\\")
60
+ out.append("[" + ("^" if neg else "") + body + "]")
61
+ i = j
62
+ elif ch == "\\" and i + 1 < n:
63
+ i += 1
64
+ out.append(re.escape(pat[i]))
65
+ else:
66
+ out.append(re.escape(ch))
67
+ i += 1
68
+ return "".join(out)
69
+
70
+
71
+ class Rule:
72
+ __slots__ = ("base", "neg", "dir_only", "anchored", "rx")
73
+
74
+ def __init__(self, base: str, neg: bool, dir_only: bool, anchored: bool, rx):
75
+ self.base, self.neg, self.dir_only, self.anchored, self.rx = base, neg, dir_only, anchored, rx
76
+
77
+ def match(self, rel: str, is_dir: bool) -> bool:
78
+ if self.dir_only and not is_dir:
79
+ return False
80
+ if self.base:
81
+ if not rel.startswith(self.base + "/"):
82
+ return False
83
+ rel = rel[len(self.base) + 1:]
84
+ if not self.anchored:
85
+ rel = rel.rsplit("/", 1)[-1]
86
+ return self.rx.fullmatch(rel) is not None
87
+
88
+
89
+ def parse_line(line: str, base: str = "") -> Rule | None:
90
+ line = line.rstrip("\r\n")
91
+ if not line.strip() or line.startswith("#"):
92
+ return None
93
+ while line.endswith(" ") and not line.endswith("\\ "): # trailing spaces drop unless escaped
94
+ line = line[:-1]
95
+ neg = line.startswith("!")
96
+ if neg:
97
+ line = line[1:]
98
+ dir_only = line.endswith("/")
99
+ line = line.rstrip("/")
100
+ if not line:
101
+ return None
102
+ anchored = "/" in line
103
+ line = line.lstrip("/")
104
+ if not line:
105
+ return None
106
+ try:
107
+ rx = re.compile(_translate(line))
108
+ except re.error:
109
+ return None
110
+ return Rule(base, neg, dir_only, anchored, rx)
111
+
112
+
113
+ def parse(text: str, base: str = "") -> list[Rule]:
114
+ return [r for r in (parse_line(ln, base) for ln in text.splitlines()) if r]
115
+
116
+
117
+ def _decide(rules, rel: str, is_dir: bool):
118
+ verdict = None
119
+ for r in rules:
120
+ if r.match(rel, is_dir):
121
+ verdict = not r.neg
122
+ return verdict
123
+
124
+
125
+ class Matcher:
126
+ """gitignore semantics. Nested .gitignore files are read lazily as the scan descends."""
127
+
128
+ def __init__(self, root: str, patterns=(), respect_gitignore: bool = True):
129
+ self.root = root
130
+ self.respect = respect_gitignore
131
+ self.user = [r for r in (parse_line(p) for p in patterns or ()) if r]
132
+ self._dir_rules: dict[str, list[Rule]] = {}
133
+
134
+ def _read(self, path: str, base: str) -> list[Rule]:
135
+ try:
136
+ with open(path, encoding="utf-8", errors="replace") as fh:
137
+ return parse(fh.read(), base)
138
+ except OSError:
139
+ return []
140
+
141
+ def _rules_for(self, d: str) -> list[Rule]:
142
+ got = self._dir_rules.get(d)
143
+ if got is not None:
144
+ return got
145
+ if d == "":
146
+ rules = (self._read(os.path.join(self.root, ".git", "info", "exclude"), "")
147
+ + self._read(os.path.join(self.root, ".gitignore"), ""))
148
+ else:
149
+ parent = d.rsplit("/", 1)[0] if "/" in d else ""
150
+ rules = self._rules_for(parent) + self._read(os.path.join(self.root, *d.split("/"), ".gitignore"), d)
151
+ self._dir_rules[d] = rules
152
+ return rules
153
+
154
+ def matches(self, rel: str, is_dir: bool) -> bool:
155
+ """Does this one entry match (its parents assumed not ignored, as in a pruned scan)?"""
156
+ if self.user:
157
+ v = _decide(self.user, rel, is_dir)
158
+ if v is not None:
159
+ return v
160
+ if not self.respect:
161
+ return False
162
+ parent = rel.rsplit("/", 1)[0] if "/" in rel else ""
163
+ return bool(_decide(self._rules_for(parent), rel, is_dir))
164
+
165
+ def is_ignored(self, rel: str, is_dir: bool = False) -> bool:
166
+ """Full check including ancestors (an ignored directory cannot be re-included)."""
167
+ parts = rel.replace(os.sep, "/").strip("/").split("/")
168
+ for k in range(1, len(parts) + 1):
169
+ if self.matches("/".join(parts[:k]), is_dir if k == len(parts) else True):
170
+ return True
171
+ return False
172
+
173
+
174
+ def survey(root: str, matcher: Matcher | None = None, limit: int = 200_000) -> dict[str, int]:
175
+ """rel path -> size for every non-ignored file of any type (used only by `init` suggestions)."""
176
+ out: dict[str, int] = {}
177
+ for dirpath, dirs, files in os.walk(root):
178
+ rd = os.path.relpath(dirpath, root).replace(os.sep, "/")
179
+ rd = "" if rd == "." else rd
180
+ keep = []
181
+ for d in sorted(dirs):
182
+ rel = f"{rd}/{d}" if rd else d
183
+ if d in SKIP_SURVEY or d.endswith(".egg-info") or (matcher and matcher.matches(rel, True)):
184
+ continue
185
+ keep.append(d)
186
+ dirs[:] = keep
187
+ for f in sorted(files):
188
+ rel = f"{rd}/{f}" if rd else f
189
+ if matcher and matcher.matches(rel, False):
190
+ continue
191
+ try:
192
+ out[rel] = os.lstat(os.path.join(dirpath, f)).st_size
193
+ except OSError:
194
+ continue
195
+ if len(out) >= limit:
196
+ return out
197
+ return out
198
+
199
+
200
+ def suggest_ignores(files: dict[str, int], min_files: int = 200, min_bytes: int = 50_000_000) -> list[dict]:
201
+ """Pure heuristic. `files` maps rel path -> size. Returns [{pattern, files, bytes, reason}], largest first.
202
+
203
+ A directory is suggested when it has at least `min_files` files or `min_bytes` bytes and is mostly data
204
+ (json/pdf/images/csv/...), when it has a generated-looking name, or when its name says "bank".
205
+ The highest qualifying directory wins; its subtree is not reported again.
206
+ """
207
+ tree: dict[str, dict] = {}
208
+ for rel, size in files.items():
209
+ parts = rel.split("/")
210
+ ext = os.path.splitext(parts[-1])[1].lower()
211
+ for k in range(1, len(parts)):
212
+ d = "/".join(parts[:k])
213
+ t = tree.setdefault(d, {"files": 0, "bytes": 0, "data": 0, "ext": Counter()})
214
+ t["files"] += 1
215
+ t["bytes"] += size
216
+ t["data"] += ext in DATA_EXT
217
+ t["ext"][ext] += 1
218
+ out, taken = [], []
219
+ for d in sorted(tree, key=lambda x: (x.count("/"), x)):
220
+ if any(d == t or d.startswith(t + "/") for t in taken):
221
+ continue
222
+ t, name = tree[d], d.rsplit("/", 1)[-1]
223
+ mostly_data = t["data"] >= 0.8 * t["files"]
224
+ top_ext, top_n = t["ext"].most_common(1)[0]
225
+ reason = None
226
+ if name in GENERATED_NAMES:
227
+ reason = "generated output"
228
+ elif "bank" in name.lower() and t["files"] >= 20 and mostly_data:
229
+ reason = f"data folder ({t['files']} files)"
230
+ elif mostly_data and t["files"] >= min_files:
231
+ reason = f"{t['files']} mostly data/binary files" + (f", {top_n} of them {top_ext}" if top_n >= 0.5 * t["files"] else "")
232
+ elif mostly_data and t["bytes"] >= min_bytes:
233
+ reason = f"{t['bytes'] // 1_000_000} MB of data/binary files"
234
+ if reason:
235
+ while True: # narrow to the one child holding nearly everything
236
+ kids = [k for k in tree if k.startswith(d + "/") and k.count("/") == d.count("/") + 1 and tree[k]["files"] >= 0.9 * t["files"]]
237
+ if not kids or name in GENERATED_NAMES:
238
+ break
239
+ d = kids[0]
240
+ t = tree[d]
241
+ taken.append(d)
242
+ out.append({"pattern": d + "/", "files": t["files"], "bytes": t["bytes"], "reason": reason})
243
+ covered = tuple(t + "/" for t in taken)
244
+ mins = [r for r in files if r.endswith((".min.js", ".min.css")) and not r.startswith(covered)]
245
+ if len(mins) >= 3:
246
+ out.append({"pattern": "*.min.*", "files": len(mins), "bytes": sum(files[r] for r in mins), "reason": "minified bundles"})
247
+ out.sort(key=lambda s: (-s["files"], s["pattern"]))
248
+ return out