featureparity 0.0.2 → 0.0.4

data/lib/fp/config.rb

@@ -2,6 +2,7 @@
 
 require 'yaml'
 require 'fileutils'
+require 'uri'
 
 module Fp
   # Handles configuration: profiles, API keys, API URL.
@@ -15,17 +16,26 @@ module Fp
   #
   # API key resolution priority:
   #   1. FP_API_KEY env var
-  #   2. Profile api_key (--profile flag > FP_PROFILE env var)
+  #   2. Profile api_key (--profile flag > FP_PROFILE env var > "default" profile)
+  #
+  # Profile name resolution priority:
+  #   1. --profile CLI flag
+  #   2. FP_PROFILE env var
+  #   3. A profile literally named "default" (if one exists in config.yml)
   class Config
     DEFAULT_API_URL = 'https://api.featureparity.dev'
+    DEFAULT_PROFILE_NAME = 'default'
     CONFIG_DIR = File.expand_path('~/.config/fp')
     CONFIG_FILE = File.join(CONFIG_DIR, 'config.yml')
 
     attr_reader :api_key, :api_url, :profile_name
 
+    # Where a resolved value came from, for `fp whoami` transparency.
+    attr_reader :api_key_source, :api_url_source, :profile_source
+
     def initialize(profile: nil, api_url: nil)
-      @profile_name = resolve_profile_name(profile)
       @explicit_api_url = api_url
+      @profile_name = resolve_profile_name(profile)
       @api_key = resolve_api_key
       @api_url = resolve_api_url
     end
@@ -34,6 +44,56 @@ module Fp
       !@api_key.nil? && !@api_key.empty?
     end
 
+    # The API URL passed via the global --api-url flag, if any (nil otherwise).
+    # `profile add` / `setup` use this so `fp profile add x --api-url URL` still
+    # records URL even though the global parser consumes the flag first.
+    def explicit_api_url
+      return nil if @explicit_api_url.nil? || @explicit_api_url.empty?
+
+      @explicit_api_url
+    end
+
+    # Short, human-readable environment label derived from the API host, e.g.
+    #   https://api.dev.featureparity.dev      -> "dev"
+    #   https://api.staging.featureparity.dev  -> "staging"
+    #   https://api.featureparity.dev          -> "production"
+    #   http://localhost:9292                  -> "local"
+    # This is what "tags" a profile/key to an environment: the API URL it targets.
+    def environment
+      self.class.environment_for(@api_url)
+    end
+
+    # The environment explicitly recorded on the active profile, if any.
+    # Falls back to nil when unset (callers derive from api_url instead).
+    def profile_environment
+      return nil unless @profile_name
+
+      profile = self.class.load_profiles[@profile_name]
+      profile && profile['environment']
+    end
+
+    # Masked hint for display — never reveal the full key.
+    def masked_api_key
+      self.class.mask_key(@api_key)
+    end
+
+    # Full resolved snapshot for `fp whoami` (safe to print / JSON-encode).
+    def resolved
+      {
+        profile: @profile_name,
+        profile_source: @profile_source,
+        api_url: @api_url,
+        api_url_source: @api_url_source,
+        environment: environment,
+        profile_environment: profile_environment,
+        authenticated: valid?,
+        api_key_present: valid?,
+        api_key_hint: masked_api_key,
+        api_key_source: @api_key_source,
+        config_file: self.class::CONFIG_FILE
+      }
+    end
+
     def validation_error
       return nil if valid?
 
@@ -58,7 +118,7 @@ module Fp
         config['profiles'] || {}
       end
 
-      def save_profile(name, api_key:, api_url: nil)
+      def save_profile(name, api_key:, api_url: nil, environment: nil)
         FileUtils.mkdir_p(CONFIG_DIR)
         ensure_config_file!
 
@@ -66,6 +126,10 @@ module Fp
         config['profiles'] ||= {}
         config['profiles'][name] = { 'api_key' => api_key }
         config['profiles'][name]['api_url'] = api_url if api_url
