convex-launch-readiness

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Launch-readiness report

上线就绪报告

Readiness is not one check — it's the union of the checks, deduped, ranked, and scored. This capability is pure composition over the findings bus (specs/finding.schema.json): it runs each audit capability, normalizes their outputs into one report (specs/finding-report.schema.json), computes an auditable score, and — because every finding names a fixCapability — hands the user a prioritized, actionable punch list instead of four separate reports. It fixes nothing itself; it decides WHAT to fix and in what order, then dispatches to the fixers.

就绪状态并非单一检查项，而是多项检查的集合，经过去重、排序和评分后得出的结果。该功能完全基于发现总线（specs/finding.schema.json）进行组合：它会运行每一项审计功能，将输出标准化为一份报告（specs/finding-report.schema.json），计算可审计的评分，并且——由于每一项发现都会指定对应的fixCapability——为用户提供一份优先级明确、可执行的任务清单，而非四份独立的报告。它本身不执行任何修复操作，而是决定需要修复什么以及修复顺序，然后将任务分派给修复工具。

Workflow

工作流程

GUARD + SCOPE: deploy-guard classifies the target (local-anonymous / dev / preview / prod); announce it. Detect what's assessable — is there a convex/ dir, a deployed deployment with traffic, an auth foundation? Skip passes whose preconditions aren't met and SAY which were skipped (a skipped pass is not a pass).
RUN THE PASSES, each emitting findings on the bus:
- convex-authz — the authz scan (identity-from-arg, missing ownership, PII leak, parent-ref-on-write). Always runnable on code.
- convex-reviewer — validators, indexes-not-filter, idiom, error handling. Always runnable on code.
- convex-advisor — live read-limit / OCC evidence (only if a deployment with traffic exists; else record 'skipped: no traffic').
- convex-insights — recent failures from logs (only if a deployment exists). Run independent passes concurrently; each returns findings, not fixes.
NORMALIZE + DEDUPE: collect all findings into one report. Set each finding's
```
identity
```
field to a normalized function/table key (e.g.
```
messages:list
```
) that is the SAME whether the pass reported a code-locus or a deployment-locus for that function — so the SAME defect seen from two loci (reviewer flags a missing index at code-locus, advisor flags its read-limit symptom at deployment-locus) collapses to ONE via the bus's (class, identity) dedup and isn't double-counted in the score. Keep the higher-confidence source. Drop nothing silently; a pass that errored/was skipped is a stated coverage gap, not a clean result.
SCORE, auditable: start at 100; subtract per CONFIRMED finding by severity (high −15, med −5, low −1), floor at 0; print the exact formula and the per-class breakdown so the number is reproducible, not a vibe. plausible-only findings are listed as candidates but do NOT move the score (evidence-not-vibes). A deployment/traffic-less run reports a code-only score and says so.
REPORT: the score, then findings ranked by severity, each with its evidence, its locus, and the fixCapability + a one-line fix note. Group by 'blockers' (high) / 'should-fix' (med) / 'nice-to-have' (low). End with the ordered fix plan: which capability to run next, in what order (authz/data-loss first, then perf/scale, then idiom/observability).
DISPATCH on request: for each finding the user accepts, invoke its fixCapability (convex-authz, convex-reviewer's fixers, migrate-rehearse for schema changes, suggest for component swaps). After fixes, RE-RUN the affected passes and show the score delta — the readiness number is only meaningful if it moves when you fix things.
Never claim more coverage than was run: the report header lists which passes ran, which were skipped and why. A green score on a code-only run is 'code looks ready', not 'production-verified'.

防护与范围界定：deploy-guard对目标环境进行分类（local-anonymous / dev / preview / prod）并告知用户。检测可评估的内容——是否存在convex/目录、有流量的已部署实例、权限基础架构？跳过不满足前置条件的检查项，并说明跳过的原因（跳过不等于通过）。
运行各项检查，每项检查都会在总线上输出发现结果：
- convex-authz——权限控制扫描（参数身份识别、缺失所有权、PII泄露、写入时父引用问题）。始终可针对代码运行。
- convex-reviewer——验证器、未过滤索引、编码规范、错误处理。始终可针对代码运行。
- convex-advisor——实时读取限制/OCC证据（仅当存在有流量的部署实例时运行；否则记录“已跳过：无流量”）。
- convex-insights——日志中的近期失败记录（仅当存在部署实例时运行）。并行运行独立的检查项；每项仅返回发现结果，不执行修复。
标准化与去重：将所有发现结果整合到一份报告中。为每个发现的
```
identity
```
字段设置为标准化的函数/表键（例如
```
messages:list
```
），无论检查项报告的是代码位置还是部署位置，该键保持一致——这样，同一缺陷从两个位置被发现（reviewer在代码位置标记缺失索引，advisor在部署位置标记其读取限制症状）时，会通过总线的（类别，身份）规则合并为一项，不会在评分中重复计算。保留可信度更高的来源。不静默丢弃任何内容；检查项出错或被跳过都会明确列为覆盖缺口，而非无问题结果。
可审计评分：初始分为100分；根据已确认发现结果的严重程度扣分（高严重度扣15分，中严重度扣5分，低严重度扣1分），最低分为0；打印精确的计算公式和按类别划分的明细，确保分数可重现，而非主观判断。仅为疑似的发现结果会列为候选，但不会影响分数（基于证据而非主观感受）。无部署/无流量的运行会报告仅基于代码的评分，并明确说明。
生成报告：先展示评分，然后按严重度排序展示发现结果，每个结果包含证据、位置、对应的fixCapability以及一行修复说明。按“阻塞项”（高严重度）/“应修复项”（中严重度）/“优化项”（低严重度）分组。最后给出有序修复计划：下一步应运行哪些功能，以及顺序（先修复权限控制/数据丢失问题，然后是性能/扩展问题，最后是编码规范/可观测性问题）。
按需分派：针对用户确认的每一项发现，调用对应的fixCapability（convex-authz、convex-reviewer的修复工具、用于架构变更的migrate-rehearse、用于组件替换的suggest）。修复完成后，重新运行受影响的检查项并展示评分变化——只有在修复后分数发生变化，就绪状态数值才有意义。
绝不夸大覆盖范围：报告头部会列出已运行的检查项、被跳过的检查项及原因。仅基于代码运行得出的高分表示“代码看起来已就绪”，而非“已通过生产环境验证”。

Rules

规则

Compose, don't re-implement: run the existing audit capabilities and aggregate their bus findings — never re-derive an authz or perf check inline.
The score counts CONFIRMED findings only, by severity, with the formula printed; plausible findings are candidates that don't move the number.
Normalize each finding's locus to a function/table identity before dedup (map deployment functionId ↔ code file:line) so one defect seen from two loci collapses to one and isn't double-scored; keep the higher-confidence source; drop nothing silently.
Every finding carries its fixCapability; the report ends with an ORDERED fix plan (data-loss/authz first, then scale, then idiom/observability).
Re-run affected passes after fixes and show the score delta — a readiness number that doesn't move when you fix things is theater.
Never claim more than was run: header lists ran/skipped passes; a code-only run yields a code-only score, explicitly labeled.
This is a read + aggregate + dispatch pass; fixes happen in the fixer capabilities, gated by their own consent/deploy-target rules.

组合而非重实现：运行现有的审计功能并汇总总线发现结果——绝不内联重新实现权限控制或性能检查。
评分仅计算已确认的发现结果，按严重度扣分，并打印计算公式；疑似发现结果仅作为候选，不影响分数。
在去重前将每个发现的位置标准化为函数/表身份（映射部署functionId ↔ 代码文件:行），确保同一缺陷从两个位置被发现时合并为一项，不会重复扣分；保留可信度更高的来源；不静默丢弃任何内容。
每一项发现都附带对应的fixCapability；报告末尾给出有序修复计划（先处理数据丢失/权限控制问题，然后是扩展问题，最后是编码规范/可观测性问题）。
修复完成后重新运行受影响的检查项并展示评分变化——修复后分数不变的就绪状态数值毫无意义。
绝不夸大已运行的检查范围：头部列出已运行/已跳过的检查项；仅基于代码的运行会生成仅基于代码的评分，并明确标注。
这是一个读取、汇总、分派的检查项；修复操作在修复工具功能中执行，受其自身的授权/部署目标规则限制。