@govtechsg/oobee 0.10.36 → 0.10.42

package/src/utils.ts

@@ -7,7 +7,10 @@ import constants, {
   destinationPath,
   getIntermediateScreenshotsPath,
 } from './constants/constants.js';
-import { silentLogger } from './logs.js';
+import { consoleLogger, silentLogger } from './logs.js';
+import { getAxeConfiguration } from './crawlers/custom/getAxeConfiguration.js';
+import axe from 'axe-core';
+import { Rule, RuleMetadata } from 'axe-core';
 
 export const getVersion = () => {
   const loadJSON = filePath =>
@@ -178,18 +181,6 @@ export const cleanUp = async pathToDelete => {
   fs.removeSync(pathToDelete);
 };
 
-/* istanbul ignore next */
-// export const getFormattedTime = () =>
-//   new Date().toLocaleTimeString('en-GB', {
-//     year: 'numeric',
-//     month: 'short',
-//     day: 'numeric',
-//     hour12: true,
-//     hour: 'numeric',
-//     minute: '2-digit',
-//     timeZoneName: "longGeneric",
-//   });
-
 export const getWcagPassPercentage = (
   wcagViolations: string[],
   showEnableWcagAaa: boolean
@@ -228,6 +219,291 @@ export const getWcagPassPercentage = (
   };
 };
 
+export interface ScanPagesDetail {
+  oobeeAppVersion?: string;
+  pagesAffected: PageDetail[];
+  pagesNotAffected: PageDetail[];
+  scannedPagesCount: number;
+  pagesNotScanned: PageDetail[];
+  pagesNotScannedCount: number;
+}
+
+export interface PageDetail {
+  pageTitle: string;
+  url: string;
+  totalOccurrencesFailedIncludingNeedsReview: number;
+  totalOccurrencesFailedExcludingNeedsReview: number;
+  totalOccurrencesMustFix?: number;
+  totalOccurrencesGoodToFix?: number;
+  totalOccurrencesNeedsReview: number;
+  totalOccurrencesPassed: number;
+  occurrencesExclusiveToNeedsReview: boolean;
+  typesOfIssuesCount: number;
+  typesOfIssuesExcludingNeedsReviewCount: number;
+  categoriesPresent: IssueCategory[];
+  conformance?: string[]; // WCAG levels as flexible strings
+  typesOfIssues: IssueDetail[];
+}
+
+export type IssueCategory = "mustFix" | "goodToFix" | "needsReview" | "passed";
+
+export interface IssueDetail {
+  ruleId: string;
+  wcagConformance: string[];
+  occurrencesMustFix?: number;
+  occurrencesGoodToFix?: number;
+  occurrencesNeedsReview?: number;
+  occurrencesPassed: number;
+}
+
+export const getProgressPercentage = (
+  scanPagesDetail: ScanPagesDetail,
+  showEnableWcagAaa: boolean
+): {
+  averageProgressPercentageAA: string;
+  averageProgressPercentageAAandAAA: string;
+} => {
+  const pages = scanPagesDetail.pagesAffected || [];
+  
+  const progressPercentagesAA = pages.map((page: any) => {
+    const violations: string[] = page.conformance;
+    return getWcagPassPercentage(violations, showEnableWcagAaa).passPercentageAA;
+  });
+  
+  const progressPercentagesAAandAAA = pages.map((page: any) => {
+    const violations: string[] = page.conformance;
+    return getWcagPassPercentage(violations, showEnableWcagAaa).passPercentageAAandAAA;
+  });
+  
+  const totalAA = progressPercentagesAA.reduce((sum, p) => sum + parseFloat(p), 0);
+  const avgAA = progressPercentagesAA.length ? totalAA / progressPercentagesAA.length : 0;
+
+  const totalAAandAAA = progressPercentagesAAandAAA.reduce((sum, p) => sum + parseFloat(p), 0);
+  const avgAAandAAA = progressPercentagesAAandAAA.length ? totalAAandAAA / progressPercentagesAAandAAA.length : 0;
+  
+  return { 
+    averageProgressPercentageAA: avgAA.toFixed(2),
+    averageProgressPercentageAAandAAA: avgAAandAAA.toFixed(2),
+  };
+};
+
+export const getTotalRulesCount = async (
+  enableWcagAaa: boolean,
+  disableOobee: boolean
+): Promise<{
+  totalRulesMustFix: number;
+  totalRulesGoodToFix: number;
+  totalRulesMustFixAndGoodToFix: number;
+}> => {
+  const axeConfig = getAxeConfiguration({
+    enableWcagAaa,
+    gradingReadabilityFlag: '',
+    disableOobee,
+  });
+
+  // Get default rules from axe-core
+  const defaultRules = await axe.getRules();
+
+  // Merge custom rules with default rules, converting RuleMetadata to Rule
+  const mergedRules: Rule[] = defaultRules.map((defaultRule) => {
+    const customRule = axeConfig.rules.find((r) => r.id === defaultRule.ruleId);
+    if (customRule) {
+      // Merge properties from customRule into defaultRule (RuleMetadata) to create a Rule
+      return {
+        id: defaultRule.ruleId,
+        enabled: customRule.enabled,
+        selector: customRule.selector,
+        any: customRule.any,
+        tags: defaultRule.tags,
+        metadata: customRule.metadata, // Use custom metadata if it exists
+      };
+    } else {
+      // Convert defaultRule (RuleMetadata) to Rule
+      return {
+        id: defaultRule.ruleId,
+        enabled: true, // Default to true if not overridden
+        tags: defaultRule.tags,
+        // No metadata here, since defaultRule.metadata might not exist
+      };
+    }
+  });
+
+  // Add any custom rules that don't override the default rules
+  axeConfig.rules.forEach(customRule => {
+    if (!mergedRules.some(mergedRule => mergedRule.id === customRule.id)) {
+      // Ensure customRule is of type Rule
+      const rule: Rule = {
+        id: customRule.id,
+        enabled: customRule.enabled,
+        selector: customRule.selector,
+        any: customRule.any,
+        tags: customRule.tags,
+        metadata: customRule.metadata,
+        // Add other properties if needed
+      };
+      mergedRules.push(rule);
+    }
+  });
+
+  // Apply the merged configuration to axe-core
+  await axe.configure({ ...axeConfig, rules: mergedRules });
+
+  const rules = await axe.getRules();
+
+  // ... (rest of your logic)
+  let totalRulesMustFix = 0;
+  let totalRulesGoodToFix = 0;
+
+  const wcagRegex = /^wcag\d+a+$/;
+
+  // Use mergedRules instead of rules to check enabled property
+  mergedRules.forEach((rule) => {
+    if (!rule.enabled) {
+      return;
+    }
+
+    if (rule.id === 'frame-tested') return; // Ignore 'frame-tested' rule
+
+    const tags = rule.tags || [];
+
+    // Skip experimental and deprecated rules
+    if (tags.includes('experimental') || tags.includes('deprecated')) {
+      return;
+    }
+
+    let conformance = tags.filter(tag => tag.startsWith('wcag') || tag === 'best-practice');
+
+    // Ensure conformance level is sorted correctly
+    if (conformance.length > 0 && conformance[0] !== 'best-practice' && !wcagRegex.test(conformance[0])) {
+      conformance.sort((a, b) => {
+        if (wcagRegex.test(a) && !wcagRegex.test(b)) {
+          return -1;
+        }
+        if (!wcagRegex.test(a) && wcagRegex.test(b)) {
+          return 1;
+        }
+        return 0;
+      });
+    }
+
+    if (conformance.includes('best-practice')) {
+      // console.log(`${totalRulesMustFix} Good To Fix: ${rule.id}`);
+
+      totalRulesGoodToFix++; // Categorized as "Good to Fix"
+    } else {
+      // console.log(`${totalRulesMustFix} Must Fix: ${rule.id}`);
+
+      totalRulesMustFix++; // Otherwise, it's "Must Fix"
+    }
+  });
+
+  return {
+    totalRulesMustFix,
+    totalRulesGoodToFix,
+    totalRulesMustFixAndGoodToFix: totalRulesMustFix + totalRulesGoodToFix,
+  };
+};
+
+export const getIssuesPercentage = async (
+  scanPagesDetail: ScanPagesDetail,
+  enableWcagAaa: boolean,
+  disableOobee: boolean
+): Promise<{
+  avgTypesOfIssuesPercentageOfTotalRulesAtMustFix: string;
+  avgTypesOfIssuesPercentageOfTotalRulesAtGoodToFix: string;
+  avgTypesOfIssuesPercentageOfTotalRulesAtMustFixAndGoodToFix: string;
+  totalRulesMustFix: number;
+  totalRulesGoodToFix: number;
+  totalRulesMustFixAndGoodToFix: number;
+  avgTypesOfIssuesCountAtMustFix: string;
+  avgTypesOfIssuesCountAtGoodToFix: string;
+  avgTypesOfIssuesCountAtMustFixAndGoodToFix: string;
+  pagesAffectedPerRule: Record<string, number>;
+  pagesPercentageAffectedPerRule: Record<string, string>;
+}> => {
+  const pages = scanPagesDetail.pagesAffected || [];
+  const totalPages = pages.length;
+
+  const pagesAffectedPerRule: Record<string, number> = {};
+
+  pages.forEach((page) => {
+    page.typesOfIssues.forEach((issue) => {
+      if ((issue.occurrencesMustFix || issue.occurrencesGoodToFix) > 0) {
+        pagesAffectedPerRule[issue.ruleId] = (pagesAffectedPerRule[issue.ruleId] || 0) + 1;
+      }
+    });
+  });
+
+  const pagesPercentageAffectedPerRule: Record<string, string> = {};
+  for (const [ruleId, count] of Object.entries(pagesAffectedPerRule)) {
+    pagesPercentageAffectedPerRule[ruleId] = totalPages > 0 ? ((count / totalPages) * 100).toFixed(2) : "0.00";
+  }
+
+  const typesOfIssuesCountAtMustFix = pages.map((page) =>
+    page.typesOfIssues.filter((issue) => (issue.occurrencesMustFix || 0) > 0).length
+  );
+
+  const typesOfIssuesCountAtGoodToFix = pages.map((page) =>
+    page.typesOfIssues.filter((issue) => (issue.occurrencesGoodToFix || 0) > 0).length
+  );
+
+  const typesOfIssuesCountSumMustFixAndGoodToFix = pages.map(
+    (_, index) =>
+      (typesOfIssuesCountAtMustFix[index] || 0) +
+      (typesOfIssuesCountAtGoodToFix[index] || 0)
+  );
+
+  const { totalRulesMustFix, totalRulesGoodToFix, totalRulesMustFixAndGoodToFix } = await getTotalRulesCount(
+    enableWcagAaa,
+    disableOobee
+  );
+
+  const avgMustFixPerPage = totalPages > 0
+    ? typesOfIssuesCountAtMustFix.reduce((sum, count) => sum + count, 0) / totalPages
+    : 0;
+
+  const avgGoodToFixPerPage = totalPages > 0
+    ? typesOfIssuesCountAtGoodToFix.reduce((sum, count) => sum + count, 0) / totalPages
+    : 0;
+
+  const avgMustFixAndGoodToFixPerPage = totalPages > 0
+    ? typesOfIssuesCountSumMustFixAndGoodToFix.reduce((sum, count) => sum + count, 0) / totalPages
+    : 0;
+
+  const avgTypesOfIssuesPercentageOfTotalRulesAtMustFix =
+    totalRulesMustFix > 0
+      ? ((avgMustFixPerPage / totalRulesMustFix) * 100).toFixed(2)
+      : "0.00";
+
+  const avgTypesOfIssuesPercentageOfTotalRulesAtGoodToFix =
+    totalRulesGoodToFix > 0
+      ? ((avgGoodToFixPerPage / totalRulesGoodToFix) * 100).toFixed(2)
+      : "0.00";
+
+  const avgTypesOfIssuesPercentageOfTotalRulesAtMustFixAndGoodToFix =
+    totalRulesMustFixAndGoodToFix > 0
+      ? ((avgMustFixAndGoodToFixPerPage / totalRulesMustFixAndGoodToFix) * 100).toFixed(2)
+      : "0.00";
+
+  const avgTypesOfIssuesCountAtMustFix = avgMustFixPerPage.toFixed(2);
+  const avgTypesOfIssuesCountAtGoodToFix = avgGoodToFixPerPage.toFixed(2);
+  const avgTypesOfIssuesCountAtMustFixAndGoodToFix = avgMustFixAndGoodToFixPerPage.toFixed(2);
+
+  return {
+    avgTypesOfIssuesCountAtMustFix,
+    avgTypesOfIssuesCountAtGoodToFix,
+    avgTypesOfIssuesCountAtMustFixAndGoodToFix,
+    avgTypesOfIssuesPercentageOfTotalRulesAtMustFix,
+    avgTypesOfIssuesPercentageOfTotalRulesAtGoodToFix,
+    avgTypesOfIssuesPercentageOfTotalRulesAtMustFixAndGoodToFix,
+    totalRulesMustFix,
+    totalRulesGoodToFix,
+    totalRulesMustFixAndGoodToFix,
+    pagesAffectedPerRule,
+    pagesPercentageAffectedPerRule,
+  };
+};
+
 export const getFormattedTime = inputDate => {
   if (inputDate) {
     return inputDate.toLocaleTimeString('en-GB', {

package/src/xPathToCssCypress.ts

@@ -0,0 +1,178 @@
+export function xPathToCss(expr: string) {
+    const isValidXPath = expr =>
+        typeof expr !== 'undefined' &&
+        expr.replace(/[\s-_=]/g, '') !== '' &&
+        expr.length ===
+        expr.replace(
+            /[-_\w:.]+\(\)\s*=|=\s*[-_\w:.]+\(\)|\sor\s|\sand\s|\[(?:[^\/\]]+[\/\[]\/?.+)+\]|starts-with\(|\[.*last\(\)\s*[-\+<>=].+\]|number\(\)|not\(|count\(|text\(|first\(|normalize-space|[^\/]following-sibling|concat\(|descendant::|parent::|self::|child::|/gi,
+            '',
+        ).length;
+
+    const getValidationRegex = () => {
+        let regex =
+            '(?P<node>' +
+            '(' +
+            '^id\\(["\\\']?(?P<idvalue>%(value)s)["\\\']?\\)' + // special case! `id(idValue)`
+            '|' +
+            '(?P<nav>//?(?:following-sibling::)?)(?P<tag>%(tag)s)' + //  `//div`
+            '(\\[(' +
+            '(?P<matched>(?P<mattr>@?%(attribute)s=["\\\'](?P<mvalue>%(value)s))["\\\']' + // `[@id="well"]` supported and `[text()="yes"]` is not
+            '|' +
+            '(?P<contained>contains\\((?P<cattr>@?%(attribute)s,\\s*["\\\'](?P<cvalue>%(value)s)["\\\']\\))' + // `[contains(@id, "bleh")]` supported and `[contains(text(), "some")]` is not
+            ')\\])?' +
+            '(\\[\\s*(?P<nth>\\d+|last\\(\\s*\\))\\s*\\])?' +
+            ')' +
+            ')';
+
+        const subRegexes = {
+            tag: '([a-zA-Z][a-zA-Z0-9:-]*|\\*)',
+            attribute: '[.a-zA-Z_:][-\\w:.]*(\\(\\))?)',
+            value: '\\s*[\\w/:][-/\\w\\s,:;.]*',
+        };
+
+        Object.keys(subRegexes).forEach(key => {
+            regex = regex.replace(new RegExp(`%\\(${key}\\)s`, 'gi'), subRegexes[key]);
+        });
+
+        regex = regex.replace(
+            /\?P<node>|\?P<idvalue>|\?P<nav>|\?P<tag>|\?P<matched>|\?P<mattr>|\?P<mvalue>|\?P<contained>|\?P<cattr>|\?P<cvalue>|\?P<nth>/gi,
+            '',
+        );
+
+        return new RegExp(regex, 'gi');
+    };
+
+    const preParseXpath = expr =>
+        expr.replace(
+            /contains\s*\(\s*concat\(["']\s+["']\s*,\s*@class\s*,\s*["']\s+["']\)\s*,\s*["']\s+([a-zA-Z0-9-_]+)\s+["']\)/gi,
+            '@class="$1"',
+        );
+
+    function escapeCssIdSelectors(cssSelector) {
+        return cssSelector.replace(/#([^ >]+)/g, (match, id) => {
+            // Escape special characters in the id part
+            return `#${id.replace(/[!"#$%&'()*+,./:;<=>?@[\\\]^`{|}~]/g, '\\$&')}`;
+        });
+    }
+    if (!expr) {
+        throw new Error('Missing XPath expression');
+    }
+
+    expr = preParseXpath(expr);
+
+    if (!isValidXPath(expr)) {
+        console.error(`Invalid or unsupported XPath: ${expr}`);
+        // do not throw error so that this function proceeds to convert xpath that it does not support
+        // for example, //*[@id="google_ads_iframe_/4654/dweb/imu1/homepage/landingpage/na_0"]/html/body/div[1]/a
+        // becomes #google_ads_iframe_/4654/dweb/imu1/homepage/landingpage/na_0 > html > body > div:first-of-type > div > a
+        // which is invalid because the slashes in the id selector are not escaped
+        // throw new Error('Invalid or unsupported XPath: ' + expr);
+    }
+
+    const xPathArr = expr.split('|');
+    const prog = getValidationRegex();
+    const cssSelectors = [];
+    let xindex = 0;
+
+    while (xPathArr[xindex]) {
+        const css = [];
+        let position = 0;
+        let nodes;
+
+        while ((nodes = prog.exec(xPathArr[xindex]))) {
+            let attr;
+
+            if (!nodes && position === 0) {
+                throw new Error(`Invalid or unsupported XPath: ${expr}`);
+            }
+
+            const match = {
+                node: nodes[5],
+                idvalue: nodes[12] || nodes[3],
+                nav: nodes[4],
+                tag: nodes[5],
+                matched: nodes[7],
+                mattr: nodes[10] || nodes[14],
+                mvalue: nodes[12] || nodes[16],
+                contained: nodes[13],
+                cattr: nodes[14],
+                cvalue: nodes[16],
+                nth: nodes[18],
+            };
+
+            let nav = '';
+
+            if (position != 0 && match.nav) {
+                if (~match.nav.indexOf('following-sibling::')) {
+                    nav = ' + ';
+                } else {
+                    nav = match.nav == '//' ? ' ' : ' > ';
+                }
+            }
+
+            const tag = match.tag === '*' ? '' : match.tag || '';
+
+            if (match.contained) {
+                if (match.cattr.indexOf('@') === 0) {
+                    attr = `[${match.cattr.replace(/^@/, '')}*="${match.cvalue}"]`;
+                } else {
+                    throw new Error(`Invalid or unsupported XPath attribute: ${match.cattr}`);
+                }
+            } else if (match.matched) {
+                switch (match.mattr) {
+                    case '@id':
+                        attr = `#${match.mvalue.replace(/^\s+|\s+$/, '').replace(/\s/g, '#')}`;
+                        break;
+                    case '@class':
+                        attr = `.${match.mvalue.replace(/^\s+|\s+$/, '').replace(/\s/g, '.')}`;
+                        break;
+                    case 'text()':
+                    case '.':
+                        throw new Error(`Invalid or unsupported XPath attribute: ${match.mattr}`);
+                    default:
+                        if (match.mattr.indexOf('@') !== 0) {
+                            throw new Error(`Invalid or unsupported XPath attribute: ${match.mattr}`);
+                        }
+                        if (match.mvalue.indexOf(' ') !== -1) {
+                            match.mvalue = `\"${match.mvalue.replace(/^\s+|\s+$/, '')}\"`;
+                        }
+                        attr = `[${match.mattr.replace('@', '')}="${match.mvalue}"]`;
+                        break;
+                }
+            } else if (match.idvalue) {
+                attr = `#${match.idvalue.replace(/\s/, '#')}`;
+            } else {
+                attr = '';
+            }
+
+            let nth = '';
+
+            if (match.nth) {
+                if (match.nth.indexOf('last') === -1) {
+                    if (isNaN(parseInt(match.nth, 10))) {
+                        throw new Error(`Invalid or unsupported XPath attribute: ${match.nth}`);
+                    }
+                    nth = parseInt(match.nth, 10) !== 1 ? `:nth-of-type(${match.nth})` : ':first-of-type';
+                } else {
+                    nth = ':last-of-type';
+                }
+            }
+
+            css.push(nav + tag + attr + nth);
+            position++;
+        }
+
+        const result = css.join('');
+
+        if (result === '') {
+            throw new Error('Invalid or unsupported XPath');
+        }
+
+        cssSelectors.push(result);
+        xindex++;
+    }
+
+    // return cssSelectors.join(', ');
+    const originalResult = cssSelectors.join(', ');
+    return escapeCssIdSelectors(originalResult);
+}

package/src/crawlers/customAxeFunctions.ts

@@ -1,82 +0,0 @@
-import { Spec } from 'axe-core';
-
-// Custom Axe Functions for axe.config
-export const customAxeConfig: Spec = {
-  branding: {
-    application: 'oobee',
-  },
-  checks: [
-    {
-      id: 'oobee-confusing-alt-text',
-      metadata: {
-        impact: 'serious',
-        messages: {
-          pass: 'The image alt text is probably useful.',
-          fail: "The image alt text set as 'img', 'image', 'picture', 'photo', or 'graphic' is confusing or not useful.",
-        },
-      },
-    },
-    {
-      id: 'oobee-accessible-label',
-      metadata: {
-        impact: 'serious',
-        messages: {
-          pass: 'The clickable element has an accessible label.',
-          fail: 'The clickable element does not have an accessible label.',
-        },
-      },
-    },
-    {
-      id: 'oobee-grading-text-contents',
-      metadata: {
-        impact: 'moderate',
-        messages: {
-          pass: 'The text content is easy to understand.',
-          fail: 'The text content is potentially difficult to undersatnd.',
-        },
-      },
-    },
-  ],
-  rules: [
-    { id: 'target-size', enabled: true },
-    {
-      id: 'oobee-confusing-alt-text',
-      selector: 'img[alt]',
-      enabled: true,
-      any: ['oobee-confusing-alt-text'],
-      tags: ['wcag2a', 'wcag111'],
-      metadata: {
-        description: 'Ensures image alt text is clear and useful.',
-        help: 'Image alt text must not be vague or unhelpful.',
-        helpUrl: 'https://www.deque.com/blog/great-alt-text-introduction/',
-      },
-    },
-    {
-      id: 'oobee-accessible-label',
-      // selector: '*', // to be set with the checker function output xpaths converted to css selectors
-      enabled: true,
-      any: ['oobee-accessible-label'],
-      tags: ['wcag2a', 'wcag211', 'wcag412'],
-      metadata: {
-        description: 'Ensures clickable elements have an accessible label.',
-        help: 'Clickable elements must have accessible labels.',
-        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/',
-      },
-    },
-  ],
-};
-
-export default customAxeConfig;