docit 0.3.1 → 0.5.0

data/lib/docit/dsl.rb

@@ -2,14 +2,14 @@
 
 module Docit
   # Included in all Rails controllers via the Engine.
-  # Provides +swagger_doc+ and +use_docs+ class methods.
+  # Provides +doc_for+ and +use_docs+ class methods.
   module DSL
     def self.included(base)
       base.extend(ClassMethods)
     end
 
     module ClassMethods
-      def swagger_doc(action, &block)
+      def doc_for(action, &block)
         operation = Operation.new(
           controller: name,
           action: action
@@ -18,9 +18,12 @@ module Docit
         Registry.register(operation)
       end
 
+      # Backward-compatible alias
+      alias swagger_doc doc_for
+
       def use_docs(doc_module)
         doc_module.actions.each do |action|
-          swagger_doc(action, &doc_module[action])
+          doc_for(action, &doc_module[action])
         end
       end
     end

data/lib/docit/operation.rb

@@ -2,11 +2,11 @@
 
 module Docit
   # Represents the documentation for a single controller action.
-  # Created by +swagger_doc+ and stored in the {Registry}.
+  # Created by +doc_for+ and stored in the {Registry}.
   class Operation
     attr_reader :controller, :action, :_summary, :_description,
                 :_tags, :_responses, :_request_body, :_parameters,
-                :_security, :_deprecated
+                :_security, :_deprecated, :_operation_id
 
     def initialize(controller:, action:)
       @controller = controller
@@ -17,6 +17,7 @@ module Docit
       @_request_body = nil
       @_security = []
       @_deprecated = false
+      @_operation_id = nil
     end
 
     def summary(text)
@@ -35,6 +36,10 @@ module Docit
       @_deprecated = value
     end
 
+    def operation_id(text)
+      @_operation_id = text
+    end
+
     def security(scheme)
       @_security << scheme
     end

data/lib/docit/route_inspector.rb

@@ -5,7 +5,7 @@ module Docit
   class RouteInspector
     VALID_METHODS = %w[get post put patch delete].freeze
 
-    # Eagerly loads controller classes so swagger_doc/use_docs macros run before spec generation.
+    # Eagerly loads controller classes so doc_for/use_docs macros run before spec generation.
     def self.eager_load_controllers!
       return if defined?(Rails).nil? || Rails.application.routes.nil?
 

data/lib/docit/schema_generator.rb

@@ -12,11 +12,7 @@ module Docit
 
       spec = {
         openapi: "3.0.3",
-        info: {
-          title: config.title,
-          version: config.version,
-          description: config.description
-        },
+        info: build_info(config),
         paths: build_paths,
         components: {
           securitySchemes: config.security_schemes
@@ -37,6 +33,18 @@ module Docit
 
     private
 
+    def build_info(config)
+      info = {
+        title: config.title,
+        version: config.version,
+        description: config.description
+      }
+      info[:license] = config.license_info if config.license_info
+      info[:contact] = config.contact_info if config.contact_info
+      info[:termsOfService] = config.terms_of_service_url if config.terms_of_service_url
+      info
+    end
+
     def build_paths
       paths = {}
 
@@ -58,6 +66,7 @@ module Docit
 
     def build_operation(operation)
       result = {
+        operationId: operation._operation_id || generate_operation_id(operation),
         summary: operation._summary || operation.action.humanize,
         description: operation._description || "",
         tags: operation._tags,
@@ -183,5 +192,15 @@ module Docit
         hash[ex[:name].to_s] = entry
       end
     end
+
+    def generate_operation_id(operation)
+      # "Api::V1::UsersController" → "users" ; "index" → "listUsers"
+      resource = operation.controller
+                          .gsub(/.*::/, "") # strip namespace
+                          .gsub(/Controller$/, "") # strip suffix
+      action = operation.action
+
+      "#{action}_#{resource}".gsub("::", "_").downcase
+    end
   end
 end

data/lib/docit/system_graph/edge.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Docit
+  module SystemGraph
+    class Edge
+      attr_reader :id, :source, :target, :type, :confidence, :evidence
+
+      def initialize(id:, source:, target:, type:, confidence:, evidence:)
+        @id = id.to_s
+        @source = source.to_s
+        @target = target.to_s
+        @type = type.to_s
+        @confidence = confidence.to_s
+        @evidence = evidence.to_s
+      end
+
+      def to_h
+        {
+          id: id,
+          source: source,
+          target: target,
+          type: type,
+          confidence: confidence,
+          evidence: evidence
+        }
+      end
+    end
+  end
+end

data/lib/docit/system_graph/generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Docit
+  module SystemGraph
+    class Generator
+      def self.generate
+        new.generate
+      end
+
+      def generate
+        RailsAnalyzer.new.analyze.to_h
+      end
+    end
+  end
+end

data/lib/docit/system_graph/graph.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Docit
+  module SystemGraph
+    class Graph
+      VERSION = "1.0"
+
+      attr_reader :nodes, :edges, :framework
+
+      def initialize(framework: "rails")
+        @framework = framework
+        @nodes = {}
+        @edges = {}
+      end
+
+      def add_node(node)
+        nodes[node.id] ||= node
+      end
+
+      def add_edge(edge)
+        return if edge.source == edge.target
+        return unless nodes.key?(edge.source) && nodes.key?(edge.target)
+
+        edges[edge.id] ||= edge
+      end
+
+      def to_h
+        node_values = nodes.values
+        edge_values = edges.values
+
+        {
+          version: VERSION,
+          generated_at: Time.now.utc.iso8601,
+          framework: framework,
+          nodes: node_values.map(&:to_h),
+          edges: edge_values.map(&:to_h),
+          stats: stats(node_values, edge_values)
+        }
+      end
+
+      private
+
+      def stats(node_values, edge_values)
+        {
+          nodes: node_values.length,
+          edges: edge_values.length,
+          node_types: node_values.group_by(&:type).transform_values(&:length),
+          edge_types: edge_values.group_by(&:type).transform_values(&:length)
+        }
+      end
+    end
+  end
+end

data/lib/docit/system_graph/node.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Docit
+  module SystemGraph
+    class Node
+      attr_reader :id, :type, :label, :metadata, :file, :line, :status
+
+      def initialize(id:, type:, label:, metadata: {}, file: nil, line: nil, status: nil)
+        @id = id.to_s
+        @type = type.to_s
+        @label = label.to_s
+        @metadata = metadata
+        @file = file
+        @line = line
+        @status = status
+      end
+
+      def to_h
+        {
+          id: id,
+          type: type,
+          label: label,
+          metadata: metadata
+        }.tap do |hash|
+          hash[:file] = file if file
+          hash[:line] = line if line
+          hash[:status] = status if status
+        end
+      end
+    end
+  end
+end

data/lib/docit/system_graph/rails_analyzer.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module Docit
+  module SystemGraph
+    class RailsAnalyzer
+      VALID_METHODS = %w[get post put patch delete].freeze
+      SKIP_PREFIXES = %w[docit/ rails/ active_storage/ action_mailbox/].freeze
+
+      def initialize(graph: Graph.new, scanner: SourceScanner.new(root: Rails.root))
+        @graph = graph
+        @scanner = scanner
+      end
+
+      def analyze
+        add_routes_and_actions
+        add_schemas
+        add_models
+        add_source_nodes
+        graph
+      end
+
+      private
+
+      attr_reader :graph, :scanner
+
+      def add_routes_and_actions
+        route_infos.each do |info|
+          controller_id = node_id("controller", info[:controller])
+          action_id = "#{controller_id}##{info[:action]}"
+          route_id = "route:#{info[:method]}:#{info[:path]}"
+          operation = Registry.find(controller: info[:controller], action: info[:action])
+
+          graph.add_node(Node.new(
+                           id: controller_id,
+                           type: "controller",
+                           label: info[:controller],
+                           file: controller_file(info[:controller]),
+                           metadata: { controller_path: info[:controller_path] }
+                         ))
+          graph.add_node(Node.new(
+                           id: action_id,
+                           type: "action",
+                           label: "#{info[:controller]}##{info[:action]}",
+                           file: controller_file(info[:controller]),
+                           status: operation ? "documented" : "undocumented",
+                           metadata: { action: info[:action], http_method: info[:method], path: info[:path] }
+                         ))
+          graph.add_node(Node.new(
+                           id: route_id,
+                           type: "route",
+                           label: "#{info[:method].upcase} #{info[:path]}",
+                           metadata: { method: info[:method], path: info[:path] },
+                           status: operation ? "documented" : "undocumented"
+                         ))
+
+          graph.add_edge(edge(route_id, action_id, "routes_to", "high", "Rails route table"))
+          graph.add_edge(edge(controller_id, action_id, "contains", "high", "Rails controller action"))
+          add_doc_node(info, operation, action_id) if operation
+        end
+      end
+
+      def add_doc_node(info, operation, action_id)
+        doc_id = "doc:#{info[:controller].underscore}:#{info[:action]}"
+
+        request_body_info = nil
+        if operation._request_body
+          request_body_info = {
+            required: operation._request_body.required,
+            content_type: operation._request_body.content_type,
+            schema_ref: operation._request_body.schema_ref,
+            properties: operation._request_body.properties
+          }
+        end
+
+        responses_info = operation._responses.map do |res|
+          {
+            status: res.status,
+            description: res.description,
+            schema_ref: res.schema_ref,
+            properties: res.properties,
+            examples: res.examples
+          }
+        end
+
+        parameters_info = operation._parameters.params.map do |param|
+          {
+            name: param[:name],
+            location: param[:in],
+            type: param[:schema][:type],
+            required: param[:required],
+            description: param[:description]
+          }
+        end
+
+        graph.add_node(Node.new(
+                         id: doc_id,
+                         type: "doc",
+                         label: operation._summary || "#{info[:controller]}##{info[:action]}",
+                         metadata: {
+                           controller: info[:controller],
+                           action: info[:action],
+                           description: operation._description,
+                           tags: operation._tags,
+                           request_body: request_body_info,
+                           responses: responses_info,
+                           parameters: parameters_info
+                         },
+                         status: "documented"
+                       ))
+        graph.add_edge(edge(doc_id, action_id, "documents", "high", "Docit registry"))
+      end
+
+      def add_schemas
+        Docit.schemas.each_key do |name|
+          graph.add_node(Node.new(
+                           id: node_id("schema", name),
+                           type: "schema",
+                           label: name.to_s,
+                           metadata: { properties: Docit.schemas[name].properties.map { |prop| prop[:name].to_s } }
+                         ))
+        end
+      end
+
+      def add_models
+        return unless defined?(ActiveRecord::Base)
+
+        ActiveRecord::Base.descendants.each do |model|
+          next if model.name.nil?
+
+          model_id = node_id("model", model.name)
+          graph.add_node(Node.new(
+                           id: model_id,
+                           type: "model",
+                           label: model.name,
+                           file: model_file(model.name),
+                           metadata: { table_name: table_name(model) }
+                         ))
+          add_model_associations(model, model_id)
+        end
+      end
+
+      def add_model_associations(model, model_id)
+        return unless model.respond_to?(:reflect_on_all_associations)
+
+        model.reflect_on_all_associations.each do |association|
+          target = association.class_name
+          target_id = node_id("model", target)
+          next unless graph.nodes.key?(target_id)
+
+          graph.add_edge(edge(model_id, target_id, "association", "high", "ActiveRecord reflection: #{association.name}"))
+        end
+      end
+
+      def add_source_nodes
+        source_nodes = scanner.source_nodes
+        source_nodes.each { |node| graph.add_node(node) }
+
+        labels = graph.nodes.values.select { |node| %w[model service job mailer].include?(node.type) }.map(&:label)
+        graph.nodes.values.select { |node| %w[controller action service job mailer].include?(node.type) }.each do |source|
+          scanner.references_for(source.file, labels).each do |label|
+            target = graph.nodes.values.find { |node| node.label == label }
+            next unless target
+
+            graph.add_edge(edge(source.id, target.id, edge_type_for(target), "medium", "Constant reference in #{source.file}"))
+          end
+        end
+      end
+
+      def route_infos
+        return [] if defined?(Rails).nil? || Rails.application.routes.nil?
+
+        Rails.application.routes.routes.filter_map do |route|
+          controller_path = route.defaults[:controller]
+          action = route.defaults[:action]
+          next if controller_path.nil? || action.nil?
+          next if skip_route?(controller_path)
+
+          method = extract_verb(route)
+          next if VALID_METHODS.exclude?(method)
+
+          controller = "#{controller_path}_controller".camelize
+          next if excluded_path?(controller_file(controller))
+
+          {
+            controller: controller,
+            controller_path: controller_path,
+            action: action.to_s,
+            method: method,
+            path: normalize_path(route.path.spec.to_s)
+          }
+        end.uniq
+      end
+
+      def edge(source, target, type, confidence, evidence)
+        Edge.new(
+          id: "#{type}:#{source}->#{target}",
+          source: source,
+          target: target,
+          type: type,
+          confidence: confidence,
+          evidence: evidence
+        )
+      end
+
+      def node_id(type, label)
+        "#{type}:#{label.to_s.underscore.tr('/', ':')}"
+      end
+
+      def controller_file(controller)
+        "app/controllers/#{controller.underscore}.rb"
+      end
+
+      def model_file(model)
+        "app/models/#{model.underscore}.rb"
+      end
+
+      def edge_type_for(target)
+        target.type == "model" ? "uses_model" : "calls"
+      end
+
+      def table_name(model)
+        model.table_name if model.respond_to?(:table_name)
+      rescue ActiveRecord::StatementInvalid
+        nil
+      end
+
+      def skip_route?(controller_path)
+        SKIP_PREFIXES.any? { |prefix| controller_path.start_with?(prefix) }
+      end
+
+      def excluded_path?(path)
+        Docit.configuration.system_graph_excluded_paths.any? do |excluded|
+          path.start_with?(excluded.to_s)
+        end
+      end
+
+      def extract_verb(route)
+        verb = route.verb
+        verb = verb.source if verb.is_a?(Regexp)
+        verb.to_s.downcase.gsub(/[^a-z]/, "")
+      end
+
+      def normalize_path(path)
+        path
+          .gsub("(.:format)", "")
+          .gsub(/\(\.?:(\w+)\)/, '{\1}')
+          .gsub(/:(\w+)/, '{\1}')
+      end
+    end
+  end
+end

data/lib/docit/system_graph/source_scanner.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Docit
+  module SystemGraph
+    class SourceScanner
+      SOURCE_TYPES = {
+        "app/services" => "service",
+        "app/jobs" => "job",
+        "app/mailers" => "mailer"
+      }.freeze
+
+      def initialize(root:, excluded_paths: Docit.configuration.system_graph_excluded_paths)
+        @root = root
+        @excluded_paths = excluded_paths.map(&:to_s)
+      end
+
+      def source_nodes
+        SOURCE_TYPES.each_with_object([]) do |(dir, type), nodes|
+          scan_dir(dir).each do |path|
+            relative = relative_path(path)
+            label = constant_name(relative, dir)
+            nodes << Node.new(
+              id: node_id(type, label),
+              type: type,
+              label: label,
+              file: relative,
+              metadata: { path: relative }
+            )
+          end
+        end
+      end
+
+      def references_for(path, candidates)
+        return [] unless path && File.exist?(full_path(path))
+
+        content = File.read(full_path(path))
+        candidates.select do |candidate|
+          content.match?(/\b#{Regexp.escape(candidate)}\b/)
+        end
+      end
+
+      private
+
+      attr_reader :root
+      attr_reader :excluded_paths
+
+      def scan_dir(dir)
+        full_dir = root.join(dir)
+        return [] unless Dir.exist?(full_dir)
+
+        Dir.glob(full_dir.join("**", "*.rb")).sort.reject do |path|
+          excluded?(relative_path(path))
+        end
+      end
+
+      def relative_path(path)
+        path.to_s.sub("#{root}/", "")
+      end
+
+      def constant_name(relative, dir)
+        relative.delete_prefix("#{dir}/").delete_suffix(".rb").camelize
+      end
+
+      def node_id(type, label)
+        "#{type}:#{label.underscore.tr('/', ':')}"
+      end
+
+      def full_path(path)
+        root.join(path)
+      end
+
+      def excluded?(path)
+        excluded_paths.any? { |excluded| path.start_with?(excluded) }
+      end
+    end
+  end
+end

data/lib/docit/system_graph.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "system_graph/node"
+require_relative "system_graph/edge"
+require_relative "system_graph/graph"
+require_relative "system_graph/source_scanner"
+require_relative "system_graph/rails_analyzer"
+require_relative "system_graph/generator"