[wip] Check images for alt text

.github/workflows/main.yml

@@ -28,6 +28,8 @@ jobs:
 
       - name: File metadata
         run: npm run check:metadata
+      - name: Check image alt text
+        run: npm run check:alt-text
       - name: Spellcheck
         run: npm run check:spelling
       - name: Check Qiskit bot config

README.md

@@ -284,6 +284,20 @@ npm run check:metadata -- --apis
 npm run check
 ```
 
+## Check image alt text
+
+Every image needs to have `alt text` for accessibility. The `lint` job in CI will fail if images do not have alt text.
+
+You can also check for valid metadata locally:
+
+```bash
+# Only check file metadata
+npm run check:alt-text
+
+# Or, run all the checks. Although this only checks non-API docs.
+npm run check
+```
+
 ## Spellcheck
 
 We use [cSpell](https://cspell.org) to check for spelling. The `lint` job in CI will fail if there are spelling issues.

package.json

@@ -15,8 +15,9 @@
     "fmt": "prettier --write .",
     "test": "playwright test",
     "typecheck": "tsc",
-    "check": "npm run check:qiskit-bot && npm run check:patterns-index && npm run check:metadata && npm run check:spelling && npm run check:internal-links && npm run check:orphan-pages && npm run check:fmt",
+    "check": "npm run check:qiskit-bot && npm run check:patterns-index && npm run check:alt-text && npm run check:metadata && npm run check:spelling && npm run check:internal-links && npm run check:orphan-pages && npm run check:fmt",
     "check:metadata": "tsx scripts/js/commands/checkMetadata.ts",
+    "check:alt-text:": "tsx scripts/js/commands/checkAltText.ts",
     "check:spelling": "tsx scripts/js/commands/checkSpelling.ts",
     "check:fmt": "prettier --check .",
     "check:internal-links": "tsx scripts/js/commands/checkInternalLinks.ts",

scripts/js/commands/checkAltText.ts

@@ -0,0 +1,97 @@
+// This code is a Qiskit project.
+//
+// (C) Copyright IBM 2024.
+//
+// This code is licensed under the Apache License, Version 2.0. You may
+// obtain a copy of this license in the LICENSE file in the root directory
+// of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+//
+// Any modifications or derivative works of this code must retain this
+// copyright notice, and modified files need to carry a notice indicating
+// that they have been altered from the originals.
+
+import { globby } from "globby";
+import yargs from "yargs/yargs";
+import { hideBin } from "yargs/helpers";
+
+import { extractAlt } from "../lib/links/extractAltText.js";
+import { readMarkdown } from "../lib/markdownReader.js";
+
+interface Arguments {
+    [x: string]: unknown;
+  }
+
+const readArgs = (): Arguments => {
+    return yargs(hideBin(process.argv))
+      .version(false)
+      .parseSync();
+  };
+
+async function determineFiles(args: Arguments): Promise<[string[], string[]]> {
+  const mdGlobs = ["docs/guides/*.mdx", "docs/migration-guides/*.mdx"];
+  const notebookGlobs = ["docs/guides/*.ipynb", "docs/migration-guides/*.ipynb"];
+  return [await globby(mdGlobs), await globby(notebookGlobs)];
+}
+
+
+function getNullAlt(
+    alt: Set<string | null | undefined>, 
+    imgPath: Set<string>,
+    Err: string[]
+): void {
+    const altArray = Array.from(alt);
+    const imgArray = Array.from(imgPath);
+
+    altArray.forEach((alt, i) => {
+        if(alt===null) {
+            Err.push(imgArray[i]);
+        }
+    });
+}
+
+
+const main = async (): Promise<void> => {
+  const args = readArgs();
+  const [mdFiles, notebookFiles] = await determineFiles(args);
+
+  const mdErrors: string[] = [];
+  for (const file of mdFiles) {
+    const markdown = await readMarkdown(file);
+    const{ imageName, altText } = await extractAlt(markdown);
+    getNullAlt(altText, imageName, mdErrors);
+  }
+
+  const notebookErrors: string[] = [];
+  for (const file of notebookFiles) {
+    const markdown = await readMarkdown(file);
+    const{ imageName, altText } = await extractAlt(markdown);
+    getNullAlt(altText, imageName, notebookErrors);
+
+  }
+  handleErrors(mdErrors, notebookErrors);
+};
+
+function handleErrors(mdErrors: string[], notebookErrors: string[]): void {
+    if (mdErrors.length > 0) {
+        console.error(`
+            Image does not have alt text. Every image must have associated alt text like this:
+            ![Alt text goes here](/random-img.png) 
+
+            Please fix these images:\n\n${mdErrors.join("\n")}
+            `)
+    }
+    if (notebookErrors.length > 0) {
+        console.error(`
+            Image does not have alt text. Every image in markdown must have associated alt text like this:
+            ![Alt text goes here](/random-img.png) 
+
+            Please fix these images:\n\n${notebookErrors.join("\n")}
+            `);
+    }
+    if (mdErrors.length > 0 || notebookErrors.length > 0) {
+        process.exit(1);
+      }
+}
+
+main();
+

scripts/js/lib/links/extractAltText.test.ts

@@ -0,0 +1,36 @@
+// This code is a Qiskit project.
+//
+// (C) Copyright IBM 2024.
+//
+// This code is licensed under the Apache License, Version 2.0. You may
+// obtain a copy of this license in the LICENSE file in the root directory
+// of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+//
+// Any modifications or derivative works of this code must retain this
+// copyright notice, and modified files need to carry a notice indicating
+// that they have been altered from the originals.
+
+import { expect, test } from "@jest/globals";
+import { extractAlt, AltText } from "./extractAltText";
+
+test("extractAlt()", async () => {
+  const markdown = `
+    # A header
+    ![Our first image with alt text](/images/img1.png)
+
+    ![](/images/invalid_img1.png)
+
+    ![Here's another valid image](/images/img3.png)
+
+    ![](/images/invalid_img2.png)
+
+    ![And now, our last link](https://ibm.com)
+    `;
+  const{ imageName, altText } = await extractAlt(markdown);
+  expect(imageName).toEqual(
+    new Set(["/images/img1.png", "/images/invalid_img1.png", "/images/img3.png", "/images/invalid_img2.png", "https://ibm.com"]),
+  );
+  expect(altText).toEqual(
+    new Set(["Our first image with alt text", null, "Here's another valid image", null, "And now, our last link"]),
+  );
+});

scripts/js/lib/links/extractAltText.ts

@@ -0,0 +1,49 @@
+// This code is a Qiskit project.
+//
+// (C) Copyright IBM 2024.
+//
+// This code is licensed under the Apache License, Version 2.0. You may
+// obtain a copy of this license in the LICENSE file in the root directory
+// of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+//
+// Any modifications or derivative works of this code must retain this
+// copyright notice, and modified files need to carry a notice indicating
+// that they have been altered from the originals.
+
+import { visit } from "unist-util-visit";
+import { unified } from "unified";
+import { Root } from "remark-mdx";
+import remarkStringify from "remark-stringify";
+import rehypeRemark from "rehype-remark";
+import rehypeParse from "rehype-parse";
+import remarkGfm from "remark-gfm";
+
+export interface AltText {
+  imageName: Set<string>; 
+  altText: Set<string | null | undefined>;
+};
+
+
+export async function extractAlt(
+  markdown: string,
+): Promise<AltText> {
+  const imageName = new Set<string>();
+  const altText = new Set<string | null | undefined>();
+
+  const getAlt = (link: string, a: string | null | undefined): void => {
+    imageName.add(link);
+    altText.add(a);
+  };
+
+  await unified()
+    .use(rehypeParse)
+    .use(remarkGfm)
+    .use(rehypeRemark)
+    .use(() => (tree: Root) => {
+      visit(tree, "image", (TreeNode) => getAlt(TreeNode.url, TreeNode.alt));
+    })
+    .use(remarkStringify)
+    .process(markdown);
+
+  return { imageName, altText };
+}