@graphoria/server 0.1.0

package/src/analyzeQuery/analyzers/fragmentAnalyzer.ts

@@ -0,0 +1,29 @@
+import type { FragmentDefinitionNode, GraphQLObjectType, GraphQLSchema } from "graphql";
+import type { MergedEntities } from "../../configuration/getSchemas/mergeEntities";
+import type { FragmentAnalysis, VariableDefinition } from "../types";
+
+import { analyzeSelections } from "./selectionAnalyzer";
+
+export const analyzeFragment = (
+  fragmentDef: FragmentDefinitionNode,
+  entities: MergedEntities,
+  gqlSchema: GraphQLSchema,
+  generatedVariables: VariableDefinition[],
+): FragmentAnalysis => {
+  const typeCondition = gqlSchema.getType(
+    fragmentDef.typeCondition.name.value,
+  ) as GraphQLObjectType;
+
+  return {
+    name: fragmentDef.name.value,
+    typeCondition: fragmentDef.typeCondition.name.value,
+    fields: analyzeSelections(
+      fragmentDef.selectionSet.selections,
+      typeCondition,
+      entities,
+      gqlSchema,
+      [],
+      generatedVariables,
+    ),
+  };
+};

package/src/analyzeQuery/analyzers/operationAnalyzer.ts

@@ -0,0 +1,50 @@
+import { GraphQLObjectType, GraphQLSchema } from "graphql";
+
+import type { OperationDefinitionNode } from "graphql";
+import type { Maybe } from "graphql/jsutils/Maybe";
+import type { MergedEntities } from "../../configuration/getSchemas/mergeEntities";
+import type { OperationAnalysis, VariableDefinition } from "../types";
+
+import { analyzeSelections } from "./selectionAnalyzer";
+import { analyzeVariables } from "./variableAnalyzer";
+
+export const analyzeOperation = (
+  operationDef: OperationDefinitionNode,
+  entities: MergedEntities,
+  gqlSchema: GraphQLSchema,
+  generatedVariables: VariableDefinition[],
+): OperationAnalysis | null => {
+  let rootType: Maybe<GraphQLObjectType> | undefined;
+
+  if (operationDef.operation === "query") {
+    rootType = gqlSchema.getQueryType();
+  } else if (operationDef.operation === "mutation") {
+    rootType = gqlSchema.getMutationType();
+  } else if (operationDef.operation === "subscription") {
+    rootType = gqlSchema.getSubscriptionType();
+  }
+
+  if (!rootType) return null;
+
+  const { name, operation, variableDefinitions, selectionSet } = operationDef;
+
+  const declaredVariables = analyzeVariables(variableDefinitions);
+
+  const fields = analyzeSelections(
+    selectionSet.selections,
+    rootType,
+    entities,
+    gqlSchema,
+    declaredVariables,
+    generatedVariables,
+  );
+
+  const allVariables = [...declaredVariables, ...generatedVariables];
+
+  return {
+    name: name ? name.value : null,
+    operation,
+    variables: allVariables,
+    fields,
+  };
+};

package/src/analyzeQuery/analyzers/selectionAnalyzer.ts

