@remotex-labs/xmap 3.0.1 → 3.0.3

package/dist/formatter.component.d.ts

@@ -0,0 +1,258 @@
+/**
+ * A callback function for formatting code lines
+ *
+ * @param lineString - The content of the line to be formatted
+ * @param padding - The amount of padding to be applied to the line
+ * @param line - The line number of the line to be formatted
+ * @returns Formatted line string
+ *
+ * @since 1.0.0
+ */
+export type FormatCodeCallbackType = (lineString: string, padding: number, line: number) => string;
+/**
+ * Configuration options for formatting code
+ *
+ * @since 1.0.0
+ */
+export interface FormatCodeInterface {
+    /**
+     * The amount of padding to be applied to each line
+     * @since 1.0.0
+     */
+    padding?: number;
+    /**
+     * The starting line number for formatting
+     * @since 1.0.0
+     */
+    startLine?: number;
+    /**
+     * An optional action object specifying a line where a callback function should be triggered.
+     * @since 1.0.0
+     */
+    action?: {
+        /**
+         * The line number at which the callback function should be triggered.
+         * @since 1.0.0
+         */
+        triggerLine: number;
+        /**
+         * The callback function to be executed when the trigger line is encountered.
+         * @since 1.0.0
+         */
+        callback: FormatCodeCallbackType;
+    };
+}
+/**
+ * Configuration for ANSI color styling of error pointers
+ * @since 1.0.0
+ */
+export interface AnsiOptionInterface {
+    /**
+     * ANSI color code to apply to the error pointer
+     * @since 1.0.0
+     */
+    color: string;
+    /**
+     * ANSI reset code to restore default styling after the error pointer
+     * @since 1.0.0
+     */
+    reset: string;
+}
+/**
+ * Represents a source map structure used for mapping code within a file to its original source
+ * @since 1.0.0
+ */
+export interface SourceMapInterface {
+    /**
+     * The generated file's name that the source map is associated with
+     * @since 1.0.0
+     */
+    file?: string | null;
+    /**
+     * An array of variable/function names present in the original source
+     * @since 1.0.0
+     */
+    names: Array<string>;
+    /**
+     * The version of the source map specification (standard is 3)
+     * @since 1.0.0
+     */
+    version: number;
+    /**
+     * An array of URLs or paths to the original source files
+     * @since 1.0.0
+     */
+    sources: Array<string>;
+    /**
+     * VLQ encoded string that maps generated code back to original source code
+     * @since 1.0.0
+     */
+    mappings: string;
+    /**
+     * Root URL for resolving the sources
+     * @since 1.0.0
+     */
+    sourceRoot?: string | null;
+    /**
+     * Array containing the content of the original source files
+     * @since 1.0.0
+     */
+    sourcesContent?: Array<string>;
+}
+/**
+ * Represents a position in source code with mapping information
+ * @since 1.0.0
+ */
+export interface PositionInterface {
+    /**
+     * Name of the identifier at this position
+     * @since 1.0.0
+     */
+    name: string | null;
+    /**
+     * Line number in the original source
+     * @since 1.0.0
+     */
+    line: number;
+    /**
+     * Column number in the original source
+     * @since 1.0.0
+     */
+    column: number;
+    /**
+     * Path or URL to the original source file
+     * @since 1.0.0
+     */
+    source: string;
+    /**
+     * Root URL for resolving the source
+     * @since 1.0.0
+     */
+    sourceRoot: string | null;
+    /**
+     * Index of the source in the sources array
+     * @since 1.0.0
+     */
+    sourceIndex: number;
+    /**
+     * Line number in the generated code
+     * @since 1.0.0
+     */
+    generatedLine: number;
+    /**
+     * Column number in the generated code
+     * @since 1.0.0
+     */
+    generatedColumn: number;
+}
+/**
+ * Position in source code including the original source content
+ *
+ * @see PositionInterface
+ * @since 1.0.0
+ */
+export interface PositionWithContentInterface extends PositionInterface {
+    /**
+     * Content of the original source file
+     * @since 1.0.0
+     */
+    sourcesContent: string;
+}
+/**
+ * Position in source code including code fragment information
+ *
+ * @see PositionInterface
+ * @since 1.0.0
+ */
+export interface PositionWithCodeInterface extends PositionInterface {
+    /**
+     * Code fragment from the original source
+     * @since 1.0.0
+     */
+    code: string;
+    /**
+     * Ending line number of the code fragment
+     * @since 1.0.0
+     */
+    endLine: number;
+    /**
+     * Starting line number of the code fragment
+     * @since 1.0.0
+     */
+    startLine: number;
+}
+/**
+ * Options for retrieving source code context
+ * @since 1.0.0
+ */
+export interface SourceOptionsInterface {
+    /**
+     * Number of lines to include after the target line
+     * @since 1.0.0
+     */
+    linesAfter?: number;
+    /**
+     * Number of lines to include before the target line
+     * @since 1.0.0
+     */
+    linesBefore?: number;
+}
+/**
+ * Formats a code snippet with optional line padding and custom actions
+ *
+ * @param code - The source code | stack to be formatted
+ * @param options - Configuration options for formatting the code
+ * @returns A formatted string of the code snippet with applied padding and custom actions
+ *
+ * @remarks
+ * 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.
+ * Options include padding (default 10), startLine (default 0), and custom actions for specific lines.
+ *
+ * @example
+ * ```ts
+ * const formattedCode = formatCode(code, {
+ *     padding: 8,
+ *     startLine: 5,
+ *     action: {
+ *         triggerLine: 7,
+ *         callback: (lineString, padding, lineNumber) => {
+ *             return `Custom formatting for line ${lineNumber}: ${lineString}`;
+ *         }
+ *     }
+ * });
+ * ```
+ *
+ * @since 1.0.0
+ */
+export function formatCode(code: string, options?: FormatCodeInterface): string;
+/**
+ * Formats a code snippet around an error location with special highlighting
+ *
+ * @param sourcePosition - An object containing information about the source code and error location
+ * @param ansiOption - Optional configuration for ANSI color codes
+ * @returns A formatted string representing the relevant code snippet with error highlighting
+ *
+ * @throws Error - If the provided sourcePosition object has invalid line or column numbers
+ *
+ * @remarks
+ * This function takes a sourcePosition object with code content and error location information,
+ * then uses formatCode to format and highlight the relevant code snippet around the error.
+ * The sourcePosition object should contain code (string), line (number), column (number),
+ * and optional startLine (number, defaults to 1).
+ *
+ * @example
+ * ```ts
+ * const formattedErrorCode = formatErrorCode({
+ *     code: "const x = 1;\nconst y = x.undefined;\n",
+ *     line: 2,
+ *     column: 15,
+ *     startLine: 1
+ * });
+ * ```
+ *
+ * @see formatCode - The underlying function used for basic code formatting
+ *
+ * @since 1.0.0
+ */
+export function formatErrorCode(sourcePosition: PositionWithCodeInterface, ansiOption?: AnsiOptionInterface): string;

