archspec 0.1.0.pre1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 14c27bcdf86ac400321503fdb1f2a5b904068aafaac65921e00a33a80acea45f
+  data.tar.gz: fca658eec0f2f6becfc7159c989ba8ad132c3de0d39c5dfb59561f249afb2407
+SHA512:
+  metadata.gz: 4b51c1666d0ec2b27913e796be1969f81b030582b2faf18f9d18f29a1badd7ae1f4b68f2d196a94e976d16fc40e217699a899c6460e037e6a413a68a6aac2299
+  data.tar.gz: 8853a35c37af66fd6f18d2aaace5c6e44a22fccd941cff3b00fae5ec739184451329cd639d9cba730a3f925b2a66c232c0e85dbd6b5122c85c91437a17515e1e

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArchSpec contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,225 @@
+# ArchSpec
+
+Architecture checks for Ruby and Rails.
+
+Turn your application's architecture into executable checks.
+
+ArchSpec reads Ruby source with Prism, maps conventional Rails files to
+constants, and checks the structural rules you write down: components, layers,
+constant references, inheritance, mixins, named method calls, method protocols,
+cycles, and Rails boundaries.
+
+It does not try to infer the "true" design pattern of arbitrary Ruby code. You
+describe the architecture your team wants. ArchSpec checks whether the code still
+matches it.
+
+## Why ArchSpec?
+
+Architecture usually lives in pull request comments, onboarding docs, and senior
+engineers' heads. That does not scale well, especially when code is moving fast.
+
+ArchSpec gives you a small Ruby DSL for the rules that code review otherwise has
+to remember:
+
+- models do not reach into controllers
+- domain code does not depend on adapters
+- packs only depend on approved packs
+- query objects do not call obvious write methods
+- generated code follows the same boundaries as hand-written code
+
+## Show me the code
+
+Start with conventional Rails boundaries:
+
+```ruby
+# Archspec.rb
+ArchSpec.define "Application architecture" do
+  root "."
+  preset :rails_way
+end
+```
+
+Add layers when the app has a clear direction of dependencies:
+
+```ruby
+ArchSpec.define "Application architecture" do
+  root "."
+  architecture :layered, layers: {
+    interface: "app/controllers/**/*.rb",
+    application: "app/services/**/*.rb",
+    domain: "app/models/**/*.rb"
+  }
+end
+```
+
+Keep a hexagonal core away from adapters:
+
+```ruby
+ArchSpec.define "Application architecture" do
+  root "."
+
+  architecture :hexagonal,
+    application: %w[app/services/**/*.rb app/use_cases/**/*.rb],
+    domain: "app/domain/**/*.rb",
+    ports: "app/ports/**/*.rb",
+    adapters: %w[app/adapters/**/*.rb app/integrations/**/*.rb]
+end
+```
+
+Check a modular monolith:
+
+```ruby
+ArchSpec.define "Application architecture" do
+  root "."
+
+  architecture :modular_monolith,
+    components: {
+      billing: "packs/billing/**/*.rb",
+      catalog: "packs/catalog/**/*.rb",
+      shared: "packs/shared/**/*.rb"
+    },
+    allow: {
+      billing: %i[shared],
+      catalog: %i[shared]
+    }
+end
+```
+
+Write local rules in plain Ruby:
+
+```ruby
+ArchSpec.define "Application architecture" do
+  root "."
+
+  component :controllers, in: "app/controllers/**/*.rb"
+  component :models, in: "app/models/**/*.rb"
+  component :services, in: "app/services/**/*.rb"
+
+  controllers.can_use :models, :services
+  models.cannot_use :controllers
+  services.cannot_call :render, :redirect_to, :params, :session
+  services.cannot_instantiate_and_invoke
+end
+```
+
+Check command/query separation:
+
+```ruby
+ArchSpec.define "Application architecture" do
+  root "."
+
+  architecture :cqrs,
+    commands: "app/commands/**/*.rb",
+    queries: "app/queries/**/*.rb",
+    read_models: "app/read_models/**/*.rb"
+end
+```
+
+## What It Checks
+
+- **Dependencies:** allowed and forbidden references between components
+- **Layers:** dependency direction and cycles
+- **Rails MVC:** controller APIs kept out of models and services
+- **Architectures:** Rails MVC, layered, hexagonal, clean, modular monolith, CQRS, and event-driven bundles
+- **Protocols:** required methods such as `resolve`, `perform`, or project-specific interfaces
+- **Objects:** rules against one-shot `Something.new(...).whatever` command objects
+- **Zeitwerk names:** conventional file names defining the expected constants
+- **Suppressions:** narrow local exceptions with a reason
+
+## Installation
+
+Add ArchSpec to your Gemfile:
+
+```ruby
+group :development, :test do
+  gem "archspec"
+end
+```
+
+Then install it:
+
+```sh
+bundle install
+```
+
+Create `Archspec.rb`:
+
+```sh
+bundle exec archspec init
+```
+
+Run the checks:
+
+```sh
+bundle exec archspec check
+```
+
+## Commands
+
+```sh
+bundle exec archspec init
+bundle exec archspec check
+bundle exec archspec check --format json
+bundle exec archspec check --update-baseline
+bundle exec archspec explain app/models/user.rb
+```
+
+`explain` shows why a file or constant belongs to a component and which outgoing
+facts ArchSpec found.
+
+## Checking AI-Written Code
+
+Generated code should pass the same architecture checks as hand-written code.
+
+After an AI-assisted change:
+
+```sh
+bundle exec archspec check
+```
+
+If it fails, read the evidence before changing the spec:
+
+```text
+[dependencies.forbid] app/models/user.rb:2:3
+  models must not depend on controllers
+  evidence: User references_constant UsersController
+  confidence: high
+```
+
+Most failures should be fixed in the generated code. Update the spec only when
+the architecture decision itself has changed.
+
+## Baselines and Suppressions
+
+Use a baseline when adopting ArchSpec in an existing app:
+
+```ruby
+baseline ".archspec_todo.yml"
+```
+
+```sh
+bundle exec archspec check --update-baseline
+```
+
+Use local suppressions for deliberate exceptions:
+
+```ruby
+# archspec:disable-next-line dependencies.forbid -- legacy admin export
+Admin::UsersController
+```
+
+## Documentation
+
+Read the guides at [crmne.github.io/archspec](https://crmne.github.io/archspec/).
+
+## Dogfooding
+
+This repository checks its own architecture:
+
+```sh
+bundle exec rake architecture
+```
+
+## License
+
+Released under the MIT License.

data/exe/archspec

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "archspec"
+
+exit ArchSpec::CLI.run(ARGV)

data/lib/archspec/analyzer.rb

@@ -0,0 +1,376 @@
+require "prism"
+require "pathname"
+require "set"
+
+module ArchSpec
+  module Analyzer
+    extend self
+
+    def analyze(definition, root:)
+      root = File.expand_path(root)
+      graph = Graph.new(root)
+
+      ruby_files(definition, root).each do |path|
+        result = Prism.parse_file(path)
+        graph.add_file(
+          path: path,
+          expected_constant: expected_constant_for(path, root),
+          parse_errors: parse_errors_for(path, result.errors),
+          suppressions: suppressions_for(result.comments)
+        )
+
+        SourceVisitor.visit(graph, path, result.value) if result.value
+      end
+
+      graph.assign_components(definition.component_specs.values)
+      graph
+    end
+
+    private
+
+    def ruby_files(definition, root)
+      ignored = ignored_files(definition, root)
+
+      definition.analysis_patterns.flat_map do |pattern|
+        Dir.glob(File.absolute_path(pattern, root))
+      end.select do |path|
+        File.file?(path) && path.end_with?(".rb")
+      end.map do |path|
+        File.expand_path(path)
+      end.uniq.reject do |path|
+        ignored.include?(path)
+      end.sort
+    end
+
+    def ignored_files(definition, root)
+      definition.ignore_patterns.flat_map do |pattern|
+        Dir.glob(File.absolute_path(pattern, root))
+      end.select { |path| File.file?(path) }.map { |path| File.expand_path(path) }.to_set
+    end
+
+    def expected_constant_for(path, root)
+      relative = Pathname(path).relative_path_from(Pathname(root)).to_s
+      stem =
+        case relative
+        when %r{\Aapp/[^/]+/concerns/(.+)\.rb\z}
+          Regexp.last_match(1)
+        when %r{\Aapp/[^/]+/(.+)\.rb\z}
+          Regexp.last_match(1)
+        when %r{\Alib/(.+)\.rb\z}
+          Regexp.last_match(1)
+        when %r{\A(?:packs|engines)/[^/]+/app/[^/]+/(.+)\.rb\z}
+          Regexp.last_match(1)
+        else
+          return nil
+        end
+
+      camelize_path(stem)
+    end
+
+    def camelize_path(path)
+      path.split("/").map do |part|
+        part.split("_").map { |word| word[0] ? word[0].upcase + word[1..] : word }.join
+      end.join("::")
+    end
+
+    def suppressions_for(comments)
+      SuppressionParser.parse(comments)
+    end
+
+    def parse_errors_for(path, errors)
+      errors.map do |error|
+        ParseError.new(error.message, SourceLocation.from_prism(path, error.location))
+      end
+    end
+
+    module SuppressionParser
+      extend self
+
+      DISABLE_PATTERN = /\Aarchspec:disable(?:-(next-line|line))?(?:\s+([a-z0-9_.-]+|\*))?(?:\s+--\s*(.+))?\z/i
+      ENABLE_PATTERN = /\Aarchspec:enable(?:\s+([a-z0-9_.-]+|\*))?\z/i
+
+      def parse(comments)
+        suppressions = []
+        active = Hash.new { |hash, key| hash[key] = [] }
+
+        sorted_comments(comments).each do |comment|
+          text = comment.slice.sub(/\A#\s?/, "").strip
+          line = comment.location.start_line
+
+          if (match = text.match(DISABLE_PATTERN))
+            mode, rule, reason = match.captures
+            rule = normalize_rule(rule)
+
+            case mode
+            when "line"
+              suppressions << Suppression.new(rule, line, line, reason)
+            when "next-line"
+              suppressions << Suppression.new(rule, line + 1, line + 1, reason)
+            else
+              active[rule] << [line + 1, reason]
+            end
+          elsif (match = text.match(ENABLE_PATTERN))
+            rule = normalize_rule(match[1])
+            if active[rule].any?
+              start_line, reason = active[rule].pop
+              suppressions << Suppression.new(rule, start_line, [line - 1, start_line].max, reason)
+            end
+          end
+        end
+
+        active.each do |rule, entries|
+          entries.each do |start_line, reason|
+            suppressions << Suppression.new(rule, start_line, Float::INFINITY, reason)
+          end
+        end
+
+        suppressions
+      end
+
+      private
+
+      def sorted_comments(comments)
+        comments.sort_by { |comment| [comment.location.start_line, comment.location.start_column] }
+      end
+
+      def normalize_rule(rule)
+        return nil if rule.nil? || rule == "*"
+
+        rule.downcase
+      end
+    end
+
+    module SourceVisitor
+      extend self
+
+      DYNAMIC_MESSAGES = %i[
+        class_eval
+        const_get
+        const_set
+        define_method
+        instance_eval
+        method_missing
+        module_eval
+        public_send
+        send
+      ].freeze
+
+      MIXIN_MESSAGES = {
+        include: :includes,
+        prepend: :prepends,
+        extend: :extends
+      }.freeze
+
+      def visit(graph, path, node, current_constant: nil, namespace: [])
+        return unless node
+
+        case node
+        when Prism::ProgramNode, Prism::StatementsNode
+          visit_children(graph, path, node, current_constant: current_constant, namespace: namespace)
+        when Prism::ClassNode
+          visit_class(graph, path, node, current_constant: current_constant, namespace: namespace)
+        when Prism::ModuleNode
+          visit_module(graph, path, node, current_constant: current_constant, namespace: namespace)
+        when Prism::DefNode
+          visit_def(graph, path, node, current_constant: current_constant, namespace: namespace)
+        when Prism::CallNode
+          visit_call(graph, path, node, current_constant: current_constant, namespace: namespace)
+        when Prism::ConstantPathNode, Prism::ConstantReadNode
+          add_constant_reference(graph, path, node, current_constant)
+        else
+          visit_children(graph, path, node, current_constant: current_constant, namespace: namespace)
+        end
+      end
+
+      private
+
+      def visit_class(graph, path, node, current_constant:, namespace:)
+        name = qualified_constant_name(node.constant_path, namespace)
+        constant = graph.add_constant(
+          name: name,
+          kind: :class,
+          path: path,
+          location: SourceLocation.from_prism(path, node.location)
+        )
+
+        if node.superclass
+          superclass = constant_reference_name(node.superclass)
+          constant.superclass = superclass
+          graph.add_edge(
+            type: :inherits_from,
+            from_path: path,
+            from_constant: constant.name,
+            to: superclass,
+            location: SourceLocation.from_prism(path, node.superclass.location)
+          )
+        end
+
+        visit(graph, path, node.body, current_constant: constant.name, namespace: constant.name.split("::"))
+      end
+
+      def visit_module(graph, path, node, current_constant:, namespace:)
+        name = qualified_constant_name(node.constant_path, namespace)
+        constant = graph.add_constant(
+          name: name,
+          kind: :module,
+          path: path,
+          location: SourceLocation.from_prism(path, node.location)
+        )
+
+        visit(graph, path, node.body, current_constant: constant.name, namespace: constant.name.split("::"))
+      end
+
+      def visit_def(graph, path, node, current_constant:, namespace:)
+        if current_constant && (constant = graph.constants_named(current_constant).find { |candidate| candidate.path == path })
+          if node.receiver
+            constant.add_class_method(node.name, location: SourceLocation.from_prism(path, node.location))
+          else
+            constant.add_instance_method(node.name, location: SourceLocation.from_prism(path, node.location))
+          end
+        end
+
+        if node.name == :method_missing
+          graph.add_edge(
+            type: :dynamic_feature,
+            from_path: path,
+            from_constant: current_constant,
+            to: "method_missing",
+            location: SourceLocation.from_prism(path, node.location),
+            confidence: :unknown_due_to_dynamic_feature
+          )
+        end
+
+        visit_children(graph, path, node, current_constant: current_constant, namespace: namespace)
+      end
+
+      def visit_call(graph, path, node, current_constant:, namespace:)
+        return visit_children(graph, path, node, current_constant: current_constant, namespace: namespace) unless node.message
+
+        message = node.message.to_sym
+        location = SourceLocation.from_prism(path, node.location)
+
+        if (one_shot = instantiates_and_invokes(node))
+          graph.add_edge(
+            type: :instantiates_and_invokes,
+            from_path: path,
+            from_constant: current_constant,
+            to: one_shot,
+            location: location
+          )
+        end
+
+        if (required = literal_require_argument(node))
+          graph.add_edge(
+            type: message == :require_relative ? :requires_relative : :requires,
+            from_path: path,
+            from_constant: current_constant,
+            to: required,
+            location: location
+          )
+        end
+
+        if (edge_type = MIXIN_MESSAGES[message])
+          constant_arguments(node).each do |constant_name|
+            if current_constant && (constant = graph.constants_named(current_constant).find { |candidate| candidate.path == path })
+              constant.add_mixin(message, constant_name)
+            end
+
+            graph.add_edge(
+              type: edge_type,
+              from_path: path,
+              from_constant: current_constant,
+              to: constant_name,
+              location: location
+            )
+          end
+        end
+
+        graph.add_edge(
+          type: :calls_named_method,
+          from_path: path,
+          from_constant: current_constant,
+          to: message,
+          location: location
+        )
+
+        if DYNAMIC_MESSAGES.include?(message)
+          graph.add_edge(
+            type: :dynamic_feature,
+            from_path: path,
+            from_constant: current_constant,
+            to: message,
+            location: location,
+            confidence: :unknown_due_to_dynamic_feature
+          )
+        end
+
+        visit_children(graph, path, node, current_constant: current_constant, namespace: namespace)
+      end
+
+      def add_constant_reference(graph, path, node, current_constant)
+        graph.add_edge(
+          type: :references_constant,
+          from_path: path,
+          from_constant: current_constant,
+          to: constant_reference_name(node),
+          location: SourceLocation.from_prism(path, node.location)
+        )
+      end
+
+      def visit_children(graph, path, node, current_constant:, namespace:)
+        node.child_nodes.compact.each do |child|
+          visit(graph, path, child, current_constant: current_constant, namespace: namespace)
+        end
+      end
+
+      def literal_require_argument(node)
+        return unless %i[require require_relative].include?(node.message.to_sym)
+        return if node.receiver
+
+        first_argument = node.arguments&.arguments&.first
+        return unless first_argument.is_a?(Prism::StringNode)
+
+        first_argument.unescaped
+      end
+
+      def constant_arguments(node)
+        node.arguments&.arguments&.filter_map do |argument|
+          constant_reference_name(argument) if constant_node?(argument)
+        end || []
+      end
+
+      def instantiates_and_invokes(node)
+        receiver = node.receiver
+        return unless receiver.is_a?(Prism::CallNode)
+        return unless receiver.message == "new"
+
+        "#{new_receiver_name(receiver)}##{node.message}"
+      end
+
+      def new_receiver_name(node)
+        return constant_reference_name(node.receiver) if constant_node?(node.receiver)
+
+        node.receiver&.slice || "(unknown)"
+      end
+
+      def qualified_constant_name(node, namespace)
+        raw = constant_reference_name(node)
+        absolute = node.respond_to?(:full_name_parts) && node.full_name_parts.first == :""
+
+        if absolute || raw.include?("::") || namespace.empty?
+          raw
+        else
+          "#{namespace.join("::")}::#{raw}"
+        end
+      end
+
+      def constant_reference_name(node)
+        node.full_name.to_s.sub(/\A::/, "")
+      end
+
+      def constant_node?(node)
+        node.is_a?(Prism::ConstantReadNode) || node.is_a?(Prism::ConstantPathNode)
+      end
+    end
+  end
+end