dequelabs · jeeyyy · Jan 15, 2020 · Jun 5, 2019 · Jun 18, 2019 · Jun 20, 2019
diff --git a/doc/backwards-compatibility-doc.md b/doc/backwards-compatibility-doc.md
@@ -26,7 +26,7 @@ In a minor release, we may add support for new technologies in the Public Utils
 
 If the HTML page is unchanged, calls to the analysis function(s) when compared across minor or patch releases will return the same exact selector for the nodes in any of the result arrays. If the HTML page has changed, it is possible for the selector to be different but it is not guaranteed that the selector will be different.
 
-APIs may be deprecated in a major or minor release. APIs that have been deprecated for 6 months or more will be removed in the next major release. 
+APIs may be deprecated in a major or minor release. APIs that have been deprecated for 6 months or more will be removed in the next major release.
 
 A major or a minor release may introduce new Public Utils.
 

@@ -42,6 +42,7 @@
 | html-has-lang                       | Ensures every HTML document has a lang attribute                                                                           | Serious            | cat.language, wcag2a, wcag311                                                    | true               |
 | html-lang-valid                     | Ensures the lang attribute of the &lt;html&gt; element has a valid value                                                   | Serious            | cat.language, wcag2a, wcag311                                                    | true               |
 | html-xml-lang-mismatch              | Ensure that HTML elements with both valid lang and xml:lang attributes agree on the base language of the page              | Moderate           | cat.language, wcag2a, wcag311                                                    | true               |
+| identical-links-same-purpose        | Ensure that links with the same accessible name serve a similar purpose                                                    | Minor              | wcag2aaa, wcag249, best-practice, experimental                                   | true               |
 | image-alt                           | Ensures &lt;img&gt; elements have alternate text or a role of none or presentation                                         | Critical           | cat.text-alternatives, wcag2a, wcag111, section508, section508.22.a              | true               |
 | image-redundant-alt                 | Ensure image alternative is not repeated as text                                                                           | Minor              | cat.text-alternatives, best-practice                                             | true               |
 | input-button-name                   | Ensures input buttons have discernible text                                                                                | Critical           | cat.name-role-value, wcag2a, wcag412, section508, section508.22.a                | true               |

@@ -0,0 +1,99 @@
+/**
+ * Skip, as no results to curate
+ */
+if (results.length < 2) {
+	return results;
+}
+
+/**
+ * for each result
+ * - get other results with matching accessible name
+ * - check if same purpose is served
+ * - if not change `result` to `undefined`
+ * - construct a list of unique results with relatedNodes to return
+ */
+const uniqueResults = [];
+const nameMap = {};
+
+for (let index = 0; index < results.length; index++) {
+	const currentResult = results[index];
+	const { name, urlProps } = currentResult.data;
+
+	/**
+	 * This is to avoid duplications in the `nodeMap`
+	 */
+	if (nameMap[name]) {
+		continue;
+	}
+
+	const sameNameResults = results
+		.filter(({ data }, resultNum) =>
+			data.name === name && resultNum !== index
+		)
+	const isSameUrl = sameNameResults
+		.every(({ data }) => isIdenticalObject(data.urlProps, urlProps))
+
+	/**
+	 * when identical nodes exists but do not resolve to same url, flag result as `incomplete`
+	 */
+	if (sameNameResults.length && !isSameUrl) {
+		currentResult.result = undefined;
+	}
+
+	/**
+	 *  -> deduplicate results (for both `pass` or `incomplete`) and add `relatedNodes` if any
+	 */
+	currentResult.relatedNodes = [];
+	currentResult.relatedNodes.push(
+		...sameNameResults.map(node => node.relatedNodes[0])
+	);
+
+	/**
+	 * Update `nodeMap` with `sameNameResults`
+	 */
+	nameMap[name] = sameNameResults;
+
+	uniqueResults.push(currentResult);
+}
+
+return uniqueResults;
+
+
+/**
+ * Check if two given objects are the same (Note: this fn is not extensive in terms of depth equality)
+ * @param {Object} a object a, to compare
+ * @param {*} b object b, to compare
+ * @returns {Boolean}
+ */
+function isIdenticalObject(a, b) {
+	if (!a || !b) {
+		return false
+	}
+
+	const aProps = Object.getOwnPropertyNames(a);
+	const bProps = Object.getOwnPropertyNames(b);
+
+	if (aProps.length !== bProps.length) {
+		return false;
+	}
+
+	const result = aProps.every(propName => {
+		const aValue = a[propName]
+		const bValue = b[propName]
+
+		if (typeof aValue !== typeof bValue) {
+			return false
+		}
+
+		if (
+			typeof aValue === `object` ||
+			typeof bValue === `object`
+		) {
+			return isIdenticalObject(aValue, bValue)
+		}
+
+		return aValue === bValue
+	})
+
+	return result;
+}
@@ -0,0 +1,31 @@
+/**
+ * Note: `identical-links-same-purpose-after` fn, helps reconcile the results
+ */
+const { dom, text } = axe.commons;
+
+const accText = text.accessibleTextVirtual(virtualNode);
+const name = text
+	.sanitize(
+		text.removeUnicode(accText, {
+			emoji: true,
+			nonBmp: true,
+			punctuations: true
+		})
+	)
+	.toLowerCase();
+
+if (!name) {
+	return undefined;
+}
+
+/**
+ * Set `data` and `relatedNodes` for use in `after` fn
+ */
+const afterData = {
+	name,
+	urlProps: dom.urlPropsFromAttribute(node, 'href')
+};
+this.data(afterData);
+this.relatedNodes([node]);
+
+return true;
@@ -0,0 +1,12 @@
+{
+	"id": "identical-links-same-purpose",
+	"evaluate": "identical-links-same-purpose.js",
+	"after": "identical-links-same-purpose-after.js",
+	"metadata": {
+		"impact": "minor",
+		"messages": {
+			"pass": "There are no other links with the same name, that go to a different URL",
+			"incomplete": "Check that links have the same purpose, or are intentionally ambiguous."
+		}
+	}
+}
@@ -39,6 +39,39 @@ function isClipped(style) {
 	return false;
 }
 
