Merge branch 'main' into benjie/incremental-common

Author: benjie

.github/algorithm-format-check.mjs

@@ -2,6 +2,9 @@ import { readFile, readdir } from "node:fs/promises";
 
 const SPEC_DIR = new URL("../spec", import.meta.url).pathname;
 
+/** @see {@link https://spec-md.com/#sec-Value-Literals} */
+const valueLiteralsRegexp = /\{((?:[^{}]|(?:\{[^{}]*\}))+)\}/g;
+
 process.exitCode = 0;
 const filenames = await readdir(SPEC_DIR);
 for (const filename of filenames) {
@@ -72,6 +75,33 @@ for (const filename of filenames) {
             console.log();
             process.exitCode = 1;
           }
+
+          const stepWithoutValueLiterals = step.replace(
+            valueLiteralsRegexp,
+            ""
+          );
+          if (stepWithoutValueLiterals.match(/\b[A-Z][A-Za-z0-9]+\(/)) {
+            console.log(
+              `Bad formatting of '${algorithmName}' step (algorithm call should be wrapped in braces: \`{MyAlgorithm(a, b, c)}\`) in '${filename}':`
+            );
+            console.dir(step);
+            console.log();
+            process.exitCode = 1;
+          }
+
+          const valueLiterals = step.matchAll(valueLiteralsRegexp, "");
+          for (const lit of valueLiterals) {
+            const inner = lit[1];
+            if (inner.includes("{")) {
+              console.log(
+                `Bad formatting of '${algorithmName}' step (algorithm call should not contain braces: \`${lit}\`) in '${filename}':`
+              );
+              console.dir(step);
+              console.log();
+              process.exitCode = 1;
+            }
+          }
+
           const trimmedInnerLine = step.replace(/\s+/g, " ");
           if (
             trimmedInnerLine.match(

spec/Section 2 -- Language.md

@@ -466,9 +466,9 @@ These two operations are semantically identical:
 
 Alias : Name :
 
-:: A _response key_ is the key in the response object which correlates with a
-field's result. By default the response key will use the field's name; however,
-you can define a different response key by specifying an alias.
+:: A _response name_ is the key in the response object which correlates with a
+field's result. By default the response name will use the field's name; however,
+you can define a different response name by specifying an alias.
 
 In this example, we can fetch two profile pictures of different sizes and ensure
 the resulting response object will not have duplicate keys:
@@ -1254,7 +1254,7 @@ Type : Name
 
 - Let {name} be the string value of {Name}.
 - Let {type} be the type defined in the Schema named {name}.
-- {type} must not be {null}.
+- {type} must exist.
 - Return {type}.
 
 Type : [ Type ]

spec/Section 3 -- Type System.md

@@ -329,8 +329,8 @@ A GraphQL schema may describe that a field represents a list of another type;
 the `List` type is provided for this reason, and wraps another type.
 
 Similarly, the `Non-Null` type wraps another type, and denotes that the
-resulting value will never be {null} (and that a _field error_ cannot result in
-a {null} value).
+resulting value will never be {null} (and that an _execution error_ cannot
+result in a {null} value).
 
 These two types are referred to as "wrapping types"; non-wrapping types are
 referred to as "named types". A wrapping type has an underlying named type,
@@ -351,7 +351,7 @@ IsInputType(type):
 
 - If {type} is a List type or Non-Null type:
   - Let {unwrappedType} be the unwrapped type of {type}.
-  - Return IsInputType({unwrappedType}).
+  - Return {IsInputType(unwrappedType)}.
 - If {type} is a Scalar, Enum, or Input Object type:
   - Return {true}.
 - Return {false}.
@@ -360,7 +360,7 @@ IsOutputType(type):
 
 - If {type} is a List type or Non-Null type:
   - Let {unwrappedType} be the unwrapped type of {type}.
-  - Return IsOutputType({unwrappedType}).
+  - Return {IsOutputType(unwrappedType)}.
 - If {type} is a Scalar, Object, Interface, Union, or Enum type:
   - Return {true}.
 - Return {false}.
@@ -461,14 +461,14 @@ more guidance.
 
 A GraphQL service, when preparing a field of a given scalar type, must uphold
 the contract the scalar type describes, either by coercing the value or
-producing a _field error_ if a value cannot be coerced or if coercion may result
-in data loss.
+producing an _execution error_ if a value cannot be coerced or if coercion may
+result in data loss.
 
 A GraphQL service may decide to allow coercing different internal types to the
 expected return type. For example when coercing a field of type {Int} a boolean
 {true} value may produce {1} or a string value {"123"} may be parsed as base-10
 {123}. However if internal type coercion cannot be reasonably performed without
-losing information, then it must raise a _field error_.
+losing information, then it must raise an _execution error_.
 
 Since this coercion behavior is not observable to clients of the GraphQL
 service, the precise rules of coercion are left to the implementation. The only
@@ -513,15 +513,15 @@ Fields returning the type {Int} expect to encounter 32-bit integer internal
 values.
 
 GraphQL services may coerce non-integer internal values to integers when
-reasonable without losing information, otherwise they must raise a _field
+reasonable without losing information, otherwise they must raise an _execution
 error_. Examples of this may include returning `1` for the floating-point number
 `1.0`, or returning `123` for the string `"123"`. In scenarios where coercion
-may lose data, raising a field error is more appropriate. For example, a
-floating-point number `1.2` should raise a field error instead of being
+may lose data, raising an execution error is more appropriate. For example, a
+floating-point number `1.2` should raise an execution error instead of being
 truncated to `1`.
 
 If the integer internal value represents a value less than -2<sup>31</sup> or
-greater than or equal to 2<sup>31</sup>, a _field error_ should be raised.
+greater than or equal to 2<sup>31</sup>, an _execution error_ should be raised.
 
 **Input Coercion**
 
@@ -548,12 +548,12 @@ Fields returning the type {Float} expect to encounter double-precision
 floating-point internal values.
 
 GraphQL services may coerce non-floating-point internal values to {Float} when
-reasonable without losing information, otherwise they must raise a _field
+reasonable without losing information, otherwise they must raise an _execution
 error_. Examples of this may include returning `1.0` for the integer number `1`,
 or `123.0` for the string `"123"`.
 
 Non-finite floating-point internal values ({NaN} and {Infinity}) cannot be
-coerced to {Float} and must raise a _field error_.
+coerced to {Float} and must raise an _execution error_.
 
 **Input Coercion**
 
@@ -579,9 +579,9 @@ that representation must be used to serialize this type.
 Fields returning the type {String} expect to encounter Unicode string values.
 
 GraphQL services may coerce non-string raw values to {String} when reasonable
-without losing information, otherwise they must raise a _field error_. Examples
-of this may include returning the string `"true"` for a boolean true value, or
-the string `"1"` for the integer `1`.
+without losing information, otherwise they must raise an _execution error_.
+Examples of this may include returning the string `"true"` for a boolean true
+value, or the string `"1"` for the integer `1`.
 
 **Input Coercion**
 
@@ -600,8 +600,8 @@ representation of the integers `1` and `0`.
 Fields returning the type {Boolean} expect to encounter boolean internal values.
 
 GraphQL services may coerce non-boolean raw values to {Boolean} when reasonable
-without losing information, otherwise they must raise a _field error_. Examples
-of this may include returning `true` for non-zero numbers.
+without losing information, otherwise they must raise an _execution error_.
+Examples of this may include returning `true` for non-zero numbers.
 
 **Input Coercion**
 
@@ -623,7 +623,7 @@ large 128-bit random numbers, to base64 encoded values, or string values of a
 format like [GUID](https://en.wikipedia.org/wiki/Globally_unique_identifier).
 
 GraphQL services should coerce as appropriate given the ID formats they expect.
-When coercion is not possible they must raise a _field error_.
+When coercion is not possible they must raise an _execution error_.
 
 **Input Coercion**
 
@@ -1492,7 +1492,7 @@ enum Direction {
 **Result Coercion**
 
 GraphQL services must return one of the defined set of possible values. If a
-reasonable coercion is not possible they must raise a _field error_.
+reasonable coercion is not possible they must raise an _execution error_.
 
 **Input Coercion**
 
@@ -1548,8 +1548,9 @@ Fields may accept arguments to configure their behavior. These inputs are often
 scalars or enums, but they sometimes need to represent more complex values.
 
 A GraphQL Input Object defines a set of input fields; the input fields are
-either scalars, enums, or other input objects. This allows arguments to accept
-arbitrarily complex structs.
+scalars, enums, other input objects, or any wrapping type whose underlying base
+type is one of those three. This allows arguments to accept arbitrarily complex
+structs.
 
 In this example, an Input Object called `Point2D` describes `x` and `y` inputs:
 
@@ -1654,10 +1655,10 @@ is constructed with the following rules:
 
 - If a variable is provided for an input object field, the runtime value of that
   variable must be used. If the runtime value is {null} and the field type is
-  non-null, a _field error_ must be raised. If no runtime value is provided, the
-  variable definition's default value should be used. If the variable definition
-  does not provide a default value, the input object field definition's default
-  value should be used.
+  non-null, an _execution error_ must be raised. If no runtime value is
+  provided, the variable definition's default value should be used. If the
+  variable definition does not provide a default value, the input object field
+  definition's default value should be used.
 
 Following are examples of input coercion for an input object type with a
 `String` field `a` and a required (non-null) `Int!` field `b`:
@@ -1742,19 +1743,19 @@ brackets like this: `pets: [Pet]`. Nesting lists is allowed: `matrix: [[Int]]`.
 
 GraphQL services must return an ordered list as the result of a list type. Each
 item in the list must be the result of a result coercion of the item type. If a
-reasonable coercion is not possible it must raise a _field error_. In
+reasonable coercion is not possible it must raise an _execution error_. In
 particular, if a non-list is returned, the coercion should fail, as this
 indicates a mismatch in expectations between the type system and the
 implementation.
 
 If a list's item type is nullable, then errors occurring during preparation or
 coercion of an individual item in the list must result in a the value {null} at
-that position in the list along with a _field error_ added to the response. If a
-list's item type is non-null, a field error occurring at an individual item in
-the list must result in a field error for the entire list.
+that position in the list along with an _execution error_ added to the response.
+If a list's item type is non-null, an execution error occurring at an individual
+item in the list must result in an execution error for the entire list.
 
-Note: See [Handling Field Errors](#sec-Handling-Field-Errors) for more about
-this behavior.
+Note: See [Handling Execution Errors](#sec-Handling-Execution-Errors) for more
+about this behavior.
 
 **Input Coercion**
 
@@ -1812,12 +1813,13 @@ always optional and non-null types are always required.
 In all of the above result coercions, {null} was considered a valid value. To
 coerce the result of a Non-Null type, the coercion of the wrapped type should be
 performed. If that result was not {null}, then the result of coercing the
-Non-Null type is that result. If that result was {null}, then a _field error_
-must be raised.
+Non-Null type is that result. If that result was {null}, then an _execution
+error_ must be raised.
 
-Note: When a _field error_ is raised on a non-null value, the error propagates
-to the parent field. For more information on this process, see
-[Errors and Non-Null Fields](#sec-Executing-Selection-Sets.Errors-and-Non-Null-Fields)
+Note: When an _execution error_ is raised on a non-null _response position_, the
+error propagates to the parent _response position_. For more information on this
+process, see
+[Errors and Non-Null Types](#sec-Executing-Selection-Sets.Errors-and-Non-Null-Types)
 within the Execution section.
 
 **Input Coercion**
@@ -2035,19 +2037,20 @@ directive @invalidExample(arg: String @invalidExample) on ARGUMENT_DEFINITION
 Note: The order in which directives appear may be significant, including
 repeatable directives.
 
-**Validation**
+**Type Validation**
 
-1. A directive definition must not contain the use of a directive which
+1. A Directive definition must include at least one DirectiveLocation.
+2. A Directive definition must not contain the use of a Directive which
    references itself directly.
-2. A directive definition must not contain the use of a directive which
+3. A Directive definition must not contain the use of a Directive which
    references itself indirectly by referencing a Type or Directive which
-   transitively includes a reference to this directive.
-3. The directive must not have a name which begins with the characters {"\_\_"}
+   transitively includes a reference to this Directive.
+4. The Directive must not have a name which begins with the characters {"\_\_"}
    (two underscores).
-4. For each argument of the directive:
+5. For each argument of the Directive:
    1. The argument must not have a name which begins with the characters
       {"\_\_"} (two underscores).
-   2. The argument must have a unique name within that directive; no two
+   2. The argument must have a unique name within that Directive; no two
       arguments may share the same name.
    3. The argument must accept a type where {IsInputType(argumentType)} returns
       {true}.

spec/Section 5 -- Validation.md

@@ -418,7 +418,7 @@ fragment directFieldSelectionOnUnion on CatOrDog {
 
 FieldsInSetCanMerge(set):
 
-- Let {fieldsForName} be the set of selections with a given response name in
+- Let {fieldsForName} be the set of selections with a given _response name_ in
   {set} including visiting fragments and inline fragments.
 - Given each pair of distinct members {fieldA} and {fieldB} in {fieldsForName}:
   - {SameResponseShape(fieldA, fieldB)} must be true.
@@ -450,7 +450,7 @@ SameResponseShape(fieldA, fieldB):
 - Assert: {typeB} is an object, union or interface type.
 - Let {mergedSet} be the result of adding the selection set of {fieldA} and the
   selection set of {fieldB}.
-- Let {fieldsForName} be the set of selections with a given response name in
+- Let {fieldsForName} be the set of selections with a given _response name_ in
   {mergedSet} including visiting fragments and inline fragments.
 - Given each pair of distinct members {subfieldA} and {subfieldB} in
   {fieldsForName}:
@@ -462,10 +462,10 @@ type that is either an Object, Interface or Union type.
 
 **Explanatory Text**
 
-If multiple field selections with the same response names are encountered during
-execution, the field and arguments to execute and the resulting value should be
-unambiguous. Therefore any two field selections which might both be encountered
-for the same object are only valid if they are equivalent.
+If multiple field selections with the same _response name_ are encountered
+during execution, the field and arguments to execute and the resulting value
+should be unambiguous. Therefore any two field selections which might both be
+encountered for the same object are only valid if they are equivalent.
 
 During execution, the simultaneous execution of fields with the same response
 name is accomplished by {CollectSubfields()}.
@@ -1304,15 +1304,26 @@ fragment resourceFragment on Resource {
 
 **Formal Specification**
 
-- For each input Value {value} in the document:
+- For each literal Input Value {value} in the document:
   - Let {type} be the type expected in the position {value} is found.
-  - {value} must be coercible to {type}.
+  - {value} must be coercible to {type} (with the assumption that any
+    {variableUsage} nested within {value} will represent a runtime value valid
+    for usage in its position).
 
 **Explanatory Text**
 
 Literal values must be compatible with the type expected in the position they
 are found as per the coercion rules defined in the Type System chapter.
 
+Note: A {ListValue} or {ObjectValue} may contain nested Input Values, some of
+which may be a variable usage. The
+[All Variable Usages Are Allowed](#sec-All-Variable-Usages-Are-Allowed)
+validation rule ensures that each {variableUsage} is of a type allowed in its
+position. The [Coercing Variable Values](#sec-Coercing-Variable-Values)
+algorithm ensures runtime values for variables coerce correctly. Therefore, for
+the purposes of the "coercible" assertion in this validation rule, we can assume
+the runtime value of each {variableUsage} is valid for usage in its position.
+
 The type expected in a position includes the type defined by the argument a
 value is provided for, the type defined by an input object field a value is
 provided for, and the type of a variable definition a default value is provided
@@ -2010,4 +2021,4 @@ query booleanArgQueryWithDefault($booleanArg: Boolean = true) {
 ```
 
 Note: The value {null} could still be provided to such a variable at runtime. A
-non-null argument must raise a _field error_ if provided a {null} value.
+non-null argument must raise an _execution error_ if provided a {null} value.