@gqlkit-ts/cli 0.1.0 → 0.3.0

package/src/shared/source-location.ts

@@ -0,0 +1,38 @@
+import type ts from "typescript";
+
+export interface SourceLocation {
+  readonly file: string;
+  readonly line: number;
+  readonly column: number;
+}
+
+/**
+ * Extracts source location from a TypeScript AST node.
+ */
+export function getSourceLocationFromNode(
+  node: ts.Node | undefined,
+): SourceLocation | null {
+  if (!node) return null;
+
+  const sourceFile = node.getSourceFile();
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(
+    node.getStart(sourceFile),
+  );
+
+  return {
+    file: sourceFile.fileName,
+    line: line + 1,
+    column: character + 1,
+  };
+}
+
+/**
+ * Returns the source location if present, otherwise creates a default location
+ * with the given source file and line/column 1.
+ */
+export function getSourceLocationOrDefault(
+  location: SourceLocation | null,
+  sourceFile: string,
+): SourceLocation {
+  return location ?? { file: sourceFile, line: 1, column: 1 };
+}

package/src/shared/tsconfig-loader.ts

@@ -0,0 +1,126 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import type { Diagnostic } from "../type-extractor/types/index.js";
+
+export interface LoadTsconfigOptions {
+  readonly cwd: string;
+  readonly tsconfigPath: string | null;
+}
+
+export interface LoadTsconfigResult {
+  readonly compilerOptions: ts.CompilerOptions | null;
+  readonly configFilePath: string | null;
+  readonly diagnostics: ReadonlyArray<Diagnostic>;
+}
+
+export function loadTsconfig(options: LoadTsconfigOptions): LoadTsconfigResult {
+  const { cwd, tsconfigPath } = options;
+
+  if (tsconfigPath !== null) {
+    return loadFromSpecifiedPath(cwd, tsconfigPath);
+  }
+
+  return autoDetectTsconfig(cwd);
+}
+
+function loadFromSpecifiedPath(
+  cwd: string,
+  tsconfigPath: string,
+): LoadTsconfigResult {
+  const absolutePath = path.isAbsolute(tsconfigPath)
+    ? tsconfigPath
+    : path.resolve(cwd, tsconfigPath);
+
+  if (!existsSync(absolutePath)) {
+    return {
+      compilerOptions: null,
+      configFilePath: null,
+      diagnostics: [
+        {
+          code: "TSCONFIG_NOT_FOUND",
+          message: `tsconfig.json not found at: ${absolutePath}`,
+          severity: "error",
+          location: null,
+        },
+      ],
+    };
+  }
+
+  return parseConfigFile(absolutePath);
+}
+
+function autoDetectTsconfig(cwd: string): LoadTsconfigResult {
+  const configPath = ts.findConfigFile(cwd, ts.sys.fileExists, "tsconfig.json");
+
+  if (!configPath) {
+    return {
+      compilerOptions: null,
+      configFilePath: null,
+      diagnostics: [],
+    };
+  }
+
+  return parseConfigFile(configPath);
+}
+
+function parseConfigFile(configFilePath: string): LoadTsconfigResult {
+  const diagnostics: Diagnostic[] = [];
+
+  const readResult = ts.readConfigFile(configFilePath, ts.sys.readFile);
+
+  if (readResult.error) {
+    diagnostics.push({
+      code: "TSCONFIG_PARSE_ERROR",
+      message: `Failed to parse tsconfig.json: ${ts.flattenDiagnosticMessageText(readResult.error.messageText, "\n")}`,
+      severity: "error",
+      location: {
+        file: configFilePath,
+        line: 1,
+        column: 1,
+      },
+    });
+    return {
+      compilerOptions: null,
+      configFilePath: null,
+      diagnostics,
+    };
+  }
+
+  const configDir = path.dirname(configFilePath);
+  const parseResult = ts.parseJsonConfigFileContent(
+    readResult.config,
+    ts.sys,
+    configDir,
+  );
+
+  const significantErrors = parseResult.errors.filter(
+    (error) => error.code !== 18003,
+  );
+
+  if (significantErrors.length > 0) {
+    for (const error of significantErrors) {
+      diagnostics.push({
+        code: "TSCONFIG_INVALID",
+        message: `Invalid compiler options: ${ts.flattenDiagnosticMessageText(error.messageText, "\n")}`,
+        severity: "error",
+        location: {
+          file: configFilePath,
+          line: 1,
+          column: 1,
+        },
+      });
+    }
+    return {
+      compilerOptions: null,
+      configFilePath,
+      diagnostics,
+    };
+  }
+
+  return {
+    compilerOptions: parseResult.options,
+    configFilePath,
+    diagnostics: [],
+  };
+}

