chore: Generate and display implementation metrics

build/create-glossary-usages.js

@@ -0,0 +1,89 @@
+/**
+ * Create glossary usages
+ * -> for each glossary item (find references in each rule)
+ * -> this is saved in `_data` which is later used in `pages/glossary`
+ */
+const globby = require('globby')
+const regexps = require('../utils/reg-exps')
+const createFile = require('../utils/create-file')
+const getAllMatchesForRegex = require('../utils/get-all-matches-for-regex')
+const getMarkdownData = require('../utils/get-markdown-data')
+
+const init = async () => {
+	/**
+	 * Get all rules `markdown` data
+	 */
+	const rulesData = globby
+		.sync([`./_rules/*.md`])
+		.map(rulePath => getMarkdownData(rulePath))
+
+	/**
+	 * Eg:
+	 * {
+	 *  `non-empty`: [
+	 *    { name: `aria valid ...`, slug: `rules/XXXXX` },
+	 *    ....
+	 *  ]
+	 *  ....
+	 * }
+	 */
+	const glossaryUsages = {}
+
+	rulesData.forEach(ruleData => {
+		const { frontmatter, body } = ruleData
+		const {
+			id: ruleId,
+			name: ruleName,
+			accessibility_requirements: ruleAccessibilityRequirements,
+		} = frontmatter
+
+		const glossaryMatches = getAllMatchesForRegex(
+			regexps.glossaryReferenceInRules,
+			body,
+			false
+		)
+
+		glossaryMatches.forEach(glossaryItem => {
+			const hasGlossaryKey = regexps.glossaryKey.test(glossaryItem.block)
+			if (!hasGlossaryKey) {
+				return
+			}
+
+			const key = glossaryItem.block.match(regexps.glossaryKey)[1]
+			if (!key) {
+				return
+			}
+
+			const usage = {
+				name: ruleName,
+				slug: `rules/${ruleId}`,
+			}
+			if (!glossaryUsages[key]) {
+				glossaryUsages[key] = [usage]
+				return
+			}
+
+			const exists = glossaryUsages[key].some(u => u.slug === usage.slug)
+			if (exists) {
+				return
+			}
+
+			glossaryUsages[key] = glossaryUsages[key].concat(usage)
+		})
+	})
+
+	/**
+	 * Create `_data/glossary-usages.json`
+	 */
+	await createFile(
+		`./_data/glossary-usages.json`,
+		JSON.stringify(glossaryUsages, undefined, 2)
+	)
+}
+
+/**
+ * Invoke
+ */
+init()
+	.then(() => console.info(`Completed: task: create:glossary\n`))
+	.catch(e => console.error(e))

build/create-implementation-metrics.js

@@ -0,0 +1,81 @@
+const globby = require('globby')
+const readFile = require('../utils/read-file')
+const createFile = require('../utils/create-file')
+
+/**
+ * Init
+ */
+const init = async () => {
+	/**
+	 * Get all implementation reports
+	 */
+	const reports = globby
+		.sync([`./_data/implementations/*.json`])
+		.map(reportPath => {
+			const fileContent = readFile(reportPath)
+			return JSON.parse(fileContent)
+		})
+
+	const implementers = []
+	const implementationsGroupedByRuleId = {}
+
+	reports.forEach(report => {
+		const { tool, organisation, data } = report
+
+		/**
+		 * Create data that can be used in `src/templates/coverage.js`
+		 */
+		implementers.push(report)
+
+		/**
+		 * Iterate each implementation & group by rule id
+		 */
+		data.forEach(({ ruleId, implementation }) => {
+			if (!implementation) {
+				return
+			}
+
+			/**
+			 * Note:
+			 * only build `metrics` for implementations that are `complete`
+			 */
+			const { complete = false } = implementation
+			if (complete) {
+				return
+			}
+
+			if (!implementationsGroupedByRuleId[ruleId]) {
+				implementationsGroupedByRuleId[ruleId] = []
+			}
+
+			implementationsGroupedByRuleId[ruleId].push({
+				organisation,
+				tool,
+				implementation,
+			})
+		})
+	})
+
+	/**
+	 * Create `implementations.json`
+	 */
+	await createFile(
+		`_data/implementers.json`,
+		JSON.stringify(implementers, null, 2)
+	)
+
+	/**
+	 * Create metrics in `_data` for usage in `site`
+	 */
+	await createFile(
+		`_data/implementation-metrics.json`,
+		JSON.stringify(implementationsGroupedByRuleId, null, 2)
+	)
+}
+
+init()
+	.then(() => console.info(`\nImplementation metrics generated.\n`))
+	.catch(e => {
+		console.error(e)
+		process.exit(1)
+	})

build/create-testcases.js

