cluaupp 1.5.0 → 1.5.1

package/src/api/model.ts

@@ -0,0 +1,283 @@
+/** Canonical Roblox API model for Cluaupp (RobloxTargetProfile schemaVersion 2). */
+
+export const ROBLOX_TARGET_SCHEMA_VERSION = 2 as const;
+
+export type CanonicalTypeKind =
+	| "Primitive"
+	| "Class"
+	| "Enum"
+	| "Datatype"
+	| "Array"
+	| "Dictionary"
+	| "Map"
+	| "Tuple"
+	| "Function"
+	| "Union"
+	| "Intersection"
+	| "Optional"
+	| "GenericParameter"
+	| "TypePack"
+	| "Singleton"
+	| "Unknown"
+	| "Any"
+	| "Never"
+	| "Buffer"
+	| "Vector"
+	| "Unsupported";
+
+export type CanonicalType =
+	| { kind: "Primitive"; name: string }
+	| { kind: "Class"; name: string }
+	| { kind: "Enum"; name: string }
+	| { kind: "Datatype"; name: string }
+	| { kind: "Array"; element: CanonicalType }
+	| { kind: "Dictionary"; key: CanonicalType; value: CanonicalType }
+	| { kind: "Map"; key: CanonicalType; value: CanonicalType }
+	| { kind: "Tuple"; elements: CanonicalType[] }
+	| { kind: "Function"; parameters: CanonicalType[]; returns: CanonicalType[]; variadic?: boolean }
+	| { kind: "Union"; members: CanonicalType[] }
+	| { kind: "Intersection"; members: CanonicalType[] }
+	| { kind: "Optional"; inner: CanonicalType }
+	| { kind: "GenericParameter"; name: string }
+	| { kind: "TypePack"; name: string }
+	| { kind: "Singleton"; value: string | number | boolean }
+	| { kind: "Unknown" }
+	| { kind: "Any" }
+	| { kind: "Never" }
+	| { kind: "Buffer" }
+	| { kind: "Vector" }
+	| { kind: "Unsupported"; raw: string; reason: string };
+
+export type DefaultKind = "Null" | "Boolean" | "Number" | "String" | "EnumItem" | "Literal" | "Unknown";
+
+export interface ParameterDefinition {
+	name: string;
+	type: CanonicalType;
+	optional: boolean;
+	default?: string;
+	defaultKind?: DefaultKind;
+}
+
+export type ThreadSafety = "Unsafe" | "ReadSafe" | "LocalSafe" | "Safe" | "Unknown";
+
+export interface SecurityPair {
+	read?: string;
+	write?: string;
+	call?: string;
+	listen?: string;
+	create?: string;
+}
+
+export interface DeprecationInfo {
+	deprecated: boolean;
+	message?: string;
+	replacement?: string;
+}
+
+export interface PropertyDefinition {
+	name: string;
+	owner: string;
+	valueType: CanonicalType;
+	readable: boolean;
+	writable: boolean;
+	readSecurity?: string;
+	writeSecurity?: string;
+	/** Roblox Parallel Luau thread safety (from API dump). */
+	threadSafety?: ThreadSafety;
+	tags: string[];
+	defaultValue?: string;
+	description?: string;
+	deprecated?: DeprecationInfo;
+}
+
+export interface MethodDefinition {
+	name: string;
+	owner: string;
+	overloadIndex: number;
+	parameters: ParameterDefinition[];
+	returnTypes: CanonicalType[];
+	canYield: boolean;
+	security?: string;
+	threadSafety?: ThreadSafety;
+	tags: string[];
+	deprecated?: DeprecationInfo;
+	description?: string;
+}
+
+export interface EventDefinition {
+	name: string;
+	owner: string;
+	parameters: ParameterDefinition[];
+	listenSecurity?: string;
+	threadSafety?: ThreadSafety;
+	tags: string[];
+	description?: string;
+	deprecated?: DeprecationInfo;
+}
+
+export interface CallbackDefinition {
+	name: string;
+	owner: string;
+	parameters: ParameterDefinition[];
+	returnTypes: CanonicalType[];
+	canYield: boolean;
+	security?: string;
+	threadSafety?: ThreadSafety;
+	tags: string[];
+	description?: string;
+	deprecated?: DeprecationInfo;
+}
+
+export interface ConstructorDefinition {
+	owner: string;
+	overloadIndex: number;
+	parameters: ParameterDefinition[];
+	tags: string[];
+}
+
+export type CreationKind = "creatable" | "service" | "abstract" | "pluginOnly" | "unknown";
+
+export interface CreationPolicy {
+	kind: CreationKind;
+	creatable: boolean;
+	service: boolean;
+	abstract: boolean;
+	pluginOnly: boolean;
+	security?: string;
+	notes?: string;
+}
+
+export interface ClassDefinition {
+	name: string;
+	superclass: string | null;
+	subclasses: string[];
+	tags: string[];
+	description?: string;
+	deprecated?: DeprecationInfo;
+	security?: SecurityPair;
+	creatable: boolean;
+	service: boolean;
+	preferredParent?: string;
+	creation: CreationPolicy;
+	properties: PropertyDefinition[];
+	methods: MethodDefinition[];
+	events: EventDefinition[];
+	callbacks: CallbackDefinition[];
+	constructors: ConstructorDefinition[];
+}
+
+export interface EnumItemDefinition {
+	name: string;
+	numericValue: number;
+	description?: string;
+	tags: string[];
+	deprecated?: DeprecationInfo;
+}
+
+export interface EnumDefinition {
+	name: string;
+	description?: string;
+	items: EnumItemDefinition[];
+	tags: string[];
+}
+
+export interface DatatypeDefinition {
+	name: string;
+	summary?: string;
+	fields: Array<{ name: string; type: CanonicalType }>;
+	constructors: ConstructorDefinition[];
+	staticProperties: string[];
+	staticMethods: MethodDefinition[];
+	instanceMethods: MethodDefinition[];
+	source: "dump" | "override" | "inferred";
+}
+
+export interface ServiceDefinition {
+	name: string;
+	className: string;
+	kind: "service";
+	accessor: string;
+	singleton: true;
+	type: CanonicalType;
+}
+
+export interface GlobalDefinition {
+	name: string;
+	type: CanonicalType;
+	layer: "luau-core" | "roblox-engine" | "cluaupp-runtime";
+	description?: string;
+}
+
+export interface LibraryDefinition {
+	name: string;
+	layer: "luau-core" | "roblox-engine" | "cluaupp-runtime";
+	bind?: string;
+	file?: string;
+}
+
+export interface UnsupportedRepresentation {
+	symbol: string;
+	source: string;
+	reason: string;
+	fallback: string;
+	severity: "error" | "warning" | "info";
+}
+
+export interface SourceMeta {
+	id: string;
+	path?: string;
+	hash: string;
+	loadedAt: string;
+	version?: string | number;
+}
+
+export interface RobloxTargetProfile {
+	target: "roblox";
+	schemaVersion: typeof ROBLOX_TARGET_SCHEMA_VERSION;
+	robloxApiVersion?: string;
+	studioVersion?: string;
+	generatorVersion: string;
+	sources: Record<string, SourceMeta>;
+	classes: Record<string, ClassDefinition>;
+	enums: Record<string, EnumDefinition>;
+	datatypes: Record<string, DatatypeDefinition>;
+	globals: Record<string, GlobalDefinition>;
+	libraries: Record<string, LibraryDefinition>;
+	services: Record<string, ServiceDefinition>;
+	aliases: Record<string, string>;
+	constructors: Record<string, ConstructorDefinition[]>;
+	security: Record<string, SecurityPair>;
+	deprecations: Record<string, DeprecationInfo>;
+	unsupported: UnsupportedRepresentation[];
+}
+
+export interface OverrideEntry {
+	reason: string;
+	source: string;
+	introducedAt: string;
+	reviewAfter?: string;
+}
+
+export type DiffKind =
+	| "ADDED_CLASS"
+	| "REMOVED_CLASS"
+	| "CHANGED_SUPERCLASS"
+	| "ADDED_PROPERTY"
+	| "REMOVED_PROPERTY"
+	| "CHANGED_PROPERTY_TYPE"
+	| "ADDED_METHOD_OVERLOAD"
+	| "REMOVED_METHOD_OVERLOAD"
+	| "ADDED_EVENT"
+	| "CHANGED_EVENT_SIGNATURE"
+	| "ADDED_ENUM"
+	| "REMOVED_ENUM"
+	| "ADDED_ENUM_ITEM"
+	| "REMOVED_ENUM_ITEM"
+	| "DEPRECATED_MEMBER";
+
+export interface ApiDiffEntry {
+	kind: DiffKind;
+	symbol: string;
+	oldValue?: string;
+	newValue?: string;
+}

