wesl 0.7.22 → 0.7.23

package/dist/index.d.ts

@@ -171,6 +171,7 @@ interface SrcModule {
 }
 /** a src declaration or reference to an ident */
 type Ident = DeclIdent | RefIdent;
+type ScopeItem = Ident | Scope;
 /** LATER change this to a Map, so that `toString` isn't accidentally a condition */
 type Conditions = Record<string, boolean>;
 interface IdentBase {
@@ -229,7 +230,7 @@ interface ScopeBase {
   id: number;
   /** null for root scope in a module */
   parent: Scope | null;
-  contents: (Ident | Scope)[];
+  contents: ScopeItem[];
   /** Conditional attribute (@if or @else) for this scope */
   condAttribute?: IfAttribute | ElifAttribute | ElseAttribute;
 }
@@ -976,6 +977,8 @@ interface BindIdentsParams extends Pick<LinkRegistryParams, "resolver" | "condit
   virtuals?: VirtualLibrarySet;
   /** 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. */
 declare function bindIdents(params: BindIdentsParams): BindResults;
@@ -1016,6 +1019,17 @@ interface BindContext {
  */
 declare function bindIdentsRecursive(scope: Scope, bindContext: BindContext, liveDecls: LiveDecls): DeclIdent[];
 //#endregion
+//#region src/Conditions.d.ts
+/**
+ * Filter elements based on @if/@else conditional logic.
+ * This function processes elements sequentially to handle @if/@else chains correctly.
+ *
+ * @param elements Array of elements at the same scope level
+ * @param conditions Current conditional compilation settings
+ * @return Array of valid elements after applying @if/@else logic
+ */
+declare function filterValidElements<T extends AbstractElem>(elements: readonly T[], conditions: Conditions): T[];
+//#endregion
 //#region src/debug/ASTtoString.d.ts
 declare function astToString(elem: AbstractElem, indent?: number): string;
 /** @return string representation of an attribute (for test/debug) */
@@ -1043,6 +1057,23 @@ declare function identToString(ident?: Ident): string;
 declare function findUnboundIdents(resolver: BatchModuleResolver): string[][];
 /** Find unbound references with full position info. */
 declare function findUnboundRefs(resolver: BatchModuleResolver): UnboundRef[];
+/** Thin decorator that records which modules were resolved. */
+declare class TrackingResolver implements ModuleResolver {
+  #private;
+  readonly visited: Set<string>;
+  constructor(inner: ModuleResolver);
+  resolveModule(modulePath: string): WeslAST | undefined;
+}
+/**
+ * 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`.
+ */
+declare function discoverModules(weslSrc: Record<string, string>, resolver: ModuleResolver, rootModuleName: string, packageName?: string): {
+  weslSrc: Record<string, string>;
+  unbound: string[][];
+};
 //#endregion
 //#region src/discovery/PackageNameUtils.d.ts
 /** Package name sanitization for WESL.
@@ -1139,6 +1170,9 @@ declare const textureStorageTypes = "\n  texture_storage_1d texture_storage_2d t
 declare const stdTypes: string[];
 /** https://www.w3.org/TR/WGSL/#predeclared-enumerants  */
 declare const stdEnumerants: string[];
+/** WGSL standard attributes whose params need binding (e.g., @workgroup_size).
+ * See: https://www.w3.org/TR/WGSL/#attributes */
+declare const wgslStandardAttributes: Set<string>;
 /** return true if the name is for a built in type (not a user struct) */
 declare function stdType(name: string): boolean;
 /** return true if the name is for a built in fn (not a user function) */
@@ -1241,4 +1275,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, BatchModuleResolver, BinaryExpression, BinaryOperator, BindIdentsParams, BindResults, BindingAST, BindingStructElem, BlockStatement, BoundAndTransformed, BuiltinAttribute, BundleResolver, ComponentExpression, ComponentMemberExpression, CompositeResolver, ConditionalAttribute, Conditions, ConstAssertElem, ConstElem, ContainerElem, ContinuingElem, DeclIdent, DeclIdentElem, DeclarationElem, DiagnosticAttribute, DiagnosticDirective, DiagnosticRule, DirectiveElem, DirectiveVariant, ElemKindMap, 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, OpenElem, OverrideElem, ParenthesizedExpression, ParseError, type ParseOptions, PartialScope, RecordResolver, RecordResolverOptions, RefIdent, RefIdentElem, RequiresDirective, Scope, SimpleMemberRef, Span, SrcMap, SrcMapBuilder, SrcMapEntry, SrcModule, SrcPosition, SrcWithPath, StableState, StandardAttribute, StatementElem, StructElem, StructMemberElem, StuffElem, SwitchClauseElem, SyntheticElem, TerminalElem, TextElem, TransformedAST, TranslateTimeExpressionElem, TypeRefElem, TypeTemplateParameter, TypedDeclElem, UnaryExpression, UnaryOperator, UnboundRef, UnknownExpressionElem, VarElem, VirtualLibrary, VirtualLibraryFn, VirtualLibrarySet, WeslAST, WeslBundle, WeslDevice, WeslGPUCompilationInfo, WeslGPUCompilationMessage, WeslJsPlugin, WeslParseContext, WeslParseError, WeslParseState, WeslStream, _linkSync, astToString, attributeToString, bindAndTransform, bindIdents, bindIdentsRecursive, bindingStructsPlugin, childIdent, childScope, containsScope, debug, debugContentsToString, emptyScope, errorHighlight, fileToModulePath, filterMap, findAllRootDecls, findMap, findRefsToBindingStructs, findUnboundIdents, findUnboundRefs, findValidRootDecls, flatImports, groupBy, grouped, identToString, last, lengthPrefixMangle, link, linkRegistry, liveDeclsToString, log, lowerBindingStructs, makeLiveDecls, makeWeslDevice, mapForward, mapValues, markBindingStructs, markEntryTypes, mergeScope, minimalMangle, minimallyMangledName, modulePartsToRelativePath, moduleToRelativePath, multiKeySet, multisampledTextureTypes, nextIdentId, noSuffix, normalize, normalizeDebugRoot, normalizeModuleName, npmNameVariations, offsetToLineNumber, overlapTail, parseSrcModule, partition, publicDecl, replaceWords, requestWeslDevice, resetScopeIds, resolveModulePath, sampledTextureTypes, sanitizePackageName, scan, scopeToString, scopeToStringLong, srcLog, stdEnumerant, stdEnumerants, stdFn, stdFns, stdType, stdTypes, textureStorageTypes, transformBindingReference, transformBindingStruct, underscoreMangle, validation, withLoggerAsync };
+export { AbstractElem, AbstractElemBase, AliasElem, Attribute, AttributeElem, BatchModuleResolver, BinaryExpression, BinaryOperator, BindIdentsParams, BindResults, BindingAST, BindingStructElem, BlockStatement, BoundAndTransformed, BuiltinAttribute, BundleResolver, ComponentExpression, ComponentMemberExpression, CompositeResolver, ConditionalAttribute, Conditions, ConstAssertElem, ConstElem, ContainerElem, ContinuingElem, DeclIdent, DeclIdentElem, DeclarationElem, DiagnosticAttribute, DiagnosticDirective, DiagnosticRule, DirectiveElem, DirectiveVariant, ElemKindMap, 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, OpenElem, OverrideElem, ParenthesizedExpression, ParseError, type ParseOptions, PartialScope, RecordResolver, RecordResolverOptions, RefIdent, RefIdentElem, RequiresDirective, Scope, ScopeItem, SimpleMemberRef, Span, SrcMap, SrcMapBuilder, SrcMapEntry, SrcModule, SrcPosition, SrcWithPath, StableState, StandardAttribute, StatementElem, StructElem, StructMemberElem, StuffElem, SwitchClauseElem, SyntheticElem, TerminalElem, TextElem, TrackingResolver, TransformedAST, TranslateTimeExpressionElem, TypeRefElem, TypeTemplateParameter, TypedDeclElem, UnaryExpression, UnaryOperator, UnboundRef, UnknownExpressionElem, VarElem, VirtualLibrary, VirtualLibraryFn, VirtualLibrarySet, WeslAST, WeslBundle, WeslDevice, WeslGPUCompilationInfo, WeslGPUCompilationMessage, WeslJsPlugin, WeslParseContext, WeslParseError, WeslParseState, WeslStream, _linkSync, astToString, attributeToString, bindAndTransform, bindIdents, bindIdentsRecursive, bindingStructsPlugin, childIdent, childScope, containsScope, debug, debugContentsToString, discoverModules, emptyScope, errorHighlight, fileToModulePath, filterMap, filterValidElements, findAllRootDecls, findMap, findRefsToBindingStructs, findUnboundIdents, findUnboundRefs, findValidRootDecls, flatImports, groupBy, grouped, identToString, last, lengthPrefixMangle, link, linkRegistry, liveDeclsToString, log, lowerBindingStructs, makeLiveDecls, makeWeslDevice, mapForward, mapValues, markBindingStructs, markEntryTypes, mergeScope, minimalMangle, minimallyMangledName, modulePartsToRelativePath, moduleToRelativePath, multiKeySet, multisampledTextureTypes, nextIdentId, noSuffix, normalize, normalizeDebugRoot, normalizeModuleName, npmNameVariations, offsetToLineNumber, overlapTail, parseSrcModule, partition, publicDecl, replaceWords, requestWeslDevice, resetScopeIds, resolveModulePath, sampledTextureTypes, sanitizePackageName, scan, scopeToString, scopeToStringLong, srcLog, stdEnumerant, stdEnumerants, stdFn, stdFns, stdType, stdTypes, textureStorageTypes, transformBindingReference, transformBindingStruct, underscoreMangle, validation, wgslStandardAttributes, withLoggerAsync };

package/dist/index.js

@@ -504,11 +504,78 @@ function childIdent(child) {
 }
 
 //#endregion
-//#region src/LowerAndEmit.ts
-/** 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$1 = new Set([
+//#region src/StandardTypes.ts
+const stdFns = `bitcast all any select arrayLength 
+  abs acos acosh asin asinh atan atanh atan2 ceil clamp cos cosh 
+  countLeadingZeros countOneBits countTrailingZeros cross 
+  degrees determinant distance dot dot4U8Packed dot4I8Packed 
+  exp exp2 extractBits faceForward firstLeadingBit firstTrailingBit 
+  floor fma fract frexp insertBits inverseSqrt ldexp length log log2
+  max min mix modf normalize pow quantizeToF16 radians reflect refract
+  reverseBits round saturate sign sin sinh smoothstep sqrt step tan tanh
+  transpose trunc
+  dpdx dpdxCoarse dpdxFine dpdy dpdyCoarse dpdyFine fwidth 
+  fwidthCoarse fwidthFine
+  textureDimensions textureGather textureGatherCompare textureLoad
+  textureNumLayers textureNumLevels textureNumSamples
+  textureSample textureSampleBias textureSampleCompare textureSampleCompareLevel
+  textureSampleGrad textureSampleLevel textureSampleBaseClampToEdge
+  textureStore
+  atomicLoad atomicStore atomicAdd atomicSub atomicMax atomicMin
+  atomicAnd atomicOr atomicXor atomicExchange atomicCompareExchangeWeak
+  pack4x8snorm pack4x8unorm pack4xI8 pack4xU8 pack4xI8Clamp pack4xU8Clamp
+  pack2x16snorm pack2x16unorm pack2x16float
+  unpack4x8snorm unpack4x8unorm unpack4xI8 unpack4xU8 
+  unpack2x16snorm unpack2x16unorm unpack2x16float
+  storageBarrier textureBarrier workgroupBarrier workgroupUniformLoad
+  subgroupAdd subgroupAll subgroupAnd subgroupAny subgroupBallot 
+  subgroupBroadcast subgroupBroadcastFirst subgroupElect 
+  subgroupExclusiveAdd subgroupExclusiveMul subgroupInclusiveAdd 
+  subgroupInclusiveMul subgroupMax subgroupMin subgroupMul subgroupOr 
+  subgroupShuffle subgroupShuffleUp subgroupShuffleXor subgroupXor
+  quadBroadcast quadSwapDiagonal quadSwapX quadSwapY`.split(/\s+/);
+const sampledTextureTypes = `
+  texture_1d texture_2d texture_2d_array texture_3d 
+  texture_cube texture_cube_array
+`;
+const multisampledTextureTypes = `
+  texture_multisampled_2d texture_depth_multisampled_2d
+`;
+const textureStorageTypes = `
+  texture_storage_1d texture_storage_2d texture_storage_2d_array 
+  texture_storage_3d
+`;
+const stdTypes = `array atomic bool f16 f32 i32 
+  mat2x2 mat2x3 mat2x4 mat3x2 mat3x3 mat3x4 mat4x2 mat4x3 mat4x4
+  mat2x2f mat2x3f mat2x4f mat3x2f mat3x3f mat3x4f
+  mat4x2f mat4x3f mat4x4f
+  mat2x2h mat2x3h mat2x4h mat3x2h mat3x3h mat3x4h
+  mat4x2h mat4x3h mat4x4h
+  u32 vec2 vec3 vec4 ptr
+  vec2i vec3i vec4i vec2u vec3u vec4u
+  vec2f vec3f vec4f vec2h vec3h vec4h
+  ${sampledTextureTypes}
+  ${multisampledTextureTypes}
+  texture_external
+  ${textureStorageTypes}
+  texture_depth_2d texture_depth_2d_array texture_depth_cube
+  texture_depth_cube_array
+  sampler sampler_comparison
+  rgba8unorm rgba8snorm rgba8uint rgba8sint
+  rgba16uint rgba16sint rgba16float 
+  r32uint r32sint r32float rg32uint rg32sint rg32float
+  rgba32uint rgba32sint rgba32float
+  bgra8unorm`.split(/\s+/);
+/** https://www.w3.org/TR/WGSL/#predeclared-enumerants  */
+const stdEnumerants = `read write read_write 
+  function private workgroup uniform storage
+  rgba8unorm rgba8snorm rgba8uint rgba8sint 
+  rgba16uint rgba16sint rgba16float 
+  r32uint r32sint r32float rg32uint rg32sint rg32float
+  rgba32uint rgba32sint rgba32float bgra8unorm`.split(/\s+/);
+/** WGSL standard attributes whose params need binding (e.g., @workgroup_size).
+* See: https://www.w3.org/TR/WGSL/#attributes */
+const wgslStandardAttributes = new Set([
 	"align",
 	"binding",
 	"blend_src",
@@ -524,6 +591,21 @@ const wgslStandardAttributes$1 = new Set([
 	"vertex",
 	"workgroup_size"
 ]);
+/** return true if the name is for a built in type (not a user struct) */
+function stdType(name) {
+	return stdTypes.includes(name);
+}
+/** return true if the name is for a built in fn (not a user function) */
+function stdFn(name) {
+	return stdFns.includes(name) || stdType(name);
+}
+/** return true if the name is for a built in enumerant */
+function stdEnumerant(name) {
+	return stdEnumerants.includes(name);
+}
+
+//#endregion
+//#region src/LowerAndEmit.ts
 /** Traverse the AST, starting from root elements, emitting WGSL for each. */
 function lowerAndEmit(params) {
 	const { srcBuilder, rootElems, conditions } = params;
@@ -803,7 +885,7 @@ function emitAttribute(e, ctx) {
 	const { kind } = e.attribute;
 	if (kind === "@if" || kind === "@elif" || kind === "@else") return false;
 	if (kind === "@attribute") {
-		if (!wgslStandardAttributes$1.has(e.attribute.name)) return false;
+		if (!wgslStandardAttributes.has(e.attribute.name)) return false;
 		emitStandardAttribute(e, ctx);
 		return true;
 	}
@@ -3595,115 +3677,16 @@ function flatImports(ast, conditions) {
 	return flat;
 }
 
-//#endregion
-//#region src/StandardTypes.ts
-const stdFns = `bitcast all any select arrayLength 
-  abs acos acosh asin asinh atan atanh atan2 ceil clamp cos cosh 
-  countLeadingZeros countOneBits countTrailingZeros cross 
-  degrees determinant distance dot dot4U8Packed dot4I8Packed 
-  exp exp2 extractBits faceForward firstLeadingBit firstTrailingBit 
-  floor fma fract frexp insertBits inverseSqrt ldexp length log log2
-  max min mix modf normalize pow quantizeToF16 radians reflect refract
-  reverseBits round saturate sign sin sinh smoothstep sqrt step tan tanh
-  transpose trunc
-  dpdx dpdxCoarse dpdxFine dpdy dpdyCoarse dpdyFine fwidth 
-  fwidthCoarse fwidthFine
-  textureDimensions textureGather textureGatherCompare textureLoad
-  textureNumLayers textureNumLevels textureNumSamples
-  textureSample textureSampleBias textureSampleCompare textureSampleCompareLevel
-  textureSampleGrad textureSampleLevel textureSampleBaseClampToEdge
-  textureStore
-  atomicLoad atomicStore atomicAdd atomicSub atomicMax atomicMin
-  atomicAnd atomicOr atomicXor atomicExchange atomicCompareExchangeWeak
-  pack4x8snorm pack4x8unorm pack4xI8 pack4xU8 pack4xI8Clamp pack4xU8Clamp
-  pack2x16snorm pack2x16unorm pack2x16float
-  unpack4x8snorm unpack4x8unorm unpack4xI8 unpack4xU8 
-  unpack2x16snorm unpack2x16unorm unpack2x16float
-  storageBarrier textureBarrier workgroupBarrier workgroupUniformLoad
-  subgroupAdd subgroupAll subgroupAnd subgroupAny subgroupBallot 
-  subgroupBroadcast subgroupBroadcastFirst subgroupElect 
-  subgroupExclusiveAdd subgroupExclusiveMul subgroupInclusiveAdd 
-  subgroupInclusiveMul subgroupMax subgroupMin subgroupMul subgroupOr 
-  subgroupShuffle subgroupShuffleUp subgroupShuffleXor subgroupXor
-  quadBroadcast quadSwapDiagonal quadSwapX quadSwapY`.split(/\s+/);
-const sampledTextureTypes = `
-  texture_1d texture_2d texture_2d_array texture_3d 
-  texture_cube texture_cube_array
-`;
-const multisampledTextureTypes = `
-  texture_multisampled_2d texture_depth_multisampled_2d
-`;
-const textureStorageTypes = `
-  texture_storage_1d texture_storage_2d texture_storage_2d_array 
-  texture_storage_3d
-`;
-const stdTypes = `array atomic bool f16 f32 i32 
-  mat2x2 mat2x3 mat2x4 mat3x2 mat3x3 mat3x4 mat4x2 mat4x3 mat4x4
-  mat2x2f mat2x3f mat2x4f mat3x2f mat3x3f mat3x4f
-  mat4x2f mat4x3f mat4x4f
-  mat2x2h mat2x3h mat2x4h mat3x2h mat3x3h mat3x4h
-  mat4x2h mat4x3h mat4x4h
-  u32 vec2 vec3 vec4 ptr
-  vec2i vec3i vec4i vec2u vec3u vec4u
-  vec2f vec3f vec4f vec2h vec3h vec4h
-  ${sampledTextureTypes}
-  ${multisampledTextureTypes}
-  texture_external
-  ${textureStorageTypes}
-  texture_depth_2d texture_depth_2d_array texture_depth_cube
-  texture_depth_cube_array
-  sampler sampler_comparison
-  rgba8unorm rgba8snorm rgba8uint rgba8sint
-  rgba16uint rgba16sint rgba16float 
-  r32uint r32sint r32float rg32uint rg32sint rg32float
-  rgba32uint rgba32sint rgba32float
-  bgra8unorm`.split(/\s+/);
-/** https://www.w3.org/TR/WGSL/#predeclared-enumerants  */
-const stdEnumerants = `read write read_write 
-  function private workgroup uniform storage
-  rgba8unorm rgba8snorm rgba8uint rgba8sint 
-  rgba16uint rgba16sint rgba16float 
-  r32uint r32sint r32float rg32uint rg32sint rg32float
-  rgba32uint rgba32sint rgba32float bgra8unorm`.split(/\s+/);
-/** return true if the name is for a built in type (not a user struct) */
-function stdType(name) {
-	return stdTypes.includes(name);
-}
-/** return true if the name is for a built in fn (not a user function) */
-function stdFn(name) {
-	return stdFns.includes(name) || stdType(name);
-}
-/** return true if the name is for a built in enumerant */
-function stdEnumerant(name) {
-	return stdEnumerants.includes(name);
-}
-
 //#endregion
 //#region src/BindIdents.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"
-]);
 /** Bind ref idents to declarations and mangle global declaration names. */
 function bindIdents(params) {
 	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,
 		conditions,
@@ -3714,13 +3697,14 @@ function bindIdents(params) {
 		foundScopes: /* @__PURE__ */ new Set(),
 		globalNames,
 		globalStatements: /* @__PURE__ */ new Map(),
-		unbound: accumulateUnbound ? [] : void 0
+		unbound: accumulateUnbound ? [] : void 0,
+		discoveryMode
 	};
 	const liveDecls = {
-		decls: new Map(validRootDecls.map((d) => [d.originalName, d])),
+		decls: new Map(rootDecls.map((d) => [d.originalName, d])),
 		parent: null
 	};
-	const fromRootDecls = validRootDecls.flatMap((decl) => processDependentScope(decl, bindContext));
+	const fromRootDecls = rootDecls.flatMap((decl) => processDependentScope(decl, bindContext));
 	const fromRefs = bindIdentsRecursive(rootAst.rootScope, bindContext, liveDecls);
 	const newStatements = [...bindContext.globalStatements.values()];
 	return {
@@ -3756,17 +3740,11 @@ function* validItems(scope, conditions) {
 }
 /** Find all conditionally valid declarations at the root level. */
 function findValidRootDecls(rootScope, conditions) {
-	const found = [];
-	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. */
 function findAllRootDecls(rootScope) {
-	const found = [];
-	for (const item of rootScope.contents) if (item.kind === "decl") found.push(item);
-	else if (item.kind === "partial") collectDecls(item, found);
-	return found;
+	return collectDecls(rootScope.contents);
 }
 /** Find a public declaration with the given original name. */
 function publicDecl(scope, name, conditions) {
@@ -3834,10 +3812,11 @@ function handleRef(ident, liveDecls, bindContext) {
 	}
 	if (!bindContext.unbound) failIdent(ident, `unresolved identifier '${ident.originalName}'`);
 }
+/** Follow new global declarations into their dependent scopes. */
 function handleDecls(newGlobals, bindContext) {
 	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, foundDecl, ctx) {
 	const { decl, moduleAst } = foundDecl;
 	const { knownDecls, globalNames, mangler, globalStatements } = ctx;
@@ -3864,7 +3843,8 @@ function findDeclInModule(ident, liveDecls) {
 /** Match a ref ident to a declaration in another module via import or qualified ident. */
 function findQualifiedImport(refIdent, ctx) {
 	const { conditions, unbound, discoveryMode } = ctx;
-	const flatImps = flatImports(refIdent.ast, discoveryMode ? void 0 : conditions);
+	const conds = discoveryMode ? void 0 : conditions;
+	const flatImps = flatImports(refIdent.ast, conds);
 	const identParts = refIdent.originalName.split("::");
 	const pathParts = matchingImport(identParts, flatImps) ?? qualifiedIdent(identParts);
 	if (!pathParts) {
@@ -3918,7 +3898,7 @@ function virtualModule(moduleName, ctx) {
 /** Get cached valid root declarations, computing on first access. */
 function getValidRootDecls(rootScope, conditions) {
 	const lexScope = rootScope;
-	if (!lexScope._validRootDecls) lexScope._validRootDecls = findValidRootDecls(rootScope, conditions);
+	lexScope._validRootDecls ??= findValidRootDecls(rootScope, conditions);
 	return lexScope._validRootDecls;
 }
 /** Given a global declIdent, return the liveDecls for its root scope. */
@@ -3947,13 +3927,167 @@ function setMangledName(proposedName, decl, globalNames, srcModule, mangler) {
 function stdWgsl(name) {
 	return stdType(name) || stdFn(name) || stdEnumerant(name);
 }
+/** @return identParts if it's a qualified path (has ::). */
 function qualifiedIdent(identParts) {
 	if (identParts.length > 1) return identParts;
 }
-/** Collect all declarations in a scope (used when scope is already validated). */
-function collectDecls(scope, found) {
-	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) {
+	return [...items].flatMap((item) => {
+		const { kind } = item;
+		if (kind === "decl") return [item];
+		if (kind === "partial") return collectDecls(item.contents);
+		return [];
+	});
+}
+
+//#endregion
+//#region src/PathUtil.ts
+/** simplistic path manipulation utilities */
+/** return path with ./ and foo/.. elements removed */
+function normalize(path) {
+	const noDots = path.split("/").filter((s) => s !== ".");
+	const noDbl = [];
+	noDots.forEach((s) => {
+		if (s !== "") if (s === ".." && noDbl.length && noDbl[noDbl.length - 1] !== "..") noDbl.pop();
+		else noDbl.push(s);
+	});
+	return noDbl.join("/");
+}
+/** return path w/o a suffix.
+* e.g. /foo/bar.wgsl => /foo/bar */
+function noSuffix(path) {
+	const lastSlash = path.lastIndexOf("/");
+	const lastStart = lastSlash === -1 ? 0 : lastSlash + 1;
+	const suffix = path.indexOf(".", lastStart);
+	const suffixStart = suffix === -1 ? path.length : suffix;
+	return path.slice(0, suffixStart);
+}
+
+//#endregion
+//#region src/ModuleResolver.ts
+const libRegex = /^lib\.w[eg]sl$/i;
+/** Module resolver for in-memory source records. Lazy by default. */
+var RecordResolver = class {
+	astCache = /* @__PURE__ */ new Map();
+	sources;
+	packageName;
+	debugWeslRoot;
+	constructor(sources, options = {}) {
+		const { packageName = "package", debugWeslRoot } = options;
+		this.sources = sources;
+		this.packageName = packageName;
+		this.debugWeslRoot = normalizeDebugRoot(debugWeslRoot);
+	}
+	resolveModule(modulePath) {
+		const cached = this.astCache.get(modulePath);
+		if (cached) return cached;
+		const source = this.findSource(modulePath);
+		if (source === void 0) return void 0;
+		const ast = parseSrcModule({
+			modulePath,
+			debugFilePath: this.modulePathToDebugPath(modulePath),
+			src: source
+		});
+		this.astCache.set(modulePath, ast);
+		return ast;
+	}
+	findSource(modulePath) {
+		if (this.sources[modulePath] !== void 0) return this.sources[modulePath];
+		const filePath = this.moduleToFilePath(modulePath);
+		if (filePath === void 0) return void 0;
+		return findInVariants(this.sources, filePath);
+	}
+	/** Convert module path to file path, or undefined if not local. */
+	moduleToFilePath(modulePath) {
+		return moduleToRelativePath(modulePath, this.packageName);
+	}
+	modulePathToDebugPath(modulePath) {
+		const filePath = this.moduleToFilePath(modulePath) ?? modulePath;
+		return this.debugWeslRoot + filePath + ".wesl";
+	}
+	/** Parse all modules and return entries. */
+	allModules() {
+		for (const filePath of Object.keys(this.sources)) {
+			const treatLibAsRoot = this.packageName !== "package";
+			const modulePath = fileToModulePath(filePath, this.packageName, treatLibAsRoot);
+			this.resolveModule(modulePath);
+		}
+		return this.astCache.entries();
+	}
+};
+/** Composite resolver that tries each resolver in order until one succeeds. */
+var CompositeResolver = class {
+	resolvers;
+	constructor(resolvers) {
+		this.resolvers = resolvers;
+	}
+	resolveModule(modulePath) {
+		for (const resolver of this.resolvers) {
+			const ast = resolver.resolveModule(modulePath);
+			if (ast) return ast;
+		}
+	}
+};
+/** Lazy resolver for WeslBundle library modules. */
+var BundleResolver = class {
+	astCache = /* @__PURE__ */ new Map();
+	sources;
+	packageName;
+	debugWeslRoot;
+	constructor(bundle, debugWeslRoot) {
+		this.sources = bundle.modules;
+		this.packageName = bundle.name;
+		this.debugWeslRoot = normalizeDebugRoot(debugWeslRoot);
+	}
+	resolveModule(modulePath) {
+		const pkgPrefix = this.packageName + "::";
+		if (modulePath !== this.packageName && !modulePath.startsWith(pkgPrefix)) return;
+		const cached = this.astCache.get(modulePath);
+		if (cached) return cached;
+		const source = this.findSource(modulePath);
+		if (!source) return void 0;
+		const ast = parseSrcModule({
+			modulePath,
+			debugFilePath: this.modulePathToDebugPath(modulePath),
+			src: source
+		});
+		this.astCache.set(modulePath, ast);
+		return ast;
+	}
+	findSource(modulePath) {
+		const filePath = this.moduleToFilePath(modulePath);
+		if (modulePath === this.packageName) {
+			const libSrc = findInVariants(this.sources, "lib", ["wesl", "wgsl"]);
+			if (libSrc) return libSrc;
+		}
+		return findInVariants(this.sources, filePath);
+	}
+	moduleToFilePath(modulePath) {
+		return moduleToRelativePath(modulePath, this.packageName) ?? modulePath;
+	}
+	modulePathToDebugPath(modulePath) {
+		const filePath = this.moduleToFilePath(modulePath);
+		return this.debugWeslRoot + this.packageName + "/" + filePath + ".wesl";
+	}
+};
+/** Convert file path to module path (e.g., "foo/bar.wesl" to "package::foo::bar"). */
+function fileToModulePath(filePath, packageName, treatLibAsRoot) {
+	if (filePath.includes("::")) return filePath;
+	if (treatLibAsRoot && libRegex.test(filePath)) return packageName;
+	const moduleSuffix = noSuffix(normalize(filePath)).replaceAll("/", "::");
+	return packageName + "::" + moduleSuffix;
+}
+/** Try path variants with/without ./ prefix and extension suffixes. */
+function findInVariants(sources, basePath, extensions = ["wesl", "wgsl"]) {
+	for (const prefix of ["", "./"]) {
+		const path = prefix + basePath;
+		if (sources[path] !== void 0) return sources[path];
+		for (const ext of extensions) {
+			const withExt = `${path}.${ext}`;
+			if (sources[withExt] !== void 0) return sources[withExt];
+		}
+	}
 }
 
 //#endregion
@@ -3992,13 +4126,48 @@ function findUnboundRefs(resolver) {
 			decls: new Map(rootDecls.map((d) => [d.originalName, d])),
 			parent: null
 		};
-		filterMap(rootDecls, (decl) => decl.dependentScope).forEach((s) => {
-			bindIdentsRecursive(s, bindContext, makeLiveDecls(liveDecls));
-		});
+		for (const s of filterMap(rootDecls, (decl) => decl.dependentScope)) bindIdentsRecursive(s, bindContext, makeLiveDecls(liveDecls));
 		bindIdentsRecursive(ast.rootScope, bindContext, liveDecls);
 	}
 	return bindContext.unbound;
 }
+/** Thin decorator that records which modules were resolved. */
+var TrackingResolver = class {
+	visited = /* @__PURE__ */ new Set();
+	#inner;
+	constructor(inner) {
+		this.#inner = inner;
+	}
+	resolveModule(modulePath) {
+		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`.
+*/
+function discoverModules(weslSrc, resolver, rootModuleName, packageName = "package") {
+	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]));
+	const reachable = [...tracking.visited].map((m) => moduleToKey.get(m)).filter((key) => key !== void 0).map((key) => [key, weslSrc[key]]);
+	const unbound = (result.unbound ?? []).map((ref) => ref.path);
+	return {
+		weslSrc: Object.fromEntries(reachable),
+		unbound
+	};
+}
 
 //#endregion
 //#region src/discovery/PackageNameUtils.ts
@@ -4169,155 +4338,6 @@ function compilationInfoToErrorMessage(compilationInfo, shaderModule) {
 	return result;
 }
 
-//#endregion
-//#region src/PathUtil.ts
-/** simplistic path manipulation utilities */
-/** return path with ./ and foo/.. elements removed */
-function normalize(path) {
-	const noDots = path.split("/").filter((s) => s !== ".");
-	const noDbl = [];
-	noDots.forEach((s) => {
-		if (s !== "") if (s === ".." && noDbl.length && noDbl[noDbl.length - 1] !== "..") noDbl.pop();
-		else noDbl.push(s);
-	});
-	return noDbl.join("/");
-}
-/** return path w/o a suffix.
-* e.g. /foo/bar.wgsl => /foo/bar */
-function noSuffix(path) {
-	const lastSlash = path.lastIndexOf("/");
-	const lastStart = lastSlash === -1 ? 0 : lastSlash + 1;
-	const suffix = path.indexOf(".", lastStart);
-	const suffixStart = suffix === -1 ? path.length : suffix;
-	return path.slice(0, suffixStart);
-}
-
-//#endregion
-//#region src/ModuleResolver.ts
-const libRegex = /^lib\.w[eg]sl$/i;
-/** Module resolver for in-memory source records. Lazy by default. */
-var RecordResolver = class {
-	astCache = /* @__PURE__ */ new Map();
-	sources;
-	packageName;
-	debugWeslRoot;
-	constructor(sources, options = {}) {
-		const { packageName = "package", debugWeslRoot } = options;
-		this.sources = sources;
-		this.packageName = packageName;
-		this.debugWeslRoot = normalizeDebugRoot(debugWeslRoot);
-	}
-	resolveModule(modulePath) {
-		const cached = this.astCache.get(modulePath);
-		if (cached) return cached;
-		const source = this.findSource(modulePath);
-		if (source === void 0) return void 0;
-		const ast = parseSrcModule({
-			modulePath,
-			debugFilePath: this.modulePathToDebugPath(modulePath),
-			src: source
-		});
-		this.astCache.set(modulePath, ast);
-		return ast;
-	}
-	findSource(modulePath) {
-		if (this.sources[modulePath] !== void 0) return this.sources[modulePath];
-		const filePath = this.moduleToFilePath(modulePath);
-		if (filePath === void 0) return void 0;
-		return findInVariants(this.sources, filePath);
-	}
-	/** Convert module path to file path, or undefined if not local. */
-	moduleToFilePath(modulePath) {
-		return moduleToRelativePath(modulePath, this.packageName);
-	}
-	modulePathToDebugPath(modulePath) {
-		const filePath = this.moduleToFilePath(modulePath) ?? modulePath;
-		return this.debugWeslRoot + filePath + ".wesl";
-	}
-	/** Parse all modules and return entries. */
-	allModules() {
-		for (const filePath of Object.keys(this.sources)) {
-			const treatLibAsRoot = this.packageName !== "package";
-			const modulePath = fileToModulePath(filePath, this.packageName, treatLibAsRoot);
-			this.resolveModule(modulePath);
-		}
-		return this.astCache.entries();
-	}
-};
-/** Composite resolver that tries each resolver in order until one succeeds. */
-var CompositeResolver = class {
-	resolvers;
-	constructor(resolvers) {
-		this.resolvers = resolvers;
-	}
-	resolveModule(modulePath) {
-		for (const resolver of this.resolvers) {
-			const ast = resolver.resolveModule(modulePath);
-			if (ast) return ast;
-		}
-	}
-};
-/** Lazy resolver for WeslBundle library modules. */
-var BundleResolver = class {
-	astCache = /* @__PURE__ */ new Map();
-	sources;
-	packageName;
-	debugWeslRoot;
-	constructor(bundle, debugWeslRoot) {
-		this.sources = bundle.modules;
-		this.packageName = bundle.name;
-		this.debugWeslRoot = normalizeDebugRoot(debugWeslRoot);
-	}
-	resolveModule(modulePath) {
-		const pkgPrefix = this.packageName + "::";
-		if (modulePath !== this.packageName && !modulePath.startsWith(pkgPrefix)) return;
-		const cached = this.astCache.get(modulePath);
-		if (cached) return cached;
-		const source = this.findSource(modulePath);
-		if (!source) return void 0;
-		const ast = parseSrcModule({
-			modulePath,
-			debugFilePath: this.modulePathToDebugPath(modulePath),
-			src: source
-		});
-		this.astCache.set(modulePath, ast);
-		return ast;
-	}
-	findSource(modulePath) {
-		const filePath = this.moduleToFilePath(modulePath);
-		if (modulePath === this.packageName) {
-			const libSrc = findInVariants(this.sources, "lib", ["wesl", "wgsl"]);
-			if (libSrc) return libSrc;
-		}
-		return findInVariants(this.sources, filePath);
-	}
-	moduleToFilePath(modulePath) {
-		return moduleToRelativePath(modulePath, this.packageName) ?? modulePath;
-	}
-	modulePathToDebugPath(modulePath) {
-		const filePath = this.moduleToFilePath(modulePath);
-		return this.debugWeslRoot + this.packageName + "/" + filePath + ".wesl";
-	}
-};
-/** Convert file path to module path (e.g., "foo/bar.wesl" to "package::foo::bar"). */
-function fileToModulePath(filePath, packageName, treatLibAsRoot) {
-	if (filePath.includes("::")) return filePath;
-	if (treatLibAsRoot && libRegex.test(filePath)) return packageName;
-	const moduleSuffix = noSuffix(normalize(filePath)).replaceAll("/", "::");
-	return packageName + "::" + moduleSuffix;
-}
-/** Try path variants with/without ./ prefix and extension suffixes. */
-function findInVariants(sources, basePath, extensions = ["wesl", "wgsl"]) {
-	for (const prefix of ["", "./"]) {
-		const path = prefix + basePath;
-		if (sources[path] !== void 0) return sources[path];
-		for (const ext of extensions) {
-			const withExt = `${path}.${ext}`;
-			if (sources[withExt] !== void 0) return sources[withExt];
-		}
-	}
-}
-
 //#endregion
 //#region src/SrcMap.ts
 /** map text ranges in multiple src texts to a single dest text */
@@ -4972,4 +4992,4 @@ function makeWeslDevice(device) {
 }
 
 //#endregion
-export { BundleResolver, CompositeResolver, LinkedWesl, ParseError, RecordResolver, SrcMap, SrcMapBuilder, WeslParseError, WeslStream, _linkSync, astToString, attributeToString, bindAndTransform, bindIdents, bindIdentsRecursive, bindingStructsPlugin, childIdent, childScope, containsScope, debug, debugContentsToString, emptyScope, errorHighlight, fileToModulePath, filterMap, findAllRootDecls, findMap, findRefsToBindingStructs, findUnboundIdents, findUnboundRefs, findValidRootDecls, flatImports, groupBy, grouped, identToString, last, lengthPrefixMangle, link, linkRegistry, liveDeclsToString, log, lowerBindingStructs, makeLiveDecls, makeWeslDevice, mapForward, mapValues, markBindingStructs, markEntryTypes, mergeScope, minimalMangle, minimallyMangledName, modulePartsToRelativePath, moduleToRelativePath, multiKeySet, multisampledTextureTypes, nextIdentId, noSuffix, normalize, normalizeDebugRoot, normalizeModuleName, npmNameVariations, offsetToLineNumber, overlapTail, parseSrcModule, partition, publicDecl, replaceWords, requestWeslDevice, resetScopeIds, resolveModulePath, sampledTextureTypes, sanitizePackageName, scan, scopeToString, scopeToStringLong, srcLog, stdEnumerant, stdEnumerants, stdFn, stdFns, stdType, stdTypes, textureStorageTypes, transformBindingReference, transformBindingStruct, underscoreMangle, validation, withLoggerAsync };
+export { BundleResolver, CompositeResolver, LinkedWesl, ParseError, RecordResolver, SrcMap, SrcMapBuilder, TrackingResolver, WeslParseError, WeslStream, _linkSync, astToString, attributeToString, bindAndTransform, bindIdents, bindIdentsRecursive, bindingStructsPlugin, childIdent, childScope, containsScope, debug, debugContentsToString, discoverModules, emptyScope, errorHighlight, fileToModulePath, filterMap, filterValidElements, findAllRootDecls, findMap, findRefsToBindingStructs, findUnboundIdents, findUnboundRefs, findValidRootDecls, flatImports, groupBy, grouped, identToString, last, lengthPrefixMangle, link, linkRegistry, liveDeclsToString, log, lowerBindingStructs, makeLiveDecls, makeWeslDevice, mapForward, mapValues, markBindingStructs, markEntryTypes, mergeScope, minimalMangle, minimallyMangledName, modulePartsToRelativePath, moduleToRelativePath, multiKeySet, multisampledTextureTypes, nextIdentId, noSuffix, normalize, normalizeDebugRoot, normalizeModuleName, npmNameVariations, offsetToLineNumber, overlapTail, parseSrcModule, partition, publicDecl, replaceWords, requestWeslDevice, resetScopeIds, resolveModulePath, sampledTextureTypes, sanitizePackageName, scan, scopeToString, scopeToStringLong, srcLog, stdEnumerant, stdEnumerants, stdFn, stdFns, stdType, stdTypes, textureStorageTypes, transformBindingReference, transformBindingStruct, underscoreMangle, validation, wgslStandardAttributes, withLoggerAsync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wesl",
-  "version": "0.7.22",
+  "version": "0.7.23",
   "type": "module",
   "files": [
     "dist",

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,22 +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[] {
-  const found: DeclIdent[] = [];
-  for (const item of rootScope.contents) {
-    if (item.kind === "decl") found.push(item);
-    else if (item.kind === "partial") collectDecls(item, found);
-  }
-  return found;
+  return collectDecls(rootScope.contents);
 }
 
 /** Find a public declaration with the given original name. */
@@ -353,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,
@@ -360,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,
@@ -397,10 +382,8 @@ function findQualifiedImport(
   ctx: BindContext,
 ): FoundDecl | undefined {
   const { conditions, unbound, discoveryMode } = ctx;
-  const flatImps = flatImports(
-    refIdent.ast,
-    discoveryMode ? undefined : conditions,
-  );
+  const conds = discoveryMode ? undefined : conditions;
+  const flatImps = flatImports(refIdent.ast, conds);
   const identParts = refIdent.originalName.split("::");
   const pathParts =
     matchingImport(identParts, flatImps) ?? qualifiedIdent(identParts);
@@ -490,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;
 }
 
@@ -504,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;
@@ -543,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,5 +1,6 @@
 import type { AbstractElem } from "../AbstractElems.ts";
 import {
+  bindIdents,
   bindIdentsRecursive,
   type EmittableElem,
   findAllRootDecls,
@@ -7,7 +8,12 @@ import {
 } 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";
 
@@ -43,18 +49,70 @@ export function findUnboundRefs(resolver: BatchModuleResolver): UnboundRef[] {
 
   for (const [, ast] of resolver.allModules()) {
     const rootDecls = findAllRootDecls(ast.rootScope);
-    const liveDecls: LiveDecls = {
-      decls: new Map(rootDecls.map(d => [d.originalName, d] as const)),
-      parent: null,
-    };
+    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([]);
+});