@mui/internal-code-infra 0.0.4-canary.9 → 0.0.4-canary.91

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,
+    }));
+  };
+}

package/src/remark/firstBlockHeading.mjs

@@ -0,0 +1,87 @@
+import { lintRule } from 'unified-lint-rule';
+
+const FRONTMATTER_TYPES = new Set(['yaml', 'toml']);
+const INVISIBLE_TAGS = new Set(['style', 'script']);
+const DEFAULT_FRONT_MATTER_TITLE = /^\s*"?title"?\s*[:=]/m;
+
+/** @param {import('mdast').RootContent} node */
+const isSkippable = (node) => {
+  const type = /** @type {string} */ (node.type);
+  if (FRONTMATTER_TYPES.has(type)) {
+    return true;
+  }
+  if (type === 'html') {
+    const value = /** @type {{ value: string }} */ (/** @type {unknown} */ (node)).value.trim();
+    if (value.startsWith('<!--')) {
+      return true;
+    }
+    const match = value.match(/^<\s*([a-zA-Z][a-zA-Z0-9-]*)/);
+    if (match && INVISIBLE_TAGS.has(match[1].toLowerCase())) {
+      return true;
+    }
+  }
+  if (type === 'mdxJsxFlowElement') {
+    const name = /** @type {{ name: string | null }} */ (/** @type {unknown} */ (node)).name;
+    if (name && INVISIBLE_TAGS.has(name.toLowerCase())) {
+      return true;
+    }
+  }
+  if (type === 'mdxjsEsm') {
+    return true;
+  }
+  if (type === 'mdxFlowExpression') {
+    const value = /** @type {{ value: string }} */ (/** @type {unknown} */ (node)).value.trim();
+    if (
+      value === '' ||
+      (value.startsWith('/*') && value.endsWith('*/')) ||
+      value.startsWith('//')
+    ) {
+      return true;
+    }
+  }
+  return false;
+};
+
+/**
+ * @param {import('mdast').Root} tree
+ * @param {RegExp | false} pattern
+ */
+const hasFrontMatterTitle = (tree, pattern) => {
+  if (!pattern) {
+    return false;
+  }
+  const frontMatter = tree.children.find((child) => FRONTMATTER_TYPES.has(child.type));
+  if (!frontMatter) {
+    return false;
+  }
+  return pattern.test(
+    /** @type {{ value: string }} */ (/** @type {unknown} */ (frontMatter)).value,
+  );
+};
+
+const remarkLintMuiFirstBlockHeading = lintRule(
+  {
+    origin: 'remark-lint:mui-first-block-heading',
+    url: 'https://github.com/mui/mui-public',
+  },
+  /** @type {import('unified-lint-rule').Rule<import('mdast').Root, { frontMatterTitle?: RegExp | false } | undefined>} */
+  (tree, file, options) => {
+    const frontMatterTitle =
+      options?.frontMatterTitle === undefined
+        ? DEFAULT_FRONT_MATTER_TITLE
+        : options.frontMatterTitle;
+    if (hasFrontMatterTitle(tree, frontMatterTitle)) {
+      return;
+    }
+    const firstBlock = tree.children.find((child) => !isSkippable(child));
+    if (!firstBlock) {
+      file.message('Documents must begin with a top-level heading.');
+      return;
+    }
+    if (firstBlock.type !== 'heading' || firstBlock.depth !== 1) {
+      file.message('Documents must begin with a top-level heading.', firstBlock);
+    }
+  },
+);
+
+export default remarkLintMuiFirstBlockHeading;

package/src/remark/gitDiff.mjs

