cluaupp 1.4.1 → 1.5.1

package/src/api/identifier.ts

@@ -0,0 +1,47 @@
+/** Deterministic identifier escaping for CL++ headers. */
+
+const CLPP_RESERVED = new Set([
+	"alignas", "alignof", "and", "and_eq", "asm", "auto", "bitand", "bitor", "bool", "break",
+	"case", "catch", "char", "class", "compl", "concept", "const", "consteval", "constexpr",
+	"const_cast", "continue", "co_await", "co_return", "co_yield", "decltype", "default",
+	"delete", "do", "double", "dynamic_cast", "else", "enum", "explicit", "export", "extern",
+	"false", "float", "for", "friend", "goto", "if", "inline", "int", "long", "mutable",
+	"namespace", "new", "noexcept", "not", "not_eq", "nullptr", "operator", "or", "or_eq",
+	"private", "protected", "public", "register", "reinterpret_cast", "requires", "return",
+	"short", "signed", "sizeof", "static", "static_assert", "static_cast", "struct", "switch",
+	"template", "this", "thread_local", "throw", "true", "try", "typedef", "typeid", "typename",
+	"union", "unsigned", "using", "virtual", "void", "volatile", "wchar_t", "xor", "xor_eq",
+	"NULL", "string",
+]);
+
+const MEMBER_COLLISIONS: Record<string, Set<string>> = {
+	Instance: new Set(["class"]),
+};
+
+export function escapeIdent(name: string): string {
+	let out = String(name || "");
+	if (!out) {
+		return "_";
+	}
+	if (/^\d/.test(out)) {
+		out = `_${out}`;
+	}
+	out = out.replace(/[^A-Za-z0-9_]/g, "_");
+	if (CLPP_RESERVED.has(out)) {
+		out = `${out}_`;
+	}
+	return out;
+}
+
+export function escapeMember(owner: string, name: string): string {
+	const escaped = escapeIdent(name);
+	const collisions = MEMBER_COLLISIONS[owner];
+	if (collisions?.has(name) || collisions?.has(escaped)) {
+		return `${escaped}_`;
+	}
+	return escaped;
+}
+
+export function isReserved(name: string): boolean {
+	return CLPP_RESERVED.has(name);
+}

package/src/api/index.ts

