@gqlkit-ts/cli 0.1.0 → 0.2.0

package/src/schema-generator/integrator/result-integrator.ts

@@ -0,0 +1,690 @@
+import type { AutoGeneratedType } from "../../auto-type-generator/index.js";
+import type {
+  AbstractResolverInfo,
+  ExtractResolversResult,
+  GraphQLFieldDefinition,
+  GraphQLInputValue,
+  TypeExtension as ResolverTypeExtension,
+} from "../../resolver-extractor/index.js";
+import { validateAbstractResolvers } from "../../resolver-extractor/validator/abstract-resolver-validator.js";
+import type {
+  DirectiveDefinitionInfo,
+  DirectiveLocation,
+} from "../../shared/directive-definition-extractor.js";
+import type {
+  DirectiveArgumentValue,
+  DirectiveInfo,
+} from "../../shared/directive-detector.js";
+import {
+  detectCircularInterfaceReferences,
+  validateInterfaceImplementations,
+} from "../../shared/interface-validator.js";
+import type { DeprecationInfo } from "../../shared/tsdoc-parser.js";
+import type { CollectedScalarType } from "../../type-extractor/collector/scalar-collector.js";
+import { mergeDescriptions } from "../../type-extractor/collector/scalar-collector.js";
+import type { ExtractTypesResult } from "../../type-extractor/index.js";
+import type {
+  Diagnostic,
+  EnumValueInfo,
+  GraphQLFieldType,
+} from "../../type-extractor/types/index.js";
+
+export interface BaseField {
+  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 BaseType {
+  readonly name: string;
+  readonly kind: "Object" | "Interface" | "Union" | "Enum";
+  readonly fields: ReadonlyArray<BaseField> | 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 description: string | null;
+  readonly deprecated: DeprecationInfo | null;
+  readonly sourceFile: string | null;
+  readonly directives: ReadonlyArray<DirectiveInfo> | null;
+}
+
+export interface InputType {
+  readonly name: string;
+  readonly fields: ReadonlyArray<BaseField>;
+  readonly sourceFile: string;
+  readonly description: string | null;
+  readonly isOneOf: boolean;
+}
+
+export interface ExtensionField {
+  readonly name: string;
+  readonly type: GraphQLFieldType;
+  readonly args: ReadonlyArray<GraphQLInputValue> | null;
+  readonly resolverSourceFile: string;
+  readonly resolverExportName: string | null;
+  readonly description: string | null;
+  readonly deprecated: DeprecationInfo | null;
+  readonly directives: ReadonlyArray<DirectiveInfo> | null;
+}
+
+export interface TypeExtension {
+  readonly targetTypeName: string;
+  readonly fields: ReadonlyArray<ExtensionField>;
+}
+
+/**
+ * Custom scalar information for schema generation.
+ */
+export interface CustomScalarInfo {
+  readonly scalarName: string;
+  readonly description: string | null;
+}
+
+/**
+ * Numeric enum member value mapping.
+ */
+export interface NumericEnumMember {
+  readonly name: string;
+  readonly numericValue: number;
+}
+
+/**
+ * Numeric enum information for resolver generation.
+ */
+export interface NumericEnumInfo {
+  readonly enumName: string;
+  readonly members: ReadonlyArray<NumericEnumMember>;
+}
+
+/**
+ * String enum member value mapping.
+ */
+export interface StringEnumMember {
+  /** GraphQL enum value name (SCREAMING_SNAKE_CASE) */
+  readonly graphqlValue: string;
+  /** Original TypeScript enum value */
+  readonly typescriptValue: string;
+}
+
+/**
+ * String enum information for resolver generation.
+ */
+export interface StringEnumMappingInfo {
+  readonly enumName: string;
+  readonly members: ReadonlyArray<StringEnumMember>;
+}
+
+export interface IntegratedResult {
+  readonly baseTypes: ReadonlyArray<BaseType>;
+  readonly inputTypes: ReadonlyArray<InputType>;
+  readonly typeExtensions: ReadonlyArray<TypeExtension>;
+  /** @deprecated Use customScalars instead */
+  readonly customScalarNames: ReadonlyArray<string> | null;
+  /** Custom scalars with description information */
+  readonly customScalars: ReadonlyArray<CustomScalarInfo> | null;
+  /** Directive definitions extracted from type aliases */
+  readonly directiveDefinitions: ReadonlyArray<DirectiveDefinitionInfo> | null;
+  /** Abstract type resolvers (resolveType and isTypeOf) */
+  readonly abstractTypeResolvers: ReadonlyArray<AbstractResolverInfo>;
+  /** Numeric enum information for resolver generation */
+  readonly numericEnums: ReadonlyArray<NumericEnumInfo>;
+  /** String enum mappings for resolver generation */
+  readonly stringEnumMappings: ReadonlyArray<StringEnumMappingInfo>;
+  readonly hasQuery: boolean;
+  readonly hasMutation: boolean;
+  readonly hasErrors: boolean;
+  readonly diagnostics: ReadonlyArray<Diagnostic>;
+}
+
+function convertToExtensionField(
+  field: GraphQLFieldDefinition,
+): ExtensionField {
+  return {
+    name: field.name,
+    type: field.type,
+    args: field.args,
+    resolverSourceFile: field.sourceLocation.file,
+    resolverExportName: field.resolverExportName,
+    description: field.description,
+    deprecated: field.deprecated,
+    directives: field.directives,
+  };
+}
+
+function convertResolverTypeExtension(
+  ext: ResolverTypeExtension,
+): TypeExtension {
+  return {
+    targetTypeName: ext.targetTypeName,
+    fields: ext.fields.map(convertToExtensionField),
+  };
+}
+
+const UNSUPPORTED_LOCATIONS: ReadonlySet<DirectiveLocation> = new Set([
+  "SCHEMA",
+  "SCALAR",
+  "INTERFACE",
+  "UNION",
+  "ENUM",
+]);
+
+type UsageLocation =
+  | "OBJECT"
+  | "FIELD_DEFINITION"
+  | "INPUT_OBJECT"
+  | "INPUT_FIELD_DEFINITION";
+
+interface DirectiveUsageContext {
+  readonly directiveName: string;
+  readonly usageLocation: UsageLocation;
+  readonly targetName: string;
+  readonly sourceFile: string;
+  readonly line: number;
+}
+
+function validateDirectiveUsage(
+  context: DirectiveUsageContext,
+  directiveDefMap: Map<string, DirectiveDefinitionInfo>,
+  diagnostics: Diagnostic[],
+): void {
+  const { directiveName, usageLocation, targetName, sourceFile, line } =
+    context;
+
+  const def = directiveDefMap.get(directiveName);
+  if (!def) {
+    diagnostics.push({
+      code: "UNDEFINED_DIRECTIVE",
+      message: `${targetName}: Directive '@${directiveName}' is not defined`,
+      severity: "error",
+      location: { file: sourceFile, line, column: 1 },
+    });
+    return;
+  }
+
+  for (const loc of def.locations) {
+    if (UNSUPPORTED_LOCATIONS.has(loc)) {
+      diagnostics.push({
+        code: "UNSUPPORTED_DIRECTIVE_LOCATION",
+        message: `${targetName}: Directive '@${directiveName}' uses unsupported location ${loc}`,
+        severity: "error",
+        location: { file: sourceFile, line, column: 1 },
+      });
+      return;
+    }
+  }
+
+  const allowedLocations = getCompatibleLocations(usageLocation);
+  const hasValidLocation = def.locations.some((loc) =>
+    allowedLocations.includes(loc),
+  );
+
+  if (!hasValidLocation) {
+    diagnostics.push({
+      code: "INVALID_DIRECTIVE_LOCATION",
+      message: `${targetName}: Directive '@${directiveName}' cannot be used on ${usageLocation} (allowed: ${def.locations.join(", ")})`,
+      severity: "error",
+      location: { file: sourceFile, line, column: 1 },
+    });
+  }
+}
+
+function getCompatibleLocations(
+  usageLocation: UsageLocation,
+): DirectiveLocation[] {
+  switch (usageLocation) {
+    case "OBJECT":
+      return ["OBJECT"];
+    case "FIELD_DEFINITION":
+      return ["FIELD_DEFINITION"];
+    case "INPUT_OBJECT":
+      return ["INPUT_OBJECT"];
+    case "INPUT_FIELD_DEFINITION":
+      return ["INPUT_FIELD_DEFINITION"];
+  }
+}
+
+export function integrate(
+  typesResult: ExtractTypesResult,
+  resolversResult: ExtractResolversResult,
+  customScalarNames: ReadonlyArray<string> | null,
+  collectedScalars?: ReadonlyArray<CollectedScalarType> | null,
+  directiveDefinitions?: ReadonlyArray<DirectiveDefinitionInfo> | null,
+  autoGeneratedTypes?: ReadonlyArray<AutoGeneratedType> | null,
+): IntegratedResult {
+  const directiveTypeAliasNames = new Set(
+    directiveDefinitions?.map((d) => d.typeAliasName) ?? [],
+  );
+
+  const diagnostics: Diagnostic[] = [];
+
+  diagnostics.push(...typesResult.diagnostics.errors);
+  diagnostics.push(...typesResult.diagnostics.warnings);
+  diagnostics.push(...resolversResult.diagnostics.errors);
+  diagnostics.push(...resolversResult.diagnostics.warnings);
+
+  const interfaceValidation = validateInterfaceImplementations(
+    typesResult.types,
+  );
+  diagnostics.push(...interfaceValidation.diagnostics);
+
+  const circularValidation = detectCircularInterfaceReferences(
+    typesResult.types,
+  );
+  diagnostics.push(...circularValidation.diagnostics);
+
+  const baseTypes: BaseType[] = [];
+  const inputTypes: InputType[] = [];
+
+  for (const autoType of autoGeneratedTypes ?? []) {
+    if (autoType.kind === "Object") {
+      baseTypes.push({
+        name: autoType.name,
+        kind: "Object",
+        fields: autoType.fields!.map((f) => ({
+          name: f.name,
+          type: f.type,
+          description: f.description,
+          deprecated: f.deprecated,
+          directives: f.directives,
+          defaultValue: f.defaultValue,
+        })),
+        unionMembers: null,
+        enumValues: null,
+        isNumericEnum: false,
+        needsStringEnumMapping: false,
+        implementedInterfaces: null,
+        description: autoType.description,
+        deprecated: null,
+        sourceFile: autoType.sourceLocation.file,
+        directives: null,
+      });
+    } else if (autoType.kind === "Enum") {
+      baseTypes.push({
+        name: autoType.name,
+        kind: "Enum",
+        fields: null,
+        unionMembers: null,
+        enumValues:
+          autoType.enumValues?.map((v) => ({
+            name: v.name,
+            originalValue: v.originalValue,
+            numericValue: null,
+            description: v.description,
+            deprecated: v.deprecated,
+          })) ?? null,
+        isNumericEnum: false,
+        needsStringEnumMapping: autoType.needsStringEnumMapping,
+        implementedInterfaces: null,
+        description: autoType.description,
+        deprecated: null,
+        sourceFile: autoType.sourceLocation.file,
+        directives: null,
+      });
+    } else {
+      inputTypes.push({
+        name: autoType.name,
+        fields: autoType.fields!.map((f) => ({
+          name: f.name,
+          type: f.type,
+          description: f.description,
+          deprecated: f.deprecated,
+          directives: f.directives,
+          defaultValue: f.defaultValue,
+        })),
+        sourceFile: autoType.sourceLocation.file,
+        description: autoType.description,
+        isOneOf: false,
+      });
+    }
+  }
+
+  for (const type of typesResult.types) {
+    if (directiveTypeAliasNames.has(type.name)) {
+      continue;
+    }
+
+    if (type.kind === "InputObject" || type.kind === "OneOfInputObject") {
+      inputTypes.push({
+        name: type.name,
+        fields:
+          type.fields?.map((field) => ({
+            name: field.name,
+            type: field.type,
+            description: field.description,
+            deprecated: field.deprecated,
+            directives: field.directives,
+            defaultValue: field.defaultValue,
+          })) ?? [],
+        sourceFile: type.sourceFile,
+        description: type.description,
+        isOneOf: type.kind === "OneOfInputObject",
+      });
+    } else if (type.kind === "Enum") {
+      baseTypes.push({
+        name: type.name,
+        kind: type.kind,
+        fields: null,
+        unionMembers: null,
+        enumValues: type.enumValues,
+        isNumericEnum: type.isNumericEnum,
+        needsStringEnumMapping: type.needsStringEnumMapping,
+        implementedInterfaces: null,
+        description: type.description,
+        deprecated: type.deprecated,
+        sourceFile: type.sourceFile,
+        directives: type.directives,
+      });
+    } else if (type.kind === "Interface") {
+      baseTypes.push({
+        name: type.name,
+        kind: type.kind,
+        fields:
+          type.fields?.map((field) => ({
+            name: field.name,
+            type: field.type,
+            description: field.description,
+            deprecated: field.deprecated,
+            directives: field.directives,
+            defaultValue: field.defaultValue,
+          })) ?? null,
+        unionMembers: null,
+        enumValues: null,
+        isNumericEnum: false,
+        needsStringEnumMapping: false,
+        implementedInterfaces: type.implementedInterfaces ?? null,
+        description: type.description,
+        deprecated: type.deprecated,
+        sourceFile: type.sourceFile,
+        directives: type.directives,
+      });
+    } else if (type.kind === "Object") {
+      baseTypes.push({
+        name: type.name,
+        kind: type.kind,
+        fields:
+          type.fields?.map((field) => ({
+            name: field.name,
+            type: field.type,
+            description: field.description,
+            deprecated: field.deprecated,
+            directives: field.directives,
+            defaultValue: field.defaultValue,
+          })) ?? null,
+        unionMembers: null,
+        enumValues: null,
+        isNumericEnum: false,
+        needsStringEnumMapping: false,
+        implementedInterfaces: type.implementedInterfaces ?? null,
+        description: type.description,
+        deprecated: type.deprecated,
+        sourceFile: type.sourceFile,
+        directives: type.directives,
+      });
+    } else {
+      baseTypes.push({
+        name: type.name,
+        kind: type.kind,
+        fields: null,
+        unionMembers: type.unionMembers,
+        enumValues: null,
+        isNumericEnum: false,
+        needsStringEnumMapping: false,
+        implementedInterfaces: null,
+        description: type.description,
+        deprecated: null,
+        sourceFile: type.sourceFile,
+        directives: type.directives,
+      });
+    }
+  }
+
+  const hasQuery = resolversResult.queryFields.fields.length > 0;
+  const hasMutation = resolversResult.mutationFields.fields.length > 0;
+
+  if (hasQuery) {
+    baseTypes.push({
+      name: "Query",
+      kind: "Object",
+      fields: [],
+      unionMembers: null,
+      enumValues: null,
+      isNumericEnum: false,
+      needsStringEnumMapping: false,
+      implementedInterfaces: null,
+      description: null,
+      deprecated: null,
+      sourceFile: null,
+      directives: null,
+    });
+  }
+  if (hasMutation) {
+    baseTypes.push({
+      name: "Mutation",
+      kind: "Object",
+      fields: [],
+      unionMembers: null,
+      enumValues: null,
+      isNumericEnum: false,
+      needsStringEnumMapping: false,
+      implementedInterfaces: null,
+      description: null,
+      deprecated: null,
+      sourceFile: null,
+      directives: null,
+    });
+  }
+
+  const abstractResolverValidation = validateAbstractResolvers({
+    abstractResolvers: resolversResult.abstractTypeResolvers,
+    baseTypes,
+  });
+  diagnostics.push(...abstractResolverValidation.diagnostics);
+
+  const knownTypeNames = new Set([
+    ...baseTypes.map((t) => t.name),
+    ...inputTypes.map((t) => t.name),
+  ]);
+
+  const typeExtensions: TypeExtension[] = [];
+
+  if (hasQuery) {
+    typeExtensions.push({
+      targetTypeName: "Query",
+      fields: resolversResult.queryFields.fields.map(convertToExtensionField),
+    });
+  }
+
+  if (hasMutation) {
+    typeExtensions.push({
+      targetTypeName: "Mutation",
+      fields: resolversResult.mutationFields.fields.map(
+        convertToExtensionField,
+      ),
+    });
+  }
+
+  for (const ext of resolversResult.typeExtensions) {
+    if (!knownTypeNames.has(ext.targetTypeName)) {
+      const firstField = ext.fields[0];
+      diagnostics.push({
+        code: "UNKNOWN_TARGET_TYPE",
+        message: `Type extension references unknown type '${ext.targetTypeName}'`,
+        severity: "error",
+        location: firstField
+          ? {
+              file: firstField.sourceLocation.file,
+              line: firstField.sourceLocation.line,
+              column: firstField.sourceLocation.column,
+            }
+          : null,
+      });
+    } else {
+      typeExtensions.push(convertResolverTypeExtension(ext));
+    }
+  }
+
+  const directiveDefMap = new Map<string, DirectiveDefinitionInfo>();
+  for (const def of directiveDefinitions ?? []) {
+    directiveDefMap.set(def.name, def);
+  }
+
+  for (const type of typesResult.types) {
+    if (directiveTypeAliasNames.has(type.name)) {
+      continue;
+    }
+
+    const usageLocation: UsageLocation =
+      type.kind === "InputObject" || type.kind === "OneOfInputObject"
+        ? "INPUT_OBJECT"
+        : "OBJECT";
+
+    if (type.directives) {
+      for (const directive of type.directives) {
+        validateDirectiveUsage(
+          {
+            directiveName: directive.name,
+            usageLocation,
+            targetName: `Type '${type.name}'`,
+            sourceFile: type.sourceFile,
+            line: 1,
+          },
+          directiveDefMap,
+          diagnostics,
+        );
+      }
+    }
+
+    const fieldUsageLocation: UsageLocation =
+      type.kind === "InputObject" || type.kind === "OneOfInputObject"
+        ? "INPUT_FIELD_DEFINITION"
+        : "FIELD_DEFINITION";
+
+    for (const field of type.fields ?? []) {
+      if (field.directives) {
+        for (const directive of field.directives) {
+          validateDirectiveUsage(
+            {
+              directiveName: directive.name,
+              usageLocation: fieldUsageLocation,
+              targetName: `Field '${type.name}.${field.name}'`,
+              sourceFile: type.sourceFile,
+              line: 1,
+            },
+            directiveDefMap,
+            diagnostics,
+          );
+        }
+      }
+    }
+  }
+
+  for (const ext of typeExtensions) {
+    for (const field of ext.fields) {
+      if (field.directives) {
+        for (const directive of field.directives) {
+          validateDirectiveUsage(
+            {
+              directiveName: directive.name,
+              usageLocation: "FIELD_DEFINITION",
+              targetName: `Field '${ext.targetTypeName}.${field.name}'`,
+              sourceFile: field.resolverSourceFile,
+              line: 1,
+            },
+            directiveDefMap,
+            diagnostics,
+          );
+        }
+      }
+    }
+  }
+
+  const hasErrors = diagnostics.some((d) => d.severity === "error");
+
+  const scalarDescriptionMap = new Map<string, string | null>();
+  if (collectedScalars) {
+    for (const scalar of collectedScalars) {
+      const description = mergeDescriptions(scalar.descriptions);
+      scalarDescriptionMap.set(scalar.scalarName, description);
+    }
+  }
+
+  const customScalars: CustomScalarInfo[] | null =
+    customScalarNames && customScalarNames.length > 0
+      ? customScalarNames.map((name) => ({
+          scalarName: name,
+          description: scalarDescriptionMap.get(name) ?? null,
+        }))
+      : null;
+
+  const numericEnums: NumericEnumInfo[] = baseTypes
+    .filter(
+      (
+        type,
+      ): type is BaseType & {
+        enumValues: NonNullable<BaseType["enumValues"]>;
+      } =>
+        type.kind === "Enum" && type.isNumericEnum && type.enumValues !== null,
+    )
+    .map((type) => ({
+      enumName: type.name,
+      members: type.enumValues
+        .filter(
+          (value): value is typeof value & { numericValue: number } =>
+            value.numericValue !== null,
+        )
+        .map((value) => ({
+          name: value.name,
+          numericValue: value.numericValue,
+        })),
+    }))
+    .filter((info) => info.members.length > 0);
+
+  const stringEnumMappings: StringEnumMappingInfo[] = baseTypes
+    .filter(
+      (
+        type,
+      ): type is BaseType & {
+        enumValues: NonNullable<BaseType["enumValues"]>;
+      } =>
+        type.kind === "Enum" &&
+        type.needsStringEnumMapping &&
+        type.enumValues !== null,
+    )
+    .map((type) => ({
+      enumName: type.name,
+      members: type.enumValues.map((value) => ({
+        graphqlValue: value.name,
+        typescriptValue: value.originalValue,
+      })),
+    }))
+    .filter((info) => info.members.length > 0);
+
+  return {
+    baseTypes,
+    inputTypes,
+    typeExtensions,
+    customScalarNames:
+      customScalarNames && customScalarNames.length > 0
+        ? customScalarNames
+        : null,
+    customScalars,
+    directiveDefinitions:
+      directiveDefinitions && directiveDefinitions.length > 0
+        ? directiveDefinitions
+        : null,
+    abstractTypeResolvers: resolversResult.abstractTypeResolvers,
+    numericEnums,
+    stringEnumMappings,
+    hasQuery,
+    hasMutation,
+    hasErrors,
+    diagnostics,
+  };
+}