Merge branch 'main' into fragment-args-2024-amendments

Author: JoviDeCroock

.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) {
@@ -25,7 +28,7 @@ for (const filename of filenames) {
       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).*)$/);
+        line.match(/^([A-Za-z0-9]+) ::?\s+((\S).*)$/);
       if (matches) {
         const [, algorithmName, ns1, _args, ns2, ns3] = matches;
         if (ns1 || ns2 || ns3) {
@@ -64,14 +67,50 @@ for (const filename of filenames) {
             console.log();
             process.exitCode = 1;
           }
-          if (step.match(/^\s*(-|[0-9]\.)\s+[a-z]/)) {
+          if (step.match(/^\s*(-|[0-9]+\.)\s+[a-z]/)) {
             console.log(
               `Bad formatting of '${algorithmName}' step (should start with a capital) in '${filename}':`
             );
             console.dir(step);
             console.log();
             process.exitCode = 1;
           }
+          const assertMatch = step.match(/^\s*(-|[0-9]+\.)\s*Assert([^:])/);
+          if (assertMatch) {
+            console.log(
+              `Bad formatting of '${algorithmName}' step (Assert should be immediately followed by ':'; found '${assertMatch[2]}') in '${filename}':`
+            );
+            console.dir(step);
+            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(
@@ -101,6 +140,10 @@ for (const filename of filenames) {
           console.log();
           process.exitCode = 1;
         }
+        while (lines[i + 1].trim() !== "") {
+          // Continuation of definition
+          i++;
+        }
         if (!lines[i + 2].startsWith("- ")) {
           // Not an algorithm; probably more grammar
           continue;
@@ -146,6 +189,15 @@ for (const filename of filenames) {
             console.log();
             process.exitCode = 1;
           }
+          const assertMatch = step.match(/^\s*(-|[0-9]+\.)\s*Assert([^:])/);
+          if (assertMatch) {
+            console.log(
+              `Bad formatting of '${grammarName}' step (Assert should be immediately followed by ':'; found '${assertMatch[2]}') in '${filename}':`
+            );
+            console.dir(step);
+            console.log();
+            process.exitCode = 1;
+          }
         }
       }
     }

CONTRIBUTING.md

@@ -6,8 +6,9 @@ contributions.
 
 Contributions that do not change the interpretation of the spec but instead
 improve legibility, fix editorial errors, clear up ambiguity and improve
-examples are encouraged and are often merged by a spec editor with little
-process.
+examples are encouraged. These "editorial changes" will normally be given the
+["✏ Editorial" label](https://github.com/graphql/graphql-spec/issues?q=sort%3Aupdated-desc+is%3Aopen+label%3A%22%E2%9C%8F%EF%B8%8F+Editorial%22)
+and are often merged by a spec editor with little process.
 
 However, contributions that _do_ meaningfully change the interpretation of the
 spec must follow an RFC (Request For Comments) process led by a _champion_

README.md

@@ -1,4 +1,4 @@
-[![GraphQLConf 2024 Banner: September 10-12, San Francisco. Hosted by the GraphQL Foundation](https://github.com/user-attachments/assets/0203f10b-ae1e-4fe1-9222-6547fa2bbd5d)](https://graphql.org/conf/2024/?utm_source=github&utm_medium=graphql_spec&utm_campaign=readme)
+[![GraphQLConf 2025 Banner: September 08-10, Amsterdam. Hosted by the GraphQL Foundation](./assets/graphql.org_conf_2025_.png)](https://graphql.org/conf/2025/?utm_source=github&utm_medium=graphql_js&utm_campaign=readme)
 
 # GraphQL
 

STYLE_GUIDE.md

@@ -82,3 +82,25 @@ MyAlgorithm(argOne, argTwo):
     - Let {something} be {true}.
 - Return {something}.
 ```
+
+## Definitions
+
+For important terms, use
+[Spec Markdown definition paragraphs](https://spec-md.com/#sec-Definition-Paragraph).
+
+Definition paragraphs start with `::` and add the matching italicized term to
+the [specification index](https://spec.graphql.org/draft/#index), making it easy
+to reference them.
+
+## Tone of voice
+
+The GraphQL specification is a reference document and should use neutral and
+descriptive tone of voice.
+
+**Favor the present tense**
+
+The present tense is usually clearer and shorter:
+
+✅ Present: The client then sends a request to the server.
+
+❌ Future: The client will then send a request to the server.

assets/graphql.org_conf_2025_.png

@@ -21,13 +21,15 @@
     "suggest:format": "echo \"\nTo resolve this, run: $(tput bold)npm run format$(tput sgr0)\" && exit 1",
     "build": "./build.sh",
     "test:build": "spec-md --metadata spec/metadata.json spec/GraphQL.md > /dev/null",
-    "watch": "nodemon -e json,md --exec \"npm run build\""
+    "watch": "nodemon -e json,md --exec \"npm run build\"",
+    "update-appendix-c": "node scripts/update-appendix-c.mjs; prettier --write \"spec/Appendix C -- Built-in Definitions.md\""
   },
   "devDependencies": {
     "cspell": "5.9.1",
     "nodemon": "2.0.20",
     "prettier": "2.8.2",
-    "spec-md": "3.1.0"
+    "spec-md": "3.1.0",
+    "graphql": "^17.0.0-alpha.8"
   },
   "prettier": {
     "proseWrap": "always",

package-lock.json

@@ -0,0 +1,28 @@
+import { writeFile } from 'node:fs/promises';
+import { printIntrospectionSchema, buildSchema, specifiedScalarTypes, printType } from 'graphql';
+
+const FILE = './spec/Appendix C -- Specified Definitions.md';
+function printSpecifiedScalars() {
+  return specifiedScalarTypes
+    .map((type) => printType(type))
+    .join('\n\n');
+}
+
+const introspectionSchema = printIntrospectionSchema(buildSchema(`type Query { i: Int }`));
+const prefix = `
+# C. Appendix: Type System Definitions
+
+This appendix lists the specified type system definitions.
+
+The descriptions are non-normative. Implementations are recommended to use them
+for consistency but different descriptions are allowed.
+
+The order of types, fields, arguments, values and directives is non-normative.
+
+\`\`\`graphql
+`
+
+const suffix = `
+\`\`\`
+`
+await writeFile(FILE, prefix + printSpecifiedScalars() + '\n\n' + introspectionSchema + suffix);

package.json

@@ -214,5 +214,36 @@ Fibonacci(number):
 - Return {Fibonacci(previousNumber)} + {Fibonacci(previousPreviousNumber)}.
 
 Note: Algorithms described in this document are written to be easy to
-understand. Implementers are encouraged to include equivalent but optimized
-implementations.
+understand. Implementers are encouraged to include observably equivalent but
+optimized implementations.
+
+## Data Collections
+
+Algorithms within this specification refer to abstract data collection types to
+express normative structural, uniqueness, and ordering requirements. Temporary
+data collections internal to an algorithm use these types to best describe
+expected behavior, but implementers are encouraged to provide observably
+equivalent but optimized implementations. Implementations may use any data
+structure as long as the expected requirements are met.
+
+**List**
+
+:: A _list_ is an ordered collection of values which may contain duplicates. A
+value added to a list is ordered after existing values.
+
+**Set**
+
+:: A _set_ is a collection of values which must not contain duplicates.
+
+:: An _ordered set_ is a set which has a defined order. A value added to an
+ordered set, which does not already contain that value, is ordered after
+existing values.
+
+**Map**
+
+:: A _map_ is a collection of entries, each of which has a key and value. Each
+entry has a unique key, and can be directly referenced by that key.
+
+:: An _ordered map_ is a map which has a defined order. An entry added to an
+ordered map, which does not have an entry with that key, is ordered after
+existing entries.

scripts/update-appendix-c.mjs

@@ -133,6 +133,8 @@ lines and uniform indentation with {BlockStringValue()}.
 
 ## Document Syntax
 
+Description : StringValue
+
 Document : Definition+
 
 Definition :
@@ -149,7 +151,7 @@ ExecutableDefinition :
 
 OperationDefinition :
 
-- OperationType Name? VariablesDefinition? Directives? SelectionSet
+- Description? OperationType Name? VariablesDefinition? Directives? SelectionSet
 - SelectionSet
 
 OperationType : one of `query` `mutation` `subscription`
@@ -174,7 +176,7 @@ FragmentSpread : ... FragmentName Arguments? Directives?
 
 InlineFragment : ... TypeCondition? Directives? SelectionSet
 
-FragmentDefinition : fragment FragmentName VariablesDefinition? TypeCondition
+FragmentDefinition : Description? fragment FragmentName TypeCondition
 Directives? SelectionSet
 
 FragmentName : Name but not `on`
@@ -213,7 +215,8 @@ ObjectField[Const] : Name : Value[?Const]
 
 VariablesDefinition : ( VariableDefinition+ )
 
-VariableDefinition : Variable : Type DefaultValue? Directives[Const]?
+VariableDefinition : Description? Variable : Type DefaultValue?
+Directives[Const]?
 
 Variable : $ Name
 
@@ -268,8 +271,6 @@ SchemaExtension :
 
 RootOperationTypeDefinition : OperationType : NamedType
 
-Description : StringValue
-
 TypeDefinition :
 
 - ScalarTypeDefinition