haveapi 0.31.2 → 0.32.0

data/spec/documentation/search_routes_spec.rb

@@ -0,0 +1,199 @@
+require 'spec_helper'
+require 'rack/mock'
+require_relative '../../test_support/dynamic_documentation_api'
+
+module DocumentationSearchRoutesSpec
+  User = Struct.new(:login)
+
+  class Provider < HaveAPI::Authentication::Basic::Provider
+    protected
+
+    def find_user(_request, username, password)
+      User.new(username) if password == 'pass'
+    end
+  end
+end
+
+RSpec.describe HaveAPI::DocumentationSearch::Helpers do
+  api do
+    define_resource(:Widget) do
+      version 1
+      auth false
+      define_action(:Renew) do
+        http_method :post
+        route 'renew'
+        aliases ['extend']
+        authorize do |user|
+          input blacklist: [:private_ticket] unless user.login == 'admin'
+          allow
+        end
+        input(:hash) do
+          integer :lifetime, label: 'Lease duration'
+          string :private_ticket, label: 'Secret ticket', default: 'DEFAULT_SECRET'
+        end
+        output(:hash) { string :valid_to, label: 'Expiry date' }
+      end
+      define_action(:Hidden) do
+        http_method :post
+        route 'hidden'
+        authorize { |user| user.login == 'admin' ? allow : deny }
+        output(:hash) { string :private_response }
+      end
+
+      define_resource(:Child) do
+        define_action(:Show) do
+          http_method :get
+          route '{child_id}'
+          authorize { allow }
+          output(:hash) { string :name }
+        end
+      end
+    end
+  end
+  default_version 1
+  auth_chain DocumentationSearchRoutesSpec::Provider
+
+  def results
+    last_response.body.match(%r{<section data-search-results.*?</section>}m)[0]
+  end
+
+  it 'renders ordinary GET search forms on versions, resources and neutral guides without discovery for guides' do
+    app
+    server = instance_variable_get(:@api)
+    allow(server).to receive(:describe_version).and_call_original
+    get '/doc/protocol'
+    expect(last_response.body).to include('data-documentation-search method="get" action="/v1/"',
+                                          'name="page" value="resources"', 'name="q" data-search-query', 'Search API v1')
+    expect(last_response.body).to include('placeholder="Resource..."')
+    expect(server).not_to have_received(:describe_version)
+    get '/v1/?page=resources'
+    expect(last_response.body).to include('data-resource-nav', 'data-resource-link="widget"')
+    expect(last_response.body).not_to include('data-search-results', 'data-resource-filter')
+    ids = last_response.body.scan(/\bid="(docs-search-[^"]+)"/).flatten
+    expect(ids).to contain_exactly('docs-search-sidebar-query')
+    main = last_response.body.match(%r{<main[^>]*>(.*?)</main>}m)[1]
+    expect(main).not_to include('data-documentation-search', 'type="submit"')
+  end
+
+  it 'trims and escapes the query, title and results while describing exactly once' do
+    app
+    server = instance_variable_get(:@api)
+    allow(server).to receive(:describe_version).and_call_original
+    get '/v1/', page: 'resources', q: '  lease duration  '
+    expect(last_response).to be_ok
+    expect(last_response.headers['Cache-Control']).to eq('private, no-store')
+    expect(last_response.body).to include('<title>Search API v1: lease duration', 'value="lease duration"')
+    expect(results).to include('Parameter:', 'lifetime', 'Input', 'Integer')
+    expect(server).to have_received(:describe_version).once
+    get '/v1/', page: 'resources', q: '<script>evil</script>'
+    expect(last_response.body).not_to include('<script>evil</script>')
+    expect(results).to include('&lt;script&gt;evil&lt;/script&gt;', 'No matches')
+  end
+
+  it 'renders a nested resource full path and escaped ancestor context without a duplicate leaf label' do
+    app
+    server = instance_variable_get(:@api)
+    allow(server).to receive(:describe_version).and_wrap_original do |original, *arguments|
+      original.call(*arguments).tap { |help| help[:resources]['widget'][:resources]['child'][:label] = 'Child <node>' }
+    end
+    get '/v1/', page: 'resources', q: 'widget.child'
+    expect(last_response).to be_ok
+    expect(results).to include('Resource: <code>widget.child</code>', '<span>Widget · Child &lt;node&gt;</span>',
+                               'href="/v1/?resource=widget.child"', '<span>widget.child · show</span>')
+    expect(results).not_to include('Resource: <code>child</code>', '<span>child</span>', '<span>Child &lt;node&gt;</span>', '<node>')
+  end
+
+  it 'does not run query matching on unqueried pages or a query supplied to another page' do
+    allow(HaveAPI::DocumentationSearch).to receive(:new).and_call_original
+    ['/v1/', '/v1/?resource=widget', '/v1/?page=resources', '/v1/?page=resources&q=++', '/v1/?q=widget'].each do |path|
+      get path
+      expect(last_response).to be_ok
+    end
+    expect(HaveAPI::DocumentationSearch).not_to have_received(:new)
+  end
+
+  it 'rejects duplicate, bracketed, malformed UTF-8 and overlong search queries before describing' do
+    app
+    server = instance_variable_get(:@api)
+    allow(server).to receive(:describe_version).and_call_original
+    ['q=a&q=b', 'q[]=widget', 'q[x]=widget', 'q=%FF', 'q=%C0%AF', 'q=%ZZ', "q=#{'a' * 257}"].each do |query|
+      response = Rack::MockRequest.new(app).get('/v1/', 'HTTP_HOST' => 'example.test', 'QUERY_STRING' => "page=resources&#{query}")
+      expect(response.status).to eq(400), query
+    end
+    expect(server).not_to have_received(:describe_version)
+    get '/v1/', page: 'resources', q: 'ž' * 256
+    expect(last_response).to be_ok
+  end
+
+  it 'links parameter results to the exact row and keeps its owning action as a containing section' do
+    get '/v1/', page: 'resources', q: 'lifetime'
+    anchor = HaveAPI::DocumentationSearch.parameter_anchor(resource_path: ['widget'], action_name: 'renew',
+                                                           direction: :input, parameter_name: 'lifetime')
+    expect(results).to include("href=\"/v1/?resource=widget##{anchor}\"")
+    get '/v1/?resource=widget'
+    section = last_response.body.match(%r{<section data-doc-section id="root-widget-renew">(.*?)</section>}m)[1]
+    expect(section).to include("<tr id=\"#{anchor}\"")
+  end
+
+  it 'links advertised provider parameters to their actual authentication-page rows' do
+    request = Rack::MockRequest.new(DynamicDocumentationAPI.build.app)
+    response = request.get('/mount/v2/?page=resources&q=token+request+user', 'HTTP_HOST' => 'example.test')
+    expect(response.status).to eq(200)
+    anchor = HaveAPI::DocumentationSearch.parameter_anchor(resource_path: ['token'], action_name: 'request',
+                                                           direction: :input, parameter_name: 'user', authentication: :token)
+    expect(response.body).to include("href=\"/mount/v2/?page=authentication##{anchor}\"", 'Authentication: token')
+    page = request.get('/mount/v2/?page=authentication', 'HTTP_HOST' => 'example.test')
+    expect(page.body).to include("<tr id=\"#{anchor}\"")
+  end
+
+  it 'keeps result links canonical under both API and Rack mounts and leaves OPTIONS query semantics unchanged' do
+    server = HaveAPI::Server.new(get_opt(:api_module))
+    server.use_version(1)
+    server.mount('/api/')
+    response = Rack::MockRequest.new(server.app).get('/api/v1/?page=resources&q=lifetime',
+                                                     'HTTP_HOST' => 'example.test', 'SCRIPT_NAME' => '/rack')
+    expect(response.status).to eq(200)
+    expect(response.body).to include('action="/rack/api/v1/"', 'href="/rack/api/v1/?resource=widget#parameter-')
+    call_api(:options, '/v1/?page=resources&q[]=bad&q=other')
+    expect(last_response).to be_ok
+    expect(api_response[:resources]).to have_key(:widget)
+  end
+
+  context 'with OAuth documentation sessions' do
+    let(:documentation_server) do
+      HaveAPI::Server.new(self.class.const_get(:ApiModule)).tap do |api|
+        api.use_version(1)
+        api.auth_chain << DocumentationSearchRoutesSpec::Provider
+      end
+    end
+    let(:documentation_fixture) do
+      require_relative '../../test_support/documentation_oauth_fixture'
+      DocumentationOAuthFixture.configure(documentation_server, users: {
+        1 => { 'member-token' => DocumentationSearchRoutesSpec::User.new('member'),
+               'admin-token' => DocumentationSearchRoutesSpec::User.new('admin') }
+      })
+    end
+
+    before do
+      documentation_fixture
+      documentation_server.mount('/')
+      @api = documentation_server
+    end
+
+    it 'uses only cookie-user accessible parameters and actions while anonymous docs retain their full view' do
+      get "#{documentation_fixture.origin}/v1/", page: 'resources', q: 'private_ticket'
+      expect(results).to include('private_ticket')
+      header 'Cookie', documentation_fixture.header_for(documentation_server, version: 1, token: 'member-token')
+      login('admin', 'pass')
+      get "#{documentation_fixture.origin}/v1/", page: 'resources', q: 'private_ticket'
+      expect(results).not_to include('<code>private_ticket</code>', 'Secret ticket', 'DEFAULT_SECRET')
+      get "#{documentation_fixture.origin}/v1/", page: 'resources', q: 'hidden'
+      expect(results).not_to include('<code>hidden</code>', 'private_response')
+      header 'Cookie', documentation_fixture.header_for(documentation_server, version: 1, token: 'admin-token')
+      login('member', 'pass')
+      get "#{documentation_fixture.origin}/v1/", page: 'resources', q: 'private_ticket'
+      expect(results).to include('<code>private_ticket</code>')
+      expect(documentation_fixture.lookups).to eq([[1, 'member-token'], [1, 'member-token'], [1, 'admin-token']])
+    end
+  end
+end

