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

package/out/module/module.luau

@@ -5,11 +5,20 @@ local convertConciseDependencyInfo = TS.import(script, script.Parent.Parent, "ut
 local getClassImplements = TS.import(script, script.Parent.Parent, "utility", "getClassImplements").getClassImplements
 local getClassesInPath = TS.import(script, script.Parent.Parent, "utility", "getClassesInPath").getClassesInPath
 local getClassesInGlob = TS.import(script, script.Parent.Parent, "utility", "globs").getClassesInGlob
+local explainUnresolvedClass = TS.import(script, script.Parent.Parent, "utility", "explainUnresolved").explainUnresolvedClass
+local _leftOut = TS.import(script, script.Parent.Parent, "utility", "leftOut")
+local explainLeftOut = _leftOut.explainLeftOut
+local leftOutRegistration = _leftOut.leftOutRegistration
+local _threadWaits = TS.import(script, script.Parent.Parent, "utility", "threadWaits")
+local extinguishesBegun = _threadWaits.extinguishesBegun
+local threadWaits = _threadWaits.threadWaits
 local clearDefaultModule = TS.import(script, script.Parent, "defaultModule").clearDefaultModule
 local HookPriority = TS.import(script, script.Parent, "moduleHooks").HookPriority
 local _providerRegistration = TS.import(script, script.Parent, "providerRegistration")
+local DEFAULT_LOAD_ORDER = _providerRegistration.DEFAULT_LOAD_ORDER
 local getProviderClassId = _providerRegistration.getProviderClassId
 local getProviderClassScope = _providerRegistration.getProviderClassScope
+local getProviderLoadOrder = _providerRegistration.getProviderLoadOrder
 local normalizeProviderConfig = _providerRegistration.normalizeProviderConfig
 local _scopes = TS.import(script, script.Parent, "scopes")
 local NO_CONDITION = _scopes.NO_CONDITION
@@ -73,6 +82,12 @@ local function createModuleInstantiation(state, options)
 	local providers = {}
 	--* The registrations left out, by id, with the conditions that were judged: for the error a miss gets. 
 	local skipped = {}
+	--* The path and glob registrations left out by their own condition, the builder's and the plugins'. 
+	local _array_2 = {}
+	local _length_1 = #_array_2
+	local _array_3 = (state.leftOut or {})
+	table.move(_array_3, 1, #_array_3, _length_1 + 1, _array_2)
+	local leftOut = _array_2
 	--* Modules searched after this one's own providers, in order. Ignited before this one, and extinguished after. 
 	local _result = options
 	if _result ~= nil then
@@ -88,12 +103,24 @@ local function createModuleInstantiation(state, options)
 	local instantiatedProviders = {}
 	--* Objects handed over by `provideInstance`, attached to their interfaces once every plugin is set up. 
 	local providedInstances = {}
+	--[[
+		*
+		     * Provided objects that have not joined their interfaces: until the ignition reaches them, and
+		     * for good when an observer refuses one. `release` has nothing to take them out of, and a failed
+		     * ignition told every observer `onRemoved` for objects it had never been told of, and told the
+		     * observers that had just undone a refused one of it again.
+		     
+	]]
+	local unjoinedInstances = {}
 	local observers = {}
 	local hooks = {}
 	local includedPlugins = {}
 	local filledSlots = {}
 	local temporaryInstances = {}
 	local moduleInitState = ModuleInitState.Created
+	--* The thread `extinguish` runs on, and what wakes each thread waiting in `awaitExtinguished` for it to finish. 
+	local extinguishingThread
+	local extinguishWaiters = {}
 	local switchInitState = function(from, to)
 		if moduleInitState ~= from then
 			error(`module '{state.debugName}' is in invalid state when transitioning to '{ModuleInitState[to]}', got '{ModuleInitState[moduleInitState]}' when '{ModuleInitState[from]}' was expected.`)
@@ -214,6 +241,67 @@ local function createModuleInstantiation(state, options)
 		end
 		providers = active
 	end
+	--[[
+		*
+		     * The registrations in ascending `loadOrder`, registration order among equals. The same list
+		     * when none sets one, which is every module that does not use it.
+		     
+	]]
+	local inLoadOrder = function(entries)
+		-- ▼ ReadonlyArray.map ▼
+		local _newValue = table.create(#entries)
+		local _callback = function(entry)
+			local _condition_1 = getProviderLoadOrder(entry.config)
+			if _condition_1 == nil then
+				_condition_1 = DEFAULT_LOAD_ORDER
+			end
+			return _condition_1
+		end
+		for _k, _v in entries do
+			_newValue[_k] = _callback(_v, _k - 1, entries)
+		end
+		-- ▲ ReadonlyArray.map ▲
+		local orders = _newValue
+		-- ▼ ReadonlyArray.every ▼
+		local _result_1 = true
+		local _callback_1 = function(order)
+			return order == DEFAULT_LOAD_ORDER
+		end
+		for _k, _v in orders do
+			if not _callback_1(_v, _k - 1, orders) then
+				_result_1 = false
+				break
+			end
+		end
+		-- ▲ ReadonlyArray.every ▲
+		if _result_1 then
+			return entries
+		end
+		-- `table.sort` is not stable, so equals are ordered by their position.
+		-- ▼ ReadonlyArray.map ▼
+		local _newValue_1 = table.create(#entries)
+		local _callback_2 = function(_, index)
+			return index
+		end
+		for _k, _v in entries do
+			_newValue_1[_k] = _callback_2(_v, _k - 1, entries)
+		end
+		-- ▲ ReadonlyArray.map ▲
+		local indices = _newValue_1
+		table.sort(indices, function(a, b)
+			return if orders[a + 1] ~= orders[b + 1] then orders[a + 1] < orders[b + 1] else a < b
+		end)
+		-- ▼ ReadonlyArray.map ▼
+		local _newValue_2 = table.create(#indices)
+		local _callback_3 = function(index)
+			return entries[index + 1]
+		end
+		for _k, _v in indices do
+			_newValue_2[_k] = _callback_3(_v, _k - 1, indices)
+		end
+		-- ▲ ReadonlyArray.map ▲
+		return _newValue_2
+	end
 	local registerHook = function(phase, callback, priority)
 		local _object = {
 			phase = phase,
@@ -233,11 +321,11 @@ local function createModuleInstantiation(state, options)
 		local _callback = function(hook)
 			return hook.phase == phase
 		end
-		local _length_1 = 0
+		local _length_2 = 0
 		for _k, _v in hooks do
 			if _callback(_v, _k - 1, hooks) == true then
-				_length_1 += 1
-				_newValue[_length_1] = _v
+				_length_2 += 1
+				_newValue[_length_2] = _v
 			end
 		end
 		-- ▲ ReadonlyArray.filter ▲
@@ -292,12 +380,18 @@ local function createModuleInstantiation(state, options)
 		     * observer that raises from its `onAdded` has the ones before it told `onRemoved`, and the
 		     * error comes out, so a refused object is attached nowhere -- rather than left ticking in the
 		     * lifecycle's sets, with no handle to remove it by.
+		     *
+		     * `dependencies`, what a provider's constructor was given, is handed to the observers with it.
 		     
 	]]
-	local registerClassInterfaces = function(instance, kind)
-		local added = {}
+	local registerClassInterfaces = function(instance, kind, dependencies, loadOrder)
+		local interfaces = getClassImplements(instance)
+		-- How many observers have been told `onAdded`, in the order they were told: what a refusal
+		-- undoes. Counted rather than recorded, since an attachment that goes through -- every one,
+		-- in a game -- then builds nothing to throw away.
+		local attached = 0
 		local success, err = pcall(function()
-			for _, interfaceId in getClassImplements(instance) do
+			for _, interfaceId in interfaces do
 				local interested = observers[interfaceId]
 				if not interested then
 					continue
@@ -308,18 +402,36 @@ local function createModuleInstantiation(state, options)
 						_result_1(instance, {
 							interfaceId = interfaceId,
 							kind = kind,
+							dependencies = dependencies,
+							loadOrder = loadOrder,
 						})
 					end
-					local _arg0 = { interfaceId, observer }
-					table.insert(added, _arg0)
+					attached += 1
 				end
 			end
 		end)
 		if not success then
+			-- The observers told, found again by walking the same way as far as the count goes.
+			local told = {}
+			for _, interfaceId in interfaces do
+				local interested = observers[interfaceId]
+				if not interested then
+					continue
+				end
+				for _1, observer in interested do
+					if #told == attached then
+						break
+					end
+					local _arg0 = { interfaceId, observer }
+					table.insert(told, _arg0)
+				end
+			end
 			-- Undone in reverse, each step guarded, so that one `onRemoved` raising does not leave
-			-- the rest attached; the observer's error is what comes out.
-			for i = #added - 1, 0, -1 do
-				local _binding = added[i + 1]
+			-- the rest attached; the observer's error is what comes out. Marked as refused, so that
+			-- an observer owing a departing object a last event -- the lifecycle plugin's
+			-- `onExtinguished` while the module extinguishes -- does not deliver it.
+			for i = #told - 1, 0, -1 do
+				local _binding = told[i + 1]
 				local interfaceId = _binding[1]
 				local observer = _binding[2]
 				guarded("undoing an attachment", function()
@@ -328,6 +440,7 @@ local function createModuleInstantiation(state, options)
 						_result_1 = _result_1(instance, {
 							interfaceId = interfaceId,
 							kind = kind,
+							refused = true,
 						})
 					end
 					return _result_1
@@ -353,11 +466,15 @@ local function createModuleInstantiation(state, options)
 			end
 		end
 	end
+	--* Constructs a class, resolving what its constructor takes into `resolvedParameters`. 
 	local resolveDependencyWithOrigin
-	local instantiateClassWithDependencies = function(constructor, resolve)
+	local instantiateClassWithDependencies = function(constructor, resolve, resolvedParameters)
+		if resolvedParameters == nil then
+			resolvedParameters = {}
+		end
 		local dependencies = Reflect.getMetadata(constructor, "flamework:dependencies") or {}
-		local resolvedParameters = {}
 		for _, dependency in dependencies do
+			local _resolvedParameters = resolvedParameters
 			local _result_1 = resolve
 			if _result_1 ~= nil then
 				_result_1 = _result_1(dependency)
@@ -366,7 +483,7 @@ local function createModuleInstantiation(state, options)
 			if _condition_1 == nil then
 				_condition_1 = resolveDependencyWithOrigin(dependency, constructor)
 			end
-			table.insert(resolvedParameters, _condition_1)
+			table.insert(_resolvedParameters, _condition_1)
 		end
 		return constructor.new(unpack(resolvedParameters))
 	end
@@ -405,10 +522,21 @@ local function createModuleInstantiation(state, options)
 		if moduleProvider then
 			local config = moduleProvider.config
 			if config.type == "class" then
-				local instantiatedProvider = instantiateClassWithDependencies(config.value)
+				local dependencies = {}
+				local instantiatedProvider = instantiateClassWithDependencies(config.value, nil, dependencies)
 				local _id_1 = info.id
 				instantiatedProviders[_id_1] = instantiatedProvider
-				registerClassInterfaces(instantiatedProvider, "provider")
+				-- Held only if it is attached: one an observer refuses is attached nowhere, so it must
+				-- not be cached either -- the next resolve handed it out with no lifecycle at all, and
+				-- `release` told every observer, the refusing one included, it was removed again.
+				local attached, err = pcall(function()
+					return registerClassInterfaces(instantiatedProvider, "provider", dependencies, getProviderLoadOrder(config))
+				end)
+				if not attached then
+					local _id_2 = info.id
+					instantiatedProviders[_id_2] = nil
+					error(err, 0)
+				end
 				return instantiatedProvider
 			elseif config.type == "function" then
 				-- Function providers are not cached.
@@ -456,6 +584,17 @@ local function createModuleInstantiation(state, options)
 			if inactive ~= nil then
 				error(`module '{state.debugName}' could not resolve dependency '{info.id}': it is registered but inactive ({describeConditions(inactive)}){searched}`)
 			end
+			-- A folder registration left out by its own condition registered nothing to be inactive.
+			local leftOutReason = explainLeftOut(info.id, leftOut)
+			if leftOutReason ~= nil then
+				error(`module '{state.debugName}' could not resolve dependency '{info.id}': {leftOutReason}{searched}`)
+			end
+			-- A class that has been loaded says why it is not here: a component, a provider nothing
+			-- registered, a class that is not a provider at all.
+			local explanation = explainUnresolvedClass(info.id, requestingOrigin)
+			if explanation ~= nil then
+				error(`module '{state.debugName}' could not resolve dependency '{info.id}': {explanation}{searched}`)
+			end
 			error(`module '{state.debugName}' could not resolve dependency '{info.id}'{searched}`)
 		end
 		return dependency
@@ -602,14 +741,27 @@ local function createModuleInstantiation(state, options)
 			-- every plugin's observers are in place.
 			for _, instance in providedInstances do
 				registerClassInterfaces(instance, "provider")
+				unjoinedInstances[instance] = nil
 			end
-			for _, provider in providers do
+			-- In ascending `loadOrder`, each after what its constructor takes, which is the order the
+			-- lifecycle plugin runs `onInit` in: a low `loadOrder` goes first and pulls its
+			-- dependencies forward with it, and dependency order still wins over `loadOrder`.
+			for _, provider in inLoadOrder(providers) do
 				-- Lazy providers are constructed the first time they are resolved instead.
 				if provider.config.type == "class" and provider.config.lazy ~= true then
 					resolveDependency(provider.injectionId)
 				end
 			end
 			runHooks("postIgnite")
+			-- Checked again once everything has run: an `onInit` that yields lets other threads run in
+			-- the middle of ignition, and one that extinguished an import then did not see this module
+			-- among its importers, since it joins them only below. Carrying on left it ignited onto a
+			-- released import that would never take it down.
+			for _, imported in imports do
+				if not imported.isIgnited() then
+					error(`module '{state.debugName}': imported module '{imported.debugName}' was extinguished while this module was igniting`)
+				end
+			end
 		end)
 		if not success then
 			moduleInitState = ModuleInitState.Extinguishing
@@ -621,21 +773,40 @@ local function createModuleInstantiation(state, options)
 		for _, imported in imports do
 			imported.addImporter(module)
 		end
+		-- Ignition has completed, so this is where the lifecycle plugin starts the providers: an
+		-- `onStart` sees the module ignited, may extinguish it, and may ignite one that imports it.
+		-- Nothing here can fail the ignition, so a hook that raises is warned about. One that
+		-- extinguishes the module ends the phase: the hooks after it would set up a module gone.
+		for _, hook in sortedHooks("ignited") do
+			if moduleInitState ~= ModuleInitState.Ignited then
+				break
+			end
+			guarded("an onIgnited hook", function()
+				return hook.callback(module)
+			end)
+		end
 		return module
 	end
 	local extinguish = function()
 		switchInitState(ModuleInitState.Ignited, ModuleInitState.Extinguishing)
+		extinguishingThread = coroutine.running()
+		extinguishesBegun.count += 1
 		-- Importers hold this module's instances, so they go first, and each takes its own importers
-		-- down before it returns: the deepest goes first. Copied, since each removes itself.
-		local _array_2 = {}
-		local _length_1 = #_array_2
+		-- down before it returns: the deepest goes first. Copied, since each removes itself. One
+		-- extinguishing already, on another thread suspended in a handler that yields, is still
+		-- using this module's providers, so it is waited for: skipped, it had this module released
+		-- under it.
+		local _array_4 = {}
+		local _length_2 = #_array_4
 		for _v in importers do
-			_length_1 += 1
-			_array_2[_length_1] = _v
+			_length_2 += 1
+			_array_4[_length_2] = _v
 		end
-		for _, importer in _array_2 do
+		for _, importer in _array_4 do
 			if not importer.isExtinguished() then
 				importer.extinguish()
+			else
+				importer.awaitExtinguished()
 			end
 		end
 		table.clear(importers)
@@ -660,13 +831,13 @@ local function createModuleInstantiation(state, options)
 			end)
 		end
 		-- Copied first: removal callbacks may themselves remove instances.
-		local _array_2 = {}
-		local _length_1 = #_array_2
+		local _array_4 = {}
+		local _length_2 = #_array_4
 		for _v in temporaryInstances do
-			_length_1 += 1
-			_array_2[_length_1] = _v
+			_length_2 += 1
+			_array_4[_length_2] = _v
 		end
-		for _, temporaryInstance in _array_2 do
+		for _, temporaryInstance in _array_4 do
 			guarded("removing an instance", function()
 				return removeClassInstance(temporaryInstance)
 			end)
@@ -674,10 +845,31 @@ local function createModuleInstantiation(state, options)
 		-- Providers join their interfaces when they are instantiated, so they have to leave them
 		-- too. Without this, a plugin such as the lifecycle plugin keeps holding (and ticking)
 		-- providers that belong to an extinguished module.
-		for _, provider in instantiatedProviders do
-			guarded("removing a provider", function()
-				return unregisterClassInterfaces(provider, "provider")
-			end)
+		--
+		-- Over a copy, taken again until nothing new turns up: a removal runs user code -- the
+		-- lifecycle plugin tells a provider resolved since its walk `onExtinguished` as it leaves --
+		-- which may resolve a lazy provider for the first time, and a table gaining keys while it
+		-- is walked skipped providers, or had others unregistered twice. By object, not by id: an
+		-- object provided under several ids joined its interfaces once, so it leaves them once.
+		local released = {}
+		while true do
+			local remaining = {}
+			for _, provider in instantiatedProviders do
+				if not (released[provider] ~= nil) then
+					released[provider] = true
+					if not (unjoinedInstances[provider] ~= nil) then
+						table.insert(remaining, provider)
+					end
+				end
+			end
+			if #remaining == 0 then
+				break
+			end
+			for _, provider in remaining do
+				guarded("removing a provider", function()
+					return unregisterClassInterfaces(provider, "provider")
+				end)
+			end
 		end
 		-- A removal that raised leaves its instance behind, and nothing can add one any more.
 		table.clear(temporaryInstances)
@@ -689,6 +881,80 @@ local function createModuleInstantiation(state, options)
 		-- Released last, once nothing in here can resolve any more, so that the next root ignited
 		-- becomes the default rather than `Dependency<T>()` answering from a dead module.
 		clearDefaultModule(module)
+		for _, wake in extinguishWaiters do
+			wake()
+		end
+		table.clear(extinguishWaiters)
+	end
+	local awaitExtinguished = function()
+		if moduleInitState ~= ModuleInitState.Extinguishing then
+			return nil
+		end
+		-- On the extinguish's own thread -- one of its handlers extinguishing an import -- it cannot
+		-- finish until this returns, so waiting would never end. Nor on a thread the extinguish's
+		-- thread is itself waiting on here, however many waits away: two extinguishes, each waiting
+		-- for a module the other is taking down, held each other -- and every module between them,
+		-- still ticking -- for good. The wait that would close the circle is skipped, as the wait on
+		-- the extinguish's own thread is. The chain runs through an ignition waiting for an `onInit`
+		-- on its own thread too, which the lifecycle plugin records -- and through one waiting for the
+		-- Promise an `onInit` returned, whose work runs on a thread nothing can name: an `async`
+		-- method's body runs on one of its own. A chain that ends at one is taken to close the circle,
+		-- since the thread that settles it may be this one.
+		local running = coroutine.running()
+		local thread = extinguishingThread
+		local closesCircle = function()
+			local waitedOn = thread
+			while waitedOn ~= nil do
+				local _condition_1 = waitedOn == running
+				if not _condition_1 then
+					local _waitedOn = waitedOn
+					_condition_1 = not (type(_waitedOn) == "thread")
+				end
+				if _condition_1 then
+					return true
+				end
+				local _waitedOn = waitedOn
+				waitedOn = threadWaits[_waitedOn]
+			end
+			return false
+		end
+		if closesCircle() then
+			return nil
+		end
+		-- Nor on a thread that has died -- cancelled, as the testing runner cancels a body that
+		-- overran, or closed: that extinguish never finishes, and waiting for it held this module,
+		-- and everything in it, for good. One that dies while this waits is noticed within a frame.
+		if coroutine.status(thread) == "dead" then
+			return nil
+		end
+		local woken = false
+		local wake = function()
+			if woken then
+				return nil
+			end
+			woken = true
+			-- Removed here rather than by this thread once it resumes: one cancelled while it waits
+			-- never does, and left its entry behind for good.
+			threadWaits[running] = nil
+			if coroutine.status(running) ~= "dead" then
+				task.spawn(running)
+			end
+		end
+		threadWaits[running] = thread
+		table.insert(extinguishWaiters, wake)
+		-- Checked again every frame, as well as for a dead extinguish: this thread may be cancelled
+		-- while it waits, and the chain may come to close the circle after the wait began -- an
+		-- `async` `onInit`'s body waits here before the ignition that called it takes the Promise it
+		-- returned and waits on that.
+		task.spawn(function()
+			while not woken do
+				task.wait()
+				if coroutine.status(thread) == "dead" or coroutine.status(running) == "dead" or closesCircle() then
+					wake()
+				end
+			end
+		end)
+		coroutine.yield()
 	end
 	local isExtinguished = function()
 		return moduleInitState >= ModuleInitState.Extinguishing
@@ -721,6 +987,7 @@ local function createModuleInstantiation(state, options)
 			-- ▲ Set.delete ▲
 			return _valueExisted
 		end,
+		awaitExtinguished = awaitExtinguished,
 	}
 	--* What a plugin's setup is handed. Everything registers into this instantiation. 
 	pluginTarget = {
@@ -728,21 +995,35 @@ local function createModuleInstantiation(state, options)
 		scope = if hasCondition(moduleScope) then moduleScope else nil,
 		isActive = function(...)
 			local conditions = { ... }
-			local _array_2 = { moduleScope }
-			local _length_1 = #_array_2
-			table.move(conditions, 1, #conditions, _length_1 + 1, _array_2)
-			return holdsEveryCondition(_array_2)
+			local _array_4 = { moduleScope }
+			local _length_2 = #_array_4
+			table.move(conditions, 1, #conditions, _length_2 + 1, _array_4)
+			return holdsEveryCondition(_array_4)
 		end,
 		registerClassProvider = registerClassProvider,
-		registerProviders = function(_path, registrationOptions, resolved)
+		registerProviders = function(path, registrationOptions, resolved)
 			local _arg0 = resolved ~= nil
 			assert(_arg0)
-			registerProviderClasses(getClassesInPath(resolved), registrationOptions)
+			if holdsCondition(registrationOptions) then
+				registerProviderClasses(getClassesInPath(resolved), registrationOptions)
+			else
+				local _arg0_1 = leftOutRegistration(`registerProviders("{path}")`, registrationOptions, {
+					path = resolved,
+				})
+				table.insert(leftOut, _arg0_1)
+			end
 		end,
-		registerProvidersGlob = function(_glob, registrationOptions, resolved)
+		registerProvidersGlob = function(glob, registrationOptions, resolved)
 			local _arg0 = resolved ~= nil
 			assert(_arg0)
-			registerProviderClasses(getClassesInGlob(resolved), registrationOptions)
+			if holdsCondition(registrationOptions) then
+				registerProviderClasses(getClassesInGlob(resolved), registrationOptions)
+			else
+				local _arg0_1 = leftOutRegistration(`registerProvidersGlob("{glob}")`, registrationOptions, {
+					glob = resolved,
+				})
+				table.insert(leftOut, _arg0_1)
+			end
 		end,
 		registerProvider = function(config, injectionId)
 			local _arg0 = injectionId ~= nil
@@ -760,8 +1041,15 @@ local function createModuleInstantiation(state, options)
 			local _injectionId = injectionId
 			local _instance = instance
 			instantiatedProviders[_injectionId] = _instance
+			-- Once, however many ids it is provided under: it joins its interfaces once per entry,
+			-- and the same object twice was initialised, started and told `onAdded` twice.
 			local _instance_1 = instance
-			table.insert(providedInstances, _instance_1)
+			if not (table.find(providedInstances, _instance_1) ~= nil) then
+				local _instance_2 = instance
+				table.insert(providedInstances, _instance_2)
+				local _instance_3 = instance
+				unjoinedInstances[_instance_3] = true
+			end
 		end,
 		includePlugin = includePlugin,
 		onPreIgnite = function(callback, hookOptions)
@@ -780,6 +1068,14 @@ local function createModuleInstantiation(state, options)
 			end
 			return registerHook("postIgnite", _exp, _result_1)
 		end,
+		onIgnited = function(callback, hookOptions)
+			local _exp = callback
+			local _result_1 = hookOptions
+			if _result_1 ~= nil then
+				_result_1 = _result_1.priority
+			end
+			return registerHook("ignited", _exp, _result_1)
+		end,
 		onExtinguished = function(callback, hookOptions)
 			local _exp = callback
 			local _result_1 = hookOptions

package/out/module/moduleBuilder.d.ts

@@ -2,7 +2,7 @@ import { Modding } from "../modding";
 import { ModuleDefinition, ProviderConfig, type IgniteOptions, type ProviderRegistrationOptions } from "./moduleDefinition";
 import type { Constructor } from "../utility/constructors";
 import { type PluginDefinition } from "../plugin/pluginDefinition";
-import type { ScopeCondition } from "./scopes";
+import { type ScopeCondition } from "./scopes";
 type GenericId<T> = string | Modding.Target.Id<T>;
 export declare class ModuleBuilder {
     /** A global count of the number of module builders. Used to disambiguate identical module debug names. */
@@ -36,10 +36,16 @@ export declare class ModuleBuilder {
     /**
      * Register all providers under the specified path and its descendants.
      *
-     * The providers must be exported, and must carry the `@Provider()` decorator themselves: an
-     * undecorated subclass of a provider is not registered.
+     * Every `@Provider()` class the modules there define at their top level is registered, exported
+     * or not, as v1 registered every decorated class it required, and so is one they export from
+     * elsewhere; each once. A class declared inside a function is registered only if its module
+     * exports it. A provider must carry the `@Provider()` decorator itself: an undecorated subclass
+     * of a provider is not registered.
      *
      * The options apply to every provider found: a scope condition here scopes the whole folder.
+     * When it does not hold, the folder is not touched at all -- not looked up, nothing under it
+     * required -- so a build can leave the folder out of the place (a release build without its
+     * tests, say).
      *
      * @metadata macro
      */
@@ -51,6 +57,9 @@ export declare class ModuleBuilder {
      * This is the v2 equivalent of v1's `Flamework.addPathsGlob`. Globs can match a large number of
      * paths, so keep them as specific as possible.
      *
+     * As with `registerProviders`, a scope condition that does not hold leaves every matched folder
+     * untouched.
+     *
      * @metadata macro
      */
     registerProvidersGlob<T extends string>(_glob: T, options?: ProviderRegistrationOptions, glob?: Modding.Intrinsic<"pathglob", [T], string>): this;

package/out/module/moduleBuilder.luau

@@ -8,6 +8,8 @@ local LIFECYCLE_SLOT = TS.import(script, script.Parent.Parent, "plugin", "plugin
 local _providerRegistration = TS.import(script, script.Parent, "providerRegistration")
 local getProviderClassId = _providerRegistration.getProviderClassId
 local normalizeProviderConfig = _providerRegistration.normalizeProviderConfig
+local holdsCondition = TS.import(script, script.Parent, "scopes").holdsCondition
+local leftOutRegistration = TS.import(script, script.Parent.Parent, "utility", "leftOut").leftOutRegistration
 local ModuleBuilder
 do
 	ModuleBuilder = setmetatable({}, {
@@ -28,6 +30,7 @@ do
 			debugName = "Anonymous",
 			providers = {},
 			plugins = {},
+			leftOut = {},
 		}
 	end
 	function ModuleBuilder:includePlugin(plugin, options)
@@ -107,11 +110,30 @@ do
 	function ModuleBuilder:registerProviders(_stringPath, options, path)
 		local _path = path
 		assert(_path)
+		-- The active scopes are the ones the build was compiled with, so this is the answer
+		-- ignition would give; what it would register is only ever skipped there. Recorded, so that
+		-- a miss on a class under the folder can say why it is missing.
+		if not holdsCondition(options) then
+			local _leftOut = self.module.leftOut
+			local _arg0 = leftOutRegistration(`registerProviders("{_stringPath}")`, options, {
+				path = path,
+			})
+			table.insert(_leftOut, _arg0)
+			return self
+		end
 		return self:registerProviderClasses(getClassesInPath(path), options)
 	end
 	function ModuleBuilder:registerProvidersGlob(_glob, options, glob)
 		local _arg0 = glob ~= nil
 		assert(_arg0)
+		if not holdsCondition(options) then
+			local _leftOut = self.module.leftOut
+			local _arg0_1 = leftOutRegistration(`registerProvidersGlob("{_glob}")`, options, {
+				glob = glob,
+			})
+			table.insert(_leftOut, _arg0_1)
+			return self
+		end
 		return self:registerProviderClasses(getClassesInGlob(glob), options)
 	end
 	function ModuleBuilder:registerProviderClasses(classes, options)

package/out/module/moduleDefinition.d.ts

@@ -2,6 +2,7 @@ import type { Modding } from "../modding";
 import type { PluginDefinition } from "../plugin/pluginDefinition";
 import { type Module } from "./module";
 import type { ScopeCondition } from "./scopes";
+import type { LeftOutRegistration } from "../utility/leftOut";
 /**
  * Options for one ignition of a module.
  *
@@ -44,6 +45,11 @@ export interface ModuleState {
     readonly providers: readonly ModuleProvider[];
     /** The plugins to set up on ignition, in inclusion order. */
     readonly plugins: readonly PluginInclusion[];
+    /**
+     * The path and glob registrations left out by their own scope condition, whose folders were
+     * never looked up: what a miss on a class under one of them names.
+     */
+    readonly leftOut?: readonly LeftOutRegistration[];
 }
 export declare class ModuleDefinition {
     private moduleState;