Mault AI-Assisted Code Quality Extension

Automate architectural discipline for AI-assisted development.

Currently supports TypeScript, JavaScript, Python
Best for newer projects
14 deterministic pattern detectors for clean code
Context-rich prompts for any AI coding assistant
Local-first with optional network-enabled features (e.g., dependency health analysis). Tool-agnostic (works with Cursor, Copilot, ChatGPT, Claude)
30-day free trial → $7.99/month | Pro add-on: $99 one-time

Mault is designed as a local-first VS Code extension. While most analysis runs entirely on your machine, certain features (such as dependency health checks) may perform network requests to retrieve external metadata. See Data & Privacy Disclosure for details.

Ready to upgrade? Subscribe to Core ($7.99/month) | Purchase Pro ($99)

How It Works

Mault Core (Included in 30-Day Free Trial)

Mault Core is easy to set up and monitors your workspace, surfacing architectural violations in the Problems Panel. Each notification includes:

DIY Guidance: Fix it yourself with the clear explanation provided
Mault Fix: One-click native fixes for common issues
Copy AI Prompt: Context-rich prompts optimized for any AI coding assistant

14 detectors catch misplaced files, identify common security vulnerabilities, naming violations, deprecated patterns, config drift, and more.

Mault Pro ($99 one-time) is not included in the 30-Day Free Trial. Pro includes all Core features plus production-readiness specs, automated enforcement, and specialized guardrails for engineering professionals, developers commercializing their product, and security/engineering leaders. Pro requires an active Core subscription. Details below.

Option A: AI-Assisted Setup

Copy this prompt into your AI coding assistant:

Run command "Mault: Open AI Coder Guide" and set up my project.

1. Analyze my codebase structure
2. Generate a docs/mault.yaml file customized to my project
3. Tell me to check the Problems Panel when done

Your AI will read the bundled guide, understand the schema, and create your rulebook automatically.

Option B: DIY Setup

Prefer to set it up yourself?

Run command: Mault: Open AI Coder Guide
Read the schema reference and examples
Create docs/mault.yaml manually following the guide

After Setup: Monitor & Fix

Few problems? Resolve one-by-one using Quick Fix (Cmd+. / Ctrl+.)
Many problems? Copy a block of diagnostics, paste into your AI coder, then prompt to resolve
Intentional deviations? Use ⏭️ Dismiss in Quick Fix to hide diagnostics you've decided to keep (persists across restarts)

Mault Pro ($99 One-Time Add-On)

Requires active Mault Core subscription. Not included in free trial.

Mault Pro includes all Core features and is for developers who are serious about shipping production-ready software: whether you're commercializing a product, leading a team, or building enterprise-grade applications.

What Pro Unlocks

Feature	What It Does
Dependency Health	Detects vulnerable and outdated packages automatically
Supply Chain Security	Catches hallucinated libraries and phantom dependencies
Architecture Diagrams	Visualizes your project's dependency graph for impact analysis
Structural Governance	Enforces complex code patterns via AST analysis
Semantic Similarity	Architectural testing with built-in vector embeddings
14 Production-Readiness Specs	Battle-tested guides for CI/CD, TDD, containerization, security, and more

Getting Started with Pro

Step 1: Purchase Pro via the extension or mault.ai/billing

Step 2: Copy Setup Prompt into your AI coding assistant (Claude Code, Cursor, Copilot, ChatGPT):

Run command "Mault: Open Production Readiness Kit (Pro)" and set up my project.

1. Read the Production Readiness Kit that opens
2. Follow the 8-step journey to make my project production-ready
3. Tell me to check the Problems Panel when each step is complete

Step 3: Watch Progress in the Problems Panel (Ctrl+Shift+M / Cmd+Shift+M):

mault-pro-setup (8)
  ⚠ Step 1/8: Git Repository — Not initialized
  ⚠ Step 2/8: Environment Setup — .env.example missing
  ⚠ Step 3/8: Containerization — Dockerfile missing
  ...

Step 4: Use Quick Fix Actions on each step:

Click the lightbulb (💡) or press Ctrl+. / Cmd+. on any step
🤖 Copy AI Prompt for Step N — Copies a context-rich prompt for your AI coder
⏭️ Ignore Step N — Hide completed or skipped steps from Problems Panel

Step 5: Initialize Mault Hook (Step 7) — After AI completes Steps 1-6, click the Quick Fix for Step 7. This runs Mault's compiled enforcement setup (license-gated).

Done! Problems Panel clears as steps complete. Your project is now production-ready with CI/CD, TDD, pre-commit hooks, and governance enforcement.

The 8-Step Journey

Step	Category	What It Creates
1	Infrastructure	Git repository, .gitignore, branch conventions
2	Infrastructure	.env.example, secrets management
3	Infrastructure	Dockerfile, docker-compose.yml
4	Infrastructure	CI/CD pipeline (GitHub Actions)
5	Testing	TDD framework (Jest/pytest/go test/JUnit)
6	Hooks	Pre-commit hooks (up to 9 layers)
7	Enforcement	Mault polyglot detectors
8	Governance	AI-generated governance scripts

For deep-dive documentation, see Pro: Production Readiness Kit below.

Commands

Access via Command Palette (Ctrl+Shift+P / Cmd+Shift+P).

Setup & Configuration

Command	Description
`Mault: Initialize`	Initialize Mault in the workspace
`Mault: Open AI Coder Guide`	Open the setup guide for AI assistants
`Mault: Audit Configuration`	Check mault.yaml validity

AI Prompt Generation (Clipboard)

