osv-scanner-mcp 0.1.0

package/dist/test/utils/mavenVersion.test.js

@@ -0,0 +1,185 @@
+import { describe, expect, it } from "vitest";
+import { compareMavenVersions, mavenVersionSeries } from "../../utils/mavenVersion.js";
+function expectEqual(a, b) {
+    expect(compareMavenVersions(a, b), `${a} == ${b}`).toBe(0);
+    expect(compareMavenVersions(b, a), `${b} == ${a}`).toBe(0);
+}
+function expectLess(a, b) {
+    expect(compareMavenVersions(a, b), `${a} < ${b}`).toBeLessThan(0);
+    expect(compareMavenVersions(b, a), `${b} > ${a}`).toBeGreaterThan(0);
+}
+/** 配列内のすべてのペア(i < j)について versions[i] < versions[j] を検証する。 */
+function expectStrictOrder(versions) {
+    for (let i = 0; i < versions.length; i++) {
+        expectEqual(versions[i], versions[i]);
+        for (let j = i + 1; j < versions.length; j++) {
+            expectLess(versions[i], versions[j]);
+        }
+    }
+}
+// Maven本家 ComparableVersionTest のテストコーパス
+describe("compareMavenVersions (Maven本家テストコーパス)", () => {
+    it("修飾子付きバージョンの全順序", () => {
+        expectStrictOrder([
+            "1-alpha2snapshot",
+            "1-alpha2",
+            "1-alpha-123",
+            "1-beta-2",
+            "1-beta123",
+            "1-m2",
+            "1-m11",
+            "1-rc",
+            "1-cr2",
+            "1-rc123",
+            "1-SNAPSHOT",
+            "1",
+            "1-sp",
+            "1-sp2",
+            "1-sp123",
+            "1-abc",
+            "1-def",
+            "1-pom-1",
+            "1-1-snapshot",
+            "1-1",
+            "1-2",
+            "1-123",
+        ]);
+    });
+    it("数値バージョンの全順序", () => {
+        expectStrictOrder([
+            "2.0",
+            "2-1",
+            "2.0.a",
+            "2.0.0.a",
+            "2.0.2",
+            "2.0.123",
+            "2.1.0",
+            "2.1-a",
+            "2.1b",
+            "2.1-c",
+            "2.1-1",
+            "2.1.0.1",
+            "2.2",
+            "2.123",
+            "11.a2",
+            "11.a11",
+            "11.b2",
+            "11.b11",
+            "11.m2",
+            "11.m11",
+            "11",
+            "11.a",
+            "11b",
+            "11c",
+            "11m",
+        ]);
+    });
+    it("末尾ゼロ・区切り表記ゆれの同値", () => {
+        expectEqual("1", "1");
+        expectEqual("1", "1.0");
+        expectEqual("1", "1.0.0");
+        expectEqual("1.0", "1.0.0");
+        expectEqual("1", "1-0");
+        expectEqual("1", "1.0-0");
+        expectEqual("1.0", "1.0-0");
+        // 数字と文字の境界は区切り扱い
+        expectEqual("1a", "1-a");
+        expectEqual("1a", "1.0-a");
+        expectEqual("1a", "1.0.0-a");
+        expectEqual("1.0a", "1.0-a");
+        expectEqual("1.0.0a", "1.0.0-a");
+        expectEqual("1x", "1-x");
+        expectEqual("1x", "1.0-x");
+        expectEqual("1x", "1.0.0-x");
+        expectEqual("1.0x", "1.0-x");
+        expectEqual("1.0.0x", "1.0.0-x");
+        // 先頭・連続セパレータの空トークンはゼロとして補完される
+        expectEqual(".1", "0.1");
+        expectEqual("1..2", "1.0.2");
+        expectEqual("-1", "0-1");
+    });
+    it("修飾子のエイリアスと略記の同値", () => {
+        expectEqual("1ga", "1");
+        expectEqual("1release", "1");
+        expectEqual("1final", "1");
+        expectEqual("1cr", "1rc");
+        // 大文字小文字は区別しない
+        expectEqual("1a1", "1-alpha-1");
+        expectEqual("1b2", "1-beta-2");
+        expectEqual("1m3", "1-milestone-3");
+        expectEqual("1X", "1x");
+        expectEqual("1A", "1a");
+        expectEqual("1B", "1b");
+        expectEqual("1M", "1m");
+        expectEqual("1Ga", "1");
+        expectEqual("1GA", "1");
+        expectEqual("1RELEASE", "1");
+        expectEqual("1release", "1");
+        expectEqual("1RELeaSE", "1");
+        expectEqual("1Final", "1");
+        expectEqual("1FinaL", "1");
+        expectEqual("1FINAL", "1");
+        expectEqual("1Cr", "1Rc");
+        expectEqual("1cR", "1rC");
+        expectEqual("1m3", "1Milestone3");
+        expectEqual("1m3", "1MileStone3");
+        expectEqual("1m3", "1MILESTONE3");
+    });
+    it("基本的な大小関係", () => {
+        expectLess("1", "2");
+        expectLess("1.5", "2");
+        expectLess("1", "2.5");
+        expectLess("1.0", "1.1");
+        expectLess("1.1", "1.2");
+        expectLess("1.0.0", "1.1");
+        expectLess("1.0.1", "1.1");
+        expectLess("1.1", "1.2.0");
+        expectLess("1.0-alpha-1", "1.0");
+        expectLess("1.0-alpha-1", "1.0-alpha-2");
+        expectLess("1.0-alpha-1", "1.0-beta-1");
+        expectLess("1.0-beta-1", "1.0-SNAPSHOT");
+        expectLess("1.0-SNAPSHOT", "1.0");
+        expectLess("1.0-alpha-1-SNAPSHOT", "1.0-alpha-1");
+        expectLess("1.0", "1.0-1");
+        expectLess("1.0-1", "1.0-2");
+        expectLess("1.0.0", "1.0-1");
+        expectLess("2.0-1", "2.0.1");
+        expectLess("2.0.1-klm", "2.0.1-lmn");
+        expectLess("2.0.1", "2.0.1-xyz");
+        expectLess("2.0.1", "2.0.1-123");
+        expectLess("2.0.1-xyz", "2.0.1-123");
+    });
+});
+// このプロジェクト固有の要件(docs/DESIGN_TODO.md 実機確認の実例)
+describe("compareMavenVersions (OSV-Scanner-MCP要件)", () => {
+    it("semverが扱えないMaven特有の接尾辞", () => {
+        expectEqual("2.17.1-RELEASE", "2.17.1");
+        expectEqual("2.17.1.RELEASE", "2.17.1");
+        expectLess("2.17.0", "2.17.1-RELEASE");
+        expectLess("2.17.1-RELEASE", "2.17.2");
+    });
+    it("log4j-coreの複数リリース系統(実スキャンで確認した実例)", () => {
+        // 2.12系バックポート < 2.1x系メインライン < 2.25系
+        expectStrictOrder(["2.12.2", "2.12.4", "2.14.1", "2.15.0", "2.16.0", "2.17.1", "2.25.3", "2.25.4"]);
+    });
+    it("タイムスタンプ形式の大きな数値", () => {
+        expectLess("20040616", "20211215");
+        expectLess("2.4.0", "20040616");
+    });
+});
+describe("mavenVersionSeries", () => {
+    it("major.minorを系統として抽出する", () => {
+        expect(mavenVersionSeries("2.14.1")).toEqual({ major: 2, minor: 14 });
+        expect(mavenVersionSeries("2.25.4")).toEqual({ major: 2, minor: 25 });
+        expect(mavenVersionSeries("1.0-alpha-1")).toEqual({ major: 1, minor: 0 });
+        expect(mavenVersionSeries("2.17.1-RELEASE")).toEqual({ major: 2, minor: 17 });
+    });
+    it("minor省略時は0とみなす", () => {
+        expect(mavenVersionSeries("3")).toEqual({ major: 3, minor: 0 });
+        expect(mavenVersionSeries("3-beta")).toEqual({ major: 3, minor: 0 });
+    });
+    it("数字で始まらないバージョンはnull(系統判定不能)", () => {
+        expect(mavenVersionSeries("alpha")).toBeNull();
+        expect(mavenVersionSeries("")).toBeNull();
+    });
+});