+        # Tag the key/profile with the environment it targets. If not given
+        # explicitly, derive it from the api_url so keys are always tagged.
+        env = environment || environment_for(api_url || get_setting('api_url') || DEFAULT_API_URL)
+        config['profiles'][name]['environment'] = env if env
 
         write_config!(config)
       end
@@ -76,6 +140,67 @@ module Fp
         config[key.to_s]
       end
 
+      # Derive a short environment label from an API URL's host. This mirrors
+      # the Belt DNS convention (see infrastructure/modules/app/dns.tf), which is
+      # what actually "tags" a profile/key to an environment: the API host tells
+      # you which FeatureParity environment the key talks to.
+      #
+      # Standalone environments use a dotted "api." prefix:
+      #   api.featureparity.dev          -> "production"
+      #   api.dev.featureparity.dev      -> "dev"
+      #   api.staging.featureparity.dev  -> "staging"
+      #
+      # Nested / ephemeral (per-branch) environments use a dashed "api-" prefix,
+      # because SSL wildcards are single-level (*.dev.featureparity.dev covers
+      # api-<env>.dev.featureparity.dev but not api.<env>.dev.featureparity.dev).
+      # The env slug is everything after "api-" up to the first dot, and may
+      # itself contain dashes:
+      #   api-abc-1234.dev.featureparity.dev  -> "abc-1234"
+      #   api-fizzy123.dev.featureparity.dev  -> "fizzy123"
+      #
+      # Anything local:
+      #   localhost / 127.0.0.1 / 0.0.0.0     -> "local"
+      def environment_for(url)
+        return nil if url.nil? || url.to_s.empty?
+
+        host = begin
+          URI.parse(url.to_s).host
+        rescue URI::InvalidURIError
+          nil
+        end
+        return nil if host.nil? || host.empty?
+
+        return 'local' if host == 'localhost' || host.start_with?('127.') || host == '0.0.0.0'
+
+        first, *rest = host.split('.')
+
+        # Nested/ephemeral: "api-<env>" where <env> may contain dashes.
+        return first.sub(/\Aapi-/, '') if first.start_with?('api-')
+
+        # Standalone dotted "api." prefix: the env is the next label.
+        if first == 'api'
+          # api.featureparity.dev -> ["featureparity", "dev"] -> production
+          return 'production' if rest.length <= 2
+
+          return rest.first
+        end
+
+        # No recognizable "api" prefix — best effort: treat a bare apex
+        # (two labels, e.g. featureparity.dev) as production, else the left label.
+        return 'production' if rest.length <= 1
+
+        first
+      end
+
+      # Mask an API key for display: keep a short prefix + last 4 chars.
+      #   fp_abcdefgh1234 -> fp_…1234
+      def mask_key(key)
+        return nil if key.nil? || key.empty?
+        return '****' if key.length <= 8
+
+        "#{key[0, 3]}…#{key[-4..]}"
+      end
+
       # Set a global setting (top-level key in config.yml)
       def set_setting(key, value)
         FileUtils.mkdir_p(CONFIG_DIR)
@@ -99,6 +224,72 @@ module Fp
         load_profiles.key?(name)
       end
 
