featureparity 0.0.27 → 0.0.29

data/lib/fp/requirement_lint.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Fp
+  # Local wording checks for a requirement before it is written (Fizzy #1786).
+  #
+  # `fp analyze` reviews a requirement already in the catalog; an agent writing a batch
+  # of drafts wants the cheap mechanical checks *before* anything is created, so a human
+  # can review the batch with `fp propose --dry-run` and nothing lands half-finished.
+  # These are the rules from the requirement-writing guidance that a string can be
+  # tested against: a promise for a title, no filler, a stated outcome, one rule, an
+  # example, and no numbers nobody decided. Everything here is a warning — the human
+  # product owner decides scope, and a heuristic doesn't get to veto a draft.
+  module RequirementLint
+    # Titles that name the work rather than the promise.
+    WORK_VERBS = %w[implement add build create refactor fix support enable integrate migrate].freeze
+
+    # Commentary about the requirement instead of the requirement.
+    COMMENTARY_OPENINGS = [
+      'this feature', 'this requirement', 'the goal is', 'users should be able to',
+      'the system should', 'we need to', 'we should', 'as a user'
+    ].freeze
+
+    # Phrases that sell instead of saying anything a reviewer can check.
+    FILLER = [
+      'seamless', 'robust', 'user-friendly', 'intuitive', 'best-in-class', 'world-class',
+      'leverage', 'streamline', 'cutting-edge', 'state-of-the-art', 'ensure a smooth',
+      'enhance the user experience', 'improve the user experience', 'delightful'
+    ].freeze
+
+    Finding = Struct.new(:field, :message, keyword_init: true)
+
+    module_function
+
+    # spec: a hash with :slug, :title, :why, :acceptance, :source_type (string keys or
+    # symbol keys). Returns [Finding, ...] — empty when nothing stood out.
+    def check(spec)
+      get = ->(k) { (spec[k] || spec[k.to_s]).to_s.strip }
+      title = get.call(:title)
+      why = get.call(:why)
+      acceptance = get.call(:acceptance)
+      findings = []
+
+      first_word = title.split(/\s+/).first.to_s.downcase
+      if WORK_VERBS.include?(first_word)
+        findings << Finding.new(field: 'title',
+                                message: "starts with '#{first_word}' — name the promise a user gets, not the work " \
+                                         '(e.g. "Dispatchers see current shipment status", not "Implement status polling")')
+      end
+
+      { 'title' => title, 'why' => why, 'acceptance' => acceptance }.each do |field, text|
+        opening = COMMENTARY_OPENINGS.find { |o| text.downcase.start_with?(o) }
+        if opening
+          findings << Finding.new(field: field,
+                                  message: "opens with \"#{opening}\" — state the promise itself, with the real actor as the subject")
+        end
+        filler = FILLER.select { |f| text.downcase.include?(f) }
+        unless filler.empty?
+          findings << Finding.new(field: field,
+                                  message: "uses filler (#{filler.join(', ')}) — say what a reviewer could observe instead")
+        end
+      end
+
+      findings << Finding.new(field: 'why', message: 'is missing — who needs this, and what goes wrong without it?') if why.empty?
+
+      if acceptance.empty?
+        findings << Finding.new(field: 'acceptance', message: 'is missing — a reviewer needs a rule they can check')
+      else
+        rule, example = split_example(acceptance)
+        if example.nil?
+          findings << Finding.new(field: 'acceptance',
+                                  message: "has no 'Example: ...' — add one concrete case that would pass the rule")
+        end
+        sentences = rule.split(/(?<=[.!?])\s+(?=[A-Z])/).reject { |s| s.strip.empty? }
+        if sentences.length > 2
+          findings << Finding.new(field: 'acceptance',
+                                  message: "states #{sentences.length} sentences of rule — if they could pass or fail " \
+                                           'separately, split them into their own requirements')
+        end
+        if rule.match?(/\d/)
+          findings << Finding.new(field: 'acceptance',
+                                  message: 'contains a number — keep it only if the source decided it; never invent a limit, price or timeout')
+        end
+      end
+
+      if title.downcase == why.downcase && !why.empty?
+        findings << Finding.new(field: 'why', message: 'repeats the title — say why the outcome matters')
+      end
+
+      if get.call(:source_type).empty?
+        findings << Finding.new(field: 'source',
+                                message: 'none given — pass --source-type/--source-url (repo_scan with --source-ref when you read it from the code)')
+      end
+
+      findings
+    end
+
+    # [rule, example_or_nil] — the example is whatever follows "Example:".
+    def split_example(acceptance)
+      idx = acceptance =~ /\bexample:/i
+      return [acceptance, nil] if idx.nil?
+
+      [acceptance[0...idx].strip, acceptance[idx..].sub(/\Aexample:\s*/i, '').strip]
+    end
+  end
+end

