@adhisang/minecraft-modding-mcp 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.2.0] - 2026-04-12
+
+### Added
+- `resolve-artifact`, `find-mapping`, `resolve-method-mapping-exact`, `resolve-workspace-symbol`, and `check-symbol-exists` now accept an optional `compact` parameter (default `false`). When `true`, empty arrays, null values, and empty objects are stripped from the top-level response. For `resolve-artifact`, compact mode additionally omits `provenance`, `artifactContents`, `sampleEntries`, `adjacentSourceCandidates`, `binaryJarPath`, `coordinate`, `repoUrl`, and `resolvedSourceJarPath`. For mapping tools, compact mode omits the redundant `candidates` array when the result is a single full-confidence exact-match resolution.
+- `validate-access-widener` now accepts `projectPath`, `scope`, and `preferProjectVersion` for runtime-aware validation against Loom runtime jars, and reports additive `provenance`, `resolvedInRuntime`, and `resolvedRuntimeAccess` evidence for matched class, method, and field entries.
+- Added `validate-access-transformer` for Forge / NeoForge Access Transformer validation, including `atNamespace` support, workspace-driven namespace inference, runtime artifact provenance, and per-entry runtime access evidence.
+- `analyze-mod-jar` now surfaces packaged Access Transformer paths alongside mod metadata.
+
+### Fixed
+- `validate-access-widener` and `validate-access-transformer` runtime-aware method validation now preserves remapped JVM descriptors through exact and fallback member remaps, eliminating false-negative `method not found` results for entries whose descriptors reference remapped Minecraft classes such as `Level#setBlock(BlockPos, BlockState, int)`.
+- `validate-access-widener` runtime-aware `scope: "merged"` now prefers explicit `*merged-intermediary*` / `*merged-mojang*` runtime jars over ambiguous `minecraft-merged.jar` candidates, and Loom tiny lookup now scans workspace and Gradle user-home caches so runtime validation can resolve descriptor remaps in normal Loom setups.
+- `validate-project` now forwards workspace runtime context to discovered Access Widener validation so project-summary runs can use the same runtime-aware behavior as direct `validate-access-widener` calls.
+- `validate-project` now discovers Access Transformer files, supports `task="access-transformer"`, and can include those validations in workspace summaries when `discover` requests them.
+- `resolve-artifact`, `get-class-source`, `get-class-members`, and `inspect-minecraft` source/class-member flows now treat unobfuscated releases such as `26.1+` as native `mojang` runtime namespaces for both version and versioned-coordinate targets, avoiding false `ERR_MAPPING_NOT_APPLIED` failures and wrong-version Loom source-jar approximations when no exact source jar is present.
+- `validate-mixin` tool-health diagnostics now treat unobfuscated `mojang` runtime names as available, while still flagging `intermediary`/`yarn` as unavailable on `26.1+`.
+- `validate-project task="project-summary"` now pre-resolves `preferProjectVersion=true` consistently across discovered Access Widener and workspace Mixin checks, and returns a blocked summary with version-agnostic recovery guidance when discovered validators need a version but neither the request nor `gradle.properties` can supply one.
+- `check-symbol-exists` and `analyze-symbol task="exists"` now fall back to unobfuscated runtime bytecode for `mojang`/runtime-name existence checks on `26.1+`, preserve the original `mapping_unavailable` result when the runtime JAR cannot be resolved, and return a targeted warning when callers provide only a short class name.
+- Loom tiny mapping discovery no longer performs unbounded directory traversal when the version-specific cache directory is absent, preventing excessive memory consumption on systems with large Gradle caches.
+- Mapping graph cache eviction after lifecycle scans now correctly releases all cached entries for a version instead of silently skipping them.
+
+### Performance
+- `resolve-artifact` source-jar detection and mapping tiny-jar loading now reuse a single ZIP walk per jar probe instead of reopening and fully enumerating matching archives on each helper call.
+- `search-mod-source`, `decompile-mod-jar`, `get-mod-class-source`, `validate-project` workspace discovery, and workspace mapping detection now avoid synchronous hot-path file/glob reads and use bounded concurrent text reads where safe, reducing event-loop stalls on larger decompiled outputs and multi-module workspaces.
+
+## [3.1.1] - 2026-03-21
+
+### Fixed
+- `analyze-symbol task="api-overview"` now inherits `sourceMapping` as the default `classNameMapping`, avoiding unintended fallback to `obfuscated` when callers omit `classNameMapping`.
+- `get-class-api-matrix` now builds rows from the explicitly requested `classNameMapping` instead of silently pivoting to `obfuscated` when both identities are available.
+- `find-mapping` now accepts short obfuscated class ids such as `dhl` when `sourceMapping="obfuscated"` instead of rejecting them at input validation.
+- `find-mapping` now restores `mojang -> intermediary`, `mojang -> yarn`, and `intermediary -> mojang` conversions on mappings builds where those paths previously failed.
+- `trace-symbol-lifecycle` now strips an accidental inline signature suffix from `symbol` before splitting `Class.method`, preventing misparsed lifecycle lookups while keeping the separate `descriptor` field as the exact-match path.
+- `trace-symbol-lifecycle` now rejects class-like `symbol` inputs such as `net.minecraft.world.item.Item` with `ERR_INVALID_INPUT` instead of scanning versions until lookup work fails elsewhere.
+- `analyze-symbol task="lifecycle"` now applies its required `version` as the lifecycle scan upper bound instead of ignoring that input and always scanning the default full range, and the high-level helper now keeps that scan to a recent 5-version window for predictable runtime.
+- `trace-symbol-lifecycle` now completes broad lifecycle scans more reliably without long stalls.
+- `analyze-mod` and `validate-project` now return retryable `suggestedCall` guidance when older string-subject or domain-include payloads fail with `ERR_INVALID_INPUT`.
+- `validate-mixin` and `validate-project task="project-summary"` now treat empty mixin configs as warning-only discovery results with zero validated classes instead of `ERR_INVALID_INPUT`.
+- `inspect-minecraft` now keeps workspace `class-overview`, class-like `search`, and `list-files` usable when source coverage is partial, with partial-status guidance where needed.
+- `inspect-minecraft` invalid task/subject combinations now return retryable `suggestedCall` guidance instead of dead-end `ERR_INVALID_INPUT` messages, preserving the requested task when artifact context is the only missing input and otherwise pointing to the subject-compatible retry path.
+- Path-based environment overrides now treat blank values and the literal strings `undefined` and `null` as unset, preventing accidental `./undefined` and `./null` cache roots and invalid JAR override paths when clients serialize missing values incorrectly.
+
+### Performance
+- `trace-symbol-lifecycle`, `check-symbol-exists`, and `find-mapping` now respond faster on Mojang/obfuscated-only workflows, especially on cold lookups.
+
+### Documentation
+- Shortened the English and Japanese READMEs so onboarding guidance, workflow notes, and detailed reference material no longer repeat the same content across multiple sections.
+- Simplified the generated tool-surface tables in both READMEs to compact purpose-only summaries and pointed exact input/output details to `docs/tool-reference.md`.
+- Rewrote the Japanese workflow guidance in more natural Japanese and clarified that the detailed examples and full reference remain English-first for now.
+
 ## [3.1.0] - 2026-03-15
 
 ### Changed
@@ -16,15 +65,11 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 - Error recovery payloads (`suggestedCall`) now omit parameters when the supplied value matches the tool's default behavior, keeping retryable calls smaller without changing their semantics.
 
 ### Performance
-- Explicit text/path scan fallbacks no longer materialize the full scoped file-path list before scanning, reducing heap growth and keeping full-scan cost more predictable on large artifacts.
-- Runtime metrics now keep cache LRU byte-accounting rows by reference and only materialize `cache_artifact_bytes_lru` during snapshot reads, removing per-publish array copies from the cache hit path.
+- Explicit text and path scan fallbacks in `search-class-source` now use less memory and stay more predictable on large artifacts.
 
 ### Documentation
-- README tool tables are now validated from a shared contract manifest in code, correcting the documented `compare-minecraft` class-only `subject.kind="class".sourcePriority` input and aligning the published `inspect-minecraft` / `validate-project` output summaries with the implementation.
-- Clarified the updated `search-class-source` `queryMode` behavior and the summary-first follow-up contract for the top-level workflow tools in both READMEs.
+- Corrected the published `compare-minecraft` class-only `subject.kind="class".sourcePriority` input and aligned the documented `inspect-minecraft` / `validate-project` outputs with current behavior.
 - Documented that safe fixed defaults now appear in `tools/list` schema output and that `suggestedCall` omits default-valued parameters.
-- Reorganized the English README around package-user quick start, start-here examples, and linked reference docs so setup guidance is easier to scan without losing detailed contract notes.
-- Synchronized the Japanese README with the current English README structure, examples, quick-start guidance, and tool-surface summary.
 
 ## [3.0.0] - 2026-03-09
 
@@ -33,9 +78,6 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 - The new v3 entry tools share `detail` / `include` response shaping and always return `result.summary` inside the standard `{ result?, error?, meta }` envelope, reducing default payload size and making next actions explicit.
 - `analyze-mod` now exposes `executionMode="preview" | "apply"` for safe remap planning and execution, and `manage-cache` now exposes the same preview/apply model for cache deletion, pruning, and rebuild workflows.
 
-### Documentation
-- Added v3 entry-tool usage guidance, shared response-shaping notes, and entry-tool-first migration guidance to both READMEs.
-
 ### Fixed
 - `inspect-minecraft` now routes `subject.kind="workspace"` requests with `focus.kind="class" | "file" | "search"` through the matching task for `task=auto`, while preserving workspace-aware artifact resolution for focused file and search follow-up flows.
 - `inspect-minecraft task=class-overview | class-source | class-members` now accepts `subject.kind="workspace"` with `focus.kind="class"` even when the focus omits an explicit artifact reference, reusing workspace version detection to resolve artifact context first.
@@ -56,8 +98,8 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ### Fixed
 - `compare-versions` now applies `packageFilter` consistently to `classes.addedCount`, `removedCount`, and `unchanged`, so class summary counts reflect the same filtered package scope as the returned class lists.
-- Heavy analysis tools are now serialized behind a bounded in-process queue, and queue overflow fails fast with `ERR_LIMIT_EXCEEDED` instead of amplifying concurrent load across the whole MCP transport.
-- The stdio CLI entrypoint now supervises an internal worker process, automatically restarts it after an unexpected exit, replays MCP initialization for the live session, and turns in-flight crashes into retryable JSON-RPC request failures instead of a full transport disconnect.
+- Heavy analysis tools now fail fast with `ERR_LIMIT_EXCEEDED` when too many expensive requests arrive at once, instead of letting the whole MCP session degrade under load.
+- The stdio CLI now recovers more cleanly from unexpected internal exits, reducing full-session disconnects during live use.
 - `trace-symbol-lifecycle` now uses strict method remapping when a descriptor is provided, falls back to name-only lookup when it is omitted, and surfaces real mapping input failures in warnings instead of collapsing them into generic lookup errors.
 - `get-class-source` / `get-class-members` now infer a missing artifact version from `projectPath` when `preferProjectVersion=true`, making project-aware lookups more consistent for previously resolved artifacts.
 - Error recovery payloads (`suggestedCall`) now use the current `target` object schema instead of deprecated `targetKind` / `targetValue` fields.
@@ -70,7 +112,7 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 - `resolve-workspace-symbol` now recognizes NeoForge ModDevGradle workspaces as `mojang` compile mappings instead of returning `mapping_unavailable`.
 - `resolve-artifact`, `get-class-source`, and `get-class-members` now preserve `ERR_JAR_NOT_FOUND` for missing `target.kind=jar` paths instead of leaking raw filesystem `ENOENT` failures through the public contract.
 - `get-registry-data` now invalidates corrupt cached `registries.json` snapshots, regenerates them on demand, and reports `ERR_REGISTRY_GENERATION_FAILED` when the regenerated snapshot is still unreadable.
-- `validate-mixin` now retries with `sourcePriority="maven-first"` after a partial `loom-first` validation caused by mapping/signature resolution limits, reducing false warnings from Loom-only resolution paths.
+- `validate-mixin` now retries with Maven mapping data after Loom-only partial results when that can complete validation, reducing false warnings.
 - `validate-mixin` no longer emits schema-invalid `check-symbol-exists` recovery payloads in `suggestedCall`; unsupported parameters such as `scope` and `projectPath` are omitted from those calls.
 - `validate-mixin` now lowers confidence for skipped member validation and exposes requested-vs-applied scope/source-priority details instead of making partial results look fully verified.
 - `validate-mixin` now follows the resolved artifact namespace during bytecode lookup for non-vanilla scopes, so `scope="merged"` on Mojang-mapped Loom workspaces validates against merged class names instead of falling back to false partial results and retry-driven timeouts.
