haveapi 0.29.12 → 0.30.0

data/spec/client_examples/dynamic_acceptance_spec.rb

@@ -0,0 +1,76 @@
+require 'spec_helper'
+require 'rack/mock'
+require_relative 'dynamic_acceptance'
+
+RSpec.describe DynamicDocumentationAcceptance do
+  it 'extracts actual six-language HTML panels from the mounted fixture' do
+    request = Rack::MockRequest.new(DynamicDocumentationAPI.build.app)
+    response = request.get('http://example.test/mount/v2/', 'HTTP_HOST' => 'example.test')
+    expect(response.status).to eq(200), response.body
+    panels = described_class.extract(response.body)
+    described_class::VARIANTS.each do |variant|
+      selected = panels.select { |panel| panel[:variant] == variant }
+      expect(selected.map { |panel| panel[:id].split('-').first }).to include('init', 'auth', 'example')
+      expect(selected.count { |panel| panel[:id].start_with?('example-') }).to eq(2)
+      expect(selected.last[:source]).to include('http://example.test/mount/')
+      expect(selected.last[:source]).not_to include('"')
+    end
+  end
+
+  it 'records real success and failure request values without source rewriting' do
+    request = Rack::MockRequest.new(DynamicDocumentationAPI.build.app)
+    payload = { widget: { name: '', enabled: false, count: 0, nullable: nil, payload: DynamicDocumentationAPI::PAYLOAD } }
+    headers = {
+      'CONTENT_TYPE' => 'application/json',
+      'HTTP_AUTHORIZATION' => "Basic #{['fixture-user:fixture-password'].pack('m0')}",
+      input: JSON.generate(payload)
+    }
+    path = 'http://example.test/mount/v2/parents/7/children/name%20with%20space'
+    response = request.post(path, headers)
+    expect(response.status).to eq(200), response.body
+    expect(JSON.parse(response.body).fetch('status')).to be(true)
+    expect(DynamicDocumentationAPI.receipts.last[:input][:payload]).to eq(DynamicDocumentationAPI::PAYLOAD)
+    payload[:widget][:count] = -1
+    response = request.post(path, headers.merge(input: JSON.generate(payload)))
+    expect(response.status).to eq(400), response.body
+    expect(JSON.parse(response.body).fetch('message')).to eq('DOC_FAILURE')
+  end
+
+  it 'preserves subprocess output before reporting a nonzero execution failure' do
+    Dir.mktmpdir('haveapi-doc-output-') do |directory|
+      path = File.join(directory, 'example-12.log')
+      expect do
+        described_class.run!('ruby', '-e', 'warn "Discovery or authentication failed"; exit 1', chdir: directory, log_path: path)
+      end.to raise_error(RuntimeError, /Discovery or authentication failed/)
+      expect(File.read(path)).to include('Discovery or authentication failed')
+    end
+  end
+
+  it 'preserves separate existing-token and challenge output before completion assertions' do
+    Dir.mktmpdir('haveapi-doc-output-') do |directory|
+      command = ['ruby', '-e', 'puts ENV.key?("HAVEAPI_TOKEN") ? "Authenticated" : "Discovery or authentication failed"']
+      path = File.join(directory, 'example-12.log')
+      challenge_path = File.join(directory, 'example-12-challenge.log')
+      result = described_class.run!(*command, chdir: directory, env: { 'HAVEAPI_TOKEN' => 'fixture-token' }, log_path: path)
+      challenge = described_class.run!(*command, chdir: directory, env: { 'HAVEAPI_TOKEN' => nil }, log_path: challenge_path)
+      expect(File.read(path)).to eq(result)
+      expect(File.read(challenge_path)).to eq(challenge)
+      expect(result).to include('Authenticated')
+      expect(challenge).to include('Discovery or authentication failed')
+    end
+  end
+
+  it 'traces failed mounted routes without headers, query strings or request bodies' do
+    output = StringIO.new
+    app = DynamicDocumentationAPI::RequestTrace.new(DynamicDocumentationAPI.build.app, output:)
+    request = Rack::MockRequest.new(app)
+    response = request.post('http://example.test/mount/mount/_auth/token/tokens?credential=query-secret',
+                            'HTTP_AUTHORIZATION' => 'Bearer header-secret', 'CONTENT_TYPE' => 'application/json',
+                            input: JSON.generate({ password: 'body-secret' }))
+    expect(response.status).to eq(404)
+    prefix = 'DYNAMIC_DOCUMENTATION_REQUEST '
+    trace = JSON.parse(output.string.delete_prefix(prefix))
+    expect(trace).to eq('method' => 'POST', 'path' => '/mount/mount/_auth/token/tokens', 'status' => 404)
+    expect(output.string).not_to include('secret', 'credential', 'password', 'Bearer')
+  end
+end

