@lhechenberger/check-links 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukas Hechenberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# @lhechenberger/check-links
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Crawls a deployed site for broken links and tells real failures apart from flaky ones. Made for CI checks against Vercel preview deployments, built on [linkinator](https://github.com/JustinBeckwith/linkinator).
+
+Fresh deployments answer some first requests with errors: image optimization (`/_next/image?url=…`) from a function that has just started often returns `400`, hundreds of URLs at once. A plain crawl fails on these. This tool:
+
+1. crawls the site (with linkinator's own retries for 5xx and network errors),
+2. waits a few seconds,
+3. requests every broken link **again, at low concurrency**,
+4. reports links that work now as **warnings** ("flaky") and only fails (exit code `1`) for links that are still broken.
+
+It also handles Vercel's deployment protection (bypass header, and a check that the start URL isn't the login page) and can downgrade known-unfixable links (e.g. third-party content) to warnings.
+
+Requires [Bun](https://bun.sh) (the package ships TypeScript source and runs with a Bun shebang).
+
+## Install
+
+```bash
+bun add -d @lhechenberger/check-links
+```
+
+## Usage
+
+```bash
+bunx check-links https://my-preview.example.vercel.app
+bunx check-links                      # uses `url` from the config, e.g. the local dev server
+bunx check-links <url> --config ci/check-links.config.ts
+```
+
+Set `VERCEL_AUTOMATION_BYPASS_SECRET` (Vercel project → Deployment Protection → Protection Bypass for Automation) to check protected deployments. The secret is sent as `x-vercel-protection-bypass` header, also to the second requests (same-origin only, never to third parties).
+
+The last line of the output is a one-line summary (`Checked N links on <origin>: X broken, Y warnings`); the exit code is `1` if `X > 0`.
+
+## Configuration
+
+Optional `check-links.config.ts` in the working directory:
+
+```ts
+import { defineConfig } from '@lhechenberger/check-links';
+
+export default defineConfig({
+  url: 'http://localhost:3000',
+  // Never checked. Strings are regular expression sources.
+  skip: [/^https:\/\/www\.instagram\.com\//, String.raw`^https://example\.org/`],
+  // Broken links that must not fail the check, e.g. content you can't fix. Not re-requested.
+  isWarningOnly: (link, { origin, url }) =>
+    !link.url.startsWith(origin) && new URL(link.parent ?? url).pathname.startsWith('/docs/'),
+  warningTitle: 'Broken links in embedded READMEs',
+  retryAfterMs: 5000, // wait before the second request
+  recheckConcurrency: 5, // parallel second requests
+  concurrency: 20, // parallel requests of the crawl
+  timeout: 30_000,
+});
+```
+
+| Option               | Default | Description                                          |
+| -------------------- | ------- | ---------------------------------------------------- |
+| `url`                | –       | Used when no URL is passed on the command line       |
+| `skip`               | `[]`    | Links not to check                                   |
+| `isWarningOnly`      | –       | `(link, { origin, url }) => boolean`                 |
+| `warningTitle`       | generic | Heading for the `isWarningOnly` links                |
+| `retryAfterMs`       | `5000`  | Wait before broken links are requested a second time |
+| `recheckConcurrency` | `5`     | Parallel second requests; keep low (see above)       |
+| `concurrency`        | `20`    | Parallel requests of the crawl                       |
+| `timeout`            | `30000` | Timeout per request in ms                            |
+
+## GitHub workflow: check every Vercel deployment
+
+The package contains a workflow template that runs the check when Vercel reports a ready deployment, shows the result as a **"Broken Links" check run** on the deployed commit (so it appears on the pull request, with the full output) and reports the commit status that Vercel's Deployment Checks can require before a production deployment gets its domain.
+
+```bash
+bunx check-links init-workflow          # writes .github/workflows/broken-links.yml
+```
+
+Setup:
+
+1. Add the repository secret `VERCEL_AUTOMATION_BYPASS_SECRET` (same value as in the Vercel project's protection bypass).
+2. In Vercel, enable Deployment Checks / the `repository_dispatch` events for the project, so it sends `vercel.deployment.ready`.
+3. Commit the workflow to the **default branch** (GitHub runs `repository_dispatch` workflows only from there).
+4. Adjust the "Check for broken links" step if the package isn't a dependency of the repository root (e.g. `bun --cwd=apps/web run …`), and optionally remove the "Report to Vercel" step.
+5. Run it once by hand: Actions → Broken Links → Run workflow, with a deployment URL.
+
+Without the secret, production deployments fail the job (they would be held back anyway) and previews are skipped with a warning.
+
+## Local development of the checks
+
+`bun test` runs the unit tests of the classification (flaky vs. real errors).
+
+## Programmatic API
+
+```ts
+import { classify, run, defineConfig } from '@lhechenberger/check-links';
+```
+
+`run(url, config)` crawls and prints, and resolves to the exit code; `classify` is the pure part that sorts broken links into `errors`, `flaky` and `warnings`.
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@lhechenberger/check-links",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "Crawls a deployed site for broken links, separating flaky failures from real ones. Built for Vercel preview deployments.",
+  "keywords": [
+    "broken-links",
+    "link-checker",
+    "linkinator",
+    "vercel",
+    "ci"
+  ],
+  "homepage": "https://github.com/LukasHechenberger/workbench/tree/main/packages/check-links#readme",
+  "bugs": {
+    "url": "https://github.com/LukasHechenberger/workbench/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LukasHechenberger/workbench.git",
+    "directory": "packages/check-links"
+  },
+  "license": "MIT",
+  "author": "Lukas Hechenberger",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": {
+    "check-links": "src/cli.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "templates"
+  ],
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "linkinator": "^8.1.0"
+  },
+  "engines": {
+    "bun": ">=1.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/classify.ts

@@ -0,0 +1,45 @@
+import type { LinkResult } from 'linkinator';
+
+export interface Classification {
+  /** Still broken on the second request */
+  errors: LinkResult[];
+  /** Worked on the second request */
+  flaky: LinkResult[];
+  /** Broken, but allowed to be (see `isWarningOnly`) */
+  warnings: LinkResult[];
+}
+
+export interface ClassifyOptions {
+  isWarningOnly: (link: LinkResult) => boolean;
+  /** Requests `link` again and tells whether it works now */
+  recovers: (link: LinkResult) => Promise<boolean>;
+  /** Waits before the second pass; only called if there is something to re-request */
+  wait: () => Promise<void>;
+  /** Parallel `recovers` calls */
+  concurrency: number;
+}
+
+/**
+ * Sorts broken links into real errors, flaky links (fine on a second request) and tolerated
+ * warnings. Fresh deployments answer some first requests with errors, e.g. image optimizations
+ * from a function that has just started, so a failure on the first request isn't proof.
+ */
+export async function classify(
+  broken: LinkResult[],
+  { isWarningOnly, recovers, wait, concurrency }: ClassifyOptions,
+): Promise<Classification> {
+  const warnings = broken.filter((link) => isWarningOnly(link));
+  const toRecheck = broken.filter((link) => !isWarningOnly(link));
+  const errors: LinkResult[] = [];
+  const flaky: LinkResult[] = [];
+  if (toRecheck.length === 0) return { errors, flaky, warnings };
+
+  await wait();
+  // A burst of requests is what failed in the first place, so the second pass is gentle
+  for (let i = 0; i < toRecheck.length; i += concurrency) {
+    const batch = toRecheck.slice(i, i + concurrency);
+    const results = await Promise.all(batch.map((link) => recovers(link)));
+    for (const [index, link] of batch.entries()) (results[index] ? flaky : errors).push(link);
+  }
+  return { errors, flaky, warnings };
+}

package/src/cli.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env bun
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import type { CheckLinksConfig } from './config.ts';
+import { run } from './run.ts';
+
+const usage = `Usage:
+  check-links [url] [--config check-links.config.ts]
+  check-links init-workflow [path]   Writes the GitHub workflow template (default .github/workflows/broken-links.yml)`;
+
+const { positionals, values } = parseArgs({
+  allowPositionals: true,
+  options: { config: { type: 'string' }, help: { type: 'boolean', short: 'h' } },
+});
+
+if (values.help) {
+  console.log(usage);
+  process.exit(0);
+}
+
+if (positionals[0] === 'init-workflow') {
+  const target = resolve(positionals[1] ?? '.github/workflows/broken-links.yml');
+  if (existsSync(target)) {
+    console.error(`${target} exists already`);
+    process.exit(1);
+  }
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(
+    target,
+    readFileSync(new URL('../templates/broken-links.yml', import.meta.url), 'utf8'),
+  );
+  console.log(`Wrote ${target}. See the README for the setup it needs.`);
+  process.exit(0);
+}
+
+const configPath = resolve(values.config ?? 'check-links.config.ts');
+let config: CheckLinksConfig = {};
+if (existsSync(configPath)) {
+  config = ((await import(configPath)) as { default: CheckLinksConfig }).default;
+} else if (values.config) {
+  console.error(`Config ${configPath} not found`);
+  process.exit(1);
+}
+
+const url = positionals[0] ?? config.url;
+if (!url) {
+  console.error(`No URL given.\n\n${usage}`);
+  process.exit(1);
+}
+
+process.exit(await run(url, config));

package/src/config.ts

@@ -0,0 +1,33 @@
+import type { LinkResult } from 'linkinator';
+
+export interface LinkContext {
+  /** Origin of the checked site, e.g. `https://preview.example.com` */
+  origin: string;
+  /** The URL the crawl started at */
+  url: string;
+}
+
+export interface CheckLinksConfig {
+  /** URL to check when none is passed on the command line (e.g. the local dev server) */
+  url?: string;
+  /** Links not to check. Strings are matched as regular expression sources. */
+  skip?: (string | RegExp)[];
+  /**
+   * Broken links that only count as warnings (e.g. content you don't control). They are not
+   * requested a second time.
+   */
+  isWarningOnly?: (link: LinkResult, context: LinkContext) => boolean;
+  /** Heading printed above the `isWarningOnly` links */
+  warningTitle?: string;
+  /** Wait before broken links are requested a second time (ms), default 5000 */
+  retryAfterMs?: number;
+  /** Parallel requests of the second pass, default 5. Low on purpose: see the README. */
+  recheckConcurrency?: number;
+  /** Parallel requests of the crawl, default 20 */
+  concurrency?: number;
+  /** Timeout per request (ms), default 30000 */
+  timeout?: number;
+}
+
+/** Type helper for `check-links.config.ts` */
+export const defineConfig = (config: CheckLinksConfig): CheckLinksConfig => config;

