Module: ArchSpec::DSL::Context

Defined in:
lib/archspec/dsl.rb

Overview

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.

Instance Method Summary collapse

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name) ⇒ Object 



144
145
146
147
148
 
# File 'lib/archspec/dsl.rb', line 144

def method_missing(name, ...)
  return ComponentProxy.new(self, name) if component?(name)

  super
end

Instance Method Details

#architecture(name, **options) ⇒ Object Also known as: preset

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.



119
120
121
 
# File 'lib/archspec/dsl.rb', line 119

def architecture(name, **options)
  Architectures.apply(name, self, **options)
end

#component(name, in: nil, namespace: nil, constants: nil) ⇒ Object

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.



100
101
102
103
104
105
 
# File 'lib/archspec/dsl.rb', line 100

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

#each_directory(glob) ⇒ Object

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.



80
81
82
83
84
85
86
87
88
89
 
# File 'lib/archspec/dsl.rb', line 80

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

#ignore(*patterns) ⇒ Object

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



54
55
56
 
# File 'lib/archspec/dsl.rb', line 54

def ignore(*patterns)
  add_ignore_patterns(patterns)
end

#no_cycles(among: nil) ⇒ Object

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.



132
133
134
135
 
# File 'lib/archspec/dsl.rb', line 132

def no_cycles(among: nil)
  DSL.assert_known_components!(self, among, for_rule: 'no_cycles') if among
  add_rule(Rules::NoCyclesRule.new(among: among))
end

#respond_to_missing?(name, include_private = false) ⇒ Boolean

Returns:

  • (Boolean) 


150
151
152
 
# File 'lib/archspec/dsl.rb', line 150

def respond_to_missing?(name, include_private = false)
  component?(name) || super
end

#root(path = nil) ⇒ Object

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



39
40
41
42
43
 
# File 'lib/archspec/dsl.rb', line 39

def root(path = nil)
  return root_path unless path

  self.root_path = path.to_s
end

#rule(rule) ⇒ Object

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.



140
141
142
 
# File 'lib/archspec/dsl.rb', line 140

def rule(rule)
  add_rule(rule)
end

#source(*patterns) ⇒ Object

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.



48
49
50
 
# File 'lib/archspec/dsl.rb', line 48

def source(*patterns)
  add_source_patterns(patterns)
end

#todo(path = 'archspec_todo.yml') ⇒ Object

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.



65
66
67
 
# File 'lib/archspec/dsl.rb', line 65

def todo(path = 'archspec_todo.yml')
  self.todo_path = path.to_s
end