@scriptc/compiler 0.2.8 → 0.2.10

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

@@ -1,8 +1,11 @@
 import { type CycleInitFlag } from "./cycle-initialization.js";
 import type { FieldLift } from "./coercions/structural-plans.js";
 import { CoercionState } from "./coercions/state.js";
+import { NarrowingStability } from "./narrowing-stability.js";
 import { StringIndexBounds } from "./string-index-bounds.js";
+import { NanCodedReads } from "./nan-coded-reads.js";
 import { RuntimeOptionalLocals } from "./runtime-optional-locals.js";
+import { type ContractAnnotations } from "../contract-types.js";
 import type { WidthLift } from "./width-lift.js";
 import { type FnCtx } from "./function-context.js";
 import type { FrontendServices } from "../services.js";
@@ -87,6 +90,9 @@ export interface LowerResult {
     /** Present iff diagnostics is empty. */
     module: IrModule | null;
     diagnostics: ScrDiagnostic[];
+    /** The program's written contract types (@scriptc/types), keyed by the
+     * source locations the IR carries; absent when it writes none. */
+    contracts?: ContractAnnotations;
     /** JS statements whose compile fences DEFERRED to runtime (runtimeFence
      * statements in the module) — off the build, on the coverage report. */
     runtimeFences: ScrDiagnostic[];
@@ -361,6 +367,10 @@ export declare class Lowerer {
     /** Per-symbol result of the never-reassigned file scan
      * (bindingNeverReassigned — object-literal generic-method receivers). */
     readonly neverReassignedCache: Map<ts.Symbol, boolean>;
+    /** Typed-array element reads whose every consumer treats undefined like
+     * NaN, which lower to plain doubles (see nan-coded-reads.ts). Settled by
+     * analyzeRuntimeOptionalArrayReads before any body lowers. */
+    nanCodedReads: NanCodedReads | null;
     private stringIndexBoundsCache;
     /** Proofs that a string element read names an existing code unit. The
      * indexed-read analysis and expression lowering share one instance, so a
@@ -471,6 +481,10 @@ export declare class Lowerer {
      * discriminant was captured. A case match narrows the captured value,
      * not that mutable binding; preserve its tagged representation on reads. */
     readonly unstableSwitchBindings: Set<ts.Symbol>;
+    /** Whether a checker narrowing of a mutable member or closure-assigned
+     * binding still holds at its use (calls do not reset TypeScript's
+     * narrowing). Stale ones read the declared storage or check it. */
+    readonly narrowing: NarrowingStability;
     /** All storage slots widened for runtime absence, including slots whose
      * current control-flow branch has temporarily narrowed the value. */
     readonly runtimeOptionalStorageLocals: Set<IrLocal>;

package/dist/frontend/lowering/lowerer.js

@@ -19,11 +19,14 @@ import { lowerUtilTypeValue, pathModuleValue, utilTypesModuleValue, } from "./lo
 import { everyExprChild, everyStmtChild, transformStmtList } from "../../ir/traverse.js";
 import { RuntimeOptionalProvenance } from "./runtime-optional-provenance.js";
 import { presentAtUse, reassignedBindings } from "./runtime-optional-guards.js";
+import { NarrowingStability } from "./narrowing-stability.js";
 import { ArrayElementStates } from "./runtime-optional-elements.js";
 import { indexReadInBounds } from "./runtime-optional-bounds.js";
 import { ArrayOwnership } from "./runtime-optional-ownership.js";
 import { StringIndexBounds } from "./string-index-bounds.js";
+import { NanCodedReads } from "./nan-coded-reads.js";
 import { RuntimeOptionalLocals } from "./runtime-optional-locals.js";
+import { collectContractAnnotations } from "../contract-types.js";
 import { sanitizeUnregisteredClassTypes } from "./sanitize-class-types.js";
 import { UnregisteredClassTypes } from "./unregistered-class-types.js";
 import { bindingInContext, captureContextBinding, declareContextLocal, declareContextThis, } from "./function-context.js";
@@ -394,6 +397,39 @@ export function lowerToIr(program, entry, moduleOrder, options = {}) {
     timing("divergence-scan", { found: divergences.length });
     if (divergences.length > 0)
         result = { ...result, divergences };
+    // Contract types (@scriptc/types): written annotations, checked against
+    // the IR by the compile pipeline (contracts/check.ts).
+    // Acyclic object types name the IR unit the program lowered them to; a
+    // type the module never uses has no unit (mapping it now only touches the
+    // lowerer's tables, never the finished module).
+    const lowered = result.module;
+    const contracts = collectContractAnnotations(program.getTypeChecker(), moduleOrder, (type) => {
+        if (lowered === null)
+            return null;
+        const mapped = panicSafe(() => resultLowerer.mapTypeOf(type), null);
+        if (mapped?.kind === "object")
+            return lowered.classes?.some((c) => c.name === mapped.className)
+                ? `object:${mapped.className}`
+                : null;
+        if (mapped?.kind === "record")
+            return lowered.records?.some((r) => r.id === mapped.shapeId)
+                ? `record:${mapped.shapeId}`
+                : null;
+        if (mapped?.kind === "union")
+            return lowered.unions?.some((u) => u.id === mapped.unionId)
+                ? `union:${mapped.unionId}`
+                : null;
+        return null;
+    });
+    timing("contract-annotations", { found: contracts.count });
+    if (contracts.diagnostics.length > 0)
+        result = {
+            ...result,
+            module: null,
+            diagnostics: [...result.diagnostics, ...contracts.diagnostics],
+        };
+    else if (contracts.count > 0)
+        result = { ...result, contracts };
     if (options.coverage !== true)
         return result;
     const remainder = new Lowerer(program, entry, moduleOrder, dynamic, {
@@ -976,6 +1012,10 @@ export class Lowerer {
     /** Per-symbol result of the never-reassigned file scan
      * (bindingNeverReassigned — object-literal generic-method receivers). */
     neverReassignedCache = new Map();
+    /** Typed-array element reads whose every consumer treats undefined like
+     * NaN, which lower to plain doubles (see nan-coded-reads.ts). Settled by
+     * analyzeRuntimeOptionalArrayReads before any body lowers. */
+    nanCodedReads = null;
     stringIndexBoundsCache = null;
     /** Proofs that a string element read names an existing code unit. The
      * indexed-read analysis and expression lowering share one instance, so a
@@ -1214,6 +1254,10 @@ export class Lowerer {
      * discriminant was captured. A case match narrows the captured value,
      * not that mutable binding; preserve its tagged representation on reads. */
     unstableSwitchBindings = new Set();
+    /** Whether a checker narrowing of a mutable member or closure-assigned
+     * binding still holds at its use (calls do not reset TypeScript's
+     * narrowing). Stale ones read the declared storage or check it. */
+    narrowing = new NarrowingStability(this);
     /** All storage slots widened for runtime absence, including slots whose
      * current control-flow branch has temporarily narrowed the value. */
     runtimeOptionalStorageLocals = new Set();
@@ -3133,6 +3177,32 @@ export class Lowerer {
                 }
             }
         }
+        const mappedOrNull = (node) => panicSafe(() => this.mapTypeOf(this.typeOf(node)), null);
+        const nanCoded = new NanCodedReads({
+            symbolOf,
+            declarationOf: (symbol) => this.checker.valueDeclarationOf(symbol),
+            bytesElemOf: (receiver) => {
+                const t = mappedOrNull(receiver);
+                return t?.kind === "bytes" ? t.elem : null;
+            },
+            isNumber: (node) => mappedOrNull(node)?.kind === "f64",
+            isString: (node) => mappedOrNull(node)?.kind === "string",
+            hasLength: (node) => {
+                const kind = mappedOrNull(node)?.kind;
+                return kind === "array" || kind === "bytes";
+            },
+            isStdlibGlobal: (node, name) => this.isStdlibGlobal(node, name),
+            paramIsNumber: (fn, index) => {
+                const param = signatureBySymbol.get(fn)?.params[index];
+                return (param !== undefined &&
+                    param.type.kind === "f64" &&
+                    (param.mode === "required" || param.mode === "omittable"));
+            },
+            returnIsNumber: (fn) => signatureBySymbol.get(fn)?.returnType.kind === "f64",
+            methodOverridden: (fn) => (familyBySymbol.get(fn)?.length ?? 1) > 1,
+        }, sourceFiles);
+        nanCoded.analyze();
+        this.nanCodedReads = nanCoded;
         const peel = (node) => {
             let e = node;
             while (ts.isParenthesizedExpression(e) ||
@@ -3252,8 +3322,11 @@ export class Lowerer {
             const kind = this.mapTypeOf(this.typeOf(e.expression))?.kind;
             if (kind === "string")
                 return !this.stringIndexBounds.inBounds(e);
-            // Typed-array reads answer undefined for an invalid index too.
-            return kind === "array" || kind === "bytes";
+            // Typed-array reads answer undefined for an invalid index too, unless
+            // every consumer treats undefined like NaN.
+            if (kind === "bytes")
+                return !nanCoded.isNumericRead(e);
+            return kind === "array";
         };
         const isDynamicObjectEntryRead = (node) => {
             const read = peel(node);
@@ -3337,6 +3410,13 @@ export class Lowerer {
                 this.mapTypeOf(this.typeOf(e))?.kind === "union" &&
                 this.armTag(this.mapTypeOf(this.typeOf(e)).unionId, UNDEFINED_T) >= 0)
                 return true;
+            // A NaN-coded value that reaches a consumer able to observe undefined
+            // is rebuilt as the ordinary optional value there; every other read
+            // of a NaN-coded slot is a plain number.
+            if (nanCoded.reboxes(e))
+                return true;
+            if (nanCoded.readsNanCodedSlot(e))
+                return false;
             if (ts.isIdentifier(e)) {
                 const symbol = symbolOf(e);
                 return (symbol !== null &&
@@ -3429,6 +3509,25 @@ export class Lowerer {
                 return false;
             return noteFieldSymbol(symbol, name);
         };
+        /** An instance field of a TypeScript class whose declared storage is
+         * exactly `T | undefined`: an assignment from a missing read stores the
+         * undefined arm while the checker narrows later reads to `T`. */
+        const optionalInstanceField = (symbol) => {
+            const decl = this.checker.valueDeclarationOf(symbol);
+            if (!decl || !ts.isPropertyDeclaration(decl) || !ts.isIdentifier(decl.name))
+                return false;
+            if (ts.getCombinedModifierFlags(decl) & ts.ModifierFlags.Static)
+                return false;
+            const sf = decl.getSourceFile();
+            if (isJsSourceFile(sf) || sf.isDeclarationFile)
+                return false;
+            const declared = typeOrNull(decl.name);
+            const mapped = declared ? this.mapTypeOf(declared) : null;
+            if (mapped?.kind !== "union" || this.armTag(mapped.unionId, UNDEFINED_T) < 0)
+                return false;
+            const arms = this.unions.get(mapped.unionId)?.arms ?? [];
+            return (arms.length === 2 && arms.every((arm) => arm.kind === "undefinedT" || !isUnitType(arm)));
+        };
         const noteFieldSymbol = (symbol, name) => {
             const set = optionalFields.get(symbol) ?? new Set();
             const before = set.size;
@@ -3567,14 +3666,31 @@ export class Lowerer {
             return found;
         };
         const jsLambdas = [];
+        // TypeScript lambdas keep the checker's inferred return type, which
+        // spells a missing read as its bare element type and `read ?? "text"`
+        // as a number. Their closures return the runtime result instead.
+        const tsLambdas = [];
         for (const sf of sourceFiles) {
-            if (!isJsSourceFile(sf))
+            const js = isJsSourceFile(sf);
+            if (!js && sf.isDeclarationFile)
                 continue;
             ts.walkPreorder(sf, (node) => {
                 if (ts.isArrowFunction(node) || ts.isFunctionExpression(node))
-                    jsLambdas.push(node);
+                    (js ? jsLambdas : tsLambdas).push(node);
             });
         }
+        /** The primitive result union of a lambda's returns (see
+         * optionalPrimitiveResultType), as declared functions record it. */
+        const lambdaArithmeticReturn = (fn) => {
+            if (fn.body && !ts.isBlock(fn.body))
+                return optionalPrimitiveResultType(fn.body);
+            for (const expression of returnsOf(fn)) {
+                const result = optionalPrimitiveResultType(expression);
+                if (result)
+                    return result;
+            }
+            return null;
+        };
         for (const [symbol, signature] of signatureBySymbol) {
             const declaration = functionDeclBySymbol.get(symbol);
             if (!declaration || !isJsSourceFile(declaration.getSourceFile()))
@@ -4262,6 +4378,14 @@ export class Lowerer {
                             provenance?.note("static-field", node.left, node.right);
                             changed = true;
                         }
+                        else if (field && !optionalSymbols.has(field) && optionalInstanceField(field)) {
+                            // The checker narrows the field to the assigned read's bare
+                            // type, but the stored value can be undefined: reads keep the
+                            // stored union (runtimeOptionalClassField).
+                            optionalSymbols.add(field);
+                            provenance?.note("assigned-field", node.left, node.right);
+                            changed = true;
+                        }
                         else if (ts.isIdentifier(node.left.expression)) {
                             const symbol = symbolOf(node.left.expression);
                             if (symbol && noteFieldSymbol(symbol, node.left.name.text)) {
@@ -4575,6 +4699,52 @@ export class Lowerer {
             for (const [symbol, decl] of functionDeclBySymbol)
                 if (scanReturns(symbol, decl))
                     changed = true;
+            for (const fn of tsLambdas) {
+                // An annotated return is the author's contract, as for parameters.
+                if (fn.type)
+                    continue;
+                const mapped = this.mapTypeOf(this.typeOf(fn));
+                if (mapped?.kind !== "func")
+                    continue;
+                const previous = this.runtimeOptionalFunctionReturnType(fn, mapped.ret);
+                // Async, generator and void bodies keep their own result shapes.
+                if (previous.kind === "promise" ||
+                    previous.kind === "generator" ||
+                    previous.kind === "void")
+                    continue;
+                const arithmetic = lambdaArithmeticReturn(fn);
+                const next = arithmetic &&
+                    (previous.kind === "f64" || previous.kind === "string" || previous.kind === "bool")
+                    ? arithmetic
+                    : bodyReturnsOptional(fn)
+                        ? this.runtimeOptionalType(previous)
+                        : previous;
+                if (!typeEquals(previous, next)) {
+                    this.runtimeOptionalFunctionReturns.set(fn, next);
+                    provenance?.note("lambda-return", fn, fn.body);
+                    changed = true;
+                }
+                // Calls through the lambda's own binding (`const get = () => xs[i];
+                // get()`) produce the same result as calls of a declared function.
+                const binding = fn.parent;
+                if (next !== previous &&
+                    ts.isVariableDeclaration(binding) &&
+                    binding.initializer === fn &&
+                    !binding.type &&
+                    ts.isIdentifier(binding.name)) {
+                    const symbol = symbolOf(binding.name);
+                    if (symbol && next.kind === "union" && this.armTag(next.unionId, UNDEFINED_T) >= 0) {
+                        if (!optionalReturns.has(symbol)) {
+                            optionalReturns.add(symbol);
+                            changed = true;
+                        }
+                    }
+                    else if (symbol && !arithmeticReturns.has(symbol)) {
+                        arithmeticReturns.set(symbol, next);
+                        changed = true;
+                    }
+                }
+            }
             for (const fn of jsLambdas) {
                 if (!bodyReturnsOptional(fn))
                     continue;
@@ -4606,6 +4776,25 @@ export class Lowerer {
                 }
             }
         }
+        // NaN-coded slots convert optional values on entry instead of holding
+        // the union, so promotion never applies to them.
+        for (const symbol of [...optionalSymbols])
+            if (nanCoded.nanCodedBinding(symbol))
+                optionalSymbols.delete(symbol);
+        for (const symbol of [...optionalReturns])
+            if (nanCoded.nanCodedReturn(symbol))
+                optionalReturns.delete(symbol);
+        for (const [symbol, params] of optionalParams) {
+            const decl = functionDeclBySymbol.get(symbol);
+            for (const index of [...params]) {
+                const name = decl?.parameters[index]?.name;
+                const param = name && ts.isIdentifier(name) ? symbolOf(name) : null;
+                if (param && nanCoded.nanCodedBinding(param))
+                    params.delete(index);
+            }
+            if (params.size === 0)
+                optionalParams.delete(symbol);
+        }
         for (const [site, present] of presentSites)
             if (present)
                 this.presentElementCalls.add(site);
@@ -4678,11 +4867,11 @@ export class Lowerer {
                 const symbol = symbolOf(node.name);
                 if (!symbol)
                     return;
-                if (isJsSourceFile(sf) &&
-                    !node.type &&
+                if (!node.type &&
                     !hasJsTypeAnnotation(node) &&
                     node.initializer &&
-                    (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer))) {
+                    (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer)) &&
+                    (isJsSourceFile(sf) || this.runtimeOptionalFunctionReturns.has(node.initializer))) {
                     const global = this.globalsBySymbol.get(symbol);
                     if (global?.type.kind === "func")
                         global.type = {
@@ -4791,6 +4980,7 @@ export class Lowerer {
     }
     run() {
         const parts = this.splitFiles();
+        this.narrowing.setFiles(parts.map((fp) => fp.sf));
         // The coverage remainder deliberately visits every body that reachable
         // emit skipped. Those files are already phase-managed, so an ordinary
         // checker miss would stay a one-node IPC query instead of falling back
@@ -5170,6 +5360,7 @@ export class Lowerer {
     emitReachable(extraRoots) {
         this.deferredModuleInitializers = new DeferredModuleInitializers();
         const parts = this.splitFiles();
+        this.narrowing.setFiles(parts.map((fp) => fp.sf));
         // Direct lowering callers do not necessarily run program preflight.
         // Establish the same managed header/top-level batch here before
         // collection, while the production path simply finds warm memos.
@@ -5995,6 +6186,12 @@ export class Lowerer {
         const narrowed = this.chainNarrowedType.get(node);
         if (narrowed)
             return narrowed;
+        // A stale narrowing of a mutable member or closure-assigned binding in
+        // an absence/type test (or a slot accepting the declared type) reads
+        // as declared, so the test inspects the stored value.
+        const widened = this.narrowing.widenedType(node);
+        if (widened)
+            return widened;
         const t = this.checker.getTypeAtLocation(node);
         // ALIASED-TYPEOF narrowing: inside a branch a `type === 'string'`
         // test proves (type = typeof val, both never reassigned), references
@@ -8224,7 +8421,23 @@ export class Lowerer {
     }
     /* ── scoping and captures ─────────────────────────────────────────── */
     declareLocal(nameNode, name, type, mutable) {
-        return declareContextLocal(this.ctx, name, type, mutable, this.checker.getSymbolAtLocation(nameNode), bindingSource(nameNode));
+        const symbol = this.checker.getSymbolAtLocation(nameNode);
+        const local = declareContextLocal(this.ctx, name, type, mutable, symbol, bindingSource(nameNode));
+        // A binding declared `T | undefined` that receives a missing read: the
+        // checker narrows it to `T` after the assignment, but the stored value
+        // can be undefined. Track it like widened storage so bare reads keep
+        // the union until a guard proves presence.
+        if (symbol &&
+            this.runtimeOptionalAssignedSymbols.has(symbol) &&
+            type.kind === "union" &&
+            this.armTag(type.unionId, UNDEFINED_T) >= 0 &&
+            this.unions.get(type.unionId)?.arms.length === 2 &&
+            !isUnitType(this.stripUndefinedArm(type))) {
+            const root = this.runtimeOptionalRootOf(local);
+            this.runtimeOptionalStorageLocals.add(root);
+            this.runtimeOptionalLocals.add(root);
+        }
+        return local;
     }
     /** A never-returning call in a value position of type `expected`: the
      * call runs for its effects (it throws or exits), and the expression ends