設定項目（ツール別）¶

ツールごとの起動方式（python-runner / uvx既定 / js-runner / bin-runner / 直接実行）・2段階実行を扱う。基本設定（プリセット・言語カテゴリによる限定・並列実行等）は設定項目を参照。導入手順ははじめにを参照。

pyfltrは対応ツールを実行方式の観点から5カテゴリに分けて扱う。カテゴリ委譲を採用する3カテゴリでは既定値が対応するカテゴリ委譲値になっている。残る2カテゴリは共通の委譲先を持たず、"uvx"または"direct"を既定値とする。

python-runner経由（既定{command}-runner = "python-runner"）。対象はPython系ツール一式に加え、banditが該当する。 Python系ツール一式はmypy / pylint / pyright / ty / arid / pytest / ruff-format / ruff-check / uv-sortを指す。グローバルpython-runner設定（"uv" / "uvx" / "direct"）へ委譲する。既定"uv"ではcwdにuv.lockがありuvバイナリが利用可能な場合にuv run --frozen <bin>でプロジェクトのvenv経由で起動する
uvx既定のPython製ツール（既定{command}-runner = "uvx"）。対象はsemgrep / sqlfluff。本体依存から分離し、uvx <bin>で別環境へ解決する
js-runner経由（既定{command}-runner = "js-runner"）。対象はeslint / prettier / biome / oxlint / tsc / vitest / markdownlint-cli2 / textlint / designmd。 npm / pnpm / yarn等のJavaScriptパッケージマネージャー経由で起動する
bin-runner経由（既定{command}-runner = "bin-runner"）。対象はec / shellcheck / shfmt / actionlint / pinact / glab-ci-lint / taplo / hadolint / gitleaks / lychee。さらにcargo系（cargo-fmt / cargo-clippy / cargo-check / cargo-test / cargo-deny）も対象。 dotnet系（dotnet-format / dotnet-build / dotnet-test）も含む。グローバルbin-runner設定（既定"mise"）に従ってmiseまたはPATH経由でネイティブバイナリを解決する
直接実行（既定{command}-runner = "direct"）。対象はtypos・yamllint・pre-commit・prek・依存の脆弱性監査ツール（uv-audit・pnpm-audit・npm-audit・yarn-audit）。 PATH上または{command}-pathで指定した実行ファイルを直接呼び出す。監査ツールはパッケージマネージャー（uv・pnpm・npm・yarn）自体を解決し、auditサブコマンドを引数で付与する

{command}-runnerはカテゴリ委譲値と直接指定値の対称12値を許容する（per-toolオーバーライドと委譲を対等に並べる設計）。

種別	値	解決方法
カテゴリ委譲	`"python-runner"`	グローバル`python-runner`設定（`"uv"` / `"uvx"` / `"direct"`）へ委譲する
カテゴリ委譲	`"js-runner"`	グローバル`js-runner`設定（`"pnpx"` / `"pnpm"` / `"npm"` / `"npx"` / `"yarn"` / `"direct"`）へ委譲する
カテゴリ委譲	`"bin-runner"`	グローバル`bin-runner`設定（`"mise"` / `"direct"`）へ委譲する
直接指定	`"direct"`	PATH上または`{command}-path`で指定した実行ファイルを直接呼び出す
直接指定	`"mise"`	`mise exec <backend>@<version> -- <bin>`形式で起動する
直接指定	`"uv"`	cwdに`uv.lock`があり`uv`バイナリが利用可能なら`uv run --frozen <bin>`で起動。いずれかが欠ける場合はdirectフォールバック
直接指定	`"uvx"`	`uvx <bin>`形式で起動。`uv.lock`は参照せず`{command}-version`設定とも連動しない
直接指定	`"pnpx"` / `"pnpm"` / `"npm"` / `"npx"` / `"yarn"`	各JSパッケージマネージャー経由で起動する

個別ツール単位で起動方式を切り替えたい場合は{command}-runnerを明示する。例えばcargo-fmt-runner = "direct"でcargoをPATH経由で直接呼び出す形に切り替えられる。 mypy-runner = "uvx"を指定するとmypyだけuvx経由に切り替えられる。カテゴリ横断の無意味な組み合わせ（例: Python系ツールにpnpmを指定）は実行時エラーになる。

{command}-pathを非空に指定するとあらゆる{command}-runner設定より優先され、その値で直接実行する。個別パスを指定して使っている場合の後方互換の手段として機能する。

PATHの解決はpyfltrが自動で管理する。利用者側の追加設定は不要。

各ツールに共通する設定は設定項目、カスタムコマンドの仕様と事例はプロジェクト固有チェックの追加を参照。

python-runner経由実行ツール（Python系）¶

対象はmypy / pylint / pyright / ty / arid / pytest / ruff-format / ruff-check / uv-sortのPython系ツールとbandit。これらの{command}-runner既定値は"python-runner"（カテゴリ委譲値）で、グローバルpython-runner設定（既定"uv"）へ委譲して起動方式を解決する。

[tool.pyfltr]
# python-runner経路の解決先を切り替える（既定 "uv"）
python-runner = "uvx"

`python-runner`	挙動
`"uv"`（既定）	cwdに`uv.lock`があり`uv`バイナリが利用可能なら`uv run --frozen <bin>`でプロジェクトのvenv経由で起動。いずれかが欠ける場合はdirectフォールバック
`"uvx"`	`uvx <bin>`形式でPyPI最新版を都度取得して起動。`uv.lock`は参照せず`{command}-version`設定とも連動しない。`uvx`shim不在時はdirectフォールバック
`"direct"`	`shutil.which`で本体依存に同梱されたバイナリを直接呼ぶ

