feat(template-input): inject Go struct doc comments into generated YAML templates

[graham-chainlink]

Inspired from this conversation - https://chainlink-core.slack.com/archives/C07CF8V02KX/p1783508226153149

What changed

The template-input command now extracts // and /* */ doc comments from Go source files via AST parsing (golang.org/x/tools/go/packages + go/parser) and injects them as # comment lines in the generated YAML templates, giving users useful hints on what values to set.

Three levels of comments are surfaced:

• Changeset-level: the doc comment above the changeset type declaration (e.g. // MyChangeset deploys ...)
• Struct-level: the doc comment above the input/config struct type (e.g. // MyConfig is the config for ...) — emitted at the start of the payload: section and for any nested structs
• Field-level: the doc comment above each struct field

Both // single-line and /* * ... */ block comment styles are supported, with star prefixes stripped from block comments.

Why

When users run chainlink-deployments durable-pipeline template-input, the generated YAML previously only showed field names and type annotations (# string, # int). Without context, users had to read the Go source to understand what values to set. By surfacing the doc comments that changeset authors already write, the YAML templates become self-documenting.

Example

Go struct with different comment styles

// envInputFixtureChangeset is a stub changeset typed with envInputFixtureConfig,
// used by the golden test to verify the WithEnvInput path.
type envInputFixtureChangeset struct{}

// envInputFixtureConfig is the config struct for envInputFixtureChangeset.
type envInputFixtureConfig struct {
	// FeedURL is the HTTP endpoint the workflow polls for data.
	FeedURL string `yaml:"feedURL" json:"feedURL"`

	// PollIntervalSec is the interval between polls in seconds.
	// Must be a positive integer.
	PollIntervalSec int `yaml:"pollIntervalSec" json:"pollIntervalSec"`

	// Enabled controls whether the feed is active.
	Enabled bool `yaml:"enabled" json:"enabled"`

	/* BlockCommentField demonstrates a multi-line block comment
	 * with star-prefixed lines, which should be stripped in the
	 * generated YAML output.
	 */
	BlockCommentField string `yaml:"blockComment" json:"blockComment"`

	NoComment string `yaml:"noComment" json:"noComment"`
}

Generated YAML (WithEnvInput path)

# Generated via template-input command
environment: testnet
domain: mydomain
changesets:
  # Input type: template.envInputFixtureConfig
  # envInputFixtureChangeset is a stub changeset typed with envInputFixtureConfig,
  # used by the golden test to verify the WithEnvInput path.
  - 0002_env:
      # Optional: Chain overrides (uncomment if needed)
      # chainOverrides:
      #   - 1  # Chain selector 1
      #   - 2  # Chain selector 2
      payload:
        # envInputFixtureConfig is the config struct for envInputFixtureChangeset.
        # FeedURL is the HTTP endpoint the workflow polls for data.
        feedURL: # string
        # PollIntervalSec is the interval between polls in seconds.
        # Must be a positive integer.
        pollIntervalSec: # int
        # Enabled controls whether the feed is active.
        enabled: # bool
        # BlockCommentField demonstrates a multi-line block comment
        # with star-prefixed lines, which should be stripped in the
        # generated YAML output.
        blockComment: # string
        noComment: # string

[changeset-bot]

🦋 Changeset detected

Latest commit: 9808448

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

This PR includes changesets to release 1 package

Name	Type
chainlink-deployments-framework	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 comment extraction from Go source (via go/packages + go/parser) and threads it through the template generation pipeline so generated YAML templates can include helpful # comment lines derived from Go doc comments.

Changes:

• Introduces a commentProvider (commentExtractor) that AST-parses Go packages and caches struct/field doc comments.
• Updates YAML template generation to inject changeset-level and field-level comments into template-input output.
• Adds end-to-end golden tests (plus fixtures + golden YAML files) to lock in the new output format.

Reviewed changes

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

Show a summary per file

File	Description
go.mod	Promotes golang.org/x/tools to a direct dependency and adds golang.org/x/mod (indirect) for AST/package loading support.
engine/cld/pipeline/template/template.go	Wires comment extraction into changeset section generation and struct/field YAML rendering.
engine/cld/pipeline/template/template_test.go	Updates unit tests for new function signatures (adds comments parameter).
engine/cld/pipeline/template/golden_test.go	Adds golden-file test harness covering full GenerateMultiChangesetYAML output variants.
engine/cld/pipeline/template/fixture_changeset_env.go	Adds non-test fixtures (changesets + structs) to exercise env-input and typed-resolver paths.
engine/cld/pipeline/template/comments.go	Implements AST-based doc comment extraction with per-package caching.
engine/cld/pipeline/template/comments_test.go	Adds tests validating real-world comment extraction and nil-safe behavior.
engine/cld/pipeline/template/comments_test_fixture.go	Adds a non-test struct with representative doc comments for extraction tests.
engine/cld/pipeline/template/testdata/multi_changeset_env_input.golden.yaml	Golden output capturing comment-injected YAML for WithEnvInput.
engine/cld/pipeline/template/testdata/multi_changeset_typed_resolver.golden.yaml	Golden output capturing comment-injected YAML for WithConfigResolver input-type behavior.
engine/cld/changeset/common.go	Extends Configurations with ChangesetType to enable changeset-level doc comment lookups.
.changeset/clever-steaks-end.md	Records a minor release note for the new template comment injection feature.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cl-sonarqube-production]

Quality Gate passed

Issues
3 New issues
0 Fixed issues
0 Accepted issues

Measures
0 Security Hotspots
87.4% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube

[DimitriosNaikopoulos]

Should fixtures be part of the testdata since they are not actually part of the codebase itself (we can compile without them) 🤔

[DimitriosNaikopoulos]

Should we may this a bit more clear that this is the struct comments eg Struct: envInputFixtureConfig is the config struct for envInputFixtureChangeset

Currently looks the same as the other inputs and it looks like we are missing a field from the yaml (especially if in their comment they do not mention that this is the struct and not a field in the struct.

example

# envInputFixtureConfig provides input to the changeset
type envInputFixtureConfig struct {
...
}

Generated yaml

# Generated via template-input command
environment: testnet
domain: mydomain
changesets:
 - 0002_env:
      # Optional: Chain overrides (uncomment if needed)
      # chainOverrides:
      #   - 1  # Chain selector 1
      #   - 2  # Chain selector 2
      payload:
        # envInputFixtureConfig provides input to the changeset <-- What is envInputFixtureConfig?
        # FeedURL is the HTTP endpoint the workflow polls for data.
        feedURL: # string

Basically since the yaml doesn't have a field for the struct name we want to make it clear that this is the struct commend and not a missing field especially when the comment is something generic.