cluaupp 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## Unreleased
+
+## 0.2.0
+
+- CLI rewritten as a TypeScript collector-emitter pipeline: Tree-sitter collection, Rojo-mapped `require`s, ordered Luau blocks (Services → Requires → Types → Constants → Code), then optional StyLua / `luau-analyze`. Commands `init`, `build`, `watch`, `lsp`, and `intellisense` stay. `cluaupp build -i file.cpp -o out.luau --rojo default.project.json` is the single-file path.
+- C++ IntelliSense is **clangd** only. The old tokenizer/`completeAt` engine is gone. Tree-sitter is the compiler frontend. `cluaupp lsp` publishes subset parse errors only.
+- `SystemUnderstander` scans identifiers, scores Roblox intents, and stamps Controller / Manager / utility plus `GetService` injections. Filename tags still decide Script vs LocalScript vs ModuleScript.
+- Sample game C++ lives in `examples/game/` (`src/server`, `src/client`, `src/shared`). Compiler `src/` is TypeScript only.
+- CLI security: StyLua / luau-analyze via `spawn` without a shell; emitted paths cannot leave the project; `.env*` stays out of git and the npm pack.
+- Docs / GitHub Pages: clangd, SystemUnderstander, one-file-out emit, `examples/game`. Rojo **7.7.0**.
+- Tests cover `out/` tree, types, modules, path safety, and understander roles.
+
 ## 0.1.5
 
 - Default emit is one tagged `.cpp` → one `.server.luau` / `.client.luau`. `"architecture": true` keeps the old ForeverHD service folders.

package/README.md

@@ -42,7 +42,7 @@ players.PlayerAdded:Connect(CreateLeaderstats)
 
 ## Install
 