@@ -80,13 +122,11 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 - `check-symbol-exists` no longer repeats raw Loom tiny-cache miss warnings when Maven tiny mappings successfully satisfy the lookup; successful fallback now emits concise fallback context instead.
 
 ### Documentation
-- Corrected the `compare-versions` README contract to document registry results under `result.registry`.
-- Documented the new compact-response options, `summary-first` validate-mixin mode, bare-string `target` recovery guidance, and updated token-efficient examples in both READMEs.
+- Corrected the published `compare-versions` response docs to show registry results under `result.registry`.
 
 ### Performance
-- `resolve-artifact`, `index-artifact`, and `get-runtime-metrics` now keep cache entry/byte accounting incrementally during ingest, reindex, cache hits, and eviction, avoiding repeated full-cache rescans after each artifact load.
-- `find-mapping`, `get-class-api-matrix`, `resolve-workspace-symbol`, `check-symbol-exists`, and `validate-mixin` now reuse hot-path mapping graph paths, class remaps, and normalization work, reducing latency for repeated namespace lookups and large Mixin validation batches.
-- Warm-cache source and mod workflows now avoid extra regex recompilation, statement-cache churn, and FIFO cache evictions across search, signature lookup, source resolution, and decompile paths.
+- Cache-heavy artifact loading and runtime metric reads now stay faster after repeated operations instead of rescanning cache state each time.
+- `find-mapping`, `get-class-api-matrix`, `resolve-workspace-symbol`, `check-symbol-exists`, and `validate-mixin` now respond faster on repeated mapping-heavy workflows.
 
 ## [2.0.0] - 2026-03-07
 
@@ -102,7 +142,7 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ### Fixed
 - `resolve-artifact`: `targetKind=coordinate` now reuses the local Gradle `modules-2` cache in addition to the local Maven repository and configured source repos, so cached third-party libraries such as Architectury can resolve without manual cache spelunking.
-- `resolve-artifact`: `mapping=mojang` + Loom merged source discovery now flags partial source coverage with `qualityFlags=["partial-source-no-net-minecraft"]` and a warning when the selected source jar does not actually contain `net.minecraft` entries.
+- `resolve-artifact`: `mapping=mojang` + Loom merged source discovery now warns when the selected source jar only provides partial Minecraft source coverage.
 - `get-class-source` / `get-class-members`: when an artifact is resolved from a `*-sources.jar`, the server now keeps the sibling binary jar and automatically falls back to it when source coverage is incomplete instead of treating the source jar as bytecode.
 - `get-class-source`: partial-source binary fallback now bypasses the same sibling `*-sources.jar` that triggered the miss, and fallback failures for vanilla classes point to `get-class-api-matrix` instead of misleading `find-class` recovery.
 - `get-class-members`: bytecode lookup now follows the resolved artifact namespace (`mappingApplied`) before remapping members back to the requested namespace, fixing merged Mojang artifacts that were incorrectly forced through obfuscated class names.
@@ -112,18 +152,14 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 - Tool input parsing now leaves nested `typedJson` and JSON Patch `value` payload fields untouched, even when their keys happen to match top-level numeric option names such as `limit` or `maxLines`.
 
 ### Performance
-- `search-class-source`: reduce search latency, heap growth, and DB round-trips by returning compact hits only and skipping snippet hydration, relation expansion, and `totalApprox` count queries.
-- Tool input preprocessing now stays shallow, avoiding recursive scans through large nested payloads such as NBT typed JSON and patch bodies.
+- `search-class-source` now returns compact hits more efficiently, reducing latency and memory use on larger artifacts.
 
 ## [1.2.1] - 2026-03-05
 
 ### Fixed
-- MCP startup regression: removed eager `SourceService` pre-initialization during server startup so `tools/list` handshakes are not blocked by SQLite initialization on slower environments.
+- MCP startup regression: `tools/list` handshakes no longer stall on SQLite initialization in slower environments.
 - Decompiler: skip Java/Vineflower availability checks when decompiled source is already cached, avoiding unnecessary startup errors on systems without Java.
 
-### Documentation
-- Clarified startup behavior in README (`SourceService` remains lazy and is not pre-initialized before tool discovery).
-
 ## [1.2.0] - 2026-03-05
 
 ### Added
@@ -165,12 +201,7 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 - Mojang proguard mapping: JVM descriptor parsing fixes.
 
 ### Changed
-- Lazy `SourceService` initialization — deferred until first tool/resource access, reducing cold-start latency during MCP handshake.
-- Eagerly init `SourceService` during MCP handshake idle time for faster first-request response.
-
-### Performance
-- Avoid duplicate UTF-8 decode during truncation.
-- Eager `SourceService` init during handshake idle time.
+- `SourceService` startup work now avoids slowing the MCP handshake while still using idle time to reduce the wait before the first source-heavy request.
 
 ## [1.1.1] - 2026-03-02
 
@@ -180,11 +211,8 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ## [1.1.0] - 2026-03-01
 
-### Changed
-- Migrate stdio transport from mcp-use to @modelcontextprotocol/sdk.
-
 ### Fixed
-- Restore Codex startup handshake compatibility by accepting both newline-delimited and `Content-Length` stdio framing.
+- Restore Codex startup handshake compatibility by accepting both newline-delimited and `Content-Length` stdio framing on stdio connections.
 
 ### Documentation
 - Add Quick Start setup for Claude Code, OpenAI Codex CLI, and Gemini CLI.

package/README.md

@@ -20,8 +20,8 @@
 - **Source Exploration**: browse and search decompiled Minecraft source code with line-level precision and cursor-paginated file listing
 - **Multi-Mapping Conversion**: translate class, field, and method names between `obfuscated`, `mojang`, `intermediary`, and `yarn`
 - **Version Comparison**: diff class signatures and registry entries between Minecraft versions
-- **Mod JAR Analysis**: extract metadata, dependencies, entrypoints, and Mixin configs from Fabric, Forge, and NeoForge mod JARs
-- **Mixin and Access Widener Validation**: validate source and `.accesswidener` files against a target Minecraft version
+- **Mod JAR Analysis**: extract metadata, dependencies, entrypoints, Mixin configs, and packaged Access Transformer paths from Fabric, Forge, and NeoForge mod JARs
+- **Mixin, Access Widener, and Access Transformer Validation**: validate source, `.accesswidener`, and Forge/NeoForge access transformer files against a target Minecraft version
 - **NBT Round-Trip**: decode NBT binary to typed JSON, apply RFC 6902 patches, and encode it back to NBT
 - **Registry Data and Runtime Metrics**: query generated registry snapshots and inspect cache and latency counters
 - **MCP Resources**: expose versions, class source, artifact metadata, and mappings through URI-based resources
