scan-effect-solutions

Effect Solutions 合规性审计

根据 effect.solutions 的最佳实践审计代码库中的 Effect TypeScript 用法。遵循此技能，生成一致且基于证据的合规性报告。

前提条件

加载最新的 effect.solutions 建议：

effect-solutions list

加载此检查清单所用的指南：

effect-solutions show tsconfig
effect-solutions show services-and-layers
effect-solutions show data-modeling
effect-solutions show error-handling
effect-solutions show config
effect-solutions show testing

加载 effect-ts 技能，了解 Effect 专属的实现模式：

skill({ name: "effect-ts" })

---

审计清单

1. TypeScript 配置

检查 tsconfig.base.json（或 tsconfig.json）并确认：

• exactOptionalPropertyTypes: true
• strict: true
• noUnusedLocals: true
• declarationMap: true
• sourceMap: true
• 确认已配置 Effect Language Service 插件。
• 确认 module 设置符合项目类型（应用使用 preserve/bundler，库使用 NodeNext）。

参考：effect-solutions show tsconfig

2. 服务与层模式

搜索 Effect 服务并确认：

• 确认服务使用 Context.Tag 定义。
• 确认标签标识符遵循 @path/ServiceName 模式。
• 确认层使用 Layer.effect 或 Layer.sync。
• 确认在入口点只应用一次 Effect.provide。

参考：effect-solutions show services-and-layers

3. 数据建模

检查数据建模方式并确认：

• 确认记录使用 Schema.Class。
• 确认变体使用 Schema.TaggedClass。
• 确认原始值（ID、电子邮件等）使用品牌类型。
• 确认模式匹配使用 Match.valueTags。

参考：effect-solutions show data-modeling

4. 错误处理

检查错误处理方式并确认：

• 确认领域错误使用 Schema.TaggedError。
• 确认在适当情况下使用 catchTag/catchTags 恢复错误。
• 确认有意区分缺陷和类型化错误。

参考：effect-solutions show error-handling

5. 配置

检查配置模式并确认：

• 确认使用 Schema.Config 进行验证。
• 确认存在配置服务层模式。
• 确认机密使用 Config.redacted。

参考：effect-solutions show config

6. 测试

检查测试并确认：

• 确认测试使用 @effect/vitest。
• 确认 Effect 测试使用 it.effect()。
• 确认测试层组合遵循 Effect 层模式。

参考：effect-solutions show testing

7. 运行时执行反模式（应用代码中的 Effect.runPromise / Effect.runSync）

搜索应用代码中直接使用 Effect.runPromise 和 Effect.runSync 的情况。排除仅用于测试的文件和测试辅助文件（__tests__/、*.test.ts、*.spec.ts、fixture 目录）。

如果裸用 Effect.runPromise / Effect.runSync 绕过了项目运行时组合，则将其视为问题。裸执行通常会使用默认运行时，而不会注入项目提供的层（例如用于追踪、配置、日志记录或领域服务的层）。

根据项目情况进行评估：

• 应用代码优先使用项目的运行时入口点（例如 runtime.runPromise）。
• 如果无法使用运行时（例如在引导阶段或存在依赖循环约束时），可以接受显式提供层。
• 豁免有意提供专用测试层的测试。

Template-ts 惯例示例（仅在受审计代码库适用时使用）：

• effect-runtime.ts 中的 ManagedRuntime
• AppLayer 组合
• 由运行时提供的可观测性中的 SentryTracingLive

搜索模式：

• 在应用源代码目录下搜索 Effect.runPromise(（例如 src/、apps/*/src/、packages/*/src/）
• 在应用源代码目录下搜索 Effect.runSync(（范围相同）

报告每个匹配项，并包含：

• 文件路径和行号
• 是否使用 runtime.runPromise（✅）或裸用 Effect.runPromise（❌）
• 必需的可观测性/配置层是否由运行时提供，或通过显式 Effect.provide 作为回退方案提供

参考：effect-solutions show services-and-layers

8. Option/Either 内部标签反模式

检查应用代码和测试中对 Option/Either 的直接 _tag 分支判断。

• 生产代码：将所有直接使用 _tag 的情况报告为问题，并给出替换建议
• 测试：允许使用 _tag 断言领域错误的身份，但应指出应改用辅助函数的控制流分支模式
• 优先使用：
  • Either.match、Either.isLeft、Either.isRight
  • Option.match、Option.isSome、Option.isNone、Option.getOrElse

应包含的搜索模式：

• if (.*\._tag === "Left")
• if (.*\._tag === "Right")
• if (.*\._tag === "Some")
• if (.*\._tag === "None")
• expect\(.*\._tag\)

参考：effect-solutions show error-handling

---

输出格式

请提供一份结构化报告，包含：

1. 摘要：根据以下评分标准给出总体合规分数。

   评分标准（总分 0-16）：

   • 按 0-2 分评估每个检查清单章节（1-8）。
   • 2：完全合规或仅有轻微的格式问题。
   • 1：部分合规，存在较明显的缺漏。
   • 0：不合规或缺少相关模式。
   • 总分 = 所有章节分数之和。
   • 给出百分比 = (总分 / 16) * 100，四舍五入到整数。

2. 做得好的方面：列出符合最佳实践的模式

3. 需要改进的方面：列出具体问题，包括：

   • 文件位置
   • 当前模式
   • 建议模式
   • 优先级（高/中/低）
   • 范围标签：production 或 test

4. 快速修复：列出可立即完成的简单修复

5. 后续步骤：按建议的顺序列出改进事项

---

相关技能

• effect-ts — Effect 服务、层、错误处理、配置模式
• testing-patterns — Vitest 和 @effect/vitest 测试模式
• code-review — 通用代码审查方法（包含 Effect 部分）