Repository navigation
v1.5.0 — typography, 27 scripts, CMYK & PDF/X-4 - #41
Merged
Merged
Conversation
…ge 1.8.0 re-exports; real ICC fixture pdfnative 1.8.0 validates the ICC header (acsp signature, size field), so the 128-byte stub in render-enhancements.test.ts is replaced by the committed synthetic CMYK press profile (tests/fixtures/synthetic-cmyk.icc, structurally valid, colourimetrically meaningless). Lockfile regenerated with npm 11.19.1: npm 10.9.2's arborist fails on a fresh vitest resolution (edgesOut on the peer set); npm ci under npm 10 still works.
…tes, opt-in git hooks, vitest UTC/forks/reporters Ports pdfnative 1.8.0's repository hygiene: tsconfig.scripts.json + typecheck:scripts, eslint allowDefaultProject for scripts/*.mjs, .npmrc (ignore-scripts, fund=false, audit-level=high — now committed), .nvmrc and .node-version at 22 (was lts/iron = Node 20, contradicting engines), .gitattributes (LF everywhere, binaries, linguist-generated), committed .vscode/settings.json (token discipline), .githooks + hooks:install, the scripts/helpers trio (tz, io, cli) and the gate/verify npm scripts.
…e corpus + validators in TypeScript; hardened workflows scripts/gate.ts is the single definition of green (typecheck:all, lint, test[:coverage], build, dist-check, smoke on the BUILT binary, bundle-size budget, verify:docs, test:generate, verify:samples, corpus:pdfa, validate:pdfx, validate:pdfa) with --only/--from/--json/--require-all. The PDF/A corpus generator and veraPDF runner move to .ts with tested pure cores (scripts/lib/verapdf.ts); the corpus is reproducible (fixture key, pinned dates, sha256 per file) and gains a PDF/X-4 triple checked by a new scripts/validate-pdfx.ts over pdfnative's validatePdfX() — veraPDF does not cover PDF/X. docs/assets/ecosystem.json seeds the counts manifest. CI ported from pdfnative 1.8.0: harden-runner on every job, SHA-pinned actions (upload-artifact unified on v7.0.1), persist-credentials: false, npm ci --ignore-scripts, ci.yml runs the gate with --require-all, publish.yml pins npm 11.19.1 on the .nvmrc line, runs the publish gate, publishes with provenance and attests tarball + CycloneDX SBOM in a separate job; composite setup-verapdf with a committed SHA-256 (ROADMAP item 18); new sample-regression, dependency-review, audit and docs workflows; branch/tag rulesets committed; PR template mirrors the new CONTRIBUTING checklist; tests/tools/workflows.test.ts locks all of it.
…, reproducible dates, --font-file, inspect --pdfx/--iso-dates, annotate link, sign --timestamp-timeout, verify weak digest, global flags first render: --pdfx [pdfx4], --output-intent-icc/--output-intent-id (16 MB cap, engine-validated ICC, prtr for PDF/X), --trapped, four typography flags (--split-paragraphs, --keep-headings-with-next, --kerning, --font-features) over a layout.typography passthrough, nested typography/outputIntent merge across JSON / --layout / flags, layout JSON revival (creationDate, iccProfile) on both routes, --layout size cap (ROADMAP 13), the 27-script allow-list with ha/yo/ig/sw → latin aliases, --font-file with a guarded posture (path, 32 MB cap, sfnt magic, parseFontData + validateFontData, ROADMAP 4), fontEntries on the table variant (ROADMAP 17), PDF/X build errors classified E_INPUT from a committed errors.json fixture, envelope pdfx/creationDate fields. Reproducible output: global --creation-date with a SOURCE_DATE_EPOCH fallback (invalid values are usage errors), applied process-wide so batch manifests inherit it; dates are UTC since pdfnative 1.8.0. inspect: --pdfx report and --check pdfx over validatePdfX(), pdfxConformance always present, --summary gains pdfx, --iso-dates (ROADMAP 14). doctor: fonts (31 modules / 27 scripts probed on disk), unicode, conformance checks. annotate: link type with validateURL as the boundary (ROADMAP 5). sign: --timestamp-timeout (ROADMAP 7). verify: RFC 3161 SHA-1 imprint → timestampDigest, weak-digest note, refused under --strict (ROADMAP 11). fetch-guard: 198.18.0.0/15, 192.0.2.0/24, 64:ff9b::/96 (ROADMAP 12). Dispatcher: boolean globals may precede the command name (ROADMAP 15). Governance policy mirror at 1.1.0. Schemas, completions and usage updated; 21 commands / 19 subjects / 12 codes unchanged. Tests: 40 → 63 files, 600 → 821 cases, including a built-binary reproducibility suite and a PDF/X round trip. Known upstream limit recorded in a test: PdfModifier.updateMetadata drops the PDF/X identification.
…ngerprints, initial baseline chain, PDF/X corpus samples/run-all.js (global binary, shell: true, no verification) is replaced by scripts/generate-samples.ts: every samples/render JSON plus the multilang driver scripts and the outputs derived through merge/split/ extract, annotate, fill, metadata, encrypt/decrypt and sign are written into test-output/samples/ by the BUILT CLI under TZ=UTC with the creation instant pinned twice (--creation-date and SOURCE_DATE_EPOCH). The plan table lives in scripts/lib/sample-plan.ts (tested); the drivers honour PDFNATIVE_SAMPLES_OUT and SOURCE_DATE_EPOCH. scripts/lib/sample-fingerprint.ts + scripts/verify-samples.ts (ported from pdfnative 1.8.0) hold the corpus to tests/regression/baselines/ samples.sha256.json: 79 entries, 69 byte-exact, 10 semantic (6 encrypted: CSPRNG file keys; 4 signed: the incremental revision carries a per-revision /ID drawn at signing time). The baseline is a chain with `since` per entry and a provenance note; verified identical across two generator runs. New samples: typography (paragraph breaking, justify/optical/soft hyphens, French spacing + unit binding, kerning/features/metrics), print (CMYK colours, colour bars, PDF/X-4 with the synthetic prtr profile), multilang (Lao; Tai Tham/New Tai Lue/Tai Le/Cham; Hausa/Yoruba/Igbo/Swahili), font (five 1.8.0 scripts, --font-file), reproducible (pinned date twice; the double-render script is the proof), inspect --check pdfx and --iso-dates, doctor capabilities, annotate link, verify weak digest, sign --timestamp-timeout, agent global-flags-first; each as a dual-shell pair. The conformance corpus (16 files) now carries the PDF/X-4 triple checked by validate:pdfx (2 PASS, 1 XFAIL) and the table-variant positive.
…tract in docs/AGENT_CONTRACT.md Ported from pdfnative 1.8.0: CLAUDE.md is now `@AGENTS.md` plus an addendum (token discipline, the gate, hooks and permissions, Windows session notes), .claude/settings.json (Read deny list on the generated bulk directories, the HITL Bash denies, `attribution.commit: ""`), .claude/hooks/guard.mjs (the fail-closed PreToolUse hook refusing publish / push / tag / GitHub writes in every shell segment, substitution and interpreter payload; verbatim, with its .d.mts and tests/tools/guard.test.ts), .claude/rules/ generated from .github/instructions/ by scripts/build-claude-rules.ts (lib/agent-config.ts holds the pure checks), the /release-audit skill adapted to the CLI's surfaces, and .github/prompts/quality-gate.prompt.md. AGENTS.md (16.5 KB, over the 16 KiB context budget) is split: the consumer contract (§1-8, updated for 1.5.0 — additive envelope fields, global flags before the command, reproducible output, PDF/X preflight, the 16-file corpus, the new SSRF ranges and input caps, --font-file posture) moves verbatim to docs/AGENT_CONTRACT.md; AGENTS.md now follows pdfnative's structure (mission, gate, where-is-what, architecture checklist, contract in brief, never touch, generated files, counts, releasing, governance, ecosystem) in 93 lines. .github/copilot-instructions.md is rewritten (it still said "eleven commands" and "Node >= 20"), the three instruction files describe the 1.5.0 surface, and AI_GOVERNANCE_POLICY becomes a verbatim mirror of .github/ai-governance.json (claude_code block included) so `govern policy` prints the whole policy.
…urface derivation, release-prepare docs/assets/ecosystem.json is the single source of every count and version the docs quote. scripts/verify-docs.ts (ported from pdfnative 1.8.0, exit 0/1, --json, --online, --strict, `verify-docs:allow <rule>` markers) holds README, docs/, llms.txt, AGENTS.md, CLAUDE.md, the Copilot files, samples/README.md and the current release note to it. scripts/lib/ cli-surface.ts derives the counts from the constants the CLI runs on (COMMANDS, GLOBAL_FLAGS, SUBJECTS, ErrorCode, MANIFEST_COMMANDS, the corpus and font tables, the samples tree, the baseline) and parses src/index.ts and README for the parity rules; scripts/lib/prose-language.ts is the English-only detector shared with tests/docs/prose-language.test.ts. Rules: manifest-shape (incl. the pdfnative pin and the CLI version vs package.json), derived-counts, stale-token, canonical-present, version-token, count-tokens, command-parity (COMMANDS == USAGE == both index.ts switches == README reference == commandGroups; samples/ dirs are commands), flag-parity (every <NAME>_USAGE flag is in the completion table and vice versa — it found `--conformance` undeclared and a phantom `--data-shaped` in the fill usage), schema-parity, error-parity (ErrorCode == DEFAULT_MESSAGE == the contract docs), governance-embed, sample-shell-parity, claude-md-budget, governance-sources, node-pin-parity, ruleset-parity, agent-config-parity, claude-rules-sync, claude-rules-budget, pr-template-parity, eol-lf (warn until the renormalisation commit), skills-shape, internal-links, verified-on-parity, prose-language. scripts/release-prepare.ts applies a version bump in one pass (package manifests, ecosystem.json + Verified-on stamps, CITATION.cff, the SECURITY table, the README banner tokens, the knowledge-base footer, llms.txt, the release-note scaffold); its pure functions are covered by tests/tools/release-prepare.test.ts. The verifier itself is tested against the real tree (the gate condition) and against a corrupted sandbox copy.
Measured after the 1.5.0 suites (1058 tests across 72 files): statements 84.97 %, branches 74.45 %, functions 92.38 %, lines 86.81 %. Each threshold is min(measured - 2, previous + 3), never below the previous floor; the statements floor is mirrored by declared.coverageStatements in docs/assets/ecosystem.json.
…ng, roadmap, changelog, release note and PR draft README: banner (built on pdfnative 1.8.0), highlights (typography, CMYK & PDF/X-4, reproducible output, 27 scripts & custom fonts, engineered like the engine), the v1.5.0 feature block, PDF/A & PDF/X status (16 corpus files), quick start (typography / PDF/X-4 / reproducible), the samples table (every category, agent scripts, the generator replacing run-all.js), the command reference (render, sign, inspect, verify, doctor, annotate, global options — before or after the command), the agent and security sections. Engine "since" tags are written as `pdfnative >= x.y.z` so verify-docs' version-token rule reads them as floors, not claims. docs/KNOWLEDGE_BASE.md: architecture tree with scripts/ and tests/, the data flow (booleanFlags, splitCommandArgv, setDefaultCreationDate, reviveLayoutJson, classifyBuildError), the 1.8.0 bridge block, the render reference (typography, CMYK and PDF/X-4, reproducible output, --font-file), sign / verify / inspect / annotate / metadata / doctor deltas, the agent contract (additive fields, the 12 codes, summary shapes), the security model (ICC / font validation, --layout cap, link URLs, false PDF/X claims, non-determinism, supply chain), the API mapping, the gate as development reference, the samples table, two FAQ entries, a Verified-on footer. llms.txt (Current version, the 12 codes, the new flags, the reproducibility promise, AGENT_CONTRACT), SECURITY.md (1.5.x / 1.4.x table, validated binary inputs, SSRF ranges, weak digests, Reproducible builds, Supply chain), CONTRIBUTING.md (the gate, samples and the baseline policy, the corpus and validators incl. the Windows JAVACMD recipe, the manifest and verify:docs, the Release procedure), ROADMAP.md (v1.5.0 block; delivered items removed; new upstream gaps: metadata drops the PDF/X identification, signed output carries a per-revision /ID, PDF/X-1a/-3/-4p, PDF/A + PDF/X in one file, hyphenation dictionaries; version-token markers on the release history), CHANGELOG.md (## [1.5.0] – 2026-09-17 plus compare links back to 0.1.0 — roadmap item 16), CITATION.cff, package.json description and keywords, samples/README.md (new categories, the generator section), tests/fixtures/ README.md (ICC and build-error fixture provenance), release-notes/v1.5.0.md and release-notes/draft/PR-v1.5.0.md.
…esults in the PR draft `npx tsx scripts/release-prepare.ts --version 1.5.0 --date 2026-09-17 --previous v1.4.0` run end to end: every manifest, table and banner was already current; the four Verified-on stamps (docs/assets/ecosystem.json, llms.txt, docs/KNOWLEDGE_BASE.md, docs/AGENT_CONTRACT.md) move to the release date. release-notes/draft/PR-v1.5.0.md records the publish gate as it ran: `npx tsx scripts/gate.ts --publish --require-all` — 13 passed, 0 skipped in 308 s (1058 tests, 85.0 % statements, 21 commands smoke-tested on the built binary, 357 KiB bundle, 79 sample PDFs matching the baseline, 16 corpus files: veraPDF 11 PASS + 2 XFAIL, PDF/X 2 PASS + 1 XFAIL).
A dry run emitted its status before the engine builder ran, so a missing PDF/X output intent, an incoherent inline layout or a non-ICC profile passed `--dry-run` and failed the real render (audit A-22). `preflight()` now runs the buffered builder (`buildDocumentPDFBytes` / `buildPDFBytes`, never a stream variant) and discards the bytes: engine coherence errors map to E_INPUT, `--strict` escalations to E_CHECK_FAILED, and the diagnostics reach the dry-run envelope (`dryRun: true`, no `bytes`). `batch --dry-run` inherits it per task. Tests: tests/commands/render-dry-run.test.ts (14 cases) plus one case each in render-pdfx and render-typography; docs: AGENT_CONTRACT §4, README global options, knowledge base, global usage text, commands instructions.
Audit findings A-12/A-13/A-14, A-23, A-30, A-34, A-44, A-45, B-03, B-08, B-09, B-17, B-18: - docs: the typography keys are the engine's `TypographyOptions` verbatim (`fontFeatures`, `punctuationSpacing: "fr" | "fr-CA" | rules[]`; no `features`, `softHyphens` or `justify` key — U+00AD is honoured unconditionally, justification is the paragraph `align`). - inspect: emits `metadata.modDate` (additive; `--iso-dates` covers it, `schema inspect` pins it, the text report prints `Modified:`). - schema status: every emitted envelope field is pinned (31 properties, each command-specific one described with its command); new suite tests/commands/schema-status-parity.test.ts holds the sources to it. - layout: `--output-intent-icc` checks the `acsp` signature in the CLI (E_INPUT), so the docs' claim holds on real and dry runs. - govern: AGENT_RULES_TEXT is `.github/AGENT_RULES.md` verbatim; the `governance-embed` verify-docs rule and a test hold them together. - config: `.pdfnativerc.json` sections work for all 21 commands (KNOWN_COMMANDS derived from the completion table). - fonts: resolve the fonts directory through `pdfnative/package.json` (exported since 1.8.0); stale comment fixed. - AGENT_CONTRACT: `batch` is not a status-envelope writer; `creationDate` is emitted by `render`; policy reference points at an existing anchor (`AGENTS.md#mission-and-constraints`); PR draft flag counts 57 / 23; bug template offers Node 22/24 and `doctor --format json`.
tests/fuzz/{argv,pages,config,manifest,layout,pdf-bytes,reproducible,fonts}
over tests/helpers/fuzz.ts (mulberry32 PRNG with a fixed seed, per-iteration
seed reporting, the "only a CliError with a stable code" invariant, hostile
argv / JSON / page-spec / date generators, PDF byte builders for the xref
/Prev chain, a /Prev cycle, nesting past MAX_PARSE_DEPTH, an inflate bomb
and random mutations). Deterministic; ~3 s. Object.prototype is checked
untouched after every suite.
Source hardenings (audit G1), two of them crashes the suite found:
- args: `--toString x --toString x` read the inherited function as an
existing flag and threw a TypeError; own keys only now. `--__proto__`,
`--constructor`, `--prototype` are usage errors.
- inspect: a structural error while reading the catalog (nesting past the
engine limit) escaped as a raw Error; mapped to E_PARSE like the open.
- layout: `deepMerge` / `isPlainObject` moved from render.ts, exported;
own keys only, `__proto__` / `constructor` / `prototype` skipped, depth
capped at 64 (E_INPUT); `outputIntent.iccProfile` arrays capped at the
16 MiB ICC limit before allocation.
- config: the forbidden keys are skipped in both loops and in
applyConfigDefaults (own-key check).
- manifest: a task flag named like a prototype key is a usage error.
- bridge: MAX_XREF_CHAIN and MAX_PARSE_DEPTH re-exported.
New rule (26th) after internal-links: every `#fragment` a Markdown link targets — same document or another file — is an anchor its target really has, computed the way GitHub does (scripts/lib/markdown-anchors.ts: githubSlug mirrors pdfnative's build-guides slugify; markdownAnchors reads ATX and setext headings, skips fences and comments, suffixes duplicates, adds explicit id/name attributes; fragmentLinks lists the links). The governance policy's `references.*` are checked the same way, which is how audit B-09 (`README.md#zero-dependency`) would have been caught. Corpus: the doc files, CHANGELOG, the PR template, the current release note, the PR drafts and the templates — shipped release notes are frozen history. `verify-docs:allow anchor-parity` opts a line out. Tests: tests/tools/markdown-anchors.test.ts (slug table, setext vs table separators, fences, comments, duplicates, CRLF) and three sandbox cases in tests/tools/verify-docs.test.ts. Docs quote 26 rules.
Audit A-08: the ci / publish profiles ran test:coverage before build, so tests/integration/reproducible-build (spawns dist/cli.cjs) and tests/regression/samples (reads test-output/samples/) were `runIf`-skipped on every fresh CI runner and `--require-all` could not see it. The STEPS table now runs build, dist-check, smoke, bundle-size, bundle-check and test:generate before test:coverage, which carries GATE_REQUIRE_ARTIFACTS=1: under it both suites throw when their input is missing instead of skipping. The fast profile is unchanged (test first, no build); the summary line now prints a skipped count when there is one. Audit G5: new inline step `bundle-check` (scripts/lib/bundle-probe.ts) — the bundle starts with the one shebang, requires `pdfnative` and `pdfnative/tools` externally and nothing else beyond Node built-ins and the allow list, and carries no engine marker, base64 blob, noto-*-data module, PEM block, console.log or attribution trailer. The regex source in src/utils/keys.ts does not trip the PEM check. Tests: tests/tools/bundle-probe.test.ts (synthetic bundle, one case per marker, the real bundle when built), tests/tools/gate.test.ts ordering, profile and env assertions. Docs: the step lists in AGENTS.md, CONTRIBUTING.md, CHANGELOG, the knowledge base, SECURITY.md, ci.yml, the release note's Verification section and testing.instructions.md.
…ts index, contributor paths The parity inventory of the release audit (118 mechanisms compared with the engine) left these applicable gaps: - release-notes/PR_TEMPLATE.md: the section source of the committed release-notes/draft/PR-vX.Y.Z.md bodies (the CLI keeps its PR bodies under version control as the record of what each release claimed and ran); every figure comes from a command, which is how "render flags 44 -> 54" (real: 57) is not written again. - .github/drafts/TEMPLATE.md: an issue draft that passes `pdfnative govern verify-issue`; every other draft in the directory is git-ignored so a draft never lands in a commit by accident. `*.log` ignored too. - .github/prompts/compliance-audit.prompt.md: the engine's audit prompt rewritten for the CLI (process contract, input boundary, network opt-ins, PDF/A and PDF/X gates, dual-shell samples). - scripts/README.md: every script with its npm alias, gate step, flags and exit codes; scripts/tsconfig.json so editors type scripts/ the way typecheck:scripts does. - CONTRIBUTING: "First pull request in ten minutes", "Branch protection" (what the two committed rulesets enforce, why path-filtered workflows are not required checks, the maintainer-only import commands), the PR template in the Release procedure. - overrides.esbuild pinned exactly (0.28.1, what the lockfile already resolves), as the engine does. Waived with a reason in the ledger: THIRD-PARTY-NOTICES.md (the CLI vendors nothing; the bundle keeps the engine external). Rejected by the verifier: the docs.yml call form and the README badge (inside an HTML comment).
CHANGELOG 1.5.0 and release-notes/v1.5.0.md record what the independent audit changed: `render --dry-run` pre-flights the real build, `schema status` pins every emitted field (31 properties), `inspect` emits metadata.modDate, `govern rules` prints .github/AGENT_RULES.md verbatim, .pdfnativerc.json sections apply to all 21 commands, the hostile-input suite and the hardenings it drove, the bundle-check gate step, the release and draft templates, and the audit itself in the Verification section. ROADMAP gains the deferred performance budget (method, not code). AGENTS.md lists tests/fuzz/.
…ag placed first Final review (agent D) findings: - D-01 render refuses a formField.fieldType outside the six engine values with E_INPUT (real run and --dry-run); the engine wrote NaN rectangles for textarea/select. Three samples corrected and rebaselined (declared in the release note). - D-02 splitCommandArgv recovers the command from the known names when a command flag precedes it; arguments with no command exit 2 (E_USAGE). - D-03..D-11 docs and help aligned with the binary (smcp example, modDate, instruction files, stderr reading rule, flag placement), release-audit ledger moved to the git-ignored .audit/, unique temp names in two suites, upstream items in ROADMAP. Tests: 1234 across 85 files.
…sitional; refuse a null block Re-review of ee0fc95: - R-01 a misspelt command is reported as unknown (exit 1) even when a later flag value equals a command name. - R-02 the flag that swallowed the command moves to the end of the command argv, so --pretty schema status prints the status schema. - R-04 blocks: [null] is E_INPUT, not a TypeError. Docs, instruction files, counts (1237 tests) and coverage figures refreshed from the publish gate.
Independent audit ledger and GO verdict in the PR draft; validation figures from the publish gate at b1f87c3 (14 passed, 0 skipped, 1237 tests, 86.0 % statements); maintainer steps extended with the audit countersign and the upstream issues.
…df options Shared helpers for the engine-surface suites: renderJson, diagnosticCodes, inspectLayoutTo, latin1, SYNTHETIC_GRAY_ICC; buildObjectsPdf takes a header and a trailer /ID; patchBytes throws when its marker is absent.
inspect --pdfx is held to the validator's own answer on files render cannot produce: an error, a warning alone (still valid, --check passes), the 1.8.0 /TR rule change, the Hidden exemption, actions/JavaScript/unembedded Form XObject fonts and a halftone warning.
scripts/lib/synthetic-gray-profile.ts writes a 408-byte ICC v2.1 monochrome prtr profile (desc, cprt, wtpt, kTRC), the twin of the engine's synthetic CMYK profile: the Gray output intent and the non-CMYK PDF/X intent that triggers PDFX_DEVICE_CMYK become reachable through the CLI. Committed as tests/fixtures/ and samples/render/print/ copies held to the generator by a test; the v4 variant is never committed.
tests/helpers/diagnostic-triggers.ts holds one minimal trigger per code (9); each is asserted as a warning in the --json envelope and on stderr, and as E_CHECK_FAILED under --strict with nothing written. Newly triggered: PDFA_DEVICE_CMYK_CONTENT, PDFA_DEVICE_CMYK_IMAGE, PDFA_UNEMBEDDED_FORM_FONT, PDFA_ICC_PROFILE_VERSION (silent under pdfa2b), PDFX_DEVICE_CMYK (Gray prtr intent), PDFX_ANNOTATIONS at build time, and the undeclared-feature reason of TYPOGRAPHY_FEATURE_INEFFECTIVE.
…p rules, features One observable assertion per pdfnative 1.8.0 typography option: fr vs fr-CA vs explicit rules (extracted U+202F / U+00A0, base-14 degradation), orphans/widows and splittable / keepWithNext through the --inspect-layout page map, keepHeadingsWithNext with splitParagraphs, soft hyphens, justified extraction, unitBinding, bindShortWords, opticalMargins (Td left of the margin), hyphenationLanguage inert, fontFeatures round-trip (onum) and every tag; metrics exact on the base-14 path, inert under a registered font.
Every SCRIPT_CODES entry is rendered with its own font under --tagged pdfa2b --strict and extracts back (texts from the engine's vetted language documents). Shaping fixes of 1.8.0 observed through the CLI: Devanagari conjuncts from untagged output, reph / Tamil pre-base / Thai sara am keep every letter, pl/tr/vi draw no .notdef, CJK modules, U+061C stripped. Three upstream limits of untagged extraction are pinned with it.fails (Khmer coeng, Myanmar kinzi, Kangxi radicals for zh). Colour emoji: each skin tone, ZWJ sequence and flag is one COLRv1 form; alpha-ramp glyphs stay vector.
…ay intent AcroForm under a PDF/A claim embeds its /DR font (#74) and falls back with a diagnostic without one; --inspect-layout totalPages equals the rendered page count with and without a table of contents (#75); Gray prtr intent validates as PDF/X-4 with /N 1 and /DefaultRGB; printer's marks in a 3 mm bleed stay inside the MediaBox and targets drop below the 6.6 pt strip; TrimBox synthesised from a bleedBox; marks are a page artifact in tagged output; CMYK reaches table, zebra and chart colours in both notations.
pdfnative writes a title, author or subject outside Latin-1 (an em dash is enough) as a UTF-16BE text string. inspect read its NUL bytes as control characters and reported null; compare printed the raw bytes in a metadata difference. utils/pdftext.ts decodes the byte-order-marked forms (UTF-16BE, UTF-8) for both. Found while inspecting the new PDF/X samples.
Twelve documents close the sample side of the pdfnative 1.8.0 surface: an AcroForm under PDF/A-2b; fr-CA spacing, explicit spacing rules, soft hyphens with per-block keepWithNext / splittable; metrics exact in a flag-less base14/ category (the option is inert under a registered font); four script families (el ru ka hy pl tr vi, ar he, hi bn ta, zh ko) so every one of the 27 script codes is rendered by the corpus; colour emoji skin tones, ZWJ sequences and flags; PDF/X-4 under a Gray intent; marks in a 3 mm bleed. Ten dual-shell pairs (print/03, print/04 included), validated under Git Bash and PowerShell. Plan: FILE_ICC replaces the 05-pdfx4 special case. Baseline: 79 -> 91 entries, additions only (since 1.5.0). print/03 chart keys corrected to chartType / label (bytes unchanged). README: rows, tree, the skipped-files and typography-flags statements corrected.
Conformance corpus 16 -> 22 files. PDF/A positives validated by veraPDF 1.30.2: an AcroForm under PDF/A-2b (pdfnative 1.8.0 #74), a Gray output intent (the synthetic Gray profile is accepted), CMYK colours under a CMYK intent. Negative canaries veraPDF rejects: the same form without an embedded font, and a PDF/A-1b render with an ICC v4 profile (written under .specs/ at generation time, never committed). PDF/X-4: a Gray-intent press file. veraPDF: 14 PASS + 4 XFAIL; validatePdfX: 3 PASS + 1 XFAIL. Counts and corpus descriptions updated in every document.
tests/regression/engine-surface.json maps every bullet of the pdfnative 1.8.0 changelog entry to named CLI tests and baseline samples, or to a motivated waiver (LIB, TOOLING, DOCS, tested-upstream with its transmission suite). The suite holds every reference to the tree, requires each diagnostic code the schema names to have an executed trigger, each TypographyOptions key and each of the 27 script codes to appear in a rendered sample, and fails when the pdfnative pin moves without the matrix. Where the engine checkout is present it also proves the matrix complete against the engine changelog.
…se note, changelog, roadmap, PR draft Every mention of the sample count is now machine-checked (N sample PDFs / N-sample baseline tokens, with a sandbox case). CONTRIBUTING gains 'Bumping the engine pin'; the testing instructions describe the engine-surface matrix, the trigger table, the transmission contract, it.fails for upstream limits and the captured()/stdout and invisible-character gotchas (rules regenerated). KNOWLEDGE_BASE documents the nine diagnostics with their trigger and fix, the Gray PDF/X intent, the base-14 scope of metrics exact. ROADMAP records the upstream limits found (untagged extraction of shaped scripts, table of contents pagination, malformed block shapes). CHANGELOG, release note (additive baseline declared) and PR draft describe the coverage closure. 1387 tests across 96 files.
Figures of the publish gate at d4d8530: 14 passed, 0 skipped — 1387 tests, 86.06 % statements / 75.91 % branches / 92.59 % functions / 87.92 % lines, 91 sample PDFs, 22 corpus files (veraPDF 14 PASS + 4 XFAIL, validatePdfX 3 PASS + 1 XFAIL), bundle 368 KiB, npm audit clean.
…ag sanitisation in the slugger Found by the first CI run (Linux runners) and by CodeQL: - defaultFontName() used node:path, which only splits on the host separator: C:\fonts\a.ttf named the font 'a' on Windows and 'c-fonts-a' on Linux (tests/utils/fonts.test.ts failed on ubuntu). Both separators now end a directory on every platform; the name is a pure function of the string. - scripts/lib/markdown-anchors.ts: tags are recognised by their leading letter, and the brackets a single pass can leave behind are removed where the tags are (js/incomplete-multi-character-sanitization). Same slugs; 'a < b and c > d' is no longer read as a tag. 1390 tests across 96 files.
CodeQL js/incomplete-multi-character-sanitization still reported githubSlug(): the query targets the single-pass removal of a multi-character pattern itself, whatever follows it. stripTags() replaces it with one left-to-right scan that drops '<' + optional '/' + letter ... '>' spans and every remaining angle bracket, so its output can hold neither '<' nor '>' for any input. Same slugs. Tests: a case table, a 2000-case seeded property (no bracket in the output, idempotent) and a linearity check on hostile input. 1403 tests across 96 files.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
v1.5.0 — typography, 27 scripts, CMYK & PDF/X-4
Summary
Aligns the CLI with pdfnative 1.8.0 in both directions: every 1.8.0 engine feature is
exposed (typography engine, CMYK colours + colour bars, PDF/X-4 with a structural
validator, 27 Unicode scripts +
latinaliases, custom fonts from disk, UTC and pinnablecreation dates), every roadmap item the engine unblocked is delivered (global flags before
the command,
annotate link,sign --timestamp-timeout,verifyweak-digest note,inspect --iso-dates, richerdoctor, SSRF ranges,--layoutcap, table-variant fonts,CHANGELOG compare links), and the repository adopts the engine's engineering without
reinventing it: one quality gate, a byte-exact sample baseline, a PDF/A + PDF/X conformance
corpus, hardened CI with Trusted Publishing and attestations, a documentation verifier and a
committed Claude Code layer.
Counts: 21 commands, 19 schema subjects, 12 stable error codes and 14 manifest commands
unchanged; global flags 9 → 10 (
--creation-date);renderflags 44 → 57;inspect14 → 16;
sign21 → 23;--font22 → 27 scripts (+ 4 aliases);--strictdiagnostics3 → 9;
doctorchecks 5 → 8; conformance corpus 12 → 22 files; workflows 5 → 9;tests 600 → 1403 across 96 files.
Changes
Engine surface (
src/core-bridge/index.ts,src/commands/render.ts,src/utils/)(pdfnative 1.8.0):PDF_X_CONFORMANCE_TARGETS,validatePdfX,setDefaultCreationDate/getDefaultCreationDate,validateURL,USE_UNICODE_VERSION,validateFontData,parseFontData(pdfnative/tools) + the 1.8.0 types.utils/layout.tsrewritten:reviveLayoutJson(attachments, ICC arrays,creationDate),mergeNestedLayout(typography,outputIntent),parsePdfx,parseTrapped,buildOutputIntentFromFlags(16 MiB cap,acspcheck),buildTypographyFromFlags,PDF/X × PDF/A and PDF/X × encryption pre-checks, 50 MB cap on
--layout.utils/fonts.ts(new):BUNDLED_FONT_MODULES(31),SCRIPT_CODES(27),FONT_ALIASES,applyFontFlags,buildFontEntriesForLangs(document + table variant),loadCustomFontsfor--font-file(path check, 32 MiB cap, magic bytes,parseFontData+validateFontData, name collision guard).utils/reproducible.ts(new): strict--creation-date/SOURCE_DATE_EPOCHresolution,applied once in
index.tsafter the config merge (process-wide,batchinherits).utils/build-errors.ts(new):classifyBuildErrormaps the engine's PDF/X, print,OutputIntent, attachment and watermark coherence messages to
E_INPUT(fixturetests/fixtures/pdfnative-build-errors.json, engine 1.8.0).utils/args.ts(booleanFlags,GLOBAL_BOOLEAN_FLAGS) +utils/argv.ts(
splitCommandArgv): global flags before the command.utils/pdfdate.ts(new):pdfDateToIsoforinspect --iso-dates.utils/fetch-guard.ts: 198.18.0.0/15, 192.0.2.0/24, 64:ff9b::/96 blocked.utils/governance.ts:AI_GOVERNANCE_POLICYis now the verbatim 1.1.0 policy.Commands
render:--pdfx,--output-intent-icc,--output-intent-id,--trapped,--font-file,--split-paragraphs,--keep-headings-with-next,--kerning,--font-features; 27 scripts + aliases; envelopepdfx/creationDate; 9--strictcodes;
--variant tableembeds fonts.inspect:--pdfx,--check pdfx,pdfxConformance,--iso-dates, summarypdfx,PDF/X:text lines.annotate:linktype (buildLinkBodyaftervalidateURL).sign:--timestamp-timeout <ms>→createTsaProvider(url, { timeoutMs }),timestamp.timeoutMsin both envelopes.verify:timestampDigest,WEAK_DIGEST_NOTE,digestOkunder--strict.doctor:fonts,unicode,conformancechecks.schema/completion: every new flag and field;SUBJECTSexported;manifestPATH_FLAGS +=
output-intent-icc,font-file.index.ts: usage texts (Conformance / Typography / Fonts blocks,--creation-date,docs/AGENT_CONTRACT.mdpointer);fillusage no longer names a phantom flag.Tooling (
scripts/)gate.ts(STEPS + fast / ci / publish,--only,--json,--require-all),validate-pdfa.ts,generate-pdfa-corpus.ts,validate-pdfx.ts,lib/{verapdf,pdfx, pdfa-corpus}.ts(22 entries),helpers/{tz,io,cli}.ts.generate-samples.ts+generators/{render,drivers,derived}.ts+lib/sample-plan.ts(replaces
samples/run-all.js),lib/sample-fingerprint.ts+verify-samples.ts(chained baseline, semantic mode for encrypted and signed samples, identical groups).
verify-docs.ts(26 rules) +lib/{cli-surface,agent-config,prose-language}.ts,release-prepare.ts,build-claude-rules.ts,install-git-hooks.mjs.docs/assets/ecosystem.json— the single source of every count and version.CI / repository (
.github/, root)ci,publish(Trusted Publishing, npm 11.19.1, publish gate, SBOM +attestations, release upload),
verapdf(composite action + SHA-256 checksum),sample-regression,dependency-review,audit,docs,codeql,scorecard—harden-runner, SHA pins,
persist-credentials: false,npm ci --ignore-scripts..github/rulesets/{main,tags}.json,dependabot.yml(ignore@types/nodemajors),pull_request_template.md(mirrors CONTRIBUTING §Pull Request Checklist),prompts/quality-gate.prompt.md,instructions/*refreshed,copilot-instructions.mdrewritten (it still said "eleven commands" and "Node ≥ 20"),
ai-governance.json1.1.0..npmrc,.nvmrc/.node-version= 22,.gitattributes,.githooks/,.vscode/settings.json,tsconfig.scripts.json,vitest.config.ts(TZ=UTC, forks,gate JSON report),
package.json(scripts, overrides, description, keywords).Agent layer
docs/AGENT_CONTRACT.md(consumer contract, moved out of AGENTS.md),AGENTS.md(repository rules, pdfnative structure, 9.8 KB),
CLAUDE.md=@AGENTS.md+ addendum,.claude/settings.json,.claude/hooks/guard.mjs+.d.mts,.claude/rules/(generated),
.claude/skills/release-audit/.Samples and tests
render/typography/(4),render/print/03-05+synthetic-cmyk.icc,render/multilang/05-07,render/font/04-05,render/reproducible/,inspect/09-10,doctor/02,annotate/02,verify/07,sign/10,agent/05; multilang drivers honourPDFNATIVE_SAMPLES_OUT/SOURCE_DATE_EPOCH;tests/regression/baselines/samples.sha256.json(91 sample PDFs).tests/helpers/cli-harness.ts, per-featurecommand suites, utils,
integration/{pdfx-roundtrip,reproducible-build},tools/{gate,verapdf,pdfx,workflows,sample-plan,verify-docs,cli-surface,agent-config, build-claude-rules,release-prepare,guard},regression/samples,docs/prose-language.Documentation
start, samples table, command reference, agents, security),
docs/KNOWLEDGE_BASE.md,llms.txt,SECURITY.md,CONTRIBUTING.md(gate, baseline policy, corpus, Release),ROADMAP.md(v1.5.0 block; re-triaged future items incl. the new upstream gaps),CHANGELOG.md(1.5.0 entry + compare links back to 0.1.0),CITATION.cff,samples/README.md,tests/fixtures/README.md,release-notes/v1.5.0.md.Independent audit
Method of
.claude/skills/release-audit/applied on the branch before this PR: twoindependent auditors, an adversarial verifier, the fixes, a final reviewer and a re-review of
the final fixes. Every finding carries a reproducible command; the working reports stay out
of the tree (git-ignored
.audit/). The maintainer's own/release-audit release-notes/v1.5.0.md v1.4.0countersigns this before merge.AGENT_CONTRACT checked against the code and the built binary.
.github/, scripts, tests,.claude/, docs, supply chain) + the agent surfaces.8 minor, 1 note.
2 majors, both fixed; re-review: all D fixes hold, 2 minor residues + 1 note fixed.
render --dry-runreturned before the engine builder: no coherence error, no diagnosticsd2df525— the real buffered build runs in memory, bytes discardedlayout.typography.features/softHyphens/justifyand an object form ofpunctuationSpacing; none exists in the engine3cddfb3—fontFeatures, paragraphalign,'fr' | 'fr-CA' | rule[]schema statuspinned 9 of the emitted envelope fields3cddfb3— 31 properties pinned + an emit ↔ schema parity testrunIfsuites skipped silentlyf795e20— build and samples first,GATE_REQUIRE_ARTIFACTS=1formField.fieldType: "textarea"(3 samples, docs) is not an engine type:NaNrectangles,fillrefused the PDFee0fc95—renderrefuses unknown types (E_INPUT), samples corrected and rebaselinedee0fc95,b1f87c3— recovered before the first positional; no command → exit 2acspcheck attribution,batchenvelope wording,inspectmodDate, config sections for 21 commands,govern rules= AGENT_RULES.md verbatim, dead anchor, flag counts, Node version in the bug template3cddfb3ligaexample, ROADMAP wording,--iso-dateshelp, instruction files vs binary, kerning note, stderr last-line rule, ledger under a read-denied path, temp-name collisionee0fc95--pretty schema statusprinted another subject;blocks: [null]raised aTypeErrorb1f87c3exportsmap3cddfb3anchor-parityrule,bundle-checkgate step01cb2d3,a11c891,f795e20scripts/README.md,scripts/tsconfig.json, exact esbuild override, ignored logs4fec43fTHIRD-PARTY-NOTICES.mdbundle-check)bench/Rejected by the verifier: the
docs.ymlcall form, the README badge placeholder (inside anHTML comment), one duplicate claim. Known and accepted: R-03 — a boolean command flag
followed by two command names (
--pretty schema render) is ambiguous; AGENT_CONTRACT §1tells agents to write command flags after the command. One intermittent failure of the
live-tree
verify-docstest was seen twice undergate --fastwhile files were beingedited and not reproduced in 11 consecutive full runs on a quiet tree.
Verdict: GO — no open blocker, every major has a commit, publish gate green (below).
Engine-surface coverage closure
After the audit, every user-facing bullet of the pdfnative 1.8.0 changelog was mapped to the
CLI's tests and samples (
tests/regression/engine-surface.json, 85 items: tests + samples, or amotivated waiver). The mapping found about thirty gaps — four 1.8.0 fixes with no CLI coverage
(AcroForm
/DRfont under PDF/A,--inspect-layoutwith a table of contents,fr≡fr-CA,marks clearance), five of nine diagnostic codes never triggered, 14 of 27 script codes never
rendered with their font,
metrics: "exact"inert in its own sample — all closed:--tagged pdfa2b --strict; a transmission contract forvalidatePdfXon crafted PDFs.additions only. Conformance corpus 16 → 22 (veraPDF: form under PDF/A-2b, Gray and CMYK
intents pass; unembedded form font and ICC v4 under PDF/A-1b are rejected).
prtrICC profile (scripts/lib/synthetic-gray-profile.ts).inspect/compareand UTF-16/Infostrings.it.fails(untagged extraction of Khmer / Myanmar stacksand of CJK ideographs), plus two recorded in ROADMAP.md (a long table of contents does not
paginate; a malformed chart series raises a
TypeError). No CLI workaround.Validation (what actually ran on the release branch, Windows 11, Node 22.17.0)
npm run typecheck:all→ clean (three configs).npm run lint→ clean.npm run test:coverage→ 1403 / 1403 passing across 96 files; coveragestatements 86.06 % / branches 75.91 % / functions 92.59 % / lines 87.92 %
(thresholds raised 79/68/83/79 → 82/71/86/82,
min(measured − 2, current + 3)).npm run verify:docs→ 26 rules across the documentation corpus, 0 errors(156
eol-lfwarnings, shrinking as touched files normalise: CRLF blobs pending the maintainer's renormalisation commit).npm run build && npm run test:generate→ 91 sample PDFs, byte-identical across two runs;npx tsx scripts/verify-samples.ts --strict→ green.npm run corpus:pdfa && npm run validate:pdfx→ 22 files; PDF/X 3 PASS + 1 XFAIL.npm run validate:pdfawith veraPDF 1.30.2 (portable) + JDK 13 (JAVACMD) →14 PASS + 4 XFAIL + 4 SKIP (the PDF/X files), exit 0.
npx tsx scripts/gate.ts --publish --require-allatd4d8530→ 14 passed, 0 skippedin 437 s (typecheck:all 26 s, lint 10 s, build 10 s, dist-check, smoke — 21 commands —,
bundle-size 368 KiB of the 448 KiB budget, bundle-check — 2 externals —, test:generate
44 s — 91 sample PDFs —, test:coverage 130 s — 1403 tests, 86.1 % stmts —, verify:docs 8 s,
verify:samples 10 s, corpus:pdfa 30 s — 22 files —, validate:pdfx 11 s, validate:pdfa 158 s).
--version1.5.0;doctor --json(pdfnative 1.8.0, fonts31/27, unicode, conformance); PDF/X-4 render →
inspect --check pdfxexit 0 →annotatelink →--check pdfxexit 1; identical SHA-256 underTZ=Europe/Parisand
TZ=UTC, and viaSOURCE_DATE_EPOCH;pdfnative --json --dry-run render ….npm audit→ 0 vulnerabilities.node .claude/hooks/guard.mjsrefusesgit push(stdin test in
tests/tools/guard.test.ts).docs.yml --online.Backward compatibility
field is additive and pinned by
schema status;schema$idmoves with the version./ActualText, hintingtables) — spec-valid output, not byte-identical to 1.4.0; documented in the release note
and CHANGELOG Compatibility sections.
samples/run-all.jsremoved (a repository script, never part of the npm surface).npm ci --ignore-scripts/.npmrc ignore-scripts=truedisablesprepublishOnlylocally;the gate builds explicitly.
Out of scope (tracked in ROADMAP.md)
metadatakeeping the PDF/X identification; reproducible signed output (per-revision/ID); PDF/X-1a / -3 / -4p and spot colours; PDF/A + PDF/X in one file — all upstream.optimize/ linearisation; visualcompare; category help commands; man pages;positional arguments in manifest tasks.
Human-in-the-loop — steps for the maintainer
git add --renormalize .on this branch (then flipEOL_LF_MODEto'fail'inscripts/lib/agent-config.ts) — the agent never runs it (guard hook).release/v1.5.0, open this PR with this body; required checksci (22),ci (24),sample-regression(import.github/rulesets/*.jsonviagh api repos/Nizoka/pdfnative-cli/rulesets --method POST --input …once; keepverapdfanddocsunrequired — path-filtered).npm-publishenvironment (required reviewer), link npm Trusted Publishingto
publish.yml+ that environment, enable the dependency graph, close or merge theopen Dependabot PRs superseded by the pinned versions.
release: v1.5.0 — typography, 27 scripts, CMYK & PDF/X-4, tagv1.5.0on the merge commit, publish the GitHub Release withrelease-notes/v1.5.0.md, approve the environment; thennpm view pdfnative-cli version, a manualdocs.yml --onlinerun; at J+14 consideregress-policy: blockonpublish.yml./release-audit release-notes/v1.5.0.md v1.4.0in Claude Code(ledger under
.audit/1.5.0/) before the merge.pdfnative govern verify-issue):untagged extraction (U+FFFD for Khmer / Myanmar stacks, Kangxi radicals for CJK); a long
table of contents does not paginate; a chart series without
labelraises aTypeError;a Gray synthetic profile generator to sit next to the CMYK one; export
decodePdfTextString;formField.fieldTypeis not validated (NaNrectangles);updateMetadatadrops thePDF/X identification; the signed revision
/IDignores the pinned creation instant;kerning on untagged output leaves a stray space in extracted text.
docs/guides/cli.md,docs/data/surfaces.json(
pdfnative-cligaps are closed) anddocs/assets/ecosystem.json(cli 1.5.0, pin^1.8.0) — an alignment PR after publication.Self-review checklist
console.loginsrc/; all output viaprocess.stdout.write/process.stderr.write.signfailures stayFailed to sign PDF..--output-intent-icc,--font-file,--layout); fonts and profiles never loaded from JSON.--dry-runnevertouches the network;
--timestamp-timeoutonly bounds an existing opt-in.any;readonlywhere applicable; ESM-first with.jsimports.pdfnativesymbol goes throughsrc/core-bridge/index.ts.pdfnativeis still the only runtime dependency (tsxis dev-only).completion.tsand its usage text (flag-parity);every new envelope field in
schema.ts(schema-parity).Co-Authored-By/ generated-with trailer.🤖 Generated with Claude Code