edify-agents-cli 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.
Files changed (102) hide show
  1. edify/__init__.py +19 -0
  2. edify/__main__.py +6 -0
  3. edify/_toml.py +286 -0
  4. edify/agents.py +261 -0
  5. edify/anim.py +499 -0
  6. edify/assets/commands/build.md +64 -0
  7. edify/assets/commands/plan.md +68 -0
  8. edify/assets/commands/spec.md +63 -0
  9. edify/assets/commands/tasks.md +65 -0
  10. edify/assets/commands/verify.md +67 -0
  11. edify/assets/formats/plan.example.md +455 -0
  12. edify/assets/formats/plan.format.md +128 -0
  13. edify/assets/formats/spec.example.md +483 -0
  14. edify/assets/formats/spec.format.md +116 -0
  15. edify/assets/formats/tasks.example.md +712 -0
  16. edify/assets/formats/tasks.format.md +199 -0
  17. edify/assets/harvest/harvest.md +91 -0
  18. edify/assets/harvest/sources.md +295 -0
  19. edify/assets/harvest/vocab.md +52 -0
  20. edify/assets/manifest.md +30 -0
  21. edify/assets/mcp/default-registry.md +66 -0
  22. edify/assets/skills/adversary.md +61 -0
  23. edify/assets/skills/debugger.md +64 -0
  24. edify/assets/skills/implementer-general.md +53 -0
  25. edify/assets/skills/implementer-go.md +63 -0
  26. edify/assets/skills/implementer-node.md +61 -0
  27. edify/assets/skills/implementer-postgres.md +63 -0
  28. edify/assets/skills/implementer-python.md +65 -0
  29. edify/assets/skills/implementer-react.md +65 -0
  30. edify/assets/skills/planner.md +58 -0
  31. edify/assets/skills/test-writer-node.md +64 -0
  32. edify/assets/skills/test-writer-python.md +60 -0
  33. edify/assets/skills/verifier.md +67 -0
  34. edify/assets/templates/CLAUDE.md +18 -0
  35. edify/assets.py +77 -0
  36. edify/cli.py +681 -0
  37. edify/commands/__init__.py +1 -0
  38. edify/commands/check_cmd.py +72 -0
  39. edify/commands/doctor_cmd.py +206 -0
  40. edify/commands/feedback_cmd.py +90 -0
  41. edify/commands/governance_cmd.py +65 -0
  42. edify/commands/graph_cmd.py +156 -0
  43. edify/commands/harvest_cmd.py +538 -0
  44. edify/commands/init_cmd.py +333 -0
  45. edify/commands/init_new_cmd.py +151 -0
  46. edify/commands/license_cmd.py +80 -0
  47. edify/commands/mcp_cmd.py +159 -0
  48. edify/commands/self_cmd.py +185 -0
  49. edify/commands/setup_cmd.py +79 -0
  50. edify/commands/skills_cmd.py +177 -0
  51. edify/commands/upgrade_cmd.py +178 -0
  52. edify/context.py +57 -0
  53. edify/conventions.py +275 -0
  54. edify/detect.py +313 -0
  55. edify/distribution.py +40 -0
  56. edify/errors.py +66 -0
  57. edify/feedback.py +207 -0
  58. edify/formats/__init__.py +11 -0
  59. edify/formats/check.py +573 -0
  60. edify/formats/document.py +238 -0
  61. edify/formats/finding.py +50 -0
  62. edify/formats/fix.py +114 -0
  63. edify/formats/mcp.py +126 -0
  64. edify/formats/plan.py +151 -0
  65. edify/formats/skill.py +139 -0
  66. edify/formats/spec.py +164 -0
  67. edify/formats/tasks.py +321 -0
  68. edify/governance.py +316 -0
  69. edify/graph/__init__.py +11 -0
  70. edify/graph/extract.py +351 -0
  71. edify/graph/ignore.py +107 -0
  72. edify/graph/langs/__init__.py +93 -0
  73. edify/graph/langs/ctags.py +145 -0
  74. edify/graph/langs/markdown.py +41 -0
  75. edify/graph/langs/patterns.py +361 -0
  76. edify/graph/langs/python_ast.py +154 -0
  77. edify/graph/langs/sqlish.py +86 -0
  78. edify/graph/model.py +102 -0
  79. edify/graph/queries.py +211 -0
  80. edify/graph/store.py +157 -0
  81. edify/harvest/__init__.py +28 -0
  82. edify/harvest/ledger.py +191 -0
  83. edify/harvest/screen.py +236 -0
  84. edify/harvest/sources.py +298 -0
  85. edify/host.py +345 -0
  86. edify/interview.py +354 -0
  87. edify/library.py +176 -0
  88. edify/licensing/__init__.py +30 -0
  89. edify/licensing/ed25519.py +154 -0
  90. edify/licensing/projects.py +223 -0
  91. edify/licensing/tier.py +172 -0
  92. edify/licensing/token.py +149 -0
  93. edify/paths.py +282 -0
  94. edify/selfinstall.py +244 -0
  95. edify/skills.py +108 -0
  96. edify/tsv.py +109 -0
  97. edify/ui.py +334 -0
  98. edify_agents_cli-0.2.0.dist-info/METADATA +408 -0
  99. edify_agents_cli-0.2.0.dist-info/RECORD +102 -0
  100. edify_agents_cli-0.2.0.dist-info/WHEEL +4 -0
  101. edify_agents_cli-0.2.0.dist-info/entry_points.txt +2 -0
  102. edify_agents_cli-0.2.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,361 @@
