xbintsc 0.5.6 → 0.5.20

package/doc/implemented/runtime-core.md

@@ -0,0 +1,32 @@
+# C runtime core
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/runtime-core.md)
+
+Location: `runtime/xt_alloc.c`, `runtime/xt_values.c`, `runtime/xt_containers.c`,
+`runtime/xt_builtins.c`, `runtime/xt_constructors.c`, `runtime/xt_io.c`, sharing the
+private header `runtime/rt_internal.h`; the public ABI is in `runtime/rt.h`.
+
+Strings, symbols, typed arrays, collections, promises/async, `fetch` and the
+standard-library surface have their own pages:
+
+- [Strings and text](./strings.md)
+- [Standard library](./stdlib.md)
+- [Collections](./collections.md)
+- [Typed arrays and binary data](./typed-arrays.md)
+- [Async, promises and generators](./async.md)
+- [fetch](./fetch.md)
+
+- Allocator: non-moving mark-sweep collector behind `xt_alloc` (explicit roots, subsystem root providers and a conservative C-stack scan).
+- Value construction: `xt_undefined/xt_null/xt_bool/xt_number/xt_string_new/xt_string_from_cstr`.
+- Type conversion: `xt_truthy`, `xt_to_number`, `xt_to_string`, `xt_typeof`.
+- Arithmetic: `add/sub/mul/div/mod/pow/neg/pos`.
+- Bitwise: `and/or/xor/not/shl/shr/ushr` (including `ToInt32` semantics).
+- Comparison: `lt/le/gt/ge`, loose / strict equality, `not`, `is_nullish`.
+- Objects: linear property list, `object_new/get/set/has/keys/values/entries/assign/spread`.
+- Arrays: `array_new/get/set/push/length/spread`; assigning `arr.length` truncates or extends (matching JS); `iter_length` / `iter_value` expose a uniform iteration view over arrays, strings (by code point), `Map` and `Set`.
+- Generic member access: `xt_get` / `xt_set` (dispatch over arrays / objects / strings).
+- Operator helpers: `xt_in` (`in`), `xt_delete` (`delete`), `xt_rest_args` (rest parameters / `arguments`).
+- Box: `box_new/get/set` (for closure-captured variables).
+- Functions and closures: `arg`, `closure_new/call/env/arity`.
+- Exceptions: `xt_try_enter` / `xt_try_exception` / `xt_try_leave` maintain the `_setjmp` frame stack; `xt_throw` long-jumps to the nearest `try` when a frame exists, otherwise prints `Uncaught ...` and exits. Codegen also maintains a shadow call stack (function name, source file and line) that `Error.stack` captures (see [Standard library](./stdlib.md)), and a fatal-signal handler dumps the same frames on a native crash. `--debug` additionally emits `!DICompileUnit` / `!DISubprogram` / `!DILocation` metadata and compiles with `-g -fno-omit-frame-pointer`, so gdb/lldb/WinDbg map instructions back to source lines.
+- Objects / functions: `xt_object` with a prototype chain, `xt_function` with a property bag (static members and `prototype`); `xt_new` (instantiation), `xt_instance_of` (prototype chain), `xt_object_freeze/is_frozen/from_entries`; `xt_constructors.c` holds the first-class constructor cache, constructor prototypes and static-value dispatch.

package/doc/implemented/stdlib.md

