Metadata-Version: 2.4
Name: spdx-diff
Version: 1.1.0
Summary: SPDX3 SBOM comparison tool for packages, kernel config, and PACKAGECONFIG
Project-URL: Repository, https://github.com/bootlin/spdx-diff
Project-URL: Documentation, https://github.com/bootlin/spdx-diff/blob/main/README.md
Project-URL: Bug Tracker, https://github.com/bootlin/spdx-diff/issues
Project-URL: Changelog, https://github.com/bootlin/spdx-diff/blob/main/CHANGELOG.md
Author-email: Kamel BOUHARA <kamel.bouhara@bootlin.com>
License: GPL-2.0
License-File: LICENSE
Keywords: embedded,kernel,linux,packageconfig,sbom,spdx,yocto
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Requires-Dist: backports-zstd; python_version < '3.14'
Description-Content-Type: text/markdown

SPDX3 Diff Tool
===============

Overview
--------
This tool compares two SPDX3 JSON documents and reports differences in:
- Software packages (name + version)
- Kernel configuration parameters (CONFIG_*)
- PACKAGECONFIG entries per package

The application separates human-readable and machine-readable outputs to improve automation and pipeline integration.

- By default, the tool emits structured **JSON output**, making it suitable for consumption by scripts and CI/CD pipelines.
- The default output format can be changed into a human-readable (text) using --human-readable optional argument.
- When a JSON filename parameter is provided, the JSON result is also written to the specified file.

Usage
-----
```bash
./spdx-diff reference.json new.json [OPTIONS]
```

Required arguments:
  - `reference`: Path to the baseline SPDX3 JSON file.
  - `new`: Path to the newer SPDX3 JSON file.

Optional arguments:
  - `--json-output <file>`: Save diff results to the given JSON file.
  - `--human-readable`: Output results in a human-readable text format.

Text output filtering - category :
  - `--[no-]packages`: show|hide package differences.
  - `--[no-]kernel-config`: show|hide kernel config differences.
  - `--[no-]packageconfig`: show|hide PACKAGECONFIG differences.
  - `--[no-]packages-proprietary`: show|hide packages with LicenseRef-Proprietary.

Output
------
The script prints differences grouped into three sections:

1. Packages
   - Added packages
   - Removed packages
   - Changed versions

2. Kernel Config (CONFIG_*)
   - Added options
   - Removed options
   - Modified options

3. PACKAGECONFIG (per package)
   - Packages with added PACKAGECONFIG entries
   - Packages with removed PACKAGECONFIG entries
   - Packages with changed feature configurations
   - Shows package name and associated features

Symbols:
  + added
  - removed
  ~ changed

```

JSON Diff File
--------------
The output file (default: spdx_diff_<timestamp>.json) contains a structured diff:

```json
{
  "package_diff": {
    "added": { "pkgA": "1.2.3" },
    "removed": { "pkgB": "4.5.6" },
    "changed": { "pkgC": { "from": "1.0", "to": "2.0" } }
  },
  "kernel_config_diff": {
    "added": { "CONFIG_XYZ": "y" },
    "removed": { "CONFIG_ABC": "n" },
    "changed": { "CONFIG_DEF": { "from": "m", "to": "y" } }
  },
  "packageconfig_diff": {
    "added": {
      "xz": { "doc": "enabled" }
    },
    "removed": {
      "old-package": { "feature1": "disabled" }
    },
    "changed": {
      "zstd-native": {
        "added": { "zlib": "enabled" },
        "removed": { "lz4": "disabled" },
        "changed": {
          "doc": { "from": "disabled", "to": "enabled" }
        }
      }
    }
  }
}
```

PACKAGECONFIG Structure
-----------------------
PACKAGECONFIG entries are tracked per package, showing which features are
enabled/disabled for each specific package:

Console output example:
```
PACKAGECONFIG - Changed Packages:
 ~ xz:
     + doc: enabled
 ~ zstd-native:
     ~ lz4: disabled -> enabled
     - lzma: disabled
```

This shows:
- xz package: doc feature was added and enabled
- zstd-native package: lz4 changed from disabled to enabled, lzma was removed

Logging
-------
The script uses Python's logging module:
```
  INFO     Normal operations (file opened, counts, etc.)
  WARNING  Missing sections (no build_Build objects found)
  ERROR    Invalid input or format issues
```

Examples
--------

### Basic comparison with default JSON output on stdout:
    ./spdx-diff reference.json new.json

### Full details with proprietary packages excluded:
    ./spdx-diff reference.json new.json --no-packages-proprietary

### Console output for CI/CD:
    ./spdx-diff reference.json new.json

### Console output human-readable:
    ./spdx-diff reference.json new.json --human-readable

### Console and JSON output with JSON file generated:
    ./spdx-diff reference.json new.json --json-output result.json

### Exclude on console PACKAGECONFIG differences:
    ./spdx-diff reference.json new.json --no-packageconfig

Human readable console output example:
```
Packages - Added:
 + libfoo: 2.0

Packages - Changed:
 ~ zlib: 1.2.11 -> 1.2.13

Kernel Config - Removed:
 - CONFIG_OLD_FEATURE

PACKAGECONFIG - Added Packages:
 + newpkg:
     gtk: enabled
     doc: disabled

PACKAGECONFIG - Changed Packages:
 ~ xz:
     + lzma: enabled
```
