Metadata-Version: 2.4
Name: diffora
Version: 0.1.0
Summary: Secret-aware semantic configuration diffs for JSON, YAML, TOML and .env files.
Author: HashPalace
License: MIT
Project-URL: Homepage, https://github.com/hashpalace/ConfigDiff
Project-URL: Repository, https://github.com/hashpalace/ConfigDiff
Project-URL: Issues, https://github.com/hashpalace/ConfigDiff/issues
Project-URL: Documentation, https://github.com/hashpalace/ConfigDiff#readme
Keywords: config,configuration,configuration-diff,config-drift,diff,diff-tool,semantic-diff,devops,infrastructure,json,yaml,toml,dotenv,secrets,debugging,ci,github-actions
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: orjson>=3.9
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: test
Requires-Dist: build>=1.2; extra == "test"
Requires-Dist: coverage>=7.6; extra == "test"
Requires-Dist: hypothesis>=6.100; extra == "test"
Requires-Dist: ruff>=0.9; extra == "test"
Requires-Dist: twine>=6; extra == "test"
Dynamic: license-file

# Diffora

[![Tests](https://github.com/hashpalace/ConfigDiff/actions/workflows/tests.yml/badge.svg)](https://github.com/hashpalace/ConfigDiff/actions/workflows/tests.yml)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/hashpalace/ConfigDiff?style=social)](https://github.com/hashpalace/ConfigDiff/stargazers)
[![GitHub issues](https://img.shields.io/github/issues/hashpalace/ConfigDiff)](https://github.com/hashpalace/ConfigDiff/issues)

**Stop guessing what changed between configs.** Diffora compares parsed configuration values and pinpoints added, removed, and changed fields—even across different formats. Pass two directories to compare their file inventories and the semantic contents of supported configuration files.

JSON · YAML · TOML · `.env` · cross-format · directory comparison · secret-aware · CI-friendly

## Why Diffora?

- **Custom redaction:** add `--redact PATH` rules for sensitive fields that don't use conventional secret-like names.

If this saves you time, [star the repository](https://github.com/hashpalace/ConfigDiff) and share it with another developer. Stars help other people discover useful open-source tools.

- **Useful paths, not noisy text diffs:** `services[0].port` or `services[id="api"].port`.
- **Added and removed objects are expanded:** see the individual leaf values instead of one giant object blob.
- **Match lists by identity:** reordering services won't create fake changes when you use `--list-key id`.
- **Ignore known differences:** repeat `--ignore` or use glob patterns.
- **Safer output by default:** values under sensitive-looking keys are masked.
- **Automation-ready:** JSON output and predictable exit codes.
- **Safe by default:** comparisons never modify input files; the separate `apply` command only writes when explicitly requested.

## Install

From a local clone:

```bash
python -m pip install .
```

Or install the latest code directly from GitHub:

```bash
python -m pip install "git+https://github.com/hashpalace/ConfigDiff.git"
```

Install from PyPI with `python -m pip install diffora`. Requires Python 3.9+. YAML parsing uses PyYAML. Python 3.9 and 3.10 use `tomli` for TOML; Python 3.11+ uses the standard library. The `configdiff` command remains available as a compatibility alias.

## Quick start

```bash
diffora old.json new.json
diffora config.yaml config.toml
diffora .env.production .env.staging
diffora ./config/staging ./config/production
```

Example output:

```diff
+ database.pool_size = 20
- legacy_endpoint = "https://old.example"
~ database.port: 5432 -> 5433
```

Try the included demo files from the repository root:

```bash
diffora examples/before.json examples/after.json --summary
```

Formats are detected from file extensions. For files with custom names, specify each format:

```bash
diffora before.conf after.conf --left-format json --right-format yaml
```

Supported format names: `json`, `yaml`, `toml`, `env`, and `dotenv`.

## Compare lists by a stable key

By default, lists are compared by index. If entries are objects with a stable identifier, match them by that field to avoid noisy diffs when entries are reordered. `--list-key` also accepts comma-separated nested fields, such as `apiVersion,kind,metadata.name` for Kubernetes resources. Alternatively, `--ignore-order` compares lists as multisets: order is ignored but duplicate counts still matter; unmatched changed objects are represented as removals and additions:

```bash
diffora old.json new.json --list-key id
diffora old.json new.json --ignore-order
```

For example, changes are reported as `services[id="api"].port` instead of depending on the item's array position. The option applies to lists of objects that contain a unique, non-null value for the chosen key. If either list doesn't meet that requirement, Diffora safely falls back to index comparison. For Kubernetes resource lists, use --list-key kubernetes: resources are matched by apiVersion, kind, metadata.namespace, and metadata.name; a missing namespace is treated as the empty namespace for cluster-scoped resources.

## Ignore paths

Pass `--ignore` multiple times to skip fields that are expected to differ:

```bash
diffora old.yaml new.yaml --ignore metadata.generated_at --ignore 'services[*].replicas'
```

Patterns support `*` (any sequence of characters) and `?` (one character). An exact path also ignores its descendants. For example, ignoring `database` ignores all of `database.host`, `database.port`, and nested paths below it.

## JSON output and exit codes

Use machine-readable output in scripts. JSON output is a versioned object with `schema_version` and `differences`:

```bash
diffora old.json new.json --format json
diffora old.json new.json --format json --summary
```

Each difference includes `path`, `kind`, `old`, `new`, `old_missing`, and `new_missing`. The missing flags distinguish an absent value from an explicit JSON `null`. `kind` is `added`, `removed`, or `changed`. The output contract is documented in [`schemas/differences.schema.json`](schemas/differences.schema.json); consumers should check `schema_version` before relying on the structure.

| Exit code | Meaning |
| --- | --- |
| `0` | No differences found |
| `1` | Differences found |
| `2` | File, input, or parsing error |

For a concise text summary:

```bash
diffora old.yaml new.yaml --summary
```

Disable terminal colors with `--no-color`. Colors are otherwise enabled only when writing to an interactive terminal. Set the `NO_COLOR` environment variable to disable colors without changing your command.

## Stdin, quiet mode, and output formats

Read one side from a pipe by using `-` and explicitly setting that side's format. A single stdin stream can supply only one side per invocation.

```bash
cat new.json | diffora old.json - --right-format json
git show HEAD:config.yaml | diffora - config.yaml --left-format yaml
```

For CI checks that only need a pass/fail result, `--quiet` suppresses standard output while preserving exit codes: `0` means identical, `1` means differences, and `2` means an input or parsing error.

```bash
diffora production.yaml staging.yaml --quiet
```

Choose `--format markdown` for a readable table in pull-request comments, `--format unified` for a unified diff of normalized paths and values, `--format github-actions` to emit escaped workflow warning annotations, or `--format json-patch` to generate an RFC 6902 patch:

```bash
diffora before.json after.json --format markdown
diffora before.json after.json --format unified
diffora before.json after.json --format github-actions
diffora before.json after.json --format json-patch --show-secrets > patch.json
diffora apply patch.json before.json
```

A unified output is a semantic diff of parsed paths and values, not a byte-for-byte diff of the source files.

## `.env` parsing notes

Diffora handles common dotenv lines: `KEY=value`, optional `export KEY=value`, surrounding whitespace, blank values, quoted values, and comments. For quoted values, text after the closing quote must be whitespace or a comment. Values are compared literally: Diffora does not expand variables, execute shell syntax, or interpret escape sequences. Duplicate keys use the last value. This is a practical parser for comparison, not a full shell or dotenv runtime.

## Secret handling

Built-in key-name masking is best-effort. Add project-specific paths or glob patterns with repeatable `--redact`; for example:

```bash
diffora before.yaml after.yaml --redact database.url --redact 'services[*].endpoint'
```

Exact custom paths also mask their descendants. Glob patterns use `*` and `?`. These rules are added to the built-in sensitive-key detection. `--show-secrets` disables both built-in and custom masking, so use it deliberately.



Values whose path names look sensitive (such as `password`, `token`, `secret`, `api_key`, or `private_key`) are masked by default in both text and JSON output.

```bash
diffora old.env new.env
diffora old.env new.env --show-secrets
```

Only use `--show-secrets` when you are certain the output won't be exposed. Redaction is a best-effort key-name safeguard, not a complete secret scanner.

## Input safety limits

Diffora reads at most 16 MiB from each input, including standard input. YAML aliases that create cyclic references are rejected; YAML structures are limited to 500,000 nodes and 256 levels of nesting. Direct calls to the Python `compare_values` API receive the same cycle, node-count, and nesting checks. These safeguards help avoid runaway recursion and excessive resource use when comparing untrusted configuration files. Parser diagnostics report the format and location when available without echoing source values.

## Custom redaction

Add project-specific paths or glob patterns when a sensitive field does not have an obvious secret-like name:

```bash
diffora before.yaml after.yaml --redact database.url --redact 'services[*].endpoint'
```

Exact custom paths also mask descendants. Glob patterns support `*` and `?`. These rules are added to built-in sensitive-key detection and apply to text, JSON, Markdown, and unified output. `--show-secrets` disables both built-in and custom masking; use it deliberately.

## CLI reference

```text
diffora LEFT RIGHT [options]

Options:
  --left-format FORMAT   Format of the original file
  --right-format FORMAT  Format of the comparison file
  --format FORMAT        Output: text, json, markdown, unified, github-actions, or json-patch
  --show-secrets         Display values under sensitive-looking keys
  --redact PATH          Redact an additional path or glob pattern; repeatable
  --no-color             Disable ANSI colors
  --list-key KEY         Match lists by stable key; use kubernetes for Kubernetes manifests
  --ignore-order         Ignore list order while preserving duplicate counts
  --ignore PATH          Ignore a path or glob pattern; repeatable
  --summary              Print counts of added, removed, and changed values
  -h, --help             Show help
```

JSON Patch output may contain secret values needed to reproduce the target exactly, so `--format json-patch` requires the explicit `--show-secrets` opt-in. Review the patch before sharing it. `diffora apply PATCH.json TARGET.json` applies add/remove/replace operations to a JSON target file; the target is only rewritten after the patch validates and applies successfully. Small lists use bounded LCS matching to generate minimal add/remove operations; very large list comparisons fall back to replacing the array to keep patch generation predictable.

## Shell and CI examples

Fail a shell script when configuration values differ:

```bash
set -eu
diffora config.example.yaml config.production.yaml --quiet
```

GitHub Actions step that fails only when differences exist (parse errors also fail):

```yaml
- name: Check configuration drift
  run: diffora config/staging.yaml config/production.yaml --quiet
```

If you want to show the differences in a CI log, omit `--quiet`; use `--format json` when a later step consumes the structured output.

## Development

```bash
git clone https://github.com/hashpalace/ConfigDiff.git
cd ConfigDiff
python -m pip install -e .
python -m unittest discover -s tests -v
```

GitHub Actions tests Python 3.9–3.13.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.

## Real-world examples

The `examples/` directory includes a small service configuration comparison. Run `diffora examples/services-before.yaml examples/services-after.yaml --list-key id --summary` to see it. The `benchmarks/` directory contains paired 100-service JSON fixtures for repeatable performance checks; run `diffora benchmarks/before.json benchmarks/after.json --list-key id --summary`. To measure Diffora's core latency and enforce the 5 ms median budget, use `python -m benchmarks.bench_compare --runs 50 --budget-ms 5`. To compare the same synthetic changes against DeepDiff, jd, and diffyml, install those tools and run `python -m benchmarks.bench_competitors --runs 30 --require-all`. The cross-tool report separates in-process library timings from end-to-end CLI timings (including process startup and parsing); diffyml receives an equivalent YAML serialization of the same dataset. All values are synthetic and illustrative, not production configuration.

## Roadmap

Milestones and contribution ideas live in [ROADMAP.md](ROADMAP.md).

## Contributing

Bug reports, ideas, and pull requests are welcome. Please include a focused test for behavior changes and read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a PR.

## License

MIT — see [LICENSE](LICENSE).
