autosnippet 3.2.9 → 3.2.11

package/dist/lib/external/mcp/handlers/LanguageExtensions.js

@@ -0,0 +1,941 @@
+/**
+ * LanguageExtensions — 语言检测与语言特有扩展字段构建
+ *
+ * 负责：
+ *   - 文件扩展名 → 语言映射（委托 LanguageService）
+ *   - langStats 聚合 → 主语言推断（委托 LanguageService）
+ *   - 主语言 → 语言扩展字段（分析维度、典型模式、反模式、Guard 规则等）
+ *
+ * 注册表驱动：
+ *   所有语言知识集中在 LANG_REGISTRY 中，新增语言只需添加条目即可。
+ *   覆盖 LanguageService.KNOWN_PROGRAMMING_LANGS 全部 14 种编程语言。
+ */
+import { LanguageService } from '#shared/LanguageService.js';
+/** 根据文件扩展名推断语言 — 委托给 LanguageService（唯一来源） */
+export function inferLang(filename) {
+    return LanguageService.inferLang(filename);
+}
+/** 从 langStats 推断主语言 — 委托给 LanguageService（唯一来源） */
+export function detectPrimaryLanguage(langStats) {
+    return LanguageService.detectPrimary(langStats);
+}
+// ═══════════════════════════════════════════════════════════
+// 语言扩展注册表 — 按 lang ID 索引
+// ═══════════════════════════════════════════════════════════
+/**
+ * JS/TS 共享扩展生成器（根据具体 lang 微调差异点）
+ * @param {'javascript'|'typescript'} lang
+ */
+function _buildJsTsEntry(lang) {
+    const isTs = lang === 'typescript';
+    return {
+        extraDimensions: [
+            {
+                id: 'module-system',
+                label: '模块系统',
+                guide: 'ESM vs CJS、dynamic import、barrel export、tree-shaking',
+            },
+            {
+                id: 'type-safety',
+                label: '类型安全',
+                guide: isTs
+                    ? 'strict 模式、泛型、类型守卫、Utility Types、satisfies 操作符'
+                    : 'JSDoc 类型标注、.d.ts 声明、@ts-check',
+            },
+            {
+                id: 'async-pattern',
+                label: '异步模式',
+                guide: 'Promise 链、async/await、Error 处理、AbortController、AsyncIterator',
+            },
+            {
+                id: 'framework-convention',
+                label: '框架约定',
+                guide: 'React Hooks/Vue Composition/Node.js 中间件/Svelte runes 等框架特有模式',
+            },
+        ],
+        typicalPatterns: [
+            'async/await + try-catch 错误处理',
+            'barrel export (index.ts re-export)',
+            isTs ? '泛型约束 <T extends Base>、satisfies 编译期验证' : 'JSDoc @param/@returns 类型标注',
+            'Optional chaining (?.) + nullish coalescing (??)',
+            'Factory function / 闭包替代 class',
+            'Event emitter / pub-sub 解耦',
+            isTs ? 'Discriminated union 状态建模' : 'Symbol 作为私有 key',
+        ],
+        commonAntiPatterns: [
+            { bad: 'any 类型滥用', why: '丧失类型安全', fix: '定义具体接口或泛型' },
+            { bad: '.catch() 空回调', why: '静默吞掉错误', fix: '记录日志或 re-throw' },
+            { bad: 'callback hell', why: '嵌套层级过深难以维护', fix: 'async/await 改写' },
+            {
+                bad: 'for...in 遍历数组',
+                why: '遍历原型链属性、顺序不保证',
+                fix: 'for...of 或 Array 方法',
+            },
+        ],
+        suggestedGuardRules: [
+            ...(isTs
+                ? [
+                    {
+                        pattern: ': any',
+                        severity: 'warning',
+                        message: '避免 any 类型，使用 unknown 或具体类型',
+                    },
+                ]
+                : []),
+            { pattern: '\\.catch\\(\\(\\)\\s*=>', severity: 'info', message: 'catch 回调不应为空' },
+            { pattern: 'console\\.log', severity: 'info', message: '生产代码移除 console.log' },
+            { pattern: 'eval\\(', severity: 'error', message: '禁止使用 eval，存在安全风险' },
+        ],
+        agentCautions: [
+            '使用 ESM (import/export) 而非 CJS (require/module.exports)',
+            '异步函数必须处理错误 (try-catch 或 .catch)',
+            isTs
+                ? '启用 strict 模式，优先使用 unknown 替代 any'
+                : '使用 JSDoc 或 @ts-check 标注关键函数类型',
+            'Node.js 中注意 unhandledRejection 处理',
+            '优先使用 structuredClone() 深拷贝，避免 JSON.parse(JSON.stringify())',
+        ],
+    };
+}
+/** @type {Readonly<Record<string, object>>} */
+const LANG_REGISTRY = Object.freeze({
+    // ── Swift ──────────────────────────────────────────────────
+    swift: {
+        extraDimensions: [
+            {
+                id: 'concurrency',
+                label: 'Swift Concurrency',
+                guide: 'async/await、Actor、@Sendable、TaskGroup、MainActor、AsyncStream 用法',
+            },
+            {
+                id: 'protocol-oriented',
+                label: '面向协议编程',
+                guide: 'Protocol 扩展、条件一致性、PAT (Protocol with Associated Type)、some/any 关键字',
+            },
+            {
+                id: 'property-wrapper',
+                label: 'Property Wrapper',
+                guide: '@Published、@State、@Environment、@Observable (Observation)、自定义 Property Wrapper',
+            },
+            {
+                id: 'value-semantics',
+                label: '值语义',
+                guide: 'struct vs class 决策、COW (Copy-on-Write)、Equatable/Hashable、~Copyable (non-copyable types)',
+            },
+        ],
+        typicalPatterns: [
+            'Result<Success, Failure> 统一错误处理',
+            'Protocol + Extension 默认实现',
+            '@MainActor 标注 UI 相关类',
+            'Combine Publisher / AsyncStream 数据流',
+            'enum + associated value 状态建模',
+            'Codable 自定义 CodingKeys',
+            '@Observable 宏 (Observation 框架)',
+        ],
+        commonAntiPatterns: [
+            { bad: '强制 try! / as! 解包', why: '运行时 crash', fix: 'guard let / if let / do-catch' },
+            {
+                bad: 'DispatchQueue.main.async 更新 UI',
+                why: 'Swift Concurrency 下造成 data race',
+                fix: '@MainActor',
+            },
+            {
+                bad: '闭包中不用 [weak self]',
+                why: '循环引用导致内存泄漏',
+                fix: '[weak self] / [unowned self]',
+            },
+            {
+                bad: '大量使用 AnyView 擦除类型',
+                why: 'SwiftUI diff 性能下降',
+                fix: '使用泛型或 @ViewBuilder',
+            },
+        ],
+        suggestedGuardRules: [
+            { pattern: 'try!', severity: 'warning', message: '避免 force try，使用 do-catch' },
+            { pattern: 'as!', severity: 'warning', message: '避免 force cast，使用 as?' },
+            { pattern: 'DispatchQueue\\.main', severity: 'info', message: '考虑使用 @MainActor 替代' },
+            { pattern: 'AnyView', severity: 'info', message: '避免 AnyView，使用泛型或 @ViewBuilder' },
+        ],
+        agentCautions: [
+            '新代码优先使用 Swift Concurrency (async/await) 而非 GCD/DispatchQueue',
+            'UI 相关类和方法标注 @MainActor',
+            '优先使用 struct（值类型），class 仅在需要引用语义时使用',
+            '闭包捕获 self 时必须使用 [weak self] 或 [unowned self]',
+            '使用 guard let 提前返回，避免嵌套 if let',
+        ],
+    },
+    // ── Objective-C ────────────────────────────────────────────
+    objectivec: {
+        extraDimensions: [
+            {
+                id: 'memory-management',
+                label: '内存管理',
+                guide: 'ARC 下的 strong/weak/unsafe_unretained、autorelease、dealloc 模式',
+            },
+            {
+                id: 'category-extension',
+                label: 'Category/Extension',
+                guide: 'Category 方法命名冲突、Class Extension 私有属性',
+            },
+            {
+                id: 'block-pattern',
+                label: 'Block 模式',
+                guide: 'Block 循环引用、__weak/__strong dance、Block 作为回调',
+            },
+            {
+                id: 'nullability',
+                label: 'Nullability 标注',
+                guide: 'nullable/nonnull/NS_ASSUME_NONNULL、与 Swift 互操作',
+            },
+        ],
+        typicalPatterns: [
+            'delegate + protocol 回调模式',
+            'Category 扩展系统类',
+            '__weak typeof(self) weakSelf = self',
+            'NS_ASSUME_NONNULL_BEGIN/END 包裹头文件',
+            'dispatch_once 单例',
+            'KVO 属性观察',
+        ],
+        commonAntiPatterns: [
+            { bad: 'Block 内直接引用 self', why: '循环引用', fix: '__weak + __strong dance' },
+            {
+                bad: '头文件缺少 nullability 标注',
+                why: 'Swift 桥接时全部变为 optional',
+                fix: 'NS_ASSUME_NONNULL + 显式 nullable',
+            },
+            {
+                bad: 'Category 方法不带前缀',
+                why: '与系统方法/其他库冲突',
+                fix: '加项目前缀如 xx_methodName',
+            },
+        ],
+        suggestedGuardRules: [
+            { pattern: '\\[self\\s', severity: 'warning', message: 'Block 内直接引用 self，考虑 __weak' },
+            {
+                pattern: '@property.*assign.*id',
+                severity: 'warning',
+                message: '对象属性使用 strong/weak 替代 assign',
+            },
+        ],
+        agentCautions: [
+            'ObjC 头文件必须包含 NS_ASSUME_NONNULL_BEGIN/END',
+            'Category 方法名加项目前缀避免冲突',
+            'Block 回调注意 __weak/__strong self dance',
+            'dealloc 中移除 KVO 观察者和 NSNotification 订阅',
+        ],
+    },
+    // ── Python ─────────────────────────────────────────────────
+    python: {
+        extraDimensions: [
+            {
+                id: 'type-hints',
+                label: '类型注解',
+                guide: 'typing 模块、Protocol、TypeVar、Generic、dataclass、TypeAlias (3.12+)',
+            },
+            {
+                id: 'async-io',
+                label: '异步 IO',
+                guide: 'asyncio、aiohttp、async generators、TaskGroup (3.11+)',
+            },
+            {
+                id: 'package-structure',
+                label: '包结构',
+                guide: '__init__.py、相对导入、pyproject.toml、src-layout',
+            },
+            {
+                id: 'testing',
+                label: '测试模式',
+                guide: 'pytest fixtures、parametrize、mock/patch、conftest.py 层级',
+            },
+        ],
+        typicalPatterns: [
+            'dataclass / pydantic BaseModel 数据建模',
+            'context manager (with statement / @contextmanager)',
+            'decorator 横切关注点',
+            'typing.Protocol 鸭子类型接口',
+            'generator / yield 惰性求值',
+            'match-case 结构化模式匹配 (3.10+)',
+            'pathlib.Path 替代 os.path 字符串操作',
+        ],
+        commonAntiPatterns: [
+            {
+                bad: 'bare except:',
+                why: '捕获所有异常包括 SystemExit/KeyboardInterrupt',
+                fix: 'except Exception as e:',
+            },
+            {
+                bad: '可变默认参数 def f(x: any[]=[])',
+                why: '函数间共享可变状态',
+                fix: 'def f(x=None): x = x or []',
+            },
+            { bad: 'import *', why: '污染命名空间、难以追踪来源', fix: '显式导入: from mod import name' },
+            { bad: '全局可变状态', why: '并发不安全、测试困难', fix: '依赖注入或函数参数传递' },
+        ],
+        suggestedGuardRules: [
+            {
+                pattern: 'except:',
+                severity: 'warning',
+                message: '避免 bare except，至少 except Exception',
+            },
+            { pattern: 'import \\*', severity: 'warning', message: '避免 wildcard import，使用显式导入' },
+            {
+                pattern: 'os\\.system\\(',
+                severity: 'error',
+                message: '使用 subprocess.run() 替代 os.system()',
+            },
+            { pattern: 'eval\\(', severity: 'error', message: '禁止 eval()，存在代码注入风险' },
+        ],
+        agentCautions: [
+            '函数签名使用 type hints (PEP 484+)',
+            '使用 dataclass 或 pydantic 建模数据，避免裸 dict',
+            '避免 bare except，至少 except Exception',
+            '使用 pathlib.Path 处理文件路径',
+            '异步代码使用 asyncio.TaskGroup (3.11+) 做结构化并发',
+        ],
+    },
+    // ── Kotlin ─────────────────────────────────────────────────
+    kotlin: {
+        extraDimensions: [
+            {
+                id: 'coroutines',
+                label: '协程',
+                guide: 'suspend、Flow、CoroutineScope、Dispatchers、structured concurrency',
+            },
+            {
+                id: 'null-safety',
+                label: '空安全',
+                guide: '?.、!!、let、elvis ?:、requireNotNull、lateinit',
+            },
+            {
+                id: 'dsl-builder',
+                label: 'DSL/Builder',
+                guide: 'Kotlin DSL、buildList、apply/run/let/also 作用域函数',
+            },
+            {
+                id: 'multiplatform',
+                label: 'Kotlin Multiplatform',
+                guide: 'expect/actual、共享模块、平台特定实现',
+            },
+        ],
+        typicalPatterns: [
+            'sealed class/interface 状态建模',
+            'data class 值对象',
+            'extension function 扩展已有类',
+            'Flow 链式异步流',
+            'companion object 工厂方法',
+            'when 表达式穷举枚举/sealed class',
+            'inline function + reified 泛型',
+        ],
+        commonAntiPatterns: [
+            { bad: '!! 强制非空断言', why: '运行时 NPE', fix: '?.let {} 或 elvis ?: defaultValue' },
+            {
+                bad: 'GlobalScope.launch',
+                why: '泄漏协程，无法取消',
+                fix: '使用 viewModelScope/lifecycleScope',
+            },
+            { bad: 'var 过度使用', why: '可变状态难以追踪', fix: '优先使用 val（不可变）' },
+        ],
+        suggestedGuardRules: [
+            { pattern: '!!', severity: 'warning', message: '避免 !! 操作符，使用 ?.let 或 elvis ?:' },
+            {
+                pattern: 'GlobalScope',
+                severity: 'warning',
+                message: '使用结构化并发 scope 替代 GlobalScope',
+            },
+            { pattern: 'lateinit', severity: 'info', message: '确认 lateinit 使用合理，考虑 lazy 替代' },
+        ],
+        agentCautions: [
+            '避免 !! 操作符，使用安全调用 ?.let 或 elvis ?: ',
+            '协程使用结构化并发 (viewModelScope/lifecycleScope)',
+            '优先 data class + sealed class/interface 建模',
+            '利用 when 表达式穷举所有分支',
+            '优先使用 val 不可变声明',
+        ],
+    },
+    // ── Java ───────────────────────────────────────────────────
+    java: {
+        extraDimensions: [
+            {
+                id: 'concurrency',
+                label: '并发',
+                guide: 'synchronized、ExecutorService、CompletableFuture、虚拟线程 (21+)、StructuredTaskScope (preview)',
+            },
+            { id: 'generics', label: '泛型', guide: '类型擦除、通配符 <? extends/super>、类型安全容器' },
+            {
+                id: 'modern-java',
+                label: '现代 Java',
+                guide: 'record (16+)、sealed class (17+)、pattern matching (21+)、text block',
+            },
+        ],
+        typicalPatterns: [
+            'Builder 模式构造复杂对象',
+            'Stream API 集合处理',
+            'Optional 空值处理',
+            'record 类型替代 POJO (Java 16+)',
+            '依赖注入 (@Inject/@Autowired)',
+            'sealed interface + record 代数数据类型 (Java 17+)',
+            'try-with-resources 自动关闭资源',
+        ],
+        commonAntiPatterns: [
+            {
+                bad: '返回 null 表示不存在',
+                why: '调用方容易忘记 null check',
+                fix: 'Optional<T> 或 @Nullable 标注',
+            },
+            { bad: 'raw type 泛型', why: '运行时 ClassCastException', fix: '指定具体类型参数' },
+            { bad: 'catch (Exception e) {}', why: '静默吞掉异常', fix: '至少记录日志或 rethrow' },
+            {
+                bad: 'new Thread().start()',
+                why: '无法管理线程生命周期',
+                fix: 'ExecutorService 或虚拟线程',
+            },
+        ],
+        suggestedGuardRules: [
+            {
+                pattern: 'catch\\s*\\(\\s*Exception',
+                severity: 'info',
+                message: '避免宽泛的 Exception catch，使用具体异常类型',
+            },
+            {
+                pattern: '\\.printStackTrace\\(\\)',
+                severity: 'warning',
+                message: '使用日志框架替代 printStackTrace',
+            },
+            {
+                pattern: 'new Thread\\(',
+                severity: 'info',
+                message: '考虑使用 ExecutorService 或虚拟线程',
+            },
+        ],
+        agentCautions: [
+            '优先使用 Optional 处理可空返回值',
+            '使用 Stream API 替代手动循环',
+            '并发使用 ExecutorService 或虚拟线程 (21+) 而非 raw Thread',
+            '使用 try-with-resources 管理 AutoCloseable 资源',
+            '数据载体优先使用 record (16+) 替代手写 POJO',
+        ],
+    },
+    // ── Go ─────────────────────────────────────────────────────
+    go: {
+        extraDimensions: [
+            {
+                id: 'goroutine',
+                label: 'Goroutine/Channel',
+                guide: '并发模式、channel、select、context 传播、errgroup',
+            },
+            {
+                id: 'error-handling',
+                label: '错误处理',
+                guide: 'error interface、errors.Is/As、sentinel errors、%w wrap、多错误 errors.Join (1.20+)',
+            },
+            {
+                id: 'interface',
+                label: '接口设计',
+                guide: '隐式实现、小接口、io.Reader/Writer 组合、Accept interfaces return structs',
+            },
+        ],
+        typicalPatterns: [
+            'if err != nil { return err }',
+            'context.Context 贯穿调用链',
+            'functional options 模式',
+            'table-driven tests',
+            'interface 在消费侧定义',
+            'defer 确保资源清理',
+            'embed 嵌入结构体组合复用',
+        ],
+        commonAntiPatterns: [
+            { bad: '忽略 error 返回值 _', why: '静默丢失错误信息', fix: '检查并传播 error' },
+            {
+                bad: 'goroutine 无退出控制',
+                why: '泄漏 goroutine',
+                fix: 'context.WithCancel / done channel',
+            },
+            { bad: 'init() 函数过度使用', why: '隐式副作用、测试困难', fix: '显式初始化函数 + 依赖注入' },
+            { bad: 'sync.Mutex 包级变量', why: '全局可变状态', fix: '封装到 struct 内' },
+        ],
+        suggestedGuardRules: [
+            {
+                pattern: 'panic\\(',
+                severity: 'warning',
+                message: '仅在不可恢复错误时使用 panic，正常错误返回 error',
+            },
+            {
+                pattern: 'log\\.Fatal',
+                severity: 'info',
+                message: 'log.Fatal 会调用 os.Exit，确认场景合理',
+            },
+            {
+                pattern: 'go func\\(',
+                severity: 'info',
+                message: '确保 goroutine 有退出路径（context/done channel）',
+            },
+        ],
+        agentCautions: [
+            '函数必须检查并传播 error，不要忽略 _',
+            '使用 context.Context 作为第一个参数',
+            'goroutine 确保有退出路径，使用 errgroup 管理并发',
+            'defer 放在资源获取之后立即声明',
+            '接口在消费方定义，保持小而精',
+        ],
+    },
+    // ── Rust ───────────────────────────────────────────────────
+    rust: {
+        extraDimensions: [
+            {
+                id: 'ownership',
+                label: '所有权/借用',
+                guide: 'ownership、borrowing、lifetime、Clone vs Copy、interior mutability (RefCell/Mutex)',
+            },
+            {
+                id: 'error-handling',
+                label: '错误处理',
+                guide: 'Result<T,E>、? 操作符、thiserror/anyhow、自定义 Error enum',
+            },
+            {
+                id: 'trait-system',
+                label: 'Trait 系统',
+                guide: 'trait bound、impl Trait、dyn Trait、derive 宏、blanket impl',
+            },
+            {
+                id: 'async-runtime',
+                label: '异步运行时',
+                guide: 'tokio/async-std、Future、Pin、async trait、select!',
+            },
+        ],
+        typicalPatterns: [
+            'Result<T, E> + ? 操作符链式传播',
+            'enum 代数数据类型 + pattern matching',
+            'impl Trait 返回类型 / dyn Trait 动态分发',
+            'Builder 模式 (consuming self)',
+            '#[derive(Debug, Clone, ...)] 自动实现',
+            'From/Into trait 类型转换',
+            'Iterator 链式组合子',
+        ],
+        commonAntiPatterns: [
+            { bad: '.unwrap() / .expect() 泛滥', why: '生产环境 panic', fix: '? 操作符或 match' },
+            { bad: '.clone() 逃避借用检查', why: '隐藏性能问题', fix: '重新设计所有权或使用引用' },
+            {
+                bad: 'Arc<Mutex<T>> 过度使用',
+                why: '运行时锁开销',
+                fix: '优先考虑消息传递 (channel) 或更细粒度设计',
+            },
+        ],
+        suggestedGuardRules: [
+            {
+                pattern: '\\.unwrap\\(\\)',
+                severity: 'warning',
+                message: '避免 unwrap()，使用 ? 或 expect("reason")',
+            },
+            {
+                pattern: 'unsafe\\s*\\{',
+                severity: 'warning',
+                message: '审查 unsafe 代码块，确保 safety invariant 有文档',
+            },
+            {
+                pattern: 'todo!\\(\\)|unimplemented!\\(\\)',
+                severity: 'info',
+                message: '确认 todo!/unimplemented! 不会进入生产环境',
+            },
+        ],
+        agentCautions: [
+            '优先使用借用 (&T / &mut T) 而非 clone',
+            '错误类型使用 thiserror 定义，应用层使用 anyhow',
+            '避免 unwrap()，使用 ? 或 expect("有意义的说明")',
+            'unsafe 代码块必须写 // SAFETY: 注释说明 invariant',
+            '优先使用 Iterator 组合子替代手动循环',
+        ],
+    },
+    // ── C ──────────────────────────────────────────────────────
+    c: {
+        extraDimensions: [
+            {
+                id: 'memory-safety',
+                label: '内存安全',
+                guide: 'malloc/free 配对、指针生命周期、缓冲区溢出防范、AddressSanitizer',
+            },
+            {
+                id: 'preprocessor',
+                label: '预处理器',
+                guide: '#define 宏、条件编译、include guard / #pragma once、X-Macro 模式',
+            },
+            {
+                id: 'api-design',
+                label: 'API 设计',
+                guide: 'opaque pointer(PIMPL)、const 正确性、错误码约定、头文件组织',
+            },
+        ],
+        typicalPatterns: [
+            'struct + 函数指针模拟 OOP',
+            'typedef 定义公共 API 类型',
+            'const 修饰只读参数',
+            '错误码 + goto cleanup 资源释放',
+            'include guard (#ifndef ... #define ... #endif)',
+            'opaque pointer 隐藏实现细节',
+        ],
+        commonAntiPatterns: [
+            {
+                bad: 'malloc 后不检查 NULL',
+                why: 'OOM 时解引用空指针 → crash',
+                fix: 'if (!ptr) { handle_error(); }',
+            },
+            {
+                bad: '缓冲区无边界检查',
+                why: '缓冲区溢出 → 安全漏洞',
+                fix: '使用 snprintf/strncat + 显式长度参数',
+            },
+            {
+                bad: 'malloc/free 未配对',
+                why: '内存泄漏或 double free',
+                fix: '集中管理资源生命周期、使用 goto cleanup 模式',
+            },
+            {
+                bad: '函数式宏无括号包裹参数',
+                why: '宏展开时运算优先级错误',
+                fix: '#define MAX(a,b) ((a) > (b) ? (a) : (b))',
+            },
+        ],
+        suggestedGuardRules: [
+            {
+                pattern: 'gets\\(',
+                severity: 'error',
+                message: '禁止使用 gets()，已被移除（CVE 风险），使用 fgets()',
+            },
+            {
+                pattern: 'sprintf\\(',
+                severity: 'warning',
+                message: '使用 snprintf() 替代 sprintf()，防止缓冲区溢出',
+            },
+            {
+                pattern: 'strcpy\\(',
+                severity: 'warning',
+                message: '使用 strncpy()/strlcpy() 替代 strcpy()',
+            },
+            {
+                pattern: 'atoi\\(',
+                severity: 'info',
+                message: '使用 strtol() 替代 atoi()，可检测解析错误',
+            },
+        ],
+        agentCautions: [
+            'malloc/calloc 后必须检查返回值是否为 NULL',
+            '使用 snprintf/strncat 等带长度参数的安全函数',
+            '每个 malloc 必须有对应 free，推荐 goto cleanup 模式',
+            '头文件使用 include guard 或 #pragma once',
+            '函数参数中只读指针用 const 修饰',
+        ],
+    },
+    // ── C++ ────────────────────────────────────────────────────
+    cpp: {
+        extraDimensions: [
+            {
+                id: 'raii',
+                label: 'RAII / 智能指针',
+                guide: 'unique_ptr、shared_ptr、weak_ptr、自定义 deleter、make_unique/make_shared',
+            },
+            {
+                id: 'templates',
+                label: '模板 / Concepts',
+                guide: '函数模板、类模板、SFINAE、Concepts (C++20)、requires 表达式',
+            },
+            {
+                id: 'move-semantics',
+                label: '移动语义',
+                guide: '右值引用 (&&)、std::move、完美转发 (std::forward)、Rule of 0/3/5',
+            },
+            {
+                id: 'modern-cpp',
+                label: '现代 C++ 特性',
+                guide: 'constexpr、std::optional、std::variant、structured bindings、ranges (C++20)',
+            },
+        ],
+        typicalPatterns: [
+            'RAII 管理资源 (unique_ptr/shared_ptr)',
+            'range-based for 遍历容器',
+            'constexpr 编译期求值',
+            'override + final 虚函数覆盖',
+            'std::optional 替代 nullable pointer',
+            'std::variant + std::visit 类型安全联合',
+            'auto + structured bindings 简化声明',
+        ],
+        commonAntiPatterns: [
+            {
+                bad: 'new/delete 手动管理内存',
+                why: '容易泄漏，异常不安全',
+                fix: 'std::make_unique / std::make_shared',
+            },
+            { bad: 'catch(...) 吃掉所有异常', why: '隐藏真实错误', fix: '捕获具体异常类型并处理' },
+            { bad: '对象切片 (slicing)', why: '派生类信息丢失', fix: '使用指针/引用传递多态对象' },
+            {
+                bad: '#define 常量/函数',
+                why: '无类型检查、调试困难',
+                fix: 'constexpr 变量 / inline 函数 / 模板',
+            },
+        ],
+        suggestedGuardRules: [
+            {
+                pattern: '\\bnew\\b(?!.*unique_ptr|.*shared_ptr)',
+                severity: 'warning',
+                message: '优先使用 make_unique/make_shared 替代 raw new',
+            },
+            { pattern: '\\bdelete\\b', severity: 'warning', message: '避免手动 delete，使用智能指针' },
+            {
+                pattern: 'using namespace std',
+                severity: 'info',
+                message: '避免在头文件中使用 using namespace',
+            },
+            {
+                pattern: 'reinterpret_cast',
+                severity: 'warning',
+                message: '审查 reinterpret_cast 使用是否合理',
+            },
+        ],
+        agentCautions: [
+            '使用智能指针 (unique_ptr/shared_ptr) 而非 raw new/delete',
+            '虚函数覆盖必须加 override 关键字',
+            '优先使用 constexpr 替代 #define 宏常量',
+            '遵循 Rule of Zero — 除非必要，不自定义析构/拷贝/移动',
+            '头文件使用前置声明减少编译依赖',
+        ],
+    },
+    // ── Ruby ───────────────────────────────────────────────────
+    ruby: {
+        extraDimensions: [
+            {
+                id: 'metaprogramming',
+                label: '元编程',
+                guide: 'define_method、method_missing、class_eval、open class、DSL 构建',
+            },
+            {
+                id: 'block-proc-lambda',
+                label: 'Block/Proc/Lambda',
+                guide: 'yield、block_given?、Proc.new vs lambda、& 转换',
+            },
+            {
+                id: 'convention-over-config',
+                label: '约定优于配置',
+                guide: 'Rails 约定 (命名/目录结构)、ActiveRecord 模式、concern 复用',
+            },
+        ],
+        typicalPatterns: [
+            'block + yield 迭代器模式',
+            'module include/prepend 混入',
+            'attr_accessor/attr_reader 声明式属性',
+            'Symbol 作为 Hash key',
+            'Enumerable 方法链 (map/select/reduce)',
+            'begin-rescue-ensure 异常处理',
+            'frozen_string_literal 优化字符串',
+        ],
+        commonAntiPatterns: [
+            {
+                bad: 'method_missing 无 respond_to_missing?',
+                why: '反射 API 行为不一致',
+                fix: '同时定义 respond_to_missing?',
+            },
+            { bad: 'Monkey-patch 核心类', why: '全局影响、版本升级冲突', fix: 'Refinements 或委托模式' },
+            {
+                bad: 'N+1 查询 (ActiveRecord)',
+                why: '数据库性能严重退化',
+                fix: 'includes/preload 预加载关联',
+            },
+        ],
+        suggestedGuardRules: [
+            {
+                pattern: 'eval\\(',
+                severity: 'error',
+                message: '避免 eval，存在代码注入风险，使用 send/public_send',
+            },
+            {
+                pattern: 'method_missing',
+                severity: 'info',
+                message: '确认配套定义了 respond_to_missing?',
+            },
+            {
+                pattern: '\\.find_each|\\.all\\.each',
+                severity: 'info',
+                message: '大数据集使用 find_each / in_batches 分批处理',
+            },
+        ],
+        agentCautions: [
+            '在文件头添加 # frozen_string_literal: true',
+            '元编程 (method_missing) 必须配套 respond_to_missing?',
+            'ActiveRecord 使用 includes/preload 避免 N+1',
+            '优先使用 module + include 组合，慎用 monkey-patching',
+            '异常处理使用 begin-rescue-ensure，不要 rescue Exception',
+        ],
+    },
+    // ── Dart ───────────────────────────────────────────────────
+    dart: {
+        extraDimensions: [
+            {
+                id: 'null-safety',
+                label: '空安全',
+                guide: '?、!、late、required、null-aware operators (?., ??, ??=)',
+            },
+            {
+                id: 'widget-composition',
+                label: 'Widget 组合 (Flutter)',
+                guide: 'StatelessWidget/StatefulWidget、Widget 拆分、const 构造器、InheritedWidget',
+            },
+            {
+                id: 'async-patterns',
+                label: '异步模式',
+                guide: 'Future、Stream、async*/yield*、Isolate 并行计算',
+            },
+            {
+                id: 'state-management',
+                label: '状态管理',
+                guide: 'Provider/Riverpod/Bloc/GetX、单向数据流、响应式编程',
+            },
+        ],
+        typicalPatterns: [
+            'const 构造器优化 Widget rebuild',
+            'StatelessWidget 优先、StatefulWidget 按需',
+            'extension methods 扩展已有类型',
+            'freezed + json_serializable 生成不可变模型',
+            'named parameters + required 提升可读性',
+            'Stream.listen / StreamBuilder 响应式 UI',
+            'sealed class (Dart 3) 穷举模式匹配',
+        ],
+        commonAntiPatterns: [
+            {
+                bad: '在 build() 中调用 setState 或异步操作',
+                why: '无限重建循环',
+                fix: '在 initState/事件回调中处理',
+            },
+            {
+                bad: '单个 Widget 过大 (>200 行)',
+                why: '难以维护和复用',
+                fix: '拆分为小 Widget + const 子树',
+            },
+            {
+                bad: '滥用 late 关键字',
+                why: '运行时 LateInitializationError',
+                fix: '使用 nullable (?) 或在声明处初始化',
+            },
+            {
+                bad: 'setState 管理全局状态',
+                why: '状态散落、难以追踪',
+                fix: '使用 Provider/Riverpod 等状态管理方案',
+            },
+        ],
+        suggestedGuardRules: [
+            { pattern: 'print\\(', severity: 'info', message: '生产代码使用 logger 替代 print()' },
+            {
+                pattern: '!\\s*\\.',
+                severity: 'info',
+                message: '审查 ! (force-unwrap) 使用，考虑 ?. 安全访问',
+            },
+            { pattern: 'dynamic', severity: 'warning', message: '避免 dynamic 类型，使用具体类型或泛型' },
+        ],
+        agentCautions: [
+            '优先使用 const 构造器优化 Widget 树性能',
+            '每个 Widget 保持单一职责，超过 100 行应考虑拆分',
+            '使用 sealed class (Dart 3+) 进行穷举模式匹配',
+            '异步操作使用 Future/Stream，计算密集型使用 Isolate',
+            '优先用 final 声明局部变量和类属性',
+        ],
+    },
+    // ── C# ─────────────────────────────────────────────────────
+    csharp: {
+        extraDimensions: [
+            {
+                id: 'async-await',
+                label: 'async/await',
+                guide: 'Task、ValueTask、IAsyncEnumerable、ConfigureAwait、CancellationToken',
+            },
+            {
+                id: 'linq',
+                label: 'LINQ',
+                guide: '查询表达式、方法链、延迟执行、IQueryable vs IEnumerable',
+            },
+            {
+                id: 'pattern-matching',
+                label: '模式匹配',
+                guide: 'switch expression、is pattern、property pattern、list pattern (C# 11)',
+            },
+            {
+                id: 'dependency-injection',
+                label: '依赖注入',
+                guide: 'IServiceCollection、Scoped/Transient/Singleton、IOptions<T>、Hosted Services',
+            },
+        ],
+        typicalPatterns: [
+            'async Task 方法 + CancellationToken',
+            'LINQ 方法链处理集合',
+            'record 类型 (C# 9+) 不可变数据',
+            'nullable reference types (#nullable enable)',
+            '依赖注入 (IServiceCollection / constructor injection)',
+            'switch expression 替代 if-else 链',
+            'using declaration 自动释放资源',
+        ],
+        commonAntiPatterns: [
+            { bad: 'async void 方法', why: '异常无法捕获、调用方无法 await', fix: '返回 async Task' },
+            { bad: '.Result / .Wait() 阻塞', why: '线程池饥饿 / UI 线程死锁', fix: 'await 全程异步' },
+            {
+                bad: 'IDisposable 未 Dispose',
+                why: '资源泄漏 (连接/句柄)',
+                fix: 'using statement/declaration',
+            },
+            {
+                bad: 'catch (Exception: any) { } 空处理',
+                why: '静默吞掉错误',
+                fix: '记录日志或 rethrow (throw;)',
+            },
+        ],
+        suggestedGuardRules: [
+            { pattern: 'async void', severity: 'warning', message: '避免 async void，使用 async Task' },
+            {
+                pattern: '\\.Result\\b|\\.Wait\\(',
+                severity: 'warning',
+                message: '避免同步阻塞异步方法，使用 await',
+            },
+            {
+                pattern: 'catch\\s*\\(Exception',
+                severity: 'info',
+                message: '避免宽泛 catch Exception，捕获具体异常类型',
+            },
+        ],
+        agentCautions: [
+            'async 方法返回 Task/ValueTask，不要 async void',
+            '异步代码全程 await，避免 .Result/.Wait() 死锁',
+            'IDisposable 资源使用 using statement 确保释放',
+            '启用 nullable reference types (#nullable enable)',
+            '使用 record (C# 9+) 构建不可变数据传输对象',
+        ],
+    },
+});
+// ═══════════════════════════════════════════════════════════
+// buildLanguageExtension — 公共 API
+// ═══════════════════════════════════════════════════════════
+/**
+ * 根据主语言构建语言扩展字段
+ * 包含：语言特有的分析关注点、典型模式、反模式、Guard 规则、Agent 注意事项
+ *
+ * @param {string} lang 规范化语言 ID (如 'swift', 'typescript')
+ * @returns {{ language: string, customFields: object, extraDimensions: object[], typicalPatterns: string[], commonAntiPatterns: object[], suggestedGuardRules: object[], agentCautions: string[] }}
+ */
+export function buildLanguageExtension(lang) {
+    const base = {
+        language: lang ?? 'unknown',
+        customFields: {},
+        extraDimensions: [],
+        typicalPatterns: [],
+        commonAntiPatterns: [],
+        suggestedGuardRules: [],
+        agentCautions: [],
+    };
+    // JS/TS 动态生成（有 lang-specific 差异点）
+    if (lang === 'javascript' || lang === 'typescript') {
+        const entry = _buildJsTsEntry(lang);
+        return Object.assign(base, entry);
+    }
+    // 其他语言从注册表查找
+    if (lang) {
+        const entry = LANG_REGISTRY[lang];
+        if (entry) {
+            return Object.assign(base, entry);
+        }
+    }
+    return base;
+}
+//# sourceMappingURL=LanguageExtensions.js.map