Reproduce the StockControls offline PDF dependencies
==================================================

This folder is source/build documentation for developers and reviewers. It is
not a WordPress feature or an installer. The plugin and PDF export never load,
invoke or execute anything in development/pdf-dependencies/. Runtime exports
use only the already bundled readable vendor tree and local font.

The five included files are byte-identical to the maintained development copies
in tools/pdf-dependencies/: rebuild.py, composer.json, composer.lock, NOTICE.txt
and this README.txt. No private repository or separate source download is needed
to run the exact dependency transformation used for this plugin.

Developer requirements
----------------------
Use a separate development directory outside any public web root. You need
Python 3, PHP CLI 8.2 or newer on PATH as php, the PHP extensions required by the
locked packages (including mbstring and GD), and ZIP extraction support for
Composer (PHP zip or an installed unzip/7z program). PHP 8.2+ is a build-tool
requirement, not an increase to the plugin's PHP 7.4 runtime minimum.

An explicit rebuild needs network access to the official Composer, GitHub and
Packagist dependency-download endpoints. It downloads Composer 2.10.3 and
PHP-Scoper 0.18.19 and verifies their pinned SHA256 digests before execution.
Composer installs the exact composer.lock versions/revisions with development
dependencies, Composer plugins and Composer scripts disabled. Downloaded tools
and upstream archives remain in the chosen private work directory; they are not
part of the installed plugin. No global package installation is performed.

Build from an extracted plugin ZIP
---------------------------------
From the extracted stockcontrols-inventory-operations directory, run the command
below. Replace both output paths with new, distinct paths that do not exist.
The recipe refuses existing --work or --output directories; it does not modify
the installed/extracted vendor tree or publish anything.

python3 development/pdf-dependencies/rebuild.py \
  --work /path/to/new-private-pdf-work \
  --output /path/to/new-rebuilt-pdf-vendor

The command prefixes the readable sources with StockControlsPDFVendor, applies
the narrowly documented namespace/polyfill corrections, embeds only DejaVu Sans,
retains upstream license/attribution data, and omits unused development content.
Case-insensitive directory matching covers Test/tests and developer folders;
explicit exclusions cover the unused HTTP helper and Psalm development loader.
The exact six removed PHP files are asserted for this pinned dependency set.
The work directory's result.json records each final member's SHA256 and the
removed development files. NOTICE.txt documents versions, upstream references,
licenses, font hash and all adaptations.

Verify the output
-----------------
From the same extracted plugin directory, compare the complete rebuilt tree
against the shipped vendor tree with this Python command. Both member names and
file bytes must match. It writes nothing to either tree.

python3 - /path/to/new-rebuilt-pdf-vendor vendor/stockcontrols-pdf <<'PY'
from pathlib import Path
import hashlib, sys
def snapshot(root):
    root = Path(root)
    if not root.is_dir():
        raise SystemExit('Missing directory: ' + str(root))
    return {str(p.relative_to(root)): hashlib.sha256(p.read_bytes()).hexdigest()
            for p in root.rglob('*') if p.is_file()}
built, shipped = map(snapshot, sys.argv[1:])
if built != shipped:
    raise SystemExit('PDF vendor member names or SHA256 hashes differ')
print(str(len(built)) + ' PDF vendor files match exactly')
PY

This recipe reproduces the PDF vendor subtree only. It does not package the
whole Free/Pro release, start WordPress/database services, or run store actions.
It does not test every host or replace the plugin's functional qualification.
Source files are provided in readable form. Licenses are described in NOTICE.txt
and retained with the corresponding third-party components; original
StockControls code remains GPL-2.0-or-later and the combined Free package is GPLv2.
