cluaupp 1.5.0 → 1.5.1

package/src/api/registry.ts

@@ -0,0 +1,162 @@
+import type {
+	ClassDefinition,
+	EventDefinition,
+	MethodDefinition,
+	PropertyDefinition,
+	RobloxTargetProfile,
+	ServiceDefinition,
+} from "./model.js";
+
+export interface ApiRegistry {
+	profile: RobloxTargetProfile;
+	classes: Map<string, ClassDefinition>;
+	services: Map<string, ServiceDefinition>;
+	enums: Map<string, RobloxTargetProfile["enums"][string]>;
+	datatypes: Map<string, RobloxTargetProfile["datatypes"][string]>;
+	members: Map<string, { owner: string; kind: string; name: string }>;
+	methods: Map<string, MethodDefinition[]>;
+	properties: Map<string, PropertyDefinition>;
+	events: Map<string, EventDefinition>;
+	ancestors: Map<string, string[]>;
+}
+
+export function buildRegistry(profile: RobloxTargetProfile): ApiRegistry {
+	const classes = new Map(Object.entries(profile.classes));
+	const services = new Map(Object.entries(profile.services));
+	const enums = new Map(Object.entries(profile.enums));
+	const datatypes = new Map(Object.entries(profile.datatypes));
+	const members = new Map<string, { owner: string; kind: string; name: string }>();
+	const methods = new Map<string, MethodDefinition[]>();
+	const properties = new Map<string, PropertyDefinition>();
+	const events = new Map<string, EventDefinition>();
+	const ancestors = new Map<string, string[]>();
+
+	for (const cls of classes.values()) {
+		ancestors.set(cls.name, collectAncestors(cls.name, profile.classes));
+		for (const prop of cls.properties) {
+			const key = `${cls.name}.${prop.name}`;
+			properties.set(key, prop);
+			members.set(key, { owner: cls.name, kind: "property", name: prop.name });
+		}
+		for (const method of cls.methods) {
+			const key = `${cls.name}.${method.name}`;
+			const list = methods.get(key) || [];
+			list.push(method);
+			methods.set(key, list);
+			members.set(key, { owner: cls.name, kind: "method", name: method.name });
+		}
+		for (const event of cls.events) {
+			const key = `${cls.name}.${event.name}`;
+			events.set(key, event);
+			members.set(key, { owner: cls.name, kind: "event", name: event.name });
+		}
+		for (const cb of cls.callbacks) {
+			members.set(`${cls.name}.${cb.name}`, { owner: cls.name, kind: "callback", name: cb.name });
+		}
+	}
+
+	return {
+		profile,
+		classes,
+		services,
+		enums,
+		datatypes,
+		members,
+		methods,
+		properties,
+		events,
+		ancestors,
+	};
+}
+
+function collectAncestors(name: string, classes: Record<string, ClassDefinition>): string[] {
+	const chain: string[] = [];
+	let current = classes[name]?.superclass || null;
+	const seen = new Set<string>();
+	while (current && !seen.has(current)) {
+		seen.add(current);
+		chain.push(current);
+		current = classes[current]?.superclass || null;
+	}
+	return chain;
+}
+
+/** Flattened IntelliSense view — does not mutate ClassGraph. */
+export function flattenMembers(registry: ApiRegistry, className: string): {
+	properties: PropertyDefinition[];
+	methods: MethodDefinition[];
+	events: EventDefinition[];
+} {
+	const order = [className, ...(registry.ancestors.get(className) || [])];
+	const properties: PropertyDefinition[] = [];
+	const methods: MethodDefinition[] = [];
+	const events: EventDefinition[] = [];
+	const seenProp = new Set<string>();
+	const seenMethod = new Set<string>();
+	const seenEvent = new Set<string>();
+	for (const name of order) {
+		const cls = registry.classes.get(name);
+		if (!cls) {
+			continue;
+		}
+		for (const p of cls.properties) {
+			if (!seenProp.has(p.name)) {
+				seenProp.add(p.name);
+				properties.push(p);
+			}
+		}
+		for (const m of cls.methods) {
+			const key = `${m.name}#${m.overloadIndex}`;
+			if (!seenMethod.has(key)) {
+				seenMethod.add(key);
+				methods.push(m);
+			}
+		}
+		for (const e of cls.events) {
+			if (!seenEvent.has(e.name)) {
+				seenEvent.add(e.name);
+				events.push(e);
+			}
+		}
+	}
+	return { properties, methods, events };
+}
+
+export function deriveServices(classes: Record<string, ClassDefinition>): Record<string, ServiceDefinition> {
+	const services: Record<string, ServiceDefinition> = {};
+	for (const cls of Object.values(classes)) {
+		if (!cls.service && !cls.creation.service) {
+			continue;
+		}
+		services[cls.name] = {
+			name: cls.name,
+			className: cls.name,
+			kind: "service",
+			accessor: "game:GetService",
+			singleton: true,
+			type: { kind: "Class", name: cls.name },
+		};
+	}
+	return services;
+}
+
+export function searchRegistry(registry: ApiRegistry, query: string, limit = 50): Array<{ kind: string; symbol: string }> {
+	const q = query.toLowerCase();
+	const hits: Array<{ kind: string; symbol: string }> = [];
+	for (const name of registry.classes.keys()) {
+		if (name.toLowerCase().includes(q)) {
+			hits.push({ kind: "class", symbol: name });
+		}
+	}
+	for (const name of registry.enums.keys()) {
+		if (name.toLowerCase().includes(q)) {
+			hits.push({ kind: "enum", symbol: name });
+		}
+	}
+	for (const [key] of registry.members) {
+		if (key.toLowerCase().includes(q)) {
+			hits.push({ kind: "member", symbol: key });
+		}
+	}
+	return hits.slice(0, limit);
+}

