@getarbiter/cli 0.5.0

package/dist/templates/behavioral-tests/TESTING_POLICY.md.ejs

@@ -0,0 +1,116 @@
+# Testing Policy — <%= projectName %>
+
+> Generated by arbiter. Update sections marked **[CUSTOMIZE]** for your project.
+
+---
+
+## Test Pyramid
+
+| Level | Scope | Tools | Speed |
+|-------|-------|-------|-------|
+| L1 — Unit | Single function / class | <% if (language === 'java') { %>JUnit5, AssertJ<% } else if (language === 'typescript') { %>Vitest<% } else if (language === 'rust') { %>cargo test<% } else if (language === 'go') { %>go test<% } else if (language === 'python') { %>pytest<% } else { %>language test runner<% } %> | Fast (<1s each) |
+| L2 — Architecture | Module boundaries, imports | <% if (language === 'java') { %>ArchUnit<% } else if (language === 'typescript') { %>eslint-plugin-boundaries<% } else if (language === 'rust') { %>cargo-deny, clippy<% } else if (language === 'go') { %>golangci-lint<% } else if (language === 'python') { %>import-linter, ruff<% } else { %>architecture tooling<% } %> | Medium (<10s) |
+<% if (governanceLevel !== 'L1') { %>| L3 — Integration | Cross-module, database, messaging | <% if (language === 'java') { %>JUnit5 IT + Testcontainers<% } else if (language === 'typescript') { %>Vitest integration + Testcontainers<% } else if (language === 'rust') { %>Testcontainers-rs<% } else if (language === 'go') { %>testcontainers-go<% } else if (language === 'python') { %>pytest + testcontainers-python<% } else { %>Testcontainers<% } %> | Slow (requires containers) |
+<% } %><% if (governanceLevel !== 'L1') { %>| L4 — E2E | Full system via public interface | <% if (language === 'typescript') { %>Playwright<% } else if (language === 'java') { %>RestAssured<% } else { %>HTTP client against running service<% } %> | Slowest (full stack) |
+<% } %>
+---
+
+## Mock Policy
+
+### What CAN be mocked
+
+- External third-party APIs (payment, email, SMS, maps, weather)
+- External authentication providers when running unit tests
+- Outbound HTTP to services outside the system boundary
+
+### What CANNOT be mocked
+
+- Core domain logic — test the real implementation
+- Internal application services — inject real or in-memory fakes, not mocks
+<% if (hasDatabase) { %>- Database — use Testcontainers for a real database at L2+ (see INV-34)
+<% } %>- Auth layer — test with a real user context or test token
+
+**Rule:** if you are mocking to make a test easier to write, ask whether the design needs to change instead.
+
+---
+
+<% if (governanceLevel !== 'L1') { %>
+## E2E Policy
+
+- Core API endpoints (`/api/*` or equivalent) must be tested against the **real running service**
+- Mocking core API responses in E2E tests is **prohibited** — it tests the mock, not the system
+- External providers (payment, email) MAY be stubbed via WireMock or equivalent
+- Minimum smoke test set (mandatory before each release):
+  1. Authentication flow (login / token refresh)
+  2. Core CRUD operation
+  3. Authorization enforcement (role or permission check)
+
+<% } %>
+---
+
+## Test Naming Convention
+
+<% if (language === 'java') { %>
+| Type | Pattern | Example |
+|------|---------|---------|
+| Unit test | `*Test.java` | `OrderServiceTest.java` |
+| Integration test | `*IT.java` | `OrderRepositoryIT.java` |
+| Architecture test | `*ArchTest.java` | `DependencyFlowArchTest.java` |
+
+Method names: `given_<context>_when_<action>_then_<expected>` or use `@DisplayName`.
+<% } else if (language === 'typescript') { %>
+| Type | Pattern | Example |
+|------|---------|---------|
+| Unit / integration | `*.test.ts` | `orderService.test.ts` |
+| E2E / component | `*.spec.ts` | `checkout.spec.ts` |
+
+Describe blocks: outer = subject, inner = context (`given X`). `it()` = behaviour (`when Y then Z`).
+<% } else if (language === 'rust') { %>
+| Type | Pattern | Example |
+|------|---------|---------|
+| Unit (inline) | `mod tests { }` inside `src/` | — |
+| Integration | `*_test.rs` in `tests/` | `order_service_test.rs` |
+
+Function names: `given_<context>_when_<action>_then_<expected>`.
+<% } else if (language === 'go') { %>
+| Type | Pattern | Example |
+|------|---------|---------|
+| All tests | `*_test.go` | `order_service_test.go` |
+
+Use `t.Run("given X / when Y / then Z", ...)` for behavioural subtests.
+<% } else if (language === 'python') { %>
+| Type | Pattern | Example |
+|------|---------|---------|
+| Test file | `test_*.py` | `test_order_service.py` |
+| Test class | `class Test<Subject>` | `class TestOrderService` |
+| Test method | `def test_<behaviour>` | `def test_when_empty_returns_zero` |
+<% } %>
+
+---
+
+## Coverage Targets
+
+<% if (governanceLevel === 'L1') { %>
+| Level | Target |
+|-------|--------|
+| L1 (minimum) | 70% line coverage |
+
+<% } else if (governanceLevel === 'L2') { %>
+| Level | Target |
+|-------|--------|
+| L1 (minimum) | 70% line coverage |
+| L2 (standard) | 80% line coverage |
+
+<% } else { %>
+| Level | Target |
+|-------|--------|
+| L1 (minimum) | 70% line coverage |
+| L2 (standard) | 80% line coverage |
+| L3 (full audit) | 85% line coverage + mutation score ≥ 70% |
+
+<% } %>
+Coverage is enforced by the gate (`node scripts/check-all.mjs L2`).
+
+---
+
+*[CUSTOMIZE] — adjust thresholds and patterns to match your team's standards.*

