@gqlkit-ts/cli 0.0.1 → 0.2.0

package/src/shared/file-scanner.ts

@@ -0,0 +1,170 @@
+import { readdir, stat } from "node:fs/promises";
+import { join, matchesGlob, relative, resolve } from "node:path";
+import type { Diagnostic } from "../type-extractor/types/index.js";
+import { toPosixPath } from "./path-utils.js";
+
+export interface ScanResult {
+  readonly files: ReadonlyArray<string>;
+  readonly errors: ReadonlyArray<Diagnostic>;
+}
+
+export interface ScanOptions {
+  /**
+   * Glob patterns to exclude files.
+   * Patterns are matched against file paths relative to the scan directory.
+   */
+  readonly excludeGlobs?: ReadonlyArray<string>;
+
+  /**
+   * File paths to exclude (for generated files).
+   * Each path is individually excluded from scanning.
+   */
+  readonly excludePaths?: ReadonlyArray<string>;
+
+  /**
+   * Simple suffix patterns to exclude (existing behavior).
+   * @deprecated Use excludeGlobs instead
+   */
+  readonly excludePatterns?: ReadonlyArray<string>;
+}
+
+const TS_SOURCE_EXTENSIONS = [".ts", ".cts", ".mts"];
+const TS_DEFINITION_SUFFIXES = [".d.ts", ".d.cts", ".d.mts"];
+
+export function isTypeScriptSourceFile(fileName: string): boolean {
+  if (TS_DEFINITION_SUFFIXES.some((suffix) => fileName.endsWith(suffix))) {
+    return false;
+  }
+  return TS_SOURCE_EXTENSIONS.some((ext) => fileName.endsWith(ext));
+}
+
+function matchesSuffixPattern(fileName: string, pattern: string): boolean {
+  return fileName.endsWith(pattern);
+}
+
+function shouldExcludeBySuffix(
+  fileName: string,
+  excludePatterns: ReadonlyArray<string>,
+): boolean {
+  return excludePatterns.some((pattern) =>
+    matchesSuffixPattern(fileName, pattern),
+  );
+}
+
+function shouldExcludeByGlobs(
+  filePath: string,
+  rootDir: string,
+  excludeGlobs: ReadonlyArray<string>,
+): boolean {
+  if (excludeGlobs.length === 0) {
+    return false;
+  }
+
+  const relativePath = toPosixPath(relative(rootDir, filePath));
+  return excludeGlobs.some((pattern) => matchesGlob(relativePath, pattern));
+}
+
+function shouldExcludeByPaths(
+  filePath: string,
+  excludePaths: ReadonlyArray<string>,
+): boolean {
+  const normalizedFilePath = toPosixPath(filePath);
+  return excludePaths.some(
+    (excludePath) => normalizedFilePath === toPosixPath(excludePath),
+  );
+}
+
+interface CollectFilesContext {
+  readonly rootDir: string;
+  readonly excludePatterns: ReadonlyArray<string>;
+  readonly excludeGlobs: ReadonlyArray<string>;
+  readonly excludePaths: ReadonlyArray<string>;
+}
+
+async function collectFiles(
+  directory: string,
+  files: string[],
+  context: CollectFilesContext,
+): Promise<void> {
+  const entries = await readdir(directory, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = join(directory, entry.name);
+
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules") {
+        continue;
+      }
+      await collectFiles(fullPath, files, context);
+    } else if (entry.isFile()) {
+      if (!isTypeScriptSourceFile(entry.name)) {
+        continue;
+      }
+      if (shouldExcludeBySuffix(entry.name, context.excludePatterns)) {
+        continue;
+      }
+      if (
+        shouldExcludeByGlobs(fullPath, context.rootDir, context.excludeGlobs)
+      ) {
+        continue;
+      }
+      if (shouldExcludeByPaths(fullPath, context.excludePaths)) {
+        continue;
+      }
+      files.push(toPosixPath(fullPath));
+    }
+  }
+}
+
+export async function scanDirectory(
+  directory: string,
+  options: ScanOptions = {},
+): Promise<ScanResult> {
+  const absolutePath = resolve(directory);
+
+  try {
+    const stats = await stat(absolutePath);
+    if (!stats.isDirectory()) {
+      return {
+        files: [],
+        errors: [
+          {
+            code: "DIRECTORY_NOT_FOUND",
+            message: `Path is not a directory: ${absolutePath}`,
+            severity: "error",
+            location: null,
+          },
+        ],
+      };
+    }
+  } catch {
+    return {
+      files: [],
+      errors: [
+        {
+          code: "DIRECTORY_NOT_FOUND",
+          message: `Directory not found: ${absolutePath}`,
+          severity: "error",
+          location: null,
+        },
+      ],
+    };
+  }
+
+  const context: CollectFilesContext = {
+    rootDir: absolutePath,
+    excludePatterns: options.excludePatterns ?? [],
+    excludeGlobs: options.excludeGlobs ?? [],
+    excludePaths: options.excludePaths ?? [],
+  };
+
+  const files: string[] = [];
+  await collectFiles(absolutePath, files, context);
+
+  files.sort();
+
+  return {
+    files,
+    errors: [],
+  };
+}