package/src/api/release.ts

@@ -0,0 +1,47 @@
+/** Release / checksum helpers for Roblox Target artifacts. */
+import fs from "node:fs";
+import path from "node:path";
+import { projectRoot } from "../package-info.js";
+import { pkg } from "../package-info.js";
+import { hashBuffer } from "./resolver.js";
+import { ROBLOX_TARGET_SCHEMA_VERSION } from "./model.js";
+
+export interface ReleaseChecklist {
+	schemaVersion: number;
+	generatorVersion: string;
+	lockPresent: boolean;
+	manifestPresent: boolean;
+	checksums: Record<string, string>;
+}
+
+export function buildReleaseChecklist(): ReleaseChecklist {
+	const lockPath = path.join(projectRoot, "api", "roblox-api.lock.json");
+	const manifestPath = path.join(projectRoot, "api", "manifests", "roblox-target.manifest.json");
+	const checksums: Record<string, string> = {};
+	for (const rel of [
+		"include/clpp/generated/enums.clh",
+		"include/clpp/datatypes.clh",
+		"include/clpp/generated/instances.clh",
+		"api/overrides/datatypes.json",
+	]) {
+		const full = path.join(projectRoot, rel);
+		if (fs.existsSync(full)) {
+			checksums[rel] = hashBuffer(fs.readFileSync(full));
+		}
+	}
+	return {
+		schemaVersion: ROBLOX_TARGET_SCHEMA_VERSION,
+		generatorVersion: pkg.version,
+		lockPresent: fs.existsSync(lockPath),
+		manifestPresent: fs.existsSync(manifestPath),
+		checksums,
+	};
+}
+
+export function writeApiChangelog(entries: string[], outPath?: string): string {
+	const target = outPath || path.join(projectRoot, "api", "CHANGELOG.md");
+	const body = [`# Roblox API changelog`, ``, ...entries.map((e) => `- ${e}`), ``].join("\n");
+	fs.mkdirSync(path.dirname(target), { recursive: true });
+	fs.writeFileSync(target, body, "utf8");
+	return target;
+}

package/src/api/resolver.ts

