@immense/vue-pom-generator 1.0.45 → 1.0.47

package/README.md

@@ -13,6 +13,7 @@ If you already use Playwright with `getByTestId`, the point is simple: this pack
 - **Uses real template signals to name ids and methods.** Click handlers, `v-model`, `id`/`name`, `:to`, wrapper configuration, and a few targeted fallbacks all feed the generated API.
 - **Generates one aggregated TypeScript POM file** plus a stable `index.ts` barrel.
 - **Can generate Playwright fixtures** so tests can request `userListPage` instead of constructing `new UserListPage(page)` manually.
+- **Can fail fast on unnameable wrapper-button actions** so complex inline handlers do not silently degrade into low-signal generated APIs.
 - **Can emit a single C# POM file** for Playwright .NET consumers.
 - **Exposes `virtual:testids`** so your app can import the current collected test-id manifest at runtime.
 - **Ships ESLint rules** to remove legacy manually-authored test ids, ban raw `page` fixture usage in spec callbacks, and discourage raw locator actions on generated getters.
@@ -73,6 +74,7 @@ The generator does not use one naming trick. It layers several signals.
 - **Router links / `:to` bindings** can contribute route-based naming and typed navigation return types when the target can be resolved.
 - **Wrapper components** can be explicit (`nativeWrappers`) or inferred from simple local SFC templates.
 - **Fallback naming exists, but it is intentionally conservative.** That is why `generation.nameCollisionBehavior` exists.
+- **You can opt into stricter wrapper-action generation.** `errorBehavior: "error"` blocks button-like wrapper `:handler` expressions that the generator cannot turn into a semantic action name.
 
 Important limit: wrapper inference is helpful, not magical. The current implementation recursively inspects simple local SFC templates for the first inferable primitive (`input`, `textarea`, `select`, `button`, `vselect`, radio/checkbox inputs). It also recognizes some naming patterns like `*Button`. For anything more complex, configure `nativeWrappers` explicitly.
 
