@remotex-labs/xmap 1.1.0 → 2.0.0

package/dist/cjs/providers/interfaces/mapping.interface.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Represents a mapping segment that corresponds to a position in the source map.
+ *
+ * @property line - The original line number in the source file.
+ * @property column - The original column number in the source file.
+ * @property nameIndex - The index of the symbol name in the source map, or `null` if there is no associated name.
+ * @property sourceIndex - The index of the source file in the source map.
+ * @property generatedLine - The line number in the generated code.
+ * @property generatedColumn - The column number in the generated code.
+ */
+export interface SegmentInterface {
+    line: number;
+    column: number;
+    nameIndex: number | null;
+    sourceIndex: number;
+    generatedLine: number;
+    generatedColumn: number;
+}
+/**
+ * Extends the `SegmentInterface` to represent an offset segment used during mapping calculations.
+ * The main difference is that `nameIndex` is always a number.
+ *
+ * @augments { SegmentInterface }
+ * @property nameIndex - The index of the symbol name in the source map (cannot be null in this context).
+ */
+export interface SegmentOffsetInterface extends SegmentInterface {
+    nameIndex: number;
+}
+/**
+ * Represents the bias used when searching for segments in the source map.
+ * This enum is useful for determining the preferred matching behavior
+ * when the exact line and column cannot be found.
+ *
+ * @property BOUND - No preference for column matching; returns the first match found.
+ * @property LOWER_BOUND - Prefer the closest mapping with a lower column value.
+ * @property UPPER_BOUND - Prefer the closest mapping with a higher column value.
+ */
+export declare const enum Bias {
+    BOUND = 0,
+    LOWER_BOUND = 1,
+    UPPER_BOUND = 2
+}
+/**
+ * A type alias for a frame in the source map, representing an array of segments.
+ * Each frame consists of multiple mapping segments for a given line in the generated code.
+ */
+export type FrameType = Array<SegmentInterface>;
+/**
+ * A type alias for the source map, where each entry represents a frame of mappings.
+ * A frame can either be an array of segments (frame) or `null` if the line has no mappings (represented by a semicolon in the mapping string).
+ */
+export type MapType = Array<null | FrameType>;

