module ArchSpec::DSL::Context

The top-level DSL. Declare the project, its components, an architecture preset, and global rules.

root "."
source "app/**/*.rb", "lib/**/*.rb"
ignore "app/legacy/**/*.rb"
todo "archspec_todo.yml"

component :models, in: "app/models/**/*.rb"
component :controllers, in: "app/controllers/**/*.rb"
models.cannot_use :controllers

Declaring a component defines a reader for it, so models and controllers above return an ArchSpec::DSL::ComponentProxy you attach rules to.

Public Instance Methods

architecture (name, **options)

Source

# File lib/archspec/dsl.rb, line 115
def architecture(name, **options)
  Architectures.apply(name, self, **options)
end

Applies a bundled architecture preset, defining its components and rules together.

architecture :rails
architecture :hexagonal
architecture :modular_monolith, components: { ... }, allow: { ... }

preset is an alias. Use whichever word fits: architecture reads well for structural bundles like :rails, preset for convention packs like :ruby_conventions.

See ArchSpec::Architectures for every preset and its options.

Also aliased as: preset

component (name, in: nil, namespace: nil, constants: nil)

Source

# File lib/archspec/dsl.rb, line 93
def component(name, in: nil, namespace: nil, constants: nil)
  add_component(
    ComponentSpec.new(name, files: binding.local_variable_get(:in), namespace: namespace, constants: constants)
  )
  ComponentProxy.new(self, name)
end

Declares a component: a named set of files, matched by glob, namespace, or explicit constant.

component :services, in: "app/services/**/*.rb"
component :billing, namespace: "Billing"
component :legacy, constants: %w[OldReport OldExport]

Returns an ArchSpec::DSL::ComponentProxy for attaching rules. The component is also available by name later in the file.

layer and role are aliases. Use whichever word fits the architecture you are describing.

Also aliased as: layer, role

each_directory (glob) { |name, path| ... }

Source

# File lib/archspec/dsl.rb, line 70
def each_directory(glob)
  base = absolute_root
  pairs = Dir.glob(File.join(base, glob)).select { |path| File.directory?(path) }.sort.map do |absolute|
    [File.basename(absolute), Pathname(absolute).relative_path_from(Pathname(base)).to_s]
  end

  return pairs unless block_given?

  pairs.each { |name, path| yield(name, path) }
end

Yields each subdirectory matching a glob, so you can declare one component per engine or pack without hardcoding their names. Paths resolve against the Archspec.rb directory, not the working directory, so it does not matter where archspec is run from.

each_directory "engines/*" do |name, path|
  component name, in: "#{path}/**/*.rb"
end

Yields the directory basename and its root-relative path. Returns the [name, path] pairs when called without a block.

ignore (*patterns)

Source

# File lib/archspec/dsl.rb, line 44
def ignore(*patterns)
  add_ignore_patterns(patterns)
end

Adds glob patterns for files to skip. Combines with the built-in ignores for .git, tmp, vendor, and node_modules.

layer (name, in: nil, namespace: nil, constants: nil)

Alias for: component

method_missing (name, ...)

Source

# File lib/archspec/dsl.rb, line 139
def method_missing(name, ...)
  return ComponentProxy.new(self, name) if component?(name)

  super
end

Calls superclass method

no_cycles! (among: nil)

Source

# File lib/archspec/dsl.rb, line 128
def no_cycles!(among: nil)
  add_rule(Rules::NoCyclesRule.new(among: among))
end

Forbids dependency cycles between components. Pass among: to limit the check to a subset; omit it to check every declared component.

no_cycles!
no_cycles! among: %i[billing catalog shared]

Rule id: dependencies.no_cycles.

preset (name, **options)

Alias for: architecture

respond_to_missing? (name, include_private = false)

Source

# File lib/archspec/dsl.rb, line 145
def respond_to_missing?(name, include_private = false)
  component?(name) || super
end

Calls superclass method

role (name, in: nil, namespace: nil, constants: nil)

Alias for: component

root (path = nil)

Source

# File lib/archspec/dsl.rb, line 29
def root(path = nil)
  return root_path unless path

  self.root_path = path.to_s
end

Sets or reads the project root that file patterns resolve against. Defaults to the directory of the Archspec.rb file.

rule (rule)

Source

# File lib/archspec/dsl.rb, line 135
def rule(rule)
  add_rule(rule)
end

Adds a custom rule object. A rule responds to id and evaluate(graph), returning ArchSpec::Diagnostic objects. Use this to extend ArchSpec with project-specific checks.

source (*patterns)

Source

# File lib/archspec/dsl.rb, line 38
def source(*patterns)
  add_source_patterns(patterns)
end

Adds glob patterns for the files ArchSpec parses. Defaults cover app, lib, packs, and engines. Component patterns are always analyzed, so most projects never need this.

todo (path = 'archspec_todo.yml')

Source

# File lib/archspec/dsl.rb, line 55
def todo(path = 'archspec_todo.yml')
  self.todo_path = path.to_s
end

Points at a todo file of accepted violations. Diagnostics recorded there are subtracted from future runs, so you can adopt ArchSpec in an existing app without fixing everything first, then burn the list down.

todo "archspec_todo.yml"

Write or refresh it with archspec check --update-todo.