Command	Description
`Mault: Copy findings report (JSON)`	Full JSON report of all issues
`Mault: Copy remediation prompt`	AI-optimized prompt for specific issue
`Mault: Copy Impact Analysis Prompt`	Impact analysis for high-dependency files
`Mault: Copy scaffolding reorganization prompt`	Flat architecture fix guidance
`Mault: Copy naming convention fix prompt`	Naming violation fix prompt
`Mault: Copy dead-end remediation prompt`	Dead-end folder fix prompt
`Mault: Copy dependency health AI prompt`	Dependency issue fix prompt

Analysis & Summaries

Command	Description
`Mault: Show findings summary`	Quick overview popup
`Mault: Show Impact Summary`	High-impact file details
`Mault: Analyze dead-end directories`	Find unreferenced folders
`Mault: Find Scattered Utils`	Locate misplaced utility files
`Mault: Analyze naming conventions`	Check naming violations
`Mault: Analyze file proliferation`	Find duplicate/versioned files

File Operations

Command	Description
`Mault: Move file to expected location`	Quick Fix in Problems panel
`Mault: Archive temporary files`	Move temp files to archive
`Mault: Quick rename file to follow naming convention`	Single file rename
`Mault: Batch rename all files to follow naming convention`	Batch rename

Pro Features

Command	Description
`Mault: Open Production Readiness Kit (Pro)`	Open bundled production-ready specs
`Mault: Generate Architecture Diagram (Pro)`	Visualize dependency graph
`Mault: Analyze dependency health (Pro)`	Check for vulnerable packages
`Mault: Analyze structural compliance (Pro)`	AST-based pattern analysis

14 Architectural Detectors

#	Detector	What It Catches	Language Support
1	Directory Reinforcement	Files placed in wrong folders	Polyglot
2	Legacy Path Prevention	Deprecated libraries, patterns, or APIs	Polyglot
3	Convention Reinforcement	Naming convention violations (camelCase vs snake_case)	Polyglot
4	Environment Reinforcement	OS-specific paths or commands that break cross-platform	Polyglot
5	Temporary Files	Clutter from .log, .tmp, .cache files	Polyglot
6	Flat Architecture	Too many files in source root without structure	Polyglot
7	Configuration Chaos	Missing critical configs (.gitignore, tsconfig, Dockerfile)	Polyglot
8	File Proliferation	Versioned duplicates (_v1, _backup, _old files)	Polyglot
9	Naming Chaos	Inconsistent file naming across the project	Polyglot
10	Overcrowded Folders	Folders with too many mixed file types	Polyglot
11	Scattered Utils	Utility functions not centralized in shared location	JS/TS (import analysis)
12	Dead-End Directories	Unused folders with unreferenced code	JS/TS (import analysis)
13	Dependency Health	Outdated or vulnerable packages	JS/TS (npm audit)
14	Application Flows	High-impact file changes affecting critical paths	JS/TS (import analysis)

Language Support Key:

Polyglot: Works with any language via file/folder pattern matching
JS/TS: Requires JavaScript/TypeScript for import/dependency analysis

Requirements

VS Code 1.104+
A workspace containing docs/mault.yaml (version: 1)
Trusted workspace for full functionality

Pricing

Tier	Price	What's Included
Free Trial	30 days	Full Core access
Mault Core	$7.99/month	14 architectural detectors, AI prompts, quick fixes
Mault Pro	$99 one-time	All Core features + production-readiness specs, security guardrails

Manage billing at mault.ai/billing

Release Notes

See CHANGELOG.md for detailed release notes.

1. Directory Reinforcement

Problem: Files are placed in the wrong folders, violating project structure conventions.

Example:

❌ src/utils/UserService.ts      # Wrong: Service in utils/
✅ src/services/UserService.ts   # Correct: Service in services/

Technical Flow

┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ File watcher detects file save/change
    │
    ├─▶ DirectoryDetector analyzes file path
    │   - Reads `docs/mault.yaml` for directory rules
    │   - Checks file name against expected directories
    │   - Example rule: "*Service.ts" → "src/services/"
    │
    └─▶ Creates DirectoryViolation finding

┌─────────────────────────────────────────────────────────────┐
│ 2. NOTIFICATION                                             │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ DiagnosticsPublisher converts finding to VS Code diagnostic
    │   - Severity: Warning (yellow squiggly)
    │   - Message: "File should be in src/services/ based on naming"
    │   - Range: Entire file path line
    │
    ├─▶ Problems Panel shows violation
    │
    └─▶ Status Bar updates: "⚠️ 1 issue"

┌─────────────────────────────────────────────────────────────┐
│ 3. USER ACTIONS                                             │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User clicks lightbulb (💡) icon
    │
    └─▶ Code Actions menu appears:
        ├─ 🔧 Quick Fix: Move to src/services/ (preferred)
        └─ 📋 Copy AI Migration Prompt

┌─────────────────────────────────────────────────────────────┐
│ 4. RESOLUTION (Option A: Quick Fix)                         │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User selects "Move to src/services/"
    │
    ├─▶ Extension executes file move
    │   - Creates target directory if needed
    │   - Moves file to correct location
    │   - Updates imports in other files (future)
    │
    └─▶ Diagnostic cleared, status bar updates: "✅ 0 issues"

┌─────────────────────────────────────────────────────────────┐
│ 5. RESOLUTION (Option B: AI Prompt)                         │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User selects "Copy AI Migration Prompt"
    │
    ├─▶ Extension generates prompt:
    │   "Move src/utils/UserService.ts to src/services/UserService.ts
    │    and update all imports across the project."
    │
    ├─▶ Prompt copied to clipboard
    │
    ├─▶ User pastes into ChatGPT/Copilot
    │
    └─▶ AI generates migration script

---

## 2. Legacy Path Prevention

**Problem:** AI Coder imports deprecated libraries or use outdated patterns.