@@ -0,0 +1,269 @@
+import fs from "node:fs";
+import path from "node:path";
+import { projectRoot } from "../package-info.js";
+import { pkg } from "../package-info.js";
+import { buildRobloxTargetProfile, profileContentHash, writeProfileCache } from "./build-profile.js";
+import { computeCoverage } from "./coverage.js";
+import { diffProfiles } from "./diff.js";
+import { generateClppHeaders } from "./generators/clpp-headers.js";
+import { generateLuauDefs, tryLuauAnalyze } from "./generators/luau-defs.js";
+import { generateReferenceDocs } from "./generators/docs-reference.js";
+import { writeLspIndex } from "./generators/lsp-index.js";
+import { writeCapabilityProfile } from "../target/capability-profile.js";
+import { overridesHash } from "./loader.js";
+import type { RobloxTargetProfile } from "./model.js";
+import { ROBLOX_TARGET_SCHEMA_VERSION } from "./model.js";
+import { buildRegistry, searchRegistry } from "./registry.js";
+import { hashBuffer } from "./resolver.js";
+import { validateProfile } from "./validate.js";
+
+export * from "./model.js";
+export * from "./resolver.js";
+export * from "./identifier.js";
+export * from "./registry.js";
+export * from "./diff.js";
+export * from "./coverage.js";
+export { buildRobloxTargetProfile, writeProfileCache, profileContentHash } from "./build-profile.js";
+export { generateClppHeaders } from "./generators/clpp-headers.js";
+export { generateLuauDefs } from "./generators/luau-defs.js";
+export { generateReferenceDocs } from "./generators/docs-reference.js";
+export { buildLspIndex, writeLspIndex, LSP_INDEX_SCHEMA_VERSION } from "./generators/lsp-index.js";
+export { loadMiniDump } from "./sources/mini-dump.js";
+export { loadStudioApi } from "./sources/studio-api.js";
+export { loadStudioFullApi } from "./sources/studio-full-api.js";
+export { loadStudioApiV2 } from "./sources/studio-apiv2.js";
+export { loadLuauTypes } from "./sources/luau-types.js";
+export { loadCreatorDocs } from "./sources/creator-docs.js";
+export { loadClientTrackerDump } from "./sources/client-tracker.js";
+export { diffAgainstAuxTypes } from "./sources/aux-types-diff.js";
+export { escapeIdent, escapeMember, isReserved } from "./identifier.js";
+export {
+	listMembers,
+	describeSymbol,
+	similarSymbols,
+	completeMember,
+	hoverSymbol,
+	suggestDidYouMean,
+	getApiRegistry,
+} from "./ide.js";
+export { runStudioSmoke, RUNTIME_SUITE } from "./studio-smoke.js";
+export { matchIntents, understandSymbol, INTENT_RULES } from "./understander.js";
+export { computeCacheKey, cacheKeyHash, readCache, writeCache } from "./cache.js";
+export { resolveGetServiceType, runContextFromFileName, defaultRobloxProject, isRegisteredService } from "../target/roblox.js";
+export { checkGetService, assertGetServiceSafe, collectGetServiceUses, rewriteGetServiceLuau } from "../target/get-service.js";
+export { builtinCapabilityProfile, capabilitiesForContext, CAPABILITY_PROFILE_SCHEMA_VERSION } from "../target/capabilities.js";
+export { checkContextSafety, assertContextSafe, stripNoise } from "../target/context-check.js";
+export { writeCapabilityProfile, loadCapabilityProfile, capabilityProfilePath } from "../target/capability-profile.js";
+export {
+	buildDatamodelProfile,
+	findProjectJson,
+	DATAMODEL_SCHEMA_VERSION,
+} from "../target/datamodel.js";
+export { checkDatamodelPaths, assertDatamodelSafe } from "../target/datamodel-check.js";
+export { writeDatamodelArtifacts, generateDatamodelHeader } from "../target/datamodel-generate.js";
+export { checkParallelSafety, assertParallelSafe } from "../target/parallel-check.js";
+export { checkAuthority, assertAuthoritySafe, loadPlatformPolicy } from "../target/authority-check.js";
+export { checkAuthorityGraph } from "../target/authority-graph.js";
+export { checkComponentContracts } from "../target/component-contracts.js";
+export { checkSecurity } from "../target/security-check.js";
+export { checkLifetime } from "../target/lifetime-check.js";
+export { adviseOptimizer, adviceAsDiagnostics } from "../target/optimizer-advise.js";
+export { buildProjectGraph } from "../target/project-graph.js";
+export { checkFlareVersions } from "../target/flare-version.js";
+export { writeSourceMap } from "../target/source-map.js";
+export { stampLuauFromClpp } from "../target/luau-stamp.js";
+export { runDoctor } from "../target/doctor.js";
+export { applyOptimizerHints } from "../target/optimizer-apply.js";
+export {
+	generateSoaLuau,
+	applyLayoutPragmas,
+	writeSoaArtifacts,
+	collectSoaPlansFromProject,
+	planSoa,
+	listLayoutTargets,
+} from "../target/optimizer-soa.js";
+export { startStudioBridge, BRIDGE_DEFAULT_PORT } from "../target/studio-bridge.js";
+export {
+	loadProfile,
+	writeProfileTemplate,
+	rankAdvice,
+	defaultProfilePath,
+	ingestProfile,
+	PGO_SCHEMA_VERSION,
+} from "../target/pgo.js";
+export { generateProjectDocs } from "../target/project-docs.js";
+export {
+	fingerprintSource,
+	readCachedJob,
+	writeCachedJob,
+	mapPool,
+	defaultJobCount,
+	COMPILE_CACHE_SCHEMA,
+} from "../target/build-cache.js";
+export { buildReleaseChecklist, writeApiChangelog } from "./release.js";
+export { timeCall, formatPerf } from "./perf.js";
+export { validateOverrides, diffOverrideFiles } from "./overrides-validate.js";
+
+export interface ManifestDocument {
+	schemaVersion: typeof ROBLOX_TARGET_SCHEMA_VERSION;
+	generatorVersion: string;
+	profileHash: string;
+	overridesHash: string;
+	sources: RobloxTargetProfile["sources"];
+	generatedAt: string;
+}
+
+export interface LockDocument {
+	schemaVersion: typeof ROBLOX_TARGET_SCHEMA_VERSION;
+	profileHash: string;
+	overridesHash: string;
+	robloxApiVersion?: string;
+	files: Record<string, string>;
+}
+
+export function generateAll(options: {
+	dumpPath?: string;
+	skipHeaders?: boolean;
+	skipLuau?: boolean;
+	skipDocs?: boolean;
+	skipLspIndex?: boolean;
+} = {}): {
+	profile: RobloxTargetProfile;
+	manifestPath: string;
+	lockPath: string;
+	headerFiles: string[];
+	luauFiles: string[];
+	docFiles: string[];
+	lspIndexPath: string | null;
+} {
+	const profile = buildRobloxTargetProfile({ dumpPath: options.dumpPath });
+	writeProfileCache(profile);
+	const headerFiles = options.skipHeaders ? [] : generateClppHeaders(profile).files;
+	const luauFiles = options.skipLuau ? [] : generateLuauDefs(profile);
+	const docFiles = options.skipDocs !== false ? [] : generateReferenceDocs(profile);
+	const lspIndexPath = options.skipLspIndex ? null : writeLspIndex(profile);
+	writeCapabilityProfile();
+
+	const fileHashes: Record<string, string> = {};
+	for (const file of [...headerFiles, ...luauFiles, ...(lspIndexPath ? [lspIndexPath] : [])]) {
+		fileHashes[path.relative(projectRoot, file).replace(/\\/g, "/")] = hashBuffer(fs.readFileSync(file));
+	}
+
+	const profileHash = profileContentHash(profile);
+	const oHash = overridesHash();
+	const manifest: ManifestDocument = {
+		schemaVersion: ROBLOX_TARGET_SCHEMA_VERSION,
+		generatorVersion: pkg.version,
+		profileHash,
+		overridesHash: oHash,
+		sources: profile.sources,
+		generatedAt: new Date().toISOString(),
+	};
+	const lock: LockDocument = {
+		schemaVersion: ROBLOX_TARGET_SCHEMA_VERSION,
+		profileHash,
+		overridesHash: oHash,
+		robloxApiVersion: profile.robloxApiVersion,
+		files: fileHashes,
+	};
+
+	const manifestsDir = path.join(projectRoot, "api", "manifests");
+	fs.mkdirSync(manifestsDir, { recursive: true });
+	const manifestPath = path.join(manifestsDir, "roblox-target.manifest.json");
+	const lockPath = path.join(projectRoot, "api", "roblox-api.lock.json");
+	atomicWriteJson(manifestPath, manifest);
+	atomicWriteJson(lockPath, lock);
+
+	return { profile, manifestPath, lockPath, headerFiles, luauFiles, docFiles, lspIndexPath };
+}
+
+function atomicWriteJson(file: string, value: unknown): void {
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	const tmp = `${file}.${process.pid}.tmp`;
+	fs.writeFileSync(tmp, `${JSON.stringify(value, null, "\t")}\n`, "utf8");
+	fs.renameSync(tmp, file);
+}
+
+export function verifyLock(): { ok: boolean; messages: string[] } {
+	const lockPath = path.join(projectRoot, "api", "roblox-api.lock.json");
+	const messages: string[] = [];
+	if (!fs.existsSync(lockPath)) {
+		return { ok: false, messages: ["roblox-api.lock.json missing — run cluaupp api generate"] };
+	}
+	const lock = JSON.parse(fs.readFileSync(lockPath, "utf8")) as LockDocument;
+	const profile = buildRobloxTargetProfile({ skipValidate: true });
+	const profileHash = profileContentHash(profile);
+	if (lock.profileHash !== profileHash) {
+		messages.push(`profile hash mismatch: lock=${lock.profileHash.slice(0, 12)}… current=${profileHash.slice(0, 12)}…`);
+	}
+	if (lock.overridesHash !== overridesHash()) {
+		messages.push("overrides hash mismatch");
+	}
+	for (const [rel, expected] of Object.entries(lock.files || {})) {
+		const full = path.join(projectRoot, rel);
+		if (!fs.existsSync(full)) {
+			messages.push(`missing generated file ${rel}`);
+			continue;
+		}
+		const actual = hashBuffer(fs.readFileSync(full));
+		if (actual !== expected) {
+			messages.push(`hash mismatch ${rel}`);
+		}
+	}
+	return { ok: messages.length === 0, messages };
+}
+
+export function inspectSymbol(symbol: string): unknown {
+	const profile = buildRobloxTargetProfile({ skipValidate: true });
+	const registry = buildRegistry(profile);
+	if (registry.classes.has(symbol)) {
+		return registry.classes.get(symbol);
+	}
+	if (registry.enums.has(symbol)) {
+		return registry.enums.get(symbol);
+	}
+	if (registry.datatypes.has(symbol)) {
+		return registry.datatypes.get(symbol);
+	}
+	if (registry.members.has(symbol)) {
+		return registry.members.get(symbol);
+	}
+	return searchRegistry(registry, symbol, 20);
+}
+
+export function apiCoverage(): ReturnType<typeof computeCoverage> {
+	const profile = buildRobloxTargetProfile({ skipValidate: true });
+	return computeCoverage(buildRegistry(profile));
+}
+
+export function apiDiffAgainstSnapshot(snapshotPath: string): ReturnType<typeof diffProfiles> {
+	const before = JSON.parse(fs.readFileSync(snapshotPath, "utf8")) as RobloxTargetProfile;
+	const after = buildRobloxTargetProfile({ skipValidate: true });
+	return diffProfiles(before, after);
+}
+
+export function writeSnapshot(outPath?: string): string {
+	const profile = buildRobloxTargetProfile();
+	const target = outPath || path.join(projectRoot, "api", "snapshots", "latest.profile.json");
+	writeProfileCache(profile, target);
+	return target;
+}
+
+export function validateCurrent(): ReturnType<typeof validateProfile> {
+	return validateProfile(buildRobloxTargetProfile({ skipValidate: true }));
+}
+
+export function analyzeLuauOutput(): Array<{ file: string; ok: boolean; output: string }> {
+	const dir = path.join(projectRoot, "api", "generated", "luau");
+	if (!fs.existsSync(dir)) {
+		return [];
+	}
+	return fs
+		.readdirSync(dir)
+		.filter((f) => f.endsWith(".luau"))
+		.map((f) => {
+			const file = path.join(dir, f);
+			const result = tryLuauAnalyze(file);
+			return { file, ...result };
+		});
+}