package/dist/templates/behavioral-tests/bdd/ExampleBddIT.java.ejs

@@ -0,0 +1,19 @@
+package <%= locals.basePackage || 'com.example' %>.bdd;
+
+import io.cucumber.junit.platform.engine.Constants;
+import org.junit.platform.suite.api.ConfigurationParameter;
+import org.junit.platform.suite.api.IncludeEngines;
+import org.junit.platform.suite.api.SelectClasspathResource;
+import org.junit.platform.suite.api.Suite;
+
+@Suite
+@IncludeEngines("cucumber")
+@SelectClasspathResource("features")
+@ConfigurationParameter(key = Constants.PLUGIN_PROPERTY_NAME, value = "pretty")
+@ConfigurationParameter(
+        key = Constants.FEATURES_PROPERTY_NAME,
+        value = "src/test/resources/features")
+public class ExampleBddIT {
+    // Cucumber JUnit Platform Engine discovers and runs all .feature files
+    // under src/test/resources/features/. Add step definitions in the same package.
+}

package/dist/templates/behavioral-tests/bdd/ExampleSteps.java.ejs

@@ -0,0 +1,61 @@
+package <%= locals.basePackage || 'com.example' %>.bdd;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.util.Optional;
+import io.cucumber.java.en.Given;
+import io.cucumber.java.en.Then;
+import io.cucumber.java.en.When;
+
+/**
+ * Step definitions for example.feature — glue code for ExampleBddIT's Cucumber suite. Without
+ * these, the scenarios resolve as UNDEFINED and Cucumber-JVM fails the run (strict-by-default), so
+ * this file is load-bearing for the generated project's default `test` task, not just
+ * documentation.
+ */
+public class ExampleSteps {
+
+    private static final String EMPTY = "";
+    private static final String INVALID_INPUT = "invalid";
+    private static final String INVALID_INPUT_ERROR = "invalid input";
+    private static final String SUCCESS = "success";
+    private static final String VALID_INPUT = "valid";
+
+    private String input = EMPTY;
+    private String result = EMPTY;
+    private Optional<String> error = Optional.empty();
+
+    @Given("a valid input")
+    public void aValidInput() {
+        input = VALID_INPUT;
+        error = Optional.empty();
+    }
+
+    @Given("an invalid input")
+    public void anInvalidInput() {
+        input = INVALID_INPUT;
+        error = Optional.empty();
+    }
+
+    @When("the operation is executed")
+    public void theOperationIsExecuted() {
+        if (VALID_INPUT.equals(input)) {
+            result = SUCCESS;
+            error = Optional.empty();
+        } else {
+            result = EMPTY;
+            error = Optional.of(INVALID_INPUT_ERROR);
+        }
+    }
+
+    @Then("the result is successful")
+    public void theResultIsSuccessful() {
+        assertThat(result).isEqualTo(SUCCESS);
+        assertThat(error).isEmpty();
+    }
+
+    @Then("an error is returned")
+    public void anErrorIsReturned() {
+        assertThat(error).contains(INVALID_INPUT_ERROR);
+    }
+}

