cluaupp 1.5.0 → 1.5.1

package/src/target/datamodel.ts

@@ -0,0 +1,261 @@
+/**
+ * Typed DataModel v1 — Rojo default.project.json → instance graph.
+ * Used for path validation at compile time and generated IntelliSense headers.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "comment-json";
+
+export const DATAMODEL_SCHEMA_VERSION = 1;
+
+export interface DatamodelNode {
+	/** Roblox instance name (tree key). */
+	name: string;
+	/** Dot path from game, e.g. ReplicatedStorage.Shared (DataModel root is "DataModel"). */
+	path: string;
+	className: string;
+	/** Project-relative fs path when backed by $path. */
+	fsPath?: string;
+	children: Record<string, DatamodelNode>;
+}
+
+export interface DatamodelProfile {
+	schemaVersion: number;
+	projectName: string;
+	projectJson: string;
+	root: DatamodelNode;
+	/** Flat index path → node */
+	byPath: Record<string, DatamodelNode>;
+	generatedAt: string;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		return null;
+	}
+	return value as Record<string, unknown>;
+}
+
+function posix(p: string): string {
+	return p.replace(/\\/g, "/");
+}
+
+function childPath(parentPath: string, name: string): string {
+	if (!parentPath || parentPath === "DataModel") {
+		return name;
+	}
+	return `${parentPath}.${name}`;
+}
+
+function readMetaClassName(dir: string): string | undefined {
+	for (const metaName of ["init.meta.json", "init.meta.jsonc"]) {
+		const file = path.join(dir, metaName);
+		if (!fs.existsSync(file)) {
+			continue;
+		}
+		try {
+			const meta = asRecord(parse(fs.readFileSync(file, "utf8")));
+			if (meta && typeof meta.className === "string") {
+				return meta.className;
+			}
+		} catch {
+			/* ignore */
+		}
+	}
+	return undefined;
+}
+
+function classFromFileName(fileName: string): { name: string; className: string } | null {
+	const lower = fileName.toLowerCase();
+	if (lower === "init.meta.json" || lower === "init.meta.jsonc") {
+		return null;
+	}
+	if (/\.server\.(luau|lua|clpp)$/i.test(fileName)) {
+		return { name: fileName.replace(/\.server\.(luau|lua|clpp)$/i, ""), className: "Script" };
+	}
+	if (/\.client\.(luau|lua|clpp)$/i.test(fileName)) {
+		return { name: fileName.replace(/\.client\.(luau|lua|clpp)$/i, ""), className: "LocalScript" };
+	}
+	if (/\.plugin\.(luau|lua|clpp)$/i.test(fileName)) {
+		return { name: fileName.replace(/\.plugin\.(luau|lua|clpp)$/i, ""), className: "Script" };
+	}
+	if (/^init\.(luau|lua|clpp|clp)$/i.test(fileName)) {
+		return null;
+	}
+	if (/\.(luau|lua|clpp|clp|clh)$/i.test(fileName)) {
+		return {
+			name: fileName.replace(/\.(luau|lua|clpp|clp|clh)$/i, ""),
+			className: "ModuleScript",
+		};
+	}
+	return null;
+}
+
+function scanFsChildren(absDir: string, parentPath: string, projectRoot: string): Record<string, DatamodelNode> {
+	const children: Record<string, DatamodelNode> = {};
+	if (!fs.existsSync(absDir) || !fs.statSync(absDir).isDirectory()) {
+		return children;
+	}
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(absDir, { withFileTypes: true });
+	} catch {
+		return children;
+	}
+	for (const entry of entries) {
+		if (entry.name.startsWith(".")) {
+			continue;
+		}
+		const full = path.join(absDir, entry.name);
+		if (entry.isDirectory()) {
+			const className = readMetaClassName(full) || "Folder";
+			const nodePath = childPath(parentPath, entry.name);
+			children[entry.name] = {
+				name: entry.name,
+				path: nodePath,
+				className,
+				fsPath: posix(path.relative(projectRoot, full) || "."),
+				children: scanFsChildren(full, nodePath, projectRoot),
+			};
+			continue;
+		}
+		if (!entry.isFile()) {
+			continue;
+		}
+		const mapped = classFromFileName(entry.name);
+		if (!mapped || !mapped.name) {
+			continue;
+		}
+		const nodePath = childPath(parentPath, mapped.name);
+		children[mapped.name] = {
+			name: mapped.name,
+			path: nodePath,
+			className: mapped.className,
+			fsPath: posix(path.relative(projectRoot, full)),
+			children: {},
+		};
+	}
+	return children;
+}
+
+function walkNamedNode(node: unknown, name: string, parentPath: string, projectRoot: string): DatamodelNode {
+	const record = asRecord(node) || {};
+	const nodePath = childPath(parentPath, name);
+	const className = typeof record.$className === "string" ? record.$className : "Folder";
+	const fsRel = typeof record.$path === "string" ? record.$path : undefined;
+	const absFs = fsRel ? path.resolve(projectRoot, fsRel) : undefined;
+
+	const children: Record<string, DatamodelNode> = {};
+	for (const [key, child] of Object.entries(record)) {
+		if (key.startsWith("$")) {
+			continue;
+		}
+		children[key] = walkNamedNode(child, key, nodePath, projectRoot);
+	}
+
+	if (absFs && fs.existsSync(absFs) && fs.statSync(absFs).isDirectory()) {
+		const scanned = scanFsChildren(absFs, nodePath, projectRoot);
+		for (const [key, child] of Object.entries(scanned)) {
+			if (!children[key]) {
+				children[key] = child;
+			} else {
+				children[key] = {
+					...children[key],
+					fsPath: children[key].fsPath || child.fsPath,
+					children: { ...child.children, ...children[key].children },
+				};
+			}
+		}
+	}
+
+	return {
+		name,
+		path: nodePath,
+		className,
+		fsPath: fsRel ? posix(fsRel) : undefined,
+		children,
+	};
+}
+
+function indexByPath(node: DatamodelNode, into: Record<string, DatamodelNode>): void {
+	into[node.path] = node;
+	for (const child of Object.values(node.children)) {
+		indexByPath(child, into);
+	}
+}
+
+export function findProjectJson(projectRoot: string, explicit?: string): string | null {
+	const candidates = [
+		explicit,
+		path.join(projectRoot, "default.project.json"),
+		path.join(projectRoot, "default.project.jsonc"),
+	].filter(Boolean) as string[];
+	for (const c of candidates) {
+		const abs = path.resolve(c);
+		if (fs.existsSync(abs)) {
+			return abs;
+		}
+	}
+	return null;
+}
+
+export function buildDatamodelProfile(projectRoot: string, projectJsonPath?: string): DatamodelProfile | null {
+	const jsonPath = findProjectJson(projectRoot, projectJsonPath);
+	if (!jsonPath) {
+		return null;
+	}
+	const raw = parse(fs.readFileSync(jsonPath, "utf8")) as { name?: string; tree?: unknown };
+	const tree = asRecord(raw.tree) || {};
+	const className = typeof tree.$className === "string" ? tree.$className : "DataModel";
+	const children: Record<string, DatamodelNode> = {};
+	for (const [key, child] of Object.entries(tree)) {
+		if (key.startsWith("$")) {
+			continue;
+		}
+		children[key] = walkNamedNode(child, key, "DataModel", projectRoot);
+	}
+
+	const root: DatamodelNode = {
+		name: "DataModel",
+		path: "DataModel",
+		className,
+		children,
+	};
+
+	const byPath: Record<string, DatamodelNode> = {};
+	indexByPath(root, byPath);
+
+	return {
+		schemaVersion: DATAMODEL_SCHEMA_VERSION,
+		projectName: typeof raw.name === "string" ? raw.name : "game",
+		projectJson: posix(path.relative(projectRoot, jsonPath) || path.basename(jsonPath)),
+		root,
+		byPath,
+		generatedAt: new Date().toISOString(),
+	};
+}
+
+export function lookupChild(parent: DatamodelNode, childName: string): DatamodelNode | undefined {
+	return parent.children[childName];
+}
+
+export function resolvePath(profile: DatamodelProfile, segments: string[]): DatamodelNode | null {
+	let node: DatamodelNode = profile.root;
+	for (const seg of segments) {
+		if (seg === "game" || seg === "DataModel") {
+			node = profile.root;
+			continue;
+		}
+		const next = lookupChild(node, seg);
+		if (!next) {
+			return null;
+		}
+		node = next;
+	}
+	return node;
+}
+
+export function listChildNames(node: DatamodelNode): string[] {
+	return Object.keys(node.children).sort();
+}

