wesl 0.7.21 → 0.7.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wesl",
-  "version": "0.7.21",
+  "version": "0.7.23",
   "type": "module",
   "files": [
     "dist",
@@ -26,14 +26,6 @@
     "typedoc-theme-hierarchy": "^6.0.0",
     "wrangler": "^4.22.0"
   },
-  "peerDependencies": {
-    "random_wgsl": "^0.6.69"
-  },
-  "peerDependenciesMeta": {
-    "random_wgsl": {
-      "optional": true
-    }
-  },
   "license": "MIT",
   "keywords": [
     "webgpu",

package/src/BindIdents.ts

@@ -16,29 +16,17 @@ import type {
   LexicalScope,
   RefIdent,
   Scope,
+  ScopeItem,
   SrcModule,
 } from "./Scope.ts";
-import { stdEnumerant, stdFn, stdType } from "./StandardTypes.ts";
+import {
+  stdEnumerant,
+  stdFn,
+  stdType,
+  wgslStandardAttributes,
+} from "./StandardTypes.ts";
 import { last } from "./Util.ts";
 
-/** WGSL standard attributes whose params need binding (e.g., @workgroup_size). */
-const wgslStandardAttributes = new Set([
-  "align",
-  "binding",
-  "blend_src",
-  "compute",
-  "const",
-  "fragment",
-  "group",
-  "id",
-  "invariant",
-  "location",
-  "must_use",
-  "size",
-  "vertex",
-  "workgroup_size",
-]);
-
 /**
  * BindIdents pass: link reference identifiers to declarations.
  *
@@ -112,16 +100,22 @@ export interface BindIdentsParams
 
   /** If true, accumulate unbound identifiers into BindResults.unbound instead of throwing. */
   accumulateUnbound?: true;
+
+  /** Visit all conditional branches (for dependency discovery). */
+  discoveryMode?: boolean;
 }
 
 /** Bind ref idents to declarations and mangle global declaration names. */
 export function bindIdents(params: BindIdentsParams): BindResults {
   const { rootAst, resolver, virtuals, accumulateUnbound } = params;
   const { conditions = {}, mangler = minimalMangle } = params;
+  const { discoveryMode } = params;
   const packageName = rootAst.srcModule.modulePath.split("::")[0];
 
-  const validRootDecls = findValidRootDecls(rootAst.rootScope, conditions);
-  const { globalNames, knownDecls } = initRootDecls(validRootDecls);
+  const rootDecls = discoveryMode
+    ? findAllRootDecls(rootAst.rootScope)
+    : findValidRootDecls(rootAst.rootScope, conditions);
+  const { globalNames, knownDecls } = initRootDecls(rootDecls);
 
   const bindContext = {
     resolver,
@@ -134,13 +128,13 @@ export function bindIdents(params: BindIdentsParams): BindResults {
     globalNames,
     globalStatements: new Map<AbstractElem, EmittableElem>(),
     unbound: accumulateUnbound ? [] : undefined,
+    discoveryMode,
   };
 
-  const decls = new Map(validRootDecls.map(d => [d.originalName, d] as const));
+  const decls = new Map(rootDecls.map(d => [d.originalName, d] as const));
   const liveDecls: LiveDecls = { decls, parent: null };
 
-  // Process dependent scopes for all valid root decls (already filtered by conditions)
-  const fromRootDecls = validRootDecls.flatMap(decl =>
+  const fromRootDecls = rootDecls.flatMap(decl =>
     processDependentScope(decl, bindContext),
   );
 
@@ -195,12 +189,12 @@ export function findValidRootDecls(
   rootScope: Scope,
   conditions: Conditions,
 ): DeclIdent[] {
-  const found: DeclIdent[] = [];
-  for (const item of validItems(rootScope, conditions)) {
-    if (item.kind === "decl") found.push(item);
-    else if (item.kind === "partial") collectDecls(item, found);
-  }
-  return found;
+  return collectDecls(validItems(rootScope, conditions));
+}
+
+/** Find all declarations at the root level, ignoring conditions. */
+export function findAllRootDecls(rootScope: Scope): DeclIdent[] {
+  return collectDecls(rootScope.contents);
 }
 
 /** Find a public declaration with the given original name. */
@@ -244,6 +238,9 @@ interface BindContext {
 
   /** Don't follow references from declarations (for library dependency detection). */
   dontFollowDecls?: boolean;
+
+  /** Visit all conditional branches (for dependency discovery). */
+  discoveryMode?: boolean;
 }
 
 /**
@@ -277,7 +274,10 @@ function processScope(
   const newGlobals: DeclIdent[] = [];
   const newFromChildren: DeclIdent[] = [];
 
-  for (const child of validItems(scope, bindContext.conditions)) {
+  const items = bindContext.discoveryMode
+    ? scope.contents
+    : validItems(scope, bindContext.conditions);
+  for (const child of items) {
     if (child.kind === "decl") {
       liveDecls.decls.set(child.originalName, child);
     } else if (child.kind === "ref") {
@@ -337,6 +337,7 @@ function handleRef(
     failIdent(ident, `unresolved identifier '${ident.originalName}'`);
 }
 
+/** Follow new global declarations into their dependent scopes. */
 function handleDecls(
   newGlobals: DeclIdent[],
   bindContext: BindContext,
@@ -344,7 +345,7 @@ function handleDecls(
   return newGlobals.flatMap(decl => processDependentScope(decl, bindContext));
 }
 
-/** If found declaration is new, mangle its name. Return if it's a global declaration. */
+/** If found declaration is new, mangle its name. @return the decl if it's global. */
 function handleNewDecl(
   refIdent: RefIdent,
   foundDecl: FoundDecl,
@@ -380,8 +381,9 @@ function findQualifiedImport(
   refIdent: RefIdent,
   ctx: BindContext,
 ): FoundDecl | undefined {
-  const { conditions, unbound } = ctx;
-  const flatImps = flatImports(refIdent.ast, conditions);
+  const { conditions, unbound, discoveryMode } = ctx;
+  const conds = discoveryMode ? undefined : conditions;
+  const flatImps = flatImports(refIdent.ast, conds);
   const identParts = refIdent.originalName.split("::");
   const pathParts =
     matchingImport(identParts, flatImps) ?? qualifiedIdent(identParts);
@@ -471,9 +473,7 @@ function getValidRootDecls(
   conditions: Conditions,
 ): DeclIdent[] {
   const lexScope = rootScope as LexicalScope;
-  if (!lexScope._validRootDecls) {
-    lexScope._validRootDecls = findValidRootDecls(rootScope, conditions);
-  }
+  lexScope._validRootDecls ??= findValidRootDecls(rootScope, conditions);
   return lexScope._validRootDecls;
 }
 
@@ -485,9 +485,7 @@ function rootLiveDecls(
   assertThatDebug(decl.isGlobal, identToString(decl));
 
   let scope = decl.containingScope;
-  while (scope.parent) {
-    scope = scope.parent;
-  }
+  while (scope.parent) scope = scope.parent;
   assertThatDebug(scope.kind === "scope");
 
   const root = scope as LexicalScope;
@@ -524,14 +522,17 @@ function stdWgsl(name: string): boolean {
   return stdType(name) || stdFn(name) || stdEnumerant(name); // TODO add tests for enumerants case (e.g. var x = read;)
 }
 
+/** @return identParts if it's a qualified path (has ::). */
 function qualifiedIdent(identParts: string[]): string[] | undefined {
   if (identParts.length > 1) return identParts;
 }
 
-/** Collect all declarations in a scope (used when scope is already validated). */
-function collectDecls(scope: Scope, found: DeclIdent[]): void {
-  for (const item of scope.contents) {
-    if (item.kind === "decl") found.push(item);
-    else if (item.kind === "partial") collectDecls(item, found);
-  }
+/** Collect all declarations from scope items, recursing into partial scopes. */
+function collectDecls(items: Iterable<ScopeItem>): DeclIdent[] {
+  return [...items].flatMap(item => {
+    const { kind } = item;
+    if (kind === "decl") return [item];
+    if (kind === "partial") return collectDecls(item.contents);
+    return [];
+  });
 }

package/src/LowerAndEmit.ts

@@ -18,6 +18,7 @@ import { filterValidElements } from "./Conditions.ts";
 import { identToString } from "./debug/ScopeToString.ts";
 import type { Conditions, DeclIdent, Ident } from "./Scope.ts";
 import type { SrcMapBuilder } from "./SrcMap.ts";
+import { wgslStandardAttributes } from "./StandardTypes.ts";
 
 export interface EmitParams {
   srcBuilder: SrcMapBuilder;
@@ -36,26 +37,6 @@ interface EmitContext {
   extracting: boolean;
 }
 
-/** Valid WGSL standard attributes (from spec). Non-WGSL attributes are stripped.
- * See: https://www.w3.org/TR/WGSL/#attributes
- * Note: @builtin, @diagnostic, @interpolate are parsed as separate attribute types. */
-const wgslStandardAttributes = new Set([
-  "align",
-  "binding",
-  "blend_src",
-  "compute",
-  "const",
-  "fragment",
-  "group",
-  "id",
-  "invariant",
-  "location",
-  "must_use",
-  "size",
-  "vertex",
-  "workgroup_size",
-]);
-
 /** Traverse the AST, starting from root elements, emitting WGSL for each. */
 export function lowerAndEmit(params: EmitParams): void {
   const { srcBuilder, rootElems, conditions } = params;

package/src/Scope.ts

@@ -23,6 +23,8 @@ export interface SrcModule {
 /** a src declaration or reference to an ident */
 export type Ident = DeclIdent | RefIdent;
 
+export type ScopeItem = Ident | Scope;
+
 /** LATER change this to a Map, so that `toString` isn't accidentally a condition */
 export type Conditions = Record<string, boolean>;
 
@@ -106,7 +108,7 @@ interface ScopeBase {
   parent: Scope | null;
 
   /* Child scopes and idents in lexical order  */
-  contents: (Ident | Scope)[];
+  contents: ScopeItem[];
 
   /** Conditional attribute (@if or @else) for this scope */
   condAttribute?: IfAttribute | ElifAttribute | ElseAttribute;

package/src/StandardTypes.ts

@@ -81,6 +81,25 @@ export const stdEnumerants = `read write read_write
   the texture format names with e.g. a 'struct rbga8unorm .)
 */
 
+/** WGSL standard attributes whose params need binding (e.g., @workgroup_size).
+ * See: https://www.w3.org/TR/WGSL/#attributes */
+export const wgslStandardAttributes = new Set([
+  "align",
+  "binding",
+  "blend_src",
+  "compute",
+  "const",
+  "fragment",
+  "group",
+  "id",
+  "invariant",
+  "location",
+  "must_use",
+  "size",
+  "vertex",
+  "workgroup_size",
+]);
+
 /** return true if the name is for a built in type (not a user struct) */
 export function stdType(name: string): boolean {
   return stdTypes.includes(name);

package/src/discovery/FindUnboundIdents.ts

@@ -1,13 +1,19 @@
 import type { AbstractElem } from "../AbstractElems.ts";
 import {
+  bindIdents,
   bindIdentsRecursive,
   type EmittableElem,
-  findValidRootDecls,
+  findAllRootDecls,
   type UnboundRef,
 } from "../BindIdents.ts";
 import { type LiveDecls, makeLiveDecls } from "../LiveDeclarations.ts";
 import { minimalMangle } from "../Mangler.ts";
-import type { BatchModuleResolver } from "../ModuleResolver.ts";
+import {
+  type BatchModuleResolver,
+  fileToModulePath,
+  type ModuleResolver,
+} from "../ModuleResolver.ts";
+import type { WeslAST } from "../ParseWESL.ts";
 import type { DeclIdent, Scope } from "../Scope.ts";
 import { filterMap } from "../Util.ts";
 
@@ -38,22 +44,75 @@ export function findUnboundRefs(resolver: BatchModuleResolver): UnboundRef[] {
     packageName: "package",
     unbound: [] as UnboundRef[],
     dontFollowDecls: true,
+    discoveryMode: true,
   };
 
   for (const [, ast] of resolver.allModules()) {
-    const rootDecls = findValidRootDecls(ast.rootScope, {});
-    const liveDecls: LiveDecls = {
-      decls: new Map(rootDecls.map(d => [d.originalName, d] as const)),
-      parent: null,
-    };
+    const rootDecls = findAllRootDecls(ast.rootScope);
+    const decls = new Map(rootDecls.map(d => [d.originalName, d] as const));
+    const liveDecls: LiveDecls = { decls, parent: null };
     // Process dependent scopes of root decls to find unbound refs in function bodies
-    const scopes = filterMap(rootDecls, decl => decl.dependentScope);
-    scopes.forEach(s => {
+    for (const s of filterMap(rootDecls, decl => decl.dependentScope)) {
       bindIdentsRecursive(s, bindContext, makeLiveDecls(liveDecls));
-    });
+    }
     // Also process refs at root scope level
     bindIdentsRecursive(ast.rootScope, bindContext, liveDecls);
   }
 
   return bindContext.unbound;
 }
+
+/** Thin decorator that records which modules were resolved. */
+export class TrackingResolver implements ModuleResolver {
+  readonly visited = new Set<string>();
+  #inner: ModuleResolver;
+  constructor(inner: ModuleResolver) {
+    this.#inner = inner;
+  }
+
+  resolveModule(modulePath: string): WeslAST | undefined {
+    const ast = this.#inner.resolveModule(modulePath);
+    if (ast) this.visited.add(modulePath);
+    return ast;
+  }
+}
+
+/**
+ * Discover reachable modules and unbound external refs from a single root.
+ *
+ * Traces the import graph from `rootModuleName`, returning only the reachable
+ * local modules in `weslSrc` and unresolved external references in `unbound`.
+ */
+export function discoverModules(
+  weslSrc: Record<string, string>,
+  resolver: ModuleResolver,
+  rootModuleName: string,
+  packageName = "package",
+): { weslSrc: Record<string, string>; unbound: string[][] } {
+  const tracking = new TrackingResolver(resolver);
+  const rootAst = tracking.resolveModule(rootModuleName);
+  if (!rootAst) {
+    throw new Error(`root module not found: '${rootModuleName}'`);
+  }
+
+  const result = bindIdents({
+    rootAst,
+    resolver: tracking,
+    accumulateUnbound: true,
+    discoveryMode: true,
+  });
+
+  const moduleToKey = new Map(
+    Object.keys(weslSrc).map(
+      key => [fileToModulePath(key, packageName, false), key] as const,
+    ),
+  );
+
+  const reachable = [...tracking.visited]
+    .map(m => moduleToKey.get(m))
+    .filter(key => key !== undefined)
+    .map(key => [key, weslSrc[key]] as const);
+
+  const unbound = (result.unbound ?? []).map(ref => ref.path);
+  return { weslSrc: Object.fromEntries(reachable), unbound };
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./AbstractElems.ts";
 export * from "./BindIdents.ts";
+export { filterValidElements } from "./Conditions.ts";
 export * from "./debug/ASTtoString.ts";
 export * from "./debug/ScopeToString.ts";
 export * from "./discovery/FindUnboundIdents.ts";

package/src/test/DiscoverModules.test.ts

@@ -0,0 +1,113 @@
+import { expect, test } from "vitest";
+import { discoverModules } from "../discovery/FindUnboundIdents.ts";
+import { RecordResolver } from "../ModuleResolver.ts";
+
+test("discoverModules returns only reachable modules", () => {
+  const weslSrc: Record<string, string> = {
+    "main.wesl": `
+      import package::util::helper;
+      fn main() { helper(); }
+    `,
+    "util.wesl": `fn helper() {}`,
+    "unused.wesl": `fn unused() {}`,
+  };
+  const result = discoverModules(
+    weslSrc,
+    new RecordResolver(weslSrc),
+    "package::main",
+  );
+  const keys = Object.keys(result.weslSrc);
+
+  expect(keys).toContain("main.wesl");
+  expect(keys).toContain("util.wesl");
+  expect(keys).not.toContain("unused.wesl");
+});
+
+test("discoverModules finds unbound external refs", () => {
+  const weslSrc: Record<string, string> = {
+    "main.wesl": `
+      import ext_pkg::dep;
+      fn main() { dep(); }
+    `,
+  };
+  const result = discoverModules(
+    weslSrc,
+    new RecordResolver(weslSrc),
+    "package::main",
+  );
+  expect(result.unbound).toContainEqual(["ext_pkg", "dep"]);
+});
+
+test("discoverModules finds refs in conditional branches", () => {
+  const weslSrc: Record<string, string> = {
+    "main.wesl": `
+      import package::a;
+      import package::b;
+      fn main() {
+        @if(feature) a::run();
+        @else b::run();
+      }
+    `,
+    "a.wesl": `
+      import ext_a::dep;
+      fn run() { dep(); }
+    `,
+    "b.wesl": `
+      import ext_b::dep;
+      fn run() { dep(); }
+    `,
+    "unused.wesl": `fn unused() {}`,
+  };
+  const result = discoverModules(
+    weslSrc,
+    new RecordResolver(weslSrc),
+    "package::main",
+  );
+  const keys = Object.keys(result.weslSrc);
+
+  expect(keys).toContain("a.wesl");
+  expect(keys).toContain("b.wesl");
+  expect(keys).not.toContain("unused.wesl");
+
+  expect(result.unbound).toContainEqual(["ext_a", "dep"]);
+  expect(result.unbound).toContainEqual(["ext_b", "dep"]);
+});
+
+test("discoverModules excludes modules only reachable from other roots", () => {
+  const weslSrc: Record<string, string> = {
+    "main.wesl": `
+      import package::shared;
+      fn main() { shared::helper(); }
+    `,
+    "other.wesl": `
+      import package::only_other;
+      fn other() { only_other::run(); }
+    `,
+    "shared.wesl": `fn helper() {}`,
+    "only_other.wesl": `fn run() {}`,
+  };
+  const result = discoverModules(
+    weslSrc,
+    new RecordResolver(weslSrc),
+    "package::main",
+  );
+  const keys = Object.keys(result.weslSrc);
+
+  expect(keys).toContain("main.wesl");
+  expect(keys).toContain("shared.wesl");
+  expect(keys).not.toContain("other.wesl");
+  expect(keys).not.toContain("only_other.wesl");
+});
+
+test("discoverModules with single-file project", () => {
+  const weslSrc: Record<string, string> = {
+    "main.wesl": `fn main() { let x = 1; }`,
+  };
+  const result = discoverModules(
+    weslSrc,
+    new RecordResolver(weslSrc),
+    "package::main",
+  );
+  expect(Object.keys(result.weslSrc)).toEqual(["main.wesl"]);
+  expect(result.unbound).toEqual([]);
+});

package/src/test/FindUnboundIdents.test.ts

@@ -0,0 +1,71 @@
+import { expect, test } from "vitest";
+import { findUnboundIdents } from "../discovery/FindUnboundIdents.ts";
+import { RecordResolver } from "../ModuleResolver.ts";
+
+test("ref inside @if block is discovered", () => {
+  const srcs = {
+    "./test.wesl": `
+      import package::util::helper;
+      fn main() {
+        @if(feature) helper();
+      }
+    `,
+    "./util.wesl": `
+      import ext_pkg::dep;
+      fn helper() { dep(); }
+    `,
+  };
+  const resolver = new RecordResolver(srcs);
+  const unbound = findUnboundIdents(resolver);
+  expect(unbound).toContainEqual(["ext_pkg", "dep"]);
+});
+
+test("ref inside @else block is discovered", () => {
+  const srcs = {
+    "./test.wesl": `
+      import package::util::a;
+      import package::util::b;
+      fn main() {
+        @if(feature) a();
+        @else b();
+      }
+    `,
+    "./util.wesl": `
+      import ext_pkg::dep;
+      fn a() { }
+      fn b() { dep(); }
+    `,
+  };
+  const resolver = new RecordResolver(srcs);
+  const unbound = findUnboundIdents(resolver);
+  expect(unbound).toContainEqual(["ext_pkg", "dep"]);
+});
+
+test("import declaration inside @if block is discovered", () => {
+  const srcs = {
+    "./test.wesl": `
+      @if(feature)
+      import ext_pkg::mod::helper;
+
+      fn main() {
+        @if(feature) helper();
+      }
+    `,
+  };
+  const resolver = new RecordResolver(srcs);
+  const unbound = findUnboundIdents(resolver);
+  expect(unbound).toContainEqual(["ext_pkg", "mod", "helper"]);
+});
+
+test("inline qualified ref inside @if is discovered", () => {
+  const srcs = {
+    "./test.wesl": `
+      fn main() {
+        @if(feature) ext_pkg::mod::helper();
+      }
+    `,
+  };
+  const resolver = new RecordResolver(srcs);
+  const unbound = findUnboundIdents(resolver);
+  expect(unbound).toContainEqual(["ext_pkg", "mod", "helper"]);
+});

package/src/test/LinkPackage.test.ts

@@ -1,30 +1,36 @@
 import second from "multi_pkg/second";
 import trans from "multi_pkg/transitive";
-import rand from "random_wgsl";
 import { expect, test } from "vitest";
 import { link } from "../Linker.ts";
+import type { WeslBundle } from "../WeslBundle.ts";
 import { expectNoLogAsync } from "./LogCatcher.ts";
 
-test("import rand() from a package", async () => {
-  const src = `
-    import random_wgsl::pcg_2u_3f; 
+// Static fixture bundle - no external package dependency needed
+const hashPkg: WeslBundle = {
+  name: "hash_pkg",
+  edition: "unstable_2025_1",
+  modules: {
+    "hash.wesl":
+      "fn hashFn(v: u32) -> u32 { return v ^ (v >> 16u); }\nfn unusedFn() { }",
+  },
+};
 
-    struct Uniforms { frame: u32 }
-    @binding(0) @group(0) var<uniform> u: Uniforms;
+test("import fn from a package bundle", async () => {
+  const src = `
+    import hash_pkg::hash::hashFn;
 
-    @fragment
-    fn fragmentMain(@builtin(position) pos: vec4f) -> @location(0) vec4f {
-        let rand = pcg_2u_3f(vec2u(pos.xy) + u.frame);
-        return vec4(rand, 1f);
-    }
+    @compute @workgroup_size(1)
+    fn main() { let x = hashFn(1u); }
   `;
-
-  const weslSrc = { "./main.wesl": src };
-  const result = await expectNoLogAsync(async () =>
-    link({ weslSrc, rootModuleName: "./main.wesl", libs: [rand] }),
+  const result = await expectNoLogAsync(() =>
+    link({
+      weslSrc: { "./main.wesl": src },
+      rootModuleName: "./main.wesl",
+      libs: [hashPkg],
+    }),
   );
-  expect(result.dest).toContain("fn pcg_2u_3f");
-  expect(result.dest).not.toContain("sinRand");
+  expect(result.dest).toContain("fn hashFn");
+  expect(result.dest).not.toContain("unusedFn");
 });
 
 test("import from multi_pkg/second", async () => {