@@ -0,0 +1,255 @@
+import { createHash } from "node:crypto";
+import type { CanonicalType, DefaultKind, ParameterDefinition } from "./model.js";
+
+export type RobloxTypeRef = {
+	Category?: string;
+	Name?: string;
+	Optional?: boolean;
+};
+
+const PRIMITIVE_MAP: Record<string, string> = {
+	bool: "boolean",
+	boolean: "boolean",
+	int: "int",
+	int64: "int64",
+	float: "float",
+	double: "double",
+	number: "double",
+	string: "string",
+	null: "void",
+	void: "void",
+	nil: "void",
+};
+
+export function hashBuffer(data: string | Buffer): string {
+	return createHash("sha256").update(data).digest("hex");
+}
+
+export function mapRobloxType(ref: RobloxTypeRef | string | undefined | null): CanonicalType {
+	if (!ref) {
+		return { kind: "Unknown" };
+	}
+	if (typeof ref === "string") {
+		return mapNamedType(ref);
+	}
+	const category = String(ref.Category || "");
+	const name = String(ref.Name || "");
+	let mapped: CanonicalType;
+	switch (category) {
+		case "Primitive":
+			mapped = mapNamedType(name);
+			break;
+		case "Class":
+			mapped = { kind: "Class", name };
+			break;
+		case "Enum":
+			mapped = { kind: "Enum", name };
+			break;
+		case "DataType":
+			if (name === "Function") {
+				mapped = {
+					kind: "Function",
+					parameters: [{ kind: "Any" }],
+					returns: [{ kind: "Any" }],
+					variadic: true,
+				};
+			} else if (name === "buffer" || name === "Buffer") {
+				mapped = { kind: "Buffer" };
+			} else {
+				mapped = { kind: "Datatype", name };
+			}
+			break;
+		case "Group":
+			if (name === "Array") {
+				mapped = { kind: "Array", element: { kind: "Any" } };
+			} else if (name === "Dictionary" || name === "Map") {
+				mapped = {
+					kind: "Dictionary",
+					key: { kind: "Any" },
+					value: { kind: "Any" },
+				};
+			} else if (name === "Tuple") {
+				mapped = { kind: "Tuple", elements: [{ kind: "Any" }] };
+			} else if (name === "Variant") {
+				mapped = { kind: "Any" };
+			} else {
+				mapped = {
+					kind: "Unsupported",
+					raw: `${category}:${name}`,
+					reason: `Group type ${name} has no direct CL++ mapping yet`,
+				};
+			}
+			break;
+		default:
+			if (!name) {
+				mapped = { kind: "Unknown" };
+			} else {
+				mapped = mapNamedType(name);
+			}
+	}
+	if (ref.Optional || /\?$/.test(name)) {
+		return { kind: "Optional", inner: stripOptionalMarker(mapped) };
+	}
+	return mapped;
+}
+
+function stripOptionalMarker(type: CanonicalType): CanonicalType {
+	if (type.kind === "Class" || type.kind === "Enum" || type.kind === "Datatype" || type.kind === "Primitive") {
+		return { ...type, name: type.name.replace(/\?$/, "") };
+	}
+	return type;
+}
+
+function mapNamedType(rawName: string): CanonicalType {
+	const name = rawName.replace(/\?$/, "");
+	if (!name) {
+		return { kind: "Unknown" };
+	}
+	if (name === "any") {
+		return { kind: "Any" };
+	}
+	if (name === "unknown") {
+		return { kind: "Unknown" };
+	}
+	if (name === "never") {
+		return { kind: "Never" };
+	}
+	if (name === "buffer" || name === "Buffer") {
+		return { kind: "Buffer" };
+	}
+	if (PRIMITIVE_MAP[name]) {
+		return { kind: "Primitive", name: PRIMITIVE_MAP[name] };
+	}
+	if (/^[A-Z]/.test(name)) {
+		return { kind: "Class", name };
+	}
+	return { kind: "Primitive", name };
+}
+
+export function mapParameter(
+	param: { Name?: string; Type?: RobloxTypeRef; Default?: string },
+	index: number,
+): ParameterDefinition {
+	const name = param.Name || `arg${index}`;
+	const type = mapRobloxType(param.Type);
+	const optional = type.kind === "Optional" || param.Default !== undefined;
+	const def = classifyDefault(param.Default);
+	return {
+		name,
+		type: optional && type.kind !== "Optional" ? { kind: "Optional", inner: type } : type,
+		optional,
+		default: param.Default,
+		defaultKind: def,
+	};
+}
+
+function classifyDefault(value: string | undefined): DefaultKind | undefined {
+	if (value === undefined) {
+		return undefined;
+	}
+	if (value === "null" || value === "nil") {
+		return "Null";
+	}
+	if (value === "true" || value === "false") {
+		return "Boolean";
+	}
+	if (/^-?\d+(\.\d+)?$/.test(value)) {
+		return "Number";
+	}
+	if (/^Enum\./.test(value)) {
+		return "EnumItem";
+	}
+	if (/^['"`]/.test(value)) {
+		return "String";
+	}
+	return "Unknown";
+}
+
+export function typeToClpp(type: CanonicalType): string {
+	switch (type.kind) {
+		case "Primitive":
+			if (type.name === "boolean") {
+				return "bool";
+			}
+			if (type.name === "void") {
+				return "void";
+			}
+			return type.name;
+		case "Class":
+		case "Datatype":
+			return type.name;
+		case "Enum":
+			return `Enum::${type.name}`;
+		case "Optional":
+			return `${typeToClpp(type.inner)}?`;
+		case "Array":
+			return `array<${typeToClpp(type.element)}>`;
+		case "Dictionary":
+		case "Map":
+			return `dictionary<${typeToClpp(type.key)}, ${typeToClpp(type.value)}>`;
+		case "Tuple":
+			return `tuple<${type.elements.map(typeToClpp).join(", ")}>`;
+		case "Function":
+			return "func";
+		case "Union":
+			return type.members.map(typeToClpp).join(" | ");
+		case "Buffer":
+			return "buffer";
+		case "Any":
+			return "auto";
+		case "Unknown":
+			return "auto";
+		case "Never":
+			return "void";
+		case "Unsupported":
+			return "auto";
+		default:
+			return "auto";
+	}
+}
+
+export function typeToLuau(type: CanonicalType): string {
+	switch (type.kind) {
+		case "Primitive":
+			if (type.name === "int" || type.name === "int64" || type.name === "float" || type.name === "double") {
+				return "number";
+			}
+			if (type.name === "void") {
+				return "()";
+			}
+			return type.name;
+		case "Class":
+		case "Datatype":
+			return type.name;
+		case "Enum":
+			return `Enum.${type.name}`;
+		case "Optional":
+			return `${typeToLuau(type.inner)}?`;
+		case "Array":
+			return `{ ${typeToLuau(type.element)} }`;
+		case "Dictionary":
+		case "Map":
+			return `{ [${typeToLuau(type.key)}]: ${typeToLuau(type.value)} }`;
+		case "Buffer":
+			return "buffer";
+		case "Any":
+			return "any";
+		case "Unknown":
+			return "unknown";
+		case "Function":
+			return "(...any) -> ...any";
+		case "Unsupported":
+			return "any";
+		default:
+			return "any";
+	}
+}
+
+export function eventSignalType(parameters: ParameterDefinition[]): CanonicalType {
+	return {
+		kind: "Datatype",
+		name: parameters.length
+			? `RBXScriptSignal/*(${parameters.map((p) => typeToClpp(p.type)).join(", ")})*/`
+			: "RBXScriptSignal",
+	};
+}

package/src/api/sources/aux-types-diff.ts

@@ -0,0 +1,81 @@
+/**
+ * Optional coverage cross-check against @rbxts/types or LuauTypes.
+ * Never imported by the compile hot path.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+export interface AuxTypesDiff {
+	source: string;
+	auxSymbols: number;
+	registrySymbols: number;
+	onlyInAux: string[];
+	onlyInRegistry: string[];
+}
+
+function collectDeclareClasses(text: string): Set<string> {
+	const names = new Set<string>();
+	const re = /\b(?:declare\s+class|export\s+type|interface|type)\s+([A-Za-z_][\w]*)/g;
+	let match: RegExpExecArray | null;
+	while ((match = re.exec(text))) {
+		names.add(match[1]);
+	}
+	return names;
+}
+
+/**
+ * Diff registry class/datatype/enum names against a local types file or directory
+ * (e.g. node_modules/@rbxts/types or Studio LuauTypes.d.luau).
+ */
+export function diffAgainstAuxTypes(
+	registryNames: string[],
+	auxPath: string,
+): AuxTypesDiff {
+	if (!fs.existsSync(auxPath)) {
+		throw new Error(`Aux types path not found: ${auxPath}`);
+	}
+	const stat = fs.statSync(auxPath);
+	let auxSet: Set<string>;
+	if (stat.isDirectory()) {
+		auxSet = new Set<string>();
+		const stack = [auxPath];
+		while (stack.length) {
+			const dir = stack.pop()!;
+			for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+				const full = path.join(dir, entry.name);
+				if (entry.isDirectory()) {
+					stack.push(full);
+				} else if (/\.(luau|ts|d\.ts)$/i.test(entry.name)) {
+					for (const name of collectDeclareClasses(fs.readFileSync(full, "utf8"))) {
+						auxSet.add(name);
+					}
+				}
+			}
+		}
+	} else {
+		auxSet = collectDeclareClasses(fs.readFileSync(auxPath, "utf8"));
+	}
+
+	const regSet = new Set(registryNames);
+	const onlyInAux: string[] = [];
+	const onlyInRegistry: string[] = [];
+	for (const name of auxSet) {
+		if (!regSet.has(name)) {
+			onlyInAux.push(name);
+		}
+	}
+	for (const name of regSet) {
+		if (!auxSet.has(name)) {
+			onlyInRegistry.push(name);
+		}
+	}
+	onlyInAux.sort();
+	onlyInRegistry.sort();
+	return {
+		source: auxPath,
+		auxSymbols: auxSet.size,
+		registrySymbols: regSet.size,
+		onlyInAux,
+		onlyInRegistry,
+	};
+}