data/lib/fp/rspec_json.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Fp
+  module JUnit
+    # RSpec's built-in JSON report (`rspec --format json --out rspec.json`), read into the
+    # same TestCase structs a JUnit report produces (Fizzy #1786). Getting JUnit out of
+    # RSpec takes the `rspec_junit_formatter` gem, which most Gemfiles don't carry, so a
+    # first `fp report` meant editing the project before it could report anything. The
+    # JSON formatter ships with rspec-core and carries everything binding needs: the file,
+    # the example's line, its full description and its status.
+    module RspecJson
+      module_function
+
+      # Content sniffing rather than a flag or a file extension: every `--junit` option
+      # accepts it unchanged, and an XML report can never start with `{`.
+      def json?(content)
+        content.lstrip.start_with?('{')
+      end
+
+      def parse(content, path = 'report')
+        data = JSON.parse(content)
+        examples = data.is_a?(Hash) ? data['examples'] : nil
+        unless examples.is_a?(Array)
+          raise ArgumentError,
+                "#{path} is JSON but not RSpec's --format json output (no \"examples\" list). " \
+                'Pass a JUnit XML report or `rspec --format json --out <file>`.'
+        end
+
+        examples.map { |example| testcase(example) }
+      rescue JSON::ParserError => e
+        raise ArgumentError, "Could not parse JSON report (#{path}): #{e.message}"
+      end
+
+      # passed → present; pending (RSpec's `skip`/`pending`/`xit`) → skipped, which
+      # agents file as a stub, as with a JUnit <skipped/>; failed → failed, which only
+      # CI acts on.
+      def testcase(example)
+        file = example['file_path'].to_s
+        status = example['status'].to_s
+        TestCase.new(
+          name: (example['full_description'] || example['description']).to_s,
+          classname: file,
+          file: file.empty? ? nil : file,
+          line: example['line_number']&.to_i,
+          status: status == 'pending' ? :skipped : :present,
+          failed: status == 'failed',
+          attachments: []
+        )
+      end
+    end
+  end
+end

data/lib/fp/tutorial/hexhaven/AGENTS.md

@@ -0,0 +1,5 @@
+# Hexhaven: agent notes
+
+Practice repo for the FeatureParity tutorial: a made-up board game's game server.
+Tests: `ruby -Ilib test/rules_test.rb` (prefix `JUNIT_OUT=junit.xml` for a report).
+Everything here is the `server` surface, so pin markers with `@server`.

data/lib/fp/tutorial/hexhaven/README.md

@@ -0,0 +1,29 @@
+# Hexhaven: your FeatureParity practice table
+
+Hexhaven's game server: the referee that checks every move. Rules in `lib/`, tests in
+`test/`. Plain Ruby; nothing to install.
+
+1. Run the tests:
+
+   ```sh
+   ruby -Ilib test/rules_test.rb
+   ```
+
+2. Put this above the last test in `test/rules_test.rb`, or ask your agent to
+   (`AGENTS.md` tells it how):
+
+   ```ruby
+   # fp:tallest_tower_scores_two_points@server
+   ```
+
+3. Report it:
+
+   ```sh
+   JUNIT_OUT=junit.xml ruby -Ilib test/rules_test.rb
+   fp report --junit junit.xml --repo hexhaven/server
+   ```
+
+The tallest-tower cell on Server turns from **missing** to **present**. Back to the
+tutorial.
+
+Made a mess? `fp tutorial --restart`

