設定項目（ツール別）¶

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

pyfltrは対応ツールを実行方式の観点から4カテゴリに分けて扱う。カテゴリ委譲を採用する3カテゴリでは既定値が対応するカテゴリ委譲値になっており、直接実行カテゴリのみ既定値が"direct"（直接指定値）となる（共通の委譲先が無いため）。

python-runner経由（既定{command}-runner = "python-runner"）。対象はPython系ツール一式に加え、semgrep / sqlfluff / banditが該当する。 Python系ツール一式はmypy / pylint / pyright / ty / pytest / ruff-format / ruff-check / uv-sortを指す。グローバルpython-runner設定（"uv" / "uvx" / "direct"）へ委譲する。既定"uv"ではcwdにuv.lockがありuvバイナリが利用可能な場合にuv run --frozen <bin>でプロジェクトのvenv経由で起動する
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 / 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・依存の脆弱性監査ツール（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が自動で管理する。利用者側の追加設定は不要。

本ページではまず全カテゴリ共通の設定を示し、続いて各カテゴリ固有の設定を説明する。

対象ファイルパターンのカスタマイズ¶

各コマンドが処理する対象ファイルパターンを変更できる。

{command}-targetsでパターンを完全に上書きする。

[tool.pyfltr]
# shfmtの対象を *.bash のみに変更（既定の *.sh は対象外になる）
shfmt-targets = ["*.bash"]

{command}-extend-targetsで既存パターンに追加する。

[tool.pyfltr]
# shfmtの対象に *.sh.tmpl と dot_bashrc を追加（既定の *.sh も維持）
shfmt-extend-targets = ["*.sh.tmpl", "dot_bashrc"]
shellcheck-extend-targets = ["*.sh.tmpl", "dot_bashrc"]

両方を指定した場合、targetsで上書きした後にextend-targetsで追加する。

引数の追加¶

各コマンドの引数を変更したい場合、{command}-argsで既定値を完全に上書きするか、 {command}-extend-argsで既定値を保ったまま末尾へ引数を追加する。

[tool.pyfltr]
# 既定値を完全に上書きする（pyfltr既定の必須引数も含めて全て指定する必要がある）
lychee-args = ["--format", "json", "--no-progress", "--exclude=github\\.com/owner/repo/actions"]

# 既定値を保ったまま末尾へ引数を追加する
lychee-extend-args = ["--exclude=github\\.com/owner/repo/actions"]

{command}-extend-argsの対象は共通引数{command}-argsのみ。 {command}-lint-args・{command}-fix-args・{command}-check-args・{command}-write-args等のモード専用引数には対応しない。モード切替時の引数は既定値を尊重する設計のため。

pass-filenames設定¶

{command}-pass-filenames = falseを設定すると、コマンド実行時にファイル引数を渡さない。プロジェクト全体を一括チェックするツール（tscなど）で使用する。

ビルトインでは、プロジェクト全体を単位として動作する以下のツールがpass-filenames = falseに設定されている。

tsc
cargo-fmt / cargo-clippy / cargo-check / cargo-test / cargo-deny
dotnet-format / dotnet-build / dotnet-test

pre-commitは変更ファイル指定（--files <対象>）で起動する。各hook内部のtypes・types_or・files・excludeフィルタはファイル指定起動でも適用されるため、関係するhookのみ動作する。 pass_filenames: false属性のhook（gitleaks等）はpre-commit側でリポジトリ全体走査となる。

カスタムコマンドでも同様に設定可能。

[tool.pyfltr]
tsc = true
# tsc は既定で pass-filenames = false のため明示不要

[tool.pyfltr.custom-commands.commitlint]
type = "linter"
path = "commitlint"
args = ["--from=HEAD~1"]
pass-filenames = false

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

対象はmypy / pylint / pyright / ty / pytest / ruff-format / ruff-check / uv-sortのPython系ツールと、 semgrep / sqlfluff / 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だけでゲートを通過する。

semgrep¶

