@piercebarney/whs-eleventy 2026.9.1

package/README.md

@@ -0,0 +1,61 @@
+# @piercebarney/whs-eleventy
+
+The [web house style](https://github.com/piercebarney/web-house-style)'s
+**Eleventy + Netlify** tooling — one shared copy of the checks every project on
+the stack runs, so a fix lands once and `npm update` carries it everywhere.
+
+```
+whs compliance [--strict]              codebase-vs-standard conformance sweep
+whs doctor [--live|--deploy-preflight] infrastructure drift check
+whs links                              built-output link / CSP / JSON-LD integrity
+whs a11y                               axe-core WCAG 2.1 A/AA scan of _site/
+whs content-check                      lint · validate · build · links (no browser)
+whs --version                          tooling + bundled-standard version
+```
+
+Each subcommand resolves the project against the current working directory and
+expects the eleventy-netlify layout (`src/_data/*.js`, `netlify.toml`, `_site/`,
+`test/`). It is not configurable — projects on this stack are copies of
+`templates/eleventy-netlify/` and share that shape.
+
+## Install
+
+```
+npm i -D @piercebarney/whs-eleventy
+```
+
+Then in `package.json`:
+
+```json
+{
+  "scripts": {
+    "links": "whs links",
+    "a11y": "whs a11y",
+    "doctor": "whs doctor",
+    "compliance": "whs compliance",
+    "content-check": "whs content-check"
+  }
+}
+```
+
+The `/audit/` data files import the API directly:
+
+```js
+const { runCompliance, summarize } = require("@piercebarney/whs-eleventy/lib/compliance.js");
+const { runRepoChecks, readCache } = require("@piercebarney/whs-eleventy/lib/doctor.js");
+```
+
+## The bundled standard
+
+`whs compliance`'s drift check reads `core.md` + `CHANGELOG.md` to compare the
+project's `standard-version` pin against the current standard. The package ships
+a snapshot of both under `standard/`, cut when the version is published. Override
+with `WHS_STANDARD=/path/to/web-house-style` (the authoring repo points this at
+itself). When neither resolves, the drift row is a visible `MANUAL`, never a
+silent pass.
+
+## Not in this package
+
+`scripts/og.js`, `scripts/icons.js`, `scripts/og-card.js` stay in the project —
+they are asset _generators_ wired into the eleventy build, with a per-project
+page list and card design.

package/cli.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// whs — the web house style's Eleventy + Netlify tooling.
+//
+//   whs compliance [--strict]              codebase-vs-standard conformance sweep
+//   whs doctor [--live|--deploy-preflight] infrastructure drift check
+//   whs links                              built-output link / CSP / JSON-LD integrity
+//   whs a11y                               axe-core WCAG 2.1 A/AA scan of _site/
+//   whs content-check                      the content-relevant slice of the gate
+//   whs --version                          print the tooling + bundled-standard version
+//
+// Each subcommand is a plain Node script under lib/, spawned with the project's
+// cwd so `require.main === module` and exit codes behave exactly as a direct
+// `node lib/<x>.js` run would.
+
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const COMMANDS = {
+  compliance: "compliance.js",
+  doctor: "doctor.js",
+  links: "check-links.js",
+  a11y: "a11y.js",
+  "content-check": "content-check.js",
+};
+
+const [cmd, ...rest] = process.argv.slice(2);
+
+if (cmd === "--version" || cmd === "-v") {
+  const pkg = require("./package.json");
+  const fs = require("node:fs");
+  const { resolveStandard } = require("./lib/_project.js");
+  const std = resolveStandard();
+  let standardVersion = "not resolved";
+  if (std) {
+    const core = fs.readFileSync(path.join(std, "core.md"), "utf8");
+    standardVersion = (core.match(/\*\*Version:\*\*\s*([0-9-]+)/) || [])[1] || "unknown";
+  }
+  console.log(`@piercebarney/whs-eleventy ${pkg.version} · standard ${standardVersion}`);
+  process.exit(0);
+}
+
+if (!cmd || cmd === "--help" || cmd === "-h") {
+  console.log(`usage: whs <${Object.keys(COMMANDS).join(" | ")}>`);
+  process.exit(0);
+}
+
+if (!COMMANDS[cmd]) {
+  console.error(`whs: unknown command '${cmd}' — try one of: ${Object.keys(COMMANDS).join(", ")}`);
+  process.exit(1);
+}
+
+const r = spawnSync(process.execPath, [path.join(__dirname, "lib", COMMANDS[cmd]), ...rest], {
+  stdio: "inherit",
+});
+process.exit(r.status ?? 1);

package/lib/_project.js

@@ -0,0 +1,42 @@
+// Resolves the consuming project against the current working directory. Every
+// `whs` subcommand is run from a project root (npm runs package scripts there),
+// so the project's files live under process.cwd(), not next to this package.
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const ROOT = process.cwd();
+
+// require() a file from the project tree (its _data modules, its content schema).
+function projectRequire(rel) {
+  return require(path.join(ROOT, rel));
+}
+
+// Try to require() a project module; return fallback if it isn't there.
+function tryProjectRequire(rel, fallback = null) {
+  try {
+    return projectRequire(rel);
+  } catch {
+    return fallback;
+  }
+}
+
+// Locate the standard's text (core.md, CHANGELOG.md) for the drift check:
+//   1. WHS_STANDARD env var (the authoring repo points this at itself)
+//   2. the copy bundled into this package at publish time (standard/)
+//   3. the legacy ~/.claude/standards/web-house-style symlink
+// Returns an absolute dir path, or null if none of them has a core.md.
+function resolveStandard() {
+  const candidates = [
+    process.env.WHS_STANDARD,
+    path.join(__dirname, "..", "standard"),
+    path.join(os.homedir(), ".claude", "standards", "web-house-style"),
+  ].filter(Boolean);
+  for (const dir of candidates) {
+    if (fs.existsSync(path.join(dir, "core.md"))) return dir;
+  }
+  return null;
+}
+
+module.exports = { ROOT, projectRequire, tryProjectRequire, resolveStandard };

package/lib/a11y.js

@@ -0,0 +1,178 @@
+// Automated accessibility scan — the `a11y` step of the gate (whs a11y). Serves the built
+// _site/ with sirv, drives headless Chrome over every sitemap URL (plus
+// /audit/), runs axe-core (WCAG 2.1 A + AA) in each page, and exits non-zero on
+// any violation. axe-core is the engine pa11y/Lighthouse wrap; driving it
+// directly keeps CI free of a bundled-chromium download and its CVE churn.
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const http = require("node:http");
+const { spawn } = require("node:child_process");
+const sirv = require("sirv");
+const axeSource = require("axe-core").source;
+
+const SITE = "_site";
+const PORT = 8411;
+const DBG = 9333;
+
+const CHROME =
+  process.env.CHROME_PATH ||
+  [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/usr/bin/google-chrome",
+    "/usr/bin/chromium-browser",
+    "/usr/bin/chromium",
+  ].find((p) => {
+    try {
+      fs.accessSync(p);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+
+const getJSON = (url) =>
+  new Promise((res, rej) =>
+    http
+      .get(url, (r) => {
+        let d = "";
+        r.on("data", (c) => (d += c));
+        r.on("end", () => res(JSON.parse(d)));
+      })
+      .on("error", rej),
+  );
+
+function sitemapPaths() {
+  const xml = fs.readFileSync(path.join(SITE, "sitemap.xml"), "utf8");
+  const paths = [...xml.matchAll(/<loc>([^<]+)<\/loc>/g)].map((m) => new URL(m[1]).pathname);
+  paths.push("/audit/");
+  return [...new Set(paths)];
+}
+
+function connect(wsUrl) {
+  const ws = new WebSocket(wsUrl);
+  let id = 0;
+  const pending = {};
+  ws.addEventListener("message", (e) => {
+    const m = JSON.parse(e.data);
+    if (m.id && pending[m.id]) {
+      pending[m.id](m.result);
+      delete pending[m.id];
+    }
+  });
+  const ready = new Promise((r) => ws.addEventListener("open", r, { once: true }));
+  return {
+    ready,
+    ws,
+    send: (method, params) =>
+      new Promise((res) => {
+        const i = ++id;
+        pending[i] = res;
+        ws.send(JSON.stringify({ id: i, method, params }));
+      }),
+  };
+}
+
+async function main() {
+  if (!CHROME) {
+    console.error("a11y: no Chrome/Chromium found (set CHROME_PATH)");
+    process.exit(1);
+  }
+  if (!fs.existsSync(path.join(SITE, "sitemap.xml"))) {
+    console.error("a11y: _site/sitemap.xml missing — build first");
+    process.exit(1);
+  }
+
+  const handler = sirv(SITE, { dev: true });
+  const server = http.createServer((req, res) =>
+    handler(req, res, () => {
+      res.statusCode = 404;
+      res.end("not found");
+    }),
+  );
+  await new Promise((r) => server.listen(PORT, r));
+
+  const userDir = fs.mkdtempSync(path.join(os.tmpdir(), "a11y-"));
+  const chrome = spawn(
+    CHROME,
+    [
+      "--headless",
+      "--disable-gpu",
+      "--no-sandbox",
+      "--no-first-run",
+      `--remote-debugging-port=${DBG}`,
+      `--user-data-dir=${userDir}`,
+      "about:blank",
+    ],
+    { stdio: "ignore" },
+  );
+
+  const cleanup = () => {
+    try {
+      chrome.kill("SIGKILL");
+    } catch {}
+    server.close();
+    try {
+      fs.rmSync(userDir, { recursive: true, force: true });
+    } catch {}
+  };
+
+  try {
+    let target;
+    for (let i = 0; i < 60 && !target; i++) {
+      await new Promise((r) => setTimeout(r, 200));
+      try {
+        const list = await getJSON(`http://localhost:${DBG}/json`);
+        target = list.find((t) => t.type === "page");
+      } catch {}
+    }
+    if (!target) throw new Error("Chrome devtools did not come up");
+
+    const cdp = connect(target.webSocketDebuggerUrl);
+    await cdp.ready;
+    await cdp.send("Page.enable");
+    await cdp.send("Runtime.enable");
+
+    const paths = sitemapPaths();
+    const report = [];
+
+    for (const p of paths) {
+      const url = `http://localhost:${PORT}${p}`;
+      await cdp.send("Page.navigate", { url });
+      await new Promise((r) => setTimeout(r, 800));
+      await cdp.send("Runtime.evaluate", { expression: axeSource });
+      const r = await cdp.send("Runtime.evaluate", {
+        expression:
+          "axe.run(document,{runOnly:['wcag2a','wcag2aa','wcag21a','wcag21aa']}).then(function(x){return JSON.stringify(x.violations)})",
+        awaitPromise: true,
+        returnByValue: true,
+      });
+      const violations = JSON.parse((r.result && r.result.value) || "[]");
+      if (violations.length) report.push({ path: p, violations });
+    }
+
+    cdp.ws.close();
+    cleanup();
+
+    if (report.length) {
+      const total = report.reduce((n, r) => n + r.violations.length, 0);
+      console.error(`\na11y: ${total} violation type(s) across ${report.length} page(s):\n`);
+      for (const { path: p, violations } of report) {
+        console.error(`  ${p}`);
+        for (const v of violations) {
+          console.error(`    [${v.impact}] ${v.id} — ${v.help}`);
+          for (const node of v.nodes.slice(0, 3)) console.error(`        ${node.target.join(" ")}`);
+        }
+      }
+      process.exit(1);
+    }
+    console.log(`  a11y: ${paths.length} pages, no WCAG 2.1 A/AA violations`);
+  } catch (e) {
+    cleanup();
+    console.error("a11y:", e.stack || e.message);
+    process.exit(1);
+  }
+}
+
+main();

package/lib/check-links.js

@@ -0,0 +1,288 @@
+// Build-time link & reference integrity. Walks the built _site/ and exits
+// non-zero on:
+//   - an internal href/src that doesn't resolve to a generated file
+//   - an in-page #anchor with no matching id
+//   - a /glossary/#slug with no such glossary term
+//   - a referenced asset (og:image, icon, manifest, stylesheet, script, img)
+//     missing from the output
+//   - an external <a> without rel="noopener"/"noreferrer"
+//   - an external origin not declared in src/_data/thirdparties.js
+//   - a JSON-LD block that doesn't parse or lacks its @type's required fields
+//
+// Run by `npm run links` / `whs links` and as the `links` step of `npm run check`.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { parse } = require("node-html-parser");
+const { projectRequire, tryProjectRequire } = require("./_project.js");
+
+const SITE = "_site";
+const site = projectRequire("src/_data/site.js");
+const thirdparties = projectRequire("src/_data/thirdparties.js");
+
+// The /glossary/#slug check runs only when add-ons/glossary/ is applied
+// (it ships src/_data/glossary.js). No file → no glossary → the check is inert.
+const glossary = tryProjectRequire("src/_data/glossary.js");
+const glossarySlugs = new Set(glossary ? glossary.map((t) => t.slug) : []);
+const declaredOrigins = thirdparties
+  .flatMap((t) => [t.origin, ...(t.cspOrigins || [])])
+  .filter(Boolean);
+const allowedOrigins = new Set([site.url, ...declaredOrigins]);
+
+// Privacy/ad opt-out destinations that policy prose links to, plus the
+// search-engine webmaster consoles the /audit/ page links to. All are
+// informational <a> targets — they never load a resource or receive visitor
+// data — so they don't belong in thirdparties.js (which drives the "who sees
+// your data" list). Allowed only as plain links.
+const POLICY_LINK_ORIGINS = new Set([
+  "https://adssettings.google.com",
+  "https://policies.google.com",
+  "https://www.aboutads.info",
+  "https://youradchoices.com",
+  "https://optout.networkadvertising.org",
+  "https://www.google.com",
+  "https://search.google.com",
+  "https://www.bing.com",
+]);
+
+const REQUIRED_LD = {
+  WebSite: ["name", "url"],
+  WebApplication: ["name", "url"],
+  WebPage: ["name"],
+  BreadcrumbList: ["itemListElement"],
+  DefinedTermSet: ["name"],
+  Organization: ["name"],
+  Article: ["headline"],
+};
+
+const errors = [];
+const err = (file, msg) => errors.push(`${file}: ${msg}`);
+
+// ---- CSP <-> origin manifest agreement -------------------------------------
+(function checkCsp() {
+  let toml;
+  try {
+    toml = fs.readFileSync("netlify.toml", "utf8");
+  } catch (e) {
+    return err("netlify.toml", "missing — no security headers defined");
+  }
+  const m = toml.match(/Content-Security-Policy\s*=\s*"([^"]+)"/);
+  if (!m) return err("netlify.toml", "no Content-Security-Policy header");
+  const csp = m[1];
+  const cspOrigins = new Set(
+    (csp.match(/https?:\/\/[^\s;'"]+/g) || []).map((u) => {
+      try {
+        return new URL(u).origin;
+      } catch {
+        return u; // wildcard host (https://*.example.com) — keep the literal
+      }
+    }),
+  );
+  // Every origin the CSP grants must be a declared party — matched against each
+  // party's `origin` or its `cspOrigins` list. (The reverse isn't required: a
+  // host / form processor is in thirdparties.js but is not a browser-resource
+  // origin, so it needn't appear in the CSP.)
+  const declared = new Set(thirdparties.flatMap((t) => [t.origin, ...(t.cspOrigins || [])]));
+  for (const o of cspOrigins) {
+    if (!declared.has(o)) {
+      err("netlify.toml", `CSP allows an origin not in thirdparties.js: ${o}`);
+    }
+  }
+})();
+
+function walk(dir) {
+  const out = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...walk(p));
+    else out.push(p);
+  }
+  return out;
+}
+
+const allFiles = walk(SITE);
+const htmlFiles = allFiles.filter((f) => f.endsWith(".html"));
+
+// id sets per rendered page path ("/foo/" -> Set of ids), for anchor checks.
+const idsByUrl = {};
+for (const f of htmlFiles) {
+  const url =
+    "/" +
+    path
+      .relative(SITE, f)
+      .replace(/index\.html$/, "")
+      .replace(/\\/g, "/");
+  const root = parse(fs.readFileSync(f, "utf8"));
+  idsByUrl[url] = new Set(root.querySelectorAll("[id]").map((n) => n.getAttribute("id")));
+}
+
+function outputHas(urlPath) {
+  const clean = urlPath.split(/[?#]/)[0];
+  if (clean === "/" || clean === "") return fs.existsSync(path.join(SITE, "index.html"));
+  const asFile = path.join(SITE, clean);
+  if (fs.existsSync(asFile)) return true;
+  if (clean.endsWith("/")) return fs.existsSync(path.join(SITE, clean, "index.html"));
+  return fs.existsSync(asFile + "/index.html") || fs.existsSync(asFile + ".html");
+}
+
+function checkRef(file, pageUrl, raw, { external = true } = {}) {
+  if (!raw) return;
+  const v = raw.trim();
+  if (v === "" || v.startsWith("data:") || v.startsWith("mailto:") || v.startsWith("tel:")) return;
+
+  if (/^https?:\/\//i.test(v)) {
+    if (!external) return;
+    let origin;
+    try {
+      origin = new URL(v).origin;
+    } catch {
+      return err(file, `unparseable URL: ${v}`);
+    }
+    if (origin === site.url) {
+      if (!outputHas(new URL(v).pathname)) err(file, `absolute link to a missing page: ${v}`);
+    } else if (!allowedOrigins.has(origin) && !POLICY_LINK_ORIGINS.has(origin)) {
+      err(file, `external origin not in thirdparties.js: ${origin}`);
+    }
+    return;
+  }
+
+  if (v.startsWith("#")) {
+    if (v.length > 1 && !(idsByUrl[pageUrl] || new Set()).has(v.slice(1))) {
+      err(file, `#anchor with no matching id: ${v}`);
+    }
+    return;
+  }
+
+  if (v.startsWith("/")) {
+    if (!outputHas(v)) err(file, `internal reference does not resolve: ${v}`);
+    const hash = v.includes("#") ? v.split("#")[1] : "";
+    if (hash) {
+      const targetUrl = v.split("#")[0];
+      if (targetUrl === "/glossary/" && !glossarySlugs.has(hash)) {
+        err(file, `/glossary/#${hash} is not a glossary term`);
+      } else if (idsByUrl[targetUrl] && !idsByUrl[targetUrl].has(hash)) {
+        err(file, `${targetUrl}#${hash} — no such id on that page`);
+      }
+    }
+    return;
+  }
+  // relative path — resolve against the page dir
+  const resolved = path.posix.join(pageUrl, v);
+  if (!outputHas(resolved)) err(file, `relative reference does not resolve: ${v}`);
+}
+
+for (const f of htmlFiles) {
+  const rel = "/" + path.relative(SITE, f).replace(/\\/g, "/");
+  const pageUrl = rel.replace(/index\.html$/, "");
+  const root = parse(fs.readFileSync(f, "utf8"));
+
+  // CSP-safety: the strict CSP (script-src 'self'; style-src 'self') rejects
+  // inline scripts, inline styles, and on* handlers. Fail the build if any
+  // reappear in the output.
+  const EXECUTABLE = ["", "text/javascript", "application/javascript", "module"];
+  root.querySelectorAll("script").forEach((s) => {
+    const type = (s.getAttribute("type") || "").toLowerCase();
+    if (!s.getAttribute("src") && s.text.trim() && EXECUTABLE.includes(type)) {
+      err(f, `inline <script> (blocked by CSP script-src 'self')`);
+    }
+  });
+  root
+    .querySelectorAll("style")
+    .forEach(() => err(f, `inline <style> (blocked by CSP style-src 'self')`));
+  root.querySelectorAll("*").forEach((el) => {
+    for (const name of Object.keys(el.attributes)) {
+      if (/^on/i.test(name)) err(f, `inline handler ${name}= (blocked by CSP script-src 'self')`);
+      if (name.toLowerCase() === "style") err(f, `inline style= (blocked by CSP style-src 'self')`);
+    }
+  });
+
+  root.querySelectorAll("a[href]").forEach((a) => {
+    const href = a.getAttribute("href");
+    checkRef(f, pageUrl, href);
+    if (/^https?:\/\//i.test(href || "")) {
+      let origin;
+      try {
+        origin = new URL(href).origin;
+      } catch {
+        origin = "";
+      }
+      if (origin && origin !== site.url) {
+        const rel2 = (a.getAttribute("rel") || "").toLowerCase();
+        if (!/\bnoopener\b|\bnoreferrer\b/.test(rel2)) {
+          err(f, `external <a> without rel="noopener": ${href}`);
+        }
+      }
+    }
+  });
+
+  root.querySelectorAll("link[href]").forEach((l) => checkRef(f, pageUrl, l.getAttribute("href")));
+  root.querySelectorAll("script[src]").forEach((s) => checkRef(f, pageUrl, s.getAttribute("src")));
+  root.querySelectorAll("img[src]").forEach((i) => checkRef(f, pageUrl, i.getAttribute("src")));
+  root
+    .querySelectorAll('meta[property="og:image"], meta[name="twitter:image"]')
+    .forEach((m) => checkRef(f, pageUrl, m.getAttribute("content")));
+
+  root.querySelectorAll('script[type="application/ld+json"]').forEach((s, i) => {
+    let data;
+    try {
+      data = JSON.parse(s.text);
+    } catch (e) {
+      return err(f, `JSON-LD block #${i + 1} does not parse: ${e.message}`);
+    }
+    for (const node of [].concat(data)) {
+      const type = node["@type"];
+      const req = REQUIRED_LD[type];
+      if (!type) err(f, `JSON-LD block #${i + 1} has no @type`);
+      else if (req) {
+        for (const k of req) {
+          if (node[k] === undefined) err(f, `JSON-LD ${type} missing required "${k}"`);
+        }
+      }
+    }
+  });
+}
+
+// ---- ads: production-only, ads.txt present (core.md#ads) -------------------
+(function checkAds() {
+  const ads = tryProjectRequire("src/_data/ads.js", {});
+  if (!ads.pub) return;
+  // Infer prod-ness from the built output, not process.env — so `npm run links`
+  // is correct whichever build is on disk.
+  const home = fs.readFileSync(path.join(SITE, "index.html"), "utf8");
+  const isProdBuild = !/<meta[^>]+name=["']robots["'][^>]+noindex/i.test(home);
+  // Real ad/consent CODE — not a bare origin string (the audit page renders the
+  // origin manifest as data, which is fine).
+  const AD_CODE =
+    /adsbygoogle\.js|<ins[^>]+adsbygoogle|name=["']google-adsense-account["']|fundingchoicesmessages\.google\.com\/i\//;
+  if (!isProdBuild) {
+    for (const f of htmlFiles) {
+      if (AD_CODE.test(fs.readFileSync(f, "utf8"))) {
+        err(f, "ad / consent code in a non-production build (must be gated on build.isProduction)");
+      }
+    }
+  }
+  if (!fs.existsSync(path.join(SITE, "ads.txt"))) {
+    err("_site/ads.txt", "missing — src/ads.txt.njk should emit it on every build");
+  }
+})();
+
+if (errors.length) {
+  console.error(`\nLink check failed (${errors.length}):`);
+  errors.forEach((e) => console.error("  - " + e));
+  process.exit(1);
+}
+
+try {
+  fs.writeFileSync(
+    path.join(SITE, "links-report.json"),
+    JSON.stringify(
+      { generatedAt: new Date().toISOString(), pages: htmlFiles.length, checked: allFiles.length },
+      null,
+      2,
+    ),
+  );
+} catch (e) {
+  /* _site may be read-only in some contexts; the console line is the source of truth */
+}
+
+console.log(`  links: ${htmlFiles.length} pages OK`);