check-links: report absolute self-links only with --check-self-links, so next build fails on dead links alone

Amp-Thread-ID: https://ampcode.com/threads/T-01a08a01-44c1-775b-84d0-d67ff9501905
Co-authored-by: Amp <amp@ampcode.com>

Author: marcleblanc2

.github/workflows/check-links.yml

@@ -46,7 +46,7 @@ jobs:
             - name: Record broken links already present on the base branch
               # Exit 1 means findings, which is expected here
               run: |
-                  node dev/check-links.mjs --check-anchors --format json \
+                  node dev/check-links.mjs --check-anchors --check-self-links --format json \
                       --root "$RUNNER_TEMP/base" > "$RUNNER_TEMP/base-links.json" \
                       || [ $? -eq 1 ]
 
@@ -56,7 +56,7 @@ jobs:
                   # File links in the report open the file on the PR branch
                   LINK_BASE: ${{ github.event.pull_request.head.repo.html_url }}/blob/${{ github.event.pull_request.head.ref }}
               run: |
-                  if node dev/check-links.mjs --check-anchors --check-external --format markdown \
+                  if node dev/check-links.mjs --check-anchors --check-self-links --check-external --format markdown \
                       --baseline "$RUNNER_TEMP/base-links.json" \
                       --diff "$RUNNER_TEMP/changes.diff" \
                       --review "$RUNNER_TEMP/review.json" \

AGENTS.md

@@ -6,7 +6,7 @@
 -   **Build**: `npm run build`
 -   **Dev**: `npm run dev`
 -   **Lint**: `npm run lint`
--   **Check links**: `npm run check-links -- --check-anchors` (CI comments on PRs that break links; 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-external --diff <(git diff -U0 origin/main)`
+-   **Check links**: `npm run check-links -- --check-anchors --check-self-links` (CI comments on PRs that break links; see `dev/check-links.mjs`; `next 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)`
 -   **Prove changed links resolve on a deploy**: `node dev/verify-links-live.mjs --site <vercel-preview-url>` prints a Markdown table for the PR description
 
 ## AI Chat Integration

dev/check-links.mjs

@@ -11,13 +11,17 @@
  * - Links whose case differs from the real path (work on macOS, 404 on Linux)
  * - Missing anchor/heading references
  * - Invalid file paths
- * - Absolute links to this site (https://sourcegraph.com/docs/..., the legacy
- *   https://docs.sourcegraph.com/... host, http://, //, www.), which should be
- *   relative links; the finding proposes one, following src/data/redirects.ts
+ * - With --check-self-links, absolute links to this site (https://sourcegraph.com/docs/...,
+ *   the legacy https://docs.sourcegraph.com/... host, http://, //, www.), which
+ *   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.
+ *
  * Usage: node dev/check-links.mjs [options]
  *   --check-anchors        Also validate #anchors against headings
+ *   --check-self-links     Also report absolute links to this site
  *   --root <dir>           Repository to check (default: this repository)
  *   --format <name>        Output as text (default), json, or markdown
  *   --baseline <file>      Only report findings absent from this JSON file
@@ -49,6 +53,7 @@ const __dirname = path.dirname(__filename);
 // Parse CLI flags
 const args = process.argv.slice(2);
 const CHECK_ANCHORS = args.includes('--check-anchors');
+const CHECK_SELF_LINKS = args.includes('--check-self-links');
 const ROOT_DIR = path.resolve(flagValue('--root') ?? path.dirname(__dirname));
 const FORMAT = flagValue('--format') ?? 'text';
 const BASELINE_FILE = flagValue('--baseline');
@@ -326,7 +331,7 @@ function validateLink(link, currentFile, maps) {
 	const { url } = link;
 
 	if (isSelfLink(url)) {
-		return validateSelfLink(url, currentFile, maps);
+		return CHECK_SELF_LINKS ? validateSelfLink(url, currentFile, maps) : null;
 	}
 
 	// Skip external links, mailto, tel, javascript, etc.