fun_ci 2.0.0-x86_64-linux

data/lib/fun_ci/setup/agent_instructions.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Setup
+    # What `fun-ci init` tells a coding agent working in the project, in the
+    # instructions file agents read (acceptance-tests.md, AT-9.15): AGENTS.md,
+    # or CLAUDE.md when that is the only one. The marker keeps it to once.
+    module AgentInstructions
+      MARKER = "<!-- fun-ci: agent instructions -->"
+      SECTION = <<~MD.freeze
+        ## fun-ci
+
+        #{MARKER}
+        This project runs fun-ci on every commit. After each commit, run the
+        `fun-ci wait` command it prints, in the background, and act on its exit
+        code: 0 passed, 1 failed, 2 over budget, 3 undecided, 4 superseded.
+        `fun-ci wait --need all` must exit 0 before the work is called done.
+        `fun-ci runs` lists recent runs, and `fun-ci status` says where one stands.
+      MD
+
+      def self.file_for(names) = names.include?("CLAUDE.md") && !names.include?("AGENTS.md") ? "CLAUDE.md" : "AGENTS.md"
+
+      # The text with the section added, or nil when it has it already.
+      def self.merged(text)
+        return nil if text.include?(MARKER)
+
+        text.strip.empty? ? SECTION : "#{text.rstrip}\n\n#{SECTION}"
+      end
+    end
+  end
+end

data/lib/fun_ci/setup/commands.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "installer"
+require_relative "hook_writer"
+require_relative "git_hooks"
+require_relative "setup_checker"
+require_relative "legacy_hooks"
+
+module FunCi
+  module Setup
+    # `fun-ci init`, `install-hooks` and `check`, in the project directory.
+    # `hooks_dir` answers where git runs a project's hooks from.
+    class Commands
+      def initialize(project_root, stdout, hooks_dir: GitHooks.method(:dir))
+        @project_root = project_root
+        @stdout = stdout
+        @hooks_dir = hooks_dir
+      end
+
+      def init(args)
+        code = Installer.run(project_root: @project_root, stdout: @stdout)
+        return code if !code.zero? || !args.include?("--everything")
+
+        code = install_hooks([])
+        return code unless code.zero?
+
+        check([])
+      end
+
+      def install_hooks(args)
+        LegacyHooks.new(@project_root).remove(@stdout)
+        install(args.any? ? [args.first] : HookScript.types)
+      end
+
+      def check(_args) = SetupChecker.run(project_root: @project_root, stdout: @stdout)
+
+      private
+
+      def install(types)
+        hooks_dir = @hooks_dir.call(@project_root)
+        types.each do |type|
+          code = HookWriter.run(hooks_dir: hooks_dir, hook_type: type, stdout: @stdout)
+          return code unless code.zero?
+        end
+        0
+      end
+    end
+  end
+end

data/lib/fun_ci/setup/git_hooks.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "../pipeline/git_environment"
+
+module FunCi
+  module Setup
+    # Where git runs a project's hooks from: its git directory's hooks, or
+    # where core.hooksPath points, and from a linked worktree the
+    # repository's own. Git is asked, as .git may be a file or be ignored.
+    module GitHooks
+      # The directory, or nil outside a git repository.
+      def self.dir(project_root)
+        out, status = Open3.capture2(Pipeline::GitEnvironment::CLEAN, "git", "rev-parse", "--git-path", "hooks",
+                                     chdir: project_root, err: File::NULL)
+        status.success? ? File.expand_path(out.strip, project_root) : nil
+      end
+    end
+  end
+end

