Manual de utilização da ferramenta ArchRuby (também disponível em inglês)

1. Instalação e requisitos
2. Definição de módulos
3. Restrições arquiteturais
4. Relatório de violações
5. Visualização arquitetural
6. Aplicando a ferramenta

Instalação e requisitos

A ferramenta ArchRuby é disponibilizada como um GEM para a linguagem Ruby. O processo de instalação segue o mesmo padrão de instalação de GEM na linguagem Ruby. Basta executar o comando gem install archruby que a instalação será feita de forma automática.

ArchRuby tem dependências dos seguintes GEMs:
* ruby_graphviz
* ruby_parser
* sexp_processor

Todas as dependências são instaladas junto com a instalação da GEM archruby. É preciso ter instalado a biblioteca Graphviz no seu sistema.

Definição de módulos

A definição de módulos na ferramenta ArchRuby é feita através de um arquivo YAML. É através dos módulos que o mapeamento do sistema é feito.

Exemplo:

            <module_id >:
              (files | gems): ’< pattern_desc > {, < pattern_desc >}’
              [(allowed | forbidden): ’< module_id> {, < module_id>}’]
              [(required): ’< module_id > {, < module_id>}’]
              

A chave < module_id > é o identificador do módulo. O módulo pode ser formado por arquivos (files) ou por Gems (gems) que devem ser definidos por um ou mais < pattern_desc > separados por vírgula. O casamento de padrões é baseado em shell glob (padrão da biblioteca de arquivos do Ruby) para mapear vários arquivos de uma só vez. Para a detecção de divergências, para cada módulo pode-se definir os módulos cujo acesso é autorizado (allowed) ou não autorizado (forbidden), os quais são definidos por um ou mais < module_id > separados por vírgula (veja mais na seção Restrições Arquiteturais). Similarmente, para a detecção de ausências, para cada módulo pode-se definir os módulos cujo acesso é obrigatório (required), os quais são definidos conforme supracitado. É importante mencionar que, para um mesmo módulo, a chave required pode ser utilizada em conjunto com as chaves allowed e forbidden. No entanto, não existe a possibilidade de se utilizar a chave allowed e forbidden na definição de um mesmo módulo.

Restrições arquiteturais

Dentro da definição de módulos é possível definir as restrições arquiteturais que serão aplicadas a ele. É através dessas restrições arquiteturais que a ferramenta detectará se a arquitetura planejada está sendo seguida ou não.

Existem três tipos de restrições arquiteturais que podem ser utilizadas na ferramenta ArchRuby:
* Allowed
* Forbidden
* Required

As restrições do tipo allowed indicam que o módulo está autorizado a acessar os módulos presentes na chave allowed conforme explicado na seção Definição de módulos. Já as restrições do tipo forbidden indicam que o módulo não pode acessar os módulos presentes na chave forbidden. Por fim, as restrições do tipo required indicam quais módulos são obrigatórios de depender.

Exemplo:

            controller:
              files: 'app/controllers/**/*.rb'
              allowed: 'model, integracao_twitter, integracao_pdf, actioncontroller, view'
            

O exemplo acima demonstra as restrições arquiteturais de um módulo chamado controller. O módulo é composto por todos os arquivos, .rb, que estão na pasta app/controllers e está permitido acessar os módulos: model, integracao_twitter, integracao_pdf, actioncontroller e view.

Relatório de violações

O processo de conformidade arquitetural gera como saída um relatório reportando todas as violações arquiteturais encontradas (divergências e ausências).

Exemplo de uma divergência:

              1 divergence:
              2  class_origin: TwitterController
              3  line_origin: 21
              4  class_target: Twitter::REST::Client
              5  module_origin: controller
              6  module_target: twitter
              7  message: module controller is not allowed to depend on module twitter
              

Exemplo de uma ausência:

              1 absence:
              2  class_origin: TesteClass
              3  line_origin:
              4  class_target:
              5  module_origin: model
              6  module_target: activerecord
              7  message: not implement a required module
              

O relatório indica o tipo de violação (linha 1), informações da classe de origem (linhas 2–4), da classe de destino (linhas 5–6) e da regra não respeitada (linhas 7).

Visualização arquitetural

Após o processo de conformidade arquitetural, ArchRuby apresenta uma visão de alto nível da arquitetura. O modelo de alto nível é um grafo de dependências orientado, onde os vértices representam os módulos definidos na especificação da arquitetura no arquivo YAML e as arestas representam as dependências estabelecidas entre os módulos, as quais são diferenciadas quando se tratar de violações arquiteturais.

Exemplo de imagem gerada pela ferramenta:

Aplicando a ferramenta

Para utilizar a ferramenta ArchRuby basta executar o comando:

                archruby --arch_def_file=< path definição da arquitetura > --app_root_path=< path root do sistema >
              

Lembrando que esse comando ficará disponível para utilização logo após a instalação da ferramenta.