Mault

Contact Us

Mault
Docs
Get Started

AI Coder Guide

Mault Core – AI Coder Guide
READ THIS FIRST: This document helps AI coding assistants (Cursor, Copilot, ChatGPT, Claude) understand and maintain `mault.yaml` — the project’s architectural rulebook.
 
What is Mault?
Mault automates architectural discipline for AI-assisted development. It’s a VS Code extension that:
1. Detects architectural violations in real-time (wrong file locations, deprecated patterns, naming chaos)
2. Advises with context-rich prompts explaining why something is wrong and how to fix it
3. Enforces project conventions defined in `docs/mault.yaml`
Why it matters for AI coders: AI coding tools are fast but lack architectural memory. They write messy code if they see messy code. Mault gives you the rulebook so you can **maintain consistency** across the codebase.
 
Quick Setup (New Projects)
CRITICAL: The mault.yaml configuration MUST match your actual project structure. Generic templates won’t work. You MUST scan the codebase first.  
Step 1: Detect Language
Look for indicator files:
| If you find… | Language | Test Pattern | Function Naming |
| `tsconfig.json`, `*.ts` files | **TypeScript** | `*.test.ts`, `*.spec.ts` | `camelCase` |
| `package.json` (no tsconfig) | **JavaScript** | `*.test.js`, `*.spec.js` | `camelCase` |
| `pyproject.toml`, `requirements.txt`, `setup.py` | **Python** | `test_*.py`, `*_test.py` | `snake_case` |
 
