From d73699a63cf4a7511963a012b61beb13a298428e Mon Sep 17 00:00:00 2001
From: Ivan Goncharov <ivan.goncharov.ua@gmail.com>
Date: Fri, 1 Oct 2021 14:43:28 +0300
Subject: [PATCH] Improve documentation of validation rules

* Added missing documentation
* Added links to GraphQL spec
---
 src/validation/rules/ExecutableDefinitionsRule.ts        | 2 ++
 src/validation/rules/FieldsOnCorrectTypeRule.ts          | 2 ++
 src/validation/rules/FragmentsOnCompositeTypesRule.ts    | 2 ++
 src/validation/rules/KnownArgumentNamesRule.ts           | 3 +++
 src/validation/rules/KnownDirectivesRule.ts              | 2 ++
 src/validation/rules/KnownFragmentNamesRule.ts           | 2 ++
 src/validation/rules/KnownTypeNamesRule.ts               | 2 ++
 src/validation/rules/LoneAnonymousOperationRule.ts       | 2 ++
 src/validation/rules/NoFragmentCyclesRule.ts             | 8 ++++++++
 src/validation/rules/NoUndefinedVariablesRule.ts         | 2 ++
 src/validation/rules/NoUnusedFragmentsRule.ts            | 2 ++
 src/validation/rules/NoUnusedVariablesRule.ts            | 2 ++
 src/validation/rules/OverlappingFieldsCanBeMergedRule.ts | 2 ++
 src/validation/rules/SingleFieldSubscriptionsRule.ts     | 2 ++
 src/validation/rules/UniqueArgumentNamesRule.ts          | 2 ++
 src/validation/rules/UniqueDirectivesPerLocationRule.ts  | 2 ++
 src/validation/rules/UniqueFragmentNamesRule.ts          | 2 ++
 src/validation/rules/UniqueInputFieldNamesRule.ts        | 2 ++
 src/validation/rules/UniqueOperationNamesRule.ts         | 2 ++
 src/validation/rules/ValuesOfCorrectTypeRule.ts          | 2 ++
 src/validation/rules/VariablesAreInputTypesRule.ts       | 2 ++
 src/validation/rules/VariablesInAllowedPositionRule.ts   | 6 +++++-
 22 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/src/validation/rules/ExecutableDefinitionsRule.ts b/src/validation/rules/ExecutableDefinitionsRule.ts
index c446e000e1..1a6c21a91f 100644
--- a/src/validation/rules/ExecutableDefinitionsRule.ts
+++ b/src/validation/rules/ExecutableDefinitionsRule.ts
@@ -11,6 +11,8 @@ import type { ASTValidationContext } from '../ValidationContext';
  *
  * A GraphQL document is only valid for execution if all definitions are either
  * operation or fragment definitions.