semgrepは多言語SAST。pyfltr本体依存（pyproject.tomlの[project].dependencies）に同梱されるため、 uvx pyfltr単発でも利用できる。ルールセット指定が必須のため既定で無効（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本体依存に同梱されるため、uvx pyfltr単発でも利用できる。 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は維持する。

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はディレクトリ指定時の再帰探索を行う。

直接実行ツール¶

対象はtypos・yamllint・pre-commit・依存の脆弱性監査ツール（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"

依存の脆弱性監査ツール（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", "--frozen", "--no-progress"]。--frozenで監査時にuv.lockを書き換えない
pnpm-audit-args・npm-audit-args・yarn-audit-argsはいずれも既定値["audit", "--json"]。 --jsonはpyfltrが脆弱性情報を構造化して抽出するために必須

uv auditはuv 0.10.8以降のサブコマンド。uv-audit利用時はuv 0.10.8以降が必要。

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で、グローバル/キャッシュから都度取得する挙動となる。

プロジェクトの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`	`pnpx`経由で起動する (既定)。`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。builtin パーサが compact 出力を想定している)
textlint-lint-args = ["--format", "compact"]

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

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

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に列挙する。既定では以下の3パッケージが含まれる。

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

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"]（lint / fix両モードで有効にするため共通argsに配置）
- 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", "--reporter=github"]（checkサブコマンドと機械可読出力を共通argsで常時適用）
- biome-fix-args = ["--write", "--unsafe"]（ruffの--unsafe-fixes採用方針に準拠）
- safe fixのみに戻したい場合はbiome-fix-args = ["--write"]に上書き
- 注: biome-argsの先頭からサブコマンド（check / lint / format）を外すとbiomeがhelp表示で失敗する。必ずサブコマンド名を残すこと
- 注: unsafe fix適用可能な診断はbiomeが::notice（info）として出力する。 pyfltrの出力（JSONL・github-annotations等）にもinfoとして反映する。 biome公式設計でinfoは終了コードに影響しないため、CIの失敗扱いにはならない。個別ルールを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で、miseによるバージョン管理付きの実行となる。 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・pinact等がGitHub APIを呼び出す際のレート制限（403）回避。
      GITHUB_TOKEN: ${{ github.token }}
    steps:
      - uses: actions/checkout@v6
      - uses: jdx/mise-action@v4
      - 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
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 = []
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でプログレスバーを抑止）。既定で有効。外部URL到達失敗による判定変動を抑えたい場合はlychee-severity = "warning"で警告扱いに切り替えられる
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
# 外部URL到達失敗を警告扱いに切り替える例
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で対象を追加できる。

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"

カスタムコマンド¶

[tool.pyfltr.custom-commands]で任意のツールを追加できる。

[tool.pyfltr.custom-commands.mytool]
type = "linter"
path = "mytool"
args = ["-r", "-f", "custom"]
targets = "*.py"
error-pattern = '(?P<file>[^:]+):(?P<line>\d+):(?P<col>\d+):\s*(?P<message>.+)'
config-files = [".mytoolrc", "pyproject.toml"]
fast = true

設定項目。

type（必須）: "formatter" / "linter" / "tester"
- formatterは直列実行、linter/testerは並列実行
path: 実行コマンド（省略時はコマンド名）
args: 追加引数（省略時は空）
extend-args: argsの末尾へ追加する引数（省略時は空）。 args既定値を保ったまま要素を足したい場合に使う
targets: 対象ファイルパターン（省略時は"*.py"）
error-pattern: エラーパース用正規表現（省略可）
- fileとlineとmessageの名前付きグループが必須
- colは任意
- 指定するとErrorsタブやエラー一覧に表示される
fast: fastサブコマンドに含めるか否か（省略時はfalse）
fix-args: fix段でargsの後ろへ追加する引数（省略時はfix段の対象外）
pass-filenames: ファイル引数をコマンドに渡すか否か（省略時はtrue）。プロジェクト全体を一括チェックするツールではfalseに設定する
config-files: このコマンドの設定ファイル候補のリスト（省略時は空）。globパターン可。有効化時にどれもプロジェクトルート直下に見つからないとpyfltrが警告を発行する（ツール自体は実行する）。 pre-commitなどの「設定ファイル無しでは機能しないツール」の設定不備を可視化する用途
severity: "error"（既定）または"warning"。詳細はseverityによる失敗の警告化を参照
hints: LLM向けの追加文言（文字列の配列、省略時は空）。詳細はhintsによるLLM向け補足を参照

