@gqlkit-ts/cli 0.2.0 → 0.3.0

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

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

package/src/commands/docs.ts

@@ -0,0 +1,211 @@
+import { access, mkdir, readFile, symlink, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { define } from "gunshi";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLI_DOCS_DIR = join(__dirname, "../../docs");
+const SKILL_NAME = "gqlkit-guide";
+
+export interface RunDocsCommandOptions {
+  readonly output: string;
+  readonly claude: boolean;
+  readonly codex: boolean;
+}
+
+export interface RunDocsCommandResult {
+  readonly exitCode: number;
+  readonly filesWritten: string[];
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function detectClaudeEnvironment(dir: string): Promise<boolean> {
+  const claudeMdExists = await exists(join(dir, "CLAUDE.md"));
+  const claudeDirExists = await exists(join(dir, ".claude"));
+  return claudeMdExists || claudeDirExists;
+}
+
+async function detectCodexEnvironment(dir: string): Promise<boolean> {
+  const agentsMdExists = await exists(join(dir, "AGENTS.md"));
+  const codexDirExists = await exists(join(dir, ".codex"));
+  return agentsMdExists || codexDirExists;
+}
+
+function generateSkillMd(): string {
+  return `---
+name: ${SKILL_NAME}
+description: Use when the user asks about "gqlkit", "gqlkit usage", "gqlkit schema definition", "gqlkit configuration", "gqlkit resolvers", "GraphQL code generation with gqlkit", or needs guidance on gqlkit conventions, type definitions, or integration with GraphQL servers or ORMs.
+---
+
+# gqlkit Guide
+
+gqlkit generates GraphQL schema and resolver maps from TypeScript types and functions.
+
+## How it works
+
+1. Write TypeScript types in \`src/gqlkit/schema/\` → become GraphQL types
+2. Write resolver functions using \`defineQuery\`, \`defineMutation\`, \`defineField\` → become GraphQL resolvers
+3. Run \`gqlkit gen\` → outputs \`typeDefs\` and \`resolvers\` to \`src/gqlkit/__generated__/\`
+
+## Design principles
+
+- **Implement first**: Write types and resolvers, generate schema when ready. No edit-regenerate-implement loops.
+- **Just types and functions**: Plain TypeScript with a thin API. No decorators, no complex generics.
+- **Type-safe**: TypeScript types become GraphQL types. Resolver signatures checked at compile time.
+
+## How to Use This Skill
+
+Read [references/index.md](references/index.md) first. It contains the complete documentation index with all available topics.
+
+Navigate to specific documentation files based on user needs as indicated in the index.
+`;
+}
+
+function generateRules(): string {
+  return `## gqlkit
+
+When working with GraphQL schema, types, or resolvers using gqlkit, use the \`${SKILL_NAME}\` skill.
+`;
+}
+
+async function createSymlinkIfNotExists(
+  linkPath: string,
+  target: string,
+): Promise<void> {
+  try {
+    await symlink(target, linkPath, "dir");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+      throw error;
+    }
+  }
+}
+
+async function appendOrCreateFile(
+  filePath: string,
+  content: string,
+): Promise<void> {
+  try {
+    const existing = await readFile(filePath, "utf-8");
+    if (!existing.includes("## gqlkit")) {
+      await writeFile(filePath, `${existing}\n${content}`);
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      await writeFile(filePath, content);
+    } else {
+      throw error;
+    }
+  }
+}
+
+interface AiToolConfig {
+  readonly configDir: string;
+  readonly rulesFile: string;
+}
+
+async function generateToolFiles(
+  outputDir: string,
+  config: AiToolConfig,
+  filesWritten: string[],
+): Promise<void> {
+  const skillDir = join(outputDir, `${config.configDir}/skills/${SKILL_NAME}`);
+  await mkdir(skillDir, { recursive: true });
+
+  const skillMdPath = join(skillDir, "SKILL.md");
+  await writeFile(skillMdPath, generateSkillMd());
+  filesWritten.push(skillMdPath);
+
+  const referencesPath = join(skillDir, "references");
+  const relativePath = relative(skillDir, CLI_DOCS_DIR);
+  await createSymlinkIfNotExists(referencesPath, relativePath);
+  filesWritten.push(referencesPath);
+
+  const rulesPath = join(outputDir, config.rulesFile);
+  await appendOrCreateFile(rulesPath, generateRules());
+  filesWritten.push(rulesPath);
+}
+
+export async function runDocsCommand(
+  options: RunDocsCommandOptions,
+): Promise<RunDocsCommandResult> {
+  if (!(await exists(CLI_DOCS_DIR))) {
+    console.error(
+      `Documentation directory not found: ${CLI_DOCS_DIR}\nRun "pnpm build" to generate documentation files.`,
+    );
+    return { exitCode: 1, filesWritten: [] };
+  }
+
+  const filesWritten: string[] = [];
+
+  const autoDetect = !options.claude && !options.codex;
+  const generateClaude =
+    options.claude ||
+    (autoDetect && (await detectClaudeEnvironment(options.output)));
+  const generateCodex =
+    options.codex ||
+    (autoDetect && (await detectCodexEnvironment(options.output)));
+
+  if (!generateClaude && !generateCodex) {
+    console.log(
+      "No AI tool environment detected. Use --claude or --codex to generate explicitly.",
+    );
+    return { exitCode: 0, filesWritten: [] };
+  }
+
+  if (generateClaude) {
+    await generateToolFiles(
+      options.output,
+      { configDir: ".claude", rulesFile: "CLAUDE.md" },
+      filesWritten,
+    );
+  }
+
+  if (generateCodex) {
+    await generateToolFiles(
+      options.output,
+      { configDir: ".codex", rulesFile: "AGENTS.md" },
+      filesWritten,
+    );
+  }
+
+  return { exitCode: 0, filesWritten };
+}
+
+export const docsCommand = define({
+  name: "docs",
+  args: {
+    output: {
+      type: "string",
+      description: "Output directory for generated files",
+    },
+    claude: {
+      type: "boolean",
+      description: `Generate Claude Code files (.claude/skills/${SKILL_NAME}/, CLAUDE.md)`,
+    },
+    codex: {
+      type: "boolean",
+      description: `Generate Codex files (.codex/skills/${SKILL_NAME}/, AGENTS.md)`,
+    },
+  },
+  run: async (ctx) => {
+    const output = ctx.values.output ?? process.cwd();
+    const claude = ctx.values.claude ?? false;
+    const codex = ctx.values.codex ?? false;
+    const result = await runDocsCommand({ output, claude, codex });
+    for (const file of result.filesWritten) {
+      console.log(`Generated: ${file}`);
+    }
+    if (result.exitCode !== 0) {
+      process.exitCode = result.exitCode;
+    }
+  },
+});

package/src/gen-orchestrator/orchestrator.ts

@@ -262,6 +262,8 @@ function convertArgsToInputValues(
     externalEnumSymbol: arg.tsType.externalEnumSymbol ?? null,
     externalEnumDescription: arg.tsType.externalEnumDescription ?? null,
     externalEnumDeprecated: arg.tsType.externalEnumDeprecated ?? null,
+    inlineUnionMembers:
+      arg.tsType.kind === "union" ? (arg.tsType.members ?? null) : null,
   }));
 }
 
