@polymorphism-tech/morph-spec 4.8.14 → 4.8.15

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

@@ -0,0 +1,189 @@
+#!/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);

package/framework/skills/level-0-meta/frontend-review/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: frontend-review
+description: Auditoria completa do frontend — valida design outputs (design-system, contraste WCAG,
+  mockups), scan estático de acessibilidade (TSX + Razor), screenshots responsivos em 3
+  breakpoints via Playwright, axe-core a11y em runtime, e SEO (Next.js metadata). Cobre Next.js
+  e Blazor. Disparado ao final do phase-uiux e pós-implementação.
+argument-hint: "[feature-name]"
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep,
+  mcp__playwright__browser_navigate, mcp__playwright__browser_resize,
+  mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot,
+  mcp__playwright__browser_evaluate, mcp__playwright__browser_console_messages
+cliVersion: "4.8.14"
+---
+
+# Frontend Review
+
+> Auditoria completa do frontend: design outputs, acessibilidade estática + runtime, screenshots
+> responsivos e SEO. Disparado ao final do `phase-uiux` (valida design) e pós-implementação
+> (valida código implementado).
+
+> **Nota sobre MCP:** O prefixo `mcp__playwright__` corresponde ao nome do servidor Playwright
+> conforme configurado no `settings.json` do projeto. Se o servidor tiver nome diferente (ex:
+> `plugin_playwright_playwright`), ajuste o prefixo nos calls abaixo.
+
+---
+
+## Step 0 — Detectar Contexto e Stack
+
+```bash
+node .claude/skills/post-implementation/scripts/detect-stack.mjs
+```
+
+Output JSON: `{ stack: "DOTNET" | "NEXTJS" | "FULLSTACK" | "UNKNOWN", frontendPath, backendPath, startCommand }`
+
+Além do stack, determinar o **contexto** examinando o que existe:
+
+```bash
+# Verificar se design outputs existem
+ls .morph/features/$ARGUMENTS/2-ui/ 2>/dev/null
+
+# Verificar se arquivos frontend implementados existem
+find . -name "*.tsx" -o -name "*.razor" 2>/dev/null | head -5
+```
+
+- Se `.morph/features/$ARGUMENTS/2-ui/ui-design-system.md` existe → contexto inclui **design validation**
+- Se arquivos frontend implementados existem (`.tsx`, `.razor`) → contexto inclui **implementation validation**
+- Ambos podem coexistir
+
+Guarde `stack`, `frontendPath`, `startCommand` e o contexto detectado — todos os passos dependem deles.
+
+---
+
+## Step 1 — Validação de Design Outputs (se contexto inclui design validation)
+
+```bash
+npx morph-spec validate-feature $ARGUMENTS --phase uiux
+```
+
+Verificar existência e qualidade dos 4 outputs obrigatórios em `.morph/features/$ARGUMENTS/2-ui/`:
+
+```
+[ ] ui-design-system.md — paleta de cores, tokens de tipografia, espaçamento
+[ ] ui-mockups.md — wireframes com estados responsivos
+[ ] ui-components.md — specs técnicas dos componentes
+[ ] ui-flows.md — jornadas de usuário e edge cases
+[ ] Contraste WCAG AA: cores primárias e de texto ≥ 4.5:1 (verificar ui-design-system.md)
+[ ] Touch targets documentados: ≥ 44x44px para mobile
+[ ] Estados de loading/error/empty definidos nos mockups
+```
+
+**🚫 BLOCK** se `validate-feature` falhar ou outputs obrigatórios ausentes.
+
+Leia `ui-design-system.md` e verifique manualmente se as cores primária e de texto têm razão de
+contraste ≥ 4.5:1. Ferramentas de referência: WebAIM Contrast Checker (critérios WCAG 2.1 AA).
+
+---
+
+## Step 2 — Scan Estático de Acessibilidade
+
+```bash
+node .claude/skills/frontend-review/scripts/scan-accessibility.mjs $frontendPath
+```
+
+O script detecta automaticamente a extensão dos arquivos para determinar Next.js (`.tsx`) vs
+Blazor (`.razor`). Se `frontendPath` não estiver definido, o script usa `.` (raiz do projeto).
+
+**Checks implementados:**
+
+| ID | Severidade | Arquivos | Verifica |
+|----|-----------|---------|---------|
+| `IMG_MISSING_ALT` | CRITICAL | .tsx, .razor | `<img` sem atributo `alt=` |
+| `INPUT_MISSING_LABEL` | HIGH | .tsx, .razor | `<input`/`<InputText`/`<FluentTextField` sem `aria-label`, `aria-labelledby`, ou `<label for=` associado |
+| `HEADING_HIERARCHY` | HIGH | .tsx, .razor | Salto de nível em headings (H1→H3 pulando H2) |
+| `LINK_NO_TEXT` | HIGH | .tsx, .razor | `<a` vazio ou com apenas ícone e sem `aria-label` |
+| `BUTTON_NO_TEXT` | HIGH | .tsx, .razor | `<button`/`<FluentButton` sem texto e sem `aria-label` |
+| `AUTOPLAY_MEDIA` | MEDIUM | .tsx, .razor | `<video`/`<audio` com `autoPlay` sem `muted` |
+| `FLUENT_CHECKBOX_NO_LABEL` | MEDIUM | .razor | `<FluentCheckbox` sem `Label=` |
+
+**🚫 BLOCK** se qualquer finding CRITICAL ou count de HIGH ≥ 3.
+
+Corrija todos os CRITICALs antes de continuar. Para HIGH < 3, registre no resumo como warnings.
+
+---
+
+## Step 3 — Scan de Código Frontend (se contexto inclui implementation validation)
+
+### Se NEXTJS ou FULLSTACK:
+
+```bash
+node .claude/skills/code-review-nextjs/scripts/scan-nextjs.mjs $frontendPath
+```
+
+> Pular se já executado pelo `post-implementation` na mesma sessão.
+
+**🚫 BLOCK** se CRITICAL findings encontrados.
+
+### Se DOTNET ou FULLSTACK (Blazor):
+
+Verificar manualmente as categorias principais do checklist para o feature implementado:
+
+```
+[ ] Componentes Blazor com parâmetros tipados corretamente
+[ ] EventCallback<T> para eventos — sem Action/Func diretos
+[ ] Dispose implementado onde há subscriptions (IDisposable)
+[ ] Sem lógica de negócio nos arquivos .razor (separar em @code ou classes)
+[ ] StateHasChanged() chamado apenas quando necessário
+[ ] Formulários com EditForm e DataAnnotationsValidator
+[ ] Campos obrigatórios com [Required] e mensagens de erro definidas
+```
+
+**🚫 BLOCK** se qualquer item CRITICAL for encontrado.
+
+---
+
+## Step 4 — Screenshots Responsivos (Playwright MCP)
+
+### 4a. Detectar Dev Server
+
+```bash
+node .claude/skills/post-implementation/scripts/detect-dev-server.mjs "$startCommand"
+```
+
+### 4b. Se dev server disponível (exit 0):
+
+Extraia as URLs principais da feature lendo `spec.md`:
+
+```bash
+Read: .morph/features/$ARGUMENTS/1-design/spec.md
+```
+
+Para cada página principal (máximo 3), capture screenshots nos 3 breakpoints:
+
+```javascript
+// Mobile (375px)
+await mcp__playwright__browser_resize({ width: 375, height: 812 });
+await mcp__playwright__browser_navigate({ url: '<url-da-feature>' });
+await mcp__playwright__browser_take_screenshot({
+  type: 'png',
+  filename: `.morph/features/${ARGUMENTS}/visual-screenshots/mobile-<page>.png`
+});
+
+// Tablet (768px)
+await mcp__playwright__browser_resize({ width: 768, height: 1024 });
+await mcp__playwright__browser_navigate({ url: '<url-da-feature>' });
+await mcp__playwright__browser_take_screenshot({
+  type: 'png',
+  filename: `.morph/features/${ARGUMENTS}/visual-screenshots/tablet-<page>.png`
+});
+
+// Desktop (1440px)
+await mcp__playwright__browser_resize({ width: 1440, height: 900 });
+await mcp__playwright__browser_navigate({ url: '<url-da-feature>' });
+await mcp__playwright__browser_take_screenshot({
+  type: 'png',
+  filename: `.morph/features/${ARGUMENTS}/visual-screenshots/desktop-<page>.png`
+});
+```
+
+Screenshots salvos em: `.morph/features/$ARGUMENTS/visual-screenshots/`
+(funciona tanto na fase `2-ui` quanto na `4-implement`)
+
+### 4c. Se dev server NÃO disponível (exit 1):
+
+**⚠️ ATENÇÃO: Dev server não encontrado.**
+
+Solicite confirmação explícita ao usuário antes de pular os screenshots:
+
+```
+Dev server não detectado. Screenshots responsivos via Playwright não podem ser capturados.
+
+Opções:
+1. Inicie manualmente o servidor e re-execute /frontend-review
+2. Confirme explicitamente que deseja pular os screenshots e por quê
+
+Não é possível prosseguir para axe-core sem dev server.
+```
+
+**Aguarde resposta antes de continuar.**
+
+---
+
+## Step 5 — axe-core Runtime (Playwright MCP, se dev server ativo)
+
+Para cada página da feature (usar as mesmas URLs do Step 4):
+
+```javascript
+// Navegar para a página
+await mcp__playwright__browser_navigate({ url: '<url-da-feature>' });
+
+// Injetar axe-core via CDN e executar scan WCAG 2.1 AA
+await mcp__playwright__browser_evaluate({
+  function: `async () => {
+    if (!window.axe) {
+      await new Promise((resolve, reject) => {
+        const s = document.createElement('script');
+        s.src = 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.9.1/axe.min.js';
+        s.onload = resolve;
+        s.onerror = reject;
+        document.head.appendChild(s);
+      });
+    }
+    const results = await window.axe.run(document, {
+      runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa'] }
+    });
+    return results.violations.map(v => ({
+      id: v.id,
+      impact: v.impact,
+      description: v.description,
+      nodes: v.nodes.length,
+      helpUrl: v.helpUrl
+    }));
+  }`
+});
+```
+
+Agrupar violations por impacto:
+- `critical` / `serious` → **🚫 BLOCK** (não criar PR)
+- `moderate` / `minor` → reportar como warnings no resumo, não bloqueiam
+
+Verificar também erros de console relacionados a acessibilidade:
+
+```javascript
+await mcp__playwright__browser_console_messages({ level: 'error' });
+```
+
+---
+
+## Step 6 — SEO Check (Next.js only)
+
+Varrer arquivos `page.tsx` da feature para verificar metadata:
+
+```bash
+# Buscar páginas da feature
+find . -name "page.tsx" -path "*$ARGUMENTS*" 2>/dev/null
+
+# Verificar se têm metadata
+grep -l "export const metadata\|export async function generateMetadata" $(find . -name "page.tsx" -path "*$ARGUMENTS*" 2>/dev/null)
+```
+
+Checklist por página:
+
+```
+[ ] export const metadata com title e description
+[ ] og:title e og:description (Open Graph)
+[ ] og:image definida (para compartilhamento social)
+[ ] Sem título duplicado entre páginas
+[ ] robots não bloqueia indexação das páginas públicas
+```
+
+> SEO não bloqueia PR — reportar como warnings no resumo final.
+
+---
+
+## Step 7 — Checklist de Design Responsivo
+
+Após visualizar os screenshots do Step 4:
+
+```
+[ ] Mobile (375px): sem scroll horizontal, botões ≥ 44px, texto legível
+[ ] Tablet (768px): layout adapta (sidebar colapsa, grid ajusta colunas)
+[ ] Desktop (1440px): aproveita espaço disponível, sem conteúdo esticado
+[ ] Navegação funciona em todos os breakpoints
+[ ] Formulários acessíveis em mobile (labels visíveis, inputs grandes o suficiente)
+```
+
+Se screenshots não foram capturados (dev server indisponível), marcar como "não verificado" e
+registrar no resumo.
+
+---
+
+## Step 8 — Resumo e Artefatos
+
+Criar arquivo de resumo consolidado:
+
+```bash
+mkdir -p ".morph/features/$ARGUMENTS/visual-screenshots"
+```
+
+Salvar em `.morph/features/$ARGUMENTS/visual-screenshots/frontend-review-summary.md`:
+
+```markdown
+# Frontend Review — {feature}
+
+**Data:** {data}
+**Stack:** {stack detectado}
+**Contexto:** design validation | implementation validation | ambos
+
+## Resultados
+
+### Step 1 — Design Outputs
+- validate-feature: ✅ PASS / 🚫 BLOCK
+- Outputs verificados: ui-design-system.md, ui-mockups.md, ui-components.md, ui-flows.md
+- Contraste WCAG: {resultado}
+
+### Step 2 — Scan de Acessibilidade Estática
+- Arquivos escaneados: {N}
+- Findings: {total} ({CRITICAL: N, HIGH: N, MEDIUM: N})
+- Status: ✅ PASS / 🚫 BLOCK
+
+### Step 3 — Scan de Código Frontend
+- Status: ✅ PASS / 🚫 BLOCK / ⏭️ pulado (já executado)
+
+### Step 4 — Screenshots Responsivos
+- Mobile (375px): {paths ou "não capturado"}
+- Tablet (768px): {paths ou "não capturado"}
+- Desktop (1440px): {paths ou "não capturado"}
+
+### Step 5 — axe-core Runtime
+- Violations críticas/sérias: {N} → ✅ / 🚫
+- Warnings (moderate/minor): {N}
+
+### Step 6 — SEO (Next.js)
+- Páginas com metadata: {N}/{total}
+- Gaps: {lista ou "nenhum"}
+
+## Status Geral
+
+**{✅ PASS / 🚫 BLOCK}**
+
+{Se BLOCK: motivo(s) listados aqui}
+```
+
+---
+
+## Resumo dos BLOCKs
+
+| Step | Condição de BLOCK |
+|------|-------------------|
+| Step 1 | `validate-feature` falhou ou outputs obrigatórios ausentes |
+| Step 2 | Qualquer finding CRITICAL ou HIGH ≥ 3 no scan estático |
+| Step 3 | Qualquer finding CRITICAL no scan de código |
+| Step 5 | Dev server ativo + axe-core violations `critical` ou `serious` |
+
+**Todos os BLOCKs devem ser resolvidos antes de criar o PR (quando executado pós-implementação).**
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*