@loopdive/js2 0.57.0

package/dist/checker/index.d.ts

@@ -0,0 +1,117 @@
+import { ts } from '../ts-api.js';
+export declare function preloadLibFiles(files: Record<string, string>): void;
+export interface TypedAST {
+    sourceFile: ts.SourceFile;
+    checker: ts.TypeChecker;
+    program: ts.Program;
+    diagnostics: ts.Diagnostic[];
+    syntacticDiagnostics: readonly ts.Diagnostic[];
+}
+/** Check if a file name is a known lib file */
+export declare function isKnownLibName(name: string): boolean;
+export declare function getLibSourceFile(name: string, languageVersion: ts.ScriptTarget | ts.CreateSourceFileOptions): ts.SourceFile | undefined;
+export interface AnalyzeOptions {
+    /** Allow JavaScript source files (enables allowJs + checkJs in TS compiler) */
+    allowJs?: boolean;
+    /** Skip semantic diagnostics collection (faster — checker still available for type queries) */
+    skipSemanticDiagnostics?: boolean;
+    /**
+     * Node API emulation (#2603), opt-in via `--emulate node`. Serves a synthetic
+     * ambient `process` declaration so the checker resolves the Node globals
+     * js2wasm lowers (process.std{in,out,err}, argv, env, exit) without the user
+     * installing @types/node — eliminating the repeated TS2580 "Cannot find name
+     * 'process'" warnings. Type-level only; does not change emitted wasm (codegen
+     * lowers `process.*` syntactically regardless). Falls back to no injection if
+     * the user already declares `process`, so it never creates a dup-identifier error.
+     */
+    emulateNode?: boolean;
+    /**
+     * Host environment scoping the AMBIENT global surface (#2528/#2645), unified
+     * under `--target {web,node,deno}` (#2736; `--platform` is a deprecated
+     * alias). Orthogonal to the backend `target` (`gc`/`wasi`/…): this selects
+     * which globals are in scope at type-check time.
+     *
+     *   - `"web"`         → the DOM ambient surface (`window`, `document`, DOM
+     *                       types). Byte-identical to the historical default.
+     *   - `"node"`/`"deno"` → the DOM-free ambient surface (DOM-only globals are
+     *                       NOT in scope, so `window.stop` is a clear type error)
+     *                       AND implies the Node-emulation injection path
+     *                       (`emulateNode`), so `process` & friends type-check
+     *                       without @types/node. (Real `@types/node`/Deno-lib
+     *                       loading is a later #2698 slice; `deno` currently routes
+     *                       through the same node-emulation/no-DOM surface.)
+     *
+     * `undefined` (unset) preserves today's behaviour exactly: the DOM composite
+     * is loaded and `emulateNode` is driven solely by its own option. This keeps
+     * the common (web/test262) path byte-neutral. See `buildNodeEnvDtsForSource`
+     * + the `emulateNode ||= platform ∈ {node,deno}` composition in #2645/#2736.
+     */
+    platform?: "web" | "node" | "deno";
+    /**
+     * Force TypeScript GRAMMAR for the parse even when the input file is named
+     * `.js`/`.mjs`/`.cjs` (#2752). When the compiler prepends an injected source
+     * prelude that is written in TypeScript — currently the `process.stdin`
+     * Readable prelude (`src/process-stdin-prelude.ts`), which carries the
+     * nullable/union types codegen relies on (`read(size?): string | null`) — the
+     * combined unit must be parsed under the TS grammar, or the loose-JS grammar
+     * checker hard-rejects the prelude's TS syntax with TS8009/8010/8017 ("X can
+     * only be used in TypeScript files") and compilation fails before codegen.
+     * This flag flips ONLY the `ScriptKind` (TS vs JS) for the parse; the
+     * `isJs`-derived semantics (`strict: false`, `allowJs`+`checkJs`) stay
+     * derived from the filename, so the user's `.js` code keeps its lenient
+     * checking while the prelude's TS syntax is accepted and its types stay
+     * load-bearing. Scoped to the prelude-injection path only — byte-neutral for
+     * every program that does not trigger a TS prelude injection.
+     */
+    forceTsGrammar?: boolean;
+}
+/**
+ * #2624 — compose `scanNodeEmuUsage` + `buildNodeEnvDts` for a source. Exported
+ * so tests can assert the EXACT import-scoped surface that emulation injects
+ * (e.g. that a `node:fs`-only program does not declare the `process` global).
+ * Returns `undefined` when the program touches no Node surface.
+ */
+export declare function buildNodeEnvDtsForSource(source: string, scriptKind?: ts.ScriptKind): string | undefined;
+/**
+ * #2684 — build the import-scoped ambient `Deno` `.d.ts` for `source`, or
+ * `undefined` when the program does not reference `Deno`. The reference is
+ * approximated by a word-boundary regex, exactly like the bare-`process`
+ * detection in `scanNodeEmuUsage`; a user that declares its own `Deno` triggers
+ * the dup-identifier rebuild-without-injection fallback.
+ */
+export declare function buildDenoEnvDtsForSource(source: string): string | undefined;
+/**
+ * Parse and type-check a TS or JS source file.
+ * In-memory CompilerHost – no filesystem needed.
+ */
+export declare function analyzeSource(source: string, fileName?: string, analyzeOptions?: AnalyzeOptions): TypedAST;
+/** Result of multi-file analysis */
+export interface MultiTypedAST {
+    /** All user source files (in dependency order, entry file last) */
+    sourceFiles: ts.SourceFile[];
+    /** The entry source file */
+    entryFile: ts.SourceFile;
+    checker: ts.TypeChecker;
+    program: ts.Program;
+    diagnostics: ts.Diagnostic[];
+    syntacticDiagnostics: readonly ts.Diagnostic[];
+}
+/**
+ * Parse and type-check multiple TS source files.
+ * In-memory CompilerHost — no filesystem needed.
+ * The TypeScript compiler handles cross-file imports natively.
+ */
+export declare function analyzeMultiSource(files: Record<string, string>, entryFile: string, 
+/** Optional mapping from bare specifiers to file keys (e.g. { "lodash": "lodash/index.ts" }) */
+specifierMap?: Record<string, string>, 
+/** Compiler options (allowJs, skipSemanticDiagnostics, ...) */
+analyzeOptions?: AnalyzeOptions): MultiTypedAST;
+/**
+ * Analyze a TypeScript project from an entry file on disk.
+ * Uses ts.createProgram with real filesystem access -- TypeScript resolves
+ * all imports automatically via its standard module resolution.
+ *
+ * Returns a MultiTypedAST suitable for generateMultiModule().
+ */
+export declare function analyzeFiles(entryPath: string, analyzeOptions?: AnalyzeOptions): MultiTypedAST;
+export { IncrementalLanguageService } from './language-service.js';

