featmap 0.1.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.

Potentially problematic release.


This version of featmap might be problematic. Click here for more details.

Files changed (130) hide show
  1. featmap-0.1.0.dist-info/METADATA +129 -0
  2. featmap-0.1.0.dist-info/RECORD +130 -0
  3. featmap-0.1.0.dist-info/WHEEL +5 -0
  4. featmap-0.1.0.dist-info/entry_points.txt +2 -0
  5. featmap-0.1.0.dist-info/licenses/LICENSE +24 -0
  6. featmap-0.1.0.dist-info/licenses/fmap/vendor/typescript/LICENSE.txt +55 -0
  7. featmap-0.1.0.dist-info/licenses/fmap/vendor/typescript/ThirdPartyNoticeText.txt +193 -0
  8. featmap-0.1.0.dist-info/top_level.txt +1 -0
  9. fmap/__init__.py +1 -0
  10. fmap/__main__.py +3 -0
  11. fmap/axum.py +485 -0
  12. fmap/cache.py +25 -0
  13. fmap/cli.py +907 -0
  14. fmap/goext/go.mod +3 -0
  15. fmap/goext/main.go +547 -0
  16. fmap/goext.py +43 -0
  17. fmap/graph.py +920 -0
  18. fmap/impact.py +171 -0
  19. fmap/index.py +66 -0
  20. fmap/pyx.py +1133 -0
  21. fmap/routes.py +163 -0
  22. fmap/rsx.py +381 -0
  23. fmap/scip.py +80 -0
  24. fmap/trace_site.py +63 -0
  25. fmap/tsx.cjs +1258 -0
  26. fmap/tsx.py +98 -0
  27. fmap/vendor/typescript/LICENSE.txt +55 -0
  28. fmap/vendor/typescript/ThirdPartyNoticeText.txt +193 -0
  29. fmap/vendor/typescript/lib/lib.d.ts +22 -0
  30. fmap/vendor/typescript/lib/lib.decorators.d.ts +384 -0
  31. fmap/vendor/typescript/lib/lib.decorators.legacy.d.ts +22 -0
  32. fmap/vendor/typescript/lib/lib.dom.asynciterable.d.ts +41 -0
  33. fmap/vendor/typescript/lib/lib.dom.d.ts +39429 -0
  34. fmap/vendor/typescript/lib/lib.dom.iterable.d.ts +571 -0
  35. fmap/vendor/typescript/lib/lib.es2015.collection.d.ts +147 -0
  36. fmap/vendor/typescript/lib/lib.es2015.core.d.ts +597 -0
  37. fmap/vendor/typescript/lib/lib.es2015.d.ts +28 -0
  38. fmap/vendor/typescript/lib/lib.es2015.generator.d.ts +77 -0
  39. fmap/vendor/typescript/lib/lib.es2015.iterable.d.ts +605 -0
  40. fmap/vendor/typescript/lib/lib.es2015.promise.d.ts +81 -0
  41. fmap/vendor/typescript/lib/lib.es2015.proxy.d.ts +128 -0
  42. fmap/vendor/typescript/lib/lib.es2015.reflect.d.ts +144 -0
  43. fmap/vendor/typescript/lib/lib.es2015.symbol.d.ts +46 -0
  44. fmap/vendor/typescript/lib/lib.es2015.symbol.wellknown.d.ts +326 -0
  45. fmap/vendor/typescript/lib/lib.es2016.array.include.d.ts +116 -0
  46. fmap/vendor/typescript/lib/lib.es2016.d.ts +21 -0
  47. fmap/vendor/typescript/lib/lib.es2016.full.d.ts +23 -0
  48. fmap/vendor/typescript/lib/lib.es2016.intl.d.ts +31 -0
  49. fmap/vendor/typescript/lib/lib.es2017.arraybuffer.d.ts +21 -0
  50. fmap/vendor/typescript/lib/lib.es2017.d.ts +26 -0
  51. fmap/vendor/typescript/lib/lib.es2017.date.d.ts +31 -0
  52. fmap/vendor/typescript/lib/lib.es2017.full.d.ts +23 -0
  53. fmap/vendor/typescript/lib/lib.es2017.intl.d.ts +44 -0
  54. fmap/vendor/typescript/lib/lib.es2017.object.d.ts +49 -0
  55. fmap/vendor/typescript/lib/lib.es2017.sharedmemory.d.ts +135 -0
  56. fmap/vendor/typescript/lib/lib.es2017.string.d.ts +45 -0
  57. fmap/vendor/typescript/lib/lib.es2017.typedarrays.d.ts +53 -0
  58. fmap/vendor/typescript/lib/lib.es2018.asyncgenerator.d.ts +77 -0
  59. fmap/vendor/typescript/lib/lib.es2018.asynciterable.d.ts +53 -0
  60. fmap/vendor/typescript/lib/lib.es2018.d.ts +24 -0
  61. fmap/vendor/typescript/lib/lib.es2018.full.d.ts +24 -0
  62. fmap/vendor/typescript/lib/lib.es2018.intl.d.ts +83 -0
  63. fmap/vendor/typescript/lib/lib.es2018.promise.d.ts +30 -0
  64. fmap/vendor/typescript/lib/lib.es2018.regexp.d.ts +37 -0
  65. fmap/vendor/typescript/lib/lib.es2019.array.d.ts +79 -0
  66. fmap/vendor/typescript/lib/lib.es2019.d.ts +24 -0
  67. fmap/vendor/typescript/lib/lib.es2019.full.d.ts +24 -0
  68. fmap/vendor/typescript/lib/lib.es2019.intl.d.ts +23 -0
  69. fmap/vendor/typescript/lib/lib.es2019.object.d.ts +33 -0
  70. fmap/vendor/typescript/lib/lib.es2019.string.d.ts +37 -0
  71. fmap/vendor/typescript/lib/lib.es2019.symbol.d.ts +24 -0
  72. fmap/vendor/typescript/lib/lib.es2020.bigint.d.ts +765 -0
  73. fmap/vendor/typescript/lib/lib.es2020.d.ts +27 -0
  74. fmap/vendor/typescript/lib/lib.es2020.date.d.ts +42 -0
  75. fmap/vendor/typescript/lib/lib.es2020.full.d.ts +24 -0
  76. fmap/vendor/typescript/lib/lib.es2020.intl.d.ts +474 -0
  77. fmap/vendor/typescript/lib/lib.es2020.number.d.ts +28 -0
  78. fmap/vendor/typescript/lib/lib.es2020.promise.d.ts +47 -0
  79. fmap/vendor/typescript/lib/lib.es2020.sharedmemory.d.ts +99 -0
  80. fmap/vendor/typescript/lib/lib.es2020.string.d.ts +44 -0
  81. fmap/vendor/typescript/lib/lib.es2020.symbol.wellknown.d.ts +41 -0
  82. fmap/vendor/typescript/lib/lib.es2021.d.ts +23 -0
  83. fmap/vendor/typescript/lib/lib.es2021.full.d.ts +24 -0
  84. fmap/vendor/typescript/lib/lib.es2021.intl.d.ts +166 -0
  85. fmap/vendor/typescript/lib/lib.es2021.promise.d.ts +48 -0
  86. fmap/vendor/typescript/lib/lib.es2021.string.d.ts +33 -0
  87. fmap/vendor/typescript/lib/lib.es2021.weakref.d.ts +78 -0
  88. fmap/vendor/typescript/lib/lib.es2022.array.d.ts +121 -0
  89. fmap/vendor/typescript/lib/lib.es2022.d.ts +25 -0
  90. fmap/vendor/typescript/lib/lib.es2022.error.d.ts +75 -0
  91. fmap/vendor/typescript/lib/lib.es2022.full.d.ts +24 -0
  92. fmap/vendor/typescript/lib/lib.es2022.intl.d.ts +145 -0
  93. fmap/vendor/typescript/lib/lib.es2022.object.d.ts +26 -0
  94. fmap/vendor/typescript/lib/lib.es2022.regexp.d.ts +39 -0
  95. fmap/vendor/typescript/lib/lib.es2022.string.d.ts +25 -0
  96. fmap/vendor/typescript/lib/lib.es2023.array.d.ts +924 -0
  97. fmap/vendor/typescript/lib/lib.es2023.collection.d.ts +21 -0
  98. fmap/vendor/typescript/lib/lib.es2023.d.ts +22 -0
  99. fmap/vendor/typescript/lib/lib.es2023.full.d.ts +24 -0
  100. fmap/vendor/typescript/lib/lib.es2023.intl.d.ts +56 -0
  101. fmap/vendor/typescript/lib/lib.es2024.arraybuffer.d.ts +65 -0
  102. fmap/vendor/typescript/lib/lib.es2024.collection.d.ts +29 -0
  103. fmap/vendor/typescript/lib/lib.es2024.d.ts +26 -0
  104. fmap/vendor/typescript/lib/lib.es2024.full.d.ts +24 -0
  105. fmap/vendor/typescript/lib/lib.es2024.object.d.ts +29 -0
  106. fmap/vendor/typescript/lib/lib.es2024.promise.d.ts +35 -0
  107. fmap/vendor/typescript/lib/lib.es2024.regexp.d.ts +25 -0
  108. fmap/vendor/typescript/lib/lib.es2024.sharedmemory.d.ts +68 -0
  109. fmap/vendor/typescript/lib/lib.es2024.string.d.ts +29 -0
  110. fmap/vendor/typescript/lib/lib.es5.d.ts +4601 -0
  111. fmap/vendor/typescript/lib/lib.es6.d.ts +23 -0
  112. fmap/vendor/typescript/lib/lib.esnext.array.d.ts +35 -0
  113. fmap/vendor/typescript/lib/lib.esnext.collection.d.ts +96 -0
  114. fmap/vendor/typescript/lib/lib.esnext.d.ts +29 -0
  115. fmap/vendor/typescript/lib/lib.esnext.decorators.d.ts +28 -0
  116. fmap/vendor/typescript/lib/lib.esnext.disposable.d.ts +193 -0
  117. fmap/vendor/typescript/lib/lib.esnext.error.d.ts +24 -0
  118. fmap/vendor/typescript/lib/lib.esnext.float16.d.ts +445 -0
  119. fmap/vendor/typescript/lib/lib.esnext.full.d.ts +24 -0
  120. fmap/vendor/typescript/lib/lib.esnext.intl.d.ts +21 -0
  121. fmap/vendor/typescript/lib/lib.esnext.iterator.d.ts +148 -0
  122. fmap/vendor/typescript/lib/lib.esnext.promise.d.ts +34 -0
  123. fmap/vendor/typescript/lib/lib.esnext.sharedmemory.d.ts +25 -0
  124. fmap/vendor/typescript/lib/lib.scripthost.d.ts +322 -0
  125. fmap/vendor/typescript/lib/lib.webworker.asynciterable.d.ts +41 -0
  126. fmap/vendor/typescript/lib/lib.webworker.d.ts +13150 -0
  127. fmap/vendor/typescript/lib/lib.webworker.importscripts.d.ts +23 -0
  128. fmap/vendor/typescript/lib/lib.webworker.iterable.d.ts +340 -0
  129. fmap/vendor/typescript/lib/typescript.js +200276 -0
  130. fmap/vendor/typescript/package.json +120 -0
