import { readdirSync, readFileSync } from 'node:fs' import { basename, join, resolve } from 'node:path' import { fileURLToPath } from 'node:url' import type { Plugin } from 'vite' import { checkKeys, LABELS, parsePage, parseRenamedKeys, type ConfigKey, type RenamedKey } from './configSchema' /* The Node half of the config schema: reads the reference pages and the default config files from disk, and fails the docs build when they disagree. The parsing and the checks themselves are in configSchema.ts. */ const DOCS_CONFIG_DIR = fileURLToPath(new URL('../config/', import.meta.url)) const REPO_ROOT = fileURLToPath(new URL('../../', import.meta.url)) /** The default config files, as repo paths. Both containers can share one config, so they are checked as one. */ const DEFAULTS_FILES = ['app/config.json', 'upload-app/config.json'] /** * Read every page in docs/config and both default config files, and check * them against each other. Returns `checkKeys`' keys, the renamed keys from * config/upgrading.md, and every problem, the pages' own format problems * first. A renamed key whose current name no page documents is a problem too, * and so is a label in `LABELS` for a key no page documents. */ export function readConfigSchema (): { keys: ConfigKey[], renamed: RenamedKey[], problems: string[] } { const keys: ConfigKey[] = [] const problems: string[] = [] for (const file of readdirSync(DOCS_CONFIG_DIR).filter(name => name.endsWith('.md')).sort()) { const page = parsePage(readFileSync(join(DOCS_CONFIG_DIR, file), 'utf8'), '/config/' + basename(file, '.md')) keys.push(...page.keys) problems.push(...page.problems) } const files = DEFAULTS_FILES.map(name => ({ name, config: JSON.parse(readFileSync(join(REPO_ROOT, name), 'utf8')) })) const checked = checkKeys(keys, files) problems.push(...checked.problems) const renamed = parseRenamedKeys(readFileSync(join(DOCS_CONFIG_DIR, 'upgrading.md'), 'utf8')) const documented = new Set(checked.keys.map(key => key.path)) for (const { from, to } of renamed) { if (!documented.has(to)) problems.push(`docs/config/upgrading.md: \`${from}\` is renamed to \`${to}\`, which no page documents`) } for (const path of Object.keys(LABELS)) { if (!documented.has(path)) problems.push(`docs/.vitepress/configSchema.ts: LABELS has a label for \`${path}\`, which no page documents`) } return { keys: checked.keys, renamed, problems } } /** The check's problems as one message, or undefined when there are none. */ function problemsMessage (): string | undefined { const { problems } = readConfigSchema() if (problems.length === 0) return undefined return 'The config reference pages (docs/config) and the default config files disagree. ' + 'See "Config reference pages" in docs/README.md.\n' + problems.map(problem => ' - ' + problem).join('\n') } /** * Fails `vitepress build` when the config reference pages and the default * config files disagree, so a mismatch never deploys. `vitepress dev` only * warns, at start and again when a page or a default config file changes, so * a half-edited page doesn't stop the server. */ export function configCheckPlugin (): Plugin { const repoFiles = DEFAULTS_FILES.map(name => join(REPO_ROOT, name)) const isChecked = (file: string) => repoFiles.includes(resolve(file)) || (resolve(file).startsWith(DOCS_CONFIG_DIR) && file.endsWith('.md')) let isBuild = false return { name: 'ipp-config-check', configResolved (config) { isBuild = config.command === 'build' }, buildStart () { const message = problemsMessage() if (message && isBuild) this.error(message) else if (message) this.warn(message) }, configureServer (server) { // Outside the docs folder, so Vite doesn't watch them unless told to server.watcher.add(repoFiles) }, handleHotUpdate ({ file, server }) { if (!isChecked(file)) return const message = problemsMessage() if (message) server.config.logger.warn(message) } } }