diffora 0.1.0__py3-none-any.whl

configdiff/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.1.0"
+
+from .core import ConfigDiffError, Difference, compare_files, compare_values, load_config
+
+__all__ = ["ConfigDiffError", "Difference", "compare_files", "compare_values", "load_config", "__version__"]

configdiff/cli.py

@@ -0,0 +1,225 @@
+import argparse
+import difflib
+import json
+import os
+import sys
+from pathlib import Path
+from collections import Counter
+from typing import List, Optional
+
+from .core import ConfigDiffError, Difference, _MISSING, compare_directories, compare_files, load_config, safe_value, serialize_differences
+from .patch import apply_json_patch, build_json_patch
+
+_RED = "\033[31m"
+_GREEN = "\033[32m"
+_YELLOW = "\033[33m"
+_RESET = "\033[0m"
+_SCHEMA_VERSION = "1.0"
+
+
+def _display(value, path, show_secrets, redaction_patterns=None):
+    if value is _MISSING:
+        return "<missing>"
+    safe = safe_value(value, path, show_secrets, redaction_patterns)
+    return json.dumps(safe, ensure_ascii=False, sort_keys=True, default=str)
+
+
+def _type_name(value):
+    if value is None:
+        return "null"
+    if value is _MISSING:
+        return "missing"
+    if isinstance(value, bool):
+        return "bool"
+    if isinstance(value, dict):
+        return "object"
+    if isinstance(value, list):
+        return "array"
+    return type(value).__name__
+
+
+def _counts(differences):
+    counts = Counter(diff.kind for diff in differences)
+    return {"added": counts["added"], "removed": counts["removed"], "changed": counts["changed"]}
+
+
+def _render(differences: List[Difference], color: bool, show_secrets: bool, summary: bool = False, redaction_patterns=None) -> str:
+    lines = []
+    for diff in differences:
+        path = diff.path
+        if diff.kind == "added":
+            line = f"+ {path} = {_display(diff.new, path, show_secrets, redaction_patterns)}"
+            tone = _GREEN
+        elif diff.kind == "removed":
+            line = f"- {path} = {_display(diff.old, path, show_secrets, redaction_patterns)}"
+            tone = _RED
+        else:
+            old = _display(diff.old, path, show_secrets, redaction_patterns)
+            new = _display(diff.new, path, show_secrets, redaction_patterns)
+            if type(diff.old) is not type(diff.new):
+                old = f"{old} ({_type_name(diff.old)})"
+                new = f"{new} ({_type_name(diff.new)})"
+            line = f"~ {path}: {old} -> {new}"
+            tone = _YELLOW
+        lines.append(f"{tone}{line}{_RESET}" if color else line)
+    if summary:
+        counts = _counts(differences)
+        lines.append(f"Summary: {counts['added']} added, {counts['removed']} removed, {counts['changed']} changed")
+    return "\n".join(lines)
+
+
+def _markdown_cell(value: str) -> str:
+    return value.replace("|", "\\|").replace("\n", "<br>").replace("`", "\\`")
+
+
+def _render_markdown(differences: List[Difference], show_secrets: bool, summary: bool = False, redaction_patterns=None) -> str:
+    if not differences:
+        return "No differences found."
+    lines = ["| Path | Change | Old value | New value |", "| --- | --- | --- | --- |"]
+    for diff in differences:
+        old = "" if diff.old is _MISSING else _display(diff.old, diff.path, show_secrets, redaction_patterns)
+        new = "" if diff.new is _MISSING else _display(diff.new, diff.path, show_secrets, redaction_patterns)
+        lines.append("| " + " | ".join(_markdown_cell(value) for value in (diff.path, diff.kind, old, new)) + " |")
+    if summary:
+        counts = _counts(differences)
+        lines.extend(["", f"**Summary:** {counts['added']} added, {counts['removed']} removed, {counts['changed']} changed"])
+    return "\n".join(lines)
+
+
+def _render_unified(differences: List[Difference], show_secrets: bool, left: str, right: str, redaction_patterns=None) -> str:
+    old_lines = []
+    new_lines = []
+    for diff in differences:
+        if diff.kind != "added":
+            old_lines.append(f"{diff.path} = {_display(diff.old, diff.path, show_secrets, redaction_patterns)}")
+        if diff.kind != "removed":
+            new_lines.append(f"{diff.path} = {_display(diff.new, diff.path, show_secrets, redaction_patterns)}")
+    return "\n".join(difflib.unified_diff(
+        old_lines,
+        new_lines,
+        fromfile=left,
+        tofile=right,
+        lineterm="",
+    ))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="diffora", description="Compare JSON, YAML, TOML and .env configuration files.")
+    parser.add_argument("left", help="Original configuration file, or - to read stdin")
+    parser.add_argument("right", help="Configuration file to compare against, or - to read stdin")
+    parser.add_argument("--left-format", choices=["json", "yaml", "toml", "env", "dotenv"])
+    parser.add_argument("--right-format", choices=["json", "yaml", "toml", "env", "dotenv"])
+    parser.add_argument("--format", choices=["text", "json", "markdown", "unified", "github-actions", "json-patch"], default="text", help="Output format")
+    parser.add_argument("--show-secrets", action="store_true", help="Display values whose keys look sensitive")
+    parser.add_argument("--redact", action="append", default=[], metavar="PATH", help="Redact an additional path or glob pattern; may be repeated")
+    parser.add_argument("--no-color", action="store_true", help="Disable ANSI colors")
+    parser.add_argument("--quiet", "-q", action="store_true", help="Suppress stdout; preserve exit codes for CI")
+    parser.add_argument("--list-key", help="Match lists by a stable key; use kubernetes for apiVersion/kind/namespace/name matching")
+    parser.add_argument("--ignore-order", action="store_true", help="Treat lists as unordered multisets when no --list-key is set")
+    parser.add_argument("--ignore", action="append", default=[], metavar="PATH", help="Ignore a path or glob pattern; may be repeated")
+    parser.add_argument("--summary", action="store_true", help="Print counts of added, removed, and changed values")
+    return parser
+
+
+def _apply_command(argv: List[str]) -> int:
+    if len(argv) != 3:
+        print("usage: diffora apply PATCH.json TARGET.json", file=sys.stderr)
+        return 2
+    _, patch_path, target_path = argv
+    if Path(patch_path).resolve() == Path(target_path).resolve():
+        print("diffora: patch and target must be different files", file=sys.stderr)
+        return 2
+    try:
+        patch = load_config(patch_path, "json")
+        target = load_config(target_path, "json")
+        updated = apply_json_patch(target, patch)
+        Path(target_path).write_text(json.dumps(updated, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    except (ConfigDiffError, OSError, TypeError, ValueError) as exc:
+        print(f"diffora: {exc}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] == "apply":
+        return _apply_command(argv)
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.left == "-" and args.right == "-":
+        parser.error("only one input can read from stdin at a time; use a file for the other input")
+    if args.left == "-" and not args.left_format:
+        parser.error("--left-format is required when left input is stdin (-)")
+    if args.right == "-" and not args.right_format:
+        parser.error("--right-format is required when right input is stdin (-)")
+    try:
+        left_is_dir, right_is_dir = os.path.isdir(args.left), os.path.isdir(args.right)
+        if left_is_dir or right_is_dir:
+            if not (left_is_dir and right_is_dir):
+                raise ConfigDiffError("Both inputs must be directories when comparing directories")
+            if args.left_format or args.right_format:
+                raise ConfigDiffError("Explicit file formats cannot be used for directory comparison")
+            differences = compare_directories(args.left, args.right, args.list_key, args.ignore, args.ignore_order)
+        else:
+            differences = compare_files(args.left, args.right, args.left_format, args.right_format, args.list_key, args.ignore, args.ignore_order)
+    except ConfigDiffError as exc:
+        print(f"diffora: {exc}", file=sys.stderr)
+        return 2
+    if args.quiet:
+        return 1 if differences else 0
+    if args.format == "json-patch":
+        if left_is_dir or right_is_dir:
+            print("diffora: --format json-patch supports files, not directory comparisons", file=sys.stderr)
+            return 2
+        if args.ignore or args.redact:
+            print("diffora: --format json-patch cannot be combined with --ignore or --redact because patches must reproduce the complete target", file=sys.stderr)
+            return 2
+        if not args.show_secrets:
+            print("diffora: --format json-patch requires --show-secrets because a usable patch may contain secret values", file=sys.stderr)
+            return 2
+        try:
+            old = load_config(args.left, args.left_format)
+            new = load_config(args.right, args.right_format)
+        except ConfigDiffError as exc:
+            print(f"diffora: {exc}", file=sys.stderr)
+            return 2
+        print(json.dumps(build_json_patch(old, new), ensure_ascii=False, indent=2, default=str))
+    elif args.format == "json":
+        result = {
+            "schema_version": _SCHEMA_VERSION,
+            "differences": serialize_differences(differences, args.show_secrets, args.redact),
+        }
+        if args.summary:
+            result["summary"] = _counts(differences)
+        print(json.dumps(result, ensure_ascii=False, indent=2, default=str))
+    elif args.format == "markdown":
+        print(_render_markdown(differences, args.show_secrets, args.summary, args.redact))
+    elif args.format == "unified":
+        rendered = _render_unified(differences, args.show_secrets, args.left, args.right, args.redact)
+        if rendered:
+            print(rendered)
+    elif args.format == "github-actions":
+        for diff in differences:
+            old = "" if diff.kind == "added" else _display(diff.old, diff.path, args.show_secrets, args.redact)
+            new = "" if diff.kind == "removed" else _display(diff.new, diff.path, args.show_secrets, args.redact)
+            message = f"{diff.kind}: {diff.path}"
+            if diff.kind == "changed":
+                message += f" ({old} -> {new})"
+            elif diff.kind == "added":
+                message += f" ({new})"
+            else:
+                message += f" ({old})"
+            message = message.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+            print(f"::warning title=Diffora configuration difference::{message}")
+    elif not differences:
+        print("No differences found.")
+        if args.summary:
+            print("Summary: 0 added, 0 removed, 0 changed")
+    else:
+        color = sys.stdout.isatty() and not args.no_color and not os.environ.get("NO_COLOR")
+        print(_render(differences, color, args.show_secrets, args.summary, args.redact))
+    return 1 if differences else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

configdiff/core.py

@@ -0,0 +1,598 @@
+import json
+import os
+import re
+from functools import lru_cache
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+try:
+    import tomllib
+except ModuleNotFoundError:
+    import tomli as tomllib
+
+import yaml
+
+try:
+    import orjson
+except ImportError:
+    orjson = None
+
+
+class ConfigDiffError(ValueError):
+    pass
+
+
+class _MissingValue:
+    pass
+
+
+_MISSING = _MissingValue()
+
+
+@dataclass(frozen=True)
+class Difference:
+    path: str
+    kind: str
+    old: Any = _MISSING
+    new: Any = _MISSING
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+_FORMATS = {
+    ".json": "json",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+    ".toml": "toml",
+    ".env": "env",
+}
+_SECRET_PATTERN = re.compile(r"password|passwd|secret|token|api[_-]?key|private[_-]?key|client[_-]?secret|credential|authorization|\bauth\b|cookie|session|connection[_-]?string|\bdsn\b|signing[_-]?key|encryption[_-]?key", re.I)
+_MAX_INPUT_BYTES = 16 * 1024 * 1024
+_MAX_STRUCTURE_NODES = 500_000
+_MAX_STRUCTURE_DEPTH = 256
+_IDENTIFIER_PATTERN = re.compile(r"[A-Za-z_][A-Za-z0-9_-]*")
+
+@lru_cache(maxsize=4096)
+def _is_identifier(value: str) -> bool:
+    return _IDENTIFIER_PATTERN.fullmatch(value) is not None
+
+
+def detect_format(path: os.PathLike) -> str:
+    name = Path(path).name.lower()
+    if name == ".env" or name.startswith(".env."):
+        return "env"
+    suffix = Path(name).suffix
+    try:
+        return _FORMATS[suffix]
+    except KeyError as exc:
+        raise ConfigDiffError("Cannot detect format from extension; use --left-format or --right-format") from exc
+
+
+def _parse_env(text: str) -> Dict[str, str]:
+    result: Dict[str, str] = {}
+    for number, raw_line in enumerate(text.splitlines(), 1):
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[7:].lstrip()
+        if "=" not in line:
+            raise ConfigDiffError(f"Invalid .env entry at line {number}, column {len(line) + 1}: expected KEY=VALUE")
+        key, value = line.split("=", 1)
+        key = key.strip()
+        if not key or not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", key):
+            raise ConfigDiffError(f"Invalid .env key at line {number}, column 1")
+        value = value.strip()
+        if value.startswith(("'", '"')):
+            quote = value[0]
+            closing = value.find(quote, 1)
+            if closing < 0:
+                raise ConfigDiffError(f"Unterminated quoted value at line {number}, column {len(key) + 2}")
+            trailing = value[closing + 1:].strip()
+            if trailing and not trailing.startswith("#"):
+                raise ConfigDiffError(f"Unexpected text after quoted value at line {number}, column {closing + 2}")
+            value = value[1:closing]
+        elif " #" in value:
+            value = value.split(" #", 1)[0].rstrip()
+        result[key] = value
+    return result
+
+
+def _read_input(file_path: Path, selected: str, is_stdin: bool) -> Any:
+    try:
+        if is_stdin:
+            stream = getattr(sys.stdin, "buffer", None)
+            data = stream.read(_MAX_INPUT_BYTES + 1) if stream is not None else sys.stdin.read(_MAX_INPUT_BYTES + 1)
+        else:
+            with file_path.open("rb") as stream:
+                data = stream.read(_MAX_INPUT_BYTES + 1)
+    except (OSError, ValueError) as exc:
+        raise ConfigDiffError(f"Cannot read {file_path}: {exc}") from exc
+    size = len(data) if isinstance(data, bytes) else len(data.encode("utf-8"))
+    if size > _MAX_INPUT_BYTES:
+        raise ConfigDiffError(f"Input exceeds the maximum size of {_MAX_INPUT_BYTES} bytes")
+    if selected == "json":
+        return data
+    if isinstance(data, str):
+        return data.lstrip("\ufeff")
+    try:
+        return data.decode("utf-8-sig")
+    except UnicodeDecodeError:
+        raise ConfigDiffError(f"Cannot decode {file_path} as UTF-8") from None
+
+
+def _validate_structure(value: Any) -> None:
+    """Validate a parsed tree with O(depth), rather than O(width), traversal memory."""
+    nodes = 1
+    if nodes > _MAX_STRUCTURE_NODES:
+        raise ConfigDiffError(f"Configuration exceeds the {_MAX_STRUCTURE_NODES} node limit")
+    if not isinstance(value, (dict, list)):
+        return
+
+    active = {id(value)}
+    children = value.values() if isinstance(value, dict) else value
+    stack = [(iter(children), id(value), 0)]
+    while stack:
+        iterator, container_id, parent_depth = stack[-1]
+        try:
+            current = next(iterator)
+        except StopIteration:
+            active.remove(container_id)
+            stack.pop()
+            continue
+
+        depth = parent_depth + 1
+        nodes += 1
+        if nodes > _MAX_STRUCTURE_NODES:
+            raise ConfigDiffError(f"Configuration exceeds the {_MAX_STRUCTURE_NODES} node limit")
+        if depth > _MAX_STRUCTURE_DEPTH:
+            raise ConfigDiffError(f"Configuration exceeds the maximum nesting depth of {_MAX_STRUCTURE_DEPTH}")
+        current_type = type(current)
+        if current_type is dict or current_type is list:
+            is_container = True
+        elif current_type in (str, int, float, bool, type(None)):
+            is_container = False
+        else:
+            # Preserve support for container subclasses without paying for
+            # isinstance() on the common scalar types in parsed config trees.
+            is_container = isinstance(current, (dict, list))
+        if is_container:
+            identity = id(current)
+            if identity in active:
+                raise ConfigDiffError("Cyclic configuration references are not supported")
+            active.add(identity)
+            children = current.values() if isinstance(current, dict) else current
+            stack.append((iter(children), identity, depth))
+
+
+def _reject_json_constant(value: str) -> None:
+    raise ValueError(f"Non-standard JSON constant: {value}")
+
+
+def load_config(path: os.PathLike, fmt: Optional[str] = None) -> Any:
+    file_path = Path(path)
+    is_stdin = str(path) == "-"
+    if is_stdin and fmt is None:
+        raise ConfigDiffError("Input from stdin requires an explicit --left-format or --right-format")
+    selected = (fmt or detect_format(file_path)).lower()
+    if selected == "dotenv":
+        selected = "env"
+    if selected not in {"json", "yaml", "toml", "env"}:
+        raise ConfigDiffError(f"Unsupported format: {selected}")
+    text = _read_input(file_path, selected, is_stdin)
+    try:
+        if selected == "json":
+            if orjson is not None:
+                try:
+                    value = orjson.loads(text)
+                except orjson.JSONDecodeError:
+                    value = json.loads(text, parse_constant=_reject_json_constant)
+            else:
+                value = json.loads(text, parse_constant=_reject_json_constant)
+        elif selected == "yaml":
+            value = yaml.safe_load(text)
+            if value is None:
+                value = {}
+        elif selected == "toml":
+            value = tomllib.loads(text)
+        else:
+            value = _parse_env(text)
+        if selected == "yaml":
+            _validate_structure(value)
+        return value
+    except ConfigDiffError:
+        raise
+    except RecursionError:
+        raise ConfigDiffError("Configuration exceeds the supported parser nesting depth") from None
+    except Exception as exc:
+        location = ""
+        line = getattr(exc, "lineno", None)
+        column = getattr(exc, "colno", None)
+        problem_mark = getattr(exc, "problem_mark", None)
+        if problem_mark is not None:
+            line = problem_mark.line + 1
+            column = problem_mark.column + 1
+        if line is None or column is None:
+            match = re.search(r"at line (\d+), column (\d+)", str(exc))
+            if match:
+                line = line or int(match.group(1))
+                column = column or int(match.group(2))
+        if line is not None and column is not None:
+            location = f" at line {line}, column {column}"
+        elif line is not None:
+            location = f" at line {line}"
+        raise ConfigDiffError(f"Cannot parse {file_path} as {selected.upper()}{location}: invalid syntax") from None
+
+def _child_path(path: str, key: Any, is_index: bool = False) -> str:
+    if is_index:
+        return f"{path}[{key}]"
+    if isinstance(key, str) and _is_identifier(key):
+        return f"{path}.{key}" if path else key
+    encoded = json.dumps(str(key), ensure_ascii=False)
+    return f"{path}[{encoded}]" if path else f"[{encoded}]"
+
+
+@lru_cache(maxsize=4096)
+def _glob_match(path: str, pattern: str) -> bool:
+    path_index = 0
+    pattern_index = 0
+    star_index = -1
+    retry_index = 0
+    while path_index < len(path):
+        if pattern_index < len(pattern) and (pattern[pattern_index] == "?" or pattern[pattern_index] == path[path_index]):
+            path_index += 1
+            pattern_index += 1
+        elif pattern_index < len(pattern) and pattern[pattern_index] == "*":
+            star_index = pattern_index
+            pattern_index += 1
+            retry_index = path_index
+        elif star_index >= 0:
+            pattern_index = star_index + 1
+            retry_index += 1
+            path_index = retry_index
+        else:
+            return False
+    while pattern_index < len(pattern) and pattern[pattern_index] == "*":
+        pattern_index += 1
+    return pattern_index == len(pattern)
+
+
+@lru_cache(maxsize=4096)
+def _is_ignored_cached(path: str, patterns: tuple) -> bool:
+    for pattern in patterns:
+        if _glob_match(path, pattern):
+            return True
+        if not any(char in pattern for char in "*?"):
+            if path.startswith(pattern + ".") or path.startswith(pattern + "["):
+                return True
+    return False
+
+
+def _is_ignored(path: str, patterns) -> bool:
+    if not patterns:
+        return False
+    normalized = patterns if isinstance(patterns, tuple) else tuple(patterns)
+    return _is_ignored_cached(path, normalized)
+
+
+def _append_tree(value: Any, path: str, kind: str, differences: List[Difference], ignore_paths: List[str]) -> None:
+    if _is_ignored(path, ignore_paths):
+        return
+    if isinstance(value, dict) and value:
+        for key in sorted(value, key=lambda item: str(item)):
+            _append_tree(value[key], _child_path(path, key), kind, differences, ignore_paths)
+        return
+    if isinstance(value, list) and value:
+        for index, item in enumerate(value):
+            _append_tree(item, _child_path(path, index, True), kind, differences, ignore_paths)
+        return
+    differences.append(Difference(path or "$", kind, _MISSING if kind == "added" else value, value if kind == "added" else _MISSING))
+
+
+def _keyed_list_index(items: List[Any], key: str) -> Optional[Dict[Any, Any]]:
+    """Index by a stable identity; reject missing or duplicate identities.
+
+    The built-in kubernetes key handles cluster-scoped resources by treating
+    an absent metadata.namespace as the empty namespace.
+    """
+    kubernetes = key.strip().lower() == "kubernetes"
+    fields = ("apiVersion", "kind", "metadata.namespace", "metadata.name") if kubernetes else tuple(part.strip() for part in key.split(","))
+    if not fields or any(not field for field in fields):
+        return None
+    # Parse dotted selectors once, rather than allocating segment lists for
+    # every field of every item in a large resource list.
+    field_segments = tuple((field, tuple(field.split("."))) for field in fields)
+    indexed = {}
+    try:
+        for item in items:
+            if not isinstance(item, dict):
+                return None
+            identity_parts = []
+            for field, segments in field_segments:
+                value = item
+                for segment in segments:
+                    if not isinstance(value, dict):
+                        return None
+                    if segment not in value:
+                        if kubernetes and field == "metadata.namespace":
+                            value = ""
+                            break
+                        return None
+                    value = value[segment]
+                if value is None or isinstance(value, (dict, list)):
+                    return None
+                identity_parts.append(value)
+            identity = tuple(identity_parts) if kubernetes or len(identity_parts) > 1 else identity_parts[0]
+            if identity in indexed:
+                return None
+            indexed[identity] = item
+    except TypeError:
+        return None
+    return indexed if len(indexed) == len(items) else None
+
+
+def _keyed_path(path: str, key: str, identity: Any) -> str:
+    if key.strip().lower() == "kubernetes":
+        fields = "apiVersion,kind,metadata.namespace,metadata.name"
+    else:
+        fields = ",".join(part.strip() for part in key.split(","))
+    if isinstance(identity, str) and "\\\\" not in identity and '"' not in identity and identity.isprintable():
+        encoded = f'"{identity}"'
+    else:
+        encoded = json.dumps(identity, ensure_ascii=False, sort_keys=True)
+    selector = f"{fields}={encoded}"
+    return f"{path}[{selector}]" if path else f"[{selector}]"
+
+def _append_keyed_item(value: Any, path: str, kind: str, key: str, differences: List[Difference], ignore_paths: List[str]) -> None:
+    if isinstance(value, dict):
+        has_remaining = any(name != key for name in value)
+        if has_remaining:
+            for name in sorted(value, key=lambda item: str(item)):
+                if name != key:
+                    _append_tree(value[name], _child_path(path, name), kind, differences, ignore_paths)
+            return
+        _append_tree({}, path, kind, differences, ignore_paths)
+        return
+    _append_tree(value, path, kind, differences, ignore_paths)
+
+
+def _unordered_fingerprint(value: Any) -> int:
+    """Build a compact, order-aware fingerprint without retaining a duplicate tree.
+
+    Fingerprints only select candidate buckets: callers still verify exact equality,
+    so hash collisions cannot turn unequal values into matches.
+    """
+    if isinstance(value, dict):
+        combined = 0
+        for key, item in value.items():
+            combined ^= hash((_unordered_fingerprint(key), _unordered_fingerprint(item)))
+        return hash((dict, len(value), combined))
+    if isinstance(value, list):
+        result = hash((list, len(value)))
+        for item in value:
+            result = hash((result, _unordered_fingerprint(item)))
+        return result
+    if isinstance(value, float) and value != value:
+        return hash((float, "nan"))
+    try:
+        return hash((type(value), value))
+    except TypeError:
+        return hash((type(value), repr(value)))
+
+
+def _values_equal(old: Any, new: Any) -> bool:
+    """Compare JSON-like trees while preserving strict scalar types."""
+    if old is new:
+        return True
+    if type(old) is not type(new):
+        return False
+    if isinstance(old, dict):
+        if old.keys() != new.keys():
+            return False
+        for key in old:
+            if not _values_equal(old[key], new[key]):
+                return False
+        return True
+    if isinstance(old, list):
+        if len(old) != len(new):
+            return False
+        for index, left in enumerate(old):
+            if not _values_equal(left, new[index]):
+                return False
+        return True
+    return old == new
+
+def _nested_types_equal(old: Any, new: Any) -> bool:
+    """Backward-compatible alias for strict recursive equality."""
+    return _values_equal(old, new)
+
+
+def _compare_values(old: Any, new: Any, path: str, list_key: Optional[str], ignored: tuple, differences: List[Difference], ignore_order: bool = False) -> None:
+    if ignored and _is_ignored_cached(path, ignored):
+        return
+    if old is new:
+        return
+    if isinstance(old, dict) and isinstance(new, dict):
+        keys = list(old) if old.keys() == new.keys() else list(old.keys() | new.keys())
+        try:
+            keys.sort()
+        except TypeError:
+            keys.sort(key=str)
+        for key in keys:
+            if key in old and key in new:
+                left, right = old[key], new[key]
+                if not (list_key and isinstance(left, list) and isinstance(right, list)) and _values_equal(left, right):
+                    continue
+            child = _child_path(path, key)
+            if key not in old:
+                _append_tree(new[key], child, "added", differences, ignored)
+            elif key not in new:
+                _append_tree(old[key], child, "removed", differences, ignored)
+            else:
+                _compare_values(old[key], new[key], child, list_key, ignored, differences, ignore_order)
+        return
+    if isinstance(old, list) and isinstance(new, list):
+        if (not list_key and _values_equal(old, new)) or old is new:
+            return
+        if ignore_order and not list_key:
+            new_buckets = {}
+            for index, item in enumerate(new):
+                new_buckets.setdefault(_unordered_fingerprint(item), []).append(index)
+            unmatched_old = []
+            for old_index, old_item in enumerate(old):
+                candidates = new_buckets.get(_unordered_fingerprint(old_item), [])
+                match_position = next((position for position, index in enumerate(candidates) if _values_equal(old_item, new[index])), None)
+                if match_position is None:
+                    unmatched_old.append((old_index, old_item))
+                else:
+                    candidates.pop(match_position)
+            unmatched_new = sorted(index for indexes in new_buckets.values() for index in indexes)
+            for index, item in unmatched_old:
+                _append_tree(item, _child_path(path, index, True), "removed", differences, ignored)
+            for index in unmatched_new:
+                _append_tree(new[index], _child_path(path, index, True), "added", differences, ignored)
+            return
+        old_index = _keyed_list_index(old, list_key) if list_key else None
+        new_index = _keyed_list_index(new, list_key) if list_key else None
+        if old_index is not None and new_index is not None:
+            identities = list(old_index)
+            identities.extend(identity for identity in new_index if identity not in old_index)
+            try:
+                identities.sort()
+            except TypeError:
+                identities.sort(key=str)
+            for identity in identities:
+                if identity not in old_index:
+                    child = _keyed_path(path, list_key, identity)
+                    _append_keyed_item(new_index[identity], child, "added", list_key, differences, ignored)
+                elif identity not in new_index:
+                    child = _keyed_path(path, list_key, identity)
+                    _append_keyed_item(old_index[identity], child, "removed", list_key, differences, ignored)
+                elif not _values_equal(old_index[identity], new_index[identity]):
+                    child = _keyed_path(path, list_key, identity)
+                    _compare_values(old_index[identity], new_index[identity], child, list_key, ignored, differences, ignore_order)
+            return
+        for index in range(max(len(old), len(new))):
+            child = _child_path(path, index, True)
+            if index >= len(old):
+                _append_tree(new[index], child, "added", differences, ignored)
+            elif index >= len(new):
+                _append_tree(old[index], child, "removed", differences, ignored)
+            elif not _values_equal(old[index], new[index]):
+                _compare_values(old[index], new[index], child, list_key, ignored, differences, ignore_order)
+        return
+    if type(old) is not type(new) or old != new:
+        differences.append(Difference(path or "$", "changed", old, new))
+
+
+def _compare_validated_values(old: Any, new: Any, path: str, list_key: Optional[str], ignore_paths: Optional[List[str]], ignore_order: bool = False) -> List[Difference]:
+    differences: List[Difference] = []
+    try:
+        _compare_values(old, new, path, list_key, tuple(ignore_paths or ()), differences, ignore_order)
+    except RecursionError:
+        raise ConfigDiffError("Comparison exceeds the supported nesting depth") from None
+    return differences
+
+
+def compare_values(old: Any, new: Any, path: str = "", list_key: Optional[str] = None, ignore_paths: Optional[List[str]] = None, ignore_order: bool = False) -> List[Difference]:
+    _validate_structure(old)
+    _validate_structure(new)
+    return _compare_validated_values(old, new, path, list_key, ignore_paths, ignore_order)
+
+
+def compare_files(left: os.PathLike, right: os.PathLike, left_format: Optional[str] = None, right_format: Optional[str] = None, list_key: Optional[str] = None, ignore_paths: Optional[List[str]] = None, ignore_order: bool = False) -> List[Difference]:
+    old = load_config(left, left_format)
+    new = load_config(right, right_format)
+    return _compare_validated_values(old, new, "", list_key, ignore_paths, ignore_order)
+
+
+def compare_directories(left: os.PathLike, right: os.PathLike, list_key: Optional[str] = None, ignore_paths: Optional[List[str]] = None, ignore_order: bool = False) -> List[Difference]:
+    left_root, right_root = Path(left), Path(right)
+    if not left_root.is_dir() or not right_root.is_dir():
+        raise ConfigDiffError("Directory comparison requires two existing directories")
+
+    def inventory(root: Path) -> Dict[str, Path]:
+        files = {}
+        for candidate in root.rglob("*"):
+            if candidate.is_symlink() or not candidate.is_file():
+                continue
+            files[candidate.relative_to(root).as_posix()] = candidate
+        return files
+
+    left_files, right_files = inventory(left_root), inventory(right_root)
+    differences: List[Difference] = []
+    for relative in sorted(left_files.keys() | right_files.keys()):
+        if relative not in left_files:
+            differences.append(Difference(relative, "added", _MISSING, "<file>"))
+            continue
+        if relative not in right_files:
+            differences.append(Difference(relative, "removed", "<file>", _MISSING))
+            continue
+        left_file, right_file = left_files[relative], right_files[relative]
+        try:
+            fmt = detect_format(left_file)
+        except ConfigDiffError:
+            try:
+                with left_file.open("rb") as left_stream, right_file.open("rb") as right_stream:
+                    while True:
+                        left_chunk, right_chunk = left_stream.read(65536), right_stream.read(65536)
+                        if left_chunk != right_chunk:
+                            same = False
+                            break
+                        if not left_chunk:
+                            same = True
+                            break
+            except OSError as exc:
+                raise ConfigDiffError(f"Cannot read directory entry {relative}: {exc}") from exc
+            if not same:
+                differences.append(Difference(relative, "changed", "<file>", "<file>"))
+            continue
+        try:
+            file_differences = compare_files(left_file, right_file, fmt, fmt, list_key, ignore_paths, ignore_order)
+        except ConfigDiffError as exc:
+            raise ConfigDiffError(f"In {relative}: {exc}") from None
+        for diff in file_differences:
+            differences.append(Difference(f"{relative}::{diff.path}", diff.kind, diff.old, diff.new))
+    return differences
+
+
+def _is_secret_path(path: str, redaction_patterns: Optional[List[str]] = None) -> bool:
+    segments = re.findall(r'[^.\[\]]+', path)
+    if any(_SECRET_PATTERN.search(segment.strip(chr(34) + chr(39))) for segment in segments):
+        return True
+    for pattern in redaction_patterns or []:
+        if _glob_match(path, pattern):
+            return True
+        if not any(char in pattern for char in "*?"):
+            if path.startswith(pattern + ".") or path.startswith(pattern + "["):
+                return True
+    return False
+
+
+def safe_value(value: Any, path: str, show_secrets: bool = False, redaction_patterns: Optional[List[str]] = None) -> Any:
+    if value is _MISSING:
+        return None
+    if not show_secrets and _is_secret_path(path, redaction_patterns):
+        return "********"
+    if isinstance(value, dict):
+        return {key: safe_value(item, _child_path(path, key), show_secrets, redaction_patterns) for key, item in value.items()}
+    if isinstance(value, list):
+        return [safe_value(item, _child_path(path, index, True), show_secrets, redaction_patterns) for index, item in enumerate(value)]
+    return value
+
+
+def serialize_differences(differences: List[Difference], show_secrets: bool = False, redaction_patterns: Optional[List[str]] = None) -> List[Dict[str, Any]]:
+    result = []
+    for diff in differences:
+        result.append({
+            "path": diff.path,
+            "kind": diff.kind,
+            "old": safe_value(diff.old, diff.path, show_secrets, redaction_patterns),
+            "new": safe_value(diff.new, diff.path, show_secrets, redaction_patterns),
+            "old_missing": diff.old is _MISSING,
+            "new_missing": diff.new is _MISSING,
+        })
+    return result

configdiff/patch.py

@@ -0,0 +1,124 @@
+import copy
+from typing import Any, Dict, List, Optional
+
+from .core import ConfigDiffError, _values_equal
+
+# Keep exact list diffing bounded: quadratic LCS is useful for small config
+# arrays, but a whole-list replacement is safer and faster for large arrays.
+_MAX_LIST_DIFF_CELLS = 4096
+
+
+def _pointer(parts: List[Any]) -> str:
+    return "".join("/" + str(part).replace("~", "~0").replace("/", "~1") for part in parts)
+
+
+def _list_patch(old: List[Any], new: List[Any], path: List[Any]) -> List[Dict[str, Any]]:
+    n, m = len(old), len(new)
+    if n * m > _MAX_LIST_DIFF_CELLS:
+        return [{"op": "replace", "path": _pointer(path), "value": copy.deepcopy(new)}]
+
+    # Longest common subsequence minimizes add/remove operations while keeping
+    # array indices valid as each operation is applied from left to right.
+    lcs = [[0] * (m + 1) for _ in range(n + 1)]
+    for i in range(n - 1, -1, -1):
+        row, next_row = lcs[i], lcs[i + 1]
+        for j in range(m - 1, -1, -1):
+            if _values_equal(old[i], new[j]):
+                row[j] = next_row[j + 1] + 1
+            else:
+                row[j] = max(next_row[j], row[j + 1])
+
+    operations: List[Dict[str, Any]] = []
+    i = j = index = 0
+    while i < n or j < m:
+        if i < n and j < m and _values_equal(old[i], new[j]):
+            i += 1
+            j += 1
+            index += 1
+        elif i < n and (j == m or lcs[i + 1][j] >= lcs[i][j + 1]):
+            operations.append({"op": "remove", "path": _pointer(path + [index])})
+            i += 1
+        else:
+            operations.append({
+                "op": "add",
+                "path": _pointer(path + [index]),
+                "value": copy.deepcopy(new[j]),
+            })
+            j += 1
+            index += 1
+    return operations
+
+
+def build_json_patch(old: Any, new: Any, path: Optional[List[Any]] = None) -> List[Dict[str, Any]]:
+    operations: List[Dict[str, Any]] = []
+    path = list(path or [])
+    if _values_equal(old, new):
+        return operations
+    if type(old) is type(new) and isinstance(old, dict):
+        for key in sorted(old.keys() - new.keys(), key=str):
+            operations.append({"op": "remove", "path": _pointer(path + [key])})
+        for key in sorted(new.keys() - old.keys(), key=str):
+            operations.append({"op": "add", "path": _pointer(path + [key]), "value": copy.deepcopy(new[key])})
+        for key in sorted(old.keys() & new.keys(), key=str):
+            operations.extend(build_json_patch(old[key], new[key], path + [key]))
+        return operations
+    if isinstance(old, list) and isinstance(new, list):
+        return _list_patch(old, new, path)
+    return [{"op": "replace", "path": _pointer(path), "value": copy.deepcopy(new)}]
+
+
+def _decode_pointer(pointer: str) -> List[str]:
+    if pointer == "":
+        return []
+    if not pointer.startswith("/"):
+        raise ConfigDiffError("Invalid JSON Pointer in patch")
+    return [part.replace("~1", "/").replace("~0", "~") for part in pointer[1:].split("/")]
+
+
+def apply_json_patch(document: Any, operations: Any) -> Any:
+    if not isinstance(operations, list):
+        raise ConfigDiffError("JSON Patch must be an array")
+    result = copy.deepcopy(document)
+    for number, operation in enumerate(operations):
+        if not isinstance(operation, dict) or operation.get("op") not in {"add", "remove", "replace"} or not isinstance(operation.get("path"), str):
+            raise ConfigDiffError(f"Invalid JSON Patch operation at index {number}")
+        op, parts = operation["op"], _decode_pointer(operation["path"])
+        if op in {"add", "replace"} and "value" not in operation:
+            raise ConfigDiffError(f"Missing value in JSON Patch operation at index {number}")
+        if not parts:
+            if op == "remove":
+                raise ConfigDiffError("Removing the document root is not supported")
+            result = copy.deepcopy(operation["value"])
+            continue
+        parent = result
+        try:
+            for part in parts[:-1]:
+                parent = parent[int(part)] if isinstance(parent, list) else parent[part]
+            key = parts[-1]
+            if isinstance(parent, list):
+                if op == "add":
+                    if key == "-":
+                        parent.append(copy.deepcopy(operation["value"]))
+                    else:
+                        index = int(key)
+                        if index < 0 or index > len(parent):
+                            raise IndexError
+                        parent.insert(index, copy.deepcopy(operation["value"]))
+                elif op == "remove":
+                    del parent[int(key)]
+                else:
+                    parent[int(key)] = copy.deepcopy(operation["value"])
+            elif isinstance(parent, dict):
+                if op == "add":
+                    parent[key] = copy.deepcopy(operation["value"])
+                elif op == "remove":
+                    del parent[key]
+                else:
+                    if key not in parent:
+                        raise KeyError(key)
+                    parent[key] = copy.deepcopy(operation["value"])
+            else:
+                raise TypeError
+        except (KeyError, IndexError, ValueError, TypeError) as exc:
+            raise ConfigDiffError(f"Cannot apply JSON Patch operation at index {number}: path does not exist or is invalid") from exc
+    return result

diffora-0.1.0.dist-info/METADATA

@@ -0,0 +1,292 @@
+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).

diffora-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+configdiff/__init__.py,sha256=tHxX1np6rIaX4KEV4ZvVFE6YYrw27xDmNqJfqX7ekU0,223
+configdiff/cli.py,sha256=rLzLBHpI6HE18gSVM9xxx0IfpaOedUnyJgxmH82ONlI,10860
+configdiff/core.py,sha256=jqngFh60uLax_b9kX4g7iDhUEhIvuyLieVARC4d5-Zw,25344
+configdiff/patch.py,sha256=2KWQxTJIUGLCRJRQini7M8BI3vwvpNsGqhdIMbtJyik,5412
+diffora-0.1.0.dist-info/licenses/LICENSE,sha256=l5keh_f-OrbRqd-U6EolmzK1KvXxaMLVz32svHjD2SM,1067
+diffora-0.1.0.dist-info/METADATA,sha256=9nKuufE4tPQva8N-8rwr_CcJbCiJBM8N02ekMgnsqRE,14468
+diffora-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+diffora-0.1.0.dist-info/entry_points.txt,sha256=jq9F1vo5L7bkZWD6HvaKHlQpn367HaZPU5SSvqjgohM,81
+diffora-0.1.0.dist-info/top_level.txt,sha256=vsVJN11EiBLRQJ4LxI2g0a45_Mhp19YHyt2G4ArqPSs,11
+diffora-0.1.0.dist-info/RECORD,,

diffora-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

diffora-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+configdiff = configdiff.cli:main
+diffora = configdiff.cli:main

diffora-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HashPalace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

diffora-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+configdiff