Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude/skills/pr-workflow/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ disable-model-invocation: true
- 他の Issue ファイルの `status:` は変えない。この Issue は手順11で閉じる
4. issueの「確認」項目と、リポ CLAUDE.md の「静的チェック / 検証手段」に従い提出前確認を行う。コードを読んでcaller・importの整合性も確認する。実行系・デプロイ系コマンド(rebuild / deploy / 本番起動)は実行しない
- 画面に出る変更があれば、開発サーバーを立て、`screen-operator` にトップの URL と、Issue の確認に書かれた画面の道順を渡して操作させる。返ってきた「見えたもの」を Issue と突き合わせ、違えば直して流し直す。画面写真を自分で見て、崩れも直す
5. issueの保証節がリポの保証台帳 `docs/guarantees.md` の記載に影響する場合(新保証・変更・廃止)、テストと同じPR内で台帳(保証の文言と対応テストの表)を更新する。台帳の更新漏れは実装未完了として扱う
5. issueの保証節がリポの保証台帳 `docs/guarantees/` の記載に影響する場合(新保証・変更・廃止)、`docs/guarantees/README.md` の運用に従い、テストと同じPR内で該当するファイルの表(保証の文と対応テスト)を更新する。台帳の更新漏れは実装未完了として扱う
6. `git add {変更したファイル}` し、`git diff --name-only --cached` がissueの「対象」フィールドと完全一致することを確認する(保証台帳を更新した場合はそれも対象に含まれていること)。不一致なら実装に戻る
7. コミットする(保証台帳を更新した場合は同じコミットに含める)。メッセージ本文に報告を入れる(手順11で PR 本文の下敷きにする)。一時ファイルは作らず、heredoc で標準入力から渡して1コマンドに収めること:
```
Expand Down
2 changes: 1 addition & 1 deletion README.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,7 +184,7 @@ Prerequisites:
- Cloudflare Pages allows 20,000 files per deployment. build warns when over it, and `publish` stops without pushing
- Up to two accounts

The externally visible behavior pinned by tests is listed in the [guarantee ledger](docs/guarantees.md) (Japanese).
The externally visible behavior pinned by tests is listed in the [guarantee ledger](docs/guarantees/README.md) (Japanese).

## Design Decisions

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,7 +184,7 @@ codeview cf-status # プロジェクトと直近のデ
- Cloudflare Pages の上限は 1 デプロイ 20,000 ファイル。build は超えたら警告し、`publish` は push せずに止まる
- アカウントは2つまで

外から見える振る舞いのうち、テストで固定しているものは [保証台帳](docs/guarantees.md) にある。
外から見える振る舞いのうち、テストで固定しているものは [保証台帳](docs/guarantees/README.md) にある。

## Design Decisions

Expand Down
199 changes: 0 additions & 199 deletions docs/guarantees.md

This file was deleted.

33 changes: 33 additions & 0 deletions docs/guarantees/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Guarantee Ledger

codeview が外へ約束している振る舞いと、それを守るテストの一覧である。約束が破れればテストが落ちるので、
ここに書いたことは気づかないうちに実装とずれていかない。**ここに載っていない振る舞いは約束ではなく、予告なく変わりうる**。
対象は `codeview` コマンド(`build` / `publish`)の外から見える振る舞い、`codeview.toml` の検証、拡張のインターフェース、例の拡張 `examples/plugins/sessions.py` である。
`serve`・`cf-setup`・`cf-status` とページの見た目は対象外である。地位は README の Design Decisions と同格である。

- 目的: いま何を約束しているかを1か所で読む。変更の前に、維持すべき約束をここから引く。テストの無い約束を Gaps に残す
- 分け方: 約束の対象(コマンド・生成するページの群・設定・拡張のインターフェース)ごとに1ファイル。テストファイルや Issue の単位では分けない。新しい対象を作ったときだけファイルを足す
- 書き方: 各ファイルに「保証|対応テスト」の表を置き、1行に約束を1つ、宣言文で書く。出典・経緯・設計の理由は書かない(README の Design Decisions に書く)。ページの見た目と、手で確かめる画面の振る舞いは載せない。約束が10行以上のファイルは、内容のまとまりで `##` の見出しを立て、見出しごとに表を置く。1つの見出しには3行以上を入れ、見出しは行の主語になる名詞句にする。10行未満のファイルは見出しを置かない。ファイルは分けない。同じ名前のテストが別のファイルにあれば、テスト名にテストファイルのパスを添える
- 引き方: Issue で「維持する保証」を挙げるときは、Issue の対象のファイルを開く。テストが落ちたら、テストの名前で台帳を検索すると、破れた約束の行が見つかる。約束が守られていることは、全テストを流す CI が確かめる
- 運用: 変更の前にこの README を読み、変更が触れるファイルから「維持する保証」を引く。約束を足す・変える・消すときは、承認を受けた保証節の文のまま、該当するファイルの表に行を足す・直す・消し、対応テストも同じ変更で直す。行を足して10行以上になったら、同じ変更で見出しを立てる。Issue や作業ごとにファイルや節を起こさない。テストの無い約束は Gaps に書き、テストを足したら移す。乖離は `guarantee-audit` で棚卸しする

