@gqlkit-ts/cli 0.0.1 → 0.2.0

package/src/type-extractor/types/ts-type-reference-factory.ts

@@ -0,0 +1,137 @@
+import type ts from "typescript";
+import type {
+  InlineEnumMemberInfo,
+  InlineObjectPropertyDef,
+  ScalarTypeInfo,
+  TSTypeReference,
+} from "./typescript.js";
+
+interface CreateTSTypeReferenceParams {
+  readonly kind: TSTypeReference["kind"];
+  readonly overrides: Partial<TSTypeReference>;
+}
+
+function createTSTypeReference(
+  params: CreateTSTypeReferenceParams,
+): TSTypeReference {
+  return {
+    kind: params.kind,
+    name: null,
+    elementType: null,
+    members: null,
+    nullable: false,
+    scalarInfo: null,
+    inlineObjectProperties: null,
+    inlineEnumMembers: null,
+    externalEnumSymbol: null,
+    externalEnumDescription: null,
+    externalEnumDeprecated: null,
+    ...params.overrides,
+  };
+}
+
+interface CreateReferenceTypeParams {
+  readonly name: string;
+  readonly nullable: boolean;
+}
+
+export function createReferenceType(
+  params: CreateReferenceTypeParams,
+): TSTypeReference {
+  return createTSTypeReference({
+    kind: "reference",
+    overrides: { name: params.name, nullable: params.nullable },
+  });
+}
+
+interface CreatePrimitiveTypeParams {
+  readonly name: string;
+  readonly nullable: boolean;
+}
+
+export function createPrimitiveType(
+  params: CreatePrimitiveTypeParams,
+): TSTypeReference {
+  return createTSTypeReference({
+    kind: "primitive",
+    overrides: { name: params.name, nullable: params.nullable },
+  });
+}
+
+export function createArrayType(elementType: TSTypeReference): TSTypeReference {
+  return createTSTypeReference({ kind: "array", overrides: { elementType } });
+}
+
+interface CreateUnionTypeParams {
+  readonly members: ReadonlyArray<TSTypeReference>;
+  readonly nullable: boolean;
+}
+
+export function createUnionType(
+  params: CreateUnionTypeParams,
+): TSTypeReference {
+  return createTSTypeReference({
+    kind: "union",
+    overrides: { members: params.members, nullable: params.nullable },
+  });
+}
+
+export function createInlineObjectType(
+  properties: ReadonlyArray<InlineObjectPropertyDef>,
+): TSTypeReference {
+  return createTSTypeReference({
+    kind: "inlineObject",
+    overrides: { inlineObjectProperties: properties },
+  });
+}
+
+interface CreateScalarTypeParams {
+  readonly name: string;
+  readonly scalarInfo: ScalarTypeInfo;
+  readonly nullable: boolean;
+}
+
+export function createScalarType(
+  params: CreateScalarTypeParams,
+): TSTypeReference {
+  return createTSTypeReference({
+    kind: "scalar",
+    overrides: {
+      name: params.name,
+      scalarInfo: params.scalarInfo,
+      nullable: params.nullable,
+    },
+  });
+}
+
+export function createLiteralType(name: string): TSTypeReference {
+  return createTSTypeReference({ kind: "literal", overrides: { name } });
+}
+
+interface CreateInlineEnumTypeParams {
+  readonly members: ReadonlyArray<InlineEnumMemberInfo>;
+  readonly nullable: boolean;
+  /** External TypeScript enum symbol for deduplication (null for string literal unions) */
+  readonly externalEnumSymbol: ts.Symbol | null;
+  /** TSDoc description from the external enum type itself (null for string literal unions) */
+  readonly externalEnumDescription: string | null;
+  /** @deprecated tag from the external enum type itself (null for string literal unions) */
+  readonly externalEnumDeprecated:
+    | import("../../shared/tsdoc-parser.js").DeprecationInfo
+    | null;
+}
+
+export function createInlineEnumType(
+  params: CreateInlineEnumTypeParams,
+): TSTypeReference {
+  return createTSTypeReference({
+    kind: "inlineEnum",
+    overrides: {
+      inlineEnumMembers: params.members,
+      nullable: params.nullable,
+      externalEnumSymbol: params.externalEnumSymbol,
+      externalEnumDescription: params.externalEnumDescription,
+      externalEnumDeprecated: params.externalEnumDeprecated,
+    },
+  });
+}

