@yabgu_gm/tensionscript 0.13.1 → 0.14.0

package/dist/asc.generated.d.ts

@@ -6516,6 +6516,300 @@ declare module "types:tensionscript/src/builtins" {
     /** Compiles runtime type information for use by stdlib. */
     export function compileRTTI(compiler: Compiler): void;
 }
+declare module "types:tensionscript/src/dwarf/leb" {
+    /**
+     * @fileoverview LEB128 and byte writing, shared by the wasm readers and the
+     * DWARF encoder. Port of `tension-core/src/leb.rs` and the `cstr` helper in
+     * `tension-core/src/dwarf/encode.rs`.
+     * @license Apache-2.0
+     */
+    /** A growable byte sink. Rust's `Vec<u8>` has no direct counterpart here. */
+    export class ByteWriter {
+        buf: Uint8Array;
+        len: number;
+        constructor(capacity?: number);
+        private grow;
+        push(byte: number): void;
+        /** Appends `data[0..data.length]`. */
+        bytes(data: Uint8Array): void;
+        /** Appends `data[start..end]`, the Rust `extend_from_slice(&slice[a..b])`. */
+        slice(data: Uint8Array, start: number, end: number): void;
+        /** Unsigned LEB128. Values here are addresses and lengths, so 32 bits suffice. */
+        uleb(value: number): void;
+        /**
+         * Signed LEB128. Rust writes line deltas as `i64`; every value here is a
+         * source-line difference, which fits `i32`, and SLEB128's terminating
+         * condition makes the two widths encode identically for such values.
+         */
+        sleb(value: number): void;
+        u16le(value: number): void;
+        u32le(value: number): void;
+        /** A NUL-terminated UTF-8 string, the Rust `cstr`. */
+        cstr(text: string): void;
+        /** UTF-8 bytes with no terminator (a wasm name, a DWARF file path). */
+        utf8(text: string): void;
+        /** The written bytes as their own array. */
+        finish(): Uint8Array;
+    }
+}
+declare module "types:tensionscript/src/dwarf/source-map" {
+    /**
+     * @fileoverview The source-map v3 side: a purpose-built JSON reader and the
+     * mappings (base64 VLQ) decoder. Port of
+     * `tension-core/src/dwarf/source_map.rs`.
+     * @license Apache-2.0
+     */
+    /** One source-map segment: wasm file offset -> source line/column. */
+    export class Seg {
+        addr: number;
+        file: number;
+        line: number;
+        col: number;
+        constructor(addr: number, file: number, line: number, col: number);
+    }
+    export class SourceMap {
+        sources: string[];
+        segments: Seg[];
+        constructor(sources: string[], segments: Seg[]);
+    }
+    /** Decode one comma-free group of base64 VLQ digits. */
+    export function vlq(text: string): number[];
+    /**
+     * Decode `mappings`. Generated columns are absolute wasm file offsets.
+     *
+     * The source-map spec resets the generated column to 0 at each `;`-separated
+     * line group; source line, source column and file index keep accumulating
+     * across groups.
+     */
+    export function parseMappings(mappings: string, sourceCount: number): Seg[];
+    /** Read `sources` and `mappings` out of a source-map v3 document. */
+    export function parseSourceMap(json: string): SourceMap;
+}
+declare module "types:tensionscript/src/dwarf/wasm-layout" {
+    /**
+     * @fileoverview Parsing the guest module: the section walk, code bodies, the
+     * `name` section, and everything synthesis needs from all of it. Port of
+     * `tension-core/src/dwarf/wasm.rs`.
+     *
+     * D8 measured the alternative — taking function and local names from the
+     * compiler's in-memory state — and rejected it: Binaryen owns the emitted
+     * function and local indices (it renames through its own passes), and the
+     * compiler's `FunctionRef`/`Local` keys are not the emitted index space. The
+     * emitted `name` section is the only faithful source, so it is parsed here
+     * exactly as the host parses it.
+     * @license Apache-2.0
+     */
+    /** A cursor over bytes, the Rust `Reader`. */
+    export class Reader {
+        b: Uint8Array;
+        i: number;
+        constructor(b: Uint8Array, i: number);
+        u8(): number;
+        uleb(): number;
+        name(): string;
+    }
+    /**
+     * A wasm value type we can describe to a debugger. `None` is the Rust
+     * `Option<ValType>::None` — everything else (`v128`, reference types) has no
+     * DWARF base type here and is left undescribed.
+     */
+    export enum ValType {
+        None = -1,
+        I32 = 0,
+        I64 = 1,
+        F32 = 2,
+        F64 = 3
+    }
+    export function valTypeFromByte(b: number): ValType;
+    export function valTypeName(ty: ValType): string;
+    /** `DW_AT_encoding`: signed integer or IEEE float. */
+    export function valTypeEncoding(ty: ValType): number;
+    export function valTypeByteSize(ty: ValType): number;
+    /** A body's `[start, end)` file offsets. */
+    export class BodyRange {
+        start: number;
+        end: number;
+        constructor(start: number, end: number);
+    }
+    /** One `(count, valtype)` local-declaration group. */
+    export class LocalDecl {
+        count: number;
+        ty: number;
+        constructor(count: number, ty: number);
+    }
+    /** A local in index order: name, index, value type (null when undescribable). */
+    export class LocalInfo {
+        name: string;
+        index: number;
+        ty: ValType;
+        constructor(name: string, index: number, ty: ValType);
+    }
+    /** A `name` section entry. */
+    export class NamedEntry {
+        index: number;
+        name: string;
+        constructor(index: number, name: string);
+    }
+    /** A local-name entry: function index, local index, name. */
+    export class LocalNameEntry {
+        func: number;
+        index: number;
+        name: string;
+        constructor(func: number, index: number, name: string);
+    }
+    /** A `(params, results)` function type, as valtype bytes. */
+    export class FuncType {
+        params: number[];
+        results: number[];
+        constructor(params: number[], results: number[]);
+    }
+    /** What the synthesizer must learn from the guest module itself. */
+    export class Layout {
+        /** File offset of the code section payload: DWARF address 0. */
+        codePayloadStart: number;
+        /** Payload size; also the exclusive end of the address space. */
+        codePayloadSize: number;
+        /** Body content `[start, end)` in file offsets, one per defined function. */
+        bodies: BodyRange[];
+        /** Body local declarations, parallel to `bodies`. */
+        bodyDecls: LocalDecl[][];
+        /** Functions declared in the import section; the index space starts there. */
+        importedFuncs: number;
+        /** `name` section function names by function index. */
+        names: NamedEntry[];
+        /** `name` section local names: function index, local index, name. */
+        localNames: LocalNameEntry[];
+        /** Function type indices from the function section, one per defined function. */
+        funcTypes: number[];
+        /** Function types from the type section. */
+        types: FuncType[];
+        /** Name of the function defined by body `i`, if the guest kept names. */
+        nameForBody(body: number): string | null;
+        /**
+         * A guest local in index order: the function's parameters first, then the
+         * body's declarations. `name` is what `asc --debug` kept in the `name`
+         * section (subsection 2) when present, else a fallback.
+         */
+        localsForBody(body: number): LocalInfo[];
+        private localName;
+    }
+    /** The two parallel arrays `readCodeBodies` produces. */
+    export class CodeBodies {
+        bodies: BodyRange[];
+        decls: LocalDecl[][];
+    }
+    /** Walk the module and collect everything synthesis needs. */
+    export function parseLayout(wasm: Uint8Array): Layout;
+}
+declare module "types:tensionscript/src/dwarf/encode" {
+    /**
+     * @fileoverview The DWARF 4 encoder: abbreviations, the line program,
+     * `.debug_info` DIEs, and the custom-section wrapper. Port of
+     * `tension-core/src/dwarf/encode.rs`.
+     * @license Apache-2.0
+     */
+    import { ByteWriter } from "types:tensionscript/src/dwarf/leb";
+    import { Seg } from "types:tensionscript/src/dwarf/source-map";
+    import { LocalInfo, ValType } from "types:tensionscript/src/dwarf/wasm-layout";
+    /** One subprogram: its name and payload-relative `[lo, hi)` address. */
+    export class FunctionRange {
+        name: string;
+        lo: number;
+        hi: number;
+        constructor(name: string, lo: number, hi: number);
+    }
+    /** A payload-relative `[start, end)` interval. */
+    export class Range {
+        start: number;
+        end: number;
+        constructor(start: number, end: number);
+    }
+    /**
+     * Abbrev 1: compile unit. Abbrev 2: subprogram. Abbrev 3: subprogram with
+     * children. Abbrev 4: base type. Abbrev 5: variable. No `strp`, so no
+     * `.debug_str`; type references are `DW_FORM_ref4` within the unit.
+     */
+    export function encodeDebugAbbrev(): Uint8Array;
+    /**
+     * Turn an AssemblyScript source-map path into one the symbol root resolves.
+     * `asc` writes library sources as `~lib/...`, which no debugger understands.
+     *
+     * The Rust original also probes the filesystem and prefers
+     * `node_modules/assemblyscript/std/assembly/...` when that directory exists.
+     * The compiler has no filesystem access, so the probe collapses to the
+     * fallback branch - which is what the host produced for the baseline fixture
+     * (neither probed path exists in a TensionScript project: the package ships
+     * its stdlib as `@yabgu_gm/tensionscript/std/assembly`).
+     */
+    export function sourcePath(raw: string, compDir: string): string;
+    /**
+     * A DWARF v4 line program. `rows` must be sorted ascending by address.
+     * `ranges` are the payload-relative body ranges, one line sequence each.
+     */
+    export function encodeDebugLine(compDir: string, sources: string[], rows: Seg[], ranges: Range[]): Uint8Array;
+    /**
+     * One `DW_TAG_subprogram` per defined function the name section knows about,
+     * and one `DW_TAG_variable` child per wasm local whose type we can describe.
+     * `locals` is parallel to `functions`.
+     */
+    export function encodeDebugInfo(moduleName: string, compDir: string, functions: FunctionRange[], locals: LocalInfo[][]): Uint8Array;
+    /** Position of a `ValType` in the base-type DIE order, for `typeOffsets`. */
+    export function typeIndex(ty: ValType): number;
+    /**
+     * Append a custom section to `out`: id, size, name length, name, payload -
+     * where `size` counts everything after itself.
+     */
+    export function appendCustom(out: ByteWriter, name: string, payload: Uint8Array): void;
+}
+declare module "types:tensionscript/src/dwarf/index" {
+    /**
+     * @fileoverview DWARF synthesis for TensionScript guests, compiler side.
+     *
+     * Port of `tension-core/src/dwarf/mod.rs` (`synthesize`) and the module
+     * comment that explains it. The host rebuilt this from a guest's `name`
+     * section and source map because `asc` emitted no DWARF; the compiler now
+     * carries the same code, so a guest ships its own `.debug_*` sections.
+     *
+     * Address convention (measured, not assumed): a guest DWARF code address is a
+     * byte offset from the start of the code section payload - address 0 is the
+     * first byte of the function-count LEB.
+     *
+     * The encoder is a verbatim port, including the range-splitting rule: the
+     * compile unit's `DW_AT_ranges` entries are intervals between line rows, not
+     * whole bodies, because cranelift emits a function's natives in an order that
+     * is not monotonic in wasm addresses. Its range translation only sees the
+     * ranges active at an entry's start and end addresses, so a whole-body entry
+     * hides any internal range that begins and ends strictly inside it, and lldb
+     * drops line rows that fall in the resulting holes.
+     * @license Apache-2.0
+     */
+    /** What synthesis produced, for the caller's diagnostics. */
+    export class SynthesisResult {
+        bytes: Uint8Array;
+        files: number;
+        rows: number;
+        functions: number;
+        locals: number;
+        dropped: number;
+        constructor(bytes: Uint8Array, files: number, rows: number, functions: number, locals: number, dropped: number);
+    }
+    /**
+     * Copy `wasm` with synthesized `.debug_abbrev`, `.debug_info`, `.debug_line`
+     * and `.debug_ranges` appended: line tables for source breakpoints, function
+     * DIEs for the call stack, and variable DIEs for locals.
+     *
+     * `compDir` becomes the DWARF compile directory and the base for every
+     * file-table entry. `moduleName` becomes the unit's `DW_AT_name`.
+     *
+     * Throws `Error` on malformed input. The Rust original returned
+     * `Result<_, String>`; a throw is the idiomatic equivalent here, and the
+     * caller decides whether a failed synthesis is fatal (the compiler treats it
+     * as a warning and emits the undecorated module).
+     */
+    export function synthesize(wasm: Uint8Array, sourceMapJson: string, compDir: string, moduleName: string): Uint8Array;
+    /** `synthesize` plus the counts the host used to log. */
+    export function synthesizeVerbose(wasm: Uint8Array, sourceMapJson: string, compDir: string, moduleName: string): SynthesisResult;
+}
 declare module "types:tensionscript/src/module" {
     /**
      * @fileoverview A thin wrapper around Binaryen's C-API.
@@ -7900,7 +8194,16 @@ declare module "types:tensionscript/src/module" {
         optimize(optimizeLevel: number, shrinkLevel: number, debugInfo?: boolean, zeroFilledMemory?: boolean): void;
         validate(): boolean;
         interpret(): void;
-        toBinary(sourceMapUrl?: string | null): BinaryModule;
+        /**
+         * Emits the module.
+         *
+         * When `debugInfo` is set *and* a source map is requested, the emitted bytes
+         * gain synthesized DWARF (`.debug_abbrev`, `.debug_info`, `.debug_line`,
+         * `.debug_ranges`) - the same sections `tension-core` used to rebuild from
+         * the guest's source map. A host that already ships DWARF (a C or Rust
+         * guest) is unaffected: this only decorates a module this compiler emits.
+         */
+        toBinary(sourceMapUrl?: string | null, debugInfo?: boolean, compDir?: string, moduleName?: string): BinaryModule;
         toText(watFormat?: boolean): string;
         private cachedStringsToPointers;
         private cachedPointersToStrings;
@@ -11333,25 +11636,75 @@ declare module "types:tensionscript/src/compiler" {
          * Compiles an array literal into one operand per element leaf, starting at
          * `at`, and returns how many were written.
          *
-         * Shared by the call site (`expandSroaArrayArgument`) and the return
-         * (`compileMultivalueReturnStatement`) so the two positions accept the same
-         * shapes and refuse the same ones by the same rule, instead of by two copies
-         * of it. `verb` is `"passing"` or `"returning"` — the only word the two
-         * refusals disagree on.
-         *
-         * Three rules:
-         *
-         * - A **record element** is several leaves and no literal names them, so it is
-         *   refused by name; building the array field-by-field in a local is the
-         *   working route in both positions.
-         * - A **short** literal zero-fills. The slot exists either way, and a WASM
-         *   operand cannot be left out.
-         * - A **long** literal is an arity error rather than a write past the operand
-         *   block — `sum([1, 2, 3, 4, 5])` into a `[u32 * 4]` parameter reached
-         *   Binaryen with five operands for four slots and crashed the compiler, so
-         *   this bound is a guard, not a formality.
+         * The operand sink of `emitSroaArrayLiteralLeaves`: the walk yields the leaves
+         * and this places them, then fills any element the literal omitted — a WASM
+         * operand cannot be left out, even when a local could (`fillSroaArrayFromLiteral`,
+         * where zero is free).
          */
         private pushSroaArrayLiteralOperands;
+        /**
+         * Compiles an array literal into one **leaf expression per leaf**, appended to
+         * `leaves` in element-major order.
+         *
+         * **The one array-literal element walk.** Three positions use it: the call site
+         * (`pushSroaArrayLiteralOperands`), the return
+         * (`compileMultivalueReturnStatement`), and the local declaration
+         * (`fillSroaArrayFromLiteral`). A value-form array's elements are leaves, and
+         * the positions differ only in what they do with them — push operands, make a
+         * tuple, or `local.set` — so the rules for *reading* a literal live here once.
+         *
+         * `verb` is `"passing"`, `"returning"` or `"initializing"`; it only chooses
+         * the wording of the refusals.
+         *
+         * The elements a literal omits are **not** produced here: a WASM local starts
+         * at zero, so a local declaration needs no stores for them, while an argument
+         * or a return needs an operand and the caller fills it (`makeZero` per leaf
+         * type). Two different destinations, one walk.
+         *
+         * A **long** literal is an arity error rather than a write past the leaf
+         * block — `sum([1, 2, 3, 4, 5])` into a `[u32 * 4]` parameter reached Binaryen
+         * with five operands for four slots and crashed the compiler, so this bound is
+         * a guard, not a formality.
+         *
+         * A **record** element is several leaves, so it is read one leaf per field: an
+         * object literal (`{ x: 1.5, y: 2.5 }`) compiles straight to them
+         * (`emitSroaObjectElementLeaves`), and anything else — a record local, a call —
+         * is refused by name, because a local there is a pointer, not the leaves.
+         */
+        private emitSroaArrayLiteralLeaves;
+        /**
+         * Compiles one **object literal** element of a `[T * N]` array literal into
+         * that element's field leaves, in declaration order.
+         *
+         * `{ x: 10.5, y: 20.5 }` is the natural way to write a record element, and for
+         * an `@unmanaged struct` it can be compiled straight to leaves — no heap
+         * record, no constructor, no pointer. The class path (`compileObjectLiteral`)
+         * cannot be reused for it: that one requires a class, takes a temp local of
+         * that class, and returns one reference, because it has to produce an
+         * *address*. Measured on the same spelling: `const p: P = { x: 10.5 }` emits
+         * `P#constructor` plus `__alloc(16)` and setters — a heap record, not a value.
+         *
+         * Policies, each measured against the class path so the two spellings agree:
+         *
+         * - **Declaration order.** Fields are emitted in the record's declaration
+         *   order, not the literal's, because the leaves are positional.
+         * - **Last duplicate wins** — `{ x: 1.0, x: 2.0 }` is `2.0`, as measured for
+         *   `const p: P = { x: 1.0, x: 2.0 }`.
+         * - **An unknown name is an error** at the name, matching
+         *   `compileObjectLiteral`'s `TS2339`.
+         * - **An omitted field takes its declared default**, matching the constructor
+         *   the class path runs: measured, `{ x: 10.0 }` on `{ x = 5.0; y = 7.0 }`
+         *   yielded `y = 7.0`, not `0`. Only a **constant** default is reproduced
+         *   here; one that needs the record instance (`y = this.x * 2.0`) is refused
+         *   by name, because a leaf emission has no instance to evaluate it against.
+         * - **A field left with no default is zero**, matching `{ x: 3.0 }` on a record
+         *   with no initialisers (measured: `y` came back `0`).
+         *
+         * A **nested** field (an `@inline struct` inside the record) is refused: its
+         * value is a second set of leaves behind a second object literal, which is the
+         * recursion this landing does not carry.
+         */
+        private emitSroaObjectElementLeaves;
         private expandSroaArgument;
         /**
          * The SROA local an expression names, or `null`.
@@ -11377,6 +11730,18 @@ declare module "types:tensionscript/src/compiler" {
          * carrying its own map, so the walk descends through it.
          */
         private pushSroaLeafOperands;
+        /**
+         * Collects a `fieldLocals` tree's leaves into `out`, depth first.
+         *
+         * **The one definition of leaf order.** A nested value is a placeholder
+         * (index `-1`) carrying its own map, so the walk descends through it rather
+         * than yielding it. Every emitter that needs "the leaves of this value, in
+         * order" goes through here — `pushSroaLeafOperands` for call operands, the
+         * array-literal walk for literal elements, the local binder for stores — so
+         * order is stated once instead of re-derived per site. It must agree with
+         * `Signature.leafTypesOf`, which is the type-level twin.
+         */
+        private collectSroaLeafLocals;
         private resolveSroaReceiver;
         /** Size of the static call-temp region, in bytes. 4 KB is 256 slots at the
          *  16-byte fixture record size. Overflow aborts (see `makeSretCallBlock`);
@@ -11688,14 +12053,18 @@ declare module "types:tensionscript/src/compiler" {
         /**
          * Stores an array literal's elements into a value-form array's leaves.
          *
-         * A scalar element is compiled straight into its leaf. A **record** element is
-         * several leaves and a literal cannot name them one at a time, so it is
-         * refused by name here rather than compiled: the object-literal spelling
-         * (`{ x: 1.5, y: 2.5 }`) goes through the class path and *allocates* — measured,
-         * `const p: P = { x: 1.5 }` emitted `P#constructor` plus setters and needed
-         * `env.abort`, i.e. a heap record behind a pointer, which is not a value.
-         * Initialising the elements field by field (`arr[0].x = 10.5`) is the working
-         * route, and it is what the diagnostic says.
+         * The **local-declaration sink** of `emitSroaArrayLiteralLeaves`: the walk
+         * yields one expression per leaf in element-major order, and this local's
+         * leaves were created in the same order (`fillSroaArrayLocals` keys them
+         * `"0"`, `"1"`, ...), so the two line up positionally and a `local.set` per
+         * pair is the whole job. No zero-fill: a WASM local starts at zero, so an
+         * omitted element needs no store — which is why the walk does not produce one.
+         *
+         * A scalar element is one leaf. A **record** element is several, and the walk
+         * refuses it by name: the object-literal spelling (`{ x: 1.5, y: 2.5 }`) goes
+         * through the class path and *allocates* — measured, `const p: P = { x: 1.5 }`
+         * emitted `P#constructor` plus setters and needed `env.abort`, i.e. a heap
+         * record behind a pointer, which is not a value.
          */
         private fillSroaArrayFromLiteral;
         /**
@@ -12688,6 +13057,14 @@ declare module "types:tensionscript/src/index-wasm" {
     /** Sets the `pedantic` option. */
     export function setPedantic(options: Options, pedantic: boolean): void;
     export function setDebugInfo(options: Options, debug: boolean): void;
+    /**
+     * Appends synthesized DWARF (`.debug_abbrev`, `.debug_info`, `.debug_line`,
+     * `.debug_ranges`) to an emitted module and returns the augmented bytes.
+     *
+     * Exposed for hosts that emit through Binaryen's own writer rather than
+     * `Module#toBinary` - the CLI does exactly that. See `src/dwarf/`.
+     */
+    export function synthesizeDwarf(wasmBytes: Uint8Array, sourceMapJson: string, compDir: string, moduleName: string): Uint8Array;
     /**
      * Runs the compiler's own in-tree `afterParse` transforms (closure lowering,
      * then async lowering) over a program.