fix(lint): 字段公式校验读回声明的 expression —— 激活一条从未跑过的检查 (#5026)

[xuyushun441-sys]

Fixes #5026

这一单和 #4984 / #5009 / #5017 的差别

同族的前三轮都是删死代码:别名 limb 在链里,canonical limb 也在,删掉别名对任何能解析的 stack 零行为变化。这一条不是。

validate-expressions.ts 的字段公式校验读 f.formula,而 FieldSchema 声明的是 expression —— formula 恰恰是 field.zod.ts:333 按名拒绝的别名:

aliases: { formula: 'expression', calculation: 'expression', compute: 'expression' }

规则以 input: 'parsed' 注册(authoring-rules.ts),compile/build/validate 路径上它看到的是 ObjectStackSchema 的解析产物,所以 f.formula 恒为 undefined。代码里根本没有 f.expression 的读法。结论:整段检查对任何 spec 合法 stack 从未执行过一次。

所以把读法收敛为 f.expression 是启用一条从未跑过的检查,是覆盖面扩大 —— 不是删死代码。这也是它没跟着 #5017 顺手带上、而是单独一单的原因。

真实元数据实测:零新红

激活是覆盖面扩大,可能对现有元数据判红 —— 那是本单的目的而非事故,所以逐条跑过、逐条定性。用激活后的规则在全部真实元数据上实测(先 ObjectStackSchema.safeParse,再喂 validateStackExpressions,和 compile 路径完全一致):

元数据	解析	本次激活新访问的 expression 槽	新判决
examples/app-showcase	✅	3	0
examples/app-crm	✅	5	0
examples/app-todo	✅	0	0
packages/platform-objects	—	0(无公式字段)	0
plugin-security default-permission-sets	—	0(无公式字段)	0
skills/ 公式样例(3 处)	—	3	0(已是 canonical)

八个真实公式槽全部判绿。这不是"门没开"——反向验证里坏 expression 确实判红(见下),所以绿是判别的结果,不是不可达的结果。

顺带扫到的两处裸引用样例在文档/博客里(content/docs/data-modeling/fields.mdx:230 的 'quantity * price * …'、content/blog/context-window-is-the-constraint.mdx:108 的 cel`amount * probability`),两条都实测判红。它们是 markdown 散文、不在本规则的消费半径内,按 Prime Directive #10 另开 #5116 记账,没有在本 PR 里改(本 PR 限于 packages/lint)。

双向证明

新增 validateStackExpressions — the field-formula check now actually runs (#5026),四条,全部执行而非描述:

1. spec 合法 stack 上坏 expression 判红且点名 —— unknown field 'no_such_field',定位到 field 'expected_revenue' expression;1b 语法坏的同样判红;
2. 正确的 expression 判绿 —— 门会判别,不是一律亮;
3. formula: 拼法交给 schema 按名拒绝(Did you mean 'formula' → 'expression'?),本规则不再对同一个键给第二套说法;
4. 变异:把源码里的读法改回 f.formula,fix(lint): 收敛 validate-expressions / validate-security-posture 的 spec 不声明键 ?? 别名读法 (#5017) #5046 的 declared-key meta-guard 用同一段 source scan 判红并点名 formula —— 接住了,已验证。

另有 reachability 一条:fields[].expression 的判决从一个真正 ObjectStackSchema.parse 过的 stack 上产生 —— 这句话在本 PR 之前从来不成立。

TRACKED_UNDECLARED_READS 清账

那份"只缩不长"的清单唯一一条就是 { receiver: 'f', key: 'formula', issue: 5026 }。本单清空到 0:规则读的每一个键都是 spec 声明的键。断言从"恰好等于这一条 debt"改成 toEqual([]),再加一条独立断言把"清单为空"钉住,任何新增条目都成为一次刻意行为。

消费半径扫描(#5046 返工的教训)

全仓 grep formula: 作字段谓词键的测试 fixture:

• packages/lint/src/validate-expressions.test.ts 7 处 → 全部换 canonical expression:(185 / 214 / 234 / 255 / 329 / 348 / 1171);
• 同文件 1485 处是 validation rule 的 formula → condition 别名 fixture,是刻意判红的对象,不属本单面,保留;
• packages/cli/test/authoring-rule-command-parity.test.ts 的 expression-invalid 用例写的是 condition:(validate-expressions / validate-security-posture 也有同形的 spec 不声明键的 ?? 别名读法(#5009 建议 3 的核对结果) #5017 已修过),不涉字段公式,无需改;cli 全量测试已跑绿(68 files / 600 tests);
• #5096 playbook 点名的 validate-rule-compilability.test.ts:295 —— 该文件 grep formula 零命中,与本单面不重叠,留给 validate-rule-compilability.ts:239 也有同形的 obj.validations ?? obj.validationRules 别名读法(#5017 全包 grep 的第八处,第三个文件) #5096;
• driver-sql / driver-sqlite-wasm / objectql 等包里的 expression fixture 是 DDL / 引擎测试,不经过本规则,不在半径内。

其他改动

• 诊断定位串 … field 'Y' formula → … field 'Y' expression。理由写在代码注释里:说 "formula" 正是错拼法的传播路径 —— 下一位作者读了诊断就去写 formula:,然后被 schema 拒。消息要点名作者要改的那个键。
• validate-null-guards.ts 的 surface ledger 把该行从 Field.formula 正名为 field expression(Field.formula({ expression: … }) 写入的槽),并写明:排除的只是 null-guard 这一条判决(公式是 value 角色、天然可空,guard ? value : null 是祝福写法),语法 / 字段存在性 / 裸引用判决从此生效。对应的那条测试也补了注释 —— 它现在零 issue 是"gate 确实被排除",而不是过去的"surface 压根不可达"。
• changeset:@objectstack/lint minor。

验证

pnpm --filter @objectstack/lint test       →  57 files / 1169 tests passed
pnpm --filter @objectstack/lint typecheck  →  tsc --noEmit, clean
eslint (三个改动文件)                       →  exit 0
pnpm --filter @objectstack/cli test        →  68 files / 600 tests passed

已 merge origin/main(5 个新 commit,均不触及 packages/{lint,spec,formula},无冲突),在合并后的树上重跑 lint 测试 + typecheck 仍全绿。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 4, 2026 5:23am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint.

3 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/automation/hook-bodies.mdx (via @objectstack/lint)
• content/docs/permissions/authorization.mdx (via @objectstack/lint)
• content/docs/releases/v17.mdx (via @objectstack/lint)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.