Skip to content

generated-artifacts.md

Latest commit

 

History

History
166 lines (121 loc) · 9.62 KB

generated-artifacts.md

File metadata and controls

166 lines (121 loc) · 9.62 KB
Raw

Generated Artifacts

Yumemi commits two generated PHP artifacts so ordinary installations do not require Bison, the PHP parser skeleton, UDUNITS2 XML, or catalog-export tooling. This document records their editing authorities, known reproducible toolchain, provenance, licensing, consumer requirements, and verification.

Generated output is a consumption artifact, not an editing authority. Change the inputs or generator, regenerate the output, and review the resulting diff. Do not hand-edit either generated file.

Inventory

Output Editing authority Exact check
src/Parser/Parser.php Grammar, Bison, and mrsuh/php-bison-skeleton Nix generated-artifacts check
data/udunits2.php UDUNITS2 XML and Yumemi's catalog-generation pipeline Nix generated-artifacts check

Both files must remain committed and present in release archives. A future generator may replace the current one, but it must preserve the supported grammar or catalog semantics and produce the committed consumer artifact.

data/yumemi.php is separate authored catalog data, not a generated artifact. It layers project-defined dimensions, units, and aliases over UDUNITS2 without changing the provenance or reproducibility of data/udunits2.php.

Known Reproducible Environment

The authoritative pins are flake.lock and composer.lock. At the time of this inventory, the checked-in artifacts reproduce byte-for-byte with:

Component Version or revision Used for
PHP 8.2.32 from the pinned Nix package set Catalog
GNU Bison 3.8.2 Parser
mrsuh/php-bison-skeleton 1.2.0 (3aef7e150eb1c069c81150edf4768c9619f08159) Parser
brick/varexporter 0.6.0 (af98bfc2b702a312abbcaff37656dbe419cec5bc) Catalog
UDUNITS2 source unstable-2021-03-17 (c83da987387db1174cd2266b73dd5dd556f4476b) Catalog
Nixpkgs fd1462031fdee08f65fd0b4c6b64e22239a77870 Both

These versions describe a known reproducible environment, not permanent minimum or maximum versions. A dependency update may intentionally change generated bytes. Such a change must regenerate the artifact, explain the diff, and keep the exact check green. Whenever flake.lock or composer.lock changes, review this table and update any listed component whose resolved version or revision moved, even when regeneration remains byte-identical.

Generated Parser

Authority and Procedure

src/Parser/grammar.y is the grammar authority. GNU Bison applies the PHP skeleton from vendor/mrsuh/php-bison-skeleton/src/php-skel.m4; a post-processing step restores dollar signs represented by the skeleton's __DOLLAR__ placeholder.

From the Nix development shell with Composer dependencies installed, regenerate the parser with:

composer generate-parser

The equivalent Make target is src/Parser/Parser.php; make --always-make src/Parser/Parser.php forces regeneration when auditing reproducibility. A successful regeneration with the pinned environment must leave no diff.

Verification

The generated-artifacts flake check copies the committed parser, runs composer generate-parser with the pinned Bison and Composer dependencies, and compares the result byte-for-byte before running composer test:udunits2. Parser behavior is independently exercised by the normal PHPUnit suite, the runtime conformance corpus, documentation examples, finite generative tests, and the manual parser “probator.”

Byte identity protects against an uncommitted grammar or toolchain change. Behavioral tests remain authoritative for supported syntax and semantics if the generator is deliberately replaced and its textual output necessarily changes.

Provenance and Licensing

The grammar identifies portions derived from UDUNITS2 lib/parser.y. Yumemi's derivative grammar and modifications use the project license; incorporated upstream portions remain subject to the UCAR license reproduced in docs/UDUNITS-COPYRIGHT.

The generated file preserves the notices emitted by GNU Bison and the PHP skeleton, including Bison's parser-skeleton special exception. composer.lock records the PHP skeleton package's source, revision, and declared license. Preserve all generated notices when changing the generator.

