featureparity 0.0.20 → 0.0.22

data/lib/fp/commands/surfaces.rb

@@ -7,10 +7,24 @@ module Fp
     # fp surfaces --project <slug>              - list available surfaces for a project
     # fp surfaces show <key> --project <slug>   - view a single surface's details
     # fp surfaces add <key> --project <slug>    - create a surface
+    # fp surfaces edit <key> --project <slug>   - change an existing surface
+    # fp surfaces delete <key> --project <slug> - delete a surface, with confirmation
     #
     # `add` exists because a requirement can only name surfaces that already exist, so an
     # agent onboarding a project it hasn't seen before would otherwise be blocked waiting
     # on a human to click through the web app.
+    #
+    # `edit` and `delete` exist because `add` on an existing key used to make a second
+    # surface with the same key, and there was no way to fix that short of a raw API call
+    # (Fizzy #1480). The server now refuses a duplicate key with a 409; `add` turns that
+    # into a pointer at `edit`. `delete` is guarded like `fp projects delete`.
+    #
+    # `edit` also keeps the surface's client-showroom card (Fizzy #1479): the link a
+    # client opens, the button text, and how to sign in and try it. The agent that
+    # deployed the surface and made the demo accounts is the one that knows these, so
+    # it fills them in rather than leaving a human to retype them. Pass an empty value
+    # to clear a field; a surface with neither a link nor instructions leaves the
+    # showroom. Feedback and the share link stay with humans (`fp showroom` explains).
     class Surfaces < Base
       ADD_FLAGS = {
         project: :string,
@@ -21,9 +35,45 @@ module Fp
         default_branch: :string
       }.freeze
 
+      SHOWROOM_FLAGS = {
+        showroom_url: :string,
+        showroom_label: :string,
+        showroom_instructions: :string,
+        showroom_instructions_file: :string
+      }.freeze
+
+      EDIT_FLAGS = ADD_FLAGS.merge(key: :string).merge(SHOWROOM_FLAGS).freeze
+
+      DELETE_FLAGS = {
+        project: :string,
+        yes: :boolean
+      }.freeze
+
       VALID_KINDS = %w[api web android ios other].freeze
       VALID_AUDIENCES = %w[customer ops both internal].freeze
 
+      help_summary 'List, view, create, edit, and delete a project\'s surfaces'
+      help_usage 'fp surfaces --project <slug>',
+                 'fp surfaces show <key> --project <slug>',
+                 'fp surfaces add <key> --project <slug> [--name ...] [--kind K] [--repo org/repo]',
+                 'fp surfaces edit <key> --project <slug> [flags]',
+                 'fp surfaces delete <key> --project <slug> [--yes]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :name, 'Human-readable surface name'
+      help_flag :kind, "Surface kind: #{VALID_KINDS.join(', ')}"
+      help_flag :audience, "Audience: #{VALID_AUDIENCES.join(', ')}"
+      help_flag :repo, 'Repository the surface maps to (org/repo)'
+      help_flag :default_branch, 'Default branch for the repo'
+      help_flag :showroom_url, 'Client showroom card: the http(s) link a client opens (edit; empty clears)'
+      help_flag :showroom_label, 'Client showroom card: the button text for that link (edit)'
+      help_flag :showroom_instructions, 'Client showroom card: how to sign in and try the surface (edit)'
+      help_flag :showroom_instructions_file, 'Read --showroom-instructions from a file (multi-line)'
+      help_flag :yes, 'Skip the typed-key confirmation on delete'
+      help_example 'fp surfaces --project stowzilla'
+      help_example 'fp surfaces add customer_android --project stowzilla --kind android --repo stowzilla/customer-android'
+      help_example 'fp surfaces delete web --project stowzilla --yes'
+      help_example 'fp surfaces edit web --project stowzilla --showroom-url https://dev.example.com --showroom-instructions-file docs/showroom/web.txt'
+
       def run(args)
         # Subcommand dispatch. Bare `fp surfaces --project X` stays a list, so existing
         # callers (and the docs) keep working.
@@ -32,6 +82,10 @@ module Fp
           add(args[1..])
         when 'show'
           show(args[1..])