@@ -0,0 +1,78 @@
+# Standard library
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/stdlib.md)
+
+Location: `runtime/xt_stdlib.c`, `runtime/xt_stdlib2.c`, `runtime/xt_symbol.c`,
+`runtime/xt_builtins.c`, `runtime/xt_constructors.c`, `runtime/xt_io.c`,
+`runtime/xt_structured_clone.c`, `runtime/xt_url.c`.
+
+The dispatch layer is `xt_call_method` (array / string methods and function
+properties on objects), `xt_math_call` (`Math.*` and constants) and the
+`xt_*` entry point of each constructor. Well-known symbols and the iterator
+protocol are in [Symbol](#symbol) below; collections and typed arrays have their
+own pages: [Collections](./collections.md), [Typed arrays and binary data](./typed-arrays.md).
+
+## Objects
+
+- `Object.keys` / `values` / `entries` / `assign` / `getOwnPropertyNames` / `groupBy`, object spread `{...obj}`.
+- `Object.defineProperty` / `getOwnPropertyDescriptor(s)` — data and accessor descriptors; the attribute flags are reported but not enforced on later writes/enumeration.
+- `Object.freeze` / `is_frozen` / `from_entries`, `Object.getPrototypeOf`.
+- `Object.prototype`: `hasOwnProperty` / `toString` / `valueOf` / `isPrototypeOf` / `propertyIsEnumerable` / `__proto__`; `Object.getPrototypeOf({}) === Object.prototype`.
+- First-class built-in constructors (`const A = Array`, `new A(...)`, `A.isArray`, `x instanceof A`) are covered in [Codegen](./codegen.md#llvm-ir-code-generation-codegen).
+
+## Arrays
+
+- `push` `pop` `shift` `unshift` `join` `slice` `splice` `indexOf` `lastIndexOf` `includes` `concat` `reverse` `forEach` `map` `filter` `reduce` `reduceRight` `find` `findIndex` `findLast` `findLastIndex` `some` `every` `sort` `flat` `flatMap` `fill` `copyWithin` `at` `keys` `values` `entries`
+- Immutable helpers: `toReversed` / `toSorted` / `toSpliced` / `with`.
+- Statics: `Array.isArray` / `of` / `from`.
+- Default `sort` is stable and compares string forms, like Node; assigning `arr.length` truncates or extends the array.
+
+## Numbers, BigInt and Math
+
+- Number formatting and coercion match Node: `toFixed` / `toPrecision` / `toExponential`, hex / octal / binary parsing, and the full `+` / relational `ToPrimitive` rules. These are covered by the differential tests.
+- `BigInt` literals and values: arbitrary precision arithmetic, bitwise and shift operators, comparisons, `toString(radix)`, `BigInt()`, `BigInt.asIntN` / `BigInt.asUintN`.
+- `Math`: the full function set and constants.
+- `Number` statics and `Number()` conversion; `parseInt` / `parseFloat` / `isNaN` / `isFinite`.
+
+## JSON
+
+- `JSON.parse` with a `reviver`.
+- `JSON.stringify` with a function or array `replacer`, `toJSON`, and `space` (number or string, clamped to 10). `undefined` / function / symbol values follow the standard omission rules.
+- Object keys are emitted in insertion order, with integer keys ordered numerically; circular references throw.
+
+## Date
+
+- `Date` backed by `gmtime_r`; ISO 8601 parsing through `Date.parse` / `new Date(string)`.
+
+## RegExp
+
+- `RegExp` uses POSIX ERE (`regcomp` / `regexec`) for `test` / `exec`, with capture groups exposed through `exec` / `match` / `replace` / `split` / `search`.
+- Matching is byte-oriented and `/g` / `/y` `lastIndex` is not honoured — see [Runtime deviations](../unimplemented/deviations.md).
+
+## Symbol
+
+- `Symbol(description)` primitives (`XT_OBJECT_KIND_SYMBOL`), the 13 well-known symbols (`Symbol.iterator`, `Symbol.asyncIterator`, `Symbol.match`, ...), `Symbol.for` / `Symbol.keyFor` global registry, `symbol.description` / `toString()` / `valueOf()`.
+- Symbols are valid property keys (`Object.getOwnPropertySymbols`, symbol keyed `get`/`set`/`in`/`delete`), are skipped by `Object.keys` / `values` / `entries` / `for...in` / `JSON.stringify`, and print as `Symbol(desc)`.
+
+## URLSearchParams
+
+- `URLSearchParams` is implemented in `runtime/xt_url.c`.
+
+## Errors
+
+- The `Error` family: `Error`, `TypeError`, `RangeError`, `SyntaxError`, `ReferenceError`, `EvalError`, `URIError`, `AggregateError` — `new`, `instanceof`, `extends`, `String(err)` / `err.toString()` and `.stack`.
+- `Promise.any` rejects with an `AggregateError`.
+- `.stack` contains function-level frames (`at name (file:line)`), captured from the runtime shadow call stack; the exact limitations are in [Runtime deviations](../unimplemented/deviations.md).
+
+## console
+
+- `xt_print` / `xt_println` / `xt_console_log` / `info` / `warn` / `error`; `info` / `log` go to stdout, `warn` / `error` to stderr.
+- Node-style inspection: arrays `[ a, b ]`, objects `{ k: v }`, UTF-8-aware, with circular references marked.
+- `dir` / `trace` / `assert` / `count` / `countReset` / `group` / `groupEnd` / `table` / `time` / `timeEnd` / `timeLog`.
+
+## Global functions
+
+- `parseInt` `parseFloat` `isNaN` `isFinite` `Number` `String` `Boolean` `encodeURI` `decodeURI` `encodeURIComponent` `decodeURIComponent`.
+- `btoa` / `atob` base64 encoding and decoding (core globals; not Node-extension-only).
+- `structuredClone`: arrays, objects, `Map`, `Set`, `Date`, `RegExp` and typed arrays, preserving cycles and shared references; functions, symbols, promises and generators are rejected.
+- Timers, `queueMicrotask` and `performance.now` are described in [Async, promises and generators](./async.md); `fetch` in [fetch](./fetch.md).

package/doc/implemented/strings.md

@@ -0,0 +1,27 @@
+# Strings and text
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/strings.md)
+
+Location: the string value lives in the core runtime (`runtime/xt_values.c`);
+the method surface is dispatched from `runtime/xt_stdlib.c` / `xt_stdlib2.c`;
+`TextEncoder` / `TextDecoder` live in `runtime/xt_text_codec.c`.
+
+## Value model
+
+- UTF-8 storage exposed through JavaScript's UTF-16 view: `length`, indexing, `slice`, `indexOf`, `split`, `padStart` and `codePointAt` count code units; `for...of` and `Array.from` count code points; lone surrogate halves are kept as WTF-8 and recombined on concatenation.
+- Lazy cons-node concatenation: bytes are flattened on first observation, so append loops stay linear.
+- Equality comparison, and formatted number-to-string.
+- `xt_string_length` reports bytes for I/O; `xt_string_utf16_length` reports the JavaScript length.
+
+## Methods
+
+- `charAt` `charCodeAt` `codePointAt` `indexOf` `lastIndexOf` `includes` `startsWith` `endsWith` `slice` `substring` `substr` `split` `match` `replace` `replaceAll` `search` `toUpperCase` `toLowerCase` `trim` `trimStart` `trimEnd` `padStart` `padEnd` `repeat` `concat` `at` `localeCompare` `valueOf`
+- `String.match` / `lastIndexOf` / `split` with a limit; RegExp capture groups flow through `match` / `replace` / `split` / `search` (see [Standard library](./stdlib.md)).
+- `String` statics: `fromCharCode` / `fromCodePoint` / `raw`; tagged templates keep their raw strings.
+
+## Text encoding
+
+- `TextEncoder` / `TextDecoder` encode and decode through a `Uint8Array`; only the UTF-8 encoding is supported.
+
+Known divergences (`String.prototype.normalize`, byte-oriented RegExp matching)
+are listed in [Unimplemented: standard library](../unimplemented/stdlib.md).

package/doc/implemented/tests.md

@@ -0,0 +1,10 @@
+# Tests
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/tests.md)
+
+Location: `tests/` (`lexer` / `parser` / `binder` / `codegen` / `driver` / `extensions` / `cli` / `e2e`)
+
+- Per-module unit tests mirror the source tree.
+- `tests/e2e/` compiles real programs and runs the resulting binaries. When `clang` is absent the suite skips itself automatically; it is not a silent pass.
+- `tests/e2e/differential-*.test.ts` runs the same source through both `xbintsc` and Node and compares output byte-for-byte. When semantics change, add a differential case instead of a hand-written expected string.
+- Feature pages in this directory record the supported behaviour; the tests are the executable form of that contract. See [Contributing](../ai/contributing.md) for the gate (`npm run typecheck && npm run lint && npm test`).

