@gqlkit-ts/cli 0.1.0 → 0.3.0

package/src/auto-type-generator/typename-resolve-type-generator.ts

@@ -0,0 +1,281 @@
+import type {
+  ExtractedTypeInfo,
+  InlineObjectMember,
+  InlineObjectProperty,
+} from "../type-extractor/types/index.js";
+import type {
+  AutoGeneratedField,
+  AutoGeneratedType,
+} from "./auto-type-generator.js";
+import type { ResolveTypeFieldPattern } from "./resolve-type-generator.js";
+import {
+  collectTypenameExtractions,
+  type TypenameExtractionResult,
+} from "./typename-extractor.js";
+import type { TypenameFieldName } from "./typename-types.js";
+
+/**
+ * Pattern for resolveType generation from typename fields.
+ * Uses the common ResolveTypeFieldPattern for usedFieldNames,
+ * with an optional memberFieldMap for mixed patterns.
+ */
+export interface ResolveTypePattern extends ResolveTypeFieldPattern {
+  readonly memberFieldMap: ReadonlyMap<string, TypenameFieldName> | null;
+}
+
+export interface TypenameAutoResolveTypeInfo {
+  readonly abstractTypeName: string;
+  readonly abstractTypeKind: "union" | "interface";
+  readonly resolveTypePattern: ResolveTypePattern;
+}
+
+export interface GeneratedInlineObjectType {
+  readonly typeName: string;
+  readonly abstractTypeName: string;
+  readonly memberIndex: number;
+}
+
+export interface CollectTypenameResolveTypesParams {
+  readonly extractedTypes: ReadonlyArray<ExtractedTypeInfo>;
+  readonly typeMap: ReadonlyMap<string, ExtractedTypeInfo>;
+  readonly manualResolveTypeNames: ReadonlySet<string>;
+}
+
+export interface CollectTypenameResolveTypesResult {
+  readonly autoResolveTypes: ReadonlyArray<TypenameAutoResolveTypeInfo>;
+  readonly autoResolveTypeNames: ReadonlySet<string>;
+  readonly generatedObjectTypes: ReadonlyArray<AutoGeneratedType>;
+  readonly generatedInlineObjectTypes: ReadonlyArray<GeneratedInlineObjectType>;
+}
+
+function determineResolveTypePattern(
+  extraction: TypenameExtractionResult,
+): ResolveTypePattern | null {
+  if (!extraction.allMembersHaveTypename) {
+    return null;
+  }
+
+  const members = extraction.members;
+  if (members.length === 0) {
+    return null;
+  }
+
+  const usedFieldNames = new Set<TypenameFieldName>();
+
+  for (const member of members) {
+    if (member.typenameInfo === null) {
+      return null;
+    }
+    usedFieldNames.add(member.typenameInfo.fieldName);
+  }
+
+  if (usedFieldNames.size === 1) {
+    return { usedFieldNames, memberFieldMap: null };
+  }
+
+  const memberFieldMap = new Map<string, TypenameFieldName>();
+  for (const member of members) {
+    if (member.typenameInfo && member.memberTypeName) {
+      memberFieldMap.set(member.memberTypeName, member.typenameInfo.fieldName);
+    }
+  }
+
+  return { usedFieldNames, memberFieldMap };
+}
+
+function primitiveToGraphQLScalar(primitive: string): string {
+  switch (primitive) {
+    case "string":
+      return "String";
+    case "number":
+      return "Float";
+    case "boolean":
+      return "Boolean";
+    default:
+      return "String";
+  }
+}
+
+function convertInlineObjectPropertyToField(
+  property: InlineObjectProperty,
+): AutoGeneratedField | null {
+  if (
+    property.propertyName === "__typename" ||
+    property.propertyName === "$typeName"
+  ) {
+    return null;
+  }
+
+  const tsType = property.propertyType;
+  let typeName: string;
+  const nullable = tsType.nullable;
+  let list = false;
+  let listItemNullable: boolean | null = null;
+
+  if (tsType.kind === "array" && tsType.elementType) {
+    list = true;
+    listItemNullable = tsType.elementType.nullable;
+    const elementName = tsType.elementType.name ?? "String";
+    typeName =
+      tsType.elementType.kind === "primitive"
+        ? primitiveToGraphQLScalar(elementName)
+        : elementName;
+  } else if (tsType.kind === "reference" && tsType.name) {
+    typeName = tsType.name;
+  } else if (tsType.kind === "primitive" && tsType.name) {
+    typeName = primitiveToGraphQLScalar(tsType.name);
+  } else if (tsType.kind === "scalar" && tsType.scalarInfo) {
+    typeName = tsType.scalarInfo.scalarName;
+  } else {
+    typeName = "String";
+  }
+
+  return {
+    name: property.propertyName,
+    type: {
+      typeName,
+      nullable,
+      list,
+      listItemNullable,
+    },
+    description: property.description,
+    deprecated: property.deprecated,
+    directives: null,
+    defaultValue: null,
+  };
+}
+
+function generateObjectTypeFromInlineObject(
+  inlineObjectMember: InlineObjectMember,
+  typeName: string,
+  abstractTypeName: string,
+  sourceFile: string,
+): AutoGeneratedType {
+  const fields: AutoGeneratedField[] = [];
+
+  for (const property of inlineObjectMember.properties) {
+    const field = convertInlineObjectPropertyToField(property);
+    if (field !== null) {
+      fields.push(field);
+    }
+  }
+
+  return {
+    name: typeName,
+    kind: "Object",
+    fields,
+    enumValues: null,
+    unionMembers: null,
+    needsStringEnumMapping: false,
+    sourceLocation: { file: sourceFile, line: 1, column: 1 },
+    generatedFrom: {
+      parentTypeName: abstractTypeName,
+      fieldPath: [],
+      context: "typeField",
+    },
+    description: null,
+    resolveTypeFieldPattern: null,
+  };
+}
+
+function collectGeneratedObjectTypes(
+  extraction: TypenameExtractionResult,
+  extractedType: ExtractedTypeInfo,
+): {
+  generatedObjectTypes: AutoGeneratedType[];
+  generatedInlineObjectTypes: GeneratedInlineObjectType[];
+} {
+  const generatedObjectTypes: AutoGeneratedType[] = [];
+  const generatedInlineObjectTypes: GeneratedInlineObjectType[] = [];
+
+  if (!extraction.hasInlineObjects) {
+    return { generatedObjectTypes, generatedInlineObjectTypes };
+  }
+
+  const inlineObjectMembers = extractedType.inlineObjectMembers ?? [];
+  const namedMemberCount = extractedType.unionMembers?.length ?? 0;
+
+  for (const member of extraction.members) {
+    if (!member.isInlineObject || member.typenameInfo === null) {
+      continue;
+    }
+
+    const inlineIndex = member.memberIndex - namedMemberCount;
+    const inlineObjectMember = inlineObjectMembers[inlineIndex];
+
+    if (!inlineObjectMember) {
+      continue;
+    }
+
+    const typeName = member.typenameInfo.typeName;
+
+    const objectType = generateObjectTypeFromInlineObject(
+      inlineObjectMember,
+      typeName,
+      extraction.abstractTypeName,
+      extractedType.metadata.sourceFile,
+    );
+
+    generatedObjectTypes.push(objectType);
+    generatedInlineObjectTypes.push({
+      typeName,
+      abstractTypeName: extraction.abstractTypeName,
+      memberIndex: member.memberIndex,
+    });
+  }
+
+  return { generatedObjectTypes, generatedInlineObjectTypes };
+}
+
+export function collectTypenameResolveTypes(
+  params: CollectTypenameResolveTypesParams,
+): CollectTypenameResolveTypesResult {
+  const { extractedTypes, typeMap, manualResolveTypeNames } = params;
+
+  const extractions = collectTypenameExtractions({
+    extractedTypes,
+    typeMap,
+  });
+
+  const autoResolveTypes: TypenameAutoResolveTypeInfo[] = [];
+  const autoResolveTypeNames = new Set<string>();
+  const allGeneratedObjectTypes: AutoGeneratedType[] = [];
+  const allGeneratedInlineObjectTypes: GeneratedInlineObjectType[] = [];
+
+  const typeInfoMap = new Map(extractedTypes.map((t) => [t.metadata.name, t]));
+
+  for (const extraction of extractions) {
+    if (manualResolveTypeNames.has(extraction.abstractTypeName)) {
+      continue;
+    }
+
+    const extractedType = typeInfoMap.get(extraction.abstractTypeName);
+    if (extractedType && extraction.hasInlineObjects) {
+      const { generatedObjectTypes, generatedInlineObjectTypes } =
+        collectGeneratedObjectTypes(extraction, extractedType);
+      allGeneratedObjectTypes.push(...generatedObjectTypes);
+      allGeneratedInlineObjectTypes.push(...generatedInlineObjectTypes);
+    }
+
+    const pattern = determineResolveTypePattern(extraction);
+    if (pattern === null) {
+      continue;
+    }
+
+    autoResolveTypes.push({
+      abstractTypeName: extraction.abstractTypeName,
+      abstractTypeKind: extraction.abstractTypeKind,
+      resolveTypePattern: pattern,
+    });
+    autoResolveTypeNames.add(extraction.abstractTypeName);
+  }
+
+  return {
+    autoResolveTypes: autoResolveTypes.sort((a, b) =>
+      a.abstractTypeName.localeCompare(b.abstractTypeName),
+    ),
+    autoResolveTypeNames,
+    generatedObjectTypes: allGeneratedObjectTypes,
+    generatedInlineObjectTypes: allGeneratedInlineObjectTypes,
+  };
+}

