@scriptc/compiler 0.0.14 → 0.0.16

package/dist/frontend/lowering/lowerer.d.ts

@@ -1,7 +1,7 @@
 import * as ts from "../ts7/adapter.js";
 import type { ScrDiagnostic } from "../../diagnostics/diagnostic.js";
 import { UNSUPPORTED } from "../../diagnostics/diagnostic.js";
-import type { IrClassDef, IrExpr, IrFunction, IrGlobal, IrLocal, IrModule, IrParam, IrRecordShape, IrStmt, IrType, IrUnionDef, SrcLoc } from "../../ir/nodes.js";
+import type { IrClassDef, IrExpr, IrFfiImport, IrFunction, IrGlobal, IrLocal, IrModule, IrParam, IrRecordShape, IrStmt, IrType, IrUnionDef, SrcLoc } from "../../ir/nodes.js";
 import { type DynamicImportResolution, type NpmBuiltinUse, type NpmLazyTrap } from "../npm.js";
 import { type StartupCrash } from "../program.js";
 import { ShapeRegistry, type TypeMapperCtx, UnionRegistry } from "../types.js";
@@ -210,6 +210,11 @@ export interface LowerOptions {
      * OUTSIDE the graph, so discovery seeds them alongside the init
      * bodies. Names are the entry file's unqualified declaration names. */
     libRoots?: readonly string[];
+    /** Outbound native FFI declarations from a validated format-1 manifest.
+     * Calls of their exact ambient TypeScript bindings lower to direct C ABI
+     * imports; without this option ambient declarations keep Node's ordinary
+     * ReferenceError behavior. */
+    ffiImports?: readonly IrFfiImport[];
 }
 /** The Lowerer's pass configuration (see lowerToIr). */
 export interface LowererMode {
@@ -230,6 +235,11 @@ export interface LowererMode {
      * module init — Node refuses the whole graph before anything evaluates,
      * so nothing runs. */
     startupCrash?: StartupCrash | null;
+    /** The build's outbound native FFI declarations. */
+    ffiImports?: readonly IrFfiImport[];
+    /** Program-validated ambient declaration symbols for each FFI name.
+     * Undefined in discovery's legacy call-local validation path. */
+    ffiBindingSymbols?: ReadonlyMap<string, ReadonlySet<ts.Symbol>>;
 }
 /** Build lowering runs in two passes over the same ts.Program:
  *
@@ -699,6 +709,11 @@ export declare class Lowerer {
     readonly targetPlatform: string;
     /** LowererMode.startupCrash — buildMain opens %main with the throw. */
     readonly startupCrash: StartupCrash | null;
+    /** Outbound native bindings by their source-level ambient name. */
+    readonly ffiImports: readonly IrFfiImport[];
+    readonly ffiImportsByName: ReadonlyMap<string, IrFfiImport>;
+    /** Non-null after whole-program FFI declaration validation. */
+    readonly ffiBindingSymbols: ReadonlyMap<string, ReadonlySet<ts.Symbol>> | null;
     /** Symbols a POISONED declaration statement would have bound: the
      * declaration's own diagnostic is already recorded, and no local/global
      * registered, so later references fall through every resolution step —

package/dist/frontend/lowering/lowerer.js

@@ -23,7 +23,7 @@ import { boundaryIntoIslandMsg, boundaryOutOfIslandMsg, builtinConstLit, builtin
 import { splitFiles, collectProgram, collectNpmImports, collectJsonImports, moduleArtifacts, collectGlobals, declSymbolOf, defaultExportSymbolOf, lowerFileInit, lowerDefaultExport, buildMain, appendDynamicImportModules } from "./lower-modules.js";
 import { registerBuiltinErrorClasses, registerBuiltinEmitterClass, registerBuiltinStreamClasses, builtinErrorInfoOf, builtinEmitterInfoOf, builtinStreamInfoOf, analyzeClassDecoration, classIteratorDrainCall, classIteratorNextCall, classIteratorOf, classIteratorOpenCall, classIteratorRestDrainCall, classMemberNameOf, classValueRef, collectClassShape, exactClassOfReceiver, collectClassShapeInner, ctorAbiEquals, findMethodOn, findStaticOn, findGenericMethodOn, findGenericStaticOn, genericClassInstanceType, isSubclassOf, inHierarchy, overrideBelow, staticShadowBelow, upcastTo, lowerClassMembers, lowerClassCtor, lowerClassExpression, lowerClassExpressionInfo, lowerClassMethodMember, lowerClassValueProperty, lowerStaticMethod, throwingSetterFn, fieldInitStmts, lowerStaticFieldInits, lowerStaticFieldRead, lowerDerivedCtorBody, superCallStmt, lowerSuperMethodCall, superThisRef, lowerSuperAccessorRead, lowerSuperAccessorWrite, inheritsBuiltinErrorCtor, inheritsBuiltinEmitterCtor, errorMessageArg, lowerNew, accessorCall } from "./lower-classes.js";
 import { mixinCallClassInfoOf, mixinIntersectionInstanceType } from "./lower-mixins.js";
-import { bindingNeverReassigned, bodyReadsArguments, isThisParameter, paramShape, paramShapes, checkDefaultParamBodyType, completeArgs, wrappedUndefined, undefinedArgFor, requireExactArityValue, bodyReturnType, declaredReturnType, collectSignature, collectSignatureInner, collectGenericSignature, genericFnOf, lowerGenericCall, lowerGenericFnValue, inferTypeParamBindings, lowerGenericInstance, lowerCall, lowerTimersMemberCall, lowerPromiseMethodCall, lowerFilterNarrowCall, isTopLevelFnSymbol, lowerNestedFunctionDecl, lambdaSignature, lowerLambda, lowerFunction } from "./lower-calls.js";
+import { bindingNeverReassigned, bodyReadsArguments, isThisParameter, paramShape, paramShapes, checkDefaultParamBodyType, completeArgs, wrappedUndefined, undefinedArgFor, requireExactArityValue, bodyReturnType, declaredReturnType, collectSignature, collectSignatureInner, collectGenericSignature, genericFnOf, lowerGenericCall, lowerGenericFnValue, inferTypeParamBindings, lowerGenericInstance, lowerCall, lowerFfiCall, lowerTimersMemberCall, lowerPromiseMethodCall, lowerFilterNarrowCall, isTopLevelFnSymbol, lowerNestedFunctionDecl, lambdaSignature, lowerLambda, lowerFunction, validateFfiImports } from "./lower-calls.js";
 import { lowerArrayMethodCall, lowerBufferStaticCall, lowerBytesMethodCall, lowerBytesNew, lowerMapMethodCall, lowerMapForEachCall, buildMapForEachFn, lowerRecordOvfCaptureHelper, lowerEnvToPairsHelper, lowerSetMethodCall, lowerSetForEachCall, buildSetForEachFn, lowerRegexMethodCall, lowerStringMethodCall } from "./lower-containers.js";
 import { lowerStreamModuleCall } from "./lower-stream.js";
 import { lowerEmitOverrideSpec } from "./lower-emitter.js";
@@ -163,10 +163,37 @@ export function lowerToIr(program, entry, moduleOrder, options = {}) {
             dynamicCycleDiags.push(unsupportedDiag("SC1016", { file: entry.fileName, start: 0, end: 0 }, `circular imports (${cycle}; ${reason})`));
         });
     }
-    const reachable = new Lowerer(program, entry, moduleOrder, dynamic, { targetPlatform }).discover(options.libRoots);
-    const emit = new Lowerer(program, entry, moduleOrder, dynamic, { reachable, targetPlatform, startupCrash });
+    const ffiImports = options.ffiImports ?? [];
+    const validation = new Lowerer(program, entry, moduleOrder, dynamic, {
+        targetPlatform,
+        ffiImports,
+    });
+    const ffiValidation = validateFfiImports(validation);
+    // Discovery must use the same exact-symbol ownership as emit. Otherwise a
+    // local function shadowing a configured ambient name is mistaken for FFI
+    // while computing reachability, even though emit would correctly lower it
+    // as ordinary TypeScript. FFI-free builds reuse the validation lowerer
+    // (validation is an immediate no-op there), retaining the historical
+    // two-pass construction cost.
+    const discovery = ffiImports.length === 0
+        ? validation
+        : new Lowerer(program, entry, moduleOrder, dynamic, {
+            targetPlatform,
+            ffiImports,
+            ffiBindingSymbols: ffiValidation.symbolsByName,
+        });
+    const reachable = discovery.discover(options.libRoots);
+    const emit = new Lowerer(program, entry, moduleOrder, dynamic, {
+        reachable,
+        targetPlatform,
+        startupCrash,
+        ffiImports,
+        ffiBindingSymbols: ffiValidation.symbolsByName,
+    });
     for (const d of dynamicCycleDiags)
         emit.pushDiag(d);
+    for (const d of ffiValidation.diagnostics)
+        emit.pushDiag(d);
     const result = emit.run();
     if (options.coverage !== true)
         return result;
@@ -175,6 +202,8 @@ export function lowerToIr(program, entry, moduleOrder, options = {}) {
         remainder: true,
         alreadyFlushed: emit.flushedSymbols,
         targetPlatform,
+        ffiImports,
+        ffiBindingSymbols: ffiValidation.symbolsByName,
     });
     const rem = remainder.run();
     return { ...result, unreached: { diagnostics: rem.diagnostics, stats: rem.stats } };
@@ -852,6 +881,11 @@ export class Lowerer {
     targetPlatform;
     /** LowererMode.startupCrash — buildMain opens %main with the throw. */
     startupCrash;
+    /** Outbound native bindings by their source-level ambient name. */
+    ffiImports;
+    ffiImportsByName;
+    /** Non-null after whole-program FFI declaration validation. */
+    ffiBindingSymbols;
     /** Symbols a POISONED declaration statement would have bound: the
      * declaration's own diagnostic is already recorded, and no local/global
      * registered, so later references fall through every resolution step —
@@ -902,6 +936,9 @@ export class Lowerer {
         this.alreadyFlushed = mode.alreadyFlushed ?? new Set();
         this.targetPlatform = mode.targetPlatform ?? process.platform;
         this.startupCrash = mode.startupCrash ?? null;
+        this.ffiImports = mode.ffiImports ?? [];
+        this.ffiImportsByName = new Map(this.ffiImports.map((entry) => [entry.name, entry]));
+        this.ffiBindingSymbols = mode.ffiBindingSymbols ?? null;
         this.checker = program.getTypeChecker();
         this.typeCtx = {
             checker: this.checker,
@@ -1588,7 +1625,7 @@ export class Lowerer {
         const module = this.diags.length > 0
             ? null
             : {
-                irVersion: 1,
+                irVersion: 2,
                 sourceFile: this.entry.fileName,
                 functions,
                 classes: artifacts.classes,
@@ -1597,6 +1634,7 @@ export class Lowerer {
                 globals: this.globalsList,
                 ...(this.npmEmbedded ? { embedded: this.npmEmbedded } : {}),
                 entry: ENTRY_NAME,
+                ...(this.ffiImports.length > 0 ? { ffiImports: [...this.ffiImports] } : {}),
             };
         return {
             module,
@@ -6614,7 +6652,8 @@ export class Lowerer {
         // calls before the general dispatch (the general identifier-call paths
         // have no lowering for a promise-returning ambient global, and
         // `import` is a keyword callee no identifier path matches).
-        return (lowerFetchCall(this, expr) ??
+        return (lowerFfiCall(this, expr) ??
+            lowerFetchCall(this, expr) ??
             lowerDynamicImportCall(this, expr) ??
             lowerCall(this, expr));
     }