+/**
+ * Check `AREA` element is visible
+ * - validate if it is a child of `map`
+ * - ensure `map` is referred by `img` using the `usemap` attribute
+ * @param {Element} areaEl `AREA` element
+ * @retruns {Boolean}
+ */
+function isAreaVisible(el, screenReader, recursed) {
+	/**
+	 * Note:
+	 * - Verified that `map` element cannot refer to `area` elements across different document trees
+	 * - Verified that `map` element does not get affected by altering `display` property
+	 * - using `.closest` fails in `phantomjs`, hence using `dom.findUp`
+	 */
+	const mapEl = dom.findUp(el, 'map');
+	if (!mapEl) {
+		return false;
+	}
+
+	const mapElName = mapEl.getAttribute('name');
+	if (!mapElName) {
+		return false;
+	}
+	const refs = document.querySelectorAll(
+		`img[usemap="#${axe.utils.escapeSelector(mapElName)}"]`
+	);
+	if (!refs || !refs.length) {
+		return false;
+	}
+
+	return  Array.from(refs).some(ref => dom.isVisible(ref, screenReader, recursed))
+}
+
 /**
  * Determine whether an element is visible
  * @method isVisible
@@ -74,9 +107,13 @@ dom.isVisible = function(el, screenReader, recursed) {
 	}
 
 	const nodeName = el.nodeName.toUpperCase();
-
 	if (
-		style.getPropertyValue('display') === 'none' ||
+		/**
+		 * Note:
+		 * Firefox's user-agent always sets `AREA` element to `display:none`
+		 * hence excluding the edge case, for visibility computation
+		 */
+		(nodeName !== 'AREA' && style.getPropertyValue('display') === 'none') ||
 		['STYLE', 'SCRIPT', 'NOSCRIPT', 'TEMPLATE'].includes(nodeName) ||
 		(!screenReader && isClipped(style)) ||
 		(!recursed &&
@@ -89,6 +126,13 @@ dom.isVisible = function(el, screenReader, recursed) {
 		return false;
 	}
 
+	/**
+	 * check visibility of `AREA`
+	 */
+	if (nodeName === 'AREA') {
+		return isAreaVisible(el, screenReader, recursed);
+	}
+
 	const parent = el.assignedSlot ? el.assignedSlot : el.parentNode;
 	let isVisible = false;
 	if (parent) {

@@ -0,0 +1,154 @@
+/* global dom */
+
+/**
+ * Parse resource object for a given node from a specified attribute
+ * @method urlPropsFromAttribute
+ * @param {HTMLElement} node given node
+ * @param {String} attribute attribute of the node from which resource should be parsed
+ * @returns {Object}
+ */
+dom.urlPropsFromAttribute = function urlPropsFromAttribute(node, attribute) {
+	const value = node[attribute];
+	if (!value) {
+		return undefined;
+	}
+
+	const nodeName = node.nodeName.toUpperCase();
+	let parser = node;
+
+	/**
+	 * Note:
+	 * The need to create a parser, is to keep this function generic, to be able to parse resource from element like `iframe` with `src` attribute
+	 */
+	if (!['A', 'AREA'].includes(nodeName)) {
+		parser = document.createElement('a');
+		parser.href = value;
+	}
+
+	const { pathname = '', filename = '' } = getPathnameOrFilename(
+		parser.pathname
+	);
+	return {
+		protocol: parser.protocol,
+		hostname: parser.hostname,
+		port: getPort(parser.port),
+		pathname: pathname.replace(/\/$/, ''), // remove trialing slashes
+		search: getSearchPairs(parser.search),
+		hash: getHashRoute(parser.hash),
+		filename
+	};
+};
+
+
+/**
+ * Resolve given port excluding default port(s)
+ * @param {String} port port
+ * @returns {String}
+ */
+function getPort(port) {
+	/**
+	 * Note: IE11 resolves port to `443` for any URL with `https:`
+	 */
+	const excludePorts = [`443`, `80`]
+	return !excludePorts.includes(port)
+		? port
+		: ``
+}
+
+/**
+ * Resolve if a given pathname has filename & resolve the same as parts
+ * @method getPathnameOrFilename
+ * @param {String} pathname pathname part of a given uri
+ * @returns {Array<String>}
+ */
+function getPathnameOrFilename(pathname) {
+	if (!pathname) {
+		return;
+	}
+
+	const filename = pathname.split('/').pop();
+	if (!filename || filename.indexOf('.') === -1) {
+		return {
+			pathname
+		};
+	}
+
+	return {
+		// remove `filename` from `pathname`
+		pathname: pathname.replace(filename, ''),
+
+		// ignore filename when index.*
+		filename: /index./.test(filename)
+			? undefined
+			: filename
+	};
+}
+
+/**
+ * Parse a given query string to key/value pairs sorted alphabetically
+ * @param {String} searchStr search string
+ * @returns {Object}
+ */
+function getSearchPairs(searchStr) {
+	const query = {};
+
+	if (!searchStr || !searchStr.length) {
+		return query
+	}
+
+	const curatedSearchStr = searchStr[0] === `?` ? searchStr.substring(1) : searchStr
+	const pairs = curatedSearchStr.split(`&`);
+	if (!pairs || !pairs.length) {
+		return query
+	}
+
+
+	for (let index = 0; index < pairs.length; index++) {
+		const pair = pairs[index];
+		const [key, value = ''] = pair.split(`=`)
+		query[decodeURIComponent(key)] = decodeURIComponent(value);
+	}
+
+	/**
+	 * Sort query `keys` alphabetically
+	 */
+	return Object.keys(query)
+		.sort()
+		.reduce((out, key) => {
+			out[key] = query[key]
+			return out
+		}, {});
+}
+
+/**
+ * Interpret a given hash
+ * if `hash`
+ * -> is `hashbang` -or- `hash` is followed by `slash`
+ * -> it resolves to a different resource
+ * @method getHashRoute
+ * @param {String} hash hash component of a parsed uri
+ * @returns {String|undefined}
+ */
+function getHashRoute(hash) {
+	if (!hash) {
+		return undefined;
+	}
+
+	/**
+	 * Check for any conventionally-formatted hashbang may be present
+	 * eg: `#, #/, #!, #!/`
+	 */
+	const hashRegex = /#!?\/?/g;
+	const hasMatch = hash.match(hashRegex);
+	if (!hasMatch) {
+		return undefined;
+	}
+
+	// do not resolve inline link as hash
+	const [matchedStr] = hasMatch;
+	if (matchedStr === '#') {
+		return undefined;
+	}
+
+	return hash;
+}