+        when 'edit'
+          edit(args[1..])
+        when 'delete'
+          delete(args[1..])
         else
           list(args)
         end
@@ -116,6 +170,15 @@ module Fp
 
         result = client.create_surface(project_id, params)
 
+        if !result[:ok] && result[:status] == 409
+          output.error(
+            "Surface '#{key}' already exists in project '#{opts[:project]}'. " \
+            "Change it with: fp surfaces edit #{key} --project #{opts[:project]} [--name ...] [--kind ...] [--repo ...]",
+            status: 409
+          )
+          exit 1
+        end
+
         unless result[:ok]
           output.error(result[:error], status: result[:status])
           exit 1
@@ -133,6 +196,176 @@ module Fp
         end
       end
 
+      def edit(args)
+        opts, positional = parse_flags(args, EDIT_FLAGS)
+        require_project!(opts)
+
+        key = positional.first
+        if key.nil? || key.strip.empty?
+          output.error('Usage: fp surfaces edit <key> --project <slug> [--name "Name"] [--kind ...] ' \
+                       '[--audience ...] [--repo org/repo] [--default-branch main] [--key new_key] ' \
+                       '[--showroom-url URL] [--showroom-label "..."] ' \
+                       '[--showroom-instructions "..." | --showroom-instructions-file PATH]')
+          exit 1
+        end
+
+        validate_choice!(opts[:kind], VALID_KINDS, '--kind')
+        validate_choice!(opts[:audience], VALID_AUDIENCES, '--audience')
+
+        # Only what was passed is sent, so an edit never blanks a field it wasn't asked about.
+        params = {}
+        %i[key name kind audience repo default_branch].each do |field|
+          params[field] = opts[field] if opts.key?(field)
+        end
+        params.merge!(showroom_params(opts))
+
+        if params.empty?
+          output.error('Nothing to change. Pass --name, --kind, --audience, --repo, --default-branch, --key, ' \
+                       'or a --showroom-* flag.')
+          exit 1
+        end
+
+        project_id = resolve_project_id(opts[:project])
+        surface = find_surface!(project_id, key)
+
+        result = client.update_surface(project_id, surface['id'], params)
+
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        # The update action answers with update!'s return value, not the record, so read
+        # the surface back rather than trusting the response body.
+        updated = client.get_surface(project_id, surface['id'])
+        record = (updated[:ok] && updated[:data]['surface']) || surface.merge(params.transform_keys(&:to_s))
+
+        output.success({ surface: record, project: opts[:project] }) do
+          puts "Updated surface '#{record['key']}' in project '#{opts[:project]}'."
+          puts
+          puts "  Name:     #{record['name']}"
+          puts "  Kind:     #{record['kind']}"
+          puts "  Audience: #{record['audience']}"
+          puts "  Repo:     #{record['repo'] || '(none)'}"
+          puts "  Branch:   #{record['default_branch'] || '(none)'}"
+          print_showroom(record, indent: '  ') if params.keys.any? { |field| field.to_s.start_with?('showroom_') }
+        end
+      end
+
+      # The showroom fields from --showroom-* flags, as the API expects them. A string
+      # flag given as empty clears the field. The URL is checked here with the same rule
+      # the server applies (http/https only) so a typo fails before anything is sent.
+      def showroom_params(opts)
+        if opts.key?(:showroom_instructions) && opts.key?(:showroom_instructions_file)
+          output.error('Pass --showroom-instructions or --showroom-instructions-file, not both.')
+          exit 1
+        end
+
+        params = {}
+        %i[showroom_url showroom_label showroom_instructions].each do |field|
+          params[field] = flag_text(opts[field]) if opts.key?(field)
+        end
+
+        if opts.key?(:showroom_instructions_file)
+          params[:showroom_instructions] = read_text_file!(opts[:showroom_instructions_file],
+                                                           '--showroom-instructions-file')
+        end
+
+        url = params[:showroom_url]
+        if url && !url.empty? && url !~ %r{\Ahttps?://\S+\z}i
+          output.error("Invalid --showroom-url '#{url}'. Must be an http:// or https:// link; " \
+                       'pass an empty value to clear it.')
+          exit 1
+        end
+
+        params
+      end
+
+      # A string flag given with no value parses as `true`; treat that as "clear it",
+      # the same as an explicit empty string.
+      def flag_text(value)
+        value == true ? '' : value.to_s
+      end
+
+      def read_text_file!(path, flag)
+        if path.nil? || path == true || path.to_s.strip.empty?
+          output.error("#{flag} needs a path")
+          exit 1
+        end
+        unless File.file?(path)
+          output.error("#{flag}: no such file '#{path}'")
+          exit 1
+        end
+        File.read(path).strip
+      end
+
+      def delete(args)
+        opts, positional = parse_flags(args, DELETE_FLAGS)
+        require_project!(opts)
+
+        key = positional.first
+        if key.nil? || key.strip.empty?
+          output.error('Usage: fp surfaces delete <key> --project <slug> [--yes]')
+          exit 1
+        end
+
+        project_id = resolve_project_id(opts[:project])
+        surface = find_surface!(project_id, key)
+        confirm_delete!(surface, opts)
+
+        result = client.delete_surface(project_id, surface['id'])
+
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        output.success({ deleted: true, surface: { 'id' => surface['id'], 'key' => surface['key'] },
+                         project: opts[:project] }) do
+          puts "Deleted surface '#{surface['key']}' from project '#{opts[:project]}'."
+        end
+      end
+
+      # Same guard as `fp projects delete`: --yes skips the prompt, an interactive
+      # terminal types the key back, and anything else is refused.
+      def confirm_delete!(surface, opts)
+        return if opts[:yes]
+
+        unless interactive?
+          output.error(
+            "Refusing to delete surface '#{surface['key']}' without confirmation. " \
+            'Re-run with --yes to confirm from a non-interactive session.'
+          )
+          exit 1
+        end
+
+        warn "This will delete surface '#{surface['key']}' (#{surface['name']}) from project '#{opts[:project]}'."
+        warn 'Evidence filed against it stays behind with nothing to measure.'
+        $stderr.print "Type '#{surface['key']}' to confirm: "
+        $stderr.flush
+
+        typed = $stdin.gets&.strip
+        return if typed == surface['key']
+
+        output.error('Aborted. The key did not match; nothing was deleted.')
+        exit 1
+      end
+
+      def interactive?
+        $stdin.respond_to?(:tty?) && $stdin.tty?
+      end
+
+      def find_surface!(project_id, key)
+        result = client.find_surface_by_key(project_id, key)
+
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        result[:data]['surface']
+      end
+
       def validate_choice!(value, allowed, flag)
         return if value.nil? || allowed.include?(value)
 
@@ -166,12 +399,37 @@ module Fp
           globs.each { |g| puts "  - #{g}" }
         end
 
+        puts
+        print_showroom(surface, indent: '')
+
         puts
         puts "ID:       #{surface['id']}" if surface['id']
         puts "Created:  #{surface['created_at']}" if surface['created_at']
         puts "Updated:  #{surface['updated_at']}" if surface['updated_at']
       end
 
+      # The surface's client-showroom card. Says plainly whether a client can see the
+      # surface, since that is decided by the content (a link or instructions), not a
+      # switch, and an agent that just wrote instructions should know they went live.
+      def print_showroom(surface, indent:)
+        url = text_or_nil(surface['showroom_url'])
+        label = text_or_nil(surface['showroom_label'])
+        instructions = text_or_nil(surface['showroom_instructions'])
+        shown = !(url.nil? && instructions.nil?)
+
+        puts "#{indent}Showroom: #{shown ? 'shown to clients' : 'hidden (no link or instructions)'}"
+        return unless shown
+
+        puts "#{indent}  Link:         #{url || '(none)'}#{label ? " [#{label}]" : ''}"
+        puts "#{indent}  Instructions: #{instructions ? '' : '(none)'}"
+        instructions&.each_line { |line| puts "#{indent}    #{line.rstrip}" }
+      end
+
+      def text_or_nil(value)
+        text = value.to_s.strip
+        text.empty? ? nil : text
+      end
+
       # test_globs may arrive as a JSON string or an array; normalize to an array for
       # display. Blank/unparseable → empty (the server falls back to kind defaults).
       def normalize_test_globs(value)

data/lib/fp/commands/version.rb

@@ -4,6 +4,9 @@ module Fp
   module Commands
     # fp version
     class Version < Base
+      help_summary 'Show the installed fp version'
+      help_usage 'fp version'
+
       def run(_args)
         output.success({ version: Fp::VERSION }) do
           puts "fp #{Fp::VERSION}"

data/lib/fp/commands/whoami.rb

@@ -10,6 +10,12 @@ module Fp
     # (masked — never the full token). Purely local; makes no API calls, so it
     # works even without a valid key. Honors --profile / --api-url / --json.
     class Whoami < Base
+      help_summary 'Show the resolved config (profile, API URL, environment, masked key)'
+      help_usage 'fp whoami [--json]'
+      help_example 'fp whoami'
+      help_example 'fp --profile staging whoami'
+      help_note 'Purely local; makes no API calls, so it works even without a valid key.'
+
       def run(_args)
         r = config.resolved
 

data/lib/fp/commands.rb

@@ -3,6 +3,7 @@
 require_relative 'commands/base'
 require_relative 'commands/projects'
 require_relative 'commands/surfaces'
+require_relative 'commands/showroom'
 require_relative 'commands/list'
 require_relative 'commands/show'
 require_relative 'commands/propose'

data/lib/fp/junit.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'rexml/document'
+require 'pathname'
 require_relative 'source_fingerprint'
 
 module Fp
@@ -18,7 +19,8 @@ module Fp
     # is the runner's own verdict, which only CI is allowed to act on (`fp ci-report`).
     # Both are kept because they answer different questions: a red test still proves the
     # test exists (present), it just doesn't prove the requirement is met.
-    TestCase = Struct.new(:name, :classname, :file, :line, :status, :failed, keyword_init: true) do
+    TestCase = Struct.new(:name, :classname, :file, :line, :status, :failed, :attachments,
+                          keyword_init: true) do
       # Agents only ever report present/stub — never passing/failing (that's CI).
       # A skipped test is treated as a stub; anything else counts as present.
       def stub?
@@ -28,6 +30,12 @@ module Fp
       def failed?
         !!failed
       end
+
+      # Media (videos, screenshots, traces) the runner recorded for this test — e.g.
+      # Playwright's `[[ATTACHMENT|path]]` lines. Always an array.
+      def attachments
+        self[:attachments] || []
+      end
     end
 
     # One requirement's aggregated CI outcome for one surface, ready to hand to the
@@ -77,6 +85,12 @@ module Fp
     # 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)
 
+    # 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,
+    # these are per-testcase, not aggregated: a run can record a distinct video for every
+    # test, and `example_title` is what nests each capture under the receipt it proves.
+    MediaBinding = Struct.new(:slug, :surface, :path, :example_title, keyword_init: true)
+
     # Matches `fp:<slug>` inside a comment, with an optional `@surface` (or
     # `@surface1,surface2`) suffix to target one or more specific surfaces, and an
     # optional `:<type>` suffix to pin the kind of test:
@@ -132,13 +146,30 @@ module Fp
           file: resolve_file(el.attributes['file'], classname, suite_name),
           line: (el.attributes['line'] && el.attributes['line'].to_i),
           status: testcase_status(el),
-          failed: testcase_failed?(el)
+          failed: testcase_failed?(el),
+          attachments: extract_attachments(el)
         )
       end
 
       cases
     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
+    # bound requirement, instead of a hand-matched `fp attach` per file.
+    #
+    # The path is relative to wherever Playwright ran; it's resolved against --base-dir at
+    # upload time, the same way test-file paths are.
+    ATTACHMENT_RE = /\[\[ATTACHMENT\|([^\]]+)\]\]/.freeze
+
+    def extract_attachments(el)
+      text = el.get_elements('system-out').map(&:text).compact.join("\n")
+      return [] if text.empty?
+
+      text.scan(ATTACHMENT_RE).map { |(path)| path.strip }.reject(&:empty?).uniq
+    end
+
     # Runners disagree about where the source file goes. Minitest- and RSpec-style reports
     # put it on the testcase's `file` attribute; vitest and jest omit `file` entirely and
     # carry the path in `classname` and the enclosing `<testsuite name>`. Markers live in