@@ -200,6 +202,7 @@ const pomConfig = defineVuePomGeneratorConfig({
     script: { defineModel: true, propsDestructure: true },
   },
   logging: { verbosity: "info" },
+  errorBehavior: "error",
   injection: {
     attribute: "data-testid",
     viewsDir: "src/views",
@@ -804,6 +807,18 @@ The sections below follow the actual `VuePomGeneratorPluginOptions` shape from `
   logging: { verbosity: "debug" }
   ```
 
+#### `errorBehavior`
+
+- **What it does:** Controls strict/error behavior for generator checks.
+- **Why it exists:** complex inline handlers can otherwise fall through to generic naming, which makes generated APIs harder to discover and review.
+- **Benefit:** `"error"` lets you opt into fail-fast behavior globally, while the object form lets you turn on only the checks you care about.
+- **Without it:** the default is `"ignore"`, so existing permissive fallback behavior remains in place.
+- **Accepted values:**
+  - `"ignore"` — keep permissive defaults for all supported checks
+  - `"error"` — enable error-on-failure behavior for all supported checks
+  - `{ missingSemanticNameBehavior: "error" }` — enable only the button-wrapper semantic-name check
+- **Current scope:** this first pass is intentionally narrow. The object form currently supports `missingSemanticNameBehavior`, which targets button-like wrappers with `:handler`; value/model-driven wrappers still use their existing naming flow.
+
 ### `injection`
 
 `injection` controls compile-time test-id derivation and template rewriting.

package/RELEASE_NOTES.md

@@ -1,52 +1,49 @@
 ● ## Highlights
 
-  - New ESLint rule `no-page-fixture-in-specs` enforces Playwright Page Object Model best
-  practices
-  - Dev-mode POM generation now has parity with build mode
-  - Fail-fast behavior added for dev snapshot generation errors
-  - Enhanced test coverage with build-serve parity regression tests
-  - Improved release workflow with PR preview comments
+  - **Fail-fast validation** for wrapper handlers that cannot be named, improving error detection
+  at build time
+  - Added comprehensive validation logic across plugin lifecycle (dev and build modes)
+  - Expanded test coverage with 54+ new test cases for handler naming scenarios
+  - Enhanced error reporting when anonymous or unnameable handlers are detected
+  - Updated documentation with new validation requirements and best practices
 
   ## Changes
 
-  **Tooling & Linting**
-  - Added new ESLint rule to prevent `page` fixture usage in spec files (112 lines)
-  - Updated ESLint configuration and exports
+  **Core Validation**
+  - Added fail-fast validation in `transform.ts` to detect unnameable wrapper handlers before
+  runtime
+  - Implemented handler name validation in `create-vue-pom-generator-plugins.ts` with detailed
+  error messages
+  - Added validation hooks in both `build-plugin.ts` and `dev-plugin.ts` for consistency across
+  modes
 
-  **Code Generation**
-  - Fixed keyed POM deduplication logic
-  - Improved C# navigation return types
-  - Minor adjustments to class generation
+  **Type System & API**
+  - Extended plugin types with new validation options and error handling interfaces
+  - Added support for configurable validation behavior in plugin options
 
   **Testing**
-  - Added comprehensive vue-plugin-state tests (71 lines)
-  - Enhanced ESLint rule test coverage (58 new lines)
-  - Added build-serve parity regression tests
-  - Updated test assertions for better coverage
+  - Added 54 new test cases in `options.test.ts` covering edge cases for handler naming
+  - Added 23 new tests in `transform.test.ts` for transformation validation
+  - Added 9 coverage tests in `utils-coverage.test.ts`
+  - Enhanced `dev-plugin-options.test.ts` with validation scenario tests
 
-  **Documentation & CI**
-  - Updated README with improved guidance (54 lines added)
-  - Enhanced release workflow with PR release-notes preview comments
-  - Workflow improvements for Playwright generator
+  **Documentation**
+  - Updated README.md with guidance on handler naming requirements and validation behavior
 
   ## Breaking Changes
 
-  None.
+  - **Handler naming validation**: The plugin now throws errors when wrapper handlers cannot be
+  named (anonymous functions, computed property names, etc.). Code that previously compiled with
+  unnameable handlers will now fail at build time. Ensure all wrapper handlers have statically
+  determinable names.
 
   ## Pull Requests Included
 
-  - #7 test: add build–serve parity regression tests
-  (https://github.com/immense/vue-pom-generator/pull/7)
-  - #6 fix: fail fast on dev snapshot generation errors
-  (https://github.com/immense/vue-pom-generator/pull/6)
-  - #5 fix: dev-mode POM generation parity with build mode
-  (https://github.com/immense/vue-pom-generator/pull/5)
-  - #4 Fix keyed POM dedupe and C# navigation returns
-  (https://github.com/immense/vue-pom-generator/pull/4)
-  - #1 Add PR release-notes preview comments (https://github.com/immense/vue-pom-generator/pull/1)
+  - #11: feat: fail fast on unnameable wrapper handlers
+  (https://github.com/immense/vue-pom-generator/pull/11) by @dkattan
 
   ## Testing
 
-  All changes include corresponding test coverage. Added 132 lines of new tests across
-  vue-plugin-state and ESLint rule validation.
+  Comprehensive test coverage added with 80+ new test cases spanning handler naming validation,
+  transformation scenarios, plugin options, and edge case coverage.
 

package/dist/index.cjs

@@ -5437,6 +5437,7 @@ function createTestIdTransform(componentName, componentHierarchyMap, nativeWrapp
   const existingIdBehavior = options.existingIdBehavior ?? "preserve";
   const testIdAttribute = (options.testIdAttribute || "data-testid").trim() || "data-testid";
   const nameCollisionBehavior = options.nameCollisionBehavior ?? "suffix";
+  const missingSemanticNameBehavior = options.missingSemanticNameBehavior ?? "ignore";
   const warn = options.warn;
   const vueFilesPathMap = options.vueFilesPathMap;
   const wrapperSearchRoots = options.wrapperSearchRoots ?? [];
@@ -5702,6 +5703,22 @@ function createTestIdTransform(componentName, componentHierarchyMap, nativeWrapp
       });
     };
     const { nativeWrappersValue, optionDataTestIdPrefixValue, semanticNameHint } = getNativeWrapperTransformInfo(element, componentName, nativeWrappers);
+    const handlerDirective = element.props.find((p) => {
+      return p.type === compilerCore.NodeTypes.DIRECTIVE && p.name === "bind" && p.arg?.type === compilerCore.NodeTypes.SIMPLE_EXPRESSION && p.arg.content === "handler" && !!p.exp;
+    }) ?? null;
+    const handlerInfo = handlerDirective ? nodeHandlerAttributeInfo(element) : null;
+    if (missingSemanticNameBehavior === "error" && nativeWrappers[element.tag]?.role === "button" && handlerDirective && !handlerInfo) {
+      const loc = element.loc?.start;
+      const locationHint = loc ? `${loc.line}:${loc.column}` : "unknown";
+      const handlerSource = (handlerDirective.exp?.loc?.source ?? "").trim() || "<unknown>";
+      throw new Error(
+        `[vue-pom-generator] Could not derive a semantic POM action name for button-like wrapper in ${componentName} (${context.filename ?? "unknown"}:${locationHint}).
+Element: <${element.tag}>
+Handler: ${handlerSource}
+
+Fix: move complex inline logic into a named function (for example, const onAction = () => ...; then bind :handler="onAction"), or simplify the handler to a direct identifier/call the generator can name. You can also set errorBehavior = "ignore" to keep generic fallback behavior.`
+      );
+    }
     if (nativeWrappersValue) {
       if (optionDataTestIdPrefixValue) {
         const existing = existingIdBehavior === "preserve" ? tryGetExistingElementDataTestId(element, testIdAttribute) : null;
@@ -5811,7 +5828,6 @@ Fix: remove the explicit ${attrLabel}, or change existingIdBehavior to "overwrit
       });
       return;
     }
-    const handlerInfo = nodeHandlerAttributeInfo(element);
     if (handlerInfo) {
       const testId = getHandlerAttributeValueDataTestId(handlerInfo.semanticNameHint);
       applyResolvedDataTestIdForElement({
@@ -5920,6 +5936,7 @@ function createBuildProcessorPlugin(options) {
     customPomImportNameCollisionBehavior,
     testIdAttribute,
     nameCollisionBehavior,
+    missingSemanticNameBehavior,
     existingIdBehavior,
     nativeWrappers,
     excludedComponents,
@@ -6030,6 +6047,7 @@ function createBuildProcessorPlugin(options) {
                   existingIdBehavior: existingIdBehavior ?? "preserve",
                   testIdAttribute,
                   nameCollisionBehavior,
+                  missingSemanticNameBehavior,
                   warn: (message) => loggerRef.current.warn(message),
                   vueFilesPathMap,
                   wrapperSearchRoots: getWrapperSearchRoots()
@@ -6154,6 +6172,7 @@ function createDevProcessorPlugin(options) {
     customPomImportAliases,
     customPomImportNameCollisionBehavior,
     nameCollisionBehavior = "suffix",
+    missingSemanticNameBehavior,
     existingIdBehavior,
     testIdAttribute,
     routerAwarePoms,
@@ -6318,6 +6337,7 @@ function createDevProcessorPlugin(options) {
               {
                 existingIdBehavior: existingIdBehavior ?? "preserve",
                 nameCollisionBehavior,
+                missingSemanticNameBehavior,
                 testIdAttribute,
                 warn: (message) => loggerRef.current.warn(message),
                 vueFilesPathMap: targetVuePathMap,
@@ -6558,6 +6578,7 @@ function createSupportPlugins(options) {
     scanDirs,
     getWrapperSearchRoots,
     nameCollisionBehavior = "suffix",
+    missingSemanticNameBehavior,
     existingIdBehavior,
     outDir,
     emitLanguages,
@@ -6613,6 +6634,7 @@ function createSupportPlugins(options) {
     customPomImportNameCollisionBehavior,
     testIdAttribute,
     nameCollisionBehavior,
+    missingSemanticNameBehavior,
     existingIdBehavior,
     nativeWrappers,
     excludedComponents,
@@ -6641,6 +6663,7 @@ function createSupportPlugins(options) {
     customPomImportAliases,
     customPomImportNameCollisionBehavior,
     nameCollisionBehavior,
+    missingSemanticNameBehavior,
     existingIdBehavior,
     testIdAttribute,
     routerAwarePoms,
@@ -7015,6 +7038,41 @@ function assertNonEmptyStringArray(value, name) {
     assertNonEmptyString(entry, `${name}[${index}]`);
   }
 }
+function assertOneOf(value, allowed, name) {
+  if (!value)
+    return;
+  if (allowed.includes(value)) {
+    return;
+  }
+  throw new TypeError(`${name} must be one of: ${allowed.join(", ")}.`);
+}
+function assertErrorBehavior(value, name) {
+  if (!value) {
+    return;
+  }
+  if (value === "ignore" || value === "error") {
+    return;
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${name} must be "ignore", "error", or an object.`);
+  }
+  const supportedKeys = /* @__PURE__ */ new Set(["missingSemanticNameBehavior"]);
+  for (const key of Object.keys(value)) {
+    if (!supportedKeys.has(key)) {
+      throw new TypeError(`${name} contains unsupported key "${key}".`);
+    }
+  }
+  assertOneOf(value.missingSemanticNameBehavior, ["ignore", "error"], `${name}.missingSemanticNameBehavior`);
+}
+function resolveMissingSemanticNameBehavior(value) {
+  if (!value) {
+    return "ignore";
+  }
+  if (value === "ignore" || value === "error") {
+    return value;
+  }
+  return value.missingSemanticNameBehavior ?? "ignore";
+}
 function assertRouterModuleShims(value, name) {
   if (!value)
     return;
@@ -7147,6 +7205,8 @@ function createVuePomGeneratorPlugins(options = {}) {
   const vuePluginOwnership = isNuxt ? "external" : options.vuePluginOwnership ?? "internal";
   const usesExternalVuePlugin = vuePluginOwnership === "external";
   const csharp = generationOptions?.csharp;
+  const errorBehavior = options.errorBehavior;
+  const missingSemanticNameBehavior = resolveMissingSemanticNameBehavior(errorBehavior);
   const generateFixtures = generationOptions?.playwright?.fixtures;
   const customPoms = generationOptions?.playwright?.customPoms;
   const resolvedCustomPomAttachments = customPoms?.attachments ?? [];
@@ -7178,6 +7238,7 @@ function createVuePomGeneratorPlugins(options = {}) {
       assertNonEmptyString(testIdAttribute, "[vue-pom-generator] injection.attribute");
       assertNonEmptyString(viewsDir, "[vue-pom-generator] injection.viewsDir");
       assertNonEmptyStringArray(wrapperSearchRoots, "[vue-pom-generator] injection.wrapperSearchRoots");
+      assertErrorBehavior(errorBehavior, "[vue-pom-generator] errorBehavior");
       if (generationEnabled) {
         assertNonEmptyString(outDir, "[vue-pom-generator] generation.outDir");
         assertRouterModuleShims(routerModuleShims, "[vue-pom-generator] generation.router.moduleShims");
@@ -7189,7 +7250,7 @@ function createVuePomGeneratorPlugins(options = {}) {
         applyTemplateCompilerOptionsToResolvedVuePlugin(config, templateCompilerOptions, isNuxt ? "nuxt" : vuePluginOwnership);
       }
       loggerRef.current.info(`projectRoot=${projectRootRef.current}`);
-      loggerRef.current.info(`Active plugins: ${config.plugins.map((p) => p.name).filter((n) => n.includes("vue-pom")).join(", ")}`);
+      loggerRef.current.info(`Active plugins: ${(config.plugins ?? []).map((p) => p.name).filter((n) => n.includes("vue-pom")).join(", ")}`);
     }
   };
   const getViewsDirAbs = () => resolveFromProjectRoot(projectRootRef.current, viewsDir);
@@ -7223,6 +7284,7 @@ function createVuePomGeneratorPlugins(options = {}) {
     scanDirs,
     getWrapperSearchRoots: getWrapperSearchRootsAbs,
     nameCollisionBehavior,
+    missingSemanticNameBehavior,
     existingIdBehavior,
     outDir,
     emitLanguages,