diff --git a/.claude/skills/readme-cli/SKILL.md b/.claude/skills/readme-cli/SKILL.md index ea5cd73..e34f7a9 100644 --- a/.claude/skills/readme-cli/SKILL.md +++ b/.claude/skills/readme-cli/SKILL.md @@ -18,7 +18,7 @@ npx @readme/cli lint --fix # Automatically fix common issues npx @readme/cli lint --json # Machine-readable output (good for CI) ``` -Validates: frontmatter, ordering, duplicates, OAS references, OAS schema, MDX components, and recipes. +Validates: frontmatter, ordering, duplicates, OAS references, OAS schema, MDX components, recipes, and the `_readme.yaml` config. Always try `lint --fix` before attempting manual fixes. @@ -28,7 +28,7 @@ Always try `lint --fix` before attempting manual fixes. npx @readme/cli oas:sync ``` -Syncs `reference/` directory with OpenAPI specs. Creates, updates, or removes pages based on spec operations. Run this when you see `oas-reference` errors. +Syncs `reference/` directory (and any other reference section declared in `_readme.yaml`) with OpenAPI specs. Creates, updates, or removes pages based on spec operations. Run this when you see `oas-reference` errors. ### OpenAPI Bundle @@ -67,10 +67,26 @@ Starts a local dev server to preview docs with live reload. The CLI expects to be run inside a git repo that has: - A version branch matching `v[0-9]*` (e.g., `v1`, `v2.0`) -- A `docs/` and/or `reference/` directory at the repo root +- A `docs/` and/or `reference/` directory at the repo root (or a section declared in `_readme.yaml`) Use `--no-check` to skip this validation if needed. +## Sections and `_readme.yaml` + +Every repo has the built-in sections: `docs/`, `reference/`, `recipes/`, `custom_pages/`. A project with multiple guides declares extra sections in an optional `_readme.yaml` at the repo root: + +```yaml +navigation: + - kind: guide # guide or reference + directory: sdks # top-level folder; lowercase letters, numbers, - and _ + name: SDKs +``` + +- A declared `guide` section is linted like `docs/`; a declared `reference` section like `reference/`, including `oas:sync` and `oas:validate`. +- Repos without `_readme.yaml` are fine: only the built-in sections apply. +- A new top-level folder of pages is ignored by ReadMe until it's declared here. `lint` warns about a folder that has an `_order.yaml` but isn't declared. +- `lint` reports problems in the file under the `config` rule. These have no `--fix`; edit `_readme.yaml` by hand. + ## Typical Workflow 1. Run `npx @readme/cli lint` to check for issues diff --git a/README.md b/README.md index d809bf1..ba3911e 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,29 @@ npx @readme/cli oas:bundle path/to/openapi.yaml --out reference/api.json Without `--out`, the bundled spec is printed to stdout. The output format follows the `--out` extension (`.yaml`/`.yml` for YAML, JSON otherwise). This command works from any directory, so you can run it in your API's source repo. +### Multiple guides (`_readme.yaml`) + +Every project has the built-in sections: `docs/`, `reference/`, `recipes/` and `custom_pages/`. If your project has more than one guide or API reference, they're declared in a `_readme.yaml` file at the root of the repo, each with its own directory: + +```yaml +navigation: + - kind: guide + directory: docs + name: Guides + - kind: guide + directory: sdks + name: SDKs + - kind: reference + directory: reference + - kind: reference + directory: partner-api + name: Partner API +``` + +The CLI reads this file and treats each declared section like the built-in one of its kind: `lint` checks `sdks/` the way it checks `docs/`, and `oas:sync` and `oas:validate` cover the specs in `partner-api/` as well as `reference/`. `lint` also checks the file itself. + +The file is optional. If your repo doesn't have one, nothing changes: the CLI works with the built-in sections, same as always. + ### Import Imports content from an external folder and converts it into ReadMe's format using Claude. Great for migrating existing docs. diff --git a/action.yml b/action.yml index 7921408..1c4c86c 100644 --- a/action.yml +++ b/action.yml @@ -40,7 +40,7 @@ outputs: skipped-count: description: Reference pages skipped because the destination filename already exists (oas:sync only) skipped: - description: JSON array of skipped pages, each { filename, path, operationId } (oas:sync only) + description: JSON array of skipped pages, each { section, filename, path, operationId } (oas:sync only) runs: using: node24 pre: src/gha-pre.js diff --git a/dist-gha/index.js b/dist-gha/index.js index 0ff440f..f50540e 100644 --- a/dist-gha/index.js +++ b/dist-gha/index.js @@ -69219,6 +69219,14 @@ __nccwpck_require__.d(components_namespaceObject, { validateAll: () => (validateAll) }); +// NAMESPACE OBJECT: ./src/validators/config.js +var config_namespaceObject = {}; +__nccwpck_require__.r(config_namespaceObject); +__nccwpck_require__.d(config_namespaceObject, { + name: () => (config_name), + validateAll: () => (config_validateAll) +}); + // NAMESPACE OBJECT: ./src/validators/content.js var content_namespaceObject = {}; __nccwpck_require__.r(content_namespaceObject); @@ -69279,7 +69287,6 @@ __nccwpck_require__.d(oas_schema_namespaceObject, { var ordering_namespaceObject = {}; __nccwpck_require__.r(ordering_namespaceObject); __nccwpck_require__.d(ordering_namespaceObject, { - CONTENT_DIRS: () => (ordering_CONTENT_DIRS), name: () => (ordering_name), validateAll: () => (ordering_validateAll) }); @@ -73333,6 +73340,265 @@ function toFrontmatter(data, body = '') { return body ? `${fence}\n${body}` : fence; } +;// CONCATENATED MODULE: ./src/utils/sections.js + + + + + +/** + * Sections are the top-level content directories of a ReadMe repo. + * + * Every project has the built-in ones (`docs`, `reference`, `recipes`, + * `custom_pages`). Projects with multiple guides declare more in a + * `_readme.yaml` file at the repo root: + * + * navigation: + * - kind: guide + * directory: docs + * name: Guides + * - kind: guide + * directory: sdks + * name: SDKs + * - kind: reference + * directory: apis + * + * The file is optional. A repo without one (every repo from before the + * feature) resolves to just the built-ins, exactly as ReadMe itself does. + * The rules here mirror the ones ReadMe applies when it reads the file. + */ + +const CONFIG_FILE = '_readme.yaml'; + +/** Allowed shape for a section `directory`. */ +const SECTION_DIRECTORY_REGEX = /^[a-z0-9][a-z0-9_-]{0,29}$/; + +/** Built-in directories, and the one kind each is locked to. */ +const BUILT_IN_KINDS = { + changelogs: 'changelog', + custom_pages: 'custom_pages', + docs: 'guide', + recipes: 'recipes', + reference: 'reference', + skills: 'skill', +}; + +/** Kinds a non-built-in directory may declare. */ +const DECLARABLE_KINDS = ['guide', 'reference']; + +/** Kinds whose `navigation` entry owns a top-level directory. */ +const DIRECTORY_KINDS = ['guide', 'recipes', 'reference', 'skill']; + +/** Kinds that may appear only once, and point at nothing. */ +const SINGLETON_KINDS = ['changelog', 'discuss', 'home', 'version']; + +/** Directories that can never be declared as a section. */ +const RESERVED_DIRECTORIES = new Set([ + // Owned by ReadMe's storage. + 'custom_blocks', + 'llms_txt', + 'apidefinition', + 'api_config', + // `docs` is served at /guides, so a directory of that name would collide. + 'guides', + // URL segments the hub routes itself. + 'admin', + 'api', + 'auth', + 'blog', + 'chatgpt', + 'comments', + 'custom-login', + 'dash', + 'discuss', + 'discuss-new', + 'edit', + 'graphql', + 'inactive', + 'login', + 'login-webhook', + 'logout', + 'logs', + 'mcp', + 'oauth', + 'oauth2-redirect', + 'og-image', + 'openapi', + 'password', + 'reference-link', + 'suggested-edits', + 'throw-error', + 'unvalidated', +]); + +// The sections the CLI has always handled, in the order it lists them. +const BUILT_IN_SECTIONS = [ + { directory: 'docs', kind: 'guide', label: 'Docs' }, + { directory: 'reference', kind: 'reference', label: 'Reference' }, + { directory: 'custom_pages', kind: 'custom_pages', label: 'Custom Pages' }, + { directory: 'recipes', kind: 'recipes', label: 'Recipes' }, +]; + +// What ReadMe calls a built-in section that `_readme.yaml` lists without a name. +const DEFAULT_SECTION_NAMES = { + docs: 'Guides', + reference: 'API Reference', + recipes: 'Recipes', + custom_pages: 'Custom Pages', +}; + +function isBuiltInDirectory(directory) { + return Object.hasOwn(BUILT_IN_KINDS, directory); +} + +/** Whether a directory could be declared as a section of its own. */ +function isDeclarableDirectory(directory) { + return ( + typeof directory === 'string' && + SECTION_DIRECTORY_REGEX.test(directory) && + !isBuiltInDirectory(directory) && + !RESERVED_DIRECTORIES.has(directory) + ); +} + +/** + * Parse `_readme.yaml` content the way ReadMe does: core YAML types only, so a + * directory called `2026-07-31` stays a string rather than becoming a date. + * + * @returns {{ config: object | null, error: string | null }} + */ +function parseConfig(content) { + let parsed; + try { + parsed = load(content, { json: true, schema: CORE_SCHEMA }); + } catch (err) { + return { config: null, error: err.reason || err.message || 'invalid YAML' }; + } + if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) { + return { config: null, error: 'must be a YAML object' }; + } + return { config: parsed, error: null }; +} + +class Sections { + constructor({ exists, config, error, list, order }) { + /** Whether the repo has a `_readme.yaml`. */ + this.exists = exists; + /** The parsed file, or null when it's missing or unreadable. */ + this.config = config; + /** Why the file couldn't be parsed, or null. */ + this.error = error; + this.list = list; + /** Directories in the order `_readme.yaml` lists them, the rest after. */ + this.order = [...new Set([...(order || []), ...list.map(section => section.directory)])]; + this.byDirectory = new Map(list.map(section => [section.directory, section])); + } + + /** The kind of a top-level directory, or undefined when it isn't a section. */ + kindOf(directory) { + if (directory === 'custom_blocks') return 'custom_blocks'; + return this.byDirectory.get(directory)?.kind; + } + + /** Every directory that holds pages: the built-ins plus the declared ones. */ + directories() { + return this.list.map(section => section.directory); + } + + /** The directories of the given kind(s), e.g. every API reference. */ + directoriesOfKind(...kinds) { + return this.list.filter(section => kinds.includes(section.kind)).map(section => section.directory); + } + + /** The directories declared in `_readme.yaml` on top of the built-ins. */ + declaredDirectories() { + return this.list.filter(section => !section.builtIn).map(section => section.directory); + } +} + +/** + * The API reference directories that exist in a repo: `reference`, plus any + * section `_readme.yaml` declares with the `reference` kind. + */ +function findReferenceDirs(gitRoot, sections = loadSections(gitRoot)) { + return sections.directoriesOfKind('reference').filter(directory => { + try { + return external_node_fs_namespaceObject.statSync(external_node_path_namespaceObject.join(gitRoot, directory)).isDirectory(); + } catch { + return false; + } + }); +} + +/** The sections of a repo with no `_readme.yaml`. */ +const DEFAULT_SECTIONS = new Sections({ + exists: false, + config: null, + error: null, + list: BUILT_IN_SECTIONS.map(section => ({ ...section, builtIn: true, hidden: false })), +}); + +/** + * Resolve a repo's sections from its `_readme.yaml`. + * + * Never throws: a missing, unparseable, or partly invalid file still resolves + * (to the built-ins, plus whichever declared sections are usable), so one bad + * entry doesn't stop the rest of the repo from being linted. Reporting what's + * wrong with the file is the `config` validator's job. + */ +function loadSections(gitRoot) { + const configPath = external_node_path_namespaceObject.join(gitRoot, CONFIG_FILE); + + let content; + try { + // `readFile` follows a symlink, and a linked config could declare sections + // from a file outside the repo. Like every other linked path, it's refused. + if (external_node_fs_namespaceObject.lstatSync(configPath).isSymbolicLink()) { + return new Sections({ + exists: true, + config: null, + error: 'symbolic links are not followed', + list: BUILT_IN_SECTIONS.map(section => ({ ...section, builtIn: true, hidden: false })), + }); + } + content = external_node_fs_namespaceObject.readFileSync(configPath, 'utf-8'); + } catch { + return DEFAULT_SECTIONS; + } + + const { config, error } = parseConfig(content); + const navigation = Array.isArray(config?.navigation) ? config.navigation : []; + + const list = BUILT_IN_SECTIONS.map(section => ({ ...section, builtIn: true, hidden: false })); + const byDirectory = new Map(list.map(section => [section.directory, section])); + const order = []; + + for (const entry of navigation) { + if (!entry || typeof entry !== 'object' || typeof entry.directory !== 'string') continue; + const { directory, kind } = entry; + const name = typeof entry.name === 'string' && entry.name ? entry.name : null; + + const builtIn = byDirectory.get(directory); + if (builtIn?.builtIn) { + // A built-in keeps its kind whatever the file says; only its label and + // visibility are the file's to set. + builtIn.label = name || DEFAULT_SECTION_NAMES[directory]; + builtIn.hidden = entry.hidden === true; + if (!order.includes(directory)) order.push(directory); + continue; + } + + if (builtIn || !isDeclarableDirectory(directory) || !DECLARABLE_KINDS.includes(kind)) continue; + + const section = { directory, kind, label: name || directory, builtIn: false, hidden: entry.hidden === true }; + list.push(section); + byDirectory.set(directory, section); + order.push(directory); + } + + return new Sections({ exists: true, config, error, list, order }); +} + ;// CONCATENATED MODULE: ./src/validators/components.js @@ -73341,6 +73607,7 @@ function toFrontmatter(data, body = '') { + const { mdxishTags } = markdown_namespaceObject["default"]; const components_name = 'components'; @@ -73375,9 +73642,6 @@ const BUILTIN_COMPONENTS = new Set([ 'TutorialTile', ]); -// Directories that can contain MDXish content with component references. -const CONTENT_DIRS = new Set(['docs', 'reference', 'custom_pages', 'recipes']); - /** * Extract component tag names from MDXish content. * Parses via @readme/markdown's mdxishTags so code blocks, inline code, and @@ -73526,14 +73790,16 @@ function validate({ content, relativePath }) { /** * Cross-file: check that all component references in content files resolve. */ -function validateAll(files, gitRoot) { +function validateAll(files, gitRoot, { sections = loadSections(gitRoot) } = {}) { const results = []; + // Every section can contain MDXish content with component references. + const contentDirs = new Set(sections.directories()); const customBlocks = collectCustomBlockNames(gitRoot); const available = new Set([...BUILTIN_COMPONENTS, ...customBlocks]); for (const relPath of files) { const dir = relPath.split('/')[0]; - if (!CONTENT_DIRS.has(dir)) continue; + if (!contentDirs.has(dir)) continue; if (!relPath.endsWith('.md')) continue; const filePath = external_node_path_namespaceObject.join(gitRoot, relPath); @@ -73561,17 +73827,260 @@ function validateAll(files, gitRoot) { return results; } +;// CONCATENATED MODULE: ./src/validators/config.js + + + + + +const config_name = 'config'; + +// Fields every `navigation` entry may carry, plus the one its kind points at. +const COMMON_KEYS = ['kind', 'name', 'hidden', 'icon']; +// The fields that say what an entry points at. Each belongs to certain kinds. +const TARGET_KEYS = ['directory', 'slug', 'url']; +// Custom pages are markdown or raw HTML. +const CUSTOM_PAGE_EXTENSIONS = ['md', 'mdx', 'html']; +const KNOWN_KINDS = [...DIRECTORY_KINDS, ...SINGLETON_KINDS, 'custom_pages', 'url']; + +function targetKeyFor(kind) { + if (DIRECTORY_KINDS.includes(kind)) return 'directory'; + if (kind === 'custom_pages') return 'slug'; + if (kind === 'url') return 'url'; + return null; +} + +function isAbsoluteUrl(value) { + try { + return Boolean(new URL(value).protocol); + } catch { + return false; + } +} + +/** + * Top-level folders that are laid out like a section (they have an + * `_order.yaml`) but that ReadMe doesn't know about, because nothing in + * `_readme.yaml` declares them. + */ +function findUndeclaredSections(gitRoot, sections) { + let entries; + try { + entries = external_node_fs_namespaceObject.readdirSync(gitRoot, { withFileTypes: true }); + } catch { + return []; + } + + const known = new Set(sections.directories()); + return entries + .filter(entry => entry.isDirectory()) + .map(entry => entry.name) + .filter(directory => !known.has(directory) && !isBuiltInDirectory(directory)) + .filter(directory => !RESERVED_DIRECTORIES.has(directory) && SECTION_DIRECTORY_REGEX.test(directory)) + .filter(directory => external_node_fs_namespaceObject.existsSync(external_node_path_namespaceObject.join(gitRoot, directory, '_order.yaml'))) + .sort(); +} + +/** + * Validate `_readme.yaml`, the optional file that declares a project's + * navigation and any sections beyond the built-in ones. + * + * A repo without the file is fine: it's how every repo looked before multiple + * guides, and ReadMe falls back to the built-in sections. + * + * The checks mirror the ones ReadMe runs when the file is saved from the + * dashboard. A file that arrives through git sync skips some of those (a + * reserved or duplicated directory, a built-in declared as the wrong kind), so + * this is the only place they get caught. + * + * One deliberate difference: ReadMe ignores the whole file when it holds a + * property or kind it doesn't recognize, but the format can grow ahead of this + * CLI, so anything this version merely doesn't know is a warning, not an error. + */ +function config_validateAll(_files, gitRoot, { sections = loadSections(gitRoot) } = {}) { + const results = []; + const error = message => results.push({ file: CONFIG_FILE, rule: config_name, severity: 'error', message }); + const warning = message => results.push({ file: CONFIG_FILE, rule: config_name, severity: 'warning', message }); + + for (const directory of findUndeclaredSections(gitRoot, sections)) { + results.push({ + file: directory, + rule: config_name, + severity: 'warning', + message: sections.exists + ? `Undeclared section: "${directory}" has an _order.yaml but isn't declared in ${CONFIG_FILE}, so ReadMe will ignore it` + : `Undeclared section: "${directory}" has an _order.yaml but there's no ${CONFIG_FILE} declaring it, so ReadMe will ignore it`, + }); + } + + if (!sections.exists) return results; + + if (sections.error) { + error(`Invalid ${CONFIG_FILE}: ${sections.error}`); + return results; + } + + const { config } = sections; + + for (const key of Object.keys(config)) { + if (key !== 'navigation') { + warning( + `Unknown property: "${key}" isn't recognized by this version of the CLI (if ReadMe doesn't recognize it either, it ignores the whole file)`, + ); + } + } + + // ReadMe reads a file with no `navigation` as an empty one. + if (config.navigation === undefined || config.navigation === null) return results; + + // ...and one whose `navigation` isn't a list the same way, which is never + // what was meant. + if (!Array.isArray(config.navigation)) { + warning('Invalid navigation: "navigation" must be a list (ReadMe treats anything else as empty)'); + return results; + } + + const directories = new Set(); + const customPageSlugs = new Set(); + const singletons = new Set(); + + config.navigation.forEach((entry, index) => { + const where = `navigation[${index}]`; + + if (!entry || typeof entry !== 'object' || Array.isArray(entry)) { + error(`Invalid entry: ${where} must be an object with a "kind"`); + return; + } + + const { kind } = entry; + if (typeof kind !== 'string' || !kind) { + error(`Invalid entry: ${where} is missing a "kind"`); + return; + } + if (!KNOWN_KINDS.includes(kind)) { + warning( + `Unknown kind: "${kind}" (${where}) isn't recognized by this version of the CLI (if ReadMe doesn't recognize it either, it ignores the whole file)`, + ); + return; + } + + const targetKey = targetKeyFor(kind); + const allowed = targetKey ? [...COMMON_KEYS, targetKey] : COMMON_KEYS; + for (const key of Object.keys(entry)) { + if (allowed.includes(key)) continue; + if (TARGET_KEYS.includes(key)) { + // A real field, on a kind that can't carry it. ReadMe rejects the file. + error(`Invalid entry: a "${kind}" entry can't have a "${key}" (${where})`); + } else { + warning( + `Unknown property: "${key}" on a "${kind}" entry (${where}) isn't recognized by this version of the CLI (if ReadMe doesn't recognize it either, it ignores the whole file)`, + ); + } + } + + if (entry.name !== undefined && entry.name !== null && (typeof entry.name !== 'string' || !entry.name)) { + error(`Invalid entry: "name" must be a non-empty string (${where})`); + } + if (entry.hidden !== undefined && entry.hidden !== null && typeof entry.hidden !== 'boolean') { + error(`Invalid entry: "hidden" must be true or false (${where})`); + } + if (entry.icon !== undefined && entry.icon !== null && typeof entry.icon !== 'string') { + error(`Invalid entry: "icon" must be a string (${where})`); + } + + if (kind === 'custom_pages') { + const { slug } = entry; + if (typeof slug === 'number' || typeof slug === 'boolean') { + // YAML reads a bare `404` or `true` as a number or boolean, not a slug. + error(`Invalid entry: ${slug} must be wrapped in quotes to be used as a slug (${where})`); + } else if (typeof slug !== 'string' || !slug) { + error(`Invalid entry: a "custom_pages" entry needs a "slug" (${where})`); + } else if (customPageSlugs.has(slug)) { + error(`Duplicate entry: the "${slug}" custom page is listed more than once`); + } else { + customPageSlugs.add(slug); + const exists = CUSTOM_PAGE_EXTENSIONS.some(ext => + external_node_fs_namespaceObject.existsSync(external_node_path_namespaceObject.join(gitRoot, 'custom_pages', `${slug}.${ext}`)), + ); + if (!exists) { + warning(`Missing page: "${slug}" is in the navigation but there's no custom_pages/${slug}.md (or .html)`); + } + } + return; + } + + if (kind === 'url') { + if (typeof entry.url !== 'string' || !isAbsoluteUrl(entry.url)) { + error(`Invalid entry: a "url" entry needs an absolute "url" (${where})`); + } + return; + } + + if (SINGLETON_KINDS.includes(kind)) { + if (singletons.has(kind)) error(`Duplicate entry: a "${kind}" entry may only appear once`); + singletons.add(kind); + return; + } + + // What's left owns a top-level directory. + const { directory } = entry; + if (typeof directory === 'number' || typeof directory === 'boolean') { + // YAML reads a bare `2026` or `true` as a number or boolean, not a name. + error(`Invalid directory: ${directory} must be wrapped in quotes to be used as a directory (${where})`); + return; + } + if (typeof directory !== 'string' || !directory) { + error(`Invalid entry: a "${kind}" entry needs a "directory" (${where})`); + return; + } + if (directories.has(directory)) { + error(`Duplicate section: the "${directory}" directory is declared more than once`); + return; + } + directories.add(directory); + + if (!SECTION_DIRECTORY_REGEX.test(directory)) { + error( + `Invalid directory: "${directory}" must be 1-30 characters of lowercase letters, numbers, "-" or "_", and start with a letter or number`, + ); + return; + } + if (RESERVED_DIRECTORIES.has(directory)) { + error(`Reserved directory: "${directory}" can't be used as a section`); + return; + } + + // `hasOwn`, not a bare lookup: `constructor` is a valid directory name. + const builtInKind = isBuiltInDirectory(directory) ? BUILT_IN_KINDS[directory] : undefined; + if (builtInKind !== undefined) { + if (kind !== builtInKind) { + error(`Invalid kind: the "${directory}" directory must use the "${builtInKind}" kind, not "${kind}"`); + } + return; + } + if (!DECLARABLE_KINDS.includes(kind)) { + error(`Invalid kind: "${directory}" must be one of ${DECLARABLE_KINDS.join(' or ')}, not "${kind}"`); + } + }); + + return results; +} + ;// CONCATENATED MODULE: ./src/validators/content.js + const content_name = 'content'; -function content_validate({ filePath, content, relativePath }) { - const dir = relativePath.split('/')[0]; - if (!['docs', 'reference', 'custom_pages'].includes(dir)) return null; +// Kinds of section whose pages are expected to have a body. +const CHECKED_KINDS = ['guide', 'reference', 'custom_pages']; + +function content_validate({ filePath, content, relativePath, sections = DEFAULT_SECTIONS }) { + const topDir = relativePath.split('/')[0]; + if (!CHECKED_KINDS.includes(sections.kindOf(topDir))) return null; if (!relativePath.endsWith('.md')) return null; const { data, content: body } = parseFrontmatter(content); @@ -73640,19 +74149,20 @@ function slugForEntry(relPath) { + const duplicates_name = 'duplicates'; -// Only docs and reference require unique slugs. -const CHECKED_DIRS = ['docs', 'reference']; +// Only guide and reference sections require unique slugs. +const duplicates_CHECKED_KINDS = ['guide', 'reference']; -function duplicates_validateAll(files) { +function duplicates_validateAll(files, _gitRoot, { sections = DEFAULT_SECTIONS } = {}) { const results = []; // Group files by ":" so slugs only collide within the same section. const slugMap = new Map(); for (const relPath of files) { const topDir = relPath.split('/')[0]; - if (!CHECKED_DIRS.includes(topDir)) continue; + if (!duplicates_CHECKED_KINDS.includes(sections.kindOf(topDir))) continue; const slug = slugForEntry(relPath); const key = `${topDir}:${slug}`; @@ -73698,6 +74208,7 @@ const frontmatter_schema_namespaceObject = /*#__PURE__*/JSON.parse('{"yL":[{"tit + const frontmatter_name = 'frontmatter'; function getNestedValue(obj, instancePath) { @@ -73758,27 +74269,28 @@ function collectPropertyNames(schema, defs) { return props; } -// Map directory names to their index in the schema's oneOf array. -const DIR_SCHEMA_INDEX = { - docs: 0, +// Map each kind of section to its index in the schema's oneOf array. A declared +// section's pages use the same frontmatter as the built-in section of its kind. +const KIND_SCHEMA_INDEX = { + guide: 0, custom_pages: 1, reference: 2, recipes: 3, custom_blocks: 4, }; -// Compile a validator for each directory type from the vendored schema. +// Compile a validator for each kind from the vendored schema. const frontmatter_ajv = new ajv({ allErrors: true, strict: false, logger: false, verbose: true }); const validators = {}; const knownProperties = {}; -for (const [dir, index] of Object.entries(DIR_SCHEMA_INDEX)) { +for (const [kind, index] of Object.entries(KIND_SCHEMA_INDEX)) { const subSchema = { defs: frontmatter_schema_namespaceObject.$B, ...frontmatter_schema_namespaceObject.yL[index] }; - validators[dir] = frontmatter_ajv.compile(subSchema); - knownProperties[dir] = collectPropertyNames(subSchema, frontmatter_schema_namespaceObject.$B); + validators[kind] = frontmatter_ajv.compile(subSchema); + knownProperties[kind] = collectPropertyNames(subSchema, frontmatter_schema_namespaceObject.$B); } -function frontmatter_validate({ content, filePath, relativePath, fix }) { +function frontmatter_validate({ content, filePath, relativePath, fix, sections = DEFAULT_SECTIONS }) { // Step 1: Parse the frontmatter YAML. const { data, error } = parseFrontmatter(content); if (error) { @@ -73790,10 +74302,10 @@ function frontmatter_validate({ content, filePath, relativePath, fix }) { } const results = []; - const dir = relativePath.split('/')[0]; + const kind = sections.kindOf(relativePath.split('/')[0]); // Step 2: Validate the parsed frontmatter against the schema. - const validateFn = validators[dir]; + const validateFn = validators[kind]; if (validateFn) { const valid = validateFn(data); if (!valid) { @@ -73801,7 +74313,7 @@ function frontmatter_validate({ content, filePath, relativePath, fix }) { // Reference pages are OAS-backed: title/excerpt come from the spec, so a // missing title is not an error for pages that declare an api.file. if ( - dir === 'reference' && + kind === 'reference' && data?.api?.file && err.keyword === 'required' && err.params?.missingProperty === 'title' @@ -73834,7 +74346,7 @@ function frontmatter_validate({ content, filePath, relativePath, fix }) { } // Step 3: Warn about unknown properties (allow x- prefix for custom metadata). - const allowed = knownProperties[dir]; + const allowed = knownProperties[kind]; const unknownKeys = []; if (allowed && data && typeof data === 'object') { for (const key of Object.keys(data)) { @@ -73951,17 +74463,16 @@ function frontmatter_validate({ content, filePath, relativePath, fix }) { -const links_name = 'links'; -const links_CHECKED_DIRS = ['docs', 'reference', 'custom_pages', 'recipes']; +const links_name = 'links'; // Match doc:slug and ref:slug links, e.g. [text](doc:my-page) or [text](ref:my-op#anchor) const DOC_LINK_RE = /\((?:doc|ref):([a-zA-Z0-9_-]+)(?:#[^)]*)?\)/g; -function collectSlugs(gitRoot) { +function collectSlugs(gitRoot, dirs) { const slugs = new Set(); - for (const dir of links_CHECKED_DIRS) { + for (const dir of dirs) { const dirPath = external_node_path_namespaceObject.join(gitRoot, dir); if (!external_node_fs_namespaceObject.existsSync(dirPath)) continue; @@ -73975,13 +74486,14 @@ function collectSlugs(gitRoot) { return slugs; } -function links_validateAll(files, gitRoot) { - const validSlugs = collectSlugs(gitRoot); +function links_validateAll(files, gitRoot, { sections = loadSections(gitRoot) } = {}) { + const checkedDirs = sections.directories(); + const validSlugs = collectSlugs(gitRoot, checkedDirs); const results = []; for (const relPath of files) { const topDir = relPath.split('/')[0]; - if (!links_CHECKED_DIRS.includes(topDir)) continue; + if (!checkedDirs.includes(topDir)) continue; if (!/\.(md|mdx)$/.test(relPath)) continue; const raw = external_node_fs_namespaceObject.readFileSync(external_node_path_namespaceObject.join(gitRoot, relPath), 'utf-8'); @@ -74009,29 +74521,29 @@ function links_validateAll(files, gitRoot) { const nesting_name = 'nesting'; -// Max folder nesting per top-level content dir. Anything deeper still syncs -// but won't appear in the sidebar. +// Max folder nesting per kind of section. Anything deeper still syncs but +// won't appear in the sidebar. // -// For `docs` and `reference` the category is the first folder and each page +// For guide and reference sections the category is the first folder and each page // level below it adds one, so this is the number of page levels the sidebar // renders under a category. It mirrors our publicly documented sidebar levels. // Keep in sync with src/dev/lib/docs.js. const MAX_DEPTH = { - docs: 5, + guide: 5, reference: 5, recipes: 0, custom_pages: 0, custom_blocks: 0, }; -function nesting_validateAll(files) { +function nesting_validateAll(files, _gitRoot, { sections = DEFAULT_SECTIONS } = {}) { const results = []; const seen = new Set(); for (const relPath of files) { const parts = relPath.split('/'); const topDir = parts[0]; - const max = MAX_DEPTH[topDir]; + const max = MAX_DEPTH[sections.kindOf(topDir)]; if (max === undefined) continue; // Depth = number of folders between the top dir and the file. @@ -74225,6 +74737,7 @@ function warning(message) { + const command = 'oas:sync'; const order = 2; const category = 'OAS Tooling'; @@ -74266,6 +74779,19 @@ function findOasFiles(refDir) { return oasFiles; } +/** + * Find the OAS files in every reference section of a repo: `reference/`, plus + * any section `_readme.yaml` declares with the `reference` kind. + * + * @returns {Array<{ section: string, refDir: string, filename: string, spec: object }>} + */ +function findAllOasFiles(gitRoot, sections) { + return findReferenceDirs(gitRoot, sections).flatMap(section => { + const refDir = external_node_path_namespaceObject.join(gitRoot, section); + return findOasFiles(refDir).map(oasFile => ({ section, refDir, ...oasFile })); + }); +} + /** * Generate a synthetic operationId from the HTTP method and path. * Matches the algorithm used by the `oas` package for specs without operationIds. @@ -75211,49 +75737,55 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs, assertContained) { } /** - * Sync reference pages with the OpenAPI spec(s) under `/reference/`. + * Sync reference pages with the OpenAPI spec(s) under `/reference/`, + * and under any other reference section the repo declares in `_readme.yaml`. * * Pure programmatic API: returns per-file change descriptors and prints * nothing. Used by the CLI command, the lint --fix flow, and external - * callers. Throws `PathEscapeError` if `reference/` contains a symlink + * callers. Throws `PathEscapeError` if a reference section contains a symlink * (before anything is modified) or a destination would leave it. * Callers report that and exit non-zero. * * @param {string | { cwd?: string }} input Repo root path, or `{ cwd }` object. - * @returns {null | Array<{ filename: string, spec: object, opCount: number, - * changes: { added: string[], deleted: string[], moved: { from, to }[], - * updated: string[], skipped: { path, operationId }[] } }>} - * Returns null if there's no reference/ dir or no specs. + * @returns {null | Array<{ section: string, filename: string, spec: object, + * opCount: number, changes: { added: string[], deleted: string[], + * moved: { from, to }[], updated: string[], skipped: { path, operationId }[] } }>} + * `section` is the directory the spec lives in, and the paths in `changes` + * are relative to it. Returns null if there's no reference dir or no specs. */ function syncOas(input) { const gitRoot = typeof input === 'string' ? input : input?.cwd || process.cwd(); - const refDir = external_node_path_namespaceObject.join(gitRoot, 'reference'); - if (!external_node_fs_namespaceObject.existsSync(refDir)) return null; + const sections = findReferenceDirs(gitRoot); // Before the no-spec return and before any write. `findOasFiles` skips // symlink specs, so a reference/ whose only spec is a link would otherwise // report success and leave pages unsynced. Refusing first also keeps a later // real spec from being half-applied, and keeps a link the page walk would - // have skipped from being deleted or written through. - refuseSymlinks(refDir); + // have skipped from being deleted or written through. Every section is + // checked before any of them is synced, for the same reason. + for (const section of sections) refuseSymlinks(external_node_path_namespaceObject.join(gitRoot, section)); - const oasFiles = findOasFiles(refDir); - if (oasFiles.length === 0) return null; + const allChanges = []; - const assertContained = makeContainment(refDir); + for (const section of sections) { + const refDir = external_node_path_namespaceObject.join(gitRoot, section); + const oasFiles = findOasFiles(refDir); + if (oasFiles.length === 0) continue; - // Reference slugs share one flat namespace across every spec, so build the set - // of in-use slugs once and let each spec read/extend it. - const takenSlugs = collectReferenceSlugs(refDir); - const allChanges = []; + const assertContained = makeContainment(refDir); - for (const { filename, spec } of oasFiles) { - const ops = extractOperations(spec); - const changes = syncOneOas(refDir, filename, spec, takenSlugs, assertContained); - allChanges.push({ filename, spec, opCount: ops.size, changes }); + // Reference slugs share one flat namespace across every spec in a section, + // so build the set of in-use slugs once and let each spec read/extend it. + const takenSlugs = collectReferenceSlugs(refDir); + + for (const { filename, spec } of oasFiles) { + const ops = extractOperations(spec); + const changes = syncOneOas(refDir, filename, spec, takenSlugs, assertContained); + allChanges.push({ section, filename, spec, opCount: ops.size, changes }); + } } - return allChanges; + return allChanges.length > 0 ? allChanges : null; } /** @@ -75265,7 +75797,7 @@ function syncOas(input) { * @param {ReturnType} results * @returns {{ totalAdded: number, totalDeleted: number, totalMoved: number, * totalUpdated: number, totalSkipped: number, - * skipped: Array<{ filename: string, path: string, operationId: string }> }} + * skipped: Array<{ section: string, filename: string, path: string, operationId: string }> }} */ function printSyncResults(results) { let totalAdded = 0; @@ -75275,8 +75807,10 @@ function printSyncResults(results) { let totalSkipped = 0; const skipped = []; - for (const { filename, spec, opCount, changes } of results) { + for (const { section = 'reference', filename, spec, opCount, changes } of results) { const title = spec.info?.title || filename; + // Only name the directory when it isn't the one everybody has. + const specPath = section === 'reference' ? filename : `${section}/${filename}`; const hasChanges = changes.added.length + changes.deleted.length + @@ -75288,7 +75822,7 @@ function printSyncResults(results) { const dot = hasChanges ? warn('●') : success('●'); console.log(); console.log( - ` ${dot} ${bold(title)} ${dim(`(${filename} · ${opCount} ${opCount === 1 ? 'endpoint' : 'endpoints'})`)}`, + ` ${dot} ${bold(title)} ${dim(`(${specPath} · ${opCount} ${opCount === 1 ? 'endpoint' : 'endpoints'})`)}`, ); if (!hasChanges) { @@ -75309,7 +75843,7 @@ function printSyncResults(results) { } for (const { path: file, operationId } of changes.skipped) { console.log(` ${warn('!')} Skipped ${file} for "${operationId}" (destination already exists)`); - skipped.push({ filename, path: file, operationId }); + skipped.push({ section, filename, path: file, operationId }); } totalAdded += changes.added.length; @@ -75324,9 +75858,9 @@ function printSyncResults(results) { async function run(_options, _cmd, ctx) { const { gitRoot } = ctx; - const refDir = external_node_path_namespaceObject.join(gitRoot, 'reference'); + const refDirs = findReferenceDirs(gitRoot); - if (!external_node_fs_namespaceObject.existsSync(refDir)) { + if (refDirs.length === 0) { error('No reference/ directory found.'); writeGithubActionsOutputs({ 'added-count': '0', @@ -75359,7 +75893,7 @@ async function run(_options, _cmd, ctx) { } if (!results) { - info('No OpenAPI spec files found in reference/.'); + info(`No OpenAPI spec files found in ${refDirs.map(dir => `${dir}/`).join(', ')}.`); writeGithubActionsOutputs({ 'added-count': '0', 'deleted-count': '0', @@ -75421,12 +75955,20 @@ async function run(_options, _cmd, ctx) { + const oas_reference_name = 'oas-reference'; -function oas_reference_validateAll(files, gitRoot, { fix } = {}) { - const refDir = external_node_path_namespaceObject.join(gitRoot, 'reference'); - if (!external_node_fs_namespaceObject.existsSync(refDir)) return []; +function oas_reference_validateAll(files, gitRoot, { fix, sections } = {}) { + // Each reference section is checked on its own: a page can only point at a + // spec that lives in the same section as it does. + const results = findReferenceDirs(gitRoot, sections).flatMap(section => validateSection(files, gitRoot, section)); + + applyFixes(results, gitRoot, { fix }); + return results; +} +function validateSection(files, gitRoot, section) { + const refDir = external_node_path_namespaceObject.join(gitRoot, section); const oasFiles = findOasFiles(refDir); const results = []; @@ -75438,7 +75980,7 @@ function oas_reference_validateAll(files, gitRoot, { fix } = {}) { // Check: `x-readme.internal`, which ReadMe ignores for page visibility. for (const location of findIgnoredInternalExtensions(spec)) { results.push({ - file: `reference/${filename}`, + file: `${section}/${filename}`, rule: oas_reference_name, severity: 'warning', message: `"x-readme.internal" is ignored by ReadMe (${location}); use "x-internal" instead to hide pages`, @@ -75448,7 +75990,7 @@ function oas_reference_validateAll(files, gitRoot, { fix } = {}) { } // Collect all reference pages with api frontmatter. - const refPages = files.filter(f => f.startsWith('reference/') && f.endsWith('.md')); + const refPages = files.filter(f => f.startsWith(`${section}/`) && f.endsWith('.md')); for (const relPath of refPages) { const filePath = external_node_path_namespaceObject.join(gitRoot, relPath); @@ -75465,7 +76007,7 @@ function oas_reference_validateAll(files, gitRoot, { fix } = {}) { results.push({ file: relPath, rule: oas_reference_name, - message: `OAS file not found: "${oasFilename}" does not exist in reference/`, + message: `OAS file not found: "${oasFilename}" does not exist in ${section}/`, fixable: false, }); continue; @@ -75498,7 +76040,7 @@ function oas_reference_validateAll(files, gitRoot, { fix } = {}) { for (const op of ops.values()) { if (!coveredOps.has(operationKey(op))) { results.push({ - file: `reference/${oasFilename}`, + file: `${section}/${oasFilename}`, rule: oas_reference_name, severity: 'warning', message: `Missing page: no reference page found for operation "${op.operationId}"`, @@ -75508,6 +76050,10 @@ function oas_reference_validateAll(files, gitRoot, { fix } = {}) { } } + return results; +} + +function applyFixes(results, gitRoot, { fix }) { // Apply fixes by running the full sync — but only when something reported // is actually fixable. The sync adds, deletes, moves, hides and reorders // reference files, which is far too much to do on the strength of an @@ -75533,8 +76079,6 @@ function oas_reference_validateAll(files, gitRoot, { fix } = {}) { }); } } - - return results; } ;// CONCATENATED MODULE: ./node_modules/oas-normalize/dist/chunk-45XXAYDL.js @@ -92042,14 +92586,11 @@ function findBadRefs(obj, pointer = '') { return issues; } -async function oas_schema_validateAll(files, gitRoot) { - const refDir = external_node_path_namespaceObject.join(gitRoot, 'reference'); - if (!external_node_fs_namespaceObject.existsSync(refDir)) return []; - - const oasFiles = findOasFiles(refDir); +async function oas_schema_validateAll(files, gitRoot, { sections } = {}) { + const oasFiles = findAllOasFiles(gitRoot, sections); const results = []; - for (const { filename, spec } of oasFiles) { + for (const { section, refDir, filename, spec } of oasFiles) { const filePath = external_node_path_namespaceObject.join(refDir, filename); const raw = external_node_fs_namespaceObject.readFileSync(filePath, 'utf-8'); @@ -92085,7 +92626,7 @@ async function oas_schema_validateAll(files, gitRoot) { if (!result.valid) { for (const err of result.errors) { results.push({ - file: `reference/${filename}`, + file: `${section}/${filename}`, rule: oas_schema_name, message: err.message, }); @@ -92094,7 +92635,7 @@ async function oas_schema_validateAll(files, gitRoot) { for (const warn of result.warnings) { results.push({ - file: `reference/${filename}`, + file: `${section}/${filename}`, rule: oas_schema_name, severity: 'warning', message: warn.message, @@ -92102,7 +92643,7 @@ async function oas_schema_validateAll(files, gitRoot) { } } catch (err) { results.push({ - file: `reference/${filename}`, + file: `${section}/${filename}`, rule: oas_schema_name, message: err.message || String(err), }); @@ -92111,7 +92652,7 @@ async function oas_schema_validateAll(files, gitRoot) { // Check for malformed $ref pointers (oas-normalize doesn't catch these). for (const { path: refPath, ref } of findBadRefs(spec)) { results.push({ - file: `reference/${filename}`, + file: `${section}/${filename}`, rule: oas_schema_name, message: `Malformed $ref: "${ref}" at ${refPath} (should start with "#/")`, }); @@ -92127,15 +92668,13 @@ async function oas_schema_validateAll(files, gitRoot) { -const ordering_name = 'ordering'; -// Top-level content directories that use _order.yaml. -const ordering_CONTENT_DIRS = ['docs', 'reference', 'recipes', 'custom_pages']; +const ordering_name = 'ordering'; -// Of those, the dirs that must list every page/folder. reference ordering is -// OAS-managed, so we never flag pages "missing from" a reference _order.yaml — -// but stale entries are flagged everywhere. -const REQUIRE_ORDER = new Set(['docs', 'recipes', 'custom_pages']); +// Every section uses _order.yaml, but not every kind has to list each +// page/folder: reference ordering is OAS-managed, so we never flag pages +// "missing from" a reference _order.yaml — stale entries are flagged everywhere. +const REQUIRE_ORDER = new Set(['guide', 'recipes', 'custom_pages']); // Values that YAML interprets as non-strings and need quoting in _order.yaml. const ordering_YAML_UNSAFE = /^(?:\d+\.?\d*|true|false|yes|no|on|off|null|~)$/i; @@ -92224,12 +92763,12 @@ function collectDirs(gitRoot, topDir, assertContained) { * - in _order.yaml but missing on disk → "Stale entry" * - an index entry that shouldn't be listed → "Invalid entry" */ -function ordering_validateAll(files, gitRoot, { fix } = {}) { +function ordering_validateAll(files, gitRoot, { fix, sections = loadSections(gitRoot) } = {}) { const assertContained = makeContainment(gitRoot, { label: 'repository' }); const results = []; - for (const topDir of ordering_CONTENT_DIRS) { - const requireOrder = REQUIRE_ORDER.has(topDir); + for (const topDir of sections.directories()) { + const requireOrder = REQUIRE_ORDER.has(sections.kindOf(topDir)); for (const { dir, onDisk, orderEntries, refused } of collectDirs(gitRoot, topDir, assertContained)) { const orderPath = external_node_path_namespaceObject.join(dir, '_order.yaml'); @@ -92518,21 +93057,23 @@ function recipes_validate({ content, relativePath }) { -const TARGET_PATTERNS = [ - { dir: 'custom_blocks', ext: ['.mdx', '.md'] }, - { dir: 'docs', ext: '.md' }, - { dir: 'reference', ext: '.md' }, - { dir: 'custom_pages', ext: '.md' }, - { dir: 'recipes', ext: '.md' }, -]; + + +/** + * The directories lint reads: custom blocks, the built-in sections, and any + * section the repo declares in `_readme.yaml`. + */ +function targetPatterns(sections) { + return [{ dir: 'custom_blocks', ext: ['.mdx', '.md'] }, ...sections.directories().map(dir => ({ dir, ext: '.md' }))]; +} /** * Collect all target files from the repo root. */ -function collectFiles(gitRoot) { +function collectFiles(gitRoot, sections = loadSections(gitRoot)) { const files = []; - for (const { dir, ext } of TARGET_PATTERNS) { + for (const { dir, ext } of targetPatterns(sections)) { const dirPath = external_node_path_namespaceObject.join(gitRoot, dir); // `readdir` follows a symlink at `dirPath`. A linked content root is not a // directory this walk lists; `lstat` is what sees the link. ordering @@ -92565,6 +93106,7 @@ function collectFiles(gitRoot) { // import above and its module here. const ALL_VALIDATORS = [ components_namespaceObject, + config_namespaceObject, content_namespaceObject, duplicates_namespaceObject, frontmatter_namespaceObject, @@ -92591,13 +93133,14 @@ function loadValidators() { */ async function runValidators(files, gitRoot, { onFile, onBeforeCrossFile, fix, nonInteractive } = {}) { const validators = await loadValidators(); + const sections = loadSections(gitRoot); const results = []; const assertContained = makeContainment(gitRoot, { label: 'repository' }); - // ordering refuses a linked docs/reference/recipes/custom_pages root. - // collectFiles skips every linked root, so a root ordering does not walk - // (custom_blocks) would otherwise lint as a clean repository. - const orderedRoots = new Set(ordering_CONTENT_DIRS); - for (const { dir } of TARGET_PATTERNS) { + // ordering refuses a linked section root (docs, reference, a declared + // section, ...). collectFiles skips every linked root, so a root ordering + // does not walk (custom_blocks) would otherwise lint as a clean repository. + const orderedRoots = new Set(sections.directories()); + for (const { dir } of targetPatterns(sections)) { if (orderedRoots.has(dir)) continue; try { assertContained(external_node_path_namespaceObject.join(gitRoot, dir)); @@ -92645,7 +93188,7 @@ async function runValidators(files, gitRoot, { onFile, onBeforeCrossFile, fix, n for (const validator of validators) { if (!validator.validate) continue; - const result = validator.validate({ filePath, content, relativePath, fix }); + const result = validator.validate({ filePath, content, relativePath, fix, sections }); if (result) { if (Array.isArray(result)) { results.push(...result); @@ -92660,7 +93203,7 @@ async function runValidators(files, gitRoot, { onFile, onBeforeCrossFile, fix, n if (onBeforeCrossFile) onBeforeCrossFile(); for (const validator of validators) { if (!validator.validateAll) continue; - const result = await validator.validateAll(admitted, gitRoot, { fix, nonInteractive }); + const result = await validator.validateAll(admitted, gitRoot, { fix, nonInteractive, sections }); if (result) { if (Array.isArray(result)) { results.push(...result); @@ -96006,6 +96549,7 @@ function getRandomTip(context) { + const isRunningInClaude = !!process.env.CLAUDECODE; const CATEGORY_LABELS = { @@ -96020,7 +96564,8 @@ function categorize(files) { const counts = new Map(); for (const file of files) { const dir = file.split('/')[0]; - const label = CATEGORY_LABELS[dir] || dir; + // `hasOwn`, not a bare lookup: a declared section can be called `constructor`. + const label = Object.hasOwn(CATEGORY_LABELS, dir) ? CATEGORY_LABELS[dir] : dir; counts.set(label, (counts.get(label) || 0) + 1); } return [...counts.entries()]; @@ -96245,10 +96790,19 @@ function createGithubReporter() { const baseSha = process.env.GITHUB_BASE_SHA; if (baseSha && gitRoot) { try { - const changed = (0,external_node_child_process_namespaceObject.execSync)( - `git diff --name-only ${baseSha}..HEAD -- 'reference/*.json' 'reference/*.yaml' 'reference/*.yml'`, - { cwd: gitRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }, - ).trim(); + // Section directories are limited to [a-z0-9_-], so they're safe to + // interpolate into the command. + const pathspecs = findReferenceDirs(gitRoot) + .flatMap(dir => ['json', 'yaml', 'yml'].map(ext => `'${dir}/*.${ext}'`)) + .join(' '); + // With no pathspec git would list every changed file, so skip the diff. + const changed = pathspecs + ? (0,external_node_child_process_namespaceObject.execSync)(`git diff --name-only ${baseSha}..HEAD -- ${pathspecs}`, { + cwd: gitRoot, + encoding: 'utf-8', + stdio: ['pipe', 'pipe', 'pipe'], + }).trim() + : ''; if (changed) { const files = changed.split('\n'); @@ -96385,6 +96939,7 @@ async function lint_run(options, _cmd, ctx) { + const oas_validate_command = 'oas:validate'; const oas_validate_order = 3; const oas_validate_category = 'OAS Tooling'; @@ -96437,8 +96992,9 @@ const RULES = { }; /** - * Validate all OAS files under `/reference/`. Pure programmatic API: - * returns per-file results without printing or exiting. + * Validate all OAS files under `/reference/`, and under any other + * reference section the repo declares in `_readme.yaml`. Pure programmatic + * API: returns per-file results without printing or exiting. * * @param {object} [opts] * @param {string} [opts.cwd] Repo root (defaults to process.cwd()). @@ -96449,6 +97005,7 @@ const RULES = { * totalWarnings: number, * totalValid: number, * results: Array<{ + * section: string, * filename: string, * title: string, * version: string, @@ -96458,14 +97015,12 @@ const RULES = { * valid: boolean, * }>, * }>} - * Returns null if there's no reference/ dir or no spec files. + * `section` is the directory the spec lives in. Returns null if there's no + * reference dir or no spec files. */ async function validateOas({ cwd, dereference = false } = {}) { const gitRoot = cwd || process.cwd(); - const refDir = external_node_path_namespaceObject.join(gitRoot, 'reference'); - if (!external_node_fs_namespaceObject.existsSync(refDir)) return null; - - const oasFiles = findOasFiles(refDir); + const oasFiles = findAllOasFiles(gitRoot); if (oasFiles.length === 0) return null; const results = []; @@ -96473,7 +97028,7 @@ async function validateOas({ cwd, dereference = false } = {}) { let totalWarnings = 0; let totalValid = 0; - for (const { filename, spec } of oasFiles) { + for (const { section, refDir, filename, spec } of oasFiles) { const filePath = external_node_path_namespaceObject.join(refDir, filename); const raw = external_node_fs_namespaceObject.readFileSync(filePath, 'utf-8'); const title = spec.info?.title || filename; @@ -96489,7 +97044,7 @@ async function validateOas({ cwd, dereference = false } = {}) { }); } catch (err) { const errors = [{ message: err.message || String(err) }]; - results.push({ filename, title, version, opCount, errors, warnings: [], valid: false }); + results.push({ section, filename, title, version, opCount, errors, warnings: [], valid: false }); totalErrors += 1; continue; } @@ -96519,7 +97074,7 @@ async function validateOas({ cwd, dereference = false } = {}) { const valid = errors.length === 0; if (valid) totalValid += 1; - results.push({ filename, title, version, opCount, errors, warnings, valid }); + results.push({ section, filename, title, version, opCount, errors, warnings, valid }); } return { fileCount: oasFiles.length, totalErrors, totalWarnings, totalValid, results }; @@ -96537,7 +97092,9 @@ async function validateOasFiles(gitRoot, { dereference = false } = {}) { if (!summary) return null; for (const r of summary.results) { - const meta = `${r.filename} · ${r.version} · ${r.opCount} ${r.opCount === 1 ? 'endpoint' : 'endpoints'}`; + // Only name the directory when it isn't the one everybody has. + const specPath = r.section === 'reference' ? r.filename : `${r.section}/${r.filename}`; + const meta = `${specPath} · ${r.version} · ${r.opCount} ${r.opCount === 1 ? 'endpoint' : 'endpoints'}`; const dot = r.errors.length > 0 ? err('●') : r.warnings.length > 0 ? warn('●') : success('●'); console.log(); @@ -96557,9 +97114,9 @@ async function validateOasFiles(gitRoot, { dereference = false } = {}) { async function oas_validate_run(options, _cmd, ctx) { const { gitRoot } = ctx; - const refDir = external_node_path_namespaceObject.join(gitRoot, 'reference'); + const refDirs = findReferenceDirs(gitRoot); - if (!external_node_fs_namespaceObject.existsSync(refDir)) { + if (refDirs.length === 0) { error('No reference/ directory found.'); writeGithubActionsOutputs({ 'has-errors': 'true', @@ -96574,7 +97131,7 @@ async function oas_validate_run(options, _cmd, ctx) { const result = await validateOasFiles(gitRoot, { dereference: options.dereference }); if (!result) { - info('No OpenAPI spec files found in reference/.'); + info(`No OpenAPI spec files found in ${refDirs.map(dir => `${dir}/`).join(', ')}.`); writeGithubActionsOutputs({ 'has-errors': 'false', 'total-errors': '0', diff --git a/src/bootstrap.js b/src/bootstrap.js index 2fb522d..4429795 100644 --- a/src/bootstrap.js +++ b/src/bootstrap.js @@ -5,6 +5,7 @@ import path from 'node:path'; import updateNotifier from 'update-notifier'; +import { loadSections } from './utils/sections.js'; import * as styles from './utils/styles.js'; const require = createRequire(import.meta.url); @@ -71,17 +72,19 @@ function validateReadMeRepo(gitRoot) { const hasVersionBranch = branches.split('\n').some(b => /^(origin\/)?v[0-9]/.test(b.trim())); - // Check for /docs or /reference at the repo root - const hasDocs = fs.existsSync(path.join(gitRoot, 'docs')); - const hasReference = fs.existsSync(path.join(gitRoot, 'reference')); + // Check for /docs or /reference at the repo root, or a section the repo + // declares in _readme.yaml (a project doesn't have to use the built-in ones) + const hasContent = ['docs', 'reference', ...loadSections(gitRoot).declaredDirectories()].some(dir => + fs.existsSync(path.join(gitRoot, dir)), + ); - if (!hasVersionBranch || (!hasDocs && !hasReference)) { + if (!hasVersionBranch || !hasContent) { styles.error("This doesn't look like a ReadMe docs repo."); if (!hasVersionBranch) { styles.info(`We couldn't find a version branch (e.g. ${styles.bold('v1')}, ${styles.bold('v2')}).`); } - if (!hasDocs && !hasReference) { + if (!hasContent) { styles.info(`We couldn't find a ${styles.bold('/docs')} or ${styles.bold('/reference')} folder.`); } diff --git a/src/commands/oas-sync.js b/src/commands/oas-sync.js index aebe956..aad06c5 100644 --- a/src/commands/oas-sync.js +++ b/src/commands/oas-sync.js @@ -6,6 +6,7 @@ import { CORE_SCHEMA, load as loadYAML, mergeTag } from 'js-yaml'; import { makeContainment, PathEscapeError } from '../utils/containment.js'; import { writeGithubActionsOutputs } from '../utils/gha-output.js'; import { parseFrontmatter, toFrontmatter, frontmatterWriteError } from '../utils/markdown.js'; +import { findReferenceDirs } from '../utils/sections.js'; import * as styles from '../utils/styles.js'; export const command = 'oas:sync'; @@ -49,6 +50,19 @@ export function findOasFiles(refDir) { return oasFiles; } +/** + * Find the OAS files in every reference section of a repo: `reference/`, plus + * any section `_readme.yaml` declares with the `reference` kind. + * + * @returns {Array<{ section: string, refDir: string, filename: string, spec: object }>} + */ +export function findAllOasFiles(gitRoot, sections) { + return findReferenceDirs(gitRoot, sections).flatMap(section => { + const refDir = path.join(gitRoot, section); + return findOasFiles(refDir).map(oasFile => ({ section, refDir, ...oasFile })); + }); +} + /** * Generate a synthetic operationId from the HTTP method and path. * Matches the algorithm used by the `oas` package for specs without operationIds. @@ -994,49 +1008,55 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs, assertContained) { } /** - * Sync reference pages with the OpenAPI spec(s) under `/reference/`. + * Sync reference pages with the OpenAPI spec(s) under `/reference/`, + * and under any other reference section the repo declares in `_readme.yaml`. * * Pure programmatic API: returns per-file change descriptors and prints * nothing. Used by the CLI command, the lint --fix flow, and external - * callers. Throws `PathEscapeError` if `reference/` contains a symlink + * callers. Throws `PathEscapeError` if a reference section contains a symlink * (before anything is modified) or a destination would leave it. * Callers report that and exit non-zero. * * @param {string | { cwd?: string }} input Repo root path, or `{ cwd }` object. - * @returns {null | Array<{ filename: string, spec: object, opCount: number, - * changes: { added: string[], deleted: string[], moved: { from, to }[], - * updated: string[], skipped: { path, operationId }[] } }>} - * Returns null if there's no reference/ dir or no specs. + * @returns {null | Array<{ section: string, filename: string, spec: object, + * opCount: number, changes: { added: string[], deleted: string[], + * moved: { from, to }[], updated: string[], skipped: { path, operationId }[] } }>} + * `section` is the directory the spec lives in, and the paths in `changes` + * are relative to it. Returns null if there's no reference dir or no specs. */ export function syncOas(input) { const gitRoot = typeof input === 'string' ? input : input?.cwd || process.cwd(); - const refDir = path.join(gitRoot, 'reference'); - if (!fs.existsSync(refDir)) return null; + const sections = findReferenceDirs(gitRoot); // Before the no-spec return and before any write. `findOasFiles` skips // symlink specs, so a reference/ whose only spec is a link would otherwise // report success and leave pages unsynced. Refusing first also keeps a later // real spec from being half-applied, and keeps a link the page walk would - // have skipped from being deleted or written through. - refuseSymlinks(refDir); + // have skipped from being deleted or written through. Every section is + // checked before any of them is synced, for the same reason. + for (const section of sections) refuseSymlinks(path.join(gitRoot, section)); - const oasFiles = findOasFiles(refDir); - if (oasFiles.length === 0) return null; + const allChanges = []; - const assertContained = makeContainment(refDir); + for (const section of sections) { + const refDir = path.join(gitRoot, section); + const oasFiles = findOasFiles(refDir); + if (oasFiles.length === 0) continue; - // Reference slugs share one flat namespace across every spec, so build the set - // of in-use slugs once and let each spec read/extend it. - const takenSlugs = collectReferenceSlugs(refDir); - const allChanges = []; + const assertContained = makeContainment(refDir); - for (const { filename, spec } of oasFiles) { - const ops = extractOperations(spec); - const changes = syncOneOas(refDir, filename, spec, takenSlugs, assertContained); - allChanges.push({ filename, spec, opCount: ops.size, changes }); + // Reference slugs share one flat namespace across every spec in a section, + // so build the set of in-use slugs once and let each spec read/extend it. + const takenSlugs = collectReferenceSlugs(refDir); + + for (const { filename, spec } of oasFiles) { + const ops = extractOperations(spec); + const changes = syncOneOas(refDir, filename, spec, takenSlugs, assertContained); + allChanges.push({ section, filename, spec, opCount: ops.size, changes }); + } } - return allChanges; + return allChanges.length > 0 ? allChanges : null; } /** @@ -1048,7 +1068,7 @@ export function syncOas(input) { * @param {ReturnType} results * @returns {{ totalAdded: number, totalDeleted: number, totalMoved: number, * totalUpdated: number, totalSkipped: number, - * skipped: Array<{ filename: string, path: string, operationId: string }> }} + * skipped: Array<{ section: string, filename: string, path: string, operationId: string }> }} */ export function printSyncResults(results) { let totalAdded = 0; @@ -1058,8 +1078,10 @@ export function printSyncResults(results) { let totalSkipped = 0; const skipped = []; - for (const { filename, spec, opCount, changes } of results) { + for (const { section = 'reference', filename, spec, opCount, changes } of results) { const title = spec.info?.title || filename; + // Only name the directory when it isn't the one everybody has. + const specPath = section === 'reference' ? filename : `${section}/${filename}`; const hasChanges = changes.added.length + changes.deleted.length + @@ -1071,7 +1093,7 @@ export function printSyncResults(results) { const dot = hasChanges ? styles.warn('●') : styles.success('●'); console.log(); console.log( - ` ${dot} ${styles.bold(title)} ${styles.dim(`(${filename} · ${opCount} ${opCount === 1 ? 'endpoint' : 'endpoints'})`)}`, + ` ${dot} ${styles.bold(title)} ${styles.dim(`(${specPath} · ${opCount} ${opCount === 1 ? 'endpoint' : 'endpoints'})`)}`, ); if (!hasChanges) { @@ -1092,7 +1114,7 @@ export function printSyncResults(results) { } for (const { path: file, operationId } of changes.skipped) { console.log(` ${styles.warn('!')} Skipped ${file} for "${operationId}" (destination already exists)`); - skipped.push({ filename, path: file, operationId }); + skipped.push({ section, filename, path: file, operationId }); } totalAdded += changes.added.length; @@ -1107,9 +1129,9 @@ export function printSyncResults(results) { export async function run(_options, _cmd, ctx) { const { gitRoot } = ctx; - const refDir = path.join(gitRoot, 'reference'); + const refDirs = findReferenceDirs(gitRoot); - if (!fs.existsSync(refDir)) { + if (refDirs.length === 0) { styles.error('No reference/ directory found.'); writeGithubActionsOutputs({ 'added-count': '0', @@ -1142,7 +1164,7 @@ export async function run(_options, _cmd, ctx) { } if (!results) { - styles.info('No OpenAPI spec files found in reference/.'); + styles.info(`No OpenAPI spec files found in ${refDirs.map(dir => `${dir}/`).join(', ')}.`); writeGithubActionsOutputs({ 'added-count': '0', 'deleted-count': '0', diff --git a/src/commands/oas-validate.js b/src/commands/oas-validate.js index 07ac13f..21cde95 100644 --- a/src/commands/oas-validate.js +++ b/src/commands/oas-validate.js @@ -4,9 +4,10 @@ import path from 'node:path'; import OASNormalize from 'oas-normalize'; import { writeGithubActionsOutputs } from '../utils/gha-output.js'; +import { findReferenceDirs } from '../utils/sections.js'; import * as styles from '../utils/styles.js'; -import { findOasFiles, extractOperations } from './oas-sync.js'; +import { findAllOasFiles, extractOperations } from './oas-sync.js'; export const command = 'oas:validate'; export const order = 3; @@ -60,8 +61,9 @@ const RULES = { }; /** - * Validate all OAS files under `/reference/`. Pure programmatic API: - * returns per-file results without printing or exiting. + * Validate all OAS files under `/reference/`, and under any other + * reference section the repo declares in `_readme.yaml`. Pure programmatic + * API: returns per-file results without printing or exiting. * * @param {object} [opts] * @param {string} [opts.cwd] Repo root (defaults to process.cwd()). @@ -72,6 +74,7 @@ const RULES = { * totalWarnings: number, * totalValid: number, * results: Array<{ + * section: string, * filename: string, * title: string, * version: string, @@ -81,14 +84,12 @@ const RULES = { * valid: boolean, * }>, * }>} - * Returns null if there's no reference/ dir or no spec files. + * `section` is the directory the spec lives in. Returns null if there's no + * reference dir or no spec files. */ export async function validateOas({ cwd, dereference = false } = {}) { const gitRoot = cwd || process.cwd(); - const refDir = path.join(gitRoot, 'reference'); - if (!fs.existsSync(refDir)) return null; - - const oasFiles = findOasFiles(refDir); + const oasFiles = findAllOasFiles(gitRoot); if (oasFiles.length === 0) return null; const results = []; @@ -96,7 +97,7 @@ export async function validateOas({ cwd, dereference = false } = {}) { let totalWarnings = 0; let totalValid = 0; - for (const { filename, spec } of oasFiles) { + for (const { section, refDir, filename, spec } of oasFiles) { const filePath = path.join(refDir, filename); const raw = fs.readFileSync(filePath, 'utf-8'); const title = spec.info?.title || filename; @@ -112,7 +113,7 @@ export async function validateOas({ cwd, dereference = false } = {}) { }); } catch (err) { const errors = [{ message: err.message || String(err) }]; - results.push({ filename, title, version, opCount, errors, warnings: [], valid: false }); + results.push({ section, filename, title, version, opCount, errors, warnings: [], valid: false }); totalErrors += 1; continue; } @@ -142,7 +143,7 @@ export async function validateOas({ cwd, dereference = false } = {}) { const valid = errors.length === 0; if (valid) totalValid += 1; - results.push({ filename, title, version, opCount, errors, warnings, valid }); + results.push({ section, filename, title, version, opCount, errors, warnings, valid }); } return { fileCount: oasFiles.length, totalErrors, totalWarnings, totalValid, results }; @@ -160,7 +161,9 @@ export async function validateOasFiles(gitRoot, { dereference = false } = {}) { if (!summary) return null; for (const r of summary.results) { - const meta = `${r.filename} · ${r.version} · ${r.opCount} ${r.opCount === 1 ? 'endpoint' : 'endpoints'}`; + // Only name the directory when it isn't the one everybody has. + const specPath = r.section === 'reference' ? r.filename : `${r.section}/${r.filename}`; + const meta = `${specPath} · ${r.version} · ${r.opCount} ${r.opCount === 1 ? 'endpoint' : 'endpoints'}`; const dot = r.errors.length > 0 ? styles.err('●') : r.warnings.length > 0 ? styles.warn('●') : styles.success('●'); console.log(); @@ -180,9 +183,9 @@ export async function validateOasFiles(gitRoot, { dereference = false } = {}) { export async function run(options, _cmd, ctx) { const { gitRoot } = ctx; - const refDir = path.join(gitRoot, 'reference'); + const refDirs = findReferenceDirs(gitRoot); - if (!fs.existsSync(refDir)) { + if (refDirs.length === 0) { styles.error('No reference/ directory found.'); writeGithubActionsOutputs({ 'has-errors': 'true', @@ -197,7 +200,7 @@ export async function run(options, _cmd, ctx) { const result = await validateOasFiles(gitRoot, { dereference: options.dereference }); if (!result) { - styles.info('No OpenAPI spec files found in reference/.'); + styles.info(`No OpenAPI spec files found in ${refDirs.map(dir => `${dir}/`).join(', ')}.`); writeGithubActionsOutputs({ 'has-errors': 'false', 'total-errors': '0', diff --git a/src/dev/lib/docs.js b/src/dev/lib/docs.js index ababf1a..b3410a9 100644 --- a/src/dev/lib/docs.js +++ b/src/dev/lib/docs.js @@ -6,6 +6,7 @@ import { compile, run } from '@readme/markdown'; import { load as loadYAML } from 'js-yaml'; import { parseFrontmatter } from '../../utils/markdown.js'; +import { loadSections } from '../../utils/sections.js'; // Use createRequire to load react-dom/server at runtime, // bypassing Next.js App Router's static import restriction. @@ -15,23 +16,17 @@ const { renderToStaticMarkup } = _require('react-dom/server'); const DOCS_ROOT = process.env.DOCS_ROOT; -const SECTIONS = [ - { dir: 'docs', label: 'Docs' }, - { dir: 'reference', label: 'Reference' }, - { dir: 'custom_pages', label: 'Custom Pages' }, - { dir: 'recipes', label: 'Recipes' }, -]; - -// Max folder nesting per section — anything deeper doesn't render in ReadMe's -// sidebar, so we mirror the cap here. Keep in sync with src/validators/nesting.js. +// Max folder nesting per kind of section — anything deeper doesn't render in +// ReadMe's sidebar, so we mirror the cap here. Keep in sync with +// src/validators/nesting.js. const MAX_DEPTH = { - docs: 5, + guide: 5, reference: 5, recipes: 0, custom_pages: 0, }; -function walkDir(dirPath, sectionDir, depth = 0) { +function walkDir(dirPath, sectionDir, maxDepth, depth = 0) { if (!fs.existsSync(dirPath)) return []; // Read _order.yaml for ordering @@ -69,10 +64,9 @@ function walkDir(dirPath, sectionDir, depth = 0) { if (isDir) { // Skip folders whose contents would exceed ReadMe's sidebar nesting // cap — they won't render in production, so don't show them here either. - const maxDepth = MAX_DEPTH[sectionDir]; if (maxDepth !== undefined && depth + 1 > maxDepth) continue; - const children = walkDir(path.join(dirPath, name), sectionDir, depth + 1); + const children = walkDir(path.join(dirPath, name), sectionDir, maxDepth, depth + 1); // ReadMeConfig pages are internal — show them without a group header if (name === 'ReadMeConfig') { @@ -130,11 +124,15 @@ function walkDir(dirPath, sectionDir, depth = 0) { export function collectSidebar() { const sections = []; - for (const { dir, label } of SECTIONS) { + // The built-in sections, plus any the repo declares in _readme.yaml — read + // on every request so edits to the file show up on reload. + const declared = loadSections(DOCS_ROOT); + for (const dir of declared.order) { + const { label, kind } = declared.byDirectory.get(dir); const fullPath = path.join(DOCS_ROOT, dir); if (!fs.existsSync(fullPath)) continue; - const children = walkDir(fullPath, dir); + const children = walkDir(fullPath, dir, MAX_DEPTH[kind]); if (children.length > 0) { sections.push({ title: label, dir, firstHref: findFirstHref(children), children }); } @@ -212,7 +210,7 @@ export function getPage(slugArray) { // used to show a blank page. If we see `api.file` + `api.operationId`, // render a minimal preview from the spec so the page isn't empty. if (data.api?.file && data.api?.operationId && !content.trim()) { - html = renderOasOperationPreview(data.api.file, data.api.operationId); + html = renderOasOperationPreview(section, data.api.file, data.api.operationId); } else { try { const { sources, modules } = loadCustomBlocks(DOCS_ROOT); @@ -245,10 +243,10 @@ export function getPage(slugArray) { * (production ReadMe handles that); just enough so dev server pages show * something meaningful instead of a blank body. */ -function renderOasOperationPreview(specFile, operationId) { - const specPath = path.join(DOCS_ROOT, 'reference', specFile); +function renderOasOperationPreview(section, specFile, operationId) { + const specPath = path.join(DOCS_ROOT, section, specFile); if (!fs.existsSync(specPath)) { - return `

