components-version-badge

/components:version-badge

バージョン番号、Git コミット、および最近の変更履歴をツールチップに表示するバージョンバッジコンポーネントを実装します。

コンテキスト

• フレームワーク設定：!find . -maxdepth 1 \( -name "next.config.*" -o -name "nuxt.config.*" -o -name "svelte.config.*" -o -name "vite.config.*" \)
• パッケージマネージャー：!find . -maxdepth 1 \( -name "package.json" -o -name "bun.lockb" -o -name "pnpm-lock.yaml" \)
• スタイリング：!find . -maxdepth 1 \( -name "tailwind.config.*" -o -name "postcss.config.*" \)
• UI ライブラリ：!find . -maxdepth 1 -name "components.json"
• 変更履歴：!find . -maxdepth 1 -name \'CHANGELOG.md\'
• バージョン：!jq -r '.version // "unknown"' package.json

パラメーター

• --check-only：プロジェクトを分析し、変更を加えずに実装内容を表示します
• --location <header|footer|custom>：コンポーネントの配置場所を指定します（デフォルト：header）

概要

このコマンドは、アプリケーションに次のバージョン表示を追加します。

• トリガー要素：v1.43.0 | 004ddd9（バージョン＋省略形のコミット）
• ツールチップ：完全なビルド情報（バージョン、コミット、タイムスタンプ、ブランチ）＋最近の変更履歴
• ビルド時の処理：実行時のオーバーヘッドはゼロです

技術スタックの検出

上記のコンテキストから、プロジェクトの技術スタックを検出します。

1. フレームワーク：

   • Next.js：next.config.js、next.config.mjs、または next.config.ts
   • Nuxt：nuxt.config.ts または nuxt.config.js
   • SvelteKit：svelte.config.js
   • Vite + React：vite.config.* ＋依存関係に React
   • Vite + Vue：vite.config.* ＋依存関係に Vue
   • Create React App：依存関係に react-scripts
   • Plain React：特定のフレームワークを使用せず、依存関係に React

2. スタイリング：

   • Tailwind CSS：tailwind.config.* または CSS 内の @tailwind
   • CSS Modules：.module.css ファイル
   • styled-components：依存関係に含まれる
   • Emotion：依存関係に @emotion/*
   • Plain CSS：フォールバック

3. UI ライブラリ：

   • shadcn/ui：shadcn 設定を含む components.json
   • Radix UI：依存関係に @radix-ui/*
   • Headless UI：依存関係に @headlessui/*
   • なし：ネイティブ実装を使用

実行

このバージョンバッジ実装ワークフローを実行します。

ステップ 1：プロジェクトを分析する

package.json を読み込み、依存関係を特定します。フレームワーク設定ファイル、スタイリング設定、および既存のコンポーネントパターンを確認します。

ステップ 2：変更履歴の解析スクリプトを作成する

CHANGELOG.md を解析するビルド時スクリプトを作成します。

場所：scripts/parse-changelog.mjs（または適切な場所）

// Script should:
// 1. Read CHANGELOG.md
// 2. Extract last 2 versions with their changes
// 3. Categorize changes (feat, fix, perf, breaking)
// 4. Output as JSON for NEXT_PUBLIC_CHANGELOG (or equivalent)

変更タイプのアイコン：

タイプ	アイコン	説明
feat	sparkles	新機能
fix	bug	バグ修正
perf	zap	パフォーマンスの改善
breaking	warning	破壊的変更

上限：

• バージョンごとに機能は最大 3 件
• バージョンごとにその他の変更は最大 2 件
• 直近の 2 バージョンのみ

ステップ 3：ビルドパイプラインを設定する

フレームワークに応じて、ビルド時の環境変数を追加します。

Next.js（next.config.mjs）：

const buildInfo = {
  version: process.env.npm_package_version || 'dev',
  commit: process.env.VERCEL_GIT_COMMIT_SHA || process.env.GITHUB_SHA || 'local',
  branch: process.env.VERCEL_GIT_COMMIT_REF || process.env.GITHUB_REF_NAME || 'local',
  buildTime: new Date().toISOString(),
};

export default {
  env: {
    NEXT_PUBLIC_BUILD_INFO: JSON.stringify(buildInfo),
    // NEXT_PUBLIC_CHANGELOG set by parse-changelog.mjs
  },
};

Vite（vite.config.ts）：

export default defineConfig({
  define: {
    'import.meta.env.VITE_BUILD_INFO': JSON.stringify(buildInfo),
  },
});

ステップ 4：コンポーネントを作成する

検出したフレームワークに適したバージョンバッジコンポーネントを作成します。

コンポーネントの構造：

src/components/
  version-badge/
    version-badge.tsx     # Main component
    version-badge.css     # Styles (if not using Tailwind)
    index.ts              # Export

実装する機能：

1. トリガーの表示：

   • ビルド情報から取得したバージョン番号
   • 省略形のコミット SHA（7 文字）
   • 控えめなスタイリング：text-[10px] text-muted-foreground/60
   • 操作可能であることが伝わるホバー時の明るさ変更
   • ビルド情報がない場合（ローカル開発時）は非表示

2. ツールチップの内容：

   • テーブル形式のビルド情報セクション
   • カテゴリー分けされた項目を含む最近の変更セクション
   • 適切なキーボードアクセシビリティ

3. アクセシビリティ：

   • フォーカス可能なボタンのトリガー
   • バージョン情報を含む aria-label
   • フォーカスリングのスタイリング
   • ホバー時とフォーカス時の両方でツールチップを表示
   • スクリーンリーダーに配慮した内容

ステップ 5：コンポーネントを統合する

コンポーネントを適切な場所に追加します。

一般的な配置場所：

• ヘッダー／ナビゲーションバー（最も一般的）
• フッター
• 設定ページ
• 概要モーダル

デフォルト：デスクトップとモバイルの両方のナビゲーションで、ヘッダー内のメインタイトルの下に配置します。

コンポーネントのバリエーション

React + Tailwind + shadcn/ui

shadcn/ui の Tooltip と、クラスを結合する cn ユーティリティを使用します。

React + Tailwind（UI ライブラリなし）

Radix Tooltip またはカスタムツールチップを使ったネイティブな実装です。

Vue 3 + Tailwind

ツールチップの配置に Teleport を使う Vue コンポーネントです。

Svelte + Tailwind

ツールチップの動作にアクションを使う Svelte コンポーネントです。

Plain CSS

テーマ設定用のカスタムプロパティを含む CSS を生成します。

ビルドスクリプトのテンプレート

#!/usr/bin/env node
/**
 * parse-changelog.mjs
 * Parses CHANGELOG.md and outputs JSON for the version badge tooltip
 */

