@adhisang/minecraft-modding-mcp 4.0.0 → 4.1.0

package/dist/source/lifecycle/runtime-check.js

@@ -0,0 +1,142 @@
+export async function checkSymbolExistsInUnobfuscatedRuntime(svc, input, fallbackBase) {
+    const version = input.version.trim();
+    const name = input.name.trim();
+    const owner = input.owner?.trim();
+    if (!version || !name) {
+        return undefined;
+    }
+    if (input.kind === "class" && input.nameMode !== "fqcn" && !name.includes(".")) {
+        return {
+            ...fallbackBase,
+            warnings: [
+                ...fallbackBase.warnings,
+                `Version ${version} is unobfuscated, but short class name "${name}" could not be checked against runtime bytecode without a fully-qualified name.`
+            ]
+        };
+    }
+    const querySymbol = input.kind === "class"
+        ? {
+            kind: "class",
+            name,
+            symbol: name
+        }
+        : input.kind === "field"
+            ? {
+                kind: "field",
+                owner,
+                name,
+                symbol: `${owner}.${name}`
+            }
+            : {
+                kind: "method",
+                owner,
+                name,
+                descriptor: input.descriptor?.trim(),
+                symbol: `${owner}.${name}${input.descriptor?.trim() ?? ""}`
+            };
+    const targetClass = input.kind === "class" ? name : owner;
+    if (!targetClass) {
+        return fallbackBase;
+    }
+    let jarPath;
+    try {
+        ({ jarPath } = await svc.versionService.resolveVersionJar(version));
+    }
+    catch {
+        return undefined;
+    }
+    let signature;
+    try {
+        signature = await svc.explorerService.getSignature({
+            fqn: targetClass,
+            jarPath,
+            access: "all"
+        });
+    }
+    catch {
+        return {
+            ...fallbackBase,
+            querySymbol,
+            warnings: [
+                ...fallbackBase.warnings,
+                `Version ${version} is unobfuscated; runtime bytecode lookup could not load class "${targetClass}".`
+            ]
+        };
+    }
+    const warnings = [
+        ...fallbackBase.warnings,
+        ...signature.warnings,
+        `Version ${version} is unobfuscated; validated symbol existence against runtime bytecode.`
+    ];
+    const buildResolved = (resolvedSymbol) => ({
+        ...fallbackBase,
+        querySymbol,
+        resolved: true,
+        status: "resolved",
+        resolvedSymbol,
+        candidates: resolvedSymbol
+            ? [{
+                    ...resolvedSymbol,
+                    matchKind: "exact",
+                    confidence: 1
+                }]
+            : [],
+        candidateCount: resolvedSymbol ? 1 : 0,
+        warnings
+    });
+    const buildUnresolved = (status) => ({
+        ...fallbackBase,
+        querySymbol,
+        resolved: false,
+        status,
+        resolvedSymbol: undefined,
+        candidates: [],
+        candidateCount: 0,
+        warnings
+    });
+    if (input.kind === "class") {
+        return buildResolved({
+            kind: "class",
+            name,
+            symbol: name
+        });
+    }
+    if (input.kind === "field") {
+        const matched = signature.fields.filter((field) => field.name === name);
+        if (matched.length !== 1) {
+            return buildUnresolved(matched.length > 1 ? "ambiguous" : "not_found");
+        }
+        return buildResolved({
+            kind: "field",
+            owner,
+            name,
+            symbol: `${owner}.${name}`
+        });
+    }
+    const methodCandidates = signature.methods.filter((method) => method.name === name);
+    if (input.signatureMode === "name-only") {
+        if (methodCandidates.length !== 1) {
+            return buildUnresolved(methodCandidates.length > 1 ? "ambiguous" : "not_found");
+        }
+        return buildResolved({
+            kind: "method",
+            owner,
+            name,
+            descriptor: methodCandidates[0]?.jvmDescriptor,
+            symbol: `${owner}.${name}${methodCandidates[0]?.jvmDescriptor ?? ""}`
+        });
+    }
+    const descriptor = input.descriptor?.trim();
+    const matched = methodCandidates.filter((method) => method.jvmDescriptor === descriptor);
+    if (matched.length !== 1) {
+        return buildUnresolved(matched.length > 1 ? "ambiguous" : "not_found");
+    }
+    return buildResolved({
+        kind: "method",
+        owner,
+        name,
+        descriptor,
+        symbol: `${owner}.${name}${descriptor ?? ""}`
+    });
+}
+//# sourceMappingURL=runtime-check.js.map