ビルトインコマンド（mypy等）は自動的にエラーパースされる。カスタムコマンドに対しても--{name}-argsやenable/disableを使用できる。

pyfltr run / pyfltr ci のように--commandsを省略したサブコマンドでは、登録済みの有効なカスタムコマンドもビルトインと同様にデフォルトの実行対象に含まれる。特定のツールだけを動かしたい場合は--commands=svelte-checkのように明示指定する。

カスタムコマンドでの fix モード対応¶

autofix機能を持つツールをカスタムコマンドとして登録する場合は、fix-argsを定義しておくとrun/fastのfix段に含まれる。

[tool.pyfltr.custom-commands.my-linter]
type = "linter"
path = "my-linter"
args = ["--check"]
fix-args = ["--fix"]

fixモードではargsの後にfix-argsが追加され、my-linter --check --fix <files>として実行される。

severityによる失敗の警告化¶

{command}-severityを"warning"に設定すると、当該ツールの失敗をJSONL command.status="warning" で記録し、パイプライン全体のexit codeに影響させない扱いに切り替えられる。口語表現検出など「警告で十分」な用途で、エージェントを止めずに通知だけしたい場合に使う。カスタムコマンド・ビルトイン共通で利用できる。

[tool.pyfltr.custom-commands.colloquial]
type = "linter"
path = "uv"
args = ["run", "--script", "~/dotfiles/agent-toolkit/skills/writing-standards/scripts/check_colloquial.py"]
targets = ["*"]
severity = "warning"

許容値は"error"（既定）と"warning"の2値。 "warning"設定下ではcommands_summary.needs_action.warningに集計し、 summary.guidanceのfailure系文言は出力しない。

ツール起動自体に失敗するケース（resolution_failed / timeout_exceeded）はseverityの影響を受けない。ツール起動側の異常で警告扱いに馴染まないため、failed/resolution_failedのままとなる。

hintsによるLLM向け補足¶

{command}-hintsに文字列配列を指定すると、JSONL command.hints に user.<n> 連番キーで埋め込む。 LLMエージェントへ修正方針や参考文献を渡したいときに使う。配列要素は英語推奨（command.hints / summary.guidance と同じくLLM入力前提のため）。

[tool.pyfltr.custom-commands.colloquial]
type = "linter"
# ...
hints = [
    "Colloquial Japanese expressions detected. Replace with formal written-language equivalents.",
    "See ~/dotfiles/agent-toolkit/skills/writing-standards/SKILL.md for guidance.",
]

指摘1件以上のときに限り出力する（指摘0件の実行で固定的なhintを残してLLM入力のトークンを浪費しないため）。ビルトインコマンドにも同名キーで指定可能で、利用者ごとの運用ノウハウを永続化する用途に利用できる。

`~`展開¶

対応キーは以下。これらに~を含めると、subprocess引数組み立て直前に展開する。利用者ホーム配下に置いた個人ツールスクリプトをそのまま参照したい場合に使う。

{command}-path
{command}-args / {command}-extend-args / {command}-lint-args / {command}-fix-args
{command}-check-args / {command}-write-args
ruff-format-check-args

[tool.pyfltr.custom-commands.my-tool]
type = "linter"
path = "uv"
args = ["run", "--script", "~/dotfiles/scripts/my_tool.py"]

展開規則は2点。要素先頭が~または~userの場合はos.path.expanduserで展開する。要素内最初の=直後の~/~userも同様に展開する。そのため"--config=~/cfg.toml"形式と["--config", "~/cfg.toml"]の分割形式のどちらでも同じく展開される。

config-files / targets / {command}-extend-targets等のglobパターンには展開を適用しない（glob内チルダの意図しない展開を防ぐため）。

起動方式の確認¶

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