@flamework-experimental/transformer 2.0.0-alpha.0

package/README.md

@@ -0,0 +1,66 @@
+# Flamework
+
+Flamework is an extensible framework for roblox-ts designed around portable, isolated and testable modules.
+
+## Documentation
+
+**[docs/](docs/README.md)** -- start there. A ten-part guide that builds up from a working entry
+point to plugins and project layout, plus reference material:
+
+| | |
+|---|---|
+| [Guide](docs/README.md#guide) | Getting started, modules, providers, lifecycle events, components, networking, macros, plugins, project structure, migrating from v1. |
+| [Internals](docs/reference/internals.md) | What the transformer does to your code and what the runtime does with the result. |
+| [Transformer plugins](docs/reference/transformer-plugins.md) | Adding macro types of your own. |
+
+The Flamework website documents v1, most of which no longer applies:
+
+https://flamework.fireboltofdeath.dev/docs/introduction
+
+## Development
+
+This repository is a [Bun](https://bun.sh) workspace. It also needs
+[Lune](https://lune-org.github.io/docs) on `PATH` to run the runtime specs.
+
+```sh
+bun install
+bun run build          # builds every package in dependency order
+bun run test           # build + transformer tests + runtime specs
+bun run lint
+```
+
+### Packages
+
+| Package | Description |
+|---|---|
+| `packages/core` | Modules, dependency injection, plugins and lifecycle events |
+| `packages/components` | CollectionService components, built on the core plugin system |
+| `packages/networking` | Remote events and functions |
+| `packages/testing` | In-place tests: sections, cleanup, a bindable and a remote to run them, a cloud entry; and `flamework-test`, the CLI that runs them in Roblox Studio on this machine or through Open Cloud (`cli/`) |
+| `packages/transformer` | The roblox-ts transformer |
+| `packages/transformer-plugin` | Public API for writing transformer plugins |
+| `packages/specs` | Runtime specs, compiled by `rbxtsc` and executed under Lune |
+
+### Tests
+
+Two suites, both run by `bun run test`:
+
+- **Transformer tests** (`bun run test:unit`) compile a fixture project with the real `rbxtsc` and
+  assert on the emitted Luau — guard generation, identifiers, nested macros and the plugin system.
+- **Runtime specs** (`bun run test:runtime`) execute compiled `@flamework-experimental/core`, `components` and
+  `networking` under Lune using the harness in [`tests/runtime`](tests/runtime), which models
+  roblox-ts's `TS.import` tree over the filesystem and stubs the Roblox API surface Flamework
+  touches (Instances, attributes, CollectionService, RemoteEvents, Players, signals, `task`,
+  `Enum`, and a `Heartbeat` pump so `Promise.delay` -- and therefore request timeouts -- runs).
+  They cover dependency injection, modules, hooks and the per-frame lifecycle events, component
+  construction, dependencies and streaming, and both halves of networking: events, functions,
+  middleware and the generated guards.
+
+  They run twice, once as `Server` and once as `Client`, because realm-dependent code paths --
+  `@Provider`'s metadata, component streaming, and the client/server halves of networking -- differ
+  between them. Where a spec asserts something realm-specific, running it from both sides is what
+  proves the two agree: a function receives on `$name` and sends on `@name` from the server and the
+  mirror image from the client, so the pair of runs pins the wire format down from both ends.
+
+Specs live in [`packages/specs`](packages/specs) and are compiled by `rbxtsc` like any other
+Flamework consumer, so they exercise the transformer and the runtime together.

package/flamework-schema.json

@@ -0,0 +1,76 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "#root",
+	"type": "object",
+	"properties": {
+		"globs": {
+			"$id": "globs",
+			"type": "object",
+			"properties": {
+				"paths": {
+					"type": "object",
+					"additionalProperties": {
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					}
+				},
+				"origins": {
+					"type": "object",
+					"additionalProperties": {
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					}
+				}
+			}
+		},
+		"buildInfo": {
+			"$id": "buildInfo",
+			"required": ["version", "flameworkVersion", "identifiers"],
+			"type": "object",
+			"properties": {
+				"version": {
+					"type": "number"
+				},
+				"flameworkVersion": {
+					"type": "string"
+				},
+				"identifierPrefix": {
+					"type": "string"
+				},
+				"idGenerationMode": {
+					"type": "string"
+				},
+				"buildSeed": {
+					"type": "string"
+				},
+				"identifiers": {
+					"type": "object",
+					"additionalProperties": {
+						"type": "string"
+					}
+				},
+				"salt": {
+					"type": "string"
+				},
+				"stringHashes": {
+					"type": "object",
+					"additionalProperties": {
+						"type": "string"
+					}
+				},
+				"metadata": {
+					"type": "object",
+					"properties": {
+						"globs": {
+							"$ref": "globs"
+						}
+					}
+				}
+			}
+		}
+	}
+}

package/flamework.config.schema.json

@@ -0,0 +1,197 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "flamework.config.schema.json",
+	"title": "Flamework project configuration",
+	"description": "One file for every Flamework package, read from flamework.config.json next to (or above) your tsconfig.json. The transformer section can also be written inline on the transformer entry in tsconfig.json, where it overrides the file; the other sections are compiled into include/flamework/config.json for the runtime packages. Any string may reference the environment as ${NAME} or ${NAME:-fallback} ($$ for a literal dollar), read from .env and .env.local next to this file with the process environment on top; a string where a boolean, number or list is expected is converted.",
+	"type": "object",
+	"additionalProperties": false,
+	"properties": {
+		"$schema": {
+			"type": "string",
+			"description": "Editor support: point this at node_modules/@flamework-experimental/transformer/flamework.config.schema.json."
+		},
+		"transformer": {
+			"type": "object",
+			"additionalProperties": false,
+			"description": "Options for @flamework-experimental/transformer.",
+			"properties": {
+				"plugins": {
+					"type": "array",
+					"description": "Transformer plugins to load. Each entry is a module specifier or a path relative to the package root, optionally with options passed to the plugin as `api.options`.",
+					"items": {
+						"oneOf": [
+							{ "type": "string" },
+							{
+								"type": "object",
+								"additionalProperties": false,
+								"required": ["path"],
+								"properties": {
+									"path": { "type": "string" },
+									"options": { "type": "object" }
+								}
+							}
+						]
+					}
+				},
+				"noSemanticDiagnostics": {
+					"type": "boolean",
+					"description": "Skips TypeScript's semantic diagnostics. Faster, but type errors no longer stop the build and diagnostic spans may be wrong.",
+					"default": false
+				},
+				"salt": {
+					"type": "string",
+					"description": "Salt for generated hashes. Defaults to a random 64-byte salt stored in flamework.build."
+				},
+				"hashPrefix": {
+					"type": "string",
+					"description": "Prefix for generated ids. Defaults to the package name; set a short one in a game to keep ids compact and distinct from any package's."
+				},
+				"obfuscation": {
+					"type": "boolean",
+					"description": "Obfuscates identifiers: randomises remote names, shuffles metadata and shortens ids. Game projects only.",
+					"default": false
+				},
+				"idGenerationMode": {
+					"type": "string",
+					"enum": ["full", "short", "tiny", "obfuscated"],
+					"description": "How identifiers are generated. Only shorten in a game; a published package must stay on \"full\" so its ids do not collide with its consumers'.",
+					"default": "full"
+				},
+				"optimizations": {
+					"type": "object",
+					"additionalProperties": false,
+					"description": "Experimental output optimisations.",
+					"properties": {
+						"guardGenerationDedupLimit": {
+							"type": "integer",
+							"minimum": 1,
+							"description": "Object and union types that occur at least this many times inside one generated guard are emitted once as a local and referenced."
+						}
+					}
+				}
+			}
+		},
+		"core": {
+			"type": "object",
+			"additionalProperties": false,
+			"description": "Options for @flamework-experimental/core.",
+			"properties": {
+				"profiling": {
+					"type": "boolean",
+					"description": "Wraps every lifecycle event in debug.profilebegin so providers show up in the MicroProfiler. Defaults to true in Studio and false elsewhere; createLifecyclePlugin({ profiling }) overrides it per module."
+				}
+			}
+		},
+		"networking": {
+			"type": "object",
+			"additionalProperties": false,
+			"description": "Options for @flamework-experimental/networking.",
+			"properties": {
+				"serialization": {
+					"type": "boolean",
+					"description": "Serialises every event and function payload into a buffer, with encode and decode code generated from the event's parameter types at each createServer/createClient call site. Values that cannot live in a buffer (Instances, unknown) travel alongside it.",
+					"default": false
+				}
+			}
+		},
+		"components": {
+			"type": "object",
+			"additionalProperties": false,
+			"description": "Options for @flamework-experimental/components.",
+			"properties": {
+				"warningTimeout": {
+					"type": "number",
+					"minimum": 0,
+					"description": "Seconds before a component that never qualifies produces a warning; 0 disables it. Components that set their own warningTimeout keep it.",
+					"default": 5
+				},
+				"attributeWarningTimeout": {
+					"type": "number",
+					"minimum": 0,
+					"description": "Seconds before an instance-valued attribute that has not streamed in produces a warning; 0 disables it. Defaults to warningTimeout.",
+					"default": 5
+				},
+				"streamingMode": {
+					"type": "string",
+					"enum": ["Disabled", "Watching", "Contextual"],
+					"description": "Default ComponentStreamingMode for components that do not set one.",
+					"default": "Contextual"
+				}
+			}
+		},
+		"scopes": {
+			"type": "object",
+			"additionalProperties": false,
+			"description": "Build scopes: which scoped modules, registrations, providers and components are active in this build. Usually driven by the environment, as \"active\": \"${FLAMEWORK_SCOPES:-}\".",
+			"properties": {
+				"active": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "The active scopes. A string from the environment is split on commas; \"*\" activates every scope and an empty list activates none.",
+					"default": []
+				}
+			}
+		},
+		"testing": {
+			"type": "object",
+			"additionalProperties": false,
+			"description": "Options for @flamework-experimental/testing. Tests are on when the \"testing\" scope is active (scopes.active, usually FLAMEWORK_SCOPES in .env), so a release build carries none; \"activeIn\" renames that scope and \"enabled\" overrides it.",
+			"properties": {
+				"enabled": {
+					"type": "boolean",
+					"description": "Whether the plugin attaches the host at all: Workspace.FlameworkTests (a BindableFunction) and Workspace.FlameworkTestsServer (a RemoteFunction). Unset, it follows activeIn and inactiveIn, so this is an override for either direction."
+				},
+				"activeIn": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Scopes under which tests are on: the host attaches when at least one is active, the way activeIn works everywhere else (an empty list is no constraint). A string from the environment is split on commas.",
+					"default": ["testing"]
+				},
+				"inactiveIn": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Scopes under which tests stay off, whatever else is active. A string from the environment is split on commas.",
+					"default": []
+				},
+				"autoRun": {
+					"type": "boolean",
+					"description": "Runs every test right after the module ignites, printing the results. Otherwise tests only run when the bindable or remote is invoked.",
+					"default": false
+				},
+				"timeout": {
+					"type": "number",
+					"minimum": 0,
+					"description": "Seconds a single test may take before it is cancelled and counted as failed.",
+					"default": 30
+				},
+				"entry": {
+					"type": "string",
+					"description": "Cloud runs only. The source path of a ModuleScript exporting `ignite()`, for example \"src/server/main\": an Open Cloud Luau execution task runs none of the place's Scripts, so the runner requires this module and ignites the game itself before invoking the bindable. Studio runs need none, the place runs itself. Compiled into the artifact as a tree path."
+				}
+			}
+		},
+		"cloud": {
+			"type": "object",
+			"additionalProperties": false,
+			"description": "Where the flamework-test CLI (@flamework-experimental/testing) publishes the build and runs its tests: a testing place, never the original. Read by that CLI only; never compiled into the place. Keep the key in the environment: \"apiKey\": \"${ROBLOX_API_KEY:-}\".",
+			"properties": {
+				"testingUniverseId": {
+					"type": "string",
+					"description": "The testing experience's universe id, from the Creator Dashboard URL (game.GameId in Studio)."
+				},
+				"testingPlaceId": {
+					"type": "string",
+					"description": "The place to publish to, run tests in, and open in Studio. Never the original place."
+				},
+				"apiKey": {
+					"type": "string",
+					"description": "An Open Cloud API key with universe-places:write and universe.place.luau-execution-session:read and :write for the testing experience. Reference the environment, \"${ROBLOX_API_KEY:-}\", so the key is never in the file."
+				},
+				"originalPlace": {
+					"type": "string",
+					"description": "A copy of the original place (File > Save to File in Studio), relative to this file. When set, the CLI lays the Rojo build over a copy of it before publishing, following the project file, so the tests see assets that exist only in the original. Needs lune."
+				}
+			}
+		}
+	}
+}