@xyd-js/gql 0.1.0-xyd.12 → 0.1.0-xyd.15

package/src/gql-core.ts

@@ -0,0 +1,362 @@
+import {
+    GraphQLArgument,
+    GraphQLEnumType,
+    GraphQLEnumValue,
+    GraphQLInputObjectType,
+    GraphQLInterfaceType,
+    GraphQLObjectType,
+    GraphQLScalarType,
+    GraphQLUnionType,
+    GraphQLField,
+    GraphQLInputField,
+    GraphQLNamedType,
+
+    isIntrospectionType,
+    isSpecifiedScalarType, GraphQLNonNull,
+    GraphQLList
+} from "graphql";
+import GithubSlugger from 'github-slugger';
+
+import {
+    Definition,
+    DefinitionProperty,
+    DefinitionPropertyMeta,
+    ExampleGroup,
+    Reference,
+    ReferenceCategory,
+    ReferenceType
+} from "@xyd-js/uniform";
+
+import {GQLTypeInfo, GQLOperation} from "./types";
+import {gqlFieldToUniformDefinitionProperty} from "./converters/gql-field";
+import {Context} from "./context";
+import {openDocsCanonical, openDocsToGroup} from "./opendocs";
+
+export type GraphqlUniformReferenceType =
+    | GraphQLScalarType
+    | GraphQLObjectType
+    | GraphQLInterfaceType
+    | GraphQLUnionType
+    | GraphQLEnumType
+    | GraphQLInputObjectType
+    | GQLOperation
+    | GraphQLField<any, any> | GraphQLInputField | GraphQLArgument
+
+export function extractScopesFromDocDirective(
+    ctx: Context,
+    gqlType: GraphqlUniformReferenceType,
+): string[] {
+    const scopes: string[] = []
+
+    const schema = ctx?.schema
+
+    if (gqlType.astNode?.directives) {
+        for (const directive of gqlType.astNode.directives) {
+            if (directive.name.value === "doc") {
+                const scopesArg = directive.arguments?.find(arg => arg.name.value === 'scopes')
+                if (scopesArg?.value.kind === 'ListValue') {
+                    for (const scopeValue of scopesArg.value.values) {
+                        if (scopeValue.kind === 'EnumValue') {
+                            // For enum values, we need to find the enum type and its value with @scope directive
+                            let enumType: GraphQLEnumType | undefined
+
+                            // First check if current type is an enum
+                            if (gqlType instanceof GraphQLEnumType) {
+                                enumType = gqlType
+                            }
+                            // If not and we have a schema, try to find the enum type
+                            else if (schema) {
+                                const type = schema.getType('OpenDocsScope')
+                                if (type instanceof GraphQLEnumType) {
+                                    enumType = type
+                                }
+                            }
+
+                            if (enumType) {
+                                const enumValue = enumType.getValue(scopeValue.value)
+                                if (enumValue?.astNode?.directives) {
+                                    for (const enumDirective of enumValue.astNode.directives) {
+                                        if (enumDirective.name.value === 'scope') {
+                                            const valueArg = enumDirective.arguments?.find(arg => arg.name.value === 'value')
+                                            if (valueArg?.value.kind === 'StringValue') {
+                                                scopes.push(valueArg.value.value)
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        } else if (scopeValue.kind === 'StringValue') {
+                            // Handle string literal (e.g. "user:write")
+                            scopes.push(scopeValue.value)
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    return scopes
+}
+
+export function uniformify(
+    ctx: Context,
+    gqlType: GraphqlUniformReferenceType,
+    definitions: Definition[],
+    examples: ExampleGroup[],
+): Reference {
+    let canonicalPrefix = ""
+    let graphqlTypeShort = ""
+    let refType: ReferenceType | undefined = undefined
+
+    if (gqlType instanceof GraphQLScalarType) {
+        canonicalPrefix = "scalars"
+        graphqlTypeShort = "scalar"
+        refType = ReferenceType.GRAPHQL_SCALAR
+    } else if (gqlType instanceof GraphQLObjectType) {
+        canonicalPrefix = "objects"
+        graphqlTypeShort = "object"
+        refType = ReferenceType.GRAPHQL_OBJECT
+    } else if (gqlType instanceof GraphQLInterfaceType) {
+        canonicalPrefix = "interfaces"
+        graphqlTypeShort = "interface"
+        refType = ReferenceType.GRAPHQL_INTERFACE
+    } else if (gqlType instanceof GraphQLUnionType) {
+        canonicalPrefix = "unions"
+        graphqlTypeShort = "union"
+        refType = ReferenceType.GRAPHQL_UNION
+    } else if (gqlType instanceof GraphQLEnumType) {
+        canonicalPrefix = "enums"
+        graphqlTypeShort = "enum"
+        refType = ReferenceType.GRAPHQL_ENUM
+    } else if (gqlType instanceof GraphQLInputObjectType) {
+        canonicalPrefix = "inputs"
+        graphqlTypeShort = "input"
+        refType = ReferenceType.GRAPHQL_INPUT
+    } else if (gqlType instanceof GQLOperation) {
+        switch (gqlType._operationType) {
+            case "query": {
+                canonicalPrefix = "queries"
+                graphqlTypeShort = "query"
+                refType = ReferenceType.GRAPHQL_QUERY
+                break;
+            }
+            case "mutation": {
+                canonicalPrefix = "mutations"
+                graphqlTypeShort = "mutation"
+                refType = ReferenceType.GRAPHQL_MUTATION
+                break;
+            }
+            case "subscription": {
+                canonicalPrefix = "subscriptions"
+                graphqlTypeShort = "subscription"
+                refType = ReferenceType.GRAPHQL_SUBSCRIPTION
+                break;
+            }
+        }
+    } else {
+        const info = gqlFieldTypeInfo(gqlType)
+        if (info?.typeFlat && !isBuiltInType(info?.typeFlat)) {
+            if (info?.typeFlat) {
+                return uniformify(ctx, info.typeFlat, definitions, examples)
+            }
+        }
+    }
+
+    const slugger = new GithubSlugger();
+    // const slug = slugger.slug(gqlType.name);
+    const slug = gqlType.name;
+
+    const odCanonical = openDocsCanonical(ctx, gqlType);
+
+    let canonical = ""
+    if (odCanonical) {
+        canonical = odCanonical;
+    } else if (canonicalPrefix) {
+        canonical = [canonicalPrefix, slug].join("/")
+    }
+
+    const scopes = extractScopesFromDocDirective(ctx, gqlType) || []
+    return {
+        title: gqlType.name,
+        description: gqlType.description || "",
+        canonical,
+
+        category: ReferenceCategory.GRAPHQL,
+        type: refType,
+
+        context: {
+            graphqlTypeShort: graphqlTypeShort,
+            graphqlName: gqlType.name,
+            group: openDocsToGroup(ctx, gqlType),
+            scopes
+        },
+
+        examples: {
+            groups: examples || [],
+        },
+
+        definitions,
+    }
+}
+
+export function propsUniformify(
+    ctx: Context,
+    field: GraphQLField<any, any> | GraphQLInputField | GraphQLArgument,
+    properties?: DefinitionProperty[],
+    meta?: DefinitionPropertyMeta[]
+): DefinitionProperty {
+    const fieldInfo = gqlFieldTypeInfo(field);
+    const objRef = uniformify(ctx, field, [], []);
+
+    const builtInType = fieldInfo?.typeFlat ? isBuiltInType(fieldInfo?.typeFlat) : undefined
+
+    return {
+        name: field.name,
+        type: field.type.toJSON(),
+        description: field.description || "",
+        context: {
+            graphqlName: field.name,
+            graphqlTypeFlat: fieldInfo.typeFlat?.toJSON() || "",
+            graphqlBuiltInType: builtInType,
+        },
+        properties: properties || [],
+        meta: [
+            ...gqlFieldToUniformMeta(field),
+            ...(meta || []),
+        ],
+        symbolDef: {
+            canonical: objRef?.canonical,
+        },
+    }
+}
+
+export function gqlObjectPropsUniformify(
+    ctx: Context,
+    obj: GraphQLInputObjectType | GraphQLObjectType,
+    meta?: DefinitionPropertyMeta[]
+): DefinitionProperty {
+    const objRef = uniformify(ctx, obj, [], []);
+    const inputFields = obj.getFields?.()
+    const nestedProps: DefinitionProperty[] = []
+
+    const nestedDefinitionProperty: DefinitionProperty = {
+        name: obj.name,
+        type: obj.toJSON(),
+        description: obj.description || "",
+        context: objRef.context,
+        properties: nestedProps,
+        meta: [
+            ...(meta || []),
+        ],
+        symbolDef: {
+            canonical: objRef.canonical,
+        },
+    }
+
+    if (!ctx?.config?.flatArg) {
+        for (const [name, inputField] of Object.entries(inputFields)) {
+            const prop = gqlFieldToUniformDefinitionProperty(
+                ctx,
+                inputField,
+            )
+
+            if (prop) {
+                nestedProps.push(prop)
+            }
+        }
+    }
+
+    return nestedDefinitionProperty
+}
+
+export function gqlFieldToUniformMeta(
+    field: GraphQLField<any, any> | GraphQLInputField | GraphQLArgument
+): DefinitionPropertyMeta[] {
+    const meta: DefinitionPropertyMeta[] = []
+
+    // Check if field is required (non-null)
+    if (isNonNullField(field.type) || isListOfNonNullItems(field.type)) {
+        meta.push({
+            name: "required",
+            value: "true"
+        })
+    }
+
+    // Handle directives
+    if (field.astNode?.directives) {
+        for (const directive of field.astNode.directives) {
+            // Handle @deprecated directive
+            if (directive.name.value === "deprecated") {
+                let foundDeprecatedReason = false
+                for (const arg of directive.arguments || []) {
+                    if (arg.name.value === "reason") {
+                        foundDeprecatedReason = true
+                        meta.push({
+                            name: "deprecated",
+                            value: arg.value.kind === 'StringValue' ? arg.value.value : "true"
+                        })
+                    }
+                }
+
+                if (!foundDeprecatedReason) {
+                    meta.push({
+                        name: "deprecated",
+                        value: "true"
+                    })
+                }
+            }
+        }
+    }
+
+    if ("defaultValue" in field && field.defaultValue !== undefined) {
+        meta.push({
+            name: "defaults",
+            value: field.defaultValue
+        })
+    }
+
+    return meta
+}
+
+export function gqlFieldTypeInfo(
+    field: GraphQLField<any, any> | GraphQLInputField
+): GQLTypeInfo {
+    const getTypeInfo = (type: any): GraphQLNamedType | undefined => {
+        if (!type) return undefined;
+
+        // Handle non-null types
+        if (type instanceof GraphQLNonNull) {
+            return getTypeInfo(type.ofType);
+        }
+
+
+        if (type instanceof GraphQLList) {
+            return getTypeInfo(type.ofType);
+        }
+
+        // Return the actual type
+        return type;
+    };
+
+    const graphqlTypeFlat = getTypeInfo(field.type);
+
+    return {
+        typeFlat: graphqlTypeFlat
+    }
+}
+
+export function isBuiltInType(gqlType: GraphQLNamedType): boolean {
+    return isSpecifiedScalarType(gqlType) || isIntrospectionType(gqlType)
+}
+
+// TODO: fix any
+function isNonNullField(type: any): boolean {
+    return type.constructor.name === "GraphQLNonNull"
+}
+
+// TODO: fix any
+function isListOfNonNullItems(type: any): boolean {
+    return "ofType" in type &&
+        type.constructor.name === "GraphQLList" &&
+        type.ofType.constructor.name === "GraphQLNonNull"
+}

package/src/opendocs.graphql

@@ -0,0 +1,56 @@
+directive @scope(value: String!) on ENUM_VALUE
+
+enum OpenDocsScope {
+    _PLACEHOLDER_
+}
+
+directive @docs(
+    route: String
+    sort: [OpenDocsSortInput!]
+    sortStack: [[String!]!]
+    flattenTypes: Boolean
+    sidebar: [OpenDocsPage]
+    group: [String]
+) repeatable on SCHEMA
+
+input OpenDocsPage {
+    type: OpenDocsSidebarItemType!
+    key: String!
+    group: String
+    path: String
+    pages: [OpenDocsPage]
+}
+
+enum OpenDocsSidebarItemType {
+    OPERATION
+    TYPE
+}
+
+directive @doc(
+    group: [String!],
+    path: String,
+    example: OpenDocsExampleInput,
+    scopes: [OpenDocsScope],
+) on QUERY |
+    FIELD_DEFINITION |
+    MUTATION |
+    SUBSCRIPTION |
+    OBJECT |
+    INPUT_OBJECT |
+    ENUM |
+    SCALAR |
+    UNION
+
+# TODO: finish
+input OpenDocsExampleInput {
+    """
+    The name of the code
+    """
+    code: String!
+}
+
+input OpenDocsSortInput {
+    node: String
+    group: [String!]
+    stack: Int
+}

package/src/opendocs.ts

@@ -0,0 +1,253 @@
+import {
+    GraphQLSchema,
+    GraphQLArgument,
+    GraphQLEnumType,
+    GraphQLEnumValue,
+    GraphQLField,
+    GraphQLInputObjectType,
+    GraphQLInterfaceType,
+    GraphQLObjectType,
+    GraphQLScalarType,
+    GraphQLUnionType,
+    ConstValueNode,
+    StringValueNode,
+} from "graphql";
+
+import {GQLOperation, GQLSchemaToReferencesOptions, SortItem} from "./types";
+import {GraphqlUniformReferenceType} from "./gql-core";
+import {Context} from "./context";
+
+export const OPEN_DOCS_SCHEMA_DIRECTIVE_NAME = "docs";
+export const OPEN_DOCS_DIRECTIVE_NAME = "doc";
+
+export function openDocsExtensionsToOptions(
+    schema: GraphQLSchema,
+) {
+    const options: GQLSchemaToReferencesOptions = {}
+
+    // Check for @docs directive in schema extensions
+    for (const extension of schema.extensionASTNodes || []) {
+        if (extension.kind === 'SchemaExtension') {
+            for (const directive of extension.directives || []) {
+                if (directive.name.value === OPEN_DOCS_SCHEMA_DIRECTIVE_NAME) {
+                    for (const arg of directive.arguments || []) {
+                        if (arg.name.value === 'flattenTypes' && arg.value.kind === 'BooleanValue') {
+                            if (arg.value.value === true) {
+                                options.flat = true
+                            } else if (arg.value.value === false) {
+                                options.flat = false
+                            }
+                        } else if (arg.name.value === 'sort' && arg.value.kind === 'ListValue') {
+                            const sortItems: SortItem[] = [];
+                            for (const item of arg.value.values) {
+                                if (item.kind === 'ObjectValue') {
+                                    const sortItem: SortItem = {};
+                                    for (const field of item.fields) {
+                                        if (field.name.value === 'node' && field.value.kind === 'StringValue') {
+                                            sortItem.node = field.value.value;
+                                        } else if (field.name.value === 'group' && field.value.kind === 'ListValue') {
+                                            sortItem.group = field.value.values
+                                                .filter((v): v is StringValueNode => v.kind === 'StringValue')
+                                                .map(v => v.value);
+                                        } else if (field.name.value === 'stack' && field.value.kind === 'IntValue') {
+                                            sortItem.stack = parseInt(field.value.value);
+                                        }
+                                    }
+                                    sortItems.push(sortItem);
+                                }
+                            }
+                            if (!options.sort) {
+                                options.sort = {};
+                            }
+                            options.sort.sort = sortItems;
+                        } else if (arg.name.value === 'sortStack' && arg.value.kind === 'ListValue') {
+                            const sortStacks: string[][] = [];
+                            for (const item of arg.value.values) {
+                                if (item.kind === 'ListValue') {
+                                    const stack = item.values
+                                        .filter((v): v is StringValueNode => v.kind === 'StringValue')
+                                        .map(v => v.value);
+                                    sortStacks.push(stack);
+                                }
+                            }
+                            if (!options.sort) {
+                                options.sort = {};
+                            }
+                            options.sort.sortStack = sortStacks;
+                        } else if (arg.name.value === 'route' && arg.value.kind === 'StringValue') {
+                            options.route = arg.value.value;
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    return options;
+}
+
+type OpenDocsGQLNode =
+    | GQLOperation
+    | GraphQLScalarType
+    | GraphQLObjectType
+    | GraphQLField<any, any>
+    | GraphQLArgument
+    | GraphQLInterfaceType
+    | GraphQLUnionType
+    | GraphQLEnumType
+    | GraphQLEnumValue
+    | GraphQLInputObjectType
+
+export function openDocsToGroup(
+    ctx: Context | undefined,
+    odGqlNode: OpenDocsGQLNode,
+): string[] {
+    let groups: string[] = []
+
+    const metadata = (ctx?.schema as any).__metadata;
+
+    if (metadata?.rootGroups) {
+        groups = [...metadata.rootGroups];
+    }
+
+    let directiveGroups = false
+
+    // Check schema metadata for field-specific groups (for operations)
+    if (ctx?.schema && 'name' in odGqlNode) {
+        const metadata = (ctx.schema as any).__metadata;
+        if (metadata?.fields) {
+            if ("_operationType" in odGqlNode) {
+                let fieldKey = ""
+
+                switch (odGqlNode._operationType) {
+                    case "query": {
+                        fieldKey = `Query.${odGqlNode.name}`;
+                        break;
+                    }
+                    case "mutation": {
+                        fieldKey = `Mutation.${odGqlNode.name}`;
+                        break;
+                    }
+                    case "subscription": {
+                        fieldKey = `Subscription.${odGqlNode.name}`;
+                        break;
+                    }
+                }
+
+                const fieldMetadata = metadata.fields.get(fieldKey);
+                if (fieldMetadata?.groups) {
+                    directiveGroups = true
+                    groups.push(...fieldMetadata.groups);
+                }
+            }
+        }
+    }
+
+    // If no groups from metadata, try getting groups from the node itself
+    if (!directiveGroups && odGqlNode.astNode?.directives) {
+        for (const directive of odGqlNode.astNode.directives) {
+            switch (directive.name.value) {
+                case OPEN_DOCS_DIRECTIVE_NAME: {
+                    const groupArg = directive.arguments?.find((arg: {
+                        name: { value: string }
+                    }) => arg.name.value === 'group')
+                    if (groupArg?.value.kind === 'ListValue') {
+                        directiveGroups = true
+                        groups.push(...groupArg.value.values
+                            .filter((v: ConstValueNode): v is StringValueNode => v.kind === 'StringValue')
+                            .map(v => v.value)
+                        )
+                    }
+                    break
+                }
+            }
+        }
+    }
+
+    // If still no groups, use default based on type
+    if (!directiveGroups) {
+        if (odGqlNode instanceof GraphQLObjectType) {
+            groups.push("Objects")
+        } else if (odGqlNode instanceof GraphQLInterfaceType) {
+            groups.push("Interfaces")
+        } else if (odGqlNode instanceof GraphQLUnionType) {
+            groups.push("Unions")
+        } else if (odGqlNode instanceof GraphQLEnumType) {
+            groups.push("Enums")
+        } else if (odGqlNode instanceof GraphQLInputObjectType) {
+            groups.push("Inputs")
+        } else if (odGqlNode instanceof GraphQLScalarType) {
+            groups.push("Scalars")
+        } else if (odGqlNode instanceof GQLOperation) {
+            switch (odGqlNode._operationType) {
+                case "query": {
+                    groups.push("Queries")
+                    break;
+                }
+                case "mutation": {
+                    groups.push("Mutations")
+                    break;
+                }
+                case "subscription": {
+                    groups.push("Subscriptions")
+                    break;
+                }
+            }
+        }
+    }
+
+    return groups
+}
+
+export function openDocsCanonical(
+    ctx: Context,
+    gqlType: GraphqlUniformReferenceType,
+) {
+    let path = ""
+
+    // Get parent path if this is a field
+    if ('astNode' in gqlType && gqlType.astNode?.kind === 'FieldDefinition' && ctx?.schema) {
+        // Check schema metadata for field-specific path
+        const metadata = (ctx.schema as any).__metadata;
+        if (metadata?.fields && 'name' in gqlType) {
+            if ("_operationType" in gqlType) {
+                let fieldKey = ""
+
+                switch (gqlType._operationType) {
+                    case "query": {
+                        fieldKey = `Query.${gqlType.name}`;
+                        break;
+                    }
+                    case "mutation": {
+                        fieldKey = `Mutation.${gqlType.name}`;
+                        break;
+                    }
+                    case "subscription": {
+                        fieldKey = `Subscription.${gqlType.name}`;
+                        break;
+                    }
+                }
+                const fieldMetadata = metadata.fields.get(fieldKey);
+
+
+                if (fieldMetadata?.path) {
+                    path = fieldMetadata.path;
+                }
+            }
+        }
+    }
+
+    // Extract path from @doc directive if present
+    if (!path && gqlType.astNode?.directives) {
+        for (const directive of gqlType.astNode.directives) {
+            if (directive.name.value === OPEN_DOCS_DIRECTIVE_NAME) {
+                const pathArg = directive.arguments?.find(arg => arg.name.value === 'path')
+                if (pathArg?.value.kind === 'StringValue') {
+                    path = pathArg.value.value
+                }
+            }
+        }
+    }
+
+    return path
+}