@scriptc/compiler 0.0.14 → 0.0.16

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

@@ -1,6 +1,7 @@
 import * as ts from "../ts7/adapter.js";
 import type { Lowerer } from "./lowerer.js";
 import { IrExpr, IrFunction, IrStmt, IrType, SrcLoc } from "../../ir/nodes.js";
+import type { ScrDiagnostic } from "../../diagnostics/diagnostic.js";
 import { type ClassInfo } from "./lower-classes.js";
 /** How a parameter participates in CALL-SITE COMPLETION (the frontend
  * completes every call to the one full signature, so the IR and backends
@@ -372,6 +373,22 @@ export declare const TIMER_MODULE_MEMBERS: ReadonlySet<string>;
    * form (`timers.setTimeout(...)`). Null when the member isn't a lowered
    * timer function (the caller's fence machinery takes over). */
 export declare function lowerTimersMemberCall(L: Lowerer, expr: ts.CallExpression, member: string, loc: SrcLoc): IrExpr | null;
+export interface FfiValidationResult {
+    diagnostics: ScrDiagnostic[];
+    symbolsByName: ReadonlyMap<string, ReadonlySet<ts.Symbol>>;
+}
+/** Resolve and validate every configured outbound binding before emit.
+ * Candidate declarations are signature-only functions bearing the manifest
+ * name anywhere in the program. Multiple scoped declarations are all native
+ * bindings under the existing name-based call surface, so every candidate
+ * must fit the one manifest ABI. */
+export declare function validateFfiImports(L: Lowerer): FfiValidationResult;
+/** A manifest-bound call of a signature-only ambient declaration. This
+ * recognition deliberately runs before ambientUndefVarRootOf: without the
+ * manifest the exact same source keeps Node's ReferenceError semantics;
+ * with it, only the resolved declaration binding (never a shadowing
+ * function with a body) becomes a direct native call. */
+export declare function lowerFfiCall(L: Lowerer, expr: ts.CallExpression): IrExpr | null;
 export declare function lowerCall(L: Lowerer, expr: ts.CallExpression): IrExpr;
 /** The RUNTIME-ARITY spread call — `f(...args)`, the rest-forwarding idiom
    * (`const f = (...args) => from(...args)`): a spread whose length is a

package/dist/frontend/lowering/lower-calls.js

@@ -4,13 +4,13 @@
  * generic instantiation (bounded by MAX_GENERIC_INSTANCES). */
 import * as ts from "../ts7/adapter.js";
 import { lowerGenMethodCall } from "./lower-generators.js";
-import { BOOL, CAUGHT, DYN, F64, JSVAL, STRING, SYMBOL_T, UNDEFINED_T, VOID, arrayOf, canBoxFuncIntoDyn, canConvertToDyn, canDynCheckTo, canMarshalTypedFuncIntoIsland, funcOf, isUnitType, shapeHasAccessorSlots, typeEquals } from "../../ir/nodes.js";
+import { BOOL, BYTES_U8, CAUGHT, DYN, F64, JSVAL, STRING, SYMBOL_T, UNDEFINED_T, VOID, arrayOf, canBoxFuncIntoDyn, canConvertToDyn, canDynCheckTo, canMarshalTypedFuncIntoIsland, funcOf, isUnitType, shapeHasAccessorSlots, typeEquals } from "../../ir/nodes.js";
 import { isJsSourceFile, locOf } from "../program.js";
 import { isGenericCallableMemberType, typeKey } from "../types.js";
 import { PoisonError, dynFallbackType, dynUndefinedExpr, importCallHandleType, jsFuncNameOf, newFnCtx, nodeThrowExpr } from "./lowerer.js";
 import { enforceLibBoundary } from "./lib-boundary.js";
 import { NARROW_FIRST, builtinFenceHintOf, builtinModuleFnOf } from "./surfaces.js";
-import { requiresDynamicDiag } from "../../diagnostics/diagnostic.js";
+import { ffiBindingDiag, ffiSignatureDiag, requiresDynamicDiag } from "../../diagnostics/diagnostic.js";
 import { mixinFnShapeOf } from "./lower-mixins.js";
 import { bufEncoding, dynStringReceiver, lowerArrayFromCall, lowerDynArrayFilterCall, lowerDynArrayFlatMapCall, lowerGroupByStaticCall, lowerIteratorHelperCall, lowerObjectAssignIndexShape, lowerObjectFromEntriesCall, lowerObjectIterOverIndexShape, lowerRegexMethodCall, lowerStringMethodCall, lowerTupleReadMethodCall } from "./lower-containers.js";
 import { lowerChildStreamMethodCall, lowerCreateRequireCall, lowerDirentMethodCall, lowerPerfHooksCall, lowerProcStreamMethodCall, lowerReflectApplyCall, lowerWatcherMethodCall } from "./lower-builtins.js";
