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

package/docs/guide/11-scopes.md

@@ -0,0 +1,165 @@
+# 11. Scopes
+
+A **scope** is a name that a build is compiled with. You can tell providers, components,
+registrations, plugin inclusions and whole modules to exist only in builds with certain scopes
+active, or never in builds with others. That way a repository can hold test scenarios, debug tooling
+and stand-ins for production code, and none of it registers in a build that did not ask for it.
+
+## Naming the active scopes
+
+The active scopes are `scopes.active` in `flamework.config.json`. The list is meant to come from the
+environment:
+
+```jsonc
+// flamework.config.json
+{ "scopes": { "active": "${FLAMEWORK_SCOPES:-}" } }
+```
+
+```ini
+# .env.local
+FLAMEWORK_SCOPES=components,collections
+```
+
+The variable is split on commas. An empty value activates nothing, and `*` activates every scope.
+[Values from the environment](09-project-structure.md#values-from-the-environment) explains how the
+file reads `.env`. A running `rbxtsc -w` reports a change but keeps the scopes it started with, so
+restart the watcher to switch scopes (see [watching](09-project-structure.md#watching)).
+
+At runtime, `Flamework.activeScopes()` returns the list as configured.
+`Flamework.isScopeActive(name)` tells you whether one scope is active, and is always true when `*`
+is.
+
+## Conditions
+
+A condition has two lists:
+
+| Field | Holds when |
+|---|---|
+| `activeIn` | at least one of the names is active, or the list is empty |
+| `inactiveIn` | none of the names is active |
+
+You can set conditions at four levels: the module, a registration, a plugin inclusion and the class
+itself. They combine by AND: a class is registered only when every condition that applies to it
+holds.
+
+```ts
+// The module: everything it registers is subject to this.
+Flamework.createModule()
+	// A registration: everything under the folder gets this on top.
+	.registerProviders("src/server/Testing/components", { activeIn: ["components"] })
+	// A plugin inclusion: skipped entirely, hooks and all, unless it holds.
+	.includePlugin(ComponentPlugin.fromPath("src/server/Testing/components"), { activeIn: ["components"] })
+	.ignite({ activeIn: ["components"] });
+```
+
+```ts
+// The class itself.
+@Provider({ activeIn: ["components.streaming"] })
+export class StreamingProbe {
+	constructor(private readonly data: DataService) {}
+}
+
+@Component({ tag: "TestRig", activeIn: ["components"] })
+export class TestRig extends BaseComponent<{}, Model> {}
+```
+
+`StreamingProbe`, inside the module above, is registered only when both `components` and
+`components.streaming` are active. A class can narrow the condition of whatever registered it, but
+never widen it. A class inside a `components` module cannot exist without `components`. If it
+should, put it in another module or registration.
+
+A module whose own condition does not hold still ignites. It holds no providers and no components,
+but its plugins are set up. `Dependency<T>(module)` raises an error for anything it would have had.
+
+A path or glob registration whose own condition does not hold skips its folder entirely. It does not
+look the folder up or load anything in it, so the folder does not have to be in the place. This
+applies to `registerProviders`, `registerProvidersGlob`, `ComponentPlugin.fromPath` and `fromGlob`,
+`registerComponents` and `registerComponentsGlob`, and a plugin's own `registerProviders` and
+`registerProvidersGlob`.
+
+The other levels work differently:
+
+- The module's condition and the class's condition are checked at ignition, after the folder has
+  loaded.
+- A plugin inclusion whose condition does not hold skips the plugin's setup. So the registrations a
+  plugin makes in its setup never run, and their folders are not looked up.
+
+`ComponentPlugin.fromPath` and `fromGlob` look their folder up when you call them, before
+`includePlugin` sees its condition. Put the condition on `fromPath` itself.
+
+In the example above, `registerProviders` loads its folder only when `components` is active.
+`ComponentPlugin.fromPath` loads its folder in every build.
+
+## What being left out means
+
+A class whose conditions do not hold is **not registered**. It is not constructed, it receives no
+lifecycle events, and `resolveDependency` does not find it. A component that is left out is never
+attached to a tagged instance. Anything active that depends on a left-out class fails at ignition,
+with the reason:
+
+```
+module 'Game' could not resolve dependency 'server/Testing/Probe@Probe': it is registered but
+inactive (activeIn [components]; active scopes [])
+```
+
+`getComponent` on a left-out component says the same. A lazy provider that was left out reports it
+the first time something resolves it.
+
+A class under a folder whose registration was left out is different. That folder was never loaded,
+so the class was never registered at all. The error names the registration instead:
+
+```
+module 'Game' could not resolve dependency 'server/Testing/Probe@Probe': 'Probe'
+(ServerScriptService.TS.Testing.Probe) is under registerProviders("src/server/Testing"), which is
+left out by its scope (activeIn [components]; active scopes []): nothing under it is registered.
+Change the build's scopes so that the condition holds, or do not depend on it in this build
+```
+
+This needs the class to be loaded, for example by a file that imports it as a value. If nothing has
+loaded it, the error lists every registration that the module left out this way, since the class
+may be under any of them. `getComponent` does the same for the registrations of the module's component plugins.
+
+## Standing in for production code
+
+Two registrations may share an id if their conditions keep at most one of them in any one build.
+That is how a fake takes a real provider's place, in the same module as the real one, so everything
+that injects it gets the fake:
+
+```ts
+Flamework.createModule()
+	.registerClassProvider(CollectionHandler, { inactiveIn: ["collections"] })
+	.registerProvider<CollectionHandler>({ type: "class", value: FakeCollectionHandler, activeIn: ["collections"] })
+	.ignite();
+```
+
+With `collections` active, the fake is registered under the real one's id, and the real one is not.
+If both are kept in one build, ignition refuses it, as it does for any duplicate id.
+
+Use `inactiveIn` on its own for production code that a test replaces or must not run alongside: a
+real game loop, or a component whose tag a test rig reuses.
+
+## Where scopes are decided
+
+Every condition is checked against the scopes the build was compiled with. It is checked at
+ignition. A path or glob registration's own condition is also checked when the registration is
+made, so that a left-out folder is never loaded. Both checks give the same answer. After a change to
+`.env`, rebuild (restart the watcher if one is running) and, in Studio, stop and play again. There
+is no runtime override. The scopes a place runs with are part of the build, so a test scope cannot
+be switched on in a published game.
+
+## Caveats
+
+- **Conditions narrow, never widen.** A class cannot opt out of its module's or registration's
+  condition. Move it instead.
+- **A module's condition does not stop its plugins.** They are set up so that the module is
+  complete, and what they register is checked like everything else. To leave a plugin out, put the
+  condition on its inclusion.
+- **`*` turns every `inactiveIn` off.** Running every scope at once runs every replacement at once.
+  Two tests that replace the same thing collide, and ignition says so.
+- **Plugins with a registry of their own must ask.** The components plugin filters its classes with
+  `target.isActive(...)`. A plugin that keeps its own list of classes has to do the same, or its
+  classes ignore the module's condition. See [plugins](08-plugins.md#what-a-plugin-can-do).
+
+---
+
+Previous: [Migrating from v1](10-migrating-from-v1.md) · Next: [Testing in the place](12-testing.md)

package/docs/guide/12-testing.md

@@ -0,0 +1,342 @@
+# 12. Testing in the place
+
+`@flamework-experimental/testing` runs tests inside a real place: in Studio, in a live server, or
+in an Open Cloud task. Tests are plain functions grouped into **sections**. Providers define them,
+so they get their dependencies injected like any other code. They are tied to a
+[scope](11-scopes.md), so a build that did not ask for them does not register them.
+
+```ts
+// src/server/Tests/economy.ts
+import { OnStart, Provider } from "@flamework-experimental/core";
+import { defer, defineTests, expectEqual, test } from "@flamework-experimental/testing";
+import { Shop } from "server/services/shop";
+
+@Provider({ activeIn: ["testing"] })
+export class EconomyTests implements OnStart {
+    constructor(private readonly shop: Shop) {}
+
+    onStart() {
+        defineTests("economy", () => {
+            test("buying deducts the price", () => {
+                const wallet = this.shop.open("test");
+                defer(() => this.shop.close("test"));
+
+                this.shop.buy("test", "sword");
+                expectEqual(wallet.balance, 90);
+            });
+        });
+    }
+}
+```
+
+```ts
+// src/server/main.ts
+Flamework.createModule()
+    .registerProviders("src/server/services")
+    .registerProviders("src/server/Tests", { activeIn: ["testing"] })
+    .includePlugin(TestingPlugin)
+    .ignite();
+```
+
+```jsonc
+// flamework.config.json
+"scopes": { "active": "${FLAMEWORK_SCOPES:-}" }
+```
+
+In a build with `FLAMEWORK_SCOPES=testing` (the test script below sets it), the test providers
+register like any other and define their sections as they start. The plugin creates
+`Workspace.FlameworkTests` and waits. Nothing runs until something invokes it:
+
+```lua
+-- the Studio command bar, a debug UI, or `flamework-test` from a terminal
+local result = workspace.FlameworkTests:Invoke()          -- every section
+local result = workspace.FlameworkTests:Invoke("economy") -- one section
+```
+
+Without the scope, the `Tests` folders are skipped entirely. A folder registration whose own
+condition does not hold does not look the folder up or require anything in it. No test class is
+loaded or constructed, the plugin does nothing, and no instance is made. One switch,
+`FLAMEWORK_SCOPES`, turns on both the tests and the host that runs them. Keeping the files out of a
+release place altogether is Rojo's job; see [shipping](#shipping).
+
+## Setting up
+
+Everything a project needs, in the order it is needed:
+
+1. The package: `npm install @flamework-experimental/testing`. It brings the roblox-ts side and the
+   `flamework-test` CLI, nothing else. Map it in your Rojo project next to `core`
+   ([Getting started › Rojo](01-getting-started.md#rojo)). The CLI runs on
+   [Bun](https://bun.sh), whatever installed it: npm's and pnpm's `flamework-test` command starts
+   `bun`, and without it on the `PATH` fails with `'"bun"' is not recognized`.
+2. The switch: the `scopes` line above in `flamework.config.json`, and the scope in neither `.env`
+   nor `.env.local`. Every build reads both files: `.env` is committed
+   ([Project structure › What to commit](09-project-structure.md#what-to-commit)), and `.env.local`
+   is read by every build on your machine, release builds included. A scope in either ships the
+   test host and its remote with those builds. Set the variable for the one build that needs it
+   instead, as the test script below does.
+
+   To have the tests in a place you sync with `rojo serve`, give the watcher the scope in its own
+   environment, and nothing else: a `watch:tests` script like the test script, which runs
+   `rbxtsc -w` with `FLAMEWORK_SCOPES: "testing"`. Once you stop it, `out/` still holds the test
+   host, so compile once without the scope (`npm run build`) before you build a place to ship.
+3. A `Tests` folder per realm, registered under the scope, and `TestingPlugin` in each realm's
+   module. The server is shown above; the client is the same shape:
+
+   ```ts
+   // src/client/runtime.client.ts
+   Flamework.createModule()
+       .registerProviders("src/client/controllers")
+       .registerProviders("src/client/Tests", { activeIn: ["testing"] })
+       .registerProviders("src/shared/Tests", { activeIn: ["testing"] }) // sections both realms run
+       .includePlugin(TestingPlugin)
+       .ignite();
+   ```
+
+   A shared folder registered by both modules gives sections that run in both realms, one copy in
+   each. The component specs of this repository's test place,
+   [`tests/place`](https://github.com/Velover/ExperimentalFlameworkV2/blob/HEAD/tests/place/README.md), live in such a folder.
+4. A script that compiles with the scope, builds the place, runs the tests, and then compiles again
+   without the scope, whatever happened, so that `out/` never keeps a build with the test host in
+   it. The rebuild sets the variable to nothing rather than leaving it out, so that a scope in
+   `.env.local` cannot come back through it. It exits with the tests' code:
+
+   ```js
+   // scripts/test.mjs: run it as `npm test` or `bun run test`, which put node_modules/.bin on the
+   // PATH (`bun scripts/test.mjs` on its own finds no rbxtsc). Arguments go to flamework-test.
+   function run(command, env = process.env) {
+       try {
+           return Bun.spawnSync(command, { env, stdio: ["inherit", "inherit", "inherit"] }).exitCode ?? 1;
+       } catch {
+           console.error(`${command[0]} could not be started: is it installed?`);
+           return 127;
+       }
+   }
+
+   let code = run(["rbxtsc"], { ...process.env, FLAMEWORK_SCOPES: "testing" });
+   if (code === 0) code = run(["rojo", "build", "-o", "test.rbxl"]);
+   if (code === 0) code = run(["flamework-test", "test", "test.rbxl", ...process.argv.slice(2)]);
+
+   console.log("rebuilding out/ without the testing scope...");
+   const rebuild = run(["rbxtsc"], { ...process.env, FLAMEWORK_SCOPES: "" });
+   process.exit(code !== 0 ? code : rebuild);
+   ```
+
+   ```jsonc
+   // package.json
+   "scripts": { "test": "bun scripts/test.mjs" }
+   ```
+
+   `test.rbxl` has a name of its own, so the place a release is built into never holds the tests.
+   Ignore it with the other built places, `/*.rbxl` at the root. Besides the build, a run leaves:
+   - the places `flamework-test` makes beside the build (`test.patched.rbxl` with an original
+     place, `test.<project>.rbxl` under `--project`), which the same line covers;
+   - `build/version.json`, which `cloud publish` writes, and so `cloud test` and `test --cloud`;
+   - Studio's lock file beside a place it has open, `test.rbxl.lock`. `flamework-test` removes the
+     lock of a window it ends, but one left by a Studio closed any other way stays, so ignore
+     `*.rbxl.lock` too.
+
+   The files a patch needs while it runs go to a folder of the system's temp directory, one per
+   run, removed when the patch is done.
+5. Roblox Studio with "MCP server" enabled in its Assistant settings, which is what lets the CLI
+   open a window, run the tests in it and close it again.
+
+`npm test` (or `bun run test`) then prints one summary per realm. That is the whole setup for
+Studio. Running in the cloud also needs an API key and a testing place; see
+[Running the tests](https://github.com/Velover/ExperimentalFlameworkV2/blob/HEAD/docs/testing/place.md).
+
+## Where tests live
+
+`defineTests` is an ordinary function, so anything may call it. A provider's `onStart` is the
+natural place, since by then every provider is constructed and every `onInit` has run. Put the scope
+condition on the folder registration (`registerProviders("src/server/Tests", { activeIn: ["testing"] })`),
+on the class (`@Provider({ activeIn: ["testing"] })`), or on both. These are the usual
+[scope rules](11-scopes.md), nothing specific to testing.
+
+Only the condition on the folder registration keeps the folder from loading in a build without the
+scope. A release place that leaves the folder out needs that. A condition on the class is read after
+its file has loaded.
+
+Client tests have the same shape, in a client provider, with the plugin included in the client
+module. Each realm has its own host.
+
+## Sections and tests
+
+`defineTests(name, body)` runs `body` at once. Inside it, `test(name, fn)` registers a test, and
+`beforeEach` / `afterEach` register hooks. `name` may be `undefined`, which means the section
+`"default"`. The same section name used by several providers is one section, so a feature's tests
+can be spread over several files. Sections do not nest, and a name may not contain `/`.
+
+The body receives a context with the section's `name` and the `module` that was igniting when the
+section was defined:
+
+```ts
+defineTests("components", ({ module }) => {
+    test("finds the tagged part", () => {
+        const components = module!.resolveDependency<Components>();
+        // ...
+    });
+});
+```
+
+Define sections before the first yield of `onStart`. `onStart` runs on its own thread, and the
+module is only marked current until ignition finishes. A section defined after a `task.wait` still
+registers, but without a module. Few tests need the module: a provider already has what it
+injected.
+
+A test may yield (`task.wait`, `WaitForChild`, a signal), and a Promise it returns is awaited.
+Each test runs on its own thread, with a timeout of `testing.timeout` seconds (30 by default). A
+test that runs over is cancelled and counted as failed, and the run moves on.
+
+## Cleanup
+
+Tests in a place leave things behind unless they clean up, and the next test would run against
+whatever was left. There are three cleanup tools, and all of them run whether the test passed,
+failed or timed out:
+
+| Tool | Does |
+|---|---|
+| `defer(fn)` | Registers cleanup for the running test: a connection to disconnect, an instance to destroy, a state to restore. Runs in reverse order after the test. |
+| `scratch()` | A Folder in Workspace for whatever the test builds, made on first use and destroyed with everything in it afterwards. |
+| `afterEach(fn)` | A section-level hook, run after every test of the section. |
+
+A cleanup that raises fails the test, since whatever it was meant to remove is still there.
+
+## Assertions
+
+`expectEqual`, `expectTrue`, `expectFalse`, `expectDefined`, `expectThrows`, `expectNoThrow`,
+`expectArrayEqual`, `expectResolves`, `expectRejects` and `fail` raise a one-line message that
+becomes the test's failure. `eventually(predicate, what?, timeout?)` checks `predicate` every frame,
+for something the engine delivers later: a deferred signal, a replicated instance, a component built
+on the next resumption. Any other assertion library works too: a test fails when its body raises an
+error.
+
+## Running
+
+| From | How |
+|---|---|
+| A terminal, in Studio on this machine | `npm test`, the script in [Setting up](#setting-up): its `flamework-test test test.rbxl` opens the build in Studio, runs both realms, closes it; see [Running the tests](https://github.com/Velover/ExperimentalFlameworkV2/blob/HEAD/docs/testing/place.md) |
+| A terminal, under another Rojo project | `npm test -- --project tests/deferred.project.json`: the same, in a place with that project's `$properties` set, `Workspace.SignalBehavior` and the streaming radii included; one run per `--project`, see [Workspace settings no script can change](https://github.com/Velover/ExperimentalFlameworkV2/blob/HEAD/docs/testing/place.md#workspace-settings-no-script-can-change) |
+| A terminal, in the cloud | `npm test -- --cloud`: publishes to a testing place and runs the server's sections in a real server; needs `testing.entry`, see below |
+| The realm's own code | `Testing.run(filter?)` and `Testing.list(filter?)` |
+| Anything with the DataModel | `Workspace.FlameworkTests:Invoke(filter?, options?)` |
+| A client, for the server's tests | `Testing.runOnServer(filter?)`, over `Workspace.FlameworkTestsServer` |
+| Start-up | `"autoRun": true` in the config runs everything right after ignition |
+
+A filter is nothing (every section), one section name, one `section/test` name, or a list of
+those; `--sections a,b` on the command line. Passing `{ list = true }` as the options reports the
+selection without running it. In one realm, an entry that names nothing there makes the run fail.
+When `flamework-test` runs both realms, an entry only one realm has is fine: the other realm lists it
+as `not among the client's sections: coin`, and the run fails only on an entry that no realm has
+(`MISS matched nothing in any realm: coins`). So `--sections coin` runs a server-only section without
+`--realm server`. The result is a plain table, the same whether it came back from an invoke, a
+remote or `Testing.run`:
+
+```lua
+{ ok = true, realm = "server", passed = 12, failed = 0, durationMs = 340,
+  sections = { { name = "economy", passed = 12, failed = 0,
+                 tests = { { name = "buying deducts the price", ok = true, durationMs = 3 }, ... } } },
+  unknown = {} }  -- filter entries that named nothing in this realm; any makes ok false
+```
+
+Every test also prints one line, such as
+`[FWTEST] server economy/buying deducts the price: PASS (3ms)`, and the run ends with a summary
+line. So the Output window and a task's log show the same as the table.
+
+A place made by `flamework-test` knows which Rojo project it was made under. `getProject()` returns
+that project's name: `deferred` for `tests/deferred.project.json`, and `undefined` in a place opened
+by hand. The result carries it as `project`. A test that only holds under one project's `Workspace`
+settings (`SignalBehavior`, say) checks it and returns early under the others; see
+[several projects, one suite](https://github.com/Velover/ExperimentalFlameworkV2/blob/HEAD/docs/testing/place.md#several-projects-one-suite).
+
+A BindableFunction's callback is set per realm, so the one `Workspace.FlameworkTests` serves both.
+A client with the plugin answers on it for its own tests, and reaches the server's tests through
+`FlameworkTestsServer`. A second invoke while a run is in progress raises an error.
+
+### Both realms in one session
+
+`flamework-test test` runs the server's sections and then the client's, in the same play session.
+So the client's tests run against a server whose own tests have already run, and they see whatever
+those tests left on the wire.
+
+One engine fact matters here. A RemoteEvent message fired at a client before it has connected
+`OnClientEvent` is not dropped: the engine queues it and delivers it the first time anything
+connects. Say a server test calls `predict` with the real player, through a handler that answers
+with `fire(player, ...)`. That leaves a reply waiting, and the reply lands in the middle of the
+client's tests as an answer nobody asked for.
+
+So predict with a stand-in that is not a `Player` (`scratch()` will do), and have the answering
+handler skip it:
+
+```ts
+function fromPlayer(player: Player) {
+    return typeIs(player, "Instance") && player.IsA("Player");
+}
+server.setScore.connect((player, score) => {
+    if (fromPlayer(player)) server.scoreChanged.fire(player, score);
+});
+
+test("accepts a message through its guards", () => {
+    server.setScore.predict(scratch() as unknown as Player, 5);
+});
+```
+
+The `networking` sections of this repository's test place ([`tests/place`](https://github.com/Velover/ExperimentalFlameworkV2/blob/HEAD/tests/place/README.md))
+are written this way.
+
+## Configuration
+
+```jsonc
+"testing": {
+  "activeIn": ["testing"],     // scopes under which the plugin attaches: any of them; the default
+  "inactiveIn": [],            // scopes under which it never does
+  "enabled": true,             // when set, overrides the two above in either direction
+  "autoRun": false,            // run everything right after ignition
+  "timeout": 30,               // seconds per test
+  "entry": "src/server/main"   // cloud runs only: the ModuleScript exporting ignite()
+}
+```
+
+`entry` exists for one reason. An Open Cloud task loads the place but runs none of its Scripts, so
+nothing ignites the game there. The runner has to require a ModuleScript and call its `ignite()`
+itself, and `entry` names that ModuleScript. In Studio, the place runs its own Scripts, and the
+module is up before anything invokes the tests. So a project that only runs its tests locally never
+sets `entry`. A cloud command refuses to publish without it.
+
+`activeIn` and `inactiveIn` follow the same rules as everywhere else: `activeIn` needs at least one
+of its names active, `inactiveIn` needs none of its names active, and an empty `activeIn` is no
+constraint. `TestingPlugin` is the plugin with the file's settings. `createTestingPlugin({ ... })`
+overrides them for one plugin, which is what a test harness of your own would use.
+
+## Shipping
+
+Never ship a build with tests on: the remote lets any client run the server's tests. Keep the
+`testing` scope out of `.env` and `.env.local` altogether, since every build reads them; the test
+script in [Setting up](#setting-up) sets the scope for its own build and compiles again with it set
+to nothing afterwards, so `out/` is never left with the host in it. After a watcher that ran with
+the scope, compile once without it before you build a place to ship.
+
+Without the scope, the test files still compile and are still copied into the place. A `Tests`
+folder registered under the scope is never loaded, though. To leave the files out of the place as
+well, give the release build a Rojo project that ignores the folders:
+
+```jsonc
+// release.project.json, otherwise identical to default.project.json
+"globIgnorePaths": ["**/package.json", "**/tsconfig.json", "**/Tests"]
+```
+
+`**/Tests` drops every folder with that name, at any depth (`**/Tests/**` would leave empty folders
+behind).
+
+Register such a folder by its own path only with the scope condition on the registration itself, as
+in [Setting up](#setting-up): `registerProviders("src/server/Tests", { activeIn: ["testing"] })`.
+The release build does not have the scope, so the folder is never looked up. Without that
+condition on the registration, the folder is looked up in every build that runs it. That includes
+`registerProviders("src/server/Tests")` with the condition only on the classes, and
+`ComponentPlugin.fromPath` with the condition only on `includePlugin`. The transformer resolves the
+path against the project file without regard to `globIgnorePaths`, so a registered folder that is
+not in the place stalls ignition: the registration waits for it, and warns after five seconds that
+it is `still waiting for its folder`.
+
+---
+
+Previous: [Scopes](11-scopes.md) · See also: [Running the tests](https://github.com/Velover/ExperimentalFlameworkV2/blob/HEAD/docs/testing/place.md), [Testing in Studio](https://github.com/Velover/ExperimentalFlameworkV2/blob/HEAD/docs/testing/studio.md)

package/flamework.build

@@ -1,6 +1,6 @@
 {
 	"version": 1,
-	"flameworkVersion": "2.0.0-alpha.4",
+	"flameworkVersion": "2.0.0-alpha.5",
 	"identifiers": {
 		"@flamework-experimental/core:out/module/module@Module": "$:module/module@Module",
 		"@flamework-experimental/core:out/lifecycle/lifecyclePlugin@LifecycleProvider": "$:lifecycle/lifecyclePlugin@LifecycleProvider",

package/out/index.d.ts

@@ -4,6 +4,7 @@ export { Reflect } from "./reflect";
 export { Provider } from "./provider";
 export { Injectable } from "./injectable";
 export { Dependency } from "./dependency";
+export { requireModules } from "./utility/getClassesInPath";
 export { Serialization } from "./serialization/types";
 export type { ProviderDecoratorConfig } from "./provider";
 export type { InjectableDecoratorConfig } from "./injectable";

package/out/init.luau

@@ -7,6 +7,7 @@ exports.Reflect = TS.import(script, script, "reflect").Reflect
 exports.Provider = TS.import(script, script, "provider").Provider
 exports.Injectable = TS.import(script, script, "injectable").Injectable
 exports.Dependency = TS.import(script, script, "dependency").Dependency
+exports.requireModules = TS.import(script, script, "utility", "getClassesInPath").requireModules
 -- Modules
 exports.ModuleDefinition = TS.import(script, script, "module", "moduleDefinition").ModuleDefinition
 exports.ModuleBuilder = TS.import(script, script, "module", "moduleBuilder").ModuleBuilder

package/out/module/module.luau

@@ -1005,7 +1005,7 @@ local function createModuleInstantiation(state, options)
 			local _arg0 = resolved ~= nil
 			assert(_arg0)
 			if holdsCondition(registrationOptions) then
-				registerProviderClasses(getClassesInPath(resolved), registrationOptions)
+				registerProviderClasses(getClassesInPath(resolved, `registerProviders("{path}")`), registrationOptions)
 			else
 				local _arg0_1 = leftOutRegistration(`registerProviders("{path}")`, registrationOptions, {
 					path = resolved,

package/out/module/moduleBuilder.luau

@@ -121,7 +121,7 @@ do
 			table.insert(_leftOut, _arg0)
 			return self
 		end
-		return self:registerProviderClasses(getClassesInPath(path), options)
+		return self:registerProviderClasses(getClassesInPath(path, `registerProviders("{_stringPath}")`), options)
 	end
 	function ModuleBuilder:registerProvidersGlob(_glob, options, glob)
 		local _arg0 = glob ~= nil

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.
@@ -13,6 +14,28 @@ export declare function importModule(moduleScript: ModuleScript): defined | unde
  * `resolveRbxPath` finds.
  */
 export declare function requireModulesInPath(rbxPath: readonly string[]): Array<defined>;
+/**
+ * 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
@@ -27,5 +50,8 @@ export declare function requireModulesInPath(rbxPath: readonly string[]): Array<
  *
  * 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>;