numbl 0.1.0 → 0.1.2

package/dist-lib/numbl-core/interpreter/jit/jitLoopAnalysis.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Static AST analysis to determine input/output variables for loop JIT.
+ *
+ * Walks the loop body (and condition for while) to collect:
+ * - assigned: variables written inside the loop
+ * - referenced: variables read inside the loop
+ * - hasReturn: whether the loop body contains a return statement
+ */
+import type { Stmt } from "../../parser/types.js";
+export interface LoopVarInfo {
+    /** Variables referenced in the loop that must come from enclosing scope */
+    inputs: string[];
+    /** Variables assigned in the loop body (written back after JIT execution) */
+    outputs: string[];
+    /** Whether the loop body contains a return statement (skip JIT if true) */
+    hasReturn: boolean;
+}
+/** Analyze a for loop statement for JIT compilation. */
+export declare function analyzeForLoop(stmt: Stmt & {
+    type: "For";
+}): LoopVarInfo;
+/** Analyze a while loop statement for JIT compilation. */
+export declare function analyzeWhileLoop(stmt: Stmt & {
+    type: "While";
+}): LoopVarInfo;

package/dist-lib/numbl-core/interpreter/jit/jitLower.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AST -> JIT IR lowering with type propagation.
+ *
+ * Returns null if any unsupported construct is encountered,
+ * causing the entire function to fall back to interpretation.
+ */
+import type { FunctionDef } from "../types.js";
+import type { Interpreter } from "../interpreter.js";
+import { type JitType, type JitStmt } from "./jitTypes.js";
+export interface LoweringResult {
+    body: JitStmt[];
+    outputNames: string[];
+    localVars: Set<string>;
+    hasTensorOps: boolean;
+    /** Generated JS code for called user functions: jitName → code */
+    generatedFns: Map<string, string>;
+    /** Type of the first output variable after lowering */
+    outputType: JitType | null;
+}
+export declare function lowerFunction(fn: FunctionDef, argTypes: JitType[], nargout: number, interp?: Interpreter, generatedFns?: Map<string, string>, loweringInProgress?: Set<string>): LoweringResult | null;

package/dist-lib/numbl-core/interpreter/jit/jitTypes.d.ts

