docs-kit 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: feed239eb09deeafd1a9dc6e92e91d192c14f927fa562105139f4b16473d1a60
-  data.tar.gz: 6149bf7b9509fb611ce86e9c183a38c027ce77addee69669be41a0ce85fb292d
+  metadata.gz: 6340fb386df08272f63e525ca81d43baaa1f440a82287e4a34e9a392b220a530
+  data.tar.gz: 3740655d5194976ea25a3ed3cdd6a633bb593c03c288a1c3a069d16d7c522cfe
 SHA512:
-  metadata.gz: 5af123f6815e81ccad67dcb7737836c0a2727fb60e963bfc16d6ff0a6540325ca1a67fa2aaaea2ff824ba3b36f2210d8fb4aaab43f097195ec7f020cbfc8c54e
-  data.tar.gz: 32e24110ca11cfba1c795d60ea93d6ecb2f1e42af912274ebc816718cd235d93e217bb1ac2a6082b08039eaefe162c6b8287f4ed328c685ab3c669c840e2e359
+  metadata.gz: 01e79925a8f67168a27e898fb13f6a9a5658b331b8a5b1ba854c9481c1afc5256f7ec89fb80a6e762f9ec0fd399425c38be82a1943a8fc9517e5cd0803e32fa4
+  data.tar.gz: a9a74e687605433c9a23069d6760a5a14093e898e0f64b133ede84f951f9f4deead0e98ad7735ca5a87e9f79ba86c9a340993004f1ece46731bda6016e6b9bab

data/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 ## [Unreleased]
 
