ModCodePattern - Maintenez la cohérence entre fichiers interdépendants

📖 ModCodePattern User Guide

Complete guide to master ModCodePattern and maintain codebase consistency.

🌟 Introduction

🎯 What is ModCodePattern?

ModCodePattern is a revolutionary VS Code extension that automatically maintains code consistency across your project. Instead of manually remembering to update exports, create tests, or maintain documentation when you add new files, ModCodePattern watches your codebase and reminds you through an intelligent Todo system.

🤔 What is a "Pattern"?

A pattern in ModCodePattern is a rule that defines what should happen when certain events occur in your codebase. Think of it as an "if-then" automation rule:

IF you create a new React component in src/components/
THEN remind me to:

Add the export to src/components/index.ts
Create corresponding tests in tests/components/
Update the component documentation

📂 Configuration File Structure

All patterns must be defined in a .mod-patterns.json file at your project root, and patterns must be inside a "patterns" array:

{
  "patterns": [
    {
      "onCreateFile": "src/components/**/*.tsx",
      "notify": ["src/components/index.ts"],
      "description": "📦 Add component export"
    }
  ]
}

⚠️ Don't just put patterns in random JSON objects - they must be in the "patterns" array!

🚀 Why ModCodePattern?

❌ Without ModCodePattern

Forget to export new components
Inconsistent file organization
Missing tests for new features
Outdated documentation
Manual code reviews to catch these issues
Time wasted fixing consistency issues

✅ With ModCodePattern

Automatic reminders for consistency
Adaptive patterns that fit your architecture
Never forget to add exports or tests
Maintains documentation automatically
Works silently in the background
Focus on coding, not maintenance
Smooth onboarding - New developers follow pre-defined patterns
Guided workflows - Chained patterns create step-by-step tutorials

🎮 How Does It Work?

Install & Configure

Install the extension and create a .mod-patterns.json file at your project root with a "patterns" array containing your automation rules

Work Normally

Code as usual - create files, modify components, add features

Get Smart Reminders

ModCodePattern detects changes and shows you a Todo list of consistency tasks

Stay Consistent

Check off completed tasks and maintain perfect codebase consistency

🎓 Smooth Onboarding & Guided Workflows

🚀 Effortless Team Onboarding

New developers joining your project don't need extensive documentation or training. ModCodePattern patterns act as living guidelines that automatically guide them through your project's conventions.

Add a new component → Automatically reminded to export it
Create an API route → Guided to add corresponding tests
Update a utility → Reminded to update related documentation

🔗 Chained Pattern Workflows

Create step-by-step tutorials using chained patterns. When one pattern completes, it can trigger the next, creating guided workflows for complex features.

1. Create component → 2. Add export → 3. Create test → 4. Update docs

🎯 Perfect For

👥 Teams

Ensure all team members follow the same patterns and conventions

🏗️ Large Projects

Maintain consistency across complex codebases with multiple modules

⚡ Rapid Development

Focus on features while ModCodePattern handles the maintenance

📋 Table of Contents

🌟 Introduction
🎯 What is ModCodePattern?
🚀 Fundamental Concepts
🎨 User Interface
🧠 Adaptive Patterns
🔗 Chained Patterns - Automatic Workflows
🎯 JSON Auto-completion
📁 Basic Configuration
🔄 Modular Configuration
🌍 Multilingual Support
🔕 Silent Mode
🎯 Complete Lifecycle
🚀 Recommended Workflow
💡 Best Practices

🎯 What is ModCodePattern?

ModCodePattern solves a fundamental development problem: maintaining consistency between interdependent files.

The Problem

In a development project, modifying one file often requires updating other files:

✅ Modify an API → Update hooks, tests, documentation
✅ Create a component → Add export, create tests, document
✅ Refactor → Synchronize types, stories, configurations

The ModCodePattern Solution

🔍 Automatic monitoring of modifications
📋 Smart reminders of actions to perform
🧠 Automatic adaptation to your architecture
⚡ Integrated interface in VS Code

🚀 Fundamental Concepts

