Merge branch 'main' into oneof-v2

Author: benjie

.github/algorithm-format-check.mjs

@@ -23,13 +23,16 @@ for (const filename of filenames) {
     {
       // Is it an algorithm definition?
       const matches = line.match(/^([a-z0-9A-Z]+)(\s*)\(([^)]*)\)(\s*):(\s*)$/);
+      const grammarMatches =
+        filename === "Section 2 -- Language.md" &&
+        line.match(/^([A-Za-z0-9]+) :\s+((\S).*)$/);
       if (matches) {
         const [, algorithmName, ns1, _args, ns2, ns3] = matches;
         if (ns1 || ns2 || ns3) {
           console.log(
             `Bad whitespace in definition of ${algorithmName} in '${filename}':`
           );
-          console.log(line);
+          console.dir(line);
           console.log();
           process.exitCode = 1;
         }
@@ -47,7 +50,7 @@ for (const filename of filenames) {
               console.log(
                 `Bad algorithm ${algorithmName} step in '${filename}':`
               );
-              console.log(step);
+              console.dir(step);
               console.log();
               process.exitCode = 1;
             }
@@ -57,15 +60,15 @@ for (const filename of filenames) {
             console.log(
               `Bad formatting for '${algorithmName}' step (does not end in '.' or ':') in '${filename}':`
             );
-            console.log(step);
+            console.dir(step);
             console.log();
             process.exitCode = 1;
           }
           if (step.match(/^\s*(-|[0-9]\.)\s+[a-z]/)) {
             console.log(
               `Bad formatting of '${algorithmName}' step (should start with a capital) in '${filename}':`
             );
-            console.log(step);
+            console.dir(step);
             console.log();
             process.exitCode = 1;
           }
@@ -79,7 +82,67 @@ for (const filename of filenames) {
             console.log(
               `Potential bad formatting of '${algorithmName}' step (true/false/null should be wrapped in curly braces, e.g. '{true}') in '${filename}':`
             );
-            console.log(step);
+            console.dir(step);
+            console.log();
+            process.exitCode = 1;
+          }
+        }
+      } else if (grammarMatches) {
+        // This is super loosey-goosey
+        const [, grammarName, rest] = grammarMatches;
+        if (rest.trim() === "one of") {
+          // Still grammar, not algorithm
+          continue;
+        }
+        if (rest.trim() === "" && lines[i + 1] !== "") {
+          console.log(
+            `No empty space after grammar ${grammarName} header in '${filename}'`
+          );
+          console.log();
+          process.exitCode = 1;
+        }
+        if (!lines[i + 2].startsWith("- ")) {
+          // Not an algorithm; probably more grammar
+          continue;
+        }
+        for (let j = i + 2; j < l; j++) {
+          const step = lines[j];
+          if (!step.match(/^\s*(-|[0-9]+\.) /)) {
+            if (step !== "") {
+              console.log(`Bad grammar ${grammarName} step in '${filename}':`);
+              console.dir(step);
+              console.log();
+              process.exitCode = 1;
+            }
+            break;
+          }
+          if (!step.match(/[.:]$/)) {
+            console.log(
+              `Bad formatting for '${grammarName}' step (does not end in '.' or ':') in '${filename}':`
+            );
+            console.dir(step);
+            console.log();
+            process.exitCode = 1;
+          }
+          if (step.match(/^\s*(-|[0-9]\.)\s+[a-z]/)) {
+            console.log(
+              `Bad formatting of '${grammarName}' step (should start with a capital) in '${filename}':`
+            );
+            console.dir(step);
+            console.log();
+            process.exitCode = 1;
+          }
+          const trimmedInnerLine = step.replace(/\s+/g, " ");
+          if (
+            trimmedInnerLine.match(
+              /(?:[rR]eturn|is (?:not )?)(true|false|null)\b/
+            ) &&
+            !trimmedInnerLine.match(/null or empty/)
+          ) {
+            console.log(
+              `Potential bad formatting of '${grammarName}' step (true/false/null should be wrapped in curly braces, e.g. '{true}') in '${filename}':`
+            );
+            console.dir(step);
             console.log();
             process.exitCode = 1;
           }

cspell.yml

@@ -23,3 +23,7 @@ words:
   - zuckerberg
   - brontie
   - oneOf
+# Forbid Alternative spellings
+flagWords:
+  - implementor
+  - implementors

spec/Section 2 -- Language.md

@@ -291,7 +291,8 @@ There are three types of operations that GraphQL models:
 - subscription - a long-lived request that fetches data in response to source
   events.
 
-Each operation is represented by an optional operation name and a selection set.
+Each operation is represented by an optional operation name and a _selection
+set_.
 
 For example, this mutation operation might "like" a story and then retrieve the
 new number of likes:
@@ -337,6 +338,9 @@ An operation selects the set of information it needs, and will receive exactly
 that information and nothing more, avoiding over-fetching and under-fetching
 data.
 
+:: A _selection set_ defines an ordered set of selections (fields, fragment
+spreads and inline fragments) against an object, union or interface type.
+
 ```graphql example
 {
   id
@@ -346,14 +350,14 @@ data.
 ```
 
 In this query operation, the `id`, `firstName`, and `lastName` fields form a
-selection set. Selection sets may also contain fragment references.
+_selection set_. Selection sets may also contain fragment references.
 
 ## Fields
 
 Field : Alias? Name Arguments? Directives? SelectionSet?
 
-A selection set is primarily composed of fields. A field describes one discrete
-piece of information available to request within a selection set.
+A _selection set_ is primarily composed of fields. A field describes one
+discrete piece of information available to request within a selection set.
 
 Some fields describe complex data or relationships to other data. In order to
 further explore this data, a field may itself contain a selection set, allowing
@@ -381,7 +385,7 @@ down to scalar values.
 }
 ```
 
-Fields in the top-level selection set of an operation often represent some
+Fields in the top-level _selection set_ of an operation often represent some
 information that is globally accessible to your application and its current
 viewer. Some typical examples of these top fields include references to a
 current logged-in viewer, or accessing certain types of data referenced by a
@@ -667,9 +671,9 @@ be present and `likers` will not. Conversely when the result is a `Page`,
 
 InlineFragment : ... TypeCondition? Directives? SelectionSet
 
-Fragments can also be defined inline within a selection set. This is useful for
-conditionally including fields based on a type condition or applying a directive
-to a selection set.
+Fragments can also be defined inline within a _selection set_. This is useful
+for conditionally including fields based on a type condition or applying a
+directive to a selection set.
 
 This feature of standard fragment inclusion was demonstrated in the
 `query FragmentTyping` example above. We could accomplish the same thing using

spec/Section 3 -- Type System.md

@@ -677,8 +677,8 @@ operations, Objects describe the intermediate levels.
 GraphQL Objects represent a list of named fields, each of which yield a value of
 a specific type. Object values should be serialized as ordered maps, where the
 selected field names (or aliases) are the keys and the result of evaluating the
-field is the value, ordered by the order in which they appear in the selection
-set.
+field is the value, ordered by the order in which they appear in the _selection
+set_.
 
 All fields defined within an Object type must not have a name which begins with
 {"\_\_"} (two underscores), as this is used exclusively by GraphQL's
@@ -1026,7 +1026,7 @@ Object, Interface, or Union type).
 ### Field Deprecation
 
 Fields in an object may be marked as deprecated as deemed necessary by the
-application. It is still legal to include these fields in a selection set (to
+application. It is still legal to include these fields in a _selection set_ (to
 ensure existing clients are not broken by the change), but the fields should be
 appropriately treated in documentation and tooling.
 
@@ -1142,7 +1142,7 @@ type Contact {
 }
 ```
 
-This allows us to write a selection set for a `Contact` that can select the
+This allows us to write a _selection set_ for a `Contact` that can select the
 common fields.
 
 ```graphql example
@@ -1881,9 +1881,9 @@ to denote a field that uses a Non-Null type like this: `name: String!`.
 
 **Nullable vs. Optional**
 
-Fields are _always_ optional within the context of a selection set, a field may
-be omitted and the selection set is still valid (so long as the selection set
-does not become empty). However fields that return Non-Null types will never
+Fields are _always_ optional within the context of a _selection set_, a field
+may be omitted and the selection set is still valid (so long as the selection
+set does not become empty). However fields that return Non-Null types will never
 return the value {null} if queried.
 
 Inputs (such as field arguments), are always optional by default. However a

spec/Section 4 -- Introspection.md

@@ -68,7 +68,7 @@ underscores {"\_\_"}.
 
 ## Type Name Introspection
 
-GraphQL supports type name introspection within any selection set in an
+GraphQL supports type name introspection within any _selection set_ in an
 operation, with the single exception of selections at the root of a subscription
 operation. Type name introspection is accomplished via the meta-field
 `__typename: String!` on any Object, Interface, or Union. It returns the name of

spec/Section 5 -- Validation.md

@@ -383,7 +383,7 @@ fragment aliasedLyingFieldTargetNotDefined on Dog {
 ```
 
 For interfaces, direct field selection can only be done on fields. Fields of
-concrete implementors are not relevant to the validity of the given
+concrete implementers are not relevant to the validity of the given
 interface-typed selection set.
 
 For example, the following is valid:
@@ -397,7 +397,7 @@ fragment interfaceFieldSelection on Pet {
 and the following is invalid:
 
 ```graphql counter-example
-fragment definedOnImplementorsButNotInterface on Pet {
+fragment definedOnImplementersButNotInterface on Pet {
   nickname
 }
 ```
@@ -467,7 +467,8 @@ SameResponseShape(fieldA, fieldB):
 - If {typeA} or {typeB} is Scalar or Enum:
   - If {typeA} and {typeB} are the same type return {true}, otherwise return
     {false}.
-- Assert: {typeA} and {typeB} are both composite types.
+- Assert: {typeA} is an object, union or interface type.
+- 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
@@ -476,6 +477,9 @@ SameResponseShape(fieldA, fieldB):
   - If {SameResponseShape(subfieldA, subfieldB)} is {false}, return {false}.
 - Return {true}.
 
+Note: In prior versions of the spec the term "composite" was used to signal a
+type that is either an Object, Interface or Union type.
+
 **Explanatory Text**
 
 If multiple field selections with the same response names are encountered during
@@ -931,7 +935,7 @@ fragment inlineNotExistingType on Dog {
 }
 ```
 
-#### Fragments on Composite Types
+#### Fragments on Object, Interface or Union Types
 
 **Formal Specification**