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.
This commit is contained in:
sam committed 2026-09-03 03:07:27 +10:00
1 parent 556038e7cb
commit 8c19555b4a
6 files changed
+353

No files matched your search

+14
View File
@@ -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:
+85
View File
@@ -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 <command> [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
}
+75
View File
@@ -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)
}
}
+14
View File
@@ -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
+50
View File
@@ -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}
}
+115
View File
@@ -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)
}
}