@mui/internal-code-infra 0.1.1-canary.12 → 0.1.1-canary.14

package/build/remark/config.d.mts

@@ -1,5 +1,3 @@
-import remarkGfm from 'remark-gfm';
-import remarkLint from 'remark-lint';
 /**
  * Returns a remark preset wiring the MUI-authored remark-lint plugins together
  * with a curated set of community plugins. Drop this into `.remarkrc.mjs`:
@@ -23,21 +21,14 @@ import remarkLint from 'remark-lint';
  * ```
  *
  * @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 declare function createRemarkConfig({ overrides }?: {
+export declare function createRemarkConfig({ overrides, allowDefinitionComments }?: {
+    allowDefinitionComments?: boolean;
     overrides?: Array<{
         files: string | string[];
         rules: Record<string, false | unknown[]>;
     }>;
-}): {
-    settings: {
-        bullet: string;
-        emphasis: string;
-        fence: string;
-        listItemIndent: string;
-        resourceLink: boolean;
-        rule: string;
-    };
-    plugins: (any[] | typeof remarkGfm | typeof remarkLint)[];
-};
+}): import('unified').Preset;

package/build/utils/build.d.mts

@@ -93,6 +93,20 @@ export declare function validatePkgJson(packageJson: Record<string, any>, option
     skipMainCheck?: boolean;
     enableReactCompiler?: boolean;
 }): void;
+/**
+ * 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 declare function validateEnginesNode(packageJson: {
+    name?: string;
+    engines?: {
+        node?: string;
+    };
+}, cwd: string): void;
 /**
  * Marks the start and end of a function execution for performance measurement.
  * Uses the Performance API to create marks and measure the duration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-code-infra",
-  "version": "0.1.1-canary.12",
+  "version": "0.1.1-canary.14",
   "author": "MUI Team",
   "description": "Infra scripts and configs to be used across MUI repos.",
   "license": "MIT",
@@ -56,6 +56,7 @@
     "@argos-ci/core": "6.8.7",
     "@babel/cli": "^8.0.6",
     "@babel/core": "^8.0.7",
+    "@babel/helper-compilation-targets": "^8.0.7",
     "@babel/plugin-syntax-jsx": "^8.0.1",
     "@babel/plugin-syntax-typescript": "^8.0.3",
     "@babel/plugin-transform-react-pure-annotations": "^8.0.1",
@@ -189,7 +190,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitSha": "e15cf53015fb529c870cbc6ed088429355435928",
+  "gitSha": "a8db5a1b050cfffe37636173e3d1e18537baaca1",
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typescript": "tsc -noEmit",

package/src/cli/cmdBuild.mjs

@@ -12,6 +12,7 @@ import {
   createPackageExports,
   createPackageImports,
   getOutExtension,
+  validateEnginesNode,
   validatePkgJson,
 } from '../utils/build.mjs';
 import { readPnpmConfig } from '../utils/pnpm.mjs';
@@ -266,6 +267,7 @@ export default /** @type {import('yargs').CommandModule<{}, Args>} */ ({
     const pkgJsonPath = path.join(cwd, 'package.json');
     const packageJson = JSON.parse(await fs.readFile(pkgJsonPath, { encoding: 'utf8' }));
     validatePkgJson(packageJson, { skipMainCheck: args.skipMainCheck, enableReactCompiler });
+    validateEnginesNode(packageJson, cwd);
 
     const buildDirBase = /** @type {string} */ (packageJson.publishConfig?.directory);
     const buildDir = path.join(cwd, buildDirBase);

package/src/remark/config.mjs

@@ -97,6 +97,37 @@ 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
+        );
+      });
+    };
+  };
+}
+
 /**
  * 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 +151,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 +163,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] }));

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.