cluaupp 1.5.0 → 1.5.1

package/generated/api/loader.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadJsonFile = loadJsonFile;
+exports.readOverrideFile = readOverrideFile;
+exports.overridesHash = overridesHash;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const package_info_js_1 = require("../package-info.js");
+const resolver_js_1 = require("./resolver.js");
+function loadJsonFile(id, filePath) {
+    const absolute = node_path_1.default.isAbsolute(filePath) ? filePath : node_path_1.default.join(package_info_js_1.projectRoot, filePath);
+    if (!node_fs_1.default.existsSync(absolute)) {
+        throw new Error(`API source not found: ${absolute}`);
+    }
+    const raw = node_fs_1.default.readFileSync(absolute);
+    const text = raw.toString("utf8");
+    const data = JSON.parse(text);
+    return {
+        meta: {
+            id,
+            path: absolute,
+            hash: (0, resolver_js_1.hashBuffer)(raw),
+            loadedAt: new Date().toISOString(),
+            version: typeof data.Version !== "undefined"
+                ? data.Version
+                : undefined,
+        },
+        data,
+    };
+}
+function readOverrideFile(relativeName) {
+    const filePath = node_path_1.default.join(package_info_js_1.projectRoot, "api", "overrides", relativeName);
+    if (!node_fs_1.default.existsSync(filePath)) {
+        return { meta: null, data: {} };
+    }
+    const parsed = JSON.parse(node_fs_1.default.readFileSync(filePath, "utf8"));
+    const meta = parsed._meta || null;
+    const { _meta: _, ...rest } = parsed;
+    return { meta, data: rest };
+}
+function overridesHash() {
+    const dir = node_path_1.default.join(package_info_js_1.projectRoot, "api", "overrides");
+    if (!node_fs_1.default.existsSync(dir)) {
+        return (0, resolver_js_1.hashBuffer)("");
+    }
+    const parts = [];
+    for (const name of node_fs_1.default.readdirSync(dir).sort()) {
+        if (!name.endsWith(".json")) {
+            continue;
+        }
+        parts.push(name, node_fs_1.default.readFileSync(node_path_1.default.join(dir, name), "utf8"));
+    }
+    return (0, resolver_js_1.hashBuffer)(parts.join("\n"));
+}

package/generated/api/merge.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapNamedTypeLike = void 0;
+exports.applyDatatypeOverrides = applyDatatypeOverrides;
+exports.applyGlobalsOverrides = applyGlobalsOverrides;
+exports.applyLibraryOverrides = applyLibraryOverrides;
+exports.applyClassOverrides = applyClassOverrides;
+const type_parse_js_1 = require("./type-parse.js");
+Object.defineProperty(exports, "mapNamedTypeLike", { enumerable: true, get: function () { return type_parse_js_1.mapNamedTypeLike; } });
+function applyDatatypeOverrides(existing, raw) {
+    const out = { ...existing };
+    for (const [name, spec] of Object.entries(raw)) {
+        out[name] = convertDatatypeOverride(name, spec);
+    }
+    return out;
+}
+function convertDatatypeOverride(name, spec) {
+    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: (0, type_parse_js_1.parseClppTypeString)(typeStr) };
+    });
+    const constructors = (spec.ctors || []).map((params, i) => ({
+        owner: name,
+        overloadIndex: i,
+        parameters: params.map((p, idx) => parseParamString(p, idx)),
+        tags: [],
+    }));
+    const staticMethods = (spec.staticMethods || []).map((m, i) => ({
+        name: m[0],
+        owner: name,
+        overloadIndex: i,
+        parameters: (m[2] || []).map((p, idx) => parseParamString(p, idx)),
+        returnTypes: [(0, type_parse_js_1.parseClppTypeString)(m[1])],
+        canYield: false,
+        tags: ["static"],
+    }));
+    const instanceMethods = (spec.methods || []).map((m, i) => ({
+        name: m[0],
+        owner: name,
+        overloadIndex: i,
+        parameters: (m[2] || []).map((p, idx) => parseParamString(p, idx)),
+        returnTypes: [(0, type_parse_js_1.parseClppTypeString)(m[1])],
+        canYield: false,
+        tags: [],
+    }));
+    return {
+        name,
+        summary: spec.summary,
+        fields,
+        constructors,
+        staticProperties: spec.statics || [],
+        staticMethods,
+        instanceMethods,
+        source: "override",
+    };
+}
+function parseParamString(raw, index) {
+    const parts = raw.trim().split(/\s+/);
+    const name = parts.pop() || `arg${index}`;
+    const typeStr = parts.join(" ") || "auto";
+    const type = (0, type_parse_js_1.parseClppTypeString)(typeStr);
+    return { name, type, optional: type.kind === "Optional" };
+}
+function applyGlobalsOverrides(existing, raw) {
+    const out = { ...existing };
+    for (const [name, g] of Object.entries(raw)) {
+        out[name] = {
+            name,
+            type: g.type ? (0, type_parse_js_1.parseClppTypeString)(g.type) : { kind: "Any" },
+            layer: g.layer || "roblox-engine",
+            description: g.description,
+        };
+    }
+    return out;
+}
+function applyLibraryOverrides(existing, raw) {
+    return { ...existing, ...raw };
+}
+function applyClassOverrides(classes, raw) {
+    for (const [name, patch] of Object.entries(raw)) {
+        if (!classes[name]) {
+            continue;
+        }
+        Object.assign(classes[name], patch, { name });
+    }
+}