data/spec/documentation/search_spec.rb

@@ -0,0 +1,134 @@
+require 'spec_helper'
+
+RSpec.describe HaveAPI::DocumentationSearch do
+  let(:action) do
+    { method: 'POST', path: '/v1/widgets/{id}/renew', aliases: ['extend'],
+      input: { parameters: { lifetime: { label: 'Lease duration', type: 'Integer', default: 'DEFAULT_SECRET',
+                                         validators: { include: { values: ['VALIDATOR_SECRET'] } } } } },
+      output: { parameters: { valid_to: { label: 'Expires at', type: 'Datetime' } } },
+      description: 'DESCRIPTION_SECRET', examples: [{ request: { name: 'EXAMPLE_SECRET' } }] }
+  end
+  let(:description) do
+    { resources: { widget: { actions: { renew: action }, resources: {} } },
+      authentication: { token: { resources: { token: { actions: { request: action }, resources: {} } } } } }
+  end
+  let(:presentation) { Object.new.extend(described_class::Helpers) }
+
+  def search(query, source = description)
+    index = described_class::Index.new(description: source, base_path: '/v1/', version: '1', locale: 'en', visibility: 'anonymous')
+    described_class.new(index: index.payload, query:).call
+  end
+
+  it 'uses complete resource identities and ancestor labels without changing the index' do
+    fixture = JSON.parse(File.read(File.join(__dir__, 'fixtures/search_index.json')))
+    index = fixture.fetch('index')
+    before = JSON.generate(index)
+    fixture.fetch('display_queries').each do |query|
+      results = described_class.new(index:, query: query.fetch('query')).call[:results]
+      display = results.map do |result|
+        { 'title' => "#{result[:kind].to_s.capitalize}: #{presentation.documentation_search_result_title(result)}",
+          'context' => presentation.documentation_search_result_context(result) }
+      end
+      expect(display).to eq(query.fetch('expected'))
+    end
+    expect(JSON.generate(index)).to eq(before)
+  end
+
+  it 'keeps ancestor labels within their provider and omits an identical resource context' do
+    source = { resources: { token: { label: 'Public tokens', resources: { child: { label: 'Public child' } } },
+                            same: { label: 'same' } },
+               authentication: { token: { resources: { token: { label: 'Private tokens',
+                                                                resources: { child: { label: 'Private child' } } } } } } }
+    results = search('child', source)[:results]
+    labels = results.map { |result| [result[:authentication], result[:resource_label]] }
+    expect(labels).to eq([[nil, 'Public tokens · Public child'], ['token', 'Private tokens · Private child']])
+    same = search('same', source)[:results].first
+    expect(presentation.documentation_search_result_context(same)).to eq([])
+  end
+
+  it 'uses machine segments when a compact fixture omits an ancestor record' do
+    index = { resources: [{ path: %w[parent child], label: 'Child label', search: ['child'] }], actions: [], parameters: [] }
+    result = described_class.new(index:, query: 'child').call[:results].first
+    expect(result[:resource_label]).to eq('parent · Child label')
+    expect(presentation.documentation_search_result_title(result)).to eq('parent.child')
+  end
+
+  it 'matches all case-insensitive query tokens across parent and selected metadata' do
+    result = search('WIDGET lease INTEGER')
+    expect(result[:results]).to include(include(kind: :parameter, name: 'lifetime', direction: :input,
+                                                type: 'Integer', resource_path: ['widget'], action_name: 'renew'))
+    expect(search('extend POST')[:results]).to include(include(kind: :action, name: 'renew'))
+    expect(search('/v1/widgets/{id}/renew')[:results]).to include(include(kind: :action, name: 'renew'))
+    expect(search('Expires')[:results]).to include(include(name: 'valid_to', direction: :output, type: 'Datetime'))
+  end
+
+  it 'excludes examples, defaults, validators, arbitrary prose and provider credentials' do
+    source = Marshal.load(Marshal.dump(description))
+    source[:authentication][:token][:password] = 'CREDENTIAL_SECRET'
+    %w[DEFAULT_SECRET VALIDATOR_SECRET DESCRIPTION_SECRET EXAMPLE_SECRET CREDENTIAL_SECRET].each do |query|
+      expect(search(query, source)[:results]).to eq([])
+    end
+  end
+
+  it 'ranks exact machine matches before prefixes and remaining token matches with deterministic ties' do
+    tree = %w[widget_long mywidget widget].reverse.to_h do |name|
+      [name, { actions: {}, resources: {} }]
+    end
+    source = { resources: tree }
+    expect(search('widget', source)[:results].map { |result| result[:name] }).to eq(%w[widget widget_long mywidget])
+    reverse = { resources: tree.to_a.reverse.to_h }
+    expect(search('widget', reverse)).to eq(search('widget', source))
+  end
+
+  it 'prioritizes resources, actions and parameters before match strength within each kind' do
+    source = { resources: { mywidget: { actions: {
+      widget: { input: { parameters: { widget: { type: 'String' } } } },
+      widget_long: { input: { parameters: { widget_long: { type: 'String' } } } }
+    } }, widget: { actions: {} } } }
+    results = search('widget', source)[:results]
+    expect(results.map { |result| [result[:kind], result[:name]] }).to eq([
+                                                                            [:resource, 'widget'], [:resource, 'mywidget'],
+                                                                            [:action, 'widget'], [:action, 'widget_long'],
+                                                                            [:parameter, 'widget'], [:parameter, 'widget_long']
+                                                                          ])
+  end
+
+  it 'caps returned matches at twenty and explicitly reports more without changing the source' do
+    tree = 32.times.to_h { |index| ["widget#{index}", { actions: {}, resources: {} }] }
+    source = { resources: tree }
+    before = Marshal.dump(source)
+    result = search('widget', source)
+    expect(result[:results].length).to eq(20)
+    expect(result[:more]).to be(true)
+    expect(search('widget31', source)[:more]).to be(false)
+    expect(search('absent', source)).to eq(query: 'absent', results: [], more: false)
+    expect(Marshal.dump(source)).to eq(before)
+  end
+
+  it 'returns provider-resource matches only from the supplied filtered authentication tree' do
+    results = search('token lifetime')[:results]
+    expect(results).to contain_exactly(include(kind: :parameter, authentication: 'token', resource_path: ['token'],
+                                               action_name: 'request', name: 'lifetime'))
+    expect(search('token', description.merge(authentication: {}))[:results]).to eq([])
+  end
+
+  it 'supports serialized string keys and nested resource context without reading hidden trees' do
+    source = JSON.parse(JSON.generate(description))
+    source['resources']['parent'] = { 'actions' => {}, 'resources' => { 'child' => { 'actions' => { 'renew' => action } } } }
+    expect(search('parent child duration', source)[:results]).to include(include(resource_path: %w[parent child], name: 'lifetime'))
+  end
+
+  it 'encodes every parameter anchor component unambiguously and uses it in result records' do
+    arguments = { resource_path: %w[a b-c], action_name: 'show', direction: :input, parameter_name: 'x-y' }
+    first = described_class.parameter_anchor(**arguments)
+    variations = [arguments.merge(resource_path: %w[a-b c]), arguments.merge(action_name: 'show-input'),
+                  arguments.merge(direction: :output), arguments.merge(parameter_name: 'x/y "ž"'),
+                  arguments.merge(authentication: 'token')]
+    anchors = [first] + variations.map { |value| described_class.parameter_anchor(**value) }
+    expect(anchors.uniq.length).to eq(anchors.length)
+    expect(anchors).to all(match(/\Aparameter-[0-9a-f]+\z/))
+    record = search('widget lifetime')[:results].first
+    expect(record[:anchor]).to eq(described_class.parameter_anchor(resource_path: ['widget'], action_name: 'renew',
+                                                                   direction: :input, parameter_name: 'lifetime'))
+  end
+end