data/lib/fun_ci/setup/hook_script.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Setup
+    # The script fun-ci writes into each git hook it manages.
+    module HookScript
+      MARKER = "# fun-ci-managed-hook"
+      NULL_SHA = "0" * 40
+
+      GUARD = <<~SH.freeze
+        #!/bin/sh
+        #{MARKER}
+        if ! command -v fun-ci >/dev/null 2>&1; then
+          echo "fun-ci is not installed or not on PATH, so this runs without CI. Install it with: gem install fun_ci" >&2
+          exit 0
+        fi
+      SH
+
+      # After a commit: the commit just made, in the background.
+      POST_COMMIT = <<~SH.freeze
+        COMMIT=$(git rev-parse HEAD 2>/dev/null || echo "#{NULL_SHA}")
+        BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+        fun-ci trigger --background "$COMMIT" "$BRANCH"
+      SH
+
+      # Before a push: the fast verdict of each commit git says it pushes
+      # (acceptance-tests.md, AT-9.13). A deleted ref pushes the null SHA, and
+      # exit 5 is a project not set up for fun-ci, which pushes without CI.
+      PRE_PUSH = <<~SH.freeze
+        status=0
+        while read -r local_ref local_sha remote_ref remote_sha; do
+          [ "$local_sha" = "#{NULL_SHA}" ] && continue
+          fun-ci wait "$local_sha" --need fast
+          code=$?
+          [ "$code" -eq 0 ] || [ "$code" -eq 5 ] || status=1
+        done
+        exit $status
+      SH
+
+      BODIES = { "post-commit" => POST_COMMIT, "pre-push" => PRE_PUSH }.freeze
+
+      def self.types = BODIES.keys
+      def self.for(hook_type) = GUARD + BODIES.fetch(hook_type)
+      def self.managed?(script) = script.include?(MARKER)
+    end
+  end
+end

data/lib/fun_ci/setup/hook_writer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "hook_script"
+
+module FunCi
+  module Setup
+    # Writes a hook into `hooks_dir`, where git runs the project's hooks
+    # from (GitHooks.dir); nil outside a git repository.
+    class HookWriter
+      def self.run(hooks_dir:, hook_type:, stdout: $stdout)
+        new(hooks_dir: hooks_dir, hook_type: hook_type, stdout: stdout).run
+      end
+
+      def initialize(hooks_dir:, hook_type:, stdout:)
+        @hooks_dir = hooks_dir
+        @hook_type = hook_type
+        @stdout = stdout
+      end
+
+      def run
+        return reject("Not a git repository: no .git/ found.") unless git_repo?
+        return reject("Unknown hook type: #{@hook_type}") unless HookScript.types.include?(@hook_type)
+        return skip("Hook #{@hook_type} already exists from another tool, so it was left alone.") if foreign_hook?
+
+        write_hook
+        @stdout.puts "Installed #{@hook_type} hook."
+        0
+      end
+
+      private
+
+      def git_repo? = !@hooks_dir.nil?
+      def hook_path = File.join(@hooks_dir, @hook_type)
+
+      def foreign_hook?
+        File.exist?(hook_path) && !HookScript.managed?(File.read(hook_path))
+      end
+
+      def write_hook
+        FileUtils.mkdir_p(@hooks_dir)
+        File.write(hook_path, HookScript.for(@hook_type))
+        File.chmod(0o755, hook_path)
+      end
+
+      def reject(message)
+        @stdout.puts message
+        1
+      end
+
+      def skip(message)
+        @stdout.puts message
+        0
+      end
+    end
+  end
+end