@@ -0,0 +1,168 @@
+/**
+ * JIT type system and IR node definitions.
+ */
+import type { BinaryOperation, UnaryOperation } from "../../parser/types.js";
+export type SignCategory = "positive" | "nonneg" | "nonpositive" | "negative";
+export type JitType = {
+    kind: "number";
+    exact?: number;
+    sign?: SignCategory;
+} | {
+    kind: "boolean";
+    value?: boolean;
+} | {
+    kind: "complex_or_number";
+    pureImaginary?: boolean;
+} | {
+    kind: "tensor";
+    isComplex: boolean;
+    shape?: number[];
+    ndim?: number;
+    isLogical?: boolean;
+    nonneg?: boolean;
+} | {
+    kind: "string";
+    value?: string;
+} | {
+    kind: "char";
+    value?: string;
+} | {
+    kind: "struct";
+    fields?: Record<string, JitType>;
+} | {
+    kind: "class_instance";
+    className: string;
+    isHandleClass?: boolean;
+    fields?: Record<string, JitType>;
+} | {
+    kind: "sparse_matrix";
+    isComplex: boolean;
+    m?: number;
+    n?: number;
+} | {
+    kind: "cell";
+    shape?: number[];
+} | {
+    kind: "dictionary";
+} | {
+    kind: "unknown";
+};
+export declare function signFromNumber(v: number): SignCategory | undefined;
+export declare function isNonneg(t: JitType): boolean;
+export declare function flipSign(s?: SignCategory): SignCategory | undefined;
+export declare function unifySign(a?: SignCategory, b?: SignCategory): SignCategory | undefined;
+export declare function jitTypeKey(t: JitType): string;
+export declare function computeJitCacheKey(nargout: number, argTypes: JitType[]): string;
+/** Compute a unique JS function name for a JIT'd specialization. */
+export declare function computeJitFnName(identity: string, funcName: string): string;
+/** Widen/unify two types at control-flow join points. */
+export declare function unifyJitTypes(a: JitType, b: JitType): JitType;
+export declare function isScalarType(t: JitType): boolean;
+export declare function isNumericScalarType(t: JitType): boolean;
+export declare function isTensorType(t: JitType): boolean;
+export declare function isComplexType(t: JitType): boolean;
+/** Types that support arithmetic binary operations in the JIT. */
+export declare function isArithmeticType(t: JitType): boolean;
+export declare function shapeAfterReduction(shape: number[], dim?: number): {
+    scalar: true;
+} | {
+    scalar: false;
+    shape: number[];
+};
+export type JitExpr = {
+    tag: "NumberLiteral";
+    value: number;
+    jitType: JitType;
+} | {
+    tag: "ImagLiteral";
+    jitType: JitType;
+} | {
+    tag: "Var";
+    name: string;
+    jitType: JitType;
+} | {
+    tag: "Binary";
+    op: BinaryOperation;
+    left: JitExpr;
+    right: JitExpr;
+    jitType: JitType;
+} | {
+    tag: "Unary";
+    op: UnaryOperation;
+    operand: JitExpr;
+    jitType: JitType;
+} | {
+    tag: "StringLiteral";
+    value: string;
+    isChar: boolean;
+    jitType: JitType;
+} | {
+    tag: "Call";
+    name: string;
+    args: JitExpr[];
+    jitType: JitType;
+} | {
+    tag: "UserCall";
+    jitName: string;
+    name: string;
+    args: JitExpr[];
+    jitType: JitType;
+} | {
+    tag: "Index";
+    base: JitExpr;
+    indices: JitExpr[];
+    jitType: JitType;
+} | {
+    tag: "TensorLiteral";
+    rows: JitExpr[][];
+    nRows: number;
+    nCols: number;
+    jitType: JitType;
+};
+export type JitStmt = {
+    tag: "Assign";
+    name: string;
+    expr: JitExpr;
+} | {
+    tag: "If";
+    cond: JitExpr;
+    thenBody: JitStmt[];
+    elseifBlocks: {
+        cond: JitExpr;
+        body: JitStmt[];
+    }[];
+    elseBody: JitStmt[] | null;
+} | {
+    tag: "For";
+    varName: string;
+    start: JitExpr;
+    step: JitExpr | null;
+    end: JitExpr;
+    body: JitStmt[];
+} | {
+    tag: "While";
+    cond: JitExpr;
+    body: JitStmt[];
+} | {
+    tag: "Break";
+} | {
+    tag: "Continue";
+} | {
+    tag: "Return";
+} | {
+    tag: "ExprStmt";
+    expr: JitExpr;
+} | {
+    tag: "MultiAssign";
+    names: (string | null)[];
+    callName: string;
+    args: JitExpr[];
+    outputTypes: JitType[];
+} | {
+    tag: "SetLoc";
+    line: number;
+};
+export interface JitCacheEntry {
+    fn: (...args: unknown[]) => unknown;
+    source: string;
+}