1. Patterns (Motifs)

A pattern defines a monitoring rule:

{
  "onChange": "src/api/user.ts",        ← When this file changes
  "notify": ["src/hooks/useUser.ts"],   ← Remind these actions
  "description": "🔧 User API modified"
}

2. Triggers

Events that activate a pattern:

Trigger	Description	Example
onChange	File modified	Edit an existing file
onCreateFile	New file	Create a component
onCreateFolder	New folder	Add a module
onDeleteFile	File deleted	Cleanup after deletion
onDeleteFolder	Folder deleted	Major refactoring
onRenameFile	File renamed	Rename a component
onRenameFolder	Folder renamed	Reorganize structure
onStart	Manual trigger	Educational guidance

3. Notifications

Three types of actions to remind:

Files to Modify

{
  "file": "src/components/index.ts",
  "description": "📦 Add component export"
}

Folders to Create/Modify

{
  "folder": "tests/components/",
  "description": "🧪 Create tests in this folder"
}

Commands to Execute

{
  "commands": ["pnpm run lint:fix", "pnpm test"],
  "description": "🚀 Run quality tools"
}

🎨 User Interface

1. Status Bar

Permanent indicator in VS Code:

✅ `✓ ModCodePattern`: No pending tasks
📋 `📋 3 task(s)`: Pending actions (orange background)
🖱️ Clickable to open todo list

2. Interactive Todo List

Native VS Code interface with:

✅ Checkboxes to mark completed tasks
🔗 Clickable links to open files/folders
🚀 Execute buttons for commands
📝 Detailed descriptions for each action
🔄 Real-time updates automatic

3. Popup Notifications

Alerts during detections with:

📢 Contextualized message of what changed
📋 "View Todo" button to access actions
🔕 Silent mode available

4. VS Code Commands

Access via `Ctrl+Shift+P`:

📋 Open Todo List
🌍 Change Language (FR/EN)
🔧 View Adaptive Variables
🔕 Toggle Notifications
🚀 ModCodePattern: Start - Trigger onStart patterns

🧠 Adaptive Patterns

🆕 REVOLUTION!

Adaptive patterns automatically adapt to your architecture!

Fixed Patterns Problem

❌ Rigid pattern - only works for ONE architecture

{
  "onCreateFile": "src/components/**/*.tsx",
  "notify": ["src/components/index.ts"]
}

Problems:

❌ What if your components are in `app/ui/`?
❌ What if your export file is `lib/index.ts`?

Solution: Adaptive Variables

✅ Adaptive pattern - works for ALL projects!

{
  "onCreateFile": "{{COMPONENTS_DIR}}/**/*.tsx",
  "notify": ["{{COMPONENTS_DIR}}/index.ts"],
  "description": "📦 Add component export"
}

Available Variables

🏗️ Adaptive Variables (Automatically Detected)

Variable	Description	Examples
{{SRC_DIR}}	Main source folder	src, lib, app
{{COMPONENTS_DIR}}	Components folder	src/components, app/ui
{{HOOKS_DIR}}	Hooks/composables folder	src/hooks, src/composables
{{API_DIR}}	API/services folder	src/api, src/services
{{TESTS_DIR}}	Tests folder	tests, __tests__
{{DOCS_DIR}}	Documentation folder	docs, documentation
{{CONFIG_DIR}}	Configuration folder	config, configs
{{CONFIG_FILE}}	Configuration file	config/index.ts
{{TYPES_FILE}}	Types file	src/types/index.ts

⚡ Runtime Variables (New!)

Variable	Description	Examples
{{TRIGGER_PATH}}	Trigger file path	src/components/Button.tsx
{{TRIGGER_TYPE}}	Event type	onCreateFile, onChange, onStart
{{TRIGGER_FILE}}	Trigger file name	Button.tsx
{{TRIGGER_DIR}}	Trigger file directory	src/components

Automatic Detection

The extension analyzes your project and detects:

📁 Folder structure (src/, app/, lib/)
🛠️ Framework used (React, Vue, Angular, etc.)
⚙️ Build tools (Vite, Webpack, Next.js)
📝 Naming conventions

