@mhosaic/feedback-cli 0.19.0 → 0.21.0

package/skills/integrate-qa-meter/references/qa-meter-config.md

@@ -0,0 +1,168 @@
+# QA Meter — config reference, framework matrix, surfaces, CI
+
+Everything needed to author `qa-meter.config.json`, enable the FAB, and wire CI. Self-contained (this file ships in the CLI tarball; it does not assume the repo `docs/` are present).
+
+---
+
+## `qa-meter.config.json`
+
+Discovered in **cwd only** (no walk-up) by every `qa` subcommand. All path fields resolve **relative to the config file's directory**, except `testsGlob` / `fixturesFile` / `pageObjectsDir`, which resolve **relative to `e2eDir`**. Put the file at the common parent of your e2e dir and your app dir (in a monorepo, that's usually one level up from both) and use relative paths into each.
+
+| Field | Required | Default | Meaning |
+| --- | --- | --- | --- |
+| `e2eDir` | ✅ | — | Playwright e2e root. |
+| `suitesDir` | ✅ | — | Where suites live: hand-authored at the root, generated ones under `<suitesDir>/generated/`. |
+| `outFile` | ✅ | — | Where `qa-status.json` is written. Point it inside the app's served static dir. |
+| `testsGlob` | | `tests/**/*.spec.ts` | Spec glob, relative to `e2eDir`. |
+| `fixturesFile` | | `helpers/fixtures.ts` | Playwright fixtures file (fixture name → page-object class), relative to `e2eDir`. |
+| `pageObjectsDir` | | `pages` | Page-objects dir (classes with `goto()`), relative to `e2eDir`. |
+| `annotationPrefix` | | `@mhosaic` | Honored annotation prefix in spec headers (`@mhosaic:pages`, `@mhosaic:scenario`). |
+| `environment` | | `staging` | Stamped into the artifact (shown in the modal header). |
+| `appVersion` | | `null` | App version stamp; or pass `--version <v>` on the CLI. |
+| `resultsFile` | | `null` | Playwright JSON report. **Absent ⇒ every scenario is `never_run` (gray).** |
+| `devValidationsFile` | | `null` | Append-only dev-validation ledger (human "I checked this" lane). |
+| `sitemap` | | `null` | Sitemap block (below). Omit for a flat page list (no tree). |
+
+### `sitemap` block
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `file` | ✅ (if block present) | Where the sitemap JSON is written (by `qa sitemap`) and read (by `qa build`). |
+| `framework` | | Adapter name, e.g. `"vue-router"`. **Set ⇒ `qa refresh` runs `qa sitemap`. Omit ⇒ you hand-provide `file`.** |
+| `entry` | | **react-router:** the file holding the route tree (`frontend/src/App.tsx` or `frontend/src/router.tsx`). Preferred over `routerDir` for react. |
+| `routerStyle` | | **react-router:** force the reader — `"jsx"` or `"data"`. Omit to auto-detect. |
+| `routerDir` | | Dir holding the route declarations + entry (an `index.*` that exports `routes`). |
+| `titlesFrom` | | Locale JSON for human page titles. Looked up by route `name` under `pages.<name>` (or a root-level `<name>`). |
+| `alias` | | Import-alias map, e.g. `{ "@": "frontend/src" }`. Values resolve relative to the config dir; the adapter follows only in-tree (within `routerDir`) imports and stubs the rest. |
+
+### Worked template (vue-router + Playwright)
+
+> Shipped next to this file as a copy-pasteable **`qa-meter.config.example.json`** — `cp` it to your project root as `qa-meter.config.json` and edit the paths. (Strict JSON: the loader uses `JSON.parse`, so no comments.)
+
+```json
+{
+  "e2eDir": "e2e",
+  "suitesDir": "qa-meter/suites",
+  "outFile": "frontend/public/qa-status.json",
+  "testsGlob": "tests/**/*.spec.ts",
+  "fixturesFile": "helpers/fixtures.ts",
+  "pageObjectsDir": "pages",
+  "environment": "staging",
+  "appVersion": null,
+  "resultsFile": null,
+  "sitemap": {
+    "file": "qa-meter/sitemap.json",
+    "framework": "vue-router",
+    "routerDir": "frontend/src/router",
+    "titlesFrom": "frontend/src/locales/fr.json",
+    "alias": { "@": "frontend/src" }
+  }
+}
+```
+
+---
+
+## Framework matrix
+
+| Capability | Supported | Escape hatch when not |
+| --- | --- | --- |
+| **Spec analysis** (`qa generate`) | **Playwright** (static parse of specs + fixtures + page-objects; no execution) | No Playwright → skip `generate`; hand-author suites in `suitesDir` (see `docs/qa-meter/SUITE-FORMAT.md`), or run sitemap-only. |
+| **Sitemap** (`qa sitemap`) | **vue-router** (`framework: "vue-router"`, `routerDir`) and **react-router** (`framework: "react-router"`, `entry`) | Other router → omit `framework` and hand-provide `sitemap.file` (a `format: 1` SitemapPayload you author). Or omit the whole `sitemap` block → flat page list from the suites' page patterns. |
+| **Test results** (`qa build`) | **Playwright JSON report** via `resultsFile` | No results → all `never_run`/gray (the honest default). |
+
+The adapter reads `routerDir`'s entry (`index.ts/.mjs/.js` exporting `routes`, else the first file that does), transpiles + evaluates it in a sandbox, follows in-tree imports (resolved through `alias`), and stubs out-of-tree ones (stores/components/enums). It handles lazy `() => import()`, nested `children`, spread route arrays, `redirect`, `name`, and dynamic `:segments`. If a route module throws at eval because it *uses* an out-of-tree value at module top-level, move that usage out of the eval path or hand-provide the sitemap.
+
+**react-router (v7 declarative).** Set `framework: "react-router"` and `entry` to the file
+holding the route tree — either JSX `<Routes><Route/>` (e.g. `src/App.tsx`) or
+`createBrowserRouter([…])` (e.g. `src/router.tsx`). This adapter reads routes **statically**
+from the TypeScript syntax tree (no app boot, no sandbox eval). The style is auto-detected;
+force it with `routerStyle: "jsx" | "data"`. Limits, all WARNED (never silently dropped):
+non-literal `path={expr}` and dynamically-composed object routes (spreads / imported arrays /
+`.map()`). Catch-all `*` and root-element `<Navigate>` redirects are dropped; a `<Navigate>`
+nested inside a guard/wrapper element honestly surfaces as a page.
+
+---
+
+## Enabling the FAB (surfaces)
+
+`source` is the only required field. For a host install it's the URL your app serves the artifact at (a string); it also accepts an inline artifact object or a `() => Promise<artifact>` loader for advanced cases.
+
+```ts
+// npm
+createFeedback({
+  apiKey: 'pk_proj_…',
+  endpoint: 'https://…',
+  qaMeter: {
+    source: '/qa-status.json', // required
+    locale: 'fr',              // 'fr' | 'en' — defaults to the feedback widget's resolved locale
+    size: 'sm',                // 'sm' | 'md' (default 'sm' — the half-size second FAB)
+    // position: { right: 36, bottom: 84 },   // default auto-stacks above the feedback FAB
+    // getCurrentPage: () => location.pathname, // override route resolution
+  },
+})
+```
+
+```tsx
+// React — FeedbackProvider forwards the prop unchanged
+<FeedbackProvider apiKey="…" endpoint="…" qaMeter={{ source: '/qa-status.json' }}>
+  {children}
+</FeedbackProvider>
+```
+
+```html
+<!-- CDN / loader embed -->
+<script
+  src="https://cdn.jsdelivr.net/npm/@mhosaic/feedback@<version>/dist/embed.min.js"
+  data-key="pk_proj_…"
+  data-endpoint="https://…"
+  data-qa-source="/qa-status.json"
+  data-qa-locale="fr"
+  defer
+></script>
+```
+
+**Host-gate it:** only set `qaMeter.source` / `data-qa-source` where you want the meter (staging, internal dev). Omit it in production to ship feedback-only. A common pattern is to drive it from an env var that's only set in non-prod builds.
+
+---
+
+## Consuming an unreleased build
+
+The `qaMeter` option exists only on `@mhosaic/feedback` builds that ship the second-FAB integration. To test against an unreleased build (e.g. a feature branch), pack and install the local tarball:
+
+```bash
+# in the feedback-tool-mhosaic monorepo
+pnpm --filter @mhosaic/feedback build
+( cd packages/core && pnpm pack )   # → packages/core/mhosaic-feedback-<ver>.tgz
+
+# in the host app
+npm i  /abs/path/to/packages/core/mhosaic-feedback-<ver>.tgz
+# or yarn add file:/abs/path/...
+```
+
+Once the feature is released, switch back to a semver range.
+
+---
+
+## CI wiring
+
+Rebuild the artifact whenever specs or routes change. The high-value job runs **after** e2e and feeds real results so the meter shows true color:
+
+```yaml
+# after the e2e job has produced a Playwright JSON report
+- name: Build QA Meter artifact
+  run: |
+    npx @mhosaic/feedback-cli@latest qa refresh --version "${{ github.sha }}"
+    # config.resultsFile → the playwright JSON report (e.g. e2e/results.json)
+- name: Publish with static assets
+  run: cp frontend/public/qa-status.json "$BUILD_OUTPUT/"   # ships like any public/ file
+```
+
+Generate the Playwright JSON with `playwright test --reporter=json --output=… > e2e/results.json` (or a `json` reporter in `playwright.config`), and set `resultsFile` to that path.
+
+**Tripwire (optional):** fail CI when the committed inputs drift from what the artifact represents:
+
+```bash
+npx @mhosaic/feedback-cli@latest qa check --strict
+```
+
+All `qa` subcommands accept `--version <app_version>`; `check` accepts `--strict`.

