@govtechsg/oobee 0.10.87 → 0.10.88

package/src/crawlers/crawlLocalFile.ts

@@ -8,6 +8,7 @@ import constants, {
   UrlsCrawled,
   STATUS_CODE_METADATA,
   FileTypes,
+  RuleFlags,
 } from '../constants/constants.js';
 import { ViewportSettingsClass } from '../combine.js';
 import {
@@ -35,6 +36,7 @@ export const crawlLocalFile = async ({
   includeScreenshots,
   extraHTTPHeaders,
   scanDuration = 0,
+  ruleset = [],
   fromCrawlIntelligentSitemap = false,
   userUrlInputFromIntelligent = null,
   datasetFromIntelligent = null,
@@ -53,6 +55,7 @@ export const crawlLocalFile = async ({
   includeScreenshots: boolean;
   extraHTTPHeaders: Record<string, string>;
   scanDuration?: number;
+  ruleset?: RuleFlags[];
   fromCrawlIntelligentSitemap?: boolean;
   userUrlInputFromIntelligent?: string | null;
   datasetFromIntelligent?: Dataset | null;
@@ -178,7 +181,7 @@ export const crawlLocalFile = async ({
       return urlsCrawled;
     }
 
-    const results = await runAxeScript({ includeScreenshots, page, randomToken });
+    const results = await runAxeScript({ includeScreenshots, page, randomToken, ruleset });
 
     const actualUrl = page.url() || request.loadedUrl || url;
 

package/src/crawlers/custom/extractAndGradeText.ts

@@ -45,7 +45,7 @@ export async function extractAndGradeText(page: Page): Promise<string> {
 
     // Determine the return value
     const result =
-      readabilityScore === 0 || readabilityScore > 50 ? '' : readabilityScore.toString(); // Convert readabilityScore to string
+      readabilityScore <= 0 || readabilityScore > 50 ? '' : readabilityScore.toString();
 
     return result;
   } catch (error) {

package/src/crawlers/custom/getAxeConfiguration.ts

@@ -10,6 +10,12 @@ export function getAxeConfiguration({
   gradingReadabilityFlag?: string;
   disableOobee?: boolean;
 }) {
+  function getReadabilityInterpretation(score: string): string {
+    const num = parseFloat(score);
+    if (Number.isNaN(num)) return '';
+    if (num > 30) return 'It is targeted for junior college (JC) level comprehension and above.';
+    return 'It is targeted for university graduate level comprehension and above.';
+  }
   return {
     branding: {
       application: 'oobee',
@@ -39,7 +45,7 @@ export function getAxeConfiguration({
           return !node.dataset.flagged; // fail any element with a data-flagged attribute set to true
         },
       },
-      ...(enableWcagAaa
+      ...((enableWcagAaa && gradingReadabilityFlag !== '')
         ? [
           {
             id: 'oobee-grading-text-contents',
@@ -47,17 +53,11 @@ export function getAxeConfiguration({
               impact: 'moderate' as ImpactValue,
               messages: {
                 pass: 'The text content is easy to understand.',
-                fail: 'The text content is potentially difficult to understand.',
-                incomplete: `The text content is potentially difficult to read, with a Flesch-Kincaid Reading Ease score of ${gradingReadabilityFlag
-                  }.\nThe target passing score is above 50, indicating content readable by university students and lower grade levels.\nA higher score reflects better readability.`,
+                fail: `Text content is potentially difficult to read.\n  It scored ${gradingReadabilityFlag} out of 50 on the Flesch-Kincaid Readability Test.\n  ${getReadabilityInterpretation(gradingReadabilityFlag)}`,
+                incomplete: `Text content is potentially difficult to read.\n  It scored ${gradingReadabilityFlag} out of 50 on the Flesch-Kincaid Readability Test.\n  ${getReadabilityInterpretation(gradingReadabilityFlag)}`,
               },
             },
-            evaluate: (_node: HTMLElement) => {
-              if (gradingReadabilityFlag === '') {
-                return true; // Pass if no readability issues
-              }
-              // Fail if readability issues are detected
-            },
+            evaluate: (_node: HTMLElement) => false,
           },
         ]
         : []),
@@ -88,19 +88,21 @@ export function getAxeConfiguration({
           helpUrl: 'https://www.deque.com/blog/accessible-aria-buttons',
         },
       },
-      {
-        id: 'oobee-grading-text-contents',
-        selector: 'html',
-        enabled: true,
-        any: ['oobee-grading-text-contents'],
-        tags: ['wcag2aaa', 'wcag315'],
-        metadata: {
-          description:
-            'Text content should be easy to understand for individuals with education levels up to university graduates. If the text content is difficult to understand, provide supplemental content or a version that is easy to understand.',
-          help: 'Text content should be clear and plain to ensure that it is easily understood.',
-          helpUrl: 'https://www.wcag.com/uncategorized/3-1-5-reading-level/',
-        },
-      },
+      ...((enableWcagAaa && gradingReadabilityFlag !== '')
+        ? [{
+            id: 'oobee-grading-text-contents',
+            selector: 'html',
+            enabled: true,
+            any: ['oobee-grading-text-contents'],
+            tags: ['wcag2aaa', 'wcag315'],
+            metadata: {
+              description:
+                'Text content should be easy to understand for individuals with education levels up to university graduates. If the text content is difficult to understand, provide supplemental content or a version that is easy to understand.',
+              help: 'Text content should be clear and plain to ensure that it is easily understood.',
+              helpUrl: 'https://www.wcag.com/uncategorized/3-1-5-reading-level/',
+            },
+          }]
+        : []),
     ]
       .filter(rule => (disableOobee ? !rule.id.startsWith('oobee') : true))
       .concat(

package/src/crawlers/custom/gradeReadability.ts

@@ -20,7 +20,7 @@ export function gradeReadability(sentences: string[]): string {
 
     // Determine the return value
     const result =
-      readabilityScore === 0 || readabilityScore > 50 ? '' : readabilityScore.toString(); // Convert readabilityScore to string
+      readabilityScore <= 0 || readabilityScore > 50 ? '' : readabilityScore.toString();
 
     return result;
   } catch (error) {

package/src/npmIndex.ts

@@ -12,10 +12,10 @@ import {
   getPlaywrightLaunchOptions,
   submitForm,
 } from './constants/common.js';
-import { createCrawleeSubFolders, filterAxeResults } from './crawlers/commonCrawlerFunc.js';
+import { createCrawleeSubFolders, enrichViolationMessages, filterAxeResults } from './crawlers/commonCrawlerFunc.js';
 import { createAndUpdateResultsFolders, getVersion } from './utils.js';
 import generateArtifacts, { createBasicFormHTMLSnippet, sendWcagBreakdownToSentry } from './mergeAxeResults.js';
-import { takeScreenshotForHTMLElements } from './screenshotFunc/htmlScreenshotFunc.js';
+import { enrichColorContrastDOMContext, takeScreenshotForHTMLElements } from './screenshotFunc/htmlScreenshotFunc.js';
 import { consoleLogger, silentLogger } from './logs.js';
 import { alertMessageOptions } from './constants/cliFunctions.js';
 import { evaluateAltText } from './crawlers/custom/evaluateAltText.js';
@@ -86,6 +86,13 @@ const getOobeeFunctionsScript = (disableOobee: boolean, enableWcagAaa: boolean)
       window.xPathToCss = ${xPathToCss.toString()};
       window.extractText = ${extractText.toString()};
       
+      function getReadabilityInterpretation(score) {
+        const num = parseFloat(score);
+        if (Number.isNaN(num)) return '';
+        if (num > 30) return 'It is targeted for junior college (JC) level comprehension and above.';
+        return 'It is targeted for university graduate level comprehension and above.';
+      }
+
       function getAxeConfiguration({
         enableWcagAaa = false,
         gradingReadabilityFlag = '',
@@ -120,7 +127,7 @@ const getOobeeFunctionsScript = (disableOobee: boolean, enableWcagAaa: boolean)
                 return !node.dataset.flagged; // fail any element with a data-flagged attribute set to true
               },
             },
-            ...((enableWcagAaa && !disableOobee)
+            ...((enableWcagAaa && !disableOobee && gradingReadabilityFlag !== '')
               ? [
                   {
                     id: 'oobee-grading-text-contents',
@@ -128,16 +135,11 @@ const getOobeeFunctionsScript = (disableOobee: boolean, enableWcagAaa: boolean)
                       impact: 'moderate',
                       messages: {
                         pass: 'The text content is easy to understand.',
-                        fail: 'The text content is potentially difficult to understand.',
-                        incomplete: \`The text content is potentially difficult to read, with a Flesch-Kincaid Reading Ease score of \${gradingReadabilityFlag}.\nThe target passing score is above 50, indicating content readable by university students and lower grade levels.\nA higher score reflects better readability.\`,
+                        fail: \`Text content is potentially difficult to read.\n  It scored \${gradingReadabilityFlag} out of 50 on the Flesch-Kincaid Readability Test.\n  \${getReadabilityInterpretation(gradingReadabilityFlag)}\`,
+                        incomplete: \`Text content is potentially difficult to read.\n  It scored \${gradingReadabilityFlag} out of 50 on the Flesch-Kincaid Readability Test.\n  \${getReadabilityInterpretation(gradingReadabilityFlag)}\`,
                       },
                     },
-                    evaluate: (_node) => {
-                      if (gradingReadabilityFlag === '') {
-                        return true; // Pass if no readability issues
-                      }
-                      // Fail if readability issues are detected
-                    },
+                    evaluate: (_node) => false,
                   },
                 ]
               : []),
@@ -168,7 +170,7 @@ const getOobeeFunctionsScript = (disableOobee: boolean, enableWcagAaa: boolean)
                 helpUrl: 'https://www.deque.com/blog/accessible-aria-buttons',
               },
             },
-            ...((enableWcagAaa && !disableOobee)
+            ...((enableWcagAaa && !disableOobee && gradingReadabilityFlag !== '')
               ? [
                   {
                     id: 'oobee-grading-text-contents',
@@ -864,6 +866,9 @@ export const scanPage = async (
         return window.runA11yScan();
       });
 
+      await enrichViolationMessages(scanResult.axeScanResults, page);
+      await enrichColorContrastDOMContext(scanResult.axeScanResults.violations, page);
+
       scanData.push({
         axeScanResults: scanResult.axeScanResults,
         pageUrl: page.url(),

package/src/screenshotFunc/htmlScreenshotFunc.ts

@@ -5,10 +5,89 @@ import path from 'path';
 // import { silentLogger } from '../logs.js';
 import { Result } from 'axe-core';
 import { Page } from 'playwright';
-import { NodeResultWithScreenshot, ResultWithScreenshot } from '../crawlers/commonCrawlerFunc.js';
+import {
+  ContrastDOMContext,
+  NodeResultWithScreenshot,
+  ResultWithScreenshot,
+} from '../crawlers/commonCrawlerFunc.js';
 
 const screenshotMap: Record<string, string> = {}; // Map of screenshot hashkey to its buffer value and screenshot path
 
+export const enrichColorContrastDOMContext = async (
+  violations: Result[],
+  page: Page,
+): Promise<void> => {
+  for (const violation of violations) {
+    if (violation.id !== 'color-contrast' && violation.id !== 'color-contrast-enhanced') continue;
+
+    for (const node of violation.nodes) {
+      const { target } = node;
+      const selector = target.length === 1 && typeof target[0] === 'string' ? target[0] : null;
+      if (!selector) continue;
+
+      try {
+        const domContext = await page
+          .evaluate((sel: string): ContrastDOMContext | null => {
+            const el = document.querySelector(sel);
+            if (!el) return null;
+
+            const style = window.getComputedStyle(el);
+            const bgImage = style.backgroundImage;
+            const hasGradient = bgImage !== 'none' && bgImage.includes('gradient');
+            const hasBackgroundImage = bgImage !== 'none' && !hasGradient;
+
+            let hasReducedOpacity = parseFloat(style.opacity) < 1;
+            let ancestorHasGradient = false;
+            let ancestorHasBackgroundImage = false;
+
+            let ancestor = el.parentElement;
+            while (ancestor && ancestor.tagName !== 'HTML') {
+              const anStyle = window.getComputedStyle(ancestor);
+              if (!hasReducedOpacity && parseFloat(anStyle.opacity) < 1) {
+                hasReducedOpacity = true;
+              }
+              const anBgImg = anStyle.backgroundImage;
+              if (anBgImg !== 'none') {
+                if (!ancestorHasGradient && anBgImg.includes('gradient')) {
+                  ancestorHasGradient = true;
+                } else if (!ancestorHasBackgroundImage) {
+                  ancestorHasBackgroundImage = true;
+                }
+              }
+              ancestor = ancestor.parentElement;
+            }
+
+            const mixBlendMode = style.mixBlendMode !== 'normal' ? style.mixBlendMode : null;
+            const backdropFilter =
+              style.backdropFilter && style.backdropFilter !== 'none'
+                ? style.backdropFilter
+                : null;
+            const filter = style.filter && style.filter !== 'none' ? style.filter : null;
+
+            return {
+              backgroundImage: bgImage !== 'none' ? bgImage : '',
+              hasGradient,
+              hasBackgroundImage,
+              ancestorHasGradient,
+              ancestorHasBackgroundImage,
+              hasReducedOpacity,
+              mixBlendMode,
+              backdropFilter,
+              filter,
+            };
+          }, selector)
+          .catch(() => null);
+
+        if (domContext) {
+          (node as NodeResultWithScreenshot).contrastDOMContext = domContext;
+        }
+      } catch {
+        // Non-critical; proceed without DOM context
+      }
+    }
+  }
+};
+
 export const takeScreenshotForHTMLElements = async (
   violations: Result[],
   page: Page,
@@ -67,6 +146,7 @@ export const takeScreenshotForHTMLElements = async (
         } catch (e) {
           // consoleLogger.info(`Unable to take element screenshot at ${selector}`);
         }
+
       }
       newViolationNodes.push(nodeWithScreenshotPath);
     }

package/src/static/ejs/partials/scripts/ruleModal/itemCardRenderer.ejs

@@ -239,14 +239,17 @@
           ${item.xpath ? createXpathSection(item.xpath) : ''}
           ${createElementSection(item)}
           ${
-            item.displayNeedsReview
-              ? `<div class="d-flex justify-content-between g-one">
+            (() => {
+              const showDetails = item.displayNeedsReview || ['color-contrast', 'color-contrast-enhanced', 'oobee-grading-text-contents', 'target-size', 'valid-lang'].includes(aiConfig.ruleInCategory.rule);
+              return showDetails && item.message
+                ? `<div class="d-flex justify-content-between g-one">
             <div class="fw-semibold page-item-card-section-title">Details</div>
             <div class="page-item-card-section-content">
-              ${generateItemMessageElement(item.displayNeedsReview, item.message)}
+              ${generateItemMessageElement(item.displayNeedsReview || true, item.message)}
             </div>
           </div>`
-              : ''
+                : '';
+            })()
           }
           ${isPurpleAiRule ? createAiSuggestionSection(item, oobeeAiQueryLabel, aiConfig) : ''}
           ${showGenAiUI ? createGenAiSuggestFixSection(item, aiConfig) : ''}

package/src/static/ejs/partials/scripts/ruleModal/pageAccordionBuilder.ejs

@@ -393,14 +393,17 @@
         </div>
 
           ${
-            item.displayNeedsReview
-              ? `<div class="d-flex justify-content-between g-one modal-view">
+            (() => {
+              const showDetails = item.displayNeedsReview || ['color-contrast', 'color-contrast-enhanced', 'oobee-grading-text-contents', 'target-size', 'valid-lang'].includes(aiConfig.ruleInCategory.rule);
+              return showDetails && item.message
+                ? `<div class="d-flex justify-content-between g-one modal-view">
             <div class="fw-semibold page-item-card-section-title">Details</div>
             <div class="page-item-card-section-content">
-              ${generateItemMessageElement(item.displayNeedsReview, item.message)}
+              ${generateItemMessageElement(item.displayNeedsReview || true, item.message)}
             </div>
           </div>`
-              : ''
+                : '';
+            })()
           }
           ${isPurpleAiRule ? createAiSuggestionSection(item, oobeeAiQueryLabel, aiConfig) : ''}
         </div>

package/src/static/ejs/partials/scripts/ruleModal/utilities.ejs

@@ -53,7 +53,8 @@
       if (htmlEscapedMessageArray.length === 1) {
         return `<p class="mb-0">${htmlEscapedMessageArray[0]}</p>`;
       } else {
-        return `<ul>${htmlEscapedMessageArray.map(m => `<li>${m}</li>`).join('')}</ul>`;
+        const [first, ...rest] = htmlEscapedMessageArray;
+        return `<p class="mb-0">${first}</p><ul>${rest.map(m => `<li>${m}</li>`).join('')}</ul>`;
       }
     } else {
       let i = 0;