typescript-go-sync - SKILL.md Agent Skill

name: typescript-go-sync description: Keeping packages/ttsc/shim/* synced with typescript-go and complete for plugin authors. Read before adding a re-export, bumping the pinned typescript-go version, or chasing a missing AST/transform/printer/emit API a plugin needs.

TypeScript-Go Shim Sync

Why the shim exists

ttsc is built on top of typescript-go (the Go port of tsc, module github.com/microsoft/typescript-go). Almost all of its real compiler surface lives under that module's internal/* packages, and Go forbids importing another module's internal/ tree. So ttsc re-exports the pieces it needs through packages/ttsc/shim/<name>, where each shim sub-module (ast, checker, compiler, core, printer, scanner, parser, tsoptions, tspath, vfs, ...) is its own Go module that wraps the matching internal/<name> package.

Keeping this shim synced and complete is a core purpose of ttsc, not a chore. The shim is the only typescript-go surface that source-plugin authors (typia, nestia, and third-party rules) can touch. The job is to track typescript-go source changes and expose EVERY AST, transform, printer, and emit API a plugin needs, so plugins never have to reach into internal/ themselves. A missing re-export is an ttsc bug, not a plugin bug.

Shim structure

Each shim/<name>/ directory holds two kinds of file:

surface.go — generated, do not edit. Header // Code generated ... DO NOT EDIT.. Plain type aliases (type Foo = innerast.Foo) for the package's exported API surface, produced by go run ./tools/gen_shims from packages/ttsc. Regenerating overwrites it.
shim.go — hand-maintained. First line // gen_shims:hand-maintained; the generator detects that marker and skips the file. This is where wrapper funcs and //go:linkname declarations live. Extra files like ast/parent.go are also hand-maintained.

Per-directory extra-shim.json feeds the generator the symbols it cannot derive on its own: ExtraFunctions (unexported funcs to linkname), ExtraMethods, ExtraFields, and IgnoreFunctions (exported funcs the generator should skip because a hand-written variant exists).

Pick the mechanism by what the symbol is:

Exported type → type alias in surface.go (let the generator add it), e.g. type Node = innerast.Node.
Exported func that the generator skips (e.g. its signature names an unexported type) → hand-write a wrapper func in shim.go, like func SetParentInChildren(node *Node) { innerast.SetParentInChildren(node) }.
Unexported symbol → //go:linkname, like the GetSourceFileOfNode / GetNodeAtPosition entries in ast/shim.go. Add an _ "unsafe" import and declare the func with no body.

Adding a missing API a plugin needs

The common task: a plugin needs a typescript-go symbol that the shim does not yet re-export.

Find the symbol in the pinned typescript-go source under the module cache: go env GOMODCACHE/github.com/microsoft/typescript-go@<version>/internal/<pkg>/. Confirm its exact name, signature, and whether it is exported.
Add the re-export to the matching shim/<pkg>/:
- exported func with a clean signature → re-run go run ./tools/gen_shims (or add a wrapper in shim.go if the generator skips it);
- exported type → add the alias in surface.go via the generator;
- unexported symbol → add a //go:linkname declaration in shim.go.
Build the shim module and packages/ttsc to verify it links.

Recent worked example: ast.SetParentInChildren was exposed in shim/ast/parent.go as a thin wrapper so a transform can re-parent synthetic nodes before emit (the emit resolver dereferences Parent and would hit nil otherwise). For an unexported symbol the pattern is the linkname form already in ast/shim.go.

Bumping the pinned typescript-go version

The version is pinned per shim module: require github.com/microsoft/typescript-go v0.0.0-<timestamp>-<hash> in every shim/*/go.mod, kept identical across all of them and also referenced as an indirect require in packages/ttsc/go.mod. The sibling go.work wires the shim sub-modules; tagged upstream versions can later replace these local wires.

To bump:

Update the require line to the new pseudo-version in every shim/*/go.mod (keep them all the same) and in packages/ttsc/go.mod, then refresh each go.sum.
Re-run go run ./tools/gen_shims from packages/ttsc to regenerate surface.go against the new source.
Re-check the hand-maintained shim.go files and extra-shim.json entries: an upstream rename, signature change, or export/unexport flip can break a wrapper or linkname. Build packages/ttsc and fix the fallout.

Validating a shim change in a real consumer

A shim change is only proven by a downstream plugin compiling and passing against it. Build the ttsc tarballs and install them into a consumer checkout:

pnpm package:tgz            # full release-rehearsal tarballs
# or, faster for a single platform:
TTSC_TARBALLS_CURRENT=1 pnpm package:tgz

Install the produced tarballs into ../typia (or another consumer) and run a relevant typia test that exercises the new API. The experimental/tarballs/index.ts flow is what CI uses; --current / TTSC_TARBALLS_CURRENT=1 packs only the current-platform package for a quick loop.

Mechanical completeness gate

packages/ttsc/tools/shim_audit enforces shim completeness in CI (the shim-audit job runs pnpm --filter ttsc shim:audit) so the recurring "missing re-export" class cannot return. It treats the shim as a closure: if a type is aliased, everything reachable from it should be reachable through the shim. Three layers:

Enum families (zero-tolerance). shim/<pkg>/enums_gen.go completes every exposed enum family, re-exporting any member not already re-exported in the package's shim.go/surface.go; the gate fails on any partial enum. After a typescript-go bump, run pnpm --filter ttsc shim:audit -fix to regenerate it. This is the SignatureKindConstruct (#230) class.
Reachable funcs / escaping types (ratcheted). tools/shim_audit/baseline.json grandfathers the current backlog; the gate fails on any new gap. Expose the symbol, or run pnpm --filter ttsc shim:audit -write-baseline to accept it deliberately.
Unexported helpers. Closure cannot predict these (a new consumer's first ask for an internal helper); the audit lists them as a demand pool. Expose with the //go:linkname pattern above (Checker_getMinArgumentCount is the worked example).

Traversal-completeness probes

Closure and the audit only see whether a symbol is nameable or whether a composition compiles. They cannot see a runtime dead-end: an exposed graph-walk op that silently can't reach part of the graph. Checker_getBaseTypes nil-derefs on a generic Reference base, so a base-chain walk dead-ends at the generic boundary — invisible to the audit, surfaced only when a consumer crashes (#246).

The net for that class is a runtime probe that exercises the exposed traversal over a ttsc-owned fixture and asserts it completes. The worked example is packages/lint/test/shim/base_chain_walk_crosses_generic_boundary_test.go: it builds a real Checker via the lint host's loadProgram, walks a Base{#brand} <- Mid<T> <- Sub extends Mid<string> chain through only the exposed shim ops, and asserts the naive walk dead-ends before Base (the gap is real) while the getDeclaredTypeOfSymbol-bridged walk reaches it. These live in packages/lint/test/ (the only ttsc-owned Go harness with a Checker-over-source) and run in pnpm test:go. When you expose a new graph-walk op, add a fixture + completeness assertion so its dead-ends can't silently return — prefer this over a compile-only guard, which proves linkage but not traversal.