notes

13.3 KB

1. // hl:core/AST — WHAT A FILE READS AND WHAT IT WRITES, from the compiler's own AST.
2. //
3. // The language has always been able to hand a caller the SYNTAX of a node
4. // (`hlSyntax`) and the list of members a file declares (`hlMembers`). What it
5. // never answered is what that syntax DOES with names: which members an
6. // expression reads, which members a handler writes. Every consumer that needed
7. // it wrote its own walk — hl:web's tree builder decides per tag what counts as
8. // a read, and its browser half rediscovers the same set at runtime by walking
9. // the DOM against the tree and JSON-comparing state afterwards (FRAMEWORK_AUDIT
10. // §3). Two copies of one answer drift, and neither could see a write at all.
11. //
12. // The answer is the language's, so it lives here. `query(file)` is a table of
13. // one file's (and, recursively, its project's) members, derivations, handlers
14. // and methods, each with the names it reads and the names it writes, every node
15. // carrying a stable site id `file:line:col`.
16. //
17. // NOTHING HERE KNOWS WHAT A VIEW IS. There is no attr, text, region, key or
18. // component vocabulary in this file and none in the runtime rule beneath it: a
19. // member is a member. A caller that wants one member's answer — hl:web wants
20. // `View`'s — passes that member's NAME as the filter. That is the only way to
21. // narrow the query, and it is a name, not a concept.
22. //
23. // import { query } from 'hl:core/AST'
24. // let q = query('components/home.hl') // recursive, every member
25. // let v = query('components/home.hl', true, 'View')
26. //
27. // THE GENERATION. Reflection reads a parse that is valid until the next
28. // analysis; this package runs one of its own (`hlProject()`) the first time it
29. // is asked and keeps the handle. `refresh()` runs a new one — a dev reload, or
30. // a caller that changed a file. A static cannot be reassigned, so the handle
31. // lives in a static hybrid, which can.
33. static state = { gen = 0; graph = null; }
35. // The live analysis generation, started on first use.
36. static analysis = () => {
37. if (state.gen == 0) {
38. let g = hlProject()
39. state.graph = g
40. state.gen = g.analysisGen
41. }
42. return state.gen
43. }
45. // A NEW ANALYSIS: the parses this package answers from are replaced, and every
46. // handle a caller still holds from the old one is refused by the language.
47. static refresh = () => {
48. let g = hlProject()
49. state.graph = g
50. state.gen = g.analysisGen
51. return state.gen
52. }
54. // …of a project this run did not boot: a directory, a manifest, or an entry
55. // file. The keys every answer below is filed under are that project's.
56. static analyseFrom = (path) => {
57. let g = hlProject(path)
58. state.graph = g
59. state.gen = g.analysisGen
60. return state.gen
61. }
63. // The project graph the generation belongs to (`hlProject()`'s answer).
64. static project = () => {
65. analysis()
66. return state.graph
67. }
69. // ---- the reflection surface, without the generation argument ------------------
70. // `hlSyntax` and `hlMembers` are the ambient names the framework still calls;
71. // here they are statics of a package, which is where they belong.
73. static syntax = (file, node) => { return hlSyntax(analysis(), file, node) }
74. static members = (file) => { return hlMembers(analysis(), file) }
75. static methods = (file) => { return hlMethods(analysis(), file) }
76. static handlers = (file) => { return hlEvents(analysis(), file).handles }
77. static denotes = (file, name) => { return hlDenotes(analysis(), file, name) }
78. static file = (file) => { return hlFile(analysis(), file) }
80. // ---- the syntax of one node, as a tree ----------------------------------------
81. // Every node carries its tag, its site id and the two answers the language gives
82. // for it: the free names it READS and the names it WRITES. The shape below is
83. // the shape `hlSyntax` returns, followed one child at a time — there is no
84. // interpretation of any tag, only its children.
85. //
86. // AN `on` HANDLER IS A LEAF HERE ON PURPOSE. Its body is not evaluated by the
87. // literal that carries it, so the names inside are the HANDLER's reads and
88. // writes, not the literal's; the node answers for them and the walk stops.
90. static tree = (file, node) => {
91. let n = hlSyntax(analysis(), file, node)
92. if (n == null) { return null }
93. let out = { tag = n.tag; site = n.site; line = n.line; col = n.col; reads = n.reads; writes = n.writes; }
94. if (n.tag == 'object_expression') {
95. let kids = []
96. for (h of n.entries) { kids.push(tree(file, h)) }
97. out.entries = kids
98. } else if (n.tag == 'object_property') {
99. out.key = n.key
100. out.value = tree(file, n.value)
101. } else if (n.tag == 'view_for') {
102. // A `for` ENTRY NAMES ITS LIST AND ITS ROW VARIABLE. The list is read in
103. // the scope standing around the `for`; the row variable is bound inside
104. // the body and every read of it there resolves as kind 'row'.
105. out.row = n.varName
106. out.list = tree(file, n.list)
107. out.body = tree(file, n.body)
108. } else if (n.tag == 'view_if') {
109. out.condition = tree(file, n.condition)
110. out.consequent = tree(file, n.consequent)
111. out.alternate = tree(file, n.alternate)
112. } else if (n.tag == 'on_statement') {
113. out.event = n.event
114. out.scope = n.scope
115. out.realm = n.realm
116. out.handler = n.handler
117. } else if (n.tag == 'identifier' || n.tag == 'new_expression') {
118. out.name = n.name
119. } else if (n.tag == 'literal') {
120. out.kind = n.kind
121. out.text = n.text
122. } else if (n.tag == 'member_expression') {
123. out.object = tree(file, n.object)
124. out.property = tree(file, n.property)
125. out.computed = n.computed
126. } else if (n.tag == 'call_expression') {
127. out.callee = tree(file, n.callee)
128. let args = []
129. for (h of n.args) { args.push(tree(file, h)) }
130. out.args = args
131. } else if (n.tag == 'binary_expression') {
132. out.operator = n.operator
133. out.left = tree(file, n.left)
134. out.right = tree(file, n.right)
135. } else if (n.tag == 'unary_expression') {
136. out.operator = n.operator
137. out.operand = tree(file, n.operand)
138. } else if (n.tag == 'conditional_expression') {
139. out.condition = tree(file, n.condition)
140. out.consequent = tree(file, n.consequent)
141. out.alternate = tree(file, n.alternate)
142. } else if (n.tag == 'array_expression') {
143. let els = []
144. for (h of n.elements) { els.push(tree(file, h)) }
145. out.elements = els
146. }
147. return out
148. }
150. // ---- names ---------------------------------------------------------------------
151. // A read or a write is `{ name, kind, isStatic, path?, key? }`. `kind` is the
152. // language's own resolution of the bare name: 'member', 'method', 'handler',
153. // 'class' (a default import), 'import' (a braced one), 'plugin', 'row' (bound by
154. // an enclosing `for` entry), 'local' (a lambda, handler or method parameter, or
155. // a `let`), 'none' (nothing this file declares — an ambient or a typo).
157. // the names of a read/write list, as plain strings
158. static namesOf = (list) => {
159. let out = []
160. for (r of list) { if (!out.includes(r.name)) { out.push(r.name) } }
161. return out
162. }
164. // the subset of a read/write list that resolves to a member of the file itself
165. static membersOf = (list) => {
166. let out = []
167. for (r of list) {
168. if (r.kind == 'member' && !r.isStatic && !out.includes(r.name)) { out.push(r.name) }
169. }
170. return out
171. }
173. // ---- one file's answer ---------------------------------------------------------
175. // every `on` node inside a member's syntax tree, flattened, each at its site
176. static nestedHandlers = (member, node, into) => {
177. if (node == null) { return into }
178. if (node.tag == 'on_statement') {
179. into.push({ member = member; event = node.event; scope = node.scope; realm = node.realm; site = node.site; reads = node.reads; writes = node.writes; nested = true; })
180. return into
181. }
182. if (node.entries != null) { for (c of node.entries) { nestedHandlers(member, c, into) } }
183. if (node.args != null) { for (c of node.args) { nestedHandlers(member, c, into) } }
184. if (node.elements != null) { for (c of node.elements) { nestedHandlers(member, c, into) } }
185. if (node.value != null) { nestedHandlers(member, node.value, into) }
186. if (node.list != null) { nestedHandlers(member, node.list, into) }
187. if (node.body != null) { nestedHandlers(member, node.body, into) }
188. if (node.condition != null) { nestedHandlers(member, node.condition, into) }
189. if (node.consequent != null) { nestedHandlers(member, node.consequent, into) }
190. if (node.alternate != null) { nestedHandlers(member, node.alternate, into) }
191. if (node.object != null) { nestedHandlers(member, node.object, into) }
192. if (node.property != null) { nestedHandlers(member, node.property, into) }
193. if (node.callee != null) { nestedHandlers(member, node.callee, into) }
194. if (node.left != null) { nestedHandlers(member, node.left, into) }
195. if (node.right != null) { nestedHandlers(member, node.right, into) }
196. if (node.operand != null) { nestedHandlers(member, node.operand, into) }
197. return into
198. }
200. static one = (key, member) => {
201. let gen = analysis()
202. let f = hlFile(gen, key)
203. let out = { key = key; class = f.class; members = []; derivations = []; handlers = []; methods = []; reaches = []; }
205. for (m of hlMembers(gen, key)) {
206. // (Hybriel has no `continue`: the body is guarded instead.)
207. if (member == null || m.name == member) {
208. let entry = { name = m.name; type = m.type; mandatory = m.mandatory; isStatic = m.isStatic; site = key + ':' + m.line + ':' + m.col; default = null; reads = []; writes = []; syntax = null; }
209. if (m.hasValue) {
210. let n = hlSyntax(gen, key, m.node)
211. entry.default = n.site
212. entry.reads = n.reads
213. entry.writes = n.writes
214. entry.syntax = tree(key, m.node)
215. // A DERIVATION IS AN INITIALIZER READ THE OTHER WAY: the same table,
216. // listed by the names the value depends on.
217. out.derivations.push({ name = m.name; site = n.site; reads = n.reads; })
218. nestedHandlers(m.name, entry.syntax, out.handlers)
219. for (r of n.reads) {
220. if (r.kind == 'class' && r.key != null && !out.reaches.includes(r.key)) { out.reaches.push(r.key) }
221. }
222. }
223. out.members.push(entry)
224. }
225. }
227. // The DECLARED handlers and methods answer for their whole body. A member
228. // filter narrows the member table only — a handler is not a member, and
229. // hiding the writes would make the filtered answer a lie about the file.
230. for (h of hlEvents(gen, key).handles) {
231. let n = hlSyntax(gen, key, h.node)
232. out.handlers.push({ member = null; event = h.event; scope = h.scope; realm = h.realm; params = h.params; site = n.site; reads = n.reads; writes = n.writes; nested = false; })
233. }
234. for (mm of hlMethods(gen, key)) {
235. // A literal's inline `on` is hoisted as a method over the SAME body
236. // (parser `inlineHandlerEntry`); it already answered at its site above.
237. if (!mm.inlineHandler) {
238. let n = hlSyntax(gen, key, mm.node)
239. out.methods.push({ name = mm.name; params = mm.params; site = n.site; reads = n.reads; writes = n.writes; })
240. }
241. }
243. // WHAT THIS FILE REACHES: every import the language resolved to another file
244. // of the project, and every composed reference a member's syntax read.
245. if (state.graph.files[key] != null) {
246. for (imp of state.graph.files[key].imports) {
247. if (imp.key != null && !out.reaches.includes(imp.key)) { out.reaches.push(imp.key) }
248. }
249. }
250. if (f.wrapper != null && !out.reaches.includes(f.wrapper)) { out.reaches.push(f.wrapper) }
251. for (k of f.inherits) { if (!out.reaches.includes(k)) { out.reaches.push(k) } }
252. return out
253. }
255. // ---- the query -----------------------------------------------------------------
256. // `query(file, recursive = true, member = null)`:
257. // files — one answer per file reached, keyed by the analysis key
258. // order — the keys in the order they were reached, `file` first
259. // Recursive follows what each file reaches (its imports, its wrapper, what it
260. // inherits, and the composed references its members read), each file once.
262. static query = (file, recursive, member) => {
263. let rec = recursive == null ? true : recursive
264. let want = member == null ? null : member
265. analysis()
266. let out = { root = file; files = {}; order = []; }
267. let queue = [file]
268. let seen = {}
269. while (queue.length > 0) {
270. let key = queue.shift()
271. if (seen[key] == null) {
272. seen[key] = true
273. // A key the analysis does not hold is not this package's to parse —
274. // the root is answered regardless, because the caller named it.
275. if (state.graph.files[key] != null || key == file) {
276. let answer = one(key, want)
277. out.files[key] = answer
278. out.order.push(key)
279. if (rec) {
280. for (k of answer.reaches) { if (seen[k] == null) { queue.push(k) } }
281. }
282. }
283. }
284. }
285. return out
286. }
288. // EVERY FILE THE ANALYSIS HOLDS, once. A project's root reaches nearly all of
289. // them; this reaches the rest too, which is what a whole-project report wants.
290. static queryAll = (member) => {
291. analysis()
292. let out = { root = null; files = {}; order = []; }
293. for (k of state.graph.files.keys()) {
294. out.files[k] = one(k, member)
295. out.order.push(k)
296. }
297. return out
298. }
300. // ---- what `hybriel --graph` carries, per file -----------------------------------
301. // THE ONE DOCUMENT ASKS THIS PACKAGE (creator, 2026-09-14: the language scans
302. // EVERYTHING by default and a filter only narrows). `--graph` prints the
303. // language graph, and every file record in it carries the four tables below —
304. // the same objects `query()` puts in `files[key]`, handed to the writer as they
305. // are. There is no second walk and no second rendering: a person reads that
306. // JSON, and a program imports `query` and gets the same answer as values.
308. static tables = (path, member) => {
309. if (path == null) { analysis() } else { analyseFrom(path) }
310. let q = queryAll(member)
311. let out = {}
312. for (k of q.order) {
313. let f = q.files[k]
314. out[k] = { members = f.members; derivations = f.derivations; methods = f.methods; handlers = f.handlers; }
315. }
316. return out
317. }