chore: replace ambiguous Unicode characters across compose-scripts + bats tests (sister of #149) #150

New issue

Closed

opened 2026-06-27 01:32:13 +02:00 by quartermaster · 0 comments

quartermaster commented

2026-06-27 01:32:13 +02:00

Owner

The phenomenon

Operator surfaced 2026-06-27: the same ambiguous-Unicode pattern that Forgejo's lint flags on _release.yml + release.yml (#149) appears across the bash compose-scripts AND bats test files too. Neither bash nor bats is currently lint-flagged by Forgejo (their lint scope is workflow YAML), but the look-alike-character readability + consistency-with-#149 concern applies + the bats test assertions track the scripts' log output (so they must change in lockstep).

Inventory

Compose-scripts (11 files, ~160 occurrences)

File	Occurrences
`scripts/release-prep.sh`	28
`scripts/release-decide.sh`	25
`scripts/lib/fragments.sh`	24
`scripts/manifest-precheck.sh`	16
`scripts/lib/conventional-commits.sh`	14
`scripts/lib/config.sh`	13
`scripts/manifest-check.sh`	10
`scripts/draft-release.sh`	9
`scripts/lib/forgejo-api.sh`	9
`scripts/lib/changelog.sh`	6
`scripts/lib/semver.sh`	6
Scripts subtotal	~160

Bats tests (12 files, ~159 occurrences)

File	Occurrences
`tests/release-decide.bats`	39
`tests/fragments.bats`	21
`tests/manifest-check.bats`	20
`tests/manifest-precheck.bats`	18
`tests/release-prep.bats`	18
`tests/draft-release.bats`	11
`tests/check-self-bootstrap.bats`	10
`tests/conventional-commits.bats`	8
`tests/changelog.bats`	5
`tests/semver.bats`	5
`tests/config.bats`	2
`tests/workflows.bats`	2
Bats subtotal	~159

Combined total: ~319 occurrences

Unique characters present

Four characters beyond #149's set (em-dash, arrow, alpha, gamma, section):

Character	Codepoint	Source-of-use
`—`	U+2014 em-dash	Comments + log strings
`→`	U+2192 right arrow	Comments + log strings
`α`	U+03B1 alpha	"path-α" jargon
`γ`	U+03B3 gamma	"path-γ" jargon
`§`	U+00A7 section sign	"AGENTS.md §2" / "design doc §X" references
`×`	U+00D7 multiplication	Math notation in retry-loop comments ("3 retries × 5s")
`…`	U+2026 ellipsis	Comments for elided content
`∈`	U+2208 element-of	Math notation in fragment-bump compositions
`≠`	U+2260 not-equal	Math notation in bats assertions/comments

Replacement scheme (extends #149)

From	To
`—`	`-` (or `--`)
`→`	`->`
`α`	`alpha`
`γ`	`gamma`
`§`	`section` or `sec.`
`×`	`x` (e.g., "3 retries x 5s")
`…`	`...`
`∈`	`in` (e.g., "x in {set}")
`≠`	`!=` or `not equal`

Why bundle scripts + bats

The bats tests assert on log output from the scripts via [[ "$output" == *"…"* ]] patterns. When a script's log() line changes from "manifest update — idempotent skip" to "manifest update - idempotent skip", the corresponding bats assertion must change in lockstep. Splitting scripts + bats into separate PRs would mean the scripts' PR temporarily breaks bats; one PR keeps the lockstep consistent.

Scope decisions worth noting

Scripts + bats only, not the comprehensive sweep

ADR docs + markdown comments + other repo content remain unchanged. The Greek-letter jargon (path-α/path-γ) IS established naming from ADR-0007; replacing in scripts means switching to path-alpha/path-gamma in code while leaving ADR docs using the original characters. The ADR-vs-code naming drift is the smallest cost; the alternative (sweep ADRs too) would be a much bigger PR.

Log-output cosmetic changes

Bash log() / printf / echo lines containing these characters will change their runtime log output text. No behavioral change. Bats assertions tracking those strings will be updated in the same PR.

Composition with #149 + #148

Compose-script touch (all 11 files): AGENTS.md §2 mechanism-of-touch applies. After merge, in-cycle re-pin needed (#124 backstop will surface red on push:main until the re-pin lands).
Can ship before, after, or bundled with #149: same kind of cleanup, similar mechanical nature. Bundling all three (#149 workflow YAML + #150 scripts + bats) into one PR reduces re-pin count to 1.
Sequencing relative to #148: independent. If #148 ships first, the build-bake refactor doesn't touch the Unicode in script bodies; this tracker still applies cleanly.

Implementation surface

11 compose-script files modified
12 bats test files modified
AGENTS.md note: "compose-scripts + bats use ASCII only; ADR + markdown docs retain Unicode latitude"
Estimated ~2-3 PR cycles (file substitutions are mechanical; bats assertion-tracking is the substantive coordination)

What this PR does NOT do

Does NOT touch ADR or markdown documentation (those retain Unicode latitude)
Does NOT change runtime behavior (substitutions in comments + log strings only)
Does NOT add an automated lint regression guard — out of scope; could be a bats schema check if the pattern recurs

Refs

Sister tracker: #149 (workflow YAML Unicode cleanup)
Operator engagement 2026-06-27: identified the spread to bash scripts + bats tests after #149 surfaced the YAML cases
Composition: AGENTS.md §2 (mechanism-of-touch); #124 backstop (post-merge red until re-pin); ADR-0007 (where the path-α/γ jargon originates)

## The phenomenon Operator surfaced 2026-06-27: the same ambiguous-Unicode pattern that Forgejo's lint flags on `_release.yml` + `release.yml` ([#149](https://git.frankenbit.de/frankenbit/release-toolkit/issues/149)) appears across the **bash compose-scripts** AND **bats test files** too. Neither bash nor bats is currently lint-flagged by Forgejo (their lint scope is workflow YAML), but the look-alike-character readability + consistency-with-#149 concern applies + the bats test assertions track the scripts' log output (so they must change in lockstep). ## Inventory ### Compose-scripts (11 files, ~160 occurrences) | File | Occurrences | |---|---| | `scripts/release-prep.sh` | 28 | | `scripts/release-decide.sh` | 25 | | `scripts/lib/fragments.sh` | 24 | | `scripts/manifest-precheck.sh` | 16 | | `scripts/lib/conventional-commits.sh` | 14 | | `scripts/lib/config.sh` | 13 | | `scripts/manifest-check.sh` | 10 | | `scripts/draft-release.sh` | 9 | | `scripts/lib/forgejo-api.sh` | 9 | | `scripts/lib/changelog.sh` | 6 | | `scripts/lib/semver.sh` | 6 | | **Scripts subtotal** | **~160** | ### Bats tests (12 files, ~159 occurrences) | File | Occurrences | |---|---| | `tests/release-decide.bats` | 39 | | `tests/fragments.bats` | 21 | | `tests/manifest-check.bats` | 20 | | `tests/manifest-precheck.bats` | 18 | | `tests/release-prep.bats` | 18 | | `tests/draft-release.bats` | 11 | | `tests/check-self-bootstrap.bats` | 10 | | `tests/conventional-commits.bats` | 8 | | `tests/changelog.bats` | 5 | | `tests/semver.bats` | 5 | | `tests/config.bats` | 2 | | `tests/workflows.bats` | 2 | | **Bats subtotal** | **~159** | ### Combined total: ~319 occurrences ## Unique characters present Four characters beyond #149's set (em-dash, arrow, alpha, gamma, section): | Character | Codepoint | Source-of-use | |---|---|---| | `—` | U+2014 em-dash | Comments + log strings | | `→` | U+2192 right arrow | Comments + log strings | | `α` | U+03B1 alpha | "path-α" jargon | | `γ` | U+03B3 gamma | "path-γ" jargon | | `§` | U+00A7 section sign | "AGENTS.md §2" / "design doc §X" references | | `×` | U+00D7 multiplication | Math notation in retry-loop comments ("3 retries × 5s") | | `…` | U+2026 ellipsis | Comments for elided content | | `∈` | U+2208 element-of | Math notation in fragment-bump compositions | | `≠` | U+2260 not-equal | Math notation in bats assertions/comments | ## Replacement scheme (extends #149) | From | To | |---|---| | `—` | `-` (or `--`) | | `→` | `->` | | `α` | `alpha` | | `γ` | `gamma` | | `§` | `section` or `sec.` | | `×` | `x` (e.g., "3 retries x 5s") | | `…` | `...` | | `∈` | `in` (e.g., "x in {set}") | | `≠` | `!=` or `not equal` | ## Why bundle scripts + bats The bats tests assert on log output from the scripts via `[[ "$output" == *"…"* ]]` patterns. When a script's `log()` line changes from `"manifest update — idempotent skip"` to `"manifest update - idempotent skip"`, the corresponding bats assertion must change in lockstep. Splitting scripts + bats into separate PRs would mean the scripts' PR temporarily breaks bats; one PR keeps the lockstep consistent. ## Scope decisions worth noting ### Scripts + bats only, not the comprehensive sweep ADR docs + markdown comments + other repo content remain unchanged. The Greek-letter jargon (`path-α`/`path-γ`) IS established naming from ADR-0007; replacing in scripts means switching to `path-alpha`/`path-gamma` in code while leaving ADR docs using the original characters. The ADR-vs-code naming drift is the smallest cost; the alternative (sweep ADRs too) would be a much bigger PR. ### Log-output cosmetic changes Bash `log()` / `printf` / `echo` lines containing these characters will change their **runtime log output text**. No behavioral change. Bats assertions tracking those strings will be updated in the same PR. ## Composition with #149 + #148 - **Compose-script touch (all 11 files)**: AGENTS.md §2 mechanism-of-touch applies. After merge, in-cycle re-pin needed (#124 backstop will surface red on push:main until the re-pin lands). - **Can ship before, after, or bundled with #149**: same kind of cleanup, similar mechanical nature. Bundling all three (#149 workflow YAML + #150 scripts + bats) into one PR reduces re-pin count to 1. - **Sequencing relative to [#148](https://git.frankenbit.de/frankenbit/release-toolkit/issues/148)**: independent. If #148 ships first, the build-bake refactor doesn't touch the Unicode in script bodies; this tracker still applies cleanly. ## Implementation surface - 11 compose-script files modified - 12 bats test files modified - AGENTS.md note: "compose-scripts + bats use ASCII only; ADR + markdown docs retain Unicode latitude" - Estimated ~2-3 PR cycles (file substitutions are mechanical; bats assertion-tracking is the substantive coordination) ## What this PR does NOT do - **Does NOT touch ADR or markdown documentation** (those retain Unicode latitude) - **Does NOT change runtime behavior** (substitutions in comments + log strings only) - **Does NOT add an automated lint regression guard** — out of scope; could be a bats schema check if the pattern recurs ## Refs - **Sister tracker**: [#149](https://git.frankenbit.de/frankenbit/release-toolkit/issues/149) (workflow YAML Unicode cleanup) - **Operator engagement 2026-06-27**: identified the spread to bash scripts + bats tests after #149 surfaced the YAML cases - **Composition**: AGENTS.md §2 (mechanism-of-touch); #124 backstop (post-merge red until re-pin); ADR-0007 (where the path-α/γ jargon originates)

quartermaster changed title from ~~chore: replace ambiguous Unicode characters across all compose-scripts (sister of #149)~~ to chore: replace ambiguous Unicode characters across compose-scripts + bats tests (sister of #149)

2026-06-27 01:33:04 +02:00

quartermaster referenced this issue

2026-06-27 01:34:19 +02:00

chore: audit-cleanup of .keep files (drop unused, document load-bearing ones) #151

quartermaster referenced this issue

2026-06-27 01:46:13 +02:00

chore: reconsider underscore-prefix convention for reusable workflow filenames (aesthetic) #155

quartermaster referenced this issue

2026-06-27 01:56:27 +02:00

audit: security pass (token leaks, injection vectors, trust model, sed-rewrite hardening) #156

quartermaster referenced this issue

2026-06-27 02:05:09 +02:00