@polymorphism-tech/morph-spec 4.21.0 → 5.0.1

package/framework/skills/level-0-meta/morph-code-review-nextjs/SKILL.md

@@ -1,165 +0,0 @@
----
-name: morph-code-review-nextjs
-description: Next.js code review checklist covering naming conventions, component architecture (Server vs Client), data fetching patterns, form implementation, state management, TypeScript/Zod discipline, feature boundaries, and testing. Use after implementing Next.js code, before creating PRs, or when reviewing TSX/TS code for compliance with MORPH-SPEC Next.js standards.
-user-invocable: true
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-stacks:
-  - nextjs
----
-
-# Next.js Code Review Checklist
-
-> Comprehensive checklist for Next.js code review: naming, component architecture, data fetching, forms, state, TypeScript, structure, and testing.
-> **Ref:** `framework/standards/frontend/nextjs/naming-conventions.md`
-> **Ref:** `framework/standards/frontend/nextjs/app-router.md`
-> **Ref:** `framework/standards/frontend/nextjs/components.md`
-> **Ref:** `framework/standards/frontend/nextjs/data-fetching.md`
-> **Ref:** `framework/standards/frontend/nextjs/forms.md`
-> **Ref:** `framework/standards/frontend/nextjs/state-management.md`
-> **Ref:** `framework/standards/frontend/nextjs/testing.md`
-> **Example:** `references/review-example-nextjs.md` — filled-in review showing expected finding format.
-> **Script:** `scripts/scan-nextjs.mjs` — automated scan for CRITICAL/HIGH violations before manual review.
-> **Ref:** `.claude/skills/morph-code-review/references/review-guidelines.md` — false-positive rubric, confidence scoring, evidence format.
-
----
-
-## Step 0 — Eligibility Check
-
-```bash
-git diff --name-only main...HEAD -- "*.tsx" "*.ts" | wc -l
-```
-
-**Skip review if:**
-- 0 `.tsx`/`.ts` files changed → no frontend code to review
-- Only changes in `*.json`, `*.md`, config files → infrastructure scope
-- `.morph/features/$ARGUMENTS/5-implement/code-review-nextjs.md` already exists from today → already reviewed
-
-If skipping: output `"Skipping code-review-nextjs: [reason]"` and stop.
-
----
-
-## Step 1 — Run automated scan first
-
-```bash
-node scripts/scan-nextjs.mjs src/
-```
-
-Review and address CRITICAL findings before proceeding with the manual checklist below. Warnings can be addressed during review.
-
----
-
-## Naming & Style (ref: naming-conventions.md)
-
-- [ ] `[CRITICAL]` File names use kebab-case (`user-card.tsx`, NOT `UserCard.tsx`)
-- [ ] `[HIGH]` Components exported as named exports (`export function UserCard`, NOT `export default function UserCard`)
-- [ ] `[HIGH]` Hook files named `use-{action}.ts` and export `use{Action}()`
-- [ ] `[HIGH]` Schema files named `{feature}.schemas.ts` with Zod exports
-- [ ] `[HIGH]` Type files named `{feature}.types.ts` with `z.infer<>` derived types
-- [ ] `[MEDIUM]` No abbreviations in public API names (`repository` not `repo`)
-- [ ] `[MEDIUM]` Feature folder uses kebab-case (`features/user-management/`, NOT `features/userManagement/`)
-
----
-
-## Component Architecture (ref: app-router.md, components.md)
-
-### Server vs Client Discipline
-- [ ] `[CRITICAL]` `'use client'` only on components that use hooks or event handlers
-- [ ] `[CRITICAL]` No `useEffect(() => { fetch(...) }, [])` for data fetching — use Server Components or TanStack Query
-- [ ] `[HIGH]` Server Components used for initial page data (no `'use client'` on page files)
-- [ ] `[HIGH]` `loading.tsx`, `error.tsx` co-located with every `page.tsx`
-- [ ] `[HIGH]` No business logic in `app/` route files — import from `features/`
-
-### Three-Tier Hierarchy
-- [ ] `[CRITICAL]` No edits to `components/ui/` files — shadcn primitives are never modified
-- [ ] `[HIGH]` `components/` (Tier 2) has no imports from `features/` — no domain knowledge
-- [ ] `[HIGH]` Feature components (`features/*/components/`) do not import from other features
-- [ ] `[MEDIUM]` Feature cross-dependencies extracted to `components/` or `lib/`
-
----
-
-## Data Fetching (ref: data-fetching.md)
-
-- [ ] `[CRITICAL]` No `useEffect` + `useState` pattern for API data — use `useQuery`
-- [ ] `[HIGH]` TanStack Query v5 syntax: `useQuery({ queryKey: [...], queryFn: async () => {} })`
-- [ ] `[HIGH]` Query key factory pattern used (`userKeys.lists()`, NOT hardcoded `['users']`)
-- [ ] `[HIGH]` `useMutation` used for POST/PUT/DELETE — not inline `fetch` in handlers
-- [ ] `[HIGH]` API responses validated with Zod before use
-- [ ] `[MEDIUM]` `onSuccess` in `useMutation` invalidates relevant query keys
-- [ ] `[MEDIUM]` `QueryClientProvider` wraps app in `app/layout.tsx`, not per-component
-
----
-
-## Forms (ref: forms.md)
-
-- [ ] `[CRITICAL]` Zod schema defined BEFORE TypeScript type — type derived with `z.infer<>`
-- [ ] `[HIGH]` `useForm` uses `zodResolver(schema)` — NOT manual validation
-- [ ] `[HIGH]` shadcn `<Form>`, `<FormField>`, `<FormItem>`, `<FormLabel>`, `<FormControl>`, `<FormMessage>` used
-- [ ] `[HIGH]` Form submission uses `useMutation` — NOT direct `fetch` in `onSubmit`
-- [ ] `[MEDIUM]` `isPending` used for loading state — NOT `isLoading` (v5 renamed)
-- [ ] `[MEDIUM]` Root-level errors displayed: `form.formState.errors.root`
-- [ ] `[MEDIUM]` No `useState` for individual form fields — react-hook-form handles this
-
----
-
-## State Management (ref: state-management.md)
-
-- [ ] `[HIGH]` No Zustand/Redux installed without documented justification
-- [ ] `[HIGH]` No React Context used for server state (API data) — use TanStack Query
-- [ ] `[MEDIUM]` Local UI state (open/closed, selected) in `useState` — not global store
-- [ ] `[MEDIUM]` Context only for truly global UI: theme, auth user, locale
-- [ ] `[LOW]` No prop drilling beyond 3 levels — consider Context or co-location
-
----
-
-## TypeScript Discipline
-
-- [ ] `[CRITICAL]` No `any` type — use `unknown` and narrow, or fix the actual type
-- [ ] `[HIGH]` Types derived from Zod schemas (`type User = z.infer<typeof userSchema>`)
-- [ ] `[HIGH]` No duplicate type definitions — if the server returns it, define it once with Zod
-- [ ] `[MEDIUM]` API response types come from the shared schema, not manually written
-- [ ] `[MEDIUM]` `noUncheckedIndexedAccess` respected — array accesses use optional chaining
-- [ ] `[LOW]` No type assertions (`as User`) without validation
-
----
-
-## Feature Structure (ref: project-structure.md)
-
-- [ ] `[HIGH]` Feature exposes public API via `features/{name}/index.ts` — no deep path imports
-- [ ] `[HIGH]` Consumers import from index: `from '@/features/users'` NOT `from '@/features/users/components/user-list'`
-- [ ] `[MEDIUM]` New features create: `components/`, `hooks/`, `types/` subdirectories
-- [ ] `[MEDIUM]` TanStack Query hooks in `features/{name}/hooks/` — NOT co-located with components
-- [ ] `[MEDIUM]` Zod schemas in `features/{name}/types/{name}.schemas.ts`
-- [ ] `[LOW]` Feature index only exports what external consumers actually need (no over-exposure)
-
----
-
-## Testing (ref: testing.md)
-
-- [ ] `[HIGH]` Test files co-located with source (`user-card.test.tsx` next to `user-card.tsx`)
-- [ ] `[HIGH]` `@testing-library/user-event` used — NOT `fireEvent`
-- [ ] `[HIGH]` API calls mocked with MSW — NOT `jest.mock('fetch')` or `global.fetch = jest.fn()`
-- [ ] `[MEDIUM]` Hook tests use `QueryClientWrapper` helper with `retry: false`
-- [ ] `[MEDIUM]` Tests cover happy path + one error path per component
-- [ ] `[LOW]` No snapshot tests — use `expect(screen.getByText(...))`
-
----
-
-## Quick Pre-Merge Checklist
-
-```
-[ ] node scripts/scan-nextjs.mjs src/ — 0 CRITICAL findings
-[ ] File names are kebab-case (UserCard.tsx → user-card.tsx)
-[ ] 'use client' only on interactive components (hooks or event handlers)
-[ ] No useEffect for data fetching — Server Component or useQuery
-[ ] Zod schema defined first, type derived with z.infer<>
-[ ] zodResolver connected to useForm, useMutation for submit
-[ ] Query key factory used (userKeys.lists() not ['users'])
-[ ] Feature public API via features/{name}/index.ts
-[ ] components/ui/ files untouched (shadcn CLI only)
-[ ] Tests: userEvent not fireEvent, MSW not mock fetch
-```
-
----
-
-*Covers: naming-conventions.md + app-router.md + components.md + data-fetching.md + forms.md + state-management.md + testing.md + project-structure.md*
-*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-0-meta/morph-code-review-nextjs/references/review-example-nextjs.md

