@loopdive/js2 0.57.0

package/dist/codegen/helpers/is-strict-function.d.ts

@@ -0,0 +1,52 @@
+import { ts } from '../../ts-api.js';
+/**
+ * Decide whether `fn`'s body is strict-mode code (ECMA-262 §11.2.2).
+ *
+ * Strict applies when any of these hold:
+ *  - the function body itself opens with a `"use strict"` directive,
+ *  - an enclosing function body or the SourceFile opens with `"use strict"`,
+ *  - the function is a class element or lives anywhere inside a class
+ *    (ClassDeclaration / ClassExpression bodies are always strict).
+ *
+ * ES-module strictness (§11.2.2: Module code is always strict) IS inferred when
+ * `inferModuleStrict` is true (the default) — from the **genuine** module signal
+ * `externalModuleIndicator` (set by TypeScript when the source has a top-level
+ * `import`/`export`), or an ESM `impliedNodeFormat`. Real module input (TS/ES
+ * modules — the product's actual input) thus gets an unmapped `arguments`
+ * object (#2119).
+ *
+ * CAVEAT — the synthetic test wrapper. The test262 harness's `wrapTest` injects
+ * a top-level `export function test()` entry point, which makes TypeScript flag
+ * *every* wrapped source as a module (`externalModuleIndicator` is set even for
+ * a sloppy `noStrict` script). Inferring module-strictness from that synthetic
+ * export would wrongly unmap `arguments` for the 14 `language/arguments-object/
+ * mapped/*` (and async/yield `noStrict`) tests that assert *mapped* behaviour.
+ * So the harness passes `inferModuleStrict=false` for non-module-goal (script)
+ * tests, and leaves it true for genuine module tests. With the flag false this
+ * function ignores the module signal and the source's true sloppy strictness is
+ * honoured. `"use strict"` prologues and class context still force strict.
+ *
+ * This drives the mapped-vs-unmapped `arguments` split: strict functions get
+ * an *unmapped* arguments object, so writes to `arguments[i]` must not flow
+ * back into the named parameter (#779e).
+ */
+export declare function isStrictFunction(fn: ts.FunctionLikeDeclaration, inferModuleStrict?: boolean): boolean;
+/**
+ * (#2743) IsSimpleParameterList (ECMA-262 §15.1.3). A FormalParameters list is
+ * "simple" iff every element is a plain `BindingIdentifier` with no default
+ * initializer — i.e. it contains NO rest element, NO defaulted parameter, and
+ * NO destructuring (binding-pattern) parameter.
+ *
+ * This drives the mapped-vs-unmapped `arguments` split in
+ * FunctionDeclarationInstantiation (§10.2.11 step 22.a): the arguments object is
+ * *unmapped* when the function is strict OR its parameter list is non-simple.
+ * A non-simple list must therefore NOT install `mappedArgsInfo`, so a write to
+ * `arguments[i]` does not flow back into the named parameter (and the mapped
+ * write-back's `local.set` — which the rest/default param local shapes can't
+ * satisfy — is never emitted).
+ *
+ * A TypeScript `this` parameter (`function f(this: T, ...)`) is a plain
+ * identifier with no initializer/rest, so it does not make the list non-simple;
+ * it is erased before lowering and the call sites skip it via `paramOffset`.
+ */
+export declare function isSimpleParameterList(params: readonly ts.ParameterDeclaration[]): boolean;

