Class: ArchSpec::DSL::ComponentProxy

Inherits:
Object
  • Object
show all
Defined in:
lib/archspec/dsl.rb

Overview

A handle to one component, returned by ArchSpec::DSL::Context#component and by calling a declared component's name. Rule methods return self, so they chain.

services.cannot_use(:controllers).cannot_call(:render, receiver: :none)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(definition, name) ⇒ ComponentProxy

Returns a new instance of ComponentProxy.



174
175
176
177
 
# File 'lib/archspec/dsl.rb', line 174

def initialize(definition, name)
  @definition = definition
  @name = name.to_sym
end

Instance Attribute Details

#definition ⇒ Object (readonly)

Returns the value of attribute definition.



172
173
174
 
# File 'lib/archspec/dsl.rb', line 172

def definition
  @definition
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



172
173
174
 
# File 'lib/archspec/dsl.rb', line 172

def name
  @name
end

Instance Method Details

#can_only_be_used_by(*consumers) ⇒ Object

Allowlists the components that may reference this one, the inverse of #can_use. A reference from any other component fails. Use it to protect a shared kernel or a component with a deliberately narrow audience.

shared_kernel.can_only_be_used_by :billing, :catalog

Rule id: dependencies.consumers.



212
213
214
215
 
# File 'lib/archspec/dsl.rb', line 212

def can_only_be_used_by(*consumers)
  add_rule(Rules::AllowedConsumersRule.new(name, consumers))
  self
end

#can_use(*targets) ⇒ Object Also known as: only_depend_on, must_only_depend_on

Allowlists the components this one may depend on. A reference to any other declared component fails.

controllers.can_use :models, :services

only_depend_on and must_only_depend_on are aliases. Rule id: dependencies.allow.



186
187
188
189
 
# File 'lib/archspec/dsl.rb', line 186

def can_use(*targets)
  add_rule(Rules::AllowDependenciesRule.new(name, targets))
  self
end

#cannot_call(*methods, receiver: :any) ⇒ Object

Forbids calling the named methods. By default any receiver matches, so this catches record.update and cache.update alike. Pass receiver: :none to match only bare, implicit-+self+ calls, which is how the Rails presets keep the controller API out of models.

queries.cannot_call :save, :update, :destroy
services.cannot_call :render, :params, receiver: :none

A bare call to a method the component defines, inherits, or generates with attr_* or delegate is treated as its own API and not flagged. Rule id: methods.forbid.



228
229
230
231
 
# File 'lib/archspec/dsl.rb', line 228

def cannot_call(*methods, receiver: :any)
  add_rule(Rules::CannotCallRule.new(name, methods, receiver: receiver))
  self
end

#cannot_define(*methods) ⇒ Object

Forbids defining the named methods in this component. Use it when the method name itself is a design smell there, such as call on a component that should not hold command objects.

models.cannot_define :call

Rule id: methods.define_forbid.



240
241
242
243
 
# File 'lib/archspec/dsl.rb', line 240

def cannot_define(*methods)
  add_rule(Rules::CannotDefineMethodRule.new(name, methods))
  self
end

#cannot_instantiate_and_invoke ⇒ Object

Forbids the one-shot Thing.new(...).call pattern, where a class is instantiated and immediately invoked. Use it to steer a component toward plain methods over anonymous command objects.

Rule id: objects.instantiate_and_invoke_forbid.



250
251
252
253
 
# File 'lib/archspec/dsl.rb', line 250

def cannot_instantiate_and_invoke
  add_rule(Rules::CannotInstantiateAndInvokeRule.new(name))
  self
end

#cannot_reference_constants(*constants) ⇒ Object

Forbids referencing the named constants or anything under them. Use this when the boundary is a framework constant rather than a component.

models.cannot_reference_constants "ActionController", "ActionView"

Rule id: constants.forbid.



261
262
263
264
 
# File 'lib/archspec/dsl.rb', line 261

def cannot_reference_constants(*constants)
  add_rule(Rules::CannotReferenceConstantsRule.new(name, constants))
  self
end

#cannot_reference_includers ⇒ Object

Forbids a concern from referencing the constants that include it. A concern that names its includer knows too much about who uses it, which couples the two and defeats the point of extracting the concern.

component :model_concerns, in: "app/models/concerns/**/*.rb"
model_concerns.cannot_reference_includers

Rule id: concerns.independence.



289
290
291
292
 
# File 'lib/archspec/dsl.rb', line 289

def cannot_reference_includers
  add_rule(Rules::ConcernIndependenceRule.new(name))
  self
end

#cannot_use(*targets) ⇒ Object

Forbids depending on the named components. Narrower than #can_use: only the listed components fail, other dependencies are left alone.

models.cannot_use :controllers, :helpers

Rule id: dependencies.forbid.



200
201
202
203
 
# File 'lib/archspec/dsl.rb', line 200

def cannot_use(*targets)
  add_rule(Rules::ForbidDependenciesRule.new(name, targets))
  self
end

#must_be_empty(because: nil) ⇒ Object

Requires the component to hold no files. Use it to keep a directory empty, such as app/services in a vanilla Rails app, with a reason shown in the diagnostic.

component(:services, in: "app/services/**/*.rb")
.must_be_empty(because: "behavior belongs on models")

Rule id: components.empty.



302
303
304
305
 
# File 'lib/archspec/dsl.rb', line 302

def must_be_empty(because: nil)
  add_rule(Rules::MustBeEmptyRule.new(name, because: because))
  self
end

#must_implement(*methods) ⇒ Object

Requires every class in the component to implement all the named instance methods. Methods inherited from resolvable superclasses or mixins count.

commands.must_implement :perform

Rule id: protocol.must_implement.



314
315
316
317
318
319
 
# File 'lib/archspec/dsl.rb', line 314

def must_implement(*methods)
  methods.each do |method_name|
    add_rule(Rules::MustImplementRule.new(name, method_name))
  end
  self
end

#must_implement_one_of(*methods) ⇒ Object

Requires every class in the component to implement at least one of the named instance methods. Useful when a protocol allows either name.

commands.must_implement_one_of :perform, :call

Rule id: protocol.must_implement_one_of.



327
328
329
330
 
# File 'lib/archspec/dsl.rb', line 327

def must_implement_one_of(*methods)
  add_rule(Rules::MustImplementOneOfRule.new(name, methods))
  self
end

#public_api(*patterns, constants: nil, namespace: nil) ⇒ Object

Marks part of the component as its public API. References from outside must resolve to a public constant; everything else becomes private.

billing.public_api "packs/billing/app/public/**/*.rb"
billing.public_api constants: "Billing::Api"
billing.public_api namespace: "Billing::Public"

constants matches exact names, namespace matches a name and its children. Code inside the component may still reach its own internals. Rule id: dependencies.privacy.



276
277
278
279
 
# File 'lib/archspec/dsl.rb', line 276

def public_api(*patterns, constants: nil, namespace: nil)
  add_rule(Rules::PublicApiRule.new(name, files: patterns, constants: constants, namespaces: namespace))
  self
end