@redpanda-data/docs-extensions-and-macros 5.55.0 → 5.56.0

package/cli-utils/helm-commented-values.js

@@ -46,6 +46,8 @@
  * displayed default, which is otherwise `nil`.
  */
 
+const { spawnSync } = require('child_process')
+
 // Key names never contain dots or slashes: a dotted or slashed "key" in a
 // comment is prose or a URL (`# docker.redpanda.com/...:4.101.0`), and
 // treating it as a key both fabricates a path and truncates the description.
@@ -464,6 +466,31 @@ function filterEntriesBySchema (entries, schema) {
   return { accepted, rejected }
 }
 
+/**
+ * Convert Markdown to AsciiDoc with pandoc. `generate helm-spec` uses this for
+ * the helm-docs README and for each values.yaml comment it injects, so both
+ * get the same conversion. values.yaml comments are Markdown (helm-docs copies
+ * them into the README as is), so without it an injected comment's links and
+ * emphasis are published as literal Markdown.
+ *
+ * The `smart` extension is turned off on input. With it, pandoc turns straight
+ * quotes into curly ones and writes them as ``text'', which only AsciiDoc
+ * Python understood. Asciidoctor prints those backticks and apostrophes
+ * literally, so straight quotes are passed through instead.
+ *
+ * @param {string} markdown - Markdown text.
+ * @returns {string} AsciiDoc text, without a trailing newline.
+ * @throws {Error} When pandoc cannot be run or exits non-zero.
+ */
+function markdownToAsciiDoc (markdown) {
+  if (!markdown || !markdown.trim()) return markdown
+  const r = spawnSync('pandoc', ['-f', 'markdown-smart', '-t', 'asciidoc'], { input: markdown, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+  if (r.error) throw new Error(`pandoc failed: ${r.error.message}`)
+  if (r.status !== 0) throw new Error(`pandoc exited ${r.status}: ${(r.stderr || '').trim()}`)
+  if (r.stderr) process.stderr.write(r.stderr)
+  return r.stdout.replace(/\s+$/, '')
+}
+
 // Neutralize description lines that would otherwise parse as AsciiDoc
 // structure when injected at block level: section titles re-parent the
 // following sections, and an unclosed block delimiter swallows the rest of
@@ -484,11 +511,17 @@ function sanitizeDescription (text) {
  * sections and are inserted in alphabetical key order. Keys that are already
  * documented are skipped.
  *
+ * Descriptions and defaults come from values.yaml comments, which are
+ * Markdown. Pass `toAsciiDoc` (for example `markdownToAsciiDoc`) to convert
+ * them the way the rest of the document was converted. Without it, the text
+ * is inserted as is.
+ *
  * @param {string} adoc - The converted AsciiDoc document.
  * @param {Array<{path: string, description: string, default: string}>} entries
+ * @param {{toAsciiDoc?: (markdown: string) => string}} [options]
  * @returns {{doc: string, injected: string[], sectionsFound: number}}
  */
-function injectIntoAsciiDoc (adoc, entries) {
+function injectIntoAsciiDoc (adoc, entries, { toAsciiDoc = (text) => text } = {}) {
   // The label may itself contain brackets (`[storage.volume[0].name]` in the
   // connectors chart), so it is matched to end of line rather than to the
   // first closing bracket.
@@ -530,9 +563,9 @@ function injectIntoAsciiDoc (adoc, entries) {
     const section = [
       `=== link:++${urlPrefix}${entry.path}++[${entry.path}]`,
       '',
-      sanitizeDescription(entry.description),
+      sanitizeDescription(toAsciiDoc(entry.description)),
       '',
-      `*Default:* ${entry.default}`,
+      `*Default:* ${toAsciiDoc(entry.default)}`,
       '',
       '',
     ].join('\n')
@@ -562,6 +595,7 @@ module.exports = {
   parseValuesFile,
   extractCommentedValueDocs,
   injectIntoAsciiDoc,
+  markdownToAsciiDoc,
   filterEntriesBySchema,
   isPathAllowedBySchema,
   // Exported so the lint surface cannot hold its own copy. Every one of these

package/extension-utils/llms-utils.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { decode } = require('html-entities');
+
 /**
  * Shared utilities for llms.txt generation and markdown processing.
  * Used by both convert-to-markdown.js and convert-llms-to-txt.js.
@@ -115,9 +117,11 @@ const MAX_INDEX_CHARS = 45000;
  */
 const MAX_INDEX_DESCRIPTION_CHARS = 200;
 
+// Titles and descriptions arrive as converted HTML, so tags are stripped and
+// entities decoded. Decoding comes after stripping: an escaped placeholder
+// such as `&lt;name&gt;` must survive as `<name>`, not be removed as a tag.
 function oneLine(text) {
-  return String(text || '')
-    .replace(/<[^>]+>/g, '')
+  return decode(String(text || '').replace(/<[^>]+>/g, ''))
     .replace(/\s+/g, ' ')
     .trim();
 }

package/extension-utils/metadata-candidates.js

@@ -0,0 +1,304 @@
+'use strict'
+
+/**
+ * Candidate taxonomy terms: frequent, distinctive terms on a page that no
+ * concept's label or altLabel matches. `doc-tools check-metadata --suggest`
+ * lists them beside the suggestions, and `--candidates-only` aggregates them
+ * across a repository, so a person or a later model step can propose new
+ * concepts or altLabels from evidence instead of from memory.
+ *
+ * Deterministic, with no model. Two kinds of term are collected:
+ *
+ *   - Capitalized terms in prose: a run of up to four capitalized, CamelCase,
+ *     or all-caps words (Amazon S3, BigQuery, SASL), in the description and
+ *     the body outside code blocks. Titles and headings are left out because
+ *     they are title case. A single word is counted only where it does not
+ *     start a sentence, and a leading common word is dropped ("Use Amazon S3"
+ *     is "Amazon S3").
+ *   - Code identifiers: a snake_case or kebab-case name in backticks that the
+ *     page uses as a component (followed by input, output, processor, cache,
+ *     connector, and so on), or the target of an xref to a Redpanda Connect
+ *     component page. Other identifiers are configuration properties and
+ *     fields, not taxonomy values, so they are left out.
+ *
+ * A term is dropped when a taxonomy label or altLabel matches inside it, when
+ * it is in the terminology list (the style guide's word lists or the docs
+ * glossary, see loadTerminology), when every word is common English
+ * (COMMON_WORDS), or when a single word also appears in lowercase in the
+ * page's prose, which is the mark of an ordinary word that started a phrase.
+ *
+ * Each candidate has a likely facet from simple cues: a connector name or a
+ * database, format, or product cue word next to it is a technology; a
+ * multi-word title-case name with no cue is a topic (Remote Read Replicas);
+ * anything else has no facet.
+ */
+
+const fs = require('fs')
+const path = require('path')
+const { matchText, words, foldWord } = require('./metadata-suggest')
+
+// Common English and docs boilerplate words. A term made only of these is not
+// distinctive. Lowercase.
+const COMMON_WORDS = new Set(`
+a about above across add added after again against all allow also always an and another any are as at available
+back be because been before being below best between both build built but by
+can cannot change changes check choose click close come complete configure configuring connect content contents
+copy could create created current custom
+data default define delete describe description different do does doing done down during
+each edit either else enable enabled end enter even every example examples except
+false file files find first follow following for from full
+get give go good
+has have help here how however
+if important in include includes information install instead into is it its
+just
+keep know
+last learn least less let like limit limits list load local
+make many may more most move must
+name names need new next no none not note now number
+of off on once one only open option optional options or order other our out output over overview
+page part per prerequisites prerequisite previous provide
+read reference related remove replace required requirements result return run running
+same save see select set sets setting settings should show since so some specify start started step steps still
+such summary support supported
+table take than that the their them then there these they this those through tip to true try two type types
+under until up update updated use used uses using
+value values version versions view
+want warning was way we what when where whether which while who why will with within without would write
+yes you your
+caution notice
+b kb mb gb tb pb kib mib gib tib bps kbps mbps gbps ms msec ns us
+api apis ui url urls uri uris id ids ip ips cpu cpus ram os vm vms cli sdk http https tcp udp dns utc sha
+get post put patch head
+monday tuesday wednesday thursday friday saturday sunday
+january february march april june july august september october november december
+`.trim().split(/\s+/))
+
+// Words next to a term that say which facet it belongs to.
+const CUES = [
+  { facet: 'technology', cue: 'connector-name', re: /^(?:input|output|processor|cache|buffer|connector|scanner|tracer|rate[_ -]?limit|component)s?$/i },
+  { facet: 'technology', cue: 'database-name', re: /^(?:database|databases|db|table|tables|replica|cdc|warehouse)$/i },
+  { facet: 'technology', cue: 'format-name', re: /^(?:format|formats|schema|schemas|serialization|encoding|file|files)$/i },
+  { facet: 'technology', cue: 'product-name', re: /^(?:cli|api|apis|sdk|sdks|client|clients|library|libraries|server|servers|service|services|catalog|catalogs|bucket|buckets|operator|chart|cluster|clusters|plugin|plugins|driver|drivers|provider|providers|console|dashboard|dashboards)$/i },
+]
+const CONNECT_COMPONENT_XREF_RE = /\bxref:(?:connect:)?components:(?:inputs|outputs|processors|caches|buffers|rate_limits|metrics|tracers|scanners)\/([a-z0-9_]+)\.adoc/g
+const BACKTICK_RE = /`([^`\s]+)`/g
+const IDENT_RE = /^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)+$/
+const CAP_WORD_RE = /^(?:[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]*)*|[A-Z]{2,}[a-z]?[0-9]*|[A-Z][a-z]*[0-9]+[A-Za-z0-9]*|[a-z]+[A-Z][A-Za-z0-9]*)$/
+// Words dropped from the front of a capitalized run: articles, prepositions,
+// and the imperative verbs that start steps ("Configure Amazon S3").
+const LEADING_WORDS = new Set('a an the to for in on of with from by if when and or use using see set create configure enable disable install select click add remove update delete run start stop open go read write check review learn edit choose deploy manage connect test verify view'.split(' '))
+const MAX_TERM_WORDS = 4
+const MAX_LINES = 10
+
+/** Lowercase, whitespace-collapsed key. */
+const keyOf = (term) => String(term).normalize('NFKC').replace(/\s+/g, ' ').trim().toLowerCase()
+
+/**
+ * Read terminology lists into a Set of lowercase keys.
+ *
+ * Accepts, per path:
+ *   - a directory of docs glossary partials (shared/modules/terms/partials):
+ *     each file's `:term-name:` and its `=== heading`;
+ *   - a Markdown file such as the style guide's terminology.md: the first
+ *     column of each table, except under a heading that names brands (the
+ *     third-party brand list names exactly the products a candidate should
+ *     surface);
+ *   - any other file: one term per line.
+ * A term with an abbreviation in parentheses, "access control list (ACL)",
+ * adds both.
+ *
+ * @param {Array<string>} paths
+ * @returns {{terms: Set<string>, sources: string[]}}
+ */
+function loadTerminology (paths) {
+  const terms = new Set()
+  const sources = []
+  const add = (raw) => {
+    const t = String(raw).replace(/[`*_]/g, '').trim()
+    if (!t) return
+    const paren = /^(.*?)\s*\(([^)]+)\)\s*$/.exec(t)
+    if (paren) {
+      add(paren[1])
+      add(paren[2])
+      return
+    }
+    terms.add(keyOf(t))
+  }
+  for (const p of paths || []) {
+    if (!fs.existsSync(p)) continue
+    sources.push(p)
+    if (fs.statSync(p).isDirectory()) {
+      for (const f of fs.readdirSync(p).filter((f) => f.endsWith('.adoc')).sort()) {
+        const text = fs.readFileSync(path.join(p, f), 'utf8')
+        const name = /^:term-name:\s*(.+)$/m.exec(text)
+        if (name) add(name[1])
+        const heading = /^=+\s+(.+)$/m.exec(text)
+        if (heading) add(heading[1])
+      }
+      continue
+    }
+    const text = fs.readFileSync(p, 'utf8')
+    if (/\.md$/i.test(p)) {
+      let brands = false
+      for (const line of text.split(/\r?\n/)) {
+        const h = /^#+\s+(.*)$/.exec(line)
+        if (h) { brands = /brand/i.test(h[1]); continue }
+        if (brands) continue
+        const row = /^\|([^|]+)\|/.exec(line)
+        if (!row || /^\s*:?-+:?\s*$/.test(row[1]) || /^\s*(term|unit|extension)\s*$/i.test(row[1])) continue
+        add(row[1])
+      }
+    } else {
+      for (const line of text.split(/\r?\n/)) if (line.trim() && !line.startsWith('#')) add(line)
+    }
+  }
+  return { terms, sources }
+}
+
+/** The cue in the word right after a term ("Snowflake catalog"), if any. */
+function cueAfter (word) {
+  return word ? CUES.find((x) => x.re.test(word)) || null : null
+}
+
+/**
+ * Collect candidate terms on one page.
+ *
+ * @param {Object} parts - from pageParts
+ * @param {Object} matcher - from buildMatcher(taxonomy, { allLabels: true }), so a
+ *   term any concept covers, in any scheme, is dropped
+ * @param {Object} [options]
+ * @param {Set<string>} [options.terminology] - lowercase keys to drop
+ * @param {number} [options.minCount=2] - occurrences on the page
+ * @param {number} [options.max=10] - candidates per page, most frequent first
+ * @returns {Array<{term: string, count: number, lines: Array<{line: number, source?: string}>, facet: string|null, cue: string}>}
+ */
+function pageCandidates (parts, matcher, { terminology = new Set(), minCount = 2, max = 10 } = {}) {
+  const found = new Map() // key -> { spellings: Map, count, lines, cues: Map }
+  const note = (term, part, cue) => {
+    const key = keyOf(term)
+    if (!found.has(key)) found.set(key, { spellings: new Map(), count: 0, lines: [], cues: new Map() })
+    const f = found.get(key)
+    f.spellings.set(term, (f.spellings.get(term) || 0) + 1)
+    f.count++
+    if (f.lines.length < MAX_LINES && !f.lines.some((l) => l.line === part.line && l.source === part.source)) {
+      f.lines.push(part.source ? { line: part.line, source: part.source } : { line: part.line })
+    }
+    const name = cue ? `${cue.facet}:${cue.cue}` : 'none'
+    f.cues.set(name, (f.cues.get(name) || 0) + 1)
+  }
+
+  // Lowercase words in prose: a capitalized single word that also appears
+  // lowercase is an ordinary word.
+  const lowercase = new Set()
+  const prose = [parts.description, ...parts.body.filter((b) => !b.code && !b.sourceLanguage)].filter(Boolean)
+  for (const p of prose) for (const w of words(p.text)) if (w.raw === w.raw.toLowerCase()) lowercase.add(foldWord(w.raw))
+
+  // Capitalized terms.
+  for (const p of prose) {
+    const ws = words(p.text)
+    let i = 0
+    while (i < ws.length) {
+      if (!CAP_WORD_RE.test(ws[i].raw)) { i++; continue }
+      let j = i
+      // Consecutive words, separated by a single space only.
+      while (j + 1 < ws.length && j + 1 - i < MAX_TERM_WORDS && CAP_WORD_RE.test(ws[j + 1].raw) &&
+        /^ $/.test(p.text.slice(ws[j].index + ws[j].raw.length, ws[j + 1].index))) j++
+      let start = i
+      // Drop leading common words ("Use", "The") and a sentence-starting word.
+      while (start < j && (LEADING_WORDS.has(ws[start].raw.toLowerCase()) || (start === i && ws[i].sentenceStart && COMMON_WORDS.has(ws[i].raw.toLowerCase())))) start++
+      const span = ws.slice(start, j + 1)
+      i = j + 1
+      if (!span.length) continue
+      if (span.length === 1 && span[0].sentenceStart) continue
+      if (span.length === 1 && lowercase.has(foldWord(span[0].raw.toLowerCase()))) continue
+      // A lowerCamelCase word is an identifier (stringArray), unless the rest
+      // is capitals (mTLS).
+      if (span.some((w) => /^[a-z]/.test(w.raw) && !/^[a-z]{1,2}[A-Z0-9]+$/.test(w.raw))) continue
+      if (span.every((w) => COMMON_WORDS.has(w.raw.toLowerCase()))) continue
+      if (span.every((w) => /^[A-Z0-9]+$/.test(w.raw) && w.raw.length < 2)) continue
+      const term = p.text.slice(span[0].index, span[span.length - 1].index + span[span.length - 1].raw.length)
+      // Part of a hyphenated compound ("Comma-separated"), not a name.
+      const end = span[span.length - 1].index + span[span.length - 1].raw.length
+      if (p.text[end] === '-' || p.text[span[0].index - 1] === '-') continue
+      note(term, p, cueAfter(ws[j + 1] && ws[j + 1].raw))
+    }
+  }
+
+  // Code identifiers used as components, and Connect component xrefs.
+  for (const b of parts.body) {
+    if (b.sourceLanguage || !b.raw) continue
+    for (const m of b.raw.matchAll(CONNECT_COMPONENT_XREF_RE)) note(m[1], b, CUES[0])
+    if (b.code) continue
+    for (const m of b.raw.matchAll(BACKTICK_RE)) {
+      const ident = m[1]
+      if (!IDENT_RE.test(ident)) continue
+      const [after] = words(b.raw.slice(m.index + m[0].length))
+      const cue = cueAfter(after && after.raw)
+      if (cue && cue.cue === 'connector-name') note(ident, b, cue)
+    }
+  }
+
+  const out = []
+  for (const [key, f] of found) {
+    if (f.count < minCount) continue
+    if (terminology.has(key)) continue
+    const spelling = [...f.spellings.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0][0]
+    if (matchText(matcher, spelling).length) continue // a label already covers it
+    const best = [...f.cues.entries()].filter(([k]) => k !== 'none').sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0]
+    let facet = null
+    let cue = 'none'
+    if (best) [facet, cue] = best[0].split(':')
+    else if (/^[a-z]+[A-Z]|[a-z][A-Z]/.test(spelling) && !/\s/.test(spelling)) { facet = 'technology'; cue = 'brand-casing' }
+    else if (/\s/.test(spelling) && spelling.split(/\s+/).every((w) => /^[A-Z][a-z]/.test(w))) { facet = 'topic'; cue = 'title-case-name' }
+    out.push({ term: spelling, count: f.count, lines: f.lines, facet, cue })
+  }
+  out.sort((a, b) => b.count - a.count || a.term.localeCompare(b.term))
+  return out.slice(0, max)
+}
+
+/**
+ * Aggregate per-page candidates across a repository: one entry per term with
+ * the pages it appears in, most widespread first.
+ *
+ * @param {Array<{file: string, candidates: Array}>} perPage
+ * @param {Object} [options]
+ * @param {number} [options.minPages=1]
+ * @param {number} [options.minCount=2] - occurrences across all pages
+ * @param {number} [options.maxPageShare=0.2] - a term on more than this share
+ *   of the pages is boilerplate (a shared partial, a table heading), not a
+ *   distinctive term; dropped when there are 20 pages or more
+ * @returns {Array<{term, count, pageCount, facet, cue, pages: Array<{file, count, lines}>}>}
+ */
+function aggregateCandidates (perPage, { minPages = 1, minCount = 2, maxPageShare = 0.2 } = {}) {
+  const all = new Map()
+  for (const { file, candidates } of perPage) {
+    for (const c of candidates) {
+      const key = keyOf(c.term)
+      if (!all.has(key)) all.set(key, { spellings: new Map(), count: 0, facets: new Map(), pages: [] })
+      const a = all.get(key)
+      a.spellings.set(c.term, (a.spellings.get(c.term) || 0) + c.count)
+      a.count += c.count
+      const fk = `${c.facet || ''}:${c.cue}`
+      a.facets.set(fk, (a.facets.get(fk) || 0) + c.count)
+      a.pages.push({ file, count: c.count, lines: c.lines })
+    }
+  }
+  const out = []
+  for (const a of all.values()) {
+    if (a.pages.length < minPages || a.count < minCount) continue
+    if (perPage.length >= 20 && a.pages.length > maxPageShare * perPage.length) continue
+    const term = [...a.spellings.entries()].sort((x, y) => y[1] - x[1] || x[0].localeCompare(y[0]))[0][0]
+    const ranked = [...a.facets.entries()].sort((x, y) => (x[0].startsWith(':') ? 1 : 0) - (y[0].startsWith(':') ? 1 : 0) || y[1] - x[1] || x[0].localeCompare(y[0]))
+    const [facet, cue] = ranked[0][0].split(':')
+    out.push({ term, count: a.count, pageCount: a.pages.length, facet: facet || null, cue, pages: a.pages.sort((x, y) => y.count - x.count || x.file.localeCompare(y.file)) })
+  }
+  out.sort((x, y) => y.pageCount - x.pageCount || y.count - x.count || x.term.localeCompare(y.term))
+  return out
+}
+
+module.exports = {
+  COMMON_WORDS,
+  loadTerminology,
+  pageCandidates,
+  aggregateCandidates,
+}

