feat: add @context attribute for context-based output splitting#77

Open

keithharvey wants to merge 5 commits intorhys-vdw:mainfrom

keithharvey:contexts

Collaborator

keithharvey commented Mar 15, 2026 •

edited

Loading

Summary

Allow doc comments to declare @context tags (e.g. synced, unsynced) that partition the generated Lua library into mutually exclusive output files per context. Functions tagged with multiple contexts are placed into a shared base type, and EmmyLua class inheritance is generated so that context-specific types extend the shared one. Table names are only remapped when their members span more than one context bucket.

Motivation

The Recoil engine exposes a single Spring table in Lua, but different contexts (synced vs unsynced) have access to different subsets of functions. These options allow generating SpringSynced and SpringUnsynced type libraries from the same C++ sources without duplicating shared helper types that already exist in the per-file output.

Enabled Recoil PR

beyond-all-reason/RecoilEngine#2799

Note on Backward Comparability

If you don't add contexts, no projection happens and file structure is maintained.

LLM Disclosure

Prompt was pretty detailed but Opus 4.6 typed most of this one. I read the specs too. I think it checks out.

keithharvey mentioned this pull request

Add --table-mapping and --strip-helpers CLI options #74

Closed

keithharvey added a commit to keithharvey/RecoilEngine that referenced this pull request


          contexts for explicit output types

8c1df38

Use lua-doc-extractors @context feature to group output files into synced, unsynced and shared, see rhys-vdw/lua-doc-extractor#77

keithharvey mentioned this pull request

EmmyLua Synced-Unsynced-Shared Types beyond-all-reason/RecoilEngine#2799

Open

keithharvey added a commit to keithharvey/RecoilEngine that referenced this pull request


          contexts for explicit output types

8bc2619

Use lua-doc-extractors @context feature to group output files into synced, unsynced and shared, see rhys-vdw/lua-doc-extractor#77

keithharvey added a commit to keithharvey/RecoilEngine that referenced this pull request


          contexts for explicit output types

0f098b3

Use lua-doc-extractors @context feature to group output files into synced, unsynced and shared, see rhys-vdw/lua-doc-extractor#77

Collaborator Author

keithharvey commented Mar 17, 2026 •

edited

Loading

Ok so a couple changes to the generation today. I was just throwing everything not-context'ed into shared, which led to shared being out of control huge. So I changed it to preserve the file mapping for anything without a specified context. That keeps shared smol. This is more of a hybrid approach but keeps us non-breaking.

Verified the Recoil CI working https://github.com/keithharvey/RecoilEngine/actions/runs/23181438332/job/67357579048

keithharvey added a commit to keithharvey/RecoilEngine that referenced this pull request


          contexts for explicit output types

81f951e

Use lua-doc-extractors @context feature to group output files into synced, unsynced and shared, see rhys-vdw/lua-doc-extractor#77

keithharvey added a commit to keithharvey/RecoilEngine that referenced this pull request


          contexts for explicit output types

ed5b29e

Use lua-doc-extractors @context feature to group output files into synced, unsynced and shared, see rhys-vdw/lua-doc-extractor#77

keithharvey added a commit to keithharvey/RecoilEngine that referenced this pull request


          contexts for explicit output types

Use lua-doc-extractors @context feature to group output files into synced, unsynced and shared, see rhys-vdw/lua-doc-extractor#77

Collaborator Author

keithharvey commented Mar 22, 2026 •

edited

Loading

@rhys-vdw So I took another look at this after our discord conversation, then refactored the output layer. No more explicit "shared" handling in the CLI. It's internal to the bucket naming now. The CLI just gets a flat FileOutput[] from projectContextOutputs, and --file is a merge step on that same list, not a separate code path. Single write loop, no branching.

I also pulled isStandaloneContextDoc into a generic isFileAttributeDoc backed by a FILE_ATTRIBUTE_TYPES constant, so @context is just the first entry. Future file-level meta attrs just add to the constant and get the validation for free (must be first doc, only one per file). Plus combinatorial tests for 3 contexts covering all subset combinations.

keithharvey added a commit to keithharvey/RecoilEngine that referenced this pull request


          feat(Lua): EmmyLua Synced/Unsynced/Shared type splitting

18258d8

Use lua-doc-extractor's @context attribute to partition Lua API
documentation into synced, unsynced, and shared output files.
Tables appearing in multiple contexts (e.g. Spring) are remapped
to context-specific classes (SpringSynced, SpringUnsynced) that
inherit from a shared base (SpringShared).

