[ASDAlexander77]

Draft, stacked on #366 (linkname-decorator). Retarget to main once that merges. CI for pull requests runs only against main, so both workflows were started by hand on this branch; the Linux result is below once it's in.

PR 2 of docs/superpowers/specs/2026-09-25-tsbindgen-linkname-design.md. It adds tsbindgen, a tool that reads a C header with clang and writes tslang bindings for it.

tsbindgen fixture.h [-o fixture.ts] [--namespace N [--strip-prefix P]] [--filter GLOB] -- <clang args>

What it writes

• Functions: declare function, with @linkname("c_name") whenever the TS name differs from the symbol. That covers --namespace, --strip-prefix, escaped reserved words and __asm__ labels.
• Types:
  • structs become named tuples;
  • enums become enums of the C integer type;
  • typedefs become type aliases;
  • literal object-like macros become consts.
• Pointers: Reference<T>, or Opaque for handles, void *, function pointers and C++ classes. char * is string.
• Integers: signed map to sN and unsigned to uN, by the width the target gives them.
• Skips: anything it can't bind correctly is skipped with a // skipped: <name>: <reason> line and a warning, never dropped silently. Examples:
  • variadic functions;
  • bit-fields;
  • packed or over-aligned layouts;
  • unions;
  • non-C calling conventions;
  • function-like and non-literal macros.

The code is in three places:

• tslang/lib/TsClangImporter: the binding model, clang HeaderParser, TypeMapper and BindingPrinter.
• tslang/tsbindgen: the command line.
• tslang/unittests/TsClangImporter: 53 gtest cases.

Where it differs from the spec

The full table is in the spec's new "As built (2026-09-26)" section. Each row was found by running generated bindings through tslang:

• The output is .ts, not .d.ts. A const in a .d.ts, or in any file pulled in with import, has no value: LNK2019 when linked, Symbols not found under the JIT. The bindings are included with /// <reference path>.
• Signed integers are sN, not iN. tslang's iN are signless, so an int8_t -5 printed 251.
• A pointer field that leads back to its own struct is Opaque. A self-referencing type alias makes tslang exit 127 with no message. That's a compiler bug to file separately.
• A function-pointer signature is an inline /* ... */ comment on the parameter. The spec had one trailing comment, which can't say which parameter it describes.
• clang runs through ToolInvocation with our own diagnostics. runToolOnCodeWithArgs exits 0 even when the clang command line has an error.
• Four behaviors the spec left open:
  • non-literal macros are skipped with a reason;
  • --strip-prefix never produces an empty, digit-leading or duplicate name;
  • structs with an unnatural layout are skipped;
  • "nothing selected" is a warning.

tslang/docs/reference-counting-evaluation.md §9.78 records the open issue: under -mm=rc, a C-owned char * returned as string has no string header. v1 targets gc.

Tests

• unittest-TsClangImporterTests (53 cases):
  • type mapping on x86_64 Linux, x86_64 Windows and i686;
  • naming and escaping;
  • selection;
  • every skip reason;
  • printer output.
• test-bindgen-plain and test-bindgen-namespace: build fixture.c into a real C library at -O2, generate bindings from fixture.h, and run bindgen_test.ts both linked and under --emit=jit. The output must match expected.txt.
  • The narrow row passes int8_t/uint16_t/bool arguments. It exists to catch a missing signext/zeroext on tslang's declare parameters. That can only fail on SysV (Linux), where an optimized callee trusts the caller to extend.
  • If it fails there, it's a tslang call-lowering bug to file, not a mapping change.
• test-bindgen-cli: pins the exit codes and messages for bad arguments, a missing header and a clang error.
• Full Release suite on Windows: all pass, with one test disabled; that one belongs to @linkname: a second name for @dllname, and one C symbol for many declarations #366.

Checked against the default library

Bindings generated from DefaultLib's regex.cpp and http.cpp compile in tslang. Compared with the hand-written lib.native.d.ts, the 22 functions in each have the same names. The only differences are expected:

• Opaque versus a named or commented Opaque handle;
• int versus s32;
• one parameter named s by hand where the C++ source says c;
• an omitted : void.

No mistakes were found in lib.native.d.ts. The comparison did find one generator bug: std::cmatch * came out as an undeclared match_results. It's fixed in 6918335 with a unit test.

Known gaps (v1)

Nothing is emitted, and no skip line is written, for these:

• extern global variables;
• anonymous enum { FOO = 1 } constants;
• typedef struct {…} *Handle (the typedef and its users).

Smaller:

• enum member names aren't checked against reserved words;
• a non-static C99 inline function is emitted as a declaration;
• float macros print at full precision.

Linux CI

Run 36246544195 on b3a03ca3: 2897/2899 pass. test-bindgen-plain and test-bindgen-namespace fail on exactly one line, the narrow row, both linked and under the JIT. Windows is green.

expected: narrow -5 65535 -5 false true
got:      narrow 251 65535 -5 false true

fx_widen_s8(-5) returns 251. On x86-64 SysV, a clang-compiled callee assumes the caller has already sign- or zero-extended an 8- or 16-bit argument to 32 bits. tslang never emits signext/zeroext; nothing in lib/TypeScript sets either. So tslang passes the raw 8 bits and the callee reads garbage in the upper bits. u16 passed only because the 16-bit constant happened to arrive zero-extended.

This is the tslang call-lowering bug from Review Focus 1, not a mapping error. It affects every tslang call into C with an 8- or 16-bit argument on Linux, hand-written bindings included. The mapping stays as it is.

Fixed in #369. This branch with #369 cherry-picked passes on Linux: 2907/2907 (run 36250596356). #367 goes green once it's rebased onto main after #366 and #369 merge.

(An earlier run failed to build: gcc -Wpedantic rejects &main. Fixed in b3a03ca.)

🤖 Generated with Claude Code