docs: enhance CLI help system for AI agents and users

Improved guardian --help with comprehensive, actionable information: - Add DETECTS section with quick fix instructions for all 8 violation types - Add SEVERITY LEVELS explanation (CRITICAL → LOW) - Add step-by-step WORKFLOW guide - Add 7 practical EXAMPLES covering common use cases - Add HOW TO FIX COMMON ISSUES reference section Technical improvements: - Extract all help text strings to CLI_HELP_TEXT constants - Fix 17 hardcoded string violations - Maintain Single Source of Truth principle - Zero violations in Guardian's own codebase The help system now provides complete context for autonomous AI agents and clear guidance for human developers.
docs: update ROADMAP to v0.6.0
2025-12-27 23:06:54 +05:00 · 2025-11-24 21:53:41 +05:00 · 2025-11-24 21:37:11 +05:00
5 changed files with 194 additions and 37 deletions
--- a/packages/guardian/CHANGELOG.md
+++ b/packages/guardian/CHANGELOG.md
@@ -5,6 +5,45 @@ All notable changes to @samiyev/guardian will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

+## [0.6.1] - 2025-11-24
+
+### Improved
+
+**📖 Enhanced CLI Help System**
+
+Guardian's `--help` command is now comprehensive and AI-agent-friendly!
+
+- ✅ **Detailed Main Help**
+  - Complete detector descriptions with quick fix instructions
+  - Severity level explanations (CRITICAL → LOW)
+  - Step-by-step workflow guide for fixing violations
+  - 7 practical usage examples
+  - "HOW TO FIX COMMON ISSUES" reference section
+
+- ✅ **Better Organization**
+  - Clear DETECTS section with all 8 violation types
+  - Each detector includes → what to do to fix it
+  - Severity system with priority guidance
+  - Examples cover all major use cases
+
+- ✅ **AI Agent Ready**
+  - Help output provides complete context for autonomous agents
+  - Actionable instructions for each violation type
+  - Clear workflow: run → review → fix → verify
+
+### Fixed
+
+- **Code Quality**: Extracted all hardcoded strings from help text to constants
+  - Moved 17 magic strings to `CLI_HELP_TEXT` constant
+  - Improved maintainability and i18n readiness
+  - Follows Clean Code principles (Single Source of Truth)
+
+### Technical
+
+- All CLI help strings now use `CLI_HELP_TEXT` from constants
+- Zero hardcode violations in Guardian's own codebase
+- Passes all quality checks (format, lint, build, self-check)
+
 ## [0.6.0] - 2025-11-24

 ### Added
--- a/packages/guardian/ROADMAP.md
+++ b/packages/guardian/ROADMAP.md
@@ -2,7 +2,7 @@

 This document outlines the current features and future plans for @puaros/guardian.

-## Current Version: 0.5.2 ✅ RELEASED
+## Current Version: 0.6.0 ✅ RELEASED

 **Released:** 2025-11-24

@@ -198,6 +198,47 @@ guardian check src --min-severity high

 ---

+## Version 0.6.0 - Output Limit Control & ESLint Optimization 🎯 ✅ RELEASED
+
+**Released:** 2025-11-24
+**Priority:** MEDIUM
+
+Control output verbosity for large codebases and achieve perfect code quality:
+
+```bash
+# Limit detailed output for large codebases
+guardian check src --limit 10
+
+# Combine with severity filters
+guardian check src --only-critical --limit 5
+
+# Short form
+guardian check src -l 20
+```
+
+**Implemented Features:**
+- ✅ `--limit` option to control detailed violation output per category
+- ✅ Short form `-l <number>` for convenience
+- ✅ Works seamlessly with `--only-critical` and `--min-severity` filters
+- ✅ Warning message when violations exceed limit
+- ✅ Full statistics always displayed at the end
+- ✅ Severity display constants extracted (`SEVERITY_DISPLAY_LABELS`, `SEVERITY_SECTION_HEADERS`)
+- ✅ ESLint configuration optimized (reduced warnings from 129 to 0)
+- ✅ CLI-specific overrides for no-console, complexity, max-lines-per-function
+- ✅ Dead code removal (unused IBaseRepository interface)
+- ✅ Complete development workflow added to CLAUDE.md
+- ✅ 292 tests passing with 90.63% coverage
+- ✅ Guardian self-check: ✅ 0 issues found
+
+**Benefits:**
+- Better experience with large codebases
+- Faster CI/CD output
+- Improved CLI maintainability with constants
+- Perfect ESLint score (0 errors, 0 warnings)
+- Guardian now passes its own quality checks
+
+---
+
 ## Version 0.5.1 - Code Quality Refactoring 🧹 ✅ RELEASED

 **Released:** 2025-11-24
