ajsc 1.0.0

package/src/JSONSchemaConverter.ts

@@ -0,0 +1,459 @@
+import { JSONSchema7, JSONSchema7Definition } from "json-schema";
+import { ConverterOptions, IRNode, SignatureOccurrences } from "./types.js";
+
+/**
+ * JSONSchemaConverter converts a JSON Schema (Draft‑07) into an
+ * intermediate representation (IR) that can later be transformed
+ * into target language code via a language plugin.
+ *
+ * This implementation now supports internal definitions via both
+ * "$defs" and "definitions", and resolves local "$ref" pointers.
+ */
+export class JSONSchemaConverter {
+  private ir: IRNode;
+  // The root schema is stored to support reference resolution.
+  private rootSchema: JSONSchema7Definition | null = null;
+  // Keep track of the occurrences of each schema signature and the schema/property names
+  // used to reference the signature.
+  private signatureOccurrences: SignatureOccurrences = new Map();
+
+  get irNode(): IRNode {
+    return this.ir;
+  }
+
+  get signatureOccurrencesMap(): SignatureOccurrences {
+    return this.signatureOccurrences;
+  }
+
+  constructor(
+    schema: JSONSchema7Definition,
+    private opts?: ConverterOptions,
+  ) {
+    if (typeof schema === "object") {
+      schema.title = schema.title || "Root";
+    }
+
+    // Optionally validate the schema.
+    if (this.opts?.validateSchema) {
+      this.validateSchema(schema);
+    }
+
+    // Resolve references (for now, this is a placeholder).
+    const resolvedSchema = this.resolveReferences(schema);
+
+    // Store the root schema (if it is an object) to support local $ref resolution.
+    if (typeof resolvedSchema === "object") {
+      this.rootSchema = resolvedSchema;
+    }
+
+    // Convert the resolved schema to our intermediate representation.
+    let ir = this.convertToIR(resolvedSchema);
+
+    // add calculated signature occurrences by traversing the IR for all object types
+
+    // Apply any custom IR transformation.
+    if (this.opts?.transform) {
+      ir = this.opts.transform(ir);
+    }
+
+    this.ir = ir;
+  }
+
+  private calcObjSignatureOccurrences(
+    schema: JSONSchema7Definition & {
+      type: "object";
+      properties: Record<string, JSONSchema7Definition>;
+    },
+    node: IRNode & { name: string },
+  ): string {
+    // If no path then it's the root object
+    if (!node.path) {
+      return "";
+    }
+
+    const signature = this.getSchemaSignature(schema);
+
+    if (Object.keys(node.properties ?? {}).length === 0) {
+      // empty object - can be extended with options ie: emptyObjectAsUnknown
+      return signature;
+    }
+
+    if (this.signatureOccurrences.has(signature)) {
+      const occurrences = this.signatureOccurrences.get(signature)!;
+      occurrences.total += 1;
+
+      const foundPath = occurrences.occurrences.find(
+        (x) => x.nodePath === node.path,
+      );
+      if (foundPath) {
+        foundPath.count += 1;
+      } else {
+        occurrences.occurrences.push({ node, nodePath: node.path, count: 1 });
+      }
+
+      this.signatureOccurrences.set(signature, occurrences);
+    } else {
+      this.signatureOccurrences.set(signature, {
+        total: 1,
+        occurrences: [{ node, nodePath: node.path, count: 1 }],
+        signature,
+      });
+    }
+
+    return signature;
+  }
+
+  /**
+   * Recursively converts a JSON Schema definition into an IRNode.
+   *
+   * This method now handles $ref resolution (using the root schema),
+   * combinators (oneOf, anyOf, allOf), as well as enums, const, objects,
+   * arrays, and primitives.
+   */
+  private convertSchema(
+    schema: JSONSchema7Definition,
+    ctx: {
+      path: string;
+    },
+  ): IRNode {
+    if (!schema) {
+      // Return an unknown
+      return {
+        type: "null",
+        path: ctx.path,
+      };
+    }
+    // Handle boolean schemas.
+    if (typeof schema === "boolean") {
+      if (schema === true) {
+        // A schema of 'true' accepts any value.
+        return {
+          type: "object",
+          properties: {},
+          path: ctx.path,
+        };
+      } else {
+        throw new Error(
+          "Encountered JSON Schema 'false', which is not supported.",
+        );
+      }
+    }
+
+    // If the schema contains a $ref, resolve it.
+    if (schema.$ref) {
+      const resolved = this.resolveRef(schema);
+      return this.convertSchema(resolved, ctx);
+    }
+
+    // Handle combinators.
+    if (schema.oneOf) {
+      const options = schema.oneOf.map((subSchema) =>
+        this.convertSchema(subSchema, ctx),
+      );
+      return {
+        type: "union",
+        options,
+        constraints: { combinator: "oneOf" },
+        path: ctx.path,
+      };
+    }
+    if (schema.anyOf) {
+      const options = schema.anyOf.map((subSchema) =>
+        this.convertSchema(subSchema, ctx),
+      );
+      return {
+        type: "union",
+        options,
+        constraints: { combinator: "anyOf" },
+        path: ctx.path,
+      };
+    }
+    if (schema.allOf) {
+      const options = schema.allOf.map((subSchema) =>
+        this.convertSchema(subSchema, ctx),
+      );
+      return {
+        type: "intersection",
+        options,
+        path: ctx.path,
+      };
+    }
+
+    // Handle "enum".
+    if (schema.enum) {
+      return {
+        type: "enum",
+        values: schema.enum,
+        path: ctx.path,
+      };
+    }
+
+    // Handle "const".
+    if (schema.const !== undefined) {
+      return {
+        type: "literal",
+        constraints: { value: schema.const },
+        path: ctx.path,
+      };
+    }
+
+    // Process based on the "type" keyword.
+    if (schema.type) {
+      // If multiple types are provided, treat as a union.
+      if (Array.isArray(schema.type)) {
+        const options = schema.type.map((t) =>
+          this.convertSchema({ ...schema, type: t }, ctx),
+        );
+        return {
+          type: "union",
+          options,
+          path: ctx.path,
+        };
+      } else {
+        switch (schema.type) {
+          case "object": {
+            const name = this.getTypeName(schema, ctx);
+
+            const node: IRNode & {
+              name: string;
+              properties: {};
+              type: "object";
+            } = {
+              type: "object",
+              properties: {},
+              path: ctx.path,
+              name,
+            };
+
+            if (schema.properties) {
+              for (const key in schema.properties) {
+                const propSchema = schema.properties[key];
+
+                let child = this.convertSchema(propSchema, {
+                  path: ctx.path ? `${ctx.path}.${key}` : key,
+                });
+
+                // Mark the property as required if listed in the "required" array.
+                child.required = schema.required
+                  ? schema.required.includes(key)
+                  : false;
+                node.properties![key] = child;
+              }
+            }
+
+            node.signature = this.calcObjSignatureOccurrences(
+              schema as JSONSchema7 & {
+                type: "object";
+                properties: Record<string, JSONSchema7Definition>;
+              },
+              node,
+            );
+
+            return node;
+          }
+          case "array": {
+            const name = this.getTypeName(schema, ctx);
+
+            const node: IRNode & { name: string } = {
+              type: "array",
+              path: ctx.path,
+              name,
+            };
+
+            if (schema.items) {
+              if (Array.isArray(schema.items)) {
+                // For tuple validation, treat as a union of the item types.
+                const options = schema.items.map((item, i) =>
+                  this.convertSchema(item, ctx),
+                );
+                node.items = { type: "union", options, path: ctx.path };
+              } else {
+                node.items = this.convertSchema(schema.items, {
+                  path: ctx.path ? `${ctx.path}.0` : "0",
+                });
+              }
+            }
+            return node;
+          }
+          case "string":
+          case "number":
+          case "integer":
+          case "boolean":
+          case "null": {
+            const node: IRNode = { type: schema.type, path: ctx.path };
+            node.constraints = {};
+            if (schema.pattern) node.constraints.pattern = schema.pattern;
+            if (schema.minLength !== undefined)
+              node.constraints.minLength = schema.minLength;
+            if (schema.maxLength !== undefined)
+              node.constraints.maxLength = schema.maxLength;
+            if (schema.minimum !== undefined)
+              node.constraints.minimum = schema.minimum;
+            if (schema.maximum !== undefined)
+              node.constraints.maximum = schema.maximum;
+            return node;
+          }
+          default:
+            throw new Error(
+              `Unsupported schema type: ${schema.type} - ${JSON.stringify(schema)}`,
+            );
+        }
+      }
+    }
+
+    // Fallback: if no type is provided, assume an object.
+    return { type: "object", properties: {}, path: ctx.path };
+  }
+
+  /**
+   * Converts a JSON Schema definition to target code using the provided language plugin.
+   */
+  public convertToIRSchema(schema: JSONSchema7Definition): IRNode {
+    // reset the root schema
+    this.rootSchema = null;
+
+    // Optionally validate the schema.
+    if (this.opts?.validateSchema) {
+      this.validateSchema(schema);
+    }
+
+    // Resolve references (for now, this is a placeholder).
+    const resolvedSchema = this.resolveReferences(schema);
+
+    // Store the root schema (if it is an object) to support local $ref resolution.
+    if (typeof resolvedSchema === "object") {
+      this.rootSchema = resolvedSchema;
+    }
+
+    // Convert the resolved schema to our intermediate representation.
+    let ir = this.convertToIR(resolvedSchema);
+
+    // Apply any custom IR transformation.
+    if (this.opts?.transform) {
+      ir = this.opts.transform(ir);
+    }
+
+    return ir;
+  }
+
+  private validateSchema(schema: JSONSchema7Definition): void {
+    // Implement or integrate with a JSON Schema validator if desired.
+    // For now, we assume the schema is valid.
+  }
+
+  /**
+   * A placeholder for reference resolution. In a more advanced implementation,
+   * this method might inline external references or perform more complex processing.
+   * ie: fetching a remote/url $def
+   */
+  private resolveReferences(
+    schema: JSONSchema7Definition,
+  ): JSONSchema7Definition {
+    // For this implementation, simply return the schema unchanged.
+    return schema;
+  }
+
+  private convertToIR(schema: JSONSchema7Definition): IRNode {
+    return this.convertSchema(schema, { path: "" });
+  }
+
+  private getNameFromPath(path: string): string | undefined {
+    // ignore numbers
+    const split = path.split(".").filter((x) => !x.match(/^\d+$/));
+
+    return split[split.length - 1] || undefined;
+  }
+
+  private getNextObjectSequence(): number {
+    return this.signatureOccurrences.size;
+  }
+
+  private getParentNameFromPath(path: string): string | undefined {
+    const split = path.split(".").filter((x) => !x.match(/^\d+$/));
+    // ignore numbers
+    return split[split.length - 2] || undefined;
+  }
+
+  /**
+   * Generates a unique signature for a schema.
+   * Uses a stable JSON.stringify that sorts keys to ensure that
+   * semantically equivalent schemas produce the same string.
+   */
+  private getSchemaSignature(schema: JSONSchema7Definition): string {
+    function sortKeys(obj: any): any {
+      if (typeof obj !== "object" || obj === null) return obj;
+      if (Array.isArray(obj)) return obj.map(sortKeys);
+      const sorted: any = {};
+      Object.keys(obj)
+        .sort()
+        .forEach((key) => {
+          sorted[key] = sortKeys(obj[key]);
+        });
+      return sorted;
+    }
+    return this.simpleHash(JSON.stringify(sortKeys(schema))).toString();
+  }
+
+  private getTypeName(schema: JSONSchema7, ctx: { path: string }): string {
+    return (
+      schema.title ||
+      this.getNameFromPath(ctx.path) ||
+      `Object${this.getNextObjectSequence()}`
+    );
+  }
+
+  /**
+   * Resolves a local $ref using the stored root schema.
+   *
+   * This method expects local references (starting with "#/") and uses a simple
+   * JSON Pointer resolution algorithm.
+   */
+  private resolveRef(schema: JSONSchema7): JSONSchema7Definition {
+    if (!schema.$ref) return schema as unknown as JSONSchema7Definition;
+    if (!this.rootSchema || typeof this.rootSchema !== "object") {
+      throw new Error("Root schema not available for reference resolution.");
+    }
+    const ref = schema.$ref;
+    if (!ref.startsWith("#/")) {
+      throw new Error(
+        `Only local references are supported. Encountered: ${ref}`,
+      );
+    }
+    return this.resolvePointer(ref, this.rootSchema);
+  }
+
+  /**
+   * Resolves a JSON Pointer (RFC 6901) within the given document.
+   *
+   * @param pointer A JSON Pointer string (e.g., "#/definitions/Foo" or "#/$defs/Bar")
+   * @param document The root document object.
+   */
+  private resolvePointer(pointer: string, document: any): any {
+    // Remove the leading '#' character.
+    if (pointer[0] === "#") {
+      pointer = pointer.substring(1);
+    }
+    if (!pointer) return document;
+    // Split the pointer by "/" and filter out empty parts.
+    const parts = pointer.split("/").filter((part) => part);
+    let current = document;
+    for (const part of parts) {
+      // Unescape any "~1" to "/" and "~0" to "~".
+      const unescaped = part.replace(/~1/g, "/").replace(/~0/g, "~");
+      current = current[unescaped];
+      if (current === undefined) {
+        throw new Error(`Reference "${pointer}" not found in document.`);
+      }
+    }
+    return current;
+  }
+
+  private simpleHash(str: string) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      hash = (hash << 5) - hash + str.charCodeAt(i);
+      hash |= 0; // Convert to 32bit integer
+    }
+    return hash;
+  }
+}

