featureparity 0.0.1 → 0.0.3

data/lib/fp/config.rb

@@ -5,16 +5,33 @@ require 'fileutils'
 
 module Fp
   # Handles configuration: profiles, API keys, API URL.
-  # Priority: FP_API_KEY env var > --profile flag > FP_PROFILE env var > default profile
+  #
+  # API URL resolution priority (highest wins):
+  #   1. --api-url CLI flag (passed via constructor)
+  #   2. FP_API_URL env var
+  #   3. Profile-specific api_url (in profile config)
+  #   4. Global api_url setting (top-level in config.yml)
+  #   5. DEFAULT_API_URL
+  #
+  # API key resolution priority:
+  #   1. FP_API_KEY 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
 
-    def initialize(profile: nil)
+    def initialize(profile: nil, api_url: nil)
       @profile_name = resolve_profile_name(profile)
+      @explicit_api_url = api_url
       @api_key = resolve_api_key
       @api_url = resolve_api_url
     end
@@ -33,34 +50,51 @@ module Fp
     end
 
     class << self
-      def load_profiles
+      def load_config
         return {} unless File.exist?(CONFIG_FILE)
 
-        config = YAML.safe_load_file(CONFIG_FILE, permitted_classes: [Symbol]) || {}
-        config['profiles'] || {}
+        YAML.safe_load_file(CONFIG_FILE, permitted_classes: [Symbol]) || {}
       rescue StandardError => e
         warn "Warning: Could not load config file: #{e.message}"
         {}
       end
 
+      def load_profiles
+        config = load_config
+        config['profiles'] || {}
+      end
+
       def save_profile(name, api_key:, api_url: nil)
         FileUtils.mkdir_p(CONFIG_DIR)
+        ensure_config_file!
 
-        # Ensure config file has restricted permissions
-        unless File.exist?(CONFIG_FILE)
-          File.write(CONFIG_FILE, "---\nprofiles: {}\n")
-          File.chmod(0o600, CONFIG_FILE)
-        end
-
-        config = YAML.safe_load_file(CONFIG_FILE, permitted_classes: [Symbol]) || {}
+        config = load_config
         config['profiles'] ||= {}
-        config['profiles'][name] = {
-          'api_key' => api_key
-        }
+        config['profiles'][name] = { 'api_key' => api_key }
         config['profiles'][name]['api_url'] = api_url if api_url
 
-        File.write(CONFIG_FILE, YAML.dump(config))
-        File.chmod(0o600, CONFIG_FILE)
+        write_config!(config)
+      end
+
+      # Get a global setting (top-level key in config.yml)
+      def get_setting(key)
+        config = load_config
+        config[key.to_s]
+      end
+
+      # Set a global setting (top-level key in config.yml)
+      def set_setting(key, value)
+        FileUtils.mkdir_p(CONFIG_DIR)
+        ensure_config_file!
+
+        config = load_config
+        if value.nil?
+          config.delete(key.to_s)
+        else
+          config[key.to_s] = value
+        end
+
+        write_config!(config)
       end
 
       def list_profiles
@@ -70,13 +104,101 @@ module Fp
       def profile_exists?(name)
         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!
+        return if File.exist?(CONFIG_FILE)
+
+        File.write(CONFIG_FILE, "---\nprofiles: {}\n")
+        File.chmod(0o600, CONFIG_FILE)
+      end
+
+      def write_config!(config)
+        File.write(CONFIG_FILE, YAML.dump(config))
+        File.chmod(0o600, CONFIG_FILE)
+      end
     end
 
     private
 
     def resolve_profile_name(explicit_profile)
-      # Explicit --profile flag takes precedence over FP_PROFILE env var
-      explicit_profile || ENV['FP_PROFILE']
+      # 1. Explicit --profile flag  2. FP_PROFILE env var
+      name = explicit_profile || ENV['FP_PROFILE']
+      return name if name && !name.empty?
+
+      # 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.
+      return DEFAULT_PROFILE_NAME if self.class.profile_exists?(DEFAULT_PROFILE_NAME)
+
+      nil
     end
 
     def resolve_api_key
@@ -94,17 +216,24 @@ module Fp
     end
 
     def resolve_api_url
-      # FP_API_URL env var takes precedence
+      # 1. Explicit --api-url flag
+      return @explicit_api_url if @explicit_api_url && !@explicit_api_url.empty?
+
+      # 2. FP_API_URL env var
       return ENV['FP_API_URL'] if ENV['FP_API_URL'] && !ENV['FP_API_URL'].empty?
 
-      # Then profile-specific URL
+      # 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']
       end
 
-      # Finally, default
+      # 4. Global api_url setting
+      global_url = self.class.get_setting('api_url')
+      return global_url if global_url && !global_url.empty?
+
+      # 5. 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/output.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'json'
-require 'csv'
 
 module Fp
   # Output formatting for CLI responses