package/src/api/sources/client-tracker.ts

@@ -0,0 +1,10 @@
+import type { LoadedSource } from "../loader.js";
+import { loadJsonFile } from "../loader.js";
+
+/**
+ * Optional Client Tracker adapter (non-authoritative early-diff source).
+ * Pass a local API-Dump.json / Full-API-Dump.json checkout path.
+ */
+export function loadClientTrackerDump(filePath: string): LoadedSource<unknown> {
+	return loadJsonFile("client-tracker", filePath);
+}

package/src/api/sources/creator-docs.ts

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+import { hashBuffer } from "../resolver.js";
+import type { LoadedSource } from "../loader.js";
+
+/**
+ * Creator Docs engine reference walker.
+ * Expects a local clone of Roblox/creator-docs (or a fixture subtree).
+ */
+export function loadCreatorDocs(rootDir: string): LoadedSource<{ pages: string[] }> {
+	if (!fs.existsSync(rootDir)) {
+		throw new Error(`Creator Docs root not found: ${rootDir}`);
+	}
+	const pages: string[] = [];
+	const stack = [rootDir];
+	while (stack.length) {
+		const dir = stack.pop()!;
+		for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+			const full = path.join(dir, entry.name);
+			if (entry.isDirectory()) {
+				stack.push(full);
+			} else if (/\.(md|mdx|yaml|yml)$/i.test(entry.name)) {
+				pages.push(path.relative(rootDir, full).replace(/\\/g, "/"));
+			}
+		}
+	}
+	pages.sort();
+	return {
+		meta: {
+			id: "creator-docs",
+			path: rootDir,
+			hash: hashBuffer(pages.join("\n")),
+			loadedAt: new Date().toISOString(),
+		},
+		data: { pages },
+	};
+}

