Skip to content

Commit 8fc7482

Browse files
committed
fix(lint): read a roll-up filter's keys as authored, the way the recompute query serves them
The recompute's where serves only the nested one-level relation form; it refuses a dotted key, a field computed on read and a second relation level, and each refusal fails every child write's recompute (measured on a real SqlDriver). walkFilterFieldKeys flattens a dotted key and a nested condition into one path, so the position now walks the authored keys itself: an unknown key keeps the family's verdict; a dotted key is refused with the nested spelling (relation head) or the denormalise cure, a formula key with the denormalise cure, and beneath a relation an unknown, dotted, second-level or empty condition is refused. The block is guarded on a `summary` field. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FEkQ5oEQNYg7j3ueo5t6pV
1 parent 834abfd commit 8fc7482

4 files changed

Lines changed: 270 additions & 33 deletions

File tree

‎.changeset/31224-summary-filter-key-unknown.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,11 @@ Skills-docs: none — `skills/**` and `content/docs/**` teach `summaryOperations
1313
**BREAKING** accept-set narrowing in `os validate` / `os build` / `os lint` and at the object save and publish doors (`PUT /api/v1/meta/object/NAME` live save, the per-item and package publish; Studio, REST and MCP authors), through the `object-field-ref-unknown` rule.
1414

1515
- **Before.** A summary field with `summaryOperations: { object: 'invoice_line', function: 'sum', field: 'amount', filter: { stauts: 'paid' } }` parsed, built and published. The engine runs the filter as the `where` of an aggregate on the child, ANDed with the parent-FK match. Measured on a real `SqlDriver` (better-sqlite3): every insert of a child row then answered `SummaryRecomputeError` ("the triggering records WERE written"), and the summary kept a stale value.
16-
- **Now.** Each key the child lacks is refused `error` at `objects[i].fields.FIELD.summaryOperations.filter.KEY`, naming the key, the child object and the nearest field ("Did you mean"). Keys inside `$and` / `$or` / `$not` groups and past operator objects are judged too, and a relationship path is resolved through the child.
16+
- **Now.** Each key the child lacks is refused `error` at `objects[i].fields.FIELD.summaryOperations.filter.KEY`, naming the key, the child object and the nearest field ("Did you mean"). Keys inside `$and` / `$or` / `$not` groups are judged too. Three more shapes the recompute query refuses are refused the same way, each measured on the same driver as a `SummaryRecomputeError` on every child insert:
17+
- a dotted key such as `account.status`: the cure is the nested one-level form the query serves, `{ account: { status: VALUE } }`;
18+
- a child field computed on read, such as a `formula`: denormalise it onto the child as a stored field;
19+
- beneath a relation, a key the related object lacks, a dotted key, a second relation holding a condition of its own, or an empty condition. The nested form reaches one level.
20+
- **Accepted.** Child fields with any operator, and the nested one-level relation form `{ relation: { field: VALUE } }` over fields of the related object.
1721
- **Not judged.** A child object the stack does not define, a child with no readable field map, and a registry-injected system column (resolved per object), the same skips every position of this rule takes.
1822

1923
**What an author does.** Nothing for a filter whose keys are fields of the child object. For a refused key: name the child field you meant (the verdict suggests the nearest one), or drop the key.

‎packages/lint/src/rule-explanations.ts‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4251,10 +4251,13 @@ const OBJECT_FIELD_REF_UNKNOWN_EXPLANATION: RuleExplanation = {
42514251
'`dependsOn` name that misses on the owning object is reported once, there.',
42524252
'A summary field\'s `summaryOperations.filter` is judged against the CHILD object ' +
42534253
'`summaryOperations.object` names: the engine ANDs it with the parent-FK match and runs it as the ' +
4254-
'query on that child, so every key (inside `$and` / `$or` / `$not` groups and operator objects, ' +
4255-
'or a relationship path) is a field of the child. A key the child lacks makes every child write ' +
4256-
'answer a roll-up recompute failure (the row is still written) while the summary keeps a stale ' +
4257-
'value.',
4254+
'query on that child, so every key (inside `$and` / `$or` / `$not` groups) is a field of the child. ' +
4255+
'That query refuses what it cannot serve, and each refusal makes every child write answer a roll-up ' +
4256+
'recompute failure (the row is still written) while the summary keeps a stale value. So the rule ' +
4257+
'refuses a key the child lacks; a dotted key such as `account.status` (write the nested one-level ' +
4258+
'form `{ account: { status: VALUE } }` instead); a field computed on read, such as a `formula` ' +
4259+
'(denormalise it onto the child as a stored field); and, beneath a relation, a key the related ' +
4260+
'object lacks, a dotted key or a second relation holding a condition of its own.',
42584261
'`lookupColumns`, `dependsOn` and `indexes[].fields` are read verbatim (a picker column key, a ' +
42594262
'record key, a physical column), so a dotted name there is one name no field carries; the ' +
42604263
'other positions resolve a relationship path. Not judged: an object this stack does not ' +

‎packages/lint/src/validate-object-field-refs.test.ts‎

Lines changed: 68 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -575,15 +575,81 @@ describe('validateObjectFieldRefs — summaryOperations.filter (addresses the CH
575575
]);
576576
});
577577

578-
it('passes child fields, operators, and a relationship path through the child', () => {
578+
it('passes child fields with operators, and the nested one-level relation form the engine serves', () => {
579579
expect(validateObjectFieldRefs(rollup({
580580
total: { $gt: 0 },
581581
issued_on: { $gte: '2026-01-01' },
582582
region: { $in: ['emea', 'apac'] },
583-
'account.status': 'active',
583+
account: { status: 'active', industry: { $in: ['saas'] } },
584584
}))).toEqual([]);
585585
});
586586

587+
it('REFUSES the dotted spelling of a relation path, with the nested spelling as the cure', () => {
588+
const findings = validateObjectFieldRefs(rollup({ 'account.status': 'active' }));
589+
expect(findings).toHaveLength(1);
590+
expect(findings[0]).toMatchObject({
591+
severity: 'error',
592+
rule: OBJECT_FIELD_REF_UNKNOWN,
593+
path: 'objects[0].fields.billed.summaryOperations.filter.account.status',
594+
});
595+
expect(findings[0]!.message).toContain('dotted path through the relation "account"');
596+
expect(findings[0]!.message).toContain('every recompute fails');
597+
expect(findings[0]!.hint).toBe('Nest the condition beneath the relation field: { account: { status: VALUE } }.');
598+
});
599+
600+
it('REFUSES a dotted path into a scalar field, and judges a dotted key whose head is unknown as unknown', () => {
601+
const findings = validateObjectFieldRefs(rollup({ 'region.code': 'x', 'regoin.code': 'y' }));
602+
expect(findings.map((f) => f.path)).toEqual([
603+
'objects[0].fields.billed.summaryOperations.filter.region.code',
604+
'objects[0].fields.billed.summaryOperations.filter.regoin.code',
605+
]);
606+
expect(findings[0]!.message).toContain('a dotted path into "region", a text field');
607+
expect(findings[0]!.hint).toContain('Denormalise the value onto the child object');
608+
expect(findings[1]!.message).toContain('"regoin" is not a field on object "crm_invoice"');
609+
});
610+
611+
it('REFUSES a child field computed on read (formula), at the top level and one level down', () => {
612+
const stack = rollup({ is_big: true, account: { score_band: 'a' } }) as any;
613+
stack.objects[1].fields.is_big = { type: 'formula', expression: 'total > 100' };
614+
stack.objects[0].fields.score_band = { type: 'formula', expression: "'a'" };
615+
const findings = validateObjectFieldRefs(stack);
616+
expect(findings.map((f) => f.path)).toEqual([
617+
'objects[0].fields.billed.summaryOperations.filter.is_big',
618+
'objects[0].fields.billed.summaryOperations.filter.account.score_band',
619+
]);
620+
expect(findings[0]!.message).toContain('a formula field of "crm_invoice", computed on read');
621+
for (const f of findings) expect(f.hint).toContain('Denormalise the value onto the child object');
622+
});
623+
624+
it('REFUSES what the nested form cannot serve: an unknown related key, a dotted one, a second relation level, an empty condition', () => {
625+
const stack = rollup({
626+
$and: [
627+
{ account: { statsu: 'active' } },
628+
{ account: { 'parent.name': 'x' } },
629+
{ account: { parent: { name: 'x' } } },
630+
{ account: {} },
631+
],
632+
}) as any;
633+
stack.objects[0].fields.parent = { type: 'lookup', reference: 'crm_account' };
634+
const findings = validateObjectFieldRefs(stack);
635+
expect(findings.map((f) => f.path)).toEqual([
636+
'objects[0].fields.billed.summaryOperations.filter.$and[0].account.statsu',
637+
'objects[0].fields.billed.summaryOperations.filter.$and[1].account.parent.name',
638+
'objects[0].fields.billed.summaryOperations.filter.$and[2].account.parent',
639+
'objects[0].fields.billed.summaryOperations.filter.$and[3].account',
640+
]);
641+
expect(findings[0]!.message).toContain('"statsu" is not a field on object "crm_account"');
642+
expect(findings[1]!.message).toContain('reaches one level only');
643+
expect(findings[2]!.message).toContain('is itself a relation of "crm_account"');
644+
expect(findings[3]!.message).toContain('names no field of "crm_account"');
645+
});
646+
647+
it('judges only a `summary` field', () => {
648+
const stack = rollup({ regoin: 'emea' }) as any;
649+
stack.objects[0].fields.billed.type = 'number';
650+
expect(validateObjectFieldRefs(stack)).toEqual([]);
651+
});
652+
587653
it('does not judge a filter whose child the stack does not define, or a roll-up with no filter', () => {
588654
expect(validateObjectFieldRefs(rollup({ anything: 1 }, { object: 'elsewhere_line' }))).toEqual([]);
589655
expect(validateObjectFieldRefs(rollup(undefined))).toEqual([]);

0 commit comments

Comments
 (0)