vue-harvest

vue-harvest

Vue プロジェクトを指定すると、すべてのコンポーネントを検出し、再利用可能なものを判別して抽出します。デザイントークン（色、間隔、タイポグラフィ）も抽出し、視覚的なレポートを生成します。

判断が必要な難しいケース（ストアに依存するコンポーネント、依存関係が不明確なコンポーネント）は、LLM に構造化された分析を提供する MCP サーバーが処理します。

主な機能

コンポーネントの抽出。 @vue/compiler-sfc を使用して、プロジェクト内のすべての .vue ファイルを解析します。各コンポーネントについて、インターフェース全体（props、emits、slots）を抽出し、依存関係グラフを構築して、結合の問題を検出し、安全に抽出できるかどうかの信頼度を評価します。しきい値を超えたコンポーネントは、インポートを置き換え、ピア依存関係のマニフェストを含むスタンドアロンバンドルに自動抽出されます。

デザイントークンの抽出。 すべての CSS（スコープ付きスタイル、スタンドアロンのスタイルシート）をスキャンし、色、フォントファミリー、フォントサイズ、フォントの太さ、間隔、角丸、影を抽出します。CSS カスタムプロパティファイル、JSON ダンプ、スウォッチとスケールを表示するビジュアル HTML エクスプローラーを出力します。

MCP サーバー。 LLM が難しいケースを推論するために必要な構造化データを提供する 12 個のツールを備えています。対象は、信頼度が 30〜70％で、ある程度のリファクタリングによって抽出できるコンポーネントです。LLM は結合を詳細に分析し、変更前後のコードを含む分離の提案を生成し、ストアに依存するコンポーネント用のコンポーザブルラッパーを作成し、コードの書き換えから抽出までを一度に実行できます。

インストール

npm install -g vue-harvest

# or run directly
npx vue-harvest analyze ./my-app

MCP サーバーの場合：

npm install -g vue-harvest-mcp

CLI

vue-harvest analyze [path]

分析パイプライン全体を実行します。.vue ファイルを検出し、インターフェースを解析して依存関係グラフを構築し、すべてのコンポーネントを分類して、安全なコンポーネントを自動抽出し、レジストリとカタログを生成します。

vue-harvest analyze
vue-harvest analyze ./path/to/project
vue-harvest analyze --threshold 60
vue-harvest analyze --output ./harvested
vue-harvest analyze --json | jq '.summary'

出力はデフォルトで .vue-harvest/ に保存されます：

.vue-harvest/
  registry.json       Component registry (shadcn-compatible format)
  catalog.html        Browsable catalog with tier filters
  analysis.json       Full analysis dump for the MCP server
  SUMMARY.md          Human-readable report
  components/         Extracted component bundles
    Button/
      Button.vue
      manifest.json
    Card/
      Card.vue
      manifest.json

vue-harvest list [path]

すべてのコンポーネントを、抽出の信頼度順に一覧表示します。

vue-harvest list
vue-harvest list --tier primitive
vue-harvest list --json

vue-harvest inspect <name>

単一のコンポーネントの詳細を表示します：props、イベント、スロット、依存関係、結合の問題、スタイル分析。

vue-harvest inspect Button
vue-harvest inspect UserProfileCard --json

vue-harvest extract <name>

指定したコンポーネントとそのすべてのローカル依存関係を、スタンドアロンバンドルに抽出します。

vue-harvest extract Button
vue-harvest extract UserProfileCard --force
vue-harvest extract Card --output ./my-components

vue-harvest tokens [path]

プロジェクトからデザインシステムのトークンを抽出します。

vue-harvest tokens
vue-harvest tokens --json
vue-harvest tokens --output ./design-system

出力：

• CSS カスタムプロパティを含む tokens.css
• トークンデータ全体を含む tokens.json
• ビジュアルエクスプローラー（カラースウォッチ、フォントスケール、間隔の可視化）を含む design-system.html

vue-harvest init

検出したプロジェクト設定を含む harvest.config.json を作成します。

設定

任意です。プロジェクトのルートに harvest.config.json を配置します：