package/dist/checker/language-service.d.ts

@@ -0,0 +1,39 @@
+import { AnalyzeOptions, TypedAST } from './index.js';
+/**
+ * Incremental compiler that reuses parsed lib SourceFiles across compilations.
+ *
+ * Uses the module-level LIB_SOURCE_FILES cache from checker/index.ts to return
+ * the SAME SourceFile objects for lib files. Each compilation creates a fresh
+ * Program and checker — no type state leaks between compilations. (#973)
+ *
+ * Performance: lib SourceFile caching avoids re-parsing ~10MB of .d.ts files
+ * per compilation, which is the dominant cost. We intentionally do NOT pass
+ * oldProgram to ts.createProgram — TypeScript's structure reuse carries forward
+ * internal symbol tables and type caches that leak stale type info between
+ * unrelated test compilations, causing ~400 false compile errors in the fork
+ * worker pool.
+ */
+export declare class IncrementalLanguageService {
+    private currentSource;
+    private currentSourceFile;
+    private fileName;
+    private compilerOptions;
+    private host;
+    private defaultLibName;
+    constructor(fileName?: string);
+    /**
+     * Update the source for the next compilation.
+     *
+     * #2752 — `forceTsGrammar` forces `ScriptKind.TS` for the parsed SourceFile
+     * even when `fileName` ends in `.js` (otherwise `ts.createSourceFile` infers
+     * `ScriptKind.JS` from the extension and the loose-JS grammar checker rejects
+     * an injected TS prelude with TS8009/8010/8017). Mirrors the
+     * `forceTsGrammar` override in the non-incremental `analyzeSource`.
+     */
+    updateSource(source: string, fileName?: string, forceTsGrammar?: boolean): void;
+    /**
+     * Analyze — fresh Program + fresh checker, cached lib SourceFiles.
+     */
+    analyze(analyzeOptions?: AnalyzeOptions): TypedAST;
+    dispose(): void;
+}