package/dist/test/utils/projectDetector.test.js

@@ -0,0 +1,154 @@
+import { chmod, mkdtemp, mkdir, rm, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterAll, describe, expect, it } from "vitest";
+import { ScanToolError } from "../../errors.js";
+import { detectJavaProject } from "../../utils/projectDetector.js";
+const POM = "<project/>";
+const tempDirs = [];
+async function makeTempDir() {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "osv-mcp-detector-"));
+    tempDirs.push(dir);
+    return dir;
+}
+afterAll(async () => {
+    await Promise.all(tempDirs.map((dir) => rm(dir, { recursive: true, force: true })));
+});
+async function expectScanError(promise, kind) {
+    const error = await promise.then(() => null, (e) => e);
+    expect(error).toBeInstanceOf(ScanToolError);
+    expect(error.kind).toBe(kind);
+}
+describe("detectJavaProject", () => {
+    it("ルート直下のpom.xmlを検出する", async () => {
+        const dir = await makeTempDir();
+        await writeFile(path.join(dir, "pom.xml"), POM);
+        const project = await detectJavaProject(dir);
+        expect(project.manifests).toEqual(["pom.xml"]);
+    });
+    it("サブモジュールのpom.xmlも深さ上限内で検出する", async () => {
+        const dir = await makeTempDir();
+        await writeFile(path.join(dir, "pom.xml"), POM);
+        await mkdir(path.join(dir, "module-a"), { recursive: true });
+        await writeFile(path.join(dir, "module-a", "pom.xml"), POM);
+        await mkdir(path.join(dir, "a", "b", "c", "d"), { recursive: true });
+        await writeFile(path.join(dir, "a", "b", "c", "d", "pom.xml"), POM); // 深さ5: 対象外
+        const project = await detectJavaProject(dir);
+        expect(project.manifests.sort()).toEqual(["module-a/pom.xml", "pom.xml"]);
+    });
+    it("target等のビルド成果物ディレクトリは探索しない", async () => {
+        const dir = await makeTempDir();
+        await mkdir(path.join(dir, "target"), { recursive: true });
+        await writeFile(path.join(dir, "target", "pom.xml"), POM);
+        await expectScanError(detectJavaProject(dir), "no_manifest_found");
+    });
+    it("pom.xmlファイルのパスを直接受け付ける", async () => {
+        const dir = await makeTempDir();
+        const pomPath = path.join(dir, "pom.xml");
+        await writeFile(pomPath, POM);
+        const project = await detectJavaProject(pomPath);
+        expect(project.manifests).toEqual(["pom.xml"]);
+    });
+    it("対応外のファイル指定はエラー", async () => {
+        const dir = await makeTempDir();
+        const filePath = path.join(dir, "readme.txt");
+        await writeFile(filePath, "");
+        await expectScanError(detectJavaProject(filePath), "project_not_found");
+    });
+    it("存在しないパス・空文字はエラー", async () => {
+        await expectScanError(detectJavaProject("/no/such/path/xyz"), "project_not_found");
+        await expectScanError(detectJavaProject("  "), "project_not_found");
+    });
+    it("対応マニフェストが無いディレクトリはno_manifest_found", async () => {
+        const dir = await makeTempDir();
+        await expectScanError(detectJavaProject(dir), "no_manifest_found");
+    });
+    it("gradle.lockfileを検出する(buildscript-gradle.lockfileも)", async () => {
+        const dir = await makeTempDir();
+        await writeFile(path.join(dir, "gradle.lockfile"), "a:b:1.0=runtimeClasspath\n");
+        await writeFile(path.join(dir, "buildscript-gradle.lockfile"), "empty=classpath\n");
+        const project = await detectJavaProject(dir);
+        expect(project.manifests.sort()).toEqual(["buildscript-gradle.lockfile", "gradle.lockfile"]);
+    });
+    it("MavenとGradleの混在プロジェクトは両方のマニフェストを返す", async () => {
+        const dir = await makeTempDir();
+        await writeFile(path.join(dir, "pom.xml"), POM);
+        await mkdir(path.join(dir, "gradle-module"));
+        await writeFile(path.join(dir, "gradle-module", "gradle.lockfile"), "a:b:1.0=runtimeClasspath\n");
+        const project = await detectJavaProject(dir);
+        expect(project.manifests.sort()).toEqual(["gradle-module/gradle.lockfile", "pom.xml"]);
+    });
+    it("build.gradleはあるがlockfileが無い場合は生成手順を案内する", async () => {
+        const dir = await makeTempDir();
+        await writeFile(path.join(dir, "build.gradle"), "plugins { id 'java' }\n");
+        const error = await detectJavaProject(dir).then(() => null, (e) => e);
+        expect(error).toBeInstanceOf(ScanToolError);
+        expect(error.kind).toBe("gradle_lockfile_missing");
+        expect(error.message).toContain("--write-locks");
+    });
+    it("build.gradle.kts / settings.gradle でもGradleプロジェクトとして認識する", async () => {
+        for (const name of ["build.gradle.kts", "settings.gradle"]) {
+            const dir = await makeTempDir();
+            await writeFile(path.join(dir, name), "");
+            await expectScanError(detectJavaProject(dir), "gradle_lockfile_missing");
+        }
+    });
+    it("gradle.lockfileのパスを直接受け付ける", async () => {
+        const dir = await makeTempDir();
+        const lockPath = path.join(dir, "gradle.lockfile");
+        await writeFile(lockPath, "a:b:1.0=runtimeClasspath\n");
+        const project = await detectJavaProject(lockPath);
+        expect(project.manifests).toEqual(["gradle.lockfile"]);
+    });
+    it("build.gradleのパス直接指定はディレクトリとして解決される(lockfile無しなら案内)", async () => {
+        const dir = await makeTempDir();
+        const buildPath = path.join(dir, "build.gradle");
+        await writeFile(buildPath, "");
+        await expectScanError(detectJavaProject(buildPath), "gradle_lockfile_missing");
+        // lockfileがあれば正常に解決される
+        await writeFile(path.join(dir, "gradle.lockfile"), "a:b:1.0=runtimeClasspath\n");
+        const project = await detectJavaProject(buildPath);
+        expect(project.manifests).toEqual(["gradle.lockfile"]);
+    });
+    it("allowedRoot配下なら許可、外ならエラー", async () => {
+        const root = await makeTempDir();
+        const inside = path.join(root, "sub");
+        await mkdir(inside);
+        await writeFile(path.join(inside, "pom.xml"), POM);
+        const project = await detectJavaProject(inside, { allowedRoot: root });
+        expect(project.manifests).toEqual(["pom.xml"]);
+        const outside = await makeTempDir();
+        await writeFile(path.join(outside, "pom.xml"), POM);
+        await expectScanError(detectJavaProject(outside, { allowedRoot: root }), "path_outside_allowed_root");
+    });
+    it("シンボリックリンクは実体パスに解決してから境界チェックする", async () => {
+        const root = await makeTempDir();
+        const outside = await makeTempDir();
+        await writeFile(path.join(outside, "pom.xml"), POM);
+        // root配下のリンクがroot外を指すケース: ../../etc型の抜け道を塞ぐ
+        const link = path.join(root, "sneaky-link");
+        await symlink(outside, link);
+        await expectScanError(detectJavaProject(link, { allowedRoot: root }), "path_outside_allowed_root");
+    });
+    it("権限不足で読めないディレクトリはスキップして探索を続ける", async () => {
+        const dir = await makeTempDir();
+        await writeFile(path.join(dir, "pom.xml"), POM);
+        const locked = path.join(dir, "locked");
+        await mkdir(locked);
+        await chmod(locked, 0o000);
+        try {
+            const project = await detectJavaProject(dir);
+            expect(project.manifests).toEqual(["pom.xml"]);
+        }
+        finally {
+            await chmod(locked, 0o755); // クリーンアップできるよう権限を戻す
+        }
+    });
+    it("pom.xml探索でシンボリックリンクのディレクトリは辿らない", async () => {
+        const dir = await makeTempDir();
+        const elsewhere = await makeTempDir();
+        await writeFile(path.join(elsewhere, "pom.xml"), POM);
+        await symlink(elsewhere, path.join(dir, "linked"));
+        await expectScanError(detectJavaProject(dir), "no_manifest_found");
+    });
+});

