@gqlkit-ts/cli 0.2.0 → 0.4.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/config/types.ts

@@ -1,3 +1,11 @@
+/**
+ * File extension mode for generated import statements.
+ * - "js": Convert .ts to .js (default, compatible with ESM + Node16)
+ * - "none": No extension (for bundlers)
+ * - "ts": Keep .ts extension (for Deno)
+ */
+export type ImportExtension = "js" | "none" | "ts";
+
 /**
  * Output configuration for generated files.
  * All paths are relative to project root.
@@ -29,6 +37,13 @@ export interface OutputConfig {
    * @default "src/gqlkit/__generated__/schema.graphql"
    */
   readonly schemaPath?: string | null;
+
+  /**
+   * File extension to use in generated import statements.
+   * @see ImportExtension
+   * @default "js"
+   */
+  readonly importExtension?: ImportExtension;
 }
 
 /**

package/src/config-loader/loader.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { createJiti } from "jiti";
+import type { ImportExtension } from "../config/types.js";
 import type { Diagnostic } from "../type-extractor/types/index.js";
 import { validateConfig } from "./validator.js";
 
@@ -27,6 +28,8 @@ export interface ResolvedOutputConfig {
   readonly typeDefsPath: string | null;
   /** Schema SDL output path. Null suppresses output */
   readonly schemaPath: string | null;
+  /** File extension for imports. Default: "js" */
+  readonly importExtension: ImportExtension;
 }
 
 /**
@@ -64,6 +67,7 @@ const DEFAULT_OUTPUT_CONFIG: ResolvedOutputConfig = {
   resolversPath: DEFAULT_RESOLVERS_PATH,
   typeDefsPath: DEFAULT_TYPEDEFS_PATH,
   schemaPath: DEFAULT_SCHEMA_PATH,
+  importExtension: "js",
 };
 
 const DEFAULT_HOOKS_CONFIG: ResolvedHooksConfig = {

package/src/config-loader/validator.ts

@@ -1,3 +1,4 @@
+import type { ImportExtension } from "../config/types.js";
 import type { Diagnostic } from "../type-extractor/types/index.js";
 import {
   DEFAULT_RESOLVERS_PATH,
@@ -186,6 +187,31 @@ function validateTsconfigPath(
   return { resolved: value, diagnostics: [] };
 }
 
+function validateImportExtension(
+  value: unknown,
+  configPath: string,
+): { resolved: ImportExtension; diagnostics: Diagnostic[] } {
+  if (value === undefined) {
+    return { resolved: "js", diagnostics: [] };
+  }
+
+  if (value !== "js" && value !== "none" && value !== "ts") {
+    return {
+      resolved: "js",
+      diagnostics: [
+        {
+          code: "CONFIG_INVALID_IMPORT_EXTENSION",
+          message: 'output.importExtension must be "js", "none", or "ts"',
+          severity: "error",
+          location: { file: configPath, line: 1, column: 1 },
+        },
+      ],
+    };
+  }
+
+  return { resolved: value, diagnostics: [] };
+}
+
 function validateOutputConfig(
   output: unknown,
   configPath: string,
@@ -198,6 +224,7 @@ function validateOutputConfig(
         resolversPath: DEFAULT_RESOLVERS_PATH,
         typeDefsPath: DEFAULT_TYPEDEFS_PATH,
         schemaPath: DEFAULT_SCHEMA_PATH,
+        importExtension: "js",
       },
       diagnostics: [],
     };
@@ -228,10 +255,15 @@ function validateOutputConfig(
     "output.schemaPath",
     configPath,
   );
+  const importExtensionResult = validateImportExtension(
+    output["importExtension"],
+    configPath,
+  );
 
   diagnostics.push(...resolversPathResult.diagnostics);
   diagnostics.push(...typeDefsPathResult.diagnostics);
   diagnostics.push(...schemaPathResult.diagnostics);
+  diagnostics.push(...importExtensionResult.diagnostics);
 
   if (diagnostics.length > 0) {
     return { resolved: undefined, diagnostics };
@@ -242,6 +274,7 @@ function validateOutputConfig(
       resolversPath: resolversPathResult.resolved,
       typeDefsPath: typeDefsPathResult.resolved,
       schemaPath: schemaPathResult.resolved,
+      importExtension: importExtensionResult.resolved,
     },
     diagnostics: [],
   };