Skip to content

About

Poststruct: Audit what shipped. A zero-dependency CLI that walks a directory of baked HTML (any generator's output) and verifies it against a head/site contract. FAIL findings exit non-zero so CI gates regressions.

Resources

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

poststruct 1.2.0

Audit what shipped. A zero-dependency CLI that walks a directory of baked HTML (any generator's output) and verifies it against a head/site contract. FAIL findings exit non-zero so CI gates regressions.

Where the family sits: prestruct puts SEO in before the build (source-time), freestruct injects after an SSG, and poststruct checks the baked artifact that both of them (and everyone else) actually shipped.

Core law: files on disk only. No SPA runtime, no scraping, no source linting. The fence is timeless by construction.

Boundary (one truth per concern)

Poststruct owns the audit of a baked artifact: walking a directory of shipped HTML, the head/site contract it verifies, the finding ids and levels it emits, and the pack loader that runs shape packs over a tree. Its inputs are a directory and a config; its outputs are findings and an exit code.

Poststruct defers to packstruct for the pack contract: manifest validation, pack naming, the pack.json schema, and semver policy all live in SPEC v1 and are consumed here verbatim rather than restated. The loader conforms to that spec (npm run conform:packs proves it) and does not re-derive it.

Shared vocabulary is consumed, not copied: pack ids are namespaced by pack slug, verdicts are packstruct's, and the spec is referenced by version (the exact 1.0.0 devDependency pin) rather than duplicated in prose. Copies drift; a pin does not.

House rules adopted from the family: no-fiction docs (every claim verified against the actual tool before it lands), fail loudly at the cause (unsupported shapes are refused by name, never silently accepted), and zero runtime dependencies (plain Node ESM).

What this version audits

npx poststruct audit [dir] (default dist):

npx poststruct audit dist/          # human output, one line per finding
npx poststruct audit dist/ --json   # {schema: 1, counts, findings}
  • head module (per page): title present + length band, description present + band, canonical present + absolute, OG(7) + Twitter(4) sets, og:image raster-format (an SVG og:image FAILs: most social scrapers cannot render it), og:image dims, JSON-LD parses + LocalBusiness recommended fields, h1 sanity. A 404 keeps only its noindex contract.
  • site module: sitemap.xml exists + has entries + lastmod, and robots.txt points at the sitemap with Sitemap:.
  • links module: internal <a href> graph vs the files present (a directory with no index.html is broken, not a pass), _redirects rule targets, and #fragment targets (WARN). --check-external adds the one network lane, opt-in; it refuses a private/loopback/link-local host before any socket (SSRF guard, links/external-blocked).
  • i18n module: <html lang> present and non-empty, agreement between it and content-language/og:locale (by primary subtag, so en-US vs en-GB is not a conflict), same-origin hreflang targets resolve, and reciprocal pairs (one-way inside the graph WARNs).
  • a11y-lite module: informative <img> without alt FAILs (decorative alt="" and role="presentation" are respected), form controls must be labeled, viewport must be present, and a skip link is a WARN.
  • language module: the text-shaped input profile. Grades prose wherever it lives - a baked page's rendered text, and the source documents the config names (language.textDirs: markdown, YAML values, JSON string values, plain text). Dash classes FAIL by default (em/en/figure dash, horizontal bar; tunable per class), an AI-cliche starter lexicon WARNs (delve, tapestry, unlock the potential, the "not just X, it is Y" construction), config or voice-pack banned terms are silent until named, lorem ipsum FAILs, whitespace disasters WARN, and malformed frontmatter FAILs. Every finding carries count + snippet.
  • feeds module: every page's RSS/Atom <link rel="alternate"> must resolve to a built file, each feed on disk must be well-formed with an <rss>/<feed> root, item/entry links must resolve, and an empty feed or a missing rel="self" WARNs. sitemap.xml is never mistaken for a feed.

Exit codes: 0 clean or warns-only, 1 any FAIL, 2 usage/environment error (no directory to walk).

Fixtures (the negative test is permanent)

npm test

The corpus is test/fixtures/good (must audit clean) and test/fixtures/bad (must hit EXACTLY the expected FAIL ids, warns included). Deleting or degrading a check breaks the test - that is the point.

Packs (realized)

The /packs mount follows the shared packstruct SPEC v1, check profile: packs/public/<name>/pack.json + entry exporting { checks: [...] }, ids namespaced by pack slug, and the config packs: entry as the arm. The loader is realized here: packs/public/eyes-reference/ ships the reference-shape pack and packs/public/eyestruct-shapes/ ships the canon-audit pack over an eyestruct-shaped lab tree (seven pure file checks, the EYESTRUCT_TREE target knob, one BOUNDED docket when no tree is present, never a fake pass), both against the committed packs/eye-ledger.json verdict baseline (22 rows). The packs ride the published tarball (files carries packs/), so a consumer arms node_modules/poststruct/packs/public/<name> from the exact pin - test/distribution-run.mjs pins that contract. The pack lane runs as the discoverable wrapper verb poststruct lint-packs [--deep] over the repo's own packstruct install (exact 1.0.0 devDependency pin), and the CI battery (npm run check) carries the deep lint plus npm run conform:packs, which proves the loader itself conforms. Future shape packs keep landing per the PRD.

Release ladder

0.9.x is the manual npm publish ladder; publish.yml refuses 0.x at the gate. 1.0.0 flips OIDC trusted publishing (id-token: write). See DEPLOY.md.

Landing & docs

  • Landing: poststruct.creadev.org - Cloudflare Pages rooted at web/ (Vite + React, prerendered by the prestruct build). Pages settings: root directory web, build command npm run build, build output directory dist; the CF config lives inside web/ (web/public/_headers, web/public/_redirects, web/functions/api/health.js for the /api/health canary), matching eyestruct / packstruct / govstruct. The baked tree is poststruct's own first audit target: npx poststruct audit web/dist/ gates clean on it (0 FAIL).
  • Identity: web/public/icon.svg is the authored seal (the audit lens), rendered to the favicon set + OG cards by web/scripts/make-icons.mjs and web/scripts/build-og.mjs - generated assets, never hand-drawn, the family's generated asset lane.
  • Docs: docs.creadev.org/poststruct - Jekyll + Pagefind + Freestruct via GitHub Actions (.github/workflows/docs.yml), with the getting started and CLI reference pages in the nav.

Related

  • prestruct - source-time audit, my upstream sibling
  • freestruct - post-SSG injection, my other sibling
  • crashtest - transport-level adversarial testing
  • packstruct - the shared packs spec (pinned 1.0.0 as an exact devDependency here; npm run conform:packs proves the pack loader itself conforms - 8/8 audit cases honored)
  • The workshop → Creadev.org (poststruct is made by Rook @ Creadev.org — the same home as the landing and docs surfaces above)

About

Poststruct: Audit what shipped. A zero-dependency CLI that walks a directory of baked HTML (any generator's output) and verifies it against a head/site contract. FAIL findings exit non-zero so CI gates regressions.

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages