Fix results ordering, control file whitespace, ENABLE_* override, debug levels

[jnasbyupgrade]

Related pgxntool-test PR: Postgres-Extensions/pgxntool-test#19

Summary

• Fix results: prerequisite ordering: verify-results ran before make test, checking stale regression.diffs from a prior run; reordered to results: test verify-results
• Fix parse_control_file trailing whitespace: ${value%% } only stripped one trailing space; now uses a regex to strip all trailing spaces and tabs (e.g. default_version = '1.0.0' # comment)
• Add override to PGXNTOOL_ENABLE_TEST_BUILD/PGXNTOOL_ENABLE_TEST_INSTALL so command-line values are normalized by pgxntool_validate_yesno rather than silently ignored
• Fix pgtle.sh debug levels: stray single-digit values (1–4) replaced with verbosity tiers (30/40/50) consistent with the lib.sh scheme
• Rework the debug() level docs in lib.sh and .claude/development.md: levels encode verbosity/esotericness, not code nesting depth (a top-level line can be high if it's esoteric; loop-body detail is high because it's noisy). The 10/20/30/40/50 tiers are anchors, not strict multiples of 10 — any in-range value is fine, so fine-tuning needs no renumbering
• Clarify CLAUDE.md audience: for extension developers using pgxntool, not contributors; redirect contributors to .claude/
• Move developer guidelines (Makefile := rules, debug level rules) from CLAUDE.md into .claude/development.md, which also now prominently states that pgxntool changes must be made from a pgxntool-test checkout
• Update HISTORY.asc with entries for the two user-visible fixes

[jnasbyupgrade]

@claude please review this PR.

[claude]

Claude finished @jnasbyupgrade's task in 3m 44s —— View job

---

Review of PR #31

• Gather context (read diff, changed files)
• Review base.mk changes (results ordering, ENABLE_* override)
• Review lib.sh changes (debug level docs)
• Review pgtle.sh changes (control file parsing, debug levels)
• Review CLAUDE.md / .claude/development.md changes
• Review HISTORY.asc changes
• Post final review

Summary

Overall this is a solid, well-documented set of fixes. The two functional/user-visible fixes (results ordering, control-file whitespace trimming) are correct and the reasoning in the added comments checks out against Make/bash semantics. One inconsistency worth resolving before merge:

Finding: pgtle.sh debug levels don't actually follow the new lib.sh scheme

lib.sh:64-71 (and the mirrored .claude/development.md doc) now documents a nesting-depth-based scheme:

• 1-9: high-level script context (top-level entry/exit, arguments)
• 10-19: per-iteration detail inside loops
• 20-29: nesting inside loop-level detail
• higher ranges follow the same pattern

But the values this PR assigns in pgtle.sh don't follow that pattern — they're a straight substitution of the old tiered scheme (10=critical, 20=warning, 30=general/entry-exit, 40=verbose/loop, 50=max verbosity), just scaled from the stray 1-4 typos to 30/40/50:

• pgtle.sh:159 — debug 30 "Global arrays initialized..." fires at global script scope (not even inside a function), yet is 30. Per the new scheme this is the textbook 1-9 case ("top-level entry/exit").
• pgtle.sh:838 — debug 50 "generate_pgtle_sql: Processing upgrade file $i..." is the one call that's genuinely inside a loop, per-iteration — exactly the doc's 10-19 example ("entry (11)") — but it's assigned 50, the opposite end of the range.
• None of the 17 debug calls in pgtle.sh use anything in 1-9 or 10-19, despite the file containing multiple loops (discover_sql_files, generate_pgtle_sql's upgrade-path loop).

Pre-existing usage in update-setup-files.sh:65,85,128 (debug 20/debug 30, flat, non-nested) shows the tiered convention is what's actually used elsewhere in the codebase too — so this may just mean the new doc describes an aspirational scheme nothing follows yet, rather than a bug unique to this PR. But as written, the PR body's claim ("range-based values ... per lib.sh convention") isn't quite accurate: the new lib.sh convention is about nesting depth, and these values don't reflect nesting depth. Worth either:

1. Renumbering the pgtle.sh calls to reflect actual nesting (top-level ≈ 1-9, the one real loop iteration ≈ 10-19), or
2. Adjusting the lib.sh/development.md doc to describe the tiered-verbosity scheme that's actually in use.

Fix this →

Other things checked, no issues found

• base.mk:303-309 — the verify-results: test / results: verify-results dependency chain correctly forces serialization even under make -j; the recipe at base.mk:310-314 merges correctly with the prerequisite-only rule (standard Make behavior for multiple rules on the same target).
• base.mk:96-98,140-142 — adding override to PGXNTOOL_ENABLE_TEST_BUILD/PGXNTOOL_ENABLE_TEST_INSTALL is correct and brings them in line with the pre-existing PGXNTOOL_ENABLE_VERIFY_RESULTS pattern (base.mk:176), which already used override := for the same reason.
• pgtle.sh:466-474 — the new regex-based trailing-whitespace strip correctly handles multiple spaces/tabs before a comment, unlike the old ${value%% } (which only strips one literal space char). No regex-injection concern since value is the subject, not the pattern, in the [[ =~ ]] test.
• .gitattributes already export-ignores .claude/ and *.md, so the new .claude/development.md won't leak into git subtree distributions.
• CLAUDE.md/HISTORY.asc edits are clear and consistent with the rest of the docs.

I did not run make test (no live Postgres in this environment) — the two functional fixes were verified by code reading against Make/bash semantics rather than execution.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 2c7d40a3-03e1-4da6-93a9-0d5512564106

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}