package/dist/tools/explainVulnerability.js

@@ -0,0 +1,18 @@
+/**
+ * `explain_vulnerability`ツールのハンドラ。
+ * OSVデータベースAPIから脆弱性レコードを取得し、構造化した詳細を返す。
+ * (スキャナ実行は不要。scan_java_project / suggest_fix の結果に含まれる
+ *  GHSA/CVE IDをそのまま渡せる)
+ */
+import { fetchOsvRecord } from "../osv/osvApi.js";
+import { buildVulnerabilityExplanation } from "../osv/vulnerabilityExplanation.js";
+import { errorResult, jsonResult } from "./toolResult.js";
+export async function handleExplainVulnerability(args, options = {}) {
+    try {
+        const raw = await fetchOsvRecord(args.vulnerability_id, options);
+        return jsonResult(buildVulnerabilityExplanation(raw, args.vulnerability_id.trim()));
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+}

package/dist/tools/scanJavaProject.js

@@ -0,0 +1,23 @@
+/**
+ * `scan_java_project`ツールのハンドラ。
+ * レスポンス形式(成功/エラー)は`toolResult.ts`参照。
+ */
+import { runOsvScan } from "../osv/runner.js";
+import { detectJavaProject } from "../utils/projectDetector.js";
+import { errorResult, jsonResult } from "./toolResult.js";
+export async function handleScanJavaProject(args, options = {}) {
+    try {
+        const project = await detectJavaProject(args.project_path, {
+            allowedRoot: options.allowedRoot,
+        });
+        const report = await runOsvScan(project.projectDir, options);
+        return jsonResult({
+            project_dir: project.projectDir,
+            manifests: project.manifests,
+            ...report,
+        });
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+}

package/dist/tools/suggestFix.js

@@ -0,0 +1,29 @@
+/**
+ * `suggest_fix`ツールのハンドラ。
+ * scan_java_projectと同じスキャンを実行し、脆弱なパッケージごとの
+ * 推奨アップグレードバージョン(3段階Tier)を返す。
+ */
+import { runOsvScan } from "../osv/runner.js";
+import { suggestUpgrades } from "../osv/suggestFix.js";
+import { detectJavaProject } from "../utils/projectDetector.js";
+import { errorResult, jsonResult } from "./toolResult.js";
+export async function handleSuggestFix(args, options = {}) {
+    try {
+        const project = await detectJavaProject(args.project_path, {
+            allowedRoot: options.allowedRoot,
+        });
+        const report = await runOsvScan(project.projectDir, options);
+        const suggestions = suggestUpgrades(report.packages);
+        const unfixedVulnerabilities = suggestions.reduce((sum, s) => sum + s.per_cve_detail.filter((d) => d.tier === "unfixed").length, 0);
+        return jsonResult({
+            project_dir: project.projectDir,
+            manifests: project.manifests,
+            vulnerable_package_count: suggestions.length,
+            unfixed_vulnerability_count: unfixedVulnerabilities,
+            suggestions,
+        });
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+}

package/dist/tools/toolResult.js

@@ -0,0 +1,29 @@
+/**
+ * MCPツール共通のレスポンス整形。
+ *
+ * エラーレスポンス形式(確定済み):
+ * - 失敗時は`isError: true`+`{"error": {"kind", "message", "detail?"}}`のJSONテキスト
+ * - `kind`は`ScanToolError`のkind。LLMクライアントが機械的に分岐できるよう必ず含める
+ * - 予期しない例外は内部情報を漏らさず`internal_error`に丸める
+ */
+import { ScanToolError } from "../errors.js";
+export function jsonResult(payload, isError = false) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+/** 捕捉した例外をエラーレスポンスに変換する。 */
+export function errorResult(error) {
+    if (error instanceof ScanToolError) {
+        return jsonResult({
+            error: {
+                kind: error.kind,
+                message: error.message,
+                ...(error.detail !== undefined && error.detail !== "" ? { detail: error.detail } : {}),
+            },
+        }, true);
+    }
+    // 想定外の例外はスタックトレース等の内部情報をクライアントへ返さない
+    return jsonResult({ error: { kind: "internal_error", message: "予期しないエラーが発生しました" } }, true);
+}

package/dist/utils/mavenVersion.js

@@ -0,0 +1,211 @@
+/**
+ * Maven形式バージョンのコンパレータ。
+ *
+ * npmの`semver`は`2.17.1-RELEASE`のようなMaven特有の接尾辞を正しく扱えないため、
+ * Maven本家の`org.apache.maven.artifact.versioning.ComparableVersion`の
+ * アルゴリズムをTypeScriptに移植したもの。suggest_fixの3段階Tier
+ * フォールバック(docs/DESIGN_TODO.md参照)の前提部品。
+ *
+ * 仕様の要点:
+ * - `.`と`-`でトークン分割。数字⇔文字の境界でも暗黙に分割される
+ * - 修飾子の順序: alpha < beta < milestone < rc < snapshot < ""(通常リリース) < sp
+ *   未知の修飾子はそれらの後に辞書順
+ * - エイリアス: ga / final / release → ""(通常リリース)、cr → rc
+ * - 数字直前の1文字略記: a → alpha, b → beta, m → milestone(例: `1a1` = `1-alpha-1`)
+ * - 末尾のゼロ・空修飾子は正規化で除去(`1.0.0` = `1`、`1-ga` = `1`)
+ */
+const QUALIFIERS = ["alpha", "beta", "milestone", "rc", "snapshot", "", "sp"];
+const ALIASES = new Map([
+    ["ga", ""],
+    ["final", ""],
+    ["release", ""],
+    ["cr", "rc"],
+]);
+/** 修飾子を比較可能なキーに変換する。既知の修飾子は順序インデックス、未知はその後に辞書順で並ぶ。 */
+function comparableQualifier(qualifier) {
+    const index = QUALIFIERS.indexOf(qualifier);
+    return index === -1 ? `${QUALIFIERS.length}-${qualifier}` : String(index);
+}
+function cmp(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+class IntItem {
+    value;
+    // タイムスタンプ形式(例: 20211215)や桁あふれに備えbigintで保持
+    constructor(value) {
+        this.value = value;
+    }
+    isNull() {
+        return this.value === 0n;
+    }
+    compareTo(other) {
+        if (other === null) {
+            return this.isNull() ? 0 : 1;
+        }
+        if (other instanceof IntItem) {
+            return cmp(this.value, other.value);
+        }
+        // 数値トークンは修飾子(StrItem)やサブリスト(ListItem)より常に新しい
+        return 1;
+    }
+}
+class StrItem {
+    value;
+    constructor(raw, followedByDigit) {
+        let v = raw;
+        if (followedByDigit && v.length === 1) {
+            if (v === "a")
+                v = "alpha";
+            else if (v === "b")
+                v = "beta";
+            else if (v === "m")
+                v = "milestone";
+        }
+        this.value = ALIASES.get(v) ?? v;
+    }
+    isNull() {
+        return this.value === "";
+    }
+    compareTo(other) {
+        if (other === null) {
+            // トークン無し = 通常リリース("")との比較
+            return cmp(comparableQualifier(this.value), comparableQualifier(""));
+        }
+        if (other instanceof StrItem) {
+            return cmp(comparableQualifier(this.value), comparableQualifier(other.value));
+        }
+        // IntItemにもListItemにも負ける
+        return -1;
+    }
+}
+class ListItem {
+    items = [];
+    isNull() {
+        return this.items.length === 0;
+    }
+    /** 末尾のnull相当トークン(0、空修飾子、空リスト)を取り除く。 */
+    normalize() {
+        for (let i = this.items.length - 1; i >= 0; i--) {
+            const last = this.items[i];
+            if (last.isNull()) {
+                this.items.splice(i, 1);
+            }
+            else if (!(last instanceof ListItem)) {
+                break;
+            }
+        }
+    }
+    compareTo(other) {
+        if (other === null) {
+            for (const item of this.items) {
+                const result = item.compareTo(null);
+                if (result !== 0)
+                    return result;
+            }
+            return 0;
+        }
+        if (other instanceof IntItem) {
+            return -1;
+        }
+        if (other instanceof StrItem) {
+            return 1;
+        }
+        const otherItems = other.items;
+        const len = Math.max(this.items.length, otherItems.length);
+        for (let i = 0; i < len; i++) {
+            const left = i < this.items.length ? this.items[i] : null;
+            const right = i < otherItems.length ? otherItems[i] : null;
+            // 片側にトークンが無い場合はnull埋めで比較する
+            const result = left === null ? (right === null ? 0 : -right.compareTo(null)) : left.compareTo(right);
+            if (result !== 0)
+                return result;
+        }
+        return 0;
+    }
+}
+function isDigitChar(c) {
+    return c >= "0" && c <= "9";
+}
+function parseItem(digit, buf) {
+    return digit ? new IntItem(BigInt(buf)) : new StrItem(buf, false);
+}
+function parseVersion(version) {
+    const v = version.toLowerCase();
+    const root = new ListItem();
+    let list = root;
+    const stack = [root];
+    let digit = false;
+    let startIndex = 0;
+    const pushSublist = () => {
+        const sub = new ListItem();
+        list.items.push(sub);
+        list = sub;
+        stack.push(sub);
+    };
+    for (let i = 0; i < v.length; i++) {
+        const c = v[i];
+        if (c === ".") {
+            if (i === startIndex) {
+                list.items.push(new IntItem(0n));
+            }
+            else {
+                list.items.push(parseItem(digit, v.slice(startIndex, i)));
+            }
+            startIndex = i + 1;
+        }
+        else if (c === "-") {
+            if (i === startIndex) {
+                list.items.push(new IntItem(0n));
+            }
+            else {
+                list.items.push(parseItem(digit, v.slice(startIndex, i)));
+            }
+            startIndex = i + 1;
+            pushSublist();
+        }
+        else if (isDigitChar(c)) {
+            if (!digit && i > startIndex) {
+                // 文字→数字の境界: 直前の文字列は「数字が続く修飾子」として解釈(a→alpha等)
+                list.items.push(new StrItem(v.slice(startIndex, i), true));
+                startIndex = i;
+                pushSublist();
+            }
+            digit = true;
+        }
+        else {
+            if (digit && i > startIndex) {
+                list.items.push(parseItem(true, v.slice(startIndex, i)));
+                startIndex = i;
+                pushSublist();
+            }
+            digit = false;
+        }
+    }
+    if (v.length > startIndex) {
+        list.items.push(parseItem(digit, v.slice(startIndex)));
+    }
+    while (stack.length > 0) {
+        stack.pop().normalize();
+    }
+    return root;
+}
+/**
+ * Mavenのバージョン優先順位規則で2つのバージョン文字列を比較する。
+ *
+ * @returns a < b なら負、a > b なら正、優先順位が等しければ 0
+ *   (例: `compareMavenVersions("2.17.1-RELEASE", "2.17.1") === 0`)
+ */
+export function compareMavenVersions(a, b) {
+    return parseVersion(a).compareTo(parseVersion(b));
+}
+/**
+ * バージョンが属する「系統」(major.minor)を返す。
+ * 3段階Tierフォールバックの系統判定に使う(例: `2.14.1` → major 2, minor 14)。
+ * 先頭が数字で始まらないバージョンはnull(系統判定不能としてTier 3扱いを想定)。
+ */
+export function mavenVersionSeries(version) {
+    const m = /^(\d+)(?:\.(\d+))?/.exec(version.trim());
+    if (!m)
+        return null;
+    return { major: Number(m[1]), minor: m[2] === undefined ? 0 : Number(m[2]) };
+}