tracker

13.0 KB

1. #!/usr/bin/env python3
2. """tools/let-audit.py [--fix] [--list] <file.hl …> — mission 028 (code order rule 1: `let` ONLY for a variable that is reassigned).
4. Counts every `let NAME = …` and decides whether it may be a plain declaration (`NAME = …`); --fix rewrites those in place,
5. --list prints every kept one with its reason. A `let` STAYS when:
6. reassigned NAME is written again in its function (a nested closure included), or appended to (`NAME[] = v`)
7. loop it is declared inside a loop body (a plain declaration there is "Cannot reassign" on the 2nd pass) or a for head
8. shadow the same name is a member / import of the file (or of a component's `parent`), a parameter or name of an
9. enclosing function, or is read somewhere else as a free name (a plain `NAME = …` would then REBIND that outer binding instead of declaring one)
10. block NAME is used outside the block it is declared in, or before it (the browser target emits a bare declaration as a
11. block-scoped JS `let`, a `let` as a function-scoped `var`)
12. root a file-root `let` of a component (a View member; left alone) or one written anywhere else in the file
13. form destructuring or no initializer
14. Tokens: `//` comments; '…' and "…" strings (a backslash masks the next character); no regexes, no backtick strings in code.
15. """
16. import os, re, sys
18. KEYWORDS_BLOCK = {'if', 'switch', 'catch', 'with'}
19. KEYWORDS_LOOP = {'for', 'while'}
20. IMPLICIT = {'session', 'params', 'route', 'req', 'res', 'server', 'title', 'head', 'query', 'state', 'kids', 'page', 'emit',
21. 'refresh', 'this', 'super', 'styles', 'View', 'console'}
23. def tokenize(src):
24. toks = [] # (kind, text, start)
25. i, n = 0, len(src)
26. while i < n:
27. c = src[i]
28. if c in ' \t\r\n':
29. i += 1
30. elif src.startswith('//', i):
31. j = src.find('\n', i)
32. i = n if j < 0 else j
33. elif c in '\'"':
34. j = i + 1
35. while j < n and src[j] != c:
36. j += 2 if src[j] == '\\' else 1
37. toks.append(('str', src[i:j + 1], i))
38. i = j + 1
39. elif c.isalpha() or c in '_#@$' or ord(c) > 127:
40. j = i
41. while j < n and (src[j].isalnum() or src[j] in '_#@$' or ord(src[j]) > 127):
42. j += 1
43. toks.append(('id', src[i:j], i))
44. i = j
45. elif c.isdigit():
46. m = re.match(r'\d+(\.\d+)?([eE][+-]?\d+)?', src[i:])
47. toks.append(('num', m.group(0), i))
48. i += len(m.group(0))
49. else:
50. for op in ('===', '!==', '=>', '==', '!=', '<=', '>=', '&&', '||', '??', '++', '--', '+=', '-=', '*=', '/=', '<>', '?.', '...'):
51. if src.startswith(op, i):
52. toks.append(('op', op, i))
53. i += len(op)
54. break
55. else:
56. toks.append(('op', c, i))
57. i += 1
58. return toks
60. OBJ_BEFORE = {'=', '(', ',', '[', ':', '?', '||', '&&', '??', '!', '+', '-', '<>', '==', '!=', '===', '!==', '<', '>', '<=', '>=', '...'}
62. class Frame:
63. def __init__(self, kind, start, parent, params=()):
64. self.kind, self.start, self.end, self.parent, self.params = kind, start, None, parent, set(params)
65. def func(self):
66. f = self
67. while f.kind not in ('func', 'root'):
68. f = f.parent
69. return f
71. def rootsOf(path):
72. return analyse(path, True, want_roots=True)
74. def analyse(path, is_component, want_roots=False):
75. src = open(path, encoding='utf-8').read()
76. toks = tokenize(src)
77. root = Frame('root', -1, None)
78. root.end = len(toks)
79. frames = [root]
80. stack = [root]
81. match = {}
82. popen = []
83. frame_of = [None] * len(toks) # the innermost brace frame of each token
84. paren_kind = [None] * len(toks) # 'forhead' when inside a for(...) head
85. forheads = []
86. param_toks = set()
87. for k, (kind, text, _) in enumerate(toks):
88. top = stack[-1]
89. frame_of[k] = top
90. if forheads:
91. paren_kind[k] = 'forhead'
92. if kind != 'op':
93. continue
94. if text in '([':
95. popen.append(k)
96. if text == '(' and k > 0 and toks[k - 1][1] == 'for':
97. forheads.append(k)
98. elif text in ')]':
99. o = popen.pop()
100. match[k] = o
101. match[o] = k
102. if forheads and forheads[-1] == o:
103. forheads.pop()
104. elif text == '{':
105. prev = toks[k - 1] if k > 0 else ('op', '', 0)
106. fkind, params = 'block', ()
107. if prev[1] == '=>':
108. fkind = 'func'
109. b = k - 2
110. if toks[b][1] == ')':
111. params = [t[1] for t in toks[match[b] + 1:b] if t[0] == 'id']
112. param_toks.update(j for j in range(match[b] + 1, b) if toks[j][0] == 'id')
113. elif toks[b][0] == 'id':
114. params = [toks[b][1]]
115. param_toks.add(b)
116. elif prev[1] == ')':
117. o = match[k - 1]
118. before = toks[o - 1] if o > 0 else ('op', '', 0)
119. if before[0] == 'id' and before[1] in KEYWORDS_LOOP:
120. fkind = 'loop'
121. elif before[0] == 'id' and before[1] in KEYWORDS_BLOCK:
122. fkind = 'block'
123. elif before[0] == 'id':
124. fkind = 'func'
125. params = [t[1] for t in toks[o + 1:k - 1] if t[0] == 'id']
126. param_toks.update(j for j in range(o + 1, k - 1) if toks[j][0] == 'id')
127. else:
128. fkind = 'obj'
129. elif prev[0] == 'id' and prev[1] in ('else', 'try', 'finally'):
130. fkind = 'block'
131. elif prev[0] == 'id' and prev[1] == 'do':
132. fkind = 'loop'
133. elif prev[0] in ('id', 'str'):
134. fkind = 'elem'
135. elif prev[0] == 'op' and (prev[1] in OBJ_BEFORE or prev[1] == '') or (prev[0] == 'id' and prev[1] == 'return'):
136. fkind = 'obj'
137. f = Frame(fkind, k, top, params)
138. frames.append(f)
139. stack.append(f)
140. elif text == '}':
141. f = stack.pop()
142. f.end = k
143. frame_of[k] = f.parent
144. # every identifier occurrence: (k, name, role) role = let | assign | append | param | read | key
145. occ = {}
146. roots = set()
147. for k, (kind, text, _) in enumerate(toks):
148. if kind != 'id':
149. continue
150. prev = toks[k - 1][1] if k > 0 else ''
151. nxt = toks[k + 1][1] if k + 1 < len(toks) else ''
152. fr = frame_of[k]
153. if prev in ('.', '?.'):
154. continue
155. if k in param_toks:
156. role = 'param'
157. elif prev == 'let':
158. role = 'let'
159. elif prev == '(' and k > 1 and toks[k - 2][1] == 'for' and nxt in ('of', 'in'):
160. role = 'forvar'
161. elif fr.kind in ('obj', 'elem') and nxt == '=':
162. role = 'key'
163. elif nxt in ('=', '++', '--', '+=', '-=', '*=', '/=') or prev in ('++', '--'):
164. role = 'assign'
165. elif nxt == '[' and k + 3 < len(toks) and toks[k + 2][1] == ']' and toks[k + 3][1] == '=':
166. role = 'append'
167. else:
168. role = 'read'
169. occ.setdefault(text, []).append((k, role))
170. # file-root members: written at the root (outside every function), static, imported, root methods
171. if fr.func() is root and role in ('let', 'assign'):
172. roots.add(text)
173. if prev == 'static' or prev == 'import':
174. roots.add(text)
175. if nxt == '(' and fr is root and prev not in ('new',):
176. c = match.get(k + 1)
177. if c is not None and c + 1 < len(toks) and toks[c + 1][1] == '{':
178. roots.add(text)
179. # a component's `parent '<file>'`: the parent's members are this one's too (main.hl's header members in every page)
180. for k, (kind, text, _) in enumerate(toks):
181. if text == 'parent' and kind == 'id' and k + 1 < len(toks) and toks[k + 1][0] == 'str' and frame_of[k] is root:
182. ppath = os.path.normpath(os.path.join(os.path.dirname(path), toks[k + 1][1][1:-1]))
183. if os.path.exists(ppath):
184. roots |= rootsOf(ppath)
185. # imports `import { a, b } from` / `import X from`
186. for k, (kind, text, _) in enumerate(toks):
187. if text == 'import' and k + 1 < len(toks):
188. j = k + 1
189. if toks[j][1] == '{':
190. while toks[j][1] != '}':
191. if toks[j][0] == 'id':
192. roots.add(toks[j][1])
193. j += 1
194. elif toks[j][0] == 'id':
195. roots.add(toks[j][1])
197. if want_roots:
198. return roots
200. def inside(k, f):
201. return f.start < k < f.end if f.kind != 'root' else True
203. def chain(f):
204. out = []
205. while f is not None:
206. out.append(f)
207. f = f.parent
208. return out
210. def declares(g, name):
211. # does function g itself bind `name` (param, let, or a plain write at its own level that is not a root member)?
212. if name in g.params:
213. return True
214. for (k, role) in occ.get(name, []):
215. if role in ('let', 'assign', 'forvar') and frame_of[k].func() is g:
216. return True
217. return False
219. results = []
220. for k, (kind, text, start) in enumerate(toks):
221. if text != 'let' or kind != 'id':
222. continue
223. if k + 2 >= len(toks) or toks[k + 1][0] != 'id' or toks[k + 2][1] != '=':
224. results.append((k, toks[k + 1][1] if k + 1 < len(toks) else '?', 'form'))
225. continue
226. name = toks[k + 1][1]
227. fr = frame_of[k]
228. F = fr.func()
229. if paren_kind[k] == 'forhead':
230. results.append((k, name, 'loop'))
231. continue
232. # loop between the let and its function?
233. g, loop = fr, False
234. while g is not F:
235. if g.kind == 'loop':
236. loop = True
237. g = g.parent
238. others = [(j, r) for (j, r) in occ[name] if j != k + 1 and inside(j, F)]
239. reassigned = any(r in ('assign', 'append', 'let', 'forvar') for (j, r) in others)
240. others = [(j, r) for (j, r) in others if r not in ('key', 'param')]
241. if F is root:
242. elsewhere = [(j, r) for (j, r) in occ[name] if j != k + 1 and r in ('assign', 'append', 'let', 'forvar')]
243. if loop:
244. results.append((k, name, 'loop'))
245. elif elsewhere or is_component:
246. results.append((k, name, 'reassigned' if elsewhere else 'root'))
247. else:
248. results.append((k, name, 'ok'))
249. continue
250. if reassigned:
251. results.append((k, name, 'reassigned'))
252. continue
253. if loop:
254. results.append((k, name, 'loop'))
255. continue
256. # shadow: a member/import, an implicit member, a param of F or an enclosing function, a name an enclosing function binds,
257. # a nested function's parameter of the same name, or a FREE read anywhere outside F
258. bad = name in roots or name in IMPLICIT or name in F.params
259. for g in chain(F.parent):
260. if g.kind == 'func' and declares(g, name):
261. bad = True
262. for f2 in frames:
263. if f2.kind == 'func' and f2 is not F and inside(f2.start, F) and name in f2.params:
264. bad = True
265. if not bad:
266. for (j, r) in occ[name]:
267. if inside(j, F) or r in ('key', 'param'):
268. continue
269. if not any(g.kind == 'func' and declares(g, name) for g in chain(frame_of[j].func())):
270. bad = True
271. break
272. if bad:
273. results.append((k, name, 'shadow'))
274. continue
275. # block: every use inside the declaration's own block, after it
276. blk = fr
277. if any(not (j > k and (blk is F or inside(j, blk))) for (j, r) in others):
278. results.append((k, name, 'block'))
279. continue
280. results.append((k, name, 'ok'))
281. return src, toks, results
283. def main():
284. args = sys.argv[1:]
285. fix = '--fix' in args
286. lst = '--list' in args
287. files = [a for a in args if not a.startswith('--')]
288. total = {}
289. for path in files:
290. is_component = '/components/' in '/' + path
291. src, toks, results = analyse(path, is_component)
292. counts = {}
293. for (k, name, why) in results:
294. counts[why] = counts.get(why, 0) + 1
295. total[why] = total.get(why, 0) + 1
296. if lst and why != 'ok':
297. line = src.count('\n', 0, toks[k][2]) + 1
298. print(f'{path}:{line}: keep let {name} ({why})')
299. n = len(results)
300. print(f'{path}: let={n} ' + ' '.join(f'{w}={c}' for w, c in sorted(counts.items())))
301. if fix:
302. out = src
303. for (k, name, why) in sorted(results, key=lambda r: -toks[r[0]][2]):
304. if why == 'ok':
305. s = toks[k][2]
306. e = toks[k + 1][2]
307. out = out[:s] + out[e:]
308. if out != src:
309. open(path, 'w', encoding='utf-8').write(out)
310. n = sum(total.values())
311. print(f'TOTAL let={n} ' + ' '.join(f'{w}={c}' for w, c in sorted(total.items())))
313. if __name__ == '__main__':
314. main()