以下に、make_run_report.py の解析結果に基づくSphinx（MyST）でビルド可能なMarkdownドキュメントを作成します。

# ``make_run_report.py`` ドキュメント

## 概要

``make_run_report.py`` は、指定された作業ディレクトリ (``--workdir``) で特定のコマンド (``--cmd``) を実行し、その実行結果を詳細なレポートとしてMarkdown形式で出力する簡易ツールです。このレポートには、コマンド実行前後のファイル差分、標準出力 (``stdout``)、標準エラー出力 (``stderr``)、プログラムの終了コード、実行中に生成または変更された画像ファイル、およびログファイル（``.log``, ``.out``, ``.txt``）や ``stderr`` 内で検出された警告 (``WARNING``) やエラー (``ERROR``) の情報が含まれます。

オプションで `pandoc` コマンドが利用可能な場合、MarkdownレポートをHTML形式に変換することもできます。

## インストール

本スクリプトはPythonの標準ライブラリのみを使用しており、追加のPythonライブラリのインストールは不要です。

HTMLレポートを生成する場合 (``--html 1`` オプション使用時) は、システムに `pandoc` コマンドがインストールされ、実行パスが通っている必要があります。`pandoc` のインストール方法については、公式ウェブサイトを参照してください。
URL: https://pandoc.org/installing.html

## 使い方

``make_run_report.py`` は、Pythonインタプリタを通じて実行します。

基本的な実行例:
作業ディレクトリをカレントディレクトリ (``.``) とし、``test_program.py`` を実行してレポートを生成します。