Runtime Variables - New Feature!

🆕 NEW FEATURE!

Runtime variables allow you to use information about the file that triggers the pattern.

Usage in Descriptions

{
  "onChange": "{{COMPONENTS_DIR}}/**/*.tsx",
  "notify": [
    {
      "file": "{{COMPONENTS_DIR}}/index.ts",
      "description": "📦 Add export for {{TRIGGER_FILE}} from {{TRIGGER_DIR}}"
    }
  ],
  "description": "🔧 Component {{TRIGGER_FILE}} modified in {{TRIGGER_PATH}}"
}

Usage in Paths

{
  "onCreateFile": "src/components/**/*.tsx",
  "notify": [
    {
      "file": "{{TRIGGER_DIR}}/{{TRIGGER_FILE}}.test.tsx",
      "description": "🧪 Create test for {{TRIGGER_FILE}}"
    },
    {
      "folder": "docs/components/{{TRIGGER_FILE}}/",
      "description": "📝 Document {{TRIGGER_FILE}}"
    }
  ]
}

Usage in Commands

{
  "onChange": "src/**/*.ts",
  "notify": [
    {
      "commands": [
        "echo 'File modified: {{TRIGGER_PATH}}'",
        "code {{TRIGGER_PATH}}",
        "git add {{TRIGGER_PATH}}"
      ],
      "description": "🚀 Actions for {{TRIGGER_FILE}}"
    }
  ]
}

Complete Example with Mixed Variables

{
  "onCreateFile": "{{COMPONENTS_DIR}}/**/*.tsx",
  "notify": [
    {
      "file": "{{COMPONENTS_DIR}}/index.ts",
      "description": "📦 Add export for {{TRIGGER_FILE}}"
    },
    {
      "file": "{{TESTS_DIR}}/{{TRIGGER_FILE}}.test.tsx",
      "description": "🧪 Test for {{TRIGGER_FILE}} from {{TRIGGER_DIR}}"
    },
    {
      "commands": ["pnpm test {{TRIGGER_PATH}}"],
      "description": "🚀 Test {{TRIGGER_FILE}}"
    }
  ],
  "description": "🆕 New component {{TRIGGER_FILE}} created in {{TRIGGER_PATH}}"
}

View Detected Variables

Ctrl+Shift+P → "ModCodePattern: View Adaptive Variables"

🔗 Chained Patterns - Automatic Workflows

🚀 Revolutionary Advanced Feature!

Chained patterns allow you to create automatic workflows where each pattern triggers the next in cascade.

The Concept

Instead of isolated patterns, create smart pipelines:

Pattern 1: Create Component
       ↓
Pattern 2: Create Story
       ↓
Pattern 3: Create Tests
       ↓
Pattern 4: Run Tests

🚀 Vision: AI-Guided Development

Imagine this scenario: Your AI assistant generates a complex React component with hooks, state management, and API calls. Instead of leaving you to figure out the implementation details, it automatically creates chained patterns that guide you step-by-step through:

📝 Understanding the component's architecture
🧪 Setting up the corresponding tests
📚 Adding proper TypeScript types
🔗 Integrating with your existing state management
📖 Documenting the new patterns for your team

"Your AI doesn't just generate code—it creates a personalized learning path through chained patterns, turning every AI-generated feature into a guided tutorial that teaches your team the 'why' behind the 'what'."

Basic Example

{
  "patterns": [
    {
      "onCreateFile": "{{COMPONENTS_DIR}}/**/*.tsx",
      "notify": [
        {
          "folder": "src/stories/",
          "description": "📖 Create Storybook Story"
        }
      ],
      "description": "🆕 Component created → Story to create"
    },
    {
      "onCreateFile": "src/stories/**/*.stories.tsx",
      "notify": [
        {
          "folder": "{{TESTS_DIR}}/stories/",
          "description": "🧪 Create Story tests"
        }
      ],
      "description": "📖 Story created → Tests to create"
    },
    {
      "onCreateFile": "{{TESTS_DIR}}/stories/**/*.test.tsx",
      "notify": [
        {
          "commands": ["pnpm run test:stories"],
          "description": "🚀 Run Story tests"
        }
      ],
      "description": "🧪 Tests created → Auto execution"
    }
  ]
}

