diff --git a/agent-skills/skills/atmos-hooks/SKILL.md b/agent-skills/skills/atmos-hooks/SKILL.md index b508e712a4d..234b7a86919 100644 --- a/agent-skills/skills/atmos-hooks/SKILL.md +++ b/agent-skills/skills/atmos-hooks/SKILL.md @@ -1,6 +1,6 @@ --- name: atmos-hooks -description: "Atmos hooks: lifecycle events, hook kinds, command/store/git/security hooks, step/steps hooks, when: conditions, scoping and overrides, toolchain integration, --skip-hooks, and Atmos Pro/local output" +description: "Atmos hooks: lifecycle events, hook kinds, command/store/git/security hooks, step/steps hooks, when: conditions, scoping and overrides, toolchain integration, --skip-hooks, docs generate hooks, and Atmos Pro/local output" metadata: copyright: Copyright Cloud Posse, LLC 2026 version: "1.0.0" @@ -10,7 +10,8 @@ metadata: # Atmos Hooks Use this skill for lifecycle hooks that run before or after component operations, -or for generation hooks declared in a scaffold template. +for generation hooks declared in a scaffold template, or for repo-level hooks declared under +`docs.generate` in `atmos.yaml`. Hooks can run scanners, policy checks, store writes, Git actions, custom commands, or other toolchain-aware automation around Terraform, Helm, Kubernetes, and other component commands. @@ -77,6 +78,9 @@ Scaffold templates use the separate `before.scaffold.generate` and `after.scaffold.generate` events. They reuse the condition vocabulary but can run only `kind: step` and `kind: steps`; do not configure stack-only kinds in `spec.hooks`. +Documentation generation uses `before.docs.generate` and `after.docs.generate`; see +[Repo-Level Hooks: docs generate](#repo-level-hooks-docs-generate). + Multi-component DAG runs (e.g. `--affected`, `--query`, or workflows that fan out across several components) also fire aggregate events once for the whole run, in addition to the per-component events fired for each individual component: `after.terraform.plan.aggregate`, @@ -210,14 +214,62 @@ to opt back into running the hook in the directory Atmos was launched from. This against the directory Atmos was launched from, so it keeps the ambient cwd unless `working_directory:` is set explicitly. +## Repo-Level Hooks: docs generate + +`atmos docs generate ` has no stack or component, so its hooks are declared in `atmos.yaml` +as a **map** of named hooks (not a list) under `docs.generate..hooks`. They use the same +kinds and fields as component hooks (`kind: command`/`step`/`steps`, `type`, `events`, `when`, +`on_failure`, `retry`, `with`, `env`). Hooks belong to one generator: hooks under `readme` do not +run for another type. + +```yaml +docs: + generate: + readme: + input: ["./README.yaml"] + template: "./README.md.gotmpl" + output: "./README.md" + hooks: + publish-wiki: + kind: step + type: http + events: [after.docs.generate] + when: success + on_failure: fail + with: + url: "https://wiki.example.com/rest/api/content/123456" + method: PUT + headers: + Authorization: "Bearer {{ .env.WIKI_TOKEN }}" + expect: + status: [200] +``` + +- Publishing to a wiki or portal is a generic `http` step, or a `kind: command` hook that reads + `ATMOS_DOCS_OUTPUT_PATH`. Atmos has no wiki-specific integration. +- `events:` omitted means the hook fires on both events. Hooks run in name order, in the process working directory where `atmos docs generate` starts (or the `--chdir` target), not `base-dir`. +- A `before.docs.generate` hook with `on_failure: fail`, or a policy denial, aborts before any file + is written. With the default `on_failure: warn`, or with `ignore`, generation continues, so set + `on_failure: fail` on any hook that must block generation. `after.docs.generate` hooks run on + success and on failure, filtered by `when:` (default is success only; use `failure` or `always` + to react to failures). A failing after-hook fails the command only with `on_failure: fail`. +- Hook context: env vars `ATMOS_DOCS_TYPE`, `ATMOS_DOCS_OUTPUT_PATH`, `ATMOS_DOCS_BASE_DIR`, and + template values `{{ .docs.type }}`, `{{ .docs.output_path }}`, `{{ .docs.base_dir }}`. There is + no infrastructure component or stack: the stack is empty, and `ATMOS_COMPONENT` holds the + generator name (for example `readme`). +- `atmos docs generate --skip-hooks` skips all hooks, `--skip-hooks=name1,name2` skips named + hooks, and `ATMOS_SKIP_HOOKS` is honored. +- Governing policies with `on: operation` and `action: hooks` also apply; see + [atmos-policy](../atmos-policy/SKILL.md). + ## Operational Guidance - Use hooks for repeatable lifecycle behavior, not one-off local scripts. - Scope hooks as narrowly as possible: component hooks for component-specific behavior, shared mixins/defaults for organization-wide checks. - Use `--skip-hooks` to bypass all hooks for a diagnostic run, or `--skip-hooks=name1,name2` to skip - specific hooks by name. This flag is registered on the `terraform` command only today; there is no - helmfile or packer equivalent yet. + specific hooks by name. This flag is registered on the `terraform` and `docs generate` commands + today; there is no helmfile or packer equivalent yet. `ATMOS_SKIP_HOOKS` sets it from the environment. - Treat hook output as part of CI evidence. When Atmos Pro is connected and the hook kind supports upload, prefer structured upload; otherwise rely on local/CI summaries. - Keep destructive hooks opt-in and visible in stack config. diff --git a/agent-skills/skills/atmos-policy/SKILL.md b/agent-skills/skills/atmos-policy/SKILL.md index 337b57b0a94..5f824a6bf57 100644 --- a/agent-skills/skills/atmos-policy/SKILL.md +++ b/agent-skills/skills/atmos-policy/SKILL.md @@ -31,8 +31,11 @@ Distinguish input kind, component type, and CI provider: successful plan, including no-change plans, and again before applying the evaluated private copy. Implicit apply/deploy and direct destroy are rejected when plan policies are enabled. - `operation`: lifecycle event, component type/name, stack, command, status, exit code, dry-run. - Current integration uses existing Terraform, Helmfile, Helm, and Kubernetes hooks. Do not claim - enforcement for Packer, Ansible, containers, emulators, or custom components yet. + Current integration uses existing Terraform, Helmfile, Helm, and Kubernetes hooks, plus + `atmos docs generate` (`before.docs.generate`/`after.docs.generate`): `component_type: docs`, + `command: generate`, `component` is the doc type (for example `readme`), and `stack` is empty. + `action: hooks` rules dispatch hooks there too. Do not claim enforcement for Packer, Ansible, + containers, emulators, or custom components yet. - `plugin` (`on: plugin`): native plugin registries, packages, and local builds (`origin`, `path`, `profiles`, `operation`) checked before install, activation, test, publish, and sign. See `atmos-plugins` for inputs and recipes. - GitHub Actions context: `ci.provider == 'github-actions'`, `ci.schema == 'github-actions/v1'`. diff --git a/agent-skills/skills/atmos-settings/SKILL.md b/agent-skills/skills/atmos-settings/SKILL.md index 4fd7f0e4208..b6905615ecc 100644 --- a/agent-skills/skills/atmos-settings/SKILL.md +++ b/agent-skills/skills/atmos-settings/SKILL.md @@ -19,7 +19,7 @@ Use this skill for global `atmos.yaml` options that are not owned by a narrower | `logs` | Log level, log file path, log color, debug output behavior | | `errors` | Error output formatting and error reporting options | | `env` | Environment variables applied to Atmos operations | -| `docs` | Documentation generation defaults | +| `docs` | Documentation generation defaults, including `docs.generate..hooks` (`before.docs.generate`/`after.docs.generate`; see `atmos-hooks`) | | `metadata` | Project-level metadata such as name, tags, and version | | `version` | Minimum or maximum Atmos version constraints | diff --git a/cmd/command_discovery.go b/cmd/command_discovery.go index 8a2df0aa5b9..179518060b5 100644 --- a/cmd/command_discovery.go +++ b/cmd/command_discovery.go @@ -18,6 +18,7 @@ import ( "github.com/cloudposse/atmos/cmd/internal" errUtils "github.com/cloudposse/atmos/errors" tuiutils "github.com/cloudposse/atmos/internal/tui/utils" + "github.com/cloudposse/atmos/pkg/browser" iolib "github.com/cloudposse/atmos/pkg/io" "github.com/cloudposse/atmos/pkg/perf" "github.com/cloudposse/atmos/pkg/reexec" @@ -28,8 +29,9 @@ import ( ) // Dependencies are replaceable so discovery tests never open a browser, prompt, -// or fetch an example. The browser helper is shared with the existing docs command. +// or fetch an example. var ( + openDocsURL = func(url string) error { return browser.New().Open(url) } discoverySelect = selectCommandExample discoveryConfirm = confirmCommandExample discoveryInit = initializeCommandExample diff --git a/cmd/docs.go b/cmd/docs/docs.go similarity index 52% rename from cmd/docs.go rename to cmd/docs/docs.go index 64bcd9d90f3..f8472dcaa91 100644 --- a/cmd/docs.go +++ b/cmd/docs/docs.go @@ -1,9 +1,10 @@ -package cmd +package docs import ( "fmt" "os" "path/filepath" + "strings" "github.com/charmbracelet/glamour" "github.com/charmbracelet/lipgloss" @@ -12,9 +13,13 @@ import ( "golang.org/x/term" "github.com/cloudposse/atmos/cmd/internal" + "github.com/cloudposse/atmos/internal/exec" termUtils "github.com/cloudposse/atmos/internal/tui/templates/term" "github.com/cloudposse/atmos/pkg/browser" cfg "github.com/cloudposse/atmos/pkg/config" + "github.com/cloudposse/atmos/pkg/flags" + "github.com/cloudposse/atmos/pkg/flags/compat" + l "github.com/cloudposse/atmos/pkg/list" log "github.com/cloudposse/atmos/pkg/logger" "github.com/cloudposse/atmos/pkg/schema" "github.com/cloudposse/atmos/pkg/ui" @@ -22,7 +27,12 @@ import ( u "github.com/cloudposse/atmos/pkg/utils" ) -const atmosDocsURL = "https://atmos.tools" +const ( + atmosDocsURL = "https://atmos.tools" + + // Prefix of a long flag in shell completion input. + longFlagPrefix = "--" +) var openDocsURL = func(url string) error { return browser.New().Open(url) @@ -36,7 +46,7 @@ var docsCmd = &cobra.Command{ Example: "atmos docs vpc", Args: cobra.MaximumNArgs(1), FParseErrWhitelist: struct{ UnknownFlags bool }{UnknownFlags: false}, - ValidArgsFunction: ComponentsArgCompletion, + ValidArgsFunction: componentsArgCompletion, RunE: func(cmd *cobra.Command, args []string) error { if len(args) == 1 { info := schema.ConfigAndStacksInfo{ @@ -145,10 +155,112 @@ var docsCmd = &cobra.Command{ }, } +// componentsArgCompletion provides shell completion for the component positional argument. +// It mirrors the root command's component completion: directory completion for path-like input, +// otherwise component names from the stack configurations. +func componentsArgCompletion(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) { + if len(args) == 0 { + // Enable directory completion for paths (platform-specific separator and forward slash). + if toComplete == "." || strings.Contains(toComplete, string(filepath.Separator)) || strings.Contains(toComplete, "/") { + log.Trace("Enabling directory completion for path input", "toComplete", toComplete) + return nil, cobra.ShellCompDirectiveFilterDirs + } + + // Otherwise, suggest component names from stack configurations. + output, err := listComponents(cmd) + if err != nil { + return nil, cobra.ShellCompDirectiveNoFileComp + } + return output, cobra.ShellCompDirectiveNoFileComp + } + + flagName := args[len(args)-1] + if strings.HasPrefix(flagName, longFlagPrefix) { + flagName = strings.ReplaceAll(flagName, longFlagPrefix, "") + } + if strings.HasPrefix(toComplete, longFlagPrefix) { + flagName = strings.ReplaceAll(toComplete, longFlagPrefix, "") + } + flagName = strings.ReplaceAll(flagName, "=", "") + if option, ok := cmd.GetFlagCompletionFunc(flagName); ok { + return option(cmd, args, toComplete) + } + return nil, cobra.ShellCompDirectiveNoFileComp +} + +// listComponents returns the component names found in the stack configurations, +// filtered by the --stack flag when the command defines one. +func listComponents(cmd *cobra.Command) ([]string, error) { + stackFlag, err := cmd.Flags().GetString("stack") + if err != nil { + stackFlag = "" + } + + atmosConfig, err := cfg.InitCliConfig(schema.ConfigAndStacksInfo{}, true) + if err != nil { + return nil, fmt.Errorf("error initializing CLI config: %w", err) + } + + stacksMap, err := exec.ExecuteDescribeStacks(&atmosConfig, "", nil, nil, nil, false, false, false, false, nil, nil) + if err != nil { + return nil, fmt.Errorf("error describing stacks: %w", err) + } + + return l.FilterAndListComponents(stackFlag, stacksMap) +} + func init() { - RootCmd.AddCommand(docsCmd) - internal.RegisterCommandMetadata( - docsCmd, + // Register this command with the registry. + // This happens during package initialization via blank import in cmd/root.go. + internal.Register( + &DocsCommandProvider{}, internal.WithDocumentationURL("https://atmos.tools/cli/commands/docs/usage"), ) } + +// DocsCommandProvider implements the CommandProvider interface. +type DocsCommandProvider struct{} + +// GetCommand returns the docs command. +func (d *DocsCommandProvider) GetCommand() *cobra.Command { + return docsCmd +} + +// GetName returns the command name. +func (d *DocsCommandProvider) GetName() string { + return "docs" +} + +// GetGroup returns the command group for help organization. +func (d *DocsCommandProvider) GetGroup() string { + return "Configuration Management" +} + +// GetFlagsBuilder returns the flags builder for this command. +// The docs command has no flags of its own; docs generate registers its own via its parser. +func (d *DocsCommandProvider) GetFlagsBuilder() flags.Builder { + return nil +} + +// GetPositionalArgsBuilder returns the positional args builder for this command. +// The docs command validates its optional component argument via cobra.MaximumNArgs(1). +func (d *DocsCommandProvider) GetPositionalArgsBuilder() *flags.PositionalArgsBuilder { + return nil +} + +// GetCompatibilityFlags returns compatibility flags for this command. +// The docs command has no compatibility flags. +func (d *DocsCommandProvider) GetCompatibilityFlags() map[string]compat.CompatibilityFlag { + return nil +} + +// GetAliases returns command aliases. +// The docs command has no aliases. +func (d *DocsCommandProvider) GetAliases() []internal.CommandAlias { + return nil +} + +// IsExperimental returns whether this command is experimental. +func (d *DocsCommandProvider) IsExperimental() bool { + return false +} diff --git a/cmd/docs/docs_generate.go b/cmd/docs/docs_generate.go new file mode 100644 index 00000000000..02211adeb27 --- /dev/null +++ b/cmd/docs/docs_generate.go @@ -0,0 +1,75 @@ +package docs + +import ( + "github.com/spf13/cobra" + "github.com/spf13/viper" + + "github.com/cloudposse/atmos/cmd/internal" + pkgdocs "github.com/cloudposse/atmos/pkg/docs" + "github.com/cloudposse/atmos/pkg/flags" + log "github.com/cloudposse/atmos/pkg/logger" +) + +// skipHooksFlag is the flag (and Viper key suffix) that skips lifecycle hooks for one run. +const ( + skipHooksFlag = "skip-hooks" + skipHooksViperPrefix = "docs_generate_flags" +) + +// docsGenerateParser registers and binds the docs generate flags. +var docsGenerateParser = flags.NewStandardParser( + // Bare --skip-hooks skips all hooks; --skip-hooks=a,b skips the named hooks. + flags.WithStringFlag(skipHooksFlag, "", "", "Skip lifecycle hooks for this invocation. Use --skip-hooks (no value) to skip all, or --skip-hooks=name1,name2 to skip specific hooks by name"), + flags.WithNoOptDefVal(skipHooksFlag, "*"), + flags.WithEnvVars(skipHooksFlag, "ATMOS_SKIP_HOOKS"), + // The prefix avoids colliding with the docs.generate section of atmos.yaml in Viper. + flags.WithViperPrefix(skipHooksViperPrefix), +) + +// applySkipHooksEnv resolves --skip-hooks precedence (flag, then ATMOS_SKIP_HOOKS) and records the +// result on the flag, which is where the hook engine reads it. +func applySkipHooksEnv(cmd *cobra.Command) error { + v := viper.GetViper() + if err := docsGenerateParser.BindFlagsToViper(cmd, v); err != nil { + return err + } + flag := cmd.Flags().Lookup(skipHooksFlag) + if flag == nil || flag.Changed { + return nil + } + if value := v.GetString(skipHooksViperPrefix + "." + skipHooksFlag); value != "" { + return cmd.Flags().Set(skipHooksFlag, value) + } + return nil +} + +// docsGenerateCmd is the subcommand under docs that groups generation operations. +var docsGenerateCmd = &cobra.Command{ + Use: "generate", + Short: "Generate documentation artifacts", + Long: `Generate documentation by merging YAML data sources and applying templates. +Supports native terraform-docs injection.`, + Example: `Generate the README.md in the current directory: + atmos docs generate readme`, + Args: cobra.ExactArgs(1), + ValidArgs: []string{"readme"}, + RunE: func(cmd *cobra.Command, args []string) error { + // cobra.ExactArgs(1) already validates argument count. + if err := applySkipHooksEnv(cmd); err != nil { + return err + } + return pkgdocs.ExecuteGenerate(cmd, args) + }, +} + +func init() { + docsGenerateParser.RegisterFlags(docsGenerateCmd) + if err := docsGenerateParser.BindToViper(viper.GetViper()); err != nil { + log.Debug("Failed to bind docs generate flags to Viper", "error", err) + } + docsCmd.AddCommand(docsGenerateCmd) + internal.RegisterCommandMetadata( + docsGenerateCmd, + internal.WithDocumentationURL("https://atmos.tools/cli/commands/docs/generate"), + ) +} diff --git a/cmd/docs/docs_generate_test.go b/cmd/docs/docs_generate_test.go new file mode 100644 index 00000000000..e95f1c162aa --- /dev/null +++ b/cmd/docs/docs_generate_test.go @@ -0,0 +1,132 @@ +package docs + +import ( + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "sync" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "go.yaml.in/yaml/v3" + + // Link the hook engine, as the full binary does, so docs generate hooks can run. + _ "github.com/cloudposse/atmos/pkg/hooks" +) + +// ensureGlobalFlags defines the persistent root flags that ExecuteGenerate reads. In production +// the root command supplies them; this package has no access to RootCmd, so tests stand them in. +func ensureGlobalFlags(t *testing.T) { + t.Helper() + fs := docsGenerateCmd.Flags() + if fs.Lookup("base-path") != nil { + return + } + fs.String("base-path", "", "") + fs.StringSlice("config", nil, "") + fs.StringSlice("config-path", nil, "") + fs.StringSlice("profile", nil, "") +} + +func TestDocsGenerateCmd_Error(t *testing.T) { + err := docsGenerateCmd.RunE(docsGenerateCmd, []string{}) + assert.Error(t, err, "docs generate command should return an error when called with no parameters") +} + +// TestDocsGenerateCmd_AbsoluteBase verifies the command preserves an absolute module directory. +func TestDocsGenerateCmd_AbsoluteBase(t *testing.T) { + ensureGlobalFlags(t) + workingDir, moduleDir := t.TempDir(), t.TempDir() + t.Chdir(workingDir) + t.Setenv("ATMOS_CLI_CONFIG_PATH", workingDir) + require.NoError(t, os.WriteFile(filepath.Join(moduleDir, "main.tf"), []byte(`variable "bucket" { type = string }`), 0o600)) + templatePath := filepath.Join(workingDir, "README.md.gomplate") + require.NoError(t, os.WriteFile(templatePath, []byte(`{{ with terraform }}{{ range .Inputs }}{{ .Name }}{{ end }}{{ else }}unavailable{{ end }}`), 0o600)) + outputPath := filepath.Join(workingDir, "README.md") + config := map[string]any{"docs": map[string]any{"generate": map[string]any{"absolute": map[string]any{ + "base-dir": moduleDir, "template": templatePath, "output": outputPath, "terraform": map[string]any{"enabled": true, "source": "."}, + }}}} + content, err := yaml.Marshal(config) + require.NoError(t, err) + require.NoError(t, os.WriteFile(filepath.Join(workingDir, "atmos.yaml"), content, 0o600)) + require.NoError(t, docsGenerateCmd.RunE(docsGenerateCmd, []string{"absolute"})) + actual, err := os.ReadFile(outputPath) + require.NoError(t, err) + assert.Equal(t, "bucket", string(actual)) +} + +// docsGenerateHookFixture writes an atmos.yaml with a docs hook per name that POSTs to server, +// and returns the output path. +func docsGenerateHookFixture(t *testing.T, serverURL string, names ...string) string { + t.Helper() + workingDir := t.TempDir() + t.Chdir(workingDir) + t.Setenv("ATMOS_CLI_CONFIG_PATH", workingDir) + t.Setenv("ATMOS_BASE_PATH", workingDir) + outputPath := filepath.Join(workingDir, "README.md") + hooks := map[string]any{} + for _, name := range names { + hooks[name] = map[string]any{ + "kind": "step", "type": "http", "events": []any{"after.docs.generate"}, + "with": map[string]any{"url": serverURL + "/" + name, "method": "POST"}, + } + } + config := map[string]any{"base_path": workingDir, "docs": map[string]any{"generate": map[string]any{"readme": map[string]any{ + "base-dir": workingDir, "output": outputPath, "hooks": hooks, + }}}} + content, err := yaml.Marshal(config) + require.NoError(t, err) + require.NoError(t, os.WriteFile(filepath.Join(workingDir, "atmos.yaml"), content, 0o600)) + return outputPath +} + +func TestDocsGenerateCmd_SkipHooks(t *testing.T) { + tests := []struct { + name string + args []string + env string + want []string + }{ + {name: "no flag runs every hook", want: []string{"/keep", "/skip"}}, + {name: "bare flag skips all", args: []string{"--skip-hooks"}, want: nil}, + {name: "named flag skips only that hook", args: []string{"--skip-hooks=skip"}, want: []string{"/keep"}}, + {name: "env var skips named hook", env: "skip", want: []string{"/keep"}}, + {name: "unrelated name skips nothing", args: []string{"--skip-hooks=other"}, want: []string{"/keep", "/skip"}}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + ensureGlobalFlags(t) + var mu sync.Mutex + var seen []string + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + mu.Lock() + seen = append(seen, r.URL.Path) + mu.Unlock() + w.WriteHeader(http.StatusNoContent) + })) + t.Cleanup(server.Close) + outputPath := docsGenerateHookFixture(t, server.URL, "keep", "skip") + t.Setenv("ATMOS_SKIP_HOOKS", tt.env) + t.Cleanup(func() { + _ = docsGenerateCmd.Flags().Set(skipHooksFlag, "") + docsGenerateCmd.Flags().Lookup(skipHooksFlag).Changed = false + }) + require.NoError(t, docsGenerateCmd.ParseFlags(tt.args)) + + require.NoError(t, docsGenerateCmd.RunE(docsGenerateCmd, []string{"readme"})) + + assert.FileExists(t, outputPath, "skipping hooks never skips generation") + mu.Lock() + defer mu.Unlock() + assert.ElementsMatch(t, tt.want, seen) + }) + } +} + +func TestDocsGenerateCmd_SkipHooksFlagRegistered(t *testing.T) { + flag := docsGenerateCmd.Flags().Lookup(skipHooksFlag) + require.NotNil(t, flag) + assert.Equal(t, "*", flag.NoOptDefVal) +} diff --git a/cmd/docs/docs_test.go b/cmd/docs/docs_test.go new file mode 100644 index 00000000000..8e50d71badc --- /dev/null +++ b/cmd/docs/docs_test.go @@ -0,0 +1,56 @@ +package docs + +import ( + "errors" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestDocsCmdOpensDefaultDocsURL(t *testing.T) { + origOpen := openDocsURL + t.Cleanup(func() { openDocsURL = origOpen }) + + var openedURL string + openDocsURL = func(url string) error { + openedURL = url + return nil + } + + require.NoError(t, docsCmd.RunE(docsCmd, nil)) + assert.Equal(t, atmosDocsURL, openedURL) +} + +func TestDocsCmdReturnsDefaultDocsOpenError(t *testing.T) { + origOpen := openDocsURL + t.Cleanup(func() { openDocsURL = origOpen }) + + openErr := errors.New("browser unavailable") + openDocsURL = func(string) error { + return openErr + } + + err := docsCmd.RunE(docsCmd, nil) + require.ErrorIs(t, err, openErr) + assert.ErrorContains(t, err, "open Atmos docs") +} + +func TestDocsCommandProvider(t *testing.T) { + provider := &DocsCommandProvider{} + + cmd := provider.GetCommand() + require.NotNil(t, cmd) + assert.Equal(t, "docs", cmd.Use) + assert.Equal(t, "docs", provider.GetName()) + assert.Equal(t, "Configuration Management", provider.GetGroup()) + assert.Nil(t, provider.GetFlagsBuilder()) + assert.Nil(t, provider.GetPositionalArgsBuilder()) + assert.Nil(t, provider.GetCompatibilityFlags()) + assert.Nil(t, provider.GetAliases()) + assert.False(t, provider.IsExperimental()) + + sub, _, err := cmd.Find([]string{"generate"}) + require.NoError(t, err) + assert.Equal(t, "generate", sub.Name()) +} diff --git a/cmd/docs_generate.go b/cmd/docs_generate.go deleted file mode 100644 index f47fb4e9d9f..00000000000 --- a/cmd/docs_generate.go +++ /dev/null @@ -1,32 +0,0 @@ -package cmd - -import ( - "github.com/spf13/cobra" - - "github.com/cloudposse/atmos/cmd/internal" - e "github.com/cloudposse/atmos/internal/exec" -) - -// docsGenerateCmd is the subcommand under docs that groups generation operations. -var docsGenerateCmd = &cobra.Command{ - Use: "generate", - Short: "Generate documentation artifacts", - Long: `Generate documentation by merging YAML data sources and applying templates. -Supports native terraform-docs injection.`, - Example: `Generate the README.md in the current directory: - atmos docs generate readme`, - Args: cobra.ExactArgs(1), - ValidArgs: []string{"readme"}, - RunE: func(cmd *cobra.Command, args []string) error { - // cobra.ExactArgs(1) already validates argument count - return e.ExecuteDocsGenerateCmd(cmd, args) - }, -} - -func init() { - docsCmd.AddCommand(docsGenerateCmd) - internal.RegisterCommandMetadata( - docsGenerateCmd, - internal.WithDocumentationURL("https://atmos.tools/cli/commands/docs/generate"), - ) -} diff --git a/cmd/docs_generate_test.go b/cmd/docs_generate_test.go deleted file mode 100644 index 75e62d023dd..00000000000 --- a/cmd/docs_generate_test.go +++ /dev/null @@ -1,38 +0,0 @@ -package cmd - -import ( - "os" - "path/filepath" - "testing" - - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" - "go.yaml.in/yaml/v3" -) - -func TestDocsGenerateCmd_Error(t *testing.T) { - err := docsGenerateCmd.RunE(docsGenerateCmd, []string{}) - assert.Error(t, err, "docs generate command should return an error when called with no parameters") -} - -// TestDocsGenerateCmd_AbsoluteBase verifies the command preserves an absolute module directory. -func TestDocsGenerateCmd_AbsoluteBase(t *testing.T) { - _ = NewTestKit(t) - workingDir, moduleDir := t.TempDir(), t.TempDir() - t.Chdir(workingDir) - t.Setenv("ATMOS_CLI_CONFIG_PATH", workingDir) - require.NoError(t, os.WriteFile(filepath.Join(moduleDir, "main.tf"), []byte(`variable "bucket" { type = string }`), 0o600)) - templatePath := filepath.Join(workingDir, "README.md.gomplate") - require.NoError(t, os.WriteFile(templatePath, []byte(`{{ with terraform }}{{ range .Inputs }}{{ .Name }}{{ end }}{{ else }}unavailable{{ end }}`), 0o600)) - outputPath := filepath.Join(workingDir, "README.md") - config := map[string]any{"docs": map[string]any{"generate": map[string]any{"absolute": map[string]any{ - "base-dir": moduleDir, "template": templatePath, "output": outputPath, "terraform": map[string]any{"enabled": true, "source": "."}, - }}}} - content, err := yaml.Marshal(config) - require.NoError(t, err) - require.NoError(t, os.WriteFile(filepath.Join(workingDir, "atmos.yaml"), content, 0o600)) - require.NoError(t, docsGenerateCmd.RunE(docsGenerateCmd, []string{"absolute"})) - actual, err := os.ReadFile(outputPath) - require.NoError(t, err) - assert.Equal(t, "bucket", string(actual)) -} diff --git a/cmd/docs_test.go b/cmd/docs_test.go deleted file mode 100644 index 9547a5b183a..00000000000 --- a/cmd/docs_test.go +++ /dev/null @@ -1,46 +0,0 @@ -package cmd - -import ( - "errors" - "testing" - - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" -) - -// TestDocsCmd_WithoutStacks verifies that docs command does not require stack configuration. -// This test documents that the docs command uses InitCliConfig with processStacks=false. -func TestDocsCmd_WithoutStacks(t *testing.T) { - _ = NewTestKit(t) - - // This test documents that docs command does not process stacks - // by verifying InitCliConfig is called with processStacks=false in docs.go:38 - // No runtime test needed - this is enforced by code structure. - t.Log("docs command uses InitCliConfig with processStacks=false") -} - -func TestDocsCmdOpensDefaultDocsURL(t *testing.T) { - _ = NewTestKit(t) - - var openedURL string - openDocsURL = func(url string) error { - openedURL = url - return nil - } - - require.NoError(t, docsCmd.RunE(docsCmd, nil)) - assert.Equal(t, atmosDocsURL, openedURL) -} - -func TestDocsCmdReturnsDefaultDocsOpenError(t *testing.T) { - _ = NewTestKit(t) - - openErr := errors.New("browser unavailable") - openDocsURL = func(string) error { - return openErr - } - - err := docsCmd.RunE(docsCmd, nil) - require.ErrorIs(t, err, openErr) - assert.ErrorContains(t, err, "open Atmos docs") -} diff --git a/cmd/root.go b/cmd/root.go index e5669ef8b44..6120fd8df69 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -39,6 +39,7 @@ import ( configcmd "github.com/cloudposse/atmos/cmd/config" _ "github.com/cloudposse/atmos/cmd/container" "github.com/cloudposse/atmos/cmd/devcontainer" + _ "github.com/cloudposse/atmos/cmd/docs" doctorcmd "github.com/cloudposse/atmos/cmd/doctor" _ "github.com/cloudposse/atmos/cmd/emulator" _ "github.com/cloudposse/atmos/cmd/env" diff --git a/docs/fixes/2026-11-17-docs-generate-hooks-field-test.md b/docs/fixes/2026-11-17-docs-generate-hooks-field-test.md new file mode 100644 index 00000000000..d53924814bc --- /dev/null +++ b/docs/fixes/2026-11-17-docs-generate-hooks-field-test.md @@ -0,0 +1,54 @@ +# Fix: `docs generate` hooks field-test findings + +**Date:** 2026-11-17 + +## Summary + +Hooks on `atmos docs generate` (`before.docs.generate` and `after.docs.generate`) had six defects found in +a field test: the docs environment variables never reached hook subprocesses, hooks ran in random order, +hook failures did not name the hook, a list-shaped `hooks:` produced an opaque decoder error, an invalid +step hook only warned at run time, and a few error and documentation messages were unhelpful. + +## Context + +The hook engine builds an `ExecContext` for each hook. For repo-level operations, the new +`OperationEnv` field (carrying `ATMOS_DOCS_TYPE`, `ATMOS_DOCS_OUTPUT_PATH`, `ATMOS_DOCS_BASE_DIR`) was read +when building the subprocess environment but was never assigned when the context was created. Hook +execution also iterated a Go map, so order changed between runs. The remaining findings were missing +validation and messaging around operation hooks. + +## Changes + +- Assign `OperationEnv` when building the execution context, covering user hooks, policy-selected hooks, + and the step engine (which builds its environment through the same function). +- Run, preflight and verify hooks in hook-name order. This also makes component hook order deterministic. +- Name the hook and event in failure errors (`hook "name" (kind command, event ...) failed`), keeping the + wrapped error so the hook's exit code still propagates. +- Make the missing-binary hint operation-aware: it no longer mentions Terraform, and omits the + `dependencies.tools` suggestion for repo-level operations that have no component dependencies. +- Reject hooks that are not maps with an error that names the config path + (`docs.generate..hooks`) and shows an example. +- Validate operation hooks when they are constructed, using the same checks governing policy hooks get, + so an unknown kind, unknown step type or missing required step field fails before generation. +- Add a hint to the unknown doc type error listing the configured `docs.generate` types. +- Log a warning when a docs hook declares events from another operation, since they can never fire. +- Document in the docs page and the PRD that hooks run in hook-name order and with the project root as the + working directory, not `base-dir`. + +## Validation + +- Each fix was reproduced with a failing test first (environment variables, ordering, error text and hint, + non-map hooks, construction-time validation, doc type hint), then the code was fixed. The foreign-event + warning was added with its test in the same step. +- New tests run a real command-hook subprocess through the test binary and assert the three variables + arrive for both a user hook and a policy hook. +- `go test -count=1` passed for `./pkg/hooks/...`, `./pkg/docs/...`, `./errors/...`, `./pkg/policy/...`, + `./pkg/config/schema`, `./pkg/schema`, `./cmd/terraform`, `./pkg/component/...`, and `./cmd` with + `-run Docs`. +- `atmos lint --changed` reported 0 issues. No golden snapshots changed. +- `go test` prints `[no tests to run]` for `pkg/hooks`; a test re-runs the test binary as a child process + that prints the warning. All tests still run and pass. + +## Follow-ups + +None. diff --git a/docs/prd/docs-generate-hooks.md b/docs/prd/docs-generate-hooks.md new file mode 100644 index 00000000000..6055ef9b2eb --- /dev/null +++ b/docs/prd/docs-generate-hooks.md @@ -0,0 +1,172 @@ +# PRD: Hooks, Lifecycle Events, and Policy Support for `atmos docs generate` + +**Status**: Proposed + +**Related PRDs**: [Custom Hooks](./custom-hooks.md) | [Hook step types](./hooks-step-types.md) | [Shared Policy Runtime Context](./policy-runtime-context.md) + +## Problem and scope + +Teams generate documentation with `atmos docs generate` (a README, release notes, component +reference pages) and then need that output somewhere else: a wiki, a documentation portal, an +artifact bucket, a chat announcement. Today that last step lives outside Atmos, in a shell +wrapper or a CI job that must remember to run after the generator and must know where the +output landed. + +Lifecycle hooks already solve this for component operations. Documentation generation is a +repository-level operation, not a component operation, so it has no events, no place to declare +hooks, and no way for a policy to require or forbid a follow-up action. + +This PRD defines how documentation generation joins the existing hook and policy system. It +adds no publishing feature for any specific destination. Publishing to a wiki is a generic +`http` step against that wiki's REST API, using the same step library available in workflows +and component hooks. + +## Goals + +1. Run any existing hook kind (`step`, `steps`, `command`) before and after `atmos docs generate`. +2. Declare hooks next to the generator they belong to, so each document type owns its follow-up. +3. Give hook steps the facts they need (which document, where it was written) without parsing + configuration. +4. Let governing policies select hooks for documentation generation the same way they do for + component operations. +5. Keep behavior familiar: the same fields, `when:` predicates, `on_failure` handling, and + `--skip-hooks` semantics as component hooks. + +## Non-goals + +- A built-in integration for any particular documentation destination. +- Hooks for repository-level operations other than documentation generation. Other operations + may adopt the same mechanism later; this PRD does not commit to them. +- A new hook kind. Publishing uses `kind: step` with the existing `http` step type, or + `kind: command`. +- Hooks that change what gets generated. Hooks run around generation; they do not alter the + template, inputs, or output path. + +## User-facing behavior + +### Events + +Two lifecycle events are registered: + +| Event | When it fires | +|---|---| +| `before.docs.generate` | After the generator is selected and validated, before any input is read or any file is written. | +| `after.docs.generate` | After generation finishes, with the operation's outcome (success or failure). | + +Both follow the same event-name validation and [edition](./editions.md) gating as every other +registered hook event. An unregistered event name in a hook declaration is an error. + +### Declaring hooks + +Hooks are declared under the generator they belong to, in `atmos.yaml`: + +```yaml +docs: + generate: + readme: + base-dir: . + input: + - "./README.yaml" + template: "./README.md.gotmpl" + output: "./README.md" + hooks: + publish-wiki: + kind: step + type: http + events: [after.docs.generate] + when: success + on_failure: fail + with: + url: https://wiki.example.com/rest/api/content/12345 + method: PUT + headers: + Authorization: "Bearer {{ .env.WIKI_TOKEN }}" + Content-Type: application/json + body: '{"title": "README", "body": "see attached"}' +``` + +Each entry under `hooks` has the same shape as a component hook: `kind` (`step`, `steps`, or +`command`), `events`, `when`, `on_failure`, and the kind's own fields. Hooks belong to one +generator; a hook under `readme` never runs for `release-notes`. + +A hook with no `events` list fires on both documentation events, matching component hook +behavior. + +### Ordering and failure + +1. `before.docs.generate` hooks run first. If one fails with `on_failure: fail`, or a policy denies it, + generation is aborted and no output file is written or modified. The default is + `on_failure: warn`, so generation continues unless a hook opts in to `fail`. +2. Generation runs. +3. `after.docs.generate` hooks run with the outcome of generation. Each hook's `when:` decides + whether it runs: `success` (the default), `failure`, or `always`. +4. If generation succeeded and an after-hook fails, the command fails according to that hook's + `on_failure` setting (`warn` by default; only `fail` fails the command, and `warn` and `ignore` + keep it successful). +5. If generation failed, the command reports the generation error. After-hooks selected by + `when: failure` or `when: always` still run. + +Within one event, hooks run in a deterministic order (sorted by hook name). Hooks run with the +process working directory (where `atmos docs generate` starts, or the `--chdir` target), not +`base-dir`; +`ATMOS_DOCS_BASE_DIR` and `ATMOS_DOCS_OUTPUT_PATH` locate the generator's files. + +### Context available to steps + +Hook steps receive these environment variables: + +| Variable | Value | +|---|---| +| `ATMOS_DOCS_TYPE` | The generator name, such as `readme`. | +| `ATMOS_DOCS_OUTPUT_PATH` | The resolved path of the output file. | +| `ATMOS_DOCS_BASE_DIR` | The resolved base directory of the generator. | + +The same values are available to step templates as `{{ .docs.type }}`, +`{{ .docs.output_path }}`, and `{{ .docs.base_dir }}`. After-hooks also see the operation +outcome through the existing `{{ .status }}` and `{{ .error }}` values and `ATMOS_HOOK_*` +variables. Documentation hooks have no infrastructure component and no stack: the stack is empty and +`ATMOS_COMPONENT` holds the generator name (for example `readme`). + +### Skipping hooks + +`--skip-hooks` and `ATMOS_SKIP_HOOKS` work as they do for component commands: skip all hooks +for one invocation, or name specific hooks. Hooks required by a policy cannot be skipped. + +### Policy support + +A governing policy that uses `on: operation` with `action: hooks` applies to documentation +generation. The operation input is: + +| Field | Value | +|---|---| +| `event` | `before.docs.generate` or `after.docs.generate` | +| `component_type` | `docs` | +| `command` | `generate` | +| `component` | The generator name, such as `readme` | +| `stack` | Empty; documentation generation has no stack | +| `status` | `success` or `failure`; before-events begin with `success` | + +A policy can therefore require a hook for a given generator, restrict a hook to one +generator, or deny generation outright with a policy rule on the before-event. Policy hook +selection, `required`, and `require_success` behave exactly as for component operations. + +## Success criteria + +- A `kind: step` hook with `type: http` under `docs.generate..hooks` runs after a + successful `atmos docs generate ` and can read the output path from + `ATMOS_DOCS_OUTPUT_PATH`. +- A failing `before.docs.generate` hook leaves the output file untouched. +- A `when: failure` after-hook runs when generation fails and does not run when it succeeds. +- `--skip-hooks` suppresses non-required documentation hooks and does not suppress policy-required ones. +- A policy rule on `before.docs.generate` can block generation for a named generator. +- A hook declared with an unregistered event name is rejected when configuration loads. +- The `atmos.yaml` JSON schema accepts `hooks` under each generator. + +## Documentation + +- `atmos docs generate` command page: a Hooks section with the `http` step example, the + environment variables, and the policy note. +- `docs.generate` configuration page: the `hooks` option. +- Hooks reference: the new events in the supported events table. +- Policy documentation: `docs` as a component type in the operation input. +- A changelog post and a roadmap entry. diff --git a/errors/errors.go b/errors/errors.go index cc179229494..350a9049df1 100644 --- a/errors/errors.go +++ b/errors/errors.go @@ -150,6 +150,7 @@ var ( ErrRefuseWriteThroughSymlink = errors.New("refusing to write through symbolic link") ErrNoDocsGenerateEntry = errors.New("no docs.generate entry found") ErrMissingDocType = errors.New("doc-type argument missing") + ErrDocsHooksUnavailable = errors.New("docs generate hooks are configured but the hook engine is not available") ErrUnsupportedInputType = errors.New("unsupported input type") ErrMissingStackNameTemplateAndPattern = errors.New("'stacks.name_template' (or the deprecated 'stacks.name_pattern') needs to be specified in 'atmos.yaml'") ErrStackNamePatternPartMissing = errors.New("stack name pattern references a context part that is not defined in the stack file") diff --git a/internal/exec/docs_generate.go b/internal/exec/docs_generate.go deleted file mode 100644 index 5b5011ed31e..00000000000 --- a/internal/exec/docs_generate.go +++ /dev/null @@ -1,47 +0,0 @@ -package exec - -import ( - "fmt" - - "github.com/spf13/cobra" - - errUtils "github.com/cloudposse/atmos/errors" - cfg "github.com/cloudposse/atmos/pkg/config" - "github.com/cloudposse/atmos/pkg/docs" - log "github.com/cloudposse/atmos/pkg/logger" - "github.com/cloudposse/atmos/pkg/perf" -) - -// ExecuteDocsGenerateCmd implements the 'atmos docs generate ' logic. -func ExecuteDocsGenerateCmd(cmd *cobra.Command, args []string) error { - defer perf.Track(nil, "exec.ExecuteDocsGenerateCmd")() - - if len(args) == 0 { - return errUtils.ErrMissingDocType - } - info, err := ProcessCommandLineArgs("", cmd, args, nil) - if err != nil { - return err - } - rootConfig, err := cfg.InitCliConfig(info, false) - if err != nil { - return err - } - - // Retrieve the generation config from atmos.yaml. - // The target directory is taken from docs.generate..base-dir. - docsGenerate, ok := rootConfig.Docs.Generate[args[0]] - if !ok { - return fmt.Errorf("%w: %q", errUtils.ErrNoDocsGenerateEntry, args[0]) - } - - if len(docsGenerate.Input) == 0 { - log.Debug("docs.generate[''].input is empty in atmos.yaml") - } - if len(docsGenerate.Template) == 0 { - log.Debug("No docs.generate[''].template' defined, generating minimal .") - } - - // Generate a single document in the targetDir using the default renderer. - return docs.Generate(&rootConfig, docsGenerate.BaseDir, &docsGenerate) -} diff --git a/pkg/ci/internal/provider/comment.go b/pkg/ci/internal/provider/comment.go index e0c7cc1ea7b..6a9774f77e6 100644 --- a/pkg/ci/internal/provider/comment.go +++ b/pkg/ci/internal/provider/comment.go @@ -80,6 +80,11 @@ type PostCommentOptions struct { // Behavior controls create/update/upsert semantics. Empty defaults to // CommentBehaviorUpsert. Behavior CommentBehavior + + // RunURL optionally links to the CI run (job summary) that produced the + // comment. Providers that truncate oversized bodies include it in the + // truncation notice so readers can reach the full output. Empty omits it. + RunURL string } // Comment represents a PR/MR comment returned by PostComment. diff --git a/pkg/ci/plugins/terraform/template_test.go b/pkg/ci/plugins/terraform/template_test.go index 5438948b980..bbfbe44b425 100644 --- a/pkg/ci/plugins/terraform/template_test.go +++ b/pkg/ci/plugins/terraform/template_test.go @@ -1077,3 +1077,47 @@ func TestTemplateGolden(t *testing.T) { }) } } + +// TestPlanTemplateRunLink verifies the plan template links the CI run only when a run URL exists. +func TestPlanTemplateRunLink(t *testing.T) { + const runURL = "https://github.com/owner/repo/actions/runs/123" + tests := []struct { + name string + ci *provider.Context + wantLink string + }{ + {name: "run URL present", ci: &provider.Context{RunURL: runURL}, wantLink: "[View full run](" + runURL + ")"}, + {name: "run URL empty", ci: &provider.Context{}}, + {name: "nil CI context", ci: nil}, + } + + content, err := defaultTemplates.ReadFile("templates/plan.md") + require.NoError(t, err) + tmpl, err := template.New("plan").Parse(string(content)) + require.NoError(t, err) + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + ctx := &TerraformTemplateContext{ + TemplateContext: &plugin.TemplateContext{ + Stack: "dev", + Component: "vpc", + Command: "plan", + CI: tt.ci, + Result: &plugin.OutputResult{HasChanges: true}, + }, + Resources: plugin.ResourceCounts{Create: 1}, + CreatedResources: []string{"aws_vpc.main"}, + } + var buf strings.Builder + require.NoError(t, tmpl.Execute(&buf, ctx)) + rendered := buf.String() + if tt.wantLink == "" { + assert.NotContains(t, rendered, "View full run") + return + } + assert.Contains(t, rendered, tt.wantLink) + assert.True(t, strings.HasSuffix(strings.TrimSpace(rendered), "job summary, and logs."), "link is the footer") + }) + } +} diff --git a/pkg/ci/plugins/terraform/templates/plan.md b/pkg/ci/plugins/terraform/templates/plan.md index 2c48aceeb45..98105058b54 100644 --- a/pkg/ci/plugins/terraform/templates/plan.md +++ b/pkg/ci/plugins/terraform/templates/plan.md @@ -144,3 +144,8 @@ atmos terraform plan {{.Component}} -s {{.Stack}} {{- end }} {{- end }} {{- end }} + +{{- if and .CI .CI.RunURL }} + +[View full run]({{ .CI.RunURL }}) for the complete plan output, job summary, and logs. +{{- end }} diff --git a/pkg/ci/providers/github/comment_size.go b/pkg/ci/providers/github/comment_size.go index c60347759a2..3d2ea4b3289 100644 --- a/pkg/ci/providers/github/comment_size.go +++ b/pkg/ci/providers/github/comment_size.go @@ -13,12 +13,12 @@ const issueCommentMaxBytes = 65536 // limitIssueCommentBody keeps the upsert marker and a visible truncation notice // ahead of the retained content. The full summary remains untouched at the caller. -func limitIssueCommentBody(body, marker string) (string, error) { +// When runURL is non-empty, the notice links to it so readers can open the full output. +func limitIssueCommentBody(body, marker, runURL string) (string, error) { if len(body) <= issueCommentMaxBytes { return body, nil } - const notice = "> [!WARNING]\n> Comment truncated to fit GitHub's size limit. Consult the workflow summary, logs, or artifacts for the full output.\n\n" - prefix := notice + prefix := truncationNotice(runURL) if marker != "" { prefix = marker + "\n" + prefix body = strings.ReplaceAll(body, marker, "") @@ -36,3 +36,13 @@ func limitIssueCommentBody(body, marker string) (string, error) { } return prefix + body, nil } + +// truncationNotice returns the warning prepended to truncated comments. With a +// run URL, it links to the run, whose job summary holds the full output. +func truncationNotice(runURL string) string { + const base = "> [!WARNING]\n> Comment truncated to fit GitHub's size limit. Consult the workflow summary, logs, or artifacts for the full output." + if runURL == "" { + return base + "\n\n" + } + return base + " [View the full run](" + runURL + ").\n\n" +} diff --git a/pkg/ci/providers/github/comment_size_test.go b/pkg/ci/providers/github/comment_size_test.go index b1c131ff70c..f6dc9ee01c5 100644 --- a/pkg/ci/providers/github/comment_size_test.go +++ b/pkg/ci/providers/github/comment_size_test.go @@ -87,3 +87,55 @@ func TestPostComment_RejectsOversizedMarker(t *testing.T) { require.ErrorIs(t, err, errUtils.ErrCICommentPostFailed) assert.Empty(t, s.CommentsFor("owner", "repo", 42)) } + +// TestPostComment_TruncationNoticeRunLink verifies the truncation notice links the run when known +// and is unchanged when it is not. +func TestPostComment_TruncationNoticeRunLink(t *testing.T) { + const runURL = "https://github.com/owner/repo/actions/runs/123" + tests := []struct { + name string + runURL string + wantNotice string + }{ + { + name: "with run URL", + runURL: runURL, + wantNotice: "> [!WARNING]\n> Comment truncated to fit GitHub's size limit. Consult the workflow summary, logs, or artifacts for the full output. [View the full run](" + runURL + ").\n\n", + }, + { + name: "without run URL", + wantNotice: "> [!WARNING]\n> Comment truncated to fit GitHub's size limit. Consult the workflow summary, logs, or artifacts for the full output.\n\n", + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + s := ghtest.NewServer(t) + p := newTestProvider(t, s) + marker := "" + _, err := p.PostComment(context.Background(), &provider.PostCommentOptions{ + Owner: "owner", Repo: "repo", PRNumber: 42, + Marker: marker, Body: strings.Repeat("x", 70000) + marker, + Behavior: provider.CommentBehaviorCreate, RunURL: tt.runURL, + }) + require.NoError(t, err) + comments := s.CommentsFor("owner", "repo", 42) + require.Len(t, comments, 1) + assert.True(t, strings.HasPrefix(comments[0].Body, marker+"\n"+tt.wantNotice+"x"), "notice must follow the marker exactly") + assert.LessOrEqual(t, len(comments[0].Body), 65536) + }) + } +} + +// TestPostComment_RunURLIgnoredWhenNotTruncated verifies short bodies are posted unchanged. +func TestPostComment_RunURLIgnoredWhenNotTruncated(t *testing.T) { + s := ghtest.NewServer(t) + p := newTestProvider(t, s) + _, err := p.PostComment(context.Background(), &provider.PostCommentOptions{ + Owner: "owner", Repo: "repo", PRNumber: 42, + Body: "short", Behavior: provider.CommentBehaviorCreate, RunURL: "https://example.com/run/1", + }) + require.NoError(t, err) + comments := s.CommentsFor("owner", "repo", 42) + require.Len(t, comments, 1) + assert.Equal(t, "short", comments[0].Body) +} diff --git a/pkg/ci/providers/github/comments.go b/pkg/ci/providers/github/comments.go index dec95dc87f0..b81f5f3aad9 100644 --- a/pkg/ci/providers/github/comments.go +++ b/pkg/ci/providers/github/comments.go @@ -42,7 +42,7 @@ func (p *Provider) postComment(ctx context.Context, opts *provider.PostCommentOp maskedOpts := *opts maskedOpts.Body = provider.MaskPublishedContent(opts.Body) maskedOpts.Marker = provider.MaskPublishedContent(opts.Marker) - limitedBody, err := limitIssueCommentBody(maskedOpts.Body, maskedOpts.Marker) + limitedBody, err := limitIssueCommentBody(maskedOpts.Body, maskedOpts.Marker, provider.MaskPublishedContent(opts.RunURL)) if err != nil { return nil, err } diff --git a/pkg/ci/providers/github/comments_test.go b/pkg/ci/providers/github/comments_test.go index e07e27d559e..99a1d162553 100644 --- a/pkg/ci/providers/github/comments_test.go +++ b/pkg/ci/providers/github/comments_test.go @@ -182,6 +182,34 @@ func TestProvider_PostComment_MasksRegisteredSecrets(t *testing.T) { assert.Contains(t, writes[0].Body, atmosio.MaskReplacement) } +func TestProvider_PostComment_MasksRunURLInTruncationNotice(t *testing.T) { + atmosio.Reset() + t.Cleanup(atmosio.Reset) + + const secret = "runurl-secret-ABCD1234" + atmosio.RegisterSecret(secret) + + s := ghtest.NewServer(t) + p := newTestProvider(t, s) + + marker := "" + _, err := p.PostComment(context.Background(), &provider.PostCommentOptions{ + Owner: "owner", + Repo: "repo", + PRNumber: 42, + Marker: marker, + Body: marker + "\n" + strings.Repeat("x", issueCommentMaxBytes+10), + RunURL: "https://github.com/owner/repo/actions/runs/1?token=" + secret, + Behavior: provider.CommentBehaviorCreate, + }) + require.NoError(t, err) + + writes := s.Comments() + require.Len(t, writes, 1) + assert.NotContains(t, writes[0].Body, secret) + assert.Contains(t, writes[0].Body, atmosio.MaskReplacement) +} + func TestProvider_PostComment_UpdateReturnsNotFoundWhenAbsent(t *testing.T) { s := ghtest.NewServer(t) p := newTestProvider(t, s) diff --git a/pkg/ci/reporter_comments.go b/pkg/ci/reporter_comments.go index 54fef33ac28..2497d5dbd5e 100644 --- a/pkg/ci/reporter_comments.go +++ b/pkg/ci/reporter_comments.go @@ -145,6 +145,7 @@ func postPullRequestComment(ctx context.Context, p provider.Provider, plan comme Marker: plan.marker, Body: plan.body, Behavior: plan.behavior, + RunURL: ciCtx.RunURL, }) } diff --git a/pkg/ci/reporter_test.go b/pkg/ci/reporter_test.go index 5c4bb28bb63..11b5c0886c7 100644 --- a/pkg/ci/reporter_test.go +++ b/pkg/ci/reporter_test.go @@ -582,6 +582,7 @@ func TestReporter_Comment(t *testing.T) { Marker: "", Body: "\nhello", Behavior: CommentBehaviorUpsert, + RunURL: "https://ci.example/run/1", }).Return(want, nil) rc, err := NewReporter(ciConfig(commentsOn)).Comment(ctx, CommentRequest{Body: "hello", Key: "plan"}) @@ -621,6 +622,7 @@ func TestReporter_Comment(t *testing.T) { PRNumber: 42, Body: "plain", Behavior: CommentBehaviorCreate, + RunURL: "https://ci.example/run/1", }).Return(&Comment{}, nil) _, err := NewReporter(ciConfig(commentsOn)).Comment(ctx, CommentRequest{Body: "plain"}) diff --git a/pkg/datafetcher/schema/atmos/config/1.0.json b/pkg/datafetcher/schema/atmos/config/1.0.json index 9fbe3b80bc9..7aaa6127726 100644 --- a/pkg/datafetcher/schema/atmos/config/1.0.json +++ b/pkg/datafetcher/schema/atmos/config/1.0.json @@ -5345,6 +5345,20 @@ "$ref": "#/$defs/yamlFunction" } ] + }, + "hooks": { + "anyOf": [ + { + "type": "object" + }, + { + "type": "null" + }, + { + "$ref": "#/$defs/yamlFunction" + } + ], + "description": "Hooks declares lifecycle hooks (before.docs.generate / after.docs.generate) for this doc type.\nThe map is decoded into hook definitions by pkg/hooks, which schema cannot import." } }, "type": "object" diff --git a/pkg/docs/command.go b/pkg/docs/command.go new file mode 100644 index 00000000000..3dfb88e8f7c --- /dev/null +++ b/pkg/docs/command.go @@ -0,0 +1,90 @@ +package docs + +import ( + "fmt" + "slices" + "strings" + + "github.com/spf13/cobra" + + errUtils "github.com/cloudposse/atmos/errors" + cfg "github.com/cloudposse/atmos/pkg/config" + log "github.com/cloudposse/atmos/pkg/logger" + "github.com/cloudposse/atmos/pkg/perf" + "github.com/cloudposse/atmos/pkg/schema" +) + +// ExecuteGenerate implements 'atmos docs generate ': it loads atmos.yaml honoring the +// global --base-path, --config, --config-path, and --profile flags, selects the +// docs.generate. entry, and generates the document with lifecycle hooks. +func ExecuteGenerate(cmd *cobra.Command, args []string) error { + defer perf.Track(nil, "docs.ExecuteGenerate")() + + if len(args) == 0 { + return errUtils.ErrMissingDocType + } + // Cobra already parsed the flags and stripped any "--" separator, so args are positional only + // (a doc type named like a flag must not be parsed again). InheritedFlags merges the parent's + // persistent flags (--base-path, --config, ...) into cmd.Flags() without parsing. + _ = cmd.InheritedFlags() + info, err := globalFlagsInfo(cmd) + if err != nil { + return err + } + rootConfig, err := cfg.InitCliConfig(info, false) + if err != nil { + return err + } + + // Retrieve the generation config from atmos.yaml. + // The target directory is taken from docs.generate..base-dir. + docsGenerate, ok := rootConfig.Docs.Generate[args[0]] + if !ok { + return errUtils.Build(fmt.Errorf("%w: %q", errUtils.ErrNoDocsGenerateEntry, args[0])). + WithHint(configuredDocTypesHint(rootConfig.Docs.Generate)). + Err() + } + + if len(docsGenerate.Input) == 0 { + log.Debug("docs.generate[''].input is empty in atmos.yaml") + } + if len(docsGenerate.Template) == 0 { + log.Debug("No docs.generate[''].template' defined, generating minimal .") + } + + // Generate a single document in the targetDir using the default renderer. + return GenerateWithHooks(&rootConfig, cmd, args[0], &docsGenerate) +} + +// globalFlagsInfo carries the persistent configuration-selection flags into the config loader. +// Profiles fall back to ATMOS_PROFILE inside the loader when the flag is unset. +func globalFlagsInfo(cmd *cobra.Command) (schema.ConfigAndStacksInfo, error) { + var info schema.ConfigAndStacksInfo + var err error + if info.BasePath, err = cmd.Flags().GetString("base-path"); err != nil { + return info, err + } + if info.AtmosConfigFilesFromArg, err = cmd.Flags().GetStringSlice("config"); err != nil { + return info, err + } + if info.AtmosConfigDirsFromArg, err = cmd.Flags().GetStringSlice("config-path"); err != nil { + return info, err + } + if info.ProfilesFromArg, err = cmd.Flags().GetStringSlice("profile"); err != nil { + return info, err + } + return info, nil +} + +// configuredDocTypesHint lists the configured docs.generate types in name order. +func configuredDocTypesHint(configured map[string]schema.DocsGenerate) string { + if len(configured) == 0 { + return "No docs.generate entries are configured in atmos.yaml" + } + names := make([]string, 0, len(configured)) + for name := range configured { + names = append(names, name) + } + slices.Sort(names) + return "Configured docs.generate types: " + strings.Join(names, ", ") +} diff --git a/pkg/docs/command_test.go b/pkg/docs/command_test.go new file mode 100644 index 00000000000..dacb4f1c658 --- /dev/null +++ b/pkg/docs/command_test.go @@ -0,0 +1,62 @@ +package docs + +import ( + "os" + "path/filepath" + "strings" + "testing" + + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + errUtils "github.com/cloudposse/atmos/errors" + "github.com/cloudposse/atmos/pkg/schema" +) + +// newGenerateCmd mimics the persistent root flags ExecuteGenerate reads. +func newGenerateCmd() *cobra.Command { + cmd := &cobra.Command{} + cmd.Flags().String("base-path", "", "") + cmd.Flags().StringSlice("config", nil, "") + cmd.Flags().StringSlice("config-path", nil, "") + cmd.Flags().StringSlice("profile", nil, "") + return cmd +} + +func TestExecuteGenerate(t *testing.T) { + dir := t.TempDir() + atmosYAML := "base_path: .\ndocs:\n generate:\n readme:\n base-dir: .\n output: OUT.md\n" + require.NoError(t, os.WriteFile(filepath.Join(dir, "atmos.yaml"), []byte(atmosYAML), 0o600)) + t.Setenv("ATMOS_CLI_CONFIG_PATH", dir) + t.Setenv("ATMOS_BASE_PATH", dir) + t.Chdir(dir) + + t.Run("missing doc type", func(t *testing.T) { + require.ErrorIs(t, ExecuteGenerate(newGenerateCmd(), nil), errUtils.ErrMissingDocType) + }) + t.Run("unknown doc type lists configured types", func(t *testing.T) { + err := ExecuteGenerate(newGenerateCmd(), []string{"nope"}) + require.ErrorIs(t, err, errUtils.ErrNoDocsGenerateEntry) + assert.Contains(t, strings.Join(errUtils.AllHints(err), "\n"), "readme") + }) + t.Run("generates configured document", func(t *testing.T) { + require.NoError(t, ExecuteGenerate(newGenerateCmd(), []string{"readme"})) + assert.FileExists(t, filepath.Join(dir, "OUT.md")) + }) + t.Run("flag-shaped doc type stays positional", func(t *testing.T) { + cmd := newGenerateCmd() + cmd.Flags().StringSlice("skip-hooks", nil, "") + err := ExecuteGenerate(cmd, []string{"--skip-hooks"}) + require.ErrorIs(t, err, errUtils.ErrNoDocsGenerateEntry) + assert.False(t, cmd.Flags().Changed("skip-hooks"), "args must not be parsed as flags again") + }) + t.Run("missing flag definitions", func(t *testing.T) { + require.Error(t, ExecuteGenerate(&cobra.Command{}, []string{"readme"})) + }) +} + +func TestConfiguredDocTypesHint(t *testing.T) { + assert.Contains(t, configuredDocTypesHint(map[string]schema.DocsGenerate{"b": {}, "a": {}}), "a, b") + assert.Contains(t, configuredDocTypesHint(nil), "No docs.generate") +} diff --git a/pkg/docs/generate.go b/pkg/docs/generate.go index db8442e89fa..c4013805034 100644 --- a/pkg/docs/generate.go +++ b/pkg/docs/generate.go @@ -198,26 +198,28 @@ func Generate(atmosConfig *schema.AtmosConfiguration, baseDir string, docsGenera if err != nil { return fmt.Errorf("%w: %w", errUtils.ErrPathResolution, err) } - return generateDocument(atmosConfig, absoluteDir, docsGenerate, defaultTemplateRenderer{}) + _, err = generateDocument(atmosConfig, absoluteDir, docsGenerate, defaultTemplateRenderer{}) + return err } // generateDocument merges the docs inputs, optionally runs terraform-docs, renders, and writes the document. +// It returns the resolved output path. func generateDocument( atmosConfig *schema.AtmosConfiguration, baseDir string, docsGenerate *schema.DocsGenerate, renderer templateRenderer, -) error { +) (string, error) { // 1) Merge YAML inputs. mergedData, err := mergeInputs(atmosConfig, baseDir, docsGenerate) if err != nil { - return errors.Join(errUtils.ErrMergeInputYAMLs, err) + return "", errors.Join(errUtils.ErrMergeInputYAMLs, err) } // 2) Generate terraform docs if enabled. module, err := applyTerraformDocs(atmosConfig, baseDir, docsGenerate, mergedData) if err != nil { - return err + return "", err } if _, ok := mergedData["terraform_docs"]; !ok { mergedData["terraform_docs"] = "" @@ -226,29 +228,29 @@ func generateDocument( // 3) Fetch the template. chosenTemplate, err := fetchTemplate(atmosConfig, docsGenerate, baseDir) if err != nil { - return err + return "", err } // 4) Render final document using the injected renderer. rendered, err := renderer.Render("docs-generate", chosenTemplate, mergedData, module) if err != nil { - return errors.Join(errUtils.ErrRenderTemplate, err) + return "", errors.Join(errUtils.ErrRenderTemplate, err) } // 5) Resolve and write final document. outputPath, err := resolvePath(docsGenerate.Output, baseDir, defaultReadmeOutput) if err != nil { - return fmt.Errorf("%w: %s: %w", errUtils.ErrResolveOutputPath, docsGenerate.Output, err) + return "", fmt.Errorf("%w: %s: %w", errUtils.ErrResolveOutputPath, docsGenerate.Output, err) } if err = os.WriteFile(outputPath, []byte(rendered), defaultFilePermissions); err != nil { - return fmt.Errorf("%w: %s: %w", errUtils.ErrWriteOutput, outputPath, err) + return "", fmt.Errorf("%w: %s: %w", errUtils.ErrWriteOutput, outputPath, err) } ui.Writeln("") ui.Success("Generated docs") ui.Writeln("") log.Debug("Documentation generated", "output", outputPath) - return nil + return outputPath, nil } // fetchAndParseYAML reads a YAML file from a local path or downloads it from a remote URL. diff --git a/pkg/docs/generate_test.go b/pkg/docs/generate_test.go index 8a2ccb1c227..a56ff60bf6c 100644 --- a/pkg/docs/generate_test.go +++ b/pkg/docs/generate_test.go @@ -265,7 +265,7 @@ func TestGenerateDocument_WithInjectedRenderer(t *testing.T) { docsGenerate := atmosConfig.Docs.Generate["readme"] // Call generateDocument with our injected stubRenderer. - err = generateDocument(&atmosConfig, targetDir, &docsGenerate, mockRenderer{}) + _, err = generateDocument(&atmosConfig, targetDir, &docsGenerate, mockRenderer{}) if err != nil { t.Fatalf("generateDocument failed: %v", err) } @@ -314,7 +314,7 @@ func TestGenerateDocument_DefaultTemplateFallback_RealRenderer(t *testing.T) { } docsGenerate := atmosConfig.Docs.Generate["readme"] - if err := generateDocument(&atmosConfig, targetDir, &docsGenerate, defaultTemplateRenderer{}); err != nil { + if _, err := generateDocument(&atmosConfig, targetDir, &docsGenerate, defaultTemplateRenderer{}); err != nil { t.Fatalf("generateDocument failed: %v", err) } @@ -368,7 +368,7 @@ func TestGenerateDocument_TemplateFetchFailsReturnsError(t *testing.T) { } docsGenerate := atmosConfig.Docs.Generate["readme"] - err = generateDocument(&atmosConfig, targetDir, &docsGenerate, defaultTemplateRenderer{}) + _, err = generateDocument(&atmosConfig, targetDir, &docsGenerate, defaultTemplateRenderer{}) if err == nil { t.Fatal("expected generateDocument to return an error for a missing configured template") } diff --git a/pkg/docs/hooks.go b/pkg/docs/hooks.go new file mode 100644 index 00000000000..5332c20e844 --- /dev/null +++ b/pkg/docs/hooks.go @@ -0,0 +1,109 @@ +package docs + +import ( + "errors" + "path/filepath" + + "github.com/spf13/cobra" + + errUtils "github.com/cloudposse/atmos/errors" + "github.com/cloudposse/atmos/pkg/hooks/events" + log "github.com/cloudposse/atmos/pkg/logger" + "github.com/cloudposse/atmos/pkg/perf" + "github.com/cloudposse/atmos/pkg/schema" +) + +// HookRunnerRequest describes the docs generation a HookRunner serves. +type HookRunnerRequest struct { + // AtmosConfig is the active configuration. + AtmosConfig *schema.AtmosConfiguration + // DocType is the docs.generate. key. + DocType string + // BaseDir is the absolute docs.generate..base-dir. + BaseDir string + // OutputPath is the absolute path of the document being generated. + OutputPath string + // Hooks is the untyped docs.generate..hooks map. + Hooks map[string]any + // Cmd is the running command, used for --skip-hooks. + Cmd *cobra.Command +} + +// HookRunner fires lifecycle hooks around document generation. +type HookRunner interface { + // Run fires event. genErr is the generation result for after events and nil for before + // events. The returned error already reflects each hook's on_failure handling and any + // policy denial. + Run(event events.HookEvent, genErr error) error +} + +// HookRunnerFactory builds a HookRunner for one generation. +type HookRunnerFactory func(req *HookRunnerRequest) (HookRunner, error) + +// hookRunnerFactory is registered by pkg/hooks. The hook engine depends on the exec pipeline, +// which depends on this package, so this package cannot import it directly. +// +//nolint:gochecknoglobals // registry seam that breaks the pkg/hooks -> internal/exec -> pkg/docs import cycle. +var hookRunnerFactory HookRunnerFactory + +// RegisterHookRunnerFactory installs the factory that supplies lifecycle hooks to Generate +// callers. The pkg/hooks package registers it at init; a nil factory disables hooks. +func RegisterHookRunnerFactory(factory HookRunnerFactory) { + defer perf.Track(nil, "docs.RegisterHookRunnerFactory")() + + hookRunnerFactory = factory +} + +// GenerateWithHooks generates the document configured under docs.generate. and runs the +// before.docs.generate and after.docs.generate lifecycle hooks around it. A before hook failure +// (or a policy denial) aborts before any file is written. After hooks run on success and on +// failure, filtered by each hook's `when`. +func GenerateWithHooks(atmosConfig *schema.AtmosConfiguration, cmd *cobra.Command, docType string, docsGenerate *schema.DocsGenerate) error { + defer perf.Track(atmosConfig, "docs.GenerateWithHooks")() + + baseDir, err := filepath.Abs(docsGenerate.BaseDir) + if err != nil { + return errors.Join(errUtils.ErrPathResolution, err) + } + outputPath, err := resolvePath(docsGenerate.Output, baseDir, defaultReadmeOutput) + if err != nil { + return errors.Join(errUtils.ErrResolveOutputPath, err) + } + + var runner HookRunner + if hookRunnerFactory == nil && len(docsGenerate.Hooks) > 0 { + // Never drop configured hooks silently: they may gate or publish the document. + return errUtils.Build(errUtils.ErrDocsHooksUnavailable). + WithHint("Link the hook engine into the binary by importing github.com/cloudposse/atmos/pkg/hooks, or remove docs.generate..hooks."). + Err() + } + if hookRunnerFactory != nil { + runner, err = hookRunnerFactory(&HookRunnerRequest{ + AtmosConfig: atmosConfig, DocType: docType, BaseDir: baseDir, + OutputPath: outputPath, Hooks: docsGenerate.Hooks, Cmd: cmd, + }) + if err != nil { + return err + } + } + return runLifecycle(atmosConfig, baseDir, docsGenerate, defaultTemplateRenderer{}, runner) +} + +// runLifecycle runs before hooks, generates the document, then runs after hooks. A nil runner +// generates without hooks. +func runLifecycle(atmosConfig *schema.AtmosConfiguration, baseDir string, docsGenerate *schema.DocsGenerate, renderer templateRenderer, runner HookRunner) error { + if runner == nil { + _, err := generateDocument(atmosConfig, baseDir, docsGenerate, renderer) + return err + } + if err := runner.Run(events.BeforeDocsGenerate, nil); err != nil { + return err + } + outputPath, genErr := generateDocument(atmosConfig, baseDir, docsGenerate, renderer) + if genErr != nil { + log.Debug("Docs generation failed, running after hooks for failure", "error", genErr) + } else { + log.Debug("Docs generated, running after hooks", "output", outputPath) + } + return errors.Join(genErr, runner.Run(events.AfterDocsGenerate, genErr)) +} diff --git a/pkg/docs/hooks_test.go b/pkg/docs/hooks_test.go new file mode 100644 index 00000000000..e9392f89704 --- /dev/null +++ b/pkg/docs/hooks_test.go @@ -0,0 +1,183 @@ +package docs + +import ( + "errors" + "os" + "path/filepath" + "testing" + + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + tfdocsTf "github.com/terraform-docs/terraform-docs/terraform" + + errUtils "github.com/cloudposse/atmos/errors" + "github.com/cloudposse/atmos/pkg/hooks/events" + "github.com/cloudposse/atmos/pkg/schema" +) + +var errTestHook = errors.New("hook failed") + +// fakeHookRunner records fired events and the generation result passed with each. +type fakeHookRunner struct { + fired []events.HookEvent + genErrs []error + failOn events.HookEvent + failWith error + // outputExistsAtBefore records whether the output file existed when the before event fired. + outputPath string + outputExistsAtFire map[events.HookEvent]bool +} + +func (f *fakeHookRunner) Run(event events.HookEvent, genErr error) error { + f.fired = append(f.fired, event) + f.genErrs = append(f.genErrs, genErr) + if f.outputExistsAtFire == nil { + f.outputExistsAtFire = map[events.HookEvent]bool{} + } + _, statErr := os.Stat(f.outputPath) + f.outputExistsAtFire[event] = statErr == nil + if event == f.failOn { + return f.failWith + } + return nil +} + +// failingRenderer always fails to render, simulating a broken template. +type failingRenderer struct{} + +func (failingRenderer) Render(string, string, map[string]any, *tfdocsTf.Module) (string, error) { + return "", errTestHook +} + +func lifecycleFixture(t *testing.T) (string, *schema.DocsGenerate) { + t.Helper() + dir := t.TempDir() + return dir, &schema.DocsGenerate{BaseDir: dir, Output: filepath.Join(dir, "OUT.md")} +} + +func TestRunLifecycle(t *testing.T) { + tests := []struct { + name string + failOn events.HookEvent + failWith error + breakTemplate bool + wantFired []events.HookEvent + wantErr error + wantFile bool + }{ + { + name: "success runs before then after", + wantFired: []events.HookEvent{events.BeforeDocsGenerate, events.AfterDocsGenerate}, + wantFile: true, + }, + { + name: "before failure aborts before generation", + failOn: events.BeforeDocsGenerate, + failWith: errTestHook, + wantFired: []events.HookEvent{events.BeforeDocsGenerate}, + wantErr: errTestHook, + }, + { + name: "generation failure still runs after hooks", + breakTemplate: true, + wantFired: []events.HookEvent{events.BeforeDocsGenerate, events.AfterDocsGenerate}, + wantErr: errUtils.ErrRenderTemplate, + }, + { + name: "after failure is returned after a successful generation", + failOn: events.AfterDocsGenerate, + failWith: errTestHook, + wantFired: []events.HookEvent{events.BeforeDocsGenerate, events.AfterDocsGenerate}, + wantErr: errTestHook, + wantFile: true, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + dir, dg := lifecycleFixture(t) + var renderer templateRenderer = mockRenderer{} + if tt.breakTemplate { + renderer = failingRenderer{} + } + runner := &fakeHookRunner{failOn: tt.failOn, failWith: tt.failWith, outputPath: dg.Output} + + err := runLifecycle(&schema.AtmosConfiguration{}, dir, dg, renderer, runner) + + if tt.wantErr != nil { + require.ErrorIs(t, err, tt.wantErr) + } else { + require.NoError(t, err) + } + assert.Equal(t, tt.wantFired, runner.fired) + if tt.wantFile { + assert.FileExists(t, dg.Output) + } else { + assert.NoFileExists(t, dg.Output) + } + assert.False(t, runner.outputExistsAtFire[events.BeforeDocsGenerate], "before hooks run before the file is written") + if len(runner.genErrs) == 2 { + assert.NoError(t, runner.genErrs[0], "before events carry no generation result") + assert.Equal(t, tt.breakTemplate, runner.genErrs[1] != nil, "after events carry the generation result") + } + }) + } +} + +func TestRunLifecycleWithoutRunnerGenerates(t *testing.T) { + dir, dg := lifecycleFixture(t) + require.NoError(t, runLifecycle(&schema.AtmosConfiguration{}, dir, dg, mockRenderer{}, nil)) + assert.FileExists(t, dg.Output) +} + +func TestGenerateWithHooksUsesRegisteredFactory(t *testing.T) { + t.Cleanup(func() { RegisterHookRunnerFactory(nil) }) + + dir, dg := lifecycleFixture(t) + dg.Hooks = map[string]any{"example": map[string]any{}} + var got *HookRunnerRequest + runner := &fakeHookRunner{outputPath: dg.Output} + RegisterHookRunnerFactory(func(req *HookRunnerRequest) (HookRunner, error) { + got = req + return runner, nil + }) + cmd := &cobra.Command{} + + require.NoError(t, GenerateWithHooks(&schema.AtmosConfiguration{}, cmd, "readme", dg)) + + require.NotNil(t, got) + assert.Equal(t, "readme", got.DocType) + assert.Equal(t, dir, got.BaseDir) + assert.Equal(t, dg.Output, got.OutputPath) + assert.Same(t, cmd, got.Cmd) + assert.Equal(t, dg.Hooks, got.Hooks) + assert.Equal(t, []events.HookEvent{events.BeforeDocsGenerate, events.AfterDocsGenerate}, runner.fired) +} + +func TestGenerateWithHooksFactoryError(t *testing.T) { + t.Cleanup(func() { RegisterHookRunnerFactory(nil) }) + + _, dg := lifecycleFixture(t) + RegisterHookRunnerFactory(func(*HookRunnerRequest) (HookRunner, error) { return nil, errTestHook }) + + require.ErrorIs(t, GenerateWithHooks(&schema.AtmosConfiguration{}, nil, "readme", dg), errTestHook) + assert.NoFileExists(t, dg.Output) +} + +func TestGenerateWithHooksWithoutFactory(t *testing.T) { + RegisterHookRunnerFactory(nil) + _, dg := lifecycleFixture(t) + require.NoError(t, GenerateWithHooks(&schema.AtmosConfiguration{}, nil, "readme", dg)) + assert.FileExists(t, dg.Output) +} + +func TestGenerateWithHooksConfiguredHooksWithoutFactoryFails(t *testing.T) { + RegisterHookRunnerFactory(nil) + _, dg := lifecycleFixture(t) + dg.Hooks = map[string]any{"publish": map[string]any{"kind": "step"}} + + err := GenerateWithHooks(&schema.AtmosConfiguration{}, nil, "readme", dg) + + require.ErrorIs(t, err, errUtils.ErrDocsHooksUnavailable) + assert.NoFileExists(t, dg.Output, "nothing may be generated when configured hooks cannot run") +} diff --git a/pkg/docs/native_terraform_test.go b/pkg/docs/native_terraform_test.go index ee04b2bae55..9157c0875ba 100644 --- a/pkg/docs/native_terraform_test.go +++ b/pkg/docs/native_terraform_test.go @@ -198,13 +198,15 @@ func TestGenerateDocument_NativeTerraformRenderIsolation(t *testing.T) { dir := t.TempDir() require.NoError(t, os.WriteFile(filepath.Join(dir, "main.tf"), []byte(`variable "`+name+`" { type = string }`), 0o600)) docs := nativeDocsTestConfig(t, `{{ range (terraform).Inputs }}{{ .Name }}{{ end }}`) - require.NoError(t, generateDocument(&schema.AtmosConfiguration{}, dir, &docs, renderer)) + _, err := generateDocument(&schema.AtmosConfiguration{}, dir, &docs, renderer) + require.NoError(t, err) assert.Equal(t, name, readDocsTestFile(t, docs.Output)) } // A subsequent render without Terraform must not inherit the previous module. docs := nativeDocsTestConfig(t, `{{ if terraform }}leaked{{ else }}unavailable{{ end }}`) docs.Terraform.Enabled = false - require.NoError(t, generateDocument(&schema.AtmosConfiguration{}, t.TempDir(), &docs, renderer)) + _, genErr := generateDocument(&schema.AtmosConfiguration{}, t.TempDir(), &docs, renderer) + require.NoError(t, genErr) assert.Equal(t, "unavailable", readDocsTestFile(t, docs.Output)) // The helper is not registered globally for unrelated template consumers. _, err := datasource.Render(nil, "unrelated", `{{ terraform }}`, map[string]any{}, nil) diff --git a/pkg/hooks/command_engine.go b/pkg/hooks/command_engine.go index 6c0664bbad4..7168d562904 100644 --- a/pkg/hooks/command_engine.go +++ b/pkg/hooks/command_engine.go @@ -6,6 +6,7 @@ import ( "errors" "fmt" "io" + "maps" "os" "os/exec" "path/filepath" @@ -704,6 +705,7 @@ func buildAtmosEnv(ctx *ExecContext, outputFile, outputDir string) map[string]st for k, v := range OutcomeEnv(ctx.Outcome) { env[k] = v } + maps.Copy(env, ctx.OperationEnv) if ctx.HookDepth > 0 { env[HookDepthEnvVar] = strconv.Itoa(ctx.HookDepth) } @@ -988,6 +990,15 @@ func ApplyOnFailure(ctx *ExecContext, runErr error) error { return applyOnFailure(ctx, runErr) } +// hookDisplayName names the failing hook for error messages, falling back to the hook's +// kind when the execution context carries no name (directly constructed contexts). +func hookDisplayName(ctx *ExecContext) string { + if ctx.HookName != "" { + return fmt.Sprintf("%q", ctx.HookName) + } + return fmt.Sprintf("%q", ctx.Hook.Kind) +} + // applyOnFailure returns nil or an error depending on the configured failure // mode. "warn" (default) logs and returns nil; "fail" propagates the error; // "ignore" drops it entirely. @@ -1001,7 +1012,7 @@ func applyOnFailure(ctx *ExecContext, runErr error) error { } switch mode { case OnFailureFail: - return fmt.Errorf("hook (kind %s) failed: %w", ctx.Hook.Kind, runErr) + return fmt.Errorf("hook %s (kind %s, event %s) failed: %w", hookDisplayName(ctx), ctx.Hook.Kind, ctx.Event.Normalize(), runErr) case OnFailureIgnore: log.Debug( "Hook command failed (ignored per on_failure)", diff --git a/pkg/hooks/event.go b/pkg/hooks/event.go index ee468575883..4174453de4e 100644 --- a/pkg/hooks/event.go +++ b/pkg/hooks/event.go @@ -87,4 +87,6 @@ const ( AfterHelmfileDestroy = events.AfterHelmfileDestroy BeforeScaffoldGenerate = events.BeforeScaffoldGenerate AfterScaffoldGenerate = events.AfterScaffoldGenerate + BeforeDocsGenerate = events.BeforeDocsGenerate + AfterDocsGenerate = events.AfterDocsGenerate ) diff --git a/pkg/hooks/events/builtins.go b/pkg/hooks/events/builtins.go index f64427def0f..f37ce214877 100644 --- a/pkg/hooks/events/builtins.go +++ b/pkg/hooks/events/builtins.go @@ -43,6 +43,7 @@ func builtins() []HookEvent { BeforeHelmfileDeploy, AfterHelmfileDeploy, BeforeHelmfileDestroy, AfterHelmfileDestroy, BeforeScaffoldGenerate, AfterScaffoldGenerate, + BeforeDocsGenerate, AfterDocsGenerate, "before.helmfile.version", "after.helmfile.version", } } diff --git a/pkg/hooks/events/event.go b/pkg/hooks/events/event.go index eef1194c8fe..5bbf2e0104f 100644 --- a/pkg/hooks/events/event.go +++ b/pkg/hooks/events/event.go @@ -90,6 +90,11 @@ const ( // which reuses this same Hook vocabulary and MatchesEvent/RunsWhenE. BeforeScaffoldGenerate HookEvent = "before.scaffold.generate" AfterScaffoldGenerate HookEvent = "after.scaffold.generate" + // BeforeDocsGenerate and AfterDocsGenerate fire around atmos docs generate. + // Like the scaffold events they are repo-level (no stack or component), and + // hooks are declared under docs.generate..hooks in atmos.yaml. + BeforeDocsGenerate HookEvent = "before.docs.generate" + AfterDocsGenerate HookEvent = "after.docs.generate" ) // Normalize returns the canonical form of a HookEvent, collapsing command diff --git a/pkg/hooks/events/registry_test.go b/pkg/hooks/events/registry_test.go index c14cb21553a..101e8960ea0 100644 --- a/pkg/hooks/events/registry_test.go +++ b/pkg/hooks/events/registry_test.go @@ -19,6 +19,7 @@ func TestRegisteredEvents(t *testing.T) { "before.aws/cloudformation.changeset-create", "after.aws/cloudformation.drift-detect", "before.scaffold.generate", "after.scaffold.generate", "after.helm.apply.aggregate", "before.terraform.destroy", "after.terraform.destroy", + "before.docs.generate", "after.docs.generate", } { t.Run(event, func(t *testing.T) { require.True(t, DefaultRegistry.Contains(event)) diff --git a/pkg/hooks/hooks.go b/pkg/hooks/hooks.go index fedc1dbcd2a..8b8a58e7d2c 100644 --- a/pkg/hooks/hooks.go +++ b/pkg/hooks/hooks.go @@ -72,11 +72,27 @@ type Hooks struct { // outcome is the lifecycle operation result (success/failure) for the next // RunAll, set by SetOutcome. Zero value defaults to success. - outcome Outcome + outcome Outcome + // operationEnv carries extra ATMOS_* variables for repo-level operations + // built by NewOperationHooks. Nil for component hooks. + operationEnv map[string]string + // operation marks hooks built by NewOperationHooks (no component dependencies section). + operation bool policyBundle *policy.Bundle policyCI *policy.CISnapshot } +// sortedHookNames returns the hook names in lexical order. Execution, preflight, and +// verification all iterate in this order so a run is deterministic. +func (h *Hooks) sortedHookNames() []string { + names := make([]string, 0, len(h.items)) + for name := range h.items { + names = append(names, name) + } + slices.Sort(names) + return names +} + func (h Hooks) HasHooks() bool { return len(h.items) > 0 || h.policyBundle != nil } @@ -171,7 +187,7 @@ func (h *Hooks) RunAll(event HookEvent, atmosConfig *schema.AtmosConfiguration, if outcome.Status == "" { outcome.Status = RunSuccess } - if err := h.runPolicyHooks(&hookRunContext{event: event, atmosConfig: atmosConfig, info: info, cmd: cmd, args: args, outcome: outcome}); err != nil { + if err := h.runPolicyHooks(&hookRunContext{event: event, atmosConfig: atmosConfig, info: info, cmd: cmd, args: args, outcome: outcome, operationEnv: h.operationEnv}); err != nil { return err } @@ -205,8 +221,10 @@ func (h *Hooks) RunAll(event HookEvent, atmosConfig *schema.AtmosConfiguration, args: args, filter: filter, outcome: outcome, + + operationEnv: h.operationEnv, } - for name := range h.items { + for _, name := range h.sortedHookNames() { hook := h.items[name] if err := h.runHookIfMatch(name, &hook, &runCtx); err != nil { return err @@ -223,6 +241,9 @@ type hookRunContext struct { args []string filter hookFilter outcome Outcome + // operationEnv mirrors Hooks.operationEnv so policy-selected hooks, which run on a + // separate trusted Hooks value, still receive the operation variables. + operationEnv map[string]string } func (h *Hooks) runHookIfMatch(name string, hook *Hook, ctx *hookRunContext) error { @@ -285,6 +306,7 @@ func (h *Hooks) runResolvedHook(name string, kind *Kind, executionHook *Hook, ct Args: ctx.args, HookName: name, Outcome: ctx.outcome, + OperationEnv: ctx.operationEnv, ToolchainPATH: h.toolchainPATH, Stdout: h.stdout, Stderr: h.stderr, @@ -784,7 +806,7 @@ func (h *Hooks) markPreflightDone(filter hookFilter) { } func (h *Hooks) hasUnskippedHooks(filter *hookFilter) (bool, error) { - for name := range h.items { + for _, name := range h.sortedHookNames() { hook := h.items[name] if !hook.MatchesEvent(filter.event) { continue @@ -864,13 +886,13 @@ func (h *Hooks) installDeps(atmosConfig *schema.AtmosConfiguration, info *schema } // verifyAllBinaries checks every hook's command resolves on the -// toolchain-augmented PATH so failures surface before terraform runs. +// toolchain-augmented PATH so failures surface before the operation runs. // Store-kind hooks have no Command and are skipped naturally. Hooks that // won't run for the current outcome status (per their `when`) are skipped so // an unrelated hook's misconfiguration cannot block the hooks that do run // (e.g. a success-only hook with a missing binary must not fail the failure path). func (h *Hooks) verifyAllBinaries(filter hookFilter) error { - for name := range h.items { + for _, name := range h.sortedHookNames() { if filter.skipPredicate != nil && filter.skipPredicate(name) { continue } @@ -909,7 +931,7 @@ func (h *Hooks) verifyHookBinary(name string, hook *Hook) error { return unknownHookKindError(name, hook.Kind) } // Step-kind hooks have no Command to resolve on PATH; instead verify the - // named step type is registered so a typo fails before terraform runs + // named step type is registered so a typo fails before the operation runs // rather than mid-lifecycle. if hook.Kind == stepKindName { return verifyStepHookType(name, hook.Type) @@ -924,10 +946,14 @@ func (h *Hooks) verifyHookBinary(name string, hook *Hook) error { if err := verifyCommandAvailable(resolved.Command, h.toolchainPATH); err != nil { // The cause already wraps ErrCommandNotFound with the command name, so // build on it directly instead of stacking a second sentinel prefix. - return errUtils.Build(err). - WithExplanationf("Hook %q (kind %s) requires %q, which is not installed and not on PATH", name, hook.Kind, resolved.Command). - WithHintf("Declare `%s: \"\"` in the component's dependencies.tools to auto-install it before terraform runs", resolved.Command). - WithHintf("Alternatively, install %s manually so it appears on PATH", resolved.Command). + builder := errUtils.Build(err). + WithExplanationf("Hook %q (kind %s) requires %q, which is not installed and not on PATH", name, hook.Kind, resolved.Command) + if !h.operation { + // Component hooks can auto-install pinned tools from the component's dependencies. + builder = builder.WithHintf("Declare `%s: \"\"` in the component's dependencies.tools to auto-install it before the command runs", resolved.Command) + } + return builder. + WithHintf("Install %s so it appears on PATH", resolved.Command). WithContext("hook", name). WithContext("kind", hook.Kind). WithContext("command", resolved.Command). diff --git a/pkg/hooks/kind.go b/pkg/hooks/kind.go index 1dcc6744821..370b1a8d9ed 100644 --- a/pkg/hooks/kind.go +++ b/pkg/hooks/kind.go @@ -53,6 +53,11 @@ type ExecContext struct { // sets ATMOS_HOOK_STATUS and injects `.status` into the template context). Outcome Outcome + // OperationEnv holds extra ATMOS_* variables describing a repo-level operation + // (for example ATMOS_DOCS_OUTPUT_PATH for docs generate). Engines export them + // alongside the standard component variables. Nil for component lifecycles. + OperationEnv map[string]string + // ToolchainPATH is the PATH fragment containing directories for any // dependencies.tools that were auto-installed for this component's // hooks. Populated by Hooks.preflight; consumed by CommandEngine diff --git a/pkg/hooks/main_test.go b/pkg/hooks/main_test.go index a22e4ade9b9..c037b1e89f5 100644 --- a/pkg/hooks/main_test.go +++ b/pkg/hooks/main_test.go @@ -3,6 +3,7 @@ package hooks import ( "fmt" "os" + "strconv" "testing" "github.com/cloudposse/atmos/pkg/data" @@ -41,6 +42,23 @@ func TestMain(m *testing.M) { } os.Exit(0) } + if code := os.Getenv("_ATMOS_TEST_EXIT_CODE"); code != "" { + // Exits with the requested status before m.Run, so no test-runner output is produced. + n, err := strconv.Atoi(code) + if err != nil { + os.Exit(2) + } + os.Exit(n) + } + if dump := os.Getenv("_ATMOS_TEST_DUMP_DOCS_ENV"); dump != "" { + // Records the docs operation variables a hook subprocess receives, then exits before m.Run. + body := os.Getenv("ATMOS_DOCS_TYPE") + "\n" + os.Getenv("ATMOS_DOCS_OUTPUT_PATH") + "\n" + os.Getenv("ATMOS_DOCS_BASE_DIR") + if err := os.WriteFile(dump, []byte(body), 0o600); err != nil { + fmt.Fprintln(os.Stderr, err) + os.Exit(1) + } + os.Exit(0) + } if os.Getenv("_ATMOS_TEST_ECHO_STDOUT") == "1" { fmt.Fprint(os.Stdout, os.Getenv("_ATMOS_TEST_STDOUT_BODY")) } diff --git a/pkg/hooks/operation.go b/pkg/hooks/operation.go new file mode 100644 index 00000000000..1c8d6f909de --- /dev/null +++ b/pkg/hooks/operation.go @@ -0,0 +1,217 @@ +package hooks + +import ( + "fmt" + "maps" + "slices" + "strings" + + "github.com/spf13/cobra" + yamlv2 "gopkg.in/yaml.v2" + yamlv3 "gopkg.in/yaml.v3" + + errUtils "github.com/cloudposse/atmos/errors" + log "github.com/cloudposse/atmos/pkg/logger" + "github.com/cloudposse/atmos/pkg/perf" + "github.com/cloudposse/atmos/pkg/schema" +) + +// OperationContext describes a repo-level operation (one that has no stack or component +// instance, such as `atmos docs generate`) whose lifecycle events run hooks. +type OperationContext struct { + // Type is the operation family. It becomes the policy component_type and the + // template/env namespace (for example "docs"). + Type string + // Name identifies the operation target. It becomes the policy component and the + // ATMOS_COMPONENT value (for example the docs.generate doc-type key). + Name string + // ConfigPath is where the hooks are declared (for example docs.generate.readme.hooks). + // It names the location in configuration errors. + ConfigPath string + // Env holds extra ATMOS_* variables exported to every hook run. + Env map[string]string + // Data is exposed to hook templates under the Type key (for example `.docs.output_path`). + Data map[string]any +} + +// NewOperationHooks builds hooks for a repo-level operation from an untyped hooks map +// (for example docs.generate..hooks). Unlike GetHooks it does not describe a +// component: the declarations are decoded and validated directly, while the governing +// policy bundle is loaded exactly as it is for component hooks. The result works with +// SetOutcome and RunOperation (or RunAll). +func NewOperationHooks(atmosConfig *schema.AtmosConfiguration, raw map[string]any, op OperationContext) (*Hooks, error) { + defer perf.Track(atmosConfig, "hooks.NewOperationHooks")() + + bundle, snapshot, err := loadPolicyGovernance() + if err != nil { + return nil, err + } + items, normalized, err := decodeOperationHooks(atmosConfig, raw, op.ConfigPath) + if err != nil { + return nil, err + } + warnForeignEvents(items, op.Type) + h := &Hooks{ + config: atmosConfig, + info: &schema.ConfigAndStacksInfo{ + ComponentType: op.Type, + ComponentFromArg: op.Name, + }, + items: items, + operation: true, + policyBundle: bundle, + policyCI: snapshot, + } + h.sections = map[string]any{} + if normalized != nil { + h.sections["hooks"] = normalized + } + h.SetOperationContext(op) + return h, nil +} + +// decodeOperationHooks decodes and validates the declarations. The second return value is a +// type-normalized copy used as the raw section for execution-time template rendering. +func decodeOperationHooks(atmosConfig *schema.AtmosConfiguration, raw map[string]any, configPath string) (map[string]Hook, map[string]any, error) { + if len(raw) == 0 { + return nil, nil, nil + } + if err := requireHookMap(raw, configPath); err != nil { + return nil, nil, err + } + data, err := yamlv2.Marshal(raw) + if err != nil { + return nil, nil, fmt.Errorf("%w: %w", errUtils.ErrInvalidHooksSection, err) + } + var items map[string]Hook + if err := yamlv2.Unmarshal(data, &items); err != nil { + return nil, nil, fmt.Errorf("%w: %w", errUtils.ErrInvalidHooksSection, err) + } + var edition string + if atmosConfig != nil { + edition = atmosConfig.Edition + } + if err := ValidateEvents(edition, items); err != nil { + return nil, nil, err + } + if err := validateOperationHooks(items); err != nil { + return nil, nil, err + } + var normalized map[string]any + if err := yamlv3.Unmarshal(data, &normalized); err != nil { + return nil, nil, fmt.Errorf("%w: %w", errUtils.ErrInvalidHooksSection, err) + } + return items, normalized, nil +} + +// foreignOperationEvents returns, per hook name, the declared events that belong to another +// operation family and so can never fire for this one. +func foreignOperationEvents(items map[string]Hook, opType string) map[string][]string { + foreign := map[string][]string{} + for name := range items { + for _, event := range items[name].Events { + parts := strings.Split(string(HookEvent(event).Normalize()), ".") + if len(parts) < 2 || parts[1] != opType { + foreign[name] = append(foreign[name], event) + } + } + } + return foreign +} + +// warnForeignEvents logs a warning for hooks whose events are valid but belong to another +// operation. Such hooks are legal, so this is not an error. +func warnForeignEvents(items map[string]Hook, opType string) { + if opType == "" { + return + } + foreign := foreignOperationEvents(items, opType) + names := make([]string, 0, len(foreign)) + for name := range foreign { + names = append(names, name) + } + slices.Sort(names) + for _, name := range names { + log.Warn("Hook declares events that never fire for this operation", + "hook", name, "events", foreign[name], + "supported", []string{"before." + opType + ".generate", "after." + opType + ".generate"}) + } +} + +// validateOperationHooks applies the checks governing policy hooks get, so a misconfigured hook +// fails before the operation starts instead of warning at run time. Hooks are checked in name order. +func validateOperationHooks(items map[string]Hook) error { + names := make([]string, 0, len(items)) + for name := range items { + names = append(names, name) + } + slices.Sort(names) + for _, name := range names { + hook := items[name] + if isDeprecatedCIKind(hook.Kind) { + continue + } + label := fmt.Sprintf("hook %q (kind %s", name, hook.Kind) + if hook.Type != "" { + label += ", type " + hook.Type + } + label += ")" + kind, ok := GetKind(hook.Kind) + if !ok { + return fmt.Errorf("%s: %w", label, unknownHookKindError(name, hook.Kind)) + } + if err := validatePolicyHookDefinition(name, &hook, kind); err != nil { + return fmt.Errorf("%s: %w", label, err) + } + } + return nil +} + +// requireHookMap checks that every hook is a map of hook definition fields. A list of hooks or a +// bare value has the wrong shape and would otherwise surface as a decoder error. +func requireHookMap(raw map[string]any, configPath string) error { + if configPath == "" { + configPath = "hooks" + } + names := make([]string, 0, len(raw)) + for name := range raw { + names = append(names, name) + } + slices.Sort(names) + for _, name := range names { + switch raw[name].(type) { + case map[string]any, map[any]any: + continue + } + cause := fmt.Errorf("%w: %s.%s must be a map of hook fields, not a list or a plain value", errUtils.ErrInvalidHooksSection, configPath, name) + return errUtils.Build(cause). + WithExplanationf("%s must be a map of hook name to hook definition, but %q is not a map.", configPath, name). + WithHintf("Write each hook under its own name, for example:\n%s:\n publish:\n kind: step\n events: [after.docs.generate]\n type: http", configPath). + WithContext("path", configPath). + Err() + } + return nil +} + +// SetOperationContext replaces the environment and template data exposed to hooks. Operations +// whose context changes over their lifecycle (for example an output path that is only known +// after generation) call it between events. +func (h *Hooks) SetOperationContext(op OperationContext) { + defer perf.Track(h.config, "hooks.Hooks.SetOperationContext")() + + h.operationEnv = maps.Clone(op.Env) + if h.sections == nil { + h.sections = map[string]any{} + } + if op.Type != "" { + h.sections[op.Type] = maps.Clone(op.Data) + } +} + +// RunOperation runs the hooks registered for event using the context the Hooks value was +// built with. Callers set the lifecycle result with SetOutcome first. +func (h *Hooks) RunOperation(event HookEvent, cmd *cobra.Command) error { + defer perf.Track(h.config, "hooks.Hooks.RunOperation")() + + return h.RunAll(event, h.config, h.info, cmd, nil) +} diff --git a/pkg/hooks/operation_docs.go b/pkg/hooks/operation_docs.go new file mode 100644 index 00000000000..e155abf8cd1 --- /dev/null +++ b/pkg/hooks/operation_docs.go @@ -0,0 +1,74 @@ +package hooks + +import ( + "github.com/cloudposse/atmos/pkg/docs" + "github.com/cloudposse/atmos/pkg/hooks/events" + "github.com/cloudposse/atmos/pkg/perf" +) + +// Docs generate operation identifiers shared by policy input, templates, and hook environment. +const ( + docsOperationType = "docs" + + // DocsTypeEnvVar, DocsOutputPathEnvVar, and DocsBaseDirEnvVar are exported to hooks that fire + // around `atmos docs generate`. + DocsTypeEnvVar = "ATMOS_DOCS_TYPE" + DocsOutputPathEnvVar = "ATMOS_DOCS_OUTPUT_PATH" + DocsBaseDirEnvVar = "ATMOS_DOCS_BASE_DIR" +) + +//nolint:gochecknoinits // registers the docs hook runner; pkg/docs cannot import this package without an import cycle. +func init() { + docs.RegisterHookRunnerFactory(newDocsHookRunner) +} + +// docsHookRunner adapts Hooks to the docs.HookRunner interface. +type docsHookRunner struct { + hooks *Hooks + req *docs.HookRunnerRequest +} + +// newDocsHookRunner builds the hooks declared under docs.generate..hooks, together with +// any governing policy, for one generation. +func newDocsHookRunner(req *docs.HookRunnerRequest) (docs.HookRunner, error) { + h, err := NewOperationHooks(req.AtmosConfig, req.Hooks, docsOperationContext(req)) + if err != nil { + return nil, err + } + return &docsHookRunner{hooks: h, req: req}, nil +} + +// Run fires event with the lifecycle result recorded, so hooks filter on `when`. +func (r *docsHookRunner) Run(event events.HookEvent, genErr error) error { + defer perf.Track(r.req.AtmosConfig, "hooks.docsHookRunner.Run")() + + if !r.hooks.HasHooks() { + return nil + } + outcome := Outcome{Status: RunSuccess} + if genErr != nil { + outcome = Outcome{Status: RunFailure, Err: genErr, ExitCode: 1} + } + r.hooks.SetOutcome(outcome) + return r.hooks.RunOperation(event, r.req.Cmd) +} + +// docsOperationContext exposes the document type, output path, and base directory to hooks as +// environment variables and as `.docs.*` template data. +func docsOperationContext(req *docs.HookRunnerRequest) OperationContext { + return OperationContext{ + Type: docsOperationType, + Name: req.DocType, + ConfigPath: "docs.generate." + req.DocType + ".hooks", + Env: map[string]string{ + DocsTypeEnvVar: req.DocType, + DocsOutputPathEnvVar: req.OutputPath, + DocsBaseDirEnvVar: req.BaseDir, + }, + Data: map[string]any{ + "type": req.DocType, + "output_path": req.OutputPath, + "base_dir": req.BaseDir, + }, + } +} diff --git a/pkg/hooks/operation_docs_test.go b/pkg/hooks/operation_docs_test.go new file mode 100644 index 00000000000..cfd2dd17a00 --- /dev/null +++ b/pkg/hooks/operation_docs_test.go @@ -0,0 +1,110 @@ +package hooks + +import ( + "os" + "path/filepath" + "testing" + + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + errUtils "github.com/cloudposse/atmos/errors" + "github.com/cloudposse/atmos/pkg/docs" + "github.com/cloudposse/atmos/pkg/schema" +) + +// docsGenerateFixture writes a template and returns a docs.generate entry that renders it into dir. +func docsGenerateFixture(t *testing.T, hooks map[string]any) *schema.DocsGenerate { + t.Helper() + dir := t.TempDir() + require.NoError(t, os.WriteFile(filepath.Join(dir, "README.md.gotmpl"), []byte("hello docs"), 0o600)) + return &schema.DocsGenerate{ + BaseDir: dir, + Template: "README.md.gotmpl", + Output: filepath.Join(dir, "README.md"), + Hooks: hooks, + } +} + +func TestGenerateWithHooksEndToEnd(t *testing.T) { + recorder, url := newRecorderServer(t) + dg := docsGenerateFixture(t, map[string]any{ + "before": httpStepHook(url+"/before/{{ .docs.type }}", map[string]any{"events": []any{"before.docs.generate"}}), + "after": httpStepHook(url+"/after", map[string]any{"events": []any{"after.docs.generate"}}), + }) + + require.NoError(t, docs.GenerateWithHooks(&schema.AtmosConfiguration{}, &cobra.Command{}, "readme", dg)) + + assert.Equal(t, []string{"/before/readme", "/after"}, recorder.seen()) + content, err := os.ReadFile(dg.Output) + require.NoError(t, err) + assert.Equal(t, "hello docs", string(content)) +} + +func TestGenerateWithHooksBeforeFailureWritesNothing(t *testing.T) { + exe, err := os.Executable() + require.NoError(t, err) + dg := docsGenerateFixture(t, map[string]any{ + "gate": map[string]any{ + "kind": "command", "command": exe, "events": []any{"before.docs.generate"}, + "env": map[string]any{"_ATMOS_TEST_EXIT_ONE": "1"}, "on_failure": OnFailureFail, + }, + }) + + require.Error(t, docs.GenerateWithHooks(&schema.AtmosConfiguration{}, &cobra.Command{}, "readme", dg)) + assert.NoFileExists(t, dg.Output) +} + +func TestGenerateWithHooksAfterRunsOnFailure(t *testing.T) { + recorder, url := newRecorderServer(t) + dg := docsGenerateFixture(t, map[string]any{ + "on-fail": httpStepHook(url+"/failure", map[string]any{"events": []any{"after.docs.generate"}, "when": "failure"}), + "on-success": httpStepHook(url+"/success", map[string]any{"events": []any{"after.docs.generate"}}), + "always": httpStepHook(url+"/always", map[string]any{"events": []any{"after.docs.generate"}, "when": "always"}), + }) + dg.Template = "missing.gotmpl" + + err := docs.GenerateWithHooks(&schema.AtmosConfiguration{}, &cobra.Command{}, "readme", dg) + require.Error(t, err) + assert.NoFileExists(t, dg.Output) + assert.ElementsMatch(t, []string{"/failure", "/always"}, recorder.seen()) +} + +func TestGenerateWithHooksPolicyDenialBlocksGeneration(t *testing.T) { + recorder, url := newRecorderServer(t) + t.Cleanup(func() { docs.RegisterHookRunnerFactory(newDocsHookRunner) }) + docs.RegisterHookRunnerFactory(func(req *docs.HookRunnerRequest) (docs.HookRunner, error) { + runner, err := newDocsHookRunner(req) + if err != nil { + return nil, err + } + runner.(*docsHookRunner).hooks = docsPolicyHooks(t, url, true) + return runner, nil + }) + dg := docsGenerateFixture(t, nil) + + err := docs.GenerateWithHooks(&schema.AtmosConfiguration{}, &cobra.Command{}, "readme", dg) + require.ErrorIs(t, err, errUtils.ErrPolicyDenied) + assert.NoFileExists(t, dg.Output) + assert.Empty(t, recorder.seen()) +} + +func TestGenerateWithHooksInvalidEventRejected(t *testing.T) { + dg := docsGenerateFixture(t, map[string]any{ + "bad": httpStepHook("http://127.0.0.1:1", map[string]any{"events": []any{"after.docs.publish"}}), + }) + err := docs.GenerateWithHooks(&schema.AtmosConfiguration{}, &cobra.Command{}, "readme", dg) + require.ErrorIs(t, err, errUtils.ErrUnsupportedHookEvent) + assert.NoFileExists(t, dg.Output, "invalid hook configuration must fail before generation") +} + +func TestDocsOperationContext(t *testing.T) { + op := docsOperationContext(&docs.HookRunnerRequest{DocType: "readme", BaseDir: "/base", OutputPath: "/base/README.md"}) + assert.Equal(t, "docs", op.Type) + assert.Equal(t, "readme", op.Name) + assert.Equal(t, map[string]string{ + "ATMOS_DOCS_TYPE": "readme", "ATMOS_DOCS_OUTPUT_PATH": "/base/README.md", "ATMOS_DOCS_BASE_DIR": "/base", + }, op.Env) + assert.Equal(t, "/base/README.md", op.Data["output_path"]) +} diff --git a/pkg/hooks/operation_test.go b/pkg/hooks/operation_test.go new file mode 100644 index 00000000000..945bf6b78a2 --- /dev/null +++ b/pkg/hooks/operation_test.go @@ -0,0 +1,489 @@ +package hooks + +import ( + "encoding/json" + "fmt" + "net/http" + "net/http/httptest" + "os" + "os/exec" + "path/filepath" + "sort" + "strings" + "sync" + "testing" + + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + errUtils "github.com/cloudposse/atmos/errors" + "github.com/cloudposse/atmos/pkg/policy" + "github.com/cloudposse/atmos/pkg/schema" +) + +// requestRecorder records the request paths an httptest server receives. +type requestRecorder struct { + mu sync.Mutex + paths []string +} + +func (r *requestRecorder) handler(w http.ResponseWriter, req *http.Request) { + r.mu.Lock() + defer r.mu.Unlock() + r.paths = append(r.paths, req.URL.Path) + w.WriteHeader(http.StatusNoContent) +} + +func (r *requestRecorder) seen() []string { + r.mu.Lock() + defer r.mu.Unlock() + return append([]string(nil), r.paths...) +} + +func newRecorderServer(t *testing.T) (*requestRecorder, string) { + t.Helper() + recorder := &requestRecorder{} + server := httptest.NewServer(http.HandlerFunc(recorder.handler)) + t.Cleanup(server.Close) + return recorder, server.URL +} + +func httpStepHook(url string, extra map[string]any) map[string]any { + hook := map[string]any{ + "kind": "step", "type": "http", + "with": map[string]any{"url": url, "method": "POST"}, + } + for k, v := range extra { + hook[k] = v + } + return hook +} + +func docsTestOperation() OperationContext { + return OperationContext{ + Type: "docs", Name: "readme", + Env: map[string]string{DocsTypeEnvVar: "readme", DocsOutputPathEnvVar: "/out/README.md"}, + Data: map[string]any{"type": "readme", "output_path": "/out/README.md"}, + } +} + +func TestNewOperationHooksDecodesAndValidates(t *testing.T) { + tests := []struct { + name string + raw map[string]any + wantErr error + items int + }{ + {name: "nil hooks", raw: nil, items: 0}, + {name: "valid hook", raw: map[string]any{"publish": httpStepHook("http://x", map[string]any{"events": []any{"after.docs.generate"}})}, items: 1}, + {name: "before event", raw: map[string]any{"pre": httpStepHook("http://x", map[string]any{"events": []any{"before.docs.generate"}})}, items: 1}, + {name: "unregistered event", raw: map[string]any{"bad": httpStepHook("http://x", map[string]any{"events": []any{"after.docs.publish"}})}, wantErr: errUtils.ErrUnsupportedHookEvent}, + {name: "malformed hook", raw: map[string]any{"bad": "not-a-map"}, wantErr: errUtils.ErrInvalidHooksSection}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + h, err := NewOperationHooks(&schema.AtmosConfiguration{}, tt.raw, docsTestOperation()) + if tt.wantErr != nil { + require.ErrorIs(t, err, tt.wantErr) + assert.Nil(t, h) + return + } + require.NoError(t, err) + assert.Len(t, h.items, tt.items) + assert.Equal(t, "docs", h.info.ComponentType) + assert.Equal(t, "readme", h.info.ComponentFromArg) + assert.Empty(t, h.info.Stack) + }) + } +} + +func TestOperationHooksRunsOnlyMatchingEvent(t *testing.T) { + recorder, url := newRecorderServer(t) + raw := map[string]any{ + "before-hook": httpStepHook(url+"/before", map[string]any{"events": []any{"before.docs.generate"}}), + "after-hook": httpStepHook(url+"/after", map[string]any{"events": []any{"after.docs.generate"}}), + // Hooks for another operation must never fire for docs events (negative path). + "other-hook": httpStepHook(url+"/other", map[string]any{"events": []any{"after.terraform.apply"}}), + } + h, err := NewOperationHooks(&schema.AtmosConfiguration{}, raw, docsTestOperation()) + require.NoError(t, err) + + require.NoError(t, h.RunOperation(BeforeDocsGenerate, nil)) + assert.Equal(t, []string{"/before"}, recorder.seen()) + + require.NoError(t, h.RunOperation(AfterDocsGenerate, nil)) + assert.Equal(t, []string{"/before", "/after"}, recorder.seen()) +} + +func TestOperationHooksFilterByOutcome(t *testing.T) { + tests := []struct { + name string + when any + outcome Outcome + fires bool + }{ + {name: "default runs on success", when: nil, outcome: Outcome{Status: RunSuccess}, fires: true}, + {name: "default skipped on failure", when: nil, outcome: Outcome{Status: RunFailure, ExitCode: 1}, fires: false}, + {name: "failure runs on failure", when: "failure", outcome: Outcome{Status: RunFailure, ExitCode: 1}, fires: true}, + {name: "failure skipped on success", when: "failure", outcome: Outcome{Status: RunSuccess}, fires: false}, + {name: "always runs on failure", when: "always", outcome: Outcome{Status: RunFailure, ExitCode: 1}, fires: true}, + {name: "always runs on success", when: "always", outcome: Outcome{Status: RunSuccess}, fires: true}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + recorder, url := newRecorderServer(t) + extra := map[string]any{"events": []any{"after.docs.generate"}} + if tt.when != nil { + extra["when"] = tt.when + } + h, err := NewOperationHooks(&schema.AtmosConfiguration{}, map[string]any{"notify": httpStepHook(url+"/notify", extra)}, docsTestOperation()) + require.NoError(t, err) + h.SetOutcome(tt.outcome) + require.NoError(t, h.RunOperation(AfterDocsGenerate, nil)) + if tt.fires { + assert.Equal(t, []string{"/notify"}, recorder.seen()) + } else { + assert.Empty(t, recorder.seen()) + } + }) + } +} + +func TestOperationHooksSkipHooksFlag(t *testing.T) { + recorder, url := newRecorderServer(t) + raw := map[string]any{ + "skipped": httpStepHook(url+"/skipped", map[string]any{"events": []any{"after.docs.generate"}}), + "kept": httpStepHook(url+"/kept", map[string]any{"events": []any{"after.docs.generate"}}), + } + h, err := NewOperationHooks(&schema.AtmosConfiguration{}, raw, docsTestOperation()) + require.NoError(t, err) + + cmd := &cobra.Command{} + cmd.Flags().String("skip-hooks", "", "") + require.NoError(t, cmd.Flags().Set("skip-hooks", "skipped")) + require.NoError(t, h.RunOperation(AfterDocsGenerate, cmd)) + assert.Equal(t, []string{"/kept"}, recorder.seen()) + + require.NoError(t, cmd.Flags().Set("skip-hooks", "*")) + require.NoError(t, h.RunOperation(AfterDocsGenerate, cmd)) + assert.Equal(t, []string{"/kept"}, recorder.seen(), "skip-hooks=* skips every user hook") +} + +func TestOperationHooksFailureHonorsOnFailure(t *testing.T) { + exe, err := os.Executable() + require.NoError(t, err) + failing := func(onFailure string) map[string]any { + return map[string]any{ + "kind": "command", "command": exe, "events": []any{"before.docs.generate"}, + "env": map[string]any{"_ATMOS_TEST_EXIT_ONE": "1"}, "on_failure": onFailure, + } + } + tests := []struct { + name string + onFailure string + wantErr bool + }{ + {name: "fail propagates", onFailure: OnFailureFail, wantErr: true}, + {name: "warn is swallowed", onFailure: OnFailureWarn, wantErr: false}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + h, err := NewOperationHooks(&schema.AtmosConfiguration{}, map[string]any{"gate": failing(tt.onFailure)}, docsTestOperation()) + require.NoError(t, err) + err = h.RunOperation(BeforeDocsGenerate, nil) + if tt.wantErr { + require.Error(t, err) + return + } + require.NoError(t, err) + }) + } +} + +func TestOperationHooksTemplateData(t *testing.T) { + recorder, url := newRecorderServer(t) + raw := map[string]any{"publish": httpStepHook(url, map[string]any{"events": []any{"after.docs.generate"}})} + raw["publish"].(map[string]any)["with"] = map[string]any{"url": url + "/{{ .docs.type }}", "method": "POST"} + h, err := NewOperationHooks(&schema.AtmosConfiguration{}, raw, docsTestOperation()) + require.NoError(t, err) + require.NoError(t, h.RunOperation(AfterDocsGenerate, nil)) + assert.Equal(t, []string{"/readme"}, recorder.seen()) + + // SetOperationContext replaces the data exposed to templates. + h.SetOperationContext(OperationContext{Type: "docs", Data: map[string]any{"type": "changelog"}}) + require.NoError(t, h.RunOperation(AfterDocsGenerate, nil)) + assert.Equal(t, []string{"/readme", "/changelog"}, recorder.seen()) +} + +func TestOperationHooksExportEnvironment(t *testing.T) { + h, err := NewOperationHooks(&schema.AtmosConfiguration{}, nil, docsTestOperation()) + require.NoError(t, err) + assert.Equal(t, "/out/README.md", h.operationEnv[DocsOutputPathEnvVar]) + + ctx := &ExecContext{OperationEnv: h.operationEnv, Info: h.info} + env := buildAtmosEnv(ctx, "", "") + assert.Equal(t, "readme", env[DocsTypeEnvVar]) + assert.Equal(t, "/out/README.md", env[DocsOutputPathEnvVar]) + assert.Equal(t, "readme", env["ATMOS_COMPONENT"]) + assert.Empty(t, env["ATMOS_STACK"]) + + // Component lifecycles carry no operation variables. + plain := buildAtmosEnv(&ExecContext{Info: &schema.ConfigAndStacksInfo{}}, "", "") + assert.NotContains(t, plain, DocsTypeEnvVar) +} + +// docsPolicyHooks attaches a governing policy requiring a callback hook for event. +func docsPolicyHooks(t *testing.T, url string, deny bool) *Hooks { + t.Helper() + event := BeforeDocsGenerate + definition, err := json.Marshal(map[string]any{"kind": "step", "type": "http", "with": map[string]any{"url": url + "/policy", "method": "POST"}}) + require.NoError(t, err) + h, err := NewOperationHooks(&schema.AtmosConfiguration{}, nil, docsTestOperation()) + require.NoError(t, err) + rules := []policy.Rule{{ + ID: "docs-callback", On: policy.Operation, Engine: policy.CELEngine, + Expression: "input.event == '" + string(event) + "' && input.component_type == 'docs' && input.component == 'readme' && input.stack == ''", + Effects: policy.Effects{Hooks: []policy.HookRequirement{ + {Ref: "test/callback", Event: string(event), Required: true, RequireSuccess: true}, + }}, + }} + if deny { + rules = append(rules, policy.Rule{ID: "deny", On: policy.Operation, Engine: policy.CELEngine, Expression: "true", Effects: policy.Effects{Deny: true}}) + } + h.policyBundle = &policy.Bundle{Hooks: map[string]json.RawMessage{"test/callback": definition}, Rules: rules} + return h +} + +func TestOperationPolicyMatchSelectorOnStacklessDocsOperation(t *testing.T) { + recorder, url := newRecorderServer(t) + h := docsPolicyHooks(t, url, false) + h.policyBundle.Rules[0].Match = &policy.Selector{Components: []string{"readme"}, ComponentTypes: []string{"docs"}} + + require.NoError(t, h.RunOperation(BeforeDocsGenerate, nil)) + assert.Equal(t, []string{"/policy"}, recorder.seen(), "a matching selector must attach the rule") + + // Negative path: a selector that does not match the generator excludes the rule without erroring. + recorder, url = newRecorderServer(t) + h = docsPolicyHooks(t, url, false) + h.policyBundle.Rules[0].Match = &policy.Selector{Components: []string{"release-notes"}} + require.NoError(t, h.RunOperation(BeforeDocsGenerate, nil)) + assert.Empty(t, recorder.seen()) +} + +func TestOperationPolicyHooksFireOnDocsEvents(t *testing.T) { + recorder, url := newRecorderServer(t) + h := docsPolicyHooks(t, url, false) + assert.True(t, h.HasHooks(), "a governing policy counts as hooks even with no user hooks") + + // Policy input carries the docs operation with an empty stack. + require.NoError(t, h.RunOperation(BeforeDocsGenerate, nil)) + assert.Equal(t, []string{"/policy"}, recorder.seen()) + + // The rule targets the before event only (negative path). + require.NoError(t, h.RunOperation(AfterDocsGenerate, nil)) + assert.Equal(t, []string{"/policy"}, recorder.seen()) +} + +func TestOperationPolicyDenialBlocks(t *testing.T) { + recorder, url := newRecorderServer(t) + h := docsPolicyHooks(t, url, true) + require.ErrorIs(t, h.RunOperation(BeforeDocsGenerate, nil), errUtils.ErrPolicyDenied) + assert.Empty(t, recorder.seen(), "a denial must prevent policy hooks from running") +} + +func TestOperationPolicyRequestToleratesEmptyStack(t *testing.T) { + run := &hookRunContext{ + event: BeforeDocsGenerate, + info: &schema.ConfigAndStacksInfo{ComponentType: "docs", ComponentFromArg: "readme"}, + } + request, err := operationPolicyRequest(run, nil) + require.NoError(t, err) + var input policy.OperationInput + require.NoError(t, json.Unmarshal(request.Input, &input)) + assert.Equal(t, policy.OperationInput{Event: "before.docs.generate", ComponentType: "docs", Command: "generate", Component: "readme", Stack: "", Status: ""}, input) +} + +// docsEnvOperation returns an operation whose environment the dump hook must observe. +func docsEnvOperation() OperationContext { + return OperationContext{ + Type: "docs", Name: "readme", + Env: map[string]string{ + DocsTypeEnvVar: "readme", DocsOutputPathEnvVar: "/out/README.md", DocsBaseDirEnvVar: "/base", + }, + Data: map[string]any{"type": "readme"}, + } +} + +func readDump(t *testing.T, path string) []string { + t.Helper() + data, err := os.ReadFile(path) + require.NoError(t, err) + return strings.Split(string(data), "\n") +} + +func TestOperationEnvReachesCommandHookSubprocess(t *testing.T) { + exe, err := os.Executable() + require.NoError(t, err) + want := []string{"readme", "/out/README.md", "/base"} + + t.Run("user hook", func(t *testing.T) { + dump := filepath.Join(t.TempDir(), "env.txt") + raw := map[string]any{"dump": map[string]any{ + "kind": "command", "command": exe, "events": []any{"after.docs.generate"}, + "env": map[string]any{"_ATMOS_TEST_DUMP_DOCS_ENV": dump}, "on_failure": OnFailureFail, + }} + h, err := NewOperationHooks(&schema.AtmosConfiguration{}, raw, docsEnvOperation()) + require.NoError(t, err) + require.NoError(t, h.RunOperation(AfterDocsGenerate, nil)) + assert.Equal(t, want, readDump(t, dump)) + }) + + t.Run("policy hook", func(t *testing.T) { + dump := filepath.Join(t.TempDir(), "env.txt") + definition, err := json.Marshal(map[string]any{ + "kind": "command", "command": exe, "env": map[string]any{"_ATMOS_TEST_DUMP_DOCS_ENV": dump}, + }) + require.NoError(t, err) + h, err := NewOperationHooks(&schema.AtmosConfiguration{}, nil, docsEnvOperation()) + require.NoError(t, err) + h.policyBundle = &policy.Bundle{ + Hooks: map[string]json.RawMessage{"test/callback": definition}, + Rules: []policy.Rule{{ + ID: "cb", On: policy.Operation, Engine: policy.CELEngine, Expression: "true", + Effects: policy.Effects{Hooks: []policy.HookRequirement{{Ref: "test/callback", Event: string(AfterDocsGenerate), Required: true, RequireSuccess: true}}}, + }}, + } + require.NoError(t, h.RunOperation(AfterDocsGenerate, nil)) + assert.Equal(t, want, readDump(t, dump)) + }) +} + +func TestOperationHooksRunInSortedNameOrder(t *testing.T) { + recorder, url := newRecorderServer(t) + raw := map[string]any{} + var names []string + for i := 0; i < 25; i++ { + name := fmt.Sprintf("hook-%02d", 24-i) // Declared in reverse so source order cannot pass by accident. + names = append(names, name) + raw[name] = httpStepHook(url+"/"+name, map[string]any{"events": []any{"after.docs.generate"}}) + } + sort.Strings(names) + h, err := NewOperationHooks(&schema.AtmosConfiguration{}, raw, docsTestOperation()) + require.NoError(t, err) + + for run := 0; run < 5; run++ { + before := len(recorder.seen()) + require.NoError(t, h.RunOperation(AfterDocsGenerate, nil)) + got := recorder.seen()[before:] + require.Len(t, got, len(names)) + assert.Equal(t, "/"+names[0], got[0]) + assert.Equal(t, "/"+names[len(names)-1], got[len(got)-1]) + for i, name := range names { + require.Equal(t, "/"+name, got[i], "run %d position %d", run, i) + } + } +} + +func TestOperationHookFailureNamesHookAndKeepsExitCode(t *testing.T) { + exe, err := os.Executable() + require.NoError(t, err) + raw := map[string]any{"publish-wiki": map[string]any{ + "kind": "command", "command": exe, "events": []any{"after.docs.generate"}, + "env": map[string]any{"_ATMOS_TEST_EXIT_CODE": "3"}, "on_failure": OnFailureFail, + }} + h, err := NewOperationHooks(&schema.AtmosConfiguration{}, raw, docsTestOperation()) + require.NoError(t, err) + + err = h.RunOperation(AfterDocsGenerate, nil) + + require.Error(t, err) + assert.Contains(t, err.Error(), "publish-wiki") + assert.Contains(t, err.Error(), "after.docs.generate") + var exitErr *exec.ExitError + require.ErrorAs(t, err, &exitErr) + assert.Equal(t, 3, exitErr.ExitCode()) +} + +func TestMissingHookBinaryHintIsOperationAware(t *testing.T) { + raw := map[string]any{"publish": map[string]any{ + "kind": "command", "command": "atmos-test-no-such-binary", "events": []any{"after.docs.generate"}, + }} + h, err := NewOperationHooks(&schema.AtmosConfiguration{}, raw, docsTestOperation()) + require.NoError(t, err) + + err = h.RunOperation(AfterDocsGenerate, nil) + + require.Error(t, err) + hints := strings.ToLower(strings.Join(errUtils.AllHints(err), "\n")) + assert.NotEmpty(t, hints) + assert.NotContains(t, hints, "terraform") + assert.NotContains(t, hints, "dependencies.tools", "operations have no component dependencies section") +} + +func TestOperationHooksNonMapHooksGetClearError(t *testing.T) { + op := docsTestOperation() + op.ConfigPath = "docs.generate.readme.hooks" + raw := map[string]any{"publish": []any{map[string]any{"kind": "command"}}, "other": "text"} + + h, err := NewOperationHooks(&schema.AtmosConfiguration{}, raw, op) + + require.ErrorIs(t, err, errUtils.ErrInvalidHooksSection) + assert.Nil(t, h) + assert.Contains(t, err.Error(), "docs.generate.readme.hooks") + assert.Contains(t, err.Error(), "docs.generate.readme.hooks.other", "the first offending entry in name order is named") + hints := strings.Join(errUtils.AllHints(err), "\n") + assert.Contains(t, hints, "kind: step") + for _, leaked := range []string{"hookAlias", "hooks.Hook", "cannot unmarshal"} { + assert.NotContains(t, err.Error(), leaked) + assert.NotContains(t, hints, leaked) + } +} + +func TestOperationHooksValidatedAtConstruction(t *testing.T) { + tests := []struct { + name string + hook map[string]any + wantErr bool + contain []string + }{ + {name: "step missing required field", hook: map[string]any{"kind": "step", "type": "http", "events": []any{"after.docs.generate"}, "with": map[string]any{"method": "POST"}}, wantErr: true, contain: []string{"publish", "url"}}, + {name: "unknown kind", hook: map[string]any{"kind": "no-such-kind", "events": []any{"after.docs.generate"}}, wantErr: true, contain: []string{"publish", "no-such-kind"}}, + {name: "unknown step type", hook: map[string]any{"kind": "step", "type": "no-such-step", "events": []any{"after.docs.generate"}}, wantErr: true, contain: []string{"publish", "no-such-step"}}, + {name: "valid step with templated field", hook: map[string]any{"kind": "step", "type": "http", "events": []any{"after.docs.generate"}, "with": map[string]any{"url": "http://x/{{ .docs.type }}"}}}, + {name: "valid command", hook: map[string]any{"kind": "command", "command": "some-tool", "events": []any{"after.docs.generate"}}}, + {name: "valid steps", hook: map[string]any{"kind": "steps", "events": []any{"after.docs.generate"}, "with": []any{map[string]any{"type": "http", "url": "http://x"}}}}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + h, err := NewOperationHooks(&schema.AtmosConfiguration{}, map[string]any{"publish": tt.hook}, docsTestOperation()) + if !tt.wantErr { + require.NoError(t, err) + assert.NotNil(t, h) + return + } + require.Error(t, err) + assert.Nil(t, h) + full := err.Error() + "\n" + strings.Join(errUtils.AllHints(err), "\n") + for _, want := range tt.contain { + assert.Contains(t, full, want) + } + }) + } +} + +func TestForeignOperationEvents(t *testing.T) { + items := map[string]Hook{ + "ok": {Events: []string{"before.docs.generate", "after.docs.generate"}}, + "foreign": {Events: []string{"after.terraform.apply", "after.docs.generate"}}, + "empty": {}, + } + got := foreignOperationEvents(items, "docs") + assert.Equal(t, map[string][]string{"foreign": {"after.terraform.apply"}}, got) + + // Declaring a foreign event is valid: construction succeeds. + _, err := NewOperationHooks(&schema.AtmosConfiguration{}, map[string]any{ + "foreign": map[string]any{"kind": "command", "command": "tool", "events": []any{"after.terraform.apply"}}, + }, docsTestOperation()) + require.NoError(t, err) +} diff --git a/pkg/hooks/policy.go b/pkg/hooks/policy.go index 217e48aad9f..025aeac9209 100644 --- a/pkg/hooks/policy.go +++ b/pkg/hooks/policy.go @@ -23,17 +23,10 @@ import ( func getGovernedHooks(config *schema.AtmosConfiguration, info *schema.ConfigAndStacksInfo) (*Hooks, error) { // Resolve governing data before describing (potentially untrusted) component data. - var snapshot *policy.CISnapshot - bundle, err := admission.LoadBundle() + bundle, snapshot, err := loadPolicyGovernance() if err != nil { return nil, err } - if bundle != nil { - snapshot, err = ci.CollectPolicySnapshot(context.Background()) - if err != nil { - return nil, err - } - } h, err := getComponentHooks(config, info) if err != nil { return nil, err @@ -42,6 +35,23 @@ func getGovernedHooks(config *schema.AtmosConfiguration, info *schema.ConfigAndS return h, nil } +// loadPolicyGovernance loads the governing policy bundle and, when one exists, the CI snapshot +// policy evaluation needs. A nil bundle means no policy governs the operation. +func loadPolicyGovernance() (*policy.Bundle, *policy.CISnapshot, error) { + bundle, err := admission.LoadBundle() + if err != nil { + return nil, nil, err + } + if bundle == nil { + return nil, nil, nil + } + snapshot, err := ci.CollectPolicySnapshot(context.Background()) + if err != nil { + return nil, nil, err + } + return bundle, snapshot, nil +} + func (h *Hooks) runPolicyHooks(run *hookRunContext) error { if h.policyBundle == nil { return nil @@ -70,6 +80,8 @@ func (h *Hooks) runPolicyHooks(run *hookRunContext) error { if err != nil { return err } + // Operations such as `atmos docs generate` have no stack; selectors must still evaluate. + request.Subject.Stackless = h.operation && run.info.Stack == "" } engine := admission.NewEngine() decision, err := engine.Evaluate(ctx, request, h.policyBundle.Rules) diff --git a/pkg/policy/selector.go b/pkg/policy/selector.go index 5d9bf582489..f0e451d2b56 100644 --- a/pkg/policy/selector.go +++ b/pkg/policy/selector.go @@ -17,6 +17,9 @@ type Subject struct { Metadata SubjectMetadata `json:"metadata"` // TemplateLeft identifies unresolved metadata under a configured delimiter. TemplateLeft string `json:"template_left,omitempty"` + // Stackless marks a subject that is an operation (such as `atmos docs generate`) with no stack. + // Selectors on stack, tags, and labels still evaluate; an empty stack is not an error. + Stackless bool `json:"stackless,omitempty"` } // SubjectMetadata contains only data used for attachment, never executable configuration. @@ -105,7 +108,7 @@ func (s *Selector) Matches(subject *Subject) (bool, error) { } func validateSubject(subject *Subject) error { - if subject == nil || subject.Name == "" || subject.Stack == "" || subject.ComponentType == "" { + if subject == nil || subject.Name == "" || (subject.Stack == "" && !subject.Stackless) || subject.ComponentType == "" { return fmt.Errorf("%w: attachment requires an instance identity and metadata", errUtils.ErrPolicyInputUnavailable) } if unresolvedMetadata(subject.Metadata, subject.TemplateLeft) { diff --git a/pkg/policy/selector_test.go b/pkg/policy/selector_test.go index 344442d5b94..cc58eaf0e6c 100644 --- a/pkg/policy/selector_test.go +++ b/pkg/policy/selector_test.go @@ -162,3 +162,26 @@ func TestSelectorRejectsValuesInTheConfiguredDelimiter(t *testing.T) { require.NoError(t, err) require.True(t, matched) } + +func TestSelectorStacklessSubject(t *testing.T) { + identity := ObjectIdentity{Name: "readme", ComponentType: "docs"} + + t.Run("stackless operation subject evaluates selectors", func(t *testing.T) { + subject, err := NewSubject(identity, nil) + require.NoError(t, err) + subject.Stackless = true + matched, err := (&Selector{Components: []string{"readme"}, ComponentTypes: []string{"docs"}}).Matches(subject) + require.NoError(t, err) + require.True(t, matched) + matched, err = (&Selector{Stacks: []string{"prod"}}).Matches(subject) + require.NoError(t, err) + require.False(t, matched) + }) + + t.Run("an empty stack is still rejected for ordinary subjects", func(t *testing.T) { + subject, err := NewSubject(identity, nil) + require.NoError(t, err) + _, err = (&Selector{Components: []string{"readme"}}).Matches(subject) + require.ErrorIs(t, err, errUtils.ErrPolicyInputUnavailable) + }) +} diff --git a/pkg/schema/schema.go b/pkg/schema/schema.go index aa820039a15..1a1cad77187 100644 --- a/pkg/schema/schema.go +++ b/pkg/schema/schema.go @@ -1923,6 +1923,9 @@ type DocsGenerate struct { Template string `yaml:"template,omitempty" json:"template,omitempty" mapstructure:"template"` Output string `yaml:"output,omitempty" json:"output,omitempty" mapstructure:"output"` Terraform TerraformDocsReadmeSettings `yaml:"terraform,omitempty" json:"terraform,omitempty" mapstructure:"terraform"` + // Hooks declares lifecycle hooks (before.docs.generate / after.docs.generate) for this doc type. + // The map is decoded into hook definitions by pkg/hooks, which schema cannot import. + Hooks map[string]any `yaml:"hooks,omitempty" json:"hooks,omitempty" mapstructure:"hooks"` } type ArgsAndFlagsInfo struct { diff --git a/website/blog/2026-11-17-docs-generate-hooks.mdx b/website/blog/2026-11-17-docs-generate-hooks.mdx new file mode 100644 index 00000000000..76b003f210f --- /dev/null +++ b/website/blog/2026-11-17-docs-generate-hooks.mdx @@ -0,0 +1,70 @@ +--- +slug: docs-generate-hooks +title: "Publish Generated Docs Anywhere With docs generate Hooks" +authors: [osterman] +tags: [feature] +--- + +Generating a README is the easy half. The harder half is getting it where people actually read it. A common request is to keep the README and docs in the repository as the source of truth, and publish a copy to Confluence for the people who live there. Others want a documentation portal or a bucket behind a static site. Most teams end up with a shell script or a CI job that runs after the generator, has to know where the output landed, and quietly drifts out of sync with the generator it follows. + +Documentation generation in Atmos now has lifecycle hooks, so the publishing step lives right next to the generator it belongs to. + + + +## The Problem + +Once a document is generated, something has to move it. In practice that something is glue: + +- A wrapper script that calls the generator and then calls `curl`, and has to be kept in sync with the generator's output path. +- A CI step that assumes the generator already ran, so running the same thing locally means remembering two commands. +- No clean way to say "never publish if generation failed" or "post a note even when it did." +- No way for a platform team to require a publishing or review step for every generated document without editing every repository's scripts. + +## The Fix + +Hooks can now run before and after `atmos docs generate`. You declare them under the generator in `atmos.yaml`, using the same hook kinds you already use around Terraform and other component operations, so a step you run in a workflow works here unchanged. + +Two new events, `before.docs.generate` and `after.docs.generate`, mark the edges. A before-hook that fails stops the command before any file is written. An after-hook runs after the generation attempt, so a failure hook must not assume a new file was written, and its `when:` setting decides whether it runs on success, on failure, or both. Steps receive the document type, the output path, and the base directory, so a hook never has to parse configuration to find the file it is supposed to publish. + +Governing policies reach documentation generation too. A rule with `on: operation` and `action: hooks` can require a hook for a specific generator, or block generation on the before-event, exactly as it does for component operations. + +## How to Use It + +Publishing to Confluence, or any wiki with a REST API, is a generic HTTP request. This example updates a Confluence page after the README is generated: + +```yaml +docs: + generate: + readme: + input: + - "./README.yaml" + template: "./README.md.gotmpl" + output: "./README.md" + hooks: + publish-wiki: + kind: step + type: http + events: [after.docs.generate] + when: success + with: + url: "https://example.atlassian.net/wiki/rest/api/content/123456" + method: PUT + headers: + Authorization: "Bearer {{ .env.WIKI_TOKEN }}" + Content-Type: application/json + body: '{"id": "123456", "type": "page", "title": "README", "version": {"number": 2}, "body": {"storage": {"value": "

