diff --git a/.agents/skills/reverse-engineer-anything/SKILL.md b/.agents/skills/reverse-engineer-anything/SKILL.md index fca53e9858..910f961fc2 100644 --- a/.agents/skills/reverse-engineer-anything/SKILL.md +++ b/.agents/skills/reverse-engineer-anything/SKILL.md @@ -2,7 +2,7 @@ name: reverse-engineer-anything description: Reverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. metadata: - version: "62" + version: "63" --- # REA @@ -269,6 +269,14 @@ explicit path or endpoint and do not need it. delivery requires `--evidence_output`. See the [Rust binary guide](https://github.com/morluto/rea/blob/main/docs/rust-binaries.md). +- Maven POM or Gradle module metadata: `inspect_maven_gradle_metadata` with + the explicit local `pom.xml` or `.module` file. This built-in target-free + inspection requires no Maven or Gradle. Preserve coordinates as spelled, + dependency and dependencyManagement rows, BOM imports, Gradle variants and + rich versions, and unresolved property or parent references. Interpolation, + inheritance, tree resolution, and repository access are not performed. See + the + [Maven POM and Gradle module metadata guide](https://github.com/morluto/rea/blob/main/docs/maven-gradle-metadata.md). - PE Authenticode certificate table: `inspect_pe_certificates` with the explicit local PE32/PE32+ file. This built-in target-free inspection requires no Windows SDK. Preserve WIN_CERTIFICATE ranges, types, payload SHA-256, and diff --git a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md index a53ee6e940..d807ea1fd4 100644 --- a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md +++ b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md @@ -139,6 +139,18 @@ kind `cyclonedx` for one CycloneDX 1.6 document. Build-kind packages are `scope: excluded`. See [Rust binaries](https://github.com/morluto/rea/blob/main/docs/rust-binaries.md) and [CycloneDX dependencies](https://github.com/morluto/rea/blob/main/docs/guides/native/cyclonedx-view.md). +## Maven POM and Gradle module metadata + +Use `inspect_maven_gradle_metadata` for an explicit local Maven `pom.xml` or +Gradle `.module` file when the question concerns declared coordinates, +dependency scopes and exclusions, BOM or platform constraints, or unresolved +property and parent references. No `open_binary`, Maven, Gradle, or repository +access is required. The CLI equivalent is `inspect-maven-gradle-metadata PATH`. +Preserve artifact SHA-256, versions as spelled, and `unresolved` entries. +Interpolation and inheritance are not performed. A missing version is not a +resolved BOM selection. See +[Maven POM and Gradle module metadata](https://github.com/morluto/rea/blob/main/docs/maven-gradle-metadata.md). + ## PE Authenticode certificate tables Use `inspect_pe_certificates` for an explicit local PE32/PE32+ image when the diff --git a/.cursor-plugin/skills/reverse-engineer-anything/SKILL.md b/.cursor-plugin/skills/reverse-engineer-anything/SKILL.md index fca53e9858..910f961fc2 100644 --- a/.cursor-plugin/skills/reverse-engineer-anything/SKILL.md +++ b/.cursor-plugin/skills/reverse-engineer-anything/SKILL.md @@ -2,7 +2,7 @@ name: reverse-engineer-anything description: Reverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. metadata: - version: "62" + version: "63" --- # REA @@ -269,6 +269,14 @@ explicit path or endpoint and do not need it. delivery requires `--evidence_output`. See the [Rust binary guide](https://github.com/morluto/rea/blob/main/docs/rust-binaries.md). +- Maven POM or Gradle module metadata: `inspect_maven_gradle_metadata` with + the explicit local `pom.xml` or `.module` file. This built-in target-free + inspection requires no Maven or Gradle. Preserve coordinates as spelled, + dependency and dependencyManagement rows, BOM imports, Gradle variants and + rich versions, and unresolved property or parent references. Interpolation, + inheritance, tree resolution, and repository access are not performed. See + the + [Maven POM and Gradle module metadata guide](https://github.com/morluto/rea/blob/main/docs/maven-gradle-metadata.md). - PE Authenticode certificate table: `inspect_pe_certificates` with the explicit local PE32/PE32+ file. This built-in target-free inspection requires no Windows SDK. Preserve WIN_CERTIFICATE ranges, types, payload SHA-256, and diff --git a/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md index a53ee6e940..d807ea1fd4 100644 --- a/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md +++ b/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md @@ -139,6 +139,18 @@ kind `cyclonedx` for one CycloneDX 1.6 document. Build-kind packages are `scope: excluded`. See [Rust binaries](https://github.com/morluto/rea/blob/main/docs/rust-binaries.md) and [CycloneDX dependencies](https://github.com/morluto/rea/blob/main/docs/guides/native/cyclonedx-view.md). +## Maven POM and Gradle module metadata + +Use `inspect_maven_gradle_metadata` for an explicit local Maven `pom.xml` or +Gradle `.module` file when the question concerns declared coordinates, +dependency scopes and exclusions, BOM or platform constraints, or unresolved +property and parent references. No `open_binary`, Maven, Gradle, or repository +access is required. The CLI equivalent is `inspect-maven-gradle-metadata PATH`. +Preserve artifact SHA-256, versions as spelled, and `unresolved` entries. +Interpolation and inheritance are not performed. A missing version is not a +resolved BOM selection. See +[Maven POM and Gradle module metadata](https://github.com/morluto/rea/blob/main/docs/maven-gradle-metadata.md). + ## PE Authenticode certificate tables Use `inspect_pe_certificates` for an explicit local PE32/PE32+ image when the diff --git a/docs/.vitepress/documentation.ts b/docs/.vitepress/documentation.ts index 9465aa9b35..1f56d0cae9 100644 --- a/docs/.vitepress/documentation.ts +++ b/docs/.vitepress/documentation.ts @@ -645,6 +645,11 @@ export const documentationSections = [ source: "kuna-provider.md", route: "/kuna-provider", }, + { + text: "Maven POM and Gradle module metadata", + source: "maven-gradle-metadata.md", + route: "/maven-gradle-metadata", + }, { text: "Model file declarations", source: "model-artifacts.md", diff --git a/docs/README.md b/docs/README.md index 5a23dea4b9..27e490bb41 100644 --- a/docs/README.md +++ b/docs/README.md @@ -194,6 +194,7 @@ the exact commit messages and references from the release they describe. - [Static JavaScript route inventory](javascript-route-inventory.md) - [Linux kernel modules](kernel-modules.md) - [Kuna provider](kuna-provider.md) +- [Maven POM and Gradle module metadata](maven-gradle-metadata.md) - [Model file declarations](model-artifacts.md) - [Match native functions across builds](native-function-matching.md) - [Node.js single executable applications](node-sea.md) diff --git a/docs/getting-started/cli.md b/docs/getting-started/cli.md index e0ecee7365..07564cdd27 100644 --- a/docs/getting-started/cli.md +++ b/docs/getting-started/cli.md @@ -640,6 +640,19 @@ The workflow reports IFF chunk names, atom tables, exports, imports, lambdas, and the Code chunk header. Missing optional tables stay null. See [Erlang BEAM files](../erlang-beam.md). +Inspect a Maven POM or Gradle module-metadata file without running Maven or +Gradle, resolving a tree, or contacting a repository: + +```bash +rea inspect-maven-gradle-metadata /absolute/path/to/pom.xml --json +rea inspect-maven-gradle-metadata /absolute/path/to/demo-1.2.3.module --json +``` + +The workflow reports coordinates as spelled, dependency and +dependencyManagement rows, BOM or platform notes, Gradle variants, and +unresolved property or parent references. See +[Maven POM and Gradle module metadata](../maven-gradle-metadata.md). + Inspect a NuGet `.nupkg` without restoring the package or contacting a feed: ```bash diff --git a/docs/index.md b/docs/index.md index a787a3758e..ff7104ffe0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -49,19 +49,19 @@ For runtime instrumentation, see the [Frida guide](guides/runtime/frida-instrume The [documentation directory](README.md) lists every guide by domain. -| Task | Guides | -| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Identify a desktop installation | [Runtime candidates, evidence and follow-up files](desktop-applications.md) | -| Inspect native functions, references, or types | [Native binaries](guides/native/native-investigation.md), [Go metadata](guides/native/go-binaries.md), [Rust dependencies](rust-binaries.md), [CPython pyc files](python-pyc.md), [PE certificates](pe-certificates.md), [PE imports](pe-imports.md), [PE TLS/load config](pe-load-config.md), [ELF notes](elf-notes.md), [DWARF compile units](guides/native/dwarf-units.md), [ELF debug files](guides/native/elf-debug-link.md), [ELF dependencies](elf-dependencies.md), [initializer functions](guides/native/native-initializers.md), [ELF unwind ranges](guides/native/elf-unwind-ranges.md), [Linux kernel modules](kernel-modules.md), [Linux kernel build config](guides/native/kernel-build-config.md), [Apple IPS](apple-ips.md), [Erlang BEAM](erlang-beam.md), [offline ELF layout](guides/native/binary-diagnostics.md), [recorded crashes](guides/native/recorded-crashes.md) | -| Select a native provider or import format | [Ghidra semantics](providers/ghidra-provider.md), [Windows](providers/windows-ghidra-p0.md), [DOS](providers/ghidra-dos.md), [raw bytes](providers/raw-binary.md), [GameCube DOL](ghidra-dol.md), [MIPS](providers/ghidra-mips.md), [RISC-V](providers/ghidra-riscv.md), [PowerPC](ghidra-ppc.md), [PSP](providers/ghidra-psp.md), [NativeAOT](providers/ghidra-nativeaot.md), [IDA](providers/ida-provider.md), [Kuna](kuna-provider.md), [JEB](providers/jeb-analysis.md) | -| Analyze JavaScript or Electron artifacts | [Static analysis](guides/javascript/javascript-artifact-reconstruction.md), [tracing and comparisons](guides/javascript/javascript-application-workflows.md), [application graph](guides/javascript/javascript-application-graph.md), [source recovery](guides/javascript/javascript-recovery.md) | -| Compare static JavaScript with runtime observations | [Runtime attribution](guides/javascript/javascript-runtime-observation.md), [reconciliation](guides/javascript/javascript-runtime-reconciliation.md), [Electron observation](guides/javascript/electron-observation.md), [Electron fuses](electron-fuses.md), [Release exposure](release-exposure.md) | -| Inspect assemblies, packages, or firmware | [Godot PCK](godot-pck.md), [UnityFS](unityfs.md), [wxapkg](wxapkg.md), [U-Boot uImage](uimage.md), [Android boot images](android-boot-image.md), [.NET](guides/managed/managed-code-analysis.md), [NuGet packages](guides/managed/nuget-nupkg.md), [Python packages](python-packaged-applications.md), [Android](guides/android/android-analysis.md), [Android OTA payloads](guides/firmware/android-ota-payload.md), [APK signatures](apk-signature.md), [Apktool resources](guides/android/apktool-resource-analysis.md), [ADB acquisition](guides/android/adb-device-analysis.md), [Apple](guides/apple/apple-application-analysis.md), [Harmony](guides/harmony/harmony-analysis.md), [firmware](guides/firmware/firmware-analysis.md), [Device Tree](devicetree.md), [FIT images](fit-images.md), [UF2/DfuSe](uf2-dfuse.md), [Flutter](guides/android/flutter-analysis.md), [ESP images](esp-image.md), [ESP flash images](esp-flash-image.md), [WASM](guides/wasm/wasm-artifacts.md), [EVM](guides/evm/evm-bytecode.md) | -| Observe or compare a browser scenario | [CDP observation](guides/web/browser-observation.md), [scenarios](guides/web/browser-scenario-contract.md), [runtime evidence](guides/web/web-runtime.md), [historical captures](guides/web/web-network-captures.md) | -| Serve recorded behavior as an agent environment | [Agent environments](agent-environments.md) | -| Trace captured website source | [Source locations](guides/web/web-source-location.md), [module traces](guides/web/website-module-trace.md), [script export](guides/web/website-script-export.md) | -| Capture and compare a command | [Process capture](guides/runtime/process-capture.md) | -| Use CLI/MCP and retain evidence | [CLI](getting-started/cli.md), [MCP contracts](reference/mcp-contracts.md), [agent prompts](getting-started/mcp-prompts.md), [obligation ledgers](reference/reconstruction-obligation-ledgers.md) | +| Task | Guides | +| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Identify a desktop installation | [Runtime candidates, evidence and follow-up files](desktop-applications.md) | +| Inspect native functions, references, or types | [Native binaries](guides/native/native-investigation.md), [Go metadata](guides/native/go-binaries.md), [Rust dependencies](rust-binaries.md), [CPython pyc files](python-pyc.md), [PE certificates](pe-certificates.md), [PE imports](pe-imports.md), [PE TLS/load config](pe-load-config.md), [ELF notes](elf-notes.md), [DWARF compile units](guides/native/dwarf-units.md), [ELF debug files](guides/native/elf-debug-link.md), [ELF dependencies](elf-dependencies.md), [initializer functions](guides/native/native-initializers.md), [ELF unwind ranges](guides/native/elf-unwind-ranges.md), [Linux kernel modules](kernel-modules.md), [Linux kernel build config](guides/native/kernel-build-config.md), [Apple IPS](apple-ips.md), [Erlang BEAM](erlang-beam.md), [offline ELF layout](guides/native/binary-diagnostics.md), [recorded crashes](guides/native/recorded-crashes.md) | +| Select a native provider or import format | [Ghidra semantics](providers/ghidra-provider.md), [Windows](providers/windows-ghidra-p0.md), [DOS](providers/ghidra-dos.md), [raw bytes](providers/raw-binary.md), [GameCube DOL](ghidra-dol.md), [MIPS](providers/ghidra-mips.md), [RISC-V](providers/ghidra-riscv.md), [PowerPC](ghidra-ppc.md), [PSP](providers/ghidra-psp.md), [NativeAOT](providers/ghidra-nativeaot.md), [IDA](providers/ida-provider.md), [Kuna](kuna-provider.md), [JEB](providers/jeb-analysis.md) | +| Analyze JavaScript or Electron artifacts | [Static analysis](guides/javascript/javascript-artifact-reconstruction.md), [tracing and comparisons](guides/javascript/javascript-application-workflows.md), [application graph](guides/javascript/javascript-application-graph.md), [source recovery](guides/javascript/javascript-recovery.md) | +| Compare static JavaScript with runtime observations | [Runtime attribution](guides/javascript/javascript-runtime-observation.md), [reconciliation](guides/javascript/javascript-runtime-reconciliation.md), [Electron observation](guides/javascript/electron-observation.md), [Electron fuses](electron-fuses.md), [Release exposure](release-exposure.md) | +| Inspect assemblies, packages, or firmware | [Godot PCK](godot-pck.md), [UnityFS](unityfs.md), [wxapkg](wxapkg.md), [U-Boot uImage](uimage.md), [Android boot images](android-boot-image.md), [.NET](guides/managed/managed-code-analysis.md), [NuGet packages](guides/managed/nuget-nupkg.md), [Maven POM and Gradle module metadata](maven-gradle-metadata.md), [Python packages](python-packaged-applications.md), [Android](guides/android/android-analysis.md), [Android OTA payloads](guides/firmware/android-ota-payload.md), [APK signatures](apk-signature.md), [Apktool resources](guides/android/apktool-resource-analysis.md), [ADB acquisition](guides/android/adb-device-analysis.md), [Apple](guides/apple/apple-application-analysis.md), [Harmony](guides/harmony/harmony-analysis.md), [firmware](guides/firmware/firmware-analysis.md), [Device Tree](devicetree.md), [FIT images](fit-images.md), [UF2/DfuSe](uf2-dfuse.md), [Flutter](guides/android/flutter-analysis.md), [ESP images](esp-image.md), [ESP flash images](esp-flash-image.md), [WASM](guides/wasm/wasm-artifacts.md), [EVM](guides/evm/evm-bytecode.md) | +| Observe or compare a browser scenario | [CDP observation](guides/web/browser-observation.md), [scenarios](guides/web/browser-scenario-contract.md), [runtime evidence](guides/web/web-runtime.md), [historical captures](guides/web/web-network-captures.md) | +| Serve recorded behavior as an agent environment | [Agent environments](agent-environments.md) | +| Trace captured website source | [Source locations](guides/web/web-source-location.md), [module traces](guides/web/website-module-trace.md), [script export](guides/web/website-script-export.md) | +| Capture and compare a command | [Process capture](guides/runtime/process-capture.md) | +| Use CLI/MCP and retain evidence | [CLI](getting-started/cli.md), [MCP contracts](reference/mcp-contracts.md), [agent prompts](getting-started/mcp-prompts.md), [obligation ledgers](reference/reconstruction-obligation-ledgers.md) | For development, use [testing](development/testing.md), [client verification](development/client-verification.md), [tool design](development/tool-design.md), [admission limits and recovery](design/limits-and-recovery.md), diff --git a/docs/maven-gradle-metadata.md b/docs/maven-gradle-metadata.md new file mode 100644 index 0000000000..7237fed2ed --- /dev/null +++ b/docs/maven-gradle-metadata.md @@ -0,0 +1,106 @@ +# Maven POM and Gradle module metadata + +`inspect_maven_gradle_metadata` / `inspect-maven-gradle-metadata` reports the +coordinates, dependency declarations, BOM or platform notes, and unresolved +property or parent references written in one selected local Maven `pom.xml` or +Gradle `.module` file. It reads the file without running Maven or Gradle, +resolving a dependency tree, or contacting a repository. + +```bash +rea inspect-maven-gradle-metadata /absolute/path/to/pom.xml --json +rea inspect-maven-gradle-metadata /absolute/path/to/demo-1.2.3.module --json +``` + +The CLI resolves relative paths against the caller's working directory. MCP +requires an absolute filesystem path and preserves that exact selection: + +```json +{ + "name": "inspect_maven_gradle_metadata", + "arguments": { "path": "/artifacts/pom.xml" } +} +``` + +Classification is from content, not the suffix: a well-formed Maven `` +document is `maven-pom`; a JSON object with `formatVersion` and a `component` +or `variants` array is `gradle-module`. + +## Observations + +The inline Evidence result contains the artifact path, SHA-256, and byte length. +Its parameters retain caller-selected controls. An omitted `max_file_bytes` +uses the default for execution and stays out of the parameters; an explicitly +selected default remains recorded. + +`coordinates` holds `group_id`, `artifact_id`, `version`, and `packaging` as +spelled. Missing project coordinates stay `null`. A `${property}` spelling is +kept as written and listed in `unresolved`; this reader does not interpolate +properties or inherit parent or BOM values. +When a parent is declared, omitted project group/version fields point to the +parent as possible sources. An omitted project `artifactId` is a missing child +coordinate: [only group/version coordinates may be inherited](https://maven.apache.org/pom.html#Maven_Coordinates). + +For a POM, `parent` records the declared parent coordinates and `relative_path` +when present. `relative_path_declared` distinguishes an empty ``, +which disables Maven's local parent lookup, from an omitted tag. `properties` +lists each child of `` as name and value. URL userinfo +credentials in a property value are removed and `value_credentials_redacted` +is `true`; when the credential span cannot be located, `value` is `null`. +`dependencies` comes from the project's `` list. +`dependency_management` comes from ``. A managed +dependency with `type` `pom` and `scope` `import` is a BOM import +(`bom_import: true`). Each row keeps scope, type, optional, classifier, and +exclusions as present. `optional` is the interpreted boolean and +`optional_spelling` keeps the text as written, so a `${property}` value stays +visible and is listed in `unresolved` with `field` `optional`. `version_kind` +is `literal`, `range`, `dynamic`, `property`, or `missing`; `dynamic` is +Gradle's `+` prefix (`1.+`) or a `latest.` selector +(`latest.release`). + +For Gradle module metadata, `gradle` records `format_version`, +`created_by_gradle`, and each variant's name, `org.gradle.category`, +`org.gradle.usage`, `available-at` coordinates as spelled, and declared +dependency and constraint counts. Variant dependencies are `origin` +`variant-dependencies`; `dependencyConstraints` are `origin` +`variant-constraints`. Rich versions keep `requires`, `prefers`, `strictly`, +and `rejects`. A variant whose category is `platform` or `enforced-platform` +marks its constraints `platform: true`. `available-at` is not fetched. URL +userinfo credentials in `available_at.url` are removed and +`url_credentials_redacted` is `true`; when the credential span cannot be +located, `url` is `null`. + +`unresolved` names every property reference in the coordinates, packaging, and +each dependency's scope, type, classifier, and optional, plus missing +coordinates that a parent would normally supply and other missing coordinates. These are explicit +unknowns, not guesses. + +## Limits and failures + +The selected file is limited to 1 MiB by default (16 MiB maximum). Exceeding +the budget fails without partial success. Malformed XML or JSON is +`invalid_format`. A well-formed document that is not a Maven project or Gradle +module metadata file is `unsupported_target`. Document type declarations are +unsupported. External entities are not resolved. + +A POM is counted as a stream before its document tree is built, and one with +more than 1,048,576 XML nodes (elements, attributes, text, CDATA, comments and +processing instructions) is refused as a resource limit, as is a report above +65,536 dependency and constraint rows, 4,096 Gradle variants, or 65,536 +dependency exclusions summed over every row. Each collection is counted before +its report records are built. +Unresolved property-reference and coordinate-gap records share a 65,536-record +allowance. Repeated references within one field are deduplicated in source +order; the same spelling in different fields or rows remains separate evidence. +Variant names repeated across dependency and constraint rows are also limited +to 4,194,304 UTF-16 code units. These fixed parser and report allowances are +separate from the selected file-read budget; raising `max_file_bytes` does not +raise them. + +POM profiles, when present, stay unread and unactivated. Declared repositories +stay unread and are not contacted. Packaging is not defaulted to `jar` when +omitted. Gradle variant attributes other than category and usage are not +decoded. + +Complete coverage means the selected document was read. It does not establish +a resolved dependency tree, a repository fetch, or that Maven or Gradle would +select the same versions. diff --git a/docs/specs/README.md b/docs/specs/README.md index a06bf410af..b016d00e97 100644 --- a/docs/specs/README.md +++ b/docs/specs/README.md @@ -34,6 +34,7 @@ for new work, roadmap granularity and producer-owned contracts. - [Solidity terminal metadata inspection](solidity/cbor-metadata/spec.md) ([plan](solidity/cbor-metadata/plan.md), [tasks](solidity/cbor-metadata/tasks.md), [verification](solidity/cbor-metadata/verification.md)) - [Inspect a V8 code cache container](v8/code-cache-inspection/spec.md) ([plan](v8/code-cache-inspection/plan.md), [tasks](v8/code-cache-inspection/tasks.md)) - [Deno compile executable inventory and extraction](artifacts/deno-standalone/spec.md) ([plan](artifacts/deno-standalone/plan.md), [tasks](artifacts/deno-standalone/tasks.md)) +- [Inspect Maven POM and Gradle module metadata](artifacts/maven-gradle-metadata/spec.md) ([plan](artifacts/maven-gradle-metadata/plan.md), [tasks](artifacts/maven-gradle-metadata/tasks.md)) - [ELF dynamic dependencies](native/elf-dependencies/spec.md) ([plan](native/elf-dependencies/plan.md), [tasks](native/elf-dependencies/tasks.md)) - [ELF unwind function ranges](native/elf-unwind-ranges/spec.md) ([plan](native/elf-unwind-ranges/plan.md), [tasks](native/elf-unwind-ranges/tasks.md)) - [Linux kernel build config](native/kernel-build-config/spec.md) ([plan](native/kernel-build-config/plan.md), [tasks](native/kernel-build-config/tasks.md)) diff --git a/docs/specs/artifacts/maven-gradle-metadata/plan.md b/docs/specs/artifacts/maven-gradle-metadata/plan.md new file mode 100644 index 0000000000..604d0a9093 --- /dev/null +++ b/docs/specs/artifacts/maven-gradle-metadata/plan.md @@ -0,0 +1,30 @@ +# Plan + +## Shape + +The document formats are the only thing this feature knows, so the parser owns +them and everything else consumes its facts. + +- `src/domain/java/mavenGradleMetadata.ts` holds the schema and version-kind + helpers, so a reader and a test share one definition of the report. +- `src/java/MavenGradleMetadataParser.ts` decodes UTF-8 bytes into coordinates, + dependencies, and unresolved references. It is given bytes only; it never + opens a file. +- `src/java/MavenGradleMetadataProvider.ts` owns the file read and the + file-size budget. It is the boundary that turns bytes into a reported fact. +- `src/cli/mavenGradleMetadataCommands.ts` and the MCP registration are thin + adapters over the same service, so both surfaces report the same facts. + +## Order + +1. Pin the report in the domain schema so later steps cannot disagree about it. +2. Write the parser against tiny valid POM and Gradle `.module` fixtures. +3. Add the provider and the file-size budget. +4. Expose the CLI command, then the MCP tool, over the same provider. +5. Document the command and the report, and link the guide from both indexes. + +## Budget + +The only unbounded part of the read is the selected file size, so it is bounded +by `max_file_bytes` (default 1 MiB, ceiling 16 MiB). Exceeding it fails without +partial success. diff --git a/docs/specs/artifacts/maven-gradle-metadata/spec.md b/docs/specs/artifacts/maven-gradle-metadata/spec.md new file mode 100644 index 0000000000..805acb783a --- /dev/null +++ b/docs/specs/artifacts/maven-gradle-metadata/spec.md @@ -0,0 +1,45 @@ +# Inspect Maven POM and Gradle module metadata + +This specification records an implementation increment and its original problem +statement. For current behavior and limitations, see the +[current guide](../../../maven-gradle-metadata.md). + +## Outcome + +Java dependency declarations often live outside a JAR, in a Maven POM or a +Gradle module-metadata file. Looking only at archive contents misses declared +coordinates, BOM imports, version ranges, exclusions, and variant constraints. + +`rea inspect-maven-gradle-metadata ` reads one explicitly selected POM or +`.module` file as static bytes and reports coordinates, dependency +declarations, BOM or platform notes, and unresolved property or parent +references, without running Maven or Gradle, resolving a tree, or contacting a +repository. The same facts are available through the +`inspect_maven_gradle_metadata` MCP tool. + +## Requirements + +- Classification is from content, not the suffix. +- Coordinates, packaging, parent, properties, dependencies, dependencyManagement, + exclusions, BOM imports, and version ranges are recorded as spelled. +- Gradle variants, rich versions, constraints, and `available-at` coordinates + are recorded as spelled; named module files are not fetched. +- Property spellings and missing parent-inherited coordinates remain explicit + unknowns. Interpolation and inheritance are not performed. +- Malformed XML/JSON fails closed. Unrecognized documents are unsupported. + Document types are rejected. No network is used. + +## Non-goals + +- Resolving a dependency tree or selecting versions. +- Running Maven or Gradle, executing plugins, or reading a credential store. +- Comparing two metadata snapshots. +- Associating metadata with a JAR or AAR. +- Activating POM profiles or applying packaging defaults. + +## Verification + +- Parser fixtures cover a parent POM with properties, a BOM import, an + exclusion, a version range, and a Gradle 1.1 module with library and platform + variants. +- CLI, MCP, and absolute-path boundary contracts have their own tests. diff --git a/docs/specs/artifacts/maven-gradle-metadata/tasks.md b/docs/specs/artifacts/maven-gradle-metadata/tasks.md new file mode 100644 index 0000000000..b2fa502f3d --- /dev/null +++ b/docs/specs/artifacts/maven-gradle-metadata/tasks.md @@ -0,0 +1,11 @@ +# Tasks + +- [x] Record the outcome, requirements and non-goals. +- [x] Add the domain schema, version-kind helpers and unresolved-reference shape. +- [x] Add the parser for Maven POM XML and Gradle module metadata JSON. +- [x] Add the provider with the file-size budget and its remediation. +- [x] Add the CLI command and register the MCP tool over the same provider. +- [x] Document the command, the report and the bounds. +- [x] Link the guide from `docs/README.md` and the VitePress index. +- [x] Add parser, CLI, MCP and absolute-path tests. +- [x] Run the static, formatting and focused test gates. diff --git a/scripts/lib/module-layers.mjs b/scripts/lib/module-layers.mjs index 546b4d4d9c..9ff1578fd2 100644 --- a/scripts/lib/module-layers.mjs +++ b/scripts/lib/module-layers.mjs @@ -77,6 +77,7 @@ export const UNIT_LAYERS = Object.freeze( "il2cpp", "inspector", "javascript", + "java", "jeb", "kuna", "model", @@ -317,6 +318,10 @@ export const ENTRY_FILES = Object.freeze( "Il2cppMetadataProvider.ts", ], inspector: ["V8InspectorProvider.ts", "providerIdentity.ts"], + java: [ + "MavenGradleMetadataProvider.ts", + "MavenGradleMetadataProviderIdentity.ts", + ], javascript: [ "analysis/JavaScriptAnalysisTransfer.ts", "analysis/JavaScriptAnalysisWorkerServer.ts", diff --git a/scripts/lib/test-projects.mjs b/scripts/lib/test-projects.mjs index 61922d3ff4..ef3b0b1b31 100644 --- a/scripts/lib/test-projects.mjs +++ b/scripts/lib/test-projects.mjs @@ -19,7 +19,7 @@ export const SOURCE_TEST_PROJECTS = [ group: "source", include: [ "src/*.test.ts", - "src/{android,apkSignature,apktool,jeb,adb,artifacts,browser,compression,config,cutter,desktop,dotnet,electron,erlang,evm,firmware,flutter,frida,pcap,ghidra,go,gpu,hopper,hopperPaths,ida,inspector,javascript,kuna,main,native,nuget,process,providers,python,reference,resources,rust,server,sqlite,v8,wasm,windows}/**/*.test.ts", + "src/{android,apkSignature,apktool,jeb,adb,artifacts,browser,compression,config,cutter,desktop,dotnet,electron,erlang,evm,firmware,flutter,frida,pcap,ghidra,go,gpu,hopper,hopperPaths,ida,inspector,java,javascript,kuna,main,native,nuget,process,providers,python,reference,resources,rust,server,sqlite,v8,wasm,windows}/**/*.test.ts", ], }, { diff --git a/scripts/verify/advertised-schemas/tools/inspect_maven_gradle_metadata.json b/scripts/verify/advertised-schemas/tools/inspect_maven_gradle_metadata.json new file mode 100644 index 0000000000..c6fcb641f5 --- /dev/null +++ b/scripts/verify/advertised-schemas/tools/inspect_maven_gradle_metadata.json @@ -0,0 +1,9 @@ +{ + "schemas": { + "input compact": "14d15ae0b2da05c0", + "output compact": "4bda7c3651bfc579" + }, + "patterns": { + "input": ["^[^\\x00]*$"] + } +} diff --git a/src/application/java/MavenGradleMetadataService.test.ts b/src/application/java/MavenGradleMetadataService.test.ts new file mode 100644 index 0000000000..381607ca18 --- /dev/null +++ b/src/application/java/MavenGradleMetadataService.test.ts @@ -0,0 +1,119 @@ +import { createHash } from "node:crypto"; +import { expect, it } from "vitest"; + +import { + AnalysisOutputError, + AnalysisCancelledError, +} from "../../domain/analysisErrorCore.js"; +import { parseEvidence } from "../../domain/evidence.js"; +import { ok } from "../../domain/result.js"; +import type { MavenGradleMetadata } from "../../domain/java/mavenGradleMetadata.js"; +import { parseMavenGradleMetadata } from "../../java/MavenGradleMetadataParser.js"; +import { mavenPomFixture } from "../../java/MavenGradleMetadata.fixture.js"; +import { MavenGradleMetadataService } from "./MavenGradleMetadataService.js"; + +const reportFor = (): MavenGradleMetadata => { + const bytes = Buffer.from(mavenPomFixture, "utf8"); + return parseMavenGradleMetadata(bytes, { + path: "/artifacts/pom.xml", + sha256: createHash("sha256").update(bytes).digest("hex"), + bytes: bytes.length, + }); +}; + +const serviceFor = (report: MavenGradleMetadata) => + new MavenGradleMetadataService({ + identity: { + id: "metadata-fixture", + name: "Metadata fixture", + version: "1", + }, + close: async () => {}, + inspect: async () => ok(report), + }); + +const inspect = (report: MavenGradleMetadata, path = report.artifact.path) => + serviceFor(report).inspect({ path }); + +it("retains completed Evidence and selected parameters on late cancellation", async () => { + const report = reportFor(); + const controller = new AbortController(); + const reason = { source: "metadata completion" }; + const provider = serviceFor(report).provider; + const service = new MavenGradleMetadataService({ + ...provider, + inspect: async () => { + controller.abort(reason); + return ok(report); + }, + }); + const result = await service.inspect( + { path: report.artifact.path }, + { signal: controller.signal }, + ); + if (result.ok) throw new Error("Expected late cancellation"); + expect(result.error).toBeInstanceOf(AnalysisCancelledError); + expect(result.error.cause).toBe(reason); + expect(result.error.partialObservation).toMatchObject({ + operation: "inspect_maven_gradle_metadata", + parameters: { path: report.artifact.path }, + normalized_result: report, + }); +}); + +it("rejects complete coverage claiming the wrong examined byte count", async () => { + const report = reportFor(); + const result = await inspect({ + ...report, + coverage: { ...report.coverage, examined_bytes: report.artifact.bytes + 8 }, + }); + expect(result.ok).toBe(false); + if (!result.ok) expect(result.error).toBeInstanceOf(AnalysisOutputError); +}); + +it("rejects a report whose artifact identity disagrees with the caller path", async () => { + const report = reportFor(); + const result = await inspect( + { + ...report, + artifact: { ...report.artifact, path: "/other/pom.xml" }, + }, + report.artifact.path, + ); + expect(result.ok).toBe(false); + if (!result.ok) expect(result.error).toBeInstanceOf(AnalysisOutputError); +}); + +it("retains observed coordinates and unresolved property references", async () => { + const report = reportFor(); + const result = await inspect(report); + if (!result.ok) throw result.error; + expect(parseEvidence(result.value).normalized_result).toMatchObject({ + format: "maven-pom", + coordinates: { + artifact_id: "demo", + version: "${revision}", + }, + coverage: { status: "complete", examined_bytes: report.artifact.bytes }, + }); + expect(result.value.confidence).toBe("observed"); +}); + +it("keeps an omitted read budget out of Evidence parameters", async () => { + const report = reportFor(); + const omitted = await inspect(report); + if (!omitted.ok) throw omitted.error; + expect(parseEvidence(omitted.value).parameters).toStrictEqual({ + path: report.artifact.path, + }); + + const explicit = await serviceFor(report).inspect({ + path: report.artifact.path, + max_file_bytes: 1024 * 1024, + }); + if (!explicit.ok) throw explicit.error; + expect(parseEvidence(explicit.value).parameters).toStrictEqual({ + path: report.artifact.path, + max_file_bytes: 1024 * 1024, + }); +}); diff --git a/src/application/java/MavenGradleMetadataService.ts b/src/application/java/MavenGradleMetadataService.ts new file mode 100644 index 0000000000..0b3866d8b0 --- /dev/null +++ b/src/application/java/MavenGradleMetadataService.ts @@ -0,0 +1,93 @@ +import type { ExecutionOptions } from "../../ports/AnalysisProvider.js"; +import type { MavenGradleMetadataPort } from "../../ports/java/MavenGradleMetadataPort.js"; +import type { AnalysisError } from "../../domain/analysisErrorBase.js"; +import { AnalysisOutputError } from "../../domain/analysisErrorCore.js"; +import { createEvidence, type Evidence } from "../../domain/evidence.js"; +import { + inspectMavenGradleMetadataInputSchema, + mavenGradleMetadataSchema, + type MavenGradleMetadata, +} from "../../domain/java/mavenGradleMetadata.js"; +import { err, type Result } from "../../domain/result.js"; +import { completeProviderEvidence } from "../ProviderOperationExecution.js"; +import { + callerAnalysisParameters, + parseAnalysisInput, +} from "../AnalysisInput.js"; + +const OPERATION = "inspect_maven_gradle_metadata"; + +/** Shared caller validation, output parsing and Evidence provenance for CLI/MCP. */ +export class MavenGradleMetadataService { + constructor(readonly provider: MavenGradleMetadataPort) {} + + close(): Promise { + return this.provider.close(); + } + + async inspect( + rawInput: unknown, + options?: ExecutionOptions, + ): Promise> { + const selectedParameters = callerAnalysisParameters(rawInput); + const input = parseAnalysisInput( + OPERATION, + rawInput, + inspectMavenGradleMetadataInputSchema, + options?.signal, + ); + if (!input.ok) return input; + const result = await this.provider.inspect(input.value, options); + if (!result.ok) return result; + const report = mavenGradleMetadataSchema.safeParse(result.value); + if ( + !report.success || + report.data.artifact.path !== input.value.path || + !validReport(report.data, input.value) + ) + return err( + new AnalysisOutputError( + OPERATION, + "Maven/Gradle metadata provider returned malformed output or changed artifact identity.", + ), + ); + const value = report.data; + return completeProviderEvidence( + createEvidence( + { + path: value.artifact.path, + format: "file", + sha256: value.artifact.sha256, + }, + this.provider.identity, + { + operation: OPERATION, + parameters: selectedParameters(input.value), + result: value, + confidence: "observed", + limitations: value.limitations, + locations: [ + { kind: "artifact-path" as const, path: value.artifact.path }, + { + kind: "file-offset-range" as const, + start: 0, + end: value.artifact.bytes, + }, + ], + }, + ), + options?.signal, + ); + } +} + +const validReport = ( + report: MavenGradleMetadata, + input: { max_file_bytes: number }, +): boolean => { + if (report.artifact.bytes > input.max_file_bytes) return false; + if (report.coverage.examined_bytes !== report.artifact.bytes) return false; + if (report.format === "maven-pom" && report.gradle !== null) return false; + if (report.format === "gradle-module" && report.parent !== null) return false; + return true; +}; diff --git a/src/cli.ts b/src/cli.ts index d3852a6bf4..dbc01d356d 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -34,6 +34,7 @@ import * as pythonPycModule from "./cli/pythonPycCommands.js"; import * as nugetNupkgModule from "./cli/nugetNupkgCommands.js"; import * as erlangModule from "./cli/erlangCommands.js"; import * as v8CodeCacheModule from "./cli/v8CodeCacheCommands.js"; +import * as mavenGradleMetadataModule from "./cli/mavenGradleMetadataCommands.js"; import * as sqliteModule from "./cli/sqliteCommands.js"; import * as artifactModule from "./cli/artifactCommands.js"; import * as managedModule from "./cli/managedCommands.js"; @@ -91,6 +92,7 @@ const CLI_COMMAND_MODULES: CliCommandModules = { nugetNupkg: nugetNupkgModule, erlang: erlangModule, v8CodeCache: v8CodeCacheModule, + mavenGradleMetadata: mavenGradleMetadataModule, sqlite: sqliteModule, artifact: artifactModule, managed: managedModule, diff --git a/src/cli/cliCommandRegistrations.ts b/src/cli/cliCommandRegistrations.ts index ada30569ef..131e592649 100644 --- a/src/cli/cliCommandRegistrations.ts +++ b/src/cli/cliCommandRegistrations.ts @@ -165,6 +165,11 @@ export const CLI_COMMAND_REGISTRATIONS = { (module, context) => module.registerV8CodeCacheCommands(context.cli, context.logger), ), + mavenGradleMetadata: plain( + () => import("./mavenGradleMetadataCommands.js"), + (module, context) => + module.registerMavenGradleMetadataCommands(context.cli, context.logger), + ), sqlite: plain( () => import("./sqliteCommands.js"), (module, context) => @@ -450,6 +455,7 @@ const CLI_FAMILY_REGISTRATIONS: { "nugetNupkg", "erlang", "v8CodeCache", + "mavenGradleMetadata", "sqlite", "artifact", ], diff --git a/src/cli/mavenGradleMetadataCommands.ts b/src/cli/mavenGradleMetadataCommands.ts new file mode 100644 index 0000000000..d2a910068f --- /dev/null +++ b/src/cli/mavenGradleMetadataCommands.ts @@ -0,0 +1,40 @@ +import type { Logger } from "pino"; + +import { createMavenGradleMetadataService } from "../composition/mavenGradleMetadata.js"; +import { MAVEN_GRADLE_METADATA_TOOL_CONTRACTS } from "../contracts/java/mavenGradleMetadataToolContracts.js"; +import { contractNamed } from "./contractCliDescription.js"; +import { + inspectWithService, + registerContractCommand, +} from "./contractCommand.js"; +import type { CliInstance } from "./types.js"; + +/** Inspect operator-selected POM or module metadata through the same shared workflow as MCP. */ +export const registerMavenGradleMetadataCommands = ( + cli: CliInstance, + logger: Logger, +): void => { + registerContractCommand( + cli, + logger, + contractNamed( + MAVEN_GRADLE_METADATA_TOOL_CONTRACTS, + "inspect_maven_gradle_metadata", + ), + { + description: + "Inspect a Maven POM or Gradle module-metadata document without running Maven or Gradle", + positionals: ["path"], + callerPaths: ["path"], + fields: { + path: { + description: "Local Maven pom.xml or Gradle .module metadata file", + }, + }, + }, + inspectWithService( + createMavenGradleMetadataService, + "rea-maven-gradle-metadata", + ), + ); +}; diff --git a/src/composition/capabilityDeclarations.ts b/src/composition/capabilityDeclarations.ts index 7be09b128a..94c23e702a 100644 --- a/src/composition/capabilityDeclarations.ts +++ b/src/composition/capabilityDeclarations.ts @@ -62,6 +62,7 @@ import { import { ELECTRON_FUSE_PROVIDER_IDENTITY } from "../electron/ElectronFuseProviderIdentity.js"; import { ERLANG_BEAM_PROVIDER_IDENTITY } from "../erlang/ErlangBeamProviderIdentity.js"; import { V8_CODE_CACHE_PROVIDER_IDENTITY } from "../v8/V8CodeCacheProviderIdentity.js"; +import { MAVEN_GRADLE_METADATA_PROVIDER_IDENTITY } from "../java/MavenGradleMetadataProviderIdentity.js"; import { EVMOLE_PROVIDER_IDENTITY } from "../evm/EvmoleProviderIdentity.js"; import { BINWALK_PROVIDER_IDENTITY, @@ -520,6 +521,13 @@ export const CAPABILITY_DECLARATIONS = { }), ], }, + mavenGradleMetadata: { + providers: [ + providerBinding(MAVEN_GRADLE_METADATA_PROVIDER_IDENTITY, { + group: "MAVEN_GRADLE_METADATA_TOOL_CONTRACTS", + }), + ], + }, recordedCrash: { providers: [ providerBinding(PWNTOOLS_PROVIDER_IDENTITY, ["inspect_recorded_crash"]), diff --git a/src/composition/capabilityServices.ts b/src/composition/capabilityServices.ts index e9ddda0a6f..b9e591789d 100644 --- a/src/composition/capabilityServices.ts +++ b/src/composition/capabilityServices.ts @@ -30,6 +30,7 @@ import { createGoBinaryService } from "./go.js"; import { createRustBinaryService } from "./rust.js"; import { createBeamService } from "./erlang.js"; import { createV8CodeCacheService } from "./v8CodeCache.js"; +import { createMavenGradleMetadataService } from "./mavenGradleMetadata.js"; import { createModelArtifactService } from "./model.js"; import { createIl2cppMetadataService } from "./il2cpp.js"; import { createElectronFuseService } from "./electronFuses.js"; @@ -102,6 +103,7 @@ import type { PythonPycService } from "../application/python/PythonPycService.js import type { NugetNupkgService } from "../application/nuget/NugetNupkgService.js"; import type { BeamService } from "../application/erlang/BeamService.js"; import type { V8CodeCacheService } from "../application/v8CodeCache/V8CodeCacheService.js"; +import type { MavenGradleMetadataService } from "../application/java/MavenGradleMetadataService.js"; import type { RecordedCrashService } from "../application/binaryDiagnostics/RecordedCrashService.js"; import type { BinaryLayoutService } from "../application/binaryDiagnostics/BinaryLayoutService.js"; import type { BrowserObservationPort } from "../ports/BrowserObservationPort.js"; @@ -142,6 +144,7 @@ export interface CapabilityServiceOptions { readonly nugetNupkg?: NugetNupkgService; readonly erlangBeam?: BeamService; readonly v8CodeCache?: V8CodeCacheService; + readonly mavenGradleMetadata?: MavenGradleMetadataService; readonly electronFuses?: ElectronFuseService; readonly recordedCrash?: RecordedCrashService; readonly firmwareAnalysis?: FirmwareAnalysisPort; @@ -370,6 +373,10 @@ const modules = { v8CodeCache: service( ({ options }) => options.v8CodeCache ?? createV8CodeCacheService(), ), + mavenGradleMetadata: service( + ({ options }) => + options.mavenGradleMetadata ?? createMavenGradleMetadataService(), + ), modelArtifact: service(() => createModelArtifactService()), gpuCodeObjects: service(() => createGpuCodeObjectsService()), il2cppMetadata: service( diff --git a/src/composition/mavenGradleMetadata.ts b/src/composition/mavenGradleMetadata.ts new file mode 100644 index 0000000000..206d3c8e08 --- /dev/null +++ b/src/composition/mavenGradleMetadata.ts @@ -0,0 +1,10 @@ +import type { MavenGradleMetadataPort } from "../ports/java/MavenGradleMetadataPort.js"; +import { MavenGradleMetadataService } from "../application/java/MavenGradleMetadataService.js"; +import { MavenGradleMetadataProvider } from "../java/MavenGradleMetadataProvider.js"; + +/** Compose bundled Maven POM and Gradle module metadata inspection without Maven or Gradle. */ +export const createMavenGradleMetadataService = + (): MavenGradleMetadataService => { + const provider: MavenGradleMetadataPort = new MavenGradleMetadataProvider(); + return new MavenGradleMetadataService(provider); + }; diff --git a/src/contracts/java/mavenGradleMetadataToolContracts.ts b/src/contracts/java/mavenGradleMetadataToolContracts.ts new file mode 100644 index 0000000000..9d069e53bc --- /dev/null +++ b/src/contracts/java/mavenGradleMetadataToolContracts.ts @@ -0,0 +1,32 @@ +import { + inspectMavenGradleMetadataInputSchema, + mavenGradleMetadataSchema, +} from "../../domain/java/mavenGradleMetadata.js"; +import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js"; +import type { ToolContract } from "../toolContractTypes.js"; +import { evidenceEffects, toolContractMetadata } from "../toolEffects.js"; + +/** Static Maven POM and Gradle module metadata inspection is independent of active native-analysis providers. */ +export const MAVEN_GRADLE_METADATA_TOOL_CONTRACTS = [ + { + name: "inspect_maven_gradle_metadata", + availability: "standalone", + cli: true, + ...toolContractMetadata("inspect_maven_gradle_metadata", evidenceEffects), + kind: "artifact-provider", + description: + "Inspect a local Maven pom.xml or Gradle .module metadata file as static bytes, without running Maven or Gradle, resolving a dependency tree, or contacting a repository. Returns artifact identity, coordinates as spelled, parent and property declarations, dependency and dependencyManagement rows (scope, type, optional, classifier, exclusions, BOM import), Gradle variants and rich versions, and unresolved property or parent-coordinate references as explicit unknowns. Classification is from content, not the suffix. Malformed XML/JSON fails closed; unrecognized documents are unsupported. Resource refusals remain explicit.", + inputSchema: inspectMavenGradleMetadataInputSchema, + outputSchema: evidenceResultOf(mavenGradleMetadataSchema), + examples: [ + { + title: "Read declared Maven coordinates and a BOM import", + input: { path: "/artifacts/pom.xml" }, + }, + { + title: "Read Gradle module variants and version constraints", + input: { path: "/artifacts/demo-1.2.3.module" }, + }, + ], + }, +] as const satisfies readonly ToolContract[]; diff --git a/src/contracts/toolContracts.ts b/src/contracts/toolContracts.ts index 17edd88353..0b61a70dfb 100644 --- a/src/contracts/toolContracts.ts +++ b/src/contracts/toolContracts.ts @@ -15,6 +15,7 @@ import { PYTHON_PYC_TOOL_CONTRACTS } from "./python/pythonPycToolContracts.js"; import { NUGET_NUPKG_TOOL_CONTRACTS } from "./nuget/nupkgToolContracts.js"; import { ERLANG_BEAM_TOOL_CONTRACTS } from "./erlang/beamToolContracts.js"; import { V8_CODE_CACHE_TOOL_CONTRACTS } from "./v8/v8CodeCacheToolContracts.js"; +import { MAVEN_GRADLE_METADATA_TOOL_CONTRACTS } from "./java/mavenGradleMetadataToolContracts.js"; import { SQLITE_TOOL_CONTRACTS } from "./sqlite/sqliteToolContracts.js"; import { ANALYSIS_VIEW_TOOL_CONTRACTS } from "./analysisViewToolContracts.js"; import { BINARY_DIAGNOSTICS_TOOL_CONTRACTS } from "./native/binaryDiagnosticsToolContracts.js"; @@ -74,6 +75,7 @@ const CATALOG_CONTRACT_GROUPS = { NUGET_NUPKG_TOOL_CONTRACTS, ERLANG_BEAM_TOOL_CONTRACTS, V8_CODE_CACHE_TOOL_CONTRACTS, + MAVEN_GRADLE_METADATA_TOOL_CONTRACTS, WASM_TOOL_CONTRACTS, APK_SIGNATURE_TOOL_CONTRACTS, SQLITE_TOOL_CONTRACTS, diff --git a/src/contracts/toolFamilies.ts b/src/contracts/toolFamilies.ts index 9417ab4b40..007c49b47d 100644 --- a/src/contracts/toolFamilies.ts +++ b/src/contracts/toolFamilies.ts @@ -53,6 +53,7 @@ export const TOOL_FAMILY_DEFINITIONS = [ ...TOOL_CONTRACT_GROUPS.NUGET_NUPKG_TOOL_CONTRACTS, ...TOOL_CONTRACT_GROUPS.ERLANG_BEAM_TOOL_CONTRACTS, ...TOOL_CONTRACT_GROUPS.V8_CODE_CACHE_TOOL_CONTRACTS, + ...TOOL_CONTRACT_GROUPS.MAVEN_GRADLE_METADATA_TOOL_CONTRACTS, ...TOOL_CONTRACT_GROUPS.WASM_TOOL_CONTRACTS, ...TOOL_CONTRACT_GROUPS.APK_SIGNATURE_TOOL_CONTRACTS, ...TOOL_CONTRACT_GROUPS.SQLITE_TOOL_CONTRACTS, diff --git a/src/domain/artifactOperationError.ts b/src/domain/artifactOperationError.ts index 08b841116e..6418476593 100644 --- a/src/domain/artifactOperationError.ts +++ b/src/domain/artifactOperationError.ts @@ -91,6 +91,7 @@ export class ArtifactOperationError extends AnalysisError { | "inspect_erlang_beam" | "inspect_nuget_nupkg" | "inspect_v8_code_cache" + | "inspect_maven_gradle_metadata" | "extract_artifact" | "decode_interface_builder" | "inspect_asset_catalog" diff --git a/src/domain/java/mavenGradleMetadata.test.ts b/src/domain/java/mavenGradleMetadata.test.ts new file mode 100644 index 0000000000..f588f2d296 --- /dev/null +++ b/src/domain/java/mavenGradleMetadata.test.ts @@ -0,0 +1,155 @@ +import { expect, it } from "vitest"; +import { + inspectMavenGradleMetadataInputSchema, + mavenGradleMetadataSchema, + mavenPropertyOccurrences, + requestedVersionKind, +} from "./mavenGradleMetadata.js"; +import { absoluteLocalPathStringSchema } from "../localPath.js"; + +const jsonSchema = (schema: { + readonly "~standard": { + readonly jsonSchema: { + readonly input: (options: { + readonly target: "draft-2020-12"; + }) => unknown; + }; + }; +}): Record => + schema["~standard"].jsonSchema.input({ + target: "draft-2020-12", + }) as Record; + +it("applies the shared absolute local-path policy to the public input", () => { + expect( + inspectMavenGradleMetadataInputSchema.safeParse({ path: "pom.xml" }) + .success, + ).toBe(false); + expect( + inspectMavenGradleMetadataInputSchema.safeParse({ path: "" }).success, + ).toBe(false); + expect( + inspectMavenGradleMetadataInputSchema.safeParse({ + path: "/artifacts/pom\0.xml", + }).success, + ).toBe(false); + expect( + inspectMavenGradleMetadataInputSchema.safeParse({ + path: "/artifacts/pom.xml", + }).success, + ).toBe(true); + + const shared = jsonSchema(absoluteLocalPathStringSchema); + const advertised = jsonSchema(inspectMavenGradleMetadataInputSchema); + const path = ( + advertised.properties as Record> + ).path; + const { + $schema: _schema, + description: _sharedDescription, + ...sharedPolicy + } = shared; + const { description: _pathDescription, ...pathPolicy } = path ?? {}; + expect(pathPolicy).toEqual(sharedPolicy); + expect(path?.description).toBe( + "Absolute filesystem path to a Maven pom.xml or Gradle .module metadata file", + ); +}); + +it("rejects extra caller arguments", () => { + expect( + inspectMavenGradleMetadataInputSchema.safeParse({ + path: "/artifacts/pom.xml", + extra: true, + }).success, + ).toBe(false); +}); + +it("classifies requested versions without interpolating properties", () => { + expect([...mavenPropertyOccurrences("${revision}")]).toEqual(["${revision}"]); + expect([ + ...mavenPropertyOccurrences("${revision}${sha1}${changelist}"), + ]).toEqual(["${revision}", "${sha1}", "${changelist}"]); + expect([...mavenPropertyOccurrences("1.2.3")]).toEqual([]); + expect([...mavenPropertyOccurrences("${}${a${b}")]).toEqual(["${a${b}"]); + expect([...mavenPropertyOccurrences("${a".repeat(100_000))]).toEqual([]); + expect(requestedVersionKind("${jackson.version}", "maven-pom")).toBe( + "property", + ); + expect(requestedVersionKind("[5.10,6.0)", "maven-pom")).toBe("range"); + expect(requestedVersionKind("(,1.0]", "maven-pom")).toBe("range"); + expect(requestedVersionKind("2.17.2", "maven-pom")).toBe("literal"); + expect(requestedVersionKind(null, "maven-pom")).toBe("missing"); + expect(requestedVersionKind("]1.0,2.0]", "gradle-module")).toBe("range"); + expect(requestedVersionKind("[1.0,2.0[", "gradle-module")).toBe("range"); + expect(requestedVersionKind("1.0]", "maven-pom")).toBe("literal"); + expect(requestedVersionKind("1.+", "gradle-module")).toBe("dynamic"); + expect(requestedVersionKind("+", "gradle-module")).toBe("dynamic"); + expect(requestedVersionKind("latest.release", "gradle-module")).toBe( + "dynamic", + ); + expect(requestedVersionKind("latest.integration", "gradle-module")).toBe( + "dynamic", + ); + expect(requestedVersionKind("1.2.3", "gradle-module")).toBe("literal"); + expect(requestedVersionKind("1.+", "maven-pom")).toBe("literal"); +}); + +it("offers property occurrences lazily without retaining or deduplicating a collection", () => { + const occurrences = mavenPropertyOccurrences("${first}${first}${second}"); + expect(occurrences.next()).toEqual({ value: "${first}", done: false }); + expect(occurrences.next()).toEqual({ value: "${first}", done: false }); + expect(occurrences.next()).toEqual({ value: "${second}", done: false }); + expect(occurrences.next().done).toBe(true); +}); + +it("admits a complete POM report with unresolved parent and property references", () => { + const report = mavenGradleMetadataSchema.parse({ + artifact: { + path: "/artifacts/pom.xml", + sha256: "a".repeat(64), + bytes: 16, + }, + format: "maven-pom", + coordinates: { + group_id: null, + artifact_id: "demo", + version: "${revision}", + packaging: "jar", + }, + parent: { + group_id: "com.example", + artifact_id: "demo-parent", + version: "9.0.0", + packaging: null, + relative_path: "../pom.xml", + relative_path_declared: true, + }, + properties: [ + { name: "revision", value: "1.2.3", value_credentials_redacted: false }, + ], + dependencies: [], + dependency_management: [], + gradle: null, + unresolved: [ + { + kind: "parent-coordinate", + reference: "parent.group_id", + field: "group_id", + owner: "project", + index: null, + }, + { + kind: "property", + reference: "${revision}", + field: "version", + owner: "project", + index: null, + }, + ], + coverage: { status: "complete", examined_bytes: 16 }, + limitations: ["No Maven or Gradle execution was performed."], + }); + expect(report.coordinates.artifact_id).toBe("demo"); + expect(report.unresolved).toHaveLength(2); +}); diff --git a/src/domain/java/mavenGradleMetadata.ts b/src/domain/java/mavenGradleMetadata.ts new file mode 100644 index 0000000000..efeef58e92 --- /dev/null +++ b/src/domain/java/mavenGradleMetadata.ts @@ -0,0 +1,255 @@ +import { z } from "zod"; + +import { digestSchema } from "../digests.js"; +import { absoluteLocalPathStringSchema } from "../localPath.js"; + +const uint = z.number().int().min(0).max(0xffffffff); + +/** Hard ceiling on the caller-selected input read budget. */ +export const MAX_INSPECT_MAVEN_GRADLE_METADATA_FILE_BYTES = 16 * 1024 * 1024; + +/** + * Fixed allowance for variant-name characters repeated across Gradle dependency + * and constraint rows (name length times rows, summed over variants). + */ +export const MAVEN_GRADLE_METADATA_REPEATED_VARIANT_NAME_CHARS = + 4 * 1024 * 1024; + +/** + * Fixed allowance for dependency plus constraint rows in one report. A row + * spelled in two or three input bytes (`{}` or ``) becomes a full + * row and up to three unresolved records, a few hundred bytes of report; the + * largest published BOMs declare a few thousand rows. + */ +export const MAVEN_GRADLE_METADATA_DEPENDENCY_ROWS = 65_536; + +/** + * Fixed allowance for Gradle variants in one module file. An empty variant + * (`{}`) becomes a full variant record; published modules, including Kotlin + * Multiplatform roots with one variant per target and usage, declare at most a + * few hundred. + */ +export const MAVEN_GRADLE_METADATA_VARIANTS = 4_096; + +/** + * Fixed allowance for dependency exclusions summed over every row in one + * report. An empty exclusion (`{}` or ``) becomes a full exclusion + * record; real rows exclude a handful of modules each. + */ +export const MAVEN_GRADLE_METADATA_EXCLUSIONS = 65_536; + +/** Fixed allowance for expanded property-reference and coordinate-gap records. */ +export const MAVEN_GRADLE_METADATA_UNRESOLVED_RECORDS = 65_536; + +/** + * Fixed allowance for XML nodes (elements, attributes, text, CDATA, comments + * and processing instructions) in one Maven POM, counted as a stream before + * the document tree is built. Each node costs hundreds of bytes of tree, so a + * 16 MiB POM of tiny elements could otherwise allocate gigabytes; the + * allowance still admits a POM at the dependency-row allowance with a dozen + * nodes per row. + */ +export const MAVEN_GRADLE_METADATA_XML_NODES = 1_048_576; + +/** Detected metadata document; classification is from content, not the suffix. */ +export const MAVEN_GRADLE_METADATA_FORMATS = [ + "maven-pom", + "gradle-module", +] as const; +export type MavenGradleMetadataFormat = + (typeof MAVEN_GRADLE_METADATA_FORMATS)[number]; + +const nullableText = z.string().min(1).nullable(); + +/** + * Property occurrences in source order, without collecting or deduplicating. + * A `${` with no later `}` ends the scan, so matching stays linear. Consumers + * retaining references own their admission and deduplication before storage. + */ +export function* mavenPropertyOccurrences( + value: string | null, +): Generator { + if (value === null) return; + let start = value.indexOf("${"); + while (start >= 0) { + const close = value.indexOf("}", start + 2); + if (close < 0) break; + if (close > start + 2) yield value.slice(start, close + 1); + start = value.indexOf("${", close > start + 2 ? close + 1 : start + 2); + } +} + +export const REQUESTED_VERSION_KINDS = [ + "literal", + "range", + "dynamic", + "property", + "missing", +] as const; +export type RequestedVersionKind = (typeof REQUESTED_VERSION_KINDS)[number]; + +/** + * Classify a requested version as spelled for its document format, without + * interpolating or resolving. Gradle also writes an exclusive lower bound as `]`, + * and selects a version dynamically for a `+` prefix (`1.+`, `+`) or a + * `latest.` selector (`latest.release`). + */ +export const requestedVersionKind = ( + value: string | null, + format: MavenGradleMetadataFormat, +): RequestedVersionKind => { + if (value === null) return "missing"; + if (!mavenPropertyOccurrences(value).next().done) return "property"; + const rangeDelimiter = format === "gradle-module" ? /[[(\]]/u : /[[(]/u; + if (rangeDelimiter.test(value)) return "range"; + if ( + format === "gradle-module" && + (value.endsWith("+") || /^latest\.[^.]+$/u.test(value)) + ) + return "dynamic"; + return "literal"; +}; + +/** Bounded inspection of one Maven POM or Gradle module-metadata document. */ +export const inspectMavenGradleMetadataInputSchema = z.strictObject({ + path: absoluteLocalPathStringSchema.describe( + "Absolute filesystem path to a Maven pom.xml or Gradle .module metadata file", + ), + max_file_bytes: z + .number() + .int() + .min(1) + .max(MAX_INSPECT_MAVEN_GRADLE_METADATA_FILE_BYTES) + .default(1024 * 1024) + .describe( + "Maximum stable artifact bytes to read; exceeding the budget fails without partial success", + ), +}); + +const coordinateSchema = z.strictObject({ + group_id: nullableText, + artifact_id: nullableText, + version: nullableText, + packaging: nullableText, +}); + +const exclusionSchema = z.strictObject({ + group_id: nullableText, + artifact_id: nullableText, +}); + +const gradleVersionSchema = z.strictObject({ + requires: nullableText, + prefers: nullableText, + strictly: nullableText, + rejects: z.array(z.string().min(1)), +}); + +const dependencySchema = z.strictObject({ + group_id: nullableText, + artifact_id: nullableText, + version: nullableText, + version_kind: z.enum(REQUESTED_VERSION_KINDS), + gradle_version: gradleVersionSchema.nullable(), + scope: nullableText, + type: nullableText, + optional: z.boolean().nullable(), + optional_spelling: nullableText, + classifier: nullableText, + exclusions: z.array(exclusionSchema), + origin: z.enum([ + "dependencies", + "dependencyManagement", + "variant-dependencies", + "variant-constraints", + ]), + variant: nullableText, + bom_import: z.boolean(), + platform: z.boolean(), +}); + +const unresolvedSchema = z.strictObject({ + kind: z.enum(["property", "parent-coordinate", "missing-coordinate"]), + reference: z.string().min(1), + field: z.enum([ + "group_id", + "artifact_id", + "version", + "packaging", + "scope", + "type", + "classifier", + "optional", + ]), + owner: z.enum([ + "project", + "parent", + "dependency", + "dependency_management", + "variant", + ]), + index: z.number().int().nonnegative().nullable(), +}); + +const gradleVariantSchema = z.strictObject({ + name: nullableText, + category: nullableText, + usage: nullableText, + available_at: z + .strictObject({ + group_id: nullableText, + artifact_id: nullableText, + version: nullableText, + url: nullableText, + url_credentials_redacted: z.boolean(), + }) + .nullable(), + dependency_count: uint, + constraint_count: uint, +}); + +/** Observed Maven POM or Gradle module metadata; unresolved references stay explicit. */ +export const mavenGradleMetadataSchema = z.strictObject({ + artifact: z.strictObject({ + path: z.string().min(1), + sha256: digestSchema, + bytes: uint, + }), + format: z.enum(MAVEN_GRADLE_METADATA_FORMATS), + coordinates: coordinateSchema, + parent: coordinateSchema + .extend({ + relative_path: nullableText, + relative_path_declared: z.boolean(), + }) + .nullable(), + properties: z.array( + z.strictObject({ + name: z.string().min(1), + value: nullableText, + value_credentials_redacted: z.boolean(), + }), + ), + dependencies: z.array(dependencySchema), + dependency_management: z.array(dependencySchema), + gradle: z + .strictObject({ + format_version: nullableText, + created_by_gradle: nullableText, + variants: z.array(gradleVariantSchema), + }) + .nullable(), + unresolved: z.array(unresolvedSchema), + coverage: z.strictObject({ + status: z.literal("complete"), + examined_bytes: uint, + }), + limitations: z.array(z.string().min(1)).min(1), +}); + +export type MavenGradleMetadata = z.infer; +export type InspectMavenGradleMetadataInput = z.infer< + typeof inspectMavenGradleMetadataInputSchema +>; +export type MavenGradleDependency = MavenGradleMetadata["dependencies"][number]; +export type MavenGradleUnresolved = MavenGradleMetadata["unresolved"][number]; diff --git a/src/domain/xmlDocument.ts b/src/domain/xmlDocument.ts index 685b639131..7648829a55 100644 --- a/src/domain/xmlDocument.ts +++ b/src/domain/xmlDocument.ts @@ -245,6 +245,48 @@ export const xmlAttributeQuoteRanges = ( } }; +/** + * Stops the stream once counting has passed the limit. It never leaves + * countXmlNodes, which returns the count instead of reporting a failure. + */ +class StopXmlNodeCount extends Error {} + +/** + * How many nodes the DOM projection of `source` would hold (elements, + * attributes, text, CDATA, comments and processing instructions), read as a + * stream without building a document. Counting stops at `limit + 1`, so a + * caller can refuse an oversized document before `parseXmlDocument` + * allocates its tree. Ill-formed XML returns the nodes read before the + * error; `parseXmlDocument` reports the failure itself. + */ +export const countXmlNodes = (source: string, limit: number): number => { + let nodes = 0; + const count = () => { + nodes += 1; + if (nodes > limit) throw new StopXmlNodeCount(); + }; + try { + checkXmlSyntax(source, "allow", (syntax) => { + // Only the syntax owner's explicit error signal may defer diagnosis to + // parseXmlDocument. An unrelated counting failure cannot admit a DOM. + syntax.on("error", (cause) => { + throw notWellFormed(cause); + }); + syntax.on("opentagstart", count); + syntax.on("attribute", count); + syntax.on("text", count); + syntax.on("cdata", count); + syntax.on("comment", count); + syntax.on("processinginstruction", count); + }); + } catch (cause: unknown) { + if (!(cause instanceof StopXmlNodeCount) && !isXmlFailure(cause)) + throw cause; + // A known count stop, or syntax failure parseXmlDocument reports. + } + return nodes; +}; + /** One boundary owns strict XML syntax, under a DOCTYPE policy, and the source-located DOM projection. */ export const parseXmlDocument = ( source: string, diff --git a/src/generatedPackageMetadata.ts b/src/generatedPackageMetadata.ts index f54f8b6b9e..d9d9a7e505 100644 --- a/src/generatedPackageMetadata.ts +++ b/src/generatedPackageMetadata.ts @@ -6,5 +6,5 @@ export const PACKAGE_METADATA = { serverSdkVersion: "2.3.1", clientSdkVersion: "2.3.1", coreSdkVersion: "2.3.1", - skillVersion: "62", + skillVersion: "63", } as const; diff --git a/src/java/MavenGradleMetadata.errors.ts b/src/java/MavenGradleMetadata.errors.ts new file mode 100644 index 0000000000..06b394c43e --- /dev/null +++ b/src/java/MavenGradleMetadata.errors.ts @@ -0,0 +1,48 @@ +import { decodeLimit } from "../domain/parseFailure.js"; +/** The ParseFailure format of a Maven POM or Gradle module metadata file. */ +export const MAVEN_GRADLE_METADATA_FORMAT = "maven-gradle-metadata"; + +/** Fixed report allowances; each names the representation it bounds. */ +export type MavenGradleReportAllowance = + | "repeated_variant_name_chars" + | "dependency_rows" + | "variants" + | "exclusions" + | "unresolved_records" + | "xml_nodes"; + +const REPORT_REFUSALS: Readonly< + Record< + MavenGradleReportAllowance, + (required: number, limit: number) => string + > +> = { + repeated_variant_name_chars: (required, limit) => + `Gradle module metadata would repeat ${String(required)} characters of variant names across its dependency rows, above the ${String(limit)}-character report allowance.`, + dependency_rows: (required, limit) => + `Metadata declares ${String(required)} dependency and constraint rows, above the ${String(limit)}-row report allowance.`, + variants: (required, limit) => + `Gradle module metadata declares ${String(required)} variants, above the ${String(limit)}-variant report allowance.`, + exclusions: (required, limit) => + `Metadata declares ${String(required)} dependency exclusions, above the ${String(limit)}-exclusion report allowance.`, + unresolved_records: (required, limit) => + `Metadata needs at least ${String(required)} unresolved reference and coordinate records, above the ${String(limit)}-record report allowance.`, + xml_nodes: (required, limit) => + `Maven POM holds more than ${String(limit)} XML nodes (at least ${String(required)} counted), above the ${String(limit)}-node allowance for its document tree.`, +}; + +/** + * Refuse a report that would grow far past the input bytes. Each dependency + * row (with its unresolved-coordinate records), variant, exclusion and + * repeated variant name expands a few input bytes into a much larger report. + */ +export const metadataReportLimit = ( + allowance: MavenGradleReportAllowance, + maximum: number, + required: number, +) => + decodeLimit( + MAVEN_GRADLE_METADATA_FORMAT, + REPORT_REFUSALS[allowance](required, maximum), + { name: allowance, maximum, required }, + ); diff --git a/src/java/MavenGradleMetadata.fixture.ts b/src/java/MavenGradleMetadata.fixture.ts new file mode 100644 index 0000000000..c337f5062f --- /dev/null +++ b/src/java/MavenGradleMetadata.fixture.ts @@ -0,0 +1,120 @@ +/** Tiny well-formed Maven POM with parent, properties, BOM import, and ranges. */ +export const mavenPomFixture = ` + + 4.0.0 + + com.example + demo-parent + 9.0.0 + ../pom.xml + + demo + \${revision} + jar + + 1.2.3 + 2.17.2 + + + + + org.springframework.boot + spring-boot-dependencies + 3.3.4 + pom + import + + + com.fasterxml.jackson.core + jackson-databind + \${jackson.version} + + + + + + com.fasterxml.jackson.core + jackson-databind + compile + false + + + com.fasterxml.jackson.core + jackson-annotations + + + + + org.junit.jupiter + junit-jupiter + [5.10,6.0) + test + + + +`; + +/** Tiny Gradle Module Metadata 1.1 document with library and platform variants. */ +export const gradleModuleFixture = `{ + "formatVersion": "1.1", + "component": { + "group": "com.example", + "module": "demo", + "version": "1.2.3" + }, + "createdBy": { + "gradle": { + "version": "8.10.2" + } + }, + "variants": [ + { + "name": "apiElements", + "attributes": { + "org.gradle.usage": "java-api", + "org.gradle.category": "library" + }, + "dependencies": [ + { + "group": "com.fasterxml.jackson.core", + "module": "jackson-databind", + "version": { "requires": "2.17.2" }, + "excludes": [ + { + "group": "com.fasterxml.jackson.core", + "module": "jackson-annotations" + } + ] + } + ] + }, + { + "name": "runtimeElements", + "attributes": { + "org.gradle.usage": "java-runtime", + "org.gradle.category": "library" + }, + "dependencyConstraints": [ + { + "group": "org.slf4j", + "module": "slf4j-api", + "version": { "requires": "2.0.16" } + } + ] + }, + { + "name": "demoPlatform", + "attributes": { + "org.gradle.category": "platform" + }, + "dependencyConstraints": [ + { + "group": "com.fasterxml.jackson.core", + "module": "jackson-databind", + "version": { "strictly": "[2.17,2.18)" } + } + ] + } + ] +} +`; diff --git a/src/java/MavenGradleMetadataParser.test.ts b/src/java/MavenGradleMetadataParser.test.ts new file mode 100644 index 0000000000..d15c7ce8f2 --- /dev/null +++ b/src/java/MavenGradleMetadataParser.test.ts @@ -0,0 +1,1009 @@ +import { ParseFailureError } from "../domain/parseFailure.js"; +import { createHash } from "node:crypto"; +import { writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { expect, it, vi } from "vitest"; +import { SaxesParser } from "saxes"; +import { DOMParser } from "@xmldom/xmldom"; +import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js"; +import { + mavenGradleMetadataSchema, + type MavenGradleMetadata, +} from "../domain/java/mavenGradleMetadata.js"; +import { + gradleModuleFixture, + mavenPomFixture, +} from "./MavenGradleMetadata.fixture.js"; +import { MavenGradleMetadataProvider } from "./MavenGradleMetadataProvider.js"; +import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; +import { parseMavenGradleMetadata } from "./MavenGradleMetadataParser.js"; + +const parse = (source: string, path = "/artifacts/pom.xml") => { + const bytes = Buffer.from(source, "utf8"); + const report = parseMavenGradleMetadata(bytes, { + path, + sha256: createHash("sha256").update(bytes).digest("hex"), + bytes: bytes.length, + }); + const validated = mavenGradleMetadataSchema.safeParse(report); + expect(validated.success, JSON.stringify(validated.error)).toBe(true); + return report; +}; + +it("keeps a missing child artifact separate from inheritable parent coordinates", () => { + const report = parse( + `4.0.0exampleparent1`, + ); + expect(report.coordinates).toEqual({ + group_id: null, + artifact_id: null, + version: null, + packaging: null, + }); + expect(report.unresolved).toEqual([ + { + kind: "parent-coordinate", + reference: "parent.group_id", + field: "group_id", + owner: "project", + index: null, + }, + { + kind: "missing-coordinate", + reference: "project.artifact_id", + field: "artifact_id", + owner: "project", + index: null, + }, + { + kind: "parent-coordinate", + reference: "parent.version", + field: "version", + owner: "project", + index: null, + }, + ]); +}); + +it("preserves an opaque XML counting failure without allocating a DOM", () => { + const cause = new Error("controlled XML counter failure"); + const syntax = vi + .spyOn(SaxesParser.prototype, "write") + .mockImplementationOnce(() => { + throw cause; + }); + const dom = vi.spyOn(DOMParser.prototype, "parseFromString"); + try { + let failure: unknown; + try { + parse(mavenPomFixture); + } catch (caught) { + failure = caught; + } + expect(failure).toBe(cause); + expect(dom).not.toHaveBeenCalled(); + } finally { + syntax.mockRestore(); + dom.mockRestore(); + } +}); + +const expectFailure = ( + source: string | Uint8Array, + kind: "malformed" | "unsupported", +) => { + const bytes = + typeof source === "string" ? Buffer.from(source, "utf8") : source; + expect(() => + parseMavenGradleMetadata(bytes, { + path: "/artifacts/selected", + sha256: createHash("sha256").update(bytes).digest("hex"), + bytes: bytes.length, + }), + ).toThrow(ParseFailureError); + try { + parseMavenGradleMetadata(bytes, { + path: "/artifacts/selected", + sha256: createHash("sha256").update(bytes).digest("hex"), + bytes: bytes.length, + }); + } catch (cause) { + expect(cause).toBeInstanceOf(ParseFailureError); + if (cause instanceof ParseFailureError) + expect(cause.failure.kind).toBe(kind); + } +}; + +it("reads Maven coordinates, parent, BOM import, exclusions, ranges and unresolved properties", () => { + const report = parse(mavenPomFixture); + expect(report.format).toBe("maven-pom"); + expect(report.coordinates).toEqual({ + group_id: null, + artifact_id: "demo", + version: "${revision}", + packaging: "jar", + }); + expect(report.parent).toEqual({ + group_id: "com.example", + artifact_id: "demo-parent", + version: "9.0.0", + packaging: null, + relative_path: "../pom.xml", + relative_path_declared: true, + }); + expect(report.properties).toEqual([ + { name: "revision", value: "1.2.3", value_credentials_redacted: false }, + { + name: "jackson.version", + value: "2.17.2", + value_credentials_redacted: false, + }, + ]); + expect(report.dependency_management).toEqual([ + expect.objectContaining({ + group_id: "org.springframework.boot", + artifact_id: "spring-boot-dependencies", + version: "3.3.4", + version_kind: "literal", + type: "pom", + scope: "import", + bom_import: true, + origin: "dependencyManagement", + }), + expect.objectContaining({ + group_id: "com.fasterxml.jackson.core", + artifact_id: "jackson-databind", + version: "${jackson.version}", + version_kind: "property", + origin: "dependencyManagement", + bom_import: false, + }), + ]); + expect(report.dependencies).toEqual([ + expect.objectContaining({ + group_id: "com.fasterxml.jackson.core", + artifact_id: "jackson-databind", + version: null, + version_kind: "missing", + scope: "compile", + optional: false, + optional_spelling: "false", + origin: "dependencies", + exclusions: [ + { + group_id: "com.fasterxml.jackson.core", + artifact_id: "jackson-annotations", + }, + ], + }), + expect.objectContaining({ + group_id: "org.junit.jupiter", + artifact_id: "junit-jupiter", + version: "[5.10,6.0)", + version_kind: "range", + scope: "test", + }), + ]); + expect(report.unresolved).toEqual( + expect.arrayContaining([ + { + kind: "parent-coordinate", + reference: "parent.group_id", + field: "group_id", + owner: "project", + index: null, + }, + { + kind: "property", + reference: "${revision}", + field: "version", + owner: "project", + index: null, + }, + { + kind: "property", + reference: "${jackson.version}", + field: "version", + owner: "dependency_management", + index: 1, + }, + { + kind: "missing-coordinate", + reference: "dependency.version", + field: "version", + owner: "dependency", + index: 0, + }, + ]), + ); + expect(report.gradle).toBeNull(); + expect(report.coverage.status).toBe("complete"); + expect(report.limitations.join(" ")).toMatch( + /without running Maven or Gradle/u, + ); + expect(report.limitations.join(" ")).toMatch(/parent POM was not read/u); +}); + +it("reads Gradle component coordinates, variants, exclusions and platform constraints", () => { + const report = parse(gradleModuleFixture, "/artifacts/demo-1.2.3.module"); + expect(report.format).toBe("gradle-module"); + expect(report.coordinates).toEqual({ + group_id: "com.example", + artifact_id: "demo", + version: "1.2.3", + packaging: null, + }); + expect(report.parent).toBeNull(); + expect(report.gradle).toEqual({ + format_version: "1.1", + created_by_gradle: "8.10.2", + variants: [ + { + name: "apiElements", + category: "library", + usage: "java-api", + available_at: null, + dependency_count: 1, + constraint_count: 0, + }, + { + name: "runtimeElements", + category: "library", + usage: "java-runtime", + available_at: null, + dependency_count: 0, + constraint_count: 1, + }, + { + name: "demoPlatform", + category: "platform", + usage: null, + available_at: null, + dependency_count: 0, + constraint_count: 1, + }, + ], + }); + expect(report.dependencies).toEqual([ + expect.objectContaining({ + group_id: "com.fasterxml.jackson.core", + artifact_id: "jackson-databind", + version: "2.17.2", + version_kind: "literal", + origin: "variant-dependencies", + variant: "apiElements", + platform: false, + exclusions: [ + { + group_id: "com.fasterxml.jackson.core", + artifact_id: "jackson-annotations", + }, + ], + gradle_version: { + requires: "2.17.2", + prefers: null, + strictly: null, + rejects: [], + }, + }), + ]); + expect(report.dependency_management).toEqual([ + expect.objectContaining({ + group_id: "org.slf4j", + artifact_id: "slf4j-api", + version: "2.0.16", + origin: "variant-constraints", + variant: "runtimeElements", + platform: false, + }), + expect.objectContaining({ + group_id: "com.fasterxml.jackson.core", + artifact_id: "jackson-databind", + version: "[2.17,2.18)", + version_kind: "range", + origin: "variant-constraints", + variant: "demoPlatform", + platform: true, + gradle_version: { + requires: null, + prefers: null, + strictly: "[2.17,2.18)", + rejects: [], + }, + }), + ]); + expect(report.limitations.join(" ")).toMatch(/available-at coordinates/u); +}); + +it("does not interpolate Maven properties into coordinates", () => { + const report = parse(mavenPomFixture); + expect(report.coordinates.version).toBe("${revision}"); + expect(report.coordinates.version).not.toBe("1.2.3"); +}); + +it("lists every property in a compound CI-friendly version", () => { + const report = parse(` + com.example + demo + \${revision}\${sha1}\${changelist} +`); + expect(report.coordinates.version).toBe("${revision}${sha1}${changelist}"); + expect( + report.unresolved.filter( + (entry) => entry.owner === "project" && entry.field === "version", + ), + ).toEqual( + ["${revision}", "${sha1}", "${changelist}"].map((reference) => ({ + kind: "property", + reference, + field: "version", + owner: "project", + index: null, + })), + ); +}); + +it("removes credentials from Gradle available-at URLs", () => { + const report = parse( + JSON.stringify({ + formatVersion: "1.1", + component: { group: "com.example", module: "demo", version: "1.0.0" }, + variants: [ + { + name: "secret", + "available-at": { + url: "https://user:password@repo.example/demo-jvm/1.0.0/demo-jvm-1.0.0.module", + group: "com.example", + module: "demo-jvm", + version: "1.0.0", + }, + }, + { + name: "relative", + "available-at": { + url: "../../demo-jvm/1.0.0/demo-jvm-1.0.0.module", + group: "com.example", + module: "demo-jvm", + version: "1.0.0", + }, + }, + ], + }), + "/artifacts/demo-1.0.0.module", + ); + const urls = report.gradle?.variants.map((variant) => ({ + url: variant.available_at?.url, + redacted: variant.available_at?.url_credentials_redacted, + })); + expect(urls).toEqual([ + { + url: "https://repo.example/demo-jvm/1.0.0/demo-jvm-1.0.0.module", + redacted: true, + }, + { url: "../../demo-jvm/1.0.0/demo-jvm-1.0.0.module", redacted: false }, + ]); + expect(JSON.stringify(report)).not.toContain("password"); +}); + +it("removes credentials from POM property values", () => { + const report = parse(` + 4.0.0 + demo + + https://user:password@repo.example/maven + https://repo.example/mirror + user@example.com + +`); + expect(report.properties).toEqual([ + { + name: "repo.url", + value: "https://repo.example/maven", + value_credentials_redacted: true, + }, + { + name: "mirror.url", + value: "https://repo.example/mirror", + value_credentials_redacted: false, + }, + { + name: "owner", + value: "user@example.com", + value_credentials_redacted: false, + }, + ]); + expect(JSON.stringify(report)).not.toContain("password"); +}); + +it("lists properties in packaging, scope, type and classifier", () => { + const report = parse(` + com.example + demo + 1.0.0 + \${artifact.packaging} + + + com.example + lib + 1.0.0 + \${lib.scope} + \${lib.type} + \${os}-\${arch} + + +`); + expect(report.unresolved).toEqual([ + { + kind: "property", + reference: "${artifact.packaging}", + field: "packaging", + owner: "project", + index: null, + }, + ...( + [ + ["scope", "${lib.scope}"], + ["type", "${lib.type}"], + ["classifier", "${os}"], + ["classifier", "${arch}"], + ] as const + ).map(([field, reference]) => ({ + kind: "property", + reference, + field, + owner: "dependency", + index: 0, + })), + ]); +}); + +it("classifies a Gradle exclusive-lower-bound request as a range", () => { + const report = parse( + JSON.stringify({ + formatVersion: "1.1", + component: { group: "com.example", module: "demo", version: "1.0.0" }, + variants: [ + { + name: "apiElements", + dependencies: [ + { + group: "com.example", + module: "lib", + version: { requires: "]1.0,2.0]" }, + }, + ], + }, + ], + }), + "/artifacts/demo-1.0.0.module", + ); + expect(report.dependencies[0]).toMatchObject({ + version: "]1.0,2.0]", + version_kind: "range", + }); +}); + +it.each(["1.+", "latest.release"])( + "classifies a Gradle dynamic selector %s as dynamic, not literal", + (requires) => { + const report = parse( + JSON.stringify({ + formatVersion: "1.1", + component: { group: "com.example", module: "demo", version: "1.0.0" }, + variants: [ + { + name: "apiElements", + dependencies: [ + { group: "com.example", module: "lib", version: { requires } }, + ], + }, + ], + }), + "/artifacts/demo-1.0.0.module", + ); + expect(report.dependencies[0]).toMatchObject({ + version: requires, + version_kind: "dynamic", + }); + }, +); + +it("keeps an empty relativePath and a property-spelled optional distinct from omission", () => { + const report = parse(` + + com.example + demo-parent + 1.0.0 + + + demo + + + com.example + declared + 1.0.0 + \${dep.optional} + + + com.example + omitted + 1.0.0 + + +`); + expect(report.parent).toMatchObject({ + relative_path: null, + relative_path_declared: true, + }); + expect(report.dependencies).toEqual([ + expect.objectContaining({ + artifact_id: "declared", + optional: null, + optional_spelling: "${dep.optional}", + }), + expect.objectContaining({ + artifact_id: "omitted", + optional: null, + optional_spelling: null, + }), + ]); + expect(report.unresolved).toContainEqual({ + kind: "property", + reference: "${dep.optional}", + field: "optional", + owner: "dependency", + index: 0, + }); + + const omitted = parse(` + + com.example + demo-parent + 1.0.0 + + demo +`); + expect(omitted.parent).toMatchObject({ + relative_path: null, + relative_path_declared: false, + }); +}); + +it("records unread profiles without activating them", () => { + const report = parse(` + + demo + + + extra + + + com.example + hidden + + + + + +`); + expect(report.dependencies).toEqual([]); + expect(report.limitations.join(" ")).toMatch(/profiles are present/u); +}); + +it("refuses malformed XML as invalid format", () => { + expectFailure("demo", "malformed"); +}); + +it("refuses a document type declaration", () => { + expectFailure( + `demo`, + "unsupported", + ); +}); + +it("refuses XML that is not a Maven project", () => { + expectFailure( + "demo", + "unsupported", + ); +}); + +it("refuses a POM with two top-level dependencies blocks", () => { + expectFailure( + ` + demo + + + com.example + first + 1.0.0 + + + + + com.example + second + 2.0.0 + + +`, + "malformed", + ); +}); + +it("refuses a POM with two dependencies blocks inside dependencyManagement", () => { + expectFailure( + ` + demo + + + + com.example + first + 1.0.0 + + + + + com.example + second + 2.0.0 + + + +`, + "malformed", + ); +}); + +it("refuses a POM dependency with two version children", () => { + expectFailure( + ` + demo + + + com.example + lib + 1.0.0 + 2.0.0 + + +`, + "malformed", + ); +}); + +it("refuses malformed Gradle JSON", () => { + expectFailure("{", "malformed"); +}); + +it("keeps malformed Gradle JSON source out of the failure message", () => { + const bytes = Buffer.from('{\n "url": //user:secret@repo.example/x}', "utf8"); + let failure: unknown; + try { + parseMavenGradleMetadata(bytes, { + path: "/artifacts/demo.module", + sha256: createHash("sha256").update(bytes).digest("hex"), + bytes: bytes.length, + }); + } catch (cause) { + failure = cause; + } + expect(failure).toBeInstanceOf(ParseFailureError); + expect(failure).toMatchObject({ failure: { kind: "malformed" } }); + const { message } = failure as ParseFailureError; + expect(message).not.toContain("user:secret"); + expect(message).not.toContain("repo.example"); + expect(message).not.toContain('"url"'); +}); + +it("refuses unreadable Gradle version and available-at values", () => { + const module = (variant: Record) => + JSON.stringify({ + formatVersion: "1.1", + component: { group: "com.example", module: "demo", version: "1.0.0" }, + variants: [{ name: "runtime", ...variant }], + }); + const dependency = (version: unknown) => + module({ + dependencies: [{ group: "com.example", module: "lib", version }], + }); + expectFailure(dependency(42), "malformed"); + expectFailure(dependency(null), "malformed"); + expectFailure(dependency({ requires: 42 }), "malformed"); + expectFailure(dependency({ strictly: ["1.0"] }), "malformed"); + expectFailure(module({ "available-at": "demo-jvm" }), "malformed"); + expectFailure(module({ "available-at": [] }), "malformed"); +}); + +it("refuses Gradle metadata with a repeated field instead of keeping the last", () => { + const source = `{"formatVersion":"1.1","component":{"group":"com.example","module":"demo","version":"1.0.0"},"variants":[{"name":"runtime","dependencies":[{"group":"com.example","module":"lib","version":{"requires":"1.0"}}],"dependencies":[]}]}`; + expectFailure(source, "malformed"); + const root = `{"formatVersion":"1.1","formatVersion":"1.1","component":{"group":"com.example","module":"demo","version":"1.0.0"},"variants":[]}`; + expectFailure(root, "malformed"); +}); + +it("keeps a repeated Gradle field name out of the failure message", () => { + const source = `{"formatVersion":"1.1","https://user:secret@repo.example/x":1,"https://user:secret@repo.example/x":2,"component":{"group":"com.example","module":"demo","version":"1.0.0"},"variants":[]}`; + const bytes = Buffer.from(source, "utf8"); + let failure: unknown; + try { + parseMavenGradleMetadata(bytes, { + path: "/artifacts/demo.module", + sha256: createHash("sha256").update(bytes).digest("hex"), + bytes: bytes.length, + }); + } catch (cause) { + failure = cause; + } + expect(failure).toBeInstanceOf(ParseFailureError); + expect(failure).toMatchObject({ failure: { kind: "malformed" } }); + const { message } = failure as ParseFailureError; + expect(message).not.toContain("user:secret"); + expect(message).not.toContain("repo.example"); +}); + +it("refuses JSON that is not Gradle module metadata", () => { + expectFailure('{"name":"demo"}', "unsupported"); +}); + +it("refuses empty and non-metadata files", () => { + expectFailure("", "malformed"); + expectFailure("not xml or json", "unsupported"); +}); + +it("keeps coverage examined_bytes equal to the artifact length", () => { + const report: MavenGradleMetadata = parse(mavenPomFixture); + expect(report.coverage.examined_bytes).toBe(report.artifact.bytes); +}); + +// A 1,000-character variant name on 5,000 dependency rows repeats 5,000,000 +// characters, past the fixed allowance, from about 300 KB of input. +const repeatedVariantModule = () => + JSON.stringify({ + formatVersion: "1.1", + component: { group: "com.example", module: "demo", version: "1.0.0" }, + variants: [ + { + name: "v".repeat(1000), + dependencies: Array.from({ length: 5000 }, (_, index) => ({ + group: "com.example", + module: `lib${String(index)}`, + version: { requires: "1.0" }, + })), + }, + ], + }); + +it("refuses Gradle metadata whose rows would repeat variant names past the report allowance", () => { + const bytes = Buffer.from(repeatedVariantModule(), "utf8"); + expect(() => + parseMavenGradleMetadata(bytes, { + path: "/artifacts/demo.module", + sha256: createHash("sha256").update(bytes).digest("hex"), + bytes: bytes.length, + }), + ).toThrow(ParseFailureError); +}); + +it("reports the repeated variant-name refusal as a fixed report allowance", async () => { + const root = await createTestTempDirectory("rea-gradle-report-"); + const path = join(root, "demo.module"); + await writeFile(path, repeatedVariantModule()); + const provider = new MavenGradleMetadataProvider(); + try { + const result = await provider.inspect({ + path, + max_file_bytes: 1024 * 1024, + }); + expect(result.ok).toBe(false); + if (result.ok) return; + expect(projectAnalysisError(result.error)).toMatchObject({ + code: "resource_constraint", + retryable: false, + remediation: { + action: expect.stringContaining("fixed report allowance"), + }, + }); + } finally { + await provider.close(); + } +}); + +it("reads POM values written as CDATA and as mixed text and CDATA", () => { + const report = parse(` + 4.0.0 + + demo + 1.3 + +`); + expect(report.coordinates).toMatchObject({ + group_id: "com.example", + version: "1.2.3", + }); + expect(report.properties).toContainEqual({ + name: "revision", + value: "1.2.3", + value_credentials_redacted: false, + }); +}); + +it.for([ + ``, + `demo`, +])("refuses a non-Maven project document %s as unsupported", (source) => { + expectFailure(source, "unsupported"); +}); + +const gradleModule = (variant: string) => + `{"formatVersion":"1.1","component":{"group":"g","module":"m","version":"1"},"variants":[${variant}]}`; + +it.for([ + gradleModule(`{"name":"v","dependencies":{"group":"a"}}`), + gradleModule(`{"name":"v","dependencyConstraints":"none"}`), + gradleModule(`{"name":"v","dependencies":[null]}`), + gradleModule(`null`), + `{"formatVersion":"1.1","component":{"group":"g","module":"m"},"variants":{}}`, + gradleModule( + `{"name":"v","dependencies":[{"group":"a","module":"b","version":{"requires":"1","rejects":"2"}}]}`, + ), + gradleModule( + `{"name":"v","dependencies":[{"group":"a","module":"b","version":{"requires":"1","rejects":[2]}}]}`, + ), + gradleModule( + `{"name":"v","dependencies":[{"group":"a","module":"b","excludes":{"group":"x"}}]}`, + ), + gradleModule( + `{"name":"v","dependencies":[{"group":"a","module":"b","excludes":["x"]}]}`, + ), +])( + "refuses Gradle metadata with an unreadable present collection %s", + (source) => { + expectFailure(source, "malformed"); + }, +); + +it("reads Gradle version rejects and dependency exclusions", () => { + const report = parse( + gradleModule( + `{"name":"v","dependencies":[{"group":"a","module":"b","version":{"requires":"1","rejects":["2"]},"excludes":[{"group":"x","module":"y"}]}]}`, + ), + ); + expect(report.dependencies).toEqual([ + expect.objectContaining({ + exclusions: [{ group_id: "x", artifact_id: "y" }], + gradle_version: expect.objectContaining({ rejects: ["2"] }), + }), + ]); +}); + +it.for([ + [ + "Gradle", + gradleModule( + `{"name":"v","dependencies":[${Array(65_537).fill("{}").join(",")}]}`, + ), + ], + [ + "POM", + `demo${"".repeat(65_537)}`, + ], +] as const)( + "refuses %s rows past the report allowance before building them", + ([, source]) => { + const bytes = Buffer.from(source, "utf8"); + let failure: unknown; + try { + parseMavenGradleMetadata(bytes, { + path: "/artifacts/selected", + sha256: createHash("sha256").update(bytes).digest("hex"), + bytes: bytes.length, + }); + } catch (cause) { + failure = cause; + } + expect(failure).toBeInstanceOf(ParseFailureError); + expect(failure).toMatchObject({ + failure: { + kind: "limit", + limit: { name: "dependency_rows", maximum: 65_536, required: 65_537 }, + }, + }); + }, +); + +it.for([ + [ + "Gradle variants", + `{"formatVersion":"1.1","variants":[${Array(4_097).fill("{}").join(",")}]}`, + { allowance: "variants", limit: 4_096, required: 4_097 }, + ], + [ + "Gradle exclusions", + gradleModule( + `{"name":"v","dependencies":[{"group":"a","module":"b","excludes":[${Array(65_537).fill("{}").join(",")}]}]}`, + ), + { allowance: "exclusions", limit: 65_536, required: 65_537 }, + ], + [ + "POM exclusions", + `demo${"".repeat(65_537)}`, + { allowance: "exclusions", limit: 65_536, required: 65_537 }, + ], +] as const)( + "refuses %s past the report allowance before building them", + ([, source, expected]) => { + const bytes = Buffer.from(source, "utf8"); + let failure: unknown; + try { + parseMavenGradleMetadata(bytes, { + path: "/artifacts/selected", + sha256: createHash("sha256").update(bytes).digest("hex"), + bytes: bytes.length, + }); + } catch (cause) { + failure = cause; + } + expect(failure).toBeInstanceOf(ParseFailureError); + expect(failure).toMatchObject({ + failure: { + kind: "limit", + limit: { + name: expected.allowance, + maximum: expected.limit, + required: expected.required, + }, + }, + }); + }, +); + +it("reports the variant refusal as a fixed report allowance", async () => { + const root = await createTestTempDirectory("rea-gradle-variants-"); + const path = join(root, "demo.module"); + await writeFile( + path, + `{"formatVersion":"1.1","variants":[${Array(4_097).fill("{}").join(",")}]}`, + ); + const provider = new MavenGradleMetadataProvider(); + try { + const result = await provider.inspect({ + path, + max_file_bytes: 1024 * 1024, + }); + expect(result.ok).toBe(false); + if (result.ok) return; + expect(projectAnalysisError(result.error)).toMatchObject({ + code: "resource_constraint", + retryable: false, + remediation: { + action: expect.stringContaining("4096-variant allowance"), + }, + }); + } finally { + await provider.close(); + } +}); + +it("refuses a POM past the XML node allowance before building its tree", () => { + const source = `demo${"

