From ff39a6334bb5d211bf4034ec2de1ffb343917b13 Mon Sep 17 00:00:00 2001 From: shoaibyazdani Date: Wed, 2 Sep 2026 08:58:39 +0200 Subject: [PATCH 1/2] docs: add runnable Node package manifest walkthrough Add a copy-pasteable Node package.json reduction walkthrough to docs/EXAMPLES.md. Reuses the existing benchmarks/node-package fixture and its Python oracle, runs from the repository root with the temporary output parent outside the fixture, validates the exported payload with 'report validate --payload --json', and shows the independent oracle rerun that exits 1 with ORIGINAL_FAILURE on stderr. Calls out the no-Node / no-install / no-registry / no-lifecycle-scripts / no-network boundary and the descriptive Python-oracle boundary, and links the fixture README plus SECURITY.md. Closes #20 --- docs/EXAMPLES.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/docs/EXAMPLES.md b/docs/EXAMPLES.md index 68a2db9..06b02fd 100644 --- a/docs/EXAMPLES.md +++ b/docs/EXAMPLES.md @@ -180,6 +180,78 @@ repomin . \ Only direct entries in `[packages]`, `[dev-packages]`, and `[requires]` are eligible. Pipenv source settings and `Pipfile.lock` are preserved. +## Shrink a Node package manifest without Node + +The Node manifest reducer is a structural `package.json` shrinker. It does not +need a Node runtime, package install, registry access, lifecycle scripts, or +external network: the oracle in the fixture is plain Python. The repository +ships a network-free fixture under `benchmarks/node-package/` that exercises +this path end to end. See the [fixture notes](../benchmarks/node-package/README.md) +for the original layout and the [host-backend boundary](../SECURITY.md) before +running anything else through it. + +Create a temporary output parent outside the fixture and run the reduction +from the repository root: + +```sh +out_parent="$(mktemp -d /tmp/repomin-node-package.XXXXXX)" +PYTHONPATH=src python3 -m repomin benchmarks/node-package \ + --command 'python3 reproduce.py' \ + --match 'ORIGINAL_FAILURE' \ + --adapter node \ + --source-reducer none \ + --output "$out_parent/result" +``` + +The reducer keeps exactly two files in the exported payload: + +```text +package.json +reproduce.py +``` + +Inside `package.json` the required entries are preserved: the `required-sdk` +runtime dependency pinned to `1.0.0` and the `packages/required` workspace +entry. The removable manifest noise that the reducer drops includes the +`unused-sdk` dependency, the `unused-test-tool` dev dependency, the unused +`unused` script, the unused workspace entry, and the `unused-transitive` +override. The `engines` block is not consulted by this adapter and is +removable in principle; treat any exact file shape in the minimized payload +as informational rather than a contract. + +Validate the sidecar report and the exported payload fingerprint without +rerunning the failure command: + +```sh +PYTHONPATH=src python3 -m repomin report validate \ + "$out_parent/result.repomin/report.json" \ + --payload "$out_parent/result" --json +``` + +The validator reports `valid: true`, `payload_checked: true`, and +`payload_fingerprint_verified: true` with `payload_fingerprint_mode: "exact"`, +which means the report's recorded tree fingerprint matches the exported +payload byte-for-byte under the `tree-sha256-v2` policy. + +Run the configured oracle independently from the exported payload to confirm +the reduction still fails for the same reason: + +```sh +( cd "$out_parent/result" && python3 reproduce.py ) +``` + +The command exits with status `1` and prints `ORIGINAL_FAILURE` on stderr. +That marker is emitted by the fixture's Python oracle only when +`required-sdk` is still pinned to `1.0.0` and `packages/required` is still +listed in `workspaces`, so the exit status and marker together cover the +required/workspace contract without depending on npm. + +This workflow is adapter evidence for the configured Python oracle, not a +guarantee that an arbitrary minimized `package.json` installs, builds, or +runs as an npm application. To assert anything about a real npm project, you +still need a Node toolchain and a real `npm install` plus lifecycle +verification, both of which are outside this fixture by design. + ## Shrink a Cargo workspace without network access The repository includes a local-only Rust workspace with one required path From 9c83f9783a4422eb8a883d8930d39d7b76506cd7 Mon Sep 17 00:00:00 2001 From: shoaibyazdani Date: Wed, 2 Sep 2026 14:57:13 +0200 Subject: [PATCH 2/2] docs: address review feedback on Node package walkthrough Two prose corrections in docs/EXAMPLES.md: 1. Replace the misleading 'engines block is not consulted... treat exact file shape as informational' sentence with: 'engines block is outside the adapter categories and is preserved unchanged.' 2. Replace the 'matches byte-for-byte' description with one that mentions tree content and recorded metadata matching under the tree-sha256-v2 policy, and notes the transport-friendly content-only fallback as a separate mode. No code, tooling, or other prose touched. --- docs/EXAMPLES.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/EXAMPLES.md b/docs/EXAMPLES.md index 06b02fd..d2ae3ee 100644 --- a/docs/EXAMPLES.md +++ b/docs/EXAMPLES.md @@ -215,9 +215,7 @@ runtime dependency pinned to `1.0.0` and the `packages/required` workspace entry. The removable manifest noise that the reducer drops includes the `unused-sdk` dependency, the `unused-test-tool` dev dependency, the unused `unused` script, the unused workspace entry, and the `unused-transitive` -override. The `engines` block is not consulted by this adapter and is -removable in principle; treat any exact file shape in the minimized payload -as informational rather than a contract. +override. The `engines` block is outside the adapter categories and is preserved unchanged. Validate the sidecar report and the exported payload fingerprint without rerunning the failure command: @@ -230,8 +228,8 @@ PYTHONPATH=src python3 -m repomin report validate \ The validator reports `valid: true`, `payload_checked: true`, and `payload_fingerprint_verified: true` with `payload_fingerprint_mode: "exact"`, -which means the report's recorded tree fingerprint matches the exported -payload byte-for-byte under the `tree-sha256-v2` policy. +which means the exported tree content and recorded metadata match exactly +under the `tree-sha256-v2` policy. The transport-friendly content-only fallback is a separate mode. Run the configured oracle independently from the exported payload to confirm the reduction still fails for the same reason: