@govtechsg/oobee 0.10.20

package/src/constants/errorMeta.json

@@ -0,0 +1,319 @@
+{
+    "WCAG2.2": {
+        "1.3.1": {
+            "1": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Repeated characters should be avoided to represent lines or graphics, as the characters are read out one by one by reader software."
+            },
+            "2": {
+                "STATUS": "ignore",
+                "CATEGORY": "structure",
+                "RATIONALE": "Repeated white space should be avoided to align text. Repeated white space at the end of a line usually doesn't have any function."
+            },
+            "3": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Underlined text is easily confused with a hyperlink. WCAG doesn't prohibit underlining but it's bad practice."
+            },
+            "4": {
+                "STATUS": "ignore",
+                "CATEGORY": "structure",
+                "RATIONALE": "Semantics should not just be expressed by formatting text."
+            }
+        },
+        "1.3.4": {
+            "1": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Pages with different orientation are allowed as long as this is essential for the content."
+            }
+        },
+        "1.4.3": {
+            "1": {
+                "STATUS": "error",
+                "CATEGORY": "structure",
+                "RATIONALE": "Insufficient contrast makes the text difficult to read for people with visual impairments or colour blind people."
+            }
+        },
+        "1.4.4": {
+            "1": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Text not be too small, and must be readable when zoomed to 200%."
+            }
+        },
+        "1.4.8": {
+            "1": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "The use of fonts that are difficult to read should be avoided (unless it was the intention to make the text difficult to read). Reader software will read the text out correctly, but people with poor vision, ADHD or people in the autism spectrum may have problems reading the text."
+            }
+        },
+        "1.4.10": {
+            "1": {
+                "STATUS": "warning",
+                "CATEGORY": "code",
+                "RATIONALE": "A figure which is on one page should have a bounding box."
+            }
+        },
+        "2.4.9": {
+            "1": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Links should either have an alternative text or should be associated with text that explains the underlying link. Writing out URLS without alternative text should be avoided."
+            }
+        },
+        "4.1.1": {
+            "1": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Merged cells in table bodies should be avoided as much as possible as this makes the table more difficult to read out."
+            },
+            "2": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Merged cells in table heads should be avoided as much as possible as this makes the table more difficult to read out."
+            },
+            "3": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Merged cells in table heads should be avoided as much as possible as this makes the table more difficult to read out."
+            },
+            "4": {
+                "STATUS": "critical",
+                "CATEGORY": "code",
+                "RATIONALE": "A document must be tagged in order to be accessible."
+            }
+        },
+        "4.1.2": {
+            "1": {
+                "STATUS": "ignore",
+                "CATEGORY": "structure",
+                "RATIONALE": "If different lines have different formats they shouldn't be marked as a single paragraph."
+            },
+            "2": {
+                "STATUS": "ignore",
+                "CATEGORY": "code",
+                "RATIONALE": "If different lines of text have different formats they shouldn't be part of the same span."
+            },
+            "3": {
+                "STATUS": "ignore",
+                "CATEGORY": "structure",
+                "RATIONALE": "Tables should not be used to format text. However, WCAG does allow for tables to be used this way so we'll ignore this warning for the moment."
+            },
+            "4": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "If something that is not intended as a heading is tagged as a heading, this can confuse reader software for people with visual impairments. It will appear in the contents list as a heading, for example."
+            },
+            "5": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "If something that is not intended as a heading is tagged as a heading, this can confuse reader software for people with visual impairments. It will appear in the contents list as a heading, for example."
+            },
+            "6": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Text that is intended as a table row must be tagged as a table element. Otherwise reader software for people with visual impairments will not recognise it as a table and will fail to read it out correctly."
+            },
+            "7": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Text that is intended as a table head must be tagged as a table element. Otherwise reader software for people with visual impairments will not recognise it as a table and will fail to read it out correctly."
+            },
+            "8": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Text that is intended as a table cell must be tagged as a table element. Otherwise reader software for people with visual impairments will not recognise it as a table and will fail to read it out correctly."
+            },
+            "9": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Text that is intended as a part of a table must be tagged as a part of a table. Otherwise reader software for people with visual impairments will not recognise it as a table and will fail to read it out correctly."
+            },
+            "10": {
+                "STATUS": "ignore",
+                "CATEGORY": "structure",
+                "RATIONALE": "Text that is intended as a heading must be tagged as a heading. Otherwise reader software for people with visual impairments will not recognise the structure of the document and may have trouble reading it out in the correct order."
+            },
+            "11": {
+                "STATUS": "ignore",
+                "CATEGORY": "structure",
+                "RATIONALE": "If a span was not intended as a paragraph break, then it should not be tagged as such. Otherwise reader software for people with visual impairments will take this as a new paragraph and read it out as such."
+            },
+            "12": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Text that is intended as a paragraph must be tagged as a paragraph. Otherwise reader software for people with visual impairments will not recognise the text as a paragraph and may become confused about the reading order if the document."
+            },
+            "13": {
+                "STATUS": "ignore",
+                "CATEGORY": "structure",
+                "RATIONALE": "Text that is intended as a heading must be tagged as a heading. Otherwise reader software for people with visual impairments will not recognise the text as a heading and may become confused about the reading order if the document."
+            },
+            "14": {
+                "STATUS": "ignore",
+                "CATEGORY": "structure",
+                "RATIONALE": "Text that is intended as a paragraph must be tagged as a paragraph. Otherwise reader software for people with visual impairments will not recognise the text as a paragraph and may become confused about the reading order if the document."
+            },
+            "15": {
+                "STATUS": "ignore",
+                "CATEGORY": "structure",
+                "RATIONALE": "Text that is intended as a paragraph must be tagged as a paragraph. Otherwise reader software for people with visual impairments will not recognise the text as a paragraph and may become confused about the reading order if the document."
+            },
+            "16": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Empty paragraphs can confuse reader software for people with visual impairments. When multiple empty paragraphs are used to create white space in a document, they could be read out explicitly as empty paragraphs which is very disorienting and annoying."
+            },
+            "17": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Empty spans can confuse reader software for people with visual impairments. When multiple empty spans are used to create white space in a document, they could be read out explicitly as empty lines which is very disorienting and annoying."
+            },
+            "18": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Empty headings can confuse reader software for people with visual impairments. When multiple empty headings are used to create white space in a document, they could be read out explicitly as empty headings which is very disorienting and annoying."
+            },
+            "19": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Empty headings can confuse reader software for people with visual impairments. When multiple empty headings are used to create white space in a document, they could be read out explicitly as empty headings which is very disorienting and annoying."
+            },
+            "20": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Captions must be tagged as such. If not, then reader software for people with visual impairments may not recognise the text as a caption that belongs with the figure."
+            },
+            "21": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Lists must be formatted and tagged as such. If not, then reader software for people with visual impairments may not recognise the text as a list and may fail to read it out properly."
+            },
+            "22": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "List structures should be not be used for text which is not a list. And lists should not be interrupted by normal paragraphs."
+            },
+            "23": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "List structures should be not be used for text which is not a list. And lists should not be interrupted by normal paragraphs."
+            },
+            "25": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "List structures should be not be used for text which is not a list. And lists should not be interrupted by normal paragraphs."
+            },
+            "26": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Lists should not be misused to represent tables."
+            },
+            "27": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Multiple paragraphs should be tagged as such. Line breaks should not be used to delimit paragraphs."
+            },
+            "28": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Table of content items should be tagged as such."
+            },
+            "29": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Table of content items should not be empty."
+            },
+            "30": {
+                "STATUS": "warning",
+                "CATEGORY": "code",
+                "RATIONALE": "Table of content items should point somewhere in the document."
+            },
+            "31": {
+                "STATUS": "warning",
+                "CATEGORY": "code",
+                "RATIONALE": "Table of content items should point to the right place in the document."
+            },
+            "32": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Table of content items should be correctly aligned for readability."
+            },
+            "33": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "Table of contents item should match the heading it refers to."
+            },
+            "34": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "A single list should be tagged as such and not a series of smaller lists."
+            },
+            "35": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "A single table of contents should be tagged as such and not a series of tables of contents."
+            },
+            "36": {
+                "STATUS": "warning",
+                "CATEGORY": "code",
+                "RATIONALE": "The number of table row tags must correspond to the actual amount of table rows."
+            },
+            "37": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "The number of table column tags must correspond to the actual amount of table columns."
+            },
+            "38": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "A merged cell must be tagged correctly corresponding to the amount of rows it spans."
+            },
+            "39": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "A merged cell must be tagged correctly corresponding to the amount of columns it spans."
+            },
+            "40": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "List items must be tagged as such."
+            },
+            "41": {
+                "STATUS": "warning",
+                "CATEGORY": "code",
+                "RATIONALE": "The content of a table cell should appear in a position that is coherent with its tag."
+            },
+            "42": {
+                "STATUS": "warning",
+                "CATEGORY": "code",
+                "RATIONALE": "The content of a table cell should appear in a position that is coherent with its tag."
+            },
+            "43": {
+                "STATUS": "warning",
+                "CATEGORY": "code",
+                "RATIONALE": "The content of a table cell should appear in a position that is coherent with its tag."
+            },
+            "44": {
+                "STATUS": "warning",
+                "CATEGORY": "code",
+                "RATIONALE": "The content of a table cell should appear in a position that is coherent with its tag."
+            },
+            "45": {
+                "STATUS": "warning",
+                "CATEGORY": "structure",
+                "RATIONALE": "A normal table cell should not be tagged as a table head."
+            }
+        },
+        "4.1.3": {
+            "1": {
+                "STATUS": "error",
+                "CATEGORY": "code",
+                "RATIONALE": "If content has been tagged inappropriately, reader software for people with visual impairments will not read the document out in the correct way or order."
+            }
+        }
+    }
+}