import { readFileSync, existsSync } from 'fs';

const CHANGELOG_PATH = './CHANGELOG.md';
const MAX_VERSIONS = 2;
const MAX_FEATURES_PER_VERSION = 3;
const MAX_OTHER_PER_VERSION = 2;

function parseChangelog() {
  if (!existsSync(CHANGELOG_PATH)) {
    return JSON.stringify([]);
  }

  const content = readFileSync(CHANGELOG_PATH, 'utf-8');
  const versions = [];

  // Parse version headers and their changes
  const versionRegex = /^## \[?(\d+\.\d+\.\d+)\]?/gm;
  const changeRegex = /^\* \*\*(\w+):\*\* (.+)$/gm;

  // ... parsing logic ...

  return JSON.stringify(versions.slice(0, MAX_VERSIONS));
}

// Output for environment variable
console.log(parseChangelog());

フラグ

フラグ	説明
--check-only	プロジェクトを分析し、実装される内容を表示します
--location <loc>	コンポーネントの配置場所を指定します（header、footer、custom）

例

# Implement version badge with auto-detection
/components:version-badge

# Check what would be implemented without changes
/components:version-badge --check-only

# Place in footer instead of header
/components:version-badge --location footer

実装後

実装後に、以下を行います。

1. ビルドを確認する：ビルドコマンドを実行し、環境変数が設定されていることを確認します
2. ツールチップをテストする：ホバー操作とキーボードアクセシビリティを確認します
3. CI を更新する：ビルド中に変更履歴を利用できることを確認します
4. ドキュメントを作成する：バージョン表示機能について README に注記を追加します

エラー処理

• package.json がない：警告を表示し、フレームワークの指定を求めます
• 不明なフレームワーク：汎用的な実装を提案するか、ユーザーに確認します
• CHANGELOG.md がない：コンポーネントは変更履歴なしで動作し、ビルド情報のみを表示します
• 既存のコンポーネントがある：上書き前に確認し、マージ方法を提案します

関連項目

• version-badge-pattern スキル — 詳細なパターンのドキュメント