@gqlkit-ts/cli 0.6.0 → 0.7.1

package/src/shared/enum-prefix-detector.ts

@@ -32,6 +32,86 @@ export function buildEnumPrefixCandidate(enumName: string): string {
   return `${toUpperSnakeCase(enumName)}_`;
 }
 
+const IRREGULAR_PLURAL_SEGMENTS = new Map([
+  ["ALIAS", "ALIASES"],
+  ["ANALYSIS", "ANALYSES"],
+  ["CHILD", "CHILDREN"],
+  ["COOKIE", "COOKIES"],
+  ["CRISIS", "CRISES"],
+  ["DIAGNOSIS", "DIAGNOSES"],
+  ["FOOT", "FEET"],
+  ["GOOSE", "GEESE"],
+  ["MAN", "MEN"],
+  ["MOUSE", "MICE"],
+  ["MOVIE", "MOVIES"],
+  ["PERSON", "PEOPLE"],
+  ["THESIS", "THESES"],
+  ["TOOTH", "TEETH"],
+  ["WOMAN", "WOMEN"],
+]);
+
+function isConsonant(char: string): boolean {
+  return /^[BCDFGHJKLMNPQRSTVWXYZ]$/.test(char);
+}
+
+function pluralizeUpperSnakeSegment(segment: string): string {
+  const irregularPlural = IRREGULAR_PLURAL_SEGMENTS.get(segment);
+  if (irregularPlural) {
+    return irregularPlural;
+  }
+
+  if (
+    segment.endsWith("Y") &&
+    segment.length > 1 &&
+    isConsonant(segment.at(-2) ?? "")
+  ) {
+    return `${segment.slice(0, -1)}IES`;
+  }
+
+  if (
+    segment.endsWith("S") ||
+    segment.endsWith("SH") ||
+    segment.endsWith("CH") ||
+    segment.endsWith("X") ||
+    segment.endsWith("Z")
+  ) {
+    return `${segment}ES`;
+  }
+
+  return `${segment}S`;
+}
+
+function buildEnumPrefixCandidates(enumName: string): string[] {
+  const upperSnakeName = toUpperSnakeCase(enumName);
+  const baseCandidate = `${upperSnakeName}_`;
+  const segments = upperSnakeName.split("_");
+  const candidateSegmentSets: string[][] = [segments];
+
+  if (segments.length === 0) {
+    return [baseCandidate];
+  }
+
+  for (const [index, segment] of segments.entries()) {
+    const pluralizedSegment = pluralizeUpperSnakeSegment(segment);
+    if (pluralizedSegment === segment) {
+      continue;
+    }
+
+    const existingCandidates = [...candidateSegmentSets];
+    for (const candidateSegments of existingCandidates) {
+      const nextCandidateSegments = [...candidateSegments];
+      nextCandidateSegments[index] = pluralizedSegment;
+      candidateSegmentSets.push(nextCandidateSegments);
+    }
+  }
+
+  return [
+    ...new Set(
+      candidateSegmentSets.map((candidate) => `${candidate.join("_")}_`),
+    ),
+  ];
+}
+
 export interface DetectEnumPrefixParams {
   readonly enumName: string;
   readonly memberValues: ReadonlyArray<string>;
@@ -71,20 +151,28 @@ export function detectEnumPrefix(
     return { shouldStrip: false, prefix: null };
   }
 
-  const prefixCandidate = buildEnumPrefixCandidate(enumName);
+  for (const prefixCandidate of buildEnumPrefixCandidates(enumName)) {
+    let matches = true;
+
+    for (const value of memberValues) {
+      if (!value.startsWith(prefixCandidate)) {
+        matches = false;
+        break;
+      }
 
-  for (const value of memberValues) {
-    if (!value.startsWith(prefixCandidate)) {
-      return { shouldStrip: false, prefix: null };
+      const stripped = value.slice(prefixCandidate.length);
+      if (stripped === "") {
+        matches = false;
+        break;
+      }
     }
 
-    const stripped = value.slice(prefixCandidate.length);
-    if (stripped === "") {
-      return { shouldStrip: false, prefix: null };
+    if (matches) {
+      return { shouldStrip: true, prefix: prefixCandidate };
     }
   }
 
-  return { shouldStrip: true, prefix: prefixCandidate };
+  return { shouldStrip: false, prefix: null };
 }
 
 /**

package/src/shared/inline-object-utils.ts

@@ -12,7 +12,7 @@ export function isInlineObjectType(type: ts.Type): boolean {
     return false;
   }
   const symbolName = type.symbol.getName();
-  if (symbolName !== "__type") {
+  if (symbolName !== "__type" && symbolName !== "__object") {
     return false;
   }
   if (!(type.flags & ts.TypeFlags.Object)) {

package/src/shared/type-converter.ts

@@ -4,6 +4,21 @@ import type {
 } from "../type-extractor/types/index.js";
 import { PRIMITIVE_TYPE_MAP } from "./constants.js";
 
+const GRAPHQL_INT_MIN = -(2 ** 31);
+const GRAPHQL_INT_MAX = 2 ** 31 - 1;
+
+function numericLiteralToGraphQLScalar(name: string | null): string {
+  const num = Number(name);
+  if (
+    Number.isInteger(num) &&
+    num >= GRAPHQL_INT_MIN &&
+    num <= GRAPHQL_INT_MAX
+  ) {
+    return "Int";
+  }
+  return "Float";
+}
+
 function convertElementTypeName(elementType: TSTypeReference): string {
   if (elementType.kind === "scalar") {
     return elementType.scalarInfo?.scalarName ?? elementType.name ?? "String";
@@ -20,6 +35,18 @@ function convertElementTypeName(elementType: TSTypeReference): string {
   if (elementType.kind === "inlineEnum") {
     return "__INLINE_ENUM__";
   }
+  if (elementType.kind === "union") {
+    return "__INLINE_UNION__";
+  }
+  if (elementType.kind === "stringLiteral") {
+    return "String";
+  }
+  if (elementType.kind === "numericLiteral") {
+    return numericLiteralToGraphQLScalar(elementType.name);
+  }
+  if (elementType.kind === "never") {
+    return "__NEVER__";
+  }
   return elementType.name ?? "String";
 }
 
@@ -90,6 +117,42 @@ export function convertTsTypeToGraphQLType(
     };
   }
 
+  if (tsType.kind === "union") {
+    return {
+      typeName: "__INLINE_UNION__",
+      nullable,
+      list: false,
+      listItemNullable: null,
+    };
+  }
+
+  if (tsType.kind === "stringLiteral") {
+    return {
+      typeName: "String",
+      nullable,
+      list: false,
+      listItemNullable: null,
+    };
+  }
+
+  if (tsType.kind === "numericLiteral") {
+    return {
+      typeName: numericLiteralToGraphQLScalar(tsType.name),
+      nullable,
+      list: false,
+      listItemNullable: null,
+    };
+  }
+
+  if (tsType.kind === "never") {
+    return {
+      typeName: "__NEVER__",
+      nullable,
+      list: false,
+      listItemNullable: null,
+    };
+  }
+
   return {
     typeName: tsType.name ?? "String",
     nullable,

package/src/type-extractor/converter/graphql-converter.ts

@@ -1,3 +1,4 @@
+import { isTypenameFieldName } from "../../auto-type-generator/typename-types.js";
 import {
   BUILT_IN_SCALARS,
   isBuiltInScalar,
@@ -152,6 +153,11 @@ function convertFields(
   const diagnostics: Diagnostic[] = [];
 
   for (const field of extracted.fields) {
+    // Typename discrimination fields are silently excluded from the schema
+    if (isTypenameFieldName(field.name)) {
+      continue;
+    }
+
     const eligibility = isEligibleField({
       fieldName: field.name,
       kind: isInput ? "input" : "object",
@@ -171,9 +177,19 @@ function convertFields(
       continue;
     }
 
+    const graphqlType = convertTsTypeToGraphQLType(
+      field.tsType,
+      field.optional,
+    );
+
+    // Skip fields with never type — they represent impossible values
+    if (graphqlType.typeName === "__NEVER__") {
+      continue;
+    }
+
     fields.push({
       name: field.name,
-      type: convertTsTypeToGraphQLType(field.tsType, field.optional),
+      type: graphqlType,
       description: field.description,
       deprecated: field.deprecated,
       directives: field.directives,

package/src/type-extractor/extractor/field-type-resolver.ts

@@ -1,3 +1,4 @@
+import { relative } from "node:path";
 import ts from "typescript";
 import {
   detectBrandedType,
@@ -7,11 +8,16 @@ import { isInternalTypeSymbol } from "../../shared/constants.js";
 import { extractInlineObjectProperties as extractInlineObjectPropertiesShared } from "../../shared/inline-object-extractor.js";
 import { isInlineObjectType } from "../../shared/inline-object-utils.js";
 import { detectScalarMetadata } from "../../shared/metadata-detector.js";
+import {
+  getSourceLocationFromNode,
+  type SourceLocation,
+} from "../../shared/source-location.js";
 import {
   type DeprecationInfo,
   extractTsDocFromSymbol,
 } from "../../shared/tsdoc-parser.js";
 import {
+  filterNonNullTypeNodes,
   findEnumParentSymbol,
   findNonNullTypeNode,
   getNonNullableTypes,
@@ -25,14 +31,17 @@ import type {
   ScalarMappingContext,
 } from "../mapper/scalar-base-type-mapper.js";
 import { lookupScalarMapping } from "../mapper/scalar-base-type-mapper.js";
+import type { DiagnosticCode } from "../types/diagnostics.js";
 import {
   createArrayType,
   createInlineEnumType,
   createInlineObjectType,
-  createLiteralType,
+  createNeverType,
+  createNumericLiteralType,
   createPrimitiveType,
   createReferenceType,
   createScalarType,
+  createStringLiteralType,
   createUnionType,
 } from "../types/ts-type-reference-factory.js";
 import type {
@@ -41,6 +50,20 @@ import type {
 } from "../types/typescript.js";
 import type { GlobalTypeMapping } from "./type-extractor.js";
 
+export interface DiscoveredTypeEntry {
+  readonly name: string;
+  readonly tsType: ts.Type;
+  readonly tsSymbol: ts.Symbol;
+  readonly sourceFile: string;
+  readonly sourceLocation: SourceLocation;
+}
+
+export interface FieldTypeResolverDiagnostic {
+  readonly code: DiagnosticCode;
+  readonly message: string;
+  readonly severity: "error" | "warning";
+}
+
 export interface FieldTypeResolverContext {
   readonly checker: ts.TypeChecker;
   readonly knownTypeNames: ReadonlySet<string>;
@@ -52,6 +75,10 @@ export interface FieldTypeResolverContext {
   readonly scalarMappingTable: ScalarBaseTypeMappingTable | null;
   /** Current resolution context for scalar mapping (input or output) */
   readonly scalarMappingContext: ScalarMappingContext;
+  /** Mutable map for collecting transitively discovered types */
+  readonly discoveredTypes: Map<string, DiscoveredTypeEntry> | null;
+  /** Mutable array for collecting diagnostics during field type resolution */
+  readonly diagnostics: FieldTypeResolverDiagnostic[];
 }
 
 /**
@@ -141,6 +168,30 @@ function resolveFieldTypeInternal(
       }
     }
 
+    // Handle `T | null` where T is a known union type alias.
+    // TypeScript flattens `T | null` when T is itself a union, losing aliasSymbol.
+    // Recover the alias by inspecting the UnionTypeNode children for a TypeReferenceNode.
+    // Only applies when there is exactly one non-null type node (e.g., `Item | null`),
+    // not when there are multiple (e.g., `User | Post | null` which is an inline union).
+    if (nullable && typeNode && ts.isUnionTypeNode(typeNode)) {
+      const nonNullTypeNodes = filterNonNullTypeNodes(typeNode);
+      if (nonNullTypeNodes.length === 1) {
+        const singleTypeNode = nonNullTypeNodes[0]!;
+        if (ts.isTypeReferenceNode(singleTypeNode)) {
+          const typeName = getTypeNameFromNode(singleTypeNode);
+          const nodeSymbol = checker.getSymbolAtLocation(
+            singleTypeNode.typeName,
+          );
+          if (
+            typeName &&
+            isKnownSchemaType(typeName, nodeSymbol ?? undefined, ctx)
+          ) {
+            return createReferenceType({ name: typeName, nullable });
+          }
+        }
+      }
+    }
+
     const nonNullTypes = getNonNullableTypes(type);
 
     // Check if all non-null types belong to the same enum
@@ -207,11 +258,28 @@ function resolveFieldTypeInternal(
       return { ...innerResult, nullable };
     }
 
-    const memberResults = nonNullTypes.map((t) =>
-      resolveFieldTypeInternal(t, undefined, ctx),
-    );
+    const memberResults = nonNullTypes.map((t) => {
+      const result = resolveFieldTypeInternal(t, undefined, ctx);
+      // If the result is an unresolvable reference and the original type is an
+      // object type with properties, try to expand it as an inline object.
+      // This handles external library types used as union members.
+      // When type discovery is active, discovered types are kept as references
+      // so they can be registered with their original names later.
+      if (
+        result.kind === "reference" &&
+        result.name !== null &&
+        !ctx.knownTypeNames.has(result.name) &&
+        t.flags & ts.TypeFlags.Object &&
+        t.getProperties().length > 0 &&
+        !ctx.discoveredTypes?.has(result.name)
+      ) {
+        return tryExtractAsInlineObject(t, ctx, result.name);
+      }
+      return result;
+    });
 
-    return createUnionType({ members: memberResults, nullable });
+    const aliasName = type.aliasSymbol?.getName() ?? null;
+    return createUnionType({ members: memberResults, nullable, aliasName });
   }
 
   // Array type handling
@@ -231,6 +299,27 @@ function resolveFieldTypeInternal(
     return createArrayType(elementResult);
   }
 
+  // Never type — represents an impossible value, skip this field
+  // Also handles `undefined` which results from `field?: never` (never | undefined simplifies to undefined)
+  if (type.flags & ts.TypeFlags.Never || type.flags & ts.TypeFlags.Undefined) {
+    return createNeverType();
+  }
+
+  // Unknown type — represents arbitrary values, map to JSON scalar (graphql-scalars)
+  if (type.flags & ts.TypeFlags.Unknown) {
+    return createScalarType({
+      name: "JSON",
+      scalarInfo: {
+        scalarName: "JSON",
+        typeName: "unknown",
+        baseType: undefined,
+        isCustom: true,
+        only: null,
+      },
+      nullable: false,
+    });
+  }
+
   // Primitive types
   const typeString = checker.typeToString(type);
 
@@ -247,10 +336,14 @@ function resolveFieldTypeInternal(
     return createPrimitiveType({ name: "boolean", nullable: false });
   }
   if (type.flags & ts.TypeFlags.StringLiteral) {
-    return createLiteralType(typeString.replace(/"/g, ""));
+    return createStringLiteralType(typeString.replace(/"/g, ""));
   }
   if (type.flags & ts.TypeFlags.NumberLiteral) {
-    return createLiteralType(typeString);
+    return createNumericLiteralType(typeString);
+  }
+  // Template literal types (e.g., `prefix-${string}`) represent string subsets
+  if (type.flags & ts.TypeFlags.TemplateLiteral) {
+    return createPrimitiveType({ name: "string", nullable: false });
   }
 
   // Intersection types in field context
@@ -291,12 +384,69 @@ function resolveFieldTypeInternal(
       });
     }
 
-    // 4. Otherwise, treat as inline object
-    return tryExtractAsInlineObject(type, ctx);
+    // 4. Register in discoveredTypes if applicable (same logic as alias expansion)
+    //    This handles non-exported recursive intersection types that would otherwise
+    //    cause cycle detection failures in tryExtractAsInlineObject.
+    if (type.aliasSymbol) {
+      const aliasName = type.aliasSymbol.getName();
+      if (!knownTypeNames.has(aliasName)) {
+        if (ctx.discoveredTypes && !ctx.discoveredTypes.has(aliasName)) {
+          const resolvedAliasSymbol = resolveOriginalSymbol(
+            type.aliasSymbol,
+            checker,
+          );
+          const declarations = resolvedAliasSymbol.getDeclarations();
+          const decl = declarations?.[0];
+          if (decl && !decl.getSourceFile().isDeclarationFile) {
+            const properties = type.getProperties();
+            if (properties.length > 0) {
+              const declSourceFile = decl.getSourceFile();
+              const location = getSourceLocationFromNode(decl) ?? {
+                file: declSourceFile.fileName,
+                line: 1,
+                column: 1,
+              };
+              ctx.discoveredTypes.set(aliasName, {
+                name: aliasName,
+                tsType: type,
+                tsSymbol: resolvedAliasSymbol,
+                sourceFile: relative(process.cwd(), declSourceFile.fileName),
+                sourceLocation: location,
+              });
+              return createReferenceType({ name: aliasName, nullable: false });
+            }
+          }
+        }
+        if (ctx.discoveredTypes?.has(aliasName)) {
+          return createReferenceType({ name: aliasName, nullable: false });
+        }
+      }
+    }
+
+    // 5. Otherwise, treat as inline object
+    return tryExtractAsInlineObject(type, ctx, null);
   }
 
   // Inline object type handling
   if (isInlineObjectType(type)) {
+    // Index signature types (Record<string, T>, { [key: string]: T })
+    // These have no named properties, only index signatures — map to JSONObject (graphql-scalars)
+    const hasStringIndex =
+      checker.getIndexTypeOfType(type, ts.IndexKind.String) !== undefined;
+    if (hasStringIndex && type.getProperties().length === 0) {
+      return createScalarType({
+        name: "JSONObject",
+        scalarInfo: {
+          scalarName: "JSONObject",
+          typeName: "Record",
+          baseType: undefined,
+          isCustom: true,
+          only: null,
+        },
+        nullable: false,
+      });
+    }
+
     // Check if typeNode references a known type
     if (typeNode && ts.isTypeReferenceNode(typeNode)) {
       const typeName = getTypeNameFromNode(typeNode);
@@ -309,13 +459,30 @@ function resolveFieldTypeInternal(
       }
     }
 
-    return tryExtractAsInlineObject(type, ctx);
+    return tryExtractAsInlineObject(type, ctx, null);
   }
 
   // Mapped types (utility types like Omit, Pick, user-defined utilities)
   if (type.flags & ts.TypeFlags.Object) {
     const objectType = type as ts.ObjectType;
     if (objectType.objectFlags & ts.ObjectFlags.Mapped) {
+      // Index signature mapped types (Record<string, T>) — map to JSONObject (graphql-scalars)
+      const hasMappedStringIndex =
+        checker.getIndexTypeOfType(type, ts.IndexKind.String) !== undefined;
+      if (hasMappedStringIndex && type.getProperties().length === 0) {
+        return createScalarType({
+          name: "JSONObject",
+          scalarInfo: {
+            scalarName: "JSONObject",
+            typeName: "Record",
+            baseType: undefined,
+            isCustom: true,
+            only: null,
+          },
+          nullable: false,
+        });
+      }
+
       // Check if typeNode references a known type (schema-defined type)
       if (typeNode && ts.isTypeReferenceNode(typeNode)) {
         const typeName = getTypeNameFromNode(typeNode);
@@ -328,7 +495,7 @@ function resolveFieldTypeInternal(
         }
       }
       // Not a known type - treat as inline object
-      return tryExtractAsInlineObject(type, ctx);
+      return tryExtractAsInlineObject(type, ctx, null);
     }
   }
 
@@ -348,8 +515,42 @@ function resolveFieldTypeInternal(
         ((type as ts.ObjectType).objectFlags & ts.ObjectFlags.Anonymous) !== 0;
 
       if (isAnonymousObject) {
+        // Check if this type alias qualifies for transitive discovery.
+        // Type aliases to object literals used as union members should be
+        // discovered with their original alias name, not expanded as inline
+        // objects with auto-generated names. (#202)
+        if (ctx.discoveredTypes && !ctx.discoveredTypes.has(aliasName)) {
+          const resolvedAliasSymbol = resolveOriginalSymbol(
+            type.aliasSymbol,
+            checker,
+          );
+          const declarations = resolvedAliasSymbol.getDeclarations();
+          const decl = declarations?.[0];
+          if (decl && !decl.getSourceFile().isDeclarationFile) {
+            const properties = type.getProperties();
+            if (properties.length > 0) {
+              const declSourceFile = decl.getSourceFile();
+              const location = getSourceLocationFromNode(decl) ?? {
+                file: declSourceFile.fileName,
+                line: 1,
+                column: 1,
+              };
+              ctx.discoveredTypes.set(aliasName, {
+                name: aliasName,
+                tsType: type,
+                tsSymbol: resolvedAliasSymbol,
+                sourceFile: relative(process.cwd(), declSourceFile.fileName),
+                sourceLocation: location,
+              });
+              return createReferenceType({ name: aliasName, nullable: false });
+            }
+          }
+        }
+        if (ctx.discoveredTypes?.has(aliasName)) {
+          return createReferenceType({ name: aliasName, nullable: false });
+        }
         // Not a known schema type and is an anonymous object - expand to generate Payload type
-        return tryExtractAsInlineObject(type, ctx);
+        return tryExtractAsInlineObject(type, ctx, null);
       }
     }
   }
@@ -411,7 +612,7 @@ function resolveFieldTypeInternal(
           return createReferenceType({ name: symbolName, nullable: false });
         }
         // Type from outside schema files - expand as inline object
-        return tryExtractAsInlineObject(type, ctx);
+        return tryExtractAsInlineObject(type, ctx, null);
       }
 
       // Check for scalar base type mapping
@@ -461,6 +662,30 @@ function resolveFieldTypeInternal(
         }
       }
 
+      // Discover extractable named types for transitive type registration
+      if (ctx.discoveredTypes && !ctx.discoveredTypes.has(symbolName)) {
+        const declarations = resolvedSymbol.getDeclarations();
+        const decl = declarations?.[0];
+        if (decl && !decl.getSourceFile().isDeclarationFile) {
+          const properties = type.getProperties();
+          if (properties.length > 0) {
+            const declSourceFile = decl.getSourceFile();
+            const location = getSourceLocationFromNode(decl) ?? {
+              file: declSourceFile.fileName,
+              line: 1,
+              column: 1,
+            };
+            ctx.discoveredTypes.set(symbolName, {
+              name: symbolName,
+              tsType: type,
+              tsSymbol: resolvedSymbol,
+              sourceFile: relative(process.cwd(), declSourceFile.fileName),
+              sourceLocation: location,
+            });
+          }
+        }
+      }
+
       // Unknown type - still return reference but it will likely cause validation error later
       return createReferenceType({ name: symbolName, nullable: false });
     }
@@ -472,12 +697,28 @@ function resolveFieldTypeInternal(
 function tryExtractAsInlineObject(
   type: ts.Type,
   ctx: InternalFieldTypeContext,
+  hintName: string | null,
 ): TSTypeReference {
   const { visitedTypes, checker } = ctx;
   if (visitedTypes.has(type)) {
-    // Cycle detected, return a placeholder reference
-    const typeName = type.symbol?.getName() ?? "Unknown";
-    return createReferenceType({ name: typeName, nullable: false });
+    // Prefer aliasSymbol (type alias name) over type.symbol (which may be __type for anonymous objects)
+    const candidateName = type.aliasSymbol?.getName() ?? type.symbol?.getName();
+    if (
+      candidateName &&
+      !isInternalTypeSymbol(candidateName) &&
+      (ctx.knownTypeNames.has(candidateName) ||
+        ctx.discoveredTypes?.has(candidateName))
+    ) {
+      // Valid reference target exists in the schema
+      return createReferenceType({ name: candidateName, nullable: false });
+    }
+    // No valid reference target — emit warning and skip field
+    ctx.diagnostics.push({
+      code: "CYCLE_DETECTED",
+      message: "Cycle detected in type resolution; field will be skipped",
+      severity: "warning",
+    });
+    return createNeverType();
   }
 
   visitedTypes.add(type);
@@ -488,6 +729,14 @@ function tryExtractAsInlineObject(
     (propType) => resolveFieldTypeInternal(propType, undefined, ctx),
   );
 
+  // Allow this type to be visited again in sibling union members.
+  // Cycle detection still works because real cycles are caught during the
+  // recursive extractInlineObjectPropertiesShared call above (while the
+  // type is still in visitedTypes). Removing it afterward prevents
+  // false-positive cycle detection when TypeScript shares the same type
+  // object across multiple union members (common with generic .d.ts types).
+  visitedTypes.delete(type);
+
   // Extract type-level TSDoc from the alias symbol if present (Requirement 7.2)
   // Only extract from user-defined types, not built-in TypeScript utility types
   let description: string | null = null;
@@ -511,6 +760,7 @@ function tryExtractAsInlineObject(
     properties: inlineProperties,
     description,
     deprecated,
+    hintName,
   });
 }