From 5e879d97ce75af90bf44e8ac7979b423b8887de2 Mon Sep 17 00:00:00 2001 From: Wes Dean Date: Mon, 14 Sep 2026 18:22:09 -0400 Subject: [PATCH 1/7] test: add AWK lint and unified TAP entry points --- Makefile | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/Makefile b/Makefile index 27f34a1..c3835b7 100644 --- a/Makefile +++ b/Makefile @@ -5,6 +5,7 @@ SHELL := /bin/sh DIST_DIR := dist SOURCE_FILTER := doxygen-python.awk +AWK_SOURCES := $(SOURCE_FILTER) DIST_FILTER := $(DIST_DIR)/doxygen-python.awk DIST_CHECKSUM := $(DIST_FILTER).sha256 AWK_BIN ?= awk @@ -33,7 +34,7 @@ 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 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-docs deps-docs-check distclean docs docs-canary docs-clean integration-clean test test-source test-dist test-doxygen verify-bashdeps FORCE all: build @@ -55,14 +56,25 @@ build: $(SOURCE_FILTER) chmod 0755 "$(DIST_FILTER).tmp" mv "$(DIST_FILTER).tmp" "$(DIST_FILTER)" -## Run the semantic regression suite against maintained source and consumer output. -test: test-source test-dist - -## Run the semantic regression suite against the maintained source file. +## Run GNU awk lint against maintained root AWK sources. +check: + @command -v gawk >/dev/null 2>&1 || { printf '%s\n' 'gawk is required for make check' >&2; exit 1; } + @for source in $(AWK_SOURCES); do \ + printf '%s\n' "Linting $$source"; \ + gawk --lint=fatal -f "$$source" /dev/null; \ + done + +## Run one TAP stream covering maintained source and consumer output. +test: build + AWK_BIN="$(AWK_BIN)" sh ./tests/run-tests.sh \ + "source=$(SOURCE_FILTER)" \ + "dist=$(DIST_FILTER)" + +## Run the TAP semantic regression suite against the maintained source file. test-source: - DOXYGEN_PYTHON_FILTER="$(SOURCE_FILTER)" AWK_BIN="$(AWK_BIN)" sh ./tests/run-tests.sh + AWK_BIN="$(AWK_BIN)" sh ./tests/run-tests.sh "source=$(SOURCE_FILTER)" -## Build and run the semantic suite against the exact consumer artifact. +## Build and run the TAP semantic suite against the exact consumer artifact. 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)" @@ -70,7 +82,7 @@ test-dist: build 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)" - DOXYGEN_PYTHON_FILTER="$(DIST_FILTER)" AWK_BIN="$(AWK_BIN)" sh ./tests/run-tests.sh + AWK_BIN="$(AWK_BIN)" sh ./tests/run-tests.sh "dist=$(DIST_FILTER)" ## Exercise governed Python fixtures through Doxygen with the selected filter. test-doxygen: From e680136f881f43f8c61a8900b4aec716e5ecc4de Mon Sep 17 00:00:00 2001 From: Wes Dean Date: Mon, 14 Sep 2026 18:22:32 -0400 Subject: [PATCH 2/7] test: emit one TAP stream for selected filters --- tests/run-tests.sh | 393 +++++++++++++++++++++++++++++---------------- 1 file changed, 255 insertions(+), 138 deletions(-) diff --git a/tests/run-tests.sh b/tests/run-tests.sh index 5fa8677..5a6f044 100755 --- a/tests/run-tests.sh +++ b/tests/run-tests.sh @@ -6,16 +6,33 @@ TMP_DIR=$(mktemp -d) trap 'rm -rf "$TMP_DIR"' EXIT HUP INT TERM AWK_BIN=${AWK_BIN:-awk} -FILTER=${DOXYGEN_PYTHON_FILTER:-"$ROOT_DIR/doxygen-python.awk"} -case "$FILTER" in - /*) ;; - *) FILTER="$ROOT_DIR/$FILTER" ;; -esac +TEST_NUMBER=0 +FAILURE_COUNT=0 -CASE_COUNT=0 +printf '%s\n' 'TAP version 14' -fail() { - printf 'not ok - %s\n' "$1" >&2 +tap_diag_file() { + while IFS= read -r line || [ -n "$line" ]; do + printf '# %s\n' "$line" + done <"$1" +} + +tap_ok() { + TEST_NUMBER=$((TEST_NUMBER + 1)) + printf 'ok %s - %s\n' "$TEST_NUMBER" "$1" +} + +tap_not_ok() { + TEST_NUMBER=$((TEST_NUMBER + 1)) + FAILURE_COUNT=$((FAILURE_COUNT + 1)) + printf 'not ok %s - %s\n' "$TEST_NUMBER" "$1" + if [ "$#" -gt 1 ] && [ -s "$2" ]; then + tap_diag_file "$2" + fi +} + +bail_out() { + printf 'Bail out! %s\n' "$1" exit 1 } @@ -27,147 +44,247 @@ expected_line_expansion() { grep -Ec '^[[:space:]]*:(yields|rtype):[[:space:]]*[^[:space:]].*$|^[[:space:]]*:type[[:space:]]+[^:[:space:]]+:[[:space:]]*[^[:space:]].*$' "$1" || true } -for expected in "$ROOT_DIR"/tests/python/expected/*.py; do - name=${expected##*/} - input="$ROOT_DIR/tests/python/fixtures/$name" - actual="$TMP_DIR/$name" - errors="$TMP_DIR/$name.err" +resolve_filter() { + case "$1" in + /*) printf '%s\n' "$1" ;; + *) printf '%s/%s\n' "$ROOT_DIR" "$1" ;; + esac +} - test -f "$input" || fail "missing input fixture for $name" - if ! "$AWK_BIN" -f "$FILTER" -- "$input" >"$actual" 2>"$errors"; then - fail "output case failed to execute: $name" - fi - test ! -s "$errors" || fail "output case emitted a diagnostic: $name" - diff -u "$expected" "$actual" || fail "output mismatch: $name" - - expected_lines=$(wc -l <"$input" | tr -d ' ') - expected_lines=$((expected_lines + $(expected_line_expansion "$input"))) - actual_lines=$(wc -l <"$actual" | tr -d ' ') - test "$actual_lines" -eq "$expected_lines" || fail "unexpected line-count change: $name" - - CASE_COUNT=$((CASE_COUNT + 1)) - printf 'ok - output: %s\n' "$name" -done - -for expected in "$ROOT_DIR"/tests/python/programs-expected/*.py; do - name=${expected##*/} - input="$ROOT_DIR/tests/python/programs/$name" - actual="$TMP_DIR/program-$name" - errors="$TMP_DIR/program-$name.err" - - test -f "$input" || fail "missing program input for $name" - if ! "$AWK_BIN" -f "$FILTER" -- "$input" >"$actual" 2>"$errors"; then - fail "program case failed to execute: $name" - fi - test ! -s "$errors" || fail "program case emitted a diagnostic: $name" - diff -u "$expected" "$actual" || fail "program output mismatch: $name" - - expected_lines=$(wc -l <"$input" | tr -d ' ') - expected_lines=$((expected_lines + $(expected_line_expansion "$input"))) - actual_lines=$(wc -l <"$actual" | tr -d ' ') - test "$actual_lines" -eq "$expected_lines" || fail "unexpected program line-count change: $name" - - CASE_COUNT=$((CASE_COUNT + 1)) - printf 'ok - program: %s\n' "$name" -done - -for expected in "$ROOT_DIR"/tests/python/diagnostics/*.err; do - name=${expected##*/} - name=${name%.err} - input="$ROOT_DIR/tests/python/diagnostics/$name.py" - warning_err="$TMP_DIR/$name.warning.err" - strict_err="$TMP_DIR/$name.strict.err" - normalized="$TMP_DIR/$name.normalized.err" - - test -f "$input" || fail "missing diagnostic input for $name" - if ! "$AWK_BIN" -f "$FILTER" -- "$input" >"$TMP_DIR/$name.warning.py" 2>"$warning_err"; then - fail "non-strict diagnostic case exited non-zero: $name" - fi - normalize_warnings "$warning_err" >"$normalized" - diff -u "$expected" "$normalized" || fail "warning mismatch: $name" +run_filter() { + label=$1 + FILTER=$(resolve_filter "$2") + FILTER_TMP="$TMP_DIR/$label" + mkdir -p "$FILTER_TMP" - if "$AWK_BIN" -f "$FILTER" -- --strict "$input" >"$TMP_DIR/$name.strict.py" 2>"$strict_err"; then - fail "strict diagnostic case exited zero: $name" - fi - normalize_warnings "$strict_err" >"$normalized" - diff -u "$expected" "$normalized" || fail "strict warning mismatch: $name" - - CASE_COUNT=$((CASE_COUNT + 1)) - printf 'ok - diagnostic: %s\n' "$name" -done - -malformed_yields="$TMP_DIR/malformed-yields.py" -{ - printf '%s\n' 'def values():' - printf '%s\n' ' """Document values.' - printf '%s\n' '' - printf '%s%s\n' ' :yi' 'elds:' - printf '%s\n' ' """' - printf '%s\n' ' return None' -} >"$malformed_yields" -warning_err="$TMP_DIR/malformed-yields.warning.err" -strict_err="$TMP_DIR/malformed-yields.strict.err" -normalized="$TMP_DIR/malformed-yields.normalized.err" -if ! "$AWK_BIN" -f "$FILTER" -- "$malformed_yields" >"$TMP_DIR/malformed-yields.warning.py" 2>"$warning_err"; then - fail 'non-strict malformed yields case exited non-zero' -fi -normalize_warnings "$warning_err" >"$normalized" -printf '%s\n' 'malformed :yields field' | diff -u - "$normalized" || fail 'malformed yields warning mismatch' -if "$AWK_BIN" -f "$FILTER" -- --strict "$malformed_yields" >"$TMP_DIR/malformed-yields.strict.py" 2>"$strict_err"; then - fail 'strict malformed yields case exited zero' -fi -normalize_warnings "$strict_err" >"$normalized" -printf '%s\n' 'malformed :yields field' | diff -u - "$normalized" || fail 'strict malformed yields warning mismatch' -CASE_COUNT=$((CASE_COUNT + 1)) -printf '%s\n' 'ok - diagnostic: malformed yields field' - -check_malformed_type_field() { - field=$1 - input="$TMP_DIR/malformed-$field.py" - warning_out="$TMP_DIR/malformed-$field.warning.py" - warning_err="$TMP_DIR/malformed-$field.warning.err" - strict_err="$TMP_DIR/malformed-$field.strict.err" - normalized="$TMP_DIR/malformed-$field.normalized.err" - expected_err="$TMP_DIR/malformed-$field.expected.err" + [ -f "$FILTER" ] || bail_out "missing filter: $FILTER" + for expected in "$ROOT_DIR"/tests/python/expected/*.py; do + name=${expected##*/} + input="$ROOT_DIR/tests/python/fixtures/$name" + actual="$FILTER_TMP/$name" + errors="$FILTER_TMP/$name.err" + diff_out="$FILTER_TMP/$name.diff" + description="$label output: $name" + + [ -f "$input" ] || bail_out "missing input fixture for $name" + if ! "$AWK_BIN" -f "$FILTER" -- "$input" >"$actual" 2>"$errors"; then + tap_not_ok "$description" "$errors" + continue + fi + if [ -s "$errors" ]; then + tap_not_ok "$description" "$errors" + continue + fi + if ! diff -u "$expected" "$actual" >"$diff_out"; then + tap_not_ok "$description" "$diff_out" + continue + fi + + expected_lines=$(wc -l <"$input" | tr -d ' ') + expected_lines=$((expected_lines + $(expected_line_expansion "$input"))) + actual_lines=$(wc -l <"$actual" | tr -d ' ') + if [ "$actual_lines" -ne "$expected_lines" ]; then + printf 'expected %s lines, got %s\n' "$expected_lines" "$actual_lines" >"$diff_out" + tap_not_ok "$description" "$diff_out" + continue + fi + + tap_ok "$description" + done + + for expected in "$ROOT_DIR"/tests/python/programs-expected/*.py; do + name=${expected##*/} + input="$ROOT_DIR/tests/python/programs/$name" + actual="$FILTER_TMP/program-$name" + errors="$FILTER_TMP/program-$name.err" + diff_out="$FILTER_TMP/program-$name.diff" + description="$label program: $name" + + [ -f "$input" ] || bail_out "missing program input for $name" + if ! "$AWK_BIN" -f "$FILTER" -- "$input" >"$actual" 2>"$errors"; then + tap_not_ok "$description" "$errors" + continue + fi + if [ -s "$errors" ]; then + tap_not_ok "$description" "$errors" + continue + fi + if ! diff -u "$expected" "$actual" >"$diff_out"; then + tap_not_ok "$description" "$diff_out" + continue + fi + + expected_lines=$(wc -l <"$input" | tr -d ' ') + expected_lines=$((expected_lines + $(expected_line_expansion "$input"))) + actual_lines=$(wc -l <"$actual" | tr -d ' ') + if [ "$actual_lines" -ne "$expected_lines" ]; then + printf 'expected %s lines, got %s\n' "$expected_lines" "$actual_lines" >"$diff_out" + tap_not_ok "$description" "$diff_out" + continue + fi + + tap_ok "$description" + done + + for expected in "$ROOT_DIR"/tests/python/diagnostics/*.err; do + name=${expected##*/} + name=${name%.err} + input="$ROOT_DIR/tests/python/diagnostics/$name.py" + warning_err="$FILTER_TMP/$name.warning.err" + strict_err="$FILTER_TMP/$name.strict.err" + normalized="$FILTER_TMP/$name.normalized.err" + diff_out="$FILTER_TMP/$name.diff" + description="$label diagnostic: $name" + + [ -f "$input" ] || bail_out "missing diagnostic input for $name" + if ! "$AWK_BIN" -f "$FILTER" -- "$input" >"$FILTER_TMP/$name.warning.py" 2>"$warning_err"; then + tap_not_ok "$description" "$warning_err" + continue + fi + normalize_warnings "$warning_err" >"$normalized" + if ! diff -u "$expected" "$normalized" >"$diff_out"; then + tap_not_ok "$description" "$diff_out" + continue + fi + + if "$AWK_BIN" -f "$FILTER" -- --strict "$input" >"$FILTER_TMP/$name.strict.py" 2>"$strict_err"; then + printf '%s\n' 'strict diagnostic case exited zero' >"$diff_out" + tap_not_ok "$description" "$diff_out" + continue + fi + normalize_warnings "$strict_err" >"$normalized" + if ! diff -u "$expected" "$normalized" >"$diff_out"; then + tap_not_ok "$description" "$diff_out" + continue + fi + + tap_ok "$description" + done + + malformed_yields="$FILTER_TMP/malformed-yields.py" { - printf '%s\n' 'def load(path):' - printf '%s\n' ' """Document a deliberately unannotated value.' + printf '%s\n' 'def values():' + printf '%s\n' ' """Document values.' printf '%s\n' '' - if [ "$field" = type ]; then - printf '%s%s%s\n' ' :' "$field" ' path:' + printf '%s%s\n' ' :yi' 'elds:' + printf '%s\n' ' """' + printf '%s\n' ' return None' + } >"$malformed_yields" + warning_err="$FILTER_TMP/malformed-yields.warning.err" + strict_err="$FILTER_TMP/malformed-yields.strict.err" + normalized="$FILTER_TMP/malformed-yields.normalized.err" + expected_err="$FILTER_TMP/malformed-yields.expected.err" + diff_out="$FILTER_TMP/malformed-yields.diff" + description="$label diagnostic: malformed yields field" + printf '%s\n' 'malformed :yields field' >"$expected_err" + if ! "$AWK_BIN" -f "$FILTER" -- "$malformed_yields" >"$FILTER_TMP/malformed-yields.warning.py" 2>"$warning_err"; then + tap_not_ok "$description" "$warning_err" + else + normalize_warnings "$warning_err" >"$normalized" + if ! diff -u "$expected_err" "$normalized" >"$diff_out"; then + tap_not_ok "$description" "$diff_out" + elif "$AWK_BIN" -f "$FILTER" -- --strict "$malformed_yields" >"$FILTER_TMP/malformed-yields.strict.py" 2>"$strict_err"; then + printf '%s\n' 'strict malformed yields case exited zero' >"$diff_out" + tap_not_ok "$description" "$diff_out" else - printf '%s%s%s\n' ' :' "$field" ':' + normalize_warnings "$strict_err" >"$normalized" + if ! diff -u "$expected_err" "$normalized" >"$diff_out"; then + tap_not_ok "$description" "$diff_out" + else + tap_ok "$description" + fi fi - printf '%s\n' ' """' - printf '%s\n' ' return path' - } >"$input" - - if ! "$AWK_BIN" -f "$FILTER" -- "$input" >"$warning_out" 2>"$warning_err"; then - fail "non-strict malformed $field case exited non-zero" fi - cmp "$input" "$warning_out" >/dev/null || fail "malformed $field source was rewritten" - normalize_warnings "$warning_err" >"$normalized" - printf '%s%s%s\n' 'malformed :' "$field" ' field' >"$expected_err" - diff -u "$expected_err" "$normalized" || fail "malformed $field warning mismatch" - if "$AWK_BIN" -f "$FILTER" -- --strict "$input" >"$TMP_DIR/malformed-$field.strict.py" 2>"$strict_err"; then - fail "strict malformed $field case exited zero" - fi - normalize_warnings "$strict_err" >"$normalized" - diff -u "$expected_err" "$normalized" || fail "strict malformed $field warning mismatch" + for field in type rtype; do + input="$FILTER_TMP/malformed-$field.py" + warning_out="$FILTER_TMP/malformed-$field.warning.py" + warning_err="$FILTER_TMP/malformed-$field.warning.err" + strict_err="$FILTER_TMP/malformed-$field.strict.err" + normalized="$FILTER_TMP/malformed-$field.normalized.err" + expected_err="$FILTER_TMP/malformed-$field.expected.err" + diff_out="$FILTER_TMP/malformed-$field.diff" + description="$label diagnostic: malformed $field field" - CASE_COUNT=$((CASE_COUNT + 1)) - printf 'ok - diagnostic: malformed %s field\n' "$field" + { + printf '%s\n' 'def load(path):' + printf '%s\n' ' """Document a deliberately unannotated value.' + printf '%s\n' '' + if [ "$field" = type ]; then + printf '%s%s%s\n' ' :' "$field" ' path:' + else + printf '%s%s%s\n' ' :' "$field" ':' + fi + printf '%s\n' ' """' + printf '%s\n' ' return path' + } >"$input" + printf '%s%s%s\n' 'malformed :' "$field" ' field' >"$expected_err" + + if ! "$AWK_BIN" -f "$FILTER" -- "$input" >"$warning_out" 2>"$warning_err"; then + tap_not_ok "$description" "$warning_err" + continue + fi + if ! cmp "$input" "$warning_out" >/dev/null; then + printf '%s\n' "malformed $field source was rewritten" >"$diff_out" + tap_not_ok "$description" "$diff_out" + continue + fi + normalize_warnings "$warning_err" >"$normalized" + if ! diff -u "$expected_err" "$normalized" >"$diff_out"; then + tap_not_ok "$description" "$diff_out" + continue + fi + + if "$AWK_BIN" -f "$FILTER" -- --strict "$input" >"$FILTER_TMP/malformed-$field.strict.py" 2>"$strict_err"; then + printf '%s\n' "strict malformed $field case exited zero" >"$diff_out" + tap_not_ok "$description" "$diff_out" + continue + fi + normalize_warnings "$strict_err" >"$normalized" + if ! diff -u "$expected_err" "$normalized" >"$diff_out"; then + tap_not_ok "$description" "$diff_out" + continue + fi + + tap_ok "$description" + done + + runtime="$FILTER_TMP/08-runtime-triple-string.py" + description="$label boundary: runtime triple string preserved" + if [ ! -f "$runtime" ]; then + printf '%s\n' 'runtime triple-quoted fixture output is missing' >"$FILTER_TMP/runtime.diff" + tap_not_ok "$description" "$FILTER_TMP/runtime.diff" + elif ! grep -Fq ':param fake: This is data, not documentation.' "$runtime"; then + printf '%s\n' 'runtime triple-quoted string was rewritten' >"$FILTER_TMP/runtime.diff" + tap_not_ok "$description" "$FILTER_TMP/runtime.diff" + else + tap_ok "$description" + fi } -check_malformed_type_field type -check_malformed_type_field rtype +if [ "$#" -eq 0 ]; then + run_filter source "${DOXYGEN_PYTHON_FILTER:-doxygen-python.awk}" +else + for selected in "$@"; do + case "$selected" in + *=*) + label=${selected%%=*} + filter=${selected#*=} + ;; + *) + label=${selected##*/} + filter=$selected + ;; + esac + [ -n "$label" ] || bail_out 'filter label must not be empty' + [ -n "$filter" ] || bail_out 'filter path must not be empty' + run_filter "$label" "$filter" + done +fi -runtime="$TMP_DIR/08-runtime-triple-string.py" -grep -Fq ':param fake: This is data, not documentation.' "$runtime" || \ - fail 'runtime triple-quoted string was rewritten' -CASE_COUNT=$((CASE_COUNT + 1)) -printf '%s\n' 'ok - boundary: runtime triple string preserved' +printf '1..%s\n' "$TEST_NUMBER" -printf 'ok - %s regression cases passed with %s\n' "$CASE_COUNT" "$AWK_BIN" +if [ "$FAILURE_COUNT" -ne 0 ]; then + exit 1 +fi From 6d37e6a776bdf71beb224af10304f4bbcb1a9287 Mon Sep 17 00:00:00 2001 From: Wes Dean Date: Mon, 14 Sep 2026 18:22:40 -0400 Subject: [PATCH 3/7] ci: add dedicated GNU awk lint job --- .github/workflows/test.yml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index dfd9b3e..ab4931e 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -10,6 +10,15 @@ permissions: contents: read jobs: + lint: + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - name: Install GNU awk + run: sudo apt-get update && sudo apt-get install -y gawk + - name: Lint maintained AWK sources + run: make check + semantic: runs-on: ubuntu-24.04 strategy: From ad939d7e82c0437f6330dfc686603700512d9805 Mon Sep 17 00:00:00 2001 From: Wes Dean Date: Mon, 14 Sep 2026 18:22:47 -0400 Subject: [PATCH 4/7] ci: lint maintained AWK source before release --- .github/workflows/semver.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/semver.yml b/.github/workflows/semver.yml index 0e4c0bb..5546e3d 100644 --- a/.github/workflows/semver.yml +++ b/.github/workflows/semver.yml @@ -29,7 +29,7 @@ jobs: - name: Install release validation tools run: | sudo apt-get update - sudo apt-get install --yes doxygen mawk + sudo apt-get install --yes doxygen mawk gawk - name: calculate version id: calculate-version @@ -40,7 +40,7 @@ jobs: tag_prefix: v - name: Validate maintained source - run: make test-source AWK_BIN=mawk + run: make check test-source AWK_BIN=mawk - name: Build and validate release artifact run: | From 0cfdb53866674b0dc0dcbd5d7e48bfed6954ea8a Mon Sep 17 00:00:00 2001 From: Wes Dean Date: Mon, 14 Sep 2026 18:23:06 -0400 Subject: [PATCH 5/7] docs: document lint and TAP test workflow --- README.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index cf86a51..ff92cc5 100644 --- a/README.md +++ b/README.md @@ -104,15 +104,26 @@ validate whether annotations should have been used instead. ## Tests and build artifacts -Run the semantic suite against maintained source and generated consumer bytes: +Run GNU awk's fatal lint mode against maintained root AWK sources with: + +```sh +make check +``` + +Linting is intentionally separate from semantic testing. Run the semantic suite +against maintained source and generated consumer bytes with: ```sh make test AWK_BIN=mawk make test AWK_BIN=gawk ``` -CI runs both implementations and a Doxygen integration job. Build the consumer -artifact and checksum with: +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. + +CI runs GNU awk linting, both supported semantic AWK implementations, and a +Doxygen integration job. Build the consumer artifact and checksum with: ```sh make build @@ -209,4 +220,4 @@ Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and ## Author -- Wes Dean +- Wes Dean \ No newline at end of file From 5df7e373b70aab0fe5ed0c03b321d09fe2198742 Mon Sep 17 00:00:00 2001 From: Wes Dean Date: Mon, 14 Sep 2026 18:23:14 -0400 Subject: [PATCH 6/7] docs: document lint and TAP validation --- AGENTS.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c5f139d..1240b4d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,7 +56,10 @@ 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`. -Use `make test AWK_BIN=mawk` and `make test AWK_BIN=gawk`. Preserve source-line +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. @@ -99,4 +102,4 @@ asset-level validation. Keep changes surgical and reviewable. Accuracy is more important than apparent completeness. Distinguish implemented behavior from planned behavior, state uncertainty explicitly, and do not widen the parser boundary without governance -and focused fixtures. +and focused fixtures. \ No newline at end of file From d8a483dd7190f7edcddb63c8e55bf4d119f6a142 Mon Sep 17 00:00:00 2001 From: Wes Dean Date: Mon, 14 Sep 2026 18:27:46 -0400 Subject: [PATCH 7/7] fix: avoid GNU awk global shadowing warnings --- doxygen-python.awk | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/doxygen-python.awk b/doxygen-python.awk index ad35ad8..95eff2d 100644 --- a/doxygen-python.awk +++ b/doxygen-python.awk @@ -307,51 +307,51 @@ function translate_doc_line(line, indent, body, name, desc, exc) { ## @rule translate_source_record ## @brief Passes source through and translates fields in recognized docstrings. { - line = $0 + source_line = $0 if (in_docstring) { - if (index(line, "\"\"\"") > 0) { in_docstring = 0; print line; next } - print translate_doc_line(line) + if (index(source_line, "\"\"\"") > 0) { in_docstring = 0; print source_line; next } + print translate_doc_line(source_line) next } if (in_declaration) { - if (declaration_header_complete(line)) { + if (declaration_header_complete(source_line)) { in_declaration = 0 pending_suite = 1 pending_indent = declaration_indent } - print line + print source_line next } if (pending_suite) { - if (is_blank_or_comment(line)) { print line; next } - if (leading_width(line) > pending_indent && starts_docstring(line)) { + if (is_blank_or_comment(source_line)) { print source_line; next } + if (leading_width(source_line) > pending_indent && starts_docstring(source_line)) { pending_suite = 0 - if (!closes_same_line(line)) in_docstring = 1 - print line + if (!closes_same_line(source_line)) in_docstring = 1 + print source_line next } pending_suite = 0 } if (module_doc_possible) { - if (is_blank_or_comment(line)) { print line; next } - if (leading_width(line) == 0 && starts_docstring(line)) { + if (is_blank_or_comment(source_line)) { print source_line; next } + if (leading_width(source_line) == 0 && starts_docstring(source_line)) { module_doc_possible = 0 - if (!closes_same_line(line)) in_docstring = 1 - print line + if (!closes_same_line(source_line)) in_docstring = 1 + print source_line next } - if (leading_width(line) == 0) module_doc_possible = 0 + if (leading_width(source_line) == 0) module_doc_possible = 0 } - if (is_declaration_start(line)) { - declaration_indent = leading_width(line) - if (declaration_header_complete(line)) { + if (is_declaration_start(source_line)) { + declaration_indent = leading_width(source_line) + if (declaration_header_complete(source_line)) { pending_suite = 1 pending_indent = declaration_indent } else { in_declaration = 1 } } - print line + print source_line } ## @rule finalize_filter