feat(quando-7m5): implement MustParse convenience function

Add MustParse() as a convenience wrapper around Parse() that panics on error.
Designed for test fixtures and static initialization where input is known valid.

- Implement MustParse() with clear panic behavior and godoc warnings
- Add comprehensive tests for success cases and panic behavior
- Add example tests showing test fixture and static initialization patterns
- Verify panic message includes input string for debugging
- Test coverage: 97.7% (exceeds 95% target)

.beads/issues.jsonl

@@ -6,7 +6,7 @@
 {"id":"quando-5ol","title":"Format presets and constants","description":"Implement preset format constants and Format() method.\n\n**API:**\n```go\ntype Format int\n\nconst (\n    ISO Format = iota     // \"2026-02-09\"\n    EU                    // \"09.02.2026\"\n    US                    // \"02/09/2026\"\n    Long                  // \"February 9, 2026\" (language-dependent)\n    RFC2822               // \"Mon, 09 Feb 2026 00:00:00 +0000\"\n)\n\nfunc (d Date) Format(format Format) string\n```\n\n**Language Dependency:**\n- ISO, EU, US, RFC2822: Always language-independent\n- Long: Uses Lang setting\n  - EN: \"February 9, 2026\"\n  - DE: \"9. Februar 2026\"\n\n**Implementation:**\n- Map Format constants to Go layout strings\n- Use Lang() setting for Long format\n- Delegate to time.Format() internally\n\n## Acceptance Criteria\n- [ ] Format type and constants defined\n- [ ] Format() method implemented\n- [ ] ISO format outputs \"YYYY-MM-DD\"\n- [ ] EU format outputs \"DD.MM.YYYY\"\n- [ ] US format outputs \"MM/DD/YYYY\"\n- [ ] RFC2822 format correct\n- [ ] Long format respects Lang setting (EN and DE)\n- [ ] Non-Long formats ignore Lang setting\n- [ ] Unit tests for all formats\n- [ ] Unit tests for Long with both EN and DE\n- [ ] Benchmark meets \u003c5µs without i18n, \u003c10µs with i18n\n- [ ] Godoc for each format constant\n- [ ] Example tests showing each format","status":"closed","priority":2,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:21:53.217816331+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T20:11:47.455205479+01:00","closed_at":"2026-02-11T20:11:47.455205479+01:00","close_reason":"Closed","dependencies":[{"issue_id":"quando-5ol","depends_on_id":"quando-j2s","type":"blocks","created_at":"2026-02-11T16:23:12.164278602+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"quando-5ol","depends_on_id":"quando-zbr","type":"blocks","created_at":"2026-02-11T16:23:12.20045666+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"quando-6c3","title":"CI/CD pipeline setup","description":"Set up GitHub Actions CI/CD pipeline for automated testing and quality checks.\n\n**CI Workflow:**\n- Run on push and pull requests\n- Test on multiple Go versions (1.22, 1.23, latest)\n- Test on multiple platforms (Linux, macOS, Windows)\n- Run go fmt check\n- Run go vet\n- Run tests with coverage\n- Run benchmarks (informational)\n- Optional: golangci-lint\n\n**Coverage Reporting:**\n- Generate coverage report\n- Fail if coverage \u003c95% for core calculation functions\n- Optional: Upload to codecov.io or similar\n\n**Performance Monitoring:**\n- Run benchmarks on each commit\n- Report benchmark results (informational, no fail)\n\n## Acceptance Criteria\n- [ ] .github/workflows/ci.yml created\n- [ ] Tests run on push and PR\n- [ ] Multi-version Go support (1.22+)\n- [ ] Multi-platform support (Linux, macOS, Windows)\n- [ ] go fmt check passes\n- [ ] go vet check passes\n- [ ] Tests run with coverage report\n- [ ] Coverage requirement enforced (95%+)\n- [ ] Benchmarks run (informational)\n- [ ] CI badge in README (if applicable)","status":"tombstone","priority":3,"issue_type":"task","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:22:51.928117055+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T19:21:16.246958875+01:00","dependencies":[{"issue_id":"quando-6c3","depends_on_id":"quando-r1o","type":"blocks","created_at":"2026-02-11T16:23:16.259739409+01:00","created_by":"Oliver Jakoubek"}],"deleted_at":"2026-02-11T19:21:16.246958875+01:00","deleted_by":"daemon","delete_reason":"delete","original_type":"task"}
 {"id":"quando-6x3","title":"Documentation and examples","description":"Complete documentation including README, godoc, and example code.\n\n**README.md Contents:**\n- Project overview and vision\n- Installation instructions (go get)\n- Quick start examples\n- Core features showcase\n- Performance characteristics\n- Comparison to time.Time\n- Contributing guidelines\n- License\n\n**Godoc Requirements:**\n- Every exported type/function documented\n- Godoc comments start with type/function name\n- Complex behaviors explained (month-end overflow, DST, etc.)\n- Edge cases noted where applicable\n\n**Example Tests:**\n- Example_basicArithmetic\n- Example_monthEndOverflow\n- Example_snapOperations\n- Example_diffCalculation\n- Example_humanFormat\n- Example_parsing\n- Example_formatting\n- Example_timezoneConversion\n- Example_chainedOperations\n\n**Code Examples in README:**\n- Complex chaining\n- Month-end handling\n- Human-readable diffs\n- Timezone-aware operations\n- Comparison with stdlib\n\n## Acceptance Criteria\n- [ ] README.md complete with all sections\n- [ ] Installation instructions clear\n- [ ] At least 5 code examples in README\n- [ ] All exported items have godoc comments\n- [ ] Godoc comments follow conventions (name first)\n- [ ] At least 8 example tests\n- [ ] Examples demonstrate key features\n- [ ] Edge cases documented in relevant godoc\n- [ ] Comparison table with time.Time\n- [ ] Contributing guidelines (if open source)","status":"open","priority":3,"issue_type":"task","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:22:45.693695262+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:22:45.693695262+01:00","dependencies":[{"issue_id":"quando-6x3","depends_on_id":"quando-r1o","type":"blocks","created_at":"2026-02-11T16:23:16.222906911+01:00","created_by":"Oliver Jakoubek"}]}
-{"id":"quando-7m5","title":"MustParse convenience function","description":"Implement MustParse() convenience function that panics on error (for tests/initialization).\n\n**API:**\n```go\nfunc MustParse(s string) Date\n```\n\n**Behavior:**\n- Calls Parse() internally\n- Returns Date on success\n- Panics on error (with clear panic message)\n\n**Use Cases:**\n- Test fixtures\n- Static initialization\n- Configuration files where values are known-good\n\n**Documentation:**\n- MUST clearly document that this function panics\n- MUST recommend using Parse() in production code\n- MUST show test usage examples\n\n## Acceptance Criteria\n- [ ] MustParse() implemented\n- [ ] Returns Date on successful parse\n- [ ] Panics with clear message on error\n- [ ] Godoc clearly warns about panic behavior\n- [ ] Godoc recommends Parse() for production\n- [ ] Example test showing test fixture usage\n- [ ] Unit tests verifying panic on invalid input","status":"open","priority":3,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:21:46.007442996+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:21:46.007442996+01:00","dependencies":[{"issue_id":"quando-7m5","depends_on_id":"quando-gr5","type":"blocks","created_at":"2026-02-11T16:23:11.340600075+01:00","created_by":"Oliver Jakoubek"}]}
+{"id":"quando-7m5","title":"MustParse convenience function","description":"Implement MustParse() convenience function that panics on error (for tests/initialization).\n\n**API:**\n```go\nfunc MustParse(s string) Date\n```\n\n**Behavior:**\n- Calls Parse() internally\n- Returns Date on success\n- Panics on error (with clear panic message)\n\n**Use Cases:**\n- Test fixtures\n- Static initialization\n- Configuration files where values are known-good\n\n**Documentation:**\n- MUST clearly document that this function panics\n- MUST recommend using Parse() in production code\n- MUST show test usage examples\n\n## Acceptance Criteria\n- [ ] MustParse() implemented\n- [ ] Returns Date on successful parse\n- [ ] Panics with clear message on error\n- [ ] Godoc clearly warns about panic behavior\n- [ ] Godoc recommends Parse() for production\n- [ ] Example test showing test fixture usage\n- [ ] Unit tests verifying panic on invalid input","status":"closed","priority":3,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:21:46.007442996+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T20:54:19.638519056+01:00","closed_at":"2026-02-11T20:54:19.638519056+01:00","close_reason":"Closed","dependencies":[{"issue_id":"quando-7m5","depends_on_id":"quando-gr5","type":"blocks","created_at":"2026-02-11T16:23:11.340600075+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"quando-91w","title":"Project setup and structure","description":"Set up initial project structure, module, and tooling.\n\n**Repository Structure:**\n```\nquando/\n├── quando.go           # Package-level functions\n├── date.go             # Date type and core methods\n├── arithmetic.go       # Add, Sub\n├── snap.go             # StartOf, EndOf, Next, Prev\n├── diff.go             # Duration type, Diff\n├── inspect.go          # WeekNumber, Quarter, etc.\n├── format.go           # Formatting\n├── parse.go            # Parsing\n├── clock.go            # Clock abstraction\n├── i18n.go             # Internationalization\n├── errors.go           # Error types\n├── internal/calc/      # Internal helpers\n├── *_test.go           # Unit tests\n├── example_test.go     # Godoc examples\n├── bench_test.go       # Benchmarks\n├── go.mod\n├── go.sum\n├── README.md\n├── LICENSE             # MIT\n└── .github/workflows/ci.yml\n```\n\n**Go Module:**\n- Module path: code.beautifulmachines.dev/quando\n- Go version: 1.22+\n- Zero dependencies (stdlib only)\n\n**Tooling:**\n- go fmt\n- go vet\n- golangci-lint (optional)\n\n## Acceptance Criteria\n- [ ] go.mod initialized with correct module path\n- [ ] Go 1.22+ specified in go.mod\n- [ ] Directory structure created\n- [ ] README.md with project overview\n- [ ] LICENSE file (MIT)\n- [ ] .gitignore for Go projects\n- [ ] Basic CI/CD workflow (if applicable)","status":"closed","priority":0,"issue_type":"task","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:22:30.054241058+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:28:17.730717812+01:00","closed_at":"2026-02-11T16:28:17.730717812+01:00","close_reason":"Closed","comments":[{"id":1,"issue_id":"quando-91w","author":"Oliver Jakoubek","text":"Plan: 1) Initialize go.mod with module path code.beautifulmachines.dev/quando and Go 1.22+, 2) Create internal/calc/ directory structure, 3) Write comprehensive README.md, 4) Add MIT LICENSE, 5) Populate .gitignore for Go, 6) Create GitHub Actions CI workflow for testing and linting","created_at":"2026-02-11T15:26:35Z"}]}
 {"id":"quando-95w","title":"Custom layout formatting","description":"Implement FormatLayout() for custom format layouts using Go's standard layout format.\n\n**API:**\n```go\nfunc (d Date) FormatLayout(layout string) string\n```\n\n**Behavior:**\n- Uses Go's reference date format (Mon Jan 2 15:04:05 MST 2006)\n- Respects Lang() setting for month/weekday names\n- Delegates to time.Format() with translations applied\n\n**Examples:**\n```go\n// English (default)\ndate.FormatLayout(\"Monday, 2. January 2006\")\n// → \"Monday, 9. February 2026\"\n\n// German\ndate.Lang(LangDE).FormatLayout(\"Monday, 2. January 2006\")\n// → \"Montag, 9. Februar 2026\"\n```\n\n**Implementation:**\n- Replace month/weekday names based on Lang setting\n- Handle both full and abbreviated names\n- Preserve all other layout characters\n\n## Acceptance Criteria\n- [ ] FormatLayout() implemented\n- [ ] Uses Go's standard layout format\n- [ ] Default (EN) outputs English month/weekday names\n- [ ] DE lang outputs German month/weekday names\n- [ ] Full names translated (Monday, January)\n- [ ] Abbreviated names translated (Mon, Jan)\n- [ ] Non-date characters preserved in layout\n- [ ] Unit tests for various layouts\n- [ ] Unit tests for both EN and DE\n- [ ] Benchmark meets \u003c10µs target with i18n\n- [ ] Godoc with Go layout format reference\n- [ ] Example tests showing custom layouts","status":"closed","priority":2,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:21:59.18488929+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T20:34:48.639373428+01:00","closed_at":"2026-02-11T20:34:48.639373428+01:00","close_reason":"Closed","dependencies":[{"issue_id":"quando-95w","depends_on_id":"quando-j2s","type":"blocks","created_at":"2026-02-11T16:23:12.24298936+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"quando-95w","depends_on_id":"quando-zbr","type":"blocks","created_at":"2026-02-11T16:23:12.275497777+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"quando-9sf","title":"Snap operations: Next and Prev weekday","description":"Implement Next and Prev methods to jump to next/previous occurrence of a weekday.\n\n**API:**\n```go\nfunc (d Date) Next(weekday time.Weekday) Date\nfunc (d Date) Prev(weekday time.Weekday) Date\n```\n\n**Critical Behavior:**\n- **Next(Monday)**: Always NEXT Monday, never today (even if today is Monday)\n- **Prev(Friday)**: Always PREVIOUS Friday, never today (even if today is Friday)\n- Preserves time of day from source date\n\n**Examples:**\n- Monday calling Next(Monday) → next Monday (7 days later)\n- Monday calling Prev(Monday) → previous Monday (7 days earlier)\n- Tuesday calling Next(Monday) → next Monday (6 days later)\n\n## Acceptance Criteria\n- [ ] Next() implemented for all weekdays\n- [ ] Prev() implemented for all weekdays\n- [ ] Next() never returns today (always future)\n- [ ] Prev() never returns today (always past)\n- [ ] Time of day preserved from source\n- [ ] Edge case: Same weekday correctly skips to next/prev week\n- [ ] Unit tests for all weekday combinations\n- [ ] Tests for same weekday edge case\n- [ ] Benchmarks meet \u003c1µs target\n- [ ] Godoc comments with same-weekday behavior example","status":"closed","priority":1,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:20:58.320692116+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T17:33:58.411235677+01:00","closed_at":"2026-02-11T17:33:58.411235677+01:00","close_reason":"Closed","dependencies":[{"issue_id":"quando-9sf","depends_on_id":"quando-j2s","type":"blocks","created_at":"2026-02-11T16:23:07.357069002+01:00","created_by":"Oliver Jakoubek"}],"comments":[{"id":6,"issue_id":"quando-9sf","author":"Oliver Jakoubek","text":"Plan: 1) Add Next(weekday) and Prev(weekday) methods to snap.go, 2) Implement logic to ALWAYS skip to next/prev occurrence (never return today), 3) Preserve time of day from source date, 4) Handle same-weekday edge case (Monday.Next(Monday) = next Monday), 5) Write comprehensive unit tests for all weekday combinations, 6) Add tests specifically for same-weekday edge case, 7) Add benchmarks, 8) Ensure godoc comments with examples","created_at":"2026-02-11T16:31:43Z"}]}

example_test.go

@@ -916,3 +916,39 @@ func ExampleDate_Info_leapYear() {
 	// Is weekend: false
 	// Is leap year: true
 }
+
+// ExampleMustParse demonstrates basic usage in tests and initialization
+func ExampleMustParse() {
+	// Use in test fixtures or static initialization
+	date := quando.MustParse("2026-02-09")
+	fmt.Println(date)
+	// Output: 2026-02-09 00:00:00
+}
+
+// ExampleMustParse_testFixture demonstrates using MustParse in test fixtures
+func ExampleMustParse_testFixture() {
+	// Common pattern in tests - no error handling needed
+	startDate := quando.MustParse("2026-01-01")
+	endDate := quando.MustParse("2026-12-31")
+
+	fmt.Printf("Start: %v\n", startDate.Time().Format("2006-01-02"))
+	fmt.Printf("End: %v\n", endDate.Time().Format("2006-01-02"))
+	// Output:
+	// Start: 2026-01-01
+	// End: 2026-12-31
+}
+
+// ExampleMustParse_staticInit demonstrates static initialization pattern
+func ExampleMustParse_staticInit() {
+	// Pattern for package-level constants
+	var (
+		epoch = quando.MustParse("1970-01-01")
+		y2k   = quando.MustParse("2000-01-01")
+	)
+
+	fmt.Printf("Epoch: %v\n", epoch.Time().Year())
+	fmt.Printf("Y2K: %v\n", y2k.Time().Year())
+	// Output:
+	// Epoch: 1970
+	// Y2K: 2000
+}

parse.go

@@ -128,6 +128,46 @@ func Parse(s string) (Date, error) {
 	return Date{}, fmt.Errorf("parsing date %q: no matching format: %w", s, ErrInvalidFormat)
 }
 
+// MustParse parses a date string using automatic format detection and panics on error.
+//
+// This is a convenience wrapper around Parse() for use in tests and initialization code
+// where the input is known to be valid. If parsing fails, it panics with the parse error.
+//
+// IMPORTANT: This function panics on error. For production code that needs to handle
+// errors gracefully, use Parse() instead.
+//
+// Supported formats (same as Parse):
+//   - ISO format: "2026-02-09" (YYYY-MM-DD)
+//   - ISO with slash: "2026/02/09" (YYYY/MM/DD)
+//   - EU format: "09.02.2026" (DD.MM.YYYY)
+//   - RFC2822: "Mon, 09 Feb 2026 00:00:00 +0000"
+//
+// Use cases:
+//   - Test fixtures: date := quando.MustParse("2026-02-09")
+//   - Static initialization: var StartDate = quando.MustParse("2026-01-01")
+//   - Configuration where dates are validated at load time
+//
+// Example (test fixture):
+//
+//	func TestSomething(t *testing.T) {
+//	    date := quando.MustParse("2026-02-09")
+//	    // Use date without error handling...
+//	}
+//
+// Example (static initialization):
+//
+//	var (
+//	    EpochDate = quando.MustParse("1970-01-01")
+//	    Y2K       = quando.MustParse("2000-01-01")
+//	)
+func MustParse(s string) Date {
+	date, err := Parse(s)
+	if err != nil {
+		panic(fmt.Sprintf("quando.MustParse(%q): %v", s, err))
+	}
+	return date
+}
+
 // isYearPrefix checks if the first 4 characters represent a valid year (>= 1000).
 // This helps distinguish YYYY/MM/DD from DD/MM/YYYY or MM/DD/YYYY.
 func isYearPrefix(s string) bool {

parse_test.go

@@ -2,6 +2,7 @@ package quando
 
 import (
 	"errors"
+	"fmt"
 	"testing"
 	"time"
 )
@@ -855,3 +856,71 @@ func BenchmarkParseRelativeOffset(b *testing.B) {
 		_, _ = ParseRelativeWithClock("+2 days", clock)
 	}
 }
+
+func TestMustParse_Success(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		expected time.Time
+	}{
+		{"ISO format", "2026-02-09", time.Date(2026, 2, 9, 0, 0, 0, 0, time.UTC)},
+		{"ISO with slash", "2026/02/09", time.Date(2026, 2, 9, 0, 0, 0, 0, time.UTC)},
+		{"EU format", "09.02.2026", time.Date(2026, 2, 9, 0, 0, 0, 0, time.UTC)},
+		{"RFC2822", "Sun, 09 Feb 2026 00:00:00 +0000", time.Date(2026, 2, 9, 0, 0, 0, 0, time.UTC)},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := MustParse(tt.input)
+
+			if !result.Time().Equal(tt.expected) {
+				t.Errorf("MustParse(%q) = %v, want %v", tt.input, result.Time(), tt.expected)
+			}
+		})
+	}
+}
+
+func TestMustParse_Panic(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+	}{
+		{"empty string", ""},
+		{"invalid format", "not-a-date"},
+		{"ambiguous slash format", "01/02/2026"},
+		{"invalid date", "2026-13-01"},
+		{"malformed", "2026-02-"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			defer func() {
+				if r := recover(); r == nil {
+					t.Errorf("MustParse(%q) expected panic, but didn't panic", tt.input)
+				}
+			}()
+
+			// This should panic
+			_ = MustParse(tt.input)
+		})
+	}
+}
+
+func TestMustParse_PanicMessage(t *testing.T) {
+	defer func() {
+		if r := recover(); r != nil {
+			msg := fmt.Sprint(r)
+			// Verify panic message includes the input string
+			if !containsSubstring(msg, "invalid-input") {
+				t.Errorf("panic message %q should include input string %q", msg, "invalid-input")
+			}
+			if !containsSubstring(msg, "MustParse") {
+				t.Errorf("panic message %q should include function name %q", msg, "MustParse")
+			}
+		} else {
+			t.Error("expected panic but didn't panic")
+		}
+	}()
+
+	MustParse("invalid-input")
+}