@immense/vue-pom-generator 1.0.60 → 1.0.61

package/README.md

@@ -693,6 +693,7 @@ What it contains:
 - `testIdManifest`: each value is a sorted array of collected test ids for that component
 - `pomManifest`: richer per-component metadata including source file, generated locator/property names, and generated action names
 - each manifest entry also carries `locatorDescription`, which matches the human-readable label used by generated Playwright locators
+- each manifest entry may also carry `accessibility`, a compile-time review signal with static metadata, accessible-name hints, and `needsReview`
 
 What it is good for:
 
@@ -722,7 +723,7 @@ What it contains:
 
 - an object keyed by component/page object model class name
 - for each component: source file, whether it is a view or component, sorted test ids, and rich entry metadata
-- for each entry: test id, semantic name, inferred role, generated property name, generated action names, and collected compiler metadata when available
+- for each entry: test id, semantic name, inferred role, generated property name, generated action names, collected compiler metadata when available, and accessibility review metadata when available
 
 ## ESLint rules that actually ship
 
@@ -1054,6 +1055,13 @@ Set `generation: false` to keep injection and `virtual:testids` but skip emitted
 - **Benefit:** you can keep your own BasePage implementation while still using the generator.
 - **Without it:** the package uses its bundled `class-generation/BasePage.ts`.
 
+#### `generation.accessibilityAudit`
+
+- **What it does:** emits warnings for generated interactive elements whose accessible-name signals look weak or unverifiable from compile-time metadata.
+- **Why it exists:** generated POM coverage can look healthy while the underlying control still needs an accessibility review.
+- **Benefit:** gives you an opt-in review signal without auto-injecting ARIA or guessing runtime behavior.
+- **Without it:** accessibility review metadata can still appear in `pomManifest`, but no warnings are emitted during compilation.
+
 ### `generation.router`
 
 If omitted, router introspection is off.

package/RELEASE_NOTES.md

@@ -1,45 +1,49 @@
-● ## Highlights
+● # Release Notes: v1.0.61
 
-  - **Manifest and locator descriptions**: Page Object Model (POM) manifests now include
-  human-readable descriptions for both routes and locators, improving discoverability and
-  developer experience
-  - **New discoverability module**: Added `pom-discoverability.ts` to centralize description
-  generation and introspection logic
-  - **Enhanced test coverage**: Expanded tests for class generation, virtual modules, and base
-  page functionality
+  ## Highlights
+
+  - **New accessibility audit system** to detect and warn about common ARIA and semantic HTML
+  issues during POM generation
+  - Audit signals now included in the manifest output for downstream consumption
+  - Enhanced compiler metadata utilities to extract role and label information from templates
+  - Comprehensive test coverage for the new accessibility audit features
 
   ## Changes
 