package/src/api/sources/luau-types.ts

@@ -0,0 +1,30 @@
+import fs from "node:fs";
+import { hashBuffer } from "../resolver.js";
+import type { LoadedSource } from "../loader.js";
+
+/**
+ * Parse LuauTypes.d.luau into a lightweight symbol index.
+ * Full type AST is deferred; we extract declare/class/type names for cross-check.
+ */
+export function loadLuauTypes(filePath: string): LoadedSource<{ symbols: string[]; textHash: string }> {
+	if (!fs.existsSync(filePath)) {
+		throw new Error(`LuauTypes file not found: ${filePath}`);
+	}
+	const raw = fs.readFileSync(filePath);
+	const text = raw.toString("utf8");
+	const symbols = new Set<string>();
+	const declareRe = /\b(?:declare|type|export type|class)\s+([A-Za-z_][\w.]*)/g;
+	let match: RegExpExecArray | null;
+	while ((match = declareRe.exec(text))) {
+		symbols.add(match[1].split(".")[0]);
+	}
+	return {
+		meta: {
+			id: "luau-types",
+			path: filePath,
+			hash: hashBuffer(raw),
+			loadedAt: new Date().toISOString(),
+		},
+		data: { symbols: [...symbols].sort(), textHash: hashBuffer(raw) },
+	};
+}

