Repository navigation
Expand file tree
/
Copy pathdocs-redirects.test.ts
More file actions
98 lines (89 loc) · 3.84 KB
/
Copy pathdocs-redirects.test.ts
File metadata and controls
98 lines (89 loc) · 3.84 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
/**
* Pins the `/api-reference/` rules in `apps/docs/lib/redirects.ts` against the
* generated operation pages.
*
* Page identity is derived from the specs at build time, so a spec regeneration
* can silently invalidate the map in two directions: a redirect `source` can
* start shadowing a page that now exists (the redirect wins and hides it), and a
* `destination` can stop resolving (the redirect lands on a 404). Neither shows
* up in a build, a type-check, or any other check — nothing else in the repo
* reads docs URLs.
*
* Both directions use the same slug set, so a rule cannot shadow a hand-authored
* page (`/api-reference/getting-started`) any more than a generated one.
*
* The slug derivation mirrors `fumadocs-openapi`'s auto preset: pages are
* emitted at `<baseDir>/<slugify(tag)>/<operationId>.mdx` and `(generated)` is
* a folder group stripped from the URL — so the public URL is
* `/api-reference/<tag>/<operationId>`.
*/
import { readdirSync, readFileSync } from 'node:fs'
import path from 'node:path'
import { describe, expect, it } from 'vitest'
import { OPENAPI_SPEC_FILES } from '../../apps/docs/lib/openapi-specs'
import { DOCS_REDIRECTS } from '../../apps/docs/lib/redirects'
const ROOT = path.resolve(import.meta.dirname, '../..')
const DOCS_DIR = path.join(ROOT, 'apps/docs')
const STATIC_PAGES_DIR = path.join(DOCS_DIR, 'content/docs/api-reference')
const PREFIX = '/api-reference/'
/**
* `fumadocs-openapi`'s `methodKeys`, which is what decides whether an operation
* becomes a page. It is deliberately narrower than the OpenAPI method set —
* `options` and `trace` are not enumerated, so an operation declared under
* either produces no page and must not count as a resolvable destination here.
*/
const HTTP_METHODS = ['get', 'post', 'patch', 'delete', 'head', 'put'] as const
interface OperationObject {
operationId?: string
tags?: string[]
}
/** `fumadocs-openapi`'s default `slugify` for tag folder names. */
function slugify(value: string): string {
return value.replace(/\s+/g, '-').toLowerCase()
}
function generatedSlugs(): Set<string> {
const slugs = new Set<string>()
for (const file of OPENAPI_SPEC_FILES) {
const spec = JSON.parse(readFileSync(path.join(DOCS_DIR, file), 'utf8')) as {
paths?: Record<string, Record<string, OperationObject | undefined>>
}
for (const pathItem of Object.values(spec.paths ?? {})) {
for (const method of HTTP_METHODS) {
const operation = pathItem[method]
if (!operation?.operationId) continue
const tags = operation.tags?.length ? operation.tags : ['unknown']
for (const tag of tags) {
slugs.add(`${slugify(tag)}/${operation.operationId}`)
}
}
}
}
return slugs
}
/** Every slug a `/api-reference/` URL can resolve to: generated plus hand-authored. */
function resolvableSlugs(): Set<string> {
const slugs = generatedSlugs()
for (const entry of readdirSync(STATIC_PAGES_DIR)) {
if (entry.endsWith('.mdx')) slugs.add(path.basename(entry, '.mdx'))
}
return slugs
}
const API_REFERENCE_RULES = DOCS_REDIRECTS.filter(
(rule) => rule.source.startsWith(PREFIX) || rule.destination.startsWith(PREFIX)
)
describe('api-reference redirects', () => {
it('never shadows a page that exists', () => {
const resolvable = resolvableSlugs()
const shadowed = API_REFERENCE_RULES.map((rule) => rule.source)
.filter((source) => source.startsWith(PREFIX))
.filter((source) => resolvable.has(source.slice(PREFIX.length)))
expect(shadowed).toEqual([])
})
it('only points at pages that exist', () => {
const resolvable = resolvableSlugs()
const broken = API_REFERENCE_RULES.map((rule) => rule.destination)
.filter((destination) => destination.startsWith(PREFIX))
.filter((destination) => !resolvable.has(destination.slice(PREFIX.length)))
expect(broken).toEqual([])
})
})