@toolproof-core/schema 1.0.2 → 1.0.4

package/src/scripts/generateStandaloneSchema.ts

@@ -1,175 +1,185 @@
-import fs from 'fs';
-import path from 'path';
-import { getConfig } from './_lib/config.js';
-
-/**
- * Create a standalone JSON Schema for a single $defs entry under Genesis.json,
- * embedding all direct & transitive local $defs dependencies.
- *
- * Usage:
- *   node ./dist/scripts/generateStandaloneSchema.js --name <DefName>
- */
-
-/**
- * Pure function to extract a subschema and its dependencies from a flattened genesis schema.
- * Performs no I/O operations.
- */
-function extractStandaloneSubschemaLogic(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`);
-  }
-
-  const needed = collectLocalDefClosure(target, rootDefs);
-
-  const targetClone = deepClone(target);
-  const defsOut: Record<string, any> = {};
-  for (const defName of needed) {
-    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);
-  }
-
-  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.getSchemasDir();
-  const genesisPath = path.join(schemasDir, config.getSourceFile());
-  const outPath = config.getSchemaStandalonePath(`${name}.json`);
-
-  if (!fs.existsSync(genesisPath)) {
-    console.error(`Genesis.json not found at ${genesisPath}. Run extractSchemasFromResourceTypeShells first.`);
-    process.exit(1);
-  }
-
-  const raw = fs.readFileSync(genesisPath, 'utf-8');
-  const genesis = JSON.parse(raw);
-
-  try {
-    const result = extractStandaloneSubschemaLogic(genesis, name);
-
-    fs.mkdirSync(path.dirname(outPath), { recursive: true });
-    fs.writeFileSync(outPath, JSON.stringify(result, null, 2) + '\n');
-    console.log(`Created standalone subschema '${name}' -> ${outPath}`);
-  } catch (error: any) {
-    console.error(error.message);
-    process.exit(1);
-  }
-}
-
-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 {
-  if (!ref || !ref.startsWith('#/')) return null;
-  const parts = ref.slice(2).split('/');
-  if (parts.length !== 2) return null;
-  if (parts[0] !== '$defs') return null;
-  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;
-  const byPointer = extractPointerDefName(ref);
-  if (byPointer) return byPointer;
-
-  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;
-      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;
-    visit(def);
-  }
-
-  return needed;
-}
-
-main().catch((e) => {
-  console.error(e);
-  process.exit(1);
-});
+import fs from 'fs';
+import path from 'path';
+import { getConfig } from './_lib/config.js';
+
+/**
+ * Create a standalone JSON Schema for a single $defs entry under Genesis.json,
+ * embedding all direct & transitive local $defs dependencies.
+ *
+ * Usage:
+ *   node ./dist/scripts/generateStandaloneSchema.js --name <DefName>
+ */
+
+// PURE: Extract a standalone subschema from a flattened Genesis schema, returning warnings instead of logging
+function extractStandaloneSchemaLogic(genesis: any, name: string): { schema: any; warnings: string[] } {
+  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`);
+  }
+
+  const needed = collectLocalDefClosure(target, rootDefs);
+
+  const targetClone = deepClone(target);
+  const defsOut: Record<string, any> = {};
+  const warnings: string[] = [];
+  for (const defName of needed) {
+    if (defName === name) continue;
+    const defSchema = rootDefs[defName];
+    if (defSchema === undefined) {
+      warnings.push(`Warning: referenced def '${defName}' missing in root $defs (skipped).`);
+      continue;
+    }
+    defsOut[defName] = deepClone(defSchema);
+  }
+
+  const existingInner = isObject(targetClone.$defs) ? targetClone.$defs : {};
+  targetClone.$defs = { ...existingInner, ...defsOut };
+
+  return { schema: targetClone, warnings };
+}
+
+// PURE: Strip accidental surrounding quotes from CLI values (PowerShell/cmd).
+function stripSurroundingQuotes(value: string): string {
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+// PURE: Parse CLI args (no defaults, no filesystem probing).
+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];
+    }
+  }
+  const normalized = typeof name === 'string' ? stripSurroundingQuotes(name) : undefined;
+  return { name: normalized?.trim() ? normalized : undefined };
+}
+
+// PURE: Narrow unknown values to plain objects.
+function isObject(v: any): v is Record<string, any> {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+// PURE: Deep-clone JSON-ish values (no mutation of input).
+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;
+}
+
+// PURE: Extract a $defs key from a local JSON pointer ref.
+function extractPointerDefName(ref: string): string | null {
+  if (!ref || !ref.startsWith('#/')) return null;
+  const parts = ref.slice(2).split('/');
+  if (parts.length !== 2) return null;
+  if (parts[0] !== '$defs') return null;
+  const name = parts[1].replace(/~1/g, '/').replace(/~0/g, '~');
+  return name;
+}
+
+// PURE: Resolve an internal ref (pointer or anchor) to a root $defs key.
+function resolveRefToDefName(ref: string, rootDefs: Record<string, any>): string | null {
+  if (!ref) return null;
+  const byPointer = extractPointerDefName(ref);
+  if (byPointer) return byPointer;
+
+  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;
+      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;
+}
+
+// PURE: Compute the transitive closure of local $defs dependencies for a node.
+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;
+    visit(def);
+  }
+
+  return needed;
+}
+
+// IMPURE: Script entrypoint (config + filesystem I/O + console + process exit code).
+async function main() {
+  try {
+    const config = getConfig();
+    const { name } = parseArgs(process.argv.slice(2));
+    if (!name) {
+      throw new Error('Missing --name <DefName> argument');
+    }
+
+    const schemasDir = config.getSchemasDir();
+    const genesisPath = path.join(schemasDir, config.getSourceFile());
+    const outPath = config.getSchemaStandalonePath(`${name}.json`);
+
+    if (!fs.existsSync(genesisPath)) {
+      throw new Error(`Genesis.json not found at ${genesisPath}. Run extractSchemasFromResourceTypeShells first.`);
+    }
+
+    const raw = fs.readFileSync(genesisPath, 'utf-8');
+    const genesis = JSON.parse(raw);
+
+    const { schema, warnings } = extractStandaloneSchemaLogic(genesis, name);
+    for (const w of warnings) console.warn(w);
+
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, JSON.stringify(schema, null, 2) + '\n');
+    console.log(`Created standalone subschema '${name}' -> ${outPath}`);
+  } catch (error: any) {
+    console.error(error?.message ?? error);
+    process.exitCode = 1;
+  }
+}
+
+void main();

