@adhisang/minecraft-modding-mcp 3.2.0 → 4.1.0

package/dist/source/validate-mixin/pipeline/target-lookup.js

@@ -0,0 +1,260 @@
+import { performance } from "node:perf_hooks";
+function findValidateMixinClassMapping(svc, input) {
+    const cache = input.batchCaches?.classMappings;
+    if (!cache) {
+        return svc.mappingService.findMapping({
+            version: input.version,
+            kind: "class",
+            name: input.className,
+            sourceMapping: input.sourceMapping,
+            targetMapping: input.targetMapping,
+            sourcePriority: input.sourcePriority,
+            projectPath: input.projectPath
+        });
+    }
+    const cacheKey = [
+        input.version,
+        input.className,
+        input.sourceMapping,
+        input.targetMapping,
+        input.sourcePriority,
+        input.projectPath ?? ""
+    ].join("\0");
+    const cached = cache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const pending = svc.mappingService.findMapping({
+        version: input.version,
+        kind: "class",
+        name: input.className,
+        sourceMapping: input.sourceMapping,
+        targetMapping: input.targetMapping,
+        sourcePriority: input.sourcePriority,
+        projectPath: input.projectPath
+    }).catch((error) => {
+        cache.delete(cacheKey);
+        throw error;
+    });
+    cache.set(cacheKey, pending);
+    return pending;
+}
+export async function processSingleMixinTarget(svc, ctx, target, targetIndex) {
+    const totalTargets = ctx.parsed.targets.length;
+    await ctx.stageEmitter("target-lookup", {
+        targetIndex,
+        targetTotal: totalTargets,
+        targetClass: target.className,
+        memberCount: ctx.parsed.injections.length + ctx.parsed.shadows.length + ctx.parsed.accessors.length
+    });
+    const targetStartedAt = performance.now();
+    if (ctx.testHooks?.beforeTargetIter) {
+        await ctx.testHooks.beforeTargetIter(targetIndex);
+    }
+    let resolvedClassName = target.className;
+    if (!resolvedClassName.includes(".")) {
+        const fqcn = ctx.parsed.imports.get(resolvedClassName);
+        if (fqcn) {
+            resolvedClassName = fqcn;
+        }
+    }
+    else {
+        const segments = resolvedClassName.split(".");
+        const firstSegment = segments[0];
+        if (firstSegment && /^[A-Z]/.test(firstSegment)) {
+            const outerFqcn = ctx.parsed.imports.get(firstSegment);
+            if (outerFqcn) {
+                resolvedClassName = outerFqcn + "$" + segments.slice(1).join("$");
+            }
+        }
+    }
+    let obfuscatedName = resolvedClassName;
+    if (ctx.requestedMapping !== ctx.signatureLookupMapping) {
+        try {
+            const mapped = await findValidateMixinClassMapping(svc, {
+                version: ctx.version,
+                className: resolvedClassName,
+                sourceMapping: ctx.requestedMapping,
+                targetMapping: ctx.signatureLookupMapping,
+                sourcePriority: ctx.currentSourcePriority,
+                projectPath: ctx.input.projectPath,
+                batchCaches: ctx.input.batchCaches
+            });
+            if (mapped.resolved && mapped.resolvedSymbol) {
+                obfuscatedName = mapped.resolvedSymbol.name;
+                ctx.resolutionTrace?.push({ target: target.className, step: "mapping", input: resolvedClassName, output: obfuscatedName, success: true });
+            }
+            else {
+                ctx.warnings.push(`Could not map class "${resolvedClassName}" from ${ctx.requestedMapping} to ${ctx.signatureLookupMapping}; using "${obfuscatedName}" for lookup.`);
+                ctx.mappingFailedTargets.add(target.className);
+                ctx.resolutionTrace?.push({ target: target.className, step: "mapping", input: resolvedClassName, output: obfuscatedName, success: false, detail: "No mapping found" });
+            }
+        }
+        catch (mapErr) {
+            ctx.warnings.push(`Mapping lookup failed for class "${resolvedClassName}" while preparing ${ctx.signatureLookupMapping} lookup; using "${obfuscatedName}" for lookup.`);
+            ctx.mappingFailedTargets.add(target.className);
+            ctx.resolutionTrace?.push({ target: target.className, step: "mapping", input: resolvedClassName, output: obfuscatedName, success: false, detail: mapErr instanceof Error ? mapErr.message : String(mapErr) });
+        }
+    }
+    try {
+        const sig = await svc.explorerService.getSignature({
+            fqn: obfuscatedName,
+            jarPath: ctx.jarPath,
+            access: "all"
+        });
+        ctx.warnings.push(...sig.warnings);
+        ctx.resolutionTrace?.push({ target: target.className, step: "signature", input: obfuscatedName, output: `${sig.methods.length} methods, ${sig.fields.length} fields`, success: true });
+        let constructors = sig.constructors;
+        let methods = sig.methods;
+        let fields = sig.fields;
+        if (ctx.requestedMapping !== ctx.signatureLookupMapping) {
+            try {
+                const [ctorResult, methodResult, fieldResult] = await Promise.all([
+                    svc.remapSignatureMembers(sig.constructors, "method", ctx.version, ctx.signatureLookupMapping, ctx.requestedMapping, ctx.currentSourcePriority, ctx.warnings, ctx.input.projectPath),
+                    svc.remapSignatureMembers(sig.methods, "method", ctx.version, ctx.signatureLookupMapping, ctx.requestedMapping, ctx.currentSourcePriority, ctx.warnings, ctx.input.projectPath),
+                    svc.remapSignatureMembers(sig.fields, "field", ctx.version, ctx.signatureLookupMapping, ctx.requestedMapping, ctx.currentSourcePriority, ctx.warnings, ctx.input.projectPath)
+                ]);
+                constructors = ctorResult.members;
+                methods = methodResult.members;
+                fields = fieldResult.members;
+                const targetFailed = new Set();
+                for (const n of ctorResult.failedNames)
+                    targetFailed.add(n);
+                for (const n of methodResult.failedNames)
+                    targetFailed.add(n);
+                for (const n of fieldResult.failedNames)
+                    targetFailed.add(n);
+                if (targetFailed.size > 0) {
+                    ctx.remapFailedMembers.set(target.className, targetFailed);
+                    ctx.resolutionTrace?.push({ target: target.className, step: "remap", input: `${targetFailed.size} members`, output: "failed", success: false });
+                }
+                else {
+                    ctx.resolutionTrace?.push({ target: target.className, step: "remap", input: `${methods.length + fields.length} members`, output: "remapped", success: true });
+                }
+            }
+            catch (remapErr) {
+                ctx.warnings.push(`Member remapping failed for "${resolvedClassName}"; falling back to ${ctx.signatureLookupMapping} names. ` +
+                    `Member names shown may be in the ${ctx.signatureLookupMapping} runtime namespace.`);
+                ctx.mappingApplied = ctx.signatureLookupMapping;
+                ctx.wholeRemapFailedTargets.add(target.className);
+                ctx.resolutionTrace?.push({
+                    target: target.className,
+                    step: "remap",
+                    input: resolvedClassName,
+                    output: `${ctx.signatureLookupMapping} fallback`,
+                    success: false,
+                    detail: remapErr instanceof Error ? remapErr.message : String(remapErr)
+                });
+            }
+        }
+        ctx.targetMembers.set(target.className, {
+            className: target.className,
+            constructors,
+            methods,
+            fields
+        });
+    }
+    catch (sigErr) {
+        ctx.warnings.push(`Could not load signature for class "${resolvedClassName}" (obfuscated: "${obfuscatedName}").`);
+        ctx.resolutionTrace?.push({ target: target.className, step: "signature", input: obfuscatedName, output: "CLASS_NOT_FOUND", success: false, detail: sigErr instanceof Error ? sigErr.message : String(sigErr) });
+        try {
+            const existenceCheck = await svc.mappingService.checkSymbolExists({
+                version: ctx.version, kind: "class", name: resolvedClassName,
+                sourceMapping: ctx.requestedMapping, nameMode: "auto", sourcePriority: ctx.currentSourcePriority
+            });
+            if (existenceCheck.resolved) {
+                ctx.symbolExistsButSignatureFailed.add(target.className);
+                ctx.resolutionTrace?.push({ target: target.className, step: "fallback-check", input: resolvedClassName, output: "exists in mapping graph", success: true });
+            }
+            else {
+                ctx.resolutionTrace?.push({ target: target.className, step: "fallback-check", input: resolvedClassName, output: "not found", success: false });
+            }
+        }
+        catch {
+            ctx.signatureFailedTargets.add(target.className);
+            ctx.resolutionTrace?.push({ target: target.className, step: "fallback-check", input: resolvedClassName, output: "check failed", success: false });
+        }
+    }
+    const targetElapsed = performance.now() - targetStartedAt;
+    const hadToolIssue = ctx.mappingFailedTargets.has(target.className) ||
+        ctx.signatureFailedTargets.has(target.className) ||
+        ctx.symbolExistsButSignatureFailed.has(target.className) ||
+        ctx.remapFailedMembers.has(target.className) ||
+        ctx.wholeRemapFailedTargets.has(target.className);
+    const completedOutcome = hadToolIssue
+        ? {
+            targetClass: target.className,
+            status: "tool-issue",
+            elapsedMs: targetElapsed,
+            reason: ctx.signatureFailedTargets.has(target.className)
+                ? "signature-load-failed"
+                : ctx.symbolExistsButSignatureFailed.has(target.className)
+                    ? "signature-load-failed-symbol-exists"
+                    : ctx.mappingFailedTargets.has(target.className)
+                        ? "mapping-failed"
+                        : ctx.wholeRemapFailedTargets.has(target.className)
+                            ? "member-remap-failed-whole"
+                            : "member-remap-failed"
+        }
+        : {
+            targetClass: target.className,
+            status: "ok",
+            elapsedMs: targetElapsed
+        };
+    if (targetElapsed > ctx.stageBudgets.perTarget) {
+        completedOutcome.slowTarget = true;
+        completedOutcome.budgetMs = ctx.stageBudgets.perTarget;
+    }
+    return completedOutcome;
+}
+export async function runTargetLookupStage(svc, ctx) {
+    const targetLookupStartedAt = await ctx.enterStage("target-lookup");
+    if (ctx.testHooks?.beforeTargetLoop) {
+        await ctx.testHooks.beforeTargetLoop();
+    }
+    const totalTargets = ctx.parsed.targets.length;
+    for (let targetIndex = 0; targetIndex < totalTargets; targetIndex++) {
+        const stageElapsed = performance.now() - targetLookupStartedAt;
+        if (stageElapsed > ctx.stageBudgets.targetLookup) {
+            ctx.stageBudgetExhausted = true;
+            ctx.nextTargetIndex = targetIndex;
+            break;
+        }
+        const target = ctx.parsed.targets[targetIndex];
+        const outcome = await processSingleMixinTarget(svc, ctx, target, targetIndex);
+        ctx.targetOutcomes.push(outcome);
+        ctx.processedTargetCount += 1;
+    }
+    if (ctx.stageBudgetExhausted) {
+        if (ctx.processedTargetCount === 0) {
+            ctx.degradedReason = "stage-budget-pre-target";
+            for (const remaining of ctx.parsed.targets) {
+                ctx.skippedForValidator.add(remaining.className);
+            }
+        }
+        else {
+            ctx.degradedReason = "stage-budget";
+            for (let j = ctx.nextTargetIndex; j < totalTargets; j++) {
+                const remaining = ctx.parsed.targets[j];
+                ctx.deferredTargetClasses.add(remaining.className);
+                ctx.skippedForValidator.add(remaining.className);
+                ctx.targetOutcomes.push({
+                    targetClass: remaining.className,
+                    status: "deferred-budget",
+                    reason: "stage-budget",
+                    budgetMs: ctx.stageBudgets.targetLookup
+                });
+            }
+        }
+    }
+    if (ctx.healthReport) {
+        const hasFailures = ctx.signatureFailedTargets.size > 0 ||
+            ctx.mappingFailedTargets.size > 0 ||
+            ctx.symbolExistsButSignatureFailed.size > 0;
+        if (hasFailures && ctx.healthReport.overallHealthy) {
+            ctx.healthReport.overallHealthy = false;
+            ctx.healthReport.degradations.push(`${ctx.mappingFailedTargets.size} mapping failure(s), ${ctx.signatureFailedTargets.size} signature failure(s), ${ctx.symbolExistsButSignatureFailed.size} partial validation target(s).`);
+        }
+    }
+}
+//# sourceMappingURL=target-lookup.js.map

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