package/dist/checker/node-capability-map.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A provider that can satisfy a member at link time. Informational today
+ * (drives the deliberate-error message + future link wiring); the active set is
+ * target-dependent (`providersFor`).
+ */
+export type NodeProvider = "wasi-fd" | "wasi-fs" | "js-host-fs" | "edge-adapter";
+/** The compilation target surface a capability decision depends on. */
+export interface CapabilityTarget {
+    /** `--target wasi` (standalone WASI: fd IO yes, filesystem no). */
+    wasi: boolean;
+    /** `--allow-fs` — JS-host filesystem access is permitted. */
+    allowFs: boolean;
+}
+export interface NodeMemberCapability {
+    /** The exported member name (e.g. `readSync`). */
+    name: string;
+    /**
+     * Faithful `.d.ts` declaration body for this member — one or more bodiless
+     * `export function` overloads, mirroring `@types/node`. Injected verbatim into
+     * the synthetic `node:<mod>` declaration module. Types reference only globals
+     * available in the checker's loaded lib surface plus the `__NodeFs*` aliases
+     * emitted by the module's `supportDecls`.
+     */
+    decls: string;
+    /**
+     * Providers that can satisfy this member, as a function of the active target.
+     * A member is *satisfiable* under a target iff `providersFor(target)` is
+     * non-empty. Empty ⇒ deliberate "no provider" compile error.
+     */
+    providersFor: (target: CapabilityTarget) => NodeProvider[];
+}
+export interface NodeModuleCapability {
+    /** The bare module specifier, e.g. `node:fs`. */
+    module: string;
+    /**
+     * Shared declaration preamble (interfaces / type aliases) emitted ONCE before
+     * the member decls when at least one member of this module is imported.
+     */
+    supportDecls: string;
+    /** Capability entry per exported member. */
+    members: Map<string, NodeMemberCapability>;
+}
+export declare const FS_PATH_BASED_MEMBERS: readonly ["readFileSync", "readFile", "writeFile", "appendFileSync", "appendFile", "openSync", "open", "unlinkSync", "unlink", "mkdirSync", "mkdir", "readdirSync", "readdir", "statSync", "stat", "existsSync"];
+/** Look up the capability entry for a `node:<mod>` specifier, if mapped. */
+export declare function getModuleCapability(module: string): NodeModuleCapability | undefined;
+/** Is `member` a known (mapped) member of `module`? */
+export declare function isKnownMember(module: string, member: string): boolean;
+/**
+ * Is `member` of `module` satisfiable under `target`? `false` for a member that
+ * is typed in `@types/node` but has no provider under the active target (the
+ * deliberate-error case). Returns `undefined` for an unknown member (caller
+ * decides — usually permissive).
+ */
+export declare function isMemberSatisfiable(module: string, member: string, target: CapabilityTarget): boolean | undefined;
+/**
+ * Build the `.d.ts` body lines for a `node:<mod>` module, scoped to the
+ * `imported` member names. Emits the module's support decls once, then a
+ * faithful (overloaded) declaration per imported member that the map knows,
+ * falling back to permissive `any` for members outside the map. Returns
+ * `undefined` if the module is not in the capability map (caller falls back to
+ * the permissive generic module shape).
+ */
+export declare function buildModuleDecls(module: string, imported: Iterable<string>): string[] | undefined;

package/dist/checker/type-mapper.d.ts

