wesl 0.6.15 → 0.6.16

package/README.md

@@ -20,7 +20,7 @@ WESL adds features:
 - **shader libraries** on npm and cargo, for community sharing of shader code modules
 
 This [wesl] library contains a **TypeScript** WESL linker.
-[wesl] can be used at runtime or at build time to assemble WESL and WGSL modules for WebGPUk
+[wesl] can be used at runtime or at build time to assemble WESL and WGSL modules for WebGPU.
 
 <img style="margin:10px 0px -10px 40px" src="https://docs.google.com/drawings/d/e/2PACX-1vRKxcnMB-U-UVcDRO6N6UMJESTodUBRnV6cVrrS_XwJetucnOfYCU9ztk9veXoqLJ7DinBdDnR9EiK-/pub?w=400&amp;h=300">
 

package/dist/index.d.ts

@@ -8,6 +8,10 @@ interface LiveDecls {
   /** live decls in the parent scope. null for the modue root scope */
   parent?: LiveDecls | null;
 }
+/** create a LiveDecls */
+declare function makeLiveDecls(parent?: LiveDecls | null): LiveDecls;
+/** debug routine for logging LiveDecls */
+declare function liveDeclsToString(liveDecls: LiveDecls): string;
 //#endregion
 //#region src/FlattenTreeImport.d.ts
 interface FlatImport {
@@ -608,30 +612,6 @@ declare function minimalMangle(_d: DeclIdent, _s: SrcModule, proposedName: strin
  */
 declare function minimallyMangledName(proposedName: string, globalNames: Set<string>): string;
 //#endregion
-//#region src/ParsedRegistry.d.ts
-interface ParsedRegistry {
-  modules: Record<string, WeslAST>;
-}
-declare function parsedRegistry(): ParsedRegistry;
-/** for debug */
-declare function registryToString(registry: ParsedRegistry): string;
-/** Look up a module with a flexible selector.
- *    :: separated module path,   package::util
- *    / separated file path       ./util.wesl (or ./util)
- *          - note: a file path should not include a weslRoot prefix, e.g. not ./shaders/util.wesl
- *    simpleName                  util
- */
-declare function selectModule(parsed: ParsedRegistry, selectPath: string, packageName?: string): WeslAST | undefined;
-/**
- * @param srcFiles    map of source strings by file path
- *                    key is '/' separated relative path (relative to srcRoot, not absolute file path )
- *                    value is wesl source string
- * @param registry    add parsed modules to this registry
- * @param packageName name of package
- */
-declare function parseIntoRegistry(srcFiles: Record<string, string>, registry: ParsedRegistry, packageName?: string, debugWeslRoot?: string): void;
-declare function parseLibsIntoRegistry(libs: WeslBundle[], registry: ParsedRegistry): void;
-//#endregion
 //#region src/WeslBundle.d.ts
 interface WeslBundle {
   /** name of the package, e.g. random_wgsl */
@@ -647,6 +627,68 @@ interface WeslBundle {
   dependencies?: WeslBundle[];
 }
 //#endregion
+//#region src/ModuleResolver.d.ts
+/**
+ * Resolves module paths to parsed ASTs.
+ *
+ * Implementations may cache ASTs or load them lazily.
+ */
+interface ModuleResolver {
+  /**
+   * Resolve a module path to its parsed AST.
+   *
+   * @param modulePath - Module path in :: format (e.g., "package::foo::bar")
+   * @returns Parsed AST or undefined if module not found
+   */
+  resolveModule(modulePath: string): WeslAST | undefined;
+}
+/** Module resolver that supports batch enumeration of all modules. */
+interface BatchModuleResolver extends ModuleResolver {
+  /**
+   * Return all modules, parsing them on-demand if needed.
+   * Implementations should ensure all sources are parsed before returning.
+   */
+  allModules(): Iterable<[string, WeslAST]>;
+}
+interface RecordResolverOptions {
+  /** Package name for module path resolution (default: "package") */
+  packageName?: string;
+  /** Debug path prefix for error messages */
+  debugWeslRoot?: string;
+}
+/** Module resolver for in-memory source records. Lazy by default. */
+declare class RecordResolver implements BatchModuleResolver {
+  readonly astCache: Map<string, WeslAST>;
+  readonly sources: Record<string, string>;
+  readonly packageName: string;
+  readonly debugWeslRoot: string;
+  constructor(sources: Record<string, string>, options?: RecordResolverOptions);
+  resolveModule(modulePath: string): WeslAST | undefined;
+  private findSource;
+  private moduleToFilePath;
+  private modulePathToDebugPath;
+  /** Return all modules, parsing them on-demand if needed. */
+  allModules(): Iterable<[string, WeslAST]>;
+}
+/** Composite resolver that tries each resolver in order until one succeeds. */
+declare class CompositeResolver implements ModuleResolver {
+  readonly resolvers: ModuleResolver[];
+  constructor(resolvers: ModuleResolver[]);
+  resolveModule(modulePath: string): WeslAST | undefined;
+}
+/** Lazy resolver for WeslBundle library modules. */
+declare class BundleResolver implements ModuleResolver {
+  private readonly astCache;
+  private readonly sources;
+  private readonly packageName;
+  private readonly debugWeslRoot;
+  constructor(bundle: WeslBundle, debugWeslRoot?: string);
+  resolveModule(modulePath: string): WeslAST | undefined;
+  private findSource;
+  private moduleToFilePath;
+  private modulePathToDebugPath;
+}
+//#endregion
 //#region src/Linker.d.ts
 type LinkerTransform = (boundAST: TransformedAST) => TransformedAST;
 interface WeslJsPlugin {
@@ -660,7 +702,11 @@ interface LinkConfig {
   plugins?: WeslJsPlugin[];
 }
 interface LinkParams {
-  /** record of file paths and wesl text for modules.
+  /** Module resolver for lazy loading (NEW API - preferred)
+   * Replaces weslSrc for lazy module loading.
+   * If provided, weslSrc will be ignored. */
+  resolver?: ModuleResolver;
+  /** record of file paths and wesl text for modules (LEGACY API - still supported).
    *   key is module path or file path
    *     `package::foo::bar`, or './foo/bar.wesl', or './foo/bar'
    *   value is wesl src
@@ -671,7 +717,7 @@ interface LinkParams {
    * - Valid WGSL identifiers: No backslashes, no `..`, or other non-identifier symbols.
    * - Relative paths: They have to be relative to the wesl root.
    */
-  weslSrc: Record<string, string>;
+  weslSrc?: Record<string, string>;
   /** name of root wesl module
    *    for an app, the root module normally contains the '@compute', '@vertex' or '@fragment' entry points
    *    for a library, the root module defines the public api fo the library
@@ -686,6 +732,10 @@ interface LinkParams {
   libs?: WeslBundle[];
   /** generate wesl from code at runtime */
   virtualLibs?: Record<string, VirtualLibraryFn>;
+  /** package name for the local sources (in addition to default "package::").
+   * Enables imports like `import mypkg::foo` alongside `import package::foo`.
+   * Package names with hyphens should be normalized to underscores. */
+  packageName?: string;
   /** plugins and other configuration to use while linking */
   config?: LinkConfig;
   /** Host (ts/js) provided wgsl constants.
@@ -708,9 +758,9 @@ type VirtualLibraryFn = (conditions: Conditions) => string;
  */
 declare function link(params: LinkParams): Promise<LinkedWesl>;
 /** linker api for benchmarking */
-declare function _linkSync(params: LinkParams): LinkedWesl;
+declare function _linkSync(params: LinkParams): SrcMap;
 interface LinkRegistryParams extends Pick<LinkParams, "rootModuleName" | "conditions" | "virtualLibs" | "config" | "constants" | "mangler"> {
-  registry: ParsedRegistry;
+  resolver: ModuleResolver;
 }
 /** Link wesl from a registry of already parsed modules.
  *
@@ -725,8 +775,11 @@ interface BoundAndTransformed {
   newDecls: DeclIdent[];
   newStatements: EmittableElem[];
 }
-/** bind identifers and apply any transform plugins */
+/** Bind identifiers and apply transform plugins */
 declare function bindAndTransform(params: LinkRegistryParams): BoundAndTransformed;
+/** Convert root module name to module path format.
+ * Accepts: module path (package::foo), file path (./foo.wesl), or name (foo) */
+declare function normalizeModuleName(name: string): string;
 //#endregion
 //#region src/BindIdents.d.ts
 /**
@@ -783,7 +836,7 @@ interface VirtualLibrary {
 }
 /** key is virtual module name */
 type VirtualLibrarySet = Record<string, VirtualLibrary>;
-interface BindIdentsParams extends Pick<LinkRegistryParams, "registry" | "conditions" | "mangler"> {
+interface BindIdentsParams extends Pick<LinkRegistryParams, "resolver" | "conditions" | "mangler"> {
   rootAst: WeslAST;
   virtuals?: VirtualLibrarySet;
   /** if false, throw on unbound identifiers. If true, accumulate unbound identifiers into
@@ -799,8 +852,6 @@ interface BindIdentsParams extends Pick<LinkRegistryParams, "registry" | "condit
  * @return any new declaration elements found (they will need to be emitted)
  */
 declare function bindIdents(params: BindIdentsParams): BindResults;
-/** bind local references in library sources to reveal references to external packages */
-declare function findUnboundIdents(registry: ParsedRegistry): string[][];
 /**
  * Find all conditionally valid declarations at the root level.
  * Declarations are either directly in the root scope or in conditionally valid partial scopes.
@@ -821,6 +872,43 @@ declare function findValidRootDecls(rootScope: Scope, conditions: Conditions): D
 declare function publicDecl(scope: Scope, name: string, conditions: Conditions): DeclIdent | undefined;
 /** @return true if this decl is at the root scope level of a module */
 declare function isGlobal(declIdent: DeclIdent): boolean;
+/** state used during the recursive scope tree walk to bind references to declarations */
+interface BindContext {
+  resolver: ModuleResolver;
+  conditions: Record<string, any>;
+  /** decl idents discovered so far (to avoid re-traversing) */
+  knownDecls: Set<DeclIdent>;
+  /** save work by not processing scopes multiple times */
+  foundScopes: Set<Scope>;
+  /** root level names used so far (enables manglers/plugins to pick unique names) */
+  globalNames: Set<string>;
+  /** additional global statements to emit (e.g. module level const_assert, indexed by elem for uniqueness) */
+  globalStatements: Map<AbstractElem, EmittableElem>;
+  /** construct unique identifer names for global declarations */
+  mangler: ManglerFn;
+  virtuals?: VirtualLibrarySet;
+  /** list of unbound identifiers if accumulateUnbound is true */
+  unbound?: string[][];
+  /** don't follow references from declarations (used for library dependency detection) */
+  dontFollowDecls?: boolean;
+}
+/**
+ * Recursively bind references to declarations in this scope and
+ * any child scopes referenced by these declarations.
+ * Uses a hash set of found declarations to avoid duplication.
+ *
+ * IMPORTANT: This function tracks @else state while traversing sibling scopes.
+ * When an @if scope is processed, its validity determines whether the following
+ * @else scope should be considered valid. This ensures that references from
+ * filtered @else blocks don't pull in unused declarations.
+ *
+ * @return any new declarations found
+ * @param liveDecls current set of live declaration in this scope
+ *  (empty when traversing to a new scope, possibly non-empty for a partial scope)
+ * @param isRoot liveDecls refers to a prepopulated root scope
+ *  (root scope declarations may appear in any order)
+ */
+declare function bindIdentsRecursive(scope: Scope, bindContext: BindContext, liveDecls: LiveDecls, isRoot?: boolean): DeclIdent[];
 //#endregion
 //#region src/debug/ASTtoString.d.ts
 declare function astToString(elem: AbstractElem, indent?: number): string;
@@ -974,4 +1062,4 @@ declare function offsetToLineNumber(offset: number, text: string): [lineNum: num
  */
 declare function errorHighlight(source: string, span: Span): [string, string];
 //#endregion
-export { AbstractElem, AbstractElemBase, AliasElem, Attribute, AttributeElem, BinaryExpression, BinaryOperator, BindIdentsParams, BindResults, BindingAST, BindingStructElem, BoundAndTransformed, BuiltinAttribute, ComponentExpression, ComponentMemberExpression, Conditions, ConstAssertElem, ConstElem, ContainerElem, DeclIdent, DeclIdentElem, DeclarationElem, DiagnosticAttribute, DiagnosticDirective, DirectiveElem, DirectiveVariant, ElemWithAttributes, ElemWithContentsBase, ElifAttribute, ElseAttribute, EmittableElem, EnableDirective, ExpressionElem, ExtendedGPUValidationError, FnElem, FnParamElem, FunctionCallExpression, GlobalDeclarationElem, GlobalVarElem, GrammarElem, HasAttributes, Ident, IfAttribute, ImportCollection, ImportElem, ImportItem, ImportSegment, ImportStatement, InterpolateAttribute, LetElem, LexicalScope, LinkConfig, LinkParams, LinkRegistryParams, LinkedWesl, LinkerTransform, Literal, ManglerFn, ModuleElem, NameElem, OverrideElem, ParenthesizedExpression, ParsedRegistry, PartialScope, RefIdent, RefIdentElem, RequiresDirective, Scope, SimpleMemberRef, SrcModule, StableState, StandardAttribute, StatementElem, StructElem, StructMemberElem, StuffElem, SwitchClauseElem, SyntheticElem, TerminalElem, TextElem, TransformedAST, TranslateTimeExpressionElem, TranslateTimeFeature, TypeRefElem, TypeTemplateParameter, TypedDeclElem, UnaryExpression, UnaryOperator, UnknownExpressionElem, VarElem, VirtualLibrary, VirtualLibraryFn, VirtualLibrarySet, WeslAST, WeslBundle, WeslDevice, WeslGPUCompilationInfo, WeslGPUCompilationMessage, WeslJsPlugin, WeslParseContext, WeslParseError, WeslParseState, WeslStream, _linkSync, astToString, attributeToString, bindAndTransform, bindIdents, bindingStructsPlugin, blankWeslParseState, childIdent, childScope, containsScope, debugContentsToString, emptyScope, errorHighlight, filterMap, findMap, findRefsToBindingStructs, findUnboundIdents, findValidRootDecls, flatImports, groupBy, grouped, identToString, isGlobal, last, lengthPrefixMangle, link, linkRegistry, lowerBindingStructs, makeWeslDevice, mapForward, mapValues, markBindingStructs, markEntryTypes, mergeScope, minimalMangle, minimallyMangledName, multiKeySet, nextIdentId, noSuffix, normalize, offsetToLineNumber, overlapTail, parseIntoRegistry, parseLibsIntoRegistry, parseSrcModule, parsedRegistry, partition, publicDecl, registryToString, replaceWords, requestWeslDevice, resetScopeIds, scan, scopeToString, scopeToStringLong, selectModule, syntheticWeslParseState, transformBindingReference, transformBindingStruct, underscoreMangle };
+export { AbstractElem, AbstractElemBase, AliasElem, Attribute, AttributeElem, BatchModuleResolver, BinaryExpression, BinaryOperator, BindIdentsParams, BindResults, BindingAST, BindingStructElem, BoundAndTransformed, BuiltinAttribute, BundleResolver, ComponentExpression, ComponentMemberExpression, CompositeResolver, Conditions, ConstAssertElem, ConstElem, ContainerElem, DeclIdent, DeclIdentElem, DeclarationElem, DiagnosticAttribute, DiagnosticDirective, DirectiveElem, DirectiveVariant, ElemWithAttributes, ElemWithContentsBase, ElifAttribute, ElseAttribute, EmittableElem, EnableDirective, ExpressionElem, ExtendedGPUValidationError, FnElem, FnParamElem, FunctionCallExpression, GlobalDeclarationElem, GlobalVarElem, GrammarElem, HasAttributes, Ident, IfAttribute, ImportCollection, ImportElem, ImportItem, ImportSegment, ImportStatement, InterpolateAttribute, LetElem, LexicalScope, LinkConfig, LinkParams, LinkRegistryParams, LinkedWesl, LinkerTransform, Literal, LiveDecls, ManglerFn, ModuleElem, ModuleResolver, NameElem, OverrideElem, ParenthesizedExpression, PartialScope, RecordResolver, RecordResolverOptions, RefIdent, RefIdentElem, RequiresDirective, Scope, SimpleMemberRef, SrcModule, StableState, StandardAttribute, StatementElem, StructElem, StructMemberElem, StuffElem, SwitchClauseElem, SyntheticElem, TerminalElem, TextElem, TransformedAST, TranslateTimeExpressionElem, TranslateTimeFeature, TypeRefElem, TypeTemplateParameter, TypedDeclElem, UnaryExpression, UnaryOperator, UnknownExpressionElem, VarElem, VirtualLibrary, VirtualLibraryFn, VirtualLibrarySet, WeslAST, WeslBundle, WeslDevice, WeslGPUCompilationInfo, WeslGPUCompilationMessage, WeslJsPlugin, WeslParseContext, WeslParseError, WeslParseState, WeslStream, _linkSync, astToString, attributeToString, bindAndTransform, bindIdents, bindIdentsRecursive, bindingStructsPlugin, blankWeslParseState, childIdent, childScope, containsScope, debugContentsToString, emptyScope, errorHighlight, filterMap, findMap, findRefsToBindingStructs, findValidRootDecls, flatImports, groupBy, grouped, identToString, isGlobal, last, lengthPrefixMangle, link, linkRegistry, liveDeclsToString, lowerBindingStructs, makeLiveDecls, makeWeslDevice, mapForward, mapValues, markBindingStructs, markEntryTypes, mergeScope, minimalMangle, minimallyMangledName, multiKeySet, nextIdentId, noSuffix, normalize, normalizeModuleName, offsetToLineNumber, overlapTail, parseSrcModule, partition, publicDecl, replaceWords, requestWeslDevice, resetScopeIds, scan, scopeToString, scopeToStringLong, syntheticWeslParseState, transformBindingReference, transformBindingStruct, underscoreMangle };