package/src/auto-type-generator/typename-types.ts

@@ -0,0 +1,66 @@
+/**
+ * Common types for typename-related functionality.
+ * These types are shared across typename-extractor, typename-validator,
+ * typename-resolve-type-generator, and inline-union-validator.
+ */
+
+/**
+ * All recognized field names for type discrimination.
+ * - "__typename" is the standard GraphQL introspection field
+ * - "$typeName" is a gqlkit-specific alternative that won't appear in the schema
+ *
+ * To add a new typename field:
+ * 1. Add the field name to this array
+ * 2. Update findTypenameProperty priority if needed
+ */
+export const TYPENAME_FIELD_NAMES = ["__typename", "$typeName"] as const;
+
+/**
+ * The field name used for type discrimination.
+ */
+export type TypenameFieldName = (typeof TYPENAME_FIELD_NAMES)[number];
+
+/**
+ * A set of typename field names used in a resolve type pattern.
+ */
+export type TypenameFieldNameSet = ReadonlySet<TypenameFieldName>;
+
+/**
+ * Create a TypenameFieldNameSet from field names.
+ */
+export function createFieldNameSet(
+  fieldNames: ReadonlyArray<TypenameFieldName>,
+): TypenameFieldNameSet {
+  return new Set(fieldNames);
+}
+
+/**
+ * Information about a typename field extracted from a type definition.
+ */
+export interface TypenameFieldInfo {
+  readonly typeName: string;
+  readonly fieldName: TypenameFieldName;
+}
+
+/**
+ * Find __typename or $typeName property from a list of properties.
+ * __typename takes priority over $typeName.
+ */
+export function findTypenameProperty<T>(
+  properties: ReadonlyArray<T>,
+  getName: (p: T) => string,
+): { property: T; fieldName: TypenameFieldName } | null {
+  const typenameProperty = properties.find((p) => getName(p) === "__typename");
+  if (typenameProperty) {
+    return { property: typenameProperty, fieldName: "__typename" };
+  }
+
+  const dollarTypenameProperty = properties.find(
+    (p) => getName(p) === "$typeName",
+  );
+  if (dollarTypenameProperty) {
+    return { property: dollarTypenameProperty, fieldName: "$typeName" };
+  }
+
+  return null;
+}

