@scriptc/compiler 0.0.8 → 0.0.10

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

@@ -43,6 +43,12 @@ export type WidthLift = {
     how: "clsWidth";
 } | {
     how: "narrow";
+} | {
+    how: "dynIn";
+} | {
+    how: "upcast";
+} | {
+    how: "funcAdapt";
 };
 export declare class PoisonError extends Error {
 }
@@ -288,6 +294,21 @@ export declare function neverTaintedJsType(L: Lowerer, node: ts.Node, t: ts.Type
  * forward captures included), and the implicit-return completion
  * (lower-calls' own copy of this pattern predates the helper). */
 export declare function dynUndefinedExpr(loc: SrcLoc): IrExpr;
+/** An always-throwing Node-parity error expression (the error.nodeThrow
+ * libCall — the lowered form of arms Node rejects unconditionally:
+ * ERR_INVALID_THIS receivers, ERR_MISSING_ARGS arity ladders, the
+ * symbol-to-string TypeError). kind 0 Error / 1 TypeError / 2 RangeError;
+ * an empty code means no code slot. `type` is the replaced expression's
+ * own (never materialized — the global.undefRead pattern). */
+export declare function nodeThrowExpr(kind: 0 | 1 | 2, code: string, message: string, type: IrType, loc: SrcLoc): IrExpr;
+/** The post-validation fence STRING a validation-ladder Chk libCall
+ * throws after its Node-order checks pass: the same SC2020 text the
+ * per-statement runtime fence would have thrown (message + "[code at
+ * file:line]"), rendered eagerly so the runtime can throw it verbatim
+ * (scr_throw_lowering_fence). The diagnostic joins the runtime-fence
+ * ledger exactly like a deferred statement fence — nothing silently
+ * drops off the coverage report. */
+export declare function ladderFenceExpr(L: Lowerer, surface: string, node: ts.Node, hint?: string): IrExpr;
 /** The checked-dynamic declaration fallback for unmappable binding types
  * (see irTypeOf), two gates over one story:
  *
@@ -344,6 +365,29 @@ 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>;
+    /** TRAP bindings: declarations whose initializer provably throws before
+     * producing a value (its chain roots at an ambient-undefined name —
+     * ambientUndefVarRootOf). Module init unwinds at the declaration, so no
+     * reference to the binding can ever execute; the statement lowers to the
+     * root's throw, no storage exists, and references lower to the same
+     * trap shape (never reached — sound whatever the type). */
+    readonly trapBindings: Set<ts.Symbol>;
+    /** NULLISH bindings of unmappable (generic-signature) types: `const i:
+     * I<A & B> = null as any` — the binding provably holds null/undefined
+     * forever (every write's RHS is nullish too), so no storage exists and
+     * each READ knows the value. Member reads and method calls through one
+     * lower to Node's exact TypeError ("Cannot read properties of null
+     * (reading 'fn')"); nullish-to-nullish flows lower to nothing. The map
+     * answers which unit the binding holds (the TypeError names it). Null
+     * entries cache probed non-qualifiers. */
+    readonly nullishBindings: Map<ts.Symbol, "undefined" | "null" | null>;
+    /** DEAD bindings of unmappable types: never READ anywhere in the
+     * program, declared with no initializer or a value-only one (a function
+     * literal), every write's RHS side-effect-free. Node materializes the
+     * value and drops it — zero observable effect — so the declaration and
+     * its writes lower to nothing, and no type fence fires for a value the
+     * program never consumes. */
+    readonly deadBindings: Set<ts.Symbol>;
     /** IMPLICIT-ANY function-value bindings (npm-static JS — `const knownBy
      * = (cmd) => ...`), by their VariableDeclaration: the registered info,
      * or null for probed non-qualifiers (implicitLocalFnNodeOf). */
@@ -730,12 +774,14 @@ export declare class Lowerer {
     private cjsDefaultImportDepOf;
     /** True when `expr` is an identifier bound by a top-level
      * `const x = require("./local")` of a RELATIVE module — the CommonJS
-     * namespace binding — or by a DEFAULT import of a CommonJS JS module
-     * (`import d from "./lib.cjs"`: Node binds d to module.exports, the
-     * same value require answers). Member accesses on it resolve through
-     * the export table (property symbols → resolveValueSymbol); the bare
-     * value keeps the namespace-object fence, like ESM namespace imports
-     * of builtins. */
+     * namespace binding — or of a bare specifier naming an opted-in
+     * --npm-static package (its CJS entry is a program module, so the
+     * binding is the same namespace over the same export table), or by a
+     * DEFAULT import of a CommonJS JS module (`import d from "./lib.cjs"`:
+     * Node binds d to module.exports, the same value require answers).
+     * Member accesses on it resolve through the export table (property
+     * symbols → resolveValueSymbol); the bare value keeps the
+     * namespace-object fence, like ESM namespace imports of builtins. */
     cjsLocalModuleBindingOf(expr: ts.Expression): boolean;
     /** Assignment-target resolution: a function local (possibly captured) or
      * a module global. tsc has already rejected writes to consts. */
@@ -758,9 +804,11 @@ export declare class Lowerer {
     /** The lowering of a CommonJS `require("./local")` occurrence: a call of
      * the required module's run-once %init at exactly this statement's
      * position — Node's inline evaluation, with the guard supplying the
-     * cache-hit behavior for every require after the first. Null when the
-     * specifier is not a relative program module (builtins load nothing;
-     * anything else kept its preflight fence). */
+     * cache-hit behavior for every require after the first. Bare specifiers
+     * naming an opted-in --npm-static package resolve to that package's
+     * program entry (the same edge preflight admitted — bundle dists require
+     * their external dependencies by name). Null for everything else
+     * (builtins load nothing; the rest kept its preflight fence). */
     requireInitStmt(spec: string, node: ts.Node): IrStmt | null;
     /** True when this body should lower: everything with no reachable set
      * (discovery), the marked bodies in the emit pass, and exactly the
@@ -897,8 +945,10 @@ export declare class Lowerer {
     irTypeOf(node: ts.Node): IrType;
     /** Exact-shape enforcement (SC2002). Records are monomorphic structs, so
      * everywhere a value flows into a typed slot (call arg, initializer,
-     * assignment, field, return) the shapes must MATCH — TS's structural width
-     * subtyping (`{a, b}` where `{a}` is expected) has no runtime coercion.
+     * assignment, field, return) the shapes must MATCH — or width-coerce:
+     * coerceToExpected already ran widthCoerce (the copy-reshape family),
+     * so what reaches here is the RESIDUE its rules decline, and the
+     * diagnostic names the first blocking rule (describeRecordWidthBlocker).
      * Non-record mismatches are not reachable through tsc-clean programs; the
      * validator ICEs on them as the usual backstop. */
     requireExactShape(node: ts.Node, actual: IrType, expected: IrType): void;
@@ -952,6 +1002,13 @@ export declare class Lowerer {
      *               recursively — NESTED width)
      *   arr       — array into array whose element pair lifts (per-element
      *               copy loop, arrayWidthHelper)
+     *   dynIn     — a typed value into an 'unknown' (dyn) slot — the same
+     *               static→DOM deep copy coerceToExpected applies top-level
+     *   upcast    — a derived class instance into a base-typed slot (the
+     *               prefix-layout pointer reinterpret, no copy)
+     *   funcAdapt — a function into a slot whose signature differs only by
+     *               CLEAN mechanical conversions (cleanFuncAdaptable); the
+     *               stranded (trap-only) dispositions stay out of the plan
      * Null when the pair isn't in the relation — callers keep their fences. */
     widthLiftPlan(src: IrType, dst: IrType): WidthLift | null;
     /** True for the unit-only element types (`(null | undefined)[]`, the
@@ -972,9 +1029,11 @@ export declare class Lowerer {
      * optional-flavored field completes to its undefined arm (the
      * literal-completion rule). TUPLES width-coerce too, arity-exact (TS
      * permits no other tuple width): per-position lifts, never completion.
-     * Index-signature shapes keep the exactness fences here (the overflow
-     * CAPTURE helper owns their reshapes). Null when the shapes don't
-     * relate that way. */
+     * Index-signature SOURCES narrow here like any wider record — declared
+     * fields copy, the overflow drops with the width (missing target
+     * fields decline: the overflow could hold them). Index-signature
+     * TARGETS keep the overflow CAPTURE helper (widthCoerce's other arm).
+     * Null when the shapes don't relate that way. */
     /** The pure planning half of recordWidthHelper — every target field's
      * lift, or null when the pair isn't width-coercible. Callers that must
      * validate a WHOLE plan before interning anything (the retag helper's
@@ -988,6 +1047,14 @@ export declare class Lowerer {
     } | {
         absentDyn: true;
     }> | null;
+    /** Post-hoc classifier for SC2002's record→record residue: WHY the
+     * width family (recordWidthPlan and the overflow capture — widthCoerce's
+     * two record arms) declined this pair — the FIRST blocking rule, named.
+     * Pure description on the failure path (the site already carries the
+     * rejection): mirrors the planners' gates, never changes what coerces,
+     * and answers null when no pointed story applies (the generic message
+     * stands). */
+    describeRecordWidthBlocker(fromId: string, toId: string): string | null;
     recordWidthHelper(fromId: string, toId: string, loc: SrcLoc): string | null;
     /** Interned `%arr.width.<n>(a)` — the per-element copy loop over
      * widthLiftPlan's element lift: out = []; n = a.length; for (...)
@@ -1098,6 +1165,18 @@ export declare class Lowerer {
      * Deliberately EXCLUDES the trap-only stranded conversions — an adapter
      * that could only ever throw is a fence, not a bridge. */
     coercibleValue(src: IrType, dst: IrType): boolean;
+    /** True when a `src` function value enters a `dst` slot through
+     * funcCoerceAdapter with NO stranded (trap-only) piece: no rest packs,
+     * no surplus source params, every slot parameter converts into the
+     * wrapped function's own type, and the result converts back (a void
+     * slot drops it; a void result answers the exact JS undefined for
+     * dyn/jsval slots). The width family's func gate — widthLiftPlan
+     * bridges only signatures whose every call succeeds by construction. */
+    cleanFuncAdaptable(src: IrType & {
+        kind: "func";
+    }, dst: IrType & {
+        kind: "func";
+    }): boolean;
     /** Interned `%fn.adapt.<n>(f)` — the GENERAL function-value adapter: a
      * `fromT` function value flowing into a `toT` slot whose pieces differ
      * only by coercibleValue conversions. The slot's callers pass toT's
@@ -1583,7 +1662,7 @@ export declare class Lowerer {
         stmts: IrStmt[];
         value: IrExpr;
     };
-    lowerBindingPattern(pattern: ts.ArrayBindingPattern | ts.ObjectBindingPattern, srcRef: () => IrExpr, srcType: IrType, isLet: boolean, out: IrStmt[]): void;
+    lowerBindingPattern(pattern: ts.ArrayBindingPattern | ts.ObjectBindingPattern, srcRef: () => IrExpr, srcType: IrType, isLet: boolean, out: IrStmt[], dynSpell?: string): void;
     checkBindingElement(el: ts.BindingElement, allowDefault?: boolean): void;
     bindPatternTarget(name: ts.BindingName, value: IrExpr, isLet: boolean, out: IrStmt[]): void;
     lowerVarDeclList(list: ts.VariableDeclarationList): IrStmt | null;
@@ -1747,6 +1826,14 @@ export declare class Lowerer {
         module: string;
         member: string;
     }, fn: BuiltinModuleFn, loc: SrcLoc): IrExpr;
+    lowerFsToUnixTimestampCall(expr: ts.CallExpression, bi: {
+        module: string;
+        member: string;
+    }, loc: SrcLoc): IrExpr | null;
+    lowerFsLadderCall(expr: ts.CallExpression, bi: {
+        module: string;
+        member: string;
+    }, loc: SrcLoc): IrExpr | null;
     lowerChildArgsArg(node: ts.Expression | undefined, loc: SrcLoc): IrExpr;
     lowerSpawnSyncCall(expr: ts.CallExpression, loc: SrcLoc): IrExpr;
     lowerSpawnCall(expr: ts.CallExpression, loc: SrcLoc): IrExpr;