|
| 1 | +import fs from 'fs' |
| 2 | +import path from 'path' |
| 3 | +import matter from '@gr2m/gray-matter' |
| 4 | +import { addError } from 'markdownlint-rule-helpers' |
| 5 | + |
| 6 | +import { getFrontmatter } from '../helpers/utils' |
| 7 | +import type { RuleParams, RuleErrorCallback } from '@/content-linter/types' |
| 8 | + |
| 9 | +// Lazily computed list of valid category values from content/rest/index.md. |
| 10 | +let validCategories: string[] | null = null |
| 11 | + |
| 12 | +/** |
| 13 | + * Read the `includedCategories` frontmatter from content/rest/index.md. |
| 14 | + */ |
| 15 | +function getValidCategories(): string[] { |
| 16 | + if (validCategories) return validCategories |
| 17 | + |
| 18 | + const restIndexPath = path.resolve(process.env.ROOT || '.', 'content/rest/index.md') |
| 19 | + const content = fs.readFileSync(restIndexPath, 'utf-8') |
| 20 | + const { data } = matter(content) |
| 21 | + validCategories = (data.includedCategories as string[]) || [] |
| 22 | + return validCategories |
| 23 | +} |
| 24 | + |
| 25 | +/** |
| 26 | + * Reset the cached valid categories. Exported so tests can call it |
| 27 | + * between test cases if the fixture changes. |
| 28 | + */ |
| 29 | +export function resetCache(): void { |
| 30 | + validCategories = null |
| 31 | +} |
| 32 | + |
| 33 | +export const frontmatterRestApiCategory = { |
| 34 | + names: ['GHD067', 'frontmatter-rest-api-category'], |
| 35 | + description: |
| 36 | + 'Autogenerated REST API endpoint files must have a valid `category` frontmatter property', |
| 37 | + tags: ['frontmatter', 'rest', 'category'], |
| 38 | + function: (params: RuleParams, onError: RuleErrorCallback) => { |
| 39 | + const filePath = params.name |
| 40 | + const rootDir = process.env.ROOT || '.' |
| 41 | + const restDir = path.resolve(rootDir, 'content/rest') |
| 42 | + |
| 43 | + // Resolve the file path against CWD (markdownlint provides paths |
| 44 | + // relative to CWD when using `files`, or string keys when using `strings`). |
| 45 | + const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(filePath) |
| 46 | + const relativePath = path.relative(restDir, resolved) |
| 47 | + |
| 48 | + // Skip files that aren't under content/rest/ |
| 49 | + if (relativePath.startsWith('..')) return |
| 50 | + |
| 51 | + // Skip index files — they are category-level pages, not endpoint pages |
| 52 | + if (path.basename(resolved) === 'index.md') return |
| 53 | + |
| 54 | + const fm = getFrontmatter(params.lines) |
| 55 | + if (!fm) return |
| 56 | + |
| 57 | + // Only apply to autogenerated REST files |
| 58 | + if (fm.autogenerated !== 'rest') return |
| 59 | + |
| 60 | + // Find error line: prefer the category line, fall back to opening --- |
| 61 | + const categoryLineIndex = params.lines.findIndex((line) => |
| 62 | + line.trimStart().startsWith('category'), |
| 63 | + ) |
| 64 | + const fmOpenLine = params.lines.indexOf('---') |
| 65 | + const errorLine = |
| 66 | + categoryLineIndex !== -1 ? categoryLineIndex + 1 : fmOpenLine !== -1 ? fmOpenLine + 1 : 1 |
| 67 | + |
| 68 | + // Check: category must exist |
| 69 | + if (!fm.category) { |
| 70 | + addError( |
| 71 | + onError, |
| 72 | + errorLine, |
| 73 | + 'Missing `category` frontmatter. Autogenerated REST endpoint files must have a `category` property with a value from `content/rest/index.md` `includedCategories`.', |
| 74 | + undefined, |
| 75 | + undefined, |
| 76 | + undefined, |
| 77 | + ) |
| 78 | + return |
| 79 | + } |
| 80 | + |
| 81 | + // Check: category must be an array |
| 82 | + if (!Array.isArray(fm.category)) { |
| 83 | + addError( |
| 84 | + onError, |
| 85 | + errorLine, |
| 86 | + '`category` frontmatter must be an array.', |
| 87 | + undefined, |
| 88 | + undefined, |
| 89 | + undefined, |
| 90 | + ) |
| 91 | + return |
| 92 | + } |
| 93 | + |
| 94 | + // Check: category must have at least one value |
| 95 | + if (fm.category.length === 0) { |
| 96 | + addError( |
| 97 | + onError, |
| 98 | + errorLine, |
| 99 | + '`category` frontmatter must have at least one value.', |
| 100 | + undefined, |
| 101 | + undefined, |
| 102 | + undefined, |
| 103 | + ) |
| 104 | + return |
| 105 | + } |
| 106 | + |
| 107 | + // Check: each value must be in the valid list |
| 108 | + const valid = getValidCategories() |
| 109 | + for (const value of fm.category) { |
| 110 | + if (!valid.includes(value as string)) { |
| 111 | + addError( |
| 112 | + onError, |
| 113 | + errorLine, |
| 114 | + `Invalid category "${value}". Must be one of: ${valid.join(', ')}`, |
| 115 | + undefined, |
| 116 | + undefined, |
| 117 | + undefined, |
| 118 | + ) |
| 119 | + } |
| 120 | + } |
| 121 | + }, |
| 122 | +} |
0 commit comments