@adhisang/minecraft-modding-mcp 2.1.0 → 3.0.0

package/dist/entry-tools/analyze-symbol-service.js

@@ -0,0 +1,304 @@
+import { z } from "zod";
+import { createError, ERROR_CODES } from "../errors.js";
+import { buildIncludeSchema, detailSchema, positiveIntSchema } from "./entry-tool-schema.js";
+import { buildEntryToolResult } from "./response-contract.js";
+import { resolveDetail, resolveInclude } from "./request-normalizers.js";
+const nonEmptyString = z.string().trim().min(1);
+const INCLUDE_GROUPS = ["warnings", "candidates", "matrix", "workspace", "timings"];
+const TASKS = ["exists", "map", "exact-map", "lifecycle", "workspace", "api-overview"];
+export const analyzeSymbolShape = {
+    task: z.enum(TASKS),
+    subject: z.object({
+        kind: z.enum(["class", "method", "field", "symbol"]),
+        name: nonEmptyString,
+        owner: nonEmptyString.optional(),
+        descriptor: nonEmptyString.optional()
+    }),
+    version: nonEmptyString.optional(),
+    sourceMapping: z.enum(["obfuscated", "mojang", "intermediary", "yarn"]).optional(),
+    targetMapping: z.enum(["obfuscated", "mojang", "intermediary", "yarn"]).optional(),
+    classNameMapping: z.enum(["obfuscated", "mojang", "intermediary", "yarn"]).optional(),
+    projectPath: nonEmptyString.optional(),
+    signatureMode: z.enum(["exact", "name-only"]).optional(),
+    nameMode: z.enum(["fqcn", "auto"]).optional(),
+    includeKinds: z.array(z.enum(["class", "field", "method"])).optional(),
+    maxRows: positiveIntSchema.optional(),
+    maxCandidates: positiveIntSchema.optional(),
+    detail: detailSchema.optional(),
+    include: buildIncludeSchema(INCLUDE_GROUPS)
+};
+export const analyzeSymbolSchema = z.object(analyzeSymbolShape).superRefine((value, ctx) => {
+    if (value.task !== "workspace" && !value.version) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["version"],
+            message: "version is required for non-workspace tasks."
+        });
+    }
+    if (value.task === "workspace" && !value.projectPath) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["projectPath"],
+            message: "projectPath is required for task=workspace."
+        });
+    }
+    if (value.task === "api-overview" && value.subject.kind !== "class") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["subject", "kind"],
+            message: "task=api-overview requires subject.kind=class."
+        });
+    }
+    if (value.task === "api-overview" && value.subject.owner) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["subject", "owner"],
+            message: "task=api-overview does not accept owner or descriptor selectors."
+        });
+    }
+    if (value.task === "api-overview" && value.subject.descriptor) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["subject", "descriptor"],
+            message: "task=api-overview does not accept owner or descriptor selectors."
+        });
+    }
+});
+function summaryStatusFromResolution(status) {
+    switch (status) {
+        case "resolved":
+            return "ok";
+        case "not_found":
+            return "not_found";
+        case "ambiguous":
+            return "ambiguous";
+        case "mapping_unavailable":
+            return "partial";
+    }
+}
+export class AnalyzeSymbolService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(input) {
+        const detail = resolveDetail(input.detail);
+        const include = resolveInclude(input.include);
+        const subjectKind = input.subject.kind === "symbol"
+            ? "class"
+            : input.subject.kind;
+        switch (input.task) {
+            case "exists": {
+                const output = await this.deps.checkSymbolExists({
+                    version: input.version,
+                    kind: subjectKind,
+                    name: input.subject.name,
+                    owner: input.subject.owner,
+                    descriptor: input.subject.descriptor,
+                    sourceMapping: input.sourceMapping ?? "obfuscated",
+                    nameMode: input.nameMode,
+                    signatureMode: input.signatureMode,
+                    maxCandidates: input.maxCandidates
+                });
+                return {
+                    ...buildEntryToolResult({
+                        task: "exists",
+                        detail,
+                        include,
+                        summary: {
+                            status: summaryStatusFromResolution(output.status),
+                            headline: output.resolved
+                                ? `The symbol exists in ${output.mappingContext.version}.`
+                                : `The symbol could not be resolved in ${output.mappingContext.version}.`,
+                            counts: {
+                                candidates: output.candidateCount
+                            }
+                        },
+                        blocks: {
+                            match: output.resolvedSymbol ?? output.querySymbol,
+                            candidates: output.candidates,
+                            ambiguity: output.ambiguityReasons ? { reasons: output.ambiguityReasons } : undefined
+                        }
+                    }),
+                    warnings: output.warnings
+                };
+            }
+            case "map": {
+                const output = await this.deps.findMapping({
+                    version: input.version,
+                    kind: subjectKind,
+                    name: input.subject.name,
+                    owner: input.subject.owner,
+                    descriptor: input.subject.descriptor,
+                    sourceMapping: input.sourceMapping ?? "obfuscated",
+                    targetMapping: input.targetMapping ?? "mojang",
+                    signatureMode: input.signatureMode,
+                    maxCandidates: input.maxCandidates
+                });
+                return {
+                    ...buildEntryToolResult({
+                        task: "map",
+                        detail,
+                        include,
+                        summary: {
+                            status: summaryStatusFromResolution(output.status),
+                            headline: output.resolved
+                                ? `Mapped the symbol into ${output.mappingContext.targetMapping}.`
+                                : `Found ${output.candidateCount} candidate mappings.`,
+                            counts: {
+                                candidates: output.candidateCount
+                            }
+                        },
+                        blocks: {
+                            match: output.resolvedSymbol,
+                            candidates: output.candidates,
+                            ambiguity: output.ambiguityReasons ? { reasons: output.ambiguityReasons } : undefined
+                        }
+                    }),
+                    warnings: output.warnings
+                };
+            }
+            case "exact-map": {
+                if (!input.subject.owner || !input.subject.descriptor) {
+                    throw createError({
+                        code: ERROR_CODES.INVALID_INPUT,
+                        message: "task=exact-map requires owner and descriptor."
+                    });
+                }
+                const output = await this.deps.resolveMethodMappingExact({
+                    version: input.version,
+                    owner: input.subject.owner,
+                    name: input.subject.name,
+                    descriptor: input.subject.descriptor,
+                    sourceMapping: input.sourceMapping ?? "obfuscated",
+                    targetMapping: input.targetMapping ?? "mojang",
+                    maxCandidates: input.maxCandidates
+                });
+                return {
+                    ...buildEntryToolResult({
+                        task: "exact-map",
+                        detail,
+                        include,
+                        summary: {
+                            status: summaryStatusFromResolution(output.status),
+                            headline: output.resolved
+                                ? "Resolved the exact method mapping."
+                                : "Could not resolve the exact method mapping.",
+                            counts: {
+                                candidates: output.candidateCount
+                            }
+                        },
+                        blocks: {
+                            match: output.resolvedSymbol,
+                            candidates: output.candidates
+                        }
+                    }),
+                    warnings: output.warnings
+                };
+            }
+            case "lifecycle": {
+                const output = await this.deps.traceSymbolLifecycle({
+                    symbol: input.subject.owner
+                        ? `${input.subject.owner}.${input.subject.name}`
+                        : input.subject.name,
+                    descriptor: input.subject.descriptor,
+                    mapping: input.sourceMapping
+                });
+                return {
+                    ...buildEntryToolResult({
+                        task: "lifecycle",
+                        detail,
+                        include,
+                        summary: {
+                            status: output.presence.firstSeen ? "ok" : "not_found",
+                            headline: output.presence.firstSeen
+                                ? `Tracked the symbol from ${output.range.fromVersion} to ${output.range.toVersion}.`
+                                : "The symbol was not found in the scanned version range.",
+                            counts: {
+                                scannedVersions: output.range.scannedCount
+                            }
+                        },
+                        blocks: {
+                            match: output.query,
+                            timeline: output.timeline
+                        }
+                    }),
+                    warnings: output.warnings
+                };
+            }
+            case "workspace": {
+                const output = await this.deps.resolveWorkspaceSymbol({
+                    projectPath: input.projectPath,
+                    version: input.version ?? "unknown",
+                    kind: subjectKind,
+                    name: input.subject.name,
+                    owner: input.subject.owner,
+                    descriptor: input.subject.descriptor,
+                    sourceMapping: input.sourceMapping ?? "obfuscated",
+                    maxCandidates: input.maxCandidates
+                });
+                return {
+                    ...buildEntryToolResult({
+                        task: "workspace",
+                        detail,
+                        include,
+                        summary: {
+                            status: summaryStatusFromResolution(output.status),
+                            headline: output.workspaceDetection.resolved
+                                ? `Resolved compile-visible symbol using ${output.workspaceDetection.mappingApplied} workspace mappings.`
+                                : "Workspace compile mapping could not be detected confidently.",
+                            counts: {
+                                candidates: output.candidateCount
+                            }
+                        },
+                        blocks: {
+                            match: output.resolvedSymbol,
+                            candidates: output.candidates,
+                            workspace: output.workspaceDetection
+                        }
+                    }),
+                    warnings: [...output.warnings, ...output.workspaceDetection.warnings]
+                };
+            }
+            case "api-overview": {
+                const output = await this.deps.getClassApiMatrix({
+                    version: input.version,
+                    className: input.subject.name,
+                    classNameMapping: input.classNameMapping ?? "obfuscated",
+                    includeKinds: input.includeKinds,
+                    maxRows: input.maxRows
+                });
+                return {
+                    ...buildEntryToolResult({
+                        task: "api-overview",
+                        detail,
+                        include,
+                        summary: {
+                            status: "ok",
+                            headline: `Built an API overview for ${output.className}.`,
+                            counts: {
+                                rows: output.rowCount,
+                                ambiguousRows: output.ambiguousRowCount ?? 0
+                            }
+                        },
+                        blocks: {
+                            match: {
+                                className: output.className,
+                                classIdentity: output.classIdentity
+                            },
+                            matrix: include.includes("matrix") || detail !== "summary"
+                                ? {
+                                    rowCount: output.rowCount,
+                                    rowsTruncated: output.rowsTruncated,
+                                    rows: output.rows.slice(0, 25)
+                                }
+                                : undefined
+                        }
+                    }),
+                    warnings: output.warnings
+                };
+            }
+        }
+    }
+}
+//# sourceMappingURL=analyze-symbol-service.js.map

