Utilities & Type System

/**
 * Lookup file in include paths
 * @param {string} path - File path to find
 * @param {string[]} paths - Array of search paths
 * @param {string} ignore - File extension to ignore
 * @returns {string|null} Found file path or null
 */
function lookup(path, paths, ignore);

/**
 * Find file in include paths (similar to lookup)
 * @param {string} path - File path to find
 * @param {string[]} paths - Array of search paths
 * @param {string} ignore - File extension to ignore
 * @returns {string|null} Found file path or null
 */
function find(path, paths, ignore);

/**
 * Lookup index file in directory
 * @param {string} path - Directory path
 * @param {string[]} paths - Array of search paths
 * @param {string} filename - Index filename (default: 'index')
 * @returns {string|null} Found index file path or null
 */
function lookupIndex(path, paths, filename);

/**
 * Get absolute path
 * @param {string} path - Path to make absolute
 * @returns {string} Absolute path
 */
function absolute(path);

/**
 * Join path components
 * @param {string} base - Base path
 * @param {string} path - Path to join
 * @returns {string} Joined path
 */
function join(base, path);

/**
 * Get directory name from path
 * @param {string} path - File path
 * @returns {string} Directory path
 */
function dirname(path);

/**
 * Get base filename from path
 * @param {string} path - File path
 * @param {string} ext - Extension to remove
 * @returns {string} Base filename
 */
function basename(path, ext);

/**
 * Get file extension
 * @param {string} path - File path
 * @returns {string} File extension
 */
function extname(path);

/**
 * Get relative path from one path to another
 * @param {string} from - Source path
 * @param {string} to - Target path
 * @returns {string} Relative path
 */
function relative(from, to);

/**
 * Coerce two values to same type for operations
 * @param {Node} left - Left operand
 * @param {Node} right - Right operand
 * @returns {Array} Array of coerced values [left, right]
 */
function coerce(left, right);

/**
 * Unwrap expression to get inner value
 * @param {Node} expr - Expression to unwrap
 * @returns {Node} Unwrapped value
 */
function unwrap(expr);

/**
 * Get function parameter names
 * @param {Function} fn - Function to analyze
 * @returns {string[]} Array of parameter names
 */
function params(fn);

/**
 * Merge two objects
 * @param {object} a - First object
 * @param {object} b - Second object
 * @returns {object} Merged object
 */
function merge(a, b);

/**
 * Clone an object
 * @param {object} obj - Object to clone
 * @returns {object} Cloned object
 */
function clone(obj);

/**
 * Assert that node exists (not null/undefined)
 * @param {Node} node - Node to check
 * @param {string} name - Parameter name for error
 * @throws {TypeError} If node is null/undefined
 */
function assertPresent(node, name);

/**
 * Assert that node is a string
 * @param {Node} node - Node to check
 * @param {string} name - Parameter name for error
 * @returns {String} String node
 * @throws {TypeError} If not a string
 */
function assertString(node, name);

/**
 * Assert that node is a color
 * @param {Node} node - Node to check
 * @param {string} name - Parameter name for error
 * @returns {RGBA} Color node
 * @throws {TypeError} If not a color
 */
function assertColor(node, name);

/**
 * Assert that node is a boolean
 * @param {Node} node - Node to check
 * @param {string} name - Parameter name for error
 * @returns {Boolean} Boolean node
 * @throws {TypeError} If not a boolean
 */
function assertBoolean(node, name);

/**
 * Assert that node is a specific type
 * @param {Node} node - Node to check
 * @param {string} type - Expected type name
 * @param {string} name - Parameter name for error
 * @returns {Node} Typed node
 * @throws {TypeError} If not the expected type
 */
function assertType(node, type, name);

/**
 * Base visitor class for AST traversal
 */
class Visitor {
  constructor(root);
  
  /**
   * Visit a node based on its type
   * @param {Node} node - Node to visit
   * @returns {Node} Visited node
   */
  visit(node);
  
  /**
   * Visit a generic node
   * @param {Node} node - Node to visit
   * @returns {Node} Visited node
   */
  visitNode(node);
}

/**
 * Evaluator for executing Stylus AST
 */
class Evaluator extends Visitor {
  constructor(root, options);
  
  /**
   * Evaluate the AST
   * @returns {Node} Evaluated result
   */
  evaluate();
  
  /**
   * Visit and evaluate specific node types
   * @param {Node} node - Node to evaluate
   * @returns {Node} Evaluated result
   */
  visitRule(node);
  visitProperty(node);
  visitExpression(node);
  visitBinOp(node);
  visitFunction(node);
  visitCall(node);
  visitIf(node);
  visitEach(node);
  visitFor(node);
}

/**
 * Compiler for generating CSS from evaluated AST
 */
class Compiler extends Visitor {
  constructor(root, options);
  
  /**
   * Compile AST to CSS string
   * @returns {string} Generated CSS
   */
  compile();
  
  /**
   * Visit and compile specific node types
   * @param {Node} node - Node to compile
   * @returns {string} CSS fragment
   */
  visitRule(node);
  visitProperty(node);
  visitMedia(node);
  visitKeyframes(node);
  visitComment(node);
}

/**
 * Normalizer for AST preprocessing
 */
class Normalizer extends Visitor {
  constructor(root, options);
  
  /**
   * Normalize the AST
   * @returns {Node} Normalized AST
   */
  normalize();
  
  /**
   * Visit and normalize specific node types
   * @param {Node} node - Node to normalize
   * @returns {Node} Normalized node
   */
  visitRule(node);
  visitProperty(node);
  visitSelector(node);
  visitExpression(node);
}

const stylus = require('stylus');
const utils = stylus.utils;

// Path utilities
const paths = ['./styles', './node_modules'];
const foundFile = utils.lookup('variables.styl', paths);
const absolutePath = utils.absolute('./styles/main.styl');
const joined = utils.join('/styles', 'components.styl');

// Value utilities
const { nodes } = stylus;
const expr1 = new nodes.Unit(10, 'px');
const expr2 = new nodes.Unit(5, 'em');
const [coerced1, coerced2] = utils.coerce(expr1, expr2);

// Type checking
function customFunction(color, amount) {
  utils.assertColor(color, 'color');
  utils.assertType(amount, 'unit', 'amount');
  
  // Function logic here
  return new nodes.RGBA(255, 0, 0, 1);
}

// Visitor pattern
const evaluator = new stylus.Evaluator(ast);
const result = evaluator.evaluate();

const compiler = new stylus.Compiler(result);
const css = compiler.compile();

// Visitor options
interface VisitorOptions {
  /** Include imported files */
  imports?: string[];
  /** Custom functions */
  functions?: object;
  /** Global variables */
  globals?: object;
  /** Compress output */
  compress?: boolean;
  /** Source filename */
  filename?: string;
}

// Evaluator-specific options
interface EvaluatorOptions extends VisitorOptions {
  /** Warn on undefined variables */
  warn?: boolean;
  /** Resolve URLs */
  resolveURL?: boolean;
  /** Include CSS imports */
  includeCSS?: boolean;
}

// Compiler-specific options
interface CompilerOptions extends VisitorOptions {
  /** Include line numbers */
  linenos?: boolean;
  /** Firebug debug info */
  firebug?: boolean;
  /** Indent string */
  indent?: string;
  /** Generate source map */
  sourcemap?: boolean;
}