istanbul-lib-report 3.0.1: istanbul-lib-report

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify istanbul-lib-report in pkg:npm/istanbul-lib-report@3.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/istanbul-lib-report@3.0.1
Demonstrate these symbols/APIs:
  - istanbul-lib-report
Required runtime conditions:
  - ecosystem: golang
  - language: go
  - packageManager: go@1.26.6
  - runtime: go@1.26.6

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:6c2a01f0f5522f17f6caee62104d23f91c18e86136bffdddfc5601e5cef43c23","contract":["getDefaultWatermarks returns default percentage thresholds of 50 and 80 for statements, functions, branches, and lines","createContext initializes a reporting context with default directory 'coverage' and default watermarks","createContext applies custom reporting directory, customized watermarks, and custom sourceFinder","Context.classForPercent classifies percentage values into low, medium, or high buckets according to configured watermarks","Context.classForPercent returns unknown for unrecognized metric keys","Context.getSource delegates to sourceFinder function to retrieve file content","ReportBase executes report traversal across coverage tree invoking onStart, onSummary, onDetail, onSummaryEnd, and onEnd lifecycle methods"],"goal":"verify istanbul-lib-report in pkg:npm/istanbul-lib-report@3.0.1","kind":"HOW","packages":["pkg:npm/istanbul-lib-report@3.0.1"],"schemaVersion":1,"symbols":["istanbul-lib-report"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/istanbul-lib-report@3.0.1"],"schemaVersion":1,"subject":"pkg:npm/istanbul-lib-report@3.0.1","symbols":["istanbul-lib-report"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-istanbul-lib-report",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-istanbul-lib-report",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "istanbul-lib-report": "3.0.1"
      }
    },
    "node_modules/has-flag": {
      "version": "4.0.0",
      "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz",
      "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==",
      "license": "MIT",
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/istanbul-lib-coverage": {
      "version": "3.2.2",
      "resolved": "https://registry.npmjs.org/istanbul-lib-coverage/-/istanbul-lib-coverage-3.2.2.tgz",
      "integrity": "sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg==",
      "license": "BSD-3-Clause",
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/istanbul-lib-report": {
      "version": "3.0.1",
      "resolved": "https://registry.npmjs.org/istanbul-lib-report/-/istanbul-lib-report-3.0.1.tgz",
      "integrity": "sha512-GCfE1mtsHGOELCU8e/Z7YWzpmybrx/+dSTfLrvY8qRmaY6zXTKWn6WQIjaAFw069icm6GVMNkgu0NzI4iPZUNw==",
      "license": "BSD-3-Clause",
      "dependencies": {
        "istanbul-lib-coverage": "^3.0.0",
        "make-dir": "^4.0.0",
        "supports-color": "^7.1.0"
      },
      "engines": {
        "node": ">=10"
      }
    },
    "node_modules/make-dir": {
      "version": "4.0.0",
      "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-4.0.0.tgz",
      "integrity": "sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==",
      "license": "MIT",
      "dependencies": {
        "semver": "^7.5.3"
      },
      "engines": {
        "node": ">=10"
      },
      "funding": {
        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
    "node_modules/semver": {
      "version": "7.8.5",
      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz",
      "integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==",
      "license": "ISC",
      "bin": {
        "semver": "bin/semver.js"
      },
      "engines": {
        "node": ">=10"
      }
    },
    "node_modules/supports-color": {
      "version": "7.2.0",
      "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",
      "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==",
      "license": "MIT",
      "dependencies": {
        "has-flag": "^4.0.0"
      },
      "engines": {
        "node": ">=8"
      }
    }
  }
}

{
  "name": "sample-istanbul-lib-report",
  "version": "1.0.0",
  "description": "Clean-room verification sample for istanbul-lib-report",
  "main": "src/index.js",
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "istanbul-lib-report": "3.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify istanbul-lib-report in pkg:npm/istanbul-lib-report@3.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/istanbul-lib-report@3.0.1"
  ],
  "symbols": [
    "istanbul-lib-report"
  ],
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

import libReport from 'istanbul-lib-report';

const {
  createContext: createReportContext,
  getDefaultWatermarks: getReportDefaultWatermarks,
  ReportBase
} = libReport;

