chore(lint): flag package-internal imports through a barrel

AGENTS.md

@@ -169,6 +169,7 @@ Documentation lives in two places:
 - **Testing**: Vitest (colocated tests)
 - **Components**: `packages/core/`
 - **Storybook**: `apps/storybook/`
+- **Imports inside a package**: import the defining module (`'../List/List'`), never a folder's index barrel (`'../List'`); public consumers import `@astryxdesign/core`. `@astryx/no-internal-barrel-import` enforces it.
 
 ## JSDoc Conventions
 

eslint.config.js

@@ -3,6 +3,7 @@
 import {defineConfig} from 'eslint/config';
 import {includeIgnoreFile} from '@eslint/compat';
 import path from 'node:path';
+import {readFileSync} from 'node:fs';
 import js from '@eslint/js';
 import tseslint from 'typescript-eslint';
 import eslintReact from '@eslint-react/eslint-plugin';
@@ -31,6 +32,32 @@
   : astryxPlugin.configs.recommended;
 const reactSeverity = isStrictMode ? 'error' : 'warn';
 
+// Barrel imports that existed when `@astryx/no-internal-barrel-import` arrived,
+// by repo-relative file. The list only shrinks.
+const internalBarrelBaseline = JSON.parse(
+  readFileSync(
+    new URL(
+      './internal/eslint-plugin-astryx/no-internal-barrel-import.baseline.json',
+      import.meta.url,
+    ),
+    'utf8',
+  ),
+);
+// Tests, stories and test helpers never ship, so they may import barrels; a
+// barrel itself (a folder's or a package's index) is the public surface and
+// may re-export from other barrels (`architecture:public-component-api`).
+const INTERNAL_BARREL_EXEMPT_FILES = [
+  '**/index.*',
+  '**/*.test.*',
+  '**/*.spec.*',
+  '**/*.stories.*',
+  '**/*.testing.*',
+  '**/*.render-testing.*',
+  '**/__tests__/**',
+  '**/__fixtures__/**',
+  '**/dist/**',
+];
+
 // The internal plugin is plain untyped JS (kept out of the lint/type surface),
 // so its inferred shape doesn't satisfy ESLint's strict `Plugin` type. One
 // localized assertion here keeps every `plugins` entry below type-checked.
@@ -863,6 +890,27 @@
   //
   // Remove an entry here as its backlog closes; the file is clean when the
   // block is empty.
+  // Inside a package's own shipped source, import the module that defines a
+  // name, not a folder's index (a barrel): a lazily imported module that goes
+  // through a barrel pulls every sibling export into its graph, which broke
+  // the single-file bundle. Public consumers keep importing from the package
+  // entry. The barrel imports that predate the rule are listed in the
+  // baseline and stay allowed until a codemod removes them; anything new is
+  // reported (an error in strict mode, so a pull request that adds one fails
+  // lint, while main stays green). Type-only imports are erased and allowed.
+  {
+    files: ['packages/*/src/**/*.{ts,tsx,mts,cts,js,jsx,mjs}'],
+    ignores: INTERNAL_BARREL_EXEMPT_FILES,
+    plugins: {
+      '@astryx': astryxEslintPlugin,
+    },
+    rules: {
+      '@astryx/no-internal-barrel-import': [
+        reactSeverity,
+        {baseline: internalBarrelBaseline, root: import.meta.dirname},
+      ],
+    },
+  },
   {
     files: ['packages/richtext/src/**/*.{ts,tsx}'],
     rules: {

internal/eslint-plugin-astryx/README.md

@@ -185,6 +185,25 @@ function useSortedNames(names: string[]) {
 }
 ```
 
+### `@astryx/no-internal-barrel-import`
+
+Reports a relative import, inside a package's own shipped source, that
+resolves to a folder's index file (a barrel) instead of the module that defines
+what it imports: `import {List} from '../List'` rather than
+`import {List} from '../List/List'`. A barrel pulls every sibling export into
+the importer's module graph, so a lazily imported module that goes through one
+drags unrelated code, and in a single-file bundle import cycles, along with it.
+It checks `import`, `export … from` and literal `import()`; type-only imports
+and exports are erased by the compiler and allowed. Public consumers keep
+importing from the package entry (`@astryxdesign/core`), which this rule never
+reads.
+
+The repo config turns it on for `packages/*/src`, outside tests, stories and
+test helpers, at the strict-mode severity (an error in CI). Barrel imports that
+existed when the rule arrived are listed by file in
+`no-internal-barrel-import.baseline.json` and stay allowed until a codemod
+removes them; remove an entry when you fix its import, and never add one.
+
 ### `@astryx/no-core-internal-import`
 
 Reports imports of Core's internal subpaths (`@astryxdesign/core/internal` and

internal/eslint-plugin-astryx/index.js

@@ -22,6 +22,7 @@
  * - no-unstable-merged-refs: Flags render-time mergeRefs callbacks and unstable callback inputs to useMergedRefs
  * - no-light-dark-outside-theme: Flags CSS light-dark() in component source (a light/dark decision belongs to the theme layer, where a token pair reaches both schemes in every theme)
  * - no-core-internal-import: Keeps Core's internal subpaths (@astryxdesign/core/internal/*) inside Core and Lab
+ * - no-internal-barrel-import: Flags a package-internal relative import that resolves to a folder's index (a barrel) instead of the defining module
  * - no-raw-color: Flags a raw colour value (hex, rgb(), hsl(), oklch(), …) anywhere in component source, including inside light-dark()/color-mix(), behind a const, in a template literal, or as a var() fallback — the shapes no-hardcoded-styles cannot see
  *
  * Philosophy: Strict for agents (CI), lenient for humans (local dev)
@@ -54,6 +55,7 @@ import noUnstableMergedRefsRule from './no-unstable-merged-refs.js';
 import copyrightHeaderRule from './copyright-header.js';
 import noRawConsoleCliRule from './no-raw-console-cli.js';
 import noCoreInternalImportRule from './no-core-internal-import.js';
+import noInternalBarrelImportRule from './no-internal-barrel-import.js';
 import requireBasePropsRule from './require-base-props.js';
 import requireRefPropRule from './require-ref-prop.js';
 import requireBasePropsPassthroughRule from './require-baseprops-passthrough.js';
@@ -360,6 +362,7 @@ const plugin = {
     'copyright-header': copyrightHeaderRule,
     'no-raw-console-cli': noRawConsoleCliRule,
     'no-core-internal-import': noCoreInternalImportRule,
+    'no-internal-barrel-import': noInternalBarrelImportRule,
     'no-hardcoded-i18n-string': noHardcodedI18nStringRule,
     'i18n-key-format': i18nKeyFormatRule,
     'require-table-section': requireTableSectionRule,