fix: Squarespace timezone regex cannot match nested context JSON (#255)

The regex in PageVenueExtractor::extractTimezone() used `\{[^}]*"timeZone"`
which cannot cross any `}` boundary. Real Squarespace SQUARESPACE_CONTEXT
JSON always nests multiple objects (betaFeatureFlags, rollups,
merchandisingSettings, userAccountsSettings, …) before website.timeZone,
so the pattern never matched live pages. The cascade was:

  empty timezone → DateTimeParser::parseUtc() returned empty
                 → event[startDate] empty
                 → fragile description-text / AI-vision fallbacks
                 → different runs produced different dates for the same show
                 → off-by-one duplicates accumulated on the calendar
                   (~2,245 upcoming-event dupes as of writing).

Verified against https://www.theroyalamerican.com/schedule:
  old regex /\{[^}]*"timeZone"…/s : NO MATCH
  new regex /\{.*?"timeZone"…/s   : MATCHED America/New_York

Defense in depth: DateTimeParser::parseUtc() no longer silently returns an
empty result when timezone is empty/invalid. It now falls back to the WP
site timezone and emits a datamachine_log warning so the failure surfaces
instead of cascading into date drift. All three call sites (BaseExtractor,
EventImportHandler) benefit from this.

Fixes #254

Co-authored-by: homeboy-ci[bot] <266378653+homeboy-ci[bot]@users.noreply.github.com>

Author: chubes4

inc/Core/DateTimeParser.php

@@ -27,6 +27,11 @@ class DateTimeParser {
 	 * Use when API returns UTC times with a separate timezone field.
 	 * Example: Dice.fm returns "2026-01-04T02:30:00Z" with timezone "America/Chicago"
 	 *
+	 * When `$timezone` is empty or invalid, falls back to the site timezone
+	 * (`wp_timezone()`) and emits a `datamachine_log` warning. This prevents
+	 * upstream regex / extractor bugs from silently destroying the date and
+	 * cascading into off-by-one duplicates on the calendar. See #254.
+	 *
 	 * @param string $datetime UTC datetime string (e.g., "2026-01-04T02:30:00Z")
 	 * @param string $timezone Target IANA timezone (e.g., "America/Chicago")
 	 * @return array{date: string, time: string, timezone: string}
@@ -39,7 +44,18 @@ public static function parseUtc( string $datetime, string $timezone ): array {
 		}
 
 		if ( ! self::isValidTimezone( $timezone ) ) {
-			return $result;
+			$fallback = self::siteTimezoneName();
+			do_action(
+				'datamachine_log',
+				'warning',
+				'DateTimeParser::parseUtc received empty/invalid timezone; falling back to site timezone',
+				array(
+					'datetime'         => $datetime,
+					'invalid_timezone' => $timezone,
+					'fallback'         => $fallback,
+				)
+			);
+			$timezone = $fallback;
 		}
 
 		try {
@@ -56,6 +72,32 @@ public static function parseUtc( string $datetime, string $timezone ): array {
 		return $result;
 	}
 
+	/**
+	 * Resolve a usable site timezone name for fallbacks.
+	 *
+	 * Prefers `wp_timezone()` when WordPress is loaded, otherwise falls back to
+	 * UTC so the parser still produces a stable result in non-WP contexts.
+	 *
+	 * @return string IANA timezone identifier
+	 */
+	private static function siteTimezoneName(): string {
+		if ( function_exists( 'wp_timezone' ) ) {
+			try {
+				$tz = wp_timezone();
+				if ( $tz instanceof DateTimeZone ) {
+					$name = $tz->getName();
+					if ( ! empty( $name ) ) {
+						return $name;
+					}
+				}
+			} catch ( Exception $e ) {
+				// Fall through to UTC.
+			}
+		}
+
+		return 'UTC';
+	}
+
 	/**
 	 * Parse local datetime that's already in venue timezone.
 	 *

inc/Steps/EventImport/Handlers/WebScraper/PageVenueExtractor.php

@@ -381,7 +381,12 @@ public static function extractVenueName( string $html ): string {
 	 */
 	public static function extractTimezone( string $html ): string {
 		// Squarespace context
-		if ( preg_match( '/Static\.SQUARESPACE_CONTEXT\s*=\s*\{[^}]*"timeZone"\s*:\s*"([^"]+)"/s', $html, $matches ) ) {
+		// Non-greedy .*? crosses nested {...} objects in SQUARESPACE_CONTEXT to reach
+		// the first "timeZone" key (always inside the top-level `website` object). The
+		// previous [^}]* form could not cross any `}` boundary, so it never matched
+		// real Squarespace pages whose context JSON contains nested objects before
+		// `website.timeZone` (e.g. betaFeatureFlags, rollups). See #254.
+		if ( preg_match( '/Static\.SQUARESPACE_CONTEXT\s*=\s*\{.*?"timeZone"\s*:\s*"([^"]+)"/s', $html, $matches ) ) {
 			return $matches[1];
 		}
 

tests/Fixtures/squarespace-royal-american.html

@@ -36,12 +36,28 @@ public function test_parse_utc_handles_different_timezones() {
 		$this->assertEquals( '13:00', $la['time'] );
 	}
 
-	public function test_parse_utc_returns_empty_for_invalid_timezone() {
+	public function test_parse_utc_falls_back_to_site_timezone_for_invalid_timezone() {
+		// Defense-in-depth fix from #254: invalid timezone must NOT silently destroy
+		// the date — it must fall back to the site timezone so a missing venue
+		// timezone cannot cascade into off-by-one duplicates.
 		$result = DateTimeParser::parseUtc( '2026-01-15T18:00:00Z', 'Invalid/Timezone' );
 
-		$this->assertEquals( '', $result['date'] );
-		$this->assertEquals( '', $result['time'] );
-		$this->assertEquals( '', $result['timezone'] );
+		$this->assertNotEmpty( $result['date'], 'parseUtc must not return an empty date when timezone is invalid' );
+		$this->assertNotEmpty( $result['time'] );
+		$this->assertNotEmpty( $result['timezone'], 'parseUtc must report the fallback timezone it used' );
+		$this->assertTrue( DateTimeParser::isValidTimezone( $result['timezone'] ) );
+	}
+
+	public function test_parse_utc_falls_back_to_site_timezone_for_empty_timezone() {
+		// Royal American repro: Squarespace shows at 9pm Eastern land on the next
+		// calendar day in UTC. With an empty timezone, the old code returned empty
+		// and the caller picked a fragile fallback path. With the fix, parseUtc
+		// falls back to the WP site timezone and still produces a stable date.
+		$result = DateTimeParser::parseUtc( '2026-05-16T01:00:00Z', '' );
+
+		$this->assertNotEmpty( $result['date'], 'parseUtc must not silently drop the date when timezone is empty' );
+		$this->assertNotEmpty( $result['timezone'] );
+		$this->assertTrue( DateTimeParser::isValidTimezone( $result['timezone'] ) );
 	}
 
 	public function test_parse_utc_returns_empty_for_empty_datetime() {
@@ -50,6 +66,16 @@ public function test_parse_utc_returns_empty_for_empty_datetime() {
 		$this->assertEquals( '', $result['date'] );
 	}
 
+	public function test_parse_utc_valid_timezone_path_unchanged() {
+		// Regression guard: explicit valid timezone must continue to produce the
+		// exact same output it did before the fallback was introduced.
+		$result = DateTimeParser::parseUtc( '2026-05-16T01:00:00Z', 'America/New_York' );
+
+		$this->assertEquals( '2026-05-15', $result['date'] );
+		$this->assertEquals( '21:00', $result['time'] );
+		$this->assertEquals( 'America/New_York', $result['timezone'] );
+	}
+
 	public function test_parse_local_preserves_datetime() {
 		$result = DateTimeParser::parseLocal( '2026-01-15', '19:30', 'America/Denver' );
 

tests/Unit/DateTimeParserTest.php

@@ -0,0 +1,83 @@
+<?php
+/**
+ * PageVenueExtractor Tests
+ *
+ * Regression coverage for the Squarespace timezone regex fix (#254).
+ *
+ * @package DataMachineEvents\Tests\Unit
+ */
+
+namespace DataMachineEvents\Tests\Unit;
+
+use WP_UnitTestCase;
+use DataMachineEvents\Steps\EventImport\Handlers\WebScraper\PageVenueExtractor;
+
+class PageVenueExtractorTest extends WP_UnitTestCase {
+
+	/**
+	 * Minimal HTML mimicking Squarespace's nested SQUARESPACE_CONTEXT JSON.
+	 *
+	 * The pre-#254 regex used `[^}]*` which cannot cross any `}` boundary, so
+	 * it could never match a real Squarespace page (whose context JSON always
+	 * has multiple nested objects before `website.timeZone`). This fixture
+	 * reproduces that nested shape with the absolute minimum nesting required
+	 * to trigger the bug.
+	 */
+	public function test_extractTimezone_matches_nested_squarespace_context() {
+		$html = '<html><head><script>'
+			. 'Static.SQUARESPACE_CONTEXT = {'
+			. '"betaFeatureFlags":{"foo":true,"bar":1},'
+			. '"rollups":{"x":{"y":1}},'
+			. '"website":{"timeZone":"America/New_York","other":"x"}'
+			. '};'
+			. '</script></head><body></body></html>';
+
+		$this->assertEquals(
+			'America/New_York',
+			PageVenueExtractor::extractTimezone( $html ),
+			'Squarespace context with nested objects before website.timeZone must still match.'
+		);
+	}
+
+	public function test_extractTimezone_matches_when_timezone_is_first_key() {
+		// Simple shape (no nesting before timeZone) — should still match.
+		$html = '<script>Static.SQUARESPACE_CONTEXT = {"website":{"timeZone":"America/Chicago"}};</script>';
+
+		$this->assertEquals( 'America/Chicago', PageVenueExtractor::extractTimezone( $html ) );
+	}
+
+	public function test_extractTimezone_falls_back_to_generic_timezone_property() {
+		// Non-Squarespace platforms expose a generic "timezone" JSON property —
+		// the second regex branch must still hit when there's no SQUARESPACE_CONTEXT.
+		$html = '<script>var config = {"timezone":"America/Denver"};</script>';
+
+		$this->assertEquals( 'America/Denver', PageVenueExtractor::extractTimezone( $html ) );
+	}
+
+	public function test_extractTimezone_falls_back_to_meta_tag() {
+		$html = '<html><head><meta name="timezone" content="Europe/London"></head></html>';
+
+		$this->assertEquals( 'Europe/London', PageVenueExtractor::extractTimezone( $html ) );
+	}
+
+	public function test_extractTimezone_returns_empty_when_nothing_found() {
+		$html = '<html><body>no timezone here</body></html>';
+
+		$this->assertEquals( '', PageVenueExtractor::extractTimezone( $html ) );
+	}
+
+	public function test_extractTimezone_matches_royal_american_fixture() {
+		// Snapshot of https://www.theroyalamerican.com/schedule (Squarespace 7.x)
+		// captured during the #254 investigation. The full live HTML reproduces
+		// the exact failure mode of the pre-fix regex — if this stops matching,
+		// the regex has regressed.
+		$fixture = __DIR__ . '/../Fixtures/squarespace-royal-american.html';
+
+		if ( ! file_exists( $fixture ) ) {
+			$this->markTestSkipped( 'Royal American fixture not present (optional snapshot).' );
+		}
+
+		$html = file_get_contents( $fixture );
+		$this->assertEquals( 'America/New_York', PageVenueExtractor::extractTimezone( $html ) );
+	}
+}