Merge branch 'main' into subscription-single-root-field

.github/ISSUE_TEMPLATE.md

@@ -2,10 +2,15 @@
 
 Before creating your issue:
 
-* Have a question? Find community resources at https://graphql.org/community/
+- Have a question? Find community resources at https://graphql.org/community/
 
-* Find an editing mistake? Create a Pull Request with the edited fix! The Github UI allows you to edit files directly, find the source files at: https://github.com/graphql/graphql-spec/tree/master/spec
+- Find an editing mistake? Create a Pull Request with the edited fix! The Github
+  UI allows you to edit files directly, find the source files at:
+  https://github.com/graphql/graphql-spec/tree/master/spec
 
-* Improvements to documentation? Head over to https://github.com/graphql/graphql.github.io
+- Improvements to documentation? Head over to
+  https://github.com/graphql/graphql.github.io
 
-* Feature request? First read https://github.com/graphql/graphql-spec/blob/master/CONTRIBUTING.md and prefer creating a Pull Request!
+- Feature request? First read
+  https://github.com/graphql/graphql-spec/blob/master/CONTRIBUTING.md and prefer
+  creating a Pull Request!

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,3 +1,4 @@
 !!! IMPORTANT !!!
 
-Please Read https://github.com/graphql/graphql-spec/blob/master/CONTRIBUTING.md before creating a Pull Request.
+Please Read https://github.com/graphql/graphql-spec/blob/master/CONTRIBUTING.md
+before creating a Pull Request.

.github/algorithm-format-check.mjs

@@ -0,0 +1,177 @@
+import { readFile, readdir } from "node:fs/promises";
+
+const SPEC_DIR = new URL("../spec", import.meta.url).pathname;
+
+process.exitCode = 0;
+const filenames = await readdir(SPEC_DIR);
+for (const filename of filenames) {
+  if (!filename.endsWith(".md")) {
+    continue;
+  }
+  const markdown = await readFile(`${SPEC_DIR}/${filename}`, "utf8");
+
+  /**
+   * Not strictly 'lines' since we try and group indented things together as if
+   * they were one line. Close enough though.
+   */
+  const lines = markdown.split(/\n(?=[\S\n]|\s*(?:-|[0-9]+\.) )/);
+
+  for (let i = 0, l = lines.length; i < l; i++) {
+    const line = lines[i];
+
+    // Check algorithm is consistently formatted
+    {
+      // 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.dir(line);
+          console.log();
+          process.exitCode = 1;
+        }
+        if (lines[i + 1] !== "") {
+          console.log(
+            `No empty space after algorithm ${algorithmName} header in '${filename}'`
+          );
+          console.log();
+          process.exitCode = 1;
+        }
+        for (let j = i + 2; j < l; j++) {
+          const step = lines[j];
+          if (!step.match(/^\s*(-|[0-9]+\.) /)) {
+            if (step !== "") {
+              console.log(
+                `Bad algorithm ${algorithmName} step in '${filename}':`
+              );
+              console.dir(step);
+              console.log();
+              process.exitCode = 1;
+            }
+            break;
+          }
+          if (!step.match(/[.:]$/)) {
+            console.log(
+              `Bad formatting for '${algorithmName}' 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 '${algorithmName}' 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 '${algorithmName}' step (true/false/null should be wrapped in curly braces, e.g. '{true}') in '${filename}':`
+            );
+            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;
+          }
+        }
+      }
+    }
+
+    // Check `- ...:` step is followed by an indent
+    {
+      const matches = line.match(/^(\s*)- .*:\s*$/);
+      if (matches) {
+        const indent = matches[1];
+        const nextLine = lines[i + 1];
+        if (!nextLine.startsWith(`${indent}  `)) {
+          console.log(
+            `Lacking indent in '${filename}' following ':' character:`
+          );
+          console.dir(line);
+          console.dir(nextLine);
+          console.log();
+          // TODO: process.exitCode = 1;
+        }
+      }
+    }
+  }
+}
+
+if (process.exitCode === 0) {
+  console.log(`Everything looks okay!`);
+} else {
+  console.log(`Please resolve the errors detailed above.`);
+}

.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test-spelling:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - run: npm ci
+      - run: npm run test:spelling
+  test-format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - run: npm ci
+      - run: npm run test:format
+      - run: npm run test:algorithm-format
+  test-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - run: npm ci
+      - run: npm run test:build
+  publish:
+    if: github.ref == 'refs/heads/main'
+    needs:
+      - test-spelling
+      - test-format
+      - test-build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v3
+      - run: npm ci
+      - run: npm run build
+      - uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          keep_files: true
+          cname: spec.graphql.org
+          user_name: "github-actions[bot]"
+          user_email: "github-actions[bot]@users.noreply.github.com"

.gitignore

@@ -4,6 +4,6 @@
 .DS_Store
 npm-debug.log
 /build
-/out
+/public
 /gh-pages
 /node_modules

.prettierignore

@@ -0,0 +1,11 @@
+*.swp
+*~
+.*.haste_cache.*
+.DS_Store
+npm-debug.log
+/build
+/changelogs
+/out
+/gh-pages
+/node_modules
+/package.json