From 8c19555b4a70886f09237f2ef6b54eb202a6de64 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Thu, 3 Sep 2026 03:07:27 +1000 Subject: [PATCH] feat(playbooks): standalone lint tool for playbook binding dirs Fourth slice of docs/prds/eda-playbook-engine.md (t2db.12): the design doc's pre-merge collision layer, as a gopls-shaped standalone binary (cmd/archie-playbooks) rather than a Taskfile wrapper -- one binary, one schema source, mode-based entrypoints. - cmd/archie-playbooks: subcommand dispatch table from day one (lint now; an lsp/serve mode later slots in without restructuring), flag parsing only per organisation.md's cmd/ rule. - internal/app/archieplaybooks: the lint mode's composition -- collects directories, calls workflow.LoadPlaybookDirs (the daemon's own loader), reports findings. No second validation path: the linter agrees with runtime startup validation by construction. - Reuses LoadKindWorkflowsYAML/LoadLabelWorkflowsYAML/LoadPlaybookDirs directly; collision/malformed/invalid bindings exit non-zero. - Known limitation recorded: findings are file-granular, not line-granular (yaml.Unmarshal into map discards line numbers; a file:line diagnostic needs a yaml.Node upgrade, out of scope here). - Taskfile lint:playbooks target; PRD records the shipped shape and the file-granular caveat. --- Taskfile.yml | 14 +++ cmd/archie-playbooks/main.go | 85 ++++++++++++++++ cmd/archie-playbooks/main_test.go | 75 ++++++++++++++ docs/prds/eda-playbook-engine.md | 14 +++ internal/app/archieplaybooks/lint.go | 50 ++++++++++ internal/app/archieplaybooks/lint_test.go | 115 ++++++++++++++++++++++ 6 files changed, 353 insertions(+) create mode 100644 cmd/archie-playbooks/main.go create mode 100644 cmd/archie-playbooks/main_test.go create mode 100644 internal/app/archieplaybooks/lint.go create mode 100644 internal/app/archieplaybooks/lint_test.go diff --git a/Taskfile.yml b/Taskfile.yml index 0704e0f50..af2f40ec4 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -25,6 +25,20 @@ tasks: cmds: - golangci-lint run ./... + lint:playbooks: + desc: "Lint playbook binding dirs for collisions (standalone tool, cmd/archie-playbooks)" + summary: | + Runs the standalone playbook linter (archie-playbooks lint) against + ./playbooks by default. It validates playbook YAML binding files + against the same loaders the daemon uses at startup, so a pre-merge + check can never disagree with runtime validation. Exit non-zero on + any collision / malformed file / invalid binding. + + Lint a different set of directories directly: + go run ./cmd/archie-playbooks lint -dir ./a -dir ./b + cmds: + - go run ./cmd/archie-playbooks lint -dir ./playbooks + vuln: desc: "Scan for known stdlib/dependency CVEs (govulncheck). Not part of task check: it needs network access to the vuln DB and is not build/test-blocking; run it explicitly or in CI." cmds: diff --git a/cmd/archie-playbooks/main.go b/cmd/archie-playbooks/main.go new file mode 100644 index 000000000..55762b7a0 --- /dev/null +++ b/cmd/archie-playbooks/main.go @@ -0,0 +1,85 @@ +// Command archie-playbooks is the standalone playbook tool for archie-core, +// shaped like gopls: one binary, multiple invocation modes. It validates +// playbook YAML binding files against the same schema the daemon loads at +// startup, so a pre-merge check can never disagree with runtime validation. +// +// Today it ships one mode (lint). The command dispatch is a table from day +// one, so a future serve/lsp mode slots in without restructuring -- both +// modes are entrypoints into the same validation source in +// internal/domain/workflow. +// +// Known limitation (as of this slice): findings are file-granular, not +// line-granular. The loader decodes playbooks with yaml.Unmarshal into a +// plain map, which discards line numbers; a compiler-style file:line +// diagnostic needs a yaml.Node decoding upgrade, which is out of scope +// here and tracked separately. +package main + +import ( + "flag" + "fmt" + "io" + "os" + + "github.com/samcharles93/archie-core/internal/app/archieplaybooks" +) + +func main() { + os.Exit(run(os.Args[1:], os.Stderr)) +} + +func run(args []string, stderr io.Writer) int { + // Subcommand table from day one (gopls shape): each mode owns its flag + // set and returns an exit code. Adding serve/lsp later is a new entry + // here, not a restructuring. + commands := map[string]func([]string, io.Writer) int{ + "lint": runLint, + } + + if len(args) == 0 { + fmt.Fprintln(stderr, "usage: archie-playbooks [args]") + fmt.Fprintln(stderr, "commands:") + for name := range commands { + fmt.Fprintf(stderr, " %s\n", name) + } + return 2 + } + + cmd, ok := commands[args[0]] + if !ok { + fmt.Fprintf(stderr, "archie-playbooks: unknown command %q\n", args[0]) + return 2 + } + return cmd(args[1:], stderr) +} + +// runLint validates one or more playbook directories against the domain +// loaders and reports collisions / malformed files / invalid bindings. +// Exit codes: 0 clean, 1 findings, 2 usage error. +func runLint(args []string, stderr io.Writer) int { + flags := flag.NewFlagSet("archie-playbooks lint", flag.ContinueOnError) + flags.SetOutput(stderr) + var dirs multiFlag + flags.Var(&dirs, "dir", "playbook directory to lint (repeatable)") + if err := flags.Parse(args); err != nil { + return 2 // flag.ContinueOnError already printed the message + } + if len(dirs) == 0 { + fmt.Fprintln(stderr, "lint: at least one -dir is required") + flags.Usage() + return 2 + } + + result := archieplaybooks.Lint(dirs, stderr) + return result.ExitCode +} + +// multiFlag collects repeated -dir flags. +type multiFlag []string + +func (m *multiFlag) String() string { return fmt.Sprint([]string(*m)) } + +func (m *multiFlag) Set(v string) error { + *m = append(*m, v) + return nil +} diff --git a/cmd/archie-playbooks/main_test.go b/cmd/archie-playbooks/main_test.go new file mode 100644 index 000000000..40a0a4730 --- /dev/null +++ b/cmd/archie-playbooks/main_test.go @@ -0,0 +1,75 @@ +package main + +import ( + "bytes" + "os" + "path/filepath" + "strings" + "testing" +) + +// TestRunUnknownCommandExits2: an unrecognised subcommand is a usage error. +func TestRunUnknownCommandExits2(t *testing.T) { + var stderr bytes.Buffer + if code := run([]string{"frobnicate"}, &stderr); code != 2 { + t.Fatalf("run(unknown) = %d, want 2", code) + } + if !strings.Contains(stderr.String(), "unknown command") { + t.Fatalf("stderr = %q, want unknown-command message", stderr.String()) + } +} + +// TestRunNoCommandExits2: no subcommand is a usage error with the command +// table printed (the gopls-shaped dispatch surface). +func TestRunNoCommandExits2(t *testing.T) { + var stderr bytes.Buffer + if code := run(nil, &stderr); code != 2 { + t.Fatalf("run(nil) = %d, want 2", code) + } + if !strings.Contains(stderr.String(), "lint") { + t.Fatalf("stderr = %q, want lint listed in usage", stderr.String()) + } +} + +// TestRunLintCleanExits0: lint over a valid directory exits 0. +func TestRunLintCleanExits0(t *testing.T) { + dir := t.TempDir() + writeFile(t, filepath.Join(dir, "routes.yaml"), "bug: tdd\n") + + var stderr bytes.Buffer + if code := run([]string{"lint", "-dir", dir}, &stderr); code != 0 { + t.Fatalf("run(lint clean) = %d, want 0; stderr=%q", code, stderr.String()) + } +} + +// TestRunLintCollisionExits1: a cross-directory collision exits 1 and names +// the colliding key. +func TestRunLintCollisionExits1(t *testing.T) { + dirA := t.TempDir() + dirB := t.TempDir() + writeFile(t, filepath.Join(dirA, "a.yaml"), "security: security-review\n") + writeFile(t, filepath.Join(dirB, "b.yaml"), "security: other-security\n") + + var stderr bytes.Buffer + if code := run([]string{"lint", "-dir", dirA, "-dir", dirB}, &stderr); code != 1 { + t.Fatalf("run(lint collision) = %d, want 1; stderr=%q", code, stderr.String()) + } + if !strings.Contains(stderr.String(), "security") { + t.Fatalf("stderr = %q, want the colliding label named", stderr.String()) + } +} + +// TestRunLintNoDirsExits2: lint without any -dir is a usage error. +func TestRunLintNoDirsExits2(t *testing.T) { + var stderr bytes.Buffer + if code := run([]string{"lint"}, &stderr); code != 2 { + t.Fatalf("run(lint no dirs) = %d, want 2", code) + } +} + +func writeFile(t *testing.T, path, content string) { + t.Helper() + if err := os.WriteFile(path, []byte(content), 0o600); err != nil { + t.Fatalf("write %s: %v", path, err) + } +} diff --git a/docs/prds/eda-playbook-engine.md b/docs/prds/eda-playbook-engine.md index 355e3f94b..c664def6c 100644 --- a/docs/prds/eda-playbook-engine.md +++ b/docs/prds/eda-playbook-engine.md @@ -160,6 +160,20 @@ a case that should just be visible and fixed by a human. Instead: - **Linter**: a CI/dev-time tool, reading the same generated schemas, that flags duplicate or conflicting trigger definitions *within* a single maintained tree before merge. + + **Status 2026-09-03: lint mode shipped (t2db.12).** A standalone + gopls-shaped binary (`cmd/archie-playbooks`, lint subcommand) validates + playbook directories against the exact loaders the daemon uses + (`LoadPlaybookDirs`/`LoadKindWorkflowsYAML`/`LoadLabelWorkflowsYAML`), + exiting non-zero on any collision / malformed file / invalid binding. + Findings are file-granular, not line-granular: the loader decodes with + `yaml.Unmarshal` into a plain map, which discards line numbers. A + compiler-style file:line diagnostic needs a `yaml.Node` decoding + upgrade, tracked separately -- the linter agrees with runtime + validation by construction, which is the load-bearing property. + Discoverable via `task lint:playbooks` or direct `go run + ./cmd/archie-playbooks lint -dir ...`. The LSP/serve mode is a later + entrypoint of the SAME binary, per the shared-package decision above. - **LSP**: same schema source again, feeding author-time hover/completion/ inline errors while someone edits a playbook YAML in an editor. Kept explicitly in scope per Sam (not deferred), because it's the same schema diff --git a/internal/app/archieplaybooks/lint.go b/internal/app/archieplaybooks/lint.go new file mode 100644 index 000000000..89e51d0cf --- /dev/null +++ b/internal/app/archieplaybooks/lint.go @@ -0,0 +1,50 @@ +// Package archieplaybooks is the application composition for the standalone +// playbook-validation CLI (cmd/archie-playbooks). It owns the lint mode's +// orchestration: collect the configured directories, run the domain +// validator, and shape the outcome for human consumption. All validation +// rules live in internal/domain/workflow (LoadKindWorkflowsYAML, +// LoadLabelWorkflowsYAML, LoadPlaybookDirs) -- this package only calls them +// and formats results; there is deliberately no second validation path +// here (per docs/prds/eda-playbook-engine.md and t2db.12). +package archieplaybooks + +import ( + "fmt" + "io" + + "github.com/samcharles93/archie-core/internal/domain/workflow" +) + +// Result is the outcome of one lint run: the exit code for the process and +// the human-readable findings. +type Result struct { + ExitCode int + Findings []string +} + +// Lint validates one or more playbook directories against the domain +// loaders and reports every collision / malformed file / invalid binding as +// a finding. It returns exit code 0 on a clean set, 1 when any finding is +// reported. Directories and single-file fields share one validation source: +// +// workflow.LoadPlaybookDirs +// +// which already applies the same rules LoadKindWorkflowsYAML and +// LoadLabelWorkflowsYAML do, per file and across files -- so the linter can +// never disagree with the daemon's startup validation. +func Lint(dirs []string, stderr io.Writer) Result { + var findings []string + + _, _, err := workflow.LoadPlaybookDirs(dirs) + if err != nil { + findings = append(findings, err.Error()) + } + + if len(findings) > 0 { + for _, f := range findings { + fmt.Fprintln(stderr, f) + } + return Result{ExitCode: 1, Findings: findings} + } + return Result{ExitCode: 0, Findings: nil} +} diff --git a/internal/app/archieplaybooks/lint_test.go b/internal/app/archieplaybooks/lint_test.go new file mode 100644 index 000000000..7f7d2b2ba --- /dev/null +++ b/internal/app/archieplaybooks/lint_test.go @@ -0,0 +1,115 @@ +package archieplaybooks + +import ( + "os" + "path/filepath" + "strings" + "testing" +) + +// TestLintCleanExitsZero: a set of directories with no collisions lints +// cleanly -- exit 0, no findings. +func TestLintCleanExitsZero(t *testing.T) { + dir := t.TempDir() + writeFile(t, filepath.Join(dir, "routes.yaml"), "bug: tdd\n") + writeFile(t, filepath.Join(dir, "labels.yaml"), "security: security-review\n") + + result := Lint([]string{dir}, os.Stdout) + if result.ExitCode != 0 { + t.Fatalf("Lint() exit = %d, want 0; findings: %#v", result.ExitCode, result.Findings) + } + if len(result.Findings) != 0 { + t.Fatalf("Lint() findings = %#v, want none", result.Findings) + } +} + +// TestLintCrossDirectoryCollisionExitsNonZero is the load-bearing case: two +// directories binding the same label is a lint failure with a clear message +// naming the colliding key, and exit non-zero. +func TestLintCrossDirectoryCollisionExitsNonZero(t *testing.T) { + dirA := t.TempDir() + dirB := t.TempDir() + writeFile(t, filepath.Join(dirA, "a.yaml"), "security: security-review\n") + writeFile(t, filepath.Join(dirB, "b.yaml"), "security: other-security\n") + + result := Lint([]string{dirA, dirB}, os.Stdout) + if result.ExitCode == 0 { + t.Fatal("Lint() exit = 0, want non-zero for collision") + } + if len(result.Findings) == 0 { + t.Fatal("Lint() findings = none, want the collision reported") + } + joined := strings.Join(result.Findings, "\n") + if !strings.Contains(joined, "security") { + t.Fatalf("Lint() findings do not name the colliding label: %q", joined) + } +} + +// TestLintWithinDirectoryCollisionExitsNonZero: the more common real case -- +// two files in one directory binding the same key. +func TestLintWithinDirectoryCollisionExitsNonZero(t *testing.T) { + dir := t.TempDir() + writeFile(t, filepath.Join(dir, "a.yaml"), "security: security-review\n") + writeFile(t, filepath.Join(dir, "b.yaml"), "security: other-security\n") + + result := Lint([]string{dir}, os.Stdout) + if result.ExitCode == 0 { + t.Fatal("Lint() exit = 0, want non-zero for within-dir collision") + } +} + +// TestLintMalformedFileIsReported: a malformed YAML file is a lint finding. +func TestLintMalformedFileIsReported(t *testing.T) { + dir := t.TempDir() + writeFile(t, filepath.Join(dir, "broken.yaml"), "\t: : :\n") + + result := Lint([]string{dir}, os.Stdout) + if result.ExitCode == 0 { + t.Fatal("Lint() exit = 0, want non-zero for malformed file") + } +} + +// TestLintEmptyDirsAreClean: no directories configured (or none exist) is a +// clean lint, not an error -- matching the loaders' empty-means-defaults +// convention. +func TestLintEmptyDirsAreClean(t *testing.T) { + result := Lint(nil, os.Stdout) + if result.ExitCode != 0 { + t.Fatalf("Lint(nil) exit = %d, want 0", result.ExitCode) + } + missing := filepath.Join(t.TempDir(), "does-not-exist") + result = Lint([]string{missing}, os.Stdout) + if result.ExitCode != 0 { + t.Fatalf("Lint(missing dir) exit = %d, want 0", result.ExitCode) + } +} + +// TestLintReportsLoadErrorAsFinding: the linter surfaces the loader's +// definition failure verbatim -- it agrees with the daemon's startup +// validation because it IS the same validation, not a parallel one. +func TestLintReportsLoadErrorAsFinding(t *testing.T) { + dir := t.TempDir() + writeFile(t, filepath.Join(dir, "a.yaml"), "security: security-review\nbug: tdd\n") + writeFile(t, filepath.Join(dir, "b.yaml"), "security: other-security\nbug: custom-bug\n") + + result := Lint([]string{dir}, os.Stdout) + if result.ExitCode == 0 { + t.Fatal("Lint() exit = 0, want non-zero") + } + joined := strings.Join(result.Findings, "\n") + if !strings.Contains(joined, "security") { + t.Fatalf("Lint() findings = %q, want the colliding key named", joined) + } + // Fail-fast like the daemon: one definition failure is reported (the + // loader returns the first), not an enumeration of every collision. + if len(result.Findings) != 1 { + t.Fatalf("Lint() findings = %d, want exactly 1 (loader fail-fast contract)", len(result.Findings)) + } +} + +func writeFile(t *testing.T, path, content string) { + t.Helper() + if err := os.WriteFile(path, []byte(content), 0o600); err != nil { + t.Fatalf("write %s: %v", path, err) + } +}