test: identifiers and urls used as link, definition, `linkR… (act…

…-rules#1083)

__tests__/link-is-outdated.js

@@ -0,0 +1,58 @@
+/**
+ * Note:
+ * This is a top level test suite, which runs across all the markdown pages under `_rules`, `pages` etc.,
+ * which is why this is not scoped under `__tests__` within any of those sections.
+ */
+
+const describeRule = require('../test-utils/describe-rule')
+const describePage = require('../test-utils/describe-page')
+const isUrl = require('is-url')
+const getMarkdownAstNodesOfType = require('../utils/get-markdown-ast-nodes-of-type')
+const uniqueArray = require('../utils/unique-array')
+
+/**
+ * Map of bad links vs their recommendations
+ */
+const badLinksAndRecommendations = {
+	'://www.w3.org/TR/WCAG20/': 'Use WCAG 2.1 reference- https://www.w3.org/WAI/WCAG21/',
+	'://www.w3.org/TR/UNDERSTANDING-WCAG20/': 'Use WCAG 2.1 reference - https://www.w3.org/WAI/WCAG21/Understanding/',
+	'://www.w3.org/TR/WCAG20-TECHS/': 'Use WCAG 2.1 reference - https://www.w3.org/WAI/WCAG21/Techniques/',
+	'://www.w3.org/TR/wai-aria-1.0/': 'Use ARIA 1.1 reference - https://www.w3.org/TR/wai-aria-1.1/',
+	'://www.w3.org/TR/dom41/': 'Use http://dom.spec.whatwg.org',
+	'://www.w3.org/TR/html/': 'Use http://html.spec.whatwg.org',
+}
+
+/**
+ * Validate `Rules` and `Pages` markdown files
+ */
+describe('Validate links are not outdated', () => {
+	describeRule('Rules', ({ markdownAST }) => validateIfLinksAreOutdated(markdownAST))
+	describePage('Pages', ({ markdownAST }) => validateIfLinksAreOutdated(markdownAST))
+})
+
+function validateIfLinksAreOutdated(markdownAST) {
+	/**
+	 * get all links
+	 * -> eg: [Alpha](https://....)
+	 */
+	const pageLinks = getMarkdownAstNodesOfType(markdownAST, 'link').map(({ url }) => url)
+	/**
+	 * get all definition links
+	 * -> eg: [alpha]: https:// 'Link to something'
+	 */
+	const definitionLinks = getMarkdownAstNodesOfType(markdownAST, 'definition').map(({ url }) => url)
+
+	/**
+	 * get all links that is a valid
+	 * -> this test does not cover glossary/ definition referencing links (see test - 'link-to-glossary-term-valid.js')
+	 */
+	const links = uniqueArray([...pageLinks, ...definitionLinks].filter(isUrl))
+	if (links.length === 0) {
+		return
+	}
+
+	test.each(links)('%s', link => {
+		const badLink = Object.keys(badLinksAndRecommendations).find(badLink => link.includes(badLink))
+		expect(!!badLink, badLinksAndRecommendations[badLink]).toBe(false)
+	})
+}

__tests__/link-reference-has-definition.js

@@ -0,0 +1,40 @@
+/**
+ * Note:
+ *
+ * In markdownAST,
+ * a link reference is something like [Alpha][Bravo] or [Alpha][], and
+ * a definition is something like [alpha]: https://example.com
+ *
+ * See: https://github.com/syntax-tree/mdast#nodes
+ *
+ * This test checks that there is a definition in the markdown file for every given link reference
+ * The test does not verify the integrity of the referred definition, but purely for an existence of a definition
+ */
+const describeRule = require('../test-utils/describe-rule')
+const describePage = require('../test-utils/describe-page')
+const getMarkdownAstNodesOfType = require('../utils/get-markdown-ast-nodes-of-type')
+const uniqueArray = require('../utils/unique-array')
+
+describe(`Validate link references`, () => {
+	describeRule('Rules', ({ markdownAST }) => validateLinkReferences(markdownAST))
+	describePage('Rules', ({ markdownAST }) => validateLinkReferences(markdownAST))
+})
+
+function validateLinkReferences(markdownAST) {
+	const linkReferences = uniqueArray(
+		getMarkdownAstNodesOfType(markdownAST, 'linkReference').map(({ identifier }) => identifier)
+	)
+	if (!linkReferences || !linkReferences.length) {
+		return
+	}
+
+	const definitions = uniqueArray(
+		getMarkdownAstNodesOfType(markdownAST, 'definition').map(({ identifier }) => identifier)
+	)
+
+	test.each(linkReferences)('%s', linkRef => {
+		const actual = definitions.includes(linkRef)
+		const msg = `Link reference -> [${linkRef}] is not defined`
+		expect(actual, msg).toBe(true)
+	})
+}

__tests__/link-to-glossary-term-valid.js

@@ -0,0 +1,63 @@
+/**
+ * This test checks every link that refers to a glossary term, uses the correct key to reference the glossary term/ definition
+ */
+const describeRule = require('../test-utils/describe-rule')
+const describePage = require('../test-utils/describe-page')
+const isUrl = require('is-url')
+const getMarkdownAstNodesOfType = require('../utils/get-markdown-ast-nodes-of-type')
+const uniqueArray = require('../utils/unique-array')
+
+describe(`Validate glossary references`, () => {
+	/**
+	 * Rules pages
+	 */
+	describeRule('Rules', validateGlossaryReferences)
+
+	/**
+	 * Other pages
+	 * -> in this case we only want to check for glossary terms referenced with glossary pages thyself,
+	 *    hence ignoring other pages
+	 */
+	describePage('Pages', (data, metaData) => {
+		const { path } = data
+		/**
+		 * Only run validation on glossary pages
+		 */
+		if (!path.includes('/pages/glossary/')) {
+			return
+		}
+		validateGlossaryReferences(data, metaData)
+	})
+})
+
+function validateGlossaryReferences({ markdownAST }, { glossaryKeys = [] }) {
+	/**
+	 * get all links
+	 * -> eg: [Alpha](https://....) or [Beta](#semantic-role)
+	 */
+	const pageLinks = getMarkdownAstNodesOfType(markdownAST, 'link').map(({ url }) => url)
+	/**
+	 * get all definition links
+	 * -> eg: [alpha]: https:// 'Link to something' or [beta]: #some-glossary 'Def to some glossary'
+	 */
+	const definitionLinks = getMarkdownAstNodesOfType(markdownAST, 'definition').map(({ url }) => url)
+
+	/**
+	 * get all links that are not a URL (eg: #semantic-role)
+	 * -> this test does not cover normal valid URL's (see test - 'link-is-outdated.js')
+	 */
+	const links = uniqueArray([...pageLinks, ...definitionLinks].filter(link => !isUrl(link))).filter(link => {
+		const [firstCharacter] = link.split('')
+		return firstCharacter === '#'
+	})
+	if (!links || !links.length) {
+		return
+	}
+
+	test.each(links)('%s', link => {
+		const key = link.substr(1)
+		const actual = glossaryKeys.includes(key)
+		const msg = `Glossary term - [#${key}] does not exist`
+		expect(actual, msg).toBe(true)
+	})
+}

