mirror of
https://github.com/simstudioai/sim.git
synced 2026-11-22 21:28:37 +08:00
* feat(docs): rebuild documentation with the Paper design system * fix(docs): verify nested tabs and fresh-checkout CI setup * chore(docs): refresh preservation evidence against latest staging * fix(docs): align shared navigation and controls with Paper * fix(docs): share active heading across responsive outlines * fix(docs): track the final section at the end of the page * fix(docs): preserve sidebar scroll in a persistent layout * fix(docs): restore live screenshot backgrounds and framing * fix(docs): finish layout polish and clean implementation references * fix(docs): align shared dark theme and overlay states * fix(docs): remove dark borders from platform screenshots * test(docs): benchmark production navigation and image delivery in CI * fix(docs): preserve machine content and production reading contracts * fix(docs): retain readable tabs without JavaScript and verify current staging * fix(docs): expose root response schemas and generate clean-checkout types * fix(docs): resolve no-script tabs in the preflight cascade layer * perf(docs): import only the search schema constructors * fix(docs): preserve retrieval excerpts and reduce reading overhead * fix(docs): reuse in-flight intent prefetches during navigation * docs: record production readiness evidence and release requirements * docs: clarify optimizer measurement provenance * docs: preserve latest staging Search assets and compatibility evidence * fix(docs): polish responsive controls and keep search indexing current * test(docs): select the visible API example in browser checks * test(docs): execute native examples against streaming and binary responses * fix(docs): stream native API responses without buffering * test(docs): cover review regressions through public interfaces * fix(docs): preserve accessible examples and gate index publication * fix(docs): finish accessible controls and cached content validation * fix(docs): validate integration parents and report partial search failures * fix(docs): refine navigation and compact sample controls * fix(docs): isolate synchronous corpus validation from HTTP readers * fix(docs): restore Paper interaction styling and verify responsive controls * fix(docs): score each search page once per retrieval source * fix(docs): attribute benchmark metrics to their source document --------- Co-authored-by: Waleed Latif <walif6@gmail.com>
173 lines
5.3 KiB
TypeScript
173 lines
5.3 KiB
TypeScript
import { mkdir, writeFile } from 'node:fs/promises'
|
|
import { dirname } from 'node:path'
|
|
import { createLogger } from '@sim/logger'
|
|
import { getErrorMessage } from '@sim/utils/errors'
|
|
import { sleep } from '@sim/utils/helpers'
|
|
|
|
const logger = createLogger('DocsNegotiationE2E')
|
|
const origin = process.env.DOCS_E2E_BASE_URL
|
|
const reportPath = process.env.DOCS_NEGOTIATION_REPORT_PATH
|
|
if (!origin || !reportPath) {
|
|
throw new Error('DOCS_E2E_BASE_URL and DOCS_NEGOTIATION_REPORT_PATH are required')
|
|
}
|
|
const url = new URL('/introduction', origin)
|
|
if (!['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) {
|
|
throw new Error('The documentation server must use a loopback origin')
|
|
}
|
|
|
|
interface CheckResult {
|
|
name: string
|
|
status: 'passed' | 'failed'
|
|
durationMs: number
|
|
contentType?: string
|
|
vary?: string
|
|
statusCode?: number
|
|
error?: string
|
|
}
|
|
|
|
interface RepresentationCase {
|
|
name: string
|
|
accept: string
|
|
expected: 'text/html' | 'text/markdown'
|
|
method?: 'GET' | 'HEAD'
|
|
statusCode?: number
|
|
useHtmlValidator?: boolean
|
|
}
|
|
|
|
const cases: readonly RepresentationCase[] = [
|
|
{
|
|
name: 'HTML advertises its representation and router cache dimensions',
|
|
accept: 'text/html',
|
|
expected: 'text/html',
|
|
},
|
|
{
|
|
name: 'Markdown negotiates at the same URL',
|
|
accept: 'text/markdown',
|
|
expected: 'text/markdown',
|
|
},
|
|
{
|
|
name: 'HTML remains available after a Markdown request',
|
|
accept: 'text/html',
|
|
expected: 'text/html',
|
|
},
|
|
{
|
|
name: 'Higher Markdown quality wins',
|
|
accept: 'text/html;q=0.4,text/markdown;q=0.8',
|
|
expected: 'text/markdown',
|
|
},
|
|
{
|
|
name: 'Equal quality defaults to HTML',
|
|
accept: 'text/markdown;q=0.8,text/html;q=0.8',
|
|
expected: 'text/html',
|
|
},
|
|
{
|
|
name: 'Explicit Markdown rejection overrides wildcard',
|
|
accept: 'text/markdown;q=0,*/*;q=1',
|
|
expected: 'text/html',
|
|
},
|
|
{
|
|
name: 'Explicit HTML rejection permits Markdown wildcard',
|
|
accept: 'text/html;q=0,text/*;q=0.5',
|
|
expected: 'text/markdown',
|
|
},
|
|
{
|
|
name: 'HTML HEAD retains representation headers',
|
|
accept: 'text/html',
|
|
expected: 'text/html',
|
|
method: 'HEAD',
|
|
},
|
|
{
|
|
name: 'Markdown HEAD retains representation headers',
|
|
accept: 'text/markdown',
|
|
expected: 'text/markdown',
|
|
method: 'HEAD',
|
|
},
|
|
{
|
|
name: 'Matching HTML validator returns a 304 with cache dimensions',
|
|
accept: 'text/html',
|
|
expected: 'text/html',
|
|
statusCode: 304,
|
|
useHtmlValidator: true,
|
|
},
|
|
{
|
|
name: 'Conditional HTML HEAD returns a 304',
|
|
accept: 'text/html',
|
|
expected: 'text/html',
|
|
method: 'HEAD',
|
|
statusCode: 304,
|
|
useHtmlValidator: true,
|
|
},
|
|
{
|
|
name: 'An HTML validator cannot suppress the Markdown representation',
|
|
accept: 'text/markdown',
|
|
expected: 'text/markdown',
|
|
useHtmlValidator: true,
|
|
},
|
|
] as const
|
|
|
|
for (let attempt = 0; attempt < 20; attempt += 1) {
|
|
try {
|
|
const response = await fetch(url, { signal: AbortSignal.timeout(1000) })
|
|
await response.body?.cancel()
|
|
if (response.ok) break
|
|
} catch {}
|
|
await sleep(250)
|
|
}
|
|
|
|
const checks: CheckResult[] = []
|
|
let htmlValidator: string | undefined
|
|
for (const entry of cases) {
|
|
const started = performance.now()
|
|
const result: CheckResult = { name: entry.name, status: 'failed', durationMs: 0 }
|
|
try {
|
|
const headers = new Headers({ Accept: entry.accept })
|
|
if (entry.useHtmlValidator) {
|
|
if (!htmlValidator) throw new Error('HTML did not provide a cache validator')
|
|
headers.set('If-None-Match', htmlValidator)
|
|
}
|
|
const response = await fetch(url, {
|
|
method: entry.method ?? 'GET',
|
|
headers,
|
|
signal: AbortSignal.timeout(10000),
|
|
})
|
|
await response.body?.cancel()
|
|
result.statusCode = response.status
|
|
result.contentType = response.headers.get('Content-Type') ?? ''
|
|
result.vary = response.headers.get('Vary') ?? ''
|
|
const fields = result.vary.split(',').map((field) => field.trim().toLowerCase())
|
|
if (response.status !== (entry.statusCode ?? 200))
|
|
throw new Error(`Unexpected HTTP status ${response.status}`)
|
|
if (response.status !== 304 && !result.contentType.startsWith(entry.expected)) {
|
|
throw new Error(`Expected ${entry.expected}; received ${result.contentType}`)
|
|
}
|
|
if (!fields.includes('accept')) throw new Error('The response lost Vary: Accept')
|
|
if (entry.expected === 'text/html') {
|
|
if (response.status === 200) htmlValidator = response.headers.get('etag') ?? undefined
|
|
for (const field of [
|
|
'rsc',
|
|
'next-router-state-tree',
|
|
'next-router-prefetch',
|
|
'next-router-segment-prefetch',
|
|
]) {
|
|
if (!fields.includes(field)) throw new Error(`The response lost Vary: ${field}`)
|
|
}
|
|
}
|
|
if (fields.length !== new Set(fields).size) throw new Error('Vary contains duplicate fields')
|
|
result.status = 'passed'
|
|
} catch (error) {
|
|
result.error = getErrorMessage(error)
|
|
}
|
|
result.durationMs = Math.round(performance.now() - started)
|
|
checks.push(result)
|
|
}
|
|
|
|
await mkdir(dirname(reportPath), { recursive: true })
|
|
await writeFile(reportPath, `${JSON.stringify({ checks }, null, 2)}\n`)
|
|
const failures = checks.filter((check) => check.status === 'failed')
|
|
if (failures.length) {
|
|
logger.error('Documentation negotiation failed', { failures })
|
|
process.exitCode = 1
|
|
} else {
|
|
logger.info('Documentation negotiation passed', { checks: checks.length })
|
|
}
|