You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by "liwenjie200543 (via GitHub)" <gi...@apache.org> on 2026/10/04 06:23:36 UTC
[PR] feat(tools): add informational JVM checks 5-7 to maven-artifact-verify [magpie]
liwenjie200543 opened a new pull request, #1506:
URL: https://github.com/apache/magpie/pull/1506
<!-- SPDX-License-Identifier: Apache-2.0
https://www.apache.org/licenses/LICENSE-2.0 -->
## Summary
- Implement the informational checks 5–7 of #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`)
- [x] Python package (`tools/*/` with `pyproject.toml`)
- [ ] Groovy reference impl
- [ ] Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
- [x] Documentation
- [ ] Infra / CI
## Test plan
- [x] `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)
- [x] ruff + `ruff format --check` + mypy clean on the package
- [x] `skill-and-tool-validate` exits 0, no new warnings
- [x] 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`)
- [x] 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** #1505; if #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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@magpie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat(tools): add informational JVM checks 5-7 to maven-artifact-verify [magpie]
Posted by "potiuk (via GitHub)" <gi...@apache.org>.
potiuk commented on code in PR #1506:
URL: https://github.com/apache/magpie/pull/1506#discussion_r4179976043
##########
tools/maven-artifact-verify/src/maven_artifact_verify/__init__.py:
##########
@@ -608,6 +809,24 @@ def verify_staged_dir(staged_dir: Path, digests: list[str], podling: bool) -> di
for main in main_jars:
report["jars"].append(check_companions(main, digests, report["findings"]))
+ # --- informational observations (checks 5-7) ---
+ # These are signals for a human reviewer, never gates: they are
+ # appended to the report after the aggregate status is decided and
Review Comment:
**nit** — This comment says the observations are "appended to the report after the aggregate status is decided", but this block runs before `# --- aggregate ---`. What actually keeps them out of the verdict is that the aggregation only reads `report["poms"]` and `report["jars"]` — please say that, so a later edit to the aggregation doesn't rely on an ordering that doesn't exist.
##########
tools/maven-artifact-verify/README.md:
##########
@@ -77,10 +80,42 @@ blocking.
the release key, which `release-verify-rc` Step 2 runs against the
main artefacts, and the Step 6b recipe extends to the companions.
+The same run also reports the issue's **informational checks 5–7**
+under `observations` — signals for a human reviewer that never change
+the `status`:
+
+5. **Timestamp reproducibility signal** — whether every file entry of
+ a main jar shares one timestamp (consistent with
+ `project.build.outputTimestamp` being set) or varies across
+ entries. Worded as "consistent / not consistent with a reproducible
+ configuration", never as "reproducible" — only a rebuild-and-compare
+ can assert that. An empty or single-entry jar reports
+ `INSUFFICIENT-DATA`, never a pass. ZIP's MS-DOS entry times carry
Review Comment:
**minor** — Here, in verify-rc Step 6b, and in the step-6b `output-spec.md` grading rule, the single-entry case is spelled `INSUFFICIENT-DATA`, but the tool emits `"signal": "insufficient-data"` — like the other check 5–7 signals (`consistent`, `inconsistent`, `placeholder`, …). The blocking checks use uppercase (`PASS`/`FAIL`/`ABSENT`), so a reader will take the docs as the literal value. Please make the docs match the emitted value (or vice versa) so the RM and the eval grader look for the same string.
##########
tools/maven-artifact-verify/src/maven_artifact_verify/__init__.py:
##########
@@ -495,6 +521,178 @@ def split_jar_name(name: str) -> tuple[str, str | None, str | None]:
return m.group("stem"), m.group("version"), classifier
+SOURCE_EXTENSIONS = (".java", ".scala", ".kt")
+
+
+def timestamp_signal(jar: Path) -> dict:
+ """Check 5 - jar entry timestamp consistency (informational only).
+
+ If every file entry of the jar shares one timestamp, the project
+ almost certainly set ``project.build.outputTimestamp``; if the
+ timestamps vary, it almost certainly did not. The signal is
+ deliberately worded to never assert reproducibility either way -
+ only a rebuild-and-compare (``release-verify-rc`` Step 9) can do
+ that. An empty or single-entry jar gives no signal and reports
+ ``insufficient-data``, never a pass.
+
+ ZIP stores MS-DOS local times at 2-second granularity with no
+ timezone. Comparing entries *within one jar* needs neither a
+ tolerance nor a timezone assumption: the raw ``date_time`` tuples
+ are compared as-is and are never converted to absolute times.
+ """
+ with zipfile.ZipFile(jar) as archive:
Review Comment:
**major** — The observations are meant never to change the verdict, but none of the three `zipfile.ZipFile(...)` opens (here, in `namespace_signal`, and in `companion_content_signal`) is guarded. Check 3 never opens a jar, so a zero-byte or truncated `-javadoc.jar` with a matching `.asc` and `.sha512` passes check 3; `companion_content_signal` then raises `zipfile.BadZipFile: File is not a zip file`, which escapes `verify_staged_dir()` and `main()`. The process exits non-zero with a traceback and no JSON, so Step 6b never receives the `tool_report` for checks 1–3. The same happens for a damaged main jar in `timestamp_signal` / `namespace_signal`.
Please catch `(zipfile.BadZipFile, OSError)` around each open and return an observation instead (e.g. `{"jar": ..., "signal": "unreadable", "detail": "not a readable zip archive: <error>"}`), and add a pytest that stages a signed, checksummed companion and main jar whose bytes are `b"not a zip"`, asserting the JSON is still emitted and `status` is what it would be without the observations.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@magpie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat(tools): add informational JVM checks 5-7 to maven-artifact-verify [magpie]
Posted by "potiuk (via GitHub)" <gi...@apache.org>.
potiuk commented on code in PR #1506:
URL: https://github.com/apache/magpie/pull/1506#discussion_r4181744046
##########
tools/maven-artifact-verify/src/maven_artifact_verify/__init__.py:
##########
@@ -49,9 +49,34 @@
``packaging=pom`` modules are exempt (no jar), classified jars
(``-tests``, ``-shaded``, ...) are neither mains nor companions.
+Informational observations (checks 5-7 of the same issue) are
+reported alongside and **never** affect ``status`` - they are
+signals for a human reviewer, not gates:
+
+5. **Timestamp reproducibility signal** - whether every file entry
+ of a main jar shares one timestamp (consistent with
+ ``project.build.outputTimestamp`` being set) or varies (not
+ consistent with one). The report never claims the jar is or is
+ not reproducible; an empty or single-entry jar reports
+ ``insufficient-data``.
+6. **Namespace and package/groupId correspondence** - whether the
+ declared ``groupId`` sits under ``org.apache.*``, and how many of
+ the jar's class-file entries live under the package path derived
+ from the groupId, plus the package roots actually found. Reported
+ as a proportion and a root list, never a boolean verdict.
+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 a Maven-Central-sanctioned pattern and are reported as such,
+ never failed.
+
+Opening a jar here reads the zip central directory only (entry
+names and timestamps); no entry content is extracted.
+
The tool is stdlib-only and fully offline: it reads the staged
-directory, never the network. Nexus staging-repository checks are out
-of scope here (issue #1173, PR 2).
+directory, never the network. Nexus staging-repository checks are
+handled by `tools/asf-nexus` and `release-verify-rc` Step 6c (issue
Review Comment:
**nit** — This says the Nexus checks "are handled by `tools/asf-nexus` and `release-verify-rc` Step 6c", but neither exists on `main` until #1505 lands; `README.md:31-34` says the same in the present tense. Please phrase both as pending, as `jvm-artefacts.md` already does ("landing via #1505").
##########
tools/maven-artifact-verify/src/maven_artifact_verify/__init__.py:
##########
@@ -495,6 +521,202 @@ def split_jar_name(name: str) -> tuple[str, str | None, str | None]:
return m.group("stem"), m.group("version"), classifier
+SOURCE_EXTENSIONS = (".java", ".scala", ".kt")
+
+
+def timestamp_signal(jar: Path) -> dict:
+ """Check 5 - jar entry timestamp consistency (informational only).
+
+ If every file entry of the jar shares one timestamp, the project
+ almost certainly set ``project.build.outputTimestamp``; if the
+ timestamps vary, it almost certainly did not. The signal is
+ deliberately worded to never assert reproducibility either way -
+ only a rebuild-and-compare (``release-verify-rc`` Step 9) can do
+ that. An empty or single-entry jar gives no signal and reports
+ ``insufficient-data``, never a pass.
+
+ ZIP stores MS-DOS local times at 2-second granularity with no
+ timezone. Comparing entries *within one jar* needs neither a
+ tolerance nor a timezone assumption: the raw ``date_time`` tuples
+ are compared as-is and are never converted to absolute times.
+ """
+ try:
+ with zipfile.ZipFile(jar) as archive:
+ times = [info.date_time for info in archive.infolist() if not info.is_dir()]
+ except (zipfile.BadZipFile, OSError) as exc:
Review Comment:
**minor** — Thanks for the guard and the test — the `b"not a zip"` case now degrades correctly. `zipfile.ZipFile()` can still raise exceptions that are neither `BadZipFile` nor `OSError` while parsing a damaged central directory: `NotImplementedError("zip file version 12.9")` when the "version needed to extract" field is corrupted upward, and `UnicodeDecodeError` when the UTF-8 flag is set on an entry name with invalid bytes. Either escapes `verify_staged_dir()` exactly as `BadZipFile` did, so the blocking report is lost again. Please widen the catch in all three places (here, `namespace_signal`, `companion_content_signal`) to `(zipfile.BadZipFile, OSError, NotImplementedError, UnicodeDecodeError, ValueError)` — or `except Exception`, which is defensible since observations must never take the run down — and add a parametrised case with a jar whose central-directory version bytes are patched to a high value.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@magpie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat(tools): add informational JVM checks 5-7 to maven-artifact-verify [magpie]
Posted by "liwenjie200543 (via GitHub)" <gi...@apache.org>.
liwenjie200543 commented on PR #1506:
URL: https://github.com/apache/magpie/pull/1506#issuecomment-5991378367
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 #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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@magpie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat(tools): add informational JVM checks 5-7 to maven-artifact-verify [magpie]
Posted by "liwenjie200543 (via GitHub)" <gi...@apache.org>.
liwenjie200543 commented on PR #1506:
URL: https://github.com/apache/magpie/pull/1506#issuecomment-5988175314
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 #1510–#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 #1505 by number until it lands, so lychee stays green.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@magpie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat(tools): add informational JVM checks 5-7 to maven-artifact-verify [magpie]
Posted by "potiuk (via GitHub)" <gi...@apache.org>.
potiuk merged PR #1506:
URL: https://github.com/apache/magpie/pull/1506
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@magpie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org