OAS spec not found: reference/${specFile}

`; + return `

OAS spec not found: ${escapeHtml(section)}/${escapeHtml(specFile)}

`; } let spec; @@ -256,7 +254,7 @@ function renderOasOperationPreview(specFile, operationId) { const rawSpec = fs.readFileSync(specPath, 'utf-8'); spec = specFile.toLowerCase().endsWith('.json') ? JSON.parse(rawSpec) : loadYAML(rawSpec); } catch (e) { - return `

Couldn't parse reference/${specFile}: ${escapeHtml(e.message)}

`; + return `

Couldn't parse ${escapeHtml(section)}/${escapeHtml(specFile)}: ${escapeHtml(e.message)}

`; } let found = null; diff --git a/src/utils/lint.js b/src/utils/lint.js index dbbb23a..3271362 100644 --- a/src/utils/lint.js +++ b/src/utils/lint.js @@ -2,6 +2,7 @@ import fs from 'node:fs'; import path from 'node:path'; import * as componentsValidator from '../validators/components.js'; +import * as configValidator from '../validators/config.js'; import * as contentValidator from '../validators/content.js'; import * as duplicatesValidator from '../validators/duplicates.js'; import * as frontmatterValidator from '../validators/frontmatter.js'; @@ -13,22 +14,23 @@ import * as orderingValidator from '../validators/ordering.js'; import * as recipesValidator from '../validators/recipes.js'; import { makeContainment, PathEscapeError } from './containment.js'; +import { loadSections } from './sections.js'; -const TARGET_PATTERNS = [ - { dir: 'custom_blocks', ext: ['.mdx', '.md'] }, - { dir: 'docs', ext: '.md' }, - { dir: 'reference', ext: '.md' }, - { dir: 'custom_pages', ext: '.md' }, - { dir: 'recipes', ext: '.md' }, -]; +/** + * The directories lint reads: custom blocks, the built-in sections, and any + * section the repo declares in `_readme.yaml`. + */ +function targetPatterns(sections) { + return [{ dir: 'custom_blocks', ext: ['.mdx', '.md'] }, ...sections.directories().map(dir => ({ dir, ext: '.md' }))]; +} /** * Collect all target files from the repo root. */ -export function collectFiles(gitRoot) { +export function collectFiles(gitRoot, sections = loadSections(gitRoot)) { const files = []; - for (const { dir, ext } of TARGET_PATTERNS) { + for (const { dir, ext } of targetPatterns(sections)) { const dirPath = path.join(gitRoot, dir); // `readdir` follows a symlink at `dirPath`. A linked content root is not a // directory this walk lists; `lstat` is what sees the link. ordering @@ -61,6 +63,7 @@ export function collectFiles(gitRoot) { // import above and its module here. const ALL_VALIDATORS = [ componentsValidator, + configValidator, contentValidator, duplicatesValidator, frontmatterValidator, @@ -87,13 +90,14 @@ function loadValidators() { */ export async function runValidators(files, gitRoot, { onFile, onBeforeCrossFile, fix, nonInteractive } = {}) { const validators = await loadValidators(); + const sections = loadSections(gitRoot); const results = []; const assertContained = makeContainment(gitRoot, { label: 'repository' }); - // ordering refuses a linked docs/reference/recipes/custom_pages root. - // collectFiles skips every linked root, so a root ordering does not walk - // (custom_blocks) would otherwise lint as a clean repository. - const orderedRoots = new Set(orderingValidator.CONTENT_DIRS); - for (const { dir } of TARGET_PATTERNS) { + // ordering refuses a linked section root (docs, reference, a declared + // section, ...). collectFiles skips every linked root, so a root ordering + // does not walk (custom_blocks) would otherwise lint as a clean repository. + const orderedRoots = new Set(sections.directories()); + for (const { dir } of targetPatterns(sections)) { if (orderedRoots.has(dir)) continue; try { assertContained(path.join(gitRoot, dir)); @@ -141,7 +145,7 @@ export async function runValidators(files, gitRoot, { onFile, onBeforeCrossFile, for (const validator of validators) { if (!validator.validate) continue; - const result = validator.validate({ filePath, content, relativePath, fix }); + const result = validator.validate({ filePath, content, relativePath, fix, sections }); if (result) { if (Array.isArray(result)) { results.push(...result); @@ -156,7 +160,7 @@ export async function runValidators(files, gitRoot, { onFile, onBeforeCrossFile, if (onBeforeCrossFile) onBeforeCrossFile(); for (const validator of validators) { if (!validator.validateAll) continue; - const result = await validator.validateAll(admitted, gitRoot, { fix, nonInteractive }); + const result = await validator.validateAll(admitted, gitRoot, { fix, nonInteractive, sections }); if (result) { if (Array.isArray(result)) { results.push(...result); diff --git a/src/utils/reporter.js b/src/utils/reporter.js index 65675a6..5776480 100644 --- a/src/utils/reporter.js +++ b/src/utils/reporter.js @@ -15,6 +15,7 @@ import { hasReadmeWorkflow, PLATFORMS, } from './git.js'; +import { findReferenceDirs } from './sections.js'; import * as styles from './styles.js'; import { getRandomTip } from './tips.js'; @@ -32,7 +33,8 @@ function categorize(files) { const counts = new Map(); for (const file of files) { const dir = file.split('/')[0]; - const label = CATEGORY_LABELS[dir] || dir; + // `hasOwn`, not a bare lookup: a declared section can be called `constructor`. + const label = Object.hasOwn(CATEGORY_LABELS, dir) ? CATEGORY_LABELS[dir] : dir; counts.set(label, (counts.get(label) || 0) + 1); } return [...counts.entries()]; @@ -257,10 +259,19 @@ export function createGithubReporter() { const baseSha = process.env.GITHUB_BASE_SHA; if (baseSha && gitRoot) { try { - const changed = execSync( - `git diff --name-only ${baseSha}..HEAD -- 'reference/*.json' 'reference/*.yaml' 'reference/*.yml'`, - { cwd: gitRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }, - ).trim(); + // Section directories are limited to [a-z0-9_-], so they're safe to + // interpolate into the command. + const pathspecs = findReferenceDirs(gitRoot) + .flatMap(dir => ['json', 'yaml', 'yml'].map(ext => `'${dir}/*.${ext}'`)) + .join(' '); + // With no pathspec git would list every changed file, so skip the diff. + const changed = pathspecs + ? execSync(`git diff --name-only ${baseSha}..HEAD -- ${pathspecs}`, { + cwd: gitRoot, + encoding: 'utf-8', + stdio: ['pipe', 'pipe', 'pipe'], + }).trim() + : ''; if (changed) { const files = changed.split('\n'); diff --git a/src/utils/sections.js b/src/utils/sections.js new file mode 100644 index 0000000..27995e7 --- /dev/null +++ b/src/utils/sections.js @@ -0,0 +1,257 @@ +import fs from 'node:fs'; +import path from 'node:path'; + +import { CORE_SCHEMA, load as loadYAML } from 'js-yaml'; + +/** + * Sections are the top-level content directories of a ReadMe repo. + * + * Every project has the built-in ones (`docs`, `reference`, `recipes`, + * `custom_pages`). Projects with multiple guides declare more in a + * `_readme.yaml` file at the repo root: + * + * navigation: + * - kind: guide + * directory: docs + * name: Guides + * - kind: guide + * directory: sdks + * name: SDKs + * - kind: reference + * directory: apis + * + * The file is optional. A repo without one (every repo from before the + * feature) resolves to just the built-ins, exactly as ReadMe itself does. + * The rules here mirror the ones ReadMe applies when it reads the file. + */ + +export const CONFIG_FILE = '_readme.yaml'; + +/** Allowed shape for a section `directory`. */ +export const SECTION_DIRECTORY_REGEX = /^[a-z0-9][a-z0-9_-]{0,29}$/; + +/** Built-in directories, and the one kind each is locked to. */ +export const BUILT_IN_KINDS = { + changelogs: 'changelog', + custom_pages: 'custom_pages', + docs: 'guide', + recipes: 'recipes', + reference: 'reference', + skills: 'skill', +}; + +/** Kinds a non-built-in directory may declare. */ +export const DECLARABLE_KINDS = ['guide', 'reference']; + +/** Kinds whose `navigation` entry owns a top-level directory. */ +export const DIRECTORY_KINDS = ['guide', 'recipes', 'reference', 'skill']; + +/** Kinds that may appear only once, and point at nothing. */ +export const SINGLETON_KINDS = ['changelog', 'discuss', 'home', 'version']; + +/** Directories that can never be declared as a section. */ +export const RESERVED_DIRECTORIES = new Set([ + // Owned by ReadMe's storage. + 'custom_blocks', + 'llms_txt', + 'apidefinition', + 'api_config', + // `docs` is served at /guides, so a directory of that name would collide. + 'guides', + // URL segments the hub routes itself. + 'admin', + 'api', + 'auth', + 'blog', + 'chatgpt', + 'comments', + 'custom-login', + 'dash', + 'discuss', + 'discuss-new', + 'edit', + 'graphql', + 'inactive', + 'login', + 'login-webhook', + 'logout', + 'logs', + 'mcp', + 'oauth', + 'oauth2-redirect', + 'og-image', + 'openapi', + 'password', + 'reference-link', + 'suggested-edits', + 'throw-error', + 'unvalidated', +]); + +// The sections the CLI has always handled, in the order it lists them. +const BUILT_IN_SECTIONS = [ + { directory: 'docs', kind: 'guide', label: 'Docs' }, + { directory: 'reference', kind: 'reference', label: 'Reference' }, + { directory: 'custom_pages', kind: 'custom_pages', label: 'Custom Pages' }, + { directory: 'recipes', kind: 'recipes', label: 'Recipes' }, +]; + +// What ReadMe calls a built-in section that `_readme.yaml` lists without a name. +const DEFAULT_SECTION_NAMES = { + docs: 'Guides', + reference: 'API Reference', + recipes: 'Recipes', + custom_pages: 'Custom Pages', +}; + +export function isBuiltInDirectory(directory) { + return Object.hasOwn(BUILT_IN_KINDS, directory); +} + +/** Whether a directory could be declared as a section of its own. */ +export function isDeclarableDirectory(directory) { + return ( + typeof directory === 'string' && + SECTION_DIRECTORY_REGEX.test(directory) && + !isBuiltInDirectory(directory) && + !RESERVED_DIRECTORIES.has(directory) + ); +} + +/** + * Parse `_readme.yaml` content the way ReadMe does: core YAML types only, so a + * directory called `2026-07-31` stays a string rather than becoming a date. + * + * @returns {{ config: object | null, error: string | null }} + */ +export function parseConfig(content) { + let parsed; + try { + parsed = loadYAML(content, { json: true, schema: CORE_SCHEMA }); + } catch (err) { + return { config: null, error: err.reason || err.message || 'invalid YAML' }; + } + if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) { + return { config: null, error: 'must be a YAML object' }; + } + return { config: parsed, error: null }; +} + +class Sections { + constructor({ exists, config, error, list, order }) { + /** Whether the repo has a `_readme.yaml`. */ + this.exists = exists; + /** The parsed file, or null when it's missing or unreadable. */ + this.config = config; + /** Why the file couldn't be parsed, or null. */ + this.error = error; + this.list = list; + /** Directories in the order `_readme.yaml` lists them, the rest after. */ + this.order = [...new Set([...(order || []), ...list.map(section => section.directory)])]; + this.byDirectory = new Map(list.map(section => [section.directory, section])); + } + + /** The kind of a top-level directory, or undefined when it isn't a section. */ + kindOf(directory) { + if (directory === 'custom_blocks') return 'custom_blocks'; + return this.byDirectory.get(directory)?.kind; + } + + /** Every directory that holds pages: the built-ins plus the declared ones. */ + directories() { + return this.list.map(section => section.directory); + } + + /** The directories of the given kind(s), e.g. every API reference. */ + directoriesOfKind(...kinds) { + return this.list.filter(section => kinds.includes(section.kind)).map(section => section.directory); + } + + /** The directories declared in `_readme.yaml` on top of the built-ins. */ + declaredDirectories() { + return this.list.filter(section => !section.builtIn).map(section => section.directory); + } +} + +/** + * The API reference directories that exist in a repo: `reference`, plus any + * section `_readme.yaml` declares with the `reference` kind. + */ +export function findReferenceDirs(gitRoot, sections = loadSections(gitRoot)) { + return sections.directoriesOfKind('reference').filter(directory => { + try { + return fs.statSync(path.join(gitRoot, directory)).isDirectory(); + } catch { + return false; + } + }); +} + +/** The sections of a repo with no `_readme.yaml`. */ +export const DEFAULT_SECTIONS = new Sections({ + exists: false, + config: null, + error: null, + list: BUILT_IN_SECTIONS.map(section => ({ ...section, builtIn: true, hidden: false })), +}); + +/** + * Resolve a repo's sections from its `_readme.yaml`. + * + * Never throws: a missing, unparseable, or partly invalid file still resolves + * (to the built-ins, plus whichever declared sections are usable), so one bad + * entry doesn't stop the rest of the repo from being linted. Reporting what's + * wrong with the file is the `config` validator's job. + */ +export function loadSections(gitRoot) { + const configPath = path.join(gitRoot, CONFIG_FILE); + + let content; + try { + // `readFile` follows a symlink, and a linked config could declare sections + // from a file outside the repo. Like every other linked path, it's refused. + if (fs.lstatSync(configPath).isSymbolicLink()) { + return new Sections({ + exists: true, + config: null, + error: 'symbolic links are not followed', + list: BUILT_IN_SECTIONS.map(section => ({ ...section, builtIn: true, hidden: false })), + }); + } + content = fs.readFileSync(configPath, 'utf-8'); + } catch { + return DEFAULT_SECTIONS; + } + + const { config, error } = parseConfig(content); + const navigation = Array.isArray(config?.navigation) ? config.navigation : []; + + const list = BUILT_IN_SECTIONS.map(section => ({ ...section, builtIn: true, hidden: false })); + const byDirectory = new Map(list.map(section => [section.directory, section])); + const order = []; + + for (const entry of navigation) { + if (!entry || typeof entry !== 'object' || typeof entry.directory !== 'string') continue; + const { directory, kind } = entry; + const name = typeof entry.name === 'string' && entry.name ? entry.name : null; + + const builtIn = byDirectory.get(directory); + if (builtIn?.builtIn) { + // A built-in keeps its kind whatever the file says; only its label and + // visibility are the file's to set. + builtIn.label = name || DEFAULT_SECTION_NAMES[directory]; + builtIn.hidden = entry.hidden === true; + if (!order.includes(directory)) order.push(directory); + continue; + } + + if (builtIn || !isDeclarableDirectory(directory) || !DECLARABLE_KINDS.includes(kind)) continue; + + const section = { directory, kind, label: name || directory, builtIn: false, hidden: entry.hidden === true }; + list.push(section); + byDirectory.set(directory, section); + order.push(directory); + } + + return new Sections({ exists: true, config, error, list, order }); +} diff --git a/src/validators/components.js b/src/validators/components.js index 4bc3638..27a1e90 100644 --- a/src/validators/components.js +++ b/src/validators/components.js @@ -4,6 +4,7 @@ import path from 'node:path'; import markdown from '@readme/markdown'; import { parseFrontmatter } from '../utils/markdown.js'; +import { loadSections } from '../utils/sections.js'; const { mdxishTags } = markdown; @@ -39,9 +40,6 @@ const BUILTIN_COMPONENTS = new Set([ 'TutorialTile', ]); -// Directories that can contain MDXish content with component references. -const CONTENT_DIRS = new Set(['docs', 'reference', 'custom_pages', 'recipes']); - /** * Extract component tag names from MDXish content. * Parses via @readme/markdown's mdxishTags so code blocks, inline code, and @@ -190,14 +188,16 @@ export function validate({ content, relativePath }) { /** * Cross-file: check that all component references in content files resolve. */ -export function validateAll(files, gitRoot) { +export function validateAll(files, gitRoot, { sections = loadSections(gitRoot) } = {}) { const results = []; + // Every section can contain MDXish content with component references. + const contentDirs = new Set(sections.directories()); const customBlocks = collectCustomBlockNames(gitRoot); const available = new Set([...BUILTIN_COMPONENTS, ...customBlocks]); for (const relPath of files) { const dir = relPath.split('/')[0]; - if (!CONTENT_DIRS.has(dir)) continue; + if (!contentDirs.has(dir)) continue; if (!relPath.endsWith('.md')) continue; const filePath = path.join(gitRoot, relPath); diff --git a/src/validators/config.js b/src/validators/config.js new file mode 100644 index 0000000..eeb5668 --- /dev/null +++ b/src/validators/config.js @@ -0,0 +1,247 @@ +import fs from 'node:fs'; +import path from 'node:path'; + +import { + BUILT_IN_KINDS, + CONFIG_FILE, + DECLARABLE_KINDS, + DIRECTORY_KINDS, + RESERVED_DIRECTORIES, + SECTION_DIRECTORY_REGEX, + SINGLETON_KINDS, + isBuiltInDirectory, + loadSections, +} from '../utils/sections.js'; + +export const name = 'config'; + +// Fields every `navigation` entry may carry, plus the one its kind points at. +const COMMON_KEYS = ['kind', 'name', 'hidden', 'icon']; +// The fields that say what an entry points at. Each belongs to certain kinds. +const TARGET_KEYS = ['directory', 'slug', 'url']; +// Custom pages are markdown or raw HTML. +const CUSTOM_PAGE_EXTENSIONS = ['md', 'mdx', 'html']; +const KNOWN_KINDS = [...DIRECTORY_KINDS, ...SINGLETON_KINDS, 'custom_pages', 'url']; + +function targetKeyFor(kind) { + if (DIRECTORY_KINDS.includes(kind)) return 'directory'; + if (kind === 'custom_pages') return 'slug'; + if (kind === 'url') return 'url'; + return null; +} + +function isAbsoluteUrl(value) { + try { + return Boolean(new URL(value).protocol); + } catch { + return false; + } +} + +/** + * Top-level folders that are laid out like a section (they have an + * `_order.yaml`) but that ReadMe doesn't know about, because nothing in + * `_readme.yaml` declares them. + */ +function findUndeclaredSections(gitRoot, sections) { + let entries; + try { + entries = fs.readdirSync(gitRoot, { withFileTypes: true }); + } catch { + return []; + } + + const known = new Set(sections.directories()); + return entries + .filter(entry => entry.isDirectory()) + .map(entry => entry.name) + .filter(directory => !known.has(directory) && !isBuiltInDirectory(directory)) + .filter(directory => !RESERVED_DIRECTORIES.has(directory) && SECTION_DIRECTORY_REGEX.test(directory)) + .filter(directory => fs.existsSync(path.join(gitRoot, directory, '_order.yaml'))) + .sort(); +} + +/** + * Validate `_readme.yaml`, the optional file that declares a project's + * navigation and any sections beyond the built-in ones. + * + * A repo without the file is fine: it's how every repo looked before multiple + * guides, and ReadMe falls back to the built-in sections. + * + * The checks mirror the ones ReadMe runs when the file is saved from the + * dashboard. A file that arrives through git sync skips some of those (a + * reserved or duplicated directory, a built-in declared as the wrong kind), so + * this is the only place they get caught. + * + * One deliberate difference: ReadMe ignores the whole file when it holds a + * property or kind it doesn't recognize, but the format can grow ahead of this + * CLI, so anything this version merely doesn't know is a warning, not an error. + */ +export function validateAll(_files, gitRoot, { sections = loadSections(gitRoot) } = {}) { + const results = []; + const error = message => results.push({ file: CONFIG_FILE, rule: name, severity: 'error', message }); + const warning = message => results.push({ file: CONFIG_FILE, rule: name, severity: 'warning', message }); + + for (const directory of findUndeclaredSections(gitRoot, sections)) { + results.push({ + file: directory, + rule: name, + severity: 'warning', + message: sections.exists + ? `Undeclared section: "${directory}" has an _order.yaml but isn't declared in ${CONFIG_FILE}, so ReadMe will ignore it` + : `Undeclared section: "${directory}" has an _order.yaml but there's no ${CONFIG_FILE} declaring it, so ReadMe will ignore it`, + }); + } + + if (!sections.exists) return results; + + if (sections.error) { + error(`Invalid ${CONFIG_FILE}: ${sections.error}`); + return results; + } + + const { config } = sections; + + for (const key of Object.keys(config)) { + if (key !== 'navigation') { + warning( + `Unknown property: "${key}" isn't recognized by this version of the CLI (if ReadMe doesn't recognize it either, it ignores the whole file)`, + ); + } + } + + // ReadMe reads a file with no `navigation` as an empty one. + if (config.navigation === undefined || config.navigation === null) return results; + + // ...and one whose `navigation` isn't a list the same way, which is never + // what was meant. + if (!Array.isArray(config.navigation)) { + warning('Invalid navigation: "navigation" must be a list (ReadMe treats anything else as empty)'); + return results; + } + + const directories = new Set(); + const customPageSlugs = new Set(); + const singletons = new Set(); + + config.navigation.forEach((entry, index) => { + const where = `navigation[${index}]`; + + if (!entry || typeof entry !== 'object' || Array.isArray(entry)) { + error(`Invalid entry: ${where} must be an object with a "kind"`); + return; + } + + const { kind } = entry; + if (typeof kind !== 'string' || !kind) { + error(`Invalid entry: ${where} is missing a "kind"`); + return; + } + if (!KNOWN_KINDS.includes(kind)) { + warning( + `Unknown kind: "${kind}" (${where}) isn't recognized by this version of the CLI (if ReadMe doesn't recognize it either, it ignores the whole file)`, + ); + return; + } + + const targetKey = targetKeyFor(kind); + const allowed = targetKey ? [...COMMON_KEYS, targetKey] : COMMON_KEYS; + for (const key of Object.keys(entry)) { + if (allowed.includes(key)) continue; + if (TARGET_KEYS.includes(key)) { + // A real field, on a kind that can't carry it. ReadMe rejects the file. + error(`Invalid entry: a "${kind}" entry can't have a "${key}" (${where})`); + } else { + warning( + `Unknown property: "${key}" on a "${kind}" entry (${where}) isn't recognized by this version of the CLI (if ReadMe doesn't recognize it either, it ignores the whole file)`, + ); + } + } + + if (entry.name !== undefined && entry.name !== null && (typeof entry.name !== 'string' || !entry.name)) { + error(`Invalid entry: "name" must be a non-empty string (${where})`); + } + if (entry.hidden !== undefined && entry.hidden !== null && typeof entry.hidden !== 'boolean') { + error(`Invalid entry: "hidden" must be true or false (${where})`); + } + if (entry.icon !== undefined && entry.icon !== null && typeof entry.icon !== 'string') { + error(`Invalid entry: "icon" must be a string (${where})`); + } + + if (kind === 'custom_pages') { + const { slug } = entry; + if (typeof slug === 'number' || typeof slug === 'boolean') { + // YAML reads a bare `404` or `true` as a number or boolean, not a slug. + error(`Invalid entry: ${slug} must be wrapped in quotes to be used as a slug (${where})`); + } else if (typeof slug !== 'string' || !slug) { + error(`Invalid entry: a "custom_pages" entry needs a "slug" (${where})`); + } else if (customPageSlugs.has(slug)) { + error(`Duplicate entry: the "${slug}" custom page is listed more than once`); + } else { + customPageSlugs.add(slug); + const exists = CUSTOM_PAGE_EXTENSIONS.some(ext => + fs.existsSync(path.join(gitRoot, 'custom_pages', `${slug}.${ext}`)), + ); + if (!exists) { + warning(`Missing page: "${slug}" is in the navigation but there's no custom_pages/${slug}.md (or .html)`); + } + } + return; + } + + if (kind === 'url') { + if (typeof entry.url !== 'string' || !isAbsoluteUrl(entry.url)) { + error(`Invalid entry: a "url" entry needs an absolute "url" (${where})`); + } + return; + } + + if (SINGLETON_KINDS.includes(kind)) { + if (singletons.has(kind)) error(`Duplicate entry: a "${kind}" entry may only appear once`); + singletons.add(kind); + return; + } + + // What's left owns a top-level directory. + const { directory } = entry; + if (typeof directory === 'number' || typeof directory === 'boolean') { + // YAML reads a bare `2026` or `true` as a number or boolean, not a name. + error(`Invalid directory: ${directory} must be wrapped in quotes to be used as a directory (${where})`); + return; + } + if (typeof directory !== 'string' || !directory) { + error(`Invalid entry: a "${kind}" entry needs a "directory" (${where})`); + return; + } + if (directories.has(directory)) { + error(`Duplicate section: the "${directory}" directory is declared more than once`); + return; + } + directories.add(directory); + + if (!SECTION_DIRECTORY_REGEX.test(directory)) { + error( + `Invalid directory: "${directory}" must be 1-30 characters of lowercase letters, numbers, "-" or "_", and start with a letter or number`, + ); + return; + } + if (RESERVED_DIRECTORIES.has(directory)) { + error(`Reserved directory: "${directory}" can't be used as a section`); + return; + } + + // `hasOwn`, not a bare lookup: `constructor` is a valid directory name. + const builtInKind = isBuiltInDirectory(directory) ? BUILT_IN_KINDS[directory] : undefined; + if (builtInKind !== undefined) { + if (kind !== builtInKind) { + error(`Invalid kind: the "${directory}" directory must use the "${builtInKind}" kind, not "${kind}"`); + } + return; + } + if (!DECLARABLE_KINDS.includes(kind)) { + error(`Invalid kind: "${directory}" must be one of ${DECLARABLE_KINDS.join(' or ')}, not "${kind}"`); + } + }); + + return results; +} diff --git a/src/validators/content.js b/src/validators/content.js index 5695651..2eff59d 100644 --- a/src/validators/content.js +++ b/src/validators/content.js @@ -2,12 +2,16 @@ import fs from 'node:fs'; import path from 'node:path'; import { parseFrontmatter } from '../utils/markdown.js'; +import { DEFAULT_SECTIONS } from '../utils/sections.js'; export const name = 'content'; -export function validate({ filePath, content, relativePath }) { - const dir = relativePath.split('/')[0]; - if (!['docs', 'reference', 'custom_pages'].includes(dir)) return null; +// Kinds of section whose pages are expected to have a body. +const CHECKED_KINDS = ['guide', 'reference', 'custom_pages']; + +export function validate({ filePath, content, relativePath, sections = DEFAULT_SECTIONS }) { + const topDir = relativePath.split('/')[0]; + if (!CHECKED_KINDS.includes(sections.kindOf(topDir))) return null; if (!relativePath.endsWith('.md')) return null; const { data, content: body } = parseFrontmatter(content); diff --git a/src/validators/duplicates.js b/src/validators/duplicates.js index e5c0b17..6d2bb78 100644 --- a/src/validators/duplicates.js +++ b/src/validators/duplicates.js @@ -1,20 +1,21 @@ import path from 'node:path'; +import { DEFAULT_SECTIONS } from '../utils/sections.js'; import { slugForEntry } from '../utils/slug-for-entry.js'; export const name = 'duplicates'; -// Only docs and reference require unique slugs. -const CHECKED_DIRS = ['docs', 'reference']; +// Only guide and reference sections require unique slugs. +const CHECKED_KINDS = ['guide', 'reference']; -export function validateAll(files) { +export function validateAll(files, _gitRoot, { sections = DEFAULT_SECTIONS } = {}) { const results = []; // Group files by ":" so slugs only collide within the same section. const slugMap = new Map(); for (const relPath of files) { const topDir = relPath.split('/')[0]; - if (!CHECKED_DIRS.includes(topDir)) continue; + if (!CHECKED_KINDS.includes(sections.kindOf(topDir))) continue; const slug = slugForEntry(relPath); const key = `${topDir}:${slug}`; diff --git a/src/validators/frontmatter.js b/src/validators/frontmatter.js index 8f20130..33943c8 100644 --- a/src/validators/frontmatter.js +++ b/src/validators/frontmatter.js @@ -4,6 +4,7 @@ import Ajv from 'ajv'; import frontmatterSchema from '../../vendor/git-format/frontmatter.schema.json' with { type: 'json' }; import { parseFrontmatter } from '../utils/markdown.js'; +import { DEFAULT_SECTIONS } from '../utils/sections.js'; export const name = 'frontmatter'; @@ -65,27 +66,28 @@ function collectPropertyNames(schema, defs) { return props; } -// Map directory names to their index in the schema's oneOf array. -const DIR_SCHEMA_INDEX = { - docs: 0, +// Map each kind of section to its index in the schema's oneOf array. A declared +// section's pages use the same frontmatter as the built-in section of its kind. +const KIND_SCHEMA_INDEX = { + guide: 0, custom_pages: 1, reference: 2, recipes: 3, custom_blocks: 4, }; -// Compile a validator for each directory type from the vendored schema. +// Compile a validator for each kind from the vendored schema. const ajv = new Ajv({ allErrors: true, strict: false, logger: false, verbose: true }); const validators = {}; const knownProperties = {}; -for (const [dir, index] of Object.entries(DIR_SCHEMA_INDEX)) { +for (const [kind, index] of Object.entries(KIND_SCHEMA_INDEX)) { const subSchema = { defs: frontmatterSchema.defs, ...frontmatterSchema.oneOf[index] }; - validators[dir] = ajv.compile(subSchema); - knownProperties[dir] = collectPropertyNames(subSchema, frontmatterSchema.defs); + validators[kind] = ajv.compile(subSchema); + knownProperties[kind] = collectPropertyNames(subSchema, frontmatterSchema.defs); } -export function validate({ content, filePath, relativePath, fix }) { +export function validate({ content, filePath, relativePath, fix, sections = DEFAULT_SECTIONS }) { // Step 1: Parse the frontmatter YAML. const { data, error } = parseFrontmatter(content); if (error) { @@ -97,10 +99,10 @@ export function validate({ content, filePath, relativePath, fix }) { } const results = []; - const dir = relativePath.split('/')[0]; + const kind = sections.kindOf(relativePath.split('/')[0]); // Step 2: Validate the parsed frontmatter against the schema. - const validateFn = validators[dir]; + const validateFn = validators[kind]; if (validateFn) { const valid = validateFn(data); if (!valid) { @@ -108,7 +110,7 @@ export function validate({ content, filePath, relativePath, fix }) { // Reference pages are OAS-backed: title/excerpt come from the spec, so a // missing title is not an error for pages that declare an api.file. if ( - dir === 'reference' && + kind === 'reference' && data?.api?.file && err.keyword === 'required' && err.params?.missingProperty === 'title' @@ -141,7 +143,7 @@ export function validate({ content, filePath, relativePath, fix }) { } // Step 3: Warn about unknown properties (allow x- prefix for custom metadata). - const allowed = knownProperties[dir]; + const allowed = knownProperties[kind]; const unknownKeys = []; if (allowed && data && typeof data === 'object') { for (const key of Object.keys(data)) { diff --git a/src/validators/links.js b/src/validators/links.js index f437e3a..d2ba404 100644 --- a/src/validators/links.js +++ b/src/validators/links.js @@ -2,19 +2,18 @@ import fs from 'node:fs'; import path from 'node:path'; import { parseFrontmatter } from '../utils/markdown.js'; +import { loadSections } from '../utils/sections.js'; import { slugForEntry } from '../utils/slug-for-entry.js'; export const name = 'links'; -const CHECKED_DIRS = ['docs', 'reference', 'custom_pages', 'recipes']; - // Match doc:slug and ref:slug links, e.g. [text](doc:my-page) or [text](ref:my-op#anchor) const DOC_LINK_RE = /\((?:doc|ref):([a-zA-Z0-9_-]+)(?:#[^)]*)?\)/g; -function collectSlugs(gitRoot) { +function collectSlugs(gitRoot, dirs) { const slugs = new Set(); - for (const dir of CHECKED_DIRS) { + for (const dir of dirs) { const dirPath = path.join(gitRoot, dir); if (!fs.existsSync(dirPath)) continue; @@ -28,13 +27,14 @@ function collectSlugs(gitRoot) { return slugs; } -export function validateAll(files, gitRoot) { - const validSlugs = collectSlugs(gitRoot); +export function validateAll(files, gitRoot, { sections = loadSections(gitRoot) } = {}) { + const checkedDirs = sections.directories(); + const validSlugs = collectSlugs(gitRoot, checkedDirs); const results = []; for (const relPath of files) { const topDir = relPath.split('/')[0]; - if (!CHECKED_DIRS.includes(topDir)) continue; + if (!checkedDirs.includes(topDir)) continue; if (!/\.(md|mdx)$/.test(relPath)) continue; const raw = fs.readFileSync(path.join(gitRoot, relPath), 'utf-8'); diff --git a/src/validators/nesting.js b/src/validators/nesting.js index 8f4ef4d..1d94276 100644 --- a/src/validators/nesting.js +++ b/src/validators/nesting.js @@ -1,30 +1,30 @@ -import path from 'node:path'; +import { DEFAULT_SECTIONS } from '../utils/sections.js'; export const name = 'nesting'; -// Max folder nesting per top-level content dir. Anything deeper still syncs -// but won't appear in the sidebar. +// Max folder nesting per kind of section. Anything deeper still syncs but +// won't appear in the sidebar. // -// For `docs` and `reference` the category is the first folder and each page +// For guide and reference sections the category is the first folder and each page // level below it adds one, so this is the number of page levels the sidebar // renders under a category. It mirrors our publicly documented sidebar levels. // Keep in sync with src/dev/lib/docs.js. const MAX_DEPTH = { - docs: 5, + guide: 5, reference: 5, recipes: 0, custom_pages: 0, custom_blocks: 0, }; -export function validateAll(files) { +export function validateAll(files, _gitRoot, { sections = DEFAULT_SECTIONS } = {}) { const results = []; const seen = new Set(); for (const relPath of files) { const parts = relPath.split('/'); const topDir = parts[0]; - const max = MAX_DEPTH[topDir]; + const max = MAX_DEPTH[sections.kindOf(topDir)]; if (max === undefined) continue; // Depth = number of folders between the top dir and the file. diff --git a/src/validators/oas-reference.js b/src/validators/oas-reference.js index 315efc3..17e9e55 100644 --- a/src/validators/oas-reference.js +++ b/src/validators/oas-reference.js @@ -11,13 +11,21 @@ import { } from '../commands/oas-sync.js'; import { PathEscapeError } from '../utils/containment.js'; import { parseFrontmatter } from '../utils/markdown.js'; +import { findReferenceDirs } from '../utils/sections.js'; export const name = 'oas-reference'; -export function validateAll(files, gitRoot, { fix } = {}) { - const refDir = path.join(gitRoot, 'reference'); - if (!fs.existsSync(refDir)) return []; +export function validateAll(files, gitRoot, { fix, sections } = {}) { + // Each reference section is checked on its own: a page can only point at a + // spec that lives in the same section as it does. + const results = findReferenceDirs(gitRoot, sections).flatMap(section => validateSection(files, gitRoot, section)); + applyFixes(results, gitRoot, { fix }); + return results; +} + +function validateSection(files, gitRoot, section) { + const refDir = path.join(gitRoot, section); const oasFiles = findOasFiles(refDir); const results = []; @@ -29,7 +37,7 @@ export function validateAll(files, gitRoot, { fix } = {}) { // Check: `x-readme.internal`, which ReadMe ignores for page visibility. for (const location of findIgnoredInternalExtensions(spec)) { results.push({ - file: `reference/${filename}`, + file: `${section}/${filename}`, rule: name, severity: 'warning', message: `"x-readme.internal" is ignored by ReadMe (${location}); use "x-internal" instead to hide pages`, @@ -39,7 +47,7 @@ export function validateAll(files, gitRoot, { fix } = {}) { } // Collect all reference pages with api frontmatter. - const refPages = files.filter(f => f.startsWith('reference/') && f.endsWith('.md')); + const refPages = files.filter(f => f.startsWith(`${section}/`) && f.endsWith('.md')); for (const relPath of refPages) { const filePath = path.join(gitRoot, relPath); @@ -56,7 +64,7 @@ export function validateAll(files, gitRoot, { fix } = {}) { results.push({ file: relPath, rule: name, - message: `OAS file not found: "${oasFilename}" does not exist in reference/`, + message: `OAS file not found: "${oasFilename}" does not exist in ${section}/`, fixable: false, }); continue; @@ -89,7 +97,7 @@ export function validateAll(files, gitRoot, { fix } = {}) { for (const op of ops.values()) { if (!coveredOps.has(operationKey(op))) { results.push({ - file: `reference/${oasFilename}`, + file: `${section}/${oasFilename}`, rule: name, severity: 'warning', message: `Missing page: no reference page found for operation "${op.operationId}"`, @@ -99,6 +107,10 @@ export function validateAll(files, gitRoot, { fix } = {}) { } } + return results; +} + +function applyFixes(results, gitRoot, { fix }) { // Apply fixes by running the full sync — but only when something reported // is actually fixable. The sync adds, deletes, moves, hides and reorders // reference files, which is far too much to do on the strength of an @@ -124,6 +136,4 @@ export function validateAll(files, gitRoot, { fix } = {}) { }); } } - - return results; } diff --git a/src/validators/oas-schema.js b/src/validators/oas-schema.js index 3e1a16d..6527dff 100644 --- a/src/validators/oas-schema.js +++ b/src/validators/oas-schema.js @@ -3,7 +3,7 @@ import path from 'node:path'; import OASNormalize from 'oas-normalize'; -import { findOasFiles } from '../commands/oas-sync.js'; +import { findAllOasFiles } from '../commands/oas-sync.js'; export const name = 'oas-schema'; @@ -28,14 +28,11 @@ function findBadRefs(obj, pointer = '') { return issues; } -export async function validateAll(files, gitRoot) { - const refDir = path.join(gitRoot, 'reference'); - if (!fs.existsSync(refDir)) return []; - - const oasFiles = findOasFiles(refDir); +export async function validateAll(files, gitRoot, { sections } = {}) { + const oasFiles = findAllOasFiles(gitRoot, sections); const results = []; - for (const { filename, spec } of oasFiles) { + for (const { section, refDir, filename, spec } of oasFiles) { const filePath = path.join(refDir, filename); const raw = fs.readFileSync(filePath, 'utf-8'); @@ -71,7 +68,7 @@ export async function validateAll(files, gitRoot) { if (!result.valid) { for (const err of result.errors) { results.push({ - file: `reference/${filename}`, + file: `${section}/${filename}`, rule: name, message: err.message, }); @@ -80,7 +77,7 @@ export async function validateAll(files, gitRoot) { for (const warn of result.warnings) { results.push({ - file: `reference/${filename}`, + file: `${section}/${filename}`, rule: name, severity: 'warning', message: warn.message, @@ -88,7 +85,7 @@ export async function validateAll(files, gitRoot) { } } catch (err) { results.push({ - file: `reference/${filename}`, + file: `${section}/${filename}`, rule: name, message: err.message || String(err), }); @@ -97,7 +94,7 @@ export async function validateAll(files, gitRoot) { // Check for malformed $ref pointers (oas-normalize doesn't catch these). for (const { path: refPath, ref } of findBadRefs(spec)) { results.push({ - file: `reference/${filename}`, + file: `${section}/${filename}`, rule: name, message: `Malformed $ref: "${ref}" at ${refPath} (should start with "#/")`, }); diff --git a/src/validators/ordering.js b/src/validators/ordering.js index d017bdc..e06d74a 100644 --- a/src/validators/ordering.js +++ b/src/validators/ordering.js @@ -2,16 +2,14 @@ import fs from 'node:fs'; import path from 'node:path'; import { makeContainment, PathEscapeError } from '../utils/containment.js'; +import { loadSections } from '../utils/sections.js'; export const name = 'ordering'; -// Top-level content directories that use _order.yaml. -export const CONTENT_DIRS = ['docs', 'reference', 'recipes', 'custom_pages']; - -// Of those, the dirs that must list every page/folder. reference ordering is -// OAS-managed, so we never flag pages "missing from" a reference _order.yaml — -// but stale entries are flagged everywhere. -const REQUIRE_ORDER = new Set(['docs', 'recipes', 'custom_pages']); +// Every section uses _order.yaml, but not every kind has to list each +// page/folder: reference ordering is OAS-managed, so we never flag pages +// "missing from" a reference _order.yaml — stale entries are flagged everywhere. +const REQUIRE_ORDER = new Set(['guide', 'recipes', 'custom_pages']); // Values that YAML interprets as non-strings and need quoting in _order.yaml. const YAML_UNSAFE = /^(?:\d+\.?\d*|true|false|yes|no|on|off|null|~)$/i; @@ -100,12 +98,12 @@ function collectDirs(gitRoot, topDir, assertContained) { * - in _order.yaml but missing on disk → "Stale entry" * - an index entry that shouldn't be listed → "Invalid entry" */ -export function validateAll(files, gitRoot, { fix } = {}) { +export function validateAll(files, gitRoot, { fix, sections = loadSections(gitRoot) } = {}) { const assertContained = makeContainment(gitRoot, { label: 'repository' }); const results = []; - for (const topDir of CONTENT_DIRS) { - const requireOrder = REQUIRE_ORDER.has(topDir); + for (const topDir of sections.directories()) { + const requireOrder = REQUIRE_ORDER.has(sections.kindOf(topDir)); for (const { dir, onDisk, orderEntries, refused } of collectDirs(gitRoot, topDir, assertContained)) { const orderPath = path.join(dir, '_order.yaml'); diff --git a/test/sections.test.js b/test/sections.test.js new file mode 100644 index 0000000..1ad3e56 --- /dev/null +++ b/test/sections.test.js @@ -0,0 +1,365 @@ +import fs from 'node:fs'; +import path from 'node:path'; + +import { expect, test } from 'vitest'; + +import { lint } from '../src/commands/lint.js'; +import { syncOas } from '../src/commands/oas-sync.js'; +import { validateOas } from '../src/commands/oas-validate.js'; +import { loadSections } from '../src/utils/sections.js'; + +import { makeRepo, rmRepo } from './helpers.js'; + +const PAGE = '---\ntitle: Page\n---\n\nHello.\n'; + +const README_YAML = `navigation: + - kind: home + name: Home + - kind: guide + directory: docs + name: Guides + - kind: guide + directory: sdks + name: SDKs + - kind: reference + directory: reference + - kind: reference + directory: apis + name: Partner API + - kind: url + url: https://example.com + name: Status +`; + +const SPEC = JSON.stringify({ + openapi: '3.0.0', + info: { title: 'Partner', version: '1.0.0' }, + paths: { + '/pets': { get: { operationId: 'listPets', tags: ['Pets'], responses: { 200: { description: 'OK' } } } }, + }, +}); + +async function lintRepo(files) { + const root = makeRepo(files); + try { + return await lint({ cwd: root, nonInteractive: true }); + } finally { + rmRepo(root); + } +} + +const forRule = (results, rule) => results.filter(r => r.rule === rule); + +test('a repo without _readme.yaml resolves to the built-in sections', () => { + const root = makeRepo({ 'docs/a.md': PAGE }); + try { + const sections = loadSections(root); + expect(sections.exists).toBe(false); + expect(sections.directories()).toStrictEqual(['docs', 'reference', 'custom_pages', 'recipes']); + } finally { + rmRepo(root); + } +}); + +test('a repo without _readme.yaml lints exactly as before, with nothing about the config', async () => { + const { files, results } = await lintRepo({ + 'docs/a.md': PAGE, + 'docs/_order.yaml': '- a\n', + // Not a section: no _readme.yaml declares it, and it has no _order.yaml. + 'notes/scratch.md': 'not frontmatter at all', + }); + expect(files).toStrictEqual(['docs/a.md']); + expect(results).toStrictEqual([]); +}); + +test('a declared guide section is linted like docs', async () => { + const { files, results } = await lintRepo({ + '_readme.yaml': README_YAML, + 'docs/a.md': PAGE, + 'docs/_order.yaml': '- a\n', + 'sdks/node.md': '---\ntitle: Node\ntitel: typo\n---\n\nSee [missing](doc:nope).\n', + 'sdks/python.md': '---\ntitle: Python\n---\n', + 'sdks/_order.yaml': '- node\n- ghost\n', + }); + + expect(files).toContain('sdks/node.md'); + expect(forRule(results, 'config')).toStrictEqual([]); + + const messages = results.map(r => `${r.file}: ${r.message}`); + const has = text => messages.some(m => m.includes(text)); + expect(has('sdks/node.md: Unknown property: "titel"')).toBe(true); + expect(has('sdks/node.md: Broken link: "doc:nope"')).toBe(true); + expect(has('sdks/python.md: Empty page')).toBe(true); + expect(has('sdks/_order.yaml: Missing from _order.yaml: python')).toBe(true); + expect(has('sdks/_order.yaml: Stale entry: "ghost"')).toBe(true); +}); + +test('links resolve to pages in a declared section', async () => { + const { results } = await lintRepo({ + '_readme.yaml': README_YAML, + 'docs/a.md': '---\ntitle: A\n---\n\nSee [node](doc:node).\n', + 'docs/_order.yaml': '- a\n', + 'sdks/node.md': PAGE, + 'sdks/_order.yaml': '- node\n', + }); + expect(forRule(results, 'links')).toStrictEqual([]); +}); + +test('the same slug in two sections is not a duplicate, but twice in one declared section is', async () => { + const { results } = await lintRepo({ + '_readme.yaml': README_YAML, + 'docs/intro.md': PAGE, + 'docs/_order.yaml': '- intro\n', + 'sdks/intro.md': PAGE, + 'sdks/Node/intro.md': PAGE, + 'sdks/Node/_order.yaml': '- intro\n', + 'sdks/_order.yaml': '- intro\n- Node\n', + }); + const duplicates = forRule(results, 'duplicates'); + expect(duplicates).toHaveLength(1); + expect(duplicates[0].file.startsWith('sdks/')).toBe(true); +}); + +test('a folder that looks like a section but is not declared gets a warning, not an error', async () => { + const withoutConfig = await lintRepo({ + 'docs/a.md': PAGE, + 'docs/_order.yaml': '- a\n', + 'sdks/node.md': PAGE, + 'sdks/_order.yaml': '- node\n', + }); + expect(withoutConfig.hasErrors).toBe(false); + expect(withoutConfig.results.map(r => [r.file, r.rule, r.severity])).toStrictEqual([['sdks', 'config', 'warning']]); + expect(withoutConfig.results[0].message).toMatch(/no _readme\.yaml declaring it/); + + const withConfig = await lintRepo({ + '_readme.yaml': 'navigation:\n - kind: guide\n directory: docs\n', + 'docs/a.md': PAGE, + 'docs/_order.yaml': '- a\n', + 'sdks/node.md': PAGE, + 'sdks/_order.yaml': '- node\n', + }); + expect(withConfig.hasErrors).toBe(false); + expect(withConfig.results[0].message).toMatch(/isn't declared in _readme\.yaml/); +}); + +test('an unparseable _readme.yaml is an error, and the built-ins are still linted', async () => { + const { files, results } = await lintRepo({ + '_readme.yaml': 'navigation: [unclosed\n', + 'docs/a.md': PAGE, + 'docs/_order.yaml': '- a\n', + }); + expect(files).toStrictEqual(['docs/a.md']); + const config = forRule(results, 'config'); + expect(config).toHaveLength(1); + expect(config[0].severity).toBe('error'); + expect(config[0].file).toBe('_readme.yaml'); +}); + +test('_readme.yaml entries ReadMe would reject are errors', async () => { + const { results } = await lintRepo({ + '_readme.yaml': `navigation: + - kind: guide + directory: sdks + - kind: guide + directory: sdks + - kind: guide + directory: Bad Name + - kind: guide + directory: guides + - kind: reference + directory: docs + - kind: recipes + directory: cookbook + - kind: home + - kind: home + - kind: url + url: /relative + - kind: custom_pages + - kind: guide + - kind: changelog + directory: changelogs + - kind: custom_pages + slug: 404 +`, + 'docs/a.md': PAGE, + 'docs/_order.yaml': '- a\n', + }); + const errors = forRule(results, 'config') + .filter(r => r.severity === 'error') + .map(r => r.message); + const expected = [ + 'Duplicate section: the "sdks" directory', + 'Invalid directory: "Bad Name"', + 'Reserved directory: "guides"', + 'the "docs" directory must use the "guide" kind', + '"cookbook" must be one of guide or reference', + 'a "home" entry may only appear once', + 'a "url" entry needs an absolute "url"', + 'a "custom_pages" entry needs a "slug"', + 'a "guide" entry needs a "directory"', + 'a "changelog" entry can\'t have a "directory"', + '404 must be wrapped in quotes to be used as a slug', + ]; + for (const text of expected) { + expect( + errors.some(m => m.includes(text)), + `expected an error containing: ${text}`, + ).toBe(true); + } + expect(errors).toHaveLength(expected.length); +}); + +test('things this CLI version does not recognize in _readme.yaml are warnings', async () => { + const { results, hasErrors } = await lintRepo({ + '_readme.yaml': `theme: dark +navigation: + - kind: hologram + - kind: guide + directory: docs + color: blue + - kind: custom_pages + slug: pricing + - kind: custom_pages + slug: terms +`, + 'docs/a.md': PAGE, + 'docs/_order.yaml': '- a\n', + // A custom page can be raw HTML, so this one isn't missing. + 'custom_pages/terms.html': '

Terms

', + }); + expect(hasErrors).toBe(false); + const warnings = forRule(results, 'config').map(r => r.message); + expect(warnings).toHaveLength(4); + expect(warnings.some(m => m.includes('"theme"'))).toBe(true); + expect(warnings.some(m => m.includes('"hologram"'))).toBe(true); + expect(warnings.some(m => m.includes('"color"'))).toBe(true); + expect(warnings.some(m => m.includes('custom_pages/pricing.md'))).toBe(true); +}); + +test('a navigation that is not a list is a warning, since ReadMe reads it as empty', async () => { + const { results, hasErrors } = await lintRepo({ + '_readme.yaml': 'navigation: docs\n', + 'docs/a.md': PAGE, + 'docs/_order.yaml': '- a\n', + }); + expect(hasErrors).toBe(false); + expect(forRule(results, 'config')).toHaveLength(1); +}); + +test('a built-in listed without a name takes the name ReadMe gives it', () => { + const root = makeRepo({ + '_readme.yaml': + 'navigation:\n - kind: reference\n directory: reference\n - kind: guide\n directory: docs\n', + }); + try { + const sections = loadSections(root); + expect(sections.order.slice(0, 2)).toStrictEqual(['reference', 'docs']); + expect(sections.byDirectory.get('docs').label).toBe('Guides'); + expect(sections.byDirectory.get('reference').label).toBe('API Reference'); + expect(sections.kindOf('docs')).toBe('guide'); + } finally { + rmRepo(root); + } +}); + +test('a directory that looks like a date stays a string, and a bare number has to be quoted', async () => { + const files = { + '_readme.yaml': 'navigation:\n - kind: guide\n directory: 2026\n - kind: guide\n directory: 2026-07-31\n', + }; + const root = makeRepo(files); + try { + expect(loadSections(root).declaredDirectories()).toStrictEqual(['2026-07-31']); + } finally { + rmRepo(root); + } + + const { results } = await lintRepo(files); + expect(forRule(results, 'config').map(r => r.message)).toStrictEqual([ + 'Invalid directory: 2026 must be wrapped in quotes to be used as a directory (navigation[0])', + ]); +}); + +test('oas:sync and oas:validate cover a declared reference section', async () => { + const root = makeRepo({ + '_readme.yaml': README_YAML, + 'apis/partner.json': SPEC, + }); + try { + const validated = await validateOas({ cwd: root }); + expect(validated.fileCount).toBe(1); + expect(validated.results[0].section).toBe('apis'); + + const [result] = syncOas(root); + expect(result.section).toBe('apis'); + expect(result.changes.added.length).toBeGreaterThan(0); + expect(fs.existsSync(path.join(root, 'apis'))).toBe(true); + expect(fs.existsSync(path.join(root, 'reference'))).toBe(false); + + const { results } = await lint({ cwd: root, nonInteractive: true }); + expect(forRule(results, 'oas-reference')).toStrictEqual([]); + } finally { + rmRepo(root); + } +}); + +test('lint flags a missing page for a spec in a declared reference section', async () => { + const { results } = await lintRepo({ + '_readme.yaml': README_YAML, + 'apis/partner.json': SPEC, + }); + const missing = forRule(results, 'oas-reference'); + expect(missing).toHaveLength(1); + expect(missing[0].file).toBe('apis/partner.json'); +}); + +test('a reference-kind folder is ignored by the OAS tooling until it is declared', async () => { + const root = makeRepo({ 'apis/partner.json': SPEC, 'docs/a.md': PAGE }); + try { + expect(syncOas(root)).toBeNull(); + await expect(validateOas({ cwd: root })).resolves.toBeNull(); + } finally { + rmRepo(root); + } +}); + +test('a symlinked _readme.yaml is refused, and declares nothing', async () => { + const outside = makeRepo({ 'config.yaml': 'navigation:\n - kind: guide\n directory: sdks\n' }); + const root = makeRepo({ 'docs/a.md': PAGE, 'docs/_order.yaml': '- a\n', 'sdks/node.md': PAGE }); + try { + fs.symlinkSync(path.join(outside, 'config.yaml'), path.join(root, '_readme.yaml')); + + expect(loadSections(root).declaredDirectories()).toStrictEqual([]); + + const { files, results } = await lint({ cwd: root, nonInteractive: true }); + expect(files).toStrictEqual(['docs/a.md']); + expect(forRule(results, 'config')).toMatchObject([{ file: '_readme.yaml', severity: 'error' }]); + } finally { + rmRepo(root); + rmRepo(outside); + } +}); + +test('oas:sync refuses a symlink in a declared reference section before touching any section', () => { + const outside = makeRepo({ 'elsewhere.json': SPEC }); + const root = makeRepo({ '_readme.yaml': README_YAML, 'reference/partner.json': SPEC, 'apis/.keep': '' }); + try { + fs.symlinkSync(path.join(outside, 'elsewhere.json'), path.join(root, 'apis/linked.json')); + + expect(() => syncOas(root)).toThrow(/symbolic links/); + expect(fs.readdirSync(path.join(root, 'reference'))).toStrictEqual(['partner.json']); + } finally { + rmRepo(root); + rmRepo(outside); + } +}); + +test('a section named after an Object.prototype property is an ordinary section', async () => { + const { files, results, hasErrors } = await lintRepo({ + '_readme.yaml': 'navigation:\n - kind: guide\n directory: constructor\n', + 'constructor/a.md': PAGE, + 'constructor/_order.yaml': '- a\n', + }); + expect(files).toStrictEqual(['constructor/a.md']); + expect(hasErrors).toBe(false); + expect(results).toStrictEqual([]); +});