From 3ddcff1be3dd609734ff1f8bf7007c519ceabc5a Mon Sep 17 00:00:00 2001 From: imfozilbek Date: Mon, 24 Nov 2025 21:53:41 +0500 Subject: [PATCH] docs: enhance CLI help system for AI agents and users MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- packages/guardian/CHANGELOG.md | 39 ++++++++++++++ packages/guardian/package.json | 2 +- packages/guardian/src/cli/constants.ts | 75 ++++++++++++++++++++++---- packages/guardian/src/cli/index.ts | 26 ++++++++- 4 files changed, 129 insertions(+), 13 deletions(-) diff --git a/packages/guardian/CHANGELOG.md b/packages/guardian/CHANGELOG.md index 364204d..fddc96f 100644 --- 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 diff --git a/packages/guardian/package.json b/packages/guardian/package.json index 86d5505..c98eae8 100644 --- 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", diff --git a/packages/guardian/src/cli/constants.ts b/packages/guardian/src/cli/constants.ts index 72f9114..9a0f20d 100644 --- 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 diff --git a/packages/guardian/src/cli/index.ts b/packages/guardian/src/cli/index.ts index 7221dd0..a41e363 100644 --- 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( 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)