Incorporate #1800 feedback and simplify the code.

Co-authored-by: Eric Arellano <[email protected]>
Co-authored-by: Shraddha Aangiras <[email protected]>

README.md

@@ -289,6 +289,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 defined.
+
+You can check it locally by running:
+
+```bash
+# Only check alt text
+npm run check:alt-text
+
+# Or, run all the checks
+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.

scripts/js/commands/checkAltText.ts

@@ -11,7 +11,7 @@
 // that they have been altered from the originals.
 
 import { globby } from "globby";
-import { Image, extractMarkdownImages } from "../lib/extractMarkdownImages.js";
+import { findImagesWithoutAltText } from "../lib/extractMarkdownImages.js";
 import { readMarkdown } from "../lib/markdownReader.js";
 
 async function main() {
@@ -20,22 +20,19 @@ async function main() {
 
   for (const file of files) {
     const markdown = await readMarkdown(file);
-    const images: Image[] = await extractMarkdownImages(markdown);
-    const imageErrors = images.flatMap((image: Image) =>
-      image.altText
-        ? []
-        : `The image '${image.imageName}' does not have an alt text defined.`,
+    const images = await findImagesWithoutAltText(markdown);
+    const imageErrors = [...images].map(
+      (image) => `The image '${image}' does not have an alt text defined.`,
     );
-    const imageErrorsDeduplicated = new Set(imageErrors);
 
-    if (imageErrorsDeduplicated.size > 0) {
+    if (imageErrors.length) {
       fileErrors.push(
-        `Error in file '${file}':\n\t- ${[...imageErrorsDeduplicated].join("\n\t- ")}`,
+        `Error in file '${file}':\n\t- ${imageErrors.join("\n\t- ")}`,
       );
     }
   }
 
-  if (fileErrors.length > 0) {
+  if (fileErrors.length) {
     fileErrors.forEach((error) => console.log(error));
     console.error("\nSome images are missing alt text 💔\n");
     process.exit(1);

scripts/js/lib/extractMarkdownImages.test.ts

@@ -12,7 +12,7 @@
 
 import { expect, test } from "@playwright/test";
 
-import { extractMarkdownImages } from "./extractMarkdownImages.js";
+import { findImagesWithoutAltText } from "./extractMarkdownImages.js";
 
 test("Test the extraction of the images", async () => {
   const markdown = `
@@ -24,15 +24,17 @@ test("Test the extraction of the images", async () => {
 
 ![Here's another valid image](/images/img2.png)
 
+![](/images/invalid_img2.png)
+
+![](/images/invalid_img2.png)
+
 ![And now, our last link](https://ibm.com)
     `;
-  const images = await extractMarkdownImages(markdown);
-  const correct_images = [
-    { imageName: "/images/img1.png", altText: "Our first image with alt text" },
-    { imageName: "/images/invalid_img1.png", altText: "" },
-    { imageName: "/images/img2.png", altText: "Here's another valid image" },
-    { imageName: "https://ibm.com", altText: "And now, our last link" },
-  ];
+  const images = await findImagesWithoutAltText(markdown);
+  const correct_images = new Set([
+    "/images/invalid_img1.png",
+    "/images/invalid_img2.png",
+  ]);
 
   expect(images).toEqual(correct_images);
 });

scripts/js/lib/extractMarkdownImages.ts

@@ -17,23 +17,20 @@ import remarkParse from "remark-parse";
 import remarkGfm from "remark-gfm";
 import remarkStringify from "remark-stringify";
 
-export interface Image {
-  imageName: string;
-  altText: string | null;
-}
-
-export async function extractMarkdownImages(
+export async function findImagesWithoutAltText(
   markdown: string,
-): Promise<Image[]> {
-  const images: Image[] = [];
+): Promise<Set<string>> {
+  const images = new Set<string>();
 
   await unified()
     .use(remarkParse)
     .use(remarkGfm)
     .use(() => (tree: Root) => {
-      visit(tree, "image", (node) =>
-        images.push({ imageName: node.url, altText: node.alt } as Image),
-      );
+      visit(tree, "image", (node) => {
+        if (!node.alt) {
+          images.add(node.url);
+        }
+      });
     })
     .use(remarkStringify)
     .process(markdown);