@sun-asterisk/sungen 3.2.29 → 3.2.31

package/src/utils/selector-types.ts

@@ -1,20 +1,35 @@
 /**
  * Valid selector types used across scaffold generator, selector resolver, and validator.
  * Single source of truth — import this instead of hardcoding.
+ *
+ * The list is partitioned deliberately. A type is either a LOCATOR STRATEGY (the resolver's
+ * strategy switch turns it into a Playwright/WDIO locator) or a NON-STRATEGY declaration (the
+ * entry describes something other than how to find an element, and a reader downstream of the
+ * resolver consumes it). A type that is in neither set but is still accepted as valid is drift:
+ * it reaches the switch's `default:` and resolves as `getByPlaceholder('<whatever value held>')`,
+ * a selector that cannot match. `upload` sat in exactly that gap — valid, documented, and
+ * silently mis-resolved (issue #690).
+ *
+ * Keep the partition total. `tests/codegen/selector-type-dispatch.run.ts` fails if a new member
+ * of VALID_SELECTOR_TYPES is classified into neither half, or if a strategy type stops being
+ * dispatched and starts resolving as a placeholder.
  */
-export const VALID_SELECTOR_TYPES = [
+
+/**
+ * Types the resolver turns into a locator. Every member MUST be dispatched in
+ * `SelectorResolver.resolveFromEntry` — either by a `case` in its strategy switch or by an
+ * early return above it (`locator` and `upload` share one). The contract is on the RESOLVED
+ * STRATEGY, not on the syntax used to produce it.
+ */
+export const STRATEGY_SELECTOR_TYPES = [
   'placeholder',
   'role',
   'testid',
   'label',
   'text',
-  'page',
-  'column',
   'locator',
   'id',
   'upload',
-  'frame',
-  'table',
   // === Mobile (Appium) strategies — resolved by the appium adapter (MOB-3) ===
   'accessibility-id',    // cross-platform — Android content-desc / iOS accessibilityIdentifier
   'xpath',               // cross-platform, last resort
@@ -23,4 +38,38 @@ export const VALID_SELECTOR_TYPES = [
   'css',                 // hybrid WebView only — CSS inside a WEBVIEW context (after `switch to [X] frame`)
 ] as const;
 
+/**
+ * Types that declare something OTHER than a locator strategy, so they have no `case` by design.
+ * Each is read after resolution via `ResolvedSelector.selectorType`, or by the pattern that owns
+ * the step, which reads the entry's fields directly:
+ *
+ *   page   — `value` is a URL path, not a locator. The page assertion reads `selectorType`
+ *            AFTER resolving (see StepMapper.checkPageStepFallback), so this type must
+ *            pass through the switch rather than throw.
+ *   table  — the table patterns read `columns` (StepMapper's column-index lookup), `rows` (the
+ *            row templates, backed by SG-W016) and `pagination` (the paginate step, #712) off
+ *            the entry. `pagination` was the NOTE that used to sit here: documented, plumbed,
+ *            and read by nothing — the same drift shape as #690, one level down. It has a
+ *            consumer now, and SG-W004 is the gate that makes the next such field fail a check
+ *            rather than wait to be grepped.
+ *   column — addressed through its table's `columns` map, never resolved standalone.
+ *   frame  — consumed by the frame-enter/exit steps, which need the raw iframe selector.
+ *
+ * Reaching the strategy switch is legitimate for these; the placeholder fallback there is inert
+ * because no consumer reads `strategy` for them.
+ */
+export const NON_STRATEGY_SELECTOR_TYPES = [
+  'page',
+  'column',
+  'frame',
+  'table',
+] as const;
+
+export const VALID_SELECTOR_TYPES = [
+  ...STRATEGY_SELECTOR_TYPES,
+  ...NON_STRATEGY_SELECTOR_TYPES,
+] as const;
+
+export type StrategySelectorType = (typeof STRATEGY_SELECTOR_TYPES)[number];
+export type NonStrategySelectorType = (typeof NON_STRATEGY_SELECTOR_TYPES)[number];
 export type SelectorType = (typeof VALID_SELECTOR_TYPES)[number];