[Yashwanth Reddy Verupaka (yashwanth195)]

Summary

Allow plugin packages to declare defaultPluginName in heft-plugin.json. A package can then add named plugins without breaking existing heft.json references that omit pluginName.

Details

• Explicit pluginName takes precedence over the package default.
• Without a default, single-plugin inference and the error for ambiguous packages remain unchanged.
• Defaults can name task or lifecycle plugins. Unknown defaults are rejected when the manifest loads; empty defaults fail schema validation.

Includes focused tests, updated schema/template descriptions, and a minor changefile. This is a standalone change with no sharding behavior.

How it was tested

Windows, Node.js 24.22.1, Rush 5.182.0. Dependencies were installed from the lockfile with node common\scripts\install-run-rush.js install --to @rushstack/heft (passed).

Working directory	Command	Result
Repository root	node common\scripts\install-run-rush.js build --to @rushstack/heft	Passed: 17 successful build operations, 2 no-ops
apps\heft	node ..\..\common\scripts\install-run-rushx.js _phase:test --test-path-pattern HeftPluginConfiguration --disable-code-coverage	Passed: 1 suite, 16 tests
Repository root	node common\scripts\install-run-rush.js change --verify --target-branch upstream/main	Passed

Tests cover task and lifecycle defaults, explicit overrides, unknown explicit names, legacy single-plugin inference, ambiguous packages, invalid defaults, and mixed task/lifecycle packages. No sharding acceptance or coverage suites were run.

Impacted documentation

https://heft.rushstack.io/pages/configs/heft_json/

Updated the pluginName descriptions in heft.schema.json and the heft.json template, and documented defaultPluginName in heft-plugin.schema.json.

[David Michon (dmichon-msft)]

It annoys me that we ever allowed pluginName to be omitted, but this is the least bad way to fix, I guess.