package.json整理、dockerfileとciでrevisionチェックを実行

Author: na-trium-144

.github/workflows/node.js.yml

@@ -33,6 +33,20 @@ jobs:
     - run: npm ci
     - run: npm run tsc
 
+  check-docs:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [22.x]
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run checkDocs
+
   test-js-eval:
     runs-on: ubuntu-latest
     strategy:

Dockerfile

@@ -21,7 +21,8 @@ COPY --from=dependencies /app/node_modules ./node_modules
 # Copy application source code
 COPY . .
 
-ENV NODE_ENV=production
+# Stop if documentation has any change that is not reflected to revisions.yml and database.
+RUN npx tsx ./scripts/checkDocs.ts --check-diff
 
 # Next.js collects completely anonymous telemetry data about general usage.
 # Learn more here: https://nextjs.org/telemetry

README.md

@@ -54,6 +54,8 @@ npm run lint
 ```
 でコードをチェックします。出てくるwarningやerrorはできるだけ直しましょう。
 
+### データベースのスキーマ
+
 * データベースのスキーマ(./app/schema/hoge.ts)を編集した場合、 `npx drizzle-kit generate` でmigrationファイルを作成し、 `npx drizzle-kit migrate` でデータベースに反映します。
     * また、mainにマージする際に本番環境のデータベースにもmigrateをする必要があります
 * スキーマのファイルを追加した場合は app/lib/drizzle.ts でimportを追加する必要があります(たぶん)
@@ -72,6 +74,11 @@ Cloudflare Worker のビルドログとステータス表示が見れますが
 
 ## ドキュメント
 
+```bash
+npm run checkDocs
+```
+でドキュメントの読み込み時にエラーにならないか確認できます (index.ymlの間違いなど)
+
 * ドキュメントはセクション(見出し)ごとにわけ、 public/docs/言語id/ページid/並び替え用連番-セクション名.md に置く。
 * ページはディレクトリの名前によらず 言語id/index.yml に書かれている順で表示される。
 * セクションはセクションIDによらずファイル名順で表示される。
@@ -111,6 +118,7 @@ Cloudflare Worker のビルドログとステータス表示が見れますが
 * REPLのコード例は1セクションに最大1つまで。
     * コードエディターとコード実行ブロックはいくつでも置けます。
 * ページ0以外の各ページの最後はレベル2見出し「この章のまとめ」と、レベル3見出し「練習問題n」を置く
+* ドキュメントに変更を加えたものをmainブランチにpushした際、public/docs/revisions.ymlが更新されます。基本的には手動でこのファイルを編集する必要はありません。
 
 ### ベースとなるドキュメントの作り方
 
@@ -141,18 +149,17 @@ Cloudflare Worker のビルドログとステータス表示が見れますが
     - Canvasを使われた場合はやり直す。(Canvasはファイル名付きコードブロックで壊れる)
     - 太字がなぜか `**キーワード**` の代わりに `\*\*キーワード\*\*` となっている場合がある。 `\*\*` → `**` の置き換えで対応
     - 見出しの前に `-----` (水平線)が入る場合がある。my.code();は水平線の表示に対応しているが、消す方向で統一
-    - `言語名-repl` にはページ内で一意なIDを追加する (例: `言語名-repl:1`)
     - REPLの出力部分に書かれたコメントは消えるので修正する
         - ダメな例
         ````
-        ```js-repl:1
+        ```js-repl
         > console.log("Hello")
         Hello  // 文字列を表示する
         ```
         ````
         - 以下のようにすればok
         ````
-        ```js-repl:1
+        ```js-repl
         > console.log("Hello")  // 文字列を表示する
         Hello
 