package/dist/cjs/providers/mapping.provider.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Import will remove at compile time
+ */
+import { Bias, type MapType, type SegmentInterface } from './interfaces/mapping.interface';
+/**
+ * The `MappingProvider` class provides methods to encode and decode mappings
+ * from a source map or mapping string to an internal structured representation.
+ */
+export declare class MappingProvider {
+    /**
+     * The internal mapping representation, where each index represents a frame of segments.
+     */
+    private mapping;
+    /**
+     * Constructor to initialize the `MappingProvider` with a mapping.
+     * Can be initialized with either a mapping string or a structured mapping array.
+     *
+     * @param mapping - The mapping data, either as a string or structured array.
+     * @param namesOffset - Optional offset for the names index.
+     * @param sourceOffset - Optional offset for the sources index.
+     *
+     * @example
+     * ```ts
+     * const provider = new MappingProvider(";;;AAiBO,SAAS,OAAO;AACnB,UAAQ,IAAI,MAAM;AACtB;;;ACjBA,QAAQ,IAAI,GAAG;AACf,KAAK;", 0, 0);
+     * const provider2 = new MappingProvider([
+     *   null,
+     *   [
+     *     {
+     *       line: 1,
+     *       column: 1,
+     *       nameIndex: null,
+     *       sourceIndex: 0,
+     *       generatedLine: 2,
+     *       generatedColumn: 1
+     *     }
+     *   ],
+     *   null
+     * ], 0, 0);
+     * ```
+     */
+    constructor(mapping: string, namesOffset?: number, sourceOffset?: number);
+    constructor(mapping: MapType, namesOffset?: number, sourceOffset?: number);
+    constructor(mapping: MappingProvider, namesOffset?: number, sourceOffset?: number);
+    /**
+     * Encodes the internal mapping array back into a mapping string.
+     *
+     * @returns {string} - The encoded mapping string.
+     * @example
+     * ```ts
+     * const encoded = provider.encode();
+     * console.log(encoded); // Outputs encoded mapping string
+     * ```
+     */
+    encode(): string;
+    /**
+     * Decodes a mapping from either a string or structured array into the internal mapping.
+     *
+     * @param mapping - The mapping data to decode.
+     * @param namesOffset - Offset for the names index.
+     * @param sourcesOffset - Offset for the sources index.
+     * @example
+     * ```ts
+     * provider.decode(";;;AAiBO,SAAS,OAAO;AACnB,UAAQ,IAAI,MAAM;AACtB;;;ACjBA,QAAQ,IAAI,GAAG;AACf,KAAK;", 0, 0);
+     * provider.decode([
+     *   null,
+     *   [
+     *     {
+     *       line: 1,
+     *       column: 1,
+     *       nameIndex: null,
+     *       sourceIndex: 0,
+     *       generatedLine: 2,
+     *       generatedColumn: 1
+     *     }
+     *   ],
+     *   null
+     * ], 0, 0);
+     * ```
+     */
+    decode(mapping: MappingProvider | MapType | string, namesOffset?: number, sourcesOffset?: number): void;
+    /**
+     * Retrieves a segment based on the provided generated line and column,
+     * applying the specified bias when the exact match is not found.
+     *
+     * This method performs a binary search on the segments of the specified
+     * generated line to efficiently locate the segment corresponding to
+     * the provided generated column. If an exact match is not found,
+     * the method returns the closest segment based on the specified bias:
+     * - `Bias.BOUND`: No preference for column matching (returns the closest segment).
+     * - `Bias.LOWER_BOUND`: Prefers the closest mapping with a lower column value.
+     * - `Bias.UPPER_BOUND`: Prefers the closest mapping with a higher column value.
+     *
+     * @param generatedLine - The line number of the generated code (1-based index).
+     * @param generatedColumn - The column number of the generated code (0-based index).
+     * @param bias - The bias to use when the line matches, can be one of:
+     *   - `Bias.BOUND` (default): No preference for column matching.
+     *   - `Bias.LOWER_BOUND`: Prefer the closest mapping with a lower column value.
+     *   - `Bias.UPPER_BOUND`: Prefer the closest mapping with a higher column value.
+     * @returns The matching segment if found;
+     * returns null if no segments exist for the specified generated line
+     * or if the generated line is out of bounds.
+     *
+     * @throws { Error } - Throws an error if the generated line is invalid
+     * (out of bounds).
+     *
+     * @example
+     * ```ts
+     * const segment = sourceMap.getSegment(5, 10, Bias.UPPER_BOUND);
+     * if (segment) {
+     *     console.log(`Found segment: line ${segment.line}, column ${segment.column}`);
+     * } else {
+     *     console.log('No matching segment found.');
+     * }
+     * ```
+     */
+    getSegment(generatedLine: number, generatedColumn: number, bias?: Bias): SegmentInterface | null;
+    /**
+     * Retrieves the original segment based on the provided line, column, and source index.
+     *
+     * This method searches for the original segment that corresponds to the specified
+     * line, column, and source index. It uses binary search to find the closest segment
+     * based on the provided bias.
+     *
+     * @param line - The line number of the original code (1-based index).
+     * @param column - The column number of the original code (0-based index).
+     * @param sourceIndex - The index of the source file in the source map.
+     * @param bias - The bias to apply when multiple segments match; defaults to `Bias.BOUND`.
+     * @returns {SegmentInterface | null} - The matching original segment if found;
+     * returns null if no segments exist for the specified line and source index.
+     *
+     * @example
+     * ```ts
+     * const originalSegment = sourceMap.getOriginalSegment(3, 5, 0, Bias.LOWER_BOUND);
+     * if (originalSegment) {
+     *     console.log(`Found original segment: line ${originalSegment.line}, column ${originalSegment.column}`);
+     * } else {
+     *     console.log('No matching original segment found.');
+     * }
+     * ```
+     */
+    getOriginalSegment(line: number, column: number, sourceIndex: number, bias?: Bias): SegmentInterface | null;
+    /**
+     * Initializes the segment offsets used to track the current decoding position.
+     *
+     * @param namesOffset - The offset for the names index.
+     * @param sourceIndex - The offset for the source index.
+     * @returns { SegmentOffsetInterface } - The initialized segment offset.
+     */
+    private initPositionOffsets;
+    /**
+     * Validates the format of an encoded mapping string.
+     *
+     * @param encodedSourceMap - The encoded source map string to validate.
+     * @returns Returns `true` if the format is valid, otherwise `false`.
+     */
+    private validateMappingString;
+    /**
+     * Validates the properties of a segment to ensure they conform to expected types.
+     *
+     * This method checks that the segment's properties are finite numbers and that
+     * the nameIndex, if provided, is either a finite number or null.
+     * An error is thrown if any of the properties do not meet the specified criteria.
+     *
+     * @param segment - The segment object to validate, which must conform to the
+     *                  SegmentInterface structure, including:
+     *                  - line: number (finite)
+     *                  - column: number (finite)
+     *                  - nameIndex: number | null (if not null, must be finite)
+     *                  - sourceIndex: number (finite)
+     *                  - generatedLine: number (finite)
+     *                  - generatedColumn: number (finite)
+     *
+     * @throws {Error} - Throws an error if any property of the segment is invalid.
+     *                   The error message will specify which property is invalid
+     *                   and the value that was received.
+     */
+    private validateSegment;
+    /**
+     * Encodes a segment into a VLQ-encoded string based on the segment offsets.
+     *
+     * @param segmentOffset - The current segment offset.
+     * @param segmentObject - The segment to encode.
+     * @returns The encoded segment string.
+     */
+    private encodeSegment;
+    /**
+     * Encodes the entire mapping array into a VLQ-encoded mapping string.
+     *
+     * @param map - The mapping array to encode.
+     * @returns The encoded mapping string.
+     */
+    private encodeMappings;
+    /**
+     * Decodes a VLQ-encoded segment into a segment object based on the current offset.
+     *
+     * @param segmentOffset - The current segment offset.
+     * @param decodedSegment - The decoded VLQ segment values.
+     * @returns The decoded segment object.
+     */
+    private decodedSegment;
+    /**
+     * Decodes a VLQ-encoded mapping string into the internal mapping representation.
+     *
+     * @param encodedMap - The VLQ-encoded mapping string.
+     * @param namesOffset - Offset for the names index.
+     * @param sourceOffset - Offset for the sources index.
+     * @throws { Error } - Throws an error if the mapping string is invalid.
+     */
+    private decodeMappingString;
+    /**
+     * Decodes a mapping array into the internal mapping representation, adjusting for offsets.
+     *
+     * This method processes each frame in the provided structured mapping array,
+     * validating each segment within the frame and adjusting the indices based on the
+     * specified offsets for names and sources. If a frame is invalid or not an array,
+     * an error will be thrown.
+     *
+     * @param encodedMap - The structured mapping array, which should be an array of frames,
+     *                     where each frame is an array of segments. Each segment must conform
+     *                     to the SegmentInterface.
+     * @param namesOffset - Offset for the names index, which will be added to each segment's nameIndex.
+     * @param sourceOffset - Offset for the sources index, which will be added to each segment's sourceIndex.
+     * @throws { Error } - Throws an error if:
+     *                   - The mapping array is invalid (not an array).
+     *                   - Any frame is not an array.
+     *                   - Any segment does not conform to the SegmentInterface.
+     */
+    private decodeMappingArray;
+}

