xbintsc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# xbintsc
+
+`xbintsc` compiles a practical subset of **TypeScript directly to native binaries**.
+It parses TypeScript itself, binds names, lowers the program to **LLVM IR text**,
+and hands the IR to **clang**, which produces a standalone executable linked
+against a small C runtime.
+
+The design goals are:
+
+1. **Incremental compilation** — builds are content-addressed and skipped when nothing changed.
+2. **Well-factored modules** — lexer, parser, binder, codegen, driver, extensions each live in their own directory with their own tests.
+3. **Extensive tests** — per-module unit tests plus end-to-end tests that compile and run real binaries.
+4. **Pluggable extensions** — Node `fs`, Bun APIs, … are optional compile modules, not core code.
+5. **Self-hosting ready** — the compiler is written in TypeScript and emits IR text, so a TypeScript rewrite can eventually compile itself.
+6. **Multi-platform** — macOS, Linux and Windows on multiple CPUs, validated by GitHub Actions.
+
+## How it works
+
+```
+source.ts
+   │  lexer      src/lexer
+   ▼
+ tokens
+   │  parser     src/parser        → AST (src/ast)
+   ▼
+ AST
+   │  binder     src/binder        → scopes, symbols, closures
+   ▼
+ bound AST
+   │  codegen    src/codegen       → LLVM IR text (src/codegen/llvm.ts)
+   ▼
+ module.ll ──clang──► module.o ──link──► executable
+                                  ▲
+                          runtime/ (C runtime, NaN-boxed values)
+```
+
+### Value model
+
+JavaScript values are a single 64-bit word (`xt_value`). Doubles are stored
+unboxed; everything else is a tagged pointer: 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`.
+
+### 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 one 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 bump
+arena and never frees — garbage collection is deliberately deferred and isolated
+behind `xt_alloc`, so it can be replaced without touching the compiler.
+
+## Usage
+
+There are two ways to invoke the CLI:
+
+- **As a user** — the package is installed and the `xbintsc` command is available
+  (via the `bin` entry `./bin/xbintsc.js`).
+- **As a developer** — running directly from a source checkout, before building.
+
+### As a user
+
+```bash
+# Install globally
+npm install -g xbintsc
+
+# ...or use it on demand without installing
+npx xbintsc version
+
+# Compile and run a program
+xbintsc run examples/hello.ts
+
+# Produce a native binary
+xbintsc build examples/hello.ts --out build/examples
+./build/examples/hello
+
+# Inspect the generated LLVM IR
+xbintsc emit examples/hello.ts | head
+
+# Use an optional extension (here, Node's readFileSync)
+xbintsc run examples/read-file.ts --ext node
+```
+
+### As a developer (from source)
+
+In a source checkout, run the TypeScript sources directly through `tsx` (or use
+`npm run xbintsc`). The `bin` launcher also works here: without a `dist/` build it
+falls back to `tsx` automatically.
+
+```bash
+# Install dependencies
+npm install
+
+# Compile and run a program
+npm run xbintsc -- run examples/hello.ts
+# equivalently
+npx tsx src/cli/main.ts run examples/hello.ts
+
+# Produce a native binary
+npx tsx src/cli/main.ts build examples/hello.ts --out build/examples
+./build/examples/hello
+
+# Inspect the generated LLVM IR
+npx tsx src/cli/main.ts emit examples/hello.ts | head
+
+# Use an optional extension (here, Node's readFileSync)
+npx tsx src/cli/main.ts run examples/read-file.ts --ext node
+```
+
+CLI options:
+
+```
+-o, --output <path>   Output path
+    --out <dir>       Output directory (default: build/)
+    --emit <kind>     exe | obj | ir (default: exe)
+-O0..-O3              Optimization level (default: -O2)
+    --ext <names>     Comma separated extensions (e.g. node)
+    --force           Ignore the incremental cache
+    --verbose         Print progress information
+```
+
+### Programmatic API
+
+```ts
+import { build, compileString } from "xbintsc";
+
+const { ir } = compileString("console.log(1 + 1);");
+const result = build("program.ts", { emit: "exe", outDir: "build" });
+```
+
+## Incremental compilation
+
+The driver keys each build on the entry source hash, compiler version, options,
+platform and the active extension set (`src/driver/cache.ts`). If every recorded
+output still exists, the build returns immediately. The C runtime and extension
+sources are compiled once and cached on the same principle.
+
+## Extensions
+
+An extension is a plain object (`src/extensions/registry.ts`):
+
+```ts
+export const nodeExtension: Extension = {
+  name: "node",
+  runtimeSources: () => ["runtime/ext_node.c"],
+  builtins: () => ({ readFileSync: { symbol: "xt_node_read_text_file" } }),
+};
+```
+
+Registering it links the extra C source and makes `readFileSync(...)` resolve to
+the C symbol with the uniform `(argc, argv)` calling convention. Builtins can be
+added without changing the core compiler.
+
+## Tests
+
+```bash
+npm run typecheck   # tsc --noEmit
+npm test            # unit + end-to-end (runs real binaries when clang is present)
+npm run test:e2e    # only the compile-and-run tests
+```
+
+Tests are organised by module under `tests/` (`lexer`, `parser`, `binder`,
+`codegen`, `driver`, `extensions`, `cli`, `e2e`).
+
+## Requirements
+
+- Node.js 20+
+- A `clang`-compatible C compiler on `PATH` (override with `xbintsc_CLANG`)
+
+## Language subset
+
+Implemented today: functions, arrow functions and closures, `let`/`const`/`var`,
+all common operators, `if`/`while`/`do`/`for`/`for…of`/`for…in`, `break`/
+`continue`/`return`/`throw`, objects, arrays, member/element access, assignments,
+template literals, `console.log`, extension builtins, and the TypeScript type
+syntax is parsed and ignored (types are erased).
+
+Not yet implemented: classes, enums, `switch`, `try`/`catch`, `new`, `this`,
+object spread, `async`/generators, and most standard library methods (`Array`
+methods other than `push`, `Math`, etc.).

package/bin/xbintsc.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * xbintsc launcher.
+ *
+ * Prefers the compiled CLI in `dist/` (production installs run `npm run build`
+ * first). In a checkout, falls back to running the TypeScript sources through
+ * `tsx` so `npx xbintsc` works without a build step.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const compiled = join(root, "dist", "src", "cli", "main.js");
+
+if (existsSync(compiled)) {
+  const { run } = await import(pathToFileURL(compiled).href);
+  process.exit(run(process.argv.slice(2)));
+} else {
+  const tsx = join(root, "node_modules", ".bin", process.platform === "win32" ? "tsx.cmd" : "tsx");
+  const entry = join(root, "src", "cli", "main.ts");
+  const result = spawnSync(tsx, [entry, ...process.argv.slice(2)], { stdio: "inherit" });
+  process.exit(result.status ?? 1);
+}

package/dist/src/ast/factory.d.ts

@@ -0,0 +1,11 @@
+import { type Node, type Range } from "./nodes.js";
+/**
+ * Small helpers used by the parser and by the code generators to build AST
+ * nodes. Keeping construction in one place means the shape of every node is
+ * defined exactly once and is easy to evolve.
+ */
+export declare function node<T extends Node>(value: T): T;
+export declare function range(start: number, end: number): Range;
+/** Concatenate the ranges of several nodes into one span. */
+export declare function span(...nodes: (Node | Range | number | undefined)[]): Range;
+export declare function isIdentifier(node: Node): node is import("./nodes.js").Identifier;

package/dist/src/ast/factory.js

@@ -0,0 +1,36 @@
+import { SyntaxKind } from "./nodes.js";
+/**
+ * Small helpers used by the parser and by the code generators to build AST
+ * nodes. Keeping construction in one place means the shape of every node is
+ * defined exactly once and is easy to evolve.
+ */
+export function node(value) {
+    return value;
+}
+export function range(start, end) {
+    return { start, end };
+}
+/** Concatenate the ranges of several nodes into one span. */
+export function span(...nodes) {
+    let start = Number.POSITIVE_INFINITY;
+    let end = Number.NEGATIVE_INFINITY;
+    for (const item of nodes) {
+        if (item === undefined)
+            continue;
+        if (typeof item === "number") {
+            start = Math.min(start, item);
+            end = Math.max(end, item);
+        }
+        else {
+            start = Math.min(start, item.start);
+            end = Math.max(end, item.end);
+        }
+    }
+    if (!Number.isFinite(start))
+        return { start: 0, end: 0 };
+    return { start, end };
+}
+export function isIdentifier(node) {
+    return node.kind === SyntaxKind.Identifier;
+}
+//# sourceMappingURL=factory.js.map

package/dist/src/ast/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/ast/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAyB,MAAM,YAAY,CAAC;AAE/D;;;;GAIG;AAEH,MAAM,UAAU,IAAI,CAAiB,KAAQ;IAC3C,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,KAAa,EAAE,GAAW;IAC9C,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AACxB,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,IAAI,CAAC,GAAG,KAA4C;IAClE,IAAI,KAAK,GAAG,MAAM,CAAC,iBAAiB,CAAC;IACrC,IAAI,GAAG,GAAG,MAAM,CAAC,iBAAiB,CAAC;IACnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,KAAK,SAAS;YAAE,SAAS;QACjC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC9B,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC5B,CAAC;aAAM,CAAC;YACN,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;YACpC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;IACzD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAU;IACrC,OAAO,IAAI,CAAC,IAAI,KAAK,UAAU,CAAC,UAAU,CAAC;AAC7C,CAAC"}