Merge pull request #87 from mgifford/copilot/update-axe-rules-yaml

Add axe rule human-impact YAML, policy narratives in report, and bi-annual freshness workflow

Author: mgifford

.github/workflows/check-axe-rules.yml

@@ -0,0 +1,138 @@
+name: Axe Rules Freshness Check
+
+on:
+  schedule:
+    # Run twice a year: March 20 and September 20 at 09:00 UTC
+    - cron: '0 9 20 3 *'
+    - cron: '0 9 20 9 *'
+  workflow_dispatch:
+    inputs:
+      check_date:
+        description: 'Override check date (YYYY-MM-DD, defaults to today)'
+        required: false
+        type: string
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  check-axe-rules-freshness:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check axe rules data freshness
+        id: freshness
+        shell: bash
+        run: |
+          CHECK_DATE="${{ inputs.check_date }}"
+          if [[ -z "$CHECK_DATE" ]]; then
+            CHECK_DATE=$(date -u +%Y-%m-%d)
+          fi
+          echo "check_date=$CHECK_DATE" >> "$GITHUB_OUTPUT"
+
+          node --input-type=module <<'EOF'
+          import { getAxeImpactMetadata, isAxeImpactDataStale } from './src/data/axe-impact-loader.js';
+
+          const checkDate = process.env.CHECK_DATE || new Date().toISOString().slice(0, 10);
+          const metadata = getAxeImpactMetadata();
+          const stale = isAxeImpactDataStale(checkDate);
+
+          console.log('YAML axe_version:      ', metadata.axe_version);
+          console.log('YAML last_updated:     ', metadata.last_updated);
+          console.log('YAML next_review_date: ', metadata.next_review_date);
+          console.log('Check date:            ', checkDate);
+          console.log('Is stale:              ', stale);
+
+          if (stale) {
+            console.log('::warning::Axe impact rules data in src/data/axe-impact-rules.yaml is past its review date. Please review and update the YAML data.');
+            process.exitCode = 1;
+          } else {
+            console.log('Axe impact rules data is current. No action needed.');
+          }
+          EOF
+        env:
+          CHECK_DATE: ${{ steps.freshness.outputs.check_date }}
+
+      - name: Check for new axe-core rules
+        id: new-rules
+        if: success() || failure()
+        shell: bash
+        run: |
+          node src/cli/update-axe-rules.js --list-new > /tmp/new-rules-output.txt 2>&1 || true
+          cat /tmp/new-rules-output.txt
+
+          if grep -q 'missing from axe-impact-rules.yaml' /tmp/new-rules-output.txt; then
+            echo "has_new_rules=true" >> "$GITHUB_OUTPUT"
+            # Extract the missing rule IDs
+            MISSING=$(grep '  - ' /tmp/new-rules-output.txt | sed 's/  - //' | tr '\n' ', ' | sed 's/,$//')
+            echo "missing_rules=${MISSING}" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_new_rules=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Open issue if axe rules data is stale or has new rules
+        if: |
+          (failure() && steps.freshness.conclusion == 'failure') ||
+          steps.new-rules.outputs.has_new_rules == 'true'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: issues } = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              labels: 'axe-rules-review',
+              state: 'open'
+            });
+
+            if (issues.length > 0) {
+              console.log('An open axe rules review issue already exists:', issues[0].html_url);
+              return;
+            }
+
+            const hasNewRules = '${{ steps.new-rules.outputs.has_new_rules }}' === 'true';
+            const missingRules = '${{ steps.new-rules.outputs.missing_rules }}';
+            const metadata_section = hasNewRules
+              ? `\n\n### New Rules Detected\n\nThe following axe-core rules do not yet have policy narrative entries in \`src/data/axe-impact-rules.yaml\`:\n\n\`\`\`\n${missingRules}\n\`\`\`\n\nAdd entries for these rules following the existing YAML structure in \`src/data/axe-impact-rules.yaml\`.`
+              : '';
+
+            const { data: issue } = await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: 'Bi-annual review: Update axe-core rule impact data',
+              labels: ['axe-rules-review'],
+              body: `## Axe Rules Impact Data Review Required
+
+            The scheduled freshness check has detected that the axe-core rule impact data in [\`src/data/axe-impact-rules.yaml\`](../blob/main/src/data/axe-impact-rules.yaml) needs review.
+
+            ### Action Required
+
+            1. Check the latest axe-core rule documentation:
+               - [axe-core rules reference](https://dequeuniversity.com/rules/axe/html/4.11)
+               - Compare with the installed version by running: \`node src/cli/update-axe-rules.js --check --list-new\`
+
+            2. Update \`src/data/axe-impact-rules.yaml\`:
+               - Update \`metadata.axe_version\` to match the installed axe-core version
+               - Update \`metadata.last_updated\` to today's date
+               - Update \`metadata.next_review_date\` to 6 months from today
+               - Add or update \`technical_summary\` for any changed rules
+               - Add \`policy_narrative\` entries for any new rules${metadata_section}
+
+            3. Run \`npm test\` to verify no tests are broken.
+
+            See [\`src/data/axe-impact-rules.yaml\`](../blob/main/src/data/axe-impact-rules.yaml) for the current version and review dates.
+            `
+            });
+
+            console.log('Created issue:', issue.html_url);

