miwa とは
miwa（三和）は、業務要求（doc）・システム要件（req）・テスト（test）の3層を依存関係で結び、どれかが更新されたのに残りが追随していない状態を検知する CLI です。Rust で書かれています。
doc を直したら req を、req を直したらテストを見直す。こうした約束はレビューで見落とされがちです。miwa は3層の内容を前回合意した時点と比べ、ずれた依存関係を機械的に報告します。人は「どう直すか」の判断に集中できます。
実装コードそのものは扱いません。テストを実装側の仕様とみなし、ドキュメントとテストの追随だけを見ます。機械的な検知（ハッシュ比較）は CI で使い、意味が合っているかの判定（judge）はローカルでだけ使います。
テストのマーカーを読み取れる言語は、Go・Rust・C#・Java・Kotlin・TypeScript・JavaScript・Dart（Flutter）です。
例えば
miwa を使うと、次のことができます。
- req を変えたのにテストが古いままの PR を、CI で失敗させる
- どの doc からも参照されていない req や、テストが1件もない req を見つける
- 変更が妥当だと判断した依存関係を、理由付きで「合意済み」として記録する
- doc と req が意味的に食い違っていないかを、AI のスコアで確かめる
- 文書の索引（
index.md）を保ち、GitHub を使わない人もブラウザで読めるサイトを作る
doc・req・test は、それぞれ次のように書いてつなぎます。doc は Markdown のリンクで req を参照し、test はコメントのマーカーで req の id を指します。ここでは docs/auth.md、req/auth/password-min-length.md、tests/auth_test.go の3つのファイルに置きます。
type: BusinessNeed
id: DOC-AUTH
title: "ログイン"
description: "メールアドレスとパスワードで認証する。"
ユーザーはメールアドレスとパスワードで認証する。
パスワードは [最小長の制約](../req/auth/password-min-length.md) に従う。
type: Requirement
id: FR-001
8文字未満のパスワードは登録時に拒否する。
// [FR-001]
func TestRejectsShortPassword(t *testing.T)
この状態で miwa index を実行して索引を作り、miwa reconcile --all で合意として記録したとします。そのあと req の「8文字未満」を「12文字未満」に変えると、miwa check --gate は次のように報告し、終了コード 2 を返します。
drift Edge doc-req:DOC-AUTH:FR-001 ReqChanged edge doc-req:DOC-AUTH:FR-001 drifted from the agreed state
drift Edge test-req:tests:TestRejectsShortPassword:FR-001 ReqChanged edge test-req:tests:TestRejectsShortPassword:FR-001 drifted from the agreed state
doc とテストを見直して問題がなければ、miwa reconcile で新しい内容を合意として記録し直します。
使い始める
インストール
インストーラ、cargo binstall、cargo install のどれでも入れられます。入れたら miwa --version で確かめてください。
インストーラ
macOS / Linux はシェルスクリプトで入れます。$CARGO_HOME/bin（既定は ~/.cargo/bin）に置かれます。
|
Windows は PowerShell で入れます。
powershell -ExecutionPolicy Bypass -c "irm https://github.com/NikoSanko/miwa/releases/latest/download/miwa-cli-installer.ps1 | iex"
latest を download/vX.Y.Z に置き換えると、バージョンを固定できます。
cargo binstall
cargo-binstall があれば、GitHub Releases のビルド済みバイナリを入れられます。
cargo install
Rust ツールチェーン（rustup）が必要です。crates.io からソースをビルドして入れます。
Git のタグを指定して入れることもできます。
リポジトリをクローンし、その中で cargo install --path . --locked を実行しても入れられます。
Releases から手動で入れる
Releases から、環境に合うアーカイブ（miwa-cli-<target>.tar.xz。Windows は miwa-cli-x86_64-pc-windows-msvc.zip）をダウンロードします。各アーカイブには、チェックサムのファイル（<アーカイブ名>.sha256）が付いています。同じディレクトリに保存し、展開前に次のコマンドで検証してください。macOS では sha256sum の代わりに shasum -a 256 を使います。
# macOS
検証できたらアーカイブを展開し、miwa（Windows では miwa.exe）を PATH の通った場所に置きます。全アーカイブのチェックサムをまとめた sha256.sum も添付されています。
v0.5.0 から、成果物の名前を miwa-cli-<target>.tar.xz の形に変え、チェックサムのファイルも SHA256SUMS から上記のものに変えました。
CI で使う
pull request ごとに miwa check --diff --gate を実行する GitHub Actions のテンプレートを templates/miwa-check.yml に置いています。.github/workflows/ にコピーして使います。
今後の配布計画は Issue #6 を参照してください。
既存プロジェクトへの導入
miwa initを実行して.miwa/config.yamlを作ります.miwa/config.yamlで、doc・req・test を探すフォルダを指定します- doc・req・テストのマーカーを整えます
miwa reconcile --allで、現状を合意として記録します.miwa/をコミットします- CI で
miwa check --gate（または--diff）を実行します
詳しくは miwa を使い始める を参照してください。
コマンド
| コマンド | 役割 | 詳細 |
|---|---|---|
miwa init |
既定値の .miwa/config.yaml を作る |
使い始める |
miwa check |
前回の合意と比べて、追随漏れや孤立した req などを報告する | check |
miwa reconcile |
依存関係の現在の内容を、合意としてロックに記録する | reconcile |
miwa judge |
check が報告した依存関係の両端が、意味的に整合しているかを判定する |
judge |
miwa index |
文書のタイトルと要約から、索引（index.md）を更新する |
index |
miwa site |
索引の木を、ブラウザで読める静的な HTML 一式として出力する | site |
終了コードは、成功が 0、設定不備などの実行エラーが 1 です。check --gate は、finding が1件でもあれば 2 を返します。
judge は、対象の doc・req・test の本文を TypeSafe AI（api.typesafe.ai）に送ります。環境変数 TYPESAFE_API_KEY が必要です。社外に出せない内容を含むリポジトリでは、事前に確認してください。
ドキュメント
使い方の詳細は docs/ にまとめています。
- doc・req・test の3層モデルとファイルの書き方（言語ごとのテストのマーカーの書き方を含みます）
- miwa を使い始める（設定ファイルの全項目）
- 更新漏れを検知する
check - 合意を記録する
reconcile - 意味が合っているかを判定する
judge - 索引を保つ
index - 閲覧サイトを作る
site - α版の要件・仕様 / 詳細検討の参考資料
開発に参加する
リポジトリをクローンし、テストとリンターが通ることを確かめます。
このリポジトリ自身も miwa でチェックしています。.miwa/config.yaml では、docs を doc、req を req、src と tests を test の探索対象にしています。CI でも miwa check --gate を実行しているので、仕様を変えるときは docs/ と req/ も合わせて更新してください。
次に取り組む予定のことは、Issue にまとめています。