package/src/constants/itemTypeDescription.ts

@@ -0,0 +1,11 @@
+const itemTypeDescription = {
+  mustFix:
+    'Issues that need to be addressed promptly, as they create significant barriers for persons with disabilities and can prevent them from accessing essential content or features.',
+  goodToFix:
+    'Issues that could pose certain challenges for persons with disabilities (PWDs), but are unlikely to completely hinder their access to essential content or features.',
+  needsReview:
+    'Occurrences could potentially be false positives, requiring human validation for accuracy.',
+  passed: 'Occurrences that passed the automated checks.',
+};
+
+export default itemTypeDescription;

package/src/constants/oobeeAi.ts

@@ -0,0 +1,141 @@
+// Purple AI rules to process axe outputted HTML into basicFormHTML snippets
+// for sending to backend services to query GPT
+export const oobeeAiRules = [
+  'aria-allowed-attr',
+  'aria-hidden-focus',
+  'aria-input-field-name',
+  'aria-required-attr',
+  'aria-required-children',
+  'aria-required-parent',
+  'aria-roles',
+  'aria-toggle-field-name',
+  'aria-valid-attr',
+  'aria-allowed-role',
+  'form-field-multiple-labels',
+  'label',
+  'scrollable-region-focusable',
+  'select-name',
+  'landmark-unique',
+  'meta-viewport-large',
+  'presentation-role-conflict',
+  'aria-treeitem-name',
+  'server-side-image-map',
+  'svg-img-alt',
+  'autocomplete-valid',
+];
+
+export const oobeeAiHtmlETL = htmlSnippet => {
+  // Whitelisted attributes (to not drop)
+  // i.e. any other attribute will be dropped
+  const whitelistedAttributes = [
+    `type`,
+    `tabindex`,
+    `lang`,
+    `scope`,
+    `alt`,
+    `role`,
+    `charset`,
+    `for`,
+    `content`,
+    `name`,
+    `onclick`,
+    `aria*`,
+    `src`,
+    `value`,
+    `href`,
+    `title`,
+    `style`,
+  ];
+
+  // Attributes to mute
+  const mutedAttributeValues = [
+    `name`,
+    `data`,
+    `src`,
+    `value`,
+    `href`,
+    `title`,
+    `aria-describedby`,
+    `aria-label`,
+    `aria-labelledby`,
+  ];
+
+  const sortAlphaAttributes = html => {
+    let entireHtml = '';
+    const htmlOpeningTagRegex = /<[^>]+/g;
+    const htmlTagmatches = html.match(htmlOpeningTagRegex);
+
+    let sortedHtmlTag;
+
+    htmlTagmatches.forEach(htmlTag => {
+      const closingTag = htmlTag.trim().slice(-1) === '/' ? '/>' : '>';
+
+      const htmlElementRegex = /<[^> ]+/;
+      const htmlElement = htmlTag.match(htmlElementRegex);
+
+      const htmlAttributeRegex = /[a-z-]+="[^"]*"/g;
+      const allAttributes = htmlTag.match(htmlAttributeRegex);
+
+      if (allAttributes) {
+        sortedHtmlTag = `${htmlElement} `;
+        allAttributes.sort((a, b) => {
+          const attributeA = a.toLowerCase();
+          const attributeB = b.toLowerCase();
+
+          if (attributeA < attributeB) {
+            return -1;
+          }
+
+          if (attributeA > attributeB) {
+            return 1;
+          }
+
+          return 0;
+        });
+
+        allAttributes.forEach((htmlAttribute, index) => {
+          sortedHtmlTag += htmlAttribute;
+          if (index !== allAttributes.length - 1) {
+            sortedHtmlTag += ' ';
+          }
+        });
+
+        sortedHtmlTag += closingTag;
+      } else {
+        sortedHtmlTag = htmlElement + closingTag;
+      }
+
+      entireHtml += sortedHtmlTag;
+    });
+    return entireHtml;
+  };
+
+  // For all attributes within mutedAttributeValues array
+  // replace their values with "something" while maintaining the attribute
+  const muteAttributeValues = html => {
+    const regex = /(\s+)([\w-]+)(\s*=\s*")([^"]*)(")/g;
+
+    // p1 is the whitespace before the attribute
+    // p2 is the attribute name
+    // p3 is the attribute value before the replacement
+    // p4 is the attribute value (replaced with "...")
+    // p5 is the closing quote of the attribute value
+    return html.replace(regex, (match, p1, p2, p3, p4, p5) => {
+      if (mutedAttributeValues.includes(p2)) {
+        return `${p1}${p2}${p3}...${p5}`;
+      }
+      return match;
+    });
+  };
+
+  // Drop all attributes from the HTML snippet except whitelisted
+  const dropAllExceptWhitelisted = html => {
+    const regex = new RegExp(
+      `(\\s+)(?!${whitelistedAttributes.join(`|`)})([\\w-]+)(\\s*=\\s*"[^"]*")`,
+      `g`,
+    );
+    return html.replace(regex, ``);
+  };
+
+  return sortAlphaAttributes(muteAttributeValues(dropAllExceptWhitelisted(htmlSnippet)));
+};

