WIP - Start moving Clap code to a crate for clap-markdown to be run as an xtask.

Author: larrys

Cargo.lock

@@ -71,6 +71,7 @@ name = "weaver"
 
 [dependencies]
 # local crates dependencies
+weaver_cli = { path = "crates/weaver_cli" }
 weaver_common = { path = "crates/weaver_common" }
 weaver_resolver = { path = "crates/weaver_resolver" }
 weaver_semconv = { path = "crates/weaver_semconv" }
@@ -83,7 +84,6 @@ weaver_live_check = { path = "crates/weaver_live_check" }
 
 clap = { version = "4.5.37", features = ["derive"] }
 clap_complete = "4.5.48"
-clap-markdown = "0.1.5"
 rayon = "1.10.0"
 ratatui = { version = "0.29.0", features = ["serde"] }
 tui-textarea = "0.7.0"

Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "weaver_cli"
+version.workspace = true
+authors.workspace = true
+repository.workspace = true
+license.workspace = true
+publish.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+clap = { version = "4.5.37", features = ["derive"] }
+clap_complete = "4.5.50"
+#serde_yaml = "0.9.34"
+weaver_common = { path = "../weaver_common" }
+weaver_emit = { path = "../weaver_emit" }
+serde_yaml = "0.9.34+deprecated"
+thiserror = "1.0.69"
+serde = { version = "1.0.219", features = ["derive"] }
+miette = { version = "7.5.0", features = ["fancy", "serde"] }
+
+[lints]
+workspace = true

crates/weaver_cli/Cargo.toml

@@ -0,0 +1,4 @@
+# Weaver CLI
+
+This crate is used to isolate the CLI code from the rest of the weaver codebase. This is so we can generate the markdown
+help, as well as the man page file without having to build that into the weaver binary.

crates/weaver_cli/README.md

@@ -0,0 +1,7 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+# This is used with cargo-check-external-types to reduce the surface area of downstream crates from
+# the public API. Ideally this can have a few exceptions as possible.
+allowed_external_types = [
+
+]

crates/weaver_cli/allowed-external-types.toml

@@ -6,15 +6,16 @@ use crate::diagnostic::DiagnosticCommand;
 use crate::registry::RegistryCommand;
 use clap::{Args, Parser, Subcommand};
 
-/// Command line arguments.
+/// Manage semantic convention registry and telemetry schema workflows (OpenTelemetry Project)
 #[derive(Parser)]
 #[command(
     author,
     version,
     about,
     long_about = None,
     subcommand_required = true,
-    arg_required_else_help = true
+    arg_required_else_help = true,
+    bin_name = "weaver"
 )]
 pub struct Cli {
     /// Turn debugging information on
@@ -46,11 +47,9 @@ pub enum Commands {
     Diagnostic(DiagnosticCommand),
     /// Generate shell completions
     Completion(CompletionCommand),
-    /// Generate markdown documentation (hidden)
-    #[command(hide = true)]
-    Markdown(MarkdownCommand),
 }
 
+/// Commands for generating completions and markdown documentation
 #[derive(Args)]
 pub struct CompletionCommand {
     /// The shell to generate the completions for
@@ -61,10 +60,3 @@ pub struct CompletionCommand {
     #[arg(long, hide = true)]
     pub completion_file: Option<std::path::PathBuf>,
 }
-
-#[derive(Args)]
-pub struct MarkdownCommand {
-    /// The file to write the markdown documentation to. Defaults to `STDOUT`.
-    #[arg(long)]
-    pub output_file: Option<std::path::PathBuf>,
-}

src/cli.rs renamed to crates/weaver_cli/src/cli.rs

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! Module for diagnostic init sub-command.
+
+use crate::DiagnosticArgs;
+use clap::Args;
+use std::path::PathBuf;
+
+/// Parameters for the `diagnostic init` sub-command
+#[derive(Debug, Args)]
+pub struct DiagnosticInitArgs {
+    /// Optional target to initialize the diagnostic templates for. If empty, all default templates will be extracted.
+    #[arg(default_value = "")]
+    pub target: String,
+
+    /// Optional path where the diagnostic templates directory should be created.
+    #[arg(short = 't', long, default_value = "diagnostic_templates")]
+    pub diagnostic_templates_dir: PathBuf,
+
+    /// Parameters to specify the diagnostic format.
+    #[command(flatten)]
+    pub diagnostic: DiagnosticArgs,
+}

crates/weaver_cli/src/diagnostic/init.rs

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! The weaver CLI diagnostic command module
+
+pub mod init;
+
+use clap::{Args, Subcommand};
+
+/// Parameters for the `diagnostic` command
+#[derive(Debug, Args)]
+pub struct DiagnosticCommand {
+    /// Define the sub-commands for the `diagnostic` command
+    #[clap(subcommand)]
+    pub command: DiagnosticSubCommand,
+}
+
+/// Sub-commands to manage `diagnostic` messages.
+#[derive(Debug, Subcommand)]
+#[clap(verbatim_doc_comment)]
+pub enum DiagnosticSubCommand {
+    /// Initializes a `diagnostic_templates` directory to define or override diagnostic output
+    /// formats.
+    Init(init::DiagnosticInitArgs),
+}

crates/weaver_cli/src/diagnostic/mod.rs

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! Supported output formats for the resolved registry and telemetry schema
+
+use clap::ValueEnum;
+
+/// Supported output formats for the resolved schema
+#[derive(Debug, Clone, ValueEnum)]
+pub enum Format {
+    /// YAML format
+    Yaml,
+    /// JSON format
+    Json,
+}

crates/weaver_cli/src/format.rs

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! Weaver command and subcommands
+
+use clap::Args;
+use std::path::PathBuf;
+
+pub mod cli;
+pub mod diagnostic;
+pub mod format;
+pub mod registry;
+
+/// Set of parameters used to specify the diagnostic format.
+#[derive(Args, Debug, Clone)]
+pub struct DiagnosticArgs {
+    /// Format used to render the diagnostic messages. Predefined formats are: `ansi`, `json`,
+    /// `gh_workflow_command`.
+    #[arg(long, default_value = "ansi")]
+    pub diagnostic_format: String,
+
+    /// Path to the directory where the diagnostic templates are located.
+    #[arg(long, default_value = "diagnostic_templates")]
+    pub diagnostic_template: PathBuf,
+
+    /// Send the output to stdout instead of stderr.
+    #[arg(long)]
+    pub diagnostic_stdout: bool,
+}
+
+impl Default for DiagnosticArgs {
+    fn default() -> Self {
+        Self {
+            diagnostic_format: "ansi".to_owned(),
+            diagnostic_template: PathBuf::from("diagnostic_templates"),
+            diagnostic_stdout: false,
+        }
+    }
+}