package/src/scripts/generateStandaloneTypeTS.ts

@@ -0,0 +1,127 @@
+import fs from "fs";
+import { getConfig } from "./_lib/config.js";
+
+/**
+ * Generate a typed Resource variant where `nucleus` is typed to a specific schema
+ * extracted under the configured output directory.
+ *
+ * Usage: node ./dist/scripts/generateStandaloneType.js --name Job
+ */
+
+// PURE: Generate the content of a standalone Resource type definition file for a given schema name.
+function generateStandaloneTypeLogic(name: string): string {
+    const header = "// Auto-generated strict composite type. Do not edit.\n";
+    const ts =
+        `import type { ShellMaterializedBase, ${name} as NucleusSchema } from "../typesTS.js";\n` +
+        `export type Resource_${name} = ShellMaterializedBase & { nucleus: NucleusSchema };\n`;
+    return header + ts;
+}
+
+// PURE: Strip accidental surrounding quotes from CLI values (PowerShell/cmd).
+function stripSurroundingQuotes(value: string): string {
+    if ((value.startsWith("\"") && value.endsWith("\"")) || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+
+// PURE: Validate a standalone schema and return warnings (no logging).
+function validateStandaloneSchemaForWarnings(schema: any): string[] {
+    const warnings: string[] = [];
+    if (schema?.$schema && schema.$schema !== "https://json-schema.org/draft/2020-12/schema") {
+        warnings.push(
+            `Warning: schema $schema is '${String(schema.$schema)}', expected draft 2020-12. Proceeding anyway.`
+        );
+    }
+    if (schema?.type && schema.type !== "object") {
+        warnings.push(
+            `Warning: nucleusSchema usually has type: 'object' but this schema has type: '${String(schema.type)}'. Proceeding.`
+        );
+    }
+    return warnings;
+}
+
+// PURE: Parse CLI args (no defaults, no filesystem probing).
+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];
+        }
+    }
+    const normalized = typeof name === "string" ? stripSurroundingQuotes(name) : undefined;
+    return { name: normalized?.trim() ? normalized : undefined };
+}
+
+// IMPURE: Script entrypoint (config + filesystem I/O + console + process exit).
+function main() {
+    try {
+        const config = getConfig();
+        const { name } = parseArgs(process.argv.slice(2));
+
+        if (!name) {
+            throw new Error("Missing --name <SchemaBasename> argument");
+        }
+
+        const inPath =
+            name === "Genesis"
+                ? config.getSchemaPath("Genesis.json")
+                : config.getSchemaStandalonePath(`${name}.json`);
+
+        if (!fs.existsSync(inPath)) {
+            if (name === "Genesis") {
+                console.error(`Schema file not found: ${inPath}`);
+                console.error("Run extractSchemasFromResourceTypeShells first.");
+            } else {
+                console.error(`Standalone schema file not found: ${inPath}`);
+                console.error(`Run generateStandaloneSchema -- --name ${name} first.`);
+            }
+            throw new Error("Input schema file not found");
+        }
+
+        // Basic validation against the expected shape of nucleusSchema.
+        const raw = fs.readFileSync(inPath, "utf8");
+        const parsed: any = JSON.parse(raw);
+
+        for (const warning of validateStandaloneSchemaForWarnings(parsed)) console.warn(warning);
+
+        const tsContent = generateStandaloneTypeLogic(name);
+        const jsContent = "export {}\n";
+
+        // Output setup
+        const outName = `Resource_${name}.d.ts`;
+        const outJsName = `Resource_${name}.js`;
+        const outDir = config.getStandaloneTypeTsSrcDir();
+        const distLibDir = config.getStandaloneTypeTsDistDir();
+
+        // Process src output
+        fs.mkdirSync(outDir, { recursive: true });
+        const outPath = config.getStandaloneTypeTsSrcPath(outName);
+        const outJsPath = config.getStandaloneTypeTsSrcPath(outJsName);
+        fs.writeFileSync(outPath, tsContent, "utf8");
+        console.log(`Wrote ${outPath}`);
+
+        if (!fs.existsSync(outJsPath)) {
+            fs.writeFileSync(outJsPath, jsContent, "utf8");
+            console.log(`Wrote ${outJsPath}`);
+        }
+
+        // Process dist output
+        fs.mkdirSync(distLibDir, { recursive: true });
+        const distDtsPath = config.getStandaloneTypeTsDistPath(outName);
+        const distJsPath = config.getStandaloneTypeTsDistPath(outJsName);
+        fs.writeFileSync(distDtsPath, tsContent, "utf8");
+        fs.writeFileSync(distJsPath, jsContent, "utf8");
+        console.log(`Wrote ${distDtsPath}`);
+        console.log(`Wrote ${distJsPath}`);
+    } catch (e) {
+        console.error(e);
+        process.exitCode = 1;
+    }
+}
+
+main();