**Example:**
```typescript
❌ import { utils } from '../../../legacy/old-utils';
✅ import { utils } from '@/utils/modern-utils';

Technical Flow

┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ File watcher detects file save/change
    │
    ├─▶ LegacyPatternDetector scans file content
    │   - Reads `docs/mault.yaml` for deprecated patterns
    │   - Uses regex to find matches
    │   - Example: /from ['"].*\/legacy\/.*/
    │
    └─▶ Creates LegacyPatternViolation finding

┌─────────────────────────────────────────────────────────────┐
│ 2. NOTIFICATION                                             │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ LegacyPatternDiagnosticsPublisher creates diagnostic
    │   - Severity: Warning (yellow squiggly)
    │   - Message: "Deprecated: Use @/utils/modern-utils instead"
    │   - Range: Import statement line
    │
    ├─▶ Hover tooltip shows:
    │   "⚠️ Legacy Pattern Detected
    │    This import is deprecated.
    │    Recommended: import { utils } from '@/utils/modern-utils';"
    │
    └─▶ Status Bar updates: "⚠️ 1 legacy pattern"

┌─────────────────────────────────────────────────────────────┐
│ 3. USER ACTIONS                                             │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User clicks lightbulb (💡) icon
    │
    └─▶ Code Actions menu appears:
        ├─ 🔧 Quick Fix: Replace Deprecated Pattern (preferred)
        └─ 📋 Copy Migration Prompt

┌─────────────────────────────────────────────────────────────┐
│ 4. RESOLUTION (Option A: Quick Fix)                         │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User selects "Replace Deprecated Pattern"
    │
    ├─▶ Extension performs text replacement
    │   - Old: import { utils } from '../../../legacy/old-utils';
    │   - New: import { utils } from '@/utils/modern-utils';
    │
    └─▶ Diagnostic cleared, status bar updates: "✅ 0 issues"

┌─────────────────────────────────────────────────────────────┐
│ 5. RESOLUTION (Option B: AI Prompt)                         │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User selects "Copy Migration Prompt"
    │
    ├─▶ Extension generates prompt:
    │   "Replace all imports from '../../../legacy/old-utils' with
    │    '@/utils/modern-utils' across the entire project. Update
    │    any usage differences between the old and new API."
    │
    ├─▶ Prompt copied to clipboard
    │
    ├─▶ ClipCounter increments (usage tracking)
    │
    └─▶ User pastes into AI assistant

---

## 3. Convention Reinforcement

**Problem:** AI Coders are inconsistent with naming conventions (camelCase vs snake_case, etc.)

**Example:**
```typescript
❌ const user_name = "John";      // snake_case in TypeScript
✅ const userName = "John";       // camelCase (correct)

Technical Flow

┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                 │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ File watcher detects file save/change
    │
    ├─▶ NamingConventionDetector analyzes identifiers
    │   - Reads `docs/mault.yaml` for naming rules
    │   - Checks variables, functions, classes
    │   - Example rule: TypeScript variables → camelCase
    │
    └─▶ Creates NamingViolation finding

┌─────────────────────────────────────────────────────────────┐
│ 2. NOTIFICATION                                              │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ DiagnosticsPublisher creates diagnostic
    │   - Severity: Information (blue squiggly)
    │   - Message: "Use camelCase for variables (user_name → userName)"
    │   - Range: Variable name
    │
    └─▶ Status Bar updates: "ℹ️ 1 convention issue"

┌─────────────────────────────────────────────────────────────┐
│ 3. USER ACTIONS                                              │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User clicks lightbulb (💡) icon
    │
    └─▶ Code Actions menu appears:
        ├─ 🔧 Quick Fix: Rename to userName (preferred)
        └─ 📋 Copy Refactoring Prompt

┌─────────────────────────────────────────────────────────────┐
│ 4. RESOLUTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User selects "Rename to userName"
    │
    ├─▶ Extension performs rename refactoring
    │   - Uses VS Code's rename API
    │   - Updates all references
    │
    └─▶ Diagnostic cleared

---

## 4. Environment Reinforcement

**Problem:** Code uses OS-specific paths or commands that break on other platforms.

