Improve documentation of validation rules (graphql#3285)

IvanGoncharov · web-flow · commit 0c7165a5d0a7 · 2021-10-01T17:40:16.000+03:00
* Added missing documentation
* Added links to GraphQL spec
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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,

Original file line number	Diff line number	Diff line change
`@@ -11,6 +11,8 @@ import type { ASTValidationContext } from '../ValidationContext';`
`11`	`11`	`*`
`12`	`12`	`* A GraphQL document is only valid for execution if all definitions are either`
`13`	`13`	`* operation or fragment definitions.`
	`14`	`+ *`
	`15`	`+ * See https://spec.graphql.org/draft/#sec-Executable-Definitions`
`14`	`16`	`*/`
`15`	`17`	`export function ExecutableDefinitionsRule(`
`16`	`18`	`context: ASTValidationContext,`
Original file line number	Diff line number	Diff line change
`@@ -26,6 +26,8 @@ import type { ValidationContext } from '../ValidationContext';`
`26`	`26`	`*`
`27`	`27`	`* A GraphQL document is only valid if all fields selected are defined by the`
`28`	`28`	`* parent type, or are an allowed meta field such as __typename.`
	`29`	`+ *`
	`30`	`+ * See https://spec.graphql.org/draft/#sec-Field-Selections`
`29`	`31`	`*/`
`30`	`32`	`export function FieldsOnCorrectTypeRule(`
`31`	`33`	`context: ValidationContext,`
Original file line number	Diff line number	Diff line change
`@@ -21,6 +21,8 @@ import type {`
`21`	`21`	`*`
`22`	`22`	* A GraphQL document is only valid if all `@directives` are known by the
`23`	`23`	`* schema and legally positioned.`
	`24`	`+ *`
	`25`	`+ * See https://spec.graphql.org/draft/#sec-Directives-Are-Defined`
`24`	`26`	`*/`
`25`	`27`	`export function KnownDirectivesRule(`
`26`	`28`	`context: ValidationContext \| SDLValidationContext,`
Original file line number	Diff line number	Diff line change
`@@ -9,6 +9,8 @@ import type { ValidationContext } from '../ValidationContext';`
`9`	`9`	`*`
`10`	`10`	* A GraphQL document is only valid if all `...Fragment` fragment spreads refer
`11`	`11`	`* to fragments defined in the same document.`
	`12`	`+ *`
	`13`	`+ * See https://spec.graphql.org/draft/#sec-Fragment-spread-target-defined`
`12`	`14`	`*/`
`13`	`15`	`export function KnownFragmentNamesRule(context: ValidationContext): ASTVisitor {`
`14`	`16`	`return {`
Original file line number	Diff line number	Diff line change
`@@ -24,6 +24,8 @@ import type {`
`24`	`24`	`*`
`25`	`25`	`* A GraphQL document is only valid if referenced types (specifically`
`26`	`26`	`* variable definitions and fragment conditions) are defined by the type schema.`
	`27`	`+ *`
	`28`	`+ * See https://spec.graphql.org/draft/#sec-Fragment-Spread-Type-Existence`
`27`	`29`	`*/`
`28`	`30`	`export function KnownTypeNamesRule(`
`29`	`31`	`context: ValidationContext \| SDLValidationContext,`
Original file line number	Diff line number	Diff line change
`@@ -10,6 +10,8 @@ import type { ASTValidationContext } from '../ValidationContext';`
`10`	`10`	`*`
`11`	`11`	`* A GraphQL document is only valid if when it contains an anonymous operation`
`12`	`12`	`* (the query short-hand) that it contains only that one operation definition.`
	`13`	`+ *`
	`14`	`+ * See https://spec.graphql.org/draft/#sec-Lone-Anonymous-Operation`
`13`	`15`	`*/`
`14`	`16`	`export function LoneAnonymousOperationRule(`
`15`	`17`	`context: ASTValidationContext,`