@creeperhost/modlens-mcp 1.6.0

package/dist/tools/version-diff.d.ts

@@ -0,0 +1,113 @@
+import { type ClassInfo } from "../access-flags.js";
+export type ChangeKind = "method_added" | "method_removed" | "method_signature_changed" | "field_added" | "field_removed" | "field_type_changed" | "superclass_changed" | "interface_added" | "interface_removed" | "access_changed";
+export interface MethodChange {
+    name: string;
+    descriptor: string;
+    access: number;
+    accessStr: string;
+}
+export interface MethodSignatureChange {
+    name: string;
+    from: string;
+    to: string;
+    access: number;
+}
+export interface FieldChange {
+    name: string;
+    descriptor: string;
+    simpleType: string;
+    access: number;
+    accessStr: string;
+}
+export interface FieldTypeChange {
+    name: string;
+    from: string;
+    to: string;
+    fromSimple: string;
+    toSimple: string;
+}
+export interface ClassDiff {
+    className: string;
+    superChanged: boolean;
+    superFrom: string | null;
+    superTo: string | null;
+    interfaces: {
+        added: string[];
+        removed: string[];
+    };
+    methods: {
+        added: MethodChange[];
+        removed: MethodChange[];
+        signatureChanged: MethodSignatureChange[];
+    };
+    fields: {
+        added: FieldChange[];
+        removed: FieldChange[];
+        typeChanged: FieldTypeChange[];
+    };
+    hasBreakingChange: boolean;
+    /** Cosine similarity 0–1 between the two versions' source embeddings. null = unavailable. */
+    semanticSimilarity: number | null;
+}
+export interface VersionDiffResult {
+    versionA: string;
+    versionB: string;
+    packages: string[] | null;
+    summary: {
+        classesAdded: number;
+        classesRemoved: number;
+        classesChanged: number;
+        breakingChanges: number;
+    };
+    added: string[];
+    removed: string[];
+    changed: ClassDiff[];
+}
+/**
+ * Returns true if a change of this kind on a member with the given access flags
+ * constitutes a breaking API change.
+ */
+export declare function classifyBreaking(kind: ChangeKind | string, accessFlags: number): boolean;
+/**
+ * Compares two ClassInfo objects and returns a structured ClassDiff.
+ * Does NOT populate semanticSimilarity (caller does that separately).
+ */
+export declare function diffClassIndex(a: ClassInfo, b: ClassInfo): ClassDiff;
+/**
+ * Produces a detailed AST-level diff between two MC versions.
+ *
+ * @param versionA    Earlier version (e.g. "1.20.1")
+ * @param versionB    Later version (e.g. "1.21.1")
+ * @param packages    Optional slash-prefix filter (e.g. ["net/minecraft/world/entity"])
+ * @param maxClasses  Cap on changed-class output (default 200). Does not affect summary counts.
+ * @param force       Skip cache read and recompute (still writes result to cache).
+ * @param semantic    Enrich with Ollama embedding similarity (requires Ollama + index_semantic).
+ * @param cache       When false, skip both reading and writing the DB cache (default true).
+ */
+export declare function diffMcVersionsDetailed(versionA: string, versionB: string, packages?: string[], maxClasses?: number, force?: boolean, semantic?: boolean, cache?: boolean): Promise<VersionDiffResult>;
+export interface ModVersionDiffResult extends VersionDiffResult {
+    modA: {
+        id: number;
+        modId: string;
+        version: string;
+    };
+    modB: {
+        id: number;
+        modId: string;
+        version: string;
+    };
+}
+/**
+ * Produces a detailed AST-level diff between two ingested mod versions.
+ * Uses the same ClassDiff / breaking-change logic as diffMcVersionsDetailed.
+ *
+ * @param dbIdA      DB id of the older mod version
+ * @param dbIdB      DB id of the newer mod version
+ * @param packages   Optional slash-prefix filter (e.g. ["com/example/mymod"])
+ * @param maxClasses Cap on changed-class output (default 200)
+ * @param semantic   Enrich with Ollama embedding similarity (requires mod index_semantic)
+ * @param cache      When true: read from DB cache first, write result to DB after compute
+ * @param force      When true (implies cache=true): skip cache read, recompute, write to cache
+ */
+export declare function diffModVersionsDetailed(dbIdA: number, dbIdB: number, packages?: string[], maxClasses?: number, semantic?: boolean, cache?: boolean, force?: boolean): Promise<ModVersionDiffResult>;
+//# sourceMappingURL=version-diff.d.ts.map