@@ -0,0 +1,43 @@
+import { lintRule } from 'unified-lint-rule';
+import { visit } from 'unist-util-visit';
+
+const singleCharPrefixes = new Set([' ', '-', '+']);
+const linePrefixes = ['@@ ', 'diff --git ', 'index '];
+
+const remarkLintMuiGitDiff = lintRule(
+  {
+    origin: 'remark-lint:mui-git-diff',
+    url: 'https://github.com/mui/mui-public',
+  },
+  /** @param {import('mdast').Root} tree */
+  (tree, file) => {
+    visit(tree, 'code', (node) => {
+      if (node.lang !== 'diff' || !node.position) {
+        return;
+      }
+      const contentStartLine = node.position.start.line + 1;
+      const lines = node.value.split('\n');
+      lines.forEach((line, index) => {
+        if (line === '') {
+          return;
+        }
+        if (singleCharPrefixes.has(line[0])) {
+          return;
+        }
+        if (linePrefixes.some((prefix) => line.startsWith(prefix))) {
+          return;
+        }
+        const lineNumber = contentStartLine + index;
+        file.message(
+          'Line in a `diff` code block must start with " ", "+", "-", "@@ ", "diff --git ", or "index ".',
+          {
+            start: { line: lineNumber, column: 1 },
+            end: { line: lineNumber, column: line.length + 1 },
+          },
+        );
+      });
+    });
+  },
+);
+
+export default remarkLintMuiGitDiff;

package/src/remark/noSpaceInLinks.mjs

@@ -0,0 +1,42 @@
+import { lintRule } from 'unified-lint-rule';
+import { visit } from 'unist-util-visit';
+
+const remarkLintMuiNoSpaceInLinks = lintRule(
+  {
+    origin: 'remark-lint:mui-no-space-in-links',
+    url: 'https://github.com/mui/mui-public',
+  },
+  /** @param {import('mdast').Root} tree */
+  (tree, file) => {
+    const source = String(file.value);
+    visit(tree, 'link', (node) => {
+      if (!node.position || node.children.length === 0) {
+        return;
+      }
+      const first = node.children[0];
+      const last = node.children[node.children.length - 1];
+      if (!first.position || !last.position) {
+        return;
+      }
+      const textStart = first.position.start.offset;
+      const textEnd = last.position.end.offset;
+      if (textStart === undefined || textEnd === undefined) {
+        return;
+      }
+      const openBracket = source.lastIndexOf('[', textStart);
+      const closeBracket = source.indexOf(']', textEnd);
+      if (openBracket === -1 || closeBracket === -1) {
+        return;
+      }
+      const innerText = source.slice(openBracket + 1, closeBracket);
+      if (innerText.length === 0) {
+        return;
+      }
+      if (innerText !== innerText.trim()) {
+        file.message('Link text should not start or end with whitespace.', node);
+      }
+    });
+  },
+);
+
+export default remarkLintMuiNoSpaceInLinks;

package/src/remark/straightQuotes.mjs

@@ -0,0 +1,31 @@
+import { lintRule } from 'unified-lint-rule';
+
+const curlyQuotes = new Set(['‘', '’', '“', '”']);
+
+const remarkLintMuiStraightQuotes = lintRule(
+  {
+    origin: 'remark-lint:mui-straight-quotes',
+    url: 'https://github.com/mui/mui-public',
+  },
+  /** @param {import('mdast').Root} _tree */
+  (_tree, file) => {
+    const text = String(file.value);
+    let line = 1;
+    let lineStart = 0;
+    for (let index = 0; index < text.length; index += 1) {
+      const char = text[index];
+      if (char === '\n') {
+        line += 1;
+        lineStart = index + 1;
+      } else if (curlyQuotes.has(char)) {
+        const column = index - lineStart + 1;
+        file.message('Use straight quotes instead of curly quotes.', {
+          start: { line, column },
+          end: { line, column: column + 1 },
+        });
+      }
+    }
+  },
+);
+
+export default remarkLintMuiStraightQuotes;

package/src/remark/tableAlignment.mjs

@@ -0,0 +1,23 @@
+import { lintRule } from 'unified-lint-rule';
+import { visit } from 'unist-util-visit';
+
+const remarkLintMuiTableAlignment = lintRule(
+  {
+    origin: 'remark-lint:mui-table-alignment',
+    url: 'https://github.com/mui/mui-public',
+  },
+  /** @param {import('mdast').Root} tree */
+  (tree, file) => {
+    visit(tree, 'table', (node) => {
+      const align = node.align ?? [];
+      if (align.some((value) => value == null)) {
+        file.message(
+          'Table columns should declare an explicit alignment (`:---`, `---:`, or `:---:`).',
+          node,
+        );
+      }
+    });
+  },
+);
+
+export default remarkLintMuiTableAlignment;

