numbl 0.4.7 → 0.4.9

package/dist-browser/numbl-core/lowering/loweringContext.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Lowering context — workspace/function resolution for the interpreter.
+ *
+ * Manages workspace file registration, class extraction, function index
+ * building, and on-demand context creation for workspace/class files.
+ */
+import { type AbstractSyntaxTree, type Stmt } from "../parser/index.js";
+import type { IBuiltin } from "../interpreter/builtins/index.js";
+import type { WorkspaceFile } from "../../numbl-core/workspace/index.js";
+import { type ClassInfo } from "./classInfo.js";
+import { type ExternalAccessDirectives } from "../externalAccessDirective.js";
+export type { ClassInfo } from "./classInfo.js";
+/** Cache of parsed file ASTs, keyed by fileName. Built once at the outset. */
+export type FileASTCache = Map<string, AbstractSyntaxTree>;
+interface WorkspaceRegistry {
+    /** Raw workspace files: functionName → { fileName, source } */
+    filesByFuncName: Map<string, {
+        fileName: string;
+        source: string;
+    }>;
+    /** JS user functions (.numbl.js): functionName → { fileName, builtin } */
+    jsUserFunctionsByName: Map<string, {
+        fileName: string;
+        builtin: IBuiltin;
+    }>;
+    /** mtoc2-only user functions (.mtoc2.js): functionName → { fileName, source }.
+     *  Numbl never executes these — the source text is stored for mtoc2's loader
+     *  to consume. Numbl's interpreter rejects calls to them with a clear error. */
+    mtoc2UserFunctionsByName: Map<string, {
+        fileName: string;
+        source: string;
+    }>;
+    /** Per-workspace-file lowering contexts (created on demand) */
+    fileContexts: Map<string, LoweringContext>;
+    /** Workspace classes: qualifiedName → ClassInfo */
+    classesByName: Map<string, ClassInfo>;
+    /** Local classes (classdef in same file): className → ClassInfo */
+    localClassesByName: Map<string, ClassInfo>;
+    /** Private function files: parentDir → funcName → { fileName, source } */
+    privateFilesByDir: Map<string, Map<string, {
+        fileName: string;
+        source: string;
+    }>>;
+    /** Shared function index (built once, accessible from all contexts) */
+    functionIndex: FunctionIndex | null;
+    /** Cached parsed ASTs: fileName → AST (shared across all contexts) */
+    fileASTCache: FileASTCache;
+    /** Ordered search paths (absolute). Empty = backward-compat mode. */
+    searchPaths: string[];
+    /** Absolute fileName → resolved function name (e.g. "pkg.func") */
+    fileToFuncName: Map<string, string>;
+    /** Per-file external-access directives: fileName → ExternalAccessDirectives */
+    externalAccessByFile: Map<string, ExternalAccessDirectives>;
+}
+export type ImportEntry = {
+    wildcard: false;
+    qualifiedName: string;
+    shortName: string;
+    staticMethod?: {
+        className: string;
+        methodName: string;
+    };
+} | {
+    wildcard: true;
+    namespace: string;
+};
+export interface FunctionIndex {
+    /** Built-in function names */
+    builtins: Set<string>;
+    /** Main script file name (used to scope mainLocalFunctions) */
+    mainFileName: string;
+    /** Main script local function names */
+    mainLocalFunctions: Set<string>;
+    /** Primary workspace functions (filename-derived names) */
+    workspaceFunctions: Set<string>;
+    /** JS user functions (resolved at workspace-function priority, not builtin) */
+    jsUserFunctions: Set<string>;
+    /** mtoc2-only user functions (.mtoc2.js). Resolved at workspace-function
+     *  priority, like jsUserFunctions. Numbl's interpreter rejects calls to
+     *  these; mtoc2 routes them through its own loader. */
+    mtoc2UserFunctions: Set<string>;
+    /** Workspace classes (classdef files) */
+    workspaceClasses: Set<string>;
+    /** Local subfunctions per workspace file: primaryFuncName → Set<subfuncName> */
+    workspaceFileSubfunctions: Map<string, Set<string>>;
+    /** Local subfunctions per class file: className → Set<subfuncName> */
+    classFileSubfunctions: Map<string, Set<string>>;
+    /** Class instance methods: className → Set<methodName> (flattened through inheritance) */
+    classInstanceMethods: Map<string, Set<string>>;
+    /** Class static methods: className → Set<methodName> (flattened through inheritance) */
+    classStaticMethods: Map<string, Set<string>>;
+    /** Class constructor names: className → constructorName */
+    classConstructors: Map<string, string>;
+    /** Private functions: parentDir → Set<funcName> */
+    privateFunctions: Map<string, Set<string>>;
+    /** Local subfunctions per private file: "dir/funcName" → Set<subfuncName> */
+    privateFileSubfunctions: Map<string, Set<string>>;
+    /** InferiorClasses: superiorClassName → Set<inferiorClassName> */
+    classInferiorClasses: Map<string, Set<string>>;
+    /** Ordered search paths for relative path computation */
+    searchPaths: string[];
+    /** Absolute fileName → resolved function name (e.g. "pkg.func") */
+    fileToFuncName: Map<string, string>;
+    /** Per-file import entries: fileName → ImportEntry[] */
+    fileImports: Map<string, ImportEntry[]>;
+}
+export declare class LoweringContext {
+    readonly fileSource: string;
+    readonly mainFileName: string;
+    externalAccessVarNames: Set<string>;
+    /** Check if a variable name could be defined externally via assignin. */
+    isExternallyDefinable(name: string): boolean;
+    private localFunctionASTs;
+    registry: WorkspaceRegistry;
+    ownerClassName: string | null;
+    externalMethodLocalFunctions: Map<string, ({
+        type: "Function";
+        name: string;
+        functionId: string;
+        params: string[];
+        outputs: string[];
+        body: Stmt[];
+        argumentsBlocks: import("../parser/types.js").ArgumentsBlock[];
+        isFileLocalSubfunction?: boolean;
+        span: import("../parser/types.js").Span;
+    } & {
+        type: "Function";
+    })[]>;
+    constructor(fileSource: string, mainFileName: string);
+    /**
+     * Compute the relative path of a file within its search path.
+     * When no search paths are configured, returns the path as-is (backward compat).
+     * Uses the most specific (longest) matching search path to handle
+     * overlapping paths (e.g. /a/b and /a/b/tools both on the search path).
+     */
+    getRelativePath(absolutePath: string): string;
+    /** Look up a pre-parsed AST by fileName. Throws if not cached. */
+    getCachedAST(fileName: string): AbstractSyntaxTree;
+    /** Get the shared file AST cache (for pre-populating from the outside). */
+    get fileASTCache(): FileASTCache;
+    isConstant(name: string): boolean;
+    private isLocalFunction;
+    /** Register a local function's AST (called before lowering begins). */
+    registerLocalFunctionAST(stmt: Stmt & {
+        type: "Function";
+    }): void;
+    /** Unregister a local function's AST. */
+    unregisterLocalFunctionAST(name: string): void;
+    /**
+     * Register workspace files for on-demand resolution.
+     * Extracts function names from filenames (top-level only, plus +pkg namespaces).
+     * Also handles @ClassName class folders.
+     *
+     * `.m` files register as workspace functions / classes / private functions
+     * (the regular MATLAB-style discovery). `.mtoc2.js` files register as
+     * mtoc2-only user functions: numbl tracks the name so resolution sees
+     * them, but the body stays unparsed — mtoc2's loader evaluates them.
+     * `.mtoc2.js` files in `@ClassName/` are not yet supported.
+     */
+    registerWorkspaceFiles(files: WorkspaceFile[]): void;
+    isWorkspaceFunction(name: string): boolean;
+    /** Clear workspace-level registrations so they can be rebuilt after addpath/rmpath. */
+    clearWorkspaceRegistrations(): void;
+    /**
+     * Register a JS user function (.numbl.js) in the workspace registry.
+     * Uses first-wins semantics so search-path priority is honored.
+     */
+    registerJsUserFunction(funcName: string, fileName: string, builtin: IBuiltin): void;
+    /**
+     * Register an mtoc2-only user function (.mtoc2.js) in the workspace
+     * registry. Numbl stores the source text verbatim; mtoc2's loader
+     * evaluates it. Uses first-wins semantics so search-path priority is
+     * honored — same as `.numbl.js`.
+     */
+    registerMtoc2UserFunction(funcName: string, fileName: string, source: string): void;
+    /**
+     * Get the effective directory for this context's file, used for
+     * private function resolution. If the file is inside a private/ folder,
+     * the effective dir is the parent of private/ (so private functions
+     * can call each other).
+     */
+    private getEffectiveDir;
+    getOrCreatePrivateFileContext(funcName: string): LoweringContext | null;
+    /**
+     * Look up a private function entry by effective directory and name.
+     * Used by JIT to resolve private functions from a specific calling file.
+     */
+    getPrivateFileEntry(callerFileName: string, funcName: string): {
+        fileName: string;
+        source: string;
+    } | null;
+    /**
+     * Get or create an LoweringContext for a workspace file.
+     * Parses the file on demand and registers its local functions.
+     */
+    getOrCreateWorkspaceFileContext(funcName: string): LoweringContext | null;
+    /**
+     * Register a workspace file as a class definition.
+     * Parses the file to extract class structure (properties, methods).
+     */
+    private registerWorkspaceClass;
+    /**
+     * Register a classdef statement found in the local (main) file.
+     */
+    registerLocalClass(stmt: Stmt & {
+        type: "ClassDef";
+    }): void;
+    isWorkspaceClass(name: string): boolean;
+    isLocalClass(name: string): boolean;
+    isClass(name: string): boolean;
+    getClassInfo(name: string): ClassInfo | null;
+    /** Check if a class (or any ancestor) has a given method. */
+    classHasMethod(className: string, methodName: string): boolean;
+    /** Check if a class (or any ancestor) has a given static method. */
+    classHasStaticMethod(className: string, methodName: string): boolean;
+    /**
+     * Walk the inheritance chain to find the class that defines a given method.
+     * Checks instance methods, external method files, static methods, and constructors.
+     */
+    findDefiningClass(className: string, methodName: string): string;
+    /**
+     * Get or create an LoweringContext for a class file.
+     * Registers all methods as local functions so they can be specialized on demand.
+     * For constructors, the AST is modified to prepend the output variable as a parameter
+     * (Instance is passed as first arg).
+     */
+    getOrCreateClassFileContext(className: string): LoweringContext | null;
+    /**
+     * Run a callback with per-file local helper functions temporarily installed
+     * for the given method name. Ensures cleanup even on exception.
+     */
+    withMethodScope<T>(methodName: string, fn: () => T): T;
+    /**
+     * Build a FunctionIndex from the current state of the registry and local functions.
+     * Should be called once after registerWorkspaceFiles() and registerLocalFunctionAST().
+     * Parses all workspace files eagerly to discover subfunctions.
+     */
+    buildFunctionIndex(): FunctionIndex;
+    /** Get the function index (must call buildFunctionIndex() first on any context sharing the same registry). */
+    get functionIndex(): FunctionIndex;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * 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-browser/numbl-core/native/geometry-bridge.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Geometry bridge — a module-level singleton that holds the Delaunay
+ * triangulation backend.
+ *
+ * Startup (CLI, browser worker, test-runner) loads the qhull WASM module
+ * (exact, robust to cospherical/coplanar input) and installs it here. The
+ * builtins require it: if no backend is set, delaunay/delaunayn throw.
+ *
+ * Usage (startup):
+ *   import { setDelaunayBackend } from './numbl-core/native/geometry-bridge.js';
+ *   const qhull = await loadQhull();
+ *   setDelaunayBackend((points, dim) => qhull.delaunay(points, dim).facets);
+ *
+ * Usage (builtin):
+ *   import { getDelaunayBackend } from '../native/geometry-bridge.js';
+ *   const backend = getDelaunayBackend();
+ *   if (!backend) throw ...;
+ *   const cells = backend(points, dim);
+ */
+/**
+ * Compute a Delaunay triangulation of `points` (an array of dim-dimensional
+ * tuples). Returns an array of simplices, each a list of `dim+1` 0-based input
+ * point indices.
+ */
+export type DelaunayBackend = (points: number[][], dim: number) => number[][];
+/**
+ * Compute the convex hull of `points` (an array of dim-dimensional tuples).
+ * Returns an array of simplicial facets, each a list of `dim` 0-based input
+ * point indices (edges in 2-D, triangles in 3-D).
+ */
+export type ConvexHullBackend = (points: number[][], dim: number) => number[][];
+/** Install (or clear, with null) the Delaunay backend. */
+export declare function setDelaunayBackend(fn: DelaunayBackend | null): void;
+/** Get the current Delaunay backend, or null if none is installed. */
+export declare function getDelaunayBackend(): DelaunayBackend | null;
+/** Install (or clear, with null) the convex-hull backend. */
+export declare function setConvexHullBackend(fn: ConvexHullBackend | null): void;
+/** Get the current convex-hull backend, or null if none is installed. */
+export declare function getConvexHullBackend(): ConvexHullBackend | null;