cwdのuvプロジェクトに対象ツールが登録されていない場合、uv run側がエラーで失敗する。その場合はツールをプロジェクトに追加するか、{command}-pathで明示するか、 {command}-runnerを"direct"へ切り替えて対応する。

ツール単位で個別に切り替えたい場合は{command}-runnerへ直接指定値を書く（例: mypy-runner = "uvx"でmypyだけuvx経由に切り替える）。

uvx指定の特徴¶

uvx指定は他の指定と異なり、uv.lockを参照せず{command}-version設定とも連動しない。 uvxの特性（PyPI最新版の都度取得）に合わせた仕様で、利用者プロジェクトの依存固定とは独立に動作する。バージョン固定が必要な場合は既定のまま（{command}-runner = "python-runner"×グローバルpython-runner = "uv"）で利用者プロジェクトのuv.lock管理に乗せることができる。個別ツールだけ別の指定へ切り替えたい場合は{command}-runnerに直接指定値を書くか、 {command}-pathで明示パスを指定する方法を使う。

ruff-format の 2 段階実行¶

ruff-format は既定の動作として ruff check --fix --unsafe-fixes と ruff format の2ステップを連続実行する。 importソートや自動修正可能なlint違反を整形と同時に処理するための挙動。

ステップ1のlint違反（ruff checkのexit 1）は無視され、別途 ruff-check コマンドで検出される。設定ミス等によるruffの異常終了（exit 2以上）は失敗と判定する。

ステップ1に--unsafe-fixesを既定の引数へ含めているため、自動修正可能な違反を幅広く整形できる。保守的に運用したい場合は後述のとおりruff-format-check-argsで上書きする。

fix段で使うruff-check-fix-args（既定値["--fix", "--unsafe-fixes"]）も同様に--unsafe-fixesを含めている。

[tool.pyfltr]
# ステップ 1 をスキップしたい場合 (既定は true)
ruff-format-by-check = false
# ステップ 1 の引数を差し替えたい場合 (既定は ["check", "--fix", "--unsafe-fixes"])
ruff-format-check-args = ["check", "--fix"]

uv-sort¶

uv-sortはpyproject.tomlの依存定義をソートするformatter。既定は無効。

[tool.pyfltr]
uv-sort = true

Python系ツールとして扱われ、python = trueで有効化される（プリセット20260411以降に含まれる）。 mypy / pylint / pytestも全プリセットに含まれ、python = trueだけで有効化される。

bandit¶

banditはPython専用source-level SAST。pyfltr本体依存に同梱されるため、uvx pyfltr単発でも利用できる。既定は無効（opt-in）。

[tool.pyfltr]
bandit = true

[tool.bandit]例:

[tool.bandit]
skips = ["B101"]

bandit本体はYAML/TOML形式の設定ファイルを自動読み込みしない。 pyfltrが起点cwd直下のpyproject.toml・.bandit.yaml・.bandit.tomlを順に探索し、最初に見つかったファイルを--configfile <絶対パス>形式でbanditへ自動注入する。利用者がbandit-argsで--configfileを指定済みの場合は注入をスキップする。 INI形式の.banditはbandit本体の--recursive時自動探索に委ねるため、pyfltr側からの注入対象外とする。 pyfltr既定のbandit-args = ["--quiet", "--recursive", "--format=json"]は出力パースのため必須引数を含む。 --format=jsonはJSON出力指定、--quietは非JSONノイズ抑制、--recursiveはディレクトリ指定時の再帰探索を行う。

arid¶

aridはPython専用の重複コードチェッカー。Rust実装で、pylintのduplicate-code（R0801）と同じ目的のチェックを担う。 pyfltr本体依存に同梱されるため追加の導入手順は不要で、presetとpython = trueの指定で有効化される。

チェック条件はpyproject.tomlの[tool.arid]へ書く。

[tool.arid]
min-lines = 10

min-linesは重複とみなす最小の実効行数で、既定値は4
コメント・docstring・import・関数シグネチャは既定の動作として正規化の対象となり、行数の判定から除かれる
同一ファイル内の重複も既定の対象に含める（same-file = falseで無効化できる）
設定の優先順位はコマンドライン引数・[tool.arid]・aridの組込み既定の順

pyfltr既定のarid-args = ["--project-root", "."]は出力パースのために必須の引数を含む。 aridは--project-rootを省略すると、渡されたパスの共通の親ディレクトリを基準としてチェック結果のパスを組み立てる。 pyfltrは対象ファイルを明示して渡すため、省略した場合のパスは起点cwd基準にならない。 arid-argsを上書きする場合は--project-rootの指定を残す。

意図的な重複は# arid: disableと# arid: enableで囲んで抑制する。

対象ファイルを限定する実行（パスを明示指定した実行や--changed-since）では限定の対象外となったファイルとの間の重複は検出されない。重複はファイルを横断して集約するチェックであり、渡されたファイルの範囲だけで判定するためである。リポジトリ全体を対象とする検出は引数なしのrun・ciで行う。

uvx既定のPython製ツール¶

semgrep / sqlfluffの既定値は無効（opt-in）で、{command}-runnerの既定値は"uvx"。これらが課す依存制約をpyfltr本体と他ツールの依存グラフから切り離すため、本体依存には同梱しない。 uvxと対象ツールのPATH上の実行ファイルがともに見つからない場合はresolution_failedになる。利用者が版を固定する場合は、対象パッケージを利用者プロジェクトへ個別に追加して {command}-runner = "direct"へ切り替えるか、{command}-pathで実行ファイルを明示する。

semgrep¶