package/dist/source/lifecycle/trace.d.ts

@@ -0,0 +1,2 @@
+import type { SourceService, TraceSymbolLifecycleInput, TraceSymbolLifecycleOutput } from "../../source-service.js";
+export declare function traceSymbolLifecycle(svc: SourceService, input: TraceSymbolLifecycleInput): Promise<TraceSymbolLifecycleOutput>;

package/dist/source/lifecycle/trace.js

@@ -0,0 +1,231 @@
+import { buildSuggestedCall } from "../../build-suggested-call.js";
+import { mapWithConcurrencyLimit } from "../../concurrency.js";
+import { ERROR_CODES, createError, isAppError } from "../../errors.js";
+import { normalizeOptionalString } from "../shared-utils.js";
+import { normalizeMapping, rejectLifecycleClassLikeInput, releaseLifecycleMappingGraph, resolveToObfuscatedClassName, resolveToObfuscatedMemberName } from "./mapping-helpers.js";
+const TRACE_LIFECYCLE_MAX_CONCURRENCY = 3;
+function clampLimit(limit, fallback, max) {
+    if (!Number.isFinite(limit) || limit == null) {
+        return fallback;
+    }
+    return Math.max(1, Math.min(max, Math.trunc(limit)));
+}
+function looksLikeJvmMethodDescriptor(descriptor) {
+    const trimmed = descriptor?.trim();
+    if (!trimmed || !trimmed.startsWith("(")) {
+        return false;
+    }
+    const closing = trimmed.indexOf(")");
+    return closing > 0 && closing < trimmed.length - 1;
+}
+function parseQualifiedMethodSymbol(symbol) {
+    const trimmed = symbol.trim();
+    const descriptorStart = trimmed.indexOf("(");
+    const qualifiedSymbol = descriptorStart >= 0 ? trimmed.slice(0, descriptorStart) : trimmed;
+    const inlineDescriptor = descriptorStart >= 0 ? trimmed.slice(descriptorStart).trim() : undefined;
+    const separator = qualifiedSymbol.lastIndexOf(".");
+    if (separator <= 0 || separator >= qualifiedSymbol.length - 1) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: `symbol must be in the form "fully.qualified.Class.method".`,
+            details: { symbol }
+        });
+    }
+    const className = qualifiedSymbol.slice(0, separator);
+    const methodName = qualifiedSymbol.slice(separator + 1);
+    if (!className ||
+        !methodName ||
+        className.includes("/") ||
+        methodName.includes(".") ||
+        /\s/.test(methodName)) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: `symbol must be in the form "fully.qualified.Class.method".`,
+            details: { symbol }
+        });
+    }
+    return {
+        className,
+        methodName,
+        ...(inlineDescriptor ? { inlineDescriptor } : {})
+    };
+}
+export async function traceSymbolLifecycle(svc, input) {
+    const mapping = normalizeMapping(input.mapping);
+    const { className: userClassName, methodName: userMethodName, inlineDescriptor } = parseQualifiedMethodSymbol(input.symbol);
+    const descriptor = normalizeOptionalString(input.descriptor)
+        ?? (looksLikeJvmMethodDescriptor(inlineDescriptor) ? normalizeOptionalString(inlineDescriptor) : undefined);
+    const includeTimeline = input.includeTimeline ?? false;
+    const includeSnapshots = input.includeSnapshots ?? false;
+    const maxVersions = clampLimit(input.maxVersions, 120, 400);
+    const manifestOrder = await svc.versionService.listVersionIds({ includeSnapshots });
+    if (manifestOrder.length === 0) {
+        throw createError({
+            code: ERROR_CODES.VERSION_NOT_FOUND,
+            message: "No Minecraft versions were returned by manifest.",
+            details: {
+                includeSnapshots,
+                nextAction: "Use list-versions to see available Minecraft versions.",
+                ...buildSuggestedCall({ tool: "list-versions", params: {} })
+            }
+        });
+    }
+    const chronological = [...manifestOrder].reverse();
+    const requestedFrom = normalizeOptionalString(input.fromVersion) ?? chronological[0];
+    const requestedTo = normalizeOptionalString(input.toVersion) ?? chronological[chronological.length - 1];
+    const fromIndex = chronological.indexOf(requestedFrom);
+    const toIndex = chronological.indexOf(requestedTo);
+    if (fromIndex < 0) {
+        throw createError({
+            code: ERROR_CODES.VERSION_NOT_FOUND,
+            message: `fromVersion "${requestedFrom}" was not found in manifest.`,
+            details: {
+                fromVersion: requestedFrom,
+                nextAction: "Use list-versions to see available Minecraft versions.",
+                ...buildSuggestedCall({ tool: "list-versions", params: {} })
+            }
+        });
+    }
+    if (toIndex < 0) {
+        throw createError({
+            code: ERROR_CODES.VERSION_NOT_FOUND,
+            message: `toVersion "${requestedTo}" was not found in manifest.`,
+            details: {
+                toVersion: requestedTo,
+                nextAction: "Use list-versions to see available Minecraft versions.",
+                ...buildSuggestedCall({ tool: "list-versions", params: {} })
+            }
+        });
+    }
+    if (fromIndex > toIndex) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: "fromVersion must be older than or equal to toVersion.",
+            details: { fromVersion: requestedFrom, toVersion: requestedTo }
+        });
+    }
+    let selectedVersions = chronological.slice(fromIndex, toIndex + 1);
+    const warnings = [];
+    if (selectedVersions.length > maxVersions) {
+        selectedVersions = selectedVersions.slice(selectedVersions.length - maxVersions);
+        warnings.push(`Version scan truncated to ${maxVersions} entries. Effective fromVersion is now "${selectedVersions[0]}".`);
+    }
+    const referenceVersion = selectedVersions[selectedVersions.length - 1];
+    rejectLifecycleClassLikeInput(svc, {
+        symbol: input.symbol,
+        className: userClassName,
+        methodName: userMethodName,
+        mapping,
+        version: referenceVersion,
+        sourcePriority: input.sourcePriority
+    });
+    const scannedResults = await mapWithConcurrencyLimit(selectedVersions, TRACE_LIFECYCLE_MAX_CONCURRENCY, async (version) => {
+        const versionWarnings = [];
+        try {
+            const [obfuscatedClassName, obfuscatedMethod, resolvedJar] = await Promise.all([
+                resolveToObfuscatedClassName(svc, userClassName, version, mapping, input.sourcePriority, versionWarnings),
+                resolveToObfuscatedMemberName(svc, userMethodName, userClassName, descriptor, "method", version, mapping, input.sourcePriority, versionWarnings),
+                svc.versionService.resolveVersionJar(version)
+            ]);
+            const signature = await svc.explorerService.getSignature({
+                fqn: obfuscatedClassName,
+                jarPath: resolvedJar.jarPath,
+                access: "all",
+                includeSynthetic: true
+            });
+            const sameNameMethods = signature.methods.filter((method) => method.name === obfuscatedMethod.name);
+            const effectiveDescriptor = obfuscatedMethod.descriptor ?? descriptor;
+            const matchesDescriptor = effectiveDescriptor
+                ? sameNameMethods.some((method) => method.jvmDescriptor === effectiveDescriptor)
+                : sameNameMethods.length > 0;
+            const reason = !matchesDescriptor && descriptor && sameNameMethods.length > 0 ? "descriptor-mismatch" : undefined;
+            return {
+                entry: {
+                    version,
+                    exists: matchesDescriptor,
+                    reason,
+                    determinate: true
+                },
+                warnings: versionWarnings
+            };
+        }
+        catch (caughtError) {
+            if (isAppError(caughtError) && caughtError.code === ERROR_CODES.CLASS_NOT_FOUND) {
+                return {
+                    entry: {
+                        version,
+                        exists: false,
+                        reason: "class-not-found",
+                        determinate: true
+                    },
+                    warnings: versionWarnings
+                };
+            }
+            versionWarnings.push(`Failed to evaluate ${version}: ${caughtError instanceof Error ? caughtError.message : String(caughtError)}`);
+            return {
+                entry: {
+                    version,
+                    exists: false,
+                    reason: "unresolved",
+                    determinate: false
+                },
+                warnings: versionWarnings
+            };
+        }
+        finally {
+            releaseLifecycleMappingGraph(svc, version, input.sourcePriority);
+        }
+    });
+    const scanned = scannedResults.map((result) => result.entry);
+    for (const result of scannedResults) {
+        warnings.push(...result.warnings);
+    }
+    const determinate = scanned.filter((entry) => entry.determinate);
+    const present = determinate.filter((entry) => entry.exists);
+    const firstSeen = present[0]?.version;
+    const lastSeen = present[present.length - 1]?.version;
+    const missingBetween = [];
+    if (firstSeen && lastSeen) {
+        const firstSeenIndex = determinate.findIndex((entry) => entry.version === firstSeen);
+        const lastSeenIndex = determinate.findIndex((entry) => entry.version === lastSeen);
+        for (let index = firstSeenIndex; index <= lastSeenIndex; index += 1) {
+            const entry = determinate[index];
+            if (entry && !entry.exists) {
+                missingBetween.push(entry.version);
+            }
+        }
+    }
+    const toVersionEntry = scanned.find((entry) => entry.version === selectedVersions[selectedVersions.length - 1]);
+    const existsNow = toVersionEntry?.determinate ? toVersionEntry.exists : false;
+    if (toVersionEntry && !toVersionEntry.determinate) {
+        warnings.push(`Latest requested version "${toVersionEntry.version}" could not be evaluated.`);
+    }
+    return {
+        query: {
+            className: userClassName,
+            methodName: userMethodName,
+            descriptor,
+            mapping
+        },
+        range: {
+            fromVersion: selectedVersions[0],
+            toVersion: selectedVersions[selectedVersions.length - 1],
+            scannedCount: selectedVersions.length
+        },
+        presence: {
+            firstSeen,
+            lastSeen,
+            missingBetween,
+            existsNow
+        },
+        timeline: includeTimeline
+            ? scanned.map((entry) => ({
+                version: entry.version,
+                exists: entry.exists,
+                reason: entry.reason
+            }))
+            : undefined,
+        warnings
+    };
+}
+//# sourceMappingURL=trace.js.map

