Skip to content

Commit a44d621

Browse files
committed
fix(build): classify describe-suffix and dirty builds as non-release
git describe --tags on a non-tag commit yields v0.29.0-5-gabc1234, and on a dirty tree at an exact tag --dirty yields v0.29.0-dirty; both shapes were classified as releases, so contributor builds — possibly with edited embedded charts — raised false chart-drift warnings in any real project and hard-failed strictCharts: true ones. releaseVersion now rejects both shapes, while the Makefile describes with --dirty so `talm --version` still carries full provenance for bug reports. Assisted-By: Claude <[email protected]> Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent 6031d46 commit a44d621

7 files changed

Lines changed: 291 additions & 8 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -254,7 +254,7 @@ This refreshes `charts/talm/` (always) and offers to update the preset templates
254254
To catch drift automatically, a release build compares the vendored `charts/talm/` against its own built-in copy on every config-loading command. The comparison is by **content**, not version number — re-vendoring after a binary bump that did not change the library is a no-op and raises no warning. When the content genuinely differs, talm prints a non-fatal warning to stderr (stdout and the exit code are unchanged):
255255

256256
```text
257-
WARN: project's vendored charts/talm/ library differs from the copy built into talm <version>; run `talm init --update --preset <preset>` to re-sync (or ignore if this is intentional)
257+
WARN: project's vendored charts/talm/ library differs from the copy built into talm <version> (modified: templates/_helpers.tpl); run `talm init --update --preset <preset>` to re-sync (or ignore if this is intentional)
258258
```
259259

260260
The remediation needs the preset name because `talm init --update` resolves the preset from `Chart.yaml`, which an init'd project does not record — pass `--preset <your-preset>` (the one you ran `talm init` with) explicitly.

‎charts/library_test.go‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,30 @@ func TestNormalizeChartMeta_LeavesNonChartYamlUntouched(t *testing.T) {
117117
}
118118
}
119119

120+
// TestEmbeddedCharts_NoCRLF makes the LF-only invariant of the embedded
121+
// tree explicit. The drift comparison normalizes CRLF on the vendored side
122+
// only, relying on .gitattributes (`* text=auto eol=lf`) to keep the
123+
// embedded side LF on every checkout; an embedded file that ever ships
124+
// CRLF would drift against every project forever, and `init --update`
125+
// could not clear it (the vendored copy normalizes to LF on read).
126+
func TestEmbeddedCharts_NoCRLF(t *testing.T) {
127+
for name, files := range map[string]func() (map[string]string, error){
128+
"PresetFiles": PresetFiles,
129+
"TalmLibraryFiles": TalmLibraryFiles,
130+
} {
131+
all, err := files()
132+
if err != nil {
133+
t.Fatalf("%s: %v", name, err)
134+
}
135+
136+
for filePath, content := range all {
137+
if strings.Contains(content, "\r\n") {
138+
t.Errorf("%s: embedded %s contains CRLF; the drift check assumes an LF-only embedded tree (enforced by .gitattributes)", name, filePath)
139+
}
140+
}
141+
}
142+
}
143+
120144
// TestNormalizeChartMeta_PreservesNestedNameVersion pins that only the
121145
// TOP-LEVEL name/version metadata lines are folded to placeholders. Nested
122146
// occurrences — dependencies[].name/version, maintainers[].name — must

‎docs/manual-test-plan.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -233,7 +233,7 @@ printf '\n{{- /* stale edit */ -}}\n' >> charts/talm/templates/_helpers.tpl
233233
talm template -f nodes/node0.yaml --offline 2>&1 >/dev/null | grep '^WARN:'
234234
```
235235

236-
Expected (default): a single line on **stderr** — `WARN: project's vendored charts/talm/ library differs from the copy built into talm <version>; run talm init --update --preset <preset> to re-sync ...` — while stdout (the rendered config) and the exit code are unchanged. Clear it and re-confirm silence:
236+
Expected (default): a single line on **stderr** — `WARN: project's vendored charts/talm/ library differs from the copy built into talm <version> (modified: templates/_helpers.tpl); run talm init --update --preset <preset> to re-sync ...` — while stdout (the rendered config) and the exit code are unchanged. The parenthesised sample names up to 5 differing paths (`modified:` / `extra:` / `missing:`) so the cause is locatable without a manual tree diff. Clear it and re-confirm silence:
237237