package/src/shared/tsdoc-parser.ts

@@ -0,0 +1,155 @@
+import ts from "typescript";
+
+export interface DeprecationInfo {
+  readonly isDeprecated: true;
+  readonly reason: string | null;
+}
+
+export interface TSDocInfo {
+  readonly description: string | null;
+  readonly deprecated: DeprecationInfo | null;
+}
+
+function getSymbolFromNode(
+  node: ts.Node,
+  checker: ts.TypeChecker,
+): ts.Symbol | undefined {
+  if (ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node)) {
+    return checker.getSymbolAtLocation(node.name);
+  }
+  if (ts.isEnumDeclaration(node)) {
+    return checker.getSymbolAtLocation(node.name);
+  }
+  if (ts.isVariableStatement(node)) {
+    const declaration = node.declarationList.declarations[0];
+    if (declaration && ts.isIdentifier(declaration.name)) {
+      return checker.getSymbolAtLocation(declaration.name);
+    }
+  }
+  return undefined;
+}
+
+function getTagCommentText(
+  comment: string | ts.NodeArray<ts.JSDocComment> | undefined,
+): string | undefined {
+  if (typeof comment === "string") {
+    const trimmed = comment.replace(/\r\n/g, "\n").trim();
+    return trimmed === "" ? undefined : trimmed;
+  }
+  if (Array.isArray(comment)) {
+    const text = comment
+      .map((part) => part.text)
+      .join("")
+      .replace(/\r\n/g, "\n")
+      .trim();
+    return text === "" ? undefined : text;
+  }
+  return undefined;
+}
+
+function extractDescriptionTagContent(
+  declarations: ReadonlyArray<ts.Declaration> | undefined,
+): string | undefined {
+  if (!declarations) {
+    return undefined;
+  }
+
+  for (const declaration of declarations) {
+    const jsdocTags = ts.getJSDocTags(declaration);
+    for (const tag of jsdocTags) {
+      if (tag.tagName.text === "description") {
+        return getTagCommentText(tag.comment);
+      }
+    }
+  }
+
+  return undefined;
+}
+
+function extractDeprecatedFromDeclarations(
+  declarations: ReadonlyArray<ts.Declaration> | undefined,
+): DeprecationInfo | undefined {
+  if (!declarations) {
+    return undefined;
+  }
+
+  for (const declaration of declarations) {
+    const jsdocTags = ts.getJSDocTags(declaration);
+    for (const tag of jsdocTags) {
+      if (tag.tagName.text === "deprecated") {
+        const reason = getTagCommentText(tag.comment);
+        return {
+          isDeprecated: true,
+          reason: reason ?? null,
+        };
+      }
+    }
+  }
+
+  return undefined;
+}
+
+function normalizeLineEndings(text: string): string {
+  return text.replace(/\r\n/g, "\n");
+}
+
+function extractDescriptionFromSymbol(
+  symbol: ts.Symbol,
+  checker: ts.TypeChecker,
+): string | undefined {
+  const documentationComment = symbol.getDocumentationComment(checker);
+
+  if (documentationComment.length > 0) {
+    const description = normalizeLineEndings(
+      ts.displayPartsToString(documentationComment).trim(),
+    );
+    if (description !== "") {
+      return description;
+    }
+  }
+
+  const descriptionTagContent = extractDescriptionTagContent(
+    symbol.getDeclarations(),
+  );
+  if (descriptionTagContent) {
+    return normalizeLineEndings(descriptionTagContent);
+  }
+
+  return undefined;
+}
+
+export function extractTsDocInfo(
+  node: ts.Node,
+  checker: ts.TypeChecker,
+): TSDocInfo {
+  const symbol = getSymbolFromNode(node, checker);
+
+  if (!symbol) {
+    return { description: null, deprecated: null };
+  }
+
+  const description = extractDescriptionFromSymbol(symbol, checker);
+  const deprecated = extractDeprecatedFromDeclarations(
+    symbol.getDeclarations(),
+  );
+
+  return {
+    description: description ?? null,
+    deprecated: deprecated ?? null,
+  };
+}
+
+export function extractTsDocFromSymbol(
+  symbol: ts.Symbol,
+  checker: ts.TypeChecker,
+): TSDocInfo {
+  const description = extractDescriptionFromSymbol(symbol, checker);
+  const deprecated = extractDeprecatedFromDeclarations(
+    symbol.getDeclarations(),
+  );
+
+  return {
+    description: description ?? null,
+    deprecated: deprecated ?? null,
+  };
+}

