feat: add a script to check versions

YDX-2147483647 · YDX-2147483647 · commit ee2e2f796e5e · 2026-02-14T17:28:21.000+08:00
diff --git a/.gitignore b/.gitignore
@@ -1,7 +1,7 @@
 # Generated by `mdbook build`
 /book/
 
-# Generated by `download.py`
+# Generated by `just download`
 /src/meta.json
 /src/**/*.md
 !/src/licenses.md
diff --git a/justfile b/justfile
@@ -29,7 +29,7 @@ rg PATTERN *ARGS:
 
 # Download book sources from GitHub (Please rerun if you meet any network error.)
 download:
-    uv run download.py
+    uv run scripts/download.py
 
 # Build the book
 build: download
@@ -39,3 +39,10 @@ build: download
 # Serve and open the book
 serve *ARGS: download
     mdbook serve {{ ARGS }}
+
+# Check latest version of packages
+[group("maintenance")]
+check-versions: download
+    @{{ if env("GITHUB_TOKEN", "") == "" { error("$GITHUB_TOKEN is required to access GitHub GraphQL API, but it is not set.") } else { "" } }}
+    node scripts/check_versions.ts
+    # 📝 Now you may update `preprocessor.typst-extra-docs.download` in `book.toml` according to the above output.
diff --git a/scripts/check_versions.ts b/scripts/check_versions.ts
@@ -0,0 +1,286 @@
+/**
+ * Check latest versions of packages.
+ * You may update `preprocessor.typst-extra-docs.download` in `book.toml` according to the output of this script.
+ *
+ * Usage:
+ * 1. Run `just download`.
+ * 2. Set the `$GITHUB_TOKEN` env var. (no scope required)
+ * 3. Run this script with node v24+.
+ */
+
+import assert from "node:assert";
+import fs from "node:fs";
+import path from "node:path";
+import { env } from "node:process";
+import { fileURLToPath } from "node:url";
+
+/** A map from repositories to files (as their original paths). */
+type Catalog = Map<string, string[]>;
+
+/** Collect the catalog from `meta.json` generated by `just download`. */
+function collectCatalog(): Catalog {
+  const srcDir = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "../src",
+  );
+
+  const meta: { dates: Record<string, string>; map: Record<string, string> } =
+    JSON.parse(
+      fs.readFileSync(path.join(srcDir, "meta.json"), { encoding: "utf-8" }),
+    );
+
+  const catalog: Catalog = new Map(
+    Object.keys(meta.dates).map((repoUrl) => {
+      // `/OWNER/REPO/blob/COMMIT`
+      const repo = new URL(repoUrl).pathname.split("/")[2];
+      return [repo, []];
+    }),
+  );
+
+  for (const fileUrl of Object.values(meta.map)) {
+    // `/OWNER/REPO/blob/COMMIT/*`
+    const fileUrlPath = new URL(fileUrl).pathname.split("/");
+    const repo = fileUrlPath[2];
+    const filePath = fileUrlPath.slice(5).join("/");
+    catalog.get(repo)!.push(filePath);
+  }
+
+  return catalog;
+}
+
+function* _buildQuery(catalog: Catalog): Generator<string> {
+  yield "query {";
+
+  for (const [repo, files] of catalog) {
+    yield `  ${repo}: repository(owner: "typst", name: "${repo}") {`;
+    yield '    ref(qualifiedName: "refs/heads/main") {';
+    yield "      target {";
+    yield "        ... on Commit {";
+
+    for (const file of files) {
+      const tab = "  ".repeat(5);
+      const fileSafe = file.replaceAll(/[\./-]/g, "_");
+      yield `${tab}${fileSafe}: history(first: 1, path: "${file}") {`;
+      yield `${tab}  nodes {`;
+      yield `${tab}    oid`;
+      yield `${tab}    authoredDate`;
+      yield `${tab}    message`;
+      yield `${tab}  }`;
+      yield `${tab}}`;
+    }
+
+    yield "        }";
+    yield "      }";
+    yield "    }";
+    yield "  }";
+  }
+
+  yield "}";
+}
+
+type QueryResult = {
+  [repo: string]: {
+    ref: {
+      target: {
+        [fileSafe: string]: {
+          nodes: [{
+            oid: string;
+            authoredDate: string;
+            message: string;
+          }] | [];
+        };
+      };
+    };
+  };
+};
+
+/** Build the GraphQL query from the catalog. */
+function buildQuery(catalog: Catalog): string {
+  return Array.from(_buildQuery(catalog)).join("\n");
+}
+
+/** Query GitHub GraphQL API, requires the `$GITHUB_TOKEN` env var. */
+async function queryGitHub<T>(query: string): Promise<T> {
+  const result = await fetch("https://api.github.com/graphql", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${env.GITHUB_TOKEN}`,
+    },
+    body: JSON.stringify({ query }),
+  }).then((res) => res.json());
+  if (result.errors || !result.data) {
+    throw new Error(`GitHub API error: ${JSON.stringify(result)}`);
+  }
+  return result.data;
+}
+
+/**
+ * A map from repositories to their versions.
+ *
+ * Similar to `preprocessor.typst-extra-docs.download` in `book.toml`.
+ */
+type PackageVersions = Map<string, PackageVersion>;
+type PackageVersion = {
+  commit_hash: string;
+  author_date: string;
+  comment: string;
+};
+
+function determineLatestVersions(queryResult: QueryResult): PackageVersions {
+  const versions: PackageVersions = new Map();
+
+  for (const [repo, { ref: { target } }] of Object.entries(queryResult)) {
+    let latest: PackageVersion | null = null;
+
+    for (const { nodes } of Object.values(target)) {
+      if (nodes.length === 0) {
+        continue;
+      }
+
+      const node = nodes[0];
+      if (
+        !latest ||
+        new Date(node.authoredDate) > new Date(latest.author_date)
+      ) {
+        latest = {
+          commit_hash: node.oid,
+          author_date: node.authoredDate,
+          comment: node.message.split("\n\n")[0], // Only keep the first line
+        };
+      }
+    }
+
+    if (latest) {
+      versions.set(repo, latest);
+    }
+  }
+
+  return versions;
+}
+
+function _runTests(tests: { [testName: string]: () => void }): void {
+  let failed = 0;
+  for (const [testName, testFn] of Object.entries(tests)) {
+    try {
+      testFn();
+      console.log(`Test "${testName}" passed`);
+    } catch (error) {
+      failed += 1;
+      console.error(`Test "${testName}" failed:`, error);
+    }
+  }
+  if (failed > 0) {
+    throw new Error(`${failed} test(s) failed`);
+  }
+}
+
+_runTests({
+  testBuildQuery() {
+    const catalog: Catalog = new Map([
+      ["typst", ["docs/dev/architecture.md", "README.md"]],
+    ]);
+    const query = buildQuery(catalog);
+    assert.strictEqual(
+      query,
+      `query {
+  typst: repository(owner: "typst", name: "typst") {
+    ref(qualifiedName: "refs/heads/main") {
+      target {
+        ... on Commit {
+          docs_dev_architecture_md: history(first: 1, path: "docs/dev/architecture.md") {
+            nodes {
+              oid
+              authoredDate
+              message
+            }
+          }
+          README_md: history(first: 1, path: "README.md") {
+            nodes {
+              oid
+              authoredDate
+              message
+            }
+          }
+        }
+      }
+    }
+  }
+}`,
+    );
+  },
+  testDetermineLatestVersions() {
+    const queryResult: QueryResult = {
+      "typst": {
+        "ref": {
+          "target": {
+            "docs_dev_architecture_md": {
+              "nodes": [
+                {
+                  "oid": "3c47607cbf2e8e5c050317e4d948970d23b38925",
+                  "authoredDate": "2025-12-10T12:48:07Z",
+                  "message":
+                    "Fix wrong path to `typst-eval` in dev docs (#7549)\n\nCo-authored-by: Laurenz <laurmaedje@gmail.com>",
+                },
+              ],
+            },
+            "readme_md": {
+              "nodes": [
+                {
+                  "oid": "9a4316c6b112e7ed1b0ab85c2607753a6fe04481",
+                  "authoredDate": "2026-01-19T16:12:37Z",
+                  "message": "Fix grammar in README (#7718)",
+                },
+              ],
+            },
+          },
+        },
+      },
+      "hayagriva": {
+        "ref": {
+          "target": {
+            "license_mit": {
+              "nodes": [
+                {
+                  "oid": "6073e44a8c793225e347adfcb35104df063eee8c",
+                  "authoredDate": "2021-01-17T18:57:15Z",
+                  "message":
+                    "Move some things around 🚛\n\nCo-authored-by: Laurenz Mädje <laurmaedje@gmail.com>",
+                },
+              ],
+            },
+          },
+        },
+      },
+    };
+
+    const latest = determineLatestVersions(queryResult);
+    assert.deepStrictEqual(
+      latest,
+      new Map([
+        [
+          "typst",
+          {
+            commit_hash: "9a4316c6b112e7ed1b0ab85c2607753a6fe04481",
+            author_date: "2026-01-19T16:12:37Z",
+            comment: "Fix grammar in README (#7718)",
+          },
+        ],
+        [
+          "hayagriva",
+          {
+            commit_hash: "6073e44a8c793225e347adfcb35104df063eee8c",
+            author_date: "2021-01-17T18:57:15Z",
+            comment: "Move some things around 🚛",
+          },
+        ],
+      ]),
+    );
+  },
+});
+
+const catalog = collectCatalog();
+const query = buildQuery(catalog);
+const result = await queryGitHub<QueryResult>(query);
+const versions = determineLatestVersions(result);
+console.log("Latest versions:", versions);
diff --git a/scripts/download.py b/scripts/download.py
@@ -11,7 +11,8 @@
 
 import httpx
 
-src_dir = Path(__file__).parent / "src"
+src_dir = Path(__file__).parent.parent / "src"
+assert src_dir.exists() and src_dir.is_dir()
 logger = logging.getLogger(__name__)
 
 client = httpx.Client(timeout=30.0)
diff --git a/typst-extra-docs/src/issue_link.rs b/typst-extra-docs/src/issue_link.rs
@@ -61,7 +61,7 @@ pub fn link_issues(
                         // Allow texts like `rpath.rs#L116-L158`.
                         if s.eat_if("#") && s.peek().is_some_and(|c| c.is_ascii_digit()) {
                             // We meet `#{num}`. Terminate before `#`.
-                            s.uneat(); 
+                            s.uneat();
                             break;
                         }
                     }
diff --git a/typst-extra-docs/src/lib.rs b/typst-extra-docs/src/lib.rs
@@ -23,7 +23,7 @@ impl ExtraDocs {
     }
 }
 
