← 官方规则来源
Capnp · 官方规则原文
OpenCodeReview v1.13.8 · 4236c871 · Apache-2.0。保留固定版本英文原文;item 编号表示原文件中的检查项顺序。实际扫描以当前规则开关和扫描快照为准。
查看当前规则与开关 → · 下载原始 Markdown
版本与文件信息
提交:4236c871fe8130aa840a2a1c0922f469e87e0416
源码路径:internal/config/rules/rule_docs/capnp.md
SHA-256:31bd6e7319d85e5f3b15212cb41825b631e0806d9e8c0790a5183c361393b386
Apache-2.0 许可证 ·
基线说明Favor precision over recall: only raise an issue when you are confident it is a real defect, and stay silent when the surrounding context is unclear — a false alarm costs more reviewer trust than a missed minor issue. Treat wire-compatibility breaks as blocking, and naming or layout preferences as non-blocking.
Ordinals and Wire Compatibility
- Changing the
@N ordinal of an existing field or method; the ordinal is that member's fixed slot, so it is the one thing that must never move - Filling an ordinal left behind by a removed member instead of holding it with an
obsolete/obsoleteN placeholder of the original width (obsoleteSave @7 :AnyPointer, obsolete3 @3 :Bool) - Deleting a member outright rather than renaming it to
obsolete* and leaving its ordinal and type in place - Adding a member at an ordinal already used elsewhere in the same struct, union, or interface
- Do not report a rename that leaves the ordinal alone; names are not on the wire, so renaming is free
- Do not report declaration order that disagrees with ordinal order, which is legal and common (
rpc.capnp declares disembargo @13 above obsoleteSave @7)
Types and Defaults
- Widening a fixed-width field, such as
UInt32 to UInt64 or Float32 to Float64: slots are fixed-width at fixed offsets, so this is a break, unlike widening a protobuf varint - Any other change to an existing field's type, including a signedness flip or swapping an enum for the integer that backs it
- Changing the default value of an existing field; Cap'n Proto encodes values XOR the default, so the same bytes decode differently on either side of the change
Text used to carry arbitrary bytes where Data is meant, since Text asserts NUL-terminated UTF-8 and readers may validate it- Do not report a field appended at the next unused ordinal, which is backward compatible
Unions, Groups, and Type IDs
- Moving an existing field into or out of a union or group, with one legal exception: wrapping an existing field in a brand-new union where it is the first member
- A union whose lowest ordinal is not a
Void sentinel, leaving no representable "unset" state - Adding a member to an existing union without confirming readers handle an unknown discriminant; older code sees a value outside the enum it was compiled against
- Renaming a struct, interface, or file with no explicit
@0x... id pinned: the id is derived from the name, so the rename silently changes it and breaks anything holding the old one - Do not report an explicit
@0x... id carried through a rename; that is the fix, not the defect
Interfaces and Methods
- Renumbering an existing method, or reusing the ordinal of one that was removed
- Changing an existing method's parameter or result struct in any way the field rules above forbid
- Removing a method rather than renaming it to
obsolete* and keeping the ordinal (sandstorm keeps obsoleteHttpGet @1 and obsoleteGetGrainSize @3) - Capabilities returned with no documented lifetime, where dropping the client silently cancels work still in progress
- Do not report a method rename that keeps its ordinal
Security and Resource Limits
AnyPointer accepted from untrusted input and cast without a type check- Unbounded
List, Text, or Data from untrusted input with no traversal limit or nesting limit set on the reader - Secrets, tokens, or credentials embedded in constants, defaults, or comments
- Do not report when reader limits are set at the call site and that boundary is clearly documented