From f1b18463212383d7a3ba369bbea0e6b8daa00188 Mon Sep 17 00:00:00 2001 From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com> Date: Mon, 14 Sep 2026 15:31:25 +0000 Subject: [PATCH] build: drop the link check from the Vercel build; it runs as its own PR check The Broken links introduced by this PR job (.github/workflows/check-links.yml) runs dev/check-links.mjs on every pull request, with a baseline so it only reports links the PR introduces, and comments the findings. Running it again without flags in npm run build duplicated that check and made a dead link anywhere in the tree fail the deploy, even one not introduced by the commit. npm run build now runs only the filenames and images checks. npm run check still runs all three. Amp-Thread-ID: https://ampcode.com/threads/T-01a09f23-2ad6-76a8-a697-3da4969f29f9 Co-authored-by: Amp --- AGENTS.md | 4 ++-- dev/check-links.mjs | 4 ++-- dev/checks.mjs | 5 +++-- package.json | 2 +- 4 files changed, 8 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ec0207aa6..d575c3160 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,8 +7,8 @@ - **Dev**: `npm run dev` - **Lint**: `npm run lint` (ESLint 9 flat config in `eslint.config.mjs`; React Compiler rules are warnings until the vendored `src/components/search/docsearch` code is rewritten) - **Framework**: Next.js 16 with `--webpack` (`next-contentlayer2` has no Turbopack plugin); the request rewrite lives in `src/proxy.ts`; `/api/releases` and `/api/versions` opt into static caching with `export const dynamic = 'force-static'` -- **Checks**: `npm run check` runs every `dev/check-*.mjs` (links, filenames, images); `npm run build` runs them first, so any finding fails a deploy -- **Check links**: `npm run check -- links --check-anchors --check-self-links` (CI comments on PRs that break links; see `dev/check-links.mjs`; the build runs it without flags, so only dead page links fail a deploy). When moving a page or renaming a heading, update every link to it; a redirect in `src/data/redirects.ts` does not satisfy the check. Link to this site with relative paths (`/admin/config/site-config`), never `https://sourcegraph.com/docs/…` or `https://docs.sourcegraph.com/…`. To also probe the external links you added: `npm run check -- links --check-anchors --check-self-links --check-external --diff <(git diff -U0 origin/main)` +- **Checks**: `npm run check` runs every `dev/check-*.mjs` (links, filenames, images); `npm 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 own PR check (`.github/workflows/check-links.yml`) +- **Check links**: `npm run check -- links --check-anchors --check-self-links` (CI comments on PRs that break links and fails the `Broken links introduced by this PR` check; see `dev/check-links.mjs`). When moving a page or renaming a heading, update every link to it; a redirect in `src/data/redirects.ts` does not satisfy the check. Link to this site with relative paths (`/admin/config/site-config`), never `https://sourcegraph.com/docs/…` or `https://docs.sourcegraph.com/…`. To also probe the external links you added: `npm run check -- links --check-anchors --check-self-links --check-external --diff <(git diff -U0 origin/main)` - **Check redirects**: `node dev/check-redirects.mjs` reports broken entries in `src/data/redirects.ts` (CI comments on PRs that break redirects; see the script header for what it checks). Not part of `npm run check`: main has hundreds of pre-existing findings, and CI only reports the ones a PR adds - **Prove changed links resolve on a deploy**: `node dev/verify-links-live.mjs --site ` prints a Markdown table for the PR description - **Vercel build failures**: Vercel shows build logs only to its team members, so `.github/workflows/vercel-build-report.yml` attaches the log to the Vercel Slack app's "failed to deploy" post in `#alerts-vercel-doc-site` and comments a link to it on the PR (see `dev/report-vercel-build.mjs`). The log itself never goes on the PR, since the repository is public. It reads Vercel with the `VERCEL_TOKEN` repo secret, a token scoped to the `sourcegraph-docs` project that expires 2026-12-10; mint a new one with `POST /v3/user/tokens?teamId=` and `projectId` in the body. Slack needs the `SLACK_BOT_TOKEN` repo secret and `SLACK_CHANNEL_ID` repo variable. The bot is the Slack app in `dev/slack-app-vercel-build-report.json`; to recreate it, paste that manifest at (From a manifest), install it, copy its Bot User OAuth Token into the secret, and `/invite @Vercel build log` to the channel diff --git a/dev/check-links.mjs b/dev/check-links.mjs index 3bb48936e..ce15368e3 100644 --- a/dev/check-links.mjs +++ b/dev/check-links.mjs @@ -16,8 +16,8 @@ * should be relative links; the finding proposes one, following src/data/redirects.ts * - With --check-external, external links on added lines that return 404 or 410 * - * next.config.js runs this with no flags on every build, so only dead page links - * can fail a deploy; the flags below are for the pull request workflow. + * The pull request workflow (.github/workflows/check-links.yml) runs this with + * the flags below; `npm run build` does not run it, so findings never fail a deploy. * * Usage: node dev/check-links.mjs [options] * --check-anchors Also validate #anchors against headings diff --git a/dev/checks.mjs b/dev/checks.mjs index c947a9521..d2e3ffe4e 100644 --- a/dev/checks.mjs +++ b/dev/checks.mjs @@ -1,8 +1,9 @@ #!/usr/bin/env node /** - * Runs the docs checks in dev/check-*.mjs. `npm run build` runs them all - * before `next build`. + * Runs the docs checks in dev/check-*.mjs. `npm run build` runs filenames and + * images before `next build`; links has its own pull request check + * (.github/workflows/check-links.yml), so a dead link does not fail a deploy. * * Usage: node dev/checks.mjs [check ...] [flags] * node dev/checks.mjs every check diff --git a/package.json b/package.json index 5c7c7bf72..6a3f70ab7 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,7 @@ }, "scripts": { "dev": "next dev --webpack", - "build": "node dev/checks.mjs && node dev/generate-mermaid-icons.mjs && next build --webpack", + "build": "node dev/checks.mjs filenames images && node dev/generate-mermaid-icons.mjs && next build --webpack", "start": "next start", "lint": "eslint src", "check": "node dev/checks.mjs",