package/dist-lib/numbl-core/interpreter/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Shared types for the interpreter: Environment, control flow signals, FunctionDef.
+ */
+import type { Stmt, ArgumentsBlock } from "../parser/types.js";
+import type { Runtime } from "../runtime/runtime.js";
+import type { RuntimeValue } from "../runtime/types.js";
+import type { JitType } from "./jit/jitTypes.js";
+export declare class BreakSignal {
+    readonly _tag = "break";
+}
+export declare class ContinueSignal {
+    readonly _tag = "continue";
+}
+export declare class ReturnSignal {
+    values: RuntimeValue[];
+    readonly _tag = "return";
+    constructor(values: RuntimeValue[]);
+}
+export type ControlSignal = BreakSignal | ContinueSignal | ReturnSignal;
+export declare class Environment {
+    private parent?;
+    private vars;
+    /** When true, writes to variables found in parent go to the parent (nested function semantics). */
+    isNested: boolean;
+    /** Nested function definitions registered during execution. */
+    nestedFunctions: Map<string, {
+        fn: FunctionDef;
+        env: Environment;
+    }>;
+    /** Names declared as `global` in this scope — reads/writes go through rt.$g */
+    globalNames: Set<string>;
+    /** Names declared as `persistent` in this scope */
+    persistentNames: Set<string>;
+    /** Function ID for persistent variable storage */
+    persistentFuncId: string | undefined;
+    /** Back-reference to the runtime (needed for global/persistent access) */
+    rt: Runtime | null;
+    constructor(parent?: Environment | undefined);
+    get(name: string): RuntimeValue | undefined;
+    /** Set variable — for nested scopes, writes to parent if variable exists there. */
+    set(name: string, value: RuntimeValue): void;
+    /** Always writes to this scope (for parameter binding). */
+    setLocal(name: string, value: RuntimeValue): void;
+    has(name: string): boolean;
+    /** Check if this scope directly owns a variable (not parent). */
+    hasLocal(name: string): boolean;
+    /** Find the environment that owns a variable. */
+    private findOwner;
+    /** Look up a nested function definition in this scope or parent scopes. */
+    getNestedFunction(name: string): {
+        fn: FunctionDef;
+        env: Environment;
+    } | undefined;
+    localNames(): string[];
+    /** Create a snapshot of this environment (copies all variables by value).
+     *  Used for anonymous functions which capture values at definition time. */
+    snapshot(): Environment;
+    toRecord(): Record<string, RuntimeValue>;
+}
+export interface FunctionDef {
+    name: string;
+    params: string[];
+    outputs: string[];
+    body: Stmt[];
+    argumentsBlocks?: ArgumentsBlock[];
+    /** JIT compilation cache: maps signature key -> compiled entry or null (failed). */
+    _jitCache?: Map<string, {
+        fn: (...args: unknown[]) => unknown;
+        source: string;
+    } | null>;
+    /** Progressive type widening: last unified arg types, keyed by nargout. */
+    _lastJitArgTypes?: Map<number, JitType[]>;
+}
+/** Create a FunctionDef from an AST Function statement. */
+export declare function funcDefFromStmt(stmt: Stmt & {
+    type: "Function";
+}): FunctionDef;

package/dist-lib/numbl-core/jsUserFunctions.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Loader for .js user functions.
+ *
+ * Evaluates .js files that define IBuiltins via register({ resolve, jitEmit? }).
+ * Supports optional WASM and native shared library bindings via directives:
+ *   // wasm: <name>
+ *   // native: <name>
+ */
+import type { WorkspaceFile, NativeBridge } from "./workspace/index.js";
+import type { IBuiltin } from "./interpreter/builtins/types.js";
+/**
+ * Load .js user function files and return them as IBuiltin objects.
+ *
+ * Each .js file calls register({ resolve, jitEmit? }) to define an IBuiltin.
+ * resolve(argTypes, nargout) returns { outputTypes, apply } or null.
+ *
+ * A .js file can specify bindings via directives at the top of the file:
+ *   // wasm: <name>    — load a WASM module (looked up by name in wasmFiles)
+ *   // native: <name>  — load a native shared library (resolved relative to .js file)
+ *
+ * Files whose basename starts with `_` are library files. They must not call
+ * register() and instead export values via `return`. Other .js files can import
+ * them with `importJS("_name")`.
+ */
+export declare function loadJsUserFunctions(jsFiles: WorkspaceFile[], wasmFiles?: WorkspaceFile[], nativeBridge?: NativeBridge): IBuiltin[];

