@mui/internal-code-infra 0.0.4-canary.3 → 0.0.4-canary.31

package/src/brokenLinksChecker/index.mjs

@@ -1,21 +1,17 @@
 /* eslint-disable no-console */
 import { execaCommand } from 'execa';
 import timers from 'node:timers/promises';
-import { parse } from 'node-html-parser';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import chalk from 'chalk';
 import { Transform } from 'node:stream';
-import contentType from 'content-type';
-import { unified } from 'unified';
-import remarkParse from 'remark-parse';
-import remarkGfm from 'remark-gfm';
-import remarkRehype from 'remark-rehype';
-import rehypeSlug from 'rehype-slug';
-import rehypeStringify from 'rehype-stringify';
+import { Worker } from 'node:worker_threads';
 
 const DEFAULT_CONCURRENCY = 4;
 
+const crawlWorkerUrl = new URL('./crawlWorker.mjs', import.meta.url);
+
 /**
  * Creates a Transform stream that prefixes each line with a given string.
  * Useful for distinguishing server logs from other output.
@@ -105,6 +101,30 @@ function deserializeLinkStructure(data) {
   return linkStructure;
 }
 
+/**
+ * Input data passed to the crawl worker via workerData.
+ * @typedef {Object} CrawlWorkerInput
+ * @property {string} pageUrl - The page URL to crawl
+ * @property {ResolvedCrawlOptions} options - Fully resolved crawl options
+ */
+
+/**
+ * Serialized page data returned by the crawl worker (uses arrays instead of Sets for structured clone).
+ * @typedef {Object} CrawlWorkerPageData
+ * @property {string} url - The normalized page URL
+ * @property {number} status - HTTP status code
+ * @property {string[]} targets - Array of anchor targets (e.g., '#intro')
+ * @property {string} contentType - Content-type of the page
+ */
+
+/**
+ * Output message posted by the crawl worker.
+ * @typedef {Object} CrawlWorkerOutput
+ * @property {CrawlWorkerPageData} pageData - Serialized page data
+ * @property {Link[]} links - Links discovered on the page
+ * @property {{ pageUrl: string, results: import('html-validate').Result[] } | null} htmlValidateResults - HTML validation results, or null if validation was skipped/passed
+ */
+
 /**
  * Data about a crawled page including its URL, HTTP status, and available link targets.
  * @typedef {Object} PageData
@@ -131,77 +151,6 @@ async function writePagesToFile(pages, outPath) {
   await fs.writeFile(outPath, JSON.stringify(fileContent, null, 2), 'utf-8');
 }
 
-/**
- * Computes the accessible name of an element according to ARIA rules.
- * Polyfill for `node.computedName` available only in Chrome v112+.
- * Checks in order: aria-label, aria-labelledby, label[for], img alt, innerText.
- * @param {import('node-html-parser').HTMLElement | null} elm - Element to compute name for
- * @param {import('node-html-parser').HTMLElement} ownerDocument - Document containing the element
- * @returns {string} The computed accessible name, or empty string if none found
- */
-function getAccessibleName(elm, ownerDocument) {
-  if (!elm) {
-    return '';
-  }
-
-  // 1. aria-label
-  const ariaLabel = elm.getAttribute('aria-label')?.trim();
-  if (ariaLabel) {
-    return ariaLabel;
-  }
-
-  // 2. aria-labelledby
-  const labelledby = elm.getAttribute('aria-labelledby');
-  if (labelledby) {
-    const labels = [];
-    for (const id of labelledby.split(/\s+/)) {
-      const label = getAccessibleName(ownerDocument.getElementById(id), ownerDocument);
-      if (label) {
-        labels.push(label);
-      }
-    }
-    const label = labels.join(' ').trim();
-    if (label) {
-      return label;
-    }
-  }
-
-  // 3. <label for="id">
-  if (elm.id) {
-    const label = ownerDocument.querySelector(`label[for="${elm.id}"]`);
-    if (label) {
-      return getAccessibleName(label, ownerDocument);
-    }
-  }
-
-  // 4. <img alt="">
-  if (elm.tagName === 'IMG') {
-    const alt = elm.getAttribute('alt')?.trim();
-    if (alt) {
-      return alt;
-    }
-  }
-
-  // 5. Fallback: visible text
-  return elm.innerText.trim();
-}
-
-/**
- * Converts markdown content to HTML using unified pipeline.
- * @param {string} markdown - Raw markdown content
- * @returns {Promise<string>} Converted HTML string
- */
-async function markdownToHtml(markdown) {
-  const result = await unified()
-    .use(remarkParse)
-    .use(remarkGfm)
-    .use(remarkRehype)
-    .use(rehypeSlug)
-    .use(rehypeStringify)
-    .process(markdown);
-  return String(result);
-}
-
 /**
  * Generic concurrent task queue with configurable concurrency limit.
  * Processes tasks in FIFO order with a maximum number of concurrent workers.
@@ -402,11 +351,12 @@ function shouldIgnoreLink(link, ignores) {
  * @property {number} [concurrency] - Number of concurrent page fetches (defaults to 4)
  * @property {string[]} [seedUrls] - Starting URLs for the crawl (defaults to ['/'])
  * @property {IgnoreRule[]} [ignores] - 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.
+ * @property {boolean | import('html-validate').ConfigData} [htmlValidate] - Enable HTML validation on crawled pages. `false` (default): disabled. `true`: validate with recommended rules. Object: use as html-validate config (supports `extends: ['mui:recommended']` to reference the default config).
  */
 
 /**
  * Fully resolved configuration with all optional fields filled with defaults.
- * @typedef {Omit<Required<CrawlOptions>, 'ignores'> & { ignores: NormalizedIgnoreRule[] }} ResolvedCrawlOptions
+ * @typedef {Omit<Required<CrawlOptions>, 'ignores' | 'htmlValidate'> & { ignores: NormalizedIgnoreRule[], htmlValidate: import('html-validate').ConfigData | null }} ResolvedCrawlOptions
  */
 
 /**
@@ -422,6 +372,21 @@ function validateIgnoreRule(rule) {
   }
 }
 
+/**
+ * Resolves the htmlValidate option into an html-validate config object or null.
+ * @param {boolean | import('html-validate').ConfigData | undefined} option
+ * @returns {import('html-validate').ConfigData | null}
+ */
+function resolveHtmlValidateConfig(option) {
+  if (!option) {
+    return null;
+  }
+  if (option === true) {
+    return { extends: ['mui:recommended'] };
+  }
+  return option;
+}
+
 /**
  * Resolves partial crawl options by filling in defaults for all optional fields.
  * @param {CrawlOptions} rawOptions - Partial options from user
@@ -447,6 +412,7 @@ function resolveOptions(rawOptions) {
     concurrency: rawOptions.concurrency ?? DEFAULT_CONCURRENCY,
     seedUrls: rawOptions.seedUrls ?? ['/'],
     ignores: normalizedIgnores,
+    htmlValidate: resolveHtmlValidateConfig(rawOptions.htmlValidate),
   };
 }
 
@@ -506,25 +472,42 @@ async function resolveKnownTargets(options) {
 
 /**
  * Represents a broken link or broken link target discovered during crawling.
- * @typedef {Object} Issue
+ * @typedef {Object} BrokenLinkIssue
  * @property {'broken-link' | 'broken-target'} type - Type of issue: 'broken-link' for 404 pages, 'broken-target' for missing anchors
  * @property {string} message - Human-readable description of the issue (e.g., 'Target not found', 'Page returned error 404')
  * @property {Link} link - The link object that has the issue
  */
 