1
+ """The declarative line scanner.
2
+
3
+ One rule table per language, matched line by line with comment lines skipped. It
4
+ is a scanner, not a parser, and `meta` records that: a language extracted here is
5
+ marked `scan`, and `edify doctor` says what that costs. Install a pinned external
6
+ extractor (`--extractor ctags`) or the tree-sitter extra when a language needs
7
+ parse-grade precision.
8
+
9
+ A rule that would need to look at more than one line does not belong here. The
10
+ honest failure of a scanner is a missing symbol, and a missing symbol is visible.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import re
16
+ from dataclasses import dataclass
17
+
18
+ from ..model import Edge, Extraction, Node, fingerprint, node_id
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class Rule:
23
+ """One line pattern that yields one node."""
24
+
25
+ pattern: re.Pattern[str]
26
+ kind: str = "symbol" # symbol | route | table
27
+ name_group: str = "name"
28
+ method_group: str | None = None # for routes: the HTTP verb
29
+
30
+
31
+ @dataclass(frozen=True)
32
+ class LangRules:
33
+ rules: tuple[Rule, ...]
34
+ imports: tuple[re.Pattern[str], ...] = ()
35
+ line_comment: tuple[str, ...] = ("//",)
36
+ block_comment: tuple[str, str] | None = ("/*", "*/")
37
+
38
+
39
+ _ID = r"[A-Za-z_$][A-Za-z0-9_$]*"
40
+
41
+ # --------------------------------------------------------------------------
42
+ # JavaScript / TypeScript
43
+ # --------------------------------------------------------------------------
44
+
45
+ _JSTS = LangRules(
46
+ rules=(
47
+ Rule(re.compile(rf"^\s*export\s+(?:default\s+)?(?:async\s+)?function\s*\*?\s*(?P<name>{_ID})")),
48
+ Rule(re.compile(rf"^\s*export\s+(?:abstract\s+)?class\s+(?P<name>{_ID})")),
49
+ Rule(re.compile(rf"^\s*export\s+(?:declare\s+)?(?:const|let|var)\s+(?P<name>{_ID})")),
50
+ Rule(re.compile(rf"^\s*export\s+(?:declare\s+)?(?:interface|type|enum)\s+(?P<name>{_ID})")),
51
+ Rule(re.compile(rf"^\s*export\s+default\s+class\s+(?P<name>{_ID})")),
52
+ Rule(re.compile(rf"^\s*module\.exports\.(?P<name>{_ID})\s*=")),
53
+ Rule(re.compile(rf"^\s*exports\.(?P<name>{_ID})\s*=")),
54
+ Rule(
55
+ re.compile(
56
+ rf"(?:app|router|api|server|route)\s*\.\s*(?P<method>get|post|put|patch|delete|head|options|all|use)"
57
+ r"\s*\(\s*['\"`](?P<name>[^'\"`]+)['\"`]"
58
+ ),
59
+ kind="route",
60
+ method_group="method",
61
+ ),
62
+ ),
63
+ imports=(
64
+ re.compile(r"""^\s*import\s+(?:[^'"]*\s+from\s+)?['"](?P<mod>[^'"]+)['"]"""),
65
+ re.compile(r"""^\s*export\s+[^'"]*\s+from\s+['"](?P<mod>[^'"]+)['"]"""),
66
+ re.compile(r"""require\(\s*['"](?P<mod>[^'"]+)['"]\s*\)"""),
67
+ ),
68
+ )
69
+
70
+ # --------------------------------------------------------------------------
71
+ # Go
72
+ # --------------------------------------------------------------------------
73
+
74
+ _GO = LangRules(
75
+ rules=(
76
+ Rule(re.compile(r"^func\s+(?P<name>[A-Za-z_][A-Za-z0-9_]*)\s*\(")),
77
+ Rule(re.compile(r"^func\s+\([^)]*\)\s*(?P<name>[A-Za-z_][A-Za-z0-9_]*)\s*\(")),
78
+ Rule(re.compile(r"^type\s+(?P<name>[A-Za-z_][A-Za-z0-9_]*)\s+(?:struct|interface|func|\[|map|chan|\*?[A-Za-z])")),
79
+ Rule(re.compile(r"^(?:const|var)\s+(?P<name>[A-Z][A-Za-z0-9_]*)\s")),
80
+ Rule(
81
+ re.compile(
82
+ r"""\.\s*(?P<method>Get|Post|Put|Patch|Delete|Head|Handle|HandleFunc)\s*\(\s*"(?P<name>[^"]+)\""""
83
+ ),
84
+ kind="route",
85
+ method_group="method",
86
+ ),
87
+ ),
88
+ imports=(re.compile(r"""^\s*(?:[A-Za-z_.]+\s+)?"(?P<mod>[^"]+)"\s*$"""),),
89
+ )
90
+
91
+ # --------------------------------------------------------------------------
92
+ # Rust
93
+ # --------------------------------------------------------------------------
94
+
95
+ _RUST = LangRules(
96
+ rules=(
97
+ Rule(re.compile(r"^\s*pub(?:\([^)]*\))?\s+(?:async\s+)?(?:unsafe\s+)?fn\s+(?P<name>[A-Za-z_][A-Za-z0-9_]*)")),
98
+ Rule(re.compile(r"^\s*pub(?:\([^)]*\))?\s+(?:struct|enum|trait|union)\s+(?P<name>[A-Za-z_][A-Za-z0-9_]*)")),
99
+ Rule(re.compile(r"^\s*pub(?:\([^)]*\))?\s+(?:const|static)\s+(?P<name>[A-Za-z_][A-Za-z0-9_]*)")),
100
+ Rule(re.compile(r"^\s*pub(?:\([^)]*\))?\s+type\s+(?P<name>[A-Za-z_][A-Za-z0-9_]*)")),
101
+ Rule(re.compile(r"^\s*(?:pub\s+)?mod\s+(?P<name>[A-Za-z_][A-Za-z0-9_]*)")),
102
+ ),
103
+ imports=(re.compile(r"^\s*use\s+(?P<mod>[A-Za-z_][A-Za-z0-9_:]*)"),),
104
+ )
105
+
106
+ # --------------------------------------------------------------------------
107
+ # JVM and .NET family — Java, Kotlin, C#, Scala, Swift, Dart
108
+ # --------------------------------------------------------------------------
109
+
110
+ _JVM = LangRules(
111
+ rules=(
112
+ Rule(
113
+ re.compile(
114
+ r"^\s*(?:public|internal|open|sealed|abstract|final|data|static|\s)*"
115
+ r"(?:class|interface|enum|record|struct|object|trait|protocol|actor)\s+"
116
+ r"(?P<name>[A-Za-z_][A-Za-z0-9_]*)"
117
+ )
118
+ ),
119
+ Rule(
120
+ re.compile(
121
+ r"^\s*(?:public|internal|open|override|suspend|static|final|async|\s)+"
122
+ r"(?:[A-Za-z_][A-Za-z0-9_<>,\[\]\.\?]*\s+)?"
123
+ r"(?P<name>[A-Za-z_][A-Za-z0-9_]*)\s*\([^;]*\)\s*[{:]"
124
+ )
125
+ ),
126
+ Rule(re.compile(r"^\s*(?:public\s+|internal\s+)?fun\s+(?P<name>[A-Za-z_][A-Za-z0-9_]*)\s*\(")),
127
+ Rule(re.compile(r"^\s*(?:public\s+)?func\s+(?P<name>[A-Za-z_][A-Za-z0-9_]*)\s*\(")),
128
+ Rule(
129
+ re.compile(
130
+ r"""@(?P<method>Get|Post|Put|Patch|Delete|Request)Mapping\s*\(\s*(?:value\s*=\s*)?["'](?P<name>[^"']+)["']"""
131
+ ),
132
+ kind="route",
133
+ method_group="method",
134
+ ),
135
+ Rule(
136
+ re.compile(
137
+ r"""\[Http(?P<method>Get|Post|Put|Patch|Delete)\s*\(\s*["'](?P<name>[^"']+)["']"""
138
+ ),
139
+ kind="route",
140
+ method_group="method",
141
+ ),
142
+ ),
143
+ imports=(
144
+ re.compile(r"^\s*import\s+(?:static\s+)?(?P<mod>[A-Za-z_][A-Za-z0-9_.]*)"),
145
+ re.compile(r"^\s*using\s+(?P<mod>[A-Za-z_][A-Za-z0-9_.]*)\s*;"),
146
+ ),
147
+ )
148
+
149
+ # --------------------------------------------------------------------------
150
+ # Ruby / PHP / Elixir / Lua / shell — declaration keywords, one per line
151
+ # --------------------------------------------------------------------------
152
+
153
+ _RUBY = LangRules(
154
+ rules=(
155
+ Rule(re.compile(r"^\s*(?:class|module)\s+(?P<name>[A-Z][A-Za-z0-9_:]*)")),
156
+ Rule(re.compile(r"^\s*def\s+(?P<name>[a-zA-Z_][A-Za-z0-9_?!.]*)")),
157
+ Rule(
158
+ re.compile(
159
+ r"""^\s*(?P<method>get|post|put|patch|delete|resources?)\s+['"](?P<name>[^'"]+)['"]"""
160
+ ),
161
+ kind="route",
162
+ method_group="method",
163
+ ),
164
+ ),
165
+ imports=(re.compile(r"""^\s*require(?:_relative)?\s+['"](?P<mod>[^'"]+)['"]"""),),
166
+ line_comment=("#",),
167
+ block_comment=None,
168
+ )
169
+
170
+ _PHP = LangRules(
171
+ rules=(
172
+ Rule(re.compile(r"^\s*(?:abstract\s+|final\s+)?(?:class|interface|trait|enum)\s+(?P<name>[A-Za-z_][A-Za-z0-9_]*)")),
173
+ Rule(re.compile(r"^\s*(?:public\s+|private\s+|protected\s+|static\s+)*function\s+(?P<name>[A-Za-z_][A-Za-z0-9_]*)\s*\(")),
174
+ Rule(
175
+ re.compile(
176
+ r"""Route::(?P<method>get|post|put|patch|delete|any)\s*\(\s*['"](?P<name>[^'"]+)['"]"""
177
+ ),
178
+ kind="route",
179
+ method_group="method",
180
+ ),
181
+ ),
182
+ imports=(re.compile(r"^\s*use\s+(?P<mod>[A-Za-z_\\][A-Za-z0-9_\\]*)"),),
183
+ line_comment=("//", "#"),
184
+ )
185
+
186
+ _ELIXIR = LangRules(
187
+ rules=(
188
+ Rule(re.compile(r"^\s*defmodule\s+(?P<name>[A-Z][A-Za-z0-9_.]*)")),
189
+ Rule(re.compile(r"^\s*def(?:p)?\s+(?P<name>[a-z_][A-Za-z0-9_?!]*)")),
190
+ Rule(
191
+ re.compile(r"""^\s*(?P<method>get|post|put|patch|delete)\s+"(?P<name>[^"]+)\""""),
192
+ kind="route",
193
+ method_group="method",
194
+ ),
195
+ ),
196
+ imports=(re.compile(r"^\s*(?:import|alias|use)\s+(?P<mod>[A-Z][A-Za-z0-9_.]*)"),),
197
+ line_comment=("#",),
198
+ block_comment=None,
199
+ )
200
+
201
+ _LUA = LangRules(
202
+ rules=(Rule(re.compile(r"^\s*(?:local\s+)?function\s+(?P<name>[A-Za-z_][A-Za-z0-9_.:]*)")),),
203
+ imports=(re.compile(r"""require\s*\(?\s*['"](?P<mod>[^'"]+)['"]"""),),
204
+ line_comment=("--",),
205
+ block_comment=None,
206
+ )
207
+
208
+ _SHELL = LangRules(
209
+ rules=(
210
+ Rule(re.compile(r"^\s*(?:function\s+)?(?P<name>[A-Za-z_][A-Za-z0-9_]*)\s*\(\s*\)\s*\{")),
211
+ ),
212
+ line_comment=("#",),
213
+ block_comment=None,
214
+ )
215
+
216
+ _C = LangRules(
217
+ rules=(
218
+ Rule(re.compile(r"^\s*(?:typedef\s+)?(?:struct|enum|union)\s+(?P<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{")),
219
+ Rule(
220
+ re.compile(
221
+ r"^[A-Za-z_][A-Za-z0-9_\s\*]*?\b(?P<name>[A-Za-z_][A-Za-z0-9_]*)\s*\([^;]*\)\s*\{"
222
+ )
223
+ ),
224
+ Rule(re.compile(r"^\s*#define\s+(?P<name>[A-Z_][A-Z0-9_]*)")),
225
+ ),
226
+ imports=(re.compile(r'^\s*#include\s+[<"](?P<mod>[^>"]+)[>"]'),),
227
+ )
228
+
229
+ RULES: dict[str, LangRules] = {
230
+ "javascript": _JSTS,
231
+ "typescript": _JSTS,
232
+ "vue": _JSTS,
233
+ "svelte": _JSTS,
234
+ "go": _GO,
235
+ "rust": _RUST,
236
+ "java": _JVM,
237
+ "kotlin": _JVM,
238
+ "csharp": _JVM,
239
+ "scala": _JVM,
240
+ "swift": _JVM,
241
+ "dart": _JVM,
242
+ "objc": _C,
243
+ "ruby": _RUBY,
244
+ "php": _PHP,
245
+ "elixir": _ELIXIR,
246
+ "lua": _LUA,
247
+ "shell": _SHELL,
248
+ "c": _C,
249
+ "cpp": _C,
250
+ }
251
+
252
+
253
+ def extract(rel_path: str, source: str, language: str) -> Extraction:
254
+ out = Extraction(languages={language})
255
+ spec = RULES.get(language)
256
+ if spec is None:
257
+ return out
258
+
259
+ file_id = node_id("file", rel_path, ".")
260
+ module_id = node_id("module", rel_path, ".")
261
+ module_name = _module_name(rel_path)
262
+ out.nodes.append(Node(module_id, "module", rel_path, 1, module_name))
263
+ out.edges.append(Edge(file_id, "defines", module_id))
264
+
265
+ in_block = False
266
+ seen: set[str] = set()
267
+ for lineno, raw in enumerate(source.splitlines(), start=1):
268
+ line, in_block = _strip_comments(raw, spec, in_block)
269
+ if not line.strip():
270
+ continue
271
+
272
+ for pattern in spec.imports:
273
+ m = pattern.search(line)
274
+ if m:
275
+ out.pending_refs.append((file_id, m.group("mod"), "imports"))
276
+ # A named import is a reference to a specific symbol, which is what
277
+ # makes `dependents <symbol>` answer "who uses this" rather than
278
+ # only "who imports this file".
279
+ for name in _named_specifiers(line):
280
+ out.pending_refs.append((file_id, name, "references"))
281
+
282
+ for rule in spec.rules:
283
+ m = rule.pattern.search(line)
284
+ if not m:
285
+ continue
286
+ name = m.group(rule.name_group)
287
+ if not name or name in _NOISE:
288
+ continue
289
+ if rule.kind == "route":
290
+ method = (m.group(rule.method_group) or "any").upper() if rule.method_group else "ANY"
291
+ name = f"{method} {name}"
292
+ key = f"{rule.kind}:{name}"
293
+ if key in seen:
294
+ continue
295
+ seen.add(key)
296
+ sym_id = node_id(rule.kind, rel_path, name)
297
+ out.nodes.append(
298
+ Node(sym_id, rule.kind, rel_path, lineno, name, fingerprint(line.strip()))
299
+ )
300
+ out.edges.append(Edge(module_id, "defines", sym_id))
301
+ break # one node per line; the first matching rule is the specific one
302
+
303
+ return out
304
+
305
+
306
+ # Keywords that survive a loose pattern and are never symbols.
307
+ _NOISE = {
308
+ "if", "for", "while", "switch", "catch", "return", "else", "do", "try",
309
+ "func", "function", "class", "new", "await", "typeof", "case", "with",
310
+ }
311
+
312
+
313
+ _BRACED = re.compile(r"[{(]\s*(?P<names>[^{}()]*?)\s*[})]")
314
+
315
+
316
+ def _named_specifiers(line: str) -> list[str]:
317
+ """`import { a, b as c } from '...'` → ['a', 'b']. Also Go's and Rust's braces."""
318
+ m = _BRACED.search(line)
319
+ if not m:
320
+ return []
321
+ out: list[str] = []
322
+ for part in m.group("names").split(","):
323
+ token = part.strip()
324
+ if not token or token in ("*", "default"):
325
+ continue
326
+ token = re.split(r"\s+as\s+", token)[0].strip()
327
+ token = token.removeprefix("type ").strip()
328
+ if re.fullmatch(_ID, token):
329
+ out.append(token)
330
+ return out
331
+
332
+
333
+ def _module_name(rel_path: str) -> str:
334
+ stem = rel_path.rsplit("/", 1)[-1]
335
+ return stem.rsplit(".", 1)[0]
336
+
337
+
338
+ def _strip_comments(raw: str, spec: LangRules, in_block: bool) -> tuple[str, bool]:
339
+ """Blank out comment content without disturbing line numbering."""
340
+ line = raw
341
+ if spec.block_comment:
342
+ open_tok, close_tok = spec.block_comment
343
+ if in_block:
344
+ end = line.find(close_tok)
345
+ if end == -1:
346
+ return "", True
347
+ line = " " * (end + len(close_tok)) + line[end + len(close_tok) :]
348
+ in_block = False
349
+ start = line.find(open_tok)
350
+ while start != -1:
351
+ end = line.find(close_tok, start + len(open_tok))
352
+ if end == -1:
353
+ line = line[:start]
354
+ return line, True
355
+ line = line[:start] + " " * (end + len(close_tok) - start) + line[end + len(close_tok) :]
356
+ start = line.find(open_tok)
357
+ stripped = line.lstrip()
358
+ for marker in spec.line_comment:
359
+ if stripped.startswith(marker):
360
+ return "", in_block
361
+ return line, in_block
@@ -0,0 +1,154 @@
1
+ """Python, parsed with the standard library's syntax tree.
2
+
3
+ Exact rather than scanned: every symbol below is a real definition, every import
4
+ edge is a real import, and a file that does not parse produces no symbols and says
5
+ so rather than producing plausible ones.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import ast
11
+
12
+ from ..model import Edge, Extraction, Node, fingerprint, node_id
13
+
14
+ # Names a route decorator can carry. Recognising these is what puts an HTTP route
15
+ # on the map for the framework families that actually appear in Python services.
16
+ _ROUTE_DECORATORS = {
17
+ "route", "get", "post", "put", "patch", "delete", "head", "options",
18
+ "websocket", "api_route",
19
+ }
20
+ _HTTP_METHODS = {"get", "post", "put", "patch", "delete", "head", "options", "websocket"}
21
+
22
+
23
+ def extract(rel_path: str, source: str) -> Extraction:
24
+ out = Extraction(languages={"python"})
25
+ file_id = node_id("file", rel_path, ".")
26
+ module_name = rel_path[:-3].replace("/", ".").removesuffix(".__init__")
27
+
28
+ try:
29
+ tree = ast.parse(source, filename=rel_path)
30
+ except SyntaxError:
31
+ # No nodes for a file we could not parse. A missing symbol is a visible
32
+ # gap; an invented one is a fact-shaped guess.
33
+ return out
34
+
35
+ module_id = node_id("module", rel_path, ".")
36
+ out.nodes.append(Node(module_id, "module", rel_path, 1, module_name))
37
+ out.edges.append(Edge(file_id, "defines", module_id))
38
+
39
+ for node in tree.body:
40
+ _visit_top(node, rel_path, module_id, out, prefix="")
41
+
42
+ for node in ast.walk(tree):
43
+ if isinstance(node, (ast.Import, ast.ImportFrom)):
44
+ _imports(node, file_id, out)
45
+ return out
46
+
47
+
48
+ def _visit_top(node: ast.AST, rel_path: str, module_id: str, out: Extraction, prefix: str) -> None:
49
+ if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
50
+ name = prefix + node.name
51
+ sym_id = _emit(node, name, rel_path, module_id, out, _signature(node))
52
+ _routes(node, rel_path, sym_id, out)
53
+ _body_refs(node, sym_id, out)
54
+
55
+ elif isinstance(node, ast.ClassDef):
56
+ name = prefix + node.name
57
+ bases = ", ".join(_expr(b) for b in node.bases)
58
+ sym_id = _emit(node, name, rel_path, module_id, out, f"class {node.name}({bases})")
59
+ for child in node.body:
60
+ if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
61
+ # Methods are public surface; nesting stops at one level, which is
62
+ # where the value stops and the churn starts.
63
+ if not child.name.startswith("_") or child.name == "__init__":
64
+ _visit_top(child, rel_path, module_id, out, prefix=f"{name}.")
65
+
66
+ elif isinstance(node, ast.Assign):
67
+ for target in node.targets:
68
+ if isinstance(target, ast.Name) and target.id.isupper():
69
+ name = prefix + target.id
70
+ _emit(node, name, rel_path, module_id, out, f"{target.id} = ...")
71
+
72
+ elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
73
+ if node.target.id.isupper():
74
+ _emit(node, prefix + node.target.id, rel_path, module_id, out, f"{node.target.id}: ...")
75
+
76
+
77
+ def _emit(node: ast.AST, name: str, rel_path: str, module_id: str, out: Extraction, sig: str) -> str:
78
+ sym_id = node_id("symbol", rel_path, name)
79
+ line = getattr(node, "lineno", 1)
80
+ out.nodes.append(Node(sym_id, "symbol", rel_path, line, name, fingerprint(sig)))
81
+ out.edges.append(Edge(module_id, "defines", sym_id))
82
+ return sym_id
83
+
84
+
85
+ def _signature(node: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
86
+ args = [a.arg for a in node.args.posonlyargs + node.args.args]
87
+ if node.args.vararg:
88
+ args.append("*" + node.args.vararg.arg)
89
+ args += [a.arg for a in node.args.kwonlyargs]
90
+ if node.args.kwarg:
91
+ args.append("**" + node.args.kwarg.arg)
92
+ prefix = "async def" if isinstance(node, ast.AsyncFunctionDef) else "def"
93
+ returns = f" -> {_expr(node.returns)}" if node.returns is not None else ""
94
+ return f"{prefix} {node.name}({', '.join(args)}){returns}"
95
+
96
+
97
+ def _routes(node: ast.FunctionDef | ast.AsyncFunctionDef, rel_path: str, sym_id: str, out: Extraction) -> None:
98
+ """Flask, FastAPI, Django-ninja and friends all decorate with a path literal."""
99
+ for dec in node.decorator_list:
100
+ if not isinstance(dec, ast.Call):
101
+ continue
102
+ attr = dec.func
103
+ if not isinstance(attr, ast.Attribute) or attr.attr not in _ROUTE_DECORATORS:
104
+ continue
105
+ path = None
106
+ for arg in dec.args:
107
+ if isinstance(arg, ast.Constant) and isinstance(arg.value, str):
108
+ path = arg.value
109
+ break
110
+ if path is None:
111
+ continue
112
+ method = attr.attr.upper() if attr.attr in _HTTP_METHODS else "ANY"
113
+ name = f"{method} {path}"
114
+ route_id = node_id("route", rel_path, name)
115
+ out.nodes.append(Node(route_id, "route", rel_path, dec.lineno, name, fingerprint(name)))
116
+ out.edges.append(Edge(route_id, "exposes", sym_id))
117
+
118
+
119
+ def _body_refs(node: ast.AST, sym_id: str, out: Extraction) -> None:
120
+ """Called names, resolved against the repository index after the walk."""
121
+ for child in ast.walk(node):
122
+ if isinstance(child, ast.Call):
123
+ func = child.func
124
+ if isinstance(func, ast.Name):
125
+ out.pending_refs.append((sym_id, func.id, "references"))
126
+ elif isinstance(func, ast.Attribute):
127
+ out.pending_refs.append((sym_id, func.attr, "references"))
128
+
129
+
130
+ def _imports(node: ast.Import | ast.ImportFrom, file_id: str, out: Extraction) -> None:
131
+ if isinstance(node, ast.Import):
132
+ for alias in node.names:
133
+ out.pending_refs.append((file_id, alias.name, "imports"))
134
+ elif node.module and not node.level:
135
+ out.pending_refs.append((file_id, node.module, "imports"))
136
+ for alias in node.names:
137
+ out.pending_refs.append((file_id, f"{node.module}.{alias.name}", "imports"))
138
+ elif node.level:
139
+ # A relative import resolves against this file's own package, which the
140
+ # resolver knows and this pass does not.
141
+ base = node.module or ""
142
+ out.pending_refs.append((file_id, "." * node.level + base, "imports"))
143
+ for alias in node.names:
144
+ joined = f"{base}.{alias.name}" if base else alias.name
145
+ out.pending_refs.append((file_id, "." * node.level + joined, "imports"))
146
+
147
+
148
+ def _expr(node: ast.AST | None) -> str:
149
+ if node is None:
150
+ return ""
151
+ try:
152
+ return ast.unparse(node)
153
+ except Exception: # pragma: no cover - unparse covers everything we emit
154
+ return type(node).__name__
@@ -0,0 +1,86 @@
1
+ """SQL: tables, and the migrations that create them.
2
+
3
+ Tables are first-class nodes because a task that touches one needs to find it, and
4
+ because a migration file is the one place a schema decision is written down. A file
5
+ under a migrations directory emits a `migrates` edge to every table it names, which
6
+ is what makes "which migration created this table" a query rather than a grep.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import re
12
+
13
+ from ..model import Edge, Extraction, Node, fingerprint, node_id
14
+
15
+ _CREATE_TABLE = re.compile(
16
+ r"create\s+(?:or\s+replace\s+)?(?:unlogged\s+|temp(?:orary)?\s+)?table\s+"
17
+ r"(?:if\s+not\s+exists\s+)?[`\"\[]?(?P<name>[A-Za-z_][A-Za-z0-9_.]*)[`\"\]]?",
18
+ re.IGNORECASE,
19
+ )
20
+ _ALTER_TABLE = re.compile(
21
+ r"alter\s+table\s+(?:if\s+exists\s+)?[`\"\[]?(?P<name>[A-Za-z_][A-Za-z0-9_.]*)[`\"\]]?",
22
+ re.IGNORECASE,
23
+ )
24
+ _DROP_TABLE = re.compile(
25
+ r"drop\s+table\s+(?:if\s+exists\s+)?[`\"\[]?(?P<name>[A-Za-z_][A-Za-z0-9_.]*)[`\"\]]?",
26
+ re.IGNORECASE,
27
+ )
28
+ _CREATE_INDEX = re.compile(
29
+ r"create\s+(?:unique\s+)?index\s+(?:concurrently\s+)?(?:if\s+not\s+exists\s+)?"
30
+ r"[`\"\[]?(?P<name>[A-Za-z_][A-Za-z0-9_.]*)[`\"\]]?",
31
+ re.IGNORECASE,
32
+ )
33
+ _VIEW = re.compile(
34
+ r"create\s+(?:or\s+replace\s+)?(?:materialized\s+)?view\s+"
35
+ r"(?:if\s+not\s+exists\s+)?[`\"\[]?(?P<name>[A-Za-z_][A-Za-z0-9_.]*)[`\"\]]?",
36
+ re.IGNORECASE,
37
+ )
38
+
39
+ _MIGRATION_DIRS = ("migrations/", "migrate/", "db/migrate/", "alembic/versions/", "sql/migrations/")
40
+
41
+
42
+ def extract(rel_path: str, source: str) -> Extraction:
43
+ out = Extraction(languages={"sql"})
44
+ file_id = node_id("file", rel_path, ".")
45
+ is_migration = any(part in rel_path.lower() for part in _MIGRATION_DIRS)
46
+
47
+ for lineno, raw in enumerate(source.splitlines(), start=1):
48
+ line = raw.split("--", 1)[0]
49
+ if not line.strip():
50
+ continue
51
+
52
+ for pattern, kind in ((_CREATE_TABLE, "table"), (_VIEW, "table")):
53
+ m = pattern.search(line)
54
+ if m:
55
+ _emit_table(out, m.group("name"), rel_path, lineno, line, file_id, defines=True)
56
+
57
+ for pattern in (_ALTER_TABLE, _DROP_TABLE):
58
+ m = pattern.search(line)
59
+ if m:
60
+ _emit_table(out, m.group("name"), rel_path, lineno, line, file_id, defines=False)
61
+
62
+ m = _CREATE_INDEX.search(line)
63
+ if m:
64
+ name = m.group("name")
65
+ sym_id = node_id("symbol", rel_path, name)
66
+ out.nodes.append(
67
+ Node(sym_id, "symbol", rel_path, lineno, name, fingerprint(line.strip()))
68
+ )
69
+ out.edges.append(Edge(file_id, "defines", sym_id))
70
+
71
+ if is_migration:
72
+ for node in list(out.nodes):
73
+ if node.kind == "table":
74
+ out.edges.append(Edge(file_id, "migrates", node.id))
75
+ return out
76
+
77
+
78
+ def _emit_table(
79
+ out: Extraction, name: str, rel_path: str, lineno: int, line: str, file_id: str, defines: bool
80
+ ) -> None:
81
+ table_id = node_id("table", rel_path, name)
82
+ if defines:
83
+ out.nodes.append(Node(table_id, "table", rel_path, lineno, name, fingerprint(line.strip())))
84
+ out.edges.append(Edge(file_id, "defines", table_id))
85
+ else:
86
+ out.pending_refs.append((file_id, name, "references"))