feat: enforce output version v1 and add version subcommand

src/cli.rs

@@ -18,6 +18,7 @@ pub struct Cli {
 pub enum Commands {
     Fetch(FetchArgs),
     RenderMd(RenderMdArgs),
+    Version,
 }
 
 #[derive(Debug, clap::Args)]

src/lib.rs

@@ -19,6 +19,8 @@ use crate::output::write_output;
 use crate::render::json::{parse_json, render_json};
 use crate::render::markdown::render_markdown;
 
+pub const OUTPUT_VERSION: &str = "v1";
+
 pub fn run() -> anyhow::Result<()> {
     let cli = Cli::parse();
 
@@ -29,6 +31,9 @@ pub fn run() -> anyhow::Result<()> {
             let md = render_markdown(&doc);
             write_output(args.out.as_deref().map(Path::new), &md)?;
         }
+        Commands::Version => {
+            write_output(None, OUTPUT_VERSION)?;
+        }
         Commands::Fetch(args) => {
             let token = required_env("GITEA_PR_CLI_API_TOKEN")?;
             let base_url = required_env("GITEA_PR_CLI_URL")?;

src/model.rs

@@ -2,6 +2,7 @@ use serde::{Deserialize, Serialize};
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct PrReviewDocument {
+    pub version: String,
     pub meta: PrMeta,
     pub commits: Vec<CommitItem>,
     pub diff_stat: DiffStat,
@@ -15,7 +16,7 @@ pub struct PrMeta {
     pub pr_index: i64,
     pub title: String,
     pub description: Option<String>,
-    pub fetched_at: Option<String>,
+    pub fetched_at: String,
     pub state: String,
     pub author: String,
     pub base_branch: String,

src/normalize.rs

@@ -4,6 +4,7 @@ use std::convert::TryFrom;
 use chrono::{DateTime, FixedOffset};
 
 use crate::gitea::dto::{ChangedFileDto, CommitDto, PullBundleDto, ReviewCommentDto, ReviewDto};
+use crate::OUTPUT_VERSION;
 use crate::model::{
     CommentItem, CommentThread, CommitItem, DiffStat, FileStat, PrMeta, PrReviewDocument,
     ReviewItem,
@@ -28,12 +29,13 @@ pub fn normalize_bundle(repo: &str, fetched_at: String, bundle: PullBundleDto) -
     let diff_stat = normalize_diff_stat(&pull, files);
 
     PrReviewDocument {
+        version: OUTPUT_VERSION.to_string(),
         meta: PrMeta {
             repo: repo.to_string(),
             pr_index: pull.number,
             title: pull.title,
             description: pull.body,
-            fetched_at: Some(fetched_at),
+            fetched_at,
             state: pull.state,
             author: pull.user.login,
             base_branch: pull.base.ref_name,

src/render/json.rs

@@ -1,9 +1,18 @@
 use crate::model::PrReviewDocument;
+use crate::OUTPUT_VERSION;
 
 pub fn render_json(doc: &PrReviewDocument) -> anyhow::Result<String> {
     Ok(serde_json::to_string_pretty(doc)?)
 }
 
 pub fn parse_json(input: &str) -> anyhow::Result<PrReviewDocument> {
-    Ok(serde_json::from_str(input)?)
+    let doc: PrReviewDocument = serde_json::from_str(input)?;
+    if doc.version != OUTPUT_VERSION {
+        anyhow::bail!(
+            "unsupported document version: {}, expected {}",
+            doc.version,
+            OUTPUT_VERSION
+        );
+    }
+    Ok(doc)
 }

src/render/markdown.rs

@@ -65,8 +65,8 @@ pub fn render_markdown(doc: &PrReviewDocument) -> String {
     out.push_str(
         "> 编号规则：Review `<pr>.<review>`；Comment `<pr>.<review>.<comment>`；Reply `<pr>.<review>.<comment>.<reply>`\n\n",
     );
-    let fetched_at = doc.meta.fetched_at.as_deref().unwrap_or("unknown");
-    out.push_str(&format!("> fetched at: {fetched_at}\n\n"));
+    out.push_str(&format!("> version: {}\n\n", doc.version));
+    out.push_str(&format!("> fetched at: {}\n\n", doc.meta.fetched_at));
     let pr_description = doc
         .meta
         .description