check-links: flag absolute self-links with a suggested relative link, probe external links on added lines

Absolute links to this site (https://sourcegraph.com/docs/..., the legacy
docs.sourcegraph.com host, http://, //, www.) are findings even when the target
exists: they leave preview deployments and local dev, and hide moved pages
behind redirects. The finding proposes the relative link, following
src/data/redirects.ts when the page moved. Version-pinned links (/@5.1/...) stay
external.

--diff replaces --changed-files and scopes two new features to added lines:
--check-external requests each external link (HEAD, then GET on an error status,
following redirects) and reports 404/410 only; --review writes a GitHub review
with one suggested change per line, which the workflow posts, skipping
suggestions already on the PR.

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

@@ -1,7 +1,8 @@
 name: Check links
 
 # Reports internal links and #anchors that this PR breaks, compared with the
-# merge base. Pre-existing broken links on the base branch are ignored.
+# merge base, absolute links to this site, and external links on added lines
+# that 404. Pre-existing broken links on the base branch are ignored.
 
 on:
     pull_request:
@@ -40,7 +41,7 @@ jobs:
               run: |
                   merge_base=$(git merge-base "$BASE_SHA" HEAD)
                   git worktree add "$RUNNER_TEMP/base" "$merge_base"
-                  git diff --name-only "$merge_base" HEAD > "$RUNNER_TEMP/changed-files.txt"
+                  git diff -U0 "$merge_base" HEAD > "$RUNNER_TEMP/changes.diff"
 
             - name: Record broken links already present on the base branch
               # Exit 1 means findings, which is expected here
@@ -55,9 +56,10 @@ 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 --format markdown \
+                  if node dev/check-links.mjs --check-anchors --check-external --format markdown \
                       --baseline "$RUNNER_TEMP/base-links.json" \
-                      --changed-files "$RUNNER_TEMP/changed-files.txt" \
+                      --diff "$RUNNER_TEMP/changes.diff" \
+                      --review "$RUNNER_TEMP/review.json" \
                       --link-base "$LINK_BASE" > "$RUNNER_TEMP/report.md"; then
                       echo "broken=false" >> "$GITHUB_OUTPUT"
                   else
@@ -94,6 +96,26 @@ jobs:
                       gh pr comment "$PR_NUMBER" --body-file "$RUNNER_TEMP/comment.md"
                   fi
 
+            - name: Suggest fixes as review comments
+              # One suggested change per added line with a fix. Suggestions already on
+              # the PR (same file, line, and text) are not posted again.
+              if: steps.check.outputs.broken == 'true' && github.event.pull_request.head.repo.full_name == github.repository
+              env:
+                  GH_TOKEN: ${{ github.token }}
+                  PR_NUMBER: ${{ github.event.pull_request.number }}
+              run: |
+                  gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/comments" --paginate \
+                      --jq '.[] | {path, line, body}' | jq -s . > "$RUNNER_TEMP/posted.json"
+                  jq --slurpfile posted "$RUNNER_TEMP/posted.json" \
+                      '.comments |= map(select(. as $comment | $posted[0] | index({path: $comment.path, line: $comment.line, body: $comment.body}) | not))' \
+                      "$RUNNER_TEMP/review.json" > "$RUNNER_TEMP/review-new.json"
+
+                  if [ "$(jq '.comments | length' "$RUNNER_TEMP/review-new.json")" -gt 0 ]; then
+                      gh api --method POST "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/reviews" \
+                          --input "$RUNNER_TEMP/review-new.json" > /dev/null \
+                          || echo "::warning::Could not post the suggested fixes; they are in the report above"
+                  fi
+
             - name: Fail when this PR introduces broken links
               if: steps.check.outputs.broken == 'true'
               run: exit 1

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
+-   **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)`
 -   **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