⚠️ Add warnings for missing alt-text and auto-generated alt-text

.changeset/big-cooks-admire.md

@@ -0,0 +1,6 @@
+---
+"myst-transforms": patch
+"myst-common": patch
+---
+
+Add warnings for missing alt-text and auto-generated alt-text.

packages/myst-common/src/ruleids.ts

@@ -48,6 +48,8 @@ export enum RuleId {
   imageFormatConverts = 'image-format-converts',
   imageCopied = 'image-copied',
   imageFormatOptimizes = 'image-format-optimizes',
+  imageHasAltText = 'image-has-alt-text',
+  imageAltTextGenerated = 'image-alt-text-generated',
   // Math rules
   mathLabelLifted = 'math-label-lifted',
   mathEquationEnvRemoved = 'math-equation-env-removed',

packages/myst-transforms/src/basic.ts

@@ -7,7 +7,7 @@ import { captionParagraphTransform } from './caption.js';
 import { admonitionBlockquoteTransform, admonitionHeadersTransform } from './admonitions.js';
 import { blockMetadataTransform, blockNestingTransform, blockToFigureTransform } from './blocks.js';
 import { htmlIdsTransform } from './htmlIds.js';
-import { imageAltTextTransform } from './images.js';
+import { imageAltTextTransform, imageNoAltTextTransform } from './images.js';
 import { mathLabelTransform, mathNestingTransform, subequationTransform } from './math.js';
 import { blockquoteTransform } from './blockquote.js';
 import { codeBlockToDirectiveTransform, inlineCodeFlattenTransform } from './code.js';
@@ -40,6 +40,7 @@ export function basicTransformations(tree: GenericParent, file: VFile, opts?: Re
   containerChildrenTransform(tree, file);
   htmlIdsTransform(tree);
   imageAltTextTransform(tree);
+  imageNoAltTextTransform(tree, file);
   blockquoteTransform(tree);
   removeUnicodeTransform(tree);
   headingDepthTransform(tree, file, opts);

packages/myst-transforms/src/images.ts

@@ -1,8 +1,11 @@
 import type { Plugin } from 'unified';
 import type { Container, Paragraph, PhrasingContent, Image } from 'myst-spec';
+import type { VFile } from 'vfile';
 import { select, selectAll } from 'unist-util-select';
 import type { GenericParent } from 'myst-common';
-import { toText } from 'myst-common';
+import { fileWarn, toText, RuleId } from 'myst-common';
+
+const TRANSFORM_SOURCE = 'myst-transforms:images';
 
 /**
  * Generate image alt text from figure caption
@@ -29,6 +32,28 @@ export function imageAltTextTransform(tree: GenericParent) {
   });
 }
 
-export const imageAltTextPlugin: Plugin<[], GenericParent, GenericParent> = () => (tree) => {
+export function imageNoAltTextTransform(tree: GenericParent, file: VFile) {
+  const imageNodes = selectAll('image', tree) as Image[];
+  imageNodes.forEach((image, index) => {
+    if (image.alt == null) {
+      fileWarn(file, `missing alt text for ${image.url}`, {
+        ruleId: RuleId.imageHasAltText,
+        node: image,
+        source: TRANSFORM_SOURCE,
+      });
+    }
+    if (image.data?.altTextIsAutoGenerated) {
+      fileWarn(file, `alt text for ${image.url} was auto-generated`, {
+        ruleId: RuleId.imageAltTextGenerated,
+        node: image,
+        source: TRANSFORM_SOURCE,
+        note: 'You can remove this warning by writing your own altxtext',
+      });
+    }
+  });
+}
+
+export const imageAltTextPlugin: Plugin<[], GenericParent, GenericParent> = () => (tree, file) => {
   imageAltTextTransform(tree);
+  imageNoAltTextTransform(tree, file);
 };