@@ -200,11 +231,20 @@ module Fp
     #     bindings: [Binding, ...],       # unique (slug, surface, file) evidence
     #     unmatched: [TestCase, ...],     # testcases with no discoverable marker
     #     missing_surface: [Binding-ish], # markers with no surface and no default
+    #     media: [MediaBinding, ...],     # attachments on bound testcases, per surface
+    #     empty_name: [{slug:, surface:, file:}], # bound testcases with a blank name
+    #     collisions: [{slug:,surface:,   # cells >1 distinct file fed — they overwrite
+    #       test_type:,files:}],          #   each other server-side (see detect_collisions)
     #   }
     def bind_markers(testcases, base_dir: Dir.pwd, default_surface: nil, default_test_type: nil)
       bindings = {}
       matched = {}
       missing_surface = []
+      media = []
+      empty_name = []
+      # Track which source files feed each evidence cell so we can spot the silent
+      # overwrite below (see detect_collisions).
+      cell_files = Hash.new { |h, k| h[k] = [] }
 
       walk_matches(testcases, base_dir) do |match|
         tc = match.testcase
@@ -222,15 +262,52 @@ module Fp
           if surface.nil? || surface.empty?
             missing_surface << { slug: marker[:slug], file: tc.file }
           else
+            cell_files[[marker[:slug], surface, test_type]] << match.repo_file
             record_binding(bindings, marker[:slug], surface, tc, marker,
                            titles_reliable: match.precise, file: match.repo_file,
                            test_type: test_type)
