sireg

sireg is a Node.js CLI and npm package for website regression checks. Give it a sitemap, a URL file, or a handful of URLs; it fetches the pages, follows redirects, and tells you whether the final responses are healthy.

It is built for the release moment where you need a quick answer: did this deployment break important pages, staging routes, or SEO redirects?

Why sireg?

• Load URLs from sitemap files, hosted sitemaps, sitemap indexes, nested sitemap indexes, URL files, or direct CLI input.
• Rewrite production sitemap URLs to local dev, preview, or staging hosts.
• Check all URLs, the first N URLs, a deterministic random sample, or a percentage of a large site.
• Verify retired URLs that are no longer in the sitemap still return a 30x redirect and land on a 2xx page.
• Produce readable console output plus Markdown, JSON, and polished HTML reports for CI artifacts.
• Use it as npx sireg or import the typed TypeScript API in your own tooling.

Quick Start

npx sireg check --sitemap https://example.com/sitemap.xml

Check a local build using the production sitemap:

npx sireg check \
  --sitemap https://example.com/sitemap.xml \
  --origin http://localhost:3000

Create build artifacts:

npx sireg check \
  --sitemap https://example.com/sitemap.xml \
  --origin http://localhost:3000 \
  --markdown reports/sireg.md \
  --html reports/sireg.html

sireg exits with 0 when every check passes and 1 when any URL or redirect expectation fails.

Configuration

For CI and teams, commit a config file:

{
  "$schema": "./sireg.schema.json",
  "name": "Website regression check",
  "sources": [
    {
      "type": "sitemap",
      "url": "https://example.com/sitemap.xml"
    }
  ],
  "transforms": [
    {
      "origin": "http://localhost:3000"
    }
  ],
  "select": {
    "strategy": "random",
    "limit": 250,
    "seed": "pull-request"
  },
  "checks": {
    "expectedStatus": "2xx",
    "concurrency": 8,
    "timeout": 10000
  },
  "redirects": [
    {
      "from": "https://example.com/old-page",
      "to": "https://example.com/new-page",
      "expectedStatus": "30x",
      "finalStatus": "2xx"
    }
  ],
  "reports": [
    { "type": "console" },
    { "type": "markdown", "path": "reports/sireg.md" },
    { "type": "html", "path": "reports/sireg.html" }
  ]
}

Run it:

npx sireg check --config sireg.config.json

See configuration and reports for the full model.

GitHub Actions

This example starts a local app, checks the production sitemap against that local app, and uploads Markdown/HTML reports as artifacts.

name: Website regression

on: [pull_request]

jobs:
  sireg:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run build
      - run: npm run start &
      - run: npx sireg check --config sireg.config.json
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: sireg-report
          path: reports/

If your site is too large for every pull request, use a deterministic sample:

{
  "select": {
    "strategy": "random",
    "limit": 500,
    "seed": "${{ github.sha }}"
  }
}

For nightly builds, switch back to "strategy": "all".

CLI

sireg check --sitemap <url-or-file> [options]
sireg check --config <path>
sireg test <config>

Useful options:

• --sitemap <value>: Load URLs from a sitemap or sitemap index.
• --file <path>: Load newline-delimited URLs from a file.
• --url <url>: Check one URL directly.
• --origin <origin>: Replace each discovered URL origin.
• --replace <from=to>: Replace text in each URL.
• --strategy <all|first|random|percent>: Choose URL selection strategy.
• --limit <number|all>: Limit selected URLs.
• --expect-status <rule>: Expected final status, such as 2xx, 200, or 200-204.
• --markdown <path> and --html <path>: Write report artifacts.
• --no-progress: Disable the interactive spinner, progress bar, and live pass/fail stats.

When run in an interactive terminal, sireg shows live progress while it loads sources and checks URLs. CI and non-TTY environments keep deterministic output.

Redirect Checks

Sitemaps usually contain current URLs, not retired ones. That means sitemap checks alone cannot prove old URLs still redirect correctly.

Add explicit redirect expectations:

{
  "redirects": [
    {
      "from": "https://example.com/products/old-slug",
      "toPattern": "^https://example.com/products/new-slug/?$",
      "expectedStatus": "30x",
      "finalStatus": "2xx"
    }
  ]
}

sireg verifies the first response redirects, follows the chain, checks the final URL when requested, and confirms the final page is healthy.

Programmatic API

import { runSireg } from 'sireg';

const report = await runSireg({
  name: 'Preview check',
  sources: [{ type: 'sitemap', url: 'https://example.com/sitemap.xml' }],
  transforms: [{ origin: 'http://localhost:3000' }],
});

console.log(report.summary.successRate);

Development

npm install
npm test

The project is written in TypeScript, uses native Node.js APIs, and has no runtime dependencies.

See releasing for the npm publish flow.

Contributing

Issues and pull requests are welcome. Good contributions make sireg easier to trust in CI: clearer reports, stronger tests, better examples, and integrations with common website stacks.

License

MIT