nestjs-code-audit

用途

nestjs-code-audit 用于对现有的 NestJS 仓库执行只读代码审计，返回一份整合后的报告，列出经过验证的代码问题和有证据支撑的风险。该技能只做审计，不修改目标项目。

主要能力

该技能拥有只读质量证据、发现去重、严重性分级和报告组装的主要职责。在已安装且相关时，可与以下技能协调：nestjs-architecture-principles（模块、依赖、数据与事务边界）、nestjs-oop-design-patterns（对象职责、不变量与模式）、nestjs-features-performance（生命周期、API/安全、测试、运行时与性能）、nestjs-professional-software-engineering（实现与验证）、nestjs-feature-audit（分支特定路线图门禁与功能报告）、nestjs-git-commit-pr-message（授权的 Git 发布与 CI 跟进）。这些是决策边界，不是必需依赖。

使用方式

首选的可移植调用方式：

$nestjs-code-audit
$nestjs-code-audit full src/payments
$nestjs-code-audit static
$nestjs-code-audit security src/auth

Codex CLI/IDE 自定义提示别名（安装后）：

/prompts:nestjs-audit
/prompts:nestjs-audit full src/payments

Codex 不提供任意裸用户自定义命令（如 /Nestjs audit），需保持支持的别名明确。

审计动作包括：full（默认，安全静态门禁加架构、对象设计、运行时、安全、测试与交付审查）、static（语法、TypeScript、lint、配置及直接相关的工具链故障）、architecture（模块、依赖、数据/写入所有权、事务、事件、端口与服务边界）、design（职责、不变量、耦合、抽象、模式与重构风险）、runtime（Nest 生命周期、API/错误、可靠性、性能证据、健康、关闭与交付）、security（输入、身份/访问、租户隔离、密钥、输出、滥用控制与安全测试）、tests（测试层选择、缺失的边界覆盖、易碎生命周期风险与可安全运行的检查）。动作后可跟可选的仓库相对范围。若第一个参数不是可识别的动作，则将所有参数视为范围/焦点并使用 full。

审计工作流

确定资格与范围：解析当前工作目录和可选用户范围，不逃逸仓库根目录；读取 AGENTS.md 及其他仓库说明、package.json、锁文件、nest-cli.json、TypeScript 与 lint 配置、引导文件、模块文件、测试及影响范围的部署清单；验证 @nestjs/core 已声明或仓库明确是 NestJS 工作区，否则停止并报告不适用；记录当前分支和脏状态，不改变或丢弃现有更改；用一句话陈述观察到的架构基线，不根据文件夹名称推断 Clean Architecture、DDD、CQRS 或微服务。
收集确定性证据：使用该技能目录中的内置收集器：

node scripts/collect-quality-evidence.mjs --root "$PWD" --run

当用户要求更窄的审计时添加 --scope <relative-path>。收集器读取清单和源文件而不更改它们；识别包管理器和可用的质量脚本；仅在存在 --run 时运行允许列表中的、非修复性的 ESLint 和 tsc --noEmit 命令；从不安装依赖、运行构建、更新快照、写入覆盖率或调用任意包脚本；返回包含命令结果和启发式审查候选的 JSON。如果依赖缺失或命令不安全、不可用、超时或超出范围，记录为未运行。不要将缺失的检查重新解释为通过。审计期间绝不运行 lint --fix、格式化/写入命令、迁移、部署命令、实时集成测试或可能触及共享基础设施的测试。

审查四条证据通道：工具链正确性（报告解析器、TypeScript 和 lint 诊断，足够精确定位问题；当级联编译器错误共享一个根因时去重；将命令失败与代码发现分开，如缺失依赖或配置损坏）；架构（追踪引导入口点、模块导入/导出、提供者可见性、请求/消息路径、持久化所有权、事务、事件与外部适配器；从真实导入和调用路径确认循环或边界泄漏；不将架构偏好报告为缺陷）；对象设计与可维护性（检查职责、依赖集群、不变量放置、重复条件变化、框架/供应商泄漏、隐藏服务定位、推测性抽象与风险重构接缝；文件长度或正则信号本身不是发现）；运行时、安全与验证（检查生命周期放置、验证、认证/授权、租户/资源所有权、公共错误与响应契约、密钥/日志、查询与资源边界、超时/重试/幂等性、健康/关闭、测试边界与部署证据；没有测量不声称性能问题）。
验证并去重发现：已确认的发现需要稳定的 ID（TOOL、ARCH、OOP、RUN、SEC 或 TEST 加数字）、严重性（critical、high、medium 或 low）、主要拥有技能、文件与行证据及相关导入、调用路径、诊断或配置、具体影响（不仅是规则名称）、最小安全补救措施、可证明补救的验证步骤。critical 仅用于当前存在的安全、数据丢失、租户隔离或严重可用性风险。high 需要可能的不正确行为或阻碍已知更改的边界缺陷。medium 需要可信的可维护性、正确性或可操作性成本。low 是风险有限的局部改进。将未验证的正则信号、疑似死代码、可能的性能问题和因缺失依赖而受阻的检查移至 Needs verification。不要用风格偏好或一个根因的多个发现来膨胀报告。

必需报告

按以下顺序返回 Markdown：审计结论（pass、pass with risks 或 fail；审计范围；一句话基线）；质量门禁（语法/TypeScript、lint、测试（如可安全运行）和审计覆盖，每项标记为 pass、fail 或 not run，并附确切命令或原因）；发现摘要（按严重性和拥有者计数）；已确认发现（按严重性和影响排序，使用上述证据/补救/验证契约）；待验证（候选、缺失证据和最小下一步检查）；健康模式（仅列出仓库中实际验证的显著控制）；建议顺序（简短的、依赖感知的补救序列；仅在用户明确授权这些修复时在单独阶段实施）。如果没有已确认问题，说明并列出未运行的检查。干净的 lint 结果不是架构、安全、运行时行为或测试覆盖健全的证明。

适用场景

适用于需要审查现有 NestJS 仓库代码质量、架构、安全性、运行时行为或测试覆盖的场景，尤其适合在变更前建立质量基线、识别风险或为后续修复提供依据。

限制

该技能仅执行只读审计，不修改目标项目。审计本身从不授权修复；如果用户明确要求两者，先完成只读审计，然后进入授权的实施阶段，无需再次请求相同批准。不安装依赖、不运行构建、不更新快照、不写入覆盖率、不调用任意包脚本。不运行 lint --fix、格式化/写入命令、迁移、部署命令、实时集成测试或可能触及共享基础设施的测试。没有测量不声称性能问题。不根据文件夹名称推断架构风格。