plan_driven 0.1.0

data/lib/plan_driven/github.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module PlanDriven
+  # The parts of the GitHub REST API the workflow needs: issues for tickets, and pull requests,
+  # their files, CI checks and merge.
+  class GitHub
+    BASE = "https://api.github.com"
+
+    attr_reader :repository
+
+    def initialize(repository: Repository.slug, token: Credentials.fetch(:github_token), base: BASE)
+      @repository = repository or raise ConfigurationError, "No GitHub repository. Set config.github_repository " \
+                                                            "or add a GitHub `origin` remote."
+      @token = token
+      @base = base
+    end
+
+    def repo_url
+      "https://github.com/#{repository}"
+    end
+
+    def create_issue(title:, body:, labels: [])
+      request(:post, "/repos/#{repository}/issues", { title: title, body: body, labels: labels })
+    end
+
+    def update_issue(number, **fields)
+      request(:patch, "/repos/#{repository}/issues/#{number}", fields)
+    end
+
+    def comment(number, body)
+      request(:post, "/repos/#{repository}/issues/#{number}/comments", { body: body })
+    end
+
+    def pull(number)
+      request(:get, "/repos/#{repository}/pulls/#{number}")
+    end
+
+    def pull_files(number)
+      (1..30).each_with_object([]) do |page, files|
+        batch = request(:get, "/repos/#{repository}/pulls/#{number}/files?per_page=100&page=#{page}")
+        files.concat(batch)
+        break files if batch.size < 100
+      end
+    end
+
+    # Check runs (GitHub Actions and apps) and commit statuses (older CI integrations), in one shape.
+    def checks(sha)
+      runs = request(:get, "/repos/#{repository}/commits/#{sha}/check-runs?per_page=100")["check_runs"].to_a
+      statuses = request(:get, "/repos/#{repository}/commits/#{sha}/status")["statuses"].to_a
+      runs.map { |run| run.slice("name", "status", "conclusion") } + statuses.map do |status|
+        state = status["state"]
+        { "name" => status["context"], "status" => state == "pending" ? "in_progress" : "completed",
+          "conclusion" => state == "pending" ? nil : state }
+      end
+    end
+
+    # How many commits the base branch has that the pull request's branch doesn't.
+    def behind_by(pull)
+      base = pull.dig("base", "ref")
+      head = pull.dig("head", "sha")
+      return 0 unless base && head
+
+      request(:get, "/repos/#{repository}/compare/#{base}...#{head}")["behind_by"].to_i
+    end
+
+    def file(path, ref:)
+      data = request(:get, "/repos/#{repository}/contents/#{path}?ref=#{ref}")
+      Base64.decode64(data["content"].to_s)
+    end
+
+    def review(number, body:, event: "COMMENT")
+      request(:post, "/repos/#{repository}/pulls/#{number}/reviews", { body: body, event: event })
+    end
+
+    def merge(number, title:, method:)
+      request(:put, "/repos/#{repository}/pulls/#{number}/merge", { commit_title: title, merge_method: method })
+    end
+
+    # Agents open draft pull requests, and GitHub won't merge a draft. REST can't undraft; GraphQL can.
+    def ready_for_review(number)
+      node_id = pull(number)["node_id"]
+      data = request(:post, "/graphql", {
+                       query: "mutation($id: ID!) { markPullRequestReadyForReview(input: {pullRequestId: $id}) " \
+                              "{ pullRequest { isDraft } } }",
+                       variables: { id: node_id }
+                     })
+      raise ProviderError, "GitHub GraphQL: #{data["errors"].map { |e| e["message"] }.join("; ")}" if data["errors"]
+
+      data
+    end
+
+    def self.pr_number(url)
+      url.to_s[%r{/pull/(\d+)}, 1]&.to_i
+    end
+
+    private
+
+    def request(method, path, body = nil)
+      unless @token
+        raise ConfigurationError,
+              "No GitHub token. Run `plan-driven configure`, set GITHUB_TOKEN or `gh auth login`."
+      end
+
+      response = HTTP.request(method, "#{@base}#{path}", body: body, headers: {
+                                "Authorization" => "Bearer #{@token}",
+                                "Accept" => "application/vnd.github+json",
+                                "X-GitHub-Api-Version" => "2022-11-28",
+                                "Content-Type" => "application/json"
+                              })
+      return response.json if response.success?
+
+      raise ProviderError,
+            "GitHub returned #{response.status} for #{path}: #{response.json["message"] || response.body[0, 200]}"
+    end
+  end
+end

