@nialto-services/astro-site-checks 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nialto Services
+
+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

@@ -0,0 +1,98 @@
+# @nialto-services/astro-site-checks
+
+Post-build checks for Nialto's Astro sites. Each one reads the built site in `dist/client` and fails when
+something is wrong that the build itself never complains about: a link to a page that does not exist, a
+redirect that has stopped working, a scoped style rule that can never apply, or a page loading from an
+origin the site's Content-Security-Policy does not allow.
+
+The checks used to live as scripts copied into each site, and the copies drifted. This package is the one
+copy every site runs.
+
+## Install
+
+```sh
+pnpm add -D @nialto-services/astro-site-checks
+```
+
+Then add the four scripts every site uses to its `package.json`:
+
+```json
+"lint:links": "astro-site-checks links",
+"lint:redirects": "astro-site-checks redirects",
+"lint:css-scope": "astro-site-checks css-scope",
+"lint:headers": "astro-site-checks headers"
+```
+
+Every check reads the built site, so run it after `astro build`. Each one checks `dist/client` by default;
+pass `--dir <path>` to check another directory.
+
+## The checks
+
+### `links`
+
+Fails when a root-relative link in any built page points at a path the build does not serve. Each broken
+target is listed once, with up to five of the pages that link to it.
+
+A link to the source of a redirect is a warning rather than a failure: it resolves, but through a 301, so it
+is worth linking straight to the destination.
+
+Links to other hosts, including protocol-relative ones (`//cdn.example.com/…`), `mailto:` and `tel:` links,
+in-page anchors and absolute links back to the site's own host are not checked.
+
+### `redirects`
+
+Checks every rule in the built `_redirects` for four faults:
+
+- a target the build does not serve;
+- a source the build serves as a real page, so the rule can never fire;
+- a target that is itself the source of another rule, which makes a chain;
+- a page rule without its other trailing-slash spelling pointing at the same target. Cloudflare matches a
+  rule's source exactly, so without both spellings one of them lands on a 404.
+
+A placeholder (`:name`, `*`) or a target on another host is skipped only by the faults that would have to
+resolve it: a placeholder rule's concrete target is still checked, and so is the source of a rule pointing at
+another host. A site with no `_redirects` passes.
+
+### `css-scope`
+
+Fails when a scoped style rule can never match the element it targets. Astro scopes a component's styles to
+the elements that component renders, so styling a child component's root element by class compiles to a rule
+that silently does nothing. A class that never appears in the built pages is left alone, since it is either
+added at runtime or belongs to a component nothing renders.
+
+### `headers`
+
+Fails when a built page loads a script, image, frame, stylesheet or preloaded file from an origin the site's
+Content-Security-Policy does not allow. The enforced `Content-Security-Policy` header is read if the site ships
+one, otherwise `Content-Security-Policy-Report-Only`.
+
+Every site ships a policy, so a site whose built `_headers` has none fails this check. Origins a tag manager
+injects while the page runs cannot be seen by a check of the built files.
+
+## Configuration
+
+A site sets options under `astroSiteChecks` in its `package.json`. There is one:
+
+```json
+"astroSiteChecks": {
+  "headers": {
+    "ungovernedPaths": ["mockups/"]
+  }
+}
+```
+
+`headers.ungovernedPaths` lists path prefixes, relative to the built site, whose pages the policy does not
+govern: pages a site serves but did not author, such as design mock-ups reproduced as they were delivered.
+The `headers` check skips them.
+
+## Exit codes
+
+| Code | Meaning                                |
+| ---- | -------------------------------------- |
+| 0    | The check passed.                      |
+| 1    | The check failed; the output says why. |
+| 2    | Unknown or missing check name.         |
+
+## Licence
+
+MIT

