npm eslint-plugin-boundaries 7.0.0
Multi-dimensional Classification with File Descriptors

latest releases: 7.4.4, 7.4.3, 7.4.2...
4 months ago

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.types and file.categories now 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 new expand operator, which pulls values from the opposite side of the rule at match time.
  • Precise control of external/core dependencies. Match by module origin and source directly in boundaries/dependencies with to.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 rules option is now policies (each with an effect), no-unknown → no-unknown-dependencies (now file-aware), and no-ignored → no-ignored-dependencies. Old names/options keep working with a deprecation warning.

Breaking Changes:

  • If you use the strict config with eslint-disable comments referencing boundaries/no-ignored or boundaries/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 new strict-legacy config while you migrate them.
  • Default report messages changed and no-unknown-files now 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 EntityDescription type combines element, file, and module descriptions into a unified representation.
  • feat: Add new selector types: EntitySelector with element, file, and module sub-selectors; FileSelector with path, categories, captured, isIgnored, and isUnknown; ModuleSelector with origin, source, and internalPath.
  • feat: Add file descriptors system. A new files property in DescriptorsConfig allows categorizing files independently from elements. FileDescriptor supports pattern, category, and capture properties. FileDescription provides path, categories, captured, isIgnored, and isUnknown fields.
  • feat: Add module origin system. New ModuleDescription type with origin ("local" | "external" | "core"), source, and internalPath properties. New matcher methods: describeModule(), isModuleMatch(), getModuleSelectorMatching(), getModuleSelectorMatchingDescription().
  • feat: Support entity selectors in rules. The from and to properties of rule selectors now accept objects with element, file and module sub-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 from and to template properties now expose element, file and module objects, 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 partialMatch option in boundaries/elements descriptors (default: true). Set partialMatch: false to match the pattern against the full file path from the project root instead of a suffix. It is the recommended replacement for the deprecated mode: "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), and hasLength operators (AND-combined). The atIndex.matches field accepts a single value or an array (OR semantics). Supported by file selector categories and element selector types.
  • feat: anyOf, allOf, and noneOf items in element.types, file.categories, and parent.types / parents[*].types accept { 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: empty noneOf always passes; empty anyOf never matches.
  • feat: Add element selector parents property: an array query over the full ancestor chain (parents[0] is the closest parent). parent is unchanged and still matches the closest parent.
  • feat: Add boundaries/legacy-warnings boolean setting (default true). When false, 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-dependencies rule, the file-aware successor of boundaries/no-unknown. It reports a dependency when the target is unknown, configurable through the new require option ("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-legacy config (exported as strictLegacy from eslint-plugin-boundaries/config, and available as plugin.configs["strict-legacy"]), identical to strict but enabling the deprecated boundaries/no-ignored and boundaries/no-unknown rule names instead of their boundaries/no-ignored-dependencies and boundaries/no-unknown-dependencies replacements. Use it temporarily if you use the strict config and have eslint-disable comments referencing the old rule names that you are not ready to migrate yet.

Changed

  • feat(#348): Upgrade the internal @boundaries/elements library 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), including internalPath matching the internal path of external modules, and v6 custom message template data keep working without configuration changes.
  • feat: Deprecate the category property 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 module property 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 as module 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-files rule 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/files is configured; it warns only when neither boundaries/elements nor boundaries/files is defined, and the message now points to both settings.
  • feat: Deprecate the boundaries/no-unknown rule name in favor of boundaries/no-unknown-dependencies. The old name keeps working but prints a one-time rename warning and will be removed in a future major version. The recommended (disabled either way) and strict presets now reference the new rule name; if you use strict with eslint-disable comments referencing boundaries/no-unknown, update them, or use the new strict-legacy config in the meantime.
  • feat: Rename the boundaries/no-ignored rule to boundaries/no-ignored-dependencies. The behavior is unchanged. The old boundaries/no-ignored name keeps working but prints a one-time rename warning and will be removed in a future major version. The recommended (disabled either way) and strict presets now reference the new rule name; if you use strict with eslint-disable comments referencing boundaries/no-ignored, update them, or use the new strict-legacy config in the meantime.
  • feat: Rename the rules option of boundaries/dependencies (and the deprecated element-types, entry-point, and external rules) to policies, aligning with the new policy/effect vocabulary: a rule contains policies, each policy has an effect (allow/disallow), and default is the default effect. This removes the "a rule contains rules" overload that motivated the change. The old rules option keeps working as a deprecated alias — when both policies and rules are set, policies wins — and using rules prints a one-time deprecation warning, suppressible by setting boundaries/legacy-warnings to false. The public TypeScript exports RulePolicy, RULE_POLICIES_MAP, isRulePolicy, DependenciesRule, EntryPointRule, and ExternalRule are kept as @deprecated aliases of RuleEffect, RULE_EFFECTS_MAP, isRuleEffect, DependenciesPolicy, EntryPointPolicy, and ExternalPolicy.
  • feat: Rename the rule custom message template variable ({{rule.index}}, {{rule.selector}}) to policy ({{policy.index}}, {{policy.selector}}), matching the rules → policies rename above. The {{rule.*}} variable is kept as a deprecated alias and keeps rendering identically. The public CustomMessageTemplateRuleContext type is kept as a @deprecated alias of CustomMessageTemplatePolicyContext.
  • 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 files filter of the boundaries/debug setting 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 in from/to/target/allow/disallow instead 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 recommended and strict presets no longer enable the deprecated boundaries/element-types, boundaries/entry-point, and boundaries/external rules. 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.deprecated metadata (message, docs URL, and replacedBy) to the deprecated boundaries/element-types, boundaries/entry-point, boundaries/external, and boundaries/no-private rules (replaced by boundaries/dependencies) and to the deprecated boundaries/no-ignored and boundaries/no-unknown rule names (replaced by boundaries/no-ignored-dependencies and boundaries/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 strict config now enables boundaries/no-ignored-dependencies and boundaries/no-unknown-dependencies instead of boundaries/no-ignored and boundaries/no-unknown. If your codebase has eslint-disable comments 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 new strict-legacy config in the meantime, which keeps enabling the old rule names.
  • feat: Remove some TypeScript exports from the public API: the ElementTypesRule, ElementTypesRuleOptions, ElementSelectors, ElementsSelector and ElementSelectorWithOptions types, the isElementsSelector, isElementDescriptorMode and isImportKind type guards, and the deprecated IMPORT_KINDS_MAP constant. Use DependenciesPolicy, DependenciesRuleOptions, ElementSelector, isDependencyKind and DEPENDENCY_KINDS_MAP instead. This only affects TypeScript users importing these types.

elements v3.0.0

Breaking Changes

  • feat: getMatcher now accepts a DescriptorsConfig object instead of an ElementDescriptor[] array. The first argument changed from a flat array to an object with optional elements, files, and elementsSingleType properties. Existing code must wrap the array: getMatcher([...]) → getMatcher({ elements: [...] }).
  • feat: DependencyDescription.from and DependencyDescription.to are now EntityDescription objects (containing element, file, and module sub-objects) instead of flat ElementDescription objects. Code accessing properties like description.from.type must change to description.from.element.types[0].
  • feat: ElementDescription.type (single string) has been replaced by types (string array). Elements can now match multiple type descriptors at the same path level. Element selectors still support type (matches first type) for backward compatibility, but types is the canonical property.
  • feat: origin, elementPath, and internalPath have been moved out of element descriptions and selectors. origin and internalPath are now in ModuleDescription / module selectors. elementPath has been renamed to path in element descriptions. These properties still work in element selectors through legacy backward compatibility, but their canonical location is now in entity selectors with module and file sub-selectors.
  • feat: ElementDescription.category is now deprecated. It is still present for backward compatibility but will be removed in a future version. Use file descriptor categories instead for more flexible file categorization.
  • feat: The serialized cache format has changed. DescriptorsSerializedCache now includes 5 separate sub-caches (elements, files, entities, dependencies, modules). Serialized caches from v2 are incompatible and must be regenerated.
  • feat: The module property in dependency metadata selectors (dependency.module) is now deprecated. Use to.module.source via entity selectors to match the base module name instead.

Added

  • feat: Add entity abstraction layer. New EntityDescription type combines element, file, and module descriptions into a unified representation. New matcher methods: describeEntity(), isEntityMatch(), getEntitySelectorMatching(), getEntitySelectorMatchingDescription().
  • feat: Add new selector types: EntitySelector with element, file, and module sub-selectors; FileSelector with path, categories, captured, isIgnored, and isUnknown; ModuleSelector with origin, source, and internalPath.
  • feat: Add file descriptors system. A new files property in DescriptorsConfig allows categorizing files independently from elements. FileDescriptor supports pattern, category, and capture properties. FileDescription provides path, categories, captured, isIgnored, and isUnknown fields.
  • feat: Add module origin system. New ModuleDescription type with origin ("local" | "external" | "core"), source, and internalPath properties. 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 elementsSingleType option in DescriptorsConfig (default: false — multi-type mode).
  • feat: Add the partialMatch element descriptor option (default: true). When true, the pattern only needs to match a suffix of the file path (right-to-left accumulation, the existing default behavior). When false, the pattern is matched against the full file path from the project root while keeping folder semantics (the element path is the matched folder prefix). It defaults to true for backward compatibility, but will most likely default to false in 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 deprecated mode: "full", and when set to false the mode option 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), and hasLength operators (AND-combined). The atIndex.matches field accepts a single value or an array (OR semantics). Supported by file selector categories and element selector types.
  • feat: anyOf, allOf, and noneOf items in element.types, file.categories, and parent.types / parents[*].types accept { 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: empty noneOf always passes; empty anyOf never matches.
  • feat: Add element selector parents property: an array query over the full ancestor chain (parents[0] is the closest parent). parent is unchanged and still matches the closest parent.
  • feat: Add file matcher methods to Matcher: describeFile(), isFileMatch(), getFileSelectorMatching(), and getFileSelectorMatchingDescription() 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(), and getModuleSelectorMatchingDescription() 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 HomepageMultiLayer section 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.2 to 3.10.1.

Don't miss a new eslint-plugin-boundaries release

NewReleases is sending notifications on new releases.