René's URL Explorer Experiment


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

direct link

Domain: github.com


Hey, it has json ld scripts:
{"@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-profiling0
react-import-mapreact,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-controllervoltron_issues_fragments
route-actionissue_layout
fetch-noncev2:6c5b1861-c7a1-cf1c-1b1b-6b12d42f3abe
current-catalog-service-hash81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114
request-idD080:16EED3:94E8BF:BECFE5:6B00EF21
html-safe-nonceeacce26486778f7626821dd08cf4e4db6453454612ccdcb16161db77cad0234a
visitor-payloadeyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJEMDgwOjE2RUVEMzo5NEU4QkY6QkVDRkU1OjZCMDBFRjIxIiwidmlzaXRvcl9pZCI6IjI5OTg5NDU0MTEzOTUyODQ3NjkiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ==
visitor-hmacaab56eaaca127ba16db54e646a30e4d5f68f7a334412943e2e2ab074f75d07d0
hovercard-subject-tagissue:4648790627
github-keyboard-shortcutsrepository,issues,copilot
google-site-verificationApib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I
octolytics-urlhttps://collector.github.com/github/collect
analytics-location///voltron/issues_fragments/issue_layout
fb:app_id1401488693436528
apple-itunes-appapp-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/purescript-lua/purescript-lua/44/issue_layout
twitter:imagehttps://opengraph.githubassets.com/61cdaa4a5b34d99be52c2ccac73b3faf194809ba3e92e7f59af97dba5bdc88a3/purescript-lua/purescript-lua/issues/44
twitter:cardsummary_large_image
og:imagehttps://opengraph.githubassets.com/61cdaa4a5b34d99be52c2ccac73b3faf194809ba3e92e7f59af97dba5bdc88a3/purescript-lua/purescript-lua/issues/44
og:image:altWhile 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:width1200
og:image:height600
og:site_nameGitHub
og:typeobject
og:author:usernameUnisay
hostnamegithub.com
expected-hostnamegithub.com
None4ef498cbabcbe3c50befc7a5b743e7072ee770b4daf0e15e54801180d1fa91fc
turbo-cache-controlno-preview
go-importgithub.com/purescript-lua/purescript-lua git https://github.com/purescript-lua/purescript-lua.git
octolytics-dimension-user_id131581790
octolytics-dimension-user_loginpurescript-lua
octolytics-dimension-repository_id587200487
octolytics-dimension-repository_nwopurescript-lua/purescript-lua
octolytics-dimension-repository_publictrue
octolytics-dimension-repository_is_forkfalse
octolytics-dimension-repository_network_root_id587200487
octolytics-dimension-repository_network_root_nwopurescript-lua/purescript-lua
turbo-body-classeslogged-out env-production page-responsive
disable-turbofalse
browser-stats-urlhttps://api.github.com/_private/browser/stats
browser-errors-urlhttps://api.github.com/_private/browser/errors
release9983dd5da06943f833c971dd5b6bc988e2858be5
ui-targetfull
theme-color#1e2327
color-schemelight dark
react-app-nameissues

Links:

Skip to contenthttps://github.com/purescript-lua/purescript-lua/issues/44#start-of-content
https://github.com/
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fpurescript-lua%2Fpurescript-lua%2Fissues%2F44
GitHubRepository hosting, code review, and collaborationhttps://github.com/platform
CopilotAI coding agent for tasks, projects, and automated workhttps://github.com/features/copilot
ActionsCI/CD and automationhttps://github.com/features/actions
Code QualityQuality analysis, fixes, and enforcementhttps://github.com/features/code-quality
CodespacesCloud development environmentshttps://github.com/features/codespaces
Code SecurityVulnerability detection and remediationhttps://github.com/security/advanced-security/code-security
Secret ProtectionSecret scanning and leak preventionhttps://github.com/security/advanced-security/secret-protection
All Featureshttps://github.com/features
Documentationhttps://docs.github.com/en
Traininghttps://learn.github.com/skills
Certificationshttps://learn.github.com/credentials
Build with Copilothttps://github.com/features/ai
Customize Copilothttps://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-copilot-overview
Integrationshttps://github.com/marketplace
Trending reposhttps://github.com/trending
GitHub Sponsorshttps://github.com/open-source/sponsors
Developer articleshttps://github.com/resources/articles
ChangelogYour source for the latest features, improvements, and fixes across GitHub products, all in one place.https://github.blog/changelog/
Enterpriseshttps://github.com/enterprise
Teamhttps://github.com/team
Startupshttps://github.com/enterprise/startups
Nonprofitshttps://github.com/solutions/industry/nonprofits
Healthcarehttps://github.com/solutions/industry/healthcare
Financial serviceshttps://github.com/solutions/industry/financial-services
Manufacturinghttps://github.com/solutions/industry/manufacturing
Governmenthttps://github.com/solutions/industry/government
See all industrieshttps://github.com/solutions/industry
Why GitHubhttps://github.com/why-github
Customer Storieshttps://github.com/customer-stories
Business insightshttps://github.com/solutions/executive-insights
Trust Centerhttps://github.com/trust-center
GitHub Advanced SecurityEnterprise-grade code securityhttps://github.com/security/advanced-security
Copilot for businessEnterprise-grade AI featureshttps://github.com/features/copilot/copilot-business
Premium SupportEnterprise-grade 24/7 supporthttps://github.com/enterprise/premium-support
Documentationhttps://docs.github.com/en
Resource centerhttps://github.com/resources
Bloghttps://github.blog/
Events & webinarshttps://github.com/resources/events
Community Forumhttps://github.com/orgs/community/discussions
Customer Storieshttps://github.com/customer-stories
Integrationshttps://github.com/marketplace
Customer supporthttps://help.github.com/
Traininghttps://learn.github.com/skills
GitHub Statushttps://www.githubstatus.com/
Abouthttps://github.com/about
Partnershttps://github.com/partners
Changeloghttps://github.blog/changelog/
GitHub UniverseThe event for developers, by developers — talks, workshops, and what’s next for GitHub.https://githubuniverse.com/
Pricinghttps://github.com/pricing
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fpurescript-lua%2Fpurescript-lua%2Fissues%2F44
Sign uphttps://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fvoltron%2Fissues_fragments%2Fissue_layout&source=header-repo&source_repo=purescript-lua%2Fpurescript-lua
Reloadhttps://github.com/purescript-lua/purescript-lua/issues/44
Reloadhttps://github.com/purescript-lua/purescript-lua/issues/44
Reloadhttps://github.com/purescript-lua/purescript-lua/issues/44
purescript-luahttps://github.com/purescript-lua
purescript-luahttps://github.com/purescript-lua/purescript-lua
Codehttps://github.com/purescript-lua/purescript-lua
Issues48 (48)https://github.com/purescript-lua/purescript-lua/issues
Pull requestshttps://github.com/purescript-lua/purescript-lua/pulls
Discussionshttps://github.com/purescript-lua/purescript-lua/discussions
Actionshttps://github.com/purescript-lua/purescript-lua/actions
Projectshttps://github.com/purescript-lua/purescript-lua/projects
Security and qualityhttps://github.com/purescript-lua/purescript-lua/security
Insightshttps://github.com/purescript-lua/purescript-lua/insights
https://github.com/purescript-lua/purescript-lua
New issuehttps://github.com/login?return_to=https://github.com/purescript-lua/purescript-lua/issues/44
New issuehttps://github.com/login?return_to=https://github.com/purescript-lua/purescript-lua/issues/44
#130https://github.com/purescript-lua/purescript-lua/pull/130
Document load-bearing invariants and subsystems with GHC-style Noteshttps://github.com/purescript-lua/purescript-lua/issues/44#top
#130https://github.com/purescript-lua/purescript-lua/pull/130
documentationImprovements or additions to documentationhttps://github.com/purescript-lua/purescript-lua/issues?q=state%3Aopen%20label%3A%22documentation%22
https://github.com/Unisay
Unisayhttps://github.com/Unisay
on Jun 12, 2026https://github.com/purescript-lua/purescript-lua/issues/44#issue-4648790627
#37https://github.com/purescript-lua/purescript-lua/issues/37
#37https://github.com/purescript-lua/purescript-lua/issues/37
#37https://github.com/purescript-lua/purescript-lua/issues/37
Unisayhttps://github.com/Unisay
documentationImprovements or additions to documentationhttps://github.com/purescript-lua/purescript-lua/issues?q=state%3Aopen%20label%3A%22documentation%22
on Jun 15, 2026https://github.com/purescript-lua/purescript-lua/issues/44#event-26762767807
Unisayhttps://github.com/Unisay
on Jun 25, 2026https://github.com/purescript-lua/purescript-lua/issues/44#event-27193824996
Merge pull request #124 from purescript-lua/issue-44/notes-core-invar…https://github.com/purescript-lua/purescript-lua/commit/c2c89d8a9677be6149179b35f14e342926baa569
#124https://github.com/purescript-lua/purescript-lua/pull/124
c2c89d8https://github.com/purescript-lua/purescript-lua/commit/c2c89d8a9677be6149179b35f14e342926baa569
Merge pull request #125 from purescript-lua/issue-44/notes-decision-t…https://github.com/purescript-lua/purescript-lua/commit/7b9b280b9b8dea7864c178555858272b7770e90f
#125https://github.com/purescript-lua/purescript-lua/pull/125
7b9b280https://github.com/purescript-lua/purescript-lua/commit/7b9b280b9b8dea7864c178555858272b7770e90f
Merge pull request #127 from purescript-lua/issue-44/notes-lazinesshttps://github.com/purescript-lua/purescript-lua/commit/a2832b413fdf8c32a7a4ff14a674b2d299fbb007
#127https://github.com/purescript-lua/purescript-lua/pull/127
a2832b4https://github.com/purescript-lua/purescript-lua/commit/a2832b413fdf8c32a7a4ff14a674b2d299fbb007
Merge pull request #128 from purescript-lua/issue-44/notes-lua-backendhttps://github.com/purescript-lua/purescript-lua/commit/ddc40787183442008962175b7da4385e4a3d4f55
#128https://github.com/purescript-lua/purescript-lua/pull/128
ddc4078https://github.com/purescript-lua/purescript-lua/commit/ddc40787183442008962175b7da4385e4a3d4f55
Merge pull request #129 from purescript-lua/issue-44/notes-ir-inlinerhttps://github.com/purescript-lua/purescript-lua/commit/593704b4d7b1a0114b849bee3dcc91d229e65664
#129https://github.com/purescript-lua/purescript-lua/pull/129
593704bhttps://github.com/purescript-lua/purescript-lua/commit/593704b4d7b1a0114b849bee3dcc91d229e65664
Merge pull request #130 from purescript-lua/issue-44/notes-low-itemshttps://github.com/purescript-lua/purescript-lua/commit/9242f20d0f8ad41a6a4bf32d46e6f1e71401c9eb
#130https://github.com/purescript-lua/purescript-lua/pull/130
9242f20https://github.com/purescript-lua/purescript-lua/commit/9242f20d0f8ad41a6a4bf32d46e6f1e71401c9eb
Unisayhttps://github.com/Unisay
completedhttps://github.com/purescript-lua/purescript-lua/issues?q=is%3Aissue%20state%3Aclosed%20archived%3Afalse%20reason%3Acompleted
#130https://github.com/purescript-lua/purescript-lua/pull/130
on Jun 25, 2026https://github.com/purescript-lua/purescript-lua/issues/44#event-27216009577
Sign up for freehttps://github.com/signup?return_to=https://github.com/purescript-lua/purescript-lua/issues/44
Sign in to commenthttps://github.com/login?return_to=https://github.com/purescript-lua/purescript-lua/issues/44
documentationImprovements or additions to documentationhttps://github.com/purescript-lua/purescript-lua/issues?q=state%3Aopen%20label%3A%22documentation%22
https://github.com
Termshttps://docs.github.com/site-policy/github-terms/github-terms-of-service
Privacyhttps://docs.github.com/site-policy/privacy-policies/github-privacy-statement
Securityhttps://github.com/security
Statushttps://www.githubstatus.com/
Communityhttps://github.community/
Docshttps://docs.github.com/
Contacthttps://support.github.com?tags=dotcom-footer

Viewport: width=device-width


URLs of crawlers that visited me.