package/extension-utils/metadata-check.js

@@ -0,0 +1,174 @@
+'use strict'
+
+/**
+ * The taxonomy metadata rules, in one place. `doc-tools check-metadata` runs
+ * them on page headers in a PR, validate-attributes runs them on Product Docs
+ * pages in the build, and solutions-catalog runs them on solution overviews,
+ * so the PR check and the build can never disagree about a value.
+ *
+ * Rules (severity for a Product Docs page / a solution overview):
+ *
+ *   unknown-value       the value names no concept                 warning / error
+ *   deprecated-value    the concept is deprecated                  warning / warning
+ *   not-in-taxonomy     a legacy category taxonomy.yml lacks       warning / warning
+ *   wrong-facet         a solution facet value from another facet  - / warning
+ *   duplicate-concept   two values on the page are one concept     warning / error
+ *
+ * `:page-topic-type:` is checked against the content-type scheme, as a
+ * warning only. Every message names the replacement when there is one.
+ */
+
+// Attributes the rules read, with the scheme a value must belong to (null:
+// any scheme, as page-categories mixes topics, use cases, technologies, ...).
+const CATEGORY_ATTRIBUTE = 'page-categories'
+const TOPIC_TYPE_ATTRIBUTE = 'page-topic-type'
+const SOLUTION_FACETS = Object.freeze({
+  'page-solution-use-cases': 'use-case',
+  'page-solution-industries': 'industry',
+  'page-solution-technologies': 'technology',
+  'page-solution-platforms': 'deployment',
+})
+const SOLUTION_LAYOUT = 'solution'
+
+const SEVERITY = Object.freeze({
+  'unknown-value': { docs: 'warning', solution: 'error' },
+  'deprecated-value': { docs: 'warning', solution: 'warning' },
+  'not-in-taxonomy': { docs: 'warning', solution: 'warning' },
+  'wrong-facet': { docs: 'warning', solution: 'warning' },
+  'duplicate-concept': { docs: 'warning', solution: 'error' },
+  'unknown-topic-type': { docs: 'warning', solution: 'warning' },
+})
+
+/** Split a comma-separated attribute value. */
+function splitValues (value) {
+  if (Array.isArray(value)) return value.map((v) => String(v).trim()).filter(Boolean)
+  if (value === undefined || value === null || value === true) return []
+  return String(value).split(',').map((v) => v.trim()).filter(Boolean)
+}
+
+/** Is this the overview page of a solution? */
+function isSolutionPage (attributes) {
+  return Boolean(attributes) && attributes['page-layout'] === SOLUTION_LAYOUT
+}
+
+function labelsOf (taxonomy, ids) {
+  return ids.map((id) => taxonomy.label(id))
+}
+
+function describe (taxonomy, id) {
+  const concept = taxonomy.get(id)
+  return concept ? `${concept.prefLabel} (${concept.scheme})` : id
+}
+
+/**
+ * Check one page's taxonomy metadata.
+ *
+ * @param {Object} attributes - attribute name (without colons) -> value. Values
+ *   are strings as AsciiDoc holds them, or arrays.
+ * @param {Object} options
+ * @param {import('./taxonomy').Taxonomy} options.taxonomy
+ * @param {boolean} [options.solution] - a solution overview; default from page-layout
+ * @param {(label: string) => boolean} [options.isLegacyCategory] - valid-categories.yml
+ *   membership, so a legacy category the taxonomy lacks is a gap, not unknown
+ * @returns {Array<{attribute: string, value: string, severity: string, rule: string, message: string, replacement: string|null, replacementIds: string[], conceptIds: string[]}>}
+ */
+function checkPageMetadata (attributes, { taxonomy, solution, isLegacyCategory } = {}) {
+  const attrs = attributes || {}
+  const kind = (solution === undefined ? isSolutionPage(attrs) : solution) ? 'solution' : 'docs'
+  const findings = []
+  const seen = new Map() // concept id -> { attribute, value }
+  const push = (rule, attribute, value, message, { replacementIds = [], conceptIds = [] } = {}) => {
+    findings.push({
+      attribute,
+      value,
+      severity: SEVERITY[rule][kind],
+      rule,
+      message,
+      replacement: replacementIds.length ? labelsOf(taxonomy, replacementIds).join(', ') : null,
+      replacementIds,
+      conceptIds,
+    })
+  }
+  const noteConcepts = (attribute, value, ids) => {
+    for (const id of ids) {
+      const first = seen.get(id)
+      if (first && !(first.attribute === attribute && first.value === value)) {
+        push('duplicate-concept', attribute, value,
+          `${attribute} value '${value}' is the same concept as ${first.attribute} value '${first.value}': ${describe(taxonomy, id)}. Keep one`,
+          { conceptIds: [id] })
+      } else if (!first) {
+        seen.set(id, { attribute, value })
+      }
+    }
+  }
+
+  // page-categories: any scheme.
+  for (const value of splitValues(attrs[CATEGORY_ATTRIBUTE])) {
+    const hit = taxonomy.resolve(value)
+    if (!hit) {
+      if (isLegacyCategory && isLegacyCategory(value)) {
+        push('not-in-taxonomy', CATEGORY_ATTRIBUTE, value, `${CATEGORY_ATTRIBUTE} value '${value}' is in valid-categories.yml but not in taxonomy.yml; add it to the taxonomy`)
+      } else {
+        push('unknown-value', CATEGORY_ATTRIBUTE, value, `${CATEGORY_ATTRIBUTE} value '${value}' is not in the taxonomy; use an existing label, or add a concept to taxonomy.yml`)
+      }
+      continue
+    }
+    if (hit.deprecated) {
+      push('deprecated-value', CATEGORY_ATTRIBUTE, value, deprecatedMessage(CATEGORY_ATTRIBUTE, value, hit, taxonomy), { replacementIds: hit.ids, conceptIds: [hit.concept.id] })
+    }
+    noteConcepts(CATEGORY_ATTRIBUTE, value, hit.ids)
+  }
+
+  // Solution facets: each within its own scheme.
+  if (kind === 'solution') {
+    for (const [attribute, scheme] of Object.entries(SOLUTION_FACETS)) {
+      const prefer = scheme === 'deployment' ? 'id' : 'label'
+      for (const value of splitValues(attrs[attribute])) {
+        const hit = taxonomy.resolve(value, { prefer })
+        if (!hit) {
+          push('unknown-value', attribute, value, `${attribute} value '${value}' is not in the taxonomy; use an existing ${scheme}, or add it to taxonomy.yml in the docs repository first`)
+          continue
+        }
+        if (hit.deprecated) {
+          push('deprecated-value', attribute, value, deprecatedMessage(attribute, value, hit, taxonomy), { replacementIds: hit.ids, conceptIds: [hit.concept.id] })
+        } else if (hit.concept.scheme !== scheme) {
+          push('wrong-facet', attribute, value, `${attribute} value '${value}' is ${describe(taxonomy, hit.concept.id)}, not a ${scheme}`, { conceptIds: [hit.concept.id] })
+          continue
+        }
+        noteConcepts(attribute, value, hit.ids)
+      }
+    }
+  }
+
+  // Content type: one value, warning only.
+  const topicType = splitValues(attrs[TOPIC_TYPE_ATTRIBUTE])
+  for (const value of topicType) {
+    const hit = taxonomy.resolve(value, { schemes: ['content-type'], prefer: 'id' })
+    if (!hit) {
+      push('unknown-topic-type', TOPIC_TYPE_ATTRIBUTE, value, `${TOPIC_TYPE_ATTRIBUTE} '${value}' is not a content type in the taxonomy; use one of ${taxonomy.conceptIds('content-type').join(', ')}`)
+    } else if (hit.deprecated) {
+      push('deprecated-value', TOPIC_TYPE_ATTRIBUTE, value, deprecatedMessage(TOPIC_TYPE_ATTRIBUTE, value, hit, taxonomy), { replacementIds: hit.ids, conceptIds: [hit.concept.id] })
+    } else if (hit.via !== 'id') {
+      push('unknown-topic-type', TOPIC_TYPE_ATTRIBUTE, value, `${TOPIC_TYPE_ATTRIBUTE} '${value}' should be the ID ${hit.concept.id}`, { replacementIds: [hit.concept.id], conceptIds: [hit.concept.id] })
+    }
+  }
+
+  return findings
+}
+
+function deprecatedMessage (attribute, value, hit, taxonomy) {
+  const instead = hit.ids.length
+    ? `use ${hit.ids.map((id) => `'${taxonomy.label(id)}'`).join(', ')} instead`
+    : 'no single value replaces it; see its definition in taxonomy.yml and choose per page'
+  return `${attribute} value '${value}' is deprecated; ${instead}`
+}
+
+module.exports = {
+  CATEGORY_ATTRIBUTE,
+  TOPIC_TYPE_ATTRIBUTE,
+  SOLUTION_FACETS,
+  SEVERITY,
+  splitValues,
+  isSolutionPage,
+  checkPageMetadata,
+}