Skip to content

weld/no-barrel-bypass ​

Запрещает импорты, которые входят внутрь модуля мимо его точки входа (баррель).

Что ловит правило ​

Единственный источник знания о границах модуля в этом правиле — расположение файлов index.<ext>. Директория, в которой лежит такой файл, объявляет себя модулем с публичным API: всё остальное в ней — внутреннее дело модуля, и импортировать это извне напрямую нельзя, только через index.

Правило проектно-нейтральное: никакой отдельной конфигурации границ не требуется — граница появляется в тот момент, когда в директории появляется index.<ext>, и исчезает, если его убрать.

Проверяются:

  • import ... from '...' (включая import type ... from '...');
  • import('...') с строковым литералом аргумента;
  • require('...') с строковым литералом аргумента (проверка синтаксическая — затенение идентификатора require не отслеживается).

Сообщение об ошибке указывается на строковом литерале пути.

Расширение в специфаере — это в первую очередь вопрос о том, модуль ли это вообще. Импорт файла кода проверяется, ассеты и данные пропускаются молча, а незнакомое расширение (./account.entity) уточняется по диску: если рядом лежит account.entity.ts или account.entity/index.ts, специфаер считается импортом модуля. Иначе он пропускается: по форме записи account.entity неотличим от имени файла с точкой, которого в проекте нет.

Алгоритм поиска границы ​

Все пути внутри правила — виртуальные, абсолютные от корня репозитория (/src/feature/x.ts), не от диска. Обозначения:

  • F — файл, откуда идет импорт;
  • T — путь цели импорта (уже разрешенный: относительный или через алиас);
  • M — самая глубокая директория, общая для dirname(F) и dirname(T);
  • D — найденная граница.

Шаги:

  1. M = общий префикс сегментов dirname(F) и dirname(T) (минимум — виртуальный корень /).
  2. Взять сегменты relative(M, T); последний сегмент (имя файла) в обходе директорий не участвует.
  3. Идти по сегментам-директориям сверху вниз от M к T, накапливая текущий путь D, и на каждом шаге проверять, есть ли в D файл index.<ext>.
  4. На первой найденной D с точкой входа: если T — это D/index или D/index.<ext> (явное расширение), нарушения нет; иначе — нарушение с границей D.
  5. Если сегменты кончились и точка входа не найдена — нарушения нет.

Границы на уровне M и выше не проверяются: модуль не закрыт от самого себя (импорт внутри одной директории или «наверх» по дереву всегда разрешен). Отдельной проверки F === T нет — при совпадающих директориях шаг 5 сразу дает «нарушения нет».

Таблица свойств:

ситуациярезультат
F и T в одной директорииразрешено
T выше F по деревуразрешено
T внутри соседней директории с indexнарушение, D = эта директория
T — сам index первой границы на путиразрешено
T — index.<ext> первой границы (явное расширение)разрешено
T — index директории глубже первой границынарушение, D = первая граница
на пути нет ни одной точки входаразрешено
вложенные границы: точки входа у b и c, цель b/c/indexнарушение, D = b

Вложенные index — деталь внутреннего устройства модуля: побеждает верхняя граница, а не ближняя к цели.

Импорт между пакетами монорепы (например, из /packages/a/src/x.ts в /packages/b/src/internal/y.ts) обрабатывается тем же алгоритмом без специального случая: виртуальные пути делают такие импорты обычным пересечением границы.

Правильно ​

Структура проекта для примеров

Импорт внутри своего же модуля:

ts
// src/feature/internal.ts
import { helper } from './other-file'; // ✅

Импорт через точку входа:

ts
// src/consumer.ts
import { thing } from './feature'; // ✅

Голый пакет — node_modules не резолвится вовсе:

ts
import { z } from 'zod'; // ✅

Неправильно ​

Импорт в обход барреля:

ts
// src/consumer.ts
import { helper } from './feature/internal'; // ❌
// Import bypasses the module barrel. Use './feature' instead of './feature/internal'.

То же через алиас '@/*': ['src/*']:

ts
import { helper } from '@/feature/internal'; // ❌
// Import bypasses the module barrel. Use '@/feature' instead of '@/feature/internal'.

Формирование исправленного пути ​

