RFC: Multi-dimensional Element Classification with Categories #369

javierbrea · 2025-10-18T15:54:04Z

javierbrea
Oct 18, 2025
Maintainer

Status

✅ Accepted - Implementation in progress

Summary

This RFC proposes adding an optional category field to element definitions in eslint-plugin-boundaries. This enhancement would enable multi-dimensional architectural classification while maintaining full backward compatibility with existing configurations.

Key Changes

Multiple types per file (opt-in): Files can be assigned all matching element types via a new setting
Optional category field: Elements can declare a semantic category dimension
Enhanced rules syntax: Rules can filter by category, type, or both
Capture remains unchanged: The powerful capture feature continues working as before

Motivation

Current Limitation: One Type Per File

Currently, when a file matches multiple element patterns, only the first matching type is assigned. This creates a limitation for projects with multiple architectural dimensions.

Example scenario (from #348):

src/
└── domains/
    └── user/
        └── services/
            └── user.service.ts

This file is:

A service (architectural layer)
Part of the user domain (business domain)

With the current system, you must choose which dimension to enforce. The file will either be recognized as type: "service" OR type: "user-domain", but not both simultaneously.

Why Categories Over Tags?

Initially, I considered a flat tags system (similar to other tools), but categories offer significant advantages:

1. Backward Compatibility

Adding an optional category field is non-breaking:

Existing configurations work unchanged
Users can adopt categories incrementally
No migration required for current users

2. Semantic Hierarchy

Categories provide explicit architectural intent:

// ✅ With categories: Clear semantic meaning
{
  category: 'atomic-design',
  type: 'atom',
  pattern: 'components/atoms/**'
}

{
  category: 'domain',
  type: 'user',
  pattern: 'domains/user/**'
}

Compare to a flat tags system:

// ❌ Less clear: meaning encoded in tag names
{
  type: 'atom',
  tags: ['atomic-design:atom', 'component', 'ui-primitive']
}

With categories:

The category declares what architectural dimension you're describing
The type declares the specific value in that dimension
Multiple categories = multiple architectural perspectives on the same code

3. Multi-dimensional Visualization

I'm planning to create a visualization package that generates dependency graphs from the boundaries detected by this plugin. Categories would enable powerful visualization capabilities that are currently impossible:

// A file matching multiple categories
// File: src/domains/user/components/UserCard.tsx
// Matches:
[
  { category: 'atomic-design', type: 'molecule', pattern: 'components/molecules/*' },
  { category: 'domain', type: 'user', pattern: 'domains/user/*' },
  { category: 'tech', type: 'component', mode: 'file', pattern: '**/*.tsx' }
]

// In a dependency graph visualization:
graph.groupBy('domain')        // Group by business domains
graph.groupBy('atomic-design') // Group by design system hierarchy
graph.groupBy('tech')          // Group by technology/file type

// Or filter by multiple dimensions:
graph.show({ 
  category: 'domain', 
  type: 'user' 
})  // Show only user domain

This would enable viewing the same codebase from different architectural perspectives without changing the configuration—simply by switching which category to visualize.

Detailed Design

1. Multiple Type Assignment (Opt-in)

New behavior: To avoid breaking changes, multiple type assignment will be opt-in via a new setting.

// Configuration
settings: {
  'boundaries/multi-types': true,  // NEW: Enable multiple type assignment
  
  'boundaries/elements': [
    { category: 'atomic-design', type: 'molecule', pattern: 'components/molecules/*' },
    { category: 'domain', type: 'user', pattern: 'domains/user/*' },
    { category: 'tech', type: 'component', pattern: '**/*.tsx' }
  ]
}

// File: domains/user/components/UserCard.tsx
// With multi-types: true, assigned types: 
// - { category: 'atomic-design', type: 'molecule' }
// - { category: 'domain', type: 'user' }
// - { category: 'tech', type: 'component' }

// With multi-types: false (default), assigned type:
// - { category: 'atomic-design', type: 'molecule' } (first match only)

2. Enhanced Element Definition

Element definitions now support an optional category field:

{
  category: '<string>',        // Optional: semantic dimension
  type: '<string>',            // Required: the element type
  pattern: '<string|array>',   // Required: micromatch pattern
  capture: '<array>',          // Optional: capture values (unchanged)
  mode: '<string>',            // Optional: file|folder|full
  // ... other existing fields
}

3. Enhanced Rules Syntax

Rules can now match elements by category, type, or both:

rules: {
  'boundaries/element-types': [2, {
    default: 'disallow',
    rules: [
      // Match by category and type (both specified)
      {
        from: { category: 'atomic-design', type: 'atom' },
        disallow: [
          { category: 'atomic-design', type: 'molecule' },
          { category: 'atomic-design', type: 'organism' }
        ]
      },
      
      // Match by category only (any type within that category)
      {
        from: { category: 'atomic-design' },
        allow: [
          { category: 'atomic-design' },    // Any atomic-design element can import another
          'helper'                   // Or helpers
        ]
      },
      
      // Match by type only (backward compatible - no category)
      {
        from: 'helper',
        allow: ['helper', 'util']
      },
      
      // Mix category-based and traditional matchers
      {
        from: { category: 'domain', type: 'user' },
        allow: [
          { category: 'domain', type: 'user' },    // Same domain
          { category: 'domain', type: 'shared' },  // Shared domain
          'helper'                                  // Any helper (no category)
        ]
      }
    ]
  }]
}

4. Capture Remains Powerful and Complementary

Important: The capture feature is unchanged and complementary to categories.

Key Difference: Dynamic vs Semantic

capture: Extracts dynamic values from file paths for flexible pattern matching
category: Declares semantic intent for architectural classification

// Using both together
{
  category: 'domain',              // Semantic: this is a business domain
  type: 'user',
  pattern: 'domains/user/*/*.ts',
  capture: ['componentName', 'fileName']             // Dynamic: extract specific file name
}

// Rules can use both:
rules: [
  {
    // Category for high-level architectural rules
    from: { category: 'atomic-design', type: 'atom' },
    disallow: [{ category: 'atomic-design', type: 'organism' }]
  },
  {
    // Capture for fine-grained dynamic rules
    from: [['domain', { domainName: '${from.domainName}' }]],
    allow: [['domain', { domainName: '${from.domainName}' }]]
  }
]

When to use what:

Use category for: Grouping elements by architectural concern, visualization, high-level boundaries
Use capture for: Dynamic path-based rules, extracting specific values, fine-grained matching
Use both for: Maximum flexibility and clarity

5. Complete Configuration Example

export default [{
  settings: {
    'boundaries/multi-types': true,  // Enable multiple type assignment
    
    'boundaries/elements': [
      // Atomic design system
      {
        category: 'atomic-design',
        type: 'atom',
        pattern: 'components/atoms/*'
      },
      {
        category: 'atomic-design',
        type: 'molecule',
        pattern: 'components/molecules/*'
      },
      {
        category: 'atomic-design',
        type: 'organism',
        pattern: 'components/organisms/*'
      },
      
      // Business domains
      {
        category: 'domain',
        type: 'user',
        pattern: 'domains/user/*/*.{ts,tsx}',
        capture: ['componentName', 'fileName']
      },
      {
        category: 'domain',
        type: 'order',
        pattern: 'domains/order/*/*.{ts,tsx}',
        capture: ['componentName', 'fileName']
      },
      {
        category: 'domain',
        type: 'shared',
        pattern: 'domains/shared/*/*.{ts,tsx}',
        capture: ['componentName', 'fileName']
      },
      
      // Component technology (for multi-type example)
      {
        category: 'tech',
        type: 'react',
        pattern: '**/*.tsx',
        mode: 'file'
      },
      {
        category: 'tech',
        type: 'node',
        pattern: '**/*.ts',
        mode: 'file'
      }
    ]
  },
  
  rules: {
    'boundaries/element-types': [2, {
      default: 'disallow',
      rules: [
        // Atomic design rules: atoms can't import molecules or organisms
        {
          from: { category: 'atomic-design', type: 'atom' },
          disallow: [
            { category: 'atomic-design', type: 'molecule' },
            { category: 'atomic-design', type: 'organism' }
          ]
        },
        
        // Molecules can import atoms
        {
          from: { category: 'atomic-design', type: 'molecule' },
          allow: [
            { category: 'atomic-design', type: 'atom' }
          ]
        },
        
        // Domain rules: domains can't cross-import (except shared)
        {
          from: { category: 'domain', type: 'user' },
          allow: [
            { category: 'domain', type: 'user' },
            { category: 'domain', type: 'shared' }
          ]
        },
        
        {
          from: { category: 'domain', type: 'order' },
          allow: [
            { category: 'domain', type: 'order' },
            { category: 'domain', type: 'shared' }
          ]
        },
        
        // Combined rule with capture for same-domain enforcement
        {
          from: [['domain', { domainName: '${from.domainName}' }]],
          allow: [
            [['domain', { domainName: '${from.domainName}' }]],  // Same domain only
            { category: 'domain', type: 'shared' }                // Or shared
          ]
        }
      ]
    }]
  }
}]

Migration Path

This proposal is designed to be fully backward compatible:

Phase 1: v6.0 - Soft Launch

Add category as an optional field
Add boundaries/multi-types setting (default: false for backward compatibility)
All existing configurations work unchanged
Users can start adopting categories incrementally
Documentation and examples added

Phase 2: Adoption Period (v6.x)

Community feedback and iteration
Additional tooling exploration (visualization, migration helpers)
Refined based on real-world usage
Minor version releases with improvements

Phase 3: v7.0 - Default Multi-types

Change boundaries/multi-types default to true
This becomes the new recommended behavior
Users can still set it to false if needed
category remains optional for maximum flexibility

Phase 4: Future (v7.x+)

Potentially deprecate single-type mode after sufficient adoption
New features leveraging categories (graph visualization, architecture reporting)
Continue evolving based on community needs

Examples

Example 1: Atomic Design + Domain-Driven Design

settings: {
  'boundaries/multi-types': true,
  'boundaries/elements': [
    { category: 'atomic-design', type: 'atom', pattern: 'atoms/*' },
    { category: 'atomic-design', type: 'molecule', pattern: 'molecules/*' },
    { category: 'atomic-design', type: 'organism', pattern: 'organisms/*' },
    { category: 'domain', type: 'user', pattern: 'domains/user/**/*' },
    { category: 'domain', type: 'order', pattern: 'domains/order/**/*' }
  ]
}

// File: domains/user/components/atoms/UserAvatar.tsx
// Has types:
// - { category: 'atomic-design', type: 'atom' }
// - { category: 'domain', type: 'user' }

Example 2: With Capture for Fine-grained Rules

settings: {
  'boundaries/multi-types': true,
  'boundaries/elements': [
    { 
      category: 'atomic-design',
      type: 'atom',
      pattern: 'atoms/*',
      capture: ['componentName']
    },
    { 
      category: 'domain',
      type: 'user',
      pattern: 'domains/user/*/*.{ts,tsx}',
      capture: ['componentName','fileName']
    }
  ]
}

rules: {
  'boundaries/element-types': [2, {
    default: 'disallow',
    rules: [
      // Category-based rule
      {
        from: { category: 'atomic-design', type: 'atom' },
        disallow: [{ category: 'atomic-design', type: 'molecule' }]
      },
      // Capture-based rule for specific component matching
      {
        from: [['atom', { componentName: 'Button' }]],
        allow: [['atom', { componentName: 'Icon' }]]
      }
    ]
  }]
}

Example 3: Backward Compatible (no changes required)

// This still works exactly as before!
settings: {
  'boundaries/elements': [
    { type: 'helper', pattern: 'helpers/*' },
    { type: 'component', pattern: 'components/*' },
    { type: 'module', pattern: 'modules/*' }
  ]
}

rules: {
  'boundaries/element-types': [2, {
    default: 'disallow',
    rules: [
      { from: 'component', allow: ['helper', 'component'] },
      { from: 'module', allow: ['helper', 'component', 'module'] }
    ]
  }]
}

Open Questions for Community

I'd love to hear your thoughts on:

Multi-types opt-in: Does the boundaries/multi-types setting make sense? Is the migration path reasonable?
Migration concerns: Any concerns about the migration path or backward compatibility?
Visualization: Would you use a graph visualization tool if categories enabled it?

Related Issues

#348 - Multiple types for a file

Next Steps

Gather feedback from the community (this RFC!)
Refine the design based on your input
Create a prototype implementation in a feature branch
Beta release for early adopters to test
Stable release as v6.0

Thank you for taking the time to review this proposal! Your feedback is invaluable in shaping the future of eslint-plugin-boundaries. Please share your thoughts, concerns, and use cases below. 🙏

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

RFC: Multi-dimensional Element Classification with Categories #369

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Uh oh!

RFC: Multi-dimensional Element Classification with Categories #369

Uh oh!

Uh oh!

javierbrea Oct 18, 2025 Maintainer

Status

Summary

Key Changes

Motivation

Current Limitation: One Type Per File

Why Categories Over Tags?

1. Backward Compatibility

2. Semantic Hierarchy

3. Multi-dimensional Visualization

Detailed Design

1. Multiple Type Assignment (Opt-in)

2. Enhanced Element Definition

3. Enhanced Rules Syntax

4. Capture Remains Powerful and Complementary

Key Difference: Dynamic vs Semantic

5. Complete Configuration Example

Migration Path

Phase 1: v6.0 - Soft Launch

Phase 2: Adoption Period (v6.x)

Phase 3: v7.0 - Default Multi-types

Phase 4: Future (v7.x+)

Examples

Example 1: Atomic Design + Domain-Driven Design

Example 2: With Capture for Fine-grained Rules

Example 3: Backward Compatible (no changes required)

Open Questions for Community

Related Issues

Next Steps

Replies: 0 comments

javierbrea
Oct 18, 2025
Maintainer