package/src/api/normalize.ts

@@ -0,0 +1,257 @@
+import type {
+	CallbackDefinition,
+	CanonicalType,
+	ClassDefinition,
+	CreationPolicy,
+	EnumDefinition,
+	EventDefinition,
+	MethodDefinition,
+	ParameterDefinition,
+	PropertyDefinition,
+	ThreadSafety,
+	UnsupportedRepresentation,
+} from "./model.js";
+import { mapParameter, mapRobloxType } from "./resolver.js";
+import type { MiniApiDump, MiniDumpClass, MiniDumpMember } from "./sources/mini-dump.js";
+
+function tagsOf(member: MiniDumpMember | MiniDumpClass): string[] {
+	return Array.isArray(member.Tags)
+		? member.Tags.map((t) => (typeof t === "string" ? t : String((t as { PreferredDescriptorName?: string }).PreferredDescriptorName || JSON.stringify(t))))
+		: [];
+}
+
+function hasTag(tags: string[], tag: string): boolean {
+	return tags.some((t) => t.toLowerCase() === tag.toLowerCase());
+}
+
+function securityString(sec: MiniDumpMember["Security"]): string | undefined {
+	if (!sec) {
+		return undefined;
+	}
+	if (typeof sec === "string") {
+		return sec;
+	}
+	return sec.Read || sec.Write;
+}
+
+function mapThreadSafety(raw: string | undefined): ThreadSafety | undefined {
+	if (!raw) {
+		return undefined;
+	}
+	switch (raw) {
+		case "Unsafe":
+		case "ReadSafe":
+		case "LocalSafe":
+		case "Safe":
+			return raw;
+		default:
+			return "Unknown";
+	}
+}
+
+function creationPolicy(tags: string[]): CreationPolicy {
+	const service = hasTag(tags, "Service");
+	const notCreatable = hasTag(tags, "NotCreatable");
+	const deprecated = hasTag(tags, "Deprecated");
+	const pluginOnly = hasTag(tags, "PluginSecurity") || hasTag(tags, "NotBrowsable");
+	return {
+		kind: service ? "service" : notCreatable ? "abstract" : "creatable",
+		creatable: !notCreatable && !service,
+		service,
+		abstract: notCreatable && !service,
+		pluginOnly,
+		notes: deprecated ? "deprecated" : undefined,
+	};
+}
+
+function parseParams(member: MiniDumpMember): ParameterDefinition[] {
+	return (member.Parameters || []).map((p, i) => mapParameter(p, i));
+}
+
+function returnTypes(member: MiniDumpMember): CanonicalType[] {
+	if (member.ReturnType) {
+		return [mapRobloxType(member.ReturnType)];
+	}
+	return [{ kind: "Primitive", name: "void" }];
+}
+
+function collectUnsupported(type: CanonicalType, symbol: string, unsupported: UnsupportedRepresentation[]): void {
+	if (type.kind === "Unsupported") {
+		unsupported.push({
+			symbol,
+			source: "mini-api-dump",
+			reason: type.reason,
+			fallback: "auto",
+			severity: "warning",
+		});
+	} else if (type.kind === "Optional") {
+		collectUnsupported(type.inner, symbol, unsupported);
+	} else if (type.kind === "Array") {
+		collectUnsupported(type.element, symbol, unsupported);
+	} else if (type.kind === "Dictionary" || type.kind === "Map") {
+		collectUnsupported(type.key, symbol, unsupported);
+		collectUnsupported(type.value, symbol, unsupported);
+	} else if (type.kind === "Union" || type.kind === "Intersection" || type.kind === "Tuple") {
+		const members = type.kind === "Tuple" ? type.elements : type.members;
+		for (const m of members) {
+			collectUnsupported(m, symbol, unsupported);
+		}
+	}
+}
+
+function normalizeClass(raw: MiniDumpClass, unsupported: UnsupportedRepresentation[]): ClassDefinition {
+	const tags = tagsOf(raw);
+	const creation = creationPolicy(tags);
+	const properties: PropertyDefinition[] = [];
+	const methods: MethodDefinition[] = [];
+	const events: EventDefinition[] = [];
+	const callbacks: CallbackDefinition[] = [];
+	const methodOverloads = new Map<string, number>();
+
+	for (const member of raw.Members || []) {
+		const mTags = tagsOf(member);
+		const deprecated = hasTag(mTags, "Deprecated")
+			? { deprecated: true as const, message: "Deprecated in Roblox API dump" }
+			: undefined;
+		const symbol = `${raw.Name}.${member.Name}`;
+
+		switch (member.MemberType) {
+			case "Property": {
+				const valueType = mapRobloxType(member.ValueType);
+				collectUnsupported(valueType, symbol, unsupported);
+				const sec = typeof member.Security === "object" ? member.Security : undefined;
+				properties.push({
+					name: member.Name,
+					owner: raw.Name,
+					valueType,
+					readable: !hasTag(mTags, "WriteOnly"),
+					writable: !hasTag(mTags, "ReadOnly"),
+					readSecurity: sec?.Read || (typeof member.Security === "string" ? member.Security : undefined),
+					writeSecurity: sec?.Write,
+					threadSafety: mapThreadSafety(member.ThreadSafety),
+					tags: mTags,
+					defaultValue: member.Default,
+					deprecated,
+				});
+				break;
+			}
+			case "Function":
+			case "Method": {
+				const idx = methodOverloads.get(member.Name) || 0;
+				methodOverloads.set(member.Name, idx + 1);
+				const parameters = parseParams(member);
+				const returns = returnTypes(member);
+				for (const p of parameters) {
+					collectUnsupported(p.type, `${symbol}(${p.name})`, unsupported);
+				}
+				for (const r of returns) {
+					collectUnsupported(r, `${symbol}:return`, unsupported);
+				}
+				methods.push({
+					name: member.Name,
+					owner: raw.Name,
+					overloadIndex: idx,
+					parameters,
+					returnTypes: returns,
+					canYield: hasTag(mTags, "Yields") || hasTag(mTags, "CanYield"),
+					security: securityString(member.Security),
+					threadSafety: mapThreadSafety(member.ThreadSafety),
+					tags: mTags,
+					deprecated,
+				});
+				break;
+			}
+			case "Event": {
+				const parameters = parseParams(member);
+				for (const p of parameters) {
+					collectUnsupported(p.type, `${symbol}(${p.name})`, unsupported);
+				}
+				events.push({
+					name: member.Name,
+					owner: raw.Name,
+					parameters,
+					listenSecurity: securityString(member.Security),
+					threadSafety: mapThreadSafety(member.ThreadSafety),
+					tags: mTags,
+					deprecated,
+				});
+				break;
+			}
+			case "Callback": {
+				const parameters = parseParams(member);
+				const returns = returnTypes(member);
+				callbacks.push({
+					name: member.Name,
+					owner: raw.Name,
+					parameters,
+					returnTypes: returns,
+					canYield: hasTag(mTags, "Yields"),
+					security: securityString(member.Security),
+					threadSafety: mapThreadSafety(member.ThreadSafety),
+					tags: mTags,
+					deprecated,
+				});
+				break;
+			}
+			default:
+				unsupported.push({
+					symbol,
+					source: "mini-api-dump",
+					reason: `Unhandled MemberType ${member.MemberType}`,
+					fallback: "skip",
+					severity: "info",
+				});
+		}
+	}
+
+	return {
+		name: raw.Name,
+		superclass: raw.Superclass && raw.Superclass !== "<<<ROOT>>>" ? raw.Superclass : null,
+		subclasses: [],
+		tags,
+		deprecated: hasTag(tags, "Deprecated") ? { deprecated: true } : undefined,
+		creatable: creation.creatable,
+		service: creation.service,
+		creation,
+		properties,
+		methods,
+		events,
+		callbacks,
+		constructors: [],
+	};
+}
+
+export function normalizeMiniDump(dump: MiniApiDump): {
+	classes: Record<string, ClassDefinition>;
+	enums: Record<string, EnumDefinition>;
+	unsupported: UnsupportedRepresentation[];
+} {
+	const unsupported: UnsupportedRepresentation[] = [];
+	const classes: Record<string, ClassDefinition> = {};
+	for (const raw of dump.Classes) {
+		classes[raw.Name] = normalizeClass(raw, unsupported);
+	}
+	for (const cls of Object.values(classes)) {
+		if (cls.superclass && classes[cls.superclass]) {
+			classes[cls.superclass].subclasses.push(cls.name);
+		}
+	}
+	for (const cls of Object.values(classes)) {
+		cls.subclasses.sort();
+	}
+
+	const enums: Record<string, EnumDefinition> = {};
+	for (const e of dump.Enums) {
+		enums[e.Name] = {
+			name: e.Name,
+			items: (e.Items || []).map((item) => ({
+				name: item.Name,
+				numericValue: item.Value,
+				tags: [],
+			})),
+			tags: [],
+		};
+	}
+
+	return { classes, enums, unsupported };
+}

