Title: Document load-bearing invariants and subsystems with GHC-style Notes · Issue #44 · purescript-lua/purescript-lua · GitHub
Open Graph Title: Document load-bearing invariants and subsystems with GHC-style Notes · Issue #44 · purescript-lua/purescript-lua
X Title: Document load-bearing invariants and subsystems with GHC-style Notes · Issue #44 · purescript-lua/purescript-lua
Description: While fixing #37 it became clear that several of the compiler's conventions are load-bearing but documented poorly: the same rule copy-pasted across call sites, an invariant spelled out only where it is consumed rather than where it is e...
Open Graph Description: While fixing #37 it became clear that several of the compiler's conventions are load-bearing but documented poorly: the same rule copy-pasted across call sites, an invariant spelled out only where ...
X Description: While fixing #37 it became clear that several of the compiler's conventions are load-bearing but documented poorly: the same rule copy-pasted across call sites, an invariant spelled out only wh...
Opengraph URL: https://github.com/purescript-lua/purescript-lua/issues/44
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Document load-bearing invariants and subsystems with GHC-style Notes","articleBody":"While fixing #37 it became clear that several of the compiler's conventions are load-bearing but documented poorly: the same rule copy-pasted across call sites, an invariant spelled out only where it is consumed rather than where it is established, or a whole subsystem with nothing but a section banner. When those drift apart or go unnoticed, they cause exactly the kind of silent miscompilation #37 was.\n\nA repo-wide scan turned up 28 candidates for the GHC-style `Note [Title]` convention (a free-standing block comment with a bracketed title, referenced from each dependent site via `-- See Note [Title]`). Two were done as part of #37 (`Note [Sequential scoping of Let bindings]` and `Note [Locals are uniquely named after renameShadowedNames]`). This issue tracks the rest.\n\nNot every item must become a Note. The low-priority ones are listed so the call is made consciously rather than by omission. Each box is independent; pick them off in any order.\n\nOne caveat on `CoreFn/Laziness.hs`: that file is adapted from the upstream `purs` compiler, so retitling its comments increases divergence from upstream. Weigh that before touching the laziness items.\n\n## High\n\n- [ ] **PSString is UTF-16 code units, not text** (`lib/Language/PureScript/PSString.hs`): the lone-surrogate invariant and the dual JSON encoding (string vs Word16 array) are relied on by CoreFn `FromJSON` and by the IR decode-or-escape fallback in another module.\n- [ ] **Compiling case expressions to decision trees** (`lib/Language/PureScript/Backend/IR.hs`): seven functions and four types implement the algorithm; today there is only a section banner and a paper URL.\n- [ ] **Graph-based dead code elimination for Lua** (`lib/Language/PureScript/Backend/Lua/DCE.hs`): six cooperating functions, zero explanatory comments. Needs an overview Note.\n- [ ] **Runtime lazy initialization** (`Names.hs`, `Backend/Lua/Fixture.hs`, `Backend/IR/Query.hs`, `Backend.hs`): the literal string `PSLUA_runtime_lazy` silently couples four modules, and renaming either side makes the fixture stop being emitted.\n- [ ] **runtimeLazy calling convention** (`CoreFn/Laziness.hs`, `Backend/Lua/Fixture.hs`): a cross-module ABI between generated code and the hand-written Lua fixture; the fixture side has no comment.\n- [ ] **Foreign bindings structure emitted by the Linker** (producer `Backend/IR/Linker.hs`, consumers `Backend/IR/DCE.hs`): DCE pattern-matches the exact expression shape the Linker emits, but the only comment sits on the consumer side.\n- [ ] **Laziness transform for recursive binding groups** (`CoreFn/Laziness.hs`): a module overview that three other modules cooperate with but have no named anchor to cite.\n- [ ] **Delay and force** (`CoreFn/Laziness.hs`): the two core attributes that both traversal passes and the ordering analysis depend on, documented only as a Haddock on one helper.\n- [ ] **Initialization order (USE-INIT / USE-USE / USE-IMMEDIATE)** (`CoreFn/Laziness.hs`): the named rules and graph encoding that justify `searchReachable`, `reachablesByIndex`, and the SCC fallback, currently floating untitled between two functions.\n\n## Medium\n\n- [ ] **Inline annotations and inlining heuristics** (`Backend/IR/Inliner.hs`, `Linker.hs`, `Optimizer.hs`): how an annotation travels from a pragma through `Ann` to the decision sites, spanning three modules.\n- [ ] **Inliner annotations must all be consumed** (`Backend/IR.hs`): the annotation map is a linear resource filled by `parseAnnotations`, drained by `useAnnotation`, with `runRepM` erroring on leftovers, which is how typo'd pragmas get reported.\n- [ ] **Newtype constructors are erased** (`Backend/IR.hs`): three sites silently implement one convention (construction is identity, application unwraps, matching skips the constructor) and must stay consistent. No comment today.\n- [ ] **Binding case scrutinees once** (`Backend/IR.hs`): bind a scrutinee once then refer to it, except for cheap literals and refs. Matters for semantics, since decision trees duplicate the scrutinee. Could fold into the decision-tree Note.\n- [ ] **Match history pruning** (`Backend/IR.hs`): remembering positive and negative constructor outcomes per scrutinee to skip redundant tag tests. Could be a subsection of the decision-tree Note.\n- [ ] **Unique node IDs across the UberModule** (`Backend/IR/DCE.hs`): the graph construction assumes Id uniqueness across foreigns, bindings, and exports, recorded only by a terse two-liner.\n- [ ] **MaxRoseTree: late flattening guarantees termination** (`CoreFn/Laziness.hs`): why the abort monad is interleaved with the tree, a termination argument currently smeared across several comment fragments.\n- [ ] **Lua reserved words as foreign export keys** (`Backend/Lua.hs`, `Lua/Key.hs`, `Lua/Name.hs`): the reserved-key round-trip spanning three modules, hinted at only by a two-line comment.\n- [ ] **Lua operator precedence** (`Backend/Lua/Types.hs`, `Lua/Printer.hs`): an anonymous block holding the Lua 5.x precedence table that the `HasPrecedence` instances transcribe and the Printer's parenthesization depends on.\n- [ ] **Foreign module source format** (`Backend/Lua/Linker/Foreign.hs`): the FFI file contract whose two non-obvious constraints are each load-bearing for a separate parser function plus a consumer in `Lua.hs`.\n- [ ] **Nullary functions and Prim.undefined** (`Backend/Lua.hs`): `ParamUnused` becoming a no-parameter function and `Prim.undefined` becoming a no-argument call are one arity-changing encoding that must stay in sync, but only one half is commented.\n- [ ] **Namespaced De Bruijn indices** (`Backend/IR/Types.hs`): `Ref`'s per-name index scheme; possibly fold into the existing `Note [Sequential scoping of Let bindings]`, since the two conventions are intertwined.\n\n## Low (decide consciously; inline may suffice)\n\n- [ ] **InternalIdentData is the extension point for generated idents** (`Names.hs`): already a complete Haddock, only two reference sites.\n- [ ] **Prim is always imported** (`Backend/IR.hs`): a short, single-site cross-pass dependency.\n- [ ] **IR is assumed well-typed** (`Backend/IR/Optimizer.hs`): a real pass-wide assumption, but currently one consuming site.\n- [ ] **unsafePerformIO in decodeString** (`PSString.hs`): a classic safety-argument Note, but one site and three lines.\n- [ ] **Compiling case alternatives to nested ifs** (`test/.../IR/Spec.hs`): an ASCII before/after diagram that belongs with `mkCase` rather than buried in a test.\n","author":{"url":"https://github.com/Unisay","@type":"Person","name":"Unisay"},"datePublished":"2026-06-12T11:21:28Z","url":"https://github.com/purescript-lua/purescript-lua/issues/44"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:6c5b1861-c7a1-cf1c-1b1b-6b12d42f3abe |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | D080:16EED3:94E8BF:BECFE5:6B00EF21 |
| html-safe-nonce | eacce26486778f7626821dd08cf4e4db6453454612ccdcb16161db77cad0234a |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJEMDgwOjE2RUVEMzo5NEU4QkY6QkVDRkU1OjZCMDBFRjIxIiwidmlzaXRvcl9pZCI6IjI5OTg5NDU0MTEzOTUyODQ3NjkiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | aab56eaaca127ba16db54e646a30e4d5f68f7a334412943e2e2ab074f75d07d0 |
| hovercard-subject-tag | issue:4648790627 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/purescript-lua/purescript-lua/44/issue_layout |
| twitter:image | https://opengraph.githubassets.com/61cdaa4a5b34d99be52c2ccac73b3faf194809ba3e92e7f59af97dba5bdc88a3/purescript-lua/purescript-lua/issues/44 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/61cdaa4a5b34d99be52c2ccac73b3faf194809ba3e92e7f59af97dba5bdc88a3/purescript-lua/purescript-lua/issues/44 |
| og:image:alt | While fixing #37 it became clear that several of the compiler's conventions are load-bearing but documented poorly: the same rule copy-pasted across call sites, an invariant spelled out only where ... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | Unisay |
| hostname | github.com |
| expected-hostname | github.com |
| None | 4ef498cbabcbe3c50befc7a5b743e7072ee770b4daf0e15e54801180d1fa91fc |
| turbo-cache-control | no-preview |
| go-import | github.com/purescript-lua/purescript-lua git https://github.com/purescript-lua/purescript-lua.git |
| octolytics-dimension-user_id | 131581790 |
| octolytics-dimension-user_login | purescript-lua |
| octolytics-dimension-repository_id | 587200487 |
| octolytics-dimension-repository_nwo | purescript-lua/purescript-lua |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 587200487 |
| octolytics-dimension-repository_network_root_nwo | purescript-lua/purescript-lua |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 9983dd5da06943f833c971dd5b6bc988e2858be5 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width