package/src/shared/index.ts

@@ -0,0 +1,32 @@
+export type {
+  DefaultValueDetectionError,
+  DefaultValueDetectionErrorCode,
+  DefaultValueDetectionResult,
+} from "./default-value-detector.js";
+export { collectDiagnostics, deduplicateDiagnostics } from "./diagnostics.js";
+export {
+  type DirectiveArgumentDefinition,
+  type DirectiveDefinitionError,
+  type DirectiveDefinitionErrorCode,
+  type DirectiveDefinitionExtractionResult,
+  type DirectiveDefinitionInfo,
+  type DirectiveLocation,
+  extractDirectiveDefinitions,
+} from "./directive-definition-extractor.js";
+export type {
+  DirectiveArgument,
+  DirectiveArgumentValue,
+  DirectiveDetectionError,
+  DirectiveDetectionErrorCode,
+  DirectiveDetectionResult,
+  DirectiveInfo,
+} from "./directive-detector.js";
+export {
+  type ScanOptions,
+  type ScanResult,
+  scanDirectory,
+} from "./file-scanner.js";
+export type { TypeConverter } from "./inline-object-extractor.js";
+export { toPosixPath } from "./path-utils.js";
+export type { SourceLocation } from "./source-location.js";
+export { convertTsTypeToGraphQLType } from "./type-converter.js";

package/src/shared/inline-object-extractor.ts

@@ -0,0 +1,102 @@
+import type ts from "typescript";
+import type {
+  InlineObjectPropertyDef,
+  TSTypeReference,
+} from "../type-extractor/types/index.js";
+import { detectDefaultValueMetadata } from "./default-value-detector.js";
+import {
+  type DirectiveArgumentValue,
+  type DirectiveInfo,
+  detectDirectiveMetadata,
+  hasDirectiveMetadata,
+  unwrapDirectiveType,
+} from "./directive-detector.js";
+import { getSourceLocationFromNode } from "./source-location.js";
+import { extractTsDocFromSymbol } from "./tsdoc-parser.js";
+import {
+  extractPropertySymbols,
+  hasUndefinedInType,
+  isNullableUnion,
+} from "./typescript-utils.js";
+
+export type TypeConverter = (
+  type: ts.Type,
+  checker: ts.TypeChecker,
+) => TSTypeReference;
+
+/**
+ * Extracts inline object properties from a TypeScript type.
+ *
+ * @param type - The TypeScript type to extract properties from
+ * @param checker - The TypeScript type checker
+ * @param convertType - A function to convert TypeScript types to TSTypeReference
+ * @returns An array of inline object property definitions
+ */
+export function extractInlineObjectProperties(
+  type: ts.Type,
+  checker: ts.TypeChecker,
+  convertType: TypeConverter,
+): InlineObjectPropertyDef[] {
+  const properties: InlineObjectPropertyDef[] = [];
+  const typeProperties = extractPropertySymbols(type, checker);
+
+  for (const prop of typeProperties) {
+    const propName = prop.getName();
+    if (propName.startsWith(" $")) {
+      continue;
+    }
+
+    const propType = checker.getTypeOfSymbol(prop);
+    const declarations = prop.getDeclarations();
+    const declaration = declarations?.[0];
+
+    const optional = hasUndefinedInType(propType);
+
+    const tsdocInfo = extractTsDocFromSymbol(prop, checker);
+
+    let actualPropType = propType;
+    let directives: ReadonlyArray<DirectiveInfo> | null = null;
+    let directiveNullable = false;
+    let defaultValue: DirectiveArgumentValue | null = null;
+
+    if (hasDirectiveMetadata(propType)) {
+      const directiveResult = detectDirectiveMetadata(propType, checker);
+      if (directiveResult.directives.length > 0) {
+        directives = directiveResult.directives;
+      }
+
+      const defaultValueResult = detectDefaultValueMetadata(propType, checker);
+      if (defaultValueResult.defaultValue) {
+        defaultValue = defaultValueResult.defaultValue;
+      }
+
+      if (isNullableUnion(propType)) {
+        directiveNullable = true;
+      }
+      actualPropType = unwrapDirectiveType(propType, checker);
+
+      if (!directiveNullable && isNullableUnion(actualPropType)) {
+        directiveNullable = true;
+      }
+    }
+
+    const tsType = convertType(actualPropType, checker);
+    const finalTsType =
+      directiveNullable && !tsType.nullable
+        ? { ...tsType, nullable: true }
+        : tsType;
+
+    properties.push({
+      name: propName,
+      tsType: finalTsType,
+      optional,
+      description: tsdocInfo.description ?? null,
+      deprecated: tsdocInfo.deprecated ?? null,
+      directives,
+      defaultValue,
+      sourceLocation: getSourceLocationFromNode(declaration),
+    });
+  }
+
+  return properties;
+}

