@immense/vue-pom-generator 1.0.46 → 1.0.48

package/README.md

@@ -3,7 +3,7 @@
 `@immense/vue-pom-generator` is a Vite plugin for Vue 3 that does two compile-time jobs:
 
 1. it injects a test-id attribute into interactive elements in `.vue` templates
-2. it turns the collected ids into an aggregated Page Object Model library for Playwright, with optional Playwright fixtures and optional C# output
+2. it turns the collected ids into a Page Object Model library for Playwright, with aggregated or split TypeScript output, optional Playwright fixtures, and optional C# output
 
 If you already use Playwright with `getByTestId`, the point is simple: this package removes the repetitive work of keeping test ids in sync with Vue templates and then hand-writing page objects around those ids.
 
@@ -11,8 +11,9 @@ If you already use Playwright with `getByTestId`, the point is simple: this pack
 
 - **Injects test ids during Vue compilation, not at runtime.** It hooks into the Vue template compiler and rewrites the compiled template output.
 - **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.
+- **Generates TypeScript POM output as either one aggregate or split per class, always with 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",
@@ -231,6 +234,7 @@ const pomConfig = defineVuePomGeneratorConfig({
     },
     playwright: {
       fixtures: true,
+      outputStructure: "split",
       customPoms: {
         dir: "tests/playwright/pom/custom",
         importAliases: {
@@ -291,9 +295,13 @@ By default, generation writes to `tests/playwright/__generated__`.
 
 TypeScript output:
 
-- `page-object-models.g.ts` — aggregated generated classes
-- `index.ts` — stable barrel re-exporting `page-object-models.g`
-- `_pom-runtime/` — copied runtime support files used by the aggregated output
+- default (`generation.playwright.outputStructure: "aggregated"`):
+  - `page-object-models.g.ts` — aggregated generated classes
+  - `index.ts` — stable barrel re-exporting `page-object-models.g`
+- split mode (`generation.playwright.outputStructure: "split"`):
+  - one `*.g.ts` file per generated class
+  - `index.ts` — stable barrel re-exporting the split files
+- `_pom-runtime/` — copied runtime support files used by the generated TypeScript output in either mode
 
 Optional Playwright fixture output:
 
@@ -310,7 +318,7 @@ If you emit outside a `__generated__` path, the generator also manages `.gitattr
 
 This is important if you are deciding whether the tool will fit into a real codebase.
 
-- **Dev server:** on startup, it scans the configured `scanDirs`, compiles each `.vue` file into a snapshot, writes the aggregated outputs once, then batches add/change/delete events and regenerates incrementally.
+- **Dev server:** on startup, it scans the configured `scanDirs`, compiles each `.vue` file into a snapshot, writes the configured TypeScript outputs once, then batches add/change/delete events and regenerates incrementally.
 - **Build:** it generates from the richest build pass it sees, which matters because Vite can run multiple passes (for example SSR plus client). The generator avoids letting a thinner pass clobber a richer one.
 - **Always-on virtual module:** `virtual:testids` is registered whether generation is enabled or disabled.
 - **Generation can be disabled:** `generation: false` still keeps compile-time test-id injection and the virtual module, but skips emitted POM files.
@@ -380,7 +388,7 @@ These two directories solve different problems.
 
 Default: `tests/playwright/pom/custom`
 
-This directory is for handwritten helper classes that the aggregated TypeScript output can import.
+This directory is for handwritten helper classes that the generated TypeScript output can import.
 
 It is the default helper directory even if you omit `generation.playwright.customPoms` entirely.
 
@@ -389,7 +397,7 @@ Actual current behavior:
 - the generator scans the directory **non-recursively**
 - it imports top-level `.ts` files only
 - it expects the file basename to match the exported class name (`Grid.ts` → `export class Grid {}`)
-- the helper files are imported into the generated aggregate; they are **not** automatically attached everywhere
+- the helper files are available to generated output; they are **not** automatically attached everywhere
 
 What it is for:
 
@@ -431,7 +439,7 @@ A typical override looks like this:
 
 ```ts
 // tests/playwright/pom/overrides/UserListPage.ts
-import { UserListPage as GeneratedUserListPage } from "../../__generated__/page-object-models.g";
+import { UserListPage as GeneratedUserListPage } from "../../__generated__";
 
 export class UserListPage extends GeneratedUserListPage {
   async openFirstUser() {
@@ -446,7 +454,10 @@ This is where most people need precision.
 
 ### Helper imports
 
-Every `.ts` file in `customPoms.dir` becomes an import in the aggregated TypeScript output.
+Every `.ts` file in `customPoms.dir` is available for import from the generated TypeScript output.
+
+- in aggregated mode, helper files become imports in the shared aggregate
+- in split mode, each generated file imports only the helpers it actually needs
 
 Benefits:
 
@@ -804,6 +815,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.
@@ -1022,6 +1045,17 @@ This object holds Playwright-specific additions on top of the generated TypeScri
   - `"path"` — if the string ends in `.ts` / `.tsx` / `.mts` / `.cts`, it is treated as a file path; otherwise as an output directory
   - `{ outDir }` — emit to a custom directory
 
+#### `generation.playwright.outputStructure`
+
+- **What it does:** Chooses whether generated TypeScript POMs are emitted as one aggregate or split per class.
+- **Why it exists:** very large generated files are harder to browse, inspect, and discover in editors.
+- **Benefit:** `"split"` keeps the same stable barrel and fixtures surface while making individual classes and methods easier to find.
+- **Without it:** the default is `"aggregated"`.
+- **Accepted values:**
+  - `"aggregated"` — emit `page-object-models.g.ts` plus `index.ts`
+  - `"split"` — emit one `*.g.ts` file per class plus `index.ts`
+- **Current limit:** this setting only affects the generated TypeScript Playwright output; C# output remains a single aggregated file.
+
 #### `generation.playwright.customPoms`
 
 - **What it does:** Configures handwritten helper imports and attachments.
@@ -1048,7 +1082,7 @@ This object holds Playwright-specific additions on top of the generated TypeScri
 #### `customPoms.importNameCollisionBehavior`
 
 - **What it does:** Controls how helper import names behave when they collide with generated class names.
-- **Why it exists:** aggregated output shares one import namespace.
+- **Why it exists:** generated files still need a conflict-free local import namespace.
 - **Benefit:** lets you fail hard or auto-alias based on team preference.
 - **Without it:** the default is `"error"`.
 

package/RELEASE_NOTES.md

@@ -1,42 +1,53 @@
-● ## Highlights
+● # Release Notes: v1.0.48
 
-  - Fixed dev-mode POM generation to match build mode behavior
-  - Added build–serve parity regression tests
-  - Improved error handling: fail fast on dev snapshot generation errors
-  - Fixed keyed POM deduplication and C# navigation returns
-  - Added automated PR release notes preview comments
+  ## Highlights
+
+  - **Split Playwright POM Output**: Added new option to generate split/modular Page Object Models
+   for improved discoverability and maintainability
+  - **ts-morph Integration**: Migrated TypeScript code generation to use ts-morph library for more
+   robust and maintainable type emission
+  - **Fail-Fast Error Handling**: Now fails immediately when encountering unnameable wrapper
+  handlers instead of generating invalid code
+  - **Enhanced Type Safety**: Improved TypeScript code generation structure with dedicated
+  emitters and better type definitions
 
   ## Changes
 
-  **Testing & Quality**
-  - Added regression tests for build–serve parity (#7)
+  ### Features
+  - Add split Playwright POM output for improved discoverability (#12)
+  - Fail fast on unnameable wrapper handlers instead of silently generating invalid code (#11)
 
-  **Bug Fixes**
-  - Fixed dev-mode POM generation parity with build mode (#5)
-  - Fail fast on dev snapshot generation errors (#6)
-  - Fixed keyed POM dedupe and C# navigation returns (#4)
+  ### Refactoring & Code Quality
+  - Migrate to ts-morph for TypeScript code generation
+  - Structure ts-morph emitters into dedicated modules
+  - Clean up split stub generation logic
+  - Address PR feedback on split output implementation
+  - Remove duplicate rebase leftovers
 
-  **CI/CD**
-  - Use sentinel package version in release workflow
-  - Added automated PR release-notes preview comments (#1)
+  ### Configuration & Types
+  - Add ts-morph dependency to package.json
+  - Update plugin types to support split output options
+  - Enhance manifest generator for split POM structure
 
-  ## Breaking Changes
+  ### Testing
+  - Add comprehensive tests for generated TypeScript output
+  - Add test fixtures for BasePage (full/minimal), Pointer, and playwright-test declarations
+  - Update class generation coverage tests
+  - Add option tests for new split output configuration
 
-  None.
+  ### Documentation
+  - Update README with split output documentation and usage examples
 
   ## 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)
+  - #12 feat: add split Playwright POM output for discoverability
+  (https://github.com/immense/vue-pom-generator/pull/12)
+  - #11 feat: fail fast on unnameable wrapper handlers
+  (https://github.com/immense/vue-pom-generator/pull/11)
 
   ## Testing
 
-  Added regression tests to ensure build and serve modes produce consistent output.
+  Added 173+ lines of new tests for TypeScript code generation, including fixtures for BasePage
+  and Pointer types. Updated existing test suites to cover split output scenarios and plugin
+  options.