haveapi 0.29.12 → 0.30.1

data/spec/client_examples/dynamic_python_spec.rb

@@ -0,0 +1,123 @@
+require 'spec_helper'
+require 'open3'
+require_relative 'dynamic_fixture'
+
+RSpec.describe HaveAPI::ClientExamples::PythonClient do
+  include DynamicExampleFixture
+
+  let(:renderers) { [described_class, HaveAPI::ClientExamples::PythonAsyncClient] }
+
+  it 'keeps both variants available without a generated SDK profile' do
+    expect(renderers.map(&:id)).to eq(%w[python-sync python-async])
+    expect(renderers.map(&:order)).to eq([14, 15])
+    expect(renderers).to all(be_available(dynamic_context))
+  end
+
+  it 'renders complete parseable init, auth, action and async ownership' do
+    renderers.each do |renderer|
+      results = [renderer.render(:init, context: dynamic_context), renderer.render(:example, context: dynamic_context)]
+      %i[basic token oauth2].each do |method|
+        results << renderer.render(:auth, context: dynamic_context, auth_method: method, auth_description: token_description)
+      end
+      results.each do |result|
+        expect(result[:status]).to eq(:code), result.inspect
+        expect(result).to be_frozen
+        output, status = Open3.capture2e('python', '-c', 'import ast, sys; ast.parse(sys.stdin.read())', stdin_data: result[:code])
+        expect(status).to be_success, output
+        expect(result[:code]).to include('https://api.example.test/mount/', 'version="2"')
+        expect(result[:code]).to include('except ActionError', 'except HaveAPIError')
+      end
+    end
+  end
+
+  it 'preserves exact mapping names, positional path order and every input value' do
+    renderers.each do |renderer|
+      source = renderer.render(:example, context: dynamic_context).fetch(:code)
+      expect(source).to include('.resources["constructor"].resources["resources"].actions[',
+                                'path_params={"parent_id": 7, "widget_id": "name/with space"}',
+                                '"enabled": False', '"count": 0', '"nullable": None', '"__proto__":',
+                                'print(response.data)', 'print(response.meta)')
+      if renderer.id == 'python-async'
+        expect(source).to include('async with AsyncClient', 'response = await ', 'asyncio.run(main())')
+      else
+        expect(source).to include('with Client')
+        expect(source).not_to include('await ')
+      end
+    end
+  end
+
+  it 'retains list rows and exposes a limitation for an unnamespaced list' do
+    action = dynamic_action.merge(input: { layout: :hash_list, namespace: :widgets, parameters: { name: { type: 'String' } } })
+    context = dynamic_context(action:, sample: dynamic_sample.merge(request: [{ name: '' }, { name: 'second' }]))
+    renderers.each do |renderer|
+      source = renderer.render(:example, context:).fetch(:code)
+      expect(source).to include('params=[{"name": ""}, {"name": "second"}]')
+      result = renderer.render(:example, context: context.with(action: action.merge(input: action[:input].merge(namespace: nil))))
+      expect(result[:status]).to eq(:limitation)
+    end
+  end
+
+  it 'does not turn a prose-only or incomplete example into an executable call' do
+    renderers.each do |renderer|
+      [dynamic_sample.merge(path_params: []), { request: nil, response: nil }].each do |sample|
+        result = renderer.render(:example, context: dynamic_context(sample:))
+        expect(result[:status]).to eq(:limitation)
+      end
+    end
+  end
+
+  it 'uses real token challenge APIs and advertised login fields without printing credentials' do
+    renderers.each do |renderer|
+      source = renderer.render(:auth, context: dynamic_context, auth_method: :token, auth_description: token_description).fetch(:code)
+      expect(source).to include('begin_token_login', 'step.input', 'step.submit(values)', 'HAVEAPI_AUTH_login-name')
+      expect(source).not_to include('print(step.token)', 'qwertyuiop')
+    end
+  end
+
+  it 'keeps advertised required lifecycle fields while omitting optional interval in both modes' do
+    description = token_description
+    parameters = description[:resources][:token][:actions]['request'][:input][:parameters]
+    parameters[:lifetime][:required] = true
+    parameters[:interval] = { type: 'Integer', required: false }
+    renderers.each do |renderer|
+      source = renderer.render(:auth, context: dynamic_context, auth_method: :token, auth_description: description).fetch(:code)
+      expect(source).to include('"lifetime": json.loads(os.environ["HAVEAPI_AUTH_lifetime"])')
+      expect(source).not_to include('HAVEAPI_AUTH_interval', 'HAVEAPI_CHALLENGE_token', 'renewable_auto')
+      expect(source).to include('if "HAVEAPI_TOKEN" in os.environ:', 'set_auth(TokenAuth(os.environ["HAVEAPI_TOKEN"]))',
+                                'for name in step.input if name != "token"', 'step.submit(values)')
+    end
+    parameters[:interval][:required] = true
+    renderers.each do |renderer|
+      source = renderer.render(:auth, context: dynamic_context, auth_method: :token, auth_description: description).fetch(:code)
+      expect(source).to include('"interval": json.loads(os.environ["HAVEAPI_AUTH_interval"])')
+    end
+  end
+
+  it 'limits GET examples to flat scalars and safe query names in both modes' do
+    action = dynamic_action.merge(method: 'GET', input: {
+      layout: :hash, namespace: :widget, parameters: { payload: { type: 'Custom', nullable: true } }
+    })
+    renderers.each do |renderer|
+      [{ enabled: false, count: 0 }, [], {}, { nested: 'string' }, ['string'], false, 0].each do |payload|
+        result = renderer.render(:example, context: dynamic_context(action:, sample: dynamic_sample.merge(request: { payload: })))
+        expect(result[:status]).to eq(:limitation)
+        expect(result[:reason]).to include('flat scalar')
+      end
+      [nil, '', 'safe'].each do |payload|
+        result = renderer.render(:example, context: dynamic_context(action:, sample: dynamic_sample.merge(request: { payload: })))
+        expect(result[:status]).to eq(:code), result.inspect
+      end
+      unsafe = action.merge(input: action[:input].merge(namespace: 'bad[name]'))
+      expect(renderer.render(:example, context: dynamic_context(action: unsafe, sample: dynamic_sample.merge(request: {})))[:status]).to eq(:limitation)
+    end
+  end
+
+  it 'keeps JSON input intact and limits methods unsupported by Python' do
+    renderers.each do |renderer|
+      %w[POST PUT DELETE HEAD OPTIONS].each do |method|
+        result = renderer.render(:example, context: dynamic_context(action: dynamic_action.merge(method:)))
+        expect(result[:status]).to eq(%w[POST PUT DELETE].include?(method) ? :code : :limitation)
+      end
+    end
+  end
+end

