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

Part of archie-core-8szi. Restores the deleted .archie/gate.go Check() behaviour
as a registered, declarative workflow step type: RE2 rules matched against the
committed diff, per-rule level (error parks with findings in Detail, warn logs),
file:line preserved, registered through the workflowsteps provider set. The
.archie/stages equivalent (an argv-running step) is deliberately not landed and
is held for the maintainer's trust-boundary decision.
This commit is contained in:
sam committed 2026-09-21 20:35:22 +10:00
commit ff4239e79e
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.SplitSeq(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 after, ok := strings.CutPrefix(raw, "+++ "); ok {
path = diffTargetPath(after)
}
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) {
_, after, ok := strings.Cut(header, " +")
if !ok {
return 0, false
}
rest := after
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)
}
}