Skill: Architecture Audit

Analyse le code source pour détecter les écarts avec l'architecture documentée.

Objectif

Comparer l'implémentation réelle du codebase avec les règles définies dans ${CLAUDE_PLUGIN_ROOT}/blueprints/architecture/ et identifier les violations.

Prérequis

Lire les blueprints de référence embarqués dans le plugin :

• ${CLAUDE_PLUGIN_ROOT}/blueprints/architecture/frontend.md
• ${CLAUDE_PLUGIN_ROOT}/blueprints/architecture/backend.md
• ${CLAUDE_PLUGIN_ROOT}/blueprints/architecture/typing.md
• ${CLAUDE_PLUGIN_ROOT}/blueprints/architecture/tools.md
• ${CLAUDE_PLUGIN_ROOT}/blueprints/architecture/tests.md

Les chemins de code audités (src/, netlify/) sont relatifs à la racine du projet analysé.

Exécution

Sur un projet de taille non triviale, déléguer à l'agent architecture-auditor (read-only) plutôt que de tout lire soi-même. Il peut tourner en parallèle de design-auditor et clean-code-auditor si un audit complet est demandé.

Règles d'Audit

Frontend (FE-*)

Backend (BE-*)

Typage (TY-*)

Code (CD-*)

Configuration TypeScript (CFG-*)

strict: true n'active que huit options. Les cinq suivantes n'en font pas partie et sont celles qui attrapent ce que « strict » laisse passer. Toutes se lisent dans tsconfig.json.

Tests (TE-*)

Outillage (TL-*)

Un outil manquant ne produit aucune erreur : le projet compile et la règle qu'il aurait fait respecter n'existe simplement pas. C'est le seul domaine où l'audit doit chercher une absence.

Commandes de Détection

FE-001: Complexité des Hooks

grep -r "useEffect" src/hooks/ --include="*.ts" --include="*.tsx"
grep -r "useState.*useState" src/hooks/ --include="*.ts" --include="*.tsx"

FE-002: Réseau dans Contexts

grep -rE "(fetch|honoClient)" src/contexts/ --include="*.ts" --include="*.tsx"

FE-003: Isolation Services

grep -rE "from '.*/components|from '.*/hooks|from '.*/contexts|from '.*/pages" src/services/ --include="*.ts" --include="*.tsx"

FE-004: honoClient Type Inférence

grep -rE "honoClient\.(get|post|patch|delete|upload)<" src/hooks/ --include="*.ts" --include="*.tsx"

FE-005: res.ok Check

grep -rE "(json\.success|!json\.success|\.success)" src/hooks/ --include="*.ts"

FE-006: Export FromApi Types

grep -rE "export type \w+FromApi" src/hooks/ --include="*.ts"

FE-007: Composants sans appels réseau

grep -rE "(fetch\(|honoClient\.)" src/components/ --include="*.ts" --include="*.tsx"

FE-008: Layouts sans props

grep -rE "export const \w+Layout = \(\{[^}]*\}:" src/layouts/ --include="*.tsx" | grep -v "children"

FE-009: Une page = une route

grep -rE "<Route.*element=\{<\w+Page" src/routes/ --include="*.tsx"

FE-010: Pas de navigation dans les hooks data

grep -rE "(useNavigate|navigate\(|toast\(|toast\.)" src/hooks/data/ --include="*.ts"

FE-011: Pas d'état local dans hooks data

grep -rE "useState\(" src/hooks/data/ --include="*.ts"

FE-012 / FE-013 : frontière services → composants

# Les imports de VALEUR seuls : ce sont eux qui couplent à l'exécution.
grep -rnE "from '[^']*services/" src/components/ src/pages/ src/layouts/ | grep -v ":import type"

# Le compte total, pour situer la part type-only (admissible).
grep -rnE "from '[^']*services/" src/components/ src/pages/ src/layouts/ | wc -l

# FE-013 : le re-export qui rend le grep ci-dessus aveugle.
grep -rnE "^export \{" src/hooks/

⚠️ Rapporter les deux nombres. Un audit qui additionne import type et imports de valeur surestime la dette et fait rater la vraie question : d'où vient le helper, et où devrait-il vivre (cf. frontend.md, « Le discriminant utils/ ou services/ »).

BE-001: Method chaining Hono RPC

# Chercher routes séparées (perte d'inférence)
grep -rE "^\w+\.(get|post|patch|delete)\(" netlify/routes/ --include="*.ts"

BE-002: Validation Zod manquante

grep -rE "\.(post|patch)\(" netlify/routes/ --include="*.ts" | grep -v "zValidator"

BE-003: Champ success dans réponses HTTP

grep -rE "c\.json\(.*success" netlify/routes/ --include="*.ts"

BE-004: Return types explicites

grep -rE "\): Promise<" netlify/routes/ netlify/lib/ --include="*.ts"

TY-003: Duplication Types Frontend

# Chercher des interfaces qui dupliquent le schéma Drizzle dans src/types/
grep -rE "^export interface" src/types/ --include="*.ts"

