summary

README

go-deps-diff-summary

A Go library for generating human-readable Markdown summaries of dependency changes detected by the go-deps-diff library.

Overview

summary is a Go module that transforms dependency diff data into formatted Markdown output. It takes a DiffMap from go-deps-diff and produces organized, categorized summaries with visual indicators for package relationships and change types.

Installation

go get github.com/yoanm/go-deps-diff-summary

Quick Start

The library provides one main entry point for generating summaries:

Generate a Markdown Summary

package main

import (
    "fmt"
    "log"

    "github.com/yoanm/go-deps-diff/contract"
    summary "github.com/yoanm/go-deps-diff-summary"
)

func main() {
    // Assuming you have a DiffMap from go-deps-diff
    // This would typically come from comparing two dependency trees
    changes := contract.DiffMap{
        "package-name": &contract.PackageChange{
            Operation: contract.Operation{
                Name: contract.UpgradeOperation,
                SemverType: contract.SemverMinorUpdate,
            },
            Package: /* package info */,
            PreviousVersion: contract.PkgVersion{Label: "1.0.0"},
        },
    }
    
    // Generate Markdown summary
    markdown := summary.GenerateForChanges(changes, "Composer")
    
    // Output or save the markdown
    fmt.Println(markdown)
}

Features

• ✅ Generates structured Markdown with collapsible sections
• ✅ Organizes changes by type (additions, removals, updates, unchanged)
• ✅ Categorizes packages by role (prod requirements, dev requirements, transitive dependencies)
• ✅ Uses Unicode symbols for quick visual identification
• ✅ Detects and marks abandoned packages
• ✅ Tracks semantic version changes (major/minor/patch updates vs downgrades)
• ✅ Supports non-semantic versions (commit hashes, custom versions)
• ✅ Generates HTML tables for detailed package information
• ✅ Integrates seamlessly with go-deps-diff output
• ✅ Comprehensive error handling through go-deps-diff contracts

How It Works

1. Input: Accepts a contract.DiffMap from go-deps-diff containing all detected changes
2. Categorization: Organizes packages by change type (additions, removals, updates, unchanged) and category (prod, dev, transitive)
3. Formatting: Applies visual styling with symbols, colors, and hierarchical structure
4. Output: Returns a single Markdown string ready for display, documentation, or file storage

API Reference

Main Functions

GenerateForChanges(changes contract.DiffMap, managerName string) string

Generates a Markdown summary of package changes.

Parameters:

• changes: A contract.DiffMap containing package changes from go-deps-diff
• managerName: Name of the package manager (e.g., "Composer", "Npm") used in headers

Returns:

• string: Formatted Markdown summary with organized sections and symbols

Example:

markdown := summary.GenerateForChanges(changes, "Composer")
fmt.Println(markdown)

BuildVersionLabel(version contract.PkgVersion) string

Formats a package version into a display label with appropriate indicators.

Parameters:

• version: A contract.PkgVersion to format

Returns:

• string: Formatted version label, with ❗ appended if non-semantic

Example:

label := summary.BuildVersionLabel(pkgVersion)
// May return: "1.2.3" or "abc1234❗" for non-semantic versions

GetPackageSymbol(pkg contract.PkgWrapper) string

Returns a Unicode symbol indicating the package type.

Parameters:

• pkg: A contract.PkgWrapper representing the package

Returns:

• string: Unicode emoji - 🗄️ (root requirement), 🧰 (root dev), or 🔗️ (transitive)

Example:

symbol := summary.GetPackageSymbol(pkg)
// Returns one of: 🗄️, 🧰, 🔗️

GetOperationSymbol(operation contract.Operation) string

Returns a Unicode symbol representing the change operation.

Parameters:

• operation: A contract.Operation describing the change

Returns:

• string: Unicode emoji representing the operation (may include HTML sub/sup tags)

Symbol Reference:

• ➕ - Package added
• ❌ - Package removed
• 🔺 - Major version upgrade
• 🔻 - Major version downgrade
• 🔹.🔺.🔹 - Minor version upgrade
• 🔹.🔹.🔺 - Patch version upgrade
• 🟰 - No change
• ❓ - Unknown operation

Example:

symbol := summary.GetOperationSymbol(operation)
// May return: ➕, ❌, or nested version update symbols

Symbol Reference

The library uses Unicode symbols to represent package states and changes visually:

Package Type Symbols

• 🗄️ - Root requirement (explicitly required in project)
• 🧰 - Root dev requirement (explicitly required for development)
• 🔗️ - Transitive dependency (required by other packages)
• 💀 - Abandoned package (attached to package name)

Operation Symbols

• ➕ - Addition (new package)
• ❌ - Removal (package deleted)
• 🔺 - Major/Minor/Patch version change (upgrade)
• 🔻 - Major/Minor/Patch version change (downgrade)
• 🟰 - No change
• ❓ - Unknown operation
• ❔ - Unmanaged case

Examples

Generate and Save Markdown

changes, err := difflib.Diff(oldDeps, newDeps)
if err != nil {
    log.Fatal(err)
}

// Generate summary
markdown := summary.GenerateForChanges(changes, "Composer")

// Save to file
err = os.WriteFile("dependency-changes.md", []byte(markdown), 0644)
if err != nil {
    log.Fatal(err)
}

fmt.Println("Summary saved to dependency-changes.md")

Subpackages

