API の変更

このページでは Node.js API の破壊的変更について説明します。Markuplint をプログラムから呼び出している場合や、エディタ連携を構築している場合は確認してください。

変更一覧

変更内容	影響範囲
exec() 関数の削除	exec() を直接呼び出しているユーザー
結果に FixSummary を追加	fix: true を使用する API ユーザー
computeCursorOffset() の追加	エディタ連携の開発者

exec() 関数の削除

破壊的変更

レガシーの exec() 関数は削除されました。v1 から非推奨でした。

exec() を MLEngine に置き換えてください。

変更前（v4）：

import { exec } from 'markuplint';

const results = await exec({
  files: 'index.html',
  config: '.markuplintrc',
});

変更後（v5）：

import { MLEngine } from 'markuplint';

const file = await MLEngine.toMLFile('index.html');
const engine = new MLEngine(file, {
  configFile: '.markuplintrc',
});
const result = await engine.exec();

オプションの対応表

以下の表で exec() のオプションを MLEngine に変換してください。

exec() オプション（v4）	MLEngine での対応（v5）
files	MLEngine.toMLFile() の第1引数
sourceCodes / names / workspace	MLEngine.toMLFile({ sourceCode, name, workspace })
config（文字列）	configFile オプション
config（オブジェクト）	config オプション
defaultConfig	defaultConfig オプション
rules	rules オプション
rulesAutoResolve	autoLoad オプション
fix	fix オプション
locale	locale オプション

新機能: 結果の FixSummary

fix: true で実行すると、結果に fixSummary フィールドが含まれるようになりました。fix プロセスで何が起きたかを確認できます。

const result = await engine.exec();
if (result?.fixSummary) {
  console.log(`パス数: ${result.fixSummary.passCount}`);
  console.log(`適用数: ${result.fixSummary.totalApplied}`);
  console.log(`スキップ数: ${result.fixSummary.totalSkipped}`);
}

フィールド	型	説明
passCount	number	実行された fix パスの回数
totalApplied	number	全パスで適用された fix の合計数
totalSkipped	number	編集の重複によりスキップされた fix の数
reachedMaxPasses	boolean	10パスの安全上限に達したかどうか
firstPassEdits	readonly TextEdit[]	最初のパスで適用された編集（元のオフセット）

備考

これは新しい追加機能であり、破壊的変更ではありません。既存のコードへの影響はありません。

新機能: computeCursorOffset()

エディタ連携のために、@markuplint/ml-core から computeCursorOffset() がエクスポートされるようになりました。元のソースコード上のカーソル位置を、修正後のソースコード上の位置にリマップします。

import { computeCursorOffset } from '@markuplint/ml-core';

const newOffset = computeCursorOffset(result.fixSummary.firstPassEdits, originalCursorOffset);

最初のパスの編集情報（元のソースコードのオフセットを参照）を使い、修正後のコードでのカーソル位置を計算します。

ヒント

FixSummary と computeCursorOffset() を組み合わせることで、エディタプラグインでスムーズな修正・ナビゲーション体験を実現できます。