package/src/shared/type-converter.ts

@@ -0,0 +1,99 @@
+import type {
+  GraphQLFieldType,
+  TSTypeReference,
+} from "../type-extractor/types/index.js";
+import { PRIMITIVE_TYPE_MAP } from "./constants.js";
+
+function convertElementTypeName(elementType: TSTypeReference): string {
+  if (elementType.kind === "scalar") {
+    return elementType.scalarInfo?.scalarName ?? elementType.name ?? "String";
+  }
+  if (elementType.kind === "primitive") {
+    return PRIMITIVE_TYPE_MAP[elementType.name ?? ""] ?? "String";
+  }
+  if (elementType.kind === "reference") {
+    return elementType.name ?? "Unknown";
+  }
+  if (elementType.kind === "inlineObject") {
+    return "__INLINE_OBJECT__";
+  }
+  if (elementType.kind === "inlineEnum") {
+    return "__INLINE_ENUM__";
+  }
+  return elementType.name ?? "String";
+}
+
+export function convertTsTypeToGraphQLType(
+  tsType: TSTypeReference,
+  optional = false,
+): GraphQLFieldType {
+  const nullable = tsType.nullable || optional;
+
+  if (tsType.kind === "array") {
+    const elementType = tsType.elementType;
+    const elementTypeName = elementType
+      ? convertElementTypeName(elementType)
+      : "String";
+    const listItemNullable = elementType?.nullable ?? false;
+
+    return {
+      typeName: elementTypeName,
+      nullable,
+      list: true,
+      listItemNullable,
+    };
+  }
+
+  if (tsType.kind === "scalar") {
+    return {
+      typeName: tsType.scalarInfo?.scalarName ?? tsType.name ?? "String",
+      nullable,
+      list: false,
+      listItemNullable: null,
+    };
+  }
+
+  if (tsType.kind === "primitive") {
+    const graphqlType = PRIMITIVE_TYPE_MAP[tsType.name ?? ""] ?? "String";
+    return {
+      typeName: graphqlType,
+      nullable,
+      list: false,
+      listItemNullable: null,
+    };
+  }
+
+  if (tsType.kind === "reference") {
+    return {
+      typeName: tsType.name ?? "Unknown",
+      nullable,
+      list: false,
+      listItemNullable: null,
+    };
+  }
+
+  if (tsType.kind === "inlineObject") {
+    return {
+      typeName: "__INLINE_OBJECT__",
+      nullable,
+      list: false,
+      listItemNullable: null,
+    };
+  }
+
+  if (tsType.kind === "inlineEnum") {
+    return {
+      typeName: "__INLINE_ENUM__",
+      nullable,
+      list: false,
+      listItemNullable: null,
+    };
+  }
+
+  return {
+    typeName: tsType.name ?? "String",
+    nullable,
+    list: false,
+    listItemNullable: null,
+  };
+}

package/src/shared/typescript-utils.ts