+
+            # A bound testcase with no name produces a receipt with no title, which is
+            # almost always an upstream reporter problem — flag it rather than filing a
+            # nameless receipt silently.
+            empty_name << { slug: marker[:slug], surface: surface, file: match.repo_file } if presence(tc.name).nil?
+
+            # Media the run recorded for this exact test, tied to its example title so
+            # each capture nests under the receipt it proves.
+            tc.attachments.each do |path|
+              media << MediaBinding.new(slug: marker[:slug], surface: surface, path: path,
+                                        example_title: (presence(tc.name) if match.precise))
+            end
           end
         end
       end
 
       unmatched = testcases.reject { |tc| matched[tc.object_id] }
-      { bindings: bindings.values, unmatched: unmatched, missing_surface: missing_surface.uniq }
+      { bindings: bindings.values, unmatched: unmatched, missing_surface: missing_surface.uniq,
+        media: media, empty_name: empty_name.uniq,
+        collisions: detect_collisions(cell_files) }
+    end
+
+    # Find evidence cells that more than one *distinct source file* resolved to in a
+    # single run. Server-side, evidence identity is (project, slug, surface, repo,
+    # test_type) — the file is deliberately not part of it, so one requirement cell is
+    # one row. That means two different test files (an RSpec unit suite and a Playwright
+    # e2e suite, say) that bind to the same slug+surface and share a test_type both upsert
+    # the *same* row: the second POST silently overwrites the first, and only one suite's
+    # evidence survives. This is almost always the `unspecified` default colliding —
+    # neither suite pinned a `:type` marker nor passed `--test-type`.
+    #
+    # Returns [{ slug:, surface:, test_type:, files: [sorted unique repo paths] }, ...]
+    # for every cell fed by two or more distinct files, so the caller can warn instead of
+    # overwriting in silence. A single file feeding a cell is the normal case and is not
+    # reported.
+    def detect_collisions(cell_files)
+      cell_files.filter_map do |(slug, surface, test_type), files|
+        distinct = files.compact.uniq
+        next if distinct.length < 2
+
+        { slug: slug, surface: surface, test_type: test_type, files: distinct.sort }
+      end
     end
 
     # Aggregate a run's results per (slug, surface) into the pass/fail verdict CI files.