data/spec/client_examples/dynamic_fixture.rb

@@ -0,0 +1,36 @@
+module DynamicExampleFixture
+  def dynamic_action
+    {
+      method: 'POST', path: '/mount/v2/parents/{parent_id}/widgets/{widget_id}',
+      input: { layout: :hash, namespace: :widget,
+               parameters: { name: { type: 'String' }, enabled: { type: 'Boolean' }, count: { type: 'Integer' },
+                             nullable: { type: 'String', nullable: true }, metadata: { type: 'Custom' } } },
+      output: { layout: :hash, namespace: :widget, parameters: { id: { type: 'Integer' } } }
+    }
+  end
+
+  def dynamic_sample
+    {
+      path_params: [7, 'name/with space'],
+      request: { name: "Unicode žluťoučký \"quote\"\\\n</script>", enabled: false, count: 0,
+                 nullable: nil, metadata: { '__proto__' => { 'constructor' => [false, 0, nil, ''] } } },
+      response: { id: 0 }, status: true
+    }
+  end
+
+  def dynamic_context(**changes)
+    HaveAPI::ClientExample::Context.new(
+      version: '2', host: 'api.example.test', base_url: 'https://api.example.test/mount/',
+      version_url: 'https://api.example.test/mount/v2/',
+      description: { authentication: { basic: {}, token: {}, oauth2: {} }, resources: {} },
+      resource_path: %w[constructor resources], resource: {}, action_name: "new\"\n</script>",
+      action: dynamic_action, sample: dynamic_sample, **changes
+    )
+  end
+
+  def token_description
+    { resources: { token: { actions: { 'request' => { input: { parameters: {
+      'login-name' => { type: 'String' }, password: { type: 'String' }, lifetime: { type: 'String' }
+    } } } } } } }
+  end
+end

data/spec/client_examples/dynamic_js_spec.rb