package/dist/cjs/services/interfaces/source.interface.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Represents a source map structure used for mapping code within a file
+ * to its original source. Source maps are essential for debugging minified
+ * or transpiled code, as they allow developers to trace back to the
+ * original source files and understand the context of the code execution.
+ *
+ * @interface SourceMapInterface
+ * @property file - The generated file's name that the source map is associated with.
+ * This property is optional and may be null if not specified.
+ * @property names - An array of variable/function names that are present in the original source.
+ * These names help in mapping the original code context during debugging.
+ * @property version - The version of the source map specification.
+ * This should be set to `3` for the standard source map version.
+ * @property sources - An array of URLs or paths to the original source files.
+ * These sources are used to locate the original code that corresponds to the generated code.
+ * @property mappings - A VLQ (Variable-Length Quantity) encoded string that describes how to map the
+ * generated code back to the original source code. This property is crucial for the correct functioning of the source map.
+ * @property sourceRoot - An optional root URL for the sources.
+ * It can be used to specify a base path for resolving the sources, which may be null if not applicable.
+ * @property sourcesContent - An optional array containing the content of the original source files.
+ * This property can be useful when the original files are not available at runtime.
+ */
+export interface SourceMapInterface {
+    file?: string | null;
+    names: Array<string>;
+    version: number;
+    sources: Array<string>;
+    mappings: string;
+    sourceRoot?: string | null;
+    sourcesContent?: Array<string>;
+}
+export interface PositionInterface {
+    name: string | null;
+    line: number;
+    column: number;
+    source: string;
+    sourceRoot: string | null;
+    sourceIndex: number;
+    generatedLine: number;
+    generatedColumn: number;
+}
+export interface PositionWithContentInterface extends PositionInterface {
+    sourcesContent: string;
+}
+export interface PositionWithCodeInterface extends PositionInterface {
+    code: string;
+    endLine: number;
+    startLine: number;
+}
+export interface SourceOptionsInterface {
+    linesAfter?: number;
+    linesBefore?: number;
+}

