refactor(patched-jar): enforce mojmap-only, drop stripPatchedVersion

Author: GhostTypes

CLAUDE.md

@@ -289,8 +289,10 @@ The code should work automatically, but be aware:
 - Compact and efficient
 - Well-supported by tools
 
-### Patched MC JARs (Forge/NeoForge) — opaque version key
-For `decompile_minecraft_version` with `jarPath`, the `version` parameter is treated as an opaque cache-key string (convention: `<mc>-<loader>-<loaderVersion>`). No parsing — the same key flows unchanged through `getDecompiledPath`, the cache DB, the FTS5 index, and every downstream tool. This is why patched MC slots into the existing `decompiled/{version}/{mapping}/` layout with zero new code paths in search/index/compare. `find_mapping` is the one exception: it strips the loader suffix via `stripPatchedVersion` so tinyfile lookups still resolve to the vanilla MC's mapping data.
+### Patched MC JARs (Forge/NeoForge) — opaque version key, mojmap-only
+For `decompile_minecraft_version` with `jarPath`, the `version` parameter is treated as an opaque cache-key string (convention: `<mc>-<loader>-<loaderVersion>`). No parsing — the same key flows unchanged through `getDecompiledPath`, the cache DB, the FTS5 index, and every downstream tool. This is why patched MC slots into the existing `decompiled/{version}/{mapping}/` layout with zero new code paths in search/index/compare.
+
+Forge/NeoForge dev environments (1.17+) are **mojmap-exclusive** — yarn is a Fabric/Quilt mapping with no equivalent in the Forge ecosystem. The schema enforces `mapping === 'mojmap'` whenever `jarPath` is set. `find_mapping` does no special-casing for patched keys: callers wanting a vanilla mojmap↔yarn translation should pass the vanilla MC version directly.
 
 ### Sources-vs-compiled detection (`src/utils/jar-inspector.ts`)
 Deterministic central-directory scan: any `.class` entry → decompile via VineFlower; else any `.java` → extract directly (NFRT/ForgeGradle `-sources.jar` fast path); else error. Mixed JARs always decompile (any `.class` wins). Avoids filename heuristics, which Forge/NeoForge dev artifacts don't reliably follow.
@@ -316,7 +318,7 @@ Deterministic central-directory scan: any `.class` entry → decompile via VineF
 
 ### Phase 1 Tools (Core)
 1. **`get_minecraft_source`** - Get decompiled source for a Minecraft class
-2. **`decompile_minecraft_version`** - Trigger full decompilation of a version. Pass `jarPath` to point at a local Forge/NeoForge **patched** MC JAR (cache key convention: `<mc>-<loader>-<loaderVersion>`, e.g. `1.21.1-neoforge-21.1.72`). Sources JARs (no `.class` entries) are extracted directly; compiled JARs run through VineFlower. `force: true` wipes the decompiled dir, the job row, and the FTS5 index for that (version, mapping).
+2. **`decompile_minecraft_version`** - Trigger full decompilation of a version. Pass `jarPath` to point at a local Forge/NeoForge **patched** MC JAR (cache key convention: `<mc>-<loader>-<loaderVersion>`, e.g. `1.21.1-neoforge-21.1.72`); in this mode `mapping` must be `'mojmap'` (Forge/NeoForge dev environments are mojmap-only post-1.17). Sources JARs (no `.class` entries) are extracted directly; compiled JARs run through VineFlower. `force: true` wipes the decompiled dir, the job row, and the FTS5 index for that (version, mapping).
 3. **`list_minecraft_versions`** - List available and cached versions
 4. **`get_registry_data`** - Get registry data (blocks, items, entities)
 

__tests__/core/patched-version-strip.test.ts

@@ -48,30 +48,36 @@ const GetMinecraftSourceSchema = z.object({
     ),
 });
 