@@ -0,0 +1,135 @@
+import { GraphQLObjectType, GraphQLSchema } from "graphql";
+
+import type { FieldNode, SelectionNode } from "graphql";
+import type { MergedEntities } from "../../configuration/getSchemas/mergeEntities";
+import type { SelectionAnalysis, VariableDefinition } from "../types";
+
+import { analyzeDirectives } from "../directiveUtils";
+import { getFieldType, unwrapType } from "../typeUtils";
+import { extractArgumentValue } from "../valueExtractors";
+
+export const analyzeSelections = (
+  selections: readonly SelectionNode[],
+  parentType: GraphQLObjectType,
+  entities: MergedEntities,
+  gqlSchema: GraphQLSchema,
+  declaredVariables: VariableDefinition[],
+  generatedVariables: VariableDefinition[],
+): SelectionAnalysis[] =>
+  selections
+    .map((selection) => {
+      if (selection.kind === "Field") {
+        const field = selection as FieldNode;
+
+        const isGqlQuery = entities.queriesMap[field.name.value] !== undefined;
+
+        let args = field.arguments
+          ? Object.fromEntries(
+              field.arguments.map((arg) => [
+                arg.name.value,
+                extractArgumentValue(arg.value, isGqlQuery ? generatedVariables : undefined),
+              ]),
+            )
+          : undefined;
+
+        const fieldName = field.name.value;
+        if (fieldName === "__typename") {
+          return {
+            name: fieldName,
+          };
+        }
+        const fieldType = getFieldType(parentType, fieldName);
+        let isArray = false;
+        let fieldObjType: GraphQLObjectType | null = null;
+
+        if (fieldType) {
+          const unwrapped = unwrapType(fieldType);
+          isArray = unwrapped.isArray;
+          if (unwrapped.type instanceof GraphQLObjectType) {
+            fieldObjType = unwrapped.type;
+          }
+        }
+
+        const hasDirectives = field.directives && field.directives.length > 0;
+
+        const directives = analyzeDirectives(field.directives || [], generatedVariables);
+
+        const isRequired =
+          directives.filter(
+            (dir) => dir.name === "include" || dir.name === "skip" || dir.name === "when",
+          ).length === 0;
+
+        if (isArray && entities.queriesMap[fieldName]?.rolePermission?.filter) {
+          if (!args) {
+            args = {
+              where: entities.queriesMap[fieldName].rolePermission?.filter,
+            };
+          } else {
+            args = {
+              ...args,
+              where: {
+                ...(args.where || {}),
+                ...entities.queriesMap[fieldName].rolePermission?.filter,
+              },
+            };
+          }
+        }
+
+        const selectionAnalysis: SelectionAnalysis = {
+          name: fieldName,
+          ...(field.alias && { alias: field.alias.value }),
+          ...(args && Object.keys(args).length && { arguments: args }),
+          ...(isArray && { isArray }),
+          ...(hasDirectives && { directives }),
+          ...(field.selectionSet &&
+            fieldObjType && {
+              selections: analyzeSelections(
+                field.selectionSet.selections,
+                fieldObjType,
+                entities,
+                gqlSchema,
+                declaredVariables,
+                generatedVariables,
+              ),
+            }),
+          ...(isRequired && { isRequired }),
+        };
+        return selectionAnalysis;
+      } else if (selection.kind === "FragmentSpread") {
+        return {
+          name: `...${selection.name.value}`,
+          ...(selection.directives &&
+            selection.directives.length > 0 && {
+              directives: analyzeDirectives(selection.directives, generatedVariables),
+            }),
+        };
+      } else if (selection.kind === "InlineFragment") {
+        const typeCondition =
+          selection.typeCondition &&
+          (gqlSchema.getType(selection.typeCondition.name.value) as GraphQLObjectType);
+
+        return {
+          name: `... on ${selection.typeCondition?.name.value}`,
+          ...(selection.directives &&
+            selection.directives.length > 0 && {
+              directives: analyzeDirectives(selection.directives, generatedVariables),
+            }),
+          selections:
+            selection.selectionSet && typeCondition
+              ? analyzeSelections(
+                  selection.selectionSet.selections,
+                  typeCondition,
+                  entities,
+                  gqlSchema,
+                  declaredVariables,
+                  generatedVariables,
+                )
+              : undefined,
+        };
+      } else {
+        return {
+          name: "UnknownSelection",
+        };
+      }
+    })
+    .filter((sel) => sel.name !== "__typename");

package/src/analyzeQuery/analyzers/variableAnalyzer.ts

@@ -0,0 +1,17 @@
+import type { VariableDefinitionNode } from "graphql";
+import type { VariableDefinition } from "../types";
+
+import { processType } from "../typeUtils";
+import { extractArgumentValue } from "../valueExtractors";
+
+export const analyzeVariables = (
+  variableDefinitions: readonly VariableDefinitionNode[] = [],
+): VariableDefinition[] =>
+  variableDefinitions.map((varDef) => ({
+    name: varDef.variable.name.value,
+    required: varDef.type.kind === "NonNullType",
+    type: processType(varDef.type),
+    ...(varDef.defaultValue && {
+      defaultValue: extractArgumentValue(varDef.defaultValue),
+    }),
+  }));

package/src/analyzeQuery/depthLimit.ts

@@ -0,0 +1,124 @@
+import { GraphQLError, Kind } from "graphql";
+
+import type {
+  ASTNode,
+  ASTVisitor,
+  DocumentNode,
+  FragmentDefinitionNode,
+  ValidationContext,
+} from "graphql";
+
+/**
+ * Compute the depth of a selection set, resolving fragment spreads.
+ * Introspection fields (__schema, __type, __typename) are excluded.
+ */
+function computeDepth(
+  node: { selectionSet?: { selections: readonly ASTNode[] } },
+  fragments: Map<string, FragmentDefinitionNode>,
+  depthSoFar: number,
+  maxDepth: number,
+  visited: Set<string>,
+): number {
+  if (!node.selectionSet) return depthSoFar;
+
+  let max = depthSoFar;
+
+  for (const selection of node.selectionSet.selections) {
+    switch (selection.kind) {
+      case Kind.FIELD: {
+        // Skip introspection meta-fields
+        if (selection.name.value.startsWith("__")) continue;
+
+        const fieldDepth = computeDepth(selection, fragments, depthSoFar + 1, maxDepth, visited);
+
+        if (fieldDepth > max) max = fieldDepth;
+
+        // Early exit if already over the limit
+        if (max > maxDepth) return max;
+        break;
+      }
+
+      case Kind.FRAGMENT_SPREAD: {
+        const name = selection.name.value;
+
+        // Guard against circular fragments
+        if (visited.has(name)) continue;
+        visited.add(name);
+
+        const fragment = fragments.get(name);
+        if (!fragment) continue;
+
+        const fragmentDepth = computeDepth(fragment, fragments, depthSoFar, maxDepth, visited);
+
+        if (fragmentDepth > max) max = fragmentDepth;
+        if (max > maxDepth) return max;
+        break;
+      }
+
+      case Kind.INLINE_FRAGMENT: {
+        const inlineDepth = computeDepth(selection, fragments, depthSoFar, maxDepth, visited);
+
+        if (inlineDepth > max) max = inlineDepth;
+        if (max > maxDepth) return max;
+        break;
+      }
+    }
+  }
+
+  return max;
+}
+
+/**
+ * Collect all fragment definitions from a document.
+ */
+function collectFragments(document: DocumentNode): Map<string, FragmentDefinitionNode> {
+  const fragments = new Map<string, FragmentDefinitionNode>();
+
+  for (const def of document.definitions) {
+    if (def.kind === Kind.FRAGMENT_DEFINITION) {
+      fragments.set(def.name.value, def);
+    }
+  }
+
+  return fragments;
+}
+
+/**
+ * GraphQL validation rule that rejects queries exceeding a maximum nesting depth.
+ *
+ * @param maxDepth - Maximum allowed depth (1 = only top-level fields)
+ * @returns A GraphQL ValidationRule
+ *
+ * @example
+ * ```ts
+ * import { validate, parse } from "graphql";
+ *
+ * const errors = validate(schema, parse(query), [depthLimitRule(10)]);
+ * ```
+ */
+export const depthLimitRule =
+  (maxDepth: number) =>
+  (context: ValidationContext): ASTVisitor => {
+    return {
+      Document(node) {
+        const fragments = collectFragments(node);
+
+        for (const def of node.definitions) {
+          if (def.kind !== Kind.OPERATION_DEFINITION) continue;
+
+          const depth = computeDepth(def, fragments, 0, maxDepth, new Set<string>());
+
+          if (depth > maxDepth) {
+            const operationName = def.name?.value ?? "anonymous";
+
+            context.reportError(
+              new GraphQLError(
+                `Query depth of ${depth} exceeds the maximum allowed depth of ${maxDepth} (operation: "${operationName}")`,
+                { nodes: [def] },
+              ),
+            );
+          }
+        }
+      },
+    };
+  };

package/src/analyzeQuery/directiveUtils.ts

