@gqlkit-ts/cli 0.1.0 → 0.3.0

package/src/type-extractor/extractor/type-name-collector.ts

@@ -0,0 +1,130 @@
+import ts from "typescript";
+import {
+  isExported,
+  resolveOriginalSymbol,
+} from "../../shared/typescript-utils.js";
+
+export interface TypeNameCollectionResult {
+  readonly typeNames: ReadonlySet<string>;
+  readonly typeSymbols: ReadonlyMap<string, ts.Symbol>;
+  /**
+   * Maps underlying type symbols to their schema type names.
+   * For `type User = ExternalUser;`, maps ExternalUser's symbol to "User".
+   * This allows recognizing `ExternalUser` as `User` in field types.
+   */
+  readonly underlyingSymbolToTypeName: ReadonlyMap<ts.Symbol, string>;
+}
+
+/**
+ * Collects all declared type names from exported type declarations.
+ *
+ * Used in Phase 1 of the 2-phase type extraction process to gather
+ * all schema-defined type names before processing field types.
+ *
+ * Handles:
+ * - Direct type declarations (type, interface, enum)
+ * - Named re-exports: `export type { Foo } from "..."`
+ * - Wildcard re-exports: `export type * from "..."`
+ */
+export function collectDeclaredTypeNames(
+  program: ts.Program,
+  sourceFiles: ReadonlyArray<string>,
+): TypeNameCollectionResult {
+  const typeNames = new Set<string>();
+  const typeSymbols = new Map<string, ts.Symbol>();
+  const underlyingSymbolToTypeName = new Map<ts.Symbol, string>();
+  const checker = program.getTypeChecker();
+
+  for (const filePath of sourceFiles) {
+    const sourceFile = program.getSourceFile(filePath);
+    if (!sourceFile) continue;
+
+    ts.forEachChild(sourceFile, (node) => {
+      // Direct type declarations
+      if (ts.isTypeAliasDeclaration(node) && isExported(node)) {
+        const name = node.name.getText(sourceFile);
+        typeNames.add(name);
+        const symbol = checker.getSymbolAtLocation(node.name);
+        if (symbol) {
+          typeSymbols.set(name, resolveOriginalSymbol(symbol, checker));
+
+          // For type aliases like `type User = ExternalUser;`,
+          // also track the underlying type's symbol
+          const type = checker.getTypeAtLocation(node.type);
+          if (type.symbol) {
+            const underlyingSymbol = resolveOriginalSymbol(
+              type.symbol,
+              checker,
+            );
+            underlyingSymbolToTypeName.set(underlyingSymbol, name);
+          }
+        }
+      }
+      if (ts.isInterfaceDeclaration(node) && isExported(node)) {
+        const name = node.name.getText(sourceFile);
+        typeNames.add(name);
+        const symbol = checker.getSymbolAtLocation(node.name);
+        if (symbol) {
+          typeSymbols.set(name, resolveOriginalSymbol(symbol, checker));
+        }
+      }
+      if (ts.isEnumDeclaration(node) && isExported(node)) {
+        const name = node.name.getText(sourceFile);
+        typeNames.add(name);
+        const symbol = checker.getSymbolAtLocation(node.name);
+        if (symbol) {
+          typeSymbols.set(name, resolveOriginalSymbol(symbol, checker));
+        }
+      }
+
+      // Re-exports: `export type { ... } from "..."` or `export type * from "..."`
+      if (ts.isExportDeclaration(node) && node.isTypeOnly) {
+        if (node.exportClause) {
+          // Named re-exports: `export type { Foo, Bar } from "..."`
+          if (ts.isNamedExports(node.exportClause)) {
+            for (const element of node.exportClause.elements) {
+              // Use the exported name (element.name), not the property name
+              const name = element.name.getText(sourceFile);
+              typeNames.add(name);
+              const symbol = checker.getSymbolAtLocation(element.name);
+              if (symbol) {
+                typeSymbols.set(name, resolveOriginalSymbol(symbol, checker));
+              }
+            }
+          }
+        } else if (node.moduleSpecifier) {
+          // Wildcard re-exports: `export type * from "..."`
+          const moduleSymbol = checker.getSymbolAtLocation(
+            node.moduleSpecifier,
+          );
+          if (moduleSymbol) {
+            const exports = checker.getExportsOfModule(moduleSymbol);
+            for (const exp of exports) {
+              const name = exp.getName();
+              // Check if the export is a type (not a value)
+              if (isTypeExport(exp)) {
+                typeNames.add(name);
+                typeSymbols.set(name, resolveOriginalSymbol(exp, checker));
+              }
+            }
+          }
+        }
+      }
+    });
+  }
+
+  return { typeNames, typeSymbols, underlyingSymbolToTypeName };
+}
+
+/**
+ * Checks if a symbol represents a type export (not a value export).
+ */
+function isTypeExport(symbol: ts.Symbol): boolean {
+  const flags = symbol.flags;
+  return (
+    (flags & ts.SymbolFlags.Type) !== 0 ||
+    (flags & ts.SymbolFlags.TypeAlias) !== 0 ||
+    (flags & ts.SymbolFlags.Interface) !== 0 ||
+    (flags & ts.SymbolFlags.Enum) !== 0
+  );
+}

