Skip to content

Commit 350c6d4

Browse files
committed
fix(template): preserve operator comments above modeline on in-place rewrite
`talm template -I` previously parsed the node file via a strict first-line-only modeline reader. Operator-authored comments above the modeline (project documentation, deployment notes, context hints) were either rejected at parse time or lost on rewrite. The intended `-I` behavior is regeneration that preserves the operator's leading block. Adds `modeline.FindAndParseModeline` that scans the file allowing `#`-prefixed comment lines and blank lines as a leading prefix, returns them verbatim alongside the parsed modeline, and rejects any non-comment line that precedes the modeline. `talm template -I` prepends the captured leading block back to the regenerated file so operator documentation survives. The strict first-line-only `ReadAndParseModeline` is removed — `FindAndParseModeline` is now the single entry point for every node-file consumer (apply, upgrade, completion, wrapped talosctl commands, template). The file-shape contract is uniform across the talm surface. The classifier distinguishes three file shapes via `ErrModelineNotFound`: modeline-on-top (parsed and returned), orphan (no `# talm:` line anywhere — surfaces ErrModelineNotFound so callers route to the side-patch / direct-patch path), and misplaced (a `# talm:` line sits below YAML content — rejected with a specific hint). "Modeline below YAML" detection is column-0-strict: indented `# talm:` text inside the YAML body is treated as a regular comment, not a misplaced modeline, so operator-authored documentation comments referencing the modeline don't falsely trip the gate. Assisted-By: Claude <[email protected]> Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent e1b0688 commit 350c6d4

7 files changed

Lines changed: 544 additions & 93 deletions

File tree

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
// Copyright Cozystack Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package commands
16+
17+
import (
18+
"os"
19+
"path/filepath"
20+
"strings"
21+
"testing"
22+
)
23+
24+
// TestPrependLeadingComments_PreservesAllLines pins the canonical
25+
// in-place rewrite shape (#178): operator-authored `#`-prefixed
26+
// and blank lines that lived above the modeline in the source file
27+
// are re-emitted at the top of the regenerated content. Without
28+
// this guarantee, `talm template -I` silently strips operator
29+
// documentation on every rewrite.
30+
func TestPrependLeadingComments_PreservesAllLines(t *testing.T) {
31+
leading := []string{
32+
"# Note 1: reset 2026-05-12 after ticket OPS-1234",
33+
"# Note 2: DO NOT edit values directly",
34+
"",
35+
"# Note 3: extra context",
36+
}
37+
rendered := "# talm: nodes=[\"1.2.3.4\"]\n# THIS FILE IS AUTOGENERATED…\nmachine:\n type: controlplane\n"
38+
39+
got := prependLeadingComments(leading, rendered)
40+
41+
// Every leading line must appear, in order, before the
42+
// rendered output.
43+
want := "# Note 1: reset 2026-05-12 after ticket OPS-1234\n" +
44+
"# Note 2: DO NOT edit values directly\n" +
45+
"\n" +
46+
"# Note 3: extra context\n" +
47+
rendered
48+
if got != want {
49+
t.Errorf("prependLeadingComments mismatch\ngot:\n%s\n\nwant:\n%s", got, want)
50+
}
51+
}
52+
53+
// TestPrependLeadingComments_EmptyLeading_ReturnsOutputUnchanged
54+
// pins the degenerate case: no leading comments → output passes
55+
// through verbatim. Pinning this avoids a future refactor where
56+
// the helper accidentally appends an empty line for the
57+
// "no comments" case.
58+
func TestPrependLeadingComments_EmptyLeading_ReturnsOutputUnchanged(t *testing.T) {
59+
rendered := "# talm: nodes=[\"1.2.3.4\"]\nmachine:\n type: controlplane\n"
60+
61+
if got := prependLeadingComments(nil, rendered); got != rendered {
62+
t.Errorf("nil leading must pass output through; got %q want %q", got, rendered)
63+
}
64+
65+
if got := prependLeadingComments([]string{}, rendered); got != rendered {
66+
t.Errorf("empty leading must pass output through; got %q want %q", got, rendered)
67+
}
68+
}
69+
70+
// TestWriteInplaceRendered_PreservesOperatorCommentsAboveModeline
71+
// pins the end-to-end behaviour wired through templateOneFile:
72+
// when `talm template -I` rewrites a node file, the operator's
73+
// leading-comment block survives the regeneration. Reaches in via
74+
// the same writeInplaceRendered helper templateOneFile uses, so a
75+
// future refactor that changes the call site (different writer,
76+
// different file path, etc.) but keeps the helper signature must
77+
// still pass this contract.
78+
func TestWriteInplaceRendered_PreservesOperatorCommentsAboveModeline(t *testing.T) {
79+
dir := t.TempDir()
80+
file := filepath.Join(dir, "node.yaml")
81+
82+
leading := []string{
83+
"# This node was reset 2026-05-12 after ticket OPS-1234",
84+
"# DO NOT edit values directly; modify values.yaml and re-template",
85+
}
86+
rendered := "# talm: nodes=[\"1.2.3.4\"], endpoints=[\"1.2.3.4\"], templates=[\"templates/cp.yaml\"]\n" +
87+
"# THIS FILE IS AUTOGENERATED. PREFER TEMPLATE EDITS OVER MANUAL ONES.\n" +
88+
"machine:\n type: controlplane\n"
89+
90+
combined := prependLeadingComments(leading, rendered)
91+
92+
if err := writeInplaceRendered(file, combined); err != nil {
93+
t.Fatalf("writeInplaceRendered: %v", err)
94+
}
95+
96+
got, err := os.ReadFile(file)
97+
if err != nil {
98+
t.Fatalf("read back: %v", err)
99+
}
100+
101+
// The written file must start with the operator's leading
102+
// lines, then the modeline, then the rendered body — in this
103+
// exact order.
104+
gotStr := string(got)
105+
if !strings.HasPrefix(gotStr, leading[0]+"\n"+leading[1]+"\n") {
106+
t.Errorf("operator comments missing or out of order at start of file; got:\n%s", gotStr)
107+
}
108+
109+
modelineIdx := strings.Index(gotStr, "# talm:")
110+
if modelineIdx <= 0 {
111+
t.Errorf("modeline must follow the leading comments, not start the file; got:\n%s", gotStr)
112+
}
113+
}

