Rust source quality

Rust source quality 指把 Rust 源码的可读性、结构边界和 lint 可执行性写成可重复运行的 contract。它至少区分格式化、语义 lint、源码结构检查和 target/features coverage，并把每一层绑定到仓库内可运行的命令、配置或 checker，而不是把“能编译”当成质量结论（projects/flux-purr.md、data/topics/rust-source-quality.json）。

这个 Topic 关注源码质量的执行面：crate 如何配置 Clippy、入口文件如何保持可审阅、结构性豁免如何受控、以及 target-only 分支怎样被覆盖。它不规定所有 Rust 项目采用同一阈值、同一 target、同一零债务政策或同一 CI 编排；这些都是项目本地 contract，需要以仓库证据为准。

当项目新建 Rust crate、引入 Rust 作为新的实现面、建立或重构 lint contract，或一次 Rust 重构需要把格式、Clippy、source-shape 和 target coverage 变成长期可执行的门禁时使用。对已经存在 Rust 代码但只有编译检查、没有可复盘的结构或 lint 约定的项目，也可用本 Topic 建立最小 source-quality contract。

命中信号包括 rustfmt 检查、crate-local clippy.toml、严格 Clippy 脚本、syn/AST source checker、结构性 lint suppression 审计，或 target/features matrix 的 lint 命令。Rust crate release、Rust workspace layout 和“哪些 check 必须通过才能合并”的 required-check policy 应分别路由到对应 Topic；本 Topic 可以被它们并列消费，但不替代它们。

• 先定义四层 contract：格式、语义 lint、源码结构、target/features coverage；每层都应有 checked-in 配置或脚本和清晰失败语义。
• 以 crate-local 配置保存函数行数、参数数量、嵌套深度等阈值。阈值应服务于职责边界和可维护性，不应被抄成所有项目的固定数字；不需要某个阈值时，记录理由并保持可审计。
• rustfmt 是格式工具，不是模块设计工具。入口文件应只保留启动、装配或 re-export，领域实现和测试按职责进入命名模块；不设没有证据支持的全仓文件长度阈值。
• -D warnings 与选定的 Clippy size/complexity lints 应在本地入口和 CI 入口一致。对 embedded 或 feature-gated crate，host lint 与 target lint 都运行时才算覆盖完整。
• source-shape checker 适合补足编译器和 Clippy 不表达的边界，例如 inline test、入口预算、嵌套 cfg_attr 中的结构性 suppression。checker 自身也应通过同一套严格 lint。
• 豁免要窄且可解释。外部 trait、ABI 或生成代码可能需要原生 Clippy 例外，但结构性 allow/expect 不应成为积累债务的默认入口；项目是否实行零债务由本地证据决定。

• Workspace：先明确哪些 crate 共享 lint contract，哪些 crate 有独立 target、生成代码或发布责任；workspace-wide cargo clippy 不能代替 crate-specific matrix。
• Application：关注入口、用户可见错误路径和测试模块的可读性；source-quality gate 应服务于可调试交付，不应只追求 lint 数量。
• Service：把 handler、协议边界和错误转换拆成可 lint 的职责单元；服务运行时检查和 API contract 仍属于相邻 Topic。
• CLI / utility：入口通常较窄，但参数解析、I/O 和报告输出容易聚集；使用结构检查帮助保持命令入口可审阅，同时避免把业务特有的参数数量直接硬编码成通用规则。
• Embedded：必须区分 host-preview 与实际 target。target-only code 需要在真实 target 和 release feature matrix 上运行 Clippy；硬件操作、HIL 和设备验收不属于本 Topic 的默认范围。

• projects/flux-purr.md：firmware、devd 和 source checker 共同形成四层 Rust source-quality contract；100/7/4、零结构债务、Xtensa matrix 和 syn checker 都明确保留在项目边界内。
• docs/solutions/engineering/rust-style-debt-remediation.md：说明为什么入口拆分、crate-local thresholds、target-aware Clippy 和 source-shape checker 需要组合使用，并列出不应采用的结构性绕过。
• docs/guides/flux-purr-developer-policy.md：列出开发者实际运行入口，说明 fmt、host/target Clippy、checker 与非硬件验证的顺序关系。

• 不把 Flux Purr 的设备 target、feature 名称、100/7/4 阈值或零结构债务政策复制为跨项目硬规则。
• 不以 rustfmt 通过证明模块边界良好，不以 host Clippy 通过证明 target-only 分支已覆盖，也不以一次 workspace 命令代替不同 crate 的本地 contract。
• 不设置没有 source evidence 的全仓文件长度门槛；应按职责边界拆分，并让函数/参数/嵌套规则保持在 crate-local 配置。
• 不用 crate-wide、module-wide、file-wide 或 function-level 结构性 allow/expect 隐藏 debt；需要接口兼容例外时，记录最窄范围和原因，并排除三项结构性 lint。
• 不把 mock smoke、编译成功或 checker 通过描述成真实设备/HIL 验收；设备操作和 release policy 交给相邻 Topic 与项目文档。
• Topic 建议只负责选择和组合检查层；具体命令、target、feature matrix、阈值和 waiver 入口必须由目标项目的 checked-in 配置决定。

• 只有 cargo fmt 或普通 cargo check，没有语义 lint 和结构检查，导致入口膨胀、复杂度回归或 suppression 债务悄悄回归。
• 只运行 host Clippy，遗漏 embedded target-only 分支；或者 target 命令与 release 使用的 target/features 不一致，造成错误的绿灯。
• 把一个项目的阈值和 zero-debt baseline 复制到所有 Rust 项目，误把参考 profile 变成没有上下文的政策。
• 依赖宏、include! 或生成 wrapper 隐藏函数体和控制流，使 checker 与 Clippy 无法衡量真实职责边界。
• 把 required checks、crate 发布流程或 workspace 拆分问题全部塞进本 Topic，导致 delivery、release 和 project-init 路由边界失真。
• 让 checker 自己不受同一 lint contract 约束，结果质量工具成为最容易绕过的例外。

• projects/flux-purr.md
• data/topics/rust-source-quality.json
• docs/solutions/engineering/rust-style-debt-remediation.md
• docs/guides/flux-purr-developer-policy.md
• Clippy lint documentation
• Rustfmt repository