feat: todo

.vscode/settings.json

@@ -61,7 +61,7 @@
 
   // Show TypeScript errors for files that don't happen to be currently open, which makes TypeScript
   // work similar to other compiled languages like Golang or Rust.
-  // "typescript.tsserver.experimental.enableProjectDiagnostics": true,
+  "typescript.tsserver.experimental.enableProjectDiagnostics": true,
 
   // Automatically run the formatter when certain files are saved.
   "[javascript]": {

package.json

@@ -27,7 +27,7 @@
     "@docusaurus/preset-classic": "^2.4.3",
     "@eslint/js": "^8.52.0",
     "@mdx-js/react": "1.6.22",
-    "@microsoft/api-extractor": "^7.38.0",
+    "@microsoft/api-extractor": "^7.38.1",
     "@prettier/plugin-xml": "^3.2.2",
     "@svgr/webpack": "^8.1.0",
     "@tsconfig/docusaurus": "^2.0.2",
@@ -42,7 +42,7 @@
     "@types/glob": "^8.1.0",
     "@types/jest": "^29.5.7",
     "@types/klaw-sync": "^6.0.3",
-    "@types/node": "^20.8.9",
+    "@types/node": "^20.8.10",
     "@types/prompt": "^1.1.7",
     "@types/source-map-support": "^0.5.9",
     "@types/touch": "^3.1.4",

packages/docs/package.json

@@ -14,7 +14,7 @@
   "license": "GPL-3.0",
   "author": "Zamiell",
   "scripts": {
-    "build": "docusaurus build",
+    "build": "tsx --tsconfig ./scripts/tsconfig.json ./build.mts",
     "clear": "docusaurus clear",
     "deploy": "docusaurus deploy",
     "docusaurus": "docusaurus",

packages/docs/scripts/build.mts

@@ -0,0 +1,71 @@
+import { $op, $s, buildScript, rm } from "isaacscript-common-node";
+import path from "node:path";
+
+const TYPEDOC_PACKAGES = [
+  "isaac-typescript-definitions",
+  "isaacscript-common",
+] as const;
+
+const GENERATED_DOC_DIRECTORY_NAMES = [
+  ...TYPEDOC_PACKAGES,
+  "eslint-config-isaacscript",
+] as const;
+
+await buildScript(async ({ packageRoot, outDir }) => {
+  if (outDir === undefined) {
+    outDir = "dist"; // eslint-disable-line no-param-reassign
+  }
+
+  const generatedDocPaths = GENERATED_DOC_DIRECTORY_NAMES.map((directoryName) =>
+    path.join(packageRoot, "docs", directoryName),
+  );
+  rm(...generatedDocPaths);
+
+  const repoRoot = path.join(packageRoot, "..", "..");
+
+  const promises: Array<Promise<unknown>> = [];
+
+  promises.push(
+    makeITDDocs(repoRoot),
+    makeISCDocs(repoRoot),
+    makeECIDocs(repoRoot),
+  );
+
+  await Promise.all(promises);
+
+  // Format the Markdown output with Prettier, which will remove superfluous backslash escape
+  // characters that cause issues with search engine indexing. (However, we must change directories
+  // to avoid creating a spurious "node_modules" folder.)
+  const $$ = $op({ cwd: repoRoot });
+  await $$`prettier ./packages/docs/docs --write`;
+
+  $s`docusaurus build`;
+});
+
+async function makeITDDocs(repoRoot: string): Promise<void> {
+  const packagePath = path.join(
+    repoRoot,
+    "packages",
+    "isaac-typescript-definitions",
+  );
+  const $$ = $op({ cwd: packagePath });
+  await $$`npm run docs`;
+  await $$`tsx ../../scripts/fixIsaacTypeScriptDefinitions.ts`;
+}
+
+async function makeISCDocs(repoRoot: string): Promise<void> {
+  const packagePath = path.join(repoRoot, "packages", "isaacscript-common");
+  const $$ = $op({ cwd: packagePath });
+  await $$`npm run docs`;
+  await $$`tsx ../../scripts/fixIsaacScriptCommon.ts`;
+}
+
+async function makeECIDocs(repoRoot: string): Promise<void> {
+  const packagePath = path.join(
+    repoRoot,
+    "packages",
+    "eslint-config-isaacscript",
+  );
+  const $$ = $op({ cwd: packagePath });
+  await $$`npm run docs`;
+}

packages/docs/scripts/deploy.mts

@@ -0,0 +1,110 @@
+import {
+  $s,
+  appendFile,
+  cd,
+  cp,
+  dirName,
+  echo,
+  exit,
+  fatalError,
+  getArgs,
+  isGitRepositoryClean,
+  isGitRepositoryLatestCommit,
+  mv,
+  rm,
+  sleep,
+} from "isaacscript-common-node";
+import path from "node:path";
+
+const __dirname = dirName();
+
+const DOCS_REPO_NAME = "isaacscript.github.io";
+const GITHUB_PAGES_URL = `https://${DOCS_REPO_NAME}/isaacscript-common/core/constants/index.html`;
+const SECONDS_TO_SLEEP = 10;
+
+const PACKAGE_ROOT = path.join(__dirname, "..");
+const BUILD_DIRECTORY_PATH = path.join(PACKAGE_ROOT, "build");
+const REPO_ROOT = path.join(PACKAGE_ROOT, "..", "..");
+const DOCS_REPO = path.join(REPO_ROOT, DOCS_REPO_NAME);
+const DOCS_REPO_GIT = path.join(DOCS_REPO, ".git");
+const DOCS_REPO_GIT_BACKUP = `/tmp/${DOCS_REPO_NAME}.git`;
+
+// Validate environment variables.
+const GITHUB_OUTPUT_FILE = process.env["GITHUB_OUTPUT"];
+if (GITHUB_OUTPUT_FILE === undefined || GITHUB_OUTPUT_FILE === "") {
+  fatalError("Failed to read the environment variable: GITHUB_OUTPUT");
+}
+
+// Validate command-line arguments.
+const args = getArgs();
+const commitSHA1 = args[0];
+if (commitSHA1 === undefined || commitSHA1 === "") {
+  echo("Error: The SHA1 of the commit is required as an argument.");
+  exit(1);
+}
+
+// The website repository will be already cloned at this point by the previous GitHub action,
+// including switching to the "gh-pages" branch. See "ci.yml" for more information.
+mv(DOCS_REPO_GIT, DOCS_REPO_GIT_BACKUP);
+rm(DOCS_REPO);
+cp(BUILD_DIRECTORY_PATH, DOCS_REPO);
+mv(DOCS_REPO_GIT_BACKUP, DOCS_REPO_GIT);
+
+cd(DOCS_REPO);
+if (isGitRepositoryClean()) {
+  echo("There are no documentation website changes to deploy.");
+  exit();
+}
+
+// Ensure that the checked out version of this repository is the latest version. (It is possible
+// that another commit has been pushed in the meantime, in which case we should do nothing and wait
+// for the CI on that commit to finish.)
+// https://stackoverflow.com/questions/3258243/check-if-pull-needed-in-git
+cd(REPO_ROOT);
+if (!isGitRepositoryLatestCommit()) {
+  echo(
+    "A more recent commit was found in the repository; skipping website deployment.",
+  );
+  exit();
+}
+
+echo(`Deploying changes to the documentation website: ${DOCS_REPO_NAME}`);
+cd(DOCS_REPO);
+$s`git config --global user.email "github-actions@users.noreply.github.com"`;
+$s`git config --global user.name "github-actions"`;
+// We overwrite the previous commit instead of adding a new one in order to keep the size of the
+// repository as small as possible. This speeds up deployment because with thousands of commits, it
+// takes a very long time to clone.
+$s`git add --all`;
+$s`git commit --message deploy --amend`;
+$s`git push --force-with-lease`;
+
+cd(REPO_ROOT);
+
+// Wait for the website to be be live (which usually takes around 5 minutes).
+const shortCommitSHA1 = commitSHA1.slice(0, 7);
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition, no-constant-condition
+while (true) {
+  if (!isGitRepositoryLatestCommit()) {
+    echo(
+      "A more recent commit was found in the repository; skipping website scraping.",
+    );
+    exit(0);
+  }
+
+  const request = await fetch(GITHUB_PAGES_URL); // eslint-disable-line no-await-in-loop
+  const text = await request.text(); // eslint-disable-line no-await-in-loop
+  if (text.includes(shortCommitSHA1)) {
+    echo(
+      'Found a link on "$GITHUB_PAGES_URL" matching the short commit of: $SHORT_COMMIT_SHA1',
+    );
+    break;
+  }
+
+  echo(
+    `The latest version of the site (${shortCommitSHA1}) has not yet been deployed to GitHub Pages. Sleeping for ${SECONDS_TO_SLEEP} seconds.`,
+  );
+  await sleep(SECONDS_TO_SLEEP); // eslint-disable-line no-await-in-loop
+}
+
+appendFile(GITHUB_OUTPUT_FILE, "SHOULD_SCRAPE=1\n");