numbl 0.4.21 → 0.4.22

package/dist-lib/numbl-core/jit/workspace/driverPrologue.d.ts

@@ -1,59 +0,0 @@
-/**
- * Driver-script prologue extractor.
- *
- * mtoc2 accepts `addpath(<literal>, ...)` only as a leading sequence
- * of top-level statements in the driver script. Each call is parsed
- * into a list of directory arguments (literal strings only) plus an
- * optional trailing `-begin` / `-end` flag.
- *
- * Two call sites:
- *  - The CLI invokes the extractor before scanning the filesystem so
- *    it knows which directories to fold into the workspace search
- *    path.
- *  - `translateProject` / the interpreter run path invoke it purely
- *    to drop the prologue statements from the driver AST before
- *    lowering / execution begins. The dirs are ignored there.
- *
- * The two calls are idempotent: same input AST → same dirs and
- * remaining body, so it doesn't matter that they parse twice.
- *
- * Any `addpath` left in the AST (anywhere outside the leading prefix)
- * still hits the `addpath` builtin's `transfer`, which errors with a
- * span-attributed message. `rmpath` / `savepath` are always rejected
- * by their own `transfer` hooks; the extractor never accepts them.
- *
- * Function-file auto-invoke: a driver whose body (after the prologue)
- * contains only function/classdef definitions and no top-level
- * statements is a "function file" — running it means calling its
- * first function with zero arguments. The extractor appends a
- * synthesized 0-arg call so every execution path (interpreter,
- * js-aot, c-aot) treats it the same way. Mirrors numbl's
- * `Interpreter.run` (interpreter.ts).
- */
-import type { AbstractSyntaxTree, Stmt, Span } from "../parser/index.js";
-export interface AddPathDir {
-    /** Directory string as the user wrote it. Relative paths are NOT
-     *  resolved here; callers resolve against `process.cwd()`. */
-    dir: string;
-    /** Whether the directory inserts at the front of the addpath block
-     *  (default / `-begin`) or after the CLI `--path` dirs at the end
-     *  (`-end`). */
-    position: "begin" | "end";
-    /** Span of the originating `addpath(...)` call. */
-    span: Span;
-}
-export interface DriverPrologueOpts {
-    /** Set to `true` when a filesystem is available to resolve dirs
-     *  against (CLI). When `false` or omitted (web IDE, in-memory
-     *  translate, vitest), any leading `addpath` call is itself an
-     *  `UnsupportedConstruct`. */
-    allowAddpath?: boolean;
-}
-export interface DriverPrologueResult {
-    addpaths: AddPathDir[];
-    /** Top-level statements after the prologue. Suitable for direct
-     *  use with `Lowerer.lowerProgram` (via a shallow AST copy with
-     *  this `body`) or `Interpreter.runProgram`. */
-    remainingBody: Stmt[];
-}
-export declare function extractDriverPrologue(ast: AbstractSyntaxTree, opts?: DriverPrologueOpts): DriverPrologueResult;

package/dist-lib/numbl-core/jit/workspace/mtoc2UserFunctionLoader.d.ts

