@gqlkit-ts/cli 0.1.0 → 0.3.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/ignore-fields-detector.ts

@@ -0,0 +1,109 @@
+/**
+ * IgnoreFields metadata detector.
+ *
+ * This module provides functions to detect ignoreFields metadata embedded
+ * in TypeScript intersection types using the $gqlkitTypeMeta property.
+ */
+
+import ts from "typescript";
+import { METADATA_PROPERTIES } from "./constants.js";
+import { getActualMetadataType } from "./metadata-detector.js";
+
+const TYPE_META_PROPERTY = METADATA_PROPERTIES.TYPE_META;
+
+/**
+ * Parameters for detectIgnoreFieldsMetadata function.
+ */
+export interface DetectIgnoreFieldsParams {
+  readonly type: ts.Type;
+  readonly checker: ts.TypeChecker;
+}
+
+/**
+ * Extracts ignoreFields from a type's metadata.
+ * Returns null if the type doesn't have $gqlkitTypeMeta or ignoreFields is not specified.
+ */
+function extractIgnoreFieldsFromType(
+  type: ts.Type,
+  checker: ts.TypeChecker,
+): ReadonlySet<string> | null {
+  const metaProp = type.getProperty(TYPE_META_PROPERTY);
+  if (!metaProp) {
+    return null;
+  }
+
+  const rawMetadataType = checker.getTypeOfSymbol(metaProp);
+  const metadataType = getActualMetadataType(rawMetadataType);
+  if (!metadataType) {
+    return null;
+  }
+
+  const ignoreFieldsProp = metadataType.getProperty("ignoreFields");
+  if (!ignoreFieldsProp) {
+    return null;
+  }
+
+  const rawIgnoreFieldsType = checker.getTypeOfSymbol(ignoreFieldsProp);
+  const ignoreFieldsType = getActualMetadataType(rawIgnoreFieldsType);
+  if (!ignoreFieldsType) {
+    return null;
+  }
+
+  return extractStringLiteralUnion(ignoreFieldsType);
+}
+
+/**
+ * Extracts string literals from a type (single literal or union of literals).
+ */
+function extractStringLiteralUnion(type: ts.Type): ReadonlySet<string> | null {
+  if (type.flags & ts.TypeFlags.StringLiteral) {
+    const value = (type as ts.StringLiteralType).value;
+    return new Set([value]);
+  }
+
+  if (type.isUnion()) {
+    const values = new Set<string>();
+    for (const member of type.types) {
+      if (member.flags & ts.TypeFlags.StringLiteral) {
+        values.add((member as ts.StringLiteralType).value);
+      }
+    }
+    if (values.size > 0) {
+      return values;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Detects ignoreFields metadata from a TypeScript type.
+ *
+ * This function analyzes TypeScript types to detect ignoreFields metadata
+ * from the $gqlkitTypeMeta property. It extracts string literal or string
+ * literal union types and returns them as a Set.
+ *
+ * @param params - The detection parameters containing type and checker
+ * @returns The ignoreFields set or null if not specified
+ */
+export function detectIgnoreFieldsMetadata(
+  params: DetectIgnoreFieldsParams,
+): ReadonlySet<string> | null {
+  const { type, checker } = params;
+
+  const result = extractIgnoreFieldsFromType(type, checker);
+  if (result) {
+    return result;
+  }
+
+  if (type.isIntersection()) {
+    for (const member of type.types) {
+      const memberResult = extractIgnoreFieldsFromType(member, checker);
+      if (memberResult) {
+        return memberResult;
+      }
+    }
+  }
+
+  return null;
+}

package/src/shared/ignore-fields-validator.ts

@@ -0,0 +1,66 @@
+/**
+ * IgnoreFields validator.
+ *
+ * This module provides validation functions for ignoreFields metadata,
+ * checking that specified field names exist in the type and that not
+ * all fields are excluded.
+ */
+
+import type {
+  Diagnostic,
+  SourceLocation,
+} from "../type-extractor/types/diagnostics.js";
+
+/**
+ * Parameters for validateIgnoreFields function.
+ */
+export interface ValidateIgnoreFieldsParams {
+  readonly typeName: string;
+  readonly ignoreFields: ReadonlySet<string>;
+  readonly allFieldNames: ReadonlySet<string>;
+  readonly sourceLocation: SourceLocation;
+}
+
+/**
+ * Validates ignoreFields metadata.
+ *
+ * This function checks:
+ * 1. All field names in ignoreFields exist in the type
+ * 2. Not all fields are excluded (at least one field must remain)
+ *
+ * @param params - The validation parameters
+ * @returns Array of diagnostics (empty if valid)
+ */
+export function validateIgnoreFields(
+  params: ValidateIgnoreFieldsParams,
+): ReadonlyArray<Diagnostic> {
+  const { typeName, ignoreFields, allFieldNames, sourceLocation } = params;
+  const diagnostics: Diagnostic[] = [];
+
+  for (const fieldName of ignoreFields) {
+    if (!allFieldNames.has(fieldName)) {
+      const availableFields = [...allFieldNames].sort().join(", ");
+      diagnostics.push({
+        code: "IGNORE_FIELD_NOT_FOUND",
+        message: `Type '${typeName}': ignoreFields contains unknown field '${fieldName}'. Available fields: ${availableFields}`,
+        severity: "error",
+        location: sourceLocation,
+      });
+    }
+  }
+
+  const remainingFieldCount = [...allFieldNames].filter(
+    (f) => !ignoreFields.has(f),
+  ).length;
+
+  if (remainingFieldCount === 0 && allFieldNames.size > 0) {
+    diagnostics.push({
+      code: "IGNORE_ALL_FIELDS",
+      message: `Type '${typeName}': ignoreFields excludes all fields. At least one field must remain.`,
+      severity: "error",
+      location: sourceLocation,
+    });
+  }
+
+  return diagnostics;
+}

package/src/shared/index.ts

@@ -0,0 +1,34 @@
+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 { DetectIgnoreFieldsParams } from "./ignore-fields-detector.js";
+export type { ValidateIgnoreFieldsParams } from "./ignore-fields-validator.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 [];
+}