package/src/constants/questions.ts

@@ -0,0 +1,181 @@
+import { Question } from 'inquirer';
+import { Answers } from '../index.js';
+import { getUserDataTxt } from '../utils.js';
+import {
+  checkUrl,
+  deleteClonedProfiles,
+  getBrowserToRun,
+  getPlaywrightDeviceDetailsObject,
+  getUrlMessage,
+  getFileSitemap,
+  sanitizeUrlInput,
+  validEmail,
+  validName,
+  validateCustomFlowLabel,
+} from './common.js';
+import constants, { BrowserTypes, ScannerTypes } from './constants.js';
+
+const userData = getUserDataTxt();
+
+const questions = [];
+
+const startScanQuestions = [
+  {
+    type: 'list',
+    name: 'scanner',
+    message: 'What would you like to scan?',
+    choices: [
+      { name: 'Sitemap', value: ScannerTypes.SITEMAP },
+      { name: 'Website', value: ScannerTypes.WEBSITE },
+      { name: 'Custom', value: ScannerTypes.CUSTOM },
+      { name: 'Intelligent', value: ScannerTypes.INTELLIGENT },
+      { name: 'Localfile', value: ScannerTypes.LOCALFILE },
+    ],
+  },
+  {
+    type: 'confirm',
+    name: 'headless',
+    message: 'Do you want Oobee to run in the background?',
+    choices: ['Yes', 'No'],
+  },
+  {
+    type: 'list',
+    name: 'deviceChosen',
+    message: 'Which screen size would you like to scan? (Use arrow keys)',
+    choices: ['Desktop', 'Mobile', 'Custom'],
+  },
+  {
+    type: 'list',
+    name: 'customDevice',
+    message: 'Custom: (use arrow keys)',
+    when: (answers: Answers) => answers.deviceChosen === 'Custom',
+    choices: ['iPhone 11', 'Samsung Galaxy S9+', 'Specify viewport'],
+  },
+  {
+    type: 'number',
+    name: 'viewportWidth',
+    message: 'Specify width of the viewport in pixels (e.g. 360):',
+    when: (answers: Answers) => answers.customDevice === 'Specify viewport',
+    validate: (viewport: number) => {
+      if (!Number.isInteger(viewport)) {
+        return 'Invalid viewport width. Please provide an integer.';
+      }
+      if (viewport < 320 || viewport > 1080) {
+        return 'Invalid viewport width! Please provide a viewport width between 320-1080 pixels.';
+      }
+      return true;
+    },
+  },
+  {
+    type: 'input',
+    name: 'url',
+    message: (answers: Answers) => getUrlMessage(answers.scanner),
+    // eslint-disable-next-line func-names
+    // eslint-disable-next-line object-shorthand
+    validate: async function (url: string, answers: Answers) {
+      if (url.toLowerCase() === 'exit') {
+        process.exit(1);
+      }
+
+      const statuses = constants.urlCheckStatuses;
+      const { browserToRun, clonedBrowserDataDir } = getBrowserToRun(BrowserTypes.CHROME);
+      const playwrightDeviceDetailsObject = getPlaywrightDeviceDetailsObject(
+        answers.deviceChosen,
+        answers.customDevice,
+        answers.viewportWidth,
+      );
+
+      const res = await checkUrl(
+        answers.scanner,
+        url,
+        browserToRun,
+        clonedBrowserDataDir,
+        playwrightDeviceDetailsObject,
+        answers.scanner === ScannerTypes.CUSTOM,
+        answers.header,
+      );
+
+      deleteClonedProfiles(browserToRun);
+      switch (res.status) {
+        case statuses.success.code:
+          answers.finalUrl = res.url;
+          return true;
+        case statuses.cannotBeResolved.code:
+          return statuses.cannotBeResolved.message;
+        case statuses.systemError.code:
+          return statuses.systemError.message;
+        case statuses.invalidUrl.code:
+          if (answers.scanner !== (ScannerTypes.SITEMAP || ScannerTypes.LOCALFILE)) {
+            return statuses.invalidUrl.message;
+          }
+
+          /* if sitemap scan is selected, treat this URL as a filepath
+              isFileSitemap will tell whether the filepath exists, and if it does, whether the
+              file is a sitemap */
+          const finalFilePath = getFileSitemap(url);
+          if (finalFilePath) {
+            answers.isLocalFileScan = true;
+            answers.finalUrl = finalFilePath;
+            return true;
+          }
+          if (answers.scanner === ScannerTypes.LOCALFILE) {
+            return statuses.notALocalFile.message;
+          }
+          return statuses.notASitemap.message;
+
+        case statuses.notASitemap.code:
+          return statuses.notASitemap.message;
+        case statuses.notALocalFile.code:
+          return statuses.notALocalFile.message;
+      }
+    },
+    filter: (input: string) => sanitizeUrlInput(input.trim()).url,
+  },
+  {
+    type: 'input',
+    name: 'customFlowLabel',
+    message: 'Give a preferred label to your custom scan flow (Optional)',
+    when: (answers: Answers) => answers.scanner === ScannerTypes.CUSTOM,
+    validate: (label: string) => {
+      const { isValid, errorMessage } = validateCustomFlowLabel(label);
+      if (!isValid) {
+        return errorMessage;
+      }
+      return true;
+    },
+  },
+];
+
+const newUserQuestions: Question[] = [
+  {
+    type: 'input',
+    name: 'name',
+    message: `Name:`,
+    validate: (name: string): string | boolean => {
+      if (!validName(name)) {
+        return 'Invalid name. Please provide a valid name. Only alphabets in under 50 characters allowed.';
+      }
+      return true;
+    },
+  },
+  {
+    type: 'input',
+    name: 'email',
+    message: `Email:`,
+    validate: (email: string): string | boolean => {
+      if (!validEmail(email)) {
+        return 'Invalid email address. Please provide a valid email address.';
+      }
+      return true;
+    },
+  },
+];
+
+if (userData) {
+  questions.unshift(...startScanQuestions);
+} else {
+  newUserQuestions.push(...startScanQuestions);
+  questions.unshift(...newUserQuestions);
+}
+
+export default questions;