164 lines
7.3 KiB
JavaScript
164 lines
7.3 KiB
JavaScript
// scripts/validate-help-docs.mjs
|
||
// Validates ui/src/content/help/*.md frontmatter + structural invariants.
|
||
// Exits non-zero on any error. Run before `vite build`.
|
||
import { readFileSync, readdirSync, existsSync } from 'node:fs';
|
||
import { join, dirname, resolve, relative } from 'node:path';
|
||
import { fileURLToPath, pathToFileURL } from 'node:url';
|
||
import { createRequire } from 'node:module';
|
||
|
||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||
// 検証するフォルダ。引数で差し替えられるのはテスト用（scripts/validate-help-docs.test.ts）。
|
||
const HELP_DIR = process.argv[2]
|
||
? resolve(process.cwd(), process.argv[2])
|
||
: resolve(__dirname, '../ui/src/content/help');
|
||
// `yaml` lives in ui/node_modules (the build runs `node ../scripts/...` from ui/).
|
||
// Resolve it relative to ui/ so this script works regardless of cwd.
|
||
let parseYaml;
|
||
try {
|
||
const require = createRequire(pathToFileURL(resolve(__dirname, '../ui/package.json')));
|
||
({ parse: parseYaml } = await import(pathToFileURL(require.resolve('yaml')).href));
|
||
} catch {
|
||
console.error("help-docs validation: cannot load 'yaml' from ui/node_modules — run `npm --prefix ui install`");
|
||
process.exit(1);
|
||
}
|
||
const CATEGORIES = ['basic', 'advanced', 'admin'];
|
||
|
||
// 見出し → 飛び先の名前（アンカー）の規則は ui/src/lib/help-slug.ts が唯一の出どころ。
|
||
// 画面が実際に付ける id と同じものをここでも使うため、規則を写さず読み込む (#1274)。
|
||
// Node は 22.18 以降 .ts をそのまま読める（型を剥がして実行する）。
|
||
let slugify, collectHeadingIds;
|
||
try {
|
||
({ slugify, collectHeadingIds } = await import(
|
||
pathToFileURL(resolve(__dirname, '../ui/src/lib/help-slug.ts')).href
|
||
));
|
||
} catch (e) {
|
||
console.error(
|
||
'help-docs validation: cannot load ui/src/lib/help-slug.ts — needs Node >= 22.18 ' +
|
||
'(TypeScript type stripping) and `npm --prefix ui install`\n ' + (e?.message ?? e),
|
||
);
|
||
process.exit(1);
|
||
}
|
||
|
||
function splitFrontmatter(raw) {
|
||
const n = raw.replace(/^/, '').replace(/\r\n/g, '\n');
|
||
const m = /^---\n([\s\S]*?)\n---\n?/.exec(n);
|
||
if (!m) return { normalized: n, frontmatter: '', body: n };
|
||
return { normalized: n, frontmatter: m[1], body: n.slice(m[0].length) };
|
||
}
|
||
|
||
const errors = [];
|
||
const ids = new Map();
|
||
const orders = new Map();
|
||
/** file -> { normalized, body }。リンクの検証で使う。 */
|
||
const docs = new Map();
|
||
|
||
const files = readdirSync(HELP_DIR).filter((f) => f.endsWith('.md')).sort();
|
||
if (files.length === 0) errors.push('no .md files found in help dir');
|
||
|
||
for (const file of files) {
|
||
const raw = readFileSync(join(HELP_DIR, file), 'utf8');
|
||
const { normalized, frontmatter, body } = splitFrontmatter(raw);
|
||
if (!frontmatter) { errors.push(`${file}: missing frontmatter block`); continue; }
|
||
let data;
|
||
try { data = parseYaml(frontmatter); } catch (e) { errors.push(`${file}: YAML error ${e.message}`); continue; }
|
||
|
||
if (typeof data?.id !== 'string' || !data.id.trim()) errors.push(`${file}: 'id' required`);
|
||
if (typeof data?.title !== 'string' || !data.title.trim()) errors.push(`${file}: 'title' required`);
|
||
if (!CATEGORIES.includes(data?.category)) errors.push(`${file}: 'category' must be ${CATEGORIES.join('|')}`);
|
||
if (typeof data?.order !== 'number' || !Number.isFinite(data.order)) errors.push(`${file}: 'order' must be a number`);
|
||
if (data?.keywords != null && (!Array.isArray(data.keywords) || data.keywords.some((k) => typeof k !== 'string')))
|
||
errors.push(`${file}: 'keywords' must be a string array`);
|
||
|
||
if (typeof data?.id === 'string') {
|
||
if (ids.has(data.id)) errors.push(`${file}: duplicate id '${data.id}' (also ${ids.get(data.id)})`);
|
||
else ids.set(data.id, file);
|
||
}
|
||
if (typeof data?.order === 'number') {
|
||
if (orders.has(data.order)) errors.push(`${file}: duplicate order ${data.order} (also ${orders.get(data.order)})`);
|
||
else orders.set(data.order, file);
|
||
}
|
||
|
||
// Duplicate heading slugs within a file (anchor links would be ambiguous).
|
||
const slugCounts = new Map();
|
||
for (const line of body.split('\n')) {
|
||
const h = /^(#{2,3})\s+(.*)$/.exec(line);
|
||
if (!h) continue;
|
||
const slug = slugify(h[2]);
|
||
slugCounts.set(slug, (slugCounts.get(slug) ?? 0) + 1);
|
||
}
|
||
for (const [slug, count] of slugCounts) {
|
||
if (count > 1) errors.push(`${file}: ${count} headings collide on slug '${slug}' (anchor links ambiguous)`);
|
||
}
|
||
|
||
docs.set(file, { normalized, body });
|
||
}
|
||
|
||
// --- Links -----------------------------------------------------------------
|
||
// ファイルの存在だけでなく、`#` から後ろ（飛び先の見出し）も突き合わせる。
|
||
// 見出しの文言を書き換えたのにリンク側が追いついていない、を落とすため (#1274)。
|
||
// 別のページ宛て（`](./xx.md#…)`）と同じページ内（`](#…)`）の両方を見る。
|
||
// 片方だけ見張ると「見出しリンクは見張られている」という誤った前提ができる。
|
||
|
||
/** その本文を描画したときに実際に付く見出し id。ファイル単位で 1 度だけ数える。 */
|
||
const headingIdCache = new Map();
|
||
function headingIdsOf(file) {
|
||
let ids = headingIdCache.get(file);
|
||
if (!ids) {
|
||
ids = new Set(collectHeadingIds(docs.get(file).body));
|
||
headingIdCache.set(file, ids);
|
||
}
|
||
return ids;
|
||
}
|
||
|
||
/** 文字位置 → 1 始まりの行番号（元ファイルの行と一致させるため normalized 全体で数える）。 */
|
||
function lineAt(text, index) {
|
||
let line = 1;
|
||
for (let i = 0; i < index; i++) if (text[i] === '\n') line++;
|
||
return line;
|
||
}
|
||
|
||
function decodeFragment(fragment) {
|
||
try { return decodeURIComponent(fragment); } catch { return fragment; }
|
||
}
|
||
|
||
for (const [file, { normalized }] of docs) {
|
||
// href の切り出しは以前と同じ（`)` まで）。狭めると、これまで拾えていた
|
||
// 書き損じ（空白入りのパスなど）を見落とす。
|
||
for (const m of normalized.matchAll(/\]\((\.{1,2}\/[^)]+)\)/g)) {
|
||
const href = m[1];
|
||
const line = lineAt(normalized, m.index);
|
||
const where = `${file}:${line}: ${m[0]}`;
|
||
const hashAt = href.indexOf('#');
|
||
const path = hashAt === -1 ? href : href.slice(0, hashAt);
|
||
const fragment = hashAt === -1 ? '' : decodeFragment(href.slice(hashAt + 1));
|
||
|
||
// 宛先のファイルが在ること。
|
||
const target = resolve(HELP_DIR, path);
|
||
if (!existsSync(target)) { errors.push(`${where} — target file not found`); continue; }
|
||
if (!fragment) continue;
|
||
|
||
const targetFile = relative(HELP_DIR, target);
|
||
if (!docs.has(targetFile)) continue; // ヘルプ以外のファイル（見出しを数えない）
|
||
if (!headingIdsOf(targetFile).has(fragment)) {
|
||
errors.push(`${where} — no heading '#${fragment}' in ${targetFile}`);
|
||
}
|
||
}
|
||
|
||
// 同じページ内のリンク（`](#見出し)`）。飛び先は自分自身の見出し。
|
||
for (const m of normalized.matchAll(/\]\((#[^)]+)\)/g)) {
|
||
const fragment = decodeFragment(m[1].slice(1));
|
||
if (!fragment) continue;
|
||
const line = lineAt(normalized, m.index);
|
||
if (!headingIdsOf(file).has(fragment)) {
|
||
errors.push(`${file}:${line}: ${m[0]} — no heading '#${fragment}' in ${file}`);
|
||
}
|
||
}
|
||
}
|
||
|
||
if (errors.length) {
|
||
console.error('help-docs validation FAILED:');
|
||
for (const e of errors) console.error(' - ' + e);
|
||
process.exit(1);
|
||
}
|
||
console.log(`help-docs validation OK (${files.length} files)`);
|