‎pkg/commands/root.go‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -248,7 +248,14 @@ func DetectRootForTemplate(templatePath string) (string, error) {
248248
}
249249

250250
func processModelineAndUpdateGlobals(configFile string, nodesFromArgs, endpointsFromArgs, overwrite bool) ([]string, error) {
251-
modelineConfig, err := modeline.ReadAndParseModeline(configFile)
251+
// FindAndParseModeline accepts operator-authored comment / blank
252+
// lines before the modeline (#178). Every workflow that consumes
253+
// node files — apply, upgrade, template -I, completion, wrapped
254+
// talosctl subcommands — must agree on file shape; the strict
255+
// "first line must be modeline" rule of the old ReadAndParseModeline
256+
// would silently break the apply / upgrade / talosctl path against
257+
// files that template -I just produced.
258+
_, modelineConfig, err := modeline.FindAndParseModeline(configFile)
252259
if err != nil {
253260
// Don't print the error here — cobra surfaces the wrapped
254261
// return through stderr at the command level. Printing here

‎pkg/commands/root_test.go‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,48 @@ machine:
4040
}
4141
}
4242

43+
// TestProcessModelineAndUpdateGlobals_AcceptsLeadingComments pins
44+
// that the modeline parser used by apply / upgrade / completion /
45+
// wrapped talosctl commands shares the same file-shape contract as
46+
// `talm template -I` (#178). Without this, a node file produced by
47+
// the in-place rewrite — which preserves operator comments above
48+
// the modeline — would fail on the very next `talm apply -f` /
49+
// `talm upgrade -f` call against the same file.
50+
func TestProcessModelineAndUpdateGlobals_AcceptsLeadingComments(t *testing.T) {
51+
origNodes := GlobalArgs.Nodes
52+
origEndpoints := GlobalArgs.Endpoints
53+
t.Cleanup(func() {
54+
GlobalArgs.Nodes = origNodes
55+
GlobalArgs.Endpoints = origEndpoints
56+
})
57+
58+
dir := t.TempDir()
59+
configFile := filepath.Join(dir, "node.yaml")
60+
content := "# Operator note: reset 2026-05-12 after ticket OPS-1234\n" +
61+
"# DO NOT edit values directly; modify values.yaml and re-template\n" +
62+
"# talm: nodes=[\"10.0.0.1\"], endpoints=[\"10.0.0.1\"], templates=[\"templates/cp.yaml\"]\n" +
63+
"machine:\n type: controlplane\n"
64+
if err := os.WriteFile(configFile, []byte(content), 0o644); err != nil {
65+
t.Fatal(err)
66+
}
67+
68+
GlobalArgs.Nodes = nil
69+
GlobalArgs.Endpoints = nil
70+
71+
templates, err := processModelineAndUpdateGlobals(configFile, false, false, true)
72+
if err != nil {
73+
t.Fatalf("modeline parse must accept leading operator comments per #178; got error: %v", err)
74+
}
75+
76+
if len(templates) != 1 || templates[0] != "templates/cp.yaml" {
77+
t.Errorf("templates = %v, want [templates/cp.yaml]", templates)
78+
}
79+
80+
if len(GlobalArgs.Nodes) != 1 || GlobalArgs.Nodes[0] != "10.0.0.1" {
81+
t.Errorf("GlobalArgs.Nodes = %v, want [10.0.0.1]", GlobalArgs.Nodes)
82+
}
83+
}
84+
4385
func TestProcessModelineAndUpdateGlobals_NoTemplates(t *testing.T) {
4486
origNodes := GlobalArgs.Nodes
4587
origEndpoints := GlobalArgs.Endpoints

‎pkg/commands/template.go‎

Lines changed: 49 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import (
1919
"fmt"
2020
"os"
2121
"path/filepath"
22+
"strings"
2223

2324
"github.com/cockroachdb/errors"
2425
"github.com/cozystack/talm/pkg/engine"
@@ -57,8 +58,16 @@ var templateCmdFlags struct {
5758
var templateCmd = &cobra.Command{
5859
Use: "template",
5960
Short: "Render templates locally and display the output",
60-
Long: ``,
61-
Args: cobra.NoArgs,
61+
Long: `Render Talos configuration templates locally.
62+
63+
Multi-file invocation note: unlike ` + "`talm apply`" + ` (where the first -f
64+
anchors and later -f files are stacked side-patches per #184),
65+
` + "`talm template -f a.yaml -f b.yaml -f c.yaml`" + ` renders each file
66+
independently driven by its own modeline. This is intentional —
67+
template's per-file render mirrors the "regenerate the artifact
68+
beside the source" workflow, while apply's chain models "compose a
69+
single MachineConfig and apply it once".`,
70+
Args: cobra.NoArgs,
6271
PreRunE: func(cmd *cobra.Command, _ []string) error {
6372
templateCmdFlags.valueFiles = append(Config.TemplateOptions.ValueFiles, templateCmdFlags.valueFiles...)
6473
templateCmdFlags.values = append(Config.TemplateOptions.Values, templateCmdFlags.values...)
@@ -179,7 +188,11 @@ func templateWithFiles(args []string) func(ctx context.Context, c *client.Client
179188
// mode. Splitting the per-file work out of templateWithFiles keeps
180189
// the outer function's cognitive complexity within the linter's gate.
181190
func templateOneFile(ctx context.Context, args []string, configFile string, firstFileProcessed *bool) error {
182-
modelineConfig, err := modeline.ReadAndParseModeline(configFile)
191+
// FindAndParseModeline accepts operator-authored comment / blank
192+
// lines before the modeline so `talm template -I` can preserve
193+
// them on rewrite (#178). Anything other than `#`-prefixed
194+
// comments or blanks before the modeline is still rejected.
195+
leadingComments, modelineConfig, err := modeline.FindAndParseModeline(configFile)
183196
if err != nil {
184197
return errors.Wrap(err, "modeline parsing failed")
185198
}
@@ -227,23 +240,28 @@ func templateOneFile(ctx context.Context, args []string, configFile string, firs
227240
)
228241
}
229242

230-
tmpl := buildTemplateRunner(args, configFile, firstFileProcessed)
243+
tmpl := buildTemplateRunner(args, configFile, leadingComments, firstFileProcessed)
231244

232245
return runTemplate(ctx, tmpl)
233246
}
234247

235248
// buildTemplateRunner returns the per-file render-and-emit closure.
236249
// Extracted so both templateOneFile and the dispatcher in runTemplate
237-
// can stay flat.
238-
func buildTemplateRunner(args []string, configFile string, firstFileProcessed *bool) func(ctx context.Context, c *client.Client) error {
250+
// can stay flat. leadingComments is the slice of operator-authored
251+
// `#`-prefixed / blank lines that lived above the modeline in the
252+
// source file; in-place mode prepends them to the rewritten file so
253+
// the operator's documentation survives the regeneration (#178).
254+
// Non in-place renders ignore leadingComments because the original
255+
// file is left untouched.
256+
func buildTemplateRunner(args []string, configFile string, leadingComments []string, firstFileProcessed *bool) func(ctx context.Context, c *client.Client) error {
239257
return func(ctx context.Context, c *client.Client) error {
240258
output, err := generateOutput(ctx, c, args)
241259
if err != nil {
242260
return err
243261
}
244262

245263
if templateCmdFlags.inplace {
246-
return writeInplaceRendered(configFile, output)
264+
return writeInplaceRendered(configFile, prependLeadingComments(leadingComments, output))
247265
}
248266

249267
if *firstFileProcessed {
@@ -448,7 +466,7 @@ func canonicalizeInsideRootPath(templatePath, absTemplatePath, absRootDir, relPa
448466

449467
func init() {
450468
templateCmd.Flags().BoolVarP(&templateCmdFlags.insecure, "insecure", "i", false, "template using the insecure (encrypted with no auth) maintenance service")
451-
templateCmd.Flags().StringSliceVarP(&templateCmdFlags.configFiles, "file", "f", nil, "specify config files for in-place update (can specify multiple)")
469+
templateCmd.Flags().StringSliceVarP(&templateCmdFlags.configFiles, "file", "f", nil, "node config files for in-place update (`.yaml` / `.yml`; shell completion narrows to these extensions). Each file's modeline drives the per-file render.")
452470
templateCmd.Flags().BoolVarP(&templateCmdFlags.inplace, "in-place", "I", false, "re-template and update generated files in place (overwrite them)")
453471
templateCmd.Flags().StringSliceVarP(&templateCmdFlags.valueFiles, "values", "", []string{}, "specify values in a YAML file (can specify multiple)")
454472
templateCmd.Flags().StringSliceVarP(&templateCmdFlags.templateFiles, "template", "t", []string{}, "specify templates to render manifest from (can specify multiple)")
@@ -467,6 +485,29 @@ func init() {
467485
addCommand(templateCmd)
468486
}
469487

488+
// prependLeadingComments emits the operator-authored `#`-prefixed
489+
// / blank lines that lived above the modeline in the source file
490+
// (returned by modeline.FindAndParseModeline) back at the top of
491+
// the rewritten output. Without this, `talm template -I` would
492+
// silently strip the leading comment block on every rewrite (#178).
493+
// Returns output unchanged when leading is empty (the conventional
494+
// case — modeline on line 1).
495+
func prependLeadingComments(leading []string, output string) string {
496+
if len(leading) == 0 {
497+
return output
498+
}
499+
500+
var b strings.Builder
501+
for _, line := range leading {
502+
b.WriteString(line)
503+
b.WriteByte('\n')
504+
}
505+
506+
b.WriteString(output)
507+
508+
return b.String()
509+
}
510+
470511
// writeInplaceRendered writes the rendered template output over the
471512
// node config file. Routes through secureperm because the rendered
472513
// machine config embeds certs, PKI keys, and cluster join tokens —

0 commit comments

Comments
 (0)