@@ -1,62 +0,0 @@
-/**
- * Loader for `.mtoc2.js` user functions.
- *
- * A `.mtoc2.js` file is plain JavaScript with no mtoc2 dependency.
- * The loader evaluates it as a CommonJS-style module (`exports` and
- * `module.exports` are the only injected names) and reads four
- * exports to assemble a workspace-scoped `Builtin`:
- *
- *   exports.name      — string, must match the file's basename.
- *   exports.transfer  — (argTypes, nargout) -> Type[]. Raw mtoc2 Type
- *                       objects in, raw Type objects out. Throws
- *                       `Error` on bad input.
- *   exports.emit      — ({argsC, prefix, ...}) -> string. C expression
- *                       for the call. Use `prefix` to name any private
- *                       C helpers (kept collision-free across files).
- *   exports.cBody     — ({prefix}) -> string. C source (helper
- *                       function definitions) injected once per
- *                       translation unit. Use the same `prefix` as
- *                       `emit`.
- *   exports.cHeaders? — string[] of additional `#include` lines to
- *                       activate (optional).
- *
- * Prefix shape: `mtoc2_user_<safe_funcname>__<8hex>__` where the hex
- * is the FNV-1a hash of the workspace-relative file path. Including
- * the path in the hash makes the prefix unique across all `.mtoc2.js`
- * files in the workspace, even if two files happen to define
- * functions with overlapping internal names.
- */
-import type { Builtin } from "../builtins/registry.js";
-/** Resolved sibling file: the relative path (used by the build to
- *  pick a unique on-disk name) plus the file's text. */
-export interface ResolvedCSource {
-    /** Path as written by the user in `exports.cSources` (e.g.
-     *  `"impl.c"` or `"sub/helpers.h"`). */
-    relPath: string;
-    /** File text the build will write to disk. */
-    source: string;
-}
-/** Loader output: the assembled `Builtin` plus the user-supplied C
- *  sibling files the framework needs to thread through to the build
- *  pipeline. */
-export interface LoadedUserFunction {
-    builtin: Builtin;
-    cSources: ResolvedCSource[];
-}
-/** Evaluate a `.mtoc2.js` file and return its assembled `Builtin`
- *  plus the user-supplied sibling C files (`cSources`).
- *
- *  - `fileName` — the .mtoc2.js's full path (used for diagnostics and
- *    to resolve sibling paths).
- *  - `expectedName` — what numbl's workspace registered the file
- *    under (derived from the file's basename / package path); we
- *    validate the user's `exports.name` matches so a typo / rename
- *    surfaces here rather than at the first call site.
- *  - `relPath` — workspace-relative path used for the prefix hash.
- *  - `readSibling(p)` — given a path-key relative to the .mtoc2.js's
- *    directory, return the sibling file's source text. Used to pull
- *    `cSources` entries out of the workspace's file map (which is
- *    the same regardless of CLI vs web IDE). Returns `undefined` if
- *    the file is not in the workspace; the loader throws a clear
- *    error pointing at the missing path. */
-export declare function loadMtoc2UserFunction(fileName: string, source: string, expectedName: string, relPath: string, readSibling: (siblingRelPath: string) => string | undefined): LoadedUserFunction;

package/dist-lib/numbl-core/native/bridge-resolve.d.ts

@@ -1,14 +0,0 @@
-/**
- * Centralized LAPACK bridge resolution with fallback and one-time logging.
- *
- * Tries the native bridge first; falls back to ts-lapack (pure TypeScript).
- */
-import { type LapackBridge } from "./lapack-bridge.js";
-/**
- * Get the effective LAPACK bridge for a given operation.
- *
- * @param opName  Operation name for logging (e.g. "inv", "qr")
- * @param method  Optional method to check on native bridge. If native bridge
- *                lacks this method, falls back to ts-lapack.
- */
-export declare function getEffectiveBridge(opName: string, method?: keyof LapackBridge): LapackBridge;

package/dist-lib/numbl-core/runtime/plotUtils.d.ts

