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— найденная граница.
Шаги:
M= общий префикс сегментовdirname(F)иdirname(T)(минимум — виртуальный корень/).- Взять сегменты
relative(M, T); последний сегмент (имя файла) в обходе директорий не участвует. - Идти по сегментам-директориям сверху вниз от
MкT, накапливая текущий путьD, и на каждом шаге проверять, есть ли вDфайлindex.<ext>. - На первой найденной
Dс точкой входа: еслиT— этоD/indexилиD/index.<ext>(явное расширение), нарушения нет; иначе — нарушение с границейD. - Если сегменты кончились и точка входа не найдена — нарушения нет.
Границы на уровне 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) обрабатывается тем же алгоритмом без специального случая: виртуальные пути делают такие импорты обычным пересечением границы.
Правильно
Структура проекта для примеров
Импорт внутри своего же модуля:
// src/feature/internal.ts
import { helper } from './other-file'; // ✅Импорт через точку входа:
// src/consumer.ts
import { thing } from './feature'; // ✅Голый пакет — node_modules не резолвится вовсе:
import { z } from 'zod'; // ✅Неправильно
Импорт в обход барреля:
// src/consumer.ts
import { helper } from './feature/internal'; // ❌
// Import bypasses the module barrel. Use './feature' instead of './feature/internal'.То же через алиас '@/*': ['src/*']:
import { helper } from '@/feature/internal'; // ❌
// Import bypasses the module barrel. Use '@/feature' instead of '@/feature/internal'.Формирование исправленного пути
Форма записи исходного специфайера сохраняется:
- относительный импорт → относительный путь от
dirname(F)доD, с префиксом./, если результат не начинается уже с./или../(директории вроде.storybookиз-за ведущей точки не становятся относительным специфайером сами по себе); - если якорь алиаса исходного импорта покрывает
D— используется тот же алиас; беззвездочный ключ покрывает только свой якорь:@config → src/configне выражаетsrc/config/other, и TypeScript такой специфаер не резолвит. Оговорка одна: звездный ключ ровно на своем якоре без расширения в исходном импорте специфаером не становится — звездочке нечего подставить, а имени точки входа без расширения не знает никто, — и тогда работает пункт 3 или 4:@/feature/internalпри единственном'@/feature/*': ['src/feature/*']чинится в./feature, а не в нерезолвимый@/feature; - если не покрывает — берется алиас с самым длинным якорем среди тех, что покрывают
Dи дают резолвимый специфаер: звездный ключ покрывает поддерево, беззвездочный — только свой якорь; - если подходящего алиаса нет — откат на относительный путь.
Расширение — часть той же формы. Если в исходном специфайере расширение записано явно, к пути дописывается /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). Формат настроек, приоритет источников алиасов и правила автопоиска описаны в документации настроек.
Опции правила
{
rules: {
'weld/no-barrel-bypass': ['error', { fix: false }],
},
}Схема опций — один объект (лишние ключи запрещены):
| опция | тип | описание |
|---|---|---|
fix | boolean | автоисправление; по умолчанию true |
aliases | object | переопределение settings.weld.aliases |
aliasesBaseUrl | string | переопределение settings.weld.aliasesBaseUrl |
repoRoot | string | переопределение settings.weld.repoRoot |
tsconfig | string | переопределение 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 — см. автопоиск алиасов).