package/src/api/loader.ts

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import { projectRoot } from "../package-info.js";
+import { hashBuffer } from "./resolver.js";
+import type { OverrideEntry, SourceMeta } from "./model.js";
+
+export interface LoadedSource<T = unknown> {
+	meta: SourceMeta;
+	data: T;
+}
+
+export function loadJsonFile<T>(id: string, filePath: string): LoadedSource<T> {
+	const absolute = path.isAbsolute(filePath) ? filePath : path.join(projectRoot, filePath);
+	if (!fs.existsSync(absolute)) {
+		throw new Error(`API source not found: ${absolute}`);
+	}
+	const raw = fs.readFileSync(absolute);
+	const text = raw.toString("utf8");
+	const data = JSON.parse(text) as T;
+	return {
+		meta: {
+			id,
+			path: absolute,
+			hash: hashBuffer(raw),
+			loadedAt: new Date().toISOString(),
+			version: typeof (data as { Version?: unknown }).Version !== "undefined"
+				? (data as { Version: string | number }).Version
+				: undefined,
+		},
+		data,
+	};
+}
+
+export function readOverrideFile<T extends Record<string, unknown>>(
+	relativeName: string,
+): { meta: OverrideEntry | null; data: T } {
+	const filePath = path.join(projectRoot, "api", "overrides", relativeName);
+	if (!fs.existsSync(filePath)) {
+		return { meta: null, data: {} as T };
+	}
+	const parsed = JSON.parse(fs.readFileSync(filePath, "utf8")) as T & { _meta?: OverrideEntry };
+	const meta = parsed._meta || null;
+	const { _meta: _, ...rest } = parsed as T & { _meta?: OverrideEntry };
+	return { meta, data: rest as T };
+}
+
+export function overridesHash(): string {
+	const dir = path.join(projectRoot, "api", "overrides");
+	if (!fs.existsSync(dir)) {
+		return hashBuffer("");
+	}
+	const parts: string[] = [];
+	for (const name of fs.readdirSync(dir).sort()) {
+		if (!name.endsWith(".json")) {
+			continue;
+		}
+		parts.push(name, fs.readFileSync(path.join(dir, name), "utf8"));
+	}
+	return hashBuffer(parts.join("\n"));
+}

