xbintsc 0.5.22 → 0.5.31
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +12 -3
- package/README.md +46 -11
- package/README.zh-CN.md +32 -6
- package/dist/scripts/support-matrix.d.ts +18 -0
- package/dist/scripts/support-matrix.js +141 -0
- package/dist/scripts/support-matrix.js.map +1 -0
- package/dist/src/ast/common.d.ts +2 -2
- package/dist/src/ast/declarations.d.ts +7 -1
- package/dist/src/ast/expressions.d.ts +5 -0
- package/dist/src/ast/kinds.d.ts +2 -0
- package/dist/src/ast/kinds.js +2 -0
- package/dist/src/ast/kinds.js.map +1 -1
- package/dist/src/binder/binder.d.ts +2 -1
- package/dist/src/binder/binder.js +2 -0
- package/dist/src/binder/binder.js.map +1 -1
- package/dist/src/binder/declarations.d.ts +9 -0
- package/dist/src/binder/declarations.js +64 -0
- package/dist/src/binder/declarations.js.map +1 -1
- package/dist/src/binder/references.js +85 -3
- package/dist/src/binder/references.js.map +1 -1
- package/dist/src/binder/types.d.ts +32 -0
- package/dist/src/binder/types.js.map +1 -1
- package/dist/src/canonical.d.ts +29 -0
- package/dist/src/canonical.js +35 -0
- package/dist/src/canonical.js.map +1 -0
- package/dist/src/checker/assignability.d.ts +13 -0
- package/dist/src/checker/assignability.js +146 -0
- package/dist/src/checker/assignability.js.map +1 -0
- package/dist/src/checker/calls.d.ts +13 -0
- package/dist/src/checker/calls.js +127 -0
- package/dist/src/checker/calls.js.map +1 -0
- package/dist/src/checker/checker.d.ts +26 -0
- package/dist/src/checker/checker.js +31 -0
- package/dist/src/checker/checker.js.map +1 -0
- package/dist/src/checker/declarations.d.ts +9 -0
- package/dist/src/checker/declarations.js +15 -0
- package/dist/src/checker/declarations.js.map +1 -0
- package/dist/src/checker/flow.d.ts +21 -0
- package/dist/src/checker/flow.js +241 -0
- package/dist/src/checker/flow.js.map +1 -0
- package/dist/src/checker/globals.d.ts +9 -0
- package/dist/src/checker/globals.js +29 -0
- package/dist/src/checker/globals.js.map +1 -0
- package/dist/src/checker/source.d.ts +38 -0
- package/dist/src/checker/source.js +48 -0
- package/dist/src/checker/source.js.map +1 -0
- package/dist/src/checker/type-infer.d.ts +18 -0
- package/dist/src/checker/type-infer.js +173 -0
- package/dist/src/checker/type-infer.js.map +1 -0
- package/dist/src/checker/type-model.d.ts +73 -0
- package/dist/src/checker/type-model.js +151 -0
- package/dist/src/checker/type-model.js.map +1 -0
- package/dist/src/checker/type-system.d.ts +58 -0
- package/dist/src/checker/type-system.js +569 -0
- package/dist/src/checker/type-system.js.map +1 -0
- package/dist/src/checker/typecheck-types.d.ts +22 -0
- package/dist/src/checker/typecheck-types.js +109 -0
- package/dist/src/checker/typecheck-types.js.map +1 -0
- package/dist/src/checker/typecheck.d.ts +62 -0
- package/dist/src/checker/typecheck.js +574 -0
- package/dist/src/checker/typecheck.js.map +1 -0
- package/dist/src/checker/undefined.d.ts +14 -0
- package/dist/src/checker/undefined.js +32 -0
- package/dist/src/checker/undefined.js.map +1 -0
- package/dist/src/checker/walk.d.ts +10 -0
- package/dist/src/checker/walk.js +15 -0
- package/dist/src/checker/walk.js.map +1 -0
- package/dist/src/cli/help.d.ts +7 -0
- package/dist/src/cli/help.js +64 -0
- package/dist/src/cli/help.js.map +1 -0
- package/dist/src/cli/hints.js +13 -1
- package/dist/src/cli/hints.js.map +1 -1
- package/dist/src/cli/main.js +12 -48
- package/dist/src/cli/main.js.map +1 -1
- package/dist/src/codegen/generator/calls/access.js +8 -8
- package/dist/src/codegen/generator/calls/access.js.map +1 -1
- package/dist/src/codegen/generator/calls/invocation.js +9 -4
- package/dist/src/codegen/generator/calls/invocation.js.map +1 -1
- package/dist/src/codegen/generator/calls/super.d.ts +9 -1
- package/dist/src/codegen/generator/calls/super.js +56 -5
- package/dist/src/codegen/generator/calls/super.js.map +1 -1
- package/dist/src/codegen/generator/context.d.ts +13 -2
- package/dist/src/codegen/generator/context.js +25 -19
- package/dist/src/codegen/generator/context.js.map +1 -1
- package/dist/src/codegen/generator/debug.js +2 -1
- package/dist/src/codegen/generator/debug.js.map +1 -1
- package/dist/src/codegen/generator/expressions/primary.d.ts +4 -1
- package/dist/src/codegen/generator/expressions/primary.js +68 -8
- package/dist/src/codegen/generator/expressions/primary.js.map +1 -1
- package/dist/src/codegen/generator/generator.js +11 -1
- package/dist/src/codegen/generator/generator.js.map +1 -1
- package/dist/src/codegen/generator/module.d.ts +2 -0
- package/dist/src/codegen/generator/module.js +62 -26
- package/dist/src/codegen/generator/module.js.map +1 -1
- package/dist/src/codegen/generator/state.d.ts +11 -1
- package/dist/src/codegen/generator/state.js.map +1 -1
- package/dist/src/codegen/generator/statements/variables.js +20 -3
- package/dist/src/codegen/generator/statements/variables.js.map +1 -1
- package/dist/src/codegen/generator/tables.d.ts +2 -0
- package/dist/src/codegen/generator/tables.js +4 -0
- package/dist/src/codegen/generator/tables.js.map +1 -1
- package/dist/src/driver/build-key.d.ts +2 -0
- package/dist/src/driver/build-key.js +1 -0
- package/dist/src/driver/build-key.js.map +1 -1
- package/dist/src/driver/bundler/graph.js +5 -1
- package/dist/src/driver/bundler/graph.js.map +1 -1
- package/dist/src/driver/bundler/merge.js +16 -1
- package/dist/src/driver/bundler/merge.js.map +1 -1
- package/dist/src/driver/bundler/types.d.ts +12 -0
- package/dist/src/driver/compiler.d.ts +1 -1
- package/dist/src/driver/compiler.js +4 -0
- package/dist/src/driver/compiler.js.map +1 -1
- package/dist/src/driver/fingerprint.js +2 -1
- package/dist/src/driver/fingerprint.js.map +1 -1
- package/dist/src/driver/frontend.d.ts +8 -6
- package/dist/src/driver/frontend.js +4 -0
- package/dist/src/driver/frontend.js.map +1 -1
- package/dist/src/driver/options.d.ts +6 -0
- package/dist/src/driver/version.d.ts +1 -1
- package/dist/src/driver/version.js +1 -1
- package/dist/src/extensions/catalog.js +2 -1
- package/dist/src/extensions/catalog.js.map +1 -1
- package/dist/src/extensions/gui/html.js +20 -6
- package/dist/src/extensions/gui/html.js.map +1 -1
- package/dist/src/extensions/gui/index.js +63 -0
- package/dist/src/extensions/gui/index.js.map +1 -1
- package/dist/src/extensions/media/index.d.ts +27 -0
- package/dist/src/extensions/media/index.js +60 -0
- package/dist/src/extensions/media/index.js.map +1 -0
- package/dist/src/extensions/registry.d.ts +50 -0
- package/dist/src/extensions/registry.js +26 -0
- package/dist/src/extensions/registry.js.map +1 -1
- package/dist/src/index.d.ts +2 -0
- package/dist/src/index.js +2 -0
- package/dist/src/index.js.map +1 -1
- package/dist/src/parser/declarations/classes.js +7 -0
- package/dist/src/parser/declarations/classes.js.map +1 -1
- package/dist/src/parser/expressions.js +14 -1
- package/dist/src/parser/expressions.js.map +1 -1
- package/dist/src/parser/literals.js +6 -2
- package/dist/src/parser/literals.js.map +1 -1
- package/dist/tests/binder/binder.test.js +29 -0
- package/dist/tests/binder/binder.test.js.map +1 -1
- package/dist/tests/canonical.test.d.ts +1 -0
- package/dist/tests/canonical.test.js +19 -0
- package/dist/tests/canonical.test.js.map +1 -0
- package/dist/tests/checker/checker.test.d.ts +1 -0
- package/dist/tests/checker/checker.test.js +245 -0
- package/dist/tests/checker/checker.test.js.map +1 -0
- package/dist/tests/cli/check.test.js +20 -0
- package/dist/tests/cli/check.test.js.map +1 -1
- package/dist/tests/cli/hints.test.js +15 -0
- package/dist/tests/cli/hints.test.js.map +1 -1
- package/dist/tests/cli/process.test.js +12 -0
- package/dist/tests/cli/process.test.js.map +1 -1
- package/dist/tests/conformance/matrix.test.d.ts +6 -0
- package/dist/tests/conformance/matrix.test.js +23 -0
- package/dist/tests/conformance/matrix.test.js.map +1 -0
- package/dist/tests/conformance/test262/manifest.d.ts +115 -0
- package/dist/tests/conformance/test262/manifest.js +257 -0
- package/dist/tests/conformance/test262/manifest.js.map +1 -0
- package/dist/tests/conformance/test262.test.d.ts +11 -0
- package/dist/tests/conformance/test262.test.js +74 -0
- package/dist/tests/conformance/test262.test.js.map +1 -0
- package/dist/tests/docs/structure.test.js +9 -11
- package/dist/tests/docs/structure.test.js.map +1 -1
- package/dist/tests/e2e/child-process.test.js +3 -2
- package/dist/tests/e2e/child-process.test.js.map +1 -1
- package/dist/tests/e2e/compile-builtins.test.js +21 -0
- package/dist/tests/e2e/compile-builtins.test.js.map +1 -1
- package/dist/tests/e2e/compile-objects-classes.test.js +54 -0
- package/dist/tests/e2e/compile-objects-classes.test.js.map +1 -1
- package/dist/tests/e2e/differential-syntax.test.d.ts +5 -0
- package/dist/tests/e2e/differential-syntax.test.js +95 -0
- package/dist/tests/e2e/differential-syntax.test.js.map +1 -0
- package/dist/tests/e2e/differential-values.test.js +15 -0
- package/dist/tests/e2e/differential-values.test.js.map +1 -1
- package/dist/tests/e2e/gui-browser.test.d.ts +13 -0
- package/dist/tests/e2e/gui-browser.test.js +163 -0
- package/dist/tests/e2e/gui-browser.test.js.map +1 -0
- package/dist/tests/e2e/gui-example-browser.test.js +2 -2
- package/dist/tests/e2e/gui-example-browser.test.js.map +1 -1
- package/dist/tests/e2e/gui-example-canvas.test.js +8 -5
- package/dist/tests/e2e/gui-example-canvas.test.js.map +1 -1
- package/dist/tests/e2e/gui-example-svg.test.js +4 -3
- package/dist/tests/e2e/gui-example-svg.test.js.map +1 -1
- package/dist/tests/e2e/gui-example.test.js +4 -3
- package/dist/tests/e2e/gui-example.test.js.map +1 -1
- package/dist/tests/e2e/gui-helpers.d.ts +3 -0
- package/dist/tests/e2e/gui-helpers.js +6 -3
- package/dist/tests/e2e/gui-helpers.js.map +1 -1
- package/dist/tests/e2e/gui-media-disabled.test.d.ts +9 -0
- package/dist/tests/e2e/gui-media-disabled.test.js +42 -0
- package/dist/tests/e2e/gui-media-disabled.test.js.map +1 -0
- package/dist/tests/e2e/gui-media.test.d.ts +6 -4
- package/dist/tests/e2e/gui-media.test.js +20 -16
- package/dist/tests/e2e/gui-media.test.js.map +1 -1
- package/dist/tests/e2e/harness.d.ts +9 -0
- package/dist/tests/e2e/harness.js +14 -2
- package/dist/tests/e2e/harness.js.map +1 -1
- package/dist/tests/e2e/native-extensions.test.js +2 -1
- package/dist/tests/e2e/native-extensions.test.js.map +1 -1
- package/dist/tests/e2e/property-descriptors.test.js +20 -0
- package/dist/tests/e2e/property-descriptors.test.js.map +1 -1
- package/dist/tests/e2e/unicode-output.test.d.ts +16 -0
- package/dist/tests/e2e/unicode-output.test.js +67 -0
- package/dist/tests/e2e/unicode-output.test.js.map +1 -0
- package/dist/tests/e2e/weak-collections.test.js +16 -2
- package/dist/tests/e2e/weak-collections.test.js.map +1 -1
- package/dist/tests/extensions/media.test.d.ts +1 -0
- package/dist/tests/extensions/media.test.js +58 -0
- package/dist/tests/extensions/media.test.js.map +1 -0
- package/dist/tests/extensions/registry.test.js +8 -0
- package/dist/tests/extensions/registry.test.js.map +1 -1
- package/dist/tests/helpers.d.ts +1 -0
- package/dist/tests/helpers.js +1 -0
- package/dist/tests/helpers.js.map +1 -1
- package/dist/tests/lexer/identifiers.test.js +12 -0
- package/dist/tests/lexer/identifiers.test.js.map +1 -1
- package/dist/tests/lexer/scanner.test.js +8 -0
- package/dist/tests/lexer/scanner.test.js.map +1 -1
- package/dist/tests/lexer/strings.test.js +30 -0
- package/dist/tests/lexer/strings.test.js.map +1 -1
- package/dist/tests/parser/declarations.test.js +20 -0
- package/dist/tests/parser/declarations.test.js.map +1 -1
- package/dist/tests/parser/expressions.test.js +36 -0
- package/dist/tests/parser/expressions.test.js.map +1 -1
- package/dist/tests/platform.d.ts +32 -0
- package/dist/tests/platform.js +40 -0
- package/dist/tests/platform.js.map +1 -0
- package/dist/tests/platform.test.d.ts +12 -0
- package/dist/tests/platform.test.js +51 -0
- package/dist/tests/platform.test.js.map +1 -0
- package/dist/tests/version.test.js +4 -4
- package/dist/tests/version.test.js.map +1 -1
- package/doc/ai/README.md +10 -4
- package/doc/ai/build-recipe.md +1 -0
- package/doc/ai/cli.md +18 -6
- package/doc/ai/contributing.md +59 -2
- package/doc/ai/extensions.md +46 -23
- package/doc/ai/language-support.md +25 -16
- package/doc/ai/troubleshooting.md +9 -0
- package/doc/ai/zh-CN/README.md +9 -4
- package/doc/ai/zh-CN/build-recipe.md +1 -0
- package/doc/ai/zh-CN/cli.md +14 -4
- package/doc/ai/zh-CN/contributing.md +49 -3
- package/doc/ai/zh-CN/extensions.md +29 -8
- package/doc/ai/zh-CN/language-support.md +23 -14
- package/doc/ai/zh-CN/troubleshooting.md +8 -0
- package/doc/gui/api.md +45 -0
- package/doc/gui/build.md +37 -21
- package/doc/gui/known-issues.md +17 -6
- package/doc/gui/media.md +26 -11
- package/doc/gui/runtime.md +18 -0
- package/doc/gui-scripts.md +7 -0
- package/doc/gui.md +43 -33
- package/doc/implemented/binder.md +2 -0
- package/doc/implemented/checker.md +117 -0
- package/doc/implemented/cli.md +13 -1
- package/doc/implemented/codegen.md +3 -2
- package/doc/implemented/driver.md +2 -2
- package/doc/implemented/operators.md +2 -1
- package/doc/implemented/parser.md +3 -2
- package/doc/implemented/pipeline.md +8 -1
- package/doc/implemented/stdlib.md +2 -1
- package/doc/implemented/tests.md +3 -1
- package/doc/implemented.md +2 -0
- package/doc/npm-package.md +417 -0
- package/doc/requirements.md +4 -1
- package/doc/support-matrix.md +83 -0
- package/doc/unimplemented/classes.md +3 -0
- package/doc/unimplemented/deviations.md +3 -2
- package/doc/unimplemented/toolchain.md +1 -1
- package/doc/unimplemented/types.md +24 -8
- package/doc/unimplemented.md +1 -1
- package/doc/zh-CN/gui/api.md +41 -0
- package/doc/zh-CN/gui/build.md +28 -16
- package/doc/zh-CN/gui/known-issues.md +13 -5
- package/doc/zh-CN/gui/media.md +21 -10
- package/doc/zh-CN/gui/runtime.md +16 -0
- package/doc/zh-CN/gui-scripts.md +5 -0
- package/doc/zh-CN/gui.md +37 -32
- package/doc/zh-CN/implemented/binder.md +2 -0
- package/doc/zh-CN/implemented/checker.md +99 -0
- package/doc/zh-CN/implemented/cli.md +12 -1
- package/doc/zh-CN/implemented/codegen.md +3 -2
- package/doc/zh-CN/implemented/driver.md +2 -2
- package/doc/zh-CN/implemented/operators.md +1 -1
- package/doc/zh-CN/implemented/parser.md +3 -2
- package/doc/zh-CN/implemented/pipeline.md +3 -1
- package/doc/zh-CN/implemented/stdlib.md +2 -1
- package/doc/zh-CN/implemented/tests.md +3 -1
- package/doc/zh-CN/implemented.md +2 -0
- package/doc/zh-CN/npm-package.md +391 -0
- package/doc/zh-CN/post/announce.md +47 -47
- package/doc/zh-CN/requirements.md +4 -1
- package/doc/zh-CN/support-matrix.md +82 -0
- package/doc/zh-CN/unimplemented/classes.md +3 -0
- package/doc/zh-CN/unimplemented/deviations.md +3 -2
- package/doc/zh-CN/unimplemented/toolchain.md +1 -1
- package/doc/zh-CN/unimplemented/types.md +16 -6
- package/doc/zh-CN/unimplemented.md +1 -1
- package/llms.txt +4 -1
- package/package.json +3 -1
- package/runtime/ext_gui/audio.cpp +316 -0
- package/runtime/ext_gui/browser.cpp +547 -0
- package/runtime/ext_gui/browser_escape.cpp +85 -0
- package/runtime/ext_gui/browser_loop.cpp +83 -0
- package/runtime/ext_gui/canvas.cpp +9 -3
- package/runtime/ext_gui/canvas_raster.cpp +19 -1
- package/runtime/ext_gui/dom_api.cpp +36 -0
- package/runtime/ext_gui/dom_api_document.cpp +96 -5
- package/runtime/ext_gui/dom_api_events.cpp +20 -0
- package/runtime/ext_gui/dom_api_internal.h +19 -0
- package/runtime/ext_gui/dom_api_proto.cpp +6 -0
- package/runtime/ext_gui/gui.cpp +90 -23
- package/runtime/ext_gui/gui_engine.h +44 -0
- package/runtime/ext_gui/gui_media.cpp +69 -2
- package/runtime/ext_gui/media.cpp +34 -488
- package/runtime/ext_gui/media.h +54 -19
- package/runtime/ext_gui/media_api.h +65 -0
- package/runtime/ext_gui/window.cpp +9 -0
- package/runtime/ext_media/media.cpp +507 -0
- package/runtime/ext_media/media_bridge.c +35 -0
- package/runtime/ext_node/path/path.c +7 -7
- package/runtime/ext_node/url/url.c +4 -2
- package/runtime/rt.h +15 -0
- package/runtime/xt_constructors.c +2 -1
- package/runtime/xt_containers/objects.inc +22 -2
- package/runtime/xt_io/exception.inc +4 -2
- package/runtime/xt_stdlib/math.inc +62 -0
- package/runtime/xt_stdlib2/date.inc +7 -1
- package/runtime/xt_stdlib2/objects.inc +14 -0
- package/scripts/build-gui.ts +6 -72
- package/scripts/build-media.ts +245 -0
- package/scripts/support-matrix.ts +167 -0
- package/src/ast/common.ts +2 -0
- package/src/ast/declarations.ts +12 -1
- package/src/ast/expressions.ts +6 -0
- package/src/ast/kinds.ts +2 -0
- package/src/binder/binder.ts +3 -0
- package/src/binder/declarations.ts +70 -0
- package/src/binder/references.ts +84 -3
- package/src/binder/types.ts +30 -0
- package/src/canonical.ts +37 -0
- package/src/checker/assignability.ts +134 -0
- package/src/checker/calls.ts +135 -0
- package/src/checker/checker.ts +47 -0
- package/src/checker/declarations.ts +26 -0
- package/src/checker/flow.ts +236 -0
- package/src/checker/globals.ts +40 -0
- package/src/checker/source.ts +53 -0
- package/src/checker/type-infer.ts +185 -0
- package/src/checker/type-model.ts +212 -0
- package/src/checker/type-system.ts +578 -0
- package/src/checker/typecheck-types.ts +112 -0
- package/src/checker/typecheck.ts +586 -0
- package/src/checker/undefined.ts +43 -0
- package/src/checker/walk.ts +16 -0
- package/src/cli/help.ts +65 -0
- package/src/cli/hints.ts +13 -1
- package/src/cli/main.ts +12 -49
- package/src/codegen/generator/calls/access.ts +8 -8
- package/src/codegen/generator/calls/invocation.ts +8 -5
- package/src/codegen/generator/calls/super.ts +67 -5
- package/src/codegen/generator/context.ts +31 -19
- package/src/codegen/generator/debug.ts +2 -1
- package/src/codegen/generator/expressions/primary.ts +84 -13
- package/src/codegen/generator/generator.ts +11 -1
- package/src/codegen/generator/module.ts +65 -24
- package/src/codegen/generator/state.ts +11 -1
- package/src/codegen/generator/statements/variables.ts +20 -3
- package/src/codegen/generator/tables.ts +5 -0
- package/src/driver/build-key.ts +3 -0
- package/src/driver/bundler/graph.ts +6 -2
- package/src/driver/bundler/merge.ts +14 -1
- package/src/driver/bundler/types.ts +13 -0
- package/src/driver/compiler.ts +5 -1
- package/src/driver/fingerprint.ts +2 -1
- package/src/driver/frontend.ts +13 -2
- package/src/driver/options.ts +6 -0
- package/src/driver/version.ts +1 -1
- package/src/extensions/catalog.ts +2 -1
- package/src/extensions/gui/html.ts +23 -10
- package/src/extensions/gui/index.ts +65 -0
- package/src/extensions/media/index.ts +67 -0
- package/src/extensions/registry.ts +72 -0
- package/src/index.ts +2 -0
- package/src/parser/declarations/classes.ts +7 -0
- package/src/parser/expressions.ts +13 -1
- package/src/parser/literals.ts +6 -2
|
@@ -21,8 +21,15 @@ source.ts
|
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
- Front end, back end, runtime and extensions are fully decoupled.
|
|
24
|
-
- The flow is orchestrated by `src/driver/compiler.ts`: `read → parse → bind → IR → object file → link`. The front end lives in `src/driver/frontend.ts`, the cache key in `src/driver/build-key.ts`, runtime compilation in `src/driver/runtime-objects.ts`, and platform artifacts in `src/driver/app-artifacts.ts`.
|
|
24
|
+
- The flow is orchestrated by `src/driver/compiler.ts`: `read → parse → bind → check → IR → object file → link`. The front end lives in `src/driver/frontend.ts`, the cache key in `src/driver/build-key.ts`, runtime compilation in `src/driver/runtime-objects.ts`, and platform artifacts in `src/driver/app-artifacts.ts`.
|
|
25
|
+
- The [semantic checker](./checker.md) (`src/checker/`) runs between binding and code generation unless `--no-check` is passed. It combines inference-free checks (unresolved names, redeclarations, call arity) with a small structural type model (definite assignability, property shapes, simple generics and flow narrowing); the type syntax itself is still erased afterwards.
|
|
25
26
|
- **Self-hosting**: `xbintsc` compiles its own front end. Building `src/cli/main.ts`
|
|
26
27
|
with the compiler yields a working `xbintsc` binary, and that binary rebuilds
|
|
27
28
|
itself with byte-identical LLVM IR (source ≡ generation 1 ≡ generation 2 ≡
|
|
28
29
|
generation 3). The runtime is still hand-written C.
|
|
30
|
+
- **Canonical artifacts**: anything byte-compared uses one encoding on every
|
|
31
|
+
host. `src/canonical.ts` defines the IR/debug/fingerprint path separator (`/`)
|
|
32
|
+
and line ending (LF), with `artifactPath()` for native paths entering an
|
|
33
|
+
artifact; the runtime uses `XT_ARTIFACT_PATH_SEPARATOR` (`runtime/rt.h`) when it renders
|
|
34
|
+
`path` results and `file://` URLs. User-facing native paths — diagnostics,
|
|
35
|
+
`import.meta.filename`, `process.cwd()` — keep the host separator, like Node.
|
|
@@ -15,7 +15,7 @@ own pages: [Collections](./collections.md), [Typed arrays and binary data](./typ
|
|
|
15
15
|
## Objects
|
|
16
16
|
|
|
17
17
|
- `Object.keys` / `values` / `entries` / `assign` / `getOwnPropertyNames` / `groupBy`, object spread `{...obj}`.
|
|
18
|
-
- `Object.defineProperty` / `getOwnPropertyDescriptor(s)` — data and accessor descriptors; the attribute flags are reported but not enforced on later writes/enumeration.
|
|
18
|
+
- `Object.defineProperty` / `defineProperties` / `getOwnPropertyDescriptor(s)` — data and accessor descriptors, one at a time or in bulk; the attribute flags are reported but not enforced on later writes/enumeration.
|
|
19
19
|
- `Object.freeze` / `is_frozen` / `from_entries`, `Object.getPrototypeOf`.
|
|
20
20
|
- `Object.prototype`: `hasOwnProperty` / `toString` / `valueOf` / `isPrototypeOf` / `propertyIsEnumerable` / `__proto__`; `Object.getPrototypeOf({}) === Object.prototype`.
|
|
21
21
|
- 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).
|
|
@@ -32,6 +32,7 @@ own pages: [Collections](./collections.md), [Typed arrays and binary data](./typ
|
|
|
32
32
|
- 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.
|
|
33
33
|
- `BigInt` literals and values: arbitrary precision arithmetic, bitwise and shift operators, comparisons, `toString(radix)`, `BigInt()`, `BigInt.asIntN` / `BigInt.asUintN`.
|
|
34
34
|
- `Math`: the full function set and constants.
|
|
35
|
+
- `Math` is also a first-class object: `const cos = Math.cos`, `[1, 2].map(Math.max)` and `const { sqrt, PI } = Math` read members as values (`xt_math_object()` caches one native closure per function, so reads stay cheap).
|
|
35
36
|
- `Number` statics and `Number()` conversion; `parseInt` / `parseFloat` / `isNaN` / `isFinite`.
|
|
36
37
|
|
|
37
38
|
## JSON
|
package/doc/implemented/tests.md
CHANGED
|
@@ -2,9 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/tests.md)
|
|
4
4
|
|
|
5
|
-
Location: `tests/` (`lexer` / `parser` / `binder` / `codegen` / `driver` / `extensions` / `cli` / `e2e`)
|
|
5
|
+
Location: `tests/` (`lexer` / `parser` / `binder` / `checker` / `codegen` / `driver` / `extensions` / `cli` / `conformance` / `e2e`)
|
|
6
6
|
|
|
7
7
|
- Per-module unit tests mirror the source tree.
|
|
8
8
|
- `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.
|
|
9
9
|
- `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.
|
|
10
|
+
- `tests/conformance/` is the executable definition of the supported subset: it runs a pinned, vendored subset of [test262](https://github.com/tc39/test262) (unmodified files under `tests/conformance/test262/cases/`), compiling and executing each supported case. Unsupported cases are valid JavaScript that xbintsc still rejects, pinned with the diagnostic code it produces. [`doc/support-matrix.md`](../support-matrix.md) is generated from the same catalogue (`npm run docs:matrix`), and a test fails when the committed table is stale. See [`tests/conformance/test262/SOURCE.md`](../../tests/conformance/test262/SOURCE.md) for the pinned commit and the harness adaptation.
|
|
11
|
+
- `tests/checker/` pins the checker: unresolved names, same-scope redeclarations, call arity, structural assignability, property shapes and the narrowings that must stay legal.
|
|
10
12
|
- 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.md
CHANGED
|
@@ -22,6 +22,7 @@ small file instead of a single monolithic document.
|
|
|
22
22
|
- [Lexer](./implemented/lexer.md) — tokens, literals, keywords, lexical diagnostics
|
|
23
23
|
- [Parser](./implemented/parser.md) — statements, expressions, type syntax, ASI
|
|
24
24
|
- [Name binding and scopes](./implemented/binder.md) — scopes, symbols, closure capture
|
|
25
|
+
- [Semantic checker](./implemented/checker.md) — opt-out names, redeclarations and call arity
|
|
25
26
|
|
|
26
27
|
### Semantics and code generation
|
|
27
28
|
|
|
@@ -58,6 +59,7 @@ same file.
|
|
|
58
59
|
| tokenizer, literals, keywords | [Lexer](./implemented/lexer.md) |
|
|
59
60
|
| statement/expression/type syntax | [Parser](./implemented/parser.md) |
|
|
60
61
|
| scopes, symbols, captures | [Name binding](./implemented/binder.md) |
|
|
62
|
+
| checker diagnostics (names, redeclarations, arity) | [Semantic checker](./implemented/checker.md) |
|
|
61
63
|
| operators, assignment lowering | [Operators](./implemented/operators.md) |
|
|
62
64
|
| value representation, function ABI | [Value model](./implemented/value-model.md) |
|
|
63
65
|
| control flow, expression lowering, classes, `main` | [Codegen](./implemented/codegen.md) |
|
|
@@ -0,0 +1,417 @@
|
|
|
1
|
+
# Using xbintsc from npm
|
|
2
|
+
|
|
3
|
+
> Language: **English** | [简体中文](./zh-CN/npm-package.md)
|
|
4
|
+
|
|
5
|
+
`xbintsc` is published on npm as a Node package. Install it in any Node project
|
|
6
|
+
to compile that project's TypeScript into a standalone native binary — no source
|
|
7
|
+
checkout, no downloaded release archive, and no global install required.
|
|
8
|
+
|
|
9
|
+
This page is the consumer guide for the npm package. For the compiler's flags
|
|
10
|
+
and config fields see [the CLI reference](./ai/cli.md); for the platform
|
|
11
|
+
toolchain see [requirements](./requirements.md).
|
|
12
|
+
|
|
13
|
+
## Quick start
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install --save-dev --save-exact xbintsc
|
|
17
|
+
npx xbintsc doctor # "status : ok" means clang is usable
|
|
18
|
+
npx xbintsc build src/main.ts --out build
|
|
19
|
+
./build/main # .\build\main.exe on Windows
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
The rest of this page explains the requirements, the first-build cost, CI and
|
|
23
|
+
the differences from a normal Node build.
|
|
24
|
+
|
|
25
|
+
## For AI agents
|
|
26
|
+
|
|
27
|
+
If you are an agent asked to build a project that already depends on `xbintsc`:
|
|
28
|
+
|
|
29
|
+
1. Run `npx xbintsc doctor`. If it exits non-zero, report the toolchain problem;
|
|
30
|
+
do not edit the program to work around a missing or old clang.
|
|
31
|
+
2. Find the entry file: `entry` in `xbintsc.config.json`, a package script that
|
|
32
|
+
invokes `xbintsc`, or the project's main TypeScript file (often
|
|
33
|
+
`src/main.ts`). When a config exists, `npx xbintsc build` needs no arguments.
|
|
34
|
+
3. Build with `npx xbintsc build <entry> --out build`. If the program imports
|
|
35
|
+
Node built-ins, add `--ext node`; the diagnostic names the missing extension.
|
|
36
|
+
4. Run the artifact (`./build/<name>`, `.exe` on Windows) and report its path.
|
|
37
|
+
5. If the build reports unsupported syntax, read the installed subset guide at
|
|
38
|
+
`node_modules/xbintsc/doc/ai/language-support.md`; do not assume
|
|
39
|
+
Node-compatible TypeScript. The first build also compiles the C runtime, so
|
|
40
|
+
allow more time than for an incremental build.
|
|
41
|
+
|
|
42
|
+
Do not run `npm install` inside `node_modules/xbintsc`, and do not substitute
|
|
43
|
+
`tsc`/`esbuild` for xbintsc: the native artifact must come from `npx xbintsc`.
|
|
44
|
+
`xbintsc` does not read `tsconfig.json`; use relative imports or package imports.
|
|
45
|
+
|
|
46
|
+
## What the npm package is
|
|
47
|
+
|
|
48
|
+
The package contains:
|
|
49
|
+
|
|
50
|
+
- the compiler CLI (`bin/xbintsc.js` plus the compiled JavaScript in `dist/`);
|
|
51
|
+
- the C runtime **sources** (`runtime/`), including the `node` extension sources;
|
|
52
|
+
- the project config schema and documentation.
|
|
53
|
+
|
|
54
|
+
It runs the compiler through Node.js. The binary it produces is still
|
|
55
|
+
standalone: it does not embed Node, V8 or a TypeScript compiler.
|
|
56
|
+
|
|
57
|
+
The package does **not** contain:
|
|
58
|
+
|
|
59
|
+
- a C compiler — you need clang 16+ on the machine that builds;
|
|
60
|
+
- prebuilt runtime archives (`runtime/lib/<os>-<arch>/core.a`). The driver
|
|
61
|
+
compiles the C runtime from the shipped sources on first use and caches the
|
|
62
|
+
objects, so the first build is slower (see [the cache](#the-first-build-and-the-cache));
|
|
63
|
+
- the GUI/media native archives (`gui.a`, `media.a`). If you need `--ext gui` or
|
|
64
|
+
`--ext media`, use a Linux/macOS release archive or build those archives from
|
|
65
|
+
a source checkout.
|
|
66
|
+
|
|
67
|
+
## Requirements
|
|
68
|
+
|
|
69
|
+
| Requirement | Why |
|
|
70
|
+
| --- | --- |
|
|
71
|
+
| Node.js **22+** | Runs the compiler itself. The produced binary does not need Node. |
|
|
72
|
+
| clang / LLVM **16+** | xbintsc emits LLVM IR and asks clang to compile and link it. |
|
|
73
|
+
| The platform linker / SDK | macOS: Xcode Command Line Tools. Linux: clang + lld. Windows: LLVM + the Visual Studio C++ build tools (MSVC ABI). |
|
|
74
|
+
|
|
75
|
+
Check them before the first build:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
node --version # v22.x or newer
|
|
79
|
+
npx xbintsc doctor # "status : ok" means the toolchain is usable
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`doctor` also reports the resolved compiler, runtime directory and runtime
|
|
83
|
+
library directory. On Windows, if the resolved clang cannot find the MSVC/SDK
|
|
84
|
+
headers by itself, run the build from an **x64 Native Tools Command Prompt for
|
|
85
|
+
VS 2022** (or **ARM64 Native Tools** on Windows on ARM). On distributions
|
|
86
|
+
whose default `clang` is older than 16 (for example Ubuntu 22.04 or Debian 12),
|
|
87
|
+
install a newer LLVM from its LLVM package repository and point
|
|
88
|
+
`xbintsc_CLANG` at that binary. Full per-platform instructions are in
|
|
89
|
+
[requirements](./requirements.md).
|
|
90
|
+
|
|
91
|
+
## Install it in the project
|
|
92
|
+
|
|
93
|
+
Install it as a development dependency in the Node project that will run the
|
|
94
|
+
build:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
npm install --save-dev --save-exact xbintsc
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
`--save-exact` pins the compiler version in `package.json`; the lockfile pins it
|
|
101
|
+
for everyone else. Pinning matters because the compiler version is part of the
|
|
102
|
+
incremental-cache key and a newer compiler can produce a different binary.
|
|
103
|
+
|
|
104
|
+
The equivalent commands for other package managers are `pnpm add -D xbintsc`
|
|
105
|
+
and `yarn add -D xbintsc`. The rest of this page uses npm and `npx`.
|
|
106
|
+
|
|
107
|
+
Verify the local install:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
npx xbintsc version
|
|
111
|
+
npx xbintsc doctor
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
`npx` prefers `node_modules/.bin/xbintsc`. If the project has no local install,
|
|
115
|
+
`npx` may download the latest version instead — convenient for a one-off, but
|
|
116
|
+
not reproducible. In CI, either install the dependency first or use
|
|
117
|
+
`npx --no-install xbintsc …` so a missing install fails instead of silently
|
|
118
|
+
fetching a different compiler.
|
|
119
|
+
|
|
120
|
+
### One-off run without adding a dependency
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
npx --yes xbintsc@latest build src/main.ts --out build
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Replace `latest` with an exact version if the artifact must be reproducible.
|
|
127
|
+
This downloads the package into npm's `_npx` cache, which is why a project
|
|
128
|
+
dependency is preferred for regular builds.
|
|
129
|
+
|
|
130
|
+
### Global install (not recommended)
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
npm install --global xbintsc
|
|
134
|
+
xbintsc build src/main.ts --out build
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
A global install is fine for experiments, but every project then shares whichever
|
|
138
|
+
version happens to be global. A project devDependency keeps builds reproducible.
|
|
139
|
+
|
|
140
|
+
## A complete minimal project
|
|
141
|
+
|
|
142
|
+
```text
|
|
143
|
+
my-app/
|
|
144
|
+
├── package.json
|
|
145
|
+
├── xbintsc.config.json
|
|
146
|
+
└── src/
|
|
147
|
+
└── main.ts
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
`src/main.ts`:
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
const greeting: string = "Hello from xbintsc";
|
|
154
|
+
console.log(greeting);
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
`xbintsc.config.json`:
|
|
158
|
+
|
|
159
|
+
```json
|
|
160
|
+
{
|
|
161
|
+
"entry": "src/main.ts",
|
|
162
|
+
"outDir": "build"
|
|
163
|
+
}
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Add a build script to `package.json` — npm puts `node_modules/.bin` on `PATH`,
|
|
167
|
+
so the script can call `xbintsc` directly:
|
|
168
|
+
|
|
169
|
+
```json
|
|
170
|
+
{
|
|
171
|
+
"scripts": {
|
|
172
|
+
"build:native": "xbintsc build"
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Then:
|
|
178
|
+
|
|
179
|
+
```bash
|
|
180
|
+
npm install --save-dev --save-exact xbintsc
|
|
181
|
+
npm run build:native
|
|
182
|
+
./build/main # .\build\main.exe on Windows
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Expected output (the first build also compiles the C runtime):
|
|
186
|
+
|
|
187
|
+
```text
|
|
188
|
+
xbintsc: wrote /absolute/path/my-app/build/main
|
|
189
|
+
Hello from xbintsc
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
`xbintsc build` with no positional entry reads `entry` from
|
|
193
|
+
`xbintsc.config.json`, which is why the script stays short. Without a config,
|
|
194
|
+
pass the file explicitly: `xbintsc build src/main.ts --out build`.
|
|
195
|
+
|
|
196
|
+
## The first build and the cache
|
|
197
|
+
|
|
198
|
+
The runtime objects are cached by source/header content hash. The default cache
|
|
199
|
+
is `.xbintsc/` **in the directory you run the command from** (not necessarily
|
|
200
|
+
next to the config file); set `xbintsc_CACHE_DIR` to put it elsewhere.
|
|
201
|
+
|
|
202
|
+
Because the npm package ships the runtime as C sources but not as a prebuilt
|
|
203
|
+
`core.a`, the first build compiles each runtime translation unit. Expect that
|
|
204
|
+
build to take noticeably longer than the ones after it. `--time` shows where the
|
|
205
|
+
time went:
|
|
206
|
+
|
|
207
|
+
```bash
|
|
208
|
+
npx xbintsc build src/main.ts --out build --time
|
|
209
|
+
# xbintsc: timing (frontend 4ms, codegen 7ms, clang 1089ms, runtime 37770ms, link 1966ms)
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
Later builds reuse the objects and the incremental build record:
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
npx xbintsc build src/main.ts --out build
|
|
216
|
+
# xbintsc: wrote /absolute/path/build/main (cached)
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Practical consequences:
|
|
220
|
+
|
|
221
|
+
- add `.xbintsc/` to `.gitignore`;
|
|
222
|
+
- keep `.xbintsc/` between CI runs (or point `xbintsc_CACHE_DIR` at a persistent
|
|
223
|
+
directory) to avoid paying the runtime-compile cost every time;
|
|
224
|
+
- deleting `.xbintsc/` is safe — the next build recreates it;
|
|
225
|
+
- `--force` ignores the build freshness record, but cached runtime objects are
|
|
226
|
+
still reused. Delete `.xbintsc/` if you want to force a full C rebuild.
|
|
227
|
+
|
|
228
|
+
## Commands you will use
|
|
229
|
+
|
|
230
|
+
All commands below assume a local install, so `npx` finds it.
|
|
231
|
+
|
|
232
|
+
| Job | Command |
|
|
233
|
+
| --- | --- |
|
|
234
|
+
| Build an executable | `npx xbintsc build src/main.ts --out build` |
|
|
235
|
+
| Choose the exact output path | `npx xbintsc build src/main.ts -o dist/app` |
|
|
236
|
+
| Compile and run immediately | `npx xbintsc run src/main.ts -- --flag value` |
|
|
237
|
+
| Pass arguments to the program | Put them after `--`; they are not compiler flags |
|
|
238
|
+
| Check without linking (no clang) | `npx xbintsc check src/main.ts` |
|
|
239
|
+
| Print LLVM IR (no clang) | `npx xbintsc emit src/main.ts > main.ll` |
|
|
240
|
+
| Emit an object file | `npx xbintsc build src/main.ts --emit obj --out build` |
|
|
241
|
+
| Optimize | `npx xbintsc build src/main.ts -O3 --out build` |
|
|
242
|
+
| Use Node built-ins | `npx xbintsc build src/main.ts --ext node --out build` |
|
|
243
|
+
| Rebuild on change | `npx xbintsc watch src/main.ts` |
|
|
244
|
+
| Inspect the toolchain | `npx xbintsc doctor` |
|
|
245
|
+
| Read the exact help text | `npx xbintsc help` |
|
|
246
|
+
|
|
247
|
+
`--out <dir>` is a directory: the output keeps the entry file's base name.
|
|
248
|
+
`-o <path>` is the exact output path. Optimization defaults to `-O2`.
|
|
249
|
+
|
|
250
|
+
The full flag list, project config fields and environment variables are in
|
|
251
|
+
[the CLI reference](./ai/cli.md).
|
|
252
|
+
|
|
253
|
+
## Node built-ins and npm dependencies in the compiled program
|
|
254
|
+
|
|
255
|
+
Installing `xbintsc` from npm does **not** make the compiled program run on
|
|
256
|
+
Node. The output is a standalone native binary, so two rules apply:
|
|
257
|
+
|
|
258
|
+
1. **Node built-ins are opt-in.** An import such as `node:fs` or `fs` needs the
|
|
259
|
+
`node` extension:
|
|
260
|
+
|
|
261
|
+
```bash
|
|
262
|
+
npx xbintsc build src/main.ts --ext node --out build
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
or, permanently, in `xbintsc.config.json`:
|
|
266
|
+
|
|
267
|
+
```json
|
|
268
|
+
{
|
|
269
|
+
"entry": "src/main.ts",
|
|
270
|
+
"outDir": "build",
|
|
271
|
+
"extensions": ["node"]
|
|
272
|
+
}
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
2. **Third-party npm packages are bundled at build time.** A bare import is
|
|
276
|
+
resolved from the project's `node_modules` and its source is merged into the
|
|
277
|
+
binary. There is no runtime package lookup. ESM and CommonJS packages are
|
|
278
|
+
supported; circular dependencies, dynamic `require(<expression>)` and
|
|
279
|
+
packages that rely on Node globals such as `__dirname` are not.
|
|
280
|
+
|
|
281
|
+
```bash
|
|
282
|
+
npm install ms
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
```ts
|
|
286
|
+
import ms from "ms";
|
|
287
|
+
console.log(ms(60000));
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
For the complete rules and limitations see
|
|
291
|
+
[extensions](./ai/extensions.md#third-party-npm-packages).
|
|
292
|
+
|
|
293
|
+
## Build from a Node script
|
|
294
|
+
|
|
295
|
+
The package is ESM-only and exposes a programmatic API, which is useful when
|
|
296
|
+
another Node build script needs to produce the binary:
|
|
297
|
+
|
|
298
|
+
```js
|
|
299
|
+
// scripts/build-native.mjs
|
|
300
|
+
import { build } from "xbintsc";
|
|
301
|
+
|
|
302
|
+
const result = build("src/main.ts", { outDir: "build", optimize: "2" });
|
|
303
|
+
if (result.diagnostics.some((diagnostic) => diagnostic.category === "error")) {
|
|
304
|
+
process.exitCode = 1;
|
|
305
|
+
} else {
|
|
306
|
+
console.log(`wrote ${result.outputPath}${result.cached ? " (cached)" : ""}`);
|
|
307
|
+
}
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
Run it with `node scripts/build-native.mjs` (or a `package.json` script). Notes:
|
|
311
|
+
|
|
312
|
+
- use `.mjs` or `"type": "module"`, because `require("xbintsc")` is not
|
|
313
|
+
exported and fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`;
|
|
314
|
+
- `build` returns `{ outputPath, irPath?, cached, diagnostics, … }` and reports
|
|
315
|
+
source errors through `diagnostics`; it **throws** `ToolchainError` when clang
|
|
316
|
+
itself fails;
|
|
317
|
+
- `compileString(source)` is a pure IR-generation call that needs no clang;
|
|
318
|
+
- the subpath `xbintsc/driver` exposes the driver internals (cache, toolchain,
|
|
319
|
+
config, icons, macOS bundle helpers).
|
|
320
|
+
|
|
321
|
+
The full API surface is documented in [the CLI reference](./ai/cli.md#programmatic-api).
|
|
322
|
+
|
|
323
|
+
## Use it in CI
|
|
324
|
+
|
|
325
|
+
A GitHub Actions job that publishes the Linux binary can look like this:
|
|
326
|
+
|
|
327
|
+
```yaml
|
|
328
|
+
name: native
|
|
329
|
+
on: [push]
|
|
330
|
+
jobs:
|
|
331
|
+
build:
|
|
332
|
+
runs-on: ubuntu-24.04
|
|
333
|
+
steps:
|
|
334
|
+
- uses: actions/checkout@v4
|
|
335
|
+
- uses: actions/setup-node@v4
|
|
336
|
+
with:
|
|
337
|
+
node-version: 22
|
|
338
|
+
cache: npm
|
|
339
|
+
- run: sudo apt-get update && sudo apt-get install -y clang lld
|
|
340
|
+
- run: npm ci
|
|
341
|
+
- run: npx xbintsc doctor
|
|
342
|
+
- uses: actions/cache@v4
|
|
343
|
+
with:
|
|
344
|
+
path: .xbintsc
|
|
345
|
+
key: xbintsc-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
|
|
346
|
+
- run: npx xbintsc build src/main.ts --out build
|
|
347
|
+
- uses: actions/upload-artifact@v4
|
|
348
|
+
with:
|
|
349
|
+
name: my-app-linux-x64
|
|
350
|
+
path: build/main
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
- `npm ci` installs devDependencies by default, so `xbintsc` is present. If your
|
|
354
|
+
pipeline uses `npm ci --omit=dev`, build before pruning or move `xbintsc` to
|
|
355
|
+
`dependencies`.
|
|
356
|
+
- The `.xbintsc` cache key includes the lockfile, which pins the compiler
|
|
357
|
+
version; object names inside the cache are content hashes, so an old cache
|
|
358
|
+
cannot poison a new build.
|
|
359
|
+
- xbintsc builds for the **host** platform. It is not a cross-compiler: use a CI
|
|
360
|
+
matrix (one job per OS/arch) to produce artifacts for several platforms.
|
|
361
|
+
- macOS runners already have Xcode Command Line Tools; Windows runners need
|
|
362
|
+
LLVM and the MSVC build tools, and the binary is `build\main.exe`.
|
|
363
|
+
|
|
364
|
+
## npm package or release archive?
|
|
365
|
+
|
|
366
|
+
| | npm package (`xbintsc`) | Prebuilt release archive |
|
|
367
|
+
| --- | --- | --- |
|
|
368
|
+
| Needs Node.js | Yes, 22+ | No |
|
|
369
|
+
| First build | Compiles the C runtime from source | Links the prebuilt runtime |
|
|
370
|
+
| GUI / media extensions | Not included | Included in Linux/macOS archives |
|
|
371
|
+
| Installation | `npm install` + lockfile / provenance | Download, verify `.sha256`, unpack |
|
|
372
|
+
| Programmatic API | Yes | No (CLI only) |
|
|
373
|
+
| Cross-compiles | No — host only | No — host only |
|
|
374
|
+
| Best for | Node projects and CI, familiar npm workflow | Machines without Node, fastest first build, GUI apps |
|
|
375
|
+
|
|
376
|
+
If you only need the core runtime and the `node` extension, the npm package is
|
|
377
|
+
the most convenient option. If you need the fastest possible cold build or the
|
|
378
|
+
GUI/media archives, use a release archive (or build from source for
|
|
379
|
+
development).
|
|
380
|
+
|
|
381
|
+
## Things that differ from a regular Node build
|
|
382
|
+
|
|
383
|
+
- **`tsconfig.json` is not read.** xbintsc has its own `xbintsc.config.json` for
|
|
384
|
+
the entry file, output directory and build flags. TypeScript `paths` aliases
|
|
385
|
+
and other `tsconfig.json` settings are not applied; use relative imports or
|
|
386
|
+
real package imports.
|
|
387
|
+
- **The project's `package.json` `"type"` does not change the source dialect.**
|
|
388
|
+
Write ESM `import`/`export`; `require()` in your own source is rejected.
|
|
389
|
+
- **Types are checked, then erased.** The default checker catches definite
|
|
390
|
+
mismatches, but there is no full type inference or strict-null mode. Use
|
|
391
|
+
`--no-check` only when you need to skip the semantic check.
|
|
392
|
+
- **Only a subset of TypeScript compiles.** Unsupported syntax fails with a
|
|
393
|
+
diagnostic instead of being approximated. See
|
|
394
|
+
[language support](./ai/language-support.md).
|
|
395
|
+
- **The produced binary is platform- and architecture-specific.** Build it on
|
|
396
|
+
the platform you will run it on.
|
|
397
|
+
|
|
398
|
+
## Troubleshooting
|
|
399
|
+
|
|
400
|
+
Diagnostic hints end with a repository-relative path such as
|
|
401
|
+
`doc/ai/troubleshooting.md`. In a project that installed xbintsc from npm, read
|
|
402
|
+
the same file under `node_modules/xbintsc/doc/ai/`.
|
|
403
|
+
|
|
404
|
+
| Symptom | Cause / fix |
|
|
405
|
+
| --- | --- |
|
|
406
|
+
| `npx xbintsc` uses an unexpected version | Run `npx --no-install xbintsc version` and `npm ls xbintsc`; pin the version in `package.json` and use `npm ci` in CI. |
|
|
407
|
+
| `requires Node.js 22` / engine error | Upgrade Node; the compiler uses modern Node APIs. |
|
|
408
|
+
| `No C compiler found` or `requires clang 16 or newer` | Install clang 16+ and run `npx xbintsc doctor`; set `xbintsc_CLANG` to a specific clang if needed. |
|
|
409
|
+
| The first build takes a long time | Expected: the runtime C sources are compiled and cached. Later builds reuse `.xbintsc/`; `--time` confirms. Use a release archive if cold builds must be fast. |
|
|
410
|
+
| Permission errors writing `.xbintsc/` | Set `xbintsc_CACHE_DIR` to a writable directory, or run from a writable working directory. |
|
|
411
|
+
| `module 'fs' is provided by the 'node' extension` | Add `--ext node`, or `"extensions": ["node"]` in the config. |
|
|
412
|
+
| `GUI native library not found` / `media native library not found` | The npm package does not ship `gui.a`/`media.a`; use a Linux/macOS release archive or build them from a source checkout. |
|
|
413
|
+
| `require("xbintsc")` fails | The package is ESM-only; use `import` (or dynamic `import()`). |
|
|
414
|
+
| Windows link errors about missing MSVC libraries | Run from a Native Tools prompt, install the VS C++ build tools, and check `npx xbintsc doctor`. |
|
|
415
|
+
| `npm ci --omit=dev` then the build cannot find `xbintsc` | Install devDependencies for the build stage, or move `xbintsc` to `dependencies`. |
|
|
416
|
+
|
|
417
|
+
More error messages and their fixes: [troubleshooting](./ai/troubleshooting.md).
|
package/doc/requirements.md
CHANGED
|
@@ -10,7 +10,10 @@ no requirements on any platform.
|
|
|
10
10
|
| Requirement | Minimum | Notes |
|
|
11
11
|
| --- | --- | --- |
|
|
12
12
|
| clang / LLVM | **16** | The emitted IR uses opaque pointers, which LLVM 16 made the only pointer representation. |
|
|
13
|
-
| Node.js | **22** |
|
|
13
|
+
| Node.js | **22** | Required to run the compiler from npm or from source; released binaries are standalone and need no Node. |
|
|
14
|
+
|
|
15
|
+
Installing the compiler from npm instead of using a release archive? Node.js 22+
|
|
16
|
+
then runs the compiler itself; see [Using xbintsc from npm](./npm-package.md).
|
|
14
17
|
|
|
15
18
|
clang 15 and older fail on the first string literal in any program, with:
|
|
16
19
|
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Support matrix
|
|
2
|
+
|
|
3
|
+
> Language: **English** | [简体中文](./zh-CN/support-matrix.md)
|
|
4
|
+
|
|
5
|
+
> **Generated** by `npm run docs:matrix` from the executable catalogue in
|
|
6
|
+
> [`tests/conformance/test262/manifest.ts`](../tests/conformance/test262/manifest.ts). Do not edit this
|
|
7
|
+
> file by hand: change a case and regenerate.
|
|
8
|
+
|
|
9
|
+
Every supported case is an unmodified [test262](https://github.com/tc39/test262)
|
|
10
|
+
file (pinned at `d53ebc8b1931d9f1541e43d59650776e4b766248`) that xbintsc compiles **and runs**; the
|
|
11
|
+
[test262 suite](../tests/conformance/test262.test.ts) fails if one stops passing. The corpus is a
|
|
12
|
+
representative subset, not a full test262 run. Every unsupported case
|
|
13
|
+
is valid JavaScript that xbintsc currently rejects, pinned with the diagnostic
|
|
14
|
+
code it produces. See [`SOURCE.md`](../tests/conformance/test262/SOURCE.md) for the harness adaptation.
|
|
15
|
+
Because the suite runs on every CI platform, this table cannot claim more than
|
|
16
|
+
the compiler does.
|
|
17
|
+
|
|
18
|
+
## Coverage by area
|
|
19
|
+
|
|
20
|
+
| Area | Supported | Unsupported | Reference |
|
|
21
|
+
| --- | ---: | ---: | --- |
|
|
22
|
+
| Values and operators | 2 | 1 | [reference](implemented/operators.md) |
|
|
23
|
+
| Strings (UTF-16 semantics) | 2 | 0 | [reference](implemented/strings.md) |
|
|
24
|
+
| Arrays | 2 | 0 | [reference](implemented/stdlib.md) |
|
|
25
|
+
| Objects | 2 | 0 | [reference](implemented/stdlib.md) |
|
|
26
|
+
| Classes and inheritance | 2 | 0 | [reference](implemented/codegen.md) |
|
|
27
|
+
| Closures and functions | 2 | 1 | [reference](implemented/binder.md) |
|
|
28
|
+
| Exceptions | 2 | 0 | [reference](implemented/runtime-core.md) |
|
|
29
|
+
| Async and promises | 2 | 0 | [reference](implemented/async.md) |
|
|
30
|
+
| JSON | 2 | 0 | [reference](implemented/stdlib.md) |
|
|
31
|
+
| Map and Set | 2 | 0 | [reference](implemented/collections.md) |
|
|
32
|
+
| Regular expressions | 2 | 0 | [reference](implemented/stdlib.md) |
|
|
33
|
+
| Typed arrays and binary data | 2 | 0 | [reference](implemented/typed-arrays.md) |
|
|
34
|
+
| Date | 2 | 0 | [reference](implemented/stdlib.md) |
|
|
35
|
+
| Generators | 2 | 0 | [reference](implemented/async.md) |
|
|
36
|
+
| Modules | 2 | 1 | [reference](implemented/modules.md) |
|
|
37
|
+
| Optional chaining and templates | 2 | 1 | [reference](implemented/operators.md) |
|
|
38
|
+
|
|
39
|
+
## Supported cases (test262, compiled and executed)
|
|
40
|
+
|
|
41
|
+
| test262 case | Area | What it pins down |
|
|
42
|
+
| --- | --- | --- |
|
|
43
|
+
| `built-ins/Number/isInteger/integers.js` | Values and operators | Number.isInteger accepts every integer, including ±2^53 |
|
|
44
|
+
| `built-ins/Number/isSafeInteger/infinity.js` | Values and operators | Number.isSafeInteger rejects ±Infinity |
|
|
45
|
+
| `built-ins/String/prototype/padStart/fill-string-empty.js` | Strings (UTF-16 semantics) | padStart leaves the string unchanged when the fill string is empty |
|
|
46
|
+
| `built-ins/String/prototype/includes/String.prototype.includes_Success.js` | Strings (UTF-16 semantics) | includes finds a substring at the requested position |
|
|
47
|
+
| `built-ins/Array/prototype/map/15.4.4.19-1-1.js` | Arrays | map throws a TypeError when its receiver is undefined |
|
|
48
|
+
| `built-ins/Array/prototype/at/index-non-numeric-argument-tointeger.js` | Arrays | at coerces false, null, undefined and the empty string to index 0 |
|
|
49
|
+
| `built-ins/Object/keys/15.2.3.14-0-1.js` | Objects | Object.keys is a callable function |
|
|
50
|
+
| `built-ins/Object/assign/Override.js` | Objects | Object.assign lets a later source override an earlier key |
|
|
51
|
+
| `language/statements/class/subclass/class-definition-evaluation-empty-constructor-heritage-present.js` | Classes and inheritance | a derived class without a constructor forwards its arguments to super |
|
|
52
|
+
| `language/statements/class/definition/class-method-returns-promise.js` | Classes and inheritance | an async class method returns a promise instance |
|
|
53
|
+
| `language/expressions/arrow-function/cannot-override-this-with-thisArg.js` | Closures and functions | arrow functions cannot have this overridden by thisArg |
|
|
54
|
+
| `language/expressions/function/S10.1.1_A1_T2.js` | Closures and functions | named, anonymous and parenthesised function expressions all evaluate |
|
|
55
|
+
| `language/statements/try/12.14-10.js` | Exceptions | catch introduces its own scope for name lookup |
|
|
56
|
+
| `built-ins/Error/length.js` | Exceptions | the Error constructor reports length 1 |
|
|
57
|
+
| `language/expressions/await/async-await-interleaved.js` | Async and promises | await and promise continuations interleave on the microtask queue |
|
|
58
|
+
| `built-ins/Promise/all/S25.4.4.1_A1.1_T1.js` | Async and promises | Promise.all is callable |
|
|
59
|
+
| `built-ins/JSON/stringify/property-order.js` | JSON | JSON.stringify emits keys in property order |
|
|
60
|
+
| `built-ins/JSON/parse/15.12.1.1-0-9.js` | JSON | JSON.parse accepts whitespace before and after a token |
|
|
61
|
+
| `built-ins/Map/prototype/set/append-new-values.js` | Map and Set | Map.set appends new entries in insertion order |
|
|
62
|
+
| `built-ins/Set/prototype/add/does-not-have-setdata-internal-slot-array.js` | Map and Set | Set.prototype.add rejects a non-Set receiver |
|
|
63
|
+
| `built-ins/RegExp/prototype/test/S15.10.6.3_A1_T1.js` | Regular expressions | test() applies /1|12/ to the string "123" |
|
|
64
|
+
| `built-ins/String/prototype/replace/15.5.4.11-1.js` | Regular expressions | replace passes the correct this to the replacer function |
|
|
65
|
+
| `built-ins/DataView/prototype/getUint8/index-is-out-of-range.js` | Typed arrays and binary data | getUint8 throws a RangeError past the end of the view |
|
|
66
|
+
| `built-ins/DataView/prototype/setUint32/no-value-arg.js` | Typed arrays and binary data | setUint32 stores 0 when the value argument is omitted |
|
|
67
|
+
| `built-ins/Date/prototype/getUTCFullYear/this-value-valid-date.js` | Date | getUTCFullYear reads a valid date |
|
|
68
|
+
| `built-ins/Date/parse/year-zero.js` | Date | Date.parse rejects the -000000 extended year |
|
|
69
|
+
| `language/statements/generators/declaration.js` | Generators | generator function declarations are supported |
|
|
70
|
+
| `language/expressions/generators/default-proto.js` | Generators | generator functions share the intrinsic generator prototype |
|
|
71
|
+
| `language/module-code/eval-export-cls-semi.js` | Modules | an exported class declaration needs no trailing semicolon |
|
|
72
|
+
| `language/module-code/eval-export-fun-semi.js` | Modules | an exported function declaration needs no trailing semicolon |
|
|
73
|
+
| `language/expressions/optional-chaining/call-expression.js` | Optional chaining and templates | optional chaining applies to call expressions |
|
|
74
|
+
| `language/expressions/template-literal/evaluation-order.js` | Optional chaining and templates | template substitutions evaluate from left to right |
|
|
75
|
+
|
|
76
|
+
## Unsupported cases (valid JavaScript, expected diagnostics)
|
|
77
|
+
|
|
78
|
+
| test262 case | Area | Diagnostic | Why |
|
|
79
|
+
| --- | --- | ---: | --- |
|
|
80
|
+
| `language/statements/with/12.10-0-1.js` | Optional chaining and templates | TS2001 | `with` statements are not implemented |
|
|
81
|
+
| `language/expressions/new.target/value-via-call.js` | Closures and functions | TS4005 | `new.target` has no lowering |
|
|
82
|
+
| `language/expressions/comma/S11.14_A2.1_T3.js` | Values and operators | TS3002 | an unbound name is a compile-time error, not a runtime `ReferenceError` |
|
|
83
|
+
| `language/expressions/dynamic-import/always-create-new-promise.js` | Modules | TS2001 | dynamic `import()` is not implemented |
|
|
@@ -9,6 +9,9 @@
|
|
|
9
9
|
| Instance fields / property declarations | ✓ |
|
|
10
10
|
| Methods | ✓ |
|
|
11
11
|
| `static` fields / methods | ✓ |
|
|
12
|
+
| `static { ... }` blocks | ✓ implemented (runs once at class definition; static fields and blocks run in declaration order, static methods are installed first; `this` is the class, `super.x` reads the parent constructor) |
|
|
13
|
+
| `static get` / `static set` accessors | ✓ (accessors on the constructor value; inherited static setters are honoured) |
|
|
14
|
+
| `super[key]` / `super[key](...)` | ✓ |
|
|
12
15
|
| Inheritance `extends` / `super` | ✓ (single level correct; `super` takes the prototype of `this`'s prototype — see [Runtime deviations](./deviations.md)) |
|
|
13
16
|
| Prototype chain / method lookup | ✓ |
|
|
14
17
|
| `instanceof` | ✓ |
|
|
@@ -13,11 +13,12 @@ These features **compile and run**, but the result does not fully match ECMAScri
|
|
|
13
13
|
| `for...in` | Enumerates own keys of objects / arrays / strings; does not include prototype-chain properties |
|
|
14
14
|
| Array out-of-bounds / sparse | Out-of-bounds access returns `undefined`; assigning `arr.length` truncates / extends, but sparse holes are not tracked distinctly |
|
|
15
15
|
| Memory management | Non-moving mark-sweep collector behind `xt_alloc`: explicit roots, subsystem root providers and a conservative C-stack scan. Single-threaded and stop-the-world; no moving/compaction or generational mode |
|
|
16
|
-
| Function `arity` / argument count |
|
|
16
|
+
| Function `arity` / argument count | Direct calls to a locally visible function are checked by the default [semantic checker](../implemented/checker.md) (`TS4004`); calls through properties, imports, spread arguments or a reassigned binding are not. `fn.length` reports the declared arity |
|
|
17
17
|
| `async` / `await` | Real suspension on a stackful coroutine; `await` always queues a microtask (non-promises and already-settled promises included), so interleaving with pending `.then` callbacks matches the specification. Top-level `await` blocks on the event loop rather than yielding the module body. `fs/promises` and `fetch` offload their blocking work to a four-worker pool and settle on the reactor. Async generators suspend at both `await` and `yield`; `for await...of` awaits one step per iteration |
|
|
18
18
|
| Async generator cleanup | `for await...of` does not call the iterator's `return()` when the loop exits early. `yield*` inside an async generator delegates to synchronous iterables only. `.return()` at a suspended `yield` completes without running `finally` (the same limitation as synchronous generators) |
|
|
19
|
-
| `super` | `super.x` / `super
|
|
19
|
+
| `super` | `super.x` / `super[x]` read from the parent holder of the class whose body is running (in an instance method: the parent prototype; in a `static` method or static block: the parent constructor), so any inheritance depth is correct |
|
|
20
20
|
| `Error.stack` | Function-level frames only: each frame is `at name (file:line)` with the function's declaration line (updated to the construction line for the innermost frame); no column numbers and no frames for generator / `async` bodies (they switch stacks) |
|
|
21
|
+
| `let` in a `for` loop header | One binding per loop, not one per iteration: closures created inside the body all observe the final value (`for (let i = 0; i < 3; i++) fns.push(() => i)` gives `3,3,3`) |
|
|
21
22
|
| Module live bindings | Namespace imports and imported bindings are snapshots (see [Module system](./modules.md)) |
|
|
22
23
|
| `import.meta` | ✓ `import.meta.url` / `.dirname` / `.filename`, resolved from the executable path |
|
|
23
24
|
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
| --- | --- |
|
|
7
7
|
| GC (garbage collection) | ✓ non-moving mark-sweep in `xt_alloc.c`, armed by a live-heap threshold (`XT_GC_THRESHOLD` pins it) or `xt_gc_collect()`; after each collection the threshold becomes twice the surviving heap (floor 1 MiB), so the resident set follows the live set instead of only growing. `XT_GC_TRACE=1` prints one line per collection to stderr. Explicit roots + root providers + conservative active-stack scan. `WeakMap`/`WeakSet` keys are ephemerons (a value is retained only while its key is reachable) and `WeakRef` targets are cleared when unreachable; because the stack scan is conservative, a stale stack word can delay that clearing. No compaction or background collection |
|
|
8
8
|
| Self-hosting | ✓ the compiler compiles itself: `xbintsc build src/cli/main.ts` produces a working binary, and the emitted IR is stable from generation 1 onward. The runtime is still C |
|
|
9
|
-
| Type checker |
|
|
9
|
+
| Type checker | partial: the default [semantic checker](../implemented/checker.md) reports unresolved names, redeclarations, call arity, property existence and definite assignability mismatches, with structural interfaces/classes, simple generics and basic flow narrowing; there is no full inference or strict-null pass |
|
|
10
10
|
| Full standard library | partial: Math / JSON / Date / Map / Set / RegExp / `Error` / `BigInt` / `Symbol` / `structuredClone` implemented; String.normalize missing |
|
|
11
11
|
| Multi-file module bundling | partial: relative-path `.ts` bundling, ESM `node_modules` packages, namespace imports and bare-specifier extension module imports implemented; CommonJS is handled only inside `node_modules`; circular dependencies / live bindings are not implemented |
|
|
12
12
|
| Real async runtime | ✓ `async`/`await` suspends on pending promises on the `select(2)` reactor: timers, TCP sockets, offloaded file/HTTP work and promise callbacks resume the coroutine. Still missing: real OS-level file watching, non-blocking `net.connect`, TLS for `fetch`, and user-visible worker threads (`worker_threads` uses child processes) |
|