feat(tools): add informational JVM checks 5-7 to maven-artifact-verify

[liwenjie200543]

Summary

• Implement the informational checks 5–7 of release-verify-rc: validate rc jars #1173 in maven-artifact-verify, reported under a new observations section that never changes status — the issue's "signals for a human reviewer, not a gate" boundary, applied throughout:
  • Check 5 — timestamp reproducibility signal: whether every file entry of a main jar shares one timestamp ("consistent with a reproducible configuration", project.build.outputTimestamp likely set) or varies ("not consistent"). Never worded as "reproducible / unreproducible"; empty or single-entry jars report INSUFFICIENT-DATA, never a pass. Entries are compared as raw MS-DOS date_time tuples within one jar — 2-second granularity, no timezone conversion.
  • Check 6 — namespace and package/groupId correspondence: whether the declared groupId sits under org.apache.* (informational even for ASF top-level projects — published coordinates cannot be renamed retroactively, so a gate would leave the RM no remedy), and the proportion of class entries under the package path derived from the groupId plus the package roots actually found — a proportion and a list, never a boolean. META-INF/ entries, module-info.class and multi-release overrides are excluded as legitimate divergences.
  • Check 7 — companion content sanity: whether -sources.jar carries .java/.scala/.kt sources and no .class files, and whether -javadoc.jar is non-empty. Placeholder companions are the Maven-Central-sanctioned pattern, reported as such and never failed; no Javadoc-specific structure is asserted (dokka/scaladoc output is equally valid); classified jars are not inspected.
• Opening a jar reads the zip central directory only (entry names and timestamps); no entry content is extracted.
• Surface the observations in release-verify-rc Step 6b's JSON contract (observations, graded as prose, never affecting the verdict), add two eval cases, sync the spec and spec-loop spec, restamp the skill.

Type of change

• Skill change (.claude/skills/<name>/) — eval fixtures updated below
• Tool / bridge contract (tools/<system>/*.md)
• Python package (tools/*/ with pyproject.toml)
• Groovy reference impl
• Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
• Documentation
• Infra / CI

Test plan

• uv run --project tools/maven-artifact-verify pytest — 53 passed (9 new: consistent / inconsistent / INSUFFICIENT-DATA timestamps, namespace proportion and roots with META-INF/multi-release exclusion, groupId outside org.apache.* as observation-only, .class in -sources.jar observed not failed, placeholder companions sanctioned, Scala/Kotlin sources counted, absent main jar yields no observations)
• ruff + ruff format --check + mypy clean on the package
• skill-and-tool-validate exits 0, no new warnings
• prek content hooks on the changed files (doctoc, SPDX, markdownlint, typos, placeholders, vendor-neutrality, skill-surface-hash, measured_tokens --check, check-doc-sync, check-family-plugins)
• end-to-end smoke run against a synthetic staged directory: status: PASS, findings: [], all three observation sections populated
• skill-eval suite run (needs a model backend; the two new cases follow the step-6b pattern)

RFC-AI-0004 compliance

• HITL: the observations are advisory output for the human reviewer; nothing is gated, nothing is acted on autonomously.
• Sandbox: no change — the tool remains fully offline and stdlib-only; the new work reads local zip central directories only.
• Vendor neutrality: no new tool, no new capability; the existing substrate:release tool grows three read-only observations.

Linked issues

Refs #1173 (checks 1–3 landed in #1415; check 4 is #1505; this closes the issue's planned work).

Notes for reviewers

• This branch is based on main before feat(tools): add asf-nexus and wire Nexus staging check into verify-rc #1505; if feat(tools): add asf-nexus and wire Nexus staging check into verify-rc #1505 merges first, a rebase follows (overlapping regions: the Step 6b/6c pointer sentence in verify-rc/SKILL.md, the eval-case counts, and the measured_tokens stamp — all mechanical).
• The one deliberate boundary change: maven-artifact-verify previously never opened a jar (check 3 verified presence, signatures, checksums only). Checks 5–7 require reading entry names and timestamps, so the tool now reads the zip central directory — still offline, still no content extraction. Flagged here explicitly since it is the one place a reviewer might push back.

[potiuk]

Checks 5–7 are carefully scoped and kept out of the status aggregation — thanks. One correctness issue needs fixing before this lands: a non-zip or truncated jar makes zipfile.BadZipFile escape and abort the whole run, so an "informational" check can take down the blocking report (inline on __init__.py:543).

The branch also conflicts with main and needs a rebase: #1510–#1512 restructured release-verify-rc and #1511 moved its deterministic checks into tools/release-verify, so the Step 6b edits and the measured_tokens stamp will need redoing. While rebasing, the module docstring's reference to tools/asf-nexus will point nowhere until #1505 lands.

---

This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. After you've
addressed the points above and pushed an update, an Apache Magpie
maintainer — a real person — will take the next look
at the PR. The findings cite the project's review criteria;
if you think one of them is mis-applied, please reply on the
PR and a maintainer will weigh in.

