pyfltr 2.2.2__tar.gz → 2.3.0__tar.gz

{pyfltr-2.2.2 → pyfltr-2.3.0}/CLAUDE.md

@@ -15,4 +15,5 @@
 
 - `uv run mkdocs build --strict`でリンク・nav整合性を検証（ただし日本語アンカーリンク`#見出し日本語`はMkDocs TOCで解決できずINFO通知のみで`--strict`でも検知されないため手動確認要）
 - `docs/guide/index.md`の対応ツール一覧と`mkdocs.yml`内llmstxt `markdown_description`の「対応ツール」節は人手同期（SSOT化しない運用）
+- `mkdocs.yml`内llmstxt `markdown_description`にはLLMが利用する際に有用な情報のみ記載する（`run-for-agent`サブコマンド、主要オプションなど）。LLMにとって不要な情報はdocs側をSSOTとし、多重管理を避ける
 - ドキュメント構成変更時は`docs/development/development.md`の「READMEとdocsの役割分担」節を先に参照

{pyfltr-2.2.2 → pyfltr-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyfltr
-Version: 2.2.2
+Version: 2.3.0
 Summary: Python Formatters, Linters, and Testers Runner.
 Project-URL: Homepage, https://github.com/ak110/pyfltr
 Author-email: "aki." <mark@aur.ll.to>

{pyfltr-2.2.2 → pyfltr-2.3.0}/docs/guide/usage.md

@@ -70,6 +70,30 @@ pyfltr generate-config
 設定ファイルの雛形を標準出力に書き出す。`[tool.pyfltr]`セクションに貼り付けて利用する。
 このサブコマンドは他のオプションやターゲット指定を受け付けず、設定出力だけを行う。
 
+### サブコマンド: generate-shell-completion
+
+```shell
+pyfltr generate-shell-completion bash
+pyfltr generate-shell-completion powershell
+```
+
+シェル補完スクリプトを標準出力に書き出す。
+引数にシェル種別（`bash`または`powershell`）を指定する。
+
+bashでの設定例:
+
+```shell
+eval "$(pyfltr generate-shell-completion bash)"
+```
+
+PowerShellでの設定例:
+
+```powershell
+pyfltr generate-shell-completion powershell | Out-String | Invoke-Expression
+```
+
+永続化する場合はプロファイルに上記を追記する。
+
 ### `[files and/or directories ...]`
 
 対象を指定しなかった場合は、カレントディレクトリ(`.`)を指定した場合と同じ扱いとなる。
@@ -176,14 +200,16 @@ CLIオプション`--output-format`が指定されている場合は環境変数
 
 ### jsonlスキーマ
 
-出力は以下4種別のレコードからなる。`kind`フィールドでレコード種別を判別する。
+出力は以下5種別のレコードからなる。`kind`フィールドでレコード種別を判別する。
 
+- `header`: 先頭1行。実行環境情報（`version` / `python` / `platform` / `cwd` / `commands` / `files`）
 - `warning`: pyfltrが検出した設定・実行時の警告（`source`で発生元を識別）
 - `diagnostic`: 個々の診断（`error_parser`対応ツールの抽出結果）
 - `tool`: 1ツール1レコードの実行メタ情報
 - `summary`: 最終1行、全体集計
 
 ```json
+{"kind":"header","version":"1.25.0","python":"3.12.0 ...","executable":"/usr/bin/python3","platform":"linux","cwd":"/work","commands":["mypy","black"],"files":12}
 {"kind":"warning","source":"config","msg":"pre-commit が有効化されていますが、設定ファイルが見つかりません: .pre-commit-config.yaml"}
 {"kind":"diagnostic","tool":"mypy","file":"src/a.py","line":42,"col":5,"msg":"Incompatible return value type"}
 {"kind":"tool","tool":"mypy","type":"linter","status":"failed","files":12,"elapsed":0.8,"diagnostics":1,"rc":1}
@@ -191,9 +217,9 @@ CLIオプション`--output-format`が指定されている場合は環境変数
 {"kind":"summary","total":2,"succeeded":0,"formatted":1,"failed":1,"skipped":0,"diagnostics":1,"exit":1}
 ```
 
-stdoutモード（`--output-file`未指定）では、各ツールの完了時にdiagnostic行+tool行を随時書き出す。
+stdoutモード（`--output-file`未指定）では、先頭にheader行を出力し、各ツールの完了時にdiagnostic行+tool行を随時書き出す。
 ツール間の出力順は完了順となり、最後にwarning行+summary行が続く。
-ファイル出力時（`--output-file`指定）では、`pyproject.toml`の定義順にツール単位でグルーピングし、先頭にwarning行、末尾にsummary行を配置する。
+ファイル出力時（`--output-file`指定）では、先頭にheader行、続いて`pyproject.toml`の定義順にツール単位でグルーピングし、先頭にwarning行、末尾にsummary行を配置する。
 
 `warning`レコードの`source`は`config`（設定ファイル不在など）/`tool-resolve`（ツール解決失敗）/`file-resolver`（対象ファイル選定時）/`git`（`git check-ignore`失敗）のいずれか。
 

{pyfltr-2.2.2 → pyfltr-2.3.0}/mkdocs.yml

@@ -39,7 +39,6 @@ plugins:
         - `pyfltr run`: 全チェック。fix段→formatter段→linter/tester段の順で、fix-args定義済みlinterの自動修正→formatter→残りの検査を実行する（ローカル向け）
         - `pyfltr fast`: 軽量チェック。`run`と同じ3段構成だが、mypy/pylint/pytest等の重いツールを除外（pre-commit向け）
         - `pyfltr run-for-agent`: `pyfltr run --output-format=jsonl`のエイリアス。JSONL出力を既定にする（LLMエージェント向け）
-        - `pyfltr generate-config`: pyproject.toml用の設定雛形を出力
 
         `--no-fix`で`run`/`fast`/`run-for-agent`のfix段を抑止できる。`ci`は副作用回避のため元々fix段を持たない。
 
@@ -68,16 +67,15 @@ plugins:
 
         ## LLMエージェント向け出力（`--output-format=jsonl`）
 
-        `--output-format=jsonl`でJSON Lines形式の構造化出力が得られる。レコードは4種類。
+        `--output-format=jsonl`でJSON Lines形式の構造化出力が得られる。レコードは5種類。
 
+        - `header`: 先頭1行。実行環境情報（`version` / `python` / `platform` / `cwd` / `commands` / `files`）
         - `warning`: pyfltr が検出した設定・実行時の警告（`source` で発生元を識別）
         - `diagnostic`: 1診断1行（`tool` / `file` / `line` / `col` / `rule` / `severity` / `msg`）
         - `tool`: ツールごとの実行結果サマリ（`status` / `elapsed` / `diagnostics` / `rc`）
         - `summary`: 最終1行の全体集計（`succeeded` / `formatted` / `failed` / `skipped` / `diagnostics` / `exit`）
 
-        出力順は`warning`→`diagnostic`（file/line/col/command順）→`tool`（`pyproject.toml`定義順）→`summary`（1行）で固定。
-
-        `--output-file`未指定時はstdoutへJSONLのみを書き、進捗ログやTUIは無音化される。指定時はファイルへJSONLを書き、stdoutには従来どおりのテキスト出力を並行出力する（ローカル実行で進捗を追える）。
+        stdoutモード（`--output-file`未指定）の出力順は`header`→ツール完了順に`diagnostic`+`tool`→`warning`→`summary`。stdoutへJSONLのみを書き、進捗ログやTUIは無音化される。`--output-file`指定時はファイルへJSONLを書き、stdoutには従来どおりのテキスト出力を並行出力する（ローカル実行で進捗を追える）。
 
         ```shell
         pyfltr run-for-agent

{pyfltr-2.2.2 → pyfltr-2.3.0}/pyfltr/cli.py

@@ -140,6 +140,8 @@ def render_results(
     output_format: str = "text",
     output_file: pathlib.Path | None = None,
     exit_code: int = 0,
+    commands: list[str] | None = None,
+    files: int | None = None,
     warnings: list[dict[str, typing.Any]] | None = None,
 ) -> None:
     """実行結果を `成功コマンド → 失敗コマンド → summary` の順でまとめて出力する。
@@ -160,7 +162,9 @@ def render_results(
     warnings = warnings or []
 
     if output_format == "jsonl":
-        pyfltr.llm_output.write_jsonl(ordered, config, exit_code=exit_code, destination=output_file, warnings=warnings)
+        pyfltr.llm_output.write_jsonl(
+            ordered, config, exit_code=exit_code, destination=output_file, commands=commands, files=files, warnings=warnings
+        )
         if output_file is None:
             return
 

{pyfltr-2.2.2 → pyfltr-2.3.0}/pyfltr/llm_output.py

@@ -1,11 +1,13 @@
 """LLM 向け JSON Lines 出力。
 
 `--output-format=jsonl` で呼ばれ、CommandResult 群を LLM / エージェントが
-読みやすいフラットな JSON Lines 形式 (diagnostic / tool / summary の 3 種別) に
+読みやすいフラットな JSON Lines 形式 (header / diagnostic / tool / summary の 4 種別) に
 変換して書き出す。
 """
 
+import importlib.metadata
 import json
+import os
 import pathlib
 import sys
 import threading
@@ -47,14 +49,17 @@ def build_lines(
     config: pyfltr.config.Config,
     *,
     exit_code: int,
+    commands: list[str] | None = None,
+    files: int | None = None,
     warnings: list[dict[str, typing.Any]] | None = None,
 ) -> list[str]:
     """CommandResult群からJSONL各行を生成する。
 
     出力順:
-        1. ``warnings``が非空ならkind="warning"行
-        2. ツール単位でdiagnostic行+tool行（``config.command_names``の定義順）
-        3. summary行1行
+        1. ``commands``と``files``が指定されていればkind="header"行
+        2. ``warnings``が非空ならkind="warning"行
+        3. ツール単位でdiagnostic行+tool行（``config.command_names``の定義順）
+        4. summary行1行
 
     resultsは順序を問わない。内部で``config.command_names``順にソートする。
     ``warnings``は``pyfltr.warnings_.collected_warnings()``の返り値を想定する。
@@ -63,6 +68,9 @@ def build_lines(
 
     lines: list[str] = []
 
+    if commands is not None and files is not None:
+        lines.append(_dump(_build_header_record(commands, files)))
+
     for warning in warnings or []:
         lines.append(_dump(_build_warning_record(warning)))
 
@@ -86,6 +94,8 @@ def write_jsonl(
     *,
     exit_code: int,
     destination: pathlib.Path | None,
+    commands: list[str] | None = None,
+    files: int | None = None,
     warnings: list[dict[str, typing.Any]] | None = None,
 ) -> None:
     """JSONL を stdout もしくは指定ファイルに書き出す。
@@ -94,7 +104,7 @@ def write_jsonl(
     親ディレクトリを自動作成し、atomic write せず単純に上書きする
     (LLM 用途の使い捨てのため)。
     """
-    lines = build_lines(results, config, exit_code=exit_code, warnings=warnings)
+    lines = build_lines(results, config, exit_code=exit_code, commands=commands, files=files, warnings=warnings)
     if destination is None:
         for line in lines:
             sys.stdout.write(line)
@@ -108,6 +118,17 @@ def write_jsonl(
             f.write("\n")
 
 
+def write_jsonl_header(commands: list[str], files: int) -> None:
+    """header行をstdoutに書き出す（ストリーミングモード用）。
+
+    パイプライン開始直後、diagnostic行より前に1回だけ呼ぶ。
+    """
+    with _write_lock:
+        sys.stdout.write(_dump(_build_header_record(commands, files)))
+        sys.stdout.write("\n")
+        sys.stdout.flush()
+
+
 def write_jsonl_streaming(
     result: pyfltr.command.CommandResult,
     config: pyfltr.config.Config,
@@ -149,6 +170,20 @@ def _dump(record: dict[str, typing.Any]) -> str:
     return json.dumps(record, ensure_ascii=False, separators=(",", ":"))
 
 
+def _build_header_record(commands: list[str], files: int) -> dict[str, typing.Any]:
+    """実行環境の基本情報を header レコード dict として返す。"""
+    return {
+        "kind": "header",
+        "version": importlib.metadata.version("pyfltr"),
+        "python": sys.version,
+        "executable": sys.executable,
+        "platform": sys.platform,
+        "cwd": os.getcwd(),
+        "commands": commands,
+        "files": files,
+    }
+
+
 def _build_warning_record(entry: dict[str, typing.Any]) -> dict[str, typing.Any]:
     """警告 dict を warning レコード dict に変換する。"""
     return {

{pyfltr-2.2.2 → pyfltr-2.3.0}/pyfltr/main.py

@@ -14,6 +14,7 @@ import pyfltr.cli
 import pyfltr.command
 import pyfltr.config
 import pyfltr.llm_output
+import pyfltr.shell_completion
 import pyfltr.ui
 import pyfltr.warnings_
 
@@ -41,6 +42,8 @@ def build_parser() -> argparse.ArgumentParser:
             "  fast             高速ツールのみ実行 (--commands=fast 相当)。\n"
             "  run-for-agent    LLM エージェント向け (JSONL 出力を既定化)。\n"
             "  generate-config  pyproject.toml 用の設定雛形を出力する。\n"
+            "  generate-shell-completion <shell>\n"
+            "                   シェル補完スクリプトを出力する (bash / powershell)。\n"
             "\n"
             "ドキュメント: https://ak110.github.io/pyfltr/\n"
             "llms.txt: https://ak110.github.io/pyfltr/llms.txt"
@@ -151,12 +154,16 @@ _SUBCOMMANDS: frozenset[str] = frozenset(
         "fast",
         "run-for-agent",
         "generate-config",
+        "generate-shell-completion",
         # 以下は廃止済み
         "fix",
         "dirty",
     }
 )
 
+# 廃止済みサブコマンド
+_DEPRECATED_SUBCOMMANDS: frozenset[str] = frozenset({"fix", "dirty"})
+
 
 def _parse_subcommand(sys_args: typing.Sequence[str]) -> tuple[str, list[str]]:
     """第一引数からサブコマンドを判定し、(subcommand, remaining_args)を返す。
@@ -190,7 +197,7 @@ def run(sys_args: typing.Sequence[str] | None = None) -> int:
     subcommand, remaining_args = _parse_subcommand(sys_args)
 
     # 廃止済みサブコマンド
-    if subcommand in ("fix", "dirty"):
+    if subcommand in _DEPRECATED_SUBCOMMANDS:
         logger.error(f"{subcommand} サブコマンドは廃止されました。")
         return 1
 
@@ -200,6 +207,17 @@ def run(sys_args: typing.Sequence[str] | None = None) -> int:
         logger.info(pyfltr.config.generate_config_text())
         return 0
 
+    # generate-shell-completionサブコマンド: 補完スクリプトをstdoutに出力する
+    if subcommand == "generate-shell-completion":
+        if not remaining_args or remaining_args[0] not in pyfltr.shell_completion.SUPPORTED_SHELLS:
+            supported = ", ".join(pyfltr.shell_completion.SUPPORTED_SHELLS)
+            logger.error(f"シェルを指定してください: pyfltr generate-shell-completion <{supported}>")
+            return 1
+        active_subcommands = _SUBCOMMANDS - _DEPRECATED_SUBCOMMANDS
+        script = pyfltr.shell_completion.generate(remaining_args[0], build_parser(), active_subcommands)
+        print(script, end="")
+        return 0
+
     effective_args = _build_effective_args(subcommand, remaining_args)
 
     parser = build_parser()
@@ -407,6 +425,9 @@ def run_pipeline(
     # JSONL stdoutモード: ツール完了時に随時JSONL行を書き出す
     jsonl_stdout = (args.output_format == "jsonl") and (args.output_file is None)
 
+    if jsonl_stdout:
+        pyfltr.llm_output.write_jsonl_header(commands=commands, files=len(all_files))
+
     # run
     include_fix_stage = bool(getattr(args, "include_fix_stage", False))
     if use_ui:
@@ -448,6 +469,8 @@ def run_pipeline(
             output_format=args.output_format or "text",
             output_file=args.output_file,
             exit_code=returncode,
+            commands=commands,
+            files=len(all_files),
             warnings=pyfltr.warnings_.collected_warnings(),
         )
     return returncode

pyfltr-2.3.0/pyfltr/shell_completion.py

@@ -0,0 +1,214 @@
+"""シェル補完スクリプトの生成。"""
+
+import argparse
+
+import pyfltr.config
+
+SUPPORTED_SHELLS: tuple[str, ...] = ("bash", "powershell")
+"""対応シェル。"""
+
+
+def generate(
+    shell: str,
+    parser: argparse.ArgumentParser,
+    subcommands: frozenset[str],
+) -> str:
+    """シェル種別に応じた補完スクリプトを返す。"""
+    options, output_format_choices, commands_choices = _collect_completions(parser)
+    subcommand_list = sorted(subcommands)
+    if shell == "bash":
+        return _generate_bash(options, output_format_choices, commands_choices, subcommand_list)
+    if shell == "powershell":
+        return _generate_powershell(options, output_format_choices, commands_choices, subcommand_list)
+    raise ValueError(f"未対応のシェル: {shell!r}")
+
+
+def _collect_completions(
+    parser: argparse.ArgumentParser,
+) -> tuple[list[str], list[str], list[str]]:
+    """パーサーからオプション名・choices・コマンド名を収集する。
+
+    戻り値: (options, output_format_choices, commands_choices)
+    """
+    options: list[str] = []
+    output_format_choices: list[str] = []
+    for action in parser._actions:  # noqa: SLF001  # pylint: disable=protected-access
+        for opt in action.option_strings:
+            options.append(opt)
+        if "--output-format" in action.option_strings and action.choices:
+            output_format_choices = list(action.choices)
+
+    # --commands の補完候補: ビルトインコマンド名 + 静的エイリアスキー
+    commands_choices = list(pyfltr.config.BUILTIN_COMMAND_NAMES)
+    aliases = pyfltr.config.DEFAULT_CONFIG.get("aliases", {})
+    assert isinstance(aliases, dict)
+    for alias_name in aliases:
+        if alias_name not in commands_choices:
+            commands_choices.append(alias_name)
+    commands_choices.sort()
+
+    return sorted(options), sorted(output_format_choices), commands_choices
+
+
+def _generate_bash(
+    options: list[str],
+    output_format_choices: list[str],
+    commands_choices: list[str],
+    subcommands: list[str],
+) -> str:
+    """bash用補完スクリプトを生成する。"""
+    opts = " ".join(options)
+    subs = " ".join(subcommands)
+    shells = " ".join(SUPPORTED_SHELLS)
+    fmt_choices = " ".join(output_format_choices)
+    cmd_choices = " ".join(commands_choices)
+
+    return f'''\
+_pyfltr_completions() {{
+    local cur prev words cword
+    _init_completion || return
+
+    local subcommands="{subs}"
+    local options="{opts}"
+    local shells="{shells}"
+    local output_formats="{fmt_choices}"
+    local commands="{cmd_choices}"
+
+    # generate-shell-completionの第2引数: シェル名を補完
+    if [[ ${{cword}} -ge 2 && "${{words[1]}}" == "generate-shell-completion" ]]; then
+        COMPREPLY=( $(compgen -W "${{shells}}" -- "${{cur}}") )
+        return
+    fi
+
+    # --output-format / --output-format= の補完
+    if [[ "${{prev}}" == "--output-format" ]]; then
+        COMPREPLY=( $(compgen -W "${{output_formats}}" -- "${{cur}}") )
+        return
+    fi
+    if [[ "${{cur}}" == --output-format=* ]]; then
+        local prefix="${{cur%%=*}}="
+        local typed="${{cur#*=}}"
+        COMPREPLY=( $(compgen -W "${{output_formats}}" -- "${{typed}}") )
+        COMPREPLY=( "${{COMPREPLY[@]/#/${{prefix}}}}" )
+        return
+    fi
+
+    # --commands / --commands= の補完
+    if [[ "${{prev}}" == "--commands" ]]; then
+        COMPREPLY=( $(compgen -W "${{commands}}" -- "${{cur}}") )
+        return
+    fi
+    if [[ "${{cur}}" == --commands=* ]]; then
+        local prefix="${{cur%%=*}}="
+        local typed="${{cur#*=}}"
+        COMPREPLY=( $(compgen -W "${{commands}}" -- "${{typed}}") )
+        COMPREPLY=( "${{COMPREPLY[@]/#/${{prefix}}}}" )
+        return
+    fi
+
+    # 第1引数: サブコマンド + オプション
+    if [[ ${{cword}} -eq 1 ]]; then
+        COMPREPLY=( $(compgen -W "${{subcommands}} ${{options}}" -- "${{cur}}") )
+        return
+    fi
+
+    # オプション開始
+    if [[ "${{cur}}" == -* ]]; then
+        COMPREPLY=( $(compgen -W "${{options}}" -- "${{cur}}") )
+        return
+    fi
+
+    # ファイル/ディレクトリ補完
+    _filedir
+}}
+
+complete -o default -F _pyfltr_completions pyfltr
+'''
+
+
+def _generate_powershell(
+    options: list[str],
+    output_format_choices: list[str],
+    commands_choices: list[str],
+    subcommands: list[str],
+) -> str:
+    """PowerShell用補完スクリプトを生成する。"""
+    # PowerShellの配列リテラルとして出力
+    opts_ps = ", ".join(f"'{o}'" for o in options)
+    subs_ps = ", ".join(f"'{s}'" for s in subcommands)
+    shells_ps = ", ".join(f"'{s}'" for s in SUPPORTED_SHELLS)
+    fmt_ps = ", ".join(f"'{f}'" for f in output_format_choices)
+    cmd_ps = ", ".join(f"'{c}'" for c in commands_choices)
+
+    return f"""\
+Register-ArgumentCompleter -Native -CommandName pyfltr -ScriptBlock {{
+    param($wordToComplete, $commandAst, $cursorPosition)
+
+    $subcommands = @({subs_ps})
+    $options = @({opts_ps})
+    $shells = @({shells_ps})
+    $outputFormats = @({fmt_ps})
+    $commands = @({cmd_ps})
+
+    $tokens = $commandAst.ToString().Substring(0, $cursorPosition).Split(' ', [System.StringSplitOptions]::RemoveEmptyEntries)
+    $tokenCount = $tokens.Count
+
+    # generate-shell-completionの第2引数: シェル名を補完
+    if ($tokenCount -ge 2 -and $tokens[1] -eq 'generate-shell-completion') {{
+        $shells | Where-Object {{ $_ -like "$wordToComplete*" }} | ForEach-Object {{
+            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+        }}
+        return
+    }}
+
+    # --output-format の値補完
+    if ($tokenCount -ge 2 -and $tokens[-1] -eq '--output-format') {{
+        $outputFormats | Where-Object {{ $_ -like "$wordToComplete*" }} | ForEach-Object {{
+            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+        }}
+        return
+    }}
+    if ($wordToComplete -like '--output-format=*') {{
+        $typed = $wordToComplete.Substring('--output-format='.Length)
+        $outputFormats | Where-Object {{ $_ -like "$typed*" }} | ForEach-Object {{
+            $val = "--output-format=$_"
+            [System.Management.Automation.CompletionResult]::new($val, $val, 'ParameterValue', $_)
+        }}
+        return
+    }}
+
+    # --commands の値補完
+    if ($tokenCount -ge 2 -and $tokens[-1] -eq '--commands') {{
+        $commands | Where-Object {{ $_ -like "$wordToComplete*" }} | ForEach-Object {{
+            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+        }}
+        return
+    }}
+    if ($wordToComplete -like '--commands=*') {{
+        $typed = $wordToComplete.Substring('--commands='.Length)
+        $commands | Where-Object {{ $_ -like "$typed*" }} | ForEach-Object {{
+            $val = "--commands=$_"
+            [System.Management.Automation.CompletionResult]::new($val, $val, 'ParameterValue', $_)
+        }}
+        return
+    }}
+
+    # 第1引数: サブコマンド + オプション
+    if ($tokenCount -le 1 -or ($tokenCount -eq 2 -and $wordToComplete -ne '')) {{
+        $all = $subcommands + $options
+        $all | Where-Object {{ $_ -like "$wordToComplete*" }} | ForEach-Object {{
+            $type = if ($_ -like '-*') {{ 'ParameterName' }} else {{ 'ParameterValue' }}
+            [System.Management.Automation.CompletionResult]::new($_, $_, $type, $_)
+        }}
+        return
+    }}
+
+    # オプション開始
+    if ($wordToComplete -like '-*') {{
+        $options | Where-Object {{ $_ -like "$wordToComplete*" }} | ForEach-Object {{
+            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterName', $_)
+        }}
+        return
+    }}
+}}
+"""

{pyfltr-2.2.2 → pyfltr-2.3.0}/tests/output_format_test.py

@@ -33,11 +33,11 @@ def test_build_lines_supported_tool_diagnostics(default_config):
         _make_error("mypy", "src/a.py", 20, "missing return"),
     ]
     result = _make_result("mypy", returncode=1, errors=errors)
-    lines = pyfltr.llm_output.build_lines([result], default_config, exit_code=1)
+    lines = pyfltr.llm_output.build_lines([result], default_config, exit_code=1, commands=["mypy"], files=5)
     parsed = [json.loads(line) for line in lines]
 
-    assert [r["kind"] for r in parsed] == ["diagnostic", "diagnostic", "tool", "summary"]
-    assert parsed[0] == {
+    assert [r["kind"] for r in parsed] == ["header", "diagnostic", "diagnostic", "tool", "summary"]
+    assert parsed[1] == {
         "kind": "diagnostic",
         "tool": "mypy",
         "file": "src/a.py",
@@ -45,17 +45,17 @@ def test_build_lines_supported_tool_diagnostics(default_config):
         "col": 4,
         "msg": "bad type",
     }
-    assert parsed[1] == {
+    assert parsed[2] == {
         "kind": "diagnostic",
         "tool": "mypy",
         "file": "src/a.py",
         "line": 20,
         "msg": "missing return",
     }
-    assert parsed[2]["diagnostics"] == 2
-    assert parsed[2]["status"] == "failed"
     assert parsed[3]["diagnostics"] == 2
-    assert parsed[3]["failed"] == 1
+    assert parsed[3]["status"] == "failed"
+    assert parsed[4]["diagnostics"] == 2
+    assert parsed[4]["failed"] == 1
 
 
 def test_build_lines_warnings_prepended(default_config):
@@ -65,14 +65,15 @@ def test_build_lines_warnings_prepended(default_config):
         {"source": "config", "message": "pre-commit 設定ファイル不在"},
         {"source": "git", "message": "git が見つからない"},
     ]
-    lines = pyfltr.llm_output.build_lines([result], default_config, exit_code=0, warnings=warnings)
+    lines = pyfltr.llm_output.build_lines([result], default_config, exit_code=0, commands=["black"], files=1, warnings=warnings)
     parsed = [json.loads(line) for line in lines]
 
-    assert [r["kind"] for r in parsed[:2]] == ["warning", "warning"]
-    assert parsed[0] == {"kind": "warning", "source": "config", "msg": "pre-commit 設定ファイル不在"}
-    assert parsed[1] == {"kind": "warning", "source": "git", "msg": "git が見つからない"}
+    assert parsed[0]["kind"] == "header"
+    assert [r["kind"] for r in parsed[1:3]] == ["warning", "warning"]
+    assert parsed[1] == {"kind": "warning", "source": "config", "msg": "pre-commit 設定ファイル不在"}
+    assert parsed[2] == {"kind": "warning", "source": "git", "msg": "git が見つからない"}
     # warnings の後に tool レコード、最後に summary が並ぶ
-    assert [r["kind"] for r in parsed[2:]] == ["tool", "summary"]
+    assert [r["kind"] for r in parsed[3:]] == ["tool", "summary"]
 
 
 def test_build_lines_no_warnings_when_omitted(default_config):
@@ -84,7 +85,7 @@ def test_build_lines_no_warnings_when_omitted(default_config):
 
 
 def test_build_lines_unsupported_tool_only(default_config):
-    """error_parser 非対応ツール (black) は tool レコードのみ。"""
+    """error_parser 非対応ツール (black) は tool レコードのみ（header省略時）。"""
     result = _make_result("black", returncode=1, command_type="formatter", has_error=False)
     lines = pyfltr.llm_output.build_lines([result], default_config, exit_code=1)
     parsed = [json.loads(line) for line in lines]
@@ -115,11 +116,18 @@ def test_build_lines_mixed_order(default_config):
     black_result = _make_result("black", returncode=0, command_type="formatter")
 
     # config.command_names 順では black → mypy → pylint
-    lines = pyfltr.llm_output.build_lines([mypy_result, pylint_result, black_result], default_config, exit_code=1)
+    lines = pyfltr.llm_output.build_lines(
+        [mypy_result, pylint_result, black_result],
+        default_config,
+        exit_code=1,
+        commands=["black", "mypy", "pylint"],
+        files=10,
+    )
     parsed = [json.loads(line) for line in lines]
 
-    # ツール単位のグルーピング: black(tool) → mypy(diagnostic, diagnostic, tool) → pylint(diagnostic, tool) → summary
+    # header → ツール単位のグルーピング: black(tool) → mypy(diagnostic, diagnostic, tool) → pylint(diagnostic, tool) → summary
     assert [r["kind"] for r in parsed] == [
+        "header",
         "tool",  # black
         "diagnostic",
         "diagnostic",
@@ -253,7 +261,7 @@ def test_calculate_returncode_matches_summary_exit(default_config):
         _make_result("black", returncode=0, command_type="formatter"),
     ]
     exit_code = pyfltr.main.calculate_returncode(results, exit_zero_even_if_formatted=False)
-    lines = pyfltr.llm_output.build_lines(results, default_config, exit_code=exit_code)
+    lines = pyfltr.llm_output.build_lines(results, default_config, exit_code=exit_code, commands=["mypy", "black"], files=3)
     summary = json.loads(lines[-1])
     assert summary["exit"] == exit_code == 1
 
@@ -275,6 +283,9 @@ def test_run_cli_jsonl_stdout_suppresses_text(mocker, capsys):
     assert "summary" not in captured.out or '"kind":"summary"' in captured.out
     lines = [line for line in captured.out.splitlines() if line.strip()]
     assert lines, "JSONL が 1 行も出ていない"
+    first = json.loads(lines[0])
+    assert first["kind"] == "header"
+    assert "mypy" in first["commands"]
     last = json.loads(lines[-1])
     assert last["kind"] == "summary"
     assert last["exit"] == 0
@@ -467,3 +478,51 @@ def test_write_jsonl_footer_no_warnings(capsys):
     assert len(parsed) == 1
     assert parsed[0]["kind"] == "summary"
     assert parsed[0]["succeeded"] == 1
+
+
+# ---------------------------------------------------------------------------
+# header レコードのユニットテスト
+# ---------------------------------------------------------------------------
+
+
+def test_build_header_record_fields():
+    """_build_header_record が必要なフィールドをすべて含むこと。"""
+    record = pyfltr.llm_output._build_header_record(["ruff-format", "mypy"], 42)
+    assert record["kind"] == "header"
+    assert record["commands"] == ["ruff-format", "mypy"]
+    assert record["files"] == 42
+    assert "version" in record
+    assert "python" in record
+    assert "executable" in record
+    assert "platform" in record
+    assert "cwd" in record
+
+
+def test_build_lines_header_first(default_config):
+    """commands/filesを指定するとheader行が先頭に出力されること。"""
+    result = _make_result("mypy", returncode=0)
+    lines = pyfltr.llm_output.build_lines([result], default_config, exit_code=0, commands=["mypy"], files=10)
+    parsed = [json.loads(line) for line in lines]
+    assert parsed[0]["kind"] == "header"
+    assert parsed[0]["commands"] == ["mypy"]
+    assert parsed[0]["files"] == 10
+    assert parsed[-1]["kind"] == "summary"
+
+
+def test_build_lines_no_header_when_omitted(default_config):
+    """commands/filesを省略するとheader行は出力されないこと。"""
+    result = _make_result("mypy", returncode=0)
+    lines = pyfltr.llm_output.build_lines([result], default_config, exit_code=0)
+    parsed = [json.loads(line) for line in lines]
+    assert all(r["kind"] != "header" for r in parsed)
+
+
+def test_write_jsonl_header_stdout(capsys):
+    """write_jsonl_headerがstdoutにheader行を書き出すこと。"""
+    pyfltr.llm_output.write_jsonl_header(commands=["ruff-format", "mypy"], files=5)
+    captured = capsys.readouterr()
+    parsed = [json.loads(line) for line in captured.out.splitlines()]
+    assert len(parsed) == 1
+    assert parsed[0]["kind"] == "header"
+    assert parsed[0]["commands"] == ["ruff-format", "mypy"]
+    assert parsed[0]["files"] == 5

pyfltr-2.3.0/tests/shell_completion_test.py

@@ -0,0 +1,111 @@
+# pylint: disable=missing-module-docstring
+# pylint: disable=missing-function-docstring
+# pylint: disable=protected-access
+
+import pyfltr.config
+import pyfltr.main
+import pyfltr.shell_completion
+
+
+class TestCollectCompletions:
+    """補完データ収集のテスト。"""
+
+    def test_options_contain_verbose(self):
+        parser = pyfltr.main.build_parser()
+        options, _, _ = pyfltr.shell_completion._collect_completions(parser)
+        assert "--verbose" in options
+        assert "-v" in options
+
+    def test_options_contain_output_format(self):
+        parser = pyfltr.main.build_parser()
+        options, _, _ = pyfltr.shell_completion._collect_completions(parser)
+        assert "--output-format" in options
+
+    def test_output_format_choices(self):
+        parser = pyfltr.main.build_parser()
+        _, output_format_choices, _ = pyfltr.shell_completion._collect_completions(parser)
+        assert "text" in output_format_choices
+        assert "jsonl" in output_format_choices
+
+    def test_commands_choices_contain_builtin_and_aliases(self):
+        parser = pyfltr.main.build_parser()
+        _, _, commands_choices = pyfltr.shell_completion._collect_completions(parser)
+        # ビルトインコマンド
+        for name in pyfltr.config.BUILTIN_COMMAND_NAMES:
+            assert name in commands_choices
+        # 静的エイリアス
+        for alias in pyfltr.config.DEFAULT_CONFIG["aliases"]:
+            assert alias in commands_choices
+
+
+class TestGenerateBash:
+    """bash補完スクリプト生成のテスト。"""
+
+    def test_contains_function_and_complete(self):
+        parser = pyfltr.main.build_parser()
+        subcommands = frozenset({"ci", "run", "fast", "generate-shell-completion"})
+        script = pyfltr.shell_completion.generate("bash", parser, subcommands)
+        assert "_pyfltr_completions()" in script
+        assert "complete -o default -F _pyfltr_completions pyfltr" in script
+
+    def test_contains_subcommands(self):
+        parser = pyfltr.main.build_parser()
+        subcommands = frozenset({"ci", "run", "generate-shell-completion"})
+        script = pyfltr.shell_completion.generate("bash", parser, subcommands)
+        assert "ci" in script
+        assert "run" in script
+        assert "generate-shell-completion" in script
+
+    def test_contains_output_format_choices(self):
+        parser = pyfltr.main.build_parser()
+        script = pyfltr.shell_completion.generate("bash", parser, frozenset({"ci"}))
+        assert "text" in script
+        assert "jsonl" in script
+
+
+class TestGeneratePowershell:
+    """PowerShell補完スクリプト生成のテスト。"""
+
+    def test_contains_register_argument_completer(self):
+        parser = pyfltr.main.build_parser()
+        subcommands = frozenset({"ci", "run"})
+        script = pyfltr.shell_completion.generate("powershell", parser, subcommands)
+        assert "Register-ArgumentCompleter -Native -CommandName pyfltr" in script
+
+    def test_contains_subcommands(self):
+        parser = pyfltr.main.build_parser()
+        subcommands = frozenset({"ci", "run", "generate-shell-completion"})
+        script = pyfltr.shell_completion.generate("powershell", parser, subcommands)
+        assert "'ci'" in script
+        assert "'run'" in script
+        assert "'generate-shell-completion'" in script
+
+
+class TestMainIntegration:
+    """main.py経由の統合テスト。"""
+
+    def test_bash_success(self, capsys):
+        rc = pyfltr.main.run(["generate-shell-completion", "bash"])
+        assert rc == 0
+        captured = capsys.readouterr()
+        assert "_pyfltr_completions()" in captured.out
+
+    def test_powershell_success(self, capsys):
+        rc = pyfltr.main.run(["generate-shell-completion", "powershell"])
+        assert rc == 0
+        captured = capsys.readouterr()
+        assert "Register-ArgumentCompleter" in captured.out
+
+    def test_no_shell_argument(self):
+        rc = pyfltr.main.run(["generate-shell-completion"])
+        assert rc == 1
+
+    def test_invalid_shell_argument(self):
+        rc = pyfltr.main.run(["generate-shell-completion", "zsh"])
+        assert rc == 1
+
+    def test_subcommand_recognized(self):
+        """generate-shell-completionがサブコマンドとして認識される。"""
+        sub, remaining = pyfltr.main._parse_subcommand(["generate-shell-completion", "bash"])
+        assert sub == "generate-shell-completion"
+        assert remaining == ["bash"]