package/src/type-extractor/index.ts

@@ -0,0 +1,20 @@
+export type {
+  CollectedScalarType,
+  ConfigScalarMapping,
+  DescriptionSource,
+  ScalarMetadataInfo,
+} from "./collector/scalar-collector.js";
+
+export type { ExtractTypesResult } from "./extract-types.js";
+
+export type {
+  Diagnostic,
+  DiagnosticCode,
+  Diagnostics,
+  ExtractedTypeInfo,
+  FieldInfo,
+  GraphQLFieldType,
+  GraphQLTypeInfo,
+  GraphQLTypeKind,
+  SourceLocation,
+} from "./types/index.js";

package/src/type-extractor/mapper/scalar-base-type-mapper.ts

@@ -0,0 +1,265 @@
+/**
+ * ScalarBaseTypeMapper builds a mapping from base type symbols to scalar names.
+ *
+ * This enables automatic mapping of base types (e.g., Date) to their corresponding
+ * scalar types (e.g., DateTime) when used in field types.
+ *
+ * The mapper supports:
+ * - Input/output context-aware lookups
+ * - Conflict detection when multiple scalars share the same base type
+ * - Symbol-based comparison for accurate type matching
+ */
+
+import ts from "typescript";
+import type { ScalarMetadataInfo } from "../collector/scalar-collector.js";
+
+/**
+ * Information about a scalar mapping from base type to scalar name.
+ */
+export interface ScalarBaseTypeMapping {
+  /** GraphQL scalar name */
+  readonly scalarName: string;
+  /** Usage constraint from GqlScalar definition */
+  readonly only: "input" | "output" | null;
+  /** Source scalar type name for diagnostics */
+  readonly sourceTypeName: string;
+}
+
+/**
+ * Result of a scalar mapping lookup.
+ */
+export interface ScalarMappingLookupResult {
+  readonly mapping: ScalarBaseTypeMapping | null;
+  readonly conflict: ScalarMappingConflict | null;
+}
+
+/**
+ * Information about a scalar mapping conflict.
+ */
+export interface ScalarMappingConflict {
+  readonly code: "AMBIGUOUS_SCALAR_BASE_TYPE";
+  readonly baseTypeSymbol: ts.Symbol;
+  readonly conflictingScalars: ReadonlyArray<{
+    readonly scalarName: string;
+    readonly only: "input" | "output" | null;
+  }>;
+}
+
+/**
+ * Context for scalar mapping: input (for args/input types) or output (for return types/object types).
+ */
+export type ScalarMappingContext = "input" | "output";
+
+/**
+ * Mapping table built from scalar definitions.
+ */
+export interface ScalarBaseTypeMappingTable {
+  /** Maps base type symbol to scalar mappings for input context */
+  readonly inputMappings: ReadonlyMap<ts.Symbol, ScalarBaseTypeMapping>;
+  /** Maps base type symbol to scalar mappings for output context */
+  readonly outputMappings: ReadonlyMap<ts.Symbol, ScalarBaseTypeMapping>;
+  /** Conflicts detected during table construction */
+  readonly conflicts: ReadonlyMap<ts.Symbol, ScalarMappingConflict>;
+}
+
+/**
+ * Parameters for building a scalar mapping table.
+ */
+export interface BuildScalarMappingTableParams {
+  readonly detectedScalars: ReadonlyArray<ScalarMetadataInfo>;
+  readonly checker: ts.TypeChecker;
+  readonly program: ts.Program;
+}
+
+/**
+ * Extract the base type symbol from a scalar type.
+ * For GqlScalar<"DateTime", Date>, this returns the symbol for Date.
+ */
+function extractBaseTypeSymbol(
+  scalarInfo: ScalarMetadataInfo,
+  checker: ts.TypeChecker,
+  program: ts.Program,
+): ts.Symbol | null {
+  const sourceFile = program.getSourceFile(scalarInfo.sourceFile);
+  if (!sourceFile) {
+    return null;
+  }
+
+  let foundSymbol: ts.Symbol | null = null;
+
+  ts.forEachChild(sourceFile, (node) => {
+    if (ts.isTypeAliasDeclaration(node)) {
+      const name = node.name.getText(sourceFile);
+      if (name === scalarInfo.typeName) {
+        const symbol = checker.getSymbolAtLocation(node.name);
+        if (symbol) {
+          const type = checker.getDeclaredTypeOfSymbol(symbol);
+          // GqlScalar is an intersection type: Base & { " $gqlkitScalar"?: ... }
+          // We need to extract the Base type from this intersection
+          if (type.isIntersection()) {
+            for (const member of type.types) {
+              // Skip the metadata object type
+              if (member.getProperty(" $gqlkitScalar")) {
+                continue;
+              }
+              // This should be the base type
+              if (member.symbol) {
+                foundSymbol = member.symbol;
+                return;
+              }
+            }
+          }
+        }
+      }
+    }
+  });
+
+  return foundSymbol;
+}
+
+/**
+ * Builds a scalar mapping table from detected scalars.
+ *
+ * This function:
+ * 1. Extracts base type symbols from each scalar definition
+ * 2. Groups mappings by input/output context based on the `only` constraint
+ * 3. Detects conflicts when multiple scalars share the same base type in a context
+ */
+export function buildScalarMappingTable(
+  params: BuildScalarMappingTableParams,
+): ScalarBaseTypeMappingTable {
+  const { detectedScalars, checker, program } = params;
+
+  const inputMappings = new Map<ts.Symbol, ScalarBaseTypeMapping>();
+  const outputMappings = new Map<ts.Symbol, ScalarBaseTypeMapping>();
+  const conflicts = new Map<ts.Symbol, ScalarMappingConflict>();
+
+  // Track all scalars for each base type symbol to detect conflicts
+  const inputCandidates = new Map<
+    ts.Symbol,
+    Array<{
+      scalarName: string;
+      only: "input" | "output" | null;
+      typeName: string;
+    }>
+  >();
+  const outputCandidates = new Map<
+    ts.Symbol,
+    Array<{
+      scalarName: string;
+      only: "input" | "output" | null;
+      typeName: string;
+    }>
+  >();
+
+  for (const scalarInfo of detectedScalars) {
+    const baseTypeSymbol = extractBaseTypeSymbol(scalarInfo, checker, program);
+    if (!baseTypeSymbol) {
+      continue;
+    }
+
+    const candidate = {
+      scalarName: scalarInfo.scalarName,
+      only: scalarInfo.only,
+      typeName: scalarInfo.typeName,
+    };
+
+    // Register to input context if no constraint or input-only
+    if (scalarInfo.only === null || scalarInfo.only === "input") {
+      const existing = inputCandidates.get(baseTypeSymbol) ?? [];
+      existing.push(candidate);
+      inputCandidates.set(baseTypeSymbol, existing);
+    }
+
+    // Register to output context if no constraint or output-only
+    if (scalarInfo.only === null || scalarInfo.only === "output") {
+      const existing = outputCandidates.get(baseTypeSymbol) ?? [];
+      existing.push(candidate);
+      outputCandidates.set(baseTypeSymbol, existing);
+    }
+  }
+
+  // Process input mappings and detect conflicts
+  for (const [symbol, candidates] of inputCandidates) {
+    if (candidates.length === 1) {
+      const candidate = candidates[0]!;
+      inputMappings.set(symbol, {
+        scalarName: candidate.scalarName,
+        only: candidate.only,
+        sourceTypeName: candidate.typeName,
+      });
+    } else if (candidates.length > 1) {
+      conflicts.set(symbol, {
+        code: "AMBIGUOUS_SCALAR_BASE_TYPE",
+        baseTypeSymbol: symbol,
+        conflictingScalars: candidates.map((c) => ({
+          scalarName: c.scalarName,
+          only: c.only,
+        })),
+      });
+    }
+  }
+
+  // Process output mappings and detect conflicts
+  for (const [symbol, candidates] of outputCandidates) {
+    if (candidates.length === 1) {
+      const candidate = candidates[0]!;
+      outputMappings.set(symbol, {
+        scalarName: candidate.scalarName,
+        only: candidate.only,
+        sourceTypeName: candidate.typeName,
+      });
+    } else if (candidates.length > 1) {
+      // Only add conflict if not already added from input context
+      if (!conflicts.has(symbol)) {
+        conflicts.set(symbol, {
+          code: "AMBIGUOUS_SCALAR_BASE_TYPE",
+          baseTypeSymbol: symbol,
+          conflictingScalars: candidates.map((c) => ({
+            scalarName: c.scalarName,
+            only: c.only,
+          })),
+        });
+      }
+    }
+  }
+
+  return {
+    inputMappings,
+    outputMappings,
+    conflicts,
+  };
+}
+
+/**
+ * Parameters for looking up a scalar mapping.
+ */
+export interface LookupScalarMappingParams {
+  readonly baseTypeSymbol: ts.Symbol;
+  readonly context: ScalarMappingContext;
+  readonly table: ScalarBaseTypeMappingTable;
+}
+
+/**
+ * Looks up a scalar mapping for a given base type symbol and context.
+ *
+ * @returns mapping if found, conflict if detected, or both null if no mapping exists
+ */
+export function lookupScalarMapping(
+  params: LookupScalarMappingParams,
+): ScalarMappingLookupResult {
+  const { baseTypeSymbol, context, table } = params;
+
+  // Check for conflicts first
+  const conflict = table.conflicts.get(baseTypeSymbol);
+  if (conflict) {
+    return { mapping: null, conflict };
+  }
+
+  // Look up mapping based on context
+  const mappings =
+    context === "input" ? table.inputMappings : table.outputMappings;
+  const mapping = mappings.get(baseTypeSymbol);
+
+  return { mapping: mapping ?? null, conflict: null };
+}