package/src/target/diagnostics.ts

@@ -0,0 +1,67 @@
+/** Shared diagnostic shape for platform analyzers. */
+export interface PlatformDiagnostic {
+	code: string;
+	message: string;
+	line: number;
+	column: number;
+	severity: "error" | "warning" | "info";
+	file?: string;
+}
+
+export function lineColAt(source: string, index: number): { line: number; column: number } {
+	let line = 1;
+	let column = 1;
+	for (let i = 0; i < index && i < source.length; i++) {
+		if (source[i] === "\n") {
+			line++;
+			column = 1;
+		} else {
+			column++;
+		}
+	}
+	return { line, column };
+}
+
+export function stripCommentsKeepStrings(source: string): string {
+	let out = "";
+	let i = 0;
+	while (i < source.length) {
+		const c = source[i];
+		const next = source[i + 1];
+		if (c === "/" && next === "/") {
+			while (i < source.length && source[i] !== "\n") i++;
+			continue;
+		}
+		if (c === "/" && next === "*") {
+			i += 2;
+			while (i < source.length - 1 && !(source[i] === "*" && source[i + 1] === "/")) {
+				if (source[i] === "\n") out += "\n";
+				i++;
+			}
+			i += 2;
+			continue;
+		}
+		if (c === '"' || c === "'" || c === "`") {
+			const q = c;
+			out += c;
+			i++;
+			while (i < source.length && source[i] !== q) {
+				if (source[i] === "\\" && i + 1 < source.length) {
+					out += source[i] + source[i + 1];
+					i += 2;
+					continue;
+				}
+				out += source[i];
+				i++;
+			}
+			if (i < source.length) {
+				out += source[i];
+				i++;
+			}
+			continue;
+		}
+		out += c;
+		i++;
+	}
+	return out;
+}

