@mui/internal-code-infra 0.0.4-canary.7 → 0.0.4-canary.71

package/src/eslint/mui/rules/no-guarded-throw.test.mjs

@@ -0,0 +1,206 @@
+import eslint from 'eslint';
+import parser from '@typescript-eslint/parser';
+import rule from './no-guarded-throw.mjs';
+
+const ruleTester = new eslint.RuleTester({
+  languageOptions: {
+    parser,
+  },
+});
+
+ruleTester.run('no-guarded-throw', rule, {
+  valid: [
+    // Should pass: Unconditional throw
+    {
+      code: `
+throw new Error('Something went wrong');
+      `,
+    },
+    // Should pass: Throw inside a non-NODE_ENV conditional
+    {
+      code: `
+if (value == null) {
+  throw new TypeError('value is required');
+}
+      `,
+    },
+    // Should pass: Throw inside a catch block (no NODE_ENV guard)
+    {
+      code: `
+try {
+  doSomething();
+} catch (error) {
+  throw new Error('Failed');
+}
+      `,
+    },
+    // Should pass: Throw inside arrow function inside NODE_ENV guard
+    {
+      code: `
+if (process.env.NODE_ENV !== 'production') {
+  const fn = () => {
+    throw new Error('inside arrow function');
+  };
+}
+      `,
+    },
+    // Should pass: Throw inside function expression inside NODE_ENV guard
+    {
+      code: `
+if (process.env.NODE_ENV !== 'production') {
+  const fn = function () {
+    throw new Error('inside function expression');
+  };
+}
+      `,
+    },
+    // Should pass: Throw inside function declaration inside NODE_ENV guard
+    {
+      code: `
+if (process.env.NODE_ENV !== 'production') {
+  function validate() {
+    throw new Error('inside function declaration');
+  }
+}
+      `,
+    },
+  ],
+  invalid: [
+    // Should fail: Throw inside !== 'production' guard
+    {
+      code: `
+if (process.env.NODE_ENV !== 'production') {
+  throw new Error('Dev-only error');
+}
+      `,
+      errors: [{ messageId: 'guardedThrow' }],
+    },
+    // Should fail: Throw inside === 'production' guard
+    {
+      code: `
+if (process.env.NODE_ENV === 'production') {
+  throw new Error('Prod-only error');
+}
+      `,
+      errors: [{ messageId: 'guardedThrow' }],
+    },
+    // Should fail: Throw in else block of === 'production' check
+    {
+      code: `
+if (process.env.NODE_ENV === 'production') {
+  // production path
+} else {
+  throw new Error('Non-production error');
+}
+      `,
+      errors: [{ messageId: 'guardedThrow' }],
+    },
+    // Should fail: Throw nested inside NODE_ENV guard
+    {
+      code: `
+if (process.env.NODE_ENV !== 'production') {
+  if (value == null) {
+    throw new TypeError('value is required');
+  }
+}
+      `,
+      errors: [{ messageId: 'guardedThrow' }],
+    },
+    // Should fail: Reversed comparison (literal on left)
+    {
+      code: `
+if ('production' !== process.env.NODE_ENV) {
+  throw new Error('Dev-only error');
+}
+      `,
+      errors: [{ messageId: 'guardedThrow' }],
+    },
+    // Should fail: Throw in loop inside NODE_ENV guard
+    {
+      code: `
+if (process.env.NODE_ENV !== 'production') {
+  for (const item of items) {
+    throw new Error('Invalid item');
+  }
+}
+      `,
+      errors: [{ messageId: 'guardedThrow' }],
+    },
+    // Should fail: NODE_ENV combined with other conditions using &&
+    {
+      code: `
+if (process.env.NODE_ENV !== 'production' && value == null) {
+  throw new TypeError('value is required');
+}
+      `,
+      errors: [{ messageId: 'guardedThrow' }],
+    },
+    // Should fail: NODE_ENV combined with other conditions using ||
+    {
+      code: `
+if (condition || process.env.NODE_ENV === 'test') {
+  throw new Error('Test or condition error');
+}
+      `,
+      errors: [{ messageId: 'guardedThrow' }],
+    },
+    // Should fail: Unary not on process.env.NODE_ENV
+    {
+      code: `
+if (!process.env.NODE_ENV) {
+  throw new Error('NODE_ENV not set');
+}
+      `,
+      errors: [{ messageId: 'guardedThrow' }],
+    },
+    // Should fail: NODE_ENV passed to a function
+    {
+      code: `
+if (fn(process.env.NODE_ENV)) {
+  throw new Error('Function check failed');
+}
+      `,
+      errors: [{ messageId: 'guardedThrow' }],
+    },
+    // Should fail: Throw inside try/catch inside NODE_ENV guard
+    {
+      code: `
+if (process.env.NODE_ENV !== 'production') {
+  try {
+    doSomething();
+  } catch (error) {
+    throw new Error('caught inside guard');
+  }
+}
+      `,
+      errors: [{ messageId: 'guardedThrow' }],
+    },
+    // Should fail: Throw deeply nested in control flow inside NODE_ENV guard
+    {
+      code: `
+if (process.env.NODE_ENV !== 'production') {
+  if (value == null) {
+    for (const item of items) {
+      if (!item.valid) {
+        throw new Error('invalid item');
+      }
+    }
+  }
+}
+      `,
+      errors: [{ messageId: 'guardedThrow' }],
+    },
+    // Should fail: Throw inside switch/case inside NODE_ENV guard
+    {
+      code: `
+if (process.env.NODE_ENV !== 'production') {
+  switch (type) {
+    case 'a':
+      throw new Error('invalid type a');
+  }
+}
+      `,
+      errors: [{ messageId: 'guardedThrow' }],
+    },
+  ],
+});

