Validation

Validation should match the risk of the change. Prose-only edits need lighter checks than changes to executable cells, helper crates, or browser-visible runtime behavior.

Common Checks

Run the required lint and formatting gate for every code or configuration change:

pnpm lint
pnpm format:check

pnpm lint runs ESLint for JavaScript, MJS, TypeScript, TSX, and Astro with zero warnings, verifies Prettier formatting, and runs the strict Rust lint. Use pnpm format to apply the configured source, config, Markdown/MDX, JSON, and YAML format.

Run pnpm check for normal documentation changes:

pnpm check

This regenerates the development runtime and runs Astro checks. It catches most MDX, frontmatter, route, import, and TypeScript issues.

Run the documentation contract checker whenever prose, navigation, package exports, command examples, or public schemas change:

pnpm test:docs
pnpm test:package

test:docs validates internal files/routes/fragments, English/Japanese route parity, sidebar entries, every package export/path/CLI contract, JSON examples, package imports, and shell commands. test:package confirms the README and required public files are present in the npm archive.

Run the full suite before broad changes are considered complete when practical:

pnpm test

Runtime and Browser Checks

Use these commands when changing executable cells, cell metadata, rich output examples, Mermaid examples, media examples, or browser-visible behavior:

pnpm wasm:dev
pnpm test:wasm
pnpm test:haskell
pnpm build
pnpm test:bundle
pnpm test:dev-hmr
pnpm test:e2e

pnpm wasm:dev regenerates the runtime for local development. It requires wasm32-wasi-ghc when Haskell cells are present, as do pnpm build, pnpm check, pnpm wasm:build, and pnpm test:wasm. pnpm dev and pnpm dev:runtime are intentionally more forgiving: they keep Astro serving and show a Haskell cell error in the browser if the Haskell compiler is missing or a Haskell compile fails. pnpm test:wasm verifies generated Rust cell behavior, and pnpm test:haskell executes the generated Haskell/WASI runtime. pnpm test:e2e runs the full browser suite in Chromium, Firefox, and WebKit.

pnpm test:dev-hmr runs a standalone Chromium smoke against a temporary copy of the workspace. It installs dependencies offline from the pnpm store, builds the package, generates the initial runtime, edits an MDX cell, and verifies source and reactive output updates remain stable. Run pnpm install --frozen-lockfile first to populate the store; Rust/Wasm, wasm32-wasi-ghc, and Playwright Chromium are required. PR CI runs it once in the Linux packed-browser job, after the packed consumer smoke.

Production builds write dist/oxiquill/bundle-report.json and fail when an emitted client or worker JavaScript chunk exceeds 650 KiB uncompressed. Run pnpm test:bundle after pnpm build to verify the budget and confirm that ECharts and Mermaid remain behind dynamic import boundaries.

Unit and Coverage Checks

Use unit tests for handwritten TypeScript, Preact, and Node runtime code:

pnpm test:unit
pnpm test:unit:coverage

Coverage requires 85% statement, branch, function, and line coverage across handwritten CLI, Astro integration, config/path, manifest, worker, generator, and runtime modules. Only generated output and type-only declarations are excluded. Add focused tests for uncovered handwritten code instead of editing generated files.

Packed Consumer Checks

Verify installation without workspace links through both supported package managers:

pnpm test:consumer:npm
pnpm test:consumer:pnpm
pnpm test:packed-browser

The consumer commands pack oxiquill, install the tarball in a temporary standalone project, check and build a zero-cell site with only Node on PATH, then add Rust and Python cells and verify their generated runtimes without workspace links. test:packed-browser additionally builds Python and Haskell cells from the installed package, launches Astro preview in background mode, and executes both cells through their real workers in Chromium. It also verifies that clean preserves the download cache and that offline generation can reuse it.

Pull requests require compatibility jobs on Linux, macOS, and Windows, Haskell runtime jobs on Linux and macOS, the packed Chromium job on Linux, and full browser jobs for Chromium, Firefox, and WebKit. Every supported matrix cell is merge-blocking.

Rust Helper Checks

Optional reusable Rust helper crates live under crates/* in an Oxiquill site. Validate them with:

pnpm test:rust
pnpm test:rust:coverage
pnpm lint:rust
pnpm doc:rust

test:rust:coverage uses cargo-llvm-cov and requires 85% line/function/region coverage for helper crates. If no helper crates exist, helper commands skip cleanly.

Troubleshooting Failed Checks

• Unknown Rust crate: match the cell crates value to the package.name in crates/*/Cargo.toml.
• Unsupported Python package: use a vendored Pyodide package or add package support before documenting it.
• Missing Python runtime: confirm public/oxiquill/pyodide exists and run pnpm wasm:dev or pnpm build.
• Missing Haskell compiler: install wasm32-wasi-ghc, source ~/.ghc-wasm/env if using ghc-wasm-meta, or set OXIQUILL_HASKELL_GHC to the compiler path, then rerun pnpm wasm:dev or pnpm build.
• Missing Haskell runtime: confirm public/oxiquill/haskell-wasm/status.json exists and rerun runtime generation.
• Mermaid failure: confirm the code block language is mermaid and run pnpm build for MDX errors.
• Missing media: confirm the file is under public/media and the MDX URL starts with /media/.
• Coverage failure: add focused tests for handwritten source rather than modifying generated output.
• Documentation link/contract failure: fix the referenced page, route, public contract table, or canonical command instead of adding an exception.