package/dist-lib/numbl-core/lexer/helpers.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Helper functions for the lexer.
+ */
+import { Token } from "./types.js";
+export declare function isAlpha(ch: string): boolean;
+export declare function isAlnum(ch: string): boolean;
+export declare function isDigit(ch: string): boolean;
+export declare function isWhitespace(ch: string): boolean;
+/** Check if a token represents a "value" for transpose disambiguation. */
+export declare function isValueToken(tok: Token): boolean;
+/**
+ * Find the first line terminator (\n or \r\n or \r) in `s`.
+ * Returns [index, length] or undefined.
+ */
+export declare function findLineTerminator(s: string, offset?: number): [number, number] | undefined;

package/dist-lib/numbl-core/lexer/index.d.ts

@@ -0,0 +1,4 @@
+export { Token } from "./types.js";
+export { KEYWORDS, VALUE_KEYWORDS } from "./keywords.js";
+export { isAlpha, isAlnum, isDigit, isWhitespace, isValueToken, findLineTerminator, } from "./helpers.js";
+export { tokenize, tokenizeDetailed } from "./tokenizer.js";

package/dist-lib/numbl-core/lexer/keywords.d.ts

@@ -0,0 +1,3 @@
+import { Token } from "./types.js";
+export declare const KEYWORDS: ReadonlyMap<string, Token>;
+export declare const VALUE_KEYWORDS: ReadonlySet<Token>;

package/dist-lib/numbl-core/lexer/token-config.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Token configuration types and loader.
+ */
+import { Token } from "./types.js";
+export interface OperatorConfig {
+    pattern: string;
+    token: string;
+    special?: string;
+}
+export interface BlockCommentConfig {
+    start: string;
+    end: string;
+    consumeTrailingNewline?: boolean;
+}
+export interface SectionMarkerConfig {
+    pattern: string;
+    requireLineStart: boolean;
+    token: string;
+    consumeToEOL: boolean;
+    consumeTrailingNewline?: boolean;
+    fallbackToLineComment?: boolean;
+}
+export interface LineCommentConfig {
+    start: string;
+}
+export interface CommentsConfig {
+    blockComment: BlockCommentConfig;
+    sectionMarker: SectionMarkerConfig;
+    lineComment: LineCommentConfig;
+}
+export interface StringDisambiguation {
+    type: "transpose";
+    transposeToken: string;
+    conditions: {
+        requireAdjacency: boolean;
+        requirePrevValueOrDot: boolean;
+    };
+}
+export interface StringConfig {
+    delimiter: string;
+    escape: string;
+    token: string;
+    allowMultiline: boolean;
+    disambiguation?: StringDisambiguation;
+}
+export interface SpecialPatternConfig {
+    pattern: string;
+    token: string;
+    consumeToEOL?: boolean;
+    consumeTrailingNewline?: boolean;
+    coalesceMultiple?: boolean;
+    setsLineStart?: boolean;
+}
+export interface NumbersConfig {
+    allowUnderscores: boolean;
+    stripUnderscores: boolean;
+    integerToken: string;
+    floatToken: string;
+    exponentChars: string[];
+    decimalPoint: string;
+    dotOperatorPrefixes: string[];
+}
+export interface IdentifiersConfig {
+    token: string;
+    startChars: "alpha";
+    continueChars: "alnum";
+}
+export interface TokenConfig {
+    operators: {
+        twoChar: OperatorConfig[];
+        singleChar: OperatorConfig[];
+    };
+    comments: CommentsConfig;
+    strings: StringConfig[];
+    special: {
+        ellipsis: SpecialPatternConfig;
+        newline: SpecialPatternConfig;
+    };
+    numbers: NumbersConfig;
+    identifiers: IdentifiersConfig;
+}
+export declare const TOKEN_CONFIG: TokenConfig;
+/**
+ * Build a map from pattern to token for two-character operators.
+ */
+export declare function buildTwoCharMap(): Map<string, Token>;
+/**
+ * Build a map from pattern to token for single-character operators.
+ */
+export declare function buildSingleCharMap(): Map<string, Token>;
+/**
+ * Get the special behavior flag for a single-character operator.
+ */
+export declare function getSingleCharSpecial(pattern: string): string | undefined;

