package-lock-diff

#!/usr/bin/env node
/**
 * Copyright Trent Mick. Licensed under the MIT license.
 *
 * A command to attempt to sanely diff package-lock.json changes.
 * See "Usage:" string below or run `package-lock-diff -h` for usage info.
 *
 * -*- mode: js -*-
 * vim: expandtab:ts=4:sw=4
 */

const NAME = 'package-lock-diff';

const assert = require('assert/strict');
const {execFileSync} = require('child_process');
const fs = require('fs');
const path = require('path');
const dashdash = require('dashdash');

// Use `DEBUG=npm-tools ...` for debug output.
const debug = require('debug')(NAME);
debug.inspectOpts = {depth: 50, colors: true};

//---- globals, consts

const p = console.log;
const pkg = require('../package.json');
const OPTIONS = [
    {
        name: 'version',
        type: 'bool',
        help: `Print ${NAME} version and exit.`,
    },
    {
        names: ['help', 'h'],
        type: 'bool',
        help: 'Print this help and exit.',
    },
    {
        names: ['color'],
        type: 'bool',
        help: 'Color/style the diff output with ANSI codes.',
    },
    {
        names: ['no-color'],
        type: 'bool',
        help: 'Do not use ANSI codes for styling the output.',
    },
];

//---- support functions

function fail(msg) {
    console.error(`${NAME} error: ${msg}`);
    process.exit(2);
}

/**
 * Returns the git status for the given file path. The return object is:
 *      {
 *          xy: <2-char string described in the "Short Format" section of `git help status`
 *          path: <the file path relative to the repository root>
 *      }
 * If the file is unmodified in git, it returns (i.e. no "path" entry):
 *      {
 *          xy: '  '
 *      }
 *
 * The 'xy' for locally modified is ' M'.
 */
function gitStatus(fpath) {
    const stdout = execFileSync(
        'git',
        ['status', '--porcelain', '-z', path.basename(fpath)],
        {
            cwd: path.dirname(fpath),
            timeout: 5000,
            encoding: 'utf8',
        }
    );
    const status = {};
    if (stdout.length === 0) {
        status.xy = '  ';
    } else {
        status.xy = stdout.slice(0, 2);
        status.path = stdout.slice(3).split('\0')[0];
    }
    return status;
}

function gitShow(revision, fpath) {
    debug(`git show "$revision:${path.basename(fpath)}"`);
    return execFileSync(
        'git',
        ['show', `${revision}:${path.basename(fpath)}`],
        {
            cwd: path.dirname(fpath),
            timeout: 5000,
            encoding: 'utf8',
            maxBuffer: 10 * 1024 * 1024,
        }
    );
}

/**
 * Normalize a parsed package-lock object for comparison.
 *
 * - Drops fields that are irrelevant for `npm ci` usage, like "license",
 *   "engines", etc.
 * - Drops some fields that `npm ci` may *use*, but cannot reliably be used
 *   for diffing because common `npm install` actions result in them getting
 *   added or removed without a mechanism to control that that I'm aware of.
 *   E.g. "integrity" and "resolved" if it is a URL to
 *   "https://registry.npmjs.org".  Note that just removing this subset of
 *   "resolved" fields is probably not sufficient in general, but should be
 *   fine for *my* current cases.
 * - Drops the lockfileVersion=1 legacy "dependencies" top-level field.
 *   (WARNING: This *breaks* having a lockfileVersion=2 lock file that can be
 *   then used with older npm versions.)
 */
function normPackageLock(plock) {
    delete plock.dependencies;
    for (const val of Object.values(plock.packages)) {
        delete val.license;
        delete val.engines;
        delete val.workspaces;
        delete val.devDependencies;
        delete val.dependencies;
        delete val.peerDependencies;
        delete val.peerDependenciesMeta;
        delete val.optionalDependencies;
        delete val.deprecated;
        delete val.cpu;
        delete val.os;
        delete val.funding;
        delete val.bin;

        delete val.hasInstallScript;
        delete val.integrity;
        if (val.resolved) {
            try {
                const url = new URL(val.resolved);
                if (url.hostname === 'registry.npmjs.org') {
                    delete val.resolved;
                }
            } catch (_err) {}
        }
    }
    return plock;
}

/**
 * A one-line representation of a normalized value in the package-lock.json
 * "packages" section.
 */