-  **Core Features**
-  - Added manifest and locator description generation for improved POM documentation (#24)
-  - Implemented new `pom-discoverability.ts` module for centralized description handling
+  ### Accessibility & Quality
+  - Added `accessibility-audit.ts` module with audit functions for detecting missing labels,
+  invalid ARIA usage, and semantic violations
+  - Integrated audit warnings into the Vite plugin pipeline with configurable severity
+  - Extended manifest generator to include `auditSignals` for each component
+
+  ### Plugin & Configuration
+  - Added `auditSeverity` option to plugin configuration (default: `"warn"`)
+  - Enhanced `ResolvedGenerationOptions` to support audit configuration
+  - Updated plugin to emit warnings when accessibility issues are detected during build
 
-  **Generator Improvements**
-  - Enhanced `manifest-generator.ts` with description support (+256 lines)
-  - Updated method generation to include locator descriptions
-  - Improved base page class generation with description metadata
+  ### Compiler & Metadata
+  - Improved `compiler-metadata-utils.ts` to extract `role` and `aria-label` attributes
+  - Enhanced metadata collector to capture accessibility-related attributes
 
-  **Plugin & Integration**
-  - Updated virtual module system to support description exports
-  - Enhanced Vite plugin integration for description handling
+  ### Documentation
+  - Updated README with information about the new accessibility audit feature
 
-  **Testing & Documentation**
-  - Added class generation coverage tests
-  - Expanded virtual test ID tests with description validation
-  - Updated README with new feature documentation
-  - Refreshed generated TypeScript fixtures
+  ### Testing
+  - Added comprehensive test suite in `tests/accessibility-audit.test.ts` (54 new tests)
+  - Added tests for resolved generation options
+  - Updated existing tests to accommodate new audit functionality
 
   ## Breaking Changes
 
-  None
+  None.
 
   ## Pull Requests Included
 
-  - #24 feat: add manifest and locator descriptions
-  (https://github.com/immense/vue-pom-generator/pull/24)
+  - #25 feat: add accessibility audit metadata and warnings
+  (https://github.com/immense/vue-pom-generator/pull/25) by @dkattan
 
   ## Testing
 
-  All changes include corresponding test coverage. Added new test suites for class generation
-  coverage and expanded virtual module tests to validate description functionality.
+  All changes include full test coverage. New test suite validates audit detection for missing
+  labels, invalid ARIA attributes, redundant roles, and other semantic issues.
 

package/dist/accessibility-audit.d.ts

@@ -0,0 +1,20 @@
+import type { ElementMetadata } from "./metadata-collector";
+export interface AccessibilityAuditResult {
+    needsReview: boolean;
+    accessibleNameSource: "aria-label" | "title" | "text" | "dynamic" | "unknown" | "missing";
+    reasons: string[];
+    staticAriaLabel?: string;
+    staticRole?: string;
+    staticTitle?: string;
+    staticTextContent?: string;
+}
+export declare function buildAccessibilityAudit(metadata: ElementMetadata | undefined, inferredRole: string | null): AccessibilityAuditResult | undefined;
+export declare function collectAccessibilityReviewWarnings(manifest: Record<string, {
+    entries: Array<{
+        testId: string;
+        generatedPropertyName: string | null;
+        inferredRole: string | null;
+        accessibility?: AccessibilityAuditResult;
+    }>;
+}>): string[];
+//# sourceMappingURL=accessibility-audit.d.ts.map

package/dist/accessibility-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessibility-audit.d.ts","sourceRoot":"","sources":["../accessibility-audit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG5D,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,OAAO,CAAC;IACrB,oBAAoB,EAAE,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC1F,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAMD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,eAAe,GAAG,SAAS,EACrC,YAAY,EAAE,MAAM,GAAG,IAAI,GAC1B,wBAAwB,GAAG,SAAS,CA4CtC;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,KAAK,CAAC;QACxC,MAAM,EAAE,MAAM,CAAC;QACf,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;QACrC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,aAAa,CAAC,EAAE,wBAAwB,CAAC;KAC1C,CAAC,CAAA;CAAE,CAAC,GACJ,MAAM,EAAE,CAmBV"}

package/dist/compiler-metadata-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compiler-metadata-utils.d.ts","sourceRoot":"","sources":["../compiler-metadata-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,WAAW,EACX,oBAAoB,EAErB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,aAAa,GAAG,SAAS,CAAC;AAEvE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,EAAE,aAAa,GAAE,MAAsB,GAAG,cAAc,CAQ9G;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAcrE;AAED,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CA+C/G;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,WAAW,CAAC;IACrB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC,EAAE,OAAO,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,eAAe,GAAG,IAAI,CA+DzB"}
+{"version":3,"file":"compiler-metadata-utils.d.ts","sourceRoot":"","sources":["../compiler-metadata-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,WAAW,EACX,oBAAoB,EAGrB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,aAAa,GAAG,SAAS,CAAC;AAEvE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,EAAE,aAAa,GAAE,MAAsB,GAAG,cAAc,CAQ9G;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAcrE;AAED,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CA+C/G;AAkCD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,WAAW,CAAC;IACrB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC,EAAE,OAAO,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,eAAe,GAAG,IAAI,CA2DzB"}

package/dist/index.cjs

@@ -260,6 +260,7 @@ function resolveGenerationSupportOptions(options) {
     nameCollisionBehavior: options.nameCollisionBehavior ?? "error",
     existingIdBehavior: options.existingIdBehavior ?? "error",
     testIdAttribute: (options.testIdAttribute ?? "data-testid").trim() || "data-testid",
+    accessibilityAudit: options.accessibilityAudit ?? false,
     routerAwarePoms: options.routerAwarePoms ?? false,
     routerEntry: options.routerEntry,
     routerType: options.routerType ?? "vue-router",
@@ -8214,6 +8215,59 @@ function createDevProcessorPlugin(options) {
     }
   };
 }
+function supportsInlineTextAccessibleName(role) {
+  return role === "button" || role === "radio";
+}
+function buildAccessibilityAudit(metadata, inferredRole) {
+  if (!metadata || !inferredRole) {
+    return void 0;
+  }
+  const role = normalizePomRoleLabel(inferredRole).toLowerCase();
+  const dynamicProps = new Set(metadata.dynamicProps ?? []);
+  const hasDynamicAccessibleNameSignal = dynamicProps.has("aria-label") || dynamicProps.has("title") || !!metadata.hasDynamicText;
+  let accessibleNameSource;
+  const reasons = [];
+  if (metadata.staticAriaLabel) {
+    accessibleNameSource = "aria-label";
+  } else if (supportsInlineTextAccessibleName(role) && metadata.staticTextContent) {
+    accessibleNameSource = "text";
+  } else if (metadata.staticTitle) {
+    accessibleNameSource = "title";
+  } else if (hasDynamicAccessibleNameSignal) {
+    accessibleNameSource = "dynamic";
+  } else if (role === "input" || role === "select") {
+    accessibleNameSource = "unknown";
+    reasons.push("No inline accessible-name signal was found; the element may rely on external markup such as a separate <label>.");
+  } else {
+    accessibleNameSource = "missing";
+    reasons.push("No compile-time accessible-name signal was found.");
+  }
+  return {
+    needsReview: accessibleNameSource === "unknown" || accessibleNameSource === "missing",
+    accessibleNameSource,
+    reasons,
+    ...metadata.staticAriaLabel ? { staticAriaLabel: metadata.staticAriaLabel } : {},
+    ...metadata.staticRole ? { staticRole: metadata.staticRole } : {},
+    ...metadata.staticTitle ? { staticTitle: metadata.staticTitle } : {},
+    ...metadata.staticTextContent ? { staticTextContent: metadata.staticTextContent } : {}
+  };
+}
+function collectAccessibilityReviewWarnings(manifest) {
+  const warnings = [];
+  for (const [componentName, component] of Object.entries(manifest)) {
+    for (const entry of component.entries) {
+      if (!entry.accessibility?.needsReview) {
+        continue;
+      }
+      const entryLabel = entry.generatedPropertyName ?? entry.testId;
+      const reasonText = entry.accessibility.reasons.join(" ");
+      warnings.push(
+        `[vue-pom-generator] Accessibility review suggested for ${componentName}.${entryLabel} (role=${entry.inferredRole ?? "unknown"}, testId=${JSON.stringify(entry.testId)}): ${reasonText}`
+      );
+    }
+  }
+  return warnings;
+}
 function removeByKeySegment(value) {
   const idx = value.indexOf("ByKey");
   if (idx < 0) {
@@ -8272,6 +8326,7 @@ function getManifestEntry(componentName, entry, componentMetadata, extraMethods)
     ...generatedActionName ? [generatedActionName] : [],
     ...extraActionNames.filter((name) => name !== generatedActionName)
   ]));
+  const accessibility = buildAccessibilityAudit(metadata, pom?.nativeRole ?? null);
   return {
     testId,
     selectorPatternKind: entry.selectorValue.patternKind,
@@ -8282,6 +8337,7 @@ function getManifestEntry(componentName, entry, componentMetadata, extraMethods)
       nativeRole: pom.nativeRole
     }) : componentName,
     inferredRole: pom?.nativeRole ?? null,
+    ...accessibility ? { accessibility } : {},
     generatedPropertyName: pom ? getGeneratedPropertyName(pom) : null,
     generatedActionName,
     generatedActionNames,
@@ -8557,6 +8613,33 @@ function parseDynamicProps(dynamicProps) {
   }
   return void 0;
 }