package/dist-lib/numbl-core/lexer/tokenizer.d.ts

@@ -0,0 +1,9 @@
+import { SpannedToken, Token } from "./types.js";
+/**
+ * Tokenize source into a flat token array (no newlines).
+ */
+export declare function tokenize(input: string): Token[];
+/**
+ * Tokenize source with full span information.
+ */
+export declare function tokenizeDetailed(input: string): SpannedToken[];

package/dist-lib/numbl-core/lexer/types.d.ts

@@ -0,0 +1,78 @@
+export declare enum Token {
+    Integer = 0,
+    Float = 1,
+    Str = 2,
+    Char = 3,
+    Ident = 4,
+    Function = 5,
+    If = 6,
+    Else = 7,
+    ElseIf = 8,
+    For = 9,
+    While = 10,
+    Break = 11,
+    Continue = 12,
+    Return = 13,
+    End = 14,
+    ClassDef = 15,
+    Properties = 16,
+    Methods = 17,
+    Events = 18,
+    Enumeration = 19,
+    Arguments = 20,
+    Import = 21,
+    Switch = 22,
+    Case = 23,
+    Otherwise = 24,
+    Try = 25,
+    Catch = 26,
+    Global = 27,
+    Persistent = 28,
+    True = 29,
+    False = 30,
+    Plus = 31,
+    Minus = 32,
+    Star = 33,
+    Slash = 34,
+    Backslash = 35,
+    Caret = 36,
+    And = 37,
+    Or = 38,
+    Tilde = 39,
+    At = 40,
+    Question = 41,
+    Less = 42,
+    Greater = 43,
+    Dot = 44,
+    Colon = 45,
+    Comma = 46,
+    Assign = 47,
+    Semicolon = 48,
+    LParen = 49,
+    RParen = 50,
+    LBracket = 51,
+    RBracket = 52,
+    LBrace = 53,
+    RBrace = 54,
+    DotStar = 55,
+    DotSlash = 56,
+    DotBackslash = 57,
+    DotCaret = 58,
+    AndAnd = 59,
+    OrOr = 60,
+    Equal = 61,
+    NotEqual = 62,
+    LessEqual = 63,
+    GreaterEqual = 64,
+    Transpose = 65,
+    Ellipsis = 66,
+    Newline = 67,
+    Section = 68,
+    Error = 69
+}
+export interface SpannedToken {
+    token: Token;
+    lexeme: string;
+    start: number;
+    end: number;
+}

package/dist-lib/numbl-core/lowering/classInfo.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Class information types and extraction utilities.
+ */
+import { type Expr, type Stmt } from "../parser/index.js";
+/**
+ * Metadata about a class definition.
+ * The ctx field is typed as 'unknown' to avoid circular dependencies with LoweringContext.
+ * At runtime, it will hold a LoweringContext instance.
+ */
+export interface ClassInfo {
+    name: string;
+    qualifiedName: string;
+    fileName: string;
+    source: string;
+    superClass: string | null;
+    propertyNames: string[];
+    propertyDefaults: Map<string, Expr>;
+    methodNames: Set<string>;
+    staticMethodNames: Set<string>;
+    constructorName: string | null;
+    ast: Stmt & {
+        type: "ClassDef";
+    };
+    inferiorClasses: string[];
+    externalMethodFiles: Map<string, {
+        fileName: string;
+        source: string;
+    }>;
+    ctx?: any;
+}
+/**
+ * Extract ClassInfo from a parsed ClassDef AST node.
+ */
+export declare function extractClassInfo(classDef: Stmt & {
+    type: "ClassDef";
+}, qualifiedName: string, fileName: string, source: string): ClassInfo;

package/dist-lib/numbl-core/lowering/constants.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Built-in Constants and Functions
+ */
+export declare const BUILTIN_CONSTANTS: Set<string>;

