feat(deepdiffgo): add description flags for specs

.github/workflows/check-api-diff-and-add-report.yml

@@ -75,7 +75,11 @@ jobs:
           # 3. Execute DeepDiffGo
           # ========================================================
           echo "Running DeepDiffGo..."
-          if deepdiffgo "$PREV_SPEC_FILE" "$CURR_SPEC_FILE" --format markdown --output "$REPORT_FILE"; then
+          if deepdiffgo "$PREV_SPEC_FILE" "$CURR_SPEC_FILE" \
+            --old-desc "$PREV_TAG" \
+            --new-desc "${{ inputs.target_branch }}(${{ steps.get_sha.outputs.short_sha }})" \
+            --format markdown \
+            --output "$REPORT_FILE"; then
             echo "DeepDiffGo completed successfully."
           else
             echo "DeepDiffGo failed execution."

.github/workflows/check-api-diff-on-pr.yml

@@ -44,6 +44,8 @@ jobs:
           PREV_SPEC_FILE="prev_spec.yaml"
           CURR_SPEC_FILE="${{ env.API_DOC_PATH }}"
           BASE_REF="origin/${{ github.base_ref }}"
+          PR_HEAD_SHA="$(git rev-parse --short ${{ github.event.pull_request.head.sha }})"
+          PR_BRANCH="${{ github.event.pull_request.head.ref }}"
 
           # ========================================================
           # 2. Extract Previous API Spec (from Base Branch)
@@ -61,12 +63,19 @@ jobs:
             touch "$PREV_SPEC_FILE"
           fi
 
+          # Get base branch SHA
+          BASE_SHA="$(git rev-parse --short $BASE_REF)"
+
           # ========================================================
           # 3. Execute DeepDiffGo (Compare Prev vs Curr)
           # ========================================================
           echo "Running DeepDiffGo..."
 
-          if deepdiffgo "$PREV_SPEC_FILE" "$CURR_SPEC_FILE" --format text --output "$REPORT_FILE"; then
+          if deepdiffgo "$PREV_SPEC_FILE" "$CURR_SPEC_FILE" \
+            --old-desc "${{ github.base_ref }}($BASE_SHA)" \
+            --new-desc "PR#${{ github.event.pull_request.number }}($PR_HEAD_SHA)" \
+            --format text \
+            --output "$REPORT_FILE"; then
             echo "DeepDiffGo completed successfully."
           else
             echo "DeepDiffGo failed execution."

deepdiffgo/README.md

