Compare Html

compare-html

構造化 HTML 比較のためのツールキットです。要素、属性、子ノードの照合方法を制御しながら、2 つの HTML ドキュメント間の変更点を見つけます。

理由

多くの HTML 差分ツールは、構造化されていないテキストを出力するか、重要な部分（要素が追加された場所、配列の順序と内容のどちらが異なるのかなど）を隠してしまいます。compare-html は HTML を構造化された表現に解析し、差分の一覧を返します。各項目にはパス、該当する側（base / contrast / both）、変更の種類（added、deleted、valueChanged）が含まれるため、表示、フィルタリング、プログラムからの処理が可能です。

機能

• HTML 要素、属性、配列、テキスト値の詳細な比較。
• 3 種類の子ノード比較戦略：byIndex（デフォルト）、lcs（最長共通部分列による最小限の差分）、unordered（マルチセット照合）。
• タグ／属性名、および／またはテキスト／属性値の大文字小文字を区別しない照合。
• セグメント配列形式とドット記法形式の両方によるパス追跡。
• 表形式または JSON 形式で出力し、インライン文字列またはファイルから読み込めるCLI。
• MCP サーバーを内蔵。CLI を MCP 対応の AI アシスタントに組み込めます。
• エージェントスキル：Claude Code、OpenAI Codex CLI、OpenCode で使える単一のスキルです。
• 完全なTypeScript型定義。

パッケージ

これは pnpm ワークスペースです。

パッケージ	説明
@compare-html/core	コア比較ライブラリ（プログラムから利用できる API）。
@compare-html/cli	core 上に構築されたコマンドラインツールと MCP サーバー。

クイックスタート

ライブラリ

npm install @compare-html/core

import { compareHTML } from '@compare-html/core';

const differences = compareHTML({
  baseHTML: '<user><name>Alice</name><age>30</age></user>',
  contrastHTML: '<user><name>Bob</name><age>30</age><email>[email protected]</email></user>',
});

// [
//   { pathString: 'user.name',  pathBelongsTo: 'both',     diffType: 'valueChanged', ... },
//   { pathString: 'user.email', pathBelongsTo: 'contrast', diffType: 'added',        ... },
// ]

API の全容については、コアの README をご覧ください。

CLI

npm install -g @compare-html/cli

compare-html base.html contrast.html

┌──────────────┬──────────────┐
│ Key          │ Change Type  │
├──────────────┼──────────────┤
│ (Base) a     │ valueChanged │
│ (Base) b     │ deleted      │
│ (Contrast) c │ added        │
└──────────────┴──────────────┘

機械で読み取り可能な出力には --json-export を、MCP サーバーとして起動するには --mcp を使用します。すべてのフラグと MCP ツールのスキーマについては、CLI の README をご覧ください。

MCP

{
  "mcpServers": {
    "compare-html": {
      "command": "npx",
      "args": ["@compare-html/cli@latest", "--mcp"]
    }
  }
}

スキル

単一の SKILL.md で、AI コーディングアシスタントが必要に応じて CLI を呼び出す方法を説明しています。このファイルはオープンな Agent Skills 形式に準拠しており、Claude Code、OpenAI Codex CLI、OpenCode、Cursor など 50 以上のツールで動作します。

最も手軽なインストール方法は npx skills です。インストール済みのすべてのエージェントを自動検出し、それぞれにスキルを追加します。

npx skills add unitstack/compare-html

開発

Node.js ≥ 20 と pnpm が必要です。

# install dependencies
pnpm install

# build all packages
pnpm -r build

# run tests across the workspace
pnpm -r test

# lint
pnpm -r lint

リポジトリの構成：

packages/
├── compare-html-core/     # @compare-html/core — library
├── compare-html-cli/      # @compare-html/cli  — CLI + MCP server
└── internal/             # shared eslint/tsconfig (not published)
skills/
└── compare-html/          # SKILL.md for Claude Code / Codex CLI / OpenCode

ライセンス

MIT