feat: usaddress package from o1 and USPS rules

.github/workflows/fuzz.yml

@@ -0,0 +1,35 @@
+name: Go Fuzz Testing
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 0 * * *"
+
+permissions:
+  contents: read
+
+jobs:
+  fuzz-usaddress:
+    name: Fuzz usaddress
+    runs-on: ubuntu-latest
+    timeout-minutes: 12
+
+    steps:
+    - name: Set up Go 1.x
+      uses: actions/setup-go@v5
+      with:
+        go-version: stable
+      id: go
+
+    - name: Check out code into the Go module directory
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Fuzz
+      run: |
+        go test ./pkg/usaddress/... -fuzz Fuzz -fuzztime 10m
+
+    - name: Report Failures
+      if: ${{ failure() }}
+      run: |
+        find ./pkg/usaddress/testdata/fuzz/ -type f | xargs -n1 tail -n +1 -v

pkg/usaddress/data.go

@@ -0,0 +1,118 @@
+package usaddress
+
+var streetSuffixes = map[string]string{
+	"ALLEY": "ALY", "ALY": "ALY",
+	"AVENUE": "AVE", "AVE": "AVE",
+	"BOULEVARD": "BLVD", "BLVD": "BLVD",
+	"CIRCLE": "CIR", "CIR": "CIR",
+	"COURT": "CT", "CT": "CT",
+	"DRIVE": "DR", "DR": "DR",
+	"EXPRESSWAY": "EXPY", "EXPY": "EXPY",
+	"FREEWAY": "FWY", "FWY": "FWY",
+	"HIGHWAY": "HWY", "HWY": "HWY",
+	"LANE": "LN", "LN": "LN",
+	"PASS":  "PASS",
+	"PLACE": "PL", "PL": "PL",
+	"ROAD": "RD", "RD": "RD",
+	"STREET": "ST", "ST": "ST",
+	"TERRACE": "TER", "TER": "TER",
+	"TRAIL": "TRL", "TRL": "TRL",
+	"WAY": "WAY",
+}
+
+var directionalMap = map[string]string{
+	"NORTH":     "N",
+	"SOUTH":     "S",
+	"EAST":      "E",
+	"WEST":      "W",
+	"NORTHEAST": "NE",
+	"NORTHWEST": "NW",
+	"SOUTHEAST": "SE",
+	"SOUTHWEST": "SW",
+	"NE":        "NE",
+	"NW":        "NW",
+	"SE":        "SE",
+	"SW":        "SW",
+}
+
+var stateNamesAndAbbreviations = map[string]string{
+	"ALABAMA": "AL", "AL": "AL",
+	"ALASKA": "AK", "AK": "AK",
+	"ARIZONA": "AZ", "AZ": "AZ",
+	"ARKANSAS": "AR", "AR": "AR",
+	"CALIFORNIA": "CA", "CA": "CA",
+	"COLORADO": "CO", "CO": "CO",
+	"CONNECTICUT": "CT", "CT": "CT",
+	"DELAWARE": "DE", "DE": "DE",
+	"FLORIDA": "FL", "FL": "FL",
+	"GEORGIA": "GA", "GA": "GA",
+	"HAWAII": "HI", "HI": "HI",
+	"IDAHO": "ID", "ID": "ID",
+	"ILLINOIS": "IL", "IL": "IL",
+	"INDIANA": "IN", "IN": "IN",
+	"IOWA": "IA", "IA": "IA",
+	"KANSAS": "KS", "KS": "KS",
+	"KENTUCKY": "KY", "KY": "KY",
+	"LOUISIANA": "LA", "LA": "LA",
+	"MAINE": "ME", "ME": "ME",
+	"MARYLAND": "MD", "MD": "MD",
+	"MASSACHUSETTS": "MA", "MA": "MA",
+	"MICHIGAN": "MI", "MI": "MI",
+	"MINNESOTA": "MN", "MN": "MN",
+	"MISSISSIPPI": "MS", "MS": "MS",
+	"MISSOURI": "MO", "MO": "MO",
+	"MONTANA": "MT", "MT": "MT",
+	"NEBRASKA": "NE", "NE": "NE",
+	"NEVADA": "NV", "NV": "NV",
+	"NEW HAMPSHIRE": "NH", "NH": "NH",
+	"NEW JERSEY": "NJ", "NJ": "NJ",
+	"NEW MEXICO": "NM", "NM": "NM",
+	"NEW YORK": "NY", "NY": "NY",
+	"NORTH CAROLINA": "NC", "NC": "NC",
+	"NORTH DAKOTA": "ND", "ND": "ND",
+	"OHIO": "OH", "OH": "OH",
+	"OKLAHOMA": "OK", "OK": "OK",
+	"OREGON": "OR", "OR": "OR",
+	"PENNSYLVANIA": "PA", "PA": "PA",
+	"RHODE ISLAND": "RI", "RI": "RI",
+	"SOUTH CAROLINA": "SC", "SC": "SC",
+	"SOUTH DAKOTA": "SD", "SD": "SD",
+	"TENNESSEE": "TN", "TN": "TN",
+	"TEXAS": "TX", "TX": "TX",
+	"UTAH": "UT", "UT": "UT",
+	"VERMONT": "VT", "VT": "VT",
+	"VIRGINIA": "VA", "VA": "VA",
+	"WASHINGTON": "WA", "WA": "WA",
+	"WEST VIRGINIA": "WV", "WV": "WV",
+	"WISCONSIN": "WI", "WI": "WI",
+	"WYOMING": "WY", "WY": "WY",
+}
+
+var stateAbbreviations = map[string]bool{
+	"AL": true, "AK": true, "AZ": true, "AR": true, "CA": true, "CO": true, "CT": true,
+	"DE": true, "FL": true, "GA": true, "HI": true, "ID": true, "IL": true, "IN": true,
+	"IA": true, "KS": true, "KY": true, "LA": true, "ME": true, "MD": true, "MA": true,
+	"MI": true, "MN": true, "MS": true, "MO": true, "MT": true, "NE": true, "NV": true,
+	"NH": true, "NJ": true, "NM": true, "NY": true, "NC": true, "ND": true, "OH": true,
+	"OK": true, "OR": true, "PA": true, "RI": true, "SC": true, "SD": true, "TN": true,
+	"TX": true, "UT": true, "VT": true, "VA": true, "WA": true, "WV": true, "WI": true,
+	"WY": true, "DC": true,
+	"AS": true, "GU": true, "MP": true, "PR": true, "VI": true,
+}
+
+var secondaryUnitDesignators = map[string]string{
+	"APARTMENT":  "APT",
+	"APT":        "APT",
+	"BUILDING":   "BLDG",
+	"BLDG":       "BLDG",
+	"FLOOR":      "FL",
+	"FL":         "FL",
+	"SUITE":      "STE",
+	"STE":        "STE",
+	"UNIT":       "UNIT",
+	"ROOM":       "RM",
+	"RM":         "RM",
+	"DEPARTMENT": "DEPT",
+	"DEPT":       "DEPT",
+	"#":          "#",
+}