semgrepは多言語SAST。他の依存へ厳密ピンを課すためpyfltr本体依存には同梱せず、 semgrep-runner = "uvx"の既定値により実行時に別環境へ解決する。 uvxが利用できる環境ならuvx pyfltr単発でも利用できる。 uv tool install semgrepで導入済みの環境がある場合はuvxがその環境を再利用するため、実行のたびの解決は発生しない。公式Dockerイメージはこの手順で導入済みである。導入済み環境が無い場合は実行のたびに依存を解決するため、版を固定したい場合や解決コストを避けたい場合はuv tool install semgrepで導入するか、 semgrep-pathまたはsemgrep-runnerで上書きする。ルールセット指定が必須のため既定は無効（opt-in）。

[tool.pyfltr]
semgrep = true
# 公開ルールセットを使う場合
semgrep-args = ["scan", "--json", "--error", "--config=auto"]
# 個別ルールセットを使う場合
# semgrep-args = ["scan", "--json", "--error", "--config=p/python", "--config=p/typescript"]

semgrep-argsの既定値は空。利用者はscanサブコマンド・出力形式・ルールセットをまとめて指定する。 --jsonは出力パースの前提条件で、含めないとpyfltrの違反抽出が機能しない。 --errorは違反検出時にsemgrepを非0終了させる指定で、含めないとsemgrep側がexit 0を返しpyfltr側でfailed検出できない。

sqlfluff¶

sqlfluffはSQL専用linter。他の依存へ上限制約を課すためpyfltr本体依存には同梱せず、 sqlfluff-runner = "uvx"の既定値により実行時に別環境へ解決する。 uvxが利用できる環境ならuvx pyfltr単発でも利用できる。 uv tool install sqlfluffで導入済みの環境がある場合はuvxがその環境を再利用するため、実行のたびの解決は発生しない。公式Dockerイメージはこの手順で導入済みである。導入済み環境が無い場合は実行のたびに依存を解決するため、版を固定したい場合や解決コストを避けたい場合はuv tool install sqlfluffで導入するか、 sqlfluff-pathまたはsqlfluff-runnerで上書きする。 dialect指定が必須のため、.sqlfluffをプロジェクトルートに配置する前提のopt-in。 sqlfluff lintサブコマンドをlinterとして起動する（sqlfluff formatサブコマンドは対象外）。

[tool.pyfltr]
sqlfluff = true

.sqlfluff例:

[sqlfluff]
dialect = postgres

pyfltr既定のsqlfluff-args = ["lint", "--format=json"]は出力パースのため必須引数を含む。変更する場合もlintサブコマンドと--format=jsonは維持する。

直接実行ツール¶

対象はtypos・yamllint・pre-commit・prek・依存の脆弱性監査ツール（uv-audit・pnpm-audit・npm-audit・yarn-audit）。 {command}-runner既定値は"direct"で、PATH上または{command}-pathで指定した実行ファイルをpyfltrが直接呼び出す。

typos¶

typosはスペルチェッカー。PyPI経由でインストールされるため、uv add pyfltrだけで利用可能。

[tool.pyfltr]
typos = true

既定の引数はtypos-args = ["--format", "brief"]。 typos-pathを変更したい場合は明示的に指定する。

[tool.pyfltr]
typos-path = "/path/to/typos"

プロジェクト固有の許可語がある場合は[tool.typos]セクションも追記する（詳細は推奨設定例の「typosの許可語設定」を参照）。

yamllint¶