@@ -0,0 +1,84 @@
+import { ts } from '../ts-api.js';
+import { ValType } from '../ir/types.js';
+export declare function mapTsTypeToWasm(type: ts.Type, checker: ts.TypeChecker, fast?: boolean): ValType;
+/** Check if a type is an externally declared class (declare class / declare var with constructor) */
+export declare function isExternalDeclaredClass(type: ts.Type, checker?: ts.TypeChecker): boolean;
+/** Check if a ts.Type represents void */
+export declare function isVoidType(type: ts.Type): boolean;
+/**
+ * Resolve the Wasm type of a destructuring binding element's local (#821).
+ *
+ * For `{ s: t = counter() }` where `counter()` returns `void`, TS infers `t`'s
+ * type as `void` (or `void | undefined`) — its only evidence is the default
+ * initializer. `resolveWasmType` then maps that to `i32`, so the *actual*
+ * property value (`null`/`0`/`false`/`''`, an externref) gets coerced into an
+ * i32 local and is destroyed — the spec requires the present, non-`undefined`
+ * value to be preserved and the default skipped (§13.3.3.6/§13.3.3.7).
+ *
+ * When an element has a default initializer AND the resolved type is the
+ * void/undefined sentinel, the local must be `externref` so it can faithfully
+ * hold whatever real value flows in. `resolve` is the caller's
+ * `resolveWasmType(ctx, tsType)` (passed in to avoid a circular import).
+ */
+export declare function resolveBindingElementType(element: ts.BindingElement, tsType: ts.Type, resolve: (t: ts.Type) => ValType): ValType;
+/** Check if a ts.Type represents bigint */
+export declare function isBigIntType(type: ts.Type): boolean;
+/** Check if a ts.Type represents number */
+export declare function isNumberType(type: ts.Type): boolean;
+export type NullablePrimitiveKind = "number" | "boolean" | "string" | "bigint";
+export interface NullablePrimitiveInfo {
+    primitiveKind: NullablePrimitiveKind;
+    hasNull: boolean;
+    hasUndefined: boolean;
+}
+/** Check if a type is a nullable primitive sentinel, e.g. number | null or boolean | undefined. */
+export declare function getNullablePrimitiveInfo(type: ts.Type): NullablePrimitiveInfo | null;
+export declare function isNullablePrimitiveType(type: ts.Type): boolean;
+/** Check if a type is a nullable numeric sentinel, e.g. number | null or number | undefined. */
+export declare function isNullableNumberType(type: ts.Type): boolean;
+/** Check if a ts.Type represents boolean */
+export declare function isBooleanType(type: ts.Type): boolean;
+/** Check if a ts.Type represents string (including String wrapper object) */
+export declare function isStringType(type: ts.Type): boolean;
+/** Check if a ts.Type represents the Number wrapper object (e.g. `new Number(1)`) */
+export declare function isNumberWrapperType(type: ts.Type): boolean;
+/** Check if a ts.Type represents the String wrapper object (e.g. `new String("x")`) */
+export declare function isStringWrapperType(type: ts.Type): boolean;
+/** Check if a ts.Type represents the Boolean wrapper object (e.g. `new Boolean(false)`) */
+export declare function isBooleanWrapperType(type: ts.Type): boolean;
+/**
+ * Check if a ts.Type is any of Number/String/Boolean wrapper object types (#1111).
+ * These are JS objects (typeof x === "object") even though they wrap primitives.
+ * Used to route equality through JS host == / === with no numeric fallback,
+ * since wrappers have object identity semantics, not value semantics.
+ */
+export declare function isWrapperObjectType(type: ts.Type): boolean;
+/**
+ * Check if a ts.Type is a Symbol type.
+ */
+export declare function isSymbolType(type: ts.Type): boolean;
+/**
+ * Check if a ts.Type is Promise<T>.
+ * Returns true for the built-in Promise generic type.
+ */
+export declare function isPromiseType(type: ts.Type): boolean;
+/**
+ * Check if a ts.Type is Generator<T>, Iterator<T>, or IterableIterator<T>.
+ * Returns true for any of the built-in generator/iterator types.
+ */
+export declare function isGeneratorType(type: ts.Type): boolean;
+/**
+ * Check if a ts.Type is IteratorResult<T> (the return type of .next()).
+ */
+export declare function isIteratorResultType(type: ts.Type): boolean;
+/**
+ * Unwrap Promise<T> to T. If the type is not a Promise, returns the type unchanged.
+ * Used to extract the inner type of async function return types.
+ */
+export declare function unwrapPromiseType(type: ts.Type, checker: ts.TypeChecker): ts.Type;
+/**
+ * Check if a ts.Type is a heterogeneous union (e.g. number | string)
+ * that requires externref boxing. Returns false for T | null/undefined unions
+ * where the non-nullish types all map to the same Wasm kind.
+ */
+export declare function isHeterogeneousUnion(type: ts.Type, checker: ts.TypeChecker, fast?: boolean): boolean;

package/dist/cjs-rewrite.d.ts

@@ -0,0 +1,19 @@
+import { PositionMap } from './position-map.js';
+/**
+ * Rewrite top-level `const X = require('Y')` and `const { ... } = require('Y')` patterns
+ * to ESM `import` declarations.
+ *
+ * Returns the original source unchanged if no top-level require() calls are present.
+ */
+export declare function rewriteCjsRequire(source: string): string;
+/**
+ * #1928 — like {@link rewriteCjsRequire} but also returns a `PositionMap` from
+ * the rewritten output back to the input, so diagnostics computed against the
+ * rewritten source can report the user's original line numbers. `import`
+ * declarations can be longer (and multi-line) than the `const … = require(…)`
+ * they replace, shifting everything below.
+ */
+export declare function rewriteCjsRequireWithMap(source: string): {
+    source: string;
+    positionMap: PositionMap;
+};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};