package/dist/cjs/services/source.service.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Import will remove at compile time
+ */
+import type { PositionInterface, SourceMapInterface, SourceOptionsInterface, PositionWithCodeInterface, PositionWithContentInterface } from "./interfaces/source.interface";
+/**
+ * Imports
+ */
+import { MappingProvider } from "../providers/mapping.provider";
+import { Bias } from "../providers/interfaces/mapping.interface";
+/**
+ * A service for validating and processing source maps.
+ * This class allows parsing and manipulation of source maps, providing functionality such as
+ * retrieving position mappings between original and generated code, concatenating source maps,
+ * and getting code snippets based on mappings.
+ *
+ * @example
+ * ```ts
+ * const sourceMapJSON = '{"version": 3, "file": "bundle.js", "sources": ["foo.ts"], "names": [], "mappings": "AAAA"}';
+ * const sourceService = new SourceService(sourceMapJSON);
+ *
+ * console.log(sourceService.file); // Outputs: 'bundle.js'
+ * ```
+ */
+export declare class SourceService {
+    /**
+     * The name of the generated file (bundle) that this source map applies to.
+     *
+     * @example
+     * ```ts
+     * console.log(sourceService.file); // 'bundle.js'
+     * ```
+     */
+    readonly file: string | null;
+    /**
+     * A MappingProvider instance of base64 VLQ-encoded mappings.
+     */
+    readonly mappings: MappingProvider;
+    /**
+     * The root URL for the sources, if present in the source map.
+     */
+    readonly sourceRoot: string | null;
+    /**
+     * A list of symbol names used by the “mappings” entry.
+     */
+    readonly names: Array<string>;
+    /**
+     * An array of source file paths.
+     */
+    readonly sources: Array<string>;
+    /**
+     * An array of source files contents.
+     */
+    readonly sourcesContent: Array<string>;
+    /**
+     * Creates a new instance of the `SourceService` class.
+     *
+     * This constructor initializes the class using either a `SourceMapInterface` object,
+     * a JSON string representing the source map, or an existing `SourceService` instance.
+     * It validates the source map and populates its properties such as `file`, `sources`, and `mappings`.
+     *
+     * @param source - Can be one of the following:
+     *   - An object conforming to the `SourceMapInterface`.
+     *   - A JSON string representing the source map.
+     *   - A `SourceService` instance to copy the properties.
+     * @param file - (Optional) A string representing the file name of the generated bundle.
+     *               Defaults to `null`. It will overwrite any existing `file` property in the source map.
+     * @throws {Error} - If the source map does not contain required properties or has an invalid format.
+     *
+     * @example
+     * ```ts
+     * const sourceMapJSON = '{"version": 3, "file": "bundle.js", "sources": ["foo.ts"], "names": [], "mappings": "AAAA"}';
+     * const sourceService = new SourceService(sourceMapJSON);
+     * ```
+     */
+    constructor(source: SourceService);
+    constructor(source: SourceMapInterface | string, file?: string | null);
+    /**
+     * Converts the current source map data into a plain object format.
+     *
+     * @returns The source map json object.
+     *
+     * @example
+     * ```ts
+     * const mapObject = sourceService.getMapObject();
+     * console.log(mapObject.file); // 'bundle.js'
+     * ```
+     */
+    getMapObject(): SourceMapInterface;
+    /**
+     * Concatenates one or more source maps to the current source map.
+     *
+     * This method merges additional source maps into the current source map,
+     * updating the `mappings`, `names`, `sources`, and `sourcesContent` arrays.
+     *
+     * @param maps - An array of `SourceMapInterface` or `SourceService` instances to be concatenated.
+     * @throws { Error } If no source maps are provided for concatenation.
+     *
+     * @example
+     * ```ts
+     * sourceService.concat(anotherSourceMap);
+     * console.log(sourceService.sources); // Updated source paths
+     * ```
+     */
+    concat(...maps: Array<SourceMapInterface | SourceService>): void;
+    /**
+     * Creates a new instance of `SourceService` with concatenated source maps.
+     *
+     * @param maps - An array of `SourceMapInterface` or `SourceService` instances to be concatenated.
+     * @returns { SourceService } A new `SourceService` instance with the concatenated maps.
+     * @throws { Error } If no source maps are provided.
+     *
+     * @example
+     * ```ts
+     * const newService = sourceService.concatNewMap(anotherSourceMap);
+     * console.log(newService.file); // The file from the new source map
+     * ```
+     */
+    concatNewMap(...maps: Array<SourceMapInterface | SourceService>): SourceService;
+    /**
+     * Retrieves the position information based on the original source line and column.
+     *
+     * @param line - The line number in the generated code.
+     * @param column - The column number in the generated code.
+     * @param sourceIndex - The index or file path of the original source.
+     * @param bias - The bias to use when matching positions (`Bias.LOWER_BOUND`, `Bias.UPPER_BOUND`, or `Bias.BOUND`).
+     * @returns { PositionInterface | null } The corresponding position in the original source, or `null` if not found.
+     *
+     * @example
+     * ```ts
+     * const position = sourceService.getPositionByOriginal(1, 10, 'foo.ts');
+     * console.log(position?.line); // The line number in the original source
+     * ```
+     */
+    getPositionByOriginal(line: number, column: number, sourceIndex: number | string, bias?: Bias): PositionInterface | null;
+    /**
+     * Retrieves the position in the original source code based on a given line and column
+     * in the generated code.
+     *
+     * @param line - Line number in the generated code.
+     * @param column - Column number in the generated code.
+     * @param bias - The bias to use for matching positions. Defaults to `Bias.BOUND`.
+     * @returns {PositionInterface | null} The position in the original source, or null if not found.
+     *
+     * @example
+     * ```ts
+     * const position = sourceService.getPosition(2, 15);
+     * console.log(position?.source); // The original source file
+     * ```
+     */
+    getPosition(line: number, column: number, bias?: Bias): PositionInterface | null;
+    /**
+     * Retrieves the position and original source content for a given position in the generated code.
+     *
+     * @param line - Line number in the generated code.
+     * @param column - Column number in the generated code.
+     * @param bias - Bias used for position matching.
+     * @returns { PositionWithContentInterface | null } The position and its associated content, or `null` if not found.
+     *
+     * @example
+     * ```ts
+     * const positionWithContent = sourceService.getPositionWithContent(3, 5);
+     * console.log(positionWithContent?.sourcesContent); // The source code content
+     * ```
+     */
+    getPositionWithContent(line: number, column: number, bias?: Bias): PositionWithContentInterface | null;
+    /**
+     * Retrieves the position and a code snippet from the original source based on the given
+     * generated code position, with additional lines of code around the matching line.
+     *
+     * @param line - Line number in the generated code.
+     * @param column - Column number in the generated code.
+     * @param bias - Bias used for position matching.
+     * @param options - (Optional) Extra options for the amount of surrounding lines to include.
+     * @returns { PositionWithCodeInterface | null } The position and code snippet.
+     *
+     * @example
+     * ```ts
+     * const positionWithCode = sourceService.getPositionWithCode(4, 8, Bias.BOUND, { linesBefore: 2, linesAfter: 2 });
+     * console.log(positionWithCode?.code); // The code snippet from the original source
+     * ```
+     */
+    getPositionWithCode(line: number, column: number, bias?: Bias, options?: SourceOptionsInterface): PositionWithCodeInterface | null;
+    /**
+     * Converts the current source map object to a JSON string.
+     *
+     * @returns A stringified version of the source map object.
+     *
+     * @example
+     * ```ts
+     * console.log(sourceService.toString()); // JSON string of the source map
+     * ```
+     */
+    toString(): string;
+    /**
+     * Validates the provided source map object.
+     *
+     * This method checks whether all required keys are present in the source map object.
+     * It throws an error if any required keys are missing.
+     *
+     * @private
+     * @param input - The source map object to be validated.
+     * @throws Error If any required key is missing from the source map.
+     *
+     * @example
+     * ```ts
+     * const sourceMap = {
+     *     version: 3,
+     *     file: 'example.js',
+     *     names: ['src', 'maps', 'example', 'function', 'line', 'column'],
+     *     sources: ['source1.js', 'source2.js'],
+     *     mappings: 'AAAA,SAASA,CAAC,CAAC,CAAC;AAAA,CAAC,CAAC;AAAC,CAAC',
+     * };
+     * sourceService['validateSource'](sourceMap); // Throws if invalid
+     * ```
+     */
+    private validateSourceMap;
+}