package/src/auto-type-generator/typename-validator.ts

@@ -0,0 +1,326 @@
+import type {
+  Diagnostic,
+  ExtractedTypeInfo,
+  InlineObjectMember,
+  SourceLocation,
+} from "../type-extractor/types/index.js";
+import type { TypenameExtractionResult } from "./typename-extractor.js";
+import {
+  findTypenameProperty,
+  type TypenameFieldName,
+} from "./typename-types.js";
+
+export interface ValidateTypenamesParams {
+  readonly extractionResult: TypenameExtractionResult;
+  readonly sourceLocation: SourceLocation;
+  readonly inlineObjectMembers: ReadonlyArray<InlineObjectMember> | null;
+}
+
+export interface ValidateTypenamesResult {
+  readonly valid: boolean;
+  readonly diagnostics: ReadonlyArray<Diagnostic>;
+}
+
+export interface ValidateSchemaTypenamesParams {
+  readonly objectTypes: ReadonlyArray<ExtractedTypeInfo>;
+  readonly typeMap: ReadonlyMap<string, ExtractedTypeInfo>;
+}
+
+export interface ValidateSchemaTypenamesResult {
+  readonly valid: boolean;
+  readonly diagnostics: ReadonlyArray<Diagnostic>;
+}
+
+interface TypenameValueInfo {
+  readonly memberTypeName: string;
+  readonly fieldName: TypenameFieldName;
+}
+
+function getAbstractTypeLabel(kind: "union" | "interface"): string {
+  return kind === "union" ? "Union" : "Interface";
+}
+
+function getMemberLabel(kind: "union" | "interface"): string {
+  return kind === "union" ? "members" : "implementers";
+}
+
+interface InlineObjectTypenameAnalysis {
+  readonly exists: boolean;
+  readonly fieldName: TypenameFieldName | null;
+  readonly isStringLiteral: boolean;
+  readonly isNullable: boolean;
+}
+
+function analyzeInlineObjectTypename(
+  inlineObjectMember: InlineObjectMember,
+): InlineObjectTypenameAnalysis {
+  const found = findTypenameProperty(
+    inlineObjectMember.properties,
+    (p) => p.propertyName,
+  );
+
+  if (!found) {
+    return {
+      exists: false,
+      fieldName: null,
+      isStringLiteral: false,
+      isNullable: false,
+    };
+  }
+
+  const { property, fieldName } = found;
+  const { propertyType: tsType } = property;
+
+  return {
+    exists: true,
+    fieldName,
+    isStringLiteral: tsType.kind === "literal" && tsType.name !== null,
+    isNullable: tsType.nullable,
+  };
+}
+
+function validateInlineObjectsTypenames(
+  extractionResult: TypenameExtractionResult,
+  inlineObjectMembers: ReadonlyArray<InlineObjectMember>,
+  sourceLocation: SourceLocation,
+): Diagnostic[] {
+  if (!extractionResult.hasInlineObjects) {
+    return [];
+  }
+
+  if (extractionResult.abstractTypeName.endsWith("Input")) {
+    return [];
+  }
+
+  const diagnostics: Diagnostic[] = [];
+  const abstractTypeName = extractionResult.abstractTypeName;
+  const abstractTypeLabel = getAbstractTypeLabel(
+    extractionResult.abstractTypeKind,
+  );
+
+  const namedMemberCount = extractionResult.members.filter(
+    (m) => !m.isInlineObject,
+  ).length;
+
+  for (const member of extractionResult.members) {
+    if (member.isInlineObject) {
+      const inlineIndex = member.memberIndex - namedMemberCount;
+      const inlineObjectMember = inlineObjectMembers[inlineIndex];
+
+      if (inlineObjectMember) {
+        const analysis = analyzeInlineObjectTypename(inlineObjectMember);
+
+        if (!analysis.exists) {
+          diagnostics.push({
+            code: "MISSING_TYPENAME_PROPERTY",
+            message: `${abstractTypeLabel} '${abstractTypeName}' member at index ${member.memberIndex} is missing '__typename' or '$typeName' property. When a union contains inline objects, all members must have a typename property.`,
+            severity: "error",
+            location: sourceLocation,
+          });
+        } else if (!analysis.isStringLiteral) {
+          diagnostics.push({
+            code: "INVALID_TYPENAME_TYPE",
+            message: `${abstractTypeLabel} '${abstractTypeName}' member at index ${member.memberIndex} has '${analysis.fieldName}' that is not a string literal type. Expected a string literal like '__typename: "TypeName"'.`,
+            severity: "error",
+            location: sourceLocation,
+          });
+        } else if (analysis.isNullable) {
+          diagnostics.push({
+            code: "NULLABLE_TYPENAME_PROPERTY",
+            message: `${abstractTypeLabel} '${abstractTypeName}' member at index ${member.memberIndex} has nullable '${analysis.fieldName}' property. The typename property must not be nullable.`,
+            severity: "error",
+            location: sourceLocation,
+          });
+        }
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+/**
+ * Validates typename fields within an abstract type.
+ * Reports errors for:
+ * - DUPLICATE_TYPENAME_VALUE: Multiple members have the same typename value
+ * - MISSING_TYPENAME_PROPERTY: Inline objects without typename (when union has inline objects)
+ * - INVALID_TYPENAME_TYPE: Typename is not a string literal type
+ * - NULLABLE_TYPENAME_PROPERTY: Typename is nullable
+ */
+export function validateTypenames(
+  params: ValidateTypenamesParams,
+): ValidateTypenamesResult {
+  const { extractionResult, sourceLocation, inlineObjectMembers } = params;
+  const diagnostics: Diagnostic[] = [];
+
+  if (inlineObjectMembers) {
+    const inlineValidationDiagnostics = validateInlineObjectsTypenames(
+      extractionResult,
+      inlineObjectMembers,
+      sourceLocation,
+    );
+    diagnostics.push(...inlineValidationDiagnostics);
+  }
+
+  const typenameValueToMembers = new Map<string, TypenameValueInfo[]>();
+
+  for (const member of extractionResult.members) {
+    if (member.typenameInfo === null) {
+      continue;
+    }
+
+    const { typeName, fieldName } = member.typenameInfo;
+    const memberTypeName =
+      member.memberTypeName ?? `member${member.memberIndex}`;
+
+    const existing = typenameValueToMembers.get(typeName) ?? [];
+    existing.push({ memberTypeName, fieldName });
+    typenameValueToMembers.set(typeName, existing);
+  }
+
+  const abstractTypeLabel = getAbstractTypeLabel(
+    extractionResult.abstractTypeKind,
+  );
+  const memberLabel = getMemberLabel(extractionResult.abstractTypeKind);
+
+  for (const [typenameValue, members] of typenameValueToMembers) {
+    if (members.length > 1) {
+      const allSameFieldName = members.every(
+        (m) => m.fieldName === members[0]!.fieldName,
+      );
+
+      let message: string;
+      if (allSameFieldName) {
+        const memberNames = members
+          .map((m) => `'${m.memberTypeName}'`)
+          .join(" and ");
+        message = `Duplicate typename value '${typenameValue}' in ${abstractTypeLabel} '${extractionResult.abstractTypeName}': used by ${memberLabel} ${memberNames}.`;
+      } else {
+        const memberDescriptions = members
+          .map((m) => `member '${m.memberTypeName}' (${m.fieldName})`)
+          .join(" and ");
+        message = `Duplicate typename value '${typenameValue}' in ${abstractTypeLabel} '${extractionResult.abstractTypeName}': ${memberDescriptions} have the same value.`;
+      }
+
+      diagnostics.push({
+        code: "DUPLICATE_TYPENAME_VALUE",
+        message,
+        severity: "error",
+        location: sourceLocation,
+      });
+    }
+  }
+
+  return {
+    valid: diagnostics.length === 0,
+    diagnostics,
+  };
+}
+
+interface ObjectTypeTypenameInfo {
+  readonly typeName: string;
+  readonly typenameValue: string;
+  readonly fieldName: TypenameFieldName;
+  readonly sourceLocation: SourceLocation;
+}
+
+function extractTypenameFromObjectType(
+  typeInfo: ExtractedTypeInfo,
+): ObjectTypeTypenameInfo | null {
+  const found = findTypenameProperty(typeInfo.fields, (f) => f.name);
+  if (!found) {
+    return null;
+  }
+
+  const { property: field, fieldName } = found;
+  const { tsType } = field;
+
+  if (
+    field.optional ||
+    tsType.nullable ||
+    tsType.kind !== "literal" ||
+    tsType.name === null
+  ) {
+    return null;
+  }
+
+  return {
+    typeName: typeInfo.metadata.name,
+    typenameValue: tsType.name,
+    fieldName,
+    sourceLocation: typeInfo.metadata.sourceLocation,
+  };
+}
+
+/**
+ * Validates that there are no duplicate typename values across the entire schema.
+ * Reports DUPLICATE_TYPENAME_VALUE error when:
+ * - Different object types have the same __typename value (Requirement 4.7)
+ * - Different object types have the same $typeName value (Requirement 4.8)
+ * - An object's __typename equals another object's $typeName (Requirement 4.9)
+ */
+export function validateSchemaTypenames(
+  params: ValidateSchemaTypenamesParams,
+): ValidateSchemaTypenamesResult {
+  const { objectTypes } = params;
+  const diagnostics: Diagnostic[] = [];
+
+  const typenameValueToTypes = new Map<string, ObjectTypeTypenameInfo[]>();
+
+  for (const typeInfo of objectTypes) {
+    if (
+      typeInfo.metadata.kind !== "object" &&
+      typeInfo.metadata.kind !== "interface" &&
+      typeInfo.metadata.kind !== "graphqlInterface"
+    ) {
+      continue;
+    }
+
+    const typenameInfo = extractTypenameFromObjectType(typeInfo);
+    if (typenameInfo === null) {
+      continue;
+    }
+
+    const existing = typenameValueToTypes.get(typenameInfo.typenameValue) ?? [];
+    existing.push(typenameInfo);
+    typenameValueToTypes.set(typenameInfo.typenameValue, existing);
+  }
+
+  for (const [typenameValue, types] of typenameValueToTypes) {
+    if (types.length > 1) {
+      const allSameFieldName = types.every(
+        (t) => t.fieldName === types[0]!.fieldName,
+      );
+
+      const sortedTypes = [...types].sort((a, b) =>
+        a.typeName.localeCompare(b.typeName),
+      );
+
+      let message: string;
+      if (allSameFieldName) {
+        const typeNames = sortedTypes
+          .map((t) => `'${t.typeName}'`)
+          .join(" and ");
+        message = `Duplicate typename value '${typenameValue}' in schema: types ${typeNames} have the same ${sortedTypes[0]!.fieldName} value.`;
+      } else {
+        const typeDescriptions = sortedTypes
+          .map((t) => `'${t.typeName}' (${t.fieldName})`)
+          .join(" and ");
+        message = `Duplicate typename value '${typenameValue}' in schema: types ${typeDescriptions} have the same value.`;
+      }
+
+      const firstType = sortedTypes[1]!;
+      diagnostics.push({
+        code: "DUPLICATE_TYPENAME_VALUE",
+        message,
+        severity: "error",
+        location: firstType.sourceLocation,
+      });
+    }
+  }
+
+  return {
+    valid: diagnostics.length === 0,
+    diagnostics,
+  };
+}

package/src/cli.ts

@@ -0,0 +1,13 @@
+import { cli } from "gunshi";
+import { docsCommand } from "./commands/docs.js";
+import { genCommand } from "./commands/gen.js";
+import { mainCommand } from "./commands/main.js";
+
+await cli(process.argv.slice(2), mainCommand, {
+  name: "gqlkit",
+  version: "0.0.0",
+  subCommands: {
+    docs: docsCommand,
+    gen: genCommand,
+  },
+});