function pkgRepr(subdir, pkg) {
    let repr = `${subdir}:`;
    if (pkg.name) {
        repr += ` ${pkg.name}@${pkg.version}`;
    } else if (pkg.version) {
        repr += ` ${pkg.version}`;
    }
    delete pkg.name;
    delete pkg.version;

    const extras = [];
    const keys = Object.keys(pkg).sort();
    for (let k of keys) {
        const v = pkg[k];
        if (typeof v === 'boolean') {
            assert.equal(
                v,
                true,
                'unexpected false value in package-lock "packages" section: ' +
                    pkg
            );
            extras.push(k);
        } else {
            extras.push(`${k}=${JSON.stringify(v)}`);
        }
    }
    if (extras.length) {
        repr += ` (${extras.join(', ')})`;
    }

    return repr;
}

/**
 * Emit a diff-like output that attempts to more meaningfully convey
 * package-lock.json changes than a line-by-line diff comparison. Liberties
 * are taken with the typical diff format.
 *
 * See: https://docs.npmjs.com/cli/v9/configuring-npm/package-lock-json
 *
 * Limitations:
 * - This only works with lockfileVersion=2 and above, and is only tested
 *   (at least so far) with lockfileVersion=2.
 */
function packageLockDiff({pathA, contentA, pathB, contentB}) {
    const plockA = normPackageLock(JSON.parse(contentA));
    // fs.writeFileSync('plockA', JSON.stringify(plockA, null, 2) + '\n', 'utf8');
    const plockB = normPackageLock(JSON.parse(contentB));
    // fs.writeFileSync('plockB', JSON.stringify(plockB, null, 2) + '\n', 'utf8');
    const hunks = []; // sort of like `diff` hunks, be we're not doing line-by-line

    // meta
    const metaFields = ['name', 'version', 'lockfileVersion'];
    const metaChanges = [];
    for (let field of metaFields) {
        if (plockA[field] !== plockB[field]) {
            metaChanges.push({
                a: `${field}: ${plockA[field]}`,
                b: `${field}: ${plockB[field]}`,
            });
        }
    }
    if (metaChanges.length > 0) {
        hunks.push({
            section: 'meta',
            changes: metaChanges,
        });
    }

    // packages
    // TODO: separate hunk for each top-level workspace?
    const subdirs = new Set();
    const changes = [];
    for (const [subdir, pkgA] of Object.entries(plockA.packages)) {
        subdirs.add(subdir);
        const reprA = pkgRepr(subdir, pkgA);
        const pkgB = plockB.packages[subdir];
        if (!pkgB) {
            changes.push({a: reprA});
        } else {
            const reprB = pkgRepr(subdir, pkgB);
            if (reprA !== reprB) {
                changes.push({a: reprA, b: reprB});
            }
        }
    }
    for (const [subdir, pkgB] of Object.entries(plockB.packages)) {
        if (subdirs.has(subdir)) {
            continue;
        }
        changes.push({b: pkgRepr(subdir, pkgB)});
    }
    if (changes.length > 1) {
        hunks.push({
            section: 'packages',
            changes,
        });
    }

    return {
        pathA,
        pathB,
        hunks,
    };
}

function shouldColorize(opts) {
    let colorize = Boolean(process.stdout.isTTY);
    if (
        typeof process.env.NO_COLOR === 'string' &&
        process.env.NO_COLOR.length > 0
    ) {
        colorize = false; // https://no-color.org/
    }
    opts._order.forEach((opt) => {
        if (opt.key === 'color') {
            colorize = true;
        } else if (opt.key === 'no_color') {
            colorize = false;
        }
    });
    return colorize;
}

// http://en.wikipedia.org/wiki/ANSI_escape_code#graphics
// Suggested colors (some are unreadable in common cases):
// - Good: cyan, yellow (limited use), bold, green, magenta, red
// - Bad: blue (not visible on cmd.exe), grey (same color as background on
//   Solarized Dark theme from <https://github.com/altercation/solarized>, see
//   issue #160)
var colors = {
    bold: [1, 22],
    italic: [3, 23],
    underline: [4, 24],
    inverse: [7, 27],
    white: [37, 39],
    grey: [90, 39],
    black: [30, 39],
    blue: [34, 39],
    cyan: [36, 39],
    green: [32, 39],
    magenta: [35, 39],
    red: [31, 39],
    yellow: [33, 39],
};

function stylizeWithColor(str, color) {
    if (!str) return '';
    var codes = colors[color];
    if (codes) {
        return '\x1b[' + codes[0] + 'm' + str + '\x1b[' + codes[1] + 'm';
    } else {
        return str;
    }
}

function stylizeWithoutColor(str, color) {
    return str;
}

//---- mainline