package/dist/templates/behavioral-tests/bdd/example.feature.ejs

@@ -0,0 +1,14 @@
+Feature: Example feature
+  As a user of <%= projectName %>
+  I want to see a working BDD example
+  So that I can extend it with real scenarios
+
+  Scenario: Successful operation
+    Given a valid input
+    When the operation is executed
+    Then the result is successful
+
+  Scenario: Invalid input is rejected
+    Given an invalid input
+    When the operation is executed
+    Then an error is returned

package/dist/templates/behavioral-tests/bdd/example.steps.ts.ejs

@@ -0,0 +1,37 @@
+import { Given, When, Then } from '@cucumber/cucumber';
+import assert from 'node:assert/strict';
+
+interface ExampleWorld {
+  input: string;
+  result: string;
+  error: string | null;
+}
+
+Given('a valid input', function (this: ExampleWorld) {
+  this.input = 'valid';
+  this.error = null;
+});
+
+Given('an invalid input', function (this: ExampleWorld) {
+  this.input = 'invalid';
+  this.error = null;
+});
+
+When('the operation is executed', function (this: ExampleWorld) {
+  if (this.input === 'valid') {
+    this.result = 'success';
+    this.error = null;
+  } else {
+    this.result = '';
+    this.error = 'invalid input';
+  }
+});
+
+Then('the result is successful', function (this: ExampleWorld) {
+  assert.equal(this.result, 'success');
+  assert.equal(this.error, null);
+});
+
+Then('an error is returned', function (this: ExampleWorld) {
+  assert.ok(this.error, 'Expected an error but got none');
+});

package/dist/templates/behavioral-tests/bdd/example_bdd_test.rs.ejs

@@ -0,0 +1,64 @@
+// BDD suite — gated behind the `bdd` cargo feature. `cargo test` compiles every
+// file under tests/ as an integration crate, so the cucumber/tokio imports below
+// would break the DEFAULT build (the gate's `unit tests` check) until the deps
+// are wired. The crate-level cfg compiles this file to EMPTY unless the project
+// declares a `bdd` feature; the gate runs it with `cargo test --features bdd`.
+// Mirrors the Go `//go:build bdd` tag and Python `importorskip` graceful skip.
+//
+// To enable, add to Cargo.toml:
+//   [features]
+//   bdd = []
+//   [dev-dependencies]
+//   cucumber = "0.21"
+//   tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+//   [[test]]
+//   name = "example_bdd_test"
+//   harness = false
+#![cfg(feature = "bdd")]
+use cucumber::{given, then, when, World};
+
+#[derive(Debug, Default, World)]
+pub struct ExampleWorld {
+    input: String,
+    result: String,
+    error: Option<String>,
+}
+
+#[given("a valid input")]
+async fn valid_input(world: &mut ExampleWorld) {
+    world.input = "valid".to_string();
+    world.error = None;
+}
+
+#[given("an invalid input")]
+async fn invalid_input(world: &mut ExampleWorld) {
+    world.input = "invalid".to_string();
+    world.error = None;
+}
+
+#[when("the operation is executed")]
+async fn execute_operation(world: &mut ExampleWorld) {
+    if world.input == "valid" {
+        world.result = "success".to_string();
+        world.error = None;
+    } else {
+        world.result = String::new();
+        world.error = Some("invalid input".to_string());
+    }
+}
+
+#[then("the result is successful")]
+async fn result_is_successful(world: &mut ExampleWorld) {
+    assert_eq!(world.result, "success");
+    assert!(world.error.is_none());
+}
+
+#[then("an error is returned")]
+async fn error_is_returned(world: &mut ExampleWorld) {
+    assert!(world.error.is_some(), "Expected an error but got none");
+}
+
+#[tokio::main]
+async fn main() {
+    ExampleWorld::run("tests/features/example.feature").await;
+}

