@flamework-experimental/core 2.0.0-alpha.2 → 2.0.0-alpha.4

package/out/utility/explainUnresolved.luau

@@ -0,0 +1,43 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local Reflect = TS.import(script, script.Parent.Parent, "reflect").Reflect
+local findModuleClass = TS.import(script, script.Parent, "moduleClasses").findModuleClass
+local function describeModule(moduleScript)
+	local _moduleScript = moduleScript
+	return if typeof(_moduleScript) == "Instance" then moduleScript:GetFullName() else tostring(moduleScript)
+end
+--[[
+	*
+	 * Why a dependency no module resolved cannot be resolved, when its id names a Flamework class that
+	 * has been loaded -- one a module defined at its top level, which the module record knows -- with
+	 * what to do about it. Nothing for any other id: an interface, a type registered nowhere, a class
+	 * defined inside a function or never required, whose failure keeps the plain message.
+	 *
+	 * `origin` is the class whose constructor asked, when one did.
+	 
+]]
+local function explainUnresolvedClass(id, origin)
+	local found = findModuleClass(function(value)
+		return Reflect.getOwnMetadata(value, "identifier") == id
+	end)
+	if found == nil then
+		return nil
+	end
+	local _binding = found
+	local value = _binding[1]
+	local moduleScript = _binding[2]
+	local where = describeModule(moduleScript)
+	if Reflect.hasOwnMetadata(value, "flamework:provider") then
+		return `'{value}' ({where}) is a @Provider() that nothing in this module registers or provides: ` .. "add its folder to registerProviders, register it with registerClassProvider, include the plugin that provides it, " .. "or import a module that has it"
+	end
+	if Reflect.hasOwnMetadata(value, "flamework:component") then
+		if origin ~= nil and Reflect.hasOwnMetadata(origin, "flamework:component") then
+			return `'{value}' ({where}) is a component that no ComponentPlugin of this module registers, ` .. `so the component '{origin}' cannot take it: register it in one`
+		end
+		return `'{value}' ({where}) is a component (@Component), not a provider: a module never constructs a component, ` .. "so Dependency<T>() and constructor injection cannot reach one. Make it a @Provider(), or get it from " .. "Components on the instance it is attached to (components.getComponent<T>(instance))"
+	end
+	return `'{value}' ({where}) is not a provider: it carries no @Provider() decorator. ` .. "Decorate it with @Provider(), or build it with module.createClassInstance"
+end
+return {
+	explainUnresolvedClass = explainUnresolvedClass,
+}

package/out/utility/getClassesInPath.d.ts

@@ -1,3 +1,4 @@
+import type { Modding } from "../modding";
 /**
  * Requires one ModuleScript through the roblox-ts runtime, as an `import` would, and returns what
  * it exported. A module that fails to load raises with its full name and how long it took.
@@ -14,10 +15,43 @@ export declare function importModule(moduleScript: ModuleScript): defined | unde
  */
 export declare function requireModulesInPath(rbxPath: readonly string[]): Array<defined>;
 /**
- * Requires every ModuleScript at and under the specified Rojo path and returns every exported value
- * that carries its own Flamework identifier.
+ * Requires every ModuleScript at and under a source folder, in tree order, for what the modules do
+ * as they load, and returns what each exported, leaving out the ones that exported nothing. This is
+ * v1's `Flamework.addPaths` for a folder that holds no providers: modules that register themselves
+ * with a library, such as commands.
+ *
+ * The path is a source path, as a string literal: `requireModules("src/server/commands")`. The build
+ * turns it into the Rojo path the folder ends up at, as it does for `registerProviders`, so the
+ * folder has to be in your Rojo project.
+ *
+ * Each module is required through the roblox-ts module cache, so it runs once, however many times
+ * it is required. A folder inside a folder that `registerProviders` registers needs no call:
+ * registration already requires every ModuleScript under it.
+ *
+ * Raises when a module fails to load, and when the folder is not in the place. A missing folder is
+ * waited for five seconds, once the place has loaded, and the error names the part that is missing.
+ * A folder of the other realm's -- a server folder on a client, a client folder on the server --
+ * raises at once, saying so.
+ *
+ * @metadata macro
+ */
+export declare function requireModules<T extends string>(path: T, rbxPath?: Modding.Intrinsic<"path", [T], string[]>): Array<defined>;
+/**
+ * Requires every ModuleScript at and under the specified Rojo path and returns every Flamework
+ * class they hold, each once: every class carrying its own identifier that a module defined at its
+ * top level -- exported or not, as v1 registered every decorated class it required -- then every
+ * exported value carrying its own identifier that the module did not define there, such as a
+ * re-export of a class from elsewhere.
+ *
+ * A class declared inside a function is not found unless its module exports it: it is created by
+ * every call, so the transformer does not record it against its module. Neither is a class
+ * compiled by a transformer older than the one that records classes, other than through its
+ * module's exports.
  *
  * A module that fails to load raises, as it did in v1: a class that silently fails to register
  * would otherwise only show up later as an unresolvable dependency, far from the cause.
+ *
+ * The folder is waited for as {@link resolveRbxPath} waits: `caller`, the registration that gave the
+ * path (`registerProviders("src/server/services")`), is named in the warning a slow wait gets.
  */