@@ -128,21 +128,29 @@ Pass environment variables to override defaults:
 
 These six top-level workflow tools cover the common workflows and return summary-first results, so they are the best default starting points for agents and MCP clients.
 
+All six return `result.summary` first, and can include `summary.nextActions` when there is a clear follow-up step. Use the table for tool selection, then use the examples and reference docs for exact payloads.
+
 | Tool | Start here for |
 | --- | --- |
 | `inspect-minecraft` | versions, artifacts, classes, files, and source search |
 | `analyze-symbol` | symbol existence checks, mapping conversion, lifecycle tracing, and workspace symbol resolution |
 | `compare-minecraft` | version-pair diffs, class diffs, registry diffs, and migration-oriented overviews |
 | `analyze-mod` | mod metadata, decompile/search flows, class source, and safe remap preview/apply |
-| `validate-project` | workspace summaries plus direct Mixin and Access Widener validation |
+| `validate-project` | workspace summaries plus direct Mixin, Access Widener, and Access Transformer validation |
 | `manage-cache` | cache inventory, verification, and preview/apply cleanup workflows |
 
 ### Workflow Notes
 
-- These top-level workflow tools return `result.summary` first and include `summary.nextActions` when there is a clear follow-up step.
+Keep only the high-frequency notes here. For the full pitfall list, exact contract details, migration notes, and environment variables, see [docs/tool-reference.md](docs/tool-reference.md).
+
 - `search-class-source` defaults to `queryMode="auto"` and keeps separator queries such as `foo.bar`, `foo_bar`, and `foo$bar` on the indexed path. Use `queryMode="literal"` for an explicit full substring scan.
-- When a public parameter has a fixed safe default, `tools/list` exposes it through the JSON Schema `default` field.
-- Error recovery `suggestedCall` payloads omit parameters when the supplied value already matches the tool default, keeping retry calls smaller without changing behavior.
+- If you do not already have an artifact, prefer `subject.kind="workspace"` for `inspect-minecraft` instead of guessing artifact details. When artifact context is the only missing input, a retryable `suggestedCall` preserves the requested task.
+- `trace-symbol-lifecycle` expects `Class.method` in `symbol`. Keep exact overload matching in the separate `descriptor` field.
+- Workspace inspection can still confirm vanilla classes when source coverage is partial, and `inspect-minecraft task="list-files"` reports a partial result with follow-up guidance when that happens.
+- `check-symbol-exists` and `analyze-symbol task="exists"` now validate `mojang` lookups on unobfuscated releases such as `26.1+` against runtime bytecode when no mapping graph exists, preserve the original `mapping_unavailable` result if the runtime JAR itself cannot be resolved, and return a targeted warning when callers provide only a short class name.
+- `analyze-mod` and `validate-project` still require structured `subject` objects and canonical `include` groups, but stale string-subject or domain-include payloads now return `ERR_INVALID_INPUT` with a retryable `suggestedCall`.
+- `validate-project task="project-summary"` now pre-resolves `preferProjectVersion=true` consistently across discovered Access Widener, Access Transformer, and Mixin checks, and blocks with version-agnostic recovery guidance when discovered validators need a version but neither the request nor `gradle.properties` can supply one.
+- Local source-jar probing, decompiled mod source reads, and workspace discovery now avoid synchronous hot-path ZIP/file scans and use bounded concurrent reads where safe, so cold `resolve-artifact`, `analyze-mod`, and `validate-project` workflows stay more responsive on larger jars and multi-module workspaces.
 
 ### Inspect Minecraft source from a version
 
@@ -211,7 +219,7 @@ These six top-level workflow tools cover the common workflows and return summary
     "subject": {
       "kind": "workspace",
       "projectPath": "/workspace/modid",
-      "discover": ["mixins", "access-wideners"]
+      "discover": ["mixins", "access-wideners", "access-transformers"]
     },
     "preferProjectVersion": true,
     "preferProjectMapping": true