@@ -61,6 +60,7 @@ module Fp
     end
 
     def csv(headers, rows)
+      require 'csv'
       csv_string = CSV.generate do |csv|
         csv << headers
         rows.each { |row| csv << row }

data/lib/fp/version.rb

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

data/skills/fp/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: fp
+description: "Use the fp CLI to track feature parity: report evidence linking tests to requirements, propose new requirements as drafts, view the parity matrix, and upload test results from JUnit XML when CI isn't available."
+license: MIT
+compatibility: Requires the fp executable on PATH (gem install featureparity)
+metadata:
+  gem: featureparity
+  binary: fp
+---
+
+# fp — FeatureParity CLI
+
+Prefer the installed `fp` binary over inventing equivalent Ruby. Confirm it exists first:
+
+```bash
+command -v fp && fp --version
+```
+
+If missing: `gem install featureparity` (or `bundle exec fp` inside an app that already depends on the gem).
+
+## Non-interactive rules
+
+- Always pass flags. Never rely on prompts or TTY menus.
+- Use `--json` when parsing output programmatically.
+- Use `fp help <command>` before destructive commands.
+- Treat non-zero exit as failure; read stderr.
+
+## Authentication
+
+`fp` needs an API key. Check if configured:
+
+```bash
+# Environment variable (preferred for agents)
+echo $FP_API_KEY
+
+# Or via profile
+fp profile list
+```
+
+If not set, ask the user for their API key or have them run `fp setup`.
+
+## Core workflows
+
+### 1. Check existing requirements
+
+```bash
+fp list --project stowzilla                    # All active requirements
+fp list --project stowzilla --gaps             # Requirements without evidence
+fp show <slug> --project stowzilla             # Requirement details
+fp matrix --project stowzilla                  # ASCII parity matrix
+fp matrix --project stowzilla --csv            # Export as CSV
+```
+
+### 2. Add the fp:<slug> marker to tests
+
+Place a comment immediately before the test to bind it to a requirement:
+
+```ruby
+# fp:print_container_qr
+it 'prints a QR code onto the container label' do
+  expect(label.qr_code).to be_present
+end
+```
+
+**Rules:**
+- Use `fp:<slug>` where `<slug>` is the requirement's slug
+- Keep test names human-readable — the marker handles binding
+- Pin surfaces with `@suffix`: `fp:print_qr@api,web` reports for both surfaces
+
+### 3. Report evidence (single test)
+
+```bash
+fp report <slug> \
+  --project stowzilla \
+  --surface api \
+  --file spec/qr_spec.rb \
+  --repo stowzilla/marketplace \
+  --work-item https://app.fizzy.do/123/cards/456
+```
+
+**Required:** `<slug>`, `--project`, `--surface`, `--file`, `--repo`
+**Optional:** `--pr`, `--sha`, `--work-item`, `--ci-url`, `--title`
+
+**Agents report `present` (default) or `stub` only. Never `passing` or `failing`.**
+
+### 4. Report evidence from JUnit XML (batch upload without CI)
+
+When CI isn't available, run the suite locally and upload the report:
+
+```bash
+# 1. Generate JUnit XML
+rspec --format RspecJunitFormatter --out junit.xml
+
+# 2. Upload — one call covers every marked test
+fp report --junit junit.xml \
+  --project stowzilla \
+  --surface api \
+  --repo stowzilla/marketplace \
+  --work-item https://app.fizzy.do/123/cards/456
+```
+
+- No `<slug>` positional needed — slugs come from the `fp:<slug>` markers
+- Skipped tests become `stub`; all others `present`
+- Unknown slugs and unmarked tests are skipped with a warning
+- `--surface` is the default; markers can override with `@suffix`
+- `--base-dir DIR` sets where relative paths resolve from
+
+### 5. Propose new requirements
+
+```bash
+fp propose --project stowzilla \
+  --slug print_container_qr \
+  --name "Print QR on container label" \
+  --why "Enables scanning containers in the warehouse" \
+  --required api,customer_android \
+  --acceptance "Label shows scannable QR code"
+```
+
+**Agents always create requirements as draft.** A human must activate in the web app.
+
+## Quick reference
+
+| Task | Command |
+|------|---------|
+| List requirements | `fp list --project X` |
+| Show gaps | `fp list --project X --gaps` |
+| Show details | `fp show <slug> --project X` |
+| Report evidence | `fp report <slug> --project X --surface Y --file Z --repo A/B` |
+| Report from JUnit | `fp report --junit file.xml --project X --surface Y --repo A/B` |
+| Propose requirement | `fp propose --project X --slug Y --name "..."` |
+| View matrix | `fp matrix --project X` |
+| List surfaces | `fp surfaces --project X` |
+| List projects | `fp projects` |
+
+All commands support `--json` for machine-readable output.
+
+## When to read more
+
+- Full flag reference and exit codes → `references/cli.md`
+- Marker syntax and examples → `references/markers.md`