llmxml/src/types/index.ts

Convert between markdown and LLM-friendly pseudo-XML

/**
 * Core types for the LLMXML library
 */

/**
 * Base node interface for the AST
 */
export interface ASTNode {
  /** Type identifier for the node */
  type: string;
  /** Optional child nodes */
  children?: ASTNode[];
}

/**
 * Represents a Markdown heading (# Title)
 */
export interface HeadingNode extends ASTNode {
  type: 'heading';
  /** Heading level (1-6) corresponding to #, ##, etc. */
  depth: number;
  /** The text content of the heading */
  text: string;
}

/**
 * Represents a plain text node
 */
export interface TextNode extends ASTNode {
  type: 'text';
  /** The raw text content */
  value: string;
}

/**
 * Represents a code block (```lang\ncode\n```)
 */
export interface CodeBlockNode extends ASTNode {
  type: 'code';
  /** The code block content */
  value: string;
  /** Optional language identifier */
  lang?: string;
}

/**
 * Represents an ordered or unordered list
 */
export interface ListNode extends ASTNode {
  type: 'list';
  /** Whether this is an ordered (1. 2.) or unordered (- *) list */
  ordered: boolean;
  /** The list items */
  children: ListItemNode[];
}

/**
 * Represents a single item in a list
 */
export interface ListItemNode extends ASTNode {
  type: 'listItem';
  /** The content of the list item */
  children: ASTNode[];
}

/**
 * Represents a paragraph of text, which may contain formatted elements
 */
export interface ParagraphNode extends ASTNode {
  type: 'paragraph';
  /** The paragraph's content nodes */
  children: (TextNode | EmphasisNode | LinkNode)[];
}

/**
 * Represents emphasized text (*italic* or **bold**)
 */
export interface EmphasisNode extends ASTNode {
  /** 'emphasis' for *italic*, 'strong' for **bold** */
  type: 'emphasis' | 'strong';
  /** The emphasized text */
  children: TextNode[];
}

/**
 * Represents a hyperlink [text](url)
 */
export interface LinkNode extends ASTNode {
  type: 'link';
  /** The link's destination URL */
  url: string;
  /** The link text */
  children: TextNode[];
}

/**
 * Represents a pseudo-XML tag in the LLM format
 */
export interface TagNode extends ASTNode {
  type: 'tag';
  /** The tag name, derived from the heading text */
  name: string;
  /** Tag attributes */
  attributes: {
    /** Original heading text */
    title: string;
    /** Original heading level */
    hlevel: string;
    /** Any additional attributes */
    [key: string]: string;
  };
}

/**
 * Error codes used by LLMXMLError
 */
export type ErrorCode =
  | 'SECTION_NOT_FOUND'
  | 'PARSE_ERROR'
  | 'INVALID_FORMAT'
  | 'INVALID_LEVEL'
  | 'INVALID_SECTION_OPTIONS'
  | 'AMBIGUOUS_MATCH';

/**
 * Warning codes used by the warning system
 */
export type WarningCode =
  | 'AMBIGUOUS_MATCH'
  | 'POTENTIAL_MATCH'
  | 'UNKNOWN_WARNING';

/**
 * Warning object structure
 */
export interface Warning {
  /** Warning code */
  code: WarningCode;
  /** Human-readable warning message */
  message: string;
  /** Additional warning details */
  details?: unknown;
}