@@ -1,336 +0,0 @@
-/**
- * Utilities for parsing plot() arguments at runtime.
- *
- * Handles: plot(Y), plot(X,Y), plot(X1,Y1,...,Xn,Yn),
- * plot(X1,Y1,LineSpec1,...), and Name-Value pairs like 'Color','r','LineWidth',2.
- */
-import { type RuntimeValue } from "./types.js";
-export type { PlotTrace, Plot3Trace, PatchTrace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace, Quiver3Trace, } from "../../graphics/types.js";
-import type { PlotTrace, Plot3Trace, PatchTrace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace, Quiver3Trace } from "../../graphics/types.js";
-export declare function resolveColor(v: RuntimeValue | string): [number, number, number] | undefined;
-export interface ParsedLineSpec {
-    color?: string;
-    lineStyle?: string;
-    marker?: string;
-}
-export declare function parsePlotArgs(args: RuntimeValue[]): PlotTrace[];
-/**
- * Parse plot3() arguments.
- *
- * Supported forms:
- *   plot3(X, Y, Z)
- *   plot3(X, Y, Z, LineSpec)
- *   plot3(X1,Y1,Z1,...,Xn,Yn,Zn)
- *   plot3(X1,Y1,Z1,LineSpec1,...,Xn,Yn,Zn,LineSpecn)
- *   plot3(..., Name, Value)
- */
-export declare function parsePlot3Args(args: RuntimeValue[]): Plot3Trace[];
-/** Result of parsing line() arguments: a set of 2-D or 3-D traces. */
-export type ParsedLine = {
-    kind: "2d";
-    traces: PlotTrace[];
-} | {
-    kind: "3d";
-    traces: Plot3Trace[];
-};
-/**
- * Parse line() arguments.
- *
- * Supported forms:
- *   line                                  — line from (0,0) to (1,1)
- *   line(x, y)                            — 2-D line(s)
- *   line(x, y, z)                         — 3-D line(s)
- *   line(___, Name, Value)               — Color/LineStyle/LineWidth/Marker/...
- *   line('XData', x, 'YData', y, ...)    — low-level form (black line)
- *   line(ax, ___)                        — leading axes handle (ignored)
- *
- * Like plot/plot3, vector inputs make a single line and matrix inputs make one
- * line per column.
- */
-export declare function parseLineArgs(args: RuntimeValue[]): ParsedLine;
-/** Apply a single patch property (lower-cased key) to the trace. Shared by the
- *  Name-Value, struct, and `set`/handle paths. */
-export declare function applyPatchProp(trace: PatchTrace, key: string, val: RuntimeValue): void;
-/**
- * Parse patch() arguments into a canonical PatchTrace.
- *
- * Supported forms:
- *   patch(X, Y, C)                              — 2-D polygons, color C
- *   patch(X, Y, Z, C)                           — 3-D polygons
- *   patch('XData', X, 'YData', Y[, 'ZData', Z]) — coords as name-value
- *   patch('Faces', F, 'Vertices', V)            — faces/vertices model
- *   patch(S)                                    — struct of patch properties
- *   patch(___, Name, Value)                     — patch properties
- *   patch(ax, ___)                              — leading axes handle (ignored)
- */
-export declare function parsePatchArgs(args: RuntimeValue[]): PatchTrace;
-/**
- * Parse fill() arguments into one patch trace per (X,Y,C) group. fill is the
- * 2-D coordinate form of patch repeated over groups, so it reuses the patch
- * vertex/color/property helpers — the only fill-specific logic is splitting
- * the argument list into X,Y,C triplets.
- *
- * Supported forms:
- *   fill(X, Y, C)
- *   fill(X1, Y1, C1, ..., Xn, Yn, Cn)
- *   fill(___, Name, Value)
- *   fill(ax, ___)
- */
-export declare function parseFillArgs(args: RuntimeValue[]): PatchTrace[];
-/**
- * Parse trimesh() arguments into a canonical PatchTrace.
- *
- * trimesh draws a triangular mesh and (per the MATLAB docs) returns a patch
- * object, so it maps onto the PatchTrace model: the connectivity matrix T
- * supplies the faces (one triangle per row, 1-based vertex indices) and the
- * x/y[/z] vectors supply the vertices.
- *
- * Supported forms:
- *   trimesh(T, x, y)              — 2-D triangular mesh
- *   trimesh(T, x, y, z)           — 3-D triangular mesh
- *   trimesh(T, x, y, z, c)        — c is per-vertex color data
- *   trimesh(TO)                   — triangulation object (struct exposing
- *                                   ConnectivityList + Points)
- *   trimesh(___, Name, Value)     — patch properties
- *   trimesh(ax, ___)              — leading axes handle (ignored)
- */
-export declare function parseTriMeshArgs(args: RuntimeValue[]): PatchTrace;
-/**
- * Parse surf() arguments.
- *
- * Supported forms:
- *   surf(Z)           — Z is m×n, X = 1:n, Y = 1:m
- *   surf(Z, C)        — Z is m×n, C is m×n color data
- *   surf(X, Y, Z)     — X, Y, Z are m×n matrices (or X is 1×n / Y is m×1)
- *   surf(X, Y, Z, C)  — with explicit color data
- *   surf(..., Name, Value) — name-value pairs
- */
-export declare function parseSurfArgs(args: RuntimeValue[]): SurfTrace;
-/**
- * Parse pcolor() arguments.
- *
- * Supported forms:
- *   pcolor(C)         — C is m×n, X = 1:n, Y = 1:m
- *   pcolor(X, Y, C)   — X, Y, C are m×n matrices (or X is 1×n / Y is m×1)
- *   pcolor(..., Name, Value) — name-value pairs (EdgeColor, FaceAlpha)
- */
-export declare function parsePcolorArgs(args: RuntimeValue[]): PcolorTrace;
-/**
- * Parse scatter() arguments.
- *
- * Supported forms:
- *   scatter(X, Y)
- *   scatter(X, Y, sz)
- *   scatter(X, Y, sz, c)
- *   scatter(X, Y, ..., 'filled')
- *   scatter(X, Y, ..., mkr)
- *   scatter(X, Y, ..., Name, Value)
- */
-export declare function parseScatterArgs(args: RuntimeValue[]): PlotTrace[];
-/**
- * Parse imagesc() arguments.
- *
- * Supported forms:
- *   imagesc(C)         — C is m×n matrix
- *   imagesc(x, y, C)   — x and y are vectors defining axis limits
- */
-export declare function parseImagescArgs(args: RuntimeValue[]): ImagescTrace;
-/**
- * Parse contour()/contourf() arguments.
- *
- * Supported forms:
- *   contour(Z)
- *   contour(Z, N)
- *   contour(X, Y, Z)
- *   contour(X, Y, Z, N)
- *   contour(..., Name, Value)
- */
-export declare function parseContourArgs(args: RuntimeValue[], filled: boolean): ContourTrace;
-/** Result of computing contour geometry: the MATLAB contour matrix `C`
- *  (column-major `2 × n` data) plus the level list actually used. */
-export interface ContourMatrix {
-    /** Column-major `2 × n` data for a `RTV.tensor(data, [2, n])`. */
-    data: number[];
-    n: number;
-    levelList: number[];
-}
-/** Compute the MATLAB contour matrix for a parsed contour trace via marching
- *  squares. Each marching-squares segment is emitted as its own two-vertex
- *  contour line (header `[level; 2]` followed by the two `[x; y]` vertices) —
- *  a valid contour matrix whose geometry matches MATLAB's connected polylines
- *  segment-for-segment. */
-export declare function computeContourMatrix(trace: ContourTrace): ContourMatrix;
-/**
- * Parse mesh() arguments — same as surf but with different default rendering.
- */
-export declare function parseMeshArgs(args: RuntimeValue[]): SurfTrace;
-/**
- * Parse bar() arguments.
- *
- * Supported forms:
- *   bar(Y)             — Y values with x = 1:length(Y)
- *   bar(X, Y)          — explicit X positions
- *   bar(..., width)     — relative bar width (scalar 0–1)
- *   bar(..., color)     — single-char color spec
- */
-export declare function parseBarArgs(args: RuntimeValue[]): BarTrace[];
-/**
- * Parse barh() arguments — same forms as bar() but rendered horizontally.
- *
- * Supported forms:
- *   barh(Y)             — Y values (bar lengths) with positions = 1:length(Y)
- *   barh(X, Y)          — explicit positions X, bar lengths Y
- *   barh(..., width)    — relative bar thickness (scalar 0–1)
- *   barh(..., color)    — single-char color spec
- */
-export declare function parseBarHArgs(args: RuntimeValue[]): BarTrace[];
-/**
- * Parse bar3() / bar3h() arguments.
- *
- * Supported forms:
- *   bar3(Z)             — Z values with y = 1:m, x = 1:n
- *   bar3(Y, Z)          — explicit Y positions
- *   bar3(..., width)    — relative bar width (scalar 0–1)
- *   bar3(..., color)    — single-char color spec
- */
-export declare function parseBar3Args(args: RuntimeValue[]): Bar3Trace;
-/**
- * Parse stairs() arguments — same forms as plot() but with staircase-transformed coordinates.
- *
- * Supported forms:
- *   stairs(Y)
- *   stairs(X, Y)
- *   stairs(..., LineSpec)
- *   stairs(..., Name, Value)
- */
-export declare function parseStairsArgs(args: RuntimeValue[]): PlotTrace[];
-/**
- * Parse errorbar() arguments.
- *
- * Supported forms:
- *   errorbar(y, err)                    — symmetric vertical
- *   errorbar(x, y, err)                 — symmetric vertical with explicit x
- *   errorbar(x, y, neg, pos)            — asymmetric vertical
- *   errorbar(x, y, yneg, ypos, xneg, xpos) — both axes
- *   errorbar(..., LineSpec)
- */
-export declare function parseErrorBarArgs(args: RuntimeValue[]): ErrorBarTrace[];
-/**
- * Parse area() arguments.
- *
- * Supported forms:
- *   area(Y)              — fill under Y with x = 1:length(Y)
- *   area(X, Y)           — explicit X
- *   area(..., basevalue)  — scalar baseline (default 0)
- *   area(..., Name, Value)
- *
- * Returns { traces, baseValue }.
- */
-export declare function parseAreaArgs(args: RuntimeValue[]): {
-    traces: PlotTrace[];
-    baseValue: number;
-};
-/**
- * Parse scatter3() arguments.
- *
- * Supported forms:
- *   scatter3(X, Y, Z)
- *   scatter3(X, Y, Z, S)
- *   scatter3(X, Y, Z, S, C)
- *   scatter3(..., 'filled')
- *   scatter3(..., markertype)
- */
-export declare function parseScatter3Args(args: RuntimeValue[]): Plot3Trace[];
-/**
- * Parse histogram() arguments.
- *
- * Supported forms:
- *   histogram(X)
- *   histogram(X, nbins)
- *   histogram(X, edges)
- */
-export declare function parseHistogramArgs(args: RuntimeValue[]): BarTrace[];
-/**
- * Parse histogram2() arguments.
- *
- * Supported forms:
- *   histogram2(X, Y)
- *   histogram2(X, Y, nbins)        — nbins is scalar or [nx, ny]
- *   histogram2(X, Y, Xedges, Yedges)
- */
-export declare function parseHistogram2Args(args: RuntimeValue[]): Bar3Trace;
-/**
- * Parse boxchart() arguments.
- *
- * Supported forms:
- *   boxchart(ydata)           — one box per column of ydata
- *   boxchart(xgroupdata, ydata) — group ydata by unique values in xgroupdata
- */
-export declare function parseBoxchartArgs(args: RuntimeValue[]): BoxTrace[];
-/**
- * Parse swarmchart() arguments.
- *
- * Supported forms:
- *   swarmchart(x, y)
- *   swarmchart(x, y, sz)
- *   swarmchart(x, y, sz, c)
- *   swarmchart(..., 'filled')
- *   swarmchart(..., markertype)
- */
-export declare function parseSwarmchartArgs(args: RuntimeValue[]): PlotTrace[];
-/**
- * Parse swarmchart3() arguments.
- *
- * Supported forms:
- *   swarmchart3(x, y, z)
- *   swarmchart3(x, y, z, sz)
- *   swarmchart3(x, y, z, sz, c)
- *   swarmchart3(..., 'filled')
- *   swarmchart3(..., markertype)
- */
-export declare function parseSwarmchart3Args(args: RuntimeValue[]): Plot3Trace[];
-/**
- * Parse piechart() / donutchart() arguments.
- *
- * Supported forms:
- *   piechart(data)
- *   piechart(data, names)
- *
- * @param innerRadius 0 for pie, >0 for donut
- */
-export declare function parsePiechartArgs(args: RuntimeValue[], innerRadius: number): PieTrace;
-/**
- * Parse heatmap() arguments.
- *
- * Supported forms:
- *   heatmap(cdata)                — matrix of values
- *   heatmap(xvalues, yvalues, cdata) — with axis labels
- */
-export declare function parseHeatmapArgs(args: RuntimeValue[]): HeatmapTrace;
-/**
- * Parse quiver() arguments.
- *
- * Supported forms:
- *   quiver(U, V)
- *   quiver(X, Y, U, V)
- *   quiver(..., scale)        — scale: nonnegative number or 'off'
- *   quiver(..., LineSpec)
- *   quiver(..., LineSpec, 'filled')
- *   quiver(..., Name, Value)  — Color, LineStyle, LineWidth, ShowArrowHead, etc.
- *
- * X, Y, U, V can be vectors or matrices. If U,V are matrices and X,Y are
- * vectors, X and Y are expanded to a meshgrid.
- */
-export declare function parseQuiverArgs(args: RuntimeValue[]): QuiverTrace[];
-/**
- * Parse quiver3() arguments.
- *
- * Supported forms:
- *   quiver3(Z, U, V, W)
- *   quiver3(X, Y, Z, U, V, W)
- *   quiver3(..., scale)         — scale: nonnegative number or 'off'
- *   quiver3(..., LineSpec)
- *   quiver3(..., LineSpec, 'filled')
- *   quiver3(..., Name, Value)   — Color, LineStyle, LineWidth, ShowArrowHead, …
- */
-export declare function parseQuiver3Args(args: RuntimeValue[]): Quiver3Trace;

package/dist-lib/numbl-core/runtime/specialBuiltinNames.d.ts

@@ -1,2 +0,0 @@
-/** Names of all special builtins. Standalone module to avoid circular imports. */
-export declare const SPECIAL_BUILTIN_NAMES: readonly string[];