Lint unreadable Python assertion one-liners in BATS tests

[junior-ricon]

Problem

During review of KnickKnackLabs/notes#127, Or caught an unreadable BATS test shape: assertions were embedded as long python3 -c "..." one-liners.

Example smell:

echo "$output" | python3 -c "import sys, json; data = json.load(sys.stdin); assert data['frontmatter'] == {}; assert ..."

This technically works, but it is hard to review, hard to diff, and easy to normalize across repos. BATS tests should read like tests, not compressed shell/Python puzzles.

Fold's notes/bats-tool-testing.md already covers the broader BATS principle: call the tool through mise and keep tests close to real usage. This issue proposes a future codebase lint that catches the readability variant for Python assertion one-liners in .bats files.

Proposed lint

Detect suspicious Python one-liners in BATS tests, especially:

• python3 -c "...assert..."
• python -c "...assert..."
• long python3 -c commands embedded directly in a test body;
• maybe jq / ruby -e / node -e one-liners above a length threshold in .bats, if the pattern generalizes.

Preferred alternatives:

1. write $output to a temp JSON/file and run a readable heredoc Python script;
2. factor repeated assertions into a helper script under test/;
3. use jq for simple JSON checks when readable;
4. if using inline Python, keep it trivial and below a small threshold.

Good shape:

json_file="$BATS_TEST_TMPDIR/parse.json"
printf '%s\n' "$output" > "$json_file"
python3 - "$json_file" <<'PY'
import json
import sys

data = json.load(open(sys.argv[1]))
assert data["frontmatter"] == {}
assert data["frontmatter_present"] is False
assert data["diagnostics"] == []
PY

Acceptance criteria

• Add a codebase lint rule that reports unreadable python -c / python3 -c assertion one-liners in .bats files.
• Include fixture coverage for:
  • long python3 -c with assert => flagged;
  • short harmless python3 -c 'print(...)' if allowed => not flagged or low severity;
  • heredoc Python assertion style => not flagged.
• Link documentation or message text to fold notes/bats-tool-testing.md.

Related

• Review example: KnickKnackLabs/notes#127
• Fold guidance: notes/bats-tool-testing.md