{
  "include": ["**/*.vue"],
  "exclude": [
    "node_modules/**",
    "dist/**",
    "**/*.test.*",
    "**/*.story.*"
  ],
  "extractionThreshold": 70,
  "outDir": ".vue-harvest",
  "registry": "json"
}

パスエイリアスは tsconfig.json から自動検出されます。プロジェクトで @ が ./src に割り当てられている場合、vue-harvest がそれを認識します。

コンポーネントの分類

各コンポーネントは、インターフェース、依存関係、結合に基づいて再利用性の段階に分類されます：

段階	信頼度	意味
プリミティブ	85-100%	ビジネスロジックを持たない純粋な UI です。Button、Input、Card など。
複合	70-85%	プリミティブから構成され、ロジックは最小限です。FormField、DataTable など。
機能	50-70%	ビジネスロジックを持ちますが、再利用できる可能性があります。UserAvatar、SearchBar など。
ページ依存	30-50%	特定のページまたはルートに強く結合しています。
アプリ固有	0-30%	アプリの状態に深く結合しています。そのままでは再利用できません。

抽出しきい値（デフォルトは 70％）以上のコンポーネントは自動抽出されます。MCP サーバーは、30〜70％の範囲にあるコンポーネントに対して機能します。

結合の問題

アナライザーは次の結合パターンを検出します。

問題	重大度	説明
direct-store-access	警告	Pinia/Vuex ストアを直接インポートしています
hardcoded-api	警告	ハードコードされた API エンドポイント URL が含まれています
router-dependency	情報	vue-router を使用しています
i18n-dependency	警告	vue-i18n を使用しています
global-inject	警告	アプリレベルの provide に inject() を使用しています
env-variable	警告	import.meta.env を参照しています
unscoped-css	警告	グローバルに漏れるスコープなしのスタイルがあります
deep-provide-chain	警告	provide/inject チェーンに依存しています
implicit-global	警告	インポートせずにグローバル登録されたコンポーネントを使用しています
side-effect-import	警告	副作用を実行するインポートがあります

MCP サーバー

Claude Desktop でのセットアップ

~/Library/Application Support/Claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "vue-harvest": {
      "command": "vue-harvest-mcp"
    }
  }
}

Claude Code でのセットアップ

claude mcp add vue-harvest vue-harvest-mcp

利用可能なツール

ツール	機能
analyze-project	プロジェクトパスに対してパイプライン全体を実行します
list-components	フィルター（ティア、信頼度の範囲）を指定してコンポーネントを一覧表示します
inspect-component	ソースコードを含む詳細な分析を行います
extract-component	強制オプションを指定して抽出します
deep-analyze	LLM による推論のための構造化された結合分析を行います
suggest-refactor	結合を解消するための変更前／変更後のコードを提示します
generate-wrapper	ストアに依存するコンポーネント用のコンポーザブルラッパーを作成します
adapt-and-extract	書き換えと抽出を一度に行います
batch-triage	レビュー可能なすべてのコンポーネントを工数見積もりとともに優先順位付けします
coupling-report	プロジェクト全体の結合パターンを報告します
analyze-design-system	デザイントークンを抽出します
get-design-tokens	種類でフィルタリングしたトークンを返します

リソース

分析後、サーバーは次の項目を MCP リソースとして公開します。

• harvest://registry : レジストリ全体の JSON
• harvest://graph : 依存関係グラフ
• harvest://summary : 分析の概要
• harvest://component/{name} : 個別のコンポーネント分析
• harvest://design-system : 抽出されたデザイントークン

プロンプト

• analyze-new-project : 初回分析をガイドします
• extraction-sprint : 一括でリファクタリングと抽出を行うセッション
• refactor-component : 単一コンポーネントの詳細なリファクタリング
• extract-design-system : デザイントークンの抽出と分析

会話例

「/Users/me/projects/my-app にある自分の Vue プロジェクトを分析してください」

「レビューが必要なコンポーネントをすべて表示してください」

「UserProfileCard コンポーネントを詳細に分析し、auth ストアとの結合を解消する方法を提案してください」

「抽出スプリントを実施し、レビュー可能なコンポーネントをすべて確認して、可能なものを抽出してください」

「デザインシステムのトークンを抽出し、命名規則を提案してください」

プログラム API

