xbintsc 0.3.35 → 0.3.49

package/dist/tests/lexer/strings.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"strings.test.js","sourceRoot":"","sources":["../../../tests/lexer/strings.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"strings.test.js","sourceRoot":"","sources":["../../../tests/lexer/strings.test.ts"],"names":[],"mappings":"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"}

package/doc/DESIGN.md

@@ -0,0 +1,117 @@
+# xbintsc Design
+
+Build a binary compiler for TypeScript.
+
+> Language: **English** | [简体中文](./zh-CN/DESIGN.md)
+
+## Architecture
+
+```
+source.ts
+  │  lexer    src/lexer      lexing: full token set, templates, regex, ASI
+  ▼
+ tokens
+  │  parser   src/parser     recursive descent → AST (src/ast)
+  ▼
+ AST
+  │  binder   src/binder     scopes / symbols / hoisting / closure capture
+  ▼
+ bound AST
+  │  codegen  src/codegen    LLVM IR text (llvm.ts); values.ts defines the value model
+  ▼
+ module.ll ──clang──► module.o ──link──► executable
+                                    ▲
+                          runtime/  C runtime (NaN-boxed values)
+```
+
+### Value model
+
+`xt_value` is a single 64-bit word. Doubles are stored unboxed; everything else
+is a tagged pointer with a 16-bit tag in the high bits plus a 48-bit payload.
+The representation is defined once in `src/codegen/values.ts` and `runtime/rt.h`
+and shared by the compiler and the runtime.
+
+### Calling convention
+
+Every compiled function uses the same ABI:
+
+```c
+xt_value fn(xt_value env, int32_t argc, xt_value *argv);
+```
+
+`env` threads captured variables by reference through boxes, so direct calls and
+closure calls share a single code path. JavaScript semantics that are awkward to
+inline (`+` coercion, relational comparison, property access, inspection) are
+delegated to `@xt_*` runtime calls.
+
+### Runtime
+
+`runtime/xt_runtime.c` implements strings, objects, arrays, closures, arithmetic,
+comparison, exceptions and Node-like `console.log` inspection. It uses a
+non-moving mark-sweep collector behind `xt_alloc` (explicit roots, subsystem
+root providers and a conservative C-stack scan), so the collector's internals
+stay isolated from the compiler.
+
+### Replacing llc
+
+LLVM/`llc` is not installed on the host, but `clang` can compile LLVM IR text
+directly, so the pipeline is `IR text → clang -c → object file → link C runtime`.
+This keeps the "IR binding + native compilation" goal while remaining
+cross-platform.
+
+## Directory structure
+
+| Directory | Responsibility |
+| --- | --- |
+| `src/lexer` | Lexing (Scanner, TokenKind) |
+| `src/ast` | AST nodes, factories, visitors |
+| `src/parser` | Recursive descent parser (including type syntax) |
+| `src/binder` | Scope and symbol resolution, closure capture |
+| `src/codegen` | Value model and LLVM IR generation |
+| `src/diagnostics` | Source files, diagnostics, hashing |
+| `src/driver` | Pipeline driver, incremental cache, clang toolchain wrapper |
+| `src/extensions` | Pluggable extension registry and Node extension |
+| `src/cli` | Command-line entry point |
+| `runtime` | C runtime and `rt.h` |
+| `tests` | Tests organised by module (including e2e) |
+| `scripts` | Runtime build and other scripts |
+| `.github/workflows` | Multi-platform, multi-version CI |
+
+## Incremental compilation
+
+`src/driver/cache.ts` keys the cache on the entry source hash, compiler version,
+compile options, platform and extension set; when all recorded outputs still
+exist the build is skipped. The runtime C sources are cached as object files by
+content hash in the same way.
+
+## Extension mechanism
+
+An extension is a plain object (see `src/extensions/registry.ts`): it declares
+extra C runtime code, linker flags, and the modules it makes importable, mapping
+exported bindings to runtime symbols with the uniform `(argc, argv)` ABI. Node's
+`import { readFileSync } from "fs"` is wired in through
+`src/extensions/node/fs` + `runtime/ext_node/fs`, and the core compiler never
+needs to know any platform details.
+
+`nativeObjects` extends the same shape to code built outside the pipeline: a
+C++ or Rust project compiled to an `extern "C"` object or static archive can be
+linked in and exposed through a JSON manifest (`src/extensions/native.ts`,
+`--ext-native`). The driver links the artifacts verbatim and the generator binds
+their symbols exactly like the C runtime, so the extension language is invisible
+to the core compiler. Windows is covered too: xbintsc links with the toolchain
+found on `PATH` (the MSVC ABI when LLVM + the Visual Studio C++ build tools are
+installed), and each manifest declares any platform-specific linker flags. See
+`examples/extensions/` and `runtime/xt_ext.h` / `runtime/xt_ext.rs`.
+
+## Self-hosting roadmap
+
+The compiler itself is written in TypeScript and emits IR text, and `runtime` is
+already decoupled from the compiler. Later, the runtime can be rewritten in TS
+and the compiler can compile itself, gradually reaching self-hosting.
+
+## Tests
+
+Organised by module: `tests/lexer`, `tests/parser`, `tests/binder`,
+`tests/codegen`, `tests/driver`, `tests/extensions`, `tests/cli`, `tests/e2e`.
+When `clang` is present, e2e tests really compile and run binaries; otherwise
+they are skipped automatically.

package/doc/ai/README.md

@@ -0,0 +1,63 @@
+# xbintsc for AI agents
+
+**xbintsc compiles a subset of TypeScript straight to native binaries.** It
+parses TypeScript itself, lowers the program to LLVM IR text, and invokes
+`clang` to produce a standalone executable linked against a small C runtime
+(`runtime/`). The output does not embed Node.js or a TypeScript compiler.
+
+```
+source.ts --lexer--> tokens --parser--> AST --binder--> bound AST
+          --codegen--> module.ll --clang--> module.o --link--> executable
+```
+
+This directory is the **AI-facing, task-oriented** layer of the documentation.
+It is deliberately short and links onward; the canonical detail lives in the
+documents it points at. Read the page for your task, not the whole directory.
+
+| Page | Use it when |
+| --- | --- |
+| [build-recipe.md](./build-recipe.md) | You need to compile or run a program, and want the exact command shape |
+| [cli.md](./cli.md) | You need the full flag list, project config, or the programmatic API |
+| [language-support.md](./language-support.md) | You must know whether a syntax feature or API exists, or behaves like Node |
+| [extensions.md](./extensions.md) | You need `fs`/`http`/…, a GUI, or a C++/Rust library |
+| [troubleshooting.md](./troubleshooting.md) | Something failed and you need the cause and the fix |
+
+New to this repository (rather than to a program that uses xbintsc)? Read
+[../AGENTS.md](../../AGENTS.md) first — it covers the layout, the build gate and
+the rules for changing the compiler.
+
+## The three things that decide everything
+
+1. **Only a subset of TypeScript compiles.** Unsupported syntax is rejected, not
+   approximated. Check before you write a lot of code.
+2. **Types are erased, never checked.** Annotations, interfaces, generics,
+   `as`/`satisfies` and non-null `!` have no runtime effect, and no type checker
+   runs. Only real runtime behaviour matters.
+3. **Node compatibility is opt-in and incomplete.** Node modules come from the
+   `node` extension (`--ext node`); bare third-party npm imports are not
+   supported.
+
+## Choose your command
+
+```bash
+# Run a program now (compiles to a temp binary, then executes it)
+xbintsc run app.ts
+
+# Produce a standalone binary
+xbintsc build app.ts --out build          # -> build/app[.exe]
+
+# See the LLVM IR that would be compiled
+xbintsc emit app.ts
+
+# Ask what toolchain xbintsc resolved
+xbintsc doctor
+```
+
+In a source checkout, replace `xbintsc` with `npx tsx src/cli/main.ts` (or run
+`npm run xbintsc --`). A released archive needs no Node.js.
+
+Next: [build-recipe.md](./build-recipe.md) for the working commands,
+[language-support.md](./language-support.md) before writing a nontrivial
+program.
+
+> 中文版本：[zh-CN/](./zh-CN/)

package/doc/ai/build-recipe.md

@@ -0,0 +1,137 @@
+# Build recipe
+
+Copy-paste shapes for the common jobs, plus the reasoning that makes a build
+succeed. For every flag see [cli.md](./cli.md); when a command fails see
+[troubleshooting.md](./troubleshooting.md).
+
+## Calling the compiler
+
+| Situation | Invocation |
+| --- | --- |
+| Released standalone archive | `xbintsc …` (`bin/xbintsc[.exe]` on `PATH`) |
+| Source checkout, compiled | `node dist/src/cli/main.js …` |
+| Source checkout, TypeScript sources | `npx tsx src/cli/main.ts …` |
+| Source checkout, npm script | `npm run xbintsc -- …` |
+| `bin` launcher in a checkout | `node bin/xbintsc.js …` (falls back to `tsx` automatically) |
+
+The rest of these pages write `xbintsc` for brevity.
+
+## Run a program
+
+```bash
+xbintsc run app.ts
+xbintsc run app.ts -- --flag value        # everything after -- goes to the program
+```
+
+`run` compiles the program to an executable and then spawns it with inherited
+stdio. It requires `--emit exe`; `xbintsc run app.ts --emit ir` is an error.
+The exit status of `run` is the exit status of the program it ran.
+
+## Build a standalone binary
+
+```bash
+xbintsc build app.ts                      # -> build/app (build/app.exe on Windows)
+xbintsc build app.ts --out build/app      # choose the output directory
+xbintsc build app.ts -o app.bin            # or an explicit output path
+xbintsc build app.ts -O0                   # optimization level: -O0 .. -O3 (default -O2)
+xbintsc build app.ts --force               # ignore the incremental cache
+xbintsc build app.ts --verbose             # print progress
+```
+
+`build` prints the artifact it wrote, and `(cached)` when the incremental cache
+made the work unnecessary:
+
+```
+xbintsc: wrote /abs/path/build/app
+```
+
+Other emit kinds are useful for inspection:
+
+```bash
+xbintsc build app.ts --emit ir   # writes app.ll
+xbintsc build app.ts --emit obj  # writes app.o
+```
+
+## Inspect the LLVM IR
+
+```bash
+xbintsc emit app.ts > app.ll     # IR on stdout, nothing else written
+```
+
+`emit` needs no clang and no runtime library — it is the cheapest way to check
+what the compiler understood. It is the fastest feedback loop when you are
+unsure whether a construct is supported.
+
+## Program shape that compiles
+
+```ts
+// app.ts — ESM, no require()
+import { readFileSync } from "fs";          // needs `--ext node`
+
+function main(): void {
+  const text = readFileSync("package.json", "utf8");
+  console.log(text.length);
+}
+
+main();                                     // top-level code runs in order
+```
+
+- Use `import`/`export`; `require()` is rejected.
+- Relative imports are bundled (`import { helper } from "./helper.js"` resolves
+  to `helper.ts`).
+- Module specifiers for Node built-ins are the bare names (`fs`, `path`,
+  `node:fs`), and they need the `node` extension enabled.
+
+## Project config: build with no arguments
+
+`xbintsc.config.json` (discovered by walking up from the entry file, or selected
+with `--config <path>`; disable with `--no-config`) holds the build options, so
+`xbintsc build` alone works. Paths resolve against the config file's directory,
+and any CLI flag overrides the matching field.
+
+```json
+{
+  "entry": "src/app.ts",
+  "outDir": "build",
+  "optimize": "2",
+  "extensions": ["node"],
+  "app": { "name": "Demo", "icon": "assets/app.png" }
+}
+```
+
+The machine-readable schema is [../xbintsc.config.schema.json](../xbintsc.config.schema.json);
+the full field list is in [cli.md](./cli.md).
+
+## Compiling with extensions
+
+An import of a Node module fails until the extension is enabled. Enable one or
+several, comma-separated:
+
+```bash
+xbintsc run app.ts --ext node
+xbintsc run app.ts --ext node,gui
+```
+
+A C++/Rust library is added by manifest instead:
+
+```bash
+xbintsc run app.ts --ext-native ./mathx.manifest.json
+```
+
+Details, including how to author both kinds, are in
+[extensions.md](./extensions.md).
+
+## Programmatic API
+
+When you are writing tooling rather than a program:
+
+```ts
+import { build, compileString } from "xbintsc";
+
+const { ir } = compileString("console.log(1 + 1);");   // IR text, no clang needed
+const result = build("program.ts", { emit: "exe", outDir: "build" });
+```
+
+`build` returns `{ outputPath, irPath?, cached, diagnostics, bundlePath? }` and
+reports recoverable problems through `diagnostics` rather than throwing. The
+subpath export `xbintsc/driver` exposes the driver internals.

package/doc/ai/cli.md

@@ -0,0 +1,142 @@
+# CLI and configuration reference
+
+The authoritative `--help` text is the `HELP` constant in
+[../../src/cli/main.ts](../../src/cli/main.ts). This page adds the semantics that
+the help text leaves implicit.
+
+## Commands
+
+| Command | Purpose | Needs clang? |
+| --- | --- | --- |
+| `xbintsc build <file.ts>` | Compile to `exe` (default), `obj` or `ir` | yes, except `--emit ir` |
+| `xbintsc run <file.ts> [-- args]` | Compile to an executable and execute it | yes (`--emit exe` only) |
+| `xbintsc emit <file.ts>` | Print LLVM IR to stdout, write nothing | no |
+| `xbintsc doctor` | Report the resolved toolchain, runtime and icon tools | only for the probe |
+| `xbintsc version` | Print the version | no |
+| `xbintsc help` | Print the help text | no |
+
+Any command also accepts `--help`, which prints the help text and exits 0. An
+unknown command prints an error plus the help text and exits 1.
+
+## Options
+
+```
+-o, --output <path>   Explicit output path (overrides --out and the config)
+    --out <dir>       Output directory (default: build/)
+    --emit <kind>     exe | obj | ir (default: exe)
+-O0 .. -O3            Optimization level passed to clang (default: -O2)
+    --ext <names>     Enable bundled extensions, comma separated (e.g. node,gui)
+    --ext-native <m>  Register a C++/Rust extension from a JSON manifest
+                      (comma separated for several)
+    --config <path>   Use this project config instead of discovering one
+    --no-config       Do not read any project config
+    --icon <path>     Embed an application icon (PNG/ICO/ICNS)
+    --bundle          macOS: also produce a <name>.app bundle
+    --app-name <name> Bundle / display name
+    --app-id <id>     macOS bundle identifier (e.g. com.example.demo)
+    --force           Ignore the incremental cache
+    --verbose         Print progress information
+```
+
+Parsing details that occasionally surprise:
+
+- `--flag=value` and `--flag value` are both accepted.
+- `-O`, `-O1`, `-O2`, `-O3` all work; a bare `-O` means `-O2`.
+- `--` ends option parsing: everything after it belongs to the program under
+  `run`, or is a positional for the other commands.
+- `-o` consumes the next argument unconditionally; the other value flags leave
+  the value unset when the next argument starts with `-`.
+
+## Project config
+
+`xbintsc.config.json` is discovered by walking **up** from the entry file's
+directory (or from the current directory when no entry was given). Every path in
+the file resolves relative to the config file, and any CLI flag overrides the
+matching field. `--no-config` skips discovery entirely.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `entry` | string | Entry TypeScript file, so `xbintsc build` needs no positional |
+| `outDir` | string | Output directory (default `build/`) |
+| `output` | string | Explicit output path, overriding `outDir` |
+| `optimize` | `"0"｜"1"｜"2"｜"3"` | Optimization level |
+| `extensions` | string[] | Bundled extensions to enable, e.g. `["node"]` |
+| `extNative` | string[] | Native extension manifest paths |
+| `force` | boolean | Ignore the incremental cache |
+| `app.name` / `app.icon` / `app.bundle` / `app.bundleId` | | Application metadata ([icon.md](../icon.md)) |
+
+JSON schema: [xbintsc.config.schema.json](../xbintsc.config.schema.json). An
+unreadable or malformed config fails the build with `invalid JSON` or
+`Unable to read` rather than silently falling back to defaults.
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `xbintsc_CLANG` | Use this clang instead of resolving one from `PATH` |
+| `xbintsc_LINKER_ARGS` | Extra linker flags (e.g. `-fuse-ld=lld`) |
+| `xbintsc_CACHE_DIR` | Object-cache directory (default: `.xbintsc`) |
+| `xbintsc_PREFER_PREBUILT` | `0` forces the runtime to be compiled from source |
+| `xbintsc_BINARY` | Native compiler binary the `bin/` launcher should run |
+
+## Incremental compilation
+
+Each build is keyed on the entry source hash, the compiler version, the build
+options, the platform and the active extension set
+([../../src/driver/cache.ts](../../src/driver/cache.ts)). If every recorded
+output still exists, the build returns immediately and prints `(cached)`. The C
+runtime and extension sources are cached the same way; objects live in
+`.xbintsc/` (or `xbintsc_CACHE_DIR`).
+
+`--force` (or `force: true`) bypasses the freshness check. If a build ever
+returns stale output, that key is the first thing to inspect — and note that the
+object cache key deliberately excludes compiler flags, which is why the runtime
+coverage script uses a separate cache directory.
+
+## Exit codes
+
+- `0` — success (for `run`: the program exited 0).
+- `1` — diagnostics, a usage error, or a failure in the compiler itself.
+- `run` otherwise propagates the program's own exit status.
+
+## Diagnostics
+
+Errors are rendered as `file:line:col - error TS<code>: <message>` with a source
+excerpt and caret underline. Codes are grouped by stage
+([../../src/diagnostics/diagnostic.ts](../../src/diagnostics/diagnostic.ts)):
+
+| Range | Stage |
+| --- | --- |
+| TS1xxx | lexer |
+| TS2xxx | parser |
+| TS3xxx | binder |
+| TS4xxx | checker (`TS4005` is the `UnsupportedFeature` code) |
+| TS5xxx | codegen |
+| TS6xxx | driver: `TS6001` module not found, `TS6002` IO, `TS6003` toolchain, `TS6004` cache |
+
+The CLI appends a `hint:` line pointing at the relevant document (for example
+[language-support.md](./language-support.md) for `TS4005`, or
+[troubleshooting.md](./troubleshooting.md) for `TS6001`/`TS6003`). Toolchain and
+IO failures throw instead of producing a diagnostic, so the CLI reports those as
+`xbintsc: <message>` plus the same style of hint.
+
+## Programmatic API
+
+```ts
+import { build, compileString } from "xbintsc";
+```
+
+- `compileString(source, fileName?, extensions?)` → `{ ir, diagnostics }`.
+  Pure IR generation: no filesystem, no clang.
+- `build(entryPath, options?)` → `BuildResult`. `options` accepts `output`,
+  `outDir`, `emit`, `optimize`, `force`, `verbose`, `extensions` (a registry),
+  `app`, `clang`, `preferPrebuilt`.
+- `canonicalize` of results: `{ outputPath, irPath?, cached, diagnostics, ir?,
+  bundlePath? }`.
+
+`build` reports source-level problems through `diagnostics` — always check
+`diagnostics.some((d) => d.category === "error")` before using the artifact — but
+**throws** `ToolchainError` when clang itself fails
+([../../src/driver/toolchain.ts](../../src/driver/toolchain.ts)). The
+`xbintsc/driver` subpath additionally exports the cache, toolchain resolution,
+config loader, icon and macOS-bundle helpers.

package/doc/ai/contributing.md

@@ -0,0 +1,196 @@
+# Contributing to the compiler
+
+Use this page after [../AGENTS.md](../../AGENTS.md), which covers the layout, the
+build gate and the rules. This one covers the workflow details that are easy to
+get wrong.
+
+## Set up
+
+```bash
+npm install
+npm run typecheck        # tsc --noEmit
+npm run lint             # eslint + the 600-line file budget
+npm test                 # unit + end-to-end
+```
+
+Node.js ≥ 22 is required to run the compiler from source, and a **clang 16+**
+toolchain is required for anything that links a binary (see
+[troubleshooting.md](./troubleshooting.md)). `xbintsc emit` needs neither clang
+nor the runtime library, which makes it the fastest inner loop.
+
+Optional but recommended — install the repository hook:
+
+```bash
+git config core.hooksPath .githooks
+```
+
+`.githooks/pre-commit` **bumps the patch version on every commit** and folds
+`package.json` + `package-lock.json` into that commit (`npm version patch
+--no-git-tag-version`). Expect a version bump in your commits; do not countermand
+it. Release tags are created by `release.yml`, never by the hook.
+
+## The test suites
+
+| Command | Scope |
+| --- | --- |
+| `npm test` | everything: per-module unit tests plus `tests/e2e` |
+| `npm run test:e2e` | only the compile-and-run tests |
+| `npm run test:watch` | vitest in watch mode |
+| `npm run coverage` | V8 coverage of the TypeScript compiler (`src/`) |
+| `npm run coverage:runtime` | LLVM coverage of the C runtime (`runtime/`) |
+
+Unit tests live one directory per module under `tests/` (`lexer`, `parser`,
+`binder`, `codegen`, `driver`, `extensions`, `cli`, `e2e`) and mirror the source
+tree. Edge-case tests belong next to the module they cover.
+
+`tests/e2e/` compiles real programs and runs the resulting binaries, including a
+**differential harness** (`tests/e2e/differential-*.test.ts`) that executes the
+same source through both xbintsc and Node and compares output byte-for-byte. That
+harness is the strongest tool in the repository: when you touch semantics, add a
+case there rather than asserting a hand-written expected string. Tests that need
+clang skip themselves when it is unavailable (`hasClang()` in
+[tests/helpers.ts](../../tests/helpers.ts)) — do not turn that into a silent
+pass.
+
+## Two invariants you must not break
+
+### 1. The self-hosting fixpoint
+
+CI (`self-host` job in [.github/workflows/ci.yml](../../.github/workflows/ci.yml))
+compiles the compiler with itself and requires the emitted IR to be identical
+across generations:
+
+```
+source --emit--> ref.ll
+source --build--> gen1 binary
+gen1 --emit--> gen2.ll      # must equal ref.ll
+gen1 --build--> gen2 binary
+gen2 --emit--> gen3.ll      # must equal ref.ll
+```
+
+By consequence: **any change that alters emitted IR must still be reproducible by
+the compiler being changed**, and the IR must be byte-for-byte deterministic —
+iteration order, generated symbol names and numbering included. Never introduce
+nondeterminism (a `Map`/`Set` iteration over insertion-ordered data you did not
+control, a timestamp, a filesystem-order dependency) into codegen.
+
+A second consequence is the string model: the compiler's own source text has to
+mean the same thing in every generation. A compiled string is UTF-8 bytes, so the
+self-hosted `readFileSync` (`--ext node`) hands the scanner the bytes of a file,
+while Node hands it the same file already decoded — read source files through
+`decodeUtf8` ([src/diagnostics/utf8.ts](../../src/diagnostics/utf8.ts)) and never
+assume a code unit is a byte or a character. Getting this wrong shows up as a
+non-ASCII literal (`—` in a hint string) coming out re-encoded in `gen2.ll`, which
+is why the emitted IR is compared byte-for-byte rather than line-by-line.
+
+Verify locally:
+
+```bash
+npx tsx src/cli/main.ts emit src/cli/main.ts --ext node > scratch/ref.ll
+npx tsx src/cli/main.ts build src/cli/main.ts --ext node --out scratch/self --force
+./scratch/self/main emit src/cli/main.ts --ext node > scratch/gen2.ll   # .exe on Windows
+diff scratch/ref.ll scratch/gen2.ll
+```
+
+### 2. The runtime ABI and value model
+
+- Every compiled function uses
+  `xt_value fn(xt_value env, int32_t argc, xt_value *argv)` — direct calls and
+  closure calls share this one path, and `env` threads captured variables
+  through boxes.
+- Every value is a single 64-bit word: doubles unboxed, everything else a tagged
+  pointer (16-bit tag + 48-bit payload). The representation is defined **once**
+  in [../../src/codegen/values.ts](../../src/codegen/values.ts) and
+  [../../runtime/rt.h](../../runtime/rt.h); change both together or not at all.
+- Awkward JS semantics (`+` coercion, relational comparison, property access,
+  inspection) are delegated to `@xt_*` runtime calls rather than inlined.
+- The GC is a non-moving mark-sweep collector: new heap objects go through
+  `xt_alloc`, and a value must be reachable from an explicit root slot, a
+  registered root provider (the event loop, the microtask queue) or the
+  conservative C-stack scan while it is live. A value held only in a C local that
+  is not on the scanned stack is a bug.
+
+## Changing the runtime
+
+`runtime/` is C, split by function across translation units (`xt_alloc.c`,
+`xt_values.c`, `xt_containers.c`, `xt_stdlib.c`, …) sharing
+`runtime/rt_internal.h`. The runtime must be rebuilt for C changes to take
+effect:
+
+```bash
+npm run runtime            # tsx scripts/build-runtime.ts -> runtime/lib/<os>-<arch>/
+npm run runtime:clean      # drop build/runtime-obj and runtime/lib
+```
+
+Add a new C file only together with the place that lists the runtime sources
+(`RUNTIME_SOURCES` in [../../src/driver/compiler.ts](../../src/driver/compiler.ts)),
+because that list decides what gets compiled and linked. Extension C sources are
+declared by the extension itself.
+
+## Adding or extending an extension
+
+An extension is a plain object ([../../src/extensions/registry.ts](../../src/extensions/registry.ts))
+contributing `runtimeSources()`, `modules()` / `builtins()`, and optionally
+`nativeObjects()` or `assetLoaders()`. The Node extension is one folder per
+module, pairing its TypeScript exports with the C sources that implement them:
+
+```
+src/extensions/node/fs/index.ts        runtime/ext_node/fs/read_file.c
+```
+
+Adding a Node module therefore means dropping a folder in each place and
+registering it in the module list; the core compiler never changes. If your
+feature is optional or platform-specific, it belongs in an extension rather than
+in `src/codegen`. Bundled extensions are listed in
+[../../src/extensions/catalog.ts](../../src/extensions/catalog.ts) — an extension
+listed there but not enabled produces the actionable `pass --ext <name>` hint, so
+add modules to the list even when the feature is off by default.
+
+Extension authoring from C++/Rust without touching the compiler is documented in
+[../../examples/extensions/README.md](../../examples/extensions/README.md).
+
+## Adding a diagnostic
+
+1. Add a stable code to the enum grouped by pipeline stage in
+   [../../src/diagnostics/diagnostic.ts](../../src/diagnostics/diagnostic.ts)
+   (1xxx lexer, 2xxx parser, 3xxx binder, 4xxx checker, 5xxx codegen, 6xxx
+   driver). Codes are a public interface — never renumber one.
+2. Emit it with the most specific range you have; `formatDiagnostic` renders the
+   file, line, column, excerpt and caret from it.
+3. Make the message actionable, in the style of the existing ones: say what is
+   wrong *and* what to do (`pass --ext node`, `use an ESM import`, …). If a
+   reader needs more, the CLI hint layer maps codes to a document — extend that
+   map in [../../src/cli/main.ts](../../src/cli/main.ts) when you add a code.
+4. Cover it in `tests/diagnostics` or the module's own test.
+
+## Documentation is part of the change
+
+A feature is not done until the docs match:
+
+| Document | Update when |
+| --- | --- |
+| [../implemented.md](../implemented.md) | a feature starts working |
+| [../unimplemented.md](../unimplemented.md) | a limitation appears or is lifted |
+| [../node-implemented.md](../node-implemented.md) / [../node-unimplemented.md](../node-unimplemented.md) | Node module coverage changes |
+| [language-support.md](./language-support.md) | the AI-facing summary of the above changes |
+| [../requirements.md](../requirements.md) | the toolchain or platform requirements change |
+| [cli.md](./cli.md) | a flag, config field or environment variable changes |
+
+Keep the Chinese translation (`doc/zh-CN/`, `doc/ai/zh-CN/`) in step with the
+English source; a half-translated page is worse than none because it silently
+goes stale.
+
+## Repository hygiene
+
+- **600 lines per code file**, enforced by ESLint (`max-lines`) for TS/JS and by
+  [scripts/check-file-length.ts](../../scripts/check-file-length.ts) for C, C++,
+  Rust, `.inc` and shell files. Split by responsibility instead of growing a
+  file; vendored sources are exempt.
+- **No `any`**; `prefer-const` and `eqeqeq` are errors. The
+  declaration-merging pattern in the parser/generator is deliberately allowed.
+- **Public API changes** go through [../../src/index.ts](../../src/index.ts) and
+  must keep the `xbintsc` / `xbintsc/driver` export maps in
+  [../../package.json](../../package.json) valid.
+- `npm run package-release` assembles the per-platform archives into
+  `dist/release/`; the release workflow owns tagging, so never push a tag by
+  hand.