@@ -0,0 +1,195 @@
+require 'spec_helper'
+require 'open3'
+require 'tempfile'
+require_relative 'dynamic_fixture'
+
+RSpec.describe HaveAPI::ClientExamples::JsClient do
+  include DynamicExampleFixture
+
+  let(:renderers) do
+    [described_class, HaveAPI::ClientExamples::JsAsyncClient,
+     HaveAPI::ClientExamples::TsClient, HaveAPI::ClientExamples::TsAsyncClient]
+  end
+
+  def syntax(renderer, source)
+    if renderer.code == :typescript
+      compiler = File.expand_path('../../../../clients/js/node_modules/typescript', __dir__)
+      script = <<~'JS'
+        const ts = require(process.argv[1]);
+        const source = require('fs').readFileSync(0, 'utf8');
+        const result = ts.transpileModule(source, {reportDiagnostics: true, compilerOptions: {target: ts.ScriptTarget.ES2020}});
+        for (const diagnostic of result.diagnostics || []) console.error(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
+        process.exit((result.diagnostics || []).length ? 1 : 0);
+      JS
+      Open3.capture2e('node', '-e', script, compiler, stdin_data: source)
+    else
+      Tempfile.create(['haveapi-doc-js-', '.mjs']) do |file|
+        file.write(source)
+        file.flush
+        Open3.capture2e('node', '--check', file.path)
+      end
+    end
+  end
+
+  it 'keeps all four stable dynamic variants available without profiles' do
+    expect(renderers.map(&:id)).to eq(%w[javascript-callback javascript-async typescript-callback typescript-async])
+    expect(renderers.map(&:order)).to eq([10, 11, 12, 13])
+    expect(renderers).to all(be_available(dynamic_context))
+  end
+
+  it 'renders complete syntax-valid initialization, authentication and hostile action programs' 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
+        expect(result[:code]).to include('https://api.example.test/mount/', 'version: "2"')
+        output, status = syntax(renderer, result[:code])
+        expect(status).to be_success, output
+        expect(result[:code]).not_to match(/\bas any\b|\bas unknown\b|\._private|api\.constructor/)
+      end
+    end
+  end
+
+  it 'uses exact public lookups and retains false, zero, null and hostile Custom keys' do
+    renderers.each do |renderer|
+      source = renderer.render(:example, context: dynamic_context).fetch(:code)
+      expect(source).to include('["enabled"]: false', '["count"]: 0', '["nullable"]: null', '["__proto__"]:')
+      expect(source).to include('new\\"\\n</script>')
+      if renderer.id.end_with?('-async')
+        expect(source).to include('.resource("constructor").resource("resources").action(', 'result.value', 'result.response.meta')
+      else
+        expect(source).to include('CallbackClient.findResource', 'CallbackClient.findAction', 'action.directInvoke', 'reply.message()', 'reply.envelope.errors')
+      end
+    end
+  end
+
+  it 'checks TypeScript examples against the real emitted public declarations with strict types' do
+    root = File.expand_path('../../../..', __dir__)
+    Dir.mktmpdir('haveapi-ts-docs-') do |directory|
+      files = []
+      [HaveAPI::ClientExamples::TsClient, HaveAPI::ClientExamples::TsAsyncClient].each_with_index do |renderer, index|
+        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_with_index do |result, number|
+          path = File.join(directory, "#{index}-#{number}.ts")
+          File.write(path, result.fetch(:code))
+          files << path
+        end
+      end
+      options = { strict: true, noEmit: true, target: 'ES2020', module: 'ESNext', moduleResolution: 'node',
+                  typeRoots: [File.join(root, 'clients/js/node_modules/@types')], types: ['node'],
+                  baseUrl: directory, paths: { 'haveapi-client' => [File.join(root, 'clients/js/dist/types/haveapi')] } }
+      config = File.join(directory, 'tsconfig.json')
+      File.write(config, JSON.generate({ compilerOptions: options, files: }))
+      output, status = Open3.capture2e('node', File.join(root, 'clients/js/node_modules/typescript/bin/tsc'), '-p', config)
+      expect(status).to be_success, output
+    end
+  end
+
+  it 'never drops list input, unknown fields or unresolved path arguments' do
+    invalid = [
+      dynamic_context(sample: dynamic_sample.merge(request: [{ name: 'row' }])),
+      dynamic_context(sample: dynamic_sample.merge(request: { hidden: 'not visible' })),
+      dynamic_context(sample: dynamic_sample.merge(path_params: [7])),
+      dynamic_context(sample: dynamic_sample.merge(request: { count: 9_007_199_254_740_992 })),
+      dynamic_context(sample: { request: nil, response: nil, comment: 'prose only' })
+    ]
+    renderers.each do |renderer|
+      invalid.each do |context|
+        result = renderer.render(:example, context:)
+        expect(result[:status]).to eq(:limitation)
+        expect(result[:reason]).not_to be_empty
+        expect(result).not_to have_key(:code)
+      end
+    end
+  end
+
+  it 'limits unsupported or unadvertised authentication instead of inventing a flow' do
+    renderers.each do |renderer|
+      result = renderer.render(:auth, context: dynamic_context(description: { authentication: {} }), auth_method: :basic, auth_description: {})
+      expect(result[:status]).to eq(:limitation)
+      result = renderer.render(:auth, context: dynamic_context, auth_method: :custom, auth_description: {})
+      expect(result[:status]).to eq(:limitation)
+    end
+  end
+
+  it 'uses actual operation completion support only for the async client' do
+    renderers.each do |renderer|
+      source = renderer.render(:example, context: dynamic_context(action: dynamic_action.merge(blocking: true))).fetch(:code)
+      if renderer.id.end_with?('-async')
+        expect(source).to include('await api.waitForCompletion(result, {timeoutMs: 300000})')
+      else
+        expect(source).not_to include('waitForCompletion(')
+        expect(source).to include('initial response')
+      end
+    end
+  end
+
+  it 'limits nested GET and OPTIONS query input while preserving scalar queries and HEAD bodies' do
+    renderers.each do |renderer|
+      %w[GET OPTIONS HEAD].each do |method|
+        action = dynamic_action.merge(method:)
+        result = renderer.render(:example, context: dynamic_context(action:))
+        expect(result[:status]).to eq(method == 'HEAD' ? :code : :limitation)
+        params = { name: '', enabled: false, count: 0, nullable: nil }
+        scalar = renderer.render(:example, context: dynamic_context(action:, sample: dynamic_sample.merge(request: params)))
+        expect(scalar[:status]).to eq(:code), scalar.inspect
+        expect(scalar[:code]).to include('["enabled"]: false', '["count"]: 0', '["nullable"]: null')
+      end
+    end
+  end
+
+  it 'cross-checks query loss and HEAD bodies against both native JavaScript clients' do
+    helper = File.expand_path('../../../../clients/js/test/helpers/async_bundle.cjs', __dir__)
+    script = <<~JS
+      const assert = require('node:assert/strict');
+      const {harness, action, description} = require(process.argv[1]);
+      async function check() {
+        for (const method of ['GET', 'OPTIONS', 'HEAD']) {
+          for (const params of [{payload: {enabled: false, count: 0}}, {enabled: false, count: 0, nullable: null}]) {
+            const {HaveAPI, requests} = harness();
+            const callback = new HaveAPI.CallbackClient('https://api.example.test');
+            const model = description();
+            model.resources.widgets.actions.validate = action({payload: {type: 'Custom'}, enabled: {type: 'Boolean'},
+              count: {type: 'Integer'}, nullable: {type: 'String', nullable: true}}, {method});
+            callback.setup((api, ready) => {
+              assert.equal(ready, true);
+              const resource = HaveAPI.CallbackClient.findResource(api, ['widgets']);
+              HaveAPI.CallbackClient.findAction(resource, 'validate').directInvoke({params});
+            });
+            requests[0].respond({status: true, version: '2.0', response: model});
+            const asyncClient = new HaveAPI.AsyncClient('https://api.example.test');
+            const pending = asyncClient.request({method, path: '/v1/validate', inputNamespace: 'widget', params});
+            assert.equal(callback.sendAsQueryParams(method), method !== 'HEAD');
+            for (const wire of requests.slice(1)) {
+              if (method === 'HEAD') {
+                assert.deepEqual(JSON.parse(wire.body), {widget: params});
+                assert.equal(new URL(wire.url).search, '');
+              } else {
+                const query = new URL(wire.url).searchParams;
+                assert.equal(wire.body, undefined);
+                if (params.payload) assert.equal(query.get('widget[payload]'), '[object Object]');
+                else {
+                  assert.equal(query.get('widget[enabled]'), 'false');
+                  assert.equal(query.get('widget[count]'), '0');
+                  assert.equal(query.get('widget[nullable]'), '');
+                }
+              }
+              wire.respond({status: true, response: {}});
+            }
+            await pending;
+          }
+        }
+      }
+      check().catch(error => { console.error(error); process.exitCode = 1; });
+    JS
+    output, status = Open3.capture2e('node', '-e', script, helper)
+    expect(status).to be_success, output
+  end
+end

data/spec/client_examples/dynamic_metadata_spec.rb

@@ -0,0 +1,52 @@
+require 'spec_helper'
+require_relative 'dynamic_fixture'
+
+RSpec.describe HaveAPI::ClientExamples::DynamicHelpers do
+  include DynamicExampleFixture
+
+  let(:renderers) do
+    [HaveAPI::ClientExamples::JsClient, HaveAPI::ClientExamples::JsAsyncClient,
+     HaveAPI::ClientExamples::TsClient, HaveAPI::ClientExamples::TsAsyncClient,
+     HaveAPI::ClientExamples::PythonClient, HaveAPI::ClientExamples::PythonAsyncClient]
+  end
+
+  it 'limits all sample outcomes that need required global or object input metadata' do
+    %i[global object].each do |scope|
+      metadata = { scope => { input: { layout: :hash, namespace: false,
+                                       parameters: { private_confirmation: { type: 'Boolean', required: true, default: false } } } } }
+      action = dynamic_action.merge(meta: metadata)
+      [true, false].each do |status|
+        renderers.each do |renderer|
+          result = renderer.render(:example, context: dynamic_context(action:, sample: dynamic_sample.merge(status:)))
+          expect(result[:status]).to eq(:limitation)
+          expect(result[:reason]).to eq('This action requires input metadata that the sample format cannot supply.')
+          expect(result[:reason]).not_to include('private_confirmation', 'default')
+          expect(result).not_to have_key(:code)
+        end
+      end
+    end
+  end
+
+  it 'keeps absent, optional and output-only metadata executable without invented values' do
+    [nil, {}, { global: { input: { parameters: { optional: { type: 'Boolean', required: false } } } } },
+     { object: { input: { parameters: { optional: { type: 'Boolean' } } } } },
+     { global: { output: { parameters: { required_output: { type: 'String', required: true } } } } }].each do |meta|
+      renderers.each do |renderer|
+        result = renderer.render(:example, context: dynamic_context(action: dynamic_action.merge(meta:)))
+        expect(result[:status]).to eq(:code), result.inspect
+        expect(result[:code]).not_to include('optional', 'required_output')
+      end
+    end
+  end
+
+  it 'checks string-keyed metadata and does not apply object metadata without action input' do
+    action = dynamic_action.merge(meta: { 'object' => { 'input' => { 'parameters' => {
+      'confirmation' => { 'type' => 'Boolean', 'required' => true }
+    } } } })
+    renderers.each do |renderer|
+      expect(renderer.render(:example, context: dynamic_context(action:))[:status]).to eq(:limitation)
+      context = dynamic_context(action: action.merge(input: nil), sample: dynamic_sample.merge(request: {}))
+      expect(renderer.render(:example, context:)[:status]).to eq(:code)
+    end
+  end
+end

data/spec/client_examples/dynamic_mounted_paths_spec.rb

@@ -0,0 +1,65 @@
+require 'spec_helper'
+require 'open3'
+require 'rack/mock'
+require_relative '../../test_support/dynamic_documentation_api'
+
+RSpec.describe DynamicDocumentationAPI do
+  it 'uses real mounted descriptor routes for callback and async token challenges and nested actions' do
+    request = Rack::MockRequest.new(described_class.build.app)
+    headers = { 'HTTP_AUTHORIZATION' => "Basic #{['fixture-user:fixture-password'].pack('m0')}" }
+    envelope = JSON.parse(request.options('http://example.test/mount/v2/', headers).body)
+    model = envelope.fetch('response')
+    token = model.fetch('authentication').fetch('token').fetch('resources').fetch('token').fetch('actions')
+    action = model.fetch('resources').fetch('constructor').fetch('resources').fetch('resources').fetch('actions').fetch('new')
+    expect(token.fetch('request').fetch('path')).to eq('/mount/_auth/token/tokens')
+    expect(action.fetch('path')).to eq('/mount/v2/parents/{parent_id}/children/{widget_id}')
+    params = action.fetch('examples').first.fetch('request')
+    post = lambda do |path, body, extra = {}|
+      response = request.post("http://example.test#{path}", extra.merge('CONTENT_TYPE' => 'application/json', input: JSON.generate(body)))
+      expect(response.status).to eq(200), response.body
+      JSON.parse(response.body)
+    end
+    challenge = post.call(token.fetch('request').fetch('path'), { token: {
+      user: 'fixture-user', password: 'fixture-password', scope: 'all', lifetime: 'renewable_auto'
+    } })
+    completed = post.call(token.fetch('verify').fetch('path'), { token: { token: 'fixture-challenge', code: '123456' } })
+    action_path = action.fetch('path').sub('{parent_id}', '7').sub('{widget_id}', 'name%20with%20space')
+    result = post.call(action_path, { widget: params }, { 'HTTP_X_HAVEAPI_AUTH_TOKEN' => 'fixture-token' })
+    data = { envelope:, challenge:, completed:, result:, params:, action_path: }
+    script = <<~JS
+      const assert = require('node:assert/strict');
+      const {harness, tick} = require(process.argv[1]);
+      const {HaveAPI, requests} = harness();
+      const data = JSON.parse(require('node:fs').readFileSync(0, 'utf8'));
+      const model = data.envelope.response;
+      const auth = model.authentication.token.resources.token.actions;
+      async function check() {
+        const callback = new HaveAPI.CallbackClient('http://example.test/mount/', {version:'2'});
+        let ready = false;
+        callback.authenticate('token', {user:'fixture-user', password:'fixture-password', scope:'all', callback: () => ({code:'123456'})},
+          (_, ok) => { ready = ok; });
+        // Parse actual discovery JSON inside the bundle's VM, matching the real XHR boundary.
+        assert.equal(requests[0].url, 'http://example.test/mount/v2/'); requests[0].respond(data.envelope);
+        assert.equal(requests[1].url, 'http://example.test' + auth.request.path); requests[1].respond(data.challenge);
+        assert.equal(requests[2].url, 'http://example.test' + auth.verify.path); requests[2].respond(data.completed);
+        assert.equal(requests[3].url, 'http://example.test/mount/v2/'); requests[3].respond(data.envelope); assert.equal(ready, true);
+        const resource = HaveAPI.CallbackClient.findResource(callback, ['constructor','resources']);
+        HaveAPI.CallbackClient.findAction(resource, 'new').directInvoke(7, 'name with space', {params:data.params});
+        assert.equal(requests[4].url, 'http://example.test' + data.action_path); requests[4].respond(data.result);
+        const api = new HaveAPI.AsyncClient('http://example.test/mount/', {version:'2'}); api.useDescription(model);
+        const authenticating = api.authenticate('token', {user:'fixture-user', password:'fixture-password', scope:'all', onChallenge: () => ({code:'123456'})});
+        await tick(); assert.equal(requests[5].url, 'http://example.test' + auth.request.path); requests[5].respond(data.challenge);
+        await tick(); assert.equal(requests[6].url, 'http://example.test' + auth.verify.path); requests[6].respond(data.completed);
+        await tick(); assert.equal(requests[7].url, 'http://example.test/mount/v2/'); requests[7].respond(data.envelope); await authenticating;
+        const invoked = api.resource('constructor').resource('resources').action('new')(7, 'name with space', {params:data.params});
+        assert.equal(requests[8].url, 'http://example.test' + data.action_path); requests[8].respond(data.result);
+        assert.equal((await invoked).value.marker, 'DOC_SUCCESS');
+        assert.equal(requests.length, 9);
+      }
+      check().catch(error => {console.error(error); process.exitCode = 1;});
+    JS
+    helper = File.expand_path('../../../../clients/js/test/helpers/async_bundle.cjs', __dir__)
+    output, status = Open3.capture2e('node', '-e', script, helper, stdin_data: JSON.generate(data))
+    expect(status).to be_success, output
+  end
+end

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