feat: Don’t open duplicate issues for repeat findings (#11)

Fixes github/accessibility#9205 (Hubber access
only)

This PR prevents duplicate issues from being opened when findings are
rediscovered in subsequent runs. This is accomplished by caching the
findings (with issue URLs) that are outputted by the ‘file’ action,
using a newly-added
[`gh-cache/cache`](https://github.com/github/continuous-accessibility-scanner/tree/smockle/cache-findings/.github/actions/gh-cache/cache)
action[^1].

I tested these changes by running this branch’s
`continuous-accessibility-scanner` action twice:

The first run—[github/accessibility-sandbox’s
run/16838980870](https://github.com/github/accessibility-sandbox/actions/runs/16838980870/job/47705300589)
(Hubber access only)—logged `Created issue: Accessibility issue: Links
must have discernible text on /octicons/
(github/accessibility-sandbox#4373)` (on line 312), created
[github/accessibility-sandbox#4373](github/accessibility-sandbox#4373)
(Hubber access only)), and saved a reference to that issue in
[github/accessibility-sandbox’s `gh-cache` branch’s
`cached_findings-main`](https://github.com/github/accessibility-sandbox/blob/gh-cache/cached_findings-main)
(Hubber access only).

The second run—[github/accessibility-sandbox’s
run/16839227092](https://github.com/github/accessibility-sandbox/actions/runs/16839227092/job/47706132729)
(Hubber access only)—logged `Repeated issue: Accessibility issue: Links
must have discernible text on /octicons/
(github/accessibility-sandbox#4373)` (on line 310), and _didn’t_ create
another issue.

[^1]: `gh-cache/cache` itself uses newly-added
[`gh-cache/save`](https://github.com/github/continuous-accessibility-scanner/tree/smockle/cache-findings/.github/actions/gh-cache/save)
and
[`gh-cache/restore`](https://github.com/github/continuous-accessibility-scanner/tree/smockle/cache-findings/.github/actions/gh-cache/restore)
actions.

Author: smockle

.github/actions/file/README.md

@@ -22,8 +22,28 @@ Files GitHub issues to track potential accessibility gaps.
 
 **Required** Token with fine-grained permission 'issues: write'.
 
+#### `cached_findings`
+
+**Optional** Cached findings from previous runs, as stringified JSON. Without this, duplicate issues may be filed. For example: `'[]'`.
+
 ### Outputs
 
-#### `issue_numbers`
+#### `findings`
+
+List of potential accessibility gaps (plus issue URLs), as stringified JSON. For example:
+
+```JS
+'[]'
+```
+
+#### `closed_issue_urls`
+
+List of URLs for closed issues, as stringified JSON. For example: `'["https://github.com/github/docs/issues/123","https://github.com/github/docs/issues/124","https://github.com/github/docs/issues/126","https://github.com/github/docs/issues/127"]'`.
+
+#### `opened_issue_urls`
+
+List of URLs for newly-opened issues, as stringified JSON. For example: `'["https://github.com/github/docs/issues/123","https://github.com/github/docs/issues/124","https://github.com/github/docs/issues/126","https://github.com/github/docs/issues/127"]'`.
+
+#### `repeated_issue_urls`
 
-List of issue numbers for created issues, as stringified JSON. For example: `'[123, 124, 126, 127]'`.
+List of URLs for repeated issues, as stringified JSON. For example: `'["https://github.com/github/docs/issues/123","https://github.com/github/docs/issues/124","https://github.com/github/docs/issues/126","https://github.com/github/docs/issues/127"]'`.

.github/actions/file/action.yml

@@ -11,10 +11,19 @@ inputs:
   token:
     description: "Token with fine-grained permission 'issues: write'"
     required: true
+  cached_findings:
+    description: "Cached findings from previous runs, as stringified JSON. Without this, duplicate issues may be filed."
+    required: false
 
 outputs:
-  issue_numbers:
-    description: "List of issue numbers for created issues, as stringified JSON"
+  findings:
+    description: "List of potential accessibility gaps (plus issue URLs), as stringified JSON"
+  closed_issue_urls:
+    description: "List of URLs for closed issues, as stringified JSON"
+  opened_issue_urls:
+    description: "List of URLs for newly-opened issues, as stringified JSON"
+  repeated_issue_urls:
+    description: "List of URLs for repeated issues, as stringified JSON"
 
 runs:
   using: "node20"

.github/actions/file/bootstrap.js

@@ -5,12 +5,14 @@ import fs from 'node:fs'
 import * as url from 'node:url'
 import { spawn } from 'node:child_process'
 
-function spawnPromisified(command, args, options) {
+function spawnPromisified(command, args, { quiet = false, ...options } = {}) {
   return new Promise((resolve, reject) => {
     const proc = spawn(command, args, options)
     proc.stdout.setEncoding('utf8')
     proc.stdout.on('data', (data) => {
-      console.log(data)
+      if (!quiet) {
+        console.log(data)
+      }
     })
     proc.stderr.setEncoding('utf8')
     proc.stderr.on('data', (data) => {
@@ -36,7 +38,8 @@ await (async () => {
   } catch {
     try {
       await spawnPromisified('npm', ['ci'], {
-        cwd: url.fileURLToPath(new URL('.', import.meta.url))
+        cwd: url.fileURLToPath(new URL('.', import.meta.url)),
+        quiet: true
       })
     } catch {
       process.exit(1)
@@ -45,7 +48,8 @@ await (async () => {
     // Compile TypeScript.
     try {
       await spawnPromisified('npm', ['run', 'build'], {
-        cwd: url.fileURLToPath(new URL('.', import.meta.url))
+        cwd: url.fileURLToPath(new URL('.', import.meta.url)),
+        quiet: true
       })
     } catch {
       process.exit(1)

.github/actions/file/src/closeIssueForFinding.ts

@@ -0,0 +1,17 @@
+import type { Octokit } from '@octokit/core';
+import type { Finding } from './types.d.js';
+
+export async function closeIssueForFinding(octokit: Octokit, repoWithOwner: string, finding: Finding) {
+  const owner = repoWithOwner.split('/')[0];
+  const repo = repoWithOwner.split('/')[1];
+  const issueNumber = finding.issueUrl?.split('/').pop();
+  if (!issueNumber) {
+    throw new Error(`Invalid issue URL: ${finding.issueUrl}`);
+  }
+  return octokit.request(`PATCH /repos/${owner}/${repo}/issues/${issueNumber}`, {
+    owner,
+    repo,
+    issue_number: issueNumber,
+    state: 'closed'
+  });
+}

.github/actions/file/src/fileIssueForFinding.ts

@@ -1,20 +1,68 @@
 import type { Finding } from "./types.d.js";
 import core from "@actions/core";
 import { Octokit } from '@octokit/core';
-import { fileIssueForFinding } from "./fileIssueForFinding.js";
+import { toFindingsMap } from "./toFindingsMap.js"
+import { closeIssueForFinding } from "./closeIssueForFinding.js";
+import { openIssueForFinding } from "./openIssueForFinding.js";
 
 export default async function () {
+  core.info("Started 'file' action");
   const findings: Finding[] = JSON.parse(core.getInput('findings', { required: true }));
   const repoWithOwner = core.getInput('repository', { required: true });
   const token = core.getInput('token', { required: true });
+  const cachedFindings: Finding[] = JSON.parse(core.getInput('cached_findings', { required: false }) || "[]");
+  core.debug(`Input: 'findings: ${JSON.stringify(findings)}'`);
+  core.debug(`Input: 'repository: ${repoWithOwner}'`);
+  core.debug(`Input: 'cached_findings: ${JSON.stringify(cachedFindings)}'`);
+
+  const findingsMap = toFindingsMap(findings);
+  const cachedFindingsMap = toFindingsMap(cachedFindings);
 
-  const issueNumbers = [];
   const octokit = new Octokit({ auth: token });
+  const closedIssueUrls = [];
+  const openedIssueUrls = [];
+  const repeatIssueUrls = [];
+
+  for (const cachedFinding of cachedFindings) {
+    if (!findingsMap.has(`${cachedFinding.url};${cachedFinding.problemShort};${cachedFinding.html}`)) {
+      try {
+        // Finding was not found in the latest run, so close its issue (if necessary)
+        const response = await closeIssueForFinding(octokit, repoWithOwner, cachedFinding);
+        closedIssueUrls.push(response.data.html_url);
+        core.info(`Closed issue: ${response.data.title} (${repoWithOwner}#${response.data.number})`);
+      } catch (error) {
+        core.error(`Failed to close issue for finding: ${error}`);
+      }
+    }
+  }
+
   for (const finding of findings) {
-    const response = await fileIssueForFinding(octokit, repoWithOwner, finding);
-    issueNumbers.push(response.data.number);
-    console.log(`Created issue: ${response.data.title} (${repoWithOwner}#${response.data.number})`);
+    const cachedIssueUrl = cachedFindingsMap.get(`${finding.url};${finding.problemShort};${finding.html}`)?.issueUrl
+    finding.issueUrl = cachedIssueUrl;
+    try {
+      const response = await openIssueForFinding(octokit, repoWithOwner, finding);
+      finding.issueUrl = response.data.html_url;
+      if (response.data.html_url === cachedIssueUrl) {
+        // Finding was found in previous and latest runs, so reopen its issue (if necessary)
+        repeatIssueUrls.push(response.data.html_url);
+        core.info(`Repeated issue: ${response.data.title} (${repoWithOwner}#${response.data.number})`);
+      } else {
+        // New finding was found in the latest run, so create its issue
+        openedIssueUrls.push(response.data.html_url);
+        core.info(`Created issue: ${response.data.title} (${repoWithOwner}#${response.data.number})`);
+      }
+    } catch (error) {
+      core.error(`Failed to open/reopen issue for finding: ${error}`);
+    }
   }
 
-  core.setOutput("issue_numbers", JSON.stringify(issueNumbers));
-}
+  core.setOutput("closed_issue_urls", JSON.stringify(closedIssueUrls));
+  core.setOutput("opened_issue_urls", JSON.stringify(openedIssueUrls));
+  core.setOutput("repeated_issue_urls", JSON.stringify(repeatIssueUrls));
+  core.setOutput("findings", JSON.stringify(findings));
+  core.debug(`Output: 'closed_issue_urls: ${JSON.stringify(closedIssueUrls)}'`);
+  core.debug(`Output: 'opened_issue_urls: ${JSON.stringify(openedIssueUrls)}'`);
+  core.debug(`Output: 'repeated_issue_urls: ${JSON.stringify(repeatIssueUrls)}'`);
+  core.debug(`Output: 'findings: ${JSON.stringify(findings)}'`);
+  core.info("Finished 'file' action");
+}

.github/actions/file/src/index.ts

@@ -0,0 +1,45 @@
+import type { Octokit } from '@octokit/core';
+import type { Finding } from './types.d.js';
+import * as url from 'node:url'
+const URL = url.URL;
+
+export async function openIssueForFinding(octokit: Octokit, repoWithOwner: string, finding: Finding) {
+  const owner = repoWithOwner.split('/')[0];
+  const repo = repoWithOwner.split('/')[1];
+  const issueNumber = finding.issueUrl?.split('/').pop();
+  if (issueNumber) {
+    // If an issue already exists, ensure it is open
+    return octokit.request(`PATCH /repos/${owner}/${repo}/issues/${issueNumber}`, {
+      owner,
+      repo,
+      issue_number: issueNumber,
+      state: 'open'
+    });
+  } else {
+    // Otherwise, create a new issue
+    const title = `Accessibility issue: ${finding.problemShort[0].toUpperCase() + finding.problemShort.slice(1)} on ${new URL(finding.url).pathname}`;
+    const solutionLong = finding.solutionLong
+      ?.split("\n")
+      .map((line) =>
+        !line.trim().startsWith("Fix any") &&
+        !line.trim().startsWith("Fix all") &&
+        line.trim() !== ""
+          ? `- ${line}`
+          : line
+      )
+      .join("\n");
+    const body = `
+An accessibility scan flagged the element \`${finding.html}\` on ${finding.url} because ${finding.problemShort}. Learn more about why this was flagged by visiting ${finding.problemUrl}.
+
+To fix this, ${finding.solutionShort}.
+${solutionLong ? `\nSpecifically:\n\n${solutionLong}` : ''}
+`;
+
+    return octokit.request(`POST /repos/${owner}/${repo}/issues`, {
+      owner,
+      repo,
+      title,
+      body
+    });
+  }
+}

.github/actions/file/src/openIssueForFinding.ts

@@ -0,0 +1,10 @@
+import type {Finding} from "./types.d.js";
+
+export function toFindingsMap(findings: Finding[]): Map<string, Finding> {
+  const map = new Map<string, Finding>();
+  for (const finding of findings) {
+    const key = `${finding.url};${finding.problemShort};${finding.html}`;
+    map.set(key, finding);
+  }
+  return map;
+}

.github/actions/file/src/toFindingsMap.ts

@@ -5,4 +5,5 @@ export type Finding = {
   problemUrl: string;
   solutionShort: string;
   solutionLong?: string;
+  issueUrl?: string;
 }

.github/actions/file/src/types.d.ts

@@ -5,12 +5,14 @@ import fs from 'node:fs'
 import * as url from 'node:url'
 import { spawn } from 'node:child_process'
 
-function spawnPromisified(command, args, options) {
+function spawnPromisified(command, args, { quiet = false, ...options } = {}) {
   return new Promise((resolve, reject) => {
     const proc = spawn(command, args, options)
     proc.stdout.setEncoding('utf8')
     proc.stdout.on('data', (data) => {
-      console.log(data)
+      if (!quiet) {
+        console.log(data)
+      }
     })
     proc.stderr.setEncoding('utf8')
     proc.stderr.on('data', (data) => {
@@ -36,7 +38,8 @@ await (async () => {
   } catch {
     try {
       await spawnPromisified('npm', ['ci'], {
-        cwd: url.fileURLToPath(new URL('.', import.meta.url))
+        cwd: url.fileURLToPath(new URL('.', import.meta.url)),
+        quiet: true
       })
     } catch {
       process.exit(1)
@@ -45,7 +48,8 @@ await (async () => {
     // Compile TypeScript.
     try {
       await spawnPromisified('npm', ['run', 'build'], {
-        cwd: url.fileURLToPath(new URL('.', import.meta.url))
+        cwd: url.fileURLToPath(new URL('.', import.meta.url)),
+        quiet: true
       })
     } catch {
       process.exit(1)