fix(test_runner): improve statement coverage implementation and tests

- Add allowHashBang to acorn parse options for shebang support
- Reorder requires to follow ASCII convention
- Reuse existing doesRangeContainOtherRange helper
- Add comments to empty catch blocks for consistency
- Remove else after return in findLineForOffset
- Break kColumnsKeys across multiple lines (max-len)
- Document statement coverage fields in test:coverage event schema
- Migrate threshold tests to data-driven loop
- Remove unused tmpdir import from test file
- Add fixture proving statement != line coverage
- Add fixture testing shebang file parsing
- Add fixture testing graceful degradation for unparseable files

Refs: #62340

Author: Felipeness

doc/api/test.md

@@ -3255,12 +3255,15 @@ are defined, while others are emitted in the order that the tests execute.
       * `totalLineCount` {number} The total number of lines.
       * `totalBranchCount` {number} The total number of branches.
       * `totalFunctionCount` {number} The total number of functions.
+      * `totalStatementCount` {number} The total number of statements.
       * `coveredLineCount` {number} The number of covered lines.
       * `coveredBranchCount` {number} The number of covered branches.
       * `coveredFunctionCount` {number} The number of covered functions.
+      * `coveredStatementCount` {number} The number of covered statements.
       * `coveredLinePercent` {number} The percentage of lines covered.
       * `coveredBranchPercent` {number} The percentage of branches covered.
       * `coveredFunctionPercent` {number} The percentage of functions covered.
+      * `coveredStatementPercent` {number} The percentage of statements covered.
       * `functions` {Array} An array of functions representing function
         coverage.
         * `name` {string} The name of the function.
@@ -3273,22 +3276,30 @@ are defined, while others are emitted in the order that the tests execute.
         numbers and the number of times they were covered.
         * `line` {number} The line number.
         * `count` {number} The number of times the line was covered.
+      * `statements` {Array} An array of statements representing statement
+        coverage.
+        * `line` {number} The line number where the statement starts.
+        * `count` {number} The number of times the statement was executed.
     * `thresholds` {Object} An object containing whether or not the coverage for
       each coverage type.
       * `function` {number} The function coverage threshold.
       * `branch` {number} The branch coverage threshold.
       * `line` {number} The line coverage threshold.
+      * `statement` {number} The statement coverage threshold.
     * `totals` {Object} An object containing a summary of coverage for all
       files.
       * `totalLineCount` {number} The total number of lines.
       * `totalBranchCount` {number} The total number of branches.
       * `totalFunctionCount` {number} The total number of functions.
+      * `totalStatementCount` {number} The total number of statements.
       * `coveredLineCount` {number} The number of covered lines.
       * `coveredBranchCount` {number} The number of covered branches.
       * `coveredFunctionCount` {number} The number of covered functions.
+      * `coveredStatementCount` {number} The number of covered statements.
       * `coveredLinePercent` {number} The percentage of lines covered.
       * `coveredBranchPercent` {number} The percentage of branches covered.
       * `coveredFunctionPercent` {number} The percentage of functions covered.
+      * `coveredStatementPercent` {number} The percentage of statements covered.
     * `workingDirectory` {string} The working directory when code coverage
       began. This is useful for displaying relative path names in case the tests
       changed the working directory of the Node.js process.

lib/internal/test_runner/coverage.js

@@ -30,6 +30,10 @@ const { tmpdir } = require('os');
 const { join, resolve, relative } = require('path');
 const { fileURLToPath, URL } = require('internal/url');
 const { kMappings, SourceMap } = require('internal/source_map/source_map');