package/doc/implemented/typed-arrays.md

@@ -0,0 +1,26 @@
+# Typed arrays and binary data
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/typed-arrays.md)
+
+Location: `runtime/xt_typed_array.c`, `runtime/xt_array_buffer.c`.
+
+## Typed arrays
+
+- `Uint8Array`, `Int8Array`, `Uint8ClampedArray`, `Uint16Array`, `Int16Array`, `Uint32Array`, `Int32Array`, `Float32Array`, `Float64Array`.
+- Construction: `new X(n)` / `new X(iterable)` / `new X(buffer[, offset[, length]])` / `X.from` / `X.of`.
+- Properties: `length` / `byteLength` / `byteOffset` / `.buffer` / `BYTES_PER_ELEMENT`.
+- Element reads/writes apply the per-type coercion (`ToIntN` / `ToUintN`, `Uint8ClampedArray` rounding, `Float32` single-precision rounding).
+- Prototype methods: `fill` / `set` / `slice` / `subarray` / `join` / `toString` / `indexOf` / `lastIndexOf` / `includes` / `forEach` / `map` / `filter` / `every` / `some` / `find` / `findIndex` / `reduce` / `reverse` / `sort` / `copyWithin` / `at` / `keys` / `values` / `entries`. Iterator methods still return arrays, not iterator objects.
+- Typed arrays are views over an `ArrayBuffer`; `subarray` shares the buffer and `slice` copies.
+
+## ArrayBuffer and DataView
+
+- `ArrayBuffer`: `byteLength`, `slice`, `ArrayBuffer.isView`.
+- `DataView`: big-endian by default, optional `littleEndian`, with `get` / `set` for Uint8 / Int8 / Uint16 / Int16 / Uint32 / Int32 / Float32 / Float64.
+- Multiple views over one buffer share its bytes.
+
+## Not implemented
+
+- `BigInt64Array` / `BigUint64Array`.
+- `Buffer`-backed typed-array views.
+- `TextEncoder` / `TextDecoder` are implemented (UTF-8) and documented in [Strings and text](./strings.md); `structuredClone` copies typed arrays.