data/spec/client_examples/go_spec.rb

@@ -0,0 +1,57 @@
+require 'haveapi/documentation_context'
+require 'haveapi/documentation_clients'
+require 'haveapi/client_examples/go_client'
+
+RSpec.describe HaveAPI::ClientExamples::GoClient do
+  let(:result) { { status: :code, code: 'package main' }.freeze }
+  let(:adapter) do
+    contract = Class.new do
+      def render(**); end
+    end
+    instance_double(contract, render: result)
+  end
+  let(:profile) { Struct.new(:language, :adapter).new(:go, adapter) }
+  let(:context) do
+    HaveAPI::ClientExample::Context.new(
+      version: '7', host: 'api.example.test', base_url: 'https://api.example.test/mounted/',
+      version_url: 'https://api.example.test/mounted/v7/', description: {},
+      resource_path: %w[widget], action_name: 'update', action: {},
+      sample: { status: true, request: { enabled: false } }, profile:
+    )
+  end
+
+  it 'registers the frozen Go ID and requires its configured profile' do
+    expect(described_class.id).to eq('go')
+    expect(described_class.code).to eq(:go)
+    expect(described_class.order).to eq(16)
+    expect(described_class).to be_available(context)
+    expect(described_class).not_to be_available(context.with(profile: nil))
+    expect(described_class).not_to be_available(context.with(profile: Struct.new(:language).new(:rust)))
+  end
+
+  it 'delegates initialization without requiring the optional generator gem' do
+    expect(described_class.render(:init, context:)).to eq(result)
+    expect(adapter).to have_received(:render).with(kind: :init, context:, mode: :sync)
+  end
+
+  it 'delegates advertised authentication with its filtered descriptor' do
+    descriptor = { description: 'HTTP Basic authentication' }
+    expect(described_class.render(:auth, context:, auth_method: :basic, auth_description: descriptor)).to eq(result)
+    expect(adapter).to have_received(:render).with(kind: :auth, context:, mode: :sync,
+                                                   auth_method: :basic, auth_description: descriptor)
+  end
+
+  it 'binds the selected filtered example and preserves plain limitation results' do
+    limitation = { status: :limitation, reason: 'This Go SDK input is unsupported.' }.freeze
+    allow(adapter).to receive(:render).and_return(limitation)
+    expect(described_class.render(:example, context:)).to eq(limitation)
+    expect(adapter).to have_received(:render) do |**arguments|
+      selected = arguments.fetch(:context)
+      expect(arguments[:kind]).to eq(:example)
+      expect(arguments[:mode]).to eq(:sync)
+      expect(selected.sample).to eq(context.sample)
+      expect(selected.sample).to be_frozen
+      expect(selected.description).to eq(context.description)
+    end
+  end
+end

