haveapi 0.31.2 → 0.32.0

data/spec/client_examples/presentation_spec.rb

@@ -0,0 +1,247 @@
+require 'spec_helper'
+require 'tmpdir'
+require_relative 'dynamic_fixture'
+
+RSpec.describe HaveAPI::ClientExample do
+  include DynamicExampleFixture
+
+  it 'retains all registered direct lanes while keeping authored Ruby and PHP assembly separators clean' do
+    expect(described_class.clients.length).to eq(15)
+    sample = { path_params: [7], request: { name: 'widget' }, response: { id: 7 }, status: true }
+    action = dynamic_action.merge(path: '/mount/v2/widgets/{widget_id}')
+    base = dynamic_context(resource_path: ['widget'], action_name: 'show', action:, sample:)
+    lanes = [[:init, base, nil], [:auth, base, :basic], [:auth, base, :token], [:auth, base, :oauth2],
+             [:example, base, nil], [:example, base.with(action: action.merge(auth: true)), nil],
+             [:example, base.with(sample: sample.merge(status: false)), nil]]
+    described_class.clients.each do |renderer|
+      %i[simple thorough].each do |detail|
+        lanes.each do |kind, context, provider|
+          result = renderer.render(kind, context: context.with(detail:), auth_method: provider, auth_description: token_description)
+          expect(result).to include(status: satisfy { |status| %i[code limitation].include?(status) })
+          next unless result[:status] == :code && %w[ruby php].include?(renderer.language)
+
+          source = result.fetch(:code)
+          expect(source).not_to match(/\A\n|\n\n\z|\n[ \t]+\n|\n\n\n/)
+        end
+      end
+    end
+  end
+
+  it 'preserves custom renderer whitespace and literal content exactly' do
+    source = "\ncustom literal\n\n\n  content\n\n"
+    renderer = Class.new(described_class) { define_method(:init) { source } }
+    expect(renderer.render(:init, context: dynamic_context).fetch(:code)).to eq(source)
+  end
+
+  it 'keeps built-in client IDs, order and language metadata together' do
+    expected = [
+      ['0', 'ruby', 'Ruby', nil],
+      %w[javascript-callback javascript JavaScript Callback],
+      %w[javascript-async javascript JavaScript Async],
+      %w[typescript-callback typescript TypeScript Callback],
+      %w[typescript-async typescript TypeScript Async],
+      %w[python-sync python Python Sync],
+      %w[python-async python Python Async],
+      ['go', 'go', 'Go', nil],
+      %w[rust-async rust Rust Async],
+      %w[rust-blocking rust Rust Blocking],
+      ['typescript-generated', 'typescript', 'TypeScript', 'API client'],
+      ['2', 'php', 'PHP', nil], ['3', 'cli', 'CLI', nil],
+      ['5', 'curl', 'curl', nil], ['6', 'http', 'HTTP', nil]
+    ]
+    actual = described_class.clients.map { |renderer| [renderer.id, renderer.language, renderer.language_label, renderer.variant] }
+    expect(actual).to eq(expected)
+  end
+
+  it 'defaults unspecified third-party metadata to its own ID and label without inheriting a built-in group' do
+    renderer = Class.new(HaveAPI::ClientExamples::PythonClient) do
+      def self.label
+        'Custom client'
+      end
+    end
+    stub_const('CustomDocumentationExample', renderer)
+
+    expect(renderer.language).to eq(renderer.id)
+    expect(renderer.language_label).to eq('Custom client')
+    expect(renderer.variant).to be_nil
+  end
+
+  it 'defaults undeclared custom renderers to both frozen detail levels' do
+    renderer = Class.new(described_class)
+    expect(renderer.detail_levels).to eq(%i[simple thorough])
+    expect(renderer.detail_levels).to be_frozen
+    expect { renderer.detail_levels << :other }.to raise_error(FrozenError)
+  end
+
+  it 'inherits the nearest detail declaration and freezes an independently owned override' do
+    parent = Class.new(described_class)
+    levels = [:simple]
+    parent.detail_levels(*levels)
+    levels << :thorough
+    child = Class.new(parent)
+    grandchild = Class.new(child)
+    expect(child.detail_levels).to equal(parent.detail_levels)
+    expect(grandchild.detail_levels).to eq([:simple])
+    child.detail_levels :simple, :thorough
+    expect(child.detail_levels).to be_frozen
+    expect(grandchild.detail_levels).to equal(child.detail_levels)
+    expect(parent.detail_levels).to eq([:simple])
+  end
+
+  it 'rejects unsupported, duplicate, reversed and non-symbol detail declarations without changing metadata' do
+    renderer = Class.new(described_class)
+    renderer.detail_levels :simple
+    [[:thorough], %i[thorough simple], %i[simple simple], %i[simple thorough thorough],
+     [:other], ['simple'], [nil], [[:simple]]].each do |values|
+      expect { renderer.detail_levels(*values) }.to raise_error(ArgumentError)
+      expect(renderer.detail_levels).to eq([:simple])
+    end
+  end
+
+  it 'declares one format for HTTP, inherited curl and CLI without changing registry IDs or other clients' do
+    single_level = [HaveAPI::ClientExamples::Http, HaveAPI::ClientExamples::Curl, HaveAPI::ClientExamples::RubyCli]
+    registry = described_class.clients
+    single_level.each do |renderer|
+      expect(renderer.detail_levels).to eq([:simple])
+      expect(renderer.detail_levels).to be_frozen
+    end
+    expect(HaveAPI::ClientExamples::Curl.detail_levels).to equal(HaveAPI::ClientExamples::Http.detail_levels)
+    (registry - single_level).each { |renderer| expect(renderer.detail_levels).to eq(%i[simple thorough]) }
+    expect(described_class.clients).to eq(registry)
+  end
+
+  it 'uses simple for legacy positional instances and reads thorough only from its context' do
+    renderer = described_class.new('api.test', 'https://api.test/', '1')
+    context = described_class::Context.new(version: '1', host: 'api.test', base_url: 'https://api.test/',
+                                           version_url: 'https://api.test/v1/', description: {})
+    expect(renderer.thorough?).to be(false)
+    expect(renderer.with_context(context).thorough?).to be(false)
+    expect(renderer.with_context(context.with(detail: :thorough)).thorough?).to be(true)
+  end
+
+  it 'keeps a custom Simple limitation and its distinct thorough result under the legacy declaration' do
+    renderer = Class.new(described_class) do
+      def init
+        thorough? ? 'custom recovery instructions' : { status: :limitation, reason: 'custom Simple limitation' }
+      end
+    end
+    context = described_class::Context.new(version: '1', host: 'api.test', base_url: 'https://api.test/',
+                                           version_url: 'https://api.test/v1/', description: {})
+    result = renderer.render(:init, context:)
+    expect(result).to include(status: :limitation)
+    expect(renderer.detail_levels_for(:init, context:, result:)).to equal(renderer.detail_levels)
+    expect(renderer.render(:init, context: context.with(detail: :thorough))).to include(code: 'custom recovery instructions')
+    renderer.detail_levels :simple
+    expect(renderer.detail_levels_for(:init, context:, result:)).to equal(renderer.detail_levels)
+    expect(context.detail).to eq(:simple)
+  end
+
+  it 'retains inherited legacy declarations for every wrapper without invoking the adapter' do
+    calls = []
+    adapter = Class.new do
+      define_method(:resolve) { |**| calls << :resolve }
+      define_method(:render) { |**| calls << :render }
+    end.new.freeze
+    limitation = { status: :limitation, reason: 'Simple format unavailable' }.freeze
+    [[HaveAPI::ClientExamples::GoClient, :go],
+     [HaveAPI::ClientExamples::RustAsyncClient, :rust],
+     [HaveAPI::ClientExamples::RustBlockingClient, :rust],
+     [HaveAPI::ClientExamples::TsGeneratedClient, :typescript]].each do |wrapper, language|
+      profile = described_class::Profile.new(language:, package_name: 'fixture-client', package_version: nil, adapter:)
+      context = described_class::Context.new(version: '1', host: 'api.test', base_url: 'https://api.test/',
+                                             version_url: 'https://api.test/v1/', description: {}, profile:)
+      child = Class.new(wrapper)
+      expect(child.detail_levels_for(:init, context:, result: limitation)).to equal(wrapper.detail_levels)
+      expect(child.detail_levels_for(:init, context:, result: limitation)).to eq(%i[simple thorough])
+      child.detail_levels :simple
+      expect(child.detail_levels_for(:init, context:, result: limitation)).to equal(child.detail_levels)
+      expect(child.detail_levels_for(:init, context:, result: limitation)).to be_frozen
+      expect(context.profile).to equal(profile)
+      expect(context.profile.adapter).to equal(adapter)
+    end
+    expect(calls).to be_empty
+  end
+
+  it 'keeps a pinned saved-profile adapter with only resolve/render through actual wrapper selection' do
+    calls = []
+    adapter = Class.new do
+      define_method(:resolve) { |**| calls << :resolve }
+      define_method(:render) do |kind:, context:, mode:, **|
+        calls << [kind, context.detail, mode]
+        if context.detail == :thorough
+          { status: :code, code: 'legacy recovery instructions' }.freeze
+        else
+          { status: :limitation, reason: 'legacy Simple limitation' }.freeze
+        end
+      end
+    end.new
+    profiles = described_class::Profiles.new
+    generator = Module.new
+    generator.const_set(:VERSION, '0.29.0')
+    documentation = Class.new
+    generator.const_set(:Documentation, documentation)
+    stub_const('HaveAPI::GoClient', generator)
+    allow(profiles).to receive(:require).with('haveapi/go_client/documentation').and_return(true)
+    allow(documentation).to receive(:new).and_return(adapter)
+    Dir.mktmpdir('haveapi-legacy-detail-') do |directory|
+      path = File.join(directory, 'description.json')
+      File.write(path, JSON.generate(resources: {}, authentication: {}, meta: { namespace: '_meta' }))
+      profiles.register(1, go: { import_path: 'example.test/client', description_path: path,
+                                 generator_version: '0.29.0' })
+      profiles.mount([1])
+      server = instance_double(HaveAPI::Server)
+      profiles.finalize(server)
+      profile = profiles.for_version(1).fetch(:go)
+      context = described_class::Context.new(version: '1', host: 'api.test', base_url: 'https://api.test/',
+                                             version_url: 'https://api.test/v1/', description: {}, profile:)
+      wrapper = HaveAPI::ClientExamples::GoClient
+      simple = wrapper.render(:init, context:)
+      levels = wrapper.detail_levels_for(:init, context:, result: simple)
+      expect(levels).to eq(%i[simple thorough])
+      expect(levels).to be_frozen
+      expect(calls).to eq([%i[init simple sync]])
+      panels = levels.map do |detail|
+        [detail, detail == :simple ? simple : wrapper.render(:init, context: context.with(detail:))]
+      end
+      expect(panels).to eq([
+                             [:simple, { status: :limitation, reason: 'legacy Simple limitation' }],
+                             [:thorough, { status: :code, code: 'legacy recovery instructions' }]
+                           ])
+      expect(calls).to eq([%i[init simple sync], %i[init thorough sync]])
+      expect(profile.adapter).to equal(adapter)
+      expect(profile).to be_frozen
+      expect(adapter).to be_frozen
+      expect(adapter).not_to respond_to(:detail_levels_for)
+      expect(context.detail).to eq(:simple)
+      expect(documentation).to have_received(:new).once
+    end
+  end
+
+  it 'delegates modern limitation queries exactly once and propagates exceptions and invalid levels' do
+    wrapper = HaveAPI::ClientExamples::GoClient
+    adapter = Object.new
+    def adapter.detail_levels_for(**); end
+    allow(adapter).to receive(:detail_levels_for).and_return([:simple])
+    context = Object.new.freeze
+    result = { status: :limitation, reason: 'current limitation' }.freeze
+    auth_description = { http_header: 'X-Token' }.freeze
+    levels = wrapper.adapter_detail_levels_for(adapter:, kind: :auth, context:, result:, mode: :sync,
+                                               auth_method: :token, auth_description:)
+    expect(levels).to eq([:simple])
+    expect(levels).to be_frozen
+    expect(adapter).to have_received(:detail_levels_for).once.with(
+      kind: :auth, context:, result:, mode: :sync, auth_method: :token, auth_description:
+    )
+    [nil, [], [:thorough], %i[thorough simple], %i[simple simple], ['simple']].each do |invalid|
+      allow(adapter).to receive(:detail_levels_for).and_return(invalid)
+      expect do
+        wrapper.adapter_detail_levels_for(adapter:, kind: :init, context:, result:, mode: :sync)
+      end.to raise_error(ArgumentError)
+    end
+    failure = RuntimeError.new('modern query failure')
+    allow(adapter).to receive(:detail_levels_for).and_raise(failure)
+    expect do
+      wrapper.adapter_detail_levels_for(adapter:, kind: :init, context:, result:, mode: :sync)
+    end.to(raise_error { |error| expect(error).to equal(failure) })
+  end
+end