package/dist/{components/highlighter.component.d.ts → highlighter.component.d.ts}

@@ -1,15 +1,98 @@
+import * as ts from "typescript";
 /**
- * Export interfaces
- */
-export type * from "./interfaces/highlighter-component.interface";
-/**
- * Import will remove at compile time
+ * Defines the color scheme for syntax highlighting different code elements.
+ *
+ * @interface HighlightSchemeInterface
+ *
+ * @property enumColor - Color code for enum declarations and references
+ * @property typeColor - Color code for type annotations and primitive types
+ * @property classColor - Color code for class declarations and references
+ * @property stringColor - Color code for string literals and template strings
+ * @property keywordColor - Color code for language keywords
+ * @property commentColor - Color code for comments (single-line and multi-line)
+ * @property functionColor - Color code for function declarations and calls
+ * @property variableColor - Color code for variable declarations and references
+ * @property interfaceColor - Color code for interface declarations and references
+ * @property parameterColor - Color code for function and method parameters
+ * @property getAccessorColor - Color code for getter accessor methods
+ * @property numericLiteralColor - Color code for numeric literals
+ * @property methodSignatureColor - Color code for method signatures in interfaces
+ * @property regularExpressionColor - Color code for regular expression literals
+ * @property propertyAssignmentColor - Color code for property assignments in object literals
+ * @property propertyAccessExpressionColor - Color code for property access expressions
+ * @property expressionWithTypeArgumentsColor - Color code for type arguments in expressions
+ *
+ * @example
+ * ```ts
+ * const darkTheme: HighlightSchemeInterface = {
+ *   enumColor: Colors.cyan,
+ *   typeColor: Colors.blue,
+ *   classColor: Colors.yellow,
+ *   // ...other color definitions
+ * };
+ * ```
+ *
+ * @since 1.0.0
  */