data/spec/client_examples/profile_mount_spec.rb

@@ -0,0 +1,215 @@
+require 'spec_helper'
+require 'base64'
+
+module ProfileMountSpec
+  User = Struct.new(:login)
+
+  module AuthenticationResources
+    class Session < HaveAPI::Resource
+      auth false
+      version :all
+
+      class Show < HaveAPI::Action
+        route ''
+        http_method :get
+        output(:hash) { string :id }
+        authorize { allow }
+      end
+    end
+  end
+
+  class Provider < HaveAPI::Authentication::Basic::Provider
+    def resource_module
+      AuthenticationResources
+    end
+
+    protected
+
+    def find_user(_request, username, password)
+      User.new(username) if %w[member admin].include?(username) && password == 'pass'
+    end
+  end
+
+  class Added < HaveAPI::Resource
+    auth false
+    version :all
+
+    class Index < HaveAPI::Action
+      route ''
+      http_method :get
+      output(:hash) { string :late }
+      authorize { allow }
+    end
+  end
+end
+
+describe HaveAPI::Server, '#mount' do
+  api do
+    define_resource(:Widget) do
+      version :all
+      auth false
+
+      define_action(:Show) do
+        route '{widget_id}'
+        http_method :get
+        desc HaveAPI.message('profile_mount_spec.action')
+        input(:hash) do
+          string :visible
+          string :secret, default: 'PRIVATE_DEFAULT'
+        end
+        output(:hash) do
+          string :visible
+          string :secret
+        end
+        authorize do |user|
+          unless user.login == 'admin'
+            input blacklist: [:secret]
+            output blacklist: [:secret]
+          end
+          allow
+        end
+
+        # rubocop:disable RSpec/NoExpectationExample
+        example 'visible sample' do
+          path_params 7
+          request({ visible: 'public sample' })
+          response({ visible: 'public response' })
+        end
+
+        example 'privileged sample' do
+          authorize { |user| user.login == 'admin' }
+          path_params 7
+          request({ secret: 'PRIVATE_SAMPLE' })
+          response({ secret: 'PRIVATE_RESPONSE' })
+        end
+        # rubocop:enable RSpec/NoExpectationExample
+      end
+
+      define_action(:Secret) do
+        route 'secret'
+        http_method :get
+        output(:hash) { string :admin_only }
+        authorize { |user| user.login == 'admin' ? allow : deny }
+      end
+    end
+  end
+
+  let(:server) { described_class.new(get_opt(:api_module)) }
+  let(:descriptions) { [] }
+  let(:contexts) { [] }
+  let(:documentation) { Class.new }
+  let(:adapter) do
+    selected_contexts = contexts
+    Class.new do
+      define_method(:resolve) { |**| nil }
+      define_method(:render) do |kind:, context:, **|
+        selected_contexts << context
+        { status: :code, code: JSON.generate(kind == :example ? context.sample : { url: context.version_url }) }
+      end
+    end.new
+  end
+
+  before do
+    generator = Module.new
+    generator.const_set(:VERSION, HaveAPI::VERSION)
+    generator.const_set(:Documentation, documentation)
+    stub_const('HaveAPI::GoClient', generator)
+    allow(registry).to receive(:require).with('haveapi/go_client/documentation').and_return(true)
+    allow(documentation).to receive(:new) do |description:, **|
+      descriptions << description
+      adapter
+    end
+    server.use_version([1, 2])
+    server.default_version = 1
+    server.auth_chain << ProfileMountSpec::Provider
+  end
+
+  def registry
+    server.instance_variable_get(:@documentation_clients)
+  end
+
+  def register(version = 1)
+    server.documentation_clients(version, go: { import_path: 'example.test/widget/client' })
+  end
+
+  def request_as(user, locale)
+    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")}"
+    )
+  end
+
+  it 'captures the complete selected version after auth, action-state and post-mount routes exist' do
+    register
+    server.action_state = Object.new
+    server.connect_hook(:post_mount) do |_ret, api_server, _sinatra|
+      expect(api_server.documentation_client_profiles(1)).to be_empty
+      api_server.mount_resource('/mounted/api/v1/', 1, ProfileMountSpec::Added, api_server.routes[1][:resources])
+      {}
+    end
+    allow(server).to receive(:describe_version).and_call_original
+    server.mount('/mounted/api/')
+    expect(server).to have_received(:describe_version).once
+    expect(descriptions.size).to eq(1)
+    private_schema = descriptions.first
+    expect(private_schema['help']).to eq('/mounted/api/v1/')
+    expect(private_schema['resources'].keys).to include('widget', 'action_state', 'added')
+    expect(private_schema.dig('resources', 'widget', 'actions').keys).to include('show', 'secret')
+    expect(private_schema.dig('authentication', 'basic', 'resources')).to have_key('session')
+    expect(private_schema.dig('resources', 'widget', 'actions', 'show', 'input', 'parameters')).to have_key('secret')
+    expect(JSON.generate(private_schema)).not_to include('PRIVATE_DEFAULT', 'PRIVATE_SAMPLE', 'PRIVATE_RESPONSE')
+    expect(server.documentation_client_profiles(1).fetch(:go).package_version).to be_nil
+    expect(server.documentation_client_profiles(2)).to be_empty
+  end
+
+  it 'captures each configured version once and does not initialize from requests' do
+    register(1)
+    register(2)
+    server.mount('/mounted/api/')
+    expect(descriptions.map { |description| description['help'] }).to eq(['/mounted/api/v1/', '/mounted/api/v2/'])
+    request_as('member', 'en')
+    request_as('admin', 'cs')
+    expect(descriptions.size).to eq(2)
+    expect { register }.to raise_error(HaveAPI::ClientExample::Profiles::Invalid, /already mounted/)
+  end
+
+  it 'keeps private schema separate from sequential users, locales, HTML and samples' do
+    register
+    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')
+    expect(privileged.status).to eq(200)
+    expect(privileged.body).to include('PRIVATE_SAMPLE', 'Visible English action')
+    contexts.clear
+    public_response = request_as('member', 'cs')
+    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).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(descriptions.size).to eq(1)
+  end
+
+  it 'makes the server unusable and publishes no profiles after an adapter failure' do
+    register
+    allow(documentation).to receive(:new).and_raise('PRIVATE_SCHEMA_DIAGNOSTIC')
+    expect { server.mount('/') }.to raise_error(HaveAPI::ClientExample::Profiles::Invalid, 'Configured documentation client schema or configuration is invalid')
+    expect(server.app).to be_nil
+    expect(server.documentation_client_profiles(1)).to be_empty
+  end
+
+  it 'makes the server unusable when a post-mount hook fails before finalization' do
+    register
+    server.connect_hook(:post_mount) { raise 'fixture mount failure' }
+    expect { server.mount('/') }.to raise_error(RuntimeError, 'fixture mount failure')
+    expect(documentation).not_to have_received(:new)
+    expect(server.app).to be_nil
+    expect(server.documentation_client_profiles(1)).to be_empty
+  end
+end

