fix(changelog): fix KaC ordering, safer delimiter, and per-module changelog paths (#263)

* fix(changelog): fix non-deterministic ordering in keepachangelog formatter

* fix(changelog): warn when header-template file is not found

A missing header-template file was silently ignored and the default
header was used. Now prints a warning to stderr so users knowtheir
custom header is not being applied.

* fix(changelog): use unit separator as git log field delimiter

Replace pipe character (|) with ASCII unit separator (\x1f) in
--pretty=format strings and SplitN calls. Prevents commit subjects
containing | from corrupting field parsing.

* fix(changelog): skip versioned file when all commits are non-conventional

When include-non-conventional is false and all commits in the range are
non-conventional, do not write a header-only .changes/v*.md file.

* feat(changelog): write per-module changelog for independent versioning

When workspace.versioning is "independent" and a module path is set,
write the unified changelog to {modulePath}/CHANGELOG.md instead of
the shared root CHANGELOG.md. Follows the same auto-follow pattern
used by tag-manager prefix interpolation.

* test(changelog): empty file, module scope, and delimiter tests

Author: indaco

internal/commands/bump/auto.go

@@ -232,7 +232,7 @@ func runSingleModuleAuto(ctx context.Context, cmd *cli.Command, cfg *config.Conf
 	}
 
 	// Execute all post-bump actions
-	if err := executePostBumpActions(registry, next, current, "auto", path, "", ""); err != nil {
+	if err := executePostBumpActions(registry, next, current, "auto", path, "", "", false); err != nil {
 		return err
 	}
 

internal/commands/bump/bump_plugins_test.go

@@ -189,7 +189,7 @@ func TestGenerateChangelogAfterBump(t *testing.T) {
 	t.Run("nil generator returns nil", func(t *testing.T) {
 
 		registry := plugins.NewPluginRegistry()
-		err := generateChangelogAfterBump(registry, version, prevVersion, "major", "", "")
+		err := generateChangelogAfterBump(registry, version, prevVersion, "major", "", "", false)
 		if err != nil {
 			t.Errorf("expected nil error, got %v", err)
 		}
@@ -691,7 +691,7 @@ func TestApplyModuleChangelogDir(t *testing.T) {
 				t.Fatalf("failed to create changelog generator: %v", err)
 			}
 
-			cleanup := applyModuleChangelog(plugin, tt.modulePath, tt.modulePath, "")
+			cleanup := applyModuleChangelog(plugin, tt.modulePath, tt.modulePath, "", false)
 
 			gotCfg := plugin.GetConfig()
 			if gotCfg.ChangesDir != tt.wantChangesDir {
@@ -728,7 +728,7 @@ func TestApplyModuleChangelogDir_NonPluginType(t *testing.T) {
 	}
 
 	// Should return noop and not panic when cg is not *ChangelogGeneratorPlugin
-	cleanup := applyModuleChangelog(mock, "cobra", "cobra", "")
+	cleanup := applyModuleChangelog(mock, "cobra", "cobra", "", false)
 
 	// Config should be unchanged because the type assertion fails
 	gotCfg := mock.GetConfig()
@@ -750,7 +750,7 @@ func TestGenerateChangelogAfterBump_NilGeneratorWithModulePath(t *testing.T) {
 	prevVersion := semver.SemVersion{Major: 1, Minor: 0, Patch: 0}
 
 	// modulePath="cobra" with nil generator should return nil without panic
-	err := generateChangelogAfterBump(registry, version, prevVersion, "major", "cobra", "cobra")
+	err := generateChangelogAfterBump(registry, version, prevVersion, "major", "cobra", "cobra", false)
 	if err != nil {
 		t.Errorf("expected nil error, got %v", err)
 	}

internal/commands/bump/common.go

@@ -82,7 +82,7 @@ func executeSingleModuleBump(
 	}
 
 	// Execute all post-bump actions
-	if err := executePostBumpActions(registry, result.NewVersion, result.PreviousVersion, params.bumpType, execCtx.Path, "", ""); err != nil {
+	if err := executePostBumpActions(registry, result.NewVersion, result.PreviousVersion, params.bumpType, execCtx.Path, "", "", false); err != nil {
 		return err
 	}
 
@@ -122,14 +122,15 @@ func executePreBumpValidations(registry *plugins.PluginRegistry, newVersion, pre
 // bumpedPath is the .version file path (used to exclude from dep-sync output).
 // moduleName identifies the module in changelog headings (empty for single-module).
 // modulePath scopes versioned output dirs and git log (empty for root or single-module).
-func executePostBumpActions(registry *plugins.PluginRegistry, newVersion, previousVersion semver.SemVersion, bumpType, bumpedPath, moduleName, modulePath string) error {
+// independentVersioning scopes the unified changelog to the module directory.
+func executePostBumpActions(registry *plugins.PluginRegistry, newVersion, previousVersion semver.SemVersion, bumpType, bumpedPath, moduleName, modulePath string, independentVersioning bool) error {
 	// Sync dependency files after updating .version
 	if err := operations.SyncDependencies(registry, newVersion, bumpedPath); err != nil {
 		return err
 	}
 
 	// Generate changelog entry
-	if err := generateChangelogAfterBump(registry, newVersion, previousVersion, bumpType, moduleName, modulePath); err != nil {
+	if err := generateChangelogAfterBump(registry, newVersion, previousVersion, bumpType, moduleName, modulePath, independentVersioning); err != nil {
 		return err
 	}
 

internal/commands/bump/helpers.go

@@ -258,7 +258,10 @@ func validateDependencyConsistency(registry *plugins.PluginRegistry, version sem
 // moduleName is used for unified mode section headers (always set in multi-module mode).
 // modulePath scopes versioned output dirs and git log (empty for root module).
 // tagPrefix scopes tag resolution (empty for root module).
-func applyModuleChangelog(cg changeloggenerator.ChangelogGenerator, moduleName, modulePath, tagPrefix string) func() {
+// independentVersioning indicates workspace.versioning == "independent"; when true
+// and modulePath is set, the unified changelog is written to {modulePath}/CHANGELOG.md
+// instead of the shared root file, and module-name heading prefixes are skipped.
+func applyModuleChangelog(cg changeloggenerator.ChangelogGenerator, moduleName, modulePath, tagPrefix string, independentVersioning bool) func() {
 	noop := func() {}
 
 	plugin, ok := cg.(*changeloggenerator.ChangelogGeneratorPlugin)
@@ -268,9 +271,15 @@ func applyModuleChangelog(cg changeloggenerator.ChangelogGenerator, moduleName,
 
 	cfg := cg.GetConfig()
 	originalChangesDir := cfg.ChangesDir
+	originalChangelogPath := cfg.ChangelogPath
 
-	// Always set module name for unified mode heading
-	if moduleName != "" {
+	// For independent versioning with a module path, scope the unified changelog
+	// to the module directory and skip the module-name heading prefix (each module
+	// has its own file so the prefix is redundant).
+	perModuleChangelog := independentVersioning && modulePath != ""
+
+	// Set module name for unified mode heading (skip when per-module changelog is used)
+	if moduleName != "" && !perModuleChangelog {
 		plugin.SetModuleName(moduleName)
 	}
 
@@ -281,8 +290,14 @@ func applyModuleChangelog(cg changeloggenerator.ChangelogGenerator, moduleName,
 		plugin.SetTagPrefix(tagPrefix)
 	}
 
+	// Scope unified changelog path for independent versioning
+	if perModuleChangelog {
+		plugin.SetChangelogPath(filepath.Join(modulePath, originalChangelogPath))
+	}
+
 	return func() {
 		plugin.SetChangesDir(originalChangesDir)
+		plugin.SetChangelogPath(originalChangelogPath)
 		plugin.SetModuleName("")
 		plugin.SetModulePath("")
 		plugin.SetTagPrefix("")
@@ -307,7 +322,8 @@ func resolveTagPrefix(registry *plugins.PluginRegistry, modulePath string) strin
 // Returns nil if changelog generator is not enabled.
 // moduleName identifies the module in unified changelog headings (empty for single-module).
 // modulePath scopes versioned output dirs and git log (empty for root or single-module).
-func generateChangelogAfterBump(registry *plugins.PluginRegistry, version, _ semver.SemVersion, bumpType, moduleName, modulePath string) error {
+// independentVersioning scopes the unified changelog to the module directory.
+func generateChangelogAfterBump(registry *plugins.PluginRegistry, version, _ semver.SemVersion, bumpType, moduleName, modulePath string, independentVersioning bool) error {
 	cg := registry.GetChangelogGenerator()
 	if cg == nil {
 		return nil
@@ -321,7 +337,7 @@ func generateChangelogAfterBump(registry *plugins.PluginRegistry, version, _ sem
 	tagPrefix := resolveTagPrefix(registry, modulePath)
 
 	// Apply per-module changelog and git scoping
-	restore := applyModuleChangelog(cg, moduleName, modulePath, tagPrefix)
+	restore := applyModuleChangelog(cg, moduleName, modulePath, tagPrefix, independentVersioning)
 	defer restore()
 
 	versionStr := "v" + version.String()

internal/commands/bump/multimodule.go

@@ -119,7 +119,8 @@ func postBumpForModule(ctx context.Context, result workspace.ExecutionResult, re
 	effectiveCfg := resolveModuleConfig(cfg, modulePath, result.Module.Dir)
 
 	// Post-bump actions (dep-sync, changelog, audit-log)
-	if err := executePostBumpActions(registry, newVer, oldVer, bumpTypeStr, result.Module.Path, moduleName, modulePath); err != nil {
+	independentVersioning := cfg != nil && cfg.Workspace != nil && cfg.Workspace.IsIndependentVersioning()
+	if err := executePostBumpActions(registry, newVer, oldVer, bumpTypeStr, result.Module.Path, moduleName, modulePath, independentVersioning); err != nil {
 		return fmt.Errorf("module %s: post-bump actions: %w", result.Module.Name, err)
 	}
 

internal/plugins/changeloggenerator/formatter_keepachangelog.go

@@ -14,6 +14,9 @@ import (
 // - Version header: ## [version] - date (no "v" prefix, brackets around version)
 // - Standard sections: Added, Changed, Deprecated, Removed, Fixed, Security
 // - No custom icons (strict section names)
+//
+// Note: Breaking changes are placed in a separate "Breaking Changes" section,
+// which is not part of the official KaC specification but is common practice.
 type KeepAChangelogFormatter struct {
 	config *Config
 }
@@ -34,7 +37,7 @@ func (f *KeepAChangelogFormatter) FormatChangelog(
 	fmt.Fprintf(&sb, "## [%s] - %s\n\n", versionNumber, date)
 
 	// Regroup commits according to Keep a Changelog sections
-	sections := f.regroupCommits(grouped)
+	sections := f.regroupCommits(grouped, sortedKeys)
 
 	// Write sections in Keep a Changelog order
 	sectionOrder := []string{"Breaking Changes", "Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"}
@@ -58,13 +61,17 @@ func (f *KeepAChangelogFormatter) FormatChangelog(
 }
 
 // regroupCommits maps conventional commit types to Keep a Changelog sections.
+// It iterates using sortedKeys to ensure deterministic ordering when commits
+// from different original groups map to the same KaC section.
 func (f *KeepAChangelogFormatter) regroupCommits(
 	grouped map[string][]*GroupedCommit,
+	sortedKeys []string,
 ) map[string][]*GroupedCommit {
 	result := make(map[string][]*GroupedCommit)
 
-	// Iterate through all grouped commits and remap them
-	for _, commits := range grouped {
+	// Iterate in stable order using sortedKeys instead of ranging the map
+	for _, key := range sortedKeys {
+		commits := grouped[key]
 		for _, commit := range commits {
 			section := f.mapTypeToSection(commit)
 			if section != "" {

internal/plugins/changeloggenerator/formatter_test.go

@@ -717,3 +717,58 @@ func TestGroupedFormatter_MultipleBreakingChanges(t *testing.T) {
 		t.Error("empty Fixes section should not appear")
 	}
 }
+
+func TestKeepAChangelogFormatter_DeterministicOrdering(t *testing.T) {
+
+	cfg := DefaultConfig()
+	formatter := &KeepAChangelogFormatter{config: cfg}
+
+	tests := []struct {
+		name       string
+		grouped    map[string][]*GroupedCommit
+		sortedKeys []string
+	}{
+		{
+			name: "refactor and perf both map to Changed",
+			grouped: map[string][]*GroupedCommit{
+				"Refactors": {
+					{ParsedCommit: &ParsedCommit{Type: "refactor", Description: "clean up parser", CommitInfo: CommitInfo{ShortHash: "aaa"}}, GroupLabel: "Refactors", GroupOrder: 2},
+				},
+				"Performance": {
+					{ParsedCommit: &ParsedCommit{Type: "perf", Description: "optimize query", CommitInfo: CommitInfo{ShortHash: "bbb"}}, GroupLabel: "Performance", GroupOrder: 4},
+				},
+				"Enhancements": {
+					{ParsedCommit: &ParsedCommit{Type: "feat", Description: "add feature", CommitInfo: CommitInfo{ShortHash: "ccc"}}, GroupLabel: "Enhancements", GroupOrder: 0},
+				},
+			},
+			sortedKeys: []string{"Enhancements", "Refactors", "Performance"},
+		},
+		{
+			name: "style and refactor both map to Changed",
+			grouped: map[string][]*GroupedCommit{
+				"Styling": {
+					{ParsedCommit: &ParsedCommit{Type: "style", Description: "format code", CommitInfo: CommitInfo{ShortHash: "ddd"}}, GroupLabel: "Styling", GroupOrder: 5},
+				},
+				"Refactors": {
+					{ParsedCommit: &ParsedCommit{Type: "refactor", Description: "rename var", CommitInfo: CommitInfo{ShortHash: "eee"}}, GroupLabel: "Refactors", GroupOrder: 2},
+				},
+			},
+			sortedKeys: []string{"Refactors", "Styling"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+
+			var first string
+			for i := range 20 {
+				result := formatter.FormatChangelog("v1.0.0", "", tt.grouped, tt.sortedKeys, nil)
+				if i == 0 {
+					first = result
+				} else if result != first {
+					t.Fatalf("non-deterministic output on iteration %d:\nfirst:\n%s\ngot:\n%s", i, first, result)
+				}
+			}
+		})
+	}
+}

internal/plugins/changeloggenerator/generator.go

@@ -12,6 +12,7 @@ import (
 	"text/template"
 
 	"github.com/indaco/sley/internal/core"
+	"github.com/indaco/sley/internal/printer"
 	"github.com/indaco/sley/internal/semver"
 )
 
@@ -114,6 +115,7 @@ func getProviderFromHost(host string) string {
 type GenerateResult struct {
 	Content                string
 	SkippedNonConventional []*ParsedCommit
+	HasEntries             bool // true if at least one commit group was populated
 }
 
 // GenerateVersionChangelog generates the changelog content for a version.
@@ -176,6 +178,7 @@ func (g *Generator) GenerateVersionChangelogWithResult(version, previousVersion
 	return GenerateResult{
 		Content:                sb.String(),
 		SkippedNonConventional: groupResult.SkippedNonConventional,
+		HasEntries:             len(grouped) > 0,
 	}
 }
 
@@ -411,7 +414,10 @@ func (g *Generator) WriteUnifiedChangelog(newContent string) error {
 func (g *Generator) getDefaultHeader() string {
 	// Try to read custom header template
 	if g.config.HeaderTemplate != "" {
-		if data, err := os.ReadFile(g.config.HeaderTemplate); err == nil {
+		data, err := os.ReadFile(g.config.HeaderTemplate)
+		if err != nil {
+			printer.PrintWarning(fmt.Sprintf("Warning: header-template %q not found, using default header", g.config.HeaderTemplate))
+		} else {
 			return strings.TrimSpace(string(data))
 		}
 	}

internal/plugins/changeloggenerator/generator_file_test.go

@@ -557,6 +557,45 @@ func TestGetDefaultHeader_CustomTemplate(t *testing.T) {
 	}
 }
 
+func TestGetDefaultHeader_MissingTemplateFile(t *testing.T) {
+
+	tests := []struct {
+		name           string
+		headerTemplate string
+	}{
+		{
+			name:           "non-existent path",
+			headerTemplate: "/tmp/nonexistent/header-template-xyz.md",
+		},
+		{
+			name:           "empty string",
+			headerTemplate: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+
+			cfg := DefaultConfig()
+			cfg.HeaderTemplate = tt.headerTemplate
+			g, err := NewGenerator(cfg, NewGitOps())
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+
+			header := g.getDefaultHeader()
+
+			// Should fall back to default header
+			if !strings.Contains(header, "Changelog") {
+				t.Error("expected default header containing 'Changelog'")
+			}
+			if !strings.Contains(header, "Semantic Versioning") {
+				t.Error("expected default header containing 'Semantic Versioning'")
+			}
+		})
+	}
+}
+
 func TestInsertAfterHeader(t *testing.T) {
 
 	cfg := DefaultConfig()

internal/plugins/changeloggenerator/git.go

@@ -10,6 +10,11 @@ import (
 	"github.com/indaco/sley/internal/git"
 )
 
+// fieldSep is the ASCII unit separator used as a delimiter in git log format strings.
+// This character cannot appear in commit messages, avoiding parsing corruption
+// that would occur with common characters like pipe (|).
+const fieldSep = "\x1f"
+
 // Pre-compiled regexes for URL parsing (compiled once at package init).
 var (
 	// Remote URL formats
@@ -110,8 +115,7 @@ func (g *GitOps) getCommitsWithMeta(since, until string) ([]CommitInfo, error) {
 	}
 
 	revRange := since + ".." + until
-	// Use a delimiter that's unlikely to appear in commit messages
-	format := "%H|%h|%s|%an|%ae"
+	format := "%H" + fieldSep + "%h" + fieldSep + "%s" + fieldSep + "%an" + fieldSep + "%ae"
 	args := []string{"log", "--pretty=format:" + format, revRange}
 	// Scope to module path if set (only commits touching this directory)
 	if g.ModulePath != "" {
@@ -138,7 +142,7 @@ func (g *GitOps) getCommitsWithMeta(since, until string) ([]CommitInfo, error) {
 
 	commits := make([]CommitInfo, 0, len(lines))
 	for _, line := range lines {
-		parts := strings.SplitN(line, "|", 5)
+		parts := strings.SplitN(line, fieldSep, 5)
 		if len(parts) < 5 {
 			continue // Skip malformed lines
 		}
@@ -339,7 +343,7 @@ func (g *GitOps) getHistoricalContributors(beforeRef string) (map[string]struct{
 
 	// git log --format="%ae|%an" beforeRef
 	// Returns all author emails and names from the beginning of history up to beforeRef
-	cmd := g.ExecCommandFn("git", "log", "--format=%ae|%an", beforeRef)
+	cmd := g.ExecCommandFn("git", "log", "--format=%ae"+fieldSep+"%an", beforeRef)
 	var stderr bytes.Buffer
 	cmd.Stderr = &stderr
 
@@ -359,7 +363,7 @@ func (g *GitOps) getHistoricalContributors(beforeRef string) (map[string]struct{
 		if line == "" {
 			continue
 		}
-		parts := strings.SplitN(line, "|", 2)
+		parts := strings.SplitN(line, fieldSep, 2)
 		if len(parts) < 2 {
 			continue
 		}