tessl/npm-istanbul

Comprehensive JavaScript code coverage tool that computes statement, line, function and branch coverage with module loader hooks for transparent instrumentation

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Tree Summarization

Name: tessl/npm-istanbul
Author: tessl

Tree summarization generates hierarchical coverage summaries organized by directory structure. This capability is primarily used by the HTML report generator to create navigable coverage trees and is useful for analyzing coverage patterns across large codebases.

Capabilities

TreeSummarizer Class

Creates tree-structured coverage summaries from file coverage data.

/**
 * Creates a tree summarizer for organizing coverage data by directory structure
 */
class TreeSummarizer {
    constructor();
    
    /**
     * Adds coverage metrics for a specific file path
     * @param {string} filePath - The full path to the file
     * @param {Object} metrics - Coverage metrics summary for the file
     */
    addFileCoverageSummary(filePath: string, metrics: Object): void;
    
    /**
     * Generates a hierarchical tree summary from all added file coverage data
     * @returns {TreeSummary} Tree structure with coverage metrics
     */
    getTreeSummary(): TreeSummary;
}

Usage Example:

const istanbul = require('istanbul');
const TreeSummarizer = istanbul.TreeSummarizer;

// Create summarizer and add file coverage
const summarizer = new TreeSummarizer();
summarizer.addFileCoverageSummary('/src/utils/math.js', {
    statements: { total: 10, covered: 8, pct: 80 },
    branches: { total: 4, covered: 3, pct: 75 },
    functions: { total: 2, covered: 2, pct: 100 },
    lines: { total: 8, covered: 7, pct: 87.5 }
});

summarizer.addFileCoverageSummary('/src/lib/core.js', {
    statements: { total: 25, covered: 20, pct: 80 },
    branches: { total: 8, covered: 6, pct: 75 },
    functions: { total: 5, covered: 4, pct: 80 },
    lines: { total: 20, covered: 16, pct: 80 }
});

// Generate tree summary
const treeSummary = summarizer.getTreeSummary();
console.log(treeSummary.toJSON());

TreeSummary Interface

Represents the hierarchical coverage tree with navigation capabilities.

interface TreeSummary {
    /**
     * Common path prefix for all files in the tree
     */
    prefix: string[];
    
    /**
     * Root node of the coverage tree
     */
    root: Node;
    
    /**
     * Retrieves a node by its short name
     * @param {string} shortName - The relative name of the node
     * @returns {Node} The node if found
     */
    getNode(shortName: string): Node;
    
    /**
     * Converts the tree summary to JSON format
     * @returns {Object} JSON representation of the tree
     */
    toJSON(): Object;
}

Node Interface

Represents individual files and directories in the coverage tree.

interface Node {
    /**
     * Short name of the node (filename or directory name)
     */
    name: string;
    
    /**
     * Name relative to parent directory
     */
    relativeName: string;
    
    /**
     * Full path name of the node
     */
    fullName: string;
    
    /**
     * Type of node: 'file' for files, 'dir' for directories
     */
    kind: 'file' | 'dir';
    
    /**
     * Coverage metrics for this node (null for directories without files)
     * Aggregated from all child nodes for directories
     */
    metrics: Object | null;
    
    /**
     * Package-style metrics including only direct file children
     * (excludes subdirectory contributions)
     */
    packageMetrics: Object | null;
    
    /**
     * Parent node (null for root)
     */
    parent: Node | null;
    
    /**
     * Array of child nodes
     */
    children: Node[];
    
    /**
     * Returns the display name for the node
     * @returns {string} The relative name for display
     */
    displayShortName(): string;
    
    /**
     * Adds a child node and sets parent relationship
     * @param {Node} child - The child node to add
     */
    addChild(child: Node): void;
    
    /**
     * Converts the node and its children to JSON format
     * @returns {Object} JSON representation including all descendants
     */
    toJSON(): Object;
}

Coverage Metrics Structure

The metrics objects used throughout the tree summarizer follow this structure:

interface CoverageMetrics {
    statements: {
        total: number;    // Total number of statements
        covered: number;  // Number of covered statements  
        skipped: number;  // Number of skipped statements
        pct: number;      // Coverage percentage
    };
    branches: {
        total: number;    // Total number of branches
        covered: number;  // Number of covered branches
        skipped: number;  // Number of skipped branches
        pct: number;      // Coverage percentage
    };
    functions: {
        total: number;    // Total number of functions
        covered: number;  // Number of covered functions
        skipped: number;  // Number of skipped functions
        pct: number;      // Coverage percentage
    };
    lines: {
        total: number;    // Total number of lines
        covered: number;  // Number of covered lines
        skipped: number;  // Number of skipped lines
        pct: number;      // Coverage percentage
    };
}

Integration with Report Generation

The TreeSummarizer is primarily used by the HTML report generator to create navigable directory trees:

const istanbul = require('istanbul');
const collector = new istanbul.Collector();
// ... add coverage data to collector

// Generate tree for HTML reports
const summarizer = new istanbul.TreeSummarizer();
collector.files().forEach(file => {
    const fileCoverage = collector.fileCoverageFor(file);
    const summary = istanbul.utils.summarizeFileCoverage(fileCoverage);
    summarizer.addFileCoverageSummary(file, summary);
});

const tree = summarizer.getTreeSummary();
// Tree is used by HTML report templates for navigation