Add integer formatting for metric period enums (#6)

Author: bpapillon

.claude/settings.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(go test:*)",
+      "Bash(task install)",
+      "Bash(task lint)",
+      "Bash(task test)",
+      "Bash(task test:reset)"
+    ],
+    "deny": []
+  }
+}

CLAUDE.md

@@ -0,0 +1,80 @@
+# CLAUDE.md
+
+This repository is a Go implementation of the Schematic rules engine. It is used in both the Schematic public Go SDK (github.com/schematichq/schematic-go) and the private Schematic API. This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+This project uses Taskfile for development commands:
+
+```bash
+# Development workflow
+task install     # Install Go and dependencies
+task lint        # Run golangci-lint (MUST run before commits)
+task test        # Run tests with coverage
+task test:coverage  # View coverage in browser
+task test:reset  # Clear test cache
+
+# Direct Go commands
+go test ./...           # Run all tests
+go test -v ./... -run TestName  # Run specific test
+```
+
+## Architecture
+
+This is Schematic's **Rules Engine** - a feature flag evaluation system compiled to WebAssembly for client-side use. The core evaluation flow is:
+
+1. **flagcheck.go** - Main `CheckFlag()` entry point
+2. **rulecheck.go** - Processes individual rules and conditions
+3. **models.go** - Core data structures (Flag, Rule, Condition, Company, User)
+4. **metrics.go** - Usage tracking and billing cycle management
+
+### Rule Processing Priority
+
+Rules are evaluated in strict priority order:
+
+1. `global_override` - System-wide toggles
+2. `company_override` - Company-specific overrides
+3. `plan_entitlement` - Plan-based features
+4. `company_override_usage_exceeded` - Usage limit overrides
+5. `plan_entitlement_usage_exceeded` - Plan usage enforcement
+6. `standard` - Regular business rules
+7. `default` - Fallback values
+
+### Key Data Flow
+
+**Flag Evaluation:**
+
+- Flags contain multiple Rules ordered by priority
+- Rules contain Conditions (AND logic within rule, OR logic within condition groups)
+- Conditions check company/user traits, metrics, plans, etc.
+
+**Usage Tracking:**
+
+- CompanyMetric tracks usage over time periods (daily/weekly/monthly/all-time)
+- Metric periods can reset on calendar boundaries or billing cycles
+- Usage limits trigger rule overrides when exceeded
+
+### Condition Types
+
+- **Company/User targeting** - ID-based matching with set operations
+- **Plan checks** - Current plan vs. allowed plans
+- **Metric conditions** - Usage comparisons with time periods
+- **Trait matching** - Key-value trait comparisons using typeconvert utilities
+
+### WebAssembly Interface
+
+The main.go provides a WASM interface that:
+
+- Exposes `checkFlag` function to JavaScript
+- Accepts JSON with company/user/flag data
+- Returns evaluation results with detailed error information
+- Runs persistently in browser environments
+
+## Key Files
+
+- **flagcheck.go** - Main evaluation logic
+- **rulecheck.go** - Rule/condition processing
+- **metrics.go** - Time-based usage tracking and billing cycles
+- **models.go** - All data structures with JSON serialization
+- **typeconvert/** - Type comparison utilities for conditions
+- **set/** - Generic set operations for ID matching

metrics.go

@@ -1,6 +1,7 @@
 package rulesengine
 
 import (
+	"fmt"
 	"time"
 )
 
@@ -13,6 +14,56 @@ const (
 	MetricPeriodCurrentWeek  MetricPeriod = "current_week"
 )
 
+// ToInt converts MetricPeriod to its integer representation
+func (mp MetricPeriod) ToInt() int {
+	switch mp {
+	case MetricPeriodAllTime:
+		return 0
+	case MetricPeriodCurrentDay:
+		return 1
+	case MetricPeriodCurrentWeek:
+		return 2
+	case MetricPeriodCurrentMonth:
+		return 3
+	default:
+		return 0
+	}
+}
+
+// Format implements fmt.Formatter interface
+func (mp MetricPeriod) Format(f fmt.State, verb rune) {
+	switch verb {
+	case 'd':
+		fmt.Fprintf(f, "%d", mp.ToInt())
+	case 's':
+		fmt.Fprintf(f, "%s", string(mp))
+	case 'v':
+		if f.Flag('#') {
+			fmt.Fprintf(f, "MetricPeriod(%s)", string(mp))
+		} else {
+			fmt.Fprintf(f, "%s", string(mp))
+		}
+	default:
+		fmt.Fprintf(f, "%%!%c(MetricPeriod=%s)", verb, string(mp))
+	}
+}
+
+// MetricPeriodFromInt converts an integer to MetricPeriod
+func MetricPeriodFromInt(i int) MetricPeriod {
+	switch i {
+	case 0:
+		return MetricPeriodAllTime
+	case 1:
+		return MetricPeriodCurrentDay
+	case 2:
+		return MetricPeriodCurrentWeek
+	case 3:
+		return MetricPeriodCurrentMonth
+	default:
+		return MetricPeriodAllTime
+	}
+}
+
 // For MetricPeriodMonth, there's an additional option indicating when the month should reset
 type MetricPeriodMonthReset string
 
@@ -21,6 +72,48 @@ const (
 	MetricPeriodMonthResetBilling MetricPeriodMonthReset = "billing_cycle"
 )
 
+// ToInt converts MetricPeriodMonthReset to its integer representation
+func (mr MetricPeriodMonthReset) ToInt() int {
+	switch mr {
+	case MetricPeriodMonthResetFirst:
+		return 0
+	case MetricPeriodMonthResetBilling:
+		return 1
+	default:
+		return 0
+	}
+}
+
+// Format implements fmt.Formatter interface
+func (mr MetricPeriodMonthReset) Format(f fmt.State, verb rune) {
+	switch verb {
+	case 'd':
+		fmt.Fprintf(f, "%d", mr.ToInt())
+	case 's':
+		fmt.Fprintf(f, "%s", string(mr))
+	case 'v':
+		if f.Flag('#') {
+			fmt.Fprintf(f, "MetricPeriodMonthReset(%s)", string(mr))
+		} else {
+			fmt.Fprintf(f, "%s", string(mr))
+		}
+	default:
+		fmt.Fprintf(f, "%%!%c(MetricPeriodMonthReset=%s)", verb, string(mr))
+	}
+}
+
+// MetricPeriodMonthResetFromInt converts an integer to MetricPeriodMonthReset
+func MetricPeriodMonthResetFromInt(i int) MetricPeriodMonthReset {
+	switch i {
+	case 0:
+		return MetricPeriodMonthResetFirst
+	case 1:
+		return MetricPeriodMonthResetBilling
+	default:
+		return MetricPeriodMonthResetFirst
+	}
+}
+
 // Given a calendar-based metric period, return the beginning of the current metric period
 // Will return nil for non-calendar-based metric periods such as all-time or billing cycle
 func GetCurrentMetricPeriodStartForCalendarMetricPeriod(metricPeriod MetricPeriod) *time.Time {

metrics_test.go

@@ -102,39 +102,35 @@ func TestGetCurrentMetricPeriodStartForCompanyBillingSubscription(t *testing.T)
 		now := time.Now().UTC()
 		company := createTestCompany()
 
-		// Set subscription to start on a day later in the month than today
-		futureDay := now.Day() + 5
-		if futureDay > 28 {
-			futureDay = 28 // Avoid month boundary issues
-		}
+		resetDay := 5
 
 		company.Subscription.PeriodStart = time.Date(
 			now.Year()-1,
 			now.Month(),
-			futureDay,
+			resetDay,
 			12, 0, 0, 0,
 			time.UTC,
 		)
 
 		result := rulesengine.GetCurrentMetricPeriodStartForCompanyBillingSubscription(company)
 		assert.NotNil(t, result)
 
-		// In this case, the result should be last month's reset date
-		expectedMonth := now.Month() - 1
-		expectedYear := now.Year()
-		if now.Month() == time.January {
-			expectedMonth = time.December
-			expectedYear = now.Year() - 1
-		}
-
+		// Calculate what the function should return:
+		// If today's date is before the 5th, return last month's 5th
+		// If today's date is the 5th or after, return this month's 5th
 		expected := time.Date(
-			expectedYear,
-			expectedMonth,
-			futureDay,
+			now.Year(),
+			now.Month(),
+			resetDay,
 			12, 0, 0, 0,
 			time.UTC,
 		)
 
+		// If we haven't reached the reset day this month, use last month's reset day
+		if now.Day() < resetDay {
+			expected = expected.AddDate(0, -1, 0)
+		}
+
 		assert.Equal(t, expected.Year(), result.Year())
 		assert.Equal(t, expected.Month(), result.Month())
 		assert.Equal(t, expected.Day(), result.Day())
@@ -379,16 +375,18 @@ func TestGetNextMetricPeriodStartForCompanyBillingSubscription(t *testing.T) {
 		company := createTestCompany()
 
 		// Set subscription to start on a day later in the month than today
-		futureDay := now.Day() + 5
-		if futureDay > 28 {
-			futureDay = 28 // Avoid month boundary issues
+		// Use a day that's guaranteed to be in the future within this month
+		futureDay := 15 // Use middle of month to avoid edge cases
+		if now.Day() >= 15 {
+			// If we're past the 15th, use day 5 of next month
+			futureDay = 5
 		}
 
 		company.Subscription.PeriodStart = time.Date(
 			now.Year()-1,
 			now.Month(),
 			futureDay,
-			12, 0, 0, 0,
+			0, 0, 0, 0, // Use midnight for cleaner comparison
 			time.UTC,
 		)
 
@@ -397,14 +395,38 @@ func TestGetNextMetricPeriodStartForCompanyBillingSubscription(t *testing.T) {
 		result := rulesengine.GetNextMetricPeriodStartForCompanyBillingSubscription(company)
 		assert.NotNil(t, result)
 
-		// In this case, the result should be this month's reset date
-		expected := time.Date(
-			now.Year(),
-			now.Month(),
-			futureDay,
-			12, 0, 0, 0,
-			time.UTC,
-		)
+		// Calculate expected: if we're before the 15th, expect this month's reset
+		// If we're after the 15th, we used day 5, so expect next month's reset
+		var expected time.Time
+		if now.Day() < 15 {
+			// Reset day (15th) hasn't passed, so next reset is this month
+			expected = time.Date(
+				now.Year(),
+				now.Month(),
+				futureDay,
+				0, 0, 0, 0,
+				time.UTC,
+			)
+		} else {
+			// We used day 5, and since we're past 15th, next reset is next month's 5th
+			expected = time.Date(
+				now.Year(),
+				now.Month()+1,
+				futureDay,
+				0, 0, 0, 0,
+				time.UTC,
+			)
+			// Handle year boundary
+			if now.Month() == time.December {
+				expected = time.Date(
+					now.Year()+1,
+					time.January,
+					futureDay,
+					0, 0, 0, 0,
+					time.UTC,
+				)
+			}
+		}
 
 		assert.Equal(t, expected.Year(), result.Year())
 		assert.Equal(t, expected.Month(), result.Month())