package/dist-lib/numbl-core/lowering/errors.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Semantic Errors
+ */
+import type { Span } from "../parser";
+export declare class SemanticError extends Error {
+    span: Span | null;
+    identifier: string | null;
+    /** Resolved source file name (set by prepare.ts) */
+    file: string | null;
+    /** Resolved 1-based line number (set by prepare.ts) */
+    line: number | null;
+    /** Resolved 1-based column number (set by prepare.ts) */
+    column: number | undefined;
+    constructor(message: string, span?: Span | null, identifier?: string | null);
+    withSpan(span: Span): SemanticError;
+    withIdentifier(identifier: string): SemanticError;
+}

package/dist-lib/numbl-core/lowering/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./errors.js";
+export * from "./constants.js";
+export { BinaryOperation } from "../parser/index.js";

package/dist-lib/numbl-core/lowering/itemTypes.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Type System for IR
+ */
+export type ItemType = {
+    kind: "Number";
+} | {
+    kind: "ComplexNumber";
+} | {
+    kind: "Boolean";
+} | {
+    kind: "Char";
+} | {
+    kind: "String";
+} | {
+    kind: "Tensor";
+    isComplex?: boolean;
+    isLogical?: boolean;
+} | {
+    kind: "Cell";
+    elementType: ItemType | "unknown";
+    length: number | "unknown";
+} | {
+    kind: "Function";
+    params: ItemType[];
+    returns: ItemType;
+} | {
+    kind: "Struct";
+    knownFields: Record<string, ItemType>;
+} | {
+    kind: "Void";
+} | {
+    kind: "Unknown";
+} | {
+    kind: "Union";
+    types: ItemType[];
+} | {
+    kind: "MultipleOutputs";
+    outputTypes: ItemType[];
+} | {
+    kind: "ClassInstance";
+    className: string;
+} | {
+    kind: "DummyHandle";
+} | {
+    kind: "SparseMatrix";
+    isComplex?: boolean;
+} | {
+    kind: "Dictionary";
+};
+/** Returns true if the type is definitely Num, false if definitely not, undefined if unknown. */
+export declare function isNum(t: ItemType): boolean | undefined;
+/** Returns true if the type is definitely Tensor, false if definitely not, undefined if unknown. */
+export declare function isTensor(t: ItemType): boolean | undefined;
+/** Returns true if the type is definitely Complex, false if definitely not, undefined if unknown. */
+export declare function isComplex(t: ItemType): boolean | undefined;
+/** Returns true if the type is fully unknown ({kind: "Unknown"}). */
+export declare function isFullyUnknown(t: ItemType): boolean;
+/** Returns true if the type is definitely String, false if definitely not, undefined if unknown. */
+export declare function isString(t: ItemType): boolean | undefined;
+/** Returns true if the type is definitely Char, false if definitely not, undefined if unknown. */
+export declare function isChar(t: ItemType): boolean | undefined;
+export declare const IType: {
+    Num: ItemType;
+    Complex: ItemType;
+    Bool: ItemType;
+    Logical: ItemType;
+    Char: ItemType;
+    String: ItemType;
+    Void: ItemType;
+    Unknown: ItemType;
+    DummyHandle: ItemType;
+    SparseMatrix: ItemType;
+    Dictionary: ItemType;
+    /** Create a Num type */
+    num(): ItemType;
+    tensor(opts?: {
+        isComplex?: boolean;
+        isLogical?: boolean;
+    }): ItemType;
+    cell(elementType?: ItemType | "unknown", length?: number | "unknown"): ItemType;
+    func(params: ItemType[], returns: ItemType): ItemType;
+    struct(fields?: Record<string, ItemType>): ItemType;
+    sparseMatrix(isComplex?: boolean): ItemType;
+    union(types: ItemType[]): ItemType;
+    /** Unify two types, producing a common supertype */
+    unify(a: ItemType | undefined, b: ItemType | undefined): ItemType | undefined;
+};