Architecture Lints 🏗️ #

A configuration-driven, architecture-agnostic linting engine for Dart and Flutter that transforms your architectural vision into enforceable code standards.

Unlike standard linters that enforce hardcoded opinions (e.g., "Always extend Bloc"), architecture_lints reads a Policy Definition from an architecture.yaml file in your project root. This allows you to define your own architectural rules, layers, and naming conventions.

It is the core engine powering packages like architecture_clean, but it can be used standalone to enforce any architectural style (MVVM, MVC, DDD, Layer-First, Feature-First).

📦 Installation #

Add the package to your dev_dependencies:

# pubspec.yaml
dev_dependencies:
  custom_lint: ^0.8.0
  architecture_lints: ^0.1.0

Enable the plugin in analysis_options.yaml:

# analysis_options.yaml
analyzer:
  plugins:
    - custom_lint

Create an architecture.yaml file in your project root (see Configuration below).

📋 Available Lint Rules #

These rules are generic but become specific based on your configuration.

⚙️ Configuration Manual (architecture.yaml) #

This file acts as the Domain Specific Language (DSL) for your architecture.

📚 Table of Contents #

1. Concepts & Philosophies
2. Core Declarations
3. Auxiliary Declarations
4. Policies (The Rules)
5. Automation (Code Generation)

[1] 💡 Concepts & Philosophies #

To effectively lint a large project, we must understand its structure on two axes:

Modules (Horizontal Slicing) #

Modules represent the Features or high-level groupings of your application.

• Example: Core, Shared, Profile, Auth.
• A module usually contains multiple layers.

Components (Vertical Slicing) #

Components represent the Layers or technical roles within a module.

• Example: Entity, Repository, UseCase, Widget.
• A component is defined by what it is (Structure) and where it lives (Path).

The Linter combines these to identify a file:

lib/features/auth/domain/usecases/login.dart

• Module: auth (Derived from features/{{name}})
• Component: domain.usecase (Derived from path domain/usecases)

[2] 🎯 Core Declarations (The Configurations) #

The architecture.yaml file drives everything.

[2.1] Modules (modules) #

Modules represent the Features or high-level groupings of your application. The linter uses these definitions to map codebase files to specific functional boundaries. For example Core, Shared, Profile, Auth.

Relationship: A module usually acts as a container for multiple architectural layers.

Definitions

modules:
  <module_key>: <module_value>

Note:

• <module_value> can be only one of the two forms (shorthand or longhand).

Properties

Example

modules:
  # [Dynamic] Feature modules under features/
  # ID: 'feature', Instance: 'auth', 'payments', etc.
  feature:
    path: 'features/{{name}}'
    default: true # Unmatched components belong here

  # [Static] Core module
  # ID: 'core', Path: 'lib/core'
  core: 'core'

  # [Static] Shared module
  # ID: 'shared', Path: 'lib/shared'
  shared: 'shared'

[2.2] Components (components) #

Components represent the Layers or technical roles within a module.

Maps your file system structure to architectural concepts. This is the core taxonomy of your project.

• Example: Entity, Repository, UseCase, Widget.
• A component is defined by what it is (Structure) and where it lives (Path).

Definitions

components:
  <component_key>: 
    <component_property>
    <component_property>
    
    .<component_child>
    .<component_child>

Properties

Example

components:
  # [Namespace] Domain Layer
  # ID: 'domain'
  # Path: 'domain'
  # Mode: 'namespace' ensures this never matches a specific file, only the folder
  .domain:
    path: 'domain'
    mode: namespace

    # [Component] Domain Port
    # ID: 'domain.port' (Concatenated)
    # Path: 'domain/ports' (Inherited + Appended)
    .port:
      path: 'ports'
      mode: file
      
      # Structural Rules: Must be 'abstract interface class'
      kind: class
      modifier: [ abstract, interface ]
      
      # Naming Rule: Must end in 'Port' (e.g. AuthPort)
      pattern: '{{name}}Port'
      antipattern: '{{name}}Interface' # Guide away from legacy naming

