feat(workflow): register gate.diff-rules as the .archie/gate.go replacement

steps.go's StageYaegiGate tells the operator to migrate the deleted
.archie/gate.go hook to a registered YAML workflow step, and
BuiltinStepRegistry() exposed only the six shipped workflows' own stages,
so there was nothing to migrate to. What that hook did, from 02720c8e
which deleted it: it read the worktree's repository-authored Go,
exporting Check(GateContext{Diff, ChangedFiles, Dir, BaseRef, Repo})
[]Finding, where each Finding carried a level ("error" blocked the run,
"warn" was advisory) and an optional file and line, and it inspected the
committed diff.

gate.diff-rules is that behaviour as a typed step: operator-written rules
in a stored definition -- per-rule level, RE2 pattern, optional path and
exclude_path scope, message -- matched against the ADDED lines of the
diff against the base branch, reported with their new-file line numbers.
An error-level finding parks the run with the findings in the park
reason; a warn-level finding is logged and nothing else. Unlike the hook
it replaces, no code is read out of the repository being worked on, and
the rules are versioned and audited with the definition they live in.

The settings are validated at the factory, which runs where a definition
is validated and again where it is compiled: a missing level, pattern or
message, an unknown level or settings key, and an expression that is not
a RE2 all refuse the definition rather than load and check nothing.

