@govtechsg/oobee 0.10.87 → 0.10.88

package/dist/npmIndex.js

@@ -6,10 +6,10 @@ import { fileURLToPath } from 'url';
 import { EnqueueStrategy } from 'crawlee';
 import constants, { BrowserTypes, RuleFlags, ScannerTypes, a11yRuleShortDescriptionMap, a11yRuleLongDescriptionMap, a11yRuleStepByStepGuide } from './constants/constants.js';
 import { deleteClonedProfiles, getBrowserToRun, 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 } from './logs.js';
 import { alertMessageOptions } from './constants/cliFunctions.js';
 import { evaluateAltText } from './crawlers/custom/evaluateAltText.js';
@@ -50,6 +50,13 @@ const getOobeeFunctionsScript = (disableOobee, enableWcagAaa) => {
       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 = '',
@@ -84,7 +91,7 @@ const getOobeeFunctionsScript = (disableOobee, enableWcagAaa) => {
                 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',
@@ -92,16 +99,11 @@ const getOobeeFunctionsScript = (disableOobee, enableWcagAaa) => {
                       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,
                   },
                 ]
               : []),
@@ -132,7 +134,7 @@ const getOobeeFunctionsScript = (disableOobee, enableWcagAaa) => {
                 helpUrl: 'https://www.deque.com/blog/accessible-aria-buttons',
               },
             },
