pyfltr 2.2.0__tar.gz → 2.3.0__tar.gz

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

@@ -6,7 +6,7 @@
   - `make update-actions`: GitHub Actionsのハッシュピン更新のみ（mise経由でpinact実行）
 - テストコードは`pyfltr/xxx_.py`に対して`tests/xxx_test.py`として配置する
 - 実行パイプラインの構造: `run_pipeline`（main.py）がTUI/非TUI分岐の最上位関数。パイプライン共通の前処理（ファイル展開など）はこの関数内でTUI起動前に実行する
-- コミット前の検証方法: `uv run pyfltr run-for-agent | tail -30`
+- コミット前の検証方法: `uv run pyfltr run-for-agent`
   - ドキュメントなどのみの変更の場合は省略可（pre-commitで実行されるため）
   - テストコードの単体実行なども極力 `uv run pyfltr run-for-agent <path>` を使う（pytestを直接呼び出さない）
     - 詳細な情報などが必要な場合に限り `uv run pytest -vv <path>` などを使用
@@ -15,13 +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の役割分担」節を先に参照
-
-## 関連ドキュメント
-
-- @README.md
-- @docs/index.md
-- @docs/guide/index.md
-- @docs/development/index.md
-- @docs/development/development.md
-- ドキュメント追加時は `mkdocs.yml` の `nav` を更新要

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyfltr
-Version: 2.2.0
+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>
@@ -54,7 +54,7 @@ Description-Content-Type: text/markdown
 - 設定の集約: `pyproject.toml`に寄せた統一設定
 - 除外指定（exclude）の書式差をツール間で吸収
 - 自動修正系ツール（ruff format・prettierなど）を修正と失敗扱いの両立で実行
-- LLMエージェント向けJSON Lines出力（`--output-format=jsonl`）に対応
+- LLMエージェント向けJSON Lines出力（`pyfltr run-for-agent`・`PYFLTR_OUTPUT_FORMAT`環境変数・`--output-format=jsonl`）に対応
 
 ## インストール
 

{pyfltr-2.2.0 → pyfltr-2.3.0}/README.md

@@ -12,7 +12,7 @@
 - 設定の集約: `pyproject.toml`に寄せた統一設定
 - 除外指定（exclude）の書式差をツール間で吸収
 - 自動修正系ツール（ruff format・prettierなど）を修正と失敗扱いの両立で実行
-- LLMエージェント向けJSON Lines出力（`--output-format=jsonl`）に対応
+- LLMエージェント向けJSON Lines出力（`pyfltr run-for-agent`・`PYFLTR_OUTPUT_FORMAT`環境変数・`--output-format=jsonl`）に対応
 
 ## インストール
 

{pyfltr-2.2.0 → 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 ...]`
 
 対象を指定しなかった場合は、カレントディレクトリ(`.`)を指定した場合と同じ扱いとなる。
@@ -81,7 +105,7 @@ pyfltr generate-config
 - markdownlint / textlint: `*.md`
 - pytest: `*_test.py`
 
-### `fast` / `run` / `ci`の動作の違いと自動修正（fixステージ）
+### `fast` / `run` / `run-for-agent` / `ci`の動作の違いと自動修正（fixステージ）
 
 各サブコマンドの主な違いを以下に示す（軽い順）。
 
@@ -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,7 +217,9 @@ CLIオプション`--output-format`が指定されている場合は環境変数
 {"kind":"summary","total":2,"succeeded":0,"formatted":1,"failed":1,"skipped":0,"diagnostics":1,"exit":1}
 ```
 
-出力順は`warning`→`diagnostic`（file/line/col/command順）→`tool`（`pyproject.toml`の定義順）→`summary`（1行）で固定。
+stdoutモード（`--output-file`未指定）では、先頭にheader行を出力し、各ツールの完了時にdiagnostic行+tool行を随時書き出す。
+ツール間の出力順は完了順となり、最後にwarning行+summary行が続く。
+ファイル出力時（`--output-file`指定）では、先頭にheader行、続いて`pyproject.toml`の定義順にツール単位でグルーピングし、先頭にwarning行、末尾にsummary行を配置する。
 
 `warning`レコードの`source`は`config`（設定ファイル不在など）/`tool-resolve`（ツール解決失敗）/`file-resolver`（対象ファイル選定時）/`git`（`git check-ignore`失敗）のいずれか。
 
@@ -212,7 +240,7 @@ LLMエージェントがpyfltrを活用する基本的な流れ:
 1. 全体実行でsummaryを確認する
 
     ```shell
-    pyfltr run-for-agent | tail -30
+    pyfltr run-for-agent
     ```
 
     末尾のsummary行（`"kind":"summary"`）で`failed`の有無と`diagnostics`数を確認し、問題がなければ完了する。
