class ArchSpec::DSL::ComponentProxy

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.

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.

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.

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.

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.

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.

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.

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.

Starts a naming-convention rule over the component’s defined, public methods. Select the methods with matching, then assert something about them. Every check is name-based and exact.

models.methods.matching(/\A(get|set)_/).forbidden
chat.methods.matching(/\Awith_(?<base>.+)/).requires("without_%{base}")
chat.methods.matching(/\Awith_(?<b>.+)/).requires("%{b}", on: agent, scope: :class)

Pass scope: :class to select class methods instead of instance methods. See ArchSpec::Rules::Naming::Selected for the constraints (forbidden, requires). Rule ids: naming.forbidden, naming.requires.

This shadows +Object#methods+ on the proxy, which is only ever used as a short-lived DSL handle.

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.

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.

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.

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.