+/**
+ * Represents an HTML validation issue found on a crawled page.
+ * @typedef {Object} HtmlValidateIssue
+ * @property {'html-validate'} type - Issue type discriminator
+ * @property {string} message - Human-readable description of the issue
+ * @property {string} pageUrl - The page URL where the issue was found
+ * @property {string} ruleId - The html-validate rule that triggered this issue (e.g., 'no-dup-id')
+ * @property {number} severity - Severity level (1 = warning, 2 = error)
+ * @property {{ line: number, column: number }} location - Source location of the issue
+ * @property {string | null} selector - DOM selector for the element, or null
+ */
+
+/**
+ * Any issue discovered during crawling.
+ * @typedef {BrokenLinkIssue | HtmlValidateIssue} Issue
+ */
+
 /**
  * Results from a complete crawl operation.
  * @typedef {Object} CrawlResult
  * @property {Set<Link>} links - All links discovered during the crawl
  * @property {Map<string, PageData>} pages - All pages crawled, keyed by normalized URL
- * @property {Issue[]} issues - All broken links and broken targets found
+ * @property {Issue[]} issues - All issues found (broken links, broken targets, and HTML validation issues)
  */
 
 /**
  * Reports broken links to stderr, grouped by source page for better readability.
- * @param {Issue[]} issuesList - Array of issues to report
+ * @param {BrokenLinkIssue[]} issuesList - Array of broken link issues to report
  */