src/cli/update-axe-rules.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// Script to check and update axe-core rule impact data.
+//
+// Usage:
+//   node src/cli/update-axe-rules.js --check
+//     Checks whether the installed axe-core version matches the YAML metadata
+//     and whether the review date has passed. Exits with code 1 if stale.
+//
+//   node src/cli/update-axe-rules.js --list-new
+//     Lists any axe-core rule IDs that appear in the installed axe-core but
+//     are not yet present in axe-impact-rules.yaml.
+//
+// This script is intended to be run by the GitHub Actions workflow
+// check-axe-rules.yml, which runs on a schedule every 6 months.
+
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+import { getAxeImpactMetadata, getAxeImpactRuleMap, isAxeImpactDataStale } from '../data/axe-impact-loader.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+const args = process.argv.slice(2);
+const isCheck = args.includes('--check');
+const isListNew = args.includes('--list-new');
+
+if (!isCheck && !isListNew) {
+  console.error('Usage: node src/cli/update-axe-rules.js [--check] [--list-new]');
+  process.exit(1);
+}
+
+// Load installed axe-core metadata
+let axeVersion = 'unknown';
+let installedRuleIds = [];
+try {
+  const axePkg = require('axe-core/package.json');
+  axeVersion = axePkg.version;
+  const axe = require('axe-core');
+  installedRuleIds = axe.getRules().map((r) => r.ruleId);
+} catch (err) {
+  console.warn('Warning: could not load axe-core:', err.message);
+}
+
+const metadata = getAxeImpactMetadata();
+const ruleMap = getAxeImpactRuleMap();
+
+console.log('=== Axe Rule Impact Data Check ===');
+console.log(`YAML axe_version:       ${metadata.axe_version ?? '(none)'}`);
+console.log(`Installed axe-core:     ${axeVersion}`);
+console.log(`YAML last_updated:      ${metadata.last_updated ?? '(none)'}`);
+console.log(`YAML next_review_date:  ${metadata.next_review_date ?? '(none)'}`);
+console.log(`YAML rules count:       ${ruleMap.size}`);
+console.log(`Installed rules count:  ${installedRuleIds.length}`);
+console.log('');
+
+let exitCode = 0;
+
+if (isCheck) {
+  const today = new Date().toISOString().slice(0, 10);
+  const stale = isAxeImpactDataStale(today);
+
+  if (stale) {
+    console.log(`\u26a0\ufe0f  Review date (${metadata.next_review_date}) has passed. YAML data is stale.`);
+    exitCode = 1;
+  }
+
+  // Check whether the YAML axe_version major.minor matches installed
+  const yamlMajorMinor = (metadata.axe_version ?? '').split('.').slice(0, 2).join('.');
+  const installedMajorMinor = axeVersion.split('.').slice(0, 2).join('.');
+  if (axeVersion !== 'unknown' && yamlMajorMinor !== installedMajorMinor) {
+    console.log(`\u26a0\ufe0f  YAML axe_version (${metadata.axe_version}) does not match installed axe-core (${axeVersion}).`);
+    exitCode = 1;
+  }
+
+  if (exitCode === 0) {
+    console.log('\u2705 Axe impact data is current. No action needed.');
+  }
+}
+
+if (isListNew) {
+  const missingFromYaml = installedRuleIds.filter((id) => !ruleMap.has(id));
+
+  if (missingFromYaml.length === 0) {
+    console.log('\u2705 All installed axe-core rules are present in axe-impact-rules.yaml.');
+  } else {
+    console.log(`\u26a0\ufe0f  ${missingFromYaml.length} rule(s) in axe-core but missing from axe-impact-rules.yaml:`);
+    for (const id of missingFromYaml) {
+      console.log(`  - ${id}`);
+    }
+    exitCode = 1;
+  }
+}
+
+process.exitCode = exitCode;