data/spec/documentation/shared_pages_spec.rb

@@ -0,0 +1,240 @@
+require 'spec_helper'
+require 'rack/mock'
+
+RSpec.describe HaveAPI::SharedDocumentationHelpers do
+  api do
+    define_resource(:Widget) do
+      version 1
+      auth false
+
+      define_action(:Index, superclass: HaveAPI::Actions::Default::Index) do
+        authorize { allow }
+      end
+    end
+
+    define_resource(:OtherWidget) do
+      version 2
+      auth false
+
+      define_action(:Index, superclass: HaveAPI::Actions::Default::Index) do
+        authorize { allow }
+      end
+    end
+  end
+
+  default_version 1
+
+  def json_element(body, name)
+    JSON.parse(body.match(%r{<script[^>]*#{name}[^>]*>(.*?)</script>}m)[1])
+  end
+
+  def expect_neutral_shell(body, page)
+    expect(body).to include('data-docs', "data-page=\"#{page}\"", 'data-resource=""',
+                            'id="docs-main"', '/js/documentation.js', '/css/documentation.css',
+                            'Generated by')
+    expect(body).not_to include('/js/main.js', '/js/jquery', '/css/bootstrap', 'data-resource-nav',
+                                'data-language-select', 'data-documentation-login', 'docs-identity', 'docs-visibility-note',
+                                'class="docs-sign-in', 'class="authentication"')
+    expect(body).to include('<details data-documentation-menu>', 'data-documentation-menu-content')
+    expect(body).not_to include('data-theme-menu', 'data-account-menu')
+    expect(json_element(body, 'data-documentation-clients')).to eq([])
+    expect(json_element(body, 'data-legacy-anchors')).to eq({})
+    %w[auto light dark].each do |theme|
+      expect(body).to include("data-theme-choice=\"#{theme}\"")
+    end
+  end
+
+  it 'keeps root discovery once and renders its existing versions in the common shell' do
+    app
+    server = instance_variable_get(:@api)
+    allow(server).to receive(:describe).and_call_original
+
+    get '/'
+
+    expect(last_response).to be_ok
+    expect(last_response.headers['Cache-Control']).to eq('private, no-store')
+    expect(last_response.body).to include('<h1>API versions</h1>', 'href="/v1/"', 'href="/v2/"',
+                                          'Version 1', 'Version 2', '(default)', '<title>API versions')
+    main = last_response.body.match(%r{<main\b[^>]*>(.*?)</main>}m)[1]
+    expect(main.scan(/<h1\b/).length).to eq(1)
+    expect(main).not_to include('API description', 'Available versions:')
+    expect_neutral_shell(last_response.body, 'versions')
+    expect(server).to have_received(:describe).once
+  end
+
+  {
+    '/doc' => 'Server-side implementation',
+    '/doc/index' => 'Server-side implementation',
+    '/doc/index.md' => 'Server-side implementation',
+    '/doc/readme' => 'HaveAPI',
+    '/doc/protocol' => 'Protocol definition',
+    '/doc/protocol.md' => 'Protocol definition',
+    '/doc/create-client' => 'Client definition',
+    '/doc/create-client.md' => 'Client definition',
+    '/doc/client-examples' => 'Client examples',
+    '/doc/client-examples.md' => 'Client examples',
+    '/doc/json-schema' => 'Envelope'
+  }.each do |path, heading|
+    it "serves #{path} in the neutral shell without API discovery or cookie authentication" do
+      app
+      server = instance_variable_get(:@api)
+      allow(server).to receive(:describe).and_call_original
+      allow(server).to receive(:describe_version).and_call_original
+      allow(server.auth_chain).to receive(:authenticate).and_call_original
+
+      get path
+
+      expect(last_response).to be_ok
+      expect(last_response.headers['Content-Type']).to include('text/html')
+      expect(last_response.headers['Cache-Control']).to eq('private, no-store')
+      expect(last_response.body).to include(heading, 'aria-label="Breadcrumb"',
+                                            'href="/"', 'href="/doc"', 'href="/v1/?page=resources"')
+      expect_neutral_shell(last_response.body, 'guide')
+      breadcrumb = last_response.body.match(%r{<nav aria-label="Breadcrumb">(.*?)</nav>}m)[1]
+      expect(breadcrumb).to include('API versions', 'HaveAPI internals')
+      expect(breadcrumb.scan(/<li\b/).length).to eq(path.match?(%r{\A/doc(?:/(?:index(?:\.md)?|readme))?\z}) ? 2 : 3)
+      expect(server).not_to have_received(:describe)
+      expect(server).not_to have_received(:describe_version)
+      expect(server.auth_chain).not_to have_received(:authenticate)
+    end
+  end
+
+  it 'renders the real README for every internal landing alias with one sidebar menu' do
+    pages = %w[/doc /doc/index /doc/index.md /doc/readme].map do |path|
+      get path
+      body = last_response.body
+      main = body.match(%r{<main\b[^>]*>(.*?)</main>}m)[1]
+      expect(main).to include('<h1', '>HaveAPI</h1>', 'Server-side implementation', 'Server framework features',
+                              '<pre><code class="ruby">', 'class User &lt; ActiveRecord::Base')
+      expect(body).to include('<title>HaveAPI internals · ')
+      expect(main).not_to include('href="/doc/protocol"', 'href="/doc/client-examples"')
+      expect(main.scan('HaveAPI internals').length).to eq(1)
+      menu = body.match(%r{<nav aria-label="Shared documentation">(.*?)</nav>}m)[1]
+      expect(menu).to include('<h2><a href="/doc">HaveAPI internals</a></h2>')
+      expect(menu).not_to include('>Overview</a>')
+      expect(menu).not_to include('href="/doc/readme"')
+      %w[protocol json-schema create-client client-examples].each do |article|
+        expect(menu.scan("href=\"/doc/#{article}\"").length).to eq(1)
+      end
+      main
+    end
+    expect(pages.uniq.length).to eq(1)
+  end
+
+  it 'uses configured escaped identity or the actual host and port in neutral titles and brand' do
+    server = HaveAPI::Server.new(get_opt(:api_module))
+    server.use_version(1)
+    server.documentation_name = '<API & site>'
+    server.mount('/')
+    request = Rack::MockRequest.new(server.app)
+    %w[/ /doc /doc/protocol].each do |path|
+      response = request.get(path, 'HTTP_HOST' => 'example.test:4567')
+      expect(response.status).to eq(200)
+      expect(response.body).to include('href="/">&lt;API &amp; site&gt;</a>', ' · &lt;API &amp; site&gt;</title>')
+      expect(response.body).not_to include('<API & site>')
+    end
+    fallback = HaveAPI::Server.new(get_opt(:api_module))
+    fallback.use_version(1)
+    fallback.mount('/')
+    response = Rack::MockRequest.new(fallback.app).get('/doc/protocol', 'HTTP_HOST' => 'example.test:4567')
+    expect(response.body).to include('href="/">example.test:4567</a>', ' · example.test:4567</title>')
+  end
+
+  %w[protocol create-client json-schema].each do |name|
+    it "uses actual heading IDs for every #{name} TOC target" do
+      get "/doc/#{name}"
+      body = last_response.body
+      headings = body.scan(/<h[1-6]\b[^>]*\bid="([^"]+)"/).flatten
+      navigation = body.match(%r{<nav[^>]*data-action-nav[^>]*>(.*?)</nav>}m)[1]
+      targets = navigation.scan(/href="#([^"]+)"/).flatten
+      expect(targets).not_to be_empty
+      expect(targets - headings).to eq([])
+    end
+  end
+
+  it 'keeps semantic shared tables in keyboard-accessible overflow regions without changing their cells' do
+    get '/doc/performance'
+    tables = last_response.body.scan(%r{<table\b[^>]*>.*?</table>}m)
+    expect(tables).not_to be_empty
+    tables.each do |table|
+      expect(last_response.body).to include(%(<div class="docs-table-scroll" role="region" aria-label="Documentation table" tabindex="0">#{table}</div>))
+    end
+    expect(last_response.body).to include('<th>Measurement policy</th>')
+  end
+
+  it 'keeps missing documents and unsupported aliases at 404' do
+    %w[/doc/missing /doc/missing.md /doc/readme.md /doc/json-schema.md].each do |path|
+      get path
+      expect(last_response.status).to eq(404), path
+    end
+  end
+
+  it 'escapes version labels and links from the existing index description' do
+    app
+    server = instance_variable_get(:@api)
+    label = '<script>version</script>'
+    help = '/v1/" onclick="unsafe'
+    allow(server).to receive(:describe).and_return(versions: { label => { help: } }, default_version: label)
+    get '/'
+    expect(last_response.body).to include('Version &lt;script&gt;version&lt;/script&gt;', 'href="/v1/&quot; onclick=&quot;unsafe"')
+    expect(last_response.body).not_to include(label, 'href="/v1/" onclick="unsafe"')
+  end
+
+  it 'keeps shared and root links mounted under both the API and Rack prefixes' do
+    server = HaveAPI::Server.new(get_opt(:api_module))
+    server.use_version(1)
+    server.mount('/api/')
+    request = Rack::MockRequest.new(server.app)
+    %w[/api/ /api/doc/protocol].each do |path|
+      response = request.get(path, 'HTTP_HOST' => 'example.test', 'SCRIPT_NAME' => '/rack')
+      expect(response.status).to eq(200)
+      expect(response['Cache-Control']).to eq('private, no-store')
+      expect(response.body).to include('href="/rack/api/"', 'href="/rack/api/doc"',
+                                       'href="/rack/api/v1/"', 'href="/rack/api/v1/?page=resources"',
+                                       'src="/rack/js/documentation.js"')
+      expect(response.body).not_to include('href="/doc"', 'href="/v1/"')
+    end
+  end
+
+  it 'keeps guides anonymous and omits Account when documentation OAuth is not configured' do
+    server = HaveAPI::Server.new(get_opt(:api_module))
+    server.use_version(1)
+    server.mount('/api/')
+    allow(server).to receive(:describe).and_call_original
+    allow(server).to receive(:describe_version).and_call_original
+    allow(server.auth_chain).to receive(:authenticate).and_call_original
+    response = Rack::MockRequest.new(server.app).get('/api/doc/protocol', 'HTTP_HOST' => 'example.test')
+    expect(response.status).to eq(200)
+    expect(response.body).not_to include('aria-label="Account"')
+    expect(response.body).not_to include('data-account-menu', 'data-documentation-login', 'docs-visibility-note')
+    expect(server).not_to have_received(:describe)
+    expect(server).not_to have_received(:describe_version)
+    expect(server.auth_chain).not_to have_received(:authenticate)
+    get '/doc/protocol'
+    expect(last_response.body).not_to include('aria-label="Account"', 'data-account-menu')
+  end
+
+  context 'with documentation OAuth configured' do
+    it 'offers a neutral Account link without authenticating or describing even with a real session cookie' do
+      require_relative '../../test_support/documentation_oauth_fixture'
+      server = HaveAPI::Server.new(self.class.const_get(:ApiModule))
+      server.use_version(1)
+      user = Struct.new(:login).new('guide-user')
+      fixture = DocumentationOAuthFixture.configure(server, users: { 1 => { 'guide-token' => user } }, mount_path: '/api/')
+      server.mount('/api/')
+      allow(server).to receive(:describe).and_call_original
+      allow(server).to receive(:describe_version).and_call_original
+      allow(server.auth_chain).to receive(:authenticate).and_call_original
+      cookie = fixture.header_for(server, version: 1, token: 'guide-token')
+      response = Rack::MockRequest.new(server.app).get("#{fixture.origin}/api/doc/protocol",
+                                                       'HTTP_HOST' => URI(fixture.origin).host, 'HTTP_COOKIE' => cookie)
+      expect(response.status).to eq(200)
+      expect(response.body).to include('href="/api/v1/?page=authentication" aria-label="Account"')
+      expect(response.body).not_to include('guide-user', 'data-documentation-login', 'docs-visibility-note')
+      expect(fixture.lookups).to be_empty
+      expect(server).not_to have_received(:describe)
+      expect(server).not_to have_received(:describe_version)
+      expect(server.auth_chain).not_to have_received(:authenticate)
+    end
+  end
+end