xbintsc 0.2.9 → 0.3.1

package/README.md

@@ -97,6 +97,13 @@ xbintsc emit examples/hello.ts | head
 xbintsc run examples/read-file.ts --ext node
 ```
 
+#### Prebuilt standalone archives
+
+Every GitHub Release also attaches a self-contained archive per platform
+(`xbintsc-<os>-<arch>.tar.zst` or `.tar.gz`, plus a `.sha256`). Unpack it and
+call `bin/xbintsc` directly — no Node.js or system compiler required. See
+[doc/requirements.md](doc/requirements.md#prebuilt-releases-recommended).
+
 ### As a developer (from source)
 
 In a source checkout, run the TypeScript sources directly through `tsx` (or use
@@ -210,8 +217,16 @@ Tests are organised by module under `tests/` (`lexer`, `parser`, `binder`,
 
 ## Requirements
 
-- Node.js 20+
-- A `clang`-compatible C compiler on `PATH` (override with `xbintsc_CLANG`)
+See [Requirements](./doc/requirements.md) for the full, per-platform list.
+
+- Node.js 20+ — only to run/build from source; released binaries are standalone
+- macOS: the Xcode Command Line Tools (`xcode-select --install`)
+- Windows: nothing extra — the MinGW-w64 toolchain is bundled
+- Linux: a system C library (glibc)
+- To build a binary yourself: a `clang`-compatible compiler on `PATH`
+  (override with `xbintsc_CLANG`)
+
+Check your environment with `xbintsc doctor`.
 
 ## Language subset
 

package/README.zh-CN.md

@@ -91,6 +91,13 @@ xbintsc emit examples/hello.ts | head
 xbintsc run examples/read-file.ts --ext node
 ```
 
+#### 预编译独立发布包
+
+每个 GitHub Release 也会附上各平台的自包含归档
+（`xbintsc-<os>-<arch>.tar.zst` 或 `.tar.gz`，附 `.sha256`）。解压后直接调用
+`bin/xbintsc` 即可，无需 Node.js 或系统编译器。详见
+[doc/zh-CN/requirements.md](doc/zh-CN/requirements.md#预编译发布包推荐)。
+
 ### 作为开发者（从源码）
 
 在源码检出中，通过 `tsx` 直接运行 TypeScript 源码（或使用 `npm run xbintsc`）。
@@ -200,8 +207,15 @@ npm run test:e2e    # 仅编译并运行的测试
 
 ## 运行要求
 
-- Node.js 20+
-- `PATH` 中有兼容 `clang` 的 C 编译器（可用 `xbintsc_CLANG` 覆盖）
+完整的分平台要求见 [使用前置要求](./doc/zh-CN/requirements.md)。
+
+- Node.js 20+ —— 仅从源码运行/构建时需要；发布版二进制是独立的
+- macOS：Xcode Command Line Tools（`xcode-select --install`）
+- Windows：无需额外安装 —— 自带 MinGW-w64 工具链
+- Linux：系统 C 库（glibc）
+- 若要自行编译二进制：`PATH` 中有兼容 `clang` 的 C 编译器（可用 `xbintsc_CLANG` 覆盖）
+
+用 `xbintsc doctor` 检查环境。
 
 ## 语言子集
 

package/bin/xbintsc.js

@@ -2,25 +2,64 @@
 /**
  * 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.
+ * Resolution order:
+ *   1. a native compiler for this platform — an `xbintsc_BINARY` override, an
+ *      installed `@xbintsc/<os>-<arch>` package, or a co-located `bin/xbintsc`.
+ *      This is what a self-contained install provides; it needs no Node
+ *      toolchain at runtime.
+ *   2. the compiled CLI in `dist/` (a checkout that ran `npm run build`).
+ *   3. the TypeScript sources through `tsx` (a plain checkout).
  */
 
 import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
 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");
+const exe = process.platform === "win32" ? ".exe" : "";
+const slug = `${process.platform}-${process.arch}`;
+
+/** A native compiler binary for this platform, if one ships with the package. */
+function findNativeBinary() {
+  const override = process.env.xbintsc_BINARY;
+  if (override && existsSync(override)) return override;
+
+  const require = createRequire(import.meta.url);
+  for (const request of [`@xbintsc/${slug}/bin/xbintsc${exe}`, `@xbintsc/${slug}`]) {
+    try {
+      const resolved = require.resolve(request);
+      if (existsSync(resolved)) return resolved;
+    } catch {
+      // Not installed for this platform; keep looking.
+    }
+  }
+
+  for (const candidate of [
+    join(root, "bin", `xbintsc${exe}`),
+    join(root, "dist", `xbintsc${exe}`),
+  ]) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+const args = process.argv.slice(2);
 
+const native = findNativeBinary();
+if (native) {
+  const result = spawnSync(native, args, { stdio: "inherit" });
+  process.exit(result.status ?? 1);
+}
+
+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);
+  process.exit(run(args));
 }
+
+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, ...args], { stdio: "inherit" });
+process.exit(result.status ?? 1);

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