_rules/explicit-SVG-image-has-name-7d6734.md

@@ -20,7 +20,7 @@ acknowledgements:
 
 ## Applicability
 
-The rule applies to any element in the [SVG](https://www.w3.org/2000/svg) namespace with an [explicit semantic role](#explicit-semantic-role) of either `img`, `graphics-document`, `graphics-symbol`, that is [included in the accessibility tree](#included-in-the-accessibility-tree).
+The rule applies to any element in the [SVG](https://www.w3.org/2000/svg) namespace with an [explicit semantic role](#explicit-role) of either `img`, `graphics-document`, `graphics-symbol`, that is [included in the accessibility tree](#included-in-the-accessibility-tree).
 
 **Note**: The [SVG Accessibility API Mappings](https://www.w3.org/TR/svg-aam-1.0/#include_elements) specifies that many elements in the SVG namespace are purely presentational and should not be included in the accessibility tree unless indicated otherwise through the use of text alternative content, an explicit WAI ARIA role, or a valid `tabindex` attribute.
 

_rules/form-control-label-descriptive-cc0f0a.md

@@ -22,7 +22,7 @@ acknowledgements:
 
 ## Applicability
 
-This rule applies to any HTML `label` element or other element referenced by `aria-labelledby` that, is [visible][] and is programmatically associated with an HTML element that has one of the following [semantic roles][]:
+This rule applies to any HTML `label` element or other element referenced by `aria-labelledby` that, is [visible][] and is programmatically associated with an HTML element that has one of the following [semantic roles][semantic role]:
 
 - `checkbox`
 - `combobox` (`select` elements)

_rules/iframe-identical-name-equivalent-purpose-4b1c6c.md

@@ -32,7 +32,7 @@ This rule applies to any set of any two or more `iframe` elements which:
 
 ## Expectation
 
-The `iframe` elements in each set of target elements embed the [same resource](#same-resource) or [equivalent resources](#equivalent-resource).
+The `iframe` elements in each set of target elements embed the [same resource][] or [equivalent resources](#equivalent-resource).
 
 **Note:** Resolving the embedded resource includes any redirects that are instant.
 
@@ -323,3 +323,8 @@ These `iframe` elements are not [included in the accessibility tree][], because
 [top-level browsing context]: https://html.spec.whatwg.org/#top-level-browsing-context 'Definition of top level browsing context'
 [usc412]: https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html 'Understanding Success Criterion 4.1.2: Name, Role, Value'
 [web page (html)]: #web-page-html 'Definition of web page (HTML)'
+[same resource]: #same-resource 'Definition of same resource'
+[flat tree]: https://drafts.csswg.org/css-scoping/#flat-tree 'Definition of flat tree'
+[light tree]: https://dom.spec.whatwg.org/#concept-light-tree 'Definition of light tree'
+[shadow tree]: https://dom.spec.whatwg.org/#shadow-tree 'Definition of shadow tree'
+[matching]: #matching-characters 'Definition of matching characters'