**Example:**
```typescript
❌ const path = "C:\\Users\\John\\file.txt";  // Windows-only
✅ const path = path.join(os.homedir(), "file.txt");  // Cross-platform

Technical Flow

┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ EnvironmentDetector scans for OS-specific code
    │   - Hard-coded Windows paths (C:\, D:\)
    │   - Hard-coded Unix paths (/usr/local/)
    │   - OS-specific commands (cmd.exe, bash)
    │
    └─▶ Creates EnvironmentViolation finding

┌─────────────────────────────────────────────────────────────┐
│ 2. NOTIFICATION                                             │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Diagnostic shows:
    │   "⚠️ Windows-specific path. Use path.join() for cross-platform."
    │
    └─▶ Status Bar updates: "⚠️ 1 environment issue"

┌─────────────────────────────────────────────────────────────┐
│ 3. RESOLUTION                                               │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Quick Fix: Replace with path.join()
    │
    └─▶ AI Prompt: "Refactor to use Node.js path module"

---

## 5. Application Flow Analysis (UC13)

> **Language Support:** JS/TS only (import analysis)

**Problem:** Changes to high-impact files break unrelated workflows due to hidden dependencies.

**Example:**
```typescript
// User opens AuthService.ts
// Warning: This file affects CheckoutFlow, AdminPanel, ReportGenerator
❌ Modify without knowing 47 files depend on it
✅ See impact analysis before making changes
```

### Technical Flow

┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION (on activation + file open)                    │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ DependencyGraphBuilder analyzes imports on activation
    │   - Scans workspace for TS/JS files (max 1000)
    │   - Builds dependentsMap and importsMap
    │   - Computes transitive dependencies via BFS
    │
    ├─▶ FlowMapper reads docs/mault.yaml
    │   - Maps files to business flows (auth, checkout, etc.)
    │   - Identifies critical flows for severity boosting
    │
    └─▶ On file open: Creates ImpactAnalysis finding

┌─────────────────────────────────────────────────────────────┐
│ 2. NOTIFICATION                                             │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ ApplicationFlowDiagnosticsPublisher creates diagnostic
    │   - Severity: Error (high) or Warning (medium)
    │   - Message: "[IMPACT] High-impact file: 5 direct,
    │              15 transitive | In flows: auth, payment"
    │
    └─▶ Problems Panel shows warning

┌─────────────────────────────────────────────────────────────┐
│ 3. USER ACTIONS                                             │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User clicks lightbulb icon
    │
    └─▶ Code Actions menu appears:
        ├─ Copy Impact Analysis Prompt (preferred)
        ├─ Show Impact Summary
        └─ Mault Fix: Add Tests (if no test file)

┌─────────────────────────────────────────────────────────────┐
│ 4. RESOLUTION                                               │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Quick Fix: Copy AI prompt with full dependency context
    │
    └─▶ AI Prompt: "Analyze high-impact file with 47 dependents
         across 3 business flows before refactoring"

---

## 6. Cleaning Temporary Files

**Problem:** `.log`, `.tmp`, `.cache` files clutter the workspace.

**Solution:** Detect and offer to delete temporary files.

### Technical Flow

```
┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ TempFileDetector scans workspace
    │   - Finds files matching temp patterns
    │   - Example: *.log, *.tmp, *.cache, node_modules/.cache
    │
    └─▶ Creates TempFileViolation findings

┌─────────────────────────────────────────────────────────────┐
│ 2. NOTIFICATION                                             │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Status Bar: "🗑️ 15 temp files found"
    │
    └─▶ Command: "Mault: Clean Temporary Files"

┌─────────────────────────────────────────────────────────────┐
│ 3. RESOLUTION                                               │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User runs command
    │
    ├─▶ Extension shows list of files to delete
    │
    ├─▶ User confirms
    │
    └─▶ Files deleted, .gitignore updated
```

---

## 7. Fixing Disorganized Structures

**Problem:** Flat directory structure with 100+ files in one folder.

**Solution:** Detect overcrowded folders and suggest reorganization.

### Technical Flow

```
┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ FlatArchitectureDetector counts files per directory
    │   - Threshold: 20+ files = overcrowded
    │   - Analyzes file types and patterns
    │
    └─▶ Creates FlatArchitectureViolation

┌─────────────────────────────────────────────────────────────┐
│ 2. NOTIFICATION                                             │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Diagnostic shows:
    │   "⚠️ src/ has 87 files. Consider organizing into subdirectories."
    │
    └─▶ Status Bar: "⚠️ 1 overcrowded folder"

┌─────────────────────────────────────────────────────────────┐
│ 3. RESOLUTION                                               │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ AI Prompt: "Analyze src/ and suggest folder structure"
    │
    └─▶ User applies AI-generated reorganization plan

---

## 8. Adding Missing Configs

**Problem:** Project missing `.editorconfig`, `.prettierrc`, etc.

**Solution:** Detect missing config files and offer to scaffold them.

### Technical Flow

```
┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ ConfigDetector checks for required files
    │   - .editorconfig
    │   - .prettierrc
    │   - .eslintrc
    │   - tsconfig.json
    │
    └─▶ Creates MissingConfigViolation

┌─────────────────────────────────────────────────────────────┐
│ 2. NOTIFICATION                                             │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Status Bar: "⚠️ 3 missing configs"
    │
    └─▶ Command: "Mault: Add Missing Configs"

┌─────────────────────────────────────────────────────────────┐
│ 3. RESOLUTION                                               │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ User runs command
    │
    ├─▶ Extension scaffolds config files
    │
    └─▶ Files created with sensible defaults
```

---

## 9. Consolidating Duplicates

**Problem:** Same utility function copied across multiple files.

**Solution:** Detect duplicate code and suggest consolidation.

### Technical Flow

```
┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION (Future - requires semantic analysis)          │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ DuplicateDetector analyzes code similarity
    │   - Uses AST comparison or embeddings
    │   - Finds functions with >80% similarity
    │
    └─▶ Creates DuplicateCodeViolation

┌─────────────────────────────────────────────────────────────┐
│ 2. NOTIFICATION                                             │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Diagnostic shows:
    │   "⚠️ This function is duplicated in 3 files"
    │
    └─▶ Status Bar: "⚠️ 5 duplicates found"

┌─────────────────────────────────────────────────────────────┐
│ 3. RESOLUTION                                               │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ AI Prompt: "Extract to shared utils/ and update imports"
    │
    └─▶ User applies refactoring

---

## 10. Standardizing Naming

**Problem:** Inconsistent file naming (kebab-case vs camelCase vs snake_case).

**Solution:** Detect naming inconsistencies and suggest standardization.

### Technical Flow

```
┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ FileNamingDetector scans all files
    │   - Checks file name patterns
    │   - Example: UserService.ts vs user-service.ts
    │
    └─▶ Creates FileNamingViolation

┌─────────────────────────────────────────────────────────────┐
│ 2. NOTIFICATION                                             │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Diagnostic shows:
    │   "⚠️ Use kebab-case for files (UserService.ts → user-service.ts)"
    │
    └─▶ Status Bar: "⚠️ 12 naming issues"

┌─────────────────────────────────────────────────────────────┐
│ 3. RESOLUTION                                               │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Quick Fix: Rename file to kebab-case
    │
    └─▶ Extension updates imports automatically