Scenario in Action

You create `src/components/Button.tsx`
ModCodePattern detects → Notification "📖 Create Storybook Story"
You create `src/stories/Button.stories.tsx`
ModCodePattern detects → Notification "🧪 Create Story tests"
You create `tests/stories/Button.stories.test.tsx`
ModCodePattern triggers → "🚀 Run pnpm run test:stories"

Workflow Advantages

✅ Zero forgetting: Each step triggers the next
✅ Standardization: Identical workflows for the whole team
✅ Forced consistency: Impossible to bypass steps
✅ Massive acceleration: Completely automated processes
✅ Ensured quality: Integrated tests and validations

Popular Workflow Types

🎨 Frontend Component Pipeline

Component → Story → Tests → Documentation

🛠️ API Backend Pipeline

Route → Types → Tests → Documentation

📦 Feature Pipeline

Feature → Component → Hook → E2E Tests

🚀 DevOps Pipeline

Code → Lint → Tests → Build → Deploy

Best Practices

✅ Do's

Short chains (3-4 steps max)
Atomic actions at each step
Descriptive names for traceability
Individual tests for each link

❌ Don'ts

Infinite chains creating loops
Complex actions in a single pattern
Circular dependencies
Too generic patterns

Debugging Workflows

# See all active patterns
Ctrl+Shift+P → "ModCodePattern: View Adaptive Variables"

# Observe todo list after each action
Ctrl+Shift+P → "ModCodePattern: Open Todo List"

🎯 ProTip: Start with a simple workflow then gradually enrich according to your needs!

🎯 JSON Auto-completion

✨ Automatic Feature!

ModCodePattern includes a complete JSON Schema that enables auto-completion in VS Code.

How it Works

In your `.mod-patterns.json` file:

✅ Automatic auto-completion - Type `Ctrl+Space`
✅ Real-time validation - Underlined errors
✅ Integrated documentation - Hover over properties
✅ Contextual suggestions - Ready-to-use examples

Usage Example

{
  "p|" ← Type "p" then Ctrl+Space
}

Automatic suggestions:

patterns ✨ - List of monitoring patterns
imports ✨ - Configuration files to import
variables ✨ - Custom variables

Automatic Validation

{
  "patterns": [
    {
      "onChange": "src/*.ts",
      "notify": 123  ← ❌ Detected error: must be string or array
    }
  ]
}

Advantages

🚀 Facilitated learning for new users
⚡ Fast configuration with suggestions
🔍 Error prevention by validation
📚 Living documentation integrated

📁 Basic Configuration

1. Main File

Create `.mod-patterns.json` at the root of your project:

{
  "patterns": [
    {
      "onChange": "src/api/**/*.ts",
      "notify": [
        {
          "file": "src/types/api.ts",
          "description": "📘 Update types"
        },
        {
          "folder": "tests/api/",
          "description": "🧪 Create/update tests"
        }
      ],
      "description": "🔧 API modified"
    }
  ]
}

2. Custom Variables

Define your own variables:

{
  "variables": {
    "PROJECT_NAME": "MyApp",
    "API_VERSION": "v2",
    "CUSTOM_DIR": "lib/special"
  },
  "patterns": [
    {
      "onChange": "{{CUSTOM_DIR}}/**/*.ts",
      "notify": ["docs/{{PROJECT_NAME}}/{{API_VERSION}}/changelog.md"],
      "description": "📋 Update changelog {{PROJECT_NAME}}"
    }
  ]
}

🔄 Modular Configuration

For complex projects, organize your patterns into modules:

Main File

{
  "imports": [
    ".mod-patterns/react.json",
    ".mod-patterns/api.json",
    ".mod-patterns/testing.json"
  ],
  "patterns": [
    {
      "onChange": "package.json",
      "notify": ["README.md"],
      "description": "📦 Dependencies modified"
    }
  ]
}