package/src/shared/inline-object-utils.ts

@@ -0,0 +1,23 @@
+import ts from "typescript";
+
+/**
+ * Checks if a TypeScript type is an inline object type (anonymous type literal).
+ * Returns true for types like `{ foo: string; bar: number }` but not for named types.
+ */
+export function isInlineObjectType(type: ts.Type): boolean {
+  if (type.aliasSymbol) {
+    return false;
+  }
+  if (!type.symbol) {
+    return false;
+  }
+  const symbolName = type.symbol.getName();
+  if (symbolName !== "__type") {
+    return false;
+  }
+  if (!(type.flags & ts.TypeFlags.Object)) {
+    return false;
+  }
+  const objectType = type as ts.ObjectType;
+  return (objectType.objectFlags & ts.ObjectFlags.Anonymous) !== 0;
+}

package/src/shared/interface-detector.ts

@@ -0,0 +1,176 @@
+/**
+ * Interface metadata detector.
+ *
+ * This module provides functions to detect interface metadata embedded
+ * in TypeScript intersection types using the $gqlkitInterfaceMeta property,
+ * and to extract implements declarations from types using $gqlkitTypeMeta.
+ */
+
+import ts from "typescript";
+import { METADATA_PROPERTIES } from "./constants.js";
+
+const INTERFACE_META_PROPERTY = METADATA_PROPERTIES.INTERFACE_META;
+const TYPE_META_PROPERTY = METADATA_PROPERTIES.TYPE_META;
+
+/**
+ * Checks if a type alias declaration uses GqlInterface.
+ * Detects by checking for the $gqlkitInterfaceMeta property in the resolved type.
+ */
+export function isDefineInterfaceTypeAlias(
+  node: ts.TypeAliasDeclaration,
+  checker: ts.TypeChecker,
+): boolean {
+  const symbol = checker.getSymbolAtLocation(node.name);
+  if (!symbol) {
+    return false;
+  }
+
+  const type = checker.getDeclaredTypeOfSymbol(symbol);
+  return hasInterfaceMetadata(type);
+}
+
+/**
+ * Checks if a type has the $gqlkitInterfaceMeta property.
+ */
+function hasInterfaceMetadata(type: ts.Type): boolean {
+  const metaProp = type.getProperty(INTERFACE_META_PROPERTY);
+  if (metaProp) {
+    return true;
+  }
+
+  if (type.isIntersection()) {
+    for (const member of type.types) {
+      const prop = member.getProperty(INTERFACE_META_PROPERTY);
+      if (prop) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Checks if a type has the $gqlkitTypeMeta property (GqlObject).
+ */
+function hasTypeMetadata(type: ts.Type): boolean {
+  const metaProp = type.getProperty(TYPE_META_PROPERTY);
+  if (metaProp) {
+    return true;
+  }
+
+  if (type.isIntersection()) {
+    for (const member of type.types) {
+      const prop = member.getProperty(TYPE_META_PROPERTY);
+      if (prop) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Extracts implements from GqlInterface type alias.
+ */
+export function extractImplementsFromDefineInterface(
+  node: ts.TypeAliasDeclaration,
+  sourceFile: ts.SourceFile,
+  checker: ts.TypeChecker,
+): ReadonlyArray<string> {
+  const typeNode = node.type;
+  if (!ts.isTypeReferenceNode(typeNode)) {
+    return [];
+  }
+
+  const typeArgs = typeNode.typeArguments;
+  if (!typeArgs || typeArgs.length < 2) {
+    return [];
+  }
+
+  const metaArg = typeArgs[1];
+  if (!metaArg || !ts.isTypeLiteralNode(metaArg)) {
+    return [];
+  }
+
+  return extractImplementsFromTypeLiteral(metaArg, sourceFile, checker);
+}
+
+/**
+ * Extracts implements from GqlObject type alias.
+ * Detects GqlObject by checking for the $gqlkitTypeMeta property in the resolved type.
+ */
+export function extractImplementsFromGqlTypeDef(
+  node: ts.TypeAliasDeclaration,
+  sourceFile: ts.SourceFile,
+  checker: ts.TypeChecker,
+): ReadonlyArray<string> {
+  const symbol = checker.getSymbolAtLocation(node.name);
+  if (!symbol) {
+    return [];
+  }
+
+  const type = checker.getDeclaredTypeOfSymbol(symbol);
+  if (!hasTypeMetadata(type)) {
+    return [];
+  }
+
+  const typeNode = node.type;
+  if (!ts.isTypeReferenceNode(typeNode)) {
+    return [];
+  }
+
+  const typeArgs = typeNode.typeArguments;
+  if (!typeArgs || typeArgs.length < 2) {
+    return [];
+  }
+
+  const metaArg = typeArgs[1];
+  if (!metaArg || !ts.isTypeLiteralNode(metaArg)) {
+    return [];
+  }
+
+  return extractImplementsFromTypeLiteral(metaArg, sourceFile, checker);
+}
+
+function extractImplementsFromTypeLiteral(
+  typeLiteral: ts.TypeLiteralNode,
+  sourceFile: ts.SourceFile,
+  _checker: ts.TypeChecker,
+): ReadonlyArray<string> {
+  for (const member of typeLiteral.members) {
+    if (ts.isPropertySignature(member) && member.name) {
+      const propName = member.name.getText(sourceFile);
+      if (propName === "implements" && member.type) {
+        return extractInterfaceNamesFromTupleNode(member.type, sourceFile);
+      }
+    }
+  }
+  return [];
+}
+
+function extractInterfaceNamesFromTupleNode(
+  typeNode: ts.TypeNode,
+  sourceFile: ts.SourceFile,
+): ReadonlyArray<string> {
+  if (ts.isTupleTypeNode(typeNode)) {
+    return typeNode.elements
+      .map((elem) => {
+        if (ts.isTypeReferenceNode(elem)) {
+          return elem.typeName.getText(sourceFile);
+        }
+        return null;
+      })
+      .filter((name): name is string => name !== null);
+  }
+
+  if (
+    ts.isArrayTypeNode(typeNode) &&
+    ts.isTypeReferenceNode(typeNode.elementType)
+  ) {
+    return [typeNode.elementType.typeName.getText(sourceFile)];
+  }
+
+  return [];
+}

package/src/shared/interface-validator.ts

@@ -0,0 +1,211 @@
+import type { GraphQLTypeInfo } from "../type-extractor/types/graphql.js";
+import type { Diagnostic } from "../type-extractor/types/index.js";
+
+export interface InterfaceValidationResult {
+  readonly isValid: boolean;
+  readonly diagnostics: ReadonlyArray<Diagnostic>;
+}
+
+export function validateInterfaceImplementations(
+  types: ReadonlyArray<GraphQLTypeInfo>,
+): InterfaceValidationResult {
+  const diagnostics: Diagnostic[] = [];
+  const typeMap = new Map<string, GraphQLTypeInfo>();
+
+  for (const type of types) {
+    typeMap.set(type.name, type);
+  }
+
+  for (const type of types) {
+    if (
+      !type.implementedInterfaces ||
+      type.implementedInterfaces.length === 0
+    ) {
+      continue;
+    }
+
+    for (const interfaceName of type.implementedInterfaces) {
+      const interfaceType = typeMap.get(interfaceName);
+
+      if (!interfaceType) {
+        diagnostics.push({
+          code: "INTERFACE_NOT_FOUND",
+          message: `Type '${type.name}' implements unknown interface '${interfaceName}'`,
+          severity: "error",
+          location: {
+            file: type.sourceFile,
+            line: 1,
+            column: 1,
+          },
+        });
+        continue;
+      }
+
+      if (interfaceType.kind !== "Interface") {
+        diagnostics.push({
+          code: "INTERFACE_NOT_INTERFACE",
+          message: `Type '${type.name}' attempts to implement '${interfaceName}' which is not an interface`,
+          severity: "error",
+          location: {
+            file: type.sourceFile,
+            line: 1,
+            column: 1,
+          },
+        });
+        continue;
+      }
+
+      if (!interfaceType.fields) {
+        continue;
+      }
+
+      const typeFields = new Map(type.fields?.map((f) => [f.name, f]) ?? []);
+
+      for (const interfaceField of interfaceType.fields) {
+        const typeField = typeFields.get(interfaceField.name);
+
+        if (!typeField) {
+          diagnostics.push({
+            code: "INTERFACE_MISSING_FIELD",
+            message: `Type '${type.name}' implements interface '${interfaceName}' but is missing field '${interfaceField.name}'`,
+            severity: "error",
+            location: {
+              file: type.sourceFile,
+              line: 1,
+              column: 1,
+            },
+          });
+          continue;
+        }
+
+        if (!isTypeCompatible(typeField.type, interfaceField.type)) {
+          diagnostics.push({
+            code: "INTERFACE_FIELD_TYPE_MISMATCH",
+            message: `Type '${type.name}' field '${interfaceField.name}' has incompatible type with interface '${interfaceName}'`,
+            severity: "error",
+            location: {
+              file: type.sourceFile,
+              line: 1,
+              column: 1,
+            },
+          });
+        }
+      }
+    }
+  }
+
+  return {
+    isValid: diagnostics.length === 0,
+    diagnostics,
+  };
+}
+
+interface FieldType {
+  readonly typeName: string;
+  readonly nullable: boolean;
+  readonly list: boolean;
+  readonly listItemNullable?: boolean | null;
+}
+
+function isTypeCompatible(
+  implementingType: FieldType,
+  interfaceType: FieldType,
+): boolean {
+  if (implementingType.typeName !== interfaceType.typeName) {
+    return false;
+  }
+
+  if (implementingType.list !== interfaceType.list) {
+    return false;
+  }
+
+  if (implementingType.nullable && !interfaceType.nullable) {
+    return false;
+  }
+
+  if (implementingType.list) {
+    if (implementingType.listItemNullable && !interfaceType.listItemNullable) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export function detectCircularInterfaceReferences(
+  types: ReadonlyArray<GraphQLTypeInfo>,
+): InterfaceValidationResult {
+  const diagnostics: Diagnostic[] = [];
+  const typeMap = new Map<string, GraphQLTypeInfo>();
+  const reportedCycles = new Set<string>();
+
+  for (const type of types) {
+    if (type.kind === "Interface") {
+      typeMap.set(type.name, type);
+    }
+  }
+
+  for (const type of types) {
+    if (type.kind !== "Interface" || !type.implementedInterfaces) {
+      continue;
+    }
+
+    const cyclePath = findCircularReference(type.name, typeMap, new Set(), []);
+    if (cyclePath) {
+      const cycleStart = cyclePath.indexOf(cyclePath[cyclePath.length - 1]!);
+      const cycleMembers = cyclePath.slice(cycleStart, -1);
+      const cycleKey = [...cycleMembers].sort().join(",");
+      if (!reportedCycles.has(cycleKey)) {
+        reportedCycles.add(cycleKey);
+        diagnostics.push({
+          code: "INTERFACE_CIRCULAR_REFERENCE",
+          message: `Circular interface inheritance detected: ${cyclePath.join(" -> ")}`,
+          severity: "error",
+          location: {
+            file: type.sourceFile,
+            line: 1,
+            column: 1,
+          },
+        });
+      }
+    }
+  }
+
+  return {
+    isValid: diagnostics.length === 0,
+    diagnostics,
+  };
+}
+
+function findCircularReference(
+  typeName: string,
+  typeMap: Map<string, GraphQLTypeInfo>,
+  visited: Set<string>,
+  path: string[],
+): string[] | null {
+  if (visited.has(typeName)) {
+    return [...path, typeName];
+  }
+
+  visited.add(typeName);
+  path.push(typeName);
+
+  const type = typeMap.get(typeName);
+  if (!type || !type.implementedInterfaces) {
+    return null;
+  }
+
+  for (const interfaceName of type.implementedInterfaces) {
+    const result = findCircularReference(
+      interfaceName,
+      typeMap,
+      new Set(visited),
+      [...path],
+    );
+    if (result) {
+      return result;
+    }
+  }
+
+  return null;
+}