@dev-build-deploy/diagnose-it/lib/diagnosticsMessage.d.ts

Expressive Diagnostics library

import { FixItHint } from "./fixitHint";
/**
 * Diagnostics Message Level
 * @enum {number}
 *
 * @example
 * ```typescript
 * const level = DiagnosticsLevelEnum.Error;
 * console.log(level); // 4
 * console.log(DiagnosticsLevelEnum[level]); // Error
 * ```
 */
export declare enum DiagnosticsLevelEnum {
    Ignored = 0,
    Note = 1,
    Remark = 2,
    Warning = 3,
    Error = 4,
    Fatal = 5
}
/**
 * Diagnostics Context
 * @type {DiagnosticsContextType}
 * @property {number} linenumber Line number for the first line provided by `context`
 * @property {Array<string>} context Context lines
 *
 * @example
 * ```typescript
 * const context: DiagnosticsContextType = {
 *  linenumber: 1,
 *  context: ["Line 1", "Line 2", "Line 3"]
 * }
 * ```
 */
export type DiagnosticsContextType = {
    linenumber: number;
    lines: Array<string>;
};
/**
 * Diagnostics Message Type
 * @type {DiagnosticsMessageType}
 * @property {string} text Message text
 * @property {number} linenumber Line number
 * @property {number} column Column number
 *
 * @example
 * ```typescript
 * const message: DiagnosticsMessageType = {
 *   text: "Unknown property `foo`",
 *   linenumber: 3,
 *   column: 10
 * }
 * ```
 */
export type DiagnosticsMessageType = {
    text: string;
    linenumber?: number;
    column?: number;
};
/**
 * Diagnostics Message Interface
 * @interface IDiagnosticsMessage
 * @property {string} file File name
 * @property {DiagnosticsLevelEnum} level Message level
 * @property {DiagnosticsMessageType} message Message
 *
 * @example
 * ```typescript
 * const message: IDiagnosticsMessage = {
 *   file: "test.ts",
 *   level: DiagnosticsLevelEnum.Error,
 *   message: {
 *     text: "Unknown property `foo`",
 *     linenumber: 3,
 *     column: 10
 *   }
 * }
 * ```
 */
export interface IDiagnosticsMessage {
    file: string;
    level?: DiagnosticsLevelEnum;
    message: DiagnosticsMessageType;
}
/**
 * Diagnostics Message
 * @static createError Creates an error message
 * @static createWarning Creates a warning message
 * @function setFile Sets the file name
 * @function setLevel Sets the message level
 * @function setMessage Sets the message
 * @function setContext Sets the context
 * @function addFixitHint Adds a FixIt hint
 * @function toString Returns the message as a string
 *
 * @example Using the constructor
 * ```typescript
 * const message = new DiagnosticsMessage({
 *   file: "test.ts",
 *   level: DiagnosticsLevelEnum.Error,
 *   message: {
 *     text: "Unknown property `foo`",
 *     linenumber: 3,
 *     column: 10
 *   }
 * });
 * ```
 *
 * @example Using the static methods
 * ```typescript
 * const message = DiagnosticsMessage.createError("test.ts", {
 *   text: "Unknown property `foo`",
 *   linenumber: 3,
 *   column: 10
 * });
 * ```
 *
 * @example Creating a message with a context and FixIt Hints
 * ```typescript
 * const message = DiagnosticsMessage.createError("test.ts", {
 *  text: "Unknown property `foo`",
 *   linenumber: 3,
 *   column: 1
 * })
 *   .setContext(2, ["monkey: banana", "foo: foo", "elephant: trunk"])
 *   .addFixitHint(FixItHint.createInsertion(1, "bar"));
 * ```
 */
export declare class DiagnosticsMessage {
    file: string;
    level: DiagnosticsLevelEnum;
    message: DiagnosticsMessageType;
    context?: DiagnosticsContextType;
    private fixitHints;
    constructor(data: IDiagnosticsMessage);
    /**
     * Creates a Diagnostics message with the level `Error`
     * @param file File path
     * @param message Error message
     * @returns Diagnostics Message
     */
    static createError(file: string, message: DiagnosticsMessageType): DiagnosticsMessage;
    /**
     * Creates a Diagnostics message with the level `Warning`
     * @param file File path
     * @param message Warning message
     * @returns Diagnostics Message
     */
    static createWarning(file: string, message: DiagnosticsMessageType): DiagnosticsMessage;
    /**
     * Sets the path towards the file associated with the Diagnostics Message.
     *
     * Notes:
     * - The file path cannot contain newlines.
     * - All special characters in filenames ( $ # & * ? ; | < > ( ) { } [ ] ' " ` ~ ! \ ) will be escaped.
     * @param file File path
     * @returns this
     */
    setFile(file: string): this;
    /**
     * Sets the level of the Diagnostics Message (i.e. `Error`, `Warning`, ...)
     * @param level Diagnostics Level
     * @returns this
     */
    setLevel(level: DiagnosticsLevelEnum): this;
    /**
     * Sets the message of the Diagnostics Message.
     *
     * Notes:
     * * The message cannot contain newlines.
     * * The column number must be greater than 0.
     * * The line number must be greater than 0.
     *
     * @param message Diagnostics Message
     * @returns this
     */
    setMessage(message: DiagnosticsMessageType): this;
    /**
     * Sets the context of the Diagnostics Message.
     *
     * Notes:
     * * The context can be provided as an array of strings or a single string.
     *   Any single string with newlines will be split into multiple lines.
     * * The starting line number must be greater than 0.
     * * The line number associated with the message must be within the range of the context.
     *
     * @param linenumber Line number for the first line provided by `context`
     * @param lines Context lines
     * @returns this
     */
    setContext(linenumber: number, lines: string | Array<string>): this;
    /**
     * Adds a FixIt Hint to the Diagnostics Message.
     *
     * Notes:
     * * You must first provide a context before adding a FixIt Hint.
     * * The FixIt Hint cannot overlap with an existing FixIt Hint.
     *
     * @param hint FixIt Hint
     * @returns this
     *
     * @example Adding a FixIt Hint
     * ```typescript
     * const message = DiagnosticsMessage.createError("test.ts", {
     *   text: "Unknown property `foo`",
     *   linenumber: 3,
     *   column: 1
     * })
     *   .setContext(2, ["monkey: banana", "foo: foo", "elephant: trunk"])
     *   .addFixitHint(FixItHint.createInsertion(1, "bar"));
     * ```
     */
    addFixitHint(hint: FixItHint): this;
    /**
     * Returns the FixIt Hints associated with the Diagnostics Message.
     * @returns Array of FixIt Hints
     */
    getFixitHints(): Array<FixItHint>;
    private getFixitHintsString;
    private getContextString;
    /**
     * Generates an Expressive Diagnostics message in formatted output.
     * @returns Formatted message
     */
    toString(): string;
    /**
     * Applies the FixIt hints to the context and returns the result as a string.
     * @returns Fixed string
     */
    applyFixitHints(): string;
}