@@ -254,7 +295,7 @@ class Order {

 ---

-### Version 0.7.0 - Anemic Domain Model Detection 🩺
+### Version 0.8.0 - Anemic Domain Model Detection 🩺
 **Target:** Q2 2026
 **Priority:** MEDIUM

@@ -295,7 +336,7 @@ class Order {

 ---

-### Version 0.7.0 - Domain Event Usage Validation 📢
+### Version 0.8.0 - Domain Event Usage Validation 📢
 **Target:** Q2 2026
 **Priority:** MEDIUM

@@ -334,7 +375,7 @@ class Order {

 ---

-### Version 0.8.0 - Value Object Immutability Check 🔐
+### Version 0.9.0 - Value Object Immutability Check 🔐
 **Target:** Q2 2026
 **Priority:** MEDIUM

@@ -377,7 +418,7 @@ class Email {

 ---

-### Version 0.9.0 - Use Case Single Responsibility 🎯
+### Version 0.10.0 - Use Case Single Responsibility 🎯
 **Target:** Q2 2026
 **Priority:** LOW

@@ -414,7 +455,7 @@ class SendWelcomeEmail {

 ---

-### Version 0.10.0 - Interface Segregation Validation 🔌
+### Version 0.11.0 - Interface Segregation Validation 🔌
 **Target:** Q2 2026
 **Priority:** LOW

@@ -459,7 +500,7 @@ interface IUserExporter {

 ---

-### Version 0.11.0 - Port-Adapter Pattern Validation 🔌
+### Version 0.12.0 - Port-Adapter Pattern Validation 🔌
 **Target:** Q2 2026
 **Priority:** MEDIUM

@@ -498,7 +539,7 @@ class TwilioAdapter implements INotificationPort {

 ---

-### Version 0.12.0 - Configuration File Support ⚙️
+### Version 0.13.0 - Configuration File Support ⚙️
 **Target:** Q3 2026
 **Priority:** MEDIUM

@@ -549,7 +590,7 @@ export default {

 ---

-### Version 0.13.0 - Command Query Separation (CQS/CQRS) 📝
+### Version 0.14.0 - Command Query Separation (CQS/CQRS) 📝
 **Target:** Q3 2026
 **Priority:** MEDIUM

@@ -610,7 +651,7 @@ class GetUser {  // Query

 ---

-### Version 0.14.0 - Factory Pattern Validation 🏭
+### Version 0.15.0 - Factory Pattern Validation 🏭
 **Target:** Q3 2026
 **Priority:** LOW

@@ -693,7 +734,7 @@ class Order {

 ---

-### Version 0.15.0 - Specification Pattern Detection 🔍
+### Version 0.16.0 - Specification Pattern Detection 🔍
 **Target:** Q3 2026
 **Priority:** MEDIUM

@@ -765,7 +806,7 @@ class ApproveOrder {

 ---

-### Version 0.16.0 - Layered Service Anti-pattern Detection ⚠️
+### Version 0.17.0 - Layered Service Anti-pattern Detection ⚠️
 **Target:** Q3 2026
 **Priority:** MEDIUM

@@ -842,7 +883,7 @@ class OrderService {

 ---

-### Version 0.17.0 - Bounded Context Leak Detection 🚧
+### Version 0.18.0 - Bounded Context Leak Detection 🚧
 **Target:** Q3 2026
 **Priority:** LOW

@@ -907,7 +948,7 @@ class ProductPriceChangedHandler {

 ---

-### Version 0.18.0 - Transaction Script vs Domain Model Detection 📜
+### Version 0.19.0 - Transaction Script vs Domain Model Detection 📜
 **Target:** Q3 2026
 **Priority:** LOW

@@ -974,7 +1015,7 @@ class Order {

 ---

-### Version 0.19.0 - Persistence Ignorance Validation 💾
+### Version 0.20.0 - Persistence Ignorance Validation 💾
 **Target:** Q3 2026
 **Priority:** MEDIUM

@@ -1060,7 +1101,7 @@ class UserEntityMapper {

 ---

-### Version 0.20.0 - Null Object Pattern Detection 🎭
+### Version 0.21.0 - Null Object Pattern Detection 🎭
 **Target:** Q3 2026
 **Priority:** LOW

@@ -1142,7 +1183,7 @@ class ProcessOrder {

 ---

-### Version 0.21.0 - Primitive Obsession in Methods 🔢
+### Version 0.22.0 - Primitive Obsession in Methods 🔢
 **Target:** Q3 2026
 **Priority:** MEDIUM

@@ -1209,7 +1250,7 @@ class Order {

 ---

-### Version 0.22.0 - Service Locator Anti-pattern 🔍
+### Version 0.23.0 - Service Locator Anti-pattern 🔍
 **Target:** Q4 2026
 **Priority:** MEDIUM

@@ -1269,7 +1310,7 @@ class CreateUser {

 ---

-### Version 0.23.0 - Double Dispatch Pattern Validation 🎯
+### Version 0.24.0 - Double Dispatch Pattern Validation 🎯
 **Target:** Q4 2026
 **Priority:** LOW

@@ -1346,7 +1387,7 @@ class ShippingCostCalculator implements IOrderItemVisitor {

 ---

-### Version 0.24.0 - Entity Identity Validation 🆔
+### Version 0.25.0 - Entity Identity Validation 🆔
 **Target:** Q4 2026
 **Priority:** MEDIUM

@@ -1439,7 +1480,7 @@ class UserId {

 ---

-### Version 0.25.0 - Saga Pattern Detection 🔄
+### Version 0.26.0 - Saga Pattern Detection 🔄
 **Target:** Q4 2026
 **Priority:** LOW

@@ -1537,7 +1578,7 @@ abstract class SagaStep {

 ---

-### Version 0.26.0 - Anti-Corruption Layer Detection 🛡️
+### Version 0.27.0 - Anti-Corruption Layer Detection 🛡️
 **Target:** Q4 2026
 **Priority:** MEDIUM

@@ -1623,7 +1664,7 @@ interface IOrderSyncPort {

 ---

-### Version 0.27.0 - Ubiquitous Language Validation 📖
+### Version 0.28.0 - Ubiquitous Language Validation 📖
 **Target:** Q4 2026
 **Priority:** HIGH

@@ -1811,4 +1852,4 @@ Until we reach 1.0.0, minor version bumps (0.x.0) may include breaking changes a
 ---

 **Last Updated:** 2025-11-24
-**Current Version:** 0.5.0
+**Current Version:** 0.6.0
--- a/packages/guardian/package.json
+++ b/packages/guardian/package.json
@@ -1,6 +1,6 @@
 {
    "name": "@samiyev/guardian",
-    "version": "0.6.0",
+    "version": "0.6.1",
    "description": "Code quality guardian for vibe coders and enterprise teams - catch hardcodes, architecture violations, and circular deps. Enforce Clean Architecture at scale. Works with Claude, GPT, Copilot.",
    "keywords": [
        "puaros",
--- a/packages/guardian/src/cli/constants.ts
+++ b/packages/guardian/src/cli/constants.ts
@@ -13,16 +13,39 @@ export const CLI_COMMANDS = {
 } as const

 export const CLI_DESCRIPTIONS = {
-    MAIN: "🛡️  Code quality guardian - detect hardcoded values and architecture violations",
-    CHECK: "Analyze project for code quality issues",
-    PATH_ARG: "Path to analyze",
-    EXCLUDE_OPTION: "Directories to exclude",
-    VERBOSE_OPTION: "Verbose output",
-    NO_HARDCODE_OPTION: "Skip hardcode detection",
-    NO_ARCHITECTURE_OPTION: "Skip architecture checks",
-    MIN_SEVERITY_OPTION: "Minimum severity level (critical, high, medium, low)",
-    ONLY_CRITICAL_OPTION: "Show only critical severity issues",
-    LIMIT_OPTION: "Limit detailed output to specified number of violations per category",
+    MAIN:
+        "🛡️  Guardian - Code quality analyzer for TypeScript/JavaScript projects\n\n" +
+        "DETECTS:\n" +
+        "  • Hardcoded values (magic numbers/strings) - extract to constants\n" +
+        "  • Circular dependencies - refactor module structure\n" +
+        "  • Framework leaks in domain - move framework imports to infrastructure\n" +
+        "  • Naming violations - rename files to match layer conventions\n" +
+        "  • Architecture violations - respect Clean Architecture layers\n" +
+        "  • Entity exposure - use DTOs instead of returning entities\n" +
+        "  • Dependency direction - ensure dependencies flow inward\n" +
+        "  • Repository pattern - enforce repository interfaces in domain\n\n" +
+        "SEVERITY LEVELS:\n" +
+        "  🔴 CRITICAL - Must fix immediately (breaks architecture)\n" +
+        "  🟠 HIGH     - Should fix soon (major quality issue)\n" +
+        "  🟡 MEDIUM   - Should fix (moderate quality issue)\n" +
+        "  🟢 LOW      - Nice to fix (minor quality issue)",
+    CHECK:
+        "Analyze project for code quality and architecture issues\n\n" +
+        "WORKFLOW:\n" +
+        "  1. Run: guardian check ./src\n" +
+        "  2. Review violations by severity\n" +
+        "  3. Read the suggestion for each violation\n" +
+        "  4. Fix violations starting with CRITICAL\n" +
+        "  5. Re-run to verify fixes",
+    PATH_ARG: "Path to analyze (e.g., ./src or ./packages/api)",
+    EXCLUDE_OPTION:
+        "Exclude dirs/patterns (default: node_modules,dist,build,coverage,tests,**/*.test.ts)",
+    VERBOSE_OPTION: "Show additional help and analysis details",
+    NO_HARDCODE_OPTION: "Skip hardcode detection (only check architecture)",
+    NO_ARCHITECTURE_OPTION: "Skip architecture checks (only check hardcodes)",
+    MIN_SEVERITY_OPTION: "Filter by severity: critical|high|medium|low (e.g., --min-severity high)",
+    ONLY_CRITICAL_OPTION: "Show only 🔴 CRITICAL issues (shortcut for --min-severity critical)",
+    LIMIT_OPTION: "Limit violations shown per category (e.g., -l 10 shows first 10)",
 } as const

 export const CLI_OPTIONS = {
@@ -43,7 +66,8 @@ export const SEVERITY_DISPLAY_LABELS = {
 } as const

 export const SEVERITY_SECTION_HEADERS = {
-    CRITICAL: "\n═══════════════════════════════════════════\n🔴 CRITICAL SEVERITY\n═══════════════════════════════════════════",
+    CRITICAL:
+        "\n═══════════════════════════════════════════\n🔴 CRITICAL SEVERITY\n═══════════════════════════════════════════",
    HIGH: "\n═══════════════════════════════════════════\n🟠 HIGH SEVERITY\n═══════════════════════════════════════════",
    MEDIUM: "\n═══════════════════════════════════════════\n🟡 MEDIUM SEVERITY\n═══════════════════════════════════════════",
    LOW: "\n═══════════════════════════════════════════\n🟢 LOW SEVERITY\n═══════════════════════════════════════════",
@@ -94,3 +118,32 @@ export const CLI_LABELS = {
    HARDCODE_VIOLATIONS: "hardcoded values:",
    ISSUES_TOTAL: "issues total",
 } as const
+
+export const CLI_HELP_TEXT = {
+    POSITION: "after",
+    EXAMPLES_HEADER: "\nEXAMPLES:\n",
+    EXAMPLE_BASIC: "  $ guardian check ./src                          # Analyze src directory\n",
+    EXAMPLE_CRITICAL:
+        "  $ guardian check ./src --only-critical          # Show only critical issues\n",
+    EXAMPLE_SEVERITY:
+        "  $ guardian check ./src --min-severity high      # Show high and critical\n",
+    EXAMPLE_LIMIT:
+        "  $ guardian check ./src --limit 10               # Limit output to 10 per category\n",
+    EXAMPLE_NO_HARDCODE:
+        "  $ guardian check ./src --no-hardcode            # Skip hardcode detection\n",
+    EXAMPLE_NO_ARCHITECTURE:
+        "  $ guardian check ./src --no-architecture        # Skip architecture checks\n",
+    EXAMPLE_EXCLUDE:
+        "  $ guardian check ./src -e dist build            # Exclude additional dirs\n\n",
+    FIX_HEADER: "HOW TO FIX COMMON ISSUES:\n",
+    FIX_HARDCODE: "  Hardcoded values    → Extract to constants file\n",
+    FIX_CIRCULAR: "  Circular deps       → Break cycle by extracting shared code\n",
+    FIX_FRAMEWORK: "  Framework leaks     → Move Express/NestJS imports to infrastructure layer\n",
+    FIX_NAMING: "  Naming violations   → Rename file (e.g., UserEntity.ts, CreateUserUseCase.ts)\n",
+    FIX_ENTITY: "  Entity exposure     → Create DTO and map entity to DTO before returning\n",
+    FIX_DEPENDENCY:
+        "  Dependency direction → Move import to correct layer (domain ← app ← infra)\n",
+    FIX_REPOSITORY:
+        "  Repository pattern  → Create IUserRepository in domain, implement in infra\n\n",
+    FOOTER: "Each violation includes a 💡 Suggestion with specific fix instructions.\n",
+} as const
--- a/packages/guardian/src/cli/index.ts
+++ b/packages/guardian/src/cli/index.ts
@@ -6,6 +6,7 @@ import {
    CLI_ARGUMENTS,
    CLI_COMMANDS,
    CLI_DESCRIPTIONS,
+    CLI_HELP_TEXT,
    CLI_LABELS,
    CLI_MESSAGES,
    CLI_OPTIONS,
@@ -99,7 +100,30 @@ function displayGroupedViolations<T extends { severity: SeverityLevel }>(

 const program = new Command()

-program.name(CLI_COMMANDS.NAME).description(CLI_DESCRIPTIONS.MAIN).version(version)
+program
+    .name(CLI_COMMANDS.NAME)
+    .description(CLI_DESCRIPTIONS.MAIN)
+    .version(version)
+    .addHelpText(
+        CLI_HELP_TEXT.POSITION,
+        CLI_HELP_TEXT.EXAMPLES_HEADER +
+            CLI_HELP_TEXT.EXAMPLE_BASIC +
+            CLI_HELP_TEXT.EXAMPLE_CRITICAL +
+            CLI_HELP_TEXT.EXAMPLE_SEVERITY +
+            CLI_HELP_TEXT.EXAMPLE_LIMIT +
+            CLI_HELP_TEXT.EXAMPLE_NO_HARDCODE +
+            CLI_HELP_TEXT.EXAMPLE_NO_ARCHITECTURE +
+            CLI_HELP_TEXT.EXAMPLE_EXCLUDE +
+            CLI_HELP_TEXT.FIX_HEADER +
+            CLI_HELP_TEXT.FIX_HARDCODE +
+            CLI_HELP_TEXT.FIX_CIRCULAR +
+            CLI_HELP_TEXT.FIX_FRAMEWORK +
+            CLI_HELP_TEXT.FIX_NAMING +
+            CLI_HELP_TEXT.FIX_ENTITY +
+            CLI_HELP_TEXT.FIX_DEPENDENCY +
+            CLI_HELP_TEXT.FIX_REPOSITORY +
+            CLI_HELP_TEXT.FOOTER,
+    )

 program
    .command(CLI_COMMANDS.CHECK)