package/src/type-extractor/types/typescript.ts

@@ -0,0 +1,133 @@
+import type ts from "typescript";
+import type {
+  DirectiveArgumentValue,
+  DirectiveInfo,
+} from "../../shared/directive-detector.js";
+import type { DeprecationInfo } from "../../shared/tsdoc-parser.js";
+import type { SourceLocation } from "./diagnostics.js";
+
+export type TypeKind =
+  | "object"
+  | "interface"
+  | "union"
+  | "enum"
+  | "graphqlInterface";
+
+/**
+ * Information about a detected scalar type.
+ */
+export interface ScalarTypeInfo {
+  /** The GraphQL scalar type name (ID, Int, Float, String, Boolean, or custom scalar name) */
+  readonly scalarName: string;
+  /** The TypeScript type name (e.g., "IDString", "Int", "DateTime") */
+  readonly typeName: string;
+  /** The underlying TypeScript primitive type (undefined for custom scalars) */
+  readonly baseType: "string" | "number" | undefined;
+  /** Whether this is a custom scalar */
+  readonly isCustom: boolean;
+  /** Usage constraint: "input" for input-only, "output" for output-only, null for both */
+  readonly only: "input" | "output" | null;
+}
+
+export interface TypeMetadata {
+  readonly name: string;
+  readonly kind: TypeKind;
+  readonly sourceFile: string;
+  readonly sourceLocation: SourceLocation;
+  readonly exportKind: "named" | "default";
+  readonly description: string | null;
+  readonly deprecated: DeprecationInfo | null;
+  readonly directives: ReadonlyArray<DirectiveInfo> | null;
+}
+
+export type TSTypeReferenceKind =
+  | "primitive"
+  | "reference"
+  | "array"
+  | "union"
+  | "literal"
+  | "scalar"
+  | "inlineObject"
+  | "inlineEnum";
+
+/**
+ * Information about an inline enum member (string literal union value).
+ */
+export interface InlineEnumMemberInfo {
+  /** Original value from TypeScript (e.g., "pendingReview") */
+  readonly value: string;
+  /** Description from TSDoc (if available) */
+  readonly description: string | null;
+  /** Deprecation info from @deprecated tag */
+  readonly deprecated: DeprecationInfo | null;
+}
+
+export interface TSTypeReference {
+  readonly kind: TSTypeReferenceKind;
+  readonly name: string | null;
+  readonly elementType: TSTypeReference | null;
+  readonly members: ReadonlyArray<TSTypeReference> | null;
+  readonly nullable: boolean;
+  readonly scalarInfo: ScalarTypeInfo | null;
+  readonly inlineObjectProperties: ReadonlyArray<InlineObjectPropertyDef> | null;
+  /** Inline enum members when kind is "inlineEnum" */
+  readonly inlineEnumMembers: ReadonlyArray<InlineEnumMemberInfo> | null;
+  /** External TypeScript enum symbol for deduplication (Requirement 5.2) */
+  readonly externalEnumSymbol: ts.Symbol | null;
+  /** TSDoc description from the external enum type itself (Requirement 6.1) */
+  readonly externalEnumDescription: string | null;
+  /** @deprecated tag from the external enum type itself (Requirement 6.3) */
+  readonly externalEnumDeprecated: DeprecationInfo | null;
+}
+
+export interface InlineObjectPropertyDef {
+  readonly name: string;
+  readonly tsType: TSTypeReference;
+  readonly optional: boolean;
+  readonly description: string | null;
+  readonly deprecated: DeprecationInfo | null;
+  readonly directives: ReadonlyArray<DirectiveInfo> | null;
+  readonly defaultValue: DirectiveArgumentValue | null;
+  readonly sourceLocation: SourceLocation | null;
+}
+
+export interface FieldDefinition {
+  readonly name: string;
+  readonly tsType: TSTypeReference;
+  readonly optional: boolean;
+  readonly description: string | null;
+  readonly deprecated: DeprecationInfo | null;
+  readonly directives: ReadonlyArray<DirectiveInfo> | null;
+  readonly defaultValue: DirectiveArgumentValue | null;
+  readonly sourceLocation: SourceLocation | null;
+}
+
+export interface EnumMemberInfo {
+  readonly name: string;
+  readonly value: string;
+  /** Numeric value for numeric enums, null for string enums */
+  readonly numericValue: number | null;
+  readonly description: string | null;
+  readonly deprecated: DeprecationInfo | null;
+  readonly sourceLocation: SourceLocation | null;
+}
+
+export interface InlineObjectProperty {
+  readonly propertyName: string;
+  readonly propertyType: TSTypeReference;
+  readonly description: string | null;
+  readonly deprecated: DeprecationInfo | null;
+}
+
+export interface InlineObjectMember {
+  readonly properties: ReadonlyArray<InlineObjectProperty>;
+}
+
+export interface ExtractedTypeInfo {
+  readonly metadata: TypeMetadata;
+  readonly fields: ReadonlyArray<FieldDefinition>;
+  readonly unionMembers: ReadonlyArray<string> | null;
+  readonly inlineObjectMembers: ReadonlyArray<InlineObjectMember> | null;
+  readonly enumMembers: ReadonlyArray<EnumMemberInfo> | null;
+  readonly implementedInterfaces: ReadonlyArray<string> | null;
+}

