@adhisang/minecraft-modding-mcp 4.0.0 → 4.1.1

package/dist/source-service.d.ts

@@ -1,16 +1,27 @@
-import { type ResponseContext as ExplorerResponseContext, type SignatureMember } from "./minecraft-explorer-service.js";
-import { type MixinValidationResult, type MixinValidationProvenance, type MappingHealthReport, type AccessWidenerValidationResult, type AccessTransformerValidationResult } from "./mixin-validator.js";
-import { type ClassApiMatrixInput as MappingClassApiMatrixInput, type ClassApiMatrixOutput as MappingClassApiMatrixOutput, type FindMappingInput as MappingFindMappingInput, type FindMappingOutput as MappingFindMappingOutput, type ResolveMethodMappingExactInput as MappingResolveMethodMappingExactInput, type ResolveMethodMappingExactOutput as MappingResolveMethodMappingExactOutput, type SymbolResolutionOutput as MappingSymbolResolutionOutput, type SymbolExistenceInput as MappingSymbolExistenceInput, type SymbolExistenceOutput as MappingSymbolExistenceOutput } from "./mapping-service.js";
+import { MinecraftExplorerService, type ResponseContext as ExplorerResponseContext, type SignatureMember } from "./minecraft-explorer-service.js";
+import { type MixinValidationResult, type MixinValidationProvenance, type MappingHealthReport, type AccessWidenerValidationResult, type AccessTransformerValidationResult, type MixinStageBudgets } from "./mixin-validator.js";
+import { MappingService, type ClassApiMatrixInput as MappingClassApiMatrixInput, type ClassApiMatrixOutput as MappingClassApiMatrixOutput, type FindMappingInput as MappingFindMappingInput, type FindMappingOutput as MappingFindMappingOutput, type ResolveMethodMappingExactInput as MappingResolveMethodMappingExactInput, type ResolveMethodMappingExactOutput as MappingResolveMethodMappingExactOutput, type SymbolResolutionOutput as MappingSymbolResolutionOutput, type SymbolExistenceInput as MappingSymbolExistenceInput, type SymbolExistenceOutput as MappingSymbolExistenceOutput } from "./mapping-service.js";
+import { ArtifactsRepo } from "./storage/artifacts-repo.js";
+import { FilesRepo } from "./storage/files-repo.js";
+import { IndexMetaRepo } from "./storage/index-meta-repo.js";
+import { SymbolsRepo } from "./storage/symbols-repo.js";
 import { RuntimeMetrics, type RuntimeMetricSnapshot } from "./observability.js";