## Files

| 約束の対象 |
|---|
| [build](build.md) |
| [links](links.md) |
| [incremental](incremental.md) |
| [config](config.md) |
| [issues](issues.md) |
| [plugins](plugins.md) |
| [publish](publish.md) |
| [sessions](sessions.md) |

## Gaps

- 生成物が 20,000 ファイルを超えたとき、`publish` が push せずに非0で終わること。見本に 2 万件のファイルを作るとテストが重くなりすぎるため見送った
- 直下にファイルが無いディレクトリのページに案内文を出すこと。`test_readme_on_directory_page` は、ファイルのあるディレクトリに案内文が出ないことしか確かめていない
- `build --incremental` が、リポの置き場所・アカウント・本体のコード・`[scan.repos]` 以外の設定・Issue の一覧が変わったときにも作り直すこと。テストは HEAD・GitHub の URL で指す他のリポ・`[scan.repos]`・拡張の Issue の `targets` の変化しか確かめていない
- `check_every_hours` の確認で、起動のずれを見込む分が5分であること。`test_publish_checks_account_at_its_interval` は、間隔より1分短い時に見ることと、直後には見ないことしか確かめていない
- 拡張が返した Issue の `waits` の表示が、待っている Issue のページへのリンクであること。`test_issue_source_next_to_config` は `waits on <リポ> #<番号>` の文字が出ることしか確かめていない
75 changes: 75 additions & 0 deletions docs/guarantees/build.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# build

## 走査(`[[roots]]`・`[scan]`)

| 保証 | 対応テスト |
|---|---|
| `children` のルートは直下の git リポをすべて走査する | `test_scans_children_and_skips` |
| 走査したリポは HEAD にあるファイルをページにする | `test_scans_children_and_skips` |
| トップには、走査したリポへのリンクが並ぶ | `test_scans_children_and_skips` |
| `exclude_prefixes` に前方一致するパスはページにしない | `test_scans_children_and_skips` |
| `skip_exts` の拡張子のファイルはページにしない | `test_scans_children_and_skips` |
| 未コミットのファイルはページにしない | `test_scans_children_and_skips` |
| `skip_dirs` に挙げたディレクトリは走査しない | `test_scans_children_and_skips` |
| `.git` がファイルであるディレクトリ(worktree)は走査しない | `test_scans_children_and_skips` |
| `path` のルートはそのリポ1つだけを走査する | `test_scans_single_repo_path` |
| `[scan.repos."<slug>"]` に書いた `skip_exts` と `exclude_prefixes` は、その slug のリポにだけ、全体の `[scan]` の値に足して適用される | `test_repo_scan_adds_to_global_for_that_repo_only` |

## トップと出力のファイル

| 保証 | 対応テスト |
|---|---|
| トップの左上には、生成した時刻を `built <time data-ts>` で出す | `test_index_shows_build_time_only_on_top` |
| 生成した時刻は、`CODEVIEW_BUILT_AT` があればその値にする | `test_index_shows_build_time_only_on_top` |
| 生成した時刻は、`SOURCE_DATE_EPOCH` から決めない | `test_build_time_ignores_source_date_epoch` |
| 生成した時刻の、JavaScript が無いときに読める文字は `YYYY-MM-DD HH:MM` で、JavaScript があれば相対時刻に書き換える | `test_index_shows_build_time_only_on_top` |
| 生成した時刻はトップ以外のページに出さない | `test_index_shows_build_time_only_on_top` |
| 拡張を設定しなければ、`functions/` には `_middleware.js` だけを書く | `test_no_plugins_means_plain_top` |
| 拡張を設定しなければ、トップはリポの一覧と件数だけになる | `test_no_plugins_means_plain_top` |
| `functions/_middleware.js` は、ホストが `*.pages.dev` のリクエストに 404 を返す | `test_middleware_blocks_pages_dev` |

## ディレクトリのページと左の一覧