@@ -346,14 +423,29 @@ module Fp
     # can never disagree about which test a marker annotates.
     def walk_matches(testcases, base_dir)
       marker_cache = {}
+      resolve_cache = {}
       root = repo_root_for(base_dir)
 
       # Group testcases by their source file so we can reason about ordering.
       testcases.group_by(&:file).each do |file, cases|
-        markers = markers_for(cases.first, base_dir, marker_cache)
+        # The report's path may not exist under base_dir (Playwright's classname is
+        # relative to its testDir, not the repo or cwd). Find the real file first; its
+        # resolved location is what we read markers from and what we report.
+        source_path = resolve_source_path(file, base_dir, resolve_cache)
+        markers = markers_for(source_path, marker_cache)
         next if markers.empty?
 
-        repo_file = repo_relative_path(file, base_dir, root)
+        # Report the file relative to the repo root. When the file was found exactly where
+        # the report said (the common case), keep the reported path verbatim — outside a
+        # git checkout that's all we have, and expanding it would change long-standing
+        # output. Only when the search *relocated* the file (Playwright's testDir case) do
+        # we report from its real location instead of the path that didn't exist.
+        repo_file =
+          if source_path && source_path != File.expand_path(file.to_s, base_dir)
+            repo_relative_path(source_path, base_dir, root)
+          else
+            repo_relative_path(file, base_dir, root)
+          end
 
         cases.each do |tc|
           marker, precise = marker_for(tc, cases, markers)
