Authoring forked library types
Some Defold libraries ship no usable structured type source — no
.script_api, no inline LuaLS (---@) annotations,
and no README that documents the surface precisely enough to parse. The
LuaLS, .script_api, and markdown
front-ends all ingest a primary source and generate a declaration; a library
with none of those has nothing to generate from. Its .d.ts must be written
by hand — either forked from an existing hand-authored declaration or authored
fresh — and vendored into the library's folder in the toolchain repo as first-party
source. resolve then prints the
vendored declaration into the consumer's project, the way it prints the
generated lanes' declarations.
Like the other lanes, adding such a library is data, not code: you add one
fork to the library's library.json in its folder,
packages/library-types/data/<version>/<host>/<owner>/<repo>/ (the newest version-named folder), vendor
the .d.ts into the folder's fork/, run the generation command, and commit the
library's files. Every path a fork names is relative to the
library folder, except apiDoc and fidelity, which are relative to
packages/library-types/, where the tools write their reports. The toolchain's authored front-end
(packages/cli/src/library/sync-authored-types.ts) is the reusable
machinery; you touch config and fixtures, not the pipeline.
This page is for library-type authors. Library data lives in the toolchain repo under
packages/library-types/data/, so you add or change a library with a pull request there, not todefold-typescript/library-data. If you only want to use a vendored library in your own game, you need nothing here — just declare the dependency and runresolve.The
buncommands on this page run from the toolchain root. Each tool reads and writes the library data underpackages/library-types/data/and writes its reports toapi-doc/andfidelity/inpackages/library-types/.
The decision: fork, hand-author, or keep?
Reach this lane only after ruling out the generated ones. Ask, in order:
- Does upstream ship a
.script_api? → it is a script_api target. - Does its Lua carry inline
---@annotations? → it is a LuaLS target. - Does its README document the full surface precisely? → it may be a
markdown target (gated on a fidelity comparison; a lossy README is a
no-goand the library does not regenerate from markdown). - None of the above → it is an authored target, and you choose between fork, hand-author, and keep.
A markdown no-go is a verdict on the markdown source, not on the ts-defold
dependency. It says the README cannot regenerate the surface; it says nothing
about where the surface should be maintained. That second question is this
lane's, and a no-go library reaches question 4 with it still open — so run the
cost model below on it exactly as you would on a library that never had a README
at all. keep is a legitimate answer, but it has to be chosen, not inherited
from the refusal. persist.persist and orthographic.camera are the worked
examples.
The cost model
An authored .d.ts has no upstream source to regenerate from, so every future
upstream API change is a manual edit to the vendored declaration. That is the
standing cost. Weigh it against the gain of severing ts-defold: a first-party
authored surface is authored-here, carries its own upstream repo/tag pin
(not the shared ts-defold/library commit), and is maintained on the toolchain repo's
own cadence rather than inherited from a third-party vendoring.
- Fork — copy the retired ts-defold
.d.tsverbatim as the first-party fixture. Zero fidelity risk (the surface is identical to what shipped), and the provenance moves to the real upstream. Best when the ts-defold binding is already correct and the surface is small and stable, so the manual-maintenance cost is low. - Hand-author — write a fresh
.d.tsfrom the library's documentation. Only worth it when the ts-defold binding is wrong or absent and the surface is small enough to author confidently. - Keep — leave the library ts-defold-sourced. Correct when the surface is
large or churns often, so the manual-maintenance cost outweighs the
provenance gain, or when a generated lane is likely to become available.
Spent for the current corpus: every library the ts-defold registry once
carried has severed and
library-targets.jsonholds"targets": [](see 5. Cut the library over and validate), so a library reaching this decision today has no ts-defold binding to keep — the real choice is fork versus hand-author.
1. Add a fork to the library's library.json
Start with library add, which writes the
folder, library.json and reviewed.json from the archive URL:
bunx @defold-typescript/cli library add https://github.com/owner/mylib/archive/refs/tags/1.2.3.zip --data packages/library-types/dataThen add the forks entry to library.json by hand, and vendor the upstream Lua
it measures against. library add writes no fork, and when it wrote a recipe.json
for a generated module, delete that entry and its source/ files if the fork
replaces it.
Each library sits in its own folder under the data folder, named for its
repository: the URL's last path segment, lowercased, without .git
(https://github.com/britzl/defcon is defcon/). The folder pins the library's
own upstream repository and ref once — an authored library is the sole maintainer
of its namespace, so it carries its own repo/ref rather than the shared
vendored commit:
| File | Field | Required | What it is |
|---|---|---|---|
library.json | repo | yes | The GitHub or Codeberg repository URL, e.g. https://github.com/britzl/defcon. upstream:library-check reads no other host. |
library.json | license | no | SPDX-style license id, surfaced by the library page's provenance block. Defaults to "". |
library.json | refKind | no | "tag" or "commit" when upstream publishes no stable release (GitHub's latest release skips prereleases), so the docs page's adopt step names the pinned archive instead of linking a releases page. Omit it for a repo with releases. |
reviewed.json | ref | yes | The immutable upstream ref to pin. Prefer the newest stable release tag (git ls-remote --tags <repo>) — never invent one. When upstream publishes no tags, pin the current default-branch commit SHA instead; the docs page renders the full SHA as the source ref. |
Each forked module is one entry in library.json's forks list:
| Field | Required | What it is |
|---|---|---|
authored | yes | Path of the vendored authored/forked .d.ts, relative to the library folder — fork/<moduleId>.d.ts. |
moduleId | yes | The library's runtime require path, dotted (e.g. defcon.console). This is the declare module name inside the vendored .d.ts. |
namespace | yes | The artifact stem — the emitted file is api-doc/<namespace>.json. Either a bare stem (defcon) or the dotted moduleId (orthographic.camera): fork onto the retired module name when it already equals the publish namespace, and reach for a bare stem only when nothing else owns it. The orthographic.camera worked example below settles the choice. |
apiDoc | yes | The site's model output path (api-doc/<namespace>.json). |
fidelity | no | Defaults to fidelity/<namespace>.json. A fork records no fidelity artifact (see below); the field mirrors the sibling lanes for a future hand-authored target that wants one. |
upstreamLua | one of two | Library-folder-relative paths of the vendored upstream .lua this target's surface is measured against. See surface parity. |
parityVerdict | one of two | Why this target vendors no upstream .lua: { "reason": ..., "note": ... }. Mutually exclusive with upstreamLua. |
instanceType | when upstream has methods | The exported interface the fork declares the module's instances with, e.g. BehaviorTree. Required once the vendored upstream defines a function M:name(…) method, which parity measures against that interface's methods; it needs upstreamLua. See surface parity. |
A missing required field fails loudly, naming the field, the offending entry and
its library.json. So does a folder named other than its repository, a folder
without reviewed.json, and a module another library folder already names.
upstreamLua and parityVerdict are individually optional but jointly
mandatory: every entry declares exactly one. Neither field is in the required
list, yet an entry declaring neither — or both — fails the same way, naming the
offender. That is deliberate. A target with no declaration would otherwise sit in
the config indistinguishable from a measured-and-clean one, so the config cannot
express "nobody has looked at this yet"; you either measure the surface or record
why you cannot.
2. Vendor the .d.ts and generate the artifacts
Put the authored/forked declaration at the authored path. For a fork of a
ts-defold binding, that is the ts-defold lane's codemodded output
(codemodDeclaration in packages/cli/src/library/sync-library-types.ts) — not
the raw ts-defold fixture, which the ts-defold lane type-maps on the
way out (hash/url/vmath.vector3 → Hash/Url/Vector3) while the authored
lane emits its input verbatim, so forking the fixture would ship upstream's Lua
type names and fail the dts-declaration-validity gate. The two forms coincide
when the library references no mapped core types (persist), which is why the rule
is safe to state unconditionally. For a hand-authored library, it is the
declaration you wrote. Either way it must be a
declare module '<moduleId>' ambient — the target form the emit passes through
unchanged. When the library is a native extension, the declaration also carries
/** @globalTable */ so project imports lower to its runtime global rather
than a require (see
Module form).
Then run this command from the toolchain root:
# check library data, then lower api-doc/<namespace>.json — the site's model
bun packages/cli/src/bin.ts library check --data packages/library-types/data --api-doc-out packages/library-types/api-docresolveserves the vendored.d.tswith one change: each member upstream documents carries upstream's LuaDoc summary as its doc comment unless the fork's own comment is pinned to that text (see Upstream LuaDoc import). Nothing else is transformed: an authored source is already target-form, so the served types are the vendored types.--api-doc-outmakeslibrary check, once its checks pass, runextractApiDocover that printed declaration under the pinned publishnamespace, producing theapi-doc/<namespace>.jsonthe/apipage renders. A member's@deprecatedtag carries through to the page as aDeprecatedline, with the tag's own text when it has any — so mark a deprecated member in the fork rather than only saying so in its prose.
There is no fetch command — the source is vendored by hand, not snapshotted from a primary source — and no fidelity command: there is no primary source to compare against, and the emit is lossless by construction (see below).
3. Emission fidelity is by construction
The generated lanes report a coverage number because a parse can lose type
information the original had. An authored .d.ts cannot: the printed declaration
is the vendored source plus doc comments, so the go/no-go gate is a
forked-vs-printed identity diff on types — what resolve prints, with its
comments removed, is identical to the vendored fork/<moduleId>.d.ts with its
comments removed. sync-authored-types.test.ts asserts this for every fork, and
print-library.test.ts checks the lane dispatch serves that print. No
fidelity/ artifact is written.
Read that gate narrowly. It proves emission fidelity — both sides of the diff
are the toolchain repo's own files, so all it certifies is that the print loses no
type relative to the vendored .d.ts. It says nothing about whether the vendored
surface matches upstream, and there is no primary source to measure it against —
that is what "no structured type source" means. A verbatim fork inherits
whatever accuracy the binding it copied already had; a corrected fork (see
defsave below) is only as accurate as the manual audit behind it. So pin the
corrections with per-library shape assertions in
packages/cli/src/library/sync-authored-types.test.ts — the closest thing
this lane has to an upstream check.
4. Surface parity against the upstream Lua
The previous section holds for types: upstream ships none, so there is nothing to measure a fork's type annotations against. It does not hold for the surface. Upstream Lua declares its member names and its parameter names in plain source, and those are comparable — a fork that never got a member, or that dropped a trailing parameter, is measurable without any type information at all.
Opting a target in
The upstream path is derived from moduleId: replace the dots with slashes and
append .lua, so in.button is in/button.lua and richtext.richtext is
richtext/richtext.lua. Fetch that path at the library's pinned ref and vendor
it under the library folder's source/upstream/, at the same path it has
upstream — so britzl/defold-input at in/button.lua lands at
defold-input/source/upstream/in/button.lua. Vendor only the module file
the target names, never the whole repository: the parity report measures only the
files the target names, so any other copy is dead weight.
The reader accepts two closing forms: a bare return M, and a callable module's
return setmetatable(M, { … }) — on one line or spread over several, as long as it
starts at column 0. It refuses a metatable carrying __index, and one named by a
variable whose keys it cannot see, in both cases throwing rather than parsing. A
delegated member never appears at column 0, so parsing anyway would report a short
surface as the whole one and raise the target's coverage for it. An indented
return setmetatable(instance, { … }) inside a factory function is not the module's
close and is ignored, which is what the column-0 rule buys.
The reader also reads the entries of the returned table's constructor: a column-0
local M = { whose entries run over the following lines gives each top-level
name = value entry as a member, a function(…) value as a callable one, so this
constructor counts Client as M.Client = Client would:
local M = {
Client = Client,
}A constructor that closes on its opening line, local M = { NAME = "admob" }, is read
too. A nested table's keys stay out. An entry it cannot name — a bracketed ["key"] or
a positional value — or entries written on an opening line whose constructor continues
past it throw, for the same reason a delegating metatable does.
A class module's column-0 function M:name(…) methods are read as well, each with its
named parameters and without the implicit self. Parity keys them
<instanceType>:<name> and compares them with the methods of the interface the entry
names as its instanceType, so a missing or short method costs callable coverage like
any other member. The self-index M.__index = M that makes the module a class adds no
member. A column-0 colon method on any other table throws, since its instances are
reached through nothing the reader sees, and so does a name defined both as a method
and as a . member.
List the vendored paths in upstreamLua, then regenerate:
bun packages/cli/src/library/authored-parity.ts --data packages/library-types/data
bun packages/cli/src/library/native-parity.ts --data packages/library-types/dataThat writes fidelity/authored/<namespace>.json per measured target. Both halves
of the upstream surface are compared, on two axes reported side by side. The
declared side of each is the fork's api-doc/<namespace>.json — the surface the
/api page renders, so the report measures what a reader actually sees.
Only the fork's own members are compared. An api-doc element marked global: true
is a file-scope name the library installs into the environment, defined upstream in
files the target does not vendor, so it is a member of no module and enters neither
axis — calling one a phantom would describe real upstream API as invented.
declaredGlobals records how many were set aside: 30 for deftest, whose telescope
assertions are ambient, and 87 for boom, which declares one module member beside its
whole ambient game API.
The callable axis, upstream members carrying a parameter list against api-doc
FUNCTION elements:
| Field | What it counts |
|---|---|
upstreamMembers | Callable members the upstream module defines. |
declaredGlobals | Declared names the fork installs into the environment rather than onto the module. Counted, never compared. |
declaredMembers | Functions the fork declares. |
missingMembers | Upstream members the fork does not declare at all. |
phantomMembers | Declared members upstream does not have. |
arityMismatches | Shared names whose parameter counts disagree, each with both numbers — the fork's being the widest signature it declares. Names are not compared — a fork may rename parameters freely. |
undocumentedMembers | Upstream prose that reached neither the fork nor the import — a member whose accepted block carries no summary to lower, being nothing but tags or nothing but the member's own name. |
importedDocs | Declared elements carrying upstream's own doc, its summary or only its parameter and return docs, because the fork supplied none or did not pin its own. Counted on both axes. |
refusedDocBlocks | Refused upstream blocks the fork left unanswered — neither documented in the fork's own words nor excused by a recorded parityException. Counted on both axes, and the one term that reports prose the import never saw. Authoring the brief clears the charge. |
refusedDocBlocksTotal | The raw refusal count, before the answered and excused ones are subtracted. Kept so a refusedDocBlocks of 0 cannot be misread as upstream writing no ---only blocks. |
variadicMembers | Shared members compared against a floor rather than an exact count, upstream being variadic. |
overloadedMembers | Shared members the fork declares as several overloads, so the comparison had a set of counts to accept rather than one. |
placeholderMembers | Shared members whose upstream definition ends in a bare _ with no ... after it, dropped before the counts were compared. |
callableCoverage | Fraction of upstream members that are declared and agree on arity. |
An upstream definition ending in ... has no fixed parameter count to disagree
with, so function M.play(...) is compared against its named parameters as a
floor: the fork must declare at least them, and anything beyond is the rest.
variadicMembers says how many shared members that weaker check covered, so a
callableCoverage of 1 over a variadic surface cannot be read as fully verified.
A fork may also declare one name as several overloads, modelling an upstream body
that branches on whether an argument was passed — monarch.transitions.gui.create
declares create(node) and create() against upstream's single M.create(node)
and its if node then branch. That is a set of call shapes, and the member agrees
when any one of them meets the rule above; reading a single count would charge a
correct fork for whichever overload the api-doc happened to list last. A
disagreement is still reported as one number, the widest shape the fork offers.
overloadedMembers counts every member compared that way, for the same reason
variadicMembers exists: agreeing because one shape matched is a weaker result
than agreeing outright.
A generated module can also end a definition in a bare _ that no body reads and
no doc comment describes — nakama.lua opens "Code generated by
codegen/generate-rest.go" and 66 of its exports end that way. A trailing discard
is not a parameter a consumer can pass meaningfully, so charging the fork for
omitting it would report the instrument's defect as the fork's. It is dropped
before the counts are compared, and only when it is last: a _ upstream names in
the middle still has to be passed for the parameters after it to land. A _ written
before a ... tail is last only in appearance — a caller fills that slot for any
vararg to land — so it is still charged.
placeholderMembers counts every member the drop covered, whether or not it
changed the verdict. The drop is not merely subtractive — a fork that declared the
discard as a real parameter disagrees once it is gone, which is how
create_protobuf_any was found declaring a second parameter upstream does not
take.
The field axis, upstream constants (M.SOME_CONSTANT = "X") against api-doc
VARIABLE elements. A TYPEDEF is a type rather than a runtime member and enters
neither axis:
| Field | What it counts |
|---|---|
upstreamFields | Non-callable members the upstream module defines. |
declaredFields | Non-callable members the fork declares. |
missingFields | Upstream constants the fork does not declare — values its users cannot reach. |
phantomFields | Declared constants upstream has in neither half — names the fork invented. |
fieldCoverage | Fraction of upstream fields the fork declares. |
A name that is callable on either side belongs to the callable axis and is never also counted as a field, so one defect is never charged twice. A fork that declared an upstream function as a constant of a callable type would otherwise be charged on both axes at once — once as a missing member, once as a phantom field — and the second charge would describe an upstream name as invented. No measured target produces the shape today, the one that did having since been corrected, so the rule stands on the classifier rather than on any corpus case.
floors in the library's library.json ratchets both axes per module, keyed
by moduleId as { "callable": 1, "field": 1 }, each against its own floor: either
may rise, neither may fall. A regeneration that lowers either number reds the gate, a
floor entry that names only one axis is rejected when the library is read rather than
leaving the other unratcheted, and library check
measures the fork against the same floors.
A non-empty missingMembers, phantomMembers, arityMismatches,
missingFields, or phantomFields is a correction to make in the fork — never a
number to re-baseline. The measurement exists so the gap stays visible while it
is being closed; the current numbers are the honest starting point, not a target.
The committed reports are held to a fresh measurement for the same reason:
authored-parity-floor.test.ts re-measures every target and reds when a committed
report differs, so a re-vendor, fork edit or reader change that moves a number reds
until bun run --cwd packages/library-types parity rewrites the reports and the
coverage change is reviewed.
nakama is the worked example and the rollout's closing statement: its fork
declared 166 functions against upstream's 156 with only 4 agreeing on arity —
the corpus's worst case, and the last target to reach a full callableCoverage.
Closing it took every kind of correction this page describes. Requests upstream had
flattened into positional parameters were still declared as a body table, so a
caller following the fork passed a table where upstream reads a string. 84 exports
ended in retry_policy, cancellation_token the fork declared nowhere, and the two
types that pair with them — cancel and cancellation_token — were themselves
among the 16 members it never declared. 26 declared names were not on this module
at all, the realtime socket surface among them: the pinned nakama.lua requires
that module privately and exposes it only through create_socket. Eleven of the 26
have a counterpart on nakama.socket, now vendored as a target
of its own; the other fifteen — thirteen message constructors, a stream-presence
listener and a request constructor upstream no longer generates — match neither
module at the pin and were phantoms on an older nakama-defold. The field axis then
closed on the same terms: all 12 of upstream's enum constants are declared, so both
axes read 1.
boom is the opposite shape: it declares one of the six members
boom/boom.lua defines, the other five being the final/init/on_input/
on_message/update lifecycle hooks boom.script calls rather than API a user
writes. Those five are justified rather than missing — see below — so the target
reports callableCoverage: 1 with no fork edit at all. Read that beside
declaredGlobals: nearly the whole library reaches its users as ambient globals,
which this axis does not measure.
Corrected or justified
Some divergences are not defects. When upstream's own source says a member is not for consumers, declaring it would widen the published surface with a function nobody should call — so the fork is right to omit it, and the report should say so rather than charge it as a gap.
parityExceptions in the library's library.json is where that is recorded. It maps
each fork's namespace to an array of { name, kind, reason } entries sorted by name. An excepted member
counts as correct, is absent from missingMembers, and appears in the artifact's
parityExceptions carrying its reason — so a target that reached 1 by
justification reads differently from one that reached 1 by declaring everything.
kind is a closed set, in the same shape as parityVerdict's reason:
kind | When it applies |
|---|---|
script-lifecycle | Upstream exports the member for the library's own bundled .script and says so in its own comment. boom's five hooks carry -- called from boom.script; orthographic.camera's init, final and update say "called automatically from … the camera.script" in LuaDoc. |
deprecated-stub | Upstream's body is nothing but error("… is deprecated"), so the member cannot succeed if called. orthographic.camera keeps ten such one-line stubs; six are excepted here. |
reason must cite upstream's file and line, so the entry can be re-checked against
the pin instead of taken on trust. An arity or phantom exception is deliberately not
expressible — no kind is added before a real case asks for one.
An entry cannot outlive the defect it justifies. Three throws enforce that, each naming the offending entry:
- an unknown
kind, rejected at parse time; - an entry naming a member the pinned upstream does not define — the member was renamed or removed, and the entry is stale;
- an entry for a member the fork does declare — the exception is unnecessary and must be deleted rather than left to rot.
The ledger is not a way to skip a correction. It is the other half of correct it or justify it, and every entry is a claim about upstream that the next reader can check.
Upstream LuaDoc import
A measured target's printed declaration does not stop at the fork. Where upstream
documents a module-level member and the fork does not override it with a
pinned comment, upstream's own LuaDoc summary, parameter
docs and return docs are printed as that member's doc comment, so a project's editor
shows them on hover. The api-doc is lowered from the same printed declaration, so the /api
page shows the same text, marked so a reader can tell it apart from the fork's own
prose.
Six rules bound it:
- Parameter and return docs follow the declared signature. The summary ends at
the first line starting with
@. Each@paramor@tparamtext prints as an@paramon every declaration that lists that parameter, in the declaration's order, so an overload carries only its own;@returnor@treturntext prints as@returnsunless the declaration returnsvoid, and a constant takes no tags. Types never print: a---@paramline is read as LuaLS (name type description), every other line as LDoc (name description, a(type)or a@tparamtype dropped), and a following line that opens no tag continues the text. A tag with no description, a vararg..., and a dotted table field such asconfig.dsnprint nothing. An@after a space, such as LDoc's@{name}reference, prints as\@so TypeScript reads it as text rather than as a tag. - One blank line inside a comment run does not end the block. Upstream often
wraps a long
@paramlist around a blank line, which would otherwise truncate the block to its tag half and lose the summary above it. The blank is crossed only when the segment touching the definition opens no---block of its own, so a blank-separated section header above a documented member never merges into it, and only ever one blank is crossed. - A brief never restates its own symbol. Where upstream writes the member's name as the block's first line and the summary beneath it, the name line is dropped, so the rendered brief is the summary rather than the symbol you are already reading. A first line that merely mentions the name is prose and survives; a block that is only the name imports nothing at all.
- Fork prose wins only while pinned. A member upstream documents keeps exactly
what the fork wrote, on every overload, only while the fork's comment carries an
@upstreamDocpin matching upstream's current text (see Pinning a fork comment); a pinned comment replaces upstream's tags as well as its summary. Without a pin, or with a stale one, upstream's summary, parameter docs and return docs replace the fork's summary and its@paramand@returnstags; every other tag, such as@noSelfor@deprecated, stays. A member upstream does not document keeps the fork's comment, pinned or not. A comment holding only tags, such as/** @noSelf */, is not a summary: the print puts upstream's doc at the top of that same block, and an@paramor@returnsthe fork wrote there keeps its slot. - Only the module's own members. The merge fills the functions and constants
directly inside the
declare moduleblock. A file-scope global and a member of a nested namespace keep whatever the fork wrote. - The import is printed, never vendored.
fork/<moduleId>.d.tsis untouched and the print changes comments only, so the identity diff on types still proves the emit is lossless, imported prose stays distinguishable from the fork's forever after, and an upstream doc change reaches the print with no hand edit.
A block whose every segment opens with a plain -- rather than --- is refused,
and counted as refusedDocBlocksTotal on the target's parity report. Nothing
distinguishes such a block from a section header sitting above a run of constants —
monarch's -- transition messages and boom's -- initialize boom are the same
shape to any parser — so admitting the class would attach one member's heading to
another's documentation. The remedy is to author that member's doc-comment in the fork,
where a human makes the judgment and the result correctly renders as first-party.
refusedDocBlocks charges only the refusals still unanswered, so the remedy
actually clears it: write the brief and the member stops counting. A member the fork
deliberately does not declare is excused by its parityException instead — there is no
element to hang a brief on, and the ledger already carries a human's reading of that
same comment, which is why boom's five lifecycle blocks charge nothing. A merely
missingMembers name is not excused: its remedy is declaring it. The raw term is
what keeps the refusal itself visible — defmath writes all 36 of its blocks that way
and charges none of them, every one being answered in the fork's own words.
An imported symbol's /api heading carries a U dot labelled Documentation
imported from upstream, beside the G dot an ambient global carries. The page's
provenance block already names the repo and ref the text came from.
Pinning a fork comment
A fork comment on a member upstream documents is an override of upstream's text, so it
names the text it replaces. Its last line is @upstreamDoc and a 12-character pin,
on a line of its own:
/**
* Show a screen, loading it first when it is not loaded.
* @param id The screen to show.
* @upstreamDoc 3f9c2a7b41d0
*/
export function show(id: string | hash): boolean;The pin is a hash of upstream's whole LuaDoc block for that member, tags included,
with whitespace collapsed, so re-indenting or re-wrapping upstream's comment keeps
it and changing a word or a @param line does not. The pin never prints: the line
is removed from the served declaration and the /api page.
library check names every
fork comment that prints upstream's doc instead, with the pin that would keep it:
monarch: doc: monarch.monarch.show prints upstream's doc; keep the fork's with @upstreamDoc 3f9c2a7b41d0A notice never fails the check, so an update whose upstream edits a doc you override still lands; it prints upstream's new text until you read it, then either copy the pin into the fork's comment or delete the comment when upstream now says it well. A pin on a member upstream does not document guards nothing and is named as well. A pin shaped any other way, or placed anywhere but a module function's or constant's doc comment, stops the module from printing.
Why the two axes are never averaged
Neither number is "the" coverage of a target, and no single figure replaces them. A module can agree completely on one axis while missing the other entirely, so folding them into one mean would let each mask the other — exactly the reading the split exists to prevent.
platypus is the worked case. It defines one module function and 14 constants, so
its callableCoverage is 1 over a single comparison while its fieldCoverage is
1 over fourteen. Both read the same, and they are not the same result: one is a
single create agreeing on arity, the other is fourteen constants each found by
name. Averaged into one figure the module would look uniformly verified, and the
single number would move by a fourteenth for a defect on either side — which is why
the two are reported separately whether they agree or not.
Read the two together. A perfect callableCoverage over a handful of functions
still says nothing about a large upstreamFields, and a perfect fieldCoverage
says nothing about arity. A phantom on either axis enters no coverage figure,
having no upstream member to be a fraction of, so it is visible only in its list.
When a target cannot be measured
Record a parityVerdict instead of an empty upstreamLua. The reason comes
from a closed set — an unknown one throws, naming the entry — and the note must
say what was actually looked at:
reason | When it applies |
|---|---|
unresolved-path | The moduleId-derived path does not resolve at the pinned ref, including a repository that no longer exists there. No corpus target carries this verdict. Before recording it, check whether the upstream merely moved — an account rename usually redirects, and the same history may be reachable under a new owner. If it is genuinely gone, prefer dropping the library over shipping types nobody can obtain a runtime for. |
no-module-file | Upstream resolves, but declares no single module file this target could be measured against. |
unparseable-shape | The module file exists but closes in a way the reader refuses — a metatable carrying __index, or one it cannot read the keys of, either of which could delegate members no column-0 scan would find. No corpus target carries this verdict: boom.boom and in.accelerometer once did, and were lifted into measurement when the reader learned the return setmetatable(M, { __call = … }) form they close with. |
A verdict is a recorded finding, not a way to skip the work. It says someone looked and what stopped them, which is exactly what an absent declaration cannot say. The corpus currently carries no verdict of any kind — all 35 targets are measured — so every reason above is described rather than exemplified.
5. Cut the library over and validate
Severing ts-defold for the library is the same single-module cutover the generated lanes use:
- Drop the library's row from
library-targets.jsonand its dir fromlibrary-classification.json, and delete the retiredfixtures/ts-defold/<moduleId>.d.ts. Itsapi-doc/<moduleId>.jsongolden is deleted only when the fork publishes under a different namespace; whennamespace===moduleIdit is instead overwritten in place by the command above. The namespace now resolves to your authored artifacts. - Add a
usage/<library>-usage.test-d.tscompile proof in the library folder, moving any hand-written block for the old dotted specifier into it.library checktype-checks every.tsfile under a library'susage/underskipLibCheck: falsetogether with every moduleresolveprints, the fork among them.
The ts-defold registry is now empty: every library it once carried has severed,
so library-targets.json holds "targets": []. The file stays committed anyway
— the CLI's registry loader treats a missing file as "no vendored libraries at
all" and would drop the LuaLS, script_api and authored lanes with it, and
library-classification.json pins its commit against that source block.
The site's fourth maintainedHere loader reads each library's forks, so the
namespace becomes authored-here — absent from the ts-defold classification and
present in a first-party corpus — and its /api page carries the upstream pin
automatically. Then run the gates:
bunx @defold-typescript/cli library check --data packages/library-types/data # from the toolchain root
bun test packages/cli/src/library # from the toolchain root
bun run typecheck # from the toolchain rootCommit the library's library.json and reviewed.json, the vendored
fork/<moduleId>.d.ts and its usage/ examples together, along with the config and
manifest deletions. The emitted api-doc/ report folder is gitignored here and stays
uncommitted.
Worked example — defcon.console
britzl/defcon is a plain-Lua console library with no .script_api and no
---@ annotations, so it is a Bucket-E authored target. Its ts-defold binding
was a correct 24-line single-module surface, and the surface is small and stable
— exactly the low-maintenance-cost case the fork path is for. Keeping it
ts-defold-sourced would forgo the provenance gain for no real saving; a fresh
hand-author would be redundant work when the existing binding is already right.
So the decision is fork: copy the retired .d.ts verbatim, sever ts-defold,
and pin to the real upstream. The reference defcon/library.json:
{
"repo": "https://github.com/britzl/defcon",
"license": "MIT",
"forks": [
{
"authored": "fork/defcon.console.d.ts",
"moduleId": "defcon.console",
"namespace": "defcon",
"apiDoc": "api-doc/defcon.json",
"upstreamLua": ["source/upstream/defcon/console.lua"]
}
]
}and defcon/reviewed.json pins { "ref": "2.6.0" }.
authored vendors the fork; moduleId defcon.console names the declare module a consumer imports; namespace defcon is the single-segment artifact
stem, so the golden is api-doc/defcon.json — not
the dotted moduleId — keeping the docs Libraries tree and file layout uniform
with the other bare-stem severed libraries. Nothing else owned defcon, so it was
free to take; orthographic.camera below is the case where it is not. The defcon page then attributes to
britzl/defcon at 2.6.0, not the ts-defold/library corpus.
Worked example — deftest.deftest
britzl/deftest (a test runner, pinned to 2.8.0) is a second fork with the
same reference-entry shape as defcon.console. It illustrates one wrinkle: its
.d.ts declares ambient top-level globals (describe, before, after,
test, assert_*) alongside declare module 'deftest.deftest'. A fork copies
the surface verbatim, so those globals carry into the printed declaration
and therefore into the dts-declaration-validity gate's compilation. That is
fine — they raise no duplicate-identifier clash — and the api-doc lowering
publishes them alongside the module's exports (add, run), each marked as an
ambient global so the reference page distinguishes what the import reaches from
what is callable without it. Do not alter a vendored fork to suppress such
globals; they are part of the library's real surface.
A file-scope type is held to a stricter rule than a file-scope value: it
publishes only when a published signature names it and it carries members
(an interface, or a type alias over an object literal). A union, a function
type, or an internal generic helper stays off the page, so a fork's incidental
type machinery does not become reference content.
Worked example — defmath.defmath
subsoap/defmath (a pure-Lua math-helper module) is a third fork with the same
reference-entry shape, illustrating the no-tag case: upstream publishes no
git tags, so ref pins the default-branch commit SHA
(c67c227322334056cea7a631f3ddcdf2bcfd480c) rather than a semver tag. The
defmath page attributes to that SHA and its sourceUrl points at
.../tree/c67c2273… — expected, not a defect. Its surface also references core
engine types: upstream writes them as vmath.vector3 | vmath.vector4 /
vmath.quaternion, but the fork — like every vendored declaration in this
package — carries the core-type-renamed ambient Vector3 | Vector4 /
Quaternion. These resolve in library check, which compiles
every fork against the engine types the CLI ships, so a fork consuming engine
types needs no special wiring.
Worked example — defsave.defsave
subsoap/defsave (a save/load helper, pinned to the v1.2.6 tag) is the first
fork to correct a surface rather than re-home it: the ts-defold binding
declared 7 of upstream's 14 functions and just one of its 16 config fields
(appname), and three of the seven returned the wrong type. Neither pure option
fits — keep fails the cost model (upstream is frozen and the surface is tiny)
and a fork alone would knowingly re-home a half-missing surface, while a full
hand-author would rewrite five declarations that are already right (four
correct functions plus appname). So fork first, then hand-correct against the
pin: copy the retired .d.ts, add the missing members, and fix the wrong
signatures reading upstream's Lua as the authority. Extending a fork is
gate-safe: the identity diff compares the printed declaration to the vendored
fixture, not to the retired ts-defold surface. But that diff proves emission
fidelity only — the print loses nothing relative to the vendored .d.ts; it does
not check the vendored surface against upstream. That accuracy rests on the manual audit
against defsave.lua at the pin plus the per-library shape assertions in
packages/cli/src/library/sync-authored-types.test.ts, so correcting a
fork moves the accuracy burden onto the author, not onto a gate. Narrowing a wrong return is a breaking change
for consumers and belongs in the changelog's ### Breaking section; a types
package's value is accuracy, so do not keep a declaration you can see is wrong.
Two limits are worth knowing before you correct a surface. Upstream Lua that
falls off the end of a function returns nil, so a predicate like defsave's
key_exists is boolean | undefined, not boolean — read every branch, not
just the explicit returns. And a module's export let fields are still
read-only through a consumer's import * as ns, so a compile proof pins their
types by reading them; there is no way to prove assignability through a
namespace import.
Worked example — persist.persist
whiteboxdev/library-defold-persist (a save/load helper, pinned to the
b37f6104… commit SHA since upstream publishes no tags) is the first fork to
arrive here from a markdown no-go rather than from having no documented
source at all. Its README documents all six functions by name but no parameters
and no returns, so the markdown gate scored signature-loss and refused the
cutover. That verdict retired the README as a regeneration path — and nothing
more. Running the cost model on the still-open maintenance question gives
fork: the ts-defold surface is five fully-typed functions in 34 lines,
upstream is abandoned (its README redirects to a successor project) so the
surface cannot churn, and the recorded loss was the README's, not the .d.ts's.
So the cutover itself was verbatim — the identity diff made fidelity 100% by
construction, and it shipped no type change at all. The later and
separately-auditable edit that anticipated has since landed: the fork now also
declares exists, the sixth function upstream's Lua defines and ts-defold never
had.
Severing does not erase the markdown verdict. persist's no-go/signature-loss
record and its README snapshot stay exactly as recorded, and the gate still
re-derives the decision on every run — it just compares against the vendored
fork instead of the deleted fixtures/ts-defold/ snapshot. That is sound
because the comparison is re-derived against whatever the fork now declares, not
against an identity: adding exists moved two name-set terms and left the
no-go/signature-loss decision exactly where it was. Keeping a dead
library-targets.json row alive to feed that lookup would have been the wrong
fix: it would make the file stop meaning still ts-defold-sourced, which is the
signal the remaining Bucket-C libraries are measured against.
Worked example — orthographic.camera
britzl/defold-orthographic (a camera suite, pinned to tag 3.6.3) is a second
markdown no-go that answered fork, and it settles two questions persist's
surface never raised.
Which namespace does the fork publish under? persist took the bare
persist. orthographic cannot: it is the markdown lane's one registered target,
so api-doc/orthographic.json is already a committed regeneration proof owned by
that lane, and the no-go hides the bare
orthographic namespace from page enumeration. Forking under it would overwrite
the proofs and render no page. So the authored target keeps the dotted
orthographic.camera — the nakama.engine.defold shape — which takes over the
retired ts-defold module name and leaves the route and import string
byte-identical. The rule generalizes: when the retired module name already equals
the publish namespace, fork onto it; only reach for a bare namespace when nothing
else owns it.
Which file do you copy? The ts-defold lane runs a type-mapping pass, so
fixtures/ts-defold/orthographic.camera.d.ts says hash/url/vmath.vector3
while the codemodded output says Hash/Url/Vector3. persist's two
forms were identical, so the template never had to choose. Copy the codemodded
output — the authored lane emits its input verbatim, so forking the raw fixture
would ship ts-defold's upstream type names and fail the declaration-validity
gate. Forking the codemodded output makes the cutover a byte-for-byte no-op, which is what
lets you prove the severance and any type correction as two separate diffs.
orthographic then took that second diff: upstream documents follow as accepting
one game object or a table of them, and the ts-defold binding typed only the
singular target: Hash | Url. On a file the toolchain repo now owns, widening it to
targets: Hash | Url | (Hash | Url)[] is a one-line edit plus a re-emit. It
moves no recorded gate number — the fidelity comparison scores member names, the
unknown token, parameter count, return void-ness, and optionality, and a
rename plus a union widening touches none of them.
The third diff is the signature correction, and unlike the second it does move name
sets. The fork gained get_automatic_zoom and set_automatic_zoom (live API upstream
defines and ts-defold never had), lost add_projector, get_projection_id and
use_projector (deprecated stubs whose upstream body only error()s), and
world_to_screen narrowed to the (camera_id, world) upstream actually reads — its
third adjust_mode argument was silently ignored at runtime, so narrowing it is
breaking on purpose. With nine ledger entries covering the withdrawn stubs and the
three camera.script lifecycle hooks, the target reaches callableCoverage: 1. The
markdown verdict is re-derived over the new export list and lands on the same
no-go.
The fourth diff is the field correction, which moves the constants half of that
same list: MSG_SET_AUTOMATIC_ZOOM was declared from the pinned camera.lua, and
MSG_USE_PROJECTION and ORTHOGRAPHIC_RENDER_SCRIPT_USED were deleted, upstream
defining neither anywhere — reading either returned nil, so the deletion is
breaking on paper only. The verdict is re-derived a second time and holds: the
nineteen constants and five functions the README's API table does not cover are
still the surface loss that drove it.