-Node.js 18+ and [Rojo](https://rojo.space/) for Studio sync.
+Node.js 18+ and [Rojo](https://rojo.space/) **7.7.0** for Studio sync (`rokit.toml` in the game template).
 
 ```bash
 npm install -g cluaupp
@@ -59,12 +59,15 @@ npx cluaupp init my-game
 ```bash
 cluaupp init my-game
 cd my-game
+rokit install
 cluaupp build
 rojo serve
 ```
 
 Connect the Rojo plugin in Roblox Studio. Edit `src/**/*.{cpp,h,hpp}`, run `cluaupp watch` to rebuild on save.
 
+C++ autocomplete is **clangd**, not a Cluaupp tokenizer and not Microsoft cpptools. Put `#include <cluaupp/roblox.hpp>` at the top of each script; `cluaupp init` writes `.clangd` / `compile_flags.txt` / `compile_commands.json` with `-Iinclude` so clangd finds that header. Tree-sitter is only used to compile. See [IntelliSense](docs/intellisense.md).
+
 ```
 src/server/*.server.cpp  →  out/server/*.server.luau  Script
 src/client/*.client.cpp  →  out/client/*.client.luau  LocalScript
@@ -73,6 +76,8 @@ src/shared/*.cpp         →  out/shared/*.luau         ModuleScript
 
 Filename tags: `.server.cpp`, `.client.cpp`, `.legacy.server.cpp`, `.legacy.client.cpp`, or no tag (ModuleScript). One source file becomes one instance. Set `"architecture": true` only for the old PascalCase folder split. See [Architecture](docs/architecture.md) and [OOP structure](docs/oop/index.md).
 
+Compiler TypeScript lives in `src/`. Sample game C++ is [`examples/game`](examples/game) (`src/server`, `src/client`, `src/shared`). `cluaupp init` still copies [`templates/game`](templates/game).
+
 ## Documentation
 
 | Guide | What it covers |

package/bin/cluau.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 "use strict";
 
-require("../src/cli.js");
+require("../generated/cli.js");

package/bin/cluaupp.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 "use strict";
 
-require("../src/cli.js");
+require("../generated/cli.js");

package/docs/architecture.md

@@ -20,6 +20,31 @@ roblox-ts decides **what instance you get** from a filename **key** (the same id
 
 The ForeverHD-style folder split (`LeaderStats/Main.luau`, …) is **opt-in**: `"architecture": true`.
 
+## SystemUnderstander
+
+Like [roblox-ts](https://github.com/roblox-ts/roblox-ts) (filename **key** first) and [roblox-cs](https://github.com/roblox-csharp/roblox-cs) (scan the AST, then decide), Cluaupp does **not** call a generative model. `src/system-understander.ts` walks the Tree-sitter tree, scores token density against Roblox engine services, and returns a report the emitter may stamp as comments / extra `GetService` lines.
+
+| Step | What happens |
+| --- | --- |
+| `parseFileTag` | `.server.cpp` → Script / Server, `.client.cpp` → LocalScript / Client, no tag → ModuleScript |
+| `namesIn` | identifiers, `GetService<T>`, `new Class`, string literals |
+| `scoreIntents` | evidence count × side weight (server tokens count more on `.server.cpp`) |
+| `determineArchitecture` | score &lt; 2 → utility Module; otherwise Knit-style Controller / Manager / Service. `players` / `cache` stay supporting if combat, UI, or net already has ≥ 2 tokens |
+
+The **Rojo class never changes** because of a role. A HUD LocalScript can be classified as `ViewController` and still emit `hud.client.luau`. Sample sources: [examples/game](../examples/game).
+
+## Compiler pipeline
+
+Cluaupp does not rewrite C++ as text. The CLI parses a Tree-sitter CST, collects symbols (`GetService<T>()`, `#include`, types, constants), then emits Luau in a fixed order:
+
+1. `game:GetService(...)`
+2. `require(...)` (Rojo `default.project.json` when present)
+3. types
+4. constants
+5. functions / script body
+
+Formatting is delegated to StyLua; type sanity to `luau-analyze`. See [CLI](cli.md).
+
 ## File tags
 
 | Source | Meaning | Output |
@@ -42,7 +67,7 @@ Scripts and LocalScripts keep your functions and call `init()` at the end. Modul
 
 ## Opt-in: ForeverHD folders (`"architecture": true`)
 
-Set `"architecture": true` in `cluaupp.config.json` to restore the old planner: PascalCase service folders, `Main` / Managers / Controllers / Types, and `require(script.Main):Start()`.
+Set `"architecture": true` in `cluaupp.config.json` to restore the old planner: PascalCase service folders, `Main` / Managers / Controllers / Types, and `require(script.Main):Start()`. Server folders emit `init.server.luau` plus a **pure JSON** `init.meta.json` with only `RunContext.Server` — never `className`, and never library `require` lines (Rojo 7.7 rejects both).
 
 ```
 filename key  →  server | client | module | legacy

package/docs/cli.md

@@ -6,6 +6,8 @@ cluaupp <command> [folder]
 
 If `[folder]` is omitted, the current directory is used.
 
+The compiler is a **collector-emitter** pipeline: Tree-sitter walks the C++ CST, Rojo maps `#include` to `require`, Luau is emitted in a fixed block order (Services → Requires → Types → Constants → Code), then StyLua / `luau-analyze` can run as post-process.
+
 ## `cluaupp init [folder]`
 
 Creates a game from the template:
@@ -13,8 +15,9 @@ Creates a game from the template:
 - `src/server`, `src/client`, `src/shared`
 - `cluaupp.config.json`
 - `default.project.json` (Rojo)
+- `rokit.toml` (Rojo 7.7.0)
 - `include/cluaupp/roblox.hpp` (IntelliSense)
-- `.vscode/c_cpp_properties.json`
+- `.vscode/` (clangd)
 
 ```bash
 cluaupp init .
@@ -25,8 +28,8 @@ cluaupp init my-game
 
 Transpiles `src/**/*.{cpp,h,hpp}` into `out/`. One tagged `.cpp` becomes one Luau instance (`leaderstats.server.luau`, `hud.client.luau`). Shared untagged files become ModuleScripts. Set `"architecture": true` for the old PascalCase service folders.
 
-- `--!strict` only with `#pragma strict` or `"strict": true`
-- `#include "file.h"` becomes `require(ReplicatedStorage.Cluaupp...)` / `require(ServerScriptService.Cluaupp...)` for shared/server modules
+- `--!strict` only with `#pragma strict`, `"strict": true`, or `--strict` on the single-file path
+- `#include "file.h"` becomes `require(...)` resolved from `default.project.json` when present
 - `#include <cluaupp/roblox.hpp>` is ignored
 - `.h` / `.hpp` emit a type ModuleScript (`export type` + typed table). A sibling `.cpp` becomes `*Impl.luau` (the construction); the header binds those functions.
 - A parse error exits with code 1 and `file:line:column`
@@ -36,12 +39,29 @@ Transpiles `src/**/*.{cpp,h,hpp}` into `out/`. One tagged `.cpp` becomes one Lua
 ```bash
 cluaupp build
 cluaupp build ./my-game
+cluaupp build --format --analyze
+```
+
+### Single file
+
+```bash
+cluaupp build --input ./src/server/boot.server.cpp --output ./out/boot.server.luau --rojo ./default.project.json
 ```
 
+`--format` runs StyLua; `--analyze` runs `luau-analyze`. On the single-file path both run by default (warnings if the binaries are missing). On a project build they are opt-in.
+
 ## `cluaupp watch [folder]`
 
 Runs a compile (without copying `libs/`) and rebuilds when anything under `src/` changes, including deletes. Parse errors are printed; the watcher stays alive and **does not write `out/`** until the project compiles cleanly (Studio keeps the last good scripts). A second watcher in the same game exits. Deleted `.cpp` files prune their `out/` artifacts on the next successful compile.
 
+## `cluaupp lsp [folder]`
+
+Stdio JSON-RPC for **Cluaupp subset diagnostics** only. Completion, hover, and definitions are clangd.
+
+## `cluaupp intellisense [folder]`
+
+Writes `compile_commands.json`, `.clangd`, and `.vscode` for clangd, and installs LLVM clangd when needed.
+
 ## `cluaupp --version` / `cluaupp -v`
 
 Prints the npm package version.
@@ -64,7 +84,8 @@ Shows usage.
 In the Cluaupp development repo:
 
 ```bash
-npm run build    # cluaupp build game
-npm run dev      # watch + Rojo
-npm run stop     # stop Rojo
+npm run build:cli   # compile the TypeScript CLI
+npm test
+npm run dev         # local gitignored playground in game/ + Rojo
+npm run stop        # stop Rojo
 ```

package/docs/examples/index.md

@@ -7,6 +7,8 @@ sidebar_position: 1
 
 High-quality Cluaupp systems you can copy. Each page is a full service: C++ that the subset actually compiles, server authority, Janitor cleanup, and the file names Studio expects.
 
+In this repo the live sample is [`examples/game`](../../examples/game) (`src/server`, `src/client`, `src/shared`). Compiler TypeScript is never mixed with game C++. `cluaupp init` still copies [`templates/game`](../../templates/game).
+
 These are **not** dumps of `int main()`. Entry is `void init()`. There are no lambdas and no custom C++ classes — named functions + structs.
 
 ## Suggested layout

package/docs/getting-started.md

@@ -5,8 +5,8 @@ Cluaupp installs from **npm**, the same channel as roblox-ts and most Roblox too
 ## Requirements
 
 - [Node.js](https://nodejs.org/) 18 or newer
-- [Rojo](https://rojo.space/) to sync `out/` into Studio
-- An editor with C++ IntelliSense (Cursor / VS Code + the C/C++ extension)
+- [Rojo](https://rojo.space/) **7.7.0** to sync `out/` into Studio (`cluaupp init` writes `rokit.toml`; run `rokit install`)
+- LLVM clangd for C++ IntelliSense (Cursor / VS Code — installed by `cluaupp init`)
 
 ## Install the compiler
 
@@ -43,6 +43,7 @@ npm install --save-dev cluaupp
 ```bash
 cluaupp init my-game
 cd my-game
+rokit install
 cluaupp build
 rojo serve
 ```
@@ -123,13 +124,13 @@ If a file defines `void init()`, Cluaupp calls `init()` at the end of the `.luau
 
 ## IntelliSense
 
-`cluaupp init` writes the C++ IntelliSense config and installs Microsoft `ms-vscode.cpptools` (via VSIX on Cursor). Then reload the window.
+`cluaupp init` writes clangd config and installs LLVM `clang++` plus the clangd editor extension when missing. Then reload the window. Completion is clangd; Cluaupp does not index C++ itself.
 
 ```bash
 cluaupp intellisense
 ```
 
-`#include <cluaupp/roblox.hpp>` at the top of each source file. The header is **not** compiled to Luau.
+`#include <cluaupp/roblox.hpp>` at the top of each source file. The header is **not** compiled to Luau. clangd learns that path from `-Iinclude` in `.clangd`, `compile_flags.txt`, and `compile_commands.json` — it does not read `c_cpp_properties.json`.
 
 See [IntelliSense](intellisense.md).
 

package/docs/intellisense.md

@@ -1,31 +1,49 @@
-# IntelliSense
-
-`cluaupp init` and `cluaupp intellisense` install the same setup that works in Cursor:
-
-1. Microsoft [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) (`ms-vscode.cpptools`)
-2. `.vscode/c_cpp_properties.json` — LLVM `clang++`, C++20, `include/` + `src/`, `compile_commands.json`
-3. Forced include of `include/cluaupp/roblox.hpp` so `GetService`, `Player`, `Janitor` complete
-4. The Cluaupp completion engine (Roblox APIs + your `struct`s)
-
-Cursor’s marketplace does not list `ms-vscode.cpptools`. Cluaupp downloads the official VSIX from [vscode-cpptools releases](https://github.com/microsoft/vscode-cpptools/releases) and runs `cursor --install-extension`.
-
-## Install
-
-```bash
-cluaupp intellisense
-```
-
-Reload: Command Palette → **Developer: Reload Window**. Status bar `{} C++` should read **IntelliSense: Ready**.
-
-`cluaupp build` / `watch` only refresh `compile_commands.json` (no download). They never keep deleted files in the compilation database.
-
-## Config that ships
-
-| File | Role |
-| --- | --- |
-| `.vscode/c_cpp_properties.json` | compiler path, include path, `compileCommands` |
-| `.vscode/settings.json` | `C_Cpp.intelliSenseEngine: default`, `clangd.enable: false` |
-| `.vscode/extensions.json` | recommends `ms-vscode.cpptools` |
-| `compile_commands.json` | one entry per `src/` file |
-
-`#include <cluaupp/roblox.hpp>` at the top of each source file. The header is not compiled to Luau.
+# IntelliSense
+
+C++ completion, hover, and go-to-definition are **clangd**. Cluaupp does not ship a second completion engine.
+
+`cluaupp init` / `cluaupp intellisense` install:
+
+1. [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) (`llvm-vs-code-extensions.vscode-clangd`)
+2. LLVM `clang++` when missing (Windows: `winget install --id LLVM.LLVM -e`)
+3. `.clangd`, `compile_flags.txt`, and `compile_commands.json` so clangd finds `include/` (clangd does **not** read `.vscode/c_cpp_properties.json`)
+4. Forced include of `include/cluaupp/roblox.hpp` so `GetService`, `Player`, `Janitor` complete from the real C++ stubs
+
+Tree-sitter is the **compiler** frontend (collect → emit Luau). It is not an editor language server. A homemade tokenizer in the CLI would fight clangd — that path is gone.
+
+Microsoft `ms-vscode.cpptools` is **not** used. Two C++ engines in the same window fight; Cluaupp disables the Microsoft engine (`C_Cpp.intelliSenseEngine: Disabled`).
+
+`cluaupp lsp` only publishes **subset parse errors** (code that clangd may accept as C++ but Cluaupp will not transpile).
+
+## Headers clangd must see
+
+`#include <cluaupp/roblox.hpp>` resolves only if `-Iinclude` is on the clangd compile flags. That maps to `include/cluaupp/roblox.hpp`. Angle-bracket includes are ignored by the transpiler.
+
+`cluaupp init` / `build` / `watch` / `intellisense` rewrite:
+
+- `-Iinclude` and `-Isrc`
+- `-include include/cluaupp/roblox.hpp`
+- one `compile_commands.json` entry per file under `src/`
+
+## Install
+
+```bash
+cluaupp intellisense
+```
+
+Reload: Command Palette → **Developer: Reload Window**. clangd should attach to `.cpp` files.
+
+`cluaupp build` / `watch` only refresh `compile_commands.json` (no download). They never keep deleted files in the compilation database.
+
+## Config that ships
+
+| File | Role |
+| --- | --- |
+| `.vscode/c_cpp_properties.json` | compiler path (unused by clangd; kept if someone re-enables cpptools) |
+| `.vscode/settings.json` | `C_Cpp.intelliSenseEngine: Disabled`, `clangd.enable: true`, `--compile-commands-dir` |
+| `.vscode/extensions.json` | recommends `llvm-vs-code-extensions.vscode-clangd` |
+| `.clangd` | C++20, `-Iinclude`, skip `out/` and `libs/` |
+| `compile_flags.txt` | fallback flags if a file is not yet in `compile_commands.json` |
+| `compile_commands.json` | one entry per `src/` file |
+
+`#include <cluaupp/roblox.hpp>` at the top of each source file. The header is not compiled to Luau.

package/docs/intro.md

@@ -12,7 +12,7 @@ This site is built with [Moonwave](https://eryn.io/moonwave/) for local markdown
 ## What you get
 
 1. A compiler (`cluaupp init` / `build` / `watch`)
-2. Headers for IntelliSense (`#include <cluaupp/roblox.hpp>`)
+2. Headers for **clangd** (`#include <cluaupp/roblox.hpp>`)
 3. First-party libraries in `ReplicatedStorage.CluauppLibs`
 4. Wally wrappers for DataServiceV2, Fusion, Cmdr, EzVisualz, TopbarPlus, and the rest of your stack
 

package/editors/vscode/extension.js

@@ -1,146 +1,97 @@
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-const vscode = require("vscode");
-
-function loadEngine(context) {
-	const folders = vscode.workspace.workspaceFolders || [];
-	const workspaceFolder = folders[0] ? folders[0].uri.fsPath : null;
-	const rootFile = path.join(context.extensionPath, "cluaupp.root");
-	const roots = [];
-	if (fs.existsSync(rootFile)) {
-		roots.push(fs.readFileSync(rootFile, "utf8").trim());
-	}
-	if (workspaceFolder) {
-		roots.push(path.join(workspaceFolder, "..", "Cluaupp"));
-		roots.push(path.join(workspaceFolder, "node_modules", "cluaupp"));
-	}
-	roots.push(path.join(context.extensionPath, "..", ".."));
-	for (const root of roots) {
-		const engine = path.join(root, "src", "intellisense.js");
-		if (fs.existsSync(engine)) {
-			return { engine: require(engine), root, workspaceFolder };
-		}
-	}
-	throw new Error("Cluaupp IntelliSense engine not found. Run `cluaupp intellisense` in the game folder.");
-}
-
-function kindOf(kind) {
-	const map = {
-		method: vscode.CompletionItemKind.Method,
-		function: vscode.CompletionItemKind.Function,
-		constructor: vscode.CompletionItemKind.Constructor,
-		property: vscode.CompletionItemKind.Property,
-		variable: vscode.CompletionItemKind.Variable,
-		class: vscode.CompletionItemKind.Class,
-		enum: vscode.CompletionItemKind.Enum,
-		keyword: vscode.CompletionItemKind.Keyword,
-		event: vscode.CompletionItemKind.Event,
-		file: vscode.CompletionItemKind.File,
-	};
-	return map[kind] || vscode.CompletionItemKind.Text;
-}
-
-function activate(context) {
-	let loaded;
-	try {
-		loaded = loadEngine(context);
-	} catch (err) {
-		vscode.window.showWarningMessage(String(err.message || err));
-		return;
-	}
-
-	const selector = { language: "cpp", scheme: "file" };
-	const diagnostics = vscode.languages.createDiagnosticCollection("cluaupp");
-	context.subscriptions.push(diagnostics);
-
-	const optionsFor = (document) => ({
-		projectRoot: loaded.workspaceFolder || path.dirname(document.uri.fsPath),
-		file: document.uri.fsPath,
-		filePath: document.uri.fsPath,
-		includeDirs: [
-			path.dirname(document.uri.fsPath),
-			path.join(loaded.workspaceFolder || "", "src"),
-			path.join(loaded.workspaceFolder || "", "include"),
-		],
-	});
-
-	const refreshDiagnostics = (document) => {
-		if (!document || document.languageId !== "cpp") {
-			return;
-		}
-		const items = loaded.engine.diagnosticsFor(document.getText(), document.uri.fsPath, optionsFor(document));
-		diagnostics.set(
-			document.uri,
-			items.map((item) => {
-				const line = Math.max(0, (item.line || 1) - 1);
-				const col = Math.max(0, (item.col || 1) - 1);
-				const range = new vscode.Range(line, col, line, col + 1);
-				return new vscode.Diagnostic(range, item.message, vscode.DiagnosticSeverity.Error);
-			}),
-		);
-	};
-
-	context.subscriptions.push(
-		vscode.languages.registerCompletionItemProvider(
-			selector,
-			{
-				provideCompletionItems(document, position) {
-					const offset = document.offsetAt(position);
-					const items = loaded.engine.completeAt(document.getText(), offset, optionsFor(document));
-					return items.map((item) => {
-						const completion = new vscode.CompletionItem(item.name, kindOf(item.kind));
-						completion.detail = item.detail || item.type || "";
-						completion.sortText = `${item.kind === "keyword" ? "2" : "0"}_${item.name}`;
-						completion.insertText = item.name;
-						return completion;
-					});
-				},
-			},
-			".",
-			":",
-			">",
-			"<",
-			'"',
-			"/",
-		),
-		vscode.languages.registerHoverProvider(selector, {
-			provideHover(document, position) {
-				const hover = loaded.engine.hoverAt(document.getText(), document.offsetAt(position), optionsFor(document));
-				if (!hover) {
-					return null;
-				}
-				return new vscode.Hover(new vscode.MarkdownString(`**${hover.name}**\n\n\`${hover.detail || hover.type || ""}\``));
-			},
-		}),
-		vscode.languages.registerDefinitionProvider(selector, {
-			provideDefinition(document, position) {
-				const def = loaded.engine.definitionAt(document.getText(), document.offsetAt(position), optionsFor(document));
-				if (!def || !def.file) {
-					return null;
-				}
-				return new vscode.Location(vscode.Uri.file(def.file), new vscode.Position(Math.max(0, (def.line || 1) - 1), 0));
-			},
-		}),
-		vscode.workspace.onDidChangeTextDocument((event) => refreshDiagnostics(event.document)),
-		vscode.workspace.onDidOpenTextDocument(refreshDiagnostics),
-		vscode.commands.registerCommand("cluaupp.restartIntelliSense", () => {
-			try {
-				delete require.cache[require.resolve(path.join(loaded.root, "src", "intellisense.js"))];
-				loaded = loadEngine(context);
-				vscode.window.showInformationMessage("Cluaupp IntelliSense reloaded.");
-			} catch (err) {
-				vscode.window.showErrorMessage(String(err.message || err));
-			}
-		}),
-	);
-
-	for (const document of vscode.workspace.textDocuments) {
-		refreshDiagnostics(document);
-	}
-}
-
-function deactivate() {}
-
-module.exports = { activate, deactivate };
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const vscode = require("vscode");
+
+function loadEngine(context) {
+	const folders = vscode.workspace.workspaceFolders || [];
+	const workspaceFolder = folders[0] ? folders[0].uri.fsPath : null;
+	const rootFile = path.join(context.extensionPath, "cluaupp.root");
+	const roots = [];
+	if (fs.existsSync(rootFile)) {
+		roots.push(fs.readFileSync(rootFile, "utf8").trim());
+	}
+	if (workspaceFolder) {
+		roots.push(path.join(workspaceFolder, "..", "Cluaupp"));
+		roots.push(path.join(workspaceFolder, "node_modules", "cluaupp"));
+	}
+	roots.push(path.join(context.extensionPath, "..", ".."));
+	for (const root of roots) {
+		const candidates = [
+			path.join(root, "generated", "intellisense.js"),
+			path.join(root, "src", "intellisense.js"),
+		];
+		for (const engine of candidates) {
+			if (fs.existsSync(engine)) {
+				return { engine: require(engine), root, workspaceFolder, enginePath: engine };
+			}
+		}
+	}
+	throw new Error("Cluaupp diagnostics engine not found. Run `cluaupp intellisense` in the game folder.");
+}
+
+function activate(context) {
+	let loaded;
+	try {
+		loaded = loadEngine(context);
+	} catch (err) {
+		vscode.window.showWarningMessage(String(err.message || err));
+		return;
+	}
+
+	const diagnostics = vscode.languages.createDiagnosticCollection("cluaupp");
+	context.subscriptions.push(diagnostics);
+
+	const optionsFor = (document) => ({
+		projectRoot: loaded.workspaceFolder || path.dirname(document.uri.fsPath),
+		file: document.uri.fsPath,
+		filePath: document.uri.fsPath,
+		includeDirs: [
+			path.dirname(document.uri.fsPath),
+			path.join(loaded.workspaceFolder || "", "src"),
+			path.join(loaded.workspaceFolder || "", "include"),
+		],
+	});
+
+	const refreshDiagnostics = (document) => {
+		if (!document || document.languageId !== "cpp") {
+			return;
+		}
+		if (typeof loaded.engine.diagnosticsFor !== "function") {
+			return;
+		}
+		const items = loaded.engine.diagnosticsFor(document.getText(), document.uri.fsPath, optionsFor(document));
+		diagnostics.set(
+			document.uri,
+			items.map((item) => {
+				const line = Math.max(0, (item.line || 1) - 1);
+				const col = Math.max(0, (item.col || 1) - 1);
+				const range = new vscode.Range(line, col, line, col + 1);
+				return new vscode.Diagnostic(range, item.message, vscode.DiagnosticSeverity.Error);
+			}),
+		);
+	};
+
+	context.subscriptions.push(
+		vscode.workspace.onDidChangeTextDocument((event) => refreshDiagnostics(event.document)),
+		vscode.workspace.onDidOpenTextDocument(refreshDiagnostics),
+		vscode.commands.registerCommand("cluaupp.restartIntelliSense", () => {
+			try {
+				delete require.cache[require.resolve(loaded.enginePath)];
+				loaded = loadEngine(context);
+				vscode.window.showInformationMessage("Cluaupp diagnostics reloaded. C++ completion is clangd.");
+			} catch (err) {
+				vscode.window.showErrorMessage(String(err.message || err));
+			}
+		}),
+	);
+
+	for (const document of vscode.workspace.textDocuments) {
+		refreshDiagnostics(document);
+	}
+}
+
+function deactivate() {}
+
+module.exports = { activate, deactivate };

package/editors/vscode/package.json

@@ -1,14 +1,14 @@
 {
-	"name": "cluaupp-intellisense",
-	"displayName": "Cluaupp IntelliSense",
-	"description": "Completions, hover, and go-to-definition for Cluaupp C++ (Roblox APIs, DataService paths, project structs).",
-	"version": "0.1.4",
+	"name": "cluaupp-diagnostics",
+	"displayName": "Cluaupp",
+	"description": "Cluaupp subset parse errors. C++ completion, hover, and go-to-definition come from clangd + include/cluaupp/roblox.hpp.",
+	"version": "0.2.0",
 	"publisher": "kartzdev",
 	"engines": {
 		"vscode": "^1.74.0"
 	},
 	"categories": [
-		"Programming Languages"
+		"Linters"
 	],
 	"activationEvents": [
 		"onLanguage:cpp"
@@ -18,7 +18,7 @@
 		"commands": [
 			{
 				"command": "cluaupp.restartIntelliSense",
-				"title": "Cluaupp: Restart IntelliSense"
+				"title": "Cluaupp: Reload subset diagnostics"
 			}
 		]
 	}

package/examples/README.md

@@ -0,0 +1,18 @@
+# Sample game
+
+This is the C++ a Cluaupp game looks like — **not** the compiler.
+
+| Folder | Rojo | Tag |
+| --- | --- | --- |
+| `src/server/*.server.cpp` | Script | server |
+| `src/client/*.client.cpp` | LocalScript | client |
+| `src/shared/*` | ModuleScript | none |
+
+`src/` of **this repo** is the TypeScript CLI ([roblox-ts](https://github.com/roblox-ts/roblox-ts) does the same). The sample scripts live here so they never mix with `understand.ts`.
+
+```bash
+cd examples/game
+npx cluaupp build .
+```
+
+`cluaupp init` copies `templates/game` (the slim scaffold). This folder adds combat / HUD so `SystemUnderstander` has real tokens to score.

package/examples/game/.clangd

@@ -0,0 +1,25 @@
+CompileFlags:
+  CompilationDatabase: .
+  Add:
+    - -xc++
+    - -std=c++20
+    - -ferror-limit=0
+    - -Iinclude
+    - -Isrc
+    - -I../../include
+
+Diagnostics:
+  Suppress: '*'
+
+---
+If:
+  PathMatch: .*\.(cpp|cc|cxx|c|h|hpp|hh)$
+CompileFlags:
+  Add:
+    - -xc++
+
+---
+If:
+  PathMatch: (out|libs)/.*
+Index:
+  Background: Skip