feat: add validator for .mdc rule files

shijiashuai · shijiashuai · commit 527de283c0c9 · 2026-03-24T22:04:51.000+08:00
Validate rule frontmatter and heading structure so contributions stay consistent without adding a heavier tooling stack.
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@
 [![GitHub stars](https://img.shields.io/github/stars/LessUp/cursor-rules?style=flat-square&logo=github)](https://github.com/LessUp/cursor-rules/stargazers)
 [![GitHub forks](https://img.shields.io/github/forks/LessUp/cursor-rules?style=flat-square&logo=github)](https://github.com/LessUp/cursor-rules/network/members)
 [![License](https://img.shields.io/github/license/LessUp/cursor-rules?style=flat-square)](LICENSE)
-[![Rules](https://img.shields.io/badge/rules-28-blue?style=flat-square)](#-支持的技术栈)
+[![Rules](https://img.shields.io/badge/rules-26-blue?style=flat-square)](#-支持的技术栈)
 
 帮助开发者和团队统一代码风格、提升代码质量，从而更高效地进行协作开发。
 
@@ -23,6 +23,7 @@
 - [支持的技术栈](#-支持的技术栈)
 - [快速开始](#-快速开始)
 - [规则文件说明](#-规则文件说明)
+- [验证规则文件](#-验证规则文件)
 - [贡献指南](#-贡献指南)
 - [许可证](#-许可证)
 - [致谢](#-致谢)
@@ -144,9 +145,42 @@ globs: **/*.py, src/**/*.py          # 适用的文件类型
 
 - **`globs` 不为空** → 规则仅在匹配的文件类型上生效（如 `**/*.py` 只对 Python 文件生效）。
 - **`globs` 为空** → 规则作为通用规范全局生效。
+- 当前 validator 接受两种 `globs` 写法：
+  - 不带整体引号的逗号分隔字符串：`**/*.py, src/**/*.py`
+  - 带整体引号的逗号分隔字符串：`"**/*.c,**/*.cpp,Makefile"`
+
+## ✅ 验证规则文件
+
+仓库内置了一个零依赖的 validator，用于检查根目录下 `.mdc` 规则文件的基本结构是否正确。
+
+```bash
+node scripts/validate-rules.mjs
+```
+
+也可以只校验指定文件：
+
+```bash
+node scripts/validate-rules.mjs python.mdc medusa.mdc
+```
+
+validator 默认会检查：
+- 文件是否以 `---` frontmatter 开始并正确结束
+- 是否包含 `description` 和 `globs`
+- `description` 是否为空
+- 非空 `globs` 是否能解析为有效的逗号分隔条目
+- frontmatter 后是否存在正文
+- 正文中是否至少包含一个 H1 标题
+
+validator 还会给出非阻塞 warning，例如：
+- 首个 H1 之前出现正文内容
+- 同一文件中存在多个 H1
+- 出现未知 frontmatter 字段
 
 ## 🤝 贡献指南
 
+在提交 Pull Request 前，建议先运行一次 validator，确保新增或修改的规则文件符合仓库约定。
+
+
 我们非常欢迎社区的贡献！
 
 ### 参与方式
diff --git a/medusa.mdc b/medusa.mdc
@@ -3,10 +3,10 @@ description: Medusa 规则和最佳实践。在使用 Medusa 构建应用程序
 globs: **/*.tsx, **/*.ts, src/**/*.ts, src/**/*.tsx, src/**/*.js, src/**/*.jsx
 ---
 
-您是一位专注于现代 Web 开发的资深高级软件工程师，在 TypeScript、Medusa、React.js 和 TailwindCSS 方面拥有深厚的专业知识。
-
 # Medusa 规则
 
+您是一位专注于现代 Web 开发的资深高级软件工程师，在 TypeScript、Medusa、React.js 和 TailwindCSS 方面拥有深厚的专业知识。
+
 ## 通用规则
 
 - 导入文件时不要使用类型别名。
@@ -43,6 +43,6 @@ globs: **/*.tsx, **/*.ts, src/**/*.ts, src/**/*.tsx, src/**/*.js, src/**/*.jsx
 - 在管理后台定制中发送请求时，总是使用 Medusa 的 JS SDK。
 - 使用 TailwindCSS 进行样式设计。
 
-# 额外资源
+## 额外资源
 
 - [Medusa 文档](https://docs.medusajs.com/llms-full.txt)
diff --git a/scripts/validate-rules.mjs b/scripts/validate-rules.mjs
@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+const ROOT_DIR = process.cwd();
+const ALLOWED_KEYS = new Set(['description', 'globs']);
+
+function toPosixRelative(filePath) {
+  return path.relative(ROOT_DIR, filePath).split(path.sep).join('/');
+}
+
+function normalizeNewlines(text) {
+  return text.replace(/\r\n/g, '\n');
+}
+
+function createFinding(severity, filePath, line, code, message) {
+  return {
+    severity,
+    filePath,
+    line,
+    code,
+    message,
+  };
+}
+
+function isStandaloneDelimiter(line) {
+  return line.trim() === '---';
+}
+
+function unwrapMatchingQuotes(value) {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return value.slice(1, -1);
+    }
+  }
+
+  return value;
+}
+
+function parseFrontmatter(content, filePath) {
+  const findings = [];
+  const lines = content.split('\n');
+
+  if (!lines.length || !isStandaloneDelimiter(lines[0])) {
+    findings.push(createFinding('ERROR', filePath, 1, 'E001', 'Missing opening frontmatter delimiter'));
+    return { findings, frontmatter: null, body: '', bodyStartLine: 1 };
+  }
+
+  let closingIndex = -1;
+  for (let index = 1; index < lines.length; index += 1) {
+    if (isStandaloneDelimiter(lines[index])) {
+      closingIndex = index;
+      break;
+    }
+  }
+
+  if (closingIndex === -1) {
+    findings.push(createFinding('ERROR', filePath, 1, 'E002', 'Missing closing frontmatter delimiter'));
+    return { findings, frontmatter: null, body: '', bodyStartLine: 1 };
+  }
+
+  const frontmatter = new Map();
+
+  for (let index = 1; index < closingIndex; index += 1) {
+    const line = lines[index];
+    if (!line.trim()) {
+      continue;
+    }
+
+    const separatorIndex = line.indexOf(':');
+    if (separatorIndex === -1) {
+      findings.push(createFinding('ERROR', filePath, index + 1, 'E003', 'Invalid frontmatter line; expected key: value'));
+      continue;
+    }
+
+    const key = line.slice(0, separatorIndex).trim();
+    const value = line.slice(separatorIndex + 1).trim();
+
+    if (!key) {
+      findings.push(createFinding('ERROR', filePath, index + 1, 'E003', 'Invalid frontmatter line; key must not be empty'));
+      continue;
+    }
+
+    if (frontmatter.has(key)) {
+      findings.push(createFinding('ERROR', filePath, index + 1, 'E003', `Duplicate frontmatter key: ${key}`));
+      continue;
+    }
+
+    frontmatter.set(key, value);
+
+    if (!ALLOWED_KEYS.has(key)) {
+      findings.push(createFinding('WARN', filePath, index + 1, 'W003', `Unknown frontmatter key: ${key}`));
+    }
+  }
+
+  const bodyLines = lines.slice(closingIndex + 1);
+  return {
+    findings,
+    frontmatter,
+    body: bodyLines.join('\n'),
+    bodyStartLine: closingIndex + 2,
+  };
+}
+
+function validateDescription(frontmatter, filePath) {
+  const findings = [];
+
+  if (!frontmatter.has('description')) {
+    findings.push(createFinding('ERROR', filePath, 1, 'E004', 'Missing required frontmatter key: description'));
+    return findings;
+  }
+
+  const description = unwrapMatchingQuotes(frontmatter.get('description') ?? '').trim();
+  if (!description) {
+    findings.push(createFinding('ERROR', filePath, 2, 'E005', 'description must not be empty'));
+  }
+
+  return findings;
+}
+
+function validateGlobs(frontmatter, filePath) {
+  const findings = [];
+
+  if (!frontmatter.has('globs')) {
+    findings.push(createFinding('ERROR', filePath, 1, 'E006', 'Missing required frontmatter key: globs'));
+    return findings;
+  }
+
+  const rawGlobs = frontmatter.get('globs') ?? '';
+  const trimmed = rawGlobs.trim();
+  if (!trimmed) {
+    return findings;
+  }
+
+  const normalized = unwrapMatchingQuotes(trimmed);
+  const entries = normalized.split(',').map((entry) => entry.trim());
+
+  if (!entries.length || entries.some((entry) => !entry)) {
+    findings.push(createFinding('ERROR', filePath, 3, 'E007', 'globs must contain non-empty comma-separated entries'));
+  }
+
+  return findings;
+}
+
+function validateBody(body, filePath, bodyStartLine) {
+  const findings = [];
+  const bodyLines = body.split('\n');
+
+  const firstNonEmptyIndex = bodyLines.findIndex((line) => line.trim());
+  if (firstNonEmptyIndex === -1) {
+    findings.push(createFinding('ERROR', filePath, bodyStartLine, 'E008', 'Rule body must not be empty'));
+    return findings;
+  }
+
+  const h1Indexes = [];
+  for (let index = 0; index < bodyLines.length; index += 1) {
+    if (/^#\s+\S/.test(bodyLines[index])) {
+      h1Indexes.push(index);
+    }
+  }
+
+  if (!h1Indexes.length) {
+    findings.push(createFinding('ERROR', filePath, bodyStartLine + firstNonEmptyIndex, 'E009', 'Rule body must contain at least one H1 heading'));
+    return findings;
+  }
+
+  const firstH1Index = h1Indexes[0];
+  const hasContentBeforeFirstH1 = bodyLines
+    .slice(0, firstH1Index)
+    .some((line) => line.trim());
+
+  if (hasContentBeforeFirstH1) {
+    findings.push(createFinding('WARN', filePath, bodyStartLine + firstNonEmptyIndex, 'W001', 'Content appears before the first H1 heading'));
+  }
+
+  if (h1Indexes.length > 1) {
+    findings.push(createFinding('WARN', filePath, bodyStartLine + h1Indexes[1], 'W002', `Multiple H1 headings found (${h1Indexes.length})`));
+  }
+
+  return findings;
+}
+
+function validateFile(filePath) {
+  const content = normalizeNewlines(fs.readFileSync(filePath, 'utf8'));
+  const findings = [];
+
+  const parsed = parseFrontmatter(content, filePath);
+  findings.push(...parsed.findings);
+
+  if (!parsed.frontmatter) {
+    return findings;
+  }
+
+  findings.push(...validateDescription(parsed.frontmatter, filePath));
+  findings.push(...validateGlobs(parsed.frontmatter, filePath));
+  findings.push(...validateBody(parsed.body, filePath, parsed.bodyStartLine));
+
+  return findings;
+}
+
+function compareFindings(left, right) {
+  if (left.filePath !== right.filePath) {
+    return left.filePath.localeCompare(right.filePath);
+  }
+
+  if (left.line !== right.line) {
+    return left.line - right.line;
+  }
+
+  if (left.severity !== right.severity) {
+    return left.severity.localeCompare(right.severity);
+  }
+
+  return left.code.localeCompare(right.code);
+}
+
+function printFindings(findings) {
+  const sorted = [...findings].sort(compareFindings);
+
+  for (const finding of sorted) {
+    const relativePath = toPosixRelative(finding.filePath);
+    console.log(`${finding.severity} ${relativePath}:${finding.line} ${finding.code} ${finding.message}`);
+  }
+}
+
+function getDefaultTargets(rootDir) {
+  return fs
+    .readdirSync(rootDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.mdc'))
+    .map((entry) => path.join(rootDir, entry.name))
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function resolveTargets(args, rootDir) {
+  if (!args.length) {
+    return getDefaultTargets(rootDir);
+  }
+
+  return args.map((inputPath) => {
+    const resolvedPath = path.resolve(rootDir, inputPath);
+
+    if (!fs.existsSync(resolvedPath)) {
+      throw new Error(`Path does not exist: ${inputPath}`);
+    }
+
+    const stats = fs.statSync(resolvedPath);
+    if (!stats.isFile()) {
+      throw new Error(`Path is not a file: ${inputPath}`);
+    }
+
+    if (!resolvedPath.endsWith('.mdc')) {
+      throw new Error(`Path is not an .mdc file: ${inputPath}`);
+    }
+
+    return resolvedPath;
+  });
+}
+
+function main() {
+  try {
+    const args = process.argv.slice(2);
+    const targets = resolveTargets(args, ROOT_DIR);
+    const findings = targets.flatMap((filePath) => validateFile(filePath));
+
+    printFindings(findings);
+
+    const errorCount = findings.filter((finding) => finding.severity === 'ERROR').length;
+    const warningCount = findings.filter((finding) => finding.severity === 'WARN').length;
+
+    console.log(`Checked ${targets.length} file${targets.length === 1 ? '' : 's'}: ${errorCount} error${errorCount === 1 ? '' : 's'}, ${warningCount} warning${warningCount === 1 ? '' : 's'}`);
+
+    process.exitCode = errorCount > 0 ? 1 : 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`ERROR ${message}`);
+    process.exitCode = 2;
+  }
+}
+
+main();
