From 19e10337b82b55004b720971349e0a5a235d8763 Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Thu, 8 Oct 2026 21:52:34 +1300 Subject: [PATCH] Check the config reference pages against config.json when the docs build --- .github/workflows/docs.yaml | 3 + CONTRIBUTING.md | 8 +- docs/.vitepress/config.ts | 5 + docs/.vitepress/configSchema.ts | 354 ++++++++++++++++++++++++++++++++ docs/README.md | 43 +++- docs/config/gallery.md | 4 + docs/config/ipp-options.md | 6 +- docs/config/lightbox.md | 4 + docs/config/metadata.md | 54 ++--- docs/config/upload-service.md | 4 + docs/tests/configSchema.test.ts | 204 ++++++++++++++++++ package.json | 2 +- 12 files changed, 656 insertions(+), 35 deletions(-) create mode 100644 docs/.vitepress/configSchema.ts create mode 100644 docs/tests/configSchema.test.ts diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 2d7251e..8eac064 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -8,6 +8,9 @@ on: paths: - 'docs/**' - '.github/workflows/docs.yaml' + # The build checks the config reference pages against these, so a changed default fails here + - 'app/config.json' + - 'upload-app/config.json' schedule: # Weekly rebuild, so the navbar's star count stays current - cron: '0 3 * * 1' diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fb4e58c..5a432ec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -148,7 +148,7 @@ At the repo root: ```bash npm run build # core, then IPP's server and client; output to dist/ and app/public/js/ -npm test # vitest run in every workspace (unit tests on pure functions) +npm test # vitest run in every workspace, then the docs config check npm run lint # ESLint over every workspace npm run bump -- 4.0.1 # set the version in every workspace manifest and the lockfile ``` @@ -162,13 +162,13 @@ npm run test:watch # vitest in watch mode npm run test:container # build a podman image and run it locally ``` -`npm test` runs the pure-function unit tests in `shared/tests/`, `app/tests/` and `upload-app/tests/`. The apps' tests import `@ipp/core` from its source, so they need no build. Add tests as you touch a pure-function area, and for any new pure logic you introduce. Skip HTTP plumbing. +`npm test` runs the pure-function unit tests in `shared/tests/`, `app/tests/` and `upload-app/tests/`, then `docs/tests/`, which checks the config reference pages against both `config.json` files. The apps' tests import `@ipp/core` from its source, so they need no build. Add tests as you touch a pure-function area, and for any new pure logic you introduce. Skip HTTP plumbing. Beyond unit tests, exercise the gallery end-to-end against a real Immich instance: happy path plus failure paths (expired share, trashed asset, password protection, very large albums, video range requests). ## Conventions for adding code -**Configuration.** New options go in `app/config.json` under the appropriate `ipp.*` namespace, read via `getConfigOption`, and documented on the page for their group under `docs/config/` (see `docs/README.md` for the conventions). Prefer a group toggle plus per-field overrides over a single flat boolean when several related toggles cluster, following the `ipp.showMetadata` pattern. Rename a key only in a major version: the old name simply stops being read (no compatibility shim), and the rename gets a row in Renamed config keys (`docs/config/upgrading.md`) plus a line in that release's upgrade notes. +**Configuration.** New options go in `app/config.json` under the appropriate `ipp.*` namespace, read via `getConfigOption`, and documented on the page for their group under `docs/config/` (see `docs/README.md` for the conventions). `npm test` and the docs build fail until the page matches. Prefer a group toggle plus per-field overrides over a single flat boolean when several related toggles cluster, following the `ipp.showMetadata` pattern. Rename a key only in a major version: the old name simply stops being read (no compatibility shim), and the rename gets a row in Renamed config keys (`docs/config/upgrading.md`) plus a line in that release's upgrade notes. **Privacy of responses.** Always return 404 for invalid or upstream-failed requests. Use `respondToInvalidRequest` from `@ipp/core` rather than crafting ad-hoc error responses; it calls IPP's `invalidRequestHandler`, which index.ts registers at startup. Do not surface Immich status codes or error bodies to the client. @@ -190,7 +190,7 @@ Where to put a new function: ask what category of thing it is, not where it gets ## Documentation -User-facing documentation is the VitePress site in `docs/`, published at https://docs.ipp.nz. Read `docs/README.md` before adding or moving a page: it sets out the four sidebar groups (Getting started, Configuration, Guides, Troubleshooting - one per kind of content in the Diátaxis sense), where each kind of new material belongs, and the page conventions. Run `npm run build` inside `docs/` before pushing; the build fails on dead internal links. +User-facing documentation is the VitePress site in `docs/`, published at https://docs.ipp.nz. Read `docs/README.md` before adding or moving a page: it sets out the four sidebar groups (Getting started, Configuration, Guides, Troubleshooting - one per kind of content in the Diátaxis sense), where each kind of new material belongs, and the page conventions. Run `npm run build` inside `docs/` before pushing; the build fails on dead internal links and on a config reference page that disagrees with `config.json`. The root `README.md` is a front door only: pitch, demo, quick start and links. New content goes on the site. diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 6e11b09..91321f1 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -1,4 +1,5 @@ import { defineConfigWithTheme, type DefaultTheme } from 'vitepress' +import { configSchemaPlugin } from './configSchema' const REPO_URL = 'https://github.com/alangrainger/immich-public-proxy' @@ -43,6 +44,10 @@ export default async () => defineConfigWithTheme({ head: [ ['link', { rel: 'icon', href: '/ipp.svg' }] ], + vite: { + // Fails the build when the config reference pages and the default config files disagree + plugins: [configSchemaPlugin()] + }, themeConfig: { logo: '/ipp.svg', stars: await fetchStars(), diff --git a/docs/.vitepress/configSchema.ts b/docs/.vitepress/configSchema.ts new file mode 100644 index 0000000..dfabfc4 --- /dev/null +++ b/docs/.vitepress/configSchema.ts @@ -0,0 +1,354 @@ +import { readdirSync, readFileSync } from 'node:fs' +import { basename, join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { isDeepStrictEqual } from 'node:util' +import type { Plugin } from 'vite' + +/* + Reads the config reference pages (docs/config/*.md) into a schema and checks + them against the default config files, both ways. The page format this + parser accepts is the contract in docs/README.md, "Config reference pages"; + change the two together. +*/ + +/** Whether a config.json value is a plain JSON object (not an array or null). */ +function isObject (value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value) +} + +/** The types a `**Type:**` line can name, each with the check its default must pass. */ +const TYPE_CHECKS = { + bool: (value: unknown) => typeof value === 'boolean', + int: (value: unknown) => Number.isInteger(value), + string: (value: unknown) => typeof value === 'string', + object: isObject, + 'bool or string': (value: unknown) => typeof value === 'boolean' || typeof value === 'string', + various: () => true +} + +export type ConfigType = keyof typeof TYPE_CHECKS + +/** One allowed value of a key, from its enum list. */ +export interface ConfigValue { + value: unknown + /** The item's text after the value, as markdown. */ + description: string +} + +/** One documented config key. */ +export interface ConfigKey { + /** The full dotted path, e.g. `ipp.gallery.showTitle`. */ + path: string + type: ConfigType + /** Absent only for an object key whose page gives none (a group or a free-form object). */ + default?: unknown + /** The allowed values, when the section has an enum list. */ + values?: ConfigValue[] + /** The section's first paragraph, or the table row's description, as markdown. */ + description: string + /** The site path of the page, e.g. `/config/gallery`. */ + page: string + /** The anchor of the key's section on that page. */ + anchor: string +} + +/** A default config file, named by its repo path for messages. */ +export interface DefaultsFile { + name: string + config: Record +} + +/** The markdown structures the contract is made of. Everything else is `other`. */ +type Block = + | { kind: 'heading', level: number, text: string } + | { kind: 'paragraph', text: string } + | { kind: 'list', items: string[] } + | { kind: 'table', rows: string[][] } + | { kind: 'other' } + +/** + * Split a page body into blocks. Blocks are separated by blank lines; + * code fences and callouts become `other`, so a `##` or a list inside + * them is never mistaken for part of the contract. + */ +function toBlocks (markdown: string): Block[] { + const lines = markdown.split('\n') + const blocks: Block[] = [] + for (let i = 0; i < lines.length; i++) { + const line = lines[i] + if (line.trim() === '') continue + if (line.trimStart().startsWith('```')) { + while (++i < lines.length && !lines[i].trimStart().startsWith('```')); + blocks.push({ kind: 'other' }) + continue + } + const heading = /^(#{1,6})\s+(.*)$/.exec(line) + if (heading) { + blocks.push({ kind: 'heading', level: heading[1].length, text: heading[2].trim() }) + continue + } + const group = [line] + while (i + 1 < lines.length && lines[i + 1].trim() !== '' && !/^(#{1,6}\s|\s*```)/.test(lines[i + 1])) { + group.push(lines[++i]) + } + const previous = blocks[blocks.length - 1] + if (line.startsWith('|')) { + const rows = group.filter(row => !/^\|[\s:|-]+\|$/.test(row.trim())) + blocks.push({ kind: 'table', rows: rows.map(row => row.trim().slice(1, -1).split('|').map(cell => cell.trim())) }) + } else if (line.startsWith('- ')) { + const items: string[] = [] + for (const itemLine of group) { + if (itemLine.startsWith('- ')) items.push(itemLine.slice(2).trim()) + else items[items.length - 1] += ' ' + itemLine.trim() + } + // A blank line between items doesn't end a markdown list + if (previous?.kind === 'list') previous.items.push(...items) + else blocks.push({ kind: 'list', items }) + } else if (line.startsWith('>')) { + blocks.push({ kind: 'other' }) + } else { + blocks.push({ kind: 'paragraph', text: group.map(text => text.trim()).join(' ') }) + } + } + return blocks +} + +/** The anchor VitePress gives a heading, under the docs/README.md rule for link-target headings. */ +function toAnchor (heading: string): string { + return heading.replace(/`/g, '').trim().toLowerCase().replace(/\s+/g, '-') +} + +/** JSON.parse without the throw, for values written on a page. */ +function parseLiteral (text: string): { ok: true, value: unknown } | { ok: false } { + try { + return { ok: true, value: JSON.parse(text) } + } catch { + return { ok: false } + } +} + +/** Whether a type name, backticks removed, is one the contract knows. */ +function isConfigType (type: string): type is ConfigType { + return Object.hasOwn(TYPE_CHECKS, type) +} + +/** + * Parse one reference page into the keys it documents. A page without a + * `prefix` in its frontmatter documents none. `page` is its site path, used + * in the keys and in problems. + */ +export function parsePage (markdown: string, page: string): { keys: ConfigKey[], problems: string[] } { + const keys: ConfigKey[] = [] + const problems: string[] = [] + const frontmatter = /^---\n([\s\S]*?)\n---\n/.exec(markdown) + const prefix = /^prefix:\s*(\S+)\s*$/m.exec(frontmatter?.[1] ?? '')?.[1] + if (!frontmatter || !prefix) return { keys, problems } + const where = 'docs' + page + '.md' + + const blocks = toBlocks(markdown.slice(frontmatter[0].length)) + for (let i = 0; i < blocks.length; i++) { + const heading = blocks[i] + if (heading.kind !== 'heading' || heading.level < 2 || heading.level > 3) continue + let end = i + 1 + while (end < blocks.length && blocks[end].kind !== 'heading') end++ + const section = blocks.slice(i + 1, end) + const anchor = toAnchor(heading.text) + const first = section[0] + if (first?.kind !== 'paragraph') continue + + const key = /^`([^`]+)`$/.exec(heading.text)?.[1] + if (key && first.text.startsWith('**Type:**')) { + const path = prefix + '.' + key + const typeLine = /^\*\*Type:\*\* (.+?)(?: · \*\*Default:\*\* `(.*)`)?$/.exec(first.text) + const type = typeLine?.[1].replace(/`/g, '') + if (!typeLine || !type || !isConfigType(type)) { + problems.push(`${where}: the Type line of \`${path}\` has an unknown type or does not match the contract: ${first.text}`) + continue + } + const entry: ConfigKey = { path, type, description: '', page, anchor } + if (typeLine[2] !== undefined) { + const parsed = parseLiteral(typeLine[2]) + if (parsed.ok) entry.default = parsed.value + else problems.push(`${where}: the default of \`${path}\` is not JSON: ${typeLine[2]}`) + } + const description = section[1] + if (description?.kind === 'paragraph') entry.description = description.text + else problems.push(`${where}: \`${path}\` has no description paragraph after its Type line`) + const list = section[2] + if (description?.kind === 'paragraph' && list?.kind === 'list' && list.items.every(item => item.startsWith('`'))) { + entry.values = [] + for (const item of list.items) { + const [, literal, text] = /^`([^`]*)`\s*(?:-\s*)?(.*)$/.exec(item) ?? [] + const parsed = parseLiteral(literal ?? '') + if (parsed.ok) entry.values.push({ value: parsed.value, description: text ?? '' }) + else problems.push(`${where}: an allowed value of \`${path}\` is not JSON: ${item}`) + } + } + keys.push(entry) + continue + } + + const under = /^Under `([^`]+)`\./.exec(first.text)?.[1] + const table = section.find(block => block.kind === 'table') + if (under && table?.kind === 'table') { + if (under !== prefix && !under.startsWith(prefix + '.')) { + problems.push(`${where}: \`${under}\` in "${heading.text}" is not under the page prefix \`${prefix}\``) + continue + } + const [header, ...rows] = table.rows + const column = (name: string) => header.indexOf(name) + const columns = { option: column('Option'), type: column('Type'), default: column('Default'), description: column('Description') } + if (Object.values(columns).includes(-1)) { + problems.push(`${where}: the table in "${heading.text}" needs Option, Type, Default and Description columns`) + continue + } + for (const row of rows) { + const path = under + '.' + row[columns.option].replace(/`/g, '') + const type = row[columns.type].replace(/`/g, '') + const parsed = parseLiteral(row[columns.default].replace(/`/g, '')) + if (!isConfigType(type)) problems.push(`${where}: \`${path}\` has an unknown type: ${row[columns.type]}`) + else if (!parsed.ok) problems.push(`${where}: the default of \`${path}\` is not JSON: ${row[columns.default]}`) + else keys.push({ path, type, default: parsed.value, description: row[columns.description], page, anchor }) + } + } + } + return { keys, problems } +} + +/** + * Every node of a config file by dotted path, objects included, so that + * both a leaf and a group can be looked up. + */ +function flatten (config: Record, prefix = ''): Map { + const nodes = new Map() + for (const [name, value] of Object.entries(config)) { + const path = prefix + name + nodes.set(path, value) + if (isObject(value)) for (const [child, childValue] of flatten(value, path + '.')) nodes.set(child, childValue) + } + return nodes +} + +/** + * Compare the documented keys with the default config files, both ways. + * Returns the keys a config can set (group keys dropped, and a free-form + * object without a default on its page given the one from its file) and one + * line per problem; no problems means the pages and files agree. + */ +export function checkKeys (keys: ConfigKey[], files: DefaultsFile[]): { keys: ConfigKey[], problems: string[] } { + const problems: string[] = [] + const where = (key: ConfigKey) => `docs${key.page}.md` + const json = (value: unknown) => JSON.stringify(value) + + // Every config node, and the file it was first found in + const nodes = new Map() + for (const file of files) { + for (const [path, value] of flatten(file.config)) { + const seen = nodes.get(path) + if (!seen) nodes.set(path, { value, file: file.name }) + else if (!isObject(seen.value) && !isDeepStrictEqual(seen.value, value)) { + problems.push(`\`${path}\` is ${json(seen.value)} in ${seen.file} but ${json(value)} in ${file.name}`) + } + } + } + + const documented = new Map() + for (const key of keys) { + const twin = documented.get(key.path) + if (twin) problems.push(`\`${key.path}\` is documented twice, in ${where(twin)} and ${where(key)}`) + else documented.set(key.path, key) + } + // An object key with keys documented under it is a group; one without is free-form + const isGroup = (key: ConfigKey) => key.type === 'object' && keys.some(other => other.path.startsWith(key.path + '.')) + const isFreeForm = (key: ConfigKey) => key.type === 'object' && !isGroup(key) + + const fields: ConfigKey[] = [] + for (const key of documented.values()) { + const node = nodes.get(key.path) + if (!node) { + problems.push(`\`${key.path}\` is documented in ${where(key)} but is in neither ${files.map(file => file.name).join(' nor ')}`) + continue + } + if (!TYPE_CHECKS[key.type](node.value)) { + problems.push(`\`${key.path}\` is documented as \`${key.type}\` in ${where(key)} but is ${json(node.value)} in ${node.file}`) + continue + } + if (isGroup(key)) continue + if (key.default === undefined) { + if (!isFreeForm(key)) problems.push(`\`${key.path}\` has no default in ${where(key)}`) + } else if (!isDeepStrictEqual(key.default, node.value)) { + problems.push(`\`${key.path}\` defaults to ${json(key.default)} in ${where(key)} but to ${json(node.value)} in ${node.file}`) + } + if (key.values && !key.values.some(allowed => isDeepStrictEqual(allowed.value, node.value))) { + problems.push(`the allowed values of \`${key.path}\` in ${where(key)} do not include its default, ${json(node.value)}`) + } + for (const allowed of key.values ?? []) { + if (!TYPE_CHECKS[key.type](allowed.value)) { + problems.push(`the allowed value ${json(allowed.value)} of \`${key.path}\` in ${where(key)} is not a \`${key.type}\``) + } + } + fields.push(key.default === undefined ? { ...key, default: node.value } : key) + } + + // The other direction: every leaf in the files is documented itself, or sits inside a free-form object + const covered = (path: string) => { + if (documented.has(path)) return true + const parts = path.split('.') + for (let length = parts.length - 1; length > 0; length--) { + const ancestor = documented.get(parts.slice(0, length).join('.')) + if (ancestor && isFreeForm(ancestor)) return true + } + return false + } + for (const [path, node] of nodes) { + const isLeaf = !isObject(node.value) || Object.keys(node.value).length === 0 + if (isLeaf && !covered(path)) problems.push(`\`${path}\` in ${node.file} is not documented on any page in docs/config`) + } + return { keys: fields, problems } +} + +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 and problems, with the + * pages' own format problems first. + */ +export function readConfigSchema (): { keys: ConfigKey[], 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) + return { keys: checked.keys, problems: [...problems, ...checked.problems] } +} + +/** + * Fails `vitepress build` when the config reference pages and the default + * config files disagree, so a mismatch never deploys. `vitepress dev` only + * warns, so a half-edited page doesn't stop the server. + */ +export function configSchemaPlugin (): Plugin { + let isBuild = false + return { + name: 'ipp-config-schema', + configResolved (config) { + isBuild = config.command === 'build' + }, + buildStart () { + const { problems } = readConfigSchema() + if (problems.length === 0) return + const message = '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') + if (isBuild) this.error(message) + else this.warn(message) + } + } +} diff --git a/docs/README.md b/docs/README.md index 9bf3e4f..9452dbd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,6 +10,7 @@ Read it before adding or moving a page. - [Structure](#structure) - [Where new content goes](#where-new-content-goes) - [Page conventions](#page-conventions) +- [Config reference pages](#config-reference-pages) - [The README](#the-readme) ## Working on the site @@ -18,7 +19,7 @@ Read it before adding or moving a page. cd docs npm install npm run dev # live preview -npm run build # fails on dead internal links; run it before pushing +npm run build # fails on dead links and config pages that disagree with config.json; run it before pushing ``` The navbar's star count is fetched from the GitHub API when the site builds (`fetchStars` in `.vitepress/config.ts`) @@ -30,8 +31,9 @@ Static files (images, favicon) live in `public/` and are referenced by absolute `public/CNAME` holds the custom domain; it is copied to the root of the build and must stay there. Publishing is automatic. Any push to `main` that touches `docs/` runs the `docs.yaml` workflow, which builds the -site and deploys it to GitHub Pages at [docs.ipp.nz](https://docs.ipp.nz). A dead link fails the build, so the -workflow fails and the live site stays on the previous version. Run `npm run build` yourself before pushing rather +site and deploys it to GitHub Pages at [docs.ipp.nz](https://docs.ipp.nz). A dead link, or a config page that +disagrees with `config.json` ([Config reference pages](#config-reference-pages)), fails the build, so the workflow +fails and the live site stays on the previous version. Run `npm run build` yourself before pushing rather than finding out from a red tick. ## Structure @@ -77,9 +79,42 @@ started because it is what people read first, not because it is a tutorial. If e - Code fences are tagged `yaml`, `json` or `bash`. Caddyfiles use a plain fence; there is no highlighter for them. - Images are `…` with real dimensions so the page does not shift while loading. -- Types and defaults come from `app/config.json` and the code. Check, don't guess. +- Types and defaults come from `app/config.json` and `upload-app/config.json`. The build checks them; see + [Config reference pages](#config-reference-pages). - British English, hyphens rather than dashes, and "IPP" after the first "Immich Public Proxy" on a page. +## Config reference pages + +The pages in `config/` are the only description of the config keys, so the build checks them against +`app/config.json` and `upload-app/config.json`, both ways (`.vitepress/configSchema.ts`). A disagreement fails +`npm run build`, and `npm run dev` prints it as a warning. `npm test` at the repo root runs the same check without +building the site (`tests/configSchema.test.ts`). The check fails when: + +- a key in either file is not documented, or is documented twice; +- a documented key is in neither file; +- a documented type or default differs from the file, or the allowed values leave out the default; +- a key in both files has a different default in each. + +For the same reason the docs workflow also runs on a change to either `config.json`: a key or default changed on +`main` redeploys the site, and the deploy fails if the page was not updated in the same push. + +The check reads only this format: + +- **Prefix.** A reference page names its dotted prefix in frontmatter: `prefix: ipp.gallery`. Pages without one are + not read, so a key documented on such a page counts as undocumented. +- **Key section.** A `##` or `###` heading that is one inline-code key, such as `` ## `showTitle` ``, whose first + paragraph is the Type line. The key's path is the prefix plus the heading. A heading followed by anything else is + prose: `## Example` and the upload page's `` ### `PUBLIC_BASE_URL` `` are skipped. +- **Type line.** `` **Type:** `bool` · **Default:** `false` ``, on its own. The type is `bool`, `int`, `string`, + `object`, `` `bool` or `string` ``, or `various` (any JSON value), and the default is JSON. Leave the default out + only on an object key: a group whose keys are documented on their own page (`gallery` on General options), or a + free-form object such as `responseHeaders`, whose default is taken from `config.json`. +- **Description.** The paragraph after the Type line. It is the key's summary, so it should make sense on its own. +- **Allowed values.** A bullet list directly after the description whose every item starts with an inline-code JSON + value: `` - `"original"` - the full-resolution original file ``. Any other list is prose. +- **Flag tables.** A section whose first paragraph starts ``Under `ipp.showMetadata.exif`.`` and that has a table + with `Option`, `Type`, `Default` and `Description` columns documents one key per row, as on the Metadata page. + ## The README `README.md` at the repo root is the front door, not a second copy of the site: pitch, demo, screenshot, quick start diff --git a/docs/config/gallery.md b/docs/config/gallery.md index 19da3ca..695b0d0 100644 --- a/docs/config/gallery.md +++ b/docs/config/gallery.md @@ -1,3 +1,7 @@ +--- +prefix: ipp.gallery +--- + # Gallery Options that control how the gallery page is rendered. Configured under `ipp.gallery`. diff --git a/docs/config/ipp-options.md b/docs/config/ipp-options.md index 540d245..163dbeb 100644 --- a/docs/config/ipp-options.md +++ b/docs/config/ipp-options.md @@ -1,3 +1,7 @@ +--- +prefix: ipp +--- + # General options Top-level options under `ipp.*` that don't belong to the [Gallery](/config/gallery), [Lightbox](/config/lightbox) or [Metadata](/config/metadata) groups. @@ -174,6 +178,6 @@ Description / EXIF / location reveal controls. See [Metadata](/config/metadata). ## `customInvalidResponse` -**Type:** various +**Type:** `various` · **Default:** `false` Send a custom response instead of the default 404. See [Error responses](/config/error-responses). diff --git a/docs/config/lightbox.md b/docs/config/lightbox.md index bd1e708..aaa7d98 100644 --- a/docs/config/lightbox.md +++ b/docs/config/lightbox.md @@ -1,3 +1,7 @@ +--- +prefix: ipp.lightbox +--- + # Lightbox The gallery's lightbox is powered by [PhotoSwipe](https://photoswipe.com/). Configured under `ipp.lightbox`. diff --git a/docs/config/metadata.md b/docs/config/metadata.md index d9f1fa3..b47c45a 100644 --- a/docs/config/metadata.md +++ b/docs/config/metadata.md @@ -1,3 +1,7 @@ +--- +prefix: ipp.showMetadata +--- + # Metadata Configured under `ipp.showMetadata`. The lightbox includes a slide-in info sidebar (toggle with the **i** key or the info button in the toolbar) that surfaces whatever metadata you opt into here. @@ -46,10 +50,10 @@ The info sidebar and its toolbar button only appear when at least one field is t Under `ipp.showMetadata.description`. -| Option | Type | Description | -|-----------|--------|-------------------------------------------------------------| -| `caption` | `bool` | Show the description below the photo as a lightbox caption. | -| `sidebar` | `bool` | Show the description at the top of the info sidebar. | +| Option | Type | Default | Description | +|-----------|--------|---------|-------------------------------------------------------------| +| `caption` | `bool` | `false` | Show the description below the photo as a lightbox caption. | +| `sidebar` | `bool` | `false` | Show the description at the top of the info sidebar. | Set both to show in both places; set neither and the description is not included at all. @@ -57,29 +61,29 @@ Set both to show in both places; set neither and the description is not included Under `ipp.showMetadata.exif`. Every flag defaults to `false`. -| Option | Type | Description | -|--------------------|--------|------------------------------------------------------------------------------------------------------------------| -| `dateTimeOriginal` | `bool` | Show the date the photo was taken (per EXIF), in the photographer's local time - matching Immich's own sidebar. | -| `timeZone` | `bool` | Show and use the photo's timezone when formatting the date. Only applies when `dateTimeOriginal` is also enabled. | -| `fileName` | `bool` | Show the original filename. | -| `dimensions` | `bool` | Show width x height and megapixel count. | -| `fileSize` | `bool` | Show the file size. | -| `make` | `bool` | Camera manufacturer (e.g. "Canon"). | -| `model` | `bool` | Camera model (e.g. "EOS R5"). | -| `lensModel` | `bool` | Lens model. | -| `exposureTime` | `bool` | Shutter speed (e.g. "1/200"). | -| `iso` | `bool` | ISO sensitivity. | -| `fNumber` | `bool` | Aperture f-number. | -| `focalLength` | `bool` | Focal length in millimetres. | +| Option | Type | Default | Description | +|--------------------|--------|---------|-------------------------------------------------------------------------------------------------------------------| +| `dateTimeOriginal` | `bool` | `false` | Show the date the photo was taken (per EXIF), in the photographer's local time - matching Immich's own sidebar. | +| `timeZone` | `bool` | `false` | Show and use the photo's timezone when formatting the date. Only applies when `dateTimeOriginal` is also enabled. | +| `fileName` | `bool` | `false` | Show the original filename. | +| `dimensions` | `bool` | `false` | Show width x height and megapixel count. | +| `fileSize` | `bool` | `false` | Show the file size. | +| `make` | `bool` | `false` | Camera manufacturer (e.g. "Canon"). | +| `model` | `bool` | `false` | Camera model (e.g. "EOS R5"). | +| `lensModel` | `bool` | `false` | Lens model. | +| `exposureTime` | `bool` | `false` | Shutter speed (e.g. "1/200"). | +| `iso` | `bool` | `false` | ISO sensitivity. | +| `fNumber` | `bool` | `false` | Aperture f-number. | +| `focalLength` | `bool` | `false` | Focal length in millimetres. | ## Location group Under `ipp.showMetadata.location`. Every flag defaults to `false`, except `webLink` which defaults to `true`. -| Option | Type | Description | -|-----------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `city` | `bool` | Show city. | -| `state` | `bool` | Show state / region. | -| `country` | `bool` | Show country. | -| `gps` | `bool` | Show GPS coordinates. | -| `webLink` | `bool` | Show an "Open in OpenStreetMap" link below the coordinates. The link does not pass the share URL on to the map provider. Has no effect unless `gps` is also `true`. Default `true`. | +| Option | Type | Default | Description | +|-----------|--------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `city` | `bool` | `false` | Show city. | +| `state` | `bool` | `false` | Show state / region. | +| `country` | `bool` | `false` | Show country. | +| `gps` | `bool` | `false` | Show GPS coordinates. | +| `webLink` | `bool` | `true` | Show an "Open in OpenStreetMap" link below the coordinates. The link does not pass the share URL on to the map provider. Has no effect unless `gps` is also `true`. | diff --git a/docs/config/upload-service.md b/docs/config/upload-service.md index 4ee92c0..fb79b48 100644 --- a/docs/config/upload-service.md +++ b/docs/config/upload-service.md @@ -1,3 +1,7 @@ +--- +prefix: ipp.upload +--- + # Upload service Settings for the optional upload service, the `immich-public-proxy-upload` container, which lets visitors send photos diff --git a/docs/tests/configSchema.test.ts b/docs/tests/configSchema.test.ts new file mode 100644 index 0000000..9630c55 --- /dev/null +++ b/docs/tests/configSchema.test.ts @@ -0,0 +1,204 @@ +import { describe, it, expect } from 'vitest' +import { checkKeys, parsePage, readConfigSchema, type ConfigKey, type ConfigType } from '../.vitepress/configSchema' + +/* + The first test is the one that matters: the same check `vitepress build` + runs, against the real pages and config files. The rest pin the contract + in docs/README.md, "Config reference pages". +*/ + +describe('the config reference pages', () => { + it('match app/config.json and upload-app/config.json', () => { + expect(readConfigSchema().problems).toEqual([]) + }) +}) + +/** A reference page with the given prefix and body. */ +function page (prefix: string, body: string): string { + return `---\nprefix: ${prefix}\n---\n\n# Page\n\n${body}` +} + +describe('parsePage', () => { + it('reads a key section: type, default, description and allowed values', () => { + const { keys, problems } = parsePage(page('ipp', [ + '## `quality`', + '', + '**Type:** `string` · **Default:** `"preview"`', + '', + 'Highest quality', + 'served.', + '', + '- `"preview"` - the preview (default).', + '- `"original"` - the original', + ' file.', + '', + 'More prose.' + ].join('\n')), '/config/test') + expect(problems).toEqual([]) + expect(keys).toEqual([{ + path: 'ipp.quality', + type: 'string', + default: 'preview', + description: 'Highest quality served.', + values: [ + { value: 'preview', description: 'the preview (default).' }, + { value: 'original', description: 'the original file.' } + ], + page: '/config/test', + anchor: 'quality' + }]) + }) + + it('treats a heading without a Type line as prose', () => { + const { keys } = parsePage(page('ipp', [ + '## Example', + '', + 'Some text.', + '', + '### `PUBLIC_BASE_URL`', + '', + '**Optional**', + '', + '```md', + '## `inFence`', + '', + '**Type:** `bool` · **Default:** `false`', + '```' + ].join('\n')), '/config/test') + expect(keys).toEqual([]) + }) + + it('reads nothing from a page without a prefix', () => { + const markdown = '# Page\n\n## `key`\n\n**Type:** `bool` · **Default:** `false`\n\nText.\n' + expect(parsePage(markdown, '/config/test')).toEqual({ keys: [], problems: [] }) + }) + + it('treats a list as prose unless every item starts with an inline-code value', () => { + const { keys } = parsePage(page('ipp', [ + '## `uploadUrl`', + '', + '**Type:** `string` · **Default:** `"/upload"`', + '', + 'Where the service is.', + '', + '- **A path** means the same hostname.', + '- `""` never shows the button.' + ].join('\n')), '/config/test') + expect(keys[0].values).toBeUndefined() + }) + + it('reports an allowed value that is not JSON, and an unknown type', () => { + const { problems } = parsePage(page('ipp', [ + '## `quality`', + '', + '**Type:** `string` · **Default:** `"preview"`', + '', + 'Highest quality.', + '', + '- `preview` - unquoted.', + '', + '## `count`', + '', + '**Type:** `number` · **Default:** `1`', + '', + 'How many.' + ].join('\n')), '/config/test') + expect(problems).toHaveLength(2) + expect(problems[0]).toContain('an allowed value of `ipp.quality` is not JSON') + expect(problems[1]).toContain('the Type line of `ipp.count`') + }) + + it('reads one key per row of a flag table', () => { + const { keys, problems } = parsePage(page('ipp.showMetadata', [ + '## EXIF group', + '', + 'Under `ipp.showMetadata.exif`. Every flag defaults to `false`.', + '', + '| Option | Type | Default | Description |', + '|--------|--------|---------|-----------------|', + '| `make` | `bool` | `false` | Camera make. |', + '| `iso` | `bool` | `true` | ISO sensitivity. |' + ].join('\n')), '/config/metadata') + expect(problems).toEqual([]) + expect(keys.map(key => [key.path, key.default, key.anchor])).toEqual([ + ['ipp.showMetadata.exif.make', false, 'exif-group'], + ['ipp.showMetadata.exif.iso', true, 'exif-group'] + ]) + }) +}) + +/** A documented key with the parts `checkKeys` looks at. */ +function key (path: string, type: ConfigType, extra: Partial = {}): ConfigKey { + return { path, type, description: 'Text.', page: '/config/test', anchor: 'anchor', ...extra } +} + +const APP = 'app/config.json' +const UPLOAD = 'upload-app/config.json' + +describe('checkKeys', () => { + it('passes when every key is documented with its default, both ways', () => { + const { problems } = checkKeys( + [key('ipp.showTitle', 'bool', { default: true }), key('ipp.upload.maxFileSize', 'int', { default: 500 })], + [{ name: APP, config: { ipp: { showTitle: true } } }, { name: UPLOAD, config: { ipp: { upload: { maxFileSize: 500 } } } }] + ) + expect(problems).toEqual([]) + }) + + it('reports a key in a file that no page documents', () => { + const { problems } = checkKeys([], [{ name: APP, config: { ipp: { showTitle: true } } }]) + expect(problems).toEqual(['`ipp.showTitle` in app/config.json is not documented on any page in docs/config']) + }) + + it('reports a documented key that is in neither file', () => { + const { problems } = checkKeys([key('ipp.gone', 'bool', { default: false })], [{ name: APP, config: {} }]) + expect(problems).toEqual(['`ipp.gone` is documented in docs/config/test.md but is in neither app/config.json']) + }) + + it('reports a default, type or allowed values that disagree with the file', () => { + const { problems } = checkKeys([ + key('ipp.cacheTime', 'int', { default: 600 }), + key('ipp.uploadUrl', 'bool', { default: false }), + key('ipp.quality', 'string', { default: 'original', values: [{ value: 'preview', description: '' }] }) + ], [{ name: APP, config: { ipp: { cacheTime: 300, uploadUrl: '/upload', quality: 'original' } } }]) + expect(problems).toEqual([ + '`ipp.cacheTime` defaults to 600 in docs/config/test.md but to 300 in app/config.json', + '`ipp.uploadUrl` is documented as `bool` in docs/config/test.md but is "/upload" in app/config.json', + 'the allowed values of `ipp.quality` in docs/config/test.md do not include its default, "original"' + ]) + }) + + it('reports a key documented twice', () => { + const twice = key('ipp.allowSlugLinks', 'bool', { default: true }) + const { problems } = checkKeys([twice, twice], [{ name: APP, config: { ipp: { allowSlugLinks: true } } }]) + expect(problems).toEqual(['`ipp.allowSlugLinks` is documented twice, in docs/config/test.md and docs/config/test.md']) + }) + + it('reports a key shared by both files with a different default in each', () => { + const { problems } = checkKeys( + [key('ipp.allowSlugLinks', 'bool', { default: true })], + [{ name: APP, config: { ipp: { allowSlugLinks: true } } }, { name: UPLOAD, config: { ipp: { allowSlugLinks: false } } }] + ) + expect(problems).toEqual(['`ipp.allowSlugLinks` is true in app/config.json but false in upload-app/config.json']) + }) + + it('takes a free-form object\'s default from the file and leaves its children undocumented', () => { + const headers = { 'Cache-Control': 'no-store' } + const { keys, problems } = checkKeys([key('ipp.responseHeaders', 'object')], [{ name: APP, config: { ipp: { responseHeaders: headers } } }]) + expect(problems).toEqual([]) + expect(keys[0].default).toEqual(headers) + }) + + it('treats an object key with keys documented under it as a group, left out of the keys', () => { + const { keys, problems } = checkKeys( + [key('ipp.gallery', 'object'), key('ipp.gallery.showTitle', 'bool', { default: true })], + [{ name: APP, config: { ipp: { gallery: { showTitle: true, singleImage: false } } } }] + ) + expect(problems).toEqual(['`ipp.gallery.singleImage` in app/config.json is not documented on any page in docs/config']) + expect(keys.map(field => field.path)).toEqual(['ipp.gallery.showTitle']) + }) + + it('reports a missing default on anything but an object key', () => { + const { problems } = checkKeys([key('ipp.showTitle', 'bool')], [{ name: APP, config: { ipp: { showTitle: true } } }]) + expect(problems).toEqual(['`ipp.showTitle` has no default in docs/config/test.md']) + }) +}) diff --git a/package.json b/package.json index 96e947b..a03cfad 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,7 @@ ], "scripts": { "build": "npm run build --workspaces", - "test": "npm test --workspaces", + "test": "npm test --workspaces && vitest run --root docs", "lint": "eslint shared app upload-app --ext .ts,.tsx", "dev": "npm run dev --workspace=app", "bump": "npm version --no-git-tag-version --workspaces"