@@ -0,0 +1,72 @@
+import type { ParsedMixin } from "../../mixin-parser.js";
+import type { MappingHealthReport, MixinValidationProvenance, MixinStageBudgets, ResolvedTargetMembers, TargetOutcome as MixinTargetOutcome } from "../../mixin-validator.js";
+import type { ResolveArtifactOutput, ValidateMixinOptions } from "../../source-service.js";
+import type { StageEmitter } from "../../stage-emitter.js";
+import type { ArtifactScope, MappingSourcePriority, SourceMapping } from "../../types.js";
+import type { ValidateMixinSingleInput } from "../validate-mixin.js";
+/**
+ * Diagnostic tag attached to every AppError thrown out of validate-mixin.
+ * - "input-validation": required field missing or sourcePath unreadable
+ * - "resolve": jar / artifact resolution
+ * - "mapping-health": mapping infrastructure probe
+ * - "parse": parseMixinSource failure
+ * - "target-lookup": per-target symbol/signature/remap loop
+ */
+export type ValidateMixinStage = "input-validation" | "resolve" | "mapping-health" | "parse" | "target-lookup";
+export type MixinPipelineScopeFallback = {
+    requested: string;
+    applied: string;
+    reason: string;
+};
+export interface MutableMixinPipelineContext {
+    readonly input: ValidateMixinSingleInput;
+    readonly source: string;
+    readonly requestedScope: ArtifactScope;
+    readonly currentSourcePriority: MappingSourcePriority;
+    readonly initialSourcePriority: MappingSourcePriority;
+    readonly stageEmitter: StageEmitter;
+    readonly stageBudgets: MixinStageBudgets;
+    readonly testHooks: ValidateMixinOptions["__testHooks"];
+    readonly onStage: (stage: ValidateMixinStage) => void;
+    warnings: string[];
+    version: string;
+    mappingAutoDetected: boolean;
+    requestedMapping: SourceMapping;
+    mappingApplied: SourceMapping;
+    jarPath: string;
+    resolvedArtifact?: ResolveArtifactOutput;
+    signatureLookupMapping: SourceMapping;
+    scopeFallback?: MixinPipelineScopeFallback;
+    healthReport?: MappingHealthReport;
+    parsed: ParsedMixin;
+    targetOutcomes: MixinTargetOutcome[];
+    degradedReason?: "stage-budget" | "stage-budget-pre-target";
+    deferredTargetClasses: Set<string>;
+    targetMembers: Map<string, ResolvedTargetMembers>;
+    mappingFailedTargets: Set<string>;
+    remapFailedMembers: Map<string, Set<string>>;
+    wholeRemapFailedTargets: Set<string>;
+    signatureFailedTargets: Set<string>;
+    symbolExistsButSignatureFailed: Set<string>;
+    resolutionTrace?: NonNullable<MixinValidationProvenance["resolutionTrace"]>;
+    processedTargetCount: number;
+    stageBudgetExhausted: boolean;
+    nextTargetIndex: number;
+    skippedForValidator: Set<string>;
+    enterStage(stage: ValidateMixinStage): Promise<number>;
+    checkPreParseBudget(stage: ValidateMixinStage, startedAt: number, budgetMs: number): void;
+}
+export type MixinPipelineSeed = {
+    input: ValidateMixinSingleInput;
+    version: string;
+    source: string;
+    requestedScope: ArtifactScope;
+    currentSourcePriority: MappingSourcePriority;
+    initialSourcePriority: MappingSourcePriority;
+    stageEmitter: StageEmitter;
+    stageBudgets: MixinStageBudgets;
+    testHooks: ValidateMixinOptions["__testHooks"];
+    onStage: (stage: ValidateMixinStage) => void;
+};
+export declare function createMixinPipelineContext(seed: MixinPipelineSeed): MutableMixinPipelineContext;
+export declare function normalizeMapping(mapping: SourceMapping | undefined): SourceMapping;

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