🧠 Resolution Logic

The linter uses a Smart Resolution Logic to identify files by calculating a score. This allows an Interface (AuthSource) and Implementation (AuthSourceImpl) in the same folder to be treated differently.

Scoring Criteria:

1. Path Match: Deeper directory matches get higher scores.
2. Mode: mode: file beats mode: part.
3. Naming: Matches configured {{name}}Pattern.
4. Inheritance: Implements required base classes defined in inheritances.
5. Structure: Matches required kind and modifier.

Example: A concrete class AuthImpl will fail to match a component requiring modifier: abstract, forcing the resolver to pick the Implementation component instead.

[3] 🧩 Auxiliary Declarations #

[3.1] Types (definitions) #

Maps abstract concepts (like "Result Wrapper" or "Service Locator") to concrete Dart types. This decouples your rules from specific class names.

Definitions

definitions:
  <group_key>:
    <type_key>: <type_value>

Properties

Example

definitions:
  # Domain Types
  usecase:
    .base:
      type: 'Usecase'
      import: 'package:my_app/core/usecase.dart'
    # Inherits import from .base
    .unary: 'UnaryUsecase' 
    
  # Result Wrappers
  result:
    .wrapper:
      .future:
        type: 'FutureEither'
        import: 'package:my_app/core/types.dart'
        argument: '*'

[3.2] Vocabularies (vocabularies) #

The linter uses Natural Language Processing (NLP) to check if class names make grammatical sense (e.g., "UseCases must be Verb-Noun").

Definitions

vocabularies:
  nouns: <list>
  verbs: <list>

Example

vocabularies:
  nouns: [ 'auth', 'todo', 'kyc' ]
  verbs: [ 'upsert', 'rebase', 'unfriend' ]

[4] 📜 Policies (Enforcing Behavior) #

Policies define what is required, allowed, or forbidden.

[4.1] Dependencies (dependencies) #

Enforce the Dependency Rule (Architecture Boundaries).

Definitions

dependencies:
  - on: <component_id>
    <allowed | forbidden>

Properties

Example

dependencies:
  # Domain is platform agnostic
  - on: domain
    forbidden:
      import: [ 'package:flutter/**', 'dart:ui' ]
      component: [ 'data', 'presentation' ]
  
  # UseCases can only see Domain
  - on: usecase
    allowed:
      component: [ 'entity', 'port' ]

[4.2] Type Safety (type_safeties) #

Enforce method signatures.

Definitions

type_safeties:
  - on: <component_id>
    <allowed | forbidden>

Properties

Example

type_safeties:
  # Domain must return safe wrappers
  - on: [ port, usecase ]
    allowed:
      kind: 'return'
      definition: 'result.wrapper.future'
    forbidden:
      kind: 'return'
      type: 'Future'

[4.3] Exceptions (exceptions) #

Enforce error handling flow.

Definitions

exceptions:
  - on: <component_id>
    role: <role>
    <required | forbidden>
    conversions: ...

Properties (inside required/forbidden)

Properties (inside conversions)

Example

exceptions:
  # Repositories catch and return Failures
  - on: repository
    role: boundary
    required:
      - operation: 'catch_return'
        definition: 'result.failure'
    forbidden:
      - operation: 'throw'
    conversions:
      - from: 'exception.server'
        to: 'failure.server'

[4.4] Structure #

This section enforces internal class composition.

[4.4.1] Inheritances (inheritances)

Enforces base class requirements (extends, implements, with).

Definitions

inheritances:
  - on: <component_id>
    <required | forbidden>

Properties (inside required/forbidden)

Example

inheritances:
  # Entities must extend the base Entity class
  - on: entity
    required:
      - type: 'Entity'
        import: 'package:core/entity/entity.dart'

  # Repositories must implement their corresponding Port
  - on: repository
    required:
      - component: 'port'