".repeat(1_048_577)}`; + const bytes = Buffer.from(source, "utf8"); + let failure: unknown; + try { + parseMavenGradleMetadata(bytes, { + path: "/artifacts/selected", + sha256: createHash("sha256").update(bytes).digest("hex"), + bytes: bytes.length, + }); + } catch (cause) { + failure = cause; + } + expect(failure).toBeInstanceOf(ParseFailureError); + expect(failure).toMatchObject({ + failure: { + kind: "limit", + limit: { name: "xml_nodes", maximum: 1_048_576, required: 1_048_577 }, + }, + }); +}); diff --git a/src/java/MavenGradleMetadataParser.ts b/src/java/MavenGradleMetadataParser.ts new file mode 100644 index 0000000000..c054819c35 --- /dev/null +++ b/src/java/MavenGradleMetadataParser.ts @@ -0,0 +1,661 @@ +import { MavenGradleUnresolvedCollector } from "./MavenGradleUnresolvedCollector.js"; +import { Budget } from "../domain/budget.js"; +import { decodeStrictUtf8 } from "../domain/strictUtf8.js"; +import { parseJsonWithDuplicatePolicy } from "../domain/jsonDuplicateMember.js"; +import { isRecord } from "../kernel/isRecord.js"; +import { malformedInput, unsupportedInput } from "../domain/parseFailure.js"; +import type { Element, Node } from "@xmldom/xmldom"; + +import { + countXmlNodes, + parseXmlDocument, + opensLikeXml, +} from "../domain/xmlDocument.js"; +import { + MAVEN_GRADLE_METADATA_DEPENDENCY_ROWS, + MAVEN_GRADLE_METADATA_EXCLUSIONS, + MAVEN_GRADLE_METADATA_REPEATED_VARIANT_NAME_CHARS, + MAVEN_GRADLE_METADATA_VARIANTS, + MAVEN_GRADLE_METADATA_XML_NODES, + requestedVersionKind, + type MavenGradleDependency, + type MavenGradleMetadata, +} from "../domain/java/mavenGradleMetadata.js"; +import { redactRecordedTransportUrl } from "../domain/recordedTransportUrl.js"; +import { + MAVEN_GRADLE_METADATA_FORMAT, + metadataReportLimit, + type MavenGradleReportAllowance, +} from "./MavenGradleMetadata.errors.js"; + +const BASE_LIMITATIONS = [ + "This workflow reads a Maven POM or Gradle module-metadata document without running Maven or Gradle, resolving a dependency tree, or contacting a repository.", + "Requested versions, ranges, and property spellings are recorded as written; interpolation and parent/BOM inheritance are not performed.", +] as const; + +const isElement = (node: Node | null): node is Element => + node !== null && node.nodeType === 1; + +const childElements = (element: Element): Element[] => { + const children: Element[] = []; + for ( + let child = element.firstChild; + child !== null; + child = child.nextSibling + ) + if (isElement(child)) children.push(child); + return children; +}; + +const childrenNamed = (element: Element, local: string): Element[] => + childElements(element).filter((child) => child.localName === local); + +const soleNamed = (element: Element, local: string): Element | undefined => { + const matches = childrenNamed(element, local); + if (matches.length <= 1) return matches[0]; + throw malformedInput( + MAVEN_GRADLE_METADATA_FORMAT, + `Maven POM declares <${local}> more than once in one <${element.localName}>.`, + ); +}; + +const MAVEN_POM_NAMESPACE = "http://maven.apache.org/POM/4.0.0"; + +/** + * A Maven POM root: `project` in the POM namespace, or a namespace-free + * `project` that declares `modelVersion` or `artifactId`. Ant and other + * `project` vocabularies declare neither and are not POMs. + */ +const isMavenProjectRoot = (root: Node | null): root is Element => { + if (!isElement(root) || root.localName !== "project") return false; + if (root.namespaceURI === MAVEN_POM_NAMESPACE) return true; + return ( + (root.namespaceURI === null || root.namespaceURI === "") && + childElements(root).some( + (child) => + child.localName === "modelVersion" || child.localName === "artifactId", + ) + ); +}; + +/** Refuse a report whose expanded collection would outgrow its fixed allowance. */ +const admit = ( + allowance: MavenGradleReportAllowance, + limit: number, + required: number, +): void => { + if (required > limit) throw metadataReportLimit(allowance, limit, required); +}; + +const nonempty = (value: string | null | undefined): string | null => { + if (value === null || value === undefined) return null; + const trimmed = value.trim(); + return trimmed === "" ? null : trimmed; +}; + +const elementText = (element: Element | undefined): string | null => { + if (element === undefined) return null; + const parts: string[] = []; + for ( + let child = element.firstChild; + child !== null; + child = child.nextSibling + ) + // Text (3) and CDATA section (4) nodes both carry character data. + if (child.nodeType === 3 || child.nodeType === 4) + parts.push(child.nodeValue ?? ""); + return nonempty(parts.join("")); +}; + +const childText = (element: Element, local: string): string | null => + elementText(soleNamed(element, local)); + +const textOf = (value: unknown): string | null => + typeof value === "string" ? nonempty(value) : null; + +const boolOf = (value: string | null): boolean | null => { + if (value === null) return null; + const folded = value.toLowerCase(); + if (folded === "true") return true; + if (folded === "false") return false; + return null; +}; + +const emptyGradleVersion = { + requires: null, + prefers: null, + strictly: null, + rejects: [] as string[], +}; + +/** An absent collection is empty; a present one must be a JSON array. */ +const gradleArray = (value: unknown, field: string): readonly unknown[] => { + if (value === undefined) return []; + if (Array.isArray(value)) return value; + throw malformedInput( + MAVEN_GRADLE_METADATA_FORMAT, + `Gradle module metadata ${field} is present but is not a JSON array.`, + ); +}; + +const gradleObjects = ( + value: unknown, + field: string, +): readonly Record[] => + gradleArray(value, field).map((entry, index) => { + if (isRecord(entry)) return entry; + throw malformedInput( + MAVEN_GRADLE_METADATA_FORMAT, + `Gradle module metadata ${field}[${String(index)}] is not a JSON object.`, + ); + }); + +const gradleVersionOf = ( + value: unknown, +): MavenGradleDependency["gradle_version"] => { + if (typeof value === "string") { + const requires = nonempty(value); + return requires === null + ? { ...emptyGradleVersion } + : { ...emptyGradleVersion, requires }; + } + if (value === undefined) return { ...emptyGradleVersion }; + if (!isRecord(value)) + throw malformedInput( + MAVEN_GRADLE_METADATA_FORMAT, + "Gradle module metadata version is present but is neither a string nor a JSON object.", + ); + const versionText = (field: "requires" | "prefers" | "strictly") => { + const entry = value[field]; + if (entry === undefined || typeof entry === "string") return textOf(entry); + throw malformedInput( + MAVEN_GRADLE_METADATA_FORMAT, + `Gradle module metadata version.${field} is present but is not a string.`, + ); + }; + const rejects = gradleArray(value.rejects, "version.rejects").map( + (entry, index) => { + const text = textOf(entry); + if (text !== null) return text; + throw malformedInput( + MAVEN_GRADLE_METADATA_FORMAT, + `Gradle module metadata version.rejects[${String(index)}] is not a non-empty string.`, + ); + }, + ); + return { + requires: versionText("requires"), + prefers: versionText("prefers"), + strictly: versionText("strictly"), + rejects, + }; +}; + +const requestedFromGradle = ( + version: MavenGradleDependency["gradle_version"], +): string | null => { + if (version === null) return null; + return version.requires ?? version.strictly ?? version.prefers; +}; + +/** The `` elements of one POM dependency row. */ +const mavenExclusionElements = (element: Element): Element[] => { + const container = soleNamed(element, "exclusions"); + return container === undefined ? [] : childrenNamed(container, "exclusion"); +}; + +const parseMavenDependency = ( + element: Element, + origin: "dependencies" | "dependencyManagement", + index: number, + unresolved: MavenGradleUnresolvedCollector, +): MavenGradleDependency => { + const group_id = childText(element, "groupId"); + const artifact_id = childText(element, "artifactId"); + const version = childText(element, "version"); + const type = childText(element, "type"); + const scope = childText(element, "scope"); + const bom_import = type === "pom" && scope === "import"; + const exclusions = mavenExclusionElements(element).map((exclusion) => ({ + group_id: childText(exclusion, "groupId"), + artifact_id: childText(exclusion, "artifactId"), + })); + const owner = + origin === "dependencies" ? "dependency" : "dependency_management"; + unresolved.coordinates( + { group_id, artifact_id, version }, + owner, + index, + false, + ); + const optional_spelling = childText(element, "optional"); + const classifier = childText(element, "classifier"); + unresolved.properties( + [ + ["scope", scope], + ["type", type], + ["classifier", classifier], + ["optional", optional_spelling], + ], + owner, + index, + ); + return { + group_id, + artifact_id, + version, + version_kind: requestedVersionKind(version, "maven-pom"), + gradle_version: null, + scope, + type, + optional: boolOf(optional_spelling), + optional_spelling, + classifier, + exclusions, + origin, + variant: null, + bom_import, + platform: false, + }; +}; + +const parsePom = ( + xml: string, + artifact: { path: string; sha256: string; bytes: number }, +): MavenGradleMetadata => { + const limitations: string[] = [...BASE_LIMITATIONS]; + // Count nodes as a stream first, so the tree is never built past its allowance. + const nodes = countXmlNodes(xml, MAVEN_GRADLE_METADATA_XML_NODES); + if (nodes > MAVEN_GRADLE_METADATA_XML_NODES) + throw metadataReportLimit( + "xml_nodes", + MAVEN_GRADLE_METADATA_XML_NODES, + nodes, + ); + const parsed = parseXmlDocument(xml, { + doctype: "reject", + lineEndings: "preserve", + }); + if (!parsed.ok) + throw parsed.error.kind === "unsupported" + ? unsupportedInput( + MAVEN_GRADLE_METADATA_FORMAT, + "Maven POM declares a document type, which is unsupported.", + ) + : malformedInput( + MAVEN_GRADLE_METADATA_FORMAT, + "Maven POM is not well-formed XML.", + ); + const root = parsed.value.documentElement; + if (!isMavenProjectRoot(root)) + throw unsupportedInput( + MAVEN_GRADLE_METADATA_FORMAT, + "Selected XML document is not a Maven project POM.", + ); + const unresolved = new MavenGradleUnresolvedCollector(); + const parentElement = soleNamed(root, "parent"); + const parent = + parentElement === undefined + ? null + : { + group_id: childText(parentElement, "groupId"), + artifact_id: childText(parentElement, "artifactId"), + version: childText(parentElement, "version"), + packaging: null, + relative_path: childText(parentElement, "relativePath"), + relative_path_declared: + soleNamed(parentElement, "relativePath") !== undefined, + }; + if (parent !== null) unresolved.coordinates(parent, "parent", null, false); + const coordinates = { + group_id: childText(root, "groupId"), + artifact_id: childText(root, "artifactId"), + version: childText(root, "version"), + packaging: childText(root, "packaging"), + }; + unresolved.coordinates(coordinates, "project", null, parent !== null); + unresolved.properties( + [["packaging", coordinates.packaging]], + "project", + null, + ); + const propertiesElement = soleNamed(root, "properties"); + const properties = + propertiesElement === undefined + ? [] + : childElements(propertiesElement).flatMap((property) => { + const name = nonempty(property.localName); + if (name === null) return []; + // A property may hold a repository URL; its userinfo never leaves the parser. + const { + url: value, + url_credentials_redacted: value_credentials_redacted, + } = redactRecordedTransportUrl(elementText(property)); + return [{ name, value, value_credentials_redacted }]; + }); + const dependencyManagementElement = soleNamed(root, "dependencyManagement"); + const managedContainer = dependencyManagementElement + ? soleNamed(dependencyManagementElement, "dependencies") + : undefined; + const managedElements = + managedContainer === undefined + ? [] + : childrenNamed(managedContainer, "dependency"); + const dependenciesContainer = soleNamed(root, "dependencies"); + const dependencyElements = + dependenciesContainer === undefined + ? [] + : childrenNamed(dependenciesContainer, "dependency"); + admit( + "dependency_rows", + MAVEN_GRADLE_METADATA_DEPENDENCY_ROWS, + managedElements.length + dependencyElements.length, + ); + admit( + "exclusions", + MAVEN_GRADLE_METADATA_EXCLUSIONS, + [...managedElements, ...dependencyElements].reduce( + (count, element) => count + mavenExclusionElements(element).length, + 0, + ), + ); + const dependency_management = managedElements.map((element, index) => + parseMavenDependency(element, "dependencyManagement", index, unresolved), + ); + const dependencies = dependencyElements.map((element, index) => + parseMavenDependency(element, "dependencies", index, unresolved), + ); + if (parent !== null) + limitations.push( + "Parent coordinates are recorded as spelled; the parent POM was not read and inheritance was not applied.", + ); + if (soleNamed(root, "repositories") !== undefined) + limitations.push( + "Declared repositories are recorded as unread; they were not contacted.", + ); + if (soleNamed(root, "profiles") !== undefined) + limitations.push( + "POM profiles are present and were not activated; profile-scoped declarations remain unread.", + ); + if (coordinates.packaging === null) + limitations.push( + "Packaging was not declared; Maven would default to jar, but that default was not applied.", + ); + return { + artifact: { + path: artifact.path, + sha256: artifact.sha256, + bytes: artifact.bytes, + }, + format: "maven-pom", + coordinates, + parent, + properties, + dependencies, + dependency_management, + gradle: null, + unresolved: unresolved.finish(), + coverage: { status: "complete", examined_bytes: artifact.bytes }, + limitations, + }; +}; + +const parseGradleDependency = ( + value: unknown, + origin: "variant-dependencies" | "variant-constraints", + variant: string | null, + platform: boolean, + index: number, + unresolved: MavenGradleUnresolvedCollector, +): MavenGradleDependency => { + if (!isRecord(value)) + throw malformedInput( + MAVEN_GRADLE_METADATA_FORMAT, + `Gradle ${origin === "variant-dependencies" ? "dependency" : "dependency constraint"} ${String(index)} is not a JSON object.`, + ); + const record = value; + const group_id = textOf(record.group); + const artifact_id = textOf(record.module); + const gradle_version = gradleVersionOf(record.version); + const version = requestedFromGradle(gradle_version); + unresolved.coordinates( + { group_id, artifact_id, version }, + "variant", + index, + false, + ); + const excludes = gradleObjects(record.excludes, "excludes"); + return { + group_id, + artifact_id, + version, + version_kind: requestedVersionKind(version, "gradle-module"), + gradle_version, + scope: null, + type: null, + optional: null, + optional_spelling: null, + classifier: null, + exclusions: excludes.map((entry) => ({ + group_id: textOf(entry.group), + artifact_id: textOf(entry.module), + })), + origin, + variant, + bom_import: false, + platform, + }; +}; + +const parseGradle = ( + source: string, + artifact: { path: string; sha256: string; bytes: number }, +): MavenGradleMetadata => { + const json = parseJsonWithDuplicatePolicy(source, "reject"); + if (!json.ok) { + if (json.duplicate !== undefined) + throw malformedInput( + MAVEN_GRADLE_METADATA_FORMAT, + `Gradle module metadata declares a field more than once in one object (offset ${String(json.duplicate.offset)}).`, + ); + // Engine diagnostics can quote credential-bearing source; keep the public reason generic. + throw malformedInput( + MAVEN_GRADLE_METADATA_FORMAT, + "Gradle module metadata is not well-formed JSON.", + { cause: json.cause }, + ); + } + const parsed = json.value; + if (!isRecord(parsed)) + throw unsupportedInput( + MAVEN_GRADLE_METADATA_FORMAT, + "Gradle module metadata root must be a JSON object.", + ); + const format_version = textOf(parsed.formatVersion); + const component = isRecord(parsed.component) ? parsed.component : null; + const variantsValue = parsed.variants; + if ( + format_version === null || + (component === null && !Array.isArray(variantsValue)) + ) + throw unsupportedInput( + MAVEN_GRADLE_METADATA_FORMAT, + "Selected JSON document is not Gradle module metadata (missing formatVersion and component or variants).", + ); + const limitations: string[] = [ + ...BASE_LIMITATIONS, + "Gradle variant attributes other than category and usage are not decoded.", + "available-at coordinates are recorded as spelled; the named module file was not fetched.", + ]; + const unresolved = new MavenGradleUnresolvedCollector(); + const coordinates = { + group_id: component === null ? null : textOf(component.group), + artifact_id: component === null ? null : textOf(component.module), + version: component === null ? null : textOf(component.version), + packaging: null, + }; + unresolved.coordinates(coordinates, "project", null, false); + const createdBy = isRecord(parsed.createdBy) ? parsed.createdBy : null; + const createdGradle = + createdBy !== null && isRecord(createdBy.gradle) ? createdBy.gradle : null; + // Count each expanded collection before any report record is built. + admit( + "variants", + MAVEN_GRADLE_METADATA_VARIANTS, + gradleArray(variantsValue, "variants").length, + ); + const variants = gradleObjects(variantsValue, "variants"); + const rowLists = variants.flatMap((variant) => [ + gradleArray(variant.dependencies, "dependencies"), + gradleArray(variant.dependencyConstraints, "dependencyConstraints"), + ]); + admit( + "dependency_rows", + MAVEN_GRADLE_METADATA_DEPENDENCY_ROWS, + rowLists.reduce((count, rows) => count + rows.length, 0), + ); + let exclusions = 0; + for (const rows of rowLists) + for (const row of rows) + if (isRecord(row)) + exclusions += gradleArray(row.excludes, "excludes").length; + admit("exclusions", MAVEN_GRADLE_METADATA_EXCLUSIONS, exclusions); + const dependencies: MavenGradleDependency[] = []; + const dependency_management: MavenGradleDependency[] = []; + const gradleVariants: NonNullable["variants"] = + []; + let nextIndex = 0; + const repeatedVariantNames = new Budget( + MAVEN_GRADLE_METADATA_REPEATED_VARIANT_NAME_CHARS, + ); + for (const variant of variants) { + const name = textOf(variant.name); + const attributes = isRecord(variant.attributes) ? variant.attributes : {}; + const category = textOf(attributes["org.gradle.category"]); + const usage = textOf(attributes["org.gradle.usage"]); + const platform = + category === "platform" || category === "enforced-platform"; + const availableAt: unknown = variant["available-at"]; + if (availableAt !== undefined && !isRecord(availableAt)) + throw malformedInput( + MAVEN_GRADLE_METADATA_FORMAT, + "Gradle module metadata available-at is present but is not a JSON object.", + ); + const available = availableAt === undefined ? null : availableAt; + const variantDependencies = gradleArray( + variant.dependencies, + "dependencies", + ); + const constraints = gradleArray( + variant.dependencyConstraints, + "dependencyConstraints", + ); + // Every row repeats its variant's name; admit that expansion before + // building rows, so a long name times many rows cannot outgrow the input. + const repeated = + (name?.length ?? 0) * (variantDependencies.length + constraints.length); + repeatedVariantNames.charge(repeated, () => + metadataReportLimit( + "repeated_variant_name_chars", + repeatedVariantNames.maximum, + repeatedVariantNames.used + repeated, + ), + ); + for (const dependency of variantDependencies) + dependencies.push( + parseGradleDependency( + dependency, + "variant-dependencies", + name, + platform, + nextIndex++, + unresolved, + ), + ); + for (const constraint of constraints) + dependency_management.push( + parseGradleDependency( + constraint, + "variant-constraints", + name, + platform, + nextIndex++, + unresolved, + ), + ); + gradleVariants.push({ + name, + category, + usage, + available_at: + available === null + ? null + : { + group_id: textOf(available.group), + artifact_id: textOf(available.module), + version: textOf(available.version), + ...redactRecordedTransportUrl(textOf(available.url)), + }, + dependency_count: variantDependencies.length, + constraint_count: constraints.length, + }); + } + return { + artifact: { + path: artifact.path, + sha256: artifact.sha256, + bytes: artifact.bytes, + }, + format: "gradle-module", + coordinates, + parent: null, + properties: [], + dependencies, + dependency_management, + gradle: { + format_version, + created_by_gradle: + createdGradle === null ? null : textOf(createdGradle.version), + variants: gradleVariants, + }, + unresolved: unresolved.finish(), + coverage: { status: "complete", examined_bytes: artifact.bytes }, + limitations, + }; +}; + +/** Decode one bounded Maven POM or Gradle module-metadata document without resolution. */ +export const parseMavenGradleMetadata = ( + bytes: Uint8Array, + artifact: { path: string; sha256: string; bytes: number }, +): MavenGradleMetadata => { + if (bytes.length !== artifact.bytes) + throw malformedInput( + MAVEN_GRADLE_METADATA_FORMAT, + "Selected artifact length disagrees with the retained bytes.", + ); + if (bytes.length === 0) + throw malformedInput( + MAVEN_GRADLE_METADATA_FORMAT, + "Selected file is empty.", + ); + let source: string; + try { + // ignoreBOM: true kept a leading U+FEFF; "preserve" is that same policy. + source = decodeStrictUtf8(bytes, "preserve"); + } catch { + throw malformedInput( + MAVEN_GRADLE_METADATA_FORMAT, + "Selected file is not valid UTF-8.", + ); + } + const trimmed = source.trimStart(); + if (trimmed.startsWith("{") || trimmed.startsWith("[")) + return parseGradle(source, artifact); + if (opensLikeXml(trimmed) || trimmed.startsWith("<")) + return parsePom(source, artifact); + throw unsupportedInput( + MAVEN_GRADLE_METADATA_FORMAT, + "Selected file is not a Maven POM or Gradle module-metadata document.", + ); +}; diff --git a/src/java/MavenGradleMetadataProvider.ts b/src/java/MavenGradleMetadataProvider.ts new file mode 100644 index 0000000000..3584592183 --- /dev/null +++ b/src/java/MavenGradleMetadataProvider.ts @@ -0,0 +1,213 @@ +import { + ArtifactReaderFailure, + ArtifactResourceScope, + artifactFilePrimaryFacts, + type ArtifactFilePrimaryFacts, + projectArtifactCloseFailure, + projectOwnedArtifactIdentityFailure, + projectSelectedArtifactFileFailure, + projectStableArtifactFailure, + readStableArtifact, + projectOwnedArtifactInputFailure, + translateArtifactFailure, + type StableArtifactSnapshot, +} from "../resources/index.js"; +import { + isParseLimit, + parseLimitConstraint, + parseFailureAnalysisError, +} from "../domain/parseFailureAnalysisError.js"; +import { decodeLimit } from "../domain/parseFailure.js"; +import { errorMessage } from "../kernel/errorMessage.js"; +import { ArtifactOperationError } from "../domain/artifactOperationError.js"; +import { + MAX_INSPECT_MAVEN_GRADLE_METADATA_FILE_BYTES, + type InspectMavenGradleMetadataInput, +} from "../domain/java/mavenGradleMetadata.js"; +import { err, ok } from "../domain/result.js"; +import { + MAVEN_GRADLE_METADATA_FORMAT, + type MavenGradleReportAllowance, +} from "./MavenGradleMetadata.errors.js"; +import { fixedAllowanceOptions } from "../domain/fixedAllowanceRemediation.js"; +import { MAVEN_GRADLE_METADATA_PROVIDER_IDENTITY } from "./MavenGradleMetadataProviderIdentity.js"; +import { parseMavenGradleMetadata } from "./MavenGradleMetadataParser.js"; + +const OPERATION = "inspect_maven_gradle_metadata"; + +/** Portable parser over one bounded, identity-checked POM or module-metadata file. */ +/** + * Satisfies the application's MavenGradleMetadataPort structurally; + * composition checks the fit, so this provider does not import the + * application layer. + */ +export class MavenGradleMetadataProvider { + readonly identity = MAVEN_GRADLE_METADATA_PROVIDER_IDENTITY; + readonly #resources = new ArtifactResourceScope(); + + async close(): Promise { + try { + await this.#resources.close(); + } catch (cause: unknown) { + throw projectArtifactCloseFailure( + cause, + MAVEN_GRADLE_METADATA_PROVIDER_IDENTITY.id, + OPERATION, + ); + } + } + + async inspect( + input: InspectMavenGradleMetadataInput, + options?: { readonly signal?: AbortSignal }, + ) { + let snapshot: StableArtifactSnapshot | undefined; + try { + return await this.#resources.run(async () => { + snapshot = await readStableArtifact( + input.path, + input.max_file_bytes, + options?.signal, + undefined, + this.#resources, + ); + return ok( + parseMavenGradleMetadata(snapshot.bytes, { + path: input.path, + sha256: snapshot.sha256, + bytes: snapshot.bytes.length, + }), + ); + }); + } catch (cause) { + return err(mavenGradleMetadataFailure(cause, input, snapshot)); + } + } +} + +const inputBudgetRemediation = ( + input: InspectMavenGradleMetadataInput, +): string => + input.max_file_bytes >= MAX_INSPECT_MAVEN_GRADLE_METADATA_FILE_BYTES + ? `The file exceeds the ${String(MAX_INSPECT_MAVEN_GRADLE_METADATA_FILE_BYTES)}-byte input ceiling this operation accepts; select a smaller artifact.` + : `Raise max_file_bytes above ${String(input.max_file_bytes)} bytes, up to ${String(MAX_INSPECT_MAVEN_GRADLE_METADATA_FILE_BYTES)}, or select a smaller artifact; this is the caller-selected input read budget.`; + +/** The subject a fixed-allowance remediation names for each report allowance. */ +const REPORT_ALLOWANCE_SUBJECTS: Readonly< + Record string> +> = { + dependency_rows: (limit) => + `The ${String(limit)}-row allowance for dependency and constraint rows`, + variants: (limit) => + `The ${String(limit)}-variant allowance for Gradle module variants`, + exclusions: (limit) => + `The ${String(limit)}-exclusion allowance for dependency exclusions`, + unresolved_records: (limit) => + `The ${String(limit)}-record allowance for unresolved references and coordinates`, + xml_nodes: (limit) => + `The ${String(limit)}-node allowance for a Maven POM document tree`, + repeated_variant_name_chars: (limit) => + `The ${String(limit)}-character allowance for variant names repeated across Gradle dependency rows`, +}; + +const mavenGradleMetadataFailurePrimary = ( + facts: ArtifactFilePrimaryFacts, + input: InspectMavenGradleMetadataInput, +) => { + const { cause, origin } = facts; + if (isParseLimit(cause, MAVEN_GRADLE_METADATA_FORMAT)) { + const { name, maximum } = cause.failure.limit; + return parseLimitConstraint(OPERATION, "memory", cause, { + path: input.path, + ...fixedAllowanceOptions( + Object.entries(REPORT_ALLOWANCE_SUBJECTS).find( + ([key]) => key === name, + )?.[1](maximum) ?? name, + name === "xml_nodes" ? "parser" : "report", + { + limit: maximum, + unit: + name === "repeated_variant_name_chars" + ? "UTF-16 code units" + : name === "unresolved_records" + ? "records" + : name === "dependency_rows" + ? "rows" + : name === "xml_nodes" + ? "nodes" + : name, + }, + ), + }); + } + const identityFailure = projectOwnedArtifactIdentityFailure( + facts, + OPERATION, + input.path, + ); + if (identityFailure !== undefined) return identityFailure; + const formatFailure = parseFailureAnalysisError(OPERATION, input.path, cause); + if (formatFailure !== undefined) return formatFailure; + const inputFailure = projectOwnedArtifactInputFailure( + facts, + OPERATION, + input.path, + ); + if (inputFailure !== undefined) return inputFailure; + if ( + origin === "owned-or-classified" && + cause instanceof ArtifactReaderFailure + ) { + if (cause.reason === "limit" && cause.boundary === "file-size") + return parseLimitConstraint( + OPERATION, + "file-size", + decodeLimit( + MAVEN_GRADLE_METADATA_FORMAT, + cause.message, + { name: "max_file_bytes", maximum: input.max_file_bytes }, + { cause }, + ), + { + retryable: false, + remediationAction: inputBudgetRemediation(input), + }, + ); + return translateArtifactFailure(OPERATION, cause); + } + const fileFailure = projectSelectedArtifactFileFailure( + cause, + OPERATION, + input.path, + "Maven POM or Gradle module metadata", + ); + if (fileFailure !== undefined) return fileFailure; + return new ArtifactOperationError( + OPERATION, + origin === "owned-or-classified" && cause instanceof ArtifactReaderFailure + ? cause.reason + : "io", + undefined, + errorMessage(cause), + { cause }, + ); +}; + +const mavenGradleMetadataFailure = ( + cause: unknown, + input: InspectMavenGradleMetadataInput, + snapshot?: StableArtifactSnapshot, +) => { + const primary = mavenGradleMetadataFailurePrimary( + artifactFilePrimaryFacts(cause), + input, + ); + return projectStableArtifactFailure( + cause, + primary, + input.path, + MAVEN_GRADLE_METADATA_PROVIDER_IDENTITY.id, + OPERATION, + snapshot, + ); +}; diff --git a/src/java/MavenGradleMetadataProviderIdentity.ts b/src/java/MavenGradleMetadataProviderIdentity.ts new file mode 100644 index 0000000000..c7edb89c56 --- /dev/null +++ b/src/java/MavenGradleMetadataProviderIdentity.ts @@ -0,0 +1,6 @@ +/** Bundled reader identity; coordinates and requested versions are separate observed facts. */ +export const MAVEN_GRADLE_METADATA_PROVIDER_IDENTITY = { + id: "rea-maven-gradle-metadata", + name: "REA Maven POM and Gradle module metadata reader", + version: "1", +} as const; diff --git a/src/java/MavenGradleUnresolvedCollector.test.ts b/src/java/MavenGradleUnresolvedCollector.test.ts new file mode 100644 index 0000000000..5f64974a4f --- /dev/null +++ b/src/java/MavenGradleUnresolvedCollector.test.ts @@ -0,0 +1,81 @@ +import { expect, it } from "vitest"; +import { ParseFailureError } from "../domain/parseFailure.js"; +import { MavenGradleUnresolvedCollector } from "./MavenGradleUnresolvedCollector.js"; + +it("admits distinct references before retaining them and stops at a small shared quota", () => { + const collector = new MavenGradleUnresolvedCollector(2); + let failure: unknown; + try { + collector.properties( + [["version", "${first}${first}${second}${third}${fourth}"]], + "project", + null, + ); + } catch (cause) { + failure = cause; + } + expect(failure).toBeInstanceOf(ParseFailureError); + expect(failure).toMatchObject({ + failure: { + kind: "limit", + limit: { name: "unresolved_records", maximum: 2, required: 3 }, + }, + }); + expect(collector.finish()).toEqual([ + { + kind: "property", + reference: "${first}", + field: "version", + owner: "project", + index: null, + }, + { + kind: "property", + reference: "${second}", + field: "version", + owner: "project", + index: null, + }, + ]); +}); + +it("deduplicates within each field while preserving separate field and row facts", () => { + const collector = new MavenGradleUnresolvedCollector(3); + collector.properties( + [ + ["version", "${same}${same}"], + ["scope", "${same}"], + ], + "dependency", + 0, + ); + collector.properties([["version", "${same}"]], "dependency", 1); + expect( + collector + .finish() + .map(({ field, index, reference }) => ({ field, index, reference })), + ).toEqual([ + { field: "version", index: 0, reference: "${same}" }, + { field: "scope", index: 0, reference: "${same}" }, + { field: "version", index: 1, reference: "${same}" }, + ]); +}); + +it("shares admission between coordinate gaps and references across calls", () => { + const collector = new MavenGradleUnresolvedCollector(2); + collector.coordinates( + { group_id: null, artifact_id: null, version: "1" }, + "project", + null, + false, + ); + expect(() => + collector.properties([["scope", "${scope}"]], "dependency", 0), + ).toThrow(ParseFailureError); + expect( + collector.finish().map(({ kind, reference }) => ({ kind, reference })), + ).toEqual([ + { kind: "missing-coordinate", reference: "project.group_id" }, + { kind: "missing-coordinate", reference: "project.artifact_id" }, + ]); +}); diff --git a/src/java/MavenGradleUnresolvedCollector.ts b/src/java/MavenGradleUnresolvedCollector.ts new file mode 100644 index 0000000000..e0302e3f69 --- /dev/null +++ b/src/java/MavenGradleUnresolvedCollector.ts @@ -0,0 +1,91 @@ +import { Budget } from "../domain/budget.js"; +import { + MAVEN_GRADLE_METADATA_UNRESOLVED_RECORDS, + mavenPropertyOccurrences, + type MavenGradleUnresolved, +} from "../domain/java/mavenGradleMetadata.js"; +import { metadataReportLimit } from "./MavenGradleMetadata.errors.js"; + +type FieldValue = readonly [MavenGradleUnresolved["field"], string | null]; + +/** One report-wide admission owner for references and missing-coordinate facts. */ +export class MavenGradleUnresolvedCollector { + readonly #records: MavenGradleUnresolved[] = []; + readonly #budget: Budget; + + constructor(maximum = MAVEN_GRADLE_METADATA_UNRESOLVED_RECORDS) { + this.#budget = new Budget(maximum); + } + + #reserve(): void { + this.#budget.charge(1, () => + metadataReportLimit( + "unresolved_records", + this.#budget.maximum, + this.#budget.used + 1, + ), + ); + } + + properties( + fields: readonly FieldValue[], + owner: MavenGradleUnresolved["owner"], + index: number | null, + ): void { + for (const [field, value] of fields) { + const seen = new Set(); + for (const reference of mavenPropertyOccurrences(value)) { + if (seen.has(reference)) continue; + // Admit before retaining either the distinct reference or its record. + this.#reserve(); + seen.add(reference); + this.#records.push({ + kind: "property", + reference, + field, + owner, + index, + }); + } + } + } + + coordinates( + coordinates: { + readonly group_id: string | null; + readonly artifact_id: string | null; + readonly version: string | null; + }, + owner: MavenGradleUnresolved["owner"], + index: number | null, + parentPresent: boolean, + ): void { + const fields = [ + ["group_id", coordinates.group_id], + ["artifact_id", coordinates.artifact_id], + ["version", coordinates.version], + ] as const; + for (const [field, value] of fields) { + if (value !== null) { + this.properties([[field, value]], owner, index); + continue; + } + // Maven's parent may supply group/version, but never the child's artifactId. + const inherited = + parentPresent && owner === "project" && field !== "artifact_id"; + this.#reserve(); + this.#records.push({ + kind: inherited ? "parent-coordinate" : "missing-coordinate", + reference: inherited ? `parent.${field}` : `${owner}.${field}`, + field, + owner, + index, + }); + } + } + + /** Transfer the bounded records into the completed report. */ + finish(): MavenGradleUnresolved[] { + return this.#records; + } +} diff --git a/src/ports/java/MavenGradleMetadataPort.ts b/src/ports/java/MavenGradleMetadataPort.ts new file mode 100644 index 0000000000..091b3cae21 --- /dev/null +++ b/src/ports/java/MavenGradleMetadataPort.ts @@ -0,0 +1,20 @@ +import type { + ExecutionOptions, + ProviderIdentity, +} from "../AnalysisProvider.js"; +import type { AnalysisError } from "../../domain/analysisErrorBase.js"; +import type { Result } from "../../domain/result.js"; +import type { + InspectMavenGradleMetadataInput, + MavenGradleMetadata, +} from "../../domain/java/mavenGradleMetadata.js"; + +/** Stable read and POM/module decoding, independent of Maven or Gradle. */ +export interface MavenGradleMetadataPort { + readonly identity: ProviderIdentity; + close(): Promise; + inspect( + input: InspectMavenGradleMetadataInput, + options?: ExecutionOptions, + ): Promise>; +} diff --git a/src/server/createServer.ts b/src/server/createServer.ts index 94182bc4a9..26f05821c2 100644 --- a/src/server/createServer.ts +++ b/src/server/createServer.ts @@ -203,6 +203,7 @@ export const createServer = ( releaseExposure, nugetNupkg, pythonPyc, + mavenGradleMetadata, dwarfUnits, elfDependencies, webNetworkCapture, @@ -447,6 +448,7 @@ export const createServer = ( sqliteDatabase, packetCapture, signalRecording, + mavenGradleMetadata, }, contractTools, ); diff --git a/src/server/serviceToolBindings.ts b/src/server/serviceToolBindings.ts index 5195bcc3f6..1babc82d70 100644 --- a/src/server/serviceToolBindings.ts +++ b/src/server/serviceToolBindings.ts @@ -1,3 +1,5 @@ +import type { MavenGradleMetadataService } from "../application/java/MavenGradleMetadataService.js"; + import type { NugetNupkgService } from "../application/nuget/NugetNupkgService.js"; import type { DwarfUnitsService } from "../application/binaryDiagnostics/DwarfUnitsService.js"; import type { ElfDependenciesService } from "../application/binaryDiagnostics/ElfDependenciesService.js"; @@ -862,6 +864,12 @@ const SERVICE_TOOL_BINDINGS = { run: (input, options) => service.recover(input, options), }, })) satisfies Bind, + mavenGradleMetadata: ((service) => ({ + inspect_maven_gradle_metadata: { + admission: "application", + run: (input, options) => service.inspect(input, options), + }, + })) satisfies Bind, dwarfUnits: ((service) => ({ inspect_dwarf_units: { admission: "application", diff --git a/tests/acceptance/mavenGradleMetadataCli.test.ts b/tests/acceptance/mavenGradleMetadataCli.test.ts new file mode 100644 index 0000000000..f8513c257b --- /dev/null +++ b/tests/acceptance/mavenGradleMetadataCli.test.ts @@ -0,0 +1,287 @@ +import { createHash } from "node:crypto"; +import { writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { expect } from "vitest"; +import { contractNamed } from "../../src/cli/contractCliDescription.js"; +import { MAVEN_GRADLE_METADATA_TOOL_CONTRACTS } from "../../src/contracts/java/mavenGradleMetadataToolContracts.js"; +import { toolContract } from "../../src/contracts/toolContracts.js"; +import { parseEvidenceBundle } from "../../src/domain/evidenceBundle.js"; +import { connectLocalToolsMcp } from "../fixtures/localToolsMcp.js"; +import { + gradleModuleFixture, + mavenPomFixture, +} from "../../src/java/MavenGradleMetadata.fixture.js"; +import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; +import { cliTest } from "../support/cli/cliFixture.js"; + +const outputSchema = contractNamed( + MAVEN_GRADLE_METADATA_TOOL_CONTRACTS, + "inspect_maven_gradle_metadata", +).outputSchema; + +cliTest( + "reports a missing child artifact independently of parent group and version through CLI and MCP", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-maven-parent-gap-"); + const path = join(root, "pom.xml"); + await writeFile( + path, + `4.0.0exampleparent1`, + ); + const result = await cli.run({ + arguments: ["inspect-maven-gradle-metadata", path, "--json"], + }); + expect(result.exitCode, result.stderr).toBe(0); + const expected = [ + { + kind: "parent-coordinate", + reference: "parent.group_id", + field: "group_id", + owner: "project", + index: null, + }, + { + kind: "missing-coordinate", + reference: "project.artifact_id", + field: "artifact_id", + owner: "project", + index: null, + }, + { + kind: "parent-coordinate", + reference: "parent.version", + field: "version", + owner: "project", + index: null, + }, + ]; + const cliEvidence = outputSchema.parse(result.json); + expect(cliEvidence.normalized_result.unresolved).toEqual(expected); + const { call } = await connectLocalToolsMcp(); + const response = await call("inspect_maven_gradle_metadata", { path }); + expect(response.isError, JSON.stringify(response)).not.toBe(true); + const evidence = outputSchema.parse(response.structuredContent); + expect(evidence.normalized_result).toEqual(cliEvidence.normalized_result); + const retained = await call("get_evidence_bundle", { detail: "complete" }); + expect(retained.isError, JSON.stringify(retained)).not.toBe(true); + const bundle = parseEvidenceBundle( + toolContract("get_evidence_bundle").outputSchema.parse( + retained.structuredContent, + ).result, + ); + expect( + bundle.records.find( + (record) => record.evidence_id === evidence.evidence_id, + ), + ).toEqual(evidence); + }, +); + +cliTest( + "preserves metadata caller selections and transport URL provenance through CLI, MCP and retained records", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-metadata-provenance-"); + const { call } = await connectLocalToolsMcp(); + const url = "HTTPS://user:password@Example.invalid/a/../b?token=visible"; + for (const [file, source] of [ + [ + "pom.xml", + mavenPomFixture.replace( + "", + `${url}`, + ), + ], + [ + "demo.module", + JSON.stringify({ + formatVersion: "1.1", + component: { group: "g", module: "m", version: "1" }, + variants: [ + { + name: "api", + "available-at": { + url, + group: "g", + module: "other", + version: "1", + }, + }, + ], + }), + ], + ] as const) { + const path = join(root, file); + await writeFile(path, source); + for (const maximum of [undefined, 1048576, 65536]) { + const input = { + path, + ...(maximum === undefined ? {} : { max_file_bytes: maximum }), + }; + const output = await cli.run({ + arguments: [ + "inspect-maven-gradle-metadata", + `./${file}`, + "--json", + ...(maximum === undefined + ? [] + : ["--max-file-bytes", String(maximum)]), + ], + cwd: root, + }); + expect(output.exitCode, output.stderr).toBe(0); + const cliEvidence = outputSchema.parse(output.json); + expect(cliEvidence.caller_input_path).toBe(`./${file}`); + expect(cliEvidence.parameters).toEqual(input); + const response = await call("inspect_maven_gradle_metadata", input); + expect(response.isError, JSON.stringify(response)).not.toBe(true); + const evidence = outputSchema.parse(response.structuredContent); + expect(evidence.parameters).toEqual(input); + expect(evidence.normalized_result).toEqual( + cliEvidence.normalized_result, + ); + expect(JSON.stringify(evidence)).not.toContain("user:password"); + expect(JSON.stringify(evidence)).toContain( + "HTTPS://Example.invalid/a/../b?token=visible", + ); + const retained = await call("get_evidence_bundle", { + detail: "complete", + }); + expect(retained.isError, JSON.stringify(retained)).not.toBe(true); + const bundle = parseEvidenceBundle( + toolContract("get_evidence_bundle").outputSchema.parse( + retained.structuredContent, + ).result, + ); + expect( + bundle.records.find( + (record) => record.evidence_id === evidence.evidence_id, + ), + ).toEqual(evidence); + } + } + }, +); + +cliTest( + "reports Maven coordinates and a BOM import through the public CLI", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-maven-cli-"); + const path = join(root, "pom.xml"); + const bytes = Buffer.from(mavenPomFixture, "utf8"); + await writeFile(path, bytes); + const result = await cli.run({ + arguments: ["inspect-maven-gradle-metadata", path, "--json"], + }); + expect(result.exitCode, result.stderr).toBe(0); + const evidence = outputSchema.parse(result.json); + const report = evidence.normalized_result; + expect(report.format).toBe("maven-pom"); + expect(report.coordinates.artifact_id).toBe("demo"); + expect(report.coordinates.version).toBe("${revision}"); + expect(report.dependency_management[0]).toMatchObject({ + artifact_id: "spring-boot-dependencies", + bom_import: true, + }); + expect(report.coverage.status).toBe("complete"); + expect(report.artifact.sha256).toBe( + createHash("sha256").update(bytes).digest("hex"), + ); + }, +); + +cliTest( + "reports Gradle variants and platform constraints through the public CLI", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-gradle-cli-"); + const path = join(root, "demo-1.2.3.module"); + await writeFile(path, gradleModuleFixture); + const result = await cli.run({ + arguments: ["inspect-maven-gradle-metadata", path, "--json"], + }); + expect(result.exitCode, result.stderr).toBe(0); + const report = outputSchema.parse(result.json).normalized_result; + expect(report.format).toBe("gradle-module"); + expect(report.coordinates).toMatchObject({ + group_id: "com.example", + artifact_id: "demo", + version: "1.2.3", + }); + expect(report.gradle?.variants.map((variant) => variant.name)).toEqual([ + "apiElements", + "runtimeElements", + "demoPlatform", + ]); + expect( + report.dependency_management.find((row) => row.platform), + ).toMatchObject({ + artifact_id: "jackson-databind", + version: "[2.17,2.18)", + variant: "demoPlatform", + }); + }, +); + +cliTest( + "resolves a relative POM path against the working directory", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-maven-cli-rel-"); + await writeFile(join(root, "pom.xml"), mavenPomFixture); + const result = await cli.run({ + arguments: ["inspect-maven-gradle-metadata", "pom.xml", "--json"], + cwd: root, + }); + expect(result.exitCode, result.stderr).toBe(0); + expect( + outputSchema.parse(result.json).normalized_result.artifact.path, + ).toBe(join(root, "pom.xml")); + }, +); + +cliTest( + "fails closed on a file that is not Maven POM or Gradle module metadata", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-maven-cli-foreign-"); + const path = join(root, "notes.txt"); + const foreign = Buffer.from("hello world\n", "utf8"); + await writeFile(path, foreign); + const result = await cli.run({ + arguments: ["inspect-maven-gradle-metadata", path, "--json"], + }); + expect(result.exitCode).toBe(1); + expect(result.json).toMatchObject({ + code: "unsupported_target", + details: { + operation: "inspect_maven_gradle_metadata", + partial_observation: { + kind: "file-snapshot-hash", + path, + bytes: foreign.length, + sha256: createHash("sha256").update(foreign).digest("hex"), + }, + }, + }); + }, +); + +cliTest("fails closed on malformed XML", async ({ cli }) => { + const root = await createTestTempDirectory("rea-maven-cli-malformed-"); + const path = join(root, "pom.xml"); + const corrupt = Buffer.from("demo", "utf8"); + await writeFile(path, corrupt); + const result = await cli.run({ + arguments: ["inspect-maven-gradle-metadata", path, "--json"], + }); + expect(result.exitCode).toBe(1); + expect(result.json).toMatchObject({ + code: "invalid_request", + details: { + operation: "inspect_maven_gradle_metadata", + partial_observation: { + kind: "file-snapshot-hash", + path, + bytes: corrupt.length, + sha256: createHash("sha256").update(corrupt).digest("hex"), + }, + }, + }); +}); diff --git a/tests/boundary/filesystem/mavenGradleMetadata.test.ts b/tests/boundary/filesystem/mavenGradleMetadata.test.ts new file mode 100644 index 0000000000..2d68460509 --- /dev/null +++ b/tests/boundary/filesystem/mavenGradleMetadata.test.ts @@ -0,0 +1,30 @@ +import { writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { describe, expect, it } from "vitest"; +import { createMavenGradleMetadataService } from "../../../src/composition/mavenGradleMetadata.js"; +import { mavenPomFixture } from "../../../src/java/MavenGradleMetadata.fixture.js"; +import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; + +describe("Maven POM and Gradle module metadata stable filesystem boundary", () => { + it("returns typed resource and cancellation failures", async () => { + const root = await createTestTempDirectory("rea-maven-gradle-budget-"); + const path = join(root, "pom.xml"); + await writeFile(path, mavenPomFixture); + const service = createMavenGradleMetadataService(); + try { + const tooSmall = await service.inspect({ path, max_file_bytes: 16 }); + if (tooSmall.ok) throw new Error("Expected resource budget failure"); + expect(tooSmall.error._tag).toBe("AnalysisResourceConstraintError"); + const cancelled = await service.inspect( + { path }, + { signal: AbortSignal.abort() }, + ); + if (cancelled.ok) throw new Error("Expected cancellation"); + expect(cancelled.error._tag).toBe("AnalysisCancelledError"); + const control = await service.inspect({ path }); + if (!control.ok) throw control.error; + } finally { + await service.close(); + } + }); +}); diff --git a/tests/boundary/mcp/absoluteLocalPathTools.test.ts b/tests/boundary/mcp/absoluteLocalPathTools.test.ts index 5029b09a2f..c8368cd1eb 100644 --- a/tests/boundary/mcp/absoluteLocalPathTools.test.ts +++ b/tests/boundary/mcp/absoluteLocalPathTools.test.ts @@ -6,6 +6,7 @@ import { expect, it } from "vitest"; import { JAVASCRIPT_RECOVERY_TOOL_CONTRACTS } from "../../../src/contracts/javascript/javascriptRecoveryToolContracts.js"; import { BINARY_DIAGNOSTICS_TOOL_CONTRACTS } from "../../../src/contracts/native/binaryDiagnosticsToolContracts.js"; import { V8_CODE_CACHE_TOOL_CONTRACTS } from "../../../src/contracts/v8/v8CodeCacheToolContracts.js"; +import { MAVEN_GRADLE_METADATA_TOOL_CONTRACTS } from "../../../src/contracts/java/mavenGradleMetadataToolContracts.js"; import { WEB_SCRIPT_TOOL_CONTRACTS } from "../../../src/contracts/webScriptToolContracts.js"; import { API_CONTRACT_TOOL_CONTRACTS } from "../../../src/contracts/apiContractToolContracts.js"; import { PLAYWRIGHT_TRACE_TOOL_CONTRACTS } from "../../../src/contracts/playwrightTraceToolContracts.js"; @@ -24,6 +25,7 @@ const CONTRACTS = [ ...PYTHON_PYC_TOOL_CONTRACTS, ...NUGET_NUPKG_TOOL_CONTRACTS, ...V8_CODE_CACHE_TOOL_CONTRACTS, + ...MAVEN_GRADLE_METADATA_TOOL_CONTRACTS, ]; const PATH_FIELDS = { @@ -39,6 +41,7 @@ const PATH_FIELDS = { inspect_python_pyc: ["path"], inspect_nuget_nupkg: ["path"], inspect_v8_code_cache: ["path"], + inspect_maven_gradle_metadata: ["path"], export_web_scripts: ["capture_path", "output_directory"], recover_javascript_sources: ["path", "output_directory", "additional_paths"], } as const; @@ -146,6 +149,7 @@ it("rejects one relative path field at a time on tools/list", async () => { "inspect_python_pyc.path", "inspect_nuget_nupkg.path", "inspect_v8_code_cache.path", + "inspect_maven_gradle_metadata.path", "export_web_scripts.capture_path", "export_web_scripts.output_directory", "recover_javascript_sources.path", diff --git a/tests/boundary/mcp/mavenGradleMetadataMcp.test.ts b/tests/boundary/mcp/mavenGradleMetadataMcp.test.ts new file mode 100644 index 0000000000..eda33e1c91 --- /dev/null +++ b/tests/boundary/mcp/mavenGradleMetadataMcp.test.ts @@ -0,0 +1,191 @@ +import { createHash } from "node:crypto"; +import { writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { expect } from "vitest"; +import { createServer } from "../../../src/server/createServer.js"; +import { contractNamed } from "../../../src/cli/contractCliDescription.js"; +import { MAVEN_GRADLE_METADATA_TOOL_CONTRACTS } from "../../../src/contracts/java/mavenGradleMetadataToolContracts.js"; +import { mavenGradleMetadataSchema } from "../../../src/domain/java/mavenGradleMetadata.js"; +import { + gradleModuleFixture, + mavenPomFixture, +} from "../../../src/java/MavenGradleMetadata.fixture.js"; +import { createTestBinarySession } from "../../fixtures/binarySession.js"; +import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; +import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; +import { mcpTest, type TestMcp } from "../../support/mcp/mcpFixture.js"; + +const completeEvidenceSchema = contractNamed( + MAVEN_GRADLE_METADATA_TOOL_CONTRACTS, + "inspect_maven_gradle_metadata", +).outputSchema.safeExtend({ normalized_result: mavenGradleMetadataSchema }); + +const connect = async (mcp: TestMcp) => { + const session = createTestBinarySession(() => { + throw new Error( + "Maven/Gradle metadata inspection must not start a deep provider", + ); + }); + const client = await mcp.connect(createServer({ kind: "session", session })); + return { client, session }; +}; + +mcpTest( + "retains omitted, explicit default and selected metadata budgets through registered MCP admission", + async ({ mcp }) => { + const { client, session } = await connect(mcp); + const root = await createTestTempDirectory("rea-maven-admission-"); + const path = join(root, "pom.xml"); + await writeFile(path, mavenPomFixture); + try { + for (const maximum of [undefined, 1048576, 65536]) { + const input = { + path, + ...(maximum === undefined ? {} : { max_file_bytes: maximum }), + }; + const response = await client.callTool({ + name: "inspect_maven_gradle_metadata", + arguments: input, + }); + expect(response.isError, JSON.stringify(response)).not.toBe(true); + expect( + completeEvidenceSchema.parse(response.structuredContent).parameters, + ).toEqual(input); + } + } finally { + await session.close(); + } + }, +); + +mcpTest( + "advertises inspect_maven_gradle_metadata and reports a real POM", + async ({ mcp }) => { + const { client, session } = await connect(mcp); + try { + const advertised = (await client.listTools()).tools.find( + (tool) => tool.name === "inspect_maven_gradle_metadata", + ); + expect(advertised?.annotations).toMatchObject({ + readOnlyHint: false, + idempotentHint: true, + }); + const root = await createTestTempDirectory("rea-maven-mcp-"); + const path = join(root, "pom.xml"); + await writeFile(path, mavenPomFixture); + const response = await client.callTool({ + name: "inspect_maven_gradle_metadata", + arguments: { path }, + }); + expect(response.isError, JSON.stringify(response.content)).not.toBe(true); + const evidence = completeEvidenceSchema.parse(response.structuredContent); + const report = evidence.normalized_result; + expect(report.format).toBe("maven-pom"); + expect(report.coordinates.artifact_id).toBe("demo"); + expect(report.dependency_management[0]?.bom_import).toBe(true); + expect(report.limitations.join(" ")).toContain( + "without running Maven or Gradle", + ); + } finally { + await session.close(); + } + }, +); + +mcpTest( + "reports Gradle module variants from inspect_maven_gradle_metadata", + async ({ mcp }) => { + const { client, session } = await connect(mcp); + try { + const root = await createTestTempDirectory("rea-gradle-mcp-"); + const path = join(root, "demo-1.2.3.module"); + await writeFile(path, gradleModuleFixture); + const response = await client.callTool({ + name: "inspect_maven_gradle_metadata", + arguments: { path }, + }); + expect(response.isError, JSON.stringify(response.content)).not.toBe(true); + const report = completeEvidenceSchema.parse( + response.structuredContent, + ).normalized_result; + expect(report.format).toBe("gradle-module"); + expect(report.coordinates.group_id).toBe("com.example"); + expect(report.gradle?.format_version).toBe("1.1"); + } finally { + await session.close(); + } + }, +); + +mcpTest( + "requires an absolute path for inspect_maven_gradle_metadata", + async ({ mcp }) => { + const { client, session } = await connect(mcp); + try { + const response = await client.callTool({ + name: "inspect_maven_gradle_metadata", + arguments: { path: "pom.xml" }, + }); + expect(response.isError).toBe(true); + expect(parseMcpToolError(response).error).toMatchObject({ + code: "invalid_request", + details: { operation: "inspect_maven_gradle_metadata" }, + }); + } finally { + await session.close(); + } + }, +); + +mcpTest( + "reports a foreign file as an unsupported target rather than a parse", + async ({ mcp }) => { + const { client, session } = await connect(mcp); + try { + const root = await createTestTempDirectory("rea-maven-unsupported-"); + const path = join(root, "notes.txt"); + const foreign = Buffer.from("hello world\n", "utf8"); + await writeFile(path, foreign); + const response = await client.callTool({ + name: "inspect_maven_gradle_metadata", + arguments: { path }, + }); + expect(response.isError).toBe(true); + expect(parseMcpToolError(response).error).toMatchObject({ + code: "unsupported_target", + details: { operation: "inspect_maven_gradle_metadata" }, + }); + } finally { + await session.close(); + } + }, +); + +mcpTest("reports malformed XML as invalid input", async ({ mcp }) => { + const { client, session } = await connect(mcp); + try { + const root = await createTestTempDirectory("rea-maven-malformed-"); + const path = join(root, "pom.xml"); + const corrupt = Buffer.from("demo", "utf8"); + await writeFile(path, corrupt); + const response = await client.callTool({ + name: "inspect_maven_gradle_metadata", + arguments: { path }, + }); + expect(response.isError).toBe(true); + expect(parseMcpToolError(response).error).toMatchObject({ + code: "invalid_request", + details: { + operation: "inspect_maven_gradle_metadata", + partial_observation: { + kind: "file-snapshot-hash", + path, + bytes: corrupt.length, + sha256: createHash("sha256").update(corrupt).digest("hex"), + }, + }, + }); + } finally { + await session.close(); + } +}); diff --git a/tests/conformance/providerCapabilityCases.ts b/tests/conformance/providerCapabilityCases.ts index 5082df835a..f578f07ff4 100644 --- a/tests/conformance/providerCapabilityCases.ts +++ b/tests/conformance/providerCapabilityCases.ts @@ -120,6 +120,9 @@ export const PROVIDER_CAPABILITY_CONFORMANCE: Readonly< managedWorkflow: { cases: ["tests/boundary/mcp/managedWorkflowUnknownIdentityMcp.test.ts"], }, + mavenGradleMetadata: { + cases: ["tests/acceptance/mavenGradleMetadataCli.test.ts"], + }, modelArtifact: { cases: ["tests/acceptance/modelArtifactCli.test.ts"] }, nativeExports: { cases: [ diff --git a/tests/process-global/stableArtifactConsumers.test.ts b/tests/process-global/stableArtifactConsumers.test.ts index 93472cc2f0..3c99afd7f2 100644 --- a/tests/process-global/stableArtifactConsumers.test.ts +++ b/tests/process-global/stableArtifactConsumers.test.ts @@ -1,3 +1,7 @@ +import { MavenGradleMetadataProvider } from "../../src/java/MavenGradleMetadataProvider.js"; +import { MavenGradleMetadataService } from "../../src/application/java/MavenGradleMetadataService.js"; +import { inspectMavenGradleMetadataInputSchema } from "../../src/domain/java/mavenGradleMetadata.js"; +import { mavenPomFixture } from "../../src/java/MavenGradleMetadata.fixture.js"; import { unknownTarget } from "../../src/domain/targetIdentity.js"; import { PeLoadConfigProvider } from "../../src/native/pe/PeLoadConfigProvider.js"; import { createArtifactAnalysisResources } from "../../src/providers/artifactResourceFailure.js"; @@ -209,17 +213,27 @@ it("preserves opaque NuGet decoder failures and the completed file identity", as } }); -it.each(["close failure", "close cancellation"])( - "retains only the completed NuGet file snapshot through %s and cleanup retry", - async (outcome) => { +it.each( + ["close failure", "close cancellation"].flatMap((outcome) => + ["NuGet", "Maven/Gradle"].map((kind) => ({ outcome, kind })), + ), +)( + "retains only the completed $kind file snapshot through $outcome and cleanup retry", + async ({ outcome, kind }) => { const path = await selectedImage(); - const bytes = await nugetNupkgFixture(); + const bytes = + kind === "NuGet" + ? await nugetNupkgFixture() + : Buffer.from(mavenPomFixture); await writeFile(path, bytes); const controller = new AbortController(); - const reason = { source: "NuGet file finalization" }; + const reason = { source: `${kind} file finalization` }; if (outcome === "close cancellation") fault.onClose = () => controller.abort(reason); - const service = new NugetNupkgService(new NugetNupkgProvider()); + const service = + kind === "NuGet" + ? new NugetNupkgService(new NugetNupkgProvider()) + : new MavenGradleMetadataService(new MavenGradleMetadataProvider()); try { const result = await service.inspect( { path }, @@ -1123,6 +1137,7 @@ const stableArtifactProviders = [ ["native exports", () => new NativeExportsProvider()], ["Python pyc", () => new PythonPycProvider()], ["NuGet nupkg", () => new NugetNupkgProvider()], + ["Maven/Gradle metadata", () => new MavenGradleMetadataProvider()], ] as const; const fileFailureProviders = [ @@ -1136,6 +1151,11 @@ const inspectFileFailure = ( signal?: AbortSignal, ) => { const options = signal === undefined ? undefined : { signal }; + if (provider instanceof MavenGradleMetadataProvider) + return provider.inspect( + inspectMavenGradleMetadataInputSchema.parse({ path }), + options, + ); if (provider instanceof NugetNupkgProvider) return provider.inspect( inspectNugetNupkgInputSchema.parse({ path }), @@ -1272,7 +1292,8 @@ it.each( provider instanceof KernelBuildConfigProvider || provider instanceof PeCertificatesProvider || provider instanceof PeResourcesProvider || - provider instanceof NugetNupkgProvider + provider instanceof NugetNupkgProvider || + provider instanceof MavenGradleMetadataProvider ? "ArtifactOperationError" : "ProviderAdapterError"), ); diff --git a/tests/support/providerLifecycleCoverage.ts b/tests/support/providerLifecycleCoverage.ts index e6b6b9b217..3d51b944fd 100644 --- a/tests/support/providerLifecycleCoverage.ts +++ b/tests/support/providerLifecycleCoverage.ts @@ -1460,6 +1460,20 @@ export const PROVIDER_LIFECYCLE_COVERAGE: Readonly< ), typedFailures("tests/boundary/filesystem/kernelModule.test.ts"), ), + "rea-maven-gradle-metadata": inProcess( + covered( + test( + "tests/boundary/mcp/mavenGradleMetadataMcp.test.ts", + "advertises inspect_maven_gradle_metadata and reports a real POM", + ), + ), + covered( + test( + "src/application/java/MavenGradleMetadataService.test.ts", + "retains completed Evidence and selected parameters on late cancellation", + ), + ), + ), "rea-native-exports": inProcess( covered( test(