@@ -1,254 +0,0 @@
-# Code Review Report — User Management Feature
-
-> Example of a well-structured Next.js code review output. Filled-in reference — not a template.
-
-**Scope:** `src/features/users/` + `src/app/(dashboard)/users/page.tsx`
-**Date:** 2026-02-23
-**Reviewer:** code-review-nextjs skill
-
----
-
-## Automated Scan Results
-
-```bash
-$ node scripts/scan-nextjs.mjs src/features/users/
-
-CRITICAL (1)
-  features/users/components/UserList.tsx:1  — React hooks used (useState) without 'use client'
-
-HIGH/MEDIUM (2)
-  features/users/components/UserList.tsx  — PascalCase filename (should be user-list.tsx)
-  features/users/components/user-form.tsx — 'use client' directive present but no interactivity detected
-
-Summary: 8 files scanned | 3 issues (1 critical, 2 high/medium)
-```
-
----
-
-## Findings by Severity
-
-| Severity | Count |
-|----------|-------|
-| CRITICAL | 2 |
-| HIGH | 3 |
-| MEDIUM | 2 |
-| LOW | 1 |
-
----
-
-### [CRITICAL] Missing 'use client' on interactive component
-
-**File:** `src/features/users/components/UserList.tsx:1`
-
-**Current code:**
-```tsx
-import { useState } from 'react';
-
-export function UserList() {
-  const [selected, setSelected] = useState<string | null>(null);
-  return <div onClick={() => setSelected('test')}>...</div>;
-}
-```
-
-**Suggested fix:**
-```tsx
-'use client';
-
-import { useState } from 'react';
-// ... rest unchanged
-```
-
-**Why:** React hooks (`useState`) require `'use client'`. Without it, Next.js treats this as a Server Component and the `useState` call fails at runtime.
-
----
-
-### [CRITICAL] useEffect for data fetching
-
-**File:** `src/features/users/components/user-list.tsx:8`
-
-**Current code:**
-```tsx
-'use client';
-import { useEffect, useState } from 'react';
-
-export function UserList() {
-  const [users, setUsers] = useState([]);
-  useEffect(() => {
-    fetch('/api/users').then(r => r.json()).then(setUsers);
-  }, []);
-  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
-}
-```
-
-**Suggested fix:**
-```tsx
-// Option A — Server Component (no 'use client' needed)
-// app/(dashboard)/users/page.tsx
-async function getUsers() {
-  const res = await fetch(`${process.env.API_URL}/api/users`, { next: { revalidate: 30 } });
-  return res.json();
-}
-export default async function UsersPage() {
-  const users = await getUsers();
-  return <UserList initialData={users} />;
-}
-
-// Option B — TanStack Query (when client interactivity needed)
-'use client';
-import { useUsers } from '@/features/users/hooks/use-users';
-export function UserList() {
-  const { data: users = [], isLoading } = useUsers();
-  if (isLoading) return <div>Loading...</div>;
-  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
-}
-```
-
-**Why:** `useEffect` + `useState` for fetching: (1) doubles renders, (2) no caching, (3) no SSR, (4) no error/loading states, (5) can't be cancelled. TanStack Query or Server Components solve all five.
-
----
-
-### [HIGH] PascalCase file name
-
-**File:** `src/features/users/components/UserList.tsx`
-
-**Suggested fix:** Rename to `user-list.tsx`
-
-**Why:** Linux servers are case-sensitive. `UserList.tsx` and `user-list.tsx` are different files on the server but the same on macOS/Windows, causing import failures in production.
-
----
-
-### [HIGH] Default export on non-page component
-
-**File:** `src/features/users/components/user-card.tsx:3`
-
-**Current code:**
-```tsx
-export default function UserCard({ user }: { user: User }) {
-```
-
-**Suggested fix:**
-```tsx
-export function UserCard({ user }: { user: User }) {
-```
-
-**Why:** Named exports are refactor-safe — IDEs track renames automatically. Default exports are anonymous in imports (`import X from './user-card'` allows `X` to be anything).
-
----
-
-### [HIGH] Type defined manually instead of deriving from Zod schema
-
-**File:** `src/features/users/types/user.types.ts:1`
-
-**Current code:**
-```ts
-export type User = {
-  id: string;
-  name: string;
-  email: string;
-  role: 'admin' | 'user';
-};
-```
-
-**Suggested fix:**
-```ts
-// user.schemas.ts — single source of truth
-export const userSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  email: z.string().email(),
-  role: z.enum(['admin', 'user']),
-});
-
-// user.types.ts — derived, never written manually
-export type User = z.infer<typeof userSchema>;
-```
-
-**Why:** Manually written types drift from API responses. `z.infer<>` ensures the TypeScript type is always in sync with the runtime validation.
-
----
-
-### [MEDIUM] Deep path import instead of feature index
-
-**File:** `src/app/(dashboard)/users/page.tsx:2`
-
-**Current code:**
-```tsx
-import { UserList } from '@/features/users/components/user-list';
-```
-
-**Suggested fix:**
-```tsx
-import { UserList } from '@/features/users';
-```
-
-**Why:** Deep path imports expose internal structure. When `user-list.tsx` moves or is renamed, every consumer breaks. The feature index is the stable public API.
-
----
-
-### [MEDIUM] Query key not using factory pattern
-
-**File:** `src/features/users/hooks/use-users.ts:8`
-
-**Current code:**
-```ts
-return useQuery({
-  queryKey: ['users'],
-```
-
-**Suggested fix:**
-```ts
-// query-keys.ts
-export const userKeys = {
-  all: ['users'] as const,
-  lists: () => [...userKeys.all, 'list'] as const,
-};
-
-// use-users.ts
-return useQuery({
-  queryKey: userKeys.lists(),
-```
-
-**Why:** Hardcoded `['users']` cannot be selectively invalidated. `queryClient.invalidateQueries({ queryKey: userKeys.lists() })` correctly invalidates only list queries, not detail queries with the same prefix.
-
----
-
-### [LOW] Test uses fireEvent instead of userEvent
-
-**File:** `src/features/users/components/user-card.test.tsx:14`
-
-**Current code:**
-```tsx
-fireEvent.click(screen.getByRole('button', { name: /edit/i }));
-```
-
-**Suggested fix:**
-```tsx
-await userEvent.click(screen.getByRole('button', { name: /edit/i }));
-```
-
-**Why:** `fireEvent.click` dispatches a synthetic event. `userEvent.click` simulates the full browser interaction sequence (pointerdown, mousedown, focus, click, etc.) — closer to real user behaviour.
-
----
-
-## Top Priorities
-
-1. `UserList.tsx:1` — CRITICAL missing `'use client'` (2 min fix)
-2. `user-list.tsx:8` — CRITICAL useEffect fetch → useQuery (15 min)
-3. `UserList.tsx` — HIGH rename to `user-list.tsx` (2 min)
-4. `user-card.tsx:3` — HIGH named export (2 min)
-5. `user.types.ts:1` — HIGH derive from Zod (10 min)
-
----
-
-## Passed Checks ✅
-
-- `components/ui/` files untouched
-- `zodResolver` correctly wired in `user-form.tsx`
-- `isPending` used (v5 correct — not `isLoading`)
-- `loading.tsx` and `error.tsx` present in `app/(dashboard)/users/`
-- Feature has `index.ts` re-exporting public API
-- Test file co-located with component
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-0-meta/morph-code-review-nextjs/scripts/scan-nextjs.mjs