package/dist/entry-tools/compare-minecraft-service.d.ts

@@ -0,0 +1,210 @@
+import { z } from "zod";
+import type { DiffClassSignaturesOutput } from "../source-service.js";
+import type { CompareVersionsOutput } from "../version-diff-service.js";
+import type { GetRegistryDataOutput } from "../registry-service.js";
+export declare const compareMinecraftShape: {
+    task: z.ZodOptional<z.ZodEnum<["auto", "versions", "class-diff", "registry-diff", "migration-overview"]>>;
+    subject: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"version-pair">;
+        fromVersion: z.ZodString;
+        toVersion: z.ZodString;
+        packageFilter: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "version-pair";
+        fromVersion: string;
+        toVersion: string;
+        packageFilter?: string | undefined;
+    }, {
+        kind: "version-pair";
+        fromVersion: string;
+        toVersion: string;
+        packageFilter?: string | undefined;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"class">;
+        className: z.ZodString;
+        fromVersion: z.ZodString;
+        toVersion: z.ZodString;
+        mapping: z.ZodOptional<z.ZodEnum<["obfuscated", "mojang", "intermediary", "yarn"]>>;
+        sourcePriority: z.ZodOptional<z.ZodEnum<["loom-first", "maven-first"]>>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "class";
+        className: string;
+        fromVersion: string;
+        toVersion: string;
+        mapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
+        sourcePriority?: "loom-first" | "maven-first" | undefined;
+    }, {
+        kind: "class";
+        className: string;
+        fromVersion: string;
+        toVersion: string;
+        mapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
+        sourcePriority?: "loom-first" | "maven-first" | undefined;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"registry">;
+        fromVersion: z.ZodString;
+        toVersion: z.ZodString;
+        registry: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "registry";
+        fromVersion: string;
+        toVersion: string;
+        registry?: string | undefined;
+    }, {
+        kind: "registry";
+        fromVersion: string;
+        toVersion: string;
+        registry?: string | undefined;
+    }>]>;
+    detail: z.ZodOptional<z.ZodEnum<["summary", "standard", "full"]>>;
+    include: z.ZodOptional<z.ZodArray<z.ZodEnum<[string, ...string[]]>, "many">>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    maxClassResults: z.ZodOptional<z.ZodNumber>;
+    maxEntriesPerRegistry: z.ZodOptional<z.ZodNumber>;
+    includeFullDiff: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const compareMinecraftSchema: z.ZodObject<{
+    task: z.ZodOptional<z.ZodEnum<["auto", "versions", "class-diff", "registry-diff", "migration-overview"]>>;
+    subject: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"version-pair">;
+        fromVersion: z.ZodString;
+        toVersion: z.ZodString;
+        packageFilter: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "version-pair";
+        fromVersion: string;
+        toVersion: string;
+        packageFilter?: string | undefined;
+    }, {
+        kind: "version-pair";
+        fromVersion: string;
+        toVersion: string;
+        packageFilter?: string | undefined;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"class">;
+        className: z.ZodString;
+        fromVersion: z.ZodString;
+        toVersion: z.ZodString;
+        mapping: z.ZodOptional<z.ZodEnum<["obfuscated", "mojang", "intermediary", "yarn"]>>;
+        sourcePriority: z.ZodOptional<z.ZodEnum<["loom-first", "maven-first"]>>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "class";
+        className: string;
+        fromVersion: string;
+        toVersion: string;
+        mapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
+        sourcePriority?: "loom-first" | "maven-first" | undefined;
+    }, {
+        kind: "class";
+        className: string;
+        fromVersion: string;
+        toVersion: string;
+        mapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
+        sourcePriority?: "loom-first" | "maven-first" | undefined;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"registry">;
+        fromVersion: z.ZodString;
+        toVersion: z.ZodString;
+        registry: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "registry";
+        fromVersion: string;
+        toVersion: string;
+        registry?: string | undefined;
+    }, {
+        kind: "registry";
+        fromVersion: string;
+        toVersion: string;
+        registry?: string | undefined;
+    }>]>;
+    detail: z.ZodOptional<z.ZodEnum<["summary", "standard", "full"]>>;
+    include: z.ZodOptional<z.ZodArray<z.ZodEnum<[string, ...string[]]>, "many">>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    maxClassResults: z.ZodOptional<z.ZodNumber>;
+    maxEntriesPerRegistry: z.ZodOptional<z.ZodNumber>;
+    includeFullDiff: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    subject: {
+        kind: "version-pair";
+        fromVersion: string;
+        toVersion: string;
+        packageFilter?: string | undefined;
+    } | {
+        kind: "class";
+        className: string;
+        fromVersion: string;
+        toVersion: string;
+        mapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
+        sourcePriority?: "loom-first" | "maven-first" | undefined;
+    } | {
+        kind: "registry";
+        fromVersion: string;
+        toVersion: string;
+        registry?: string | undefined;
+    };
+    limit?: number | undefined;
+    maxClassResults?: number | undefined;
+    task?: "auto" | "versions" | "class-diff" | "registry-diff" | "migration-overview" | undefined;
+    detail?: "full" | "summary" | "standard" | undefined;
+    include?: string[] | undefined;
+    maxEntriesPerRegistry?: number | undefined;
+    includeFullDiff?: boolean | undefined;
+}, {
+    subject: {
+        kind: "version-pair";
+        fromVersion: string;
+        toVersion: string;
+        packageFilter?: string | undefined;
+    } | {
+        kind: "class";
+        className: string;
+        fromVersion: string;
+        toVersion: string;
+        mapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
+        sourcePriority?: "loom-first" | "maven-first" | undefined;
+    } | {
+        kind: "registry";
+        fromVersion: string;
+        toVersion: string;
+        registry?: string | undefined;
+    };
+    limit?: number | undefined;
+    maxClassResults?: number | undefined;
+    task?: "auto" | "versions" | "class-diff" | "registry-diff" | "migration-overview" | undefined;
+    detail?: "full" | "summary" | "standard" | undefined;
+    include?: string[] | undefined;
+    maxEntriesPerRegistry?: number | undefined;
+    includeFullDiff?: boolean | undefined;
+}>;
+export type CompareMinecraftInput = z.infer<typeof compareMinecraftSchema>;
+type CompareMinecraftDeps = {
+    compareVersions: (input: {
+        fromVersion: string;
+        toVersion: string;
+        category?: "classes" | "registry" | "all";
+        packageFilter?: string;
+        maxClassResults?: number;
+    }) => Promise<CompareVersionsOutput>;
+    diffClassSignatures: (input: {
+        className: string;
+        fromVersion: string;
+        toVersion: string;
+        mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn";
+        sourcePriority?: "loom-first" | "maven-first";
+        includeFullDiff?: boolean;
+    }) => Promise<DiffClassSignaturesOutput>;
+    getRegistryData: (input: {
+        version: string;
+        registry?: string;
+        includeData?: boolean;
+        maxEntriesPerRegistry?: number;
+    }) => Promise<GetRegistryDataOutput>;
+};
+export declare class CompareMinecraftService {
+    private readonly deps;
+    constructor(deps: CompareMinecraftDeps);
+    execute(input: CompareMinecraftInput): Promise<Record<string, unknown> & {
+        warnings?: string[];
+    }>;
+}
+export {};