qpdf-compress 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ## [Unreleased]
 
+## [0.8.1] - 2026-09-23
+
+### Fixed
+
+- **The release workflow published releases without their prebuilt binaries.** `gh release create <tag> <assets>` publishes the release and then uploads, and GitHub's immutable releases reject an upload to a published release — with a 422 that `gh` does not surface, so the step went green with nothing attached. `install.mjs` reads the prebuilts off the release, so every consumer of such a version is sent to a source build. The release is now created as a draft with the tarballs attached and published afterwards, and a following step fails the job unless every artifact made it onto the release. **0.8.0 is affected and should be skipped** — it installs only where a C++ toolchain is present. It is deprecated on npm in favour of this release.
+
+### Added
+
+- `npm run verify:pdfa` — a PDF/A conformance harness. It validates `compress()` output against veraPDF, the reference validator, over a real ZUGFeRD PDF/A-3a invoice, and compares the failing clauses to a recorded baseline (`scripts/pdfa-baseline.json`), failing on any difference in either direction so that neither a regression nor an improvement passes unnoticed. CI runs it on Linux / Node 22. veraPDF is GPL-3.0 / MPL-2.0 and is run as an external container pinned by digest — never vendored or linked. Groundwork for [#35](https://github.com/xonaman/nodejs-qpdf-compress/issues/35).
+
 ## [0.8.0] - 2026-09-23
 
 ### Fixed

package/README.md

@@ -160,7 +160,7 @@ Compresses a PDF document. Automatically repairs damaged PDFs.
 | `options.stripAttachments` | `boolean`          | Remove embedded file attachments. Default: `true`                   |
 | `options.output`           | `string`           | Write to file path instead of returning a `Buffer`                  |
 
-> **Hybrid invoices (ZUGFeRD / Factur-X)**: the invoice XML rides along as an attachment, so the defaults remove it. Pass `stripAttachments: false` to keep the attachment and every path readers look it up through. The result is still not a conforming PDF/A-3 — output intents and structure information are dropped in every mode, and XMP metadata too unless `stripMetadata: false` — so a file that has to stay conformant should not be compressed at all.
+> **Hybrid invoices (ZUGFeRD / Factur-X)**: the invoice XML rides along as an attachment, so the defaults remove it. Pass `stripAttachments: false` to keep the attachment and every path readers look it up through. The result is still not a conforming PDF/A-3 — output intents and structure information are dropped in every mode, and XMP metadata too unless `stripMetadata: false` — so a file that has to stay conformant should not be compressed at all. That is measured, not assumed: `npm run verify:pdfa` validates the output against veraPDF over a real PDF/A-3a invoice, and `scripts/pdfa-baseline.json` records exactly which clauses fail.
 
 **Both modes:**
 

package/THIRD-PARTY-NOTICES.md

@@ -42,3 +42,15 @@ Copyright Jean-loup Gailly and Mark Adler. Licensed under the zlib License.
 zlib provides DEFLATE compression and is statically linked into the Windows
 build (via vcpkg); on macOS and Linux the system zlib is used at build time.
 See <https://github.com/madler/zlib/blob/master/LICENSE>.
+
+## Development and test material
+
+Neither of the following is distributed in the npm package: the fixture lives under `test/`, which is excluded from the package `files` list, and veraPDF is invoked as an external tool in its own container rather than vendored or linked.
+
+### `test/fixtures/pdfa3-invoice.pdf`
+
+A real ZUGFeRD 2.1 (EN 16931) PDF/A-3a invoice, used by `npm run verify:pdfa` to measure the PDF/A conformance of compression output. Taken unmodified from the [ZUGFeRD/corpus](https://github.com/ZUGFeRD/corpus) project (Apache-2.0), path `ZUGFeRDv2/correct/symtrax/Beispiele/EN16931/zugferd_2p1_EN16931_AbweichenderZahlungsempf.pdf`, SHA-256 `a4b903d4e508a80d65276f030d0fbeab5081d62c2c2b19ffd2f13bcdae37c564`.
+
+### veraPDF
+
+Copyright the veraPDF Consortium. Licensed under the GNU General Public License v3 or the Mozilla Public License v2. The reference PDF/A validator, run by `npm run verify:pdfa` from the `verapdf/cli` container image, pinned by digest in `scripts/pdfa-baseline.json`. See <https://github.com/veraPDF/veraPDF-apps>.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qpdf-compress",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Native PDF compression for Node.js, powered by QPDF",
   "license": "Apache-2.0",
   "type": "module",
@@ -77,6 +77,7 @@
     "download:qpdf": "node scripts/download-qpdf.mjs",
     "download:harfbuzz": "node scripts/download-harfbuzz.mjs",
     "verify:checksums": "node scripts/verify-checksums.mjs",
+    "verify:pdfa": "tsc && node scripts/verify-pdfa.mjs",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",

package/scripts/pdfa-baseline.json

@@ -0,0 +1,23 @@
+{
+  "image": "verapdf/cli@sha256:d5ee329657cf9bc4b2400392dd54c7d0a0ce9980ff6fa2da5590eebeec007cdb",
+  "flavour": "3a",
+  "fixture": "pdfa3-invoice.pdf",
+  "variants": {
+    "original": {
+      "compliant": true,
+      "failedRules": []
+    },
+    "default": {
+      "compliant": false,
+      "failedRules": ["6.1.7.1-2", "6.2.4.3-2", "6.2.4.3-4", "6.6.2.1-1", "6.7.2.2-1", "6.7.3.3-1"]
+    },
+    "keep-attachments": {
+      "compliant": false,
+      "failedRules": ["6.1.7.1-2", "6.2.4.3-2", "6.2.4.3-4", "6.6.2.1-1", "6.7.2.2-1", "6.7.3.3-1"]
+    },
+    "keep-both": {
+      "compliant": false,
+      "failedRules": ["6.1.7.1-2", "6.2.4.3-2", "6.2.4.3-4", "6.7.3.3-1"]
+    }
+  }
+}

package/scripts/prebuilds.json

@@ -1,11 +1,11 @@
 {
-  "darwin-arm64": "91bce035bd98d4c5b51eb3c43bb4b3f1734768d4edb47042cce4dbb7b73bd001",
-  "darwin-x64": "fe1fdd42d8ff24e5ed3777ced647d29f9878d0dde347b3925af3b388d49f4e15",
-  "linux-arm": "478c10a51adefddc6f4cccc580edcb0d2242e8b155d495aac6ae2dc57ec96c10",
-  "linux-arm64": "6f09b7b95ffdb382430e8d474fdad4664058210863668e85130d5f76d157796e",
-  "linux-musl-arm64": "aee2f73320bb8d911be2dbfd657fd36ad7d767f27e5257fd8060d8c53b930c37",
-  "linux-musl-x64": "0fa4510d0aac780f955880bf511e086b9c88af97f87d348f97569859d65d191d",
-  "linux-x64": "75b2b183f810af513c7905406c695e325b39d5ef6125a8845465b75985515f0d",
-  "win32-arm64": "fbac6517c8ea188ea9cfb72c5daac0e6b90a5cb8e185a6e1cf7dff116b4ff032",
-  "win32-x64": "6b0a6f16c5cbe881aa3b4da12dcd138a637cf0b6764505a0e82a8b23df4d48d9"
+  "darwin-arm64": "6835d46768f1fc7366bbc60818dff396ca03c8ffb59b80e94454ca9dd5104fbf",
+  "darwin-x64": "dc222533f2ece1d5295f40f354a7fdd0846c2141a94ece211151cee6ceb45f70",
+  "linux-arm": "a0458de5782d4f900fba4de00cad8a678eb0a416d6cfbb153e82002446e941aa",
+  "linux-arm64": "ee25a8cd3ec974e6055206ecdfa96a5e5d4bc218885640b5739b149b734fe022",
+  "linux-musl-arm64": "f95653c36036947378834fa5715a55dd4ab8b0b6245a8bee95b91b280d3dda2b",
+  "linux-musl-x64": "7fdc5b849c9d4c8c7518490c274a1814c612b999e5752521f56b9e2253a9f37f",
+  "linux-x64": "a75e4213e1309ee49ed91d0c1e5aa591954db2c84fae0768fb1ec718a65b4a11",
+  "win32-arm64": "30d895806eec45f194c89b3fc1b521de164b1a2dd91adb8a7a939254baa0100d",
+  "win32-x64": "9b294de489115c6f8cb5733db260c12904f956e1ec30275776fc29cfcab600dc"
 }

package/scripts/verify-pdfa.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * Validates the PDF/A conformance of compress() output against a recorded baseline.
+ *
+ * veraPDF is the reference PDF/A validator. It is GPL-3.0 / MPL-2.0, so it is neither
+ * vendored nor linked — it runs as an external tool in its own container, pinned by
+ * digest so a verdict cannot drift under us when the image is rebuilt.
+ *
+ * The baseline records which clauses each variant fails today. Any difference, in
+ * either direction, fails the run: a regression and an improvement both need the
+ * baseline updated deliberately (`--update`) rather than silently absorbed.
+ *
+ * Usage: npm run verify:pdfa [-- --update]
+ */
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { compress } from '../dist/index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, '..');
+const baselinePath = join(__dirname, 'pdfa-baseline.json');
+const baseline = JSON.parse(readFileSync(baselinePath, 'utf8'));
+const update = process.argv.includes('--update');
+
+// the work directory must sit inside the repo: Docker Desktop shares the user's
+// own tree, not every host temp path
+const workDir = join(root, '.cache', 'pdfa');
+
+const variants = {
+  original: null,
+  default: {},
+  'keep-attachments': { stripAttachments: false },
+  'keep-both': { stripAttachments: false, stripMetadata: false },
+};
+
+function veraPdf(name) {
+  const args = [
+    'run',
+    '--rm',
+    '--platform',
+    'linux/amd64',
+    '-v',
+    `${workDir}:/data`,
+    baseline.image,
+    '--flavour',
+    baseline.flavour,
+    '--format',
+    'mrr',
+    `/data/${name}.pdf`,
+  ];
+  let xml;
+  try {
+    xml = execFileSync('docker', args, { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+  } catch (err) {
+    // veraPDF exits non-zero for a non-compliant file; the report is still on stdout
+    if (typeof err.stdout !== 'string' || !err.stdout.includes('<validationReport')) throw err;
+    xml = err.stdout;
+  }
+  const compliant = /<validationReport[^>]*isCompliant="true"/.test(xml);
+  const failed = [
+    ...new Set(
+      [
+        ...xml.matchAll(
+          /<rule\b[^>]*\bclause="([^"]+)"[^>]*\btestNumber="([^"]+)"[^>]*\bstatus="failed"/g,
+        ),
+      ].map((m) => `${m[1]}-${m[2]}`),
+    ),
+  ].sort();
+  return { compliant, failedRules: failed };
+}
+
+try {
+  execFileSync('docker', ['version', '--format', '{{.Server.Version}}'], { stdio: 'ignore' });
+} catch {
+  console.error('Docker is required to run veraPDF. Start Docker and try again.');
+  process.exit(1);
+}
+
+rmSync(workDir, { recursive: true, force: true });
+mkdirSync(workDir, { recursive: true });
+
+const fixture = readFileSync(join(root, 'test', 'fixtures', baseline.fixture));
+writeFileSync(join(workDir, 'original.pdf'), fixture);
+for (const [name, options] of Object.entries(variants)) {
+  if (!options) continue;
+  await compress(fixture, { ...options, output: join(workDir, `${name}.pdf`) });
+}
+
+const results = {};
+let failures = 0;
+
+for (const name of Object.keys(variants)) {
+  const actual = veraPdf(name);
+  results[name] = actual;
+
+  const expected = baseline.variants[name];
+  const same =
+    expected &&
+    expected.compliant === actual.compliant &&
+    expected.failedRules.join() === actual.failedRules.join();
+
+  const verdict = actual.compliant ? 'PASS' : `FAIL (${actual.failedRules.length})`;
+  console.log(
+    `${same || update ? ' ok ' : 'DIFF'}  ${name.padEnd(17)} ${verdict.padEnd(9)} ${actual.failedRules.join(' ')}`,
+  );
+
+  if (!same && !update) {
+    failures++;
+    console.log(
+      `      expected: ${expected ? `${expected.compliant ? 'PASS' : 'FAIL'} ${expected.failedRules.join(' ')}` : '(no baseline entry)'}`,
+    );
+  }
+}
+
+if (update) {
+  writeFileSync(baselinePath, `${JSON.stringify({ ...baseline, variants: results }, null, 2)}\n`);
+  // keep the committed file canonical so the pre-commit hook has nothing to say
+  try {
+    execFileSync('npx', ['prettier', '--write', baselinePath], { stdio: 'ignore' });
+  } catch {
+    // prettier is a devDependency; a missing one is not worth failing the run over
+  }
+  console.log(`\nBaseline updated: ${baselinePath}`);
+  process.exit(0);
+}
+
+if (failures) {
+  console.error(
+    `\n${failures} variant(s) differ from the baseline. Re-run with --update once the change is intended.`,
+  );
+  process.exit(1);
+}
+console.log('\nAll variants match the recorded baseline.');