data/spec/client_examples/profile_mount_spec.rb

@@ -1,5 +1,5 @@
 require 'spec_helper'
-require 'base64'
+require_relative '../../test_support/documentation_oauth_fixture'
 
 module ProfileMountSpec
   User = Struct.new(:login)
@@ -132,10 +132,21 @@ describe HaveAPI::Server, '#mount' do
     server.documentation_clients(version, go: { import_path: 'example.test/widget/client' })
   end
 
-  def request_as(user, locale)
+  def configure_documentation_identity
+    fixture = DocumentationOAuthFixture.configure(
+      server, users: { 1 => %w[member admin].to_h { |role| [role, ProfileMountSpec::User.new(role)] } },
+              mount_path: '/mounted/api/'
+    )
+    server.define_singleton_method(:documentation_fixture) { fixture }
+  end
+
+  def request_as(user, locale, resource: nil)
+    fixture = server.documentation_fixture
+    path = '/mounted/api/v1/'
+    path += "?resource=#{CGI.escape(resource)}" if resource
     Rack::MockRequest.new(server.app).get(
-      '/mounted/api/v1/', 'HTTP_HOST' => 'example.org', 'HTTP_ACCEPT_LANGUAGE' => locale,
-                          'HTTP_AUTHORIZATION' => "Basic #{Base64.strict_encode64("#{user}:pass")}"
+      "#{fixture.origin}#{path}", 'HTTP_HOST' => 'example.org', 'HTTP_ACCEPT_LANGUAGE' => locale,
+                                  'HTTP_COOKIE' => fixture.header_for(server, version: 1, token: user)
     )
   end
 
@@ -179,6 +190,7 @@ describe HaveAPI::Server, '#mount' do
   it 'captures each configured version once and does not initialize from requests' do
     register(1)
     register(2)
+    configure_documentation_identity
     server.mount('/mounted/api/')
     expect(descriptions.map { |description| description['help'] }).to eq(['/mounted/api/v1/', '/mounted/api/v2/'])
     request_as('member', 'en')
@@ -189,24 +201,32 @@ describe HaveAPI::Server, '#mount' do
 
   it 'keeps private schema separate from sequential users, locales, HTML and samples' do
     register
+    configure_documentation_identity
     server.available_locales = %i[en cs]
     ::I18n.backend.store_translations(:en, profile_mount_spec: { action: 'Visible English action' })
     ::I18n.backend.store_translations(:cs, profile_mount_spec: { action: 'Viditelna ceska akce' })
     server.mount('/mounted/api/')
-    privileged = request_as('admin', 'en')
+    privileged = request_as('admin', 'en', resource: 'widget')
     expect(privileged.status).to eq(200)
     expect(privileged.body).to include('PRIVATE_SAMPLE', 'Visible English action')
+    expect(contexts.select { |context| context.sample&.dig(:request, :secret) == 'PRIVATE_SAMPLE' }.map(&:detail))
+      .to contain_exactly(:simple, :thorough)
+    public_overview = request_as('member', 'cs')
+    expect(public_overview.status).to eq(200)
+    expect(public_overview.body).to include('init-go', 'example.test/widget/client')
+    expect(public_overview.body).not_to include('PRIVATE_DEFAULT', 'PRIVATE_SAMPLE', 'PRIVATE_RESPONSE')
     contexts.clear
-    public_response = request_as('member', 'cs')
+    public_response = request_as('member', 'cs', resource: 'widget')
     expect(public_response.status).to eq(200)
-    expect(public_response.body).to include('Viditelna ceska akce', 'init-go', 'example.test/widget/client')
+    expect(public_response.body).to include('Viditelna ceska akce', 'example-widget-show-0-go', 'example-widget-show-0-go-thorough')
     expect(public_response.body).not_to include('PRIVATE_DEFAULT', 'PRIVATE_SAMPLE', 'PRIVATE_RESPONSE', 'admin_only', 'haveapi.invalid', 'StructuralSchema')
     selected = contexts.find { |context| context.action_name == 'show' }
     expect(selected.action.dig(:input, :parameters).keys.map(&:to_s)).to eq(['visible'])
     expect(selected.description[:resources]['widget'][:actions]).not_to have_key('secret')
     expect(selected.sample[:request]).to eq(visible: 'public sample')
     expect(selected.action[:description]).to eq('Viditelna ceska akce')
-    expect(request_as('member', 'en').body).to include('Visible English action')
+    expect(contexts.select { |context| context.action_name == 'show' }.map(&:detail)).to contain_exactly(:simple, :thorough)
+    expect(request_as('member', 'en', resource: 'widget').body).to include('Visible English action')
     expect(descriptions.size).to eq(1)
   end
 
