confdiff 0.14.0

package/dist/diff.js

@@ -0,0 +1,430 @@
+export function isKeySeg(s) {
+    return typeof s === "object" && s !== null && "key" in s && "value" in s;
+}
+/** Canonical string form of a single path segment (used for glob matching and
+ * pointers): keyed segments render as `key=value`, everything else as-is. */
+export function segStr(s) {
+    if (isKeySeg(s))
+        return `${s.key}=${String(s.value)}`;
+    return String(s);
+}
+export function typeOf(v) {
+    if (v === null)
+        return "null";
+    if (Array.isArray(v))
+        return "array";
+    if (v instanceof Date)
+        return "date";
+    if (typeof v === "object" && v !== null && !isPlainObject(v))
+        return "scalar";
+    return typeof v;
+}
+/**
+ * Only plain objects (and arrays) are treated as containers to recurse into.
+ * Exotic objects — Date (from TOML/YAML), RegExp, class instances — are compared
+ * as opaque scalars by value, so a date change isn't silently swallowed.
+ */
+function isPlainObject(v) {
+    if (v === null || typeof v !== "object" || Array.isArray(v))
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
+/** Comparable representation of a non-plain, non-array value (Date, etc.). */
+function scalarValue(v) {
+    if (v instanceof Date)
+        return v.getTime();
+    if (v !== null && typeof v === "object") {
+        try {
+            return JSON.stringify(v);
+        }
+        catch {
+            return String(v);
+        }
+    }
+    return v;
+}
+function pathToString(path) {
+    let out = "";
+    for (const seg of path) {
+        if (typeof seg === "number")
+            out += `[${seg}]`;
+        else if (isKeySeg(seg))
+            out += `[${seg.key}=${String(seg.value)}]`;
+        else if (out === "")
+            out = seg;
+        else
+            out += `.${seg}`;
+    }
+    return out;
+}
+function segMatch(pat, seg) {
+    if (pat === "*" || pat === "**")
+        return true;
+    if (pat === seg)
+        return true;
+    // Support intra-segment wildcards: `*` = any run of chars, `?` = one char
+    // (e.g. `*_SECRET`, `db_*`, `item?`). Literal chars are regex-escaped.
+    if (!pat.includes("*") && !pat.includes("?"))
+        return false;
+    const re = "^" +
+        pat.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") +
+        "$";
+    return new RegExp(re).test(seg);
+}
+/**
+ * Split a glob pattern into segment tokens, understanding BOTH dot notation
+ * and the bracket notation the tool itself prints for array indices. So
+ * `items[0].name`, `items[*].name` and `items.0.name` all tokenize to the same
+ * segment list. This is what makes a printed path (e.g. `items[0].name`)
+ * round-trippable straight back into --ignore/--only. Inside `[...]` the content
+ * is taken verbatim as one token (`0`, `*`, `**`), so an index is never split.
+ */
+function splitPattern(pattern) {
+    const tokens = [];
+    let cur = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === ".") {
+            if (cur !== "")
+                tokens.push(cur);
+            cur = "";
+        }
+        else if (ch === "[") {
+            if (cur !== "")
+                tokens.push(cur);
+            cur = "";
+            let inner = "";
+            let j = i + 1;
+            while (j < pattern.length && pattern[j] !== "]")
+                inner += pattern[j++];
+            tokens.push(inner);
+            i = j; // skip past the closing "]"
+        }
+        else {
+            cur += ch;
+        }
+    }
+    if (cur !== "")
+        tokens.push(cur);
+    return tokens;
+}
+/** Match a path against a glob pattern. `*` = one segment, `**` = zero-or-more segments; within a segment `*`/`?` are wildcards (e.g. `*_SECRET`). Array indices may be written `foo[0]`/`foo[*]` or `foo.0`/`foo.*`. */
+function matchGlob(pattern, path) {
+    const pats = splitPattern(pattern);
+    const segs = path.map(segStr);
+    // simple recursive matcher supporting **
+    const rec = (pi, si) => {
+        if (pi === pats.length)
+            return si === segs.length;
+        if (pats[pi] === "**") {
+            // ** matches any number of segments
+            for (let k = si; k <= segs.length; k++) {
+                if (rec(pi + 1, k))
+                    return true;
+            }
+            return false;
+        }
+        if (si >= segs.length)
+            return false;
+        // Standard one-token-per-segment match (preserves intra-segment wildcards).
+        if (segMatch(pats[pi], segs[si]) && rec(pi + 1, si + 1))
+            return true;
+        // Dotted-key support: a single path segment may itself contain dots (e.g.
+        // the k8s annotation key `app.kubernetes.io/name`, or log4j-style
+        // properties). Such a key is *rendered* with embedded dots, so let a run of
+        // consecutive literal pattern tokens joined by "." match one segment. This
+        // makes the tool's own printed path round-trippable back into --ignore/--only.
+        // Only literal tokens are joined, so wildcard semantics are unchanged.
+        if (!hasWildcard(pats[pi])) {
+            let joined = pats[pi];
+            for (let j = pi + 1; j < pats.length; j++) {
+                if (pats[j] === "**" || hasWildcard(pats[j]))
+                    break;
+                joined += "." + pats[j];
+                if (joined === segs[si] && rec(j + 1, si + 1))
+                    return true;
+            }
+        }
+        return false;
+    };
+    return rec(0, 0);
+}
+function hasWildcard(tok) {
+    return tok.includes("*") || tok.includes("?");
+}
+/**
+ * Public helper: does `path` match ANY of the given glob `patterns`? Uses the
+ * same matcher as --ignore/--only (dot + bracket notation, `*`/`**`/`?`, dotted
+ * keys). Also treats a bare key-name token (no separators) as matching that key
+ * at any depth, so `--redact password` masks `db.password` and `password`.
+ */
+export function matchAnyGlob(path, patterns) {
+    for (const p of patterns) {
+        if (matchGlob(p, path))
+            return true;
+        // bare key name -> match that last segment anywhere
+        if (!p.includes(".") && !p.includes("[") && path.length > 0) {
+            if (segMatch(p, segStr(path[path.length - 1])))
+                return true;
+        }
+    }
+    return false;
+}
+function pathSelected(path, opts) {
+    const s = pathToString(path);
+    if (opts.ignore && opts.ignore.some((p) => matchGlob(p, path)))
+        return false;
+    if (opts.only && opts.only.length > 0) {
+        // keep a path if it matches, or is a prefix of, or is under a selected glob
+        return opts.only.some((p) => matchGlob(p, path));
+    }
+    void s;
+    return true;
+}
+function coerce(v) {
+    if (typeof v !== "string")
+        return v;
+    const t = v.trim();
+    if (t === "true")
+        return true;
+    if (t === "false")
+        return false;
+    if (t === "null")
+        return null;
+    if (t !== "" && !Number.isNaN(Number(t)))
+        return Number(t);
+    return v;
+}
+function scalarEqual(a, b, opts) {
+    if (opts.loose) {
+        a = coerce(a);
+        b = coerce(b);
+    }
+    const sa = scalarValue(a);
+    const sb = scalarValue(b);
+    // Object.is keeps NaN == NaN (from YAML `.nan`); the extra `===` treats +0 and
+    // -0 as equal — numerically the same config value, so `0 => -0` isn't a change
+    // (Object.is alone would report a useless "0 => 0" diff).
+    return Object.is(sa, sb) || sa === sb;
+}
+/** Stable-ish key for multiset array comparison. */
+function valueKey(v) {
+    return JSON.stringify(v, (_k, val) => {
+        // BigInt (lossless large integers) isn't JSON-serialisable; tag it so two
+        // distinct big integers get distinct, stable keys.
+        if (typeof val === "bigint")
+            return `${val.toString()}n`;
+        if (val && typeof val === "object" && !Array.isArray(val)) {
+            const sorted = {};
+            for (const k of Object.keys(val).sort()) {
+                sorted[k] = val[k];
+            }
+            return sorted;
+        }
+        return val;
+    });
+}
+export function diff(a, b, opts = {}) {
+    const changes = [];
+    walk(a, b, [], changes, opts);
+    return changes;
+}
+function walk(a, b, path, out, opts) {
+    const ta = typeOf(a);
+    const tb = typeOf(b);
+    if (ta === "object" && tb === "object") {
+        const ao = a;
+        const bo = b;
+        const keys = new Set([...Object.keys(ao), ...Object.keys(bo)]);
+        for (const k of [...keys].sort()) {
+            const childPath = [...path, k];
+            const inA = Object.prototype.hasOwnProperty.call(ao, k);
+            const inB = Object.prototype.hasOwnProperty.call(bo, k);
+            if (inA && !inB) {
+                if (pathSelected(childPath, opts))
+                    out.push({ path: childPath, kind: "remove", oldValue: ao[k] });
+            }
+            else if (!inA && inB) {
+                if (pathSelected(childPath, opts))
+                    out.push({ path: childPath, kind: "add", newValue: bo[k] });
+            }
+            else {
+                walk(ao[k], bo[k], childPath, out, opts);
+            }
+        }
+        return;
+    }
+    if (ta === "array" && tb === "array") {
+        const av = a;
+        const bv = b;
+        const keyField = opts.arrayKey && opts.arrayKey.length > 0 ? resolveArrayKey(path, av, bv, opts.arrayKey) : undefined;
+        if (keyField) {
+            diffArrayKeyed(av, bv, path, out, opts, keyField);
+        }
+        else if (opts.arraySet) {
+            diffArraySet(av, bv, path, out, opts);
+        }
+        else {
+            diffArrayIndexed(av, bv, path, out, opts);
+        }
+        return;
+    }
+    // At least one side is a scalar (or a container facing a non-matching type).
+    // Container-vs-anything mismatch is always a type change.
+    const containerA = ta === "object" || ta === "array";
+    const containerB = tb === "object" || tb === "array";
+    if (containerA || containerB) {
+        if (pathSelected(path, opts))
+            out.push({ path, kind: "change", oldValue: a, newValue: b, typeChanged: true });
+        return;
+    }
+    // Both scalars. In loose mode we coerce first so "3"==3 and "true"==true.
+    if (scalarEqual(a, b, opts))
+        return;
+    if (pathSelected(path, opts))
+        out.push({ path, kind: "change", oldValue: a, newValue: b, typeChanged: ta !== tb });
+}
+function diffArrayIndexed(a, b, path, out, opts) {
+    const max = Math.max(a.length, b.length);
+    for (let i = 0; i < max; i++) {
+        const childPath = [...path, i];
+        if (i >= b.length) {
+            if (pathSelected(childPath, opts))
+                out.push({ path: childPath, kind: "remove", oldValue: a[i] });
+        }
+        else if (i >= a.length) {
+            if (pathSelected(childPath, opts))
+                out.push({ path: childPath, kind: "add", newValue: b[i] });
+        }
+        else {
+            walk(a[i], b[i], childPath, out, opts);
+        }
+    }
+}
+/** Is `v` a plain object that carries a scalar-valued `field`? */
+function keyableBy(v, field) {
+    if (!isPlainObject(v))
+        return false;
+    const rec = v;
+    if (!Object.prototype.hasOwnProperty.call(rec, field))
+        return false;
+    const fv = rec[field];
+    return fv === null || (typeof fv !== "object" && typeof fv !== "function");
+}
+/**
+ * Decide which key field (if any) to use for matching this pair of arrays.
+ * Tries each configured entry in order: scoped `pathGlob=field` entries whose
+ * glob matches this array's path, plus bare `field` entries that apply
+ * everywhere. A field is usable only when EVERY element on both sides is a plain
+ * object carrying that field as a scalar AND its values are unique within each
+ * side (otherwise keying would be ambiguous, so we fall back to indexed diff).
+ */
+function resolveArrayKey(path, a, b, specs) {
+    if (a.length === 0 && b.length === 0)
+        return undefined;
+    const candidates = [];
+    for (const spec of specs) {
+        const eq = spec.indexOf("=");
+        if (eq >= 0) {
+            const glob = spec.slice(0, eq);
+            const field = spec.slice(eq + 1);
+            if (field && matchGlob(glob, path))
+                candidates.push(field);
+        }
+        else if (spec) {
+            candidates.push(spec);
+        }
+    }
+    for (const field of candidates) {
+        const all = [...a, ...b];
+        if (!all.every((v) => keyableBy(v, field)))
+            continue;
+        if (uniqueKeyed(a, field) && uniqueKeyed(b, field))
+            return field;
+    }
+    return undefined;
+}
+function uniqueKeyed(arr, field) {
+    const seen = new Set();
+    for (const v of arr) {
+        const k = valueKey(v[field]);
+        if (seen.has(k))
+            return false;
+        seen.add(k);
+    }
+    return true;
+}
+function diffArrayKeyed(a, b, path, out, opts, field) {
+    const mapA = new Map();
+    const mapB = new Map();
+    const order = [];
+    const raw = new Map();
+    for (const v of a) {
+        const fv = v[field];
+        const k = valueKey(fv);
+        mapA.set(k, v);
+        if (!raw.has(k)) {
+            raw.set(k, fv);
+            order.push(k);
+        }
+    }
+    for (const v of b) {
+        const fv = v[field];
+        const k = valueKey(fv);
+        mapB.set(k, v);
+        if (!raw.has(k)) {
+            raw.set(k, fv);
+            order.push(k);
+        }
+    }
+    for (const k of order) {
+        const fv = raw.get(k);
+        const seg = { key: field, value: fv };
+        const childPath = [...path, seg];
+        const inA = mapA.has(k);
+        const inB = mapB.has(k);
+        if (inA && inB) {
+            walk(mapA.get(k), mapB.get(k), childPath, out, opts);
+        }
+        else if (inA) {
+            if (pathSelected(childPath, opts))
+                out.push({ path: childPath, kind: "remove", oldValue: mapA.get(k) });
+        }
+        else {
+            if (pathSelected(childPath, opts))
+                out.push({ path: childPath, kind: "add", newValue: mapB.get(k) });
+        }
+    }
+}
+function diffArraySet(a, b, path, out, opts) {
+    const counts = new Map();
+    const sample = new Map();
+    for (const v of a) {
+        const k = valueKey(v);
+        counts.set(k, (counts.get(k) ?? 0) + 1);
+        if (!sample.has(k))
+            sample.set(k, v);
+    }
+    for (const v of b) {
+        const k = valueKey(v);
+        counts.set(k, (counts.get(k) ?? 0) - 1);
+        if (!sample.has(k))
+            sample.set(k, v);
+    }
+    for (const [k, c] of counts) {
+        if (c > 0) {
+            for (let n = 0; n < c; n++)
+                if (pathSelected(path, opts))
+                    out.push({ path: [...path, "{set}"], kind: "remove", oldValue: sample.get(k) });
+        }
+        else if (c < 0) {
+            for (let n = 0; n < -c; n++)
+                if (pathSelected(path, opts))
+                    out.push({ path: [...path, "{set}"], kind: "add", newValue: sample.get(k) });
+        }
+    }
+}
+export function formatPath(path) {
+    return pathToString(path) || "(root)";
+}

