ln-645-open-source-replacer

パス： ファイルパス（references/、../ln-*）は、このスキルディレクトリを基準とします。

オープンソース置換ツール

タイプ： L3 ワーカー

カスタムモジュールを検出し、その目的を分析して、MCP Research を通じて実績のあるオープンソースの代替手段を見つける L3 ワーカーです。

目的と範囲

• 重要なカスタムモジュール（100 LOC 以上、ユーティリティ／統合タイプ）を検出します
• コードを読み、各モジュールの目的を分析します（パターンベースではなく、目標ベース）
• WebSearch、Context7、Ref を通じてオープンソースの代替手段を検索します
• 代替手段を評価します：スター数、メンテナンス状況、ライセンス、CVE ステータス、API 互換性
• 置換の信頼度をスコアリングします（HIGH／MEDIUM／LOW）
• 実行可能な置換案の移行計画を作成します
• 出力：実行時アーティファクト内の Markdown 証拠レポート、およびコーディネーターへの受け渡し用の機械可読な JSON サマリー

対象外：

• 既知の車輪の再発明（カスタムソート、手書きのバリデーションなど）のパターンベース検出
• パッケージの脆弱性スキャン（既存の依存関係に対する CVE／CVSS）
• OPT- プレフィックスを使用したストーリーレベルの最適性チェック

入力

- codebase_root: string        # Project root
- tech_stack: object            # Language, framework, package manager, existing dependencies
- output_dir: string            # e.g., ".hex-skills/runtime-artifacts/runs/{run_id}/audit-report"

# Domain-aware (optional, from coordinator)
- domain_mode: "global" | "domain-aware"   # Default: "global"
- current_domain: string                   # e.g., "users", "billing" (only if domain-aware)
- scan_path: string                        # e.g., "src/users/" (only if domain-aware)

ワークフロー

必須の読み込み： 検出方法については references/two_layer_detection.md を読み込みます。 必須の読み込み： references/mcp_tool_preferences.md と references/mcp_integration_patterns.md を読み込みます。

アーキテクチャやファイル間参照がモジュールの検出を大幅に改善する場合は、最初に hex-graph を使用します。利用可能な場合、ローカルコードを読み取る際は最初に hex-line を使用します。MCP を利用できない場合、未対応の場合、またはインデックスされていない場合は、組み込みの Read/Grep/Glob/Bash を使用して続行し、レポートにフォールバックしたことを明記します。

フェーズ 1：検出と分類

scan_root = scan_path IF domain_mode == "domain-aware" ELSE codebase_root

# Step 1: Find significant custom files
candidates = []
FOR EACH file IN Glob("**/*.{ts,js,py,rb,go,java,cs}", root=scan_root):
  IF file in node_modules/ OR vendor/ OR .venv/ OR dist/ OR build/ OR test/ OR __test__/:
    SKIP
  line_count = wc -l {file}
  IF line_count >= 100:
    candidates.append(file)

# Step 2: Filter to utility/library-like modules
utility_paths = ["utils/", "lib/", "helpers/", "common/", "shared/", "pkg/", "internal/"]
name_patterns = ["parser", "formatter", "validator", "converter", "encoder",
                 "decoder", "serializer", "logger", "cache", "queue", "scheduler",
                 "mailer", "http", "client", "wrapper", "adapter", "connector",
                 "transformer", "mapper", "builder", "factory", "handler"]

modules = []
FOR EACH file IN candidates:
  is_utility_path = any(p in file.lower() for p in utility_paths)
  is_utility_name = any(p in basename(file).lower() for p in name_patterns)
  export_count = count_exports(file)  # Grep for export/module.exports/def/class
  IF is_utility_path OR is_utility_name OR export_count > 5:
    modules.append(file)

# Step 3: Pre-classification gate
FOR EACH module IN modules:
  # Read first 30 lines to classify
  header = Read(module, limit=30)
  classify as:
    - "utility": generic reusable logic (validation, parsing, formatting, HTTP, caching)
    - "integration": wrappers around external services (email, payments, storage)
    - "domain-specific": business logic unique to project (scoring, routing, pricing rules)

  IF classification == "domain-specific":
    no_replacement_found.append({module, reason: "Domain-specific business logic"})
    REMOVE from modules

# Cap: analyze max 15 utility/integration modules per invocation
modules = modules[:15]

フェーズ 2：目的の抽出

FOR EACH module IN modules:
  # Read code (first 200 lines + exports summary)
  code = Read(module, limit=200)
  exports = Grep("export|module\.exports|def |class |func ", module)

  # Extract goal: what problem does this module solve?
  goal = {
    domain: "email validation" | "HTTP retry" | "CSV parsing" | ...,
    inputs: [types],
    outputs: [types],
    key_operations: ["validates email format", "checks MX records", ...],
    complexity_indicators: ["regex", "network calls", "state machine", "crypto", ...],
    summary: "Custom email validator with MX record checking and disposable domain filtering"
  }

