@mintlify/cli 4.0.739 → 4.0.740

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.739",
+  "version": "4.0.740",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -53,8 +53,11 @@
     "ink": "^6.0.1",
     "inquirer": "^12.3.0",
     "js-yaml": "^4.1.0",
+    "mdast": "^3.0.0",
+    "mdast-util-mdx-jsx": "^3.2.0",
     "react": "^19.1.0",
     "semver": "^7.7.2",
+    "unist-util-visit": "^5.0.0",
     "yargs": "^17.6.0"
   },
   "devDependencies": {
@@ -75,5 +78,5 @@
     "vitest": "^2.0.4",
     "vitest-mock-process": "^1.0.4"
   },
-  "gitHead": "d4f09db38679ce8a37663101c5f3b4fe2d3cfef8"
+  "gitHead": "aa87b8b6de071cfb135106af666f4ba6789ca102"
 }

package/src/accessibilityCheck.tsx

@@ -8,7 +8,7 @@ import { ContrastResult } from './accessibility.js';
 import { CMD_EXEC_PATH } from './constants.js';
 import { checkForDocsJson } from './helpers.js';
 
-type TerminateCode = 0 | 1;
+export type TerminateCode = 0 | 1;
 
 export const accessibilityCheck = async (): Promise<TerminateCode> => {
   try {

package/src/cli.tsx

@@ -28,6 +28,7 @@ import {
   terminate,
   readLocalOpenApiFile,
 } from './helpers.js';
+import { mdxLinter } from './mdxLinter.js';
 import { migrateMdx } from './migrateMdx.js';
 import { update } from './update.js';
 
@@ -240,12 +241,13 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
         }
       )
       .command(
-        'accessibility-check',
+        ['accessibility-check', 'a11y-check', 'accessibility', 'a11y'],
         false,
         () => undefined,
         async () => {
-          const terminateCode = await accessibilityCheck();
-          await terminate(terminateCode);
+          const accessibilityCheckTerminateCode = await accessibilityCheck();
+          const mdxLinterTerminateCode = await mdxLinter();
+          await terminate(accessibilityCheckTerminateCode || mdxLinterTerminateCode);
         }
       )
       .command(

package/src/mdxAccessibility.ts

@@ -0,0 +1,132 @@
+import { coreRemark } from '@mintlify/common';
+import { categorizeFilePaths } from '@mintlify/prebuild';
+import fs from 'fs';
+import type { Root, Text } from 'mdast';
+import type { MdxJsxFlowElement } from 'mdast-util-mdx-jsx';
+import path from 'path';
+import type { Node } from 'unist';
+import { visit } from 'unist-util-visit';
+
+export interface AccessibilityFixAttribute {
+  filePath: string;
+  line?: number;
+  column?: number;
+  element: 'img' | 'video' | 'a';
+  tagName: string;
+}
+
+export interface MdxAccessibilityResult {
+  missingAltAttributes: AccessibilityFixAttribute[];
+  totalFiles: number;
+  filesWithIssues: number;
+}
+
+const checkAltAttributes = (filePath: string, content: string): AccessibilityFixAttribute[] => {
+  const issues: AccessibilityFixAttribute[] = [];
+
+  const visitElements = () => {
+    return (tree: Root) => {
+      visit(tree, (node) => {
+        if (node.type === 'image') {
+          if (!node.alt || node.alt.trim() === '') {
+            issues.push({
+              filePath,
+              line: node.position?.start.line,
+              column: node.position?.start.column,
+              element: 'img',
+              tagName: 'image (markdown)',
+            });
+          }
+          return;
+        }
+
+        const mdxJsxElement = node as MdxJsxFlowElement;
+        if (mdxJsxElement.name === 'img' || mdxJsxElement.name === 'video') {
+          const altAttrIndex = mdxJsxElement.attributes.findIndex(
+            (attr) => attr.type === 'mdxJsxAttribute' && attr.name === 'alt'
+          );
+
+          const altAttribute = mdxJsxElement.attributes[altAttrIndex];
+          const hasValidAlt =
+            altAttribute &&
+            typeof altAttribute.value === 'string' &&
+            altAttribute.value.trim() !== '';
+
+          if (!hasValidAlt) {
+            issues.push({
+              filePath,
+              line: node.position?.start.line,
+              column: node.position?.start.column,
+              element: mdxJsxElement.name,
+              tagName: mdxJsxElement.name,
+            });
+          }
+        } else if (mdxJsxElement.name === 'a') {
+          const hasTextContent = (children: Node[]): boolean => {
+            return children.some((child) => {
+              if (child.type === 'text') {
+                const textNode = child as Text;
+                return textNode.value.trim() !== '';
+              }
+              if ('children' in child && Array.isArray(child.children)) {
+                return hasTextContent(child.children as Node[]);
+              }
+              return false;
+            });
+          };
+
+          if (!hasTextContent(mdxJsxElement.children as Node[])) {
+            issues.push({
+              filePath,
+              line: node.position?.start.line,
+              column: node.position?.start.column,
+              element: 'a',
+              tagName: '<a>',
+            });
+          }
+        }
+      });
+      return tree;
+    };
+  };
+
+  try {
+    coreRemark().use(visitElements).processSync(content);
+  } catch (error) {
+    console.warn(`Warning: Could not parse ${filePath}: ${error}`);
+  }
+
+  return issues;
+};
+
+export const checkMdxAccessibility = async (
+  baseDir: string = process.cwd()
+): Promise<MdxAccessibilityResult> => {
+  const { contentFilenames } = await categorizeFilePaths(baseDir);
+  const mdxFiles: string[] = [];
+  for (const file of contentFilenames) {
+    mdxFiles.push(path.join(baseDir, file));
+  }
+  const allIssues: AccessibilityFixAttribute[] = [];
+  const filesWithIssues = new Set<string>();
+
+  for (const filePath of mdxFiles) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const issues = checkAltAttributes(filePath, content);
+
+      if (issues.length > 0) {
+        allIssues.push(...issues);
+        filesWithIssues.add(filePath);
+      }
+    } catch (error) {
+      console.warn(`Warning: Could not read file ${filePath}: ${error}`);
+    }
+  }
+
+  return {
+    missingAltAttributes: allIssues,
+    totalFiles: mdxFiles.length,
+    filesWithIssues: filesWithIssues.size,
+  };
+};