package/src/type-extractor/types/diagnostics.ts

@@ -0,0 +1,109 @@
+export interface SourceLocation {
+  readonly file: string;
+  readonly line: number;
+  readonly column: number;
+}
+
+export type DiagnosticCode =
+  | "DIRECTORY_NOT_FOUND"
+  | "PARSE_ERROR"
+  | "UNSUPPORTED_SYNTAX"
+  | "RESERVED_TYPE_NAME"
+  | "UNRESOLVED_REFERENCE"
+  | "NAMING_CONVENTION_MISMATCH"
+  | "INVALID_RESOLVER_SIGNATURE"
+  | "UNSUPPORTED_RETURN_TYPE"
+  | "UNSUPPORTED_ARG_TYPE"
+  | "UNKNOWN_TARGET_TYPE"
+  | "PARENT_TYPE_MISMATCH"
+  | "MISSING_PARENT_TYPE"
+  | "UNSUPPORTED_ENUM_TYPE"
+  | "INVALID_ENUM_MEMBER"
+  | "INVALID_INPUT_TYPE"
+  | "UNKNOWN_ARGUMENT_TYPE"
+  | "OUTPUT_TYPE_IN_INPUT"
+  | "CIRCULAR_INPUT_REFERENCE"
+  | "UNKNOWN_BRANDED_SCALAR"
+  | "INVALID_SCALAR_IMPORT"
+  | "CONFLICTING_SCALAR_TYPE"
+  | "INVALID_DEFINE_CALL"
+  | "CONFIG_SYNTAX_ERROR"
+  | "CONFIG_MISSING_PROPERTY"
+  | "CONFIG_INVALID_TYPE"
+  | "CONFIG_INVALID_PATH"
+  | "CONFIG_BUILTIN_OVERRIDE"
+  | "CONFIG_DUPLICATE_MAPPING"
+  | "CONFIG_DUPLICATE_TYPE"
+  | "CONFIG_INVALID_OUTPUT_TYPE"
+  | "CONFIG_INVALID_OUTPUT_PATH"
+  | "CONFIG_INVALID_SOURCE_DIR"
+  | "CONFIG_INVALID_IGNORE_GLOBS"
+  | "CONFIG_INVALID_HOOK_TYPE"
+  | "CONFIG_INVALID_HOOK_COMMAND"
+  | "CONFIG_INVALID_ONLY_VALUE"
+  | "CUSTOM_SCALAR_TYPE_NOT_FOUND"
+  | "TSCONFIG_NOT_FOUND"
+  | "TSCONFIG_PARSE_ERROR"
+  | "TSCONFIG_INVALID"
+  | "ONEOF_FIELD_NAME_CONFLICT"
+  | "ONEOF_MULTIPLE_PROPERTIES"
+  | "ONEOF_EMPTY_OBJECT"
+  | "ONEOF_INVALID_FIELD_TYPE"
+  | "ONEOF_DUPLICATE_PROPERTY"
+  | "ONEOF_MIXED_MEMBERS"
+  | "ONEOF_NAMED_TYPE_UNION"
+  | "MULTIPLE_INPUT_TYPES"
+  | "MISSING_INPUT_TYPE"
+  | "MISSING_OUTPUT_TYPE"
+  | "EMPTY_DIRECTIVE_NAME"
+  | "UNRESOLVABLE_ARGUMENT"
+  | "UNRESOLVABLE_ARG_TYPE"
+  | "INVALID_LOCATION"
+  | "INVALID_DIRECTIVE_LOCATION"
+  | "UNSUPPORTED_DIRECTIVE_LOCATION"
+  | "UNDEFINED_DIRECTIVE"
+  | "INTERFACE_NOT_FOUND"
+  | "INTERFACE_NOT_INTERFACE"
+  | "INTERFACE_MISSING_FIELD"
+  | "INTERFACE_FIELD_TYPE_MISMATCH"
+  | "INTERFACE_CIRCULAR_REFERENCE"
+  | "UNRESOLVABLE_DEFAULT_VALUE"
+  | "AUTO_TYPE_NAME_COLLISION_USER"
+  | "AUTO_TYPE_NAME_COLLISION_AUTO"
+  | "MODULE_RESOLUTION_ERROR"
+  | "SKIPPED_FIELD"
+  | "SKIPPED_ENUM_VALUE"
+  | "INDEX_SIGNATURE_ONLY"
+  | "UNKNOWN_ABSTRACT_TYPE"
+  | "INVALID_ABSTRACT_TYPE_KIND"
+  | "INVALID_OBJECT_TYPE_KIND"
+  | "DUPLICATE_RESOLVE_TYPE"
+  | "DUPLICATE_IS_TYPE_OF"
+  | "MISSING_ABSTRACT_TYPE_RESOLVER"
+  | "DUPLICATE_ENUM_VALUE"
+  | "DUPLICATE_ENUM_VALUE_AFTER_CONVERSION"
+  | "INVALID_ENUM_MEMBER_NAME"
+  | "AMBIGUOUS_SCALAR_BASE_TYPE"
+  | "INLINE_UNION_PRIMITIVE_MEMBER"
+  | "INLINE_UNION_ENUM_MEMBER"
+  | "INLINE_UNION_UNRESOLVABLE_MEMBER"
+  | "MISSING_TYPENAME_PROPERTY"
+  | "INVALID_TYPENAME_TYPE"
+  | "OPTIONAL_TYPENAME_PROPERTY"
+  | "NULLABLE_TYPENAME_PROPERTY"
+  | "TYPENAME_FIELD_STRUCTURE_MISMATCH"
+  | "DUPLICATE_TYPENAME_VALUE"
+  | "IGNORE_FIELD_NOT_FOUND"
+  | "IGNORE_ALL_FIELDS";
+
+export interface Diagnostic {
+  readonly code: DiagnosticCode;
+  readonly message: string;
+  readonly severity: "error" | "warning";
+  readonly location: SourceLocation | null;
+}
+
+export interface Diagnostics {
+  readonly errors: ReadonlyArray<Diagnostic>;
+  readonly warnings: ReadonlyArray<Diagnostic>;
+}

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