package/dist/tools/version-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-diff.d.ts","sourceRoot":"","sources":["../../src/tools/version-diff.ts"],"names":[],"mappings":"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"}

package/dist/tools/version-diff.js

@@ -0,0 +1,519 @@
+/**
+ * AST-level version diff for Minecraft source.
+ * Uses JarIndex data (bytecode-extracted method/field descriptors) to produce
+ * structured ClassDiff results with breaking-change classification.
+ * Cache layer stores computed diffs in McVersionDiff (Prisma, both PG + SQLite).
+ * Semantic scoring (optional) uses existing Ollama + pgvector/sqlite-vec pipeline.
+ */
+import { createHash } from "crypto";
+import { readFile, writeFile } from "fs/promises";
+import { getMcJarPath, mcPaths } from "../minecraft.js";
+import { indexJar } from "../java-tools.js";
+import { descriptorToSimpleType, accessStr } from "../access-flags.js";
+import { exists, ensureDir } from "../cache.js";
+import { validateVersion } from "../validate.js";
+import { getDb } from "../db.js";
+import { detectBackend } from "../db-backend.js";
+import { ensureMcVersion } from "../repositories/mcVersion.js";
+// ── Breaking change classification ───────────────────────────────────────────
+/**
+ * Returns true if a change of this kind on a member with the given access flags
+ * constitutes a breaking API change.
+ */
+export function classifyBreaking(kind, accessFlags) {
+    const isPublicOrProtected = !!(accessFlags & 0x0001) || !!(accessFlags & 0x0004);
+    switch (kind) {
+        case "method_removed":
+        case "method_signature_changed":
+        case "field_removed":
+        case "field_type_changed":
+            return isPublicOrProtected;
+        case "superclass_changed":
+        case "interface_removed":
+            return true;
+        case "access_changed":
+            return isPublicOrProtected;
+        default:
+            return false;
+    }
+}
+// ── Single-class diff ─────────────────────────────────────────────────────────
+/**
+ * Compares two ClassInfo objects and returns a structured ClassDiff.
+ * Does NOT populate semanticSimilarity (caller does that separately).
+ */
+export function diffClassIndex(a, b) {
+    // Methods: key by (name, descriptor) for exact match
+    const aMethods = new Map();
+    const bMethods = new Map();
+    for (const m of a.methods ?? [])
+        aMethods.set(`${m.name}::${m.descriptor}`, m);
+    for (const m of b.methods ?? [])
+        bMethods.set(`${m.name}::${m.descriptor}`, m);
+    const methodsAdded = [];
+    const methodsRemoved = [];
+    const methodsSigChanged = [];
+    for (const [key, m] of aMethods) {
+        if (!bMethods.has(key))
+            methodsRemoved.push({
+                name: m.name, descriptor: m.descriptor, access: m.access, accessStr: accessStr(m.access),
+            });
+    }
+    for (const [key, m] of bMethods) {
+        if (!aMethods.has(key))
+            methodsAdded.push({
+                name: m.name, descriptor: m.descriptor, access: m.access, accessStr: accessStr(m.access),
+            });
+    }
+    // Signature change heuristic: a method with same name removed in A and added in B,
+    // only when that name has exactly one unmatched entry on each side.
+    const aByName = new Map();
+    const bByName = new Map();
+    for (const m of a.methods ?? []) {
+        const arr = aByName.get(m.name) ?? [];
+        arr.push(m);
+        aByName.set(m.name, arr);
+    }
+    for (const m of b.methods ?? []) {
+        const arr = bByName.get(m.name) ?? [];
+        arr.push(m);
+        bByName.set(m.name, arr);
+    }
+    const removedNames = new Set(methodsRemoved.map((m) => m.name));
+    const addedNames = new Set(methodsAdded.map((m) => m.name));
+    for (const name of removedNames) {
+        if (!addedNames.has(name))
+            continue;
+        const fromList = (aByName.get(name) ?? []).filter((m) => !bMethods.has(`${m.name}::${m.descriptor}`));
+        const toList = (bByName.get(name) ?? []).filter((m) => !aMethods.has(`${m.name}::${m.descriptor}`));
+        // Only collapse to signature change when neither version has multiple overloads for this name.
+        // If A or B has >1 overload, treat each descriptor independently (removed vs added).
+        const totalInA = aByName.get(name)?.length ?? 0;
+        const totalInB = bByName.get(name)?.length ?? 0;
+        if (fromList.length === 1 && toList.length === 1 && totalInA === 1 && totalInB === 1) {
+            methodsSigChanged.push({ name, from: fromList[0].descriptor, to: toList[0].descriptor, access: fromList[0].access });
+            const rIdx = methodsRemoved.findIndex((m) => m.name === name && m.descriptor === fromList[0].descriptor);
+            if (rIdx !== -1)
+                methodsRemoved.splice(rIdx, 1);
+            const aIdx = methodsAdded.findIndex((m) => m.name === name && m.descriptor === toList[0].descriptor);
+            if (aIdx !== -1)
+                methodsAdded.splice(aIdx, 1);
+        }
+    }
+    // Fields: key by name (unique within a class)
+    const aFields = new Map((a.fields ?? []).map((f) => [f.name, f]));
+    const bFields = new Map((b.fields ?? []).map((f) => [f.name, f]));
+    const fieldsAdded = [];
+    const fieldsRemoved = [];
+    const fieldsTypeChanged = [];
+    for (const [name, f] of aFields) {
+        const bf = bFields.get(name);
+        if (!bf) {
+            fieldsRemoved.push({ name, descriptor: f.descriptor, simpleType: descriptorToSimpleType(f.descriptor), access: f.access, accessStr: accessStr(f.access) });
+        }
+        else if (bf.descriptor !== f.descriptor) {
+            fieldsTypeChanged.push({ name, from: f.descriptor, to: bf.descriptor, fromSimple: descriptorToSimpleType(f.descriptor), toSimple: descriptorToSimpleType(bf.descriptor) });
+        }
+    }
+    for (const [name, f] of bFields) {
+        if (!aFields.has(name))
+            fieldsAdded.push({ name, descriptor: f.descriptor, simpleType: descriptorToSimpleType(f.descriptor), access: f.access, accessStr: accessStr(f.access) });
+    }
+    // Superclass / interfaces
+    const superChanged = a.superName !== b.superName;
+    const aIfaces = new Set(a.interfaces ?? []);
+    const bIfaces = new Set(b.interfaces ?? []);
+    const ifacesAdded = [...bIfaces].filter((i) => !aIfaces.has(i));
+    const ifacesRemoved = [...aIfaces].filter((i) => !bIfaces.has(i));
+    // Breaking change flag
+    const hasBreakingChange = methodsRemoved.some((m) => classifyBreaking("method_removed", m.access)) ||
+        methodsSigChanged.some((m) => classifyBreaking("method_signature_changed", m.access)) ||
+        fieldsRemoved.some((f) => classifyBreaking("field_removed", f.access)) ||
+        fieldsTypeChanged.some((f) => {
+            const aField = aFields.get(f.name);
+            return aField ? classifyBreaking("field_type_changed", aField.access) : false;
+        }) ||
+        (superChanged && classifyBreaking("superclass_changed", 0)) ||
+        ifacesRemoved.length > 0;
+    return {
+        className: a.name,
+        superChanged,
+        superFrom: superChanged ? a.superName : null,
+        superTo: superChanged ? b.superName : null,
+        interfaces: { added: ifacesAdded, removed: ifacesRemoved },
+        methods: { added: methodsAdded, removed: methodsRemoved, signatureChanged: methodsSigChanged },
+        fields: { added: fieldsAdded, removed: fieldsRemoved, typeChanged: fieldsTypeChanged },
+        hasBreakingChange,
+        semanticSimilarity: null,
+    };
+}
+// ── Index loading (cached to disk, mirrors vanilla.ts getMcIndex) ─────────────
+const indexMemCache = new Map();
+async function getMcIndexCached(version) {
+    if (indexMemCache.has(version))
+        return indexMemCache.get(version);
+    const cachePath = mcPaths.index(version);
+    if (await exists(cachePath)) {
+        const data = JSON.parse(await readFile(cachePath, "utf8"));
+        indexMemCache.set(version, data);
+        return data;
+    }
+    const jarPath = await getMcJarPath(version);
+    const index = await indexJar(jarPath);
+    await ensureDir(cachePath);
+    await writeFile(cachePath, JSON.stringify(index), "utf8");
+    indexMemCache.set(version, index);
+    return index;
+}
+// ── packages hash helper ──────────────────────────────────────────────────────
+function buildPackagesHash(packages) {
+    if (!packages || packages.length === 0)
+        return "all";
+    return createHash("sha1").update([...packages].sort().join("|")).digest("hex").slice(0, 12);
+}
+// ── DB cache helpers ──────────────────────────────────────────────────────────
+async function readCachedDiff(versionA, versionB, pkgHash) {
+    try {
+        const db = await getDb();
+        const row = await db.mcVersionDiff.findUnique({
+            where: { versionA_versionB_packagesHash: { versionA, versionB, packagesHash: pkgHash } },
+        });
+        if (!row)
+            return null;
+        const raw = detectBackend() === "sqlite" ? JSON.parse(row.result) : row.result;
+        return raw;
+    }
+    catch {
+        return null; // table may not exist yet in older DBs
+    }
+}
+async function writeCachedDiff(versionA, versionB, pkgHash, result) {
+    try {
+        const db = await getDb();
+        const resultData = detectBackend() === "sqlite" ? JSON.stringify(result) : result;
+        await db.mcVersionDiff.upsert({
+            where: { versionA_versionB_packagesHash: { versionA, versionB, packagesHash: pkgHash } },
+            update: { result: resultData },
+            create: { versionA, versionB, packagesHash: pkgHash, result: resultData },
+        });
+    }
+    catch {
+        // Non-fatal — result is still returned even if caching fails
+    }
+}
+// ── Main exported function ────────────────────────────────────────────────────
+/**
+ * Produces a detailed AST-level diff between two MC versions.
+ *
+ * @param versionA    Earlier version (e.g. "1.20.1")
+ * @param versionB    Later version (e.g. "1.21.1")
+ * @param packages    Optional slash-prefix filter (e.g. ["net/minecraft/world/entity"])
+ * @param maxClasses  Cap on changed-class output (default 200). Does not affect summary counts.
+ * @param force       Skip cache read and recompute (still writes result to cache).
+ * @param semantic    Enrich with Ollama embedding similarity (requires Ollama + index_semantic).
+ * @param cache       When false, skip both reading and writing the DB cache (default true).
+ */
+export async function diffMcVersionsDetailed(versionA, versionB, packages, maxClasses = 200, force = false, semantic = false, cache = true) {
+    validateVersion(versionA);
+    validateVersion(versionB);
+    const pkgHash = buildPackagesHash(packages);
+    if (!force && cache) {
+        const cached = await readCachedDiff(versionA, versionB, pkgHash);
+        if (cached) {
+            return { ...cached, changed: cached.changed.slice(0, maxClasses) };
+        }
+    }
+    const [indexA, indexB] = await Promise.all([
+        getMcIndexCached(versionA),
+        getMcIndexCached(versionB),
+    ]);
+    const setA = new Set(Object.keys(indexA.classes));
+    const setB = new Set(Object.keys(indexB.classes));
+    const inScope = (cls) => {
+        if (!packages || packages.length === 0)
+            return true;
+        return packages.some((pkg) => cls.startsWith(pkg));
+    };
+    const added = [...setB].filter((c) => !setA.has(c) && inScope(c)).sort();
+    const removed = [...setA].filter((c) => !setB.has(c) && inScope(c)).sort();
+    const common = [...setA].filter((c) => setB.has(c) && inScope(c));
+    const changed = [];
+    let breakingCount = 0;
+    for (const cls of common) {
+        const diff = diffClassIndex(indexA.classes[cls], indexB.classes[cls]);
+        const isEmpty = diff.methods.added.length === 0 &&
+            diff.methods.removed.length === 0 &&
+            diff.methods.signatureChanged.length === 0 &&
+            diff.fields.added.length === 0 &&
+            diff.fields.removed.length === 0 &&
+            diff.fields.typeChanged.length === 0 &&
+            !diff.superChanged &&
+            diff.interfaces.added.length === 0 &&
+            diff.interfaces.removed.length === 0;
+        if (!isEmpty) {
+            changed.push(diff);
+            if (diff.hasBreakingChange)
+                breakingCount++;
+        }
+    }
+    const result = {
+        versionA, versionB,
+        packages: packages ?? null,
+        summary: {
+            classesAdded: added.length,
+            classesRemoved: removed.length,
+            classesChanged: changed.length,
+            breakingChanges: breakingCount,
+        },
+        added,
+        removed,
+        changed, // full array stored in cache; sliced at return
+    };
+    if (semantic) {
+        result.changed = await enrichWithSemanticScores(result.changed, versionA, versionB);
+    }
+    if (cache) {
+        await writeCachedDiff(versionA, versionB, pkgHash, result);
+    }
+    return { ...result, changed: result.changed.slice(0, maxClasses) };
+}
+// ── Semantic similarity enrichment ───────────────────────────────────────────
+/**
+ * For each ClassDiff, look up embeddings for its class in versionA and versionB.
+ * If both are found, compute cosine similarity and set semanticSimilarity.
+ */
+async function enrichWithSemanticScores(diffs, versionA, versionB) {
+    const [idA, idB] = await Promise.all([
+        ensureMcVersion(versionA),
+        ensureMcVersion(versionB),
+    ]);
+    const backend = detectBackend();
+    const embRepo = backend === "sqlite"
+        ? await import("../repositories/embeddings-sqlite.js")
+        : await import("../repositories/embeddings.js");
+    // Build lookup keys in both slash-notation (JarIndex native) and dot-notation
+    const slashNames = diffs.map((d) => d.className);
+    const dotNames = diffs.map((d) => d.className.replace(/\//g, "."));
+    const allNames = [...new Set([...slashNames, ...dotNames])];
+    // Direct SQL lookup — embeddings are already stored; we just need the row IDs
+    const [mapA, mapB] = await Promise.all([
+        embRepo.findSourceIdsByClassNames(allNames, idA),
+        embRepo.findSourceIdsByClassNames(allNames, idB),
+    ]);
+    const pairs = [];
+    for (let i = 0; i < diffs.length; i++) {
+        const aId = mapA.get(slashNames[i]) ?? mapA.get(dotNames[i]);
+        const bId = mapB.get(slashNames[i]) ?? mapB.get(dotNames[i]);
+        if (aId !== undefined && bId !== undefined)
+            pairs.push({ diffIdx: i, aId, bId });
+    }
+    // Batch all similarity computations in one DB round-trip
+    const simMap = await batchSimilarities(pairs, backend, "mc_source_files");
+    // Assign scores back
+    const enriched = diffs.map((d) => ({ ...d, semanticSimilarity: null }));
+    for (const { diffIdx, aId, bId } of pairs) {
+        enriched[diffIdx].semanticSimilarity = simMap.get(`${aId}:${bId}`) ?? null;
+    }
+    return enriched;
+}
+/**
+ * Batch-compute cosine similarities for multiple id pairs against a source table.
+ * SQLite: opens ONE connection and fetches all needed embeddings in a single query.
+ * PG: single unnest-based JOIN query.
+ * Returns a Map keyed by "aId:bId".
+ */
+async function batchSimilarities(pairs, backend, table) {
+    const out = new Map();
+    if (pairs.length === 0)
+        return out;
+    if (backend !== "sqlite") {
+        const db = await getDb();
+        const aIds = pairs.map((p) => p.aId);
+        const bIds = pairs.map((p) => p.bId);
+        const rows = await db.$queryRawUnsafe(`SELECT p.a_id, p.b_id, (1 - (a.embedding <=> b.embedding))::float AS sim
+             FROM unnest($1::int[], $2::int[]) AS p(a_id, b_id)
+             JOIN ${table} a ON a.id = p.a_id AND a.embedding IS NOT NULL
+             JOIN ${table} b ON b.id = p.b_id AND b.embedding IS NOT NULL`, aIds, bIds);
+        for (const { a_id, b_id, sim } of rows)
+            out.set(`${a_id}:${b_id}`, sim);
+    }
+    else {
+        const Database = (await import("better-sqlite3")).default;
+        const url = process.env.DATABASE_URL ?? "";
+        const dbPath = url.replace(/^file:\/\//, "").replace(/^file:/, "");
+        const db = new Database(dbPath, { readonly: true });
+        const allIds = [...new Set(pairs.flatMap((p) => [p.aId, p.bId]))];
+        const placeholders = allIds.map(() => "?").join(",");
+        const rows = db.prepare(`SELECT id, embedding FROM ${table} WHERE id IN (${placeholders})`)
+            .all(...allIds);
+        db.close();
+        const embMap = new Map(rows.map((r) => [r.id, r.embedding]));
+        for (const { aId, bId } of pairs) {
+            const ea = embMap.get(aId);
+            const eb = embMap.get(bId);
+            out.set(`${aId}:${bId}`, ea && eb ? cosineSimilarityBlob(ea, eb) : null);
+        }
+    }
+    return out;
+}
+function cosineSimilarityBlob(a, b) {
+    const len = Math.min(a.length, b.length) >> 2;
+    let dot = 0, normA = 0, normB = 0;
+    for (let i = 0; i < len; i++) {
+        const va = a.readFloatLE(i * 4);
+        const vb = b.readFloatLE(i * 4);
+        dot += va * vb;
+        normA += va * va;
+        normB += vb * vb;
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+}
+// ── Mod diff DB cache helpers ─────────────────────────────────────────────────
+async function readCachedModDiff(dbIdA, dbIdB, pkgHash) {
+    try {
+        const db = await getDb();
+        const row = await db.modVersionDiff.findUnique({
+            where: { modDbIdA_modDbIdB_packagesHash: { modDbIdA: dbIdA, modDbIdB: dbIdB, packagesHash: pkgHash } },
+        });
+        if (!row)
+            return null;
+        const raw = detectBackend() === "sqlite" ? JSON.parse(row.result) : row.result;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeCachedModDiff(dbIdA, dbIdB, pkgHash, result) {
+    try {
+        const db = await getDb();
+        const resultData = detectBackend() === "sqlite" ? JSON.stringify(result) : result;
+        await db.modVersionDiff.upsert({
+            where: { modDbIdA_modDbIdB_packagesHash: { modDbIdA: dbIdA, modDbIdB: dbIdB, packagesHash: pkgHash } },
+            update: { result: resultData },
+            create: { modDbIdA: dbIdA, modDbIdB: dbIdB, packagesHash: pkgHash, result: resultData },
+        });
+    }
+    catch {
+        // Non-fatal
+    }
+}
+/**
+ * Produces a detailed AST-level diff between two ingested mod versions.
+ * Uses the same ClassDiff / breaking-change logic as diffMcVersionsDetailed.
+ *
+ * @param dbIdA      DB id of the older mod version
+ * @param dbIdB      DB id of the newer mod version
+ * @param packages   Optional slash-prefix filter (e.g. ["com/example/mymod"])
+ * @param maxClasses Cap on changed-class output (default 200)
+ * @param semantic   Enrich with Ollama embedding similarity (requires mod index_semantic)
+ * @param cache      When true: read from DB cache first, write result to DB after compute
+ * @param force      When true (implies cache=true): skip cache read, recompute, write to cache
+ */
+export async function diffModVersionsDetailed(dbIdA, dbIdB, packages, maxClasses = 200, semantic = false, cache = false, force = false) {
+    const { findModById } = await import("../repositories/mod.js");
+    const [modA, modB] = await Promise.all([findModById(dbIdA), findModById(dbIdB)]);
+    if (!modA)
+        throw new Error(`Mod #${dbIdA} not found`);
+    if (!modB)
+        throw new Error(`Mod #${dbIdB} not found`);
+    const useCache = cache || force;
+    const pkgHash = buildPackagesHash(packages);
+    if (useCache && !force) {
+        const cached = await readCachedModDiff(dbIdA, dbIdB, pkgHash);
+        if (cached) {
+            return { ...cached, changed: cached.changed.slice(0, maxClasses) };
+        }
+    }
+    const [indexA, indexB] = await Promise.all([
+        indexJar(modA.jarPath),
+        indexJar(modB.jarPath),
+    ]);
+    const setA = new Set(Object.keys(indexA.classes));
+    const setB = new Set(Object.keys(indexB.classes));
+    const inScope = (cls) => {
+        if (!packages || packages.length === 0)
+            return true;
+        return packages.some((pkg) => cls.startsWith(pkg));
+    };
+    const added = [...setB].filter((c) => !setA.has(c) && inScope(c)).sort();
+    const removed = [...setA].filter((c) => !setB.has(c) && inScope(c)).sort();
+    const common = [...setA].filter((c) => setB.has(c) && inScope(c));
+    const changed = [];
+    let breakingCount = 0;
+    for (const cls of common) {
+        const diff = diffClassIndex(indexA.classes[cls], indexB.classes[cls]);
+        const isEmpty = diff.methods.added.length === 0 &&
+            diff.methods.removed.length === 0 &&
+            diff.methods.signatureChanged.length === 0 &&
+            diff.fields.added.length === 0 &&
+            diff.fields.removed.length === 0 &&
+            diff.fields.typeChanged.length === 0 &&
+            !diff.superChanged &&
+            diff.interfaces.added.length === 0 &&
+            diff.interfaces.removed.length === 0;
+        if (!isEmpty) {
+            changed.push(diff);
+            if (diff.hasBreakingChange)
+                breakingCount++;
+        }
+    }
+    const base = {
+        versionA: modA.version,
+        versionB: modB.version,
+        packages: packages ?? null,
+        summary: {
+            classesAdded: added.length,
+            classesRemoved: removed.length,
+            classesChanged: changed.length,
+            breakingChanges: breakingCount,
+        },
+        added,
+        removed,
+        changed, // full array stored in cache; sliced at return
+    };
+    const result = {
+        ...base,
+        modA: { id: dbIdA, modId: modA.modId, version: modA.version },
+        modB: { id: dbIdB, modId: modB.modId, version: modB.version },
+    };
+    if (semantic) {
+        result.changed = await enrichModWithSemanticScores(result.changed, dbIdA, dbIdB);
+    }
+    if (useCache) {
+        await writeCachedModDiff(dbIdA, dbIdB, pkgHash, result);
+    }
+    return { ...result, changed: result.changed.slice(0, maxClasses) };
+}
+/**
+ * Semantic similarity enrichment for mod source files.
+ * Uses mod_source_files embeddings (mod index_semantic must have been run first).
+ */
+async function enrichModWithSemanticScores(diffs, dbIdA, dbIdB) {
+    const backend = detectBackend();
+    const embRepo = backend === "sqlite"
+        ? await import("../repositories/embeddings-sqlite.js")
+        : await import("../repositories/embeddings.js");
+    const slashNames = diffs.map((d) => d.className);
+    const dotNames = diffs.map((d) => d.className.replace(/\//g, "."));
+    const allNames = [...new Set([...slashNames, ...dotNames])];
+    const [mapA, mapB] = await Promise.all([
+        embRepo.findModSourceIdsByClassNames(allNames, dbIdA),
+        embRepo.findModSourceIdsByClassNames(allNames, dbIdB),
+    ]);
+    const pairs = [];
+    for (let i = 0; i < diffs.length; i++) {
+        const aId = mapA.get(slashNames[i]) ?? mapA.get(dotNames[i]);
+        const bId = mapB.get(slashNames[i]) ?? mapB.get(dotNames[i]);
+        if (aId !== undefined && bId !== undefined)
+            pairs.push({ diffIdx: i, aId, bId });
+    }
+    const simMap = await batchSimilarities(pairs, backend, "mod_source_files");
+    const enriched = diffs.map((d) => ({ ...d, semanticSimilarity: null }));
+    for (const { diffIdx, aId, bId } of pairs) {
+        enriched[diffIdx].semanticSimilarity = simMap.get(`${aId}:${bId}`) ?? null;
+    }
+    return enriched;
+}
+//# sourceMappingURL=version-diff.js.map