/**
 * Returns the default percentage watermarks for code coverage metrics.
 *
 * @returns {Record<string, [number, number]>} Default watermark thresholds.
 */
export function getDefaultWatermarks() {
  return getReportDefaultWatermarks();
}

/**
 * Creates an Istanbul reporting context instance with the provided options.
 *
 * @param {object} [options={}] - Configuration options for the reporting context.
 * @param {string} [options.dir] - Base output directory for reports.
 * @param {object} [options.watermarks] - Custom watermark bounds.
 * @param {Function} [options.sourceFinder] - Custom file source resolver function.
 * @param {object} [options.coverageMap] - Istanbul coverage map or mock coverage map.
 * @returns {object} Istanbul Context instance.
 */
export function createCoverageContext(options = {}) {
  const coverageMap = options.coverageMap || {
    files: () => [],
    fileCoverageFor: () => null
  };

  return createReportContext({
    dir: options.dir,
    watermarks: options.watermarks,
    sourceFinder: options.sourceFinder,
    coverageMap
  });
}

/**
 * Classifies a coverage percentage into low, medium, or high severity buckets.
 *
 * @param {object} context - Istanbul Context instance.
 * @param {string} metricType - Coverage metric name ('statements', 'functions', 'branches', 'lines').
 * @param {number} percent - Percentage value to classify.
 * @returns {string} Severity label ('low', 'medium', 'high', or 'unknown').
 */
export function classifyCoveragePercent(context, metricType, percent) {
  return context.classForPercent(metricType, percent);
}

/**
 * Custom report implementation extending ReportBase to traverse and record coverage tree nodes.
 */
export class TreeAuditReport extends ReportBase {
  constructor(options = {}) {
    super(options);
    this.events = [];
    this.summaries = [];
    this.details = [];
  }

  onStart(root, state) {
    this.events.push('start');
  }

  onSummary(node, state) {
    const name = node.getRelativeName();
    this.events.push(`summary:${name}`);
    this.summaries.push(name);
  }

  onDetail(node, state) {
    const name = node.getRelativeName();
    this.events.push(`detail:${name}`);
    this.details.push(name);
  }

  onSummaryEnd(node, state) {
    const name = node.getRelativeName();
    this.events.push(`summaryEnd:${name}`);
  }

  onEnd(root, state) {
    this.events.push('end');
  }
}

import assert from 'node:assert/strict';
import libReport from 'istanbul-lib-report';
import {
  getDefaultWatermarks,
  createCoverageContext,
  classifyCoveragePercent,
  TreeAuditReport
} from '../src/index.js';

const {
  createContext,
  getDefaultWatermarks: getDirectDefaults,
  ReportBase
} = libReport;

// 1. getDefaultWatermarks returns default percentage thresholds of 50 and 80 for statements, functions, branches, and lines
{
  const directDefaults = getDirectDefaults();
  const helperDefaults = getDefaultWatermarks();

  assert.deepEqual(
    directDefaults,
    {
      statements: [50, 80],
      functions: [50, 80],
      branches: [50, 80],
      lines: [50, 80]
    },
    'Default watermarks must contain 50/80 boundaries for all metric types'
  );

  assert.deepEqual(
    helperDefaults,
    directDefaults,
    'Helper getDefaultWatermarks must match direct package export'
  );
}

// 2. createContext initializes a reporting context with default directory 'coverage' and default watermarks
{
  const emptyMap = {
    files: () => [],
    fileCoverageFor: () => null
  };

  const context = createContext({ coverageMap: emptyMap });
  const helperContext = createCoverageContext();

  assert.equal(context.dir, 'coverage', 'Direct context default dir must be "coverage"');
  assert.equal(helperContext.dir, 'coverage', 'Helper context default dir must be "coverage"');
  assert.deepEqual(
    context.watermarks,
    {
      statements: [50, 80],
      functions: [50, 80],
      branches: [50, 80],
      lines: [50, 80]
    },
    'Direct context watermarks must default to 50/80 thresholds'
  );
}

