Core Compilation

/**
 * Creates a new Renderer instance for compiling Stylus source
 * @param {string} str - Stylus source code to compile
 * @param {RendererOptions} options - Compilation options
 * @returns {Renderer} New Renderer instance
 */
function stylus(str, options);

const stylus = require('stylus');

// Basic usage
const renderer = stylus('body\n  color red');
const css = renderer.render();

// With options
const renderer = stylus('body\n  color red', {
  compress: true,
  filename: 'styles.styl'
});

/**
 * Render Stylus source to CSS with callback
 * @param {string} str - Stylus source code
 * @param {RendererOptions|Function} options - Options or callback function
 * @param {Function} fn - Callback function (err, css)
 */
function render(str, options, fn);

const stylus = require('stylus');

// With callback only
stylus.render('body\n  color red', (err, css) => {
  if (err) throw err;
  console.log(css);
});

// With options and callback
stylus.render('body\n  color red', { compress: true }, (err, css) => {
  if (err) throw err;
  console.log(css);
});

/**
 * Main Stylus renderer for compilation control
 * @param {string} str - Stylus source code
 * @param {RendererOptions} options - Compilation options
 */
class Renderer {
  constructor(str, options);
  
  /**
   * Render to CSS with optional callback
   * @param {Function} fn - Optional callback (err, css)
   * @returns {string|undefined} CSS string if no callback, undefined otherwise
   */
  render(fn);
  
  /**
   * Set a renderer option or global variable
   * @param {string} key - Option key or variable name
   * @param {any} value - Option or variable value
   * @returns {Renderer} This renderer for chaining
   */
  set(key, value);
  
  /**
   * Get a renderer option or global variable
   * @param {string} key - Option key or variable name
   * @returns {any} Option or variable value
   */
  get(key);
  
  /**
   * Add an include path for @import statements
   * @param {string} path - Directory path to include
   * @returns {Renderer} This renderer for chaining
   */
  include(path);
  
  /**
   * Import a Stylus file
   * @param {string} file - File path to import
   * @returns {Renderer} This renderer for chaining
   */
  import(file);
  
  /**
   * Define a custom function or mixin
   * @param {string} name - Function/mixin name
   * @param {Node|Function} node - AST node or JavaScript function
   * @param {boolean} raw - Whether to return raw value
   * @returns {Renderer} This renderer for chaining
   */
  define(name, node, raw);
  
  /**
   * Use a plugin function
   * @param {Function} plugin - Plugin function
   * @returns {Renderer} This renderer for chaining
   */
  use(plugin);
  
  /**
   * Get array of file dependencies
   * @returns {string[]} Array of imported file paths
   */
  deps();
}

const stylus = require('stylus');

// Basic renderer usage
const renderer = new stylus.Renderer('body\n  color red');
const css = renderer.render();

// Advanced configuration
const renderer = stylus('body\n  font-size base-font')
  .set('compress', true)
  .set('base-font', '16px')
  .include('./styles')
  .include('./mixins')
  .import('variables.styl')
  .define('add', (a, b) => a.val + b.val)
  .use(somePlugin);

// Get dependencies
const deps = renderer.deps();
console.log('Dependencies:', deps);

// Render with callback
renderer.render((err, css) => {
  if (err) throw err;
  console.log(css);
});

/**
 * Convert CSS to Stylus syntax
 * @param {string} css - CSS source to convert
 * @param {ConversionOptions} options - Conversion options
 * @returns {string} Stylus source code
 */
function convertCSS(css, options);

const stylus = require('stylus');

const css = `
.header {
  color: red;
  font-size: 16px;
}
`;

const stylusCode = stylus.convertCSS(css);
console.log(stylusCode);
// Output:
// .header
//   color red
//   font-size 16px

// Main renderer options interface
interface RendererOptions {
  /** Input filename for error reporting and source maps */
  filename?: string;
  /** Array of paths to search for @import files */
  paths?: string[];
  /** Compress output CSS by removing whitespace */
  compress?: boolean;
  /** Include line numbers in output CSS comments */
  linenos?: boolean;
  /** Include Firebug-compatible debug information */
  firebug?: boolean;
  /** Generate source maps (boolean or detailed options) */
  sourcemap?: boolean | SourceMapOptions;
  /** Include imported CSS files in output */
  includeCSS?: boolean;
  /** Resolve relative URLs in imports */
  resolveURL?: boolean;
  /** Hoist @rules to the top level */
  hoistAtrules?: boolean;
  /** Auto-prefix CSS properties */
  prefix?: string;
  /** Array of imported file paths */
  imports?: string[];
  /** Object of custom functions */
  functions?: object;
  /** Object of global variables */
  globals?: object;
}

// Source map generation options
interface SourceMapOptions {
  /** Include source map comment in CSS */
  comment?: boolean;
  /** Inline source map in CSS */
  inline?: boolean;
  /** Include source content in source map */
  sourcesContent?: boolean;
  /** Base path for source map URLs */
  basePath?: string;
}

// CSS conversion options
interface ConversionOptions {
  /** Property prefix to add */
  prefix?: string;
  /** Include CSS comments in output */
  comment?: boolean;
  /** Indentation string for output */
  indent?: string;
}