Generated by Atmos

", "representation": "storage"}}}' +``` + +Run it the way you always have: + +```shell +atmos docs generate readme +``` + +Confluence expects the next version number of the page and content in its storage format, so a real publish usually converts the generated file first. A `command` hook that runs a small script reading the output path does that cleanly. Use `--skip-hooks` to generate without publishing, for example while iterating on a template. Atmos has nothing Confluence-specific built in: any service with an HTTP API, or any command you can run, can be a destination. + +See [`atmos docs generate`](/cli/commands/docs/generate#hooks) for ordering, failure handling, and the full list of values hooks receive, and the [hooks reference](/stacks/hooks) for the hook kinds you can use. + +## Get Involved + +If you publish generated documentation somewhere and a hook doesn't cover your case, open an issue on [GitHub](https://github.com/cloudposse/atmos/issues) and tell us what the hook needed to know. diff --git a/website/docs/cli/commands/docs/docs-generate.mdx b/website/docs/cli/commands/docs/docs-generate.mdx index 459526e3e78..52822015180 100644 --- a/website/docs/cli/commands/docs/docs-generate.mdx +++ b/website/docs/cli/commands/docs/docs-generate.mdx @@ -233,3 +233,112 @@ It supports the following local file sources: To download remote files, Atmos uses [`go-getter`](https://github.com/hashicorp/go-getter) (used by [Terraform](https://www.terraform.io/) for downloading modules) + +## Examples + +```shell +# Generate the README +atmos docs generate readme + +# Generate it without running any hooks +atmos docs generate readme --skip-hooks + +# Skip one hook by name +atmos docs generate readme --skip-hooks=publish-wiki +``` + +## Arguments + +
+
``
+
The name of a section under `docs.generate` in `atmos.yaml`, such as `readme` or `release-notes`.
+
+ +## Flags + +
+
`--skip-hooks`
+
Skip all lifecycle hooks for this run, or pass `--skip-hooks=[,]` to skip specific hooks by name. Also available as the `ATMOS_SKIP_HOOKS` environment variable. Hooks that a governing [policy](/policies/hooks) marks `required` cannot be skipped.
+
+ +## Hooks + +Generated documentation often needs to go somewhere else: a wiki, a documentation portal, a +bucket, a chat channel. Declare `hooks` under the generator that produces the document and Atmos +runs them around generation, using the same [hook kinds and fields](/stacks/hooks) as component +hooks. The events are `before.docs.generate` and `after.docs.generate`. + +```yaml +docs: + generate: + readme: + input: + - "./README.yaml" + template: "./README.md.gotmpl" + output: "./README.md" + hooks: + publish-wiki: + kind: step + type: http + events: [after.docs.generate] + when: success + on_failure: fail + with: + url: "https://example.atlassian.net/wiki/rest/api/content/123456" + method: PUT + headers: + Authorization: "Bearer {{ .env.WIKI_TOKEN }}" + Content-Type: application/json + body: '{"id": "123456", "type": "page", "title": "README", "version": {"number": 2}, "body": {"storage": {"value": "

