@toolproof-core/schema 1.0.0 → 1.0.2

package/src/generated/types/types.js

@@ -1 +1 @@
-export {}
+export {}

package/src/scripts/_lib/config.ts

@@ -1,181 +1,205 @@
-/**
- * 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: string, defaultValue: string): string {
-  const value = process.env[name];
-  return value || defaultValue;
-}
-
-/**
- * Schema configuration with required environment variables
- */
-export class SchemaConfig {
-  // Base paths
-  private readonly root: string;
-  private readonly sourceDir: string;
-  private readonly sourceFile: string;
-  private readonly normalizedDir: string;
-  private readonly outputDir: string;
-  private readonly typesSrcDir: string;
-  private readonly typesDistDir: string;
-  private readonly generatedResourcesDir: string;
-  private readonly dependencyMapPath: string;
-
-  // Schema metadata
-  private readonly baseUrl: string;
-  private readonly version: string;
-
-  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(): string {
-    return this.root;
-  }
-
-  getSourceDir(): string {
-    return path.isAbsolute(this.sourceDir)
-      ? this.sourceDir
-      : path.join(this.root, this.sourceDir);
-  }
-
-  getSourceFile(): string {
-    return this.sourceFile;
-  }
-
-  getSourcePath(): string {
-    return path.join(this.getSourceDir(), this.sourceFile);
-  }
-
-  getNormalizedDir(): string {
-    return path.isAbsolute(this.normalizedDir)
-      ? this.normalizedDir
-      : path.join(this.root, this.normalizedDir);
-  }
-
-  getNormalizedSourceFile(): string {
-    // 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(): string {
-    return path.join(this.getNormalizedDir(), this.getNormalizedSourceFile());
-  }
-
-  getOutputDir(): string {
-    return path.isAbsolute(this.outputDir)
-      ? this.outputDir
-      : path.join(this.root, this.outputDir);
-  }
-
-  getOutputPath(filename: string): string {
-    return path.join(this.getOutputDir(), filename);
-  }
-
-  getTypesSrcDir(): string {
-    return path.isAbsolute(this.typesSrcDir)
-      ? this.typesSrcDir
-      : path.join(this.root, this.typesSrcDir);
-  }
-
-  getTypesDistDir(): string {
-    return path.isAbsolute(this.typesDistDir)
-      ? this.typesDistDir
-      : path.join(this.root, this.typesDistDir);
-  }
-
-  getTypesSrcPath(filename: string): string {
-    return path.join(this.getTypesSrcDir(), filename);
-  }
-
-  getTypesDistPath(filename: string): string {
-    return path.join(this.getTypesDistDir(), filename);
-  }
-
-  getGeneratedResourcesDir(): string {
-    return path.isAbsolute(this.generatedResourcesDir)
-      ? this.generatedResourcesDir
-      : path.join(this.root, this.generatedResourcesDir);
-  }
-
-  getDependencyMapPath(): string {
-    return path.isAbsolute(this.dependencyMapPath)
-      ? this.dependencyMapPath
-      : path.join(this.root, this.dependencyMapPath);
-  }
-
-  // Schema URL methods
-  getBaseUrl(): string {
-    return this.baseUrl;
-  }
-
-  getVersion(): string {
-    return this.version;
-  }
-
-  getSchemaId(schemaName: string): string {
-    return `${this.baseUrl}/${this.version}/${schemaName}.json`;
-  }
-
-  /**
-   * Check if a URL matches the configured schema base URL pattern
-   */
-  isSchemaUrl(url: string): boolean {
-    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: string): string {
-    // 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: SchemaConfig | null = null;
-
-/**
- * Get the schema configuration singleton
- * Throws error if required environment variables are not set
- */
-export function getConfig(): SchemaConfig {
-  if (!configInstance) {
-    configInstance = new SchemaConfig();
-  }
-  return configInstance;
-}
+/**
+ * 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: string, defaultValue: string): string {
+  const value = process.env[name];
+  return value || defaultValue;
+}
+
+/**
+ * Schema configuration with required environment variables
+ */
+export class SchemaConfig {
+  // Base paths
+  private readonly root: string;
+  private readonly sourceDir: string;
+  private readonly sourceFile: string;
+  private readonly normalizedDir: string;
+  private readonly schemasDir: string;
+  private readonly resourcesDir: string;
+  private readonly dependencyMapPath: string;
+  private readonly typesSrcDir: string;
+  private readonly typesDistDir: string;
+
+  // Schema metadata
+  private readonly baseUrl: string;
+  private readonly version: string;
+
+  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 normalizeAnchorsToPointers.
+    // This should NOT live next to the source-of-truth schemas.
+    this.normalizedDir = getEnv('TP_SCHEMA_NORMALIZED_DIR', 'src/generated/normalized');
+    this.schemasDir = getEnv('TP_SCHEMA_SCHEMAS_DIR', 'src/generated/schemas');
+    this.resourcesDir = getEnv('TP_SCHEMA_RESOURCES_DIR', 'src/generated/resources');
+    this.dependencyMapPath = getEnv('TP_SCHEMA_DEPENDENCY_MAP_PATH', 'src/generated/dependencyMap.json');
+    this.typesSrcDir = getEnv('TP_SCHEMA_TYPES_SRC_DIR', 'src/generated/types');
+    this.typesDistDir = getEnv('TP_SCHEMA_TYPES_DIST_DIR', 'dist/generated/types');
+    this.baseUrl = getEnv('TP_SCHEMA_BASE_URL', 'https://schemas.toolproof.com');
+    this.version = getEnv('TP_SCHEMA_VERSION', 'v0');
+  }
+
+  // Path getters
+  getRoot(): string {
+    return this.root;
+  }
+
+  getSourceDir(): string {
+    return path.isAbsolute(this.sourceDir)
+      ? this.sourceDir
+      : path.join(this.root, this.sourceDir);
+  }
+
+  getSourceFile(): string {
+    return this.sourceFile;
+  }
+
+  getSourcePath(): string {
+    return path.join(this.getSourceDir(), this.sourceFile);
+  }
+
+  getNormalizedDir(): string {
+    return path.isAbsolute(this.normalizedDir)
+      ? this.normalizedDir
+      : path.join(this.root, this.normalizedDir);
+  }
+
+  getNormalizedSourceFile(): string {
+    // 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(): string {
+    return path.join(this.getNormalizedDir(), this.getNormalizedSourceFile());
+  }
+
+  getSchemasDir(): string {
+    return path.isAbsolute(this.schemasDir)
+      ? this.schemasDir
+      : path.join(this.root, this.schemasDir);
+  }
+
+  getSchemaPath(filename: string): string {
+    return path.join(this.getSchemasDir(), filename);
+  }
+
+  getSchemasStandaloneDir(): string {
+    return path.join(this.getSchemasDir(), 'standalone');
+  }
+
+  getSchemaStandalonePath(filename: string): string {
+    return path.join(this.getSchemasStandaloneDir(), filename);
+  }
+
+  getTypesSrcDir(): string {
+    return path.isAbsolute(this.typesSrcDir)
+      ? this.typesSrcDir
+      : path.join(this.root, this.typesSrcDir);
+  }
+
+  getTypesDistDir(): string {
+    return path.isAbsolute(this.typesDistDir)
+      ? this.typesDistDir
+      : path.join(this.root, this.typesDistDir);
+  }
+
+  getTypesSrcPath(filename: string): string {
+    return path.join(this.getTypesSrcDir(), filename);
+  }
+
+  getTypesDistPath(filename: string): string {
+    return path.join(this.getTypesDistDir(), filename);
+  }
+
+  getTypesStandaloneSrcDir(): string {
+    return path.join(this.getTypesSrcDir(), 'standalone');
+  }
+
+  getTypesStandaloneDistDir(): string {
+    return path.join(this.getTypesDistDir(), 'standalone');
+  }
+
+  getTypesStandaloneSrcPath(filename: string): string {
+    return path.join(this.getTypesStandaloneSrcDir(), filename);
+  }
+
+  getTypesStandaloneDistPath(filename: string): string {
+    return path.join(this.getTypesStandaloneDistDir(), filename);
+  }
+
+  getResourcesDir(): string {
+    return path.isAbsolute(this.resourcesDir)
+      ? this.resourcesDir
+      : path.join(this.root, this.resourcesDir);
+  }
+
+  getDependencyMapPath(): string {
+    return path.isAbsolute(this.dependencyMapPath)
+      ? this.dependencyMapPath
+      : path.join(this.root, this.dependencyMapPath);
+  }
+
+  // Schema URL methods
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+
+  getVersion(): string {
+    return this.version;
+  }
+
+  getSchemaId(schemaName: string): string {
+    return `${this.baseUrl}/${this.version}/${schemaName}.json`;
+  }
+
+  /**
+   * Check if a URL matches the configured schema base URL pattern
+   */
+  isSchemaUrl(url: string): boolean {
+    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: string): string {
+    // 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: SchemaConfig | null = null;
+
+/**
+ * Get the schema configuration singleton
+ * Throws error if required environment variables are not set
+ */
+export function getConfig(): SchemaConfig {
+  if (!configInstance) {
+    configInstance = new SchemaConfig();
+  }
+  return configInstance;
+}

package/src/scripts/extractSchemasFromResourceTypeShells.ts

@@ -0,0 +1,218 @@
+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();