Repository navigation
Expand file tree
/
Copy pathexpression-refusal-codes.test.ts
More file actions
652 lines (625 loc) · 29.8 KB
/
Copy pathexpression-refusal-codes.test.ts
File metadata and controls
652 lines (625 loc) · 29.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
/**
* The refusal codes `validateExpression` and `collectCelRootIdentifiers` carry
* beside their English message (`expression-refusal.ts`).
*
* Two kinds of pin, and they fail for different reasons:
*
* - **One test per code** — the code, its params exactly, and the English
* message exactly. The message pins are the control for adding the code: a
* code rides BESIDE the sentence API callers, the CLI and the agent tool
* already read, and must not change a byte of it. Where a message embeds a
* diagnostic the CEL or template engine wrote (`detail`), the expected text
* takes that diagnostic from the engine itself — the pin is on our words and
* on the pass-through, never on the engine's wording.
* - **The closed set** — every code has a pin and nothing else does; every
* refusal a broad sweep of inputs provokes carries a code from the set, with
* params the message actually interpolates; and at the type level a refusal
* without a code does not compile. A new refusal path without a code goes
* red at the type check, and a code nobody pinned goes red here.
*/
import { describe, expect, it } from 'vitest';
import { celEngine, collectCelRootIdentifiers, type CelRootIdentifiersResult } from './cel-engine';
import { templateEngine } from './template-engine';
import { validateExpression, type ExprInput, type ExprSchemaHint, type ExprValidationError, type FieldRole } from './validate';
import {
EXPRESSION_REFUSAL_CODES,
type CelRootsRefusalCode,
type ExpressionRefusalCode,
type ExpressionRefusalParams,
} from './expression-refusal';
import * as formula from './index';
/** What one refusal says, whichever producer said it. */
interface Said {
readonly code: string;
readonly params: unknown;
readonly message: string;
}
/** The CEL engine's own diagnostic for `source` — what a CEL code's `detail` passes through. */
function celDetail(source: string): string {
const compiled = celEngine.compile(source);
if (compiled.ok) throw new Error(`expected \`${source}\` not to compile`);
return compiled.error.message;
}
/** The template engine's own diagnostic for `source`. */
function templateDetail(source: string): string {
const compiled = templateEngine.compile(source);
if (compiled.ok) throw new Error(`expected \`${source}\` not to compile as a template`);
return compiled.error.message;
}
/** The one refusal `validateExpression` reports, as an error, with nothing beside it. */
function onlyError(role: FieldRole, input: ExprInput, schema?: ExprSchemaHint): Said {
const r = validateExpression(role, input, schema);
expect(r.ok).toBe(false);
expect(r.warnings).toHaveLength(0);
expect(r.errors).toHaveLength(1);
return r.errors[0];
}
/** The one advisory `validateExpression` reports, with no error beside it. */
function onlyWarning(role: FieldRole, input: ExprInput, schema?: ExprSchemaHint): Said {
const r = validateExpression(role, input, schema);
expect(r.ok).toBe(true);
expect(r.errors).toHaveLength(0);
expect(r.warnings).toHaveLength(1);
return r.warnings[0];
}
/** `collectCelRootIdentifiers`'s refusal, with `error` read as the message. */
function rootsRefusal(source: string): Said {
const r = collectCelRootIdentifiers(source);
if (r.ok) throw new Error(`expected \`${source}\` to be refused`);
return { code: r.code, params: r.params, message: r.error };
}
interface Pin<C extends ExpressionRefusalCode> {
readonly produce: () => Said;
readonly params: ExpressionRefusalParams[C];
readonly message: string;
}
/** Over `maxListElements` (64) and under every other bound. */
const OVERSIZED_LIST = `size([${Array.from({ length: 65 }, () => '0').join(', ')}]) > 0`;
const NON_STRING_ENVELOPE_TAIL = (example: string, dialect: string): string =>
`Write the expression as bare text (e.g. ${example}), or as an envelope whose \`source\` is that text ` +
`(e.g. \`{ dialect: '${dialect}', source: '…' }\`).`;
const METHOD_CALL_TAIL =
' The callable names this platform advertises for authoring (the `functions` list `introspectScope` returns, ' +
'`CEL_STDLIB_FUNCTIONS`) take their subject as an argument; only cel-js\'s own receiver methods ' +
'(`record.name.split(\',\')`) are written after a dot.';
const UNKNOWN_FUNCTION_TAIL =
' The callable names this platform advertises for authoring are the `functions` list `introspectScope` returns ' +
'(`CEL_STDLIB_FUNCTIONS`) — pick one of those, or precompute the value in a stored field and reference that field instead.';
/**
* Every code, its primary case first. The mapped type makes a code without a
* pin a type error in this file; the first test below makes it a red run.
*/
const PINS: { readonly [C in ExpressionRefusalCode]: readonly [Pin<C>, ...Pin<C>[]] } = {
'envelope-source-not-text': [
{
produce: () => onlyError('predicate', { dialect: 'cel', source: 42 } as unknown as ExprInput),
params: { role: 'predicate', found: 'number' },
message:
'invalid predicate envelope: an expression envelope carries its expression as a string `source` — found a number. ' +
NON_STRING_ENVELOPE_TAIL('`record.rating >= 4`', 'cel'),
},
{
produce: () => onlyError('template', { source: ['a'] } as unknown as ExprInput),
params: { role: 'template', found: 'array' },
message:
'invalid template envelope: an expression envelope carries its expression as a string `source` — found an array. ' +
NON_STRING_ENVELOPE_TAIL('`Hi {{ record.name }}`', 'template'),
},
{
produce: () => onlyError('value', { source: { a: 1 } } as unknown as ExprInput),
params: { role: 'value', found: 'object' },
message:
'invalid value envelope: an expression envelope carries its expression as a string `source` — found an object. ' +
NON_STRING_ENVELOPE_TAIL('`record.rating >= 4`', 'cel'),
},
],
'template-dialect-mismatch': [
{
produce: () => onlyError('template', { dialect: 'cel', source: 'x' }),
params: { dialect: 'cel' },
message: 'expected a text template but got a `cel` expression.',
},
],
'invalid-template': [
{
produce: () => onlyError('template', 'Hi {{ record.name '),
params: { detail: templateDetail('Hi {{ record.name ') },
message: `invalid template: ${templateDetail('Hi {{ record.name ')} (holes use \`{{ path }}\`).`,
},
],
'template-single-brace': [
{
produce: () => onlyError('template', 'Hi {name}'),
params: { ref: 'name' },
message: 'single-brace `{name}` is not a valid template hole — use double braces: `{{ name }}`.',
},
],
'cel-dialect-mismatch': [
{
produce: () => onlyError('predicate', { dialect: 'js', source: 'x' }),
params: { dialect: 'js' },
message: 'expected a CEL expression but got a `js` dialect.',
},
],
'invalid-cel': [
{
produce: () => onlyError('predicate', 'record.rating >='),
params: { role: 'predicate', detail: celDetail('record.rating >='), celCode: 'unexpected_token', pos: { start: 16, end: 16 } },
message: `invalid CEL predicate: ${celDetail('record.rating >=')} — predicates are bare CEL (e.g. \`record.rating >= 4\`).`,
},
{
produce: () => onlyError('value', "1 + 'a'"),
params: { role: 'value', detail: celDetail("1 + 'a'"), celCode: 'no_such_overload', pos: { start: 0, end: 7 } },
message: `invalid CEL value: ${celDetail("1 + 'a'")} — values are bare CEL (e.g. \`record.rating >= 4\`).`,
},
],
'cel-too-large': [
{
produce: () => onlyError('predicate', OVERSIZED_LIST),
params: { role: 'predicate', detail: celDetail(OVERSIZED_LIST), limit: 'maxListElements', limitValue: 64 },
message:
`invalid CEL predicate: ${celDetail(OVERSIZED_LIST)} — this is valid CEL that exceeds the \`maxListElements\` ` +
'budget (limit 64) — a SIZE fault, not a dialect mistake, so re-spelling the expression will not fix it. ' +
'Shrink it (fewer clauses, shallower nesting, fewer list elements), or precompute the heavy part into a stored ' +
'field and reference that field instead. Splitting it into several expressions changes how they combine at ' +
'this authoring site, so check that site\'s semantics before doing that.',
},
],
'cel-method-call': [
{
produce: () => onlyError('predicate', "record.name.upper() == 'X'"),
params: { role: 'predicate', detail: celDetail("record.name.upper() == 'X'"), name: 'upper', receiver: 'record.name' },
message:
`invalid CEL predicate: ${celDetail("record.name.upper() == 'X'")} — \`upper\` is callable bare, not as a method — ` +
'a CALL-SHAPE fault, not a dialect mistake, so re-spelling the expression will not fix it. ' +
'Write `upper(record.name)` instead.' + METHOD_CALL_TAIL,
},
{
produce: () => onlyError('predicate', "record.tags[0].upper() == 'X'"),
params: { role: 'predicate', detail: celDetail("record.tags[0].upper() == 'X'"), name: 'upper' },
message:
`invalid CEL predicate: ${celDetail("record.tags[0].upper() == 'X'")} — \`upper\` is callable bare, not as a method — ` +
'a CALL-SHAPE fault, not a dialect mistake, so re-spelling the expression will not fix it. ' +
'Write `upper(…)` with the receiver as its first argument instead.' + METHOD_CALL_TAIL,
},
],
'cel-unknown-function': [
{
produce: () => onlyError('predicate', "upperr(record.name) == 'X'"),
params: { role: 'predicate', detail: celDetail("upperr(record.name) == 'X'"), name: 'upperr', suggestion: 'upper' },
message:
`invalid CEL predicate: ${celDetail("upperr(record.name) == 'X'")} — \`upperr\` is not a callable name here — ` +
'a NAME fault, not a dialect mistake, so re-spelling the expression will not fix it. Did you mean `upper`?' +
UNKNOWN_FUNCTION_TAIL,
},
{
produce: () => onlyError('value', 'frobnicate(record.x)'),
params: { role: 'value', detail: celDetail('frobnicate(record.x)'), name: 'frobnicate' },
message:
`invalid CEL value: ${celDetail('frobnicate(record.x)')} — \`frobnicate\` is not a callable name here — ` +
'a NAME fault, not a dialect mistake, so re-spelling the expression will not fix it.' + UNKNOWN_FUNCTION_TAIL,
},
],
'cel-template-brace': [
{
produce: () => onlyError('predicate', "{status} == 'x'"),
params: { role: 'predicate', detail: celDetail("{status} == 'x'"), ref: 'status' },
message:
`invalid CEL predicate: ${celDetail("{status} == 'x'")} — it looks like a \`{status}\` template brace was used ` +
'inside a CEL expression — `{…}` parses as a CEL map literal and fails. Write the bare reference instead, e.g. `status`.',
},
],
'unknown-field': [
{
produce: () => onlyError('predicate', 'record.amout > 1', { fields: ['amount'], objectName: 'deal' }),
params: { field: 'amout', objectName: 'deal', suggestion: 'amount' },
message: 'unknown field `amout` on `deal` — did you mean `amount`?',
},
{
produce: () => onlyError('predicate', 'record.zzz > 1', { fields: ['amount'] }),
params: { field: 'zzz' },
message: 'unknown field `zzz`',
},
{
// A declared read attachment's second segment (#22386): the same code,
// the dotted path, and the optional clause naming the declared leaves.
produce: () =>
onlyError('predicate', 'record.viewer.can_actt', {
fields: ['status', 'viewer'],
objectName: 'approval',
attachedOnRead: { viewer: ['can_act', 'is_submitter'] },
}),
params: {
field: 'viewer.can_actt',
objectName: 'approval',
suggestion: 'viewer.can_act',
block: 'viewer',
leaves: ['can_act', 'is_submitter'],
},
message:
'unknown field `viewer.can_actt` on `approval` (the read attachment `viewer` declares `can_act`, `is_submitter`) ' +
'— did you mean `viewer.can_act`?',
},
],
'unknown-role': [
{
produce: () => onlyError('predicate', "'org_admni' in current_user.positions", { roleCatalog: ['org_admin', 'sales'] }),
params: { name: 'org_admni', suggestion: 'org_admin', catalog: ['org_admin', 'sales'] },
message: 'unknown role `org_admni` — not a defined role; did you mean `org_admin`? Valid roles: org_admin, sales.',
},
{
produce: () => onlyError('predicate', "'zzzzzzzz' in current_user.positions", { roleCatalog: ['org_admin', 'sales'] }),
params: { name: 'zzzzzzzz', catalog: ['org_admin', 'sales'] },
message: 'unknown role `zzzzzzzz` — not a defined role. Valid roles: org_admin, sales.',
},
],
'unbound-root': [
{
produce: () => onlyError('predicate', "pge.selectedProjectId != ''", { scope: 'record', roots: ['page'] }),
params: { name: 'pge', roots: ['page'], suggestion: 'page' },
message:
'unbound root `pge` — beyond the record this authoring surface binds `page`, and `pge` is none of them, ' +
'so `pge.…` resolves to nothing and the expression silently evaluates to null. Did you mean `page`?',
},
],
'bare-reference': [
{
produce: () => onlyError('value', 'amount * 2', { scope: 'record' }),
params: { name: 'amount' },
message:
'bare reference `amount` — a formula/validation expression binds the record as the `record` namespace, ' +
'not at top level, so `amount` resolves to nothing and the expression silently evaluates to null. Write `record.amount`.',
},
],
'date-arithmetic': [
{
produce: () => onlyError('value', 'record.close_date + 1', { scope: 'record', fieldTypes: { close_date: 'date' } }),
params: { operands: 'google.protobuf.Timestamp + int', reference: 'record.close_date' },
message:
'date arithmetic `google.protobuf.Timestamp + int` — `record.close_date` is a date, and CEL can\'t do arithmetic ' +
'on dates: this faults at runtime, so the field silently evaluates to null. Use `daysBetween(a, b)` for the span ' +
'in whole days, and `daysFromNow(n)` / `addDays(d, n)` / `addMonths(d, n)` to shift a date.',
},
{
produce: () =>
onlyError('predicate', 'close_date + 1 > 3', { fields: ['close_date'], fieldTypes: { close_date: 'date' } }),
params: { operands: 'google.protobuf.Timestamp + int', reference: 'close_date' },
message:
'date arithmetic `google.protobuf.Timestamp + int` — `close_date` is a date, and CEL can\'t do arithmetic ' +
'on dates: this faults at runtime, so the field silently evaluates to null. Use `daysBetween(a, b)` for the span ' +
'in whole days, and `daysFromNow(n)` / `addDays(d, n)` / `addMonths(d, n)` to shift a date.',
},
],
'date-text-arithmetic': [
{
produce: () =>
onlyError('value', 'record.end_date - record.start_date', {
scope: 'record',
fieldTypes: { start_date: 'date', end_date: 'date' },
}),
params: { operands: 'DateText - DateText', reference: 'record.start_date' },
message:
'date arithmetic `DateText - DateText` — `record.start_date` is a date field, and the runtime holds a date field ' +
'as its text (`YYYY-MM-DD`, or an ISO-8601 instant for a date-time), which CEL can\'t do arithmetic on: this ' +
'faults at runtime, so the field silently evaluates to null. Use `daysBetween(a, b)` for the span in whole days, ' +
'and `daysFromNow(n)` / `addDays(d, n)` / `addMonths(d, n)` to shift a date.',
},
{
produce: () =>
onlyError('predicate', 'end_at - start_at > duration("1h")', {
fields: ['start_at', 'end_at'],
fieldTypes: { start_at: 'datetime', end_at: 'datetime' },
}),
params: { operands: 'DateText - DateText', reference: 'start_at' },
message:
'date arithmetic `DateText - DateText` — `start_at` is a date field, and the runtime holds a date field ' +
'as its text (`YYYY-MM-DD`, or an ISO-8601 instant for a date-time), which CEL can\'t do arithmetic on: this ' +
'faults at runtime, so the field silently evaluates to null. Use `daysBetween(a, b)` for the span in whole days, ' +
'and `daysFromNow(n)` / `addDays(d, n)` / `addMonths(d, n)` to shift a date.',
},
],
'date-duration-value': [
{
produce: () =>
onlyError('value', 'today() - record.start_date', { scope: 'record', fieldTypes: { start_date: 'date' } }),
params: { reference: 'record.start_date' },
message:
'date arithmetic — this computes a `google.protobuf.Duration` from `record.start_date`, and a field can\'t hold ' +
'a duration: it reads `{}` at runtime. Use `daysBetween(a, b)` for the span in whole days, and ' +
'`daysFromNow(n)` / `addDays(d, n)` / `addMonths(d, n)` to shift a date.',
},
{
produce: () => onlyError('value', 'today() - daysAgo(3)', { scope: 'record', fieldTypes: { name: 'text' } }),
params: {},
message:
'date arithmetic — this computes a `google.protobuf.Duration`, and a field can\'t hold ' +
'a duration: it reads `{}` at runtime. Use `daysBetween(a, b)` for the span in whole days, and ' +
'`daysFromNow(n)` / `addDays(d, n)` / `addMonths(d, n)` to shift a date.',
},
],
'type-mismatch': [
{
produce: () => onlyWarning('predicate', 'record.name > 5', { scope: 'record', fieldTypes: { name: 'text' } }),
params: { operands: 'string > int', operator: '>', held: 'text', reference: 'record.name' },
message:
'type mismatch `string > int` — `record.name` holds text but is used with `>` against a number. This faults at ' +
'runtime, so the expression silently evaluates to null (unless the value happens to be numeric). Use a number ' +
'field, or drop the arithmetic/comparison.',
},
{
produce: () =>
onlyWarning('predicate', 'record.active + 1 > 5', { scope: 'record', fieldTypes: { active: 'boolean' } }),
params: { operands: 'bool + int', operator: '+', held: 'boolean', reference: 'record.active' },
message:
'type mismatch `bool + int` — `record.active` holds a boolean but is used with `+` against a number. This faults ' +
'at runtime, so the expression silently evaluates to null (unless the value happens to be numeric). Use a number ' +
'field, or drop the arithmetic/comparison.',
},
],
'field-near-miss': [
{
produce: () => onlyWarning('predicate', "stauts == 'x'", { fields: ['status'], objectName: 'deal' }),
params: { name: 'stauts', suggestion: 'status', objectName: 'deal' },
message:
'`stauts` is not a field of `deal` — did you mean `status`? (flow conditions reference fields bare, e.g. ' +
'`status == …`). If `stauts` is a flow variable this is safe to ignore.',
},
{
produce: () => onlyWarning('predicate', "stauts == 'x'", { fields: ['status'] }),
params: { name: 'stauts', suggestion: 'status' },
message:
'`stauts` is not a field of `the trigger object` — did you mean `status`? (flow conditions reference fields ' +
'bare, e.g. `status == …`). If `stauts` is a flow variable this is safe to ignore.',
},
],
'traversal-bare-and-traversed': [
{
produce: () =>
onlyError('predicate', "record.account == 'a1' && record.account.name == 'x'", {
fieldTypes: { account: 'lookup' },
traversalHydration: true,
}),
params: { root: 'record', field: 'account' },
message:
'`record.account` is read BOTH through the relationship (`record.account.<related field>`) and as a plain value ' +
'(`record.account`) in the same expression. Reading through the relationship resolves `record.account` to the ' +
'related RECORD, so the plain-value comparison would stop matching the stored id — silently. To compare the id, ' +
'write `record.account.id` for the value comparison, and keep `record.account.<related field>` for the ' +
'traversal. `record.account.id` is not a null guard: it reads through `account` too, and a rule that reads ' +
'through an empty `account` rejects the write instead of being skipped. If the plain value tests for empty, ' +
'take that test out of this expression. To skip the rule while `account` is empty, guard it on `account` being ' +
'set: make it the `then` of a `conditional` rule whose `when` is `record.account != null`. To refuse an empty ' +
'`account`, make `account` required (`required: true`).',
},
],
'traversal-multi-hop': [
{
produce: () =>
onlyError('predicate', "record.account.owner.name == 'x'", {
fieldTypes: { account: 'lookup' },
traversalHydration: true,
}),
params: { root: 'record', field: 'account' },
message:
'`record.account` is read through more than one relationship hop. Predicates resolve ONE hop ' +
'(`record.account.<related field>`); a second hop is not loaded, so the expression would fault at evaluation ' +
'time and reject the write. Denormalise the value you need onto `account`\'s object, or read it in a hook instead.',
},
],
'label-field-no-options': [
{
// #28659: the evaluator's own fault sentence, at author time.
produce: () =>
onlyError('value', 'label(record.first)', {
scope: 'record',
objectName: 'p4',
fields: ['first', 'kind'],
optionFields: ['kind'],
}),
params: { field: 'first' },
message:
'label(record.first): `first` declares no options, so it has no option label. ' +
"label() reads a select field's option label; read any other field directly (record.first).",
},
],
'empty-expression': [
{
produce: () => rootsRefusal(' '),
params: {},
message: 'expression is empty',
},
],
'cel-parse-failed': [
{
produce: () => rootsRefusal('a =='),
params: { detail: celDetail('a ==') },
message: celDetail('a =='),
},
{
produce: () => rootsRefusal(OVERSIZED_LIST),
params: { detail: celDetail(OVERSIZED_LIST) },
message: celDetail(OVERSIZED_LIST),
},
],
};
describe('expression refusal codes — one pin per code (code, params, unchanged message)', () => {
for (const code of EXPRESSION_REFUSAL_CODES) {
it(code, () => {
const cases = PINS[code] as readonly Pin<typeof code>[];
for (const pin of cases) {
const said = pin.produce();
expect(said.code).toBe(code);
expect(said.params).toEqual(pin.params);
expect(said.message).toBe(pin.message);
}
});
}
});
/**
* Inputs chosen to walk every arm of both producers, and a good many inputs
* that are refused by none — the sweep asserts about whatever it provokes, so
* a clean input costs nothing and a new arm reached by an old input is judged.
*/
const SWEEP_SOURCES: readonly string[] = [
'',
' ',
'record.rating >= 4',
'record.rating >=',
"1 + 'a'",
'a ==',
OVERSIZED_LIST,
"record.name.upper() == 'X'",
"record.tags[0].upper() == 'X'",
"upperr(record.name) == 'X'",
'frobnicate(record.x)',
"upper(1, 2) == 'X'",
"record.name.contains() == true",
"{status} == 'x'",
'Hi {name}',
'Hi {{ record.name }}',
'Hi {{ record.name ',
'Hi {{ }}',
'record.amout > 1',
'record.amount > 1',
'amount * 2',
"stauts == 'x'",
"status == 'x'",
"pge.selectedProjectId != ''",
"page.selectedProjectId != ''",
"'org_admni' in current_user.positions",
"current_user.positions.contains('zzz')",
'record.close_date + 1',
'close_date + 1 > 3',
'record.close_date - record.close_date',
'today() - record.close_date',
'record.name > 5',
'record.active + 1 > 5',
"record.account == 'a1' && record.account.name == 'x'",
"record.account.owner.name == 'x'",
"type == 'grid' && status == 'q'",
'has(status) && other == 1',
'daysBetween(record.a, record.b) > 3',
"label(record.name) + label(record.status)",
];
const SWEEP_INPUTS: readonly ExprInput[] = [
...SWEEP_SOURCES,
...SWEEP_SOURCES.map((source) => ({ dialect: 'cel', source })),
...SWEEP_SOURCES.map((source) => ({ dialect: 'template', source })),
{ dialect: 'js', source: 'x' },
{ source: 42 } as unknown as ExprInput,
{ source: ['a'] } as unknown as ExprInput,
{ source: { a: 1 } } as unknown as ExprInput,
{ source: true } as unknown as ExprInput,
{ dialect: 'cel' },
null,
undefined,
];
const SWEEP_SCHEMAS: readonly (ExprSchemaHint | undefined)[] = [
undefined,
{ scope: 'record' },
{ scope: 'record', roots: ['page'] },
{
scope: 'record',
objectName: 'deal',
fields: ['amount', 'close_date', 'name', 'active', 'account', 'status'],
fieldTypes: { close_date: 'date', name: 'text', active: 'boolean', account: 'lookup' },
roleCatalog: ['org_admin', 'sales'],
optionFields: ['status'],
},
{ fields: ['status', 'close_date'], objectName: 'deal', fieldTypes: { close_date: 'date' } },
{ fields: ['status'] },
{ fieldTypes: { account: 'lookup' }, traversalHydration: true },
];
const VALIDATE_CODES: ReadonlySet<string> = new Set(
EXPRESSION_REFUSAL_CODES.filter((c) => c !== 'empty-expression' && c !== 'cel-parse-failed'),
);
const ROOTS_CODES: ReadonlySet<CelRootsRefusalCode> = new Set<CelRootsRefusalCode>(['empty-expression', 'cel-parse-failed']);
/**
* The LOCATOR params (`expression-refusal.ts`): a structured reading of the
* fault `detail` renders, not text the message interpolates. Judged by
* {@link expectLocatorsRead} instead of by containment.
*/
const LOCATOR_PARAMS: ReadonlySet<string> = new Set(['celCode', 'pos']);
/** Every string a param carries, flattened — lists element by element, numbers as text. */
function paramStrings(params: unknown): string[] {
const out: string[] = [];
for (const [key, value] of Object.entries(params as Record<string, unknown>)) {
if (LOCATOR_PARAMS.has(key)) continue;
if (Array.isArray(value)) out.push(...value.map(String));
else out.push(String(value));
}
return out;
}
/**
* A locator param, where present, is a reading of the engine's fault: only
* `invalid-cel` carries them, the code is a cel-js snake_case token, and the
* range lies inside the source it was read against.
*/
function expectLocatorsRead(said: { code: string; params: unknown; source: string }): void {
const params = said.params as Record<string, unknown>;
const present = Object.keys(params).filter((k) => LOCATOR_PARAMS.has(k));
if (present.length === 0) return;
expect(said.code).toBe('invalid-cel');
if ('celCode' in params) expect(params.celCode).toMatch(/^[a-z]+(?:_[a-z]+)*$/);
if ('pos' in params) {
const { start, end } = params.pos as { start: number; end: number };
expect(Number.isInteger(start) && Number.isInteger(end)).toBe(true);
expect(0 <= start && start <= end && end <= said.source.length, `${JSON.stringify(params.pos)} in ${JSON.stringify(said.source)}`).toBe(true);
}
}
describe('expression refusal codes — the closed set', () => {
it('has a pin for every code, and no pin for a code outside the set', () => {
expect(Object.keys(PINS).sort()).toEqual([...EXPRESSION_REFUSAL_CODES].sort());
expect(new Set(EXPRESSION_REFUSAL_CODES).size).toBe(EXPRESSION_REFUSAL_CODES.length);
for (const code of EXPRESSION_REFUSAL_CODES) expect(code).toMatch(/^[a-z]+(?:-[a-z]+)+$/);
});
it('is published from the package entry, frozen', () => {
expect(formula.EXPRESSION_REFUSAL_CODES).toBe(EXPRESSION_REFUSAL_CODES);
expect(Object.isFrozen(EXPRESSION_REFUSAL_CODES)).toBe(true);
});
it('every refusal validateExpression reports on the sweep carries a code from its set, with params the message interpolates', () => {
const provoked = new Set<string>();
let refusals = 0;
for (const role of ['predicate', 'value', 'template'] as const) {
for (const input of SWEEP_INPUTS) {
for (const schema of SWEEP_SCHEMAS) {
const r = validateExpression(role, input, schema);
for (const said of [...r.errors, ...r.warnings]) {
refusals++;
expect(VALIDATE_CODES.has(said.code), `${said.code} from ${JSON.stringify(input)}`).toBe(true);
expect(typeof said.params).toBe('object');
expect(said.params).not.toBeNull();
for (const part of paramStrings(said.params)) expect(said.message).toContain(part);
expectLocatorsRead(said);
provoked.add(said.code);
}
}
}
}
// Positive control: the sweep is not vacuous — it reaches every code this
// producer owns, so a code whose arm stopped being reachable shows up too.
expect(refusals).toBeGreaterThan(100);
expect([...provoked].sort()).toEqual([...VALIDATE_CODES].sort());
});
it('every refusal collectCelRootIdentifiers reports on the sweep carries a code from its set', () => {
const provoked = new Set<string>();
for (const source of SWEEP_SOURCES) {
const r = collectCelRootIdentifiers(source);
if (r.ok) continue;
expect(ROOTS_CODES.has(r.code)).toBe(true);
for (const part of paramStrings(r.params)) expect(r.error).toContain(part);
provoked.add(r.code);
}
expect([...provoked].sort()).toEqual([...ROOTS_CODES].sort());
});
it('a refusal without a code does not type-check, on either producer', () => {
// @ts-expect-error — `code` and `params` are required on every validateExpression refusal.
const noCode: ExprValidationError = { source: 'x', message: 'y' };
// @ts-expect-error — `code` and `params` are required on collectCelRootIdentifiers' failure arm.
const noRootsCode: CelRootIdentifiersResult = { ok: false, error: 'y' };
// @ts-expect-error — a code's params are its own: `invalid-cel` carries no `ref`.
const wrongParams: ExprValidationError = { source: 'x', message: 'y', code: 'invalid-cel', params: { ref: 'r' } };
expect([noCode, noRootsCode, wrongParams]).toHaveLength(3);
});
});