Asteroid.MetaAttributes.CompilerTools 0.6.2

Asteroid.MetaAttributes.CompilerTools

本包包含与 Asteroid.MetaAttributes 配套的分析器和源生成器。

运行时模块引用本包，并将编译工具传递给下游项目。消费者应引用运行时模块，而不是直接 选择本包。

职责

本模块是零依赖契约库 Asteroid.MetaAttributes 的配套编译工具（分析器+源生成器），拥有三组 编译期行为：

• 发现与登记：发现宿主特性上声明的约束，序列化为程序集级 HostAttributeRegistryAttribute 注册表随 IL 分发（跨程序集约束的载体）；
• 宿主约束执行：在宿主特性的使用处逐条执行约束（词汇/位置/基数见契约库设计文档）；
• 义务执行：MandatoryOn 的 absence 检测（AST0110，编译末统一）与特性实参校验 （AttributeParametersAnalyzer）。

边界

• Targets netstandard2.0 for Roslyn analyzer loading.
• 不引用运行时契约程序集（约束类型按全名字符串解析，含特殊类型/未绑定泛型两跳）。
• 模块中立的 Roslyn 基建经共享源码（CompilerTools.Shared）编入，保持 internal。
• 不包含其他框架模块的分析器/生成器；模块专用约束解析与诊断不迁往共享编译基建。

管线

约束检查有三条进入通道，汇合到同一份 ConstraintActions（宿主全名 → 使用处检查动作列表）：

1. 注册表通道（跨程序集）：PopulateFromAssemblyAttributes 扫本编译+全部引用程序集的 [assembly: HostAttributeRegistry]，反序列化约束串；MandatoryOn 前缀条目同时登记义务。
2. 源内宿主通道：PopulateFromSourceHostTypes 枚举本编译源码内的特性类型，其约束 经同一套序列化→反序列化路径入表（与注册表通道同构，防双形态漂移）。
3. 语法动作：每个 Attribute 语法节点解析特性类型→查表执行动作。

义务（AST0110）单独走两遍闭合：符号动作顺带发现（宿主类型携带 [MandatoryOn] 即登记）+ 接口收集，编译末统一检查（解决符号驱动无序问题）。

Implementors 位置在类型声明处执行（非使用处）：遍历实现接口上的宿主特性，直读其 TypeConstraint/AttributeConstraint 的 Implementors 分支，在实现者声明处报告。

NameConstraint 双通道：[NameConstraint] 同时是元特性（自检通道：携带它的宿主的使用处 直接查目标名）与注册表约束。location: Members 时自检通道让位（逐成员检查由注册表通道 独占）——否则类名会去匹配成员正则造成假阳性双报。

Members 层级的成员枚举（EnumerateConstrainedMembers，五原语与 MemberKindConstraint 共享）： 统一跳过隐式声明成员（如隐式公共无参构造器）、无种类的基建成员（属性访问器/运算符/析构器）、 仅存在于生成文件中的成员（IsCompilableFile 过滤）；pick/applyTo 收窄受检集合。 违规报告定位到成员声明处（无源码位置回退特性用法处）。

序列化格式

注册表串：约束1;约束2;...；单条：前缀|参数1|参数2|...；特殊字符 \ | ; 转义 （ConstraintsSerializer）。前缀=约束特性短名。各约束 token 布局：

类型数组以全元数据名逗号连接；可空 int 缺省为空串；可空 string 以 ~ 占位； 反序列化对尾部新增参数容错（缺失回退默认值）——历史注册表串的前缀段保持稳定。

名单单源与防漂移

MetaAttributesUtility.ConstraintNames 是约束名单唯一真源（短名=序列化前缀 ↔ 全限定名）； 语法级快筛（带/不带 Attribute 后缀双形态）、全名判定、前缀查找三个 helper 同源派生。 新增约束类型须同步三处：名单一条 + 生成器 SerializeConstraint 一个 case + 分析器 DeserializeConstraints 一个 case——三处不同步的失败是静默的（漏名→生成器不发射注册表； case 缺失或参数数不对齐→约束被跳过，均零报错）。两道防漂移测试兜底 （ConstraintNameListMatchesShippedConstraintTypes / EveryConstraintRoundTripsThroughSerialization）： 名单 ↔ 运行时程序集约束类型集合相等；逐条"序列化→反序列化"往返非空。

诊断码

（AST0049 已随 MemberAttributeConstraint 溶解退役，义务并入 AST0002。）

扩展批管线（0.3.0，2026-09-08）

• 特质求值器（MetaAttributesAnalyzer.Traits.cs）：纯符号递归判定（基元/枚举/指针直达；struct 递归实例字段；开放泛型=否保守），ConditionalWeakTable 弱缓存（keyed object 规避 RS1008）。
• NamespaceConstraint 管线：序列化与 NameConstraint 同形（名单单源第 12 条）；动作分 Self/Members/Body/BodyWrite 四路；NamespaceViolation 助手复用正则缓存源（IRegexSource）。
• Body 量化器（MetaAttributesAnalyzer.Body.cs）：AttSyntax 向上找可执行体声明（方法/构造/析构/运算符/属性与索引器/事件/字段初始化器）；引用节点=IdentifierName/GenericName/MemberAccess（成员访问限定符由整体解析去重）；签名位过滤（att 列表/参数表/基类列表/约束子句/字段声明类型；局部声明不算）；BodyWrite 只取写语境表达式（赋值左端/自增自减操作数/out-ref 实参）；同符号去重（首引用点报告）。
• ref 候选集+RefTarget（AttributeParametersAnalyzer.NameRef.cs）：存在性过滤升级为候选集解析（签名收窄）；派生 ref att（is-a RefAttribute）携带的 location=RefTarget 约束经"序列化→反序列化→动作"逐候选施加（per-编译缓存 keyed object；符号层一跳）；转发诊断须进 AttributeParametersAnalyzer.SupportedDiagnostics（Roslyn 校验报出者）；多候选未消歧=AST0061。TargetContext.Data 收窄为 IRegexSource 接口（跨分析器复用反序列化动作的最小依赖）。
• 体系自检段（MetaAttributesAnalyzer.SelfCheck.cs，挂 AnalyzeNamedType）：R1/R3'[错] AST0060、R4 空约束[警] AST0062、R5 死参数+location 无对象[警] AST0063。枚举实参装箱源内 int/元数据枚举实例两种形态统一 Convert（ReadConstraintLocation/ReadFlags/FlagArgIsNone）。
• 已知限制：CodeBuilder Quoted() 只包引号不转义——跨程序集注册表通道的正则实参忌含反斜杠与双引号（源内宿主通道不受影响）；已记 CodeBuilder 待修账。