markdown

The markdown package provides internal utilities for building Markdown output:

• Builder - Main builder for constructing Markdown documents
• NewBuilder() - Creates a new Builder instance
• Support for headers, tables, details/collapsible sections, and HTML elements

This is a package used by the summary module to format output.

Testing

make test

Related Projects

• go-deps-diff - Generic dependency comparison library that powers this tool
• go-composer-diff - PHP Composer comparison library

License

See LICENSE file for details.

Documentation

Overview

Package summary generates human-readable Markdown summaries of dependency changes.

It transforms dependency diff data from the go-deps-diff library into organized, categorized Markdown output with visual indicators for package relationships and change types. The output includes collapsible sections, Unicode symbols for quick visual scanning, and semantic version tracking.

The GenerateForChanges function is the primary API. It accepts a DiffMap from go-deps-diff and produces a Markdown string ready for display, documentation, or file storage.

Example:

changes, err := difflib.Diff(oldPkgs, newPkgs)
if err != nil {
	log.Fatal(err)
}
markdown := summary.GenerateForChanges(changes, "Composer")
fmt.Println(markdown)

Helper Functions:

- BuildVersionLabel: Formats versions with semantic version indicators - GetPackageSymbol: Returns symbols indicating package type/relationship - GetOperationSymbol: Returns symbols for change operations

Index

• Constants
• func BuildVersionLabel(version contract.PkgVersion) string
• func GenerateForChanges(changes contract.DiffMap, managerName string) string
• func GetOperationSymbol(operation contract.Operation) string
• func GetPackageSymbol(pkg contract.PkgWrapper) string

Constants

const (
	AbandonedSymbol = "💀"
	NonSemverSymbol = "❗"
)

const (
	RootRequirementSymbol      = "🗄️"
	RootDevRequirementSymbol   = "🧰"
	TransitiveDependencySymbol = "🔗️"
)

const (
	SemverComponentUpgradeSymbol     = "🔺"
	SemverComponentDowngradeSymbol   = "🔻"
	SemverComponentSymbol            = "🔹"
	UnknownOperationSymbol           = "❓"
	SemverExtraUpdateOperationSymbol = SemverComponentSymbol +
		"." + SemverComponentSymbol +
		"." + SemverComponentSymbol +
		UnknownOperationSymbol
	RemovalOperationSymbol   = "❌"
	AdditionOperationSymbol  = "➕️"
	NonChangeOperationSymbol = "🟰"
	UnmanagedSymbol          = "❔"
)

Functions

func BuildVersionLabel

func BuildVersionLabel(version contract.PkgVersion) string

BuildVersionLabel formats a package version into a display label. If the version is not semantic, it appends a NonSemverSymbol (❗) indicator.

Parameters:

• version: The package version to format

Returns: A formatted string representation of the version, potentially with a symbol appended to indicate non-semantic versioning (e.g., git hashes, custom versions).

Example:

label := BuildVersionLabel(contract.PkgVersion{
	Label: "1.2.3",
	Semver: &contract.Semver{...},
})
fmt.Println(label) // Output: 1.2.3

func GenerateForChanges

func GenerateForChanges(changes contract.DiffMap, managerName string) string

GenerateForChanges produces a Markdown-formatted summary of package dependency changes. It takes a DiffMap containing package changes and organizes them into categorized sections with appropriate symbols and formatting. The managerName parameter (e.g., "Composer" or "Npm") is used in the header to identify the package manager context.

Parameters:

• changes: A contract.DiffMap from go-deps-diff containing all package changes to summarize
• managerName: The name of the package manager (e.g., "Composer", "Npm") for header formatting

Returns: A Markdown-formatted string with sections for additions, removals, updates, and unchanged packages. Changes are visually distinguished using Unicode symbols and organized in collapsible detail sections.

Example:

changes, err := difflib.Diff(oldPkgs, newPkgs)
if err != nil {
	log.Fatal(err)
}
markdown := GenerateForChanges(changes, "Composer")
fmt.Println(markdown)

func GetOperationSymbol

func GetOperationSymbol(operation contract.Operation) string

GetOperationSymbol returns a Unicode symbol representing a package change operation. The symbol communicates the type of change: additions (➕), removals (❌), upgrades (🔺), downgrades (🔻), patch updates (🔹), or no change (🟰). For semver updates, nested symbols indicate which component changed (major/minor/patch).

Parameters:

• operation: The package operation/change to determine the symbol for

Returns: A Unicode emoji string (possibly in HTML sub/sup tags) representing the operation type.

Example:

symbol := GetOperationSymbol(contract.Operation{
	Name: contract.UpgradeOperation,
	SemverType: contract.SemverMajorUpdate,
})
fmt.Println(symbol) // Output: <sub><sup>🔺.🔹.🔹</sup></sub>

func GetPackageSymbol

func GetPackageSymbol(pkg contract.PkgWrapper) string

GetPackageSymbol returns a Unicode symbol indicating the package type and relationship. The symbol communicates whether the package is a root requirement (🗄️), root dev requirement (🧰), or a transitive dependency (🔗️).

Parameters:

• pkg: The package to determine the symbol for

Returns: A Unicode emoji string representing the package type (🗄️, 🧰, or 🔗️).

Example:

symbol := GetPackageSymbol(pkg)
fmt.Println(symbol) // Output: 🗄️ (for root requirement)