changelog_from_update_log.py ドキュメント

概要

changelog_from_update_log.py は、更新ログ（例: compare_update_diff.py の出力）や、2つのソースコードファイルを直接比較し、生成AIを用いてMarkdown形式のChangeLogを自動生成するユーティリティスクリプトです。

ログファイルに記載された updated、created、deleted のステータスを読み取り、以下の処理を行います。

updated: 旧版と新版のソースコード全文または要約を生成AIに渡して変更点を抽出します。
created: 新版のソースコードのみをAIで解析し、機能概要を生成します。
deleted: AIによる解析は行わず、機械的に削除された旨をChangeLogに記載します。

動作原理

本スクリプトは、2つの実行モードを持ちます。

ログモード 位置引数が1つ与えられた場合に実行されます。ログファイルから root_dir1（新版）と root_dir2（旧版）のパスを取得し、記載された相対パスから各ソースコードを特定します。
直接比較モード 位置引数が2つ与えられた場合に実行されます。指定された2つのファイルを直接比較し、ChangeLogを作成します。

ソースコードをAIに渡す際、ファイルの文字数が指定された閾値（デフォルト200000文字）を超える場合は、コードを分割（チャンク化）し、中間要約を作成した上で比較を行います。これにより、大規模なファイルに対しても変更点の抽出を可能にしています。AIの呼び出しには、動的にロードされる外部ライブラリ tkai_lib_litellm.py を利用します。

非標準ライブラリ

スクリプト内で動的に検索・インポートされる非標準ライブラリは以下の通りです。

tkai_lib_litellm.py （または tkai_lib_litellm(5).py） ※内部で read_ai_config、query_ai_compatible、extract_text の各関数を利用します。

入出力仕様

入力
- 更新ログファイル（テキスト形式）、または比較対象の旧版・新版ソースコードファイル。
- ファイルの読み込み時は、UTF-8（BOM付き含む）およびCP932（Windows用）を自動判別してデコードします。
出力
- Markdown形式のChangeLogファイル。
- 生成されるファイルは、大見出し # ChangeLog や # Changed、# Created、# Deleted といった構成でフォーマットされます。

CLIオプション

inputs: 位置引数。1個の場合はログファイル、2個の場合は旧版と新版のソースコードファイル。
-o, --output: 出力先のMarkdownファイルパス。デフォルトは CHANGELOG.md です。
--root-dir1: ログ記載の root_dir1 を上書きします（ログモードのみ）。
--root-dir2: ログ記載の root_dir2 を上書きします（ログモードのみ）。
--ai-lib: tkai_lib_litellm.py の明示的なパスを指定します。
--config: AI設定を記述した環境変数ファイルのパス。デフォルトは translate.env です。
--provider: AIのプロバイダ（例: openai, gemini）。指定がない場合は環境変数から取得されます。
--model: AIのモデル名。指定がない場合は環境変数または gpt-4o-mini が使用されます。
--language: ChangeLogの言語（ja または en）。デフォルトは ja です。
--max-direct-chars: AIに直接比較させるソースコードの最大文字数（旧＋新の合計）。デフォルトは 200000 です。
--source-chunk-chars: 大規模ファイルを分割する際の1チャンクあたりの文字数。デフォルトは 40000 です。
--temperature: AIのtemperature設定（浮動小数点数）。
--reasoning-effort: 推論モデル向けの effort 設定（minimal, low, medium, high）。
--dry-run: AIを呼び出さず、ソースパスの解決状況などの確認のみを行います。

実行例

ログモードによるChangeLog生成

python changelog_from_update_log.py update.log -o CHANGELOG.md

直接比較モードによるChangeLog生成

python changelog_from_update_log.py old/program.py new/program.py -o CHANGELOG.md

プロバイダとモデルを指定して実行

python changelog_from_update_log.py update.log --provider gemini --model gemini-3.1-pro-preview

AIを呼び出さずに動作確認（ドライラン）

python changelog_from_update_log.py update.log --dry-run