fix: address review feedback on PR #3383

- Eliminate marker duplication: remove hardcoded marker from all 4
  templates (cli.tmpl, rego.tmpl, builtins.tmpl, task.tmpl) and write
  it programmatically via fmt.Fprintln before template execution. The
  GeneratedMarker constant is now the single source of truth, passed
  as a parameter to each generator function.
- Fix premature append in cli.go: move generated-path append after
  successful commandTemplate.Execute so failed writes do not appear
  in the generated list.
- Add logging on abandoned file removal: emit a message to stderr
  after each successful os.Remove in removeAbandonedPages.
- Add test for os.ReadDir error path: verify removeAbandonedPages
  returns an error when the pages directory does not exist.

Addresses review feedback on #3383

Author: fullsend-ai-coder[bot]

internal/documentation/asciidoc/asciidoc.go

@@ -35,19 +35,19 @@ const GeneratedMarker = "// Generated by conforma CLI documentation tooling. DO
 func GenerateAsciidoc(module string) error {
 	var generated []string
 
-	cliGenerated, err := cli.GenerateCommandLineDocumentation(module)
+	cliGenerated, err := cli.GenerateCommandLineDocumentation(module, GeneratedMarker)
 	if err != nil {
 		return err
 	}
 	generated = append(generated, cliGenerated...)
 
-	regoGenerated, err := rego.GenerateRegoReference(module)
+	regoGenerated, err := rego.GenerateRegoReference(module, GeneratedMarker)
 	if err != nil {
 		return err
 	}
 	generated = append(generated, regoGenerated...)
 
-	tektonGenerated, err := tekton.GenerateTektonDocumentation(module)
+	tektonGenerated, err := tekton.GenerateTektonDocumentation(module, GeneratedMarker)
 	if err != nil {
 		return err
 	}
@@ -98,6 +98,7 @@ func removeAbandonedPages(module string, generated []string) error {
 		if err := os.Remove(path); err != nil {
 			return fmt.Errorf("removing abandoned file %q: %w", path, err)
 		}
+		fmt.Fprintf(os.Stderr, "Removed abandoned generated file: %s\n", path)
 	}
 
 	return nil

internal/documentation/asciidoc/asciidoc_test.go

@@ -117,6 +117,14 @@ func TestRemoveAbandonedPages(t *testing.T) {
 		err := removeAbandonedPages(module, []string{})
 		require.NoError(t, err)
 	})
+
+	t.Run("returns error for non-existent directory", func(t *testing.T) {
+		module := filepath.Join(t.TempDir(), "nonexistent")
+
+		err := removeAbandonedPages(module, []string{})
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "reading pages directory")
+	})
 }
 
 func TestHasGeneratedMarker(t *testing.T) {

internal/documentation/asciidoc/cli/cli.go

@@ -59,9 +59,9 @@ func init() {
 	}).Parse(cliNavTemplateText))
 }
 