package/dist/esm/components/base64.component.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Encodes a given number using Variable-Length Quantity (VLQ) encoding.
+ * Negative numbers are encoded by converting to a non-negative representation.
+ * The continuation bit is used to indicate if more bytes follow.
+ *
+ * @param value - The number to be encoded.
+ * @returns The VLQ encoded string.
+ */
+export declare function encodeVLQ(value: number): string;
+/**
+ * Encodes an array of numbers using VLQ encoding.
+ * Each number in the array is individually encoded and the results are concatenated.
+ *
+ * @param values - The array of numbers to be encoded.
+ * @returns The concatenated VLQ encoded string.
+ */
+export declare function encodeArrayVLQ(values: number[]): string;
+/**
+ * Decodes a VLQ encoded string back into an array of numbers.
+ * Each character is decoded using the Base64 map and continuation bits are processed.
+ *
+ * @param data - The VLQ encoded string.
+ * @returns The array of decoded numbers.
+ * @throws Error If the string contains invalid Base64 characters.
+ */
+export declare function decodeVLQ(data: string): number[];

package/dist/esm/components/formatter.component.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Import will remove at compile time
+ */
+import type { PositionWithCodeInterface } from "../services/interfaces/source.interface";
+import type { AnsiOptionInterface, FormatCodeInterface } from "./interfaces/formatter.interface";
+/**
+ * Formats a code snippet with optional line padding and custom actions.
+ *
+ * This function takes a code string and an options object to format the code snippet.
+ * It applies padding to line numbers and can trigger custom actions for specific lines.
+ *
+ * @param code - The source code | stack to be formatted.
+ * @param options - Configuration options for formatting the code.
+ *   - `padding` (number, optional): Number of characters for line number padding. Defaults to 10.
+ *   - `startLine` (number, optional): The starting line number for formatting. Defaults to 1.
+ *   - `action` (object, optional): Custom actions to apply to specific lines.
+ *     - `triggerLine` (number): The line number where the action should be triggered.
+ *     - `callback` (function): A callback function to format the line string when `triggerLine` is matched.
+ *       The callback receives the formatted line string, the padding value, and the current line number as arguments.
+ *
+ * @returns A formatted string of the code snippet with applied padding and custom actions.
+ *
+ * @example
+ * ```typescript
+ * const formattedCode = formatCode(code, {
+ *     padding: 8,
+ *     startLine: 5,
+ *     action: {
+ *         triggerLine: 7,
+ *         callback: (lineString, padding, lineNumber) => {
+ *             return `Custom formatting for line ${lineNumber}: ${lineString}`;
+ *         }
+ *     }
+ * });
+ * console.log(formattedCode);
+ * ```
+ */
+export declare function formatCode(code: string, options?: FormatCodeInterface): string;
+/**
+ * Formats a code snippet around an error location with special highlighting.
+ *
+ * This function takes a `sourcePosition` object containing information about the source code
+ * and error location, then uses `formatCode` to format and highlight the relevant code snippet.
+ *
+ * @param sourcePosition - An object containing information about the source code and error location.
+ *   - `code` (string): The entire source code content.
+ *   - `line` (number): The line number where the error occurred (1-based indexing).
+ *   - `column` (number): The column number within the line where the error occurred (1-based indexing).
+ *   - `startLine` (number, optional): The starting line number of the code snippet (defaults to 1).
+ * @param ansiOption - Optional configuration for ANSI color codes.
+ *   - `color` (string): The ANSI escape sequence to colorize the error marker and prefix (e.g., `'\x1b[38;5;160m'`).
+ *   - `reset` (string): The ANSI escape sequence to reset the color (e.g., `'\x1b[0m'`).
+ *
+ * @throws Error - If the provided `sourcePosition` object has invalid line or column numbers,
+ *                  or if the error line is outside the boundaries of the provided code content.
+ *
+ * @returns A formatted string representing the relevant code snippet around the error location,
+ *          including special highlighting for the error line and column.
+ *
+ * @example
+ * ```typescript
+ * const formattedErrorCode = formatErrorCode(sourcePosition);
+ * console.log(formattedErrorCode);
+ * ```
+ */
+export declare function formatErrorCode(sourcePosition: PositionWithCodeInterface, ansiOption?: AnsiOptionInterface): string;