这个项目能做什么

AI Shipcheck 是一个本地优先的生产就绪扫描器，面向主要由 AI 编码工具编写的应用。它的前提是：AI 助手擅长产出能运行的代码，却不擅长产出能经受生产考验的代码，而无论哪种情况它们都会报告工作已完成。Shipcheck 寻找那些反复出现、枯燥乏味的缺口——没有行级安全性的 Supabase 表、写入前不检查调用方的路由处理器、存放密钥的 NEXT_PUBLIC_ 变量、没有速率限制或 token 上限的 LLM 端点。 使用只需一条命令： npx ai-shipcheck . 无需注册、无需 API 密钥、无需上传源码。它要求 Node.js 22 或更高版本。选项包括 --fail-on（例如 critical）、--min-score、--format（json、markdown、sarif），以及一个 explain 子命令，用于说明某条规则为何存在以及如何修复。仅凭发现的问题绝不会导致命令失败；阈值是选择性启用的，因此将其加入现有流水线是可逆的。退出码区分达到阈值、未达到阈值、用法错误和内部错误。 检查内容 九个类别独立评分，由 63 条规则支撑，每条规则都配有文档、一个存在漏洞的夹具、一个安全的夹具和测试： - 安全：硬编码凭据、藏在 NEXT_PUBLIC_ 后面的密钥、eval、shell 注入、开放重定向、宽松的 CORS、禁用 TLS 验证、弱加密。 - 认证：写入路由缺少授权检查、未认证的服务器操作、仅浏览器端的权限检查、未验证的 webhook、未签名的 JWT、暴露的 service-role 密钥。 - 数据库：没有行级安全性的表、USING (true) 策略、通过插值构建的 SQL、未加过滤的删除、破坏性迁移。 - 可靠性：被吞掉的错误、请求路径中缺少超时、未处理的 rejection、没有退避的重试、忽略类型错误的构建。 - 测试：没有测试、CI 缺少 test/build/typecheck、提交了 .only、服务器代码没有引用它的测试。 - 可观测性：没有错误监控、仅用 console 的服务器日志、没有 React 错误边界。 - 性能：无界查询、处理器中的同步 I/O、N+1 形态、沉重的客户端导入。 - 无障碍：缺少 alt 文本、非交互元素上的点击处理器、未加标签的表单控件、正的 tabIndex。 - AI 成本：没有认证或速率限制的 LLM 端点、没有 token 上限、由请求控制模型选择、浏览器中的提供商密钥。 可检测的技术栈包括 Next.js（两种路由）、React、Vite、Express、Fastify、Hono、NestJS、Remix、Astro、SvelteKit、Nuxt、Supabase、Firebase、Prisma、Drizzle、Mongoose、Stripe、OpenAI、Anthropic、Vercel AI SDK、LangChain、tRPC 以及常见测试运行器。框架专属规则仅在检测到该框架时运行，monorepo 也不例外。 输出与集成 报告显示分数、结论、各类别条形图，以及带有文件、行号、规则、严重性和置信度的发现项。阻断项会强制判定为 NOT READY，无论分数如何。无法评估的类别会被排除，而不是白送 100 分。GitHub Action 会在 diff 上内联标注发现项，将 Markdown 报告写入作业摘要，生成用于代码扫描的 SARIF，并输出 score、verdict、critical-count 和 high-count；它被打包为单个已提交文件，因此固定到某个 tag 的工作流运行的正是那份代码。 信任与范围 该工具不进行网络调用，不发送遥测数据；被扫描仓库中的任何内容都不会被执行——文件按字节读取并以词法方式分析。密钥在任何可能被打印的地方都会被遮蔽，扫描有边界，并在被截断时明确说明，且只有一个运行时依赖。 声明的局限性是明确的：仅支持 JavaScript 和 TypeScript；分析是词法而非语义的，没有跨文件推理或类型信息，污点跟踪只跟随值一跳，因此它不认识的定制认证包装器可能产生误报。Express 和 Fastify 路由不在认证规则覆盖范围内，被称为已知的最大缺口。基础设施对它不可见，因此一个在仪表盘中启用了 RLS 但迁移中缺失的表会被报告为未评估，而非安全。一份干净的报告意味着它所知道的检查没有发现任何问题，而不是代码正确。 这些规则已针对 20 个按 commit SHA 固定的公共仓库进行验证；据称，对其输出进行分诊后，发现项从 5,710 个减少到 2,819 个，并暴露出一个影响多行注释文件中行号的词法分析器 bug。文档涵盖规则、CLI 契约、配置、评分、信任模型、局限性、威胁模型、架构、添加规则、发布和治理。采用 MIT 许可。