-import type { HighlightSchemeInterface } from "./interfaces/highlighter-component.interface";
+export interface HighlightSchemeInterface {
+    enumColor: string;
+    typeColor: string;
+    classColor: string;
+    stringColor: string;
+    keywordColor: string;
+    commentColor: string;
+    functionColor: string;
+    variableColor: string;
+    interfaceColor: string;
+    parameterColor: string;
+    getAccessorColor: string;
+    numericLiteralColor: string;
+    methodSignatureColor: string;
+    regularExpressionColor: string;
+    propertyAssignmentColor: string;
+    propertyAccessExpressionColor: string;
+    expressionWithTypeArgumentsColor: string;
+}
 /**
- * Imports
+ * Represents a segment of source code to be highlighted with specific styling.
+ *
+ * @interface HighlightNodeSegmentInterface
+ *
+ * @property start - The starting character position of the segment in the source text
+ * @property end - The ending character position of the segment in the source text
+ * @property color - The color or style code to apply to this segment
+ * @property reset - The reset code that returns formatting to normal after this segment
+ *
+ * @remarks
+ * Segments are the fundamental units of the highlighting system.
+ * Each segment represents a portion of text that should receive specific styling.
+ * When the source code is processed for display,
+ * these segments are used to insert the appropriate color/style codes at the correct positions.
+ *
+ * The highlighter maintains a collection of these segments and applies them
+ * in position order to create the complete highlighted output.
+ *
+ * @example
+ * ```ts
+ * const keywordSegment: HighlightNodeSegmentInterface = {
+ *   start: 0,
+ *   end: 6,
+ *   color: '\x1b[34m', // Blue for the keyword "import"
+ *   reset: '\x1b[0m'   // Reset to default
+ * };
+ * ```
+ *
+ * @see HighlightSchemeInterface
+ * @see addSegment
+ *
+ * @since 1.0.0
  */
-import * as ts from 'typescript';
+export interface HighlightNodeSegmentInterface {
+    end: number;
+    start: number;
+    color: string;
+    reset: string;
+}
 /**
  * An enum containing ANSI escape sequences for various colors
  *
@@ -24,7 +107,7 @@ import * as ts from 'typescript';
  *
  * @since 1.0.0
  */
-export declare const enum Colors {
+export const enum Colors {
     reset = "\u001B[0m",
     gray = "\u001B[38;5;243m",
     darkGray = "\u001B[38;5;238m",
@@ -56,7 +139,7 @@ export declare const enum Colors {
  *
  * @since 1.0.0
  */
-export declare class CodeHighlighter {
+export class CodeHighlighter {
     private sourceFile;
     private code;
     private schema;
@@ -337,4 +420,4 @@ export declare class CodeHighlighter {
  *
  * @since 1.0.0
  */
-export declare function highlightCode(code: string, schema?: Partial<HighlightSchemeInterface>): string;
+export function highlightCode(code: string, schema?: Partial<HighlightSchemeInterface>): string;