実装ファイルの tree-shaking 誤削除を修正 + tags.json スキーマ自動移行

[TwoSquirrels]

Fixes #21

概要

宣言と実装が別ファイルに分かれたライブラリで、演算子オーバーロード等が tree-shaking で誤って消えるバグ (#21) を修正します。あわせて必要になった tags.json のスキーマ更新 (v1 → v2) を、ユーザー操作なしで吸収する仕組みを入れます。

背景 (#21)

現行の依存検出は「ユーザーコードに現れる識別子」を手がかりに逆引きします。しかし f * g のような演算子の使用は識別子として現れないため、operator*= の実装だけを置いたファイルが「未使用」と誤判定されて消え、バンドル後に undefined reference になります (Nyaan's Library の FPS で発生)。この症状は宣言がクラス本体側に残るためコンパイルは通り、リンク時にしか顕在化しません。

変更内容

#21: 実装ファイルの保持

• 登録時: クラス外の修飾付き定義 (X<...>::method) の型名や明示的特殊化の主テンプレート名を「実装先の型名」として tags.json に記録する (implements フィールド、schema v2)。
• バンドル時: 「必要と判定されたファイルが定義する型を実装先に持つファイルも必要」という逆引きを 1 種追加し、増えなくなるまで反復する。識別子に現れない依存を、実装ファイルが自ら書く型名から辿れるようにする。
• Nyaan's Library 実測: リンクエラーが解消し、全ヘッダー同時 include のワーストケースでも残存率の増加は +5pt 未満。

スキーマ更新の自動吸収

tags.json はライブラリ実体から再生成できるキャッシュなので、スキーマ不一致は risundle 側の都合と捉え、ユーザー操作を要求しません。

• bundle: 不一致の登録をライブラリ実体から自動で作り直してから続行。
• update / add-std: スキーマ非依存の中核 (Registration) だけを読み、旧スキーマからでも回復。
• list / show: 読み取りに徹し、エラーにも移行にもせず読める情報だけ表示。

原則は「ユーザーの内容変更 (ハッシュ不一致) は確認させ、risundle の形式変更 (スキーマ不一致) は黙って直す」という非対称です。

設計・ドキュメント

• 設計判断は docs/architecture.md に、挙動は docs/spec.md (ja/en) に追記。
• スキーマ耐性の土台として Registration 型を導入し、種別判定を一元化。Inventory の逆引きを FileTags レコードに整理。

テスト

• 実装ファイル保持の結合テストは、症状がリンク時にしか出ないためリンク・実行まで通して検証 (修正前のコードで落ちることを確認済み)。
• スキーマ移行 (bundle 自動移行 / update・add-std の回復 / list・show の寛容 / 破損エラーの伝播) を単体テストで網羅。

補足

• スキーマ耐性の provisioning ロジックが commands/library.rs に同居している既存の層の課題は、本 PR 以前からあるもので、別途 ライブラリ登録の処理を、あるべき層へ整理する #40 で対応します。

Summary by CodeRabbit

• New Features

  • Library details now include implementation-target type names in verbose output.
  • Bundle analysis better preserves implementation files tied to separate declarations.

• Bug Fixes

  • Tree-shaking now keeps needed operator and other out-of-class implementation files.
  • Cache schema changes are handled automatically during bundle/update flows instead of requiring manual recovery.

• Documentation

  • Updated architecture and specification docs to reflect the new library metadata and cache behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds implementation-target type-name tracking (implements) to identifier enumeration, uses it in inventory reverse-lookup and bundle tree-shaking to retain out-of-class implementation files, migrates tags.json to schema_version 2 with automatic silent schema recovery, updates library CLI commands accordingly, and revises docs/specs and tests.

Changes

Implements tracking, tree-shaking, and schema migration

Layer / File(s)	Summary
Identifier enumeration: extract implementation targets src/library/identifiers.rs	Adds Enumeration struct (definitions/implements), threads an implements accumulator through AST traversal, and adds collect_implement_target for qualified/template targets, with new tests.
tags.json schema v2 src/library/tags.rs	Bumps schema_version to 2, adds SchemaMismatch error type, extends TagsKind::Library with implements, adds Registration struct/loader, updates JSON conversion, and tests.
Inventory reverse-lookup src/bundle/inventory.rs	Adds FileTags struct, replaces defines-only lookup with file_tags, updates dependency_headers, and implements implementation_files with new tests.
Bundle tree-shaking and E2E test src/commands/bundle.rs, tests/cli.rs	Calls auto_migrate before bundling; iteratively expands needed headers via implementation-derived headers until stable; adds a CLI test verifying operator implementation retention.
library command schema-tolerant read/update paths src/commands/library.rs	Reworks existing_std_compilers, register_library, update_one/reregister, list, show to use Registration; adds exported auto_migrate, show_outdated, Implements display, and tests.
Docs and spec updates docs/architecture.md, docs/spec.md, docs/spec.ja.md	Documents implementation-target-based tree-shaking, the schema_version 2 implements format, and automatic silent schema migration policy.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
    participant Bundle as commands::bundle::run
    participant Migrate as cmd_library::auto_migrate
    participant Inventory as bundle::inventory
    participant Tags as library::tags::Tags

    Bundle->>Migrate: auto_migrate(&store)
    Migrate->>Tags: Tags::load(each library)
    Tags-->>Migrate: Ok or SchemaMismatch
    Migrate->>Migrate: reregister mismatched libraries
    Bundle->>Inventory: dependency_headers(used)
    Inventory-->>Bundle: dependency_headers set
    loop until stable
        Bundle->>Inventory: implementation_files(needed, present)
        Inventory->>Inventory: compute needed type names from defines
        Inventory->>Inventory: filter present files by implements
        Inventory-->>Bundle: implementation headers
        Bundle->>Bundle: expand dependency_headers
    end
    Bundle->>Bundle: render bundle with needed headers

Loading

Possibly related PRs

• TwoSquirrels/risundle#25: Both PRs modify tree-shaking/needed-header computation in src/commands/bundle.rs's unused_origins logic.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the two main changes: fixing implementation-file tree-shaking and adding automatic tags.json schema migration.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch keep-impl-files

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}