@mui/internal-code-infra 0.1.1-canary.2 → 0.1.1-canary.20

package/src/cli/cmdNetlifyIgnore.mjs

@@ -4,7 +4,7 @@
 
 /**
  * @typedef {Object} Args
- * @property {string[]} workspaces - List of workspace names to process
+ * @property {string[]} workspaces - Workspace names or root-relative paths to process
  * @property {boolean} [check] - Check mode - error if the generated content differs from current
  * @property {string} [baseBranch] - Branch to compare PRs against (default: master)
  */
@@ -100,7 +100,7 @@ export default /** @type {import('yargs').CommandModule<{}, Args>} */ ({
       .positional('workspaces', {
         type: 'string',
         array: true,
-        describe: 'List of workspace names to process',
+        describe: 'Workspace names or root-relative paths to process',
         demandOption: true,
       })
       .option('check', {
@@ -115,6 +115,7 @@ export default /** @type {import('yargs').CommandModule<{}, Args>} */ ({
           "Branch to compare PRs against (the site's production branch on Netlify). Production and branch deploys always rebuild regardless of this value.",
       })
       .example('$0 netlify-ignore @mui/internal-docs-infra', 'Update netlify.toml for a workspace')
+      .example('$0 netlify-ignore ./apps/dashboard', 'Update an unnamed workspace by path')
       .example(
         '$0 netlify-ignore @mui/internal-docs-infra @mui/internal-code-infra',
         'Update netlify.toml for multiple workspaces',
@@ -135,11 +136,17 @@ export default /** @type {import('yargs').CommandModule<{}, Args>} */ ({
 
     // Get all workspace packages and create workspace map
     const allWorkspaces = await getWorkspacePackages({ cwd: workspaceRoot });
-    const workspaceMap = new Map(
-      allWorkspaces.flatMap((workspace) =>
-        workspace.name ? [[workspace.name, workspace.path]] : [],
-      ),
-    );
+    /** @type {Map<string, string>} */
+    const workspaceMap = new Map();
+    for (const workspace of allWorkspaces) {
+      if (workspace.name) {
+        workspaceMap.set(workspace.name, workspace.path);
+      }
+
+      // Paths also identify private workspaces that have no package name.
+      const relativePath = toPosixPath(path.relative(workspaceRoot, workspace.path));
+      workspaceMap.set(`./${relativePath}`, workspace.path);
+    }
 
     // Process each workspace concurrently
     await Promise.all(

package/src/cli/index.mjs

@@ -4,6 +4,7 @@ import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 
 import cmdArgosPush from './cmdArgosPush.mjs';
+import cmdBaseline from './cmdBaseline.mjs';
 import cmdBuild from './cmdBuild.mjs';
 import cmdCopyFiles from './cmdCopyFiles.mjs';
 import cmdExtractErrorCodes from './cmdExtractErrorCodes.mjs';
@@ -38,6 +39,7 @@ await yargs(hideBin(process.argv))
     globalArgv = argv;
   }, true)
   .command(cmdArgosPush)
+  .command(cmdBaseline)
   .command(cmdBuild)
   .command(cmdCopyFiles)
   .command(cmdExtractErrorCodes)

package/src/eslint/baseConfig.mjs

@@ -17,6 +17,7 @@ import { createCoreConfig } from './mui/config.mjs';
 import muiPlugin from './mui/index.mjs';
 import { EXTENSION_TS } from './extensions.mjs';
 import { createJsonConfig } from './jsonConfig.mjs';
+import { createPackageJsonConfig } from './packageJsonConfig.mjs';
 
 /**
  * @param {string} filePath
@@ -73,6 +74,7 @@ export function createBaseConfig({
     includeIgnoreIfExists(path.join(baseDirectory, '.gitignore'), `Ignore rules from .gitignore`),
     includeIgnoreIfExists(path.join(baseDirectory, '.lintignore'), `Ignore rules from .lintignore`),
     createJsonConfig(),
+    createPackageJsonConfig(),
     prettier,
     // Markdown + MDX linting via eslint-plugin-mdx. Severities for markdown
     // quality checks live in the project's `.remarkrc` (see

package/src/eslint/docsConfig.mjs

@@ -19,17 +19,35 @@ export function createDocsConfig() {
     ? nextjsAlias.flatConfig.recommended
     : nextjsAlias.configs.recommended;
 
-  return defineConfig(recommendedConfig, {
-    settings: {
-      next: {
-        rootDir: 'docs',
+  return defineConfig(
+    recommendedConfig,
+    {
+      settings: {
+        next: {
+          rootDir: 'docs',
+        },
+      },
+      files: [`**/*${EXTENSION_TS}`],
+      rules: {
+        'compat/compat': 'off',
+        'jsx-a11y/anchor-is-valid': 'off',
+        'no-irregular-whitespace': ['error', { skipJSXText: true, skipStrings: true }],
       },
     },
-    files: [`**/*${EXTENSION_TS}`],
-    rules: {
-      'compat/compat': 'off',
-      'jsx-a11y/anchor-is-valid': 'off',
-      'no-irregular-whitespace': ['error', { skipJSXText: true, skipStrings: true }],
+    {
+      // Build configuration and maintenance scripts aren't documentation examples
+      // and are often intentionally outside the docs TypeScript project.
+      files: [`**/*${EXTENSION_TS}`],
+      ignores: ['**/*.config.*', '**/scripts/**'],
+      languageOptions: {
+        parserOptions: {
+          projectService: true,
+          tsconfigRootDir: process.cwd(),
+        },
+      },
+      rules: {
+        '@typescript-eslint/no-deprecated': 'error',
+      },
     },
-  });
+  );
 }

package/src/eslint/jsonConfig.mjs

@@ -9,7 +9,8 @@ export function createJsonConfig() {
     {
       name: 'JSON files',
       files: ['**/*.json'],
-      ignores: ['package-lock.json'],
+      // package.json is linted by eslint-plugin-package-json, whose rules need the jsonc-eslint-parser AST.
+      ignores: ['package-lock.json', '**/package.json'],
       plugins: { json },
       language: 'json/json',
       extends: [json.configs.recommended],

package/src/eslint/mui/config.mjs

@@ -1,5 +1,5 @@
 import { defineConfig } from 'eslint/config';
-import { EXTENSION_DTS } from '../extensions.mjs';
+import { EXTENSION_DTS, EXTENSION_TS_ONLY } from '../extensions.mjs';
 
 const restrictedMethods = ['setTimeout', 'setInterval', 'clearTimeout', 'clearInterval'];
 
@@ -184,6 +184,14 @@ const typescriptOverrides = {
   // TypeScript equivalents of ESLint rules
   'default-param-last': 'off',
   '@typescript-eslint/default-param-last': 'error',
+  '@typescript-eslint/ban-ts-comment': [
+    'error',
+    {
+      'ts-expect-error': 'allow-with-description',
+      'ts-ignore': true,
+      minimumDescriptionLength: 10,
+    },
+  ],
   'no-array-constructor': 'off',
   '@typescript-eslint/no-array-constructor': 'error',
   '@typescript-eslint/triple-slash-reference': 'off',
@@ -538,6 +546,13 @@ export function createCoreConfig(options = {}) {
         '@typescript-eslint/return-await': 'off',
       },
     },
+    {
+      name: 'mui-base/ts',
+      files: [`**/*${EXTENSION_TS_ONLY}`],
+      rules: {
+        'mui/no-constructor-assigned-field': 'error',
+      },
+    },
     {
       name: 'mui-base/dts',
       files: [`**/*${EXTENSION_DTS}`],

package/src/eslint/mui/index.mjs

@@ -14,6 +14,7 @@ import addUndefToOptional from './rules/add-undef-to-optional.mjs';
 import flattenParentheses from './rules/flatten-parentheses.mjs';
 import noPresentationRole from './rules/no-presentation-role.mjs';
 import noFloatingCleanup from './rules/no-floating-cleanup.mjs';
+import noConstructorAssignedField from './rules/no-constructor-assigned-field.mjs';
 
 /** @type {import('eslint').ESLint.Plugin} */
 const muiPlugin = {
@@ -39,6 +40,7 @@ const muiPlugin = {
     'flatten-parentheses': /** @type {any} */ (flattenParentheses),
     'no-presentation-role': noPresentationRole,
     'no-floating-cleanup': /** @type {any} */ (noFloatingCleanup),
+    'no-constructor-assigned-field': /** @type {any} */ (noConstructorAssignedField),
   },
 };
 

package/src/eslint/mui/rules/no-constructor-assigned-field.mjs

@@ -0,0 +1,183 @@
+import { ASTUtils, ESLintUtils } from '@typescript-eslint/utils';
+
+/**
+ * @typedef {import('@typescript-eslint/utils').TSESTree.PropertyDefinition} PropertyDefinition
+ * @typedef {import('@typescript-eslint/utils').TSESTree.Node} Node
+ */
+
+const createRule = ESLintUtils.RuleCreator(
+  (name) =>
+    `https://github.com/mui/mui-public/blob/master/packages/code-infra/src/eslint/mui/rules/${name}.mjs`,
+);
+
+/**
+ * Returns the constructor whose own code contains `node`, or `null` when `node` is outside a
+ * constructor or inside a nested function or class.
+ * @param {Node} node
+ */
+function getEnclosingConstructor(node) {
+  let current = node.parent;
+  while (current && !ASTUtils.isFunction(current)) {
+    if (current.type === 'ClassBody') {
+      return null;
+    }
+    current = current.parent;
+  }
+  const method = current?.parent;
+  return method && ASTUtils.isConstructor(method) ? method : null;
+}
+
+/**
+ * Returns the extra edits needed before `field` can be marked `declare`.
+ * @param {PropertyDefinition} field
+ */
+function getDeclareHint(field) {
+  const edits = [];
+  if (field.value) {
+    edits.push('drop its initializer');
+  }
+  if (field.definite) {
+    edits.push('drop the `!`');
+  }
+  if (field.override) {
+    edits.push('drop `override`');
+  }
+  return edits.length > 0 ? ` (${edits.join(', ')})` : '';
+}
+
+/**
+ * ESLint rule that disallows assigning a class field in the constructor when it is also
+ * declared as a (non-`declare`) class field.
+ *
+ * Babel 8 only strips TypeScript fields marked `declare` (see mui/material-ui#49241), so a
+ * field without an initializer is emitted as a property definition that sets it to
+ * `undefined` before the constructor assigns it again. Either initialize the field at its
+ * declaration, or mark it `declare` so it only serves as a type annotation.
+ *
+ * `declare` fields are exempt from TypeScript's strict property initialization check
+ * (TS2564), so prefer initializing at the declaration where the value doesn't depend on
+ * constructor arguments. The `declare` suggestion is only offered when every path through the
+ * constructor assigns the field, i.e. for an unconditional top-level assignment.
+ *
+ * Only plain `=` assignments count: compound assignments read the field rather than
+ * re-initialize it. A field with an initializer is only reported for an unconditional
+ * top-level assignment, as a conditional one overrides a default. Private (`#`) and decorated
+ * fields are ignored: they are runtime declarations that `declare` can't replace.
+ *
+ * @example
+ * // Invalid
+ * class ModalManager {
+ *   private modals: Modal[];
+ *   constructor() {
+ *     this.modals = [];
+ *   }
+ * }
+ *
+ * @example
+ * // Valid - initialized at the declaration
+ * class ModalManager {
+ *   private modals: Modal[] = [];
+ * }
+ *
+ * @example
+ * // Valid - declared only, assigned in the constructor
+ * class ModalManager {
+ *   declare private modals: Modal[];
+ *   constructor(modals: Modal[]) {
+ *     this.modals = modals;
+ *   }
+ * }
+ */
+export default createRule({
+  name: 'no-constructor-assigned-field',
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Disallow assigning class fields in the constructor when they are also declared as class fields',
+    },
+    hasSuggestions: true,
+    messages: {
+      assignedInConstructor:
+        "Field '{{name}}' is declared as a class field and also assigned in the constructor. " +
+        'Either initialize it at the declaration and remove the constructor assignment, ' +
+        'or mark it `declare`{{declareHint}}.',
+      addDeclare: 'Mark the field `declare`.',
+    },
+    schema: [],
+  },
+  defaultOptions: [],
+  create(context) {
+    /**
+     * Fields assigned in a constructor, mapped to whether any of those assignments is an
+     * unconditional top-level statement.
+     * @type {Map<PropertyDefinition, boolean>}
+     */
+    const assignedFields = new Map();
+
+    return {
+      AssignmentExpression(node) {
+        if (
+          node.operator !== '=' ||
+          node.left.type !== 'MemberExpression' ||
+          node.left.object.type !== 'ThisExpression'
+        ) {
+          return;
+        }
+        const name = ASTUtils.getPropertyName(node.left);
+        if (name === null) {
+          return;
+        }
+        const constructor = getEnclosingConstructor(node);
+        if (!constructor) {
+          return;
+        }
+
+        const field = constructor.parent.body.find(
+          /** @returns {member is PropertyDefinition} */
+          (member) =>
+            member.type === 'PropertyDefinition' &&
+            !member.static &&
+            !member.declare &&
+            member.decorators.length === 0 &&
+            ASTUtils.getPropertyName(member) === name,
+        );
+        if (!field) {
+          return;
+        }
+
+        const statement = node.parent;
+        const unconditional =
+          statement.type === 'ExpressionStatement' && statement.parent === constructor.value.body;
+        assignedFields.set(field, Boolean(assignedFields.get(field)) || unconditional);
+      },
+      'ClassBody:exit'(classBody) {
+        for (const member of classBody.body) {
+          if (member.type !== 'PropertyDefinition' || !assignedFields.has(member)) {
+            continue;
+          }
+          const unconditional = Boolean(assignedFields.get(member));
+          if (member.value && !unconditional) {
+            continue;
+          }
+
+          const declareHint = getDeclareHint(member);
+          context.report({
+            node: member,
+            messageId: 'assignedInConstructor',
+            data: { name: ASTUtils.getPropertyName(member), declareHint },
+            suggest:
+              unconditional && declareHint === ''
+                ? [
+                    {
+                      messageId: 'addDeclare',
+                      fix: (fixer) => fixer.insertTextBefore(member, 'declare '),
+                    },
+                  ]
+                : [],
+          });
+        }
+      },
+    };
+  },
+});

package/src/eslint/packageJsonConfig.mjs

@@ -0,0 +1,50 @@
+import { defineConfig } from 'eslint/config';
+import packageJson from 'eslint-plugin-package-json';
+
+/**
+ * Lints package.json files for publishing metadata. Published packages must
+ * declare an SPDX license, `"author": "MUI Team"` and a repository pointing at
+ * their own directory. Private packages must not carry publishing metadata.
+ * @returns {import('eslint').Linter.Config[]}
+ */
+export function createPackageJsonConfig() {
+  return defineConfig([
+    {
+      name: 'package.json files',
+      files: ['**/package.json'],
+      ignores: ['**/__fixtures__/**'],
+      extends: [packageJson.configs.recommended],
+      rules: {
+        'package-json/require-author': ['error', { ignorePrivate: true }],
+        'package-json/require-description': ['error', { ignorePrivate: true }],
+        'package-json/restrict-private-properties': [
+          'error',
+          // `publishConfig.directory` is allowed: `code-infra build` reads it, also for private packages.
+          { blockedProperties: ['files', 'license'] },
+        ],
+        'no-restricted-syntax': [
+          'error',
+          {
+            selector:
+              'Program > JSONExpressionStatement > JSONObjectExpression > JSONProperty[key.value="author"][value.value!="MUI Team"]',
+            message: 'The "author" field must be "MUI Team".',
+          },
+        ],
+        // Condition order in "exports" is significant, and scripts are grouped by purpose.
+        'package-json/sort-collections': 'off',
+        // Packages built with `code-infra build` get these fields in the generated package.json.
+        'package-json/require-files': 'off',
+        'package-json/require-sideEffects': 'off',
+        'package-json/require-type': 'off',
+        // Peer dependencies are installed once at the workspace root.
+        'package-json/specify-peers-locally': 'off',
+        // CLI-only packages have no "exports".
+        'package-json/require-exports': 'off',
+        // Rejects the object form of "browser", which the browser field spec allows.
+        'package-json/valid-browser': 'off',
+        // npm only auto-includes "main" when it has no "./" prefix; removing it from "files" can drop the entry point.
+        'package-json/no-redundant-files': 'off',
+      },
+    },
+  ]);
+}

package/src/eslint/testConfig.mjs

@@ -21,7 +21,6 @@ export const baseSpecRules = {
     '@typescript-eslint/no-unused-expressions': 'off',
     '@typescript-eslint/no-unused-vars': 'off',
     '@typescript-eslint/no-use-before-define': 'off',
-    '@typescript-eslint/ban-ts-comment': 'off',
 
     'import/prefer-default-export': 'off',
 
@@ -63,6 +62,7 @@ export function createTestConfig() {
         'import/named': 'off',
         'mui/disallow-active-element-as-key-event-target': 'error',
         'mui/consistent-production-guard': 'off',
+        'mui/no-constructor-assigned-field': 'off',
 
         // disable eslint-plugin-jsx-a11y
         // tests are not driven by assistive technology
@@ -87,7 +87,6 @@ export function createTestConfig() {
         'react/no-unused-prop-types': 'off',
         // Part of the migration away from airbnb config. Turned of initially.
         '@typescript-eslint/no-empty-function': 'off',
-        '@typescript-eslint/ban-ts-comment': 'off',
         'testing-library/no-node-access': 'off',
         '@typescript-eslint/no-non-null-asserted-optional-chain': 'off',
         // end migration

package/src/remark/config.mjs

@@ -97,6 +97,49 @@ function withOverrides(name, plugin, baseSettings, overrideEntries) {
   return wrapper;
 }
 
+/**
+ * Allows link-reference comments while retaining diagnostics for real links and definitions.
+ * Existing docs generators use these markers in both Markdown and MDX and parse them as metadata.
+ * Authored MDX can use JSX comments without this compatibility option.
+ *
+ * @param {import('unified').Plugin<any[], any, any>} plugin
+ */
+function withDefinitionComments(plugin) {
+  /** @param {any[]} settings */
+  return function wrapper(...settings) {
+    const processor = unified().use(plugin, ...settings);
+    /** @type {import('unified').Transformer} */
+    return async function transformer(tree, file) {
+      const previousMessages = file.messages.length;
+      await processor.run(tree, file);
+      file.messages = file.messages.filter((message, index) => {
+        const node = message.ancestors?.at(-1);
+        return !(
+          index >= previousMessages &&
+          node?.type === 'definition' &&
+          'identifier' in node &&
+          node.identifier === '//' &&
+          'title' in node &&
+          typeof node.title === 'string' &&
+          node.title.length > 0
+        );
+      });
+    };
+  };
+}
+
+/**
+ * Makes the processor output the source text unchanged. The preset only lints, and
+ * remark-stringify doesn't round-trip Markdown (it escapes GitHub alerts, rewrites bare
+ * URLs, ...). eslint-plugin-mdx offers the processed output as a whole-file fix for any
+ * remark message, so with this `eslint --fix` leaves Markdown alone.
+ *
+ * @this {import('unified').Processor}
+ */
+function remarkPreserveSource() {
+  this.compiler = (_tree, file) => String(file);
+}
+
 /**
  * Returns a remark preset wiring the MUI-authored remark-lint plugins together
  * with a curated set of community plugins. Drop this into `.remarkrc.mjs`:
@@ -120,9 +163,11 @@ function withOverrides(name, plugin, baseSettings, overrideEntries) {
  * ```
  *
  * @param {Object} [options]
+ * @param {boolean} [options.allowDefinitionComments=false] Allow titled `[//]` link-reference comments.
  * @param {Array<{ files: string | string[], rules: Record<string, false | unknown[]> }>} [options.overrides]
+ * @returns {import('unified').Preset}
  */
-export function createRemarkConfig({ overrides = [] } = {}) {
+export function createRemarkConfig({ overrides = [], allowDefinitionComments = false } = {}) {
   for (const override of overrides) {
     const unknown = Object.keys(override.rules).filter((ruleName) => !(ruleName in RULES));
     if (unknown.length > 0) {
@@ -130,10 +175,14 @@ export function createRemarkConfig({ overrides = [] } = {}) {
     }
   }
 
+  /** @type {import('unified').PluggableList} */
   const entries = Object.entries(RULES).map(([name, entry]) => {
-    const [plugin, baseSettings] = /** @type {[import('unified').Plugin<any[], any, any>, any]} */ (
-      entry
-    );
+    const [rulePlugin, baseSettings] =
+      /** @type {[import('unified').Plugin<any[], any, any>, any]} */ (entry);
+    const plugin =
+      allowDefinitionComments && (name === 'no-empty-url' || name === 'no-unused-definitions')
+        ? withDefinitionComments(rulePlugin)
+        : rulePlugin;
     const overrideEntries = overrides
       .filter((override) => name in override.rules)
       .map((override) => ({ files: override.files, settings: override.rules[name] }));
@@ -144,14 +193,12 @@ export function createRemarkConfig({ overrides = [] } = {}) {
   });
 
   return {
-    settings: {
-      bullet: '-',
-      emphasis: '_',
-      fence: '`',
-      listItemIndent: 'one',
-      resourceLink: true,
-      rule: '-',
-    },
-    plugins: [[remarkFrontmatter, ['yaml', 'toml']], remarkGfm, remarkLint, ...entries],
+    plugins: [
+      [remarkFrontmatter, ['yaml', 'toml']],
+      remarkGfm,
+      remarkLint,
+      ...entries,
+      remarkPreserveSource,
+    ],
   };
 }

package/src/utils/build.mjs

@@ -1,5 +1,6 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
+import getTargets from '@babel/helper-compilation-targets';
 import { globby } from 'globby';
 import * as semver from 'semver';
 
@@ -867,6 +868,39 @@ export function validatePkgJson(packageJson, options = {}) {
   }
 }
 
+/**
+ * Validates that "engines.node" in package.json doesn't allow Node.js versions older than the
+ * "node" browserslist environment, which the CommonJS bundle is compiled for. Otherwise the
+ * build can emit syntax that the oldest supported Node.js version can't run.
+ * Targets are resolved the same way `@babel/preset-env` resolves them during the build.
+ * @param {{ name?: string; engines?: { node?: string } }} packageJson
+ * @param {string} cwd - The package directory, used to find the browserslist config.
+ */
+export function validateEnginesNode(packageJson, cwd) {
+  const enginesNode = packageJson.engines?.node;
+  if (!enginesNode) {
+    return;
+  }
+
+  const minEnginesVersion = semver.minVersion(enginesNode);
+  if (!minEnginesVersion) {
+    throw new Error(
+      `Unable to determine the minimum Node.js version from "engines.node" in "${packageJson.name}" package.json: "${enginesNode}".`,
+    );
+  }
+
+  const targetNode = getTargets(undefined, { configPath: cwd, browserslistEnv: 'node' }).node;
+  if (!targetNode) {
+    return;
+  }
+
+  if (semver.gt(targetNode, minEnginesVersion)) {
+    throw new Error(
+      `"engines.node" in "${packageJson.name}" package.json allows Node.js ${minEnginesVersion.version}, but the "node" browserslist environment compiles for Node.js ${targetNode} and up. Raise "engines.node" to at least ${targetNode}, or lower the "node" browserslist target.`,
+    );
+  }
+}
+
 /**
  * Marks the start and end of a function execution for performance measurement.
  * Uses the Performance API to create marks and measure the duration.

package/src/utils/credentials.mjs

@@ -23,11 +23,12 @@ const accessedCredentials = new Map();
 
 /**
  * @param {string} key
- * @returns {Promise<string | undefined>}
+ * @returns {Promise<string | null>}
  */
 export async function getPassword(key) {
-  if (accessedCredentials.has(key)) {
-    return accessedCredentials.get(key);
+  const cached = accessedCredentials.get(key);
+  if (cached) {
+    return cached;
   }
   let credential = credentials.get(key);
   if (!credential) {

package/src/utils/extractErrorCodes.mjs

@@ -99,9 +99,7 @@ export default async function extractErrorCodes(args) {
   const packages = basePackages.filter(
     (pkg) =>
       // Ignore obvious packages that do not have user-facing errors
-      !pkg.name.startsWith('@mui/internal-') &&
-      !pkg.name.startsWith('@mui-internal/') &&
-      !skipPackages.includes(pkg.name),
+      !pkg.name.startsWith('@mui/internal-') && !skipPackages.includes(pkg.name),
   );
   const files = await Promise.all(packages.map((pkg) => getFilesForPackage(pkg)));
   packages.forEach((pkg, index) => {