mirror of
https://github.com/samiyev/puaros.git
synced 2025-12-27 23:06:54 +05:00
1176 lines
25 KiB
Markdown
1176 lines
25 KiB
Markdown
# Guardian v0.6.0 - Configuration & Presets Specification
|
||
|
||
**Version:** 0.6.0
|
||
**Target Release:** Q1 2026 (January-February)
|
||
**Status:** 📋 Specification
|
||
**Priority:** 🔥 CRITICAL
|
||
|
||
---
|
||
|
||
## 📋 Table of Contents
|
||
|
||
1. [Overview](#overview)
|
||
2. [Goals & Non-Goals](#goals--non-goals)
|
||
3. [Configuration File Format](#configuration-file-format)
|
||
4. [Preset System](#preset-system)
|
||
5. [Rule Configuration](#rule-configuration)
|
||
6. [Layer Customization](#layer-customization)
|
||
7. [Ignore & Exclude Patterns](#ignore--exclude-patterns)
|
||
8. [CLI Integration](#cli-integration)
|
||
9. [Migration Guide](#migration-guide)
|
||
10. [Implementation Plan](#implementation-plan)
|
||
11. [Testing Strategy](#testing-strategy)
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
### Problem Statement
|
||
|
||
Currently, Guardian uses hardcoded rules and layer paths. This prevents:
|
||
- ❌ Customization for different project structures
|
||
- ❌ Disabling specific rules
|
||
- ❌ Per-file or per-directory overrides
|
||
- ❌ Team-specific configurations
|
||
- ❌ Framework-specific presets (NestJS, Express, etc.)
|
||
|
||
**Without configuration support, Guardian cannot scale to enterprise adoption.**
|
||
|
||
### Solution
|
||
|
||
Add comprehensive configuration system with:
|
||
- ✅ Multiple file format support
|
||
- ✅ Zero-config presets
|
||
- ✅ Rule-level customization
|
||
- ✅ Custom layer paths
|
||
- ✅ Ignore patterns
|
||
- ✅ CLI overrides
|
||
|
||
### Success Criteria
|
||
|
||
- [ ] Support 5+ configuration file formats
|
||
- [ ] Provide 4+ built-in presets
|
||
- [ ] Enable/disable any rule via config
|
||
- [ ] Custom layer path mapping
|
||
- [ ] Per-file/directory ignore patterns
|
||
- [ ] CLI can override any config option
|
||
- [ ] 100% backward compatible (default config)
|
||
- [ ] Complete documentation with examples
|
||
- [ ] 95%+ test coverage
|
||
|
||
---
|
||
|
||
## Goals & Non-Goals
|
||
|
||
### Goals
|
||
|
||
✅ **Configuration Discovery**
|
||
- Support multiple file formats
|
||
- Auto-discover config in project root
|
||
- Clear precedence order
|
||
|
||
✅ **Zero-Config Experience**
|
||
- Works without config (sensible defaults)
|
||
- Presets for common architectures
|
||
|
||
✅ **Flexibility**
|
||
- Enable/disable any rule
|
||
- Custom severity levels
|
||
- Per-file ignores
|
||
|
||
✅ **Developer Experience**
|
||
- `guardian init` command
|
||
- Config validation
|
||
- Helpful error messages
|
||
|
||
### Non-Goals
|
||
|
||
❌ **Remote Configuration**
|
||
- No fetching config from URLs (v1.0+ maybe)
|
||
|
||
❌ **Shareable Config Packages**
|
||
- No `@company/guardian-config` packages (v0.7+ maybe)
|
||
|
||
❌ **GUI Config Editor**
|
||
- CLI/text-based only (v1.0+ maybe)
|
||
|
||
---
|
||
|
||
## Configuration File Format
|
||
|
||
### Supported File Formats
|
||
|
||
Guardian will discover configuration in this order:
|
||
|
||
1. `guardian.config.js` (ES modules) - **Recommended**
|
||
2. `guardian.config.cjs` (CommonJS)
|
||
3. `guardian.config.mjs` (ES modules, explicit)
|
||
4. `.guardianrc` (JSON)
|
||
5. `.guardianrc.json` (JSON, explicit)
|
||
6. `.guardianrc.js` (JS)
|
||
7. `package.json` (in `guardian` field)
|
||
|
||
**Precedence:** First found wins.
|
||
|
||
### Configuration Schema
|
||
|
||
```typescript
|
||
interface GuardianConfig {
|
||
// Preset (optional, zero-config)
|
||
preset?: 'clean-architecture' | 'ddd' | 'hexagonal' | 'onion' | 'minimal' | string
|
||
|
||
// Extends another config (optional)
|
||
extends?: string | string[]
|
||
|
||
// Root directory (optional, default: process.cwd())
|
||
root?: string
|
||
|
||
// File includes (optional, default: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'])
|
||
include?: string[]
|
||
|
||
// File excludes (optional)
|
||
exclude?: string[]
|
||
|
||
// Rule configuration
|
||
rules?: {
|
||
[ruleName: string]: RuleConfig
|
||
}
|
||
|
||
// Layer path mapping
|
||
layers?: {
|
||
domain?: string | string[]
|
||
application?: string | string[]
|
||
infrastructure?: string | string[]
|
||
shared?: string | string[]
|
||
}
|
||
|
||
// Per-rule ignore patterns
|
||
ignore?: {
|
||
[ruleName: string]: IgnorePattern
|
||
}
|
||
|
||
// Output format (optional, default: 'text')
|
||
format?: 'text' | 'json' | 'markdown' | 'ai-prompt'
|
||
|
||
// Fail on severity (optional, default: 'error')
|
||
failOn?: 'error' | 'warning' | 'off'
|
||
}
|
||
|
||
type RuleConfig = 'error' | 'warn' | 'off' | [RuleSeverity, RuleOptions]
|
||
type RuleSeverity = 'error' | 'warn' | 'off'
|
||
type RuleOptions = Record<string, unknown>
|
||
|
||
interface IgnorePattern {
|
||
[filePattern: string]: unknown[] // Specific values to ignore
|
||
}
|
||
```
|
||
|
||
### Example: guardian.config.js (Recommended)
|
||
|
||
```javascript
|
||
// guardian.config.js
|
||
export default {
|
||
// Use built-in preset
|
||
preset: 'clean-architecture',
|
||
|
||
// Custom layer paths
|
||
layers: {
|
||
domain: 'src/core/domain',
|
||
application: 'src/core/application',
|
||
infrastructure: 'src/adapters',
|
||
shared: 'src/shared',
|
||
},
|
||
|
||
// Rule customization
|
||
rules: {
|
||
'hardcode/magic-numbers': 'error',
|
||
'hardcode/magic-strings': 'warn',
|
||
'architecture/layer-violation': 'error',
|
||
'architecture/framework-leak': 'error',
|
||
'architecture/entity-exposure': 'error',
|
||
'circular-dependency': 'error',
|
||
'naming-convention': 'warn',
|
||
'dependency-direction': 'error',
|
||
'repository-pattern': 'error',
|
||
},
|
||
|
||
// Exclusions
|
||
exclude: [
|
||
'**/*.test.ts',
|
||
'**/*.spec.ts',
|
||
'scripts/**',
|
||
'migrations/**',
|
||
'node_modules/**',
|
||
'dist/**',
|
||
],
|
||
|
||
// Per-rule ignores
|
||
ignore: {
|
||
'hardcode/magic-numbers': {
|
||
'src/config/constants.ts': [3000, 8080, 5000], // Allow these specific values
|
||
'src/database/migrations/**': '*', // Ignore all in migrations
|
||
},
|
||
'naming-convention': {
|
||
'src/legacy/**': '*', // Ignore all legacy code
|
||
},
|
||
},
|
||
|
||
// Output format
|
||
format: 'text',
|
||
|
||
// Fail on errors only (warnings don't fail CI)
|
||
failOn: 'error',
|
||
}
|
||
```
|
||
|
||
### Example: .guardianrc (JSON)
|
||
|
||
```json
|
||
{
|
||
"preset": "clean-architecture",
|
||
"rules": {
|
||
"hardcode/magic-numbers": "error",
|
||
"hardcode/magic-strings": "warn"
|
||
},
|
||
"exclude": ["**/*.test.ts", "**/*.spec.ts"]
|
||
}
|
||
```
|
||
|
||
### Example: package.json
|
||
|
||
```json
|
||
{
|
||
"name": "my-app",
|
||
"version": "1.0.0",
|
||
"guardian": {
|
||
"preset": "clean-architecture",
|
||
"rules": {
|
||
"hardcode/magic-numbers": "error"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Preset System
|
||
|
||
### Built-in Presets
|
||
|
||
#### 1. `clean-architecture` (Default)
|
||
|
||
Enforces Clean Architecture principles:
|
||
|
||
```javascript
|
||
// Equivalent to:
|
||
{
|
||
rules: {
|
||
'architecture/layer-violation': 'error',
|
||
'architecture/framework-leak': 'error',
|
||
'architecture/entity-exposure': 'error',
|
||
'dependency-direction': 'error',
|
||
'circular-dependency': 'error',
|
||
'hardcode/magic-numbers': 'error',
|
||
'hardcode/magic-strings': 'error',
|
||
'naming-convention': 'warn',
|
||
'repository-pattern': 'error',
|
||
},
|
||
layers: {
|
||
domain: 'src/domain',
|
||
application: 'src/application',
|
||
infrastructure: 'src/infrastructure',
|
||
shared: 'src/shared',
|
||
}
|
||
}
|
||
```
|
||
|
||
**When to use:** Most TypeScript projects following Clean Architecture
|
||
|
||
#### 2. `ddd` (Domain-Driven Design)
|
||
|
||
All DDD pattern detectors enabled:
|
||
|
||
```javascript
|
||
// Equivalent to:
|
||
{
|
||
extends: 'clean-architecture',
|
||
rules: {
|
||
// All v0.11-v0.32 DDD features enabled
|
||
'aggregate-boundaries': 'error',
|
||
'anemic-domain-model': 'warn',
|
||
'domain-events': 'error',
|
||
'value-object-immutability': 'error',
|
||
// ... all 30+ DDD rules
|
||
}
|
||
}
|
||
```
|
||
|
||
**When to use:** Projects strictly following DDD
|
||
|
||
#### 3. `hexagonal` (Ports & Adapters)
|
||
|
||
Validates hexagonal architecture:
|
||
|
||
```javascript
|
||
// Equivalent to:
|
||
{
|
||
rules: {
|
||
'architecture/layer-violation': 'error',
|
||
'port-adapter-pattern': 'error', // v0.17.0
|
||
'dependency-direction': 'error',
|
||
},
|
||
layers: {
|
||
domain: 'src/domain',
|
||
application: 'src/application', // Ports here
|
||
infrastructure: 'src/adapters', // Adapters here
|
||
}
|
||
}
|
||
```
|
||
|
||
**When to use:** Projects using Ports & Adapters pattern
|
||
|
||
#### 4. `minimal` (Prototyping)
|
||
|
||
Only critical rules for fast iteration:
|
||
|
||
```javascript
|
||
// Equivalent to:
|
||
{
|
||
rules: {
|
||
'hardcode/magic-numbers': 'warn',
|
||
'circular-dependency': 'error',
|
||
'architecture/framework-leak': 'warn',
|
||
}
|
||
}
|
||
```
|
||
|
||
**When to use:** Prototypes, MVPs, learning projects
|
||
|
||
#### 5. `nestjs-clean-architecture`
|
||
|
||
NestJS-specific preset:
|
||
|
||
```javascript
|
||
// Equivalent to:
|
||
{
|
||
extends: 'clean-architecture',
|
||
layers: {
|
||
domain: 'src/domain',
|
||
application: 'src/application',
|
||
infrastructure: 'src/infrastructure',
|
||
},
|
||
ignore: {
|
||
'naming-convention': {
|
||
'**/*.module.ts': '*', // NestJS modules
|
||
'**/*.controller.ts': '*', // Already has suffix
|
||
},
|
||
'architecture/framework-leak': {
|
||
'src/infrastructure/**': ['@nestjs/*'], // Allow NestJS in infra
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**When to use:** NestJS projects
|
||
|
||
#### 6. `express-clean-architecture`
|
||
|
||
Express-specific preset:
|
||
|
||
```javascript
|
||
// Equivalent to:
|
||
{
|
||
extends: 'clean-architecture',
|
||
ignore: {
|
||
'architecture/framework-leak': {
|
||
'src/infrastructure/http/**': ['express'],
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**When to use:** Express projects
|
||
|
||
### Custom Presets
|
||
|
||
Users can create custom presets:
|
||
|
||
```javascript
|
||
// guardian.config.js
|
||
export default {
|
||
preset: './presets/my-company-preset.js'
|
||
}
|
||
|
||
// presets/my-company-preset.js
|
||
export default {
|
||
extends: 'clean-architecture',
|
||
rules: {
|
||
// Company-specific rules
|
||
}
|
||
}
|
||
```
|
||
|
||
**Future (v0.7+):** Shareable preset packages
|
||
```bash
|
||
npm install @mycompany/guardian-preset
|
||
```
|
||
|
||
```javascript
|
||
export default {
|
||
preset: '@mycompany/guardian-preset'
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Rule Configuration
|
||
|
||
### Available Rules
|
||
|
||
| Rule ID | Default | Description |
|
||
|---------|---------|-------------|
|
||
| `hardcode/magic-numbers` | `error` | Detect magic numbers |
|
||
| `hardcode/magic-strings` | `error` | Detect magic strings |
|
||
| `architecture/layer-violation` | `error` | Layer dependency violations |
|
||
| `architecture/framework-leak` | `error` | Framework imports in domain |
|
||
| `architecture/entity-exposure` | `error` | Domain entities in API |
|
||
| `circular-dependency` | `error` | Circular imports |
|
||
| `naming-convention` | `warn` | File naming conventions |
|
||
| `dependency-direction` | `error` | Wrong dependency direction |
|
||
| `repository-pattern` | `error` | Repository pattern violations |
|
||
|
||
**Future rules (v0.11+):**
|
||
- `aggregate-boundaries` (v0.11)
|
||
- `anemic-domain-model` (v0.12)
|
||
- `domain-events` (v0.13)
|
||
- `value-object-immutability` (v0.14)
|
||
- ... (25+ more)
|
||
|
||
### Rule Severity Levels
|
||
|
||
```javascript
|
||
rules: {
|
||
'hardcode/magic-numbers': 'error', // Fail CI, block PR
|
||
'naming-convention': 'warn', // Show warning, don't fail
|
||
'some-future-rule': 'off', // Completely disabled
|
||
}
|
||
```
|
||
|
||
### Rule Options (Advanced)
|
||
|
||
Some rules accept options:
|
||
|
||
```javascript
|
||
rules: {
|
||
'hardcode/magic-numbers': ['error', {
|
||
allowedNumbers: [-1, 0, 1, 2, 10, 100, 1000],
|
||
ignoreEnums: true,
|
||
ignoreReadonly: true,
|
||
}],
|
||
|
||
'naming-convention': ['warn', {
|
||
useCaseVerbs: ['Create', 'Update', 'Delete', 'Get', 'List'],
|
||
entityPattern: /^[A-Z][a-zA-Z]+$/,
|
||
}],
|
||
|
||
'circular-dependency': ['error', {
|
||
maxDepth: 5, // Only report cycles up to depth 5
|
||
}],
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Layer Customization
|
||
|
||
### Default Layer Paths
|
||
|
||
```javascript
|
||
layers: {
|
||
domain: 'src/domain',
|
||
application: 'src/application',
|
||
infrastructure: 'src/infrastructure',
|
||
shared: 'src/shared',
|
||
}
|
||
```
|
||
|
||
### Custom Paths (Single)
|
||
|
||
```javascript
|
||
layers: {
|
||
domain: 'src/core/domain',
|
||
application: 'src/core/application',
|
||
infrastructure: 'src/adapters',
|
||
shared: 'src/common',
|
||
}
|
||
```
|
||
|
||
### Multiple Paths per Layer
|
||
|
||
```javascript
|
||
layers: {
|
||
domain: ['src/core/domain', 'src/modules/*/domain'],
|
||
application: ['src/core/application', 'src/modules/*/application'],
|
||
infrastructure: ['src/adapters', 'src/modules/*/adapters'],
|
||
}
|
||
```
|
||
|
||
### Monorepo Support
|
||
|
||
```javascript
|
||
// Root guardian.config.js
|
||
layers: {
|
||
domain: 'packages/*/src/domain',
|
||
application: 'packages/*/src/application',
|
||
infrastructure: 'packages/*/src/infrastructure',
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Ignore & Exclude Patterns
|
||
|
||
### Global Excludes
|
||
|
||
```javascript
|
||
exclude: [
|
||
'**/*.test.ts',
|
||
'**/*.spec.ts',
|
||
'**/__tests__/**',
|
||
'scripts/**',
|
||
'migrations/**',
|
||
'node_modules/**',
|
||
'dist/**',
|
||
'build/**',
|
||
]
|
||
```
|
||
|
||
### Per-Rule Ignores
|
||
|
||
#### Ignore Specific Values
|
||
|
||
```javascript
|
||
ignore: {
|
||
'hardcode/magic-numbers': {
|
||
'src/config/constants.ts': [3000, 8080, 5000],
|
||
'src/config/defaults.ts': [10, 20, 30],
|
||
}
|
||
}
|
||
```
|
||
|
||
#### Ignore All Violations
|
||
|
||
```javascript
|
||
ignore: {
|
||
'naming-convention': {
|
||
'src/legacy/**': '*', // Ignore all naming in legacy
|
||
}
|
||
}
|
||
```
|
||
|
||
#### Ignore Entire Directories
|
||
|
||
```javascript
|
||
ignore: {
|
||
'hardcode/magic-numbers': {
|
||
'migrations/**': '*',
|
||
'scripts/**': '*',
|
||
}
|
||
}
|
||
```
|
||
|
||
### Pattern Syntax
|
||
|
||
Supports glob patterns:
|
||
- `*` - matches any characters except `/`
|
||
- `**` - matches any characters including `/`
|
||
- `?` - matches single character
|
||
- `[abc]` - matches `a`, `b`, or `c`
|
||
- `{a,b}` - matches `a` or `b`
|
||
|
||
---
|
||
|
||
## CLI Integration
|
||
|
||
### Commands
|
||
|
||
#### `guardian init`
|
||
|
||
Generate configuration file:
|
||
|
||
```bash
|
||
# Interactive mode
|
||
guardian init
|
||
|
||
# With preset
|
||
guardian init --preset clean-architecture
|
||
|
||
# Specific format
|
||
guardian init --format js
|
||
guardian init --format json
|
||
|
||
# Output to custom location
|
||
guardian init --output custom-config.js
|
||
```
|
||
|
||
**Interactive prompts:**
|
||
```
|
||
? Which preset would you like to use? (Use arrow keys)
|
||
❯ clean-architecture (Recommended)
|
||
ddd (Domain-Driven Design)
|
||
hexagonal (Ports & Adapters)
|
||
minimal (Prototyping)
|
||
nestjs-clean-architecture
|
||
express-clean-architecture
|
||
custom (Configure manually)
|
||
|
||
? Where are your domain files? (src/domain)
|
||
? Where are your application files? (src/application)
|
||
? Where are your infrastructure files? (src/infrastructure)
|
||
|
||
? Configuration file format? (Use arrow keys)
|
||
❯ JavaScript (guardian.config.js) - Recommended
|
||
JSON (.guardianrc)
|
||
package.json
|
||
|
||
✅ Created guardian.config.js
|
||
```
|
||
|
||
#### `guardian check` (with config)
|
||
|
||
```bash
|
||
# Use config from default locations
|
||
guardian check ./src
|
||
|
||
# Specify config file
|
||
guardian check ./src --config custom-config.js
|
||
|
||
# Override rules via CLI
|
||
guardian check ./src --rule hardcode/magic-numbers=off
|
||
guardian check ./src --rule naming-convention=error
|
||
|
||
# Override preset
|
||
guardian check ./src --preset minimal
|
||
|
||
# Override fail-on
|
||
guardian check ./src --fail-on warning
|
||
```
|
||
|
||
#### `guardian validate-config`
|
||
|
||
Validate configuration file:
|
||
|
||
```bash
|
||
guardian validate-config
|
||
guardian validate-config --config custom-config.js
|
||
|
||
# Output:
|
||
# ✅ Configuration is valid
|
||
# or
|
||
# ❌ Configuration errors:
|
||
# - Unknown rule: 'invalid-rule'
|
||
# - Invalid severity: 'critical' (must be error/warn/off)
|
||
```
|
||
|
||
### CLI Overrides
|
||
|
||
CLI options take precedence over config file:
|
||
|
||
```javascript
|
||
// guardian.config.js
|
||
{
|
||
rules: {
|
||
'hardcode/magic-numbers': 'error'
|
||
}
|
||
}
|
||
```
|
||
|
||
```bash
|
||
# Override to 'off' for this run
|
||
guardian check ./src --rule hardcode/magic-numbers=off
|
||
```
|
||
|
||
**Precedence order:**
|
||
1. CLI flags (highest)
|
||
2. Config file
|
||
3. Preset
|
||
4. Default config (lowest)
|
||
|
||
---
|
||
|
||
## Migration Guide
|
||
|
||
### From No Config → With Config
|
||
|
||
**Before (v0.5.1):**
|
||
```bash
|
||
# All rules enabled, hardcoded paths
|
||
guardian check ./src
|
||
```
|
||
|
||
**After (v0.6.0):**
|
||
```bash
|
||
# Generate config
|
||
guardian init --preset clean-architecture
|
||
|
||
# Customize guardian.config.js
|
||
# Run with config
|
||
guardian check ./src
|
||
```
|
||
|
||
### Backward Compatibility
|
||
|
||
**v0.6.0 is 100% backward compatible:**
|
||
|
||
```bash
|
||
# This still works exactly the same
|
||
guardian check ./src
|
||
|
||
# Default config is applied automatically
|
||
```
|
||
|
||
**Default config (when no config file found):**
|
||
```javascript
|
||
{
|
||
preset: 'clean-architecture',
|
||
layers: {
|
||
domain: 'src/domain',
|
||
application: 'src/application',
|
||
infrastructure: 'src/infrastructure',
|
||
shared: 'src/shared',
|
||
},
|
||
rules: {
|
||
'hardcode/magic-numbers': 'error',
|
||
'hardcode/magic-strings': 'error',
|
||
'architecture/layer-violation': 'error',
|
||
'architecture/framework-leak': 'error',
|
||
'architecture/entity-exposure': 'error',
|
||
'circular-dependency': 'error',
|
||
'naming-convention': 'warn',
|
||
'dependency-direction': 'error',
|
||
'repository-pattern': 'error',
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Implementation Plan
|
||
|
||
### Phase 1: Core Configuration (Week 1-2)
|
||
|
||
**Tasks:**
|
||
- [ ] Create `GuardianConfig` TypeScript interface
|
||
- [ ] Implement config file discovery
|
||
- [ ] Implement config parser (JS, JSON)
|
||
- [ ] Implement config validator
|
||
- [ ] Add config merging (extends, overrides)
|
||
- [ ] Update `AnalyzeProject` to accept config
|
||
- [ ] Tests for config loading
|
||
|
||
**Deliverable:** Config files are discovered and parsed
|
||
|
||
### Phase 2: Rule Configuration (Week 2-3)
|
||
|
||
**Tasks:**
|
||
- [ ] Implement rule severity system (error/warn/off)
|
||
- [ ] Update each detector to check rule config
|
||
- [ ] Implement per-rule options
|
||
- [ ] Tests for rule configuration
|
||
|
||
**Deliverable:** Rules can be enabled/disabled/configured
|
||
|
||
### Phase 3: Preset System (Week 3-4)
|
||
|
||
**Tasks:**
|
||
- [ ] Implement preset loader
|
||
- [ ] Create built-in presets (clean-architecture, ddd, etc.)
|
||
- [ ] Implement preset extends
|
||
- [ ] Implement custom preset loading
|
||
- [ ] Tests for preset system
|
||
|
||
**Deliverable:** Presets work and can be extended
|
||
|
||
### Phase 4: Ignore Patterns (Week 4-5)
|
||
|
||
**Tasks:**
|
||
- [ ] Implement ignore pattern matching
|
||
- [ ] Update detectors to check ignore patterns
|
||
- [ ] Add global exclude support
|
||
- [ ] Tests for ignore patterns
|
||
|
||
**Deliverable:** Files and values can be ignored
|
||
|
||
### Phase 5: CLI Integration (Week 5-6)
|
||
|
||
**Tasks:**
|
||
- [ ] Implement `guardian init` command
|
||
- [ ] Add `--config` flag
|
||
- [ ] Add `--rule` override flag
|
||
- [ ] Add `--preset` override flag
|
||
- [ ] Implement `guardian validate-config`
|
||
- [ ] Tests for CLI integration
|
||
|
||
**Deliverable:** CLI fully supports configuration
|
||
|
||
### Phase 6: Documentation & Testing (Week 6-7)
|
||
|
||
**Tasks:**
|
||
- [ ] Write configuration documentation
|
||
- [ ] Create example configs for each preset
|
||
- [ ] Add migration guide
|
||
- [ ] Comprehensive integration tests
|
||
- [ ] Update README
|
||
|
||
**Deliverable:** Complete docs and 95%+ coverage
|
||
|
||
### Phase 7: Beta Testing & Release (Week 7-8)
|
||
|
||
**Tasks:**
|
||
- [ ] Beta release (v0.6.0-beta.1)
|
||
- [ ] Community testing
|
||
- [ ] Bug fixes
|
||
- [ ] Final release (v0.6.0)
|
||
|
||
**Deliverable:** Stable v0.6.0 release
|
||
|
||
---
|
||
|
||
## Testing Strategy
|
||
|
||
### Unit Tests
|
||
|
||
```typescript
|
||
describe('ConfigLoader', () => {
|
||
it('should discover guardian.config.js', async () => {
|
||
// Test config file discovery
|
||
})
|
||
|
||
it('should parse JavaScript config', async () => {
|
||
// Test JS config parsing
|
||
})
|
||
|
||
it('should parse JSON config', async () => {
|
||
// Test JSON config parsing
|
||
})
|
||
|
||
it('should merge configs with extends', async () => {
|
||
// Test config merging
|
||
})
|
||
|
||
it('should validate config schema', async () => {
|
||
// Test validation
|
||
})
|
||
})
|
||
|
||
describe('PresetLoader', () => {
|
||
it('should load built-in preset', async () => {
|
||
// Test preset loading
|
||
})
|
||
|
||
it('should extend preset', async () => {
|
||
// Test preset extending
|
||
})
|
||
})
|
||
|
||
describe('RuleConfiguration', () => {
|
||
it('should disable rule when set to off', async () => {
|
||
// Test rule disabling
|
||
})
|
||
|
||
it('should apply rule options', async () => {
|
||
// Test rule options
|
||
})
|
||
})
|
||
```
|
||
|
||
### Integration Tests
|
||
|
||
```typescript
|
||
describe('Configuration Integration', () => {
|
||
it('should run with custom config', async () => {
|
||
// Create temp config file
|
||
// Run guardian check
|
||
// Verify rules are applied
|
||
})
|
||
|
||
it('should apply preset correctly', async () => {
|
||
// Test preset application
|
||
})
|
||
|
||
it('should ignore files matching pattern', async () => {
|
||
// Test ignore patterns
|
||
})
|
||
|
||
it('should override config from CLI', async () => {
|
||
// Test CLI overrides
|
||
})
|
||
})
|
||
```
|
||
|
||
### Test Coverage Goals
|
||
|
||
- Configuration loading: 100%
|
||
- Preset system: 100%
|
||
- Rule configuration: 100%
|
||
- Ignore patterns: 95%+
|
||
- CLI integration: 95%+
|
||
- Overall: 95%+
|
||
|
||
---
|
||
|
||
## Examples
|
||
|
||
### Example 1: Minimal Config
|
||
|
||
```javascript
|
||
// guardian.config.js
|
||
export default {
|
||
preset: 'clean-architecture',
|
||
}
|
||
```
|
||
|
||
### Example 2: Custom Paths
|
||
|
||
```javascript
|
||
// guardian.config.js
|
||
export default {
|
||
preset: 'clean-architecture',
|
||
layers: {
|
||
domain: 'src/core/domain',
|
||
application: 'src/core/application',
|
||
infrastructure: 'src/adapters',
|
||
},
|
||
}
|
||
```
|
||
|
||
### Example 3: Rule Customization
|
||
|
||
```javascript
|
||
// guardian.config.js
|
||
export default {
|
||
preset: 'clean-architecture',
|
||
rules: {
|
||
'hardcode/magic-numbers': 'warn', // Downgrade to warning
|
||
'naming-convention': 'off', // Disable completely
|
||
},
|
||
}
|
||
```
|
||
|
||
### Example 4: Ignore Patterns
|
||
|
||
```javascript
|
||
// guardian.config.js
|
||
export default {
|
||
preset: 'clean-architecture',
|
||
ignore: {
|
||
'hardcode/magic-numbers': {
|
||
'src/config/**': '*', // Ignore all hardcode in config
|
||
'src/constants.ts': [3000, 8080], // Allow specific values
|
||
},
|
||
'naming-convention': {
|
||
'src/legacy/**': '*', // Ignore legacy code
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
### Example 5: NestJS Project
|
||
|
||
```javascript
|
||
// guardian.config.js
|
||
export default {
|
||
preset: 'nestjs-clean-architecture',
|
||
exclude: [
|
||
'**/*.spec.ts',
|
||
'test/**',
|
||
],
|
||
}
|
||
```
|
||
|
||
### Example 6: Monorepo
|
||
|
||
```javascript
|
||
// guardian.config.js (root)
|
||
export default {
|
||
preset: 'clean-architecture',
|
||
layers: {
|
||
domain: 'packages/*/src/domain',
|
||
application: 'packages/*/src/application',
|
||
infrastructure: 'packages/*/src/infrastructure',
|
||
},
|
||
exclude: [
|
||
'packages/legacy/**',
|
||
],
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## API Changes
|
||
|
||
### Before (v0.5.1)
|
||
|
||
```typescript
|
||
// No configuration support
|
||
const result = await analyzeProject({
|
||
rootDir: './src',
|
||
exclude: ['node_modules'],
|
||
})
|
||
```
|
||
|
||
### After (v0.6.0)
|
||
|
||
```typescript
|
||
import { loadConfig } from '@samiyev/guardian'
|
||
|
||
// Load config
|
||
const config = await loadConfig('./guardian.config.js')
|
||
|
||
// Use config
|
||
const result = await analyzeProject({
|
||
rootDir: './src',
|
||
config, // New: Pass config
|
||
})
|
||
|
||
// Or auto-discover:
|
||
const result = await analyzeProject({
|
||
rootDir: './src',
|
||
// Config auto-discovered if not provided
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## Documentation Updates
|
||
|
||
### New Documentation Pages
|
||
|
||
1. **Configuration Guide**
|
||
- How to create config
|
||
- All options explained
|
||
- Examples for each preset
|
||
|
||
2. **Preset Reference**
|
||
- Description of each preset
|
||
- When to use which preset
|
||
- How to customize presets
|
||
|
||
3. **Rule Reference**
|
||
- Complete list of rules
|
||
- Rule options
|
||
- Examples for each rule
|
||
|
||
4. **Migration Guide**
|
||
- From v0.5.x to v0.6.0
|
||
- Adding config to existing projects
|
||
|
||
### Updated Pages
|
||
|
||
- **README.md** - Add configuration section
|
||
- **Quick Start** - Show `guardian init`
|
||
- **CLI Reference** - New commands and flags
|
||
|
||
---
|
||
|
||
## Success Metrics
|
||
|
||
### Release Criteria
|
||
|
||
- [ ] All tests passing (95%+ coverage)
|
||
- [ ] Documentation complete
|
||
- [ ] 5+ example configs
|
||
- [ ] Beta tested by 10+ users
|
||
- [ ] Zero critical bugs
|
||
- [ ] Backward compatible
|
||
|
||
### Adoption Metrics (3 months post-release)
|
||
|
||
- Target: 50%+ of users create config files
|
||
- Target: 100+ GitHub repos with guardian.config.js
|
||
- Target: <5 config-related issues on GitHub
|
||
|
||
---
|
||
|
||
## Future Enhancements (Post-v0.6.0)
|
||
|
||
### v0.7.0 - Shareable Configs
|
||
|
||
```bash
|
||
npm install @mycompany/guardian-config
|
||
```
|
||
|
||
```javascript
|
||
export default {
|
||
extends: '@mycompany/guardian-config'
|
||
}
|
||
```
|
||
|
||
### v0.8.0 - Remote Configs
|
||
|
||
```javascript
|
||
export default {
|
||
extends: 'https://example.com/guardian-config.js'
|
||
}
|
||
```
|
||
|
||
### v1.0.0 - GUI Config Editor
|
||
|
||
```bash
|
||
guardian config-editor
|
||
# Opens web-based config editor
|
||
```
|
||
|
||
---
|
||
|
||
## Questions & Answers
|
||
|
||
### Q: Will this be a breaking change?
|
||
|
||
**A:** No, v0.6.0 is 100% backward compatible. If no config file exists, Guardian uses the same default behavior as v0.5.1.
|
||
|
||
### Q: Can I migrate incrementally?
|
||
|
||
**A:** Yes! Start with `preset: 'clean-architecture'` and customize one rule at a time.
|
||
|
||
### Q: Will presets be updateable?
|
||
|
||
**A:** Presets are versioned with Guardian. When you update Guardian, presets update too. You can pin to a specific preset version in future versions.
|
||
|
||
### Q: Can I use TypeScript for config?
|
||
|
||
**A:** Yes, in v0.7.0+ we'll add `guardian.config.ts` support. For v0.6.0, use `.js` with JSDoc types.
|
||
|
||
---
|
||
|
||
## Timeline
|
||
|
||
| Week | Phase | Deliverable |
|
||
|------|-------|-------------|
|
||
| 1-2 | Core Configuration | Config loading works |
|
||
| 2-3 | Rule Configuration | Rules configurable |
|
||
| 3-4 | Preset System | Presets work |
|
||
| 4-5 | Ignore Patterns | Ignores work |
|
||
| 5-6 | CLI Integration | CLI supports config |
|
||
| 6-7 | Documentation | Complete docs |
|
||
| 7-8 | Beta & Release | v0.6.0 stable |
|
||
|
||
**Target Release Date:** End of Q1 2026 (February-March)
|
||
|
||
---
|
||
|
||
## Feedback & Questions
|
||
|
||
- 📧 Email: fozilbek.samiyev@gmail.com
|
||
- 🐙 GitHub: https://github.com/samiyev/puaros/issues
|
||
- 💬 Discuss: https://github.com/samiyev/puaros/discussions
|
||
|
||
---
|
||
|
||
**Status:** This specification is ready for implementation.
|
||
|
||
**Next Steps:**
|
||
1. Review and approve this spec
|
||
2. Create implementation tasks in GitHub
|
||
3. Start Phase 1 development
|
||
4. Weekly progress updates |