[4.4.2] Members (members)

Enforces rules on class members (fields, methods, constructors).

Definitions

members:
  - on: <component_id>
    <required | allowed | forbidden>

Properties

Example

members:
  # Entities must be immutable and have an 'id'
  - on: entity
    required:
      - kind: field
        identifier: 'id'
      - kind: field
        modifier: 'final'
    forbidden:
      - kind: setter
        visibility: public

[4.4.3] Annotations (annotations)

Enforces metadata (Annotations) on classes.

Definitions

annotations:
  - on: <component_id>
    mode: <mode>
    <required | forbidden>

Properties (inside required/forbidden)

Example

annotations:
  # UseCases must be injectable. No other framework annotations allowed.
  - on: usecase
    mode: strict
    required:
      - type: 'Injectable'
        import: 'package:injectable/injectable.dart'

[4.5] Relationships (relationships) #

Enforce file parity (1-to-1 mappings).

Definitions

relationships:
  - on: <component_id>
    kind: <kind>
    required: ...

Properties (inside required)

Example

relationships:
  # Every Port method needs a UseCase
  - on: domain.port
    kind: method
    visibility: public
    required:
      component: domain.usecase
      action: create_usecase

[4.6] Usage (usages) #

Bans specific coding patterns (e.g., global access).

Definitions

usages:
  - on: <component_id>
    forbidden: ...

Properties (inside forbidden)

Example

usages:
  - on: domain
    forbidden:
      kind: access
      definition: service.locator

[5] 🤖 Automation (Actions & Templates) #

The linter acts as a code generator when rules are broken.

[5.1] Actions (actions) #

Defines the logic for a Quick Fix. Uses a Dart-like Expression Language for variables.

Definitions

actions:
  <action_id>:
    <global_properties>
    trigger: ...
    source: ...
    target: ...
    write: ...
    variables: ...

[5.1.1] Trigger Configuration

Determines when the action appears.

[5.1.2] Source & Target Context

Determines where data comes from and where code goes.

[5.1.3] Write Strategy

How the generated code is saved.

[5.1.4] Variables & Expressions

Maps data from the source to the template. This uses a Dart-like expression language.

Common Variable Strategies:

1. Simple References: Direct access to properties (e.g., className: '{{source.name.pascalCase}}').
2. Conditional Switch Logic: Use a list of maps to handle "if/else" logic.
3. Complex Mappings: Iterating over lists or mapping objects (e.g., extracting parameters).
4. Common Filters: | pascalCase, | snakeCase, | camelCase.

Example

actions:
  create_usecase:
    description: 'Generate UseCase'
    template_id: 'usecase_template'
    debug: true
    
    trigger:
      error_code: 'arch_parity_missing'
      component: 'domain.port'
    
    source:
      scope: current
      element: method
    
    target:
      scope: related
      component: 'domain.usecase'
    
    write:
      strategy: file
      filename: '{{source.name.snakeCase}}.dart'
    
    variables:
      # Switch logic
      baseDef:
        select:
          - if: source.parameters.isEmpty
            value: 'NullaryUsecase'
          - else: 'UnaryUsecase'
            
      # Simple reference
      className: '{{source.name.pascalCase}}'
      
      # List mapping
      paramsList:
        type: list
        from: source.parameters
        map:
          name: item.name

[5.2] Templates (templates) #

Standard Mustache templates. Logic-less.

Definitions

templates:
  <template_id>:
    file: <path>
    description: <text>

Example

templates:
  usecase_template:
    file: 'templates/usecase.mustache'

Example template file (templates/usecase.mustache):

class {{className}} extends {{baseClass}} {
  final {{repoType}} {{repoVar}};
  const {{className}}(this.{{repoVar}});

  @override
  {{returnType}} call({{parameters}}) {
    // TODO: Implement
  }
}