data/lib/fp/tutorial/hexhaven/lib/hexhaven.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Hexhaven — a made-up board game, and the rules its game server referees.
+#
+# Every rule here is a requirement in your FeatureParity tutorial project. The server checks
+# every move; Web, iOS and Android each show the same rules on their own, and FeatureParity
+# proves all four agree.
+module Hexhaven
+  DIE = (1..6).freeze
+  HARBOR_RATE = 3
+  TALLEST_TOWER_MINIMUM = 5
+  TALLEST_TOWER_POINTS = 2
+
+  # A turn starts with two six-sided dice.
+  def self.roll(rng = Random.new)
+    [rng.rand(DIE), rng.rand(DIE)]
+  end
+
+  # At a harbor, three of one good buy one of any other.
+  def self.harbor_trade(hand, give:, get:)
+    raise ArgumentError, "a harbor trade needs #{HARBOR_RATE} #{give}" if hand.fetch(give, 0) < HARBOR_RATE
+
+    hand.merge(give => hand[give] - HARBOR_RATE, get => hand.fetch(get, 0) + 1)
+  end
+
+  # Who holds the tallest-tower bonus, given each player's tallest tower in floors. The
+  # first tower of five floors or more takes it; only a strictly taller one steals it.
+  def self.tallest_tower(towers, holder: nil)
+    contenders = towers.select { |_, floors| floors >= TALLEST_TOWER_MINIMUM }
+    return nil if contenders.empty?
+
+    best = contenders.values.max
+    holder = nil unless holder && towers.fetch(holder, 0) == best
+    holder || contenders.key(best)
+  end
+end

data/lib/fp/tutorial/hexhaven/test/junit_reporter.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+# A dependency-free JUnit XML reporter for Minitest, written only when JUNIT_OUT is set.
+#
+# `fp report --junit` reads the report, opens each test's file, and finds the fp:<slug>
+# marker above it. That is why every testcase carries the file and line it was declared
+# on.
+
+require 'minitest'
+require 'fileutils'
+
+module MinitestJUnitReporter
+  class Reporter < Minitest::AbstractReporter
+    def initialize(output_path, base_dir)
+      super()
+      @output_path = output_path
+      @base_dir = File.expand_path(base_dir)
+      @results = []
+    end
+
+    def record(result)
+      @results << result
+    end
+
+    def report
+      FileUtils.mkdir_p(File.dirname(@output_path))
+      File.write(@output_path, xml)
+    end
+
+    private
+
+    def xml
+      failures = @results.count { |r| r.failures.any? { |f| !f.is_a?(Minitest::Skip) } }
+      skips = @results.count { |r| r.failures.any? { |f| f.is_a?(Minitest::Skip) } }
+      time = @results.sum(&:time)
+
+      body = @results.map { |r| testcase_xml(r) }.join
+
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <testsuites>
+          <testsuite name="minitest" tests="#{@results.size}" failures="#{failures}" errors="0" skipped="#{skips}" time="#{format('%.6f', time)}">
+        #{body}  </testsuite>
+        </testsuites>
+      XML
+    end
+
+    def testcase_xml(result)
+      file, line = declaring_location(result)
+      attrs = [
+        %(name="#{esc(result.name)}"),
+        %(classname="#{esc(result.klass)}"),
+        %(file="#{esc(relative_to_base(file))}"),
+        # `line` is what lets `fp` bind each marker to the specific test below it. Without
+        # it fp can only handle files with exactly one marker.
+        (%(line="#{line}") if line),
+        %(time="#{format('%.6f', result.time)}")
+      ].compact.join(' ')
+
+      skip = result.failures.find { |f| f.is_a?(Minitest::Skip) }
+      real_failures = result.failures.reject { |f| f.is_a?(Minitest::Skip) }
+
+      if skip
+        %(    <testcase #{attrs}>\n      <skipped message="#{esc(skip.message)}"/>\n    </testcase>\n)
+      elsif real_failures.any?
+        inner = real_failures.map do |f|
+          tag = f.is_a?(Minitest::UnexpectedError) ? 'error' : 'failure'
+          %(      <#{tag} message="#{esc(f.message)}"/>\n)
+        end.join
+        %(    <testcase #{attrs}>\n#{inner}    </testcase>\n)
+      else
+        %(    <testcase #{attrs}/>\n)
+      end
+    end
+
+    # Where the test method is declared, as [path, line]. The path is what `fp` opens to
+    # look for markers and the line is what binds a marker to its test, so this matters
+    # more than the rest of the report.
+    def declaring_location(result)
+      # Minitest 5.18+ exposes source_location on the result.
+      return result.source_location if result.respond_to?(:source_location)
+
+      # Older minitest: ask the test class for the method's definition site.
+      klass = Object.const_get(result.klass.to_s)
+      klass.instance_method(result.name).source_location || [nil, nil]
+    rescue StandardError
+      [nil, nil]
+    end
+
+    def relative_to_base(path)
+      return '' unless path
+
+      absolute = File.expand_path(path)
+      relative = absolute.delete_prefix("#{@base_dir}/")
+      relative == absolute ? path : relative
+    rescue StandardError
+      ''
+    end
+
+    def esc(str)
+      str.to_s
+         .gsub('&', '&amp;').gsub('<', '&lt;').gsub('>', '&gt;')
+         .gsub('"', '&quot;').gsub("'", '&apos;')
+         .gsub(/[^[:print:]\t\n]/, '')
+    end
+  end
+
+  class << self
+    # Register as a Minitest plugin. Minitest calls plugin_<name>_init while building its
+    # composite reporter, which is the only point where a reporter can still be added.
+    # No-op unless JUNIT_OUT is set, so ordinary test runs are unaffected.
+    def install!
+      path = ENV['JUNIT_OUT']
+      return if path.nil? || path.strip.empty?
+      return if @installed
+
+      @installed = true
+      @output_path = File.expand_path(path)
+      @base_dir = ENV['JUNIT_BASE_DIR'] || Dir.pwd
+
+      Minitest.extensions << 'junit_xml' unless Minitest.extensions.include?('junit_xml')
+
+      Minitest.singleton_class.define_method(:plugin_junit_xml_init) do |_options|
+        Minitest.reporter << MinitestJUnitReporter.build_reporter
+      end
+    end
+
+    def build_reporter
+      Reporter.new(@output_path, @base_dir)
+    end
+  end
+end
+
+MinitestJUnitReporter.install!

data/lib/fp/tutorial/hexhaven/test/rules_test.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+
+# The referee's rules, each bound to the requirement it proves by the fp: comment directly
+# above it. `@server` pins the surface, since this repo is the game server.
+class RulesTest < Minitest::Test
+  # fp:turn_starts_with_two_dice@server
+  def test_a_turn_rolls_two_six_sided_dice
+    100.times do
+      dice = Hexhaven.roll
+      assert_equal 2, dice.size
+      dice.each { |die| assert_includes 1..6, die }
+    end
+  end
+
+  # fp:harbor_trades_three_for_one@server
+  def test_three_wool_become_one_brick_at_a_harbor
+    hand = Hexhaven.harbor_trade({ wool: 3 }, give: :wool, get: :brick)
+
+    assert_equal({ wool: 0, brick: 1 }, hand)
+  end
+
+  # fp:harbor_trades_three_for_one@server
+  def test_a_harbor_refuses_fewer_than_three
+    assert_raises(ArgumentError) { Hexhaven.harbor_trade({ wool: 2 }, give: :wool, get: :brick) }
+  end
+
+  # 👉 Your move: put this line (uncommented) above the test, or ask your agent to.
+  #      # fp:tallest_tower_scores_two_points@server
+  def test_a_six_floor_tower_takes_the_bonus_from_a_five_floor_tower
+    assert_equal :ada, Hexhaven.tallest_tower({ ada: 5, ben: 3 })
+    assert_equal :ben, Hexhaven.tallest_tower({ ada: 5, ben: 6 }, holder: :ada)
+    assert_nil Hexhaven.tallest_tower({ ada: 4, ben: 4 })
+  end
+end

data/lib/fp/tutorial/hexhaven/test/test_helper.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+# Writes a JUnit report when JUNIT_OUT is set, which is what `fp report --junit` reads.
+require_relative 'junit_reporter'
+require_relative '../lib/hexhaven'

data/lib/fp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fp
-  VERSION = '0.0.27'
+  VERSION = '0.0.29'
 end

data/lib/fp.rb

@@ -7,6 +7,7 @@ require_relative 'fp/parity'
 require_relative 'fp/client'
 require_relative 'fp/source_fingerprint'
 require_relative 'fp/junit'
+require_relative 'fp/repo_detector'
 require_relative 'fp/output'
 require_relative 'fp/commands'
 require_relative 'fp/cli'