featureparity 0.0.28 → 0.0.29

data/lib/fp/repo_detector.rb

@@ -0,0 +1,488 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+
+module Fp
+  # Reads a checkout and says what it is, for `fp init --detect` and `fp doctor`
+  # (Fizzy #1786): the frameworks and test runners it uses, the exact command that makes
+  # each runner emit a report fp can read (and whether that needs a dependency added), a
+  # project slug, the surfaces a user would touch, whether the tests need a database, and
+  # whether there's a devcontainer.
+  #
+  # Purely local and read-only: it looks at manifests (Gemfile, package.json, Podfile,
+  # pyproject, Android manifests, Rails routes) in the root and one directory down, which
+  # covers the common `frontend/` + `backend/` monorepo without walking node_modules. It
+  # suggests; the human picks. Nothing here is written anywhere.
+  class RepoDetector
+    # What makes something a surface. Printed beside every suggestion, because the
+    # suggestion is only a starting point and this is the rule to judge it by.
+    SURFACE_RUBRIC = 'A surface is somewhere a user interacts with the product: a web app, ' \
+                     'an iOS or Android app, a desktop app, a CLI, or an API that customers ' \
+                     'call directly. An internal API with no separate client is not one: ' \
+                     'its tests are evidence for the surface the user touches.'
+
+    SKIP_DIRS = %w[node_modules vendor tmp log coverage dist build .git .bundle Pods].freeze
+
+    # Database drivers that need a running server. SQLite is a file, so it's reported but
+    # never makes `needed` true.
+    RUBY_DB_GEMS = { 'pg' => 'postgresql', 'mysql2' => 'mysql', 'trilogy' => 'mysql',
+                     'mongoid' => 'mongodb', 'sqlite3' => 'sqlite' }.freeze
+    JS_DB_PACKAGES = { 'pg' => 'postgresql', 'postgres' => 'postgresql', 'mysql' => 'mysql',
+                       'mysql2' => 'mysql', 'mongodb' => 'mongodb', 'mongoose' => 'mongodb',
+                       'better-sqlite3' => 'sqlite', 'sqlite3' => 'sqlite' }.freeze
+    PY_DB_PACKAGES = { 'psycopg2' => 'postgresql', 'psycopg2-binary' => 'postgresql',
+                       'psycopg' => 'postgresql', 'asyncpg' => 'postgresql',
+                       'mysqlclient' => 'mysql', 'pymysql' => 'mysql', 'pymongo' => 'mongodb' }.freeze
+    DB_ADAPTERS = { 'postgresql' => 'postgresql', 'postgis' => 'postgresql', 'mysql2' => 'mysql',
+                    'trilogy' => 'mysql', 'sqlite3' => 'sqlite' }.freeze
+    COMPOSE_IMAGES = { 'postgres' => 'postgresql', 'postgis' => 'postgresql', 'mysql' => 'mysql',
+                       'mariadb' => 'mysql', 'mongo' => 'mongodb' }.freeze
+    SERVER_DATABASES = %w[postgresql mysql mongodb].freeze
+
+    COMPOSE_FILES = %w[docker-compose.yml docker-compose.yaml compose.yml compose.yaml].freeze
+
+    attr_reader :root
+
+    def initialize(root = Dir.pwd)
+      @root = File.expand_path(root)
+    end
+
+    # Everything, as one plain hash (string keys, JSON-ready).
+    def detect
+      @detect ||= begin
+        dirs = scan_dirs
+        frameworks = []
+        runners = []
+        surfaces = []
+        databases = []
+        dirs.each { |dir| inspect_dir(dir, frameworks, runners, surfaces, databases) }
+        databases.concat(compose_databases)
+
+        {
+          'root' => root,
+          'slug' => suggested_slug,
+          'repo' => git_remote_repo,
+          'frameworks' => frameworks.uniq,
+          'test_runners' => runners.uniq { |r| [r['name'], r['dir']] },
+          'surfaces' => merge_surfaces(surfaces),
+          'surface_rubric' => SURFACE_RUBRIC,
+          'database' => database_summary(databases),
+          'devcontainer' => devcontainer_path
+        }
+      end
+    end
+
+    # "org/repo" from the origin remote, when there is one.
+    def git_remote_repo
+      url = git_remote_url
+      return nil unless url
+
+      match = url.match(%r{[:/]([^/:]+/[^/]+?)(?:\.git)?/?\z})
+      match && match[1]
+    end
+
+    def suggested_slug
+      repo = git_remote_repo
+      self.class.slugify(repo ? repo.split('/').last : File.basename(root))
+    end
+
+    def self.slugify(name)
+      name.to_s.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/\A-+|-+\z/, '')
+    end
+
+    # The one-line database note, shared by doctor, `fp init --detect` and init's guidance.
+    def self.database_note(database)
+      return nil unless database && database['needed']
+
+      kinds = database['kinds'] & SERVER_DATABASES
+      "The tests need a #{kinds.join('/')} server (#{database['evidence'].first(3).join('; ')}). " \
+        "The generated CI workflow has no database service: add one to its report job before the tests run there."
+    end
+
+    # Human-readable summary of #detect, printed by `fp doctor` and `fp init --detect`.
+    def self.print_summary(repo, out: $stdout)
+      out.puts 'Repo'
+      out.puts "  Suggested slug:  #{repo['slug']}#{repo['repo'] ? "  (from git remote #{repo['repo']})" : '  (from the directory name)'}"
+      frameworks = repo['frameworks'].map { |f| f['dir'] == '.' ? f['name'] : "#{f['name']} (#{f['dir']})" }
+      out.puts "  Frameworks:      #{frameworks.empty? ? '(none recognised)' : frameworks.uniq.join(', ')}"
+
+      if repo['surfaces'].empty?
+        out.puts '  Surfaces:        (none suggested)'
+      else
+        out.puts '  Surfaces:'
+        repo['surfaces'].each do |s|
+          out.puts "    #{s['key'].ljust(8)} #{s['reasons'].join('; ')}"
+          out.puts "             #{s['note']}" if s['note']
+        end
+      end
+      out.puts "  Rubric:          #{repo['surface_rubric']}"
+
+      if repo['test_runners'].empty?
+        out.puts '  Test runners:    (none recognised) — any runner that writes JUnit XML works with `fp report --junit`'
+      else
+        out.puts '  Test runners:'
+        repo['test_runners'].each do |r|
+          where = r['dir'] == '.' ? '' : " (#{r['dir']})"
+          out.puts "    #{r['name']}#{where}"
+          out.puts "      report:  #{r['report_command']}"
+          out.puts "      needs:   #{r['dependency'] ? "add #{r['dependency']}" : 'nothing added to the project'}"
+          out.puts "      or:      #{r['alternative']}" if r['alternative']
+          out.puts "      fp run:  #{r['fp_run']}" if r['fp_run']
+        end
+      end
+
+      db = repo['database']
+      out.puts "  Database:        #{db['needed'] ? "needed — #{(db['kinds'] & SERVER_DATABASES).join(', ')}" : (db['kinds'].empty? ? 'none detected' : "#{db['kinds'].join(', ')} (no server needed)")}"
+      db['evidence'].each { |e| out.puts "                   #{e}" } if db['needed']
+      out.puts "  Devcontainer:    #{repo['devcontainer'] || 'none'}#{repo['devcontainer'] && db['needed'] ? ' (it may already provide the database)' : ''}"
+      note = database_note(db)
+      out.puts "  Note:            #{note}" if note
+    end
+
+    private
+
+    # The root and its immediate subdirectories that hold a manifest.
+    def scan_dirs
+      subdirs = Dir.children(root).sort.select do |name|
+        !name.start_with?('.') && !SKIP_DIRS.include?(name) && File.directory?(File.join(root, name))
+      end
+      ['.'] + subdirs
+    rescue SystemCallError
+      ['.']
+    end
+
+    def path(dir, *parts)
+      File.join(root, dir, *parts)
+    end
+
+    def file?(dir, *parts)
+      File.file?(path(dir, *parts))
+    end
+
+    def read(dir, *parts)
+      File.read(path(dir, *parts))
+    rescue SystemCallError
+      ''
+    end
+
+    def label(dir, file)
+      dir == '.' ? file : File.join(dir, file)
+    end
+
+    def inspect_dir(dir, frameworks, runners, surfaces, databases)
+      inspect_ruby(dir, frameworks, runners, surfaces, databases) if file?(dir, 'Gemfile')
+      inspect_js(dir, frameworks, runners, surfaces, databases) if file?(dir, 'package.json')
+      inspect_python(dir, frameworks, runners, surfaces, databases) if python?(dir)
+      inspect_ios(dir, frameworks, runners, surfaces)
+      inspect_android(dir, frameworks, runners, surfaces)
+    end
+
+    # --- Ruby ---------------------------------------------------------------
+
+    def ruby_gems(dir)
+      gems = read(dir, 'Gemfile').scan(/^\s*gem\s+['"]([^'"]+)['"]/).flatten
+      # Gemfile.lock's specs carry transitive gems too (rspec-core under rspec-rails).
+      gems += read(dir, 'Gemfile.lock').scan(/^ {4}([a-zA-Z0-9_.-]+) \(/).flatten
+      gemspec = Dir.glob(path(dir, '*.gemspec')).first
+      gems += File.read(gemspec).scan(/add_(?:development_)?dependency\s*\(?\s*['"]([^'"]+)['"]/).flatten if gemspec
+      gems.uniq
+    end
+
+    def inspect_ruby(dir, frameworks, runners, surfaces, databases)
+      gems = ruby_gems(dir)
+
+      if gems.include?('rails') || gems.include?('railties')
+        api_only = read(dir, 'config', 'application.rb').match?(/config\.api_only\s*=\s*true/)
+        frameworks << { 'name' => 'rails', 'dir' => dir, 'evidence' => label(dir, 'Gemfile') }
+        if api_only
+          surfaces << api_surface(dir, 'Rails app with config.api_only')
+        elsif rails_views?(dir)
+          surfaces << surface('web', dir, "Rails app with views (#{label(dir, 'app/views')})")
+          if read(dir, 'config', 'routes.rb').match?(/namespace\s+:api\b|scope\s+['"]\/?api/)
+            surfaces << api_surface(dir, "#{label(dir, 'config/routes.rb')} has an api namespace")
+          end
+        else
+          surfaces << api_surface(dir, 'Rails app with no views')
+        end
+      elsif gems.include?('sinatra') || gems.include?('roda') || gems.include?('hanami')
+        name = (%w[sinatra roda hanami] & gems).first
+        frameworks << { 'name' => name, 'dir' => dir, 'evidence' => label(dir, 'Gemfile') }
+        surfaces << api_surface(dir, "#{name} app")
+      end
+
+      gemspec = Dir.glob(path(dir, '*.gemspec')).first
+      if gemspec && File.read(gemspec).match?(/\.executables\s*=/)
+        surfaces << surface('cli', dir, "#{label(dir, File.basename(gemspec))} ships executables")
+      end
+
+      rails = frameworks.any? { |f| f['name'] == 'rails' && f['dir'] == dir }
+      if gems.include?('rspec-core') || gems.include?('rspec-rails') || gems.include?('rspec') ||
+         file?(dir, '.rspec') || File.directory?(path(dir, 'spec'))
+        runners << rspec_runner(dir, gems)
+      end
+      if (rails && !gems.include?('rspec-rails')) || gems.include?('minitest') ||
+         Dir.glob(path(dir, 'test', '**', '*_test.rb')).any?
+        runners << minitest_runner(dir, gems, rails)
+      end
+
+      gems.each do |gem|
+        databases << { 'kind' => RUBY_DB_GEMS[gem], 'evidence' => "#{label(dir, 'Gemfile')}: #{gem}" } if RUBY_DB_GEMS[gem]
+      end
+      adapters = read(dir, 'config', 'database.yml').scan(/^\s*adapter:\s*["']?([a-z0-9_]+)/).flatten.uniq
+      adapters.each do |adapter|
+        kind = DB_ADAPTERS[adapter]
+        databases << { 'kind' => kind, 'evidence' => "#{label(dir, 'config/database.yml')}: adapter #{adapter}" } if kind
+      end
+    end
+
+    def rails_views?(dir)
+      Dir.glob(path(dir, 'app', 'views', '**', '*')).any? do |f|
+        File.file?(f) && !f.include?('/layouts/') && !f.match?(%r{/views/[^/]*mailer})
+      end
+    end
+
+    def rspec_runner(dir, gems)
+      prefix = gems.include?('rspec-core') || gems.include?('rspec-rails') ? 'bundle exec ' : ''
+      command = "#{prefix}rspec"
+      runner('rspec', dir,
+             command: command,
+             report_command: "#{command} --format progress --format json --out rspec.json",
+             report_file: 'rspec.json',
+             dependency: nil,
+             alternative: "#{command} --format RspecJunitFormatter --out junit.xml " \
+                          "(needs gem 'rspec_junit_formatter' in the Gemfile's test group)",
+             fp_run: true)
+    end
+
+    def minitest_runner(dir, gems, rails)
+      command = rails ? 'bin/rails test' : 'bundle exec rake test'
+      report = rails ? "#{command} --junit --junit-filename=junit.xml" : "#{command} TESTOPTS=\"--junit --junit-filename=junit.xml\""
+      runner('minitest', dir,
+             command: command,
+             report_command: report,
+             report_file: 'junit.xml',
+             dependency: gems.include?('minitest-junit') ? nil : "gem 'minitest-junit', group: :test",
+             fp_run: false)
+    end
+
+    # --- JavaScript -----------------------------------------------------------
+
+    def inspect_js(dir, frameworks, runners, surfaces, databases)
+      pkg = begin
+        JSON.parse(read(dir, 'package.json'))
+      rescue JSON::ParserError
+        {}
+      end
+      deps = (pkg['dependencies'] || {}).merge(pkg['devDependencies'] || {}).keys
+      evidence = label(dir, 'package.json')
+
+      mobile = (deps & %w[react-native expo]).first
+      web = (deps & %w[next nuxt @remix-run/react @sveltejs/kit svelte vue @angular/core react vite]).first
+      server = (deps & %w[express fastify koa @nestjs/core hono]).first
+
+      [mobile, web, server, ('electron' if deps.include?('electron'))].compact.each do |name|
+        frameworks << { 'name' => name, 'dir' => dir, 'evidence' => evidence }
+      end
+
+      if mobile
+        surfaces << surface('ios', dir, "#{mobile} app (#{evidence})")
+        surfaces << surface('android', dir, "#{mobile} app (#{evidence})")
+      elsif deps.include?('electron')
+        surfaces << surface('desktop', dir, "electron app (#{evidence})")
+      elsif web
+        surfaces << surface('web', dir, "#{web} front end (#{evidence})")
+      elsif server
+        surfaces << api_surface(dir, "#{server} server (#{evidence})")
+      end
+      surfaces << surface('cli', dir, "#{evidence} declares a bin") if pkg['bin'] && !web && !mobile
+
+      runner_prefix = npx_for(dir)
+      if deps.include?('vitest')
+        runners << runner('vitest', dir,
+                          command: "#{runner_prefix} vitest run",
+                          report_command: "#{runner_prefix} vitest run --reporter=default --reporter=junit --outputFile.junit=junit.xml",
+                          report_file: 'junit.xml', dependency: nil, fp_run: true)
+      end
+      if deps.include?('jest')
+        runners << runner('jest', dir,
+                          command: "#{runner_prefix} jest",
+                          report_command: "JEST_JUNIT_OUTPUT_FILE=junit.xml #{runner_prefix} jest --ci --reporters=default --reporters=jest-junit",
+                          report_file: 'junit.xml',
+                          dependency: deps.include?('jest-junit') ? nil : 'jest-junit (devDependency)',
+                          fp_run: false)
+      end
+      if deps.include?('@playwright/test')
+        runners << runner('playwright', dir,
+                          command: "#{runner_prefix} playwright test",
+                          report_command: "PLAYWRIGHT_JUNIT_OUTPUT_NAME=junit.xml #{runner_prefix} playwright test --reporter=list,junit",
+                          report_file: 'junit.xml', dependency: nil, fp_run: true)
+      end
+
+      deps.each do |dep|
+        databases << { 'kind' => JS_DB_PACKAGES[dep], 'evidence' => "#{evidence}: #{dep}" } if JS_DB_PACKAGES[dep]
+      end
+      provider = read(dir, 'prisma', 'schema.prisma')[/provider\s*=\s*"(postgresql|mysql|mongodb|sqlite)"/, 1]
+      databases << { 'kind' => provider, 'evidence' => "#{label(dir, 'prisma/schema.prisma')}: #{provider}" } if provider
+    end
+
+    def npx_for(dir)
+      return 'pnpm exec' if file?(dir, 'pnpm-lock.yaml')
+      return 'yarn' if file?(dir, 'yarn.lock')
+      return 'bunx' if file?(dir, 'bun.lockb') || file?(dir, 'bun.lock')
+
+      'npx'
+    end
+
+    # --- Python ---------------------------------------------------------------
+
+    PY_MANIFESTS = %w[pyproject.toml requirements.txt requirements-dev.txt setup.cfg setup.py Pipfile].freeze
+
+    def python?(dir)
+      PY_MANIFESTS.any? { |f| file?(dir, f) } || file?(dir, 'pytest.ini')
+    end
+
+    def inspect_python(dir, frameworks, runners, surfaces, databases)
+      text = PY_MANIFESTS.map { |f| read(dir, f) }.join("\n").downcase
+      has = ->(name) { text.match?(/(?:^|["'\s\[,])#{Regexp.escape(name)}(?:[\s"'<>=~!\[;,]|$)/) }
+
+      framework = %w[django fastapi flask].find { |name| has.call(name) }
+      if framework
+        frameworks << { 'name' => framework, 'dir' => dir, 'evidence' => label(dir, 'pyproject/requirements') }
+        if framework == 'django' && Dir.glob(path(dir, '**', 'templates')).any?
+          surfaces << surface('web', dir, 'Django app with templates')
+        else
+          surfaces << api_surface(dir, "#{framework} app")
+        end
+      end
+
+      if has.call('pytest') || file?(dir, 'pytest.ini') || file?(dir, 'conftest.py')
+        runners << runner('pytest', dir,
+                          command: 'pytest',
+                          report_command: 'pytest -o junit_family=xunit1 --junitxml=junit.xml',
+                          report_file: 'junit.xml', dependency: nil, fp_run: true)
+      end
+
+      PY_DB_PACKAGES.each do |pkg, kind|
+        databases << { 'kind' => kind, 'evidence' => "#{label(dir, 'requirements')}: #{pkg}" } if has.call(pkg)
+      end
+    end
+
+    # --- Mobile ---------------------------------------------------------------
+
+    def inspect_ios(dir, frameworks, runners, surfaces)
+      xcode = Dir.glob(path(dir, '*.{xcodeproj,xcworkspace}')).first
+      podfile = file?(dir, 'Podfile')
+      spm = file?(dir, 'Package.swift')
+      return unless xcode || podfile || spm
+
+      evidence = xcode ? label(dir, File.basename(xcode)) : label(dir, podfile ? 'Podfile' : 'Package.swift')
+      frameworks << { 'name' => 'ios', 'dir' => dir, 'evidence' => evidence }
+      surfaces << surface('ios', dir, "Xcode project (#{evidence})") if xcode || podfile
+
+      if xcode || podfile
+        runners << runner('xctest', dir,
+                          command: 'xcodebuild test -scheme <Scheme> -destination "platform=iOS Simulator,name=iPhone 16"',
+                          report_command: 'xcodebuild test -scheme <Scheme> -destination "platform=iOS Simulator,name=iPhone 16" ' \
+                                          '| xcbeautify --report junit --report-path . --junit-report-filename junit.xml',
+                          report_file: 'junit.xml',
+                          dependency: 'xcbeautify (brew install xcbeautify)', fp_run: false)
+      else
+        runners << runner('xctest', dir, command: 'swift test',
+                                         report_command: 'swift test --xunit-output junit.xml',
+                                         report_file: 'junit.xml', dependency: nil, fp_run: false)
+      end
+    end
+
+    def inspect_android(dir, frameworks, runners, surfaces)
+      manifests = Dir.glob(path(dir, '{,*/}src/main/AndroidManifest.xml'))
+      return if manifests.empty?
+
+      evidence = manifests.first.delete_prefix("#{root}/")
+      frameworks << { 'name' => 'android', 'dir' => dir, 'evidence' => evidence }
+      surfaces << surface('android', dir, "Android manifest (#{evidence})")
+      runners << runner('gradle', dir,
+                        command: './gradlew test',
+                        report_command: './gradlew test   # writes JUnit XML to */build/test-results/**/*.xml',
+                        report_file: 'build/test-results', dependency: nil, fp_run: false)
+    end
+
+    # --- Shared -----------------------------------------------------------------
+
+    def runner(name, dir, command:, report_command:, report_file:, dependency:, fp_run:, alternative: nil)
+      cd = dir == '.' ? '' : "cd #{dir} && "
+      {
+        'name' => name,
+        'dir' => dir,
+        'command' => command,
+        'report_command' => "#{cd}#{report_command}",
+        'report_file' => dir == '.' ? report_file : File.join(dir, report_file),
+        'dependency' => dependency,
+        'alternative' => alternative,
+        # `fp run` injects the formatter itself, so it needs no dependency at all.
+        'fp_run' => fp_run ? "#{cd}fp run --surface <surface> --repo <org/repo> -- #{command}" : nil
+      }.compact
+    end
+
+    def surface(key, dir, reason, note = nil)
+      { 'key' => key, 'dir' => dir, 'reasons' => [reason], 'note' => note }.compact
+    end
+
+    def api_surface(dir, reason)
+      surface('api', dir, reason,
+              'Only a surface if customers call it directly. If it only serves your own ' \
+              'web or mobile app, report its tests against that surface instead.')
+    end
+
+    def merge_surfaces(surfaces)
+      surfaces.group_by { |s| s['key'] }.map do |key, group|
+        merged = { 'key' => key, 'reasons' => group.flat_map { |s| s['reasons'] }.uniq }
+        note = group.map { |s| s['note'] }.compact.first
+        merged['note'] = note if note
+        merged
+      end
+    end
+
+    def compose_databases
+      COMPOSE_FILES.flat_map do |name|
+        file = File.join(root, name)
+        next [] unless File.file?(file)
+
+        File.read(file).scan(/^\s*image:\s*["']?(?:[\w.-]+\/)*([a-z0-9_-]+)/).flatten.uniq.filter_map do |image|
+          kind = COMPOSE_IMAGES[image]
+          { 'kind' => kind, 'evidence' => "#{name}: #{image} service" } if kind
+        end
+      end
+    end
+
+    def database_summary(databases)
+      databases = databases.uniq
+      kinds = databases.map { |d| d['kind'] }.uniq
+      server = kinds & SERVER_DATABASES
+      {
+        'needed' => !server.empty?,
+        'kinds' => kinds,
+        'evidence' => databases.map { |d| d['evidence'] }.uniq
+      }
+    end
+
+    def devcontainer_path
+      %w[.devcontainer/devcontainer.json .devcontainer.json .devcontainer].find do |candidate|
+        File.exist?(File.join(root, candidate))
+      end
+    end
+
+    def git_remote_url
+      return @git_remote_url if defined?(@git_remote_url)
+
+      @git_remote_url = begin
+        out, status = Open3.capture2e('git', '-C', root, 'remote', 'get-url', 'origin')
+        status.success? ? out.strip : nil
+      rescue SystemCallError
+        nil
+      end
+      @git_remote_url = nil if @git_remote_url&.empty?
+      @git_remote_url
+    end
+  end
+end

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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fp
-  VERSION = '0.0.28'
+  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'