// 3. createContext applies custom reporting directory, customized watermarks, and custom sourceFinder
{
  const customFinder = (filePath) => `// source of ${filePath}`;
  const customWatermarks = {
    lines: [60, 90],
    functions: [70, 85]
  };

  const context = createCoverageContext({
    dir: 'custom-reports',
    watermarks: customWatermarks,
    sourceFinder: customFinder
  });

  assert.equal(context.dir, 'custom-reports', 'Custom reporting directory must be preserved');
  assert.deepEqual(context.watermarks.lines, [60, 90], 'Custom line thresholds must be set');
  assert.deepEqual(context.watermarks.functions, [70, 85], 'Custom function thresholds must be set');
  assert.deepEqual(context.watermarks.statements, [50, 80], 'Unspecified statements thresholds must fallback to defaults');
  assert.deepEqual(context.watermarks.branches, [50, 80], 'Unspecified branches thresholds must fallback to defaults');
}

// 4. Context.classForPercent classifies percentage values into low, medium, or high buckets according to configured watermarks
{
  const context = createCoverageContext({
    watermarks: {
      lines: [60, 90]
    }
  });

  assert.equal(classifyCoveragePercent(context, 'lines', 0), 'low', '0% must be low');
  assert.equal(classifyCoveragePercent(context, 'lines', 59.9), 'low', '59.9% must be low below threshold 60');
  assert.equal(classifyCoveragePercent(context, 'lines', 60), 'medium', '60% must be medium at lower bound');
  assert.equal(classifyCoveragePercent(context, 'lines', 75), 'medium', '75% must be medium between 60 and 90');
  assert.equal(classifyCoveragePercent(context, 'lines', 89.9), 'medium', '89.9% must be medium below 90');
  assert.equal(classifyCoveragePercent(context, 'lines', 90), 'high', '90% must be high at upper bound');
  assert.equal(classifyCoveragePercent(context, 'lines', 100), 'high', '100% must be high');
}

// 5. Context.classForPercent returns unknown for unrecognized metric keys
{
  const context = createCoverageContext();

  assert.equal(context.classForPercent('invalidMetric', 50), 'unknown', 'Unknown metric should return "unknown"');
  assert.equal(classifyCoveragePercent(context, 'nonexistent', 100), 'unknown', 'Helper with unknown metric returns "unknown"');
}

// 6. Context.getSource delegates to sourceFinder function to retrieve file content
{
  const customFinder = (filePath) => `export const name = "${filePath}";`;
  const context = createCoverageContext({ sourceFinder: customFinder });

  assert.equal(
    context.getSource('lib/util.js'),
    'export const name = "lib/util.js";',
    'getSource must return string from sourceFinder'
  );
}

// 7. ReportBase executes report traversal across coverage tree invoking onStart, onSummary, onDetail, onSummaryEnd, and onEnd lifecycle methods
{
  const mockCoverageMap = {
    files: () => ['src/utils/math.js', 'src/core/app.js'],
    fileCoverageFor: (filePath) => ({
      path: filePath,
      toSummary: () => ({
        merge: () => {},
        toJSON: () => ({
          lines: { total: 20, covered: 18, pct: 90 },
          statements: { total: 20, covered: 18, pct: 90 },
          functions: { total: 5, covered: 5, pct: 100 },
          branches: { total: 4, covered: 3, pct: 75 }
        })
      })
    })
  };

  const context = createContext({
    dir: 'report-output',
    coverageMap: mockCoverageMap
  });

  const report = new TreeAuditReport();
  assert.ok(report instanceof ReportBase, 'TreeAuditReport must be an instance of ReportBase');

  report.execute(context);

  assert.equal(report.events[0], 'start', 'First event must be onStart');
  assert.equal(report.events[report.events.length - 1], 'end', 'Last event must be onEnd');
  assert.ok(report.events.includes('summary:core'), 'Traversal must visit summary for core directory');
  assert.ok(report.events.includes('summary:utils'), 'Traversal must visit summary for utils directory');
  assert.ok(report.events.includes('detail:app.js'), 'Traversal must visit detail for app.js');
  assert.ok(report.events.includes('detail:math.js'), 'Traversal must visit detail for math.js');
  assert.ok(report.events.includes('summaryEnd:core'), 'Traversal must invoke summaryEnd for core directory');
  assert.ok(report.events.includes('summaryEnd:utils'), 'Traversal must invoke summaryEnd for utils directory');
}