From 72150d2c74be8d571a4253c8e8732c2c2587cefc Mon Sep 17 00:00:00 2001 From: Wes Dean Date: Mon, 14 Sep 2026 18:36:57 -0400 Subject: [PATCH 1/9] build: land development ordinary and minified artifacts --- .github/workflows/documentation-canary.yml | 36 ++-- .github/workflows/semver.yml | 20 +- .github/workflows/test.yml | 15 +- AGENTS.md | 61 ++++-- Makefile | 97 ++++++--- README.md | 79 +++++--- dependencies.txt | 4 + ...-004-build-and-release-versioned-filter.md | 9 +- ...lish-and-canary-exact-release-artifacts.md | 17 +- ...lopment-ordinary-and-minified-artifacts.md | 190 ++++++++++++++++++ doc/decisions.md | 41 ++-- 11 files changed, 457 insertions(+), 112 deletions(-) create mode 100644 dependencies.txt create mode 100644 doc/adr/ADR-011-produce-development-ordinary-and-minified-artifacts.md diff --git a/.github/workflows/documentation-canary.yml b/.github/workflows/documentation-canary.yml index a2173c1..3c4c7fd 100644 --- a/.github/workflows/documentation-canary.yml +++ b/.github/workflows/documentation-canary.yml @@ -45,7 +45,7 @@ jobs: - name: Verify generated documentation state run: | test -f doc/adr/README.md - grep -F 'ADR-007' doc/adr/README.md + grep -F 'ADR-011' doc/adr/README.md git check-ignore -q doc/adr/README.md test -z "$(git status --porcelain --untracked-files=all -- doc/adr/README.md)" test -f doc/reference/index.html @@ -67,29 +67,35 @@ jobs: sudo apt-get update sudo apt-get install --yes curl doxygen make mawk - - name: Download exact released Python filter and checksum + - name: Download exact released Python artifacts and checksums env: RELEASE_TAG: ${{ github.event.release.tag_name }} REPOSITORY: ${{ github.repository }} run: | mkdir -p .release-canary base="https://github.com/${REPOSITORY}/releases/download/${RELEASE_TAG}" - curl --fail --location --silent --show-error \ - --retry 5 --retry-all-errors --retry-delay 2 \ - "${base}/doxygen-python.awk" \ - --output .release-canary/doxygen-python.awk - curl --fail --location --silent --show-error \ - --retry 5 --retry-all-errors --retry-delay 2 \ - "${base}/doxygen-python.awk.sha256" \ - --output .release-canary/doxygen-python.awk.sha256 + for artifact in doxygen-python.dev.awk doxygen-python.awk doxygen-python.min.awk; do + curl --fail --location --silent --show-error \ + --retry 5 --retry-all-errors --retry-delay 2 \ + "${base}/${artifact}" \ + --output ".release-canary/${artifact}" + curl --fail --location --silent --show-error \ + --retry 5 --retry-all-errors --retry-delay 2 \ + "${base}/${artifact}.sha256" \ + --output ".release-canary/${artifact}.sha256" + done - - name: Verify released Python filter bytes + - name: Verify released Python artifact bytes run: | cd .release-canary + sha256sum -c doxygen-python.dev.awk.sha256 sha256sum -c doxygen-python.awk.sha256 + sha256sum -c doxygen-python.min.awk.sha256 - - name: Exercise exact released Python filter through Doxygen + - name: Exercise exact released Python artifacts through Doxygen run: | - make test-doxygen \ - AWK_BIN=mawk \ - DOXYGEN_PYTHON_FILTER=.release-canary/doxygen-python.awk + for artifact in doxygen-python.dev.awk doxygen-python.awk doxygen-python.min.awk; do + make test-doxygen \ + AWK_BIN=mawk \ + DOXYGEN_PYTHON_FILTER=".release-canary/${artifact}" + done diff --git a/.github/workflows/semver.yml b/.github/workflows/semver.yml index 5546e3d..d41856f 100644 --- a/.github/workflows/semver.yml +++ b/.github/workflows/semver.yml @@ -31,6 +31,9 @@ jobs: sudo apt-get update sudo apt-get install --yes doxygen mawk gawk + - name: Prepare pinned build dependencies + run: make deps + - name: calculate version id: calculate-version uses: bitshifted/git-auto-semver@c4e8f005e839f822325356f141939cf6c76b5701 # pin@v1 @@ -42,24 +45,27 @@ jobs: - name: Validate maintained source run: make check test-source AWK_BIN=mawk - - name: Build and validate release artifact + - name: Build and validate release artifacts run: | make test-dist \ AWK_BIN=mawk \ VERSION="${{ steps.calculate-version.outputs.version-string }}" - - name: Exercise release candidate through Doxygen + - name: Exercise release candidates through Doxygen run: | - make test-doxygen \ + make test-doxygen-dist \ AWK_BIN=mawk \ - DOXYGEN_PYTHON_FILTER=dist/doxygen-python.awk + VERSION="${{ steps.calculate-version.outputs.version-string }}" - - name: Generate and verify release checksum + - name: Generate and verify release checksums run: | make checksums \ + AWK_BIN=mawk \ VERSION="${{ steps.calculate-version.outputs.version-string }}" cd dist + sha256sum -c doxygen-python.dev.awk.sha256 sha256sum -c doxygen-python.awk.sha256 + sha256sum -c doxygen-python.min.awk.sha256 - name: Generate release notes id: release-notes @@ -79,5 +85,9 @@ jobs: draft: false prerelease: false files: | + dist/doxygen-python.dev.awk + dist/doxygen-python.dev.awk.sha256 dist/doxygen-python.awk dist/doxygen-python.awk.sha256 + dist/doxygen-python.min.awk + dist/doxygen-python.min.awk.sha256 diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index ab4931e..a5f9c02 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -28,10 +28,17 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - name: Install AWK implementation run: sudo apt-get update && sudo apt-get install -y ${{ matrix.awk }} - - name: Run source and dist semantic suite + - name: Prepare pinned build dependencies + run: make deps + - name: Run source and generated-artifact semantic suite run: make test AWK_BIN=${{ matrix.awk }} - name: Verify checksum generation - run: make checksums AWK_BIN=${{ matrix.awk }} + run: | + make checksums AWK_BIN=${{ matrix.awk }} + cd dist + sha256sum -c doxygen-python.dev.awk.sha256 + sha256sum -c doxygen-python.awk.sha256 + sha256sum -c doxygen-python.min.awk.sha256 doxygen: runs-on: ubuntu-24.04 @@ -39,5 +46,9 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - name: Install integration dependencies run: sudo apt-get update && sudo apt-get install -y doxygen mawk + - name: Prepare pinned build dependencies + run: make deps - name: Exercise maintained filter through Doxygen run: make test-doxygen AWK_BIN=mawk + - name: Exercise generated artifacts through Doxygen + run: make test-doxygen-dist AWK_BIN=mawk diff --git a/AGENTS.md b/AGENTS.md index 1240b4d..3710c08 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,15 +54,29 @@ at least `mawk` and GNU awk. Behavior-focused fixtures live under `tests/python/`. Fixtures protect public behavior, not helper structure. The same semantic suite must run against -maintained `doxygen-python.awk` and generated `dist/doxygen-python.awk`. +maintained `doxygen-python.awk` and all generated executable artifacts: +`dist/doxygen-python.dev.awk`, `dist/doxygen-python.awk`, and +`dist/doxygen-python.min.awk`. Run `make check` to apply GNU awk fatal linting to maintained root AWK sources. -Linting remains intentionally separate from semantic testing. Use -`make test AWK_BIN=mawk` and `make test AWK_BIN=gawk`; the test harness emits one -TAP-compliant stream across all selected filter variants. Preserve source-line -correspondence where practical, and pass ordinary Python source outside translated -docstrings through unchanged. `make test-doxygen` exercises the selected Python -filter against the focused Python/Doxygen integration fixture. +Linting remains intentionally separate from semantic testing. After preparing +build dependencies with `make deps`, use `make test AWK_BIN=mawk` and +`make test AWK_BIN=gawk`; the test harness emits one TAP-compliant stream across +all selected filter variants. Preserve source-line correspondence where +practical, and pass ordinary Python source outside translated docstrings through +unchanged. `make test-doxygen` exercises one selected Python filter, while +`make test-doxygen-dist` exercises all generated release candidates. + +## Build Dependencies + +Build dependencies are pinned in `dependencies.txt` and materialized beneath +`vendor/` by the SHA-256-pinned `bashdeps` bootstrap. ADR-011 requires an exact, +digest-verified `awk-minifier` release for minified artifact generation. + +`make deps` may use the network. `make deps-check` and `make build` consume +prepared state without silently downloading, repairing, or advancing pins. The +canonical build must fail clearly if its prepared minifier dependency is missing +or invalid. ## Documentation Tooling @@ -70,28 +84,35 @@ Project reference documentation describes this repository's maintained AWK, Bash, Markdown, and ADR sources. It is distinct from the Python-filter integration test. -Documentation-only dependencies are pinned in `dependencies-docs.txt` and are -materialized beneath `vendor/` by the SHA-256-pinned `bashdeps` bootstrap. The -set includes released `awk-doxygen`, released `bash-doxygen`, and released +Documentation-only dependencies are pinned separately in `dependencies-docs.txt` +and are materialized beneath `vendor/` by the same pinned `bashdeps` bootstrap. +The set includes released `awk-doxygen`, released `bash-doxygen`, and released `adrctl`. `make deps-docs` may use the network; `make deps-docs-check`, `make adr-index`, and `make docs` consume prepared state without silently repairing or advancing dependency pins. -Generated `doc/adr/README.md`, `doc/reference/`, and `vendor/` state is disposable -and must remain ignored by Git. +Generated `doc/adr/README.md`, `doc/reference/`, `dist/`, and `vendor/` state is +disposable and must remain ignored by Git. ## Build and Release -The maintained source and consumer outputs are `doxygen-python.awk`, -`dist/doxygen-python.awk`, and `dist/doxygen-python.awk.sha256`. `make build` is -the canonical artifact build. Build provenance is comments only and must not add -executable AWK state. +The maintained source is `doxygen-python.awk`. ADR-011 governs three generated +executable representations: `dist/doxygen-python.dev.awk` preserves the documented +body, `dist/doxygen-python.awk` removes full-line comments while retaining the +established default consumer filename, and `dist/doxygen-python.min.awk` is +produced by the pinned minifier. `make checksums` produces one SHA-256 file for +each executable artifact. + +`make build` is the canonical offline artifact build. Generated provenance is +owned by the build, remains comments only, and must be kept outside body +transformations so comment stripping or minification cannot erase provenance or +introduce executable AWK state. Semantic-version releases are a downstream dependency interface. The versioning -workflow must validate maintained and generated bytes, verify the checksum, and -publish both `doxygen-python.awk` and `doxygen-python.awk.sha256` as release -assets. Other repositories may pin those exact release assets with `bashdeps`, -so a version tag without the governed assets is an incomplete release. +workflow must validate maintained and generated bytes, exercise all generated +variants through Doxygen, verify all three checksums, and publish all six governed +files. Other repositories may pin any exact released executable asset with +`bashdeps`; `doxygen-python.awk` remains the default compatibility path. Exact published release bytes must be checksum-verified and exercised through the Python/Doxygen integration fixture. Do not substitute a tag checkout for this diff --git a/Makefile b/Makefile index c3835b7..e4a65c8 100644 --- a/Makefile +++ b/Makefile @@ -6,19 +6,25 @@ SHELL := /bin/sh DIST_DIR := dist SOURCE_FILTER := doxygen-python.awk AWK_SOURCES := $(SOURCE_FILTER) +DIST_DEV_FILTER := $(DIST_DIR)/doxygen-python.dev.awk DIST_FILTER := $(DIST_DIR)/doxygen-python.awk -DIST_CHECKSUM := $(DIST_FILTER).sha256 +DIST_MIN_FILTER := $(DIST_DIR)/doxygen-python.min.awk +DIST_FILTERS := $(DIST_DEV_FILTER) $(DIST_FILTER) $(DIST_MIN_FILTER) +DIST_CHECKSUMS := $(addsuffix .sha256,$(DIST_FILTERS)) AWK_BIN ?= awk INTEGRATION_CONFIG := tests/doxygen/Doxyfile INTEGRATION_OUT := tests/doxygen/out DOXYGEN_PYTHON_FILTER ?= $(SOURCE_FILTER) VENDOR_DIR := vendor +DEPENDENCY_MANIFEST := dependencies.txt DOCS_MANIFEST := dependencies-docs.txt BASHDEPS := $(VENDOR_DIR)/bashdeps.bash BASHDEPS_VERSION := 0.0.10 BASHDEPS_URL := https://github.com/wesley-dean/bashdeps/releases/download/v$(BASHDEPS_VERSION)/bashdeps.bash BASHDEPS_SHA256 := acbe79d39ab8cbbf906bd864d410ba7a223ba6f09501c02a409b8d3aa8740462 +AWK_MINIFIER := $(VENDOR_DIR)/awk-minifier.awk +AWK_MINIFIER_VERSION := 0.2.4 VENDOR_AWK_FILTER := $(VENDOR_DIR)/doxygen-awk.awk VENDOR_BASH_FILTER := $(VENDOR_DIR)/doxygen-bash.awk ADRCTL := $(VENDOR_DIR)/adrctl.bash @@ -34,27 +40,37 @@ VERSION ?= $(shell git describe --tags --always 2>/dev/null || printf '0.0.0-dev BUILD_COMMIT ?= $(shell git rev-parse --short=12 HEAD 2>/dev/null || printf 'unknown') BUILD_DATE ?= $(shell git show -s --format=%cI HEAD 2>/dev/null || printf 'unknown') -.PHONY: adr-index all build check checksums clean deps-docs deps-docs-check distclean docs docs-canary docs-clean integration-clean test test-source test-dist test-doxygen verify-bashdeps FORCE +.PHONY: adr-index all build check checksums clean deps deps-check deps-docs deps-docs-check distclean docs docs-canary docs-clean integration-clean test test-source test-dist test-doxygen test-doxygen-dist verify-bashdeps verify-build-deps FORCE -all: build +all: deps build -## Build the exact consumer artifact with immutable provenance metadata. -build: $(SOURCE_FILTER) +## Build the development, ordinary, and minified consumer artifacts offline. +build: verify-build-deps $(SOURCE_FILTER) mkdir -p "$(DIST_DIR)" - { \ + @header() { \ + artifact=$$1; transformation=$$2; \ printf '%s\n' '#!/usr/bin/awk -f'; \ printf '%s\n' '#'; \ printf '%s\n' '# Generated by make build. Do not edit directly.'; \ printf '%s\n' '# Source files: $(SOURCE_FILTER)'; \ + printf '%s\n' "# Artifact: $$artifact"; \ + printf '%s\n' "# Transformation: $$transformation"; \ printf '%s\n' '#'; \ printf '%s\n' '# DOXYGEN_PYTHON_VERSION=$(VERSION)'; \ printf '%s\n' '# DOXYGEN_PYTHON_BUILD_DATE=$(BUILD_DATE)'; \ printf '%s\n' '# DOXYGEN_PYTHON_BUILD_COMMIT=$(BUILD_COMMIT)'; \ printf '%s\n' '#'; \ - tail -n +2 "$(SOURCE_FILTER)"; \ - } >"$(DIST_FILTER).tmp" - chmod 0755 "$(DIST_FILTER).tmp" - mv "$(DIST_FILTER).tmp" "$(DIST_FILTER)" + }; \ + header 'development' 'none' >"$(DIST_DEV_FILTER).tmp"; \ + tail -n +2 "$(SOURCE_FILTER)" >>"$(DIST_DEV_FILTER).tmp"; \ + header 'ordinary' 'full-line comments removed' >"$(DIST_FILTER).tmp"; \ + tail -n +2 "$(SOURCE_FILTER)" | sed '/^[[:space:]]*#/d' >>"$(DIST_FILTER).tmp"; \ + header 'minified' 'AWK Minifier v$(AWK_MINIFIER_VERSION)' >"$(DIST_MIN_FILTER).tmp"; \ + tail -n +2 "$(SOURCE_FILTER)" | sed '/^[[:space:]]*#/d' | "$(AWK_BIN)" -f "$(AWK_MINIFIER)" >>"$(DIST_MIN_FILTER).tmp"; \ + for artifact in "$(DIST_DEV_FILTER)" "$(DIST_FILTER)" "$(DIST_MIN_FILTER)"; do \ + chmod 0755 "$$artifact.tmp"; \ + mv "$$artifact.tmp" "$$artifact"; \ + done ## Run GNU awk lint against maintained root AWK sources. check: @@ -64,25 +80,32 @@ check: gawk --lint=fatal -f "$$source" /dev/null; \ done -## Run one TAP stream covering maintained source and consumer output. +## Run one TAP stream covering maintained source and every generated artifact. test: build AWK_BIN="$(AWK_BIN)" sh ./tests/run-tests.sh \ "source=$(SOURCE_FILTER)" \ - "dist=$(DIST_FILTER)" + "dev=$(DIST_DEV_FILTER)" \ + "dist=$(DIST_FILTER)" \ + "min=$(DIST_MIN_FILTER)" ## Run the TAP semantic regression suite against the maintained source file. test-source: AWK_BIN="$(AWK_BIN)" sh ./tests/run-tests.sh "source=$(SOURCE_FILTER)" -## Build and run the TAP semantic suite against the exact consumer artifact. +## Build and run the TAP semantic suite against all generated artifacts. test-dist: build - test "$$(head -n 1 "$(DIST_FILTER)")" = '#!/usr/bin/awk -f' - grep -Fxq '# Generated by make build. Do not edit directly.' "$(DIST_FILTER)" - grep -Fxq '# Source files: $(SOURCE_FILTER)' "$(DIST_FILTER)" - grep -Fxq '# DOXYGEN_PYTHON_VERSION=$(VERSION)' "$(DIST_FILTER)" - grep -Fxq '# DOXYGEN_PYTHON_BUILD_DATE=$(BUILD_DATE)' "$(DIST_FILTER)" - grep -Fxq '# DOXYGEN_PYTHON_BUILD_COMMIT=$(BUILD_COMMIT)' "$(DIST_FILTER)" - AWK_BIN="$(AWK_BIN)" sh ./tests/run-tests.sh "dist=$(DIST_FILTER)" + @for artifact in $(DIST_FILTERS); do \ + test "$$(head -n 1 "$$artifact")" = '#!/usr/bin/awk -f'; \ + grep -Fxq '# Generated by make build. Do not edit directly.' "$$artifact"; \ + grep -Fxq '# Source files: $(SOURCE_FILTER)' "$$artifact"; \ + grep -Fxq '# DOXYGEN_PYTHON_VERSION=$(VERSION)' "$$artifact"; \ + grep -Fxq '# DOXYGEN_PYTHON_BUILD_DATE=$(BUILD_DATE)' "$$artifact"; \ + grep -Fxq '# DOXYGEN_PYTHON_BUILD_COMMIT=$(BUILD_COMMIT)' "$$artifact"; \ + done + AWK_BIN="$(AWK_BIN)" sh ./tests/run-tests.sh \ + "dev=$(DIST_DEV_FILTER)" \ + "dist=$(DIST_FILTER)" \ + "min=$(DIST_MIN_FILTER)" ## Exercise governed Python fixtures through Doxygen with the selected filter. test-doxygen: @@ -107,9 +130,18 @@ test-doxygen: grep -R -q 'Return type' "$(INTEGRATION_OUT)/xml" grep -R -q 'Configuration' "$(INTEGRATION_OUT)/xml" -## Generate the SHA-256 checksum for the exact consumer artifact. -checksums: build - cd "$(DIST_DIR)" && sha256sum "$(notdir $(DIST_FILTER))" >"$(notdir $(DIST_CHECKSUM))" +## Exercise every generated release candidate through Doxygen. +test-doxygen-dist: build + @for artifact in $(DIST_FILTERS); do \ + printf '%s\n' "Doxygen integration: $$artifact"; \ + $(MAKE) --no-print-directory test-doxygen AWK_BIN="$(AWK_BIN)" DOXYGEN_PYTHON_FILTER="$$artifact"; \ + done + +## Generate SHA-256 checksums for every generated artifact. +checksums: build $(DIST_CHECKSUMS) + +$(DIST_DIR)/%.awk.sha256: $(DIST_DIR)/%.awk + cd "$(DIST_DIR)" && sha256sum "$(notdir $<)" >"$(notdir $@)" FORCE: @@ -140,15 +172,28 @@ $(BASHDEPS): FORCE ## Verify the pinned bashdeps bootstrap without network access or repair. verify-bashdeps: - @test -x "$(BASHDEPS)" || { printf '%s\n' 'Missing or non-executable vendor/bashdeps.bash; run make deps-docs' >&2; exit 1; } + @test -x "$(BASHDEPS)" || { printf '%s\n' 'Missing or non-executable vendor/bashdeps.bash; run make deps or make deps-docs' >&2; exit 1; } @if command -v sha256sum >/dev/null 2>&1; then \ - printf '%s %s\n' "$(BASHDEPS_SHA256)" "$(BASHDEPS)" | sha256sum -c - >/dev/null 2>&1 || { printf '%s\n' 'bashdeps.bash digest mismatch; run make deps-docs' >&2; exit 1; }; \ + printf '%s %s\n' "$(BASHDEPS_SHA256)" "$(BASHDEPS)" | sha256sum -c - >/dev/null 2>&1 || { printf '%s\n' 'bashdeps.bash digest mismatch; run make deps or make deps-docs' >&2; exit 1; }; \ elif command -v shasum >/dev/null 2>&1; then \ - [ "$$(shasum -a 256 "$(BASHDEPS)" | awk '{print $$1}')" = "$(BASHDEPS_SHA256)" ] || { printf '%s\n' 'bashdeps.bash digest mismatch; run make deps-docs' >&2; exit 1; }; \ + [ "$$(shasum -a 256 "$(BASHDEPS)" | awk '{print $$1}')" = "$(BASHDEPS_SHA256)" ] || { printf '%s\n' 'bashdeps.bash digest mismatch; run make deps or make deps-docs' >&2; exit 1; }; \ else \ printf '%s\n' 'No SHA-256 verification command is available for bashdeps.bash' >&2; exit 1; \ fi +## Synchronize build dependencies; this target may use the network. +deps: $(BASHDEPS) $(DEPENDENCY_MANIFEST) + $(MAKE) --no-print-directory verify-bashdeps + "$(BASHDEPS)" sync "$(DEPENDENCY_MANIFEST)" + +## Verify prepared build dependencies without network access or repair. +deps-check: verify-bashdeps $(DEPENDENCY_MANIFEST) + "$(BASHDEPS)" verify "$(DEPENDENCY_MANIFEST)" + +## Require prepared, pinned build dependencies without network access. +verify-build-deps: deps-check + @test -r "$(AWK_MINIFIER)" || { printf '%s\n' 'Missing build dependency vendor/awk-minifier.awk; run make deps' >&2; exit 1; } + ## Synchronize documentation-only dependencies; this target may use the network. deps-docs: $(BASHDEPS) $(DOCS_MANIFEST) $(MAKE) --no-print-directory verify-bashdeps diff --git a/README.md b/README.md index ff92cc5..54afcce 100644 --- a/README.md +++ b/README.md @@ -110,20 +110,26 @@ Run GNU awk's fatal lint mode against maintained root AWK sources with: make check ``` -Linting is intentionally separate from semantic testing. Run the semantic suite -against maintained source and generated consumer bytes with: +Linting is intentionally separate from semantic testing. Prepare the pinned +build dependency and run the semantic suite against maintained source and every +generated executable artifact with: ```sh +make deps make test AWK_BIN=mawk make test AWK_BIN=gawk ``` -The semantic harness emits one TAP-compliant stream for every filter selected by -the Make target. `make test-source` and `make test-dist` remain available for -focused source-only or distribution-only validation. +The semantic harness emits one TAP-compliant stream for every selected filter. +`make test-source` remains source-only, while `make test-dist` validates the +three generated variants together. -CI runs GNU awk linting, both supported semantic AWK implementations, and a -Doxygen integration job. Build the consumer artifact and checksum with: +`awk-minifier` is an explicit build dependency pinned in `dependencies.txt` and +materialized beneath `vendor/` by the repository's pinned `bashdeps` bootstrap. +`make deps` may use the network. `make deps-check` and `make build` consume +prepared dependency state without silently downloading or advancing it. + +Build all generated forms and their checksums with: ```sh make build @@ -133,12 +139,24 @@ make checksums The generated files are: ```text +dist/doxygen-python.dev.awk +dist/doxygen-python.dev.awk.sha256 dist/doxygen-python.awk dist/doxygen-python.awk.sha256 +dist/doxygen-python.min.awk +dist/doxygen-python.min.awk.sha256 ``` -Build provenance is inserted as comments only so artifact metadata cannot change -AWK execution semantics. +The development artifact preserves the maintained body, the ordinary artifact +removes full-line comments while retaining the established consumer filename, +and the minified artifact is produced with the pinned `awk-minifier` release. +Build provenance is generated separately and inserted as comments in every +artifact so representation changes cannot erase provenance or add executable AWK +state. + +CI runs GNU awk linting, the semantic suite under both supported AWK +implementations, checksum verification for all generated artifacts, and Doxygen +integration against maintained source and all three generated release candidates. ## Documentation tooling @@ -148,8 +166,10 @@ for testing the Python filter itself. `tests/doxygen/Doxyfile` exercises project's maintained AWK, Bash, Markdown, and ADR sources. Reference documentation uses released, SHA-256-pinned `awk-doxygen`, -`bash-doxygen`, and `adrctl` assets declared in `dependencies-docs.txt`. A pinned -`bashdeps` release synchronizes those assets beneath `vendor/`. +`bash-doxygen`, and `adrctl` assets declared in `dependencies-docs.txt`. These are +separate from the build dependency in `dependencies.txt`. A pinned `bashdeps` +release synchronizes both dependency sets beneath `vendor/` through their +respective Make targets. Prepare and verify documentation dependencies with: @@ -172,26 +192,32 @@ maintained source rather than committing generated HTML. ## Releases and downstream dependencies -Semantic-version releases publish the tested consumer artifact and its checksum: +Semantic-version releases publish all three tested executable representations and +their individual checksums: ```text +doxygen-python.dev.awk +doxygen-python.dev.awk.sha256 doxygen-python.awk doxygen-python.awk.sha256 +doxygen-python.min.awk +doxygen-python.min.awk.sha256 ``` -These release assets are the dependency interface for downstream repositories. -A downstream project pins a specific `python-doxygen` version in its `bashdeps` -manifest using that version's public release-asset URL and the SHA-256 digest of -the published filter. During the downstream build, `bashdeps` downloads those -exact public bytes and verifies the digest before use. Consumption therefore -requires neither version discovery nor GitHub authentication. - -The versioning workflow validates maintained source, builds and tests the exact -distribution artifact, generates and verifies its checksum, exercises the -release candidate through Doxygen, and publishes both files as release assets. -A release-artifact canary may independently download the public released files, -verify the checksum, and exercise the Python filter through the same Doxygen -integration fixture. +The ordinary `doxygen-python.awk` asset remains the default compatibility path. +A downstream project may instead select the development or minified form and pin +that exact asset in its `bashdeps` manifest using a specific release version, +public release-asset URL, and SHA-256 digest. During the downstream build, +`bashdeps` retrieves those exact public bytes and verifies the digest before use. +Consumption therefore requires neither version discovery nor GitHub +authentication. + +The versioning workflow validates maintained source, builds and semantically tests +all three generated artifacts, exercises each release candidate through Doxygen, +generates and verifies all three checksums, and publishes all six files as release +assets. A release-artifact canary may independently download public released +files, verify checksums, and exercise the selected Python filter through the same +Doxygen integration fixture. ## Documentation and governance @@ -206,7 +232,8 @@ The maintained AWK filter follows the checked-in Before changing parser boundaries, generated representation, portability, documentation publication, or the artifact contract, review `AGENTS.md`, the documentation standards, all ADRs in `doc/adr/`, and `doc/decisions.md`. -Accepted ADRs govern the implementation. +Accepted ADRs govern the implementation. ADR-011 governs the development, +ordinary, and minified distribution contract. ## License diff --git a/dependencies.txt b/dependencies.txt new file mode 100644 index 0000000..8a06de2 --- /dev/null +++ b/dependencies.txt @@ -0,0 +1,4 @@ +# Build dependencies synchronized by the released vendor/bashdeps.bash bootstrap. +# Keep each dependency on one physical line for compatibility with bashdeps. + +id=wesley-dean/awk-minifier@0.2.4 url=https://github.com/wesley-dean/awk-minifier/releases/download/v0.2.4/awk-minifier.awk dest=vendor/awk-minifier.awk digest=sha256:9668287c394a48e6143b63074fea8ab9fed240ef0637ac169780e08e30661803 diff --git a/doc/adr/ADR-004-build-and-release-versioned-filter.md b/doc/adr/ADR-004-build-and-release-versioned-filter.md index ffbe6ab..ec682b7 100644 --- a/doc/adr/ADR-004-build-and-release-versioned-filter.md +++ b/doc/adr/ADR-004-build-and-release-versioned-filter.md @@ -9,8 +9,11 @@ Accepted ## Supersession Note ADR-007 supersedes only this ADR's milestone-1 deferral of release publication. -The maintained-source name, generated artifact name, checksum name, comment-only -provenance requirement, and source/dist parity requirements remain governing. +ADR-011 supersedes this ADR where it defines one generated artifact and one +checksum, expanding that boundary to development, ordinary, and minified +artifacts with individual checksums. The maintained-source name, generated-state +model, comment-only provenance principle, and source/artifact parity requirements +remain governing except where ADR-011 explicitly expands them. ## Context @@ -52,3 +55,5 @@ considered usable. - ADR-000 governs capability claims. - ADR-005 requires source and dist parity in the regression suite. - ADR-007 governs release publication and exact released-artifact validation. +- ADR-011 expands the generated artifact and checksum set while preserving this + ADR's underlying source/artifact boundary. diff --git a/doc/adr/ADR-007-publish-and-canary-exact-release-artifacts.md b/doc/adr/ADR-007-publish-and-canary-exact-release-artifacts.md index 0c2f68c..503cc71 100644 --- a/doc/adr/ADR-007-publish-and-canary-exact-release-artifacts.md +++ b/doc/adr/ADR-007-publish-and-canary-exact-release-artifacts.md @@ -6,6 +6,15 @@ Date: 2026-09-11 Accepted +## Supersession Note + +ADR-011 supersedes this ADR where it defines exactly one executable release +artifact and one checksum. ADR-011 expands the publication set to development, +ordinary, and minified executable artifacts with individual checksums. This ADR +remains authoritative for exact-byte release validation, versioned downstream +pinning, public retrieval, checksum verification, and release-artifact canary +principles except where ADR-011 explicitly expands the asset set. + ## Context ADR-004 established `dist/doxygen-python.awk` and its SHA-256 checksum as the @@ -86,7 +95,8 @@ make unrelated repository changes. This decision supersedes only ADR-004's milestone-1 statement that release publication is outside scope. ADR-004's maintained-source name, generated artifact name, checksum name, comment-only provenance requirement, and -source/dist parity requirements remain governing. +source/dist parity requirements remain governing subject to ADR-011's later +expansion of the generated artifact and checksum set. ## Alternatives Considered @@ -113,7 +123,8 @@ because dependency advancement is a separate reviewed repository decision. Release creation now depends on the same Make build and semantic test path used locally and in pull-request CI. Consumers receive one executable AWK artifact and -one checksum file whose bytes have been tested together. +one checksum file whose bytes have been tested together, subject to ADR-011's +later expansion to three executable representations and their checksums. Downstream repositories can pin an exact semantic version in their `bashdeps` manifest and reproduce the same dependency bytes later using only the public @@ -136,3 +147,5 @@ ADR review. - ADR-005 requires the same semantic suite to exercise maintained and generated bytes. - ADR-006 governs the shared Make and documentation infrastructure. +- ADR-011 expands this ADR's release asset set while preserving its exact-byte + publication and downstream pinning model. diff --git a/doc/adr/ADR-011-produce-development-ordinary-and-minified-artifacts.md b/doc/adr/ADR-011-produce-development-ordinary-and-minified-artifacts.md new file mode 100644 index 0000000..52ef449 --- /dev/null +++ b/doc/adr/ADR-011-produce-development-ordinary-and-minified-artifacts.md @@ -0,0 +1,190 @@ +# ADR-011: Produce development, ordinary, and minified artifacts + +Date: 2026-09-14 + +## Status + +Accepted + +## Context + +ADR-004 established one generated consumer artifact, +`dist/doxygen-python.awk`, with comment-only provenance and semantic parity with +maintained source. ADR-007 later made that exact artifact and its checksum the +published release interface. The project now needs distinct development, +ordinary, and minified forms of the same filter so consumers can choose between +maximum inspectability, reduced comment volume, and minimum distribution size. + +The requested artifact expansion changes the build and release contract. It +also introduces a build-time dependency on `awk-minifier`, whose released bytes +must be pinned and independently verifiable. These changes are consequential +because downstream repositories may pin exact release asset names and digests, +and because an additional source-to-source transformation creates another place +where semantic drift could be introduced. + +The existing project principles remain applicable: maintained source is the +source of truth, generated state remains disposable, provenance must not alter +AWK behavior, portable operation under `mawk` and GNU awk remains required, and +generated bytes must be tested rather than assumed equivalent. + +## Decision Drivers + +- Preserve one maintained, fully documented AWK source file. +- Provide a fully documented generated artifact for inspection and debugging. +- Preserve the established `doxygen-python.awk` name as the ordinary default + consumer artifact. +- Provide a smaller minified artifact without maintaining separate minified + source by hand. +- Keep build provenance visible in every generated artifact. +- Pin the exact minifier release used by the build. +- Keep `make build` free of implicit network access. +- Exercise every generated executable artifact with the same semantic suite. +- Exercise every generated release candidate through Doxygen before release. +- Publish checksums for each published executable artifact. + +## Decision + +The maintained source SHALL remain `doxygen-python.awk`. + +The build SHALL produce three executable AWK artifacts: + +```text +dist/doxygen-python.dev.awk +dist/doxygen-python.awk +dist/doxygen-python.min.awk +``` + +Their roles SHALL be: + +1. `doxygen-python.dev.awk` is the development artifact. It contains the + maintained filter body without documentation removal or minification, plus a + generated provenance header. +2. `doxygen-python.awk` is the ordinary consumer artifact. It preserves the + established downstream filename while removing full-line comments from the + maintained filter body. It retains a generated provenance header. +3. `doxygen-python.min.awk` is the minified consumer artifact. Its transformed + body is produced by the pinned `awk-minifier` release from the comment-stripped + filter body. It retains a generated provenance header identifying the + minifier version. + +The generated provenance header SHALL be owned by the build and kept outside the +body passed through comment stripping or minification. Every artifact SHALL +retain the shebang, source identity, artifact role or transformation, project +version, build date, and source commit as comments only. Generated provenance +MUST NOT introduce executable AWK state. + +`awk-minifier` SHALL be a build dependency declared in `dependencies.txt` and +materialized beneath `vendor/` by the repository's pinned `bashdeps` bootstrap. +The dependency SHALL pin an exact released version, public release-asset URL, and +SHA-256 digest. The initial governed version is `awk-minifier` v0.2.4. + +`make deps` MAY use the network to synchronize build dependencies. `make deps-check` +and `make build` SHALL NOT silently download, repair, or advance build +dependencies. `make build` SHALL fail clearly when the prepared pinned minifier +dependency is unavailable or invalid. `make all` MAY prepare pinned build +dependencies before invoking the offline build path. + +The semantic regression harness SHALL run against maintained source and all three +generated artifacts. The combined test entry point SHALL emit one TAP-compliant +stream so source/artifact parity is machine-consumable without concatenating +independent TAP documents. Pull-request CI SHALL retain both `mawk` and GNU awk +coverage. + +Doxygen integration validation SHALL exercise all three generated artifacts when +validating release candidates. A generated variant SHALL NOT be released merely +because the maintained source passes the integration fixture. + +`make checksums` SHALL produce: + +```text +dist/doxygen-python.dev.awk.sha256 +dist/doxygen-python.awk.sha256 +dist/doxygen-python.min.awk.sha256 +``` + +Semantic-version releases SHALL publish all six generated files. The ordinary +`doxygen-python.awk` asset remains the default compatibility path for downstream +consumers that do not need a different representation. Downstream projects MAY +pin any one of the three executable assets by exact version, public release URL, +and digest. + +## Alternatives Considered + +Maintaining three independent source files was rejected because documentation +removal and minification are mechanical representations of one implementation, +not separate behavior. Multiple maintained implementations would create an +avoidable synchronization and review burden. + +Replacing the established `doxygen-python.awk` release asset with only a +`.dev.awk` or `.min.awk` asset was rejected because existing downstream consumers +may already depend on the ordinary filename. The established name therefore +remains the default consumer contract. + +Allowing `make build` to download `awk-minifier` automatically was rejected +because builds should be reproducible from explicitly prepared dependency state +and should not hide network access. Dependency synchronization remains an +explicit operation. + +Tracking generated distribution artifacts in Git was rejected because generated +bytes are reproducible build state and are already governed as disposable. + +Stripping provenance before publication was rejected because exact generated +bytes need an inspectable connection to source revision, project version, build +date, and transformation. Instead, provenance is generated separately from the +body transformation so it survives every representation. + +Testing only the ordinary artifact was rejected because comment stripping and +minification are distinct transformations. Each executable result must earn the +same semantic and Doxygen confidence as the maintained source. + +Publishing only the three executable artifacts without their individual +checksums was rejected because downstream pinning relies on digest verification +of exact release bytes. + +## Consequences + +The repository now has six generated release files instead of two. Release +workflow, documentation, and downstream examples must therefore distinguish the +three executable representations and their checksums. + +A prepared build environment now requires the pinned `awk-minifier` asset in +addition to the maintained source tree. That dependency is explicit, versioned, +and digest-verified rather than discovered dynamically. + +Build and release validation become stronger because both transformations are +covered by the same semantic suite and Doxygen integration contract. A defect in +comment stripping or minification can therefore fail CI or release validation +before publication. + +The ordinary `doxygen-python.awk` filename remains stable, limiting migration +impact for current consumers. Consumers that value source comments can select +the development artifact; consumers that value size can select the minified +artifact. + +Future changes to artifact roles, filenames, provenance layout, minifier trust +boundary, checksum format, or the set of published release assets are +compatibility decisions and require corresponding ADR review. + +## Supersession + +This ADR supersedes ADR-004 where ADR-004 defines a single generated artifact and +single checksum. ADR-004 remains authoritative for the maintained-source +boundary, generated-state model, comment-only provenance principle, and semantic +parity requirement except where this ADR expands those concepts to three +artifacts. + +This ADR supersedes ADR-007 where ADR-007 defines exactly two published release +assets. ADR-007 remains authoritative for exact-byte release validation, +versioned downstream pinning, public retrieval, checksum verification, and +release-artifact canary principles except where this ADR expands the publication +set to six files. + +## Related Decisions + +- ADR-000 requires capability and release claims to match evidence. +- ADR-004 established the maintained-source/generated-artifact boundary. +- ADR-005 requires behavior-focused source/artifact parity testing. +- ADR-006 governs the shared Make, dependency, test, and documentation + infrastructure. +- ADR-007 governs exact release publication and downstream pinning. +- ADR-008 supplements focused fixtures with larger scenario regressions. diff --git a/doc/decisions.md b/doc/decisions.md index 8c03a59..973ae87 100644 --- a/doc/decisions.md +++ b/doc/decisions.md @@ -39,13 +39,15 @@ continue to preserve line count. Continuation prose remains byte-preserved when Doxygen can retain its association without extra translator state. See [ADR-003](adr/ADR-003-define-yields-translation.md). -## Versioned consumer artifact +## Versioned consumer artifacts -Maintained source and consumer bytes are separate. `make build` produces -`dist/doxygen-python.awk` with comment-only provenance, and the same semantic -suite exercises source and dist. ADR-007 later supersedes only ADR-004's initial -deferral of release publication; the artifact boundary remains unchanged. See -[ADR-004](adr/ADR-004-build-and-release-versioned-filter.md). +Maintained source and generated consumer bytes remain separate. ADR-011 expands +ADR-004's original single-artifact boundary into development, ordinary, and +minified generated variants, while preserving comment-only provenance and the +requirement that generated bytes earn semantic parity with maintained source. +The established `doxygen-python.awk` name remains the default ordinary consumer +artifact. See [ADR-004](adr/ADR-004-build-and-release-versioned-filter.md) and +[ADR-011](adr/ADR-011-produce-development-ordinary-and-minified-artifacts.md). ## Behavior-focused fixtures @@ -70,14 +72,14 @@ such as `--compact`, are deliberately not copied. See ## Release publication and downstream pinning -ADR-007 requires semantic-version releases to publish the tested -`doxygen-python.awk` artifact and its SHA-256 checksum as public release assets. -Downstream repositories pin a specific version, public release URL, and digest in -their `bashdeps` manifests; their builds retrieve and verify those exact bytes -without GitHub authentication or version discovery. Release-artifact canaries -may independently verify publication packaging, but they are not part of the -downstream dependency-resolution path. See -[ADR-007](adr/ADR-007-publish-and-canary-exact-release-artifacts.md). +ADR-007 established exact-byte semantic-version release publication and +`bashdeps` pinning. ADR-011 expands the release set from one executable artifact +and checksum to development, ordinary, and minified executable artifacts with one +checksum each, while retaining public versioned URLs and digest verification as +the downstream contract. Release-artifact canaries may independently verify +publication packaging, but they are not part of dependency resolution. See +[ADR-007](adr/ADR-007-publish-and-canary-exact-release-artifacts.md) and +[ADR-011](adr/ADR-011-produce-development-ordinary-and-minified-artifacts.md). ## Scenario-level program regressions @@ -108,3 +110,14 @@ line. The filter does not determine whether annotations make those fields redundant or inconsistent; that semantic validation remains with Python-native tooling. See [ADR-010](adr/ADR-010-translate-unannotated-type-fields.md). + +## Development, ordinary, and minified distributions + +ADR-011 defines three representations of the same maintained filter. The +development artifact preserves the documented body, the ordinary artifact strips +full-line comments while retaining the established filename, and the minified +artifact is produced by a pinned, digest-verified `awk-minifier` release. Build +provenance is generated outside those transformations, all three variants are +covered by semantic and Doxygen validation, and all three are published with +individual SHA-256 checksums. See +[ADR-011](adr/ADR-011-produce-development-ordinary-and-minified-artifacts.md). From 18c4e5cbb5a61dadd838b8a9c8872e8a6865da21 Mon Sep 17 00:00:00 2001 From: Wes Dean Date: Mon, 14 Sep 2026 18:38:36 -0400 Subject: [PATCH 2/9] build: make all produce and validate six artifacts --- Makefile | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index e4a65c8..0034d93 100644 --- a/Makefile +++ b/Makefile @@ -42,7 +42,9 @@ BUILD_DATE ?= $(shell git show -s --format=%cI HEAD 2>/dev/null || printf 'unkno .PHONY: adr-index all build check checksums clean deps deps-check deps-docs deps-docs-check distclean docs docs-canary docs-clean integration-clean test test-source test-dist test-doxygen test-doxygen-dist verify-bashdeps verify-build-deps FORCE -all: deps build +## Prepare dependencies, validate generated artifacts, and produce all checksums. +all: deps + $(MAKE) --no-print-directory test-dist checksums ## Build the development, ordinary, and minified consumer artifacts offline. build: verify-build-deps $(SOURCE_FILTER) From 9ba5386996a85b37f954a159871f88096225f542 Mon Sep 17 00:00:00 2001 From: Wes Dean Date: Mon, 14 Sep 2026 18:38:53 -0400 Subject: [PATCH 3/9] docs: define make all artifact contract --- README.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 54afcce..cfb8a89 100644 --- a/README.md +++ b/README.md @@ -129,10 +129,20 @@ materialized beneath `vendor/` by the repository's pinned `bashdeps` bootstrap. `make deps` may use the network. `make deps-check` and `make build` consume prepared dependency state without silently downloading or advancing it. -Build all generated forms and their checksums with: +Run the complete build path with: + +```sh +make all +``` + +`make all` synchronizes the pinned build dependency, builds all three generated +AWK forms, runs the TAP semantic suite against each generated artifact, and +creates all three SHA-256 files. When dependency state is already prepared, the +same stages remain available individually: ```sh make build +make test-dist make checksums ``` From 2ceeeaa61b7c4bed9b787c1c59bb4b2078bf1aa9 Mon Sep 17 00:00:00 2001 From: Wes Dean Date: Mon, 14 Sep 2026 18:39:06 -0400 Subject: [PATCH 4/9] docs: govern complete make all build path --- AGENTS.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3710c08..9a5deac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -103,10 +103,14 @@ established default consumer filename, and `dist/doxygen-python.min.awk` is produced by the pinned minifier. `make checksums` produces one SHA-256 file for each executable artifact. -`make build` is the canonical offline artifact build. Generated provenance is -owned by the build, remains comments only, and must be kept outside body -transformations so comment stripping or minification cannot erase provenance or -introduce executable AWK state. +`make all` is the complete top-level build path. It may synchronize the pinned +build dependency, then must build all three generated executable artifacts, run +the TAP semantic suite against those generated bytes, and leave all three +corresponding SHA-256 files in `dist/`. `make build` remains the canonical +offline artifact-generation step and must not acquire dependencies implicitly. +Generated provenance is owned by the build, remains comments only, and must be +kept outside body transformations so comment stripping or minification cannot +erase provenance or introduce executable AWK state. Semantic-version releases are a downstream dependency interface. The versioning workflow must validate maintained and generated bytes, exercise all generated From 4aaa1d2c47211f69efa1a67fee57248d4eb56b30 Mon Sep 17 00:00:00 2001 From: Wes Dean Date: Mon, 14 Sep 2026 18:39:24 -0400 Subject: [PATCH 5/9] docs: make top-level build contract explicit --- ...lopment-ordinary-and-minified-artifacts.md | 21 +++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/doc/adr/ADR-011-produce-development-ordinary-and-minified-artifacts.md b/doc/adr/ADR-011-produce-development-ordinary-and-minified-artifacts.md index 52ef449..a14e790 100644 --- a/doc/adr/ADR-011-produce-development-ordinary-and-minified-artifacts.md +++ b/doc/adr/ADR-011-produce-development-ordinary-and-minified-artifacts.md @@ -38,6 +38,7 @@ generated bytes must be tested rather than assumed equivalent. - Keep build provenance visible in every generated artifact. - Pin the exact minifier release used by the build. - Keep `make build` free of implicit network access. +- Make the top-level build leave all six governed artifacts in `dist/`. - Exercise every generated executable artifact with the same semantic suite. - Exercise every generated release candidate through Doxygen before release. - Publish checksums for each published executable artifact. @@ -81,8 +82,15 @@ SHA-256 digest. The initial governed version is `awk-minifier` v0.2.4. `make deps` MAY use the network to synchronize build dependencies. `make deps-check` and `make build` SHALL NOT silently download, repair, or advance build dependencies. `make build` SHALL fail clearly when the prepared pinned minifier -dependency is unavailable or invalid. `make all` MAY prepare pinned build -dependencies before invoking the offline build path. +dependency is unavailable or invalid. + +`make all` SHALL be the complete top-level build path. It MAY synchronize the +pinned build dependency, SHALL build all three generated executable artifacts, +SHALL run the TAP semantic regression suite against those generated artifacts, +and SHALL produce the three corresponding SHA-256 files. A successful +`make all` therefore leaves all six governed build artifacts in `dist/`. This +top-level orchestration does not weaken the requirement that `make build` itself +remain offline and consume only prepared dependency state. The semantic regression harness SHALL run against maintained source and all three generated artifacts. The combined test entry point SHALL emit one TAP-compliant @@ -141,6 +149,10 @@ Publishing only the three executable artifacts without their individual checksums was rejected because downstream pinning relies on digest verification of exact release bytes. +Requiring callers of the top-level build to remember separate build, test, and +checksum commands was rejected because the requested build contract is six +artifacts whose executable forms have already passed semantic validation. + ## Consequences The repository now has six generated release files instead of two. Release @@ -151,6 +163,11 @@ A prepared build environment now requires the pinned `awk-minifier` asset in addition to the maintained source tree. That dependency is explicit, versioned, and digest-verified rather than discovered dynamically. +`make all` is intentionally broader than the offline `make build` primitive: it +may prepare the pinned dependency, validates all generated executable forms, and +creates their checksums. Local callers therefore have one top-level command that +leaves the complete six-file build result behind. + Build and release validation become stronger because both transformations are covered by the same semantic suite and Doxygen integration contract. A defect in comment stripping or minification can therefore fail CI or release validation From 2c8b7179fe878edfe5a2a135e7051604e52b4bb2 Mon Sep 17 00:00:00 2001 From: Wes Dean Date: Mon, 14 Sep 2026 18:39:38 -0400 Subject: [PATCH 6/9] docs: summarize complete six-artifact build path --- doc/decisions.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/decisions.md b/doc/decisions.md index 973ae87..65ad885 100644 --- a/doc/decisions.md +++ b/doc/decisions.md @@ -119,5 +119,8 @@ full-line comments while retaining the established filename, and the minified artifact is produced by a pinned, digest-verified `awk-minifier` release. Build provenance is generated outside those transformations, all three variants are covered by semantic and Doxygen validation, and all three are published with -individual SHA-256 checksums. See +individual SHA-256 checksums. The top-level `make all` path prepares the pinned +build dependency as needed, TAP-tests the three generated executable forms, and +leaves all six governed build artifacts in `dist/`; `make build` remains the +offline artifact-generation primitive. See [ADR-011](adr/ADR-011-produce-development-ordinary-and-minified-artifacts.md). From 1b287c26fdb2cc7506963167cea973b351deca95 Mon Sep 17 00:00:00 2001 From: Wes Dean Date: Mon, 14 Sep 2026 18:40:12 -0400 Subject: [PATCH 7/9] ci: exercise complete make all build path --- .github/workflows/test.yml | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index a5f9c02..62e7a5d 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -28,13 +28,12 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - name: Install AWK implementation run: sudo apt-get update && sudo apt-get install -y ${{ matrix.awk }} - - name: Prepare pinned build dependencies - run: make deps - - name: Run source and generated-artifact semantic suite - run: make test AWK_BIN=${{ matrix.awk }} - - name: Verify checksum generation + - name: Run complete build and generated-artifact suite + run: make all AWK_BIN=${{ matrix.awk }} + - name: Run maintained-source semantic suite + run: make test-source AWK_BIN=${{ matrix.awk }} + - name: Verify generated checksums run: | - make checksums AWK_BIN=${{ matrix.awk }} cd dist sha256sum -c doxygen-python.dev.awk.sha256 sha256sum -c doxygen-python.awk.sha256 From 9e1ede107b5b014bb404ed96cc5f078bfcc8a8f7 Mon Sep 17 00:00:00 2001 From: Wes Dean Date: Mon, 14 Sep 2026 18:43:13 -0400 Subject: [PATCH 8/9] fix: generate checksums after artifact build --- Makefile | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index 0034d93..2638a20 100644 --- a/Makefile +++ b/Makefile @@ -139,11 +139,12 @@ test-doxygen-dist: build $(MAKE) --no-print-directory test-doxygen AWK_BIN="$(AWK_BIN)" DOXYGEN_PYTHON_FILTER="$$artifact"; \ done -## Generate SHA-256 checksums for every generated artifact. -checksums: build $(DIST_CHECKSUMS) - -$(DIST_DIR)/%.awk.sha256: $(DIST_DIR)/%.awk - cd "$(DIST_DIR)" && sha256sum "$(notdir $<)" >"$(notdir $@)" +## Generate SHA-256 checksums after all executable artifacts have been built. +checksums: build + @for artifact in $(DIST_FILTERS); do \ + name=$${artifact##*/}; \ + (cd "$(DIST_DIR)" && sha256sum "$$name" >"$$name.sha256"); \ + done FORCE: From 53d837efa9c9f7a82cd0142eb40125bba597182c Mon Sep 17 00:00:00 2001 From: Wes Dean Date: Mon, 14 Sep 2026 18:43:20 -0400 Subject: [PATCH 9/9] ci: run both AWK matrix entries after failures --- .github/workflows/test.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 62e7a5d..05fe213 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -22,6 +22,7 @@ jobs: semantic: runs-on: ubuntu-24.04 strategy: + fail-fast: false matrix: awk: [mawk, gawk] steps: