featureparity 0.0.27 → 0.0.29

data/lib/fp/junit.rb

@@ -3,6 +3,7 @@
 require 'rexml/document'
 require 'pathname'
 require_relative 'source_fingerprint'
+require_relative 'rspec_json'
 
 module Fp
   # Parses JUnit XML reports and binds testcases to fp:<slug> markers found in
@@ -83,7 +84,7 @@ module Fp
     # testcase's own line when the runner reported one, otherwise the line of
     # the fp:<slug> marker that annotates it (markers sit directly above the
     # test, so the marker line is a close stand-in when the runner omits lines).
-    Binding = Struct.new(:slug, :surface, :test_type, :file, :line, :title, :state, keyword_init: true)
+    Binding = Struct.new(:slug, :surface, :test_type, :file, :line, :title, :state, :tests, keyword_init: true)
 
     # A media file (video/screenshot) a run recorded for one bound testcase, ready for
     # `fp report --junit --attach-media` to upload as visual evidence. Unlike Binding,
@@ -120,17 +121,51 @@ module Fp
 
     module_function
 
-    # Parse a JUnit XML file into an array of TestCase structs.
+    # Parse a test report into an array of TestCase structs: JUnit XML, or RSpec's
+    # built-in `--format json` output (Fizzy #1786), told apart by content so every
+    # `--junit` flag takes either with no new option. RSpec's JSON needs no extra gem,
+    # where JUnit from RSpec needs `rspec_junit_formatter` in the project's Gemfile.
     # Raises ArgumentError if the file is missing or unparseable.
     def parse_file(path)
       raise ArgumentError, "JUnit file not found: #{path}" unless File.file?(path)
 
-      xml = File.read(path)
-      parse_string(xml)
+      content = File.read(path)
+      return RspecJson.parse(content, path) if RspecJson.json?(content)
+
+      parse_string(content)
     rescue REXML::ParseException => e
       raise ArgumentError, "Could not parse JUnit XML (#{path}): #{e.message}"
     end
 
+    # The report as JUnit XML, whatever format the file is in. The CLI resolves markers
+    # itself, but ci-report and check also send the raw report for servers old enough to
+    # re-resolve it, and those only read XML.
+    def read_xml(path)
+      content = File.read(path)
+      return content unless RspecJson.json?(content)
+
+      to_xml(RspecJson.parse(content, path))
+    end
+
+    # Render parsed testcases as a minimal JUnit document.
+    def to_xml(testcases)
+      doc = REXML::Document.new
+      doc << REXML::XMLDecl.new('1.0', 'UTF-8')
+      suite = doc.add_element('testsuites').add_element('testsuite', 'name' => 'fp',
+                                                                    'tests' => testcases.length.to_s)
+      testcases.each do |tc|
+        attrs = { 'name' => tc.name.to_s, 'classname' => tc.classname.to_s }
+        attrs['file'] = tc.file if tc.file
+        attrs['line'] = tc.line.to_s if tc.line
+        el = suite.add_element('testcase', attrs)
+        el.add_element('skipped') if tc.stub?
+        el.add_element('failure') if tc.failed?
+      end
+      out = +''
+      doc.write(out)
+      out
+    end
+
     def parse_string(xml)
       doc = REXML::Document.new(xml)
       cases = []
@@ -144,7 +179,7 @@ module Fp
           name: el.attributes['name'],
           classname: classname,
           file: resolve_file(el.attributes['file'], classname, suite_name),
-          line: (el.attributes['line'] && el.attributes['line'].to_i),
+          line: testcase_line(el, suite_name),
           status: testcase_status(el),
           failed: testcase_failed?(el),
           attachments: extract_attachments(el)
@@ -154,6 +189,16 @@ module Fp
       cases
     end
 
