@scriptc/compiler 0.0.0 → 0.0.2

package/dist/frontend/npm.d.ts

@@ -0,0 +1,330 @@
+export type EmbeddedFormat = "esm" | "cjs" | "json";
+export interface EmbeddedModule {
+    /** The resolved REAL path (symlinks followed) — the loader's cache key. */
+    key: string;
+    source: string;
+    format: EmbeddedFormat;
+    /** CommonJS only: the synthesized ESM facade the island's module loader
+     * evaluates when an ES module imports this file — default plus the LEXED
+     * named exports (cjsEsmFacadeSource). ESM sources compile natively and
+     * JSON keeps the loader's default-only wrapper, so both leave this
+     * unset. */
+    esm?: string;
+}
+/** The ESM facade for an embedded CommonJS module, matching Node's interop
+ * exactly (verified against Node 24): `default` IS module.exports;
+ * "module.exports" is a named alias for it (Node ships that export name);
+ * every lexed name binds the exports object's OWN property when one exists
+ * at facade evaluation (getters read once — a snapshot, like Node's
+ * loop over the lexed set) and stays undefined otherwise (a lexed-but-
+ * never-assigned name is a live binding of undefined, not an error;
+ * inherited properties do NOT leak through, hence the hasOwnProperty
+ * guard). Export names that aren't identifiers ("dash-name") use string
+ * ModuleExportNames — every name does, uniformly; the locals are e0, e1, …
+ * temps. */
+export declare function cjsEsmFacadeSource(key: string, names: readonly string[]): string;
+export interface EmbeddedEdge {
+    /** Importer's key. */
+    from: string;
+    /** The specifier as written in the importer's source. */
+    specifier: string;
+    /** Resolved target: an embedded module's key, or a "node:*" builtin. */
+    to: string;
+    /** Which call forms this resolution serves — Node picks the "exports"
+     * condition set from the EDGE KIND, not the importer's format, so one
+     * (from, specifier) can name TWO targets: a dual package's "import"
+     * condition for import/import() sites and its "require" condition for
+     * require() sites. "any" (relative files, builtins, edges whose kinds
+     * agree) answers both lookups. */
+    kind: "any" | "import" | "require";
+}
+/** What a dynamic import() specifier resolves to at build time. */
+export type DynamicImportResolution = 
+/** An embedded module's key or a shimmed builtin's "node:x" key —
+ * island.importDyn loads it through the engine's module system. */
+{
+    kind: "module";
+    key: string;
+}
+/** A Node builtin the island ships no shim for — a build diagnostic,
+ * exactly like a static import of it. */
+ | {
+    kind: "unsupported-builtin";
+    builtin: string;
+}
+/** The specifier resolves into the compiled program's own TypeScript —
+ * fenced at the site (static imports are the way in). */
+ | {
+    kind: "program-module";
+}
+/** No resolution — a build diagnostic, like static imports. */
+ | {
+    kind: "unresolved";
+    message: string;
+};
+export interface NpmGraphError {
+    /** Human-readable failure ("package 'x' requires 'node:stream', which
+     * the island does not provide"). The caller attaches the import site. */
+    message: string;
+}
+/** One Node builtin the embedded graph imports — the coverage report's
+ * honesty about what the island must (or cannot) provide. */
+export interface NpmBuiltinUse {
+    /** Canonical "node:x" key. */
+    builtin: string;
+    /** Whether the island ships a shim for it. */
+    shimmed: boolean;
+    /** Unshimmed AND only require()/import() edges reach it: the build
+     * embeds the island's lazy throw at the call instead of failing —
+     * Node's laziness for those edge kinds (Node itself would LOAD the
+     * builtin; the trap is the island's honest refusal at the only point
+     * Node would have loaded it). Always false when shimmed or when any
+     * static import reaches it (static keeps the eager build error). */
+    lazy: boolean;
+    /** The packages whose embedded code imports it (sorted). */
+    packages: string[];
+}
+/** One unresolvable specifier reached ONLY by require()/dynamic import()
+ * edges: the build embeds a runtime trap with Node's call-time error shape
+ * (MODULE_NOT_FOUND for require, ERR_MODULE_NOT_FOUND for import()) instead
+ * of failing — the coverage report lists these beside the builtins so the
+ * build output stays honest about what the binary cannot reach. */
+export interface NpmLazyTrap {
+    /** The specifier as written at the call site. */
+    specifier: string;
+    /** The call forms that reach it (sorted, require first). "import" is a
+     * STATIC import inside a lazily-reached module — Node links that whole
+     * subgraph at the require()/import() boundary that reaches it, so the
+     * failure surfaces there, at the call. */
+    via: ("require" | "import()" | "import")[];
+    /** The packages whose embedded code holds the call sites (sorted). */
+    packages: string[];
+    /** The specifier RESOLVED — to a native .node addon the island cannot
+     * dlopen. The build embeds a throwing stub (Node's ERR_DLOPEN_FAILED
+     * code) instead of the addon's raw bytes; the require/import() throws
+     * at the call. Unset for the unresolvable rows above. */
+    native?: boolean;
+}
+export interface NpmRuntimeGraph {
+    modules: EmbeddedModule[];
+    edges: EmbeddedEdge[];
+    /** (importing file dir + specifier) → the package's runtime entry key. */
+    entryOf: (fromFile: string, specifier: string) => string | null;
+    /** Every Node builtin the embedded graph imports, shimmed or not. */
+    builtins: NpmBuiltinUse[];
+    /** Unresolvable lazily-reached specifiers embedded as runtime traps. */
+    lazyTraps: NpmLazyTrap[];
+    errors: NpmGraphError[];
+}
+interface Host {
+    readFile: (path: string) => string | null;
+    isFile: (path: string) => boolean;
+    isDirectory: (path: string) => boolean;
+    /** fs.realpathSync semantics; returns the input when resolution fails. */
+    realpath: (path: string) => string;
+}
+/** Package name from a PATH into node_modules ("…/node_modules/@s/p/d/x.js"
+ * → "@s/p"), for diagnostics/chains when the entry is a file, not a bare
+ * specifier. Null when the path holds no node_modules segment. */
+export declare function packageNameOfPath(path: string): string | null;
+/** package.json "exports" resolution, per Node: subpath map with exact
+ * keys first, then '*' patterns (longest literal prefix wins, the matched
+ * text substitutes into the target), condition objects matched in OBJECT
+ * KEY order against the enabled set ("import" or "require", plus "node"
+ * and "default"), string targets, arrays taking the first resolvable
+ * entry. Returns a path relative to the package dir, or null. */
+export declare function resolveExports(exports: unknown, subpath: string, mode: "import" | "require"): string | null;
+/** A bare-specifier import edge Node's ESM resolution REFUSES, with Node's
+ * exact error message and code — or null (resolvable, or a shape this
+ * probe stays conservative about). The three refusal shapes it answers,
+ * per Node's PACKAGE_RESOLVE with the ["import","node","default"]
+ * condition set:
+ *   - nothing installed: no node_modules/<name> from the importer up to
+ *     the filesystem root (and no matching self-scope) — ERR_MODULE_NOT_FOUND
+ *     ("Cannot find package ...");
+ *   - an "exports" map that refuses the subpath (unmatched, or matched to
+ *     a null target) — ERR_PACKAGE_PATH_NOT_EXPORTED. Node's self-reference
+ *     rule participates: a nearest package scope whose "name" matches makes
+ *     that scope's "exports" the FINAL answer (no node_modules fallback);
+ *   - a matched exports target whose exact file does not exist —
+ *     ERR_MODULE_NOT_FOUND ("Cannot find module '<abs>' ..."). Exports
+ *     targets resolve to exact files in Node's ESM — no extension guessing.
+ * Everything else (no "exports": legacy main/index resolution with its
+ * leniencies; directory-shaped targets; unreadable package.json) answers
+ * null — the caller keeps its existing story. Callers exclude builtins and
+ * project-internal (#alias/self-name) resolutions BEFORE probing. */
+export interface NodeImportRefusal {
+    message: string;
+    code: "ERR_MODULE_NOT_FOUND" | "ERR_PACKAGE_PATH_NOT_EXPORTED";
+    /** file:// url of the missing resolved target, when the refusal has one
+     * (Node's ERR_MODULE_NOT_FOUND carries it for resolved-but-missing). */
+    url?: string;
+}
+export declare function probeNodeImportRefusal(fromFile: string, specifier: string, host?: Host): NodeImportRefusal | null;
+/** A bare-specifier `require()` edge Node's CJS resolution REFUSES because
+ * NOTHING INSTALLED resolves it: no node_modules/<name> from the requiring
+ * file up to the filesystem root, and no self-scope whose "name" matches.
+ * Answers Node's exact require-site Error message (MODULE_NOT_FOUND's
+ * "Cannot find module '<spec>'" with the one-entry require stack — the
+ * message property really carries both lines). Everything else — installed
+ * packages (whatever their exports say), builtins, relative and "#"
+ * specifiers — answers null: the callers' existing stories stand. Unlike
+ * the ESM startup-crash channel (SEMANTICS.md 287), this refusal is a
+ * RUNTIME throw at the require site, catchable — the optional-dependency
+ * try/require pattern depends on exactly that. */
+export declare function probeNodeRequireRefusal(fromFile: string, specifier: string, host?: Host): {
+    message: string;
+} | null;
+export declare class NpmGraphBuilder {
+    private readonly host;
+    private readonly modules;
+    private readonly edges;
+    private readonly edgeSeen;
+    private readonly entries;
+    readonly errors: NpmGraphError[];
+    private readonly pkgJsonCache;
+    /** Modules whose format the RESOLUTION decided (the "module" field names
+     * ESM sources regardless of the package's "type"). */
+    private readonly formatOverrides;
+    /** Canonical "node:x" → packages whose code imports it. */
+    private readonly builtinsSeen;
+    /** Canonical "node:x" keys some STATIC import reaches — those keep the
+     * eager build error, so their builtins never mark lazy. */
+    private readonly builtinsEager;
+    /** Unresolvable (or native-addon) lazily-reached specifiers → merged
+     * call forms/packages. */
+    private readonly lazyTrapsSeen;
+    /** Synthetic keys for embedded import()-not-found stubs. */
+    private importTrapCount;
+    /** moduleSpecifiersOf per module key — sweepEdges parses each module
+     * once; the `__require` attribution chain re-reads helper chunks
+     * through this cache. */
+    private readonly specifiersCache;
+    constructor(host?: Host);
+    /** Registers one user-level npm import and walks everything it reaches.
+     * Idempotent per (importing dir, specifier). */
+    addImport(fromFile: string, specifier: string): void;
+    /** Registers one user-level RELATIVE import whose target lives inside
+     * node_modules — the e2e driver shape (`import "../node_modules/vercel/
+     * dist/index.js"`): tsc resolves the FILE into the program, but shipped
+     * package code has exactly one execution home, the embedded engine.
+     * Resolves with Node's file rules, embeds the reached graph EAGERLY (a
+     * static import links at the root), and answers the runtime entry key.
+     * Idempotent per (importing dir, specifier). */
+    addFileImport(fromFile: string, specifier: string): string | null;
+    /** Registers one user-level dynamic `import(specifier)` and embeds what
+     * it reaches, returning the build-time classification the lowering acts
+     * on. Bare package specifiers take the same path as static imports;
+     * builtins map to their island shim keys ("fs" → "node:fs") or report
+     * the missing shim; RELATIVE specifiers — the shape static imports never
+     * see, because tsc compiles those — resolve against the importing FILE
+     * with Node's file/extension/directory rules and embed the reached JS
+     * graph. A relative target that is TypeScript is the program's own
+     * module (fenced at the site: static imports are the way in), and one
+     * with an extension no loader executes (.wasm, .node, ...) embeds a stub
+     * whose EVALUATION throws Node's exact ERR_UNKNOWN_FILE_EXTENSION
+     * TypeError — the build succeeds and the import() rejects at runtime,
+     * which is precisely what Node does. */
+    addDynamicImport(fromFile: string, specifier: string): DynamicImportResolution;
+    /** Embeds (once per distinct refusal) the ESM stub whose EVALUATION
+     * throws a probed Node refusal — the import() rejects at runtime with
+     * Node's exact message and code, the build succeeds. */
+    private refusalTrap;
+    /** The runtime entry key a previously-added import resolved to. */
+    entryOf(fromFile: string, specifier: string): string | null;
+    private entryKeyFor;
+    private resolveEntry;
+    /** The cjs-lexer.ts pass over every embedded CommonJS module: lex the
+     * export names exactly as Node's vendored lexer would, follow the
+     * re-export forms (`module.exports = require(…)`, table spreads/values,
+     * the tsc/babel star patterns) through the ALREADY-RESOLVED edges
+     * (builtin and unresolved targets are skipped; a require cycle
+     * contributes what is known when re-entered, like Node's seen-set), then
+     * synthesize each module's ESM facade. */
+    private synthesizeCjsFacades;
+    finish(): NpmRuntimeGraph;
+    /** Records one unresolvable lazily-reached specifier for the build-time
+     * inventory (the coverage report's lazy-trap rows). `via` carries only
+     * the call forms whose OWN resolution failed — with per-kind condition
+     * resolution, one form of a specifier can fail while another succeeds. */
+    private noteLazyTrap;
+    /** Embeds the throwing ESM stub for an unresolvable dynamic import()
+     * edge — Node's exact ERR_MODULE_NOT_FOUND shape at evaluation: bare
+     * specifiers say `Cannot find package 'x' imported from <file>`,
+     * relative ones resolve against the importer first and say `Cannot find
+     * module '<abs>' imported from <file>` carrying the file:// url, which
+     * is what Node's ESM resolver rejects with. Returns the stub's key (the
+     * edge target). require() never reaches these: unresolvable require
+     * edges embed NO edge and the island's require shim throws Node's
+     * MODULE_NOT_FOUND at the call, with the LIVE require stack. */
+    private importNotFoundTrap;
+    /** The throwing stub embedded for a resolved .node native addon: Node's
+     * ERR_DLOPEN_FAILED code (what a broken dlopen throws) with the island's
+     * honest message. Evaluation throws — at the require() call, at a
+     * facade-mediated import, at import() — and the CJS cache keeps no entry
+     * for a throwing module, so every retry throws again, like Node. */
+    static nativeAddonStub(key: string): string;
+    private pkgJsonOf;
+    /** The nearest package.json "type" above `file` — the .js format rule.
+     * Resolution-time overrides (the "module" field) win. */
+    private formatOf;
+    /** Node-style file resolution: exact file, extension candidates
+     * (commander requires './suggestSimilar'; ".node" is in Node's require
+     * probe list — the resolved addon embeds as a throwing dlopen stub),
+     * then directory resolution (the directory's package.json "main", else
+     * its index files). */
+    private resolveFile;
+    /** "a → b → c" — the package chain from the user's import to the point
+     * of failure, for diagnostics. */
+    private static chainOf;
+    /** Locates node_modules/<name> by walking up from `fromDir` to the
+     * filesystem ROOT (dependencies hoist arbitrarily far in workspace
+     * layouts), following symlinks with realpath (pnpm/bun virtual stores),
+     * then resolves the runtime entry: package.json "exports" with the
+     * given condition (strict — an exports map that doesn't match is an
+     * error, like Node's ERR_PACKAGE_PATH_NOT_EXPORTED), else the "module"/
+     * "main" fallbacks. Returns the realpath'd entry key. */
+    private resolvePackage;
+    /** Modules reached ONLY through lazy edges so far. Node has not linked
+     * these at the root: the whole subgraph behind a require()/import()
+     * boundary links AT THE CALL, so every blocked edge inside it — static
+     * imports included — fails there at runtime, never at build time. A
+     * later STATIC path promotes the module to eager: its edges re-sweep so
+     * blocked static ones become build errors, exactly the graph Node would
+     * refuse at link. */
+    private readonly lazilyReached;
+    /** Embeds `key` and everything it reaches. `chain` is the package path
+     * from the user's import to this module's package — diagnostics name it
+     * so a failure five dependencies deep is attributable. `lazy` is the
+     * REACHABILITY mode: true when every path from the user's import to this
+     * module crosses a require()/dynamic-import() edge. */
+    private walk;
+    /** moduleSpecifiersOf through the per-module cache (each module parses
+     * once even across promotion re-sweeps, and the `__require` attribution
+     * chain re-reads helper chunks it never sweeps itself). */
+    private specifiersOf;
+    /** The module whose scope DEFINES the `__require` helper that `key`'s
+     * call sites invoke, or null when it is key's own (or unresolvable).
+     * esbuild splits the helper into a shared chunk that every other chunk
+     * imports; the helper closed over THAT chunk's banner require
+     * (createRequire(import.meta.url)), so Node resolves its calls from the
+     * DEFINING chunk — and the island's require shim looks the edge up
+     * under that key at the call. Follows import → re-export hops through
+     * intermediate chunks, bounded. */
+    private requireHelperOriginOf;
+    /** One module's edge sweep. Per-edge semantics match Node's: an edge is
+     * EAGER only when the module itself is eagerly reached AND the site is a
+     * static import/export declaration — Node's link-time surface, where a
+     * blocked edge fails the BUILD. Everything else is LAZY — Node fails
+     * require at the CALL and import() at evaluation, and a subgraph behind
+     * either boundary (its static edges included) links at that call — so a
+     * blocked lazy edge embeds a runtime trap and the build succeeds: a
+     * program that never executes the call runs fine under Node too. */
+    private sweepEdges;
+}
+/** One-call convenience over NpmGraphBuilder. */
+export declare function buildNpmRuntimeGraph(imports: readonly {
+    fromFile: string;
+    specifier: string;
+}[]): NpmRuntimeGraph;
+export {};