package/src/eslint/mui/rules/no-presentation-role.mjs

@@ -0,0 +1,60 @@
+/**
+ * @type {import('eslint').Rule.RuleModule}
+ */
+const rule = {
+  meta: {
+    docs: {
+      description:
+        'Disallow role="presentation" in favor of role="none". Both are equivalent, but role="none" is clearer and shorter.',
+    },
+    messages: {
+      noPresentation:
+        'Use role="none" instead of role="presentation". They are equivalent, but role="none" is preferred.',
+    },
+    fixable: 'code',
+    type: 'suggestion',
+    schema: [],
+  },
+  create(context) {
+    return {
+      /** @param {import('estree-jsx').JSXAttribute} node */
+      JSXAttribute(node) {
+        if (node.name.type !== 'JSXIdentifier' || node.name.name !== 'role') {
+          return;
+        }
+
+        const { value } = node;
+
+        // role="presentation"
+        if (value !== null && value.type === 'Literal' && value.value === 'presentation') {
+          context.report({
+            node,
+            messageId: 'noPresentation',
+            fix(fixer) {
+              return fixer.replaceText(value, '"none"');
+            },
+          });
+          return;
+        }
+
+        // role={'presentation'}
+        if (
+          value !== null &&
+          value.type === 'JSXExpressionContainer' &&
+          value.expression.type === 'Literal' &&
+          value.expression.value === 'presentation'
+        ) {
+          context.report({
+            node,
+            messageId: 'noPresentation',
+            fix(fixer) {
+              return fixer.replaceText(value, '"none"');
+            },
+          });
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/src/eslint/mui/rules/no-presentation-role.test.mjs

@@ -0,0 +1,33 @@
+import eslint from 'eslint';
+import parser from '@typescript-eslint/parser';
+import rule from './no-presentation-role.mjs';
+
+const ruleTester = new eslint.RuleTester({
+  languageOptions: {
+    parser,
+    parserOptions: {
+      ecmaFeatures: { jsx: true },
+    },
+  },
+});
+
+ruleTester.run('no-presentation-role', rule, {
+  valid: ['<div role="none" />', '<div role="button" />', '<div />', '<div role={presentation} />'],
+  invalid: [
+    {
+      code: '<div role="presentation" />',
+      errors: [{ messageId: 'noPresentation' }],
+      output: '<div role="none" />',
+    },
+    {
+      code: "<div role={'presentation'} />",
+      errors: [{ messageId: 'noPresentation' }],
+      output: '<div role="none" />',
+    },
+    {
+      code: '<table role="presentation"><tr><td /></tr></table>',
+      errors: [{ messageId: 'noPresentation' }],
+      output: '<table role="none"><tr><td /></tr></table>',
+    },
+  ],
+});

package/src/eslint/mui/rules/nodeEnvUtils.mjs

@@ -39,3 +39,55 @@ export function isLiteralEq(node, value) {
 export function isLiteralNeq(node, value) {
   return node.type === 'Literal' && node.value !== value;
 }
+
+/**
+ * Checks if a BinaryExpression compares process.env.NODE_ENV with === or !==
+ * @param {import('estree').Node} node
+ * @returns {boolean}
+ */
+export function isNodeEnvBinaryComparison(node) {
+  return (
+    node.type === 'BinaryExpression' &&
+    (node.operator === '===' || node.operator === '!==') &&
+    (isProcessEnvNodeEnv(node.left) || isProcessEnvNodeEnv(node.right))
+  );
+}
+
+/**
+ * Walks up the parent chain and checks if the node is inside an IfStatement
+ * whose test is a NODE_ENV binary comparison.
+ * If a callback is provided, it is called with the IfStatement and the direct
+ * child that leads to the node. The function returns true only when the callback
+ * returns true. Without a callback the function returns true when the node is
+ * inside any branch (consequent or alternate) of such an IfStatement.
+ * @param {import('eslint').Rule.Node} node
+ * @param {(ifStatement: import('estree').IfStatement & import('eslint').Rule.NodeParentExtension, child: import('eslint').Rule.Node) => boolean} [callback]
+ * @returns {boolean}
+ */
+export function isInsideNodeEnvCheck(node, callback) {
+  /** @type {import('eslint').Rule.Node | null} */
+  let current = node.parent;
+  /** @type {import('eslint').Rule.Node} */
+  let currentChild = node;
+
+  while (current) {
+    if (current.type === 'IfStatement' && isNodeEnvBinaryComparison(current.test)) {
+      if (callback) {
+        if (callback(current, currentChild)) {
+          return true;
+        }
+      } else {
+        const isInConsequent = current.consequent === currentChild;
+        const isInAlternate = current.alternate === currentChild;
+        if (isInConsequent || isInAlternate) {
+          return true;
+        }
+      }
+    }
+
+    currentChild = current;
+    current = current.parent;
+  }
+
+  return false;
+}

package/src/eslint/mui/rules/require-dev-wrapper.mjs

@@ -1,4 +1,9 @@
-import { isProcessEnvNodeEnv, isLiteralEq, isLiteralNeq } from './nodeEnvUtils.mjs';
+import {
+  isProcessEnvNodeEnv,
+  isLiteralEq,
+  isLiteralNeq,
+  isInsideNodeEnvCheck,
+} from './nodeEnvUtils.mjs';
 
 /**
  * ESLint rule that enforces certain function calls to be wrapped with
@@ -58,18 +63,21 @@ const rule = {
     const functionNames = options.functionNames || ['warnOnce', 'warn', 'checkSlot'];
 
     /**
-     * Checks if a binary expression is comparing process.env.NODE_ENV appropriately
-     * @param {import('estree').BinaryExpression} binaryExpression - The binary expression to check
+     * Checks if an expression is comparing process.env.NODE_ENV appropriately
+     * @param {import('estree').Expression} expression - The expression to check
      * @param {string} operator - The expected comparison operator (===, !==, etc.)
      * @param {string} value - The value to compare with
      * @returns {boolean}
      */
-    function isNodeEnvComparison(binaryExpression, operator, value) {
-      const { left, right } = binaryExpression;
+    function isNodeEnvComparison(expression, operator, value) {
+      if (expression.type !== 'BinaryExpression') {
+        return false;
+      }
+      const { left, right } = expression;
 
       // Check for exact match with the specified value
       if (
-        binaryExpression.operator === operator &&
+        expression.operator === operator &&
         ((isProcessEnvNodeEnv(left) && isLiteralEq(right, value)) ||
           (isProcessEnvNodeEnv(right) && isLiteralEq(left, value)))
       ) {
@@ -79,7 +87,7 @@ const rule = {
       // For !== operator also allow === with any literal value that's NOT 'production'
       if (
         operator === '!==' &&
-        binaryExpression.operator === '===' &&
+        expression.operator === '===' &&
         ((isProcessEnvNodeEnv(left) && isLiteralNeq(right, value)) ||
           (isProcessEnvNodeEnv(right) && isLiteralNeq(left, value)))
       ) {
@@ -95,41 +103,18 @@ const rule = {
      * @returns {boolean}
      */
     function isWrappedInProductionCheck(node) {
-      /** @type {import('eslint').Rule.Node | null} */
-      let current = node.parent;
-      /** @type {import('eslint').Rule.Node} */
-      let currentChild = node;
-
-      while (current) {
-        // Check if we're inside an if statement
-        if (current.type === 'IfStatement') {
-          // Determine which branch we're in
-          const isInConsequent = current.consequent === currentChild;
-          const isInAlternate = current.alternate === currentChild;
-
-          // Skip if not in a branch
-          if (isInConsequent || isInAlternate) {
-            const test = current.test;
+      return isInsideNodeEnvCheck(node, (ifStatement, child) => {
+        const isInConsequent = ifStatement.consequent === child;
+        const isInAlternate = ifStatement.alternate === child;
 
-            // If we're in the consequent, we need !==
-            // If we're in the alternate (else), we need ===
-            const operator = isInConsequent ? '!==' : '===';
-
-            // Check for the specific pattern with the right operator
-            if (
-              test.type === 'BinaryExpression' &&
-              isNodeEnvComparison(test, operator, 'production')
-            ) {
-              return true;
-            }
-          }
+        if (isInConsequent || isInAlternate) {
+          // If we're in the consequent, we need !==
+          // If we're in the alternate (else), we need ===
+          const operator = isInConsequent ? '!==' : '===';
+          return isNodeEnvComparison(ifStatement.test, operator, 'production');
         }
-
-        currentChild = current;
-        current = current.parent;
-      }
-
-      return false;
+        return false;
+      });
     }
 
     return {

package/src/estree-typescript.d.ts

@@ -1,4 +1,4 @@
-import { BaseExpression, Expression } from 'estree';
+import type { BaseExpression, Expression } from 'estree';
 
 export * from 'estree';
 

package/src/remark/config.mjs

@@ -0,0 +1,157 @@
+import * as path from 'node:path';
+import { minimatch } from 'minimatch';
+import { unified } from 'unified';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkGfm from 'remark-gfm';
+import remarkLint from 'remark-lint';
+import remarkLintCodeBlockStyle from 'remark-lint-code-block-style';
+import remarkLintFencedCodeFlag from 'remark-lint-fenced-code-flag';
+import remarkLintHeadingIncrement from 'remark-lint-heading-increment';
+import remarkLintHeadingStyle from 'remark-lint-heading-style';
+import remarkLintNoDuplicateHeadings from 'remark-lint-no-duplicate-headings';
+import remarkLintNoEmptyUrl from 'remark-lint-no-empty-url';
+import remarkLintNoHeadingPunctuation from 'remark-lint-no-heading-punctuation';
+import remarkLintNoMultipleToplevelHeadings from 'remark-lint-no-multiple-toplevel-headings';
+import remarkLintNoUndefinedReferences from 'remark-lint-no-undefined-references';
+import remarkLintNoUnusedDefinitions from 'remark-lint-no-unused-definitions';
+import remarkLintTablePipes from 'remark-lint-table-pipes';
+import muiFirstBlockHeading from './firstBlockHeading.mjs';
+import muiGitDiff from './gitDiff.mjs';
+import muiNoSpaceInLinks from './noSpaceInLinks.mjs';
+import muiStraightQuotes from './straightQuotes.mjs';
+import muiTableAlignment from './tableAlignment.mjs';
+import muiTerminalLanguage from './terminalLanguage.mjs';
+
+const GITHUB_ALERT_LABELS = ['!NOTE', '!TIP', '!WARNING', '!IMPORTANT', '!CAUTION'];
+
+const RULES = {
+  'no-duplicate-headings': [remarkLintNoDuplicateHeadings, ['error']],
+  'no-multiple-toplevel-headings': [remarkLintNoMultipleToplevelHeadings, ['error']],
+  'no-undefined-references': [
+    remarkLintNoUndefinedReferences,
+    ['error', { allow: GITHUB_ALERT_LABELS, allowShortcutLink: true }],
+  ],
+  'no-unused-definitions': [remarkLintNoUnusedDefinitions, ['error']],
+  'heading-style': [remarkLintHeadingStyle, ['error', 'atx']],
+  'heading-increment': [remarkLintHeadingIncrement, ['error']],
+  'no-heading-punctuation': [remarkLintNoHeadingPunctuation, ['error', '.,;:!']],
+  'code-block-style': [remarkLintCodeBlockStyle, ['error', 'fenced']],
+  'fenced-code-flag': [remarkLintFencedCodeFlag, ['error']],
+  'no-empty-url': [remarkLintNoEmptyUrl, ['error']],
+  'table-pipes': [remarkLintTablePipes, ['error']],
+  'mui-first-block-heading': [muiFirstBlockHeading, ['error']],
+  'mui-git-diff': [muiGitDiff, ['error']],
+  'mui-no-space-in-links': [muiNoSpaceInLinks, ['error']],
+  'mui-straight-quotes': [muiStraightQuotes, ['error']],
+  'mui-table-alignment': [muiTableAlignment, ['error']],
+  'mui-terminal-language': [muiTerminalLanguage, ['error']],
+};
+
+/**
+ * @param {string | undefined} filePath
+ */
+function relativePath(filePath) {
+  if (!filePath) {
+    return filePath;
+  }
+  if (path.isAbsolute(filePath)) {
+    return path.relative(process.cwd(), filePath);
+  }
+  return filePath;
+}
+
+/**
+ * Wraps a remark-lint plugin so its transformer dispatches at runtime based on
+ * `file.path`. Each variant (base + per-override) runs through its own mini
+ * unified pipeline so severity, baked in by `unified-lint-rule` at attach time,
+ * is preserved correctly.
+ *
+ * @param {string} name
+ * @param {import('unified').Plugin<any[], any, any>} plugin
+ * @param {any} baseSettings
+ * @param {Array<{ files: string | string[], settings: false | any }>} overrideEntries
+ */
+function withOverrides(name, plugin, baseSettings, overrideEntries) {
+  const baseProcessor = unified().use(plugin, baseSettings);
+  const variants = overrideEntries.map(({ files, settings }) => ({
+    files: Array.isArray(files) ? files : [files],
+    processor: settings === false ? null : unified().use(plugin, settings),
+  }));
+  function wrapper() {
+    /** @type {import('unified').Transformer} */
+    return async function transformer(tree, file) {
+      const candidate = relativePath(file.path);
+      const matched = candidate
+        ? variants.find((variant) => variant.files.some((pattern) => minimatch(candidate, pattern)))
+        : undefined;
+      if (matched) {
+        if (matched.processor) {
+          await matched.processor.run(tree, file);
+        }
+        return;
+      }
+      await baseProcessor.run(tree, file);
+    };
+  }
+  Object.defineProperty(wrapper, 'name', { value: `mui-remark-overrides(${name})` });
+  return wrapper;
+}
+
+/**
+ * Returns a remark preset wiring the MUI-authored remark-lint plugins together
+ * with a curated set of community plugins. Drop this into `.remarkrc.mjs`:
+ *
+ * ```js
+ * import { createRemarkConfig } from '@mui/internal-code-infra/remark';
+ * export default createRemarkConfig();
+ * ```
+ *
+ * Pass `overrides` to scope rule changes to a glob. Each entry's `rules` map
+ * is keyed by the rule name (the key used in `RULES`); `false` disables the
+ * rule for matching files, a settings tuple replaces its severity/options:
+ *
+ * ```js
+ * createRemarkConfig({
+ *   overrides: [
+ *     { files: 'docs/special/**', rules: { 'mui-no-space-in-links': false } },
+ *     { files: '**\/CHANGELOG.md', rules: { 'heading-style': ['warn', 'atx'] } },
+ *   ],
+ * });
+ * ```
+ *
+ * @param {Object} [options]
+ * @param {Array<{ files: string | string[], rules: Record<string, false | unknown[]> }>} [options.overrides]
+ */
+export function createRemarkConfig({ overrides = [] } = {}) {
+  for (const override of overrides) {
+    const unknown = Object.keys(override.rules).filter((ruleName) => !(ruleName in RULES));
+    if (unknown.length > 0) {
+      throw new Error(`Unknown remark-lint rule name(s): ${unknown.join(', ')}`);
+    }
+  }
+
+  const entries = Object.entries(RULES).map(([name, entry]) => {
+    const [plugin, baseSettings] = /** @type {[import('unified').Plugin<any[], any, any>, any]} */ (
+      entry
+    );
+    const overrideEntries = overrides
+      .filter((override) => name in override.rules)
+      .map((override) => ({ files: override.files, settings: override.rules[name] }));
+    if (overrideEntries.length === 0) {
+      return [plugin, baseSettings];
+    }
+    return [withOverrides(name, plugin, baseSettings, overrideEntries)];
+  });
+
+  return {
+    settings: {
+      bullet: '-',
+      emphasis: '_',
+      fence: '`',
+      listItemIndent: 'one',
+      resourceLink: true,
+      rule: '-',
+    },
+    plugins: [[remarkFrontmatter, ['yaml', 'toml']], remarkGfm, remarkLint, ...entries],
+  };
+}

package/src/remark/createLintTester.mjs

@@ -0,0 +1,19 @@
+import { remark } from 'remark';
+import remarkGfm from 'remark-gfm';
+
+/**
+ * @param {unknown} plugin
+ * @param {unknown} [options]
+ * @returns {(input: string) => Array<{ reason: string, line: number, column: number }>}
+ */
+export function createLintTester(plugin, options) {
+  const entry = /** @type {any} */ (options === undefined ? plugin : [plugin, options]);
+  return function lint(input) {
+    const file = remark().use(remarkGfm).use(entry).processSync(input);
+    return file.messages.map((message) => ({
+      reason: message.reason,
+      line: message.line ?? 0,
+      column: message.column ?? 0,
+    }));
+  };
+}