package/bin/astro-site-checks.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path'
+import { DEFAULT_CLIENT_DIRECTORY } from '../src/built-site.mjs'
+import { checkHeaders, checkLinks, checkRedirects, checkScopedCSS } from '../src/index.mjs'
+
+const CHECKS = { links: checkLinks, redirects: checkRedirects, 'css-scope': checkScopedCSS, headers: checkHeaders }
+
+const USAGE = `Usage: astro-site-checks <${Object.keys(CHECKS).join('|')}> [--dir <built client directory>]
+
+Runs one post-build check against the built site (default: ${DEFAULT_CLIENT_DIRECTORY}). Run after astro build.`
+
+const [name, ...options] = process.argv.slice(2)
+
+if (name === '--help' || name === '-h') {
+  console.log(USAGE)
+  process.exit(0)
+}
+
+const check = CHECKS[name]
+if (!check) {
+  console.error(USAGE)
+  process.exit(2)
+}
+
+const directoryIndex = options.indexOf('--dir')
+const directory = directoryIndex === -1 ? DEFAULT_CLIENT_DIRECTORY : options[directoryIndex + 1]
+if (!directory || directory.startsWith('--')) {
+  console.error(USAGE)
+  process.exit(2)
+}
+
+// A site's own mistake, such as an unreadable package.json, is reported as its message: a stack trace
+// would read as a fault in this package.
+try {
+  const passed = await check({ clientDirectory: resolve(directory), siteDirectory: process.cwd(), report: console })
+  process.exit(passed ? 0 : 1)
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@nialto-services/astro-site-checks",
+  "version": "0.1.1",
+  "description": "Post-build checks for Nialto's Astro sites: internal links, redirects, scoped CSS and the Content-Security-Policy.",
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "pnpm@10.30.2",
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NialtoServices/astro-site-checks.git"
+  },
+  "bin": {
+    "astro-site-checks": "./bin/astro-site-checks.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "devDependencies": {
+    "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
+    "prettier": "^3.9.9",
+    "vitest": "^5.0.2"
+  }
+}

package/src/built-site.mjs