data/lib/plan_driven/guards/migration_guard.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  module Guards
+    # Zero-downtime rules for the Database changes section: expand first, contract last.
+    class MigrationGuard
+      DESTRUCTIVE = /\b(remove|drop|delete|rename)\w*\b[^.\n]{0,80}\b(column|table|field)s?\b|
+                     \b(remove_column|drop_table|rename_column|rename_table|change_column)\b/ix
+      SAFE_REMOVAL = /ignored_columns|expand|contract|in a later (step|phase|release)|after (the )?backfill/i
+      NOT_NULL = /\bnot[\s_-]?null\b|null:\s*false/i
+      NOT_NULL_SAFE = /default|backfill|nullable first|after (the )?backfill|validate/i
+      INDEX = /\badd_index\b|\bindex(es)?\b/i
+      CONCURRENT = /concurrent|algorithm:\s*:concurrently|disable_ddl_transaction/i
+      NEW_TABLE = /
+        create_table\s+[:"']?([a-z][a-z0-9_]+)
+        | new\s+table:?\s*`?([a-z][a-z0-9_]+)
+        | create\s+(?:a\s+|the\s+)?(?:new\s+)?`([a-z][a-z0-9_]+)`\s+table
+        | create\s+(?:a\s+|the\s+)?(?:new\s+)?table\s+`?([a-z][a-z0-9_]+)
+        | create:?\s+`([a-z][a-z0-9_]+)`(?!\s+(?:column|index))
+        | _create_([a-z][a-z0-9_]+)\.rb
+      /ix
+
+      def initialize(text, schema:)
+        @text = text.to_s
+        @schema = schema
+      end
+
+      def call
+        report = Report.new
+        return report if @text.strip.empty?
+
+        check_destructive(report)
+        check_not_null(report)
+        check_indexes(report)
+        report
+      end
+
+      def new_tables
+        @text.scan(NEW_TABLE).flatten.compact.map(&:downcase).uniq
+      end
+
+      private
+
+      def check_destructive(report)
+        return unless @text.match?(DESTRUCTIVE)
+        return if @text.match?(SAFE_REMOVAL)
+
+        report.error("Database changes remove or rename a column or table in one step. Split it: stop using " \
+                     "it and add it to `ignored_columns`, deploy, then remove it in a later migration.")
+      end
+
+      def check_not_null(report)
+        existing_tables_mentioned.each do |table|
+          paragraph = paragraph_changing(table)
+          next unless paragraph.match?(NOT_NULL) && !paragraph.match?(NOT_NULL_SAFE)
+
+          report.warning("A NOT NULL change on existing table #{table} has no default or backfill step; " \
+                         "it will fail on existing rows")
+        end
+      end
+
+      def check_indexes(report)
+        adapter = @schema.respond_to?(:adapter) ? @schema.adapter : nil
+        return unless adapter.to_s.match?(/postg/i)
+
+        existing_tables_mentioned.each do |table|
+          paragraph = paragraph_changing(table)
+          next unless paragraph.match?(INDEX) && !paragraph.match?(CONCURRENT)
+
+          report.warning("An index on existing table #{table} isn't built concurrently; it locks writes while " \
+                         "it builds")
+        end
+      end
+
+      def existing_tables_mentioned
+        @schema.tables.select { |table| @text.match?(/\b#{Regexp.escape(table)}\b/) } - new_tables
+      end
+
+      # Paragraphs that change an existing table, not ones that only describe it (plans list the
+      # current schema, "user_id integer, not null", before saying what changes).
+      def paragraph_changing(table)
+        name = Regexp.escape(table)
+        change = /
+          \b(add_column|change_column_null|change_column_default|add_reference|add_belongs_to|add_index|
+             change_table|add_check_constraint)\s*\(?\s*[:"']#{name}\b
+          | \b(add|adds|adding)\b[^.\n]{0,80}\b(to|on)\s+(the\s+)?`?#{name}`?
+          | `?#{name}`?\s+(table\s+)?(gets|gains)\b
+          | \A\#+\s+`?#{name}`?\s*\n[^\n]*\b(add\w*|change\w*|makes?)\b
+        /ix
+        @text.split(/\n\s*\n|\n(?=#+ )/).grep(change).join("\n")
+      end
+    end
+  end
+end

data/lib/plan_driven/guards/plan_guard.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  module Guards
+    # Checks a drafted plan against the template and against the application it describes.
+    class PlanGuard
+      PLACEHOLDER = /\b(TBD|TODO|lorem ipsum|FIXME|XXX)\b/i
+      RISK_LEVEL = /risk level\W{0,5}(LOW|MEDIUM|HIGH)\b/i
+      MODEL_PATH = %r{\bapp/models/[\w/]+\.rb\b}
+      CONSTANT = /`((?:[A-Z][a-z0-9]+)+(?:::(?:[A-Z][a-z0-9]+)+)*)`/
+      TABLE_COLUMN = /`([a-z][a-z0-9_]*)\.([a-z][a-z0-9_]*)`/
+
+      def initialize(sections, schema:, template: PlanDriven.configuration.template)
+        @sections = (sections || {}).transform_keys(&:to_s)
+        @schema = schema
+        @template = template
+      end
+
+      def call
+        report = Report.new
+        check_sections(report)
+        check_risk_level(report)
+        check_existing_structure(report)
+        report.merge!(MigrationGuard.new(@sections["database_changes"].to_s, schema: @schema).call)
+        report
+      end
+
+      private
+
+      def check_sections(report)
+        @template.sections.each do |section|
+          text = @sections[section.key].to_s.strip
+          if section.required && text.empty?
+            report.error("#{section.title} is empty")
+          elsif section.required && words(text) < section.min_words.to_i
+            report.error("#{section.title} is too thin (#{words(text)} words, at least #{section.min_words})")
+          end
+          if text.match?(PLACEHOLDER)
+            report.warning("#{section.title} still contains a placeholder (#{text[PLACEHOLDER]})")
+          end
+        end
+      end
+
+      def check_risk_level(report)
+        return if @sections["security"].to_s.match?(RISK_LEVEL)
+
+        report.error("Security doesn't state a risk level (a line like `Risk Level: MEDIUM`)")
+      end
+
+      # The one place a plan must match the code exactly: what it calls existing has to exist.
+      def check_existing_structure(report)
+        text = @sections["existing_data_structure"].to_s
+        text.scan(MODEL_PATH).uniq.each do |path|
+          report.error("Existing Data Structure cites #{path}, which isn't in the app") unless root.join(path).exist?
+        end
+        text.scan(CONSTANT).flatten.uniq.each do |name|
+          next if @schema.model?(name) || known_constant?(name)
+
+          report.error("Existing Data Structure describes `#{name}` as existing, but there's no such model")
+        end
+        text.scan(TABLE_COLUMN).uniq.each do |table, column|
+          next unless @schema.table?(table)
+          next if @schema.column?(table, column)
+
+          report.error("Existing Data Structure mentions `#{table}.#{column}`, but #{table} has no #{column} column")
+        end
+      end
+
+      def known_constant?(name)
+        Object.const_defined?(name)
+      rescue NameError
+        false
+      end
+
+      def root
+        PlanDriven.configuration.root_path
+      end
+
+      def words(text)
+        text.split(/\s+/).count { |word| word.match?(/\w/) }
+      end
+    end
+  end
+end

data/lib/plan_driven/guards/pr_guard.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  module Guards
+    # Checks the pull request an agent opened against the ticket it was given. Runs before a human
+    # is asked to approve it, and again before merge.
+    class PrGuard
+      MIGRATION_PATHS = %r{\Adb/}
+      CHECK_OK = %w[success neutral skipped].freeze
+
+      def initialize(ticket, pull:, files:, checks:, features: {}, behind: 0, config: PlanDriven.configuration)
+        @ticket = ticket
+        @pull = pull || {}
+        @files = files
+        @checks = checks
+        @features = features
+        @behind = behind
+        @config = config
+      end
+
+      def call
+        report = Report.new
+        check_reference(report)
+        check_size(report)
+        check_specs(report)
+        check_migrations(report)
+        check_acceptance_scenarios(report) if @config.cucumber && @ticket.kind != "docs"
+        check_ci(report)
+        check_base(report)
+        report
+      end
+
+      private
+
+      def paths
+        @paths ||= @files.map { |file| file["filename"] }
+      end
+
+      def check_reference(report)
+        text = "#{@pull["title"]}\n#{@pull["body"]}"
+        report.warning("The PR doesn't mention #{@ticket.reference}") unless text.include?(@ticket.reference)
+        number = @ticket.issue_number
+        if number && !text.match?(/(close[sd]?|fix(e[sd])?|resolve[sd]?) ##{number}\b/i)
+          report.warning("The PR doesn't close issue ##{number}")
+        elsif text.include?(@ticket.reference)
+          report.pass(["Refers to #{@ticket.reference}", ("closes ##{number}" if number)].compact.join(" and "))
+        end
+      end
+
+      def check_size(report)
+        changed = @files.sum { |file| file["additions"].to_i + file["deletions"].to_i }
+        limit = @config.max_pr_changed_lines
+        return report.pass("#{@files.size} files, #{changed} changed lines (limit #{limit})") if changed <= limit
+
+        report.error("The PR changes #{changed} lines, above the limit of #{limit}")
+      end
+
+      def check_specs(report)
+        return unless @config.require_specs_in_pr
+        return if @ticket.kind == "docs"
+
+        specs = paths.count { |path| spec_path?(path) }
+        return report.pass("#{specs} spec and feature files changed") if specs.positive?
+
+        report.error("The PR has no spec or feature changes")
+      end
+
+      def check_migrations(report)
+        added = @files.select { |file| file["filename"].start_with?("db/migrate/") && file["status"] == "added" }
+        if added.any? && !%w[migration backfill].include?(@ticket.kind)
+          report.error("A #{@ticket.kind} ticket adds a migration (#{added.first["filename"]}); " \
+                       "schema changes belong in their own migration ticket")
+        end
+        check_migration_scope(report)
+        if added.empty? && @ticket.kind != "migration"
+          report.pass("No migrations, so the schema stays with the migration tickets")
+        end
+        return if added.empty? || paths.any? { |path| path.match?(%r{\Adb/(schema\.rb|structure\.sql)\z}) }
+
+        report.warning("A migration was added but db/schema.rb didn't change")
+      end
+
+      def check_migration_scope(report)
+        return unless @ticket.kind == "migration"
+
+        app_changes = paths.reject { |path| path.match?(MIGRATION_PATHS) || spec_path?(path) }
+        return report.pass("A migration ticket, and it only changes db/ and tests") if app_changes.empty?
+
+        report.warning("A migration ticket also changes #{app_changes.first(3).join(", ")}")
+      end
+
+      def check_acceptance_scenarios(report)
+        tagged = @features.flat_map do |path, text|
+          Gherkin.parse(text, path: path).scenarios.select { |scenario| scenario.tags.include?(@ticket.feature_tag) }
+        end
+        if tagged.empty?
+          report.error("No Cucumber scenario is tagged #{@ticket.feature_tag}")
+          return
+        end
+        @ticket.criteria.each_index do |index|
+          tag = "@ac-#{index + 1}"
+          next if tagged.any? { |scenario| scenario.tags.include?(tag) }
+
+          report.error("Acceptance criterion #{index + 1} has no scenario tagged #{@ticket.feature_tag} #{tag}")
+        end
+        count = @ticket.criteria.size
+        return unless report.errors.none? { |message| message.start_with?("Acceptance criterion") }
+
+        report.pass("All #{count} acceptance criteria have a scenario tagged #{@ticket.feature_tag} @ac-N")
+      end
+
+      def check_ci(report)
+        if @checks.empty?
+          report.warning("No CI checks have reported on this PR yet")
+          return
+        end
+        pending = @checks.reject { |check| check["status"] == "completed" }
+        failed = @checks.select { |check| check["status"] == "completed" && !CHECK_OK.include?(check["conclusion"]) }
+        failed.each { |check| report.error("CI check \"#{check["name"]}\" #{check["conclusion"]}") }
+        report.warning("#{pending.size} CI check(s) still running") if pending.any?
+        return unless pending.empty? && failed.empty?
+
+        report.pass("CI is green: #{@checks.map { |check| check["name"] }.join(", ")}")
+      end
+
+      # Another ticket merged since the agent branched: CI passed without those changes.
+      def check_base(report)
+        base = @pull.dig("base", "ref") || "the base branch"
+        return report.pass("Up to date with #{base}") if @behind.zero?
+
+        report.warning("The branch is #{@behind} commit(s) behind #{base}, so CI ran without them. " \
+                       "Ask the agent to merge #{base} and run the checks again (`plan-driven feedback`).")
+      end
+
+      def spec_path?(path)
+        @config.spec_paths.any? { |prefix| path.start_with?(prefix) }
+      end
+    end
+  end
+end

data/lib/plan_driven/guards/ticket_guard.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  module Guards
+    # Checks the ticket breakdown: every ticket is small, testable and ordered so that each
+    # pull request can merge on its own without breaking the application.
+    class TicketGuard
+      BUILDS_ON_MIGRATION = %w[dual_write backfill code switch cleanup].freeze
+      MAX_CRITERIA = 8
+      LAYER_TITLE = /\A(models?|services?|controllers?|views?|polic(y|ies)|ui|api|routes?|specs?|tests?)\s*:/i
+
+      def initialize(tickets, plan_sections:, schema:, config: PlanDriven.configuration)
+        @tickets = tickets
+        @sections = (plan_sections || {}).transform_keys(&:to_s)
+        @schema = schema
+        @config = config
+      end
+
+      def call
+        report = Report.new
+        if @tickets.empty?
+          report.error("There are no tickets")
+          return report
+        end
+
+        @tickets.each { |ticket| check_ticket(ticket, report) }
+        check_slicing(report)
+        check_dependencies(report)
+        check_order(report) if report.ok?
+        check_coverage(report)
+        report
+      end
+
+      private
+
+      # A model ticket, then a controller ticket, then a view ticket: none of them does anything
+      # a user can see, so no scenario can prove its criteria.
+      def check_slicing(report)
+        layered = @tickets.select { |ticket| ticket["kind"] == "code" && ticket["title"].to_s.match?(LAYER_TITLE) }
+        return if layered.size < 2
+
+        report.error("#{layered.map { |t| t["key"] }.join(", ")} split the work by layer (model, service, " \
+                     "controller, view). Split code tickets by behaviour instead: each one delivers one thing a " \
+                     "user can do, with its model, service, controller, view and specs together")
+      end
+
+      def check_ticket(ticket, report)
+        label = ticket["key"]
+        report.error("#{label} has no title") if ticket["title"].to_s.strip.empty?
+        report.warning("#{label}: title is longer than 100 characters") if ticket["title"].to_s.length > 100
+        report.error("#{label} has an unknown type #{ticket["type"]}") unless Ticket::TYPES.include?(ticket["type"])
+        report.error("#{label} has no description") if ticket["description"].to_s.strip.empty?
+        if ticket["type"] == "STORY" && ticket["story"].to_s !~ /\bso that\b/i
+          report.error("#{label} is a story without \"so that\"")
+        end
+        check_criteria(ticket, label, report)
+        check_estimate(ticket, label, report)
+      end
+
+      def check_criteria(ticket, label, report)
+        criteria = ticket["acceptance_criteria"]
+        report.error("#{label} has no acceptance criteria") if criteria.empty?
+        criteria.each_with_index do |criterion, index|
+          next if criterion.split.size >= 3
+
+          report.error("#{label} acceptance criterion #{index + 1} is too short to test: \"#{criterion}\"")
+        end
+        return unless criteria.size > MAX_CRITERIA
+
+        report.warning("#{label} has #{criteria.size} acceptance criteria; consider splitting it")
+      end
+
+      def check_estimate(ticket, label, report)
+        estimate = ticket["estimate"]
+        if estimate.nil?
+          report.error("#{label} has no estimate")
+        elsif estimate > @config.max_estimate
+          report.error("#{label} is estimated at #{estimate}, above the limit of #{@config.max_estimate}; split it")
+        end
+      end
+
+      def check_dependencies(report)
+        keys = @tickets.map { |ticket| ticket["key"] }
+        @tickets.each do |ticket|
+          (ticket["depends_on"] - keys).each do |missing|
+            report.error("#{ticket["key"]} depends on unknown #{missing}")
+          end
+          report.error("#{ticket["key"]} depends on itself") if ticket["depends_on"].include?(ticket["key"])
+        end
+        cycle = find_cycle
+        report.error("Dependencies form a cycle: #{cycle.join(" -> ")}") if cycle
+      end
+
+      # Expand before contract, per table: anything using a table must build on the migration
+      # that changes it, and removing things comes after every backfill and read switch.
+      def check_order(report)
+        @tickets.each do |ticket|
+          ancestors = ancestors_of(ticket["key"])
+          ticket["touches"].each do |table|
+            required_before(ticket, table).each do |earlier|
+              next if ancestors.include?(earlier["key"])
+
+              report.error("#{ticket["key"]} (#{phase(ticket)}) touches #{table} but doesn't depend on " \
+                           "#{earlier["key"]} (#{phase(earlier)}), which must merge first")
+            end
+          end
+        end
+      end
+
+      def required_before(ticket, table)
+        others = @tickets.reject { |other| other["key"] == ticket["key"] || !other["touches"].include?(table) }
+        case phase(ticket)
+        when "cleanup"
+          others.select { |other| %w[migration dual_write backfill switch].include?(phase(other)) }
+        when *BUILDS_ON_MIGRATION then others.select { |other| phase(other) == "migration" }
+        else []
+        end
+      end
+
+      # A migration that removes or renames something is the contract step, whatever it's called.
+      def phase(ticket)
+        return ticket["kind"] unless ticket["kind"] == "migration"
+
+        text = "#{ticket["title"]}\n#{ticket["description"]}"
+        text.match?(MigrationGuard::DESTRUCTIVE) ? "cleanup" : "migration"
+      end
+
+      def check_coverage(report)
+        touched = @tickets.flat_map { |ticket| ticket["touches"] }.uniq
+        planned = MigrationGuard.new(@sections["database_changes"].to_s, schema: @schema)
+        new_tables = planned.new_tables
+        mentioned = @schema.tables.select { |table| @sections["database_changes"].to_s.match?(/\b#{table}\b/) }
+        (new_tables + mentioned).uniq.each do |table|
+          next if touched.include?(table)
+
+          report.warning("Database changes mention #{table}, but no ticket touches it")
+        end
+        (touched - @schema.tables - new_tables).each do |table|
+          report.warning("A ticket touches #{table}, which isn't in the schema or the plan's database changes")
+        end
+      end
+
+      def ancestors_of(key, seen = Set.new)
+        ticket = @tickets.find { |candidate| candidate["key"] == key }
+        Array(ticket && ticket["depends_on"]).each do |dependency|
+          next if seen.include?(dependency)
+
+          seen << dependency
+          ancestors_of(dependency, seen)
+        end
+        seen
+      end
+
+      def find_cycle
+        state = {}
+        @tickets.each do |ticket|
+          path = visit(ticket["key"], state, [])
+          return path if path
+        end
+        nil
+      end
+
+      def visit(key, state, path)
+        return path + [key] if state[key] == :visiting
+        return if state[key] == :done
+
+        state[key] = :visiting
+        ticket = @tickets.find { |candidate| candidate["key"] == key }
+        Array(ticket && ticket["depends_on"]).each do |dependency|
+          found = visit(dependency, state, path + [key])
+          return found.drop_while { |step| step != found.last } if found
+        end
+        state[key] = :done
+        nil
+      end
+    end
+  end
+end