package/src/api/overrides-validate.ts

@@ -0,0 +1,58 @@
+import fs from "node:fs";
+import path from "node:path";
+import { projectRoot } from "../package-info.js";
+import type { OverrideEntry } from "./model.js";
+
+export interface OverrideValidationIssue {
+	file: string;
+	message: string;
+}
+
+/** Validate override JSON files carry audit metadata. */
+export function validateOverrides(): OverrideValidationIssue[] {
+	const dir = path.join(projectRoot, "api", "overrides");
+	const issues: OverrideValidationIssue[] = [];
+	if (!fs.existsSync(dir)) {
+		return [{ file: "api/overrides", message: "overrides directory missing" }];
+	}
+	for (const name of fs.readdirSync(dir).sort()) {
+		if (!name.endsWith(".json")) {
+			continue;
+		}
+		const full = path.join(dir, name);
+		const parsed = JSON.parse(fs.readFileSync(full, "utf8")) as { _meta?: OverrideEntry };
+		if (!parsed._meta) {
+			issues.push({ file: name, message: "missing _meta" });
+			continue;
+		}
+		for (const key of ["reason", "source", "introducedAt"] as const) {
+			if (!parsed._meta[key]) {
+				issues.push({ file: name, message: `missing _meta.${key}` });
+			}
+		}
+	}
+	return issues;
+}
+
+export function diffOverrideFiles(beforeDir: string, afterDir: string): string[] {
+	const before = new Set(fs.existsSync(beforeDir) ? fs.readdirSync(beforeDir).filter((f) => f.endsWith(".json")) : []);
+	const after = new Set(fs.existsSync(afterDir) ? fs.readdirSync(afterDir).filter((f) => f.endsWith(".json")) : []);
+	const changes: string[] = [];
+	for (const f of after) {
+		if (!before.has(f)) {
+			changes.push(`ADDED ${f}`);
+		} else {
+			const a = fs.readFileSync(path.join(beforeDir, f), "utf8");
+			const b = fs.readFileSync(path.join(afterDir, f), "utf8");
+			if (a !== b) {
+				changes.push(`CHANGED ${f}`);
+			}
+		}
+	}
+	for (const f of before) {
+		if (!after.has(f)) {
+			changes.push(`REMOVED ${f}`);
+		}
+	}
+	return changes;
+}

package/src/api/perf.ts

@@ -0,0 +1,15 @@
+/** Cold/warm timing helpers for API generate / LSP-ish lookups. */
+export interface PerfSample {
+	label: string;
+	ms: number;
+}
+
+export function timeCall<T>(label: string, fn: () => T): { value: T; sample: PerfSample } {
+	const started = Date.now();
+	const value = fn();
+	return { value, sample: { label, ms: Date.now() - started } };
+}
+
+export function formatPerf(samples: PerfSample[]): string {
+	return samples.map((s) => `${s.label}=${s.ms}ms`).join(" ");
+}