```

---

## 11. Organizing Overcrowded Folders

**Problem:** Single folder with 100+ files of different types.

**Solution:** Same as [#7](https://github.com/nootan-ai/mault-memory-layer/issues/7) (Fixing Disorganized Structures).

**Suggested Organization:**

```
Before:
src/
├── UserService.ts
├── ProductService.ts
├── OrderService.ts
├── UserController.ts
├── ProductController.ts
├── ... (95 more files)

After:
src/
├── services/
│   ├── UserService.ts
│   ├── ProductService.ts
│   └── OrderService.ts
├── controllers/
│   ├── UserController.ts
│   └── ProductController.ts
└── models/
    └── ...

---

## 12. Centralizing Shared Code

> **Language Support:** JS/TS only (import analysis for auto-update)

**Problem:** Utility functions scattered across project instead of in shared location.

**Solution:** Detect scattered utilities and suggest centralization.

### Technical Flow

```
┌─────────────────────────────────────────────────────────────┐
│ 1. DETECTION                                                │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ SharedCodeDetector finds utility-like files
    │   - Files with "helper", "util", "common" in name
    │   - Files outside utils/ or shared/ directories
    │
    └─▶ Creates ScatteredUtilityViolation

┌─────────────────────────────────────────────────────────────┐
│ 2. NOTIFICATION                                             │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Diagnostic shows:
    │   "⚠️ Utility file should be in src/utils/"
    │
    └─▶ Status Bar: "⚠️ 8 scattered utilities"

┌─────────────────────────────────────────────────────────────┐
│ 3. RESOLUTION                                               │
└─────────────────────────────────────────────────────────────┘
    │
    ├─▶ Quick Fix: Move to src/utils/
    │
    └─▶ Extension updates imports
```

---

## 13. Dependency Health [Core + Pro]

> **Language Support:** JS/TS only (npm/yarn/pnpm audit)

**Problem:** Security vulnerabilities in npm/yarn/pnpm dependencies go unnoticed until security audits or production incidents.

**Example:**
```typescript
// package.json has lodash@4.17.20
// Known vulnerability: GHSA-xxx-xxx (Prototype Pollution, High severity)
// Detection: "Vulnerable package: lodash@4.17.20 - GHSA-xxx-xxx (High)"
// Fix: npm audit fix or upgrade to 4.17.21
```

### Technical Flow

```
+---------------------------------------------------------+
| 1. DETECTION (on activation + manual trigger)           |
+---------------------------------------------------------+
    |
    +-> DependencyHealthDetector runs package manager audit
    |   - Detects package manager (npm/yarn/pnpm)
    |   - Executes audit command (npm audit --json)
    |   - Parses JSON output for vulnerabilities
    |
    +-> Maps audit results to findings
    |   - CVE/GHSA advisory identifiers
    |   - Severity mapping (critical, high, moderate, low)
    |   - Affected package and version
    |   - Remediation suggestion (fix version)
    |
    +-> Creates DependencyHealthFinding for each vulnerability

+---------------------------------------------------------+
| 2. NOTIFICATION                                         |
+---------------------------------------------------------+
    |
    +-> DependencyHealthDiagnosticsPublisher creates diagnostic
    |   - Severity: Error (critical/high) or Warning (moderate/low)
    |   - Message: "Vulnerable package: lodash@4.17.20 -
    |              GHSA-xxx-xxx (High severity)"
    |
    +-> Problems Panel shows vulnerability warnings
    |
    +-> Status Bar: Shows vulnerability count if > 0

+---------------------------------------------------------+
| 3. USER ACTIONS                                         |
+---------------------------------------------------------+
    |
    +-> User clicks lightbulb icon
    |
    +-> Code Actions menu appears:
        +- Copy Dependency Health Fix (preferred)
        +- Copy Dependency Health Prompt
        +- Run npm audit fix

+---------------------------------------------------------+
| 4. RESOLUTION                                           |
+---------------------------------------------------------+
    |
    +-> Quick Fix: Copy fix command to clipboard
    |   - "npm audit fix" or "npm update lodash@4.17.21"
    |
    +-> AI Prompt: "Analyze vulnerable dependency lodash@4.17.20
         with GHSA-xxx-xxx (High severity). Recommend upgrade
         path considering breaking changes."

---

## 14. Architecture Diagrams [Pro]

> **Language Support:** JS/TS (import analysis); Polyglot for file-level diagrams

**Problem:** Understanding large codebases is difficult without visualization. Developers need to see how files relate before making architectural changes.

**Example:**
```typescript
// User runs "Mault: Generate Architecture Diagram"
// Output: Mermaid diagram showing dependency relationships
//
// graph TD
//     AuthService --> TokenManager
//     AuthService --> UserRepository
//     CheckoutController --> AuthService
//     CheckoutController --> PaymentService
```

### Technical Flow

```
+---------------------------------------------------------+
| 1. DETECTION (on activation + file open)                |
+---------------------------------------------------------+
    |
    +-> DependencyGraphBuilder analyzes imports on activation
    |   - Scans workspace for TS/JS files (max 1000)
    |   - Builds dependentsMap and importsMap
    |   - Computes transitive dependencies via BFS
    |
    +-> FlowMapper reads docs/mault.yaml
    |   - Maps files to business flows (auth, checkout, etc.)
    |   - Identifies critical flows for severity boosting
    |
    +-> Caches dependency graph for diagram generation

