@mui/internal-code-infra 0.0.3-canary.8 → 0.0.3-canary.81

package/README.md

@@ -1,3 +1,58 @@
 # @mui/internal-code-infra
 
 Scripts and configs to be used across MUI repos.
+
+## Documentation
+
+This is stored in the `docs` top-level directory.
+
+[Read in Markdown](../../docs/app/code-infra/page.mdx)
+
+[Read in Browser](https://mui-internal.netlify.app/code-infra)
+
+## Publishing packages
+
+1. Go to the publish action -
+
+- [Base UI](https://github.com/mui/base-ui/actions/workflows/publish.yml)
+- [Core](https://github.com/mui/material-ui/actions/workflows/publish.yml)
+- [MUI X](https://github.com/mui/mui-x/actions/workflows/publish.yml)
+
+2. Choose "Run workflow" dropdown
+
+   > - **Branch:** master
+   > - **Commit SHA to release from:** the commit that contains the merged release on master. This commit is linked to the GitHub release.
+   > - **Run in dry-run mode:** Used for debugging.
+   > - **Create GitHub release:** Keep selected if you want a GitHub release to be automatically created from the changelog.
+   > - **npm dist tag to publish to** Use to publish legacy or canary versions.
+
+3. Click "Run workflow"
+4. Refresh the page to see the newly created workflow, and click it.
+5. The next screen shows "@username requested your review to deploy to npm-publish", click "Review deployments" and authorize your workflow run. **Never approve workflow runs you didn't initiaite.**
+
+> [!IMPORTANT]
+> Go through the below steps if there is an error that says `The following packages are new and need to be published manually first` in the publish flow.
+
+### Adding and publishing new packages
+
+Whenever news packages are added to the repo (that will get published to npm) or a private package is turned into a public one, follow the below steps before invoking the publish workflow of the previous section.
+
+1. Goto your repo's code base on your system, open terminal and run:
+
+```bash
+pnpm code-infra publish-new-package
+```
+
+This command detects the new public packages in the repo and asks for your confirmation before publishing them to the npm registry. Add the `--dryRun` flag to skip the actual publishing.
+
+2. Goto the settings link for each packages, ie, https://www.npmjs.com/package/<pkg-name>/access , and setup `Trusted Publisher`.
+3. In `Select your publisher` step in the above link, click on the `Github Actions` button to configure Github actions based trusted publishing.
+4. Fill in the details of the repo -
+   1. `Organization or user` as `mui`,
+   2. `Repository` as per the new package
+   3. `Workflow filename*` should be `publish.yml`
+   4. `Environment name` should be `npm-publish`
+5. In the `Publishing access` section, toggle the recommended option of `Require two-factor authentication and disallow tokens`.
+6. Finally, save the changes by clicking on `Update Package Settings` button.
+
+After following these steps, the `Publish` workflow can be invoked again.

package/build/babel-config.d.mts

@@ -0,0 +1,40 @@
+/**
+ * @param {Object} param0
+ * @param {boolean} [param0.debug]
+ * @param {boolean} [param0.optimizeClsx]
+ * @param {boolean} [param0.removePropTypes]
+ * @param {boolean} [param0.noResolveImports]
+ * @param {'cjs' | 'esm'} param0.bundle
+ * @param {string | null} param0.outExtension - Specify the output file extension.
+ * @param {string} param0.runtimeVersion
+ * @param {string} [param0.reactCompilerReactVersion]
+ * @param {string} [param0.reactCompilerMode]
+ * @returns {import('@babel/core').TransformOptions} The base Babel configuration.
+ */
+export function getBaseConfig({ debug, optimizeClsx, removePropTypes, noResolveImports, bundle, runtimeVersion, outExtension, reactCompilerReactVersion, reactCompilerMode, }: {
+    debug?: boolean | undefined;
+    optimizeClsx?: boolean | undefined;
+    removePropTypes?: boolean | undefined;
+    noResolveImports?: boolean | undefined;
+    bundle: "cjs" | "esm";
+    outExtension: string | null;
+    runtimeVersion: string;
+    reactCompilerReactVersion?: string | undefined;
+    reactCompilerMode?: string | undefined;
+}): import("@babel/core").TransformOptions;
+/**
+ * @typedef {Object} Options
+ * @prop {'esm' | 'cjs'} [Options.bundle]
+ * @prop {boolean} [Options.noResolveImports]
+ * @prop {undefined} [options.env]
+ */
+/**
+ * @param {import('@babel/core').ConfigAPI | Options} api
+ * @returns {import('@babel/core').TransformOptions}
+ */
+export default function getBabelConfig(api: import("@babel/core").ConfigAPI | Options): import("@babel/core").TransformOptions;
+export type Options = {
+    bundle?: "cjs" | "esm" | undefined;
+    noResolveImports?: boolean | undefined;
+    env?: undefined;
+};

package/build/brokenLinksChecker/index.d.mts

@@ -0,0 +1,178 @@
+/**
+ * Crawls a website starting from seed URLs, discovering all internal links and checking for broken links/targets.
+ * @param {CrawlOptions} rawOptions - Configuration options for the crawl
+ * @returns {Promise<CrawlResult>} Crawl results including all links, pages, and issues found
+ */
+export function crawl(rawOptions: CrawlOptions): Promise<CrawlResult>;
+/**
+ * Maps page URLs to sets of known target IDs (anchors) on that page.
+ * Used to track which link targets (e.g., #section-id) exist on each page.
+ */
+export type LinkStructure = Map<string, Set<string>>;
+/**
+ * Serialized representation of LinkStructure for JSON storage.
+ * Converts Maps and Sets to plain objects and arrays for file persistence.
+ */
+export type SerializedLinkStructure = {
+    /**
+     * - Object mapping page URLs to arrays of target IDs
+     */
+    targets: Record<string, string[]>;
+};
+/**
+ * Data about a crawled page including its URL, HTTP status, and available link targets.
+ */
+export type PageData = {
+    /**
+     * - The normalized page URL (without trailing slash unless root)
+     */
+    url: string;
+    /**
+     * - HTTP status code from the response (e.g., 200, 404, 500)
+     */
+    status: number;
+    /**
+     * - Set of available anchor targets on the page, keyed by hash (e.g., '#intro')
+     */
+    targets: Set<string>;
+    /**
+     * - Content-type of the page (e.g., 'text/html', 'text/markdown')
+     */
+    contentType: string;
+};
+/**
+ * Represents a hyperlink found during crawling.
+ */
+export type Link = {
+    /**
+     * - URL of the page where this link was found, or null for seed URLs
+     */
+    src: string | null;
+    /**
+     * - Accessible name/text content of the link element, or null for seed URLs
+     */
+    text: string | null;
+    /**
+     * - The href attribute value (may be relative or absolute, with or without hash)
+     */
+    href: string;
+    /**
+     * - Content-type of the source page (e.g., 'text/html', 'text/markdown')
+     */
+    contentType?: string | null | undefined;
+};
+/**
+ * Rule for ignoring broken links. All properties are optional but at least one must be defined.
+ * Properties use OR logic internally (any pattern can match), AND logic between properties (all specified must match).
+ */
+export type IgnoreRule = {
+    /**
+     * - Pattern(s) to match source page path
+     */
+    path?: string | RegExp | (string | RegExp)[] | undefined;
+    /**
+     * - Pattern(s) to match broken link href
+     */
+    href?: string | RegExp | (string | RegExp)[] | undefined;
+    /**
+     * - Pattern(s) to match source page content-type
+     */
+    contentType?: string | RegExp | (string | RegExp)[] | undefined;
+};
+/**
+ * Normalized ignore rule where all properties are arrays (or undefined).
+ */
+export type NormalizedIgnoreRule = {
+    path: (string | RegExp)[] | undefined;
+    href: (string | RegExp)[] | undefined;
+    contentType: (string | RegExp)[] | undefined;
+};
+/**
+ * Configuration options for the broken links crawler.
+ */
+export type CrawlOptions = {
+    /**
+     * - Shell command to start the dev server (e.g., 'npm run dev'). If null, assumes server is already running
+     */
+    startCommand?: string | null | undefined;
+    /**
+     * - Base URL of the site to crawl (e.g., 'http://localhost:3000')
+     */
+    host: string;
+    /**
+     * - File path to write discovered link targets to. If null, targets are not persisted
+     */
+    outPath?: string | null | undefined;
+    /**
+     * - Array of regex patterns to exclude from crawling (e.g., [/^\/api\//] to skip /api/* routes)
+     */
+    ignoredPaths?: RegExp[] | undefined;
+    /**
+     * - CSS selectors for elements whose nested links should be ignored (e.g., ['.sidebar', 'footer'])
+     */
+    ignoredContent?: string[] | undefined;
+    /**
+     * - Set of element IDs to ignore as link targets (defaults to '__next', '__NEXT_DATA__')
+     */
+    ignoredTargets?: Set<string> | undefined;
+    /**
+     * - Pre-populated map of known valid targets to skip crawling (useful for external pages)
+     */
+    knownTargets?: Map<string, Set<string>> | undefined;
+    /**
+     * - URLs to fetch known targets from (fetched JSON will be merged with knownTargets)
+     */
+    knownTargetsDownloadUrl?: string[] | undefined;
+    /**
+     * - Number of concurrent page fetches (defaults to 4)
+     */
+    concurrency?: number | undefined;
+    /**
+     * - Starting URLs for the crawl (defaults to ['/'])
+     */
+    seedUrls?: string[] | undefined;
+    /**
+     * - Rules to ignore broken links. Each rule can have path, href, contentType, and/or has properties. All specified properties must match (AND logic). Within a property, multiple values use OR logic.
+     */
+    ignores?: IgnoreRule[] | undefined;
+};
+/**
+ * Fully resolved configuration with all optional fields filled with defaults.
+ */
+export type ResolvedCrawlOptions = Omit<Required<CrawlOptions>, "ignores"> & {
+    ignores: NormalizedIgnoreRule[];
+};
+/**
+ * Represents a broken link or broken link target discovered during crawling.
+ */
+export type Issue = {
+    /**
+     * - Type of issue: 'broken-link' for 404 pages, 'broken-target' for missing anchors
+     */
+    type: "broken-link" | "broken-target";
+    /**
+     * - Human-readable description of the issue (e.g., 'Target not found', 'Page returned error 404')
+     */
+    message: string;
+    /**
+     * - The link object that has the issue
+     */
+    link: Link;
+};
+/**
+ * Results from a complete crawl operation.
+ */
+export type CrawlResult = {
+    /**
+     * - All links discovered during the crawl
+     */
+    links: Set<Link>;
+    /**
+     * - All pages crawled, keyed by normalized URL
+     */
+    pages: Map<string, PageData>;
+    /**
+     * - All broken links and broken targets found
+     */
+    issues: Issue[];
+};

package/build/cli/cmdArgosPush.d.mts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+declare const _default: import("yargs").CommandModule<{}, Args>;
+export default _default;
+export type Args = {
+    /**
+     * - Run with verbose logging
+     */
+    verbose?: boolean | undefined;
+    /**
+     * - Screenshots folder path
+     */
+    folder: string;
+};

package/build/cli/cmdBuild.d.mts

@@ -0,0 +1,56 @@
+declare const _default: import("yargs").CommandModule<{}, Args>;
+export default _default;
+export type Args = {
+    /**
+     * - The bundles to build.
+     */
+    bundle: import("../utils/build.mjs").BundleType[];
+    /**
+     * - The large files to build.
+     */
+    hasLargeFiles: boolean;
+    /**
+     * - Whether to skip generating a package.json file in the /esm folder.
+     */
+    skipBundlePackageJson: boolean;
+    /**
+     * - The directory to copy the cjs files to.
+     */
+    cjsOutDir: string;
+    /**
+     * - Whether to enable verbose logging.
+     */
+    verbose: boolean;
+    /**
+     * - Whether to build types for the package.
+     */
+    buildTypes: boolean;
+    /**
+     * - Whether to build types for the package.
+     */
+    skipTsc: boolean;
+    /**
+     * - Whether to skip checking for Babel runtime dependencies in the package.
+     */
+    skipBabelRuntimeCheck: boolean;
+    /**
+     * - Whether to skip generating the package.json file in the bundle output.
+     */
+    skipPackageJson: boolean;
+    /**
+     * - Whether to skip checking for main field in package.json.
+     */
+    skipMainCheck: boolean;
+    /**
+     * - Globs to be ignored by Babel.
+     */
+    ignore: string[];
+    /**
+     * - Files/Directories to be copied. Can be a glob pattern.
+     */
+    copy?: string[] | undefined;
+    /**
+     * - Whether to use the React compiler.
+     */
+    enableReactCompiler?: boolean | undefined;
+};

package/build/cli/cmdCopyFiles.d.mts

@@ -0,0 +1,20 @@
+declare const _default: import("yargs").CommandModule<{}, Args>;
+export default _default;
+export type Args = {
+    /**
+     * Run in silent mode without logging
+     */
+    silent?: boolean | undefined;
+    /**
+     * Exclude default files from the copy operation
+     */
+    excludeDefaults?: boolean | undefined;
+    /**
+     * Glob patterns to copy
+     */
+    glob?: string[] | undefined;
+    /**
+     * Extra files to copy
+     */
+    files?: string[] | undefined;
+};

package/build/cli/cmdExtractErrorCodes.d.mts

@@ -0,0 +1,3 @@
+declare const _default: import("yargs").CommandModule<{}, Args>;
+export default _default;
+export type Args = import("../utils/extractErrorCodes.mjs").Args;

package/build/cli/cmdGithubAuth.d.mts

@@ -0,0 +1,6 @@
+declare const _default: import("yargs").CommandModule<{}, Args>;
+export default _default;
+export type Args = {
+    authorize: boolean;
+    clear: boolean;
+};

package/build/cli/cmdListWorkspaces.d.mts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+declare const _default: import("yargs").CommandModule<{}, Args>;
+export default _default;
+export type PublicPackage = import("../utils/pnpm.mjs").PublicPackage;
+export type Args = {
+    /**
+     * - Whether to filter to only public packages
+     */
+    publicOnly?: boolean | undefined;
+    /**
+     * - Output format (name, path, or json)
+     */
+    output?: "name" | "path" | "json" | "publish-dir" | undefined;
+    /**
+     * - Git reference to filter changes since
+     */
+    sinceRef?: string | undefined;
+};

package/build/cli/cmdPublish.d.mts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+declare const _default: import("yargs").CommandModule<{}, Args>;
+export default _default;
+export type Args = {
+    /**
+     * Run in dry-run mode without publishing
+     */
+    "dry-run": boolean;
+    /**
+     * Create a GitHub draft release after publishing
+     */
+    "github-release": boolean;
+    /**
+     * NPM dist tag to publish to
+     */
+    tag: string;
+    /**
+     * Runs in CI environment
+     */
+    ci: boolean;
+    /**
+     * Git SHA to use for the GitHub release workflow (local only)
+     */
+    sha?: string | undefined;
+};
+export type PublicPackage = import("../utils/pnpm.mjs").PublicPackage;
+export type PublishOptions = import("../utils/pnpm.mjs").PublishOptions;

package/build/cli/cmdPublishCanary.d.mts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+declare const _default: import("yargs").CommandModule<{}, Args>;
+export default _default;
+export type Commit = {
+    /**
+     * - Commit SHA
+     */
+    sha: string;
+    /**
+     * - Commit message
+     */
+    message: string;
+    /**
+     * - Commit author
+     */
+    author: string;
+};
+export type PublicPackage = import("../utils/pnpm.mjs").PublicPackage;
+export type VersionInfo = import("../utils/pnpm.mjs").VersionInfo;
+export type PublishOptions = import("../utils/pnpm.mjs").PublishOptions;
+export type Args = {
+    /**
+     * - Whether to run in dry-run mode
+     */
+    dryRun?: boolean | undefined;
+    /**
+     * - Whether to create GitHub releases for canary packages
+     */
+    githubRelease?: boolean | undefined;
+};

package/build/cli/cmdPublishNewPackage.d.mts

@@ -0,0 +1,8 @@
+declare const _default: import("yargs").CommandModule<{}, Args>;
+export default _default;
+export type Args = {
+    /**
+     * If true, will only log the commands without executing them
+     */
+    dryRun?: boolean | undefined;
+};

package/build/cli/cmdSetVersionOverrides.d.mts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+declare const _default: import("yargs").CommandModule<{}, Args>;
+export default _default;
+export type Args = {
+    /**
+     * - Package version specifiers in format 'package@version'
+     */
+    pkg?: string[] | undefined;
+};

package/build/cli/cmdValidateBuiltTypes.d.mts

@@ -0,0 +1,2 @@
+declare const _default: import("yargs").CommandModule<{}, {}>;
+export default _default;

package/build/cli/index.d.mts

@@ -0,0 +1 @@
+export {};

package/build/eslint/baseConfig.d.mts

@@ -0,0 +1,12 @@
+/**
+ * @param {Object} [params]
+ * @param {boolean} [params.enableReactCompiler] - Whether to enable React Compiler.
+ * @param {boolean} [params.consistentTypeImports] - Whether to enforce consistent type imports.
+ * @param {string} [params.baseDirectory] - The base directory for the configuration.
+ * @returns {import('eslint').Linter.Config[]}
+ */
+export function createBaseConfig({ enableReactCompiler, consistentTypeImports, baseDirectory, }?: {
+    enableReactCompiler?: boolean | undefined;
+    consistentTypeImports?: boolean | undefined;
+    baseDirectory?: string | undefined;
+}): import("eslint").Linter.Config[];

package/build/eslint/docsConfig.d.mts

@@ -0,0 +1,4 @@
+/**
+ * @returns {import('eslint').Linter.Config[]}
+ */
+export function createDocsConfig(): import("eslint").Linter.Config[];

package/build/eslint/extensions.d.mts

@@ -0,0 +1,8 @@
+export const EXTENSION_JS: ".?(c|m)js?(x)";
+export const EXTENSION_JS_NO_MODULE: ".js?(x)";
+export const EXTENSION_TS: ".?(c|m)[jt]s?(x)";
+export const EXTENSION_TS_NO_MODULE: ".[jt]s?(x)";
+export const EXTENSION_TS_ONLY: ".?(c|m)ts?(x)";
+export const EXTENSION_TS_ONLY_NO_MODULE: ".ts?(x)";
+export const EXTENSION_DTS: ".d.?(c|m)ts?(x)";
+export const EXTENSION_TEST_FILE: ".test.?(c|m)[jt]s?(x)";

package/build/eslint/index.d.mts

@@ -0,0 +1,4 @@
+export * from "./baseConfig.mjs";
+export * from "./docsConfig.mjs";
+export * from "./testConfig.mjs";
+export * from "./extensions.mjs";

package/build/eslint/jsonConfig.d.mts

@@ -0,0 +1,4 @@
+/**
+ * @returns {import('eslint').Linter.Config[]}
+ */
+export function createJsonConfig(): import("eslint").Linter.Config[];

package/build/eslint/material-ui/config.d.mts

@@ -0,0 +1,10 @@
+/**
+ * @param {Object} [options]
+ * @param {boolean} [options.enableReactCompiler] - Whether to enable React Compiler.
+ * @param {boolean} [options.consistentTypeImports] - Whether to enforce consistent type imports.
+ * @returns {import('eslint').Linter.Config[]}
+ */
+export function createCoreConfig(options?: {
+    enableReactCompiler?: boolean | undefined;
+    consistentTypeImports?: boolean | undefined;
+}): import("eslint").Linter.Config[];

package/build/eslint/material-ui/index.d.mts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint").ESLint.Plugin;
+export default _default;

package/build/eslint/material-ui/rules/add-undef-to-optional.d.mts

@@ -0,0 +1,5 @@
+declare const _default: ESLintUtils.RuleModule<"addUndefined", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+export default _default;
+import { ESLintUtils } from '@typescript-eslint/utils';

package/build/eslint/material-ui/rules/consistent-production-guard.d.mts

@@ -0,0 +1,36 @@
+export default rule;
+/**
+ * ESLint rule that enforces consistent patterns for production guard checks.
+ *
+ * @example
+ * // Valid - comparing with 'production'
+ * if (process.env.NODE_ENV !== 'production') {}
+ *
+ * @example
+ * // Valid - comparing with 'production'
+ * if (process.env.NODE_ENV === 'production') {}
+ *
+ * @example
+ * // Invalid - comparing with 'development'
+ * if (process.env.NODE_ENV === 'development') {}
+ *
+ * @example
+ * // Invalid - comparing with 'test'
+ * if (process.env.NODE_ENV !== 'test') {}
+ *
+ * @example
+ * // Invalid - non-static construct
+ * const env = 'production';
+ * if (process.env.NODE_ENV !== env) {}
+ *
+ * @example
+ * // Usage in ESLint config
+ * {
+ *   rules: {
+ *     'material-ui/consistent-production-guard': 'error'
+ *   }
+ * }
+ *
+ * @type {import('eslint').Rule.RuleModule}
+ */
+declare const rule: import("eslint").Rule.RuleModule;

package/build/eslint/material-ui/rules/disallow-active-element-as-key-event-target.d.mts

@@ -0,0 +1,5 @@
+export default rule;
+/**
+ * @type {import('eslint').Rule.RuleModule}
+ */
+declare const rule: import("eslint").Rule.RuleModule;

package/build/eslint/material-ui/rules/disallow-react-api-in-server-components.d.mts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;

package/build/eslint/material-ui/rules/docgen-ignore-before-comment.d.mts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;

package/build/eslint/material-ui/rules/mui-name-matches-component-name.d.mts

@@ -0,0 +1,5 @@
+export default rule;
+/**
+ * @type {import('eslint').Rule.RuleModule}
+ */
+declare const rule: import("eslint").Rule.RuleModule;

package/build/eslint/material-ui/rules/no-empty-box.d.mts

@@ -0,0 +1,5 @@
+export default rule;
+/**
+ * @type {import('eslint').Rule.RuleModule}
+ */
+declare const rule: import("eslint").Rule.RuleModule;

package/build/eslint/material-ui/rules/no-restricted-resolved-imports.d.mts

@@ -0,0 +1,12 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;
+export type PatternConfig = {
+    /**
+     * - The pattern to match against resolved imports
+     */
+    pattern: string;
+    /**
+     * - Custom message to show when the pattern matches
+     */
+    message?: string | undefined;
+};

package/build/eslint/material-ui/rules/no-styled-box.d.mts

@@ -0,0 +1,5 @@
+export default rule;
+/**
+ * @type {import('eslint').Rule.RuleModule}
+ */
+declare const rule: import("eslint").Rule.RuleModule;

package/build/eslint/material-ui/rules/nodeEnvUtils.d.mts

@@ -0,0 +1,23 @@
+/**
+ * Shared utilities for ESLint rules dealing with process.env.NODE_ENV
+ */
+/**
+ * Checks if a node is process.env.NODE_ENV
+ * @param {import('estree').Node} node
+ * @returns {boolean}
+ */
+export function isProcessEnvNodeEnv(node: import("estree").Node): boolean;
+/**
+ * Checks if a node is a Literal with a specific value
+ * @param {import('estree').Node} node
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isLiteralEq(node: import("estree").Node, value: string): boolean;
+/**
+ * Checks if a node is a Literal with a value not equal to the specified one
+ * @param {import('estree').Node} node
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isLiteralNeq(node: import("estree").Node, value: string): boolean;