Fix test/install, add test-build, verify-results, docs

[jnasbyupgrade]

test-build: Useful error messages for SQL syntax errors

When CREATE EXTENSION fails due to a syntax error, PostgreSQL reports a
cryptic error with limited context. test-build runs your extension SQL directly
through pg_regress first, so errors show the exact file, line, and position —
cutting debugging time significantly.

Place SQL files in test/build/ to enable. Auto-detects based on file presence.

test/install: Run expensive setup once instead of per-test

Extensions that install dependencies or load fixtures in every test file pay
that cost once per test. test/install runs setup SQL once before the entire
suite, and all regular tests share the resulting database state. This can
dramatically speed up test suites.

Place SQL files in test/install/ to enable. Auto-detects based on file presence.

• Uses a pg_regress schedule file so install and test files run in a single
  invocation (database state persists across phases)
• Expected output lives alongside .sql files as test/install/*.out

verify-results: Prevent blessing incorrect test output

make results now refuses to run when tests are failing. Prevents accidentally
updating expected files with wrong output. Disable with
PGXNTOOL_ENABLE_VERIFY_RESULTS=no.

Other changes

• Add .asc as a recognized asciidoc extension
• Document all new features in README

Companion PR: Postgres-Extensions/pgxntool-test#7

[jnasbyupgrade]

Enhancement request: Override mechanism for install/build file lists

I'm planning to use the test/install support for pg_tle integration in my extensions monorepo. The auto-detection is great for the common case, but I need to control which files run and in what order. Two requests:

1. Documented override for test/install and test-build file lists

TEST_INSTALL_SQL_FILES is auto-populated via wildcard, and the schedule is generated directly from it. There's no clean way to:

• Control ordering: Wildcard gives filesystem order. I need pgtle-setup to run before extensions.
• Conditionally include files: I have a pgtle-setup.sql that should only run when PGTLE_MODE is set (Docker/RDS uses pg_tle; local PGXS doesn't).

Suggested approach: Expose an intermediate variable that the schedule generation uses, documented as the public API for overriding:

# Default: auto-detected from test/install/*.sql (unordered)
# Projects can override for ordering or conditional inclusion.
PGXNTOOL_INSTALL_TESTS ?= $(notdir $(basename $(TEST_INSTALL_SQL_FILES)))

$(PGXNTOOL_INSTALL_SCHEDULE):
	@echo "# Auto-generated - DO NOT EDIT" > $@
	@for f in $(PGXNTOOL_INSTALL_TESTS); do \
		echo "test: ../install/$$f" >> $@; \
	done

Then projects can do:

include pgxntool/base.mk

# Explicit ordering + conditional pg_tle setup
PGXNTOOL_INSTALL_TESTS = extensions
ifdef PGTLE_MODE
PGXNTOOL_INSTALL_TESTS := pgtle-setup $(PGXNTOOL_INSTALL_TESTS)
endif

Same pattern would be useful for test-build (PGXNTOOL_BUILD_TESTS). The auto-detect remains the default — this just gives projects an escape hatch with a stable API.

2. Document new make targets to help with conflicts

Projects that already hand-coded test-build or verify-results (like my archive extension) will hit recipe conflicts on upgrade. The PGXNTOOL_ENABLE_* variables handle this, but only if people know about them.

Suggestions:

• README should have a "New Targets" or "Upgrading" section listing all new target names so upgraders can check for conflicts
• Ideally upgrade.sh could grep the project Makefile for potential conflicts with newly-introduced targets (e.g., grep -w 'test-build\|verify-results' Makefile). This is tricky since you'd be upgrading across potentially many pgxntool versions, but even a best-effort warning would help. Not a blocker for this PR though.

[jnasbyupgrade]

.source files would also be checked in

[jnasbyupgrade]

This is almost the same code as for test/build; propose ways (in a comment) it could be refactored. We certainly want the code to remain clear, but I'm hoping we can remove some of the duplication.

See verify-results as well; it's pretty similar as well.

[jnasbyupgrade]

can't these two lines be combined with 267?

[jnasbyupgrade]

Hmm... lets also add pgtap as an option (and make it the default). This mode would assume that all test output is from pgTap, and look for anything that indicates a test failure. This should be in addition the checks we already have around regression.diff.

Here's the way I'm handling this in another project:

verify-results:
        @failed=0; \
        if grep -Hn '^not ok' test/results/*.out 2>/dev/null | grep -v '# TODO'; then \
                failed=1; \
        fi; \
        if grep -Hn 'Looks like you planned' test/results/*.out 2>/dev/null; then \
                failed=1; \
        fi; \
        if [ $$failed -eq 1 ]; then \
                echo "ERROR: Failed tests found in results files (see above)"; \
                exit 1; \
        fi
        @echo "test/results/ files are clean (no 'not ok' lines or plan count mismatches found, TODO tests ignored)"

[jnasbyupgrade]

Need a comment on why we even need to do this

[jnasbyupgrade]

s/;/ and/

[jnasbyupgrade]

drop this line

[jnasbyupgrade]

Add a comment that this sets onerrorfail (or whatever the variable is called)

[jnasbyupgrade]

add comment on why this is desirable

[jnasbyupgrade]

Add comment above this line that if the build actually failed psql would stop immediately because of error handling set by psql.sql.