@toolproof-core/schema 1.0.0

package/src/generated/types/types.js

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

package/src/index.ts

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

package/src/scripts/_lib/config.ts

@@ -0,0 +1,181 @@
+/**
+ * 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;
+}

package/src/scripts/extractSchemas.ts

@@ -0,0 +1,229 @@
+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.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: any): boolean {
+  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: 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 envelope 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 (isTypeEnvelope(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 envelopes 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 envelope
+        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;
+  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 envelopes 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."
+    );
+  }
+
+  // Merge 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;
+
+  // 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: any, preferred: string[]): any {
+  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: any = {};
+  for (const k of sorted) out[k] = orderKeys(obj[k], preferred);
+  return out;
+}
+
+main();

package/src/scripts/extractSubSchemaWithDefs.ts

@@ -0,0 +1,196 @@
+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: any, name: string): any {
+  const rootDefs: Record<string, any> | undefined = 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: Record<string, any> = {};
+  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: any) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+// ---- Helpers ----
+function parseArgs(args: string[]): { name?: string } {
+  let name: string | undefined;
+  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: any): v is Record<string, any> {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function deepClone<T>(v: T): T {
+  if (Array.isArray(v)) return v.map((x) => deepClone(x)) as any;
+  if (isObject(v)) {
+    const out: Record<string, any> = {};
+    for (const k of Object.keys(v)) out[k] = deepClone((v as any)[k]);
+    return out as any;
+  }
+  return v;
+}
+
+function extractPointerDefName(ref: string): string | null {
+  // 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: string, rootDefs: Record<string, any>): string | null {
+  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 as any).$anchor;
+      const nested = (defSchema as any).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: any, rootDefs: Record<string, any>): Set<string> {
+  const needed = new Set<string>();
+  const queue: string[] = [];
+
+  function visit(n: any) {
+    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);
+});