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

Open

keithharvey wants to merge 7 commits into

rhys-vdw:mainfrom

keithharvey:contexts

Collaborator

keithharvey commented Mar 15, 2026 •

edited

Loading

Part of BAR type-error cleanup. Tooling

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

refactor(Lua): Spring.X -> SpringBucket.X 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

This was referenced Apr 11, 2026

[Types] LLM-driven type-error transform capstone beyond-all-reason/Beyond-All-Reason#7407

Draft

BAR type-error cleanup: coordinated merge beyond-all-reason/Beyond-All-Reason#7408

Open

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


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

a669668

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 and others added 2 commits

April 15, 2026 12:27


          refactor: group outputs by @function table prefix, drop @context indi…

65b71fd

…rection

Previously the extractor partitioned output files via a file-level
@context tag and rewrote Spring.X → SpringShared/SpringSynced/
SpringUnsynced.X at emit time. Now that every Recoil binding
authors its table prefix directly (e.g. @function SpringSynced.X),
the remap and partition steps are no longer load-bearing — doc
comments can serve as the single source of truth for bucketing.

Delete: partitionDocsByContext, remapDocTableNames,
promoteMultiContextDocs, findMultiContextTables,
generateClassDeclarations, applyFileContexts.

Add: projectOutputs (group by literal table prefix in @function)
and lintDuplicateDeclarations (error on the same @function name
declared across multiple files, replacing the previous auto-promote-
to-shared magic). removeContextAttributes stays as a defensive no-op
stripper in case a stray @context sneaks in.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>


          feat: @context fallback routing for non-Spring tables

a67dbd5

The primary simplification (65b71fd) routed output files purely by the
table prefix of each doc's @function/@table/@field declaration. That
works for the three Spring* tables, but non-Spring tables like
UnitScriptTable and ObjectRenderingTable carry no bucket prefix —
their docs all fell through to shared.lua instead of landing in
synced.lua / unsynced.lua as the pinned stubs had them.

Resurrect the minimum needed: applyFileContexts() to propagate a
standalone file-level `@context` doc onto every other doc in the same
file, and a fallback tier in outputFileFor() that routes by that
`@context` when no Spring prefix is present. Spring prefix still wins
on any doc that carries one, so a stray `@context` in a Spring file
can't drag its decls out of their declared bucket.

What stays deleted from the old model: multi-context partitioning,
Spring.X -> SpringBucket.X name-rewriting, auto-dedup of multi-context
duplicates, class-inheritance preamble generation, per-file filename-
based output. None of those are needed once authors write bucket
prefixes explicitly.

Recoil source now keeps @context on exactly two files
(LuaObjectRendering.cpp, LuaUnitScript.cpp) — both contain non-Spring
tables that would otherwise have no bucket signal.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Collaborator Author

keithharvey commented Apr 15, 2026

Stripped a lot of complexity out. Because we switched to the exclusive buckets being the first-class recoil example/decorator pattern, a lot of complexity over here (such as auto-bucketing) became worth removing.

Owner

rhys-vdw commented Apr 29, 2026

I'm just going to leave this PR open until everything settles. Cool?

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

Labels

None yet