data/lib/fun_ci/setup/installer.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "project_detector"
+require_relative "template_writer"
+require_relative "maven_linter_detector"
+require_relative "agent_instructions"
+
+module FunCi
+  module Setup
+    class Installer
+      def self.run(project_root:, stdout: $stdout)
+        new(project_root: project_root, stdout: stdout).run
+      end
+
+      def initialize(project_root:, stdout:)
+        @project_root = project_root
+        @stdout = stdout
+      end
+
+      # A project set up for fun-ci, new or not, also tells agents what to do.
+      def run
+        code = set_up
+        tell_agents if code.zero?
+        code
+      end
+
+      private
+
+      def set_up
+        return report(".fun-ci/ already exists, so init left it as it is.", 0) if initialised?
+
+        detected = ProjectDetector.new(Dir.children(@project_root)).detect
+        return report("Could not detect project type. Create .fun-ci/ manually.", 1) if detected == :unknown
+
+        write_templates(detected)
+      end
+
+      def tell_agents
+        file = AgentInstructions.file_for(Dir.children(@project_root))
+        path = File.join(@project_root, file)
+        merged = AgentInstructions.merged(File.exist?(path) ? File.read(path) : "")
+        return unless merged
+
+        File.write(path, merged)
+        @stdout.puts "Told agents what to do after a commit, in #{file}."
+      end
+
+      def initialised?
+        Dir.exist?(File.join(@project_root, ".fun-ci"))
+      end
+
+      def write_templates(detected)
+        @stdout.puts "Detected: #{detected.to_s.tr("_", " ")}"
+        TemplateWriter.new(detected, @project_root, lint_override: detect_maven_linter(detected)).write
+        report("Created .fun-ci/ with template scripts.", 0)
+      end
+
+      def report(message, exit_code)
+        @stdout.puts message
+        exit_code
+      end
+
+      def detect_maven_linter(detected)
+        return nil unless detected == :jvm_maven
+
+        command = MavenLinterDetector.new(File.read(File.join(@project_root, "pom.xml"))).lint_command
+        command == MavenLinterDetector::DEFAULT_COMMAND ? nil : command
+      end
+    end
+  end
+end

data/lib/fun_ci/setup/legacy_hooks.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "hook_script"
+
+module FunCi
+  module Setup
+    # fun-ci 1.x ran the background pipeline from a pre-commit hook, before
+    # the commit existed. The hook fun-ci wrote goes on upgrade, and is warned
+    # about until then; one someone wrote by hand that still calls fun-ci is
+    # warned about, never touched.
+    class LegacyHooks
+      WARNING = ".git/hooks/pre-commit calls fun-ci, which now runs after the commit: " \
+                "take fun-ci out of it and run `fun-ci install-hooks`"
+      NOT_UPGRADED = "fun-ci 1.x's pre-commit hook is still installed, so each run tests the commit before yours " \
+                     "and yours gets none: run `fun-ci install-hooks`"
+
+      def initialize(project_root)
+        @hook = File.join(project_root, ".git", "hooks", "pre-commit")
+      end
+
+      def remove(stdout)
+        return unless File.exist?(@hook) && HookScript.managed?(File.read(@hook))
+
+        File.delete(@hook)
+        stdout.puts "Removed fun-ci's 1.x pre-commit hook; the background pipeline now runs from post-commit."
+      end
+
+      def warnings
+        return [] unless File.exist?(@hook)
+
+        script = File.read(@hook)
+        return [NOT_UPGRADED] if HookScript.managed?(script)
+
+        script.include?("fun-ci") ? [WARNING] : []
+      end
+    end
+  end
+end

data/lib/fun_ci/setup/maven_linter_detector.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Setup
+    class MavenLinterDetector
+      LINTERS = [
+        { artifact_id: "detekt-maven-plugin", command: "mvn detekt:check" },
+        { artifact_id: "ktlint-maven-plugin", command: "mvn ktlint:check" },
+        { artifact_id: "maven-checkstyle-plugin", command: "mvn checkstyle:check" },
+        { artifact_id: "spotbugs-maven-plugin", command: "mvn spotbugs:check" },
+        { artifact_id: "maven-pmd-plugin", command: "mvn pmd:check" }
+      ].freeze
+
+      DEFAULT_COMMAND = "mvn verify -DskipTests"
+
+      def initialize(pom_content)
+        @pom_content = pom_content
+      end
+
+      def lint_command
+        match = LINTERS.find { |linter| @pom_content.include?(linter[:artifact_id]) }
+        match ? match[:command] : DEFAULT_COMMAND
+      end
+    end
+  end
+end