package/src/type-extractor/validator/type-validator.ts

@@ -0,0 +1,77 @@
+import { BUILT_IN_SCALARS } from "../../shared/constants.js";
+import type { Diagnostic, GraphQLTypeInfo } from "../types/index.js";
+
+export interface ValidationResult {
+  readonly valid: boolean;
+  readonly diagnostics: ReadonlyArray<Diagnostic>;
+}
+
+export interface ValidateTypesOptions {
+  readonly types: ReadonlyArray<GraphQLTypeInfo>;
+  readonly customScalarNames: ReadonlyArray<string> | null;
+}
+const PLACEHOLDER_TYPES = new Set(["__INLINE_OBJECT__", "__INLINE_ENUM__"]);
+
+function isOptionsObject(
+  arg: ReadonlyArray<GraphQLTypeInfo> | ValidateTypesOptions,
+): arg is ValidateTypesOptions {
+  return !Array.isArray(arg) && "types" in arg;
+}
+
+export function validateTypes(
+  typesOrOptions: ReadonlyArray<GraphQLTypeInfo> | ValidateTypesOptions,
+): ValidationResult {
+  const types = isOptionsObject(typesOrOptions)
+    ? typesOrOptions.types
+    : typesOrOptions;
+  const customScalarNames = isOptionsObject(typesOrOptions)
+    ? typesOrOptions.customScalarNames
+    : undefined;
+
+  const diagnostics: Diagnostic[] = [];
+
+  const typeNames = new Set(types.map((t) => t.name));
+  const knownScalars = new Set([
+    ...BUILT_IN_SCALARS,
+    ...(customScalarNames ?? []),
+  ]);
+
+  for (const type of types) {
+    if (type.kind === "Object" && type.fields) {
+      for (const field of type.fields) {
+        const typeName = field.type.typeName;
+
+        if (
+          !typeNames.has(typeName) &&
+          !knownScalars.has(typeName) &&
+          !PLACEHOLDER_TYPES.has(typeName)
+        ) {
+          diagnostics.push({
+            code: "UNRESOLVED_REFERENCE",
+            message: `Field '${field.name}' references unresolved type '${typeName}'`,
+            severity: "error",
+            location: { file: type.sourceFile, line: 1, column: 1 },
+          });
+        }
+      }
+    }
+
+    if (type.kind === "Union" && type.unionMembers) {
+      for (const member of type.unionMembers) {
+        if (!typeNames.has(member) && !knownScalars.has(member)) {
+          diagnostics.push({
+            code: "UNRESOLVED_REFERENCE",
+            message: `Union '${type.name}' references unresolved type '${member}'`,
+            severity: "error",
+            location: { file: type.sourceFile, line: 1, column: 1 },
+          });
+        }
+      }
+    }
+  }
+
+  return {
+    valid: diagnostics.length === 0,
+    diagnostics,
+  };
+}

package/README.md

@@ -1,45 +0,0 @@
-# @gqlkit-ts/cli
-
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@gqlkit-ts/cli`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**