Consumer Requirement

composer.json classmaps src/Parser/Parser.php, and both runtime parsing and PHPStan analysis load it. The release-style consumer test verifies that the generated parser is present in the Composer archive. Users do not need Bison or mrsuh/php-bison-skeleton.

Generated UDUNITS2 Catalog

Authority and Procedure

The external authorities are the five split XML files supplied by the pinned UDUNITS2 source, in this order:

  1. udunits2-prefixes.xml
  2. udunits2-base.xml
  3. udunits2-derived.xml
  4. udunits2-accepted.xml
  5. udunits2-common.xml

Yumemi's generation authority then consists of:

  • Udunits2CatalogImporter, which reads units, names, aliases, prefixes, and source metadata;
  • UnitDefinitionClassifier, which records supported, affine, and logarithmic semantics;
  • AffineDeltaUnitSynthesizer, which materializes multiplicative difference units; and
  • UnitRegistry::indexCatalogRecords(), which derives deterministic alias, symbol, and plural groupings from the imported effective names for constant-time runtime introspection and fails generation when an alias cannot resolve;
  • UnitRegistry::indexCatalogPrimitiveDimensions(), which derives the reverse primitive-dimension map used during registry composition; and
  • PhpCatalogExporter, which uses brick/varexporter for deterministic PHP.

The command wrapper adds the UCAR-derived-file header. The public contributor procedure is maintained in Regenerating the UDUNITS2 Catalog. In the Nix development shell, run:

composer generate-catalog

Outside that shell, UDUNITS_XML_DIR must identify a directory containing all five files. A successful rebuild from the pinned source and toolchain must leave no diff.

Verification

GenerateUdunits2CatalogCommandTest regenerates the full catalog from the split reference database and compares it byte-for-byte with data/udunits2.php. The ordinary PHPUnit run skips that case when the external database is unavailable; nix flake check supplies the matching source and requires it to pass.

Additional catalog, registry, conformance, and differential tests verify semantic behavior independently of the PHP array's textual layout. The runtime validates generated name and primitive-dimension indexes against catalog records. The validated bundled catalog is cached per process, while caller-supplied paths are reloaded and fully validated for every snapshot. Index-less custom catalog files retain dynamic indexing for compatibility. A catalog update must pass both exact regeneration and those behavioral checks.

Provenance and Licensing

The checked-in catalog is derived from the UCAR UDUNITS2 database. Its generated header identifies that provenance and points to docs/UDUNITS-COPYRIGHT, which must remain in both the repository and release archive. brick/varexporter is generation tooling and is not a runtime dependency.

Changing the Nixpkgs UDUNITS2 source is an explicit catalog update, not routine dependency churn. Review names, aliases, definitions, affine metadata, synthesized differences, and compatibility effects before accepting regenerated output.

Consumer Requirement

Udunits2UnitRegistry::DATA_FILE names data/udunits2.php as the generated upstream catalog. The bundled default registry composes that file with the authored data/yumemi.php supplement. The release-style consumer test verifies both catalogs and the UDUNITS2 copyright notice in the Composer archive. Users do not need the XML database, DOM importer, exporter, or generation command.

Change Checklist

When changing either artifact:

  1. modify the authoritative input or generator rather than generated output;
  2. regenerate in the pinned Nix development shell;
  3. inspect the complete generated diff and distinguish semantic changes from generator-only churn;
  4. run composer check:full and nix flake check --keep-going -L;
  5. update conformance cases, public documentation, compatibility notes, or licensing material when behavior or provenance changes; and
  6. commit authoritative inputs and generated output together.

If the historical generator stops working, retain the last valid committed artifact for consumers while replacing the generator. The replacement is acceptable when it reproduces supported behavior, provenance, licensing, and a reviewable committed output; preserving an obsolete implementation is not itself the goal.