+---------------------------------------------------------+
| 2. NOTIFICATION                                         |
+---------------------------------------------------------+
    |
    +-> ApplicationFlowDiagnosticsPublisher creates diagnostic
    |   - Severity: Error (high) or Warning (medium)
    |   - Message: "[IMPACT] High-impact file: 5 direct,
    |              15 transitive | In flows: auth, payment"
    |
    +-> Problems Panel shows warning
    |
    +-> Command Palette: "Mault: Generate Architecture Diagram"

+---------------------------------------------------------+
| 3. USER ACTIONS                                         |
+---------------------------------------------------------+
    |
    +-> User runs "Mault: Generate Architecture Diagram"
    |
    +-> Options menu appears:
        +- Generate Full Dependency Graph
        +- Generate Flow-Specific Diagram (select flow)
        +- Generate File-Centric Diagram (current file)
        +- Copy Mermaid to Clipboard

+---------------------------------------------------------+
| 4. DIAGRAM GENERATION                                   |
+---------------------------------------------------------+
    |
    +-> MermaidDiagramGenerator processes dependency graph
    |   - Converts dependentsMap to Mermaid syntax
    |   - Applies flow coloring (auth=blue, payment=green)
    |   - Highlights high-impact nodes (thicker borders)
    |   - Limits nodes for readability (configurable max)
    |
    +-> Output options:
        +- Preview in VS Code webview panel
        +- Copy Mermaid code to clipboard
        +- Export as PNG/SVG (via Mermaid CLI)

+---------------------------------------------------------+
| 5. VISUALIZATION OUTPUT                                 |
+---------------------------------------------------------+
    |
    +-> Webview Panel displays interactive diagram
    |   - Click node to open file
    |   - Hover for dependency count tooltip
    |   - Zoom/pan controls
    |
    +-> Mermaid code example:
        graph TD
            subgraph Authentication
                AuthService[AuthService.ts]
                TokenManager[TokenManager.ts]
                UserRepository[UserRepository.ts]
            end
            subgraph Checkout
                CheckoutController[CheckoutController.ts]
                PaymentService[PaymentService.ts]
            end
            AuthService --> TokenManager
            AuthService --> UserRepository
            CheckoutController --> AuthService
            CheckoutController --> PaymentService
            style AuthService fill:#ff6b6b,stroke:#333,stroke-width:3px

---

## 15. Structural Governance [Core + Pro]

> **Language Support:** JS/TS (AST analysis), Python (AST analysis)

**Problem:** Teams establish architectural patterns (all services must export a specific interface, handlers must follow a signature) but have no way to enforce them. AI coders generate code that ignores established patterns.

**Example:**
```typescript
// governance.rules in mault.yaml requires:
// - All services export a default class
// - All handlers have handle(request, response) signature
// - No console.log in production code

// StructuralComplianceDetector finds:
❌ src/services/UserService.ts - Missing default export
❌ src/handlers/AuthHandler.ts - handle() missing 'response' param
❌ src/utils/logger.ts - Forbidden pattern: console.log
✅ src/services/PaymentService.ts - Compliant
```

### Technical Flow

```
+---------------------------------------------------------+
| 1. DETECTION (on file save + manual trigger)            |
+---------------------------------------------------------+
    |
    +-> StructuralComplianceDetector loads governance rules
    |   - Reads governance.rules from docs/mault.yaml
    |   - Validates rule configuration via configLoader
    |   - Groups rules by target file patterns
    |
    +-> For each file matching rule targets:
    |
    +-> SYNC: Structural Assertions (Core)
    |   |
    |   +-> export_exists: Check named exports match pattern
    |   |   - Uses TypeScript AST to find export declarations
    |   |   - Validates export name/kind against assertion
    |   |
    |   +-> function_signature: Validate function params/returns
    |   |   - Parses function declarations via AST
    |   |   - Compares params against requiredParams
    |   |
    |   +-> import_exists: Check required imports present
    |   |   - Scans import declarations
    |   |   - Validates module specifiers
    |   |
    |   +-> ast_skeleton: Match against structural templates
    |   |   - Uses skeletonMatcher for pattern matching
    |   |   - Compares AST structure against template
    |   |
    |   +-> forbidden_pattern: Detect banned code patterns
    |       - Applies regex patterns to file content
    |       - Flags matches with line/column positions
    |
    +-> ASYNC: Semantic Similarity (Pro-only)
        |
        +-> semantic_similarity: Compare against gold standard
            - Normalizes code (strips comments/whitespace)
            - Generates embeddings via OpenAI API
            - Queries Pinecone vector database
            - Returns similarity score vs threshold

+---------------------------------------------------------+
| 2. NOTIFICATION                                         |
+---------------------------------------------------------+
    |
    +-> StructuralGovernanceDiagnosticsPublisher creates diagnostic
    |   - Severity: Error (structural) or Warning (semantic below threshold)
    |   - Message varies by assertion type:
    |     • "Missing required export: default class"
    |     • "Function 'handle' missing parameter: response"
    |     • "Forbidden pattern detected: console.log"
    |     • "Similarity score 0.45 below threshold 0.70"
    |
    +-> Problems Panel shows violations grouped by file
    |
    +-> Status Bar: Shows violation count

+---------------------------------------------------------+
| 3. USER ACTIONS                                         |
+---------------------------------------------------------+
    |
    +-> User clicks lightbulb icon
    |
    +-> Code Actions menu appears:
        +- Copy Structural Governance Prompt (preferred)
        +- Show Violation Details
        +- View Gold Standard Example (semantic only)

+---------------------------------------------------------+
| 4. RESOLUTION                                           |
+---------------------------------------------------------+
    |
    +-> AI Prompt generated with full context:
    |   - Rule ID and assertion type
    |   - Expected pattern/signature/structure
    |   - Current code snippet
    |   - Similar implementations (for semantic)
    |
    +-> User applies fix manually or via AI assistant
    |
    +-> Re-scan on save clears resolved violations

---

## Pro: Production Readiness Kit

> **Tier**: Pro-only ($99 one-time) | **Requires**: Active Core subscription

The Production Readiness Kit is a structured 8-step journey that takes your project from "runs locally" to "production-ready." It provides battle-tested philosophy guides that any AI coder can follow to set up production infrastructure.

### Production Readiness Levels

| Level | Name | What It Means | Artifacts Created |
|-------|------|---------------|-------------------|
| 0 | Runs primarily locally | Core analysis executes on your machine; some features may make network requests | Just code |
| 1 | Reproducible | Someone else can run it | requirements.txt, .env.example |
| 2 | Portable | Runs in a container | Dockerfile, docker-compose.yml |
| 3 | Deployed | Runs in the cloud | CI/CD pipeline, cloud config |
| 4 | Reliable | Stays running | Health checks, logging, rollback |

**The Kit takes you from Level 0 → Level 4.**

### Philosophy Guides

These guides explain the **WHY** behind enforcement. AI coders read them and generate language-specific scripts.

#### Rising Tide (Mock Tax)

**The 2x Rule**: If a unit test is more than 2x the size of the source code, delete the unit test and write an integration test instead.

```
Test : Source Ratio    Interpretation        Action
──────────────────────────────────────────────────────────
< 1.0x                 Under-tested          Add more test cases
1.0x - 2.0x            Healthy               Maintain
2.0x - 3.0x            Mock Tax Warning      Consider integration test
> 3.0x                 Excessive             Delete, rewrite as integration
```

**Why**: Tests larger than their source code indicate tight coupling and excessive mocking. These tests are brittle and don't catch real bugs.

#### Iron Dome (Type Safety)

**The Ratchet Rule**: Type-safety holes (`any`, `type: ignore`, `eslint-disable`) can only decrease, never increase.

```
NEW holes BLOCKED           OLD holes GRANDFATHERED
─────────────────           ───────────────────────
Cannot add new `any`        Existing `any` allowed
Cannot add new `ignore`     Existing `ignore` allowed
Cannot disable more rules   Existing disables allowed