@@ -229,23 +249,30 @@ describe HaveAPI::Server, '#mount' do
 
   it 'mounts a generated TypeScript panel beside dynamic tabs using only authorized request samples' do
     register_typescript
+    configure_documentation_identity
     server.mount('/mounted/api/')
     expect(descriptions.size).to eq(1)
     private_schema = descriptions.first
     expect(private_schema).to be_frozen
     expect(JSON.generate(private_schema)).not_to include('PRIVATE_DEFAULT', 'PRIVATE_SAMPLE', 'PRIVATE_RESPONSE')
     expect(private_schema.dig('resources', 'widget', 'actions')).to have_key('secret')
-    expect(request_as('admin', 'en').body).to include('PRIVATE_SAMPLE')
+    expect(request_as('admin', 'en', resource: 'widget').body).to include('PRIVATE_SAMPLE')
+    overview = request_as('member', 'en')
+    expect(overview.status).to eq(200)
+    expect(overview.body).to include('init-typescript-generated', 'init-typescript-callback',
+                                     'init-typescript-async', '@example/widget-client')
+    expect(overview.body).not_to include('PRIVATE_SAMPLE', 'example-widget-show-0-typescript-generated')
     contexts.clear
-    response = request_as('member', 'en')
+    response = request_as('member', 'en', resource: 'widget')
     expect(response.status).to eq(200)
-    expect(response.body).to include('TypeScript (generated)', 'init-typescript-generated', 'init-typescript-callback',
-                                     'init-typescript-async', 'example-widget-show-0-typescript-generated', '@example/widget-client')
+    expect(response.body).to include('TypeScript API client', 'example-widget-show-0-typescript-generated',
+                                     'example-widget-show-0-typescript-generated-thorough')
     expect(response.body).not_to include('PRIVATE_DEFAULT', 'PRIVATE_SAMPLE', 'PRIVATE_RESPONSE', 'admin_only')
     selected = contexts.find { |context| context.action_name == 'show' }