React Module (`.mod-patterns/react.json`)

{
  "patterns": [
    {
      "onCreateFile": "{{COMPONENTS_DIR}}/**/*.tsx",
      "notify": [
        {
          "file": "{{COMPONENTS_DIR}}/index.ts",
          "description": "📦 Add component export"
        },
        {
          "folder": "{{TESTS_DIR}}/components/",
          "description": "🧪 Create tests"
        }
      ],
      "description": "🆕 New React component"
    }
  ]
}

🌍 Multilingual Support

Interface

The extension supports French and English:

Ctrl+Shift+P → "ModCodePattern: Change Language"

Multilingual Patterns

Your descriptions can be translated:

{
  "description": {
    "fr": "📦 Composant modifié",
    "en": "📦 Component modified"
  },
  "notify": [
    {
      "file": "src/components/index.ts",
      "description": {
        "fr": "📦 Ajouter l'export du composant",
        "en": "📦 Add component export"
      }
    }
  ]
}

🔕 Silent Mode

Disable popup notifications while keeping essential features:

Temporary

Ctrl+Shift+P → "ModCodePattern: Toggle Notifications"

Permanent

// settings.json
{
  "modcodepattern.notifications.enabled": false
}

Silent Mode Advantages

✅ Todo list always active
✅ Status bar functional
✅ Background detection
❌ No interruption popups

🎯 Complete Lifecycle

ModCodePattern manages all lifecycle events:

Manual Trigger

{
  "onStart": true,
  "notify": [
    {
      "file": "{{TRIGGER_PATH}}/README.md",
      "description": "📚 Start by reading project guide {{TRIGGER_FILE}}"
    }
  ],
  "description": "🚀 Startup guidance for {{TRIGGER_FILE}}"
}

Creation

{
  "onCreateFile": "src/components/**/*.tsx",
  "notify": ["{{COMPONENTS_DIR}}/index.ts"],
  "description": "🆕 New component created"
}

Modification

{
  "onChange": "src/api/**/*.ts",
  "notify": ["src/types/api.ts"],
  "description": "🔧 API modified"
}

Deletion

{
  "onDeleteFile": "src/components/**/*.tsx",
  "notify": [
    {
      "file": "{{COMPONENTS_DIR}}/index.ts",
      "description": "🗑️ Remove component export"
    }
  ],
  "description": "🗑️ Component deleted"
}

Rename

{
  "onRenameFile": "src/api/**/*.ts",
  "notify": [
    {
      "file": "src/hooks/useApi.ts",
      "description": "📝 Update imports"
    }
  ],
  "description": "📝 API file renamed"
}

🚀 Recommended Workflow

1. Project Startup

Install ModCodePattern
Create `.mod-patterns.json` with basic patterns
Test with simple modifications
Iterate and enrich patterns

2. Daily Development

Modify your files normally
Watch notifications/status bar
Open todo list (`Ctrl+Shift+P` or click bar)
Process actions one by one
Check completed tasks

3. Project Evolution

Analyze missed patterns
Add new adaptive patterns
Organize into modules if necessary
Share with team

💡 Best Practices

Efficient Patterns

✅ Specific

{
  "onChange": "src/api/user.ts",
  "notify": ["src/hooks/useUser.ts"]
}

❌ Too broad (generates too many notifications)

{
  "onChange": "src/**/*",
  "notify": ["README.md"]
}

Adaptive vs Fixed Variables

✅ Adaptive (reusable)

{
  "onChange": "{{API_DIR}}/**/*.ts",
  "notify": ["{{TYPES_FILE}}"]
}

❌ Fixed (project-dependent)

{
  "onChange": "src/api/**/*.ts",
  "notify": ["src/types/index.ts"]
}

Modular Organization

✅ Organized by domain

{
  "imports": [
    ".mod-patterns/components.json",
    ".mod-patterns/api.json"
  ]
}

🔗 Useful Links