@@ -0,0 +1,93 @@
+import { performance } from "node:perf_hooks";
+import { buildSuggestedCall } from "../../build-suggested-call.js";
+import { ERROR_CODES, createError } from "../../errors.js";
+const EMPTY_PARSED = {
+    className: "",
+    targets: [],
+    imports: new Map(),
+    injections: [],
+    shadows: [],
+    accessors: [],
+    parseWarnings: []
+};
+export function createMixinPipelineContext(seed) {
+    const ctx = {
+        input: seed.input,
+        source: seed.source,
+        requestedScope: seed.requestedScope,
+        currentSourcePriority: seed.currentSourcePriority,
+        initialSourcePriority: seed.initialSourcePriority,
+        stageEmitter: seed.stageEmitter,
+        stageBudgets: seed.stageBudgets,
+        testHooks: seed.testHooks,
+        onStage: seed.onStage,
+        warnings: [],
+        version: seed.version,
+        mappingAutoDetected: false,
+        requestedMapping: "obfuscated",
+        mappingApplied: "obfuscated",
+        jarPath: "",
+        resolvedArtifact: undefined,
+        signatureLookupMapping: "obfuscated",
+        scopeFallback: undefined,
+        healthReport: undefined,
+        parsed: EMPTY_PARSED,
+        targetOutcomes: [],
+        degradedReason: undefined,
+        deferredTargetClasses: new Set(),
+        targetMembers: new Map(),
+        mappingFailedTargets: new Set(),
+        remapFailedMembers: new Map(),
+        wholeRemapFailedTargets: new Set(),
+        signatureFailedTargets: new Set(),
+        symbolExistsButSignatureFailed: new Set(),
+        resolutionTrace: seed.input.explain ? [] : undefined,
+        processedTargetCount: 0,
+        stageBudgetExhausted: false,
+        nextTargetIndex: 0,
+        skippedForValidator: new Set(),
+        enterStage: async (stage) => {
+            ctx.onStage(stage);
+            const startedAt = performance.now();
+            await ctx.stageEmitter(stage);
+            return startedAt;
+        },
+        checkPreParseBudget: (stage, stageStartedAt, budgetMs) => {
+            const elapsed = performance.now() - stageStartedAt;
+            if (elapsed > budgetMs) {
+                throw createError({
+                    code: ERROR_CODES.STAGE_BUDGET_PRE_PARSE,
+                    message: `Stage ${stage} exhausted budget before parse completed.`,
+                    details: {
+                        failedStage: stage,
+                        stageBudgetExhausted: true,
+                        budgetMs,
+                        elapsedMs: elapsed
+                    }
+                });
+            }
+        }
+    };
+    return ctx;
+}
+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" } })
+        }
+    });
+}
+//# sourceMappingURL=pipeline-context.js.map

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

