feat(artifacts): inspect Maven POM and Gradle module metadata

Inspect local Maven/Gradle metadata as Evidence with bounded report/XML admission, preserved caller choices and owned cleanup.

Refs #8828; broader comparison and resolution work remains outside this change.

Assisted-by: Suika (gensokyo-skills:suika-scatter-gather-planning)
Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
This commit is contained in:
Matt Van Hornandgensokyo-dev authored and GitHub committed 2026-11-17 14:40:38 +00:00
1 parent 5ccb7c59c8
commit 05be423acb
50 files changed
+3872 -24

No files matched your search

+155
View File
@@ -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<string, unknown> =>
schema["~standard"].jsonSchema.input({
target: "draft-2020-12",
}) as Record<string, unknown>;
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<string, Record<string, unknown>>
).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);
});
+255
View File
@@ -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 `<dependency/>`) 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 `<exclusion/>`) 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<string, void> {
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.<status>` 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<typeof mavenGradleMetadataSchema>;
export type InspectMavenGradleMetadataInput = z.infer<
typeof inspectMavenGradleMetadataInputSchema
>;
export type MavenGradleDependency = MavenGradleMetadata["dependencies"][number];
export type MavenGradleUnresolved = MavenGradleMetadata["unresolved"][number];