@toolproof-core/schema 1.0.0

package/dist/generated/types/types.js

@@ -0,0 +1 @@
+export {}

package/dist/scripts/_lib/config.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Configuration for schema generation scripts
+ * All paths are configurable via environment variables
+ * Provides sensible defaults for standard project structure
+ */
+/**
+ * Schema configuration with required environment variables
+ */
+export declare class SchemaConfig {
+    private readonly root;
+    private readonly sourceDir;
+    private readonly sourceFile;
+    private readonly normalizedDir;
+    private readonly outputDir;
+    private readonly typesSrcDir;
+    private readonly typesDistDir;
+    private readonly generatedResourcesDir;
+    private readonly dependencyMapPath;
+    private readonly baseUrl;
+    private readonly version;
+    constructor();
+    getRoot(): string;
+    getSourceDir(): string;
+    getSourceFile(): string;
+    getSourcePath(): string;
+    getNormalizedDir(): string;
+    getNormalizedSourceFile(): string;
+    getNormalizedSourcePath(): string;
+    getOutputDir(): string;
+    getOutputPath(filename: string): string;
+    getTypesSrcDir(): string;
+    getTypesDistDir(): string;
+    getTypesSrcPath(filename: string): string;
+    getTypesDistPath(filename: string): string;
+    getGeneratedResourcesDir(): string;
+    getDependencyMapPath(): string;
+    getBaseUrl(): string;
+    getVersion(): string;
+    getSchemaId(schemaName: string): string;
+    /**
+     * Check if a URL matches the configured schema base URL pattern
+     */
+    isSchemaUrl(url: string): boolean;
+    /**
+     * Extract schema name from URL (removes base URL and version prefix)
+     */
+    extractSchemaName(url: string): string;
+}
+/**
+ * Get the schema configuration singleton
+ * Throws error if required environment variables are not set
+ */
+export declare function getConfig(): SchemaConfig;

package/dist/scripts/_lib/config.js

