mcpField
S
semver-checks

semver-checks

ローカル
github.com/kyungseopk1m開発ツール01 週間前に更新

semver-checks について

semver-checksはTypeScript宣言の変更を分析し、セマンティックバージョンの更新幅を提案してAPIの破壊的変更を検出します。TypeScriptパッケージのメンテナー向けで、CLI、GitHub Action、MCPからリリースを検証できます。

主な機能

  1. 01TypeScript宣言の比較
  2. 02APIを壊す型変更の検出
  3. 03SemVerの更新幅を提案
  4. 04npm指定、参照、パスの比較
  5. 05CIやプルリクエスト向けレポート

活用シーン

  1. 01公開前にパッケージ変更を確認
  2. 02プルリクエストで確実な破壊を検出
  3. 03宣言したリリース更新幅を検証
  4. 04リリース間のAPI変更を確認

MCP 対応

MCPサーバーはバージョン比較用の`semver_compare`ツールを公開します。このツールでは`old`の明示が必要で、CLIのデフォルト比較はMCPでは利用できません。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
"mcpServers": {
"kyungseopk1m-semver-checks": {
"command": "npx",
"args": [
"-y",
"semver-checks"
]
}
}
}
起動コマンドnpx -y semver-checks

ローカルサーバーにはマシン上の実行環境(Node.js 18 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
npmsemver-checks0.15.2

ツール

2

掲載時のツール一覧 · 1 週間前に更新

パラメーター型必須説明
newstringいいえ新しいバージョン:ファイルシステムパス、git ref、または npm spec。デフォルトは現在のディレクトリです。
oldstringはい古いバージョン:ファイルシステムパス、git ref(タグ、ブランチ、commit SHA)、または npm spec。既存のパスではない "name@version" は npm として読み取られます(例:"[email protected]"、"lodash@latest")。明示するには "npm:" を先頭に付けます。
entryanyいいえプロジェクトルートからの相対パスで指定するエントリーファイル(例:"src/index.ts")。エントリーポイントが複数あるパッケージでは、配列またはカンマ区切りの文字列を渡してください。省略した場合は package.json から自動検出されます。
newAsenumいいえ"new" をファイルシステムパス、git ref、または npm spec として強制的に扱います。"ref" は "git" の有効な別名です。path | git | ref | npm
oldAsenumいいえ"old" をファイルシステムパス、git ref、または npm spec として強制的に扱います。"ref" は "git" の有効な別名です。自動検出で入力が誤った種類として読み取られる場合のみ必要です。たとえば "[email protected]" のような形式の monorepo タグが該当します。path | git | ref | npm
declaredenumいいえこのリリースが宣言する更新種別。"auto" を指定すると、.changeset/*.md から読み取り、次に 2 つの package.json のバージョンを読み取ります。レポートに "declaration" 判定が追加されます。確認済みの破壊的変更が宣言内容より重大な場合は "mismatch"、変更内容が宣言より大きな更新を求める場合は "review"、それ以外は "ok" です。"auto" で読み取る対象が見つからない場合は、合格を報告せずエラーになります。major | minor | patch | none | auto
maxChangesintegerいいえ含める変更の数(デフォルトは 50)。変更は、確認済みの破壊的変更、追加、レビューのみの項目の順に並びます。そのため、上限に達すると、対応の優先度が最も低い末尾の項目が省かれます。`summary` は常にすべての変更をカウントし、`omitted` フィールドには省略された内容と、すべて取得するために指定すべき数が報告されます。
installDepsbooleanいいえ分析前に依存関係をインストールします(`node_modules` がない場合にローカルパスを扱うために必要です)。

詳細

npm version CI License: MIT Node.js Version

semver-checks

pino 10.4.0 では、マイナーリリースで、pino 名前空間内に export { pino as default, pino } が追加されました。これにより、名前空間の9つのメンバーの暗黙的なエクスポートが無効になります。そのため、const t: pino.TimeFn = () => '' は10.3.1ではコンパイルできますが、10.4.0ではTS2694「Namespace 'pino' has no exported member 'TimeFn'」で失敗します。

npx semver-checks compare [email protected] [email protected]

公開可能なパッケージのディレクトリで引数なしで実行すると、npx semver-checks は <name>@latest と . を比較します。このデフォルトはCLI専用です。GitHub ActionとMCPのsemver_compareツールでは、oldを明示的に指定する必要があります。

semver-checks — Recommended bump: MAJOR
  major: 20 (confident: 11, review: 9)  minor: 88  patch: 0

  Breaking Changes — confident (MAJOR)
  ✗ Export 'TimeFn' was removed
      was: type-alias
  ✗ Export 'MixinFn' was removed
      was: type-alias
  ✗ Export 'MixinMergeStrategyFn' was removed
      was: type-alias
  ...

出力では、バージョン変更の件数と削除された9つのエクスポートのうち3つに絞って表示します(...は省略箇所を示し、stderrの警告は省略します)。完全な実行結果には、残り6つ、MultiStreamResに追加された必須プロパティ2つ、レビューのみの指摘事項、追加項目も表示されます。

semver-checksは両方のバージョンのTypeScript宣言を比較し、型の変更に必要なバージョン変更を推奨します。そのため、コミットメッセージではなくAPIに基づいて判断できます。どちらのバージョンもチェックアウトする必要はありません。それぞれnpm spec、git ref、または作業ツリーを指定できます。

npx semver-checks compare your-package@latest .

プルリクエストのゲートとして同じチェックを実行すると、変更行に注釈を付け、実証された破壊的変更がある場合に失敗します。

# .github/workflows/semver-check.yml
on: pull_request
jobs:
  semver-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
      - run: npm ci
      - uses: kyungseopk1m/[email protected]
        with:
          old: "your-package@latest"
          strict: "true"

すべての入力と、宣言されたバージョン変更を評価して判定をコメントとして投稿する、リリースプルリクエスト向けのバリエーションについては、GitHub Actionをご覧ください。

semver-checksを使う理由

バージョン変更は、リリースによって公開APIがどう変わったかを示すもので、通常は作業の終わりに、記憶を頼りに手作業で記述します。必須のエクスポートを削除するリファクタリングは、作成者にはパッチに見えても、下流のユーザーにとってはビルドを壊す変更です。

リリースツールが扱えるのは、与えられた根拠だけです。semantic-releaseはコミット規約からリリース種別を導き出し、changesetsは作成者が記述したリリースノートに、frontmatterで宣言されたバージョン変更を記録します。どちらも、その時点で作成者が信じていた内容を引き継ぎます。

semver-checksはts-morphを使って公開APIを直接読み取り、型シグネチャがどう変わったかに基づいてバージョン変更を判断します。

上の例は作り話ではありません。実際のリリースに対してツールを実行すると、マイナーリリースやパッチリリースとして公開された、型の破壊的変更が見つかります。最も信頼できるのは、削除または名前変更されたエクスポート、狭められたシグネチャ、追加された必須パラメーターやプロパティといった構造的な変更です。同値性を保つ型の書き換えは既知の弱点で、過剰に報告する場合があります。docs/accuracy.mdには、どこまで信頼できるか、またどこでは信頼できないかが詳しく記載されています。

// v1.0.0
export interface Config {
  host: string;
  port: number;
}

// Developer writes: "fix: add missing timeout config"
// Published as patch — but this is a MAJOR change:
export interface Config {
  host: string;
  port: number;
  timeout: number;
}
//                                                    ^^^^^^^^^^^^^^^^ required-property-added
// v1.0.0
export function findUser(id: string): User;

// Developer writes: "fix: findUser can come up empty"
// Published as minor — but no existing consumer is written to handle null:
export function findUser(id: string): User | null;
//                                    ^^^^^^^^^^^ return-type-changed (MAJOR)

この変更を逆にした場合は、破壊的変更にはなりません。User | nullをUserに狭めても、すべての利用者には、もともと受け入れられる値が渡されます。semver-checksはこれをreturn-type-narrowedとして報告し、MINORと判定します。

semver-checksは、既存のリリースワークフローを補完します。公開前の検証ステップとして使えば、予定しているバージョン変更が安全か、あるいは誤って破壊的変更をリリースしようとしているかを確認できます。

クイックスタート

npm install --save-dev semver-checks

Git タグと最新のコミットを比較します:

npx semver-checks compare v1.0.0 HEAD

公開済みの npm リリースと作業ツリーを比較します。Git タグがなくても、「現在の変更は破壊的なリリースになるか?」を確認できます:

npx semver-checks compare your-package@latest

<package>@<version> 引数は(npm pack を介して)npm レジストリから取得され、古いバージョンとして使用されます。具体的なバージョン、範囲、一般的な dist-tag は自動検出されます([email protected]、your-package@^1、your-package@next)。一般的でない dist-tag の場合は、Git の参照と誤認されないように、npm: プレフィックスまたは --old-as npm(npm:your-package@my-custom-tag)を使って意図を明示してください。

2 つのローカルディレクトリを比較します:

npx semver-checks compare ./old ./new

./ プレフィックスのない既存の相対パスも、ローカルディレクトリとして扱われます:

npx semver-checks compare packages/core packages/core-next

Git の参照と既存のパス名が衝突する場合は、参照として解釈するよう明示的に指定してください:

npx semver-checks compare main HEAD --old-as ref

JSON、Markdown(PR コメント用)、または GitHub Actions のアノテーションとして出力します:

npx semver-checks compare v1.0.0 HEAD --format json
npx semver-checks compare v1.0.0 HEAD --format markdown
npx semver-checks compare v1.0.0 HEAD --format github

破壊的変更が検出された場合に CI で失敗させます(exit 1):

npx semver-checks compare v1.0.0 HEAD --strict

現在または過去のバージョンの API サーフェスを調べます:

npx semver-checks snapshot
npx semver-checks snapshot --ref v1.0.0
npx semver-checks snapshot --npm [email protected]

すべてのフラグについては、docs/cli.md を参照してください。

複数のエントリーポイント

package.json で複数のサブパスを持つ "exports" マップを宣言している場合、.d.ts エントリーが宣言されている各サブパスが抽出され、個別に比較されます。サブパスの追加は MINOR 変更、削除は MAJOR 変更です。サブパス内の変更は # 区切りで報告されます(例:./utils#helper)。フラグは不要です。マップは自動検出されます。

"exports" マップのないプロジェクトでは、--entry を繰り返すか、カンマ区切りで指定して、複数のエントリーを明示的に渡します:

npx semver-checks compare v1.0.0 HEAD --entry src/index.ts --entry src/utils.ts
npx semver-checks compare v1.0.0 HEAD --entry src/index.ts,src/utils.ts
出力例
semver-checks — Recommended bump: MAJOR
  major: 2 (confident: 1, review: 1)  minor: 1  patch: 0

  Breaking Changes — confident (MAJOR)
  ✗ Required property 'timeout' was added to interface 'Config'
      now: number

  Needs review — couldn't prove safe (MAJOR)
  ? Call signatures of interface 'Middleware' changed
      before: (req: string) => void
      after:  (request: string, next?: (() => void) | undefined) => void

  New Features (MINOR)
  + Export 'createConfig' was added

2 つ目の指摘は、パラメーター名の変更とオプションのパラメーターの追加です。どちらも呼び出し元に影響しませんが、ツールは呼び出しシグネチャを表示テキストとして比較するため、それを証明できません。そのため推測はせず、その旨を示します。--strict は、確実な破壊的変更がある場合にのみ終了コード 1 を返します。レビューのみの項目は、--strict-review を指定しない限りゲートを通過します。

CI との統合

GitHub Action

semver-checks には、再利用可能な複合アクションが用意されています。最も手軽な構成では、公開されている latest リリースと PR の作業ツリーを比較するため、git タグは不要で、差分にインライン注釈を投稿します。

name: SemVer Check

on:
  pull_request:
    branches: [main]

jobs:
  semver-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
      - run: npm ci

      - uses: kyungseopk1m/[email protected]
        with:
          old: "your-package@latest" # the published version to compare against
          format: "github" # inline ::error:: / ::warning:: annotations
          strict: "true" # fail the PR on a confident (proven) breaking change
入力説明デフォルト
old古いバージョン — npm の指定(pkg@latest)、git ref、またはパス(必須)
new新しいバージョン — git ref、またはパス.
entryエントリーファイル(省略時は package.json から自動検出)(自動)
old-asold を path、git、または npm として読み込むよう指定します。[email protected] のようなモノレポタグで必要です。自動検出では、この形式は npm の指定として読み込まれるためです(自動検出)
new-asnew を path、git、または npm として読み込むよう指定します(自動検出)
install-depsソースの種類にかかわらず、解析前に両方の依存関係をインストールします。ローカルパスの場合に必要です。git ref の場合は自動的にインストールされますfalse
formattext、json、markdown、または githubgithub
strict**確実な(証明された)**破壊的変更がある場合にステップを失敗させます(終了コード 1)false
strict-reviewレビューのみ(ヒューリスティック)によるものを含む、あらゆる破壊的変更がある場合にステップを失敗させます(終了コード 1)false
declaredこのリリースで宣言するバージョンアップ:major、minor、patch、none、または auto。証明された破壊的変更を過小評価している場合にステップを失敗させ、strict より優先されます(無効)
commentレポートをコメントとして PR に投稿し、後続のプッシュで更新します(format: markdown を強制)false
tokenコメント投稿に使用するトークン。複合アクションでは secrets コンテキストを読み取れないため、渡す必要があります${{ github.token }}
versionnpx 経由で実行する semver-checks のバージョン(アクションの ref に一致)

完全な例は examples/github-actions.yml にあります。

リリース用プルリクエストの場合

このリリースで宣言したバージョンアップは、API サーフェスへの変更をカバーしていますか?@clerk/break-check と semvet も、2 つの package.json のバージョンから宣言されたバージョンアップを評価します。.changeset ファイルから読み取る点が、このツール固有の機能です。declared: auto は .changeset/*.md からバージョンアップを読み取り、そこにない場合は 2 つの package.json のバージョンを使用します。また、comment: true を指定すると、判定結果をログに残すのではなく、プルリクエストに投稿します。

permissions:
  contents: read
  pull-requests: write # required for `comment`

jobs:
  semver-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
      - run: npm ci

      - uses: kyungseopk1m/[email protected]
        with:
          old: "your-package@latest"
          declared: "auto"
          comment: "true"

宣言されたバージョンアップが、証明された破壊的変更を過小評価している場合、ステップは失敗します。追加のみを過小評価している場合は、注記を付けて成功します。token のデフォルトは github.token です。セットアップで別のトークンが必要な場合は、明示的に渡してください。フォークからのプルリクエストでは読み取り専用トークンが使われるため、ステップを失敗させずに警告を出してコメントをスキップします。

コメントの投稿には gh pr comment --edit-last --create-if-none を使用します。これは、トークンの所有者がプルリクエストに投稿した最新のコメントを更新します。独自のマーカーは検索しないため、同じトークンで他のワークフローから別のコメントを投稿する場合は、このアクション専用のトークンで実行するか、comment を無効にしてください。

アクションを使わない場合

CLI を直接実行します。たとえば、公開済みリリースと作業ツリーを比較するには、次のようにします。

- name: Check for breaking changes
  run: npx semver-checks compare your-package@latest --format github --strict

または、git タグと比較します。

- name: Check for breaking changes
  run: npx semver-checks compare v$(node -p "require('./package.json').version") HEAD --strict

正確性

すべての破壊的変更には信頼度が付与されます。proven は、その変更自体が根拠となるか、アナライザーが解決した型の関係が実際に無関係だと判定されたことを意味します。--strict は、その場合に限って失敗します。heuristic は、保守的に MAJOR と判定したものの、証明できなかった変更を意味します。レビュー用に提示されますが、デフォルトのゲートでは対象外です。ただし、--strict-review を指定すると対象になります。

スコアカードでは、作者が公開したバージョン変更ではなく、tsc を判定基準として使っています。このツールは、作者がそのバージョン変更を誤ることを前提としているためです。24 パッケージにわたる、隣接するマイナー/パッチリリースの組み合わせ 111 件を対象とし、それぞれの両方のバージョンに対してコンシューマープログラムをコンパイルしました。

フラグ対象となる失敗111 件の組み合わせでの結果(実際の破壊的変更 43 件)保証できること
--strictproven の MAJOR のみ37 件で検出し、そのうち 36 件は実際の破壊的変更:適合率 97.3%、再現率 83.7%失敗は強いシグナルです。成功しても、問題がないとは限りません
--strict-reviewすべての MAJOR実際の破壊的変更 43 件すべてと、何も含まない 10 件の組み合わせで検出:再現率 100%、適合率 81.1%成功すれば、分析対象のどこにも破壊的変更が報告されていないことを意味します

型解決を行わない、名前と引数の数だけに基づくベースラインの同じコーパスでのスコアは 87.5%/32.6% です。すべてのプッシュで --strict を有効にし、リリース前に人が出力を確認する場合は --strict-review を実行してください。

残りの内容は docs/accuracy.md にあります。コーパスの構築方法、--strict が何も報告しない 7 件の組み合わせとその理由、残る誤検出 1 件、分散プローブが回答を拒む内容、既知の制限事項 10 件について説明しています。

プログラム API

import { compare, extract } from "semver-checks";

const report = await compare({
  oldSource: { type: "git", ref: "v1.0.0" },
  newSource: { type: "path", path: "." },
});

console.log(report.recommended); // 'major' | 'minor' | 'patch'
console.log(report.changes); // ApiChange[]
console.log(report.summary); // { major: 2, minor: 1, patch: 0, ... }
interface CompareOptions {
  oldSource: SourceRef;
  newSource: SourceRef;
  entry?: string | string[]; // Optional: specify one or more entry points
  installDeps?: boolean; // Optional: install deps on both sides before analyzing
  declared?: DeclaredBump | "auto"; // Optional: grade the bump this release declares
}

type DeclaredBump = "major" | "minor" | "patch" | "none";

type SourceRef =
  | { type: "path"; path: string }
  | { type: "git"; ref: string; cwd?: string }
  | { type: "npm"; spec: string }; // e.g. { type: 'npm', spec: '[email protected]' }

interface SemverReport {
  recommended: "major" | "minor" | "patch";
  changes: ApiChange[];
  summary: {
    major: number;
    minor: number;
    patch: number;
    majorProven: number;
    majorReview: number;
  };
  // Present only when a declared bump was supplied or detected.
  declaration?: BumpDeclaration;
}

interface BumpDeclaration {
  declared: DeclaredBump;
  source: string; // where it was read from: a changeset path, or the two versions
  required: "major" | "minor" | "patch"; // what the proven breaks require
  suggested: "major" | "minor" | "patch"; // what the whole change set argues for
  verdict: "ok" | "review" | "mismatch";
}

interface ApiChange {
  kind: ChangeKind;
  severity: "major" | "minor" | "patch";
  symbolPath: string;
  message: string;
  oldValue?: string;
  newValue?: string;
  confidence?: "proven" | "heuristic";
}

スナップショットを個別に抽出することもできます。

import { extract } from "semver-checks";

const snapshot = await extract({ projectPath: "." });
// Snapshots are keyed by export subpath ('.' is the root entry; additional
// subpaths come from the package.json "exports" map).
console.log(Object.keys(snapshot.entrypoints["."])); // root entry's symbol names

リファレンス

ドキュメント内容
docs/cli.mdcompare と snapshot のすべてのフラグ、終了コード、出力形式、--declared の判定表
docs/change-rules.mdすべての ChangeKind 値、MAJOR と MINOR
docs/mcp.mdMCP サーバーのセットアップと 2 つのツールスキーマ
docs/accuracy.mdコーパス、信頼度の段階、既知の制限事項
MCP サーバー

semver-checks は Model Context Protocol サーバーとして提供されるため、エージェントはこれをツールとして呼び出せます。

claude mcp add semver-checks -- npx -y semver-checks --mcp

ツールは semver_compare と semver_snapshot の 2 つです。他のクライアント向けのセットアップ方法と、引数スキーマの詳細は docs/mcp.md をご覧ください。

他のツールとの比較

semver-checkssemantic-releasechangesetsnpm-check-updates
入力TypeScript APIコミットメッセージ作者が記述する changesetpackage.json
検出型付き API ルールキーワード照合開発者による宣言バージョン範囲のみ
推奨自動メッセージ形式に基づく変更ごとに手動依存関係の更新のみ

semver-checks はリリースツールではなく、検証レイヤーです。宣言されたバージョン変更が API の変更内容と一致するかを確認するために、semantic-release や changesets と併用してください。

異なる点

ts-semver-checks、[@clerk/break-check](https://www.npmjs.com/package/@clerk/break-check)、[`semvet`](https://github.com/Nithinfgs/semvet) は、それぞれローカルビルドをベースラインと比較します。ts-semver-checks と semvet はコンパイラーの代入可能性を使用します。ts-semver-checks は --expect で想定するバージョンアップを受け取り、Action も MCP サーバーもありません。一方、semvet は package.json で宣言されたバージョンアップを評価します。@clerk/break-check は API Extractor のスナップショットを差分比較し、LLM によるレビュー工程を追加して、package.json で宣言されたバージョンアップを評価し、複数パッケージのモノレポに対応します。

semver-checks は、公開済みの npm リリース同士を直接比較でき(compare pkg@x pkg@y)、.changeset ファイルから宣言されたバージョンアップを読み取り、MCP サーバーを提供し、docs/accuracy.md で精度の数値を公開しています。

仕組み

  1. 抽出:ts-morph を使用して新旧の TypeScript ソースファイルを解析し、型付き API スナップショット(関数、インターフェース、列挙型、クラス、型エイリアス、変数、名前空間)を構築します
  2. 差分比較:2 つのスナップショットをシンボルごとに比較し、追加、削除、シグネチャの変更を検出します
  3. 分類:各差分に major、minor、patch の重要度を割り当てます
  4. レポート:推奨するバージョンアップと変更ごとの詳細を含む、構造化された SemverReport を返します

git ref の比較では、git archive を使用して ref を一時ディレクトリに抽出し、そこで依存関係をインストールした後、ディレクトリをクリーンアップします。npm 仕様の比較では、公開済みの tarball にビルド出力がすでに含まれているため、npm pack でダウンロードして一時ディレクトリに展開し、依存関係はインストールしません。ローカルパスの比較では、デフォルトで何もインストールしません。--install-deps(または installDeps: true)を指定するとこれが上書きされ、ソースの種類にかかわらず両方の側でインストールを実行します。このオプションは、インストールが必要な唯一のケースであるローカルパスの比較のために用意されています。

よくある質問

semver-checks はすべての semver 違反を検出できますか?

いいえ。TypeScript の静的型システムで機械的に検出できる API サーフェスの変更、つまりエクスポートの削除、シグネチャの変更、型の変更、オプション性の変更など、構造上の変更を検出します。動作の変更、ドキュメントの変更、条件付きコンパイルによって隠れた変更は検出しません。パッケージが同じエントリーポイントに対して 異なる ESM と CJS の宣言ファイル(たとえば、相違する import.types と require.types)を公開している場合は、片方のサーフェスしか解析されないため、もう片方のサーフェスに限られた破壊的変更を見逃すことがあります。docs/accuracy.md を参照してください。

誤検出はありますか?

はい。破壊的変更の見逃しを避けるため、重大度を MAJOR と過剰に判定する傾向がありますが、デフォルトの CI ゲートで失敗するのは proven の破壊的変更だけです。パラメーター型と戻り値型の変更には構造的な代入可能性チェックを行うため、パラメーターの型が広くなる変更、戻り値の型が狭くなる変更、readonly T[] と ReadonlyArray<T> のような同等の書き換えでは、誤った MAJOR 判定を回避できます。型エイリアスと変数には、まず正規化されたシリアライズ済みテキストとして比較し、可能な場合に限りプローブで解決済みの型の関係に切り替えるため、保守的な判定となるケースが残っています。具体的なパターンは、既知の制限事項に記載されています。

デフォルトエクスポートに対応していますか?

はい。デフォルトエクスポートはシンボル名 default として抽出され、対応する関数、クラス、または値の宣言と同様に比較されます。

公開済みの npm バージョンと比較できますか?

はい。<package>@<version> 形式の指定を渡すと、semver-checks は npm pack でレジストリからそのリリースをダウンロードし、tarball を展開して、バンドルされた .d.ts 宣言を解析します。

npx semver-checks compare your-package@latest          # published latest vs working tree
npx semver-checks compare [email protected] [email protected]  # two published releases

公開済みの tarball にはコンパイル済みの .d.ts ファイルが含まれる一方、作業ツリーには .ts ソースが含まれるため、型の 表現 は両者で多少異なることがあります(TypeScript は一部の推論された型を宣言ファイル内で具体化します)。削除、追加、シグネチャの変更は確実に検出されますが、同等でも表現が異なる型がいくつか、ノイズの多い差分として表示されることがあります。公開済みの 2 つのリリース(.d.ts 対 .d.ts)を比較すれば、この非対称性を避けられます。

tsconfig.json がなくても使えますか?

ローカルパスまたは git-ref の入力では使えません。これらは TypeScript プロジェクトとして開かれるため、プロジェクトのルート、または package.json の exports フィールドから推定されたルートに tsconfig.json が必要です。公開済みの npm 入力は異なります。tarball に設定ファイルが含まれていない場合は、制約の緩い設定が生成されます。

解析対象のプロジェクトに TypeScript エラーがある場合はどうなりますか?

semver-checks は stderr に最大 5 件のエラーを警告として出力し、処理を続行します。型エラーが API の範囲に影響する場合、結果が不完全になることがあります。完全な診断を表示するには、SEMVER_CHECKS_VERBOSE=1 を設定してください。

エントリーポイントはどのように決定されますか?

semver-checks は次の順序でエントリーファイルを探します。

  1. 指定されている場合は --entry フラグ
  2. package.json の exports['.'] にある宣言ファイル — すべての条件を確認します(types、require/import/node/browser/module/default、ネストされた条件、フォールバック配列)。.d.ts/.d.mts/.d.cts はすべて使用できます。文字列のみの "exports": "./index.js"、またはフラットな条件オブジェクト "exports": { "types": "./index.d.ts", "default": "./index.js" }(. サブパスキーなし)は . エントリーとして扱われるため、types 条件が読み取られます。公開済みパッケージの場合は、.js のターゲットについて、同名の隣接する宣言ファイルも確認されます。. キーのないサブパスのみのマップにはルートエントリーを設定しません(ルートは作成されません)。
  3. package.json のトップレベルにある types または typings フィールド
  4. フォールバックとして、src/index.ts、次に index.ts、最後に一般的なルートの index.d.ts/.d.mts/.d.cts

いずれも解決できない場合は、--entry を明示的に指定してください。

プロジェクトに複数のサブパスを含む "exports" マップがある場合、各サブパスを個別に解決して比較します(複数のエントリーポイントを参照)。

モノレポでも動作しますか?

はい。--entry でパッケージのエントリーファイルを指定するか、そのパッケージのディレクトリから CLI を実行してください。[email protected] 形式のモノレポタグは自動検出で npm spec として解釈されるため、これらの場合は --old-as ref を渡してください。

要件

  • Node.js ^20.0.0 || >=22.0.0(推移的依存関係により Node 21 は除外されており、Node 21 自体もサポート終了です)
  • ローカルパス/git-ref の入力の場合:解析対象のプロジェクトに tsconfig.json と TypeScript ソースファイル(.ts/.tsx)が必要です
  • npm spec の場合:追加の要件はありません。tarball にバンドルされた .d.ts 宣言が解析され、存在しない場合は tsconfig.json が生成されます
デュアルモジュールのサポート

semver-checks には CommonJS ビルドと ES モジュールビルドの両方が含まれています。

// ESM
import { compare } from "semver-checks";

// CJS
const { compare } = require("semver-checks");

コントリビューション

コントリビューションを歓迎します。プルリクエストを送信する前に、CONTRIBUTING.md をお読みください。

ライセンス

MIT。LICENSE を参照してください。

作者

Kyungseop Kim — @kyungseopk1m

コメント

MCP は初めてですか?

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。