@@ -0,0 +1,149 @@
+const globby = require('globby')
+const makeDir = require('make-dir')
+const objectHash = require('object-hash')
+const codeBlocks = require('gfm-code-blocks')
+const {
+	www: { url, baseDir },
+} = require('./../package.json')
+const getMarkdownData = require('./../utils/get-markdown-data')
+const createFile = require('../utils/create-file')
+const regexps = require('../utils/reg-exps')
+const getAllMatchesForRegex = require('../utils/get-all-matches-for-regex')
+const copyTestcasesAssets = require('./testcases/copy-testcases-assets')
+const createTestcasesJson = require('./testcases/create-testcases-json')
+const createTestcasesOfRuleOfEmReportTool = require('./testcases/create-testcases-of-rule-of-em-report-tool')
+
+/**
+ * Create test case files & other meta-data  from test case in each rule.
+ *
+ * -> create test cases files into `./public/testcases/`
+ * -> copy `./test-assets/*` into `./public`
+ * -> create `testcases.json` into `./public`
+ */
+const init = async () => {
+	/**
+	 * Create `public` directory
+	 */
+	await makeDir(`public`)
+
+	/**
+	 * Get all rules `markdown` data
+	 */
+	const rulesData = globby
+		.sync([`./_rules/*.md`])
+		.map(rulePath => getMarkdownData(rulePath))
+
+	let allRulesTestcases = []
+
+	/**
+	 * iterate all rule pages
+	 * -> get code snippets
+	 * -> and their relevant titles
+	 */
+	rulesData.forEach(ruleData => {
+		const { frontmatter, body } = ruleData
+		const {
+			id: ruleId,
+			name: ruleName,
+			accessibility_requirements: ruleAccessibilityRequirements,
+		} = frontmatter
+		const codeTitles = getAllMatchesForRegex(regexps.testcaseTitle, body)
+
+		/**
+		 * get code blocks in markdown body
+		 */
+		const codeSnippets = codeBlocks(body)
+
+		if (codeTitles.length !== codeSnippets.length) {
+			throw new Error(
+				`Number of matching titles for code snippets is wrong. Check markdown '${ruleName}' for irregularities.`
+			)
+		}
+
+		/**
+		 * iterate each code snippet
+		 * -> create a testcase file
+		 * -> and add meta of testcase to `testcases.json`
+		 */
+		const ruleTestcases = codeSnippets.reduce((out, codeBlock, index) => {
+			const title = codeTitles[index]
+			if (!title) {
+				throw new Error('No title found for code snippet.')
+			}
+
+			const { code, block } = codeBlock
+			let { type = 'html' } = codeBlock
+
+			if (regexps.testcaseCodeSnippetTypeIsSvg.test(block.substring(0, 15))) {
+				type = 'svg'
+			}
+
+			const codeId = objectHash({
+				block,
+				type,
+				ruleId,
+			})
+
+			const titleCurated = title.value.split(' ').map(t => t.toLowerCase())
+
+			const testcaseFileName = `${ruleId}/${codeId}.${type}`
+			const testcasePath = `testcases/${testcaseFileName}`
+			/**
+			 * Create testcase file
+			 */
+			createFile(`${baseDir}/${testcasePath}`, code)
+
+			/**
+			 * Create meta data for testcase(s)
+			 */
+			const testcase = {
+				testcaseId: codeId,
+				url: `${url}/${testcasePath}`,
+				relativePath: testcasePath,
+				expected: titleCurated[0],
+				ruleId,
+				ruleName,
+				rulePage: `${url}/rules/${ruleId}`,
+				ruleAccessibilityRequirements,
+			}
+
+			out.push(testcase)
+			return out
+		}, [])
+
+		// add rule testcases to all testcases
+		allRulesTestcases = allRulesTestcases.concat(ruleTestcases)
+
+		/**
+		 * Create test cases of rule for use with `em report tool`
+		 */
+		createTestcasesOfRuleOfEmReportTool({
+			ruleId,
+			ruleName,
+			ruleTestcases,
+			ruleAccessibilityRequirements,
+		})
+	})
+
+	/**
+	 * Copy `test-assets` that are used by `testcases`
+	 */
+	await copyTestcasesAssets()
+
+	/**
+	 * Generate `testcases.json`
+	 */
+	await createTestcasesJson(allRulesTestcases)
+
+	console.info(`\nGenerated Test Cases.\n`)
+}
+
+/**
+ * Invoke
+ */
+init()
+	.then(() => console.log('Completed: task: create:testcases'))
+	.catch(e => {
+		console.error(e)
+		process.write(1)
+	})

build/get-implementation.js

@@ -0,0 +1,74 @@
+const assert = require('assert')
+const program = require('commander')
+const { version } = require('../package.json')
+const createFile = require('../utils/create-file')
+const getFramedReport = require('./implementations/get-framed-report')
+const getImplementationForReport = require('./implementations/get-implementation-for-report')
+
+/**
+ * Init
+ * @param {Object} program program
+ */
+const init = async program => {
+	const { org, tool, path } = program
+
+	/**
+	 * assert `args`
+	 */
+	assert(org, '`Organisation` is required')
+	assert(tool, '`tool` is required')
+	assert(path, '`path` is required')
+
+	console.info(`\nGet implementation of ${tool} by ${org}\n`)
+
+	/**
+	 * fetch `report` & `frame` as required
+	 */
+	const framedReport = await getFramedReport(path)
+
+	/**
+	 * Get `implementation`
+	 */
+	const data = await getImplementationForReport(framedReport)
+
+	/**
+	 * create report
+	 */
+	const report = {
+		organisation: org,
+		tool,
+		data,
+	}
+
+	/**
+	 * Save `implementation` to `_data/implementations`
+	 */
+	const filename = tool
+		.split(' ')
+		.join('-')
+		.toLowerCase()
+	await createFile(
+		`_data/implementations/${filename}.json`,
+		JSON.stringify(report, null, 2)
+	)
+}
+
+/**
+ * Parse `args`
+ */
+program
+	.version(version)
+	.option('-o, --org <org>', 'Organisation, which created the EARL report')
+	.option('-t, --tool <tool>', 'Tool used by EARL report')
+	.option('-p, --path <path>', 'Path to EARL report')
+	.parse(process.argv)
+
+/**
+ * Init
+ */
+init(program)
+	.then(() => console.info(`\nImplementations data generated.\n`))
+	.catch(e => {
+		console.error(e)
+		process.exit(1)
+	})