+function findStaticAttributeValue(element, attributeName) {
+  const attribute = element.props.find(
+    (prop) => prop.type === compilerCore.NodeTypes.ATTRIBUTE && prop.name === attributeName
+  );
+  const value = attribute?.value?.content?.trim();
+  return value ? value : void 0;
+}
+function collectStaticTextContent(children) {
+  const parts = [];
+  const visit = (nodes) => {
+    for (const node of nodes) {
+      if (node.type === compilerCore.NodeTypes.TEXT) {
+        const text2 = node.content.replace(/\s+/g, " ").trim();
+        if (text2) {
+          parts.push(text2);
+        }
+        continue;
+      }
+      if (node.type === compilerCore.NodeTypes.ELEMENT) {
+        visit(node.children);
+      }
+    }
+  };
+  visit(children);
+  const text = parts.join(" ").replace(/\s+/g, " ").trim();
+  return text || void 0;
+}
 function tryCreateElementMetadata(args) {
   const { element, semanticNameMap } = args;
   const testIdAttribute = (args.testIdAttribute ?? "data-testid").trim() || "data-testid";
@@ -8580,13 +8663,9 @@ function tryCreateElementMetadata(args) {
       dynamicPropsList = [content];
     }
   }
-  const semanticName = semanticNameMap.get(testId);
-  if (!semanticName) {
-    return null;
-  }
   const metadata = {
     testId,
-    semanticName,
+    semanticName: semanticNameMap.get(testId),
     tag: element.tag,
     tagType: element.tagType,
     patchFlag,
@@ -8595,7 +8674,11 @@ function tryCreateElementMetadata(args) {
     hasClickHandler: patchFlag ? Boolean(patchFlag & 32) : void 0,
     hasDynamicClass: patchFlag ? Boolean(patchFlag & 2) : void 0,
     hasDynamicStyle: patchFlag ? Boolean(patchFlag & 4) : void 0,
-    hasDynamicText: patchFlag ? Boolean(patchFlag & 1) : void 0
+    hasDynamicText: patchFlag ? Boolean(patchFlag & 1) : void 0,
+    staticAriaLabel: findStaticAttributeValue(element, "aria-label"),
+    staticRole: findStaticAttributeValue(element, "role"),
+    staticTitle: findStaticAttributeValue(element, "title"),
+    staticTextContent: collectStaticTextContent(element.children)
   };
   return metadata;
 }
