waygraph 0.15.40 → 0.15.41

package/dist/practices-check.d.ts

@@ -1,4 +1,4 @@
-export type PracticeKind = "wildcard-checkpoint" | "assert-no-type-arg" | "multi-input" | "combined-action" | "empty-verify";
+export type PracticeKind = "wildcard-checkpoint" | "assert-no-type-arg" | "multi-input" | "combined-action" | "empty-verify" | "overcomplex-selector" | "inline-selector-should-use-sel-file";
 export interface PracticeWarning {
     kind: PracticeKind;
     file: string;

package/dist/practices-check.js

@@ -3,8 +3,8 @@
  * that compile but erode the typed graph. Warnings only (never fail exit code)
  * unless paired with `tsc` errors in `waygraph typecheck`.
  */
-import { readFileSync } from "node:fs";
-import { relative } from "node:path";
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, relative } from "node:path";
 /** define*Block<…Checkpoint<string>…> — prefer project Checkpoint types. */
 const WILDCARD_CHECKPOINT = /\bdefine(?:Method|Effect|Page|Nav|MemNav|NavClick|Action)Block\s*<[^>]*\bCheckpoint\s*<\s*string\s*>/;
 /** defineAssertBlock({ … }) with no explicit Out type — defaults to wildcard. */
@@ -23,6 +23,19 @@ const EMPTY_VERIFY_ARRAY = /\bverify\s*:\s*\[\s*\]/;
 /** Any `verify:` key at all, empty or not. */
 const HAS_VERIFY_KEY = /\bverify\s*:/;
 const SCAN_GLOB = /\.(block|flow)\.ts$/;
+/**
+ * A selector string reaching for a regex-based Playwright text pseudo-class (`:has-text(/…/)`,
+ * `:text-matches(…)`) or a plain XPath - real, recurring pattern: an LLM asked to target a simple
+ * element (one class, one id, one data-attribute) instead writes a regex/XPath from scratch. Not a
+ * type error (Playwright's own selector syntax accepts all of this), so nothing else catches it.
+ */
+const TEXT_MATCHES_PSEUDO = /:text-matches\(/;
+const HAS_TEXT_REGEX_PSEUDO = /:has-text\(\s*\//;
+const XPATH_LOCATOR = /\.locator\(\s*["'`](?:xpath=)?\/\//;
+/** A selector string literal inline in a Block file (`.locator("…")`, `click: "…"`, `url: "…"`) -
+ *  scoped to simple, single-token selectors (id/class/attr/tag) so this doesn't fire on the
+ *  legitimate multi-part selectors `.sel.ts` files themselves are made of. */
+const INLINE_SIMPLE_SELECTOR = /(?:\.locator|\bclick|\burl)\s*[:(]\s*["'`](#|\.)[\w-]+["'`]/;
 const METHOD_OR_EFFECT_FILE = /\.(method|effect)\.block\.ts$/;
 const METHOD_OR_EFFECT_DEFINE = /\bdefine(?:Method|Effect)Block\b/;
 /** Whole-file opt-out: `// waygraph-ignore-practices` */
@@ -107,6 +120,31 @@ export function collectPracticeWarnings(projectDir, walkDir, opts) {
                 });
             }
         }
+        if (!isIgnored("overcomplex-selector", ignore) &&
+            (TEXT_MATCHES_PSEUDO.test(src) || HAS_TEXT_REGEX_PSEUDO.test(src) || XPATH_LOCATOR.test(src))) {
+            const via = TEXT_MATCHES_PSEUDO.test(src)
+                ? ":text-matches(...)"
+                : HAS_TEXT_REGEX_PSEUDO.test(src)
+                    ? ":has-text(/regex/)"
+                    : "an XPath locator";
+            warnings.push({
+                kind: "overcomplex-selector",
+                file: rel,
+                detail: `uses ${via} — reach for a plain CSS selector (id/class/data-attribute, via a .sel.ts ` +
+                    "export) instead of a regex/XPath match unless the DOM genuinely has no stable selector",
+            });
+        }
+        if (!isIgnored("inline-selector-should-use-sel-file", ignore) && INLINE_SIMPLE_SELECTOR.test(src)) {
+            const siblingSelFile = readdirSync(dirname(file)).some((f) => f.endsWith(".sel.ts"));
+            if (siblingSelFile) {
+                warnings.push({
+                    kind: "inline-selector-should-use-sel-file",
+                    file: rel,
+                    detail: "a selector string is inlined here, but this directory already has a *.sel.ts file — " +
+                        "add/reuse the selector there instead of a new one-off literal",
+                });
+            }
+        }
         if (!isIgnored("empty-verify", ignore) && IS_ASSERT_BLOCK.test(src) && EMPTY_VERIFY_ARRAY.test(src)) {
             warnings.push({
                 kind: "empty-verify",
@@ -130,6 +168,10 @@ export function practiceKindLabel(kind) {
             return "fill and click in one Block";
         case "empty-verify":
             return "empty verify — transition unconfirmed";
+        case "overcomplex-selector":
+            return "regex/XPath selector where a plain one would do";
+        case "inline-selector-should-use-sel-file":
+            return "inline selector — a .sel.ts file already exists here";
         default: {
             const _exhaustive = kind;
             return _exhaustive;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.40",
+  "version": "0.15.41",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",

package/templates/skills/waygraph-convention.skill.md

@@ -19,7 +19,14 @@ against a live site, use `--skill-pilot-blind`.
    (no goto) even when the app changes URL as a side effect of a button click.
 3. **Selectors in `*Sel`, never inline.** DOM strings live in a `*Sel` next to the page
    (static + `(id) => …`). Mem keys store values, not selectors. `waygraph check` warns on
-   inline selector literals in `Trait.visible` / `Trait.text`.
+   inline selector literals in `Trait.visible` / `Trait.text`, and separately on any inline
+   selector literal (`.locator("#x")`, `click: "#x"`) in a directory that already has a `*Sel`.
+   **Plain CSS first, always.** An id, a class, or `[data-testid=…]` is the selector for
+   almost everything real apps have - reach for that before anything else. Don't invent a
+   regex/XPath match (`:has-text(/…/)`, `:text-matches(…)`, an XPath locator) for something a
+   one-line class or id selector already targets uniquely; `waygraph check` flags this too.
+   A regex/text match is for a genuinely unstable DOM with no stable attribute at all, not
+   the default first move.
 4. **Assert-only = `defineAssertBlock`.** Self-loop, no hand-written `act`/`resolve`. Pass
    an explicit type argument when it sits between two specifically-typed Blocks in a Flow.
    Not just static content or an action's result - it also names a *feature state* worth a