@@ -361,7 +453,7 @@ module Fp
 
           yield Match.new(
             testcase: tc, marker: marker, precise: precise, repo_file: repo_file,
-            source_path: File.expand_path(file, base_dir)
+            source_path: source_path || File.expand_path(file.to_s, base_dir)
           )
         end
       end
@@ -466,8 +558,11 @@ module Fp
       markers.max_by { |m| [m[:title].length, m[:line]] }
     end
 
-    # vitest/jest join describe names and the test name with " > ".
-    NAME_SEPARATOR = / > /.freeze
+    # How runners join an enclosing group's name to the test's. vitest/jest use " > ",
+    # Playwright uses " › " (U+203A), and pytest-style ids use "::"
+    # (file.py::TestClass::test_name, no surrounding spaces). Matching all three lets a
+    # marker bind by title regardless of which runner produced the report.
+    NAME_SEPARATOR = /\s+>\s+|\s+›\s+|::/.freeze
 
     def title_matches_test?(title, name, segments)
       return false if title.nil? || title.empty?
@@ -513,23 +608,123 @@ module Fp
                                   line: line, title: (testcase.name if titles_reliable), state: state)
     end
 
-    # Load and cache the fp:<slug> markers (with line numbers) for a testcase's
-    # source file. Returns [] when the file is unknown or unreadable.
-    def markers_for(testcase, base_dir, cache)
-      file = testcase.file
-      return [] if file.nil? || file.empty?
+    # Load and cache the fp:<slug> markers (with line numbers) for an already-resolved
+    # absolute source path. Returns [] when the path is nil or unreadable.
+    def markers_for(source_path, cache)
+      return [] if source_path.nil? || source_path.empty?
 
-      return cache[file] if cache.key?(file)
+      return cache[source_path] if cache.key?(source_path)
 
-      resolved = File.expand_path(file, base_dir)
       markers =
-        if File.file?(resolved)
-          scan_markers(File.read(resolved))
+        if File.file?(source_path)
+          scan_markers(File.read(source_path))
         else
           []
         end
 