Step 2: Map Directory Structure
Run `ls -la` or `tree -L 2` to discover:
“`bash What is the source directory?
-src/ ← TypeScript standard
-lib/ ← Some Node.js projects
-app/ ← Python Flask/Django
–/ ← Python with package name
-(flat) ← All code in root
Where are services/business logic?
– src/services/, lib/services/, app/services/, or none
# Where are utilities?
-src/utils/, src/helpers/, lib/utils/, common/, or none
 
Where are tests?
-tests/, __tests__/, test/, or colocated (src/**/*.test.ts)
 
Step 3: Record What You Found
Before writing mault.yaml, note:
– **Source directory**: _______ (e.g., `src`, `lib`, `app`, or root)
– **Services location**: _______ (e.g., `src/services`, or none)
– **Utils location**: _______ (e.g., `src/utils`, `helpers`, or none)
– **Models location**: _______ (e.g., `src/models`, or none)
– **Tests location**: _______ (e.g., `tests`, `__tests__`, or colocated)
– **Config files present**: _______ (e.g., `.gitignore`, `package.json`)
 
Step 4: Create docs/mault.yaml
Create the file using the template below, **replacing ALL paths with what you discovered**.
 
your-project/
├─▶ docs/
└── mault.yaml ← CREATE THIS FILE
├─▶ [source-dir]/ ← Whatever you discovered
└── [config-files]
 
TypeScript/JavaScript Template
WARNING: Replace all `src/` paths with YOUR actual source directory.
 
yaml
version: 1
 
environment:
apiPort: 3000
shell: “bash” # or “powershell” for Windows
 
conventions:
directories:
– pattern: “**/*.test.ts”
location: “tests/” # ← REPLACE with your test location
– pattern: “**/*.spec.ts”
location: “tests/” # ← REPLACE with your test location
 
naming:
– filePattern: “*.ts”
className: “PascalCase”
functionName: “camelCase”
constantName: “SCREAMING_SNAKE_CASE”
 
deprecatedPatterns:
– id: dep-moment
import: moment
message: “Use date-fns or dayjs instead of moment.”
languages: [typescript, javascript]
– id: dep-request import: request message: “Use axios or node-fetch instead of request.” languages: [typescript, javascript]  
Add project-specific deprecated patterns here
 
Detectors:
environmentReinforcement:
enabled: true
checkPaths: true
checkCommands: true
 
directoryReinforcement:
enabled: true
rules:
# ⚠️ CUSTOMIZE THESE PATHS for your project structure
– pattern: “**/*Service.ts”
expectedDir: “src/services” # ← REPLACE with your services location
reason: “Service files should be in src/services/”
– pattern: “**/*Util*.ts”
expectedDir: “src/utils” # ← REPLACE with your utils location
reason: “Utility files should be in src/utils/”
– pattern: “**/*Helper*.ts”
expectedDir: “src/utils” # ← REPLACE with your utils location
reason: “Helper files should be in src/utils/”
– pattern: “**/*.test.ts”
expectedDir: “tests” # ← REPLACE with your tests location
reason: “Test files should be in tests/”
 
flatArchitecture:
enabled: true
targets:
– path: “src” # ← REPLACE with your source directory
maxRootFiles: 10
minSubdirs: 3
excludePatterns: [“dist/**”, “node_modules/**”]
 
configChaos:
enabled: true
requiredConfigs:
– “.gitignore”
– “package.json”
– “tsconfig.json”
 
tempFiles:
enabled: true
patterns:
– “**/*.tmp”
– “**/temp_*”
– “**/scratch_*”
– “**/*.bak”
– “**/debug_*”
 
fileProliferation:
enabled: true
threshold: 3
 
overcrowdedFolders:
enabled: true
targets:
– path: “src” # ← REPLACE with your source directory
maxFiles: 20
– path: “src/utils” # ← REPLACE with your utils location
maxFiles: 15
 
Python Template
WARNING: Python projects vary widely. Replace ALL paths with your actual structure.
 
yaml
version: 1
 
environment:
apiPort: 8000
shell: “bash”
 
conventions:
directories:
– pattern: “**/test_*.py”
location: “tests/” # ← REPLACE with your test location
– pattern: “**/*_test.py”
location: “tests/” # ← REPLACE with your test location
 
naming:
– filePattern: “*.py”
className: “PascalCase”
functionName: “snake_case”
variableName: “snake_case”
constantName: “SCREAMING_SNAKE_CASE”
 
deprecatedPatterns:
– id: dep-optparse
import: optparse
message: “Use argparse instead of optparse.”
languages: [python]
 
– id: dep-urllib2
import: urllib2
message: “Use urllib.request instead (Python 3).”
languages: [python]
 
– id: dep-imp
import: imp
message: “Use importlib instead of imp.”
languages: [python]
 
Add project-specific deprecated patterns here
 
Detectors:
environmentReinforcement:
enabled: true
checkPaths: true
checkCommands: true
 
directoryReinforcement:
enabled: true
rules:
# ⚠️ CUSTOMIZE THESE PATHS for your project structure
– pattern: “**/*_service.py”
expectedDir: “app/services” # ← REPLACE: could be src/, app/, or package name
reason: “Service files should be in app/services/”
 
– pattern: “**/*_util*.py”
expectedDir: “app/utils” # ← REPLACE with your utils location
reason: “Utility files should be in app/utils/”
 
– pattern: “**/test_*.py”
expectedDir: “tests” # ← REPLACE with your tests location
reason: “Test files should be in tests/”
 
flatArchitecture:
enabled: true
targets:
– path: “.” # Python often uses root, not src/
maxRootFiles: 15
minSubdirs: 2
excludePatterns: [“venv/**”, “.venv/**”, “__pycache__/**”, “.git/**”]
 
configChaos:
enabled: true
requiredConfigs:
– “.gitignore”
– “requirements.txt”
optionalConfigs:
– “pyproject.toml”
– “setup.py”
 
tempFiles:
enabled: true
patterns:
– “**/*.tmp”
– “**/temp_*”
– “**/scratch_*”
– “**/*.bak”
– “**/debug_*”
– “**/.ipynb_checkpoints/**”
 
fileProliferation:
enabled: true
threshold: 3
 
overcrowdedFolders:
enabled: true
targets:
– path: “app” # ← REPLACE with your source directory
maxFiles: 20
 
If a Directory Doesn’t Exist
If your project has no `services/` folder, you have two choices:
1. Skip the rule — Don’t include `directoryReinforcement` rules for it
2. Establish the convention — Keep the rule to guide future file placement
 
After Setup
Once `docs/mault.yaml` exists:
1. Reload VS Code to activate Mault’s detectors
2. Problems Panel shows any violations (`Ctrl+Shift+M` / `Cmd+Shift+M`)
3. Quick Fix (`Ctrl+.` / `Cmd+.`) offers remediation options
 
When to Update mault.yaml
Update the rulebook when you:
 
| Action | Update Section |
| Create a new directory structure | `Detectors.directoryReinforcement.rules` |
| Establish a naming convention | `conventions.naming` |
| Deprecate an old library/pattern | `deprecatedPatterns` |
| Create a new business flow | `applicationFlows` |
| Add required configuration files | `Detectors.configChaos.requiredConfigs` |
 
Example: Adding a New Directory Rule
If you create a new `src/adapters/` directory for external API adapters:
 
“`yaml
Detectors:
directoryReinforcement:
rules:
# … existing rules …
– pattern: “**/*Adapter.ts”
expectedDir: “src/adapters”
reason: “Adapter files should be in src/adapters/”
 
Example: Deprecating a Pattern
If you’re migrating from `axios` to `fetch`:
 
“`yaml
deprecatedPatterns:
– id: axios-deprecated
import: axios
message: “Use native fetch API. See docs/migration/axios-to-fetch.md”
languages: [typescript, javascript]
 
Built-in Detectors (No Config Required)
These detectors work automatically without mault.yaml:
 
| UC | Detector | What It Catches |
| UC10 | Naming Chaos | Inconsistent naming in same folder (detects dominant pattern) |
| UC16 | Dependency Health | Vulnerable npm/pip packages |
| UC17 | Architecture Diagrams | Visualizes dependencies (Pro) |
 
Config-Dependent Detectors
These require mault.yaml configuration:
 
| UC | Detector | Config Section |
| UC01 | Directory Reinforcement | `Detectors.directoryReinforcement.rules` |
| UC02 | Legacy Path Prevention | `deprecatedPatterns` |
| UC03 | Convention Reinforcement | `conventions.naming` |
| UC04 | Environment Reinforcement | `Detectors.environmentReinforcement` |
| UC06 | Temporary Files | `Detectors.tempFiles.patterns` |
| UC07 | Flat Architecture | `Detectors.flatArchitecture.targets` |
| UC08 | Configuration Chaos | `Detectors.configChaos.requiredConfigs` |
| UC09 | File Proliferation | `Detectors.fileProliferation` |
| UC11 | Overcrowded Folders | `Detectors.overcrowdedFolders.targets` |
| UC13 | Application Flows | `applicationFlows`, `flows` |
| UC18 | Structural Governance (Pro) | `rules` |
 
Available 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 this setup guide |
| `Mault: Audit Configuration` | Check mault.yaml validity |
| `Mault: Set Detection Level` | Adjust diagnostic sensitivity |
 
AI Prompt Generation
| 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 naming convention fix prompt` | Naming violation fix prompt |
 
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` | Single file rename |
| `Mault: Batch rename all files` | Batch rename |
 
Best Practices
1. Scan Before Writing
Always run `ls -la` or `tree -L 2` before creating mault.yaml. Never assume `src/` exists.
2. Replace ALL Template Paths
Every `src/services`, `src/utils`, `tests/` in the template must be replaced with your actual paths.
3. Update Rules When Creating Patterns
When you establish a new pattern (e.g., “all adapters go in `src/adapters/`”), add it to mault.yaml.
4. Check Diagnostics After Changes
Run `Mault: Show Findings Summary` to see if your changes introduced violations.
 
File Locations
| Purpose | Path |
|———|——|
| Project rulebook | `docs/mault.yaml` |
| Extension logs | `.memory-layer/logs/` |
| Cached rules | `.memory-layer/cache/` |
| Exported reports | `.memory-layer/reports/` |
| Archived files | `.memory-layer/archive/` |
 
Complete Reference
For complete templates with all UC configurations (UC01-UC18), see:
`docs/guides/mault-golden.md`
 
Remember: Mault is your architectural memory. The configuration MUST match your actual project structure — scan first, then customize.
Complete Configuration Reference
For AI Coders: This document contains comprehensive mault.yaml templates covering all Use Cases (UC01-UC18). Use this as a reference when the Quick Setup templates don’t cover your needs.
 
File Structure
 
“`yaml
version: 1
 
environment:
# Runtime settings
 
conventions:
# UC03: Naming conventions
 
deprecatedPatterns:
# UC02: Legacy imports to flag
 
applicationFlows:
# UC13: Business flow definitions
 
flows:
# UC13: Detailed flow mappings
 
applicationFlowBlindness:
# UC13: Dependency thresholds
 
Detectors:
# UC01, UC04, UC06, UC07, UC08, UC09, UC11 configurations
 
rules:
# UC18: Structural governance rules (Pro)
 
Reference Template: TypeScript/JavaScript
WARNING: This is a REFERENCE template. You MUST customize the paths based on Step 1.
– All `src/` paths should be replaced with YOUR actual source directory.
-All `src/services/`, `src/utils/`, etc. should match YOUR project structure.
 
“`yaml
Mault Configuration for TypeScript/JavaScript Projects
version: 1
 
ENVIRONMENT SETTINGS
environment:
apiPort: 3000
shell: “bash” # Options: bash, powershell, cmd, zsh
 
UC03: NAMING CONVENTIONS
 
conventions:
directories:
– pattern: “**/*.test.ts”
location: “tests/”
– pattern: “**/*.spec.ts”
location: “tests/”
– pattern: “**/*.test.tsx”
location: “tests/”
– pattern: “**/*.test.js”
location: “tests/”
 
naming:
– filePattern: “*.ts”
className: “PascalCase”
functionName: “camelCase”
constantName: “SCREAMING_SNAKE_CASE”
– filePattern: “*.tsx”
className: “PascalCase”
functionName: “camelCase”
– filePattern: “*.js”
className: “PascalCase”
functionName: “camelCase”
– filePattern: “*.jsx”
className: “PascalCase”
functionName: “camelCase”
 
UC02: LEGACY PATH PREVENTION
 
Detects deprecated imports and function calls
deprecatedPatterns:
Deprecated Libraries
– id: dep-moment
import: moment
message: “Deprecated library ‘moment’. Use ‘date-fns’ or ‘dayjs’ instead.”
languages: [typescript, javascript]
 
– id: dep-request
import: request
message: “Deprecated library ‘request’. Use ‘axios’ or ‘node-fetch’ instead.”
languages: [typescript, javascript]
 
– id: dep-request-promise
import: request-promise
message: “Deprecated ‘request-promise’. Use ‘axios’ or ‘node-fetch’ instead.”
languages: [typescript, javascript]
 
– id: dep-underscore
import: underscore
message: “Use lodash or native array methods instead of underscore.”
languages: [typescript, javascript]
 
– id: dep-colors
import: colors
message: “colors package was compromised. Use ‘chalk’ or ‘picocolors’ instead.”
languages: [typescript, javascript]
 
– id: dep-faker
import: faker
message: “faker.js is abandoned. Use ‘@faker-js/faker’ instead.”
languages: [typescript, javascript]
 
– id: dep-left-pad
import: left-pad
message: “left-pad is obsolete. Use String.padStart() instead.”
languages: [typescript, javascript]
 
– id: dep-node-uuid
import: node-uuid
message: “node-uuid is deprecated. Use ‘uuid’ package instead.”
languages: [typescript, javascript]
 
Deprecated Node.js APIs
– id: dep-sync-exec
functionCall: execSync
message: “Avoid synchronous exec. Use async exec, spawn, or execa instead.”
languages: [typescript, javascript]
 
– id: dep-sync-read
functionCall: readFileSync
message: “Consider async fs.readFile or fs/promises for non-blocking I/O.”
languages: [typescript, javascript]
 
– id: dep-sync-write
functionCall: writeFileSync
message: “Consider async fs.writeFile or fs/promises for non-blocking I/O.”
languages: [typescript, javascript]
 
React Deprecations
– id: dep-class-components
functionCall: React.Component
message: “Class components are legacy. Use functional components with Hooks.”
languages: [typescript, javascript]
 
– id: dep-createReactClass
functionCall: createReactClass
message: “createReactClass is deprecated. Use ES6 classes or functional components.”
languages: [typescript, javascript]
 
– id: dep-componentWillMount
functionCall: componentWillMount
message: “componentWillMount is deprecated. Use componentDidMount or useEffect.”
languages: [typescript, javascript]  
– id: dep-componentWillReceiveProps
functionCall: componentWillReceiveProps
message: “componentWillReceiveProps is deprecated. Use getDerivedStateFromProps.”
languages: [typescript, javascript]
 
Versioned API Deprecations
– id: dep-api-v1
import: “./api_v1”
message: “API v1 is deprecated. Migrate to current API version.”
languages: [typescript, javascript]
 
– id: dep-api-v1-relative
import: “../api_v1”
message: “API v1 is deprecated. Migrate to current API version.”
languages: [typescript, javascript]
 
UC13: APPLICATION FLOW ANALYSIS
Maps files to business flows for impact analysis
 
applicationFlows:
– id: authentication
name: “Authentication Flow”
description: “User login, logout, session, and token management”
 
– id: data-access
name: “Data Access Layer”
description: “Database connections, ORM, and repository operations”
 
– id: api-core
name: “API Core”
description: “Main API endpoints, routing, and request handling”
 
– id: business-logic
name: “Business Logic”
description: “Core business rules and domain services”
 
flows:
authentication:
name: “Authentication Flow”
description: “User authentication, authorization, and session management”
critical: true
files:
– “src/**/auth*.ts”
– “src/**/Auth*.ts”
– “src/**/login*.ts”
– “src/**/session*.ts”
– “src/**/token*.ts”
– “src/middleware/auth*.ts”
 
