@toolproof-core/schema 1.0.3 → 1.0.4

package/src/scripts/extractSchemasFromResourceTypeShells.ts

@@ -1,218 +1,261 @@
-import fs from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
-import { getConfig } from "./_lib/config.js";
-
-type JSONValue = null | boolean | number | string | JSONValue[] | { [k: string]: JSONValue };
-
-interface ExtractOptions {
-    inPath: string;
-    outPath: string;
-    topLevelId?: string;
-}
-
-function parseArgs(): ExtractOptions {
-    const config = getConfig();
-    const argv = process.argv.slice(2);
-    let inPath = "";
-    let outPath = "";
-    let topLevelId: string | undefined;
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === "--in" && i + 1 < argv.length) inPath = argv[++i];
-        else if (a === "--out" && i + 1 < argv.length) outPath = argv[++i];
-        else if (a === "--id" && i + 1 < argv.length) {
-            let v = argv[++i];
-            // Strip accidental surrounding quotes from PowerShell/cmd
-            if ((v.startsWith("'") && v.endsWith("'")) || (v.startsWith('"') && v.endsWith('"'))) {
-                v = v.slice(1, -1);
-            }
-            topLevelId = v;
-        }
-    }
-
-    // Use config defaults if not provided via CLI
-    if (!inPath) {
-        // Use generated/normalized version with anchor refs rewritten to pointers
-        inPath = config.getNormalizedSourcePath();
-    }
-    if (!outPath) {
-        outPath = config.getSchemaPath(config.getSourceFile());
-    }
-    if (!topLevelId) {
-        topLevelId = config.getSchemaId('Genesis');
-    }
-
-    // Resolve to absolute paths from project root
-    const cwd = config.getRoot();
-    const wasInRelative = !path.isAbsolute(inPath);
-    const wasOutRelative = !path.isAbsolute(outPath);
-    if (wasInRelative) inPath = path.join(cwd, inPath);
-    if (wasOutRelative) outPath = path.join(cwd, outPath);
-    // Fallback: resolve relative to script directory if not found
-    const scriptDir = path.dirname(fileURLToPath(import.meta.url));
-    if (!fs.existsSync(inPath) && wasInRelative) inPath = path.resolve(scriptDir, inPath);
-    const outDir = path.dirname(outPath);
-    if (!fs.existsSync(outDir) && wasOutRelative) {
-        // Try making directory relative to script dir
-        const altOut = path.resolve(scriptDir, outPath);
-        const altOutDir = path.dirname(altOut);
-        if (!fs.existsSync(path.dirname(outPath))) {
-            // Prefer creating outDir at cwd location if possible; otherwise fallback below when writing
-        } else {
-            outPath = altOut;
-        }
-    }
-    return { inPath, outPath, topLevelId };
-}
-
-// ATTENTION: we don't want heuristic behavior.
-// Heuristic: determine if a node is a Type shell
-function isTypeShell(node: any): boolean {
-    return (
-        node && typeof node === "object" && !Array.isArray(node) &&
-        // Treat any object that has an 'nucleusSchema' AND 'identity' as a Type shell
-        // This prevents false positives where 'nucleusSchema' is just a regular schema property
-        node.nucleusSchema && typeof node.nucleusSchema === "object" &&
-        node.identity && typeof node.identity === "string"
-    );
-}
-
-// Merge $defs into target, without overwriting existing keys unless identical
-function mergeDefs(target: Record<string, JSONValue>, source?: any, label?: string) {
-    if (!source || typeof source !== "object") return;
-    const src = (source as any)["$defs"];
-    if (!src || typeof src !== "object") return;
-    for (const [k, v] of Object.entries(src)) {
-        if (!(k in target)) {
-            target[k] = v as JSONValue;
-        } else {
-            // Best-effort: if duplicate key, require structural equality; otherwise, namespace
-            const existing = JSON.stringify(target[k]);
-            const incoming = JSON.stringify(v);
-            if (existing !== incoming) {
-                const altKey = `${k}__from_${(label || "defs").replace(/[^A-Za-z0-9_]+/g, "_")}`;
-                if (!(altKey in target)) target[altKey] = v as JSONValue;
-            }
-        }
-    }
-}
-
-// Deeply traverse an object replacing any Type shell with its nucleusSchema,
-// and hoist its inner $defs to topDefs. Prevent infinite recursion with a visited set.
-function unwrapTypes(node: JSONValue, topDefs: Record<string, JSONValue>, labelPath: string[] = [], visited = new Set<any>()): JSONValue {
-    if (node && typeof node === "object") {
-        if (visited.has(node)) return node; // avoid cycles
-        visited.add(node);
-    }
-
-    if (isTypeShell(node)) {
-        const env = node as any;
-        const inner = env.nucleusSchema;
-        // Hoist inner $defs before stripping
-        mergeDefs(topDefs, inner, labelPath.join("_"));
-        // Return the inner schema itself, after also unwrapping any nested shells it may contain
-        const unwrappedInner = unwrapTypes(inner as JSONValue, topDefs, labelPath.concat([String(env.identity || "env")]), visited);
-        return unwrappedInner;
-    }
-
-    if (Array.isArray(node)) {
-        return node.map((v, i) => unwrapTypes(v, topDefs, labelPath.concat([String(i)]), visited)) as JSONValue;
-    }
-
-    if (node && typeof node === "object") {
-        const out: Record<string, JSONValue> = {};
-        for (const [k, v] of Object.entries(node)) {
-            if (k === "$defs" && v && typeof v === "object" && !Array.isArray(v)) {
-                // Process nested $defs: unwrap each entry value if it's a Type shell
-                const defsOut: Record<string, JSONValue> = {};
-                for (const [dk, dv] of Object.entries(v as any)) {
-                    const unwrapped = unwrapTypes(dv as JSONValue, topDefs, labelPath.concat(["$defs", dk]), visited);
-                    defsOut[dk] = unwrapped;
-                }
-                out[k] = defsOut;
-            } else {
-                out[k] = unwrapTypes(v as JSONValue, topDefs, labelPath.concat([k]), visited);
-            }
-        }
-        return out;
-    }
-
-    return node;
-}
-
-/**
- * Pure function that takes a schema document and options, and returns the flattened schema.
- * Performs no I/O operations.
- */
-function extractSchemaLogic(doc: any, topLevelId?: string): any {
-    if (!doc || typeof doc !== "object" || !doc.nucleusSchema) {
-        throw new Error("Input must be a Type JSON with an nucleusSchema at the top level");
-    }
-
-    const topSchema = (doc as any).nucleusSchema;
-
-    // Collect $defs so that any '#/$defs/...' pointers can be resolved from the root.
-    const outDefs: Record<string, JSONValue> = {};
-    // Seed with top-level $defs (if any) before unwrapping
-    mergeDefs(outDefs, topSchema, "top");
-
-    // Unwrap the entire top schema tree so that any nested Type shells become raw schemas
-    const flattened = unwrapTypes(topSchema as JSONValue, outDefs, ["nucleusSchema"]);
-
-    // Assemble output: force $schema, optionally set $id, hoist collected $defs
-    let base: any;
-    if (flattened && typeof flattened === "object" && !Array.isArray(flattened)) {
-        base = { ...(flattened as any) };
-    } else {
-        // If flattened is not an object (should be rare for a top-level schema), wrap it
-        base = { const: flattened };
-    }
-    // Assemble, but avoid duplicating $id: if the flattened base already has $id, prefer it.
-    const output: Record<string, JSONValue> = {
-        $schema: "https://json-schema.org/draft/2020-12/schema",
-        ...base,
-    };
-    if (topLevelId && !(output as any).$id) {
-        (output as any).$id = topLevelId;
-    }
-
-    // Enforce presence of $id: schema must declare an absolute identity.
-    if (!(output as any).$id) {
-        throw new Error(
-            "Flattened schema must define $id. Provide it via CLI --id or include $id in the source nucleusSchema."
-        );
-    }
-
-    // Hoist collected defs into output.$defs, taking care not to clobber any existing
-    if (!("$defs" in output)) output.$defs = {} as any;
-    const finalDefs: Record<string, JSONValue> = (output.$defs as any) || {};
-    for (const [k, v] of Object.entries(outDefs)) {
-        if (!(k in finalDefs)) finalDefs[k] = v;
-    }
-    output.$defs = finalDefs as any;
-
-    // Preserve natural key ordering (do not reorder for readability)
-    return output;
-}
-
-function main() {
-    const { inPath, outPath, topLevelId } = parseArgs();
-
-    if (!fs.existsSync(inPath)) {
-        console.error(`Input file not found at ${inPath}`);
-        process.exit(1);
-    }
-
-    const raw = fs.readFileSync(inPath, "utf8");
-    const doc = JSON.parse(raw);
-
-    // Core logic is now in a pure function
-    const ordered = extractSchemaLogic(doc, topLevelId);
-
-    fs.mkdirSync(path.dirname(outPath), { recursive: true });
-    fs.writeFileSync(outPath, JSON.stringify(ordered, null, 4), "utf8");
-    console.log(`Wrote flattened schema to ${outPath}`);
-}
-
-main();
+import fs from "fs";
+import path from "path";
+import { getConfig } from "./_lib/config.js";
+
+type JSONValue = null | boolean | number | string | JSONValue[] | { [k: string]: JSONValue };
+
+interface ExtractOptions {
+    inPath: string;
+    outPath: string;
+    topLevelId?: string;
+}
+
+interface ExtractCliArgs {
+    inPath?: string;
+    outPath?: string;
+    topLevelId?: string;
+}
+
+interface TraverseResult {
+    value: JSONValue;
+    hoistEvents: Array<{ defs: Record<string, JSONValue>; label: string }>;
+}
+
+interface ExtractDefaults {
+    inPath: string;
+    outPath: string;
+    topLevelId: string;
+}
+
+// PURE: Parse CLI args (no defaults, no filesystem probing).
+function parseArgs(argv: string[]): ExtractCliArgs {
+    let inPath: string | undefined;
+    let outPath: string | undefined;
+    let topLevelId: string | undefined;
+
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--in" && i + 1 < argv.length) inPath = argv[++i];
+        else if (a === "--out" && i + 1 < argv.length) outPath = argv[++i];
+        else if (a === "--id" && i + 1 < argv.length) {
+            let v = argv[++i];
+            // Strip accidental surrounding quotes from PowerShell/cmd
+            if ((v.startsWith("'") && v.endsWith("'")) || (v.startsWith('"') && v.endsWith('"'))) {
+                v = v.slice(1, -1);
+            }
+            topLevelId = v;
+        }
+    }
+
+    return { inPath, outPath, topLevelId };
+}
+
+// PURE: Apply defaults for any missing values.
+function applyDefaults(args: ExtractCliArgs, defaults: ExtractDefaults): ExtractOptions {
+    return {
+        inPath: args.inPath?.trim() ? args.inPath : defaults.inPath,
+        outPath: args.outPath?.trim() ? args.outPath : defaults.outPath,
+        topLevelId: args.topLevelId?.trim() ? args.topLevelId : defaults.topLevelId
+    };
+}
+
+// PURE: Resolve relative paths against a root directory (no heuristics).
+function resolvePaths(options: ExtractOptions, rootDir: string): ExtractOptions {
+    const inPath = path.isAbsolute(options.inPath) ? options.inPath : path.join(rootDir, options.inPath);
+    const outPath = path.isAbsolute(options.outPath) ? options.outPath : path.join(rootDir, options.outPath);
+    return { ...options, inPath, outPath };
+}
+
+// PURE: Determine whether a node is a Type shell.
+function isTypeShell(node: any): boolean {
+    return (
+        node && typeof node === "object" && !Array.isArray(node) &&
+        // Treat any object that has an 'nucleusSchema' AND 'identity' as a Type shell
+        // This prevents false positives where 'nucleusSchema' is just a regular schema property
+        node.nucleusSchema && typeof node.nucleusSchema === "object" &&
+        node.identity && typeof node.identity === "string"
+    );
+}
+
+// PURE: Sanitize labels for use in deterministic collision keys.
+function sanitizeLabel(label: string | undefined): string {
+    return (label || "defs").replace(/[^A-Za-z0-9_]+/g, "_");
+}
+
+// PURE: Extract a `$defs` object from a schema node, if present.
+function getDefsObject(source: any): Record<string, JSONValue> | undefined {
+    if (!source || typeof source !== "object") return undefined;
+    const src = (source as any)["$defs"];
+    if (!src || typeof src !== "object" || Array.isArray(src)) return undefined;
+    return src as Record<string, JSONValue>;
+}
+
+// PURE: Merge defs without mutating inputs; collisions are namespaced deterministically.
+function mergeDefs(
+    existing: Record<string, JSONValue>,
+    incoming: Record<string, JSONValue> | undefined,
+    label?: string
+): Record<string, JSONValue> {
+    if (!incoming) return { ...existing };
+
+    const merged: Record<string, JSONValue> = { ...existing };
+    for (const [k, v] of Object.entries(incoming)) {
+        if (!(k in merged)) {
+            merged[k] = v;
+            continue;
+        }
+
+        const current = merged[k];
+        const same = JSON.stringify(current) === JSON.stringify(v);
+        if (same) continue;
+
+        const altKey = `${k}__from_${sanitizeLabel(label)}`;
+        if (!(altKey in merged)) merged[altKey] = v;
+    }
+    return merged;
+}
+
+// PURE: Unwrap Type shells and collect any encountered inner `$defs` hoist events.
+function traverseTypes(node: JSONValue, labelPath: string[] = []): TraverseResult {
+    if (isTypeShell(node)) {
+        const env = node as any;
+        const inner = env.nucleusSchema as JSONValue;
+        const label = labelPath.join("_");
+
+        const innerDefs = getDefsObject(inner);
+        const innerResult = traverseTypes(inner, labelPath.concat([String(env.identity || "env")]));
+
+        const events: TraverseResult["hoistEvents"] = [];
+        if (innerDefs) events.push({ defs: innerDefs, label });
+        events.push(...innerResult.hoistEvents);
+
+        return { value: innerResult.value, hoistEvents: events };
+    }
+
+    if (Array.isArray(node)) {
+        const events: TraverseResult["hoistEvents"] = [];
+        const mapped = node.map((v, i) => {
+            const r = traverseTypes(v, labelPath.concat([String(i)]));
+            events.push(...r.hoistEvents);
+            return r.value;
+        }) as JSONValue;
+        return { value: mapped, hoistEvents: events };
+    }
+
+    if (node && typeof node === "object") {
+        const events: TraverseResult["hoistEvents"] = [];
+        const out: Record<string, JSONValue> = {};
+        for (const [k, v] of Object.entries(node)) {
+            if (k === "$defs" && v && typeof v === "object" && !Array.isArray(v)) {
+                const defsOut: Record<string, JSONValue> = {};
+                for (const [dk, dv] of Object.entries(v as any)) {
+                    const r = traverseTypes(dv as JSONValue, labelPath.concat(["$defs", dk]));
+                    events.push(...r.hoistEvents);
+                    defsOut[dk] = r.value;
+                }
+                out[k] = defsOut;
+                continue;
+            }
+
+            const r = traverseTypes(v as JSONValue, labelPath.concat([k]));
+            events.push(...r.hoistEvents);
+            out[k] = r.value;
+        }
+        return { value: out, hoistEvents: events };
+    }
+
+    return { value: node, hoistEvents: [] };
+}
+
+
+// PURE: Flatten a Type shell JSON into a single JSON Schema document.
+function extractSchemaLogic(doc: any, topLevelId?: string): any {
+    if (!doc || typeof doc !== "object" || !doc.nucleusSchema) {
+        throw new Error("Input must be a Type JSON with an nucleusSchema at the top level");
+    }
+
+    const topSchema = (doc as any).nucleusSchema;
+
+    // Collect $defs so that any '#/$defs/...' pointers can be resolved from the root.
+    const seededDefs = mergeDefs({}, getDefsObject(topSchema), "top");
+
+    // Unwrap the entire top schema tree so that any nested Type shells become raw schemas
+    const traversal = traverseTypes(topSchema as JSONValue, ["nucleusSchema"]);
+    const flattened = traversal.value;
+
+    let outDefs = seededDefs;
+    for (const ev of traversal.hoistEvents) {
+        outDefs = mergeDefs(outDefs, ev.defs, ev.label);
+    }
+
+    // Assemble output: force $schema, optionally set $id, hoist collected $defs
+    let base: any;
+    if (flattened && typeof flattened === "object" && !Array.isArray(flattened)) {
+        base = { ...(flattened as any) };
+    } else {
+        // If flattened is not an object (should be rare for a top-level schema), wrap it
+        base = { const: flattened };
+    }
+    // Assemble, but avoid duplicating $id: if the flattened base already has $id, prefer it.
+    const output: Record<string, JSONValue> = {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        ...base,
+    };
+    if (topLevelId && !(output as any).$id) {
+        (output as any).$id = topLevelId;
+    }
+
+    // Enforce presence of $id: schema must declare an absolute identity.
+    if (!(output as any).$id) {
+        throw new Error(
+            "Flattened schema must define $id. Provide it via CLI --id or include $id in the source nucleusSchema."
+        );
+    }
+
+    // Hoist collected defs into output.$defs, taking care not to clobber any existing
+    if (!("$defs" in output)) output.$defs = {} as any;
+    const finalDefs: Record<string, JSONValue> = (output.$defs as any) || {};
+    for (const [k, v] of Object.entries(outDefs)) {
+        if (!(k in finalDefs)) finalDefs[k] = v;
+    }
+    output.$defs = finalDefs as any;
+
+    // Preserve natural key ordering (do not reorder for readability)
+    return output;
+}
+
+// IMPURE: Script entrypoint (config + filesystem I/O + console + process exit code).
+function main() {
+    try {
+        const config = getConfig();
+        const defaults: ExtractDefaults = {
+            // Use generated/normalized version with anchor refs rewritten to pointers
+            inPath: config.getNormalizedSourcePath(),
+            outPath: config.getSchemaPath(config.getSourceFile()),
+            topLevelId: config.getSchemaId("Genesis")
+        };
+
+        const cli = parseArgs(process.argv.slice(2));
+        const opts = resolvePaths(applyDefaults(cli, defaults), config.getRoot());
+        const { inPath, outPath, topLevelId } = opts;
+
+        if (!fs.existsSync(inPath)) {
+            throw new Error(`Input file not found at ${inPath}`);
+        }
+
+        const raw = fs.readFileSync(inPath, "utf8");
+        const doc = JSON.parse(raw);
+
+        // Core logic is now in a pure function
+        const extracted = extractSchemaLogic(doc, topLevelId);
+
+        fs.mkdirSync(path.dirname(outPath), { recursive: true });
+        fs.writeFileSync(outPath, JSON.stringify(extracted, null, 4), "utf8");
+        console.log(`Wrote flattened schema to ${outPath}`);
+    } catch (e) {
+        console.error(e);
+        process.exitCode = 1;
+    }
+}
+
+main();