@designfever/web-review-kit 0.7.3 → 0.8.0

package/docs/testing.md

@@ -0,0 +1,68 @@
+# Testing
+
+`df-web-review-kit` uses Vitest (jsdom environment) for package-level unit and adapter contract tests.
+
+## Commands
+
+```bash
+pnpm test
+pnpm test:watch
+```
+
+Use the full package check before release or when touching public types:
+
+```bash
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm typecheck:dev
+pnpm build:dev
+```
+
+## Current Coverage
+
+### Adapter contract suite
+
+`src/adapters/adapter.contract.test.ts` verifies that the built-in local and Supabase adapters:
+
+- support `create`, `list`, `get`, `update`, and `remove`
+- filter by project, route, and status
+- preserve attachments, external links, assignee, and status metadata
+- only return `dom` and `area` review item kinds
+- filter legacy point-note rows instead of showing them in the QA list
+
+The Supabase coverage uses an in-memory PostgREST/RPC mock. It does not contact a real Supabase project.
+
+### Pure function unit suites
+
+Colocated `*.test.ts` files cover the core pure-function modules that refactors depend on:
+
+- `src/core/geometry.test.ts`: coordinate conversion (host/target spaces), clamping, selection shapes, popover placement.
+- `src/core/hotkey.test.ts`: hotkey matching with modifiers, Korean IME key aliases, physical key-code fallback.
+- `src/core/location.test.ts`: page URL building and review-internal query param stripping.
+- `src/core/review/scope.test.ts`: viewport preset matching, scope inference, and item numbering/draft labels.
+- `src/route.test.ts`: route path normalization (`index.html`, query/hash) and item route keys.
+- `src/figma/parse.test.ts`: Figma URL/node-ref parsing, including non-figma host rejection.
+- `src/vite/figma-asset.test.ts`: asset storage key validation, including path traversal rejection, and mime/format helpers.
+- `src/vite/figma-image-store.server.test.ts`: dev middleware request guards — cross-origin (CSRF) rejection, JSON content-type enforcement, body size limit.
+- `src/vite/figma-image-store.image.test.ts`: image store mutation lock ordering, lost-update prevention, and atomic data-file writes.
+- `src/react-shell/source.open.test.ts`: repeated same-source element indexing (`#i/n`) and the per-call document scan cache.
+
+Security-relevant behavior (figma.com host allowlist, asset path traversal guard) is pinned by these tests; keep them green when touching `src/figma/parse.ts` or `src/vite/figma-asset.ts`.
+
+## When to Add Tests
+
+Add or extend Vitest coverage when changing:
+
+- `ReviewItem` shape or adapter normalization
+- localStorage migration behavior
+- Supabase row mapping, RPC payloads, or review URL generation
+- attachment upload contracts
+- status, assignee, or external link fields
+- coordinate/scope/route/parsing helpers listed above (extend the colocated suite)
+
+## Known Behavior Notes
+
+- `getReviewItemScope` (`src/core/review/scope.ts`) intentionally never returns `dom`: a legacy `dom`/`element` scope falls back to viewport-based grouping so those items keep showing markers (marker visibility requires `scope === currentScope`, and the current scope is always a viewport scope). Current code never persists a `dom` scope, so this path only applies to legacy data. `scope.test.ts` pins this behavior.
+
+Use Playwright only for browser-visible shell flows, screenshots, or iframe interaction. Adapter regressions should stay in Vitest because they are faster and easier to run in package CI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@designfever/web-review-kit",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "type": "module",
   "description": "Designfever web page review overlay toolkit.",
   "license": "Apache-2.0",
@@ -45,19 +45,25 @@
     ".env.sample"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/react-shell.tsx src/vite.ts --format esm,cjs --dts --sourcemap --clean --external react --external react-dom --external react/jsx-runtime",
-    "dev": "tsup src/index.ts src/react-shell.tsx src/vite.ts --format esm,cjs --dts --sourcemap --watch --external react --external react-dom --external react/jsx-runtime",
+    "build": "tsup src/index.ts src/react-shell.tsx src/vite.ts --format esm,cjs --dts --sourcemap --clean --external react --external react-dom --external react/jsx-runtime --external zustand",
+    "dev": "tsup src/index.ts src/react-shell.tsx src/vite.ts --format esm,cjs --dts --sourcemap --watch --external react --external react-dom --external react/jsx-runtime --external zustand",
     "dev:review": "vite --config dev/vite.config.ts",
     "build:dev": "vite build --config dev/vite.config.ts",
     "lint:dead-code": "knip",
     "prepare": "pnpm build",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "typecheck:dev": "tsc --noEmit -p tsconfig.dev.json"
   },
+  "dependencies": {
+    "html2canvas": "^1.4.1"
+  },
   "peerDependencies": {
     "react": ">=18",
     "react-dom": ">=18",
-    "vite": ">=5"
+    "vite": ">=5",
+    "zustand": ">=5"
   },
   "peerDependenciesMeta": {
     "vite": {
@@ -69,13 +75,16 @@
     "@types/node": "^26.0.1",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
+    "jsdom": "^29.1.1",
     "knip": "^6.20.0",
     "lucide-react": "^1.20.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "tsup": "^8.3.6",
     "typescript": "^6.0.2",
-    "vite": "^8.0.8"
+    "vite": "^8.0.8",
+    "vitest": "^4.1.9",
+    "zustand": "^5.0.14"
   },
   "packageManager": "pnpm@9.0.0"
 }