package/generated/api/model.js

@@ -0,0 +1,5 @@
+"use strict";
+/** Canonical Roblox API model for Cluaupp (RobloxTargetProfile schemaVersion 2). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROBLOX_TARGET_SCHEMA_VERSION = void 0;
+exports.ROBLOX_TARGET_SCHEMA_VERSION = 2;

package/generated/api/normalize.js

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeMiniDump = normalizeMiniDump;
+const resolver_js_1 = require("./resolver.js");
+function tagsOf(member) {
+    return Array.isArray(member.Tags)
+        ? member.Tags.map((t) => (typeof t === "string" ? t : String(t.PreferredDescriptorName || JSON.stringify(t))))
+        : [];
+}
+function hasTag(tags, tag) {
+    return tags.some((t) => t.toLowerCase() === tag.toLowerCase());
+}
+function securityString(sec) {
+    if (!sec) {
+        return undefined;
+    }
+    if (typeof sec === "string") {
+        return sec;
+    }
+    return sec.Read || sec.Write;
+}
+function mapThreadSafety(raw) {
+    if (!raw) {
+        return undefined;
+    }
+    switch (raw) {
+        case "Unsafe":
+        case "ReadSafe":
+        case "LocalSafe":
+        case "Safe":
+            return raw;
+        default:
+            return "Unknown";
+    }
+}
+function creationPolicy(tags) {
+    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) {
+    return (member.Parameters || []).map((p, i) => (0, resolver_js_1.mapParameter)(p, i));
+}
+function returnTypes(member) {
+    if (member.ReturnType) {
+        return [(0, resolver_js_1.mapRobloxType)(member.ReturnType)];
+    }
+    return [{ kind: "Primitive", name: "void" }];
+}
+function collectUnsupported(type, symbol, unsupported) {
+    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, unsupported) {
+    const tags = tagsOf(raw);
+    const creation = creationPolicy(tags);
+    const properties = [];
+    const methods = [];
+    const events = [];
+    const callbacks = [];
+    const methodOverloads = new Map();
+    for (const member of raw.Members || []) {
+        const mTags = tagsOf(member);
+        const deprecated = hasTag(mTags, "Deprecated")
+            ? { deprecated: true, message: "Deprecated in Roblox API dump" }
+            : undefined;
+        const symbol = `${raw.Name}.${member.Name}`;
+        switch (member.MemberType) {
+            case "Property": {
+                const valueType = (0, resolver_js_1.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: [],
+    };
+}
+function normalizeMiniDump(dump) {
+    const unsupported = [];
+    const classes = {};
+    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 = {};
+    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/generated/api/overrides-validate.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateOverrides = validateOverrides;
+exports.diffOverrideFiles = diffOverrideFiles;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const package_info_js_1 = require("../package-info.js");
+/** Validate override JSON files carry audit metadata. */
+function validateOverrides() {
+    const dir = node_path_1.default.join(package_info_js_1.projectRoot, "api", "overrides");
+    const issues = [];
+    if (!node_fs_1.default.existsSync(dir)) {
+        return [{ file: "api/overrides", message: "overrides directory missing" }];
+    }
+    for (const name of node_fs_1.default.readdirSync(dir).sort()) {
+        if (!name.endsWith(".json")) {
+            continue;
+        }
+        const full = node_path_1.default.join(dir, name);
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(full, "utf8"));
+        if (!parsed._meta) {
+            issues.push({ file: name, message: "missing _meta" });
+            continue;
+        }
+        for (const key of ["reason", "source", "introducedAt"]) {
+            if (!parsed._meta[key]) {
+                issues.push({ file: name, message: `missing _meta.${key}` });
+            }
+        }
+    }
+    return issues;
+}
+function diffOverrideFiles(beforeDir, afterDir) {
+    const before = new Set(node_fs_1.default.existsSync(beforeDir) ? node_fs_1.default.readdirSync(beforeDir).filter((f) => f.endsWith(".json")) : []);
+    const after = new Set(node_fs_1.default.existsSync(afterDir) ? node_fs_1.default.readdirSync(afterDir).filter((f) => f.endsWith(".json")) : []);
+    const changes = [];
+    for (const f of after) {
+        if (!before.has(f)) {
+            changes.push(`ADDED ${f}`);
+        }
+        else {
+            const a = node_fs_1.default.readFileSync(node_path_1.default.join(beforeDir, f), "utf8");
+            const b = node_fs_1.default.readFileSync(node_path_1.default.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/generated/api/perf.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timeCall = timeCall;
+exports.formatPerf = formatPerf;
+function timeCall(label, fn) {
+    const started = Date.now();
+    const value = fn();
+    return { value, sample: { label, ms: Date.now() - started } };
+}
+function formatPerf(samples) {
+    return samples.map((s) => `${s.label}=${s.ms}ms`).join(" ");
+}

package/generated/api/registry.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRegistry = buildRegistry;
+exports.flattenMembers = flattenMembers;
+exports.deriveServices = deriveServices;
+exports.searchRegistry = searchRegistry;
+function buildRegistry(profile) {
+    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();
+    const methods = new Map();
+    const properties = new Map();
+    const events = new Map();
+    const ancestors = new Map();
+    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, classes) {
+    const chain = [];
+    let current = classes[name]?.superclass || null;
+    const seen = new Set();
+    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. */
+function flattenMembers(registry, className) {
+    const order = [className, ...(registry.ancestors.get(className) || [])];
+    const properties = [];
+    const methods = [];
+    const events = [];
+    const seenProp = new Set();
+    const seenMethod = new Set();
+    const seenEvent = new Set();
+    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 };
+}
+function deriveServices(classes) {
+    const services = {};
+    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;
+}
+function searchRegistry(registry, query, limit = 50) {
+    const q = query.toLowerCase();
+    const hits = [];
+    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/generated/api/release.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildReleaseChecklist = buildReleaseChecklist;
+exports.writeApiChangelog = writeApiChangelog;
+/** Release / checksum helpers for Roblox Target artifacts. */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const package_info_js_1 = require("../package-info.js");
+const package_info_js_2 = require("../package-info.js");
+const resolver_js_1 = require("./resolver.js");
+const model_js_1 = require("./model.js");
+function buildReleaseChecklist() {
+    const lockPath = node_path_1.default.join(package_info_js_1.projectRoot, "api", "roblox-api.lock.json");
+    const manifestPath = node_path_1.default.join(package_info_js_1.projectRoot, "api", "manifests", "roblox-target.manifest.json");
+    const checksums = {};
+    for (const rel of [
+        "include/clpp/generated/enums.clh",
+        "include/clpp/datatypes.clh",
+        "include/clpp/generated/instances.clh",
+        "api/overrides/datatypes.json",
+    ]) {
+        const full = node_path_1.default.join(package_info_js_1.projectRoot, rel);
+        if (node_fs_1.default.existsSync(full)) {
+            checksums[rel] = (0, resolver_js_1.hashBuffer)(node_fs_1.default.readFileSync(full));
+        }
+    }
+    return {
+        schemaVersion: model_js_1.ROBLOX_TARGET_SCHEMA_VERSION,
+        generatorVersion: package_info_js_2.pkg.version,
+        lockPresent: node_fs_1.default.existsSync(lockPath),
+        manifestPresent: node_fs_1.default.existsSync(manifestPath),
+        checksums,
+    };
+}
+function writeApiChangelog(entries, outPath) {
+    const target = outPath || node_path_1.default.join(package_info_js_1.projectRoot, "api", "CHANGELOG.md");
+    const body = [`# Roblox API changelog`, ``, ...entries.map((e) => `- ${e}`), ``].join("\n");
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(target), { recursive: true });
+    node_fs_1.default.writeFileSync(target, body, "utf8");
+    return target;
+}