code-frontmatter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 coobi7
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+---
+intent: "README for Code Frontmatter project"
+role: documentation
+when_to_load: "Initial project setup or understanding CFM usage"
+---
+
+# Code Frontmatter (CFM)
+
+> **"Identity Cards" for your code files.**  
+> **Let AI understand your entire project without reading every single line.**
+
+---
+
+Code Frontmatter (CFM) is an open standard and MCP (Model Context Protocol) Server that allows you to embed structured metadata (YAML) at the top of every source code file.
+
+By scanning these lightweight headers, AI coding assistants (like Cursor, Windsurf, Claude Code) can build a cognitive map of your entire project with **minimal token cost**, eliminating hallucinations caused by context overload.
+
+## 🚀 Why CFM?
+
+| Feature | Without CFM | With CFM |
+|---|---|---|
+| **Context Load** | Full project files (huge tokens) | Just headers (~5% tokens) |
+| **Accuracy** | High hallucination risk | Deterministic file intent |
+| **Cost** | $$$ Expensive API calls | $ Cheap & Efficient |
+| **Scale** | Fails on large repos | Works on 10k+ file repos |
+
+## 📦 Installation
+
+To use CFM with your AI IDE (Cursor, Claude Desktop, etc.), install it as an MCP Server:
+
+```bash
+npx -y code-frontmatter
+```
+
+### Configuration
+
+#### For Cursor (`~/.cursor/mcp.json`)
+```json
+{
+  "mcpServers": {
+    "code-frontmatter": {
+      "command": "npx",
+      "args": ["-y", "code-frontmatter"]
+    }
+  }
+}
+```
+
+#### For Claude Desktop
+```json
+{
+  "mcpServers": {
+    "code-frontmatter": {
+      "command": "npx",
+      "args": ["-y", "code-frontmatter"]
+    }
+  }
+}
+```
+
+## 🛠 Usage
+
+### 1. Add Frontmatter to Your Code
+
+Add a CFM header to the top of your files using your language's comment syntax.
+
+**JavaScript / TypeScript:**
+```javascript
+/*---
+intent: "Manages user authentication state and login logic"
+role: service
+exports:
+  - "login: Authenticate user with email/pass"
+  - "logout: Clear session"
+depends_on: ["api-client.ts", "store.ts"]
+when_to_load: "Modifying auth flow or session handling"
+---*/
+
+export function login(email, password) { ... }
+```
+
+**Python:**
+```python
+#---
+# intent: "Data model for User entity"
+# role: model
+# exports:
+#   - "User: Standard user class"
+# mutates_state: false
+#---
+
+class User: ...
+```
+
+### 2. Available Tools
+
+The MCP Server exposes the following tools to your AI assistant:
+
+- **`cfm_scan(directory)`**: Scans your project and returns a structured index of all CFM headers.
+- **`cfm_search(query)`**: Search for files by keyword, role, or domain without reading full contents.
+- **`cfm_register_language(name, config)`**: Teach CFM how to parse headers for a new language on the fly.
+
+## 📋 Schema
+
+A valid CFM header requires at least:
+- **`intent`**: What is this file for? (String)
+- **`role`**: What is its architectural role? (String, e.g., `component`, `service`, `util`)
+- **`exports`**: What key things does it export? (Array of Strings)
+
+Optional fields: `depends_on`, `when_to_load`, `side_effects`, `mutates_state`, `domain`, `ai_notes`.
+
+## 🤝 Contributing
+
+We welcome contributions! Please follow the standard GitHub workflow.
+
+## 📄 License
+
+MIT © 2026 coobi7

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+/*---
+intent: "MCP Server 入口：注册 cfm_scan、cfm_search、cfm_register_language 三个工具，通过 stdio 与 AI IDE 通信"
+role: entry
+exports:
+  - "main: MCP Server 启动函数"
+depends_on:
+  - "@modelcontextprotocol/sdk"
+  - "./registry.ts"
+  - "./tools/scan.ts"
+  - "./tools/search.ts"
+  - "./tools/register.ts"
+when_to_load: "修改 MCP 工具注册、Server 配置或启动流程时加载"
+ai_notes: "使用 stdio transport，兼容所有 MCP 客户端（Cursor、Claude Desktop 等）"
+---*/
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadRegistry } from "./registry.js";
+import { scanDirectory } from "./tools/scan.js";
+import { searchFrontmatter } from "./tools/search.js";
+import { registerNewLanguage } from "./tools/register.js";
+/**
+ * 创建并配置 MCP Server
+ */
+async function main() {
+    // 初始化语言注册表
+    await loadRegistry();
+    // 创建 MCP Server 实例
+    const server = new McpServer({
+        name: "code-frontmatter",
+        version: "0.1.0",
+    });
+    // ─── 工具 1: cfm_scan ───────────────────────────────────
+    server.tool("cfm_scan", "扫描项目目录中所有代码文件的 CFM 表头，返回结构化索引。这是 AI 建立项目全局认知的第一步：用极低 Token 消耗获取整个项目的文件身份信息。", {
+        directory: z
+            .string()
+            .describe("要扫描的项目根目录的绝对路径"),
+        cfm_only: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("是否只返回有 CFM 表头的文件（默认 false，返回全部）"),
+        ignore_dirs: z
+            .array(z.string())
+            .optional()
+            .describe("额外忽略的目录名列表（默认已忽略 node_modules, .git, dist 等）"),
+    }, async ({ directory, cfm_only, ignore_dirs }) => {
+        try {
+            const result = await scanDirectory(directory, {
+                cfmOnly: cfm_only,
+                ignoreDirs: ignore_dirs,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `扫描失败: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // ─── 工具 2: cfm_search ─────────────────────────────────
+    server.tool("cfm_search", "在项目中搜索匹配条件的 CFM 表头。支持按关键字（在 intent, exports 等字段中全文搜索）、按角色（role）和按业务领域（domain）过滤，用于精准定位目标文件。", {
+        directory: z
+            .string()
+            .describe("要搜索的项目根目录的绝对路径"),
+        keyword: z
+            .string()
+            .optional()
+            .describe("关键字搜索，匹配 intent、exports、ai_notes 等字段"),
+        role: z
+            .string()
+            .optional()
+            .describe("按文件角色过滤（如 service, component, util, config, page）"),
+        domain: z
+            .string()
+            .optional()
+            .describe("按业务领域过滤（如 payment, auth, map-layer）"),
+    }, async ({ directory, keyword, role, domain }) => {
+        // 至少需要一个搜索条件
+        if (!keyword && !role && !domain) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "请至少提供一个搜索条件（keyword、role 或 domain）",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        try {
+            const result = await searchFrontmatter(directory, {
+                keyword,
+                role,
+                domain,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `搜索失败: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // ─── 工具 3: cfm_register_language ──────────────────────
+    server.tool("cfm_register_language", "注册新的编程语言注释规则。当遇到 CFM 尚不支持的语言时，通过此工具添加该语言的注释语法，使 cfm_scan 能正确提取其表头。注册仅在当前会话有效。", {
+        name: z
+            .string()
+            .describe("语言名称（如 elixir, dart, haskell）"),
+        comment_start: z
+            .string()
+            .describe("CFM 表头的起始标记（如 \"#---\"）"),
+        comment_end: z
+            .string()
+            .describe("CFM 表头的结束标记（如 \"#---\"）"),
+        extensions: z
+            .array(z.string())
+            .describe("该语言的文件扩展名列表（如 [\".ex\", \".exs\"]）"),
+        line_prefix: z
+            .string()
+            .nullable()
+            .optional()
+            .default(null)
+            .describe("行前缀（脚本语言使用，如 \"# \"），C 家族传 null"),
+    }, async ({ name, comment_start, comment_end, extensions, line_prefix }) => {
+        const result = registerNewLanguage(name, {
+            comment_start,
+            comment_end,
+            extensions,
+            line_prefix,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+            isError: !result.success,
+        };
+    });
+    // ─── 启动 Server ────────────────────────────────────────
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+// 启动
+main().catch((error) => {
+    console.error("MCP Server 启动失败:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/parser.d.ts

@@ -0,0 +1,16 @@
+import { type CfmEntry } from "./schema.js";
+/**
+ * 从单个文件中提取 CFM 表头
+ *
+ * 提取流程：
+ * 1. 根据文件扩展名查找语言注释规则
+ * 2. 在文件开头区域匹配 comment_start / comment_end 标记对
+ * 3. 提取标记之间的文本，去除 line_prefix（如 "# "）
+ * 4. 用 YAML 解析器解析，再用 Zod Schema 校验
+ *
+ * @param filePath - 文件的绝对路径
+ * @param relativePath - 用于输出的相对路径
+ * @returns CFM 条目（含解析数据或 null + 警告信息）
+ */
+export declare function extractFrontmatter(filePath: string, relativePath: string): Promise<CfmEntry>;
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAcA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAK5D;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACpC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACrB,OAAO,CAAC,QAAQ,CAAC,CAuFnB"}

package/dist/parser.js

@@ -0,0 +1,162 @@
+/*---
+intent: "从代码文件中提取 CFM 表头：根据语言规则定位注释标记，去除行前缀，解析 YAML 并校验"
+role: service
+exports:
+  - "extractFrontmatter: 从单个文件中提取并解析 CFM 表头"
+depends_on: ["./registry.ts", "./schema.ts", "yaml"]
+when_to_load: "修改表头提取逻辑或 YAML 解析方式时加载"
+ai_notes: "使用简单文本匹配而非 AST 解析，保持零重型依赖的设计原则"
+---*/
+import { extname } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { getLanguageByExtension } from "./registry.js";
+import { CfmSchemaLoose } from "./schema.js";
+/** 读取文件的最大字节数（只读开头部分以查找表头） */
+const MAX_READ_BYTES = 4096;
+/**
+ * 从单个文件中提取 CFM 表头
+ *
+ * 提取流程：
+ * 1. 根据文件扩展名查找语言注释规则
+ * 2. 在文件开头区域匹配 comment_start / comment_end 标记对
+ * 3. 提取标记之间的文本，去除 line_prefix（如 "# "）
+ * 4. 用 YAML 解析器解析，再用 Zod Schema 校验
+ *
+ * @param filePath - 文件的绝对路径
+ * @param relativePath - 用于输出的相对路径
+ * @returns CFM 条目（含解析数据或 null + 警告信息）
+ */
+export async function extractFrontmatter(filePath, relativePath) {
+    const ext = extname(filePath);
+    const lang = getLanguageByExtension(ext);
+    // 未知语言类型，跳过
+    if (!lang) {
+        return {
+            file: relativePath,
+            language: undefined,
+            frontmatter: null,
+            warnings: ["未注册的文件类型，跳过表头提取"],
+        };
+    }
+    const warnings = [];
+    try {
+        // 只读取文件开头部分，节省 I/O
+        const content = await readFileHead(filePath, MAX_READ_BYTES);
+        const { comment_start, comment_end, line_prefix } = lang.rule;
+        // 查找表头区域
+        const headerContent = extractHeaderContent(content, comment_start, comment_end, line_prefix);
+        if (!headerContent) {
+            return {
+                file: relativePath,
+                language: lang.name,
+                frontmatter: null,
+            };
+        }
+        // 解析 YAML
+        let parsed;
+        try {
+            parsed = parseYaml(headerContent);
+        }
+        catch (yamlError) {
+            return {
+                file: relativePath,
+                language: lang.name,
+                frontmatter: null,
+                warnings: [`YAML 解析失败: ${yamlError.message}`],
+            };
+        }
+        // 如果 YAML 解析结果不是对象（可能是纯文本）
+        if (!parsed || typeof parsed !== "object") {
+            return {
+                file: relativePath,
+                language: lang.name,
+                frontmatter: null,
+                warnings: ["表头内容不是有效的 YAML 对象"],
+            };
+        }
+        // 宽松模式校验
+        const validation = CfmSchemaLoose.safeParse(parsed);
+        if (!validation.success) {
+            warnings.push(`Schema 校验警告: ${validation.error.issues.map((i) => i.message).join("; ")}`);
+        }
+        // 检查必选字段缺失
+        if (!parsed.intent)
+            warnings.push("缺少必选字段: intent");
+        if (!parsed.role)
+            warnings.push("缺少推荐字段: role");
+        if (!parsed.exports)
+            warnings.push("缺少推荐字段: exports");
+        return {
+            file: relativePath,
+            language: lang.name,
+            frontmatter: parsed,
+            warnings: warnings.length > 0 ? warnings : undefined,
+        };
+    }
+    catch (error) {
+        return {
+            file: relativePath,
+            language: lang.name,
+            frontmatter: null,
+            warnings: [`文件读取失败: ${error.message}`],
+        };
+    }
+}
+/**
+ * 从文件内容中提取表头区域的 YAML 文本
+ * @returns 清理后的 YAML 字符串，或 null（未找到表头）
+ */
+function extractHeaderContent(content, commentStart, commentEnd, linePrefix) {
+    // 统一换行符为 \n，兼容 Windows (\r\n) 和 Mac (\r)
+    const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    const trimmedContent = normalized.trimStart();
+    // 查找起始标记
+    if (!trimmedContent.startsWith(commentStart)) {
+        return null;
+    }
+    // 查找结束标记（从起始标记之后开始搜索）
+    const afterStart = trimmedContent.slice(commentStart.length);
+    const endIndex = afterStart.indexOf(commentEnd);
+    if (endIndex === -1) {
+        return null;
+    }
+    // 提取标记之间的原始文本
+    let rawContent = afterStart.slice(0, endIndex);
+    // 去除每行的 line_prefix（如 Python 的 "# "）
+    if (linePrefix) {
+        const lines = rawContent.split("\n");
+        rawContent = lines
+            .map((line) => {
+            const trimmedLine = line.trimStart();
+            // 尝试完整前缀匹配（如 "# "），然后尝试去尾空格后的匹配（如 "#"）
+            if (trimmedLine.startsWith(linePrefix)) {
+                return trimmedLine.slice(linePrefix.length);
+            }
+            const trimmedPrefix = linePrefix.trim();
+            if (trimmedPrefix && trimmedLine.startsWith(trimmedPrefix)) {
+                return trimmedLine.slice(trimmedPrefix.length);
+            }
+            return line;
+        })
+            .join("\n");
+    }
+    const cleaned = rawContent.trim();
+    return cleaned.length > 0 ? cleaned : null;
+}
+/**
+ * 只读取文件的前 N 个字节
+ * 大文件只需读开头就能找到表头，避免全文读取
+ */
+async function readFileHead(filePath, maxBytes) {
+    const { open } = await import("node:fs/promises");
+    const fileHandle = await open(filePath, "r");
+    try {
+        const buffer = Buffer.alloc(maxBytes);
+        const { bytesRead } = await fileHandle.read(buffer, 0, maxBytes, 0);
+        return buffer.slice(0, bytesRead).toString("utf-8");
+    }
+    finally {
+        await fileHandle.close();
+    }
+}
+//# sourceMappingURL=parser.js.map

package/dist/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"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"}

package/dist/registry.d.ts

@@ -0,0 +1,28 @@
+import { type LanguageRule } from "./schema.js";
+/**
+ * 从 languages/registry.json 加载内置语言注册表
+ * 应在 MCP Server 启动时调用一次
+ */
+export declare function loadRegistry(): Promise<void>;
+/**
+ * 根据文件扩展名查找对应的语言注释规则
+ * @param ext - 文件扩展名，如 ".js", ".py"
+ * @returns 匹配的语言规则，未找到则返回 null
+ */
+export declare function getLanguageByExtension(ext: string): {
+    name: string;
+    rule: LanguageRule;
+} | null;
+/**
+ * 运行时动态注册新语言
+ * @param name - 语言名称
+ * @param rule - 语言注释规则
+ * @throws 如果该语言已存在则抛出错误
+ */
+export declare function registerLanguage(name: string, rule: LanguageRule): void;
+/**
+ * 获取所有已注册的语言及其规则
+ * @returns 语言名称与规则的映射
+ */
+export declare function getAllLanguages(): Record<string, LanguageRule>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAeA,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAcpE;;;GAGG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAmBlD;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAClC,GAAG,EAAE,MAAM,GACZ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAAG,IAAI,CAU7C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAuBvE;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAM9D"}

package/dist/registry.js

@@ -0,0 +1,96 @@
+/*---
+intent: "管理语言注册表：加载内置语言规则、按文件扩展名查找语言、支持运行时动态注册新语言"
+role: service
+exports:
+  - "loadRegistry: 从 registry.json 加载内置语言注册表"
+  - "getLanguageByExtension: 根据文件扩展名查找对应的语言规则"
+  - "registerLanguage: 运行时注册新的语言注释规则"
+  - "getAllLanguages: 获取所有已注册的语言列表"
+depends_on: ["./schema.ts", "../languages/registry.json"]
+when_to_load: "修改语言查找逻辑或注册机制时加载"
+---*/
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { LanguageRuleSchema } from "./schema.js";
+/**
+ * 语言注册表：语言名称 → 注释规则映射
+ * 键为语言名(如 "javascript")，值为注释标记配置
+ */
+const registry = new Map();
+/**
+ * 扩展名反向索引：扩展名 → 语言名映射
+ * 用于快速按扩展名查找语言
+ */
+const extensionIndex = new Map();
+/**
+ * 从 languages/registry.json 加载内置语言注册表
+ * 应在 MCP Server 启动时调用一次
+ */
+export async function loadRegistry() {
+    // 定位 registry.json 文件路径（相对于当前模块）
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+    const registryPath = join(__dirname, "..", "languages", "registry.json");
+    const raw = await readFile(registryPath, "utf-8");
+    const data = JSON.parse(raw);
+    for (const [name, rule] of Object.entries(data)) {
+        // 用 Zod 校验每条语言规则的格式
+        const parsed = LanguageRuleSchema.parse(rule);
+        registry.set(name, parsed);
+        // 建立扩展名 → 语言名的反向索引
+        for (const ext of parsed.extensions) {
+            extensionIndex.set(ext.toLowerCase(), name);
+        }
+    }
+}
+/**
+ * 根据文件扩展名查找对应的语言注释规则
+ * @param ext - 文件扩展名，如 ".js", ".py"
+ * @returns 匹配的语言规则，未找到则返回 null
+ */
+export function getLanguageByExtension(ext) {
+    const normalizedExt = ext.toLowerCase();
+    const langName = extensionIndex.get(normalizedExt);
+    if (!langName)
+        return null;
+    const rule = registry.get(langName);
+    if (!rule)
+        return null;
+    return { name: langName, rule };
+}
+/**
+ * 运行时动态注册新语言
+ * @param name - 语言名称
+ * @param rule - 语言注释规则
+ * @throws 如果该语言已存在则抛出错误
+ */
+export function registerLanguage(name, rule) {
+    const normalizedName = name.toLowerCase();
+    if (registry.has(normalizedName)) {
+        throw new Error(`语言 "${name}" 已存在于注册表中。如需更新，请先移除旧注册。`);
+    }
+    // 检查扩展名是否与已有语言冲突
+    for (const ext of rule.extensions) {
+        const existing = extensionIndex.get(ext.toLowerCase());
+        if (existing) {
+            throw new Error(`扩展名 "${ext}" 已被语言 "${existing}" 注册。`);
+        }
+    }
+    registry.set(normalizedName, rule);
+    for (const ext of rule.extensions) {
+        extensionIndex.set(ext.toLowerCase(), normalizedName);
+    }
+}
+/**
+ * 获取所有已注册的语言及其规则
+ * @returns 语言名称与规则的映射
+ */
+export function getAllLanguages() {
+    const result = {};
+    for (const [name, rule] of registry.entries()) {
+        result[name] = rule;
+    }
+    return result;
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;KAUK;AAEL,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAqB,MAAM,aAAa,CAAC;AAEpE;;;GAGG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;AAEjD;;;GAGG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,EAAkB,CAAC;AAEjD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY;IAC9B,iCAAiC;IACjC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtC,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,eAAe,CAAC,CAAC;IAEzE,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;IAExD,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9C,oBAAoB;QACpB,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9C,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAE3B,mBAAmB;QACnB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YAClC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,IAAI,CAAC,CAAC;QAChD,CAAC;IACL,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAClC,GAAW;IAEX,MAAM,aAAa,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IACxC,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAEnD,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAE3B,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACpC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAEvB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AACpC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,IAAkB;IAC7D,MAAM,cAAc,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IAE1C,IAAI,QAAQ,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACX,OAAO,IAAI,0BAA0B,CACxC,CAAC;IACN,CAAC;IAED,iBAAiB;IACjB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;QACvD,IAAI,QAAQ,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CACX,QAAQ,GAAG,WAAW,QAAQ,OAAO,CACxC,CAAC;QACN,CAAC;IACL,CAAC;IAED,QAAQ,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;IACnC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QAChC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,cAAc,CAAC,CAAC;IAC1D,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC3B,MAAM,MAAM,GAAiC,EAAE,CAAC;IAChD,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;QAC5C,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxB,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC"}