@@ -277,19 +279,30 @@ function convertDefineApiToFields(
   const typeExtensionMap = new Map<string, GraphQLFieldDefinition[]>();
 
   for (const resolver of resolvers) {
+    const returnType = resolver.returnType;
     const fieldDef: GraphQLFieldDefinition = {
       name: resolver.fieldName,
-      type: convertTsTypeToGraphQLType(resolver.returnType),
+      type: convertTsTypeToGraphQLType(returnType),
       args: resolver.args ? convertArgsToInputValues(resolver.args) : null,
-      sourceLocation: {
-        file: resolver.sourceFile,
-        line: 1,
-        column: 1,
-      },
+      sourceLocation: resolver.sourceLocation,
       resolverExportName: resolver.fieldName,
       description: resolver.description,
       deprecated: resolver.deprecated,
       directives: resolver.directives,
+      returnTypeInlineObjectProperties:
+        returnType.inlineObjectProperties ?? null,
+      returnTypeInlineObjectDescription:
+        returnType.inlineObjectDescription ?? null,
+      returnTypeInlineObjectDeprecated:
+        returnType.inlineObjectDeprecated ?? null,
+      returnTypeInlineEnumMembers: returnType.inlineEnumMembers ?? null,
+      returnTypeInlineUnionMembers:
+        returnType.kind === "union" ? (returnType.members ?? null) : null,
+      returnTypeExternalEnumSymbol: returnType.externalEnumSymbol ?? null,
+      returnTypeExternalEnumDescription:
+        returnType.externalEnumDescription ?? null,
+      returnTypeExternalEnumDeprecated:
+        returnType.externalEnumDeprecated ?? null,
     };
 
     if (resolver.resolverType === "query") {
@@ -673,6 +686,7 @@ function generateSchemaStep(ctx: PipelineContext): {
         : null,
     enablePruning: null,
     sourceRoot: ctx.config.cwd,
+    knownTypeNames: ctx.knownTypeNames,
   });
 
   const newDiagnostics = [...ctx.diagnostics, ...schemaResult.diagnostics];

package/src/resolver-extractor/extract-resolvers.ts

@@ -10,6 +10,7 @@ import type {
   InlineEnumMemberInfo,
   InlineObjectPropertyDef,
   SourceLocation,
+  TSTypeReference,
 } from "../type-extractor/types/index.js";
 import type { AbstractResolverInfo } from "./extractor/define-api-extractor.js";
 
@@ -28,6 +29,8 @@ export interface GraphQLInputValue {
   readonly externalEnumDescription: string | null;
   /** @deprecated tag from the external enum type itself (null for string literal unions) */
   readonly externalEnumDeprecated: DeprecationInfo | null;
+  /** Inline union members when arg type is a union type (for @oneOf input objects) */
+  readonly inlineUnionMembers: ReadonlyArray<TSTypeReference> | null;
 }
 
 export interface GraphQLFieldDefinition {
@@ -39,6 +42,22 @@ export interface GraphQLFieldDefinition {
   readonly description: string | null;
   readonly deprecated: DeprecationInfo | null;
   readonly directives: ReadonlyArray<DirectiveInfo> | null;
+  /** Inline object properties when return type is an inline object type */
+  readonly returnTypeInlineObjectProperties: ReadonlyArray<InlineObjectPropertyDef> | null;
+  /** TSDoc description from the inline object type alias (Requirement 7.2) */
+  readonly returnTypeInlineObjectDescription: string | null;
+  /** @deprecated tag from the inline object type alias (Requirement 7.3) */
+  readonly returnTypeInlineObjectDeprecated: DeprecationInfo | null;
+  /** Inline enum members when return type is an inline enum (string literal union or external TypeScript enum) */
+  readonly returnTypeInlineEnumMembers: ReadonlyArray<InlineEnumMemberInfo> | null;
+  /** Inline union members when return type is a union type (for Payload union types) */
+  readonly returnTypeInlineUnionMembers: ReadonlyArray<TSTypeReference> | null;
+  /** External TypeScript enum symbol for deduplication across multiple references */
+  readonly returnTypeExternalEnumSymbol: ts.Symbol | null;
+  /** TSDoc description from the external enum type itself (null for string literal unions) */
+  readonly returnTypeExternalEnumDescription: string | null;
+  /** @deprecated tag from the external enum type itself (null for string literal unions) */
+  readonly returnTypeExternalEnumDeprecated: DeprecationInfo | null;
 }
 
 export interface QueryFieldDefinitions {