@@ -0,0 +1,75 @@
+/**
+ * A built Astro site as the checks need to see it: which files the client directory holds, which
+ * paths those serve, and which internal links a page carries.
+ *
+ * Every check reads the site through these, so the link check and the redirect check cannot drift
+ * apart over what "this path resolves" means.
+ */
+import { readdir } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+
+/** Where `astro build` writes the files a site serves, relative to the site's root. */
+export const DEFAULT_CLIENT_DIRECTORY = 'dist/client'
+
+const HREF_PATTERN = /href="([^"]+)"/g
+
+/** Every file under a directory, at any depth. */
+export async function collectBuiltFiles(directory) {
+  const entries = await readdir(directory, { withFileTypes: true })
+  const files = await Promise.all(
+    entries.map((entry) => {
+      const path = join(directory, entry.name)
+      return entry.isDirectory() ? collectBuiltFiles(path) : [path]
+    })
+  )
+
+  return files.flat()
+}
+
+/** A built file's path as it would appear in an href, so `…/index.html` reads as its directory. */
+export function servedPathOf(directory, file) {
+  return `/${relative(directory, file)}`.replace(/index\.html$/, '')
+}
+
+/** Every path the built site can serve, as it would appear in an href. */
+export async function collectServablePaths(directory) {
+  const servablePaths = new Set()
+  for (const file of await collectBuiltFiles(directory)) {
+    const path = `/${relative(directory, file)}`
+    servablePaths.add(path)
+
+    if (path.endsWith('/index.html')) servablePaths.add(path.replace(/index\.html$/, ''))
+  }
+
+  return servablePaths
+}
+
+/**
+ * Whether a path resolves against the built site, allowing for the trailing slash
+ * `trailingSlash: 'always'` adds and for a directory's `index.html`.
+ */
+export function isServable(servablePaths, path) {
+  if (servablePaths.has(path)) return true
+
+  return servablePaths.has(`${path}/`) || servablePaths.has(`${path}/index.html`)
+}
+
+/**
+ * Every root-relative href in a page, reduced to a path, with fragments and query strings dropped.
+ *
+ * `mailto:`, `tel:`, in-page fragments and links to other hosts are out of scope: their targets are not
+ * ours to guarantee. A protocol-relative href (`//host/path`) names another host despite its leading
+ * slash. Absolute links back to the site's own host are skipped too, because the head's canonical and
+ * pagination tags are absolute on purpose; an absolute link in body copy therefore goes unchecked, which
+ * is why internal links are authored root-relative.
+ */
+export function extractInternalPaths(html) {
+  const paths = []
+  for (const [, href] of html.matchAll(HREF_PATTERN)) {
+    if (!href.startsWith('/') || href.startsWith('//')) continue
+
+    paths.push(href.replace(/[#?].*$/, ''))
+  }
+
+  return paths
+}

package/src/checks/built.mjs

@@ -0,0 +1,18 @@
+import { readFile, stat } from 'node:fs/promises'
+
+/** Whether the site has been built, reporting how to fix it when it has not. */
+export async function requireBuiltSite(clientDirectory, report) {
+  const found = await stat(clientDirectory).then(
+    (entry) => entry.isDirectory(),
+    () => false
+  )
+  if (found) return true
+
+  report.error(`No built site at ${clientDirectory}. Run \`astro build\` first.`)
+  return false
+}
+
+/** A built file's contents, or `undefined` when the build did not produce it. */
+export function readOptionalFile(path) {
+  return readFile(path, 'utf-8').catch(() => undefined)
+}

package/src/checks/css-scope.mjs

@@ -0,0 +1,47 @@
+/** Fails when a scoped CSS rule in the built site can never match the element it targets. */
+import { readFile } from 'node:fs/promises'
+import { relative } from 'node:path'
+import { collectBuiltFiles, servedPathOf } from '../built-site.mjs'
+import { extractStyleBlocks, findUnmatchedScopedRules } from '../scoped-css.mjs'
+import { requireBuiltSite } from './built.mjs'
+
+const SOURCES_LISTED_PER_RULE = 3
+
+export async function checkScopedCSS({ clientDirectory, report }) {
+  if (!(await requireBuiltSite(clientDirectory, report))) return false
+
+  const files = await collectBuiltFiles(clientDirectory)
+  const pages = []
+  const styleSheets = []
+  for (const file of files.filter((path) => path.endsWith('.html'))) {
+    const markup = await readFile(file, 'utf-8')
+    const source = servedPathOf(clientDirectory, file)
+
+    pages.push({ source, markup })
+    for (const css of extractStyleBlocks(markup)) styleSheets.push({ source, css })
+  }
+
+  for (const file of files.filter((path) => path.endsWith('.css'))) {
+    styleSheets.push({ source: relative(clientDirectory, file), css: await readFile(file, 'utf-8') })
+  }
+
+  const unmatched = findUnmatchedScopedRules(pages, styleSheets)
+  if (unmatched.size > 0) {
+    report.error(`\nScoped rules that can never match the element they target (${unmatched.size}):\n`)
+    for (const [selector, rule] of unmatched) {
+      report.error(`  ${selector}`)
+      report.error(`      .${rule.className} only ever renders with: ${Array.from(rule.rendered).join(', ')}`)
+      report.error(`      declared in ${Array.from(rule.sources).slice(0, SOURCES_LISTED_PER_RULE).join(', ')}`)
+    }
+    report.error(
+      '\nA component cannot style an element it does not render. Pass a prop, or declare a custom\n' +
+        'property on an element it does own and let it inherit down.\n'
+    )
+    return false
+  }
+
+  report.log(
+    `Scoped CSS OK: checked ${styleSheets.length} stylesheets against ${pages.length} pages, every rule can match.`
+  )
+  return true
+}

package/src/checks/headers.mjs

@@ -0,0 +1,55 @@
+/**
+ * Fails when a built page loads an origin the site's Content-Security-Policy does not allow, or when the
+ * site ships no policy at all.
+ *
+ * A report-only policy lets the browser load a disallowed resource anyway, so a new third-party include
+ * goes unnoticed until the policy is enforced and it breaks. This closes that gap for everything the markup
+ * itself fetches. Origins a tag manager injects at runtime remain invisible to a static check.
+ */
+import { readFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import { collectBuiltFiles, servedPathOf } from '../built-site.mjs'
+import { readConfig } from '../config.mjs'
+import { findPolicyViolations, parsePolicy } from '../csp.mjs'
+import { readOptionalFile, requireBuiltSite } from './built.mjs'
+
+export async function checkHeaders({ clientDirectory, siteDirectory, report }) {
+  if (!(await requireBuiltSite(clientDirectory, report))) return false
+
+  const { ungovernedPaths } = (await readConfig(siteDirectory)).headers
+  const policy = parsePolicy((await readOptionalFile(join(clientDirectory, '_headers'))) ?? '')
+  if (!policy) {
+    report.error(
+      'No Content-Security-Policy in the built _headers. Every site ships one: add a ' +
+        'Content-Security-Policy-Report-Only header for /* to public/_headers.'
+    )
+    return false
+  }
+
+  const pages = (await collectBuiltFiles(clientDirectory)).filter((file) => {
+    if (!file.endsWith('.html')) return false
+
+    const route = relative(clientDirectory, file)
+    return !ungovernedPaths.some((prefix) => route.startsWith(prefix))
+  })
+
+  const problems = []
+  for (const page of pages) {
+    for (const violation of findPolicyViolations(await readFile(page, 'utf-8'), policy)) {
+      problems.push({ page: servedPathOf(clientDirectory, page), ...violation })
+    }
+  }
+
+  if (problems.length > 0) {
+    report.error(`\nResources loaded from an origin the Content-Security-Policy does not allow (${problems.length}):\n`)
+    for (const problem of problems) {
+      report.error(`  ${problem.origin} (<${problem.kind}>, needs ${problem.directive})`)
+      report.error(`      loaded by ${problem.page}`)
+    }
+    report.error('')
+    return false
+  }
+
+  report.log(`Content-Security-Policy OK: checked ${pages.length} pages, every loaded origin is allowed.`)
+  return true
+}

package/src/checks/links.mjs

@@ -0,0 +1,105 @@
+/**
+ * Fails when an internal link in the built site points at a page that does not exist.
+ *
+ * Content work is exactly when dangling links creep in: pages cross-reference each other, slugs get
+ * renamed, and a link to a page that never gets written is invisible until a visitor hits it.
+ *
+ * A link to a redirect *source* is a warning rather than a failure. It resolves, so nobody lands on a 404,
+ * but the visitor pays a needless 301, so it is worth linking straight to the destination.
+ */
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import {
+  collectBuiltFiles,
+  collectServablePaths,
+  extractInternalPaths,
+  isServable,
+  servedPathOf
+} from '../built-site.mjs'
+import { parseRedirects } from '../redirects.mjs'
+import { readOptionalFile, requireBuiltSite } from './built.mjs'
+
+const SOURCES_LISTED_PER_LINK = 5
+
+/** Pages that link to each path, so a repeated mistake reads as one entry with its sources. */
+function groupByPath(findings) {
+  const grouped = new Map()
+  for (const { from, path } of findings) {
+    const sources = grouped.get(path) ?? new Set()
+    sources.add(from)
+    grouped.set(path, sources)
+  }
+
+  return grouped
+}
+
+/**
+ * A link in shared chrome appears on every page, and a list that long buries the other findings, so each
+ * one names a handful of pages and counts the rest.
+ */
+function listFindings(grouped, describeTarget, write) {
+  for (const [path, sources] of grouped) {
+    write(`  ${path}${describeTarget(path)}`)
+
+    const named = Array.from(sources).slice(0, SOURCES_LISTED_PER_LINK)
+    for (const source of named) write(`      linked from ${source}`)
+
+    const remaining = sources.size - named.length
+    if (remaining > 0) write(`      …and ${remaining} more page${remaining === 1 ? '' : 's'}`)
+  }
+}
+
+export async function checkLinks({ clientDirectory, report }) {
+  if (!(await requireBuiltSite(clientDirectory, report))) return false
+
+  const redirects = parseRedirects((await readOptionalFile(join(clientDirectory, '_redirects'))) ?? '')
+  const servablePaths = await collectServablePaths(clientDirectory)
+  const pages = (await collectBuiltFiles(clientDirectory)).filter((file) => file.endsWith('.html'))
+
+  const broken = []
+  const redirected = []
+  for (const page of pages) {
+    const html = await readFile(page, 'utf-8')
+    const from = servedPathOf(clientDirectory, page)
+
+    for (const path of extractInternalPaths(html)) {
+      if (redirects.has(path)) {
+        redirected.push({ from, path })
+        continue
+      }
+
+      if (isServable(servablePaths, path)) continue
+
+      broken.push({ from, path })
+    }
+  }
+
+  if (redirected.length > 0) {
+    const grouped = groupByPath(redirected)
+    report.warn(`\nInternal links pointing at a redirect source (${grouped.size}):\n`)
+    listFindings(
+      grouped,
+      (path) => ` -> ${redirects.get(path)}`,
+      (line) => report.warn(line)
+    )
+    report.warn('\nThese resolve, but through a 301. Link straight to the destination.\n')
+  }
+
+  if (broken.length > 0) {
+    const grouped = groupByPath(broken)
+    report.error(`\nBroken internal links (${grouped.size}):\n`)
+    listFindings(
+      grouped,
+      () => '',
+      (line) => report.error(line)
+    )
+    report.error('')
+    return false
+  }
+
+  report.log(
+    `Internal links OK: checked ${pages.length} pages, every internal link resolves` +
+      `${redirected.length > 0 ? `, ${redirected.length} through a redirect` : ''}.`
+  )
+  return true
+}

package/src/checks/redirects.mjs

@@ -0,0 +1,75 @@
+/**
+ * Fails when a rule in the built `_redirects` can no longer do its job: a target the build does not serve,
+ * a source the build serves as a real page (so the rule can never fire), a target that is itself another
+ * rule's source (a chain), or a page rule carried in only one trailing-slash spelling.
+ *
+ * A site with nothing to redirect has no `_redirects`, which passes.
+ */
+import { join } from 'node:path'
+import { collectServablePaths } from '../built-site.mjs'
+import {
+  findBrokenTargets,
+  findMissingSpellings,
+  findRedirectChains,
+  findShadowedSources,
+  parseRedirects
+} from '../redirects.mjs'
+import { readOptionalFile, requireBuiltSite } from './built.mjs'
+
+function reportFaults(report, heading, faults, describe, remedy) {
+  if (faults.length === 0) return false
+
+  report.error(`\n${heading} (${faults.length}):\n`)
+  for (const fault of faults) report.error(`  ${describe(fault)}`)
+  report.error(`\n${remedy}\n`)
+
+  return true
+}
+
+export async function checkRedirects({ clientDirectory, report }) {
+  if (!(await requireBuiltSite(clientDirectory, report))) return false
+
+  const text = await readOptionalFile(join(clientDirectory, '_redirects'))
+  if (text === undefined) {
+    report.log('No _redirects in the built site: nothing to check.')
+    return true
+  }
+
+  const redirects = parseRedirects(text)
+  const servablePaths = await collectServablePaths(clientDirectory)
+
+  const failures = [
+    reportFaults(
+      report,
+      'Redirects pointing at a path the build does not serve',
+      findBrokenTargets(redirects, servablePaths),
+      ({ source, target }) => `${source} -> ${target}`,
+      'Point the rule at a page that exists, or drop it if the destination has gone for good.'
+    ),
+    reportFaults(
+      report,
+      'Redirects whose source the build serves as a page, so the rule can never fire',
+      findShadowedSources(redirects, servablePaths),
+      ({ source, target }) => `${source} -> ${target}  (a page is built at ${source})`,
+      'Either remove the rule or stop building the page.'
+    ),
+    reportFaults(
+      report,
+      'Redirect chains',
+      findRedirectChains(redirects),
+      ({ source, target, eventualTarget }) => `${source} -> ${target} -> ${eventualTarget}`,
+      'Flatten the chain: point the first rule straight at the page the second one reaches.'
+    ),
+    reportFaults(
+      report,
+      'Redirects missing their other trailing-slash spelling',
+      findMissingSpellings(redirects),
+      ({ source, missing, target }) => `${source} -> ${target}  (add ${missing} -> ${target})`,
+      'Cloudflare matches a source exactly, so give every page rule both spellings, pointing at the same page.'
+    )
+  ]
+  if (failures.some(Boolean)) return false
+
+  report.log(`Redirects OK: ${redirects.size} rules checked, every target resolves in one hop.`)
+  return true
+}

package/src/config.mjs

@@ -0,0 +1,26 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * A site's options for the checks, read from `astroSiteChecks` in its package.json so there is no extra
+ * config file to keep. A site that sets nothing, or has no package.json, gets the defaults.
+ */
+export async function readConfig(siteDirectory) {
+  const text = await readFile(join(siteDirectory, 'package.json'), 'utf-8').catch(() => '{}')
+
+  let manifest
+  try {
+    manifest = JSON.parse(text)
+  } catch (error) {
+    throw new Error(`The site's package.json is not valid JSON: ${error.message}`, { cause: error })
+  }
+
+  const ungovernedPaths = manifest.astroSiteChecks?.headers?.ungovernedPaths ?? []
+
+  const isPathList = Array.isArray(ungovernedPaths) && ungovernedPaths.every((path) => typeof path === 'string')
+  if (!isPathList) {
+    throw new Error('astroSiteChecks.headers.ungovernedPaths in package.json must be a list of path prefixes')
+  }
+
+  return { headers: { ungovernedPaths } }
+}

package/src/csp.mjs

@@ -0,0 +1,112 @@
+/**
+ * Checks the built pages against the shipped Content-Security-Policy.
+ *
+ * A report-only policy tells nobody anything until real traffic hits it, and the origins a page loads
+ * change as components are added. This closes the gap for the ones the build can see: anything the
+ * markup itself fetches is compared to the policy, so a new external script fails a check here rather
+ * than a browser console after launch. Origins the GTM container injects at runtime are invisible to
+ * this and remain the reason the policy stays report-only.
+ */
+
+const POLICY_HEADERS = ['Content-Security-Policy', 'Content-Security-Policy-Report-Only']
+
+/**
+ * The directives of the site's policy in a `_headers` file: the enforced header when it ships, since that
+ * is the one a browser applies, else the report-only one. A header name inside a comment is not a header.
+ */
+export function parsePolicy(headers) {
+  for (const headerName of POLICY_HEADERS) {
+    const match = headers.match(new RegExp(`^\\s*${headerName}: (.*)$`, 'mi'))
+    if (!match) continue
+
+    const directives = new Map()
+    for (const part of match[1].split(';')) {
+      const [name, ...values] = part.trim().split(/\s+/)
+      if (name) directives.set(name, values)
+    }
+
+    return directives
+  }
+
+  return undefined
+}
+
+/** An attribute's value on one element, or `undefined` when it is absent. */
+function attributeOf(element, name) {
+  return element.match(new RegExp(`\\s${name}="([^"]*)"`, 'i'))?.[1]
+}
+
+/** What a `<link>` loads, judged by its `rel` tokens and, for a preload, what it preloads. */
+const PRELOAD_KIND_FOR_AS = { font: 'font', style: 'style', script: 'script', image: 'img' }
+
+/** Every externally loaded resource in a page, as `{ kind, origin }`. Links are not loads. */
+export function extractLoadedOrigins(html) {
+  const loaded = []
+  for (const match of html.matchAll(/<(script|img|iframe)\b[^>]*?\ssrc="(https?:\/\/[^"]+)"/g)) {
+    loaded.push({ kind: match[1], origin: new URL(match[2]).origin })
+  }
+
+  // Attributes are read from the whole element, since a `<link>` carries `rel`, `href` and `as` in
+  // whatever order its author wrote them.
+  for (const [element] of html.matchAll(/<link\b[^>]*>/gi)) {
+    const href = attributeOf(element, 'href')
+    if (!href || !/^https?:\/\//i.test(href)) continue
+
+    const relations = (attributeOf(element, 'rel') ?? '').toLowerCase().split(/\s+/)
+    if (relations.includes('stylesheet')) {
+      loaded.push({ kind: 'style', origin: new URL(href).origin })
+    } else if (relations.includes('preload')) {
+      const preloaded = (attributeOf(element, 'as') ?? '').toLowerCase()
+      loaded.push({ kind: PRELOAD_KIND_FOR_AS[preloaded] ?? 'preload', origin: new URL(href).origin })
+    }
+  }
+
+  return loaded
+}
+
+const DIRECTIVE_FOR_KIND = {
+  script: 'script-src',
+  img: 'img-src',
+  iframe: 'frame-src',
+  style: 'style-src',
+  font: 'font-src',
+  preload: 'default-src'
+}
+
+/**
+ * Whether a policy source covers an origin. A source may be a scheme (`https:`), a host with or without a
+ * scheme, a host wildcard (`*.a.com`, which covers subdomains and not the domain itself), and may carry a
+ * path, which does not narrow the origin it allows.
+ */
+export function originAllowedBy(source, origin) {
+  if (source === '*' || source === origin) return true
+
+  const { protocol, host } = new URL(origin)
+  if (/^[a-z][a-z0-9+.-]*:$/i.test(source)) return source.toLowerCase() === protocol
+
+  const parts = source.match(/^(?:([a-z][a-z0-9+.-]*):\/\/)?([^/]+)/i)
+  if (!parts) return false
+
+  const [, scheme, sourceHost] = parts
+  if (scheme && `${scheme.toLowerCase()}:` !== protocol) return false
+  if (!sourceHost.startsWith('*.')) return sourceHost.toLowerCase() === host
+
+  return host.endsWith(sourceHost.slice(1).toLowerCase())
+}
+
+/**
+ * Origins a page loads that its policy does not allow, falling back to `default-src` the way a
+ * browser does when a directive is absent.
+ */
+export function findPolicyViolations(html, policy) {
+  const violations = []
+  for (const { kind, origin } of extractLoadedOrigins(html)) {
+    const directive = DIRECTIVE_FOR_KIND[kind] ?? 'default-src'
+    const allowed = policy.get(directive) ?? policy.get('default-src') ?? []
+    if (allowed.some((source) => originAllowedBy(source, origin))) continue
+
+    violations.push({ kind, origin, directive })
+  }
+
+  return violations
+}

package/src/index.mjs

@@ -0,0 +1,22 @@
+export {
+  collectBuiltFiles,
+  collectServablePaths,
+  DEFAULT_CLIENT_DIRECTORY,
+  extractInternalPaths,
+  isServable,
+  servedPathOf
+} from './built-site.mjs'
+export { checkScopedCSS } from './checks/css-scope.mjs'
+export { checkHeaders } from './checks/headers.mjs'
+export { checkLinks } from './checks/links.mjs'
+export { checkRedirects } from './checks/redirects.mjs'
+export { readConfig } from './config.mjs'
+export { extractLoadedOrigins, findPolicyViolations, originAllowedBy, parsePolicy } from './csp.mjs'
+export {
+  findBrokenTargets,
+  findMissingSpellings,
+  findRedirectChains,
+  findShadowedSources,
+  parseRedirects
+} from './redirects.mjs'
+export { extractStyleBlocks, findUnmatchedScopedRules } from './scoped-css.mjs'

package/src/redirects.mjs

@@ -0,0 +1,113 @@
+/**
+ * The rules in a Cloudflare `_redirects` file, and the four ways a rule stops doing its job, as pure
+ * functions over the parsed rules and the paths the build serves.
+ *
+ * A redirect usually carries an inbound link a previous site earned, so a rule that fails loses that link
+ * silently: nothing in the build errors, and the only symptom is a 404 a crawler finds months later.
+ */
+import { isServable } from './built-site.mjs'
+
+/** `source target status` lines, comments and blanks skipped, as a source → target map. */
+export function parseRedirects(text) {
+  const redirects = new Map()
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed === '' || trimmed.startsWith('#')) continue
+
+    const [source, target] = trimmed.split(/\s+/)
+    redirects.set(source, target)
+  }
+
+  return redirects
+}
+
+/**
+ * Whether one side of a rule is a concrete path on this site. A placeholder (`:name`, `*`) matches many
+ * URLs and a target on another host is not ours to resolve, so each fault is checked only on the side it
+ * reads: a placeholder source can still have a broken target, and an external target can still have a
+ * shadowed source.
+ */
+function isConcretePath(path) {
+  return Boolean(path?.startsWith('/')) && !/[:*]/.test(path)
+}
+
+/**
+ * Rules whose target the build does not serve.
+ *
+ * A 301 to a missing page is worse than no rule at all: a crawler follows it, finds nothing, and drops the
+ * old URL without gaining a replacement.
+ */
+export function findBrokenTargets(redirects, servablePaths) {
+  const broken = []
+  for (const [source, target] of redirects) {
+    if (!isConcretePath(target)) continue
+    if (isServable(servablePaths, target)) continue
+
+    broken.push({ source, target })
+  }
+
+  return broken
+}
+
+/**
+ * Rules whose source the build serves as a real page, so the rule can never fire.
+ *
+ * A static asset wins over a redirect rule, which makes the rule invisible rather than broken: it usually
+ * means a page was rebuilt under a URL that had been retired, and the two intentions now contradict each
+ * other.
+ */
+export function findShadowedSources(redirects, servablePaths) {
+  const shadowed = []
+  for (const [source, target] of redirects) {
+    if (!isConcretePath(source)) continue
+    if (!isServable(servablePaths, source)) continue
+
+    shadowed.push({ source, target })
+  }
+
+  return shadowed
+}
+
+/**
+ * Rules whose target is itself the source of another rule.
+ *
+ * Cloudflare applies one rule per request rather than resolving a chain itself, so a chain costs the
+ * visitor a second round trip and hands a search engine a hop's worth of dilution on a link that used to
+ * arrive in one.
+ */
+export function findRedirectChains(redirects) {
+  const chains = []
+  for (const [source, target] of redirects) {
+    if (!isConcretePath(target)) continue
+    if (!redirects.has(target)) continue
+
+    chains.push({ source, target, eventualTarget: redirects.get(target) })
+  }
+
+  return chains
+}
+
+/**
+ * Page rules whose other trailing-slash spelling does not lead to the same page.
+ *
+ * Cloudflare matches a rule's source exactly, and only redirects between the two spellings when a page is
+ * built at one of them, which a retired URL never is. A previous site usually answered both, so a backlink
+ * or bookmark in the spelling without a rule lands on a 404. A file's path is left alone: nothing requests
+ * `/sitemap.xml/`.
+ */
+export function findMissingSpellings(redirects) {
+  const missing = []
+  for (const [source, target] of redirects) {
+    if (!isConcretePath(source)) continue
+
+    const lastSegment = source.replace(/\/$/, '').split('/').pop() ?? ''
+    if (source === '/' || lastSegment.includes('.')) continue
+
+    const otherSpelling = source.endsWith('/') ? source.slice(0, -1) : `${source}/`
+    if (redirects.get(otherSpelling) === target) continue
+
+    missing.push({ source, missing: otherSpelling, target })
+  }
+
+  return missing
+}

package/src/scoped-css.mjs

@@ -0,0 +1,69 @@
+/**
+ * Finds scoped CSS rules that can never match the element they target.
+ *
+ * Astro scopes a component's styles by appending `[data-astro-cid-…]` to each compound selector, and that
+ * attribute only lands on elements the component renders itself. So a component that styles a child
+ * component's root element by class (passing `<Child class='x'>` and styling `.x` from the parent) compiles
+ * to a selector requiring a scope the element does not carry, and the rule silently does nothing. There is
+ * no build error and no console warning, and the un-styled default usually looks deliberate, so one of
+ * these can ship and sit unnoticed for months.
+ *
+ * A rule is reported when its class appears in the built HTML but never alongside the scope the rule
+ * demands. A class that never appears at all is left alone: it is either applied at runtime (`.is-active`,
+ * `.is-open`) or belongs to a component nothing renders, and neither is this check's business.
+ */
+
+const SCOPED_SELECTOR_PATTERN = /\.([A-Za-z0-9_-]+)\[data-astro-cid-([a-z0-9]+)\]/g
+const ELEMENT_PATTERN = /<[a-z][a-z0-9-]*\s[^>]*>/gi
+const CLASS_ATTRIBUTE_PATTERN = /\sclass="([^"]*)"/i
+const SCOPE_ATTRIBUTE_PATTERN = /data-astro-cid-([a-z0-9]+)/g
+const STYLE_BLOCK_PATTERN = /<style[^>]*>([\s\S]*?)<\/style>/gi
+
+/** Every scope each class is rendered with, so a rule's demand can be checked against reality. */
+function indexRenderedClasses(markup, scopesByClass) {
+  for (const element of markup.match(ELEMENT_PATTERN) ?? []) {
+    const classMatch = element.match(CLASS_ATTRIBUTE_PATTERN)
+    if (!classMatch) continue
+
+    const scopes = Array.from(element.matchAll(SCOPE_ATTRIBUTE_PATTERN), (match) => match[1])
+    for (const className of classMatch[1].split(/\s+/).filter(Boolean)) {
+      const known = scopesByClass.get(className) ?? new Set()
+      for (const scope of scopes) known.add(scope)
+
+      scopesByClass.set(className, known)
+    }
+  }
+}
+
+/** The contents of every inline `<style>` block in a page. */
+export function extractStyleBlocks(markup) {
+  return Array.from(markup.matchAll(STYLE_BLOCK_PATTERN), (match) => match[1])
+}
+
+/**
+ * Scoped rules whose class renders somewhere in the built pages but never with the scope the rule
+ * demands, keyed by selector, with the scopes the class does render with and every source the rule was
+ * declared in.
+ */
+export function findUnmatchedScopedRules(pages, styleSheets) {
+  const scopesByClass = new Map()
+  for (const { markup } of pages) indexRenderedClasses(markup, scopesByClass)
+
+  const unmatched = new Map()
+  for (const { source, css } of styleSheets) {
+    for (const [selector, className, scope] of css.matchAll(SCOPED_SELECTOR_PATTERN)) {
+      const rendered = scopesByClass.get(className)
+      if (!rendered || rendered.has(scope)) continue
+
+      const existing = unmatched.get(selector)
+      if (existing) {
+        existing.sources.add(source)
+        continue
+      }
+
+      unmatched.set(selector, { className, scope, rendered, sources: new Set([source]) })
+    }
+  }
+
+  return unmatched
+}