@scriptc/compiler 0.2.9 → 0.3.0

package/dist/frontend/npm.d.ts

@@ -1,123 +1,3 @@
-import type { FrontendServices } from "./services.js";
-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;
-    /** The parsed source reaches Node's global fetch binding. This is a
-     * semantic capability fact, unlike the old whole-source word scan: comments,
-     * strings, property names, and locally-bound `fetch` identifiers do not set
-     * it. The IR/link gates consume this bit without reparsing embedded text. */
-    usesFetch?: true;
-    /** 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;
-}
-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.
- * Static builds expose its nominal live namespace; dynamic builds
- * marshal a snapshot namespace into the island. */
- | {
-    kind: "program-module";
-}
-/** A supported Node builtin imported by a static build. Its namespace
- * token routes member reads through the existing builtin tables. */
- | {
-    kind: "static-builtin";
-    module: string;
-}
-/** 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[];
-}
-export type { SpecifierUse, ModuleSpecifiers } from "./module-syntax.js";
 export interface NpmGraphHost {
     readFile: (path: string) => string | null;
     isFile: (path: string) => boolean;
@@ -126,29 +6,7 @@ export interface NpmGraphHost {
     realpath: (path: string) => string;
 }
 export declare const realNpmGraphHost: NpmGraphHost;
-/** 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;
-/** 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";
@@ -157,193 +15,19 @@ export interface NodeImportRefusal {
     url?: string;
 }
 export declare function probeNodeImportRefusal(fromFile: string, specifier: string, host?: NpmGraphHost): 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?: NpmGraphHost): {
     message: string;
 } | null;
-export declare class NpmGraphBuilder {
-    private readonly services;
+export declare class NodePackageResolver {
     private readonly host;
-    private readonly modules;
-    private readonly edges;
-    private readonly edgeSeen;
-    private readonly entries;
-    readonly errors: NpmGraphError[];
+    private readonly errors;
     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;
-    /** Helper attribution can read a module before walk reaches it. Share
-     * preparation so its edges and embedded source always use the same JS. */
-    private readonly sourceCache;
-    constructor(services: FrontendServices, host?: NpmGraphHost);
-    /** Resolve one runtime module without embedding it. This is the package
-     * half of import.meta.resolve/require.resolve: the answer is executable
-     * source under Node's import/require conditions, never the declaration-file
-     * answer from resolve.ts. Diagnostics produced by the graph-oriented
-     * resolver are discarded here; the introspection lowering supplies Node's
-     * public error shape separately. */
+    constructor(host?: NpmGraphHost);
     resolveForIntrospection(fromFile: string, specifier: string, mode: "import" | "require"): string | null;
-    /** 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 (compiled natively and exposed through the import lowering), 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;
-    /** Registers one user-level createRequire(...) require and walks what
-     * it reaches, answering the runtime entry key — resolveEntry's twin
-     * under Node's "require" condition (a dual package embeds its CJS arm,
-     * exactly what Node's createRequire loads). The cache key carries the
-     * mode so a file both importing and requiring one specifier keeps two
-     * entries, like the graph's own kind-split edges. */
-    addRequire(fromFile: string, specifier: string): string | null;
-    /** The embedded format of a resolved module key ("cjs"/"esm"/"json") —
-     * the require lowering picks its export name by it (a CJS facade's
-     * default IS module.exports; an ESM entry answers its namespace, the
-     * require(esm) shape). */
-    moduleFormatOf(key: string): EmbeddedFormat | 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;
-    /** Resolves a package-internal "#" specifier from the nearest package
-     * scope. Relative targets stay in that package; bare package targets
-     * re-enter the same runtime resolver so edge-kind conditions and package
-     * self-resolution remain consistent. */
     private resolvePackageImport;
-    /** 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;
-    private sourceOf;
-    /** 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;
 }