package/src/index.ts

@@ -0,0 +1,3 @@
+export { classify, type Classification, type ClassifyOptions } from './classify.ts';
+export { defineConfig, type CheckLinksConfig, type LinkContext } from './config.ts';
+export { run } from './run.ts';

package/src/run.ts

@@ -0,0 +1,84 @@
+import { check, type LinkResult, LinkState } from 'linkinator';
+import { classify } from './classify.ts';
+import type { CheckLinksConfig } from './config.ts';
+
+const BYPASS_ENV = 'VERCEL_AUTOMATION_BYPASS_SECRET';
+
+/** Crawls `url` and prints the result. Returns the process exit code. */
+export async function run(url: string, config: CheckLinksConfig): Promise<number> {
+  const { origin } = new URL(url);
+  const bypassSecret = process.env[BYPASS_ENV];
+  // Lets the crawler through Vercel's deployment protection
+  const headers: Record<string, string> = bypassSecret
+    ? { 'x-vercel-protection-bypass': bypassSecret }
+    : {};
+
+  // A protected deployment redirects to Vercel's login page, which linkinator would happily
+  // check instead of the site
+  const start = await fetch(url, { headers, redirect: 'manual' });
+  if (!start.ok) {
+    console.error(
+      `${url} answered with ${start.status} ${start.headers.get('location') ?? ''}`.trim() +
+        (bypassSecret ? '' : `\nIf the deployment is protected, set ${BYPASS_ENV}.`),
+    );
+    return 1;
+  }
+
+  const skip = (config.skip ?? []).map((pattern) =>
+    typeof pattern === 'string' ? new RegExp(pattern) : pattern,
+  );
+  const { links } = await check({
+    path: url,
+    recurse: true,
+    concurrency: config.concurrency ?? 20,
+    timeout: config.timeout ?? 30_000,
+    // Retries 5xx responses and network errors, which are mostly temporary
+    retryErrors: true,
+    retryErrorsCount: 2,
+    retry: true,
+    headers,
+    linksToSkip: async (link) => skip.some((pattern) => pattern.test(link)),
+  });
+
+  const isWarningOnly = (link: LinkResult) =>
+    config.isWarningOnly?.(link, { origin, url }) ?? false;
+
+  /** Whether `link` works when requested again, a while after the crawl */
+  const recovers = async (link: LinkResult) => {
+    try {
+      const response = await fetch(link.url, {
+        headers: link.url.startsWith(origin) ? headers : {},
+      });
+      await response.body?.cancel();
+      return response.ok;
+    } catch {
+      return false;
+    }
+  };
+
+  const broken = links.filter((link) => link.state === LinkState.BROKEN);
+  const { errors, flaky, warnings } = await classify(broken, {
+    isWarningOnly,
+    recovers,
+    wait: () => new Promise((resolve) => setTimeout(resolve, config.retryAfterMs ?? 5000)),
+    concurrency: config.recheckConcurrency ?? 5,
+  });
+
+  const print = (title: string, results: LinkResult[]) => {
+    if (results.length === 0) return;
+    console.log(`\n${title}`);
+    for (const link of results) {
+      console.log(`  [${link.status ?? 'error'}] ${link.url}\n    on ${link.parent}`);
+    }
+  };
+
+  print(`${config.warningTitle ?? 'Broken links that are only warnings'} (warnings):`, warnings);
+  print('Links that worked on a second request (warnings):', flaky);
+  print('Broken links:', errors);
+  // The last line is the summary the workflow shows as the check run's title
+  console.log(
+    `\nChecked ${links.length} links on ${origin}: ${errors.length} broken, ${warnings.length + flaky.length} warnings`,
+  );
+
+  return errors.length > 0 ? 1 : 0;
+}

