agpm_cli/cli/validate/
command.rs

1//! Command structure and output format definitions for validation.
2
3use clap::Args;
4
5/// Command to validate AGPM project configuration and dependencies.
6///
7/// This command performs comprehensive validation of a AGPM project, checking
8/// various aspects from basic manifest syntax to complex dependency resolution.
9/// It supports multiple validation levels and output formats for different use cases.
10///
11/// # Validation Strategy
12///
13/// The command performs validation in layers:
14/// 1. **Syntax Validation**: TOML parsing and basic structure
15/// 2. **Semantic Validation**: Required fields and references
16/// 3. **Extended Validation**: Network and dependency checks (opt-in)
17/// 4. **Consistency Validation**: Cross-file consistency checks
18///
19/// # Examples
20///
21/// ```rust,ignore
22/// use agpm_cli::cli::validate::{ValidateCommand, OutputFormat};
23///
24/// // Basic validation
25/// let cmd = ValidateCommand {
26///     file: None,
27///     resolve: false,
28///     check_lock: false,
29///     sources: false,
30///     paths: false,
31///     format: OutputFormat::Text,
32///     verbose: false,
33///     quiet: false,
34///     strict: false,
35///     render: false,
36/// };
37///
38/// // Comprehensive CI validation
39/// let cmd = ValidateCommand {
40///     file: None,
41///     resolve: true,
42///     check_lock: true,
43///     sources: true,
44///     paths: true,
45///     format: OutputFormat::Json,
46///     verbose: false,
47///     quiet: true,
48///     strict: true,
49///     render: false,
50/// };
51/// ```
52#[derive(Args)]
53pub struct ValidateCommand {
54    /// Specific manifest file path to validate
55    ///
56    /// If not provided, searches for `agpm.toml` in the current directory
57    /// and parent directories. When specified, validates the exact file path.
58    #[arg(value_name = "FILE")]
59    pub file: Option<String>,
60
61    /// Check if all dependencies can be resolved
62    ///
63    /// Performs dependency resolution to verify that all dependencies
64    /// defined in the manifest can be found and resolved to specific
65    /// versions. This requires network access to check source repositories.
66    #[arg(long, alias = "dependencies")]
67    pub resolve: bool,
68
69    /// Verify lockfile matches manifest
70    ///
71    /// Compares the manifest dependencies with those recorded in the
72    /// lockfile to identify inconsistencies. Warns if dependencies are
73    /// missing from the lockfile or if extra entries exist.
74    #[arg(long, alias = "lockfile")]
75    pub check_lock: bool,
76
77    /// Check if all sources are accessible
78    ///
79    /// Tests network connectivity to all source repositories defined
80    /// in the manifest. This verifies that sources are reachable and
81    /// accessible with current credentials.
82    #[arg(long)]
83    pub sources: bool,
84
85    /// Check if local file paths exist
86    ///
87    /// Validates that all local file dependencies (those without a
88    /// source) point to existing files on the file system.
89    #[arg(long)]
90    pub paths: bool,
91
92    /// Output format: text or json
93    ///
94    /// Controls the format of validation results:
95    /// - `text`: Human-readable output with colors and formatting
96    /// - `json`: Structured JSON output suitable for automation
97    #[arg(long, value_enum, default_value = "text")]
98    pub format: OutputFormat,
99
100    /// Verbose output
101    ///
102    /// Enables detailed output showing individual validation steps
103    /// and additional diagnostic information.
104    #[arg(short, long)]
105    pub verbose: bool,
106
107    /// Quiet output (minimal messages)
108    ///
109    /// Suppresses informational messages, showing only errors and
110    /// warnings. Useful for automated scripts and CI environments.
111    #[arg(short, long)]
112    pub quiet: bool,
113
114    /// Strict mode (treat warnings as errors)
115    ///
116    /// In strict mode, any warnings will cause the validation to fail.
117    /// This is useful for CI/CD pipelines where warnings should block
118    /// deployment or integration.
119    #[arg(long)]
120    pub strict: bool,
121
122    /// Pre-render markdown templates and validate file references
123    ///
124    /// Validates that all markdown resources can be successfully rendered
125    /// with their template syntax, and that all file references within the
126    /// markdown content point to existing files. This catches template errors
127    /// and broken cross-references before installation. Requires a lockfile
128    /// to build the template context.
129    ///
130    /// When enabled:
131    /// - Reads all markdown resources from worktrees/local paths
132    /// - Attempts to render each with the current template context
133    /// - Extracts and validates file references (markdown links and direct paths)
134    /// - Reports syntax errors, missing variables, and broken file references
135    /// - Returns non-zero exit code on validation failures
136    ///
137    /// This is useful for:
138    /// - Catching template errors in CI/CD before deployment
139    /// - Validating template syntax during development
140    /// - Ensuring referential integrity of documentation
141    /// - Testing template rendering without modifying the filesystem
142    #[arg(long)]
143    pub render: bool,
144}
145
146/// Output format options for validation results.
147///
148/// This enum defines the available output formats for validation results,
149/// allowing users to choose between human-readable and machine-parseable formats.
150///
151/// # Variants
152///
153/// - [`Text`](OutputFormat::Text): Human-readable output with colors and formatting
154/// - [`Json`](OutputFormat::Json): Structured JSON output for automation and integration
155///
156/// # Examples
157///
158/// ```rust,ignore
159/// use agpm_cli::cli::validate::OutputFormat;
160///
161/// // For human consumption
162/// let format = OutputFormat::Text;
163///
164/// // For automation/CI
165/// let format = OutputFormat::Json;
166/// ```
167#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
168pub enum OutputFormat {
169    /// Human-readable text output with colors and formatting.
170    ///
171    /// This format provides:
172    /// - Colored output (✓, ✗, ⚠ symbols)
173    /// - Contextual messages and suggestions
174    /// - Progress indicators during validation
175    /// - Formatted error and warning messages
176    Text,
177
178    /// Structured JSON output for automation.
179    ///
180    /// This format provides:
181    /// - Machine-parseable JSON structure
182    /// - Consistent field names and types
183    /// - All validation results in a single object
184    /// - Suitable for CI/CD pipeline integration
185    Json,
186}
agpm_cli/cli/validate/command.rs

agpm_cli/cli/validate/
command.rs
