@gqlkit-ts/cli 0.3.0 → 0.4.1

package/docs/configuration.md

@@ -40,6 +40,8 @@ export default defineConfig({
     schemaPath: "src/gqlkit/__generated__/schema.graphql",
     // Set to null to disable output:
     // schemaPath: null,
+    // Import extension in generated files (default: "js")
+    // importExtension: "none", // for bundlers
   },
 
   // Hooks
@@ -89,9 +91,16 @@ export default defineConfig({
 | `typeDefsPath` | `string` \| `null` | `"src/gqlkit/__generated__/typeDefs.ts"` | Path for the TypeDefs output |
 | `resolversPath` | `string` \| `null` | `"src/gqlkit/__generated__/resolvers.ts"` | Path for the resolvers output |
 | `schemaPath` | `string` \| `null` | `"src/gqlkit/__generated__/schema.graphql"` | Path for the SDL output |
+| `importExtension` | `"js"` \| `"none"` \| `"ts"` | `"js"` | File extension for import statements |
 
 Set any path to `null` to disable that output.
 
+The `importExtension` option controls file extensions in generated import statements:
+
+- `"js"` (default): Converts `.ts` to `.js` (compatible with ESM + Node16)
+- `"none"`: No extension (for bundlers like webpack, vite)
+- `"ts"`: Keeps `.ts` extension (for Deno)
+
 ## Hooks
 
 Execute commands after file generation:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gqlkit-ts/cli",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Just types and functions — write TypeScript, generate GraphQL.",
   "type": "module",
   "main": "dist/index.js",
@@ -60,8 +60,8 @@
   "devDependencies": {
     "@types/shell-quote": "1.7.5",
     "memfs": "4.56.10",
-    "@gqlkit-ts/runtime": "0.2.0",
-    "@gqlkit-ts/docs": "0.0.1"
+    "@gqlkit-ts/docs": "0.0.1",
+    "@gqlkit-ts/runtime": "0.2.0"
   },
   "scripts": {
     "build": "tsc --build && bundle-docs --target ./docs",

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

@@ -12,12 +12,10 @@ import {
   stripEnumPrefix,
 } from "../shared/enum-prefix-detector.js";
 import { getSourceLocationOrDefault } from "../shared/source-location.js";
+import { toScreamingSnakeCase } from "../shared/string-utils.js";
 import type { DeprecationInfo } from "../shared/tsdoc-parser.js";
 import { convertTsTypeToGraphQLType } from "../shared/type-converter.js";
-import {
-  isEligibleAsInputObjectField,
-  isEligibleAsObjectField,
-} from "../type-extractor/converter/field-eligibility.js";
+import { isEligibleField } from "../type-extractor/converter/field-eligibility.js";
 import {
   createReferenceType,
   type Diagnostic,
@@ -259,27 +257,33 @@ function collectInlineObjectsFromType(
   const isInput = isInputTypeName(typeInfo.metadata.name);
 
   for (const field of typeInfo.fields) {
-    collectInlineObjectsFromField(
+    collectInlineObjectsFromField({
       field,
-      typeInfo.metadata.name,
-      [],
+      parentTypeName: typeInfo.metadata.name,
+      parentPath: [],
       isInput,
-      typeInfo.metadata.sourceFile,
+      sourceFile: typeInfo.metadata.sourceFile,
       results,
-    );
+    });
   }
 
   return results;
 }
 
+interface CollectInlineObjectsFromFieldParams {
+  readonly field: FieldDefinition;
+  readonly parentTypeName: string;
+  readonly parentPath: ReadonlyArray<string>;
+  readonly isInput: boolean;
+  readonly sourceFile: string;
+  readonly results: InlineObjectWithContext[];
+}
+
 function collectInlineObjectsFromField(
-  field: FieldDefinition,
-  parentTypeName: string,
-  parentPath: ReadonlyArray<string>,
-  isInput: boolean,
-  sourceFile: string,
-  results: InlineObjectWithContext[],
+  params: CollectInlineObjectsFromFieldParams,
 ): void {
+  const { field, parentTypeName, parentPath, isInput, sourceFile, results } =
+    params;
   const tsType = field.tsType;
 
   if (tsType.kind !== "inlineObject" || !tsType.inlineObjectProperties) {
@@ -481,9 +485,10 @@ function generateAutoType(
   const diagnostics: Diagnostic[] = [];
 
   for (const prop of inlineObj.properties) {
-    const eligibility = isInput
-      ? isEligibleAsInputObjectField(prop.name)
-      : isEligibleAsObjectField(prop.name);
+    const eligibility = isEligibleField({
+      fieldName: prop.name,
+      kind: isInput ? "input" : "object",
+    });
 
     if (!eligibility.eligible) {
       diagnostics.push({
@@ -853,14 +858,6 @@ function buildGeneratedTypeNamesMap(
   return map;
 }
 
-function toScreamingSnakeCase(value: string): string {
-  return value
-    .replace(/[-\s]+/g, "_")
-    .replace(/([a-z])([A-Z])/g, "$1_$2")
-    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
-    .toUpperCase();
-}
-
 interface ConvertInlineEnumMembersParams {
   readonly members: ReadonlyArray<InlineEnumMemberInfo>;
   readonly enumName: string;

package/src/commands/docs.ts

@@ -1,10 +1,7 @@
 import { access, mkdir, readFile, symlink, writeFile } from "node:fs/promises";
-import { dirname, join, relative } from "node:path";
-import { fileURLToPath } from "node:url";
+import { dirname, join, parse, relative, resolve } from "node:path";
 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 {
@@ -27,6 +24,27 @@ async function exists(path: string): Promise<boolean> {
   }
 }
 
+async function findNodeModulesDocsPath(
+  startDir: string,
+): Promise<string | null> {
+  let currentDir = resolve(startDir);
+  const root = parse(currentDir).root;
+
+  while (currentDir !== root) {
+    const candidate = join(currentDir, "node_modules/@gqlkit-ts/cli/docs");
+    if (await exists(candidate)) {
+      return candidate;
+    }
+    const parent = dirname(currentDir);
+    if (parent === currentDir) {
+      break;
+    }
+    currentDir = parent;
+  }
+
+  return null;
+}
+
 async function detectClaudeEnvironment(dir: string): Promise<boolean> {
   const claudeMdExists = await exists(join(dir, "CLAUDE.md"));
   const claudeDirExists = await exists(join(dir, ".claude"));
@@ -124,8 +142,16 @@ async function generateToolFiles(
   await writeFile(skillMdPath, generateSkillMd());
   filesWritten.push(skillMdPath);
 
+  const docsPath = await findNodeModulesDocsPath(skillDir);
+  if (docsPath === null) {
+    throw new Error(
+      `Could not find @gqlkit-ts/cli docs directory under node_modules (starting from ${resolve(skillDir)}). ` +
+        "Ensure @gqlkit-ts/cli is installed.",
+    );
+  }
+
   const referencesPath = join(skillDir, "references");
-  const relativePath = relative(skillDir, CLI_DOCS_DIR);
+  const relativePath = relative(skillDir, docsPath);
   await createSymlinkIfNotExists(referencesPath, relativePath);
   filesWritten.push(referencesPath);
 
@@ -137,13 +163,6 @@ async function generateToolFiles(
 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;
@@ -161,20 +180,27 @@ export async function runDocsCommand(
     return { exitCode: 0, filesWritten: [] };
   }
 
-  if (generateClaude) {
-    await generateToolFiles(
-      options.output,
-      { configDir: ".claude", rulesFile: "CLAUDE.md" },
-      filesWritten,
-    );
-  }
+  try {
+    if (generateClaude) {
+      await generateToolFiles(
+        options.output,
+        { configDir: ".claude", rulesFile: "CLAUDE.md" },
+        filesWritten,
+      );
+    }
 
-  if (generateCodex) {
-    await generateToolFiles(
-      options.output,
-      { configDir: ".codex", rulesFile: "AGENTS.md" },
-      filesWritten,
+    if (generateCodex) {
+      await generateToolFiles(
+        options.output,
+        { configDir: ".codex", rulesFile: "AGENTS.md" },
+        filesWritten,
+      );
+    }
+  } catch (error) {
+    console.error(
+      error instanceof Error ? (error.stack ?? error.message) : String(error),
     );
+    return { exitCode: 1, filesWritten: [] };
   }
 
   return { exitCode: 0, filesWritten };

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: [],
   };

package/src/gen-orchestrator/orchestrator.ts

@@ -91,6 +91,12 @@ interface ResolversResult {
   diagnostics: Diagnostics;
 }
 
+interface ScalarConfig {
+  readonly customScalarNames: string[];
+  readonly globalTypeMappings: GlobalTypeMapping[];
+  readonly configScalars: ConfigScalarMapping[];
+}
+
 interface PipelineContext {
   readonly config: GenerationConfig;
   readonly sourceFiles: ReadonlyArray<string>;
@@ -101,6 +107,7 @@ interface PipelineContext {
   readonly typesResult: TypesResult | null;
   readonly resolversResult: ResolversResult | null;
   readonly directiveDefinitions: DirectiveDefinitionInfo[] | null;
+  readonly scalarConfig: ScalarConfig | null;
   readonly diagnostics: Diagnostic[];
   readonly aborted: boolean;
 }
@@ -449,6 +456,7 @@ function createInitialContext(config: GenerationConfig): PipelineContext {
     typesResult: null,
     resolversResult: null,
     directiveDefinitions: null,
+    scalarConfig: null,
     diagnostics: [],
     aborted: false,
   };
@@ -514,11 +522,7 @@ function collectTypeNamesStep(ctx: PipelineContext): PipelineContext {
   };
 }
 
-function prepareScalarConfig(config: GenerationConfig): {
-  customScalarNames: string[];
-  globalTypeMappings: GlobalTypeMapping[];
-  configScalars: ConfigScalarMapping[];
-} {
+function prepareScalarConfig(config: GenerationConfig): ScalarConfig {
   const customScalarNames =
     config.customScalars?.map((s) => s.graphqlName) ?? [];
 
@@ -556,18 +560,25 @@ function prepareScalarConfig(config: GenerationConfig): {
   return { customScalarNames, globalTypeMappings, configScalars };
 }
 
+function prepareScalarConfigStep(ctx: PipelineContext): PipelineContext {
+  if (ctx.aborted) return ctx;
+
+  return { ...ctx, scalarConfig: prepareScalarConfig(ctx.config) };
+}
+
 function extractTypesStep(ctx: PipelineContext): PipelineContext {
   if (
     ctx.aborted ||
     !ctx.program ||
     !ctx.knownTypeNames ||
     !ctx.knownTypeSymbols ||
-    !ctx.underlyingSymbolToTypeName
+    !ctx.underlyingSymbolToTypeName ||
+    !ctx.scalarConfig
   )
     return ctx;
 
   const { customScalarNames, globalTypeMappings, configScalars } =
-    prepareScalarConfig(ctx.config);
+    ctx.scalarConfig;
 
   const typesResult = extractTypesCore({
     program: ctx.program,
@@ -591,11 +602,12 @@ function extractResolversStep(ctx: PipelineContext): PipelineContext {
     !ctx.knownTypeNames ||
     !ctx.knownTypeSymbols ||
     !ctx.underlyingSymbolToTypeName ||
-    !ctx.typesResult
+    !ctx.typesResult ||
+    !ctx.scalarConfig
   )
     return ctx;
 
-  const { globalTypeMappings } = prepareScalarConfig(ctx.config);
+  const { globalTypeMappings } = ctx.scalarConfig;
 
   const resolversResult = extractResolversCore({
     program: ctx.program,
@@ -663,11 +675,16 @@ function generateSchemaStep(ctx: PipelineContext): {
   ctx: PipelineContext;
   schemaResult: ReturnType<typeof generateSchema> | null;
 } {
-  if (ctx.aborted || !ctx.typesResult || !ctx.resolversResult) {
+  if (
+    ctx.aborted ||
+    !ctx.typesResult ||
+    !ctx.resolversResult ||
+    !ctx.scalarConfig
+  ) {
     return { ctx, schemaResult: null };
   }
 
-  const { customScalarNames } = prepareScalarConfig(ctx.config);
+  const { customScalarNames } = ctx.scalarConfig;
   const allCustomScalarNames = [
     ...customScalarNames,
     ...ctx.typesResult.detectedScalarNames,
@@ -687,6 +704,7 @@ function generateSchemaStep(ctx: PipelineContext): {
     enablePruning: null,
     sourceRoot: ctx.config.cwd,
     knownTypeNames: ctx.knownTypeNames,
+    importExtension: ctx.config.output.importExtension,
   });
 
   const newDiagnostics = [...ctx.diagnostics, ...schemaResult.diagnostics];
@@ -739,6 +757,7 @@ export async function executeGeneration(
   ctx = await scanSourceFilesStep(ctx);
   ctx = createProgramStep(ctx);
   ctx = collectTypeNamesStep(ctx);
+  ctx = prepareScalarConfigStep(ctx);
   ctx = extractTypesStep(ctx);
   ctx = extractResolversStep(ctx);
   ctx = extractDirectivesStep(ctx);

package/src/resolver-extractor/extractor/define-api-extractor.ts

@@ -200,23 +200,23 @@ function extractTypeNameFromType(
 function detectResolverFromMetadataType(
   callExpr: ts.CallExpression,
   checker: ts.TypeChecker,
-): DefineApiResolverType | undefined {
+): DefineApiResolverType | null {
   const returnType = checker.getTypeAtLocation(callExpr);
 
   const metadataProp = returnType.getProperty(RESOLVER_METADATA_PROPERTY);
   if (!metadataProp) {
-    return undefined;
+    return null;
   }
 
   const metadataType = checker.getTypeOfSymbol(metadataProp);
   const actualType = getActualMetadataType(metadataType);
   if (!actualType) {
-    return undefined;
+    return null;
   }
 
   const kindProp = actualType.getProperty("kind");
   if (!kindProp) {
-    return undefined;
+    return null;
   }
 
   const kindType = checker.getTypeOfSymbol(kindProp);
@@ -227,7 +227,7 @@ function detectResolverFromMetadataType(
     }
   }
 
-  return undefined;
+  return null;
 }
 
 function isInlineTypeLiteralDeclaration(declaration: ts.Declaration): boolean {