package/templates/broken-links.yml

@@ -0,0 +1,116 @@
+name: Broken Links
+
+on:
+  # Sent by Vercel once a deployment is ready. Runs the workflow file on the default branch.
+  repository_dispatch:
+    types:
+      - 'vercel.deployment.ready'
+  workflow_dispatch:
+    inputs:
+      url:
+        type: string
+        description: The URL of the deployed site to check
+        required: true
+
+permissions:
+  contents: read
+  checks: write
+  statuses: write
+
+jobs:
+  broken-links:
+    # Differs from the check run's name below, so the two don't collide
+    name: Crawl deployment
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      URL: ${{ github.event.client_payload.url || inputs.url }}
+      SHA: ${{ github.event.client_payload.git.sha || github.sha }}
+      ENVIRONMENT: ${{ github.event.client_payload.environment || 'manual' }}
+      VERCEL_AUTOMATION_BYPASS_SECRET: ${{ secrets.VERCEL_AUTOMATION_BYPASS_SECRET }}
+    steps:
+      # Sets the commit status "Broken Links | broken-links (<project> - <environment>)" that the
+      # project's Deployment Checks can require before production deployments get the domain:
+      # pending now, and failed or passed once the job is done. Remove if you don't use them.
+      - name: Report to Vercel
+        uses: vercel/repository-dispatch/actions/status@v1
+
+      # Vercel sends the deployment's own URL, which is protected for production deployments too.
+      # Without the secret, production fails and previews are skipped.
+      - name: Require a bypass secret for deployments
+        id: guard
+        run: |
+          echo "Checking $URL ($ENVIRONMENT) at $SHA"
+          if [ "${{ github.event_name }}" = "repository_dispatch" ] && [ -z "$VERCEL_AUTOMATION_BYPASS_SECRET" ]; then
+            if [ "$ENVIRONMENT" = "production" ]; then
+              echo "::error::Set the VERCEL_AUTOMATION_BYPASS_SECRET secret to check production deployments"
+              exit 1
+            fi
+            echo "::warning::Set the VERCEL_AUTOMATION_BYPASS_SECRET secret to check preview deployments"
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Check out code
+        if: steps.guard.outputs.skip != 'true'
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ env.SHA }}
+
+      - name: Setup Bun
+        if: steps.guard.outputs.skip != 'true'
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        if: steps.guard.outputs.skip != 'true'
+        run: bun install --frozen-lockfile
+
+      # Shows up next to the other checks of the deployed commit, also on its pull request
+      - name: Create check run
+        if: steps.guard.outputs.skip != 'true'
+        id: check_run
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const { data } = await github.rest.checks.create({
+              ...context.repo,
+              name: 'Broken Links',
+              head_sha: process.env.SHA,
+              status: 'in_progress',
+              details_url: `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+            });
+            return data.id;
+
+      - name: Check for broken links
+        if: steps.guard.outputs.skip != 'true'
+        # Adjust to where @lhechenberger/check-links is installed (or add a package script)
+        run: |
+          set -o pipefail
+          bunx check-links "$URL" | tee broken-links.txt
+
+      - name: Complete check run
+        if: ${{ !cancelled() && steps.check_run.outputs.result }}
+        uses: actions/github-script@v8
+        env:
+          CHECK_RUN_ID: ${{ steps.check_run.outputs.result }}
+          OUTCOME: ${{ job.status }}
+        with:
+          script: |
+            const fs = require('node:fs');
+            const output = fs.existsSync('broken-links.txt')
+              ? fs.readFileSync('broken-links.txt', 'utf8')
+              : 'The check did not run.';
+            const conclusion = process.env.OUTCOME === 'success' ? 'success' : 'failure';
+            const summary = output.trim().split('\n').at(-1);
+
+            await github.rest.checks.update({
+              ...context.repo,
+              check_run_id: Number(process.env.CHECK_RUN_ID),
+              status: 'completed',
+              conclusion,
+              output: {
+                title: summary,
+                summary: `${process.env.URL} (${process.env.ENVIRONMENT})`,
+                // Check run texts are limited to 65,535 characters
+                text: '```\n' + output.slice(-60_000) + '\n```',
+              },
+            });