# Docs structural test suite — checks and fixes The structural test suite is the pre-merge gate for everything under [`docs/`](../../../docs/), run from this directory. It walks the whole tree and asserts three things: the locales mirror each other (**parity**), each page is mechanically sound (**structure**), and pages have an introduction and no empty final section (**content presence**). Editorial quality and factual accuracy require a separate review. A single failing assertion rarely says which rule broke — this file names every check, what it catches, and the fix. The writing method lives in the [`write-docs`](../../../.agents/skills/write-docs/SKILL.md) skill; the Tale repo facts in [`docs/AGENTS.md`](../../../docs/AGENTS.md); cross-locale terminology in [`write-translations`](../../../.agents/skills/write-translations/SKILL.md). ## When this applies Run it after renaming, moving, or deleting a page; after editing [`docs/nav.json`](../../../docs/nav.json); after adding a page in one locale; after editing any heading (heading text → slug); after translating or rewriting a page; and before opening any PR that touches `docs/` or `services/docs/` (CI runs the same suite via `bunx turbo run test`). ## Run it ```bash bun run --filter @tale/docs test ``` Runs from any directory in the monorepo. For one file or verbose output: ```bash cd services/docs && bunx vitest run tests/structure-opening.test.ts cd services/docs && bunx vitest run --reporter=verbose ``` The same package also exposes `lint` (oxlint), `typecheck` (tsc), and `build`; run those when you touch the docs _app_, not just content. (There is no `format` script — use the repo-wide `bun run format`.) ## The checks Each test scans every page, collects `Finding` records ([`lib/findings.ts`](lib/findings.ts)), and asserts the list is empty — the failure prints each file once with offending lines and a `[rule]` tag. **Parity** — the locales must stay in lockstep (`en/` is the source of truth): | Check (`*.test.ts`) | Catches → fix | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `walk` | Harness sanity: walker finds pages, base locales `en`/`de`/`fr` present → if it trips the harness itself is broken (check `lib/paths.ts`, the tree). | | `navigation` | A `docs/nav.json` slug with no `.md`/`.mdx` under a locale (renamed page, untranslated page, typo) → create the file or fix/remove the nav entry. | | `locale-tree` | An `en/` page with no DE/FR mirror, or a DE/FR orphan with no `en/` source → create the mirror or delete the orphan. | | `locale-outline` | DE/FR drifting from the EN page's heading-depth sequence or fenced-code-block count → restructure the locale page to match EN's outline. | | `locale-translation` | A DE/FR page whose opening paragraph is byte-identical to the EN source's (an untranslated English mirror) → author the page natively per `write-translations`. | | `locale-components` | DE/FR drifting from the EN page's ordered sequence of component opening tags (a dropped ``, a reordered ``) → match EN's components. | | `readme` | Root `README.md` / `README..md` heading outlines diverging, or EN not linking a mirror → mirror the change across all READMEs. | | `content-manifest` | `app/content/frontmatter.json` stale vs on-disk frontmatter → regenerate (`bun run --filter @tale/docs build:search-index`). | **Structure** — each page is mechanically well-formed: | Check (`*.test.ts`) | Catches → fix | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `frontmatter` | A page missing the `---` block or `title`/`description` → add the field (`title` sentence-case; `description` one sentence). | | `filenames` | A path segment that isn't dash-case lowercase (`API_Reference.md`) — locale segment exempt (`de-CH`) → rename and sweep inbound links. | | `structure-headings` | A body `# H1` (the frontmatter `title` is the H1) or depth past H4 → demote/split. Heading wording is reviewed for usefulness, not checked against a blacklist. | | `structure-steps` | Bare headings, paragraphs, or other content directly inside ``, or an untitled `` → wrap each action in `` and keep its explanation and images inside that wrapper. The check uses the actual Markdown renderer. | | `structure-code` | A bare ` ``` ` fence with no language → add a tag (`bash`, `typescript`, `json`, `text`, `mermaid`, …). | | `structure-prose` | A `!` in prose (outside `!=`/`!important`/image alt), or a status-chatter line opener (`Updated:`, `TODO:`, `Note that…`) → strike it. | | `links` | A relative/absolute-path page link resolving to no `.md`/`.mdx` (external, anchor-only, and `.ext` asset links are skipped) → fix or write the target; German and French links must retain their locale prefix. | | `anchors` | An internal fragment without a matching rendered heading or explicit ID → use the renderer’s slug, or retain the old ID when renaming a section. | | `images` | An `/images/...` reference with no file under `public/`, empty alt text, over ~200 KB, or a raw `` tag (bypasses these checks) → fix the path, write a descriptive alt, export WebP, use markdown image syntax inside ``. | | `image-manifest` | A `.webp` on disk that no page references, one missing from `public/images/manifest.json` (hand-captured — regenerate via `bun run docs:screenshots`), a manifest entry with no file, or a width over 2880/odd (the DPR-2 contract, parsed by `lib/webp-size.ts`). | | `videos` | A video asset outside `public/videos/manifest.json` (hand-recorded — produce via `bun run docs:videos`), a stale entry, a name off `..(mp4\|vtt\|webp)`, an episode missing a base locale, a `