+ *
+ * See https://spec.graphql.org/draft/#sec-Executable-Definitions
  */
 export function ExecutableDefinitionsRule(
   context: ASTValidationContext,
diff --git a/src/validation/rules/FieldsOnCorrectTypeRule.ts b/src/validation/rules/FieldsOnCorrectTypeRule.ts
index 1b2e066042..a0c9726646 100644
--- a/src/validation/rules/FieldsOnCorrectTypeRule.ts
+++ b/src/validation/rules/FieldsOnCorrectTypeRule.ts
@@ -26,6 +26,8 @@ import type { ValidationContext } from '../ValidationContext';
  *
  * A GraphQL document is only valid if all fields selected are defined by the
  * parent type, or are an allowed meta field such as __typename.
+ *
+ * See https://spec.graphql.org/draft/#sec-Field-Selections
  */
 export function FieldsOnCorrectTypeRule(
   context: ValidationContext,
diff --git a/src/validation/rules/FragmentsOnCompositeTypesRule.ts b/src/validation/rules/FragmentsOnCompositeTypesRule.ts
index 75f49158c7..487984ea1e 100644
--- a/src/validation/rules/FragmentsOnCompositeTypesRule.ts
+++ b/src/validation/rules/FragmentsOnCompositeTypesRule.ts
@@ -15,6 +15,8 @@ import type { ValidationContext } from '../ValidationContext';
  * Fragments use a type condition to determine if they apply, since fragments
  * can only be spread into a composite type (object, interface, or union), the
  * type condition must also be a composite type.
+ *
+ * See https://spec.graphql.org/draft/#sec-Fragments-On-Composite-Types
  */
 export function FragmentsOnCompositeTypesRule(
   context: ValidationContext,
diff --git a/src/validation/rules/KnownArgumentNamesRule.ts b/src/validation/rules/KnownArgumentNamesRule.ts
index d769fe4966..ab7471a1b6 100644
--- a/src/validation/rules/KnownArgumentNamesRule.ts
+++ b/src/validation/rules/KnownArgumentNamesRule.ts
@@ -18,6 +18,9 @@ import type {
  *
  * A GraphQL field is only valid if all supplied arguments are defined by
  * that field.
+ *
+ * See https://spec.graphql.org/draft/#sec-Argument-Names
+ * See https://spec.graphql.org/draft/#sec-Directives-Are-In-Valid-Locations
  */
 export function KnownArgumentNamesRule(context: ValidationContext): ASTVisitor {
   return {
diff --git a/src/validation/rules/KnownDirectivesRule.ts b/src/validation/rules/KnownDirectivesRule.ts
index 652bdde186..25a84e7a9c 100644
--- a/src/validation/rules/KnownDirectivesRule.ts
+++ b/src/validation/rules/KnownDirectivesRule.ts
@@ -21,6 +21,8 @@ import type {
  *
  * A GraphQL document is only valid if all `@directives` are known by the
  * schema and legally positioned.
+ *
+ * See https://spec.graphql.org/draft/#sec-Directives-Are-Defined
  */
 export function KnownDirectivesRule(
   context: ValidationContext | SDLValidationContext,
diff --git a/src/validation/rules/KnownFragmentNamesRule.ts b/src/validation/rules/KnownFragmentNamesRule.ts
index 0f3412bb45..78fb244684 100644
--- a/src/validation/rules/KnownFragmentNamesRule.ts
+++ b/src/validation/rules/KnownFragmentNamesRule.ts
@@ -9,6 +9,8 @@ import type { ValidationContext } from '../ValidationContext';
  *
  * A GraphQL document is only valid if all `...Fragment` fragment spreads refer
  * to fragments defined in the same document.
+ *
+ * See https://spec.graphql.org/draft/#sec-Fragment-spread-target-defined
  */
 export function KnownFragmentNamesRule(context: ValidationContext): ASTVisitor {
   return {
diff --git a/src/validation/rules/KnownTypeNamesRule.ts b/src/validation/rules/KnownTypeNamesRule.ts
index 61d8981c3b..a7645b4ca2 100644
--- a/src/validation/rules/KnownTypeNamesRule.ts
+++ b/src/validation/rules/KnownTypeNamesRule.ts
@@ -24,6 +24,8 @@ import type {
  *
  * A GraphQL document is only valid if referenced types (specifically
  * variable definitions and fragment conditions) are defined by the type schema.
+ *
+ * See https://spec.graphql.org/draft/#sec-Fragment-Spread-Type-Existence
  */
 export function KnownTypeNamesRule(
   context: ValidationContext | SDLValidationContext,
diff --git a/src/validation/rules/LoneAnonymousOperationRule.ts b/src/validation/rules/LoneAnonymousOperationRule.ts
index 617c80639f..07e0ac35d0 100644
--- a/src/validation/rules/LoneAnonymousOperationRule.ts
+++ b/src/validation/rules/LoneAnonymousOperationRule.ts
@@ -10,6 +10,8 @@ import type { ASTValidationContext } from '../ValidationContext';
  *
  * A GraphQL document is only valid if when it contains an anonymous operation
  * (the query short-hand) that it contains only that one operation definition.
+ *
+ * See https://spec.graphql.org/draft/#sec-Lone-Anonymous-Operation
  */
 export function LoneAnonymousOperationRule(
   context: ASTValidationContext,
diff --git a/src/validation/rules/NoFragmentCyclesRule.ts b/src/validation/rules/NoFragmentCyclesRule.ts
index eb91391731..0a33f4508d 100644
--- a/src/validation/rules/NoFragmentCyclesRule.ts
+++ b/src/validation/rules/NoFragmentCyclesRule.ts
@@ -10,6 +10,14 @@ import type { ASTVisitor } from '../../language/visitor';
 
 import type { ASTValidationContext } from '../ValidationContext';
 
+/**
+ * No fragment cycles
+ *
+ * The graph of fragment spreads must not form any cycles including spreading itself.
+ * Otherwise an operation could infinitely spread or infinitely execute on cycles in the underlying data.
+ *
+ * See https://spec.graphql.org/draft/#sec-Fragment-spreads-must-not-form-cycles
+ */
 export function NoFragmentCyclesRule(
   context: ASTValidationContext,
 ): ASTVisitor {
diff --git a/src/validation/rules/NoUndefinedVariablesRule.ts b/src/validation/rules/NoUndefinedVariablesRule.ts
index de1a84807f..36bfe049b4 100644
--- a/src/validation/rules/NoUndefinedVariablesRule.ts
+++ b/src/validation/rules/NoUndefinedVariablesRule.ts
@@ -9,6 +9,8 @@ import type { ValidationContext } from '../ValidationContext';
  *
  * A GraphQL operation is only valid if all variables encountered, both directly
  * and via fragment spreads, are defined by that operation.
+ *
+ * See https://spec.graphql.org/draft/#sec-All-Variable-Uses-Defined
  */
 export function NoUndefinedVariablesRule(
   context: ValidationContext,
diff --git a/src/validation/rules/NoUnusedFragmentsRule.ts b/src/validation/rules/NoUnusedFragmentsRule.ts
index 393f783d72..2047945463 100644
--- a/src/validation/rules/NoUnusedFragmentsRule.ts
+++ b/src/validation/rules/NoUnusedFragmentsRule.ts
@@ -13,6 +13,8 @@ import type { ASTValidationContext } from '../ValidationContext';
  *
  * A GraphQL document is only valid if all fragment definitions are spread
  * within operations, or spread within other fragments spread within operations.
+ *
+ * See https://spec.graphql.org/draft/#sec-Fragments-Must-Be-Used
  */
 export function NoUnusedFragmentsRule(
   context: ASTValidationContext,
diff --git a/src/validation/rules/NoUnusedVariablesRule.ts b/src/validation/rules/NoUnusedVariablesRule.ts
index c58c390f0b..b81fd07843 100644
--- a/src/validation/rules/NoUnusedVariablesRule.ts
+++ b/src/validation/rules/NoUnusedVariablesRule.ts
@@ -10,6 +10,8 @@ import type { ValidationContext } from '../ValidationContext';
  *
  * A GraphQL operation is only valid if all variables defined by an operation
  * are used, either directly or within a spread fragment.
+ *
+ * See https://spec.graphql.org/draft/#sec-All-Variables-Used
  */
 export function NoUnusedVariablesRule(context: ValidationContext): ASTVisitor {
   let variableDefs: Array<VariableDefinitionNode> = [];
diff --git a/src/validation/rules/OverlappingFieldsCanBeMergedRule.ts b/src/validation/rules/OverlappingFieldsCanBeMergedRule.ts
index f60c86a56e..e76b32f97c 100644
--- a/src/validation/rules/OverlappingFieldsCanBeMergedRule.ts
+++ b/src/validation/rules/OverlappingFieldsCanBeMergedRule.ts
@@ -53,6 +53,8 @@ function reasonMessage(reason: ConflictReasonMessage): string {
  * A selection set is only valid if all fields (including spreading any
  * fragments) either correspond to distinct response names or can be merged
  * without ambiguity.
+ *
+ * See https://spec.graphql.org/draft/#sec-Field-Selection-Merging
  */
 export function OverlappingFieldsCanBeMergedRule(
   context: ValidationContext,
diff --git a/src/validation/rules/SingleFieldSubscriptionsRule.ts b/src/validation/rules/SingleFieldSubscriptionsRule.ts
index 2d8fc39af2..74c0ef4af3 100644
--- a/src/validation/rules/SingleFieldSubscriptionsRule.ts
+++ b/src/validation/rules/SingleFieldSubscriptionsRule.ts
@@ -17,6 +17,8 @@ import type { ValidationContext } from '../ValidationContext';
  *
  * A GraphQL subscription is valid only if it contains a single root field and
  * that root field is not an introspection field.
+ *
+ * See https://spec.graphql.org/draft/#sec-Single-root-field
  */
 export function SingleFieldSubscriptionsRule(
   context: ValidationContext,
diff --git a/src/validation/rules/UniqueArgumentNamesRule.ts b/src/validation/rules/UniqueArgumentNamesRule.ts
index 73289efd2f..54b090c940 100644
--- a/src/validation/rules/UniqueArgumentNamesRule.ts
+++ b/src/validation/rules/UniqueArgumentNamesRule.ts
@@ -8,6 +8,8 @@ import type { ASTValidationContext } from '../ValidationContext';
  *
  * A GraphQL field or directive is only valid if all supplied arguments are
  * uniquely named.
+ *
+ * See https://spec.graphql.org/draft/#sec-Argument-Names
  */
 export function UniqueArgumentNamesRule(
   context: ASTValidationContext,
diff --git a/src/validation/rules/UniqueDirectivesPerLocationRule.ts b/src/validation/rules/UniqueDirectivesPerLocationRule.ts
index 85bea14969..99639508d3 100644
--- a/src/validation/rules/UniqueDirectivesPerLocationRule.ts
+++ b/src/validation/rules/UniqueDirectivesPerLocationRule.ts
@@ -19,6 +19,8 @@ import type {
  *
  * A GraphQL document is only valid if all non-repeatable directives at
  * a given location are uniquely named.
+ *
+ * See https://spec.graphql.org/draft/#sec-Directives-Are-Unique-Per-Location
  */
 export function UniqueDirectivesPerLocationRule(
   context: ValidationContext | SDLValidationContext,
diff --git a/src/validation/rules/UniqueFragmentNamesRule.ts b/src/validation/rules/UniqueFragmentNamesRule.ts
index 144e0e94d5..47e129e1ee 100644
--- a/src/validation/rules/UniqueFragmentNamesRule.ts
+++ b/src/validation/rules/UniqueFragmentNamesRule.ts
@@ -8,6 +8,8 @@ import type { ASTValidationContext } from '../ValidationContext';
  * Unique fragment names
  *
  * A GraphQL document is only valid if all defined fragments have unique names.
+ *
+ * See https://spec.graphql.org/draft/#sec-Fragment-Name-Uniqueness
  */
 export function UniqueFragmentNamesRule(
   context: ASTValidationContext,
diff --git a/src/validation/rules/UniqueInputFieldNamesRule.ts b/src/validation/rules/UniqueInputFieldNamesRule.ts
index cd6b1161c6..6aa585102d 100644
--- a/src/validation/rules/UniqueInputFieldNamesRule.ts
+++ b/src/validation/rules/UniqueInputFieldNamesRule.ts
@@ -13,6 +13,8 @@ import type { ASTValidationContext } from '../ValidationContext';
  *
  * A GraphQL input object value is only valid if all supplied fields are
  * uniquely named.
+ *
+ * See https://spec.graphql.org/draft/#sec-Input-Object-Field-Uniqueness
  */
 export function UniqueInputFieldNamesRule(
   context: ASTValidationContext,
diff --git a/src/validation/rules/UniqueOperationNamesRule.ts b/src/validation/rules/UniqueOperationNamesRule.ts
index 6051e91978..fb6b11cddd 100644
--- a/src/validation/rules/UniqueOperationNamesRule.ts
+++ b/src/validation/rules/UniqueOperationNamesRule.ts
@@ -8,6 +8,8 @@ import type { ASTValidationContext } from '../ValidationContext';
  * Unique operation names
  *
  * A GraphQL document is only valid if all defined operations have unique names.
+ *
+ * See https://spec.graphql.org/draft/#sec-Operation-Name-Uniqueness
  */
 export function UniqueOperationNamesRule(
   context: ASTValidationContext,
diff --git a/src/validation/rules/ValuesOfCorrectTypeRule.ts b/src/validation/rules/ValuesOfCorrectTypeRule.ts
index 6d5dc5c1ca..b6b2170884 100644
--- a/src/validation/rules/ValuesOfCorrectTypeRule.ts
+++ b/src/validation/rules/ValuesOfCorrectTypeRule.ts
@@ -26,6 +26,8 @@ import type { ValidationContext } from '../ValidationContext';
  *
  * A GraphQL document is only valid if all value literals are of the type
  * expected at their position.
+ *
+ * See https://spec.graphql.org/draft/#sec-Values-of-Correct-Type
  */
 export function ValuesOfCorrectTypeRule(
   context: ValidationContext,
diff --git a/src/validation/rules/VariablesAreInputTypesRule.ts b/src/validation/rules/VariablesAreInputTypesRule.ts
index 61fce41e8a..01db171a97 100644
--- a/src/validation/rules/VariablesAreInputTypesRule.ts
+++ b/src/validation/rules/VariablesAreInputTypesRule.ts
@@ -15,6 +15,8 @@ import type { ValidationContext } from '../ValidationContext';
  *
  * A GraphQL operation is only valid if all the variables it defines are of
  * input types (scalar, enum, or input object).
+ *
+ * See https://spec.graphql.org/draft/#sec-Variables-Are-Input-Types
  */
 export function VariablesAreInputTypesRule(
   context: ValidationContext,
diff --git a/src/validation/rules/VariablesInAllowedPositionRule.ts b/src/validation/rules/VariablesInAllowedPositionRule.ts
index bf4c8f8f7c..c167a3c5e9 100644
--- a/src/validation/rules/VariablesInAllowedPositionRule.ts
+++ b/src/validation/rules/VariablesInAllowedPositionRule.ts
@@ -17,7 +17,11 @@ import { isTypeSubTypeOf } from '../../utilities/typeComparators';
 import type { ValidationContext } from '../ValidationContext';
 
 /**
- * Variables passed to field arguments conform to type
+ * Variables in allowed position
+ *
+ * Variable usages must be compatible with the arguments they are passed to.
+ *
+ * See https://spec.graphql.org/draft/#sec-All-Variable-Usages-are-Allowed
  */
 export function VariablesInAllowedPositionRule(
   context: ValidationContext,