@flamework-experimental/core 2.0.0-alpha.1 → 2.0.0-alpha.3

package/out/module/providerRegistration.d.ts

@@ -20,3 +20,11 @@ export declare function normalizeProviderConfig(config: ProviderConfig): Provide
  * parent's scope.
  */
 export declare function getProviderClassScope(config: ProviderConfig): ScopeCondition;
+/** v1's default, which a provider that does not set `loadOrder` has. */
+export declare const DEFAULT_LOAD_ORDER = 1;
+/**
+ * Where a registration sits in its module's startup: its class's `loadOrder`, or the default. A
+ * lazy one has none (`undefined`): it starts when it is first resolved, whatever its decorator says.
+ * Own metadata, as everywhere else.
+ */
+export declare function getProviderLoadOrder(config: ProviderConfig): number | undefined;

package/out/module/providerRegistration.luau

@@ -72,9 +72,38 @@ local function getProviderClassScope(config)
 		inactiveIn = decoratorConfig.inactiveIn,
 	}
 end
+--* v1's default, which a provider that does not set `loadOrder` has. 
+local DEFAULT_LOAD_ORDER = 1
+--[[
+	*
+	 * Where a registration sits in its module's startup: its class's `loadOrder`, or the default. A
+	 * lazy one has none (`undefined`): it starts when it is first resolved, whatever its decorator says.
+	 * Own metadata, as everywhere else.
+	 
+]]
+local function getProviderLoadOrder(config)
+	if config.type ~= "class" then
+		return DEFAULT_LOAD_ORDER
+	end
+	if config.lazy == true then
+		return nil
+	end
+	local decoratorConfig = Reflect.getOwnMetadata(config.value, "flamework:providerConfig")
+	local _result = decoratorConfig
+	if _result ~= nil then
+		_result = _result.loadOrder
+	end
+	local _condition = _result
+	if _condition == nil then
+		_condition = DEFAULT_LOAD_ORDER
+	end
+	return _condition
+end
 return {
 	assertIsProviderClass = assertIsProviderClass,
 	getProviderClassId = getProviderClassId,
 	normalizeProviderConfig = normalizeProviderConfig,
 	getProviderClassScope = getProviderClassScope,
+	getProviderLoadOrder = getProviderLoadOrder,
+	DEFAULT_LOAD_ORDER = DEFAULT_LOAD_ORDER,
 }

package/out/plugin/pluginDefinition.d.ts