-    expect(selected.version_url).to eq('http://example.org/mounted/api/v1/')
+    expect(selected.version_url).to eq('https://example.org/mounted/api/v1/')
     expect(selected.action.dig(:input, :parameters).keys).to eq([:visible])
     expect(selected.sample[:request]).to eq(visible: 'public sample')
+    expect(contexts.select { |context| context.action_name == 'show' }.map(&:detail)).to contain_exactly(:simple, :thorough)
     expect(documentation).to have_received(:from_description).once
   end
 

data/spec/client_examples/rust_client_spec.rb

@@ -3,6 +3,8 @@ require 'haveapi/documentation_context'
 require 'haveapi/client_examples/rust_client'
 
 class RustDocumentationAdapterFixture
+  def detail_levels_for(kind:, context:, result:, mode:, auth_method: nil, auth_description: nil); end
+
   def render(kind:, context:, mode:, auth_method: nil, auth_description: nil); end
 end
 
@@ -61,7 +63,7 @@ describe HaveAPI::ClientExamples::RustClient do
   end
 
   it 'preserves a concise adapter limitation without fabricating source' do
-    result = { status: :limitation, reason: 'This sample needs an unsupported SDK capability.' }.freeze
+    result = { status: :limitation, reason: 'This sample needs an unsupported API client capability.' }.freeze
     allow(adapter).to receive(:render).and_return(result)
     expect(HaveAPI::ClientExamples::RustAsyncClient.render(:example, context:)).to eq(result)
   end
@@ -72,4 +74,36 @@ describe HaveAPI::ClientExamples::RustClient do
     expect(renderer.auth(:basic, {})).to include(status: :limitation)
     expect(renderer.example({})).to include(status: :limitation)
   end
+
+  it 'delegates each mode capability with the exact Simple result without rerendering or mutating context' do
+    description = { http_header: 'X-Token' }.freeze
+    [HaveAPI::ClientExamples::RustAsyncClient, HaveAPI::ClientExamples::RustBlockingClient].each do |renderer|
+      allow(adapter).to receive(:detail_levels_for).and_return(%i[simple thorough].freeze)
+      levels = renderer.detail_levels_for(:auth, context:, result: code,
+                                                 auth_method: :token, auth_description: description)
+      expect(levels).to eq(%i[simple thorough])
+      expect(levels).to be_frozen
+      expect(adapter).to have_received(:detail_levels_for).with(
+        kind: :auth, context:, result: code, mode: renderer.rust_mode,
+        auth_method: :token, auth_description: description
+      )
+    end
+    expect(adapter).not_to have_received(:render)
+    expect(context.detail).to eq(:simple)
+    expect(context.profile.adapter).to equal(adapter)
+  end
+
+  it 'delegates limitation policy and rejects malformed modern levels instead of falling back' do
+    renderer = HaveAPI::ClientExamples::RustAsyncClient
+    limitation = { status: :limitation, reason: 'Unsupported sample' }.freeze
+    allow(adapter).to receive(:detail_levels_for).and_return([:simple].freeze)
+    expect(renderer.detail_levels_for(:example, context:, result: limitation)).to eq([:simple])
+    expect(adapter).to have_received(:detail_levels_for).with(
+      kind: :example, context:, result: limitation, mode: :async, auth_method: nil, auth_description: nil
+    )
+    [nil, [], [:thorough], %i[thorough simple], %i[simple simple], ['simple']].each do |invalid|
+      allow(adapter).to receive(:detail_levels_for).and_return(invalid)
+      expect { renderer.detail_levels_for(:example, context:, result: code) }.to raise_error(ArgumentError)
+    end
+  end
 end