package/dist/source/lifecycle.d.ts

@@ -0,0 +1,4 @@
+export { checkSymbolExistsInUnobfuscatedRuntime } from "./lifecycle/runtime-check.js";
+export { traceSymbolLifecycle } from "./lifecycle/trace.js";
+export { diffClassSignatures } from "./lifecycle/diff.js";
+export { rejectLifecycleClassLikeInput, releaseLifecycleMappingGraph, resolveToObfuscatedClassName, resolveToObfuscatedMemberName, remapSignatureMembers } from "./lifecycle/mapping-helpers.js";

package/dist/source/lifecycle.js

@@ -0,0 +1,5 @@
+export { checkSymbolExistsInUnobfuscatedRuntime } from "./lifecycle/runtime-check.js";
+export { traceSymbolLifecycle } from "./lifecycle/trace.js";
+export { diffClassSignatures } from "./lifecycle/diff.js";
+export { rejectLifecycleClassLikeInput, releaseLifecycleMappingGraph, resolveToObfuscatedClassName, resolveToObfuscatedMemberName, remapSignatureMembers } from "./lifecycle/mapping-helpers.js";
+//# sourceMappingURL=lifecycle.js.map

package/dist/source/search.d.ts

@@ -0,0 +1,51 @@
+import type { SourceService } from "../source-service.js";
+import type { QueryMode, SearchClassSourceInput, SearchClassSourceOutput, SearchScope, SearchSourceHit, SymbolKind } from "../source-service.js";
+type SearchIntent = "symbol" | "text" | "path";
+type SearchMatch = "exact" | "prefix" | "contains" | "regex";
+interface IndexedSymbolHit {
+    symbol: {
+        filePath: string;
+        symbolKind: string;
+        symbolName: string;
+        qualifiedName: string | undefined;
+        line: number;
+    };
+    score: number;
+    matchIndex: number;
+}
+declare const MAX_REGEX_QUERY_LENGTH = 200;
+declare const MAX_REGEX_RESULT_LIMIT = 100;
+export { MAX_REGEX_QUERY_LENGTH, MAX_REGEX_RESULT_LIMIT };
+export declare function normalizeIntent(intent: SearchIntent | undefined): SearchIntent;
+export declare function normalizeMatch(match: SearchMatch | undefined): SearchMatch;
+export declare function canUseIndexedSearchPath(indexedSearchEnabled: boolean, intent: SearchIntent, match: SearchMatch, _scope: SearchScope | undefined): boolean;
+export declare function buildGlobRegex(pattern: string): RegExp;
+export declare function globToSqlLike(pattern: string): string;
+export declare function checkPackagePrefix(filePath: string, packagePrefix?: string): boolean;
+export declare function buildSearchCursorContext(input: {
+    artifactId: string;
+    query: string;
+    intent: SearchIntent;
+    match: SearchMatch;
+    queryMode: QueryMode;
+    scope: SearchScope | undefined;
+}): string;
+export declare function compileRegex(query: string): RegExp;
+export declare function findMatchIndex(target: string, query: string, match: SearchMatch, pattern?: RegExp): number;
+/**
+ * Content-aware variant of findMatchIndex for searching within file text.
+ */
+export declare function findContentMatchIndex(content: string, query: string, match: SearchMatch, pattern?: RegExp): number;
+export declare function scoreSymbolMatch(match: SearchMatch, index: number, symbolKind: SymbolKind): number;
+export declare function scoreTextMatch(match: SearchMatch, index: number): number;
+export declare function scorePathMatch(match: SearchMatch, index: number): number;
+export declare function matchRegexIndex(target: string, regex: RegExp): number;
+export declare function searchClassSource(svc: SourceService, input: SearchClassSourceInput): Promise<SearchClassSourceOutput>;
+export declare function searchSymbolIntent(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, regexPattern: RegExp | undefined, onHit: (hit: SearchSourceHit) => void): void;
+export declare function searchTextIntentIndexed(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, onHit: (hit: SearchSourceHit) => void): void;
+export declare function searchPathIntentIndexed(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, onHit: (hit: SearchSourceHit) => void): void;
+export declare function searchTextIntent(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, regexPattern: RegExp | undefined, onHit: (hit: SearchSourceHit) => void): void;
+export declare function searchPathIntent(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, regexPattern: RegExp | undefined, onHit: (hit: SearchSourceHit) => void): void;
+export declare function findSymbolHits(svc: SourceService, artifactId: string, query: string, match: SearchMatch, scope: SearchScope | undefined, regexPattern: RegExp | undefined): IndexedSymbolHit[];
+export declare function indexedCandidateLimit(svc: SourceService): number;
+export declare function indexedCandidateLimitForMatch(svc: SourceService, match: SearchMatch): number;