package/dist/templates/behavioral-tests/bdd/example_test.go.ejs

@@ -0,0 +1,80 @@
+//go:build bdd
+// +build bdd
+
+// BDD suite — guarded by the `bdd` build tag so the unresolved
+// github.com/cucumber/godog import does NOT break the default build. The
+// generated gate runs it explicitly with `go test -tags bdd ./internal/bdd/...`
+// (see scripts/check-all.mjs), while `go vet/test/staticcheck ./...`, coverage
+// and complexity all skip it cleanly until the dependency is wired. Mirrors the
+// Python suite's `pytest.importorskip("pytest_bdd")` graceful-skip pattern.
+package bdd_test
+
+import (
+	"context"
+	"fmt"
+	"testing"
+
+	"github.com/cucumber/godog"
+)
+
+type exampleState struct {
+	input  string
+	result string
+	err    error
+}
+
+func (s *exampleState) aValidInput(ctx context.Context) (context.Context, error) {
+	s.input = "valid"
+	s.err = nil
+	return ctx, nil
+}
+
+func (s *exampleState) anInvalidInput(ctx context.Context) (context.Context, error) {
+	s.input = "invalid"
+	s.err = nil
+	return ctx, nil
+}
+
+func (s *exampleState) theOperationIsExecuted(ctx context.Context) (context.Context, error) {
+	if s.input == "valid" {
+		s.result = "success"
+	} else {
+		s.result = ""
+		s.err = fmt.Errorf("invalid input")
+	}
+	return ctx, nil
+}
+
+func (s *exampleState) theResultIsSuccessful(ctx context.Context) (context.Context, error) {
+	if s.result != "success" {
+		return ctx, fmt.Errorf("expected success, got %q", s.result)
+	}
+	return ctx, nil
+}
+
+func (s *exampleState) anErrorIsReturned(ctx context.Context) (context.Context, error) {
+	if s.err == nil {
+		return ctx, fmt.Errorf("expected an error but got none")
+	}
+	return ctx, nil
+}
+
+func InitializeScenario(ctx *godog.ScenarioContext) {
+	s := &exampleState{}
+	ctx.Step(`^a valid input$`, s.aValidInput)
+	ctx.Step(`^an invalid input$`, s.anInvalidInput)
+	ctx.Step(`^the operation is executed$`, s.theOperationIsExecuted)
+	ctx.Step(`^the result is successful$`, s.theResultIsSuccessful)
+	ctx.Step(`^an error is returned$`, s.anErrorIsReturned)
+}
+
+func TestSuite(t *testing.T) {
+	suite := godog.TestSuite{
+		Name:                "example",
+		ScenarioInitializer: InitializeScenario,
+		Options:             &godog.Options{Format: "pretty", Paths: []string{"../../features"}},
+	}
+	if suite.Run() != 0 {
+		t.Fatal("BDD scenarios failed")
+	}
+}

package/dist/templates/behavioral-tests/bdd/test_example_bdd.py.ejs

