@yabgu_gm/tensionscript 0.13.2 → 0.14.0

package/dist/assemblyscript.generated.d.ts

@@ -8075,6 +8075,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.
@@ -9459,7 +9753,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;
@@ -12688,6 +12991,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.