| 保証 | 対応テスト |
|---|---|
| README のあるディレクトリのページには、一覧の下に README を描く | `test_readme_on_directory_page` |
| README の無いディレクトリのページには、一覧の先頭のファイルを README と同じ位置に描く | `test_readme_on_directory_page` |
| 左の一覧で、中身がディレクトリ1つだけのディレクトリは、その子のディレクトリと連ねて `a/b/c` の1行にまとめる | `test_dir_only_chains_collapse_into_one_row` |
| 左の一覧のディレクトリの連なりは、中身がディレクトリ1つだけでなくなるところで止まる | `test_dir_only_chains_collapse_into_one_row` |
| 左の一覧のまとめた行は連なりの最も深いディレクトリのページへリンクする | `test_dir_only_chains_collapse_into_one_row` |
| 左の一覧のまとめた行の件数は連なりの最も深いディレクトリの下のファイル数である | `test_dir_only_chains_collapse_into_one_row` |
| まとめた途中のディレクトリ(`a/`、`a/b/`)のページも書く | `test_dir_only_chains_collapse_into_one_row` |
| パンくずはまとめた途中のディレクトリへリンクする | `test_dir_only_chains_collapse_into_one_row` |

## ファイルのページ

| 保証 | 対応テスト |
|---|---|
| ファイルのページはヘッダに行数と(ハイライトできれば)言語を出す | `test_file_page_navigation` |
| ファイルのページは本文側にトップからのパンくずを置く | `test_file_page_navigation` |
| ファイルのページは同じディレクトリの前後のファイル(左の一覧と同じ並び)へのリンクを出す | `test_file_page_navigation` |
| ファイルが1つのディレクトリのファイルのページには、前後のリンクを出さない | `test_file_page_navigation` |
| ファイルのページはヘッダの「行数 · サイズ」に続けて、そのファイルに触れた最後のコミットの日時を出す | `test_file_header_shows_last_modified_not_in_listing` |
| ファイルのページのヘッダに静的に書く日付は、生成時の現在時刻に左右されない | `test_file_header_shows_last_modified_not_in_listing` |
| ファイルのページのヘッダの日時は、`<time>` の `data-ts` に epoch 秒を持ち、JavaScript があれば相対時刻に書き換える | `test_file_header_shows_last_modified_not_in_listing` |
| 左の一覧とディレクトリのページには、日付を出さない | `test_file_header_shows_last_modified_not_in_listing` |
| Markdown のページは、見出し(h1〜h3、表題1つの h1 を除く)が4つ以上あれば、先頭に畳める目次を出す | `test_long_markdown_gets_toc` |
| Mermaid の図を含む Markdown のページは、外部のホストからスクリプトを読まない | `test_mermaid_page_loads_only_bundled_script` |
| Mermaid の図を含む Markdown のページが読むスクリプトは、`public/` に書き出したファイルである | `test_mermaid_page_loads_only_bundled_script` |

## 画像と HTML のファイル

| 保証 | 対応テスト |
|---|---|
| 対象の拡張子(`.png` `.jpg` `.jpeg` `.gif` `.webp` `.ico` `.svg`)の画像のうち、除外していない 5 MiB 以下のものは、`public/<slug>/<リポ内パス>` にそのままコピーする | `test_images_are_copied_and_shown` |
| 除外した画像と 5 MiB を超える画像はコピーしない | `test_images_are_copied_and_shown` |
| 画像ファイルのページはその画像を `<img>` で表示する | `test_images_are_copied_and_shown` |
| 5 MiB を超える画像のページは画像を出さず `Too large to display` を出す | `test_images_are_copied_and_shown` |
| `.svg` のページはコードとして描く | `test_images_are_copied_and_shown`, `test_html_file_page_renders_in_sandboxed_iframe` |
| `.html` と `.htm` のファイルページは、ファイルの中身をそのまま `srcdoc` に入れた `<iframe>` を本文に出す | `test_html_file_page_renders_in_sandboxed_iframe` |
| `.html` と `.htm` のファイルページの iframe の `sandbox` 属性は、`allow-scripts` を含む | `test_html_file_page_renders_in_sandboxed_iframe` |
| `.html` と `.htm` のファイルページの iframe の `sandbox` 属性は、`allow-same-origin` を含まない | `test_html_file_page_renders_in_sandboxed_iframe` |
| `.html` と `.htm` のファイルページでは、ハイライトしたソースも JavaScript なしで(`<details>` で)読める | `test_html_file_page_renders_in_sandboxed_iframe` |
| `.html` と `.htm` のファイルページのヘッダのメタ情報と Copy file は、ほかのコードのページと同じで、Copy file が写すのはソースである | `test_html_file_page_renders_in_sandboxed_iframe` |
| 512 KiB を超える `.html`・`.htm` のファイルページは、iframe を出さず `Too large to display` を出す | `test_html_file_page_renders_in_sandboxed_iframe` |
| バイナリの `.html`・`.htm` のファイルページは、iframe を出さず `Binary` を出す | `test_html_file_page_renders_in_sandboxed_iframe` |
27 changes: 27 additions & 0 deletions docs/guarantees/config.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# config

