@eclipse-emfcloud/model-validation/lib/core/diagnostic.d.ts

Generic model validation framework.

import { Severity } from './severity';
/**
 * A report of the validation state of some element in the model, or the model
 * overall if the `path` is `''`.
 */
export interface Diagnostic {
    /**
     * The severity of the problem. An `'ok'` severity indicates that no problem
     * is manifest.
     */
    severity: Severity;
    /**
     * The source of the problem, indicating the component that reported it.
     * Semantics of the source is application-specific but it must not be the empty string.
     */
    source: string;
    /**
     * A code identifying the particular validation rule that reported a problem.
     * May be omitted for `ok` {@link severity} diagnostics and for "roll-ups"
     * that have {@link children}.
     */
    code?: string;
    /**
     * A JSON Pointer indicating the object within the model with which the diagnostic
     * is associated. Thus a diagnostic for the model as a whole has the `''` path.
     * An array indices in the path must be specific, not `-`.
     */
    path: string;
    /**
     * A message describing the problem that is suitable for presentation to a human user.
     * Likewise if the {@link severity} is `'ok`'.
     */
    message: string;
    /**
     * An optional blob of information providing details about the problem.
     * The schema for the data is application-specific and may vary according to
     * {@link source} and/or {@link code}.
     */
    data?: unknown;
    /**
     * An optional array of child diagnostics breaking down the validation state
     * of the object identified by the {@link path} into finer detail. Typically
     * used to represent a "roll-up" validation state for some subtree of the
     * model or the model in its entirety.
     *
     * A diagnostic that has children must not, itself, indicate a discrete problem.
     * Instead, any problem specific to the object identified by the {@link path}
     * should be included in these children. A diagnostic that has children
     * must have a {@link severity} that is the maximum of the severities of those
     * children.
     */
    children?: Diagnostic[];
}
/**
 * Obtain a diagnostic of `'ok'` severity indicating that validation found no problem.
 *
 * @param [source] an optional source for the resulting diagnostic.
 *   The default indicates this validation framework package
 * @return an `'ok'` diagnostic with empty (`''`) path as the path does not really matter in the absence of a problem
 */
export declare const ok: (source?: string) => Diagnostic;
/**
 * Merge zero or more diagnostics into one. All `'ok'` diagnostics
 * are elided. As a special case, an empty list of `diagnostics`
 * or an array containing only `'ok'` diagnostics merges to an
 * {@link ok} diagnostic. As another special case, a single
 * input merges to itself.
 *
 * For any input to the merge that has {@link Diagnostic.children children},
 * those children (except any that are OK) are added to the merge result
 * in place of the original input, as that parent diagnostic is expected
 * to be the result of a previous merge by this same algorithm.
 * In consequence, consistent use of this merge function will always
 * result in a flat structure of a diagnostic with zero or more children
 * that all have themselves no children.
 *
 * In a merge result that combines multiple non-OK diagnostics from the
 * inputs, all of the following conditions hold:
 *
 * - the {@link Diagnostic.severity severity} of the merge result is the
 *   {@link severityComparator.max maximum} of the severities of its children
 * - the {@link Diagnostic.source source} of the merge result is the
 *   same as the source of its children if they all have the same source.
 *   Otherwise, it is the empty string (`''`)
 * - the {@link Diagnostic.code code} of the merge result is `undefined`
 * - the {@link Diagnostic.path path} of the merge result is the longest
 *   common prefix of all of the paths of its children, which may be
 *   their path if they all have the same path, or may be the empty string
 *   (`''`) denoting the model as a whole if they have no common prefix
 * - the {@link Diagnostic.message message} of the merge result is a
 *   non-localized string indicating how many problems it aggregates
 *
 * @param diagnostics zero or more diagnostics to merge
 * @return a compact merge of the `diagnostics`
 */
export declare const merge: (...diagnostics: Diagnostic[]) => Diagnostic;
//# sourceMappingURL=diagnostic.d.ts.map