v4 から v5 へのマイグレーション
Markuplint v5 の破壊的変更をまとめたガイドです。該当する項目を確認してください。
はじめに
Node.js を v22.0.0 以降にアップデートしてください。Markuplint v5 の全パッケージで必須です。
AI によるマイグレーション支援
Claude Code を使用している場合、対話的にアップグレードを進めるマイグレーションスキルをインストールできます:
npx skills add markuplint/markuplint@migrate4-5
ユーザー向け
CLI ユーザー、設定ファイル作成者、CI/CD パイプラインに影響する変更です。
| 領域 | 変更内容 | 影響範囲 |
|---|---|---|
| Node.js | 最小バージョンを v22.0.0 に引き上げ（旧: v18.18.0）。ポリフィル削除。TypeScript ターゲットを ES2022 に変更。 | 全ユーザー |
| CLI | --fix-dry-run フラグ追加。--allow-warnings のデフォルトが true に変更。--config がデフォルト設定ファイルとマージしなくなった。 | CLI ユーザー、CI/CD パイプライン |
| 設定 | 共通 ARIA バージョン用の ruleCommonSettings 追加。Named nodeRules による個別設定可能なチェック。配列値が連結から上書きに変更。Options が shallow merge に変更。:closest() セレクタ非推奨。 | 設定ファイル作成者、プリセット作成者 |
| ARIA | ARIA 1.3 がデフォルトに（旧: 1.2）。generic ロールが透過的に。<aside> の条件付きロールマッピング。image/img ロールが同義語に。wai-aria オプションのリネーム。 | 全ユーザー |
| フレームワーク | @markuplint/htmx-parser 削除（@markuplint/htmx-spec に移行）。@markuplint/alpine-parser/spec 削除（@markuplint/alpine-spec に移行）。directivePatterns システム追加。useIDLAttributeNames を acceptedAttrNames にリネーム。 | htmx / Alpine.js ユーザー、スペックパッケージ作成者 |
ルール
| ルール | 変更内容 | 影響範囲 |
|---|---|---|
| invalid-attr | 属性値の { type: X } ラッパー廃止。非推奨の attrs オプション削除。オブジェクト形式を非推奨化。 | allowAttrs / disallowAttrs を使用する設定作成者 |
| required-element | ignoreOmittedElements のデフォルトが false から true に変更。ゴースト要素が要件を満たさなくなった。 | required-element を使用する設定作成者 |
| deprecated-element | 非標準要素の検出が no-unsupported-features に移管。 | 非標準要素の検出に依存する設定作成者 |
| textlint | @markuplint/rule-textlint パッケージを削除。textlint 単体で textlint-plugin-html を使用。 | textlint ルールのユーザー |
| parse-error (組み込み) | 組み込みチャネルが、致命的 ParserError に加えて HTML LS の非致命的なパースエラー (parse5 onParseError イベント) も surface できるように。デフォルトはオフ — severity.parseError で parse5 の code 単位にオプトイン。severity.parseError は Partial<Record<MLASTParseErrorCode, …>> 形式も受け付け、code ごとに severity を指定可能。新しい parserOptions.documentMode ('auto' | 'document' | 'fragment') で document/fragment 自動判定をオーバーライドできるので、<head> 始まりの SSR partial で document レベルのエラーを無効化したり、doctype を省略した完全な page で missing-doctype を opt-in したりできます。 | 非致命的な HTML LS パースエラーも lint したいユーザー |
開発者向け
カスタムルール作成者、パーサープラグイン開発者、Node.js API ユーザーに影響する変更です。
| 領域 | 変更内容 | 影響範囲 |
|---|---|---|
| ルール修正関数 | カスタムルール向けの新しい自動修正 API。9つの組み込みルールが --fix に対応。 | カスタムルール作成者 |
| API | レガシーの exec() 関数を削除。結果に FixSummary 追加。computeCursorOffset() をエクスポート。 | Node.js API ユーザー |
| AST | トークンプロパティのリネーム（startOffset から offset 等）。selfClosingSolidus 削除。MLMarkupLanguageParser 型の削除。 | パーサープラグイン開発者 |
ヒント
CLI や CI/CD でのみ Markuplint を使用している場合、「開発者向け」セクションはスキップできます。