Parsing & AST System

/**
 * Parser for Stylus source code
 * @param {string} str - Stylus source code to parse
 * @param {ParserOptions} options - Parser configuration options
 */
class Parser {
  constructor(str, options);
  
  /**
   * Parse source code to AST
   * @returns {Node} Root AST node
   */
  parse();
  
  /**
   * Peek at next token without consuming it
   * @returns {Token} Next token
   */
  peek();
  
  /**
   * Advance to next token
   * @returns {Token} Current token
   */
  advance();
  
  /**
   * Accept token of specified type
   * @param {string} type - Token type to accept
   * @returns {Token|undefined} Token if accepted, undefined otherwise
   */
  accept(type);
  
  /**
   * Expect token of specified type (throws if not found)
   * @param {string} type - Token type expected
   * @returns {Token} Expected token
   */
  expect(type);
}

/**
 * Base class for all AST nodes
 */
class Node {
  constructor();
  
  /** Line number in source file */
  lineno: number;
  /** Column number in source file */
  column: number;
  /** Source filename */
  filename: string;
  
  /**
   * Convert node to JSON representation
   * @returns {object} JSON representation
   */
  toJSON();
  
  /**
   * Evaluate the node
   * @returns {Node} Evaluated result
   */
  eval();
  
  /**
   * Clone the node
   * @returns {Node} Cloned node
   */
  clone();
  
  /**
   * String representation of node
   * @returns {string} String representation
   */
  toString();
}

/**
 * Root node - top-level container for entire stylesheet
 */
class Root extends Node {
  constructor();
  nodes: Node[];
}

/**
 * CSS property declaration
 */
class Property extends Node {
  constructor(segments, expr);
  segments: Node[];
  expr: Expression;
}

/**
 * Statement block containing rules and properties
 */
class Block extends Node {
  constructor(parent, node);
  nodes: Node[];
  parent: Block;
  scope: boolean;
}

/**
 * CSS selector
 */
class Selector extends Node {
  constructor(segments);
  segments: Node[];
  optional: boolean;
}

/**
 * Group of selectors sharing the same block
 */
class Group extends Node {
  constructor();
  nodes: Selector[];
  extends: Node[];
  block: Block;
}

/**
 * Identifier or variable reference
 */
class Ident extends Node {
  constructor(name, val, mixin);
  name: string;
  val: Node;
  mixin: boolean;
}

/**
 * String literal value
 */
class String extends Node {
  constructor(val, quote);
  val: string;
  quote: string;
}

/**
 * Numeric value with optional unit
 */
class Unit extends Node {
  constructor(val, type);
  val: number;
  type: string;
}

/**
 * RGBA color value
 */
class RGBA extends Node {
  constructor(r, g, b, a);
  r: number;
  g: number;
  b: number;
  a: number;
}

/**
 * HSLA color value
 */
class HSLA extends Node {
  constructor(h, s, l, a);
  h: number;
  s: number;
  l: number;
  a: number;
}

/**
 * Boolean value
 */
class Boolean extends Node {
  constructor(val);
  val: boolean;
}

/**
 * Null value
 */
class Null extends Node {
  constructor();
}

/**
 * Object/hash value
 */
class Object extends Node {
  constructor();
  vals: object;
}

/**
 * Expression container
 */
class Expression extends Node {
  constructor(isList);
  nodes: Node[];
  isList: boolean;
}

/**
 * Member access expression (obj.prop)
 */
class Member extends Node {
  constructor(left, right);
  left: Node;
  right: Node;
}

/**
 * Binary operation (+, -, *, /, etc.)
 */
class BinOp extends Node {
  constructor(op, left, right);
  op: string;
  left: Node;
  right: Node;
}

/**
 * Unary operation (!, -, +, etc.)
 */
class UnaryOp extends Node {
  constructor(op, expr);
  op: string;
  expr: Node;
}

/**
 * Ternary conditional expression (cond ? true : false)
 */
class Ternary extends Node {
  constructor(cond, trueExpr, falseExpr);
  cond: Node;
  trueExpr: Node;
  falseExpr: Node;
}

/**
 * Conditional if statement
 */
class If extends Node {
  constructor(cond, negate);
  cond: Node;
  block: Block;
  elses: Node[];
  negate: boolean;
}

/**
 * Each loop statement
 */
class Each extends Node {
  constructor(val, key, expr);
  val: string;
  key: string;
  expr: Node;
  block: Block;
}

/**
 * Return statement
 */
class Return extends Node {
  constructor(expr);
  expr: Node;
}

/**
 * Function definition
 */
class Function extends Node {
  constructor(name, params, body);
  name: string;
  params: Params;
  body: Block;
}

/**
 * Function call
 */
class Call extends Node {
  constructor(name, args);
  name: string;
  args: Arguments;
}

/**
 * Function parameters
 */
class Params extends Node {
  constructor();
  nodes: Node[];
}

/**
 * Function arguments
 */
class Arguments extends Node {
  constructor();
  nodes: Node[];
}

/**
 * @import directive
 */
class Import extends Node {
  constructor(path, once);
  path: Node;
  once: boolean;
}

/**
 * @media rule
 */
class Media extends Node {
  constructor();
  val: QueryList;
  block: Block;
}

/**
 * Media query list
 */
class QueryList extends Node {
  constructor();
  nodes: Query[];
}

/**
 * Single media query
 */
class Query extends Node {
  constructor();
  type: string;
  nodes: Feature[];
}

/**
 * Media feature
 */
class Feature extends Node {
  constructor(segments);
  segments: Node[];
  name: string;
  expr: Node;
}

/**
 * @extend directive
 */
class Extend extends Node {
  constructor(selectors);
  selectors: Selector[];
}

/**
 * At-rule (@font-face, @page, etc.)
 */
class Atrule extends Node {
  constructor(type);
  type: string;
  segments: Node[];
  block: Block;
}

/**
 * @keyframes rule
 */
class Keyframes extends Atrule {
  constructor(segs, prefix);
  segments: Node[];
  prefix: string;
  block: Block;
}

/**
 * @supports rule
 */
class Supports extends Node {
  constructor(condition);
  condition: Node;
  block: Block;
}

/**
 * @charset directive
 */
class Charset extends Node {
  constructor(val);
  val: string;
}

/**
 * @namespace directive
 */
class Namespace extends Node {
  constructor(val, prefix);
  val: string;
  prefix: string;
}

/**
 * @block directive
 */
class Atblock extends Node {
  constructor();
  block: Block;
  nodes: Node[];
}

/**
 * CSS comment
 */
class Comment extends Node {
  constructor(str, suppress, inline);
  str: string;
  suppress: boolean;
  inline: boolean;
}

/**
 * Literal CSS output
 */
class Literal extends Node {
  constructor(str);
  str: string;
  css: string;
}

const stylus = require('stylus');

// Parse Stylus source to AST
const parser = new stylus.Parser('body\n  color red');
const ast = parser.parse();

console.log(ast.toJSON()); // JSON representation

// Work with specific node types
const { nodes } = stylus;

// Create nodes programmatically  
const colorProp = new nodes.Property(
  [new nodes.Ident('color')],
  new nodes.Expression().push(new nodes.Ident('red'))
);

// Clone nodes
const clonedProp = colorProp.clone();

// Node type checking
if (ast instanceof nodes.Root) {
  console.log('Root node');
}

// Parser options
interface ParserOptions {
  /** Source filename for error reporting */
  filename?: string;
  /** Enable parser caching */
  cache?: boolean;
  /** Parse in compressed mode */
  compress?: boolean;
}