featureparity 0.0.2 → 0.0.3

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.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`

data/skills/fp/references/cli.md

@@ -0,0 +1,219 @@
+# fp CLI Reference
+
+Complete flag reference for the `fp` command-line tool.
+
+## Global flags
+
+These work with any command:
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output JSON instead of human-readable text |
+| `--profile NAME` | Use a named profile from `~/.config/fp/config.yml` |
+| `--api-url URL` | Override the API URL for this invocation |
+| `--help` | Show help for any command |
+
+## Commands
+
+### fp setup
+
+Interactive first-run configuration. Validates API key and saves a profile.
+
+```bash
+fp setup                                    # Interactive
+fp setup --api-key fp_... --non-interactive # Non-interactive
+fp setup --api-key fp_... --profile ci      # Named profile
+```
+
+### fp projects
+
+List accessible projects.
+
+```bash
+fp projects
+fp projects --json
+```
+
+### fp surfaces
+
+List surfaces for a project.
+
+```bash
+fp surfaces --project stowzilla
+fp surfaces --project stowzilla --json
+```
+
+### fp list
+
+List requirements.
+
+```bash
+fp list --project stowzilla              # All active requirements
+fp list --project stowzilla --gaps       # Requirements without evidence
+fp list --project stowzilla --status draft
+fp list --project stowzilla --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `--project` | Project slug (required) |
+| `--gaps` | Show only requirements without evidence |
+| `--status` | Filter by status: active, draft, archived |
+| `--category` | Filter by category |
+
+### fp show
+
+Show requirement details.
+
+```bash
+fp show print_container_qr --project stowzilla
+fp show print_container_qr --project stowzilla --json
+```
+
+### fp report
+
+Report evidence linking a test to a requirement.
+
+**Single-slug mode:**
+
+```bash
+fp report <slug> \
+  --project stowzilla \
+  --surface api \
+  --file spec/qr_spec.rb \
+  --repo stowzilla/marketplace \
+  [--pr URL] [--sha COMMIT] [--work-item URL] [--ci-url URL] [--title "..."] [--state present|stub]
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `<slug>` | Yes | Requirement slug (positional) |
+| `--project` | Yes | Project slug |
+| `--surface` | Yes | Surface this evidence covers |
+| `--file` | Yes | Path to test file (relative to repo root) |
+| `--repo` | Yes | GitHub repo as `org/repo` |
+| `--pr` | No | Pull request URL |
+| `--sha` | No | Commit SHA |
+| `--work-item` | No | Fizzy card or issue URL |
+| `--ci-url` | No | CI run URL |
+| `--title` | No | Human-readable test name for display |
+| `--state` | No | `present` (default) or `stub`. Never `passing`/`failing` — that's CI's job. |
+
+**JUnit batch mode:**
+
+```bash
+fp report --junit junit.xml \
+  --project stowzilla \
+  --surface api \
+  --repo stowzilla/marketplace \
+  [--base-dir DIR] [--pr URL] [--sha COMMIT] [--work-item URL] [--ci-url URL]
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--junit` | Yes | Path to JUnit XML report |
+| `--project` | Yes | Project slug |
+| `--surface` | Conditional | Default surface for markers without `@suffix`. Required if any matched marker pins no surface. |
+| `--repo` | Yes | GitHub repo as `org/repo` |
+| `--base-dir` | No | Where to resolve relative file paths (defaults to cwd) |
+
+In JUnit mode:
+- Slugs come from `fp:<slug>` markers in the test files referenced by the report
+- A marker binds to the test directly below it
+- Skipped/pending tests become `stub`; all others `present`
+- Unknown slugs and unmarked tests are skipped with a warning
+
+### fp propose
+
+Propose a new requirement as draft.
+
+```bash
+fp propose --project stowzilla \
+  --slug print_container_qr \
+  --name "Print QR on container label" \
+  --why "Enables scanning containers" \
+  --required api,customer_android \
+  --acceptance "Label shows scannable QR code"
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--project` | Yes | Project slug |
+| `--slug` | Yes | Requirement slug (immutable, choose carefully) |
+| `--name` | Yes | Human-readable name |
+| `--why` | No | Why this requirement matters |
+| `--required` | No | Comma-separated surfaces that must implement this |
+| `--acceptance` | No | How to verify completion |
+
+**Agents always create requirements as draft.** A human must activate in the web app.
+
+### fp matrix
+
+Display the parity matrix.
+
+```bash
+fp matrix --project stowzilla           # ASCII table
+fp matrix --project stowzilla --csv     # CSV export
+fp matrix --project stowzilla --json    # JSON
+```
+
+### fp profile
+
+Manage named profiles.
+
+```bash
+fp profile list
+fp profile add staging --api-key fp_...
+fp profile remove staging
+fp profile show staging
+```
+
+### fp config
+
+Manage global settings.
+
+```bash
+fp config list
+fp config get api_url
+fp config set api_url https://api.dev.featureparity.dev
+fp config unset api_url
+```
+
+### fp repos
+
+Map surfaces to local repo paths (stored locally, not in the web app).
+
+```bash
+fp repos list --project stowzilla
+fp repos set customer_android ~/code/customer-android --project stowzilla --repo org/repo
+fp repos get customer_android --project stowzilla
+fp repos unset customer_android --project stowzilla
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error (invalid flags, missing required args, API error) |
+
+## Configuration files
+
+- `~/.config/fp/config.yml` — Profiles and global settings
+- `FP_API_KEY` environment variable overrides all profiles
+- `FP_API_URL` environment variable overrides API URL
+- `FP_PROFILE` environment variable selects a profile
+
+## API URL priority
+
+1. `--api-url` flag
+2. `FP_API_URL` environment variable
+3. Profile `api_url` setting
+4. Global `api_url` setting
+5. Default: `https://api.featureparity.dev`
+
+## Profile resolution priority
+
+1. `--profile` flag
+2. `FP_PROFILE` environment variable
+3. `default` profile (if it exists)