+const { Parser: AcornParser } =
+  require('internal/deps/acorn/acorn/dist/acorn');
+const { simple: acornWalkSimple } =
+  require('internal/deps/acorn/acorn-walk/dist/walk');
 const {
   codes: {
     ERR_SOURCE_MAP_CORRUPT,
@@ -38,10 +42,6 @@ const {
 } = require('internal/errors');
 const { matchGlobPattern } = require('internal/fs/glob');
 const { constants: { kMockSearchParam } } = require('internal/test_runner/mock/loader');
-const { Parser: AcornParser } =
-  require('internal/deps/acorn/acorn/dist/acorn');
-const { simple: acornWalkSimple } =
-  require('internal/deps/acorn/acorn-walk/dist/walk');
 
 // Statement types excluded from coverage: containers (BlockStatement)
 // and empty statements that carry no executable semantics.
@@ -89,6 +89,7 @@ class TestCoverage {
     try {
       source ??= readFileSync(fileURLToPath(fileUrl), 'utf8');
     } catch {
+      // The file can no longer be read. Leave it out of statement coverage.
       this.#sourceStatements.set(fileUrl, null);
       return null;
     }
@@ -119,11 +120,14 @@ class TestCoverage {
         __proto__: null,
         ecmaVersion: 'latest',
         sourceType: 'script',
+        allowHashBang: true,
         allowReturnOutsideFunction: true,
         allowImportExportEverywhere: true,
         allowAwaitOutsideFunction: true,
       });
     } catch {
+      // Acorn could not parse the file (e.g. non-JS syntax, TypeScript).
+      // Degrade gracefully — the file will report no statement coverage.
       this.#sourceStatements.set(fileUrl, null);
       return null;
     }
@@ -248,6 +252,7 @@ class TestCoverage {
       try {
         source = readFileSync(fileURLToPath(url), 'utf8');
       } catch {
+        // The file can no longer be read. Skip it entirely.
         continue;
       }
 
@@ -345,8 +350,7 @@ class TestCoverage {
 
           for (let ri = 0; ri < allRanges.length; ++ri) {
             const range = allRanges[ri];
-            if (range.startOffset <= stmt.startOffset &&
-                range.endOffset >= stmt.endOffset) {
+            if (doesRangeContainOtherRange(range, stmt)) {
               const size = range.endOffset - range.startOffset;
               if (size < bestSize) {
                 bestCount = range.count;
@@ -846,7 +850,8 @@ function findLineForOffset(offset, lines) {
 
     if (offset >= line.startOffset && offset <= line.endOffset) {
       return line;
-    } else if (offset > line.endOffset) {
+    }
+    if (offset > line.endOffset) {
       start = mid + 1;
     } else {
       end = mid - 1;

lib/internal/test_runner/utils.js

@@ -454,7 +454,10 @@ function formatUncoveredLines(lines, table) {
 }
 
 const kColumns = ['stmts %', 'line %', 'branch %', 'funcs %'];
-const kColumnsKeys = ['coveredStatementPercent', 'coveredLinePercent', 'coveredBranchPercent', 'coveredFunctionPercent'];
+const kColumnsKeys = [
+  'coveredStatementPercent', 'coveredLinePercent',
+  'coveredBranchPercent', 'coveredFunctionPercent',
+];
 const kSeparator = ' | ';
 
 function buildFileTree(summary) {

test/fixtures/test-runner/coverage-multistatement.js

@@ -0,0 +1,24 @@
+'use strict';
+const test = require('node:test');
+
+// Multiple statements on one line — only first executes if condition met
+function riskyOperation(value) {
+  if (value > 0) return value * 2; return -1;
+}
+
+// Single line if/else — only one branch runs per call
+function classify(n) {
+  if (n > 0) return 'positive'; else return 'non-positive';
+}
+
+// One-liner function where early validation can skip later statements
+function processEntry(a) { if (!a) return null; return String(a).toUpperCase(); }
+
+// Uncalled function with multiple inline statements — 0% statement coverage
+function neverCalled() { const a = 1; const b = 2; return a + b; }
+
+test('multistatement coverage', () => {
+  riskyOperation(5);    // takes early return, second statement skipped
+  classify(10);         // takes positive branch, else branch skipped
+  processEntry('hello'); // passes guard, both statements execute
+});

test/fixtures/test-runner/coverage-shebang.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+'use strict';
+const test = require('node:test');
+
+// This file has a shebang line. Without allowHashBang: true,
+// acorn would fail to parse it and statement coverage would
+// degrade to 0 total statements.
+
+function greet(name) {
+  return 'Hello, ' + name;
+}
+
+// Uncalled — should show as uncovered statements
+function farewell(name) {
+  return 'Goodbye, ' + name;
+}
+
+test('shebang file coverage', () => {
+  greet('world');
+});

test/fixtures/test-runner/coverage-unparseable-test.js

@@ -0,0 +1,10 @@
+'use strict';
+const test = require('node:test');
+const unparseable = require('./coverage-unparseable.js');
+
+test('require unparseable module', () => {
+  // The unparseable module loads fine at runtime (CJS wrapper makes
+  // top-level `using` valid) but acorn cannot parse the raw source.
+  // Statement coverage should degrade gracefully for that file.
+  require('node:assert').ok(unparseable.ok);
+});

test/fixtures/test-runner/coverage-unparseable.js

@@ -0,0 +1,8 @@
+'use strict';
+// Top-level `using` is valid inside the CJS module wrapper (V8 wraps this
+// in a function) but the ECMAScript spec forbids `using` at the top level
+// of a Script. Since acorn parses raw source as sourceType:'script',
+// this file triggers a parse error -> getStatements() returns null.
+// Line, branch, and function coverage still work normally.
+using resource = { [Symbol.dispose]() {} };
+module.exports = { ok: true };