featureparity 0.0.5 → 0.0.7

data/lib/fp/commands/init.rb

@@ -0,0 +1,384 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Fp
+  module Commands
+    # fp init --project <slug> [--surface api] [--level regression] [--force]
+    #         [--no-workflow] [--no-agents] [--dir PATH]
+    #
+    # Onboards a repo onto FeatureParity by writing the three things enforcement needs
+    # to actually happen, rather than being something a human remembers to do:
+    #
+    #   .featureparity.yml                    which project this code is
+    #   .github/workflows/feature-parity.yml  the CI gate that blocks merges
+    #   AGENTS.md (appended section)          the instructions agents read
+    #
+    # The last one is the point. A gate that fails is only useful if the agent that
+    # opened the PR knows why and what to do about it — otherwise enforcement is just a
+    # red X nobody can action. Writing the marker/report/propose workflow into the file
+    # agents already read on every task is what closes that loop.
+    #
+    # Everything written is idempotent and additive: existing files are left alone
+    # unless --force, and the AGENTS.md section is appended once and detected by a
+    # marker comment on re-run.
+    class Init < Base
+      KNOWN_FLAGS = {
+        project: :string,
+        surface: :string,
+        level: :string,
+        dir: :string,
+        force: :boolean,
+        no_workflow: :boolean,
+        no_agents: :boolean
+      }.freeze
+
+      WORKFLOW_PATH = File.join('.github', 'workflows', 'feature-parity.yml')
+
+      # Files an agent is likely to already be reading. The FP section is appended to
+      # whichever of these exist; if none do, AGENTS.md is created.
+      AGENT_DOC_CANDIDATES = %w[AGENTS.md CLAUDE.md].freeze
+
+      # Lets a re-run recognise its own previous output instead of appending twice.
+      AGENTS_MARKER = '<!-- feature-parity:begin -->'
+      AGENTS_END_MARKER = '<!-- feature-parity:end -->'
+
+      def run(args)
+        opts, = parse_flags(args, KNOWN_FLAGS)
+
+        root = File.expand_path(opts[:dir] || Dir.pwd)
+        unless File.directory?(root)
+          output.error("Not a directory: #{root}")
+          exit 1
+        end
+
+        existing = ProjectConfig.discover(root)
+        project_slug = opts[:project] || existing.project
+        unless project_slug
+          output.error('--project is required (the FeatureParity project slug this repo belongs to)')
+          exit 1
+        end
+
+        level = opts[:level]
+        if level && !Parity::LEVELS.include?(level)
+          output.error("--level must be one of: #{Parity::LEVELS.join(', ')}")
+          exit 1
+        end
+
+        written = []
+        skipped = []
+
+        write_project_config(root, project_slug, level, opts, written, skipped)
+        write_workflow(root, opts, written, skipped) unless opts[:no_workflow]
+        write_agent_docs(root, project_slug, opts, written, skipped) unless opts[:no_agents]
+
+        report(project_slug, root, written, skipped, opts)
+      end
+
+      private
+
+      def write_project_config(root, project_slug, level, opts, written, skipped)
+        path = File.join(root, ProjectConfig::FILENAME)
+        body = ProjectConfig.render(
+          project: project_slug,
+          enforcement: level,
+          surface: opts[:surface]
+        )
+
+        write_file(path, body, opts, written, skipped)
+      end
+
+      def write_workflow(root, opts, written, skipped)
+        path = File.join(root, WORKFLOW_PATH)
+        write_file(path, workflow_body, opts, written, skipped)
+      end
+
+      # Appends the FP section to the agent-facing docs, creating AGENTS.md if none of
+      # the candidates exist. Appending rather than overwriting matters: these files are
+      # hand-maintained and full of project-specific instruction we must not clobber.
+      def write_agent_docs(root, project_slug, opts, written, skipped)
+        targets = AGENT_DOC_CANDIDATES.select { |name| File.file?(File.join(root, name)) }
+        targets = [AGENT_DOC_CANDIDATES.first] if targets.empty?
+
+        section = agents_section(project_slug)
+
+        targets.each do |name|
+          path = File.join(root, name)
+
+          if File.file?(path)
+            content = File.read(path)
+            if content.include?(AGENTS_MARKER) && !opts[:force]
+              skipped << [relative(root, path), 'already has a FeatureParity section']
+              next
+            end
+
+            content = strip_existing_section(content) if content.include?(AGENTS_MARKER)
+            separator = content.end_with?("\n") ? "\n" : "\n\n"
+            File.write(path, "#{content}#{separator}#{section}")
+            written << [relative(root, path), 'appended FeatureParity section']
+          else
+            File.write(path, section)
+            written << [relative(root, path), 'created']
+          end
+        end
+      end
+
+      # Remove a previously written section so --force refreshes rather than duplicates.
+      def strip_existing_section(content)
+        content.sub(/\n*#{Regexp.escape(AGENTS_MARKER)}.*?#{Regexp.escape(AGENTS_END_MARKER)}\n?/m, "\n")
+      end
+
+      def write_file(path, body, opts, written, skipped)
+        root = File.expand_path(opts[:dir] || Dir.pwd)
+        relative_path = relative(root, path)
+        existed = File.exist?(path)
+
+        if existed && !opts[:force]
+          skipped << [relative_path, 'already exists (use --force to overwrite)']
+          return
+        end
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, body)
+        written << [relative_path, existed ? 'overwritten' : 'created']
+      end
+
+      def relative(root, path)
+        path.sub(%r{\A#{Regexp.escape(root)}/?}, '')
+      end
+
+      def report(project_slug, root, written, skipped, opts)
+        output.success({
+          project: project_slug,
+          dir: root,
+          written: written.map { |p, note| { path: p, note: note } },
+          skipped: skipped.map { |p, note| { path: p, note: note } }
+        }) do
+          puts "Initialized FeatureParity for project '#{project_slug}' in #{root}"
+          puts
+
+          unless written.empty?
+            puts 'Wrote:'
+            written.each { |p, note| puts "  #{p} (#{note})" }
+            puts
+          end
+
+          unless skipped.empty?
+            puts 'Skipped:'
+            skipped.each { |p, note| puts "  #{p} — #{note}" }
+            puts
+          end
+
+          puts 'Next steps:'
+          puts "  1. Make sure the surfaces this repo ships exist:  fp surfaces --project #{project_slug}"
+          puts '  2. Add the FP_API_KEY secret to the repo so CI can report evidence and run the gate.'
+          puts "  3. Try the gate locally:  fp check#{opts[:surface] ? " --surface #{opts[:surface]}" : ''}"
+          puts
+          puts 'The gate starts at the `regression` level, which only fails on tests that have'
+          puts 'gone red — it will not block you on requirements that were never covered. Raise'
+          puts 'the level to `covered` or `strict` once the gaps are paid down.'
+        end
+      end
+
+      # The CI gate. Two jobs on purpose: reporting evidence and enforcing the gate are
+      # separate concerns, and the gate must run on pull requests (where it blocks a
+      # merge) while evidence reporting only makes sense on trusted pushes.
+      def workflow_body
+        <<~YAML
+          # FeatureParity — parity enforcement.
+          #
+          # Generated by `fp init`. Two jobs, deliberately separate:
+          #
+          #   report  On pushes to the default branch, feed test results back to
+          #           FeatureParity so the parity matrix reflects real pass/fail.
+          #   gate    On pull requests, fail the build when the project violates its
+          #           enforcement level. Make this a required status check in branch
+          #           protection to actually block merges.
+          #
+          # The gate reads the project slug from .featureparity.yml, so it needs no
+          # hardcoded project name here.
+          name: Feature Parity
+
+          on:
+            push:
+              branches: [main, master]
+            pull_request:
+            workflow_dispatch:
+
+          concurrency:
+            group: feature-parity-${{ github.ref }}
+            cancel-in-progress: true
+
+          jobs:
+            gate:
+              name: Parity gate
+              runs-on: ubuntu-latest
+              steps:
+                - uses: actions/checkout@v4
+
+                - uses: ruby/setup-ruby@v1
+                  with:
+                    ruby-version: '3.3'
+
+                - name: Install fp
+                  run: gem install featureparity
+
+                # Exits non-zero when the project violates its enforcement level.
+                # Add `--warn-only` while adopting if you need the annotations without
+                # blocking merges yet.
+                #
+                # NOTE: as written this gates on what has been *recorded*, which on a pull
+                # request is the default branch's state. To judge a branch on its own
+                # results, emit JUnit in this job and pass it — nothing is saved:
+                #
+                #   fp check --surface <surface-key> --junit junit.xml
+                #
+                # That is also the only way to catch a test that was deleted, renamed, or
+                # had its fp: marker stripped: the remaining tests still pass, so a plain
+                # suite stays green while the requirement loses its only proof. Use one
+                # call per surface.
+                - name: Check parity
+                  env:
+                    FP_API_KEY: ${{ secrets.FP_API_KEY }}
+                  run: fp check
+
+            # Uncomment and adapt once your suite emits JUnit XML. `fp ci-report` writes
+            # real passing/failing evidence — without it, the matrix only ever shows the
+            # `present` markers agents filed, and the gate has nothing green to see.
+            #
+            # report:
+            #   name: Report evidence
+            #   if: github.event_name == 'push'
+            #   runs-on: ubuntu-latest
+            #   steps:
+            #     - uses: actions/checkout@v4
+            #     - name: Run tests (emit JUnit)
+            #       run: echo "replace with your test command emitting junit.xml"
+            #     - name: Report to FeatureParity
+            #       if: always()
+            #       env:
+            #         FP_API_KEY: ${{ secrets.FP_API_KEY }}
+            #       run: |
+            #         gem install featureparity
+            #         fp ci-report --junit junit.xml \\
+            #           --surface <surface-key> \\
+            #           --ci-url "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+        YAML
+      end
+
+      # The agent-facing brief. Written as instructions rather than description, because
+      # this text is read by something that is about to write a test and needs to know
+      # exactly what to do.
+      def agents_section(project_slug)
+        <<~MARKDOWN
+          #{AGENTS_MARKER}
+          ## FeatureParity (this project tracks feature parity)
+
+          This repo is tracked by [FeatureParity](https://featureparity.dev) as project
+          **`#{project_slug}`** (see `.featureparity.yml`). Requirements are shared across every
+          surface the product ships on, and CI enforces that they stay covered — a pull request
+          that lets a covered requirement go red will fail the `Parity gate` check.
+
+          Two things are expected of you on every change, not just when someone asks:
+
+          1. **A feature or fix ships with a test bound to its requirement** (`fp:<slug>`).
+          2. **The requirements stay true.** If none covers what you're building, propose one.
+             If one is wrong or outdated, propose the change — never edit or ignore it.
+
+          **Start every task by checking the requirements — before you write code, not
+          after.** When you pick up a feature or bug, first run `fp list` / `fp show` to find
+          the requirement it belongs to. If one exists, you'll bind your test to it; if none
+          does, propose one (as a draft) so the work is on the record from the outset. Treating
+          this as the opening move — not a chore at the end — is what keeps parity honest.
+
+          ### 1. Find the requirement — do this first
+
+          ```bash
+          fp list                      # active requirements (project comes from .featureparity.yml)
+          fp list --gaps               # the ones with no evidence yet — good places to start
+          fp show <slug>               # details, acceptance criteria, and existing receipts
+          fp history <slug>            # why it says what it says, and whether a change is pending
+          ```
+
+          If no requirement covers what you're building, propose one. Agents always create
+          **drafts**; a human activates them:
+
+          ```bash
+          fp propose --slug <slug> --name "..." --required <surface>,<surface> \\
+            --why "..." --acceptance "..." \\
+            --source-type fizzy --source-url <card-or-issue-url>
+          ```
+
+          ### 2. If the requirement is wrong, propose a change — don't silently edit it
+
+          Shipping something that contradicts a requirement means one of the two is wrong.
+          Say which, in the record:
+
+          ```bash
+          fp propose-change <slug> --why "..." --acceptance "..." \\
+            --reason "what prompted this" \\
+            --source-type fizzy --source-url <card-or-issue-url>
+
+          fp propose-change <slug> --removal --reason "superseded by <other-slug>"
+          ```
+
+          What happens: the change is applied, the requirement drops back to **draft**, and a
+          human reviews the old-vs-new diff. Rejecting restores the previous wording verbatim.
+          What it *was* is kept, so nothing is lost either way.
+
+          Rules worth knowing before you try:
+
+          - Never edit a requirement's wording by any other route. `fp propose-change` is the
+            only one that records what it was and what prompted the change.
+          - You cannot change `--slug` (it's the join to every `fp:<slug>` marker) or remove a
+            required surface. Both come back as 403.
+          - You cannot approve or reject — not even your own proposal.
+          - One open proposal per requirement (409 otherwise). Run `fp history <slug>` first.
+          - **A requirement awaiting review still counts toward the gate.** Proposing a change
+            is not a way to make a red gate green; it only marks the existing evidence
+            `suspect`, because the tests were written against wording that has moved.
+
+          ### 3. Mark the test
+
+          Add an `fp:<slug>` comment directly above the test. Keep the test's own name
+          readable — the marker is the join, not the name.
+
+          ```ruby
+          # fp:print_container_qr
+          it 'prints a QR code onto the container label' do
+          ```
+
+          Pin surfaces in the marker when one test satisfies more than one:
+          `# fp:print_container_qr@api,web`.
+
+          Every feature needs one. A requirement with no marked test is a gap, and gaps are
+          what the gate is eventually going to fail on.
+
+          ### 4. Report the evidence
+
+          ```bash
+          fp report --junit junit.xml --surface <surface> --repo <org/repo> \\
+            --work-item <card-or-issue-url>
+          ```
+
+          Report `present` or `stub` only — **never** claim `passing`/`failing`. Those are CI's
+          to write, via `fp ci-report`, and the gate trusts them precisely because agents can't
+          set them.
+
+          If you just changed a requirement's wording and re-wrote its tests, re-report the
+          evidence: that's what clears `suspect`.
+
+          ### 5. Confirm you didn't break the gate
+
+          ```bash
+          fp check                     # exits non-zero if this project now violates its level
+          ```
+
+          `fp check --json` if you want to parse the violations. Run `fp help` for the full
+          command list.
+          #{AGENTS_END_MARKER}
+        MARKDOWN
+      end
+    end
+  end
+end

data/lib/fp/commands/list.rb

@@ -15,9 +15,13 @@ module Fp
 
       def run(args)
         opts, = parse_flags(args, KNOWN_FLAGS)
-        require_flag(opts, :project)
+        project_config = ProjectConfig.discover
+        project_slug = require_project!(opts, project_config)
+        project_id = resolve_project_id(project_slug)
 
-        project_id = resolve_project_id(opts[:project])
+        # A single-surface repo can declare its surface once in .featureparity.yml
+        # rather than passing --surface on every call.
+        opts[:surface] ||= project_config.surface
 
         if opts[:gaps]
           list_gaps(project_id, opts)
@@ -37,6 +41,7 @@ module Fp
         end
 
         requirements = result[:data]['requirements'] || []
+        all = requirements
 
         # Filter by status (default: active only)
         status_filter = opts[:status] || 'active'
@@ -49,7 +54,15 @@ module Fp
           end
         end
 
-        output.success({ requirements: requirements, project: opts[:project] }) do
+        # Requirements a proposed change knocked back to draft. The default `--status
+        # active` filter hides them, which would make an active requirement appear to
+        # vanish the moment an agent proposed a change to it — so they get named below
+        # even when the filter excluded them. They still count toward the gate.
+        awaiting = all.select { |r| r['pending_change_kind'].to_s != '' }
+        hidden_awaiting = awaiting.reject { |r| requirements.include?(r) }
+
+        output.success({ requirements: requirements, project: opts[:project],
+                         awaiting_review: awaiting }) do
           if requirements.empty?
             filter_desc = [status_filter]
             filter_desc << "category: #{opts[:category]}" if opts[:category]
@@ -72,13 +85,13 @@ module Fp
             parents.each do |r|
               surfaces = (r['required_surfaces'] || []).join(', ')
               category = r['category'] || '-'
-              rows << [r['slug'], truncate(r['title'], 40), category, surfaces.empty? ? '-' : surfaces, r['status']]
+              rows << [r['slug'], truncate(r['title'], 40), category, surfaces.empty? ? '-' : surfaces, status_cell(r)]
 
               # Add children indented
               (children_by_parent[r['id']] || []).each do |child|
                 child_surfaces = (child['required_surfaces'] || []).join(', ')
                 child_category = child['category'] || '-'
-                rows << ["  └ #{child['slug']}", truncate(child['title'], 36), child_category, child_surfaces.empty? ? '-' : child_surfaces, child['status']]
+                rows << ["  └ #{child['slug']}", truncate(child['title'], 36), child_category, child_surfaces.empty? ? '-' : child_surfaces, status_cell(child)]
               end
             end
 
@@ -86,56 +99,123 @@ module Fp
             orphans.each do |r|
               surfaces = (r['required_surfaces'] || []).join(', ')
               category = r['category'] || '-'
-              rows << [r['slug'], truncate(r['title'], 40), category, surfaces.empty? ? '-' : surfaces, r['status']]
+              rows << [r['slug'], truncate(r['title'], 40), category, surfaces.empty? ? '-' : surfaces, status_cell(r)]
             end
 
             output.table(headers, rows)
           end
+
+          print_awaiting_review(hidden_awaiting)
         end
       end
 
+      # "draft" alone doesn't distinguish "never approved" from "was approved, someone
+      # proposed a change". The pointer on the requirement does, so use it.
+      def status_cell(requirement)
+        kind = requirement['pending_change_kind'].to_s
+        return requirement['status'] if kind.empty?
+
+        "#{requirement['status']} (#{kind} proposed)"
+      end
+
+      def print_awaiting_review(hidden)
+        return if hidden.empty?
+
+        puts
+        puts "#{hidden.size} requirement(s) not listed above are awaiting review of a proposed change:"
+        hidden.each { |r| puts "  #{r['slug']} — #{r['pending_change_kind']} proposed  (fp history #{r['slug']})" }
+        puts 'They are still enforced by the gate. A human must approve or reject the change.'
+      end
+
+      # Gaps: active requirements with at least one required surface that has no real
+      # evidence behind it.
+      #
+      # This used to return *every* active requirement, because evidence was never
+      # consulted — "gaps" and "list" produced the same rows, so `--gaps` told you
+      # nothing. It now reads the parity report at the `covered` level, where a cell
+      # violates when it is missing, stubbed, or failing. That's the level whose
+      # definition of a violation matches what "gap" has always meant.
       def list_gaps(project_id, opts)
-        # Gaps endpoint may not exist yet - fall back to computing from requirements
-        # For now, list requirements that don't have evidence for a surface
-        result = client.list_requirements(project_id: project_id, category: opts[:category])
+        result = client.get_parity(project_id, level: 'covered', surface: opts[:surface])
 
         unless result[:ok]
           output.error(result[:error], status: result[:status])
           exit 1
         end
 
-        # Only show active requirements for gaps
-        requirements = (result[:data]['requirements'] || []).select { |r| r['status'] == 'active' }
+        report = result[:data]['parity'] || {}
+
+        # Group the violating cells back up per requirement, so a requirement missing
+        # three surfaces is one row naming three surfaces rather than three rows.
+        gaps_by_slug = {}
+        (report['violations'] || []).each do |violation|
+          entry = gaps_by_slug[violation['slug']] ||= {
+            'slug' => violation['slug'],
+            'title' => violation['title'],
+            'surfaces' => []
+          }
+          entry['surfaces'] << { 'surface' => violation['surface'], 'state' => violation['state'] }
+        end
 
-        # Filter by surface if specified
-        if opts[:surface]
-          requirements = requirements.select do |r|
-            (r['required_surfaces'] || []).include?(opts[:surface])
-          end
+        # Category isn't on the parity report, so resolve it from the requirements the
+        # report carries — and apply --category here rather than server-side.
+        rows_by_slug = (report['requirements'] || []).to_h { |r| [r['slug'], r] }
+        gaps = gaps_by_slug.values
+        gaps.each do |gap|
+          row = rows_by_slug[gap['slug']] || {}
+          gap['category'] = row['category']
+          # A gap on a requirement whose wording is mid-change is a different problem
+          # from a plain uncovered one — the fix may be to review the change, not to
+          # write a test.
+          gap['under_review'] = !!row['under_review']
         end
+        gaps = gaps.select { |gap| gap['category'] == opts[:category] } if opts[:category]
 
-        # For now, gaps = all requirements (evidence API is #1214)
-        # Once evidence API exists, filter to only those without evidence
-        output.success({ gaps: requirements, project: opts[:project], surface: opts[:surface], category: opts[:category] }) do
-          if requirements.empty?
+        render_gaps(gaps, report, opts)
+      end
+
+      def render_gaps(gaps, report, opts)
+        payload = {
+          gaps: gaps,
+          project: opts[:project],
+          surface: opts[:surface],
+          category: opts[:category],
+          summary: report['summary']
+        }
+
+        output.success(payload) do
+          if gaps.empty?
             filter_desc = []
             filter_desc << "category: #{opts[:category]}" if opts[:category]
             filter_desc << "surface: #{opts[:surface]}" if opts[:surface]
             msg = 'No gaps found'
             msg += " (#{filter_desc.join(', ')})" unless filter_desc.empty?
             puts "#{msg}."
-          else
-            desc = "Gaps for project '#{opts[:project]}'"
-            desc += " (surface: #{opts[:surface]})" if opts[:surface]
-            desc += " (category: #{opts[:category]})" if opts[:category]
-            puts "#{desc}:"
-            headers = %w[SLUG TITLE CATEGORY SURFACES]
-            rows = requirements.map do |r|
-              surfaces = (r['required_surfaces'] || []).join(', ')
-              category = r['category'] || '-'
-              [r['slug'], truncate(r['title'], 40), category, surfaces]
+
+            unscoped = (report['summary'] || {})['unscoped'].to_i
+            if unscoped.positive?
+              puts "Note: #{unscoped} requirement(s) name no surface this project has, " \
+                   'so nothing can cover them.'
             end
-            output.table(headers, rows)
+            next
+          end
+
+          desc = "Gaps for project '#{opts[:project]}'"
+          desc += " (surface: #{opts[:surface]})" if opts[:surface]
+          desc += " (category: #{opts[:category]})" if opts[:category]
+          puts "#{desc}:"
+
+          headers = %w[SLUG TITLE CATEGORY UNCOVERED]
+          rows = gaps.map do |gap|
+            uncovered = gap['surfaces'].map { |s| "#{s['surface']} (#{s['state']})" }.join(', ')
+            slug = gap['under_review'] ? "#{gap['slug']} #{Parity::UNDER_REVIEW}" : gap['slug']
+            [slug, truncate(gap['title'], 40), gap['category'] || '-', uncovered]
+          end
+          output.table(headers, rows)
+
+          if gaps.any? { |gap| gap['under_review'] }
+            puts
+            puts "#{Parity::UNDER_REVIEW} #{Parity::UNDER_REVIEW_LEGEND} — check `fp history <slug>` before writing a test against wording that may be about to move."
           end
         end
       end