package/src/TypescriptBaseConverter.ts

@@ -0,0 +1,161 @@
+import { IRNode, SignatureOccurrenceValue } from "./types.js";
+import { toPascalCase } from "./utils/to-pascal-case.js";
+
+export type RefTypeName = string;
+
+export type RefTypes = [
+  SignatureOccurrenceValue["signature"],
+  RefTypeName,
+  { code: string },
+][];
+
+export class TypescriptBaseConverter {
+  /**
+   * Recursively generates a TypeScript type string for the given IR node.
+   *
+   * @param ir - The IR node to convert.
+   * @returns A string representing the TypeScript type.
+   */
+  protected generateType(
+    ir: IRNode,
+    utils: { getReferencedType(ir: IRNode): string | undefined },
+  ): string {
+    switch (ir.type) {
+      case "object":
+        const referencedType = utils.getReferencedType(ir);
+
+        if (referencedType) {
+          return referencedType;
+        }
+
+        return this.generateObjectType(ir, utils);
+      case "array":
+        if (ir.items) {
+          return `Array<${this.generateType(ir.items, utils)}>`;
+        }
+
+        return "any[]";
+      case "string":
+        return "string";
+      case "number":
+      case "integer":
+        return "number";
+      case "boolean":
+        return "boolean";
+      case "null":
+        return "null";
+      case "literal":
+        // For literal types, output a literal value (string, number, etc.)
+        return typeof ir.constraints?.value === "string"
+          ? JSON.stringify(ir.constraints.value)
+          : String(ir.constraints?.value);
+      case "enum":
+        // Create a union of literal types from the enum values.
+        if (ir.values && ir.values.length > 0) {
+          return ir.values.map((v) => JSON.stringify(v)).join(" | ");
+        }
+        return "never";
+      case "union":
+        if (ir.options && ir.options.length > 0) {
+          return ir.options
+            .map((opt) => this.generateType(opt, utils))
+            .join(" | ");
+        }
+        return "never";
+      case "intersection":
+        if (ir.options && ir.options.length > 0) {
+          return ir.options
+            .map((opt) => this.generateType(opt, utils))
+            .join(" & ");
+        }
+        return "never";
+      default:
+        return "any";
+    }
+  }
+
+  /**
+   * Generates a TypeScript object type (as an inline type literal) from the given IR node.
+   *
+   * @param ir - The IR node of type "object".
+   * @returns A string representing the object type.
+   */
+  protected generateObjectType(
+    ir: IRNode,
+    utils: { getReferencedType(ir: IRNode): string | undefined },
+  ): string {
+    if (ir.properties) {
+      const props = Object.keys(ir.properties).map((key) => {
+        const prop = ir.properties![key];
+        // Append '?' if the property is not required.
+        const optional = prop.required ? "" : "?";
+        return `${this.isValidIdentifier(key) ? key : `"${key}"`}${optional}: ${this.generateType(prop, utils)};`;
+      });
+
+      if (!props.length) {
+        return "Record<string | number, unknown>";
+      }
+
+      return `{ ${props.join(" ")} }`;
+    }
+    return "Record<string | number, unknown>";
+  }
+
+  protected isValidIdentifier(name: string): boolean {
+    return /^[a-zA-Z_$][0-9a-zA-Z_$]*$/.test(name);
+  }
+
+  /**
+   * Parses a list of dot-separated paths into an array of string arrays.
+   * Removes any "0" character segments.
+   *
+   * @param list
+   * @protected
+   */
+  protected parsePaths(list: string[]): string[][] {
+    return list.map((item) =>
+      item.split(".").filter((segment) => segment !== "0"),
+    );
+  }
+
+  /**
+   * Returns the longest common prefix (sequence) among an array of string arrays.
+   * @param paths - An array of string arrays.
+   * @returns An array representing the common sequence.
+   *
+   * @example
+   *  const arrays = [
+   *      ["organizations", "migration", "step", "create_regions"],
+   *      ["organizations", "migration", "step", "create_location_groups"],
+   *      ["organizations", "migration", "step", "create_locations"],
+   *      ["organizations", "migration", "step", "create_locations_bolos"],
+   *   ];
+   *
+   *   console.log(commonSequence(arrays)); // Output: ["organizations", "migration", "step"]
+   *
+   */
+  protected commonSequence(paths: string[][]): string[] {
+    if (paths.length === 0) return [];
+
+    const common: string[] = [];
+    for (let i = 0; i < paths[0].length; i++) {
+      const segment = paths[0][i];
+      if (paths.every((path) => path[i] === segment)) {
+        common.push(segment);
+      } else {
+        break;
+      }
+    }
+    return common;
+  }
+
+  protected makeTypeReferenceName(
+    signatureOccurrences: SignatureOccurrenceValue["occurrences"],
+  ): string {
+    const paths = this.parsePaths(
+      signatureOccurrences.map((occurrence) => occurrence.nodePath),
+    );
+    const common = this.commonSequence(paths);
+    return common.map((str) => toPascalCase(str)).join("");
+  }
+}