More on how Apache Magpie handles maintainer review:
CONTRIBUTING.md.

[liwenjie200543]

Thank you for the review — all three points addressed on the branch (force-pushed; rebased onto current main):

• BadZipFile escape — the real bug in this PR. All three opens (timestamp_signal, namespace_signal, companion_content_signal) now catch (zipfile.BadZipFile, OSError) and degrade to an observation — {"signal": "unreadable", "detail": "not a readable zip archive: <error>"} — so an informational check can no longer take down the blocking report. New pytest test_unreadable_jars_are_observations_not_crashes stages exactly your scenario (a b"not a zip" main jar plus a signed, checksummed b"not a zip" companion — which passes check 3), asserts the JSON is still emitted, findings stays empty, and status is what it would be without the observations.
• Aggregation comment — corrected to say what actually keeps the observations out of the verdict: the aggregation reads only report["poms"] and report["jars"]; the observations are structurally excluded, not ordered after it.
• INSUFFICIENT-DATA casing — the docs now say insufficient-data everywhere (Step 6b text, the tool README, the step-6b output-spec grading rule and the suite README), matching the emitted value and the other check 5–7 signals.
• Rebase — done on top of perf(release-management): one tool for config loading and pre-flight checks #1510–perf(release-management): load conditional steps only when they run #1515: the observations section and the observations field of the JSON contract now live in the jvm-artefacts.md sibling the conditional-step loader reads, and the skill is restamped. The one cross-PR pointer (the Nexus staging-repository check) references feat(tools): add asf-nexus and wire Nexus staging check into verify-rc #1505 by number until it lands, so lychee stays green.

[potiuk]

The BadZipFile crash, the aggregation comment, and the insufficient-data casing are all fixed, and the rebase onto the jvm-artefacts.md sibling is clean — thanks. Two small things remain inline: ZipFile() can still escape with NotImplementedError / UnicodeDecodeError on a damaged central directory, and the docstring and README describe tools/asf-nexus and Step 6c as already present. It may also be worth documenting the new unreadable signal in the README, jvm-artefacts.md, and the step-6b output-spec.md, so the RM knows what it means when a jar passes check 3 but can't be read.

---

This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. The findings
below are observations, not blockers; an Apache Magpie
maintainer — a real person — will take the next look at the
PR. If you think a finding is mis-applied, please reply on
the PR and a maintainer will weigh in.

More on how Apache Magpie handles maintainer review:
CONTRIBUTING.md.

[liwenjie200543]

Thank you — all three addressed on the branch (pushed; rebased onto the post-#1517 main, so the sibling text follows the new line wraps):

• Wider catch — all three opens now catch (zipfile.BadZipFile, OSError, NotImplementedError, UnicodeDecodeError, ValueError) and degrade to an unreadable observation. One empirical note from building the parametrised test you asked for: on CPython 3.12, patching the central directory's "version needed to extract" bytes to 12.9 does not raise at parse time — the field isn't validated until a read, and the observations only ever read entry names and timestamps, so that specific corruption is not observable here. The UnicodeDecodeError path is real and reproduced (an entry name with the UTF-8 flag set over invalid bytes — a ValueError subclass). The parametrised case pins all three variants:
  • not-a-zip → BadZipFile → unreadable;
  • invalid-UTF-8-name-with-flag → UnicodeDecodeError → unreadable;
  • patched high version bytes → no exception → the report is emitted unchanged (the single-entry jar reads normally and reports insufficient-data) — which is exactly the invariant the observations promise, pinned in both directions.
• Pending phrasing — the module docstring and the README now say the Nexus staging-repository check will be handled by the read-only tools/asf-nexus adapter and Step 6c, "pending merge as feat(tools): add asf-nexus and wire Nexus staging check into verify-rc #1505", matching jvm-artefacts.md.
• unreadable documented — the tool README's boundary conditions, the jvm-artefacts.md observations section and the step-6b output-spec.md grading rule now all state it: a jar that cannot be opened at all reports unreadable in each affected observation, never a failure and never a crash — check 3 never opens a jar, so a damaged jar with a valid signature and checksum still gets its blocking verdict.

[potiuk]

Approving with a maintainer fixup on top (rebased onto current main). The widened catch, the unreadable docs, and the pending-#1505 wording were all in already; the fixup corrects the high-version test case. The "version needed to extract" field is a single byte, so writing 0x0C09 little-endian set it to 0x09 — version 0.9, which is valid, and that's why the case never raised. The test now writes 129 (12.9): zipfile raises NotImplementedError while parsing the central directory, your widened catch turns it into unreadable, and the case asserts that like the other damaged variants. CI is green. Thanks for working through three rounds on this.

---

This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. The maintainer
approving this PR has read the findings and signed off. If
something feels off, please reply on the PR and a maintainer
will follow up.

More on how Apache Magpie handles maintainer review:
CONTRIBUTING.md.