01
実装済みの機能
02
はじめ方
- CargoでCLIを導入し、検査したいプロジェクトへ移動します。
- kml check README.mdで指摘を確認します。修正する場合は差分を確認しながらfixやfmtを利用します。
Rustと必要な開発ツールを準備し、導入前にリンク先のREADMEで環境要件を確認してください。実行例は機能の入口であり、すべての環境での動作を保証するものではありません。
根拠cargo install katana-markdown-linter
kml check README.md
kml fix --diff README.md01 / KML
どんな場面で使うか
CIでMarkdown品質を検査
kml checkで単一ファイル、glob、stdin、またはcurrent directory以下のMarkdownを検査し、rule ID・severity・位置付きの診断を得ます。違反時exit 1、filesystem/config error時exit 2なのでCIの成否判定へ接続できます。
safe fixと整形を自動化
kml fixまたはcheck --fixでsafeな修正を適用し、kml fmtで改行・空行・リスト字下げなどのレイアウトを整えます。unsafeな修正は明示opt-inに限定できるため、CIと開発者ローカルの責務を分けられます。
02 / KML
入力から出力までの流れ
contentとoptionsを渡す
libraryならMarkdown文字列とLintOptionsをMarkdownLinter::lintへ渡し、CLIならkml check README.mdや--stdinなどで入力源を指定します。configとrule設定は利用する実行経路に合わせて解決されます。
全ruleを評価する
linterはoptionsからseverity mapを作り、Markdown rule群を対象path・content・rule設定へ適用します。結果は公開LintResultへ変換され、rule IDやseverityを利用側が読めます。
診断または修正結果を扱う
lintはVec<LintResult>を返し、fixは最大8 passまでfix可能な結果を適用してFixResultを返します。CLIでは違反が残るか、修正後も違反が残るかをexit codeでCIへ伝えます。
03 / KML
主要API・CLIの使い分け
MarkdownLinter::lint- メモリ上のcontentをlintし、Result<Vec<LintResult>, Error>を返します。ファイルI/Oを呼び出し側で制御したい統合テストやeditor連携に向きます。
MarkdownLinter::fix- contentを内部コピーし、fix可能な診断がなくなるか8 passに達するまでsafe fixを適用します。戻り値のcontent、適用数、詳細から変更結果を確認できます。
MarkdownLinter::fix_with_results- 既に取得したLintResultへsafe fixを適用する低レベル入口です。診断を表示した後に同じ結果を修正処理へ渡す場合に使います。
kml check / fix / fmt- CLIはcheck、fix、fmt、stdin、file、glob、JSON出力などを提供します。利用者はファイル探索をCLIへ任せるか、library APIでcontentとoptionsを直接管理できます。
04 / KML
具体例で理解する
見出しレベル違反をRust APIで検出
# Titleの次に### Skipped headingを置いたMarkdownをMarkdownLinter::lintへ渡し、返った各LintResultのrule IDとmessageを表示します。公開crateのテストと同じく、見出しincrement違反が診断として現れる入力です。
use katana_markdown_linter::{LintOptions, MarkdownLinter};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let results = MarkdownLinter::lint(
"# Title\n\n### Skipped heading\n",
&LintOptions::default(),
)?;
for result in results {
println!("{}: {}", result.rule_id, result.message);
}
Ok(())
}05 / KML
組み込み条件と責務の境界
safe/unsafeの責務を分ける
通常のfixとcheck --fixはsafe fixに限定し、unsafe fixは--unsafe --yesを明示指定します。自動CIではsafe経路、開発者の意図的な書換えではunsafe経路という運用に分けられます。
exit codeを品質gateへ接続する
ファイル未指定ならcurrent directory以下を再帰処理し、違反はexit 1、filesystem/config errorはexit 2です。CIは診断本文の表記に依存せず、exit codeを一次判定にできます。
根拠
調査時点の公開リポジトリに基づく紹介です。リンク先の固定コミットで実装と手順を確認できます。