@@ -219,11 +227,13 @@ These six top-level workflow tools cover the common workflows and return summary
 }
 ```
 
+Workspace summaries still default to discovering mixins and access wideners. Add `"access-transformers"` to `subject.discover` when you want Access Transformer files included in the summary run.
+
 ## Documentation
 
-- [Detailed example requests](docs/examples.md)
-- [Tool and configuration reference](docs/tool-reference.md)
-- [日本語 README](docs/README-ja.md)
+- [Detailed example requests](docs/examples.md) for copyable payloads and common workflows
+- [Tool and configuration reference](docs/tool-reference.md) for exact inputs, outputs, resource behavior, environment variables, and migration notes
+- [日本語 README](docs/README-ja.md) for a Japanese onboarding overview
 
 ## Tool Surface
 
@@ -232,14 +242,14 @@ Start with these top-level workflow tools unless you already know the exact spec
 ### Top-Level Workflow Tools
 
 <!-- BEGIN GENERATED TOOL TABLE: v3-entry-tools -->
-| Tool | Purpose | Key Inputs | Key Outputs |
-| --- | --- | --- | --- |
-| `inspect-minecraft` | Start from a version, artifact, class, file, search query, or workspace and route to the most relevant Minecraft inspection flow | `task?`, `subject?`, `detail?`, `include?`, `limit?`, `cursor?`, `includeSnapshots?` | `result.summary`, `versions?`, `subject`, `artifact?`, `class?`, `source?`, `members?`, `search?`, `file?`, `files?` |
-| `analyze-symbol` | One entry point for symbol existence checks, namespace mapping, lifecycle tracing, workspace symbol analysis, and API overview | `task`, `subject`, `version?`, `sourceMapping?`, `targetMapping?`, `projectPath?`, `classNameMapping?`, `signatureMode?`, `nameMode?`, `includeKinds?`, `maxRows?`, `maxCandidates?`, `detail?`, `include?` | `result.summary`, `match?`, `candidates?`, `ambiguity?`, `matrix?`, `workspace?` |
-| `compare-minecraft` | Compare version pairs, class signatures, registries, or produce a migration-oriented overview | `task?`, `subject`, `detail?`, `include?`, `subject.kind="class".sourcePriority?`, `maxClassResults?`, `maxEntriesPerRegistry?`, `includeFullDiff?`, `limit?` | `result.summary`, `comparison`, `classes?`, `classDiff?`, `registry?`, `migration?` |
-| `analyze-mod` | Metadata-first entry point for mod summary, decompile/search flows, class source, and safe remap previews/applies | `task`, `subject`, `query?`, `searchType?`, `targetMapping?`, `outputJar?`, `executionMode?`, `includeFiles?`, `maxFiles?`, `maxLines?`, `maxChars?`, `limit?`, `detail?`, `include?` | `result.summary`, `metadata?`, `decompile?`, `hits?`, `source?`, `operation?` |
-| `validate-project` | Project-level validation entry for workspace summaries plus direct Mixin and Access Widener validation | `task`, `subject`, `version?`, `mapping?`, `sourcePriority?`, `scope?`, `preferProjectVersion?`, `preferProjectMapping?`, `sourceRoots?`, `configPaths?`, `minSeverity?`, `hideUncertain?`, `explain?`, `warningMode?`, `warningCategoryFilter?`, `treatInfoAsWarning?`, `includeIssues?`, `detail?`, `include?` | `result.summary`, `project`, `workspace?`, `issues?` |
-| `manage-cache` | User-facing cache summary, listing, verification, previewed deletion/pruning/rebuild, and explicit apply operations | `action`, `cacheKinds?`, `selector?`, `executionMode?`, `detail?`, `include?`, `limit?`, `cursor?` | `result.summary`, `stats?`, `cacheEntries?`, `operation?`, `meta.pagination.nextCursor?` |
+| Tool | Purpose |
+| --- | --- |
+| `inspect-minecraft` | Inspect versions, artifacts, classes, files, source text, and workspace-aware lookup flows |
+| `analyze-symbol` | Handle symbol existence checks, namespace mapping, lifecycle tracing, workspace symbol resolution, and API overviews |
+| `compare-minecraft` | Compare version pairs, class diffs, registry diffs, and migration-oriented summaries |
+| `analyze-mod` | Summarize mod metadata, decompile and search mod code, inspect class source, and preview or apply remaps |
+| `validate-project` | Summarize workspaces and run direct Mixin, Access Widener, or Access Transformer validation |
+| `manage-cache` | List, verify, and preview or apply cache cleanup and rebuild operations |
 <!-- END GENERATED TOOL TABLE: v3-entry-tools -->
 
 ### Source Exploration
@@ -247,29 +257,31 @@ Start with these top-level workflow tools unless you already know the exact spec
 Tools for browsing Minecraft versions, resolving source artifacts, and reading or searching decompiled source code.
 
 <!-- BEGIN GENERATED TOOL TABLE: source-exploration -->
-| Tool | Purpose | Key Inputs | Key Outputs |
-| --- | --- | --- | --- |
-| `list-versions` | List available Minecraft versions from Mojang manifest + local cache | `includeSnapshots?`, `limit?` | `result.latest`, `result.releases[]`, `meta.warnings[]` |
-| `resolve-artifact` | Resolve source artifact from `version` / `jar` / `coordinate` | `target`, `mapping?`, `sourcePriority?`, `allowDecompile?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?` | `artifactId`, `origin`, `mappingApplied`, `qualityFlags[]`, `artifactContents`, `adjacentSourceCandidates?`, `sampleEntries?`, `warnings[]` |
-| `find-class` | Resolve simple or fully-qualified class names inside an artifact | `className`, `artifactId`, `limit?` | `matches[]`, `total`, `warnings[]` |
-| `get-class-source` | Get class source by artifact target or resolve target on demand (`mode=metadata` by default) | `className`, `target`, `mode?`, `mapping?`, `sourcePriority?`, `allowDecompile?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?`, `startLine?`, `endLine?`, `maxLines?`, `maxChars?`, `outputFile?` | `mode`, `sourceText`, `returnedRange`, `truncated`, `charsTruncated?`, `outputFile?`, `artifactId`, `returnedNamespace`, `artifactContents`, mapping/provenance metadata |
-| `get-class-members` | Get class fields/methods/constructors from bytecode | `className`, `target`, `mapping?`, `sourcePriority?`, `allowDecompile?`, `access?`, `includeSynthetic?`, `includeInherited?`, `memberPattern?`, `maxMembers?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?` | `members.{constructors,fields,methods}`, `counts`, `truncated`, `context`, `returnedNamespace`, `artifactContents`, `warnings[]` |
-| `search-class-source` | Search indexed class source for symbols/text/path | `artifactId`, `query`, `intent?`, `match?`, `packagePrefix?`, `fileGlob?`, `symbolKind?`, `queryMode?`, `limit?`, `cursor?` | `hits[]`, `nextCursor?`, `mappingApplied`, `returnedNamespace`, `artifactContents` |
-| `get-artifact-file` | Read full source file with byte guard | `artifactId`, `filePath`, `maxBytes?` | `content`, `contentBytes`, `truncated`, `mappingApplied`, `returnedNamespace`, `artifactContents` |
-| `list-artifact-files` | List indexed source file paths with cursor pagination | `artifactId`, `prefix?`, `limit?`, `cursor?` | `items[]`, `nextCursor?`, `mappingApplied`, `artifactContents`, `warnings[]` |
-| `index-artifact` | Rebuild index metadata for an existing artifact | `artifactId`, `force?` | `reindexed`, `reason`, `counts`, `indexedAt`, `durationMs` |
+| Tool | Purpose |
+| --- | --- |
+| `list-versions` | List available Minecraft versions from Mojang metadata and local cache |
+| `resolve-artifact` | Resolve source artifacts from versions, JAR paths, or Maven coordinates |
+| `find-class` | Find simple or fully-qualified class names inside an artifact |
+| `get-class-source` | Read class source from an artifact or resolve the backing artifact on demand |
+| `get-class-members` | List constructors, fields, and methods from bytecode |
+| `search-class-source` | Search indexed class source by symbol, text, or path |
+| `get-artifact-file` | Read a full source file with a byte limit |
+| `list-artifact-files` | List indexed source file paths with cursor pagination |
+| `index-artifact` | Rebuild indexed metadata for an existing artifact |
 <!-- END GENERATED TOOL TABLE: source-exploration -->
 
+For unobfuscated releases such as `26.1+`, `mapping="mojang"` now uses the runtime/decompile path directly for version and versioned-coordinate targets and skips Loom source-jar discovery entirely, while `intermediary` and `yarn` still fall back to `obfuscated` with a warning.
+
 ### Version Comparison & Symbol Tracking
 
 Tools for comparing class and registry changes across Minecraft versions and tracing symbol existence over time.
 
 <!-- BEGIN GENERATED TOOL TABLE: version-comparison-symbol-tracking -->
-| Tool | Purpose | Key Inputs | Key Outputs |
-| --- | --- | --- | --- |
-| `trace-symbol-lifecycle` | Trace when `Class.method` exists across Minecraft versions (`descriptor` omitted = name-only lookup) | `symbol`, `descriptor?`, `fromVersion?`, `toVersion?`, `mapping?`, `sourcePriority?`, `includeSnapshots?`, `maxVersions?`, `includeTimeline?` | `presence.firstSeen`, `presence.lastSeen`, `presence.missingBetween[]`, `presence.existsNow`, `timeline?`, `warnings[]` |
-| `diff-class-signatures` | Compare one class between two versions and return member deltas | `className`, `fromVersion`, `toVersion`, `mapping?`, `sourcePriority?`, `includeFullDiff?` | `classChange`, `constructors/methods/fields.{added,removed,modified}`, `modified`, `modified[].{key,changed,from?,to?}`, `summary`, `warnings[]` |
-| `compare-versions` | Compare class/registry changes between two versions | `fromVersion`, `toVersion`, `category?`, `packageFilter?`, `maxClassResults?` | `classes`, `registry`, `summary`, `warnings[]` |
+| Tool | Purpose |
+| --- | --- |
+| `trace-symbol-lifecycle` | Trace when `Class.method` exists across Minecraft versions |
+| `diff-class-signatures` | Compare one class across two versions and return member deltas |
+| `compare-versions` | Compare class and registry changes between two versions |
 <!-- END GENERATED TOOL TABLE: version-comparison-symbol-tracking -->
 
 ### Mapping & Symbols
@@ -277,25 +289,27 @@ Tools for comparing class and registry changes across Minecraft versions and tra
 Tools for converting symbol names between namespaces and checking symbol existence.
 
 <!-- BEGIN GENERATED TOOL TABLE: mapping-symbols -->
-| Tool | Purpose | Key Inputs | Key Outputs |
-| --- | --- | --- | --- |
-| `find-mapping` | Find mapping candidates for class/field/method symbols between namespaces | `version`, `kind`, `name`, `owner?`, `descriptor?`, `sourceMapping`, `targetMapping`, `sourcePriority?`, `disambiguation?`, `maxCandidates?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `candidateCount`, `candidatesTruncated?`, `ambiguityReasons?`, `provenance?`, `meta.warnings[]` |
-| `resolve-method-mapping-exact` | Resolve one method mapping with strict owner+name+descriptor matching | `version`, `name`, `owner`, `descriptor`, `sourceMapping`, `targetMapping`, `sourcePriority?`, `maxCandidates?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `candidateCount`, `candidatesTruncated?`, `provenance?`, `meta.warnings[]` |
-| `get-class-api-matrix` | Show one class API as a mapping matrix (`obfuscated/mojang/intermediary/yarn`) | `version`, `className`, `classNameMapping`, `includeKinds?`, `sourcePriority?`, `maxRows?` | `classIdentity`, `rows[]`, `rowCount`, `rowsTruncated?`, `ambiguousRowCount?`, `meta.warnings[]` |
-| `resolve-workspace-symbol` | Resolve compile-visible symbol names for a Gradle workspace (`build.gradle/.kts`) | `projectPath`, `version`, `kind`, `name`, `owner?`, `descriptor?`, `sourceMapping`, `sourcePriority?`, `maxCandidates?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `candidateCount`, `candidatesTruncated?`, `workspaceDetection`, `meta.warnings[]` |
-| `check-symbol-exists` | Strict symbol presence check for class/field/method | `version`, `kind`, `name`, `owner?`, `descriptor?`, `sourceMapping`, `sourcePriority?`, `nameMode?`, `signatureMode?`, `maxCandidates?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `candidateCount`, `candidatesTruncated?`, `meta.warnings[]` |
+| Tool | Purpose |
+| --- | --- |
+| `find-mapping` | Look up mapping candidates for class, field, or method symbols |
+| `resolve-method-mapping-exact` | Resolve one method mapping with strict owner, name, and descriptor matching |
+| `get-class-api-matrix` | Show one class API across `obfuscated`, `mojang`, `intermediary`, and `yarn` |
+| `resolve-workspace-symbol` | Resolve compile-visible symbol names from a Gradle workspace |
+| `check-symbol-exists` | Check whether a class, field, or method exists in a namespace |
 <!-- END GENERATED TOOL TABLE: mapping-symbols -->
 
+`resolve-artifact`, `find-mapping`, `resolve-method-mapping-exact`, `resolve-workspace-symbol`, and `check-symbol-exists` accept an optional `compact` parameter (default `false`). When `true`, empty arrays, null values, and empty objects are stripped from the top-level response to reduce token overhead. For `resolve-artifact`, compact mode additionally omits diagnostic fields (`provenance`, `artifactContents`, `sampleEntries`, `adjacentSourceCandidates`, `binaryJarPath`, `coordinate`, `repoUrl`, `resolvedSourceJarPath`), returning only the essential fields needed for downstream tool calls. For mapping tools, compact mode omits the redundant `candidates` array when the result is a single full-confidence exact-match resolution (`resolved=true`, `resolvedSymbol` present, `candidates.length=1`, `candidateCount=1`, `!candidatesTruncated`, `matchKind="exact"`, `confidence` missing or `1`).
+
 ### NBT Utilities
 
 Tools for decoding, patching, and encoding Java Edition NBT binary data using a typed JSON representation.
 
 <!-- BEGIN GENERATED TOOL TABLE: nbt-utilities -->
-| Tool | Purpose | Key Inputs | Key Outputs |
-| --- | --- | --- | --- |
-| `nbt-to-json` | Decode Java Edition NBT binary (`base64`) to typed JSON | `nbtBase64`, `compression?` (`none`, `gzip`, `auto`) | `typedJson`, `meta.compressionDetected`, `meta.inputBytes` |
-| `nbt-apply-json-patch` | Apply RFC 6902 patch (`add/remove/replace/test`) to typed NBT JSON | `typedJson`, `patch` | `typedJson`, `meta.appliedOps`, `meta.testOps`, `meta.changed` |
-| `json-to-nbt` | Encode typed JSON back to Java Edition NBT binary (`base64`) | `typedJson`, `compression?` (`none`, `gzip`) | `nbtBase64`, `meta.outputBytes`, `meta.compressionApplied` |
+| Tool | Purpose |
+| --- | --- |
+| `nbt-to-json` | Decode Java Edition NBT binary payloads into typed JSON |
+| `nbt-apply-json-patch` | Apply RFC 6902 patches to typed NBT JSON |
+| `json-to-nbt` | Encode typed JSON back to Java Edition NBT binary |
 <!-- END GENERATED TOOL TABLE: nbt-utilities -->
 
 ### Mod Analysis
@@ -303,24 +317,27 @@ Tools for decoding, patching, and encoding Java Edition NBT binary data using a
 Tools for extracting metadata from mod JARs, decompiling mod source, searching mod code, and remapping mod namespaces.
 
 <!-- BEGIN GENERATED TOOL TABLE: mod-analysis -->
-| Tool | Purpose | Key Inputs | Key Outputs |
-| --- | --- | --- | --- |
-| `analyze-mod-jar` | Extract mod metadata/dependencies/entrypoints from mod JAR | `jarPath`, `includeClasses?` | `modId`, `loader`, `jarKind`, `dependencies`, `entrypoints`, `mixinConfigs`, class stats |
-| `decompile-mod-jar` | Decompile mod JAR and optionally return one class source | `jarPath`, `className?`, `includeFiles?`, `maxFiles?` | `outputDir`, `fileCount`, `files?`, `returnedFileCount?`, `filesTruncated?`, `filesOmitted?`, `source?`, `warnings[]` |
-| `get-mod-class-source` | Read one class source from decompiled mod cache | `jarPath`, `className`, `maxLines?`, `maxChars?`, `outputFile?` | `className`, `content`, `totalLines`, `truncated?`, `charsTruncated?`, `outputFilePath?`, `warnings[]` |
-| `search-mod-source` | Search decompiled mod source by class/method/field/content | `jarPath`, `query`, `searchType?`, `limit?` | `hits[]`, `totalHits`, `truncated`, `warnings[]` |
-| `remap-mod-jar` | Remap a Fabric/Quilt mod JAR to yarn/mojang names; Mojang-mapped inputs are copied for `targetMapping="mojang"` | `inputJar`, `targetMapping`, `mcVersion?`, `outputJar?` | `outputJar`, `mcVersion`, `fromMapping`, `targetMapping`, `resolvedTargetNamespace`, `warnings[]` |
+| Tool | Purpose |
+| --- | --- |
+| `analyze-mod-jar` | Extract mod metadata, dependencies, entrypoints, mixin config info, and packaged access transformer paths from a JAR |
+| `decompile-mod-jar` | Decompile a mod JAR and optionally return one class source |
+| `get-mod-class-source` | Read one class source from the decompiled mod cache |
+| `search-mod-source` | Search decompiled mod source by class, method, field, or content |
+| `remap-mod-jar` | Remap a Fabric or Quilt mod JAR to `yarn` or `mojang` names |
 <!-- END GENERATED TOOL TABLE: mod-analysis -->
 
 ### Validation
 
-Tools for validating Mixin source and Access Widener files against a target Minecraft version.
+Tools for validating Mixin source, Access Widener files, and Forge/NeoForge Access Transformer files against a target Minecraft version.
+`validate-access-widener` keeps vanilla bytecode validation by default, and now also supports runtime-aware validation through `projectPath`, `scope`, and `preferProjectVersion`, returning runtime `provenance` plus per-entry `resolvedRuntimeAccess` evidence when that mode is used. Runtime-aware method validation now preserves remapped JVM descriptors across namespace changes, searches Loom tiny mappings from workspace and Gradle user-home caches, and prefers explicit `*merged-intermediary*` / `*merged-mojang*` jars over ambiguous `minecraft-merged.jar` candidates.
+`validate-access-transformer` infers `atNamespace` from Forge or NeoForge workspace context when `projectPath` is provided, validates packaged or inline AT content, and uses loader/runtime artifacts for `scope="loader"` instead of treating loader as a merged-only alias.
 
 <!-- BEGIN GENERATED TOOL TABLE: validation -->
-| Tool | Purpose | Key Inputs | Key Outputs |
-| --- | --- | --- | --- |
-| `validate-mixin` | Parse/validate Mixin source against target Minecraft version | `input`, `sourceRoots?`, `version`, `mapping?`, `sourcePriority?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `minSeverity?`, `hideUncertain?`, `warningMode?`, `preferProjectMapping?`, `reportMode?`, `warningCategoryFilter?`, `treatInfoAsWarning?`, `explain?`, `includeIssues?` | `mode`, `results[].validationStatus`, `summary.partial`, `issueSummary?`, `provenance?`, `incompleteReasons?`, `toolHealth?`, `confidenceScore?`, `confidenceBreakdown?` |
-| `validate-access-widener` | Parse/validate Access Widener content against target version | `content`, `version`, `mapping?`, `sourcePriority?` | `valid`, `issues[]`, `warnings[]`, `summary` |
+| Tool | Purpose |
+| --- | --- |
+| `validate-mixin` | Validate Mixin source against a target Minecraft version |
+| `validate-access-widener` | Validate Access Widener content against a target Minecraft version, optionally using runtime-aware Loom artifacts |
+| `validate-access-transformer` | Validate Access Transformer content against a target Minecraft version, optionally using Forge/NeoForge runtime artifacts |
 <!-- END GENERATED TOOL TABLE: validation -->
 
 ### Registry & Diagnostics
