@carbon/upgrade 11.44.0 → 11.45.0

package/README.md

@@ -342,6 +342,47 @@ npx @carbon/upgrade migrate slug-prop-to-decorator-prop --write
 <Component decorator="my-identifier">Content</Component>
 ```
 
+### Unstable / preview Pagination to Pagination
+
+Migrates `unstable_Pagination` / `preview_Pagination` to the stable `Pagination`
+component. Drops `PageSelector` imports and children render-props, since the
+stable component renders an equivalent page-select control by default.
+
+**Usage:**
+
+```bash
+npx @carbon/upgrade migrate unstable-pagination-to-pagination --write
+```
+
+**Example:**
+
+```jsx
+// Before
+import {
+  unstable_Pagination as Pagination,
+  unstable_PageSelector as PageSelector,
+} from '@carbon/react';
+
+<Pagination pageSizes={[10, 20, 30]} totalItems={100}>
+  {({ currentPage, onSetPage, totalPages }) => (
+    <PageSelector
+      currentPage={currentPage}
+      onChange={(event) => onSetPage(event.target.value)}
+      totalPages={totalPages}
+    />
+  )}
+</Pagination>;
+
+// After
+import { Pagination } from '@carbon/react';
+
+<Pagination pageSizes={[10, 20, 30]} totalItems={100} />;
+```
+
+Custom page-select children are removed and a `TODO` comment is left to migrate
+them with `renderPageSelect` if needed. Omit `pageSizes` to hide the items per
+page selector.
+
 ### FeatureFlag deprecate flags prop
 
 Updates FeatureFlags component to use individual boolean props instead of the

package/cli.js

@@ -36694,6 +36694,62 @@ const upgrades = [
 			}
 		],
 		migrations: [
+			{
+				name: "wc-report-non-barrel-imports",
+				description: "Report @carbon/web-components class-file (non-barrel) imports that register nothing under v3 pure exports",
+				migrate: async (options) => {
+					const transform = path.default.join(TRANSFORM_DIR, "wc-report-non-barrel-imports.js");
+					const paths = Array.isArray(options.paths) && options.paths.length > 0 ? options.paths : await (0, import_out.default)([
+						"**/*.js",
+						"**/*.jsx",
+						"**/*.ts",
+						"**/*.tsx"
+					], {
+						cwd: options.workspaceDir,
+						ignore: [
+							"**/es/**",
+							"**/lib/**",
+							"**/umd/**",
+							"**/node_modules/**",
+							"**/storybook-static/**"
+						]
+					});
+					await runCodemod(options, {
+						dry: !options.write,
+						transform,
+						paths,
+						verbose: options.verbose
+					});
+				}
+			},
+			{
+				name: "wc-add-barrel-imports",
+				description: "Add/collapse @carbon/web-components component barrel imports so class-file imports still register under v3 pure exports",
+				migrate: async (options) => {
+					const transform = path.default.join(TRANSFORM_DIR, "wc-add-barrel-imports.js");
+					const paths = Array.isArray(options.paths) && options.paths.length > 0 ? options.paths : await (0, import_out.default)([
+						"**/*.js",
+						"**/*.jsx",
+						"**/*.ts",
+						"**/*.tsx"
+					], {
+						cwd: options.workspaceDir,
+						ignore: [
+							"**/es/**",
+							"**/lib/**",
+							"**/umd/**",
+							"**/node_modules/**",
+							"**/storybook-static/**"
+						]
+					});
+					await runCodemod(options, {
+						dry: !options.write,
+						transform,
+						paths,
+						verbose: options.verbose
+					});
+				}
+			},
 			{
 				name: "icons-react-size-prop",
 				description: "Update imports and size usage for @carbon/icons-react",
@@ -37465,6 +37521,39 @@ const upgrades = [
 						parser: "tsx"
 					});
 				}
+			},
+			{
+				name: "unstable-pagination-to-pagination",
+				description: "Replace unstable_Pagination / preview_Pagination with Pagination and remove unstable_PageSelector / preview_PageSelector. Custom page-select children must use renderPageSelect and may need a manual update.",
+				migrate: async (options) => {
+					const transform = path.default.join(TRANSFORM_DIR, "unstable-pagination-to-pagination.js");
+					const paths = Array.isArray(options.paths) && options.paths.length > 0 ? options.paths : await (0, import_out.default)([
+						"**/*.js",
+						"**/*.jsx",
+						"**/*.ts",
+						"**/*.tsx"
+					], {
+						cwd: options.workspaceDir,
+						ignore: [
+							"**/es/**",
+							"**/lib/**",
+							"**/umd/**",
+							"**/node_modules/**",
+							"**/storybook-static/**",
+							"**/dist/**",
+							"**/build/**",
+							"**/*.d.ts",
+							"**/coverage/**"
+						]
+					});
+					await runCodemod(options, {
+						dry: !options.write,
+						transform,
+						paths,
+						verbose: options.verbose,
+						parser: "tsx"
+					});
+				}
 			}
 		]
 	},
@@ -37486,7 +37575,7 @@ const upgrades = [
 //#endregion
 //#region package.json
 var name = "@carbon/upgrade";
-var version = "11.44.0";
+var version = "11.45.0";
 //#endregion
 //#region ../../node_modules/y18n/build/index.cjs
 var require_build$3 = /* @__PURE__ */ __commonJSMin(((exports, module) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@carbon/upgrade",
   "description": "A tool for upgrading Carbon versions",
-  "version": "11.44.0",
+  "version": "11.45.0",
   "license": "Apache-2.0",
   "bin": {
     "carbon-upgrade": "./bin/carbon-upgrade.js"
@@ -60,5 +60,5 @@
     "@ibm/telemetry-js": "^1.5.0",
     "jscodeshift": "^17.0.0"
   },
-  "gitHead": "7518c84ffd00f22434fe19d83119692c12fccb2f"
+  "gitHead": "acdc7d80f45eb01c892b1697403726c4dbc24a57"
 }

package/transforms/__testfixtures__/wc-add-barrel-imports.input.tsx

@@ -0,0 +1,20 @@
+import { html, LitElement } from 'lit';
+// side-effect class imports of one component -> collapse to a single barrel
+import '@carbon/web-components/es/components/data-table/table.js';
+import '@carbon/web-components/es/components/data-table/table-head.js';
+import '@carbon/web-components/es/components/data-table/table-row.js';
+// value import -> keep binding, add barrel alongside
+import CDSButton from '@carbon/web-components/es/components/button/button.js';
+// named value import for a component whose barrel is already present below
+import { CDSSearch } from '@carbon/web-components/es/components/search/search.js';
+import '@carbon/web-components/es/components/search/index.js';
+// type-only -> untouched
+import type CDSModal from '@carbon/web-components/es/components/modal/modal.js';
+// already a barrel -> untouched
+import '@carbon/web-components/es/components/tag/index.js';
+
+export class Widget extends LitElement {
+  render() {
+    return html`<cds-button></cds-button>`;
+  }
+}

package/transforms/__testfixtures__/wc-add-barrel-imports.output.tsx

@@ -0,0 +1,19 @@
+import { html, LitElement } from 'lit';
+// side-effect class imports of one component -> collapse to a single barrel
+import '@carbon/web-components/es/components/data-table/index.js';
+// value import -> keep binding, add barrel alongside
+import CDSButton from '@carbon/web-components/es/components/button/button.js';
+import '@carbon/web-components/es/components/button/index.js';
+// named value import for a component whose barrel is already present below
+import { CDSSearch } from '@carbon/web-components/es/components/search/search.js';
+import '@carbon/web-components/es/components/search/index.js';
+// type-only -> untouched
+import type CDSModal from '@carbon/web-components/es/components/modal/modal.js';
+// already a barrel -> untouched
+import '@carbon/web-components/es/components/tag/index.js';
+
+export class Widget extends LitElement {
+  render() {
+    return html`<cds-button></cds-button>`;
+  }
+}

package/transforms/__tests__/wc-add-barrel-imports-test.js

@@ -0,0 +1,17 @@
+/**
+ * Copyright IBM Corp. 2026
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+const { defineTest } = require('jscodeshift/dist/testUtils');
+
+// covers:
+// - side-effect collapse: i.e. 3 data-table class imports into 1 barrel
+// - default value import: named value import with barrel already present;
+//   type-only imports
+// - tpre-existing barrels
+defineTest(__dirname, 'wc-add-barrel-imports', null, 'wc-add-barrel-imports');

package/transforms/__tests__/wc-report-non-barrel-imports-test.js

@@ -0,0 +1,181 @@
+/**
+ * Copyright IBM Corp. 2026
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+const jscodeshift = require('jscodeshift');
+const { collectNonBarrelWebComponentImports } = require('../carbon-wc-imports');
+const { formatFileBlock } = require('../wc-report-non-barrel-imports');
+
+const j = jscodeshift.withParser('tsx');
+
+function findings(source) {
+  return collectNonBarrelWebComponentImports(j, j(source));
+}
+
+const sampleFindings = [
+  {
+    specifier: '@carbon/web-components/es/components/search/search.js',
+    component: 'search',
+    kind: 'side-effect',
+    typeOnly: false,
+    suggestedBarrel: '@carbon/web-components/es/components/search/index.js',
+    line: 16,
+  },
+  {
+    specifier:
+      '@carbon/web-components/es/components/overflow-menu/overflow-menu-item.js',
+    component: 'overflow-menu',
+    kind: 'default',
+    typeOnly: true,
+    suggestedBarrel:
+      '@carbon/web-components/es/components/overflow-menu/index.js',
+    line: 8,
+  },
+];
+
+describe('collectNonBarrelWebComponentImports', () => {
+  it('flags a side-effect class-file import', () => {
+    const found = findings(
+      `import '@carbon/web-components/es/components/search/search.js';`
+    );
+    expect(found).toHaveLength(1);
+    expect(found[0]).toMatchObject({
+      component: 'search',
+      kind: 'side-effect',
+      typeOnly: false,
+      suggestedBarrel: '@carbon/web-components/es/components/search/index.js',
+    });
+  });
+
+  it('flags a default class import', () => {
+    const found = findings(
+      `import CDSSearch from '@carbon/web-components/es/components/search/search.js';`
+    );
+    expect(found).toHaveLength(1);
+    expect(found[0].kind).toBe('default');
+  });
+
+  it('flags a named class import (no .js extension)', () => {
+    const found = findings(
+      `import { CDSSearch } from '@carbon/web-components/es/components/search/search';`
+    );
+    expect(found).toHaveLength(1);
+    expect(found[0].kind).toBe('named');
+  });
+
+  it('flags a namespace import', () => {
+    const found = findings(
+      `import * as Search from '@carbon/web-components/es/components/search/search.js';`
+    );
+    expect(found[0].kind).toBe('namespace');
+  });
+
+  it('flags a nested class file and still suggests the top-level barrel', () => {
+    const found = findings(
+      `import CDSTable from '@carbon/web-components/es/components/data-table/table.js';`
+    );
+    expect(found[0]).toMatchObject({
+      component: 'data-table',
+      suggestedBarrel:
+        '@carbon/web-components/es/components/data-table/index.js',
+    });
+  });
+
+  it('marks type-only imports for review', () => {
+    const found = findings(
+      `import type CDSSearch from '@carbon/web-components/es/components/search/search.js';`
+    );
+    expect(found[0]).toMatchObject({ kind: 'type', typeOnly: true });
+  });
+
+  it('does NOT flag the component barrel (file, bare dir, or /index)', () => {
+    expect(
+      findings(`import '@carbon/web-components/es/components/search/index.js';`)
+    ).toHaveLength(0);
+    expect(
+      findings(`import '@carbon/web-components/es/components/search';`)
+    ).toHaveLength(0);
+    expect(
+      findings(
+        `import { CDSSearch } from '@carbon/web-components/es/components/search/index';`
+      )
+    ).toHaveLength(0);
+  });
+
+  it('does NOT flag defs imports (constants/types, register nothing)', () => {
+    expect(
+      findings(
+        `import { SEARCH_SIZE } from '@carbon/web-components/es/components/search/defs.js';`
+      )
+    ).toHaveLength(0);
+  });
+
+  it('does NOT flag non-carbon or top-level package imports', () => {
+    expect(findings(`import { html } from 'lit';`)).toHaveLength(0);
+    expect(
+      findings(`import '@carbon/web-components/es/index.js';`)
+    ).toHaveLength(0);
+    expect(
+      findings(
+        `import { defineCustomElement } from '@carbon/web-components/es/globals/register.js';`
+      )
+    ).toHaveLength(0);
+  });
+
+  it('reports the source line number', () => {
+    const source = [
+      `import { html } from 'lit';`,
+      `import CDSSearch from '@carbon/web-components/es/components/search/search.js';`,
+    ].join('\n');
+    expect(findings(source)[0].line).toBe(2);
+  });
+
+  it('collects multiple findings across a file', () => {
+    const source = [
+      `import '@carbon/web-components/es/components/search/search.js';`,
+      `import '@carbon/web-components/es/components/button/index.js';`,
+      `import CDSDropdown from '@carbon/web-components/es/components/dropdown/dropdown.js';`,
+    ].join('\n');
+    const found = findings(source);
+    expect(found.map((f) => f.component)).toEqual(['search', 'dropdown']);
+  });
+});
+
+describe('formatFileBlock', () => {
+  it('renders a grouped, prefix-shortened tree (no ANSI when color off)', () => {
+    const out = formatFileBlock('src/history-toolbar.ts', sampleFindings, {
+      color: false,
+    });
+
+    // header + tree connectors, sorted by line (8 before 16)
+    expect(out).toContain('src/history-toolbar.ts');
+    expect(out.indexOf('overflow-menu/overflow-menu-item.js')).toBeLessThan(
+      out.indexOf('search/search.js')
+    );
+    expect(out).toContain('├─');
+    expect(out).toContain('└─');
+
+    // component-prefix stripped on both the import and the barrel
+    expect(out).toContain('search/search.js');
+    expect(out).toContain('search/index.js');
+    expect(out).not.toContain('@carbon/web-components/es/components');
+
+    // kinds + review labeling + per-file summary
+    expect(out).toContain('(side-effect)');
+    expect(out).toContain('(type · review)');
+    expect(out).toContain('1 needs a barrel, 1 to review');
+
+    // no color codes when disabled
+    expect(out).not.toContain('\x1b[');
+  });
+
+  it('emits ANSI escapes when color is on', () => {
+    const out = formatFileBlock('src/a.ts', sampleFindings, { color: true });
+    expect(out).toContain('\x1b[');
+  });
+});

package/transforms/carbon-wc-imports.js

@@ -0,0 +1,129 @@
+/**
+ * Copyright IBM Corp. 2026
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+/**
+ * Shared detection for imports of `@carbon/web-components` component class
+ * files (or any non-barrel entry) under `es|lib/components/<name>/...`.
+ *
+ * In the new (starting v3) pure-exports model, importing a component's class
+ * file registers nothing — only the component barrel (`<name>/index.js`) calls
+ * `defineCustomElement`. A consumer that imports the class file but renders
+ * `<cds-name>` gets an inert (un-upgraded) element: it renders to nothing, with
+ * no error thrown.
+ *
+ * This is the AST counterpart (consumer source) version of the internal
+ * web components tool `tools/check-registration-coverage.mjs`, which audits
+ * Carbon's own source as part of CI).
+ *
+ * Consumed by:
+ *  - `wc-report-non-barrel-imports` (advisory reporting only, no changes)
+ *  - the additive barrel-registration codemod (planned)
+ */
+
+// @carbon/web-components/<es|lib>/components/<name>[/<sub...>]
+const COMPONENT_IMPORT_RE =
+  /^(@carbon\/web-components\/(?:es|lib)\/components\/([^/]+))(?:\/(.+))?$/;
+
+/**
+ * Classify an ImportDeclaration by how it binds the module
+ *
+ * @param {object} node an ImportDeclaration AST node
+ * @returns {{ kind: 'side-effect'|'default'|'named'|'namespace'|'type',
+ *   typeOnly: boolean }}
+ */
+function classifyKind(node) {
+  // `import type ... from` (whole-declaration type import)
+  if (node.importKind === 'type') {
+    return { kind: 'type', typeOnly: true };
+  }
+
+  const specs = node.specifiers || [];
+
+  // `import '...'` - imported purely for side effects
+  if (specs.length === 0) {
+    return { kind: 'side-effect', typeOnly: false };
+  }
+
+  // `import { type A, type B } from` - every specifier is a type
+  if (specs.every((s) => s.importKind === 'type')) {
+    return { kind: 'type', typeOnly: true };
+  }
+
+  if (specs.some((s) => s.type === 'ImportNamespaceSpecifier')) {
+    return { kind: 'namespace', typeOnly: false };
+  }
+
+  if (specs.some((s) => s.type === 'ImportDefaultSpecifier')) {
+    return { kind: 'default', typeOnly: false };
+  }
+
+  return { kind: 'named', typeOnly: false };
+}
+
+/**
+ * Find every non-barrel `@carbon/web-components` component import in a file
+ *
+ * @param {import('jscodeshift').JSCodeshift} j
+ * @param {import('jscodeshift').Collection} root
+ * @returns {Array<{ specifier: string, component: string,
+ *   kind: string, typeOnly: boolean, suggestedBarrel: string,
+ *   line: (number|null) }>}
+ */
+function collectNonBarrelWebComponentImports(j, root) {
+  const findings = [];
+
+  root.find(j.ImportDeclaration).forEach((p) => {
+    const node = p.node;
+    const specifier = node.source && node.source.value;
+
+    if (typeof specifier !== 'string') {
+      return;
+    }
+
+    const match = specifier.match(COMPONENT_IMPORT_RE);
+    if (!match) {
+      return;
+    }
+
+    const barrelBase = match[1]; // @carbon/web-components/es/components/<name>
+    const component = match[2];
+    let sub = match[3]; // undefined for a bare `.../components/<name>` import
+
+    if (sub) {
+      sub = sub.replace(/\.js$/, '');
+    }
+
+    // Barrel imports already register. A bare dir (`sub` undefined) and
+    // `<name>/index` both resolve to `<name>/index.js` — nothing to flag
+    if (!sub || sub === 'index') {
+      return;
+    }
+
+    // `defs` modules are constants/types by convention; they register nothing
+    // and aren't expected to (aligns with check-registration-coverage.mjs)
+    if (sub.split('/').pop() === 'defs') {
+      return;
+    }
+
+    const { kind, typeOnly } = classifyKind(node);
+
+    findings.push({
+      specifier,
+      component,
+      kind,
+      typeOnly,
+      suggestedBarrel: `${barrelBase}/index.js`,
+      line: node.loc ? node.loc.start.line : null,
+    });
+  });
+
+  return findings;
+}
+
+module.exports = { collectNonBarrelWebComponentImports, classifyKind };

package/transforms/wc-add-barrel-imports.js

@@ -0,0 +1,116 @@
+/**
+ * Copyright IBM Corp. 2026
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+const { collectNonBarrelWebComponentImports } = require('./carbon-wc-imports');
+
+/**
+ * Ensure every `@carbon/web-components` element a file imports as a non-barrel
+ * class file still registers under v3 pure exports, by making sure the
+ * component barrel (`<name>/index.js`) is imported
+ *
+ * Per import kind:
+ *  - side-effect (`import '.../button/button.js'`) — rewritten to the barrel
+ *    (`import '.../button/index.js'`); multiple side-effect imports of the same
+ *    component collapse into one barrel import. Safe: a class-file side-effect
+ *    import registers nothing in v3, so it is dead already.
+ *  - default / named / namespace (value imports) — left untouched (the class
+ *    binding is preserved), and a side-effect barrel import is *added* alongside.
+ *    The barrel exports the class as a named export with no default, so the path
+ *    can't simply be swapped; adding is the safe move, and `defineCustomElement`
+ *    is idempotent so a duplicate registration can't throw.
+ *  - type-only — ignored; registers/renders nothing
+ *  - if the component barrel is already imported, redundant side-effect class
+ *    imports of that component are dropped.
+ *
+ * Idempotent. Run it (dry by default):
+ *   npx @carbon/upgrade migrate wc-add-barrel-imports [paths...]
+ *   npx @carbon/upgrade migrate wc-add-barrel-imports --write [paths...]
+ */
+function transform(fileInfo, api) {
+  const j = api.jscodeshift;
+  const root = j(fileInfo.source);
+
+  const findings = collectNonBarrelWebComponentImports(j, root).filter(
+    (f) => !f.typeOnly
+  );
+  if (findings.length === 0) {
+    return fileInfo.source;
+  }
+
+  // group the non-barrel imports by component
+  const byComponent = new Map();
+  for (const f of findings) {
+    let group = byComponent.get(f.component);
+    if (!group) {
+      group = { barrel: f.suggestedBarrel, specifiers: new Set() };
+      byComponent.set(f.component, group);
+    }
+    group.specifiers.add(f.specifier);
+  }
+
+  const stripJs = (value) => value.replace(/\.js$/, '');
+  // string source of import path, or null
+  const srcOf = (p) => {
+    const source = p.node && p.node.source;
+    return source && typeof source.value === 'string' ? source.value : null;
+  };
+  const importPaths = root.find(j.ImportDeclaration).paths();
+  let changed = false;
+
+  for (const { barrel, specifiers } of byComponent.values()) {
+    const barrelDir = barrel.replace(/\/index\.js$/, '');
+    const barrelForms = new Set([`${barrelDir}/index`, barrelDir]);
+
+    const barrelAlreadyPresent = importPaths.some((p) => {
+      const value = srcOf(p);
+      return value != null && barrelForms.has(stripJs(value));
+    });
+
+    const relevant = importPaths.filter((p) => {
+      const value = srcOf(p);
+      return value != null && specifiers.has(value);
+    });
+    const sideEffectPaths = relevant.filter(
+      (p) => (p.node.specifiers || []).length === 0
+    );
+    const valuePaths = relevant.filter(
+      (p) => (p.node.specifiers || []).length > 0
+    );
+
+    if (barrelAlreadyPresent) {
+      // drop class-file side-effect imports
+      for (const p of sideEffectPaths) {
+        j(p).remove();
+        changed = true;
+      }
+      continue;
+    }
+
+    if (sideEffectPaths.length > 0) {
+      // collapse - first side-effect import becomes barrent, drop the rest
+      sideEffectPaths[0].node.source = j.stringLiteral(barrel);
+      for (let i = 1; i < sideEffectPaths.length; i++) {
+        j(sideEffectPaths[i]).remove();
+      }
+      changed = true;
+    } else {
+      // value imports - keep and add one-side-effect barrel import
+      valuePaths[0].insertAfter(
+        j.importDeclaration([], j.stringLiteral(barrel))
+      );
+      changed = true;
+    }
+  }
+
+  return changed ? root.toSource({ quote: 'single' }) : fileInfo.source;
+}
+
+module.exports = transform;
+// Parse TS/TSX consumer source (the tsx parser also handles plain JS/JSX).
+module.exports.parser = 'tsx';

package/transforms/wc-report-non-barrel-imports.js

@@ -0,0 +1,156 @@
+/**
+ * Copyright IBM Corp. 2026
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+const path = require('path');
+const { collectNonBarrelWebComponentImports } = require('./carbon-wc-imports');
+
+/**
+ * Flags imports of `@carbon/web-components` component class files, i.e. any
+ * non-barrel entry under `es/components/<name>/...`. Starting with v3 pure
+ * exports, these register nothing, so an element imported this way but rendered
+ * in markup upgrades to nothing — it renders inert, with no error. Import the
+ * component barrel (`<name>/index.js`) instead, or run the barrel-registration
+ * codemod.
+ *
+ * Type-only imports are reported as "review" — they may be intentional (the
+ * element is registered elsewhere, or the class is imported only as a type or
+ * to subclass). Only the runtime `:not(:defined)` diagnostic reliably reflects
+ * what actually renders inert.
+ *
+ * This transform reports only, it never changes source. Output is grouped one
+ * block per file.
+ *
+ *   npx @carbon/upgrade migrate wc-report-non-barrel-imports [paths...]
+ */
+
+// Strip `@carbon/web-components/<es|lib>/components/` prefix so the
+// report shows just `search/search.js` -> `search/index.js`.
+const COMPONENT_PREFIX_RE =
+  /^@carbon\/web-components\/(?:es|lib)\/components\//;
+
+const shorten = (specifier) => specifier.replace(COMPONENT_PREFIX_RE, '');
+
+const ANSI = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  orange: '\x1b[38;5;208m',
+  yellow: '\x1b[33m',
+  gray: '\x1b[90m',
+  cyan: '\x1b[36m',
+};
+
+function colorEnabled() {
+  //  on by default; set `NO_COLOR=1` or `FORCE_COLOR=0` to disable
+  if (process.env.NO_COLOR != null) {
+    return false;
+  }
+  if (process.env.FORCE_COLOR != null) {
+    return process.env.FORCE_COLOR !== '0';
+  }
+  return true;
+}
+
+function makePaint(enabled) {
+  return (codes, str) => {
+    if (!enabled) {
+      return str;
+    }
+    const open = (Array.isArray(codes) ? codes : [codes]).join('');
+    return `${open}${str}${ANSI.reset}`;
+  };
+}
+
+/**
+ * Render findings as a grouped tree block
+ *
+ * @param {string} displayPath relative path shown in the header
+ * @param {Array<object>} findings from collectNonBarrelWebComponentImports
+ * @param {{ color?: boolean }} [options]
+ * @returns {string}
+ */
+function formatFileBlock(displayPath, findings, options = {}) {
+  const paint = makePaint(options.color ?? false);
+
+  const rows = findings
+    .slice()
+    .sort((a, b) => (a.line ?? 0) - (b.line ?? 0))
+    .map((f) => ({
+      line: f.line == null ? '' : `L${f.line}`,
+      spec: shorten(f.specifier),
+      kind: f.typeOnly ? 'type · review' : f.kind,
+      barrel: shorten(f.suggestedBarrel),
+      typeOnly: f.typeOnly,
+    }));
+
+  const lineWidth = Math.max(...rows.map((r) => r.line.length), 0);
+  const specWidth = Math.max(...rows.map((r) => r.spec.length), 0);
+  const kindWidth = Math.max(...rows.map((r) => r.kind.length), 0);
+
+  const needs = rows.filter((r) => !r.typeOnly).length;
+  const review = rows.length - needs;
+  const summaryBits = [];
+  if (needs) {
+    summaryBits.push(`${needs} need${needs === 1 ? 's' : ''} a barrel`);
+  }
+  if (review) {
+    summaryBits.push(`${review} to review`);
+  }
+
+  const header =
+    paint([ANSI.bold, ANSI.orange], displayPath) +
+    paint(ANSI.dim, `  (${summaryBits.join(', ')})`);
+
+  const lines = rows.map((r, i) => {
+    const connector = i === rows.length - 1 ? '└─' : '├─';
+    const lineCol = paint(ANSI.dim, r.line.padEnd(lineWidth));
+    const specCol = r.spec.padEnd(specWidth);
+    const kindColor = r.typeOnly ? ANSI.cyan : ANSI.gray;
+    const kindCol = paint(kindColor, `(${r.kind})`.padEnd(kindWidth + 2));
+    const arrow = paint(ANSI.dim, '→');
+    const barrel = paint(ANSI.yellow, r.barrel);
+
+    return `  ${connector} ${lineCol}  ${specCol}  ${kindCol}  ${arrow}  ${barrel}`;
+  });
+
+  return [header, ...lines].join('\n');
+}
+
+function transform(fileInfo, api) {
+  const j = api.jscodeshift;
+  const findings = collectNonBarrelWebComponentImports(j, j(fileInfo.source));
+
+  if (findings.length) {
+    let displayPath = fileInfo.path;
+    try {
+      const rel = path.relative(process.cwd(), fileInfo.path);
+      if (rel && !rel.startsWith('..')) {
+        displayPath = rel;
+      }
+    } catch {
+      // keep the raw path
+    }
+
+    // one log block per file
+    console.log(
+      '\n' +
+        formatFileBlock(displayPath, findings, {
+          color: colorEnabled(),
+        })
+    );
+  }
+
+  // report only - no changes
+  return fileInfo.source;
+}
+
+module.exports = transform;
+module.exports.formatFileBlock = formatFileBlock;
+// parse TS/TSX consumer source (tsx parser also handles plain JS/JSX)
+module.exports.parser = 'tsx';