src/data/axe-impact-loader.js

@@ -0,0 +1,98 @@
+// Loader for axe-core rule impact mappings.
+//
+// Reads src/data/axe-impact-rules.yaml and provides lookup functions
+// for policy narratives by rule ID.
+//
+// The YAML is parsed once at module load time and cached for performance.
+//
+// Review schedule: The YAML data should be refreshed every 6 months to keep
+// pace with axe-core releases. Run the check-axe-rules workflow or execute
+// `node src/cli/update-axe-rules.js --check` to verify currency.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { load as yamlLoad } from 'js-yaml';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const YAML_PATH = join(__dirname, 'axe-impact-rules.yaml');
+
+let _parsed = null;
+
+function getParsed() {
+  if (!_parsed) {
+    const raw = readFileSync(YAML_PATH, 'utf8');
+    _parsed = yamlLoad(raw);
+  }
+  return _parsed;
+}
+
+/**
+ * Returns the full parsed YAML document including metadata and rules array.
+ *
+ * @returns {{ metadata: object, rules: Array }}
+ */
+export function getAxeImpactRules() {
+  return getParsed();
+}
+
+/**
+ * Returns a Map<string, object> from rule_id to the rule entry object.
+ * Cached after first call.
+ *
+ * @returns {Map<string, object>}
+ */
+let _ruleMap = null;
+export function getAxeImpactRuleMap() {
+  if (!_ruleMap) {
+    const { rules = [] } = getParsed();
+    _ruleMap = new Map(rules.map((r) => [r.rule_id, r]));
+  }
+  return _ruleMap;
+}
+
+/**
+ * Returns the policy narrative object for a given axe rule ID,
+ * or null if no entry exists.
+ *
+ * @param {string} ruleId - axe-core rule ID (e.g. "color-contrast")
+ * @returns {{ title: string, why_it_matters: string, affected_demographics: string[] } | null}
+ */
+export function getPolicyNarrative(ruleId) {
+  const entry = getAxeImpactRuleMap().get(ruleId);
+  return entry?.policy_narrative ?? null;
+}
+
+/**
+ * Returns the technical summary string for a given axe rule ID,
+ * or null if no entry exists.
+ *
+ * @param {string} ruleId - axe-core rule ID
+ * @returns {string | null}
+ */
+export function getTechnicalSummary(ruleId) {
+  const entry = getAxeImpactRuleMap().get(ruleId);
+  return entry?.technical_summary ?? null;
+}
+
+/**
+ * Returns the metadata block from the YAML (axe_version, last_updated, next_review_date).
+ *
+ * @returns {{ axe_version: string, last_updated: string, next_review_date: string, source_url: string }}
+ */
+export function getAxeImpactMetadata() {
+  return getParsed().metadata ?? {};
+}
+
+/**
+ * Returns true if the review date is in the past relative to checkDate.
+ *
+ * @param {string} [checkDate] - ISO date string (YYYY-MM-DD), defaults to today
+ * @returns {boolean}
+ */
+export function isAxeImpactDataStale(checkDate) {
+  const today = checkDate ?? new Date().toISOString().slice(0, 10);
+  const { next_review_date } = getAxeImpactMetadata();
+  if (!next_review_date) return false;
+  return today >= next_review_date;
+}