Add proxy chain support to gas stats output

[schaable]

This PR adds proxy chain information to the pnpm hardhat test --gas-stats and pnpm hardhat test --gas-stats-json gas-stats.json commands. It's best reviewed commit by commit, as it includes some refactors.

Summary

• Gas measurements are now grouped by (contractFqn, proxyChain): calls made directly vs through a proxy produce separate entries.
• Deployment stats are duplicated across all proxy-chain variants of the same contract.
• The proxyChain is stored as-is (full chain including the implementation) in the raw measurement data. The last element is only stripped at display time, as it's redundant with the contract name.
• Internal FQN prefixes (project/, npm @version/) are stripped from proxy names at the display/JSON boundary, not in the stored data.
• Table output shows proxy information as a subtitle line ((via Proxy2 → Proxy)) using a new subtitle field on TableSectionHeader.
• JSON output keys use the display format (contracts/Impl.sol:Impl (via Proxy)) and include the proxyChain array, so no parsing from keys is required.
• Internal grouping uses null-byte-separated map keys to avoid collisions with characters that may appear in FQNs.

Docs: NomicFoundation/hardhat-website#251

Closes #8085

[changeset-bot]

🦋 Changeset detected

Latest commit: fadaab3

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

This PR includes changesets to release 2 packages

Name	Type
@nomicfoundation/hardhat-utils	Patch
hardhat	Patch

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

This PR extends Hardhat’s gas analytics output to include proxy-chain information, so gas stats are grouped and displayed separately for direct calls vs proxied calls (and JSON output includes the proxy chain explicitly). It also refactors several gas-analytics helper utilities into a shared helpers module and updates table rendering to support section-header subtitles.

Changes:

• Group gas measurements by (contractFqn, proxyChain) and duplicate deployment stats across proxy-chain variants.
• Add proxy-chain-aware display/JSON keys and include proxyChain in JSON contract entries.
• Enhance table formatting to render a section-header subtitle line (used for proxy-chain labels).

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/hardhat/test/internal/builtin-plugins/test/task-action.ts	Updates tests to include proxyChain in function measurements.
packages/hardhat/test/internal/builtin-plugins/gas-analytics/gas-analytics-manager.ts	Expands test coverage for proxy-chain grouping, JSON keys, and helper functions.
packages/hardhat/src/internal/builtin-plugins/network-manager/edr/utils/convert-to-edr.ts	Propagates proxyChain from EDR gas report into Hardhat gas measurements.
packages/hardhat/src/internal/builtin-plugins/gas-analytics/types.ts	Adds proxyChain to function measurements and JSON contract entries.
packages/hardhat/src/internal/builtin-plugins/gas-analytics/snapshot-cheatcodes.ts	Switches getUserFqn import to the helpers module.
packages/hardhat/src/internal/builtin-plugins/gas-analytics/helpers.ts	Adds proxy-chain/grouping/display helper functions and keeps existing compatibility helpers.
packages/hardhat/src/internal/builtin-plugins/gas-analytics/gas-analytics-manager.ts	Implements proxy-chain grouping, report subtitles, and JSON output changes.
packages/hardhat/src/internal/builtin-plugins/gas-analytics/function-gas-snapshots.ts	Switches getUserFqn import to the helpers module.
packages/hardhat-utils/test/format.ts	Adds tests for rendering section-header subtitles and table expansion.
packages/hardhat-utils/src/internal/format.ts	Accounts for subtitle width when computing heading width.
packages/hardhat-utils/src/format.ts	Adds subtitle?: string to TableSectionHeader and renders it on a second line.
packages/example-project/test/node/Proxies.ts	Adds node-based example tests exercising proxied calls for gas stats.
packages/example-project/test/contracts/Proxies.t.sol	Adds forge-based example tests exercising proxied calls for gas stats.
packages/example-project/contracts/Proxies.sol	Adds simple proxy/proxy-chain contracts for the example project.
.changeset/seven-insects-move.md	Changeset for releasing the updated gas-stats outputs.

[Copilot]

Pull request overview

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

[alcuadrado]

I think this PR looks good. It needs a good explanation in the docs about the format of the JSON. In particular, that the top-level keys are labels, and how sourceName, contractName, and proxyChain should be combined. Both in the cases when there's a proxy and when there isn't.