@@ -0,0 +1,138 @@
+/**
+ * Configuration for schema generation scripts
+ * All paths are configurable via environment variables
+ * Provides sensible defaults for standard project structure
+ */
+import path from 'path';
+/**
+ * Get environment variable with optional default
+ */
+function getEnv(name, defaultValue) {
+    const value = process.env[name];
+    return value || defaultValue;
+}
+/**
+ * Schema configuration with required environment variables
+ */
+export class SchemaConfig {
+    constructor() {
+        // Environment variables with sensible defaults
+        this.root = getEnv('TP_SCHEMA_ROOT', process.cwd());
+        this.sourceDir = getEnv('TP_SCHEMA_SOURCE_DIR', 'src/');
+        this.sourceFile = getEnv('TP_SCHEMA_SOURCE_FILE', 'Genesis.json');
+        // Intermediate, generated artifact produced by rewriteAnchors.
+        // This should NOT live next to the source-of-truth schemas.
+        this.normalizedDir = getEnv('TP_SCHEMA_NORMALIZED_DIR', 'src/generated/resourceTypes');
+        this.outputDir = getEnv('TP_SCHEMA_OUTPUT_DIR', 'src/generated/schemas');
+        this.typesSrcDir = getEnv('TP_SCHEMA_TYPES_SRC_DIR', 'src/generated/types');
+        this.typesDistDir = getEnv('TP_SCHEMA_TYPES_DIST_DIR', 'dist/generated/types');
+        this.generatedResourcesDir = getEnv('TP_SCHEMA_RESOURCES_DIR', 'src/generated/resources');
+        this.dependencyMapPath = getEnv('TP_SCHEMA_DEPENDENCY_MAP_PATH', 'src/generated/dependencies.json');
+        this.baseUrl = getEnv('TP_SCHEMA_BASE_URL', 'https://schemas.toolproof.com');
+        this.version = getEnv('TP_SCHEMA_VERSION', 'v0');
+    }
+    // Path getters
+    getRoot() {
+        return this.root;
+    }
+    getSourceDir() {
+        return path.isAbsolute(this.sourceDir)
+            ? this.sourceDir
+            : path.join(this.root, this.sourceDir);
+    }
+    getSourceFile() {
+        return this.sourceFile;
+    }
+    getSourcePath() {
+        return path.join(this.getSourceDir(), this.sourceFile);
+    }
+    getNormalizedDir() {
+        return path.isAbsolute(this.normalizedDir)
+            ? this.normalizedDir
+            : path.join(this.root, this.normalizedDir);
+    }
+    getNormalizedSourceFile() {
+        // We keep the same basename (Genesis.json) in the generated folder.
+        // The source-of-truth Genesis.json lives under `TP_SCHEMA_SOURCE_DIR`.
+        // The generated/normalized Genesis.json lives under `TP_SCHEMA_NORMALIZED_DIR`.
+        return this.sourceFile;
+    }
+    getNormalizedSourcePath() {
+        return path.join(this.getNormalizedDir(), this.getNormalizedSourceFile());
+    }
+    getOutputDir() {
+        return path.isAbsolute(this.outputDir)
+            ? this.outputDir
+            : path.join(this.root, this.outputDir);
+    }
+    getOutputPath(filename) {
+        return path.join(this.getOutputDir(), filename);
+    }
+    getTypesSrcDir() {
+        return path.isAbsolute(this.typesSrcDir)
+            ? this.typesSrcDir
+            : path.join(this.root, this.typesSrcDir);
+    }
+    getTypesDistDir() {
+        return path.isAbsolute(this.typesDistDir)
+            ? this.typesDistDir
+            : path.join(this.root, this.typesDistDir);
+    }
+    getTypesSrcPath(filename) {
+        return path.join(this.getTypesSrcDir(), filename);
+    }
+    getTypesDistPath(filename) {
+        return path.join(this.getTypesDistDir(), filename);
+    }
+    getGeneratedResourcesDir() {
+        return path.isAbsolute(this.generatedResourcesDir)
+            ? this.generatedResourcesDir
+            : path.join(this.root, this.generatedResourcesDir);
+    }
+    getDependencyMapPath() {
+        return path.isAbsolute(this.dependencyMapPath)
+            ? this.dependencyMapPath
+            : path.join(this.root, this.dependencyMapPath);
+    }
+    // Schema URL methods
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+    getVersion() {
+        return this.version;
+    }
+    getSchemaId(schemaName) {
+        return `${this.baseUrl}/${this.version}/${schemaName}.json`;
+    }
+    /**
+     * Check if a URL matches the configured schema base URL pattern
+     */
+    isSchemaUrl(url) {
+        const baseUrlPattern = this.baseUrl.replace('https://', 'https?://');
+        return new RegExp(`^${baseUrlPattern}/`, 'i').test(url);
+    }
+    /**
+     * Extract schema name from URL (removes base URL and version prefix)
+     */
+    extractSchemaName(url) {
+        // Remove base URL
+        let name = url.replace(new RegExp(`^${this.baseUrl}/`, 'i'), '');
+        // Remove version prefix (v0/, v1/, etc.)
+        name = name.replace(/^v\d+\//, '');
+        // Remove .json extension
+        name = name.replace(/\.json$/, '');
+        return name;
+    }
+}
+// Singleton instance
+let configInstance = null;
+/**
+ * Get the schema configuration singleton
+ * Throws error if required environment variables are not set
+ */
+export function getConfig() {
+    if (!configInstance) {
+        configInstance = new SchemaConfig();
+    }
+    return configInstance;
+}

package/dist/scripts/extractSchemas.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/extractSchemas.js

@@ -0,0 +1,210 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { getConfig } from "./_lib/config.js";
+function parseArgs() {
+    const config = getConfig();
+    const argv = process.argv.slice(2);
+    let inPath = "";
+    let outPath = "";
+    let topLevelId;
+    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.getOutputPath(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 };
+}
+// Heuristic: determine if a node is a Type envelope
+function isTypeEnvelope(node) {
+    return (node && typeof node === "object" && !Array.isArray(node) &&
+        // Treat any object that has an 'nucleusSchema' AND 'identity' as a Type envelope
+        // 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, source, label) {
+    if (!source || typeof source !== "object")
+        return;
+    const src = source["$defs"];
+    if (!src || typeof src !== "object")
+        return;
+    for (const [k, v] of Object.entries(src)) {
+        if (!(k in target)) {
+            target[k] = v;
+        }
+        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;
+            }
+        }
+    }
+}
+// Deeply traverse an object replacing any Type envelope with its nucleusSchema,
+// and hoist its inner $defs to topDefs. Prevent infinite recursion with a visited set.
+function unwrapTypes(node, topDefs, labelPath = [], visited = new Set()) {
+    if (node && typeof node === "object") {
+        if (visited.has(node))
+            return node; // avoid cycles
+        visited.add(node);
+    }
+    if (isTypeEnvelope(node)) {
+        const env = node;
+        const inner = env.nucleusSchema;
+        // Hoist inner $defs before stripping
+        mergeDefs(topDefs, inner, labelPath.join("_"));
+        // Return the inner schema itself, after also unwrapping any nested envelopes it may contain
+        const unwrappedInner = unwrapTypes(inner, 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));
+    }
+    if (node && typeof node === "object") {
+        const out = {};
+        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 envelope
+                const defsOut = {};
+                for (const [dk, dv] of Object.entries(v)) {
+                    const unwrapped = unwrapTypes(dv, topDefs, labelPath.concat(["$defs", dk]), visited);
+                    defsOut[dk] = unwrapped;
+                }
+                out[k] = defsOut;
+            }
+            else {
+                out[k] = unwrapTypes(v, 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, topLevelId) {
+    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.nucleusSchema;
+    const outDefs = {};
+    // Seed with top-level $defs (if any) before unwrapping
+    mergeDefs(outDefs, topSchema, "top");
+    // Unwrap the entire top schema tree so that any nested Type envelopes become raw schemas
+    const flattened = unwrapTypes(topSchema, outDefs, ["nucleusSchema"]);
+    // Assemble output: force $schema, optionally set $id, hoist collected $defs
+    let base;
+    if (flattened && typeof flattened === "object" && !Array.isArray(flattened)) {
+        base = { ...flattened };
+    }
+    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 = {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        ...base,
+    };
+    if (topLevelId && !output.$id) {
+        output.$id = topLevelId;
+    }
+    // Enforce presence of $id: schema must declare an absolute identity.
+    if (!output.$id) {
+        throw new Error("Flattened schema must define $id. Provide it via CLI --id or include $id in the source nucleusSchema.");
+    }
+    // Merge collected defs into output.$defs, taking care not to clobber any existing
+    if (!("$defs" in output))
+        output.$defs = {};
+    const finalDefs = output.$defs || {};
+    for (const [k, v] of Object.entries(outDefs)) {
+        if (!(k in finalDefs))
+            finalDefs[k] = v;
+    }
+    output.$defs = finalDefs;
+    // Ensure a stable order for readability
+    return orderKeys(output, ["$id", "$schema", "$vocabulary", "$defs", "title", "description", "type", "allOf", "anyOf", "oneOf", "not", "if", "then", "else", "properties", "required", "additionalProperties", "unevaluatedProperties"]);
+}
+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}`);
+}
+function orderKeys(obj, preferred) {
+    if (Array.isArray(obj))
+        return obj.map((v) => orderKeys(v, preferred));
+    if (!obj || typeof obj !== "object")
+        return obj;
+    const keys = Object.keys(obj);
+    const sorted = [
+        ...preferred.filter((k) => keys.includes(k)),
+        ...keys.filter((k) => !preferred.includes(k)).sort()
+    ];
+    const out = {};
+    for (const k of sorted)
+        out[k] = orderKeys(obj[k], preferred);
+    return out;
+}
+main();

package/dist/scripts/extractSubSchemaWithDefs.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/extractSubSchemaWithDefs.js

@@ -0,0 +1,187 @@
+import fs from 'fs';
+import path from 'path';
+import { getConfig } from './_lib/config.js';
+/**
+ * Generic extractor: given a subschema name that exists under Genesis.json $defs,
+ * produce a standalone JSON Schema file that contains that subschema plus an inner $defs
+ * object holding all direct & transitive local $defs dependencies (by #/$defs/... $ref).
+ *
+ * Genesis.json itself is left unchanged.
+ *
+ * Usage:
+ *   node ./dist/scripts/extractSubschemaWithDefs.js --name <DefName>
+ *
+ * Writes: src/genesis/generated/schemas/<DefName>.json
+ */
+/**
+ * Pure function to extract a subschema and its dependencies from a genesis object.
+ * Performs no I/O operations.
+ *
+ * @param genesis The root Genesis schema object
+ * @param name The name of the definition to extract
+ * @returns The standalone subschema
+ */
+function extractSubSchemaLogic(genesis, name) {
+    const rootDefs = genesis.$defs;
+    if (!rootDefs || typeof rootDefs !== 'object') {
+        throw new Error('No $defs object found in Genesis.json');
+    }
+    const target = rootDefs[name];
+    if (!target) {
+        throw new Error(`Subschema named '${name}' not found under $defs in Genesis.json`);
+    }
+    // Collect transitive local $defs names referenced by target
+    const needed = collectLocalDefClosure(target, rootDefs);
+    // Build output schema: clone target and attach collected subset as $defs
+    const targetClone = deepClone(target);
+    const defsOut = {};
+    for (const defName of needed) {
+        // Avoid including the target itself inside its own $defs (mirrors previous pattern)
+        if (defName === name)
+            continue;
+        const defSchema = rootDefs[defName];
+        if (defSchema === undefined) {
+            console.warn(`Warning: referenced def '${defName}' missing in root $defs (skipped).`);
+            continue;
+        }
+        defsOut[defName] = deepClone(defSchema);
+    }
+    // Merge any pre-existing inner $defs of targetClone (if present) giving precedence to collected ones
+    const existingInner = isObject(targetClone.$defs) ? targetClone.$defs : {};
+    targetClone.$defs = { ...existingInner, ...defsOut };
+    return targetClone;
+}
+async function main() {
+    const config = getConfig();
+    const { name } = parseArgs(process.argv.slice(2));
+    if (!name) {
+        console.error('Missing --name <DefName> argument');
+        process.exit(1);
+    }
+    const schemasDir = config.getOutputDir();
+    const genesisPath = path.join(schemasDir, config.getSourceFile());
+    const outPath = config.getOutputPath(`${name}.json`);
+    if (!fs.existsSync(genesisPath)) {
+        console.error(`Genesis.json not found at ${genesisPath}`);
+        process.exit(1);
+    }
+    const raw = fs.readFileSync(genesisPath, 'utf-8');
+    const genesis = JSON.parse(raw);
+    try {
+        // Call the pure logic function
+        const result = extractSubSchemaLogic(genesis, name);
+        // I/O: Write the result
+        fs.mkdirSync(path.dirname(outPath), { recursive: true });
+        fs.writeFileSync(outPath, JSON.stringify(result, null, 2) + '\n');
+        console.log(`Extracted subschema '${name}' -> ${outPath}`);
+    }
+    catch (error) {
+        console.error(error.message);
+        process.exit(1);
+    }
+}
+// ---- Helpers ----
+function parseArgs(args) {
+    let name;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--name') {
+            name = args[i + 1];
+            i++;
+        }
+        else if (a.startsWith('--name=')) {
+            name = a.split('=')[1];
+        }
+    }
+    return { name };
+}
+function isObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+function deepClone(v) {
+    if (Array.isArray(v))
+        return v.map((x) => deepClone(x));
+    if (isObject(v)) {
+        const out = {};
+        for (const k of Object.keys(v))
+            out[k] = deepClone(v[k]);
+        return out;
+    }
+    return v;
+}
+function extractPointerDefName(ref) {
+    // Accept refs like '#/$defs/Name' only (single-level under $defs)
+    if (!ref || !ref.startsWith('#/'))
+        return null;
+    const parts = ref.slice(2).split('/'); // remove '#/'
+    if (parts.length !== 2)
+        return null;
+    if (parts[0] !== '$defs')
+        return null;
+    // Decode JSON Pointer tokens for the def name
+    const name = parts[1].replace(/~1/g, '/').replace(/~0/g, '~');
+    return name;
+}
+function resolveRefToDefName(ref, rootDefs) {
+    if (!ref)
+        return null;
+    // Case 1: JSON Pointer into $defs: '#/$defs/Name'
+    const byPointer = extractPointerDefName(ref);
+    if (byPointer)
+        return byPointer;
+    // Case 2: Anchor ref: '#Name' -> find a def whose nucleusSchema.$anchor equals 'Name'
+    if (ref.startsWith('#') && !ref.startsWith('#/')) {
+        const anchor = ref.slice(1);
+        if (!anchor)
+            return null;
+        for (const [defName, defSchema] of Object.entries(rootDefs)) {
+            if (!defSchema || typeof defSchema !== 'object')
+                continue;
+            // Flattened Genesis has defs as the extraction schema itself (with $anchor at the top level).
+            // Unflattened may have { nucleusSchema: { $anchor } } envelopes. Support both.
+            const topLevelAnchor = defSchema.$anchor;
+            const nested = defSchema.nucleusSchema;
+            const nestedAnchor = nested && typeof nested === 'object' ? nested.$anchor : undefined;
+            const defAnchor = typeof topLevelAnchor === 'string' ? topLevelAnchor : (typeof nestedAnchor === 'string' ? nestedAnchor : undefined);
+            if (defAnchor === anchor) {
+                return defName;
+            }
+        }
+    }
+    return null;
+}
+function collectLocalDefClosure(node, rootDefs) {
+    const needed = new Set();
+    const queue = [];
+    function visit(n) {
+        if (Array.isArray(n)) {
+            for (const item of n)
+                visit(item);
+            return;
+        }
+        if (!isObject(n))
+            return;
+        if (typeof n.$ref === 'string') {
+            const name = resolveRefToDefName(n.$ref, rootDefs);
+            if (name && !needed.has(name)) {
+                needed.add(name);
+                queue.push(name);
+            }
+        }
+        for (const val of Object.values(n))
+            visit(val);
+    }
+    visit(node);
+    while (queue.length > 0) {
+        const name = queue.shift();
+        const def = rootDefs[name];
+        if (!def)
+            continue; // Missing def handled earlier
+        visit(def);
+    }
+    return needed;
+}
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/dist/scripts/generateDependencies.d.ts

@@ -0,0 +1 @@
+export {};