Also adds CI support for overriding lua-doc-extractor repo/branch
via workflow_dispatch inputs and repository variables.

Depends on: rhys-vdw/lua-doc-extractor#77

Made-with: Cursor

keithharvey added a commit to keithharvey/RecoilEngine that referenced this pull request


          feat(Lua): EmmyLua Synced/Unsynced/Shared type splitting

bb18a73

Use lua-doc-extractor's @context attribute to partition Lua API
documentation into synced, unsynced, and shared output files.
Tables appearing in multiple contexts (e.g. Spring) are remapped
to context-specific classes (SpringSynced, SpringUnsynced) that
inherit from a shared base (SpringShared).

Also adds CI support for overriding lua-doc-extractor repo/branch
via workflow_dispatch inputs and repository variables.

Depends on: rhys-vdw/lua-doc-extractor#77

keithharvey added a commit to keithharvey/RecoilEngine that referenced this pull request


          feat(Lua): EmmyLua Synced/Unsynced/Shared type splitting

98893c0

Use lua-doc-extractor's @context attribute to partition Lua API
documentation into synced, unsynced, and shared output files.
Tables appearing in multiple contexts (e.g. Spring) are remapped
to context-specific classes (SpringSynced, SpringUnsynced) that
inherit from a shared base (SpringShared).

Also adds CI support for overriding lua-doc-extractor repo/branch
via workflow_dispatch inputs and repository variables.

Depends on: rhys-vdw/lua-doc-extractor#77

keithharvey added a commit to keithharvey/RecoilEngine that referenced this pull request


          feat(Lua): EmmyLua Synced/Unsynced/Shared type splitting

a884e58

Use lua-doc-extractor's @context attribute to partition Lua API
documentation into synced, unsynced, and shared output files.
Tables appearing in multiple contexts (e.g. Spring) are remapped
to context-specific classes (SpringSynced, SpringUnsynced) that
inherit from a shared base (SpringShared).

Also adds CI support for overriding lua-doc-extractor repo/branch
via workflow_dispatch inputs and repository variables.

Depends on: rhys-vdw/lua-doc-extractor#77

keithharvey force-pushed the contexts branch from 0225903 to 0142194 Compare

March 25, 2026 16:23

keithharvey added 3 commits

March 25, 2026 12:14


          feat: add @context attribute for context-based output splitting

457cc7b

Allow doc comments to declare @context tags (e.g. synced, unsynced)
that partition the generated Lua library into mutually exclusive
output files per context. Functions tagged with multiple contexts
are placed into a shared base type, and EmmyLua class inheritance
is generated so that context-specific types extend the shared one.
Table names are only remapped when their members span more than one
context bucket.


          for unlabelled contexts fall back to file name

713f74e

shared was out of control big


          fix: functional output types

So I took another look at this and refactored the output layer. No more explicit shared handling in the CLI — it's internal to the bucket naming now. The CLI just gets a flat  from , and  is a merge step on that same list, not a separate code path. Single write loop, no branching.

I also pulled  into a generic  backed by a  constant — so  is just the first entry. Future file-level meta attrs just add to the constant and get the validation for free (must be first doc, only one per file). Plus combinatorial tests for 3 contexts covering all subset combinations.

keithharvey force-pushed the contexts branch from 0142194 to 6510520 Compare

March 25, 2026 18:14

keithharvey added 2 commits

March 26, 2026 12:49


          fix shared bug

100aef0


          no inheritance for shared contexts

119cef7

Realized that my AST was producing Shared for all shared functions, and that was accuate. We dont want devs to have to memorize whats in SpringShared and whats in SpringSynced, we want callers to be unambiguous and 1:1

keithharvey added a commit to keithharvey/RecoilEngine that referenced this pull request


          feat(Lua): EmmyLua Synced/Unsynced/Shared type splitting

e2a1062

Use lua-doc-extractor's @context attribute to partition Lua API
documentation into synced, unsynced, and shared output files.
Tables appearing in multiple contexts (e.g. Spring) are remapped
to context-specific classes (SpringSynced, SpringUnsynced) that
inherit from a shared base (SpringShared).

Also adds CI support for overriding lua-doc-extractor repo/branch
via workflow_dispatch inputs and repository variables.

Depends on: rhys-vdw/lua-doc-extractor#77

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet