docs-kit 0.1.0

data/lib/rubocop/cop/docs_kit/render_component_preferred.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module DocsKit
+      # Enforces the kit helper form over `render <Kit>::<Class>.new(...)`.
+      #
+      # The docs-kit `DocsUI` module and the `DaisyUI` gem are both extended with
+      # `Phlex::Kit`, which defines a singleton method per component class. That
+      # makes `DocsUI::Code(...)` equivalent to `render DocsUI::Code.new(...)` but
+      # terser and consistent. Adapted from cosmos' Cosmos/RenderComponentPreferred.
+      #
+      # @example
+      #   # bad
+      #   render DocsUI::Code.new(source, filename: "a.rb")
+      #   render DocsUI::Section.new("Title") { ... }
+      #   render DaisyUI::Button.new(:primary) { "Save" }
+      #
+      #   # good
+      #   DocsUI::Code(source, filename: "a.rb")
+      #   DocsUI::Section("Title") { ... }
+      #   DaisyUI::Button(:primary) { "Save" }
+      #
+      # The cop keeps the namespace prefix (`DocsUI::Code(...)` rather than
+      # `Code(...)`) because the unqualified helper may resolve to a different kit
+      # depending on inclusion order. Keeping the prefix makes the rewrite
+      # mechanically safe in every rendering context.
+      #
+      # Contexts the cop does NOT fire in:
+      # - `render <class-method-call>` like `render UI::Modal.clear` — not a .new.
+      # - elements of a `turbo_stream: [...]` array — class-method calls that
+      #   return Turbo Stream payloads, not `.new` component instances.
+      class RenderComponentPreferred < Base
+        extend AutoCorrector
+
+        MSG = "Use `%<suggestion>s` instead of `%<original>s`."
+
+        # Kit modules recognised by the cop.
+        KIT_MODULES = %w[
+          DocsUI
+          DaisyUI
+        ].to_set.freeze
+
+        # `render Kit::Class.new(args)` — plain send.
+        def_node_matcher :render_new_send, <<~PATTERN
+          (send nil? :render $(send $const :new ...))
+        PATTERN
+
+        # `render Kit::Class.new(args) { ... }` — brace block glued onto .new.
+        def_node_matcher :render_new_block, <<~PATTERN
+          (send nil? :render (block $(send $const :new ...) _ _))
+        PATTERN
+
+        def on_send(node)
+          return if inside_array_literal?(node)
+          return unless node.arguments.length == 1
+
+          match = render_new_send(node) || render_new_block(node)
+          return unless match
+
+          new_call_node, const_node = match
+
+          namespace = kit_namespace(const_node)
+          return unless namespace
+
+          helper_headline = helper_headline(new_call_node, const_node)
+          original_headline = "render #{new_call_node.source}"
+
+          add_offense(node, message: format(MSG, suggestion: helper_headline, original: original_headline)) do |corrector|
+            # Replace ONLY `render <Kit>::<Class>.new(args)` with the helper call,
+            # leaving any trailing block (`do...end` or `{ ... }`) untouched. That
+            # keeps the rewrite range off the block body, so a nested kit render
+            # inside the block corrects independently instead of clobbering.
+            range = node.source_range.begin.join(new_call_node.source_range.end)
+            corrector.replace(range, helper_headline)
+          end
+        end
+
+        private
+
+        def inside_array_literal?(node)
+          node.parent&.array_type?
+        end
+
+        def kit_namespace(const_node)
+          segments = const_segments(const_node)
+          return nil if segments.nil? || segments.length < 2
+
+          KIT_MODULES.include?(segments.first) ? segments.first : nil
+        end
+
+        def const_segments(node)
+          parts = []
+          cur = node
+          while cur&.const_type?
+            parts.unshift(cur.short_name.to_s)
+            cur = cur.children.first
+          end
+          parts
+        end
+
+        # `DocsUI::Code(args)` — the helper form the render becomes. This is both
+        # the offense-message suggestion and the exact replacement text (the block,
+        # if any, is preserved separately by keeping the rewrite range off it).
+        def helper_headline(new_call_node, const_node)
+          args_source = call_args_source(new_call_node)
+          prefix = const_node.source
+          args_source.empty? ? "#{prefix}()" : "#{prefix}(#{args_source})"
+        end
+
+        def call_args_source(new_call_node)
+          return "" if new_call_node.arguments.empty?
+
+          first = new_call_node.arguments.first
+          last = new_call_node.arguments.last
+          first_pos = first.source_range.begin_pos
+          last_pos = last.source_range.end_pos
+          new_call_node.source_range.source_buffer.source[first_pos...last_pos]
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,253 @@
+--- !ruby/object:Gem::Specification
+name: docs-kit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mikael Henriksson
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: daisyui
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: phlex-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rails_icons
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rouge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: commonmarker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.75'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.75'
+description: DocsKit is a reusable documentation-site component library for Phlex
+  + daisyUI. It extracts the shared shell, sidebar, code blocks, and page kit so multiple
+  docs sites look identical and are maintained in one place. Reactive demos (phlex-reactive)
+  and Postgres-SSE transport (pgbus) are optional, runtime-detected add-ons.
+email: mikael@zoolutions.llc
+executables:
+- docs-kit
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- app/components/docs_ui/brand_mark.rb
+- app/components/docs_ui/callout.rb
+- app/components/docs_ui/code.rb
+- app/components/docs_ui/endpoint.rb
+- app/components/docs_ui/error_table.rb
+- app/components/docs_ui/example.rb
+- app/components/docs_ui/field_table.rb
+- app/components/docs_ui/header.rb
+- app/components/docs_ui/icon.rb
+- app/components/docs_ui/json_response.rb
+- app/components/docs_ui/markdown.rb
+- app/components/docs_ui/markdown_action.rb
+- app/components/docs_ui/on_this_page.rb
+- app/components/docs_ui/open_api_operation.rb
+- app/components/docs_ui/page.rb
+- app/components/docs_ui/page_helpers.rb
+- app/components/docs_ui/prop_table.rb
+- app/components/docs_ui/prose.rb
+- app/components/docs_ui/request_example.rb
+- app/components/docs_ui/search_box.rb
+- app/components/docs_ui/search_results.rb
+- app/components/docs_ui/section.rb
+- app/components/docs_ui/shell.rb
+- app/components/docs_ui/sidebar.rb
+- app/components/docs_ui/table.rb
+- app/components/docs_ui/theme_switcher.rb
+- app/components/docs_ui/topbar_links.rb
+- app/controllers/docs_kit/llms_controller.rb
+- app/controllers/docs_kit/mcp_controller.rb
+- app/controllers/docs_kit/search_controller.rb
+- app/javascript/docs_kit/controllers/docs_nav_controller.js
+- config/importmap.rb
+- config/rubocop/docs_kit.yml
+- exe/docs-kit
+- lib/docs-kit.rb
+- lib/docs_kit.rb
+- lib/docs_kit/api_client.rb
+- lib/docs_kit/api_request.rb
+- lib/docs_kit/api_templates.rb
+- lib/docs_kit/configuration.rb
+- lib/docs_kit/controller.rb
+- lib/docs_kit/engine.rb
+- lib/docs_kit/llms_text.rb
+- lib/docs_kit/markdown_export.rb
+- lib/docs_kit/markdown_export/blocks.rb
+- lib/docs_kit/markdown_export/inline.rb
+- lib/docs_kit/markdown_export/table.rb
+- lib/docs_kit/mcp_server.rb
+- lib/docs_kit/mcp_tools.rb
+- lib/docs_kit/nav_item.rb
+- lib/docs_kit/open_api.rb
+- lib/docs_kit/open_api/document.rb
+- lib/docs_kit/open_api/operation.rb
+- lib/docs_kit/open_api/schema.rb
+- lib/docs_kit/registry.rb
+- lib/docs_kit/rubocop.rb
+- lib/docs_kit/search_hit.rb
+- lib/docs_kit/search_index.rb
+- lib/docs_kit/search_index/snippet.rb
+- lib/docs_kit/shortcut.rb
+- lib/docs_kit/templates/new_site.rb
+- lib/docs_kit/topbar_link.rb
+- lib/docs_kit/version.rb
+- lib/generators/docs_kit/install/USAGE
+- lib/generators/docs_kit/install/install_generator.rb
+- lib/generators/docs_kit/install/sync_report.rb
+- lib/generators/docs_kit/install/templates/agents_md.erb
+- lib/generators/docs_kit/install/templates/application.tailwind.css.erb
+- lib/generators/docs_kit/install/templates/build-css
+- lib/generators/docs_kit/install/templates/build_css.rake
+- lib/generators/docs_kit/install/templates/doc.rb.erb
+- lib/generators/docs_kit/install/templates/docs_controller.rb.erb
+- lib/generators/docs_kit/install/templates/docs_kit.rb.erb
+- lib/generators/docs_kit/install/templates/installation_page.rb.erb
+- lib/generators/docs_kit/install/templates/landing.rb.erb
+- lib/generators/docs_kit/install/templates/landings_controller.rb.erb
+- lib/generators/docs_kit/install/templates/phlex.rb.erb
+- lib/generators/docs_kit/install/templates/rails_icons.rb.erb
+- lib/generators/docs_kit/install/templates/skill.md.erb
+- lib/generators/docs_kit/page/USAGE
+- lib/generators/docs_kit/page/page_generator.rb
+- lib/generators/docs_kit/page/templates/page.rb.erb
+- lib/rubocop/cop/docs_kit/escaped_interpolation_in_heredoc.rb
+- lib/rubocop/cop/docs_kit/render_component_preferred.rb
+homepage: https://github.com/mhenrixon/docs-kit
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/mhenrixon/docs-kit
+  changelog_uri: https://github.com/mhenrixon/docs-kit/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/mhenrixon/docs-kit/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.9
+specification_version: 4
+summary: Shared Phlex docs-site chrome (shell, sidebar, code, theme switcher) built
+  on daisyUI
+test_files: []