package/src/api/merge.ts

@@ -0,0 +1,126 @@
+import type {
+	CanonicalType,
+	ConstructorDefinition,
+	DatatypeDefinition,
+	GlobalDefinition,
+	LibraryDefinition,
+	MethodDefinition,
+	OverrideEntry,
+	ParameterDefinition,
+	RobloxTargetProfile,
+} from "./model.js";
+import { mapNamedTypeLike, parseClppTypeString } from "./type-parse.js";
+
+export interface DatatypeOverrideFile {
+	_meta?: OverrideEntry;
+	datatypes?: Record<string, RawDatatypeOverride>;
+}
+
+export interface RawDatatypeOverride {
+	summary?: string;
+	fields?: string[];
+	ctors?: string[][];
+	statics?: string[];
+	staticMethods?: Array<[string, string, string[]]>;
+	methods?: Array<[string, string, string[]]>;
+	custom?: boolean;
+}
+
+export function applyDatatypeOverrides(
+	existing: Record<string, DatatypeDefinition>,
+	raw: Record<string, RawDatatypeOverride>,
+): Record<string, DatatypeDefinition> {
+	const out = { ...existing };
+	for (const [name, spec] of Object.entries(raw)) {
+		out[name] = convertDatatypeOverride(name, spec);
+	}
+	return out;
+}
+
+function convertDatatypeOverride(name: string, spec: RawDatatypeOverride): DatatypeDefinition {
+	const fields = (spec.fields || []).map((f) => {
+		const parts = f.trim().split(/\s+/);
+		const fieldName = parts.pop() || "value";
+		const typeStr = parts.join(" ") || "auto";
+		return { name: fieldName, type: parseClppTypeString(typeStr) };
+	});
+	const constructors: ConstructorDefinition[] = (spec.ctors || []).map((params, i) => ({
+		owner: name,
+		overloadIndex: i,
+		parameters: params.map((p, idx) => parseParamString(p, idx)),
+		tags: [],
+	}));
+	const staticMethods: MethodDefinition[] = (spec.staticMethods || []).map((m, i) => ({
+		name: m[0],
+		owner: name,
+		overloadIndex: i,
+		parameters: (m[2] || []).map((p, idx) => parseParamString(p, idx)),
+		returnTypes: [parseClppTypeString(m[1])],
+		canYield: false,
+		tags: ["static"],
+	}));
+	const instanceMethods: MethodDefinition[] = (spec.methods || []).map((m, i) => ({
+		name: m[0],
+		owner: name,
+		overloadIndex: i,
+		parameters: (m[2] || []).map((p, idx) => parseParamString(p, idx)),
+		returnTypes: [parseClppTypeString(m[1])],
+		canYield: false,
+		tags: [],
+	}));
+	return {
+		name,
+		summary: spec.summary,
+		fields,
+		constructors,
+		staticProperties: spec.statics || [],
+		staticMethods,
+		instanceMethods,
+		source: "override",
+	};
+}
+
+function parseParamString(raw: string, index: number): ParameterDefinition {
+	const parts = raw.trim().split(/\s+/);
+	const name = parts.pop() || `arg${index}`;
+	const typeStr = parts.join(" ") || "auto";
+	const type = parseClppTypeString(typeStr);
+	return { name, type, optional: type.kind === "Optional" };
+}
+
+export function applyGlobalsOverrides(
+	existing: Record<string, GlobalDefinition>,
+	raw: Record<string, { type?: string; layer?: GlobalDefinition["layer"]; description?: string }>,
+): Record<string, GlobalDefinition> {
+	const out = { ...existing };
+	for (const [name, g] of Object.entries(raw)) {
+		out[name] = {
+			name,
+			type: g.type ? parseClppTypeString(g.type) : { kind: "Any" },
+			layer: g.layer || "roblox-engine",
+			description: g.description,
+		};
+	}
+	return out;
+}
+
+export function applyLibraryOverrides(
+	existing: Record<string, LibraryDefinition>,
+	raw: Record<string, LibraryDefinition>,
+): Record<string, LibraryDefinition> {
+	return { ...existing, ...raw };
+}
+
+export function applyClassOverrides(
+	classes: RobloxTargetProfile["classes"],
+	raw: Record<string, Partial<RobloxTargetProfile["classes"][string]>>,
+): void {
+	for (const [name, patch] of Object.entries(raw)) {
+		if (!classes[name]) {
+			continue;
+		}
+		Object.assign(classes[name], patch, { name });
+	}
+}
+
+export { mapNamedTypeLike };