scripts/diff.ts

/* This file is a part of @mdn/browser-compat-data
 * See LICENSE file for more information. */

import chalk from 'chalk-template';
import deepDiff, { Diff } from 'deep-diff';
import esMain from 'es-main';
import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';

import { query } from '../utils/index.js';
import { SupportStatement, Identifier, BrowserName } from '../types/types.js';

import { getMergeBase, getFileContent, getGitDiffStatuses } from './lib/git.js';
import mirror from './build/mirror.js';

interface Contents {
  base: string;
  head: string;
}

interface DiffItem {
  name: string;
  description: string;
}

/**
 * Get contents from base and head commits
 * Note: This does not detect renamed files
 * @param baseCommit Base commit
 * @param basePath Base path
 * @param headCommit Head commit
 * @param headPath Head path
 * @returns The contents of both commits
 */
const getBaseAndHeadContents = (
  baseCommit: string,
  basePath: string,
  headCommit: string,
  headPath: string,
): Contents => {
  const base = JSON.parse(getFileContent(baseCommit, basePath));
  const head = JSON.parse(getFileContent(headCommit, headPath));
  return { base, head };
};

/**
 * Returns a formatted string of before-and-after changes
 * @param lhs Left-hand (before) side
 * @param rhs Right-hand (after) side
 * @returns Formatted string
 */
const stringifyChange = (lhs: any, rhs: any): string =>
  `${JSON.stringify(lhs)} → ${JSON.stringify(rhs)}`;

/**
 * Perform mirroring on specified diff statement
 * @param diff The diff to perform mirroring on
 * @param diff.base The diff to perform mirroring on
 * @param diff.head The diff to perform mirroring on
 * @param contents The contents to mirror from
 * @param contents.base The contents to mirror from
 * @param contents.head The contents to mirror from
 * @param path The feature path to mirror
 * @param direction Whether to mirror 'base' or 'head'
 */
const doMirror = (
  diff: { base: SupportStatement; head: SupportStatement },
  contents: { base: Identifier; head: Identifier },
  path: string[],
  direction: 'base' | 'head',
): void => {
  const browser = path[path.length - 1] as BrowserName;
  const dataPath = path.slice(0, path.length - 3).join('.');
  const data = contents[direction];

  diff[direction] = mirror(browser, query(dataPath, data).__compat.support);
};

/**
 * Describe the diff in text form (internal function)
 * @param diffItem The diff to describe
 * @param contents The contents of the diff
 * @returns A human-readable diff description
 */
const describeByKind = (
  diffItem: Diff<string, string>,
  contents: Contents,
): string => {
  const diff = { base: (diffItem as any).lhs, head: (diffItem as any).rhs };

  // Handle mirroring
  let doesMirror = '';
  if (diff.base === 'mirror') {
    doesMirror = 'No longer mirrors';
    doMirror(
      diff,
      contents as any as { base: Identifier; head: Identifier },
      diffItem.path as string[],
      'base',
    );
  } else if (diff.head === 'mirror') {
    doesMirror = 'Now mirrors';
    doMirror(
      diff,
      contents as any as { base: Identifier; head: Identifier },
      diffItem.path as string[],
      'head',
    );
  }

  switch (diffItem.kind) {
    case 'N':
      return 'added';
    case 'D':
      return 'deleted';
    case 'A':
    case 'E':
      return `edited (${stringifyChange(diff.base, diff.head)})${
        doesMirror && ` - ${doesMirror}`
      }`;
    default:
      return '';
  }
};

/**
 * Describe the diff in text form
 * @param diffItem The diff to describe
 * @param contents The contents of the diff
 * @returns A human-readable diff description
 */
const describeDiffItem = (
  diffItem: Diff<string, string>,
  contents: Contents,
): DiffItem => {
  const path = (diffItem.path as string[]).join('.');
  if (path.includes('.__compat.')) {
    const [name, member] = path.split('.__compat.');
    if (path.endsWith('.notes') && diffItem.kind === 'E') {
      return { name, description: `${member} is edited (prose change)` };
    }
    return {
      name,
      description: `${member} is ${describeByKind(diffItem, contents)}`,
    };
  }
  return {
    name: (diffItem.path as string[]).slice(0, -1).join('.'),
    description: `${path} is ${describeByKind(diffItem, contents)}`,
  };
};

/**
 * Merge diff together as a map
 * @param items Diff items to merge
 * @returns A map of the diff items
 */
const mergeAsMap = (items: DiffItem[]): Map<string, string> => {
  const map = new Map();
  for (const item of items) {
    const descriptions = map.get(item.name) || [];
    descriptions.push(item.description);
    map.set(item.name, descriptions);
  }
  return map;
};

/**
 * Get the diffs as a map
 * @param base Base ref
 * @param head Head ref
 * @returns A map of the diff items
 */
const getDiffs = (base: string, head = ''): Map<string, string> => {
  const namedDescriptions: { name: string; description: string }[] = [];
  for (const status of getGitDiffStatuses(base, head)) {
    if (!status.headPath.endsWith('.json') || !status.headPath.includes('/')) {
      continue;
    }

    // Note that A means Added for git while it means Array for deep-diff
    if (status.value === 'A' || status.value === 'D') {
      namedDescriptions.push({
        name: status.basePath.replace(/\//g, '.').slice(0, -5), // trim file extension
        description: status.value === 'A' ? 'Newly added' : 'Entirely removed',
      });
    } else {
      const contents = getBaseAndHeadContents(
        base,
        status.basePath,
        head,
        status.headPath,
      );
      const diff = deepDiff.diff(contents.base, contents.head);
      if (diff) {
        namedDescriptions.push(
          ...diff.map((item) => describeDiffItem(item, contents)),
        );
      }
    }
  }
  return mergeAsMap(namedDescriptions);
};

if (esMain(import.meta)) {
  const { argv } = yargs(hideBin(process.argv)).command(
    '$0 [base] [head]',
    'Print a formatted diff for changes between base and head commits',
    (yargs) => {
      yargs
        .positional('base', {
          describe:
            'The base commit; may be commit hash or other git ref (e.g. "origin/main")',
          type: 'string',
          default: 'origin/main',
        })
        .positional('head', {
          describe:
            'The head commit that changes are applied to; may be commit hash or other git ref (e.g. "origin/main")',
          type: 'string',
          default: 'HEAD',
        });
    },
  );

  const { base, head } = argv as any;
  for (const [key, values] of getDiffs(getMergeBase(base, head), head)) {
    console.log(chalk`{bold ${key}}:`);
    for (const value of values) {
      console.log(` → ${value}`);
    }
  }
}