It arrives through the extension point archie-core-fwmp landed: a
repo-hooks provider in internal/infrastructure/workflowsteps, so both
roots that resolve a step type (the State Store's validating side and the
daemon's workflow-definitions client) register it at once.

Deliberately not landed: a step type for .archie/stages/*.go, whose
faithful equivalent is running a configured command. That would make the
stored workflow-definitions resource a command-execution surface on the
agent host, which is a maintainer's trust decision, not this lane's; it
is escalated, so steps.go's repo-stages error stays as it is.
This commit is contained in:
sam committed 2026-09-21 20:33:47 +10:00
1 parent 8a8cca5654
commit e94db30c60
5 files changed
+1007 -2

No files matched your search

+402
View File
@@ -0,0 +1,402 @@
package workflow
import (
"bytes"
"context"
"errors"
"fmt"
"regexp"
"strconv"
"strings"
"gopkg.in/yaml.v3"
)
// DiffRulesStepName is the registered workflow step type that applies a
// repository's declarative rules to the committed diff.
//
// It is the supported migration target for the deleted .archie/gate.go hook.
// That hook was repository-authored Go, discovered in the worktree and
// interpreted in-process, exporting
//
// func Check(gate.GateContext) []gate.Finding
//
// where each Finding carried a level ("error" blocked, "warn" was advisory) and
// an optional file and line. Its useful behaviour -- project-specific rules
// that shell commands cannot express, reported against the lines a change
// introduces -- is what this step type carries, with the rules as data an
// operator writes in a stored workflow definition rather than code read out of
// the repository being worked on:
//
// steps:
// - type: gate.diff-rules
// settings:
// rules:
// - id: no-new-panic
// level: error
// path: '\.go$'
// pattern: 'panic\('
// message: new panic() call -- use error returns instead
//
// The step diffs the worktree against the repository's base branch, matches
// each rule against the ADDED lines of that diff, and reports every match with
// its file and new-file line number. An error-level finding parks the run with
// the findings in the task's park reason; a warn-level finding is logged and
// nothing else. A rule that matches nothing is silent.
//
// What it deliberately does not do is inspect a changed file's whole contents:
// a rule reads what the change adds, so a rule cannot be satisfied or broken by
// code the change did not touch. Anything a diff-shaped rule cannot express
// belongs in the repository's configured gate commands (config.Repo.Gate),
// which already run on the host.
const DiffRulesStepName = "gate.diff-rules"
// DiffRuleLevel values. An error-level finding parks the run; a warn-level
// finding is advisory and never blocks.
const (
DiffRuleLevelError = "error"
DiffRuleLevelWarn = "warn"
)
// diffRuleDetailBytes bounds how much of a park Detail the rendered findings
// occupy, matching the store's own park-reason cap headroom (see
// reviewDetailBytes in review.go).
const diffRuleDetailBytes = 4000
// DiffRule is one declarative rule applied to the added lines of the committed
// diff. Every field is an operator setting, so a rule is reviewable, versioned
// and audited with the definition it lives in -- none of which was true of the
// interpreted Go this replaces.
type DiffRule struct {
// ID names the rule in the run's log and in the park reason. Optional;
// without one a finding is still attributable to its file and line, not to
// the rule that reported it.
ID string `yaml:"id"`
// Level is DiffRuleLevelError or DiffRuleLevelWarn, and is required: a rule
// that does not say whether it blocks is refused rather than defaulted.
Level string `yaml:"level"`
// Pattern is the RE2 expression matched against each added line's text
// (without its leading "+"). Required.
Pattern string `yaml:"pattern"`
// Path, when set, is an RE2 expression the changed file's path must match
// for the rule to apply, e.g. '\.go$'. Optional.
Path string `yaml:"path"`
// ExcludePath, when set, is an RE2 expression the changed file's path must
// NOT match for the rule to apply, e.g. '_test\.go$'. Optional, and the
// only way to spare one class of file: RE2 has no lookahead.
ExcludePath string `yaml:"exclude_path"`
// Message is what the operator reads when the rule fires. Required.
Message string `yaml:"message"`
}
// diffRulesSettings is the step's whole settings surface. It exists as a type
// so the decode is strict: a settings key the step does not read is refused
// where the definition is validated, not ignored at run time.
type diffRulesSettings struct {
Rules []DiffRule `yaml:"rules"`
}
// DiffRulesStepType returns the registered step type for DiffRulesStepName, the
// way the shipped stages are declared: the factory builds the stage the
// executing side runs from the settings the validating side accepted.
func DiffRulesStepType() StepType {
return StepType{Name: DiffRulesStepName, Factory: newDiffRulesStage}
}
// newDiffRulesStage decodes and compiles the step's settings, refusing every
// contribution it cannot apply. This runs where the definition is validated and
// again where it is compiled, so a stored definition that cannot be honoured
// fails closed instead of loading and then quietly applying nothing.
func newDiffRulesStage(settings yaml.Node) (Stage, error) {
rules, err := decodeDiffRules(settings)
if err != nil {
return Stage{}, err
}
return Stage{Name: DiffRulesStepName, Run: func(ctx context.Context, tc *TaskContext) error {
return runDiffRules(ctx, tc, rules)
}}, nil
}
func runDiffRules(ctx context.Context, tc *TaskContext, rules []compiledDiffRule) error {
if tc.Dir == "" {
return fmt.Errorf("%s: no worktree to diff: this step must follow the one that prepares it", DiffRulesStepName)
}
base := tc.Repo.BaseBranch()
diff, err := tc.Trees.Diff(ctx, tc.Dir, base)
if err != nil {
return fmt.Errorf("%s: diff against %s: %w", DiffRulesStepName, base, err)
}
var blocking []diffFinding
for _, finding := range matchDiffRules(rules, addedDiffLines(diff)) {
logRuleFinding(tc, finding)
if finding.Level == DiffRuleLevelError {
blocking = append(blocking, finding)
}
}
if len(blocking) > 0 {
// A blocking finding is a verdict about the change, not a failure of the
// run: the task parks with what was found, the way the adversarial
// review parks with its findings, so an operator reads why rather than
// an execution error that hides it.
tc.Outcome = Outcome{Status: StatusParked, Detail: renderDiffRuleFindings(blocking)}
}
return nil
}
// logRuleFinding records one finding under the severity of its effect -- a
// blocking finding is a warning an operator acts on, an advisory one is
// informational -- while the rule's own declared level rides along as
// rule_level. The field is not called "level": that key is slog's own record
// level, and a record carrying it twice is a coin toss for whichever reader
// keeps one.
func logRuleFinding(tc *TaskContext, finding diffFinding) {
attributes := []any{
"rule_level", finding.Level,
"rule", finding.Rule,
"file", finding.Path,
"line", finding.Line,
"message", finding.Message,
}
if finding.Level == DiffRuleLevelError {
tc.Log.Warn("diff rule finding", attributes...)
return
}
tc.Log.Info("diff rule finding", attributes...)
}
// renderDiffRuleFindings formats the blocking findings as a park reason: one
// line per violation, at the position a reader can jump to.
func renderDiffRuleFindings(findings []diffFinding) string {
var builder strings.Builder
builder.WriteString("diff rules found blocking violations:\n")
for _, finding := range findings {
fmt.Fprintf(&builder, "- %s:%d: %s", finding.Path, finding.Line, finding.Message)
if finding.Rule != "" {
fmt.Fprintf(&builder, " (%s)", finding.Rule)
}
builder.WriteString("\n")
}
return clip(builder.String(), diffRuleDetailBytes)
}
// decodeDiffRules strictly decodes the step's settings and compiles every rule
// up front.
func decodeDiffRules(settings yaml.Node) ([]compiledDiffRule, error) {
if settings.Kind == 0 {
return nil, fmt.Errorf("%s requires settings: a step with no rules would pass every change", DiffRulesStepName)
}
var decoded diffRulesSettings
if err := decodeSettingsStrict(settings, &decoded); err != nil {
return nil, fmt.Errorf("%s settings: %w", DiffRulesStepName, err)
}
if len(decoded.Rules) == 0 {
return nil, fmt.Errorf("%s: at least one rule is required", DiffRulesStepName)
}
rules := make([]compiledDiffRule, 0, len(decoded.Rules))
for i, rule := range decoded.Rules {
compiled, err := compileDiffRule(rule)
if err != nil {
return nil, fmt.Errorf("%s rule %d: %w", DiffRulesStepName, i+1, err)
}
rules = append(rules, compiled)
}
return rules, nil
}
// compileDiffRule turns one operator rule into the form the stage matches with,
// compiling its expressions here rather than at the first line of a run: a rule
// that cannot be applied is refused where the definition is validated.
func compileDiffRule(rule DiffRule) (compiledDiffRule, error) {
compiled := compiledDiffRule{id: rule.ID, level: rule.Level, message: rule.Message}
switch rule.Level {
case DiffRuleLevelError, DiffRuleLevelWarn:
case "":
return compiledDiffRule{}, errors.New("level is required (error or warn)")
default:
return compiledDiffRule{}, fmt.Errorf("unknown level %q, want %q or %q", rule.Level, DiffRuleLevelError, DiffRuleLevelWarn)
}
if rule.Message == "" {
return compiledDiffRule{}, errors.New("message is required")
}
if rule.Pattern == "" {
return compiledDiffRule{}, errors.New("pattern is required")
}
pattern, err := regexp.Compile(rule.Pattern)
if err != nil {
return compiledDiffRule{}, fmt.Errorf("pattern: %w", err)
}
compiled.pattern = pattern
if rule.Path != "" {
path, err := regexp.Compile(rule.Path)
if err != nil {
return compiledDiffRule{}, fmt.Errorf("path: %w", err)
}
compiled.path = path
}
if rule.ExcludePath != "" {
excludePath, err := regexp.Compile(rule.ExcludePath)
if err != nil {
return compiledDiffRule{}, fmt.Errorf("exclude_path: %w", err)
}
compiled.excludePath = excludePath
}
return compiled, nil
}
// decodeSettingsStrict decodes a settings node the way ParseDefinition's own
// decoder reads a definition: unknown fields are errors. yaml.Node.Decode is
// not strict, so the node is re-encoded and decoded with KnownFields rather
// than silently dropping a key this step does not read.
func decodeSettingsStrict(settings yaml.Node, target any) error {
raw, err := yaml.Marshal(&settings)
if err != nil {
return fmt.Errorf("re-encode settings: %w", err)
}
decoder := yaml.NewDecoder(bytes.NewReader(raw))
decoder.KnownFields(true)
return decoder.Decode(target)
}
// compiledDiffRule is one rule in the form the stage applies it: expressions
// compiled, level checked.
type compiledDiffRule struct {
id string
level string
message string
pattern *regexp.Regexp
path *regexp.Regexp
excludePath *regexp.Regexp
}
// appliesTo reports whether this rule covers a changed file's path.
func (r compiledDiffRule) appliesTo(path string) bool {
if r.path != nil && !r.path.MatchString(path) {
return false
}
return r.excludePath == nil || !r.excludePath.MatchString(path)
}
// diffFinding is one rule violation, at the position the change introduced it.
type diffFinding struct {
Rule string
Level string
Message string
Path string
Line int
}
// matchDiffRules applies every rule to every added line. Rules are not
// short-circuited by the first match: two rules can both object to one line,
// and an operator who wrote both wants to read both.
func matchDiffRules(rules []compiledDiffRule, added []diffLine) []diffFinding {
var findings []diffFinding
for _, line := range added {
for _, rule := range rules {
if !rule.appliesTo(line.Path) || !rule.pattern.MatchString(line.Text) {
continue
}
findings = append(findings, diffFinding{
Rule: rule.id,
Level: rule.level,
Message: rule.message,
Path: line.Path,
Line: line.Line,
})
}
}
return findings
}
// diffLine is one added line of a unified diff, positioned in the file the
// change produces -- the number an operator can open, not the diff's own
// offset.
type diffLine struct {
Path string
Line int
Text string
}
// addedDiffLines walks a unified diff and returns the lines it ADDS, each with
// the path of the file it lands in and its line number in the new file.
//
// Only added lines are returned: a removed line has no position in the file the
// change produces, and a context line is not something the change did, so
// neither can be something a repository rule should report against.
func addedDiffLines(diff string) []diffLine {
var (
lines []diffLine
path string
newLn int
inHunk bool
)
for _, raw := range strings.Split(diff, "\n") {
switch {
case strings.HasPrefix(raw, "diff --git "):
// A new file's patch starts: nothing may be attributed to the
// previous file until its own +++ header is read.
path, inHunk = "", false
case strings.HasPrefix(raw, "@@"):
start, ok := hunkNewStart(raw)
inHunk = ok
newLn = start
case !inHunk:
// Outside a hunk only the file headers say anything; index lines,
// permissions and the like are noise here. This is also what keeps
// a body line that begins with the header marker ("+++ x", the
// added line "++ x") from being read as a header.
if strings.HasPrefix(raw, "+++ ") {
path = diffTargetPath(strings.TrimPrefix(raw, "+++ "))
}
case raw == "":
// The trailing empty element of the split, at most.
case raw[0] == '\\':
// git's "\ No newline at end of file": a marker, not a line.
case raw[0] == '-':
// A removed line: no position in the new file.
case raw[0] == '+':
lines = append(lines, diffLine{Path: path, Line: newLn, Text: raw[1:]})
newLn++
default:
// A context line: it advances the new-file position without
// itself being part of the change.
newLn++
}
}
return lines
}
// hunkNewStart reads the new-file start line out of a hunk header such as
// "@@ -1,4 +1,5 @@ func main() {". Both counts are optional in the format, and
// the trailing section heading may contain anything.
func hunkNewStart(header string) (int, bool) {
plus := strings.Index(header, " +")
if plus < 0 {
return 0, false
}
rest := header[plus+2:]
end := strings.IndexAny(rest, ", @")
if end < 0 {
return 0, false
}
start, err := strconv.Atoi(rest[:end])
if err != nil {
return 0, false
}
return start, true
}
// diffTargetPath reads the path out of a "+++ " header: "b/main.go" in git's
// own output, quoted when the path carries something git has to escape, and
// tab-separated from a timestamp in a plain unified diff.
func diffTargetPath(header string) string {
path := strings.TrimSpace(header)
if tab := strings.IndexByte(path, '\t'); tab >= 0 {
path = path[:tab]
}
path = strings.Trim(path, `"`)
return strings.TrimPrefix(strings.TrimPrefix(path, "b/"), "a/")
}
+526
View File
@@ -0,0 +1,526 @@
package workflow
import (
"bytes"
"context"
"errors"
"log/slog"
"os"
"path/filepath"
"strings"
"testing"
"gopkg.in/yaml.v3"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/worktree"
)
// errDiffUnavailable is what a Trees implementation reports when the committed
// change could not be read.
var errDiffUnavailable = errors.New("diff unavailable")
// diffTwoFiles is a committed change whose added lines carry every position a
// rule's file/line attribution can get wrong: two hunks in one Go file, a match
// on an added line in each, a removed line that matches (and must not be
// reported, because a removed line has no new-file position), a CONTEXT line
// that matches (and must not be reported, because the rules read what the
// change adds), and a second file whose added line matches.
const diffTwoFiles = `diff --git a/main.go b/main.go
index 1111111..2222222 100644
--- a/main.go
+++ b/main.go
@@ -1,4 +1,5 @@
package main
-func greet() { println("hi") }
+func greet() { println("hi") }
+func boom() { panic("boom") }
// panic( mentioned in a kept comment
func main() { greet() }
@@ -20,3 +22,3 @@ func tail() {
keep(t)
- panic("old")
+ panic("later")
}
diff --git a/notes.md b/notes.md
index 3333333..4444444 100644
--- a/notes.md
+++ b/notes.md
@@ -1,1 +1,2 @@
# notes
+panic( in a doc line
`
// diffTestFile is a change whose only matching added line is in a _test.go
// file, so a rule's exclude_path is the difference between parking and not.
const diffTestFile = `diff --git a/main_test.go b/main_test.go
index 5555555..6666666 100644
--- a/main_test.go
+++ b/main_test.go
@@ -1,1 +1,2 @@
package main
+func TestBoom(t *testing.T) { panic("boom") }
`
// stepSettingsNode decodes a step's settings the way ParseDefinition hands them
// to a factory. An empty src is the zero Node a step written without a settings
// key carries, which is not the same value as an empty mapping.
func stepSettingsNode(t *testing.T, src string) yaml.Node {
t.Helper()
if src == "" {
return yaml.Node{}
}
var document yaml.Node
if err := yaml.Unmarshal([]byte(src), &document); err != nil {
t.Fatalf("parse settings YAML: %v", err)
}
if len(document.Content) != 1 {
t.Fatalf("settings YAML decoded to %d nodes, want one", len(document.Content))
}
return *document.Content[0]
}
// diffRulesStage builds the stage through the registered step type's factory,
// so no test can drive a stage the YAML route could not compile.
func diffRulesStage(t *testing.T, settingsYAML string) (Stage, error) {
t.Helper()
return DiffRulesStepType().Factory(stepSettingsNode(t, settingsYAML))
}
// diffRulesTaskContext is the minimum a diff-rules stage runs against: a
// prepared worktree, a base branch to diff against, and a log to read back.
func diffRulesTaskContext(diff string, log *bytes.Buffer) *TaskContext {
return &TaskContext{
Task: &Task{ID: 1, Owner: "acme", Repo: "todo", IssueNumber: 42},
Repo: config.Repo{Owner: "acme", Name: "todo", Base: "main"},
Trees: &fakeTrees{diff: diff},
Dir: "/tmp/diff-rules-worktree",
Log: slog.New(slog.NewTextHandler(log, nil)),
}
}
// TestDiffRulesStepTypeIsRegisteredAndNamesItself pins the identity the
// vocabulary is keyed on: the word an operator writes in YAML, and the stage
// name that appears in the run's events -- they are the same name, so a
// workflow definition and the timeline agree about which step ran.
func TestDiffRulesStepTypeIsRegisteredAndNamesItself(t *testing.T) {
t.Parallel()
stepType := DiffRulesStepType()
if stepType.Name != DiffRulesStepName {
t.Errorf("step type name = %q, want %q", stepType.Name, DiffRulesStepName)
}
if DiffRulesStepName != "gate.diff-rules" {
t.Errorf("DiffRulesStepName = %q, want the registered vocabulary word %q", DiffRulesStepName, "gate.diff-rules")
}
stage, err := diffRulesStage(t, "rules:\n - level: error\n pattern: 'panic\\('\n message: no new panic\n")
if err != nil {
t.Fatalf("factory: %v", err)
}
if stage.Name != stepType.Name {
t.Errorf("compiled stage = %q, want the step type's own name %q", stage.Name, stepType.Name)
}
if stage.Run == nil {
t.Error("compiled stage has no Run: it would silently do nothing")
}
}
// TestDiffRulesStepRefusesSettingsItCannotApply is the validation contract, and
// it is where invalid state has to be refused: a stored definition that reaches
// a run is compiled on the executing side, so a setting this step cannot apply
// must fail at the factory -- during validation and compile -- rather than be
// quietly dropped when the stage runs.
func TestDiffRulesStepRefusesSettingsItCannotApply(t *testing.T) {
t.Parallel()
tests := []struct {
name string
settings string
want string
}{
{
name: "no settings at all",
want: "requires settings",
},
{
name: "no rules",
settings: "rules: []",
want: "at least one rule",
},
{
name: "rules key with no rules in it",
settings: "rules:",
want: "at least one rule",
},
{
name: "settings that are not a mapping",
settings: "- rules",
want: DiffRulesStepName + " settings",
},
{
name: "settings that are a scalar",
settings: "just text",
want: DiffRulesStepName + " settings",
},
{
name: "unknown settings key",
settings: "rulez:\n - level: error\n pattern: 'x'\n message: m\n",
want: "rulez",
},
{
name: "rule with no level",
settings: "rules:\n - pattern: 'x'\n message: m\n",
want: "level is required",
},
{
name: "rule with an unknown level",
settings: "rules:\n - level: fatal\n pattern: 'x'\n message: m\n",
want: `unknown level "fatal"`,
},
{
name: "rule with an unknown key",
settings: "rules:\n - level: error\n pattern: 'x'\n message: m\n severity: high\n",
want: "severity",
},
{
name: "rule with no pattern",
settings: "rules:\n - level: error\n message: m\n",
want: "pattern is required",
},
{
name: "rule with a pattern that is not a regex",
settings: "rules:\n - level: error\n pattern: 'panic('\n message: m\n",
want: "pattern",
},
{
name: "rule with no message",
settings: "rules:\n - level: error\n pattern: 'x'\n",
want: "message is required",
},
{
name: "rule with a path that is not a regex",
settings: "rules:\n - level: error\n pattern: 'x'\n message: m\n path: '('\n",
want: "path",
},
{
name: "rule with an exclude_path that is not a regex",
settings: "rules:\n - level: error\n pattern: 'x'\n message: m\n exclude_path: '('\n",
want: "exclude_path",
},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
t.Parallel()
stage, err := diffRulesStage(t, test.settings)
if err == nil {
t.Fatalf("factory accepted unusable settings and built %q; want a refusal naming %q", stage.Name, test.want)
}
if !strings.Contains(err.Error(), test.want) {
t.Errorf("factory error = %v, want it to name %q", err, test.want)
}
})
}
}
// TestDiffRulesStepAppliesRulesToTheCommittedDiff is the behaviour contract: the
// rules read the diff against the base branch, report the added lines they
// match with their new-file line numbers, park the run on an error-level
// finding, and leave a warn-level one advisory.
func TestDiffRulesStepAppliesRulesToTheCommittedDiff(t *testing.T) {
t.Parallel()
panicRule := "rules:\n" +
" - id: no-new-panic\n" +
" level: error\n" +
" pattern: 'panic\\('\n" +
" message: new panic() call -- use error returns instead\n"
tests := []struct {
name string
settings string
diff string
wantParked bool
wantDetail []string
omitDetail []string
wantLog []string
omitLog []string
}{
{
name: "an error rule reports every added line it matches",
settings: panicRule,
diff: diffTwoFiles,
wantParked: true,
wantDetail: []string{
"main.go:3: new panic() call",
"main.go:23: new panic() call",
"notes.md:2: new panic() call",
"(no-new-panic)",
},
// The removed line is at old-file line 21 and the kept comment is at
// new-file line 4: neither is something this change added.
omitDetail: []string{"main.go:21", "main.go:4:", "notes.md:1"},
wantLog: []string{"rule_level=error", "file=main.go line=3", "rule=no-new-panic"},
},
{
name: "a warn rule is advisory",
settings: "rules:\n - id: advisory\n level: warn\n pattern: 'panic\\('\n message: consider error returns\n",
diff: diffTwoFiles,
wantParked: false,
wantLog: []string{"rule_level=warn", "file=main.go line=3", "consider error returns"},
},
{
name: "a rule that matches nothing is a no-op",
settings: "rules:\n - level: error\n pattern: 'this appears nowhere'\n message: unreachable\n",
diff: diffTwoFiles,
wantParked: false,
omitLog: []string{"unreachable"},
},
{
name: "context lines are not added lines",
settings: "rules:\n - level: error\n pattern: 'mentioned in a kept comment'\n message: kept comment matched\n",
diff: diffTwoFiles,
wantParked: false,
omitDetail: []string{"main.go:4"},
omitLog: []string{"kept comment matched"},
},
{
name: "a path scope keeps the rule off other files",
settings: "rules:\n - level: error\n pattern: 'panic\\('\n path: '\\.go$'\n message: go only\n",
diff: diffTwoFiles,
wantParked: true,
wantDetail: []string{"main.go:3", "go only"},
omitDetail: []string{"notes.md:2"},
},
{
name: "an exclude_path spares the files it names",
settings: "rules:\n - level: error\n pattern: 'panic\\('\n path: '\\.go$'\n exclude_path: '_test\\.go$'\n message: production code only\n",
diff: diffTestFile,
wantParked: false,
omitLog: []string{"production code only"},
},
{
name: "the same rule without the exclude_path matches the test file",
settings: "rules:\n - level: error\n pattern: 'panic\\('\n path: '\\.go$'\n message: any go file\n",
diff: diffTestFile,
wantParked: true,
wantDetail: []string{"main_test.go:2", "any go file"},
},
{
name: "no committed change is a no-op",
settings: panicRule,
diff: "",
wantParked: false,
omitLog: []string{"no-new-panic"},
},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
t.Parallel()
stage, err := diffRulesStage(t, test.settings)
if err != nil {
t.Fatalf("factory: %v", err)
}
var log bytes.Buffer
tc := diffRulesTaskContext(test.diff, &log)
if err := stage.Run(context.Background(), tc); err != nil {
t.Fatalf("stage.Run() = %v, want nil: a finding is a verdict about the task, not a stage failure", err)
}
detail := tc.Outcome.Detail
if test.wantParked {
if tc.Outcome.Status != StatusParked {
t.Fatalf("Outcome = %+v, want a parked outcome", tc.Outcome)
}
} else if tc.Outcome.Status != "" {
t.Errorf("Outcome = %+v, want no outcome: nothing the change did violated the rules", tc.Outcome)
}
for _, want := range test.wantDetail {
if !strings.Contains(detail, want) {
t.Errorf("park Detail = %q, want it to contain %q", detail, want)
}
}
for _, omit := range test.omitDetail {
if strings.Contains(detail, omit) {
t.Errorf("park Detail = %q, want it NOT to contain %q", detail, omit)
}
}
for _, want := range test.wantLog {
if !strings.Contains(log.String(), want) {
t.Errorf("log = %q, want it to contain %q", log.String(), want)
}
}
for _, omit := range test.omitLog {
if strings.Contains(log.String(), omit) {
t.Errorf("log = %q, want it NOT to contain %q", log.String(), omit)
}
}
})
}
}
// TestDiffRulesStepRequiresAPreparedWorktree pins the wiring failure a
// mis-ordered definition produces: a step placed before the workflow prepared a
// worktree has nothing to diff, and must say so instead of handing git an empty
// directory and parking with a git error.
func TestDiffRulesStepRequiresAPreparedWorktree(t *testing.T) {
t.Parallel()
stage, err := diffRulesStage(t, "rules:\n - level: error\n pattern: 'x'\n message: m\n")
if err != nil {
t.Fatalf("factory: %v", err)
}
var log bytes.Buffer
tc := diffRulesTaskContext("", &log)
tc.Dir = ""
err = stage.Run(context.Background(), tc)
if err == nil {
t.Fatal("stage.Run() = nil with no worktree, want the wiring failure")
}
if !strings.Contains(err.Error(), "worktree") {
t.Errorf("stage.Run() error = %v, want it to name the missing worktree", err)
}
}
// TestDiffRulesStepPropagatesTheDiffFailure pins that a diff this stage could
// not read is an execution failure, not a clean change: reporting "no findings"
// because the read failed would pass a gate that never ran.
func TestDiffRulesStepPropagatesTheDiffFailure(t *testing.T) {
t.Parallel()
stage, err := diffRulesStage(t, "rules:\n - level: error\n pattern: 'x'\n message: m\n")
if err != nil {
t.Fatalf("factory: %v", err)
}
var log bytes.Buffer
tc := diffRulesTaskContext("", &log)
tc.Trees = &fakeTrees{diffErr: errDiffUnavailable}
err = stage.Run(context.Background(), tc)
if err == nil {
t.Fatal("stage.Run() = nil when the diff could not be read, want the read failure")
}
if !strings.Contains(err.Error(), "diff") {
t.Errorf("stage.Run() error = %v, want it to name the diff it could not read", err)
}
if tc.Outcome.Status != "" {
t.Errorf("Outcome = %+v, want none: a read failure is not a verdict", tc.Outcome)
}
}
// TestAddedDiffLinesAttributesNewFilePositions drives the walker on its own,
// because the line a finding carries is the difference between an operator
// being able to find the violation and not.
func TestAddedDiffLinesAttributesNewFilePositions(t *testing.T) {
t.Parallel()
tests := []struct {
name string
diff string
want []diffLine
}{
{
name: "one hunk",
diff: "diff --git a/a.go b/a.go\n--- a/a.go\n+++ b/a.go\n@@ -1,2 +1,3 @@\n package a\n+var b = 1\n var c = 2\n",
want: []diffLine{{Path: "a.go", Line: 2, Text: "var b = 1"}},
},
{
name: "a second hunk keeps counting from its own header",
diff: "diff --git a/a.go b/a.go\n--- a/a.go\n+++ b/a.go\n@@ -1,1 +1,2 @@\n package a\n+var b = 1\n@@ -40,1 +41,2 @@\n func f() {}\n+func g() {}\n",
want: []diffLine{{Path: "a.go", Line: 2, Text: "var b = 1"}, {Path: "a.go", Line: 42, Text: "func g() {}"}},
},
{
name: "a removed line advances no new-file position",
diff: "diff --git a/a.go b/a.go\n--- a/a.go\n+++ b/a.go\n@@ -1,3 +1,2 @@\n package a\n-var gone = 1\n+var kept = 2\n var tail = 3\n",
want: []diffLine{{Path: "a.go", Line: 2, Text: "var kept = 2"}},
},
{
name: "a header for the next file moves the path, not the position",
diff: "diff --git a/a.go b/a.go\n--- a/a.go\n+++ b/a.go\n@@ -1,1 +1,2 @@\n package a\n+var b = 1\ndiff --git a/b.go b/b.go\n--- a/b.go\n+++ b/b.go\n@@ -1,1 +1,2 @@\n package b\n+var c = 2\n",
want: []diffLine{{Path: "a.go", Line: 2, Text: "var b = 1"}, {Path: "b.go", Line: 2, Text: "var c = 2"}},
},
{
// A body line whose own text begins with the file-header marker is
// still a body line: inside a hunk, `+++ x` is the added line `++ x`.
name: "an added line that looks like a file header is body text",
diff: "diff --git a/a.md b/a.md\n--- a/a.md\n+++ b/a.md\n@@ -1,1 +1,2 @@\n # a\n+++ title\n",
want: []diffLine{{Path: "a.md", Line: 2, Text: "++ title"}},
},
{
name: "no newline marker is not a line",
diff: "diff --git a/a.go b/a.go\n--- a/a.go\n+++ b/a.go\n@@ -1,1 +1,2 @@\n package a\n+var b = 1\n\\ No newline at end of file\n",
want: []diffLine{{Path: "a.go", Line: 2, Text: "var b = 1"}},
},
{
name: "an empty diff adds nothing",
diff: "",
want: nil,
},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
t.Parallel()
got := addedDiffLines(test.diff)
if len(got) != len(test.want) {
t.Fatalf("addedDiffLines() = %+v, want %+v", got, test.want)
}
for i := range got {
if got[i] != test.want[i] {
t.Errorf("addedDiffLines()[%d] = %+v, want %+v", i, got[i], test.want[i])
}
}
})
}
}
// diffRulesTestTaskContext is the same context a diff-rules stage runs against,
// for a test that drives a real worktree instead of a fake one.
func diffRulesTestTaskContext(t *testing.T, dir string, log *bytes.Buffer) *TaskContext {
t.Helper()
tc := diffRulesTaskContext("", log)
tc.Dir = dir
return tc
}
// TestDiffRulesStepReadsARealDiff drives the step against the production Trees
// implementation rather than a fixture: every other test here feeds a
// hand-written unified diff, and the positions a rule reports have to survive
// what a real worktree actually emits -- headers, index lines and all.
func TestDiffRulesStepReadsARealDiff(t *testing.T) {
t.Parallel()
dir := gitRepoWithOriginRef(t, "main")
added := "package main\n\nvar a = 1\n\nfunc boom() { panic(\"boom\") }\n"
if err := os.WriteFile(filepath.Join(dir, "main.go"), []byte(added), 0o644); err != nil {
t.Fatal(err)
}
runGit(t, dir, "add", "-A")
runGit(t, dir, "commit", "-m", "add panic")
stage, err := diffRulesStage(t, "rules:\n - id: no-new-panic\n level: error\n pattern: 'panic\\('\n message: new panic() call\n")
if err != nil {
t.Fatalf("factory: %v", err)
}
var log bytes.Buffer
tc := diffRulesTestTaskContext(t, dir, &log)
tc.Trees = &worktree.Manager{WorkDir: t.TempDir()}
if err := stage.Run(context.Background(), tc); err != nil {
t.Fatalf("stage.Run(): %v", err)
}
if tc.Outcome.Status != StatusParked {
t.Fatalf("Outcome = %+v, want a parked outcome for the added panic", tc.Outcome)
}
// The panic is on line 5 of the file the change produces. A walker that
// counted the diff's own offsets would report a different number.
if !strings.Contains(tc.Outcome.Detail, "main.go:5: new panic() call") {
t.Errorf("park Detail = %q, want it to locate the added line as main.go:5", tc.Outcome.Detail)
}
}
+5 -1
View File
@@ -459,6 +459,10 @@ type fakeTrees struct {
dir string
// changedLines is what ChangedLines reports, for StageDiffCap.
changedLines int
// diff is what Diff reports, for the stages that read the committed
// change (StageReview, the diff-rules step).
diff string
diffErr error
resumed bool
resumeDir string
@@ -483,7 +487,7 @@ func (f *fakeTrees) Push(_ context.Context, _, branch string) error {
return nil
}
func (f *fakeTrees) Diff(context.Context, string, string) (string, error) { return "", nil }
func (f *fakeTrees) Diff(context.Context, string, string) (string, error) { return f.diff, f.diffErr }
func (f *fakeTrees) ChangedFiles(context.Context, string, string) ([]string, error) { return nil, nil }
@@ -38,6 +38,24 @@ func (shippedStages) StepTypes() []workflow.StepType {
return stepTypes
}
// repoHooks is the provider that contributes the step types replacing the
// repository-authored hooks that were deleted with the interpreted workflow
// engine -- .archie/gate.go, whose rules now arrive as settings on
// workflow.DiffRulesStepName instead of as Go read out of the worktree being
// worked on.
//
// It is a provider of its own rather than part of shippedStages, which is
// scoped to the stages of the shipped workflows: a repository's migration target
// is not part of any shipped workflow, and a root that bundles one set should be
// able to tell which set a step type came from.
type repoHooks struct{}
func (repoHooks) Name() string { return "repo-hooks" }
func (repoHooks) StepTypes() []workflow.StepType {
return []workflow.StepType{workflow.DiffRulesStepType()}
}
// Providers returns the provider set the roots that resolve a workflow step
// type register at their composition root, before the first resolution: it is
// what NewManager registers, and what the roots' guards read to hold a
@@ -53,7 +71,7 @@ func (shippedStages) StepTypes() []workflow.StepType {
// provider_secrets.go). Until one exists for step types, adding a step type
// means adding a provider here.
func Providers() []workflow.StepTypeProvider {
return []workflow.StepTypeProvider{shippedStages{}}
return []workflow.StepTypeProvider{shippedStages{}, repoHooks{}}
}
// NewManager builds this process's workflow step-type manager by registering
@@ -134,3 +134,58 @@ func TestNewManagerIsRepeatableWithinOneProcess(t *testing.T) {
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)
}
}