data/spec/client_examples/profiles_spec.rb

@@ -0,0 +1,265 @@
+require 'spec_helper'
+require 'tmpdir'
+
+describe HaveAPI::ClientExample::Profiles do
+  let(:profiles) { described_class.new }
+  let(:adapter) do
+    Class.new do
+      def resolve(**); end
+      def render(**); end
+    end.new
+  end
+  let(:directory) { Dir.mktmpdir('haveapi-doc-profiles-') }
+  let(:description) { { resources: {}, authentication: {}, meta: { namespace: '_meta' } } }
+  let(:server) { instance_double(HaveAPI::Server, versions: [1], root: '/', describe_version: description) }
+
+  def description_path
+    File.join(directory, 'description.json')
+  end
+
+  def config_path
+    File.join(directory, 'generator.toml')
+  end
+
+  def go_config
+    { import_path: 'example.test/widget/client', module_version: 'v1.2.3', description_path:, generator_version: HaveAPI::VERSION }
+  end
+
+  def rust_config
+    { snapshot_path: description_path, generator_config_path: config_path, generator_version: HaveAPI::VERSION }
+  end
+
+  def generator_config
+    { 'crate_name' => 'widget-client', 'crate_version' => '1.2.3' }
+  end
+
+  before do
+    File.write(description_path, JSON.generate(description))
+    File.write(config_path, 'fixture config')
+  end
+
+  after { FileUtils.remove_entry(directory) }
+
+  def install_go_adapter(version: HaveAPI::VERSION)
+    generator = Module.new
+    generator.const_set(:VERSION, version)
+    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)
+    documentation
+  end
+
+  def install_rust_adapter(factories: true)
+    generator = Module.new
+    generator.const_set(:VERSION, HaveAPI::VERSION)
+    documentation = Class.new
+    generator.const_set(:Documentation, documentation)
+    generator.const_set(:Generator, Class.new)
+    generator.const_set(:Model, Module.new)
+    generator.const_set(:Snapshot, Class.new)
+    stub_const('HaveAPI::RustClient', generator)
+    stub_const('Tomlrb', Module.new)
+    allow(Tomlrb).to receive(:load_file).with(config_path).and_return(generator_config)
+    allow(profiles).to receive(:require).with('haveapi/rust_client/documentation').and_return(true)
+    allow(documentation).to receive(:new).and_return(adapter)
+    if factories
+      allow(documentation).to receive_messages(from_description: adapter, from_snapshot: adapter)
+      allow(documentation).to receive(:validate_source) { |source| source }
+      allow(HaveAPI::RustClient::Generator).to receive(:validate_config)
+      allow(HaveAPI::RustClient::Model).to receive(:validate_package)
+    end
+    documentation
+  end
+
+  def finalize
+    profiles.mount([1])
+    profiles.finalize(server)
+  end
+
+  it 'needs no optional generator or schema when profiles are absent' do
+    allow(profiles).to receive(:require).and_raise('Unexpected optional dependency')
+    finalize
+    expect(profiles).not_to have_received(:require)
+    expect(server).not_to have_received(:describe_version)
+    expect(profiles.for_version(1)).to eq({})
+    expect(profiles.for_version(1)).to be_frozen
+  end
+
+  it 'loads an explicit saved adapter once without rereading it during finalization' do
+    documentation = install_go_adapter
+    profiles.register(1, go: go_config)
+    expect(profiles.for_version(1)).to be_empty
+    File.unlink(description_path)
+    finalize
+    profile = profiles.for_version(1).fetch(:go)
+    expect(profile).to have_attributes(language: :go, package_name: 'example.test/widget/client', package_version: 'v1.2.3')
+    expect(profile).to be_frozen
+    expect(profile.adapter).to equal(adapter)
+    expect(documentation).to have_received(:new).once.with(description: JSON.parse(JSON.generate(description)), import_path: 'example.test/widget/client', module_version: 'v1.2.3')
+    expect(server).not_to have_received(:describe_version)
+    expect(profile).not_to respond_to(:description_path)
+  end
+
+  it 'defaults the generator version and defers automatic Go without inventing an SDK version' do
+    documentation = install_go_adapter
+    config = { import_path: 'example.test/widget/client' }
+    profiles.register(1, go: config)
+    config[:import_path].replace('changed.test/client')
+    expect(documentation).not_to have_received(:new)
+    finalize
+    profile = profiles.for_version(1).fetch(:go)
+    expect(profile.package_name).to eq('example.test/widget/client')
+    expect(profile.package_version).to be_nil
+    expect(documentation).to have_received(:new).with(description: JSON.parse(JSON.generate(description)), import_path: 'example.test/widget/client', module_version: nil)
+    expect(server).to have_received(:describe_version).once
+  end
+
+  it 'permits nil SDK versions and retains explicitly pinned generator versions' do
+    documentation = install_go_adapter(version: '0.29.0')
+    profiles.register(1, go: go_config.merge(module_version: nil, generator_version: '0.29.0'))
+    finalize
+    expect(profiles.for_version(1).fetch(:go).package_version).to be_nil
+    expect(documentation).to have_received(:new).with(description: anything, import_path: anything, module_version: nil)
+  end
+
+  it 'rejects unknown languages, malformed fields and unsafe package configuration' do
+    expect { profiles.register(1, python: {}) }.to raise_error(described_class::Invalid, /Unknown/)
+    expect { profiles.register(1, go: go_config.merge(unexpected: 'value')) }.to raise_error(described_class::Invalid, /fields/)
+    expect { profiles.register(1, go: go_config.merge(import_path: "example.test/\nsource")) }.to raise_error(described_class::Invalid, /package/)
+    ['latest', '', 1, false].each do |value|
+      expect { profiles.register(1, go: go_config.merge(module_version: value)) }.to raise_error(described_class::Invalid, /package/)
+    end
+    expect { profiles.register(1, go: go_config.merge(generator_version: nil)) }.to raise_error(described_class::Invalid)
+    expect { profiles.register(1, go: go_config.merge(generator_version: 'latest')) }.to raise_error(described_class::Invalid, /generator version/)
+    expect { profiles.register(1, go: {}) }.to raise_error(described_class::Invalid, /package/)
+  end
+
+  it 'rejects missing adapters, mismatched generator versions and missing files at registration' do
+    allow(profiles).to receive(:require).and_raise(LoadError)
+    expect { profiles.register(1, go: go_config) }.to raise_error(described_class::Invalid, /not installed/)
+    install_go_adapter
+    expect { profiles.register(1, go: go_config.merge(generator_version: '0.29.0')) }.to raise_error(described_class::Invalid, /version mismatch/)
+    expect { profiles.register(1, go: go_config.merge(description_path: 'relative.json')) }.to raise_error(described_class::Invalid, /absolute local/)
+  end
+
+  it 'checks the configured adapter interface' do
+    documentation = install_go_adapter
+    allow(documentation).to receive(:new).and_return(Object.new)
+    expect { profiles.register(1, go: go_config) }.to raise_error(described_class::Invalid, /adapter interface/)
+  end
+
+  it 'does not leave a partially registered language set after an invalid second profile' do
+    install_go_adapter
+    expect { profiles.register(1, go: go_config, rust: { unknown: 'field' }) }.to raise_error(described_class::Invalid)
+    profiles.register(1, go: go_config)
+    finalize
+    expect(profiles.for_version(1).keys).to eq([:go])
+  end
+
+  it 'rejects duplicates and registration after mounting starts' do
+    install_go_adapter
+    profiles.register(1, go: go_config)
+    expect { profiles.register('1', go: go_config) }.to raise_error(described_class::Invalid, /Duplicate/)
+    profiles.mount([1])
+    expect { profiles.register(2, go: go_config) }.to raise_error(described_class::Invalid, /already mounted/)
+    profiles.finalize(server)
+    expect { profiles.finalize(server) }.to raise_error(described_class::Invalid, /not ready/)
+  end
+
+  it 'rejects profiles for an unavailable version' do
+    install_go_adapter
+    profiles.register(1, go: go_config)
+    expect { profiles.mount([2]) }.to raise_error(described_class::Invalid, /unavailable API version/)
+    expect(profiles.for_version(1)).to be_empty
+  end
+
+  it 'preserves legacy Rust construction even without the new factories' do
+    documentation = install_rust_adapter(factories: false)
+    File.write(description_path, JSON.generate({ api_version: '1' }))
+    profiles.register(1, rust: rust_config)
+    finalize
+    expect(documentation).to have_received(:new).with(snapshot: { 'api_version' => '1' }, config: generator_config)
+    expect(profiles.for_version(1).fetch(:rust)).to have_attributes(package_name: 'widget-client', package_version: '1.2.3')
+  end
+
+  it 'rejects a saved Rust snapshot for a different selected API version at mount' do
+    install_rust_adapter
+    File.write(description_path, JSON.generate({ api_version: '2' }))
+    profiles.register(1, rust: rust_config)
+    expect { profiles.mount([1]) }.to raise_error(described_class::Invalid, /snapshot API version mismatch/)
+    expect(profiles.for_version(1)).to be_empty
+  end
+
+  it 'validates inline Rust identity and source before building from the mounted description' do
+    documentation = install_rust_adapter
+    source = { git: 'https://example.test/widget-client', rev: 'a' * 40 }
+    profiles.register(1, rust: { crate_name: 'widget-client', source: })
+    expect(HaveAPI::RustClient::Model).to have_received(:validate_package).with(crate_name: 'widget-client', crate_version: nil)
+    expect(documentation).to have_received(:validate_source).with(source)
+    expect(documentation).not_to have_received(:from_description)
+    finalize
+    expect(documentation).to have_received(:from_description).with(description: anything, api_version: '1', protocol_version: HaveAPI::PROTOCOL_VERSION,
+                                                                   mount_path: '/', crate_name: 'widget-client', crate_version: nil, source:)
+    expect(profiles.for_version(1).fetch(:rust).package_version).to be_nil
+  end
+
+  it 'supports an inline Rust identity with a saved snapshot and optional explicit SDK version' do
+    documentation = install_rust_adapter
+    snapshot = { 'api_version' => '1' }
+    File.write(description_path, JSON.generate(snapshot))
+    profiles.register(1, rust: { snapshot_path: description_path, crate_name: 'widget-client', crate_version: '1.2.3' })
+    finalize
+    expect(documentation).to have_received(:from_snapshot).with(snapshot:, crate_name: 'widget-client', crate_version: '1.2.3', source: nil)
+    expect(server).not_to have_received(:describe_version)
+  end
+
+  it 'validates full legacy TOML before using it with an automatic Rust description' do
+    documentation = install_rust_adapter
+    snapshot = { 'api_version' => '1' }
+    allow(HaveAPI::RustClient::Snapshot).to receive(:from_description).and_return(snapshot)
+    profiles.register(1, rust: { generator_config_path: config_path })
+    expect(HaveAPI::RustClient::Generator).to have_received(:validate_config).with(generator_config)
+    finalize
+    expect(HaveAPI::RustClient::Snapshot).to have_received(:from_description).with(description: anything, api_version: '1', protocol_version: HaveAPI::PROTOCOL_VERSION,
+                                                                                   mount_path: '/', source_url: 'https://haveapi.invalid/v1/', profile: 'server-documentation')
+    expect(documentation).to have_received(:new).with(snapshot:, config: generator_config)
+  end
+
+  it 'rejects automatic and inline modes when an older Rust generator lacks their factories' do
+    install_rust_adapter(factories: false)
+    expect { profiles.register(1, rust: { generator_config_path: config_path }) }.to raise_error(described_class::Invalid, /does not support/)
+    expect { profiles.register(1, rust: { crate_name: 'widget-client', snapshot_path: description_path }) }.to raise_error(described_class::Invalid, /does not support/)
+  end
+
+  it 'rejects conflicting Rust identities and unknown source profile fields' do
+    install_rust_adapter
+    expect { profiles.register(1, rust: rust_config.merge(crate_name: 'widget-client')) }.to raise_error(described_class::Invalid, /Conflicting/)
+    expect { profiles.register(1, rust: rust_config.merge(crate_version: nil)) }.to raise_error(described_class::Invalid, /Conflicting/)
+    expect { profiles.register(1, rust: { crate_name: 'widget-client', branch: 'main' }) }.to raise_error(described_class::Invalid, /fields/)
+  end
+
+  it 'captures one private structural schema per version shared by automatic profiles' do
+    go = install_go_adapter
+    rust = install_rust_adapter
+    profiles.register(1, go: { import_path: 'example.test/client' }, rust: { crate_name: 'widget-client' })
+    finalize
+    expect(server).to have_received(:describe_version).once do |context|
+      expect(context).to have_attributes(server:, version: 1, current_user: nil, endpoint: false, doc: true)
+    end
+    expect(go).to have_received(:new).with(description: anything, import_path: anything, module_version: nil)
+    expect(rust).to have_received(:from_description).with(description: anything, api_version: '1', protocol_version: anything, mount_path: '/', crate_name: anything, crate_version: nil, source: nil)
+  end
+
+  it 'publishes no partial profiles and hides private diagnostics when finalization fails' do
+    install_go_adapter
+    rust = install_rust_adapter
+    allow(rust).to receive(:from_description).and_raise('HIDDEN_SCHEMA_DEFAULT')
+    profiles.register(1, go: { import_path: 'example.test/client' }, rust: { crate_name: 'widget-client' })
+    profiles.mount([1])
+    expect { profiles.finalize(server) }.to raise_error(described_class::Invalid, 'Configured documentation client schema or configuration is invalid')
+    expect(profiles.for_version(1)).to be_empty
+    expect { profiles.register(1, go: go_config) }.to raise_error(described_class::Invalid, /already mounted/)
+  end
+end