-            ...((enableWcagAaa && !disableOobee)
+            ...((enableWcagAaa && !disableOobee && gradingReadabilityFlag !== '')
               ? [
                   {
                     id: 'oobee-grading-text-contents',
@@ -629,6 +631,8 @@ export const scanPage = async (pages, config) => {
             const scanResult = await page.evaluate(async () => {
                 return window.runA11yScan();
             });
+            await enrichViolationMessages(scanResult.axeScanResults, page);
+            await enrichColorContrastDOMContext(scanResult.axeScanResults.violations, page);
             scanData.push({
                 axeScanResults: scanResult.axeScanResults,
                 pageUrl: page.url(),

package/dist/screenshotFunc/htmlScreenshotFunc.js

@@ -3,6 +3,73 @@ import { createHash } from 'crypto';
 import fs from 'fs';
 import path from 'path';
 const screenshotMap = {}; // Map of screenshot hashkey to its buffer value and screenshot path
+export const enrichColorContrastDOMContext = async (violations, page) => {
+    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) => {
+                    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.contrastDOMContext = domContext;
+                }
+            }
+            catch {
+                // Non-critical; proceed without DOM context
+            }
+        }
+    }
+};
 export const takeScreenshotForHTMLElements = async (violations, page, randomToken, locatorTimeout = 2000, maxScreenshots = 100) => {
     const newViolations = [];
     let screenshotCount = 0;

package/dist/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/dist/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/dist/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;

package/examples/oobee-test-details-runner.js

@@ -0,0 +1,214 @@
+/**
+ * Details Output Demo
+ *
+ * Runs scanPage against intentionally non-compliant test pages to capture the
+ * enriched Details messages for: color-contrast, color-contrast-enhanced,
+ * target-size, valid-lang, and oobee-grading-text-contents.
+ *
+ * Usage: node examples/details-runner.js
+ */
+import { chromium } from 'playwright';
+import { scanPage } from '../dist/npmIndex.js';
+import { gradeReadability } from '../dist/crawlers/custom/gradeReadability.js';
+
+// --- Test HTML pages ---
+
+const colorContrastHTML = `
+<!DOCTYPE html>
+<html lang="en">
+<head><title>Color Contrast Test</title></head>
+<body style="background-color: #ffffff;">
+  <h1>Color Contrast Violations</h1>
+  <p style="color: #999999; font-size: 14px;">This light gray text on white background fails AA contrast</p>
+  <p style="color: #aaaaaa; font-size: 14px; background-color: #f0f0f0;">Very light gray on light gray</p>
+  <button style="background-color: #55aa99; color: #e8ffe8; font-size: 12px;">Low contrast button</button>
+</body>
+</html>
+`;
+
+const colorContrastEnhancedHTML = `
+<!DOCTYPE html>
+<html lang="en">
+<head><title>Color Contrast Enhanced Test</title></head>
+<body style="background-color: #ffffff;">
+  <h1>Color Contrast Enhanced AAA Violations</h1>
+  <p style="color: #757575; font-size: 14px;">This text passes AA but fails AAA needs 7 to 1</p>
+  <p style="color: #6b6b6b; font-size: 12px;">Small text needs 7 to 1 for AAA</p>
+</body>
+</html>
+`;
+
+const targetSizeHTML = `
+<!DOCTYPE html>
+<html lang="en">
+<head><title>Target Size Test</title>
+<style>
+body { font-family: sans-serif; padding: 40px; }
+.icon-link {
+  display: inline-block;
+  width: 16px;
+  height: 16px;
+  font-size: 10px;
+  line-height: 16px;
+  text-align: center;
+  text-decoration: none;
+  color: #333;
+  overflow: hidden;
+}
+</style>
+</head>
+<body>
+<main>
+<h1>Icon-sized interactive targets</h1>
+<a href="/a" class="icon-link" style="width: 16px; height: 16px;">A</a>
+<a href="/b" class="icon-link" style="width: 16px; height: 16px;">B</a>
+<a href="/c" class="icon-link" style="width: 16px; height: 16px;">C</a>
+</main>
+</body>
+</html>
+`;
+
+const validLangHTML = `
+<!DOCTYPE html>
+<html lang="x-sindarin">
+<head><title>Valid Lang Test</title></head>
+<body>
+  <main>
+  <h1>Valid Lang Violation</h1>
+  <p>This page uses a private-use language subtag that is not valid according to BCP 47.</p>
+  <div lang="x-klingon">This section also has an invalid private-use lang tag with some sample text content for context.</div>
+  </main>
+</body>
+</html>
+`;
+
+const readabilityHTML = `
+<!DOCTYPE html>
+<html lang="en">
+<head><title>Readability Test</title></head>
+<body>
+  <main>
+  <h1>Building Safety Standards</h1>
+  <p>The committee reviewed the proposed changes to the building safety standards last Thursday. Members noted that the current regulations do not address modern construction materials adequately. Several technical amendments were suggested to improve clarity for contractors and inspectors. The revised standards will require additional testing for fire resistance in commercial properties. Public consultation on these proposed changes will remain open until the end of next quarter. Building owners should review the draft guidelines to understand potential compliance requirements.</p>
+  </main>
+</body>
+</html>
+`;
+
+// --- Helpers ---
+
+function extractMessages(result, ruleId) {
+  const messages = [];
+  for (const category of ['mustFix', 'goodToFix', 'needsReview']) {
+    const rules = result?.[category]?.rules;
+    if (rules && rules[ruleId]) {
+      const rule = rules[ruleId];
+      messages.push({
+        category,
+        rule: rule.rule || ruleId,
+        description: rule.description,
+        totalItems: rule.totalItems,
+        items: rule.items?.map(item => ({
+          html: item.html || item.element,
+          message: item.message,
+        })),
+      });
+    }
+  }
+  return messages;
+}
+
+// --- Main ---
+
+(async () => {
+  console.log("Launching browser...");
+  const browser = await chromium.launch({ headless: true });
+  const output = {};
+
+  // 1. Color Contrast (AA)
+  console.log("Scanning: color-contrast...");
+  try {
+    const page = await browser.newPage();
+    await page.setContent(colorContrastHTML);
+    const result = await scanPage(page, {
+      name: "Test", email: "test@test.com", pageTitle: "Color Contrast Test",
+    });
+    output['color-contrast'] = extractMessages(result, 'color-contrast');
+    await page.close();
+  } catch (e) { console.error("color-contrast error:", e.message); }
+
+  // 2. Color Contrast Enhanced (AAA)
+  console.log("Scanning: color-contrast-enhanced...");
+  try {
+    const page = await browser.newPage();
+    await page.setContent(colorContrastEnhancedHTML);
+    const result = await scanPage(page, {
+      name: "Test", email: "test@test.com", pageTitle: "Color Contrast Enhanced Test",
+      ruleset: ['default', 'enable-wcag-aaa'],
+    });
+    output['color-contrast-enhanced'] = extractMessages(result, 'color-contrast-enhanced');
+    await page.close();
+  } catch (e) { console.error("color-contrast-enhanced error:", e.message); }
+
+  // 3. Target Size
+  console.log("Scanning: target-size...");
+  try {
+    const page = await browser.newPage();
+    await page.setContent(targetSizeHTML);
+    const result = await scanPage(page, {
+      name: "Test", email: "test@test.com", pageTitle: "Target Size Test",
+    });
+    output['target-size'] = extractMessages(result, 'target-size');
+    await page.close();
+  } catch (e) { console.error("target-size error:", e.message); }
+
+  // 4. Valid Lang
+  console.log("Scanning: valid-lang...");
+  try {
+    const page = await browser.newPage();
+    await page.setContent(validLangHTML);
+    const result = await scanPage(page, {
+      name: "Test", email: "test@test.com", pageTitle: "Valid Lang Test",
+    });
+    output['valid-lang'] = extractMessages(result, 'valid-lang');
+    await page.close();
+  } catch (e) { console.error("valid-lang error:", e.message); }
+
+  // 5. Readability (oobee-grading-text-contents)
+  console.log("Scanning: oobee-grading-text-contents...");
+  try {
+    const page = await browser.newPage();
+    await page.setContent(readabilityHTML);
+
+    // Simulate what the crawler does: extract text, grade readability
+    const textContent = readabilityHTML.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+    const sentences = textContent.split(/(?<=[.!?])\s+/).filter(s => s.trim().length > 0);
+    const flag = gradeReadability(sentences);
+    console.log(`  Readability flag: "${flag}"`);
+
+    if (flag) {
+      const score = parseFloat(flag);
+      let interpretation = '';
+      if (score > 30) interpretation = 'It is targeted for junior college (JC) level comprehension and above.';
+      else interpretation = 'It is targeted for university graduate level comprehension and above.';
+
+      output['oobee-grading-text-contents'] = [{
+        category: 'needsReview',
+        rule: 'oobee-grading-text-contents',
+        description: 'Page content must use clear, plain language',
+        items: [{
+          html: '<html lang="en">...</html>',
+          message: `Text content is potentially difficult to read. It scored ${flag} out of 50 on the Flesch-Kincaid Readability Test. ${interpretation}`,
+        }],
+      }];
+    } else {
+      console.log("  Score filtered out (<=0 or >50). No violation triggered.");
+    }
+    await page.close();
+  } catch (e) { console.error("readability error:", e.message); }
+
+  await browser.close();
+
+  // Print results
+  console.log("\n" + JSON.stringify(output, null, 2));
+})();

package/examples/test-violations.html

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<title>Combined Accessibility Test</title>
+<style>
+body { font-family: sans-serif; padding: 40px; }
+.icon-link {
+  display: inline-block;
+  width: 16px;
+  height: 16px;
+  font-size: 10px;
+  line-height: 16px;
+  text-align: center;
+  text-decoration: none;
+  color: #333;
+  overflow: hidden;
+}
+</style>
+</head>
+<body>
+<main>
+<h1>Accessibility Violations Test Page</h1>
+
+<h2>Color Contrast</h2>
+<p style="color: #999999; font-size: 14px;">This light gray text on white background fails AA contrast</p>
+<p style="color: #aaaaaa; font-size: 14px; background-color: #f0f0f0;">Very light gray on light gray</p>
+<button style="background-color: #55aa99; color: #e8ffe8; font-size: 12px;">Low contrast button</button>
+
+<h2>Target Size</h2>
+<a href="/a" class="icon-link" style="width: 16px; height: 16px;">A</a>
+<a href="/b" class="icon-link" style="width: 16px; height: 16px;">B</a>
+<a href="/c" class="icon-link" style="width: 16px; height: 16px;">C</a>
+
+<h2>Valid Lang</h2>
+<div lang="x-klingon">This section has an invalid private-use lang tag with some sample text content for context.</div>
+
+<h2>Readability</h2>
+<p>The committee reviewed the proposed changes to the building safety standards last Thursday. Members noted that the current regulations do not address modern construction materials adequately. Several technical amendments were suggested to improve clarity for contractors and inspectors. The revised standards will require additional testing for fire resistance in commercial properties. Public consultation on these proposed changes will remain open until the end of next quarter. Building owners should review the draft guidelines to understand potential compliance requirements.</p>
+
+</main>
+</body>
+</html>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@govtechsg/oobee",
   "main": "dist/npmIndex.js",
-  "version": "0.10.87",
+  "version": "0.10.88",
   "type": "module",
   "author": "Government Technology Agency <info@tech.gov.sg>",
   "bin": {

package/src/combine.ts

@@ -184,6 +184,7 @@ const combineRun = async (details: Data, deviceToScan: string) => {
         includeScreenshots,
         extraHTTPHeaders,
         scanDuration,
+        ruleset,
       });
       if (localFileResult) {
         if ('urlsCrawled' in localFileResult) {