Add --gas-stats-json global option for JSON gas stats export

[schaable]

This PR adds a new --gas-stats-json <path> global option that writes gas usage statistics to a JSON file at the specified path. It works independently of --gas-stats (terminal table output), so either or both flags can be used together.

Docs: NomicFoundation/hardhat-website#238

Closes #7990.

[changeset-bot]

🦋 Changeset detected

Latest commit: 52b1a79

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@nomicfoundation/hardhat-node-test-runner	Patch
@nomicfoundation/hardhat-mocha	Patch
@nomicfoundation/hardhat-errors	Patch
hardhat	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

Pull request overview

Adds support for exporting gas usage statistics from test runs to a JSON file via a new global CLI option, enabling CI/custom tooling workflows alongside (or instead of) the existing terminal table output.

Changes:

• Introduces --gas-stats-json <path> global option and wires it into test flows (built-in test task, mocha runner, node test runner, solidity test runner).
• Implements JSON generation and file writing in the gas analytics manager (including directory creation and invalid path handling).
• Adds/updates tests, error descriptor, and release metadata (.changeset + peer bumps).

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
v-next/hardhat/test/internal/hre-initialization.ts	Asserts the new global option is present in resolved HRE global options
v-next/hardhat/test/internal/cli/main.ts	Updates expected global help output to include --gas-stats-json
v-next/hardhat/test/internal/builtin-plugins/gas-analytics/gas-analytics-manager.ts	Adds unit tests for JSON generation and JSON file writing behavior
v-next/hardhat/src/internal/builtin-plugins/test/task-action.ts	Ensures gas analytics collection/reporting can run for JSON export even when table output is disabled
v-next/hardhat/src/internal/builtin-plugins/solidity-test/task-action.ts	Enables gas measurement collection when JSON export is requested
v-next/hardhat/src/internal/builtin-plugins/gas-analytics/types.ts	Defines JSON output types and extends the manager interface with writeGasStatsJson
v-next/hardhat/src/internal/builtin-plugins/gas-analytics/type-extensions.ts	Extends GlobalOptions with gasStatsJson
v-next/hardhat/src/internal/builtin-plugins/gas-analytics/index.ts	Registers the new global option definition
v-next/hardhat/src/internal/builtin-plugins/gas-analytics/hook-handlers/test.ts	Saves measurements and emits JSON output at test run end when requested
v-next/hardhat/src/internal/builtin-plugins/gas-analytics/hook-handlers/hre.ts	Instantiates the gas analytics manager when either gas stats output is enabled
v-next/hardhat/src/internal/builtin-plugins/gas-analytics/gas-analytics-manager.ts	Implements JSON generation + writing with validation
v-next/hardhat-node-test-runner/src/task-action.ts	Ensures worker-done hook is loaded when JSON export is requested
v-next/hardhat-mocha/src/task-action.ts	Ensures worker-done hook is loaded when JSON export is requested
v-next/hardhat-errors/src/descriptors.ts	Adds INVALID_FILE_PATH error used when output path is a directory
.peer-bumps.json	Adds peer bump reasons for packages now reading gasStatsJson
.changeset/wet-apes-kick.md	Declares release bumps for affected packages

[Copilot]

Pull request overview

This PR introduces a new global CLI option --gas-stats-json <path> to export gas usage statistics as JSON, enabling CI/custom tooling to consume the same data currently shown via --gas-stats terminal output.

Changes:

• Add --gas-stats-json global option wiring (types, CLI help text, hooks/task actions).
• Implement JSON generation and file writing in the gas analytics manager (including path validation).
• Add/update tests and error descriptors to cover JSON export behavior and invalid paths.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
v-next/hardhat/test/internal/hre-initialization.ts	Updates expected default global options to include gasStatsJson.
v-next/hardhat/test/internal/cli/main.ts	Updates CLI help output snapshots to include --gas-stats-json.
v-next/hardhat/test/internal/builtin-plugins/gas-analytics/gas-analytics-manager.ts	Adds test coverage for JSON generation, sorting, and file output/validation behavior.
v-next/hardhat/src/internal/builtin-plugins/test/task-action.ts	Ensures gas stats collection/reporting is enabled when JSON output is requested; writes JSON at end of aggregated test run.
v-next/hardhat/src/internal/builtin-plugins/solidity-test/task-action.ts	Enables gas report generation for Solidity tests when --gas-stats-json is used.
v-next/hardhat/src/internal/builtin-plugins/gas-analytics/types.ts	Defines JSON output types and extends manager interface with writeGasStatsJson.
v-next/hardhat/src/internal/builtin-plugins/gas-analytics/type-extensions.ts	Extends GlobalOptions with gasStatsJson?: string.
v-next/hardhat/src/internal/builtin-plugins/gas-analytics/index.ts	Registers the new global option with ArgumentType.FILE_WITHOUT_DEFAULT.
v-next/hardhat/src/internal/builtin-plugins/gas-analytics/hook-handlers/test.ts	Collects measurements when JSON is requested; writes JSON at test-run completion.
v-next/hardhat/src/internal/builtin-plugins/gas-analytics/hook-handlers/hre.ts	Instantiates gas analytics manager when either gas stats flag is set.
v-next/hardhat/src/internal/builtin-plugins/gas-analytics/gas-analytics-manager.ts	Implements JSON generation and file writing with directory-path validation.
v-next/hardhat-utils/src/env.ts	Expands env-global-options typing to allow undefined values.
v-next/hardhat-node-test-runner/src/task-action.ts	Treats gasStatsJson as a trigger for test-worker wiring (like gasStats).
v-next/hardhat-mocha/src/task-action.ts	Treats gasStatsJson as a trigger for test-worker wiring (like gasStats).
v-next/hardhat-errors/src/descriptors.ts	Adds INVALID_FILE_PATH error used when output path is a directory.
.peer-bumps.json	Records peer bumps required due to new global option usage in related packages.
.changeset/wet-apes-kick.md	Adds release notes/versions for the new option across packages.