@gqlkit-ts/cli 0.1.0 → 0.3.0

package/src/shared/interface-validator.ts

@@ -0,0 +1,211 @@
+import type { GraphQLTypeInfo } from "../type-extractor/types/graphql.js";
+import type { Diagnostic } from "../type-extractor/types/index.js";
+
+export interface InterfaceValidationResult {
+  readonly isValid: boolean;
+  readonly diagnostics: ReadonlyArray<Diagnostic>;
+}
+
+export function validateInterfaceImplementations(
+  types: ReadonlyArray<GraphQLTypeInfo>,
+): InterfaceValidationResult {
+  const diagnostics: Diagnostic[] = [];
+  const typeMap = new Map<string, GraphQLTypeInfo>();
+
+  for (const type of types) {
+    typeMap.set(type.name, type);
+  }
+
+  for (const type of types) {
+    if (
+      !type.implementedInterfaces ||
+      type.implementedInterfaces.length === 0
+    ) {
+      continue;
+    }
+
+    for (const interfaceName of type.implementedInterfaces) {
+      const interfaceType = typeMap.get(interfaceName);
+
+      if (!interfaceType) {
+        diagnostics.push({
+          code: "INTERFACE_NOT_FOUND",
+          message: `Type '${type.name}' implements unknown interface '${interfaceName}'`,
+          severity: "error",
+          location: {
+            file: type.sourceFile,
+            line: 1,
+            column: 1,
+          },
+        });
+        continue;
+      }
+
+      if (interfaceType.kind !== "Interface") {
+        diagnostics.push({
+          code: "INTERFACE_NOT_INTERFACE",
+          message: `Type '${type.name}' attempts to implement '${interfaceName}' which is not an interface`,
+          severity: "error",
+          location: {
+            file: type.sourceFile,
+            line: 1,
+            column: 1,
+          },
+        });
+        continue;
+      }
+
+      if (!interfaceType.fields) {
+        continue;
+      }
+
+      const typeFields = new Map(type.fields?.map((f) => [f.name, f]) ?? []);
+
+      for (const interfaceField of interfaceType.fields) {
+        const typeField = typeFields.get(interfaceField.name);
+
+        if (!typeField) {
+          diagnostics.push({
+            code: "INTERFACE_MISSING_FIELD",
+            message: `Type '${type.name}' implements interface '${interfaceName}' but is missing field '${interfaceField.name}'`,
+            severity: "error",
+            location: {
+              file: type.sourceFile,
+              line: 1,
+              column: 1,
+            },
+          });
+          continue;
+        }
+
+        if (!isTypeCompatible(typeField.type, interfaceField.type)) {
+          diagnostics.push({
+            code: "INTERFACE_FIELD_TYPE_MISMATCH",
+            message: `Type '${type.name}' field '${interfaceField.name}' has incompatible type with interface '${interfaceName}'`,
+            severity: "error",
+            location: {
+              file: type.sourceFile,
+              line: 1,
+              column: 1,
+            },
+          });
+        }
+      }
+    }
+  }
+
+  return {
+    isValid: diagnostics.length === 0,
+    diagnostics,
+  };
+}
+
+interface FieldType {
+  readonly typeName: string;
+  readonly nullable: boolean;
+  readonly list: boolean;
+  readonly listItemNullable?: boolean | null;
+}
+
+function isTypeCompatible(
+  implementingType: FieldType,
+  interfaceType: FieldType,
+): boolean {
+  if (implementingType.typeName !== interfaceType.typeName) {
+    return false;
+  }
+
+  if (implementingType.list !== interfaceType.list) {
+    return false;
+  }
+
+  if (implementingType.nullable && !interfaceType.nullable) {
+    return false;
+  }
+
+  if (implementingType.list) {
+    if (implementingType.listItemNullable && !interfaceType.listItemNullable) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export function detectCircularInterfaceReferences(
+  types: ReadonlyArray<GraphQLTypeInfo>,
+): InterfaceValidationResult {
+  const diagnostics: Diagnostic[] = [];
+  const typeMap = new Map<string, GraphQLTypeInfo>();
+  const reportedCycles = new Set<string>();
+
+  for (const type of types) {
+    if (type.kind === "Interface") {
+      typeMap.set(type.name, type);
+    }
+  }
+
+  for (const type of types) {
+    if (type.kind !== "Interface" || !type.implementedInterfaces) {
+      continue;
+    }
+
+    const cyclePath = findCircularReference(type.name, typeMap, new Set(), []);
+    if (cyclePath) {
+      const cycleStart = cyclePath.indexOf(cyclePath[cyclePath.length - 1]!);
+      const cycleMembers = cyclePath.slice(cycleStart, -1);
+      const cycleKey = [...cycleMembers].sort().join(",");
+      if (!reportedCycles.has(cycleKey)) {
+        reportedCycles.add(cycleKey);
+        diagnostics.push({
+          code: "INTERFACE_CIRCULAR_REFERENCE",
+          message: `Circular interface inheritance detected: ${cyclePath.join(" -> ")}`,
+          severity: "error",
+          location: {
+            file: type.sourceFile,
+            line: 1,
+            column: 1,
+          },
+        });
+      }
+    }
+  }
+
+  return {
+    isValid: diagnostics.length === 0,
+    diagnostics,
+  };
+}
+
+function findCircularReference(
+  typeName: string,
+  typeMap: Map<string, GraphQLTypeInfo>,
+  visited: Set<string>,
+  path: string[],
+): string[] | null {
+  if (visited.has(typeName)) {
+    return [...path, typeName];
+  }
+
+  visited.add(typeName);
+  path.push(typeName);
+
+  const type = typeMap.get(typeName);
+  if (!type || !type.implementedInterfaces) {
+    return null;
+  }
+
+  for (const interfaceName of type.implementedInterfaces) {
+    const result = findCircularReference(
+      interfaceName,
+      typeMap,
+      new Set(visited),
+      [...path],
+    );
+    if (result) {
+      return result;
+    }
+  }
+
+  return null;
+}

package/src/shared/metadata-detector.ts

@@ -0,0 +1,443 @@
+/**
+ * Scalar metadata detector.
+ *
+ * This module provides functions to detect scalar metadata embedded
+ * in TypeScript intersection types using the $gqlkitScalar property.
+ */
+
+import ts from "typescript";
+import { METADATA_PROPERTIES } from "./constants.js";
+import { isNullOrUndefined } from "./typescript-utils.js";
+
+const SCALAR_METADATA_PROPERTY = METADATA_PROPERTIES.SCALAR;
+
+/**
+ * Error information for mixed scalar union detection.
+ */
+export interface ScalarMetadataError {
+  readonly code: "MIXED_SCALAR_UNION";
+  readonly message: string;
+  readonly scalarNames: ReadonlyArray<string>;
+}
+
+/**
+ * Result of scalar metadata detection.
+ */
+export interface ScalarMetadataResult {
+  /** The GraphQL scalar name if detected, null otherwise */
+  readonly scalarName: string | null;
+  /** Usage constraint: "input", "output", or null for both */
+  readonly only: "input" | "output" | null;
+  /** Whether the type is nullable (union with null) */
+  readonly nullable: boolean;
+  /** Whether the type is a list (array type) */
+  readonly isList: boolean;
+  /** Whether list items are nullable (for list types) */
+  readonly listItemNullable: boolean;
+  /** Whether this is a TypeScript primitive type */
+  readonly isPrimitive: boolean;
+  /** Whether this is an object type (not a scalar) */
+  readonly isObjectType: boolean;
+  /** Error if mixed scalar union is detected */
+  readonly error: ScalarMetadataError | undefined;
+}
+
+interface InternalMetadata {
+  scalarName: string | null;
+  only: "input" | "output" | null;
+  isPrimitive: boolean;
+  isObjectType: boolean;
+}
+
+function createDefaultResult(): ScalarMetadataResult {
+  return {
+    scalarName: null,
+    only: null,
+    nullable: false,
+    isList: false,
+    listItemNullable: false,
+    isPrimitive: false,
+    isObjectType: false,
+    error: undefined,
+  };
+}
+
+/**
+ * Extracts the actual type from an optional property type (T | undefined).
+ * Used by both scalar and resolver metadata detection.
+ *
+ * For simple cases like `T | undefined`, returns T.
+ * For union cases like `T | null | undefined`, returns the original union type
+ * so the caller can analyze it (e.g., check for null members).
+ * For boolean types (true | false | undefined), reconstructs the boolean type.
+ *
+ * @param metadataType - The type of the metadata property (may be union with undefined)
+ * @returns The actual type excluding undefined, or null if extraction fails
+ */
+export function getActualMetadataType(metadataType: ts.Type): ts.Type | null {
+  if (metadataType.isUnion()) {
+    const nonUndefinedTypes = metadataType.types.filter(
+      (t) => !(t.flags & ts.TypeFlags.Undefined),
+    );
+    if (nonUndefinedTypes.length === 1) {
+      return nonUndefinedTypes[0]!;
+    }
+    // Special case: boolean (true | false) optionally with undefined
+    // TypeScript represents boolean | undefined as true | false | undefined
+    if (
+      nonUndefinedTypes.length === 2 &&
+      nonUndefinedTypes.every((t) => t.flags & ts.TypeFlags.BooleanLiteral)
+    ) {
+      // This is effectively "boolean" - return the first member to preserve
+      // the boolean literal nature, or we could return the union
+      return metadataType;
+    }
+    // If there are multiple non-undefined types (e.g., string | null),
+    // return the original metadataType. The caller should analyze this
+    // union type and handle null members appropriately.
+    if (nonUndefinedTypes.length > 1) {
+      // Return the original type - caller will need to filter out undefined
+      // when checking for nullability
+      return metadataType;
+    }
+    return null;
+  }
+  return metadataType;
+}
+
+function extractMetadataFromType(
+  type: ts.Type,
+  checker: ts.TypeChecker,
+): InternalMetadata | null {
+  const metadataProp = type.getProperty(SCALAR_METADATA_PROPERTY);
+  if (!metadataProp) {
+    return null;
+  }
+
+  const rawMetadataType = checker.getTypeOfSymbol(metadataProp);
+  const metadataType = getActualMetadataType(rawMetadataType);
+  if (!metadataType) {
+    return null;
+  }
+
+  const nameProp = metadataType.getProperty("name");
+  if (!nameProp) {
+    return null;
+  }
+
+  const nameType = checker.getTypeOfSymbol(nameProp);
+  if (!(nameType.flags & ts.TypeFlags.StringLiteral)) {
+    return null;
+  }
+
+  const scalarName = (nameType as ts.StringLiteralType).value;
+
+  const onlyProp = metadataType.getProperty("only");
+  let only: "input" | "output" | null = null;
+  if (onlyProp) {
+    const onlyType = checker.getTypeOfSymbol(onlyProp);
+    if (onlyType.flags & ts.TypeFlags.StringLiteral) {
+      const onlyValue = (onlyType as ts.StringLiteralType).value;
+      if (onlyValue === "input" || onlyValue === "output") {
+        only = onlyValue;
+      }
+    }
+  }
+
+  return {
+    scalarName,
+    only,
+    isPrimitive: false,
+    isObjectType: false,
+  };
+}
+
+function detectScalarMetadataFromIntersection(
+  type: ts.Type,
+  checker: ts.TypeChecker,
+): InternalMetadata | null {
+  if (!type.isIntersection()) {
+    return null;
+  }
+
+  for (const member of type.types) {
+    const metadata = extractMetadataFromType(member, checker);
+    if (metadata) {
+      return metadata;
+    }
+  }
+
+  return null;
+}
+
+function detectPrimitiveScalar(type: ts.Type): InternalMetadata | null {
+  if (type.flags & ts.TypeFlags.String) {
+    return {
+      scalarName: "String",
+      only: null,
+      isPrimitive: true,
+      isObjectType: false,
+    };
+  }
+  if (type.flags & ts.TypeFlags.Number) {
+    return {
+      scalarName: "Float",
+      only: null,
+      isPrimitive: true,
+      isObjectType: false,
+    };
+  }
+  if (
+    type.flags & ts.TypeFlags.Boolean ||
+    type.flags & ts.TypeFlags.BooleanLiteral
+  ) {
+    return {
+      scalarName: "Boolean",
+      only: null,
+      isPrimitive: true,
+      isObjectType: false,
+    };
+  }
+
+  return null;
+}
+
+function isBooleanLiteralUnion(types: readonly ts.Type[]): boolean {
+  const nonNullTypes = types.filter((t) => !isNullOrUndefined(t));
+  return (
+    nonNullTypes.length === 2 &&
+    nonNullTypes.every((t) => t.flags & ts.TypeFlags.BooleanLiteral)
+  );
+}
+
+function detectScalarMetadataCore(
+  type: ts.Type,
+  checker: ts.TypeChecker,
+): InternalMetadata | null {
+  const primitiveResult = detectPrimitiveScalar(type);
+  if (primitiveResult) {
+    return primitiveResult;
+  }
+
+  const intersectionResult = detectScalarMetadataFromIntersection(
+    type,
+    checker,
+  );
+  if (intersectionResult) {
+    return intersectionResult;
+  }
+
+  const directMetadata = extractMetadataFromType(type, checker);
+  if (directMetadata) {
+    return directMetadata;
+  }
+
+  if (type.aliasSymbol) {
+    const aliasedType = checker.getDeclaredTypeOfSymbol(type.aliasSymbol);
+    if (aliasedType !== type) {
+      const aliasResult = detectScalarMetadataCore(aliasedType, checker);
+      if (aliasResult) {
+        return aliasResult;
+      }
+    }
+  }
+
+  const symbol = type.getSymbol();
+  if (symbol) {
+    const declarations = symbol.getDeclarations();
+    if (declarations && declarations.length > 0) {
+      for (const decl of declarations) {
+        if (ts.isTypeAliasDeclaration(decl)) {
+          const declSymbol = checker.getSymbolAtLocation(decl.name);
+          if (declSymbol) {
+            const declType = checker.getDeclaredTypeOfSymbol(declSymbol);
+            if (declType !== type && declType.isIntersection()) {
+              const result = detectScalarMetadataFromIntersection(
+                declType,
+                checker,
+              );
+              if (result) {
+                return result;
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+function isObjectLikeType(type: ts.Type): boolean {
+  if (type.flags & ts.TypeFlags.Object) {
+    const objectType = type as ts.ObjectType;
+    if (
+      objectType.objectFlags & ts.ObjectFlags.Anonymous ||
+      objectType.objectFlags & ts.ObjectFlags.Interface ||
+      objectType.objectFlags & ts.ObjectFlags.Reference
+    ) {
+      const properties = type.getProperties();
+      const hasOnlyMetadataProperty =
+        properties.length === 1 &&
+        properties[0]?.getName() === SCALAR_METADATA_PROPERTY;
+
+      if (!hasOnlyMetadataProperty && properties.length > 0) {
+        const metadataProp = type.getProperty(SCALAR_METADATA_PROPERTY);
+        if (!metadataProp) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Detects scalar metadata from a TypeScript type.
+ *
+ * This function analyzes TypeScript types to detect scalar metadata:
+ * - TypeScript primitives (string, boolean, number) map to GraphQL scalars
+ * - Intersection types with " $gqlkitScalar" property indicate custom scalars
+ * - Type aliases are followed to find the underlying scalar metadata
+ * - Unions with null indicate nullable types
+ * - Array types indicate list types
+ *
+ * @param type - The TypeScript type to analyze
+ * @param checker - The TypeScript type checker
+ * @returns Detection result with scalar information
+ */
+export function detectScalarMetadata(
+  type: ts.Type,
+  checker: ts.TypeChecker,
+): ScalarMetadataResult {
+  const result = createDefaultResult();
+
+  if (checker.isArrayType(type)) {
+    const typeRef = type as ts.TypeReference;
+    const elementType = typeRef.typeArguments?.[0];
+
+    if (!elementType) {
+      return {
+        ...result,
+        isList: true,
+        scalarName: "String",
+      };
+    }
+
+    const elementResult = detectScalarMetadata(elementType, checker);
+    return {
+      ...result,
+      scalarName: elementResult.scalarName,
+      only: elementResult.only,
+      isList: true,
+      listItemNullable: elementResult.nullable,
+      isPrimitive: elementResult.isPrimitive,
+      error: elementResult.error,
+    };
+  }
+
+  if (type.isUnion()) {
+    const nonNullTypes = type.types.filter((t) => !isNullOrUndefined(t));
+    const hasNull = type.types.some((t) => isNullOrUndefined(t));
+
+    if (isBooleanLiteralUnion(type.types)) {
+      return {
+        ...result,
+        scalarName: "Boolean",
+        isPrimitive: true,
+        nullable: hasNull,
+      };
+    }
+
+    if (nonNullTypes.length === 0) {
+      return result;
+    }
+
+    if (nonNullTypes.length === 1) {
+      const innerType = nonNullTypes[0]!;
+
+      if (checker.isArrayType(innerType)) {
+        const innerResult = detectScalarMetadata(innerType, checker);
+        return {
+          ...innerResult,
+          nullable: hasNull,
+        };
+      }
+
+      const innerResult = detectScalarMetadata(innerType, checker);
+      return {
+        ...innerResult,
+        nullable: hasNull || innerResult.nullable,
+      };
+    }
+
+    const scalarNames = new Set<string>();
+    const detectedResults: InternalMetadata[] = [];
+
+    for (const unionMember of nonNullTypes) {
+      const memberResult = detectScalarMetadataCore(unionMember, checker);
+      if (memberResult?.scalarName) {
+        scalarNames.add(memberResult.scalarName);
+        detectedResults.push(memberResult);
+      }
+    }
+
+    if (scalarNames.size > 1) {
+      const scalarNameArray = Array.from(scalarNames).sort();
+      return {
+        ...result,
+        nullable: hasNull,
+        error: {
+          code: "MIXED_SCALAR_UNION",
+          message: `Cannot use union of different scalar types: ${scalarNameArray.join(", ")}`,
+          scalarNames: scalarNameArray,
+        },
+      };
+    }
+
+    if (scalarNames.size === 1 && detectedResults.length > 0) {
+      const firstResult = detectedResults[0]!;
+      return {
+        ...result,
+        scalarName: firstResult.scalarName,
+        only: firstResult.only,
+        nullable: hasNull,
+        isPrimitive: firstResult.isPrimitive,
+      };
+    }
+
+    if (nonNullTypes.every((t) => isObjectLikeType(t))) {
+      return {
+        ...result,
+        isObjectType: true,
+        nullable: hasNull,
+      };
+    }
+
+    return {
+      ...result,
+      nullable: hasNull,
+    };
+  }
+
+  const coreResult = detectScalarMetadataCore(type, checker);
+  if (coreResult) {
+    return {
+      ...result,
+      scalarName: coreResult.scalarName,
+      only: coreResult.only,
+      isPrimitive: coreResult.isPrimitive,
+      isObjectType: coreResult.isObjectType,
+    };
+  }
+
+  if (isObjectLikeType(type)) {
+    return {
+      ...result,
+      isObjectType: true,
+    };
+  }
+
+  return result;
+}

package/src/shared/path-utils.ts

@@ -0,0 +1,3 @@
+export function toPosixPath(filePath: string): string {
+  return filePath.replace(/\\/g, "/");
+}

package/src/shared/program-factory.ts

@@ -0,0 +1,51 @@
+import ts from "typescript";
+import type { Diagnostic } from "../type-extractor/types/index.js";
+import { loadTsconfig } from "./tsconfig-loader.js";
+
+const DEFAULT_COMPILER_OPTIONS: ts.CompilerOptions = {
+  target: ts.ScriptTarget.ES2022,
+  module: ts.ModuleKind.NodeNext,
+  moduleResolution: ts.ModuleResolutionKind.Node16,
+  strict: true,
+  esModuleInterop: true,
+  skipLibCheck: true,
+  noEmit: true,
+};
+
+export interface CreateSharedProgramOptions {
+  readonly cwd: string;
+  readonly tsconfigPath: string | null;
+  readonly typeFiles: ReadonlyArray<string>;
+  readonly resolverFiles: ReadonlyArray<string>;
+}
+
+export interface CreateSharedProgramResult {
+  readonly program: ts.Program | null;
+  readonly diagnostics: ReadonlyArray<Diagnostic>;
+}
+
+export function createSharedProgram(
+  options: CreateSharedProgramOptions,
+): CreateSharedProgramResult {
+  const { cwd, tsconfigPath, typeFiles, resolverFiles } = options;
+
+  const tsconfigResult = loadTsconfig({ cwd, tsconfigPath });
+
+  if (tsconfigResult.diagnostics.length > 0) {
+    return {
+      program: null,
+      diagnostics: tsconfigResult.diagnostics,
+    };
+  }
+
+  const compilerOptions: ts.CompilerOptions =
+    tsconfigResult.compilerOptions ?? DEFAULT_COMPILER_OPTIONS;
+
+  const allFiles = [...typeFiles, ...resolverFiles];
+  const program = ts.createProgram(allFiles, compilerOptions);
+
+  return {
+    program,
+    diagnostics: [],
+  };
+}