@@ -77,6 +77,29 @@ deepdiffgo old.yaml new.yaml -f markdown -o report.md
 deepdiffgo old.yaml new.yaml -f json -o report.json
 ```
 
+### Adding Descriptions to Specs
+
+You can add descriptions (such as version tags, branch names, or commit SHAs) to each specification file. These descriptions will be displayed in the comparison report next to each file name.
+
+```bash
+# Add descriptions for version tracking
+deepdiffgo old.yaml new.yaml --old-desc "v1.0.0" --new-desc "v1.1.0"
+
+# Add descriptions for branch/commit tracking
+deepdiffgo prev_spec.yaml api/swagger.yaml --old-desc "release/v1.0" --new-desc "main(abc123)"
+
+# With Markdown output
+deepdiffgo old.yaml new.yaml --old-desc "v1.0.0" --new-desc "v1.1.0" -f markdown -o report.md
+```
+
+**Output example:**
+
+```
+Diff between:
+  - Old: prev_spec.yaml [v1.0.0]
+  - New: api/swagger.yaml [main(abc123)]
+```
+
 ### Help
 
 View all available options:

deepdiffgo/cmd/deepdiffgo/main.go

@@ -15,6 +15,8 @@ import (
 func main() {
 	var outputFile string
 	var format string
+	var oldDesc string
+	var newDesc string
 
 	var rootCmd = &cobra.Command{
 		Use:   "deepdiffgo [old_spec] [new_spec]",
@@ -26,7 +28,10 @@ func main() {
   deepdiffgo https://example.com/v1/swagger.yaml new_swagger.yaml
 
   # Output as Markdown to a file
-  deepdiffgo old.yaml new.yaml -f markdown -o report.md`,
+  deepdiffgo old.yaml new.yaml -f markdown -o report.md
+
+  # Add descriptions for each spec file
+  deepdiffgo old.yaml new.yaml --old-desc "v1.0.0" --new-desc "main/abc123"`,
 		Args: cobra.ExactArgs(2),
 		Run: func(cmd *cobra.Command, args []string) {
 			oldPath := args[0]
@@ -64,7 +69,9 @@ func main() {
 			}
 
 			diffReport.Spec1 = oldPath
+			diffReport.Spec1Desc = oldDesc
 			diffReport.Spec2 = newPath
+			diffReport.Spec2Desc = newDesc
 
 			var w io.Writer = os.Stdout
 			if outputFile != "" {
@@ -90,6 +97,8 @@ func main() {
 
 	rootCmd.Flags().StringVarP(&outputFile, "output", "o", "", "Output file path (default stdout)")
 	rootCmd.Flags().StringVarP(&format, "format", "f", "text", "Output format: text, markdown, json")
+	rootCmd.Flags().StringVar(&oldDesc, "old-desc", "", "Description for old spec (e.g., tag version, branch/SHA)")
+	rootCmd.Flags().StringVar(&newDesc, "new-desc", "", "Description for new spec (e.g., tag version, branch/SHA)")
 
 	if err := rootCmd.Execute(); err != nil {
 		fmt.Println(err)

deepdiffgo/pkg/diff/diff.go

@@ -32,7 +32,9 @@ type APIChange struct {
 
 type DiffReport struct {
 	Spec1      string      `json:"spec1,omitempty"`
+	Spec1Desc  string      `json:"spec1Desc,omitempty"`
 	Spec2      string      `json:"spec2,omitempty"`
+	Spec2Desc  string      `json:"spec2Desc,omitempty"`
 	APIChanges []APIChange `json:"apiChanges"`
 }
 

deepdiffgo/pkg/report/report.go

@@ -17,9 +17,17 @@ func WriteText(w io.Writer, report *diff.DiffReport) {
 
 	fmt.Fprintln(w, "DeepDiffGo Report")
 	if report.Spec1 != "" && report.Spec2 != "" {
-		fmt.Fprintln(w, "Comparing:")
-		fmt.Fprintf(w, "  - Old: %s\n", report.Spec1)
-		fmt.Fprintf(w, "  - New: %s\n", report.Spec2)
+		fmt.Fprintln(w, "Diff between:")
+		oldSpec := report.Spec1
+		if report.Spec1Desc != "" {
+			oldSpec += fmt.Sprintf(" [%s]", report.Spec1Desc)
+		}
+		newSpec := report.Spec2
+		if report.Spec2Desc != "" {
+			newSpec += fmt.Sprintf(" [%s]", report.Spec2Desc)
+		}
+		fmt.Fprintf(w, "  - Old: %s\n", oldSpec)
+		fmt.Fprintf(w, "  - New: %s\n", newSpec)
 	}
 	fmt.Fprintln(w, "=================")
 
@@ -64,9 +72,17 @@ func WriteMarkdown(w io.Writer, report *diff.DiffReport) {
 
 	fmt.Fprintln(w, "## DeepDiffGo Report")
 	if report.Spec1 != "" && report.Spec2 != "" {
-		fmt.Fprintln(w, "**Comparing:**")
-		fmt.Fprintf(w, "- Old: `%s`\n", report.Spec1)
-		fmt.Fprintf(w, "- New: `%s`\n", report.Spec2)
+		fmt.Fprintln(w, "**Diff between:**")
+		oldSpec := report.Spec1
+		if report.Spec1Desc != "" {
+			oldSpec += fmt.Sprintf(" [%s]", report.Spec1Desc)
+		}
+		newSpec := report.Spec2
+		if report.Spec2Desc != "" {
+			newSpec += fmt.Sprintf(" [%s]", report.Spec2Desc)
+		}
+		fmt.Fprintf(w, "- Old: `%s`\n", oldSpec)
+		fmt.Fprintf(w, "- New: `%s`\n", newSpec)
 	}
 	fmt.Fprintln(w, "")