Generated by Atmos

", "representation": "storage"}}}' + expect: + status: [200] +``` + +The example uses the generic [`http` step](/steps/type/http) against a wiki's REST API. Atmos has +no wiki-specific feature; any service that accepts an HTTP request works the same way. To send the +generated file's contents instead of fixed text, use a `kind: command` hook or a +[`script` step](/steps/type/script) that reads `ATMOS_DOCS_OUTPUT_PATH`. + +### Ordering and failure + +1. `before.docs.generate` hooks run first. A before-hook with `on_failure: fail`, or a policy + denial, aborts the command before any file is written. The default is `on_failure: warn`, and + with `warn` or `ignore` generation continues, so set `on_failure: fail` on any hook that must + block generation. +2. The document is generated. +3. `after.docs.generate` hooks run with the outcome. By default an after-hook runs only on success; + set `when: failure` or `when: always` to run it on failure too. See + [reacting to success or failure](/stacks/hooks#reacting-to-success-or-failure). +4. If generation succeeded and an after-hook fails, the command fails only when that hook sets + `on_failure: fail`. With the default `warn`, or with `ignore`, the command still succeeds. + +A hook with no `events` list runs on both events. Hooks belong to one generator: hooks under +`readme` do not run for `release-notes`. + +Within one event, hooks run in order of hook name. Hooks run in the process working directory (the +directory where `atmos docs generate` starts, or the `--chdir` target) rather than `base-dir`. Use +`ATMOS_DOCS_BASE_DIR` or `ATMOS_DOCS_OUTPUT_PATH` to reach the generator's files. + +### Hook context + +
+
`ATMOS_DOCS_TYPE`
+
The generator name, such as `readme`.
+ +
`ATMOS_DOCS_OUTPUT_PATH`
+
The resolved path of the generated file.
+ +
`ATMOS_DOCS_BASE_DIR`
+
The resolved base directory of the generator.
+
+ +Step templates can use the same values as `{{ .docs.type }}`, `{{ .docs.output_path }}`, and +`{{ .docs.base_dir }}`. Documentation hooks have no infrastructure component or stack: the stack is empty, and +`ATMOS_COMPONENT` holds the generator name (for example `readme`). + +### Policy + +A governing policy with `on: operation` and `action: hooks` applies to documentation generation +too. The operation input has `component_type: docs`, `command: generate`, the generator name as +`component`, and no `stack`. See [Policy-Driven Hooks](/policies/hooks) and +[operation input](/policies/inputs#operation-input). diff --git a/website/docs/cli/configuration/ci/comments.mdx b/website/docs/cli/configuration/ci/comments.mdx index 7a583a3bd5e..bbc7b1cef6c 100644 --- a/website/docs/cli/configuration/ci/comments.mdx +++ b/website/docs/cli/configuration/ci/comments.mdx @@ -60,6 +60,14 @@ The [`ci.comment`](/functions/automation/ci.comment) function in a script takes example) comments on the commit. Commit comments need the `contents: write` permission instead of `pull-requests: write`. Both kinds are gated by `ci.comments.enabled`. +## Link to the full run + +When the CI provider reports a run URL (GitHub Actions, Gitea Actions, or `ATMOS_CI_RUN_URL`, `CI_JOB_URL`, or +`BUILD_URL` for other systems), each Terraform plan comment ends with a "View full run" link to the run, whose job +summary and logs hold the complete output. GitHub limits a comment to 65,536 bytes; when a plan comment exceeds it, Atmos +truncates the body and the truncation notice at the top of the comment links to the run as well. Without a run URL, the +comment is unchanged. + ## Container image comments The `atmos container build` and `atmos container push` commands post one image summary comment per diff --git a/website/docs/cli/configuration/docs.mdx b/website/docs/cli/configuration/docs.mdx index 4134e831837..909249400d4 100644 --- a/website/docs/cli/configuration/docs.mdx +++ b/website/docs/cli/configuration/docs.mdx @@ -66,6 +66,9 @@ Each named section under `docs.generate` supports the following options:
`terraform`
Optional terraform-docs configuration for including Terraform documentation in the output.
+ +
`hooks`
+
Optional map of lifecycle hooks that run around generation, on the `before.docs.generate` and `after.docs.generate` events. Hooks use the same kinds and fields as [component hooks](/stacks/hooks); see [Hooks](#hooks).
### Terraform Documentation Options @@ -111,6 +114,36 @@ Visibility, `hide_empty`, and `indent_level` settings are honored for unpinned projects and editions on or after `2026-10-17`. Earlier edition pins retain the legacy formatter behavior, which ignored these settings. +## Hooks + +Declare `hooks` under a generator to run steps or commands before and after it generates, for +example to publish the result to a wiki. Each hook has the same fields as a +[component hook](/stacks/hooks), and its `events` must be `before.docs.generate` or +`after.docs.generate`: + + +```yaml +docs: + generate: + readme: + input: + - "./README.yaml" + template: "./README.md.gotmpl" + output: "./README.md" + hooks: + announce: + kind: step + type: log + events: [after.docs.generate] + with: + content: "Generated {{ .docs.output_path }}" +``` + + +Hook steps receive `ATMOS_DOCS_TYPE`, `ATMOS_DOCS_OUTPUT_PATH`, and `ATMOS_DOCS_BASE_DIR`. See +[`atmos docs generate`](/cli/commands/docs/generate#hooks) for ordering, failure handling, an +`http` step example, and policy support. + ## Multiple Documentation Generators You can define as many documentation generators as needed. Each top-level key under `docs.generate` becomes a CLI argument: diff --git a/website/docs/policies/hooks.mdx b/website/docs/policies/hooks.mdx index 74312625bb7..617ade465cc 100644 --- a/website/docs/policies/hooks.mdx +++ b/website/docs/policies/hooks.mdx @@ -46,6 +46,11 @@ atmos terraform plan vpc -s dev The hook runs after a successful plan, including a detailed exit code of `2`. A failing TFLint process fails the command. `--skip-hooks` cannot skip this required hook. +Policies also apply to `atmos docs generate`. Its events are `before.docs.generate` and +`after.docs.generate`, the operation input has `component_type: docs` and no stack, and the +`component` is the generator name. Rules may use `match` selectors such as `components` or +`component_types`; a `stacks` selector never matches because the operation has no stack. See [`atmos docs generate`](/cli/commands/docs/generate#hooks). + ## Hook requirements
diff --git a/website/docs/policies/inputs.mdx b/website/docs/policies/inputs.mdx index 1ffe3b85567..4a582029bdf 100644 --- a/website/docs/policies/inputs.mdx +++ b/website/docs/policies/inputs.mdx @@ -53,7 +53,7 @@ for fields, operations, local development handling, and reusable CEL/Starlark ex ## Operation input -Use `on: operation` for Terraform, Helmfile, Helm, and Kubernetes lifecycle events. +Use `on: operation` for Terraform, Helmfile, Helm, Kubernetes, and documentation generation lifecycle events. ```json { @@ -71,10 +71,10 @@ Use `on: operation` for Terraform, Helmfile, Helm, and Kubernetes lifecycle even | Field | Type | Meaning | |---|---|---| | `event` | String | Canonical `before..` or `after..` lifecycle event | -| `component_type` | String | `terraform`, `helmfile`, `helm`, or `kubernetes` | +| `component_type` | String | `terraform`, `helmfile`, `helm`, `kubernetes`, or `docs` | | `command` | String | Operation represented by the normalized event; deploy aliases use apply events | -| `component` | String | Component argument | -| `stack` | String | Selected stack | +| `component` | String | Component argument; for `docs`, the `docs.generate` generator name | +| `stack` | String | Selected stack; empty for `docs` | | `status` | String | `success` or `failure`; before-events begin with `success`. A Terraform plan exit code of `2` counts as success unless policy enforcement failed | | `exit_code` | Integer | Recorded command exit code; not proof that policies passed | | `dry_run` | Boolean | Whether this invocation is a dry-run | diff --git a/website/docs/stacks/hooks.mdx b/website/docs/stacks/hooks.mdx index cb610a1d605..d3c3d31b437 100644 --- a/website/docs/stacks/hooks.mdx +++ b/website/docs/stacks/hooks.mdx @@ -63,6 +63,7 @@ each level merges into the final result so you can keep configuration | Native Helm | `before`/`after.helm.template`, `diff`, `apply`/`deploy`, and `delete`. `deploy` normalizes to `apply`. CI aggregate events include `after.helm.plan.aggregate` and `after.helm.apply.aggregate`. | | Helmfile | `before`/`after.helmfile.template`, `diff`, `apply`/`sync`/`deploy`, `destroy`, and `version`. `sync` and `deploy` normalize to `apply`. | | CloudFormation | `before`/`after.aws/cloudformation.diff`, `apply`, `delete`, `drift-detect`, `drift-describe`, `changeset-create`, and `changeset-execute`. The aliases `plan` and `deploy` use the `diff` and `apply` events; the changeset events are separate and are not aliases of `apply`. See [CloudFormation lifecycle hooks](/stacks/components/aws-cloudformation#lifecycle-hooks). | +| Documentation generation | `before.docs.generate` and `after.docs.generate`. These are declared under `docs.generate..hooks` in `atmos.yaml`, not stack manifests, and support `kind: step`, `kind: steps`, and `kind: command`. They have no component or stack. See [`atmos docs generate`](/cli/commands/docs/generate#hooks). | | Scaffold generation | `before.scaffold.generate` and `after.scaffold.generate`. These are declared in `scaffold.yaml`, not stack manifests, and support only `kind: step` and `kind: steps`. | Hooks with no `events` list fire on every supported event for backward diff --git a/website/src/data/roadmap.js b/website/src/data/roadmap.js index bdcb922de40..ae895046072 100644 --- a/website/src/data/roadmap.js +++ b/website/src/data/roadmap.js @@ -509,7 +509,7 @@ export const roadmapConfig = { tagline: 'Truly extensible architecture', description: 'Modern infrastructure spans Terraform, Kubernetes, serverless, and custom tooling. A single orchestration layer should manage all of it consistently, not just a subset.', - progress: 85, + progress: 86, status: 'in-progress', milestones: [ { label: 'Configurable concurrent YAML exec evaluation', status: 'shipped', quarter: 'q4-2026', changelog: 'parallel-yaml-exec', docs: '/cli/configuration/settings/functions/exec', description: 'Run ordinary !exec expressions concurrently within a document evaluation with a configurable limit, preserving result placement and serial execution by default.', benefits: 'Reduce time spent waiting on independent configuration lookups without new tags or grouping syntax.' }, @@ -530,6 +530,7 @@ export const roadmapConfig = { { label: 'Scanner hooks write findings to GitHub Actions job summary (GITHUB_STEP_SUMMARY); Docker image bumped to debian:trixie-slim', status: 'shipped', quarter: 'q2-2026', changelog: 'scanner-findings-in-ci-job-summary', pr: 2617, description: 'Scanner and cost-analysis hooks (Checkov, Trivy, KICS for security; Infracost for cost) now automatically append their markdown findings summary to $GITHUB_STEP_SUMMARY when running in GitHub Actions. Previously findings only appeared in the terminal/log stream. The write is best-effort and never fails the hook. Also bumps the official Atmos Docker image base from debian:bookworm-slim (glibc 2.36) to debian:trixie-slim (glibc 2.41) so the PyInstaller-bundled Checkov binary (requires GLIBC_2.38+) runs correctly.', benefits: 'Security and cost findings are visible as a formatted report in the GitHub Actions job summary — no need to dig into log output. Checkov works out of the box in the official Docker image without a manual glibc workaround.' }, { label: 'Scanner hooks surface findings as GitHub Actions annotations and upload SARIF to Code Scanning', status: 'shipped', quarter: 'q2-2026', changelog: 'scanner-annotations-and-code-scanning', pr: 2631, description: 'Security scanner hooks (Checkov, Trivy, KICS) and generic `kind: command` hooks that emit SARIF now surface findings as inline GitHub Actions `::error`/`::warning` annotations on the PR diff via a new Annotator CI provider capability, and can upload SARIF results to GitHub Code Scanning (the Security tab) via a new SARIFReporter capability — no `github/codeql-action` required. Controlled by two new config keys gated behind `ci.enabled`: `ci.annotations` (default on, works without GitHub Advanced Security) and `ci.results` (default off, requires GHAS). Custom `kind: command` hooks opt in by setting `format: sarif`.', benefits: 'Security findings appear inline on PR diffs as annotations and in the repository Security tab without adding the codeql-action to every workflow. Teams without GitHub Advanced Security get free inline annotations; GHAS subscribers get full Code Scanning history and alert tracking.' }, { label: 'Built-in `tflint` hook kind for Terraform linting', status: 'shipped', quarter: 'q2-2026', changelog: 'tflint-hook-kind', description: 'A built-in `tflint` scanner hook kind lints Terraform/OpenTofu on lifecycle events with zero configuration. Because tflint writes SARIF only to stdout (no file-output flag), the hook engine gained an opt-in `CaptureStdout` mode that redirects a tool\'s stdout into the structured-output side channel. tflint then rides the shared SARIF handler, so findings render in the terminal and Atmos Pro and — in CI — as a step summary, inline PR annotations, and a GitHub Code Scanning upload, all automatically.', codeExample: 'hooks:\n lint: { events: [after.terraform.plan], kind: tflint }', benefits: 'Catch unused declarations, deprecated syntax, and provider-specific mistakes before apply — with the same zero-config, CI-integrated experience as the security scanners.' }, + { label: 'Lifecycle hooks and policy support for `atmos docs generate`', status: 'shipped', quarter: 'q4-2026', changelog: 'docs-generate-hooks', docs: '/cli/commands/docs/generate#hooks', prd: 'docs-generate-hooks', description: 'Documentation generators accept `hooks` that run on the new `before.docs.generate` and `after.docs.generate` events, using the same step, steps, and command kinds as component hooks. Steps receive the document type, output path, and base directory; a failing before-hook stops generation before any file is written, `when:` selects success, failure, or always, `--skip-hooks` is honored, and `on: operation` policies with `action: hooks` apply.', benefits: "Publish generated documentation to a wiki, portal, or bucket from the generator itself with a generic step, instead of wrapper scripts and CI glue." }, { label: 'Added `!terraform.output` YAML function', status: 'shipped', quarter: 'q3-2025', docs: '/functions/yaml/terraform.output', description: 'Reference outputs from other components without data sources.', codeExample: 'subnet_ids: !terraform.output vpc.private_subnet_ids', benefits: 'Wire components together declaratively. Dependencies are explicit in configuration.' }, { label: 'Component mocks for Terraform YAML lookups', status: 'shipped', quarter: 'q3-2026', pr: 2755, changelog: 'terraform-component-mocks', description: 'Terraform components can declare literal `mocks` outputs. Explicit `--use-mocks` support makes `!terraform.state` and `!terraform.output` resolve from those values during local plans and component inspection, without initializing Terraform or reading a remote backend.', benefits: 'Plan and review a component before its dependencies exist or when backend access is unavailable, while keeping the fake output surface explicit and owned by the producer component.' }, { label: 'Component mocks as fallbacks for missing state', status: 'shipped', quarter: 'q4-2026', changelog: 'terraform-component-mocks-fallback', description: 'With `--use-mocks`, `!terraform.state` and `!terraform.output` use real state when it exists and fall back to component mocks only when the state is not provisioned or the output is missing. `--use-mocks=always` and the edition-gated `components.terraform.mocks.mode` setting keep the hermetic mocks-only behavior available.', benefits: 'Plan against a partly deployed environment with real values where they exist and mocks only for the gaps, without hiding credential or backend errors.' },