package/src/mdxLinter.tsx

@@ -0,0 +1,88 @@
+import { addLog, ErrorLog, SuccessLog } from '@mintlify/previewing';
+import { Text } from 'ink';
+import path from 'path';
+
+import { TerminateCode } from './accessibilityCheck.js';
+import { checkMdxAccessibility, type AccessibilityFixAttribute } from './mdxAccessibility.js';
+
+export const mdxLinter = async (): Promise<TerminateCode> => {
+  try {
+    addLog(
+      <Text bold color="cyan">
+        Checking mdx files for accessibility issues...
+      </Text>
+    );
+
+    const results = await checkMdxAccessibility();
+
+    if (results.missingAltAttributes.length === 0) {
+      addLog(<SuccessLog message="no accessibility issues found" />);
+      addLog(
+        <Text>
+          Checked {results.totalFiles} MDX files - all images and videos have alt attributes.
+        </Text>
+      );
+      return 0;
+    }
+
+    const issuesByFile: Record<string, AccessibilityFixAttribute[]> = {};
+    results.missingAltAttributes.forEach((issue) => {
+      if (!issuesByFile[issue.filePath]) {
+        issuesByFile[issue.filePath] = [];
+      }
+      issuesByFile[issue.filePath]?.push(issue);
+    });
+
+    addLog(
+      <Text bold color="red">
+        Found {results.missingAltAttributes.length} accessibility issues in{' '}
+        {results.filesWithIssues} files:
+      </Text>
+    );
+    addLog(<Text></Text>);
+
+    for (const [filePath, issues] of Object.entries(issuesByFile)) {
+      const relativePath = path.relative(process.cwd(), filePath);
+      addLog(<Text bold>{relativePath}:</Text>);
+
+      for (const issue of issues) {
+        const location =
+          issue.line && issue.column ? ` (line ${issue.line}, col ${issue.column})` : '';
+        if (issue.element === 'a') {
+          addLog(
+            <Text>
+              <Text color="red"> ✗</Text> Missing text attribute <Text bold>{issue.tagName}</Text>{' '}
+              element{location}
+            </Text>
+          );
+        } else {
+          addLog(
+            <Text>
+              <Text color="red"> ✗</Text> Missing alt attribute on <Text bold>{issue.tagName}</Text>{' '}
+              element{location}
+            </Text>
+          );
+        }
+      }
+      addLog(<Text></Text>);
+    }
+
+    addLog(
+      <Text color="yellow">
+        <Text bold>Recommendation:</Text> Add alt attributes to all images and videos for better
+        accessibility.
+      </Text>
+    );
+
+    return 1;
+  } catch (error) {
+    addLog(
+      <ErrorLog
+        message={`MDX accessibility check failed: ${
+          error instanceof Error ? error.message : 'Unknown error'
+        }`}
+      />
+    );
+    return 1;
+  }
+};