Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
15.8 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Compare API reports and render the pull request's API changes.
 *
 * @input  the merge base's reports (built from the merge base, or as committed
 *         there when no build of it was kept), the reports generated from the
 *         head's build, and the head's committed reports, per package
 * @output added, changed, and removed rows per package, each with its
 *         signature and a usage example, plus how many rows the committed
 *         report is behind the head's build; and the advisory Markdown the
 *         pull request report embeds
 * @position scripts/api-report — evidence only: nothing here fails a check or
 *           decides acceptance (architecture:public-component-api INV24, INV13)
 */

/**
 * @typedef {object} Row
 * @property {string} entry - entry point (`.`, `./theme`) or a package-level section heading
 * @property {string} section - `Components`, `Types`, `Stylesheets`, …
 * @property {string} item - `component Button`, `var --color-accent`, …
 * @property {string|null} member - `size`, `inherits`, … or null for the item row
 * @property {string} line - the row as the report writes it
 */

/**
 * Split a report into rows keyed by entry point, section, item, and member.
 * @param {string|null|undefined} text
 * @returns {Map<string, Row>}
 */
export function parseReport(text) {
  const rows = new Map();
  let entry = '';
  let section = '';
  let fenced = false;
  let item = null;
  for (const line of (text ?? '').split('\n')) {
    if (line.startsWith('```')) {
      fenced = !fenced;
      item = null;
      continue;
    }
    if (!fenced) {
      const h2 = line.match(/^## (.+)$/);
      const h3 = line.match(/^### (.+)$/);
      if (h2) [entry, section] = [h2[1].replace(/`/g, ''), ''];
      else if (h3) section = h3[1];
      else if (/^(bin|stylesheet|asset|missing) /.test(line)) {
        const key = line.split(':')[0].split(' (')[0];
        rows.set(`${entry}\0${key}`, {
          entry,
          section: 'Entry point',
          item: key,
          member: null,
          line,
        });
      }
      continue;
    }
    if (!line.trim()) continue;
    if (!line.startsWith(' ')) {
      item = itemName(line);
      rows.set(uniqueKey(rows, `${entry}\0${section}\0${item}`), {
        entry,
        section,
        item,
        member: null,
        line,
      });
    } else if (item) {
      const member = memberName(line);
      rows.set(uniqueKey(rows, `${entry}\0${section}\0${item}\0${member}`), {
        entry,
        section,
        item,
        member,
        line: line.trim(),
      });
    }
  }
  for (const [key, row] of rows) ROW_KEY.set(row, key);
  return rows;
}

/** Each parsed row's key in its report, for matching rows across two diffs. */
const ROW_KEY = new WeakMap();

function itemName(line) {
  if (/^[\w$]+ \(/.test(line)) return line.split(' ')[0]; // `Name (./entry)` in an also-exported list
  const m = line.match(/^(\w+) ([^\s(:<=]+)(?: (\([^)]*\)))?/);
  if (!m) return line;
  // One custom property can come from two stylesheets, and one target class
  // from two components: their qualifier is part of the row's identity.
  return (m[1] === 'var' || m[1] === 'target') && m[3]
    ? `${m[1]} ${m[2]} ${m[3]}`
    : `${m[1]} ${m[2]}`;
}

/** A key no earlier row holds, so a repeated row is never dropped. */
function uniqueKey(rows, key) {
  let unique = key;
  for (let n = 2; rows.has(unique); n++) unique = `${key}\0#${n}`;
  return unique;
}

function memberName(line) {
  const t = line.trim();
  if (t.startsWith('inherits ')) return 'inherits';
  if (t.startsWith('overload ')) return t;
  const m = t.match(/^(?:prop )?([^\s?:(]+)/);
  return m ? m[1] : t;
}

/**
 * @param {string|null|undefined} base
 * @param {string} head
 * @returns {{added: Row[], changed: Array<Row & {before: string}>, removed: Row[]}}
 */
export function diffReports(base, head) {
  const a = parseReport(base);
  const b = parseReport(head);
  const added = [];
  const changed = [];
  const removed = [];
  // Every differing key before folding, so a caller can match single members.
  const keys = new Set();
  for (const [k, row] of b) {
    if (!a.has(k)) added.push(row);
    else if (a.get(k).line !== row.line) {
      const change = {...row, before: a.get(k).line};
      ROW_KEY.set(change, k);
      changed.push(change);
    } else continue;
    keys.add(k);
  }
  for (const [k, row] of a)
    if (!b.has(k)) {
      removed.push(row);
      keys.add(k);
    }
  // A wholly added or removed item reports once, not once per member.
  const fold = rows => {
    const items = new Set(
      rows
        .filter(r => !r.member)
        .map(r => `${r.entry}\0${r.section}\0${r.item}`),
    );
    return rows.filter(
      r => !r.member || !items.has(`${r.entry}\0${r.section}\0${r.item}`),
    );
  };
  return {added: fold(added), changed, removed: fold(removed), keys};
}

/**
 * A one-line usage example for a row.
 * @param {string} pkg
 * @param {Row} row
 * @returns {string}
 */
export function usageFor(pkg, row) {
  const spec = row.entry.startsWith('./') ? `${pkg}${row.entry.slice(1)}` : pkg;
  const [kind, name = row.item] = row.item.split(' ');
  // Package-level sections sit under their own `##` heading, held in `entry`.
  if (row.entry === 'Stylesheets') return `.my-scope { ${name}: …; }`;
  if (row.entry === 'Theme targets')
    return `defineTheme({components: {'${name}': {…}}})`;
  if (row.entry === 'Public attributes') return `[${name}] { … }`;
  if (row.entry === 'Reachable members tagged internal')
    return `import {${name}} from '${pkg}'`;
  if (row.section === 'Entry point')
    return kind === 'bin'
      ? `npx ${name.replace(/`/g, '')}`
      : `import '${spec}'`;
  if (kind === 'component') {
    if (!row.member || row.member === 'inherits') return `<${name} />`;
    // An overload line is another call shape of the component, not a prop.
    if (row.member.startsWith('overload ')) return `<${name} … />`;
    const literal = row.line.match(/'([^']+)'/);
    const value = literal
      ? `"${literal[1]}"`
      : /: boolean/.test(row.line)
        ? ''
        : '{…}';
    return `<${name} ${row.member}${value ? `=${value}` : ''} />`;
  }
  if (kind === 'hook' || kind === 'function')
    return `import {${name}} from '${spec}'; ${name}(…)`;
  if (kind === 'class')
    return `import {${name}} from '${spec}'; new ${name}(…)`;
  if (kind === 'interface' || kind === 'type' || kind === 'enum') {
    return row.member && row.member !== 'inherits'
      ? `import type {${name}} from '${spec}'; const x: ${name} = {${row.member}: …}`
      : `import type {${name}} from '${spec}'`;
  }
  return `import {${name}} from '${spec}'`;
}

/** The rows one report differs from another by, as the changes list them. */
const rowCount = ({added, changed, removed}) =>
  added.length + changed.length + removed.length;

/** The rows of a `diffReports` result, in one list. */
const rowsOf = ({added, changed, removed}) => [
  ...added,
  ...changed,
  ...removed,
];

/**
 * How many of the pull request's rows its committed report does not show,
 * counted as the pull request report counts them (a wholly added or removed
 * item is one row). Rows a report on main already lacked are not the pull
 * request's, and only a built surface of the merge base tells the two apart:
 * against the merge base's committed report, this counts none.
 */
function staleOwnRowCount({base, head, committed, baseSource, stale}) {
  if (!stale || base == null || baseSource === 'committed') return 0;
  const behind = diffReports(committed, head).keys;
  const own = diffReports(base, head);
  const whole = new Set([...own.added, ...own.removed].filter(r => !r.member));
  // A member or a changed item line matches by its own key; a wholly added
  // or removed item matches when any of its keys is behind.
  return rowsOf(own).filter(r => {
    const key = ROW_KEY.get(r);
    if (behind.has(key)) return true;
    return whole.has(r) && [...behind].some(k => k.startsWith(`${key}\0`));
  }).length;
}

/**
 * @param {Array<{pkg: string, base: string|null, head: string,
 *   committed: string|null, baseSource?: 'build'|'head'|'committed'}>} packages
 */
export function computeChanges(packages) {
  return packages
    .map(({pkg, base, head, committed, baseSource = 'committed'}) => {
      // With no report at the merge base there is nothing to compare: the
      // package's report is new, and every row would read as added.
      const baseline = base == null;
      const d = baseline
        ? {added: [], changed: [], removed: []}
        : diffReports(base, head);
      const stale = committed != null && committed !== head;
      return {
        pkg,
        baseline,
        baseSource,
        stale,
        // A stale report is one line in the PR report, not its rows.
        staleRows: stale ? rowCount(diffReports(committed, head)) : 0,
        staleOwnRows: staleOwnRowCount({
          base,
          head,
          committed,
          baseSource,
          stale,
        }),
        missing: committed == null,
        counts: {
          added: d.added.length,
          changed: d.changed.length,
          removed: d.removed.length,
        },
        rows: [
          ...d.added.map(r => ({change: 'added', ...r})),
          ...d.changed.map(r => ({change: 'changed', ...r})),
          ...d.removed.map(r => ({change: 'removed', ...r})),
        ].map(r => ({...r, usage: usageFor(pkg, r)})),
      };
    })
    .sort((x, y) => (x.pkg < y.pkg ? -1 : x.pkg > y.pkg ? 1 : 0));
}

/**
 * A GitHub Actions warning for each package whose public API this pull
 * request changed while its committed report stayed behind. It never fails
 * the job (architecture:public-component-api INV24); a report that was stale
 * before this pull request gets only the pull request report's line.
 * @param {ReturnType<typeof computeChanges>} changes
 * @param {(pkg: string) => string} reportFile the package's committed report path
 * @returns {string[]}
 */
export function staleReportWarnings(changes, reportFile) {
  return changes
    .filter(c => c.staleOwnRows > 0)
    .map(
      c =>
        `::warning file=${reportFile(c.pkg)},title=API report not regenerated::` +
        `This pull request changes ${plural(c.staleOwnRows, 'row')} of ${c.pkg}'s public API ` +
        `that its committed api-report.md does not show. Run pnpm api:report and commit the report.`,
    );
}

// The pull request comment has a size limit; a wide change lists its first rows.
const MAX_ROWS = 150;

/**
 * Literal text as a code span, for every string the report renders: no link
 * (GitHub autolinks a bare URL in plain text), no markup, no HTML. The pull
 * request's own build writes these strings and the comment is public. A pipe
 * is escaped so a table cell stays one cell; the fence is longer than any
 * backtick run inside.
 */
const code = value => {
  const text = String(value ?? '')
    .replace(/\s*[\r\n]+\s*/g, ' ')
    .replace(/\|/g, '\\|');
  if (text.trim() === '') return '';
  const longest = Math.max(
    0,
    ...(text.match(/`+/g) || []).map(run => run.length),
  );
  const fence = '`'.repeat(longest + 1);
  const pad = text.startsWith('`') || text.endsWith('`') ? ' ' : '';
  return `${fence}${pad}${text}${pad}${fence}`;
};
const count = value => (Number.isFinite(Number(value)) ? Number(value) : 0);
const where = r =>
  code([r.entry, r.section, r.item].filter(Boolean).join(' · '));
const short = pkg => code(String(pkg ?? '').replace(/^@astryxdesign\//, ''));

const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;

/**
 * The advisory API changes for the pull request report: one visible summary
 * line, with every row inside a closed disclosure.
 *
 * Changes from version 2 (each package carries `staleRows`) list only the
 * rows the pull request changes; a stale committed report is one line naming
 * how far behind it is. Version 1 changes render as they always did.
 * @param {ReturnType<typeof computeChanges>} changes
 * @returns {string} empty when nothing changed and every report is current
 */
export function renderChanges(changes) {
  const list = (Array.isArray(changes) ? changes : []).map(c => ({
    ...c,
    rows: Array.isArray(c?.rows) ? c.rows : [],
  }));
  if (list.some(c => typeof c?.staleRows === 'number'))
    return renderBuiltChanges(list);
  const touched = list.filter(
    c =>
      c.rows.length ||
      c.stale === true ||
      c.missing === true ||
      c.baseline === true,
  );
  if (!touched.length) return '';
  const parts = touched.map(c => {
    if (c.baseline === true && c.missing !== true)
      return `${short(c.pkg)} new report${c.stale ? ' (stale: run `pnpm api:report`)' : ''}`;
    const counts = c.rows.length
      ? ` +${count(c.counts?.added)} · ~${count(c.counts?.changed)} · −${count(c.counts?.removed)}`
      : ' no changes';
    const note =
      c.missing === true
        ? ' (report not committed: run `pnpm api:report`)'
        : c.stale === true
          ? ' (report stale: run `pnpm api:report`)'
          : '';
    return `${short(c.pkg)}${counts}${note}`;
  });
  return (
    [`**API changes:** ${parts.join('; ')}`, ...rowTable(touched)].join('\n') +
    '\n'
  );
}

/** The disclosure holding every row, or nothing without rows. */
function rowTable(packages) {
  const rows = packages.flatMap(c =>
    c.rows.map(r => ({...r, pkg: short(c.pkg)})),
  );
  const L = [];
  if (rows.length) {
    L.push(
      '',
      `<details><summary>${rows.length} API change${rows.length === 1 ? '' : 's'} (advisory)</summary>`,
      '',
      '| | Package | Where | Signature | Usage |',
      '| --- | --- | --- | --- | --- |',
      ...rows.slice(0, MAX_ROWS).map(r => {
        const sign =
          r.change === 'added' ? '+' : r.change === 'removed' ? '−' : '~';
        const sig =
          r.change === 'changed' && r.before != null
            ? `${code(r.before)} → ${code(r.line)}`
            : code(r.line);
        return `| ${sign} | ${r.pkg} | ${where(r)} | ${sig} | ${code(r.usage)} |`;
      }),
      ...(rows.length > MAX_ROWS
        ? [
            '',
            `…and ${rows.length - MAX_ROWS} more; run \`pnpm api:report\` and read the report diff.`,
          ]
        : []),
      '',
      '</details>',
    );
  }
  return L;
}

/**
 * Version 2: the summary names only the packages this pull request changes
 * (or whose report is new or missing); stale committed reports share one line.
 * @param {ReturnType<typeof computeChanges>} list
 */
function renderBuiltChanges(list) {
  const touched = list.filter(
    c => c.rows.length || c.missing === true || c.baseline === true,
  );
  const stale = list.filter(c => c.stale === true && c.missing !== true);
  if (!touched.length && !stale.length) return '';
  const parts = touched.map(c => {
    if (c.baseline === true && c.missing !== true)
      return `${short(c.pkg)} new report`;
    const counts = c.rows.length
      ? ` +${count(c.counts?.added)} · ~${count(c.counts?.changed)} · −${count(c.counts?.removed)}`
      : ' no changes';
    const missing =
      c.missing === true
        ? ' (report not committed: run `pnpm api:report`)'
        : '';
    // No build of the merge base was kept: rows a stale report at the merge
    // base carried may show here too.
    const committed =
      c.rows.length && c.baseSource === 'committed'
        ? " (against the merge base's committed report)"
        : '';
    return `${short(c.pkg)}${counts}${missing}${committed}`;
  });
  const L = [
    `**API changes:** ${parts.length ? parts.join('; ') : 'none in this pull request'}`,
  ];
  if (stale.length) {
    const behind = stale.map(c =>
      count(c.staleRows)
        ? `${short(c.pkg)} ${plural(count(c.staleRows), 'row')}`
        : short(c.pkg),
    );
    L.push(
      '',
      `Committed API report behind this build: ${behind.join(', ')}; run \`pnpm api:report\`.`,
    );
  }
  L.push(...rowTable(touched));
  return L.join('\n') + '\n';
}