data-access:
name: “Data Access Layer”
description: “Database and ORM operations”
critical: true
files:
– “src/**/db*.ts”
– “src/**/database*.ts”
– “src/**/repository*.ts”
– “src/**/Repository*.ts”
– “src/models/**/*.ts”
 
api-core:
name: “API Core”
description: “Main API routing and handlers”
critical: true
files:
– “src/**/api*.ts”
– “src/**/router*.ts”
– “src/**/routes*.ts”
– “src/controllers/**/*.ts”
– “src/handlers/**/*.ts”
 
business-logic:
name: “Business Logic”
description: “Core business rules and domain services”
critical: true
files:
– “src/services/**/*.ts”
– “src/domain/**/*.ts”
 
applicationFlowBlindness:
enabled: true
thresholds:
warnOnDirectDependents: 5
warnOnTransitiveDependents: 15
excludePatterns:
– “**/node_modules/**”
– “**/*.test.ts”
– “**/*.spec.ts”
– “**/dist/**”
– “**/build/**”
– “**/__tests__/**”
– “**/__mocks__/**”
 
DETECTORS CONFIGURATION
 
Detectors:
UC04: Environment Reinforcement
environmentReinforcement:
enabled: true
checkPaths: true
checkCommands: true
 
UC01: Directory Reinforcement
directoryReinforcement:
enabled: true
rules:
Service files
– pattern: “**/*Service.ts”
expectedDir: “src/services”
reason: “Service files should be in src/services/”
– pattern: “**/*service.ts”
expectedDir: “src/services”
reason: “Service files should be in src/services/”
 
Controller files
– pattern: “**/*Controller.ts”
expectedDir: “src/controllers”
reason: “Controller files should be in src/controllers/”
– pattern: “**/*controller.ts”
expectedDir: “src/controllers”
reason: “Controller files should be in src/controllers/”
 
Handler files
– pattern: “**/*Handler.ts”
expectedDir: “src/handlers”
reason: “Handler files should be in src/handlers/”
– pattern: “**/*handler.ts”
expectedDir: “src/handlers”
reason: “Handler files should be in src/handlers/”
 
Utility files
– pattern: “**/*Util*.ts”
expectedDir: “src/utils”
reason: “Utility files should be in src/utils/”
– pattern: “**/*util*.ts”
expectedDir: “src/utils”
reason: “Utility files should be in src/utils/”
– pattern: “**/*Helper*.ts”
expectedDir: “src/utils”
reason: “Helper files should be in src/utils/”
– pattern: “**/*helper*.ts”
expectedDir: “src/utils”
reason: “Helper files should be in src/utils/”
 
Model files
– pattern: “**/*Model.ts”
expectedDir: “src/models”
reason: “Model files should be in src/models/”
– pattern: “**/*model.ts”
expectedDir: “src/models”
reason: “Model files should be in src/models/”
 
Type definition files
– pattern: “**/*Types.ts”
expectedDir: “src/types”
reason: “Type definition files should be in src/types/”
– pattern: “**/*types.ts”
expectedDir: “src/types”
reason: “Type definition files should be in src/types/”
 
Test files
– pattern: “**/*.test.ts”
expectedDir: “tests”
reason: “Test files should be in tests/”
– pattern: “**/*.spec.ts”
expectedDir: “tests”
reason: “Spec files should be in tests/”
 
Component files (React/Vue)
– pattern: “**/*Component.tsx”
expectedDir: “src/components”
reason: “Component files should be in src/components/”
 
