Add new subcommands to changelogger for supporting file-per-change …

…changelog (#3771)

## Motivation and Context
Adds new subcommands `--new` and `--ls` to `changelogger`

## Description
This is part 2 in a series of PRs supporting [file-per-change
changelog](https://smithy-lang.github.io/smithy-rs/design/rfcs/rfc0042_file_per_change_changelog.html).
This PR just adds utilities for humans and does NOT impact the current
dev workflow, smithy-rs CI, or our release pipeline.

#### A subcommand `--new`
We can use this subcommand when creating a new changelog entry markdown
file. An example usage:
```
$ changelogger new -t client -t aws-sdk-rust -r smithy-rs#1234 -a someone --bug-fix -m "Some changelog" \
# for long flags, replace -t with --applies-to, -r with --references, -a with --authors, and -m with --message \
# also remember to escape with \ when including backticks in the message at command line, e.g. \`pub\`

The following changelog entry has been written to "/Users/ysaito1001/src/smithy-rs/.changelog/5745197.md":
---
applies_to:
- aws-sdk-rust
- client
authors:
- someone
references:
- smithy-rs#1234
breaking: false
new_feature: false
bug_fix: true
---
Some changelog
```
The following CLI arguments are "logically" required
- `--applies-to`
- `--ref`
- `--author`
- `--message`

If any of the above is not passed a value at command line, then an
editor is opened for further edit (which editor to open can be
configured per the [edit crate](https://docs.rs/edit/0.1.5/edit/)).

Note that the YAML syntax above is different from the single line array
syntax [proposed in the
RFC](https://smithy-lang.github.io/smithy-rs/design/rfcs/rfc0042_file_per_change_changelog.html#the-proposed-developer-experience).
This is due to [a
limitation](dtolnay/serde-yaml#355) in
`serde-yaml` (which has been archived unfortunately), but the multi-line
values are still a valid YAML syntax and, most importantly, rendering
changelong entries will continue working. For now, I won't post-process
from the multi-line values syntax to the single line array syntax. One
can work around this by handwriting a changelog entry Markdown file in
`smithy-rs/.changelog` without using this subcommand.

#### A subcommand `--ls`
This subcommand will render a preview of changelog entries stored in
`smithy-rs/.changelog` and print it to the standard output. Example
usages (using the entry created at 5745197.md above):
```
$ changelogger ls -c smithy-rs \
# for long flag, replace -c with --change-set

Next changelog preview for smithy-rs
=====================================
**New this release:**
- 🐛 (client, [smithy-rs#1234](#1234), @Someone) Some changelog

**Contributors**
Thank you for your contributions! ❤
- @Someone ([smithy-rs#1234](#1234))
```
```
$ changelogger ls -c aws-sdk \
# for long flag, replace -c with --change-set

Next changelog preview for aws-sdk-rust
========================================
**New this release:**
- 🐛 ([smithy-rs#1234](#1234), @Someone) Some changelog

**Contributors**
Thank you for your contributions! ❤
- @Someone ([smithy-rs#1234](#1234))
```


## Testing
- Existing tests in CI
- Basic unit tests for subcommands

----

_By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice._

tools/ci-build/changelogger/Cargo.toml

@@ -17,10 +17,12 @@ opt-level = 0
 [dependencies]
 anyhow = "1.0.57"
 clap = { version = "~3.2.1", features = ["derive"] }
+edit = "0.1"
 once_cell = "1.15.0"
 ordinal = "0.3.2"
 serde = { version = "1", features = ["derive"]}
 serde_json = "1"
+serde_yaml = "0.9"
 smithy-rs-tool-common = { path = "../smithy-rs-tool-common" }
 time = { version = "0.3.9", features = ["local-offset"]}
 toml = "0.5.8"

tools/ci-build/changelogger/src/entry.rs

@@ -8,6 +8,7 @@ use clap::clap_derive::ArgEnum;
 use smithy_rs_tool_common::changelog::{Changelog, HandAuthoredEntry, SdkModelEntry};
 use smithy_rs_tool_common::git::Git;
 use smithy_rs_tool_common::versions_manifest::VersionsManifest;
+use std::fmt::{Display, Formatter};
 use std::path::Path;
 
 #[derive(ArgEnum, Copy, Clone, Debug, Eq, PartialEq)]
@@ -16,6 +17,19 @@ pub enum ChangeSet {
     AwsSdk,
 }
 
+impl Display for ChangeSet {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "{}",
+            match self {
+                ChangeSet::SmithyRs => "smithy-rs",
+                ChangeSet::AwsSdk => "aws-sdk-rust",
+            }
+        )
+    }
+}
+
 pub struct ChangelogEntries {
     pub aws_sdk_rust: Vec<ChangelogEntry>,
     pub smithy_rs: Vec<ChangelogEntry>,

tools/ci-build/changelogger/src/lib.rs

@@ -5,5 +5,7 @@
 
 pub mod entry;
 pub mod init;
+pub mod ls;
+pub mod new;
 pub mod render;
 pub mod split;

tools/ci-build/changelogger/src/ls.rs

@@ -0,0 +1,50 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+use crate::entry::{ChangeSet, ChangelogEntries};
+use crate::render::render;
+use anyhow::Context;
+use clap::Parser;
+use smithy_rs_tool_common::changelog::{ChangelogLoader, ValidationSet};
+use smithy_rs_tool_common::git::find_git_repository_root;
+use smithy_rs_tool_common::here;
+use smithy_rs_tool_common::versions_manifest::CrateVersionMetadataMap;
+
+#[derive(Parser, Debug, Eq, PartialEq)]
+pub struct LsArgs {
+    /// Which set of changes to preview
+    #[clap(long, short, action)]
+    pub change_set: ChangeSet,
+}
+
+pub fn subcommand_ls(args: LsArgs) -> anyhow::Result<()> {
+    let mut dot_changelog = find_git_repository_root("smithy-rs", ".").context(here!())?;
+    dot_changelog.push(".changelog");
+
+    let loader = ChangelogLoader::default();
+    let changelog = loader.load_from_dir(dot_changelog.clone())?;
+
+    changelog.validate(ValidationSet::Render).map_err(|errs| {
+        anyhow::Error::msg(format!(
+            "failed to load {dot_changelog:?}: {errors}",
+            errors = errs.join("\n")
+        ))
+    })?;
+
+    let entries = ChangelogEntries::from(changelog);
+
+    let (release_header, release_notes) = render(
+        match args.change_set {
+            ChangeSet::SmithyRs => &entries.smithy_rs,
+            ChangeSet::AwsSdk => &entries.aws_sdk_rust,
+        },
+        CrateVersionMetadataMap::new(),
+        &format!("\nNext changelog preview for {}", args.change_set),
+    );
+
+    println!("{release_header}{release_notes}");
+
+    Ok(())
+}

tools/ci-build/changelogger/src/main.rs

@@ -5,37 +5,49 @@
 
 use anyhow::Result;
 use changelogger::init::subcommand_init;
+use changelogger::ls::subcommand_ls;
+use changelogger::new::subcommand_new;
 use changelogger::render::subcommand_render;
 use changelogger::split::subcommand_split;
 use clap::Parser;
 
 #[derive(Parser, Debug, Eq, PartialEq)]
 #[clap(name = "changelogger", author, version, about)]
 pub enum Args {
-    /// Split SDK changelog entries into a separate file
-    Split(changelogger::split::SplitArgs),
+    /// Print to stdout the empty "next" CHANGELOG template
+    Init(changelogger::init::InitArgs),
+    /// Create a new changelog entry Markdown file in the `smithy-rs/.changelog` directory
+    New(changelogger::new::NewArgs),
+    /// Render a preview of changelog entries since the last release
+    Ls(changelogger::ls::LsArgs),
     /// Render a TOML/JSON changelog into GitHub-flavored Markdown
     Render(changelogger::render::RenderArgs),
-    /// Print to stdout the empty "next" CHANGELOG template.
-    Init(changelogger::init::InitArgs),
+    /// Split SDK changelog entries into a separate file
+    Split(changelogger::split::SplitArgs),
 }
 
 fn main() -> Result<()> {
     match Args::parse() {
-        Args::Split(split) => subcommand_split(&split),
-        Args::Render(render) => subcommand_render(&render),
         Args::Init(init) => subcommand_init(&init),
+        Args::New(new) => subcommand_new(new),
+        Args::Ls(ls) => subcommand_ls(ls),
+        Args::Render(render) => subcommand_render(&render),
+        Args::Split(split) => subcommand_split(&split),
     }
 }
 
 #[cfg(test)]
 mod tests {
     use super::Args;
     use changelogger::entry::ChangeSet;
+    use changelogger::ls::LsArgs;
+    use changelogger::new::NewArgs;
     use changelogger::render::RenderArgs;
     use changelogger::split::SplitArgs;
     use clap::Parser;
+    use smithy_rs_tool_common::changelog::{Reference, Target};
     use std::path::PathBuf;
+    use std::str::FromStr;
 
     #[test]
     fn args_parsing() {
@@ -188,5 +200,55 @@ mod tests {
             ])
             .unwrap()
         );
+
+        assert_eq!(
+            Args::New(NewArgs {
+                applies_to: Some(vec![Target::Client, Target::AwsSdk]),
+                authors: Some(vec!["external-contrib".to_owned(), "ysaito1001".to_owned()]),
+                references: Some(vec![
+                    Reference::from_str("smithy-rs#1234").unwrap(),
+                    Reference::from_str("aws-sdk-rust#5678").unwrap()
+                ]),
+                breaking: false,
+                new_feature: true,
+                bug_fix: false,
+                message: Some("Implement a long-awaited feature for S3".to_owned()),
+                basename: None,
+            }),
+            Args::try_parse_from([
+                "./changelogger",
+                "new",
+                "--applies-to",
+                "client",
+                "--applies-to",
+                "aws-sdk-rust",
+                "--authors",
+                "external-contrib",
+                "--authors",
+                "ysaito1001",
+                "--references",
+                "smithy-rs#1234",
+                "--references",
+                "aws-sdk-rust#5678",
+                "--new-feature",
+                "--message",
+                "Implement a long-awaited feature for S3",
+            ])
+            .unwrap()
+        );
+
+        assert_eq!(
+            Args::Ls(LsArgs {
+                change_set: ChangeSet::SmithyRs
+            }),
+            Args::try_parse_from(["./changelogger", "ls", "--change-set", "smithy-rs",]).unwrap()
+        );
+
+        assert_eq!(
+            Args::Ls(LsArgs {
+                change_set: ChangeSet::AwsSdk
+            }),
+            Args::try_parse_from(["./changelogger", "ls", "--change-set", "aws-sdk",]).unwrap()
+        );
     }
 }