package/skills/integrate-qa-meter/references/qa-meter-troubleshooting.md

@@ -0,0 +1,37 @@
+# QA Meter — troubleshooting
+
+Diagnostics for the `/integrate-qa-meter` flow. Stop on the first red, narrow the cause, fix it — don't silently retry.
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| **Meter is all gray, "0% scenarios passing"** | No test results fed — `resultsFile: null`, so every scenario is `never_run`. This is the honesty model, not a bug. | Run the Playwright suite, write a JSON report, set `resultsFile` to it, re-run `qa build` (or `qa refresh`). Scenarios with a matching passing result turn green. |
+| **QA pastille never appears** (no `[data-mqa-host]` on `<body>`) | `qaMeter.source` not set on the surface, OR `createFeedback` never runs, OR the installed `@mhosaic/feedback` predates the second-FAB integration. | Confirm the source is wired (Step 4). Confirm `createFeedback`/`<FeedbackProvider>`/embed actually executes. Check the installed version supports `qaMeter` (`references/qa-meter-config.md` → "Consuming an unreleased build"). |
+| **`[data-mqa-host]` exists but the pastille is gray "unknown page" on every route** | The current `location.pathname` doesn't match any sitemap/page pattern — usually the sitemap patterns don't reflect the app's real routes. | Inspect `qa-status.json` → `sitemap[].path_pattern`; compare to real URLs. Re-check `routerDir`/`alias` produced the right patterns. For custom routing, pass `qaMeter.getCurrentPage: () => <pattern>`. |
+| **Artifact 404s at runtime** | `outFile` isn't under the served static dir, or `source` points at the wrong URL. | Move `outFile` into the app's static dir (e.g. `public/`); set `source` to the served path. Verify: `curl -s <origin>/qa-status.json -o /dev/null -w "%{http_code}\n"` → `200`. |
+| **`qa sitemap` errors / "No router entry found"** | `routerDir` wrong, `alias` missing/incorrect, the entry doesn't export `routes`, or a route module throws at eval (uses an out-of-tree value at module top-level). | Point `routerDir` at the dir whose `index.*` exports `routes`. Set `alias` (e.g. `{ "@": "<src>" }`). For non-vue-router or a stubborn module, hand-provide `sitemap.file` and omit `framework`. |
+| **Lots of `unmappable` / `zero-case` warnings from `qa generate`** | Specs whose target pages can't be inferred statically (no destructured page-object fixture, no literal `goto()`), or factory/loop/dynamic-title tests that yield no static case. | Not fatal — the artifact still builds. To represent them, add `@mhosaic:pages /route, /other` or `@mhosaic:scenario <id>` to the spec header, or give tests string-literal titles. See `docs/qa-meter/SUITE-FORMAT.md`. Surface the count to the user. |
+| **Console: "QA Meter artifact has an unsupported `format` — refusing to mount"** | The artifact's `format` doesn't match what the installed widget expects (CLI/widget version skew). | Regenerate with a CLI version matching the widget build; bump both together. |
+| **Meter shows stale data** | The artifact wasn't rebuilt after specs/routes changed. | Re-run `qa refresh`; wire it into CI after the e2e job (`references/qa-meter-config.md` → CI wiring). |
+| **Pastille overlaps the feedback FAB or sits in the wrong corner** | Custom feedback-FAB position, or a host element competing for the bottom-right. | Set `qaMeter.position: { right, bottom }` to nudge it; the default stacks it above the feedback FAB. |
+| **`qa generate` finds 0 cases across the whole suite** | `fixturesFile` / `pageObjectsDir` / `testsGlob` point at the wrong place, so nothing is parsed. | Re-check those three against `e2eDir`. Confirm the fixtures file is the one specs import `test` from and that page objects expose `goto()`. |
+
+If a step still fails after narrowing, capture: the full CLI output, the relevant slice of `qa-status.json` (or `sitemap.json`), and the config — then escalate or open an issue against `feedback-tool-mhosaic`.
+
+---
+
+## Quick browser checks (Step 5)
+
+```js
+// pastille mounted + half size?
+const host = document.querySelector('[data-mqa-host]')
+host && host.getAttribute('data-mqa-size')            // → "sm"
+
+// artifact reachable?
+fetch('/qa-status.json').then(r => r.status)          // → 200
+
+// open the sitemap modal programmatically (clicks the pastille)
+document.querySelector('[data-mqa-host]')
+  ?.shadowRoot?.querySelector('[data-testid=qa-pastille]')?.click()
+```
+
+The pastille resolves the current route on SPA navigations (it patches `pushState`/`replaceState` and listens for `popstate`), so its color/aria updates as you navigate without a reload.