package/dist/dirdiff.d.ts

@@ -0,0 +1,28 @@
+import { type Change, type DiffOptions } from "./diff.js";
+export type FileStatus = "added" | "removed" | "changed" | "error";
+export interface FileEntry {
+    /** POSIX-style relative path within the compared directories. */
+    path: string;
+    status: FileStatus;
+    /** Semantic changes for a "changed" file. */
+    changes?: Change[];
+    /** Human-readable error for an "error" file (e.g. parse failure on one side). */
+    error?: string;
+}
+export interface DirDiffResult {
+    files: FileEntry[];
+    /** True if any added/removed/changed file was found. */
+    changed: boolean;
+    /** True if any file could not be parsed on one/both sides (exit 2). */
+    errored: boolean;
+}
+export interface DirDiffOptions extends DiffOptions {
+    csvKey?: string;
+}
+export declare function isDirectory(p: string): boolean;
+/**
+ * Compare two directory trees file-by-file, matching config files by their
+ * relative path and reporting per-file semantic changes. Files present on only
+ * one side are reported as added/removed.
+ */
+export declare function dirDiff(dirA: string, dirB: string, opts?: DirDiffOptions): DirDiffResult;

package/dist/dirdiff.js

@@ -0,0 +1,99 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { diff } from "./diff.js";
+import { parseContent, detectFormat, keyRowsByColumn, isConfigFilename, } from "./parse.js";
+export function isDirectory(p) {
+    if (p === "-")
+        return false;
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Recursively collect POSIX-normalized relative paths of config files under `root`. */
+function collectConfigFiles(root) {
+    const found = new Set();
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const name = e.name;
+            // Skip common noise directories that never hold meaningful config.
+            if (e.isDirectory()) {
+                if (name === ".git" || name === "node_modules")
+                    continue;
+                walk(join(dir, name));
+            }
+            else if (e.isFile() || e.isSymbolicLink()) {
+                if (isConfigFilename(name)) {
+                    const rel = relative(root, join(dir, name)).split(sep).join("/");
+                    found.add(rel);
+                }
+            }
+        }
+    };
+    walk(root);
+    return found;
+}
+function loadValue(absPath, relPath, csvKey) {
+    const raw = readFileSync(absPath, "utf8");
+    const fmt = detectFormat(relPath, raw);
+    let val = parseContent(raw, fmt);
+    if (csvKey && fmt === "csv") {
+        val = keyRowsByColumn(val, csvKey);
+    }
+    return val;
+}
+/**
+ * Compare two directory trees file-by-file, matching config files by their
+ * relative path and reporting per-file semantic changes. Files present on only
+ * one side are reported as added/removed.
+ */
+export function dirDiff(dirA, dirB, opts = {}) {
+    const filesA = collectConfigFiles(dirA);
+    const filesB = collectConfigFiles(dirB);
+    const all = new Set([...filesA, ...filesB]);
+    const sorted = [...all].sort();
+    const diffOpts = {
+        ignore: opts.ignore,
+        only: opts.only,
+        arraySet: opts.arraySet,
+        arrayKey: opts.arrayKey,
+        loose: opts.loose,
+    };
+    const files = [];
+    for (const rel of sorted) {
+        const inA = filesA.has(rel);
+        const inB = filesB.has(rel);
+        if (inA && !inB) {
+            files.push({ path: rel, status: "removed" });
+            continue;
+        }
+        if (!inA && inB) {
+            files.push({ path: rel, status: "added" });
+            continue;
+        }
+        // Present on both sides — diff the parsed models.
+        try {
+            const valA = loadValue(join(dirA, rel), rel, opts.csvKey);
+            const valB = loadValue(join(dirB, rel), rel, opts.csvKey);
+            const changes = diff(valA, valB, diffOpts);
+            if (changes.length > 0) {
+                files.push({ path: rel, status: "changed", changes });
+            }
+        }
+        catch (e) {
+            files.push({ path: rel, status: "error", error: e.message });
+        }
+    }
+    const errored = files.some((f) => f.status === "error");
+    const changed = files.some((f) => f.status !== "error");
+    return { files, changed, errored };
+}