## 設定ファイルと拡張の読み込み

| 保証 | 対応テスト |
|---|---|
| 設定ファイルが無いときは、`error:` を出して非0で終わり、`public/` を作らない | `test_missing_config_stops_before_build` |
| 設定の書式が誤っているときは、`error:` を出して非0で終わり、`public/` を作らない | `test_broken_config_stops_before_build` |
| 読み込めない拡張を設定したときは、そのモジュール名を出して非0で終わり、`public/` を作らない | `test_unknown_plugin_stops_before_build` |
| アカウントの `issues` に `[plugins] modules` に無いモジュールを挙げると、`error:` を出して非0で終わり、`public/` を作らない | `test_issue_source_must_be_listed_plugin` |
| `issues` に挙げた拡張が `issues()` を持たなければ、`no issues()` を出して非0で終わり、`public/` を作らない | `test_issue_source_needs_issues_function` |

## `[scan.repos]`

| 保証 | 対応テスト |
|---|---|
| `[scan.repos."<slug>"]` に `skip_exts` と `exclude_prefixes` 以外のキーがあれば、`error:` を出して非0で終わり、`public/` を作らない | `test_repo_scan_unknown_key_stops_before_build` |
| `[scan.repos]` の slug ごとの値が表でなければ、`error:` を出して非0で終わり、`public/` を作らない | `test_repo_scan_must_be_a_table_per_repo` |
| 走査対象に無い slug を `[scan.repos]` に書いても build は止まらず、その slug を標準エラーに出す | `test_repo_scan_unknown_slug_warns_and_continues` |

## `[[accounts]]`

| 保証 | 対応テスト |
|---|---|
| `[[accounts]]` が3つ以上なら、`1 to 2` を含むエラーで非0で終わり、`public/` を作らない | `test_at_most_two_accounts` |
| `issues` が `github` でないアカウントに `gh_config_dir` を書くと、非0で終わる | `test_gh_config_dir_only_for_github` |
| `check_every_hours` は正の整数だけを受け付け、それ以外は設定の誤りとして止める | `test_check_every_hours_must_be_positive_integer` |
26 changes: 26 additions & 0 deletions docs/guarantees/incremental.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# incremental

## `build --incremental` が作り直すリポ

| 保証 | 対応テスト |
|---|---|
| `build --incremental` は、前回の `--incremental` から入力が変わったリポだけを作り直す | `test_incremental_build_matches_full_build`, `test_incremental_build_copies_images_like_full_build` |
| `build --incremental` は、Markdown が GitHub の URL で指す他のリポが変わったとき、指している側のリポも作り直す | `test_incremental_build_matches_full_build` |
| `build --incremental` は、リポ単位の設定(`[scan.repos]`)が変わったリポを作り直す | `test_repo_scan_change_rebuilds_incrementally` |
| `build --incremental` は、拡張が返した Issue の `targets` が変われば、リポの HEAD が同じでも、そのリポのページを作り直す | `test_incremental_build_follows_issue_targets` |

## `build --incremental` の出力

| 保証 | 対応テスト |
|---|---|
| `build --incremental` の出力は、付けずに作り直したものと同じになる | `test_incremental_build_matches_full_build`, `test_incremental_build_copies_images_like_full_build`, `test_repo_scan_change_rebuilds_incrementally` |
| `build --incremental` は消えたリポのページを残さない | `test_incremental_build_matches_full_build` |
| `build --incremental` の記録は `public/` の外に置く | `test_incremental_build_skips_when_nothing_changed` |

## `build --incremental` の見送りと使い回し

| 保証 | 対応テスト |
|---|---|
| `build --incremental` は、リポ・Issue・拡張の `fingerprint()` のどれも変わっていなければ、何も書かずに終わる | `test_incremental_build_skips_when_nothing_changed` |
| `build --incremental` は、拡張の `fingerprint()` だけが変わったとき、リポのページを使い回す | `test_incremental_build_follows_plugin_fingerprint` |
| `build --incremental` は、拡張の `fingerprint()` だけが変わったとき、拡張のページを書き直す | `test_incremental_build_follows_plugin_fingerprint` |
Loading
Loading