featureparity 0.0.2 → 0.0.3

data/skills/fp/references/markers.md

@@ -0,0 +1,149 @@
+# fp Marker Syntax
+
+The `fp:<slug>` marker binds a test to a FeatureParity requirement. Place it as a comment immediately before the test definition.
+
+## Basic syntax
+
+```
+fp:<slug>
+```
+
+Where `<slug>` is the requirement's slug (lowercase, underscores, e.g., `print_container_qr`).
+
+## Surface pinning
+
+Pin one or more surfaces with the `@` suffix:
+
+```
+fp:<slug>@<surface>
+fp:<slug>@<surface1>,<surface2>
+```
+
+Examples:
+- `fp:print_qr` — uses `--surface` flag when reporting
+- `fp:print_qr@api` — reports for `api` surface only
+- `fp:print_qr@api,web` — reports for both `api` and `web`
+
+When using `fp report --junit`, each pinned surface produces a separate evidence upload.
+
+## Language examples
+
+### Ruby/RSpec
+
+```ruby
+# fp:print_container_qr
+it 'prints a QR code onto the container label' do
+  expect(label.qr_code).to be_present
+end
+
+# fp:print_container_qr@api,web
+it 'prints a QR code (backend test covering multiple surfaces)' do
+  expect(label.qr_code).to be_present
+end
+```
+
+### Kotlin/JUnit
+
+```kotlin
+// fp:print_container_qr
+@Test
+fun `prints a QR code onto the container label`() {
+    assertNotNull(label.qrCode)
+}
+
+// fp:print_container_qr@customer_android
+@Test
+fun `prints a QR code (Android-specific)`() {
+    assertNotNull(label.qrCode)
+}
+```
+
+### Swift/XCTest
+
+```swift
+// fp:print_container_qr
+func testPrintsQRCodeOntoContainerLabel() {
+    XCTAssertNotNil(label.qrCode)
+}
+
+// fp:print_container_qr@customer_ios
+func testPrintsQRCodeOniOS() {
+    XCTAssertNotNil(label.qrCode)
+}
+```
+
+### TypeScript/Jest
+
+```typescript
+// fp:print_container_qr
+it('prints a QR code onto the container label', () => {
+  expect(label.qrCode).toBeDefined();
+});
+
+// fp:print_container_qr@web
+it('prints a QR code (web-specific)', () => {
+  expect(label.qrCode).toBeDefined();
+});
+```
+
+### Python/pytest
+
+```python
+# fp:print_container_qr
+def test_prints_qr_code_onto_container_label():
+    assert label.qr_code is not None
+
+# fp:print_container_qr@api
+def test_prints_qr_code_api():
+    assert label.qr_code is not None
+```
+
+### Go
+
+```go
+// fp:print_container_qr
+func TestPrintsQRCodeOntoContainerLabel(t *testing.T) {
+    if label.QRCode == nil {
+        t.Fatal("expected QR code")
+    }
+}
+
+// fp:print_container_qr@api
+func TestPrintsQRCodeAPI(t *testing.T) {
+    if label.QRCode == nil {
+        t.Fatal("expected QR code")
+    }
+}
+```
+
+## Rules
+
+1. **One marker per test.** A marker binds to the test directly below it.
+
+2. **Human-readable test names.** The marker handles binding; don't name tests after slugs.
+   - ❌ `it 'print_container_qr' do`
+   - ✅ `it 'prints a QR code onto the container label' do`
+
+3. **Marker must be immediately before the test.** No blank lines or other code between the marker comment and the test definition.
+
+4. **Comment style follows language conventions.** Use `#` for Ruby/Python, `//` for Kotlin/Swift/TypeScript/Go.
+
+## Verification
+
+After adding a marker, verify it's findable:
+
+```bash
+grep -r "fp:print_container_qr" spec/
+```
+
+## JUnit binding
+
+When using `fp report --junit`, the CLI:
+
+1. Parses the JUnit XML report
+2. For each `<testcase>`, reads the `file` attribute to find the source file
+3. Scans the source file for `fp:<slug>` markers
+4. Binds each marker to the test directly below it
+5. Reports evidence for each binding
+
+Testcases without a marker are skipped with a warning. Markers with unknown slugs are also skipped.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureparity
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Stowzilla
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-25 00:00:00.000000000 Z
+date: 2026-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http
@@ -103,13 +103,18 @@ files:
 - lib/fp/commands/projects.rb
 - lib/fp/commands/propose.rb
 - lib/fp/commands/report.rb
+- lib/fp/commands/repos.rb
 - lib/fp/commands/setup.rb
 - lib/fp/commands/show.rb
 - lib/fp/commands/surfaces.rb
 - lib/fp/commands/version.rb
 - lib/fp/config.rb
+- lib/fp/junit.rb
 - lib/fp/output.rb
 - lib/fp/version.rb
+- skills/fp/SKILL.md
+- skills/fp/references/cli.md
+- skills/fp/references/markers.md
 homepage: https://featureparity.dev
 licenses:
 - MIT