-/// `meta.json` generated by `download.py`.
+/// `meta.json` generated by `just download`.
 #[derive(serde::Deserialize)]
 struct Metadata {
     /// A mapping from file paths to source URLs.
@@ -38,7 +38,7 @@ impl Preprocessor for ExtraDocs {
     }
 
     fn run(&self, ctx: &PreprocessorContext, mut book: Book) -> Result<Book> {
-        // Read data generated by `download.py`
+        // Read data generated by `just download`
         let meta = ctx.config.book.src.join("meta.json");
         let meta: Metadata = serde_json::from_reader(File::open(&meta).inspect_err(|e| {
             eprintln!("Failed to open {:?}: {e:?}", &meta);
@@ -51,7 +51,7 @@ impl Preprocessor for ExtraDocs {
                 return; // Skip draft chapters
             };
             let Some(source_url) = meta.map.get(file) else {
-                return; // Skip chapters not generated by `download.py`
+                return; // Skip chapters not generated by `just download`
             };
 
             let markdown_options = MarkdownOptions::default();

Original file line number	Diff line number	Diff line change
`@@ -61,7 +61,7 @@ pub fn link_issues(`
`61`	`61`	// Allow texts like `rpath.rs#L116-L158`.
`62`	`62`	`if s.eat_if("#") && s.peek().is_some_and(\|c\| c.is_ascii_digit()) {`
`63`	`63`	// We meet `#{num}`. Terminate before `#`.
`64`		`- s.uneat();`
	`64`	`+ s.uneat();`
`65`	`65`	`break;`
`66`	`66`	`}`
`67`	`67`	`}`