+      # --- Repo → surface mappings (per-machine, local) ---
+      #
+      # Stored under a top-level `repos` key in config.yml, scoped by project slug:
+      #
+      #   repos:
+      #     stowzilla:
+      #       customer_android:
+      #         path: /home/dev/code/customer-android
+      #         repo: stowzilla/customer-android
+      #
+      # This is intentionally local (per fp installation) — it maps FeatureParity
+      # surfaces to wherever the code lives on THIS machine, so an agent working a
+      # requirement for a given surface knows which directory to open. Analogous to
+      # how `brainiac projects` maps repos to project names.
+
+      # Return the full repos mapping ({ project => { surface => {path, repo} } }).
+      def repos_map
+        config = load_config
+        config['repos'] || {}
+      end
+
+      # Return the surface => {path, repo} mapping for a single project.
+      def repos_for_project(project)
+        repos_map[project.to_s] || {}
+      end
+
+      # Look up the mapping for a single surface within a project.
+      # Returns a hash like { 'path' => ..., 'repo' => ... } or nil if unmapped.
+      def repo_for_surface(project, surface)
+        repos_for_project(project)[surface.to_s]
+      end
+
+      # Map a surface (within a project) to a local path and optional org/repo.
+      def set_repo(project, surface, path:, repo: nil)
+        FileUtils.mkdir_p(CONFIG_DIR)
+        ensure_config_file!
+
+        config = load_config
+        config['repos'] ||= {}
+        config['repos'][project.to_s] ||= {}
+
+        entry = { 'path' => path }
+        entry['repo'] = repo if repo && !repo.to_s.empty?
+        config['repos'][project.to_s][surface.to_s] = entry
+
+        write_config!(config)
+        entry
+      end
+
+      # Remove a surface mapping within a project. Prunes empty project hashes.
+      # Returns true if something was removed, false otherwise.
+      def unset_repo(project, surface)
+        config = load_config
+        return false unless config['repos'].is_a?(Hash)
+
+        project_map = config['repos'][project.to_s]
+        return false unless project_map.is_a?(Hash) && project_map.key?(surface.to_s)
+
+        project_map.delete(surface.to_s)
+        config['repos'].delete(project.to_s) if project_map.empty?
+        config.delete('repos') if config['repos'].empty?
+
+        write_config!(config)
+        true
+      end
+
       private
 
       def ensure_config_file!
@@ -117,42 +308,85 @@ module Fp
     private
 
     def resolve_profile_name(explicit_profile)
-      explicit_profile || ENV['FP_PROFILE']
+      # 1. Explicit --profile flag  2. FP_PROFILE env var
+      if explicit_profile && !explicit_profile.empty?
+        @profile_source = 'flag'
+        return explicit_profile
+      end
+
+      if ENV['FP_PROFILE'] && !ENV['FP_PROFILE'].empty?
+        @profile_source = 'env (FP_PROFILE)'
+        return ENV['FP_PROFILE']
+      end
+
+      # 3. Fall back to a profile literally named "default", if one exists.
+      #    This mirrors AWS/git/gcloud, which all consult a default profile when
+      #    nothing else is specified.
+      if self.class.profile_exists?(DEFAULT_PROFILE_NAME)
+        @profile_source = 'default profile'
+        return DEFAULT_PROFILE_NAME
+      end
+
+      @profile_source = 'none'
+      nil
     end
 
     def resolve_api_key
       # FP_API_KEY env var always wins
-      return ENV['FP_API_KEY'] if ENV['FP_API_KEY'] && !ENV['FP_API_KEY'].empty?
+      if ENV['FP_API_KEY'] && !ENV['FP_API_KEY'].empty?
+        @api_key_source = 'env (FP_API_KEY)'
+        return ENV['FP_API_KEY']
+      end
 
       # Otherwise, use profile if specified
-      return nil unless @profile_name
+      unless @profile_name
+        @api_key_source = 'none'
+        return nil
+      end
 
       profiles = self.class.load_profiles
       profile = profiles[@profile_name]
-      return nil unless profile
+      unless profile
+        @api_key_source = 'none'
+        return nil
+      end
 
+      @api_key_source = "profile (#{@profile_name})"
       profile['api_key']
     end
 
     def resolve_api_url
       # 1. Explicit --api-url flag
-      return @explicit_api_url if @explicit_api_url && !@explicit_api_url.empty?
+      if @explicit_api_url && !@explicit_api_url.empty?
+        @api_url_source = 'flag'
+        return @explicit_api_url
+      end
 
       # 2. FP_API_URL env var
-      return ENV['FP_API_URL'] if ENV['FP_API_URL'] && !ENV['FP_API_URL'].empty?
+      if ENV['FP_API_URL'] && !ENV['FP_API_URL'].empty?
+        @api_url_source = 'env (FP_API_URL)'
+        return ENV['FP_API_URL']
+      end
 
       # 3. Profile-specific URL
       if @profile_name
         profiles = self.class.load_profiles
         profile = profiles[@profile_name]