@@ -328,52 +345,14 @@ Tools for validating Mixin source and Access Widener files against a target Mine
 Tools for querying generated registry data and inspecting server runtime state.
 
 <!-- BEGIN GENERATED TOOL TABLE: registry-diagnostics -->
-| Tool | Purpose | Key Inputs | Key Outputs |
-| --- | --- | --- | --- |
-| `get-registry-data` | Get generated registry snapshots (blocks/items/entities etc.) | `version`, `registry?`, `includeData?`, `maxEntriesPerRegistry?` | `registries`, `data?`, `entryCount`, `returnedEntryCount?`, `registryEntryCounts?`, `dataTruncated?`, `warnings[]` |
-| `get-runtime-metrics` | Inspect runtime counters and latency snapshots | none | `result.*` runtime metrics, `meta` envelope |
+| Tool | Purpose |
+| --- | --- |
+| `get-registry-data` | Read generated registry snapshots and optionally include entry data |
+| `get-runtime-metrics` | Inspect runtime metrics and latency snapshots |
 <!-- END GENERATED TOOL TABLE: registry-diagnostics -->
 
 Detailed parameter constraints, migration notes, resource behavior, and the full environment-variable matrix live in [docs/tool-reference.md](docs/tool-reference.md).
 
-## Resources
-
-Fixed resources:
-
-- `mc://versions/list`
-- `mc://metrics`
-
-Template resources:
-
-- `mc://source/{artifactId}/{className}`
-- `mc://artifact/{artifactId}/files/{filePath}`
-- `mc://mappings/{version}/{sourceMapping}/{targetMapping}/{kind}/{name}`
-- `mc://artifact/{artifactId}/members/{className}`
-- `mc://artifact/{artifactId}`
-
-See [docs/tool-reference.md#resources](docs/tool-reference.md#resources) for the full resource table and response behavior.
-
-## Response Model
-
-Tools and JSON resources return the standard `{ result?, error?, meta }` envelope. Text resources (`class-source` and `artifact-file`) return raw text on success and structured JSON on failure.
-
-See [docs/tool-reference.md#response-envelope](docs/tool-reference.md#response-envelope) for the exact envelope fields and error shape.
-
-## Common Environment Variables
-
-These are the most commonly changed settings. For the full supported list, see [docs/tool-reference.md#environment-variables](docs/tool-reference.md#environment-variables).
-
-| Variable | Default | Description |
-| --- | --- | --- |
-| `MCP_CACHE_DIR` | `~/.cache/minecraft-modding-mcp` | Cache root for downloads and SQLite |
-| `MCP_SOURCE_REPOS` | Maven Central + Fabric + Forge + NeoForge | Comma-separated Maven repository URLs |
-| `MCP_MAPPING_SOURCE_PRIORITY` | `loom-first` | Mapping source priority (`loom-first` or `maven-first`) |
-| `MCP_ENABLE_INDEXED_SEARCH` | `true` | Enable indexed search for `search-class-source` |
-| `MCP_VINEFLOWER_JAR_PATH` | unset | Override the Vineflower JAR path |
-| `MCP_TINY_REMAPPER_JAR_PATH` | unset | Override the tiny-remapper JAR path |
-| `MCP_MAX_SEARCH_HITS` | `200` | Maximum search result count |
-| `MCP_MAX_CACHE_BYTES` | `2147483648` | Maximum total cache size in bytes |
-
 ## Development
 
 Repository requirements:

package/dist/access-transformer-parser.d.ts

@@ -0,0 +1,17 @@
+export type AccessTransformerAccessAction = "public" | "protected" | "package-private" | "private";
+export type AccessTransformerFinalAction = "add" | "remove";
+export type AccessTransformerEntry = {
+    line: number;
+    targetKind: "class" | "field" | "method";
+    owner: string;
+    target: string;
+    name?: string;
+    descriptor?: string;
+    accessAction: AccessTransformerAccessAction;
+    finalAction?: AccessTransformerFinalAction;
+};
+export type ParsedAccessTransformer = {
+    entries: AccessTransformerEntry[];
+    parseWarnings: string[];
+};
+export declare function parseAccessTransformer(content: string): ParsedAccessTransformer;

package/dist/access-transformer-parser.js

@@ -0,0 +1,97 @@
+function parseAccessDeclaration(raw) {
+    const match = raw.match(/^(public|protected|default|private)([+-]f)?$/i);
+    if (!match) {
+        return undefined;
+    }
+    const finalModifier = match[2]?.toLowerCase();
+    return {
+        accessAction: match[1]?.toLowerCase() === "default"
+            ? "package-private"
+            : match[1]?.toLowerCase(),
+        ...(finalModifier === "+f" ? { finalAction: "add" } : {}),
+        ...(finalModifier === "-f" ? { finalAction: "remove" } : {})
+    };
+}
+function splitMemberToken(tokens) {
+    if (tokens.length === 0) {
+        return { targetKind: "class" };
+    }
+    if (tokens.length === 1) {
+        const token = tokens[0] ?? "";
+        const descriptorStart = token.indexOf("(");
+        if (descriptorStart >= 0) {
+            return {
+                targetKind: "method",
+                name: token.slice(0, descriptorStart),
+                descriptor: token.slice(descriptorStart)
+            };
+        }
+        return {
+            targetKind: "field",
+            name: token
+        };
+    }
+    return {
+        targetKind: "method",
+        name: tokens[0],
+        descriptor: tokens.slice(1).join("")
+    };
+}
+export function parseAccessTransformer(content) {
+    const entries = [];
+    const parseWarnings = [];
+    const lines = content.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index++) {
+        const lineNumber = index + 1;
+        const rawLine = (lines[index] ?? "").trim();
+        if (!rawLine || rawLine.startsWith("#")) {
+            continue;
+        }
+        const withoutComment = rawLine.replace(/\s+#.*$/, "").trim();
+        if (!withoutComment) {
+            continue;
+        }
+        const parts = withoutComment.split(/\s+/);
+        if (parts.length < 2) {
+            parseWarnings.push(`Line ${lineNumber}: Incomplete access transformer entry "${withoutComment}".`);
+            continue;
+        }
+        const declaration = parseAccessDeclaration(parts[0] ?? "");
+        if (!declaration) {
+            parseWarnings.push(`Line ${lineNumber}: Unsupported access declaration "${parts[0]}".`);
+            continue;
+        }
+        const owner = parts[1] ?? "";
+        if (!owner) {
+            parseWarnings.push(`Line ${lineNumber}: Incomplete access transformer entry "${withoutComment}".`);
+            continue;
+        }
+        const member = splitMemberToken(parts.slice(2));
+        if (member.targetKind === "method" && (!member.name || !member.descriptor)) {
+            parseWarnings.push(`Line ${lineNumber}: Method entry requires a method name and JVM descriptor.`);
+            continue;
+        }
+        if ((member.targetKind === "field" || member.targetKind === "method") && !member.name) {
+            parseWarnings.push(`Line ${lineNumber}: Member entry requires a target name.`);
+            continue;
+        }
+        const target = member.targetKind === "class"
+            ? owner
+            : `${owner}#${member.name}${member.descriptor ?? ""}`;
+        entries.push({
+            line: lineNumber,
+            owner,
+            target,
+            targetKind: member.targetKind,
+            ...(member.name ? { name: member.name } : {}),
+            ...(member.descriptor ? { descriptor: member.descriptor } : {}),
+            accessAction: declaration.accessAction,
+            ...(declaration.finalAction ? { finalAction: declaration.finalAction } : {})
+        });
+    }
+    return {
+        entries,
+        parseWarnings
+    };
+}
+//# sourceMappingURL=access-transformer-parser.js.map

package/dist/concurrency.d.ts

@@ -0,0 +1 @@
+export declare function mapWithConcurrencyLimit<T, R>(items: readonly T[], limit: number, mapper: (item: T, index: number) => Promise<R>): Promise<R[]>;