package/dist/gitdriver.d.ts

@@ -0,0 +1,25 @@
+/** Default file patterns wired to the confdiff diff driver. */
+export declare const DEFAULT_PATTERNS: string[];
+/** The command git should run as the external diff driver. */
+export declare const DRIVER_COMMAND = "confdiff --git-diff-driver";
+export interface InstallOptions {
+    global: boolean;
+    patterns: string[];
+    /** Injected for testing; defaults to real git via execFileSync. */
+    git?: (args: string[]) => string;
+    /** Injected for testing; defaults to process.cwd(). */
+    cwd?: string;
+}
+export interface InstallResult {
+    scope: "global" | "local";
+    attributesFile: string;
+    added: string[];
+    alreadyPresent: string[];
+    command: string;
+}
+/**
+ * Configure git to use confdiff as an external diff driver and wire the given
+ * file patterns to it. Idempotent: existing `<pattern> diff=confdiff` lines are
+ * left untouched and reported as alreadyPresent.
+ */
+export declare function installGitDriver(opts: InstallOptions): InstallResult;

package/dist/gitdriver.js

@@ -0,0 +1,84 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+/** Default file patterns wired to the confdiff diff driver. */
+export const DEFAULT_PATTERNS = [
+    "*.json",
+    "*.yaml",
+    "*.yml",
+    "*.toml",
+    "*.ini",
+    "*.env",
+    "*.csv",
+    "*.tsv",
+    "*.xml",
+];
+/** The command git should run as the external diff driver. */
+export const DRIVER_COMMAND = "confdiff --git-diff-driver";
+function defaultGit(args) {
+    return execFileSync("git", args, { encoding: "utf8" }).trim();
+}
+/**
+ * Resolve the git attributes file to write pattern lines into.
+ * Global scope honours core.attributesFile, falling back to
+ * $XDG_CONFIG_HOME/git/attributes (or ~/.config/git/attributes).
+ * Local scope uses <repo>/.gitattributes.
+ */
+function resolveAttributesFile(global, git, cwd) {
+    if (!global)
+        return join(cwd, ".gitattributes");
+    let configured = "";
+    try {
+        configured = git(["config", "--global", "--get", "core.attributesFile"]);
+    }
+    catch {
+        configured = "";
+    }
+    if (configured) {
+        return configured.replace(/^~(?=\/|$)/, homedir());
+    }
+    const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+    return join(base, "git", "attributes");
+}
+/**
+ * Configure git to use confdiff as an external diff driver and wire the given
+ * file patterns to it. Idempotent: existing `<pattern> diff=confdiff` lines are
+ * left untouched and reported as alreadyPresent.
+ */
+export function installGitDriver(opts) {
+    const git = opts.git ?? defaultGit;
+    const cwd = opts.cwd ?? process.cwd();
+    const patterns = opts.patterns.length ? opts.patterns : DEFAULT_PATTERNS;
+    const configArgs = ["config"];
+    if (opts.global)
+        configArgs.push("--global");
+    git([...configArgs, "diff.confdiff.command", DRIVER_COMMAND]);
+    const attributesFile = resolveAttributesFile(opts.global, git, cwd);
+    const existing = existsSync(attributesFile) ? readFileSync(attributesFile, "utf8") : "";
+    const existingLines = new Set(existing.split(/\r?\n/).map((l) => l.trim()).filter(Boolean));
+    const added = [];
+    const alreadyPresent = [];
+    for (const p of patterns) {
+        const line = `${p} diff=confdiff`;
+        if (existingLines.has(line))
+            alreadyPresent.push(p);
+        else
+            added.push(p);
+    }
+    if (added.length) {
+        let out = existing;
+        if (out.length && !out.endsWith("\n"))
+            out += "\n";
+        out += added.map((p) => `${p} diff=confdiff`).join("\n") + "\n";
+        mkdirSync(dirname(attributesFile), { recursive: true });
+        writeFileSync(attributesFile, out);
+    }
+    return {
+        scope: opts.global ? "global" : "local",
+        attributesFile,
+        added,
+        alreadyPresent,
+        command: DRIVER_COMMAND,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { diff, type Change, type ChangeKind, type DiffOptions, type Path, formatPath, typeOf } from "./diff.js";
+export { parseContent, parseEnv, parseCsv, parseXml, keyRowsByColumn, detectFormat, sniff, type Format, type Value, } from "./parse.js";
+export { renderText, renderJson, type RenderOptions } from "./render.js";
+import { type DiffOptions, type Change } from "./diff.js";
+import { type Format } from "./parse.js";
+export interface CompareOptions extends DiffOptions {
+    formatA?: Format;
+    formatB?: Format;
+    filenameA?: string;
+    filenameB?: string;
+    /** For CSV inputs: match rows by this column instead of by position. */
+    csvKey?: string;
+}
+/** High-level helper: compare two raw strings of (possibly different) formats. */
+export declare function compare(a: string, b: string, opts?: CompareOptions): Change[];