-        return profile['api_url'] if profile && profile['api_url']
+        if profile && profile['api_url']
+          @api_url_source = "profile (#{@profile_name})"
+          return profile['api_url']
+        end
       end
 
       # 4. Global api_url setting
       global_url = self.class.get_setting('api_url')
-      return global_url if global_url && !global_url.empty?
+      if global_url && !global_url.empty?
+        @api_url_source = 'global setting'
+        return global_url
+      end
 
       # 5. Default
+      @api_url_source = 'default'
       DEFAULT_API_URL
     end
   end

data/lib/fp/junit.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require 'rexml/document'
+
+module Fp
+  # Parses JUnit XML reports and binds testcases to fp:<slug> markers found in
+  # the referenced source files.
+  #
+  # This is what powers "upload evidence without CI": an agent runs the test
+  # suite locally, produces a JUnit XML report, and `fp report --junit` walks
+  # the results, discovers the fp:<slug> markers in the test files, and uploads
+  # evidence for each requirement the suite covered.
+  module JUnit
+    # A single parsed testcase.
+    TestCase = Struct.new(:name, :classname, :file, :line, :status, 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?
+        status == :skipped
+      end
+    end
+
+    # Evidence discovered by binding a testcase to a marker.
+    Binding = Struct.new(:slug, :surface, :file, :title, :state, keyword_init: true)
+
+    # Matches `fp:<slug>` inside a comment, with an optional `@surface` (or
+    # `@surface1,surface2`) suffix to target one or more specific surfaces:
+    #
+    #   fp:print_qr                # uses the --surface flag as the default
+    #   fp:print_qr@api            # reports evidence for the `api` surface
+    #   fp:print_qr@api,web        # reports for both `api` and `web`
+    #
+    # Slugs and surfaces are lowercase letters, digits, underscores and hyphens
+    # (matching the propose/report convention).
+    MARKER_RE = /fp:([a-z0-9][a-z0-9_-]*)(?:@([a-z0-9_-]+(?:,[a-z0-9_-]+)*))?/.freeze
+
+    module_function
+
+    # Parse a JUnit XML file into an array of TestCase structs.
+    # 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)
+    rescue REXML::ParseException => e
+      raise ArgumentError, "Could not parse JUnit XML (#{path}): #{e.message}"
+    end
+
+    def parse_string(xml)
+      doc = REXML::Document.new(xml)
+      cases = []
+
+      doc.each_element('//testcase') do |el|
+        cases << TestCase.new(
+          name: el.attributes['name'],
+          classname: el.attributes['classname'],
+          file: el.attributes['file'],
+          line: (el.attributes['line'] && el.attributes['line'].to_i),
+          status: testcase_status(el)
+        )
+      end
+
+      cases
+    end
+
+    # Determine present/skipped for a testcase element.
+    # Failures/errors still count as "present" for agent evidence — the test
+    # exists and was executed. Only skipped/pending tests become stubs.
+    def testcase_status(el)
+      return :skipped if el.get_elements('skipped').any?
+
+      :present
+    end
+
+    # Bind parsed testcases to fp:<slug> markers found in their source files.
+    #
+    # A marker binds to the test it annotates — the testcase whose line is the
+    # smallest line strictly greater than the marker's line (i.e. the next test
+    # below the marker in the same file). This mirrors the convention that the
+    # `fp:<slug>` comment sits immediately above its test. Tests with no marker
+    # directly above them are left unmatched rather than being bound to an
+    # unrelated marker.
+    #
+    # When testcases carry no line information, a file with exactly one marker
+    # binds that marker to every testcase in the file (common for small,
+    # single-requirement test files); files with multiple markers and no line
+    # info can't be disambiguated and are reported as unmatched.
+    #
+    # A marker may pin one or more surfaces via `@surface` / `@a,b` (e.g. a
+    # backend test that satisfies several surfaces). Each surface yields its own
+    # binding. Markers without a surface fall back to `default_surface`.
+    #
+    # base_dir: directory to resolve relative testcase file paths against.
+    # default_surface: surface applied to markers that don't pin their own.
+    #
+    # Returns a hash:
+    #   {
+    #     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
+    #   }
+    def bind_markers(testcases, base_dir: Dir.pwd, default_surface: nil)
+      marker_cache = {}
+      bindings = {}
+      matched = {}
+      missing_surface = []
+
+      # Group testcases by their source file so we can reason about ordering.
+      by_file = testcases.group_by(&:file)
+
+      by_file.each do |file, cases|
+        markers = markers_for(cases.first, base_dir, marker_cache)
+        next if markers.empty?
+
+        cases.each do |tc|
+          marker = marker_for(tc, cases, markers)
+          next unless marker
+
+          matched[tc.object_id] = true
+
+          surfaces = marker[:surfaces]
+          surfaces = [default_surface] if surfaces.empty?
+
+          surfaces.each do |surface|
+            if surface.nil? || surface.empty?
+              missing_surface << { slug: marker[:slug], file: tc.file }
+            else
+              record_binding(bindings, marker[:slug], surface, tc)
+            end
+          end
+        end
+      end
+
+      unmatched = testcases.reject { |tc| matched[tc.object_id] }
+      { bindings: bindings.values, unmatched: unmatched, missing_surface: missing_surface.uniq }
+    end
+
+    # Determine the marker (slug + surfaces) that annotates a testcase, or nil.
+    def marker_for(testcase, sibling_cases, markers)
+      if testcase.line
+        marker_for_line(testcase.line, sibling_cases, markers)
+      elsif markers.length == 1 && sibling_cases.none?(&:line)
+        # No line info anywhere and a single marker: unambiguous.
+        markers.first
+      end
+    end
+
+    # A marker annotates the testcase that is the first test below it. Given a
+    # testcase line, find the marker that sits directly above it with no other
+    # testcase in between.
+    def marker_for_line(line, sibling_cases, markers)
+      candidate = markers.select { |m| m[:line] < line }.max_by { |m| m[:line] }
+      return nil unless candidate
+
+      # Reject if another testcase falls between the marker and this test —
+      # that means the marker belongs to the intervening test, not this one.
+      intervening = sibling_cases.any? do |other|
+        other.line && other.line > candidate[:line] && other.line < line
+      end
+      return nil if intervening
+
+      candidate
+    end
+
+    def record_binding(bindings, slug, surface, testcase)
+      rel_file = testcase.file
+      key = [slug, surface, rel_file]
+      state = testcase.stub? ? 'stub' : 'present'
+
+      existing = bindings[key]
+      # Prefer a concrete 'present' state over 'stub' when a slug has both.
+      return if existing && !(existing.state == 'stub' && state == 'present')
+
+      bindings[key] = Binding.new(slug: slug, surface: surface, file: rel_file,
+                                  title: testcase.name, 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?
+
+      return cache[file] if cache.key?(file)
+
+      resolved = File.expand_path(file, base_dir)
+      markers =
+        if File.file?(resolved)
+          scan_markers(File.read(resolved))
+        else
+          []
+        end
+
+      cache[file] = markers
+    end
+
+    # Scan file contents for fp:<slug>[@surface[,surface...]] markers, returning
+    # [{ slug:, surfaces: [..], line: }, ...] (1-based line numbers).
+    # `surfaces` is [] when the marker pins none (use the default surface).
+    def scan_markers(contents)
+      markers = []
+      contents.each_line.with_index(1) do |line, num|
+        line.scan(MARKER_RE) do |(slug, surface_list)|
+          surfaces = surface_list ? surface_list.split(',').map(&:strip).reject(&:empty?) : []
+          markers << { slug: slug, surfaces: surfaces, line: num }
+        end
+      end
+      markers
+    end
+  end
+end

data/lib/fp/version.rb

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

data/lib/fp.rb

@@ -3,6 +3,7 @@
 require_relative 'fp/version'
 require_relative 'fp/config'
 require_relative 'fp/client'
+require_relative 'fp/junit'
 require_relative 'fp/output'
 require_relative 'fp/commands'
 require_relative 'fp/cli'