Context Management

/**
 * Creates a reporting context for the supplied options
 * @param {Object} opts - Configuration options
 * @param {string} [opts.dir="coverage"] - The reporting directory
 * @param {Object} [opts.watermarks] - Watermarks for statements, lines, branches and functions
 * @param {Function} [opts.sourceFinder] - Function that returns source code given a file path
 * @param {Object} opts.coverageMap - Coverage map from istanbul-lib-coverage
 * @param {string} [opts.defaultSummarizer="pkg"] - Default summarizer type (flat, nested, pkg)
 * @returns {Context} Context instance for report generation
 */
function createContext(opts);

const libReport = require('istanbul-lib-report');

const context = libReport.createContext({
  dir: 'coverage-reports',
  watermarks: {
    statements: [60, 90],
    functions: [60, 90],
    branches: [60, 90],
    lines: [60, 90]
  },
  coverageMap,
  defaultSummarizer: 'nested'
});

/**
 * Returns the default watermarks that would be used when not overridden
 * @returns {Object} Object with statements, functions, branches, and lines keys.
 * Each value is a 2-element array with low and high watermark percentages.
 */
function getDefaultWatermarks();

const libReport = require('istanbul-lib-report');

const defaults = libReport.getDefaultWatermarks();
// Returns: { statements: [50, 80], functions: [50, 80], branches: [50, 80], lines: [50, 80] }

/**
 * A reporting context that is passed to report implementations
 */
class Context {
  /**
   * Create a new Context instance
   * @param {Object} opts - Configuration options
   */
  constructor(opts);

  /**
   * Returns a FileWriter implementation for reporting use
   * @returns {FileWriter} Writer instance for file operations
   */
  getWriter();

  /**
   * Returns the source code for the specified file path
   * @param {string} filePath - The file path as found in a file coverage object
   * @returns {string} The source code
   * @throws {Error} If the source could not be found
   */
  getSource(filePath);

  /**
   * Returns the coverage class given a coverage type and percentage value
   * @param {string} type - Coverage type: "statements", "functions", "branches", or "lines"
   * @param {number} value - The percentage value
   * @returns {string} One of "high", "medium", "low", or "unknown"
   */
  classForPercent(type, value);

  /**
   * Returns an XML writer for the supplied content writer
   * @param {ContentWriter} contentWriter - Content writer for XML output
   * @returns {XMLWriter} XML writer instance
   */
  getXMLWriter(contentWriter);

  /**
   * Returns a full visitor given a partial one
   * @param {Object} partialVisitor - Partial visitor with methods of interest
   * @returns {Visitor} Full visitor instance
   */
  getVisitor(partialVisitor);

  /**
   * Returns a tree for the specified summarizer type
   * @param {string} [name="defaultSummarizer"] - Tree type name
   * @returns {Object} Tree instance for traversal
   */
  getTree(name);
}

const context = libReport.createContext({ dir: 'reports', coverageMap });

// Get file writer
const writer = context.getWriter();

// Get source code
const sourceCode = context.getSource('/path/to/file.js');

// Classify coverage percentage
const cssClass = context.classForPercent('statements', 75); // "medium"

// Get XML writer
const contentWriter = writer.writeFile('report.xml');
const xmlWriter = context.getXMLWriter(contentWriter);

// Create visitor
const visitor = context.getVisitor({
  onSummary(node, state) {
    console.log('Processing summary node:', node.getQualifiedName());
  }
});

// Get tree
const tree = context.getTree('nested');

/**
 * FileWriter property - getter that creates FileWriter if needed
 */
Context.prototype.writer; // Returns FileWriter instance

/**
 * Factory for creating different tree summarization strategies
 */
class SummarizerFactory {
  /**
   * Create a summarizer factory
   * @param {Object} coverageMap - Coverage map from istanbul-lib-coverage
   * @param {string} [defaultSummarizer="pkg"] - Default summarizer type
   */
  constructor(coverageMap, defaultSummarizer);

  /**
   * Get the default summarizer tree
   * @returns {ReportTree} Default summarizer tree instance
   */
  get defaultSummarizer();

  /**
   * Get flat tree organization (all files at root level)
   * @returns {ReportTree} Flat tree instance
   */
  get flat();

  /**
   * Get package-based tree organization
   * @returns {ReportTree} Package tree instance
   */
  get pkg();

  /**
   * Get nested directory tree organization
   * @returns {ReportTree} Nested tree instance
   */
  get nested();
}

const context = libReport.createContext({
  coverageMap,
  defaultSummarizer: 'nested' // Can be 'flat', 'pkg', or 'nested'
});

// Get different tree organizations
const flatTree = context.getTree('flat');
const nestedTree = context.getTree('nested');
const pkgTree = context.getTree('pkg');
const defaultTree = context.getTree(); // Uses defaultSummarizer

interface ContextOptions {
  dir?: string;                              // Output directory (default: "coverage")
  watermarks?: WatermarkThresholds;          // Coverage thresholds
  sourceFinder?: (filePath: string) => string; // Source code finder function
  coverageMap: Object;                       // Coverage map from istanbul-lib-coverage
  defaultSummarizer?: 'flat' | 'nested' | 'pkg';  // Summarizer strategy
}

interface WatermarkThresholds {
  statements?: [number, number];  // [low, high] thresholds
  functions?: [number, number];   // [low, high] thresholds
  branches?: [number, number];    // [low, high] thresholds
  lines?: [number, number];       // [low, high] thresholds
}