data/lib/fun_ci/setup/project_config.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require_relative "settings"
+require_relative "../evidence/settings"
+require_relative "../evidence/start"
+
+module FunCi
+  module Setup
+    class ProjectConfig
+      REQUIRED_SCRIPTS = %w[lint.sh build.sh fast.sh slow.sh].freeze
+
+      def initialize(project_root)
+        @project_root = project_root
+        @fun_ci_dir = File.join(project_root, ".fun-ci")
+      end
+
+      def folder_exists?
+        Dir.exist?(@fun_ci_dir)
+      end
+
+      def validate
+        return ["No .fun-ci/ folder found in #{@project_root}"] unless folder_exists?
+
+        REQUIRED_SCRIPTS.flat_map { |script| script_errors(script) } + settings.errors
+      end
+
+      # Mistakes in the `evidence` key, which `fun-ci check` reports but which
+      # never stop a pipeline: the entry with the mistake is left out instead.
+      def evidence_errors = Evidence::Settings.load(File.join(@fun_ci_dir, "config")).errors(root: @project_root)
+
+      # The presets whose markers the project has, which run when a stage fails
+      # and its output shows their tool.
+      def presets = preset_candidates.select(&:because).map { |found| found.preset.name }
+
+      # The presets without markers, which read what any project's output
+      # may hold, such as JSON logs.
+      def any_project_presets = preset_candidates.reject(&:because).map { |found| found.preset.name }
+
+      def worktree_slots = settings.worktree_slots
+
+      def script_path(stage)
+        File.join(@fun_ci_dir, "#{stage}.sh")
+      end
+
+      # The shell command that runs a stage's script on a commit, its path
+      # quoted, since a project's path may hold spaces.
+      def stage_command(stage, sha) = "#{Shellwords.escape(script_path(stage))} #{sha}"
+
+      private
+
+      def settings = Settings.new(File.join(@fun_ci_dir, "config"))
+
+      def preset_candidates
+        evidence = Evidence::Settings.load(File.join(@fun_ci_dir, "config"))
+        Evidence::Start.candidates(Evidence::Worktree.new(@project_root), evidence, "all")
+      end
+
+      def script_errors(script)
+        path = File.join(@fun_ci_dir, script)
+        return [".fun-ci/#{script} is not found"] unless File.exist?(path)
+        return [".fun-ci/#{script} is not executable"] unless File.executable?(path)
+
+        []
+      end
+    end
+  end
+end

data/lib/fun_ci/setup/project_detector.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Setup
+    # Which kind of project a directory is, from the names at its top: the
+    # first stack, in this order, any of whose markers is there. A marker is a
+    # name, a glob, or a list of them that must all be there. A language
+    # comes before the tooling that sits beside it (Node beside Python, a
+    # Makefile around Go), and a lockfile picks the package manager.
+    class ProjectDetector
+      STACKS = {
+        ruby_rspec: [%w[Gemfile spec], %w[Gemfile .rspec]],
+        ruby_bundler: ["Gemfile"],
+        jvm_gradle_kotlin: %w[build.gradle.kts settings.gradle.kts],
+        jvm_gradle_groovy: %w[build.gradle settings.gradle],
+        jvm_maven: ["pom.xml"],
+        rust_cargo: ["Cargo.toml"],
+        go: ["go.mod"],
+        elixir_mix: ["mix.exs"],
+        dart: ["pubspec.yaml"],
+        swift: ["Package.swift"],
+        php_composer: ["composer.json"],
+        dotnet: %w[*.sln *.csproj *.fsproj],
+        python_uv: ["uv.lock"],
+        python_poetry: ["poetry.lock"],
+        python: %w[pyproject.toml setup.py setup.cfg requirements.txt],
+        deno: %w[deno.json deno.jsonc],
+        bun: %w[bun.lock bun.lockb bunfig.toml],
+        node_pnpm: ["pnpm-lock.yaml"],
+        node_yarn: ["yarn.lock"],
+        node_npm: ["package.json"],
+        perl: %w[cpanfile Makefile.PL Build.PL dist.ini],
+        cmake: ["CMakeLists.txt"],
+        make: %w[Makefile makefile GNUmakefile]
+      }.freeze
+
+      def initialize(filenames)
+        @filenames = filenames
+      end
+
+      def detect
+        STACKS.find { |_, markers| markers.any? { |marker| present?(marker) } }&.first || :unknown
+      end
+
+      private
+
+      def present?(marker)
+        Array(marker).all? { |part| @filenames.any? { |name| names?(part, name) } }
+      end
+
+      def names?(part, name) = File.fnmatch?(part, name)
+    end
+  end
+end