@@ -2271,6 +2271,195 @@ export function lowerTimersMemberCall(L, expr, member, loc) {
     }
     return null;
 }
+function ffiTypeForClass(cls) {
+    switch (cls) {
+        case "bool":
+            return BOOL;
+        case "string":
+            return STRING;
+        case "bytes":
+            return BYTES_U8;
+        case "void":
+            return VOID;
+        default:
+            return F64;
+    }
+}
+/** The declaration half of an outbound FFI binding. Kept independent of
+ * call-site argument checks so the whole manifest can be validated even
+ * when a configured function is never called. */
+function ffiDeclarationDiagnostic(L, binding, symbol, loc) {
+    const declarations = L.checker.declarationsOf(symbol);
+    const functionDecls = declarations.filter(ts.isFunctionDeclaration);
+    if (functionDecls.length === 0 ||
+        declarations.some((decl) => !ts.isFunctionDeclaration(decl)) ||
+        functionDecls.some((decl) => decl.body !== undefined)) {
+        return ffiBindingDiag(binding.name, "the configured name does not resolve exclusively to signature-only function declarations", loc);
+    }
+    if (functionDecls.some((decl) => (decl.typeParameters?.length ?? 0) > 0)) {
+        return ffiSignatureDiag(binding.name, "generic ambient declarations cannot describe one fixed C ABI", loc);
+    }
+    const signatures = L.checker.getCallSignatures(L.checker.getTypeOfSymbol(symbol));
+    if (signatures.length !== 1) {
+        return ffiSignatureDiag(binding.name, `the ambient binding has ${signatures.length} call signatures; exactly one non-overloaded signature is required`, loc);
+    }
+    const signature = signatures[0];
+    const params = signature.getParameters();
+    if (params.length !== binding.params.length) {
+        return ffiSignatureDiag(binding.name, `the TypeScript declaration has ${params.length} parameter(s), but the manifest declares ${binding.params.length}`, loc);
+    }
+    const expectedParams = binding.params.map(ffiTypeForClass);
+    for (let i = 0; i < params.length; i++) {
+        const paramType = L.checker.getTypeOfSymbol(params[i]);
+        // `mapType` deliberately gives uninhabited value positions a cheap f64
+        // slot because no TypeScript value can ever reach them. An FFI
+        // declaration is different: it is a callable external contract, so a
+        // `never` slot cannot truthfully describe any native parameter.
+        if ((paramType.flags & ts.TypeFlags.Never) !== 0) {
+            return ffiSignatureDiag(binding.name, `parameter ${i + 1} is 'never', an uninhabited TypeScript type that cannot describe a native ABI parameter`, loc);
+        }
+        const mapped = L.mapTypeOf(paramType);
+        const expected = expectedParams[i];
+        if (mapped === null || !typeEquals(mapped, expected)) {
+            return ffiSignatureDiag(binding.name, `parameter ${i + 1} maps to '${mapped === null ? L.checker.typeToString(paramType) : L.fmt(mapped)}', ` +
+                `which does not fit manifest class '${binding.params[i]}'`, loc);
+        }
+    }
+    const returnType = L.checker.getReturnTypeOfSignature(signature);
+    // A native function is allowed to return. Accepting `never` here would
+    // let tsc erase all control flow after the call while the linked function
+    // continues, making the generated program disagree with TypeScript.
+    if ((returnType.flags & ts.TypeFlags.Never) !== 0) {
+        return ffiSignatureDiag(binding.name, "the return type is 'never', but a native ABI return cannot uphold TypeScript's non-returning contract", loc);
+    }
+    const declaredReturn = L.mapTypeOf(returnType);
+    const expectedReturn = ffiTypeForClass(binding.returns);
+    if (declaredReturn === null || !typeEquals(declaredReturn, expectedReturn)) {
+        return ffiSignatureDiag(binding.name, `the return maps to '${declaredReturn === null ? L.checker.typeToString(returnType) : L.fmt(declaredReturn)}', ` +
+            `which does not fit manifest class '${binding.returns}'`, loc);
+    }
+    return null;
+}
+/** Resolve and validate every configured outbound binding before emit.
+ * Candidate declarations are signature-only functions bearing the manifest
+ * name anywhere in the program. Multiple scoped declarations are all native
+ * bindings under the existing name-based call surface, so every candidate
+ * must fit the one manifest ABI. */
+export function validateFfiImports(L) {
+    const diagnostics = [];
+    const symbolsByName = new Map();
+    const configuredNames = new Set(L.ffiImports.map((binding) => binding.name));
+    const candidates = new Map();
+    if (configuredNames.size === 0)
+        return { diagnostics, symbolsByName };
+    for (const file of L.program.getSourceFiles()) {
+        ts.walkPreorder(file, (node) => {
+            if (ts.isFunctionDeclaration(node)) {
+                if (node.body === undefined &&
+                    node.name !== undefined &&
+                    configuredNames.has(node.name.text)) {
+                    const symbol = L.checker.getSymbolAtLocation(node.name);
+                    if (symbol !== undefined) {
+                        let bySymbol = candidates.get(node.name.text);
+                        if (bySymbol === undefined) {
+                            bySymbol = new Map();
+                            candidates.set(node.name.text, bySymbol);
+                        }
+                        if (!bySymbol.has(symbol))
+                            bySymbol.set(symbol, node);
+                    }
+                }
+                return "skip";
+            }
+            if (ts.isFunctionLike(node))
+                return "skip";
+        });
+    }
+    for (const binding of L.ffiImports) {
+        const bySymbol = candidates.get(binding.name);
+        if (bySymbol === undefined || bySymbol.size === 0) {
+            diagnostics.push(ffiBindingDiag(binding.name, "the program has no signature-only function declaration with this name", { file: L.entry.fileName, start: 0, end: 0 }));
+            continue;
+        }
+        const validSymbols = new Set();
+        let valid = true;
+        for (const [symbol, declaration] of bySymbol) {
+            const diagnostic = ffiDeclarationDiagnostic(L, binding, symbol, locOf(declaration));
+            if (diagnostic === null) {
+                validSymbols.add(symbol);
+            }
+            else {
+                diagnostics.push(diagnostic);
+                valid = false;
+            }
+        }
+        if (valid)
+            symbolsByName.set(binding.name, validSymbols);
+    }
+    return { diagnostics, symbolsByName };
+}
+/** A manifest-bound call of a signature-only ambient declaration. This
+ * recognition deliberately runs before ambientUndefVarRootOf: without the
+ * manifest the exact same source keeps Node's ReferenceError semantics;
+ * with it, only the resolved declaration binding (never a shadowing
+ * function with a body) becomes a direct native call. */
+export function lowerFfiCall(L, expr) {
+    if (!ts.isIdentifier(expr.expression))
+        return null;
+    const binding = L.ffiImportsByName.get(expr.expression.text);
+    if (binding === undefined)
+        return null;
+    const loc = locOf(expr);
+    const bindingError = (detail) => {
+        L.pushDiag(ffiBindingDiag(binding.name, detail, loc));
+        throw new PoisonError();
+    };
+    const signatureError = (detail) => {
+        L.pushDiag(ffiSignatureDiag(binding.name, detail, loc));
+        throw new PoisonError();
+    };
+    const symbol = L.resolveValueSymbol(expr.expression) ??
+        bindingError("the call has no resolved TypeScript symbol");
+    if (L.ffiBindingSymbols !== null) {
+        const validSymbols = L.ffiBindingSymbols.get(binding.name);
+        // No entry means the program-level pass already diagnosed this
+        // binding. Poison the statement without duplicating that diagnostic.
+        if (validSymbols === undefined)
+            throw new PoisonError();
+        if (!validSymbols.has(symbol)) {
+            // TypeScript resolved this call to a distinct local declaration.
+            // The manifest owns only the exact validated ambient binding; a
+            // same-named function with a body remains ordinary scriptc code.
+            return null;
+        }
+    }
+    else {
+        const diagnostic = ffiDeclarationDiagnostic(L, binding, symbol, loc);
+        if (diagnostic !== null) {
+            L.pushDiag(diagnostic);
+            throw new PoisonError();
+        }
+    }
+    if (expr.questionDotToken !== undefined || expr.typeArguments !== undefined) {
+        signatureError("native bindings support direct, non-generic calls only");
+    }
+    if (expr.arguments.some(ts.isSpreadElement)) {
+        signatureError("spread arguments do not have a fixed native ABI");
+    }
+    if (expr.arguments.length !== binding.params.length) {
+        signatureError(`this call passes ${expr.arguments.length} argument(s), but the native ABI requires exactly ${binding.params.length}`);
+    }
+    const expectedParams = binding.params.map(ffiTypeForClass);
+    const expectedReturn = ffiTypeForClass(binding.returns);
+    const args = expr.arguments.map((arg, i) => L.lowerExprExpecting(arg, expectedParams[i]));
+    return {
+        kind: "ffiCall",
+        import: binding.name,
+        args,
+        type: expectedReturn,
+        loc,
+    };
+}
 export function lowerCall(L, expr) {
     const loc = locOf(expr);
     // A call whose chain ROOTS at an ambient-undefined name (`declare