-import { type WorkspaceCompileMappingOutput } from "./workspace-mapping-service.js";
-import type { AccessTransformerNamespace, ArtifactProvenance, ArtifactRow, ArtifactScope, Config, MappingSourcePriority, ResolvedSourceArtifact, SourceMapping, SourceTargetInput } from "./types.js";
-import { type ListVersionsInput, type ListVersionsOutput } from "./version-service.js";
-import { type GetRegistryDataInput, type GetRegistryDataOutput } from "./registry-service.js";
-import { type CompareVersionsInput, type CompareVersionsOutput } from "./version-diff-service.js";
-import { type DecompileModJarInput, type DecompileModJarOutput, type GetModClassSourceInput, type GetModClassSourceOutput } from "./mod-decompile-service.js";
-import { type SearchModSourceInput, type SearchModSourceOutput } from "./mod-search-service.js";
+import { SourceServiceState } from "./source/state.js";
+import * as indexer from "./source/indexer.js";
+import * as workspaceTarget from "./source/workspace-target.js";
+import * as validateMixinModule from "./source/validate-mixin.js";
+import * as artifactResolver from "./source/artifact-resolver.js";
+import { type StageEmitter } from "./stage-emitter.js";
+import { WorkspaceMappingService, type WorkspaceCompileMappingOutput } from "./workspace-mapping-service.js";
+import { type WorkspaceContextCache } from "./workspace-context-cache.js";
+import type { AccessTransformerNamespace, ArtifactProvenance, ArtifactRow, ArtifactScope, Config, MappingSourcePriority, ResolveArtifactTargetInput, ResolvedSourceArtifact, RuntimeValidationProvenance, SourceMapping } from "./types.js";
+import { VersionService, type ListVersionsInput, type ListVersionsOutput } from "./version-service.js";
+import { RegistryService, type GetRegistryDataInput, type GetRegistryDataOutput } from "./registry-service.js";
+import { VersionDiffService, type CompareVersionsInput, type CompareVersionsOutput } from "./version-diff-service.js";
+import { ModDecompileService, type DecompileModJarInput, type DecompileModJarOutput, type GetModClassSourceInput, type GetModClassSourceOutput } from "./mod-decompile-service.js";
+import { ModSearchService, type SearchModSourceInput, type SearchModSourceOutput } from "./mod-search-service.js";
 export type ResolveArtifactInput = {
-    target: SourceTargetInput;
+    target: ResolveArtifactTargetInput;
     mapping?: SourceMapping;
     sourcePriority?: MappingSourcePriority;
     allowDecompile?: boolean;
@@ -39,13 +50,29 @@ export type ResolveArtifactOutput = {
     warnings: string[];
     sampleEntries?: string[];
 };
+export type ProbeMinecraftArtifactInput = {
+    target: {
+        kind: "version";
+        value: string;
+    };
+    mapping?: SourceMapping;
+    sourcePriority?: MappingSourcePriority;
+    projectPath?: string;
+    scope?: ArtifactScope;
+    preferProjectVersion?: boolean;
+};
+export type ProbeMinecraftArtifactOutput = {
+    artifactId: string;
+    mappingApplied: SourceMapping;
+    warnings?: string[];
+};
 export type ArtifactContentsSummary = {
     sourceKind: "source-jar" | "decompiled-binary";
     indexedContentKinds: string[];
     resourcesIncluded: boolean;
     sourceCoverage: "full" | "partial";
 };
-type SymbolKind = "class" | "interface" | "enum" | "record" | "method" | "field";
+export type SymbolKind = "class" | "interface" | "enum" | "record" | "method" | "field";
 type SearchIntent = "symbol" | "text" | "path";
 type SearchMatch = "exact" | "prefix" | "contains" | "regex";
 export type SearchScope = {
@@ -146,7 +173,7 @@ export type ResolveWorkspaceSymbolOutput = MappingSymbolResolutionOutput & {
 export type SourceMode = "metadata" | "snippet" | "full";
 export type GetClassSourceInput = {
     artifactId?: string;
-    target?: SourceTargetInput;
+    target?: ResolveArtifactTargetInput;
     className: string;
     mode?: SourceMode;
     mapping?: SourceMapping;
@@ -203,7 +230,7 @@ export type FindClassOutput = {
 type MemberAccess = "public" | "all";
 export type GetClassMembersInput = {
     artifactId?: string;
-    target?: SourceTargetInput;
+    target?: ResolveArtifactTargetInput;
     className: string;
     mapping?: SourceMapping;
     sourcePriority?: MappingSourcePriority;
@@ -229,6 +256,7 @@ export type DecompiledFallback = {
     methods: DecompiledMember[];
     origin: "source-extracted";
 };
+export type GetClassMembersStatus = "ok" | "members_unavailable" | "partial";
 export type GetClassMembersOutput = {
     className: string;
     members: {
@@ -259,6 +287,12 @@ export type GetClassMembersOutput = {
         methods: number;
         total: number;
     };
+    status?: GetClassMembersStatus;
+    unavailableReason?: string;
+    suggestedCall?: {
+        tool: string;
+        params: Record<string, unknown>;
+    };
     warnings: string[];
 };
 export type TraceSymbolLifecycleInput = {
@@ -298,7 +332,7 @@ export type TraceSymbolLifecycleOutput = {
     timeline?: TraceSymbolLifecycleTimelineEntry[];
     warnings: string[];
 };
-type DiffClassChange = "added" | "removed" | "present_in_both" | "absent_in_both";
+export type DiffClassChange = "added" | "removed" | "present_in_both" | "absent_in_both";
 type DiffMemberChangedField = "accessFlags" | "isSynthetic" | "javaSignature" | "jvmDescriptor";
 export type DiffMember = SignatureMember;
 export type DiffMemberChange = {
@@ -359,24 +393,7 @@ export type DiffClassSignaturesOutput = {
     };
     warnings: string[];
 };
-export type IndexArtifactInput = {
-    artifactId: string;
-    force?: boolean;
-};
-type IndexRebuildReason = "force" | "missing_meta" | "schema_mismatch" | "signature_mismatch" | "already_current";
-export type IndexArtifactOutput = {
-    artifactId: string;
-    reindexed: boolean;
-    reason: IndexRebuildReason;
-    counts: {
-        files: number;
-        symbols: number;
-        ftsRows: number;
-    };
-    indexedAt: string;
-    durationMs: number;
-    mappingApplied: SourceMapping;
-};
+export type { IndexArtifactInput, IndexArtifactOutput } from "./source/indexer.js";
 export type ValidateMixinInput = {
     input: {
         mode: "inline";
@@ -411,6 +428,19 @@ export type ValidateMixinInput = {
     treatInfoAsWarning?: boolean;
     includeIssues?: boolean;
 };
+export type ValidateMixinOptions = {
+    stageEmitter?: StageEmitter;
+    /** Test-only override for stage budgets. Production code uses defaults. */
+    __stageBudgets?: Partial<MixinStageBudgets>;
+    /** Test-only hooks injected at stage boundaries to simulate slow work. */
+    __testHooks?: {
+        afterResolve?: () => Promise<void>;
+        afterMappingHealth?: () => Promise<void>;
+        afterParse?: () => Promise<void>;
+        beforeTargetLoop?: () => Promise<void>;
+        beforeTargetIter?: (targetIndex: number) => Promise<void>;
+    };
+};
 export type ValidateMixinResultSource = {
     kind: "inline" | "path" | "config";
     label: string;
@@ -421,6 +451,10 @@ export type ValidateMixinBatchResult = {
     source: ValidateMixinResultSource;
     result?: MixinValidationResult;
     error?: string;
+    /** Stable error code from AppError when the entry failed with a typed error (e.g. ERR_STAGE_BUDGET_PRE_PARSE). */
+    errorCode?: string;
+    /** AppError details (failedStage, stageBudgetExhausted, budgetMs, elapsedMs, …) preserved across batch aggregation. */
+    errorDetails?: Record<string, unknown>;
 };
 export type ValidateMixinBatchIssueSummaryItem = {
     kind: string;
@@ -469,52 +503,78 @@ export type ValidateAccessTransformerInput = {
 };
 export type ValidateAccessTransformerOutput = AccessTransformerValidationResult;
 export declare class SourceService {
-    private readonly config;
-    private readonly db;
-    private readonly artifactsRepo;
-    private readonly filesRepo;
-    private readonly indexMetaRepo;
-    private readonly symbolsRepo;
-    private readonly metrics;
-    private readonly versionService;
-    private readonly mappingService;
-    private readonly workspaceMappingService;
-    private readonly explorerService;
-    private readonly registryService;
-    private readonly versionDiffService;
-    private readonly modDecompileService;
-    private readonly modSearchService;
-    private readonly lru;
-    private cacheTotalContentBytes;
-    private readonly remappedJarBytes;
-    /** In-flight binary-remap jobs keyed by remapped jar path so concurrent
-     * resolveArtifact calls for the same artifactId share a single tiny-remapper run. */
-    private readonly inflightRemaps;
-    constructor(explicitConfig?: Config, metrics?: RuntimeMetrics);
-    private discoverVersionSourceJar;
-    private discoverAccessWidenerRuntimeCandidates;
-    private discoverAccessTransformerRuntimeCandidates;
-    private resolveAccessWidenerRuntimeArtifact;
-    private resolveAccessTransformerNamespace;
-    private resolveAccessTransformerRuntimeArtifact;
-    private buildVersionSourceRecoveryCommand;
-    /**
-     * Decide whether the upcoming resolveArtifact call may transparently remap a
-     * binary-only artifact (obfuscated -> mojang) and decompile it. The gate
-     * succeeds only when:
-     *   - the requested mapping is "mojang" on a still-obfuscated runtime
-     *   - tiny-remapper jar is downloadable / available locally
-     *   - the version's Mojang tiny mapping file can be produced
-     *   - checkMappingHealth reports mojang mappings are usable
-     * On any failure the variant defaults to "pass" so the legacy
-     * MAPPING_NOT_APPLIED fallback (or the existing source-backed flow) keeps
-     * its existing artifactId hash.
-     */
-    private computeBinaryRemapGate;
-    private buildArtifactContentsSummary;
-    private inferVersionFromContext;
-    private resolveVersionContext;
+    readonly config: Config;
+    readonly db: import("./storage/sqlite.js").default;
+    readonly artifactsRepo: ArtifactsRepo;
+    readonly filesRepo: FilesRepo;
+    readonly indexMetaRepo: IndexMetaRepo;
+    readonly symbolsRepo: SymbolsRepo;
+    readonly metrics: RuntimeMetrics;
+    readonly versionService: VersionService;
+    readonly mappingService: MappingService;
+    readonly workspaceMappingService: WorkspaceMappingService;
+    readonly workspaceContextCache: WorkspaceContextCache;
+    readonly explorerService: MinecraftExplorerService;
+    readonly registryService: RegistryService;
+    readonly versionDiffService: VersionDiffService;
+    readonly modDecompileService: ModDecompileService;
+    readonly modSearchService: ModSearchService;
+    readonly state: SourceServiceState;
+    constructor(explicitConfig?: Config, metrics?: RuntimeMetrics, deps?: {
+        workspaceContextCache?: WorkspaceContextCache;
+    });
     resolveArtifact(input: ResolveArtifactInput): Promise<ResolveArtifactOutput>;
+    probeMinecraftArtifact(input: ProbeMinecraftArtifactInput): Promise<ProbeMinecraftArtifactOutput>;
+    synthesizeWorkspaceTarget(input: ResolveArtifactInput, workspace: import("./types.js").WorkspaceTargetInput): ReturnType<typeof workspaceTarget.synthesizeWorkspaceTarget>;
+    synthesizeDependencyTarget(input: ResolveArtifactInput, dep: import("./types.js").DependencyTargetInput): ReturnType<typeof workspaceTarget.synthesizeDependencyTarget>;
+    loadOrDetectWorkspaceContext(projectPath: string): ReturnType<typeof workspaceTarget.loadOrDetectWorkspaceContext>;
+    resolveAccessWidenerRuntimeArtifact(input: {
+        version: string;
+        awNamespace: SourceMapping;
+        projectPath?: string;
+        scope?: ArtifactScope;
+        preferProjectVersion?: boolean;
+    }): Promise<RuntimeValidationProvenance<SourceMapping>>;
+    resolveAccessTransformerNamespace(input: {
+        atNamespace?: AccessTransformerNamespace;
+        projectPath?: string;
+    }): Promise<AccessTransformerNamespace>;
+    resolveAccessTransformerRuntimeArtifact(input: {
+        version: string;
+        atNamespace: AccessTransformerNamespace;
+        projectPath?: string;
+        scope?: ArtifactScope;
+        preferProjectVersion?: boolean;
+    }): Promise<RuntimeValidationProvenance<AccessTransformerNamespace>>;
+    buildArtifactContentsSummary(input: {
+        origin: ResolvedSourceArtifact["origin"];
+        sourceJarPath?: string;
+        isDecompiled?: boolean;
+        qualityFlags: string[];
+    }): ArtifactContentsSummary;
+    discoverVersionSourceJar(input: {
+        version: string;
+        projectPath?: string;
+    }): ReturnType<typeof artifactResolver.discoverVersionSourceJar>;
+    discoverAccessWidenerRuntimeCandidates(input: {
+        version: string;
+        projectPath?: string;
+        requestedScope: ArtifactScope;
+    }): ReturnType<typeof artifactResolver.discoverAccessWidenerRuntimeCandidates>;
+    discoverAccessTransformerRuntimeCandidates(input: {
+        version: string;
+        projectPath?: string;
+        requestedScope: ArtifactScope;
+        atNamespace: AccessTransformerNamespace;
+        loader: import("./workspace-mapping-service.js").WorkspaceProjectLoader | "unknown";
+    }): ReturnType<typeof artifactResolver.discoverAccessTransformerRuntimeCandidates>;
+    buildMappingFallbackSuggestedCall(args: {
+        input: ResolveArtifactInput;
+        kind: import("./types.js").ArtifactTargetKind;
+        value: string;
+        scope: ArtifactScope | undefined;
+        effectiveMapping: SourceMapping;
+    }): ReturnType<typeof artifactResolver.buildMappingFallbackSuggestedCall>;
     searchClassSource(input: SearchClassSourceInput): Promise<SearchClassSourceOutput>;
     getArtifactFile(input: GetArtifactFileInput): Promise<GetArtifactFileOutput>;
     listArtifactFiles(input: ListArtifactFilesInput): Promise<ListArtifactFilesOutput>;
@@ -535,103 +595,37 @@ export declare class SourceService {
     findClass(input: FindClassInput): FindClassOutput;
     getClassSource(input: GetClassSourceInput): Promise<GetClassSourceOutput>;
     getClassMembers(input: GetClassMembersInput): Promise<GetClassMembersOutput>;
-    private buildDecompiledFallback;
-    validateMixin(input: ValidateMixinInput): Promise<ValidateMixinOutput>;
-    private runValidateMixinDispatcher;
-    private createProjectValidateMixinConfigInput;
-    private shouldRetryValidateMixinWithMavenFirst;
-    private findValidateMixinClassMapping;
-    private validateMixinSingle;
-    private runValidateMixinPipeline;
-    private resolveMixinInputPath;
-    private resolveMixinConfigSources;
-    private validateMixinMany;
-    private applyValidateMixinOutputCompaction;
-    private buildValidateMixinOutput;
+    validateMixin(input: ValidateMixinInput, options?: ValidateMixinOptions): Promise<ValidateMixinOutput>;
+    validateMixinSingle(input: validateMixinModule.ValidateMixinSingleInput): Promise<MixinValidationResult>;
+    remapSignatureMembers(members: SignatureMember[], kind: "field" | "method", version: string, sourceMapping: SourceMapping, targetMapping: SourceMapping, sourcePriority: MappingSourcePriority | undefined, warnings: string[], projectPath?: string): Promise<{
+        members: SignatureMember[];
+        failedNames: Set<string>;
+    }>;
     validateAccessWidener(input: ValidateAccessWidenerInput): Promise<ValidateAccessWidenerOutput>;
     validateAccessTransformer(input: ValidateAccessTransformerInput): Promise<ValidateAccessTransformerOutput>;
     recordToolCall(tool: string, durationMs: number): void;
     getRuntimeMetrics(): RuntimeMetricSnapshot;
-    indexArtifact(input: IndexArtifactInput): Promise<IndexArtifactOutput>;
-    private searchSymbolIntent;
-    private searchTextIntentIndexed;
-    private searchPathIntentIndexed;
-    private searchTextIntent;
-    private searchPathIntent;
-    private findSymbolHits;
-    private indexedCandidateLimit;
-    private indexedCandidateLimitForMatch;
-    private extractClassMetadata;
-    private extractDecompiledMembers;
-    private computeLineBraceDepths;
-    private computeBraceRange;
-    private scanBraceRange;
-    private computeNestedTypeRanges;
-    private resolveClassFilePath;
-    private resolveBinaryFallbackArtifact;
-    private buildProvenance;
-    private buildFallbackProvenance;
-    private resolveClassNameForLookup;
-    private buildClassSourceNotFoundError;
-    private rejectLifecycleClassLikeInput;
-    private releaseLifecycleMappingGraph;
-    private resolveToObfuscatedClassName;
-    private resolveToObfuscatedMemberName;
-    private remapSignatureMembers;
-    private fallbackArtifactSignature;
-    private resolveIndexRebuildReason;
-    private toResolvedArtifact;
-    private rebuildAndPersistArtifactIndex;
-    private buildRebuiltArtifactData;
+    indexArtifact(input: indexer.IndexArtifactInput): Promise<indexer.IndexArtifactOutput>;
+    resolveClassNameForLookup(input: {
+        className: string;
+        version?: string;
+        sourceMapping: SourceMapping;
+        targetMapping: SourceMapping;
+        sourcePriority: MappingSourcePriority | undefined;
+        warnings: string[];
+        context: string;
+    }): Promise<string>;
+    resolveBinaryFallbackArtifact(input: {
+        binaryJarPath?: string;
+        version?: string;
+        coordinate?: string;
+        requestedMapping: SourceMapping;
+        mappingApplied: SourceMapping;
+        provenance?: ArtifactProvenance;
+        qualityFlags: string[];
+    }): Promise<ResolvedSourceArtifact | undefined>;
     getArtifact(artifactId: string): ArtifactRow;
-    private ingestIfNeeded;
-    /**
-     * If the resolved artifact's transformChain promised an "obf -> mojang"
-     * binary remap, run tiny-remapper now and return the remapped jar path.
-     * Otherwise return the original binaryJarPath unchanged.
-     *
-     * Cache safety: writes to a per-attempt temp file then atomic-renames into
-     * <cacheDir>/remapped/<artifactId>.jar. A per-target inflight Promise map
-     * collapses concurrent calls so two simultaneous resolveArtifact calls for
-     * the same artifactId share one tiny-remapper run instead of racing on the
-     * same output path.
-     */
-    private maybeRemapBinaryForMojang;
-    private recordRemappedJarBytesFromDisk;
-    /**
-     * Best-effort structural check that `path` is a non-empty file beginning with
-     * the ZIP local-file-header magic (`50 4B 03 04`). Used to drop partial /
-     * corrupt remap-cache entries before they reach Vineflower. False positives
-     * are acceptable (Vineflower will surface a clearer error); false negatives
-     * are not (a corrupt cache hit must be evicted).
-     */
-    private isUsableJarFile;
-    private runBinaryRemap;
-    private loadFromSourceJar;
-    private hasAnyFiles;
-    /**
-     * Best-effort cleanup of `<cacheDir>/remapped/<artifactId>.jar` written by
-     * `maybeRemapBinaryForMojang`. Called from cache-eviction paths so the
-     * Mojang-remapped binary jar does not outlive the artifact row that owns it.
-     * Also releases the jar's bytes from `cacheTotalContentBytes`. Errors are
-     * swallowed: orphaned jars remain visible to `manage-cache` under the
-     * `binary-remap` cache kind and can be reclaimed there.
-     */
-    private unlinkRemappedJarForArtifact;
-    /**
-     * Add the remapped jar's on-disk size to `cacheTotalContentBytes` so the
-     * `enforceCacheLimits` byte gate sees the jar before deciding to evict.
-     * Without this, a Mojang-remapped client jar (tens of MB) can accumulate
-     * silently while the indexed-source byte total stays below `maxCacheBytes`.
-     */
-    private recordRemappedJarBytes;
-    private releaseRemappedJarBytes;
-    private enforceCacheLimits;
+    ingestIfNeeded(resolved: ResolvedSourceArtifact): Promise<void>;
     private refreshCacheMetrics;
-    private touchCacheMetrics;
-    private upsertCacheMetrics;
-    private removeCacheMetrics;
-    private publishCacheMetrics;
     private snapshotLruAccounting;
 }
-export {};