reclaimable 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. checksums.yaml +7 -0
  2. data/.claude/launch.json +11 -0
  3. data/.gitignore +11 -0
  4. data/.gitlab-ci.yml +16 -0
  5. data/AGENTS.md +88 -0
  6. data/CLAUDE.md +1 -0
  7. data/Gemfile +3 -0
  8. data/LICENSE +674 -0
  9. data/README.md +160 -0
  10. data/Rakefile +28 -0
  11. data/ai-skill/reclaimable/SKILL.md +94 -0
  12. data/benchmark/README.md +59 -0
  13. data/benchmark/experiments/lstat_scanner.rb +11 -0
  14. data/benchmark/experiments/ractor_scanner.rb +92 -0
  15. data/benchmark/experiments/verify_bulk_list.rb +34 -0
  16. data/benchmark/lib/fixture.rb +104 -0
  17. data/benchmark/lib/results.rb +62 -0
  18. data/benchmark/reports/00-baseline.md +75 -0
  19. data/benchmark/reports/01-jit.md +70 -0
  20. data/benchmark/reports/02-ractor.md +58 -0
  21. data/benchmark/reports/03-getattrlistbulk.md +84 -0
  22. data/benchmark/reports/04-others.md +52 -0
  23. data/benchmark/reports/05-outside-root.md +56 -0
  24. data/benchmark/reports/06-round2-discussion.md +374 -0
  25. data/benchmark/reports/06-round2.md +194 -0
  26. data/benchmark/reports/README.md +46 -0
  27. data/benchmark/results/baseline.yml +126 -0
  28. data/benchmark/results/bulk-list.yml +126 -0
  29. data/benchmark/results/final-yjit.yml +126 -0
  30. data/benchmark/results/final.yml +126 -0
  31. data/benchmark/results/ractor-exp.yml +38 -0
  32. data/benchmark/results/round2-after.yml +126 -0
  33. data/benchmark/results/round2-before.yml +126 -0
  34. data/benchmark/results/src-baseline.yml +32 -0
  35. data/benchmark/results/src-bulk-list.yml +32 -0
  36. data/benchmark/results/src-pair-none1.yml +38 -0
  37. data/benchmark/results/src-pair-none2.yml +38 -0
  38. data/benchmark/results/src-pair-yjit1.yml +38 -0
  39. data/benchmark/results/src-pair-yjit2.yml +38 -0
  40. data/benchmark/results/src-ractor-exp.yml +32 -0
  41. data/benchmark/results/src-round2-after1.yml +52 -0
  42. data/benchmark/results/src-round2-after2.yml +52 -0
  43. data/benchmark/results/src-round2-before1.yml +52 -0
  44. data/benchmark/results/src-round2-before2.yml +52 -0
  45. data/benchmark/results/yjit.yml +126 -0
  46. data/benchmark/results/zjit.yml +126 -0
  47. data/benchmark/run.rb +149 -0
  48. data/bin/reclaimable +10 -0
  49. data/doc/performance.md +179 -0
  50. data/lib/reclaimable/ai_skill.rb +138 -0
  51. data/lib/reclaimable/bulk_list.rb +91 -0
  52. data/lib/reclaimable/cache_dump.rb +125 -0
  53. data/lib/reclaimable/cli.rb +168 -0
  54. data/lib/reclaimable/cloud_files.rb +33 -0
  55. data/lib/reclaimable/config.rb +100 -0
  56. data/lib/reclaimable/i18n.rb +24 -0
  57. data/lib/reclaimable/locations.rb +89 -0
  58. data/lib/reclaimable/output.rb +154 -0
  59. data/lib/reclaimable/paths.rb +36 -0
  60. data/lib/reclaimable/report.rb +504 -0
  61. data/lib/reclaimable/ruby_abi.rb +69 -0
  62. data/lib/reclaimable/scan_cache.rb +97 -0
  63. data/lib/reclaimable/scanner.rb +440 -0
  64. data/lib/reclaimable/util.rb +34 -0
  65. data/lib/reclaimable.rb +42 -0
  66. data/locale/ja/LC_MESSAGES/reclaimable.mo +0 -0
  67. data/man/reclaimable.1.ronn +302 -0
  68. data/man/reclaimable.en.1 +234 -0
  69. data/man/reclaimable.ja.1 +452 -0
  70. data/po/ja/reclaimable-docs.po +668 -0
  71. data/po/ja/reclaimable.po +510 -0
  72. data/rakelib/benchmark.rake +22 -0
  73. data/rakelib/docs/japanese.rb +132 -0
  74. data/rakelib/docs/man_page.rb +73 -0
  75. data/rakelib/docs/site.rb +187 -0
  76. data/rakelib/docs/sources.rb +94 -0
  77. data/rakelib/docs/translation.rb +157 -0
  78. data/rakelib/docs.rake +62 -0
  79. data/rakelib/gettext.rake +30 -0
  80. data/rakelib/i18n.rake +199 -0
  81. data/reclaimable.gemspec +56 -0
  82. data/site/index.md +142 -0
  83. data/site/layout.html.erb +60 -0
  84. data/site/style.css +82 -0
  85. metadata +231 -0
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: a34d91f6a6814d77a01850460a088c2a44f53aa7950688b1e684e90051d5cc1e
4
+ data.tar.gz: f04219310b8bcd054eeba1cdbf79c7753bc54eeb5417d91442f1921b663ed54c
5
+ SHA512:
6
+ metadata.gz: 64077808348292bdffc204a3f7ef84201cfce2e579335e0b14d1208e6874952a76639769793a64fa1b3422376a7086565f23636edee34a52049eb09e45feb086
7
+ data.tar.gz: '089063f8398615ce1c1892fa5ee123c03bed9d3c617ef819e3a7ebf8fb47f5bf092f5898ae37c61b292e9b6c0d593344d0b22c784ab271e909bb8aa605fbb944'
@@ -0,0 +1,11 @@
1
+ {
2
+ "version": "0.0.1",
3
+ "configurations": [
4
+ {
5
+ "name": "docs-site",
6
+ "runtimeExecutable": "python3",
7
+ "runtimeArgs": ["-m", "http.server", "8765", "-d", "public"],
8
+ "port": 8765
9
+ }
10
+ ]
11
+ }
data/.gitignore ADDED
@@ -0,0 +1,11 @@
1
+ /pkg/
2
+ /vendor/bundle/
3
+ /.bundle/
4
+ /public/
5
+ /po/*.pot
6
+ /po/*/*.edit.po
7
+ /po/*/*.po.time_stamp
8
+ /tmp/
9
+ /locale/
10
+ /man/*.1
11
+ /Gemfile.lock
data/.gitlab-ci.yml ADDED
@@ -0,0 +1,16 @@
1
+ # GitLab Pages にドキュメントのサイトを公開する。
2
+ # 既定のブランチに push したときだけ、rake site で public/ を作って公開する。
3
+ # CI_PAGES_URL は GitLab が決める公開先の URL(独自ドメインや「unique domain」の設定も反映される)
4
+
5
+ pages:
6
+ image: ruby:4.0
7
+ variables:
8
+ LANG: C.UTF-8 # 日本語の原稿を読むため
9
+ script:
10
+ - bundle install --jobs 4
11
+ - SITE_URL="${CI_PAGES_URL}/" bundle exec rake site
12
+ artifacts:
13
+ paths:
14
+ - public
15
+ rules:
16
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
data/AGENTS.md ADDED
@@ -0,0 +1,88 @@
1
+ # AGENTS.md
2
+
3
+ AI のコーディングエージェント向けの、このリポジトリーでの作業の決まり。人向けの説明は README.md にある。
4
+
5
+ reclaimable は、macOS のストレージの削除候補を洗い出して一覧表示する gem(Ruby 4.0 向け、読み取り専用)。
6
+
7
+ ## 環境
8
+
9
+ - Ruby 4.0 が要る。chruby なら `chruby ruby-4.0` で切り替える(`chruby 4.0` は ruby-3.4.0 に一致しうる)。
10
+ `ruby -v` で 4.0 になったことを確かめる。
11
+ - rake は必ず `bundle exec rake ...` で動かす。bundler を通さないと、`rake man` などが
12
+ strscan の版の食い違い(`StringScanner (expected StringScanner)`)で落ちる。
13
+ - エージェントのシェルでは `LANG` が未設定のことが多く、Ruby が日本語を含むファイルや出力を
14
+ US-ASCII として読んで落ちる。その場で書くスクリプトは `ruby -E UTF-8` で動かす
15
+ (`bin/reclaimable` と Rakefile は自分で UTF-8 にしている)。
16
+
17
+ ## 変更の確かめ方
18
+
19
+ - 構文: `bundle exec rake check`
20
+ - 動作: インストールせずに `ruby -Ilib bin/reclaimable ...` で動かす。
21
+ `rake install` は頼まれたときだけ行う(毎回はしない)。
22
+ - ホーム全体の走査は数十秒から数分かかり、キャッシュも書き換える。小さく試すなら `-d <フォルダー> --no-save`。
23
+ ただし `-d` で起点を絞っても、起点の外の既知のキャッシュ置き場などは別に測り(結果はキャッシュする)、
24
+ 外部コマンドも動かすので、それなりに時間がかかる。
25
+ - 英語の表示は `LC_ALL=C`、日本語は `LANG=ja_JP.UTF-8` を付けて確かめる。
26
+ `ruby -Ilib` で動かすときは Rake を通らないので、日本語の訳(`.mo`)は先に `bundle exec rake gettext` で作っておく。
27
+ - サイト(`bundle exec rake site` で作る `public/`)はシンプルな静的ページなので、ブラウザーでは確かめない。
28
+ 生成したファイルを Ruby や grep で調べるか、curl や Ruby の open-uri で取得して確かめる。
29
+
30
+ ## 速さに関わる変更
31
+
32
+ - 走査やキャッシュの速さに関わる変更は、前後でベンチマークを測って比べる(`benchmark/README.md`)。
33
+ 変更の前に `bundle exec rake "benchmark[before]"`、後に `bundle exec rake "benchmark[after]"` で測り、
34
+ `bundle exec rake "benchmark:compare[before,after]"` で比べる。
35
+ - 既定の対象は作り物のツリーで、CPU 時間しか出ない。採否は、実際のフォルダー(`BENCH_ROOT=~/src` など)の値も見て決める。
36
+ 実際のフォルダーの値は測るたびに 1〜2 割ばらつくので、比べる 2 つを続けて交互に測る。
37
+ - 手を入れる前に `doc/performance.md` を読む。試した施策の採否と理由、計測した環境が書いてある
38
+ (Ractor・ZJIT・スレッド数を増やす、などは試して不採用)。同じ環境なら調べ直さない。
39
+ 判断を変えたり、新しい施策を試したりしたら、そこに書き足す。くわしいリポートは `benchmark/reports/` にある。
40
+
41
+ ## 文言と翻訳
42
+
43
+ - 画面・レポート・ログの文言は英語で書き、`_()`・`n_()`・`p_()` で包む(`lib/reclaimable/i18n.rb`)。
44
+ 翻訳対象の抜き出しはリテラルを探すので、文言は必ずリテラルで渡す。
45
+ - ドキュメントの原稿は英語の `man/reclaimable.1.ronn` と `site/index.md`。日本語版は訳から生成する。
46
+ ronn の定義リストの項目の中にコードブロックを置くと man page から消えるので、例はリストの外に置く。
47
+ - ソースのコメントは日本語。
48
+
49
+ ### 訳の更新(この手順で行い、po を手で編集したり、その場でスクリプトを書いたりしない)
50
+
51
+ コードの改修と同じ流れで訳さない。訳は別のセッションかサブエージェントに任せる。
52
+
53
+ 文言や原稿を変えたら:
54
+
55
+ 1. `bundle exec rake i18n:todo`
56
+ po を原文に合わせて更新し、訳が無い・fuzzy の項目を ID 付きで出す(`tmp/i18n/todo.yml` にも書く)。
57
+ - `current` は msgmerge が似た原文から当てた訳で、まったく違う意味のことがある。そのまま使わず、直すための下書きとして読む。
58
+ - `note` はドキュメントの単位の種類(段落・見出し・コードなど)。
59
+ - 文言を抜き出すのは git が追跡しているファイルだけ(gemspec の files)。新しく作ったファイルの文言が
60
+ 出てこないときは、先に `git add -N <ファイル>` で追跡対象にする。
61
+ 2. 訳を「ID: 訳」の YAML に書く(例: `tmp/i18n/ja.yml`。`tmp/` は git に入らない)。原文は書き写さない。
62
+ ```yaml
63
+ 63ae011e: DIR の固定を外し、また走査するようにする
64
+ 3201cc81: "%{count} 個のファイルを調べました"
65
+ ```
66
+ 複数行の原文(コードブロック)は、行の数と並びをそろえて `|-` で書く。
67
+ 3. `bundle exec rake "i18n:apply[tmp/i18n/ja.yml]"`
68
+ 置き換え部分(`%{...}`・`%<...>d` など)が原文と一致するか、ID が一覧にあるかを確かめてから
69
+ po に書き込み、`.po`・`.mo`・man page を作り直す。食い違いがあれば何も書かずに止まる。
70
+ 最後に残りの件数を出すので、0 になるまで 1〜3 を繰り返す。
71
+
72
+ 訳済みの項目を直すときは、`bundle exec rake "i18n:find[原文か訳の一部]"` で ID と今の訳を調べ、
73
+ 上の 2・3 と同じように「ID: 新しい訳」を書いて `i18n:apply` する(今の訳を置き換える)。
74
+
75
+ 途中の出力を見たいときは `VERBOSE=1` を付ける。
76
+
77
+ ### 訳の書き方
78
+
79
+ - 既存の訳に合わせる。括弧は半角の `()`、「ディレクトリー」「フォルダー」のように長音を付ける。
80
+ - オプションの説明は「〜する」で終える(例: `前回の走査結果(キャッシュ)を使わず全部走査し直す`)。
81
+ 画面のメッセージとドキュメントの本文は「です・ます」。
82
+ - `%{...}` や `` `--freeze` `` のようなコード、パスは訳さずに残す。
83
+
84
+ ## リポジトリーに入れるもの
85
+
86
+ - 訳の正本の `po/*/*.po` はコミットする。
87
+ - 生成物の `man/*.1`・`locale/**/*.mo`・`po/*.pot`・`po/*/*.edit.po`・`public/`・`tmp/` は入れない(.gitignore 済み)。
88
+ gem に入る `man/*.1` と `.mo` は、gem のビルドの依存として Rake が作る。
data/CLAUDE.md ADDED
@@ -0,0 +1 @@
1
+ @AGENTS.md
data/Gemfile ADDED
@@ -0,0 +1,3 @@
1
+ source "https://rubygems.org"
2
+
3
+ gemspec