eslint-plugin v7.0.0
Highlights
Version 7 introduces the entity model: every file is now described along three independent dimensions — its element (architectural unit), its file (categorized on its own), and the module each dependency resolves to. This unlocks multi-dimensional classification and much more precise rules.
- Upgrade with close to zero config changes. Everything new is additive and every v6 pattern keeps working, so you can adopt features one at a time, at your own pace. See the Breaking Changes below and the v6-to-v7 migration guide for the one exception.
- File descriptors (
boundaries/files). Categorize files (tests, styles, …) independently of the element they belong to. A file can carry multiple categories. - Multi-type elements. A single element can now match several types at once (opt-in via
boundaries/elements-single-type: false). - Entity selectors in
from/to. Match rules by element, file, and module properties together — e.g. scope a rule to test files, or to a module's origin. - Advanced array matching for types and categories.
element.typesandfile.categoriesnow accept query objects (anyOf,allOf,noneOf,equalsTo,atIndex,hasLength) instead of just plain patterns, enabling precise rules like "must have exactly these types" or "must not share a type with the other side" — the latter via the newexpandoperator, which pulls values from the opposite side of the rule at match time. - Precise control of external/core dependencies. Match by module
originandsourcedirectly inboundaries/dependencieswithto.module.*. - Richer error messages. Custom message templates can reference the full entity (
{{to.file.categories}},{{to.module.source}}, …). Default messages now include entity information too — re-record any exact-string snapshot assertions. - Clearer vocabulary and rule names. The
rulesoption is nowpolicies(each with aneffect),no-unknown→no-unknown-dependencies(now file-aware), andno-ignored→no-ignored-dependencies. Old names/options keep working with a deprecation warning.
Breaking Changes:
- If you use the
strictconfig witheslint-disablecomments referencingboundaries/no-ignoredorboundaries/no-unknown, those comments stop suppressing violations (now reported under the new rule names) and may themselves trigger "unused eslint-disable directive" errors. Update the comments to the new rule names, or use the newstrict-legacyconfig while you migrate them.- Default report messages changed and
no-unknown-filesnow considers file descriptors. If you assert exact report strings in snapshots or CI, re-record them after upgrading.
Added
- feat: Add entity abstraction layer. New
EntityDescriptiontype combineselement,file, andmoduledescriptions into a unified representation. - feat: Add new selector types:
EntitySelectorwithelement,file, andmodulesub-selectors;FileSelectorwithpath,categories,captured,isIgnored, andisUnknown;ModuleSelectorwithorigin,source, andinternalPath. - feat: Add file descriptors system. A new
filesproperty inDescriptorsConfigallows categorizing files independently from elements.FileDescriptorsupportspattern,category, andcaptureproperties.FileDescriptionprovidespath,categories,captured,isIgnored, andisUnknownfields. - feat: Add module origin system. New
ModuleDescriptiontype withorigin("local"|"external"|"core"),source, andinternalPathproperties. New matcher methods:describeModule(),isModuleMatch(),getModuleSelectorMatching(),getModuleSelectorMatchingDescription(). - feat: Support entity selectors in rules. The
fromandtoproperties of rule selectors now accept objects withelement,fileandmodulesub-selectors, allowing to match by element properties (type,types,captured,parent, etc.), file properties (path,categories,captured, etc.) and module properties (origin,source,internalPath). Legacy flat element selectors keep working and are converted internally. - feat: Add new data to custom message templates. The
fromandtotemplate properties now exposeelement,fileandmoduleobjects, enabling template variables such as{{from.element.types}},{{to.file.categories}},{{to.module.origin}}or{{to.module.source}}. Templates using the previous data ({{from.type}},{{from.elementPath}},{{from.internalPath}},{{from.origin}}, etc.) keep working for backward compatibility. - feat: Support the
partialMatchoption inboundaries/elementsdescriptors (default:true). SetpartialMatch: falseto match the pattern against the full file path from the project root instead of a suffix. It is the recommended replacement for the deprecatedmode: "full". - feat: Array-valued selector properties accept a new array query object with
anyOf,allOf,noneOf,equalsTo(ordered, exact length),atIndex({ index, matches }, negative index supported), andhasLengthoperators (AND-combined). TheatIndex.matchesfield accepts a single value or an array (OR semantics). Supported byfileselectorcategoriesandelementselectortypes. - feat:
anyOf,allOf, andnoneOfitems inelement.types,file.categories, andparent.types/parents[*].typesaccept{ expand: "{{ path }}" }objects in addition to plain micromatch pattern strings. The expand item resolves the Handlebars path against the template data at match time and spreads the resulting string array as individual matchers. This enables dynamic cross-side comparisons such as "to element must not share any type with from element" (noneOf: [{ expand: "{{ from.element.types }}" }]). Mixed static + expand items in the same array are supported. Empty-operand rules apply when the path resolves to null/undefined: emptynoneOfalways passes; emptyanyOfnever matches. - feat: Add
elementselectorparentsproperty: an array query over the full ancestor chain (parents[0]is the closest parent).parentis unchanged and still matches the closest parent. - feat: Add
boundaries/legacy-warningsboolean setting (defaulttrue). Whenfalse, the plugin skips all legacy-pattern detection work — element descriptor deprecated-field checks and rule option deprecated-syntax scans — and suppresses the related deprecation warnings, reducing overhead at lint time. - feat: Add the
boundaries/no-unknown-dependenciesrule, the file-aware successor ofboundaries/no-unknown. It reports a dependency when the target is unknown, configurable through the newrequireoption ("any"|"element"|"file"|"all", default"any"), which selects which classification axes the target must be known on to be considered valid. With the default"any"it reports only when the target is unknown on both the element and file axes;"element"reports when the element is unknown,"file"reports when the file is unknown, and"all"reports when either axis is unknown. - feat: Add a
strict-legacyconfig (exported asstrictLegacyfromeslint-plugin-boundaries/config, and available asplugin.configs["strict-legacy"]), identical tostrictbut enabling the deprecatedboundaries/no-ignoredandboundaries/no-unknownrule names instead of theirboundaries/no-ignored-dependenciesandboundaries/no-unknown-dependenciesreplacements. Use it temporarily if you use thestrictconfig and haveeslint-disablecomments referencing the old rule names that you are not ready to migrate yet.
Changed
- feat(#348): Upgrade the internal
@boundaries/elementslibrary to v3, which reorganizes file analysis around entities composed of an element, a file and a module description, and adds file descriptors, module origins and multi-type elements. All of its breaking changes are absorbed by the plugin: legacy selector properties (type,category,captured,elementPath,internalPath,origin), includinginternalPathmatching the internal path of external modules, and v6 custom message template data keep working without configuration changes. - feat: Deprecate the
categoryproperty in element descriptors and element selectors in favor of file descriptor categories, which allow assigning multiple categories to different files within the same element. It keeps working for backward compatibility, but will be removed in a future major version. - feat: Deprecate the
moduleproperty in dependency metadata selectors (dependency.module) in favor of matching the module source through entity selectors (to.module.source). It keeps working for backward compatibility. - feat: Improve default error messages to include the new entity information. Captured values are now formatted as
captured values: key="value", the module of external dependencies is reported asmodule with origin "external" and module source "...", and elements with multiple types report all of them. If you rely on exact report messages (e.g., in snapshots or CI assertions), you may need to update them. - feat(#348): The
no-unknown-filesrule now takes file descriptors into account: a file is reported only when it does not match any file descriptor pattern and does not belong to any known element. The report message changed from "File does not match any element pattern" to "File does not match any file pattern and does not belong to any known element". - feat(#348): The missing-classification warning now treats element and file descriptors as equally valid layers. The plugin no longer warns when only
boundaries/filesis configured; it warns only when neitherboundaries/elementsnorboundaries/filesis defined, and the message now points to both settings. - feat: Deprecate the
boundaries/no-unknownrule name in favor ofboundaries/no-unknown-dependencies. The old name keeps working but prints a one-time rename warning and will be removed in a future major version. Therecommended(disabled either way) andstrictpresets now reference the new rule name; if you usestrictwitheslint-disablecomments referencingboundaries/no-unknown, update them, or use the newstrict-legacyconfig in the meantime. - feat: Rename the
boundaries/no-ignoredrule toboundaries/no-ignored-dependencies. The behavior is unchanged. The oldboundaries/no-ignoredname keeps working but prints a one-time rename warning and will be removed in a future major version. Therecommended(disabled either way) andstrictpresets now reference the new rule name; if you usestrictwitheslint-disablecomments referencingboundaries/no-ignored, update them, or use the newstrict-legacyconfig in the meantime. - feat: Rename the
rulesoption ofboundaries/dependencies(and the deprecatedelement-types,entry-point, andexternalrules) topolicies, aligning with the new policy/effect vocabulary: a rule containspolicies, each policy has aneffect(allow/disallow), anddefaultis the default effect. This removes the "a rule contains rules" overload that motivated the change. The oldrulesoption keeps working as a deprecated alias — when bothpoliciesandrulesare set,policieswins — and usingrulesprints a one-time deprecation warning, suppressible by settingboundaries/legacy-warningstofalse. The public TypeScript exportsRulePolicy,RULE_POLICIES_MAP,isRulePolicy,DependenciesRule,EntryPointRule, andExternalRuleare kept as@deprecatedaliases ofRuleEffect,RULE_EFFECTS_MAP,isRuleEffect,DependenciesPolicy,EntryPointPolicy, andExternalPolicy. - feat: Rename the
rulecustom message template variable ({{rule.index}},{{rule.selector}}) topolicy({{policy.index}},{{policy.selector}}), matching therules→policiesrename above. The{{rule.*}}variable is kept as a deprecated alias and keeps rendering identically. The publicCustomMessageTemplateRuleContexttype is kept as a@deprecatedalias ofCustomMessageTemplatePolicyContext. - feat: Improve performance by caching the result of merging rule policies.
- feat: Debug output now prints the full entity description (element, file and module) of each file, and the
filesfilter of theboundaries/debugsetting accepts both file selectors and entity selectors. - feat: Emit a one-time runtime console deprecation warning when a rule uses a legacy element selector — a legacy string or tuple selector, or a plain element-selector object (e.g.
{ type: "component" }) used directly infrom/to/target/allow/disallowinstead of wrapped in an entity selector ({ element: { type: "component" } }) — encouraging migration to object-based entity selectors. The warning is harmless and does not change results. - feat: The
recommendedandstrictpresets no longer enable the deprecatedboundaries/element-types,boundaries/entry-point, andboundaries/externalrules. Configured without options (as the presets did), these rules are no-ops — the shared rule runner short-circuits when no options are provided — so enabling them added nothing. They remain available in the plugin for projects that configure them explicitly with their own options. - feat: Add ESLint
meta.deprecatedmetadata (message, docs URL, andreplacedBy) to the deprecatedboundaries/element-types,boundaries/entry-point,boundaries/external, andboundaries/no-privaterules (replaced byboundaries/dependencies) and to the deprecatedboundaries/no-ignoredandboundaries/no-unknownrule names (replaced byboundaries/no-ignored-dependenciesandboundaries/no-unknown-dependencies). This lets editors and tooling that read ESLint's standard deprecation metadata surface the deprecation, in addition to the existing runtime console warning.
Breaking Changes
- feat: The
strictconfig now enablesboundaries/no-ignored-dependenciesandboundaries/no-unknown-dependenciesinstead ofboundaries/no-ignoredandboundaries/no-unknown. If your codebase haseslint-disablecomments referencing the old rule names, they stop suppressing the corresponding violations (now reported under the new rule names) and may themselves trigger "unused eslint-disable directive" errors. Update the comments to the new rule names (recommended, and required for a future major version), or use the newstrict-legacyconfig in the meantime, which keeps enabling the old rule names. - feat: Remove some TypeScript exports from the public API: the
ElementTypesRule,ElementTypesRuleOptions,ElementSelectors,ElementsSelectorandElementSelectorWithOptionstypes, theisElementsSelector,isElementDescriptorModeandisImportKindtype guards, and the deprecatedIMPORT_KINDS_MAPconstant. UseDependenciesPolicy,DependenciesRuleOptions,ElementSelector,isDependencyKindandDEPENDENCY_KINDS_MAPinstead. This only affects TypeScript users importing these types.
elements v3.0.0
Breaking Changes
- feat:
getMatchernow accepts aDescriptorsConfigobject instead of anElementDescriptor[]array. The first argument changed from a flat array to an object with optionalelements,files, andelementsSingleTypeproperties. Existing code must wrap the array:getMatcher([...])→getMatcher({ elements: [...] }). - feat:
DependencyDescription.fromandDependencyDescription.toare nowEntityDescriptionobjects (containingelement,file, andmodulesub-objects) instead of flatElementDescriptionobjects. Code accessing properties likedescription.from.typemust change todescription.from.element.types[0]. - feat:
ElementDescription.type(single string) has been replaced bytypes(string array). Elements can now match multiple type descriptors at the same path level. Element selectors still supporttype(matches first type) for backward compatibility, buttypesis the canonical property. - feat:
origin,elementPath, andinternalPathhave been moved out of element descriptions and selectors.originandinternalPathare now inModuleDescription/ module selectors.elementPathhas been renamed topathin element descriptions. These properties still work in element selectors through legacy backward compatibility, but their canonical location is now in entity selectors withmoduleandfilesub-selectors. - feat:
ElementDescription.categoryis now deprecated. It is still present for backward compatibility but will be removed in a future version. Use file descriptorcategoriesinstead for more flexible file categorization. - feat: The serialized cache format has changed.
DescriptorsSerializedCachenow includes 5 separate sub-caches (elements,files,entities,dependencies,modules). Serialized caches from v2 are incompatible and must be regenerated. - feat: The
moduleproperty in dependency metadata selectors (dependency.module) is now deprecated. Useto.module.sourcevia entity selectors to match the base module name instead.
Added
- feat: Add entity abstraction layer. New
EntityDescriptiontype combineselement,file, andmoduledescriptions into a unified representation. New matcher methods:describeEntity(),isEntityMatch(),getEntitySelectorMatching(),getEntitySelectorMatchingDescription(). - feat: Add new selector types:
EntitySelectorwithelement,file, andmodulesub-selectors;FileSelectorwithpath,categories,captured,isIgnored, andisUnknown;ModuleSelectorwithorigin,source, andinternalPath. - feat: Add file descriptors system. A new
filesproperty inDescriptorsConfigallows categorizing files independently from elements.FileDescriptorsupportspattern,category, andcaptureproperties.FileDescriptionprovidespath,categories,captured,isIgnored, andisUnknownfields. - feat: Add module origin system. New
ModuleDescriptiontype withorigin("local"|"external"|"core"),source, andinternalPathproperties. New matcher methods:describeModule(),isModuleMatch(),getModuleSelectorMatching(),getModuleSelectorMatchingDescription(). - feat: Add multi-type elements support. Elements can now match multiple type descriptors at the same path level. Behavior is controlled by the
elementsSingleTypeoption inDescriptorsConfig(default:false— multi-type mode). - feat: Add the
partialMatchelement descriptor option (default:true). Whentrue, the pattern only needs to match a suffix of the file path (right-to-left accumulation, the existing default behavior). Whenfalse, the pattern is matched against the full file path from the project root while keeping folder semantics (the elementpathis the matched folder prefix). It defaults totruefor backward compatibility, but will most likely default tofalsein a future major version and eventually be removed, because requiring the full pattern is more intuitive and is already how file descriptors match. It is the recommended replacement for the deprecatedmode: "full", and when set tofalsethemodeoption has no effect. - feat: Array-valued selector properties accept a new array query object with
anyOf,allOf,noneOf,equalsTo(ordered, exact length),atIndex({ index, matches }, negative index supported), andhasLengthoperators (AND-combined). TheatIndex.matchesfield accepts a single value or an array (OR semantics). Supported byfileselectorcategoriesandelementselectortypes. - feat:
anyOf,allOf, andnoneOfitems inelement.types,file.categories, andparent.types/parents[*].typesaccept{ expand: "{{ path }}" }objects in addition to plain micromatch pattern strings. The expand item resolves the Handlebars path against the template data at match time and spreads the resulting string array as individual matchers. This enables dynamic cross-side comparisons such as "to element must not share any type with from element" (noneOf: [{ expand: "{{ from.element.types }}" }]). Mixed static + expand items in the same array are supported. Empty-operand rules apply when the path resolves to null/undefined: emptynoneOfalways passes; emptyanyOfnever matches. - feat: Add
elementselectorparentsproperty: an array query over the full ancestor chain (parents[0]is the closest parent).parentis unchanged and still matches the closest parent. - feat: Add file matcher methods to
Matcher:describeFile(),isFileMatch(),getFileSelectorMatching(), andgetFileSelectorMatchingDescription()to work with file descriptions and file selectors directly without going through the entity abstraction layer. - feat: Add module matcher methods to
Matcher:describeModule(),isModuleMatch(),getModuleSelectorMatching(), andgetModuleSelectorMatchingDescription()to work with module descriptions and module selectors directly without going through the entity abstraction layer.
Changed
- refactor: Reorganize internal architecture into domain-based module structure (Element, File, Entity, Module, Dependency) for better separation of concerns.
- refactor: Enhance cache system to support 5 separate descriptor type caches for improved granularity.
website v7.0.0
Added
- feat: Add "v6 to v7" migration guide to the documentation.
- feat: Add
HomepageMultiLayersection to the home page, showcasing multi-dimensional/multi-layer classification. - feat: Add "v7-launch" announcement bar highlighting file descriptors, multi-dimensional classification and the zero-breaking-changes upgrade, linking to the "v6 to v7" migration guide.
- feat: Add dedicated "Files", "Modules" and "Dependency" pages to the "Classification" section, and per-type pages to the "Selectors" and "Policies" sections.
- feat: Adapt all content and examples in the documentation to the new file descriptors, multi-dimensional classification, and array queries features.
Changed
- feat: Restructure the sidebar, flattening the single "Setup" section into four top-level sections: "Classification", "Selectors", "Policies" and "Settings".
- feat: Change links in navigation bar to point to the new "Classifications", "Selectors", and "Policies" sections, instead of the old "Setup" section.
- feat: Change footer link from "Setup" to "Settings" section.
- chore: Upgrade Docusaurus from
3.9.2to3.10.1.