+    # pytest's `line` (written with junit_family=xunit1, the only family that carries a
+    # file) counts from 0, so a `def` directly under its marker would report the marker's
+    # own line and bind to the marker above that. Its suites are named "pytest".
+    def testcase_line(el, suite_name)
+      line = el.attributes['line']&.to_i
+      return line unless line && suite_name == 'pytest' && el.attributes['file'].to_s.end_with?('.py')
+
+      line + 1
+    end
+
     # Playwright's JUnit reporter records media (video, screenshots, trace) by writing
     # `[[ATTACHMENT|<path>]]` lines into the testcase's `<system-out>`. Pull those paths
     # out so `fp report --junit --attach-media` can upload them as visual evidence for the
@@ -600,12 +645,20 @@ module Fp
       # omitted line info.
       line = testcase.line || (marker && marker[:line])
 
+      # Every testcase that fed this receipt, so `fp report` can say "3 tests → one
+      # receipt" instead of printing one line and leaving the other two unaccounted for.
+      entry = { name: presence(testcase.name), line: line, state: state }
+
       existing = bindings[key]
       # Prefer a concrete 'present' state over 'stub' when a slug has both.
-      return if existing && !(existing.state == 'stub' && state == 'present')
+      if existing && !(existing.state == 'stub' && state == 'present')
+        existing.tests << entry
+        return
+      end
 
       bindings[key] = Binding.new(slug: slug, surface: surface, test_type: test_type, file: rel_file,
-                                  line: line, title: (testcase.name if titles_reliable), state: state)
+                                  line: line, title: (testcase.name if titles_reliable), state: state,
+                                  tests: (existing ? existing.tests : []) + [entry])
     end
 
     # Load and cache the fp:<slug> markers (with line numbers) for an already-resolved
@@ -756,10 +809,16 @@ module Fp
     # How a test (or group) declaration announces its name, per language. Each entry is
     # [regex, kind]; the captured group is the name. `:group` entries are describe-style
     # blocks, whose name prefixes the names of the tests inside them.
+    #
+    # A quoted name may contain its own quote escaped (`'its kind\'s logo'`), so the name
+    # runs to the first *unescaped* closing quote and is unescaped before matching — the
+    # runner reports `its kind's logo`. Stopping at the first quote cut the name off at
+    # `kind\` and the marker silently bound nothing (Fizzy #1759).
+    QUOTED_NAME = %q{((?:\\\\.|(?!\\1).)+?)\\1}
     TEST_DECL_PATTERNS = [
-      [/\b(?:it|test|bench)(?:\.\w+)*\s*\(\s*(['"`])(.+?)\1/, :test],   # vitest/jest/mocha
-      [/\bdescribe(?:\.\w+)*\s*\(\s*(['"`])(.+?)\1/, :group],           # vitest/jest/mocha group
-      [/\b(?:it|specify|scenario)\s+(['"])(.+?)\1/, :test],             # rspec
+      [/\b(?:it|test|bench)(?:\.\w+)*\s*\(\s*(['"`])#{QUOTED_NAME}/, :test],   # vitest/jest/mocha
+      [/\bdescribe(?:\.\w+)*\s*\(\s*(['"`])#{QUOTED_NAME}/, :group],           # vitest/jest/mocha group
+      [/\b(?:it|specify|scenario)\s+(['"])#{QUOTED_NAME}/, :test],             # rspec
       [/\b(?:def|fun)\s+`(.+?)`/, :test],                               # kotlin backticked
       [/\b(?:def|fun|func)\s+(test_?\w+)/i, :test]                      # minitest / xctest / pytest
     ].freeze
@@ -779,7 +838,7 @@ module Fp
           next unless match
 
           # Two-quote patterns capture the quote first, the name second.
-          return [match.captures.last, kind]
+          return [unescape_name(match.captures.last), kind]
         end
 
         # A line of real code that declares nothing recognisable: the marker doesn't
@@ -794,5 +853,9 @@ module Fp
     # the first line of real code regardless, so this only bounds how long a comment block
     # between the marker and its test may be.
     DECL_SEARCH_WINDOW = 40
+
+    def unescape_name(name)
+      name.gsub(/\\(.)/, '\\1')
+    end
   end
 end

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