@@ -1,189 +0,0 @@
-#!/usr/bin/env node
-/**
- * scan-nextjs.mjs
- *
- * Scans .tsx/.ts files for MORPH-SPEC Next.js coding standard violations.
- * Executed locally by Claude via Bash — output returned to Claude.
- *
- * Usage:
- *   node scan-nextjs.mjs [path]                  # scan directory or file
- *   node scan-nextjs.mjs src/                    # scan src/ recursively
- *   node scan-nextjs.mjs --summary               # counts only, no details
- *   node scan-nextjs.mjs --diff                  # scan only changed files (git diff main...HEAD)
- *   node scan-nextjs.mjs --diff --base=develop   # use different base branch
- *
- * Checks (ref: framework/standards/frontend/nextjs/):
- *   - Non-PascalCase component files      → MyComponent.tsx, not myComponent.tsx
- *   - Explicit `any` type annotations     → avoid untyped code
- *   - useEffect with fetch inside         → use TanStack Query instead
- *   - Importing from components/ui/       → use shadcn/ui without modification
- *   - useMutation calling fetch directly  → use api client utilities
- */
-
-import { readdirSync, readFileSync, statSync, existsSync } from 'fs';
-import { join, extname, basename, relative } from 'path';
-import { execSync } from 'child_process';
-
-const args = process.argv.slice(2);
-const diffMode = args.includes('--diff');
-const summaryOnly = args.includes('--summary');
-const baseBranch = args.find(a => a.startsWith('--base='))?.split('=')[1] ?? 'main';
-const targetPath = args.find(a => !a.startsWith('--')) ?? '.';
-
-const CHECKS = [
-  {
-    id: 'NON_PASCAL_CASE_COMPONENT',
-    severity: 'CRITICAL',
-    fileLevel: true,
-    check: (filePath) => {
-      const name = basename(filePath, extname(filePath));
-      // Only check files that look like components (exclude lowercase utils/hooks/types)
-      if (!filePath.endsWith('.tsx')) return null;
-      // Skip files starting with lowercase (could be utils)
-      if (/^[a-z]/.test(name) && !name.includes('-') && !name.includes('.')) return null;
-      // Flag kebab-case or non-PascalCase component files
-      if (name.includes('-') || /^[a-z]/.test(name)) {
-        return `Component file '${name}.tsx' is not PascalCase → rename to '${toPascalCase(name)}.tsx'`;
-      }
-      return null;
-    },
-  },
-  {
-    id: 'EXPLICIT_ANY_TYPE',
-    severity: 'CRITICAL',
-    pattern: /:\s*any\b(?!\s*\[)/g,
-    message: (m, line) => `Explicit 'any' type annotation on line ${line} → use proper TypeScript type`,
-  },
-  {
-    id: 'USE_EFFECT_FETCH',
-    severity: 'CRITICAL',
-    pattern: /useEffect\s*\(\s*\(\s*\)\s*=>\s*\{[^}]*fetch\s*\(/gs,
-    message: () => 'useEffect with fetch() inside → use TanStack Query (useQuery/useMutation) instead',
-  },
-  {
-    id: 'COMPONENTS_UI_IMPORT_MODIFIED',
-    severity: 'CRITICAL',
-    pattern: /from\s+['"](?:@\/|\.\.\/)*components\/ui\/(\w+)['"]/g,
-    message: (m) => `Import from 'components/ui/${m[1]}' — do not modify shadcn/ui components directly; extend via composition instead`,
-  },
-  {
-    id: 'USE_MUTATION_FETCH',
-    severity: 'HIGH',
-    pattern: /useMutation\s*\(\s*\{[^}]*mutationFn[^}]*fetch\s*\(/gs,
-    message: () => 'useMutation with direct fetch() call → use a typed API client utility function instead',
-  },
-];
-
-function toPascalCase(str) {
-  return str
-    .replace(/-([a-z])/g, (_, c) => c.toUpperCase())
-    .replace(/^[a-z]/, (c) => c.toUpperCase());
-}
-
-function collectTsFiles(dir) {
-  if (!existsSync(dir)) return [];
-  const stat = statSync(dir);
-  if (stat.isFile()) {
-    const ext = extname(dir);
-    return ext === '.tsx' || ext === '.ts' ? [dir] : [];
-  }
-  const results = [];
-  const ignored = ['node_modules', '.git', '.next', 'dist', 'build', '.turbo'];
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    if (entry.isDirectory() && !ignored.includes(entry.name)) {
-      results.push(...collectTsFiles(join(dir, entry.name)));
-    } else if (entry.isFile()) {
-      const ext = extname(entry.name);
-      if (ext === '.tsx' || ext === '.ts') {
-        results.push(join(dir, entry.name));
-      }
-    }
-  }
-  return results;
-}
-
-function getChangedFiles(base) {
-  try {
-    const raw = execSync(`git diff --name-only ${base}...HEAD`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
-    return raw.split('\n')
-      .map(f => f.trim())
-      .filter(f => (f.endsWith('.ts') || f.endsWith('.tsx')) && existsSync(f));
-  } catch {
-    return null;
-  }
-}
-
-let mode = 'full';
-let files;
-if (diffMode) {
-  const changed = getChangedFiles(baseBranch);
-  if (changed !== null) {
-    files = changed;
-    mode = 'diff';
-  } else {
-    files = collectTsFiles(targetPath);
-  }
-} else {
-  files = collectTsFiles(targetPath);
-}
-
-const findings = [];
-
-for (const file of files) {
-  const content = readFileSync(file, 'utf-8');
-  const lines = content.split('\n');
-  const relFile = relative(process.cwd(), file).replace(/\\/g, '/');
-
-  for (const check of CHECKS) {
-    if (check.fileLevel) {
-      const msg = check.check(file);
-      if (msg) {
-        findings.push({
-          severity: check.severity,
-          id: check.id,
-          file: relFile,
-          line: 1,
-          message: msg,
-          snippet: '',
-        });
-      }
-      continue;
-    }
-
-    const regex = new RegExp(check.pattern.source, check.pattern.flags);
-    let match;
-    while ((match = regex.exec(content)) !== null) {
-      const lineNum = content.slice(0, match.index).split('\n').length;
-      const msg = check.message(match, lineNum);
-      if (!msg) continue;
-      findings.push({
-        severity: check.severity,
-        id: check.id,
-        file: relFile,
-        line: lineNum,
-        message: msg,
-        snippet: lines[lineNum - 1]?.trim().slice(0, 100),
-      });
-    }
-  }
-}
-
-const bySeverity = { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0 };
-for (const f of findings) bySeverity[f.severity] = (bySeverity[f.severity] ?? 0) + 1;
-
-const summary = {
-  scanned: files.length,
-  findings: findings.length,
-  bySeverity,
-  clean: findings.length === 0,
-  mode,
-  ...(mode === 'diff' && { baseBranch, changedFilesCount: files.length }),
-};
-
-if (summaryOnly) {
-  console.log(JSON.stringify(summary, null, 2));
-} else {
-  console.log(JSON.stringify({ summary, findings }, null, 2));
-}
-
-process.exit(findings.some(f => f.severity === 'CRITICAL') ? 1 : 0);