confdiff 0.14.0

package/dist/redact.js

@@ -0,0 +1,172 @@
+import { matchAnyGlob } from "./diff.js";
+/**
+ * Secret-safe diffs. When enabled, values at "sensitive" paths (passwords,
+ * tokens, API keys, …) are replaced in the output with a stable, non-reversible
+ * fingerprint — `«redacted:ab12cd»` — instead of the raw value. This lets you
+ * paste a config diff into a PR, a Slack thread or a CI log to prove *what
+ * drifted* without ever leaking the credential itself. Because the fingerprint
+ * is derived from the value, a reader can still see that old and new differ (the
+ * two fingerprints won't match), but can't recover either one.
+ *
+ * No other config-diff tool does this; it's the reason `confdiff --redact` is
+ * safe to run in shared/automated contexts on real secrets-bearing files
+ * (`.env`, `application.properties`, Helm values, k8s Secrets, …).
+ */
+/**
+ * Built-in heuristics for "this key holds a secret". Matched against the LAST
+ * path segment (the key name), case-insensitively, after stripping separators.
+ * Deliberately conservative: whole-token indicators so `key` matches but
+ * `keyboard`/`monkey` don't, and `pass`-family words are anchored.
+ */
+const SECRET_TOKENS = [
+    "password",
+    "passwd",
+    "passphrase",
+    "pwd",
+    "secret",
+    "token",
+    "apikey",
+    "accesskey",
+    "secretkey",
+    "privatekey",
+    "signingkey",
+    "encryptionkey",
+    "credential",
+    "credentials",
+    "clientsecret",
+    "authtoken",
+    "accesstoken",
+    "refreshtoken",
+    "bearer",
+    "dsn",
+];
+/** A separator-insensitive view of a key: `DB_PASSWORD` / `db-password` / `dbPassword` -> tokens. */
+function keyTokens(seg) {
+    return seg
+        // split camelCase / PascalCase into words
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+/** Does a key name look like it holds a secret, by built-in heuristics? */
+export function looksSecret(seg) {
+    const words = keyTokens(seg);
+    if (words.length === 0)
+        return false;
+    const joined = words.join("");
+    // Multi-word combined forms: apikey, accesstoken, clientsecret, privatekey…
+    if (SECRET_TOKENS.includes(joined))
+        return true;
+    for (const w of words) {
+        if (SECRET_TOKENS.includes(w))
+            return true;
+        // standalone "key" is a secret indicator only next to auth-ish words
+        if (w === "key" && words.some((x) => ["api", "access", "secret", "private", "signing", "encryption"].includes(x)))
+            return true;
+    }
+    return false;
+}
+/**
+ * Shannon entropy (bits per character) of a string. A uniformly random
+ * high-entropy string (API key, JWT, base64 token) scores high (~4–6);
+ * repetitive or natural-language text scores low.
+ */
+export function shannonEntropy(s) {
+    if (s.length === 0)
+        return 0;
+    const freq = new Map();
+    for (const ch of s)
+        freq.set(ch, (freq.get(ch) ?? 0) + 1);
+    let e = 0;
+    for (const n of freq.values()) {
+        const p = n / s.length;
+        e -= p * Math.log2(p);
+    }
+    return e;
+}
+/**
+ * Content-based secret heuristic: does a VALUE *look* like a random credential,
+ * regardless of its key name? Catches secrets stored under non-obvious keys
+ * (`x`, `data`, `value`) that the key-name heuristics miss.
+ *
+ * Deliberately conservative to avoid masking ordinary config: only long,
+ * whitespace-free, tokenish strings with high per-character entropy qualify.
+ * This *complements* the key-name heuristics — it does NOT replace them: a
+ * short weak password like `Letmein` under a `password:` key has low entropy
+ * and is only caught by the key-name check, while a 40-char API token under a
+ * bland key is only caught here. Enable both for the widest coverage.
+ */
+export function looksHighEntropy(v) {
+    if (typeof v !== "string")
+        return false;
+    const s = v.trim();
+    // Secrets are long and contiguous; prose/paths/URLs with spaces are not.
+    if (s.length < 20 || /\s/.test(s))
+        return false;
+    // Restrict to the character set of tokens/keys/base64/hex (avoids flagging
+    // long prose-y identifiers, sentences joined by punctuation, etc.).
+    if (!/^[A-Za-z0-9+/=_.\-:]+$/.test(s))
+        return false;
+    // Require a mix of character classes so a long all-lowercase word or a run of
+    // digits (phone/id) isn't mistaken for a random secret.
+    const classes = Number(/[a-z]/.test(s)) + Number(/[A-Z]/.test(s)) + Number(/[0-9]/.test(s)) + Number(/[+/=_.\-:]/.test(s));
+    if (classes < 2)
+        return false;
+    return shannonEntropy(s) >= 3.5;
+}
+/**
+ * Build a predicate deciding whether a given path's VALUE should be redacted.
+ * @param builtins  use the built-in secret-key heuristics
+ * @param globs     extra key-name substrings / path globs (matched via matchAnyGlob)
+ * @param entropy   also redact values that *look* like high-entropy secrets,
+ *                  regardless of key name (complements, doesn't replace, the above)
+ */
+export function makeRedactMatcher(builtins, globs, entropy = false) {
+    return (path, value) => {
+        if (globs.length && matchAnyGlob(path, globs))
+            return true;
+        if (builtins && path.length > 0) {
+            const last = path[path.length - 1];
+            if (typeof last === "string" && looksSecret(last))
+                return true;
+        }
+        if (entropy && looksHighEntropy(value))
+            return true;
+        return false;
+    };
+}
+/**
+ * cyrb53 — a fast, well-distributed 53-bit string hash. Pure JS with no
+ * dependencies, so the CLI, the GitHub Action bundle and the browser playground
+ * all compute the SAME fingerprint (node:crypto isn't available in the browser).
+ * We surface only the low 24 bits (6 hex chars): enough to make a *changed*
+ * value obvious (the two tokens differ) while truncation keeps it
+ * non-reversible — you can't recover the value from the fingerprint.
+ */
+function cyrb53(str, seed = 0x9e3779b9) {
+    let h1 = 0xdeadbeef ^ seed;
+    let h2 = 0x41c6ce57 ^ seed;
+    for (let i = 0; i < str.length; i++) {
+        const ch = str.charCodeAt(i);
+        h1 = Math.imul(h1 ^ ch, 2654435761);
+        h2 = Math.imul(h2 ^ ch, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return 4294967296 * (2097151 & h2) + (h1 >>> 0);
+}
+/**
+ * Stable, non-reversible fingerprint of a value. Equal values -> equal token,
+ * so an *unchanged* redacted value never shows up as a spurious diff, while a
+ * *changed* one shows two visibly different tokens.
+ */
+export function redactToken(v) {
+    if (v === undefined)
+        return "«redacted»";
+    const s = typeof v === "string"
+        ? v
+        : JSON.stringify(v, (_k, val) => (typeof val === "bigint" ? val.toString() : val));
+    const h = (cyrb53(s ?? "null") & 0xffffff).toString(16).padStart(6, "0");
+    return `«redacted:${h}»`;
+}

package/dist/render.d.ts

@@ -0,0 +1,13 @@
+import { type Change } from "./diff.js";
+import { type RedactMatcher } from "./redact.js";
+export interface RenderOptions {
+    color?: boolean;
+    labelA?: string;
+    labelB?: string;
+    /** If set, values at matching paths are replaced with a non-reversible fingerprint. */
+    redact?: RedactMatcher;
+}
+export declare function renderText(changes: Change[], opts?: RenderOptions): string;
+export declare function renderJson(changes: Change[], opts?: {
+    redact?: RedactMatcher;
+}): string;

package/dist/render.js

@@ -0,0 +1,105 @@
+import pc from "picocolors";
+import { formatPath, segStr } from "./diff.js";
+import { redactToken } from "./redact.js";
+function preview(v) {
+    if (typeof v === "string")
+        return JSON.stringify(v);
+    if (v === null)
+        return "null";
+    if (v === undefined)
+        return "undefined";
+    if (typeof v === "object") {
+        const json = JSON.stringify(v, (_k, val) => (typeof val === "bigint" ? val.toString() : val));
+        if (json.length <= 60)
+            return json;
+        return json.slice(0, 57) + "...";
+    }
+    return String(v);
+}
+export function renderText(changes, opts = {}) {
+    const useColor = opts.color ?? true;
+    const c = useColor ? pc : passthrough();
+    const redact = opts.redact;
+    // Redact a change if its key looks secret OR either side's value does; mask
+    // both sides together so drift stays visible (differing fingerprints).
+    const isMasked = (ch) => !!redact && (redact(ch.path, ch.oldValue) || redact(ch.path, ch.newValue));
+    const show = (ch, v) => isMasked(ch) ? redactToken(v) : preview(v);
+    if (changes.length === 0) {
+        return c.dim("no semantic differences");
+    }
+    const lines = [];
+    let added = 0;
+    let removed = 0;
+    let changed = 0;
+    // Pad the path column so values line up in a clean second column.
+    const width = Math.min(40, changes.reduce((m, ch) => Math.max(m, formatPath(ch.path).length), 0));
+    const pad = (s) => (s.length >= width ? s : s + " ".repeat(width - s.length));
+    for (const ch of changes) {
+        const p = formatPath(ch.path);
+        if (ch.kind === "add") {
+            added++;
+            lines.push(`${c.green("+")} ${c.green(pad(p))}  ${c.dim("=")} ${c.green(show(ch, ch.newValue))}`);
+        }
+        else if (ch.kind === "remove") {
+            removed++;
+            lines.push(`${c.red("-")} ${c.red(pad(p))}  ${c.dim("=")} ${c.red(show(ch, ch.oldValue))}`);
+        }
+        else {
+            changed++;
+            const tag = ch.typeChanged ? c.dim(" (type)") : "";
+            lines.push(`${c.yellow("~")} ${c.yellow(pad(p))}${tag}  ${c.red(show(ch, ch.oldValue))} ${c.dim("=>")} ${c.green(show(ch, ch.newValue))}`);
+        }
+    }
+    const parts = [];
+    if (added)
+        parts.push(c.green(`${added} added`));
+    if (removed)
+        parts.push(c.red(`${removed} removed`));
+    if (changed)
+        parts.push(c.yellow(`${changed} changed`));
+    lines.push("");
+    lines.push(c.bold(`${changes.length} change${changes.length === 1 ? "" : "s"}: `) + parts.join(", "));
+    return lines.join("\n");
+}
+/**
+ * Build an RFC 6901 JSON Pointer from a path. Keys are escaped so that a `/`
+ * inside a key (e.g. the k8s annotation `app.kubernetes.io/name`) becomes `~1`
+ * and a literal `~` becomes `~0` — otherwise the pointer would be ambiguous and
+ * break any downstream JSON Pointer consumer. An empty path is the whole
+ * document, whose pointer is the empty string.
+ */
+function toJsonPointer(path) {
+    return path
+        .map((s) => "/" + segStr(s).replace(/~/g, "~0").replace(/\//g, "~1"))
+        .join("");
+}
+export function renderJson(changes, opts = {}) {
+    // Large integers are preserved as BigInt (lossless); emit them as decimal
+    // strings so the JSON stays valid and precise (a raw number would round).
+    const bigIntSafe = (_k, v) => (typeof v === "bigint" ? v.toString() : v);
+    const redact = opts.redact;
+    return JSON.stringify({
+        changed: changes.length > 0,
+        count: changes.length,
+        changes: changes.map((ch) => {
+            const masked = !!(redact && (redact(ch.path, ch.oldValue) || redact(ch.path, ch.newValue)));
+            const old = masked ? redactToken(ch.oldValue) : ch.oldValue;
+            const nw = masked ? redactToken(ch.newValue) : ch.newValue;
+            return {
+                path: ch.path,
+                pointer: toJsonPointer(ch.path),
+                kind: ch.kind,
+                ...(ch.oldValue !== undefined || ch.kind !== "add" ? { oldValue: old } : {}),
+                ...(ch.newValue !== undefined || ch.kind !== "remove" ? { newValue: nw } : {}),
+                ...(ch.typeChanged ? { typeChanged: true } : {}),
+                ...(masked ? { redacted: true } : {}),
+            };
+        }),
+    }, bigIntSafe, 2);
+}
+function passthrough() {
+    const id = (s) => s;
+    return new Proxy({}, {
+        get: () => id,
+    });
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "confdiff",
+  "version": "0.14.0",
+  "description": "Semantic, format-aware diff for config & structured data files (JSON, YAML, TOML, INI, .env, CSV, XML). See what actually changed — the meaning, not the text.",
+  "type": "module",
+  "bin": {
+    "confdiff": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test --import tsx test/*.test.ts",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build",
+    "build:action": "esbuild src/cli.ts --bundle --platform=node --target=node20 --format=cjs --outfile=action/confdiff.cjs",
+    "build:web": "esbuild web/entry.ts --bundle --format=iife --platform=browser --target=es2020 --alias:node:path=./web/shims/path.js --outfile=docs/playground.js --minify && cp web/index.html docs/index.html && cp web/app.js docs/app.js && cp web/og.png docs/og.png && cp web/robots.txt docs/robots.txt && cp web/sitemap.xml docs/sitemap.xml && cp web/secrets-in-config-diffs.html docs/secrets-in-config-diffs.html && cp web/diff-kubernetes-manifests.html docs/diff-kubernetes-manifests.html && cp web/diff-docker-compose.html docs/diff-docker-compose.html && cp web/cross-format-config-diff.html docs/cross-format-config-diff.html && cp web/confdiff-preview.png docs/confdiff-preview.png"
+  },
+  "keywords": [
+    "diff",
+    "config",
+    "yaml",
+    "json",
+    "toml",
+    "ini",
+    "dotenv",
+    "semantic-diff",
+    "structured-diff",
+    "cli",
+    "ci",
+    "config-drift",
+    "xml",
+    "csv"
+  ],
+  "author": "Esperanza Volkov",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/esperanza-volkov/confdiff.git"
+  },
+  "bugs": {
+    "url": "https://github.com/esperanza-volkov/confdiff/issues"
+  },
+  "homepage": "https://github.com/esperanza-volkov/confdiff#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "fast-xml-parser": "^5.10.1",
+    "ini": "^5.0.0",
+    "picocolors": "^1.1.1",
+    "smol-toml": "^1.3.1",
+    "yaml": "^2.6.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "esbuild": "^0.24.0"
+  }
+}