@@ -0,0 +1,55 @@
+import type {
+  DirectiveArgumentValue,
+  DirectiveInfo,
+} from "../../shared/directive-detector.js";
+import type { DeprecationInfo } from "../../shared/tsdoc-parser.js";
+
+export type GraphQLTypeKind =
+  | "Object"
+  | "Interface"
+  | "Union"
+  | "Enum"
+  | "InputObject"
+  | "OneOfInputObject";
+
+export interface GraphQLFieldType {
+  readonly typeName: string;
+  readonly nullable: boolean;
+  readonly list: boolean;
+  readonly listItemNullable: boolean | null;
+}
+
+export interface FieldInfo {
+  readonly name: string;
+  readonly type: GraphQLFieldType;
+  readonly description: string | null;
+  readonly deprecated: DeprecationInfo | null;
+  readonly directives: ReadonlyArray<DirectiveInfo> | null;
+  readonly defaultValue: DirectiveArgumentValue | null;
+}
+
+export interface EnumValueInfo {
+  readonly name: string;
+  readonly originalValue: string;
+  /** Numeric value for numeric enums, null for string enums */
+  readonly numericValue: number | null;
+  readonly description: string | null;
+  readonly deprecated: DeprecationInfo | null;
+}
+
+export interface GraphQLTypeInfo {
+  readonly name: string;
+  readonly kind: GraphQLTypeKind;
+  readonly fields: ReadonlyArray<FieldInfo> | null;
+  readonly unionMembers: ReadonlyArray<string> | null;
+  readonly enumValues: ReadonlyArray<EnumValueInfo> | null;
+  /** True if this enum uses numeric values */
+  readonly isNumericEnum: boolean;
+  /** True if this string enum needs value mapping (at least one value converted) */
+  readonly needsStringEnumMapping: boolean;
+  readonly implementedInterfaces: ReadonlyArray<string> | null;
+  readonly sourceFile: string;
+  readonly description: string | null;
+  readonly deprecated: DeprecationInfo | null;
+  readonly directives: ReadonlyArray<DirectiveInfo> | null;
+}

package/src/type-extractor/types/index.ts

@@ -0,0 +1,37 @@
+export type { DeprecationInfo } from "../../shared/tsdoc-parser.js";
+export type {
+  Diagnostic,
+  DiagnosticCode,
+  Diagnostics,
+  SourceLocation,
+} from "./diagnostics.js";
+export type {
+  EnumValueInfo,
+  FieldInfo,
+  GraphQLFieldType,
+  GraphQLTypeInfo,
+  GraphQLTypeKind,
+} from "./graphql.js";
+export {
+  createArrayType,
+  createInlineObjectType,
+  createLiteralType,
+  createPrimitiveType,
+  createReferenceType,
+  createScalarType,
+  createUnionType,
+} from "./ts-type-reference-factory.js";
+export type {
+  EnumMemberInfo,
+  ExtractedTypeInfo,
+  FieldDefinition,
+  InlineEnumMemberInfo,
+  InlineObjectMember,
+  InlineObjectProperty,
+  InlineObjectPropertyDef,
+  ScalarTypeInfo,
+  TSTypeReference,
+  TSTypeReferenceKind,
+  TypeKind,
+  TypeMetadata,
+} from "./typescript.js";