@toolproof-core/schema 1.0.3 → 1.0.4

package/src/scripts/generateTypesTS.ts

@@ -0,0 +1,532 @@
+import fs from 'fs';
+import path from 'path';
+import { compile } from 'json-schema-to-typescript';
+import { getConfig } from './_lib/config.js';
+
+// PURE: Format a JSON path for error messages.
+function formatPath(pathSegments: Array<string | number>): string {
+    let out = '';
+    for (const seg of pathSegments) {
+        if (typeof seg === 'number') {
+            out += `[${seg}]`;
+            continue;
+        }
+        out = out ? `${out}.${seg}` : seg;
+    }
+    return out || '<root>';
+}
+
+// PURE: Validate schema array-keyword shapes; returns a list of issues (no mutation, no I/O).
+function validateSchemaArrayKeywords(node: any, parentKey?: string, pathSegments: Array<string | number> = []): string[] {
+    if (Array.isArray(node)) {
+        const issues: string[] = [];
+        for (let i = 0; i < node.length; i++) {
+            issues.push(...validateSchemaArrayKeywords(node[i], parentKey, pathSegments.concat([i])));
+        }
+        return issues;
+    }
+
+    if (!node || typeof node !== 'object') return [];
+
+    // IMPORTANT:
+    // In meta-schemas we often have `properties: { required: { ...schema... } }`.
+    // Here, the key "required" is a *property name*, not the JSON-Schema keyword.
+    // So when we are iterating a property-name map, do not treat keys as schema keywords.
+    const isPropertyNameMap =
+        parentKey === 'properties' ||
+        parentKey === 'patternProperties' ||
+        parentKey === '$defs' ||
+        parentKey === 'dependentSchemas' ||
+        parentKey === 'dependentRequired';
+
+    const arrayKeys = ['anyOf', 'allOf', 'oneOf', 'required', 'enum'] as const;
+    const issues: string[] = [];
+
+    for (const [k, v] of Object.entries(node)) {
+        // Keyword sanity checks for schema objects (regardless of where they appear).
+        // These reduce the chance of feeding obviously malformed shapes into the generator.
+        if (k === 'properties' || k === 'patternProperties' || k === '$defs' || k === 'dependentSchemas') {
+            if (v === null || typeof v !== 'object' || Array.isArray(v)) {
+                issues.push(
+                    `${formatPath(pathSegments.concat([k]))}: expected \`${k}\` to be an object map, got ${v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v}`
+                );
+            }
+        }
+        if (k === 'dependentRequired') {
+            if (v === null || typeof v !== 'object' || Array.isArray(v)) {
+                issues.push(
+                    `${formatPath(pathSegments.concat([k]))}: expected \`dependentRequired\` to be an object map, got ${v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v}`
+                );
+            } else {
+                for (const [depKey, depVal] of Object.entries(v as any)) {
+                    if (!Array.isArray(depVal)) {
+                        issues.push(
+                            `${formatPath(pathSegments.concat([k, depKey]))}: expected dependentRequired entries to be string arrays, got ${depVal === null ? 'null' : typeof depVal}`
+                        );
+                        continue;
+                    }
+                    for (let i = 0; i < depVal.length; i++) {
+                        if (typeof depVal[i] !== 'string') {
+                            issues.push(
+                                `${formatPath(pathSegments.concat([k, depKey, i]))}: expected dependentRequired entries to be strings, got ${depVal[i] === null ? 'null' : typeof depVal[i]}`
+                            );
+                        }
+                    }
+                }
+            }
+        }
+
+        if (!isPropertyNameMap && (arrayKeys as readonly string[]).includes(k) && Object.prototype.hasOwnProperty.call(node, k)) {
+            if (!Array.isArray(v)) {
+                issues.push(
+                    `${formatPath(pathSegments.concat([k]))}: expected \`${k}\` to be an array, got ${v === null ? 'null' : typeof v}`
+                );
+            } else {
+                if ((k === 'anyOf' || k === 'allOf' || k === 'oneOf') && v.length === 0) {
+                    issues.push(`${formatPath(pathSegments.concat([k]))}: expected \`${k}\` to be a non-empty array`);
+                }
+
+                if (k === 'anyOf' || k === 'allOf' || k === 'oneOf') {
+                    for (let i = 0; i < v.length; i++) {
+                        const item = v[i];
+                        const ok =
+                            typeof item === 'boolean' ||
+                            (item !== null && typeof item === 'object' && !Array.isArray(item));
+                        if (!ok) {
+                            issues.push(
+                                `${formatPath(pathSegments.concat([k, i]))}: expected a schema (object or boolean), got ${item === null ? 'null' : Array.isArray(item) ? 'array' : typeof item}`
+                            );
+                        }
+                    }
+                }
+
+                if (k === 'required') {
+                    // `required` must be string[] when used as a JSON-Schema keyword.
+                    const seen = new Set<string>();
+                    for (let i = 0; i < v.length; i++) {
+                        if (typeof v[i] !== 'string') {
+                            issues.push(
+                                `${formatPath(pathSegments.concat([k, i]))}: expected \`required\` entries to be strings, got ${v[i] === null ? 'null' : typeof v[i]}`
+                            );
+                            continue;
+                        }
+                        if (seen.has(v[i])) {
+                            issues.push(`${formatPath(pathSegments.concat([k]))}: duplicate required entry \`${v[i]}\``);
+                        }
+                        seen.add(v[i]);
+                    }
+                }
+            }
+        }
+
+        issues.push(...validateSchemaArrayKeywords(v, k, pathSegments.concat([k])));
+    }
+
+    return issues;
+}
+
+// PURE: Move sibling object keywords into `allOf` overlays (returns a new tree; does not mutate inputs).
+function normalizeAllOfSiblingObjectKeywords(node: any): any {
+    if (Array.isArray(node)) {
+        let changed = false;
+        const out = node.map((item) => {
+            const next = normalizeAllOfSiblingObjectKeywords(item);
+            if (next !== item) changed = true;
+            return next;
+        });
+        return changed ? out : node;
+    }
+    if (!node || typeof node !== 'object') return node;
+
+    const hasAllOf = Array.isArray((node as any).allOf) && (node as any).allOf.length > 0;
+    const looksLikeObjectSchema =
+        (node as any).type === 'object' ||
+        (node as any).properties !== undefined ||
+        (node as any).required !== undefined ||
+        (node as any).unevaluatedProperties !== undefined ||
+        (node as any).additionalProperties !== undefined;
+
+    const siblingKeys = [
+        'properties',
+        'required',
+        'additionalProperties',
+        'unevaluatedProperties',
+        'propertyNames',
+        'patternProperties',
+        'dependentRequired',
+        'dependentSchemas',
+        'minProperties',
+        'maxProperties'
+    ] as const;
+
+    let localNode: any = node;
+    if (hasAllOf && looksLikeObjectSchema) {
+        const hasSiblingObjectKeywords = siblingKeys.some((k) => k in localNode);
+        if (hasSiblingObjectKeywords) {
+            const overlay: any = {};
+            if ((localNode as any).type === 'object') overlay.type = 'object';
+
+            const nextNode: any = { ...localNode };
+            for (const k of siblingKeys) {
+                if (k in nextNode) {
+                    overlay[k] = nextNode[k];
+                    delete nextNode[k];
+                }
+            }
+
+            nextNode.allOf = [overlay, ...(nextNode.allOf as any[])];
+            localNode = nextNode;
+        }
+    }
+
+    let changed = localNode !== node;
+    const out: Record<string, any> = localNode === node ? ({} as any) : { ...localNode };
+    for (const [k, v] of Object.entries(localNode)) {
+        const next = normalizeAllOfSiblingObjectKeywords(v);
+        if (next !== v) {
+            if (!changed) {
+                changed = true;
+                Object.assign(out, localNode);
+            }
+            out[k] = next;
+        } else if (changed) {
+            out[k] = v;
+        }
+    }
+
+    return changed ? out : node;
+}
+
+// PURE: Clone + apply all generator-normalizations.
+function normalizeSchemaForGenerator(schema: any): any {
+    return normalizeAllOfSiblingObjectKeywords(schema);
+}
+
+// PURE: Convert a regex-ish pattern into a TS template literal when recognizable.
+function deriveTemplateFromPattern(pattern: string): string | undefined {
+    // Common (and currently canonical for identities): ^PREFIX-.+$ => `PREFIX-${string}`
+    const m1 = /^\^([^$]+)\.\+\$/.exec(pattern);
+    if (m1) {
+        const prefix = m1[1];
+        if (!/[`]/.test(prefix)) {
+            return '`' + prefix + '${string}`';
+        }
+    }
+    return undefined;
+}
+
+// PURE: Extract Identity template-literal aliases from a parsed schema.
+function loadPatternTemplatesFromSchema(schema: any): Record<string, string> {
+    const map: Record<string, string> = {};
+    const defs = schema?.$defs && typeof schema.$defs === 'object' ? schema.$defs : {};
+    for (const [defName, defVal] of Object.entries(defs)) {
+        const isPatternType = /Identity$/.test(defName);
+        if (!isPatternType) continue;
+
+        const v: any = defVal;
+        if (v && v.type === 'string' && typeof v.pattern === 'string') {
+            const tmpl = deriveTemplateFromPattern(v.pattern);
+            if (tmpl) map[defName] = tmpl;
+        }
+    }
+    return map;
+}
+
+// PURE: Remove duplicate union members from emitted `export type X = | ...` blocks.
+function removeDuplicateUnionEntries(ts: string): string {
+    return ts.replace(/export type ([A-Za-z0-9_]+) =([\s\S]*?);/g, (_m, typeName, body) => {
+        const lines = body.split(/\r?\n/);
+        const seen = new Set<string>();
+        const kept: string[] = [];
+        for (const line of lines) {
+            const trimmed = line.trim();
+            const match = /^\|\s*([A-Za-z0-9_]+)\b/.exec(trimmed);
+            if (match) {
+                const name = match[1];
+                if (!seen.has(name)) {
+                    seen.add(name);
+                    kept.push('  | ' + name);
+                }
+                continue;
+            }
+            if (trimmed.length) kept.push(line);
+        }
+        return `export type ${typeName} =\n` + kept.join('\n') + ';';
+    });
+}
+
+// PURE: Escape a string for use inside a RegExp pattern.
+function escapeRegExpLiteral(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// PURE: Fix a known json-schema-to-typescript edge case where a JSON-like recursive value union
+// accidentally includes a direct self-reference (`| JsonData`) instead of the intended array case (`| JsonData[]`).
+function fixJsonDataSelfReference(ts: string): string {
+    const lines = ts.split(/\r?\n/);
+    const startIndex = lines.findIndex((l) => /^export\s+type\s+JsonData\s*=\s*$/.test(l.trimEnd()));
+    if (startIndex < 0) return ts;
+
+    // This type currently ends with a union member object whose closing line is `};`.
+    // Find that terminator after the type header.
+    let endIndex = -1;
+    for (let i = startIndex + 1; i < lines.length; i++) {
+        if (/^\s*};\s*$/.test(lines[i])) {
+            endIndex = i;
+            break;
+        }
+    }
+    if (endIndex < 0) return ts;
+
+    for (let i = startIndex + 1; i < endIndex; i++) {
+        if (/^\s*\|\s*JsonData\s*$/.test(lines[i])) {
+            lines[i] = lines[i].replace(/\bJsonData\b/, 'JsonData[]');
+        }
+    }
+
+    return lines.join('\n');
+}
+
+// PURE: Apply deterministic post-processing to the generator output (no I/O).
+function postProcessEmittedTypes(ts: string, parsedSchema: any): string {
+    // Remove permissive index signatures that make interfaces open-ended.
+    // Keep meaningful map-like signatures (e.g., `[k: string]: ResourceRoleValue`) intact.
+    // Robust single-pass: delete the entire line (with optional trailing newline) where the signature appears.
+    // This avoids introducing extra blank lines while handling CRLF/LF and varying indentation.
+    ts = ts.replace(/^\s*\[k:\s*string\]:\s*unknown;\s*(?:\r?\n)?/gm, '');
+
+    // Fix meta-schema types where json-schema-to-typescript can still incorrectly interpret
+    // schema definitions as literal values (or emit overly-restrictive `{}` objects).
+    // We do this as a broad post-pass on the emitted TS because the generator output varies
+    // (e.g. `allOf?: { }[];` vs `allOf?: [{type:"array"; ...}]`).
+
+    // `$defs?: { }` or `$defs: { }` -> map type (preserve required/optional marker)
+    // NOTE: We emit `Record<...>` instead of an index signature because later cleanup
+    // strips standalone `[k: string]: unknown;` lines.
+    ts = ts.replace(
+        /^(\s*)(\$defs\??:\s*)\{\s*\r?\n\s*\};/gm,
+        (_m, indent, head) => `${indent}${head}Record<string, unknown>;`
+    );
+
+    // `properties?: { }` or `properties: { }` -> map type
+    ts = ts.replace(
+        /^(\s*)(properties\??:\s*)\{\s*\r?\n\s*\};/gm,
+        (_m, indent, head) => `${indent}${head}Record<string, unknown>;`
+    );
+
+    // `allOf?: { }[];` (and similar for anyOf/oneOf) -> array of schema-ish objects
+    ts = ts.replace(
+        /^(\s*)((?:allOf|anyOf|oneOf)\??:\s*)\{\s*\r?\n\s*\}\[\];/gm,
+        (_m, indent, head) => `${indent}${head}Array<{[k: string]: unknown}>;`
+    );
+
+    ts = removeDuplicateUnionEntries(ts);
+
+    // Strip URL-derived root schema interface names produced by json-schema-to-typescript
+    // (e.g. `HttpsSchemasToolproofComV2GenesisJson`). These are naming artifacts and not
+    // meaningful domain types.
+    const schemaId = parsedSchema?.$id;
+    if (typeof schemaId === 'string') {
+        const m = /\/([^/]+)\.json$/i.exec(schemaId);
+        const rootBaseName = m?.[1];
+        if (rootBaseName) {
+            const rootJsonSuffix = `${rootBaseName}Json`;
+            const rootJsonSuffixEsc = escapeRegExpLiteral(rootJsonSuffix);
+
+            // Remove the (typically empty) URL-derived root interface, if present.
+            ts = ts.replace(
+                new RegExp(`^export interface Https[A-Za-z0-9_]*${rootJsonSuffixEsc}\\s*\\{\\s*\\}\\s*(?:\\r?\\n)?`, 'gm'),
+                ''
+            );
+
+            // Replace remaining references to that URL-derived name in doc/comments.
+            ts = ts.replace(
+                new RegExp(`\\bHttps[A-Za-z0-9_]*${rootJsonSuffixEsc}\\b`, 'g'),
+                rootBaseName
+            );
+        }
+    }
+
+    if (!ts || !ts.trim()) {
+        throw new Error('Type generator emitted no output for Genesis schema.');
+    }
+
+    // Overlay Identity aliases with template literal types inferred from Genesis.json patterns.
+    // For each $defs entry ending with "Identity" that provides a `pattern`,
+    // derive a TS template literal; otherwise fall back to plain `string`.
+    const patternTemplates = loadPatternTemplatesFromSchema(parsedSchema);
+
+    // Replace any exported Identity aliases to use the inferred template literals where available.
+    // Handle the common `= string;` output from json-schema-to-typescript.
+    ts = ts.replace(
+        /^(export\s+type\s+)([A-Za-z_][A-Za-z0-9_]*Identity)(\s*=\s*)string\s*;$/gm,
+        (_m, p1, typeName, p3) => {
+            const tmpl = patternTemplates[typeName];
+            return `${p1}${typeName}${p3}${tmpl ?? 'string'};`;
+        }
+    );
+
+    // Post-process map-like interfaces to enforce key constraints via template literal Identity types.
+    // Replace index-signature interfaces with Record<KeyType, ValueType> so object literal keys are checked.
+    const resourceRoleKeyType = 'ResourceRoleIdentity';
+    const jobStepKeyType = 'JobStepIdentity';
+    const strategyThreadKeyType = 'StrategyThreadIdentity';
+
+    ts = ts.replace(
+        /export interface RoleMap\s*{[^}]*}/g,
+        `export type RoleMap = Record<${resourceRoleKeyType}, ResourceRoleValue>;`
+    );
+    // Normalize StrategyState & related socket maps to identity-keyed Records.
+    // These are emitted as `[k: string]` by json-schema-to-typescript but are identity-keyed in practice.
+    // Per schema: JobStepSocket: Record<ResourceRoleIdentity, Resource>
+    //            StrategyState: Record<JobStepIdentity, JobStepSocket>
+    const jobStepSocketValueType = 'Resource';
+    ts = ts.replace(
+        /export interface JobStepSocket\s*\{\s*\[k:\s*string\]:\s*[^;]+;\s*\}/g,
+        `export type JobStepSocket = Record<${resourceRoleKeyType}, ${jobStepSocketValueType}>;`
+    );
+    ts = ts.replace(
+        /export interface StrategyState\s*\{\s*\[k:\s*string\]:\s*JobStepSocket;\s*\}/g,
+        `export type StrategyState = Record<${jobStepKeyType}, JobStepSocket>;`
+    );
+    ts = ts.replace(
+        /(strategyStateUpdate\??:\s*)\{\s*\[k:\s*string\]:\s*JobStepSocket;\s*\};/g,
+        `$1Record<${jobStepKeyType}, JobStepSocket>;`
+    );
+
+    // Ensure key constraints for strategyThreadMap are preserved as template-literal identity keys.
+    // json-schema-to-typescript emits `[k: string]: StepArray;`, but we want keys to be `StrategyThreadIdentity`.
+    ts = ts.replace(
+        /export interface StrategyThreadMap\s*\{\s*\[k:\s*string\]:\s*StepArray;\s*\}/g,
+        `export type StrategyThreadMap = Record<${strategyThreadKeyType}, StepArray>;`
+    );
+
+    ts = fixJsonDataSelfReference(ts);
+
+    return ts;
+}
+
+// PURE: Add banner + formatting/guards to build the final .d.ts content.
+function finalizeOutputDts(emittedTypesTs: string): string {
+    const banner = '// Auto-generated from JSON schemas. Do not edit.\n';
+
+    let output = banner + '\n' + emittedTypesTs + '\n';
+
+    // Final guard: strip any lingering `[k: string]: unknown;` that might have been
+    // reintroduced by later transforms.
+    output = output.replace(/^\s*\[k:\s*string\]:\s*unknown;\s*$/gm, '');
+
+    // Cosmetic post-format: remove lone blank lines before closing braces and collapse excessive blank lines
+    // - Remove a single blank line before `};` and `}`
+    // - Collapse 3+ consecutive newlines into a maximum of 2
+    output = output
+        .replace(/\r?\n\s*\r?\n(\s*};)/g, '\n$1')
+        .replace(/\r?\n\s*\r?\n(\s*})/g, '\n$1')
+        .replace(/(\r?\n){3,}/g, '\n\n');
+
+    // As an additional safeguard, make sure the final .d.ts is treated as a module.
+    // If no export/interface/module is present, append an empty export.
+    if (!/\bexport\b|\bdeclare\s+module\b|\bdeclare\s+namespace\b/.test(output)) {
+        output += '\nexport {}\n';
+    }
+
+    return output;
+}
+
+// IMPURE: Main script entrypoint (config + filesystem I/O + console + process exit).
+async function main() {
+    try {
+        const config = getConfig();
+        const inputDir = config.getSchemasDir();
+        const srcLibTypesDir = config.getTypesTsSrcDir();
+        const srcLibOutputPath = config.getTypesTsSrcPath('typesTS.d.ts');
+
+        fs.mkdirSync(srcLibTypesDir, { recursive: true });
+
+        const schemaFileName = config.getSourceFile();
+        const schemaPath = path.join(inputDir, schemaFileName);
+        if (!fs.existsSync(schemaPath)) {
+            throw new Error(
+                `Root schema not found: ${schemaPath}\n` +
+                `Run the schema extraction step first (e.g. pnpm run extractSchemasFromResourceTypeShells).`
+            );
+        }
+
+        const rawSchema = fs.readFileSync(schemaPath, 'utf8');
+        const parsedSchema: any = JSON.parse(rawSchema);
+
+        const validationIssues = validateSchemaArrayKeywords(parsedSchema);
+        if (validationIssues.length) {
+            throw new Error(
+                'Genesis schema is not in canonical form for type generation:\n' +
+                validationIssues.map((s) => `- ${s}`).join('\n')
+            );
+        }
+
+        const normalizedSchema = normalizeSchemaForGenerator(parsedSchema);
+
+        let ts: string;
+
+        const rootName = path.basename(schemaFileName, path.extname(schemaFileName));
+        ts = await compile(normalizedSchema, rootName, {
+            bannerComment: '',
+            declareExternallyReferenced: true,
+            unreachableDefinitions: true,
+            $refOptions: {
+                resolve: {
+                    file: { order: 2 },
+                    http: false,
+                    https: false
+                }
+            } as any
+        });
+
+        ts = postProcessEmittedTypes(ts, parsedSchema);
+        const output = finalizeOutputDts(ts);
+
+        // Write only under configured types output folder
+        try {
+            fs.writeFileSync(srcLibOutputPath, output, 'utf8');
+            console.log('Wrote', srcLibOutputPath);
+        } catch (e) {
+            console.warn('Failed to write types to src/_lib:', e);
+        }
+
+        // Also write a copy into dist so consumers get the generated declarations
+        const distLibTypesDir = config.getTypesTsDistDir();
+        const distLibOutputPath = config.getTypesTsDistPath('typesTS.d.ts');
+        try {
+            fs.mkdirSync(distLibTypesDir, { recursive: true });
+            fs.writeFileSync(distLibOutputPath, output, 'utf8');
+            console.log('Wrote', distLibOutputPath);
+        } catch (e) {
+            // If copying to dist fails, log but don't crash the generator.
+            console.warn('Failed to write types to dist:', e);
+        }
+
+        // Ensure there is a runtime-resolvable module next to `typesTS.d.ts`
+        // Some consumers and TS NodeNext resolution expect a concrete .js next to .d.ts
+        // The file is intentionally empty as all exports are types-only.
+        try {
+            const srcLibTypesJsPath = config.getTypesTsSrcPath('typesTS.js');
+            if (!fs.existsSync(srcLibTypesJsPath)) {
+                fs.writeFileSync(srcLibTypesJsPath, 'export {}\n', 'utf8');
+                console.log('Wrote', srcLibTypesJsPath);
+            }
+        } catch (e) {
+            console.warn('Failed to write typesTS.js to src/_lib:', e);
+        }
+        try {
+            const distLibTypesJsPath = config.getTypesTsDistPath('typesTS.js');
+            fs.writeFileSync(distLibTypesJsPath, 'export {}\n', 'utf8');
+            console.log('Wrote', distLibTypesJsPath);
+        } catch (e) {
+            console.warn('Failed to write typesTS.js to dist/_lib:', e);
+        }
+    } catch (err) {
+        console.error(err);
+        process.exitCode = 1;
+    }
+}
+
+void main();