@@ -52,15 +52,18 @@ export interface PluginTarget {
      */
     registerClassProvider: (provider: Constructor, options?: ProviderRegistrationOptions) => void;
     /**
-     * Registers every exported `@Provider()` class under a source folder, as the module builder's
-     * `registerProviders` does. This is how a plugin ships a folder of providers. The options apply
-     * to every class found.
+     * Registers every `@Provider()` class the modules under a source folder define, exported or not,
+     * as the module builder's `registerProviders` does. This is how a plugin ships a folder of
+     * providers. The options apply to every class found; when their scope condition does not hold,
+     * the folder is not looked up and nothing under it is required.
      *
      * @metadata macro
      */
     registerProviders: <T extends string>(path: T, options?: ProviderRegistrationOptions, resolved?: Modding.Intrinsic<"path", [T], string[]>) => void;
     /**
-     * Registers every exported `@Provider()` class under every folder a compile-time glob matches.
+     * Registers every `@Provider()` class the modules under every folder a compile-time glob matches
+     * define, exported or not. As with `registerProviders`, a scope condition that does not hold
+     * leaves the folders untouched.
      *
      * @metadata macro
      */
@@ -94,6 +97,13 @@ export interface PluginTarget {
     onPreIgnite: (callback: (module: Module) => void, options?: HookOptions) => void;
     /** Runs after every provider has been constructed. */
     onPostIgnite: (callback: (module: Module) => void, options?: HookOptions) => void;
+    /**
+     * Runs once ignition has completed: the module is ignited, and its imports count it among
+     * their importers. The lifecycle plugin starts the providers here. Nothing can fail the
+     * ignition any more, so a hook that raises is warned about and the ones after it still run;
+     * once the module has been extinguished -- by an `onStart`, say -- the rest do not run.
+     */
+    onIgnited: (callback: (module: Module) => void, options?: HookOptions) => void;
     /** Runs when the module extinguishes, before its providers are released. */
     onExtinguished: (callback: (module: Module) => void, options?: HookOptions) => void;
     /**

package/out/provider.d.ts

@@ -11,6 +11,25 @@ export interface ProviderDecoratorConfig extends ScopeCondition {
      * Defaults to `false`.
      */
     lazy?: boolean;
+    /**
+     * Orders this provider's `onInit` and `onStart` against the other providers the same ignition
+     * constructs, as v1's `loadOrder` did: lower goes first. Defaults to `1`; any finite number,
+     * negative and fractional ones included. Providers with the same `loadOrder` keep the order
+     * they would have without one.
+     *
+     * Dependency order still wins. The module constructs its providers in ascending `loadOrder`,
+     * each after what its constructor takes, so a provider's dependencies are constructed and
+     * initialised before it even when theirs is higher: a low `loadOrder` pulls what the provider
+     * needs forward with it. `onInit` runs in that construction order. `onStart` runs in ascending
+     * `loadOrder` alone, each on its own thread as always, so a lower one runs up to its first yield
+     * before the next is started.
+     *
+     * Only within one module's ignition: imported modules ignite, and start, before it. Per-frame
+     * events (`onTick`, `onPhysics`, `onRender`) stay unordered. A lazy provider is not part of
+     * the order: it is initialised and started when it is first resolved, and its `loadOrder` is
+     * ignored.
+     */
+    loadOrder?: number;
 }
 /**
  * Register a class as a provider.

package/out/provider.luau

@@ -17,6 +17,14 @@ local Reflect = TS.import(script, script.Parent, "reflect").Reflect
 ]]
 local function Provider(config)
 	return function(constructor)
+		local _loadOrder = config
+		if _loadOrder ~= nil then
+			_loadOrder = _loadOrder.loadOrder
+		end
+		local loadOrder = _loadOrder
+		if loadOrder ~= nil and (not (type(loadOrder) == "number") or not (math.abs(loadOrder) < math.huge)) then
+			error(`@Provider() on '{constructor}': loadOrder must be a finite number, got {tostring(loadOrder)} ({typeof(loadOrder)})`)
+		end
 		Reflect.defineMetadata(constructor, "flamework:provider", true)
 		Reflect.defineMetadata(constructor, "flamework:providerConfig", config or {})
 	end

package/out/reflect.luau

@@ -1,4 +1,7 @@
 -- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local forgetImplements = TS.import(script, script.Parent, "utility", "implementsCache").forgetImplements
+local recordModuleClass = TS.import(script, script.Parent, "utility", "moduleClasses").recordModuleClass
 --[[
 	*
 	 * Reflection/metadata API
@@ -60,6 +63,15 @@ do
 		local _key = key
 		local _value = value
 		metadata[_key] = _value
+		-- What `getClassImplements` keeps per class is built from this key.
+		if key == "flamework:implements" then
+			forgetImplements(obj)
+		end
+		-- The transformer records the module a class was defined in under this key, which is how
+		-- path registration finds a class its module does not export.
+		if key == "flamework:module" and property == nil then
+			recordModuleClass(value, obj)
+		end
 	end
 	_container.defineMetadata = defineMetadata
 	--[[
@@ -72,6 +84,7 @@ do
 		for key, value in pairs(list) do
 			metadata[key] = value
 		end
+		forgetImplements(obj)
 	end
 	_container.defineMetadataBatch = defineMetadataBatch
 	--[[
@@ -86,6 +99,9 @@ do
 			local _key = key
 			_result[_key] = nil
 		end
+		if key == "flamework:implements" then
+			forgetImplements(obj)
+		end
 	end
 	_container.deleteMetadata = deleteMetadata
 	--[[
@@ -302,6 +318,7 @@ do
 	local function resetObject(object)
 		local _object = object
 		metadata[_object] = nil
+		forgetImplements(object)
 	end
 	_container.resetObject = resetObject
 end

package/out/utility/explainUnresolved.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export declare function explainUnresolvedClass(id: string, origin?: object): string | undefined;

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/getClassImplements.d.ts

@@ -1,7 +1,14 @@
 /**
- * The interfaces a class implements, own and inherited, each once: the transformer writes every
+ * The interfaces an object implements, own and inherited, each once: the transformer writes every
  * class's own heritage clause, so a subclass that re-declares an interface its parent implements
  * carries the id twice up the chain, and attached to it twice -- the lifecycle's ordered lists ran
  * `onInit` and `onStart` twice for it.
+ *
+ * Walked once per class and kept: this runs on every attach and detach, and behind
+ * `Flamework.implements`. An instance, which implements nothing of its own, answers its class's
+ * list; so does a class asked directly. An object that implements something of its own -- a
+ * `listen` proxy, a plain object given the metadata -- or whose `__index` is not a table is walked
+ * every time, as before, rather than kept per object. The list is shared and frozen: callers must
+ * not change it.
  */
-export declare function getClassImplements(constructor: object): string[];
+export declare function getClassImplements(object: object): ReadonlyArray<string>;

package/out/utility/getClassImplements.luau

@@ -1,18 +1,26 @@
 -- Compiled with roblox-ts v3.0.0
 local TS = _G[script]
 local Reflect = TS.import(script, script.Parent.Parent, "reflect").Reflect
+local implementsCache = TS.import(script, script.Parent, "implementsCache").implementsCache
+local IMPLEMENTS = "flamework:implements"
+local EMPTY = table.freeze({})
+--* Where `Reflect.getMetadatas` goes next from an object: its metatable's `__index`, its class. 
+local function getParent(object)
+	local metatable = getmetatable(object)
+	if metatable ~= nil and type(metatable) == "table" then
+		return rawget(metatable, "__index")
+	end
+end
 --[[
 	*
-	 * The interfaces a class implements, own and inherited, each once: the transformer writes every
-	 * class's own heritage clause, so a subclass that re-declares an interface its parent implements
-	 * carries the id twice up the chain, and attached to it twice -- the lifecycle's ordered lists ran
-	 * `onInit` and `onStart` twice for it.
+	 * The walk as `Reflect.getMetadatas` makes it, for an object whose list is not cached: every
+	 * `flamework:implements` list from the object up its chain, each id once, first seen first.
 	 
 ]]
-local function getClassImplements(constructor)
+local function collect(object)
 	local classImplements = {}
 	local seen = {}
-	for _, implementList in Reflect.getMetadatas(constructor, "flamework:implements") do
+	for _, implementList in Reflect.getMetadatas(object, IMPLEMENTS) do
 		for _1, implementId in implementList do
 			if not (seen[implementId] ~= nil) then
 				seen[implementId] = true
@@ -22,6 +30,81 @@ local function getClassImplements(constructor)
 	end
 	return classImplements
 end
+--[[
+	*
+	 * A class's list, built once: its own ids, then those of the class above it that it does not
+	 * re-declare, which is the order and the ids `collect` finds. One that declares nothing of its own
+	 * shares the list above it.
+	 
+]]
+local function getCachedImplements(object)
+	local _byClass = implementsCache.byClass
+	local _object = object
+	local cached = _byClass[_object]
+	if cached ~= nil then
+		return cached
+	end
+	local parent = getParent(object)
+	local inherited = if parent ~= nil then getCachedImplements(parent) else EMPTY
+	local list = inherited
+	local own = Reflect.getOwnMetadata(object, IMPLEMENTS)
+	if own ~= nil then
+		local merged = {}
+		for _, implementId in own do
+			if not (table.find(merged, implementId) ~= nil) then
+				table.insert(merged, implementId)
+			end
+		end
+		for _, implementId in inherited do
+			if not (table.find(merged, implementId) ~= nil) then
+				table.insert(merged, implementId)
+			end
+		end
+		list = table.freeze(merged)
+	end
+	local _byClass_1 = implementsCache.byClass
+	local _object_1 = object
+	local _list = list
+	_byClass_1[_object_1] = _list
+	return list
+end
+--[[
+	*
+	 * The interfaces an object implements, own and inherited, each once: the transformer writes every
+	 * class's own heritage clause, so a subclass that re-declares an interface its parent implements
+	 * carries the id twice up the chain, and attached to it twice -- the lifecycle's ordered lists ran
+	 * `onInit` and `onStart` twice for it.
+	 *
+	 * Walked once per class and kept: this runs on every attach and detach, and behind
+	 * `Flamework.implements`. An instance, which implements nothing of its own, answers its class's
+	 * list; so does a class asked directly. An object that implements something of its own -- a
+	 * `listen` proxy, a plain object given the metadata -- or whose `__index` is not a table is walked
+	 * every time, as before, rather than kept per object. The list is shared and frozen: callers must
+	 * not change it.
+	 
+]]
+local function getClassImplements(object)
+	if Reflect.getOwnMetadata(object, IMPLEMENTS) == nil then
+		local parent = getParent(object)
+		if parent == nil then
+			return EMPTY
+		end
+		if type(parent) == "table" then
+			return getCachedImplements(parent)
+		end
+	else
+		local _object = object
+		local _condition = type(_object) == "table"
+		if _condition then
+			_condition = rawget(object, "__index") == object
+		end
+		if _condition then
+			-- A class: a roblox-ts class is its own instances' `__index`.
+			return getCachedImplements(object)
+		end
+	end
+	return collect(object)
+end
 return {
 	getClassImplements = getClassImplements,
 }

package/out/utility/getClassesInPath.d.ts

@@ -14,8 +14,16 @@ 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 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.

package/out/utility/getClassesInPath.luau

@@ -3,6 +3,7 @@ local TS = _G[script]
 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 getModuleClasses = TS.import(script, script.Parent, "moduleClasses").getModuleClasses
 --[[
 	*
 	 * Requires one ModuleScript through the roblox-ts runtime, as an `import` would, and returns what
@@ -20,6 +21,25 @@ local function importModule(moduleScript)
 	end
 	return value
 end
+--[[
+	*
+	 * Requires every ModuleScript at and under a Rojo path, in tree order, handing each to `visit` with
+	 * what it exported.
+	 
+]]
+local function loadModulesInPath(rbxPath, visit)
+	local _rbxPath = rbxPath
+	assert(_rbxPath)
+	local preloadPath = resolveRbxPath(rbxPath)
+	if preloadPath:IsA("ModuleScript") then
+		visit(preloadPath, importModule(preloadPath))
+	end
+	for _, instance in preloadPath:GetDescendants() do
+		if instance:IsA("ModuleScript") then
+			visit(instance, importModule(instance))
+		end
+	end
+end
 --[[
 	*
 	 * Requires every ModuleScript at and under the specified Rojo path, in tree order, and returns
@@ -32,30 +52,27 @@ 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)
+	loadModulesInPath(rbxPath, function(_, value)
 		if value ~= nil then
-			table.insert(loaded, value)
+			local _value = value
+			table.insert(loaded, _value)
 		end
-	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
-	end
+	end)
 	return loaded
 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.
@@ -63,25 +80,47 @@ end
 ]]
 local function getClassesInPath(rbxPath)
 	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)
 	return foundClasses
 end
 return {

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/implementsCache.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What each class implements, own and inherited, as `getClassImplements` found it, by the class --
+ * and by every class above it, which it walked on the way. Its own module, apart from
+ * `getClassImplements`, so that `Reflect`, which that one reads through, can reach it too.
+ */
+export declare const implementsCache: {
+    byClass: WeakMap<object, readonly string[]>;
+};
+/**
+ * Forgets every list once an object whose `flamework:implements` metadata one was built from has
+ * it changed: the lists of the classes below it were built from it too. The transformer writes a
+ * class's metadata as the class is defined, before anything can ask, so this does not happen in a
+ * game; it keeps a later change seen as it was before the lists were cached. What `listen` gives
+ * its proxies changes nothing here: an object that implements something of its own is not cached.
+ */
+export declare function forgetImplements(object: object): void;

package/out/utility/implementsCache.luau

@@ -0,0 +1,35 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * What each class implements, own and inherited, as `getClassImplements` found it, by the class --
+	 * and by every class above it, which it walked on the way. Its own module, apart from
+	 * `getClassImplements`, so that `Reflect`, which that one reads through, can reach it too.
+	 
+]]
+local implementsCache = {
+	byClass = setmetatable({}, {
+		__mode = "k",
+	}),
+}
+--[[
+	*
+	 * Forgets every list once an object whose `flamework:implements` metadata one was built from has
+	 * it changed: the lists of the classes below it were built from it too. The transformer writes a
+	 * class's metadata as the class is defined, before anything can ask, so this does not happen in a
+	 * game; it keeps a later change seen as it was before the lists were cached. What `listen` gives
+	 * its proxies changes nothing here: an object that implements something of its own is not cached.
+	 
+]]
+local function forgetImplements(object)
+	local _byClass = implementsCache.byClass
+	local _object = object
+	if _byClass[_object] ~= nil then
+		implementsCache.byClass = setmetatable({}, {
+			__mode = "k",
+		})
+	end
+end
+return {
+	forgetImplements = forgetImplements,
+	implementsCache = implementsCache,
+}

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;