@gqlkit-ts/cli 0.1.0 → 0.3.0

package/src/type-extractor/collector/result-collector.ts

@@ -0,0 +1,57 @@
+import { deduplicateDiagnostics } from "../../shared/index.js";
+import type {
+  Diagnostic,
+  Diagnostics,
+  FieldInfo,
+  GraphQLTypeInfo,
+} from "../types/index.js";
+
+export interface ExtractTypesResult {
+  readonly types: ReadonlyArray<GraphQLTypeInfo>;
+  readonly diagnostics: Diagnostics;
+}
+
+function sortFields(fields: ReadonlyArray<FieldInfo>): FieldInfo[] {
+  return [...fields].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function sortUnionMembers(members: ReadonlyArray<string>): string[] {
+  return [...members].sort((a, b) => a.localeCompare(b));
+}
+
+function sortType(type: GraphQLTypeInfo): GraphQLTypeInfo {
+  if (type.kind === "Object" && type.fields) {
+    return {
+      ...type,
+      fields: sortFields(type.fields),
+    };
+  }
+
+  if (type.kind === "Union" && type.unionMembers) {
+    return {
+      ...type,
+      unionMembers: sortUnionMembers(type.unionMembers),
+    };
+  }
+
+  return type;
+}
+
+export function collectResults(
+  types: ReadonlyArray<GraphQLTypeInfo>,
+  diagnostics: ReadonlyArray<Diagnostic>,
+): ExtractTypesResult {
+  const sortedTypes = [...types]
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map(sortType);
+
+  const uniqueDiagnostics = deduplicateDiagnostics(diagnostics);
+
+  const errors = uniqueDiagnostics.filter((d) => d.severity === "error");
+  const warnings = uniqueDiagnostics.filter((d) => d.severity === "warning");
+
+  return {
+    types: sortedTypes,
+    diagnostics: { errors, warnings },
+  };
+}

package/src/type-extractor/collector/scalar-collector.ts

@@ -0,0 +1,254 @@
+/**
+ * ScalarCollector collects scalar definitions from types and config,
+ * validates input/output type constraints, and builds type parameters.
+ */
+import { isBuiltInScalar } from "../../shared/constants.js";
+
+/**
+ * Information about a detected scalar type from metadata detection.
+ */
+export interface ScalarMetadataInfo {
+  /** The GraphQL scalar name */
+  readonly scalarName: string;
+  /** The TypeScript type name */
+  readonly typeName: string;
+  /** Usage constraint: "input", "output", or null for both */
+  readonly only: "input" | "output" | null;
+  /** Source file path */
+  readonly sourceFile: string;
+  /** Line number in source file */
+  readonly line: number;
+  /** TSDoc description if available */
+  readonly description: string | null;
+}
+
+/**
+ * Configuration scalar mapping information.
+ */
+export interface ConfigScalarMapping extends ScalarMetadataInfo {
+  /** Whether this mapping comes from config file */
+  readonly fromConfig: boolean;
+}
+
+/**
+ * Reference to a scalar type.
+ */
+export interface ScalarTypeRef {
+  /** TypeScript type name */
+  readonly typeName: string;
+  /** Source file path */
+  readonly sourceFile: string;
+  /** Line number in source file */
+  readonly line: number;
+}
+
+/**
+ * Description source information.
+ */
+export interface DescriptionSource {
+  /** Description text */
+  readonly text: string;
+  /** Source file path */
+  readonly sourceFile: string;
+  /** Line number in source file */
+  readonly line: number;
+  /** Whether this description comes from config */
+  readonly fromConfig: boolean;
+}
+
+/**
+ * Collected scalar type with input/output type information.
+ */
+export interface CollectedScalarType {
+  /** GraphQL scalar name */
+  readonly scalarName: string;
+  /** Input type reference (exactly one required) */
+  readonly inputType: ScalarTypeRef | null;
+  /** Output type references (one or more required, union built from these) */
+  readonly outputTypes: ReadonlyArray<ScalarTypeRef>;
+  /** Description sources */
+  readonly descriptions: ReadonlyArray<DescriptionSource>;
+  /** Whether this is a custom scalar (not built-in) */
+  readonly isCustom: boolean;
+}
+
+/**
+ * Diagnostic error information.
+ */
+export interface ScalarCollectorDiagnostic {
+  readonly code:
+    | "MULTIPLE_INPUT_TYPES"
+    | "MISSING_INPUT_TYPE"
+    | "MISSING_OUTPUT_TYPE";
+  readonly message: string;
+  readonly severity: "error";
+}
+
+/**
+ * Result type for scalar collection.
+ */
+export type CollectScalarsResult =
+  | { success: true; data: ReadonlyArray<CollectedScalarType> }
+  | { success: false; errors: ReadonlyArray<ScalarCollectorDiagnostic> };
+
+interface ScalarGroup {
+  inputTypes: ScalarTypeRef[];
+  outputTypes: ScalarTypeRef[];
+  descriptions: DescriptionSource[];
+}
+
+function createTypeRef(info: ScalarMetadataInfo): ScalarTypeRef {
+  return {
+    typeName: info.typeName,
+    sourceFile: info.sourceFile,
+    line: info.line,
+  };
+}
+
+function createDescriptionSource(
+  info: ScalarMetadataInfo,
+  fromConfig: boolean,
+): DescriptionSource | null {
+  if (!info.description) return null;
+  return {
+    text: info.description,
+    sourceFile: info.sourceFile,
+    line: info.line,
+    fromConfig,
+  };
+}
+
+function sortDescriptions(
+  descriptions: DescriptionSource[],
+): DescriptionSource[] {
+  return [...descriptions].sort((a, b) => {
+    const fileCompare = a.sourceFile.localeCompare(b.sourceFile);
+    if (fileCompare !== 0) return fileCompare;
+    return a.line - b.line;
+  });
+}
+
+/**
+ * Merges multiple descriptions into a single string with blank line separators.
+ * Descriptions are expected to be pre-sorted by file path alphabetically
+ * and by line number within the same file.
+ *
+ * @param descriptions - Array of description sources to merge
+ * @returns Merged description string, or null if no descriptions available
+ */
+export function mergeDescriptions(
+  descriptions: ReadonlyArray<DescriptionSource>,
+): string | null {
+  if (descriptions.length === 0) {
+    return null;
+  }
+  return descriptions.map((d) => d.text).join("\n\n");
+}
+
+function formatTypeLocation(
+  ref: ScalarTypeRef,
+  sourceRoot: string | null,
+): string {
+  const filePath =
+    sourceRoot !== null
+      ? ref.sourceFile.replace(sourceRoot, "").replace(/^[/\\]/, "")
+      : ref.sourceFile;
+  return `${filePath.replace(/\\/g, "/")}:${ref.line}`;
+}
+
+/**
+ * Options for scalar collection.
+ */
+export interface CollectScalarsOptions {
+  /** Root path for normalizing source file paths in error messages */
+  readonly sourceRoot?: string | null;
+}
+
+/**
+ * Collects scalar definitions from types and config,
+ * validates constraints, and builds type parameters.
+ *
+ * @param scalarInfos - Scalar metadata from source files
+ * @param configScalars - Scalar mappings from config file
+ * @param options - Collection options
+ * @returns Result with collected scalars or diagnostics
+ */
+export function collectScalars(
+  scalarInfos: ReadonlyArray<ScalarMetadataInfo>,
+  configScalars: ReadonlyArray<ConfigScalarMapping>,
+  options: CollectScalarsOptions = {},
+): CollectScalarsResult {
+  const sourceRoot = options.sourceRoot ?? null;
+  const scalarGroups = new Map<string, ScalarGroup>();
+
+  const processInfo = (info: ScalarMetadataInfo, fromConfig: boolean): void => {
+    if (isBuiltInScalar(info.scalarName)) {
+      return;
+    }
+
+    let group = scalarGroups.get(info.scalarName);
+    if (!group) {
+      group = { inputTypes: [], outputTypes: [], descriptions: [] };
+      scalarGroups.set(info.scalarName, group);
+    }
+
+    const typeRef = createTypeRef(info);
+
+    if (info.only === null || info.only === "input") {
+      group.inputTypes.push(typeRef);
+    }
+    if (info.only === null || info.only === "output") {
+      group.outputTypes.push(typeRef);
+    }
+
+    const descSource = createDescriptionSource(info, fromConfig);
+    if (descSource) {
+      group.descriptions.push(descSource);
+    }
+  };
+
+  for (const info of scalarInfos) {
+    processInfo(info, false);
+  }
+  for (const info of configScalars) {
+    processInfo(info, info.fromConfig);
+  }
+
+  const diagnostics: ScalarCollectorDiagnostic[] = [];
+  const collectedScalars: CollectedScalarType[] = [];
+
+  for (const [scalarName, group] of scalarGroups) {
+    if (group.inputTypes.length > 1) {
+      const typeLocations = group.inputTypes
+        .map((t) => `'${t.typeName}' at ${formatTypeLocation(t, sourceRoot)}`)
+        .join(", ");
+      diagnostics.push({
+        code: "MULTIPLE_INPUT_TYPES",
+        message: `Custom scalar '${scalarName}' has multiple input types: ${typeLocations}. Only one input type is allowed per scalar.`,
+        severity: "error",
+      });
+      continue;
+    }
+
+    // Allow input-only scalars (no output type required) and output-only scalars (no input type required)
+    // These are valid for context-specific scalar usage patterns (Requirements 3.1, 3.2, 3.3)
+    if (group.inputTypes.length === 0 && group.outputTypes.length === 0) {
+      // Both missing - this shouldn't happen but guard against it
+      continue;
+    }
+
+    collectedScalars.push({
+      scalarName,
+      inputType: group.inputTypes[0] ?? null,
+      outputTypes: group.outputTypes,
+      descriptions: sortDescriptions(group.descriptions),
+      isCustom: true,
+    });
+  }
+
+  if (diagnostics.length > 0) {
+    return { success: false, errors: diagnostics };
+  }
+
+  return { success: true, data: collectedScalars };
+}

package/src/type-extractor/converter/field-eligibility.ts

@@ -0,0 +1,112 @@
+/**
+ * Field and enum value eligibility checks for GraphQL schema generation.
+ *
+ * These functions determine whether a field or enum value can be included
+ * in the generated GraphQL schema based on naming conventions and other rules.
+ */
+
+const GRAPHQL_NAME_PATTERN = /^[_A-Za-z][_0-9A-Za-z]*$/;
+
+export type SkipReason =
+  | { readonly code: "INVALID_NAME"; readonly message: string }
+  | { readonly code: "RESERVED_NAME"; readonly message: string };
+
+export type EligibilityResult =
+  | { readonly eligible: true; readonly skipReason: null }
+  | { readonly eligible: false; readonly skipReason: SkipReason };
+
+function isValidGraphQLName(name: string): boolean {
+  if (name.length === 0) return false;
+  return GRAPHQL_NAME_PATTERN.test(name);
+}
+
+function isReservedName(name: string): boolean {
+  return name.startsWith("__");
+}
+
+/**
+ * Check if a field name is eligible to be included as a GraphQL object field.
+ */
+export function isEligibleAsObjectField(fieldName: string): EligibilityResult {
+  if (isReservedName(fieldName)) {
+    return {
+      eligible: false,
+      skipReason: {
+        code: "RESERVED_NAME",
+        message: `Field '${fieldName}' starts with '__' which is reserved for GraphQL introspection`,
+      },
+    };
+  }
+
+  if (!isValidGraphQLName(fieldName)) {
+    return {
+      eligible: false,
+      skipReason: {
+        code: "INVALID_NAME",
+        message: `Field '${fieldName}' is not a valid GraphQL identifier (must match /^[_A-Za-z][_0-9A-Za-z]*$/)`,
+      },
+    };
+  }
+
+  return { eligible: true, skipReason: null };
+}
+
+/**
+ * Check if a field name is eligible to be included as a GraphQL input object field.
+ */
+export function isEligibleAsInputObjectField(
+  fieldName: string,
+): EligibilityResult {
+  if (isReservedName(fieldName)) {
+    return {
+      eligible: false,
+      skipReason: {
+        code: "RESERVED_NAME",
+        message: `Input field '${fieldName}' starts with '__' which is reserved for GraphQL introspection`,
+      },
+    };
+  }
+
+  if (!isValidGraphQLName(fieldName)) {
+    return {
+      eligible: false,
+      skipReason: {
+        code: "INVALID_NAME",
+        message: `Input field '${fieldName}' is not a valid GraphQL identifier (must match /^[_A-Za-z][_0-9A-Za-z]*$/)`,
+      },
+    };
+  }
+
+  return { eligible: true, skipReason: null };
+}
+
+/**
+ * Check if an enum value name is eligible to be included as a GraphQL enum value.
+ * Note: The name should be the converted (SCREAMING_SNAKE_CASE) name, not the original.
+ */
+export function isEligibleAsEnumValue(
+  convertedName: string,
+  originalName: string,
+): EligibilityResult {
+  if (isReservedName(convertedName)) {
+    return {
+      eligible: false,
+      skipReason: {
+        code: "RESERVED_NAME",
+        message: `Enum member '${originalName}' converts to '${convertedName}' which starts with '__' (reserved for GraphQL introspection)`,
+      },
+    };
+  }
+
+  if (!isValidGraphQLName(convertedName)) {
+    return {
+      eligible: false,
+      skipReason: {
+        code: "INVALID_NAME",
+        message: `Enum member '${originalName}' converts to '${convertedName}' which is not a valid GraphQL identifier`,
+      },
+    };
+  }
+
+  return { eligible: true, skipReason: null };
+}