data/lib/fun_ci/setup/settings.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module FunCi
+  module Setup
+    # .fun-ci/config: settings for this machine's runs, as YAML. Each one left
+    # out takes its default; one that is wrong is reported and the default used,
+    # as are all of them when the file isn't YAML.
+    class Settings
+      DEFAULTS = { "worktree_slots" => 2 }.freeze
+
+      def initialize(path)
+        @path = path
+      end
+
+      def worktree_slots = errors.empty? ? values.fetch("worktree_slots") : DEFAULTS.fetch("worktree_slots")
+
+      def errors
+        return [".fun-ci/config must be a mapping such as `worktree_slots: 2`"] unless raw.is_a?(Hash)
+
+        slots = values["worktree_slots"]
+        return [] if slots.is_a?(Integer) && slots.positive?
+
+        [".fun-ci/config: worktree_slots must be a whole number above 0, not #{slots.inspect}"]
+      rescue Psych::SyntaxError => e
+        [".fun-ci/config is not YAML: #{e.problem} (line #{e.line})"]
+      end
+
+      private
+
+      def raw = File.exist?(@path) ? YAML.safe_load_file(@path) || {} : {}
+      def values = DEFAULTS.merge(raw)
+    end
+  end
+end

data/lib/fun_ci/setup/setup_checker.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "project_config"
+require_relative "legacy_hooks"
+
+module FunCi
+  module Setup
+    class SetupChecker
+      def self.run(project_root:, stdout: $stdout)
+        new(config: ProjectConfig.new(project_root), hooks: LegacyHooks.new(project_root), stdout: stdout).run
+      end
+
+      def initialize(config:, hooks:, stdout:)
+        @config = config
+        @hooks = hooks
+        @stdout = stdout
+      end
+
+      # Warnings are printed but don't fail the check.
+      def run
+        errors = @config.validate + @config.evidence_errors
+        @stdout.puts(errors.empty? ? "All OK. The project is configured." : errors)
+        list_presets
+        @hooks.warnings.each { |warning| @stdout.puts "Warning: #{warning}" }
+        errors.empty? ? 0 : 1
+      end
+
+      private
+
+      def list_presets
+        lists = { "this project" => @config.presets, "any project's output" => @config.any_project_presets }
+        lists.each { |what, names| @stdout.puts "Evidence presets for #{what}: #{names.join(", ")}" if names.any? }
+      end
+    end
+  end
+end

data/lib/fun_ci/setup/stage_templates/javascript.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "shell"
+
+module FunCi
+  module Setup
+    # JavaScript and TypeScript: Deno, Bun, and Node with its package managers.
+    module StageTemplates
+      JAVASCRIPT = {
+        deno: stages("deno lint", "deno check", "deno test", "deno task test:slow"),
+        bun: stages("bunx eslint .", "bun install", "bun test", "bun run test:slow"),
+        node_pnpm: stages("pnpm exec eslint .", "pnpm install", "pnpm test", "pnpm run test:slow"),
+        node_yarn: stages("yarn eslint .", "yarn install", "yarn test", "yarn run test:slow"),
+        node_npm: stages("npx eslint .", "npm install", "npm test", "npm run test:slow")
+      }.freeze
+    end
+  end
+end

