@kurotako/ir 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @kurotako/ir
 
+## 0.2.0
+
+### Minor Changes
+
+- 7a50439: IR union type support: `FieldType` gains `ref` and `union` kinds (recursive,
+  `v.lazy`-wrapped schema, hand-written type), a `TypeAlias` registry
+  (`SourceIR.typeAliases?`), the builder API (`f.ref`, `f.union` with
+  `UnionBuilder`, `addTypeAlias`), resolution helpers (`resolveRef`,
+  `resolveTypeAlias`, `iterTypeAliases`, `flattenUnion`) and an exhaustive
+  `scalarTsType`. Validation walks field types recursively (`unresolved_ref`,
+  `unresolved_type_alias`, `type_alias_key_mismatch`), tolerates degenerate
+  unions and reference cycles through a new non-fatal `info` channel on
+  `IrValidation` (`degenerate_union`, `union_cycle`).
+  
+  Bumps `IR_VERSION` from `1` to `2`; `isCompatible` stays strict equality, so a
+  persisted `irVersion: '1'` dump is rejected with `version_incompatible`.
+
 ## 0.1.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -51,10 +51,13 @@ __export(index_exports, {
   ScalarTypeSchema: () => ScalarTypeSchema,
   SourceIrSchema: () => SourceIrSchema,
   StringFormatSchema: () => StringFormatSchema,
+  TypeAliasSchema: () => TypeAliasSchema,
   assertIR: () => assertIR,
   assertSourceIR: () => assertSourceIR,
+  collectRefNames: () => collectRefNames,
   createFields: () => createFields,
   createSourceIR: () => createSourceIR,
+  flattenUnion: () => flattenUnion,
   getSource: () => getSource,
   isCompatible: () => isCompatible,
   isCreateOptional: () => isCreateOptional,