function main(argv) {
    var parser = dashdash.createParser({options: OPTIONS});
    try {
        var opts = parser.parse(argv);
    } catch (e) {
        fail(e.message);
    }

    if (opts.help) {
        var help = parser.help({includeEnv: true}).trimRight();
        console.log(`Diff package-lock.json.

Usage:
    package-lock-diff                   # diff local git changes to ./package-lock.json
    package-lock-diff <commit>          # diff between <commit> and local state of ./package-lock.json
    package-lock-diff <path-a> <path-b> # diff changes between the given package-lock.json paths

Options:
${help}`);
        process.exit(0);
    } else if (opts.version) {
        console.log(`${NAME} ${pkg.version}`);
        console.log(pkg.homepage);
        process.exit(0);
    }

    var stylize = shouldColorize(opts) ? stylizeWithColor : stylizeWithoutColor;

    let pathA;
    let contentA;
    let pathB;
    let contentB;
    if (opts._args.length === 0) {
        const fpath = './package-lock.json';
        if (!fs.existsSync(fpath)) {
            fail(`${fpath} does not exist`);
        }
        const status = gitStatus(fpath);
        if (status.xy === '  ') {
            debug(`there are no local changes to git file ${fpath}`);
            process.exit(0);
        } else if (status.xy === ' M') {
            pathA = `a/${status.path}`;
            contentA = gitShow('HEAD', fpath);
            pathB = `b/${status.path}`;
            contentB = fs.readFileSync(fpath, {encoding: 'utf8'});
        } else {
            fail(
                `don't know how to handle git status '${status.xy}' for ${fpath}`
            );
        }
    } else if (opts._args.length === 1) {
        const commitish = opts._args[0];
        const fpath = './package-lock.json';
        if (!fs.existsSync(fpath)) {
            fail(`${fpath} does not exist`);
        }
        pathA = `${fpath} (${commitish})`;
        contentA = gitShow(commitish, fpath);
        pathB = fpath;
        contentB = fs.readFileSync(fpath, {encoding: 'utf8'});
    } else if (opts._args.length === 2) {
        pathA = opts._args[0];
        contentA = fs.readFileSync(pathA, {encoding: 'utf8'});
        pathB = opts._args[1];
        contentB = fs.readFileSync(pathB, {encoding: 'utf8'});
    } else {
        fail(
            `incorrect number of arguments: args=${JSON.stringify(opts._args)}`
        );
    }

    const diff = packageLockDiff({pathA, contentA, pathB, contentB});
    if (diff.hunks.length > 0) {
        // console.dir(diff, {depth: 50});
        p(stylize(`package-lock-diff ${opts._args.join(' ')}`, 'bold'));
        p(stylize(`--- ${diff.pathA}`, 'bold'));
        p(stylize(`+++ ${diff.pathB}`, 'bold'));
        for (let hunk of diff.hunks) {
            p(stylize('@@ @@', 'cyan') + ' ' + hunk.section);
            for (let change of hunk.changes) {
                if (change.a && change.b) {
                    // Simple attempt at inner-line highlight of diffs.
                    // const changeIndeces = [];
                    const tokensA = change.a.split(/([: (),]+)/g);
                    let segmentsA = [stylize('- ', 'red')];
                    const tokensB = change.b.split(/([: (),]+)/g);
                    let segmentsB = [stylize('+ ', 'green')];
                    let i = 0;
                    for (; i < tokensA.length; i++) {
                        const tokenA = tokensA[i];
                        const tokenB = tokensB[i];
                        if (tokenA === tokenB) {
                            segmentsA.push(stylize(tokenA, 'red'));
                            if (tokenB != null) {
                                segmentsB.push(stylize(tokenB, 'green'));
                            }
                        } else {
                            segmentsA.push(
                                stylize(stylize(tokenA, 'red'), 'inverse')
                            );
                            if (tokenB != null) {
                                segmentsB.push(
                                    stylize(stylize(tokenB, 'green'), 'inverse')
                                );
                            }
                        }
                    }
                    for (let j = i; j < tokensB.length; j++) {
                        segmentsB.push(
                            stylize(stylize(tokensB[j], 'green'), 'inverse')
                        );
                    }
                    p(segmentsA.join(''));
                    p(segmentsB.join(''));
                } else if (change.a) {
                    p(stylize(`- ${change.a}`, 'red'));
                } else if (change.b) {
                    p(stylize(`+ ${change.b}`, 'green'));
                }
            }
        }
    }
}

if (require.main === module) {
    main(process.argv);
}