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:
1 parent
556038e7cb
commit
8c19555b4a
6 files changed
+353
No files matched your search
@@ -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:
|
||||
|
||||
@@ -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
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
|
||||
@@ -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}
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user