package/src/api/sources/mini-dump.ts

@@ -0,0 +1,50 @@
+import path from "node:path";
+import { projectRoot } from "../../package-info.js";
+import { loadJsonFile, type LoadedSource } from "../loader.js";
+
+export interface MiniDumpParameter {
+	Name?: string;
+	Type?: { Category?: string; Name?: string; Optional?: boolean };
+	Default?: string;
+}
+
+export interface MiniDumpMember {
+	MemberType: string;
+	Name: string;
+	ValueType?: { Category?: string; Name?: string; Optional?: boolean };
+	ReturnType?: { Category?: string; Name?: string; Optional?: boolean };
+	Parameters?: MiniDumpParameter[];
+	Tags?: Array<string | Record<string, unknown>>;
+	Security?: string | { Read?: string; Write?: string };
+	ThreadSafety?: string;
+	Default?: string;
+	Category?: string;
+}
+
+export interface MiniDumpClass {
+	Name: string;
+	Superclass?: string;
+	Tags?: Array<string | Record<string, unknown>>;
+	Members?: MiniDumpMember[];
+	MemoryCategory?: string;
+}
+
+export interface MiniDumpEnum {
+	Name: string;
+	Items?: Array<{ Name: string; Value: number }>;
+}
+
+export interface MiniApiDump {
+	Classes: MiniDumpClass[];
+	Enums: MiniDumpEnum[];
+	Version?: number | string;
+}
+
+export function loadMiniDump(filePath?: string): LoadedSource<MiniApiDump> {
+	const target = filePath || path.join(projectRoot, "data", "Mini-API-Dump.json");
+	const loaded = loadJsonFile<MiniApiDump>("mini-api-dump", target);
+	if (!Array.isArray(loaded.data.Classes) || !Array.isArray(loaded.data.Enums)) {
+		throw new Error("Mini-API-Dump.json missing Classes/Enums arrays");
+	}
+	return loaded;
+}

package/src/api/sources/studio-api.ts

@@ -0,0 +1,7 @@
+import type { LoadedSource } from "../loader.js";
+import { loadJsonFile } from "../loader.js";
+
+/** Studio --api JSON (same shape family as Mini dump when exported). */
+export function loadStudioApi(filePath: string): LoadedSource<unknown> {
+	return loadJsonFile("studio-api", filePath);
+}

package/src/api/sources/studio-apiv2.ts

@@ -0,0 +1,10 @@
+import type { LoadedSource } from "../loader.js";
+import { loadJsonFile } from "../loader.js";
+
+/**
+ * Studio --apiV2 JSON export — preferred canonical schema when available.
+ * Until a fixture is checked in, callers may pass a local Studio dump path.
+ */
+export function loadStudioApiV2(filePath: string): LoadedSource<unknown> {
+	return loadJsonFile("studio-api-v2", filePath);
+}