@@ -220,11 +248,11 @@ LLMエージェントがpyfltrを活用する基本的な流れ:
 2. 問題があるツール/ファイルだけ個別に再実行する
 
     ```shell
-    pyfltr run-for-agent --commands=mypy path/to/file.py | tail -30
+    pyfltr run-for-agent --commands=mypy path/to/file.py
     ```
 
     `--commands`で特定ツールに絞ることで出力量を抑えつつ、`diagnostic`行から修正対象のファイル・行番号・メッセージを取得する。
-    詳細が必要な場合に限り`--output-format=text`で再実行するなど、段階的に情報を掘り下げることも可能。
+    詳細が必要な場合に限り`run`で再実行するなど、段階的に情報を掘り下げることも可能。
 
 ## pre-commitとの統合
 

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

@@ -38,9 +38,9 @@ plugins:
         - `pyfltr ci`: 全チェック。formatterによる変更も失敗と判定する（CI向け）
         - `pyfltr run`: 全チェック。fix段→formatter段→linter/tester段の順で、fix-args定義済みlinterの自動修正→formatter→残りの検査を実行する（ローカル向け）
         - `pyfltr fast`: 軽量チェック。`run`と同じ3段構成だが、mypy/pylint/pytest等の重いツールを除外（pre-commit向け）
-        - `pyfltr generate-config`: pyproject.toml用の設定雛形を出力
+        - `pyfltr run-for-agent`: `pyfltr run --output-format=jsonl`のエイリアス。JSONL出力を既定にする（LLMエージェント向け）
 
-        `--no-fix`で`run`/`fast`のfix段を抑止できる。`ci`は副作用回避のため元々fix段を持たない。
+        `--no-fix`で`run`/`fast`/`run-for-agent`のfix段を抑止できる。`ci`は副作用回避のため元々fix段を持たない。
 
         ## 対応ツール
 
@@ -67,19 +67,18 @@ 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 | tail -30
+        pyfltr run-for-agent
         ```
 
         `pyfltr run-for-agent`は`pyfltr run --output-format=jsonl`と等価のエイリアス。

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

@@ -29,6 +29,7 @@ def run_commands_with_cli(
     *,
     per_command_log: bool,
     include_fix_stage: bool = False,
+    on_result: typing.Callable[[pyfltr.command.CommandResult], None] | None = None,
 ) -> list[pyfltr.command.CommandResult]:
     """コマンドを実行する (非 TUI)。
 
@@ -40,6 +41,9 @@ def run_commands_with_cli(
     ``include_fix_stage=True`` のとき、fix-args 定義済みコマンドを先に ``--fix`` 付きで
     直列実行してから、formatter → linter/tester の順で通常実行に進む
     （``ruff check --fix → ruff format → ruff check`` と同じ 2 段階方式の一般化）。
+
+    ``on_result`` が指定されている場合、各コマンド完了時にコールバックを呼び出す。
+    JSONL stdoutモードでのストリーミング出力に使用する。
     """
     results: list[pyfltr.command.CommandResult] = []
     fixers, formatters, linters_and_testers = pyfltr.executor.split_commands_for_execution(
@@ -54,7 +58,10 @@ def run_commands_with_cli(
 
     # formatters を順序実行
     for command in formatters:
-        results.append(_run_one_command(command, args, config, all_files, per_command_log=per_command_log))
+        result = _run_one_command(command, args, config, all_files, per_command_log=per_command_log)
+        results.append(result)
+        if on_result is not None:
+            on_result(result)
 
     # linters/testers を並列実行
     if len(linters_and_testers) > 0:
@@ -64,7 +71,10 @@ def run_commands_with_cli(
                 for command in linters_and_testers
             }
             for future in concurrent.futures.as_completed(future_to_command):
-                results.append(future.result())
+                result = future.result()
+                results.append(result)
+                if on_result is not None:
+                    on_result(result)
 
     return results
 
@@ -130,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` の順でまとめて出力する。
@@ -150,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.0 → pyfltr-2.3.0}/pyfltr/command.py

@@ -121,7 +121,7 @@ _STRUCTURED_OUTPUT_SPECS: dict[str, tuple[str, _StructuredOutputSpec]] = {
     "pytest-tb-line": (
         "pytest",
         _StructuredOutputSpec(
-            inject=["--tb=line"],
+            inject=["--tb=short"],
             conflicts=["--tb"],
         ),
     ),

{pyfltr-2.2.0 → pyfltr-2.3.0}/pyfltr/error_parser.py

@@ -427,28 +427,58 @@ def _parse_typos_jsonl(output: str) -> list[ErrorLocation]:
 
 
 def _parse_pytest(output: str) -> list[ErrorLocation]:
-    """Pytest 出力をパース。--tb=line 形式の行番号付き出力を優先的に抽出する。"""
-    # --tb=line 出力行を探す: /path/to/test.py:42: assert message
-    tb_line_re = re.compile(rf"^(?P<file>{_FILE}):(?P<line>\d+):\s+(?P<message>.+)$", re.MULTILINE)
-    # FAILURES セクション内の --tb=line 出力のみを対象にする
+    """Pytest出力をパース。--tb=short形式のトレースバックからプロジェクト内フレームを優先的に抽出する。"""
     failures_start = output.find("= FAILURES =")
     summary_start = output.find("short test summary info")
-    if failures_start >= 0:
-        end = summary_start if summary_start > failures_start else len(output)
-        failures_section = output[failures_start:end]
-        tb_results: list[ErrorLocation] = []
-        for match in tb_line_re.finditer(failures_section):
-            tb_results.append(
-                ErrorLocation(
-                    file=_normalize_path(match.group("file")),
-                    line=int(match.group("line")),
-                    col=None,
-                    command="pytest",
-                    message=match.group("message").strip(),
-                )
+    if failures_start < 0:
+        return _parse_with_pattern("pytest", output, _BUILTIN_PATTERNS["pytest"])
+
+    end = summary_start if summary_start > failures_start else len(output)
+    failures_section = output[failures_start:end]
+
+    # テスト単位のブロックに分割（`_ test_name _` 区切り）
+    block_re = re.compile(r"^_+ .+ _+$", re.MULTILINE)
+    block_starts = [m.end() for m in block_re.finditer(failures_section)]
+    if not block_starts:
+        return _parse_with_pattern("pytest", output, _BUILTIN_PATTERNS["pytest"])
+
+    # フレーム行: file:line: in func_name
+    frame_re = re.compile(rf"^(?P<file>{_FILE}):(?P<line>\d+): in .+$", re.MULTILINE)
+    # エラー行: E   message
+    error_re = re.compile(r"^E\s+(?P<message>.+)$", re.MULTILINE)
+
+    results: list[ErrorLocation] = []
+    for i, start in enumerate(block_starts):
+        block_end = block_starts[i + 1] if i + 1 < len(block_starts) else len(failures_section)
+        block = failures_section[start:block_end]
+
+        # フレーム群から最後のプロジェクト内フレームを選択
+        frames = list(frame_re.finditer(block))
+        if not frames:
+            continue
+
+        chosen = frames[-1]  # フォールバック: 最後のフレーム
+        for frame in reversed(frames):
+            if _is_project_path(_normalize_path(frame.group("file"))):
+                chosen = frame
+                break
+
+        # エラーメッセージ（先頭のE行）
+        error_match = error_re.search(block)
+        message = error_match.group("message").strip() if error_match else ""
+
+        results.append(
+            ErrorLocation(
+                file=_normalize_path(chosen.group("file")),
+                line=int(chosen.group("line")),
+                col=None,
+                command="pytest",
+                message=message,
             )
-        if tb_results:
-            return tb_results
+        )
+
+    if results:
+        return results
     # フォールバック: FAILED file::test_name パターン（line=0）
     return _parse_with_pattern("pytest", output, _BUILTIN_PATTERNS["pytest"])
 
@@ -576,3 +606,21 @@ def _normalize_path(file_path: str) -> str:
             return file_path
         return result.replace("\\", "/")
     return file_path.replace("\\", "/")
+
+
+def _is_project_path(normalized_path: str) -> bool:
+    """正規化済みパスがプロジェクト内のファイルかを判定する。
+
+    以下を全て満たす場合にプロジェクト内と見なす:
+    - 相対パスである（絶対パスはcwd外 = 標準ライブラリ等）
+    - ``..``で始まらない（uv管理Pythonの標準ライブラリ等）
+    - ``.venv/``で始まらない（仮想環境内サードパーティー）
+    - ``site-packages/``・``dist-packages/``を含まない（名前の異なる仮想環境内サードパーティー）
+    """
+    if pathlib.PurePosixPath(normalized_path).is_absolute():
+        return False
+    if normalized_path.startswith(".."):
+        return False
+    if normalized_path.startswith(".venv/"):
+        return False
+    return not ("site-packages/" in normalized_path or "dist-packages/" in normalized_path)

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

@@ -1,19 +1,26 @@
 """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
 import typing
 
 import pyfltr.command
 import pyfltr.config
 import pyfltr.error_parser
 
+# ストリーミング書き出し時に複数行（diagnostic行+tool行）をアトミックに出力するためのロック。
+# 並列実行される linters/testers から同時にコールバックが呼ばれる可能性がある。
+_write_lock = threading.Lock()
+
 # failed かつ diagnostics=0 のときに tool.message として載せる生出力のトリム上限。
 # 末尾 30 行を取り出し、さらに末尾 2000 文字に切り詰める。
 _MESSAGE_MAX_LINES = 30
@@ -21,45 +28,54 @@ _MESSAGE_MAX_CHARS = 2000
 _TRUNCATED_PREFIX = "... (truncated)\n"
 
 
+def build_tool_lines(
+    result: pyfltr.command.CommandResult,
+    config: pyfltr.config.Config,
+) -> list[str]:
+    """1コマンド分のdiagnostic行+tool行をJSONL文字列のリストとして生成する。
+
+    diagnostic行はツール内でソートされる。
+    """
+    sorted_errors = pyfltr.error_parser.sort_errors(result.errors, config.command_names)
+    lines: list[str] = []
+    for error in sorted_errors:
+        lines.append(_dump(_build_diagnostic_record(error)))
+    lines.append(_dump(_build_tool_record(result, diagnostics=len(result.errors))))
+    return lines
+
+
 def build_lines(
     results: list[pyfltr.command.CommandResult],
     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 各行を生成する。
+    """CommandResult群からJSONL各行を生成する。
 
     出力順:
-        1. `warnings` が非空なら kind="warning" 行（先頭）
-        2. 全診断を (file, line, col, command 順) で昇順ソートした diagnostic 行
-        3. config.command_names の定義順に並べた tool 行
-        4. 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()` の返り値を想定する。
+    resultsは順序を問わない。内部で``config.command_names``順にソートする。
+    ``warnings``は``pyfltr.warnings_.collected_warnings()``の返り値を想定する。
     """
     ordered = sorted(results, key=lambda r: _command_index(config, r.command))
 
     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)))
 
-    all_errors: list[pyfltr.error_parser.ErrorLocation] = []
     for result in ordered:
-        all_errors.extend(result.errors)
-    sorted_errors = pyfltr.error_parser.sort_errors(all_errors, config.command_names)
-    for error in sorted_errors:
-        lines.append(_dump(_build_diagnostic_record(error)))
-
-    diagnostic_counts: dict[str, int] = {}
-    for error in all_errors:
-        diagnostic_counts[error.command] = diagnostic_counts.get(error.command, 0) + 1
-
-    for result in ordered:
-        diagnostics = diagnostic_counts.get(result.command, 0)
-        lines.append(_dump(_build_tool_record(result, diagnostics=diagnostics)))
+        lines.extend(build_tool_lines(result, config))
 
     lines.append(_dump(_build_summary_record(ordered, exit_code=exit_code)))
     return lines
@@ -78,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 もしくは指定ファイルに書き出す。
@@ -86,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)
@@ -100,11 +118,72 @@ 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,
+) -> None:
+    """1コマンド分のdiagnostic行+tool行をstdoutに即時書き出す。
+
+    ``_write_lock``取得下で書き出し+flushするため、並列実行されるlinters/testers
+    から呼ばれてもツール単位のグルーピングが崩れない。
+    """
+    lines = build_tool_lines(result, config)
+    with _write_lock:
+        for line in lines:
+            sys.stdout.write(line)
+            sys.stdout.write("\n")
+        sys.stdout.flush()
+
+
+def write_jsonl_footer(
+    results: list[pyfltr.command.CommandResult],
+    *,
+    exit_code: int,
+    warnings: list[dict[str, typing.Any]] | None = None,
+) -> None:
+    """warning行+summary行をstdoutに書き出す。
+
+    ``results``は``_build_summary_record()``の集計に使用する。
+    """
+    with _write_lock:
+        for warning in warnings or []:
+            sys.stdout.write(_dump(_build_warning_record(warning)))
+            sys.stdout.write("\n")
+        sys.stdout.write(_dump(_build_summary_record(results, exit_code=exit_code)))
+        sys.stdout.write("\n")
+        sys.stdout.flush()
+
+
 def _dump(record: dict[str, typing.Any]) -> str:
     """JSON 1 行にシリアライズする。ensure_ascii=False + 区切り最短化でトークン効率を稼ぐ。"""
     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 {