vue-harvest は、他のツールで使用できる分析エンジンをエクスポートします。

import { analyze, writeOutput, analyzeTokens } from 'vue-harvest'

const report = await analyze('./my-vue-app', {
  extractionThreshold: 0.6,
})

console.log(report.summary)
// { totalFiles: 42, analyzed: 40, autoExtracted: 12, needsMCP: 8, ... }

await writeOutput(report)

// Design tokens
const tokens = await analyzeTokens('./my-vue-app')
console.log(tokens.palette)    // [{ hex: '#3b82f6', usageCount: 14 }, ...]
console.log(tokens.spacing)    // ['4px', '8px', '12px', '16px', '24px']

アーキテクチャ

vue-harvest (monorepo)
  packages/
    cli/                        Published as "vue-harvest" on npm
      src/
        types.ts                Type system shared across the whole project
        index.ts                Pipeline orchestrator
        cli.ts                  CLI entry point (citty)
        analyzers/
          sfc-analyzer.ts       SFC parsing, interface extraction, coupling detection
          graph-builder.ts      Dependency graph with Tarjan's SCC for cycle detection
          design-system-analyzer.ts   Token extraction from CSS
        extractors/
          component-extractor.ts   Import rewriting, file bundling, manifest generation
        generators/
          registry.ts           Registry JSON + catalog HTML generation
        commands/               CLI command definitions
        utils/
          config.ts             Config resolution, alias detection from tsconfig
      tests/
        fixtures/               A real mini Vue project used as test input
        unit/                   66 tests across 5 suites

    mcp/                        Published as "vue-harvest-mcp" on npm
      src/
        index.ts                MCP server (12 tools, resources, prompts)

CLI と MCP を分けているのは意図的です。CLI は、解析、グラフの構築、分類、抽出といった決定論的な処理をすべて担当します。MCP は、結合の解消に関する提案、リファクタリングコードの生成、曖昧さの解消など、推論が必要な 20% を担当します。

開発

git clone https://github.com/virgilvox/vue-harvest.git
cd vue-harvest
pnpm install
pnpm build
pnpm test

CLI のウォッチモード：

pnpm --filter vue-harvest dev

特定のテストファイルを実行する：

npx vitest run packages/cli/tests/unit/sfc-analyzer.test.ts

内部の仕組み

1. 検出。 .vue ファイルを glob で検索し、tsconfig.json を読み込んでパスエイリアスを取得します。
2. SFC の解析。 @vue/compiler-sfc が各ファイルをテンプレート、スクリプト、スタイルのブロックに分割します。
3. インターフェースの抽出。 正規表現ベースの抽出で、defineProps、defineEmits、<slot> タグを取得します。ジェネリック型構文、withDefaults、ネストされたオプションを含むオブジェクト構文に対応します。
4. 依存関係の分析。 es-module-lexer がインポートを解析します。各インポートは種類（内部コンポーネント、コンポーザブル、ストア、ユーティリティ、外部パッケージなど）に分類されます。
5. 結合度の検出。 スクリプトとテンプレートの AST に対するパターンマッチングで、ストアへのアクセス、ハードコードされた API、ルーターの使用、i18n、inject、環境変数、スコープ指定のない CSS を検出します。
6. 分類。 信頼度スコアは 1.0 から始まり、結合度の問題、ストアへのアクセス、ページパスのパターンに応じて減点されます。props／slot インターフェースと UI パスのパターンに応じて加点されます。
7. グラフの構築。 インポートパスを解決して隣接リストを構築し、Tarjan の強連結成分アルゴリズムで循環依存を検出し、推移的な依存関係の閉包を計算します。
8. 抽出。 しきい値を超えるコンポーネントについて、コンポーネント本体とすべてのローカル依存関係（コンポーザブル、ユーティリティ、型、スタイル）を収集し、抽出したバンドル内で相対パスになるようインポートパスを書き換え、ピア依存関係と必要なグローバルを記載したマニフェストを生成します。
9. トークンの抽出。 PostCSS の値パーサーで CSS 宣言から色（hex、rgb、hsl）、フォントプロパティ、スペーシング値、角丸、シャドウを特定します。重複を除去し、hex 値を正規化して、種類ごとに分類します。

ライセンス

MIT