-export declare function getClassesInPath(rbxPath: readonly string[]): Array<object>;
+export declare function getClassesInPath(rbxPath: readonly string[], caller?: string): Array<object>;

package/out/utility/getClassesInPath.luau

@@ -1,8 +1,34 @@
 -- Compiled with roblox-ts v3.0.0
 local TS = _G[script]
+local RunService = TS.import(script, TS.getModule(script, "@rbxts", "services")).RunService
 local tsImport = TS.import(script, script.Parent, "tsImport").tsImport
 local Reflect = TS.import(script, script.Parent.Parent, "reflect").Reflect
-local resolveRbxPath = TS.import(script, script.Parent, "pathRoot").resolveRbxPath
+local _pathRoot = TS.import(script, script.Parent, "pathRoot")
+local findRbxPath = _pathRoot.findRbxPath
+local getPathRoot = _pathRoot.getPathRoot
+local resolveRbxPath = _pathRoot.resolveRbxPath
+local getModuleClasses = TS.import(script, script.Parent, "moduleClasses").getModuleClasses
+--* How long {@link requireModules} waits for a folder that is not in the place, in seconds. 
+local MISSING_FOLDER_TIMEOUT = 5
+--[[
+	*
+	 * Why this realm cannot require a folder under `game` that belongs to the other realm, or nothing
+	 * when it can: a client sees nothing of the server's containers, and the server has no
+	 * `PlayerScripts` to take a client folder from.
+	 
+]]
+local function otherRealmReason(rbxPath)
+	if getPathRoot() ~= game then
+		return nil
+	end
+	local service = rbxPath[1]
+	if RunService:IsClient() and (service == "ServerScriptService" or service == "ServerStorage") then
+		return `the folder is in {service}, which does not replicate to clients. Call requireModules for it on the server`
+	end
+	if not RunService:IsClient() and service == "StarterPlayer" then
+		return "the folder is in StarterPlayer/StarterPlayerScripts, which only a client requires from, through its PlayerScripts. Call requireModules for it on the client"
+	end
+end
 --[[
 	*
 	 * Requires one ModuleScript through the roblox-ts runtime, as an `import` would, and returns what
@@ -20,6 +46,44 @@ local function importModule(moduleScript)
 	end
 	return value
 end
+--[[
+	*
+	 * Requires every ModuleScript at and under an instance, in tree order, handing each to `visit` with
+	 * what it exported.
+	 
+]]
+local function loadModulesIn(root, visit)
+	if root:IsA("ModuleScript") then
+		visit(root, importModule(root))
+	end
+	for _, instance in root:GetDescendants() do
+		if instance:IsA("ModuleScript") then
+			visit(instance, importModule(instance))
+		end
+	end
+end
+--[[
+	*
+	 * Requires every ModuleScript at and under a Rojo path, in tree order, handing each to `visit` with
+	 * what it exported. `caller` names the call that gave the path, for the warning a slow wait gets.
+	 
+]]
+local function loadModulesInPath(rbxPath, visit, caller)
+	local _rbxPath = rbxPath
+	assert(_rbxPath)
+	loadModulesIn(resolveRbxPath(rbxPath, caller), visit)
+end
+--* What every ModuleScript at and under an instance exported, leaving out the ones that exported nothing. 
+local function requireModulesIn(root)
+	local loaded = {}
+	loadModulesIn(root, function(_, value)
+		if value ~= nil then
+			local _value = value
+			table.insert(loaded, _value)
+		end
+	end)
+	return loaded
+end
 --[[
 	*
 	 * Requires every ModuleScript at and under the specified Rojo path, in tree order, and returns
@@ -34,58 +98,115 @@ end
 local function requireModulesInPath(rbxPath)
 	local _rbxPath = rbxPath
 	assert(_rbxPath)
-	local preloadPath = resolveRbxPath(rbxPath)
-	local loaded = {}
-	if preloadPath:IsA("ModuleScript") then
-		local value = importModule(preloadPath)
-		if value ~= nil then
-			table.insert(loaded, value)
-		end
+	return requireModulesIn(resolveRbxPath(rbxPath))
+end
+--[[
+	*
+	 * Requires every ModuleScript at and under a source folder, in tree order, for what the modules do
+	 * as they load, and returns what each exported, leaving out the ones that exported nothing. This is
+	 * v1's `Flamework.addPaths` for a folder that holds no providers: modules that register themselves
+	 * with a library, such as commands.
+	 *
+	 * The path is a source path, as a string literal: `requireModules("src/server/commands")`. The build
+	 * turns it into the Rojo path the folder ends up at, as it does for `registerProviders`, so the
+	 * folder has to be in your Rojo project.
+	 *
+	 * Each module is required through the roblox-ts module cache, so it runs once, however many times
+	 * it is required. A folder inside a folder that `registerProviders` registers needs no call:
+	 * registration already requires every ModuleScript under it.
+	 *
+	 * Raises when a module fails to load, and when the folder is not in the place. A missing folder is
+	 * waited for five seconds, once the place has loaded, and the error names the part that is missing.
+	 * A folder of the other realm's -- a server folder on a client, a client folder on the server --
+	 * raises at once, saying so.
+	 *
+	 * @metadata macro
+	 
+]]
+local function requireModules(path, rbxPath)
+	if rbxPath == nil then
+		error(`requireModules("{path}") was called without the folder's Rojo path, which the build fills in. ` .. "Call it directly, with a string literal, in code that the Flamework transformer compiles.", 2)
 	end
-	for _, instance in preloadPath:GetDescendants() do
-		if instance:IsA("ModuleScript") then
-			local value = importModule(instance)
-			if value ~= nil then
-				table.insert(loaded, value)
-			end
-		end
+	local otherRealm = otherRealmReason(rbxPath)
+	if otherRealm ~= nil then
+		error(`requireModules("{path}"): {otherRealm}.`, 2)
 	end
-	return loaded
+	local _binding = findRbxPath(rbxPath, MISSING_FOLDER_TIMEOUT)
+	local found = _binding.found
+	local missing = _binding.missing
+	if missing ~= nil then
+		error(`requireModules("{path}"): the folder is not in the place. The build put it at {table.concat(rbxPath, "/")}, ` .. `and {found:GetFullName()} has no child named '{missing}' after {MISSING_FOLDER_TIMEOUT} seconds. ` .. "The path is misspelled or differs in case from the folder, or the folder is empty and missing from this " .. "clone, since git keeps no empty folder (the build warns about these where the path is used); or it was " .. "moved or renamed after the build; or the Rojo project the place was built from leaves it out.", 2)
+	end
+	return requireModulesIn(found)
 end
 --[[
 	*
-	 * Requires every ModuleScript at and under the specified Rojo path and returns every exported value
-	 * that carries its own Flamework identifier.
+	 * Requires every ModuleScript at and under the specified Rojo path and returns every Flamework
+	 * class they hold, each once: every class carrying its own identifier that a module defined at its
+	 * top level -- exported or not, as v1 registered every decorated class it required -- then every
+	 * exported value carrying its own identifier that the module did not define there, such as a
+	 * re-export of a class from elsewhere.
+	 *
+	 * A class declared inside a function is not found unless its module exports it: it is created by
+	 * every call, so the transformer does not record it against its module. Neither is a class
+	 * compiled by a transformer older than the one that records classes, other than through its
+	 * module's exports.
 	 *
 	 * A module that fails to load raises, as it did in v1: a class that silently fails to register
 	 * would otherwise only show up later as an unresolvable dependency, far from the cause.
+	 *
+	 * The folder is waited for as {@link resolveRbxPath} waits: `caller`, the registration that gave the
+	 * path (`registerProviders("src/server/services")`), is named in the warning a slow wait gets.
 	 
 ]]
-local function getClassesInPath(rbxPath)
+local function getClassesInPath(rbxPath, caller)
 	local foundClasses = {}
-	for _, value in requireModulesInPath(rbxPath) do
-		if not (type(value) == "table") then
-			continue
+	local found = {}
+	-- Own metadata only: an undecorated subclass inherits its parent's identifier, and must not be
+	-- mistaken for a registered class of its own.
+	local add = function(value)
+		local _value = value
+		local _condition = type(_value) == "table"
+		if _condition then
+			local _value_1 = value
+			_condition = not (found[_value_1] ~= nil)
+			if _condition then
+				_condition = Reflect.hasOwnMetadata(value, "identifier")
+			end
+		end
+		if _condition then
+			local _value_1 = value
+			found[_value_1] = true
+			local _value_2 = value
+			table.insert(foundClasses, _value_2)
+		end
+	end
+	loadModulesInPath(rbxPath, function(moduleScript, value)
+		local defined = getModuleClasses(moduleScript)
+		if defined ~= nil then
+			for _, value in defined do
+				add(value)
+			end
+		end
+		local _value = value
+		if not (type(_value) == "table") then
+			return nil
 		end
 		-- This is an `export =` on a Flamework class.
 		if Reflect.hasOwnMetadata(value, "identifier") then
-			table.insert(foundClasses, value)
-			continue
+			add(value)
+			return nil
 		end
-		for _1, member in pairs(value) do
-			-- This is an `export` on a Flamework class.
-			--
-			-- Own metadata only: an undecorated subclass inherits its parent's identifier, and
-			-- must not be mistaken for a registered class of its own.
-			if type(member) == "table" and Reflect.hasOwnMetadata(member, "identifier") then
-				table.insert(foundClasses, member)
-			end
+		-- This is an `export` on a Flamework class.
+		for _, member in pairs(value) do
+			add(member)
 		end
-	end
+	end, caller)
 	return foundClasses
 end
 return {
 	importModule = importModule,
 	requireModulesInPath = requireModulesInPath,
+	requireModules = requireModules,
 	getClassesInPath = getClassesInPath,
 }

package/out/utility/globs.d.ts

@@ -3,7 +3,7 @@
  */
 export declare function getGlobPaths(glob: string): string[][];
 /**
- * Requires every ModuleScript under every path the glob matched and returns the exported classes,
- * each at most once.
+ * Requires every ModuleScript under every path the glob matched and returns the Flamework classes
+ * they hold, exported or not, each at most once (see {@link getClassesInPath}).
  */
 export declare function getClassesInGlob(glob: string): Array<object>;

package/out/utility/globs.luau

@@ -37,14 +37,14 @@ local function getGlobPaths(glob)
 	end
 	local paths = _result
 	if paths == nil then
-		error(`Flamework has no paths for the glob '{glob}'. ` .. "Globs are resolved at compile time into include/flamework/globs.json, which only game projects emit; " .. "make sure the include directory is part of your Rojo project and that the glob matched at least one file.", 0)
+		error(`Flamework has no paths for the glob '{glob}'. ` .. "A game's globs are resolved at compile time into include/flamework/globs.json, and this one is not there: " .. "the include folder is not in your Rojo project, the glob is used inside a package (a package's globs " .. "are not resolved), the string was not produced by a glob macro, or globs.json is from another build. " .. "A glob that matched no files does not raise: it resolves to no paths, and the build warns about it.", 0)
 	end
 	return paths
 end
 --[[
 	*
-	 * Requires every ModuleScript under every path the glob matched and returns the exported classes,
-	 * each at most once.
+	 * Requires every ModuleScript under every path the glob matched and returns the Flamework classes
+	 * they hold, exported or not, each at most once (see {@link getClassesInPath}).
 	 
 ]]
 local function getClassesInGlob(glob)

package/out/utility/leftOut.d.ts

@@ -0,0 +1,35 @@
+import { type ScopeCondition } from "../module/scopes";
+/**
+ * A path or glob registration that its own scope condition left out. Its folder was never looked up,
+ * so nothing under it was loaded, and nothing from it was registered or recorded as inactive: this
+ * is what a miss can still say about the classes there.
+ */
+export interface LeftOutRegistration {
+    /** The call as written, for messages: `registerProviders("src/server/debug")`. */
+    readonly call: string;
+    /** The registration's own condition, which did not hold. */
+    readonly condition: ScopeCondition;
+    /** The folder's tree path, for a path registration. */
+    readonly path?: readonly string[];
+    /** The glob as the runtime keys it, for a glob registration. */
+    readonly glob?: string;
+    /** What `path` was relative to when the registration was made. */
+    readonly root: Instance;
+}
+/**
+ * Records a registration left out by its own condition. Reads nothing but the path root, which is
+ * found from Flamework's own metadata, never from the folder.
+ */
+export declare function leftOutRegistration(call: string, condition: ScopeCondition, folder: {
+    path?: readonly string[];
+    glob?: string;
+}): LeftOutRegistration;
+/**
+ * What a miss on `id` can say about the registrations its module or plugin left out by their own
+ * condition, without looking at their folders:
+ *
+ * - the class has loaded some other way, and its module is under one of them: that one, and why;
+ * - the class has not loaded: every one of them, since the class may be under any;
+ * - nothing when there are none, or when the loaded class is under none of them.
+ */
+export declare function explainLeftOut(id: string, leftOut: ReadonlyArray<LeftOutRegistration>): string | undefined;

package/out/utility/leftOut.luau

@@ -0,0 +1,171 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local describeConditions = TS.import(script, script.Parent.Parent, "module", "scopes").describeConditions
+local Reflect = TS.import(script, script.Parent.Parent, "reflect").Reflect
+local getGlobPaths = TS.import(script, script.Parent, "globs").getGlobPaths
+local findModuleClass = TS.import(script, script.Parent, "moduleClasses").findModuleClass
+local getPathRoot = TS.import(script, script.Parent, "pathRoot").getPathRoot
+--[[
+	*
+	 * A path or glob registration that its own scope condition left out. Its folder was never looked up,
+	 * so nothing under it was loaded, and nothing from it was registered or recorded as inactive: this
+	 * is what a miss can still say about the classes there.
+	 
+]]
+--[[
+	*
+	 * Records a registration left out by its own condition. Reads nothing but the path root, which is
+	 * found from Flamework's own metadata, never from the folder.
+	 
+]]
+local function leftOutRegistration(call, condition, folder)
+	return {
+		call = call,
+		condition = {
+			activeIn = condition.activeIn,
+			inactiveIn = condition.inactiveIn,
+		},
+		path = folder.path,
+		glob = folder.glob,
+		root = getPathRoot(),
+	}
+end
+--[[
+	*
+	 * The tree path of a loaded module below `root`, in the form a compile-time path has: a client's
+	 * `PlayerScripts` is written as `StarterPlayer/StarterPlayerScripts`, where its content comes from.
+	 * Nothing when the module is not below `root`.
+	 
+]]
+local function treePathOf(moduleScript, root)
+	local names = {}
+	local current = moduleScript
+	while current ~= nil and current ~= root do
+		local _name = current.Name
+		table.insert(names, 1, _name)
+		current = current.Parent
+	end
+	if current == nil then
+		return nil
+	end
+	if root == game and names[1] == "Players" and names[3] == "PlayerScripts" then
+		-- ▼ ReadonlyArray.filter ▼
+		local _newValue = {}
+		local _callback = function(_, index)
+			return index >= 3
+		end
+		local _length = 0
+		for _k, _v in names do
+			if _callback(_v, _k - 1, names) == true then
+				_length += 1
+				_newValue[_length] = _v
+			end
+		end
+		-- ▲ ReadonlyArray.filter ▲
+		local rest = _newValue
+		local _array = { "StarterPlayer", "StarterPlayerScripts" }
+		local _length_1 = #_array
+		table.move(rest, 1, #rest, _length_1 + 1, _array)
+		return _array
+	end
+	return names
+end
+local function startsWith(path, prefix)
+	if #path < #prefix then
+		return false
+	end
+	for i = 0, #prefix - 1 do
+		if path[i + 1] ~= prefix[i + 1] then
+			return false
+		end
+	end
+	return true
+end
+--* Whether a loaded module is under the folder, or one of the folders, a left-out registration named. 
+local function isUnder(moduleScript, registration)
+	local modulePath = treePathOf(moduleScript, registration.root)
+	if modulePath == nil then
+		return false
+	end
+	if registration.path ~= nil then
+		return startsWith(modulePath, registration.path)
+	end
+	if registration.glob ~= nil then
+		-- `globs.json`, not the folders: what the glob matched when the build was compiled.
+		local ok, paths = pcall(getGlobPaths, registration.glob)
+		if not ok then
+			return false
+		end
+		-- ▼ ReadonlyArray.some ▼
+		local _result = false
+		local _callback = function(path)
+			return startsWith(modulePath, path)
+		end
+		for _k, _v in paths do
+			if _callback(_v, _k - 1, paths) then
+				_result = true
+				break
+			end
+		end
+		-- ▲ ReadonlyArray.some ▲
+		return _result
+	end
+	return false
+end
+--[[
+	*
+	 * What a miss on `id` can say about the registrations its module or plugin left out by their own
+	 * condition, without looking at their folders:
+	 *
+	 * - the class has loaded some other way, and its module is under one of them: that one, and why;
+	 * - the class has not loaded: every one of them, since the class may be under any;
+	 * - nothing when there are none, or when the loaded class is under none of them.
+	 
+]]
+local function explainLeftOut(id, leftOut)
+	if #leftOut == 0 then
+		return nil
+	end
+	local advice = "the build's scopes so that the condition holds, or do not depend on it in this build"
+	local found = findModuleClass(function(value)
+		return Reflect.getOwnMetadata(value, "identifier") == id
+	end)
+	if found ~= nil then
+		local _binding = found
+		local value = _binding[1]
+		local moduleScript = _binding[2]
+		-- ▼ ReadonlyArray.find ▼
+		local _callback = function(registration)
+			return isUnder(moduleScript, registration)
+		end
+		local _result
+		for _i, _v in leftOut do
+			if _callback(_v, _i - 1, leftOut) == true then
+				_result = _v
+				break
+			end
+		end
+		-- ▲ ReadonlyArray.find ▲
+		local under = _result
+		if under == nil then
+			return nil
+		end
+		local where = if typeof(moduleScript) == "Instance" then moduleScript:GetFullName() else tostring(moduleScript)
+		return `'{value}' ({where}) is under {under.call}, which is left out by its scope ` .. `({describeConditions({ under.condition })}): nothing under it is registered. Change {advice}`
+	end
+	-- ▼ ReadonlyArray.map ▼
+	local _newValue = table.create(#leftOut)
+	local _callback = function(v)
+		return `{v.call} ({describeConditions({ v.condition })})`
+	end
+	for _k, _v in leftOut do
+		_newValue[_k] = _callback(_v, _k - 1, leftOut)
+	end
+	-- ▲ ReadonlyArray.map ▲
+	local listed = table.concat(_newValue, ", ")
+	return `nothing registers it. Left out by their scope, without loading their folders: {listed}. ` .. `If it is defined under one of them, change {advice}`
+end
+return {
+	leftOutRegistration = leftOutRegistration,
+	explainLeftOut = explainLeftOut,
+}

package/out/utility/moduleClasses.d.ts

@@ -0,0 +1,9 @@
+/** Records a class against the module that defined it. Called by `Reflect.defineMetadata`. */
+export declare function recordModuleClass(moduleScript: unknown, value: object): void;
+/** The classes a module defined as it loaded, in definition order, or none. */
+export declare function getModuleClasses(moduleScript: unknown): ReadonlyArray<object> | undefined;
+/**
+ * Every recorded class, with the module that defined it, until the callback answers `true`. For
+ * explaining a failed resolution, which is rare: nothing here is indexed for it.
+ */
+export declare function findModuleClass(predicate: (value: object) => boolean): [object, unknown] | undefined;

package/out/utility/moduleClasses.luau

@@ -0,0 +1,64 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * The Flamework classes each module defined as it loaded, by the module's `script`, in the order
+	 * they were defined: what path registration finds in a module besides what it exports.
+	 *
+	 * The transformer records a class with `Reflect.defineMetadata(class, "flamework:module", script)`,
+	 * and only a class the module creates once per load -- declared at the top level of the file, or
+	 * of a namespace in it. A class declared inside a function is created by every call and is never
+	 * recorded, so nothing here grows with calls, and a later path registration never finds a class
+	 * that belongs to a test case or a factory. Keyed by the ModuleScript rather than read off the
+	 * class's identifier, which says nothing about where the class came from once ids are short, tiny
+	 * or obfuscated.
+	 *
+	 * Held for good, as the module's own exports are held by the require cache: a module loads once.
+	 
+]]
+local classesByModule = {}
+--* Records a class against the module that defined it. Called by `Reflect.defineMetadata`. 
+local function recordModuleClass(moduleScript, value)
+	if moduleScript == nil then
+		return nil
+	end
+	local _moduleScript = moduleScript
+	local classes = classesByModule[_moduleScript]
+	if classes == nil then
+		classes = {}
+		local _moduleScript_1 = moduleScript
+		local _classes = classes
+		classesByModule[_moduleScript_1] = _classes
+	end
+	local _classes = classes
+	local _value = value
+	if not (table.find(_classes, _value) ~= nil) then
+		local _classes_1 = classes
+		local _value_1 = value
+		table.insert(_classes_1, _value_1)
+	end
+end
+--* The classes a module defined as it loaded, in definition order, or none. 
+local function getModuleClasses(moduleScript)
+	local _moduleScript = moduleScript
+	return classesByModule[_moduleScript]
+end
+--[[
+	*
+	 * Every recorded class, with the module that defined it, until the callback answers `true`. For
+	 * explaining a failed resolution, which is rare: nothing here is indexed for it.
+	 
+]]
+local function findModuleClass(predicate)
+	for moduleScript, classes in classesByModule do
+		for _, value in classes do
+			if predicate(value) then
+				return { value, moduleScript }
+			end
+		end
+	end
+end
+return {
+	recordModuleClass = recordModuleClass,
+	getModuleClasses = getModuleClasses,
+	findModuleClass = findModuleClass,
+}

package/out/utility/pathRoot.d.ts

@@ -13,5 +13,24 @@ export declare function getPathRoot(): Instance;
  *
  * Under `game` the first segment names a service, and `StarterPlayer/StarterPlayerScripts` is
  * answered from the local player's `PlayerScripts`, which is where that content actually runs.
+ *
+ * A child that is not there within five seconds (on a client, once the place has loaded) is warned
+ * about, naming `caller` -- the call that gave the path, such as `registerProviders("src/shared/components")`
+ * -- and the child missing, and then waited for without a limit: content that arrives late still
+ * resolves, as it always has. The warning comes once per path: a child further down that is late
+ * too is the same wait, and is waited for without a second one.
+ */
+export declare function resolveRbxPath(rbxPath: readonly string[], caller?: string): Instance;
+/**
+ * Walks a compile-time path as {@link resolveRbxPath} does, but gives up on a child that is not
+ * there instead of waiting for it forever. A client still loading the place waits for it to load
+ * first, since the place's content arrives as it loads; after that, a missing child is given
+ * `timeout` seconds to appear.
+ *
+ * Returns the instance the path names, or the deepest instance it found and the name missing below
+ * it.
  */
-export declare function resolveRbxPath(rbxPath: readonly string[]): Instance;
+export declare function findRbxPath(rbxPath: readonly string[], timeout: number): {
+    found: Instance;
+    missing?: string;
+};