@hatem427/code-guard-ci 3.6.2 → 3.6.4

package/scripts/config-generators/frameworks/nextjs.ts

@@ -6,107 +6,355 @@
 export function nextjsGuidelines(): string {
   return `## Frontend Team Constitution — Next.js (App Router)
 
-### Principle I. App Router Mandate
+> Version: 1.0.0 | Ratified: 2026-04-03
+> This constitution is the supreme authority for all development decisions. It supersedes personal preferences, external tutorials, and ad-hoc patterns.
 
-- MUST use App Router (\`app/\`).
-- Server Components by default.
-- Use "use client" ONLY when necessary.
-- Prefer Server Actions for mutations.
-- Use Route Handlers inside \`app/api/\`.
+---
+
+### Core Philosophy
+
+Build scalable, maintainable, and predictable Next.js systems.
+
+**Priority order:** Reusability > Readability > Accessibility > Performance.
+
+Every piece of code MUST:
+- Be understandable at first glance
+- Follow a single responsibility
+- Be reusable or explicitly justify why it is not
+- Feel like a well-designed, minimal product API
+
+---
+
+### I. Server-First Architecture
+
+- Default to React Server Components (RSC) for ALL components
+- Use Client Components (\`"use client"\`) ONLY when strictly required:
+  - User interactivity (\`onClick\`, \`useState\`, \`useEffect\`)
+  - Browser-only APIs (\`window\`, \`localStorage\`, \`IntersectionObserver\`)
+- Client Components MUST be placed as deep as possible in the component tree — never wrap large sections unnecessarily
+- Data fetching MUST happen on the server by default
+- Maximize server-rendered HTML; minimize client-side JavaScript
+
+---
+
+### II. Component Design & Reusability
+
+- Every component MUST follow the Single Responsibility Principle
+- Every component MUST expose a clean, minimal props API
+- Components MUST be small, focused, and easily composable
+- If a component grows large, it MUST be split into:
+  - Sub-components (for UI decomposition)
+  - Custom hooks (for logic extraction)
+  - Utility functions (for reusable pure logic)
+- Before creating any new component, check for:
+  - Existing components in \`/components\`
+  - Existing utilities in \`/utils\` or \`/lib\`
+  - Existing hooks in \`/hooks\`
+- Shared/reusable components MUST live in \`/components\`
+- No duplicated logic — ever. Extract and reuse
+- No god components (components handling UI + business logic + data fetching simultaneously)
+- Each component MUST feel like a clean, minimal, reusable API:
+  \`<Card title="..." description="..." action={<Button />} />\`
+
+PROHIBITED:
+- Overloaded props and complex nested internal logic
+- Duplicated logic anywhere in the codebase
+
+---
+
+### III. Design System Enforcement (NON-NEGOTIABLE)
+
+\`global.css\` (Tailwind) is the ONLY source of truth for all visual design tokens.
+
+The design system MUST define and contain:
+- Colors, Spacing scale, Typography scale
+- Shadows, Blur variants
+- Animation durations and delays
+- Border radii, Breakpoints
 
 PROHIBITED:
-- Pages Router.
-- Unnecessary client components.
-- Mixing server/client logic improperly.
+- ❌ Inline custom styles (\`style={{}}\`)
+- ❌ Arbitrary Tailwind values (\`px-[13px]\`, \`bg-[#ff0000]\`)
+- ❌ Using any visual property before adding it as a design token
+
+REQUIRED:
+- ✅ Use design tokens ONLY
+- ✅ If a token is missing: add it to \`global.css\` FIRST, then use it
 
 ---
 
-### Principle II. Server vs Client Separation
+### IV. Accessibility (NON-NEGOTIABLE)
 
-Server Components MUST:
-- Fetch data.
-- Handle secure logic.
-- Access environment variables.
+- Every component MUST use semantic HTML: \`<button>\`, \`<nav>\`, \`<section>\`, \`<article>\`, \`<main>\`, \`<header>\`, \`<footer>\`, \`<aside>\`, \`<form>\`, \`<label>\`
+- Every interactive element MUST include appropriate \`aria-*\` attributes where native semantics are insufficient
+- Every interactive element MUST support full keyboard navigation
+- Focus states MUST be visible and follow the design system
+- Color contrast MUST meet WCAG 2.1 AA minimum (4.5:1 for text, 3:1 for large text/UI)
+- All form inputs MUST have associated \`<label>\` elements
+- Images MUST have meaningful \`alt\` text or \`aria-hidden="true"\` if decorative
+- Dynamic content changes MUST use live regions where appropriate
+- Skip navigation links MUST be provided for page-level layouts
 
-Client Components MUST:
-- Handle UI interactivity only.
-- Not access server secrets.
+---
+
+### V. Responsiveness (NON-NEGOTIABLE)
+
+- ALL components and layouts MUST be fully responsive
+- Follow mobile-first design: base styles target mobile, use \`sm:\`, \`md:\`, \`lg:\`, \`xl:\`, \`2xl:\` to enhance
+- Every section and page MUST render correctly on:
+  - Mobile (320px–767px)
+  - Tablet (768px–1023px)
+  - Desktop (1024px+)
+
+PROHIBITED:
+- ❌ Fixed widths (except for icons and known fixed-size elements)
 
-Never:
-- Use \`process.env\` inside client components.
-- Perform secure logic in client side.
+REQUIRED:
+- ✅ Flexible layouts: \`flex\`, \`grid\`, \`auto\`, \`min/max\`
 
 ---
 
-### Principle III. Data Fetching Strategy
+### VI. Testing (NON-NEGOTIABLE)
 
-MANDATORY:
-- Use async Server Components for data fetching.
-- Use Server Actions for mutations.
-- Wrap API logic in services.
+- Every component MUST have unit tests covering:
+  - Rendering (does it mount without errors)
+  - Props behavior (correct response to different props)
+  - Edge cases (empty states, missing optional props, boundary values)
+  - Accessibility basics (semantic structure, aria attributes)
+- Test file location: colocated in a \`__tests__\` folder next to the component
+- Test file naming: \`ComponentName.test.tsx\`
+- Tests MUST be written alongside the component — no component is complete without tests
+
+---
+
+### VII. Type Safety & Code Quality
+
+- TypeScript strict mode MUST be used everywhere
 
 PROHIBITED:
-- Fetching in random client components.
-- Mixing REST calls inside UI.
+- ❌ \`any\` type — ever
+- ❌ \`@ts-ignore\` or \`@ts-expect-error\` without a tracked issue
+
+REQUIRED:
+- ✅ Explicit types for: all component props, all API responses, all state shapes, all function parameters/return types, all hook return values
+- ✅ All types MUST live in \`/types\` (shared) or colocated with feature code (feature-specific)
+- ✅ Prefer \`interface\` for object shapes, \`type\` for unions and computed types
 
 ---
 
-### Principle IV. Performance & SEO
+### VIII. Data Fetching Strategy
 
-MANDATORY:
-- Use \`next/image\`.
-- Use \`next/link\`.
-- Export \`metadata\`.
-- Implement \`loading.tsx\` and \`error.tsx\`.
+- Preferred: server-side fetching via React Server Components
+- Use \`fetch\` with appropriate caching (\`force-cache\`, \`no-store\`, \`revalidate\`)
+- Use React \`cache()\` for deduplicating server-side requests
+- Every data-driven component MUST implement:
+  - A loading state (skeleton/spinner via \`loading.tsx\` or \`<Suspense>\`)
+  - An error state (via \`error.tsx\` or explicit error UI)
 
 PROHIBITED:
-- Raw \`<img>\`
-- Raw \`<a>\` for internal routes
+- ❌ Data fetching in Client Components unless strictly required
+- ❌ Duplicate API calls — centralize and reuse fetch functions in \`/services\` or \`/lib\`
 
 ---
 
-### Principle V. Folder Architecture
+### IX. Internationalization (i18n)
+
+- The project MUST support multi-language from day one
+- Adding a new language MUST require only adding a new translation file
+- Hybrid translation strategy:
+  - Frontend (static): UI labels, buttons, headings, static content from translation files
+  - Backend (dynamic): API-driven content served in the requested locale
+- Translation key naming rules:
+  - ✅ Semantic and decoupled from content: \`title\`, \`desc\`, \`cta\`, \`item-1\`, \`label\`, \`placeholder\`, \`error-required\`
+  - ❌ Keys MUST NOT mirror content: \`welcomeToOurAmazingPlatform\`, \`clickHereToSubmit\`
+- ❌ No hardcoded user-facing text in any component
+- Translation files MUST be organized per-locale: \`/messages/en.json\`, \`/messages/ar.json\`
+
+---
+
+### X. Icon System
+
+- ALL icons MUST be rendered through a \`BaseIcon\` component
+- Icon SVG files MUST be stored in \`/assets/icons\`
+- \`BaseIcon\` MUST support: \`name\`, \`size\`, \`className\` props and proper \`aria-hidden\`/\`aria-label\`
+
+PROHIBITED:
+- ❌ Direct SVG usage in components
+- ❌ Inline SVG markup in JSX
+
+---
+
+### XI. Performance & Optimization
+
+- Minimize client-side JavaScript bundle size
+- Avoid unnecessary re-renders in Client Components
+- Use \`React.memo\` ONLY when profiling confirms a performance issue
+- Use \`next/dynamic\` for lazy-loading heavy Client Components
+- Use \`next/image\` for all images
+- Use \`next/font\` for font loading
+- Prefer CSS-based animations over JavaScript-based animations
+- Code-split at the route level via the App Router
+
+---
+
+### XII. Separation of Concerns
+
+| Concern | Location |
+|---------|----------|
+| UI Components | \`/components\` |
+| Logic / Hooks | \`/hooks\` |
+| API Services | \`/services\` |
+| Shared Types | \`/types\` |
+| Utilities | \`/utils\` |
+| Libraries | \`/lib\` |
+| Static Assets | \`/assets\` |
+| Icons | \`/assets/icons\` |
+| Translations | \`/messages\` |
+
+PROHIBITED:
+- ❌ Mixing concerns within a single file
+- ❌ Business logic in components
+- ❌ UI rendering in hooks
+
+---
+
+### XIII. Code Cleanliness
+
+Naming conventions:
+- Components: \`PascalCase\` (e.g., \`HeroSection\`, \`BaseIcon\`)
+- Hooks: \`camelCase\` with \`use\` prefix (e.g., \`useTranslation\`)
+- Utilities: \`camelCase\` (e.g., \`formatDate\`, \`cn\`)
+- Types/Interfaces: \`PascalCase\` (e.g., \`CardProps\`, \`ApiResponse\`)
+- Constants: \`UPPER_SNAKE_CASE\`
+- Files: \`PascalCase\` for components, \`camelCase\` for utils
+
+Comments:
+- ❌ No unnecessary comments — if a comment is needed, the code is too complex; simplify it
+- ✅ Acceptable ONLY for: non-obvious business rules, workarounds with linked issues, JSDoc on exported functions
+
+---
+
+### XIV. Anti-Patterns (STRICTLY FORBIDDEN)
+
+- ❌ Large Client Components wrapping server-renderable content
+- ❌ Inline styles (\`style={{}}\`)
+- ❌ Hardcoded user-facing text
+- ❌ Duplicated/repeated logic anywhere in the codebase
+- ❌ Ignoring accessibility requirements
+- ❌ Breaking or bypassing the design system
+- ❌ Using \`any\` type
+- ❌ Unstructured or random folder creation
+- ❌ Over-engineering simple components
+- ❌ Direct SVG usage outside \`BaseIcon\`
+- ❌ Arbitrary Tailwind values
+- ❌ Data fetching in Client Components without justification
+- ❌ Components without unit tests
+- ❌ Hardcoded colors, spacing, or typography values
+- ❌ \`console.log\` in production code
+
+---
+
+### Architecture & Folder Structure
 
 \`\`\`
-src/
-├── app/              # Routes (Server-first)
-├── components/       # Reusable UI
-├── hooks/            # Custom hooks
-├── services/         # API layer
-├── lib/              # Utilities
-└── types/            # Type definitions
+apps/project-name/src/
+├── app/                    # Next.js App Router (routes, layouts, pages, loading, error boundaries)
+│   ├── [locale]/           # i18n dynamic locale segment
+│   │   ├── layout.tsx
+│   │   ├── page.tsx
+│   │   ├── loading.tsx
+│   │   ├── error.tsx
+│   │   └── [feature]/      # Feature routes
+│   │       ├── page.tsx
+│   │       ├── loading.tsx
+│   │       └── error.tsx
+│   ├── layout.tsx          # Root layout
+│   └── global.css          # Design system (Tailwind tokens)
+├── components/
+│   ├── ui/                 # Atomic UI components (Button, Input, Card, Badge, Modal, etc.)
+│   ├── shared/             # Shared composed components (Header, Footer, Navbar, BaseIcon, etc.)
+│   └── layout/             # Layout components (Container, Section, Grid, Stack, etc.)
+├── hooks/                  # Custom React hooks
+├── lib/                    # Third-party integrations, config, and framework utilities
+├── utils/                  # Pure utility functions
+├── services/               # API service layer (fetch wrappers, data transformers)
+├── types/                  # Shared TypeScript type definitions
+├── assets/
+│   ├── icons/              # SVG icon files (used via BaseIcon)
+│   └── images/             # Static image assets
+└── messages/               # i18n translation files
+    ├── en.json
+    └── [locale].json
 \`\`\`
 
-No business logic inside components.
+Rules:
+- No random or ad-hoc folder creation
+- Group by feature within route folders when needed
+- Keep ALL shared logic in global folders (\`/components\`, \`/hooks\`, \`/utils\`, \`/lib\`, \`/services\`, \`/types\`)
+- Feature-specific code lives within its route folder ONLY if it is truly not reusable
 
 ---
 
-### Principle VI. Type & Safety Enforcement
+### Component Creation Checklist
+
+Before any component is marked as complete, verify:
 
-- No \`any\`.
-- All route handlers must have try/catch.
-- Validate request body.
-- Never expose secrets to client.
+- [ ] Is it reusable (or justified why not)?
+- [ ] Does it strictly follow the design system?
+- [ ] Is it fully accessible (semantic HTML, aria, keyboard)?
+- [ ] Is it fully responsive (mobile, tablet, desktop)?
+- [ ] Does it have comprehensive unit tests?
+- [ ] Is it fully typed (no \`any\`, explicit props interface)?
+- [ ] Is it small and focused (single responsibility)?
+- [ ] Does it avoid duplicating existing logic?
+- [ ] Does it use \`BaseIcon\` for any icons?
+- [ ] Does it use translation keys for all user-facing text?
+- [ ] Does it handle loading and error states (if data-driven)?
+- [ ] Is it a Server Component (or justified why client)?
+- [ ] Are new design tokens added to \`global.css\` first?
 
 ---
 
-### Principle VII. Styling & Design
+### ESLint & Linting Rules
 
-- Follow design tokens.
-- Use logical properties for RTL.
-- No hardcoded spacing values.
-- Prefer Tailwind utility patterns.
+The project MUST enforce the following ESLint rules:
+
+\`\`\`
+no-unused-vars: error
+@typescript-eslint/no-explicit-any: error
+@typescript-eslint/consistent-type-imports: warn
+react-hooks/rules-of-hooks: error
+react-hooks/exhaustive-deps: warn
+jsx-a11y/alt-text: error
+jsx-a11y/anchor-is-valid: error
+jsx-a11y/click-events-have-key-events: error
+jsx-a11y/no-static-element-interactions: error
+jsx-a11y/label-has-associated-control: error
+import/order: warn (grouped and alphabetized)
+no-console: warn (error in production builds)
+react/no-unescaped-entities: error
+@next/next/no-img-element: error
+\`\`\`
 
 ---
 
-### Principle VIII. Clean Code & Build Integrity
+### Governance
 
-PROHIBITED:
-- Console logs.
-- Dead imports.
-- Unused server actions.
-- Build warnings.
+**Amendment procedure:**
+1. Propose a change with rationale and impact assessment
+2. Document the change in this file with version bump
+3. Update all dependent templates and artifacts
+4. Commit with: \`docs: amend constitution to vX.Y.Z (description)\`
 
-Build must pass with \`next build\` without warnings.
+**Versioning policy:**
+- MAJOR: Principle removal, redefinition, or backward-incompatible governance change
+- MINOR: New principle, section, or materially expanded guidance
+- PATCH: Wording clarification, typo fix, non-semantic refinement
+
+**Compliance review:**
+- Every PR MUST be checked against this constitution
+- Every new component MUST pass the Component Creation Checklist
+- Violations MUST be fixed before merge — no exceptions
 `;
 }
