lint: `validate-translation-references` builds its `_validations` universe from top-level rules only, so a nested `conditional` branch's legitimate bundle entry is reported as an orphan

[os-musk]

What

validate-translation-references collects the _validations universe with a flat walk of objects[].validations[]:

// packages/lint/src/validate-translation-references.ts:629
for (const rule of asArray(obj.validations)) {
 const ruleName = strName(rule.name);
 if (ruleName) facts.validations.add(ruleName);
}

A conditional rule's then / otherwise branch is a full rule carrying its own name, and that branch name is the address the resolver uses — checkConditional delegates to the branch and authoredRuleMessage keys on the branch's rule.name. So a bundle entry for a branch is correct and resolves at runtime, but this walk never sees the name and the rule reports it as an orphan.

Measured

Against the built rule (packages/lint/dist/index.js), a stack with one conditional carrying two named branches and bundle entries for all three names:

findings on _validations keys: 2
 - translation-target-unknown | translations[0]["zh-CN"].objects.demo_account._validations.churn_reason_present
 Translations are keyed to validation rule "churn_reason_present", which object "demo_account" does not
 declare in `validations[]`. The rule's authored `message` keeps its source locale in every refusal.
 - translation-target-unknown | translations[0]["zh-CN"].objects.demo_account._validations.churn_reason_absent
 (same)

The wrapper's own name (churn_reason_consistency) is accepted; the two branches — the only two whose messages a caller ever reads — are flagged.

Two things are wrong at once:

1. False positive. The entry is legitimate. packages/objectql/src/validation/rule-validator.test.ts pins the behaviour directly: it('addresses a nested conditional branch by the BRANCH's own name', ...), with the wrapper's entry present and deliberately NOT rendered.
2. The advice is inverted. The finding says the authored message "keeps its source locale in every refusal" — the opposite of the truth for these keys. Acting on it (deleting the entry) reintroduces the exact defect the entry fixes, and the message reads as authoritative.

Blast radius today

Severity is warning, and the rule id is translation-target-unknown — not the i18n/ prefix scripts/check-i18n-coverage.mjs counts (countI18nRuleIssues filters rule.startsWith('i18n/')), so no gate goes red. It is noise plus wrong advice, not a build break.

It is live in the tree as of #14518: showcase_account now carries churn_reason_present / churn_reason_absent entries, which is what a nested conditional requires.

Suggested shape

Descend into then / otherwise when building ObjectFacts.validations, the same recursion evaluateRule performs. Same shape as the missing-leg family (#13835 _tabs, #11608 flows), except the leg exists here and its universe is short.

Worth checking in the same pass whether a conditional wrapper's own name should stay in the universe. Its message is structurally unreachable (checkConditional either returns nothing, returns unevaluableRuleError — which builds its own sentence — or delegates), so an entry for it is inert. #14518 keeps one deliberately, so the bundle mirrors the declared rule set 1:1 and its pin can ask for every declared name rather than re-deriving objectql's dispatch; if the rule ever grows a "redundant, never rendered" verdict, that is the shape to weigh it against.

Where

• packages/lint/src/validate-translation-references.ts:629 — the flat walk.
• packages/objectql/src/validation/rule-validator.ts — checkConditional / authoredRuleMessage, the addressing this must mirror.

Found while implementing #14518; outside that card's declared file surface, so recorded here rather than widened into its PR.

Generated by Claude Code

[huangyiirene]

Triage — graded p2, bug + i18n, pm:queue, routed domain:devx (packages/lint is that lane). Applied and read back first.

Every claim reproduced at origin/main 4d0d944

• The flat walk is at validate-translation-references.ts:632-634, exactly as quoted.
• The objectql pin exists: rule-validator.test.ts:2509 — it('addresses a nested conditional branch by the BRANCH's own name', …). So the behaviour the lint rule contradicts is pinned in another package.
• Live in the tree: churn_reason_present / churn_reason_absent appear in examples/app-showcase/src/data/objects/account.object.ts and four times in src/system/translations/index.ts.
• No gate reds: check-i18n-coverage.mjs:272 filters i.rule.startsWith('i18n/'), and this rule id is translation-target-unknown.

Why p2 — the inverted advice, not the false positive

A false positive at warning severity that no gate counts is ordinary noise, and would be p3.

⭐ What lifts it is your second point: the finding tells the author "The rule's authored message keeps its source locale in every refusal" — the opposite of the truth for these keys — and the remedy it implies (delete the entry) reintroduces the exact defect the entry fixes. A lint rule that is merely wrong wastes a minute. One that is wrong and prescriptive converts a correct bundle into a broken one, and it reads as authoritative while doing it.

Not p1: nothing is red, nothing is blocked, and the damage requires an author to act on the advice.

⭐ The comment directly above the walk is the sharpest evidence

// #14253: `_validations.<rule>` is keyed by the rule's own `name`. A rule
// without a name has no key and is not registered — the resolver cannot
// address it either, so nothing is lost by skipping it here.

That is careful reasoning — it considers unnamed rules and correctly concludes nothing is lost. It just never considers a nested rule. So this is not an oversight in unconsidered code; it is a considered walk whose universe was defined one level too shallow, with a comment that reads as complete.

⚠️ And the #14253 citation puts this in the i18n declaration-drift cluster with #14653 (the extractor half) and #14708 (the docblock half) — three consumers of the same declaration, each with its own hand-maintained walk. ⛔ Not to be folded together; #14653 holds that class.

Scope

Descend into then / otherwise when building ObjectFacts.validations, mirroring evaluateRule's recursion — your suggested shape, adopted.

⭐ Also settle the wrapper question in the same pass, since a fixer touching this walk will have to decide it anyway: you note the wrapper's own message is structurally unreachable (checkConditional returns nothing, returns unevaluableRuleError which builds its own sentence, or delegates), so an entry for it is inert — while #14518 deliberately keeps one so the bundle mirrors the declared rule set 1:1. ⛔ Do not silently drop the wrapper from the universe to "tidy" it; #14518's reason is a live constraint, and removing it would make that card's pin unsatisfiable.

⛔ Do not widen into packages/objectql. checkConditional / authoredRuleMessage are the addressing this must mirror, not change.

---

Generated by Claude Code