Result: Quality can only IMPROVE over time.
```

**Type Safety Holes by Language**:

| Language | Holes to Track |
|----------|----------------|
| TypeScript | `any`, `as any`, `@ts-ignore`, `@ts-expect-error`, `!` |
| Python | `type: ignore`, `Any`, `cast()`, `# noqa` |
| Go | `interface{}`, `any`, type assertions, `//nolint` |
| Java | Raw types, `@SuppressWarnings("unchecked")`, unchecked casts |

#### TDD Guide

**Red-Green-Refactor**:

```
1. RED     → Write failing test (captures intent)
2. GREEN   → Write minimum code to pass
3. REFACTOR → Clean up while tests protect
```

**The Pure Core Pattern**: Business logic with no I/O imports (easy to test). Adapters are thin wrappers for I/O (tested via integration tests).

#### Ratchet Strategy

**Baseline + Improvement**: Count current violations, set as baseline, block any increase.

```
Day 0:  Generate baseline → 127 type holes
Day 5:  Developer adds 2 → BLOCKED (129 > 127)
Day 10: Developer fixes 5 → New baseline: 122
Day 30: Overall: 127 → 98 (23% reduction)
```

### Pre-commit Layers (Language-Specific)

The Kit sets up pre-commit hooks with up to 9 layers of protection. These are **language-specific governance patterns** that AI generates for your stack—use TypeScript as the reference implementation and adapt for your language:

**TypeScript Reference (9 Layers)**:

| Layer | Name | Purpose |
|-------|------|---------|
| 1 | Compilation & Static Analysis | Catch type errors Jest might mask |
| 2 | Rising Tide (Mock Tax) | Block oversized unit tests (2x rule) |
| 3 | Test Impact Analysis (TIA) | Run only affected tests |
| 4 | Adversarial Mock Scan | Prevent mocking reality |
| 5 | Precision Coverage Ratchet | Enforce 80% on new files |
| 6 | Security Gate | npm audit for vulnerabilities |
| 7 | Integration Test Pairing | Buddy System enforcement |
| 8 | Type Safety Gate (any Ratchet) | Block new `any` usage |
| 9 | Dead Code Gate | Detect silent catches |

These patterns apply to any language—AI adapts them to your stack (pytest for Python, go test for Go, JUnit for Java, etc.).

### Polyglot Detectors (All Languages)

In addition to language-specific hooks, Mault provides **9 polyglot detectors** that work with ANY language. These enforce architectural rules regardless of your stack:

| UC | Detector | What It Blocks |
|----|----------|----------------|
| UC01 | Directory Reinforcement | Files in wrong directories |
| UC02 | Legacy Prevention | Files in deprecated paths |
| UC04 | Environment Reinforcement | Missing/malformed .env |
| UC06 | Temp File Cleanup | Temp files in commits |
| UC07 | Flat Architecture | Too many files in root |
| UC08 | Config Chaos | Config files misplaced |
| UC09 | File Proliferation | Duplicate files |
| UC11 | Overcrowded Folders | Too many files per folder |
| UC13 | Application Flows | High-impact file warnings |

These detectors are initialized via Step 7 ("Initialize Mault Hook") and work on Python, Go, Java, Rust, or any other language.

### Language-Specific Pro Detectors

The following Pro detectors provide additional pre-commit enforcement. AI coders should include these in Step 6 (Pre-commit Framework) when working with supported languages:

| UC | Detector | Language Support | What It Blocks |
|----|----------|------------------|----------------|
| UC16 | Dependency Health | JS/TS (npm audit) | Vulnerable packages, outdated deps |
| UC18 | Structural Governance | JS/TS (AST), Python (AST) | Missing exports, forbidden patterns, DI violations |