フェーズ 3：代替手段の検索（MCP Research）

FOR EACH module WHERE module.goal extracted:
  # Strategy 1: WebSearch (primary)
  WebSearch("{goal.domain} {tech_stack.language} library package 2026")
  WebSearch("{goal.summary} open source alternative {tech_stack.language}")

  # Strategy 2: Context7 (for known ecosystems)
  IF tech_stack.package_manager == "npm":
    WebSearch("{goal.domain} npm package weekly downloads")
  IF tech_stack.package_manager == "pip":
    WebSearch("{goal.domain} python library pypi")

  # Strategy 3: Ref (documentation search)
  ref_search_documentation("{goal.domain} {tech_stack.language} recommended library")

  # Strategy 4: Ecosystem alignment -- check if existing project dependencies
  # already cover this goal (e.g., project uses Zod -> check zod plugins first)
  FOR EACH dep IN tech_stack.existing_dependencies:
    IF dep.ecosystem overlaps goal.domain:
      WebSearch("{dep.name} {goal.domain} plugin extension")

  # Collect candidates (max 5 per module)
  alternatives = top_5_by_relevance(search_results)

フェーズ 4：評価

必須： 信頼度を割り当てる前に、すべての候補に対してセキュリティゲートとライセンス分類を実施します。

FOR EACH module, FOR EACH alternative:
  # 4a. Basic info
  info = {
    name: "zod" | "email-validator" | ...,
    version: "latest stable",
    weekly_downloads: N,
    github_stars: N,
    last_commit: "YYYY-MM-DD",
  }

  # 4b. Security Gate (mandatory)
  WebSearch("{alternative.name} CVE vulnerability security advisory")
  IF unpatched HIGH/CRITICAL CVE found:
    security_status = "VULNERABLE"
    -> Cap confidence at LOW, add warning to Findings
  ELIF patched CVE (older version):
    security_status = "PATCHED_CVE"
    -> Note in report, no confidence cap
  ELSE:
    security_status = "CLEAN"

  # 4c. License Classification
  license = detect_license(alternative)
  IF license IN ["MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "ISC", "Unlicense"]:
    license_class = "PERMISSIVE"
  ELIF license IN ["GPL-2.0", "GPL-3.0", "AGPL-3.0", "LGPL-2.1", "LGPL-3.0"]:
    IF project_license is copyleft AND compatible:
      license_class = "COPYLEFT_COMPATIBLE"
    ELSE:
      license_class = "COPYLEFT_INCOMPATIBLE"
  ELSE:
    license_class = "UNKNOWN"

  # 4d. Ecosystem Alignment
  ecosystem_match = alternative.name IN tech_stack.existing_dependencies
                    OR alternative.ecosystem == tech_stack.framework
  # Prefer: zod plugin over standalone if project uses zod

  # 4e. Feature & API Evaluation
  api_surface_match = HIGH | MEDIUM | LOW
  feature_coverage = percentage  # what % of custom module features covered
  migration_effort = S | M | L   # S=<4h, M=4-16h, L=>16h

  # 4f. Confidence Assignment
  # HIGH: >10k stars, active (commit <6mo), >90% coverage,
  #       PERMISSIVE license, CLEAN security, ecosystem_match preferred
  # MEDIUM: >1k stars, maintained (commit <1yr), >70% coverage,
  #         PERMISSIVE license, no unpatched CRITICAL CVEs
  # LOW: <1k stars OR unmaintained OR <70% coverage
  #      OR COPYLEFT_INCOMPATIBLE OR VULNERABLE

フェーズ 5：レポートと移行計画の作成

必須の読み込み： references/audit_worker_core_contract.md と references/templates/audit_worker_report_template.md を読み込みます。

references/audit_summary_contract.md に従って JSON サマリーを作成します。管理モードでは呼び出し元が runId と summaryArtifactPath の両方を渡します。スタンドアロンモードでは、共有コントラクトに従ってワーカーが独自の実行単位のアーティファクトパスを生成します。

レポートをメモリ内で作成し、{output_dir}/645-open-source-replacer[-{domain}].md に書き込みます。

# Open Source Replacement Audit Report



## Checks

| ID | Check | Status | Details |
|----|-------|--------|---------|
| module_discovery | Module Discovery | passed/warning | Found N modules >= 100 LOC |
| classification | Pre-Classification | passed | N utility, M integration, K domain-specific (excluded) |
| goal_extraction | Goal Extraction | passed/warning | Extracted goals for N/M modules |
| alternative_search | Alternative Search | passed/warning | Found alternatives for N modules |
| security_gate | Security Gate | passed/warning | N candidates checked, M clean, K vulnerable |
| evaluation | Replacement Evaluation | passed/failed | N HIGH confidence, M MEDIUM |
| migration_plan | Migration Plan | passed/skipped | Generated for N replacements |

## Findings

| Severity | Location | Issue | Principle | Recommendation | Effort |
|----------|----------|-------|-----------|----------------|--------|
| HIGH | src/utils/email-validator.ts (245 LOC) | Custom email validation with MX checking | Reuse / OSS Available | Replace with zod + zod-email (28k stars, MIT, 95% coverage) | M |

## Migration Plan

| Priority | Module | Lines | Replacement | Confidence | Effort | Steps |
|----------|--------|-------|-------------|------------|--------|-------|
| 1 | src/utils/email-validator.ts | 245 | zod + zod-email | HIGH | M | 1. Install 2. Create schema 3. Replace calls 4. Remove module 5. Test |

フェーズ 6：サマリーの返却

Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/645-open-source-replacer[-{domain}].md
Score: X.X/10 | Issues: N (C:0 H:N M:N L:N)

スコアリング

references/audit_scoring.md の標準的な減点方式を使用します。

penalty = (critical x 2.0) + (high x 1.0) + (medium x 0.5) + (low x 0.2)
score = max(0, 10 - penalty)

重大度の対応付け：

• HIGH： 200 LOC を超えるモジュールに対する、信頼度 HIGH の置換案
• MEDIUM： 信頼度 MEDIUM の置換案、または 100～200 LOC のモジュールに対する、信頼度 HIGH の置換案
• LOW： 信頼度 LOW の置換案（部分的な対応のみ）
• 例外： OSS パッケージでは対応できないドメイン固有のロジックを持つカスタムモジュールはスキップします。機能の同等性が 80% 未満の場合は、推奨をスキップします。レイヤー 2： 推奨する前に、置換案が機能の完全な同等性を備えていることを確認します

重要なルール

必ず読むこと： references/audit_worker_core_contract.md を読み込みます。

• パターンベースではなく、目標ベースで進める： 代替手段を探す前に、コードを読んで目的を理解します
• MCP による調査は必須： 常に WebSearch／Context7／Ref で検索し、パッケージが存在すると決めつけないでください
• セキュリティゲートは必須： パッケージを推奨する前に WebSearch で CVE を検索します。未修正の HIGH／CRITICAL CVE があるパッケージは推奨しないでください
• ライセンスの分類は必須： パーミッシブライセンス（MIT／Apache／BSD）を優先します。コピーレフトライセンスは、プロジェクトとの互換性がある場合に限ります
• エコシステムとの整合性： プロジェクトの既存の依存関係ツリーにあるパッケージを優先します（例：プロジェクトで zod を使っている場合は、単体のものより zod プラグインを優先します）
• 事前分類ゲート： 分析前にモジュールを分類し、ドメイン固有のビジネスロジックは除外します
• 自動修正なし： 報告のみを行い、パッケージのインストールやコードの変更は行いません
• 工数の現実的な見積もり： S = 4 時間未満、M = 4～16 時間、L = 16 時間超（移行にかかる工数は単純な修正より大きくなります）
• 分析数の上限： トークン予算を超えないよう、1 回の実行で分析するモジュールは最大 15 個です
• 常に根拠を示す： すべての指摘にファイルパスと行数を記載します

完了の定義

必ず読むこと： references/audit_worker_core_contract.md を読み込みます。

• カスタムモジュールを検出済み（100 LOC 以上、ユーティリティ／統合タイプ）
• 事前分類ゲートを適用済み：ドメイン固有のモジュールを、文書化した理由とともに除外済み
• 各モジュールの目標を抽出済み（ドメイン、入力、出力、操作）
• MCP による調査（WebSearch、Context7、Ref）でオープンソースの代替手段を検索済み
• セキュリティゲートを通過済み：すべての候補について WebSearch で CVE を確認済み
• ライセンスを分類済み：各候補をパーミッシブ／コピーレフト／不明に分類済み
• エコシステムとの整合性を確認済み：プロジェクトの既存依存関係を考慮済み
• 置き換え候補ごとに信頼度を評価済み（HIGH／MEDIUM／LOW）
• 信頼度が HIGH／MEDIUM の置き換え候補について、移行計画を作成済み
• {output_dir}/645-open-source-replacer[-{domain}].md にレポートを作成済み
• コントラクトに従ってサマリーを作成済み

参照ファイル

• スコアリングアルゴリズム： references/audit_scoring.md
• 必ず読むこと： references/research_tool_fallback.md を読み込みます

---

バージョン： 1.0.0 最終更新日： 2026-02-26