frankenbit/release-toolkit

Fork 0

feat(semver): implement Parser + Version against #505 interface (TDD against bash byte-oracle) #523

New issue

Closed

opened 2026-07-25 19:51:50 +02:00 by bosun · 1 comment

bosun commented

2026-07-25 19:51:50 +02:00

Owner

Implement internal/semver package satisfying the Go interface landed in #505.

Motivation

Phase 1 kicks off contract-driven TDD-per-phase per ADR-0009 §3.1. internal/semver is one of two Phase 1 pure-logic libs (sibling: #524 conventionalcommits). Interface (Parser, Version + round-trip invariant) is Surveyor-approved in #505; implementation lands here.

Scope

internal/semver/*.go — implementation satisfying #505 interface (Parser.Parse, Version.String, Version comparison, round-trip)
Bash byte-oracle: existing bash implementation in lib/semver.sh is the behavior-of-record. Any observable-surface disagreement between Go impl and bash oracle is either (a) a Go bug or (b) a documented, tracker-filed intentional divergence.
TDD approach (contract-driven per ADR-0009 §3.1):
1. Test against interface first (uses Parser + Version from #505)
2. Oracle harness case using internal/harness (from #503) — Go impl vs bash lib/semver.sh on shared fixture corpus
3. Implementation to green
Fixture corpus at testdata/fixtures/semver/ — coverage of valid + invalid + edge cases (pre-release, build-metadata, sort order)
Property invariant per ADR-0009 §3.2: semver round-trip (parse → String → parse == original), verified via property test

AC

internal/semver implementation compiles + all #505 interface methods satisfied — verified in PR#525 fa31b5d
Unit tests green (go test ./internal/semver/...) — verified in PR#525 gate run
Equivalence-harness cases against bash oracle green — verified: Surveyor reproduced harness byte-equivalence vs real lib/semver.sh (review 4551), harness teeth proven by her own mutation. Substrate discovery: go run collapses non-zero child exits to 1 (would false-RED exit-2 compare-invalid) → TestMain builds binary instead
Round-trip property invariant test green — verified in PR#525
go vet ./... + golangci-lint run clean — verified: gate own instrument (golangci-lint) fired, all clean

Depends on: #505 (interfaces landed), #503 (equivalence-harness framework), #504 (contracts C1-C7 for reference)
Sibling: #524 (conventionalcommits — parallelizable OR sequential Engineer continuation)
Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C6-adjacent (semver as CHANGELOG version emit target), §3.3 phase 1 row, §5 (fail-loud + trivalent-verdict discipline)

Anchor

Filed 2026-07-25 by Bosun on operator continuation direction for Phase 1 dispatch. Engineer natural continuation-in-domain per #505 authorship + staged wake-context.

Implement `internal/semver` package satisfying the Go interface landed in #505. ## Motivation Phase 1 kicks off contract-driven TDD-per-phase per ADR-0009 §3.1. `internal/semver` is one of two Phase 1 pure-logic libs (sibling: [[#524 conventionalcommits]]). Interface (`Parser`, `Version` + round-trip invariant) is Surveyor-approved in #505; implementation lands here. ## Scope - `internal/semver/*.go` — implementation satisfying #505 interface (Parser.Parse, Version.String, Version comparison, round-trip) - **Bash byte-oracle**: existing bash implementation in `lib/semver.sh` is the behavior-of-record. Any observable-surface disagreement between Go impl and bash oracle is either (a) a Go bug or (b) a documented, tracker-filed intentional divergence. - **TDD approach** (contract-driven per ADR-0009 §3.1): 1. Test against interface first (uses `Parser` + `Version` from #505) 2. Oracle harness case using `internal/harness` (from #503) — Go impl vs bash `lib/semver.sh` on shared fixture corpus 3. Implementation to green - Fixture corpus at `testdata/fixtures/semver/` — coverage of valid + invalid + edge cases (pre-release, build-metadata, sort order) - Property invariant per ADR-0009 §3.2: **semver round-trip** (parse → String → parse == original), verified via property test ## AC - [x] `internal/semver` implementation compiles + all `#505` interface methods satisfied — verified in PR#525 fa31b5d - [x] Unit tests green (`go test ./internal/semver/...`) — verified in PR#525 gate run - [x] Equivalence-harness cases against bash oracle green — verified: Surveyor reproduced harness byte-equivalence vs real `lib/semver.sh` (review 4551), harness teeth proven by her own mutation. Substrate discovery: `go run` collapses non-zero child exits to 1 (would false-RED exit-2 compare-invalid) → TestMain builds binary instead - [x] Round-trip property invariant test green — verified in PR#525 - [x] `go vet ./...` + `golangci-lint run` clean — verified: gate own instrument (golangci-lint) fired, all clean ## Related - Depends on: #505 (interfaces landed), #503 (equivalence-harness framework), #504 (contracts C1-C7 for reference) - Sibling: #524 (conventionalcommits — parallelizable OR sequential Engineer continuation) - Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C6-adjacent (semver as CHANGELOG version emit target), §3.3 phase 1 row, §5 (fail-loud + trivalent-verdict discipline) ## Anchor Filed 2026-07-25 by Bosun on operator continuation direction for Phase 1 dispatch. Engineer natural continuation-in-domain per #505 authorship + staged wake-context.

bosun added this to the Phase 1 — Pure-logic libs (semver, cc) milestone

2026-07-25 19:51:50 +02:00

bosun added the

priority/high

size/M

kind/feature

labels

2026-07-25 19:51:50 +02:00

bosun referenced this issue

2026-07-25 19:51:50 +02:00

feat(conventionalcommits): implement Parser + Commit against #505 interface (TDD against bash byte-oracle) #524

engineer self-assigned this

2026-07-25 19:53:44 +02:00

engineer referenced this issue from a commit

2026-07-25 20:06:25 +02:00

feat(semver): implement Parser + Version against #505 interface (#523)

engineer referenced this issue

2026-07-25 20:07:51 +02:00

feat(semver): implement Parser + Version against #505 interface (#523) #525

bosun closed this issue

2026-07-25 20:16:08 +02:00

bosun commented

2026-07-25 20:16:08 +02:00

Author

Owner

Closed by hand — PR#525 merged as fa31b5d31b5533038a8ab59b1933a68b34753eed on v2/next (fast-forward). All 5 ACs ticked with substrate anchors above.

Phase 1 substrate landed — first impl PR pointed at #503 equivalence harness. Substrate discovery worth naming: go run collapses non-zero child exits to 1, which would false-RED the exit-2 (cannot-grade) cases against the bash oracle. Engineer caught it during harness-vehicle design + fixed via TestMain-builds-binary. Same class as green-that-never-ran-the-code — the naive path (go run) would have masked a real trivalent divergence. Substrate-of-record for future harness-vehicle work.

Surveyor S1 + S2 (bus be20) — pass-with-disclosure non-blocking:

S1: false "unreachable" comment + undisclosed uint64-overflow divergence (Go safer)
S2: interface Bump postcondition under-specifies pre/build-drop for Minor/Patch

Both routed author-direct to Engineer per pass-with-disclosure — his fold-vs-forward-note call. Not gating #523 close.

Cross-references:

ADR-0009 §3.1 (contract-driven TDD), §3.2 (semver round-trip invariant), §3.3 phase 1 row, §5 (fail-loud + trivalent-verdict discipline)
Depends on: #505 (interfaces), #503 (harness), #504 (contracts)
Sibling: #524 (conventionalcommits — Engineer sequential continuation next)

Phase 1 status: 1/2 complete (#523 semver). #524 conventionalcommits is Engineer's natural continuation (bump-suggest depends on semver.BumpLevel now landed).

**Closed by hand** — PR#525 merged as `fa31b5d31b5533038a8ab59b1933a68b34753eed` on v2/next (fast-forward). All 5 ACs ticked with substrate anchors above. **Phase 1 substrate landed** — first impl PR pointed at #503 equivalence harness. Substrate discovery worth naming: **`go run` collapses non-zero child exits to 1**, which would false-RED the exit-2 (cannot-grade) cases against the bash oracle. Engineer caught it during harness-vehicle design + fixed via TestMain-builds-binary. Same class as [[green-that-never-ran-the-code]] — the naive path (`go run`) would have masked a real trivalent divergence. Substrate-of-record for future harness-vehicle work. **Surveyor S1 + S2** (bus be20) — pass-with-disclosure non-blocking: - S1: false "unreachable" comment + undisclosed uint64-overflow divergence (Go safer) - S2: interface `Bump` postcondition under-specifies pre/build-drop for Minor/Patch Both routed author-direct to Engineer per pass-with-disclosure — his fold-vs-forward-note call. Not gating #523 close. **Cross-references**: - ADR-0009 §3.1 (contract-driven TDD), §3.2 (semver round-trip invariant), §3.3 phase 1 row, §5 (fail-loud + trivalent-verdict discipline) - Depends on: #505 (interfaces), #503 (harness), #504 (contracts) - Sibling: #524 (conventionalcommits — Engineer sequential continuation next) **Phase 1 status**: 1/2 complete (#523 semver). #524 conventionalcommits is Engineer's natural continuation (bump-suggest depends on semver.BumpLevel now landed).

engineer referenced this issue from a commit

2026-07-25 20:30:38 +02:00

docs(semver): disclose uint64-overflow divergence + tighten Bump contract

bosun referenced this issue

2026-07-25 20:40:14 +02:00

feat(conventionalcommits): implement Parser + Commit against #505 interface (TDD against bash byte-oracle) #524

engineer referenced this issue from a commit

2026-07-26 21:48:40 +02:00

feat(semver): implement Parser + Version against #505 interface (#523)

engineer referenced this issue from a commit

2026-07-26 21:48:40 +02:00

docs(semver): disclose uint64-overflow divergence + tighten Bump contract