package/skills/integrate-qa-meter/references/qa-meter.config.example.json

@@ -0,0 +1,20 @@
+{
+  "e2eDir": "e2e",
+  "suitesDir": "qa-meter/suites",
+  "outFile": "frontend/public/qa-status.json",
+  "testsGlob": "tests/**/*.spec.ts",
+  "fixturesFile": "helpers/fixtures.ts",
+  "pageObjectsDir": "pages",
+  "annotationPrefix": "@mhosaic",
+  "environment": "staging",
+  "appVersion": null,
+  "resultsFile": null,
+  "devValidationsFile": null,
+  "sitemap": {
+    "file": "qa-meter/sitemap.json",
+    "framework": "vue-router",
+    "routerDir": "frontend/src/router",
+    "titlesFrom": "frontend/src/locales/fr.json",
+    "alias": { "@": "frontend/src" }
+  }
+}

package/skills/integrate-qa-meter/references/qa-meter.config.example.react.json

@@ -0,0 +1,19 @@
+{
+  "e2eDir": "e2e",
+  "suitesDir": "qa-meter/suites",
+  "outFile": "frontend/public/qa-status.json",
+  "testsGlob": "tests/**/*.spec.ts",
+  "fixturesFile": "helpers/fixtures.ts",
+  "pageObjectsDir": "pages",
+  "annotationPrefix": "@mhosaic",
+  "environment": "staging",
+  "appVersion": null,
+  "resultsFile": null,
+  "devValidationsFile": null,
+  "sitemap": {
+    "file": "qa-meter/sitemap.json",
+    "framework": "react-router",
+    "entry": "frontend/src/App.tsx",
+    "routerStyle": "jsx"
+  }
+}