@@ -8647,6 +8730,7 @@ function extractMetadataAfterTransform(ast, componentName, elementMetadata, sema
   if (componentMetadata.size > 0) {
     elementMetadata.set(componentName, componentMetadata);
   }
+  return componentMetadata;
 }
 function createVuePluginWithTestIds(options) {
   const {
@@ -8661,11 +8745,13 @@ function createVuePluginWithTestIds(options) {
     excludedComponents,
     getViewsDirAbs,
     testIdAttribute,
+    accessibilityAudit,
     loggerRef,
     getSourceDirs,
     getWrapperSearchRoots,
     getProjectRoot
   } = options;
+  const lastAccessibilityWarningSignatureByComponent = /* @__PURE__ */ new Map();
   const getComponentNameFromPath = (filename) => {
     return resolveComponentNameFromPath({
       filename,
@@ -8738,13 +8824,37 @@ function createVuePluginWithTestIds(options) {
             )
           );
           return () => {
-            extractMetadataAfterTransform(
+            const componentMetadata = extractMetadataAfterTransform(
               node,
               componentName,
               elementMetadata,
               semanticNameMap,
               testIdAttribute
             );
+            if (!accessibilityAudit) {
+              return;
+            }
+            const dependencies = componentHierarchyMap.get(componentName);
+            if (!dependencies || componentMetadata.size === 0) {
+              return;
+            }
+            const manifest = buildPomManifest(
+              /* @__PURE__ */ new Map([[componentName, dependencies]]),
+              /* @__PURE__ */ new Map([[componentName, componentMetadata]])
+            );
+            const warnings = collectAccessibilityReviewWarnings(manifest);
+            const signature = warnings.join("\n");
+            if (!signature) {
+              lastAccessibilityWarningSignatureByComponent.delete(componentName);
+              return;
+            }
+            if (lastAccessibilityWarningSignatureByComponent.get(componentName) === signature) {
+              return;
+            }
+            lastAccessibilityWarningSignatureByComponent.set(componentName, signature);
+            for (const warning of warnings) {
+              loggerRef.current.warn(warning);
+            }
           };
         }
         let transform = perFileTransform.get(componentName);
@@ -9109,6 +9219,7 @@ function createVuePomGeneratorPlugins(options = {}) {
     nameCollisionBehavior: generationOptions?.nameCollisionBehavior,
     existingIdBehavior: resolvedInjectionOptions.existingIdBehavior,
     testIdAttribute,
+    accessibilityAudit: generationOptions?.accessibilityAudit,
     routerAwarePoms: typeof routerEntry === "string" && routerEntry.trim().length > 0 || routerType === "nuxt",
     routerEntry,
     routerType,
@@ -9202,6 +9313,7 @@ function createVuePomGeneratorPlugins(options = {}) {
     excludedComponents,
     getViewsDirAbs,
     testIdAttribute,
+    accessibilityAudit: resolvedGenerationOptions.accessibilityAudit,
     loggerRef,
     getSourceDirs,
     getWrapperSearchRoots: getWrapperSearchRootsAbs,