@remotex-labs/xmap 2.0.4 → 3.0.0

package/dist/components/highlighter.component.d.ts

@@ -1,26 +1,28 @@
+/**
+ * Export interfaces
+ */
+export type { HighlightSchemeInterface, HighlightNodeSegmentInterface } from "./interfaces/highlighter-component.interface";
 /**
  * Import will remove at compile time
  */
-import type { HighlightSchemeInterface } from "./interfaces/highlighter.interface";
+import type { HighlightSchemeInterface } from "./interfaces/highlighter-component.interface";
 /**
  * Imports
  */
 import * as ts from 'typescript';
 /**
- * An enum containing ANSI escape sequences for various colors.
+ * An enum containing ANSI escape sequences for various colors
  *
+ * @remarks
  * This enum is primarily intended for terminal output and won't work directly in JavaScript for web development.
- * It defines color codes for various colors and a reset code to return to
- * the default text color.
+ * It defines color codes for various colors and a reset code to return to the default text color.
  *
  * @example
- * ```typescript
- * console.log(`${Colors.red}This the text will be red in the terminal.${Colors.reset}`);
+ * ```ts
+ * console.log(`${Colors.red}This text will be red in the terminal.${Colors.reset}`);
  * ```
  *
- * This functionality is limited to terminal environments.
- * Consider alternative methods
- * for color highlighting in web development contexts, such as CSS classes.
+ * @since 1.0.0
  */
 export declare const enum Colors {
     reset = "\u001B[0m",
@@ -38,149 +40,301 @@ export declare const enum Colors {
     brightPink = "\u001B[38;5;197m"
 }
 /**
- * Class responsible for applying semantic highlighting to a source code string based on a given color scheme.
+ * Class responsible for applying semantic highlighting to a source code string based on a given color scheme
  *
- * @class
+ * @remarks
+ * Processes TypeScript AST nodes and applies color formatting to different code elements
+ * according to the provided color scheme.
  *
- * @param sourceFile - The TypeScript AST node representing the source file.
- * @param code - The source code string to be highlighted.
- * @param schema - The color scheme used for highlighting different elements in the code.
+ * @example
+ * ```ts
+ * const sourceFile = ts.createSourceFile('example.ts', code, ts.ScriptTarget.Latest);
+ * const highlighter = new CodeHighlighter(sourceFile, code, customScheme);
+ * highlighter.parseNode(sourceFile);
+ * const highlightedCode = highlighter.highlight();
+ * ```
  *
- * const highlighter = new CodeHighlighter(sourceFile, code, schema);
+ * @since 1.0.0
  */
 export declare class CodeHighlighter {
     private sourceFile;
     private code;
     private schema;
     /**
-     * A Map of segments where the key is a combination of start and end positions,
-     * and the value is an object containing the color and reset code.
+     * A Map of segments where the key is a combination of start and end positions.
+     *
+     * @remarks
      * This structure ensures unique segments and allows for fast lookups and updates.
      *
-     * @example
-     * this.segments = new Map([
-     *   ['0-10', { start: 1, end: 11, color: '\x1b[31m', reset: '\x1b[0m' }],
-     *   ['11-20', { start: 12, end: 20, color: '\x1b[32m', reset: '\x1b[0m' }]
-     * ]);
+     * @see HighlightNodeSegmentInterface
+     * @since 1.0.0
      */
     private segments;
     /**
      * Creates an instance of the CodeHighlighter class.
      *
-     * @param sourceFile - The TypeScript AST node representing the source file.
-     * @param code - The source code string to be highlighted.
-     * @param schema - The color scheme used for highlighting different elements in the code.
+     * @param sourceFile - The TypeScript AST node representing the source file
+     * @param code - The source code string to be highlighted
+     * @param schema - The color scheme used for highlighting different elements in the code
+     *
+     * @since 1.0.0
      */
     constructor(sourceFile: ts.Node, code: string, schema: HighlightSchemeInterface);
     /**
      * Parses a TypeScript AST node and processes its comments to identify segments that need highlighting.
      *
-     * @param node - The TypeScript AST node to be parsed.
+     * @param node - The TypeScript AST node to be parsed
+     *
+     * @since 1.0.0
      */
     parseNode(node: ts.Node): void;
     /**
      * Generates a string with highlighted code segments based on the provided color scheme.
      *
+     * @returns The highlighted code as a string, with ANSI color codes applied to the segments
+     *
+     * @remarks
      * This method processes the stored segments, applies the appropriate colors to each segment,
      * and returns the resulting highlighted code as a single string.
      *
-     * @returns The highlighted code as a string, with ANSI color codes applied to the segments.
+     * @since 1.0.0
      */
     highlight(): string;
     /**
-     * Extracts a substring from the code based on the specified start and end positions.
+     * Extracts a text segment from the source code using position indices.
+     *
+     * @param start - The starting index position in the source text
+     * @param end - The ending index position in the source text (optional)
+     * @returns The substring of source text between the start and end positions
+     *
+     * @remarks
+     * This utility method provides access to specific portions of the source code
+     * based on character positions. When the end parameter is omitted, the extraction
+     * will continue to the end of the source text.
+     *
+     * This method is typically used during the highlighting process to access the
+     * actual text content that corresponds to syntax nodes or other text ranges
+     * before applying formatting.
+     *
+     * @example
+     * ```ts
+     * // Extract a variable name
+     * const variableName = this.getSegmentSource(10, 15);
      *
-     * This method is used to retrieve the source code segment that corresponds to the
-     * given start and end positions. It is primarily used for highlighting specific
-     * segments of the code.
+     * // Extract from a position to the end of source
+     * const remaining = this.getSegmentSource(100);
+     * ```
      *
-     * @param start - The starting index of the segment to be extracted.
-     * @param end - The ending index of the segment to be extracted.
-     * @returns The extracted substring from the code.
+     * @see addSegment
+     * @see highlight
+     *
+     * @since 1.0.0
      */
     private getSegmentSource;
     /**
-     * Adds a new segment to the list of segments to be highlighted.
-     * The segment is defined by its start and end positions, the color to apply, and an optional reset code.
+     * Registers a text segment for syntax highlighting with specified style information.
+     *
+     * @param start - The starting position of the segment in the source text
+     * @param end - The ending position of the segment in the source text
+     * @param color - The color code to apply to this segment
+     * @param reset - The color reset code to apply after the segment (defaults to the standard reset code)
+     *
+     * @remarks
+     * This method creates a unique key for each segment based on its position and stores the segment information in a map.
+     * Each segment contains its position information, styling code,
+     * and reset code which will later be used during the highlighting process.
+     *
+     * If multiple segments are added with the same positions, the later additions will
+     * overwrite earlier ones due to the map's key-based storage.
+     *
+     * @example
+     * ```ts
+     * // Highlight a variable name in red
+     * this.addSegment(10, 15, Colors.red);
+     *
+     * // Highlight a keyword with custom color and reset
+     * this.addSegment(20, 26, Colors.blue, Colors.customReset);
+     * ```
      *
-     * @param start - The starting index of the segment in the code string.
-     * @param end - The ending index of the segment in the code string.
-     * @param color - The color code to apply to the segment.
-     * @param reset - The color reset code to apply after the segment, Defaults to the reset code defined in `Colors.reset`.
+     * @see Colors
+     * @see processNode
+     *
+     * @since 1.0.0
      */
     private addSegment;
     /**
-     * Processes comments within a TypeScript AST node and adds segments for highlighting.
-     * Extracts trailing and leading comments from the node and adds them as segments using the color defined in `this.colorSchema.comments`.
+     * Processes and highlights comments associated with a TypeScript AST node.
+     *
+     * @param node - The TypeScript AST node whose comments are to be processed
+     *
+     * @remarks
+     * This method identifies both leading and trailing comments associated with the given node
+     * and adds them to the highlighting segments.
+     * The comments are extracted from the full source text using TypeScript's utility functions
+     * and are highlighted using the color specified
+     * in the schema's commentColor property.
+     *
+     * Leading comments appear before the node, while trailing comments appear after it.
+     * Both types are processed with the same highlighting style.
+     *
+     * @example
+     * ```ts
+     * // For a node that might have comments like:
+     * // This is a leading comment
+     * const x = 5; // This is a trailing comment
      *
-     * @param node - The TypeScript AST node whose comments are to be processed.
+     * this.processComments(someNode);
+     * // Both comments will be added to segments with the comment color
+     * ```
+     *
+     * @see addSegment
+     * @see ts.getLeadingCommentRanges
+     * @see ts.getTrailingCommentRanges
+     *
+     * @since 1.0.0
      */
     private processComments;
     /**
-     * Processes the keywords within a TypeScript AST node and adds them as segments for highlighting.
+     * Processes TypeScript keywords and primitive type references in an AST node for syntax highlighting.
+     *
+     * @param node - The TypeScript AST node to be processed for keywords
+     *
+     * @remarks
+     * This method handles two categories of tokens that require special highlighting:
      *
-     * This method identifies potential keyword tokens within the provided node and adds them to the
-     * list of segments with the color defined in `this.schema.keywordColor`.
-     * The method considers the current node, its first token, and its last token to determine if they should be highlighted
-     * as keywords.
+     * 1. Primitive type references: Highlights references to built-in types like `null`,
+     *    `void`, `string`, `number`, `boolean`, and `undefined` using the type color.
      *
-     * The method checks if the node's kind falls within the range of keyword kinds defined by TypeScript.
-     * If the node or any of its tokens are identified as keywords, a segment is added to `this.segments`
-     * with the start and end positions of the node and the specified color for keywords.
+     * 2. TypeScript keywords: Identifies any node whose kind falls within the TypeScript
+     *    keyword range (between FirstKeyword and LastKeyword) and highlights it using
+     *    the keyword color.
+     *
+     * Each identified token is added to the segments collection with appropriate position
+     * and color information.
+     *
+     * @example
+     * ```ts
+     * // Inside syntax highlighting process
+     * this.processKeywords(someNode);
+     * // If the node represents a keyword like 'const' or a primitive type like 'string',
+     * // it will be added to the segments with the appropriate color
+     * ```
      *
-     * @param  node - The TypeScript AST node to be processed for keywords.
+     * @see addSegment
+     * @see ts.SyntaxKind
+     *
+     * @since 1.0.0
      */
     private processKeywords;
     /**
-     * Processes identifiers within a TypeScript AST node and adds them as segments for highlighting
-     * based on the node's parent type.
+     * Processes identifier nodes and applies appropriate syntax highlighting based on their context.
+     *
+     * @param node - The TypeScript AST node representing the identifier to be processed
+     *
+     * @remarks
+     * This method determines the appropriate color for an identifier by examining its parent node's kind.
+     * Different colors are applied based on the identifier's role in the code:
+     * - Enum members use enumColor
+     * - Interface names use interfaceColor
+     * - Class names use classColor
+     * - Function and method names use functionColor
+     * - Parameters use parameterColor
+     * - Variables and properties use variableColor
+     * - Types use typeColor
+     * - And more specialized cases for other syntax kinds
+     *
+     * Special handling is applied to property access expressions to differentiate between
+     * the object being accessed and the property being accessed.
+     *
+     * @example
+     * ```ts
+     * // Inside the CodeHighlighter class
+     * const identifierNode = getIdentifierNode(); // Get some identifier node
+     * this.processIdentifier(identifierNode);
+     * // The identifier is now added to segments with appropriate color based on its context
+     * ```
      *
-     * This method determines the appropriate color for an identifier based on its parent node's kind.
-     * If the parent node matches one of the specified kinds, the identifier is highlighted with a cyan color.
-     * Supported parent kinds include various declarations, expressions, and signatures.
+     * @see addSegment
+     * @see HighlightSchemeInterface
      *
-     * @param node - The TypeScript AST node representing the identifier to be processed.
+     * @since 1.0.0
      */
     private processIdentifier;
     /**
-     * Processes a TypeScript template expression and adds segments for highlighting its literal parts.
+     * Processes a TypeScript template expression and adds highlighting segments for its literal parts.
      *
-     * This method adds a segment for the head of the template expression with the color specified in `this.schema.stringColor`.
-     * It also processes each template span within the expression, adding
-     * segments for each span's literal part.
+     * @param templateExpression - The TypeScript template expression to be processed
      *
-     * @param templateExpression - The TypeScript template expression to be processed.
+     * @remarks
+     * This method adds color segments for both the template head and each template span's literal part.
+     * All template string components are highlighted using the color defined in the schema's stringColor.
+     *
+     * @example
+     * ```ts
+     * // Given a template expression like: `Hello ${name}`
+     * this.processTemplateExpression(templateNode);
+     * // Both "Hello " and the closing part after the expression will be highlighted
+     * ```
+     *
+     * @see addSegment
+     *
+     * @since 1.0.0
      */
     private processTemplateExpression;
     /**
-     * Processes a TypeScript AST node and adds segments for highlighting based on the node's kind.
+     * Processes a TypeScript AST node and adds highlighting segments based on the node's kind.
      *
-     * This method identifies the kind of the node and determines the appropriate color for highlighting.
-     * It handles various node kinds including string literals, regular expressions, template expressions, and identifiers.
-     * Specific methods are invoked for more complex node kinds, such as template expressions and identifiers.
+     * @param node - The TypeScript AST node to be processed
      *
-     * @param  node - The TypeScript AST node to be processed.
+     * @remarks
+     * This method identifies the node's kind and applies the appropriate color for highlighting.
+     * It handles various syntax kinds including literals (string, numeric, regular expressions),
+     * template expressions, identifiers, and type references.
+     * For complex node types like template expressions and identifiers, it delegates to specialized processing methods.
+     *
+     * @throws Error - When casting to TypeParameterDeclaration fails for non-compatible node kinds
+     *
+     * @example
+     * ```ts
+     * // Inside the CodeHighlighter class
+     * const node = sourceFile.getChildAt(0);
+     * this.processNode(node);
+     * // Node is now added to the segments map with appropriate colors
+     * ```
+     *
+     * @see processTemplateExpression
+     * @see processIdentifier
+     *
+     * @since 1.0.0
      */
     private processNode;
 }
 /**
  * Applies semantic highlighting to the provided code string using the specified color scheme.
  *
- * @param code - The source code to be highlighted.
- * @param schema - An optional partial schema defining the color styles for various code elements.
- *                 Defaults to an empty object, which means no specific highlighting will be applied.
+ * @param code - The source code to be highlighted
+ * @param schema - An optional partial schema defining the color styles for various code elements
+ *
+ * @returns A string with the code elements wrapped in the appropriate color styles
  *
- * @returns A string with the code elements wrapped in the appropriate color styles as specified by the schema.
+ * @remarks
+ * If no schema is provided, the default schema will be used. The function creates a TypeScript
+ * source file from the provided code and walks through its AST to apply syntax highlighting.
  *
  * @example
+ * ```ts
  * const code = 'const x: number = 42;';
  * const schema = {
  *   keywordColor: '\x1b[34m', // Blue
- *   stringColor: '\x1b[32m',  // Green
  *   numberColor: '\x1b[31m',  // Red
- *   reset: '\x1b[0m'          // Reset
  * };
  * const highlightedCode = highlightCode(code, schema);
  * console.log(highlightedCode);
+ * ```
+ *
+ * @see CodeHighlighter
+ * @see HighlightSchemeInterface
+ *
+ * @since 1.0.0
  */
 export declare function highlightCode(code: string, schema?: Partial<HighlightSchemeInterface>): string;

package/dist/components/interfaces/{formatter.interface.d.ts → formatter-component.interface.d.ts}

@@ -1,42 +1,60 @@
 /**
- * A callback function type used for formatting code lines.
+ * 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 The formatted line string.
+ * @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.
+ * Configuration options for formatting code
+ *
+ * @since 1.0.0
  */
 export interface FormatCodeInterface {
     /**
-     * The amount of padding to be applied to each line. If not specified, defaults to 0.
+     * The amount of padding to be applied to each line
+     * @since 1.0.0
      */
     padding?: number;
     /**
-     * The starting line number for formatting. If not specified, defaults to 1.
+     * 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;
     };
 }
 /**
- * Set color to an error pointer
+ * 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;
 }

package/dist/components/interfaces/highlighter-component.interface.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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
+ */
+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;
+}
+/**
+ * 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
+ */
+export interface HighlightNodeSegmentInterface {
+    end: number;
+    start: number;
+    color: string;
+    reset: string;
+}

package/dist/components/interfaces/parse-component.interface.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Interface representing a stack frame in a stack trace.
+ *
+ * This structure provides detailed information about the location
+ * of a specific frame in the stack trace, primarily used in error debugging and stack analysis.
+ * It optionally includes information about the line, column, file, function name, and other details
+ * about the origin of the code.
+ *
+ * Properties:
+ * - source: The source code relevant to the stack frame.
+ * - line: An optional line number in the code associated with this frame.
+ * - column: An optional column number in the line associated with this frame.
+ * - fileName: The name of the file associated with the frame, if available.
+ * - functionName: The name of the function where the stack frame is located, if available.
+ * - eval: Indicates if the stack frame originates from an evaluated script.
+ * - async: Indicates if the stack frame is part of an asynchronous operation.
+ * - native: Indicates if the stack frame is part of native code execution.
+ * - constructor: Indicates if the frame is related to an object constructor invocation.
+ * - evalOrigin: Optional information about the origin of the code if it resulted from an eval execution,
+ * including line number, column number, file name, and function name.
+ *
+ * @since 3.0.0
+ */
+export interface StackFrame {
+    source: string;
+    line?: number;
+    column?: number;
+    fileName?: string;
+    functionName?: string;
+    eval: boolean;
+    async: boolean;
+    native: boolean;
+    constructor: boolean;
+    evalOrigin?: {
+        line?: number;
+        column?: number;
+        fileName?: string;
+        functionName?: string;
+    };
+}
+/**
+ * Represents a fully parsed error stack trace with structured information
+ *
+ * @see StackFrame
+ * @since 2.1.0
+ */
+export interface ParsedStackTrace {
+    name: string;
+    message: string;
+    stack: StackFrame[];
+    rawStack: string;
+}