@@ -0,0 +1,246 @@
+import ts from "typescript";
+import { isInlineObjectType } from "./inline-object-utils.js";
+
+/**
+ * Extracts type name from a TypeNode.
+ * Handles both simple identifiers and qualified names.
+ */
+export function getTypeNameFromNode(typeNode: ts.TypeNode): string | null {
+  if (ts.isTypeReferenceNode(typeNode)) {
+    if (ts.isIdentifier(typeNode.typeName)) {
+      return typeNode.typeName.text;
+    }
+    if (ts.isQualifiedName(typeNode.typeName)) {
+      return typeNode.typeName.right.text;
+    }
+  }
+  return null;
+}
+
+/**
+ * Checks if a type represents null or undefined.
+ */
+export function isNullOrUndefined(type: ts.Type): boolean {
+  return (
+    (type.flags & ts.TypeFlags.Null) !== 0 ||
+    (type.flags & ts.TypeFlags.Undefined) !== 0
+  );
+}
+
+/**
+ * Checks if a TypeNode represents null (literal null type).
+ */
+function isNullTypeNode(typeNode: ts.TypeNode): boolean {
+  return (
+    ts.isLiteralTypeNode(typeNode) &&
+    typeNode.literal.kind === ts.SyntaxKind.NullKeyword
+  );
+}
+
+/**
+ * Filters non-null type nodes from a union type node.
+ */
+export function filterNonNullTypeNodes(
+  typeNode: ts.UnionTypeNode,
+): ts.TypeNode[] {
+  return typeNode.types.filter((t) => !isNullTypeNode(t));
+}
+
+/**
+ * Finds the first non-null type node from a union type node.
+ */
+export function findNonNullTypeNode(
+  typeNode: ts.UnionTypeNode,
+): ts.TypeNode | undefined {
+  return filterNonNullTypeNodes(typeNode)[0];
+}
+
+/**
+ * Checks if a union type contains null or undefined.
+ */
+export function isNullableUnion(type: ts.Type): boolean {
+  if (!type.isUnion()) return false;
+  return type.types.some((t) => isNullOrUndefined(t));
+}
+
+/**
+ * Gets non-nullable types from a union type.
+ */
+export function getNonNullableTypes(type: ts.Type): ts.Type[] {
+  if (!type.isUnion()) return [type];
+  return type.types.filter((t) => !isNullOrUndefined(t));
+}
+
+/**
+ * Checks if a type contains undefined.
+ * This is used to determine property optionality from resolved types,
+ * which correctly handles utility types like Required<T> and Partial<T>.
+ *
+ * In TypeScript:
+ * - Optional properties (?) add undefined to the type
+ * - Partial<T> adds undefined to all property types
+ * - Required<T> removes undefined from all property types
+ */
+export function hasUndefinedInType(type: ts.Type): boolean {
+  if ((type.flags & ts.TypeFlags.Undefined) !== 0) return true;
+  if (type.isUnion()) {
+    return type.types.some((t) => (t.flags & ts.TypeFlags.Undefined) !== 0);
+  }
+  return false;
+}
+
+/**
+ * Checks if a node has the export modifier.
+ */
+export function isExported(node: ts.Node): boolean {
+  const modifiers = ts.getCombinedModifierFlags(node as ts.Declaration);
+  return (modifiers & ts.ModifierFlags.Export) !== 0;
+}
+
+/**
+ * Checks if a type is an anonymous object type (like inline type literals).
+ * Named types and type aliases are not considered anonymous.
+ * This is used to determine if an intersection member should trigger
+ * treating the whole intersection as an inline object.
+ */
+export function isAnonymousObjectType(type: ts.Type): boolean {
+  if (type.aliasSymbol) {
+    return false;
+  }
+  if (!type.symbol) {
+    return true;
+  }
+  const symbolName = type.symbol.getName();
+  return symbolName === "__type" || symbolName === "";
+}
+
+/**
+ * Checks if a type is an object-like type (interface, anonymous object, or mapped type).
+ * Used to determine if an intersection of object types should be treated as inline.
+ */
+function isObjectLikeType(type: ts.Type): boolean {
+  if (!(type.flags & ts.TypeFlags.Object)) {
+    return false;
+  }
+  const objectType = type as ts.ObjectType;
+  return (
+    (objectType.objectFlags & ts.ObjectFlags.Interface) !== 0 ||
+    (objectType.objectFlags & ts.ObjectFlags.Anonymous) !== 0 ||
+    (objectType.objectFlags & ts.ObjectFlags.Mapped) !== 0
+  );
+}
+
+/**
+ * Extracts property symbols from a type, handling intersection types
+ * and falling back to getApparentType when getProperties() returns empty.
+ */
+export function extractPropertySymbols(
+  type: ts.Type,
+  checker: ts.TypeChecker,
+): ts.Symbol[] {
+  if (type.isIntersection()) {
+    const allProps = new Map<string, ts.Symbol>();
+    for (const member of type.types) {
+      const memberProps = member.getProperties();
+      for (const prop of memberProps) {
+        const propName = prop.getName();
+        if (!allProps.has(propName)) {
+          allProps.set(propName, prop);
+        }
+      }
+    }
+    return [...allProps.values()];
+  }
+
+  const properties = type.getProperties();
+  if (properties.length > 0) {
+    return [...properties];
+  }
+
+  const apparentType = checker.getApparentType(type);
+  if (apparentType !== type) {
+    return [...apparentType.getProperties()];
+  }
+
+  return [];
+}
+
+/**
+ * Determines if an intersection type should be treated as an inline object.
+ * Returns true when:
+ * - Case 1: Has at least one anonymous/inline member
+ * - Case 2: All members are object-like types that should be merged
+ */
+export function shouldTreatIntersectionAsInline(
+  type: ts.IntersectionType,
+): boolean {
+  const hasResolvableMember = type.types.some(
+    (t) => isInlineObjectType(t) || isAnonymousObjectType(t),
+  );
+  if (hasResolvableMember) {
+    return true;
+  }
+
+  const allObjectLike = type.types.every((t) => isObjectLikeType(t));
+  if (allObjectLike) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Internal TypeScript symbol with parent reference.
+ * Used to access the parent enum symbol from enum member types.
+ */
+export type SymbolWithParent = ts.Symbol & { parent?: ts.Symbol };
+
+/**
+ * Finds the parent enum symbol if all types belong to the same enum.
+ * Returns null if types are empty, don't have a common parent enum, or belong to different enums.
+ */
+export function findEnumParentSymbol(
+  types: readonly ts.Type[],
+): ts.Symbol | null {
+  if (types.length === 0) return null;
+
+  const firstSymbol = types[0]!.symbol as SymbolWithParent | undefined;
+  const parentSymbol = firstSymbol?.parent;
+
+  if (!parentSymbol || !(parentSymbol.flags & ts.SymbolFlags.Enum)) {
+    return null;
+  }
+
+  const allBelongToSameEnum = types.every((t) => {
+    const sym = t.symbol as SymbolWithParent | undefined;
+    return sym?.parent === parentSymbol;
+  });
+
+  return allBelongToSameEnum ? parentSymbol : null;
+}
+
+/**
+ * Checks if a union type is a boolean union (true | false with optional null/undefined).
+ */
+export function isBooleanUnion(type: ts.Type): boolean {
+  if (!type.isUnion()) return false;
+  const nonNullTypes = getNonNullableTypes(type);
+  return (
+    nonNullTypes.length === 2 &&
+    nonNullTypes.every((t) => t.flags & ts.TypeFlags.BooleanLiteral)
+  );
+}
+
+/**
+ * Resolves a symbol to its original symbol by following alias chains.
+ * This is necessary for re-exports where the symbol is an alias.
+ */
+export function resolveOriginalSymbol(
+  symbol: ts.Symbol,
+  checker: ts.TypeChecker,
+): ts.Symbol {
+  if (symbol.flags & ts.SymbolFlags.Alias) {
+    return checker.getAliasedSymbol(symbol);
+  }
+  return symbol;
+}