fmap/graph.py ADDED
@@ -0,0 +1,920 @@
1
+ """Build, rules, serialization and validation (spec §4, §5)."""
2
+ import fnmatch
3
+ import functools
4
+ import hashlib
5
+ from contextlib import contextmanager
6
+ import re
7
+ import json
8
+ import os
9
+ import shlex
10
+ import shutil
11
+ import subprocess
12
+ import sys
13
+ import tempfile
14
+ import time
15
+ import tomllib
16
+
17
+ from . import __version__, cache, goext, pyx, routes, rsx, tsx
18
+
19
+ JS_EXT = {".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"}
20
+ MISSING_TOOL_PATH_LIMIT = 3
21
+ SOURCE_EXT = {".py", ".go", ".rs"} | JS_EXT
22
+ PY_NO_EXTRACTOR = {"flask", "django", "click", "typer", "starlette"} # spec §10.1: warn, don't guess
23
+ UNSUPPORTED_EXT = {".go", ".rs"}
24
+ RESOLVED = ("call", "dispatch", "process", "ref", "render", "impl", "http", "invoke")
25
+
26
+
27
+ def git(root, *args, check=True):
28
+ r = subprocess.run(["git", *args], cwd=root, capture_output=True, text=True)
29
+ if check and r.returncode != 0:
30
+ raise SystemExit(f"fmap: git {' '.join(args)} failed: {r.stderr.strip()}")
31
+ return r
32
+
33
+
34
+ def repo_root(cwd="."):
35
+ r = git(cwd, "rev-parse", "--show-toplevel", check=False)
36
+ if r.returncode != 0:
37
+ raise SystemExit("fmap: not inside a git repository")
38
+ return r.stdout.strip()
39
+
40
+
41
+ def remove_revision_worktree(root, directory):
42
+ revision_root = os.path.join(directory, "tree")
43
+ removed = git(root, "worktree", "remove", "--force", revision_root, check=False)
44
+ registered = git(root, "worktree", "list", "--porcelain").stdout.splitlines()
45
+ if removed.returncode and f"worktree {revision_root}" in registered:
46
+ raise ValueError("temporary revision worktree cleanup failed: " +
47
+ removed.stderr.strip().replace(revision_root, "<rev>"))
48
+ shutil.rmtree(directory)
49
+
50
+
51
+ @contextmanager
52
+ def revision_directory(root):
53
+ common = git(root, "rev-parse", "--git-common-dir").stdout.strip()
54
+ parent = os.path.abspath(os.path.join(root, common, "fmap", "rev"))
55
+ os.makedirs(parent, exist_ok=True)
56
+ with open(os.path.join(parent, "..", "rev.lock"), "a") as lock:
57
+ try:
58
+ import fcntl
59
+ fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
60
+ except (ImportError, BlockingIOError):
61
+ directory = reserve_revision_directory(root, parent, shared=False)
62
+ else:
63
+ directory = reserve_revision_directory(root, parent)
64
+ try:
65
+ yield directory
66
+ finally:
67
+ # Keep the slot locked until its worktree and owner marker are removed.
68
+ remove_revision_worktree(root, directory)
69
+
70
+
71
+ def reserve_revision_directory(root, parent, shared=True):
72
+ for name in os.listdir(parent) if shared else []:
73
+ if name != "slot" and not name.startswith("slot-") and not re.fullmatch(r"[0-9a-f]{40,64}(?:-.*)?", name):
74
+ continue
75
+ candidate = os.path.join(parent, name)
76
+ if not os.path.isdir(candidate) or os.path.islink(candidate):
77
+ continue
78
+ try:
79
+ with open(os.path.join(candidate, ".fmap-owner")) as fh:
80
+ owner = int(fh.read())
81
+ if owner > 0:
82
+ os.kill(owner, 0)
83
+ except ProcessLookupError:
84
+ # Only reclaim our marked checkout after its creating process has exited.
85
+ remove_revision_worktree(root, candidate)
86
+ except (OSError, ValueError):
87
+ pass # Unknown ownership: leave it alone and use a unique sibling.
88
+ directory = os.path.join(parent, "slot")
89
+ if shared:
90
+ try:
91
+ os.mkdir(directory)
92
+ except FileExistsError:
93
+ shared = False
94
+ if not shared:
95
+ directory = tempfile.mkdtemp(prefix="slot-", dir=parent)
96
+ with open(os.path.join(directory, ".fmap-owner"), "w") as fh:
97
+ fh.write(str(os.getpid()))
98
+ return directory
99
+
100
+
101
+ def link_revision_dependencies(root, revision_root):
102
+ for manifest in list_files(revision_root):
103
+ if os.path.basename(manifest) != "package.json":
104
+ continue
105
+ relative = os.path.join(os.path.dirname(manifest), "node_modules")
106
+ source = os.path.join(root, relative)
107
+ target = os.path.join(revision_root, relative)
108
+ if os.path.isdir(source) and not os.path.lexists(target):
109
+ os.symlink(os.path.realpath(source), target, target_is_directory=True)
110
+
111
+
112
+ def build_revision(root, rev, config=None):
113
+ """Build tracked revision files with their config (or `config`) and installed dependencies."""
114
+ git(root, "rev-parse", "--verify", f"{rev}^{{tree}}")
115
+ with revision_directory(root) as directory:
116
+ revision_root = os.path.join(directory, "tree")
117
+ try:
118
+ git(root, "-c", "core.hooksPath=/dev/null", "worktree", "add", "--detach", "--", revision_root, rev)
119
+ link_revision_dependencies(root, revision_root)
120
+ before, errors, _ = build(revision_root, config=config, use_cache=os.path.basename(directory) == "slot")
121
+ if before["meta"].get("missing_tools") or any(p["deps"] != "ok" for p in before["meta"]["programs"]):
122
+ # The fix-it hint names the working tree's featmap.toml; for a revision the cause is its imports.
123
+ raise ValueError("; ".join(e.split(" — paketi kur")[0] for e in errors) + (
124
+ " — revizyonun importları çalışma ağacında kurulu bağımlılıklarla çözülemedi"
125
+ if any(p["deps"] == "missing" for p in before["meta"]["programs"]) else ""))
126
+ return before
127
+ except (Exception, SystemExit) as error:
128
+ # Extractor diagnostics can contain absolute filenames from the checkout.
129
+ raise ValueError(str(error).replace(revision_root, "<rev>").replace(directory, "<temp>")) from error
130
+
131
+
132
+ def list_files(root, untracked=False):
133
+ args = ["ls-files", "-z", "--cached"]
134
+ if untracked:
135
+ args += ["--others", "--exclude-standard"]
136
+ out = git(root, *args).stdout.split("\0")
137
+ # deleted-but-tracked files are skipped: the build reads the working tree
138
+ return sorted({p for p in out if p and os.path.isfile(os.path.join(root, p))})
139
+
140
+
141
+ def load_config(root):
142
+ path = os.path.join(root, "featmap.toml")
143
+ if not os.path.exists(path):
144
+ return {}
145
+ with open(path, "rb") as fh:
146
+ try:
147
+ return tomllib.load(fh)
148
+ except tomllib.TOMLDecodeError as e:
149
+ raise SystemExit(f"fmap: featmap.toml: {e}")
150
+
151
+
152
+ def read(root, path):
153
+ with open(os.path.join(root, path), encoding="utf-8", errors="replace") as fh:
154
+ return fh.read()
155
+
156
+
157
+ def missing_tools(files):
158
+ """Report unavailable extractors before building a partial graph."""
159
+ missing_tool_errors = {}
160
+ requirements = (
161
+ ("node", [f for f in files if os.path.splitext(f)[1] in JS_EXT],
162
+ "Node.js >=14.17 kur: https://nodejs.org/en/download"),
163
+ ("go", [f for f in files if f.endswith(".go")],
164
+ "Go >=1.22 kur: https://go.dev/doc/install"),
165
+ ("rust-analyzer", [f for f in files if f.endswith(".rs")],
166
+ "rustup component add rust-analyzer"),
167
+ ("cargo", [f for f in files if f.endswith(".rs")],
168
+ "Rust/Cargo kur: https://rustup.rs (rustup toolchain install stable)"),
169
+ )
170
+ for tool, affected_files, install in requirements:
171
+ if not affected_files:
172
+ continue
173
+ is_available = rsx.ra_bin() if tool == "rust-analyzer" else shutil.which(tool)
174
+ if not is_available:
175
+ preview = ", ".join(sorted(affected_files)[:MISSING_TOOL_PATH_LIMIT])
176
+ if len(affected_files) > MISSING_TOOL_PATH_LIMIT:
177
+ preview += ", …"
178
+ hint = f'[[exclude]] glob = "{sorted(affected_files)[0]}" reason = "..."'
179
+ missing_tool_errors[tool] = (f"tool missing: {tool} — {len(affected_files):,} files ({preview}) — {install}"
180
+ f" ya da bilerek kapsam dışıysa `{hint}`")
181
+ return missing_tool_errors
182
+
183
+
184
+ FMAP_DIR = os.path.dirname(os.path.abspath(__file__))
185
+ RACY_NS = 2_000_000_000 # files touched this recently are hashed by content: mtime ticks are coarse
186
+
187
+
188
+ @functools.cache
189
+ def extractor_id():
190
+ """Hash of the code that shapes a graph (not the CLI): a map built by other extractor code is a different map."""
191
+ h = hashlib.sha256()
192
+ for dirpath, dirs, names in sorted(os.walk(FMAP_DIR)):
193
+ dirs[:] = sorted(d for d in dirs if d not in ("__pycache__", "vendor"))
194
+ for name in sorted(names):
195
+ if name.endswith((".py", ".cjs", ".go")) and name not in ("cli.py", "__main__.py", "trace_site.py"):
196
+ with open(os.path.join(dirpath, name), "rb") as fh:
197
+ h.update(name.encode() + b"\0" + fh.read())
198
+ return h.hexdigest()[:12]
199
+
200
+
201
+ def input_key(root, untracked):
202
+ """Everything a query graph is built from: fmap itself, tools on PATH, featmap.toml and every input file."""
203
+ h = hashlib.sha256(f"{__version__}\0{sys.version}\0{os.path.realpath(root)}\0{untracked}".encode())
204
+ for tool in ("node", "go", "rust-analyzer", "cargo"):
205
+ h.update(f"{tool}={shutil.which(tool)}\n".encode())
206
+ now = time.time_ns()
207
+ fmap_files = [os.path.join(FMAP_DIR, f) for f in sorted(os.listdir(FMAP_DIR))]
208
+ for path in fmap_files + [os.path.join(root, p) for p in ["featmap.toml"] + list_files(root, untracked)]:
209
+ try:
210
+ st = os.stat(path)
211
+ if not os.path.isfile(path):
212
+ continue
213
+ if now - st.st_mtime_ns < RACY_NS:
214
+ with open(path, "rb") as fh:
215
+ sig = hashlib.sha256(fh.read()).hexdigest()
216
+ else:
217
+ sig = f"{st.st_size}:{st.st_mtime_ns}"
218
+ except OSError:
219
+ sig = "missing"
220
+ h.update(f"{path}\0{sig}\n".encode())
221
+ return h.hexdigest()
222
+
223
+
224
+ def cached_build(root, untracked=False):
225
+ """Query path: reuse the last graph while no input changed; build() stays the source of truth.
226
+
227
+ Only complete graphs are cached: missing deps or tools depend on what is installed, not on the key.
228
+ shortcut: an in-place dependency upgrade (node_modules, Go/Cargo caches) without a lockfile change is not
229
+ in the key; delete .git/fmap/cache/graph-* or add dependency stats if that bites.
230
+ """
231
+ key = input_key(root, untracked)
232
+ slot = hashlib.sha256(f"{os.path.realpath(root)}\0{untracked}".encode()).hexdigest()[:16]
233
+ path = os.path.join(cache.cache_dir(root), f"graph-{slot}.json")
234
+ try:
235
+ with open(path) as fh:
236
+ c = json.load(fh)
237
+ if c["key"] == key:
238
+ return c["graph"], c["errors"], c["files"]
239
+ except (OSError, ValueError, KeyError):
240
+ pass
241
+ g, errors, files = build(root, untracked=untracked)
242
+ meta = g["meta"]
243
+ if not errors and not meta.get("missing_tools") and all(
244
+ p["deps"] == "ok" and not p.get("failed") for p in meta["programs"]):
245
+ with open(path + ".tmp", "w") as fh:
246
+ json.dump({"key": key, "graph": g, "errors": errors, "files": files}, fh)
247
+ os.replace(path + ".tmp", path)
248
+ return g, errors, files
249
+
250
+
251
+ def build(root, untracked=False, config=None, use_cache=True):
252
+ """Returns (graph, errors). `errors` are build-time rule problems for `check`."""
253
+ config = load_config(root) if config is None else config
254
+ files = list_files(root, untracked)
255
+ exclusions, excluded = [], set()
256
+ tracked = set(list_files(root)) if untracked and config.get("exclude") else set(files)
257
+ exclusion_errors = []
258
+ for rule in config.get("exclude", []):
259
+ pattern = rule.get("glob", "")
260
+ matches = {p for p in files if pyx.path_match(pattern, p)}
261
+ excluded.update(matches)
262
+ exclusions.append({"glob": pattern, "reason": rule.get("reason", ""), "matched": len(matches)})
263
+ if not rule.get("reason"):
264
+ exclusion_errors.append(f"exclude {pattern}: reason is required")
265
+ if not any(pyx.path_match(pattern, p) for p in tracked):
266
+ exclusion_errors.append(f"exclude glob: no tracked file matches `{pattern}`")
267
+ files = [p for p in files if p not in excluded]
268
+ sources = {p: read(root, p) for p in files if p.endswith(".py")}
269
+ proj = pyx.extract(sources, config, root)
270
+ nodes = dict(proj.nodes)
271
+ errors = exclusion_errors + list(proj.errors)
272
+ fileset = set(files)
273
+ raw_edges = list(proj.edges)
274
+ entries = list(proj.entries)
275
+ mounts = list(getattr(proj, "mounts", []))
276
+ reach, xcalls = [], []
277
+ entries += script_entries(root, files)
278
+ programs = [{"name": "python", "deps": "ok", "tool": f"python@{sys.version_info.major}.{sys.version_info.minor}"}] if sources else []
279
+ unsupported = {}
280
+ missing_tool_errors = missing_tools(files)
281
+ errors.extend(missing_tool_errors.values())
282
+
283
+ records, ts_programs = tsx.extract(root, files, config, use_cache=use_cache, excluded=excluded) if "node" not in missing_tool_errors else ([], [])
284
+ if "node" in missing_tool_errors:
285
+ for p in files:
286
+ if os.path.splitext(p)[1] in JS_EXT:
287
+ unsupported["(node yok) " + os.path.splitext(p)[1]] = unsupported.get("(node yok) " + os.path.splitext(p)[1], 0) + 1
288
+ rs_records, rs_unsupported = ([], True) if {"rust-analyzer", "cargo"} & missing_tool_errors.keys() else rsx.extract(root, files, config, excluded=excluded, use_cache=use_cache)
289
+ records += ([] if "go" in missing_tool_errors else goext.extract(root, files, config, excluded=excluded)) + rs_records
290
+ sig_nodes, http_params, used_missing = {}, {}, set()
291
+ rust_program_dirs = {os.path.dirname(r["name"]) for r in rs_records if r["t"] == "program"}
292
+ failed_files = {p for p in files if
293
+ ("node" in missing_tool_errors and os.path.splitext(p)[1] in JS_EXT) or
294
+ ("go" in missing_tool_errors and p.endswith(".go")) or
295
+ ({"rust-analyzer", "cargo"} & missing_tool_errors.keys() and p.endswith(".rs"))}
296
+ no_extractor = {b[1].split(".")[0] for syms in proj.syms.values() for b in syms.values()
297
+ if b[0] in ("imp", "mod") and b[1].split(".")[0] in PY_NO_EXTRACTOR}
298
+ for r in records:
299
+ t = r.pop("t")
300
+ if t == "node":
301
+ nodes[r.pop("id")] = {"kind": r["kind"], "file": None, "line": r["line"], "end_line": r["end_line"]}
302
+ elif t == "edge":
303
+ if r.get("sig"):
304
+ sig_nodes[r["from"] if r["kind"] == "impl" else r["to"]] = r["sig"]
305
+ r.pop("sig", None)
306
+ raw_edges.append(r)
307
+ elif t == "entry":
308
+ entries.append(r)
309
+ elif t == "mount":
310
+ mounts.append(r)
311
+ elif t == "reach":
312
+ reach.append(r)
313
+ elif t == "xcall":
314
+ xcalls.append(r)
315
+ elif t == "fw":
316
+ no_extractor.add(r["name"])
317
+ elif t == "http_client":
318
+ http_params[r["symbol"]] = {"params": r["params"], "rest": r["rest"]}
319
+ elif t == "program":
320
+ ign = lambda key, path: any(key in i and pyx.path_match(i[key], path) for i in config.get("ignore", []))
321
+ left = []
322
+ for m in r["missing"]:
323
+ hits = {k for k, i in enumerate(config.get("ignore", [])) if "missing" in i and pyx.path_match(i["missing"], m.split(": ", 1)[0])}
324
+ used_missing |= hits
325
+ if not hits:
326
+ left.append(m)
327
+ count = r["missing_count"] - (len(r["missing"]) - len(left))
328
+ # every miss ignored: same map as installed (calls through a missing module drop as external, §6.4)
329
+ deps = "ok" if r["deps"] == "missing" and count == 0 else r["deps"]
330
+ programs.append({"name": r["name"], "deps": deps, "tool": r["tool"],
331
+ **({"missing": count} if count else {}), **({"failed": r["failed"]} if r.get("failed") else {})})
332
+ if r.get("failed"): # the tool itself failed: no import to ignore (spec §6.4)
333
+ directory = os.path.dirname(r["name"])
334
+ extensions = (".go",) if r["name"] == "go" else (".rs",) if r["name"].endswith("Cargo.toml") else tuple(JS_EXT)
335
+ nested_roots = tuple(d + "/" for d in rust_program_dirs if d and
336
+ (not directory or d.startswith(directory + "/"))) if extensions == (".rs",) else ()
337
+ failed_files.update(p for p in files if p.endswith(extensions) and
338
+ (not directory or p.startswith(directory + "/")) and not p.startswith(nested_roots))
339
+ errors.append(r["failed"])
340
+ elif deps != "ok":
341
+ hint = (f'[[ignore]] missing = "{left[0].split(": ", 1)[0]}" reason = "..."' if left and ": " in left[0]
342
+ else "[[ignore]] missing = \"<dosya>\" reason = \"...\"")
343
+ errors.append(f"deps missing in {r['name']}: {count} imports (örn. " + "; ".join(left[:3])
344
+ + f") — paketi kur/bağımlılığa ekle ya da bilerek eksikse `{hint}`")
345
+ for o in r["outside"]:
346
+ if o in excluded:
347
+ continue
348
+ if not ign("untracked", o):
349
+ errors.append(f"{r['name']}: takip edilmeyen proje dosyası yükleniyor: {o} — `git add` et "
350
+ f'ya da bilerek takip edilmiyorsa `[[ignore]] untracked = "{o}" reason = "..."`')
351
+ notes = []
352
+ for k, i in enumerate(config.get("ignore", [])):
353
+ # an existing file whose imports all resolve here; a note, not an error: it depends on what this
354
+ # machine has installed (an intentionally absent dep resolves where it is installed, e.g. CI)
355
+ if ("missing" in i and k not in used_missing
356
+ and not any(pyx.path_match(i["missing"], p) for p in failed_files)
357
+ and any(pyx.path_match(i["missing"], p) for p in files)):
358
+ notes.append(f"not: ignore missing {i['missing']}: stale — no missing import is suppressed "
359
+ "(bloklamıyor; paket bu makinede kurulu olabilir)")
360
+ for nid, n in nodes.items():
361
+ if n["file"] is None:
362
+ n["file"] = nid.split(":", 1)[0]
363
+ implemented = {e["from"] for e in raw_edges if e["kind"] == "impl"}
364
+ for e in raw_edges:
365
+ if e["kind"] == "sigcall":
366
+ if e["to"] in implemented:
367
+ e["kind"] = "call"
368
+ e.pop("expr", None)
369
+ else: # interface member with no explicit implementor: we cannot follow it
370
+ e["kind"], e["to"] = "?callback", "?"
371
+ lang = lambda f: "rs" if f.endswith(".rs") else "js" if os.path.splitext(f)[1] in JS_EXT else None
372
+ methods = {} # (language, method name) -> project methods; candidates never cross languages
373
+ for nid, n in nodes.items():
374
+ if n["kind"] == "method" and lang(n["file"]):
375
+ methods.setdefault((lang(n["file"]), nid.rsplit(":", 1)[1].rsplit(".", 1)[-1]), []).append(nid)
376
+ kept = []
377
+ for e in raw_edges:
378
+ if e["kind"] == "method?" and "candidates" not in e:
379
+ cands = methods.get((lang(e["from"].split(":", 1)[0]), e["method"]))
380
+ if not cands:
381
+ continue # no project method has this name: provably not project code
382
+ e["candidates"] = sorted(cands)
383
+ kept.append(e)
384
+ raw_edges = kept
385
+ for sid, info in sig_nodes.items():
386
+ if sid in implemented and sid not in nodes:
387
+ nodes[sid] = {"kind": "signature", **info}
388
+
389
+ edges = []
390
+ for e in raw_edges:
391
+ tf = e.pop("target_file", None)
392
+ if tf is not None:
393
+ if tf not in fileset:
394
+ errors.append(f"process target {tf}: " + (exclusion_note(tf, excluded, config) or "not a tracked file"))
395
+ continue
396
+ if e["to"] not in nodes:
397
+ n = read(root, tf).count("\n") + 1
398
+ nodes[e["to"]] = {"kind": "module", "file": tf, "line": 1, "end_line": n}
399
+ edges.append(e)
400
+
401
+ edges += shell_edges(root, files, nodes)
402
+ joined = join_mounts(entries, mounts)
403
+ extra, route_programs, route_errors, route_notes = routes.external_routes(
404
+ root, files, nodes, config, joined, [e for e in edges if e["kind"] == "?route"])
405
+ joined += [e for e in extra if not TEST_PATH.search(e["at"].rsplit(":", 1)[0])]
406
+ programs += route_programs
407
+ errors += route_errors
408
+ notes += route_notes
409
+ edges = drop_proven_route_marks(edges, joined)
410
+ edges += cross_edges(root, files, nodes, joined, xcalls)
411
+ apply_ignores(edges, config)
412
+ for p in files:
413
+ ext = os.path.splitext(p)[1]
414
+ if ext in UNSUPPORTED_EXT and not (ext == ".go" and goext.go_bin()) and not (ext == ".rs" and not rs_unsupported):
415
+ unsupported[ext] = unsupported.get(ext, 0) + 1
416
+
417
+ graph = {
418
+ "version": 1,
419
+ "meta": {"fmap": __version__, "extractor": extractor_id(), "programs": programs, "unsupported": unsupported,
420
+ **({"excluded": exclusions} if exclusions else {}),
421
+ **({"missing_tools": missing_tool_errors} if missing_tool_errors else {}),
422
+ **({"entry_points_not_extracted": sorted(no_extractor)} if no_extractor else {})},
423
+ "nodes": nodes,
424
+ "edges": group_edges(edges),
425
+ "entries": group_entries(joined),
426
+ "reach": group_entries(reach),
427
+ "features": features(config),
428
+ }
429
+ graph["_excluded"] = sorted(excluded) # for check messages, never serialized
430
+ graph["_http_params"] = http_params # [[http_client]] parameter counts for validate, never serialized
431
+ graph["_notes"] = notes # non-blocking check notes, never serialized
432
+ return graph, errors, files
433
+
434
+
435
+ SH_REF = re.compile(r"(?:\$(?:[A-Za-z_]\w*|\{[A-Za-z_]\w*\})/)?([\w./-]+\.(?:py|sh|mjs|cjs|js|ts))\b")
436
+
437
+
438
+ def shell_edges(root, files, nodes):
439
+ """A tracked .sh file that names a project script runs (or sources) it: `process` edge to its <module>.
440
+ shortcut: textual, ignores control flow and variables; enough for test scripts, upgrade if it over-selects."""
441
+ fileset, edges = set(files), []
442
+ sourced, invoked = set(), set()
443
+ by_tail = {}
444
+ for f in files:
445
+ by_tail.setdefault(f.rsplit("/", 1)[-1], []).append(f)
446
+ for p in files:
447
+ if not p.endswith(".sh"):
448
+ continue
449
+ text = read(root, p)
450
+ nodes.setdefault(f"{p}:<module>", {"kind": "module", "file": p, "line": 1, "end_line": text.count("\n") + 1})
451
+ seen = set()
452
+ for i, line in enumerate(text.splitlines(), 1):
453
+ if line.lstrip().startswith("#"):
454
+ continue
455
+ for m in SH_REF.finditer(line):
456
+ ref = m.group(1).lstrip("./")
457
+ cands = [ref] if ref in fileset else [os.path.normpath(os.path.join(os.path.dirname(p), ref))]
458
+ if cands[0] not in fileset:
459
+ cands = [f for f in by_tail.get(ref.rsplit("/", 1)[-1], []) if f.endswith("/" + ref) or ref.endswith("/" + f) or f == ref]
460
+ if not cands:
461
+ continue
462
+ if len(cands) > 1:
463
+ edges.append({"from": f"{p}:<module>", "to": "?", "kind": "?process",
464
+ "at": f"{p}:{i}", "expr": m.group(0),
465
+ "candidates": sorted(f"{t}:<module>" for t in cands)})
466
+ continue
467
+ if cands[0] == p:
468
+ continue
469
+ t = cands[0]
470
+ is_source = re.search(r'''(?:^|[;&|])\s*(?:source|\.)\s+["']?$''', line[:m.start()])
471
+ (sourced if is_source else invoked).add(t)
472
+ if t in seen:
473
+ continue
474
+ seen.add(t)
475
+ if f"{t}:<module>" not in nodes:
476
+ n = read(root, t).count("\n") + 1
477
+ nodes[f"{t}:<module>"] = {"kind": "module", "file": t, "line": 1, "end_line": n}
478
+ edges.append({"from": f"{p}:<module>", "to": f"{t}:<module>", "kind": "process", "at": f"{p}:{i}"})
479
+ for p in sorted(sourced - invoked):
480
+ if p.endswith(".sh"):
481
+ nodes[f"{p}:<module>"]["sourced_only"] = True
482
+ return edges
483
+
484
+
485
+ def script_entries(root, files):
486
+ """package.json scripts -> script:<name> (nested: script:<dir>:<name>); node = a tracked file the command runs."""
487
+ fileset, out = set(files), []
488
+ for p in files:
489
+ if os.path.basename(p) != "package.json" or "/node_modules/" in "/" + p:
490
+ continue
491
+ try:
492
+ scripts = json.loads(read(root, p)).get("scripts") or {}
493
+ except (ValueError, AttributeError):
494
+ continue
495
+ d = os.path.dirname(p)
496
+ lines = read(root, p).splitlines()
497
+ for name, cmd in sorted(scripts.items()):
498
+ if not isinstance(cmd, str):
499
+ continue
500
+ line = next((i + 1 for i, l in enumerate(lines) if f'"{name}"' in l), 1)
501
+ lexer = shlex.shlex(cmd, posix=True, punctuation_chars="&|;")
502
+ lexer.whitespace_split, lexer.commenters = True, ""
503
+ try:
504
+ words = list(lexer)
505
+ except ValueError:
506
+ words = cmd.split() # preserve literal targets even in malformed shell commands
507
+ nodes = [f"{t}:<module>" for t in (os.path.normpath(os.path.join(d, w)) for w in words)
508
+ if t in fileset and os.path.splitext(t)[1] in SOURCE_EXT]
509
+ for node in nodes or [p]:
510
+ out.append({"kind": "script", "value": f"{d}:{name}" if d else name,
511
+ "node": node, "at": f"{p}:{line}"})
512
+ return out
513
+
514
+
515
+ TAURI_CMD = re.compile(r"#\[tauri::command[^\]]*\]\s*(?:(?:#\[[^\]]*\]|//[^\n]*)\s*)*"
516
+ r"(?:pub(?:\([^)]*\))?\s+)?(?:async\s+)?fn\s+(\w+)")
517
+ TAURI_REG = re.compile(r"generate_handler!\s*\[([^\]]*)\]")
518
+
519
+
520
+ def route_parts(path):
521
+ path = re.sub(r"^[a-z]+://[^/]*", "", path).split("?")[0].split("#")[0]
522
+ return [p for p in path.split("/") if p]
523
+
524
+
525
+ def route_match(route, url):
526
+ """Literal segments must be equal; a template parameter only matches a route parameter (spec §11)."""
527
+ for i, r in enumerate(route):
528
+ if r == "*":
529
+ return True
530
+ if i >= len(url):
531
+ return False
532
+ param = lambda s: s.startswith(":") or (s.startswith("{") and s.endswith("}"))
533
+ rp, up = param(r), url[i] == ":param" or (url[i].startswith("{") and url[i].endswith("}"))
534
+ if rp != up or (not rp and r != url[i]):
535
+ return False
536
+ return len(route) == len(url)
537
+
538
+
539
+ def cross_edges(root, files, nodes, entries, xcalls):
540
+ """http: fetch -> the one matching route handler; invoke: Tauri invoke -> registered #[tauri::command]."""
541
+ out = []
542
+ routes = []
543
+ for e in entries:
544
+ if e["kind"] == "route" and " " in e["value"]:
545
+ m, path = e["value"].split(" ", 1)
546
+ routes.append((m, route_parts(path), e["node"], e["value"]))
547
+ commands, registered = {}, set()
548
+ for p in files:
549
+ if not p.endswith(".rs"):
550
+ continue
551
+ text = read(root, p)
552
+ for m in TAURI_CMD.finditer(text):
553
+ # shortcut: syntactic scan of #[tauri::command] fns (no module qualname), until the Rust extractor lands
554
+ nid = f"{p}:{m.group(1)}"
555
+ line = text.count("\n", 0, m.start(1)) + 1
556
+ nodes.setdefault(nid, {"kind": "function", "file": p, "line": line, "end_line": line})
557
+ commands.setdefault(m.group(1), []).append(nid)
558
+ for m in TAURI_REG.finditer(text):
559
+ registered |= {x.split("::")[-1].strip() for x in m.group(1).split(",") if x.strip()}
560
+ for x in xcalls:
561
+ if x["kind"] == "http":
562
+ if x["value"] is None or x["method"] is None:
563
+ out.append({"from": x["from"], "to": "?", "kind": "?http", "at": x["at"],
564
+ "expr": x["value"] if x["value"] is not None else x.get("expr", "fetch")})
565
+ continue
566
+ url = route_parts(x["value"])
567
+ matched = [(n, v) for m, r, n, v in routes if m in (x["method"], "ALL") and route_match(r, url)]
568
+ hits = sorted({n for n, _ in matched})
569
+ if hits and len({v for _, v in matched}) == 1:
570
+ # one route; several handlers only when alternative routers (e.g. owner/guest) register it
571
+ out += [{"from": x["from"], "to": n, "kind": "http", "at": x["at"]} for n in hits]
572
+ else:
573
+ out.append({"from": x["from"], "to": "?", "kind": "?http", "at": x["at"], "expr": x["value"],
574
+ **({"candidates": hits} if hits else {})})
575
+ elif x["kind"] == "invoke":
576
+ hits = commands.get(x["value"], []) if x["value"] in registered else []
577
+ if len(hits) == 1:
578
+ out.append({"from": x["from"], "to": hits[0], "kind": "invoke", "at": x["at"]})
579
+ else:
580
+ out.append({"from": x["from"], "to": "?", "kind": "?invoke", "at": x["at"],
581
+ "expr": x["value"] or x["expr"], **({"candidates": hits} if hits else {})})
582
+ return out
583
+
584
+
585
+ TEST_PATH = pyx.TEST_PATH
586
+
587
+
588
+ def join_mounts(entries, mounts):
589
+ """Route entries owned by a router/app get every literal mount prefix above them."""
590
+ # shortcut: test files mount routers at "/" for fixtures; they are not entry points, so their mounts are dropped
591
+ parents = {}
592
+ for m in mounts:
593
+ if TEST_PATH.search(m["at"].rsplit(":", 1)[0]):
594
+ continue
595
+ parents.setdefault(m["child"], []).append(m)
596
+
597
+ def prefixes(app, seen=()):
598
+ if app in seen or app not in parents:
599
+ return [""]
600
+ out = []
601
+ for m in parents[app]:
602
+ out += [p + m["prefix"] for p in prefixes(m["parent"], seen + (app,))]
603
+ return out
604
+
605
+ res = []
606
+ for e in entries:
607
+ if e["kind"] == "route" and TEST_PATH.search(e["at"].rsplit(":", 1)[0]):
608
+ continue # a test's fake server is not a product entry point
609
+ if e["kind"] == "route" and "method" in e:
610
+ for pre in prefixes(e.get("app")):
611
+ path = (pre.rstrip("/") + "/" + e["value"].lstrip("/")) if pre else e["value"]
612
+ res.append({"kind": "route", "value": f"{e['method']} {path}", "node": e["node"], "at": e["at"]})
613
+ else:
614
+ res.append(e)
615
+ return res
616
+
617
+
618
+ def drop_proven_route_marks(edges, entries):
619
+ """A safety-net `?route` whose handler (or path) another source proved is no longer uncertain."""
620
+ proven = {e["node"] for e in entries if e["kind"] == "route"}
621
+ paths = {e["value"].split(" ", 1)[-1] for e in entries if e["kind"] == "route"}
622
+ return [e for e in edges if not (e["kind"] == "?route" and (e.get("handler") in proven
623
+ or (e.get("path") and any(p.endswith(e["path"]) for p in paths))))]
624
+
625
+
626
+ def apply_ignores(edges, config):
627
+ rules = config.get("ignore", [])
628
+ rules = [r for r in rules if "method" in r or "at" in r] # `missing`/`untracked` rules are build-level
629
+ for e in edges:
630
+ if e["kind"] not in ("unresolved", "method?", "?callback", "?route"):
631
+ continue
632
+ file = e["at"].rsplit(":", 1)[0]
633
+ for r in rules:
634
+ if "method" in r:
635
+ hit = e.get("method") == r["method"]
636
+ else:
637
+ expr = e.get("expr", "")
638
+ full = e.get("full", expr)
639
+ # Some extractors retain only the callee; (*) does not constrain arguments.
640
+ if "full" not in e and "(" not in expr and r.get("expr", "").endswith("(*)"):
641
+ full = expr + "()"
642
+ hit = pyx.path_match(r.get("at", ""), file) and pyx.expr_match(r.get("expr", "*"), expr, full)
643
+ if hit:
644
+ e["kind"] = "ignored"
645
+ e["reason"] = r.get("reason", "")
646
+ break
647
+
648
+
649
+ def group_edges(edges):
650
+ groups = {}
651
+ for e in edges:
652
+ key = (e["from"], e["to"], e["kind"], e.get("expr", ""))
653
+ g = groups.get(key)
654
+ if g is None:
655
+ g = {k: v for k, v in e.items() if k not in ("at", "full")}
656
+ g["at"] = set()
657
+ groups[key] = g
658
+ g["at"].add(e["at"])
659
+ out = []
660
+ for key in sorted(groups):
661
+ g = groups[key]
662
+ g["at"] = sorted(g["at"], key=at_key)
663
+ out.append(g)
664
+ return out
665
+
666
+
667
+ def at_key(at):
668
+ f, _, line = at.rpartition(":")
669
+ return (f, int(line) if line.isdigit() else 0)
670
+
671
+
672
+ def group_entries(entries):
673
+ groups = {}
674
+ for e in entries:
675
+ g = groups.setdefault((e["kind"], e["value"]), {"kind": e["kind"], "value": e["value"],
676
+ "nodes": set(), "at": set()})
677
+ g["nodes"].add(e["node"])
678
+ g["at"].add(e["at"])
679
+ out = []
680
+ for key in sorted(groups):
681
+ g = groups[key]
682
+ g["nodes"] = sorted(g["nodes"])
683
+ g["at"] = sorted(g["at"], key=at_key)
684
+ out.append(g)
685
+ return out
686
+
687
+
688
+ # verify/expect/gotchas/verified: how an agent drives and checks the feature by hand (spec §10.3)
689
+ FEATURE_KEYS = ("title", "aliases", "entry", "reach", "test", "does", "verify", "expect", "gotchas", "verified")
690
+ # the hand-check layer changes on every verification run and shapes no edge: kept out of featmap.json (featmap.toml holds it)
691
+ VERIFY_KEYS = ("verify", "expect", "gotchas", "verified")
692
+
693
+
694
+ def features(config):
695
+ out = {}
696
+ for fid, f in sorted(config.get("feature", {}).items()):
697
+ out[fid] = {k: f[k] for k in sorted(f) if k in FEATURE_KEYS}
698
+ return out
699
+
700
+
701
+ def dumps(g):
702
+ """Deterministic, one node/edge/entry per line (spec §5.1)."""
703
+ def j(v):
704
+ return json.dumps(v, sort_keys=True, ensure_ascii=False)
705
+
706
+ def block(open_, close, lines):
707
+ return open_ + ("\n" + ",\n".join(lines) + "\n " if lines else "") + close
708
+
709
+ parts = [
710
+ f' "version": {g["version"]}',
711
+ f' "meta": {j(g["meta"])}',
712
+ ' "nodes": ' + block("{", "}", [f" {j(k)}: {j(v)}" for k, v in sorted(g["nodes"].items())]),
713
+ ' "edges": ' + block("[", "]", [f" {j(e)}" for e in g["edges"]]),
714
+ ' "entries": ' + block("[", "]", [f" {j(e)}" for e in g["entries"]]),
715
+ ' "reach": ' + block("[", "]", [f" {j(e)}" for e in g.get("reach", [])]),
716
+ ' "features": ' + block("{", "}", [f" {j(k)}: {j({f: x for f, x in v.items() if f not in VERIFY_KEYS})}"
717
+ for k, v in sorted(g["features"].items())]),
718
+ ]
719
+ return "{\n" + ",\n".join(parts) + "\n}\n"
720
+
721
+
722
+ def route_migration(value, entry_values, field="entry"):
723
+ """Suggest only a normalized route that was actually extracted; never resolve it."""
724
+ if not isinstance(value, str) or not value.startswith("route:/"):
725
+ return ""
726
+ route_id = value[len("route:"):]
727
+ parts = [part for part in route_id.split("/")
728
+ if part and not part.startswith("_") and not re.fullmatch(r"\(.*\)", part)]
729
+ parts = [re.sub(r"_$", "", part) for part in parts]
730
+ parts = [("*" if part == "$" else ":" + part[1:]) if part.startswith("$") else part for part in parts]
731
+ url = "/" + "/".join(parts)
732
+ if url != "/" and route_id.endswith("/"):
733
+ url += "/"
734
+ replacement = "route:" + url
735
+ if replacement != value and replacement in entry_values:
736
+ return f"{field} {value} bulunamadı — artık {replacement}"
737
+ return ""
738
+
739
+
740
+ def exclusion_note(pattern, excluded, config):
741
+ """A reference that only matches files an [[exclude]] rule removed names that rule, not "untracked"."""
742
+ hit = next((f for f in sorted(excluded) if pyx.path_match(pattern, f)), None)
743
+ rule = hit and next((r.get("glob") for r in config.get("exclude", []) if pyx.path_match(r.get("glob", ""), hit)), None)
744
+ return f'excluded by [[exclude]] glob = "{rule}"' if rule else ""
745
+
746
+
747
+ def enclosing_hint(sym, nodes):
748
+ """A missing `file:a.b` whose enclosing node exists (e.g. a folded object-literal callback): suggest it, never apply."""
749
+ if not isinstance(sym, str) or ":" not in sym:
750
+ return ""
751
+ path, _, qual = sym.partition(":")
752
+ while "." in qual:
753
+ qual = qual.rsplit(".", 1)[0]
754
+ if f"{path}:{qual}" in nodes:
755
+ return f" — artık {path}:{qual}?"
756
+ return f" — artık {path}:<module>?" if qual != "<module>" and f"{path}:<module>" in nodes else ""
757
+
758
+
759
+ def command_paths(cmd):
760
+ """Repo-relative project paths a test command names; `cd dir &&` moves later paths, env tools are skipped."""
761
+ cwd, word, prev, out = "", 0, None, []
762
+ for tok in shlex.split(cmd):
763
+ if tok in ("&&", "||", ";", "|"):
764
+ word, prev = 0, None
765
+ continue
766
+ if word == 0 and re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*=.*", tok):
767
+ continue # VAR=value prefix
768
+ if prev == "cd":
769
+ cwd = os.path.normpath(os.path.join(cwd, tok))
770
+ elif "/" in tok and not tok.startswith(("-", "/", "~")) and "://" not in tok:
771
+ path = os.path.normpath(os.path.join(cwd, tok))
772
+ # shortcut: the program itself inside a dot-dir or node_modules (.venv/bin/python) is the environment
773
+ if not (word == 0 and any(p.startswith(".") and p not in (".", "..") or p == "node_modules" for p in path.split("/"))):
774
+ out.append(path)
775
+ prev, word = tok, word + 1
776
+ return out
777
+
778
+
779
+ def validate(graph, config, files, references=True):
780
+ """Rule/config references that must exist (spec §5.4/3-5). `references=False` (partial graph, §6.4) skips
781
+ the checks against extracted nodes/entries and keeps the schema and tracked-file checks."""
782
+ errs = []
783
+ if config.get("approval", "agent") not in APPROVAL_MODES:
784
+ errs.append(f"approval = {config['approval']!r}: \"user\" ya da \"agent\" olmalı")
785
+ nodes = graph["nodes"]
786
+ fileset = set(files)
787
+ entry_values = {f"{e['kind']}:{e['value']}" for e in graph["entries"] + graph.get("reach", [])}
788
+ excluded = graph.get("_excluded", ())
789
+
790
+ def file_exists(pattern, what):
791
+ if not any(pyx.path_match(pattern, f) for f in fileset):
792
+ note = exclusion_note(pattern, excluded, config)
793
+ errs.append(f"{what}: `{pattern}` {note}" if note else f"{what}: no tracked file matches `{pattern}`")
794
+
795
+ for r in config.get("dispatch", []):
796
+ file_exists(r.get("at", ""), "dispatch at")
797
+ for t in r.get("targets", []):
798
+ if references and t not in nodes:
799
+ errs.append(f"dispatch target {t}: no such symbol" + enclosing_hint(t, nodes))
800
+ if "targets" not in r and "targets_from" not in r:
801
+ errs.append(f"dispatch {r.get('at')} {r.get('expr')}: needs targets or targets_from")
802
+ seen_clients = set()
803
+ for r in config.get("http_client", []):
804
+ symbol = r.get("symbol")
805
+ label = f"http_client {symbol or '<missing symbol>'}"
806
+ if not isinstance(symbol, str) or not symbol:
807
+ errs.append(f"{label}: symbol is required and must be a node id")
808
+ elif references and symbol not in nodes:
809
+ errs.append(f"{label}: no such symbol" + enclosing_hint(symbol, nodes))
810
+ if isinstance(symbol, str):
811
+ if symbol in seen_clients:
812
+ errs.append(f"{label}: duplicate symbol")
813
+ seen_clients.add(symbol)
814
+ if type(r.get("url")) is not int or r["url"] < 0:
815
+ errs.append(f"{label}: url must be a non-negative argument index")
816
+ sig = graph.get("_http_params", {}).get(symbol) if isinstance(symbol, str) and references else None
817
+ if sig and not sig["rest"]:
818
+ args = ([r["url"]] if type(r.get("url")) is int else []) + [
819
+ int(p.split(".")[0]) for p in (r.get("method_arg") if isinstance(r.get("method_arg"), list) else [r.get("method_arg")])
820
+ if isinstance(p, str) and re.match(r"[0-9]+", p)]
821
+ for i in sorted(set(a for a in args if a >= sig["params"])):
822
+ errs.append(f"{label}: argument {i} is beyond its {sig['params']} parameter(s)")
823
+ if ("method" in r) == ("method_arg" in r):
824
+ errs.append(f"{label}: needs exactly one of method or method_arg")
825
+ if "method" in r and (not isinstance(r["method"], str) or not re.fullmatch(r"[A-Z]+", r["method"])):
826
+ errs.append(f"{label}: method must be an uppercase HTTP method")
827
+ if "method_arg" in r:
828
+ paths = r["method_arg"] if isinstance(r["method_arg"], list) else [r["method_arg"]]
829
+ if not paths or any(not isinstance(p, str) or not re.fullmatch(r"[0-9]+(?:\.[A-Za-z_$][\w$]*)*", p) for p in paths):
830
+ errs.append(f"{label}: method_arg must be an argument path or non-empty list of paths (e.g. 1.method)")
831
+ if "base" in r and not isinstance(r["base"], str):
832
+ errs.append(f"{label}: base must be a literal string")
833
+ if not isinstance(r.get("reason"), str) or not r["reason"].strip():
834
+ errs.append(f"{label}: reason is required")
835
+ for r in config.get("process", []):
836
+ if "const" in r:
837
+ path, _, name = r["const"].partition(":")
838
+ if path not in fileset:
839
+ errs.append(f"process const {r['const']}: no such file")
840
+ else:
841
+ file_exists(r.get("at", ""), "process at")
842
+ if r.get("target") not in fileset:
843
+ errs.append(f"process target {r.get('target')}: "
844
+ + (exclusion_note(r.get("target", ""), excluded, config) or "not a tracked file"))
845
+ for r in config.get("ignore", []):
846
+ if not r.get("reason"):
847
+ errs.append(f"ignore {r.get('at', r.get('method', r.get('missing', r.get('untracked'))))}: reason is required")
848
+ if "at" in r:
849
+ file_exists(r["at"], "ignore at")
850
+ if "missing" in r:
851
+ file_exists(r["missing"], "ignore missing")
852
+ for r in config.get("runner", []):
853
+ file_exists(r.get("glob", ""), "runner glob")
854
+ for fid, f in config.get("feature", {}).items():
855
+ for sym in f.get("entry", []):
856
+ if references and sym not in nodes:
857
+ errs.append(f"feature {fid}: " + (route_migration(sym, entry_values)
858
+ or (f"entry {sym}: entry takes node ids — use reach = [{json.dumps(sym, ensure_ascii=False)}]"
859
+ if sym in entry_values else
860
+ f"entry {sym}: no such symbol" + enclosing_hint(sym, nodes))))
861
+ for reach in f.get("reach", []):
862
+ if references and reach not in entry_values:
863
+ errs.append(f"feature {fid}: " + (route_migration(reach, entry_values, "reach") or f"reach {reach}: not extracted from code"))
864
+ for cmd in f.get("test", []):
865
+ for tok in command_paths(cmd):
866
+ if tok not in fileset:
867
+ errs.append(f"feature {fid}: test `{cmd}`: {tok} is "
868
+ + (exclusion_note(tok, excluded, config) or "not a tracked file"))
869
+ for key in ("verify", "gotchas"):
870
+ if key in f and (not isinstance(f[key], list) or (key == "verify" and not f[key]) or not all(isinstance(x, str) and x.strip() for x in f[key])):
871
+ errs.append(f"feature {fid}: {key} must be a list of non-empty strings")
872
+ if "expect" in f and (not isinstance(f["expect"], str) or not f["expect"].strip()):
873
+ errs.append(f"feature {fid}: expect must be a non-empty string")
874
+ if "verified" in f and (not isinstance(f["verified"], str) or not re.fullmatch(r"[0-9a-f]{7,40}", f["verified"])):
875
+ errs.append(f"feature {fid}: verified must be the commit sha the verify steps last passed at")
876
+ if "verified" in f and not f.get("verify"):
877
+ errs.append(f"feature {fid}: verified without verify steps")
878
+ owned = {}
879
+ for fid, f in sorted(config.get("feature", {}).items()):
880
+ for k in f.get("reach", []): # `kind:value` keys are owned through reach only (entry takes node ids)
881
+ owned.setdefault(k, fid)
882
+ for u in config.get("unassigned", []):
883
+ if "*" in (u.get("entry") or ""): # a glob leaves out what no feature owns; it must still match something
884
+ if references and not any(unassigned_match(u["entry"], k) for k in entry_values):
885
+ errs.append(f"unassigned {u['entry']}: matches no extracted entry")
886
+ if not u.get("reason"):
887
+ errs.append(f"unassigned {u.get('entry')}: reason is required")
888
+ continue
889
+ if u.get("entry") in owned:
890
+ errs.append(f"unassigned {u.get('entry')}: also owned by feature {owned[u.get('entry')]} — remove one")
891
+ if references and u.get("entry") not in entry_values:
892
+ errs.append(route_migration(u.get("entry"), entry_values, "unassigned entry") or f"unassigned {u.get('entry')}: not extracted from code")
893
+ if not u.get("reason"):
894
+ errs.append(f"unassigned {u.get('entry')}: reason is required")
895
+ return errs
896
+
897
+
898
+ APPROVAL_MODES = ("user", "agent")
899
+
900
+
901
+ def proposed(config):
902
+ """Agent-written items awaiting user approval: [(kind, id)]. Empty unless `approval = "user"`."""
903
+ if config.get("approval", "agent") != "user":
904
+ return []
905
+ out = [("feature", fid) for fid, f in sorted(config.get("feature", {}).items()) if f.get("proposed")]
906
+ out += [("unassigned", u.get("entry")) for u in config.get("unassigned", []) if u.get("proposed")]
907
+ out += [("dispatch", r.get("expr")) for r in config.get("dispatch", []) if r.get("proposed")]
908
+ return out
909
+
910
+
911
+ def unassigned(graph, config):
912
+ assigned = {r for f in config.get("feature", {}).values() for r in f.get("reach", [])}
913
+ pats = [u.get("entry") or "" for u in config.get("unassigned", [])]
914
+ return [e for e in graph["entries"] if f"{e['kind']}:{e['value']}" not in assigned
915
+ and not any(unassigned_match(p, f"{e['kind']}:{e['value']}") for p in pats)]
916
+
917
+
918
+ def unassigned_match(pattern, key):
919
+ """`[[unassigned]] entry` is a key, or a glob (`route:/admin*`) for a group left unmapped on purpose."""
920
+ return key == pattern or ("*" in pattern and fnmatch.fnmatchcase(key, pattern))