feat(jest): add jest accessibility matcher

.eslintrc.js

@@ -14,6 +14,7 @@ module.exports = {
         'jest',
         'prettier',
         'notice', // checks for and fixes copyright header in each file
+        'markdown',
     ],
     extends: [
         'eslint:recommended',
@@ -24,7 +25,19 @@ module.exports = {
         'plugin:jest/style',
         'plugin:prettier/recommended',
         'prettier/@typescript-eslint',
+        'plugin:import/typescript',
+        'plugin:import/errors',
+        'plugin:import/warnings',
+        'plugin:eslint-comments/recommended',
     ],
+    settings: {
+        'import/resolver': {
+            // Makes plugin:import work with Typescript interfaces etc
+            typescript: {
+                alwaysTryTypes: true, // always try to resolve types under `<root>@types` directory even it doesn't contain any source code
+            },
+        },
+    },
     rules: {
         'notice/notice': [
             'error',
@@ -34,6 +47,13 @@ module.exports = {
         ],
         'tsdoc/syntax': 'warn',
     },
+    overrides: [
+        {
+            // Enable the Markdown processor for all .md files.
+            files: ['**/*.md'],
+            processor: 'markdown/markdown',
+        },
+    ],
     env: {
         browser: true,
         node: true,

.ncurc.json

@@ -0,0 +1,4 @@
+{
+    "upgrade": true,
+    "reject": ["@types/node"]
+}

.prettierrc.js

@@ -3,4 +3,10 @@ module.exports = {
     printWidth: 120,
     singleQuote: true,
     trailingComma: 'es5',
+    overrides: [
+        {
+            files: '*.md',
+            tabWidth: 2, // To accommodate doctoc formatting (no override for tab width in doctoc)
+        },
+    ],
 };

CHANGELOG.md

@@ -1,3 +1,16 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [(2020-04-07)](#2020-04-07)
+    - [Bug Fixes](#bug-fixes)
+    - [Features](#features)
+- [(2020-03-20)](#2020-03-20)
+    - [Bug Fixes](#bug-fixes-1)
+    - [Features](#features-1)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 # (2020-04-07)
 
 ### Bug Fixes

CODE_OF_CONDUCT.md

@@ -1,5 +1,19 @@
 # Salesforce Open Source Community Code of Conduct
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [About the Code of Conduct](#about-the-code-of-conduct)
+- [Our Pledge](#our-pledge)
+- [Our Standards](#our-standards)
+- [Our Responsibilities](#our-responsibilities)
+- [Scope](#scope)
+- [Enforcement](#enforcement)
+- [Attribution](#attribution)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## About the Code of Conduct
 
 Equality is a core value at Salesforce. We believe a diverse and inclusive
@@ -35,23 +49,23 @@ socioeconomic status, or other similar personal characteristics.
 Examples of behavior that contributes to creating a positive environment
 include:
 
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy toward other community members
+-   Using welcoming and inclusive language
+-   Being respectful of differing viewpoints and experiences
+-   Gracefully accepting constructive criticism
+-   Focusing on what is best for the community
+-   Showing empathy toward other community members
 
 Examples of unacceptable behavior by participants include:
 
-* The use of sexualized language or imagery and unwelcome sexual attention or
-advances
-* Personal attacks, insulting/derogatory comments, or trolling
-* Public or private harassment
-* Publishing, or threatening to publish, others' private information—such as
-a physical or electronic address—without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-professional setting
-* Advocating for or encouraging any of the above behaviors
+-   The use of sexualized language or imagery and unwelcome sexual attention or
+    advances
+-   Personal attacks, insulting/derogatory comments, or trolling
+-   Public or private harassment
+-   Publishing, or threatening to publish, others' private information—such as
+    a physical or electronic address—without explicit permission
+-   Other conduct which could reasonably be considered inappropriate in a
+    professional setting
+-   Advocating for or encouraging any of the above behaviors
 
 ## Our Responsibilities
 
@@ -98,7 +112,7 @@ It includes adaptions and additions from [Go Community Code of Conduct][golang-c
 
 This Code of Conduct is licensed under the [Creative Commons Attribution 3.0 License][cc-by-3-us].
 
-[contributor-covenant-home]: https://www.contributor-covenant.org (https://www.contributor-covenant.org/)
+[contributor-covenant-home]: https://www.contributor-covenant.org 'https://www.contributor-covenant.org/'
 [golang-coc]: https://golang.org/conduct
 [cncf-coc]: https://github.com/cncf/foundation/blob/master/code-of-conduct.md
 [microsoft-coc]: https://opensource.microsoft.com/codeofconduct/

CONTRIBUTING.md

@@ -2,40 +2,59 @@
 
 We want to encourage the developer community to contribute to Sa11y. This guide has instructions to install, build, test and contribute to the framework. Adapted from [salesforce/lwc](https://github.com/salesforce/lwc/blob/master/CONTRIBUTING.md)
 
--   [Contributing Guidelines](#contributing-guidelines)
-    -   [Requirements](#requirements)
-    -   [Installation](#installation)
-        -   [1) Download the repository](#1-download-the-repository)
-        -   [2) Install Dependencies](#2-install-dependencies)
-    -   [Building](#building)
-    -   [Testing](#testing)
-        -   [Unit Testing](#unit-testing)
-        -   [Integration Testing](#integration-testing)
-    -   [Editor Configurations](#editor-configurations)
-        -   [Types](#types)
-        -   [ESLint](#eslint)
-    -   [Git Workflow](#git-workflow)
-        -   [Fork the repo](#fork-the-repo)
-        -   [Create a feature branch](#create-a-feature-branch)
-        -   [Make your changes](#make-your-changes)
-        -   [Rebase](#rebase)
-        -   [Check your submission](#check-your-submission)
-            -   [Lint your changes](#lint-your-changes)
-            -   [Run tests](#run-tests)
-        -   [Create a pull request](#create-a-pull-request)
-            -   [Pull Request Title](#pull-request-title)
-        -   [Update the pull request](#update-the-pull-request)
-        -   [Commit Message Conventions](#commit-message-conventions)
-            -   [Commit Message Format](#commit-message-format)
-            -   [Reverting a commit](#reverting-a-commit)
-            -   [Commit Type](#commit-type)
-            -   [Commit Scope](#commit-scope)
-            -   [Commit Subject](#commit-subject)
-            -   [Commit Body](#commit-body)
-            -   [Commit Footer](#commit-footer)
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Quick start](#quick-start)
+- [Requirements](#requirements)
+- [Installation](#installation)
+  - [1) Download the repository](#1-download-the-repository)
+  - [2) Install Dependencies](#2-install-dependencies)
+- [Building](#building)
+- [Testing](#testing)
+  - [Unit Testing](#unit-testing)
+  - [Integration Testing](#integration-testing)
+- [Editor Configurations](#editor-configurations)
+  - [Types](#types)
+  - [ESLint](#eslint)
+- [Git Workflow](#git-workflow)
+  - [Fork the repo](#fork-the-repo)
+  - [Create a feature branch](#create-a-feature-branch)
+  - [Make your changes](#make-your-changes)
+  - [Rebase](#rebase)
+  - [Check your submission](#check-your-submission)
+    - [Lint your changes](#lint-your-changes)
+    - [Run tests](#run-tests)
+  - [Create a pull request](#create-a-pull-request)
+    - [Pull Request Title](#pull-request-title)
+  - [Update the pull request](#update-the-pull-request)
+  - [Commit Message Conventions](#commit-message-conventions)
+    - [Commit Message Format](#commit-message-format)
+    - [Reverting a commit](#reverting-a-commit)
+    - [Commit Type](#commit-type)
+    - [Commit Scope](#commit-scope)
+    - [Commit Subject](#commit-subject)
+    - [Commit Body](#commit-body)
+    - [Commit Footer](#commit-footer)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 Before you start, it helps to be familiar with [Web Accessibility](https://trailhead.salesforce.com/en/content/learn/trails/get-started-with-web-accessibility)
 
+## Quick start
+
+1. `yarn install` to install dependencies
+2. Make changes while building, testing and linting the changed files
+
+-   `yarn build:watch`
+-   `yarn test:watch`
+-   `yarn lint:watch`
+
+3. Update changelog with `yarn changelog`
+4. Stage changes in git and do `yarn commit` to check staged changes and commit them with a formatted commit message
+5. Push changes to feature branch
+
 ## Requirements
 
 -   [Node](https://nodejs.org/) >= 12
@@ -53,7 +72,7 @@ git clone [email protected]:salesforce/sa11y.git
 
 ### 2) Install Dependencies
 
-_We use [yarn](https://yarnpkg.com/) because it is significantly faster than npm for our use case. See this command [cheatsheet](https://yarnpkg.com/lang/en/docs/migrating-from-npm/)._
+_We use [yarn](https://yarnpkg.com/) because it is significantly faster than npm for our use case. See this command [cheat-sheet](https://yarnpkg.com/lang/en/docs/migrating-from-npm/)._
 
 ```bash
 yarn install
@@ -63,8 +82,11 @@ If this fails with an error about _UNABLE_TO_GET_ISSUER_CERT_LOCALLY_, _Error: u
 
 ## Building
 
+When developing typescript compiler can be invoked using the `build` target.
+With `:watch` the compiler would watch for changes and incrementally compile changed sources as required.
+
 ```bash
-yarn build
+yarn build[:watch]
 ```
 
 ## Testing
@@ -80,7 +102,7 @@ yarn test
 Additionally, the testing can be started in 'watch' mode which allows for automatic test re-runs on save:
 
 ```bash
-yarn test --watch
+yarn test:watch
 ```
 
 To execute a particular test, use the following command:

LICENSE.txt

@@ -1,12 +1,28 @@
+BSD 3-Clause License
+
 Copyright (c) 2020, Salesforce.com, Inc.
 All rights reserved.
 
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
 
-* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
 
-* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
 
-* Neither the name of Salesforce.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+* Neither the name of Salesforce.com nor the names of its contributors may be used
+  to endorse or promote products derived from this software without specific prior
+  written permission.
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -4,12 +4,26 @@ Salesforce Accessibility Automated Testing Libraries and Tools (@sa11y packages)
 
 ![CI](https://github.com/salesforce/sa11y/workflows/CI/badge.svg)
 
--   [Salesforce Accessibility Automation Libraries](#salesforce-accessibility-automation-libraries)
-    -   [Packages](#packages)
-        -   [Preset Accessibility rules](#preset-accessibility-rules)
-        -   [assertAccessible API (TBD)](#assertaccessible-api-tbd)
-        -   [a11y results formatter (TBD)](#a11y-results-formatter-tbd)
-        -   [Jest integration (TBD)](#jest-integration-tbd)
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Docs](#docs)
+- [Packages](#packages)
+  - [Preset accessibility rules](#preset-accessibility-rules)
+  - [assertAccessible API](#assertaccessible-api)
+  - [a11y results formatter](#a11y-results-formatter)
+  - [Jest integration](#jest-integration)
+  - [Test utilities](#test-utilities)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Docs
+
+-   [Developer Guidelines](./CONTRIBUTING.md)
+-   [Code of Conduct](./CODE_OF_CONDUCT.md)
+-   [Changelog](./CHANGELOG.md)
+-   [LICENSE](./LICENSE.txt)
 
 ## Packages
 
@@ -27,6 +41,10 @@ This repo contains the following packages
 
 -   format raw a11y issues JSON output from axe into an easy to consume format by consolidating and cross-referencing
 
-### Jest integration (TBD)
+### [Jest integration](./packages/jest/README.md)
+
+-   provides a `toBeAccessible()` accessibility matcher for Jest integrating the [assertAccessible API](./packages/assert/README.md) with the [Jest assertion API](https://jestjs.io/docs/en/using-matchers)
+
+### [Test utilities](./packages/test-utils/README.md)
 
--   integrates the assertAccessible API with the [Jest assertion API](https://jestjs.io/docs/en/using-matchers)
+-   Private package providing test utilities for `@sa11y` packages

cSpell.json

@@ -1,6 +1,9 @@
 {
     "ignorePaths": ["node_modules/**", "package.json"],
     "ignoreWords": [
+        "assertAccessible",
+        "doctoc",
+        "CNCF",
         "SPDX", // license header
         "tsdoc"
     ],

mdLinkChecker.json

@@ -0,0 +1,8 @@
+{
+    "ignorePatterns": [
+        {
+            "TODO": "REMOVE after repository is made public",
+            "pattern": "^https://github.com/salesforce/sa11y"
+        }
+    ]
+}