@scriptc/compiler 0.0.0 → 0.0.2

package/dist/frontend/lowering/lower-modules.d.ts

@@ -0,0 +1,135 @@
+import * as ts from "../ts7/adapter.js";
+import type { Lowerer } from "./lowerer.js";
+import { IrClassDef, IrFunction, IrRecordShape, IrStmt, IrUnionDef } from "../../ir/nodes.js";
+/** One file's declarations, split for collection and init-body lowering. */
+export interface FileParts {
+    sf: ts.SourceFile;
+    fnDecls: ts.FunctionDeclaration[];
+    classDecls: ts.ClassDeclaration[];
+    topStmts: ts.Statement[];
+}
+/** Splits each file into function/class declarations and the top-level
+   * statements that form its init body. Node's evaluation order (depth-first
+   * postorder, entry last), computed by preflight. Single-file programs
+   * (tests, coverage on broken files) may arrive with an empty order — fall
+   * back to the entry alone. */
+export declare function splitFiles(L: Lowerer): FileParts[];
+/** A source file dynamic `import("<relative>")` can host as a COMPILED
+   * module namespace (lowerOwnModuleImport): a non-declaration program file
+   * that is not JSON and not CommonJS-flavored (a CJS namespace is built
+   * from module.exports through Node's lexer — a different surface with no
+   * static story here). Null for everything else. */
+export declare function dynamicImportProgramTargetOf(program: ts.Program, sf: ts.SourceFile, spec: string): ts.SourceFile | null;
+/** --dynamic builds: program modules reachable ONLY through dynamic
+   * `import()` join the compiled module graph — appended to `order` (before
+   * the entry, which stays last) in depth-first postorder over their own
+   * static import edges, exactly like preflight ordered the static graph.
+   * NOTHING calls their %init at startup (%main runs only the entry's init,
+   * and no static import header names these), so a dynamic-only module
+   * still evaluates exactly when Node evaluates it: the import() site's
+   * namespace builder calls the guarded init on the engine microtask.
+   * Fixpoint: an added module's own import() sites are scanned too. Static
+   * cycles inside the added subgraph get preflight's SC1016 via `onCycle`
+   * (preflight only walked the entry's static graph, so it never saw
+   * these). Idempotent — re-running on an already-extended order adds
+   * nothing (both lowering passes share one array). */
+export declare function appendDynamicImportModules(program: ts.Program, order: ts.SourceFile[], onCycle: (cycle: string) => void): void;
+/** Collect pass over the WHOLE program: signatures, class shapes, and
+   * file-scope globals visible everywhere → hoisting, mutual recursion, and
+   * cross-module references fall out for free. Runs in both passes —
+   * signatures are cheap and calls resolve against them; only BODY lowering
+   * is reachability-gated. */
+export declare function collectProgram(L: Lowerer, parts: FileParts[]): void;
+/** The npm-import chokepoint, run once per pass during collection (so
+   * bodies lowered in ANY pass resolve the bindings). In a static build
+   * every value-importing npm import reports the requires-dynamic
+   * diagnostic naming the package — the package's shipped JS has exactly
+   * one execution home, the embedded engine. Under --dynamic each value
+   * binding becomes a jsval GLOBAL, registered by ALIASED symbol (modules
+   * importing the same export share one global) and initialized at the
+   * top of the importing module's %init by island.import — the engine's
+   * module registry caches, so re-imports are lookups, not re-evaluations.
+   * The runtime graph (the package entry plus everything it reaches)
+   * builds here too; its failures are ordinary diagnostics at the import
+   * site. Type-only imports are free either way: the .d.ts is a type
+   * surface, not code. */
+export declare function collectNpmImports(L: Lowerer, parts: FileParts[]): void;
+/** JSON module default imports (`import pkg from "../package.json"`):
+   * the document is DATA known at build time, so the binding bakes into a
+   * record global — the checker's structural type for the module (thanks
+   * to resolveJsonModule) maps to a record shape, the JSON text parses in
+   * the compiler, and comptimeValueToIr turns the value into literal IR
+   * assigned in the importing module's %init prelude (evaluation order:
+   * imports before the importer's body, like npm bindings). Two importers
+   * of the same document share one global (keyed by the ALIASED symbol).
+   * Shapes outside the bakeable surface (null-valued fields, mixed
+   * arrays, ...) report the standard unsupported-type diagnostic at the
+   * import site. Preflight already fenced named/namespace JSON imports
+   * and kept .json files out of the module order. */
+export declare function collectJsonImports(L: Lowerer, parts: FileParts[]): void;
+/** The classes, records, and unions the emitted module carries: exactly
+   * what the lowered functions and globals reference, closed transitively
+   * over record fields, union arms, class field types, base chains, and
+   * WHOLE hierarchies (hierarchy membership decides object layout:
+   * dropping an unused subclass must not turn its base into a standalone
+   * class at emit time). Registry entries interned while collecting
+   * signatures nothing reaches stay out — an unreached type leaves no
+   * trace. A referenced class with no registration had its collection
+   * deferred: the reference flushes those diagnostics. Methods whose
+   * bodies were not lowered leave the def's method list, so vtable slots
+   * exist exactly for emitted overrides. */
+export declare function moduleArtifacts(L: Lowerer, functions: IrFunction[]): {
+    classes: IrClassDef[];
+    records: IrRecordShape[];
+    unions: IrUnionDef[];
+};
+export declare function collectGlobals(L: Lowerer, sf: ts.SourceFile, topStmts: ts.Statement[]): void;
+/** The checker's symbol for a module's default export — the symbol a
+   * default import of this module aliases to (getAliasedSymbol), so keying
+   * the default's global by it makes every importer resolve to the same
+   * storage through the ordinary globalOf path. Null for modules without
+   * a default export (or non-module files). */
+export declare function defaultExportSymbolOf(L: Lowerer, sf: ts.SourceFile): ts.Symbol | null;
+/** The declaration symbol of a top-level function/class declaration,
+   * covering the one legal NAMELESS form: `export default function () {}` /
+   * `export default class {}`. A named declaration answers through its
+   * name node; the anonymous default IS the module's `default` export
+   * symbol (the binder declares it there), so collection, reachability,
+   * and body lowering all key that one identity — which is also what a
+   * default import's alias chain resolves to. */
+export declare function declSymbolOf(L: Lowerer, decl: ts.FunctionDeclaration | ts.ClassDeclaration): ts.Symbol | undefined;
+/** `export default <expr>` in a module's init body: the first (and only)
+   * assignment of the pre-registered `default` global — evaluated at the
+   * statement's source position, exactly where Node runs it (Node's
+   * expression defaults snapshot exactly once, here). ENTITY-NAME defaults
+   * are alias plumbing with no storage of their own: the statement lowers
+   * to nothing — collection either accepted the alias (const/function/
+   * class targets, where importers' alias-resolved reads equal the
+   * snapshot) or already fenced it (mutable targets), and re-lowering
+   * would double-report. A NON-alias default whose type had no
+   * registration (collection reported the blocker) re-lowers the
+   * expression so the expression's OWN diagnostic wins when it has one,
+   * then poisons. */
+export declare function lowerDefaultExport(L: Lowerer, stmt: ts.ExportAssignment): IrStmt | null;
+/** One file's top-level statements as its init function — RUN-ONCE like a
+   * Node module body: non-entry inits open with a guard flag test (already
+   * ran → return) and set the flag before anything else, so every caller —
+   * hoisted import headers, inline require statements, diamonds, cache-hit
+   * re-requires — gets Node's module-cache semantics from the same call.
+   * After the guard comes the file's HOISTED module-edge header: one
+   * guarded %init call per imported user module and the island loads for
+   * npm imports, in import order (Node evaluates every imported module
+   * before the importer's body — depth-first postorder falls out of the
+   * nesting). CommonJS requires are NOT in the header: Node runs them at
+   * their statements, so the statement lowering emits their %init calls
+   * inline in the body. JSON-import bindings (pure data) load next; then
+   * the body. Top-level var statements assign the pre-registered globals
+   * instead of declaring locals. */
+export declare function lowerFileInit(L: Lowerer, sf: ts.SourceFile, stmts: ts.Statement[], name: string): IrFunction;
+/** %main is just the entry's %init call: Node's whole module evaluation
+   * order lives in the init functions themselves — each file's hoisted
+   * import header runs its dependencies first (depth-first postorder by
+   * nesting), CommonJS require statements call dependency inits inline in
+   * their bodies, and the run-once guards turn every revisit (diamonds,
+   * re-imports, re-requires) into a cache hit. */
+export declare function buildMain(L: Lowerer): IrFunction;