@@ -0,0 +1,47 @@
+"""BDD tests using pytest-bdd — binds to features/example.feature.
+
+`pytest-bdd` is an L2 (full-gate) dependency, not part of the L1 fast gate's
+toolchain. `importorskip` makes a plain `pytest` run (the L1 unit-tests check)
+SKIP this module cleanly when pytest-bdd is not installed, instead of failing
+collection with ModuleNotFoundError — so the freshly-scaffolded project is green
+on its first `check-all.mjs L1`. With pytest-bdd installed (L2), it runs in full.
+"""
+
+import pytest
+
+pytest.importorskip("pytest_bdd")
+
+from pytest_bdd import scenarios, given, when, then  # noqa: E402
+
+scenarios("features/example.feature")
+
+
+@given("a valid input", target_fixture="context")
+def valid_input():
+    return {"input": "valid", "result": None, "error": None}
+
+
+@given("an invalid input", target_fixture="context")
+def invalid_input():
+    return {"input": "invalid", "result": None, "error": None}
+
+
+@when("the operation is executed")
+def execute_operation(context):
+    if context["input"] == "valid":
+        context["result"] = "success"
+        context["error"] = None
+    else:
+        context["result"] = ""
+        context["error"] = "invalid input"
+
+
+@then("the result is successful")
+def result_is_successful(context):
+    assert context["result"] == "success"
+    assert context["error"] is None
+
+
+@then("an error is returned")
+def error_is_returned(context):
+    assert context["error"], "Expected an error but got none"

package/dist/templates/behavioral-tests/eslint-playwright.json.ejs

@@ -0,0 +1,10 @@
+{
+  "extends": ["plugin:playwright/recommended"],
+  "plugins": ["playwright"],
+  "rules": {
+    "playwright/no-force-option": "error",
+    "playwright/no-wait-for-timeout": "error",
+    "playwright/no-page-pause": "error",
+    "playwright/prefer-web-first-assertions": "warn"
+  }
+}

package/dist/templates/behavioral-tests/eslint.config.playwright.mjs.ejs

@@ -0,0 +1,29 @@
+// eslint.config.playwright.mjs — generated by arbiter (M27, ESLint v9 flat-config).
+// Run in isolation by check-all.mjs via
+// `eslint --config eslint.config.playwright.mjs --no-config-lookup src/**/*.spec.ts` so it
+// enforces ONLY the Playwright quality rules, independent of your main eslint.config.mjs.
+// The legacy .eslintrc-playwright.json is retained for tooling that still reads
+// eslintrc-format config but is NOT used by the gate (ESLint v9 removed
+// --no-eslintrc/-c, which broke this check on every project that installed the
+// plugin — #1491-class fix, mirrors eslint.config.static.mjs).
+// Requires: npm install -D eslint-plugin-playwright
+import tseslint from 'typescript-eslint'
+import playwright from 'eslint-plugin-playwright'
+
+export default [
+  {
+    languageOptions: {
+      parser: tseslint.parser,
+      ecmaVersion: 2022,
+      sourceType: 'module',
+    },
+    plugins: { playwright },
+    rules: {
+      ...playwright.configs['flat/recommended'].rules,
+      'playwright/no-force-option': 'error',
+      'playwright/no-wait-for-timeout': 'error',
+      'playwright/no-page-pause': 'error',
+      'playwright/prefer-web-first-assertions': 'warn',
+    },
+  },
+]

package/dist/templates/behavioral-tests/example.behavioral.test.ts.ejs

@@ -0,0 +1,47 @@
+/**
+ * Example of Given/When/Then behavioral test structure using Vitest.
+ *
+ * Pattern: outer describe = subject; nested describe = context (given X);
+ * it() = behaviour assertion (when Y then Z).
+ * Replace 'exampleSubject' with the function or module under test.
+ */
+import { describe, it, expect } from "vitest";
+
+describe("exampleSubject", () => {
+  describe("given a valid input", () => {
+    it("when processed, returns the expected result", () => {
+      // Arrange
+      const input = "hello";
+
+      // Act
+      const result = input.toUpperCase();
+
+      // Assert
+      expect(result).toBe("HELLO");
+    });
+
+    it("when chained, transforms correctly", () => {
+      // Arrange
+      const input = "  hello  ";
+
+      // Act
+      const result = input.trim().toUpperCase();
+
+      // Assert
+      expect(result).toBe("HELLO");
+    });
+  });
+
+  describe("given an empty input", () => {
+    it("when processed, returns empty string", () => {
+      // Arrange
+      const input = "";
+
+      // Act
+      const result = input.toUpperCase();
+
+      // Assert
+      expect(result).toBe("");
+    });
+  });
+});