Форма записи исходного специфайера сохраняется:

  1. относительный импорт → относительный путь от dirname(F) до D, с префиксом ./, если результат не начинается уже с ./ или ../ (директории вроде .storybook из-за ведущей точки не становятся относительным специфайером сами по себе);
  2. если якорь алиаса исходного импорта покрывает D — используется тот же алиас; беззвездочный ключ покрывает только свой якорь: @config → src/config не выражает src/config/other, и TypeScript такой специфаер не резолвит. Оговорка одна: звездный ключ ровно на своем якоре без расширения в исходном импорте специфаером не становится — звездочке нечего подставить, а имени точки входа без расширения не знает никто, — и тогда работает пункт 3 или 4: @/feature/internal при единственном '@/feature/*': ['src/feature/*'] чинится в ./feature, а не в нерезолвимый @/feature;
  3. если не покрывает — берется алиас с самым длинным якорем среди тех, что покрывают D и дают резолвимый специфаер: звездный ключ покрывает поддерево, беззвездочный — только свой якорь;
  4. если подходящего алиаса нет — откат на относительный путь.

Расширение — часть той же формы. Если в исходном специфайере расширение записано явно, к пути дописывается /index.<то же расширение>; если нет — предлагается голая директория D:

исходный импортпредложение
./feature/internal./feature
./feature/internal.js./feature/index.js
@/feature/internal.ts@/feature/index.ts
@/feature/internal (ключ @/feature/*)./feature

Иначе правило ломало бы проекты, где расширения обязательны: в Node-ESM импорт директории не резолвится вовсе, и предложенный ./feature был бы заведомо нерабочим путем. Расширение берется из исходного импорта, а не с диска, — это факт про форму записи: в TypeScript под Node-ESM на диске лежит index.ts, а в специфайере полагается писать index.js.

За вычетом этого хвоста D — всегда директория: расширение самого файла-цели в предложенный путь не попадает.

Настройки: settings.weld ​

Правило читает общие настройки плагина — aliases, aliasesBaseUrl, repoRoot, tsconfig из секции settings.weld (и одноименные опции правила, перекрывающие ее). Если алиасы не заданы явно, они подхватываются из ближайшего к линтуемому файлу конфига с настроенным именем (по умолчанию tsconfig.json). Формат настроек, приоритет источников алиасов и правила автопоиска описаны в документации настроек.

Опции правила ​

js
{
    rules: {
        'weld/no-barrel-bypass': ['error', { fix: false }],
    },
}

Схема опций — один объект (лишние ключи запрещены):

опциятипописание
fixbooleanавтоисправление; по умолчанию true
aliasesobjectпереопределение settings.weld.aliases
aliasesBaseUrlstringпереопределение settings.weld.aliasesBaseUrl
repoRootstringпереопределение settings.weld.repoRoot
tsconfigstringпереопределение settings.weld.tsconfig

Опции aliases, aliasesBaseUrl, repoRoot, tsconfig — те же общие настройки, что и в settings.weld, но заданные на самом правиле; как они перекрывают секцию, описано в документации настроек.

fix ​

Правило всегда объявляет meta.fixable: 'code' и meta.hasSuggestions: true; опция fix решает, куда уходит одна и та же правка:

  • fix: true (по умолчанию) — правка применяется автофиксом (eslint --fix);
  • fix: false — та же правка доступна только как suggestion (messageId: 'useBarrel'), автоматически не применяется.

Автофикс включен по умолчанию сознательно: замена специфайера — механическая правка формы пути, она не читает содержимое барреля и не проверяет, реэкспортирует ли он нужное имя, но всегда синтаксически корректна. Если нужна ручная проверка перед применением (например, из-за отдельного правила про содержимое реэкспортов, см. «Что правило сознательно не проверяет»), автофикс можно выключить через fix: false.

Кавычки в замене берутся из исходного литерала (source.raw[0]), чтобы не конфликтовать с prettier.

configs.recommended включает правило как 'error' без опций (то есть с автофиксом по умолчанию).

Что правило сознательно не проверяет ​

  • export ... from '...' — реэкспорты не анализируются;
  • содержимое барреля и цепочки реэкспортов — правило не проверяет, что импортируемое имя реально доступно через index, оно лишь предлагает синтаксически корректный путь к баррелю;
  • дополнительные точки входа и SFC-баррели (например, index.vue) — точкой входа считается только index.<ext> из фиксированного списка;
  • импорты не-JS ресурсов (.css, .svg, .json, .png и т. п.) и специфайеры с ?/! (./x.svg?url, !!raw-loader!./x) — это инструкции сборщику, а не пути, которые можно переписать на баррель;
  • голые импорты пакетов и @scope/pkg — node_modules не резолвится вовсе;
  • абсолютные специфайеры (/foo) — для них не определена форма вывода исправленного пути;
  • эвристики поиска repoRoot, отличные от «самый верхний package.json в границах .git» (с поправкой на подъем root до якорей алиасов из tsconfig — см. автопоиск алиасов).