238238
```bash
239239
talm init --update --preset cozystack --force
@@ -242,6 +242,8 @@ talm template -f nodes/node0.yaml --offline 2>&1 >/dev/null | grep '^WARN:' && e
242242

243243
The `--preset` is required: `talm init --update` alone resolves the preset from `Chart.yaml`, which an init'd project does not record, so it errors with "preset not found in Chart.yaml dependencies" (pinned by A8) and never re-vendors. Expected: `OK: drift cleared`.
244244

245+
`init --update` re-syncs `charts/talm/` exactly: files the embedded library does not ship (an `extra:` path in the WARN — e.g. `.DS_Store`, an editor backup, a file a newer release dropped) are pruned with a `Removed charts/talm/<path>` line. Verify by dropping a stray file in `charts/talm/`, observing the `extra:` WARN, and re-running the clear step above (pinned by `TestInitUpdate_PrunesExtraneousVendoredFiles`, `TestCheckChartDrift_ExtraneousFile_DriftNamesPath`).
246+
245247
### B5a. Render with stale preset templates (preset-drift detection)
246248

247249
Unlike the library, the preset `templates/` are operator-editable, so preset drift is tracked by a pinned baseline hash in `.talm-preset.lock` (written at `init`), NOT by content-comparing the live `templates/`. A release build compares the binary's current preset hash against that baseline.

‎pkg/commands/chart_drift.go‎

Lines changed: 45 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ import (
2020
"os"
2121
"path"
2222
"path/filepath"
23+
"sort"
2324
"strings"
2425

2526
"github.com/cockroachdb/errors"
@@ -137,12 +138,54 @@ func CheckChartDrift(rootDir, binaryVersion string) (bool, string, error) {
137138
}
138139

139140
return true, fmt.Sprintf(
140-
"project's vendored charts/talm/ library differs from the copy built into talm %s; "+
141+
"project's vendored charts/talm/ library differs from the copy built into talm %s (%s); "+
141142
"run `talm init --update --preset <preset>` to re-sync (or ignore if this is intentional)",
142-
binaryVersion,
143+
binaryVersion, summarizeChartDiff(vendored, embedded),
143144
), nil
144145
}
145146

147+
// diffSampleLimit caps how many differing paths the drift message carries.
148+
// Enough to locate the cause at a glance without turning a one-line WARN
149+
// into a page when a whole release's worth of templates changed.
150+
const diffSampleLimit = 5
151+
152+
// summarizeChartDiff renders the paths where two chart trees diverge —
153+
// modified (both sides, different content), extra (vendored only), missing
154+
// (embedded only) — sorted, capped at diffSampleLimit with a "+N more"
155+
// tail. Without the paths, the operator cannot tell a stale library from
156+
// an extraneous file (.DS_Store) that `init --update` re-vendoring alone
157+
// would not have cleared.
158+
func summarizeChartDiff(vendored, embedded map[string]string) string {
159+
var diffs []string
160+
161+
for filePath, content := range vendored {
162+
embeddedContent, ok := embedded[filePath]
163+
164+
switch {
165+
case !ok:
166+
diffs = append(diffs, "extra: "+filePath)
167+
case content != embeddedContent:
168+
diffs = append(diffs, "modified: "+filePath)
169+
}
170+
}
171+
172+
for filePath := range embedded {
173+
if _, ok := vendored[filePath]; !ok {
174+
diffs = append(diffs, "missing: "+filePath)
175+
}
176+
}
177+
178+
sort.Strings(diffs)
179+
180+
more := ""
181+
if len(diffs) > diffSampleLimit {
182+
more = fmt.Sprintf(", +%d more", len(diffs)-diffSampleLimit)
183+
diffs = diffs[:diffSampleLimit]
184+
}
185+
186+
return strings.Join(diffs, ", ") + more
187+
}
188+
146189
// presetLockName is the project-root file that records the pristine preset a
147190
// project was generated from. Unlike charts/talm/ (vendored library, never
148191
// operator-edited, content-checked by CheckChartDrift), the preset templates

‎pkg/commands/chart_drift_test.go‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,58 @@ func TestCheckChartDrift_ContentChange_Drift(t *testing.T) {
123123
}
124124
}
125125

126+
// TestCheckChartDrift_ExtraneousFile_DriftNamesPath pins two contracts for
127+
// the "extra file in the talm-owned tree" shape (.DS_Store, editor backup,
128+
// a file a newer library dropped): it IS drift — the vendored tree no
129+
// longer matches the binary — and the message must name the offending
130+
// path. Without the path the operator gets a warning that
131+
// `init --update --preset` alone cannot clear and no way to locate why.
132+
func TestCheckChartDrift_ExtraneousFile_DriftNamesPath(t *testing.T) {
133+
root := writeVendoredTalmLibrary(t, "0.30.0")
134+
135+
if err := os.WriteFile(filepath.Join(root, "charts", "talm", ".DS_Store"), []byte{0x00, 0x01}, 0o644); err != nil {
136+
t.Fatalf("write extraneous file: %v", err)
137+
}
138+
139+
drift, msg, err := CheckChartDrift(root, "0.30.0")
140+
if err != nil {
141+
t.Fatalf("CheckChartDrift: %v", err)
142+
}
143+
144+
if !drift {
145+
t.Fatal("an extraneous file in the vendored tree must be reported as drift")
146+
}
147+
148+
if !strings.Contains(msg, "extra: .DS_Store") {
149+
t.Errorf("drift message must name the extraneous path; got %q", msg)
150+
}
151+
}
152+
153+
// TestCheckChartDrift_ModifiedFile_DriftNamesPath pins that a content
154+
// change is reported with the modified path, so the operator can see WHAT
155+
// drifted instead of diffing the tree by hand.
156+
func TestCheckChartDrift_ModifiedFile_DriftNamesPath(t *testing.T) {
157+
root := writeVendoredTalmLibrary(t, "0.30.0")
158+
159+
helpers := filepath.Join(root, "charts", "talm", "templates", "_helpers.tpl")
160+
if err := os.WriteFile(helpers, []byte("{{- /* divergent */ -}}\n"), 0o644); err != nil {
161+
t.Fatalf("write helpers: %v", err)
162+
}
163+
164+
drift, msg, err := CheckChartDrift(root, "0.30.0")
165+
if err != nil {
166+
t.Fatalf("CheckChartDrift: %v", err)
167+
}
168+
169+
if !drift {
170+
t.Fatal("a modified vendored file must be reported as drift")
171+
}
172+
173+
if !strings.Contains(msg, "modified: templates/_helpers.tpl") {
174+
t.Errorf("drift message must name the modified path; got %q", msg)
175+
}
176+
}
177+
126178
// TestCheckChartDrift_CRLFVendoredCopy_NoDrift pins EOL-insensitivity: a
127179
// project cloned on Windows with core.autocrlf=true (the Git for Windows
128180
// default) materializes the vendored charts/talm/ with CRLF endings while

‎pkg/commands/init.go‎

Lines changed: 90 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import (
1919
"bytes"
2020
"fmt"
2121
"io"
22+
"io/fs"
2223
"net"
2324
"net/url"
2425
"os"
@@ -75,12 +76,13 @@ const (
7576
// secret-bearing files so an over-permissive umask cannot widen
7677
// access.
7778
secureDirMode os.FileMode = 0o700
78-
// reportVerbCreated and reportVerbUpdated are the operator-facing
79-
// verbs the init flow prints when materialising or rewriting a
80-
// project artefact. Hoisted so goconst sees a single canonical
81-
// reference for each.
79+
// reportVerbCreated, reportVerbUpdated, and reportVerbRemoved are
80+
// the operator-facing verbs the init flow prints when materialising,
81+
// rewriting, or pruning a project artefact. Hoisted so goconst sees
82+
// a single canonical reference for each.
8283
reportVerbCreated = "Created"
8384
reportVerbUpdated = "Updated"
85+
reportVerbRemoved = "Removed"
8486
)
8587

8688
// resolveTalosconfigEndpoints picks the endpoint list to embed in
@@ -817,6 +819,81 @@ func writeSecretsBundleToFile(bundle *secrets.Bundle) error {
817819
return writeSecureToDestination(bundleBytes, secretsFile)
818820
}
819821

822+
// pruneVendoredTalmLibrary removes files under charts/talm/ that the
823+
// embedded library does not ship — leftovers from an older talm release or
824+
// strays (.DS_Store, editor backups). The tree is talm-owned and never
825+
// operator-edited (see talmLibraryName in charts/charts.go), so removal is
826+
// safe; keeping such files would leave the content-drift check permanently
827+
// firing on a tree that `init --update` claims to have re-synced.
828+
// presetFiles is the embedded set keyed "<chart>/<path>"; a vendored file
829+
// survives iff "talm/<rel>" is a key. Directories the prune leaves empty
830+
// are removed too, so the tree matches the embedded library exactly. A
831+
// missing charts/talm/ is a no-op. All operations go through an os.Root
832+
// scoped to charts/talm/ (mirroring vendoredTalmFiles), so a symlink inside
833+
// the tree cannot redirect a removal outside the project; symlinks are
834+
// removed as entries, never followed.
835+
func pruneVendoredTalmLibrary(presetFiles map[string]string) error {
836+
base := filepath.Join(Config.RootDir, "charts", "talm")
837+
838+
root, err := os.OpenRoot(base)
839+
if err != nil {
840+
if errors.Is(err, fs.ErrNotExist) {
841+
return nil
842+
}
843+
844+
return errors.Wrapf(err, "opening vendored talm library %q", base)
845+
}
846+
defer root.Close()
847+
848+
var seenDirs []string
849+
850+
walkErr := fs.WalkDir(root.FS(), ".", func(filePath string, entry fs.DirEntry, err error) error {
851+
if err != nil {
852+
return errors.Wrapf(err, "walking vendored talm library at %q", filePath)
853+
}
854+
855+
if entry.IsDir() {
856+
if filePath != "." {
857+
seenDirs = append(seenDirs, filePath)
858+
}
859+
860+
return nil
861+
}
862+
863+
// root.FS() keys are "/"-separated and relative to base, matching
864+
// the "<chart>/<path>" shape of the embedded set.
865+
if _, ok := presetFiles[presetTalmLibrary+"/"+filePath]; ok {
866+
return nil
867+
}
868+
869+
if err := root.Remove(filePath); err != nil {
870+
return errors.Wrapf(err, "pruning extraneous vendored file %q", filePath)
871+
}
872+
873+
fmt.Fprintf(os.Stderr, "%s %s\n", reportVerbRemoved, filepath.Join("charts", "talm", filepath.FromSlash(filePath)))
874+
875+
return nil
876+
})
877+
if walkErr != nil {
878+
return errors.Wrap(walkErr, "pruning vendored talm library")
879+
}
880+
881+
// Drop directories the prune emptied, deepest-first (reverse
882+
// lexicographic order puts "a/b" before "a"). Remove refuses
883+
// non-empty directories, which is exactly the keep signal — failures
884+
// are the expected outcome for live dirs, so they are not errors.
885+
slices.Sort(seenDirs)
886+
slices.Reverse(seenDirs)
887+
888+
for _, dir := range seenDirs {
889+
if err := root.Remove(dir); err == nil {
890+
fmt.Fprintf(os.Stderr, "%s %s\n", reportVerbRemoved, filepath.Join("charts", "talm", filepath.FromSlash(dir)))
891+
}
892+
}
893+
894+
return nil
895+
}
896+
820897
// readChartYamlPreset reads Chart.yaml and determines the preset name from dependencies.
821898
func readChartYamlPreset() (string, error) {
822899
chartYamlPath := filepath.Join(Config.RootDir, chartYamlName)
@@ -1402,6 +1479,15 @@ func updateTalmLibraryChart() error {
14021479
}
14031480
}
14041481

1482+
// Prune files the embedded library no longer ships (and strays like
1483+
// .DS_Store or editor backups). charts/talm/ is talm-owned and never
1484+
// operator-edited, so an exact re-sync is safe — and without it the
1485+
// content-drift warning (or the strictCharts hard error) stays on
1486+
// forever while its hint keeps pointing at this very command.
1487+
if err := pruneVendoredTalmLibrary(presetFiles); err != nil {
1488+
return err
1489+
}
1490+
14051491
// Step 2: Update preset template files (with interactive confirmation)
14061492
if presetName != "" {
14071493
fmt.Fprintf(os.Stderr, "Updating preset templates...\n")

‎pkg/commands/init_test.go‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -472,6 +472,82 @@ func TestInitUpdate_UnknownInferredPreset_FailsBeforeWrites(t *testing.T) {
472472
}
473473
}
474474

475+
// TestInitUpdate_PrunesExtraneousVendoredFiles pins the re-sync promise:
476+
// after `talm init --update`, the talm-owned charts/talm/ tree matches the
477+
// embedded library exactly. Without pruning, an extraneous file (.DS_Store,
478+
// editor backup, a file a newer library dropped) survives every update and
479+
// keeps the drift warning — or the strictCharts hard error — permanently
480+
// on, while the remediation hint keeps pointing at the very command that
481+
// cannot clear it.
482+
func TestInitUpdate_PrunesExtraneousVendoredFiles(t *testing.T) {
483+
imageOrig := initCmdFlags.image
484+
presetOrig := initCmdFlags.preset
485+
forceOrig := initCmdFlags.force
486+
rootOrig := Config.RootDir
487+
versionOrig := Config.InitOptions.Version
488+
t.Cleanup(func() {
489+
initCmdFlags.image = imageOrig
490+
initCmdFlags.preset = presetOrig
491+
initCmdFlags.force = forceOrig
492+
Config.RootDir = rootOrig
493+
Config.InitOptions.Version = versionOrig
494+
})
495+
496+
initCmdFlags.image = ""
497+
initCmdFlags.preset = "generic"
498+
initCmdFlags.force = true
499+
// An empty version would render "version: " in the rewritten library
500+
// Chart.yaml, which the \S+ normalizer cannot fold to a placeholder —
501+
// masking the pruning assertion behind a bogus Chart.yaml mismatch.
502+
Config.InitOptions.Version = "0.30.0"
503+
504+
dir := writeVendoredTalmLibrary(t, "0.30.0")
505+
Config.RootDir = dir
506+
507+
// Step 2 of --update substitutes the cluster name from the existing
508+
// project Chart.yaml.
509+
chartYaml := "apiVersion: v2\nname: test\nversion: 0.1.0\n"
510+
if err := os.WriteFile(filepath.Join(dir, "Chart.yaml"), []byte(chartYaml), 0o644); err != nil {
511+
t.Fatalf("seed Chart.yaml: %v", err)
512+
}
513+
514+
stray := filepath.Join(dir, "charts", "talm", ".DS_Store")
515+
if err := os.WriteFile(stray, []byte{0x00, 0x01}, 0o644); err != nil {
516+
t.Fatalf("write extraneous file: %v", err)
517+
}
518+
519+
// A whole stray subtree — e.g. a directory a newer library release
520+
// dropped — must disappear as well, including the emptied directory.
521+
strayDir := filepath.Join(dir, "charts", "talm", "templates", "dropped")
522+
if err := os.MkdirAll(strayDir, 0o755); err != nil {
523+
t.Fatalf("mkdir stray dir: %v", err)
524+
}
525+
if err := os.WriteFile(filepath.Join(strayDir, "leftover.tpl"), []byte("{{- /* gone upstream */ -}}\n"), 0o644); err != nil {
526+
t.Fatalf("write stray subtree file: %v", err)
527+
}
528+
529+
if err := updateTalmLibraryChart(); err != nil {
530+
t.Fatalf("updateTalmLibraryChart: %v", err)
531+
}
532+
533+
if _, err := os.Stat(stray); !os.IsNotExist(err) {
534+
t.Error("extraneous charts/talm/.DS_Store survived init --update; the talm-owned tree must be re-synced exactly")
535+
}
536+
537+
if _, err := os.Stat(strayDir); !os.IsNotExist(err) {
538+
t.Error("emptied stray directory survived init --update; the talm-owned tree must match the embedded library exactly")
539+
}
540+
541+
drift, msg, err := CheckChartDrift(dir, "0.30.0")
542+
if err != nil {
543+
t.Fatalf("CheckChartDrift after update: %v", err)
544+
}
545+
546+
if drift {
547+
t.Errorf("drift not cleared by init --update: %s", msg)
548+
}
549+
}
550+
475551
// TestValidateImageRefShape_RejectsMalformed pins the shape check
476552
// that runs before any --image value reaches the preset rewrite.
477553
// Catches operator typos (::malformed, no-slash:tag, trailing

0 commit comments

Comments
 (0)