package/dist/codegen/host-import-allowlist.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Allowlist of host imports tolerated under `--no-host-imports` / strict WASI
+ * mode (#1524).
+ *
+ * Strict mode is the gate that enforces the **dual-mode** architectural
+ * principle documented in `CLAUDE.md`: every user-facing feature should have
+ * a Wasm-native path that does NOT depend on a JS runtime. JS-host imports
+ * are an opt-in fast path when a host is available, not the default.
+ *
+ * Each entry on the allowlist is a host import that codegen still emits
+ * during the dual-mode migration. The entry MUST name the tracking issue
+ * that owns the Wasm-native replacement — once that work lands, the entry is
+ * removed and strict-mode builds reject the import entirely.
+ *
+ * The CI gate forbids adding entries to this list without explicit sign-off:
+ * a marker in the PR description (`[allowlist-grow]`) or a CODEOWNERS review
+ * on this file is required. The accompanying budget test
+ * (`tests/host-import-allowlist-budget.test.ts`) fails if the list grows
+ * beyond `HOST_IMPORT_ALLOWLIST_BASELINE_SIZE`.
+ *
+ * Modules besides `env`:
+ * - `wasi_snapshot_preview1` — always allowed; this is the canonical
+ *   WASI ABI, not a JS-host import.
+ * - `wasm:js-string` — host string builtins from the proposed `wasm:js-string`
+ *   import-namespace standard. Permitted only when the runtime is known to
+ *   provide them (i.e. NOT in WASI / nativeStrings mode — strict mode flips
+ *   nativeStrings ON automatically, so these should never be requested).
+ * - `string_constants` — `wasm:js-string` constant pool; same constraint.
+ *
+ * Anything in the `env` module is, by definition, a JS-host import. The
+ * allowlist below enumerates which ones we still tolerate during the
+ * transition. Use `kind === "prefix"` for parameterised import names (e.g.
+ * `Math_sin`, `console_log_number`, extern-class methods).
+ */
+/** Modules other than `env` whose imports are not JS-host bindings and are always allowed. */
+export declare const ALWAYS_ALLOWED_IMPORT_MODULES: ReadonlySet<string>;
+export interface HostImportAllowlistEntry {
+    /** Match kind. `exact` matches the import name literally; `prefix` matches a name beginning with the pattern. */
+    kind: "exact" | "prefix";
+    /** Import name (exact) or prefix (when kind === "prefix"). */
+    name: string;
+    /** Wasm signature description for documentation (e.g. "(externref) -> i32"). Optional. */
+    signature?: string;
+    /** Tracking issue that owns the Wasm-native replacement. 0 = no specific issue yet. */
+    trackingIssue: number;
+    /** One-line rationale for keeping this host import during the transition. */
+    reason: string;
+}
+/**
+ * Baseline host-import allowlist for `env` module imports under strict mode.
+ *
+ * Grouped by the tracking issue that will retire them. Order is informational
+ * — `HOST_IMPORT_ALLOWLIST_BASELINE_SIZE` below is the budget the CI gate
+ * compares against.
+ */
+export declare const HOST_IMPORT_ALLOWLIST: readonly HostImportAllowlistEntry[];
+/**
+ * Baseline size — the number of entries above. The CI budget gate fails if
+ * `HOST_IMPORT_ALLOWLIST.length` grows beyond this without explicit sign-off
+ * (PR description marker `[allowlist-grow]` or CODEOWNERS review on this file).
+ *
+ * Update this number ONLY in commits that intentionally widen the allowlist;
+ * removal of entries is encouraged and does NOT require updating this number
+ * (the budget gate is a one-way ratchet on growth).
+ */
+export declare const HOST_IMPORT_ALLOWLIST_BASELINE_SIZE: number;
+/**
+ * Returns the matching allowlist entry for `name` in the `env` module, or
+ * `undefined` if no entry matches. Used by `addImport` (#1524) to decide
+ * whether a host import is tolerated under strict mode.
+ */
+export declare function lookupAllowlistEntry(name: string): HostImportAllowlistEntry | undefined;
+/**
+ * Decide whether an import to `module.name` is allowed under strict
+ * `--no-host-imports` mode.
+ *
+ * Non-`env` modules are subject to the always-allowed list; only
+ * `wasi_snapshot_preview1` is currently on it. (`wasm:js-string` and
+ * `string_constants` are JS-host imports too, but they are gated by
+ * `nativeStrings` mode which strict mode auto-enables; they should not
+ * appear when strict mode is on.)
+ */
+export declare function isHostImportAllowed(module: string, name: string): {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: "non-env-host-module";
+} | {
+    allowed: false;
+    reason: "env-not-on-allowlist";
+};
+/**
+ * Build the user-facing error message thrown when strict mode rejects a host
+ * import. Includes the tracking issue when one is known.
+ */
+export declare function buildStrictHostImportError(module: string, name: string): string;
+/**
+ * (#2094) A single leaked host import found by the emit-time scan: a
+ * `module.name` pair that survived into the finished binary's import section
+ * but is not on the dual-mode allowlist.
+ */
+export interface LeakedHostImport {
+    module: string;
+    name: string;
+    reason: "non-env-host-module" | "env-not-on-allowlist";
+}
+/**
+ * (#2094) Emit-time import-section scan: the backstop for the `addImport`
+ * gate.
+ *
+ * The per-call `addImport` gate (`src/codegen/registry/imports.ts`) is
+ * bypassable — it only fires under `strictNoHostImports`, and even then can be
+ * defeated by call sites that push onto `ctx.mod.imports` directly or that
+ * record a stale `funcMap` index. The result was host imports leaking past the
+ * gate into standalone binaries and surfacing as *instantiation* failures
+ * (#2073/#2075) rather than structured compile errors.
+ *
+ * This scan inspects the FINISHED module's import list (after dead-import
+ * elimination, so only live imports remain) and returns every `env` import not
+ * on the dual-mode allowlist plus any non-`env`/non-WASI host-namespace import.
+ * The caller (`generateModule` finalize) turns each leak into a structured
+ * compile error via {@link buildLeakedHostImportError}, so `result.success` is
+ * `false` and the bad binary is never handed to a consumer.
+ *
+ * `imports` is the module's import descriptor list (`mod.imports`); only the
+ * `module` / `name` fields are read, so the caller may pass any shape carrying
+ * those two strings. Duplicate `module.name` pairs are de-duplicated.
+ */
+export declare function scanForLeakedHostImports(imports: ReadonlyArray<{
+    module: string;
+    name: string;
+}>): LeakedHostImport[];
+/**
+ * (#2094) Build the structured compile error for a host import that leaked
+ * into a finished standalone/strict binary. Distinct from
+ * {@link buildStrictHostImportError} (which fires at `addImport` time): this
+ * message names the emit-time scan as the source so the diagnostic points at
+ * the post-link invariant, not the registration gate.
+ */
+export declare function buildLeakedHostImportError(leak: LeakedHostImport): string;