コンテンツにスキップ
Oxiquill

検証

検証は変更の risk に合わせます。本文だけの変更は、実行可能セル、helper crate、browser-visible runtime behavior の変更より軽い check で十分です。

よく使う check

Section titled “よく使う check”

code または config を変更した場合は、必須の lint と format gate を実行します。

Terminal window
pnpm lint
pnpm format:check

pnpm lint は JavaScript、MJS、TypeScript、TSX、Astro に ESLint を warning なしで実行し、Prettier format と strict Rust lint も確認します。設定済みの source、config、Markdown/MDX、JSON、YAML format を適用するには pnpm format を使います。

通常のドキュメント変更では pnpm check を実行します。

Terminal window
pnpm check

この command は development runtime を再生成し、Astro check を実行します。多くの MDX、frontmatter、route、import、TypeScript の問題を検出できます。

prose、navigation、package export、command example、public schema を変更した場合は documentation contract checker も実行します。

Terminal window
pnpm test:docs
pnpm test:package

test:docs は internal file/route/fragment、英日 route parity、sidebar entry、全 package export/path/CLI contract、JSON example、package import、shell command を検証します。test:package は README と必須 public file が npm archive に入ることを確認します。

広い変更が完了したら、可能な範囲で full suite を実行します。

Terminal window
pnpm test

runtime と browser check

Section titled “runtime と browser check”

実行可能セル、cell metadata、rich output example、Mermaid example、media example、browser-visible behavior を変更した場合は、次の command を使います。

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

pnpm wasm:dev は local development 用 runtime を再生成します。Haskell セルがある場合は wasm32-wasi-ghc が必要で、pnpm build、pnpm check、pnpm wasm:build、pnpm test:wasm でも同じです。pnpm dev と pnpm dev:runtime は意図的により寛容で、Haskell compiler がない、または Haskell compile に失敗しても Astro の serving を続け、browser 上の Haskell セルに error を表示します。pnpm test:wasm は生成 Rust cell の動作を確認し、pnpm test:haskell は生成 Haskell/WASI runtime を実行します。pnpm test:e2e は Chromium、Firefox、WebKit で full browser suite を実行します。

pnpm test:dev-hmr はワークスペースの一時コピーで Chromium の開発スモークテストを実行します。pnpm store からのオフラインインストール、パッケージのビルド、初回 runtime 生成の後に MDX セルを編集し、ソースと reactive 出力の更新が安定することを確認します。先に pnpm install --frozen-lockfile で store を準備してください。Rust/Wasm、wasm32-wasi-ghc、Playwright Chromium が必要です。PR CI では Linux の packed-browser job で packed consumer smoke の後に1回実行します。

production build は dist/oxiquill/bundle-report.json を生成し、出力された client または worker の JavaScript chunk が uncompressed で 650 KiB を超えると失敗します。pnpm build の後に pnpm test:bundle を実行すると、budget と ECharts/Mermaid の dynamic import boundary を検証できます。

unit と coverage check

Section titled “unit と coverage check”

手書き TypeScript、Preact、Node runtime code には unit test を使います。

Terminal window
pnpm test:unit
pnpm test:unit:coverage

coverage は手書きの CLI、Astro integration、config/path、manifest、worker、generator、runtime module に statement/branch/function/line 85% を要求します。除外するのは生成物と type-only declaration だけです。生成物を編集するのではなく、未 covered の手書き code に focused test を追加します。

packed consumer check

Section titled “packed consumer check”

workspace link を使わない install を、両方の supported package manager で確認します。

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

consumer command は oxiquill を pack し、tarball を一時的な standalone project に install して、PATH に Node だけがある状態で zero-cell site を check/build します。その後 Rust/Python cell を追加し、workspace link なしで対応 runtime の生成を検証します。test:packed-browser は install 済み package から Python/Haskell cell も build し、Astro preview を background mode で起動して、実際の worker 経由で両 cell を Chromium 内で実行します。さらに clean が download cache を保持し、offline generation が再利用できることも確認します。

pull request では Linux、macOS、Windows の compatibility job、Linux/macOS の Haskell runtime job、Linux の packed Chromium job、Chromium、Firefox、WebKit の full browser job が必須です。supported matrix の全 cell が merge-blocking です。

Rust helper check

Section titled “Rust helper check”

Oxiquill site の再利用可能な任意の Rust helper crate は crates/* にあります。次の command で検証します。

Terminal window
pnpm test:rust
pnpm test:rust:coverage
pnpm lint:rust
pnpm doc:rust

test:rust:coverage は cargo-llvm-cov を使い、helper crate に line/function/region 85% coverage を要求します。helper crate がない場合、helper command は正常に skip します。

check 失敗時の確認

Section titled “check 失敗時の確認”
  • Unknown Rust crate: cell の crates 値を crates/*/Cargo.toml の package.name に合わせます。
  • Unsupported Python package: vendored Pyodide package を使うか、docs に書く前に package support を追加します。
  • Missing Python runtime: public/oxiquill/pyodide があるか確認し、pnpm wasm:dev または pnpm build を実行します。
  • Missing Haskell compiler: wasm32-wasi-ghc を install し、ghc-wasm-meta を使っている場合は ~/.ghc-wasm/env を source するか、OXIQUILL_HASKELL_GHC に compiler path を指定してから pnpm wasm:dev または pnpm build を実行します。
  • Missing Haskell runtime: public/oxiquill/haskell-wasm/status.json があるか確認し、runtime generation を再実行します。
  • Mermaid failure: code block language が mermaid か確認し、pnpm build で MDX error を確認します。
  • Missing media: file が public/media 配下にあり、MDX URL が /media/ で始まるか確認します。
  • Coverage failure: 生成物ではなく手書き source に focused test を追加します。
  • Documentation link/contract failure: exception を追加せず、referenced page、route、public contract table、canonical command を修正します。