[SITES-36639] Spacecat A11y Autofix suggestion grouping

src/accessibility/guidance-utils/mystique-data-processing.js

@@ -13,70 +13,87 @@
 import { isNonEmptyArray, isNonEmptyObject } from '@adobe/spacecat-shared-utils';
 import { Suggestion as SuggestionDataAccess } from '@adobe/spacecat-shared-data-access';
 import { issueTypesForMystique } from '../utils/constants.js';
+import { buildAggregationKey } from '../utils/aggregation-strategies.js';
 
 /**
  * Processes suggestions directly to create Mystique message data
  *
+ * Supports multiple aggregation strategies:
+ * - PER_ELEMENT: Each suggestion has one issue with one htmlWithIssues element
+ * - PER_ISSUE_TYPE_PER_PAGE: Each suggestion has one issue with multiple htmlWithIssues elements
+ * - PER_PAGE: Each suggestion has multiple issues with multiple htmlWithIssues elements
+ *
  * @param {Array} suggestions - Array of suggestion objects from the opportunity
  * @returns {Array} Array of message data objects ready for SQS sending
  */
 export function processSuggestionsForMystique(suggestions) {
-  if (!suggestions || !Array.isArray(suggestions)) {
+  if (!Array.isArray(suggestions) || suggestions.length === 0) {
     return [];
   }
 
-  // Group suggestions by url
-  const suggestionsByUrl = {};
-  for (const suggestion of suggestions) {
-    const suggestionData = suggestion.getData();
+  const SKIPPED_STATUSES = [
+    SuggestionDataAccess.STATUSES.FIXED,
+    SuggestionDataAccess.STATUSES.SKIPPED,
+  ];
+
+  // Helper: Extract issue items from a suggestion that need Mystique processing
+  const extractIssueItems = (suggestion) => {
+    const data = suggestion.getData();
     const suggestionId = suggestion.getId();
-    // skip sending to M suggestions that are fixed or skipped
-    if (![SuggestionDataAccess.STATUSES.FIXED, SuggestionDataAccess.STATUSES.SKIPPED]
-      .includes(suggestion.getStatus())
-      && suggestionData.issues
-      && isNonEmptyArray(suggestionData.issues)
-      && isNonEmptyArray(suggestionData.issues[0].htmlWithIssues)) {
-      // Starting with SITES-33832, a suggestion corresponds to a single granular issue,
-      // i.e. target selector and faulty HTML line
-      const singleIssue = suggestionData.issues[0];
-      const singleHtmlWithIssue = singleIssue.htmlWithIssues[0];
-      // skip sending to M suggestions that already have guidance
-      if (issueTypesForMystique.includes(singleIssue.type)
-      && !isNonEmptyObject(singleHtmlWithIssue.guidance)) {
-        const { url } = suggestionData;
-        if (!suggestionsByUrl[url]) {
-          suggestionsByUrl[url] = [];
-        }
-        suggestionsByUrl[url].push({ ...suggestionData, suggestionId });
-      }
+
+    if (!isNonEmptyArray(data.issues)) {
+      return [];
     }
-  }
 
-  const messageData = [];
-  for (const [url, suggestionsForUrl] of Object.entries(suggestionsByUrl)) {
-    const issuesList = [];
-    for (const suggestion of suggestionsForUrl) {
-      if (isNonEmptyArray(suggestion.issues)) {
-        // Starting with SITES-33832, a suggestion corresponds to a single granular issue,
-        // i.e. target selector and faulty HTML line
-        const singleIssue = suggestion.issues[0];
-        if (isNonEmptyArray(singleIssue.htmlWithIssues)) {
-          const singleHtmlWithIssue = singleIssue.htmlWithIssues[0];
-          issuesList.push({
-            issueName: singleIssue.type,
-            faultyLine: singleHtmlWithIssue.update_from || singleHtmlWithIssue.updateFrom || '',
-            targetSelector: singleHtmlWithIssue.target_selector || singleHtmlWithIssue.targetSelector || '',
-            issueDescription: singleIssue.description || '',
-            suggestionId: suggestion.suggestionId,
-          });
-        }
-      }
+    return data.issues
+      .filter((issue) => issueTypesForMystique.includes(issue.type))
+      .filter((issue) => isNonEmptyArray(issue.htmlWithIssues))
+      .flatMap((issue) => issue.htmlWithIssues
+        .filter((html) => !isNonEmptyObject(html.guidance))
+        .map((html) => {
+          // Build aggregation key based on granularity strategy for this issue type
+          const targetSelector = html.target_selector || html.targetSelector || '';
+          const aggregationKey = buildAggregationKey(
+            issue.type,
+            data.url,
+            targetSelector,
+            data.source,
+          );
+
+          return {
+            issueName: issue.type,
+            faultyLine: html.update_from || html.updateFrom || '',
+            targetSelector,
+            issueDescription: issue.description || '',
+            suggestionId,
+            url: data.url,
+            aggregationKey,
+          };
+        }));
+  };
+
+  // Process all suggestions and extract issue items
+  const allIssueItems = suggestions
+    .filter((suggestion) => !SKIPPED_STATUSES.includes(suggestion.getStatus()))
+    .flatMap(extractIssueItems);
+
+  // Group by aggregation key
+  const byAggregationKey = allIssueItems.reduce((acc, item) => {
+    const { aggregationKey, ...issueItem } = item;
+    if (!acc[aggregationKey]) {
+      acc[aggregationKey] = {
+        url: item.url,
+        issuesList: [],
+      };
     }
-    messageData.push({
-      url,
-      issuesList,
-    });
-  }
+    acc[aggregationKey].issuesList.push(issueItem);
+    return acc;
+  }, {});
 
-  return messageData;
+  // Convert to final format
+  return Object.entries(byAggregationKey).map(([aggregationKey, data]) => ({
+    url: data.url,
+    aggregationKey,
+    issuesList: data.issuesList,
+  }));
 }

src/accessibility/utils/aggregation-strategies.js

@@ -0,0 +1,209 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/**
+ * Accessibility suggestion aggregation strategies
+ *
+ * Defines how HTML elements with accessibility issues are grouped into database suggestions.
+ * Each granularity level has a function that builds an aggregation key from suggestion data.
+ */
+
+/**
+ * Granularity levels for suggestion aggregation
+ * @enum {string}
+ */
+export const Granularity = {
+  /** One suggestion per HTML element - url|type|selector (e.g., page1|color-contrast|div.header) */
+  INDIVIDUAL: 'INDIVIDUAL',
+
+  /**
+   * One suggestion per issue type per page - url|type (e.g., page1|color-contrast)
+   */
+  PER_PAGE_PER_COMPONENT: 'PER_PAGE_PER_COMPONENT',
+
+  /** One suggestion per page - url (e.g., page1) */
+  PER_PAGE: 'PER_PAGE',
+
+  /**
+   * One suggestion per component type across all pages - type|selector
+   */
+  PER_COMPONENT: 'PER_COMPONENT',
+
+  /** One suggestion per issue type globally - type (e.g., color-contrast) */
+  PER_TYPE: 'PER_TYPE',
+};
+
+/**
+ * Generic key builder that concatenates non-empty values with pipe separator
+ * @param {...string} parts - Variable number of key parts to concatenate
+ * @returns {string} Concatenated key
+ */
+function buildKey(...parts) {
+  return parts.filter((part) => part != null && part !== '').join('|');
+}
+
+/**
+ * Builds aggregation key for INDIVIDUAL granularity
+ * Key format: url|type|selector|source
+ */
+function buildIndividualKey({
+  url, issueType, targetSelector, source,
+}) {
+  return buildKey(url, issueType, targetSelector, source);
+}
+
+/**
+ * Builds aggregation key for PER_PAGE_PER_COMPONENT granularity
+ * Key format: url|type|source
+ */
+function buildPerPagePerComponentKey({ url, issueType, source }) {
+  return buildKey(url, issueType, source);
+}
+
+/**
+ * Builds aggregation key for PER_PAGE granularity
+ * Key format: url|source
+ */
+function buildPerPageKey({ url, source }) {
+  return buildKey(url, source);
+}
+
+/**
+ * Builds aggregation key for COMPONENT granularity
+ * Key format: type|selector
+ */
+function buildComponentKey({ issueType, targetSelector }) {
+  return buildKey(issueType, targetSelector);
+}
+
+/**
+ * Builds aggregation key for GLOBAL granularity
+ * Key format: type
+ */
+function buildGlobalKey({ issueType }) {
+  return buildKey(issueType);
+}
+
+/**
+ * Registry of key-building functions by granularity level
+ */
+export const GRANULARITY_KEY_BUILDERS = {
+  [Granularity.INDIVIDUAL]: buildIndividualKey,
+  [Granularity.PER_PAGE_PER_COMPONENT]: buildPerPagePerComponentKey,
+  [Granularity.PER_PAGE]: buildPerPageKey,
+  [Granularity.PER_COMPONENT]: buildComponentKey,
+  [Granularity.PER_TYPE]: buildGlobalKey,
+};
+
+/**
+ * Maps issue types to their aggregation granularity
+ * Based on the nature of each issue and how they should be grouped
+ */
+export const ISSUE_GRANULARITY_MAP = {
+  'color-contrast': Granularity.INDIVIDUAL,
+  list: Granularity.PER_COMPONENT,
+  'aria-roles': Granularity.PER_PAGE_PER_COMPONENT,
+  'image-alt': Granularity.PER_PAGE_PER_COMPONENT,
+  'link-in-text-block': Granularity.PER_PAGE_PER_COMPONENT,
+  'link-name': Granularity.PER_PAGE_PER_COMPONENT,
+  'target-size': Granularity.PER_PAGE_PER_COMPONENT,
+  listitem: Granularity.PER_COMPONENT,
+  label: Granularity.PER_PAGE_PER_COMPONENT,
+  'aria-prohibited-attr': Granularity.PER_TYPE,
+  'button-name': Granularity.PER_PAGE_PER_COMPONENT,
+  'frame-title': Granularity.PER_PAGE_PER_COMPONENT,
+  'aria-valid-attr-value': Granularity.PER_PAGE_PER_COMPONENT,
+  'aria-allowed-attr': Granularity.PER_TYPE,
+  'aria-hidden-focus': Granularity.PER_PAGE_PER_COMPONENT,
+  'nested-interactive': Granularity.PER_PAGE_PER_COMPONENT,
+  'html-has-lang': Granularity.PER_PAGE,
+  'meta-viewport': Granularity.PER_PAGE,
+  'aria-required-children': Granularity.PER_PAGE_PER_COMPONENT,
+  'aria-required-parent': Granularity.PER_PAGE_PER_COMPONENT,
+  'meta-refresh': Granularity.PER_PAGE,
+  'role-img-alt': Granularity.PER_PAGE_PER_COMPONENT,
+  'aria-input-field-name': Granularity.PER_PAGE_PER_COMPONENT,
+  'scrollable-region-focusable': Granularity.PER_PAGE_PER_COMPONENT,
+  'select-name': Granularity.PER_PAGE_PER_COMPONENT,
+};
+
+/**
+ * Gets the granularity level for a specific issue type
+ *
+ * @param {string} issueType - The issue type (e.g., "color-contrast")
+ * @returns {string} The granularity level (defaults to PER_PAGE_PER_COMPONENT)
+ */
+export function getGranularityForIssueType(issueType) {
+  return ISSUE_GRANULARITY_MAP[issueType] || Granularity.PER_PAGE_PER_COMPONENT;
+}
+
+/**
+ * Builds an aggregation key for grouping HTML elements during processing
+ *
+ * @param {string} issueType - The issue type
+ * @param {string} url - Page URL
+ * @param {string} targetSelector - CSS selector for the element
+ * @param {string} source - Optional source identifier
+ * @returns {string} The aggregation key based on the issue type's granularity
+ */
+export function buildAggregationKey(issueType, url, targetSelector, source) {
+  const granularity = getGranularityForIssueType(issueType);
+  const keyBuilder = GRANULARITY_KEY_BUILDERS[granularity];
+
+  if (!keyBuilder) {
+    // Fallback to INDIVIDUAL if builder not found
+    return buildIndividualKey({
+      url, issueType, targetSelector, source,
+    });
+  }
+
+  return keyBuilder({
+    url, issueType, targetSelector, source,
+  });
+}
+
+/**
+ * Builds a database-level key for matching suggestions across audit runs.
+ * Used by syncSuggestions to identify existing suggestions.
+ *
+ * This ALWAYS uses INDIVIDUAL granularity (url|type|selector|source) to ensure
+ * each HTML element gets its own suggestion in the database. This prevents
+ * incorrect merging of different HTML elements.
+ *
+ * IMPORTANT: This maintains backwards compatibility with the original buildKey logic
+ * by including a trailing pipe when selector is empty (url|type|).
+ *
+ * @param {Object} suggestionData - The suggestion data object
+ * @param {string} suggestionData.url - Page URL
+ * @param {Array} suggestionData.issues - Array of issues
+ * @param {string} suggestionData.source - Optional source
+ * @returns {string} The key for suggestion matching
+ */
+export function buildSuggestionKey(suggestionData) {
+  const { url, issues, source } = suggestionData;
+
+  if (!issues || issues.length === 0) {
+    return url;
+  }
+
+  const firstIssue = issues[0];
+  const issueType = firstIssue.type;
+  const targetSelector = firstIssue.htmlWithIssues?.[0]?.target_selector || '';
+
+  // Always build INDIVIDUAL-level key for database uniqueness
+  // Backwards compatible: url|type|selector|source or url|type| when selector is empty
+  let key = `${url}|${issueType}|${targetSelector}`;
+  if (source) {
+    key += `|${source}`;
+  }
+  return key;
+}