@@ -0,0 +1,22 @@
+import { type MixinValidationResult, type MixinStageBudgets } from "../mixin-validator.js";
+import type { SourceService } from "../source-service.js";
+import type { ValidateMixinInput, ValidateMixinOptions, ValidateMixinOutput } from "../source-service.js";
+import { type StageEmitter } from "../stage-emitter.js";
+import type { MappingSourcePriority } from "../types.js";
+import type { FindMappingOutput as MappingFindMappingOutput } from "../mapping-service.js";
+export type ValidateMixinSingleInput = Omit<ValidateMixinInput, "input"> & {
+    source?: string;
+    sourcePath?: string;
+    batchCaches?: {
+        classMappings: Map<string, Promise<MappingFindMappingOutput>>;
+    };
+    retryState?: {
+        attempted: boolean;
+        initialSourcePriority: MappingSourcePriority;
+    };
+    stageEmitter?: StageEmitter;
+    __stageBudgets?: Partial<MixinStageBudgets>;
+    __testHooks?: ValidateMixinOptions["__testHooks"];
+};
+export declare function validateMixin(svc: SourceService, input: ValidateMixinInput, options?: ValidateMixinOptions): Promise<ValidateMixinOutput>;
+export declare function validateMixinSingle(svc: SourceService, input: ValidateMixinSingleInput): Promise<MixinValidationResult>;