pkg/usaddress/fuzz_test.go

@@ -0,0 +1,50 @@
+package usaddress
+
+import (
+	"testing"
+)
+
+// FuzzStandardizeAddress performs fuzz testing on the StandardizeAddress function.
+func FuzzStandardizeAddress(f *testing.F) {
+	// Initial corpus: Add sample addresses to the corpus.
+	corpus := []string{
+		"123 Main St\nAnytown, NY 12345",
+		"PO BOX 789\nSomecity, CA 90210",
+		"456 Elm Street Apt 5B\nBigcity, TX 75001",
+		"789 O'Connor Blvd\nDublin, CA 94568",
+		"℅ John Doe\n321 Maple Ave\nSpringfield, IL 62704",
+		"350 Fifth Ave Empire State Building\nNew York, NY 10118",
+		"1234 El Niño Ave\nSan José, CA 95112",
+		"50 北京路\n上海, 200001",
+		"🏠 123 Happy St\nSmile Town, CA 90210",
+		"Münchner Straße 45\nMünchen, 80331",
+		// Add more sample addresses as needed
+		"",
+		"   \n  \t",
+		"!@#$%^&*()_+",
+		"C/O Jane Smith\n123 Unknown Rd\nMystery, ZZ 99999",
+	}
+
+	// Add the corpus entries to the fuzzer
+	for _, input := range corpus {
+		f.Add(input)
+	}
+
+	// Define the fuzz function
+	f.Fuzz(func(t *testing.T, input string) {
+		// Call the function under test
+		addr := StandardizeAddress(input)
+
+		// Optionally, you can perform validations or invariants
+		// For example, ensure that the returned Address struct is valid
+		if err := addr.Validate(); err != nil {
+			// It's acceptable for some random inputs to produce invalid addresses
+			// But you might want to check for panics or unexpected behavior
+			t.Logf("Invalid address: %v", err)
+		}
+
+		// Additional checks can be added here
+		// For example, you can re-serialize the address and ensure no panics occur
+		_ = addr.String()
+	})
+}