@sdeverywhere/check-core 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-declare type SourceName = string;
-declare type VarId = string;
-declare type ScenarioKey = string;
-declare type ScenarioGroupKey = string;
-declare type DatasetKey = string;
-declare type Dataset = Map<number, number>;
-declare type DatasetMap = Map<DatasetKey, Dataset>;
-
-declare type InputPosition = 'at-default' | 'at-minimum' | 'at-maximum';
+type SourceName = string;
+type VarId = string;
+type DatasetKey = string;
+type Dataset = Map<number, number>;
+type DatasetMap = Map<DatasetKey, Dataset>;
+
+/** A unique identifier for the scenario, derived from its input settings. */
+type ScenarioSpecUid = string;
+type InputPosition = 'at-default' | 'at-minimum' | 'at-maximum';
 interface PositionSetting {
     kind: 'position';
     inputVarId: VarId;
@@ -17,39 +17,18 @@ interface ValueSetting {
     inputVarId: VarId;
     value: number;
 }
-declare type InputSetting = PositionSetting | ValueSetting;
-interface SettingsScenario {
-    kind: 'settings';
-    key: ScenarioKey;
-    groupKey: ScenarioGroupKey;
+type InputSetting = PositionSetting | ValueSetting;
+interface InputSettingsSpec {
+    kind: 'input-settings';
+    uid: ScenarioSpecUid;
     settings: InputSetting[];
 }
-interface AllInputsScenario {
+interface AllInputsSpec {
     kind: 'all-inputs';
-    key: ScenarioKey;
-    groupKey: ScenarioGroupKey;
+    uid: ScenarioSpecUid;
     position: InputPosition;
 }
-declare type Scenario = SettingsScenario | AllInputsScenario;
-declare function positionSetting(inputVarId: VarId, position: InputPosition): InputSetting;
-declare function valueSetting(inputVarId: VarId, value: number): InputSetting;
-declare function settingsScenario(key: ScenarioKey, groupKey: ScenarioGroupKey, settings: InputSetting[]): Scenario;
-declare function inputAtPositionScenario(inputVarId: VarId, groupKey: ScenarioGroupKey, position: InputPosition): Scenario;
-declare function inputAtValueScenario(inputVarId: VarId, groupKey: ScenarioGroupKey, value: number): Scenario;
-declare function allInputsAtPositionScenario(position: InputPosition): Scenario;
-/**
- * Return an array of scenarios that can be used to run the model
- * with a matrix of output/input scenarios.
- *
- * For each output variable, run the model:
- *   - once with all inputs at their default
- *   - once with all inputs at their minimum
- *   - once with all inputs at their maximum
- *   - twice for each input
- *       - once with single input at its minimum
- *       - once with single input at its maximum
- */
-declare function matrixScenarios(inputVarIds: VarId[]): Scenario[];
+type ScenarioSpec = InputSettingsSpec | AllInputsSpec;
 
 interface DatasetsResult {
     /**
@@ -64,7 +43,7 @@ interface DatasetsResult {
 }
 interface DataSource {
     /** Return the datasets that result from running the given scenario. */
-    getDatasetsForScenario(scenario: Scenario, datasetKeys: DatasetKey[]): Promise<DatasetsResult>;
+    getDatasetsForScenario(scenarioSpec: ScenarioSpec, datasetKeys: DatasetKey[]): Promise<DatasetsResult>;
 }
 
 /**
@@ -76,24 +55,58 @@ interface RelatedItem {
     id: string;
     locationPath: string[];
 }
+/** A unique, stable input identifier. */
+type InputId = string;
 /**
  * Holds information about an input variable used in the model.
  */
 interface InputVar {
+    /**
+     * Whether this input is controlled by a continuous range/slider or a discrete on/off switch.
+     * If undefined, 'slider' will be assumed.
+     */
+    kind?: 'slider' | 'switch';
+    /**
+     * A unique, stable identifier string for this input.
+     *
+     * This can be used to identify an input variable in a way that is resilient
+     * to the variable's name being changed between two versions of the model.
+     *
+     * For example, if both the "left" and "right" versions of the model have an
+     * input with an `inputId` of 2, but the variable is called "Variable 2" in
+     * the left and "Variable Two" in the right, the inputs can be correlated and
+     * compared despite the different variable names.
+     */
+    inputId: InputId;
+    /** The variable identifier (typically a simplified/canonical ID, like the form used in SDE). */
     varId: VarId;
+    /** The full variable name as used in the modeling tool. */
     varName: string;
+    /** The default value of the input. */
     defaultValue: number;
+    /** The minimum value of the input. */
     minValue: number;
+    /** The maximum value of the input. */
     maxValue: number;
+    /** The metadata for the related input control. */
     relatedItem?: RelatedItem;
 }
 /**
  * Holds information about an output variable used in the model.
  */
 interface OutputVar {
+    /** The unique dataset key for this variable (it should include `sourceName` and `varId`). */
+    datasetKey: DatasetKey;
+    /**
+     * The source for the variable (e.g., undefined for a normal model output, "Data" for a variable
+     * that is defined in an external data file).
+     */
     sourceName?: SourceName;
+    /** The variable identifier (typically a simplified/canonical ID, like the form used in SDE). */
     varId: VarId;
+    /** The full variable name as used in the modeling tool. */
     varName: string;
+    /** The metadata for the related visuals/graphs in which this variable is used. */
     relatedItems?: RelatedItem[];
 }
 /**
@@ -122,7 +135,7 @@ interface Dimension {
 interface ImplVar {
     /** The variable identifier, as used in SDE. */
     varId: VarId;
-    /** The variable name, as used in Vensim. */
+    /** The variable name, as used in the modeling tool. */
     varName: string;
     /** The variable index, used by SDE to reference the value in the generated model. */
     varIndex: number;
@@ -132,6 +145,12 @@ interface ImplVar {
     varType: string;
 }
 
+/** The human-readable name for a group of inputs. */
+type InputGroupName = string;
+/** The alias name for an input. */
+type InputAliasName = string;
+/** The human-readable name for a group of dataset. */
+type DatasetGroupName = string;
 /**
  * Includes the properties needed to display a legend item in the UI.
  */
@@ -152,7 +171,8 @@ interface LinkItem {
     /** The link content (a URL or text). */
     content: string;
 }
-declare type BundleGraphId = string;
+/** The identifier for a bundle-specific graph. */
+type BundleGraphId = string;
 /**
  * Describes a dataset in a bundle-specific graph.
  */
@@ -211,10 +231,12 @@ interface ModelSpec {
     outputVars: Map<DatasetKey, OutputVar>;
     /** The map of all variables (both internal and exported) in this version of the model. */
     implVars: Map<DatasetKey, ImplVar>;
+    /** The custom input variable aliases defined for this model. */
+    inputAliases?: Map<InputAliasName, VarId>;
     /** The custom input variable groups defined for this model. */
-    inputGroups: Map<string, InputVar[]>;
+    inputGroups?: Map<InputGroupName, InputVar[]>;
     /** The custom dataset (output variable) groups defined for this model. */
-    datasetGroups: Map<string, DatasetKey[]>;
+    datasetGroups?: Map<DatasetGroupName, DatasetKey[]>;
     /** The start time (year) for the model. */
     startTime?: number;
     /** The end time (year) for the model. */
@@ -229,18 +251,13 @@ interface ModelSpec {
 interface BundleModel extends DataSource {
     /** The spec for the bundled model. */
     modelSpec: ModelSpec;
-    /**
-     * Return the set of context graphs to be displayed for the given dataset.  If left
-     * undefined, the set of graphs will be determined using the advertised graph specs.
-     */
-    getGraphsForDataset?(datasetKey: DatasetKey): BundleGraphId[];
     /**
      * Load the data used to display the graph by running the model with inputs
      * configured for the given scenario.
      */
-    getGraphDataForScenario(scenario: Scenario, graphId: BundleGraphId): Promise<BundleGraphData>;
+    getGraphDataForScenario(scenarioSpec: ScenarioSpec, graphId: BundleGraphId): Promise<BundleGraphData>;
     /** Return the links to be displayed for the graph in the given scenario. */
-    getGraphLinksForScenario(scenario: Scenario, graphId: BundleGraphId): LinkItem[];
+    getGraphLinksForScenario(scenarioSpec: ScenarioSpec, graphId: BundleGraphId): LinkItem[];
 }
 /**
  * Provides access to the model that is contained in this bundle for use in
@@ -279,7 +296,7 @@ interface LoadedBundle {
     model: BundleModel;
 }
 
-declare type CheckDataRequestKey = string;
+type CheckDataRequestKey = string;
 /**
  * Coordinates on-demand loading of data used to display a graph representation
  * of a check/predicate.
@@ -288,21 +305,21 @@ declare class CheckDataCoordinator {
     readonly bundleModel: BundleModel;
     private readonly taskQueue;
     constructor(bundleModel: BundleModel);
-    requestDataset(requestKey: CheckDataRequestKey, scenario: Scenario, datasetKey: DatasetKey, onResponse: (dataset: Dataset) => void): void;
+    requestDataset(requestKey: CheckDataRequestKey, scenarioSpec: ScenarioSpec, datasetKey: DatasetKey, onResponse: (dataset: Dataset) => void): void;
     cancelRequest(key: CheckDataRequestKey): void;
 }
 
-declare type CheckPredicateOp = 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'approx';
+type CheckPredicateOp = 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'approx';
 
-declare type CheckPredicateTimeSingle = number;
-declare type CheckPredicateTimeRange = [number, number];
+type CheckPredicateTimeSingle = number;
+type CheckPredicateTimeRange = [number, number];
 interface CheckPredicateTimeOptions {
     after_excl?: number;
     after_incl?: number;
     before_excl?: number;
     before_incl?: number;
 }
-declare type CheckPredicateTimeSpec = CheckPredicateTimeSingle | CheckPredicateTimeRange | CheckPredicateTimeOptions;
+type CheckPredicateTimeSpec = CheckPredicateTimeSingle | CheckPredicateTimeRange | CheckPredicateTimeOptions;
 
 interface CheckResultErrorInfo {
     kind: 'unknown-dataset' | 'unknown-input' | 'unknown-input-group' | 'empty-input-group';
@@ -318,7 +335,7 @@ interface CheckResult {
     errorInfo?: CheckResultErrorInfo;
 }
 
-declare type CheckDatasetError = 'no-matches-for-dataset' | 'no-matches-for-group' | 'no-matches-for-type';
+type CheckDatasetError = 'no-matches-for-dataset' | 'no-matches-for-group' | 'no-matches-for-type';
 interface CheckDataset {
     /** The key for the matched dataset; can be undefined if no dataset matched. */
     datasetKey?: DatasetKey;
@@ -344,8 +361,8 @@ interface CheckScenarioInputDesc {
     value?: number;
 }
 interface CheckScenario {
-    /** The scenario for the matched input(s); can be undefined if input(s) failed to match. */
-    scenario?: Scenario;
+    /** The spec used to configure the model with the matched input(s); can be undefined if input(s) failed to match. */
+    spec?: ScenarioSpec;
     /** The name of the associated input group, if any. */
     inputGroupName?: string;
     /** The descriptions of the inputs; if empty, it is an "all inputs" scenario. */
@@ -355,9 +372,9 @@ interface CheckScenario {
 }
 
 /**
- * The key type for data references (in the form `<ScenarioKey::DatasetKey>`).
+ * The key type for data references (in the form `<ScenarioUid::DatasetKey>`).
  */
-declare type CheckDataRefKey = string;
+type CheckDataRefKey = string;
 /**
  * The scenario and dataset referenced by a particular predicate (for cases
  * where the check is against another dataset rather than a constant value).
@@ -371,9 +388,9 @@ interface CheckDataRef {
     dataset: CheckDataset;
 }
 
-declare type CheckKey = number;
+type CheckKey = number;
 
-declare type CheckStatus = 'passed' | 'failed' | 'error';
+type CheckStatus = 'passed' | 'failed' | 'error';
 interface CheckPredicateOpConstantRef {
     kind: 'constant';
     value: number;
@@ -382,7 +399,7 @@ interface CheckPredicateOpDataRef {
     kind: 'data';
     dataRef: CheckDataRef;
 }
-declare type CheckPredicateOpRef = CheckPredicateOpConstantRef | CheckPredicateOpDataRef;
+type CheckPredicateOpRef = CheckPredicateOpConstantRef | CheckPredicateOpDataRef;
 interface CheckPredicateReport {
     checkKey: CheckKey;
     result: CheckResult;
@@ -413,7 +430,7 @@ interface CheckGroupReport {
 interface CheckReport {
     groups: CheckGroupReport[];
 }
-declare type StyleFunc = (s: string) => string;
+type StyleFunc = (s: string) => string;
 /**
  * Return a string representation of the given scenario.
  *
@@ -478,176 +495,456 @@ declare function checkSummaryFromReport(checkReport: CheckReport): CheckSummary;
  *
  * @param checkConfig The config used to reconstruct the check test structure.
  * @param checkSummary The simplified check summary.
- * @param simplifyScenarios If true, reduce the number of scenarios generated for a `matrix`.
  * @return The converted check report.
  */
-declare function checkReportFromSummary(checkConfig: CheckConfig, checkSummary: CheckSummary, simplifyScenarios: boolean): CheckReport | undefined;
+declare function checkReportFromSummary(checkConfig: CheckConfig, checkSummary: CheckSummary): CheckReport | undefined;
 
+type ComparisonScenarioId = string;
+type ComparisonScenarioTitle = string;
+type ComparisonScenarioSubtitle = string;
+type ComparisonScenarioInputName = string;
+type ComparisonScenarioInputPosition = 'default' | 'min' | 'max';
 /**
- * Describes a scenario/dataset comparison.
+ * Specifies an input that is set to a specific position (default / min / max).
  */
-interface CompareItem {
-    /** The item title. */
-    title: string;
-    /** The item subtitle. */
-    subtitle?: string;
-    /** The scenario used for comparison. */
-    scenario: Scenario;
-    /** The key for the datasets being compared. */
-    datasetKey: DatasetKey;
+interface ComparisonScenarioInputAtPositionSpec {
+    kind: 'input-at-position';
+    /** The requested input name or alias. */
+    inputName: ComparisonScenarioInputName;
+    /** The requested position of the input. */
+    position: ComparisonScenarioInputPosition;
 }
 /**
- * The title and subtitle info for a group of comparisons.
+ * Specifies an input that is set to a specific number value.
  */
-interface CompareGroupInfo {
-    /** The group title. */
-    title: string;
-    /** The group subtitle. */
-    subtitle?: string;
-    /** The related items (e.g. graphs or sliders) for the group. */
-    relatedItems: RelatedItem[];
+interface ComparisonScenarioInputAtValueSpec {
+    kind: 'input-at-value';
+    /** The requested input name or alias. */
+    inputName: ComparisonScenarioInputName;
+    /** The number value of the input. */
+    value: number;
 }
 /**
- * Describes a group of comparisons.  The results can be grouped either
- * by dataset or by scenario.
+ * A single input setting for a scenario.  An input can be set to a specific number value,
+ * or it can be set to a "position" (default / min / max).
  */
-interface CompareGroup {
-    /** The group title/subtitle info. */
-    info: CompareGroupInfo;
-    /** The items in the group. */
-    items: CompareItem[];
+type ComparisonScenarioInputSpec = ComparisonScenarioInputAtPositionSpec | ComparisonScenarioInputAtValueSpec;
+/**
+ * Specifies a single scenario that sets one or more inputs to a value/position.
+ */
+interface ComparisonScenarioWithInputsSpec {
+    kind: 'scenario-with-inputs';
+    /** The unique identifier for the scenario. */
+    id?: ComparisonScenarioId;
+    /** The title of the scenario. */
+    title?: ComparisonScenarioTitle;
+    /** The subtitle of the scenario. */
+    subtitle?: ComparisonScenarioSubtitle;
+    /** The input settings for this scenario. */
+    inputs: ComparisonScenarioInputSpec[];
 }
-
 /**
- * The variable/source name info associated with a dataset.
+ * Specifies a single scenario that configures inputs differently for the two
+ * model instances.
  */
-interface DatasetInfo {
-    /** The variable name. */
-    varName: string;
-    /** The new variable name, if it was renamed. */
-    newVarName?: string;
-    /** The source name. */
-    sourceName?: string;
-    /** The new source name, if it was renamed. */
-    newSourceName?: string;
-    /** The related items (e.g. graphs) for the dataset. */
-    relatedItems: RelatedItem[];
+interface ComparisonScenarioWithDistinctInputsSpec {
+    kind: 'scenario-with-distinct-inputs';
+    /** The unique identifier for the scenario. */
+    id?: ComparisonScenarioId;
+    /** The title of the scenario. */
+    title?: ComparisonScenarioTitle;
+    /** The subtitle of the scenario. */
+    subtitle?: ComparisonScenarioSubtitle;
+    /** The input settings for this scenario when run with the "left" model. */
+    inputsL: ComparisonScenarioInputSpec[];
+    /** The input settings for this scenario when run with the "right" model. */
+    inputsR: ComparisonScenarioInputSpec[];
+}
+/**
+ * Specifies a single scenario that sets all available inputs to position.
+ */
+interface ComparisonScenarioWithAllInputsSpec {
+    kind: 'scenario-with-all-inputs';
+    /** The unique identifier for the scenario. */
+    id?: ComparisonScenarioId;
+    /** The title of the scenario. */
+    title?: ComparisonScenarioTitle;
+    /** The subtitle of the scenario. */
+    subtitle?: ComparisonScenarioSubtitle;
+    /** The position that will be used for all available inputs. */
+    position: ComparisonScenarioInputPosition;
+}
+/**
+ * Special preset that expands to many scenarios:
+ * - one scenario with all inputs at their default
+ * - two scenarios for each available input:
+ *     - one scenario with the input at its minimum
+ *     - one scenario with the input at its maximum
+ */
+interface ComparisonScenarioPresetMatrixSpec {
+    kind: 'scenario-matrix';
+}
+/**
+ * A definition of input scenario(s).  A scenario can set one input to a value/position, or it
+ * can set multiple inputs to particular values/positions.
+ */
+type ComparisonScenarioSpec = ComparisonScenarioWithInputsSpec | ComparisonScenarioWithDistinctInputsSpec | ComparisonScenarioWithAllInputsSpec | ComparisonScenarioPresetMatrixSpec;
+/** A reference to a scenario definition. */
+interface ComparisonScenarioRefSpec {
+    kind: 'scenario-ref';
+    /** The ID of the scenario that is referenced. */
+    scenarioId: ComparisonScenarioId;
+    /** The optional title that is used instead of the referenced scenario's title. */
+    title?: ComparisonScenarioTitle;
+    /** The optional subtitle that is used instead of the referenced scenario's subtitle. */
+    subtitle?: ComparisonScenarioSubtitle;
+}
+type ComparisonScenarioGroupId = string;
+type ComparisonScenarioGroupTitle = string;
+/**
+ * A definition of a group of input scenarios.  Multiple scenarios can be grouped together under a single name, and
+ * can later be referenced by group ID in a view definition.
+ */
+interface ComparisonScenarioGroupSpec {
+    kind: 'scenario-group';
+    /** The unique identifier for the group. */
+    id?: ComparisonScenarioGroupId;
+    /** The title of the group. */
+    title: ComparisonScenarioGroupTitle;
+    /** The scenarios that are included in this group. */
+    scenarios: (ComparisonScenarioSpec | ComparisonScenarioRefSpec)[];
+}
+/** A reference to a scenario group definition. */
+interface ComparisonScenarioGroupRefSpec {
+    kind: 'scenario-group-ref';
+    /** The ID of the scenario group that is referenced. */
+    groupId: ComparisonScenarioGroupId;
+}
+type ComparisonViewTitle = string;
+type ComparisonViewSubtitle = string;
+type ComparisonViewGraphId = string;
+/**
+ * Specifies a list of graphs to be shown in a view.
+ */
+interface ComparisonViewGraphsArraySpec {
+    kind: 'graphs-array';
+    /** The array of IDs for graphs to show. */
+    graphIds: ComparisonViewGraphId[];
+}
+/**
+ * Specifies a preset list of graphs to be shown in a view.
+ */
+interface ComparisonViewGraphsPresetSpec {
+    kind: 'graphs-preset';
+    /** The preset (currently only "all" is supported, which shows all available graphs). */
+    preset: 'all';
+}
+/**
+ * Specifies a set of graphs to be shown in a view.
+ */
+type ComparisonViewGraphsSpec = ComparisonViewGraphsArraySpec | ComparisonViewGraphsPresetSpec;
+/**
+ * A definition of a view.  A view presents a set of graphs for a single input scenario.
+ */
+interface ComparisonViewSpec {
+    kind: 'view';
+    /** The title of the view.  If undefined, the title will be inferred from the scenario. */
+    title?: ComparisonViewTitle;
+    /** The subtitle of the view.  If undefined, the subtitle will be inferred from the scenario. */
+    subtitle?: ComparisonViewGroupTitle;
+    /** The scenario to be shown in the view. */
+    scenarioId: ComparisonScenarioId;
+    /** The graphs to be shown for each scenario view. */
+    graphs: ComparisonViewGraphsSpec;
+}
+type ComparisonViewGroupTitle = string;
+/**
+ * Specifies a view group with an explicit array of view definitions.
+ */
+interface ComparisonViewGroupWithViewsSpec {
+    kind: 'view-group-with-views';
+    /** The title of the group of views. */
+    title: ComparisonViewGroupTitle;
+    /** The views that are included in this group. */
+    views: ComparisonViewSpec[];
+}
+/**
+ * Specifies a view group by declaring the scenarios included in the group (one view per scenario), along
+ * with a set of graphs that will shown in each view.
+ */
+interface ComparisonViewGroupWithScenariosSpec {
+    kind: 'view-group-with-scenarios';
+    /** The title of the group of views. */
+    title: ComparisonViewGroupTitle;
+    /** The scenarios to be included (one view will be created for each scenario). */
+    scenarios: (ComparisonScenarioRefSpec | ComparisonScenarioGroupRefSpec)[];
+    /** The graphs to be shown for each scenario view. */
+    graphs: ComparisonViewGraphsSpec;
 }
 /**
- * The human-readable title and subtitle for a scenario.
+ * A definition of a group of views.  Multiple related views can be grouped together under a single title
+ * to make them easy to distinguish in a report.
  */
-interface ScenarioInfo {
+type ComparisonViewGroupSpec = ComparisonViewGroupWithViewsSpec | ComparisonViewGroupWithScenariosSpec;
+/**
+ * Contains the scenario and view definitions from one or more sources (JSON/YAML files or manually
+ * defined specs).
+ */
+interface ComparisonSpecs {
+    /** The requested scenarios. */
+    scenarios: ComparisonScenarioSpec[];
+    /** The requested scenario groups. */
+    scenarioGroups: ComparisonScenarioGroupSpec[];
+    /** The requested view groups. */
+    viewGroups: ComparisonViewGroupSpec[];
+}
+/** A source of comparison scenario and specifications. */
+interface ComparisonSpecsSource {
+    kind: 'yaml' | 'json';
+    /** The source filename, if known. */
+    filename?: string;
+    /** A string containing YAML or JSON content. */
+    content: string;
+}
+
+/** A resolved dataset that is being compared. */
+interface ComparisonDataset {
+    kind: 'dataset';
+    /** The unique key for the dataset (i.e., output variable or static data). */
+    key: DatasetKey;
+    /**
+     * The resolved output variable from the "left" model that corresponds to this dataset,
+     * or undefined if the variable is not defined in the left model.
+     */
+    outputVarL?: OutputVar;
+    /**
+     * The resolved output variable from the "right" model that corresponds to this dataset,
+     * or undefined if the variable is not defined in the right model.
+     */
+    outputVarR?: OutputVar;
+}
+/** A unique key for a `ComparisonScenario`, generated internally for use by the library. */
+type ComparisonScenarioKey = string & {
+    _brand?: 'ComparisonScenarioKey';
+};
+interface ComparisonResolverUnknownInputError {
+    kind: 'unknown-input';
+}
+interface ComparisonResolverInvalidValueError {
+    kind: 'invalid-value';
+}
+type ComparisonResolverError = ComparisonResolverUnknownInputError | ComparisonResolverInvalidValueError;
+/** Describes the resolution state for a scenario input relative to a specific model. */
+interface ComparisonScenarioInputState {
+    /** The matched input variable; can be undefined if no input matched. */
+    inputVar?: InputVar;
+    /** The position of the input, if this is a position scenario. */
+    position?: InputPosition;
+    /** The value of the input, for the given position or explicit value. */
+    value?: number;
+    /** The error info if the input could not be resolved. */
+    error?: ComparisonResolverError;
+}
+/** A scenario input that has been checked against both "left" and "right" model. */
+interface ComparisonScenarioInput {
+    /** The requested name of the input. */
+    requestedName: string;
+    /** The resolved state of the input for the "left" model. */
+    stateL: ComparisonScenarioInputState;
+    /** The resolved state of the input for the "right" model. */
+    stateR: ComparisonScenarioInputState;
+}
+/** A configuration that sets model inputs to specific values. */
+interface ComparisonScenarioInputSettings {
+    kind: 'input-settings';
+    /** The resolutions for the specified inputs in the scenario. */
+    inputs: ComparisonScenarioInput[];
+}
+/** A configuration that sets all inputs in the model to a certain position. */
+interface ComparisonScenarioAllInputsSettings {
+    kind: 'all-inputs-settings';
+    /** The input position that will be applied to all available inputs. */
+    position: InputPosition;
+}
+/**
+ * The configuration for an input scenario, either a set of individual input settings, or one
+ * that sets all inputs in the model to a certain position.
+ */
+type ComparisonScenarioSettings = ComparisonScenarioInputSettings | ComparisonScenarioAllInputsSettings;
+/** A single resolved input scenario. */
+interface ComparisonScenario {
+    kind: 'scenario';
+    /** The unique key for the scenario, generated internally for use by the library. */
+    key: ComparisonScenarioKey;
+    /** The unique user-defined identifier for the scenario. */
+    id?: ComparisonScenarioId;
     /** The scenario title. */
     title: string;
     /** The scenario subtitle. */
     subtitle?: string;
+    /** The resolved settings for the model inputs in this scenario. */
+    settings: ComparisonScenarioSettings;
+    /** The input scenario used to configure the "left" model, or undefined if data not available. */
+    specL?: ScenarioSpec;
+    /** The input scenario used to configure the "right" model, or undefined if data not available. */
+    specR?: ScenarioSpec;
+}
+/** An unresolved input scenario reference. */
+interface ComparisonUnresolvedScenarioRef {
+    kind: 'unresolved-scenario-ref';
+    /** The ID of the referenced scenario that could not be resolved. */
+    scenarioId: ComparisonScenarioId;
+}
+/** A resolved group of input scenarios. */
+interface ComparisonScenarioGroup {
+    kind: 'scenario-group';
+    /** The unique identifier for the group. */
+    id?: ComparisonScenarioGroupId;
+    /** The title of the group. */
+    title: ComparisonScenarioGroupTitle;
     /**
-     * The position of the scenario when displayed in a row.  Typically, 0 means
-     * "left", 1 means "middle", and so on.
+     * The scenarios that are included in this group.  This includes scenario that were successfully
+     * resolved as well as scenario references that could not be resolved.
      */
-    position: number;
+    scenarios: (ComparisonScenario | ComparisonUnresolvedScenarioRef)[];
+}
+/** An unresolved scenario group reference. */
+interface ComparisonUnresolvedScenarioGroupRef {
+    kind: 'unresolved-scenario-group-ref';
+    /** The ID of the referenced scenario group that could not be resolved. */
+    scenarioGroupId: ComparisonScenarioGroupId;
+}
+/** A resolved view definition.  A view presents a set of graphs for a single input scenario. */
+interface ComparisonView {
+    kind: 'view';
+    /** The title of the view. */
+    title: ComparisonViewTitle;
+    /** The subtitle of the view. */
+    subtitle?: ComparisonViewSubtitle;
+    /** The resolved scenario to be shown in the view. */
+    scenario: ComparisonScenario;
+    /** The graphs to be shown for each scenario view. */
+    graphs: 'all' | ComparisonViewGraphId[];
+}
+/** An unresolved view. */
+interface ComparisonUnresolvedView {
+    kind: 'unresolved-view';
+    /** The requested title of the view, if provided. */
+    title?: ComparisonViewTitle;
+    /** The requested subtitle of the view, if provided. */
+    subtitle?: ComparisonViewSubtitle;
+    /** The ID of the referenced scenario that could not be resolved. */
+    scenarioId?: ComparisonScenarioId;
+    /** The ID of the referenced scenario group that could not be resolved. */
+    scenarioGroupId?: ComparisonScenarioGroupId;
+}
+/** A resolved group of compared scenario/graph views. */
+interface ComparisonViewGroup {
+    kind: 'view-group';
+    /** The title of the group of views. */
+    title: ComparisonViewGroupTitle;
+    /** The array of resolved (and unresolved) views that are included in this group. */
+    views: (ComparisonView | ComparisonUnresolvedView)[];
 }
 
 /**
- * Provides access to the set of scenarios that are used when comparing the two models.
+ * Provides access to the set of dataset definitions (`ComparisonDataset` instances) that are used
+ * when comparing the two models.
  */
-interface CompareScenarios {
+interface ComparisonDatasets {
     /**
-     * Return an array containing all configured scenarios.
+     * Return all `ComparisonDataset` instances that are available for comparisons.
      */
-    getScenarios(): Scenario[];
+    getAllDatasets(): IterableIterator<ComparisonDataset>;
     /**
-     * Return the scenario for the given key.
+     * Return the dataset metadata for the given key.
      *
-     * @param scenarioKey The key for the scenario.
+     * @param datasetKey The key for the dataset.
      */
-    getScenario(scenarioKey: ScenarioKey): Scenario | undefined;
+    getDataset(datasetKey: DatasetKey): ComparisonDataset | undefined;
     /**
-     * Return the group info for the given group key.
+     * Return the keys for the datasets that should be compared for the given scenario.
      *
-     * @param groupKey The scenario group key.
+     * @param scenario The scenario definition.
      */
-    getScenarioGroupInfo(groupKey: ScenarioGroupKey): CompareGroupInfo | undefined;
+    getDatasetKeysForScenario(scenario: ComparisonScenario): DatasetKey[];
+}
+
+interface ComparisonScenarios {
     /**
-     * Return the title/subtitle info for the given scenario.
-     *
-     * Note that the given `groupKey` could be different than `scenario.groupKey`.  This
-     * will be the case for the "all inputs at default" item that is included in each
-     * row in the detail view for reference purposes.  The provided `groupKey` will be
-     * used to customize the title and subtitle for that item (for example, it will show
-     * the default value of the input associated with the row).
+     * Return all `ComparisonScenario` instances that are available for comparisons.
+     */
+    getAllScenarios(): IterableIterator<ComparisonScenario>;
+    /**
+     * Return the scenario definition for the given key.
      *
-     * @param scenario The scenario to be displayed.
-     * @param groupKey The key for the group in which the scenario will be displayed.
+     * @param key The key for the scenario.
      */
-    getScenarioInfo(scenario: Scenario, groupKey: ScenarioGroupKey): ScenarioInfo | undefined;
+    getScenario(key: ComparisonScenarioKey): ComparisonScenario | undefined;
 }
-/**
- * Provides access to the set of datasets that are configured for comparison.
- */
-interface CompareDatasets {
-    /** The mapping of renamed dataset keys. */
-    renamedDatasetKeys?: Map<DatasetKey, DatasetKey>;
+
+interface ComparisonDatasetOptions {
     /**
-     * Return the keys for the datasets that should be compared for the given scenario.
-     *
-     * @param scenario The scenario.
+     * The mapping of renamed dataset keys (old or "left" name as the map key,
+     * new or "right" name as the value).
      */
-    getDatasetKeysForScenario(scenario: Scenario): DatasetKey[];
+    renamedDatasetKeys?: Map<DatasetKey, DatasetKey>;
     /**
-     * Return the dataset info for the given key.
+     * An optional function that allows for limiting the datasets that are compared
+     * for a given scenario.  By default, all datasets are compared for a given
+     * scenario, but if a custom function is provided, it can return a subset of
+     * datasets (for example, to omit datasets that are not relevant).
      */
-    getDatasetInfo(datasetKey: DatasetKey): DatasetInfo | undefined;
+    datasetKeysForScenario?: (allDatasetKeys: DatasetKey[], scenario: ComparisonScenario) => DatasetKey[];
 }
-interface CompareOptions {
+interface ComparisonOptions {
+    /** The left-side ("baseline") bundle being compared. */
     baseline: NamedBundle;
+    /**
+     * The array of thresholds used to color differences, e.g., [1, 5, 10] will use
+     * buckets of 0%, 0-1%, 1-5%, 5-10%, and >10%.
+     */
     thresholds: number[];
-    scenarios: CompareScenarios;
-    datasets: CompareDatasets;
+    /**
+     * The requested comparison scenario and view specifications.  These can be
+     * specified in YAML or JSON files, or using `Spec` objects.
+     */
+    specs: (ComparisonSpecs | ComparisonSpecsSource)[];
+    /** Optional configuration for the datasets that are compared for different scenarios. */
+    datasets?: ComparisonDatasetOptions;
 }
-interface CompareConfig {
+interface ComparisonConfig {
+    /** The loaded left-side ("baseline") bundle being compared. */
     bundleL: LoadedBundle;
+    /** The loaded right-side ("current") bundle being compared. */
     bundleR: LoadedBundle;
+    /**
+     * The array of thresholds used to color differences, e.g., [1, 5, 10] will use
+     * buckets of 0%, 0-1%, 1-5%, 5-10%, and >10%.
+     */
     thresholds: number[];
-    scenarios: CompareScenarios;
-    datasets: CompareDatasets;
+    /** The set of resolved scenarios that will be compared. */
+    scenarios: ComparisonScenarios;
+    /** The set of resolved datasets that will be compared. */
+    datasets: ComparisonDatasets;
+    /** The set of resolved view groups. */
+    viewGroups: ComparisonViewGroup[];
 }
 
-declare type CompareDataRequestKey = string;
+type ComparisonDataRequestKey = string;
 /**
  * Coordinates loading of data in parallel from two models.
  */
-declare class CompareDataCoordinator {
+declare class ComparisonDataCoordinator {
     readonly bundleModelL: BundleModel;
     readonly bundleModelR: BundleModel;
     private readonly taskQueue;
     constructor(bundleModelL: BundleModel, bundleModelR: BundleModel);
-    requestDatasetMaps(requestKey: CompareDataRequestKey, scenario: Scenario, datasetKeys: DatasetKey[], onResponse: (datasetMapL: DatasetMap, datasetMapR: DatasetMap) => void): void;
-    requestGraphData(requestKey: CompareDataRequestKey, bundle: 'left' | 'right', scenario: Scenario, graphId: BundleGraphId, onResponse: (graphData: BundleGraphData) => void): void;
-    cancelRequest(key: CompareDataRequestKey): void;
-}
-
-interface PerfReport {
-    readonly minTime: number;
-    readonly maxTime: number;
-    readonly avgTime: number;
-    readonly allTimes: number[];
-}
-declare class PerfStats {
-    private readonly times;
-    addRun(timeInMillis: number): void;
-    toReport(): PerfReport;
-}
-
-interface CompareDatasetReport {
-    scenarioKey: ScenarioKey;
-    datasetKey: DatasetKey;
-    diffReport: DiffReport;
-}
-interface CompareReport {
-    datasetReports: CompareDatasetReport[];
-    perfReportL: PerfReport;
-    perfReportR: PerfReport;
+    private processDatasetRequest;
+    private processGraphDataRequest;
+    requestDatasetMaps(requestKey: ComparisonDataRequestKey, scenarioSpecL: ScenarioSpec, scenarioSpecR: ScenarioSpec, datasetKeys: DatasetKey[], onResponse: (datasetMapL?: DatasetMap, datasetMapR?: DatasetMap) => void): void;
+    requestGraphData(requestKey: ComparisonDataRequestKey, scenarioSpecL: ScenarioSpec, scenarioSpecR: ScenarioSpec, graphId: BundleGraphId, onResponse: (graphDataL?: BundleGraphData, graphDataR?: BundleGraphData) => void): void;
+    cancelRequest(key: ComparisonDataRequestKey): void;
 }
 
 interface DiffPoint {
@@ -655,7 +952,7 @@ interface DiffPoint {
     valueL: number;
     valueR: number;
 }
-declare type DiffValidity = 'neither' | 'left-only' | 'right-only' | 'both';
+type DiffValidity = 'neither' | 'left-only' | 'right-only' | 'both';
 interface DiffReport {
     validity: DiffValidity;
     minValue: number;
@@ -666,43 +963,71 @@ interface DiffReport {
     maxDiffPoint: DiffPoint;
 }
 declare function diffDatasets(datasetL: Dataset | undefined, datasetR: Dataset | undefined): DiffReport;
-declare function compareDatasets(scenarioKey: ScenarioKey, datasetKey: DatasetKey, datasetMapL: DatasetMap, datasetMapR: DatasetMap): CompareDatasetReport;
+
+interface PerfReport {
+    readonly minTime: number;
+    readonly maxTime: number;
+    readonly avgTime: number;
+    readonly allTimes: number[];
+}
+declare class PerfStats {
+    private readonly times;
+    addRun(timeInMillis: number): void;
+    toReport(): PerfReport;
+}
 
 /**
- * A simplified/terse version of `CompareDatasetReport` that matches the
- * format of the JSON objects emitted by the CLI in terse mode.
- * The object keys are terse and it only includes the minimum set of fields
+ * The report for a single comparison test (involving a dataset produced under
+ * a specific input scenario).  This includes the full `DiffReport`, whereas
+ * a `ComparisonTestSummary` only includes the `maxDiff` value.
+ */
+interface ComparisonTestReport {
+    scenarioKey: ComparisonScenarioKey;
+    datasetKey: DatasetKey;
+    diffReport: DiffReport;
+}
+/**
+ * A simplified/terse version of `ComparisonTestReport` that is used when writing
+ * results to a JSON file.  The object keys are terse and it only includes the
+ * minimum set of fields (only the `maxDiff` value instead of the full `DiffReport`)
  * to keep the file smaller when there are many reported differences.
  */
-interface CompareDatasetSummary {
+interface ComparisonTestSummary {
     /** Short for `scenarioKey`. */
-    s: ScenarioKey;
+    s: ComparisonScenarioKey;
     /** Short for `datasetKey`. */
     d: DatasetKey;
     /** Short for `maxDiff`. */
     md: number;
 }
 /**
- * A simplified/terse version of `CompareReport` that matches the
- * format of the JSON objects emitted by the CLI in terse mode.
+ * The roll-up report that contains the results of all individual comparison tests.
  */
-interface CompareSummary {
-    datasetSummaries: CompareDatasetSummary[];
+interface ComparisonReport {
+    /** The set of all comparison test reports. */
+    testReports: ComparisonTestReport[];
+    /** The perf report for the "left" model. */
     perfReportL: PerfReport;
+    /** The perf report for the "right" model. */
     perfReportR: PerfReport;
 }
 /**
- * Convert a full `CompareReport` to a simplified `CompareSummary` that includes
- * the minimum set of fields needed to keep the file smaller when there are many
- * reported differences.
- *
- * @param compareReport The full compare report.
- * @return The converted compare summary.
+ * A simplified/terse version of `ComparisonReport` that only includes the minimum set
+ * of fields needed by the reporting app (to keep the file smaller when there are many
+ * reported differences).  This only includes comparison results for which there is
+ * a non-zero `maxDiff` value.
  */
-declare function compareSummaryFromReport(compareReport: CompareReport): CompareSummary;
+interface ComparisonSummary {
+    /** The simplified set of all terse comparison test summaries. */
+    testSummaries: ComparisonTestSummary[];
+    /** The perf report for the "left" model. */
+    perfReportL: PerfReport;
+    /** The perf report for the "right" model. */
+    perfReportR: PerfReport;
+}
 
-declare type GraphInclusion = 'neither' | 'left-only' | 'right-only' | 'both';
-interface GraphMetadataReport {
+type GraphInclusion = 'neither' | 'left-only' | 'right-only' | 'both';
+interface GraphComparisonMetadataReport {
     /** The key for the metadata field. */
     key: string;
     /** The value of the metadata field in the left bundle. */
@@ -710,146 +1035,180 @@ interface GraphMetadataReport {
     /** The value of the metadata field in the right bundle. */
     valueR?: string;
 }
-interface GraphDatasetReport {
+interface GraphComparisonDatasetReport {
     /** The dataset key. */
     datasetKey: DatasetKey;
     /** The max diff for this dataset. */
     maxDiff?: number;
 }
-interface GraphReport {
+interface GraphComparisonReport {
     /** Indicates which bundles the graph is defined in. */
     inclusion: GraphInclusion;
     /** The metadata fields with differences. */
-    metadataReports: GraphMetadataReport[];
+    metadataReports: GraphComparisonMetadataReport[];
     /** The datasets with differences. */
-    datasetReports: GraphDatasetReport[];
+    datasetReports: GraphComparisonDatasetReport[];
 }
 /**
- * Compare the metadata and datasets for the given graphs.
+ * Comparison the metadata and datasets for the given graphs.
  *
  * @param graphL The graph defined in the left bundle.
  * @param graphR The graph defined in the right bundle.
- * @param scenarioKey The scenario used for comparing datasets.
- * @param datasetSummaries The set of summaries from a previous comparison run.
+ * @param scenarioKey The key of the scenario used for comparing datasets.
+ * @param testSummaries The set of test summaries from a previous comparison run.
  */
-declare function diffGraphs(graphL: BundleGraphSpec | undefined, graphR: BundleGraphSpec | undefined, scenarioKey: ScenarioKey, datasetSummaries: CompareDatasetSummary[]): GraphReport;
+declare function diffGraphs(graphL: BundleGraphSpec | undefined, graphR: BundleGraphSpec | undefined, scenarioKey: ComparisonScenarioKey, testSummaries: ComparisonTestSummary[]): GraphComparisonReport;
 
-interface ConfigOptions {
+/**
+ * Convert a full `ComparisonReport` to a simplified `ComparisonSummary` that includes
+ * the minimum set of fields needed to keep the file smaller when there are many
+ * reported differences.  This only includes comparison results for which there
+ * is a non-zero `maxDiff` value.
+ *
+ * @param comparisonReport The full comparison report.
+ * @return The terse summary.
+ */
+declare function comparisonSummaryFromReport(comparisonReport: ComparisonReport): ComparisonSummary;
+
+type ComparisonGroupKind = 'by-dataset' | 'by-scenario';
+type ComparisonGroupKey = string;
+/**
+ * A group of comparison test summaries associated with a particular scenario or dataset.
+ */
+interface ComparisonGroup {
+    /** The kind of group, either 'by-dataset' or 'by-scenario'. */
+    kind: ComparisonGroupKind;
     /**
-     * The bundle being checked.  This bundle will also be compared against the
-     * "baseline" bundle, if `compare` is defined.
+     * The unique key for this group (a `DatasetKey` if grouped by dataset, or a
+     * `ComparisonScenarioKey` if grouped by scenario).
      */
-    current: NamedBundle;
+    key: ComparisonGroupKey;
+    /** The comparison test summaries for this group. */
+    testSummaries: ComparisonTestSummary[];
+}
+/** Describes the "root" or primary item for a group of comparisons. */
+type ComparisonGroupRoot = ComparisonDataset | ComparisonScenario;
+/** A summary of scores for a group of comparisons. */
+interface ComparisonGroupScores {
+    /** The total number of comparisons (sample size) for this group. */
+    totalDiffCount: number;
+    /** The sum of the `maxDiff` values for each threshold bucket. */
+    totalMaxDiffByBucket: number[];
+    /** The number of comparisons that fall into each threshold bucket. */
+    diffCountByBucket: number[];
+    /** The percentage of comparisons that fall into each threshold bucket. */
+    diffPercentByBucket: number[];
+}
+/**
+ * A summary of a group of comparisons that includes the resolved scenario/dataset metadata
+ * and score information for the group.
+ */
+interface ComparisonGroupSummary {
+    /** The metadata for the "root" or primary item for this group of comparisons. */
+    root: ComparisonGroupRoot;
+    /** The group containing the comparison summaries. */
+    group: ComparisonGroup;
+    /** The scores for this group, or undefined if comparisons were not performed for this group. */
+    scores?: ComparisonGroupScores;
+}
+/**
+ * Breaks down a set of by-scenario or by-dataset groupings into distinct categories.
+ */
+interface ComparisonGroupSummariesByCategory {
     /**
-     * The model check options.
+     * All groups in a map, keyed by "group key" (either a dataset key or scenario key).
      */
-    check: CheckOptions;
+    allGroupSummaries: Map<ComparisonGroupKey, ComparisonGroupSummary>;
     /**
-     * The model comparison options.
+     * Groups with items that have errors (are not valid) for both "left" and "right" models.
+     */
+    withErrors: ComparisonGroupSummary[];
+    /**
+     * Groups with items that are only valid for the "left" model (for example, datasets that
+     * were removed and no longer available in the "right" model).
+     */
+    onlyInLeft: ComparisonGroupSummary[];
+    /**
+     * Groups with items that are only valid for the "right" model (for example, scenarios
+     * for inputs that were added in the "right" model).
+     */
+    onlyInRight: ComparisonGroupSummary[];
+    /**
+     * Groups with one or more comparisons that have non-zero `maxDiff` scores; the groups
+     * will be sorted by `maxDiff`, with higher scores at the front of the array.
+     */
+    withDiffs: ComparisonGroupSummary[];
+    /**
+     * Groups where all comparisons have `maxDiff` scores of zero (no differences between
+     * "left" and "right").
      */
-    compare?: CompareOptions;
+    withoutDiffs: ComparisonGroupSummary[];
 }
-interface Config {
-    check: CheckConfig;
-    compare?: CompareConfig;
+/**
+ * Rolls up all by-scenario and by-dataset groupings.
+ */
+interface ComparisonCategorizedResults {
+    /** The full set of by-scenario groupings. */
+    byScenario: ComparisonGroupSummariesByCategory;
+    /** The full set of by-dataset groupings. */
+    byDataset: ComparisonGroupSummariesByCategory;
 }
 
-declare function createConfig(options: ConfigOptions): Promise<Config>;
-
 /**
- * Manages a set of dataset keys (corresponding to the available model outputs
- * in the given bundles) that can be used to compare two versions of the model.
+ * Given a set of terse test summaries (which only includes summaries for tests with non-zero `maxDiff`
+ * scores), restore the full set of summaries and then categorize them.
  *
- * This class computes the union of the available dataset keys and handles
- * renames so that if any variables were renamed in the "right" bundle, the
- * old key will be used so that the variable can still be compared.
- *
- * This is intended to be a simple, general purpose way to create a set of
- * dataset keys, but every model is different, so you can replace this with
- * a different set of dataset keys that is better suited for the model you
- * are testing.
- */
-declare class DatasetManager implements CompareDatasets {
-    private readonly bundleL;
-    private readonly bundleR;
-    readonly renamedDatasetKeys?: Map<DatasetKey, DatasetKey>;
-    readonly allOutputVarKeys: DatasetKey[];
-    readonly modelOutputVarKeys: DatasetKey[];
-    /**
-     * @param bundleL The "left" bundle being compared.
-     * @param bundleR The "right" bundle being compared.
-     * @param renamedDatasetKeys The mapping of renamed dataset keys.
-     */
-    constructor(bundleL: Bundle, bundleR: Bundle, renamedDatasetKeys?: Map<DatasetKey, DatasetKey>);
-    getDatasetKeysForScenario(scenario: Scenario): DatasetKey[];
-    getDatasetInfo(datasetKey: DatasetKey): DatasetInfo | undefined;
-}
+ * @param comparisonConfig The comparison configuration.
+ * @param terseSummaries The set of terse test summaries.
+ */
+declare function categorizeComparisonTestSummaries(comparisonConfig: ComparisonConfig, terseSummaries: ComparisonTestSummary[]): ComparisonCategorizedResults;
 
 /**
- * Manages a set of scenarios (corresponding to the available model inputs
- * in the given bundles) that can be used to compare two versions of the model.
+ * Additional options that are passed to `getConfigOptions`.  These can be used to customize
+ * the `ConfigOptions`, for example, if the `simplifyScenarios` flag is true, a reduced set
+ * of tests can be provided in the `ConfigOptions` so that the tests run faster in a local
+ * development situation.
  */
-declare class ScenarioManager implements CompareScenarios {
-    private readonly bundleL;
-    private readonly bundleR;
-    private readonly scenarios;
-    private readonly scenarioInfo;
-    private readonly defaultInfoForGroup;
-    private readonly groupInfo;
+interface ConfigInitOptions {
+    /** If defined, overrides the displayed name of the baseline ("left") bundle. */
+    bundleNameL?: string;
+    /** If defined, overrides the displayed name of the current ("right") bundle. */
+    bundleNameR?: string;
     /**
-     * @param bundleL The "left" bundle being compared.
-     * @param bundleR The "right" bundle being compared.
+     * A hint that the user wants tests to run faster.  If true, you can return a
+     * configuration that runs a smaller subset of tests than normal.
      */
-    constructor(bundleL: Bundle, bundleR: Bundle);
-    getScenarios(): Scenario[];
-    getScenario(scenarioKey: ScenarioKey): Scenario | undefined;
-    getScenarioGroupInfo(groupKey: ScenarioGroupKey): CompareGroupInfo | undefined;
-    getScenarioInfo(scenario: Scenario, groupKey: ScenarioGroupKey): ScenarioInfo | undefined;
+    simplifyScenarios?: boolean;
+}
+/**
+ * The user-specified options used by the library to resolve and initialize a `Config` instance.
+ */
+interface ConfigOptions {
     /**
-     * Override the title and subtitle that are displayed when the "all inputs at default"
-     * scenario is included for a particular group.  This can be used to customize the
-     * text instead of showing the default message ("...at default").
-     *
-     * @param groupKey The scenario group key.
-     * @param scenarioInfo The custom info to be displayed.
+     * The bundle being checked.  This bundle will also be compared against the
+     * "baseline" bundle, if `comparison` options are defined.
      */
-    setDefaultScenarioInfoForGroup(groupKey: ScenarioGroupKey, scenarioInfo: ScenarioInfo): void;
+    current: NamedBundle;
     /**
-     * Add a scenario to the set.
-     *
-     * @param scenario The scenario to be added.
-     * @param scenarioInfo The custom title/subtitle for the scenario.  If left undefined, the
-     * default (possibly generic) info will be used.
-     * @param groupInfo The custom title/subtitle for the group.  If left undefined, the
-     * default (possibly generic) info will be used.
+     * The model check options.
      */
-    addScenario(scenario: Scenario, scenarioInfo?: ScenarioInfo, groupInfo?: CompareGroupInfo): void;
+    check: CheckOptions;
     /**
-     * Adds a set of scenarios that can be used to compare the two versions of
-     * the given model.
-     *
-     * This function computes a matrix of input scenarios using the input variables
-     * advertised by the given bundles.  It will generate scenarios such that for
-     * any output variable, the model will be run:
-     *   - once with all inputs at their default
-     *   - once with all inputs at their minimum
-     *   - once with all inputs at their maximum
-     *   - twice for each input
-     *       - once with single input at its minimum
-     *       - once with single input at its maximum
-     *
-     * This is intended to be a simple, general purpose way to create a set of
-     * scenarios, but every model is different, so you can replace this with a
-     * function to generate a different set of scenarios that is better suited
-     * for the model you are testing.
+     * The model comparison options.
      */
-    addScenarioMatrix(): void;
-    private getGroupInfoForScenario;
-    private getInfoForScenario;
-    private getInfoForPositionSetting;
-    private getRelatedItemsForSettings;
-    private getInputVarForSetting;
+    comparison?: ComparisonOptions;
 }
+/**
+ * The resolved configuration for check and comparison tests.
+ */
+interface Config {
+    /** The resolved check test configuration. */
+    check: CheckConfig;
+    /** The resolved comparison test configuration. */
+    comparison?: ComparisonConfig;
+}
+
+declare function createConfig(options: ConfigOptions): Promise<Config>;
 
 declare class PerfRunner {
     readonly bundleModelL: BundleModel;
@@ -862,12 +1221,26 @@ declare class PerfRunner {
     start(): void;
 }
 
+/**
+ * The report for a single run of the full check+comparison test suite.
+ */
 interface SuiteReport {
     checkReport: CheckReport;
-    compareReport?: CompareReport;
+    comparisonReport?: ComparisonReport;
+}
+/**
+ * A simplified/terse version of `SuiteReport` that is used when writing
+ * results to a JSON file.  The object keys are terse and it only includes
+ * the minimum set of fields (e.g., only the `maxDiff` value instead of the
+ * full `DiffReport` for each comparison test) to keep the file smaller
+ * when there are many reported differences.
+ */
+interface SuiteSummary {
+    checkSummary: CheckSummary;
+    comparisonSummary?: ComparisonSummary;
 }
 
-declare type CancelRunSuite = () => void;
+type CancelRunSuite = () => void;
 interface RunSuiteCallbacks {
     onProgress?: (pct: number) => void;
     onComplete?: (suiteReport: SuiteReport) => void;
@@ -887,14 +1260,6 @@ interface RunSuiteOptions {
  */
 declare function runSuite(config: Config, callbacks: RunSuiteCallbacks, options?: RunSuiteOptions): CancelRunSuite;
 
-/**
- * A simplified/terse version of `SuiteReport` that matches the
- * format of the JSON objects emitted by the CLI in terse mode.
- */
-interface SuiteSummary {
-    checkSummary: CheckSummary;
-    compareSummary?: CompareSummary;
-}
 /**
  * Convert a full `SuiteReport` to a simplified `SuiteSummary` that only includes
  * failed/errored checks or comparisons with differences.
@@ -904,4 +1269,4 @@ interface SuiteSummary {
  */
 declare function suiteSummaryFromReport(suiteReport: SuiteReport): SuiteSummary;
 
-export { AllInputsScenario, 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, CheckScenarioReport, CheckStatus, CheckSummary, CheckTestReport, CompareConfig, CompareDataCoordinator, CompareDataRequestKey, CompareDatasetReport, CompareDatasetSummary, CompareDatasets, CompareGroup, CompareGroupInfo, CompareItem, CompareOptions, CompareReport, CompareScenarios, CompareSummary, Config, ConfigOptions, DataSource, Dataset, DatasetInfo, DatasetKey, DatasetManager, DatasetMap, DatasetsResult, DiffPoint, DiffReport, DiffValidity, Dimension, GraphDatasetReport, GraphInclusion, GraphMetadataReport, GraphReport, ImplVar, InputPosition, InputSetting, InputVar, LegendItem, LinkItem, LoadedBundle, ModelSpec, NamedBundle, OutputVar, PerfReport, PerfRunner, PerfStats, PositionSetting, RelatedItem, RunSuiteCallbacks, RunSuiteOptions, Scenario, ScenarioGroupKey, ScenarioInfo, ScenarioKey, ScenarioManager, SettingsScenario, SourceName, Subscript, SuiteReport, SuiteSummary, ValueSetting, VarId, allInputsAtPositionScenario, checkReportFromSummary, checkSummaryFromReport, compareDatasets, compareSummaryFromReport, createConfig, datasetMessage, diffDatasets, diffGraphs, inputAtPositionScenario, inputAtValueScenario, matrixScenarios, positionSetting, predicateMessage, runSuite, scenarioMessage, settingsScenario, suiteSummaryFromReport, valueSetting };
+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 };