package/src/target/doctor.ts

@@ -0,0 +1,171 @@
+/**
+ * cluaupp doctor — run all platform checks and report.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { collectSources } from "../clpp/paths.js";
+import { buildRobloxTargetProfile, profileContentHash } from "../api/build-profile.js";
+import { projectRoot as pkgRoot } from "../package-info.js";
+import { overridesHash } from "../api/loader.js";
+import { writeCapabilityProfile } from "./capability-profile.js";
+import { builtinCapabilityProfile } from "./capabilities.js";
+import { checkContextSafety } from "./context-check.js";
+import { writeDatamodelArtifacts } from "./datamodel-generate.js";
+import { checkDatamodelPaths } from "./datamodel-check.js";
+import { checkParallelSafety } from "./parallel-check.js";
+import { checkAuthority, loadPlatformPolicy } from "./authority-check.js";
+import { checkAuthorityGraph } from "./authority-graph.js";
+import { checkComponentContracts } from "./component-contracts.js";
+import { checkSecurity } from "./security-check.js";
+import { checkLifetime } from "./lifetime-check.js";
+import { adviseOptimizer, adviceAsDiagnostics } from "./optimizer-advise.js";
+import { buildProjectGraph } from "./project-graph.js";
+import { checkFlareVersions } from "./flare-version.js";
+import { checkGetService } from "./get-service.js";
+import type { PlatformDiagnostic } from "./diagnostics.js";
+
+export interface DoctorReport {
+	ok: boolean;
+	checks: Array<{ name: string; ok: boolean; detail?: string; diagnostics?: PlatformDiagnostic[] }>;
+	outOfScope: string[];
+}
+
+function verifyLockLocal(): { ok: boolean; messages: string[] } {
+	const lockPath = path.join(pkgRoot, "api", "roblox-api.lock.json");
+	if (!fs.existsSync(lockPath)) {
+		return { ok: false, messages: ["missing api/roblox-api.lock.json"] };
+	}
+	try {
+		const lock = JSON.parse(fs.readFileSync(lockPath, "utf8")) as { profileHash?: string; overridesHash?: string };
+		const profile = buildRobloxTargetProfile({ skipValidate: true });
+		const messages: string[] = [];
+		const ph = profileContentHash(profile);
+		if (lock.profileHash && lock.profileHash !== ph) {
+			messages.push("profile hash drift — run cluaupp api generate");
+		}
+		if (lock.overridesHash && lock.overridesHash !== overridesHash()) {
+			messages.push("overrides hash drift — run cluaupp api generate");
+		}
+		return { ok: messages.length === 0, messages };
+	} catch (err) {
+		return { ok: false, messages: [err instanceof Error ? err.message : String(err)] };
+	}
+}
+
+export function runDoctor(gameRoot: string, rootDir = "src"): DoctorReport {
+	const checks: DoctorReport["checks"] = [];
+	const srcDir = path.join(gameRoot, rootDir);
+	const files = fs.existsSync(srcDir) ? collectSources(srcDir) : [];
+	const policy = loadPlatformPolicy(gameRoot);
+
+	try {
+		buildRobloxTargetProfile({ skipValidate: true });
+		checks.push({ name: "api-registry", ok: true });
+	} catch (err) {
+		checks.push({ name: "api-registry", ok: false, detail: err instanceof Error ? err.message : String(err) });
+	}
+
+	const lock =
+		path.resolve(gameRoot) === path.resolve(pkgRoot) ? verifyLockLocal() : { ok: true, messages: ["skipped (not Cluaupp package root)"] };
+	checks.push({ name: "api-lock", ok: lock.ok, detail: lock.ok ? lock.messages[0] : lock.messages.join("; ") });
+
+	writeCapabilityProfile();
+	checks.push({ name: "context-profile", ok: true, detail: `${builtinCapabilityProfile().rules.length} rules` });
+
+	const dm = writeDatamodelArtifacts(gameRoot);
+	checks.push({
+		name: "datamodel",
+		ok: Boolean(dm),
+		detail: dm ? `${Object.keys(dm.profile.byPath).length} nodes` : "no default.project.json",
+	});
+
+	const allDiags: PlatformDiagnostic[] = [];
+	for (const file of files) {
+		const rel = path.relative(gameRoot, file).replace(/\\/g, "/");
+		const source = fs.readFileSync(file, "utf8");
+		allDiags.push(
+			...checkContextSafety(source, rel).map((d) => ({
+				code: d.code,
+				message: d.message,
+				line: d.line,
+				column: d.column,
+				severity: d.severity as PlatformDiagnostic["severity"],
+				file: rel,
+			})),
+		);
+		allDiags.push(...checkParallelSafety(source, rel));
+		allDiags.push(...checkAuthority(source, rel, policy));
+		allDiags.push(
+			...checkGetService(source, rel).map((d) => ({
+				code: "CLUAU_SVC001",
+				message: d.message,
+				line: d.line,
+				column: d.column,
+				severity: d.severity as PlatformDiagnostic["severity"],
+				file: rel,
+			})),
+		);
+		allDiags.push(...checkSecurity(source, rel));
+		allDiags.push(...checkLifetime(source, rel));
+		allDiags.push(...adviceAsDiagnostics(adviseOptimizer(source, rel), rel));
+		if (dm) {
+			allDiags.push(
+				...checkDatamodelPaths(source, dm.profile).map((d) => ({
+					code: d.code,
+					message: d.message,
+					line: d.line,
+					column: d.column,
+					severity: d.severity as PlatformDiagnostic["severity"],
+					file: rel,
+				})),
+			);
+		}
+	}
+
+	if (dm && policy.components?.length) {
+		allDiags.push(...checkComponentContracts(dm.profile, policy.components));
+	}
+
+	const flare = checkFlareVersions(gameRoot, rootDir);
+	allDiags.push(...flare.conflicts);
+	allDiags.push(...checkAuthorityGraph(gameRoot, rootDir, policy));
+
+	const graph = buildProjectGraph(gameRoot, rootDir);
+	if (graph.cycles.length) {
+		allDiags.push({
+			code: "CLUAU_GRAPH_CYCLE",
+			message: `Circular includes: ${graph.cycles.map((c) => c.join(" → ")).join(" | ")}`,
+			line: 1,
+			column: 1,
+			severity: "error",
+		});
+	}
+
+	const errors = allDiags.filter((d) => d.severity === "error");
+	const warnings = allDiags.filter((d) => d.severity === "warning");
+	checks.push({
+		name: "source-analysis",
+		ok: errors.length === 0,
+		detail: `${files.length} files, ${errors.length} errors, ${warnings.length} warnings, ${allDiags.filter((d) => d.severity === "info").length} info`,
+		diagnostics: allDiags.slice(0, 50),
+	});
+	checks.push({
+		name: "project-graph",
+		ok: graph.cycles.length === 0,
+		detail: `${graph.nodes.length} nodes, ${graph.edges.length} edges, ${graph.cycles.length} cycles`,
+	});
+	checks.push({
+		name: "flare-versions",
+		ok: flare.conflicts.length === 0,
+		detail: `${flare.files.length} schemas`,
+	});
+
+	return {
+		ok: checks.every((c) => c.ok),
+		checks,
+		outOfScope: [
+			"Roblox bytecode / custom VM debugger (Studio ScriptContext + maps + CluauppNav cover source-level)",
+		],
+	};
+}

package/src/target/flare-version.ts

@@ -0,0 +1,61 @@
+/** Flare remote versioning — detect schema version drift across .flare files. */
+import fs from "node:fs";
+import path from "node:path";
+import { collectFlareFiles, parseFlare } from "../flare/index.js";
+import type { PlatformDiagnostic } from "./diagnostics.js";
+
+export interface FlareVersionReport {
+	files: Array<{ file: string; name: string; version: number | null }>;
+	conflicts: PlatformDiagnostic[];
+}
+
+function readVersion(source: string, parsedVersion?: number): number | null {
+	if (typeof parsedVersion === "number" && Number.isFinite(parsedVersion)) {
+		return parsedVersion;
+	}
+	const m =
+		source.match(/^\s*version\s+(\d+)\s*;?/m) ||
+		source.match(/^\s*opt\s+version\s*=\s*(\d+)/im) ||
+		source.match(/^\s*#\s*version\s+(\d+)/m);
+	return m ? Number(m[1]) : null;
+}
+
+export function checkFlareVersions(projectRoot: string, rootDir = "src"): FlareVersionReport {
+	const srcDir = path.join(projectRoot, rootDir);
+	const files = fs.existsSync(srcDir) ? collectFlareFiles(srcDir) : [];
+	const byName = new Map<string, Array<{ file: string; version: number | null }>>();
+	const listed: FlareVersionReport["files"] = [];
+
+	for (const file of files) {
+		const source = fs.readFileSync(file, "utf8");
+		const rel = path.relative(projectRoot, file).replace(/\\/g, "/");
+		let name = path.basename(file, ".flare");
+		let parsedVersion: number | undefined;
+		try {
+			const parsed = parseFlare(source, rel, name);
+			name = parsed.name || name;
+			parsedVersion = parsed.version;
+		} catch {
+			/* parse may fail on partial */
+		}
+		const version = readVersion(source, parsedVersion);
+		listed.push({ file: rel, name, version });
+		if (!byName.has(name)) byName.set(name, []);
+		byName.get(name)!.push({ file: rel, version });
+	}
+
+	const conflicts: PlatformDiagnostic[] = [];
+	for (const [name, entries] of byName) {
+		const versions = new Set(entries.map((e) => e.version).filter((v) => v !== null));
+		if (versions.size > 1) {
+			conflicts.push({
+				code: "CLUAU_NET_VERSION",
+				message: `Flare contract "${name}" has conflicting versions: ${[...versions].join(", ")} across ${entries.map((e) => e.file).join(", ")}`,
+				line: 1,
+				column: 1,
+				severity: "error",
+			});
+		}
+	}
+	return { files: listed, conflicts };
+}

package/src/target/get-service.ts

@@ -0,0 +1,85 @@
+/**
+ * GetService\<T\>() — Cluaupp host feature (Roblox Target), not a CL++ language primitive.
+ *
+ * CL++ parses `GetService<Players>()` as a normal generic call and may emit
+ * `game:GetService("Players")`. Cluaupp owns:
+ * - which names are services (Canonical Registry)
+ * - IntelliSense stubs (`#include <clpp/roblox.clh>`)
+ * - Context Safety / capability rules for services
+ * - unknown-service diagnostics at build time
+ */
+
+import type { CompileDiagnostic } from "../clpp/contract.js";
+import type { RobloxTargetProfile } from "../api/model.js";
+import { buildRobloxTargetProfile } from "../api/build-profile.js";
+import { lineColAt, stripCommentsKeepStrings } from "./diagnostics.js";
+import { resolveGetServiceType } from "./roblox.js";
+
+const GET_SERVICE_CALL =
+	/\bGetService\s*(?:<\s*([A-Za-z_]\w*)\s*>\s*\(\s*\)|\(\s*["']([A-Za-z_]\w*)["']\s*\))/g;
+
+export interface GetServiceUse {
+	service: string;
+	index: number;
+	generic: boolean;
+}
+
+/** Extract GetService\<T\>() / GetService("T") uses from CL++ source. */
+export function collectGetServiceUses(source: string): GetServiceUse[] {
+	const clean = stripCommentsKeepStrings(source);
+	const out: GetServiceUse[] = [];
+	GET_SERVICE_CALL.lastIndex = 0;
+	let m: RegExpExecArray | null;
+	while ((m = GET_SERVICE_CALL.exec(clean))) {
+		const service = m[1] || m[2];
+		if (!service) continue;
+		out.push({ service, index: m.index, generic: Boolean(m[1]) });
+	}
+	return out;
+}
+
+export function checkGetService(
+	source: string,
+	fileName: string,
+	profile?: RobloxTargetProfile,
+): CompileDiagnostic[] {
+	const p = profile || buildRobloxTargetProfile({ skipValidate: true });
+	const clean = stripCommentsKeepStrings(source);
+	const out: CompileDiagnostic[] = [];
+	for (const use of collectGetServiceUses(source)) {
+		if (resolveGetServiceType(use.service, p)) {
+			continue;
+		}
+		const { line, column } = lineColAt(clean, use.index);
+		out.push({
+			message: `CLUAU_SVC001: unknown service \`${use.service}\` for GetService (Cluaupp registry)`,
+			line,
+			column,
+			severity: "error",
+		});
+	}
+	return out;
+}
+
+export function assertGetServiceSafe(
+	source: string,
+	fileName: string,
+	profile?: RobloxTargetProfile,
+): void {
+	const diags = checkGetService(source, fileName, profile);
+	if (diags.length === 0) {
+		return;
+	}
+	const body = diags.map((d) => `  ${fileName}:${d.line}:${d.column}: ${d.message}`).join("\n");
+	throw new Error(`cluaupp: GetService check failed\n${body}`);
+}
+
+/**
+ * Normalize free-standing GetService leftovers in Luau to game:GetService("Name").
+ * Prefer CL++ emit; this is a host safety net for host-owned semantics.
+ */
+export function rewriteGetServiceLuau(luau: string): string {
+	return String(luau)
+		.replace(/\bGetService\s*<\s*([A-Za-z_]\w*)\s*>\s*\(\s*\)/g, 'game:GetService("$1")')
+		.replace(/\bGetService\s*\(\s*["']([A-Za-z_]\w*)["']\s*\)/g, 'game:GetService("$1")');
+}

package/src/target/lifetime-check.ts

@@ -0,0 +1,45 @@
+/** Lifetime / leak heuristics (CLUAU-LIFE*). */
+import { type PlatformDiagnostic, lineColAt, stripCommentsKeepStrings } from "./diagnostics.js";
+
+export function checkLifetime(source: string, fileName: string): PlatformDiagnostic[] {
+	const clean = stripCommentsKeepStrings(source);
+	const out: PlatformDiagnostic[] = [];
+	const connectRe = /\.Connect\s*\(/g;
+	let m: RegExpExecArray | null;
+	while ((m = connectRe.exec(clean))) {
+		const before = clean.slice(Math.max(0, m.index - 8), m.index);
+		if (before.includes("~>") || before.endsWith("::")) {
+			continue;
+		}
+		const window = clean.slice(Math.max(0, m.index - 120), m.index + 80);
+		if (window.includes("janitor") || window.includes("Sweep") || /\.Add\s*\(/.test(window)) {
+			continue;
+		}
+		const { line, column } = lineColAt(clean, m.index);
+		out.push({
+			code: "CLUAU_LIFE001",
+			message: "Connection created without Sweep/`~>` / janitor.Add nearby — possible leak",
+			line,
+			column,
+			severity: "warning",
+			file: fileName,
+		});
+	}
+	const spawnRe = /\bspawn\s*\{/g;
+	while ((m = spawnRe.exec(clean))) {
+		const bodyEnd = clean.indexOf("}", m.index);
+		const body = clean.slice(m.index, bodyEnd > 0 ? bodyEnd : m.index + 200);
+		if (!/cancel|Cleanup|Destroy|return/.test(body) && /while\s*\(|for\s*\(/.test(body)) {
+			const { line, column } = lineColAt(clean, m.index);
+			out.push({
+				code: "CLUAU_LIFE002",
+				message: "spawn { } with a loop and no obvious cancellation path",
+				line,
+				column,
+				severity: "info",
+				file: fileName,
+			});
+		}
+	}
+	return out;
+}