improve(backend): verify の import 名乖離を内部マスタで補正（ADR-0016 #477）

[yusuke0610]

Closes #477

背景

verify（D6）の辞書レス照合（-→_ 変換・go 接頭辞一致・npm 完全一致）では、配布名と import 名が乖離する PyPI package が actual_import へ昇格せず取りこぼしていた（PyYAML→yaml, Pillow→PIL, beautifulsoup4→bs4, scikit-learn→sklearn 等）。ADR-0016「将来の移行条件」verify 節の残課題。

対応（方針 C: オフライン生成の内部マスタ）

linguist_master.json の前例に倣い、pypi のみ内部マスタで補正する。

• resources/pypi_import_aliases.json（新規）: 配布名（canonical / PEP503）→ トップレベル import 名 の内部マスタ。既知の乖離 17 件を初期集合とする。google.* のような汎用名前空間へ畳まれる package（protobuf 等）は false positive 回避のため意図的に除外
• imports/python.py: @lru_cache でマスタを読み、機械変換で当たらない時のみ alias 照合。連携ホットパスで外部を叩かない（実行時は読むだけ / D4）
• 昇格のみ・降格なし。マスタ未収録の乖離は従来どおり false negative を受容（過剰昇格なし）

D3 テンションの整理（ADR に記録）

「辞書を持たない（D3）」と軽くテンションするが、linguist_master.json と同じモデルで解消:

• マスタは wheel の top_level.txt 由来の機械的事実であり taxonomy 判断を含まない
• 連携ホットパスに外部依存を持ち込まない（D4）
• top_level.txt からのオフライン再生成を想定した暫定キュレーション（実データ拡張は残課題）

ADR-0016 の将来条件節 + 改訂履歴を更新済み。

テスト（TDD: red→green→refactor）

• scanner 単体: 既知乖離の昇格 / 収録済みでも未 import なら昇格しない（過剰昇格防止） / 未収録は false negative 維持
• aggregator 統合: PyYAML 宣言 + yaml import → actual_import 昇格の end-to-end
• & imported → | imported ミュータントを手動注入し、過剰昇格防止テストが殺すことを実証

検証

• make ci full green（lint-tdd / lint-adr-index 含む）
• schemas / routers 不変のため codegen（make codegen-types）・migration 不要

スコープ外（別途）

• 完了条件force commit #1「自分の連携データで乖離を列挙」は実データにアクセスできないため未実施。既知乖離集合で先行（ADR に実データ拡張を残課題として記載）
• ローカルの mutmut は backend/mutants/ の**古いキャッシュ（messages.json が stale）**で baseline が無関係テストで落ちるため scoped 実行不可 → 手動ミュータント検証で代替（本 PR 範囲外・CI の mutation.yml は fresh checkout で無影響）

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved matching for several Python packages whose install names differ from their import names, reducing missed detections.
  • Added support for more known package/import name variations while keeping unknown cases conservative.

• Tests

  • Expanded test coverage for import-name mismatch handling and matching behavior.

• Documentation

  • Updated the architecture notes to reflect the new handling for Python package import-name differences.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a0443e1e-1153-4436-b71b-a26a1b8b5c0e

📥 Commits

Reviewing files that changed from the base of the PR and between ba898e8 and c4ab22f.

📒 Files selected for processing (5)

• backend/app/services/intelligence/skills/imports/python.py
• backend/app/services/intelligence/skills/resources/pypi_import_aliases.json
• backend/tests/test_skill_aggregator.py
• backend/tests/test_skill_import_scanners.py
• docs/adr/0016-github-skill-inference.md

---

📝 Walkthrough

Walkthrough

Adds an internal alias mapping resource (pypi_import_aliases.json) mapping PyPI distribution names to their import namespaces, and extends PythonImportScanner.matches() to consult this alias master when direct normalization fails to match, promoting known divergences (e.g., PyYAML→yaml) to matches. Includes updated tests and ADR documentation.

Changes

PyPI Import Alias Correction

Layer / File(s)	Summary
Alias master resource and loader backend/app/services/intelligence/skills/resources/pypi_import_aliases.json, backend/app/services/intelligence/skills/imports/python.py	Adds a JSON alias mapping resource and a cached _load_import_aliases() function that parses it into canonical-name-to-import-names sets.
Scanner matching fallback backend/app/services/intelligence/skills/imports/python.py	matches() falls back to the alias master when normalized name doesn't directly match imports, checking for intersection with alias-provided import names.
Scanner and aggregator tests backend/tests/test_skill_import_scanners.py, backend/tests/test_skill_aggregator.py	Replaces prior false-negative assertion with tests covering alias-based promotion, non-match without real import, unknown divergence non-match, and aggregator-level actual_import verification.
ADR documentation update docs/adr/0016-github-skill-inference.md	Updates verify (D6) section describing the whitelist-based alias correction approach and adds a 2026-07 revision history entry.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• yusuke0610/devforge#445: Introduced the original PythonImportScanner.matches() mechanical normalization logic that this PR extends with alias-based matching.

Suggested labels: feature

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly states the backend verify import-name divergence fix using an internal master and matches the main change.
Linked Issues check	✅ Passed	The PR implements the alias-master fix, adds deterministic tests, and updates ADR-0016, covering the coding goals of #477.
Out of Scope Changes check	✅ Passed	The added docs and tests are directly tied to the import-name divergence fix and no unrelated code changes stand out.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ 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 improve/verify-import-name-divergence

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific 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.}