yamllintはPython製のYAMLリンター。PyPI経由でインストールされるため、uv add pyfltrだけで利用可能。直接実行（PATH上またはyamllint-pathで指定した実行ファイル）で動作する。 actionlintの.github/workflows/*.yaml対象とは独立して、YAML全般を対象とする。

[tool.pyfltr]
yamllint = true
# 設定ファイルを指定したい場合
yamllint-args = ["-c", ".yamllint.yml"]

無指定時はyamllintコマンドを直接呼び出す。パスを変更したい場合はyamllint-pathを指定する。

[tool.pyfltr]
yamllint-path = "/path/to/yamllint"

違反を位置・ルール・重大度付きの診断として抽出するため、pyfltrはyamllint-parsable設定（初期値true）により-f parsableを注入する。この注入はyamllint-argsとは独立しており、yamllint-argsを上書きしても出力形式は変わらない。 yamllint-argsへ指定した-f・--formatは注入時に取り除かれる。 yamllint-parsable = falseとすると注入せず、yamllintの既定の出力形式になる。この場合もyamllintの終了コードによる成否は変わらないが、違反は診断として抽出されない。

pre-commit¶

既定の引数はpre-commit-args = ["run", "--files"]。 pyfltr関連hookの自動検出とSKIP環境変数の構築を含む共通仕様はpass-filenames設定を参照。 prekと同時に有効化すると同一フックを二重実行するため、pyfltrが警告を発行する。

prek¶

prekはRust製の.pre-commit-config.yaml実行系。 PyPI wheel配布のため、uvx prekまたはpyfltrと同じ環境のuv run prekで利用できる。

[tool.pyfltr]
prek = true

既定の引数はprek-args = ["run", "--config=.pre-commit-config.yaml", "--files"]。 --config明示指定はprekによるworkspace rootからの設定ファイル探索を抑止する。 prekの除外機能には依存せず、pyfltrが対象ファイルを選別して--filesで渡す。 pre-commitと同時に有効化すると同一フックを二重実行するため、pyfltrが警告を発行する。

依存の脆弱性監査ツール（uv-audit / pnpm-audit / npm-audit / yarn-audit）¶

依存パッケージの脆弱性を監査するツール群。それぞれパッケージマネージャー自体（uv / pnpm / npm / yarn）を直接実行し、auditサブコマンドを引数で付与する。マニフェスト（pyproject.toml / package.json）の存在をトリガーにプロジェクト単位で実行し、対象ファイルは渡さない。外部脆弱性データベースへの問い合わせでネットワーク接続が必須かつ結果が変動するため、いずれも既定は無効（opt-in）。

[tool.pyfltr]
uv-audit = true     # Python依存をuv auditで監査する
npm-audit = true    # JavaScript依存をnpm auditで監査する
# pnpm-audit = true # pnpmプロジェクトの場合
# yarn-audit = true # yarn classicプロジェクトの場合

既定引数は次のとおり。

uv-audit-args = ["audit", "--preview-features", "audit", "--frozen", "--no-progress"]。 --frozenで監査時にuv.lockを書き換えない。--preview-features auditは uv auditが実験的機能である旨の警告を抑止する
pnpm-audit-args・npm-audit-args・yarn-audit-argsはいずれも既定値["audit", "--json"]。 --jsonはpyfltrが脆弱性情報を構造化して抽出するために必須

uv auditはuv 0.10.8で追加されたサブコマンドだが、0.10.8・0.10.9は監査対象の件数を報告するのみで脆弱性を検出しない。 0.10.10以降は検出するが、0.11.1までは検出時も終了コード0を返す。非0の終了コードを返すのは0.11.2以降であり、uv-audit利用時はuv 0.11.2以降が必要（uv 0.11.2のリリースノートと uv PR #18512）。この要件はpyfltr側でも強制する。uv-auditの起動前にuvの版を取得し、0.11.2未満の場合と版を判別できなかった場合は実行せず解決失敗として扱う。解決失敗は{command}-severity = "warning"を設定しても格下げされない。監査を実施しないまま成功として報告される事態を防ぐため、判定できない場合も実行しない。要件を満たすuvが別の場所にある場合はuv-audit-pathで実行ファイルを指定する。 uv auditはuv側の実験的機能であり、仕様が予告なく変わる可能性がある。

yarn-auditはyarn classic（1.x）のJSON Lines出力を前提とする。 yarn berry（2+）はサブコマンド体系が異なるため、利用時は引数を上書きする。

[tool.pyfltr]
yarn-audit = true
yarn-audit-args = ["npm", "audit", "--json"]

js-runner経由で実行するツール¶

markdownlint-cli2 / textlint / designmd / eslint / prettier / biome / oxlint / tsc / vitestは js-runner設定で起動方式を切り替える。既定はpnpxで、グローバル/キャッシュから都度取得する挙動となる。 pnpxは公開設定名であり、実行時はPATH上のpnpmを使って pnpm --package <パッケージ> dlx <コマンド>形式へ解決される。 textlint-packagesなどの追加パッケージもdlxより前の--packageへ展開される。

プロジェクトのpackage.jsonで既にこれらのツールをインストール済みの場合は、 js-runnerをpnpm / npm / npx / yarn / directに切り替えるとよい。これによりCIなどでの再ダウンロードを避けられる。

eslint / prettier / biomeはプラグイン（typescript-eslint・prettier-plugin-svelte等）をpackage.jsonで管理するのが一般的。これらのツールを使うプロジェクトではjs-runner = "pnpm"（もしくはnpm / yarn / direct）を推奨する。

[tool.pyfltr]
# プロジェクトの node_modules を使う (pnpm exec 経由)
js-runner = "pnpm"

`js-runner`	挙動
`pnpx`	`pnpm --package ... dlx ...`経由で一時取得して起動する（既定）。`textlint-packages`は`--package`で展開される
`pnpm`	`pnpm exec`経由で起動する。パッケージは`package.json`側で管理する
`npm`	`npm exec --no --`経由で起動する
`npx`	`npx --no-install`経由で起動する。`textlint-packages`は`-p`で展開される
`yarn`	`yarn run`経由で起動する
`direct`	`node_modules/.bin/`配下の実行ファイルを直接起動する

{command}-pathを明示的に設定した場合はその値が優先され、自動解決は無効化される。グローバルインストール済みのtextlintを直接使いたい場合などに利用する。

[tool.pyfltr]
textlint-path = "textlint"
# 共通引数 (lint/fix 両モードで付与)
textlint-args = []
# lint モード専用の引数 (既定値は ["--format", "compact"]。ただし textlint-json = true の間は
# --format json へ差し替わるため、この既定値は実効しない)
textlint-lint-args = ["--format", "compact"]

textlint-lint-argsの既定値は["--format", "compact"]だが、初期状態で有効なtextlint-json設定が lint段へ--format jsonを注入し、既存の--format指定を除去する。このため既定の構成ではcompactではなくJSON出力が使われ、pyfltrはJSONを解析して違反を取得する。 compact出力を使う場合はtextlint-json = falseを設定する。

textlintのfix実行 (textlint --fix) では @textlint/fixer-formatter が使われ、compact フォーマッタを解決できない。このため --format 指定は textlint-args（共通）ではなく textlint-lint-args（lintモード専用）に分離している。

fix段では、pyfltrはtextlintを2段階で実行する（fix適用 → lintチェック）ため、残存違反は後段のlintチェックで取得される。 textlint-args（共通）に --format ペアを書いた場合、pyfltrはfixステップの起動コマンドから --format ペアを自動除去するためクラッシュしない。 --format 指定は textlint-lint-args（lintモード専用）に書くことを推奨する。

textlint-argsへ--cacheを書くと、lint段と後段のlintチェックはtextlintのキャッシュを使う。 fixステップでは、pyfltrが起動コマンドの末尾へ--no-cacheを加えてキャッシュを無効化する。 textlintはキャッシュに一致したファイルを修正しようとすると例外で終了する場合があるためである。 command-info textlintのfix_commandlineにも同じ引数が現れる。

fixステップが失敗した場合（終了コード1の例外を含む）は、後段のlintチェックが成功しても textlintをfailedとして扱い、fixステップの出力を結果へ残す。 show-runやMCPのshow_run_outputでfixステップの出力を確認できる。

prettier の 2 段階実行¶

prettierは--check（読み取り専用）と--write（書き込み）が排他のため、pyfltrは2段階で実行する。

まずprettier --checkを実行する。

rc == 0 → succeeded（整形済み）
rc == 1 → 続けてprettier --writeを実行し、rc == 0ならformatted、それ以外はfailed
rc >= 2 → failed（設定ミス等の致命的エラー、--writeは実行しない）

引数はprettier-check-args / prettier-write-argsで個別に上書きできる（既定はそれぞれ["--check"] / ["--write"]）。共通引数prettier-argsは両ステップの先頭に付与される。

[tool.pyfltr]
prettier = true
# キャッシュ等の共通引数
prettier-args = ["--cache"]

textlintのプリセット/ルール指定¶

textlintで利用するルール/プリセットパッケージはtextlint-packagesに列挙する。既定値として次のパッケージを持つ。

[tool.pyfltr]
textlint-packages = [
    "textlint-rule-preset-ja-technical-writing",
    "textlint-rule-preset-jtf-style",
    "textlint-rule-ja-no-abusage",
    "textlint-rule-preset-ai-words-ja",
]

textlint-packagesはpnpx / npxモード時に--package / -p展開される。 pnpm / npm / yarn / directモードではpackage.json側でインストールする前提のため無視される。

保護対象の識別子の破損検知¶

textlint --fixの自動修正が、コードブロック外の.NET / Node.jsなどの識別子を破損させることがある。 pyfltrはtextlint --fixのステップ直後に識別子の減少を調べる。破損の疑いがあればtextlint-identifier-corruptionソースの警告を発行する。識別子リストはtextlint-protected-identifiersで上書きでき、空リスト[]を指定すると検知を無効化できる。警告は注意喚起のみで、ツールの成否判定には影響しない。

[tool.pyfltr]
textlint-protected-identifiers = [".NET", "Node.js", "Vue.js", "Next.js", "Nuxt.js"]

designmd¶

designmdは@google/design.mdによるDESIGN.md形式仕様チェック。js-runner経由で起動する。対象ファイル名は仕様上DESIGN.md固定であり、リポジトリ内にDESIGN.mdが無い場合は自動的にスキップされる。既定値として有効化されているが、対象ファイル不在のプロジェクトでは実行されない。

設定キー名・コマンド名は内部識別子designmdを採用する（@google/design.mdはpyproject.tomlのドット区切りキーと衝突するため）。 npmパッケージ@google/design.mdへの対応付けはpyfltrが内部で行う。

[tool.pyfltr]
# 既定で有効。明示無効化したい場合のみ false を指定する
designmd = false

既定のdesignmd-args = ["lint"]はdesign.md lint <files>サブコマンドを構築する。出力はJSON形式（@google/design.mdの既定）で、pyfltrのパーサーがfindings配列から違反を抽出する。

eslint / prettier / biomeの設定¶

eslint / prettier / biomeの既定値はいずれも無効（opt-in）。全プリセットにJS/TS系ツールが含まれるため、preset = "latest" + javascript = trueだけで一式が有効化される。プラグインはpackage.json管理が前提のため、通常はjs-runner = "pnpm"と併用する。

[tool.pyfltr]
preset = "latest"
js-runner = "pnpm"
javascript = true

既定の引数は以下のとおり。必要に応じて上書きできる。

eslint:
- eslint-args = []（既定は空。--format jsonはeslint-json設定（既定true）が lint / fix両モードへ注入する）
- eslint-fix-args = ["--fix"]
- 注: ESLint 9系以降でcompact / unix / tap等のコアフォーマッタは除去されたため、コア標準のjsonを採用している
- eslint-argsを上書きする際は非コアフォーマッタを使わないこと
prettier:
- prettier-check-args = ["--check"] / prettier-write-args = ["--write"]
- 2段階実行の詳細は「prettierの2段階実行」を参照
biome:
- biome-args = ["check"]（checkサブコマンドを共通argsで常時適用。 --reporter=githubはbiome-json設定（既定true）が注入する）
- biome-fix-args = ["--write", "--unsafe"]（ruffの--unsafe-fixes採用方針に準拠）
- safe fixのみに戻したい場合はbiome-fix-args = ["--write"]に上書き
- 注: biome-argsの先頭からサブコマンド（check / lint / format）を外すと、 biomeはflag `--reporter` is not valid in this contextで始まるエラーをstderrへ出力し、終了コード1で失敗する。引数が完全に空の場合はヘルプ本文を表示して終了コード0を返すが、 pyfltrは対象ファイルを必ず末尾へ付与するためその形にはならない。いずれもチェックは行われないため、必ずサブコマンド名を残すこと
- 注: biomeの診断severityは各lintルールの既定値で決まり、fixのsafe / unsafeとは独立である。 useLiteralKeysとnoDoubleEqualsはいずれもunsafe fixを持つが、既定severityは前者がinfo、後者がerrorとなる。 --reporter=githubではinfoの診断が::noticeとして出力され、 pyfltrの出力（JSONL・github-annotations等）にもinfoとして反映する。 biome公式ドキュメントのとおり、infoは--error-on-warningsを渡しても終了コードに影響しないためCIの失敗扱いにはならない。 --diagnostic-levelは表示対象の限定のみに作用する。既定severityがinfoのルールをコマンドラインから昇格させる手段は無い。個別ルールをCIの失敗対象に変更したい場合はbiome.jsonのlinter.rules.*でseverityを上げる

oxlint / tsc / vitest¶

oxlint / tsc / vitestもjs-runner対応のツールで、既定値はいずれも無効（opt-in）。全プリセットに含まれるため、preset = "latest" + javascript = trueでeslint / prettier / biomeと同時に一式が有効化される。

[tool.pyfltr]
preset = "latest"
js-runner = "pnpm"
javascript = true

既定の引数は以下のとおり。

oxlint: oxlint-args = []
tsc: tsc-args = ["--noEmit"]、tsc-pass-filenames = false（プロジェクト全体をチェックするためファイル引数を渡さない）
vitest: vitest-args = ["run", "--passWithNoTests"]（runサブコマンドが必須、filter結果ゼロ時もsuccess扱い）

個別に無効化したい場合のみ{command} = falseを指定する。

bin-runner経由で実行するツール¶

bin-runner経由で起動するツールはページ冒頭の「3カテゴリ」節で示した通り。グローバルbin-runner設定（既定"mise"）で起動方式を切り替える。

ecはeditorconfig-checkerの略称。既定はmiseで、GitHub Releasesから取得した editorconfig-checker実行ファイルをバージョン管理付きで実行する。 PATH上のcargo / dotnet / cargo-deny等をPATH直接実行したい場合は、個別ツールに{command}-runner = "direct"を設定するか{command}-pathに明示的なパスを指定する。

[tool.pyfltr]
# mise経由で実行する（既定）
bin-runner = "mise"

`bin-runner`	挙動
`mise`	`mise exec <tool>@<version> -- <command>`で起動する（既定）。ツールの自動インストールにも対応
`direct`	PATH上のバイナリを直接実行する

ツールが見つからない場合はエラー扱い（failed）となる。

miseモードでも、miseバイナリ自体がPATH上に存在しない場合に限りdirect相当のPATH解決へ静かにフォールバックする。ディストロパッケージでshellcheck等のネイティブバイナリだけを導入した環境でも追加設定なしで動作させるための救済挙動である。

ただし、miseは存在するがmise execが失敗する場合（バージョン解決失敗・config未信頼など）はフォールバックせず、従来どおりfailed扱いとなる。

CIでの設定¶

GitHub ActionsでCIを実行する場合はjdx/mise-actionでmiseをセットアップする。

jobs:
  ci:
    runs-on: ubuntu-latest
    env:
      # mise等がGitHub APIを呼び出す際のレート制限（403）回避。
      GITHUB_TOKEN: ${{ github.token }}
    steps:
      - uses: actions/checkout@v7
      - uses: jdx/mise-action@v5
      - run: uvx pyfltr ci

GITHUB_TOKENを渡さないと、mise本体やツールのリリース取得時にGitHub APIの匿名レート制限へ達する。結果として、mise-actionのmise installおよびpyfltr経由のmise exec実行時の自動インストールが失敗する。 ${{ github.token }}と${{ secrets.GITHUB_TOKEN }}は等価。GitHub Actionsで自動発行されるため追加のシークレット設定は不要。

container:指定ジョブではsecrets.GITHUB_TOKENがコンテナ内へ自動で渡らないため、上記のとおりenv:への明示が必須。ジョブレベルenv:に置けばmise-actionステップとpyfltr実行ステップの両方をまとめてカバーできる。

miseを使わず、PATH上のバイナリを直接使う場合はbin-runner = "direct"を設定する。

mise-auto-trust¶

miseモードではworktreeやdotfiles配下のディレクトリなど、mise.tomlが未信頼扱いになっている場合に事前チェックが失敗することがある。 mise-auto-trustの既定値はtrueであり、未信頼configを検出するとmise trust --yes --allを自動実行して信頼を確立してからリトライする。 --allオプションはcwdおよびその親ディレクトリにある全configを対象とするため、プロジェクト外の親ディレクトリにmise.tomlが存在する場合もまとめて信頼される点に注意する。

mise-auto-trustが不要な場合は無効化できる。

[tool.pyfltr]
mise-auto-trust = false

無効化した場合、未信頼configが原因の失敗はmise由来のエラーメッセージとともにfailed扱いとなる。手動でmise trustを実行して対処する。

バージョン指定¶

{command}-versionでbin-runner対応ツールのバージョンを指定できる。既定は"latest"。 cargo系・dotnet系も同枠組みで指定できる。

[tool.pyfltr]
shellcheck-version = "0.10.0"
shfmt-version = "3.10.0"
cargo-fmt-version = "1.83.0"
dotnet-format-version = "9.0.100"

{command}-pathを明示した場合は、runner種別を問わず最初に評価され、その値で直接実行する（bin-runner設定を無視）。

miseモードでの起動コマンドの優先順位は次のとおり（{command}-path未指定時）。

{command}-versionに具体値を明示（"latest"以外）→ mise exec <tool>@<version> -- <command>を組み立てる
{command}-versionが既定"latest"のまま、かつmise設定にそのツールの記述がある → tool specを省略しmise exec -- <command>を組み立てる。 mise設定の対象はプロジェクトmise.tomlとグローバル設定の両方
いずれも該当しない → mise exec <backend>@latest -- <command>を組み立てる

2の挙動により、mise設定に記述したバージョン固定やcomponents指定がpyfltr経由の実行にもそのまま反映される。 cargo-fmt-version等をpyfltr側で別途明示する二重管理は不要。

{command}-versionに具体値を明示した場合は常にmise exec <backend>@<version> -- <command>を組み立てる。

[tool.pyfltr]
# rust@1.83.0 を明示して起動する場合
cargo-fmt-version = "1.83.0"

directモードではバージョン指定は無視される。

値に:または@を含む場合は、miseのtool spec全体として扱う。 <bin_name>@接頭辞や既定backendの付与は行われず、値がそのままmise execに渡る。 mise registryに無いツールへ切り替えたい場合や、既定backendを上書きしたい場合に利用する。

[tool.pyfltr]
# aquaレジストリ経由で取得（cargo-denyの既定値）
cargo-deny-version = "aqua:EmbarkStudios/cargo-deny@0.16.0"
# 既定backend（aqua）を上書きしてmise registry経由を維持する場合は次を指定する
# cargo-deny-version = "cargo-deny@latest"

{command}-runnerによる個別ツール切替¶

ツール単位で起動方式を変更したいときは{command}-runnerを指定する（対称12値の意味はページ冒頭の早見表を参照）。

"mise"を明示できるのは本カテゴリ（bin-runner対応のec系・cargo系・dotnet系）に限る。 typos / yamllint / Python系ツールなどbackend未登録のツールに"mise"を明示すると、設定読み込み時または解決時に明確なエラーとして拒否する（typo・誤設定の早期検知のため）。

[tool.pyfltr]
# cargo系をPATH直接実行に戻す
cargo-fmt-runner = "direct"
cargo-clippy-runner = "direct"
# 個別ツールだけmise経由（グローバルはdirectのまま）
shellcheck-runner = "mise"

direct実行時、対象がdotnetバイナリの場合は環境変数DOTNET_ROOT配下のdotnet実行ファイルを優先採用する（PATHにdotnetが無くてもSDK配置場所で起動できる運用を救済するため）。 miseモードではDOTNET_ROOTは参照せず、miseが管理する環境に委ねる。

bin-runner対応ツールの設定¶

各ツールの既定値はすべて無効。有効化にはpyproject.tomlで切り替える。

[tool.pyfltr]
ec = true
shellcheck = true
shfmt = true
actionlint = true
pinact = true
glab-ci-lint = true
taplo = true
hadolint = true
gitleaks = true
cargo-fmt = true
cargo-clippy = true
cargo-check = true
cargo-test = true
cargo-deny = true
dotnet-format = true
dotnet-build = true
dotnet-test = true

既定の引数は以下のとおり。必要に応じて上書きできる。

ec: ec-args = ["-format", "gcc", "-no-color"]
shellcheck: shellcheck-args = ["-f", "gcc"]
shfmt: shfmt-check-args = ["-l"] / shfmt-write-args = ["-w"]（2段階実行。共通引数はshfmt-argsで指定）
actionlint: actionlint-args = []
pinact: pinact-args = ["run", "--no-api", "--format", "sarif"]（.github/workflows/配下のworkflowを対象とする）。 uses:が40文字のSHAと版コメントでピン留めされているかだけを確かめ、GitHub APIを呼ばないためGITHUB_TOKENを要しない。ピン留めの有無を報告するだけで、ファイルを書き換えない。タグからSHAへの書き換えはGitHub APIを要し、結果が実行時点の最新リリースで変わるため、pyfltrの自動修正の対象にしない。ピン留めはpinact runを直接実行して行う
glab-ci-lint: glab-ci-lint-args = ["ci", "lint"]（glab ci lintサブコマンドを既定値として保持）。 GitLabリモートが未登録または未認証の環境ではglab自身がエラー終了するため、pyfltrが自動でスキップ扱いに変換する
taplo: taplo-check-args = ["check"] / taplo-write-args = ["format"]（2段階実行。共通引数はtaplo-argsで指定）
hadolint: hadolint-args = []（Dockerfileを対象とするためtargetsにDockerfile・Dockerfile.*・*.Dockerfileを含む）
gitleaks: gitleaks-args = ["detect", "--no-banner"]（detectサブコマンドを既定値として保持）。 pass-filenames = falseによりリポジトリ全体を対象とする
lychee: lychee-args = ["--format", "json", "--no-progress"]（出力パースのためJSON必須、--no-progressでプログレスバーを抑止）。既定は有効。 5xx・応答タイムアウトは有限回の再試行後に警告として扱い、404等のリンク切れは失敗として扱う
cargo-fmt: cargo-fmt-args = ["fmt"]（常時書き込みモード。pyfltr規約によりformatterは--fixなしでも強制修正する）
cargo-clippy:
- cargo-clippy-args = ["clippy", "--all-targets"]（共通前半部）
- cargo-clippy-lint-args = ["--", "-D", "warnings"]（lintモードで末尾に付与）
- cargo-clippy-fix-args = ["--fix", "--allow-staged", "--allow-dirty", "--", "-D", "warnings"]（fixモードで末尾に付与）
cargo-check: cargo-check-args = ["check", "--all-targets"]
cargo-test: cargo-test-args = ["test"]
cargo-deny: cargo-deny-args = ["check"]
dotnet-format: dotnet-format-args = ["format"]（常時書き込みモード）
dotnet-build: dotnet-build-args = ["build", "--nologo"]
dotnet-test: dotnet-test-args = ["test", "--nologo"]

cargo系・dotnet系はそれぞれserial_group = "cargo" / serial_group = "dotnet"で自動的に直列化される（同一ワークスペース・solutionを操作する競合を避けるため）。利用者が--jobs=1などを指定する必要はない。 mise backendの既定値は、cargo系がrust、cargo-denyがaqua:EmbarkStudios/cargo-deny、dotnet系がdotnetである。 cargo-denyはmise registryから消失したため本家aquaレジストリ経由を既定とする。

{command}-pathを明示的に設定した場合はその値が優先され、bin-runnerによる自動解決は無効化される。

shfmtの2段階実行¶

shfmtはprettierと同様に2段階で実行する。

まずshfmt -l（チェックのみ）を実行する。

rc == 0 → succeeded（整形済み）
rc != 0 → 続けてshfmt -w（書き込み）を実行する

引数はshfmt-check-args / shfmt-write-argsで個別に上書きできる（既定はそれぞれ["-l"] / ["-w"]）。共通引数shfmt-argsは両ステップの先頭に付与される。

[tool.pyfltr]
shfmt = true
shfmt-args = ["-i", "2"]

taploの2段階実行¶

taploはshfmtと同様に2段階で実行する。

まずtaplo check（チェックのみ）を実行する。

rc == 0 → succeeded（整形済み）
rc != 0 → 続けてtaplo format（書き込み）を実行する

引数はtaplo-check-args / taplo-write-argsで個別に上書きできる（既定はそれぞれ["check"] / ["format"]）。共通引数taplo-argsは両ステップの先頭に付与される。

[tool.pyfltr]
taplo = true
taplo-args = ["--config", "taplo.toml"]

ec（editorconfig-checker）¶

ecは.editorconfig違反を検出するGo製のチェッカー。bin-runner経由で実行する。プロジェクト固有の除外設定は.editorconfig-checker.jsonで行う。設定キーはPascalCase、Excludeは正規表現の配列で指定する。

{
  "Verbose": false,
  "Disable": {
    "IndentSize": true
  },
  "Exclude": [
    "\\.min\\.(js|css)$",
    "^vendor/",
    "^docs/_build/"
  ]
}

設定キーの全一覧は editorconfig-checker公式ドキュメントを参照。

hadolint¶

hadolintはHaskell製のDockerfileリンター。bin-runner経由で実行する。既定の対象ファイルはDockerfile / Dockerfile.* / *.Dockerfile。対象パターンを変更したい場合はhadolint-targetsで上書きするかhadolint-extend-targetsで追加する。

[tool.pyfltr]
hadolint = true
# 対象パターンを追加したい場合
hadolint-extend-targets = ["*.dockerfile"]

gitleaks¶

gitleaksはGoバイナリのシークレット検出ツール。bin-runner経由で実行する。 pass-filenames = falseにより、ファイル一覧ではなくリポジトリ全体を対象としてgitleaks detectを実行する。

[tool.pyfltr]
gitleaks = true

lychee¶

lycheeはRust製のリンク切れチェッカー。bin-runner経由で実行する。 Markdown・HTML中の外部URL到達性を検証するため、ネットワーク到達失敗で判定結果が変動することがある。

[tool.pyfltr]
# 既定で有効。
lychee = true
# 同時接続数（既定: 4）。0以下でlychee既定値（128）へ委ねる
lychee-max-concurrency = 4
# 404等も含め全失敗を警告にしたい場合だけ指定する
# lychee-severity = "warning"
# 非公開リポジトリ等で特定URLが認証なしで404になる場合の除外例
lychee-extend-args = ["--exclude=github\\.com/owner/repo/actions"]
# 外部URLを検証せずローカルリンクのみ検査する例（CI環境などで利用）
# lychee-extend-args = ["--offline"]

既定対象は*.md・*.html。lychee-extend-targetsで対象を追加できる。

HTTP(S)リンクの5xxは初回に加えて最大3回再試行し、応答タイムアウトはlychee自身の再試行を使う。最後まで残った失敗がこれらだけなら、URLと原因を警告として表示し、pyfltrは正常終了する。追加設定は不要で、途中で復旧したリンクは成功として扱う。警告が残ったリンクは、次回のチェックまたはpyfltr run --commands=lycheeで再確認する。 404等のリンク切れが混在すれば失敗として扱う。結果のJSONを完全に分類できない場合と、ツール起動やpyfltr側の実行時間上限に関する異常も失敗のまま保持する。再試行と待機はlychee-timeout（省略時はcommand-timeout）の時間上限に含まれる。

lychee-max-concurrencyの既定値4はCI環境でgithub.com宛リンクのチェックが Network error: HTTP/2 protocol error. Server may not support HTTP/2 properlyで失敗する事象を緩和するための値。チェックの所要時間を優先する場合は大きな値、または0以下（lychee既定値の128）を指定する。lychee-args・lychee-extend-argsで --max-concurrencyを指定した場合は自動追加せず、指定値をそのまま使う。

colloquial-check¶

colloquial-checkはLLMが頻繁に出力する口語的な日本語表現を検出する内蔵linter。起動方法はpython -m pyfltr.colloquial。既定は無効（opt-in）とし、 colloquial-check-severity = "warning"が既定のため有効化してもCI/pre-commitを失敗させない。

[tool.pyfltr]
colloquial-check = true
# 辞書ファイル自身やテスト用サンプル文言など、誤検出を招くファイルを除外する例
colloquial-check-exclude = ["pyfltr/colloquial/words.txt"]
# 対象ファイル種別を絞り込む例（既定は全ファイル`*`）
colloquial-check-targets = "*.md"

起動方式の確認¶

ツールごとの実際の起動方式（runner種別・実行ファイルパス・最終コマンドライン）は pyfltr command-info <tool>で副作用無しに確認できる。 {command}-runner設定やbin-runner / js-runnerの効果が想定どおりかを点検する用途で使う。詳細はCLIコマンドを参照。