semver-checks について
semver-checksはTypeScript宣言の変更を分析し、セマンティックバージョンの更新幅を提案してAPIの破壊的変更を検出します。TypeScriptパッケージのメンテナー向けで、CLI、GitHub Action、MCPからリリースを検証できます。
主な機能
- 01TypeScript宣言の比較
- 02APIを壊す型変更の検出
- 03SemVerの更新幅を提案
- 04npm指定、参照、パスの比較
- 05CIやプルリクエスト向けレポート
活用シーン
- 01公開前にパッケージ変更を確認
- 02プルリクエストで確実な破壊を検出
- 03宣言したリリース更新幅を検証
- 04リリース間のAPI変更を確認
MCP 対応
MCPサーバーはバージョン比較用の`semver_compare`ツールを公開します。このツールでは`old`の明示が必要で、CLIのデフォルト比較はMCPでは利用できません。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
ツール
2掲載時のツール一覧 · 1 週間前に更新
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
| new | string | いいえ | 新しいバージョン:ファイルシステムパス、git ref、または npm spec。デフォルトは現在のディレクトリです。 |
| old | string | はい | 古いバージョン:ファイルシステムパス、git ref(タグ、ブランチ、commit SHA)、または npm spec。既存のパスではない "name@version" は npm として読み取られます(例:"[email protected]"、"lodash@latest")。明示するには "npm:" を先頭に付けます。 |
| entry | any | いいえ | プロジェクトルートからの相対パスで指定するエントリーファイル(例:"src/index.ts")。エントリーポイントが複数あるパッケージでは、配列またはカンマ区切りの文字列を渡してください。省略した場合は package.json から自動検出されます。 |
| newAs | enum | いいえ | "new" をファイルシステムパス、git ref、または npm spec として強制的に扱います。"ref" は "git" の有効な別名です。path | git | ref | npm |
| oldAs | enum | いいえ | "old" をファイルシステムパス、git ref、または npm spec として強制的に扱います。"ref" は "git" の有効な別名です。自動検出で入力が誤った種類として読み取られる場合のみ必要です。たとえば "[email protected]" のような形式の monorepo タグが該当します。path | git | ref | npm |
| declared | enum | いいえ | このリリースが宣言する更新種別。"auto" を指定すると、.changeset/*.md から読み取り、次に 2 つの package.json のバージョンを読み取ります。レポートに "declaration" 判定が追加されます。確認済みの破壊的変更が宣言内容より重大な場合は "mismatch"、変更内容が宣言より大きな更新を求める場合は "review"、それ以外は "ok" です。"auto" で読み取る対象が見つからない場合は、合格を報告せずエラーになります。major | minor | patch | none | auto |
| maxChanges | integer | いいえ | 含める変更の数(デフォルトは 50)。変更は、確認済みの破壊的変更、追加、レビューのみの項目の順に並びます。そのため、上限に達すると、対応の優先度が最も低い末尾の項目が省かれます。`summary` は常にすべての変更をカウントし、`omitted` フィールドには省略された内容と、すべて取得するために指定すべき数が報告されます。 |
| installDeps | boolean | いいえ | 分析前に依存関係をインストールします(`node_modules` がない場合にローカルパスを扱うために必要です)。 |
詳細
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-as | old を path、git、または npm として読み込むよう指定します。[email protected] のようなモノレポタグで必要です。自動検出では、この形式は npm の指定として読み込まれるためです | (自動検出) |
new-as | new を path、git、または npm として読み込むよう指定します | (自動検出) |
install-deps | ソースの種類にかかわらず、解析前に両方の依存関係をインストールします。ローカルパスの場合に必要です。git ref の場合は自動的にインストールされます | false |
format | text、json、markdown、または github | github |
strict | **確実な(証明された)**破壊的変更がある場合にステップを失敗させます(終了コード 1) | false |
strict-review | レビューのみ(ヒューリスティック)によるものを含む、あらゆる破壊的変更がある場合にステップを失敗させます(終了コード 1) | false |
declared | このリリースで宣言するバージョンアップ:major、minor、patch、none、または auto。証明された破壊的変更を過小評価している場合にステップを失敗させ、strict より優先されます | (無効) |
comment | レポートをコメントとして PR に投稿し、後続のプッシュで更新します(format: markdown を強制) | false |
token | コメント投稿に使用するトークン。複合アクションでは secrets コンテキストを読み取れないため、渡す必要があります | ${{ github.token }} |
version | npx 経由で実行する 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 件) | 保証できること |
|---|---|---|---|
--strict | proven の 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.md | compare と snapshot のすべてのフラグ、終了コード、出力形式、--declared の判定表 |
| docs/change-rules.md | すべての ChangeKind 値、MAJOR と MINOR |
| docs/mcp.md | MCP サーバーのセットアップと 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-checks | semantic-release | changesets | npm-check-updates | |
|---|---|---|---|---|
| 入力 | TypeScript API | コミットメッセージ | 作者が記述する changeset | package.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 で精度の数値を公開しています。
仕組み
- 抽出:ts-morph を使用して新旧の TypeScript ソースファイルを解析し、型付き API スナップショット(関数、インターフェース、列挙型、クラス、型エイリアス、変数、名前空間)を構築します
- 差分比較:2 つのスナップショットをシンボルごとに比較し、追加、削除、シグネチャの変更を検出します
- 分類:各差分に
major、minor、patchの重要度を割り当てます - レポート:推奨するバージョンアップと変更ごとの詳細を含む、構造化された
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 は次の順序でエントリーファイルを探します。
- 指定されている場合は
--entryフラグ 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のターゲットについて、同名の隣接する宣言ファイルも確認されます。.キーのないサブパスのみのマップにはルートエントリーを設定しません(ルートは作成されません)。package.jsonのトップレベルにあるtypesまたはtypingsフィールド- フォールバックとして、
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
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。