@@ -162,7 +169,6 @@ Cloudflare Worker のビルドログとステータス表示が見れますが
         ```
         ````
     - 練習問題のファイル名は不都合がなければ `practice(章番号)_(問題番号).拡張子` で統一。空でもよいのでファイルコードブロックとexecコードブロックを置く
-- 1章にはたぶん練習問題要らない。
 
 ## markdown仕様
 

package.json

@@ -7,15 +7,14 @@
     "packages/*"
   ],
   "scripts": {
-    "dev": "npm run cf-typegen && npm run generateDocsMeta && npm run copyAllDTSFiles && npm run removeHinting && next dev",
-    "build": "npm run cf-typegen && npm run generateDocsMeta && npm run copyAllDTSFiles && npm run removeHinting && next build",
+    "prebuild": "npm run cf-typegen && tsx ./scripts/checkDocs.ts && tsx ./scripts/generateDocsMeta.ts && tsx ./scripts/copyAllDTSFiles.ts && tsx ./scripts/removeHinting.ts",
+    "dev": "npm run prebuild && next dev",
+    "build": "next build",
     "start": "next start",
     "lint": "npm run cf-typegen && next lint",
     "tsc": "npm run cf-typegen && tsc",
-    "format": "prettier --write app/",
-    "generateDocsMeta": "tsx ./scripts/generateDocsMeta.ts",
-    "copyAllDTSFiles": "tsx ./scripts/copyAllDTSFiles.ts",
-    "removeHinting": "tsx ./scripts/removeHinting.ts",
+    "format": "prettier --write app/ packages/",
+    "checkDocs": "tsx ./scripts/checkDocs.ts",
     "cf-preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview --port 3000",
     "cf-deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy",
     "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"

scripts/checkDocs.ts

@@ -0,0 +1,137 @@
+/*
+mainブランチにpushされた際にGitHub Actionが --write 引数をつけて実行し、
+その場合は public/docs/ 以下のドキュメントの各セクションについて、
+現在のパス、md5ハッシュ、コミットIDなどを ./public/docs/revisions.yml に追記
+セクションIDとページパスの対応関係をデータベースに反映
+
+過去に存在したページが削除されている場合、エラーになります。
+その場合は手動でrevisions.ymlを編集し、古いページ名の記述を新しいページ名に置き換える必要がある
+(できれば自動化したいが、いい方法が思いつかない)
+
+Dockerfile内で --check-diff 引数をつけて実行され、
+revisions.ymlが最新の状態でないならexit(1)をし、dockerのビルドを停止します
+
+なにも引数をつけずに実行した場合(npm run checkDocs)、
+変更があってもなにもせず正常終了します
+エラーなく全ドキュメントを取得できるかどうかの確認に使います
+*/
+
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  getMarkdownSections,
+  getPagesList,
+  RevisionYmlEntry,
+} from "@/lib/docs";
+import yaml from "js-yaml";
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { getDrizzle } from "@/lib/drizzle";
+import { section as sectionTable } from "@/schema/chat";
+import "dotenv/config";
+
+let doWrite = false;
+let doCheckDiff = false;
+if (process.argv[2] === "--write") {
+  doWrite = true;
+} else if (process.argv[2] === "--check-diff") {
+  doCheckDiff = true;
+} else if (process.argv[2]) {
+  throw new Error(`Unknown arg: ${process.argv[2]}`);
+}
+
+const docsDir = join(process.cwd(), "public", "docs");
+
+const commit = execFileSync("git", ["rev-parse", "--short", "HEAD"], {
+  encoding: "utf8",
+}).trim();
+
+const langEntries = await getPagesList();
+
+const revisionsPrevYml = existsSync(join(docsDir, "revisions.yml"))
+  ? await readFile(join(docsDir, "revisions.yml"), "utf-8")
+  : "{}";
+const revisions = yaml.load(revisionsPrevYml) as Record<
+  string,
+  RevisionYmlEntry
+>;
+
+for (const lang of langEntries) {
+  for (const page of lang.pages) {
+    const sections = await getMarkdownSections(lang.id, page.slug);
+    for (const section of sections) {
+      if (section.id in revisions) {
+        revisions[section.id].page = `${lang.id}/${page.slug}`;
+        if (!revisions[section.id].rev.some((r) => r.md5 === section.md5)) {
+          // ドキュメントが変更された場合
+          console.warn(`${section.id} has new md5: ${section.md5}`);
+          if (doWrite) {
+            revisions[section.id].rev.push({
+              md5: section.md5,
+              git: commit,
+              path: `public/docs/${lang.id}/${page.slug}/${section.file}`,
+            });
+          } else if (doCheckDiff) {
+            process.exit(1);
+          }
+        }
+      } else {
+        // ドキュメントが新規追加された場合
+        console.warn(`${section.id} is new section`);
+        if (doWrite) {
+          revisions[section.id] = {
+            rev: [
+              {
+                md5: section.md5,
+                git: commit,
+                path: `public/docs/${lang.id}/${page.slug}/${section.file}`,
+              },
+            ],
+            page: `${lang.id}/${page.slug}`,
+          };
+        } else if (doCheckDiff) {
+          process.exit(1);
+        }
+      }
+    }
+  }
+}
+
+for (const id in revisions) {
+  if (!existsSync(join(docsDir, revisions[id].page))) {
+    console.warn(
+      `The page slug ${revisions[id].page} previously used by section ${id} does not exist. ` +
+        `Please replace 'page: ${revisions[id].page}' in public/docs/revisions.yml with new page path manually.`
+    );
+    if (doWrite || doCheckDiff) {
+      process.exit(1);
+    }
+  }
+}
+
+if (doWrite) {
+  const drizzle = await getDrizzle();
+  for (const id in revisions) {
+    await drizzle
+      .insert(sectionTable)
+      .values({
+        sectionId: id,
+        pagePath: revisions[id].page,
+      })
+      .onConflictDoUpdate({
+        target: sectionTable.sectionId,
+        set: { pagePath: revisions[id].page },
+      });
+  }
+
+  const revisionsYml = yaml.dump(revisions, {
+    sortKeys: true,
+    noArrayIndent: true,
+  });
+  await writeFile(
+    join(docsDir, "revisions.yml"),
+    "# This file will be updated by CI. Do not edit manually, unless CI failed.\n" +
+      revisionsYml,
+    "utf-8"
+  );
+}