docit 0.4.0 → 0.6.0

data/lib/docit/system_graph/rails_analyzer.rb

@@ -0,0 +1,278 @@
+# 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
+        # Runs last: Graph#add_edge drops edges to not-yet-created nodes, so
+        # schema-usage edges must be added after both doc and schema nodes exist.
+        add_schema_usage_edges
+        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
+
+      # Link each doc node to every shared schema it references via $ref (in its
+      # request body or any response). Runs as a final pass because add_edge only
+      # keeps edges whose endpoints already exist as nodes. Confidence is high —
+      # the references come straight from the Docit registry.
+      def add_schema_usage_edges
+        graph.nodes.values.select { |node| node.type == "doc" }.each do |doc|
+          operation = Registry.find(controller: doc.metadata[:controller], action: doc.metadata[:action])
+          next unless operation
+
+          schema_refs_for(operation).each do |ref|
+            graph.add_edge(edge(doc.id, node_id("schema", ref), "uses_schema", "high", "Docit registry $ref"))
+          end
+        end
+      end
+
+      def schema_refs_for(operation)
+        refs = [operation._request_body&.schema_ref]
+        operation._responses.each { |res| refs << res.schema_ref }
+        refs.compact.uniq
+      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)
+        sources = graph.nodes.values.select { |node| %w[controller action service job mailer].include?(node.type) }
+        sources.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,76 @@
+# 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, :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"

data/lib/docit/ui/base_renderer.rb

@@ -3,10 +3,11 @@
 module Docit
   module UI
     class BaseRenderer
-      attr_reader :spec_url, :title, :nav_paths
+      attr_reader :spec_url, :system_url, :title, :nav_paths
 
-      def initialize(spec_url:, nav_paths: {})
+      def initialize(spec_url:, system_url: nil, nav_paths: {})
         @spec_url = spec_url
+        @system_url = system_url
         @nav_paths = nav_paths
         @title = ERB::Util.html_escape(Docit.configuration.title)
       end
@@ -20,35 +21,62 @@ module Docit
       def nav_bar(active:)
         swagger_active = active == :swagger
         scalar_active = active == :scalar
+        system_active = active == :system
 
         <<~HTML
-          <nav style="
-            display: flex; align-items: center; gap: 8px;
-            padding: 6px 16px;
-            background: #1a1a2e; color: #fff;
-            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-            font-size: 13px; position: sticky; top: 0; z-index: 9999;
-          ">
+          <style>
+            /* Theme-aware nav. Falls back to the original dark values when the
+               page has no theme tokens (e.g. Swagger/Scalar renderers). */
+            .docit-nav {
+              display: flex; align-items: center; gap: 8px;
+              padding: 6px 16px;
+              background: var(--bg-glass, #111827);
+              color: var(--text, #ffffff);
+              border-bottom: 1px solid var(--border, transparent);
+              backdrop-filter: blur(12px) saturate(150%);
+              font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+              font-size: 13px; position: sticky; top: 0; z-index: 9999;
+            }
+            .docit-nav-link {
+              color: var(--haze, rgba(255,255,255,0.7)); text-decoration: none;
+              padding: 4px 12px; border-radius: 6px;
+              transition: all 150ms;
+              font-family: inherit;
+              font-size: inherit;
+            }
+            .docit-nav-link:hover {
+              color: var(--text, #ffffff); background: var(--bg-option-hover, rgba(255,255,255,0.15));
+            }
+            .docit-nav-link.active {
+              color: var(--ember, #ffffff); background: var(--bg-option-hover, rgba(255,255,255,0.15)); font-weight: 600;
+            }
+          </style>
+          <nav class="docit-nav">
             <span style="font-weight: 600; margin-right: auto;">#{title}</span>
-            #{nav_link("Swagger", nav_paths[:swagger], active: swagger_active)}
-            #{nav_link("Scalar", nav_paths[:scalar], active: scalar_active)}
+            <a href="#{ERB::Util.html_escape(nav_paths[:swagger])}" class="docit-nav-link #{"active" if swagger_active}">Swagger</a>
+            <a href="#{ERB::Util.html_escape(nav_paths[:scalar])}" class="docit-nav-link #{"active" if scalar_active}">Scalar</a>
+            <a href="#{ERB::Util.html_escape(nav_paths[:system])}" class="docit-nav-link #{"active" if system_active}">System</a>
           </nav>
         HTML
       end
 
-      def nav_link(label, path, active:)
-        escaped_path = ERB::Util.html_escape(path)
-        style = if active
-                  "color: #fff; text-decoration: none; padding: 4px 12px; border-radius: 4px; background: rgba(255,255,255,0.15); font-weight: 500;"
-                else
-                  "color: rgba(255,255,255,0.7); text-decoration: none; padding: 4px 12px; border-radius: 4px;"
-                end
+      def spec_url_json
+        json_escape(JSON.generate(spec_url))
+      end
 
-        %(<a href="#{escaped_path}" style="#{style}">#{label}</a>)
+      def system_url_json
+        json_escape(JSON.generate(system_url))
       end
 
-      def spec_url_json
-        JSON.generate(spec_url)
+      def json_escape(json_string)
+        json_string.to_s.gsub(/[&<>'\u2028\u2029]/, {
+                                "&" => '\u0026',
+                                "<" => '\u003c',
+                                ">" => '\u003e',
+                                "'" => '\u0027',
+                                "\u2028" => '\u2028',
+                                "\u2029" => '\u2029'
+                              })
       end
     end
   end

data/lib/docit/ui/system_renderer.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Docit
+  module UI
+    class SystemRenderer < BaseRenderer
+      def render
+        <<~HTML
+          <!DOCTYPE html>
+          <html lang="en">
+          <head>
+            <meta charset="UTF-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1.0">
+            <title>#{title} – System Architecture</title>
+            <script>
+              /* Apply the saved theme before first paint to avoid a flash.
+                 Default is light; only switch to dark when explicitly chosen. */
+              (function() {
+                try {
+                  var saved = localStorage.getItem("docit-theme");
+                  if (saved === "dark") document.documentElement.setAttribute("data-theme", "dark");
+                } catch (e) {}
+              })();
+            </script>
+            <style>#{SystemStyles.css}</style>
+          </head>
+          <body>
+            #{nav_bar(active: :system)}
+            <div class="system-shell">
+              <header class="system-toolbar">
+                <div class="toolbar-group toolbar-brand">
+                  <div class="brand-mark" aria-hidden="true">
+                    <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round">
+                      <rect x="2" y="2" width="5" height="5" rx="1.2"/><rect x="9" y="2" width="5" height="5" rx="1.2"/>
+                      <rect x="2" y="9" width="5" height="5" rx="1.2"/><rect x="9" y="9" width="5" height="5" rx="1.2"/>
+                      <path d="M7 4.5h2M4.5 7v2M11.5 7v2"/>
+                    </svg>
+                  </div>
+                  <div class="toolbar-title">
+                    <strong>System Architecture</strong>
+                    <span>Interactive diagram · drag, zoom, explore</span>
+                  </div>
+                </div>
+                <div class="toolbar-group toolbar-filters" id="diagram-filters">
+                  <input id="search" class="control" type="search" placeholder="Search nodes…" autocomplete="off">
+                  <select id="diagram-section-filter" class="control"><option value="">All sections</option></select>
+                </div>
+                <div class="toolbar-group toolbar-filters" id="docs-filters" style="display: none;">
+                  <select id="section-filter" class="control"><option value="">All sections</option></select>
+                </div>
+                <div class="toolbar-group toolbar-view-mode" style="margin-left: 6px; border-left: 1px solid var(--border); padding-left: 10px; gap: 4px;">
+                  <button id="view-diagram" class="system-btn active" type="button">Diagram</button>
+                  <button id="view-list" class="system-btn" type="button">Docs</button>
+                </div>
+                <div class="toolbar-group toolbar-zoom">
+                  <button id="zoom-out" class="system-btn icon-btn" type="button" title="Zoom out" aria-label="Zoom out">
+                    <svg width="14" height="14" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><path d="M3 8h10"/></svg>
+                  </button>
+                  <span id="zoom-level" class="zoom-label">100%</span>
+                  <button id="zoom-in" class="system-btn icon-btn" type="button" title="Zoom in" aria-label="Zoom in">
+                    <svg width="14" height="14" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><path d="M8 3v10M3 8h10"/></svg>
+                  </button>
+                  <button id="zoom-fit" class="system-btn" type="button">Fit</button>
+                </div>
+                <div class="toolbar-group toolbar-actions">
+                  <button id="theme-toggle" class="system-btn icon-btn" type="button" title="Toggle theme" aria-label="Toggle light or dark theme"></button>
+                  <button id="export-png" class="system-btn" type="button">
+                    <span class="btn-icon" aria-hidden="true">
+                      <svg width="14" height="14" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"><path d="M8 2v8M5 7.5l3 3 3-3M3 13h10"/></svg>
+                    </span> Export PNG
+                  </button>
+                </div>
+                <div class="toolbar-group toolbar-info">
+                  <span id="stats" class="stat-pill"></span>
+                </div>
+              </header>
+
+              <div class="system-body">
+                <main class="canvas-wrap" id="canvas-wrap">
+                  <div id="canvas" class="canvas"></div>
+                  <div id="legend" class="legend collapsed">
+                    <button id="legend-toggle" class="legend-toggle" type="button">Legend ▸</button>
+                    <div id="legend-content" class="legend-content"></div>
+                  </div>
+                </main>
+                <main class="stripe-docs-wrap" id="stripe-docs-wrap" style="display: none;">
+                  <nav class="stripe-sidebar" id="stripe-sidebar"></nav>
+                  <div class="stripe-content" id="stripe-content"></div>
+                  <aside class="stripe-detail" id="stripe-detail">
+                    <button class="stripe-detail-close" id="stripe-detail-close" type="button" aria-label="Close panel">
+                      <svg width="15" height="15" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"><path d="M4 4l8 8M12 4l-8 8"/></svg>
+                    </button>
+                    <div class="stripe-detail-body" id="stripe-detail-body">
+                      <div class="stripe-detail-empty">
+                        <div class="stripe-detail-empty-icon" aria-hidden="true">
+                          <svg width="26" height="26" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 1.5h6L13 5v9.5H3z"/><path d="M9 1.5V5h4"/><path d="M5.5 8.5h5M5.5 11h3"/></svg>
+                        </div>
+                        <p>Select an endpoint to see how to call it.</p>
+                      </div>
+                    </div>
+                  </aside>
+                </main>
+                <aside id="panel" class="panel"></aside>
+              </div>
+            </div>
+            <div id="toast" class="toast" role="status"></div>
+            <script>#{SystemScript.javascript(graph_url: system_url)}</script>
+          </body>
+          </html>
+        HTML
+      end
+    end
+  end
+end