package/doc/implemented/value-model.md

@@ -0,0 +1,18 @@
+# Value model and calling convention
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/value-model.md)
+
+Location: `src/codegen/values.ts`, `runtime/rt.h`
+
+- All JS values are unified as a 64-bit `xt_value` (NaN-boxing).
+- Doubles are not boxed; other types are tagged pointers with a 16-bit tag in the high bits and a 48-bit payload.
+- Tags: `undefined` / `null` / `false` / `true` / `string` / `object` / `array` / `function`.
+- Uniform function ABI:
+
+```c
+xt_value fn(xt_value thisValue, xt_value env, int32_t argc, xt_value *argv);
+```
+
+- `thisValue` is threaded as the first ABI parameter (exception-safe, supports nesting); arrow functions inherit `this` lexically from an extra environment slot.
+- Closures thread captured variables through `env` (by reference, boxed); direct calls and closure calls share one code path.
+- `xt_object` carries a prototype field, and property lookup walks the prototype chain; `xt_function` carries a `prototype` and a property bag (static members). `xt_array` also carries a `[[Prototype]]` (Array.prototype). `Object.prototype` is the root of ordinary objects and provides `hasOwnProperty` / `toString` / `valueOf` / `isPrototypeOf` / `propertyIsEnumerable` / `__proto__`; `Object.getPrototypeOf({}) === Object.prototype`.