@@ -83,6 +83,8 @@ export interface PropertyAssignment extends Node {
 export interface ShorthandPropertyAssignment extends Node {
     readonly kind: SyntaxKind.ShorthandPropertyAssignment;
     readonly name: Identifier;
+    /** Present for `{ a = default }` when used as a destructuring target. */
+    readonly initializer?: Expression;
 }
 export interface SpreadElement extends Node {
     readonly kind: SyntaxKind.SpreadElement;

package/dist/src/binder/binder.d.ts

@@ -7,110 +7,36 @@
  *
  * The result is deliberately plain data — maps and records — so it can be
  * cached, serialized for the incremental build, and unit tested in isolation.
+ *
+ * The walk is split by functional area into sibling modules:
+ *   - `types`        — the plain-data symbol/scope model
+ *   - `declarations` — symbol/scope creation and hoisting
+ *   - `references`   — identifier resolution and capture analysis
+ *   - `helpers`      — small AST utilities
  */
-import { type ArrowFunction, type FunctionDeclaration, type FunctionExpression, type Identifier, type Node, type SourceFileNode, type Expression } from "../ast/nodes.js";
-export declare enum SymbolKind {
-    Var = "var",
-    Let = "let",
-    Const = "const",
-    Function = "function",
-    Parameter = "parameter",
-    Class = "class",
-    Interface = "interface",
-    TypeAlias = "type",
-    Enum = "enum",
-    Import = "import",
-    Namespace = "namespace"
-}
-export interface SymbolInfo {
-    readonly id: number;
-    readonly name: string;
-    readonly kind: SymbolKind;
-    /** False for `const` bindings and imports. */
-    readonly mutable: boolean;
-    /** The function this symbol belongs to. */
-    readonly fn: FunctionInfo;
-    readonly declarations: Node[];
-    readonly references: Identifier[];
-    /** Set when referenced from a nested function. */
-    captured: boolean;
-    /** Assigned after construction once we know it is captured. */
-    boxed: boolean;
-}
-export type FunctionNode = SourceFileNode | FunctionDeclaration | FunctionExpression | ArrowFunction;
-export interface FunctionInfo {
-    readonly id: number;
-    readonly name: string;
-    readonly node: FunctionNode;
-    readonly parent?: FunctionInfo;
-    readonly scope: Scope;
-    readonly params: SymbolInfo[];
-    /** Every binding declared directly in this function (params + locals). */
-    readonly locals: SymbolInfo[];
-    /** Outer bindings referenced by this function or any descendant. */
-    readonly captures: SymbolInfo[];
-    readonly captureIndex: Map<number, number>;
-    readonly isModule: boolean;
-    readonly isArrow: boolean;
-    /** True when the function was declared `async`. */
-    readonly isAsync: boolean;
-    /** True when this function's body mentions `this` directly. */
-    usesThis: boolean;
-    /** True when an arrow function must receive `this` from its enclosing scope. */
-    capturesThis: boolean;
-    /** Set for class methods/constructors; carries the owning class. */
-    classInfo?: ClassInfo;
-    /** True for `static` class members. */
-    isStatic?: boolean;
-    /** True for an explicit `constructor`. */
-    isConstructor?: boolean;
-}
-export interface ClassInfo {
-    readonly id: number;
-    readonly name: string;
-    readonly node: Node;
-    readonly scope: Scope;
-    readonly parent?: ClassInfo;
-    readonly parentExpression?: Expression;
-    /** `this`-bearing fields declared on the class. */
-    readonly fields: ClassFieldInfo[];
-    readonly methods: FunctionInfo[];
-    readonly statics: FunctionInfo[];
-    ctor?: FunctionInfo;
-}
-export interface ClassFieldInfo {
-    readonly name: string;
-    readonly initializer: Expression | undefined;
-    readonly fn: FunctionInfo;
-    readonly isStatic: boolean;
-}
-export declare enum ScopeKind {
-    Module = "module",
-    Function = "function",
-    Block = "block",
-    For = "for",
-    Catch = "catch"
-}
-export interface Scope {
-    readonly kind: ScopeKind;
-    readonly parent?: Scope;
-    readonly fn: FunctionInfo;
-    readonly symbols: Map<string, SymbolInfo>;
-    /** The syntax node that introduced the scope, when there is one. */
-    readonly node?: Node;
-}
-export interface BindResult {
-    readonly moduleFunction: FunctionInfo;
+import type { Identifier, Node, SourceFileNode } from "../ast/nodes.js";
+import { ScopeKind, type ClassInfo, type FunctionInfo, type MutableFunction, type Scope, type SymbolInfo, type BindResult, type FunctionNode } from "./types.js";
+import { type DeclarationMethods } from "./declarations.js";
+import { type ReferenceMethods } from "./references.js";
+export * from "./types.js";
+export declare function bind(sourceFile: SourceFileNode): BindResult;
+export declare class Binder {
+    readonly sourceFile: SourceFileNode;
     readonly functions: FunctionInfo[];
     readonly classes: ClassInfo[];
-    /** Maps a class-like AST node to the ClassInfo the binder built. */
     readonly classOfNode: Map<Node, ClassInfo>;
-    /** Maps a function-like AST node to the FunctionInfo the binder built for it. */
-    readonly functionOfNode: Map<Node, FunctionInfo>;
     readonly symbolOfDeclaration: Map<Node, SymbolInfo>;
     readonly symbolOfIdentifier: Map<Identifier, SymbolInfo>;
     readonly scopes: Map<Node, Scope>;
-    /** Identifier references that could not be resolved in user code. */
     readonly unresolved: Identifier[];
+    nextSymbolId: number;
+    nextFunctionId: number;
+    nextClassId: number;
+    current: MutableFunction;
+    constructor(sourceFile: SourceFileNode);
+    bind(): BindResult;
+    createFunction(name: string, node: FunctionNode, parent: MutableFunction | undefined, isModule: boolean, isArrow: boolean): MutableFunction;
+    createScope(kind: ScopeKind, node: Node | undefined, parent: Scope | undefined): Scope;
+}
+export interface Binder extends DeclarationMethods, ReferenceMethods {
 }
-export declare function bind(sourceFile: SourceFileNode): BindResult;