@contentrain/verify 0.1.0

package/README.md

@@ -0,0 +1,149 @@
+# @contentrain/verify
+
+Portable gates for a migrated site: identity, indexing, status, hreflang,
+structured data, navigation and assets — checked over documents you already
+have, with no network and no dependencies.
+
+MIT. Part of the [Contentrain](https://contentrain.io) migration pipeline, and
+usable on its own against any static build.
+
+```bash
+npx @contentrain/verify dist --site https://example.com
+```
+
+## Why it does not fetch
+
+A hardened crawler is a security surface of its own — SSRF, DNS rebinding,
+redirect limits, byte and time caps, robots handling — and it belongs where that
+hardening is maintained, not inside the MIT library every consumer embeds.
+
+So this package takes documents. That constraint turns out to be the feature:
+the same gate runs over a `dist/` directory, over pages a migration engine
+already captured, and inside CI, with no network calls to mock and no flake.
+Whoever holds a safe fetcher supplies the pages.
+
+## Usage
+
+```ts
+import { verify, formatReport } from '@contentrain/verify'
+
+const report = verify({
+  site: 'https://example.com',
+  documents: [{ url: '/about', html, status: 200, headers }],
+  assets: ['/img/hero.png'],
+  sitemap: sitemapXml,
+  redirects: [{ from: '/old', to: '/about', status: 301 }],
+  baseline: { documents: oldPages },   // optional: enables the parity checks
+})
+
+report.passed        // no error findings — this is the gate
+report.findings      // every finding, with a stable `check` id
+report.skipped       // what could not run, and why
+console.log(formatReport(report))
+```
+
+Or over a built directory:
+
+```ts
+import { loadSiteDirectory, verify } from '@contentrain/verify'
+
+const report = verify(await loadSiteDirectory('dist', 'https://example.com'))
+```
+
+## The checks
+
+Severity is decided by one rule: **error** means the built site is wrong — a
+visitor or a crawler gets something it should not. **warning** means it is worse
+than the site it replaced, or worse than it should be. A migration that improves
+a page must not fail its own gate.
+
+| Group | Check | Severity | What it catches |
+|---|---|---|---|
+| identity | `identity.title-missing` | error | No non-empty `<title>` |
+| | `identity.title-duplicate` | error | Two titles in the head — a crawler picks one, undefined which. A `<title>` inside an inline `<svg>` is an accessibility label and is not counted |
+| | `identity.canonical-missing` | warning | No canonical link |
+| | `identity.canonical-duplicate` | error | Two canonicals: the page says two things about itself |
+| | `identity.canonical-mismatch` | error | **The clone failure.** A page carrying the template's canonical points the whole site at one URL and removes it from the index. Invisible in a browser, worse than having no canonical |
+| | `identity.description-missing` | warning | No meta description |
+| | `identity.open-graph-incomplete` | warning | Missing `og:title` / `og:type` / `og:url` — shares render without a card |
+| | `identity.twitter-card-missing` | info | No `twitter:card` |
+| indexing | `indexing.noindex` | error | **The staging leak.** A `noindex` in the meta or `X-Robots-Tag` survives deploy and the site disappears from search over the following weeks |
+| | `indexing.sitemap-missing-entry` | warning | An indexable page is not in the sitemap (a `noindex` page is not asked to be) |
+| | `indexing.sitemap-stale-entry` | warning | The sitemap lists a page the build does not serve |
+| status | `status.mismatch` | error | The status changed against the baseline |
+| | `status.soft-404` | error | A "not found" page answering 200 — invisible to every status monitor, indexed as content |
+| | `status.redirect-chain` | warning | More hops than `maxRedirectHops` (default 1) |
+| | `status.redirect-loop` | error | A chain that returns to itself |
+| | `status.redirect-target-missing` | error | An internal redirect pointing at a page the build does not serve |
+| international | `international.hreflang-not-reciprocal` | error | A names B but B does not name A. Search engines ignore one-sided alternates entirely, so half the work is worth nothing |
+| | `international.hreflang-no-self` | warning | A page with alternates that does not list itself |
+| | `international.hreflang-unknown-target` | warning | An alternate pointing at a page that does not exist |
+| structured | `structured.jsonld-invalid` | error | A JSON-LD block that does not parse — consumers discard the whole block |
+| | `structured.type-lost` | warning | A `@type` the old page had is gone. Types inside `@graph` are counted, which is how themes actually ship them |
+| navigation | `navigation.broken-internal-link` | error | An internal link that goes nowhere. A path a redirect rule covers is fine; external, `mailto:`, `tel:` and fragment links are not checked |
+| | `navigation.pagination-broken` | warning | `rel="next"` / `rel="prev"` pointing at a page the build does not serve |
+| | `navigation.feed-lost` | warning | The old page advertised a feed and this one does not |
+| assets | `assets.broken-image` | error | An internal image that resolves to nothing the build serves. `data:` URIs and third-party hosts are skipped |
+| | `assets.missing-alt` | warning | An `<img>` with no `alt` attribute. `alt=""` is a decision (decorative) and is not reported |
+| | `assets.alt-lost` | warning | Alt text the old page had for the same image is gone |
+
+## Address identity
+
+Every "does this go somewhere that exists" question is a normalisation question,
+and getting it wrong in either direction is worse than not asking: too strict and
+a correct site fails, too loose and a broken one passes.
+
+- `/about`, `/about/` and `/about/index.html` are one address, because static
+  hosts serve them that way.
+- Query strings and fragments are not part of a document's identity.
+- Case is preserved, because static hosts are case-sensitive even when the
+  author assumed otherwise.
+
+Without `site`, relative links still resolve (against a reserved origin) and
+absolute links to real hosts are treated as external. Supplying `site` is better:
+it is what makes `canonical-mismatch` and cross-origin checks exact.
+
+## What a missing input does
+
+Nothing is silently skipped. A run without a baseline, a sitemap or redirect
+rules reports those absences in `report.skipped` — a green report over a run that
+compared nothing is the most dangerous output this package could produce.
+
+## CLI
+
+```
+contentrain-verify <dist-dir> [options]
+
+  --site <url>          Canonical origin
+  --baseline <dir>      The old site, as a directory of captured pages
+  --redirects <file>    JSON: [{ "from": "/a", "to": "/b", "status": 301 }]
+  --groups <list>       identity,indexing,status,international,structured,navigation,assets
+  --max-redirect-hops <n>
+  --json
+```
+
+Exits 1 when any finding is an error, 2 on a usage error. Unknown options and
+unknown group names are rejected rather than ignored.
+
+## Reading HTML
+
+Targeted regexes, not a parser — the same choice `@contentrain/emitter-astro`
+makes, for the same reason: these are machine-generated documents whose head the
+pipeline controls, the extracted set is small and fixed, and a parser would put a
+dependency into the one package a migration should be able to run anywhere.
+
+The limits are honoured rather than papered over. Attribute reads require
+whitespace before the name, so `data-src` never answers a read of `src` — which
+matters, because lazy-loading WordPress themes put the real URL in `data-src` on
+almost every image. Where a check would be wrong under these limits, it is not
+written.
+
+## Related
+
+- [`@contentrain/emitter-astro`](../emitter-astro) — produces the site this verifies
+- [`@contentrain/wp-import`](../wp-import) — produces the content
+- [`@contentrain/types`](../types) — the shared contracts
+
+## License
+
+MIT

package/dist/bin.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/bin.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { main } from "./cli.mjs";
+//#region src/bin.ts
+main(process.argv.slice(2)).then((code) => {
+	process.exitCode = code;
+}, (error) => {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exitCode = 2;
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=bin.mjs.map

package/dist/bin.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.mjs","names":[],"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\n// The executable. Kept separate from `cli.ts` so the shell can be imported and\n// tested without a module side effect that runs it.\n\nimport { main } from './cli.js'\n\nmain(process.argv.slice(2)).then(\n  (code) => { process.exitCode = code },\n  (error: unknown) => {\n    console.error(error instanceof Error ? error.message : String(error))\n    process.exitCode = 2\n  },\n)\n"],"mappings":";;;AAMA,KAAK,QAAQ,KAAK,MAAM,EAAE,CAAC,CAAC,MACzB,SAAS;AAAE,SAAQ,WAAW;IAC9B,UAAmB;AAClB,SAAQ,MAAM,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,CAAC;AACrE,SAAQ,WAAW;EAEtB"}

package/dist/cli.d.mts

@@ -0,0 +1,24 @@
+import { n as CheckGroup } from "./types-C_hmH1n3.mjs";
+
+//#region src/cli.d.ts
+declare const USAGE: string;
+interface Args {
+  dir?: string;
+  site?: string;
+  baseline?: string;
+  redirects?: string;
+  groups?: CheckGroup[];
+  maxRedirectHops?: number;
+  json: boolean;
+  help: boolean;
+}
+declare function parseArgs(argv: readonly string[]): Args;
+interface Console2 {
+  log: (line: string) => void;
+  error: (line: string) => void;
+}
+/** Returns the process exit code. `io` is injectable so tests read the output. */
+declare function main(argv: readonly string[], io?: Console2): Promise<number>;
+//#endregion
+export { Args, Console2, USAGE, main, parseArgs };
+//# sourceMappingURL=cli.d.mts.map

package/dist/cli.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.mts","names":[],"sources":["../src/cli.ts"],"mappings":";;;cAca,KAAA;AAAA,UAWI,IAAA;EACf,GAAA;EACA,IAAA;EACA,QAAA;EACA,SAAA;EACA,MAAA,GAAS,UAAA;EACT,eAAA;EACA,IAAA;EACA,IAAA;AAAA;AAAA,iBAGc,SAAA,CAAU,IAAA,sBAA0B,IAAA;AAAA,UAyBnC,QAAA;EACf,GAAA,GAAM,IAAA;EACN,KAAA,GAAQ,IAAA;AAAA;;iBAIY,IAAA,CAAK,IAAA,qBAAyB,EAAA,GAAI,QAAA,GAAqB,OAAA"}

package/dist/cli.mjs

@@ -0,0 +1,68 @@
+import { i as CHECK_GROUPS, n as formatReport, r as verify, t as loadSiteDirectory } from "./load-KUG-8Ug4.mjs";
+import { readFile } from "node:fs/promises";
+//#region src/cli.ts
+const USAGE = `contentrain-verify <dist-dir> [options]
+
+  --site <url>          Canonical origin, e.g. https://example.com
+  --baseline <dir>      The old site, as a directory of captured pages
+  --redirects <file>    JSON: [{ "from": "/a", "to": "/b", "status": 301 }]
+  --groups <list>       Comma-separated: ${CHECK_GROUPS.join(",")}
+  --max-redirect-hops <n>
+  --json                Print the report as JSON instead of text
+
+Exits 1 when any finding is an error, 2 on a usage error.`;
+function parseArgs(argv) {
+	const args = {
+		json: false,
+		help: false
+	};
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		const next = () => argv[++i];
+		if (arg === "--help" || arg === "-h") args.help = true;
+		else if (arg === "--json") args.json = true;
+		else if (arg === "--site") args.site = next();
+		else if (arg === "--baseline") args.baseline = next();
+		else if (arg === "--redirects") args.redirects = next();
+		else if (arg === "--max-redirect-hops") {
+			const value = Number(next());
+			if (!Number.isInteger(value) || value < 0) throw new Error("--max-redirect-hops expects a non-negative integer");
+			args.maxRedirectHops = value;
+		} else if (arg === "--groups") {
+			const list = (next() ?? "").split(",").map((g) => g.trim()).filter(Boolean);
+			const unknown = list.filter((g) => !CHECK_GROUPS.includes(g));
+			if (unknown.length) throw new Error(`unknown group(s): ${unknown.join(", ")}`);
+			args.groups = list;
+		} else if (arg.startsWith("-")) throw new Error(`unknown option: ${arg}`);
+		else args.dir ??= arg;
+	}
+	return args;
+}
+/** Returns the process exit code. `io` is injectable so tests read the output. */
+async function main(argv, io = console) {
+	let args;
+	try {
+		args = parseArgs(argv);
+	} catch (error) {
+		io.error(`${error.message}\n\n${USAGE}`);
+		return 2;
+	}
+	if (args.help || !args.dir) {
+		io.log(USAGE);
+		return args.help ? 0 : 2;
+	}
+	const input = {
+		...await loadSiteDirectory(args.dir, args.site),
+		groups: args.groups,
+		options: args.maxRedirectHops === void 0 ? void 0 : { maxRedirectHops: args.maxRedirectHops }
+	};
+	if (args.baseline) input.baseline = { documents: (await loadSiteDirectory(args.baseline, args.site)).documents };
+	if (args.redirects) input.redirects = JSON.parse(await readFile(args.redirects, "utf8"));
+	const report = verify(input);
+	io.log(args.json ? JSON.stringify(report, null, 2) : formatReport(report));
+	return report.passed ? 0 : 1;
+}
+//#endregion
+export { USAGE, main, parseArgs };
+
+//# sourceMappingURL=cli.mjs.map

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["// ─── contentrain-verify ───\n//\n// A thin shell over `verify()`: read a built directory, run the gates, print\n// the report, return an exit code. Everything decisional lives in the library —\n// this adds argument parsing and a number, nothing else. `bin.ts` is the\n// executable; keeping the shell importable is what makes it testable without\n// spawning a process.\n\nimport { readFile } from 'node:fs/promises'\nimport { verify, formatReport } from './verify.js'\nimport { loadSiteDirectory } from './load.js'\nimport { CHECK_GROUPS } from './types.js'\nimport type { CheckGroup, VerifyInput } from './types.js'\n\nexport const USAGE = `contentrain-verify <dist-dir> [options]\n\n  --site <url>          Canonical origin, e.g. https://example.com\n  --baseline <dir>      The old site, as a directory of captured pages\n  --redirects <file>    JSON: [{ \"from\": \"/a\", \"to\": \"/b\", \"status\": 301 }]\n  --groups <list>       Comma-separated: ${CHECK_GROUPS.join(',')}\n  --max-redirect-hops <n>\n  --json                Print the report as JSON instead of text\n\nExits 1 when any finding is an error, 2 on a usage error.`\n\nexport interface Args {\n  dir?: string\n  site?: string\n  baseline?: string\n  redirects?: string\n  groups?: CheckGroup[]\n  maxRedirectHops?: number\n  json: boolean\n  help: boolean\n}\n\nexport function parseArgs(argv: readonly string[]): Args {\n  const args: Args = { json: false, help: false }\n  for (let i = 0; i < argv.length; i += 1) {\n    const arg = argv[i]!\n    const next = (): string | undefined => argv[++i]\n    if (arg === '--help' || arg === '-h') args.help = true\n    else if (arg === '--json') args.json = true\n    else if (arg === '--site') args.site = next()\n    else if (arg === '--baseline') args.baseline = next()\n    else if (arg === '--redirects') args.redirects = next()\n    else if (arg === '--max-redirect-hops') {\n      const value = Number(next())\n      if (!Number.isInteger(value) || value < 0) throw new Error('--max-redirect-hops expects a non-negative integer')\n      args.maxRedirectHops = value\n    } else if (arg === '--groups') {\n      const list = (next() ?? '').split(',').map(g => g.trim()).filter(Boolean)\n      const unknown = list.filter(g => !(CHECK_GROUPS as readonly string[]).includes(g))\n      if (unknown.length) throw new Error(`unknown group(s): ${unknown.join(', ')}`)\n      args.groups = list as CheckGroup[]\n    } else if (arg.startsWith('-')) throw new Error(`unknown option: ${arg}`)\n    else args.dir ??= arg\n  }\n  return args\n}\n\nexport interface Console2 {\n  log: (line: string) => void\n  error: (line: string) => void\n}\n\n/** Returns the process exit code. `io` is injectable so tests read the output. */\nexport async function main(argv: readonly string[], io: Console2 = console): Promise<number> {\n  let args: Args\n  try {\n    args = parseArgs(argv)\n  } catch (error) {\n    io.error(`${(error as Error).message}\\n\\n${USAGE}`)\n    return 2\n  }\n\n  if (args.help || !args.dir) {\n    io.log(USAGE)\n    return args.help ? 0 : 2\n  }\n\n  const loaded = await loadSiteDirectory(args.dir, args.site)\n  const input: VerifyInput = {\n    ...loaded,\n    groups: args.groups,\n    options: args.maxRedirectHops === undefined ? undefined : { maxRedirectHops: args.maxRedirectHops },\n  }\n\n  if (args.baseline) {\n    const before = await loadSiteDirectory(args.baseline, args.site)\n    input.baseline = { documents: before.documents }\n  }\n  if (args.redirects) {\n    input.redirects = JSON.parse(await readFile(args.redirects, 'utf8')) as VerifyInput['redirects']\n  }\n\n  const report = verify(input)\n  io.log(args.json ? JSON.stringify(report, null, 2) : formatReport(report))\n  return report.passed ? 0 : 1\n}\n"],"mappings":";;;AAcA,MAAa,QAAQ;;;;;2CAKsB,aAAa,KAAK,IAAI,CAAC;;;;;AAiBlE,SAAgB,UAAU,MAA+B;CACvD,MAAM,OAAa;EAAE,MAAM;EAAO,MAAM;EAAO;AAC/C,MAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK,GAAG;EACvC,MAAM,MAAM,KAAK;EACjB,MAAM,aAAiC,KAAK,EAAE;AAC9C,MAAI,QAAQ,YAAY,QAAQ,KAAM,MAAK,OAAO;WACzC,QAAQ,SAAU,MAAK,OAAO;WAC9B,QAAQ,SAAU,MAAK,OAAO,MAAM;WACpC,QAAQ,aAAc,MAAK,WAAW,MAAM;WAC5C,QAAQ,cAAe,MAAK,YAAY,MAAM;WAC9C,QAAQ,uBAAuB;GACtC,MAAM,QAAQ,OAAO,MAAM,CAAC;AAC5B,OAAI,CAAC,OAAO,UAAU,MAAM,IAAI,QAAQ,EAAG,OAAM,IAAI,MAAM,qDAAqD;AAChH,QAAK,kBAAkB;aACd,QAAQ,YAAY;GAC7B,MAAM,QAAQ,MAAM,IAAI,IAAI,MAAM,IAAI,CAAC,KAAI,MAAK,EAAE,MAAM,CAAC,CAAC,OAAO,QAAQ;GACzE,MAAM,UAAU,KAAK,QAAO,MAAK,CAAE,aAAmC,SAAS,EAAE,CAAC;AAClF,OAAI,QAAQ,OAAQ,OAAM,IAAI,MAAM,qBAAqB,QAAQ,KAAK,KAAK,GAAG;AAC9E,QAAK,SAAS;aACL,IAAI,WAAW,IAAI,CAAE,OAAM,IAAI,MAAM,mBAAmB,MAAM;MACpE,MAAK,QAAQ;;AAEpB,QAAO;;;AAST,eAAsB,KAAK,MAAyB,KAAe,SAA0B;CAC3F,IAAI;AACJ,KAAI;AACF,SAAO,UAAU,KAAK;UACf,OAAO;AACd,KAAG,MAAM,GAAI,MAAgB,QAAQ,MAAM,QAAQ;AACnD,SAAO;;AAGT,KAAI,KAAK,QAAQ,CAAC,KAAK,KAAK;AAC1B,KAAG,IAAI,MAAM;AACb,SAAO,KAAK,OAAO,IAAI;;CAIzB,MAAM,QAAqB;EACzB,GAFa,MAAM,kBAAkB,KAAK,KAAK,KAAK,KAAK;EAGzD,QAAQ,KAAK;EACb,SAAS,KAAK,oBAAoB,KAAA,IAAY,KAAA,IAAY,EAAE,iBAAiB,KAAK,iBAAiB;EACpG;AAED,KAAI,KAAK,SAEP,OAAM,WAAW,EAAE,YADJ,MAAM,kBAAkB,KAAK,UAAU,KAAK,KAAK,EAC3B,WAAW;AAElD,KAAI,KAAK,UACP,OAAM,YAAY,KAAK,MAAM,MAAM,SAAS,KAAK,WAAW,OAAO,CAAC;CAGtE,MAAM,SAAS,OAAO,MAAM;AAC5B,IAAG,IAAI,KAAK,OAAO,KAAK,UAAU,QAAQ,MAAM,EAAE,GAAG,aAAa,OAAO,CAAC;AAC1E,QAAO,OAAO,SAAS,IAAI"}

package/dist/index.d.mts

@@ -0,0 +1,29 @@
+import { a as VerifyDocument, c as VerifyRedirect, i as Severity, l as VerifyReport, n as CheckGroup, o as VerifyInput, r as Finding, s as VerifyOptions, t as CHECK_GROUPS } from "./types-C_hmH1n3.mjs";
+
+//#region src/verify.d.ts
+/**
+ * Run the gates over a built site.
+ *
+ * Nothing is fetched. `input.documents` is the built site as served, and
+ * `input.baseline` — when the caller has one — is the site it replaced. Without
+ * a baseline every self-check still runs; only the parity checks (status
+ * change, lost structured data, lost alt text, lost feed) go quiet, because
+ * there is nothing to compare against.
+ */
+declare function verify(input: VerifyInput): VerifyReport;
+/** A report as lines, most severe first. Used by the CLI and by consumers. */
+declare function formatReport(report: VerifyReport): string;
+//#endregion
+//#region src/load.d.ts
+/**
+ * Load a static build as a verification input: every `.html` becomes a
+ * document served at its path, everything else becomes an asset.
+ *
+ * `dist/about/index.html` is served at `/about/`, which `identity()` then
+ * reduces to `/about` — the same address a link to `/about/` or
+ * `/about/index.html` resolves to.
+ */
+declare function loadSiteDirectory(dir: string, site?: string): Promise<Pick<VerifyInput, 'documents' | 'assets' | 'sitemap' | 'site'>>;
+//#endregion
+export { CHECK_GROUPS, type CheckGroup, type Finding, type Severity, type VerifyDocument, type VerifyInput, type VerifyOptions, type VerifyRedirect, type VerifyReport, formatReport, loadSiteDirectory, verify };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/verify.ts","../src/load.ts"],"mappings":";;;;;AAsDA;;;;;;;iBAAgB,MAAA,CAAO,KAAA,EAAO,WAAA,GAAc,YAAA;;iBAuC5B,YAAA,CAAa,MAAA,EAAQ,YAAA;;;;;AAvCrC;;;;;;iBCpBsB,iBAAA,CAAkB,GAAA,UAAa,IAAA,YAAgB,OAAA,CAAQ,IAAA,CAAK,WAAA"}

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { i as CHECK_GROUPS, n as formatReport, r as verify, t as loadSiteDirectory } from "./load-KUG-8Ug4.mjs";
+export { CHECK_GROUPS, formatReport, loadSiteDirectory, verify };