# UC07: Flat Architecture Detection
flatArchitecture:
enabled: true
targets:
– path: “src”
maxRootFiles: 10
minSubdirs: 3
excludePatterns: [“dist/**”, “node_modules/**”, “build/**”]
– path: “.”
maxRootFiles: 15
excludePatterns: [“node_modules/**”, “.git/**”, “dist/**”, “build/**”]
 
UC08: Configuration Chaos Detection
configChaos:
enabled: true
requiredConfigs:
– “.gitignore”
– “package.json”
– “tsconfig.json”
optionalConfigs:
– “.env.example”
– “.prettierrc”
– “.eslintrc.js”
– “.eslintrc.json”
– “jest.config.js”
– “jest.config.ts”
– “Dockerfile”
– “docker-compose.yml”
 
UC06: Temporary Files Detection
tempFiles:
enabled: true
patterns:
– “**/*.tmp”
– “**/temp_*”
– “**/temp-*”
– “**/temp.*”
– “**/scratch_*”
– “**/scratch-*”
– “**/scratch.*”
– “**/scratchpad.*”
– “**/*.bak”
– “**/*_backup.*”
– “**/*-backup.*”
– “**/*_old.*”
– “**/*-old.*”
– “**/*.backup”
– “**/debug_*”
– “**/debug-*”
– “**/debug.*”
– “**/test_output.*”
– “**/test-output.*”
 
UC09: File Proliferation Detection
fileProliferation:
enabled: true
threshold: 3
 
UC11: Overcrowded Folders Detection
overcrowdedFolders:
enabled: true
targets:
– path: “src”
maxFiles: 20
– path: “src/components”
maxFiles: 25
– path: “src/utils”
maxFiles: 15
– path: “src/services”
maxFiles: 20
 
UC18: STRUCTURAL GOVERNANCE (Pro)
 
rules:
Commands must use DI pattern
– id: CMD-001
name: “Command DI Pattern”
severity: error
files: “src/commands/**/*.ts”
description: “Command files must export registerXxxCommands function”
assertions:
– type: export_exists
pattern: “register*Commands”
message: “Command file must export a registerXxxCommands function”
 
Commands must accept deps parameter
– id: CMD-002
name: “Command DI Parameter”
severity: error
files: “src/commands/**/*.ts”
description: “registerXxxCommands must accept deps parameter for DI”
assertions:
– type: function_signature
target: “register*Commands”
requiredParams: [“deps”]
message: “registerXxxCommands must accept deps parameter”
 
Services should use hexagonal architecture
– id: SVC-001
name: “Service Port Import”
severity: warning
files: “src/services/**/*.ts”
description: “Services should import from ports for testability”
assertions:
– type: import_exists
source: “../ports/*”
message: “Services should import from ports directory”
 
No focused tests
– id: TEST-001
name: “No Focused Tests”
severity: error
files: “**/*.test.ts”
description: “Prevent committing focused tests (.only)”
assertions:
– type: forbidden_pattern
pattern: “describe\\.only|it\\.only|test\\.only”
message: “Remove .only() before committing”
 
No console.log in production
– id: LOG-001
name: “No Console Logs”
severity: warning
files: “src/**/*.ts”
description: “Use Logger service instead of console.log”
assertions:
– type: forbidden_pattern
pattern: “console\\.(log|warn|error)”
message: “Use Logger service instead of console methods”
 
No debugger statements
– id: DEBUG-001
name: “No Debugger Statements”
severity: error
files: “**/*.ts”
description: “Remove debugger statements before committing”
assertions:
– type: forbidden_pattern
pattern: “\\bdebugger\\b”
message: “Remove debugger statement before committing”
 
Error handling pattern
– id: ERR-001
name: “Error Handling Pattern”
severity: info
files: “src/services/**/*.ts”
description: “Exported functions should use try-catch”
assertions:
– type: ast_skeleton
target: “exported_function”
structure:
root: “FunctionDeclaration”
children:
– position: first
type: “TryStatement”
children:
– type: “CatchClause”
message: “Exported functions should use try-catch pattern”
 
Reference Template: Python
 
WARNING: This is a REFERENCE template. You MUST customize the paths based on Step 1.
– Python projects vary widely: `src/`, `app/`, package-name directory, or flat.
– All paths should match YOUR actual project structure.
“`yaml
# Mault Configuration for Python Projects
version: 1
 
ENVIRONMENT SETTINGS
environment:
apiPort: 8000
shell: “bash”
 
UC03: NAMING CONVENTIONS (PEP 8)
conventions:
directories:
– pattern: “**/test_*.py”
location: “tests/”
– pattern: “**/*_test.py”
location: “tests/”
 
naming:
– filePattern: “*.py”
className: “PascalCase”
functionName: “snake_case”
variableName: “snake_case”
constantName: “SCREAMING_SNAKE_CASE”
 
UC02: LEGACY PATH PREVENTION
deprecatedPatterns:
Python 2/3 Migration
– id: dep-optparse
import: optparse
message: “optparse is deprecated since Python 2.7. Use ‘argparse’ instead.”
languages: [python]
 
– id: dep-urllib2
import: urllib2
message: “urllib2 is Python 2 only. Use ‘urllib.request’ instead.”
languages: [python]
 
– id: dep-httplib
import: httplib
message: “httplib is Python 2 only. Use ‘http.client’ instead.”
languages: [python]
 
– id: dep-imp
import: imp
message: “imp module is deprecated since Python 3.4. Use ‘importlib’ instead.”
languages: [python]
 
– id: dep-cgi
import: cgi
message: “cgi module is deprecated since Python 3.11. Use modern web frameworks.”
languages: [python]
 
– id: dep-crypt
import: crypt
message: “crypt module is deprecated since Python 3.11. Use ‘passlib’ instead.”
languages: [python]
 
– id: dep-pipes
import: pipes
message: “pipes module is deprecated since Python 3.11. Use ‘subprocess’ instead.”
languages: [python]
 
Deprecated Functions
– id: dep-os-popen
functionCall: os.popen
message: “os.popen is deprecated. Use ‘subprocess.run()’ instead.”
languages: [python]
 
– id: dep-os-system
functionCall: os.system
message: “os.system is deprecated. Use ‘subprocess.run()’ instead.”
languages: [python]
 
– id: dep-getopt
import: getopt
message: “getopt is legacy. Use ‘argparse’ or ‘click’ instead.”
languages: [python]
 
Security Deprecations
– id: dep-md5
functionCall: hashlib.md5
message: “MD5 is cryptographically broken. Use ‘hashlib.sha256’ for security.”
languages: [python]
 
– id: dep-sha1
functionCall: hashlib.sha1
message: “SHA1 is deprecated for security. Use ‘hashlib.sha256’ instead.”
languages: [python]
 
– id: dep-random-security
functionCall: random.random
message: “random module is not cryptographically secure. Use ‘secrets’ for security.”
languages: [python]
 
Library Deprecations
– id: dep-nose
import: nose
message: “nose is deprecated. Migrate to ‘pytest’ instead.”
languages: [python]
 
– id: dep-mock
import: mock
message: “mock library is deprecated. Use ‘unittest.mock’ instead.”
languages: [python]
 
– id: dep-distutils
import: distutils
message: “distutils is deprecated since Python 3.10. Use ‘setuptools’ instead.”
languages: [python]
 
– id: dep-pkg-resources
import: pkg_resources
message: “pkg_resources is deprecated. Use ‘importlib.metadata’ instead.”
languages: [python]
 
UC13: APPLICATION FLOW ANALYSIS
applicationFlows:
– id: authentication
name: “Authentication Flow”
description: “User login, logout, session, and token management”
 
– id: data-access
name: “Data Access Layer”
description: “Database connections, ORM, and repository operations”
 
– id: api-core
name: “API Core”
description: “Main API endpoints, routing, and request handling”
 
– id: business-logic
name: “Business Logic”
description: “Core business rules and domain services”
 
flows:
authentication:
name: “Authentication Flow”
description: “User authentication, authorization, and session management”
critical: true
files:
– “**/auth*.py”
– “**/login*.py”
– “**/session*.py”
– “**/token*.py”
– “**/middleware/auth*.py”
 
data-access:
name: “Data Access Layer”
description: “Database and ORM operations”
critical: true
files:
– “**/db*.py”
– “**/database*.py”
– “**/repository*.py”
– “**/models/**/*.py”
 
api-core:
name: “API Core”
description: “Main API routing and handlers”
critical: true
files:
– “**/api*.py”
– “**/routes*.py”
– “**/views*.py”
– “**/endpoints*.py”
 
business-logic:
name: “Business Logic”
description: “Core business rules and domain services”
critical: true
files:
– “**/services/**/*.py”
– “**/domain/**/*.py”
 
applicationFlowBlindness:
enabled: true
thresholds:
warnOnDirectDependents: 5
warnOnTransitiveDependents: 15
excludePatterns:
– “**/venv/**”
– “**/.venv/**”
– “**/env/**”
– “**/__pycache__/**”
– “**/test_*.py”
– “**/*_test.py”
– “**/tests/**”
– “**/.tox/**”
– “**/.pytest_cache/**”
 
DETECTORS CONFIGURATION
Detectors:
UC04: Environment Reinforcement
environmentReinforcement:
enabled: true
checkPaths: true
checkCommands: true
 
UC01: Directory Reinforcement
directoryReinforcement:
enabled: true
rules:
Service files (snake_case)
– pattern: “**/*_service.py”
expectedDir: “src/services”
reason: “Service files should be in src/services/”
– pattern: “**/*_service.py”
expectedDir: “app/services”
reason: “Service files should be in app/services/”
 
Repository/DAO files
– pattern: “**/*_repository.py”
expectedDir: “src/repositories”
reason: “Repository files should be in src/repositories/”
– pattern: “**/*_dao.py”
expectedDir: “src/repositories”
reason: “DAO files should be in src/repositories/”
 
Utility files
– pattern: “**/*_util*.py”
expectedDir: “src/utils”
reason: “Utility files should be in src/utils/”
– pattern: “**/*_helper*.py”
expectedDir: “src/utils”
reason: “Helper files should be in src/utils/”
– pattern: “**/utils_*.py”
expectedDir: “src/utils”
reason: “Utility files should be in src/utils/”
– pattern: “**/helpers_*.py”
expectedDir: “src/utils”
reason: “Helper files should be in src/utils/”
 
Model files
– pattern: “**/*_model.py”
expectedDir: “src/models”
reason: “Model files should be in src/models/”
 
Test files
– pattern: “**/test_*.py”
expectedDir: “tests”
reason: “Test files should be in tests/”
– pattern: “**/*_test.py”
expectedDir: “tests”
reason: “Test files should be in tests/”
 
Configuration files
– pattern: “**/config*.py”
expectedDir: “src/config”
reason: “Configuration files should be in src/config/”
– pattern: “**/settings*.py”
expectedDir: “src/config”
reason: “Settings files should be in src/config/”
 
UC07: Flat Architecture Detection
flatArchitecture:
enabled: true
targets:
– path: “.”
maxRootFiles: 15
minSubdirs: 2
excludePatterns: [“venv/**”, “.venv/**”, “__pycache__/**”, “.git/**”]
– path: “src”
maxRootFiles: 10
excludePatterns: [“__pycache__/**”]
– path: “app”
maxRootFiles: 10
excludePatterns: [“__pycache__/**”]
 
UC08: Configuration Chaos Detection
configChaos:
enabled: true
requiredConfigs:
– “.gitignore”
– “requirements.txt”
optionalConfigs:
– “pyproject.toml”
– “setup.py”
– “setup.cfg”
– “.env.example”
– “Dockerfile”
– “docker-compose.yml”
– “pytest.ini”
– “tox.ini”
– “.flake8”
– “mypy.ini”
 
UC06: Temporary Files Detection
tempFiles:
enabled: true
patterns:
– “**/*.tmp”
– “**/temp_*”
– “**/temp-*”
– “**/temp.*”
– “**/scratch_*”
– “**/scratch-*”
– “**/scratch.*”
– “**/scratchpad.*”
– “**/*.bak”
– “**/*_backup.*”
– “**/*-backup.*”
– “**/*_old.*”
– “**/*-old.*”
– “**/*.backup”
– “**/debug_*”
– “**/debug-*”
– “**/debug.*”
– “**/.ipynb_checkpoints/**”
– “**/*.pyc”
– “**/*.pyo”
 
UC09: File Proliferation Detection
fileProliferation:
enabled: true
threshold: 3
 
UC11: Overcrowded Folders Detection
overcrowdedFolders:
enabled: true
targets:
– path: “src”
maxFiles: 20
– path: “app”
maxFiles: 20
– path: “src/utils”
maxFiles: 15
– path: “src/services”
maxFiles: 20
– path: “src/models”
maxFiles: 25
 
UC18: STRUCTURAL GOVERNANCE (Pro)
rules:
Service classes must have Service suffix
– id: SVC-001
name: “Service Class Naming”
severity: error
files: “**/services/**/*.py”
description: “Service files must export a class ending with Service”
assertions:
– type: export_exists
pattern: “*Service”
message: “Service file must export a class with Service suffix”
 
Services should import from models
– id: SVC-002
name: “Service Model Import”
severity: warning
files: “**/services/**/*.py”
description: “Services should import from models for data types”
assertions:
– type: import_exists
source: “.models”
message: “Services should import from models package”
 
No print() in production code
– id: LOG-001
name: “No Print Statements”
severity: warning
files: “src/**/*.py”
description: “Use logging module instead of print()”
assertions:
– type: forbidden_pattern
pattern: “print\\s*\\(“
message: “Use logging module instead of print()”
 
No print() in app directory too
– id: LOG-002
name: “No Print Statements (App)”
severity: warning
files: “app/**/*.py”
description: “Use logging module instead of print()”
assertions:
– type: forbidden_pattern
pattern: “print\\s*\\(“
message: “Use logging module instead of print()”
 
No debug breakpoints
– id: DEBUG-001
name: “No Breakpoints”
severity: error
files: “**/*.py”
description: “Remove breakpoint() and pdb before committing”
assertions:
– type: forbidden_pattern
pattern: “breakpoint\\s*\\(|import\\s+pdb|pdb\\.set_trace”
message: “Remove debug breakpoints before committing”
 
No focused tests
– id: TEST-001
name: “No Focused Tests”
severity: error
files: “tests/**/*.py”
description: “Prevent committing focused tests”
assertions:
– type: forbidden_pattern
pattern: “@pytest\\.mark\\.only|@only|@pytest\\.mark\\.skip\\(reason=.TODO”
message: “Remove focused test markers before committing”
 
No TODO/FIXME in production (info level)
– id: TODO-001
name: “No TODO in Production”
severity: info
files: “src/**/*.py”
description: “Address TODO comments before production”
assertions:
– type: forbidden_pattern
pattern: “#\\s*TODO:|#\\s*FIXME:|#\\s*HACK:”
message: “Address TODO/FIXME/HACK comments”
 
No bare except
– id: ERR-001
name: “No Bare Except”
severity: warning
files: “**/*.py”
description: “Avoid bare except clauses”
assertions:
– type: forbidden_pattern
pattern: “except\\s*:”
message: “Use specific exception types instead of bare except”
 
No wildcard imports
– id: IMPORT-001
name: “No Wildcard Imports”
severity: warning
files: “**/*.py”
description: “Avoid wildcard imports”
assertions:
– type: forbidden_pattern
pattern: “from\\s+\\w+\\s+import\\s+\\*”
message: “Use explicit imports instead of wildcard imports”
Use Case Reference
 
| UC | Name | Config Section | Required? |
|—-|——|—————-|———–|
| UC01 | Directory Reinforcement | `Detectors.directoryReinforcement` | Yes |
| UC02 | Legacy Path Prevention | `deprecatedPatterns` | Yes |
| UC03 | Convention Reinforcement | `conventions.naming` | Optional |
| UC04 | Environment Reinforcement | `Detectors.environmentReinforcement` | Optional |
| UC06 | Temporary Files | `Detectors.tempFiles` | Optional |
| UC07 | Flat Architecture | `Detectors.flatArchitecture` | Yes |
| UC08 | Configuration Chaos | `Detectors.configChaos` | Optional |
| UC09 | File Proliferation | `Detectors.fileProliferation` | Optional |
| UC10 | Naming Chaos | Built-in | No config |
| UC11 | Overcrowded Folders | `Detectors.overcrowdedFolders` | Optional |
| UC12 | Scattered Utils | Built-in | No config |
| UC13 | Application Flow | `applicationFlows`, `flows` | Yes |
| UC16 | Dependency Health (Pro) | Built-in | No config |
| UC17 | Architecture Diagrams (Pro) | Built-in | No config |
| UC18 | Structural Governance (Pro) | `rules` | Yes (Pro) |
 
Customization Guide
 
Adding Project-Specific Deprecated Patterns
Add patterns specific to your codebase:
 
“`yaml
deprecatedPatterns:
Your internal legacy code
– id: dep-old-auth
import: “./legacy/auth”
message: “Legacy auth module deprecated. Use ‘./auth/v2’ instead.”
languages: [typescript]
 
Internal API versions
– id: dep-internal-api-v1
import: “@company/api-v1”
message: “API v1 deprecated. Migrate to @company/api-v2.”
 
Adding Directory Rules
Add rules for your specific architecture:
 
“`yaml
Detectors:
directoryReinforcement:
rules:
Your custom patterns
– pattern: “**/*Repository.ts”
expectedDir: “src/repositories”
reason: “Repository files should be in src/repositories/”
– pattern: “**/*Adapter.ts”
expectedDir: “src/adapters”
reason: “Adapter files should be in src/adapters/”
 
Adding Application Flows
Map your business domains:  
“`yaml
flows:
checkout:
name: “Checkout Flow”
description: “Shopping cart, payment, order creation”
critical: true
files:
– “src/**/cart*.ts”
– “src/**/payment*.ts”
– “src/**/order*.ts”
– “src/**/checkout*.ts”
 
Adding Governance Rules (Pro)
Enforce your architectural patterns:
 
“`yaml
rules:
– id: CUSTOM-001
name: “Custom Pattern”
severity: error
files: “src/your-path/**/*.ts”
assertions:
– type: forbidden_pattern
pattern: “your-regex-here”
message: “Your guidance message”

Away from your desk?

Send a link to install later.

Finish setup on desktop

Mault runs in VS Code and can’t be installed on mobile. We’ll email you the install link.