-const DecompileMinecraftVersionSchema = z.object({
-  version: z
-    .string()
-    .describe(
-      'Minecraft version to decompile. When `jarPath` is provided this is treated as an opaque cache key — the conventional schema is `<mc>-<loader>-<loaderVersion>` (e.g., `1.21.1-neoforge-21.1.72`).',
-    ),
-  mapping: z
-    .enum(['yarn', 'mojmap'])
-    .describe(
-      'Mapping type to use. For Forge/NeoForge dev environments (1.17+) this is always `mojmap`.',
-    ),
-  force: z
-    .boolean()
-    .optional()
-    .describe(
-      'Force re-decompilation even if cached. Wipes the decompiled directory, decompile job row, and FTS5 search index for this (version, mapping) so it can be rebuilt cleanly.',
-    ),
-  jarPath: z
-    .string()
-    .optional()
-    .describe(
-      'Optional path to a local Forge/NeoForge patched Minecraft JAR (supports WSL and Windows paths). When set, skips the Mojang download + remap pipeline and decompiles the provided JAR directly. Sources JARs (no .class entries) are extracted directly; compiled JARs are decompiled with VineFlower. The `mapping` parameter is treated as a label only — no remapping is performed.',
-    ),
-});
+const DecompileMinecraftVersionSchema = z
+  .object({
+    version: z
+      .string()
+      .describe(
+        'Minecraft version to decompile. When `jarPath` is provided this is treated as an opaque cache key — the conventional schema is `<mc>-<loader>-<loaderVersion>` (e.g., `1.21.1-neoforge-21.1.72`).',
+      ),
+    mapping: z
+      .enum(['yarn', 'mojmap'])
+      .describe(
+        'Mapping type to use. `yarn` is Fabric/Quilt only. Forge/NeoForge dev environments (1.17+) are mojmap-exclusive — when `jarPath` is provided, this must be `mojmap`.',
+      ),
+    force: z
+      .boolean()
+      .optional()
+      .describe(
+        'Force re-decompilation even if cached. Wipes the decompiled directory, decompile job row, and FTS5 search index for this (version, mapping) so it can be rebuilt cleanly.',
+      ),
+    jarPath: z
+      .string()
+      .optional()
+      .describe(
+        'Optional path to a local Forge/NeoForge patched Minecraft JAR (supports WSL and Windows paths). When set, skips the Mojang download + remap pipeline and decompiles the provided JAR directly. Sources JARs (no .class entries) are extracted directly; compiled JARs are decompiled with VineFlower. No remapping is performed — the JAR is already mojmap-named, which is why `mapping` must be `mojmap` in this mode.',
+      ),
+  })
+  .refine((args) => !args.jarPath || args.mapping === 'mojmap', {
+    message:
+      "Forge/NeoForge patched JARs are mojmap-exclusive (yarn is a Fabric/Quilt mapping with no equivalent in the Forge ecosystem). Set `mapping: 'mojmap'` when passing `jarPath`.",
+    path: ['mapping'],
+  });
 
 const GetRegistryDataSchema = z.object({
   version: z.string().describe('Minecraft version'),
@@ -298,7 +304,7 @@ export const tools = [
           type: 'string',
           enum: ['yarn', 'mojmap'],
           description:
-            'Mapping type to use. For Forge/NeoForge dev environments (1.17+), use `mojmap`.',
+            'Mapping type to use. `yarn` is Fabric/Quilt only. Forge/NeoForge dev environments (1.17+) are mojmap-exclusive — when `jarPath` is provided, this must be `mojmap`.',
         },
         force: {
           type: 'boolean',
@@ -308,7 +314,7 @@ export const tools = [
         jarPath: {
           type: 'string',
           description:
-            'Optional local Forge/NeoForge patched MC JAR path (WSL or Windows). When set, skips download/remap and decompiles (or extracts, if it is a sources JAR) directly. Trusts the user-supplied `mapping` as a label.',
+            'Optional local Forge/NeoForge patched MC JAR path (WSL or Windows). When set, skips download/remap and decompiles (or extracts, if it is a sources JAR) directly. The JAR is already mojmap-named, so `mapping` must be `mojmap`.',
         },
       },
       required: ['version', 'mapping'],

src/server/tools.ts

@@ -279,19 +279,11 @@ export class MappingService {
    *                   mojmap
    */
   async lookupMapping(
-    rawVersion: string,
+    version: string,
     symbol: string,
     sourceMapping: MappingType,
     targetMapping: MappingType,
   ): Promise<MappingLookupResult> {
-    // Strip Forge/NeoForge loader suffix so callers can pass patched-version
-    // strings like "1.21.1-neoforge-21.1.72" without an explicit error. Vanilla
-    // mojmap names are preserved in patched JARs, so this lookup remains valid.
-    const version = stripPatchedVersion(rawVersion);
-    if (version !== rawVersion) {
-      logger.info(`Patched version detected (${rawVersion} → ${version}) for mapping lookup`);
-    }
-
     logger.info(`Looking up mapping: ${symbol} (${sourceMapping} -> ${targetMapping})`);
 
     // Same mapping type - no translation needed
@@ -654,19 +646,6 @@ export class MappingService {
   }
 }
 
-/**
- * Detect a patched-MC version string of the form `<mc>-<loader>-<loaderVersion>`
- * (e.g., `1.21.1-neoforge-21.1.72`, `1.20.1-forge-47.4.0`) and return just the
- * vanilla MC component. Returns the input unchanged if no known loader suffix
- * is present.
- *
- * Exported for testing and reuse by other tools that need vanilla-MC fallback.
- */
-export function stripPatchedVersion(version: string): string {
-  const match = version.match(/^(\d+\.\d+(?:\.\d+)?)-(forge|neoforge|fabric|quilt)-/i);
-  return match ? match[1] : version;
-}
-
 /**
  * Result type for mapping lookups
  */