@sdeverywhere/check-core 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1272 @@
1
+ type SourceName = string;
2
+ type VarId = string;
3
+ type DatasetKey = string;
4
+ type Dataset = Map<number, number>;
5
+ type DatasetMap = Map<DatasetKey, Dataset>;
6
+
7
+ /** A unique identifier for the scenario, derived from its input settings. */
8
+ type ScenarioSpecUid = string;
9
+ type InputPosition = 'at-default' | 'at-minimum' | 'at-maximum';
10
+ interface PositionSetting {
11
+ kind: 'position';
12
+ inputVarId: VarId;
13
+ position: InputPosition;
14
+ }
15
+ interface ValueSetting {
16
+ kind: 'value';
17
+ inputVarId: VarId;
18
+ value: number;
19
+ }
20
+ type InputSetting = PositionSetting | ValueSetting;
21
+ interface InputSettingsSpec {
22
+ kind: 'input-settings';
23
+ uid: ScenarioSpecUid;
24
+ settings: InputSetting[];
25
+ }
26
+ interface AllInputsSpec {
27
+ kind: 'all-inputs';
28
+ uid: ScenarioSpecUid;
29
+ position: InputPosition;
30
+ }
31
+ type ScenarioSpec = InputSettingsSpec | AllInputsSpec;
32
+
33
+ interface DatasetsResult {
34
+ /**
35
+ * The map of datasets for the scenario.
36
+ */
37
+ datasetMap: DatasetMap;
38
+ /**
39
+ * The number of milliseconds that elapsed when running the model, or undefined if the model
40
+ * wasn't run for this scenario.
41
+ */
42
+ modelRunTime?: number;
43
+ }
44
+ interface DataSource {
45
+ /** Return the datasets that result from running the given scenario. */
46
+ getDatasetsForScenario(scenarioSpec: ScenarioSpec, datasetKeys: DatasetKey[]): Promise<DatasetsResult>;
47
+ }
48
+
49
+ /**
50
+ * Holds information about an item related to a variable used in the model.
51
+ * For example, this can be used to attach information about a graph that
52
+ * an output variable is used in, or a slider that controls an input variable.
53
+ */
54
+ interface RelatedItem {
55
+ id: string;
56
+ locationPath: string[];
57
+ }
58
+ /** A unique, stable input identifier. */
59
+ type InputId = string;
60
+ /**
61
+ * Holds information about an input variable used in the model.
62
+ */
63
+ interface InputVar {
64
+ /**
65
+ * Whether this input is controlled by a continuous range/slider or a discrete on/off switch.
66
+ * If undefined, 'slider' will be assumed.
67
+ */
68
+ kind?: 'slider' | 'switch';
69
+ /**
70
+ * A unique, stable identifier string for this input.
71
+ *
72
+ * This can be used to identify an input variable in a way that is resilient
73
+ * to the variable's name being changed between two versions of the model.
74
+ *
75
+ * For example, if both the "left" and "right" versions of the model have an
76
+ * input with an `inputId` of 2, but the variable is called "Variable 2" in
77
+ * the left and "Variable Two" in the right, the inputs can be correlated and
78
+ * compared despite the different variable names.
79
+ */
80
+ inputId: InputId;
81
+ /** The variable identifier (typically a simplified/canonical ID, like the form used in SDE). */
82
+ varId: VarId;
83
+ /** The full variable name as used in the modeling tool. */
84
+ varName: string;
85
+ /** The default value of the input. */
86
+ defaultValue: number;
87
+ /** The minimum value of the input. */
88
+ minValue: number;
89
+ /** The maximum value of the input. */
90
+ maxValue: number;
91
+ /** The metadata for the related input control. */
92
+ relatedItem?: RelatedItem;
93
+ }
94
+ /**
95
+ * Holds information about an output variable used in the model.
96
+ */
97
+ interface OutputVar {
98
+ /** The unique dataset key for this variable (it should include `sourceName` and `varId`). */
99
+ datasetKey: DatasetKey;
100
+ /**
101
+ * The source for the variable (e.g., undefined for a normal model output, "Data" for a variable
102
+ * that is defined in an external data file).
103
+ */
104
+ sourceName?: SourceName;
105
+ /** The variable identifier (typically a simplified/canonical ID, like the form used in SDE). */
106
+ varId: VarId;
107
+ /** The full variable name as used in the modeling tool. */
108
+ varName: string;
109
+ /** The metadata for the related visuals/graphs in which this variable is used. */
110
+ relatedItems?: RelatedItem[];
111
+ }
112
+ /**
113
+ * Holds information about a subscript used in the model.
114
+ */
115
+ interface Subscript {
116
+ /** The subscript identifier, as used in SDE. */
117
+ id: string;
118
+ /** The subscript name, as used in Vensim. */
119
+ name: string;
120
+ }
121
+ /**
122
+ * Holds information about a dimension (subscript family) used in the model.
123
+ */
124
+ interface Dimension {
125
+ /** The dimension identifier, as used in SDE. */
126
+ id: string;
127
+ /** The dimension name, as used in Vensim. */
128
+ name: string;
129
+ /** The set of subscripts in this dimension. */
130
+ subscripts: Subscript[];
131
+ }
132
+ /**
133
+ * Holds information about a variable used in the model implementation.
134
+ */
135
+ interface ImplVar {
136
+ /** The variable identifier, as used in SDE. */
137
+ varId: VarId;
138
+ /** The variable name, as used in the modeling tool. */
139
+ varName: string;
140
+ /** The variable index, used by SDE to reference the value in the generated model. */
141
+ varIndex: number;
142
+ /** The set of dimensions for this variable. */
143
+ dimensions: Dimension[];
144
+ /** The variable type (e.g. 'level', 'const'). */
145
+ varType: string;
146
+ }
147
+
148
+ /** The human-readable name for a group of inputs. */
149
+ type InputGroupName = string;
150
+ /** The alias name for an input. */
151
+ type InputAliasName = string;
152
+ /** The human-readable name for a group of dataset. */
153
+ type DatasetGroupName = string;
154
+ /**
155
+ * Includes the properties needed to display a legend item in the UI.
156
+ */
157
+ interface LegendItem {
158
+ /** The item text. */
159
+ label: string;
160
+ /** The color of the item (in CSS/hex format). */
161
+ color: string;
162
+ }
163
+ /**
164
+ * Includes the properties needed to display a link item in the UI.
165
+ */
166
+ interface LinkItem {
167
+ /** Whether content is a URL or text to be copied to the clipboard. */
168
+ kind: 'url' | 'copy';
169
+ /** The link text that appears in the UI. */
170
+ text: string;
171
+ /** The link content (a URL or text). */
172
+ content: string;
173
+ }
174
+ /** The identifier for a bundle-specific graph. */
175
+ type BundleGraphId = string;
176
+ /**
177
+ * Describes a dataset in a bundle-specific graph.
178
+ */
179
+ interface BundleGraphDatasetSpec {
180
+ /** The dataset key. */
181
+ datasetKey: DatasetKey;
182
+ /** The dataset or variable name. */
183
+ varName: string;
184
+ /** The source name. */
185
+ sourceName?: string;
186
+ /** The label string (as it appears in the graph legend). */
187
+ label?: string;
188
+ /** The color of the plot (in CSS/hex format). */
189
+ color: string;
190
+ }
191
+ /**
192
+ * Describes a bundle-specific graph.
193
+ */
194
+ interface BundleGraphSpec {
195
+ /** The graph identifier. */
196
+ id: BundleGraphId;
197
+ /** The graph title. */
198
+ title: string;
199
+ /** The legend items for the graph. */
200
+ legendItems: LegendItem[];
201
+ /** The datasets displayed in this graph. */
202
+ datasets: BundleGraphDatasetSpec[];
203
+ /** Metadata for the graph that can be used to diff to another graph. */
204
+ metadata: Map<string, string>;
205
+ }
206
+ /**
207
+ * Allows for displaying a bundle-specific graph.
208
+ */
209
+ interface BundleGraphView {
210
+ /** Destroy the underlying graph view and any associated resources. */
211
+ destroy(): void;
212
+ }
213
+ /**
214
+ * Wrapper around data that can be used to initialize a graph view.
215
+ */
216
+ interface BundleGraphData {
217
+ /** Return a graph view that can be attached to the given canvas element. */
218
+ createGraphView(canvas: HTMLCanvasElement): BundleGraphView;
219
+ }
220
+ /**
221
+ * Describes the model that is contained in this bundle.
222
+ */
223
+ interface ModelSpec {
224
+ /** The size of the model binary, in bytes. */
225
+ modelSizeInBytes: number;
226
+ /** The size of the static data, in bytes. */
227
+ dataSizeInBytes: number;
228
+ /** The map of all input variables in this version of the model. */
229
+ inputVars: Map<VarId, InputVar>;
230
+ /** The map of all output (and static data) variables in this version of the model. */
231
+ outputVars: Map<DatasetKey, OutputVar>;
232
+ /** The map of all variables (both internal and exported) in this version of the model. */
233
+ implVars: Map<DatasetKey, ImplVar>;
234
+ /** The custom input variable aliases defined for this model. */
235
+ inputAliases?: Map<InputAliasName, VarId>;
236
+ /** The custom input variable groups defined for this model. */
237
+ inputGroups?: Map<InputGroupName, InputVar[]>;
238
+ /** The custom dataset (output variable) groups defined for this model. */
239
+ datasetGroups?: Map<DatasetGroupName, DatasetKey[]>;
240
+ /** The start time (year) for the model. */
241
+ startTime?: number;
242
+ /** The end time (year) for the model. */
243
+ endTime?: number;
244
+ /** The specs for the bundled graphs. */
245
+ graphSpecs?: BundleGraphSpec[];
246
+ }
247
+ /**
248
+ * An interface that allows for running the bundled model under different input scenarios
249
+ * and capturing the resulting output data.
250
+ */
251
+ interface BundleModel extends DataSource {
252
+ /** The spec for the bundled model. */
253
+ modelSpec: ModelSpec;
254
+ /**
255
+ * Load the data used to display the graph by running the model with inputs
256
+ * configured for the given scenario.
257
+ */
258
+ getGraphDataForScenario(scenarioSpec: ScenarioSpec, graphId: BundleGraphId): Promise<BundleGraphData>;
259
+ /** Return the links to be displayed for the graph in the given scenario. */
260
+ getGraphLinksForScenario(scenarioSpec: ScenarioSpec, graphId: BundleGraphId): LinkItem[];
261
+ }
262
+ /**
263
+ * Provides access to the model that is contained in this bundle for use in
264
+ * model-check packages.
265
+ */
266
+ interface Bundle {
267
+ /**
268
+ * The version of the bundle. This should be incremented when there is an
269
+ * incompatible change to the bundle format. The model-check tools can use
270
+ * this value to skip tests if two bundles have different version numbers.
271
+ */
272
+ version: number;
273
+ /** The spec for the bundled model. */
274
+ modelSpec: ModelSpec;
275
+ /** Asynchronously initialize the underlying model. */
276
+ initModel(): Promise<BundleModel>;
277
+ }
278
+ /**
279
+ * Associates a name with a `Bundle`.
280
+ */
281
+ interface NamedBundle {
282
+ /** The name of the bundle, for example, "Current" or "Baseline". */
283
+ name: string;
284
+ /** The associated bundle. */
285
+ bundle: Bundle;
286
+ }
287
+ /**
288
+ * Represents a bundle that has had its model initialized.
289
+ */
290
+ interface LoadedBundle {
291
+ /** The name of the bundle, for example, "Current" or "Baseline". */
292
+ name: string;
293
+ /** The version of the bundle. */
294
+ version: number;
295
+ /** The initialized model. */
296
+ model: BundleModel;
297
+ }
298
+
299
+ type CheckDataRequestKey = string;
300
+ /**
301
+ * Coordinates on-demand loading of data used to display a graph representation
302
+ * of a check/predicate.
303
+ */
304
+ declare class CheckDataCoordinator {
305
+ readonly bundleModel: BundleModel;
306
+ private readonly taskQueue;
307
+ constructor(bundleModel: BundleModel);
308
+ requestDataset(requestKey: CheckDataRequestKey, scenarioSpec: ScenarioSpec, datasetKey: DatasetKey, onResponse: (dataset: Dataset) => void): void;
309
+ cancelRequest(key: CheckDataRequestKey): void;
310
+ }
311
+
312
+ type CheckPredicateOp = 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'approx';
313
+
314
+ type CheckPredicateTimeSingle = number;
315
+ type CheckPredicateTimeRange = [number, number];
316
+ interface CheckPredicateTimeOptions {
317
+ after_excl?: number;
318
+ after_incl?: number;
319
+ before_excl?: number;
320
+ before_incl?: number;
321
+ }
322
+ type CheckPredicateTimeSpec = CheckPredicateTimeSingle | CheckPredicateTimeRange | CheckPredicateTimeOptions;
323
+
324
+ interface CheckResultErrorInfo {
325
+ kind: 'unknown-dataset' | 'unknown-input' | 'unknown-input-group' | 'empty-input-group';
326
+ name: string;
327
+ }
328
+ interface CheckResult {
329
+ status: 'passed' | 'failed' | 'error';
330
+ message?: string;
331
+ failValue?: number;
332
+ failOp?: CheckPredicateOp;
333
+ failRefValue?: number;
334
+ failTime?: number;
335
+ errorInfo?: CheckResultErrorInfo;
336
+ }
337
+
338
+ type CheckDatasetError = 'no-matches-for-dataset' | 'no-matches-for-group' | 'no-matches-for-type';
339
+ interface CheckDataset {
340
+ /** The key for the matched dataset; can be undefined if no dataset matched. */
341
+ datasetKey?: DatasetKey;
342
+ /** The name of the matched dataset, or the name associated with the error, if defined. */
343
+ name: string;
344
+ /** The error info if the dataset query failed to match. */
345
+ error?: CheckDatasetError;
346
+ }
347
+
348
+ interface CheckScenarioError {
349
+ kind: 'unknown-input-group' | 'empty-input-group';
350
+ /** The name of the input group that failed to match. */
351
+ name: string;
352
+ }
353
+ interface CheckScenarioInputDesc {
354
+ /** The name of the input. */
355
+ name: string;
356
+ /** The matched input variable; can be undefined if no input matched. */
357
+ inputVar?: InputVar;
358
+ /** The position of the input, if this is a position scenario. */
359
+ position?: InputPosition;
360
+ /** The value of the input, for the given position or explicit value. */
361
+ value?: number;
362
+ }
363
+ interface CheckScenario {
364
+ /** The spec used to configure the model with the matched input(s); can be undefined if input(s) failed to match. */
365
+ spec?: ScenarioSpec;
366
+ /** The name of the associated input group, if any. */
367
+ inputGroupName?: string;
368
+ /** The descriptions of the inputs; if empty, it is an "all inputs" scenario. */
369
+ inputDescs: CheckScenarioInputDesc[];
370
+ /** The error info if the scenario/input query failed to match. */
371
+ error?: CheckScenarioError;
372
+ }
373
+
374
+ /**
375
+ * The key type for data references (in the form `<ScenarioUid::DatasetKey>`).
376
+ */
377
+ type CheckDataRefKey = string;
378
+ /**
379
+ * The scenario and dataset referenced by a particular predicate (for cases
380
+ * where the check is against another dataset rather than a constant value).
381
+ */
382
+ interface CheckDataRef {
383
+ /** The key for the reference; can be undefined if inputs or datasets failed to match. */
384
+ key?: CheckDataRefKey;
385
+ /** The scenario used to generate the referenced dataset. */
386
+ scenario: CheckScenario;
387
+ /** The referenced dataset. */
388
+ dataset: CheckDataset;
389
+ }
390
+
391
+ type CheckKey = number;
392
+
393
+ type CheckStatus = 'passed' | 'failed' | 'error';
394
+ interface CheckPredicateOpConstantRef {
395
+ kind: 'constant';
396
+ value: number;
397
+ }
398
+ interface CheckPredicateOpDataRef {
399
+ kind: 'data';
400
+ dataRef: CheckDataRef;
401
+ }
402
+ type CheckPredicateOpRef = CheckPredicateOpConstantRef | CheckPredicateOpDataRef;
403
+ interface CheckPredicateReport {
404
+ checkKey: CheckKey;
405
+ result: CheckResult;
406
+ opRefs: Map<CheckPredicateOp, CheckPredicateOpRef>;
407
+ opValues: string[];
408
+ time?: CheckPredicateTimeSpec;
409
+ tolerance?: number;
410
+ }
411
+ interface CheckDatasetReport {
412
+ checkDataset: CheckDataset;
413
+ status: CheckStatus;
414
+ predicates: CheckPredicateReport[];
415
+ }
416
+ interface CheckScenarioReport {
417
+ checkScenario: CheckScenario;
418
+ status: CheckStatus;
419
+ datasets: CheckDatasetReport[];
420
+ }
421
+ interface CheckTestReport {
422
+ name: string;
423
+ status: CheckStatus;
424
+ scenarios: CheckScenarioReport[];
425
+ }
426
+ interface CheckGroupReport {
427
+ name: string;
428
+ tests: CheckTestReport[];
429
+ }
430
+ interface CheckReport {
431
+ groups: CheckGroupReport[];
432
+ }
433
+ type StyleFunc = (s: string) => string;
434
+ /**
435
+ * Return a string representation of the given scenario.
436
+ *
437
+ * @param scenario The scenario report.
438
+ * @param bold A function that applies bold styling to a string.
439
+ */
440
+ declare function scenarioMessage(scenario: CheckScenarioReport, bold: StyleFunc): string;
441
+ /**
442
+ * Return a string representation of the given dataset.
443
+ *
444
+ * @param dataset The dataset report.
445
+ * @param bold A function that applies bold styling to a string.
446
+ */
447
+ declare function datasetMessage(dataset: CheckDatasetReport, bold: StyleFunc): string;
448
+ /**
449
+ * Return a string representation of the given predicate.
450
+ *
451
+ * @param predicate The predicate report.
452
+ * @param bold A function that applies bold styling to a string.
453
+ */
454
+ declare function predicateMessage(predicate: CheckPredicateReport, bold: StyleFunc): string;
455
+
456
+ interface CheckOptions {
457
+ /** The strings containing check tests in YAML format. */
458
+ tests: string[];
459
+ }
460
+ interface CheckConfig {
461
+ /** The loaded bundle being checked. */
462
+ bundle: LoadedBundle;
463
+ /** The strings containing check tests in YAML format. */
464
+ tests: string[];
465
+ }
466
+
467
+ /**
468
+ * A simplified/terse version of `CheckPredicateReport` that matches the
469
+ * format of the JSON objects emitted by the CLI in terse mode.
470
+ */
471
+ interface CheckPredicateSummary {
472
+ checkKey: CheckKey;
473
+ result: CheckResult;
474
+ }
475
+ /**
476
+ * A simplified/terse version of `CheckReport` that matches the
477
+ * format of the JSON objects emitted by the CLI in terse mode.
478
+ * This only contains predicate summaries for checks that have a status
479
+ * of 'failed' or 'error'.
480
+ */
481
+ interface CheckSummary {
482
+ predicateSummaries: CheckPredicateSummary[];
483
+ }
484
+ /**
485
+ * Convert a full `CheckReport` to a simplified `CheckSummary` that only includes
486
+ * failed/errored checks.
487
+ *
488
+ * @param checkReport The full check report.
489
+ * @return The converted check summary.
490
+ */
491
+ declare function checkSummaryFromReport(checkReport: CheckReport): CheckSummary;
492
+ /**
493
+ * Convert a simplified `CheckSummary` to a full `CheckReport` that restores the
494
+ * structure of the tests from the given configuration.
495
+ *
496
+ * @param checkConfig The config used to reconstruct the check test structure.
497
+ * @param checkSummary The simplified check summary.
498
+ * @return The converted check report.
499
+ */
500
+ declare function checkReportFromSummary(checkConfig: CheckConfig, checkSummary: CheckSummary): CheckReport | undefined;
501
+
502
+ type ComparisonScenarioId = string;
503
+ type ComparisonScenarioTitle = string;
504
+ type ComparisonScenarioSubtitle = string;
505
+ type ComparisonScenarioInputName = string;
506
+ type ComparisonScenarioInputPosition = 'default' | 'min' | 'max';
507
+ /**
508
+ * Specifies an input that is set to a specific position (default / min / max).
509
+ */
510
+ interface ComparisonScenarioInputAtPositionSpec {
511
+ kind: 'input-at-position';
512
+ /** The requested input name or alias. */
513
+ inputName: ComparisonScenarioInputName;
514
+ /** The requested position of the input. */
515
+ position: ComparisonScenarioInputPosition;
516
+ }
517
+ /**
518
+ * Specifies an input that is set to a specific number value.
519
+ */
520
+ interface ComparisonScenarioInputAtValueSpec {
521
+ kind: 'input-at-value';
522
+ /** The requested input name or alias. */
523
+ inputName: ComparisonScenarioInputName;
524
+ /** The number value of the input. */
525
+ value: number;
526
+ }
527
+ /**
528
+ * A single input setting for a scenario. An input can be set to a specific number value,
529
+ * or it can be set to a "position" (default / min / max).
530
+ */
531
+ type ComparisonScenarioInputSpec = ComparisonScenarioInputAtPositionSpec | ComparisonScenarioInputAtValueSpec;
532
+ /**
533
+ * Specifies a single scenario that sets one or more inputs to a value/position.
534
+ */
535
+ interface ComparisonScenarioWithInputsSpec {
536
+ kind: 'scenario-with-inputs';
537
+ /** The unique identifier for the scenario. */
538
+ id?: ComparisonScenarioId;
539
+ /** The title of the scenario. */
540
+ title?: ComparisonScenarioTitle;
541
+ /** The subtitle of the scenario. */
542
+ subtitle?: ComparisonScenarioSubtitle;
543
+ /** The input settings for this scenario. */
544
+ inputs: ComparisonScenarioInputSpec[];
545
+ }
546
+ /**
547
+ * Specifies a single scenario that configures inputs differently for the two
548
+ * model instances.
549
+ */
550
+ interface ComparisonScenarioWithDistinctInputsSpec {
551
+ kind: 'scenario-with-distinct-inputs';
552
+ /** The unique identifier for the scenario. */
553
+ id?: ComparisonScenarioId;
554
+ /** The title of the scenario. */
555
+ title?: ComparisonScenarioTitle;
556
+ /** The subtitle of the scenario. */
557
+ subtitle?: ComparisonScenarioSubtitle;
558
+ /** The input settings for this scenario when run with the "left" model. */
559
+ inputsL: ComparisonScenarioInputSpec[];
560
+ /** The input settings for this scenario when run with the "right" model. */
561
+ inputsR: ComparisonScenarioInputSpec[];
562
+ }
563
+ /**
564
+ * Specifies a single scenario that sets all available inputs to position.
565
+ */
566
+ interface ComparisonScenarioWithAllInputsSpec {
567
+ kind: 'scenario-with-all-inputs';
568
+ /** The unique identifier for the scenario. */
569
+ id?: ComparisonScenarioId;
570
+ /** The title of the scenario. */
571
+ title?: ComparisonScenarioTitle;
572
+ /** The subtitle of the scenario. */
573
+ subtitle?: ComparisonScenarioSubtitle;
574
+ /** The position that will be used for all available inputs. */
575
+ position: ComparisonScenarioInputPosition;
576
+ }
577
+ /**
578
+ * Special preset that expands to many scenarios:
579
+ * - one scenario with all inputs at their default
580
+ * - two scenarios for each available input:
581
+ * - one scenario with the input at its minimum
582
+ * - one scenario with the input at its maximum
583
+ */
584
+ interface ComparisonScenarioPresetMatrixSpec {
585
+ kind: 'scenario-matrix';
586
+ }
587
+ /**
588
+ * A definition of input scenario(s). A scenario can set one input to a value/position, or it
589
+ * can set multiple inputs to particular values/positions.
590
+ */
591
+ type ComparisonScenarioSpec = ComparisonScenarioWithInputsSpec | ComparisonScenarioWithDistinctInputsSpec | ComparisonScenarioWithAllInputsSpec | ComparisonScenarioPresetMatrixSpec;
592
+ /** A reference to a scenario definition. */
593
+ interface ComparisonScenarioRefSpec {
594
+ kind: 'scenario-ref';
595
+ /** The ID of the scenario that is referenced. */
596
+ scenarioId: ComparisonScenarioId;
597
+ /** The optional title that is used instead of the referenced scenario's title. */
598
+ title?: ComparisonScenarioTitle;
599
+ /** The optional subtitle that is used instead of the referenced scenario's subtitle. */
600
+ subtitle?: ComparisonScenarioSubtitle;
601
+ }
602
+ type ComparisonScenarioGroupId = string;
603
+ type ComparisonScenarioGroupTitle = string;
604
+ /**
605
+ * A definition of a group of input scenarios. Multiple scenarios can be grouped together under a single name, and
606
+ * can later be referenced by group ID in a view definition.
607
+ */
608
+ interface ComparisonScenarioGroupSpec {
609
+ kind: 'scenario-group';
610
+ /** The unique identifier for the group. */
611
+ id?: ComparisonScenarioGroupId;
612
+ /** The title of the group. */
613
+ title: ComparisonScenarioGroupTitle;
614
+ /** The scenarios that are included in this group. */
615
+ scenarios: (ComparisonScenarioSpec | ComparisonScenarioRefSpec)[];
616
+ }
617
+ /** A reference to a scenario group definition. */
618
+ interface ComparisonScenarioGroupRefSpec {
619
+ kind: 'scenario-group-ref';
620
+ /** The ID of the scenario group that is referenced. */
621
+ groupId: ComparisonScenarioGroupId;
622
+ }
623
+ type ComparisonViewTitle = string;
624
+ type ComparisonViewSubtitle = string;
625
+ type ComparisonViewGraphId = string;
626
+ /**
627
+ * Specifies a list of graphs to be shown in a view.
628
+ */
629
+ interface ComparisonViewGraphsArraySpec {
630
+ kind: 'graphs-array';
631
+ /** The array of IDs for graphs to show. */
632
+ graphIds: ComparisonViewGraphId[];
633
+ }
634
+ /**
635
+ * Specifies a preset list of graphs to be shown in a view.
636
+ */
637
+ interface ComparisonViewGraphsPresetSpec {
638
+ kind: 'graphs-preset';
639
+ /** The preset (currently only "all" is supported, which shows all available graphs). */
640
+ preset: 'all';
641
+ }
642
+ /**
643
+ * Specifies a set of graphs to be shown in a view.
644
+ */
645
+ type ComparisonViewGraphsSpec = ComparisonViewGraphsArraySpec | ComparisonViewGraphsPresetSpec;
646
+ /**
647
+ * A definition of a view. A view presents a set of graphs for a single input scenario.
648
+ */
649
+ interface ComparisonViewSpec {
650
+ kind: 'view';
651
+ /** The title of the view. If undefined, the title will be inferred from the scenario. */
652
+ title?: ComparisonViewTitle;
653
+ /** The subtitle of the view. If undefined, the subtitle will be inferred from the scenario. */
654
+ subtitle?: ComparisonViewGroupTitle;
655
+ /** The scenario to be shown in the view. */
656
+ scenarioId: ComparisonScenarioId;
657
+ /** The graphs to be shown for each scenario view. */
658
+ graphs: ComparisonViewGraphsSpec;
659
+ }
660
+ type ComparisonViewGroupTitle = string;
661
+ /**
662
+ * Specifies a view group with an explicit array of view definitions.
663
+ */
664
+ interface ComparisonViewGroupWithViewsSpec {
665
+ kind: 'view-group-with-views';
666
+ /** The title of the group of views. */
667
+ title: ComparisonViewGroupTitle;
668
+ /** The views that are included in this group. */
669
+ views: ComparisonViewSpec[];
670
+ }
671
+ /**
672
+ * Specifies a view group by declaring the scenarios included in the group (one view per scenario), along
673
+ * with a set of graphs that will shown in each view.
674
+ */
675
+ interface ComparisonViewGroupWithScenariosSpec {
676
+ kind: 'view-group-with-scenarios';
677
+ /** The title of the group of views. */
678
+ title: ComparisonViewGroupTitle;
679
+ /** The scenarios to be included (one view will be created for each scenario). */
680
+ scenarios: (ComparisonScenarioRefSpec | ComparisonScenarioGroupRefSpec)[];
681
+ /** The graphs to be shown for each scenario view. */
682
+ graphs: ComparisonViewGraphsSpec;
683
+ }
684
+ /**
685
+ * A definition of a group of views. Multiple related views can be grouped together under a single title
686
+ * to make them easy to distinguish in a report.
687
+ */
688
+ type ComparisonViewGroupSpec = ComparisonViewGroupWithViewsSpec | ComparisonViewGroupWithScenariosSpec;
689
+ /**
690
+ * Contains the scenario and view definitions from one or more sources (JSON/YAML files or manually
691
+ * defined specs).
692
+ */
693
+ interface ComparisonSpecs {
694
+ /** The requested scenarios. */
695
+ scenarios: ComparisonScenarioSpec[];
696
+ /** The requested scenario groups. */
697
+ scenarioGroups: ComparisonScenarioGroupSpec[];
698
+ /** The requested view groups. */
699
+ viewGroups: ComparisonViewGroupSpec[];
700
+ }
701
+ /** A source of comparison scenario and specifications. */
702
+ interface ComparisonSpecsSource {
703
+ kind: 'yaml' | 'json';
704
+ /** The source filename, if known. */
705
+ filename?: string;
706
+ /** A string containing YAML or JSON content. */
707
+ content: string;
708
+ }
709
+
710
+ /** A resolved dataset that is being compared. */
711
+ interface ComparisonDataset {
712
+ kind: 'dataset';
713
+ /** The unique key for the dataset (i.e., output variable or static data). */
714
+ key: DatasetKey;
715
+ /**
716
+ * The resolved output variable from the "left" model that corresponds to this dataset,
717
+ * or undefined if the variable is not defined in the left model.
718
+ */
719
+ outputVarL?: OutputVar;
720
+ /**
721
+ * The resolved output variable from the "right" model that corresponds to this dataset,
722
+ * or undefined if the variable is not defined in the right model.
723
+ */
724
+ outputVarR?: OutputVar;
725
+ }
726
+ /** A unique key for a `ComparisonScenario`, generated internally for use by the library. */
727
+ type ComparisonScenarioKey = string & {
728
+ _brand?: 'ComparisonScenarioKey';
729
+ };
730
+ interface ComparisonResolverUnknownInputError {
731
+ kind: 'unknown-input';
732
+ }
733
+ interface ComparisonResolverInvalidValueError {
734
+ kind: 'invalid-value';
735
+ }
736
+ type ComparisonResolverError = ComparisonResolverUnknownInputError | ComparisonResolverInvalidValueError;
737
+ /** Describes the resolution state for a scenario input relative to a specific model. */
738
+ interface ComparisonScenarioInputState {
739
+ /** The matched input variable; can be undefined if no input matched. */
740
+ inputVar?: InputVar;
741
+ /** The position of the input, if this is a position scenario. */
742
+ position?: InputPosition;
743
+ /** The value of the input, for the given position or explicit value. */
744
+ value?: number;
745
+ /** The error info if the input could not be resolved. */
746
+ error?: ComparisonResolverError;
747
+ }
748
+ /** A scenario input that has been checked against both "left" and "right" model. */
749
+ interface ComparisonScenarioInput {
750
+ /** The requested name of the input. */
751
+ requestedName: string;
752
+ /** The resolved state of the input for the "left" model. */
753
+ stateL: ComparisonScenarioInputState;
754
+ /** The resolved state of the input for the "right" model. */
755
+ stateR: ComparisonScenarioInputState;
756
+ }
757
+ /** A configuration that sets model inputs to specific values. */
758
+ interface ComparisonScenarioInputSettings {
759
+ kind: 'input-settings';
760
+ /** The resolutions for the specified inputs in the scenario. */
761
+ inputs: ComparisonScenarioInput[];
762
+ }
763
+ /** A configuration that sets all inputs in the model to a certain position. */
764
+ interface ComparisonScenarioAllInputsSettings {
765
+ kind: 'all-inputs-settings';
766
+ /** The input position that will be applied to all available inputs. */
767
+ position: InputPosition;
768
+ }
769
+ /**
770
+ * The configuration for an input scenario, either a set of individual input settings, or one
771
+ * that sets all inputs in the model to a certain position.
772
+ */
773
+ type ComparisonScenarioSettings = ComparisonScenarioInputSettings | ComparisonScenarioAllInputsSettings;
774
+ /** A single resolved input scenario. */
775
+ interface ComparisonScenario {
776
+ kind: 'scenario';
777
+ /** The unique key for the scenario, generated internally for use by the library. */
778
+ key: ComparisonScenarioKey;
779
+ /** The unique user-defined identifier for the scenario. */
780
+ id?: ComparisonScenarioId;
781
+ /** The scenario title. */
782
+ title: string;
783
+ /** The scenario subtitle. */
784
+ subtitle?: string;
785
+ /** The resolved settings for the model inputs in this scenario. */
786
+ settings: ComparisonScenarioSettings;
787
+ /** The input scenario used to configure the "left" model, or undefined if data not available. */
788
+ specL?: ScenarioSpec;
789
+ /** The input scenario used to configure the "right" model, or undefined if data not available. */
790
+ specR?: ScenarioSpec;
791
+ }
792
+ /** An unresolved input scenario reference. */
793
+ interface ComparisonUnresolvedScenarioRef {
794
+ kind: 'unresolved-scenario-ref';
795
+ /** The ID of the referenced scenario that could not be resolved. */
796
+ scenarioId: ComparisonScenarioId;
797
+ }
798
+ /** A resolved group of input scenarios. */
799
+ interface ComparisonScenarioGroup {
800
+ kind: 'scenario-group';
801
+ /** The unique identifier for the group. */
802
+ id?: ComparisonScenarioGroupId;
803
+ /** The title of the group. */
804
+ title: ComparisonScenarioGroupTitle;
805
+ /**
806
+ * The scenarios that are included in this group. This includes scenario that were successfully
807
+ * resolved as well as scenario references that could not be resolved.
808
+ */
809
+ scenarios: (ComparisonScenario | ComparisonUnresolvedScenarioRef)[];
810
+ }
811
+ /** An unresolved scenario group reference. */
812
+ interface ComparisonUnresolvedScenarioGroupRef {
813
+ kind: 'unresolved-scenario-group-ref';
814
+ /** The ID of the referenced scenario group that could not be resolved. */
815
+ scenarioGroupId: ComparisonScenarioGroupId;
816
+ }
817
+ /** A resolved view definition. A view presents a set of graphs for a single input scenario. */
818
+ interface ComparisonView {
819
+ kind: 'view';
820
+ /** The title of the view. */
821
+ title: ComparisonViewTitle;
822
+ /** The subtitle of the view. */
823
+ subtitle?: ComparisonViewSubtitle;
824
+ /** The resolved scenario to be shown in the view. */
825
+ scenario: ComparisonScenario;
826
+ /** The graphs to be shown for each scenario view. */
827
+ graphs: 'all' | ComparisonViewGraphId[];
828
+ }
829
+ /** An unresolved view. */
830
+ interface ComparisonUnresolvedView {
831
+ kind: 'unresolved-view';
832
+ /** The requested title of the view, if provided. */
833
+ title?: ComparisonViewTitle;
834
+ /** The requested subtitle of the view, if provided. */
835
+ subtitle?: ComparisonViewSubtitle;
836
+ /** The ID of the referenced scenario that could not be resolved. */
837
+ scenarioId?: ComparisonScenarioId;
838
+ /** The ID of the referenced scenario group that could not be resolved. */
839
+ scenarioGroupId?: ComparisonScenarioGroupId;
840
+ }
841
+ /** A resolved group of compared scenario/graph views. */
842
+ interface ComparisonViewGroup {
843
+ kind: 'view-group';
844
+ /** The title of the group of views. */
845
+ title: ComparisonViewGroupTitle;
846
+ /** The array of resolved (and unresolved) views that are included in this group. */
847
+ views: (ComparisonView | ComparisonUnresolvedView)[];
848
+ }
849
+
850
+ /**
851
+ * Provides access to the set of dataset definitions (`ComparisonDataset` instances) that are used
852
+ * when comparing the two models.
853
+ */
854
+ interface ComparisonDatasets {
855
+ /**
856
+ * Return all `ComparisonDataset` instances that are available for comparisons.
857
+ */
858
+ getAllDatasets(): IterableIterator<ComparisonDataset>;
859
+ /**
860
+ * Return the dataset metadata for the given key.
861
+ *
862
+ * @param datasetKey The key for the dataset.
863
+ */
864
+ getDataset(datasetKey: DatasetKey): ComparisonDataset | undefined;
865
+ /**
866
+ * Return the keys for the datasets that should be compared for the given scenario.
867
+ *
868
+ * @param scenario The scenario definition.
869
+ */
870
+ getDatasetKeysForScenario(scenario: ComparisonScenario): DatasetKey[];
871
+ }
872
+
873
+ interface ComparisonScenarios {
874
+ /**
875
+ * Return all `ComparisonScenario` instances that are available for comparisons.
876
+ */
877
+ getAllScenarios(): IterableIterator<ComparisonScenario>;
878
+ /**
879
+ * Return the scenario definition for the given key.
880
+ *
881
+ * @param key The key for the scenario.
882
+ */
883
+ getScenario(key: ComparisonScenarioKey): ComparisonScenario | undefined;
884
+ }
885
+
886
+ interface ComparisonDatasetOptions {
887
+ /**
888
+ * The mapping of renamed dataset keys (old or "left" name as the map key,
889
+ * new or "right" name as the value).
890
+ */
891
+ renamedDatasetKeys?: Map<DatasetKey, DatasetKey>;
892
+ /**
893
+ * An optional function that allows for limiting the datasets that are compared
894
+ * for a given scenario. By default, all datasets are compared for a given
895
+ * scenario, but if a custom function is provided, it can return a subset of
896
+ * datasets (for example, to omit datasets that are not relevant).
897
+ */
898
+ datasetKeysForScenario?: (allDatasetKeys: DatasetKey[], scenario: ComparisonScenario) => DatasetKey[];
899
+ }
900
+ interface ComparisonOptions {
901
+ /** The left-side ("baseline") bundle being compared. */
902
+ baseline: NamedBundle;
903
+ /**
904
+ * The array of thresholds used to color differences, e.g., [1, 5, 10] will use
905
+ * buckets of 0%, 0-1%, 1-5%, 5-10%, and >10%.
906
+ */
907
+ thresholds: number[];
908
+ /**
909
+ * The requested comparison scenario and view specifications. These can be
910
+ * specified in YAML or JSON files, or using `Spec` objects.
911
+ */
912
+ specs: (ComparisonSpecs | ComparisonSpecsSource)[];
913
+ /** Optional configuration for the datasets that are compared for different scenarios. */
914
+ datasets?: ComparisonDatasetOptions;
915
+ }
916
+ interface ComparisonConfig {
917
+ /** The loaded left-side ("baseline") bundle being compared. */
918
+ bundleL: LoadedBundle;
919
+ /** The loaded right-side ("current") bundle being compared. */
920
+ bundleR: LoadedBundle;
921
+ /**
922
+ * The array of thresholds used to color differences, e.g., [1, 5, 10] will use
923
+ * buckets of 0%, 0-1%, 1-5%, 5-10%, and >10%.
924
+ */
925
+ thresholds: number[];
926
+ /** The set of resolved scenarios that will be compared. */
927
+ scenarios: ComparisonScenarios;
928
+ /** The set of resolved datasets that will be compared. */
929
+ datasets: ComparisonDatasets;
930
+ /** The set of resolved view groups. */
931
+ viewGroups: ComparisonViewGroup[];
932
+ }
933
+
934
+ type ComparisonDataRequestKey = string;
935
+ /**
936
+ * Coordinates loading of data in parallel from two models.
937
+ */
938
+ declare class ComparisonDataCoordinator {
939
+ readonly bundleModelL: BundleModel;
940
+ readonly bundleModelR: BundleModel;
941
+ private readonly taskQueue;
942
+ constructor(bundleModelL: BundleModel, bundleModelR: BundleModel);
943
+ private processDatasetRequest;
944
+ private processGraphDataRequest;
945
+ requestDatasetMaps(requestKey: ComparisonDataRequestKey, scenarioSpecL: ScenarioSpec, scenarioSpecR: ScenarioSpec, datasetKeys: DatasetKey[], onResponse: (datasetMapL?: DatasetMap, datasetMapR?: DatasetMap) => void): void;
946
+ requestGraphData(requestKey: ComparisonDataRequestKey, scenarioSpecL: ScenarioSpec, scenarioSpecR: ScenarioSpec, graphId: BundleGraphId, onResponse: (graphDataL?: BundleGraphData, graphDataR?: BundleGraphData) => void): void;
947
+ cancelRequest(key: ComparisonDataRequestKey): void;
948
+ }
949
+
950
+ interface DiffPoint {
951
+ time: number;
952
+ valueL: number;
953
+ valueR: number;
954
+ }
955
+ type DiffValidity = 'neither' | 'left-only' | 'right-only' | 'both';
956
+ interface DiffReport {
957
+ validity: DiffValidity;
958
+ minValue: number;
959
+ maxValue: number;
960
+ avgDiff: number;
961
+ minDiff: number;
962
+ maxDiff: number;
963
+ maxDiffPoint: DiffPoint;
964
+ }
965
+ declare function diffDatasets(datasetL: Dataset | undefined, datasetR: Dataset | undefined): DiffReport;
966
+
967
+ interface PerfReport {
968
+ readonly minTime: number;
969
+ readonly maxTime: number;
970
+ readonly avgTime: number;
971
+ readonly allTimes: number[];
972
+ }
973
+ declare class PerfStats {
974
+ private readonly times;
975
+ addRun(timeInMillis: number): void;
976
+ toReport(): PerfReport;
977
+ }
978
+
979
+ /**
980
+ * The report for a single comparison test (involving a dataset produced under
981
+ * a specific input scenario). This includes the full `DiffReport`, whereas
982
+ * a `ComparisonTestSummary` only includes the `maxDiff` value.
983
+ */
984
+ interface ComparisonTestReport {
985
+ scenarioKey: ComparisonScenarioKey;
986
+ datasetKey: DatasetKey;
987
+ diffReport: DiffReport;
988
+ }
989
+ /**
990
+ * A simplified/terse version of `ComparisonTestReport` that is used when writing
991
+ * results to a JSON file. The object keys are terse and it only includes the
992
+ * minimum set of fields (only the `maxDiff` value instead of the full `DiffReport`)
993
+ * to keep the file smaller when there are many reported differences.
994
+ */
995
+ interface ComparisonTestSummary {
996
+ /** Short for `scenarioKey`. */
997
+ s: ComparisonScenarioKey;
998
+ /** Short for `datasetKey`. */
999
+ d: DatasetKey;
1000
+ /** Short for `maxDiff`. */
1001
+ md: number;
1002
+ }
1003
+ /**
1004
+ * The roll-up report that contains the results of all individual comparison tests.
1005
+ */
1006
+ interface ComparisonReport {
1007
+ /** The set of all comparison test reports. */
1008
+ testReports: ComparisonTestReport[];
1009
+ /** The perf report for the "left" model. */
1010
+ perfReportL: PerfReport;
1011
+ /** The perf report for the "right" model. */
1012
+ perfReportR: PerfReport;
1013
+ }
1014
+ /**
1015
+ * A simplified/terse version of `ComparisonReport` that only includes the minimum set
1016
+ * of fields needed by the reporting app (to keep the file smaller when there are many
1017
+ * reported differences). This only includes comparison results for which there is
1018
+ * a non-zero `maxDiff` value.
1019
+ */
1020
+ interface ComparisonSummary {
1021
+ /** The simplified set of all terse comparison test summaries. */
1022
+ testSummaries: ComparisonTestSummary[];
1023
+ /** The perf report for the "left" model. */
1024
+ perfReportL: PerfReport;
1025
+ /** The perf report for the "right" model. */
1026
+ perfReportR: PerfReport;
1027
+ }
1028
+
1029
+ type GraphInclusion = 'neither' | 'left-only' | 'right-only' | 'both';
1030
+ interface GraphComparisonMetadataReport {
1031
+ /** The key for the metadata field. */
1032
+ key: string;
1033
+ /** The value of the metadata field in the left bundle. */
1034
+ valueL?: string;
1035
+ /** The value of the metadata field in the right bundle. */
1036
+ valueR?: string;
1037
+ }
1038
+ interface GraphComparisonDatasetReport {
1039
+ /** The dataset key. */
1040
+ datasetKey: DatasetKey;
1041
+ /** The max diff for this dataset. */
1042
+ maxDiff?: number;
1043
+ }
1044
+ interface GraphComparisonReport {
1045
+ /** Indicates which bundles the graph is defined in. */
1046
+ inclusion: GraphInclusion;
1047
+ /** The metadata fields with differences. */
1048
+ metadataReports: GraphComparisonMetadataReport[];
1049
+ /** The datasets with differences. */
1050
+ datasetReports: GraphComparisonDatasetReport[];
1051
+ }
1052
+ /**
1053
+ * Comparison the metadata and datasets for the given graphs.
1054
+ *
1055
+ * @param graphL The graph defined in the left bundle.
1056
+ * @param graphR The graph defined in the right bundle.
1057
+ * @param scenarioKey The key of the scenario used for comparing datasets.
1058
+ * @param testSummaries The set of test summaries from a previous comparison run.
1059
+ */
1060
+ declare function diffGraphs(graphL: BundleGraphSpec | undefined, graphR: BundleGraphSpec | undefined, scenarioKey: ComparisonScenarioKey, testSummaries: ComparisonTestSummary[]): GraphComparisonReport;
1061
+
1062
+ /**
1063
+ * Convert a full `ComparisonReport` to a simplified `ComparisonSummary` that includes
1064
+ * the minimum set of fields needed to keep the file smaller when there are many
1065
+ * reported differences. This only includes comparison results for which there
1066
+ * is a non-zero `maxDiff` value.
1067
+ *
1068
+ * @param comparisonReport The full comparison report.
1069
+ * @return The terse summary.
1070
+ */
1071
+ declare function comparisonSummaryFromReport(comparisonReport: ComparisonReport): ComparisonSummary;
1072
+
1073
+ type ComparisonGroupKind = 'by-dataset' | 'by-scenario';
1074
+ type ComparisonGroupKey = string;
1075
+ /**
1076
+ * A group of comparison test summaries associated with a particular scenario or dataset.
1077
+ */
1078
+ interface ComparisonGroup {
1079
+ /** The kind of group, either 'by-dataset' or 'by-scenario'. */
1080
+ kind: ComparisonGroupKind;
1081
+ /**
1082
+ * The unique key for this group (a `DatasetKey` if grouped by dataset, or a
1083
+ * `ComparisonScenarioKey` if grouped by scenario).
1084
+ */
1085
+ key: ComparisonGroupKey;
1086
+ /** The comparison test summaries for this group. */
1087
+ testSummaries: ComparisonTestSummary[];
1088
+ }
1089
+ /** Describes the "root" or primary item for a group of comparisons. */
1090
+ type ComparisonGroupRoot = ComparisonDataset | ComparisonScenario;
1091
+ /** A summary of scores for a group of comparisons. */
1092
+ interface ComparisonGroupScores {
1093
+ /** The total number of comparisons (sample size) for this group. */
1094
+ totalDiffCount: number;
1095
+ /** The sum of the `maxDiff` values for each threshold bucket. */
1096
+ totalMaxDiffByBucket: number[];
1097
+ /** The number of comparisons that fall into each threshold bucket. */
1098
+ diffCountByBucket: number[];
1099
+ /** The percentage of comparisons that fall into each threshold bucket. */
1100
+ diffPercentByBucket: number[];
1101
+ }
1102
+ /**
1103
+ * A summary of a group of comparisons that includes the resolved scenario/dataset metadata
1104
+ * and score information for the group.
1105
+ */
1106
+ interface ComparisonGroupSummary {
1107
+ /** The metadata for the "root" or primary item for this group of comparisons. */
1108
+ root: ComparisonGroupRoot;
1109
+ /** The group containing the comparison summaries. */
1110
+ group: ComparisonGroup;
1111
+ /** The scores for this group, or undefined if comparisons were not performed for this group. */
1112
+ scores?: ComparisonGroupScores;
1113
+ }
1114
+ /**
1115
+ * Breaks down a set of by-scenario or by-dataset groupings into distinct categories.
1116
+ */
1117
+ interface ComparisonGroupSummariesByCategory {
1118
+ /**
1119
+ * All groups in a map, keyed by "group key" (either a dataset key or scenario key).
1120
+ */
1121
+ allGroupSummaries: Map<ComparisonGroupKey, ComparisonGroupSummary>;
1122
+ /**
1123
+ * Groups with items that have errors (are not valid) for both "left" and "right" models.
1124
+ */
1125
+ withErrors: ComparisonGroupSummary[];
1126
+ /**
1127
+ * Groups with items that are only valid for the "left" model (for example, datasets that
1128
+ * were removed and no longer available in the "right" model).
1129
+ */
1130
+ onlyInLeft: ComparisonGroupSummary[];
1131
+ /**
1132
+ * Groups with items that are only valid for the "right" model (for example, scenarios
1133
+ * for inputs that were added in the "right" model).
1134
+ */
1135
+ onlyInRight: ComparisonGroupSummary[];
1136
+ /**
1137
+ * Groups with one or more comparisons that have non-zero `maxDiff` scores; the groups
1138
+ * will be sorted by `maxDiff`, with higher scores at the front of the array.
1139
+ */
1140
+ withDiffs: ComparisonGroupSummary[];
1141
+ /**
1142
+ * Groups where all comparisons have `maxDiff` scores of zero (no differences between
1143
+ * "left" and "right").
1144
+ */
1145
+ withoutDiffs: ComparisonGroupSummary[];
1146
+ }
1147
+ /**
1148
+ * Rolls up all by-scenario and by-dataset groupings.
1149
+ */
1150
+ interface ComparisonCategorizedResults {
1151
+ /** The full set of by-scenario groupings. */
1152
+ byScenario: ComparisonGroupSummariesByCategory;
1153
+ /** The full set of by-dataset groupings. */
1154
+ byDataset: ComparisonGroupSummariesByCategory;
1155
+ }
1156
+
1157
+ /**
1158
+ * Given a set of terse test summaries (which only includes summaries for tests with non-zero `maxDiff`
1159
+ * scores), restore the full set of summaries and then categorize them.
1160
+ *
1161
+ * @param comparisonConfig The comparison configuration.
1162
+ * @param terseSummaries The set of terse test summaries.
1163
+ */
1164
+ declare function categorizeComparisonTestSummaries(comparisonConfig: ComparisonConfig, terseSummaries: ComparisonTestSummary[]): ComparisonCategorizedResults;
1165
+
1166
+ /**
1167
+ * Additional options that are passed to `getConfigOptions`. These can be used to customize
1168
+ * the `ConfigOptions`, for example, if the `simplifyScenarios` flag is true, a reduced set
1169
+ * of tests can be provided in the `ConfigOptions` so that the tests run faster in a local
1170
+ * development situation.
1171
+ */
1172
+ interface ConfigInitOptions {
1173
+ /** If defined, overrides the displayed name of the baseline ("left") bundle. */
1174
+ bundleNameL?: string;
1175
+ /** If defined, overrides the displayed name of the current ("right") bundle. */
1176
+ bundleNameR?: string;
1177
+ /**
1178
+ * A hint that the user wants tests to run faster. If true, you can return a
1179
+ * configuration that runs a smaller subset of tests than normal.
1180
+ */
1181
+ simplifyScenarios?: boolean;
1182
+ }
1183
+ /**
1184
+ * The user-specified options used by the library to resolve and initialize a `Config` instance.
1185
+ */
1186
+ interface ConfigOptions {
1187
+ /**
1188
+ * The bundle being checked. This bundle will also be compared against the
1189
+ * "baseline" bundle, if `comparison` options are defined.
1190
+ */
1191
+ current: NamedBundle;
1192
+ /**
1193
+ * The model check options.
1194
+ */
1195
+ check: CheckOptions;
1196
+ /**
1197
+ * The model comparison options.
1198
+ */
1199
+ comparison?: ComparisonOptions;
1200
+ }
1201
+ /**
1202
+ * The resolved configuration for check and comparison tests.
1203
+ */
1204
+ interface Config {
1205
+ /** The resolved check test configuration. */
1206
+ check: CheckConfig;
1207
+ /** The resolved comparison test configuration. */
1208
+ comparison?: ComparisonConfig;
1209
+ }
1210
+
1211
+ declare function createConfig(options: ConfigOptions): Promise<Config>;
1212
+
1213
+ declare class PerfRunner {
1214
+ readonly bundleModelL: BundleModel;
1215
+ readonly bundleModelR: BundleModel;
1216
+ private readonly mode;
1217
+ private readonly taskQueue;
1218
+ onComplete?: (reportL: PerfReport, reportR: PerfReport) => void;
1219
+ onError?: (error: Error) => void;
1220
+ constructor(bundleModelL: BundleModel, bundleModelR: BundleModel, mode?: 'serial' | 'parallel');
1221
+ start(): void;
1222
+ }
1223
+
1224
+ /**
1225
+ * The report for a single run of the full check+comparison test suite.
1226
+ */
1227
+ interface SuiteReport {
1228
+ checkReport: CheckReport;
1229
+ comparisonReport?: ComparisonReport;
1230
+ }
1231
+ /**
1232
+ * A simplified/terse version of `SuiteReport` that is used when writing
1233
+ * results to a JSON file. The object keys are terse and it only includes
1234
+ * the minimum set of fields (e.g., only the `maxDiff` value instead of the
1235
+ * full `DiffReport` for each comparison test) to keep the file smaller
1236
+ * when there are many reported differences.
1237
+ */
1238
+ interface SuiteSummary {
1239
+ checkSummary: CheckSummary;
1240
+ comparisonSummary?: ComparisonSummary;
1241
+ }
1242
+
1243
+ type CancelRunSuite = () => void;
1244
+ interface RunSuiteCallbacks {
1245
+ onProgress?: (pct: number) => void;
1246
+ onComplete?: (suiteReport: SuiteReport) => void;
1247
+ onError?: (error: Error) => void;
1248
+ }
1249
+ interface RunSuiteOptions {
1250
+ /** Set to true to reduce the number of scenarios generated for a `matrix`. */
1251
+ simplifyScenarios?: boolean;
1252
+ }
1253
+ /**
1254
+ * Run the full suite of checks and comparisons defined in the given configuration.
1255
+ *
1256
+ * @param config The test suite configuration.
1257
+ * @param callbacks The callbacks that will be notified.
1258
+ * @param options Options to control how the tests are run.
1259
+ * @return A function that will cancel the process when invoked.
1260
+ */
1261
+ declare function runSuite(config: Config, callbacks: RunSuiteCallbacks, options?: RunSuiteOptions): CancelRunSuite;
1262
+
1263
+ /**
1264
+ * Convert a full `SuiteReport` to a simplified `SuiteSummary` that only includes
1265
+ * failed/errored checks or comparisons with differences.
1266
+ *
1267
+ * @param suiteReport The full suite report.
1268
+ * @return The converted suite summary.
1269
+ */
1270
+ declare function suiteSummaryFromReport(suiteReport: SuiteReport): SuiteSummary;
1271
+
1272
+ export { AllInputsSpec, Bundle, BundleGraphData, BundleGraphDatasetSpec, BundleGraphId, BundleGraphSpec, BundleGraphView, BundleModel, CheckDataCoordinator, CheckDataRequestKey, CheckDatasetReport, CheckGroupReport, CheckKey, CheckPredicateOp, CheckPredicateOpConstantRef, CheckPredicateOpDataRef, CheckPredicateOpRef, CheckPredicateReport, CheckPredicateSummary, CheckPredicateTimeOptions, CheckPredicateTimeRange, CheckPredicateTimeSingle, CheckPredicateTimeSpec, CheckReport, CheckResult, CheckResultErrorInfo, CheckScenario, CheckScenarioError, CheckScenarioInputDesc, CheckScenarioReport, CheckStatus, CheckSummary, CheckTestReport, ComparisonCategorizedResults, ComparisonConfig, ComparisonDataCoordinator, ComparisonDataRequestKey, ComparisonDataset, ComparisonDatasetOptions, ComparisonDatasets, ComparisonGroup, ComparisonGroupKey, ComparisonGroupKind, ComparisonGroupRoot, ComparisonGroupScores, ComparisonGroupSummariesByCategory, ComparisonGroupSummary, ComparisonOptions, ComparisonReport, ComparisonResolverError, ComparisonResolverInvalidValueError, ComparisonResolverUnknownInputError, ComparisonScenario, ComparisonScenarioAllInputsSettings, ComparisonScenarioGroup, ComparisonScenarioGroupId, ComparisonScenarioGroupRefSpec, ComparisonScenarioGroupSpec, ComparisonScenarioGroupTitle, ComparisonScenarioId, ComparisonScenarioInput, ComparisonScenarioInputAtPositionSpec, ComparisonScenarioInputAtValueSpec, ComparisonScenarioInputName, ComparisonScenarioInputPosition, ComparisonScenarioInputSettings, ComparisonScenarioInputSpec, ComparisonScenarioInputState, ComparisonScenarioKey, ComparisonScenarioPresetMatrixSpec, ComparisonScenarioRefSpec, ComparisonScenarioSettings, ComparisonScenarioSpec, ComparisonScenarioSubtitle, ComparisonScenarioTitle, ComparisonScenarioWithAllInputsSpec, ComparisonScenarioWithDistinctInputsSpec, ComparisonScenarioWithInputsSpec, ComparisonScenarios, ComparisonSpecs, ComparisonSpecsSource, ComparisonSummary, ComparisonTestReport, ComparisonTestSummary, ComparisonUnresolvedScenarioGroupRef, ComparisonUnresolvedScenarioRef, ComparisonUnresolvedView, ComparisonView, ComparisonViewGraphId, ComparisonViewGraphsArraySpec, ComparisonViewGraphsPresetSpec, ComparisonViewGraphsSpec, ComparisonViewGroup, ComparisonViewGroupSpec, ComparisonViewGroupTitle, ComparisonViewGroupWithScenariosSpec, ComparisonViewGroupWithViewsSpec, ComparisonViewSpec, ComparisonViewSubtitle, ComparisonViewTitle, Config, ConfigInitOptions, ConfigOptions, DataSource, Dataset, DatasetGroupName, DatasetKey, DatasetMap, DatasetsResult, DiffPoint, DiffReport, DiffValidity, Dimension, GraphComparisonDatasetReport, GraphComparisonMetadataReport, GraphComparisonReport, GraphInclusion, ImplVar, InputAliasName, InputGroupName, InputId, InputPosition, InputSetting, InputSettingsSpec, InputVar, LegendItem, LinkItem, LoadedBundle, ModelSpec, NamedBundle, OutputVar, PerfReport, PerfRunner, PerfStats, PositionSetting, RelatedItem, RunSuiteCallbacks, RunSuiteOptions, ScenarioSpec, ScenarioSpecUid, SourceName, Subscript, SuiteReport, SuiteSummary, ValueSetting, VarId, categorizeComparisonTestSummaries, checkReportFromSummary, checkSummaryFromReport, comparisonSummaryFromReport, createConfig, datasetMessage, diffDatasets, diffGraphs, predicateMessage, runSuite, scenarioMessage, suiteSummaryFromReport };