Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/semver.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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: |
Expand Down
9 changes: 9 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
7 changes: 5 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
28 changes: 20 additions & 8 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -55,22 +56,33 @@ 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 >/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)"
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)"
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:
Expand Down
19 changes: 15 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -209,4 +220,4 @@ Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and

## Author

- Wes Dean
- Wes Dean
36 changes: 18 additions & 18 deletions doxygen-python.awk
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Loading