```bash
python make_run_report.py --workdir . --cmd "python test_program.py"

HTMLレポートも生成する例: test_program.py が画像を保存する機能を持つと仮定し、--html 1 オプションでHTMLレポートも同時に生成します。

python make_run_report.py --workdir . --cmd "python test_program.py --save 1" --html 1

CLIオプション

make_run_report.py は以下のコマンドラインオプションをサポートしています。

オプション名

型

デフォルト値

説明

--workdir

str

.

コマンドを実行する作業ディレクトリ

--cmd

str

(必須)

--workdir 内で実行するコマンド文字列

--report

str

report.md

生成されるMarkdownレポートのファイル名。--workdir 内に作成されます。

--html

int

0

1 を指定すると、pandoc を使用してHTMLレポートも作成します。 (0: 無効, 1: 有効)

--html-name

str

report.html

HTML出力のファイル名。--workdir 内に作成されます。

--pandoc-cmd

str

pandoc

pandoc コマンドの名前またはパス

--toc

int

1

HTMLレポートに目次 (Table of Contents) を追加します。 (0: 無効, 1: 有効)

--standalone

int

1

pandoc -s オプションを使用して、独立したHTMLファイルを生成します。 (0: 無効, 1: 有効)

--shell

int

1

1 を指定すると shell=True でコマンドを実行します。Windowsでは通常 1 が便利です。 (0: 無効, 1: 有効)

--timeout

float

0.0

コマンドのタイムアウト秒数。 0 以下を指定すると無制限になります。

--ignore

str

.git,__pycache__,venv,.venv,.mypy_cache,.pytest_cache,*.pyc,*.pyo,*.tmp,*.bak,*.swp

ファイル監視から除外するファイルまたはディレクトリのパターンをカンマ区切りで指定します。

--log-exts

str

.log,.out,.txt

警告/エラーを走査するログファイルの拡張子をカンマ区切りで指定します。

--error-regex

str

``\b(error

exception

--warning-regex

str

``\b(warning

warn

--ignore-log-regex

str

""

ログ走査時に無視する行に一致する正規表現パターン。例: 'mean squared error'

--encoding

str

utf-8

stdout、stderr、ログファイルの読み込みに使用するエンコーディングを指定します。

--max-read-bytes

int

2000000

ログファイルの読み込み最大バイト数。この値を超えるとファイルは途中で打ち切られます。

--max-output-chars

int

30000

stdout / stderr のMarkdown出力における最大表示文字数。この値を超えると途中で打ち切られます。

--max-tree-items

int

500

実行前ファイルツリーの最大表示ファイル数。この値を超えると省略されます。

--max-file-items

int

300

作成・変更・削除されたファイルの表における最大表示ファイル数。この値を超えると省略されます。

--max-image-items

int

50

生成・変更された画像ファイルの埋め込み表示最大数。この値を超えると省略されます。

--max-log-hits

int

300

警告/エラー検出結果の最大表示数。この値を超えると省略されます。

--max-hits-per-file

int

100

1ファイルあたりで検出する警告/エラー行の最大数。この値を超えると省略されます。

入出力仕様

入力

  • コマンドライン引数: 上記「CLIオプション」セクションで詳述された引数を入力として受け取ります。

  • 作業ディレクトリ: --workdir オプションで指定されたディレクトリが、コマンド実行のワーキングディレクトリとして使用されます。

  • コマンド: --cmd オプションで指定された文字列が、subprocess.run() を介して実行されます。

  • 既存ファイルシステム: コマンド実行前後のファイルシステムの状態をスナップショットとして取得するために、--workdir およびそのサブディレクトリ内のファイル情報が読み込まれます。--ignore オプションに指定されたパターンに一致するファイルやディレクトリは読み込み対象から除外されます。

  • ログファイル: コマンド実行後に、--workdir 内の新規または変更されたファイルの中から、--log-exts オプションで指定された拡張子を持つテキストファイルが、警告/エラーパターン (--error-regex, --warning-regex, --ignore-log-regex) に基づいてスキャンされます。ログファイルの読み込みは --max-read-bytes で指定されたバイト数に制限されます。

出力

  • Markdownレポートファイル: --report オプションで指定されたパス（--workdir からの相対パス）に、実行結果をまとめたMarkdown形式のレポートが出力されます。ファイル名の例は report.md です。

  • HTMLレポートファイル (オプション): --html 1 オプションが指定され、pandoc コマンドが利用可能な場合、--html-name オプションで指定されたパス（--workdir からの相対パス）にHTML形式のレポートが出力されます。ファイル名の例は report.html です。

  • 標準出力 / 標準エラー出力: スクリプト自体の実行状況や pandoc のエラーメッセージなどが、コンソールに標準出力または標準エラー出力として表示されます。

    • 実行したコマンドの stdout と stderr は、生成されるMarkdownレポート内にコードブロックとして埋め込まれます。これらの出力は --max-output-chars で指定された文字数に制限されます。

  • 終了コード:

    • スクリプトは、実行された --cmd の終了コードを自身の終了コードとして返します。

    • --cmd がタイムアウトした場合は -999 を返します。

    • --cmd の実行中に予期せぬPython例外が発生した場合は -998 を返します。

    • --workdir の指定が不正な場合は 1 を返します。

    • 出力ファイルの作成パスが不正な場合は 1 を返します。

主要なデータ構造

FileInfo

ファイルの情報を保持するデータクラスです。

属性名

型

説明

relpath

str

作業ディレクトリからの相対パス

size

int

ファイルのサイズ (バイト)

mtime_ns

int

最終更新時刻 (ナノ秒単位のエポック時刻)

mtime_iso

str

最終更新時刻 (ISO 8601形式文字列)

RunResult

実行されたコマンドの結果を保持するデータクラスです。

属性名

型

説明

command

str

実行されたコマンド文字列

returncode

int

コマンドの終了コード

stdout

str

コマンドの標準出力

stderr

str

コマンドの標準エラー出力

started_at

str

コマンド開始時刻 (ISO 8601形式文字列)

finished_at

str

コマンド終了時刻 (ISO 8601形式文字列)

timed_out

bool

コマンドがタイムアウトしたかどうか

LogHit

ログファイルまたは stderr 内で検出された警告/エラーの情報を保持するデータクラスです。

属性名

型

説明

relpath

str

関連するファイルの相対パス (__stderr__ は stderr を示す)

lineno

int

検出された行番号

kind

str

検出されたメッセージの種類 ("ERROR" または "WARNING")

line

str

検出された行の内容

主要な関数

main()

スクリプトのエントリポイントです。 コマンドライン引数の解析、作業ディレクトリの検証、コマンド実行前後のファイルスナップショットの取得、コマンドの実行、ファイル差分の計算、ログファイルの走査、レポートの生成とファイルへの書き出し、およびオプションでのHTML変換を行います。

snapshot_files(workdir, ignore_patterns)

指定された workdir 内のファイルを走査し、各ファイルの FileInfo オブジェクトを含む辞書を返します。ignore_patterns に一致するファイルやディレクトリは除外されます。

diff_snapshots(before, after)

コマンド実行前 (before) と実行後 (after) のファイルスナップショットを比較し、新規に作成されたファイル、変更されたファイル、削除されたファイルを検出して、それぞれの FileInfo リストを返します。

run_command(command, workdir, shell, timeout_sec, encoding)

指定された command を workdir で実行します。shell オプション、timeout_sec、および encoding を考慮し、RunResult オブジェクトとして結果を返します。

scan_log_files(workdir, files, log_exts, encoding, error_regex, warning_regex, ignore_regex, max_read_bytes, max_hits_per_file)

指定された files リストの中から log_exts に一致する拡張子を持つファイルを読み込み、error_regex および warning_regex に一致する行を LogHit オブジェクトとして検出します。ignore_regex に一致する行は無視されます。

scan_text_for_hits(relpath, text, error_regex, warning_regex, ignore_regex, max_hits_per_file)

特定のテキストデータ (例: stdout や stderr) を走査し、指定された正規表現パターンに基づいて警告/エラーを検出します。

make_report(workdir, before, after, created, modified, deleted, run_result, log_hits, args)

収集されたすべての情報 (ファイルスナップショット、実行結果、ログ検出結果、CLI引数) を使用して、Markdown形式のレポート文字列を生成します。

run_pandoc(report_md, report_html, pandoc_cmd, toc, standalone, encoding)

生成されたMarkdownレポート (report_md) を入力として、pandoc コマンドを実行し、HTMLレポート (report_html) を出力します。pandoc の実行結果 (終了コード、stdout、stderr) を返します。

その他のヘルパー関数

  • parse_csv_list(): カンマ区切り文字列をリストに変換します。

  • now_iso(): 現在時刻をISO 8601形式で返します。

  • file_mtime_iso(): ファイルの最終更新時刻をISO 8601形式で返します。

  • normalize_relpath(): Path オブジェクトをPOSIX形式の相対パス文字列に変換します。

  • is_ignored(): 指定された相対パスが無視パターンに一致するかどうかを判定します。

  • human_size(): バイト数を人間が読める形式 (KB, MBなど) に変換します。

  • md_escape(): Markdownの特殊文字をエスケープします。

  • md_path_link(): Markdown形式の相対パスリンクを生成します。

  • md_image(): Markdown形式の画像埋め込みタグを生成します。

  • make_file_table(): ファイル情報リストからMarkdown形式の表を生成します。

  • render_tree(): ファイルパスの辞書から簡易的なツリー構造をMarkdown形式で生成します。

  • choose_fence(): テキスト内容に基づいてMarkdownのコードフェンス (`````) を選択します。

  • fenced_block(): テキストを指定された言語のMarkdownコードブロックで囲みます。

  • compile_optional_regex(): オプションの正規表現パターンをコンパイルします。

  • positive_or_zero_float(): 引数パーサー用のカスタム型で、0以上のフロート数を返します。

  • build_argparser(): コマンドライン引数パーサーオブジェクトを構築します。

  • make_inside_workdir(): 指定されたパスが workdir 内にあることを確認し、絶対パスに解決された Path オブジェクトを返します。

非標準ライブラリ

本スクリプトはPythonの標準ライブラリのみを使用しており、追加の非標準ライブラリのインストールは不要です。

ライセンス

コードからはライセンス情報は確認できません。

変更履歴

コードからは変更履歴情報は確認できません。