**AI Coder Guidance**: When setting up pre-commit hooks in Step 6:

1. **For JS/TS projects**: Add `npm audit --audit-level=high` as a pre-commit hook for UC16, and configure UC18 structural rules in `mault.yaml` under `governance.rules`

2. **For Python projects**: UC18 structural governance works via AST analysis. Configure rules in `mault.yaml`

3. **For other languages**: These detectors are roadmapped for Go (go mod audit), Java (OWASP Dependency-Check), and Rust (cargo audit). Until then, AI coders should add equivalent tooling to pre-commit manually

**Example pre-commit entry for UC16 (JS/TS)**:
```yaml
- repo: local
  hooks:
    - id: dependency-health
      name: Dependency Health (UC16)
      entry: npm audit --audit-level=high
      language: system
      pass_filenames: false
      stages: [commit]
```

### Files Created

After running the Production Readiness Kit, your project will have:

```
your-project/
├── .git/                           # Step 1
├── .gitignore                      # Step 1
├── .env.example                    # Step 2
├── Dockerfile                      # Step 3
├── docker-compose.yml              # Step 3
├── .dockerignore                   # Step 3
├── .github/
│   └── workflows/
│       └── ci.yml                  # Step 4
├── tests/
│   ├── unit/
│   │   └── governance/             # Step 8
│   └── integration/                # Step 5
├── .pre-commit-config.yaml         # Steps 6, 7, 8
├── scripts/
│   └── governance/                 # Step 8
│       ├── check-mock-tax.{js,py}
│       ├── check-type-safety.{js,py}
│       └── check-coverage-ratchet.{js,py}
└── .memory-layer/
    └── baselines/                  # Step 8
        ├── coverage.json
        ├── type-safety.json
        └── mock-tax.json
```

### Language Support

The Kit is **language-agnostic**. AI generates appropriate scripts for your stack:

| Component | TypeScript/JS | Python | Go | Java |
|-----------|---------------|--------|-----|------|
| Test Framework | Jest, Vitest | pytest | go test | JUnit 5 |
| Type Checking | TypeScript | mypy | Go compiler | Java compiler |
| Linting | ESLint | ruff, flake8 | golangci-lint | Checkstyle |
| Pre-commit | pre-commit | pre-commit | pre-commit | pre-commit |

### Core Principle: Physics, Not Policy

> **"Agents obey Physics, not Policy"**

- **Policy**: Documentation, guidelines, best practices → AI ignores these
- **Physics**: Errors, blocked commits, failed CI → AI cannot bypass these

Every rule in the Production-Readiness Kit is enforced as **physics**:
- `warn` is policy (AI ignores)
- `error` is physics (AI cannot proceed)

### For Existing Projects

Same setup process, but AI detects what already exists:
- Has Git? → Skip Step 1
- Has Dockerfile? → Skip Step 3
- Has pre-commit? → Skip Step 6

**Rising Tide for Legacy**: Existing issues are grandfathered, new issues are blocked. Quality only improves.

---

## Data & Privacy Disclosure

Mault performs core governance and integrity analysis **locally** within VS Code. Certain features, such as dependency health checks, may perform network requests to retrieve external metadata.

**What connects to the internet:**

- **Authentication**: Email/OAuth for account creation
- **Payments**: Processed securely via Stripe (we never store card details)
- **Entitlement checks**: Subscription validation
- **Error reporting**: Crash diagnostics, no code content
- **Usage analytics**: Feature metrics, opt-out via `mault.usage.enabled` setting

**AI-powered features (optional, user-invoked only):**

- Code snippets may be processed to generate semantic embeddings
- Embeddings are stored for search functionality
- Raw code is not stored; embeddings cannot reconstruct source code

**What we don't do:**

- No user code is stored on external servers
- No data is used for AI model training
- No payment card details are stored by Mault (handled entirely by Stripe)

For full details, see our [Privacy Policy](https://mault.ai/privacy/).

## Important Disclosures

- **Backend Connection**: This extension connects to Mault's backend service for authentication, payments, and subscription management.
- **Account Required**: A Mault account is required to use this extension.
- **Subscription**: Some features may require a paid subscription ($7.99/month after 30-day free trial).
- **Links**: [Privacy Policy](https://mault.ai/privacy/) | [Terms of Service](https://mault.ai/terms/) | [Billing](https://mault.ai/billing/)

---

## License

The Mault VS Code extension is licensed under the [Apache License, Version 2.0](https://github.com/nootan-ai/mault-memory-layer/blob/HEAD/LICENSE).

Use of Mault's cloud services is governed separately by [Mault's Terms of Service](https://mault.ai/terms/).

## Legal & Support

- [Privacy Policy](https://mault.ai/privacy/)
- [Terms of Service](https://mault.ai/terms/)
- [Billing](https://mault.ai/billing/)
- [Cookie Policy](https://mault.ai/cookie-policy/)
- [Support](mailto:support@mault.ai)

Mault (Beta)

Mault

Mault AI-Assisted Code Quality Extension

How It Works

Mault Core (Included in 30-Day Free Trial)

Option A: AI-Assisted Setup

Option B: DIY Setup

After Setup: Monitor & Fix

Mault Pro ($99 One-Time Add-On)

What Pro Unlocks

Getting Started with Pro

The 8-Step Journey

Commands

Setup & Configuration

AI Prompt Generation (Clipboard)

Analysis & Summaries

File Operations

Pro Features

14 Architectural Detectors

Requirements

Pricing

Release Notes

1. Directory Reinforcement

Technical Flow

Technical Flow

Technical Flow

Technical Flow