+## [1.4.0]
+
+### Upgrading from 1.3
+
+Nothing to change for a site whose initializer configures docs-kit in a
+`to_prepare` block, as the generated one does. Three things now fail loudly
+instead of later or never: a broken `brand_logo` raises at boot, in
+development too; mutating a registry DSL or `DocsUI::Page` macro value in place
+raises `FrozenError`; so does mutating one of docs-kit's constants.
+
+### Fixed
+
+- **A cold archived version is built once, however many requests ask.**
+  `DocsKit::Snapshot.for` cached snapshots in an unguarded class ivar, so
+  threads that missed a version together each read and parsed its
+  `manifest.json` and raced to store it. The cache is now per Ractor and its
+  check-then-set runs under a lock; `Configuration#openapi_document`'s
+  mtime-checked memo likewise. (#91)
+- **No per-render constant lookups once the app has booted.** The engine now
+  calls `DocsKit.finalize!` once the host has configured the kit, with no app
+  code: the Rouge code themes and every registered page's view class are
+  resolved once into frozen maps instead of `Object.const_get` /
+  `safe_constantize` on every render, and the brand logo, SEO, landing and
+  optional-mcp memos are filled at boot rather than by whichever request comes
+  first. `DocsKit.configure` re-opens it, and a theme assigned directly
+  afterwards still wins. Outside Rails, call `DocsKit.finalize!` yourself. (#91)
+
+### Changed
+
+- **Finalized after boot in every environment, and after every reload.** The
+  engine finalizes in `after_initialize` in development too. With code
+  reloading on, it finalizes again after each reload, once the host's
+  `to_prepare` configure has re-run and re-opened the configuration, so the
+  resolved page views are the reloaded classes. The host's callables (`brand`,
+  `nav`, `version_badge`, `importmap`, ...) are kept as given, never frozen:
+  they may close over app state, so `DocsKit.configuration` stays
+  main-Ractor-only and finalizing never fails on one. (#91)
+- **Boot-time values are frozen.** The registry DSL (`page`, `path_prefix`,
+  `view_namespace`, `group_by_attribute`) and `DocsUI::Page`'s `title`,
+  `eyebrow`, `description` and `on_page` macros deep-freeze what they are
+  given (Ractor-shareable), as do the gem's own constants, and
+  `DocsKit.configuration` is built at load rather than on first read. Code
+  that mutated one of those values in place after declaring it now raises
+  `FrozenError`. (#91)
+- **A broken `brand_logo` fails at boot.** `DocsKit.finalize!` builds the logo,
+  so a missing file or non-SVG markup raises when the app boots, in every
+  environment, instead of on the first render. (#91)
+- docs-kit is held to [conformance-kit](https://github.com/zoolutions/conformance-kit)
+  0.4 in CI: the rubocop-thread_safety cops, thread and fiber contention specs,
+  a Ruby 4.0 Ractor canary (search index, llms.txt, the sidebar tree) and
+  `conformance-audit --strict`, whose allowlist names Rails' and Thor's class
+  state on the engine, controllers and generators by `ancestor:` rule. (#91)
+
 ## [1.3.0] — 2026-10-13
 
 ### Fixed

data/README.md

@@ -363,6 +363,33 @@ c.nav = lambda do
 end
 ```
 
+### After boot: finalized, threads and Ractors
+
+The engine calls `DocsKit.finalize!` once the app has booted (`after_initialize`,
+after your `to_prepare` configure) in every environment, and in development again
+after every code reload. It resolves the code themes and every registered page's
+view class once, into frozen maps, and builds the brand logo, SEO, landing and
+optional-mcp memos up front, so no request races another to fill a memo, or
+looks up a theme or a resolved page view. A page whose view class didn't exist
+at boot is still looked up when it is read, so it turns up once written. That
+is also why a broken `brand_logo` fails at boot.
+
+- `DocsKit.configure` re-opens a finalized configuration, so re-running it (a
+  development reload, a spec) takes effect.
+- Outside Rails (a script or Rack app that renders the chrome), call
+  `DocsKit.finalize!` yourself once the configuration is complete.
+- Your callables (`brand`, `title_suffix`, `nav`, `version_badge`, `importmap`)
+  are kept exactly as given: they may close over app state (`Current`, a
+  tenant), so they are never frozen or copied, and finalizing never fails on
+  one. That makes `DocsKit.configuration` main-Ractor-only. Code that runs in a
+  non-main Ractor builds its own `DocsKit::Configuration` from plain values and
+  passes it in (`DocsKit::LlmsText.index(config, ...)`,
+  `DocsKit::Snapshot.for(version, config:)`).
+- What the registry DSL (`page`, `path_prefix`, `view_namespace`) and
+  `DocsUI::Page`'s macros (`title`, `eyebrow`, `description`, `on_page`) are
+  given is deep-frozen when declared, as are docs-kit's own constants: mutating
+  one in place raises `FrozenError`.
+
 ## Render
 
 ```ruby

data/app/components/docs_ui/callout.rb

@@ -7,9 +7,9 @@ module DocsUI
   #   render DocsUI::Callout.new(:warning) { "Restart the server after…" }
   class Callout < Phlex::HTML
     LEVELS = {
-      note: { klass: "alert-info", icon: "info" },
-      tip: { klass: "alert-success", icon: "lightbulb" },
-      warning: { klass: "alert-warning", icon: "triangle-alert" }
+      note: { klass: "alert-info", icon: "info" }.freeze,
+      tip: { klass: "alert-success", icon: "lightbulb" }.freeze,
+      warning: { klass: "alert-warning", icon: "triangle-alert" }.freeze
     }.freeze
 
     def initialize(level = :note, title: nil)

data/app/components/docs_ui/code.rb

@@ -24,7 +24,9 @@ module DocsUI
   class Code < Phlex::HTML
     include Phlex::Rails::Helpers::ContentSecurityPolicyNonce
 
-    FORMATTER = Rouge::Formatters::HTML.new
+    # Ractor-shareable (deep-frozen): Rouge's HTML formatter keeps no per-call
+    # state, so one instance serves every render (and every Ractor).
+    FORMATTER = DocsKit::Shareable.make(Rouge::Formatters::HTML.new)
 
     def initialize(source, lexer: nil, filename: nil)
       @source = source.to_s.strip

data/app/components/docs_ui/page.rb

@@ -35,15 +35,19 @@ module DocsUI
     # friction-free path that never trips the parens-with-blocks gotcha.
     include DocsUI::PageHelpers
 
+    # The page macros run in a page class's body, at load (boot, on the main
+    # Ractor), and make each value shareable on write: request threads only
+    # read them afterwards, and a non-main Ractor can too.
+    # rubocop:disable-next ThreadSafety/ClassInstanceVariable -- written once in the class body at load; values made shareable
     class << self
       def title(value = nil)
-        @title = value if value
+        @title = DocsKit::Shareable.make(value) if value
         @title
       end
 
       # Inherited: a subclass that sets no eyebrow shows its parent page's.
       def eyebrow(value = nil)
-        @eyebrow = value if value
+        @eyebrow = DocsKit::Shareable.make(value) if value
         @eyebrow || (superclass.eyebrow if parent_page?)
       end
 
@@ -53,7 +57,7 @@ module DocsUI
       # description, no lead) falls back to config.seo.description in MetaTags.
       # Inherited from a parent page when unset.
       def description(value = nil)
-        @description = value if value
+        @description = DocsKit::Shareable.make(value) if value
         @description || (superclass.description if parent_page?)
       end
 
@@ -62,7 +66,7 @@ module DocsUI
       # or :panel/:toggle/:sidebar to override per page. Inherited from a parent
       # page when unset.
       def on_page(value = :__unset__)
-        @on_page = value unless value == :__unset__
+        @on_page = DocsKit::Shareable.make(value) unless value == :__unset__
         return @on_page if defined?(@on_page)
 
         parent_page? ? superclass.on_page : DocsKit.configuration.on_page_default

data/lib/docs_kit/api_client.rb

@@ -31,22 +31,26 @@ module DocsKit
 
   # The four generic-HTTP clients every site starts from. Order is stable
   # (curl → javascript → ruby → python) and preserved when a site merges its own.
-  ApiClient::DEFAULTS = {
-    curl: ApiClient.new(
-      label: "cURL", lexer: :curl, filename: "request.sh",
-      template: ApiTemplates.method(:curl)
-    ),
-    javascript: ApiClient.new(
-      label: "JavaScript", lexer: :javascript, filename: "request.js",
-      template: ApiTemplates.method(:javascript)
-    ),
-    ruby: ApiClient.new(
-      label: "Ruby", lexer: :ruby, filename: "request.rb",
-      template: ApiTemplates.method(:ruby)
-    ),
-    python: ApiClient.new(
-      label: "Python", lexer: :python, filename: "request.py",
-      template: ApiTemplates.method(:python)
-    )
-  }.freeze
+  # Shareable (lambdas, not Method objects, which never are), so a non-main
+  # Ractor can read the defaults.
+  ApiClient::DEFAULTS = DocsKit::Shareable.make(
+    {
+      curl: ApiClient.new(
+        label: "cURL", lexer: :curl, filename: "request.sh",
+        template: ->(request) { ApiTemplates.curl(request) }
+      ),
+      javascript: ApiClient.new(
+        label: "JavaScript", lexer: :javascript, filename: "request.js",
+        template: ->(request) { ApiTemplates.javascript(request) }
+      ),
+      ruby: ApiClient.new(
+        label: "Ruby", lexer: :ruby, filename: "request.rb",
+        template: ->(request) { ApiTemplates.ruby(request) }
+      ),
+      python: ApiClient.new(
+        label: "Python", lexer: :python, filename: "request.py",
+        template: ->(request) { ApiTemplates.python(request) }
+      )
+    }
+  )
 end

data/lib/docs_kit/configuration.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "shareable"
 require_relative "seo_config"
 require_relative "landing_config"
 
@@ -276,7 +277,7 @@ module DocsKit
 
     # The sentinel "no explicit nav" lambda. #nav_groups compares against this
     # identity to decide whether to derive the sidebar from #nav_registries.
-    DEFAULT_NAV = -> { {} }
+    DEFAULT_NAV = DocsKit::Shareable.make(-> { {} })
 
     # The search-palette shortcuts before this was configurable — "/" and the
     # platform command chord — so a site that never sets #search_shortcuts keeps
@@ -347,6 +348,8 @@ module DocsKit
       @versions = []
       @repo_url = nil
       @snapshots_path = nil
+      @openapi_memo = nil
+      @finalized = nil
     end
 
     # The normalized App Home link (a DocsKit::TopbarLink), or nil when unset —
@@ -453,16 +456,60 @@ module DocsKit
     # spec in development is picked up without a server restart. Raises a
     # DocsKit::Error naming the knob when read while #openapi is unset — a missing
     # spec has nothing useful to degrade to.
+    #
+    # The memo lives on this configuration, so a replaced one takes its
+    # Document with it, and its mtime check-then-set runs under a per-Ractor
+    # lock (DocsKit::Store): threads that miss together load the spec once and
+    # read the same Document. A configuration is only ever read in the Ractor
+    # that built it, so that Ractor's lock is the one that matters.
     def openapi_document
       raise DocsKit::Error, "no OpenAPI spec configured — set c.openapi to a path or Hash" if @openapi.nil?
 
+      source = @openapi
       mtime = openapi_source_mtime
-      return @openapi_document if defined?(@openapi_document) && @openapi_document_mtime == mtime
+      DocsKit::Store.fetch(:docs_kit_openapi_lock) { Mutex.new }.synchronize do
+        memo = @openapi_memo
+        next memo.fetch(:document) if memo && memo.fetch(:source).equal?(source) && memo.fetch(:mtime) == mtime
+
+        DocsKit::OpenApi.load(source).tap do |document|
+          @openapi_memo = { source: source, mtime: mtime, document: document }
+        end
+      end
+    end
 
-      @openapi_document_mtime = mtime
-      @openapi_document = DocsKit::OpenApi.load(@openapi)
+    # Resolves, once at boot, what a render would otherwise look up per call:
+    # the Rouge theme classes and every registered page's view class (frozen,
+    # so a non-main Ractor can read them), and fills the lazy memos (brand logo,
+    # SEO, landing, the optional-mcp probe) so no request races to fill them.
+    # Called by DocsKit.finalize! (the engine's after_initialize, and after every
+    # code reload); DocsKit.configure re-opens it (#reopen!). The host's
+    # callables (brand, nav, version_badge, importmap, ...) are kept as they are:
+    # they can close over app state, so the configuration itself stays
+    # main-Ractor-only. A theme assigned directly afterwards still wins:
+    # the resolved class is only used while its source setting is unchanged.
+    def finalize!
+      brand_logo
+      seo
+      landing
+      mcp_gem_present?
+      each_registry { |registry| registry.finalize! if registry.respond_to?(:finalize!) }
+      @finalized = DocsKit::Shareable.make(
+        code_theme: @code_theme, code_theme_class: resolve_code_theme_class,
+        code_theme_dark: @code_theme_dark, code_theme_dark_class: resolve_code_theme_dark_class
+      )
+      self
+    end
+
+    # Drops what #finalize! resolved (and the registries' resolved view classes),
+    # so the next reads resolve lazily against the current settings.
+    def reopen!
+      @finalized = nil
+      each_registry { |registry| registry.reopen! if registry.respond_to?(:reopen!) }
+      self
     end
 
+    def finalized? = !@finalized.nil?
+
     # The effective client map for DocsUI::RequestExample: the four shipped
     # defaults with site overrides/extensions merged over them. Hash#merge keeps
     # a reused token in its original position and appends new tokens in
@@ -677,9 +724,7 @@ module DocsKit
     # name that doesn't resolve degrades to the default theme rather than raising
     # NameError on every DocsUI::Code render.
     def code_theme_class
-      return @code_theme if @code_theme.is_a?(Class)
-
-      resolve_theme(@code_theme) || Object.const_get(DEFAULT_CODE_THEME)
+      resolved(:code_theme_class, :code_theme, @code_theme) { resolve_code_theme_class }
     end
 
     # The dark Rouge theme class resolved from #code_theme_dark (String or
@@ -687,10 +732,7 @@ module DocsKit
     # dark code CSS only when this is non-nil, so an unresolvable name degrades to
     # nil (no dark restyle) rather than raising.
     def code_theme_dark_class
-      return if @code_theme_dark.nil?
-      return @code_theme_dark if @code_theme_dark.is_a?(Class)
-
-      resolve_theme(@code_theme_dark)
+      resolved(:code_theme_dark_class, :code_theme_dark, @code_theme_dark) { resolve_code_theme_dark_class }
     end
 
     # The dark themes the site actually ships: #dark_themes intersected with
@@ -703,6 +745,33 @@ module DocsKit
 
     private
 
+    def resolve_code_theme_class
+      return @code_theme if @code_theme.is_a?(Class)
+
+      resolve_theme(@code_theme) || Object.const_get(DEFAULT_CODE_THEME)
+    end
+
+    def resolve_code_theme_dark_class
+      return if @code_theme_dark.nil?
+      return @code_theme_dark if @code_theme_dark.is_a?(Class)
+
+      resolve_theme(@code_theme_dark)
+    end
+
+    # What #finalize! resolved for key, while the setting it came from is still
+    # the same object; otherwise the block resolves it now (never finalized,
+    # re-opened, or the setting was reassigned since).
+    def resolved(key, setting, current)
+      finalized = @finalized
+      return yield unless finalized && finalized.fetch(setting).equal?(current)
+
+      finalized.fetch(key)
+    end
+
+    def each_registry(&)
+      (@nav_registries || {}).each_value(&)
+    end
+
     # Resolve a Rouge theme constant from its String name, returning nil (not
     # raising) when the name doesn't resolve — a typo'd or unloaded theme must
     # not crash every code block on the page.

data/lib/docs_kit/engine.rb

@@ -15,7 +15,7 @@ module DocsKit
     config.eager_load_paths = []
     config.paths["app"].skip_eager_load!
 
-    JAVASCRIPT_PATH = root.join("app/javascript")
+    JAVASCRIPT_PATH = root.join("app/javascript").freeze
 
     initializer "docs_kit.controller_helper" do
       ActiveSupport.on_load(:action_controller_base) do
@@ -31,6 +31,19 @@ module DocsKit
       Mime::Type.register("text/markdown", :md) unless Mime::Type.lookup_by_extension(:md)
     end
 
+    # Resolve the configuration's per-render lookups once (DocsKit.finalize!)
+    # after the host has configured the kit: its to_prepare DocsKit.configure
+    # runs before after_initialize at boot. With code reloading on, every
+    # reload re-runs that configure (which re-opens the configuration) against
+    # the reloaded classes, so finalize again after it: a to_prepare added
+    # here, after boot, runs after every to_prepare the host registered.
+    initializer "docs_kit.finalize" do |app|
+      app.config.after_initialize do
+        DocsKit.finalize!
+        app.reloader.to_prepare { DocsKit.finalize! } if app.config.reloading_enabled?
+      end
+    end
+
     # Serve the bundled Stimulus controller (docs_nav) as an asset.
     initializer "docs_kit.assets" do |app|
       app.config.assets.paths << JAVASCRIPT_PATH.to_s if app.config.respond_to?(:assets)

data/lib/docs_kit/og_generator.rb

@@ -106,7 +106,9 @@ module DocsKit
 
       port = free_port
       app = Rails.application
-      server_thread = Thread.new do
+      # The docs_kit:og rake task's one-shot local server (a CLI, never a request
+      # path): one thread, killed in the ensure below.
+      server_thread = Thread.new do # rubocop:disable ThreadSafety/NewThread
         Rackup::Handler.get("webrick").run(app, Port: port, Host: "127.0.0.1", Logger: null_logger, AccessLog: [])
       rescue LoadError
         Rack::Handler.get("webrick").run(app, Port: port, Host: "127.0.0.1", Logger: null_logger, AccessLog: [])

data/lib/docs_kit/registry.rb

@@ -62,34 +62,44 @@ module DocsKit
     # given. Appends to the registry in declaration order (== sidebar order).
     #
     #   page "Getting started", group: "Guide", icon: "rocket", slug: "start", view: "Start"
+    #
+    # The DSL runs in the registry's class body, at load. Each value is made
+    # Ractor-shareable on write (the page list is replaced, never appended to
+    # in place), so a non-main Ractor can read a registry and no thread can
+    # mutate it afterwards.
     def page(title, group:, slug: nil, view: nil, icon: nil)
       raise Error, "cannot mix `page` and `entries` in one registry" if defined?(@entries) && @entries
 
-      (@pages ||= []) << {
+      entry = {
         title: title,
         group: group,
         slug: slug || title.parameterize,
         view: view || title.parameterize(separator: "_").camelize,
         icon: icon
-      }.freeze
+      }
+      @pages = DocsKit::Shareable.make([*(defined?(@pages) && @pages), entry])
     end
 
     # href = "#{path_prefix}/#{slug}". Defaults to "/docs".
     def path_prefix(value = nil)
-      @path_prefix = value if value
+      @path_prefix = DocsKit::Shareable.make(value) if value
       @path_prefix || "/docs"
     end
 
     # The namespace a page's view_class resolves under (v2 pages only), e.g.
     # "Views::Docs::Pages". Required to resolve views via the default Entry.
+    # Setting it drops the views #finalize! resolved under the old namespace.
     def view_namespace(value = nil)
-      @view_namespace = value if value
+      if value
+        @view_namespace = DocsKit::Shareable.make(value)
+        @view_classes = nil
+      end
       @view_namespace
     end
 
     # The attribute used by #grouped (default :group).
     def group_by_attribute(attr = nil)
-      @group_by_attribute = attr if attr
+      @group_by_attribute = DocsKit::Shareable.make(attr) if attr
       @group_by_attribute || :group
     end
 
@@ -98,12 +108,32 @@ module DocsKit
     # v2 pages are wrapped in the default Entry; hash entries in the site's class.
     def all
       if defined?(@pages) && @pages
-        @pages.map { |attrs| Entry.new(attrs, path_prefix, view_namespace) }
+        views = @view_classes || Entry::NO_VIEWS
+        @pages.map { |attrs| Entry.new(attrs, path_prefix, view_namespace, views) }
       else
         (entries || []).map { |entry| new(entry) }
       end
     end
 
+    # Resolves every `page`'s view class once (DocsKit.finalize!, at boot) into
+    # a frozen { view name => class } map the entries read instead of
+    # constantizing on every call. Only views that resolve are kept, so a page
+    # written later still turns up. An `entries` registry resolves its own views.
+    def finalize!
+      resolved = Array(defined?(@pages) && @pages).each_with_object({}) do |attrs, map|
+        view_class = Entry.resolve(view_namespace, attrs[:view])
+        map[attrs[:view]] = view_class if view_class
+      end
+      @view_classes = DocsKit::Shareable.make(resolved)
+      self
+    end
+
+    # Drops the resolved view classes: entries constantize again (DocsKit.configure).
+    def reopen!
+      @view_classes = nil
+      self
+    end
+
     # The instance whose slug matches, or nil.
     def from_slug(slug)
       all.find { |item| item.slug.to_s == slug.to_s }
@@ -129,15 +159,26 @@ module DocsKit
     # resolved under the registry's view_namespace (nil until the class exists,
     # preserving the no-dead-links behavior).
     class Entry
+      NO_VIEWS = {}.freeze
+
+      # The page class `view_name` names under `view_namespace`, or nil.
+      def self.resolve(view_namespace, view_name)
+        return unless view_namespace
+
+        "#{view_namespace}::#{view_name}".safe_constantize
+      end
+
       attr_reader :slug, :title, :group, :icon, :view_name, :href
 
-      def initialize(attrs, path_prefix, view_namespace)
+      # view_classes: the registry's finalized { view name => class } map.
+      def initialize(attrs, path_prefix, view_namespace, view_classes = NO_VIEWS)
         @slug = attrs[:slug]
         @title = attrs[:title]
         @group = attrs[:group]
         @icon = attrs[:icon]
         @view_name = attrs[:view]
         @view_namespace = view_namespace
+        @view_classes = view_classes
         @href = "#{path_prefix}/#{@slug}"
       end
 
@@ -145,7 +186,7 @@ module DocsKit
       def view_class
         return unless @view_namespace
 
-        "#{@view_namespace}::#{@view_name}".safe_constantize
+        @view_classes.fetch(@view_name) { self.class.resolve(@view_namespace, @view_name) }
       end
 
       # The renderable instance for this page (nil when unauthored) — the seam

data/lib/docs_kit/shareable.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module DocsKit
+  # Makes a boot-time value Ractor-shareable: Ractor.make_shareable (a deep
+  # freeze; a capture-free Proc becomes an isolated one) where the engine has
+  # Ractors, a plain #freeze where it has none (TruffleRuby, JRuby). For
+  # constants and DSL values written once at load, so a non-main Ractor can read
+  # them and no thread can mutate them afterwards.
+  module Shareable
+    def self.make(value)
+      defined?(::Ractor) && ::Ractor.respond_to?(:make_shareable) ? ::Ractor.make_shareable(value) : value.freeze
+    end
+  end
+end

data/lib/docs_kit/snapshot.rb

@@ -28,27 +28,41 @@ module DocsKit
       # invalidated when manifest.json's mtime changes — the same
       # reload-on-change posture as Configuration#openapi_document, so editing
       # a snapshot in development is picked up without a server restart.
+      #
+      # The cache is per Ractor (DocsKit::Store) and its check-then-set runs
+      # under that Ractor's lock, so threads that miss a cold key together
+      # build it once and all get the same instance.
       def for(version, config: DocsKit.configuration)
         version = DocVersion.from(version)
         root = root_for(version, config)
         mtime = manifest_mtime(root)
-        key = [version.id.to_s, root.to_s]
-
-        @cache ||= {}
-        cached = @cache[key]
-        return cached.fetch(:snapshot) if cached && cached.fetch(:mtime) == mtime
-
-        new(version: version, root: root).tap do |snapshot|
-          @cache[key] = { snapshot: snapshot, mtime: mtime }
-        end
+        memoize([version.id.to_s, root.to_s], mtime) { new(version: version, root: root) }
       end
 
       def reset_cache!
-        @cache = {}
+        cache = cache_store
+        cache.fetch(:lock).synchronize { cache.fetch(:entries).clear }
       end
 
       private
 
+      def cache_store
+        DocsKit::Store.fetch(:docs_kit_snapshots) { { lock: Mutex.new, entries: {} } }
+      end
+
+      # The cached snapshot for key while its manifest mtime is unchanged, else
+      # the block's fresh one (stored) — the whole check-then-set under the lock.
+      def memoize(key, mtime)
+        cache = cache_store
+        cache.fetch(:lock).synchronize do
+          entries = cache.fetch(:entries)
+          cached = entries[key]
+          next cached.fetch(:snapshot) if cached && cached.fetch(:mtime) == mtime
+
+          yield.tap { |snapshot| entries[key] = { snapshot: snapshot, mtime: mtime } }
+        end
+      end
+
       # <snapshots_path>/<id>, or nil when no snapshots path resolves (no
       # config, no Rails) — which reads back as an empty snapshot.
       def root_for(version, config)
@@ -70,10 +84,13 @@ module DocsKit
 
     attr_reader :version, :root
 
+    # Built whole here, never lazily: a cached Snapshot is shared by every
+    # server thread, so it carries no memo a reader could race to fill.
     def initialize(version:, root:)
       @version = version
       @root = root
       @manifest = read_manifest
+      @registries = build_registries
     end
 
     # Every snapshot page across the manifest's registries, in manifest order —
@@ -116,8 +133,10 @@ module DocsKit
     private
 
     # The manifest's registries as { heading:, entries: [Snapshot::Entry] }.
-    def registries
-      @registries ||= Array(@manifest && @manifest["registries"]).map do |registry|
+    attr_reader :registries
+
+    def build_registries
+      Array(@manifest && @manifest["registries"]).map do |registry|
         prefix = registry["path_prefix"] || "/docs"
         {
           heading: registry["heading"],

data/lib/docs_kit/store.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module DocsKit
+  # Per-Ractor lazy storage for docs-kit's caches: `Store.fetch(:docs_kit_x) { {} }`.
+  # A copy of conformance-kit's ConformanceKit::Store (MIT, same author): the kit
+  # is a development dependency only, so the gem carries its own.
+  #
+  # On Ruby 3.4+ this is `Ractor.store_if_absent`, atomic and per-Ractor. Below
+  # 3.4 (and on engines without Ractor) the main Ractor uses one Hash guarded by
+  # a Mutex, created at load (never lazily, so there is no check-then-set race);
+  # it is allowlisted main-only in .conformance.yml. A non-main Ractor on 3.3
+  # cannot read it, so it keeps its own values in Ractor-local storage instead.
+  # That path has no lock (none is shareable): threads of one Ractor that miss
+  # together may each build a value, but only the first one stored is kept and
+  # returned to all of them.
+  module Store
+    # rubocop:disable ThreadSafety/MutableClassInstanceVariable -- main-only fallback, guarded by @fallback_lock
+    @fallback_lock = Mutex.new
+    @fallback_values = {}
+    # rubocop:enable ThreadSafety/MutableClassInstanceVariable
+
+    class << self
+      def fetch(key, &init)
+        raise ArgumentError, "DocsKit::Store.fetch(#{key.inspect}) needs an initializer block" unless init
+        return ::Ractor.store_if_absent(key, &init) if native?
+        return ractor_local(key, &init) unless main_ractor?
+
+        @fallback_lock.synchronize do
+          @fallback_values.fetch(key) { @fallback_values[key] = yield }
+        end
+      end
+
+      private
+
+      def main_ractor? = !defined?(::Ractor) || ::Ractor.current == ::Ractor.main
+
+      # Boxed, so a nil or false value is cached rather than rebuilt on every fetch.
+      # The value is built before the check-then-store, which runs no Ruby code
+      # between the read and the write, so a thread that built a value after
+      # another stored one gets the stored one.
+      def ractor_local(key)
+        slot = :"docs_kit_store/#{key}"
+        stored = ::Ractor.current[slot]
+        return stored.first if stored
+
+        built = [yield]
+        (::Ractor.current[slot] ||= built).first
+      end
+
+      public
+
+      def native?
+        defined?(::Ractor) ? ::Ractor.respond_to?(:store_if_absent) : false
+      end
+    end
+  end
+end

data/lib/docs_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DocsKit
-  VERSION = "1.3.0"
+  VERSION = "1.4.0"
 end

data/lib/docs_kit.rb

@@ -5,6 +5,7 @@ require "rouge"
 require "zeitwerk"
 
 require_relative "docs_kit/version"
+require_relative "docs_kit/shareable"
 require_relative "docs_kit/configuration"
 
 # DocsKit — a reusable docs-site component library: the shared Phlex chrome
@@ -17,19 +18,36 @@ require_relative "docs_kit/configuration"
 module DocsKit
   class Error < StandardError; end
 
+  # Built at load, never lazily: no first-request race to build two.
+  @configuration = Configuration.new
+
   class << self
-    # The current configuration, memoized. Reset with DocsKit.reset_configuration!.
-    def configuration
-      @configuration ||= Configuration.new
-    end
+    # The current configuration. Reset with DocsKit.reset_configuration!.
+    # Assigned at load and by reset_configuration! (boot, specs) on the main
+    # Ractor; request threads only read it. Main-only (.conformance.yml): it
+    # holds the host's per-request callables (brand, nav, version_badge, ...).
+    attr_reader :configuration
 
+    # Re-opens a finalized configuration first (a development reload re-runs
+    # the host's to_prepare configure), so every setting takes effect.
     def configure
+      configuration.reopen!
       yield(configuration)
       configuration.validate!
     end
 
+    # Resolves the configuration's per-render lookups once (see
+    # Configuration#finalize!). In a Rails app the engine calls it after the
+    # host has configured the kit, and again after every code reload; outside
+    # Rails, call it once the configuration is complete.
+    def finalize!
+      configuration.finalize!
+    end
+
+    # A fresh default configuration (specs; a host that re-boots its config).
+    # Runs at boot or between examples, never on a request.
     def reset_configuration!
-      @configuration = Configuration.new
+      @configuration = Configuration.new # rubocop:disable ThreadSafety/ClassInstanceVariable
     end
   end
 end
@@ -54,6 +72,8 @@ loader.push_dir(File.expand_path("docs_kit", __dir__), namespace: DocsKit)
 loader.push_dir(File.expand_path("../app/components/docs_ui", __dir__), namespace: DocsUI)
 loader.ignore(File.expand_path("docs_kit/version.rb", __dir__))
 loader.ignore(File.expand_path("docs_kit/configuration.rb", __dir__))
+# Required eagerly above (configuration.rb's constants use it at load).
+loader.ignore(File.expand_path("docs_kit/shareable.rb", __dir__))
 # Required eagerly by configuration.rb (a plain-Ruby value object, no Rails), so
 # ignore it here too or zeitwerk double-manages the constant.
 loader.ignore(File.expand_path("docs_kit/seo_config.rb", __dir__))

data/lib/generators/docs_kit/install/migration.rb

@@ -14,14 +14,19 @@ module DocsKit
     # and hands back strings for whatever needs a human. A `nil` return means
     # "nothing to warn about".
     class Migration
-      attr_reader :to, :description
+      attr_reader :description
 
+      # Keeps `to` as a frozen String, so a migration list can be made
+      # Ractor-shareable without freezing Gem::Version's process-wide cached
+      # instances; #to hands back the Gem::Version.
       def initialize(to:, description:, &block)
-        @to = Gem::Version.new(to.to_s)
+        @to = -to.to_s
         @description = description
         @block = block
       end
 
+      def to = Gem::Version.new(@to)
+
       # Run the transform against the site. Returns the (possibly empty) list of
       # manual-cleanup warnings — never nil, so callers can flat-map safely.
       def call(root, generator)

data/lib/generators/docs_kit/install/migration_registry.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../../../docs_kit/shareable"
 require_relative "migration"
 require_relative "migrations/v1_2_0"
 require_relative "../../../docs_kit/version"
@@ -24,21 +25,25 @@ module DocsKit
     # its transform in migrations/vX_Y_Z.rb.
     class MigrationRegistry
       def initialize(migrations = [])
-        @migrations = migrations.sort_by(&:to)
+        @migrations = migrations.sort_by(&:to).freeze
       end
 
-      # The registry the install generator runs during `--sync`.
-      def self.default
-        @default ||= new(MIGRATIONS)
-      end
+      # The registry the install generator runs during `--sync` (DEFAULT, below).
+      def self.default = DEFAULT
 
       # Ordered `Migration.new(to: "1.x.0", description: "...") { ... }` entries, one
       # per release that changes config knobs, routes, templates, or toolchain.
-      MIGRATIONS = [
-        Migration.new(to: "1.2.0", description: Migrations::V1_2_0::DESCRIPTION) do |root, _generator|
-          Migrations::V1_2_0.call(root)
-        end
-      ].freeze
+      # Shareable: each block is capture-free (its self is this class).
+      MIGRATIONS = DocsKit::Shareable.make(
+        [
+          Migration.new(to: "1.2.0", description: Migrations::V1_2_0::DESCRIPTION) do |root, _generator|
+            Migrations::V1_2_0.call(root)
+          end
+        ]
+      )
+
+      # Built at load from MIGRATIONS, never lazily (no first-call race).
+      DEFAULT = DocsKit::Shareable.make(new(MIGRATIONS))
 
       # The migrations a site last synced at `from_version` still needs, ascending
       # by version — those in `(from_version, upto]`. `upto` defaults to the

data/lib/generators/docs_kit/install/migrations/v1_2_0.rb

@@ -12,12 +12,14 @@ module DocsKit
       # handed back as a warning, and a newer value is left alone.
       module V1_2_0 # rubocop:disable Naming/ClassAndModuleCamelCase -- named after the release
         DESCRIPTION = "docs-kit 1.2: Ruby >= 3.3, Bun 1.4.2, Tailwind 4.3 / daisyUI 5.7 floors, Node 24 deploy"
-        MIN_RUBY = Gem::Version.new("3.3")
+        # A String: Gem::Version.new hands out process-wide cached instances,
+        # which a constant must not freeze. Compared via Gem::Version below.
+        MIN_RUBY = "3.3"
         BUN = { from: "1.3.2", to: "1.4.2" }.freeze
         PACKAGE_FLOORS = {
-          "tailwindcss" => { from: "^4.1.18", to: "^4.3.3" },
-          "@tailwindcss/cli" => { from: "^4.1.18", to: "^4.3.3" },
-          "daisyui" => { from: "^5.6.0", to: "^5.7.47" }
+          "tailwindcss" => { from: "^4.1.18", to: "^4.3.3" }.freeze,
+          "@tailwindcss/cli" => { from: "^4.1.18", to: "^4.3.3" }.freeze,
+          "daisyui" => { from: "^5.6.0", to: "^5.7.47" }.freeze
         }.freeze
         DEPLOY_CALL = %r{zoolutions/docs-kit/\.github/workflows/deploy\.yml@(\S+)}
 
@@ -112,7 +114,7 @@ module DocsKit
 
         def below_min_ruby?(value)
           version = version_of(value)
-          version ? version < MIN_RUBY : false
+          version ? version < Gem::Version.new(MIN_RUBY) : false
         end
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docs-kit
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -235,9 +235,11 @@ files:
 - lib/docs_kit/search_index.rb
 - lib/docs_kit/search_index/snippet.rb
 - lib/docs_kit/seo_config.rb
+- lib/docs_kit/shareable.rb
 - lib/docs_kit/shortcut.rb
 - lib/docs_kit/snapshot.rb
 - lib/docs_kit/snapshot/entry.rb
+- lib/docs_kit/store.rb
 - lib/docs_kit/templates/new_site.rb
 - lib/docs_kit/topbar_link.rb
 - lib/docs_kit/version.rb