-function reportIssues(issuesList) {
+function reportBrokenLinks(issuesList) {
   if (issuesList.length === 0) {
     return;
   }
@@ -532,7 +515,7 @@ function reportIssues(issuesList) {
   console.error('\nBroken links found:\n');
 
   // Group issues by source URL
-  /** @type {Map<string, Issue[]>} */
+  /** @type {Map<string, BrokenLinkIssue[]>} */
   const issuesBySource = new Map();
   for (const issue of issuesList) {
     const sourceUrl = issue.link.src ?? '(unknown)';
@@ -553,6 +536,39 @@ function reportIssues(issuesList) {
   }
 }
 
+/**
+ * Reports HTML validation issues to stderr, grouped by page URL.
+ * @param {HtmlValidateIssue[]} htmlIssues - Array of HTML validation issues to report
+ */
+function reportHtmlValidation(htmlIssues) {
+  if (htmlIssues.length === 0) {
+    return;
+  }
+
+  console.error('\nHTML validation issues:\n');
+
+  // Group by page URL
+  /** @type {Map<string, HtmlValidateIssue[]>} */
+  const issuesByPage = new Map();
+  for (const issue of htmlIssues) {
+    const pageIssues = issuesByPage.get(issue.pageUrl) ?? [];
+    if (pageIssues.length === 0) {
+      issuesByPage.set(issue.pageUrl, pageIssues);
+    }
+    pageIssues.push(issue);
+  }
+
+  for (const [pageUrl, pageIssues] of issuesByPage.entries()) {
+    console.error(`Page ${chalk.cyan(pageUrl)}:`);
+    for (const issue of pageIssues) {
+      const severityLabel = issue.severity === 2 ? chalk.red('error') : chalk.yellow('warning');
+      console.error(
+        `  ${issue.location.line}:${issue.location.column}  ${severityLabel}  ${issue.message}  ${chalk.gray(issue.ruleId)}`,
+      );
+    }
+  }
+}
+
 /**
  * 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
@@ -594,6 +610,35 @@ export async function crawl(rawOptions) {
   const crawledPages = new Map();
   /** @type {Set<Link>} */
   const crawledLinks = new Set();
+  /** @type {Issue[]} */
+  const issues = [];
+  /**
+   * Spawns a crawl worker for a page URL.
+   * @param {string} pageUrl - The page URL to crawl
+   * @returns {Promise<{ pageData: PageData, links: Link[], htmlValidateResults: CrawlWorkerOutput['htmlValidateResults'] }>}
+   */
+  function crawlInWorker(pageUrl) {
+    return new Promise((resolve, reject) => {
+      /** @type {CrawlWorkerInput} */
+      const input = { pageUrl, options };
+      const worker = new Worker(crawlWorkerUrl, {
+        workerData: input,
+      });
+      worker.on('message', (/** @type {CrawlWorkerOutput} */ msg) => {
+        resolve({
+          pageData: {
+            url: msg.pageData.url,
+            status: msg.pageData.status,
+            targets: new Set(msg.pageData.targets),
+            contentType: msg.pageData.contentType,
+          },
+          links: msg.links,
+          htmlValidateResults: msg.htmlValidateResults,
+        });
+      });
+      worker.on('error', (err) => reject(err));
+    });
+  }
 
   const queue = new Queue(async (/** @type {Link} */ link) => {
     crawledLinks.add(link);
@@ -611,78 +656,30 @@ export async function crawl(rawOptions) {
       return;
     }
 
-    const pagePromise = Promise.resolve().then(async () => {
-      console.log(`Crawling ${chalk.cyan(pageUrl)}...`);
-      const res = await fetch(new URL(pageUrl, options.host));
-
-      const contentTypeHeader = res.headers.get('content-type');
-      let type = 'text/html';
-
-      if (contentTypeHeader) {
-        try {
-          const parsed = contentType.parse(contentTypeHeader);
-          type = parsed.type;
-        } catch {
-          console.warn(
-            chalk.yellow(`Warning: ${pageUrl} returned invalid content-type: ${contentTypeHeader}`),
-          );
-        }
-      }
-
-      /** @type {PageData} */
-      const pageData = {
-        url: pageUrl,
-        status: res.status,
-        targets: new Set(),
-        contentType: type,
-      };
-
-      if (pageData.status < 200 || pageData.status >= 400) {
-        console.warn(chalk.yellow(`Warning: ${pageUrl} returned status ${pageData.status}`));
-        return pageData;
-      }
-
-      if (type.startsWith('image/')) {
-        // Skip images
-        return pageData;
-      }
-
-      if (type !== 'text/html' && type !== 'text/markdown') {
-        console.warn(chalk.yellow(`Warning: ${pageUrl} returned non-HTML content-type: ${type}`));
-        return pageData;
-      }
-
-      const rawContent = await res.text();
-      const content = type === 'text/markdown' ? await markdownToHtml(rawContent) : rawContent;
-
-      const dom = parse(content, { parseNoneClosedTags: true });
-
-      let ignoredSelector = ':not(*)'; // matches nothing
-      if (options.ignoredContent.length > 0) {
-        ignoredSelector = Array.from(options.ignoredContent)
-          .flatMap((selector) => [selector, `${selector} *`])
-          .join(',');
-      }
-      const linksSelector = `a[href]:not(${ignoredSelector})`;
-
-      const pageLinks = dom.querySelectorAll(linksSelector).map((a) => ({
-        src: pageUrl,
-        text: getAccessibleName(a, dom),
-        href: a.getAttribute('href') ?? '',
-        contentType: type,
-      }));
-
-      for (const target of dom.querySelectorAll('*[id]')) {
-        if (!options.ignoredTargets.has(target.id)) {
-          pageData.targets.add(`#${target.id}`);
+    console.log(`Crawling ${chalk.cyan(pageUrl)}...`);
+    const workerPromise = crawlInWorker(pageUrl);
+    const pagePromise = workerPromise.then((result) => {
+      if (result.htmlValidateResults) {
+        for (const validationResult of result.htmlValidateResults.results) {
+          for (const msg of validationResult.messages) {
+            issues.push({
+              type: 'html-validate',
+              message: msg.message,
+              pageUrl: result.htmlValidateResults.pageUrl,
+              ruleId: msg.ruleId,
+              severity: msg.severity,
+              location: { line: msg.line, column: msg.column },
+              selector: msg.selector,
+            });
+          }
         }
       }
 
-      for (const pageLink of pageLinks) {
-        queue.add(pageLink);
+      for (const discoveredLink of result.links) {
+        queue.add(discoveredLink);
       }
 
-      return pageData;
+      return result.pageData;
     });
 
     crawledPages.set(pageUrl, pagePromise);
@@ -711,10 +708,6 @@ export async function crawl(rawOptions) {
     await writePagesToFile(results, options.outPath);
   }
 
-  /** Array to collect all issues found during validation */
-  /** @type {Issue[]} */
-  const issues = [];
-
   /** Count of links ignored due to ignores configuration */
   let ignoredCount = 0;
 
@@ -771,11 +764,24 @@ export async function crawl(rawOptions) {
     }
   }
 
-  reportIssues(issues);
+  // Split issues by type for reporting
+  /** @type {BrokenLinkIssue[]} */
+  const brokenLinkIssues = /** @type {BrokenLinkIssue[]} */ (
+    issues.filter((issue) => issue.type === 'broken-link' || issue.type === 'broken-target')
+  );
+  /** @type {HtmlValidateIssue[]} */
+  const htmlValidateIssues = /** @type {HtmlValidateIssue[]} */ (
+    issues.filter((issue) => issue.type === 'html-validate')
+  );
+
+  reportBrokenLinks(brokenLinkIssues);
+  reportHtmlValidation(htmlValidateIssues);
 
   // Derive counts from issues
-  const brokenLinks = issues.filter((issue) => issue.type === 'broken-link').length;
-  const brokenLinkTargets = issues.filter((issue) => issue.type === 'broken-target').length;
+  const brokenLinks = brokenLinkIssues.filter((issue) => issue.type === 'broken-link').length;
+  const brokenLinkTargets = brokenLinkIssues.filter(
+    (issue) => issue.type === 'broken-target',
+  ).length;
 
   const endTime = Date.now();
   const durationSeconds = (endTime - startTime) / 1000;
@@ -784,14 +790,21 @@ export async function crawl(rawOptions) {
     unit: 'second',
     maximumFractionDigits: 2,
   }).format(durationSeconds);
+  const fmt = new Intl.NumberFormat('en-US').format;
   console.log(chalk.blue(`\nCrawl completed in ${duration}`));
-  console.log(`  Total links found: ${chalk.cyan(crawledLinks.size)}`);
-  console.log(`  Total broken links: ${chalk.cyan(brokenLinks)}`);
-  console.log(`  Total broken link targets: ${chalk.cyan(brokenLinkTargets)}`);
-  console.log(`  Total ignored: ${chalk.cyan(ignoredCount)}`);
+  console.log(`  Total links found: ${chalk.cyan(fmt(crawledLinks.size))}`);
+  console.log(`  Total broken links: ${chalk.cyan(fmt(brokenLinks))}`);
+  console.log(`  Total broken link targets: ${chalk.cyan(fmt(brokenLinkTargets))}`);
+  console.log(`  Total ignored: ${chalk.cyan(fmt(ignoredCount))}`);
+  if (options.htmlValidate) {
+    const pagesWithHtmlIssues = new Set(htmlValidateIssues.map((issue) => issue.pageUrl)).size;
+    console.log(
+      `  HTML validation issues: ${chalk.cyan(fmt(htmlValidateIssues.length))} across ${chalk.cyan(fmt(pagesWithHtmlIssues))} ${pagesWithHtmlIssues === 1 ? 'page' : 'pages'}`,
+    );
+  }
 
   if (options.outPath) {
-    console.log(chalk.blue(`Output written to: ${options.outPath}`));
+    console.log(chalk.blue(`Output written to: ${pathToFileURL(options.outPath)}`));
   }
 
   return { links: crawledLinks, pages: results, issues };

package/src/brokenLinksChecker/index.test.ts

@@ -2,12 +2,18 @@ import path from 'node:path';
 import getPort from 'get-port';
 import { describe, expect, it } from 'vitest';
 
-// eslint-disable-next-line import/extensions
-import { crawl, Issue, Link } from './index.mjs';
-
-type ExpectedIssue = Omit<Partial<Issue>, 'link'> & { link?: Partial<Link> };
-
-function objectMatchingIssue(expectedIssue: ExpectedIssue) {
+import {
+  crawl,
+  type BrokenLinkIssue,
+  type HtmlValidateIssue,
+  type Issue,
+  type Link,
+  // eslint-disable-next-line import/extensions
+} from './index.mjs';
+
+type ExpectedBrokenLinkIssue = Omit<Partial<BrokenLinkIssue>, 'link'> & { link?: Partial<Link> };
+
+function objectMatchingIssue(expectedIssue: ExpectedBrokenLinkIssue) {
   return expect.objectContaining({
     ...expectedIssue,
     ...(expectedIssue.link ? { link: expect.objectContaining(expectedIssue.link) } : {}),
@@ -15,16 +21,16 @@ function objectMatchingIssue(expectedIssue: ExpectedIssue) {
 }
 
 /**
- * Helper to assert that an issue with matching properties exists in the issues array
+ * Helper to assert that a broken link issue with matching properties exists in the issues array
  */
-function expectIssue(issues: Issue[], expectedIssue: ExpectedIssue) {
+function expectIssue(issues: Issue[], expectedIssue: ExpectedBrokenLinkIssue) {
   expect(issues).toEqual(expect.arrayContaining([objectMatchingIssue(expectedIssue)]));
 }
 
 /**
- * Helper to assert that no issue with matching properties exists in the issues array
+ * Helper to assert that no broken link issue with matching properties exists in the issues array
  */
-function expectNotIssue(issues: Issue[], notExpectedIssue: ExpectedIssue) {
+function expectNotIssue(issues: Issue[], notExpectedIssue: ExpectedBrokenLinkIssue) {
   expect(issues).not.toEqual(expect.arrayContaining([objectMatchingIssue(notExpectedIssue)]));
 }
 
@@ -56,12 +62,21 @@ describe('Broken Links Checker', () => {
         // Test href-only rule (matches from any page) - note: matches the actual href value
         { href: 'broken-relative.html' },
       ],
+      htmlValidate: {
+        extends: ['mui:recommended'],
+        rules: {
+          'no-raw-characters': 'off',
+        },
+      },
     });
 
-    expect(result.links).toHaveLength(66);
-    // Issue count: original 11, minus ignored ones (broken-from-markdown via contentType,
+    expect(result.links).toHaveLength(67);
+    // Broken link issue count: original 11, minus ignored ones (broken-from-markdown via contentType,
     // broken-relative via href-only rule)
-    expect(result.issues).toHaveLength(9);
+    const brokenLinkIssues = result.issues.filter(
+      (issue) => issue.type === 'broken-link' || issue.type === 'broken-target',
+    );
+    expect(brokenLinkIssues).toHaveLength(9);
 
     // Test ignores: these broken links should be ignored (not in issues)
     expectNotIssue(result.issues, {
@@ -257,5 +272,32 @@ describe('Broken Links Checker', () => {
     // Test contentType is stored on pageData
     expect(result.pages.get('/example.md')?.contentType).toBe('text/markdown');
     expect(result.pages.get('/')?.contentType).toBe('text/html');
+
+    // Test htmlValidate: invalid-html.html has duplicate IDs which should be reported
+    const htmlValidateIssues = result.issues.filter(
+      (issue): issue is HtmlValidateIssue => issue.type === 'html-validate',
+    );
+    const invalidHtmlIssues = htmlValidateIssues.filter(
+      (issue) => issue.pageUrl === '/invalid-html.html',
+    );
+    expect(invalidHtmlIssues.length).toBeGreaterThan(0);
+    expect(invalidHtmlIssues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          type: 'html-validate',
+          pageUrl: '/invalid-html.html',
+          ruleId: 'no-dup-id',
+        }),
+      ]),
+    );
+
+    // Test htmlValidate override: no-raw-characters is off, so raw & should NOT be reported
+    expect(invalidHtmlIssues).not.toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          ruleId: 'no-raw-characters',
+        }),
+      ]),
+    );
   }, 30000);
 });

package/src/build-env.d.ts

@@ -0,0 +1,13 @@
+export {};
+
+declare global {
+  interface Env {
+    NODE_ENV?: 'production' | undefined;
+  }
+
+  interface Process {
+    env: Env;
+  }
+
+  const process: Process;
+}

package/src/changelog/fetchChangelogs.mjs

@@ -93,8 +93,12 @@ async function fetchCommitsRest({ octokit, repo, lastRelease, release, org = 'mu
   }
 
   const promises = results.map(async (commit) => {
-    const prMatch = commit.commit.message.match(/#(\d+)/);
-    if (prMatch === null) {
+    const matches = [...commit.commit.message.matchAll(/#(\d+)/g)];
+    // The PR number is always the last match.
+    // Sometimes the PR titles include an issue number like this:
+    // [tag] PR title (#00001) (#00002)
+    const prMatch = matches.at(-1);
+    if (!prMatch) {
       return null;
     }
 

package/src/changelog/types.ts

@@ -233,7 +233,7 @@ export interface IntroConfig {
    * - {{teamCount}}: Number of team members
    * - {{communityCount}}: Number of community contributors
    *
-   * Example: "We'd like to extend a big thank you to the {{contributorCount}} contributors who made this release possible"
+   * Example: "A big thanks to the {{contributorCount}} contributors who made this release possible."
    *
    * Set to `false` or omit to disable the thank you message.
    */

package/src/cli/cmdListWorkspaces.mjs

@@ -15,6 +15,7 @@ import { getWorkspacePackages } from '../utils/pnpm.mjs';
  * @property {boolean} [publicOnly] - Whether to filter to only public packages
  * @property {'json'|'path'|'name'|'publish-dir'} [output] - Output format (name, path, or json)
  * @property {string} [sinceRef] - Git reference to filter changes since
+ * @property {string[]} [filter] - Same as filtering packages with --filter in pnpm. Only include packages matching the filter. See https://pnpm.io/filtering.
  */
 
 export default /** @type {import('yargs').CommandModule<{}, Args>} */ ({
@@ -37,13 +38,19 @@ export default /** @type {import('yargs').CommandModule<{}, Args>} */ ({
       .option('since-ref', {
         type: 'string',
         description: 'Filter packages changed since git reference',
+      })
+      .option('filter', {
+        type: 'string',
+        array: true,
+        description:
+          'Same as filtering packages with --filter in pnpm. Only include packages matching the filter. See https://pnpm.io/filtering.',
       });
   },
   handler: async (argv) => {
-    const { publicOnly = false, output = 'name', sinceRef } = argv;
+    const { publicOnly = false, output = 'name', sinceRef, filter = [] } = argv;
 
     // Get packages using our helper function
-    const packages = await getWorkspacePackages({ sinceRef, publicOnly });
+    const packages = await getWorkspacePackages({ sinceRef, publicOnly, filter });
 
     if (output === 'json') {
       // Serialize packages to JSON