ci: Fail PRs that add an underscore to a docs/ file or folder name

.github/workflows/check-filenames.yml

@@ -0,0 +1,31 @@
+name: Check filenames
+
+# Fails when a file or folder name under docs/ contains an underscore: they
+# become URL paths, which use hyphens. Runs the same dev/check-filenames.mjs
+# that `pnpm run build` runs, so a bad name fails here before it fails the
+# Vercel build, whose log only Vercel team members can read.
+
+on:
+    pull_request:
+
+# A new push supersedes the run for the previous one
+concurrency:
+    group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+    cancel-in-progress: true
+
+permissions:
+    contents: read
+
+jobs:
+    check-filenames:
+        name: Underscores in docs/ file and folder names
+        runs-on: ubuntu-latest
+        steps:
+            - name: Check out pull request head
+              uses: actions/checkout@v4
+              with:
+                  ref: ${{ github.event.pull_request.head.sha }}
+
+            # No install step: the script has no dependencies beyond Node
+            - name: Find underscores in docs/ file and folder names
+              run: node dev/check-filenames.mjs

AGENTS.md

@@ -22,7 +22,9 @@
   `export const dynamic = 'force-static'`
 - **Checks**: `pnpm run check` runs the checks in `dev/checks.mjs` (links,
   filenames, images); `pnpm run build` runs filenames and images first, so a
-  finding from those fails a deploy. Links is not in the build: it runs as its
+  finding from those fails a deploy. Filenames also runs as its own PR check
+  (`.github/workflows/check-filenames.yml`), failing on an underscore in a
+  file or folder name under `docs/`. Links is not in the build: it runs as its
   own PR check (`.github/workflows/check-links.yml`)
 - **Check redirects**: `node dev/check-redirects.mjs` reports broken entries in
   `src/data/redirects.ts` (CI comments on PRs that break redirects; see the

dev/check-filenames.mjs

@@ -2,54 +2,46 @@
 
 /**
  * Filename convention checker for documentation files.
- * 
- * Ensures no underscores are used in folder or file names,
- * as URLs should only use hyphens.
- * 
+ *
+ * Ensures no underscores are used in folder or file names under docs/, since
+ * they become URL paths, which use hyphens. Runs in `pnpm run build` and as a
+ * pull request check (.github/workflows/check-filenames.yml).
+ *
  * Usage: node dev/check-filenames.mjs
  */
 
+import fs from 'fs';
 import path from 'path';
-import { glob } from 'glob';
-import { fileURLToPath } from 'url';
+import {fileURLToPath} from 'url';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
+const DOCS_DIR = path.join(
+	path.dirname(fileURLToPath(import.meta.url)),
+	'..',
+	'docs'
+);
+const ADVICE =
+	'Use hyphens (-) instead of underscores (_) in file and folder names';
 
-const DOCS_DIR = path.join(path.dirname(__dirname), 'docs');
+console.log('🔍 Checking for underscores in docs filenames...\n');
 
-async function main() {
-	console.log('🔍 Checking for underscores in docs filenames...\n');
-
-	const files = await glob('**/*', { cwd: DOCS_DIR });
-	const errors = [];
-
-	for (const file of files) {
-		const parts = file.split('/');
-		for (const part of parts) {
-			if (part.includes('_')) {
-				errors.push(file);
-				break;
-			}
-		}
-	}
-
-	if (errors.length === 0) {
-		console.log('✅ No underscores found in filenames!');
-		process.exit(0);
-	}
-
-	console.log(`❌ Found ${errors.length} path(s) with underscores:\n`);
-
-	for (const file of errors) {
-		console.log(`   docs/${file}`);
-	}
-
-	console.log('\n   Please use hyphens (-) instead of underscores (_) in file and folder names.\n');
-	process.exit(1);
+const errors = fs
+	.readdirSync(DOCS_DIR, {recursive: true})
+	.filter(file => path.basename(file).includes('_'))
+	.map(file => path.join('docs', file))
+	.sort();
+
+if (errors.length === 0) {
+	console.log('✅ No underscores found in filenames!');
+	process.exit(0);
 }
 
-main().catch(err => {
-	console.error('Error running filename checker:', err);
-	process.exit(1);
-});
+console.log(`❌ Found ${errors.length} path(s) with underscores:\n`);
+for (const file of errors) {
+	console.log(`   ${file}`);
+	// Annotation on the file in the pull request's Files changed tab
+	if (process.env.GITHUB_ACTIONS) {
+		console.log(`::error file=${file}::${ADVICE}`);
+	}
+}
+console.log(`\n   ${ADVICE}\n`);
+process.exit(1);