-      cache[file] = markers
+      cache[source_path] = markers
+    end
+
+    # Common directories a test file lives under when the reported path is relative to a
+    # runner's testDir rather than the repo/cwd. Tried in order after base_dir itself.
+    COMMON_TEST_DIRS = %w[e2e tests test spec specs integration].freeze
+
+    # How many directory levels deep the last-resort **/<name> glob will search, so an
+    # unresolved path doesn't walk a whole monorepo.
+    GLOB_SEARCH_DEPTH = 6
+
+    # Resolve a report's test-file path to an absolute path that actually exists, so
+    # markers can be read from it. Returns nil when nothing matches.
+    #
+    # Playwright's JUnit reporter writes `classname="loyalty.spec.js"` — relative to its
+    # `testDir` (e.g. `frontend/e2e/`), not the repo root or the directory the runner was
+    # invoked from. So `<base-dir>/loyalty.spec.js` doesn't exist and every testcase ends
+    # up "had no fp: marker". Rather than make the user hand-annotate the XML, search:
+    #
+    #   1. base_dir itself (the path as reported) — the common, unambiguous case;
+    #   2. Playwright's testDir, read from a playwright.config.* under base_dir;
+    #   3. the usual test directories (e2e/, tests/, test/, spec/, ...);
+    #   4. a bounded **/<basename> glob, accepted only when it matches exactly one file.
+    #
+    # Prints which strategy found the file (unless silent) so a surprising resolution is
+    # visible rather than magic. Results are cached per reported path.
+    def resolve_source_path(file, base_dir, cache = {}, silent: false)
+      return nil if file.nil? || file.empty?
+      return cache[file] if cache.key?(file)
+
+      cache[file] = compute_source_path(file, base_dir, silent: silent)
+    end
+
+    def compute_source_path(file, base_dir, silent: false)
+      direct = File.expand_path(file, base_dir)
+      return direct if File.file?(direct)
+
+      candidates = source_path_candidates(file, base_dir)
+      found = candidates.find { |path| File.file?(path) }
+      if found
+        report_resolution(file, found, base_dir) unless silent
+        return found
+      end
+
+      globbed = glob_for_source(file, base_dir)
+      if globbed
+        report_resolution(file, globbed, base_dir) unless silent
+        return globbed
+      end
+
+      nil
+    end
+
+    # Ordered, non-glob candidate locations for a reported path: Playwright's testDir
+    # first (the authoritative answer when a config declares one), then the common test
+    # directories. Each is tried both with the full reported path and with just its
+    # basename, since Playwright reports a bare filename.
+    def source_path_candidates(file, base_dir)
+      basename = File.basename(file)
+      dirs = [playwright_test_dir(base_dir), *COMMON_TEST_DIRS].compact.uniq
+
+      dirs.flat_map do |dir|
+        base = File.expand_path(dir, base_dir)
+        [File.expand_path(file, base), File.join(base, basename)]
+      end.uniq
+    end
+
+    # The last resort: a bounded glob for the basename anywhere under base_dir. Only
+    # accepted when it resolves to exactly one file — an ambiguous match is no better
+    # than no match, and silently picking one would bind a marker from the wrong file.
+    def glob_for_source(file, base_dir)
+      basename = File.basename(file)
+      return nil if basename.empty?
+
+      pattern_dirs = (1..GLOB_SEARCH_DEPTH).map { |d| File.join(base_dir, *Array.new(d, '*')) }
+      matches = Dir.glob([File.join(base_dir, basename), *pattern_dirs.map { |p| "#{p}/#{basename}" }])
+                   .select { |p| File.file?(p) }.uniq
+      matches.length == 1 ? File.expand_path(matches.first) : nil
+    end
+
+    # Read Playwright's `testDir` from a playwright.config.{js,ts,mjs,cjs} under base_dir.
+    # The config is JS/TS, not something we can evaluate, so pull the string literal with
+    # a conservative regex. Returns nil when there's no config or no testDir in it.
+    def playwright_test_dir(base_dir)
+      config = Dir.glob(File.join(base_dir, 'playwright.config.{js,ts,mjs,cjs}')).first
+      return nil unless config && File.file?(config)
+
+      contents = File.read(config)
+      match = contents.match(/testDir\s*:\s*(['"`])(.+?)\1/)
+      match && match[2]
+    rescue StandardError
+      nil
+    end
+
+    # Tell the user which strategy resolved a path that wasn't where the report said,
+    # so a surprising resolution is visible. Printed to stderr to stay out of --json.
+    def report_resolution(reported, found, base_dir)
+      rel = begin
+        Pathname.new(found).relative_path_from(Pathname.new(File.expand_path(base_dir))).to_s
+      rescue StandardError
+        found
+      end
+      warn "fp: resolved test file '#{reported}' to '#{rel}' (not found at the reported path)"
     end
 
     # Scan file contents for fp:<slug>[@surface[,surface...]][:type] markers, returning