npm package: @shameondev/mergeui
Description: Find and merge duplicate UI components
Latest version: 0.1.0

[![CI](https://img.shields.io/github/actions/workflow/status/shameondev/mergeui/ci.yml?label=CI)](https://github.com/shameondev/mergeui/actions)
[![npm](https://img.shields.io/npm/v/mergeui)](https://www.npmjs.com/package/mergeui)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

# MergeUI

**Find and merge duplicate UI components in seconds.**

- **Scan** — Finds all duplicate component clusters in your codebase automatically
- **Inspect** — Deep-compares two components with AI to identify shared features and differences
- **Merge** — Generates a merged component and rewrites all imports across your codebase

![MergeUI Demo](demo.gif)

## Quick Start

```bash
# Scan for duplicates (free, no API key needed)
npx mergeui scan ./src --no-llm

# Deep-compare two components
ANTHROPIC_API_KEY=sk-... npx mergeui inspect Select SearchSelect

# Merge with interactive feature selection
ANTHROPIC_API_KEY=sk-... npx mergeui merge Select SearchSelect --interactive
```

## Why MergeUI?

Every large codebase has this problem: someone creates a new `Select` instead of reusing the existing one. Someone imports directly from MUI instead of using the design system wrapper. Over time, you end up with 5 different Selects, 3 different Cards, and nobody knows which one to use.

MergeUI fixes this by:

1. **Scanning** your entire codebase with AST analysis to find structurally similar components
2. **Ranking** matches using AI to understand semantic similarity (not just code similarity)
3. **Merging** selected features from duplicates into a single canonical component
4. **Rewriting** all imports across your codebase automatically

## How It Works

```
npx mergeui scan ./src
```

```
Scanned 230 components

 #  Cluster                    Components  Usages  Est. savings
 1  Select/Dropdown variants   5           47      ~280 LOC
 2  Card layouts               3           23      ~150 LOC
 3  Modal wrappers             3           18      ~120 LOC
 4  Input fields               4           31      ~200 LOC
 5  Button variants            2           52      ~60 LOC

Total: ~810 LOC potential reduction
```

## Installation

```bash
# Run directly (recommended)
npx mergeui scan ./src

# Or install globally
npm install -g mergeui
```

## Commands

### `mergeui scan [dir]`

Scan for duplicate component clusters.

| Flag | Default | Description |
|------|---------|-------------|
| `--threshold` | `0.6` | Similarity threshold (0-1) |
| `--max-files` | `5000` | Maximum files to scan |
| `--no-llm` | `false` | AST-only mode (free, no API key) |
| `--json` | `false` | JSON output for piping |
| `--timeout` | `120` | Timeout in seconds |

### `mergeui inspect <A> <B>`

Deep-compare two components using AI. Shows shared features, differences, and merge advice.

### `mergeui merge <base> <donor>`

Merge donor into base component. AI generates merged code and rewrites imports.

| Flag | Description |
|------|-------------|
| `-i, --interactive` | Guided feature selection |
| `--keep <features>` | Features to keep from donor |
| `--exclude <features>` | Features to exclude |
| `--dry-run` | Preview without writing |
| `--no-rewrite` | Skip import rewriting |

## Configuration

MergeUI uses your Anthropic API key for `inspect` and `merge` commands. `scan --no-llm` works without any key.

### Setup

```bash
# Option 1: Environment variable (recommended)
export ANTHROPIC_API_KEY=sk-ant-...

# Option 2: First-run prompt
npx mergeui inspect Select SearchSelect
# -> "Enter your Anthropic API key: "
# Saved to ~/.mergeui/config.json
```

### Bring Your Own Key (BYOK)

MergeUI never stores, transmits, or logs your API key beyond local config. Your key goes directly to the Anthropic API.

| Variable | Required | Description |
|----------|----------|-------------|
| `ANTHROPIC_API_KEY` | For inspect/merge | Get one at [console.anthropic.com](https://console.anthropic.com) |

## Architecture

```
scan  -> Scanner (Babel AST) -> Matcher (fingerprinting) -> Clusterer (union-find) -> Terminal output
merge -> LLM (Claude) -> Merger -> Rewriter (ts-morph) -> Updated codebase
```

| Module | What it does |
|--------|-------------|
| **Scanner** | Parses JSX/TSX, extracts component signatures (props, hooks, structure) |
| **Matcher** | Compares components using Jaccard similarity + tree edit distance |
| **Clusterer** | Groups similar components using union-find with tag-bag pre-filtering |
| **LLM** | Claude judges semantic similarity, extracts features, generates merged code |
| **Rewriter** | Updates imports across codebase using ts-morph AST transforms |

## Supported Patterns

- Function components (`export function Button`)
- Arrow components (`export const Card = () => ...`)
- Default exports (`export default function Select`)
- HOC wrappers (`memo`, `forwardRef`, `React.memo`)
- TypeScript interfaces and generics
- All CSS approaches (CSS Modules, styled-components, Tailwind, makeStyles)
- Vue/Svelte/Angular — planned for v2
- `styled.div` template components — planned

## Requirements

- Node.js 18+
- `ANTHROPIC_API_KEY` for `inspect` and `merge` commands

## Roadmap

- [x] AST-based duplicate scanning
- [x] AI-powered semantic comparison
- [x] Interactive merge with feature selection
- [x] Auto-import rewriting with ts-morph
- [ ] Full-scan LLM refinement (remove false positives)
- [ ] CI mode (`mergeui ci` for PR checks)
- [ ] VS Code extension
- [ ] Web UI with live component previews
- [ ] Multi-framework support (Vue, Svelte)
- [ ] Embeddings for semantic search

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

[MIT](LICENSE) — use it however you want.