@letsrunit/gherkin 0.1.0

package/src/locator/parser.peggy

@@ -0,0 +1,101 @@
+// Locator grammar
+// Supports:
+// - role/tag
+// - field / image / text special cases
+// - raw locators in backticks
+// - with / without / within
+//
+// Example:
+//   button "Submit" within `form#checkout`
+//   section with button "submit" within `#main`
+//   section without text "ads" within `css=.foo >> nth(2)`
+
+Start
+  = _ e:Expr _ { return e; }
+
+Expr
+  = base:WithExpr rest:(_ "within"i ![a-zA-Z] _ s:Selector { return s; })*
+    { return { type: "Within", base, ancestors: rest ?? [] }; }
+
+WithExpr
+  = sel:Selector parts:(_ wp:WithPart { return wp; })*
+    {
+      const include = [], exclude = [];
+      for (const x of parts) {
+        (x.incl ? include : exclude).push(x.p);
+      }
+      return { type: "With", selector: sel, include, exclude };
+    }
+
+WithPart
+  = "with"i ![a-zA-Z] _ p:Predicate { return { incl: true, p }; }
+  / "without"i ![a-zA-Z] _ p:Predicate { return { incl: false, p }; }
+
+// ---------- Selectors ----------
+
+Selector
+  = RawSel
+  / DateSel
+  / RoleSelFull
+  / TagSelFull
+
+// Raw Playwright locator in backticks
+RawSel
+  = "`" s:RawChars "`"
+    { return { type: "Selector", mode: "raw", raw: s.trim() }; }
+RawChars
+  = $([^`]*)
+
+// Role-first: role or special (field, image, text)
+RoleSelFull
+  = TheOpt? base:RoleSel
+    { return { type: "Selector", mode: "role", role: base.role, name: base.name }; }
+
+DateSel
+  = "date"i _ OfOpt? n:DateValue
+    { return { type: "Selector", mode: "date", name: n }; }
+
+OfOpt = "of"i ![a-zA-Z] _
+
+DateValue
+  = s:StringLit { return `"${s}"`; }
+  / $( (!(_ "within"i ![a-zA-Z]) .) + )
+
+// Role selection rules with disambiguation:
+// - If the identifier is a known role keyword (button, link, field, image, text), it's a role.
+// - Otherwise, it is treated as a role only when followed by a quoted name.
+RoleSel
+  = // Known roles may optionally have a name
+    r:KnownRole _ n:StringLit? { return { role: r, name: n ?? null }; }
+  / // Generic role: only considered a role when it has a quoted name
+    r:Ident _ n:StringLit       { return { role: r, name: n }; }
+
+KnownRole
+  = "button"i / "link"i / "field"i / "image"i / "text"i / "date"i
+
+// Tag-first (e.g. div, section, button)
+TagSelFull
+  = TheOpt? t:TagSel
+    { return { type: "Selector", mode: "tag", tag: t }; }
+
+TagSel
+  = Ident
+
+// ---------- Predicates ----------
+
+Predicate
+  = sel:Selector { return { type: "HasDescendant", selector: sel }; }
+
+// ---------- Lexical ----------
+
+TheOpt
+  = "the"i ![a-zA-Z] _
+
+Ident
+  = $([a-zA-Z_][a-zA-Z0-9_-]*)
+
+StringLit
+  = "\"" chars:($(("\\\"" / !("\"") .))* ) "\""
+    { return chars; }
+
+_ = [ \t\r\n]*

package/src/locator/regexp.ts

@@ -0,0 +1,2 @@
+const SELECTOR = /(?:the )?\w+(?: "[^"]*")?|`([^`]+|\\.)*`/;
+export const locatorRegexp = new RegExp(String.raw`((?:${SELECTOR.source})(?: with(?:in|out)? (?:${SELECTOR.source}))*)`);

package/src/parameters.ts

@@ -0,0 +1,80 @@
+import type { Scalar } from '@letsrunit/utils';
+import { KeyCombo, parseKeyCombo } from './keys/parse-key-combo';
+import { compileLocator, locatorRegexp } from './locator';
+import { arrayRegexp, scalarRegexp, valueTransformer } from './value';
+
+export interface ParameterTypeDefinition<T> {
+  name: string;
+  placeholder: string;
+  regexp: readonly RegExp[] | readonly string[] | RegExp | string;
+  transformer?: (...match: string[]) => T;
+  useForSnippets?: boolean;
+  preferForRegexpMatch?: boolean;
+}
+
+function enumToRegexp(values: readonly string[]) {
+  const satinized = values.map((v) => v.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  return new RegExp(`(${satinized.join('|')})`);
+}
+
+export function booleanParameter(
+  trueValue: string,
+  falseValue: string,
+  regexp?: RegExp,
+): ParameterTypeDefinition<boolean> {
+  return {
+    name: trueValue.replace(/\W/, '_'),
+    placeholder: `${trueValue}|${falseValue}`,
+    regexp: regexp ?? enumToRegexp([trueValue, falseValue]),
+    transformer: (value: string): boolean => value === trueValue,
+  };
+}
+
+export function enumParameter<const T extends readonly string[]>(
+  values: T,
+  regexp?: RegExp,
+): ParameterTypeDefinition<T[number]> {
+  return {
+    name: values[0].replace(/\W/, '_'),
+    placeholder: values.join('|'),
+    regexp: regexp ?? enumToRegexp(values),
+    transformer: (value: string): string => value,
+  };
+}
+
+export function valueParameter(name = 'value'): ParameterTypeDefinition<Scalar | Scalar[]> {
+  return {
+    name,
+    placeholder: name,
+    regexp: [scalarRegexp, arrayRegexp],
+    transformer: valueTransformer,
+  };
+}
+
+export function locatorParameter(name = 'locator'): ParameterTypeDefinition<string> {
+  return {
+    name,
+    placeholder: name,
+    regexp: locatorRegexp,
+    transformer: (locator: string) => {
+      try {
+        return compileLocator(locator);
+      } catch (e) {
+        console.error(e);
+        return locator;
+      }
+    },
+  };
+}
+
+export function keysParameter(name = 'keys'): ParameterTypeDefinition<KeyCombo> {
+  return {
+    name,
+    placeholder: name,
+    regexp: /"([^"]+)"|'([^']+)'/,
+    transformer: (doubleQuoted?: string, singleQuoted?: string): KeyCombo => {
+      const raw = (doubleQuoted ?? singleQuoted ?? '').trim();
+      return parseKeyCombo(raw);
+    },
+  };
+}

package/src/sanitize.ts

@@ -0,0 +1,7 @@
+export function sanitizeStepDefinition<T extends string | RegExp>(step: T): T {
+  if (typeof step !== 'string') {
+    return step;
+  }
+
+  return step.replace(/\{([^|}]+)\|[^}]+}/g, '{$1}') as any;
+}

package/src/value.ts

@@ -0,0 +1,24 @@
+import { parseDateString, type Scalar } from '@letsrunit/utils';
+
+export const scalarRegexp =
+  /"((?:[^"\\]+|\\.)*)"|(-?\d+(?:\.\d+)?)|date (?:of )?((?:today|tomorrow|yesterday|\d+ \w+ (?:ago|from now))(?: (?:at )?\d{2}:\d{2}?(?::\d{2})?)?|"\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2})?(?:.\d{3})?Z?)?")/;
+export const arrayRegexp = new RegExp(String.raw`\[(.*?)\]`);
+
+function transformScalar(str?: string, num?: string, date?: string): Scalar {
+  if (str != null) return str;
+  if (num != null) return Number(num);
+  if (date) return parseDateString(date);
+
+  throw new Error('Unexpected value');
+}
+
+export const valueTransformer = (
+  str?: string,
+  num?: string,
+  date?: string,
+  arr?: string,
+): Scalar | Scalar[] => {
+  return arr
+    ? Array.from(arr.matchAll(new RegExp(scalarRegexp, 'g')), (m) => transformScalar(m[1], m[2], m[3]))
+    : transformScalar(str, num, date);
+};