CD-001: Named exports uniquement

grep -rE "^export default" src/ netlify/ --include="*.ts" --include="*.tsx" | grep -v "/pages/"

CD-002: Pas d'any explicite

grep -rE "(: any|as any|<any>)" src/ netlify/ --include="*.ts" --include="*.tsx"

TL-001 / TL-003 / TL-004 : présence des outils

ls eslint.config.* .prettierrc* knip.json 2>/dev/null
jq -r '[.devDependencies,.dependencies|objects|keys[]]|map(select(test("eslint|prettier|knip")))|sort|join(" ")' package.json

TL-002 : linting TypeScript réellement branché

# La config fait foi, pas la dépendance : le package peut être installé sans être utilisé
grep -E "typescript-eslint|tseslint|@typescript-eslint" eslint.config.*

TL-005 / TL-006 / TL-007 / TL-008 : scripts et hook

jq -r '.scripts | to_entries[] | select(.key|test("^(check|deep-check|lint|typecheck|format|knip|test|security|prepare)$")) | "\(.key): \(.value)"' package.json
ls -la .husky/ 2>/dev/null

TL-014 : security hors des chaînes bloquantes

# Doit être défini, et n'apparaître dans AUCUNE des trois.
jq -r '.scripts | .check, .["deep-check"]' package.json | grep -n security
grep -rn "security" .husky/ 2>/dev/null

Défini mais absent des trois = PASS. Présent dans check, deep-check ou le hook = FAIL.

BE-007 : secret avec valeur de repli

grep -rnE "process\.env\.[A-Z_]+ *(\|\||\?\?) *['\"]" netlify/ src/

⚠️ Trier ce que la commande remonte : un repli sur une URL de développement (process.env.URL ?? 'http://localhost:8888') est légitime ; un repli sur un secret (signature, identifiants, clés) ne l'est jamais.

TL-010 / TL-011 / TL-012 : preset et garde-fou de taille

# Cibler tseslint uniquement : `js.configs.recommended` est attendu dans la config canonique
grep -nE "tseslint\.configs\.[a-zA-Z]+" eslint.config.*
grep -nE "max-lines" eslint.config.*        # présence, seuil, et tout 'off'

CFG-001 à CFG-008 : options du compilateur

jq -r '.compilerOptions | to_entries[] | select(.key|test("strict|noUnused|noImplicit|noUnchecked|exactOptional|noFallthrough|verbatim|noProperty")) | "\(.key)=\(.value)"' tsconfig.json
ls tsconfig*.json          # CFG-008 : plus d'un fichier = configs séparées

TE-001 à TE-007 : tests et couverture

jq -r '[(.devDependencies//{})|keys[]|select(test("vitest|playwright|testing-library|coverage"))]|join(" ")' package.json
jq -r '.scripts|to_entries[]|select(.key|test("^test"))|"\(.key): \(.value)"' package.json
grep -nE "thresholds|coverage" vitest.config.* vite.config.* 2>/dev/null
find . -name "*.test.ts" -o -name "*.test.tsx" | grep -v node_modules | wc -l

TL-013 : désactivations répétées

grep -rhoE "eslint-disable[a-z-]* +[@a-z/-]+" src/ netlify/ | sort | uniq -c | sort -rn | head

Fichiers qui dépassent le seuil

find src/ netlify/ -name "*.ts" -o -name "*.tsx" | xargs wc -l | sort -rn | head -20

Classification des Sévérités

Format de Rapport

Le rapport généré doit inclure :

1. Résumé — Totaux par sévérité
2. Violations par catégorie — FE-, BE-, TY-, CD-, CFG-, TE-, TL-* avec fichier, ligne, description
3. Tâches recommandées — Actions de remédiation priorisées
4. Couverture des règles — Status PASS/FAIL par règle

Principes

• Non-destructif : Ne jamais modifier le code source
• Basé sur preuves : Chaque violation cite fichier et ligne
• Actionnable : Chaque violation a une action de remédiation claire
• Priorisé : Focus sur violations à fort impact
• Déterministe : Même codebase = même rapport

Exceptions Connues

Certains patterns sont intentionnels :

• Types *FormData, *WithRelations, *Props sont autorisés dans src/types/
• Les fichiers dans src/pages/ peuvent utiliser export default pour React.lazy()
• Le binary sync CRDT peut utiliser fetchWithAuth directement (pas TanStack Query)

BE-003: Clarification success interne vs HTTP

Le champ success est interdit dans les réponses HTTP (c.json) mais autorisé en interne entre fonctions comme discriminated union pour la gestion d'erreurs type-safe :

// INTERDIT : success dans la réponse HTTP
return c.json({ success: true, data: user })  // NON!

// AUTORISÉ : success interne (fonction → route)
const result = await authenticate(credentials)
if (!result.success) {
  return c.json({ error: 'Unauthorized' }, 401)
}
return c.json({ data: result.user })  // OK : pas de success dans la réponse