-func GenerateCommandLineDocumentation(module string) ([]string, error) {
+func GenerateCommandLineDocumentation(module, marker string) ([]string, error) {
 	var generated []string
-	if err := generateCommandReference(cmd.RootCmd, module, &generated); err != nil {
+	if err := generateCommandReference(cmd.RootCmd, module, marker, &generated); err != nil {
 		return nil, err
 	}
 
@@ -72,13 +72,13 @@ func GenerateCommandLineDocumentation(module string) ([]string, error) {
 	return generated, nil
 }
 
-func generateCommandReference(cmd *cobra.Command, module string, generated *[]string) error {
+func generateCommandReference(cmd *cobra.Command, module, marker string, generated *[]string) error {
 	for _, c := range cmd.Commands() {
 		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
 			continue
 		}
 
-		if err := generateCommandReference(c, module, generated); err != nil {
+		if err := generateCommandReference(c, module, marker, generated); err != nil {
 			return fmt.Errorf("generating Asciidoc for command %q: %w", c.Name(), err)
 		}
 	}
@@ -93,9 +93,17 @@ func generateCommandReference(cmd *cobra.Command, module string, generated *[]st
 	}
 	defer f.Close()
 
+	if _, err := fmt.Fprintln(f, marker); err != nil {
+		return fmt.Errorf("writing marker to %q: %w", docpath, err)
+	}
+
+	if err := commandTemplate.Execute(f, cmd); err != nil {
+		return err
+	}
+
 	*generated = append(*generated, docpath)
 
-	return commandTemplate.Execute(f, cmd)
+	return nil
 }
 
 func generateCommandReferenceNav(root *cobra.Command, module string) error {

internal/documentation/asciidoc/cli/cli.tmpl

@@ -1,4 +1,3 @@
-// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = {{ .CommandPath }}
 
 {{ .Short }}

internal/documentation/asciidoc/rego/builtins.tmpl

@@ -1,4 +1,3 @@
-// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = ec rego functions reference documentation
 
 The EC CLI provides custom rego builtin functions in addition to the

internal/documentation/asciidoc/rego/rego.go

@@ -83,8 +83,8 @@ func init() {
 	builtins = findBuiltins()
 }
 
-func GenerateRegoReference(module string) ([]string, error) {
-	generated, err := generateRegoReference(module)
+func GenerateRegoReference(module, marker string) ([]string, error) {
+	generated, err := generateRegoReference(module, marker)
 	if err != nil {
 		return nil, err
 	}
@@ -93,7 +93,7 @@ func GenerateRegoReference(module string) ([]string, error) {
 		return nil, err
 	}
 
-	builtinsPath, err := generateRegoBuiltins(module)
+	builtinsPath, err := generateRegoBuiltins(module, marker)
 	if err != nil {
 		return nil, err
 	}
@@ -117,7 +117,7 @@ func findBuiltins() []*ast.Builtin {
 	return builtins
 }
 
-func generateRegoReference(module string) ([]string, error) {
+func generateRegoReference(module, marker string) ([]string, error) {
 	var generated []string
 	for _, b := range builtins {
 		docpath := filepath.Join(module, "pages", strings.ReplaceAll(b.Name, ".", "_")+".adoc")
@@ -126,6 +126,11 @@ func generateRegoReference(module string) ([]string, error) {
 			return nil, fmt.Errorf("creating file %q: %w", docpath, err)
 		}
 
+		if _, err := fmt.Fprintln(f, marker); err != nil {
+			f.Close()
+			return nil, fmt.Errorf("writing marker to %q: %w", docpath, err)
+		}
+
 		if err := regoTemplate.Execute(f, b); err != nil {
 			f.Close()
 			return nil, err
@@ -150,13 +155,17 @@ func generateRegoReferenceNav(module string) error {
 	return regoNavTemplate.Execute(f, builtins)
 }
 
-func generateRegoBuiltins(module string) (string, error) {
+func generateRegoBuiltins(module, marker string) (string, error) {
 	builtinsPath := filepath.Join(module, "pages", "rego_builtins.adoc")
 	f, err := os.Create(builtinsPath)
 	if err != nil {
 		return "", fmt.Errorf("creating file %q: %w", builtinsPath, err)
 	}
 	defer f.Close()
 
+	if _, err := fmt.Fprintln(f, marker); err != nil {
+		return "", fmt.Errorf("writing marker to %q: %w", builtinsPath, err)
+	}
+
 	return builtinsPath, regoBuiltinsTemplate.Execute(f, builtins)
 }

internal/documentation/asciidoc/rego/rego.tmpl

@@ -39,7 +39,6 @@
   {{- end }}{{- /* range */ -}}
 {{- end -}}{{- /* "properties" */ -}}
 
-// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = {{ .Name }}
 
 {{ .Description }}

internal/documentation/asciidoc/tekton/task.tmpl

@@ -1,4 +1,3 @@
-// Generated by conforma CLI documentation tooling. DO NOT EDIT.
 = {{ .Name}}
 
 Version: {{ index .Labels "app.kubernetes.io/version" }}

internal/documentation/asciidoc/tekton/tekton.go

@@ -73,8 +73,8 @@ func init() {
 	}
 }
 
-func GenerateTektonDocumentation(module string) ([]string, error) {
-	generated, err := generateTektonReference(module)
+func GenerateTektonDocumentation(module, marker string) ([]string, error) {
+	generated, err := generateTektonReference(module, marker)
 	if err != nil {
 		return nil, err
 	}
@@ -86,7 +86,7 @@ func GenerateTektonDocumentation(module string) ([]string, error) {
 	return generated, nil
 }
 
-func generateTektonReference(module string) ([]string, error) {
+func generateTektonReference(module, marker string) ([]string, error) {
 	var generated []string
 	for _, task := range tasks {
 		docpath := filepath.Join(module, "pages", task.Name+".adoc")
@@ -95,6 +95,11 @@ func generateTektonReference(module string) ([]string, error) {
 			return nil, fmt.Errorf("creating file %q: %w", docpath, err)
 		}
 
+		if _, err := fmt.Fprintln(f, marker); err != nil {
+			f.Close()
+			return nil, fmt.Errorf("writing marker to %q: %w", docpath, err)
+		}
+
 		if err := tektonTaskTemplate.Execute(f, task); err != nil {
 			f.Close()
 			return nil, err