data/lib/fun_ci/setup/stage_templates/managed.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "shell"
+
+module FunCi
+  module Setup
+    # Stacks that run on a virtual machine: the JVM, .NET, the BEAM and Dart's.
+    module StageTemplates
+      GRADLE = stages("./gradlew check -x test", "./gradlew assemble", "./gradlew test", "./gradlew integrationTest")
+               .freeze
+
+      MANAGED = {
+        jvm_gradle_kotlin: GRADLE,
+        jvm_gradle_groovy: GRADLE,
+        jvm_maven: stages("mvn verify -DskipTests", "mvn compile", "mvn test", "mvn verify"),
+        dotnet: stages("dotnet format --verify-no-changes", "dotnet build",
+                       'dotnet test --filter "Category!=Slow"', 'dotnet test --filter "Category=Slow"'),
+        elixir_mix: stages("mix format --check-formatted", "mix deps.get && mix compile",
+                           "mix test --exclude slow", "mix test --only slow"),
+        dart: stages("dart analyze", "dart pub get", "dart test --exclude-tags slow", "dart test --tags slow")
+      }.freeze
+    end
+  end
+end

data/lib/fun_ci/setup/stage_templates/native.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "shell"
+
+module FunCi
+  module Setup
+    # Stacks that compile to the machine: Rust, Go, Swift, and C or C++ built
+    # with CMake or make.
+    module StageTemplates
+      CTEST = "ctest --test-dir build --output-on-failure --no-tests=error"
+      CLANG_FORMAT = "git ls-files -z '*.c' '*.cc' '*.cpp' '*.h' '*.hpp' | xargs -0 clang-format --dry-run --Werror"
+
+      NATIVE = {
+        rust_cargo: stages("cargo clippy --all-targets -- -D warnings", "cargo build --all-targets",
+                           "cargo test", "cargo test -- --ignored"),
+        go: stages("go vet ./...", "go build ./...", "go test -short ./...", "go test ./..."),
+        swift: stages("swift format lint --recursive --strict .", "swift build --build-tests",
+                      "swift test --skip Slow", "swift test --filter Slow"),
+        cmake: stages(CLANG_FORMAT, "cmake -S . -B build && cmake --build build",
+                      "#{CTEST} -LE slow", "#{CTEST} -L slow"),
+        make: stages("make lint", "make", "make test", "make test-slow")
+      }.freeze
+    end
+  end
+end

data/lib/fun_ci/setup/stage_templates/scripting.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "shell"
+
+module FunCi
+  module Setup
+    # Interpreted stacks: Ruby, Python, PHP and Perl.
+    module StageTemplates
+      def self.python(runner, build)
+        stages("#{runner}ruff check .", build, "#{runner}pytest -m \"not slow\"", "#{runner}pytest -m slow")
+      end
+
+      SCRIPTING = {
+        ruby_rspec: stages("bundle exec rubocop", "bundle install --quiet",
+                           "bundle exec rspec --tag ~slow", "bundle exec rspec --tag slow"),
+        ruby_bundler: stages("bundle exec rubocop", "bundle install --quiet",
+                             "bundle exec rake test", "bundle exec rake test:slow"),
+        php_composer: stages("vendor/bin/phpcs", "composer install --no-interaction --no-progress",
+                             "vendor/bin/phpunit --exclude-group slow", "vendor/bin/phpunit --group slow"),
+        python_uv: python("uv run ", "uv sync"),
+        python_poetry: python("poetry run ", "poetry install"),
+        python: python("python3 -m ", "python3 -m compileall -q ."),
+        perl: stages("perlcritic lib", "cpanm --installdeps --notest .", "prove -lr t", "prove -lr xt")
+      }.freeze
+    end
+  end
+end

data/lib/fun_ci/setup/stage_templates/shell.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Setup
+    # What every stack's stage scripts are made of.
+    module StageTemplates
+      def self.script(body) = "#!/bin/sh\n#{body}\n"
+
+      def self.stages(lint, build, fast, slow)
+        { "lint.sh" => lint, "build.sh" => build, "fast.sh" => fast, "slow.sh" => slow }.transform_values do |body|
+          script(body)
+        end
+      end
+    end
+  end
+end