@remotex-labs/xmap
Version:
A library with a sourcemap parser and TypeScript code formatter for the CLI
462 lines (459 loc) • 15.1 kB
TypeScript
/**
* This file was automatically generated by xBuild.
* DO NOT EDIT MANUALLY.
*/
import ts from 'typescript';
/**
* Represents a function that applies coloring or formatting to strings.
*
* @param args - Strings to be formatted
* @returns The formatted string
*
* @since 1.0.0
*/
type ColorFunctionType = (...args: Array<string>) => string;
/**
* Defines a color scheme for syntax highlighting various code elements.
*
* @remarks
* Each property is a {@link ColorFunctionType} that formats a specific type of syntax element,
* such as enums, classes, keywords, or literals.
*
* @see ColorFunctionType
* @since 1.0.0
*/
interface HighlightSchemeInterface {
/**
* Color function for enum names.
* @since 1.0.0
*/
enumColor: ColorFunctionType;
/**
* Color function for type names.
* @since 1.0.0
*/
typeColor: ColorFunctionType;
/**
* Color function for class names.
* @since 1.0.0
*/
classColor: ColorFunctionType;
/**
* Color function for string literals.
* @since 1.0.0
*/
stringColor: ColorFunctionType;
/**
* Color function for language keywords.
* @since 1.0.0
*/
keywordColor: ColorFunctionType;
/**
* Color function for comments.
* @since 1.0.0
*/
commentColor: ColorFunctionType;
/**
* Color function for function names.
* @since 1.0.0
*/
functionColor: ColorFunctionType;
/**
* Color function for variable names.
* @since 1.0.0
*/
variableColor: ColorFunctionType;
/**
* Color function for interface names.
* @since 1.0.0
*/
interfaceColor: ColorFunctionType;
/**
* Color function for function/method parameters.
* @since 1.0.0
*/
parameterColor: ColorFunctionType;
/**
* Color function for getter accessor names.
* @since 1.0.0
*/
getAccessorColor: ColorFunctionType;
/**
* Color function for numeric literals.
* @since 1.0.0
*/
numericLiteralColor: ColorFunctionType;
/**
* Color function for method signatures.
* @since 1.0.0
*/
methodSignatureColor: ColorFunctionType;
/**
* Color function for regular expressions.
* @since 1.0.0
*/
regularExpressionColor: ColorFunctionType;
/**
* Color function for property assignments.
* @since 1.0.0
*/
propertyAssignmentColor: ColorFunctionType;
/**
* Color function for property access expressions.
* @since 1.0.0
*/
propertyAccessExpressionColor: ColorFunctionType;
/**
* Color function for expressions with type arguments.
* @since 1.0.0
*/
expressionWithTypeArgumentsColor: ColorFunctionType;
}
/**
* Represents a segment of source code to be highlighted with specific styling.
*
* @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: xterm.red
* };
* ```
*
* @see addSegment
* @see HighlightSchemeInterface
*
* @since 1.0.0
*/
interface HighlightNodeSegmentInterface {
/**
* The starting character position of the segment in the source text.
* @since 1.0.0
*/
start: number;
/**
* The ending character position of the segment in the source text.
* @since 1.0.0
*/
end: number;
/**
* The color or style code to apply to this segment.
* @since 1.0.0
*/
color: ColorFunctionType;
}
/**
* Class responsible for applying semantic highlighting to a source code string based on a given color scheme
*
* @remarks
* Processes TypeScript AST nodes and applies color formatting to different code elements
* according to the provided color scheme.
*
* @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();
* ```
*
* @since 1.0.0
*/
declare class CodeHighlighter {
private sourceFile;
private code;
private schema;
/**
* 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.
*
* @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
*
* @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
*
* @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.
*
* @since 1.0.0
*/
highlight(): string;
/**
* 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 a 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);
*
* // Extract from a position to the end of a source
* const remaining = this.getSegmentSource(100);
* ```
*
* @see addSegment
* @see highlight
*
* @since 1.0.0
*/
private getSegmentSource;
/**
* 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 {@link ColorFunctionType} to apply to this segment
*
* @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, xterm.red);
*
* // Highlight a keyword with custom color
* this.addSegment(20, 26, xterm.blue);
* ```
*
* @see Colors
* @see processNode
*
* @since 1.0.0
*/
private addSegment;
/**
* 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
*
* 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 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:
*
* 1. Primitive type references: Highlights references to built-in types like `null`,
* `void`, `string`, `number`, `boolean`, and `undefined` using the type color.
*
* 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 segment collection with the 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
* ```
*
* @see addSegment
* @see ts.SyntaxKind
*
* @since 1.0.0
*/
private processKeywords;
/**
* 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
* ```
*
* @see addSegment
* @see HighlightSchemeInterface
*
* @since 1.0.0
*/
private processIdentifier;
/**
* Processes a TypeScript template expression and adds highlighting segments for its literal parts.
*
* @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 highlighting segments based on the node's kind.
*
* @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 segment 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
*
* @returns A string with the code elements wrapped in the appropriate color styles
*
* @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
* numberColor: '\x1b[31m', // Red
* };
* const highlightedCode = highlightCode(code, schema);
* console.log(highlightedCode);
* ```
*
* @see CodeHighlighter
* @see HighlightSchemeInterface
*
* @since 1.0.0
*/
declare function highlightCode(code: string, schema?: Partial<HighlightSchemeInterface>): string;
export {
CodeHighlighter,
ColorFunctionType,
HighlightNodeSegmentInterface,
HighlightSchemeInterface,
highlightCode
};