package/src/remark/terminalLanguage.mjs

@@ -0,0 +1,19 @@
+import { lintRule } from 'unified-lint-rule';
+import { visit } from 'unist-util-visit';
+
+const remarkLintMuiTerminalLanguage = lintRule(
+  {
+    origin: 'remark-lint:mui-terminal-language',
+    url: 'https://github.com/mui/mui-public',
+  },
+  /** @param {import('mdast').Root} tree */
+  (tree, file) => {
+    visit(tree, 'code', (node) => {
+      if (node.lang === 'sh' && node.position) {
+        file.message('Use `bash` instead of `sh` as the code block language.', node);
+      }
+    });
+  },
+);
+
+export default remarkLintMuiTerminalLanguage;

package/src/untyped-plugins.d.ts

@@ -13,77 +13,77 @@ declare module 'eslint-config-airbnb' {
 }
 
 declare module 'eslint-config-airbnb-base/rules/best-practices' {
-  import { Linter } from 'eslint';
+  import type { Linter } from 'eslint';
 
   declare const config: Omit<Linter.LegacyConfig, 'extends' | 'plugins'>;
   export default config;
 }
 
 declare module 'eslint-config-airbnb-base/rules/errors' {
-  import { Linter } from 'eslint';
+  import type { Linter } from 'eslint';
 
   declare const config: Omit<Linter.LegacyConfig, 'extends' | 'plugins'>;
   export default config;
 }
 
 declare module 'eslint-config-airbnb-base/rules/es6' {
-  import { Linter } from 'eslint';
+  import type { Linter } from 'eslint';
 
   declare const config: Omit<Linter.LegacyConfig, 'extends' | 'plugins'>;
   export default config;
 }
 
 declare module 'eslint-config-airbnb-base/rules/imports' {
-  import { Linter } from 'eslint';
+  import type { Linter } from 'eslint';
 
   declare const config: Omit<Linter.LegacyConfig, 'extends' | 'plugins'>;
   export default config;
 }
 
 declare module 'eslint-config-airbnb-base/rules/node' {
-  import { Linter } from 'eslint';
+  import type { Linter } from 'eslint';
 
   declare const config: Omit<Linter.LegacyConfig, 'extends' | 'plugins'>;
   export default config;
 }
 
 declare module 'eslint-config-airbnb-base/rules/strict' {
-  import { Linter } from 'eslint';
+  import type { Linter } from 'eslint';
 
   declare const config: Omit<Linter.LegacyConfig, 'extends' | 'plugins'>;
   export default config;
 }
 
 declare module 'eslint-config-airbnb-base/rules/style' {
-  import { Linter } from 'eslint';
+  import type { Linter } from 'eslint';
 
   declare const config: Omit<Linter.LegacyConfig, 'extends' | 'plugins'>;
   export default config;
 }
 
 declare module 'eslint-config-airbnb-base/rules/variables' {
-  import { Linter } from 'eslint';
+  import type { Linter } from 'eslint';
 
   declare const config: Omit<Linter.LegacyConfig, 'extends' | 'plugins'>;
   export default config;
 }
 
 declare module 'eslint-config-airbnb/rules/react' {
-  import { Linter } from 'eslint';
+  import type { Linter } from 'eslint';
 
   declare const config: Omit<Linter.LegacyConfig, 'extends' | 'plugins'>;
   export default config;
 }
 
 declare module 'eslint-config-airbnb/rules/react-a11y' {
-  import { Linter } from 'eslint';
+  import type { Linter } from 'eslint';
 
   declare const config: Omit<Linter.LegacyConfig, 'extends' | 'plugins'>;
   export default config;
 }
 
 declare module '@next/eslint-plugin-next' {
-  import { Linter } from 'eslint';
+  import type { Linter } from 'eslint';
 
   interface NextEslintPluginConfig extends Linter.LegacyConfig {
     flatConfig: {