@@ -0,0 +1,99 @@
+import type { DirectiveNode } from "graphql";
+import type { DirectiveAnalysis, VariableDefinition } from "./types";
+
+import { extractArgumentValue } from "./valueExtractors";
+
+// Directive argument specification — gates which args are parameterized vs enum-validated
+interface DirectiveArgSpec {
+  type: "Int" | "Float" | "String" | "Boolean";
+  kind: "param" | "enum";
+  values?: string[];
+}
+
+const DIRECTIVE_ARG_SPEC: Record<string, Record<string, DirectiveArgSpec>> = {
+  truncate: { length: { type: "Int", kind: "param" } },
+  default: { value: { type: "String", kind: "param" } },
+  substring: {
+    start: { type: "Int", kind: "param" },
+    length: { type: "Int", kind: "param" },
+  },
+  replace: {
+    find: { type: "String", kind: "param" },
+    replaceWith: { type: "String", kind: "param" },
+  },
+  concat: {
+    with: { type: "String", kind: "param" },
+    position: { type: "String", kind: "enum", values: ["before", "after"] },
+  },
+  pad: {
+    length: { type: "Int", kind: "param" },
+    char: { type: "String", kind: "param" },
+    side: { type: "String", kind: "enum", values: ["left", "right"] },
+  },
+  dateFormat: { format: { type: "String", kind: "param" } },
+  round: { decimals: { type: "Int", kind: "param" } },
+  multiply: { by: { type: "Float", kind: "param" } },
+  divide: { by: { type: "Float", kind: "param" } },
+};
+
+// Control-flow directives — exempt from spec validation, keep raw extraction
+const CONTROL_FLOW_DIRECTIVES = new Set(["skip", "include", "when"]);
+
+export const analyzeDirectives = (
+  directives: readonly DirectiveNode[],
+  generatedVariables?: VariableDefinition[],
+): DirectiveAnalysis[] =>
+  directives.map((directive) => {
+    const name = directive.name.value;
+
+    // Control-flow directives: extract raw (no parameterization, no validation)
+    if (CONTROL_FLOW_DIRECTIVES.has(name)) {
+      return {
+        name,
+        ...(directive.arguments &&
+          directive.arguments.length > 0 && {
+            arguments: Object.fromEntries(
+              directive.arguments.map((arg) => [arg.name.value, extractArgumentValue(arg.value)]),
+            ),
+          }),
+      };
+    }
+
+    // Spec'd transform directives: validate arg types and parameterize param-kind args
+    const spec = DIRECTIVE_ARG_SPEC[name];
+    if (spec && directive.arguments) {
+      const args: Record<string, unknown> = {};
+      for (const arg of directive.arguments) {
+        const argName = arg.name.value;
+        const argSpec = spec[argName];
+        if (!argSpec) {
+          throw new Error(`Unknown argument "${argName}" for directive @${name}`);
+        }
+        if (argSpec.kind === "enum") {
+          const value = extractArgumentValue(arg.value);
+          if (argSpec.values && !argSpec.values.includes(value as string)) {
+            throw new Error(
+              `Invalid value "${value}" for @${name}(${argName}:). Expected one of: ${argSpec.values.join(", ")}`,
+            );
+          }
+          args[argName] = value;
+        } else {
+          // param kind: parameterize through generatedVariables
+          args[argName] = extractArgumentValue(arg.value, generatedVariables);
+        }
+      }
+      return { name, arguments: args };
+    }
+
+    // No-arg transform directives (uppercase, trim, ceil, floor, abs, lowercase, ltrim, rtrim)
+    // or unknown directives: extract raw with no validation
+    if (directive.arguments && directive.arguments.length > 0) {
+      return {
+        name,
+        arguments: Object.fromEntries(
+          directive.arguments.map((arg) => [arg.name.value, extractArgumentValue(arg.value)]),
+        ),
+      };
+    }
+    return { name };
+  });

package/src/analyzeQuery/index.ts

@@ -0,0 +1,66 @@
+import { parse } from "graphql";
+
+import type { DocumentNode, GraphQLSchema } from "graphql";
+import type { MergedEntities } from "../configuration/getSchemas/mergeEntities";
+import type { AnalysisResult, SelectionAnalysis, VariableDefinition } from "./types";
+
+import { analyzeFragment } from "./analyzers/fragmentAnalyzer";
+import { analyzeOperation } from "./analyzers/operationAnalyzer";
+
+/**
+ * Tag each top-level field with its source from the resolver registry
+ */
+const tagFieldsWithSource = (
+  fields: SelectionAnalysis[],
+  entities: MergedEntities,
+): SelectionAnalysis[] => {
+  return fields.map((field) => ({
+    ...field,
+    source: entities.getResolverSource(field.name),
+  }));
+};
+
+// Function to analyze a GraphQL query
+export function analyzeQuery(
+  query: string,
+  entities: MergedEntities,
+  gqlSchema: GraphQLSchema,
+): AnalysisResult {
+  let ast: DocumentNode | null;
+
+  const generatedVariables: VariableDefinition[] = [];
+
+  const result: AnalysisResult & { errors?: { message: string }[] } = {
+    operations: [],
+    fragments: [],
+  };
+
+  try {
+    ast = parse(query);
+  } catch (error) {
+    result.errors = [
+      {
+        message: `Error parsing query: ${error instanceof Error ? error.message : String(error)}`,
+      },
+    ];
+    return result;
+  }
+
+  ast.definitions.forEach((def) => {
+    if (def.kind === "OperationDefinition") {
+      const operationAnalysis = analyzeOperation(def, entities, gqlSchema, generatedVariables);
+
+      if (operationAnalysis) {
+        // Tag top-level fields with their source
+        operationAnalysis.fields = tagFieldsWithSource(operationAnalysis.fields, entities);
+        result.operations.push(operationAnalysis);
+      }
+    } else if (def.kind === "FragmentDefinition") {
+      const fragmentAnalysis = analyzeFragment(def, entities, gqlSchema, generatedVariables);
+
+      result.fragments.push(fragmentAnalysis);
+    }
+  });
+
+  return result;
+}