@@ -62,11 +65,15 @@ __export(index_exports, {
   isDbAssigned: () => isDbAssigned,
   iterEntities: () => iterEntities,
   iterFields: () => iterFields,
+  iterTypeAliases: () => iterTypeAliases,
   parseIR: () => parseIR,
   primaryKeyFields: () => primaryKeyFields,
+  refCycleMembers: () => refCycleMembers,
   resolveEntity: () => resolveEntity,
   resolveEnum: () => resolveEnum,
+  resolveRef: () => resolveRef,
   resolveRelationTarget: () => resolveRelationTarget,
+  resolveTypeAlias: () => resolveTypeAlias,
   scalarTsType: () => scalarTsType,
   updateFields: () => updateFields,
   validateIR: () => validateIR,
@@ -131,11 +138,29 @@ var IndexTypeSchema = v.picklist([
   "brin",
   "spgist"
 ]);
-var FieldTypeSchema = v.variant("kind", [
-  v.object({ kind: v.literal("scalar"), scalar: ScalarTypeSchema }),
-  v.object({ kind: v.literal("enum"), ref: v.string() }),
-  v.object({ kind: v.literal("unknown"), hint: v.optional(v.string()) })
-]);
+var FieldTypeSchema = v.lazy(
+  () => v.variant("kind", [
+    v.object({ kind: v.literal("scalar"), scalar: ScalarTypeSchema }),
+    v.object({ kind: v.literal("enum"), ref: v.string() }),
+    v.object({ kind: v.literal("unknown"), hint: v.optional(v.string()) }),
+    v.object({ kind: v.literal("ref"), ref: v.string() }),
+    v.object({
+      kind: v.literal("union"),
+      variants: v.array(FieldTypeSchema),
+      discriminator: v.optional(
+        v.object({
+          propertyName: v.string(),
+          mapping: v.optional(v.record(v.string(), v.string()))
+        })
+      )
+    })
+  ])
+);
+var TypeAliasSchema = v.object({
+  name: v.string(),
+  type: FieldTypeSchema,
+  doc: v.optional(v.string())
+});
 var ConstraintsSchema = v.object({
   min: v.optional(v.number()),
   max: v.optional(v.number()),
@@ -216,7 +241,8 @@ var SourceIrSchema = v.object({
   parser: v.string(),
   parserVersion: v.optional(v.string()),
   entities: v.record(v.string(), EntitySchema),
-  enums: v.record(v.string(), EnumDefSchema)
+  enums: v.record(v.string(), EnumDefSchema),
+  typeAliases: v.optional(v.record(v.string(), TypeAliasSchema))
 });
 var IrSchema = v.object({
   irVersion: v.string(),
@@ -227,7 +253,7 @@ var IrSchema = v.object({
 var v2 = __toESM(require("valibot"), 1);
 
 // src/version.ts
-var IR_VERSION = "1";
+var IR_VERSION = "2";
 function isCompatible(irVersion) {
   return irVersion === IR_VERSION;
 }
@@ -296,7 +322,134 @@ function checkEnumValues(issues, path, values) {
     seen.add(value.name);
   }
 }
-function checkSource(namespace, source, lookupEntity, isNamespacePresent, issues) {
+function walkFieldType(type, path, entity, source, issues, info) {
+  switch (type.kind) {
+    case "scalar":
+    case "unknown":
+      return;
+    case "enum": {
+      const resolved = entity?.enums?.[type.ref] ?? source.enums[type.ref];
+      if (resolved === void 0) {
+        pushIssue(
+          issues,
+          path,
+          "unresolved_enum_ref",
+          `field type references unknown enum '${type.ref}'`
+        );
+      }
+      return;
+    }
+    case "ref": {
+      const known = source.entities[type.ref] !== void 0 || source.typeAliases?.[type.ref] !== void 0;
+      if (!known) {
+        pushIssue(
+          issues,
+          path,
+          "unresolved_ref",
+          `ref '${type.ref}' resolves to no entity and no type alias`
+        );
+      }
+      return;
+    }
+    case "union": {
+      if (type.variants.length < 2) {
+        pushIssue(
+          info,
+          path,
+          "degenerate_union",
+          `union has ${type.variants.length} variant(s); expected at least 2`
+        );
+      }
+      type.variants.forEach((variant2, i) => {
+        walkFieldType(
+          variant2,
+          `${path}.variants.${i}`,
+          entity,
+          source,
+          issues,
+          info
+        );
+      });
+      const mapping = type.discriminator?.mapping;
+      if (mapping !== void 0) {
+        const refVariants = new Set(
+          type.variants.flatMap((vv) => vv.kind === "ref" ? [vv.ref] : [])
+        );
+        for (const [key, target] of Object.entries(mapping)) {
+          if (!refVariants.has(target)) {
+            pushIssue(
+              issues,
+              `${path}.discriminator.mapping.${key}`,
+              "unresolved_type_alias",
+              `discriminator mapping '${key}' -> '${target}' names no ref variant of the union`
+            );
+          }
+        }
+      }
+      return;
+    }
+  }
+}
+function collectRefs(type, out) {
+  if (type.kind === "ref") {
+    out.add(type.ref);
+  } else if (type.kind === "union") {
+    for (const variant2 of type.variants) {
+      collectRefs(variant2, out);
+    }
+  }
+}
+function checkRefCycles(namespace, source, info) {
+  const adjacency = /* @__PURE__ */ new Map();
+  for (const [key, alias] of Object.entries(source.typeAliases ?? {})) {
+    const refs = /* @__PURE__ */ new Set();
+    collectRefs(alias.type, refs);
+    adjacency.set(key, refs);
+  }
+  for (const [key, entity] of Object.entries(source.entities)) {
+    const refs = adjacency.get(key) ?? /* @__PURE__ */ new Set();
+    for (const field of entity.fields) {
+      collectRefs(field.type, refs);
+    }
+    adjacency.set(key, refs);
+  }
+  const state = /* @__PURE__ */ new Map();
+  const stack = [];
+  const reported = /* @__PURE__ */ new Set();
+  const visit = (node) => {
+    state.set(node, "gray");
+    stack.push(node);
+    for (const next of adjacency.get(node) ?? []) {
+      if (!adjacency.has(next)) {
+        continue;
+      }
+      const seen = state.get(next);
+      if (seen === "gray") {
+        const cycle = stack.slice(stack.indexOf(next));
+        const signature = [...cycle].sort().join("|");
+        if (!reported.has(signature)) {
+          reported.add(signature);
+          pushIssue(
+            info,
+            namespace,
+            "union_cycle",
+            `reference cycle: ${[...cycle, next].join(" -> ")}`
+          );
+        }
+      } else if (seen === void 0) {
+        visit(next);
+      }
+    }
+    stack.pop();
+    state.set(node, "black");
+  };
+  for (const node of adjacency.keys()) {
+    if (state.get(node) === void 0) {
+      visit(node);
+    }
+  }
+}
+function checkSource(namespace, source, lookupEntity, isNamespacePresent, issues, info) {
   for (const [key, def] of Object.entries(source.enums)) {
     if (def.name !== key) {
       pushIssue(
@@ -331,17 +484,7 @@ function checkSource(namespace, source, lookupEntity, isNamespacePresent, issues
       }
       fieldNames.add(field.name);
       checkConstraints(issues, `${fPath}.constraints`, field.constraints);
-      if (field.type.kind === "enum") {
-        const resolved = entity.enums?.[field.type.ref] ?? source.enums[field.type.ref];
-        if (resolved === void 0) {
-          pushIssue(
-            issues,
-            fPath,
-            "unresolved_enum_ref",
-            `field '${field.name}' references unknown enum '${field.type.ref}'`
-          );
-        }
-      }
+      walkFieldType(field.type, fPath, entity, source, issues, info);
     }
     for (const [localKey, def] of Object.entries(entity.enums ?? {})) {
       if (def.name !== localKey) {
@@ -439,6 +582,19 @@ function checkSource(namespace, source, lookupEntity, isNamespacePresent, issues
       }
     });
   }
+  for (const [key, alias] of Object.entries(source.typeAliases ?? {})) {
+    const aPath = `${namespace}.typeAliases.${key}`;
+    if (alias.name !== key) {
+      pushIssue(
+        issues,
+        aPath,
+        "type_alias_key_mismatch",
+        `type alias key '${key}' does not match name '${alias.name}'`
+      );
+    }
+    walkFieldType(alias.type, `${aPath}.type`, void 0, source, issues, info);
+  }
+  checkRefCycles(namespace, source, info);
 }
 function validateSourceIR(value) {
   const parsed = v2.safeParse(SourceIrSchema, value);
@@ -447,10 +603,14 @@ function validateSourceIR(value) {
   }
   const source = parsed.output;
   const issues = [];
+  const info = [];
   const lookup = (ns, name) => ns === source.namespace ? source.entities[name] : void 0;
   const isPresent = (ns) => ns === source.namespace;
-  checkSource(source.namespace, source, lookup, isPresent, issues);
-  return issues.length > 0 ? { ok: false, issues } : { ok: true, value: source };
+  checkSource(source.namespace, source, lookup, isPresent, issues, info);
+  if (issues.length > 0) {
+    return { ok: false, issues };
+  }
+  return info.length > 0 ? { ok: true, value: source, info } : { ok: true, value: source };
 }
 function validateIR(value) {
   const parsed = v2.safeParse(IrSchema, value);
@@ -459,6 +619,7 @@ function validateIR(value) {
   }
   const ir = parsed.output;
   const issues = [];
+  const info = [];
   if (!isCompatible(ir.irVersion)) {
     pushIssue(
       issues,
@@ -478,9 +639,12 @@ function validateIR(value) {
         `source key '${key}' does not match namespace '${source.namespace}'`
       );
     }
-    checkSource(source.namespace, source, lookup, isPresent, issues);
+    checkSource(source.namespace, source, lookup, isPresent, issues, info);
+  }
+  if (issues.length > 0) {
+    return { ok: false, issues };
   }
-  return issues.length > 0 ? { ok: false, issues } : { ok: true, value: ir };
+  return info.length > 0 ? { ok: true, value: ir, info } : { ok: true, value: ir };
 }
 function assertIR(value) {
   const result = validateIR(value);
@@ -539,6 +703,123 @@ var EnumBuilderImpl = class {
     return this.#def;
   }
 };
+function checkedScalar(path, t) {
+  if (!v3.is(ScalarTypeSchema, t)) {
+    throw new IrBuildError(path, `unknown scalar type '${t}'`);
+  }
+  return { kind: "scalar", scalar: t };
+}
+var UnionBuilderImpl = class _UnionBuilderImpl {
+  #path;
+  #variants = [];
+  #discriminator;
+  constructor(path) {
+    this.#path = path;
+  }
+  scalar(t) {
+    this.#variants.push(checkedScalar(this.#path, t));
+    return this;
+  }
+  enum(ref) {
+    this.#variants.push({ kind: "enum", ref });
+    return this;
+  }
+  ref(name) {
+    this.#variants.push({ kind: "ref", ref: name });
+    return this;
+  }
+  union(build) {
+    const nested = new _UnionBuilderImpl(this.#path);
+    build(nested);
+    for (const variant2 of nested.#variants) {
+      this.#variants.push(variant2);
+    }
+    return this;
+  }
+  unknown(hint) {
+    this.#variants.push(
+      hint === void 0 ? { kind: "unknown" } : { kind: "unknown", hint }
+    );
+    return this;
+  }
+  discriminator(propertyName, mapping) {
+    this.#discriminator = mapping === void 0 ? { propertyName } : { propertyName, mapping };
+    return this;
+  }
+  build() {
+    if (this.#variants.length < 2) {
+      throw new IrBuildError(
+        this.#path,
+        `union() needs at least 2 variants, got ${this.#variants.length}`
+      );
+    }
+    const mapping = this.#discriminator?.mapping;
+    if (mapping !== void 0) {
+      const refVariants = new Set(
+        this.#variants.flatMap((vv) => vv.kind === "ref" ? [vv.ref] : [])
+      );
+      for (const [key, target] of Object.entries(mapping)) {
+        if (!refVariants.has(target)) {
+          throw new IrBuildError(
+            this.#path,
+            `discriminator mapping '${key}' -> '${target}' names no ref variant`
+          );
+        }
+      }
+    }
+    const type = {
+      kind: "union",
+      variants: this.#variants
+    };
+    if (this.#discriminator !== void 0) {
+      type.discriminator = this.#discriminator;
+    }
+    return type;
+  }
+};
+var TypeAliasBuilderImpl = class {
+  #path;
+  #name;
+  #type = { kind: "unknown" };
+  #doc;
+  constructor(path, name) {
+    this.#path = path;
+    this.#name = name;
+  }
+  scalar(t) {
+    this.#type = checkedScalar(this.#path, t);
+    return this;
+  }
+  enum(ref) {
+    this.#type = { kind: "enum", ref };
+    return this;
+  }
+  ref(name) {
+    this.#type = { kind: "ref", ref: name };
+    return this;
+  }
+  union(build) {
+    const nested = new UnionBuilderImpl(this.#path);
+    build(nested);
+    this.#type = nested.build();
+    return this;
+  }
+  unknown(hint) {
+    this.#type = hint === void 0 ? { kind: "unknown" } : { kind: "unknown", hint };
+    return this;
+  }
+  doc(text) {
+    this.#doc = text;
+    return this;
+  }
+  build() {
+    const alias = { name: this.#name, type: this.#type };
+    if (this.#doc !== void 0) {
+      alias.doc = this.#doc;
+    }
+    return alias;
+  }
+};
 var FieldBuilderImpl = class {
   #path;
   #field;
@@ -566,6 +847,16 @@ var FieldBuilderImpl = class {
     this.#field.type = { kind: "enum", ref };
     return this;
   }
+  ref(name) {
+    this.#field.type = { kind: "ref", ref: name };
+    return this;
+  }
+  union(build) {
+    const builder = new UnionBuilderImpl(this.#path);
+    build(builder);
+    this.#field.type = builder.build();
+    return this;
+  }
   unknown(hint) {
     this.#field.type = hint === void 0 ? { kind: "unknown" } : { kind: "unknown", hint };
     return this;
@@ -810,6 +1101,7 @@ var SourceIrBuilderImpl = class {
   #entities = [];
   #entityNames = /* @__PURE__ */ new Set();
   #enums = {};
+  #typeAliases = {};
   constructor(init) {
     this.#namespace = init.namespace;
     this.#parser = init.parser;
@@ -834,6 +1126,21 @@ var SourceIrBuilderImpl = class {
     this.#entities.push(builder);
     return this;
   }
+  addTypeAlias(name, def) {
+    if (name in this.#typeAliases) {
+      throw new IrBuildError(
+        `${this.#namespace}.typeAliases.${name}`,
+        `duplicate type alias '${name}'`
+      );
+    }
+    const builder = new TypeAliasBuilderImpl(
+      `${this.#namespace}.typeAliases.${name}`,
+      name
+    );
+    def(builder);
+    this.#typeAliases[name] = builder.build();
+    return this;
+  }
   build() {
     const source = {
       namespace: this.#namespace,
@@ -849,6 +1156,9 @@ var SourceIrBuilderImpl = class {
     if (this.#parserVersion !== void 0) {
       source.parserVersion = this.#parserVersion;
     }
+    if (Object.keys(this.#typeAliases).length > 0) {
+      source.typeAliases = this.#typeAliases;
+    }
     try {
       assertSourceIR(source);
     } catch (err) {
@@ -879,6 +1189,112 @@ function resolveEntity(ir, namespace, name) {
 function resolveEnum(source, entity, ref) {
   return entity?.enums?.[ref] ?? source.enums[ref];
 }
+function resolveRef(source, ref) {
+  return source.entities[ref] ?? source.typeAliases?.[ref];
+}
+function resolveTypeAlias(source, name) {
+  return source.typeAliases?.[name];
+}
+function* iterTypeAliases(ir) {
+  for (const [namespace, source] of Object.entries(ir.sources)) {
+    for (const alias of Object.values(source.typeAliases ?? {})) {
+      yield { namespace, alias };
+    }
+  }
+}
+function collectRefNames(type, into = /* @__PURE__ */ new Set()) {
+  if (type.kind === "ref") {
+    into.add(type.ref);
+  } else if (type.kind === "union") {
+    for (const variant2 of type.variants) {
+      collectRefNames(variant2, into);
+    }
+  }
+  return into;
+}
+function refCycleMembers(source) {
+  const adjacency = /* @__PURE__ */ new Map();
+  const edgesFor = (key) => {
+    let set = adjacency.get(key);
+    if (set === void 0) {
+      set = /* @__PURE__ */ new Set();
+      adjacency.set(key, set);
+    }
+    return set;
+  };
+  for (const [key, alias] of Object.entries(source.typeAliases ?? {})) {
+    collectRefNames(alias.type, edgesFor(key));
+  }
+  for (const [key, entity] of Object.entries(source.entities)) {
+    const set = edgesFor(key);
+    for (const field of entity.fields) {
+      collectRefNames(field.type, set);
+    }
+  }
+  const canReachSelf = (start) => {
+    const seen = /* @__PURE__ */ new Set();
+    const stack = [...adjacency.get(start) ?? []];
+    while (stack.length > 0) {
+      const node = stack.pop();
+      if (node === void 0) {
+        break;
+      }
+      if (node === start) {
+        return true;
+      }
+      if (seen.has(node) || !adjacency.has(node)) {
+        continue;
+      }
+      seen.add(node);
+      for (const next of adjacency.get(node) ?? []) {
+        stack.push(next);
+      }
+    }
+    return false;
+  };
+  const members = /* @__PURE__ */ new Set();
+  for (const node of adjacency.keys()) {
+    if (canReachSelf(node)) {
+      members.add(node);
+    }
+  }
+  return members;
+}
+function fieldTypeKey(type) {
+  switch (type.kind) {
+    case "scalar":
+      return `scalar:${type.scalar}`;
+    case "enum":
+      return `enum:${type.ref}`;
+    case "ref":
+      return `ref:${type.ref}`;
+    case "unknown":
+      return `unknown:${type.hint ?? ""}`;
+    case "union":
+      return `union:${flattenUnion(type).map(fieldTypeKey).join(",")}`;
+  }
+}
+function flattenUnion(type) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (t) => {
+    if (t.kind === "union") {
+      for (const variant2 of t.variants) {
+        push(variant2);
+      }
+      return;
+    }
+    const key = fieldTypeKey(t);
+    if (!seen.has(key)) {
+      seen.add(key);
+      out.push(t);
+    }
+  };
+  for (const variant2 of type.variants) {
+    push(variant2);
+  }
+  return out;
+}
 function isCrossSource(fromNamespace, rel) {
   return rel.target.namespace !== fromNamespace;
 }
@@ -931,10 +1347,16 @@ function scalarTsType(type) {
   switch (type.kind) {
     case "enum":
       return type.ref;
+    case "ref":
+      return type.ref;
     case "unknown":
       return "unknown";
     case "scalar":
       return mapScalar(type.scalar);
+    case "union":
+      return flattenUnion(type).map(
+        (variant2) => variant2.kind === "union" ? `(${scalarTsType(variant2)})` : scalarTsType(variant2)
+      ).join(" | ");
   }
 }
 function mapScalar(scalar) {
@@ -982,10 +1404,13 @@ function mapScalar(scalar) {
   ScalarTypeSchema,
   SourceIrSchema,
   StringFormatSchema,
+  TypeAliasSchema,
   assertIR,
   assertSourceIR,
+  collectRefNames,
   createFields,
   createSourceIR,
+  flattenUnion,
   getSource,
   isCompatible,
   isCreateOptional,
@@ -993,11 +1418,15 @@ function mapScalar(scalar) {
   isDbAssigned,
   iterEntities,
   iterFields,
+  iterTypeAliases,
   parseIR,
   primaryKeyFields,
+  refCycleMembers,
   resolveEntity,
   resolveEnum,
+  resolveRef,
   resolveRelationTarget,
+  resolveTypeAlias,
   scalarTsType,
   updateFields,
   validateIR,