Files
archie/internal/infrastructure/workflowsteps/workflowsteps_test.go
T
sam 9f6d323fc3 docs(prds): name the registered step type and hold the vocabulary PRD to the provider set
docs/prds/workflow-step-vocabulary.md named the repository-rules step type
`workflow.diff-rules` while the vocabulary a deployment resolves carries
`gate.diff-rules` (workflow.DiffRulesStepName), so a definition written to
the document's word is refused at save and at run. The same decision's
sibling, docs/prds/runtime-control-plane.md, still claimed "Plugins can add
step types", which this document's closed-set rule contradicts: an
interpreted plugin contributes none, and a step type arrives as a provider
in the compiled-in set.

Correct both documents, and hold the vocabulary PRD to the provider set with
a guard test: every step-type-shaped name the document identifies must
resolve in workflowsteps.Providers(). The test fails on the pre-fix document
("workflow.diff-rules" is contributed by no provider) and passes after.

Refs: archie-core-vwqc, split from archie-core-gcoj (closed as invalidated by
re-verification: the provider set exists and cross-side agreement is already
pinned).
2026-10-02 11:05:08 +10:00

271 lines
11 KiB
Go

package workflowsteps
import (
"os"
"path/filepath"
"regexp"
"slices"
"strings"
"testing"
"gopkg.in/yaml.v3"
"github.com/samcharles93/archie-core/internal/domain/stableid"
"github.com/samcharles93/archie-core/internal/domain/workflow"
)
// TestShippedVocabularyCoversEveryShippedStage is the guard that the bundled
// provider set really carries the shipped stages: a process that registers it
// can compile every shipped workflow, and one that does not has no vocabulary
// at all.
func TestShippedVocabularyCoversEveryShippedStage(t *testing.T) {
t.Parallel()
manager, err := NewManager()
if err != nil {
t.Fatalf("NewManager: %v", err)
}
got := manager.StepTypes()
// Every shipped stage is present...
for name := range workflow.BuiltinStepRegistry() {
if !slices.Contains(got, name) {
t.Errorf("registered vocabulary %v is missing the shipped stage %q", got, name)
}
}
// ...and the vocabulary is exactly what the provider set declares. The
// expectation is derived from Providers() rather than from
// workflow.BuiltinStepRegistry(): adding a provider to this set is the
// documented way a step type arrives, and that must move both sides of this
// assertion together instead of having to edit it.
if want := declaredStepTypes(); !slices.Equal(got, want) {
t.Fatalf("registered vocabulary = %v, want the provider set's declared step types %v", got, want)
}
// The vocabulary arrives by registration, not by implication: a manager
// that was handed no provider set resolves nothing, which is what makes
// every resolution site's use of the injected manager observable.
if got := workflow.NewManager().StepTypes(); len(got) != 0 {
t.Fatalf("an unregistered manager resolves %v, want nothing", got)
}
}
// declaredStepTypes returns every step type the provider set contributes,
// sorted, so a test can hold a manager to the set it was built from.
func declaredStepTypes() []string {
names := make([]string, 0)
for _, provider := range Providers() {
for _, stepType := range provider.StepTypes() {
names = append(names, stepType.Name)
}
}
slices.Sort(names)
return names
}
// TestShippedStagesKeepTheirBehaviourThroughTheManager pins that the provider
// hands the builtin factories through unchanged. The shipped stages are typed,
// non-interpreted steps: each compiles to the stage the builtin registry's own
// factory builds for that step type -- the same name, and Run present or absent
// the same way -- and refuses settings. The one way this enumeration could keep
// every name and lose that guard is to rebuild the factories instead of
// forwarding them, and definition_test.go's assertion cannot see it -- that test
// drives BuiltinStepRegistry directly, which no resolution site does any more:
// production reaches it only inside the shipped provider below.
func TestShippedStagesKeepTheirBehaviourThroughTheManager(t *testing.T) {
t.Parallel()
manager, err := NewManager()
if err != nil {
t.Fatalf("NewManager: %v", err)
}
registry := manager.Registry()
for _, entry := range workflow.ShippedDefinitions().Definitions {
definition, err := workflow.ParseDefinition(entry.YAML, registry)
if err != nil {
t.Fatalf("parse shipped workflow %q through the registered vocabulary: %v", entry.ID, err)
}
compiled, err := workflow.ParseAndCompile(entry.YAML, registry)
if err != nil {
t.Fatalf("compile shipped workflow %q through the registered vocabulary: %v", entry.ID, err)
}
if len(compiled.Stages) != len(definition.Steps) {
t.Fatalf("%s compiled %d stages, want %d", entry.ID, len(compiled.Stages), len(definition.Steps))
}
for i, step := range definition.Steps {
// The expectation is the stage the builtin registry's own factory
// builds for this step type, not a name derived from the step type:
// that is what "the registered factory is the builtin one" means
// for a Stage, which is a name plus an uncomparable func.
shipped, err := workflow.BuiltinStepRegistry()[step.Type](yaml.Node{})
if err != nil {
t.Fatalf("build shipped stage %s: %v", step.Type, err)
}
if compiled.Stages[i].Name != shipped.Name {
t.Errorf("%s step %d (%s) compiled to stage %q, want the shipped stage %q: the registered factory is not the builtin one", entry.ID, i, step.Type, compiled.Stages[i].Name, shipped.Name)
}
if (compiled.Stages[i].Run != nil) != (shipped.Run != nil) {
t.Errorf("%s step %d (%s) compiled to a stage whose Run is present=%t, want the shipped stage's present=%t", entry.ID, i, step.Type, compiled.Stages[i].Run != nil, shipped.Run != nil)
}
}
}
if _, err := workflow.ParseAndCompile("id: probe\nsteps:\n - type: bootstrap.apply\n settings:\n command: rm -rf /\n", registry); err == nil || !strings.Contains(err.Error(), "accepts no settings") {
t.Fatalf("ParseAndCompile() error = %v, want the shipped stage's settings refusal", err)
}
}
// TestNewManagerIsRepeatableWithinOneProcess is the regression guard for
// registering the provider set into shared state: every construction is
// independent, so building the vocabulary twice in one process — as `-count=2`
// does — must succeed and produce the same vocabulary.
func TestNewManagerIsRepeatableWithinOneProcess(t *testing.T) {
t.Parallel()
first, err := NewManager()
if err != nil {
t.Fatalf("first NewManager: %v", err)
}
second, err := NewManager()
if err != nil {
t.Fatalf("second NewManager: %v", err)
}
if !slices.Equal(first.StepTypes(), second.StepTypes()) {
t.Fatalf("two managers resolved different vocabularies: %v and %v", first.StepTypes(), second.StepTypes())
}
if !slices.Equal(first.Providers(), second.Providers()) {
t.Fatalf("two managers registered different providers: %v and %v", first.Providers(), second.Providers())
}
}
// TestRepoHookStepsCompileThroughTheManager pins the migration target a
// repository's rules arrive on: the step type the deleted .archie/gate.go hook
// is replaced by is in the bundled vocabulary, its factory is reached through
// the manager rather than through the domain type directly, and its settings
// are validated where a stored definition is validated -- so a definition the
// validating side admits is one the executing side can compile.
func TestRepoHookStepsCompileThroughTheManager(t *testing.T) {
t.Parallel()
manager, err := NewManager()
if err != nil {
t.Fatalf("NewManager: %v", err)
}
registry := manager.Registry()
stepType := workflow.DiffRulesStepType()
if !slices.Contains(manager.StepTypes(), stepType.Name) {
t.Fatalf("the bundled vocabulary %v does not carry the repository-rules step type %q", manager.StepTypes(), stepType.Name)
}
if _, registered := registry[stepType.Name]; !registered {
t.Fatalf("the manager resolves no factory for %q, so no stored definition could compile it", stepType.Name)
}
domainStage, err := stepType.Factory(yaml.Node{})
if err == nil {
t.Fatalf("the domain factory accepted a step with no settings and built %q", domainStage.Name)
}
definition := "id: repo-rules\nsteps:\n" +
" - type: " + stepType.Name + "\n" +
" settings:\n" +
" rules:\n" +
" - id: no-new-panic\n" +
" level: error\n" +
" pattern: 'panic\\('\n" +
" message: new panic() call\n"
compiled, err := workflow.ParseAndCompile(definition, registry)
if err != nil {
t.Fatalf("ParseAndCompile(%q) through the bundled vocabulary: %v", stepType.Name, err)
}
if len(compiled.Stages) != 1 || compiled.Stages[0].Name != stepType.Name {
t.Fatalf("compiled workflow = %+v, want the single %q step", compiled, stepType.Name)
}
if compiled.Stages[0].Run == nil {
t.Fatalf("the %q step compiled to a stage with no Run", stepType.Name)
}
// The refusal is the point, not the error type: a stored rule the step
// cannot apply must be refused while the definition is validated, or it
// would load and silently check nothing.
broken := strings.Replace(definition, "level: error", "level: fatal", 1)
if _, err := workflow.ParseAndCompile(broken, registry); err == nil || !strings.Contains(err.Error(), "fatal") {
t.Fatalf("ParseAndCompile(%q) error = %v, want the unusable rule refused by name", broken, err)
}
}
// The shipped example workflows parse against the vocabulary the roots
// register, so an example cannot drift from the steps that exist.
func TestExampleWorkflowsParse(t *testing.T) {
paths, err := filepath.Glob("../../../examples/workflows/*.yaml")
if err != nil || len(paths) == 0 {
t.Fatalf("no example workflows found: %v", err)
}
manager, err := NewManager()
if err != nil {
t.Fatal(err)
}
registry := manager.Registry()
for _, path := range paths {
src, err := os.ReadFile(path)
if err != nil {
t.Fatal(err)
}
if _, err := workflow.ParseDefinition(string(src), registry); err != nil {
t.Errorf("%s: %v", path, err)
}
}
}
// documentedSpan matches one inline-code span in the vocabulary PRD, captured
// without its backticks.
var documentedSpan = regexp.MustCompile("`([^`]+)`")
// isDocumentedStepType reports whether a documented token names a workflow step
// type. A step type is a stable identifier that carries a dot: the vocabulary
// names <family>.<word> (bootstrap.apply, gate.diff-rules, agent.run). The
// document's other backticked spans are Go identifiers (StepFactory,
// plugin.Plugin -- uppercase, so not stable identifiers), repository paths
// (slashes, so not stable identifiers) or bead ids (no dot), and none of them
// is mistaken for a step type by this rule.
func isDocumentedStepType(token string) bool {
return strings.Contains(token, ".") && stableid.Valid(token)
}
// TestDocumentedStepVocabularyResolvesInTheProviderSet ties the vocabulary the
// workflow-step-vocabulary PRD names to the vocabulary a deployment resolves.
// That PRD is where an operator or plugin author reads which step types exist,
// so a word it names that no provider contributes describes a step type every
// deployment refuses -- the drift that survived the document's own decision
// (gate.diff-rules is the registered word; the PRD called it
// workflow.diff-rules). The scan must find the vocabulary, not merely pass on
// an empty list.
func TestDocumentedStepVocabularyResolvesInTheProviderSet(t *testing.T) {
t.Parallel()
source, err := os.ReadFile(filepath.Join("..", "..", "..", "docs", "prds", "workflow-step-vocabulary.md"))
if err != nil {
t.Fatalf("read the workflow step vocabulary PRD: %v", err)
}
manager, err := NewManager()
if err != nil {
t.Fatalf("NewManager: %v", err)
}
registered := manager.StepTypes()
documented := 0
for _, match := range documentedSpan.FindAllStringSubmatch(string(source), -1) {
token := match[1]
if !isDocumentedStepType(token) {
continue
}
documented++
if !slices.Contains(registered, token) {
t.Errorf("the vocabulary PRD names step type %q, which no provider contributes: a deployment refuses a definition that uses it", token)
}
}
if documented == 0 {
t.Fatal("the vocabulary PRD named no step type; the scan is not reading the document's vocabulary")
}
}