@adhisang/minecraft-modding-mcp 4.0.0 → 4.1.1

package/dist/source/shared-utils.js

@@ -0,0 +1,55 @@
+import { access } from "node:fs/promises";
+import { buildSuggestedCall } from "../build-suggested-call.js";
+import { ERROR_CODES, createError } from "../errors.js";
+export function normalizePathStyle(path) {
+    return path.replaceAll("\\", "/");
+}
+export function normalizeOptionalString(value) {
+    if (value == null) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+export function normalizeMapping(mapping) {
+    if (mapping == null) {
+        return "obfuscated";
+    }
+    if (mapping === "obfuscated" ||
+        mapping === "mojang" ||
+        mapping === "intermediary" ||
+        mapping === "yarn") {
+        return mapping;
+    }
+    throw createError({
+        code: ERROR_CODES.MAPPING_UNAVAILABLE,
+        message: `Unsupported mapping "${mapping}".`,
+        details: {
+            mapping,
+            nextAction: "Try mapping=obfuscated which is always available.",
+            ...buildSuggestedCall({ tool: "resolve-artifact", params: { mapping: "obfuscated" } })
+        }
+    });
+}
+export async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function dedupeQualityFlags(qualityFlags) {
+    const seen = new Set();
+    const deduped = [];
+    for (const qualityFlag of qualityFlags) {
+        if (seen.has(qualityFlag)) {
+            continue;
+        }
+        seen.add(qualityFlag);
+        deduped.push(qualityFlag);
+    }
+    return deduped;
+}
+//# sourceMappingURL=shared-utils.js.map

package/dist/source/state.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Mutable per-instance state shared across SourceService domain modules
+ * (cache metrics, indexer, binary remap). Wrapped in a small class so
+ * sibling modules can read and reassign fields without dropping `private`
+ * on every individual member of `SourceService`.
+ */
+import { LruList } from "../lru-list.js";
+export declare class SourceServiceState {
+    cacheTotalContentBytes: number;
+    readonly remappedJarBytes: Map<string, number>;
+    /**
+     * In-flight binary-remap jobs keyed by remapped jar path so concurrent
+     * resolveArtifact calls for the same artifactId share a single
+     * tiny-remapper run.
+     */
+    readonly inflightRemaps: Map<string, Promise<string>>;
+    /**
+     * Process-local artifact ingest jobs keyed by artifactId. This collapses
+     * concurrent class source/member lookups inside one MCP server process.
+     */
+    readonly inflightArtifactIngests: Map<string, Promise<void>>;
+    readonly lru: LruList<{
+        totalContentBytes: number;
+        updatedAt: string;
+    }>;
+}

package/dist/source/state.js

@@ -0,0 +1,24 @@
+/**
+ * Mutable per-instance state shared across SourceService domain modules
+ * (cache metrics, indexer, binary remap). Wrapped in a small class so
+ * sibling modules can read and reassign fields without dropping `private`
+ * on every individual member of `SourceService`.
+ */
+import { LruList } from "../lru-list.js";
+export class SourceServiceState {
+    cacheTotalContentBytes = 0;
+    remappedJarBytes = new Map();
+    /**
+     * In-flight binary-remap jobs keyed by remapped jar path so concurrent
+     * resolveArtifact calls for the same artifactId share a single
+     * tiny-remapper run.
+     */
+    inflightRemaps = new Map();
+    /**
+     * Process-local artifact ingest jobs keyed by artifactId. This collapses
+     * concurrent class source/member lookups inside one MCP server process.
+     */
+    inflightArtifactIngests = new Map();
+    lru = new LruList();
+}
+//# sourceMappingURL=state.js.map

package/dist/source/symbol-resolver.d.ts

@@ -0,0 +1,3 @@
+import type { SourceService } from "../source-service.js";
+import type { ResolveWorkspaceSymbolInput, ResolveWorkspaceSymbolOutput } from "../source-service.js";
+export declare function resolveWorkspaceSymbol(svc: SourceService, input: ResolveWorkspaceSymbolInput): Promise<ResolveWorkspaceSymbolOutput>;

package/dist/source/symbol-resolver.js

@@ -0,0 +1,212 @@
+import { ERROR_CODES, createError } from "../errors.js";
+export async function resolveWorkspaceSymbol(svc, input) {
+    const projectPath = input.projectPath?.trim();
+    const version = input.version?.trim();
+    const kind = input.kind;
+    const name = input.name?.trim();
+    const owner = input.owner?.trim();
+    const descriptor = input.descriptor?.trim();
+    if (!projectPath || !version || !name) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: "projectPath, version, and name must be non-empty strings.",
+            details: {
+                projectPath: input.projectPath,
+                version: input.version,
+                name: input.name
+            }
+        });
+    }
+    if (kind !== "class" && kind !== "field" && kind !== "method") {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: `Unsupported symbol kind "${kind}".`,
+            details: { kind }
+        });
+    }
+    if (kind === "class") {
+        if (owner) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "owner is not allowed when kind=class. Use name as FQCN.",
+                details: { owner: input.owner, name: input.name }
+            });
+        }
+        if (descriptor) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "descriptor is not allowed when kind=class.",
+                details: { descriptor: input.descriptor }
+            });
+        }
+    }
+    else if (!owner) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: "owner is required when kind is field or method.",
+            details: { kind, owner: input.owner }
+        });
+    }
+    if (kind === "field" && descriptor) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: "descriptor is not allowed when kind=field.",
+            details: { descriptor: input.descriptor }
+        });
+    }
+    if (kind === "method" && !descriptor) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: "descriptor is required when kind=method."
+        });
+    }
+    const querySymbol = kind === "class"
+        ? {
+            kind,
+            name: name.replace(/\//g, "."),
+            symbol: name.replace(/\//g, ".")
+        }
+        : {
+            kind,
+            name,
+            owner: owner?.replace(/\//g, "."),
+            descriptor: kind === "method" ? descriptor : undefined,
+            symbol: `${owner?.replace(/\//g, ".")}.${name}${kind === "method" ? descriptor : ""}`
+        };
+    const sourcePriorityApplied = input.sourcePriority ?? svc.config.mappingSourcePriority;
+    const workspaceDetection = await svc.workspaceMappingService.detectCompileMapping({
+        projectPath
+    });
+    const warnings = [...workspaceDetection.warnings];
+    if (!workspaceDetection.resolved || !workspaceDetection.mappingApplied) {
+        return {
+            querySymbol,
+            mappingContext: {
+                version,
+                sourceMapping: input.sourceMapping,
+                sourcePriorityApplied
+            },
+            resolved: false,
+            status: "mapping_unavailable",
+            candidates: [],
+            candidateCount: 0,
+            workspaceDetection,
+            warnings
+        };
+    }
+    const mappingApplied = workspaceDetection.mappingApplied;
+    if (kind === "method") {
+        const methodOwner = owner;
+        const methodDescriptor = descriptor;
+        const exact = await svc.mappingService.resolveMethodMappingExact({
+            version,
+            owner: methodOwner,
+            name,
+            descriptor: methodDescriptor,
+            sourceMapping: input.sourceMapping,
+            targetMapping: mappingApplied,
+            sourcePriority: input.sourcePriority,
+            maxCandidates: input.maxCandidates
+        });
+        return {
+            ...exact,
+            workspaceDetection,
+            warnings: [...warnings, ...exact.warnings]
+        };
+    }
+    if (kind === "class") {
+        const className = name.replace(/\//g, ".");
+        const matrix = await svc.mappingService.getClassApiMatrix({
+            version,
+            className,
+            classNameMapping: input.sourceMapping,
+            includeKinds: ["class"],
+            sourcePriority: input.sourcePriority
+        });
+        const resolvedClass = matrix.classIdentity[mappingApplied];
+        if (!resolvedClass) {
+            return {
+                querySymbol,
+                mappingContext: {
+                    version,
+                    sourceMapping: input.sourceMapping,
+                    targetMapping: mappingApplied,
+                    sourcePriorityApplied
+                },
+                resolved: false,
+                status: "not_found",
+                candidates: [],
+                candidateCount: 0,
+                workspaceDetection,
+                warnings: [...warnings, ...matrix.warnings]
+            };
+        }
+        const normalizedClass = resolvedClass.replace(/\//g, ".");
+        const resolvedSymbol = {
+            kind: "class",
+            name: normalizedClass,
+            symbol: normalizedClass
+        };
+        const resolvedCandidate = {
+            ...resolvedSymbol,
+            matchKind: "exact",
+            confidence: 1
+        };
+        return {
+            querySymbol,
+            mappingContext: {
+                version,
+                sourceMapping: input.sourceMapping,
+                targetMapping: mappingApplied,
+                sourcePriorityApplied
+            },
+            resolved: true,
+            status: "resolved",
+            resolvedSymbol,
+            candidates: [resolvedCandidate],
+            candidateCount: 1,
+            workspaceDetection,
+            warnings: [...warnings, ...matrix.warnings]
+        };
+    }
+    // By this point the method and class branches have already returned; only the field
+    // branch reaches the generic findMapping fallthrough.
+    const mapped = await svc.mappingService.findMapping({
+        version,
+        kind,
+        name,
+        owner,
+        descriptor,
+        sourceMapping: input.sourceMapping,
+        targetMapping: mappingApplied,
+        sourcePriority: input.sourcePriority,
+        maxCandidates: input.maxCandidates
+    });
+    const filtered = mapped.candidates.filter((candidate) => candidate.kind === kind);
+    let status;
+    if (mapped.status === "mapping_unavailable") {
+        status = "mapping_unavailable";
+    }
+    else if (filtered.length === 1) {
+        status = "resolved";
+    }
+    else if (filtered.length > 1) {
+        status = "ambiguous";
+    }
+    else {
+        status = "not_found";
+    }
+    return {
+        querySymbol: mapped.querySymbol,
+        mappingContext: mapped.mappingContext,
+        resolved: status === "resolved",
+        status,
+        resolvedSymbol: status === "resolved" ? filtered[0] : undefined,
+        candidates: filtered,
+        candidateCount: mapped.candidateCount,
+        candidatesTruncated: mapped.candidatesTruncated,
+        workspaceDetection,
+        warnings: [...warnings, ...mapped.warnings]
+    };
+}
+//# sourceMappingURL=symbol-resolver.js.map

package/dist/source/validate-mixin/pipeline/mapping-health.d.ts

@@ -0,0 +1,3 @@
+import type { SourceService } from "../../../source-service.js";
+import type { MutableMixinPipelineContext } from "../pipeline-context.js";
+export declare function runMappingHealthStage(svc: SourceService, ctx: MutableMixinPipelineContext): Promise<void>;

package/dist/source/validate-mixin/pipeline/mapping-health.js

@@ -0,0 +1,41 @@
+import { existsSync } from "node:fs";
+export async function runMappingHealthStage(svc, ctx) {
+    const mappingHealthStartedAt = await ctx.enterStage("mapping-health");
+    try {
+        const health = await svc.mappingService.checkMappingHealth({
+            version: ctx.version,
+            requestedMapping: ctx.requestedMapping,
+            sourcePriority: ctx.currentSourcePriority
+        });
+        const jarAvailable = existsSync(ctx.jarPath);
+        ctx.healthReport = {
+            jarAvailable,
+            jarPath: ctx.jarPath,
+            mojangMappingsAvailable: health.mojangMappingsAvailable,
+            tinyMappingsAvailable: health.tinyMappingsAvailable,
+            memberRemapAvailable: health.memberRemapAvailable,
+            overallHealthy: jarAvailable && health.mojangMappingsAvailable,
+            degradations: [
+                ...(jarAvailable ? [] : ["Game jar not found."]),
+                ...health.degradations
+            ]
+        };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        ctx.healthReport = {
+            jarAvailable: existsSync(ctx.jarPath),
+            jarPath: ctx.jarPath,
+            mojangMappingsAvailable: false,
+            tinyMappingsAvailable: false,
+            memberRemapAvailable: false,
+            overallHealthy: false,
+            degradations: [`Mapping health probe failed: ${reason}`]
+        };
+    }
+    if (ctx.testHooks?.afterMappingHealth) {
+        await ctx.testHooks.afterMappingHealth();
+    }
+    ctx.checkPreParseBudget("mapping-health", mappingHealthStartedAt, ctx.stageBudgets.mappingHealth);
+}
+//# sourceMappingURL=mapping-health.js.map

package/dist/source/validate-mixin/pipeline/parse.d.ts

@@ -0,0 +1,2 @@
+import type { MutableMixinPipelineContext } from "../pipeline-context.js";
+export declare function runParseStage(ctx: MutableMixinPipelineContext): Promise<void>;

package/dist/source/validate-mixin/pipeline/parse.js

@@ -0,0 +1,10 @@
+import { parseMixinSource } from "../../../mixin-parser.js";
+export async function runParseStage(ctx) {
+    const parseStartedAt = await ctx.enterStage("parse");
+    ctx.parsed = parseMixinSource(ctx.source);
+    if (ctx.testHooks?.afterParse) {
+        await ctx.testHooks.afterParse();
+    }
+    ctx.checkPreParseBudget("parse", parseStartedAt, ctx.stageBudgets.parse);
+}
+//# sourceMappingURL=parse.js.map

package/dist/source/validate-mixin/pipeline/resolve.d.ts

@@ -0,0 +1,3 @@
+import type { SourceService } from "../../../source-service.js";
+import { type MutableMixinPipelineContext } from "../pipeline-context.js";
+export declare function runResolveStage(svc: SourceService, ctx: MutableMixinPipelineContext): Promise<void>;

package/dist/source/validate-mixin/pipeline/resolve.js

@@ -0,0 +1,78 @@
+import { normalizeMapping } from "../pipeline-context.js";
+export async function runResolveStage(svc, ctx) {
+    const resolveStartedAt = await ctx.enterStage("resolve");
+    let detectedMapping;
+    if ((!ctx.input.mapping || ctx.input.preferProjectMapping) && ctx.input.projectPath) {
+        try {
+            const detection = await svc.workspaceMappingService.detectCompileMapping({ projectPath: ctx.input.projectPath });
+            if (detection.resolved && detection.mappingApplied) {
+                detectedMapping = detection.mappingApplied;
+                ctx.mappingAutoDetected = true;
+                ctx.warnings.push(`Auto-detected mapping '${detectedMapping}' from project configuration.`);
+                ctx.warnings.push(...detection.warnings);
+            }
+            else {
+                ctx.warnings.push(...detection.warnings);
+            }
+        }
+        catch {
+            // Detection failed — fall through to default
+        }
+    }
+    ctx.requestedMapping = normalizeMapping(detectedMapping ?? ctx.input.mapping);
+    ctx.mappingApplied = ctx.requestedMapping;
+    if (ctx.input.preferProjectVersion && ctx.input.projectPath) {
+        const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(ctx.input.projectPath);
+        if (detected && detected !== ctx.version) {
+            ctx.warnings.push(`Overriding version "${ctx.version}" with project version "${detected}" from gradle.properties.`);
+        }
+        ctx.version = detected ?? ctx.version;
+    }
+    ctx.signatureLookupMapping = "obfuscated";
+    if (ctx.input.scope && ctx.input.scope !== "vanilla" && ctx.input.projectPath) {
+        try {
+            ctx.resolvedArtifact = await svc.resolveArtifact({
+                target: { kind: "version", value: ctx.version },
+                mapping: ctx.requestedMapping,
+                sourcePriority: ctx.currentSourcePriority,
+                projectPath: ctx.input.projectPath,
+                scope: ctx.input.scope,
+                preferProjectVersion: false
+            });
+            ctx.jarPath = ctx.resolvedArtifact.binaryJarPath ?? (await svc.versionService.resolveVersionJar(ctx.version)).jarPath;
+            ctx.warnings.push(...ctx.resolvedArtifact.warnings);
+            ctx.mappingApplied = ctx.resolvedArtifact.mappingApplied;
+            ctx.signatureLookupMapping = ctx.resolvedArtifact.mappingApplied;
+            if (ctx.resolvedArtifact.version) {
+                ctx.version = ctx.resolvedArtifact.version;
+            }
+        }
+        catch (scopeErr) {
+            ctx.scopeFallback = {
+                requested: ctx.input.scope,
+                applied: "vanilla",
+                reason: `Loom cache unavailable: ${scopeErr instanceof Error ? scopeErr.message : String(scopeErr)}`
+            };
+            ctx.warnings.push(`Scope "${ctx.input.scope}" resolution failed; falling back to vanilla. ${ctx.scopeFallback.reason}`);
+            ctx.jarPath = (await svc.versionService.resolveVersionJar(ctx.version)).jarPath;
+        }
+    }
+    else {
+        ctx.jarPath = (await svc.versionService.resolveVersionJar(ctx.version)).jarPath;
+    }
+    if (ctx.jarPath.includes("-sources.jar")) {
+        ctx.warnings.push(`Resolved jar appears to be a sources jar. Falling back to vanilla client jar.`);
+        ctx.jarPath = (await svc.versionService.resolveVersionJar(ctx.version)).jarPath;
+        ctx.signatureLookupMapping = "obfuscated";
+        ctx.scopeFallback = {
+            requested: ctx.input.scope ?? "vanilla",
+            applied: "vanilla",
+            reason: "Resolved jar was a sources jar, not a binary class jar."
+        };
+    }
+    if (ctx.testHooks?.afterResolve) {
+        await ctx.testHooks.afterResolve();
+    }
+    ctx.checkPreParseBudget("resolve", resolveStartedAt, ctx.stageBudgets.resolve);
+}
+//# sourceMappingURL=resolve.js.map

package/dist/source/validate-mixin/pipeline/target-lookup.d.ts

@@ -0,0 +1,6 @@
+import type { ParsedMixinTarget } from "../../../mixin-parser.js";
+import type { TargetOutcome as MixinTargetOutcome } from "../../../mixin-validator.js";
+import type { SourceService } from "../../../source-service.js";
+import type { MutableMixinPipelineContext } from "../pipeline-context.js";
+export declare function processSingleMixinTarget(svc: SourceService, ctx: MutableMixinPipelineContext, target: ParsedMixinTarget, targetIndex: number): Promise<MixinTargetOutcome>;
+export declare function runTargetLookupStage(svc: SourceService, ctx: MutableMixinPipelineContext): Promise<void>;