package/dist/templates/behavioral-tests/example_behavioral_test.go.ejs

@@ -0,0 +1,51 @@
+// Example of Given/When/Then behavioral test structure for Go.
+//
+// Pattern: use t.Run() with "given X / when Y / then Z" names.
+// This makes test output readable and allows -run flag filtering.
+package example_test
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestExampleSubject(t *testing.T) {
+	t.Run("given a valid input / when processed / then returns uppercase", func(t *testing.T) {
+		// Arrange
+		input := "hello"
+
+		// Act
+		result := strings.ToUpper(input)
+
+		// Assert
+		if result != "HELLO" {
+			t.Errorf("expected HELLO, got %s", result)
+		}
+	})
+
+	t.Run("given a valid input / when trimmed and processed / then transforms correctly", func(t *testing.T) {
+		// Arrange
+		input := "  hello  "
+
+		// Act
+		result := strings.ToUpper(strings.TrimSpace(input))
+
+		// Assert
+		if result != "HELLO" {
+			t.Errorf("expected HELLO, got %s", result)
+		}
+	})
+
+	t.Run("given an empty input / when processed / then returns empty string", func(t *testing.T) {
+		// Arrange
+		input := ""
+
+		// Act
+		result := strings.ToUpper(input)
+
+		// Assert
+		if result != "" {
+			t.Errorf("expected empty, got %s", result)
+		}
+	})
+}

package/dist/templates/behavioral-tests/example_behavioral_test.rs.ejs

@@ -0,0 +1,47 @@
+/// Example of behavioral test structure for Rust.
+///
+/// Pattern: use descriptive function names in the form
+/// `given_<context>_when_<action>_then_<expected>`.
+/// Group related tests with a `mod` block.
+
+#[cfg(test)]
+mod given_valid_input {
+    #[test]
+    fn when_processed_then_returns_uppercase() {
+        // Arrange
+        let input = "hello";
+
+        // Act
+        let result = input.to_uppercase();
+
+        // Assert
+        assert_eq!(result, "HELLO");
+    }
+
+    #[test]
+    fn when_trimmed_and_processed_then_transforms_correctly() {
+        // Arrange
+        let input = "  hello  ";
+
+        // Act
+        let result = input.trim().to_uppercase();
+
+        // Assert
+        assert_eq!(result, "HELLO");
+    }
+}
+
+#[cfg(test)]
+mod given_empty_input {
+    #[test]
+    fn when_processed_then_returns_empty_string() {
+        // Arrange
+        let input = "";
+
+        // Act
+        let result = input.to_uppercase();
+
+        // Assert
+        assert!(result.is_empty());
+    }
+}

package/dist/templates/behavioral-tests/test_example_behavioral.py.ejs

@@ -0,0 +1,40 @@
+"""
+Example of Given/When/Then behavioral test structure using pytest.
+
+Pattern: class groups by context (given X); method names describe
+the behaviour (when_Y_then_Z). pytest discovers test_ prefixed methods.
+"""
+
+
+class TestGivenValidInput:
+    def test_when_processed_then_returns_uppercase(self) -> None:
+        # Arrange
+        input_value = "hello"
+
+        # Act
+        result = input_value.upper()
+
+        # Assert
+        assert result == "HELLO"
+
+    def test_when_stripped_and_processed_then_transforms_correctly(self) -> None:
+        # Arrange
+        input_value = "  hello  "
+
+        # Act
+        result = input_value.strip().upper()
+
+        # Assert
+        assert result == "HELLO"
+
+
+class TestGivenEmptyInput:
+    def test_when_processed_then_returns_empty_string(self) -> None:
+        # Arrange
+        input_value = ""
+
+        # Act
+        result = input_value.upper()
+
+        # Assert
+        assert result == ""