+

package/scripts/postinstall.ts

@@ -33,7 +33,7 @@ console.log(`
 
 � Optional — Enable full SBOM scanning (Layer 3):
 
-     npm run install-security-tools
+     npx code-guard install-security-tools
 
    This installs Syft + Grype for deep CVE scanning of your
    full dependency tree (beyond npm audit and RetireJS).

package/scripts/precommit-check.ts

@@ -464,7 +464,7 @@ function _printGrypeInstallInstructions(): void {
   }
 
   console.log('  │                                                             │');
-  console.log('  │  Or run:  npm run install-security-tools                    │');
+  console.log('  │  Or run:  npx code-guard install-security-tools              │');
   console.log('  └─────────────────────────────────────────────────────────────┘');
   console.log('');
 }

package/scripts/utils/project-detector.ts

@@ -62,6 +62,8 @@ export interface DetectionResult {
   packageManager: 'npm' | 'yarn' | 'pnpm' | 'bun';
   /** Already-installed tooling */
   existingTooling: ExistingTooling;
+  /** App-level ESLint config paths found in Nx projects (override root config) */
+  nxAppEslintConfigs: string[];
 }
 
 // ── Detection logic ─────────────────────────────────────────────────────────
@@ -122,6 +124,48 @@ function detectMonorepo(dir: string, pkg: Record<string, any>): MonorepoType {
   return 'none';
 }
 
+/**
+ * Detect app-level ESLint config files in Nx projects.
+ * These override the root-level ESLint config.
+ */
+function detectNxAppEslintConfigs(dir: string, monorepo: MonorepoType): string[] {
+  if (monorepo !== 'nx') return [];
+
+  const eslintFiles = [
+    '.eslintrc', '.eslintrc.js', '.eslintrc.cjs', '.eslintrc.json', '.eslintrc.yml',
+    'eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs'
+  ];
+  const found: string[] = [];
+
+  // Scan apps/ and libs/ directories (standard Nx layout)
+  const searchDirs = ['apps', 'libs', 'packages'];
+  for (const sub of searchDirs) {
+    const subDir = path.join(dir, sub);
+    if (!fs.existsSync(subDir) || !fs.statSync(subDir).isDirectory()) continue;
+
+    let entries: string[];
+    try {
+      entries = fs.readdirSync(subDir);
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      const projectDir = path.join(subDir, entry);
+      if (!fs.statSync(projectDir).isDirectory()) continue;
+
+      for (const eslintFile of eslintFiles) {
+        const eslintPath = path.join(projectDir, eslintFile);
+        if (fs.existsSync(eslintPath)) {
+          found.push(path.relative(dir, eslintPath));
+        }
+      }
+    }
+  }
+
+  return found;
+}
+
 /**
  * Detect existing tooling already configured in the project.
  */
@@ -190,6 +234,7 @@ export function detectProject(startDir: string = process.cwd()): DetectionResult
       hasClaudeConfig: false, hasGeminiConfig: false,
       hasWindsurfConfig: false, hasJunieConfig: false,
     },
+    nxAppEslintConfigs: [],
   };
 
   if (!result) return defaults;
@@ -200,7 +245,9 @@ export function detectProject(startDir: string = process.cwd()): DetectionResult
   const usesTypeScript = hasDep(pkg, 'typescript') || fs.existsSync(path.join(dir, 'tsconfig.json'));
   const existingTooling = detectExistingTooling(dir, pkg);
 
-  const base = { rootDir: dir, packageJson: pkg, monorepo, usesTypeScript, packageManager, existingTooling };
+  const nxAppEslintConfigs = detectNxAppEslintConfigs(dir, monorepo);
+
+  const base = { rootDir: dir, packageJson: pkg, monorepo, usesTypeScript, packageManager, existingTooling, nxAppEslintConfigs };
 
   // Nuxt check (must come before Vue — Nuxt depends on Vue)
   if (hasDep(pkg, 'nuxt')) {