Skip to content

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

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

/**
 * @file Icon-set authoring writes (spec:AST-084 FR13): start a set and add
 * one of its own icon definitions in the local integration package. Every
 * file it reads or writes goes through here; it is imported only by the
 * `icon` subject's adapter (architecture:cli-surface INV21).
 *
 * @position api/icon — helper of api/icon/_adapter.mjs, read by
 *   api/icon/new-set and api/icon/new-definition
 */

import * as fs from 'node:fs';
import * as path from 'node:path';
import {AstryxError} from '../error.mjs';
import {logger} from '../logger.mjs';
import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
import {
  assertWithin,
  PathSafetyError,
  sanitizeName,
} from '../../foundation/fs/path-safety.mjs';
import {
  findLocalIntegrationManifestOrNull,
  IntegrationRootConflictError,
  patchIntegrationRoot,
} from '../../foundation/integrations/manifest-writer.mjs';
import {loadManifestObject} from '../../foundation/integrations/integrations.mjs';
import {assertContributionVisible} from '../../foundation/integrations/contribution-inventory.mjs';
import {
  IconSetAuthoringError,
  checkNewDefinition,
  definitionFile,
  findLocalIconSet,
  generatedModulePath,
  generatedModuleText,
  generatedOrigins,
  sameIconModule,
  generatedTypesPath,
  THEME_MAP_NAME,
  entryWiringNote,
  iconSetDataText,
  journalFile,
  librarySource,
  everyLibraryIcon,
  libraryIcons,
  libraryLooks,
  lookPositions,
  moduleNaming,
  nonIconExports,
  packageRootMoves,
  resolveIconSource,
  peerNote,
  typecheckNote,
  writeDefinitionFile,
  writeGeneratedIcons,
  writeIconSetData,
} from '../../foundation/discovery/icon-set-writer.mjs';
import {
  describedLooks,
  drawnLooks,
  resolveDefaultLook,
} from './_default-look.mjs';
import {shellArg} from '../../foundation/text/shell-arg.mjs';
import {
  hasLicenseNotice,
  licenseNoticeFix,
} from '../../foundation/discovery/icon-set-discovery.mjs';
import {astryxIconDefinitions} from '../../foundation/discovery/icon-definition-discovery.mjs';
import {suggestedIcons} from '../../foundation/discovery/icon-set-checks.mjs';
import {
  resolveProjectTypeScript,
  TYPESCRIPT_FIX,
} from '../../foundation/discovery/project-typescript.mjs';
import {
  KEBAB_NAME_RE,
  applyWrites,
  kebabToTitle,
  loadCurrentManifest,
  packageJsonUpdate,
  projectPath,
  receipt,
  resolvePackage,
} from '../integration/add-helpers.mjs';

/** Where a package's icon sets go when its manifest declares none. */
const DEFAULT_ICON_SETS_ROOT = './icon-sets';

/** Where an icon set's root is declared: an experimental manifest key. */
const ICON_SETS_ROOT_KEY = 'experimental.iconSets';

// ── Icon set ────────────────────────────────────────────────────────

/**
 * A single-quoted JavaScript string literal for any text.
 * @param {string} value
 */
function quoteJs(value) {
  return `'${value
    .replace(/\\/gu, '\\\\')
    .replace(/'/gu, "\\'")
    .replace(/\n/gu, '\\n')
    .replace(/\r/gu, '\\r')}'`;
}

/**
 * Write one icon set (spec:AST-084 FR1–FR3): `<root>/<name>/<name>.doc.mjs`,
 * a typed IconSetDoc, and a starter `<name>.icons.json` whose `module` is the
 * package itself, with no icons and an empty `map`. The set is valid and
 * discoverable; `integration check` then names every built-in icon
 * definition it still has to map.
 * @param {string} name  icon set name (kebab-case)
 * @param {{cwd?: string, dryRun?: boolean, from?: string, exclude?: string[] | string, variants?: string[] | string, defaultVariant?: string, displayName?: string, description?: string}} options
 * @returns {Promise<{type: 'integration.add', data: import('./icon.type.mjs').IconNewData}>}
 */
export async function addIconSet(name, options) {
  const {cwd = process.cwd(), dryRun = false, from} = options;
  const given = variantOptions(options);
  const exclude =
    typeof options.exclude === 'string'
      ? options.exclude
          .split(',')
          .map(each => each.trim())
          .filter(Boolean)
      : (options.exclude ?? []);
  if (exclude.length > 0 && from == null) {
    throw new AstryxError(
      '--exclude names library exports to leave out, so it needs --from.',
      undefined,
      ERROR_CODES.ERR_INVALID_OPTION,
    );
  }
  if (!KEBAB_NAME_RE.test(name)) {
    throw new AstryxError(
      `Invalid icon set name "${name}": use lowercase kebab-case starting with a letter.`,
      undefined,
      ERROR_CODES.ERR_INVALID_ARGUMENT,
    );
  }
  try {
    sanitizeName(name, {label: 'icon set name'});
  } catch (error) {
    if (error instanceof PathSafetyError) {
      throw new AstryxError(
        error.message,
        undefined,
        ERROR_CODES.ERR_INVALID_ARGUMENT,
      );
    }
    throw error;
  }

  const {packageDir, packageFile, pkg, owner, manifestFile, manifestExists} =
    resolvePackage(cwd);
  if (typeof pkg.name !== 'string' || pkg.name.trim() === '') {
    throw new AstryxError(
      'package.json has no name. An icon set imports its icons from its own package, so the package needs a name first.',
      undefined,
      ERROR_CODES.ERR_INVALID_ARGUMENT,
    );
  }
  const manifest = await loadCurrentManifest(manifestFile, manifestExists);
  const rootPath = manifest.experimental?.iconSets ?? DEFAULT_ICON_SETS_ROOT;
  /** @type {string} */
  let root;
  try {
    root = assertWithin(rootPath, packageDir, {
      label: 'experimental.iconSets root',
    });
  } catch (error) {
    if (error instanceof PathSafetyError) {
      throw new AstryxError(
        error.message,
        undefined,
        ERROR_CODES.ERR_PATH_TRAVERSAL,
      );
    }
    throw error;
  }

  try {
    await patchIntegrationRoot(packageDir, ICON_SETS_ROOT_KEY, rootPath, {
      dryRun: true,
      createIfMissing: true,
    });
  } catch (error) {
    if (error instanceof IntegrationRootConflictError) {
      throw new AstryxError(
        error.message,
        undefined,
        ERROR_CODES.ERR_INTEGRATION_ROOT_CONFLICT,
      );
    }
    throw error;
  }

  const setDir = assertWithin(name, root, {label: 'icon set directory'});
  const docFile = assertWithin(`${name}.doc.mjs`, setDir, {
    label: 'icon set descriptor',
  });
  const dataFile = assertWithin(`${name}.icons.json`, setDir, {
    label: 'icon set data file',
  });
  // Wrapping a library again refreshes the set's icons in place.
  if (from != null && fs.existsSync(docFile) && fs.existsSync(dataFile)) {
    return refreshIconSet(name, {
      cwd,
      dryRun,
      from,
      exclude,
      looks: given,
      describe: {
        displayName: options.displayName,
        description: options.description,
      },
      packageDir,
      rootPath,
      manifestPath: projectPath(path.relative(packageDir, manifestFile)),
    });
  }
  // Without --from, an existing set takes new variants, a default variant, a
  // display name or a description in place, and nothing else changes.
  if (
    from == null &&
    fs.existsSync(docFile) &&
    fs.existsSync(dataFile) &&
    (given != null ||
      options.displayName?.trim() ||
      options.description?.trim())
  ) {
    return redeclareIconSet(name, {
      cwd,
      dryRun,
      looks: given,
      describe: {
        displayName: options.displayName,
        description: options.description,
      },
      packageDir,
      rootPath,
      manifestPath: projectPath(path.relative(packageDir, manifestFile)),
    });
  }
  for (const file of [docFile, dataFile]) {
    if (fs.existsSync(file)) {
      throw new AstryxError(
        `Refusing to overwrite existing file ${projectPath(path.relative(packageDir, file))}.`,
        undefined,
        ERROR_CODES.ERR_FILE_EXISTS,
      );
    }
  }

  // The set's generated icons module, with its theme map, starts empty; with
  // --from, every component the library exports becomes an icon in it.
  const generated = `./${projectPath(path.relative(packageDir, path.join(setDir, `${name}.generated.js`)))}`;
  /** @type {Array<{id: string, export: string, words: string[]}>} */
  let icons = [];
  /** @type {Record<string, string>} */
  let map = {};
  /** @type {import('../../foundation/discovery/icon-set-writer.mjs').GeneratedIcon[]} */
  let exportsToWrite = [];
  /** @type {Array<{definition: string, icon: string, word: string}>} */
  let suggestions = [];
  /** @type {string[]} */
  let skipped = [];
  /** @type {ReturnType<typeof librarySource>} */
  let library = null;
  /** @type {{summary: import('../../foundation/discovery/icon-set-writer.mjs').LibraryLookSummary | null}} */
  const lookFound = {summary: null};
  // Without --from the set has no icons yet, so no look to match.
  let looks =
    from == null
      ? resolveDefaultLook({
          name,
          given,
          current: undefined,
          icons: 0,
          drawn: null,
          library: null,
        }).looks
      : null;
  if (from != null) {
    const source = await iconAuthoring(() =>
      resolveIconSource(from, {packageDir, pkg}),
    );
    const found = libraryIcons(source.file, {
      exclude,
      // The library's look words decide the default before any glyph is
      // picked, so each icon's export draws it.
      prefer: positions => {
        looks = resolveDefaultLook({
          name,
          given,
          current: undefined,
          icons: 0,
          drawn: null,
          library: {module: source.module, positions},
        }).looks;
        return looks ? [looks.default] : [];
      },
      module: source.module,
      progress: line => logger.warn(line),
      summary: each => {
        lookFound.summary = each;
      },
    });
    if (found.length === 0) {
      throw new AstryxError(
        `"${from}" exports no icon components this command can read. If its icons are data (objects or SVG strings), run \`astryx experimental icon new-set ${name}\`, declare an "adapter" in ${name}.icons.json, and run this command again; or add icons one at a time with \`astryx experimental icon add <Export> --from ${from} --set ${name}\`.`,
        undefined,
        ERROR_CODES.ERR_NOT_FOUND,
      );
    }
    icons = found.map(icon => ({
      id: icon.id,
      export: icon.name,
      words: [...new Set([...idWords(icon.id), ...icon.aliases])],
    }));
    map = exactDefinitionMap(icons, {});
    skipped = nonIconExports(source.file, {exclude});
    suggestions = definitionSuggestions(icons, map);
    library = librarySource(source.module, packageDir);
    exportsToWrite = found.map(icon => ({
      name: icon.name,
      from: source.module,
      source: icon.export,
      adapt: icon.adapt,
    }));
  }
  const data = {
    schemaVersion: /** @type {const} */ (1),
    module: pkg.name,
    ...(library
      ? {source: {package: library.package, version: library.version}}
      : {}),
    ...(exclude.length > 0 ? {exclude: [...new Set(exclude)].sort()} : {}),
    generated,
    ...(looks
      ? {variants: looks.variants, default: {variant: looks.default}}
      : {}),
    themeMap: THEME_MAP_NAME,
    map,
    icons,
  };
  const generatedText = await iconAuthoring(() =>
    generatedModuleText(packageDir, generated, null, data, exportsToWrite),
  );

  const displayName = options.displayName?.trim() || kebabToTitle(name);
  // The artwork license is the wrapped library's, else the package's own;
  // the author edits it when the artwork comes from elsewhere.
  const license =
    library?.license ??
    (typeof pkg.license === 'string' && pkg.license.trim() !== ''
      ? pkg.license
      : 'UNLICENSED');
  const docContents = [
    "/** @type {import('@astryxdesign/cli/authoring').IconSetDoc} */",
    'export default {',
    "  type: 'icon-set',",
    `  name: ${quoteJs(name)},`,
    `  displayName: ${quoteJs(displayName)},`,
    `  description: ${quoteJs(options.description?.trim() || `${displayName} icons.`)},`,
    '  maintained: true,',
    `  license: ${quoteJs(license)},`,
    '};',
    '',
  ].join('\n');
  const dataContents = iconSetDataText(data);

  /** @type {import('../integration/add-helpers.mjs').WritePlan[]} */
  const plans = [
    {path: docFile, contents: docContents, createOnly: true},
    {path: dataFile, contents: dataContents, createOnly: true},
  ];
  plans.push({
    path: assertWithin(generated, packageDir, {
      label: 'generated icons module',
    }),
    contents: generatedText.js,
    createOnly: true,
  });
  // The wrapped library's license notices travel with its artwork.
  for (const notice of library?.notices ?? []) {
    const target = assertWithin(notice, setDir, {label: 'license notice'});
    if (!library || fs.existsSync(target)) continue;
    plans.push({
      path: target,
      contents: fs.readFileSync(path.join(library.dir, notice), 'utf-8'),
      createOnly: true,
    });
  }
  const typesPath = generatedTypesPath(generated);
  if (typesPath && generatedText.dts != null) {
    plans.push({
      path: assertWithin(typesPath, packageDir, {
        label: 'generated icon types',
      }),
      contents: generatedText.dts,
      createOnly: true,
    });
  }
  const pkgUpdate = packageJsonUpdate(
    packageFile,
    rootPath,
    path.basename(manifestFile),
  );
  if (pkgUpdate != null) {
    plans.push({
      path: packageFile,
      contents: pkgUpdate.contents,
      createOnly: false,
      expectedOriginal: pkgUpdate.expectedOriginal,
    });
  }

  const writtenFiles = plans.map(p =>
    projectPath(path.relative(packageDir, p.path)),
  );
  const manifestPath = projectPath(path.relative(packageDir, manifestFile));

  let rootReceipt = {
    path: rootPath,
    created: !manifest.experimental?.iconSets,
  };
  if (!dryRun) {
    let rollback = () => {};
    // Every file this writes, the manifest included, is journaled first, so
    // a failure anywhere puts each back (AST-084 FR13).
    for (const plan of plans) journalFile(plan.path);
    journalFile(manifestFile);
    try {
      rollback = applyWrites(plans);
      rootReceipt = await patchIntegrationRoot(
        packageDir,
        ICON_SETS_ROOT_KEY,
        rootPath,
        {
          createIfMissing: true,
          verify: async () => {
            const m = await loadManifestObject(manifestFile, 'verify', {
              fresh: true,
            });
            const declared = m.experimental?.iconSets;
            if (!declared)
              throw new Error(
                'experimental.iconSets root not visible after writing.',
              );
            const setsRoot = assertWithin(declared, packageDir, {
              label: 'experimental.iconSets root',
            });
            await assertContributionVisible(
              {name: owner, iconSets: setsRoot},
              'icon-set',
              name,
            );
          },
        },
      );
    } catch (error) {
      rollback();
      if (error instanceof IntegrationRootConflictError) {
        throw new AstryxError(
          error.message,
          undefined,
          ERROR_CODES.ERR_INTEGRATION_ROOT_CONFLICT,
        );
      }
      if (error instanceof AstryxError) throw error;
      throw new AstryxError(
        `Failed to write icon-set contribution: ${error instanceof Error ? error.message : String(error)}`,
        undefined,
        ERROR_CODES.ERR_WRITE_FAILED,
      );
    }
  }
  if (rootReceipt.created && !writtenFiles.includes(manifestPath)) {
    writtenFiles.push(manifestPath);
  }
  const result = receipt(
    'icon-set',
    name,
    rootReceipt,
    manifestPath,
    writtenFiles,
    dryRun,
  );
  const missingNotice = noticeToAdd(
    library,
    packageDir,
    projectPath(path.relative(packageDir, setDir)),
  );
  {
    result.data.icons = icons.length;
    if (from != null) {
      result.data.mapped = Object.entries(map).map(([definition, icon]) => ({
        definition,
        icon,
      }));
      result.data.suggestions = suggestions;
    }
    // `integration check --strict` type-checks the set's typed doc files.
    const typescript = resolveProjectTypeScript([packageDir]);
    /** @type {Record<string, any>} */
    const packageAfter = pkgUpdate ? JSON.parse(pkgUpdate.contents) : pkg;
    result.data.notes = [
      // First, so a long receipt never hides it: the strict check needs it.
      ...(typescript?.ts
        ? []
        : [
            typescript
              ? `\`integration check --strict\` type-checks the set's doc files with this package's TypeScript, ${typescript.version}, which has no compiler API. ${TYPESCRIPT_FIX}`
              : "`integration check --strict` type-checks the set's doc files with TypeScript, which this package does not have: run `npm install -D typescript@6` (TypeScript 5.0 through 6).",
          ]),
      // What the package needs that the CLI leaves to its author
      // (architecture:cli-surface INV16), each as the exact change to make.
      ...[
        entryWiringNote(packageDir, packageAfter, generated),
        peerNote(packageAfter),
        typecheckNote(packageAfter),
      ].filter(note => note != null),
      ...(options.description?.trim()
        ? []
        : [
            `The set's description is a placeholder ("${displayName} icons."): apps and discover show it. Pass --description when you create a set, or edit ${projectPath(path.relative(packageDir, docFile))}.`,
          ]),
      ...(skipped.length > 0
        ? [
            `Left out ${skipped.length} exports that are not icons: ${skipped.slice(0, 12).join(', ')}${skipped.length > 12 ? ', …' : ''}.`,
          ]
        : []),
      ...(from != null && lookFound.summary == null
        ? [`Found ${icons.length} icons in ${from}.`]
        : []),
      ...(from != null && lookFound.summary != null
        ? lookNotes(lookFound.summary, icons.length, from, looks, name)
        : []),
      ...(missingNotice ? [missingNotice.note] : []),
      ...mappedNotes(map, name),
      ...suggestionNotes(suggestions, name),
      'Run `astryx integration check` to see the icon definitions still to map.',
    ];
    if (missingNotice) {
      result.data.licenseNoticeMissing = missingNotice.receipt;
    }
  }
  return result;
}

/**
 * The license notice the author must add when the wrapped library ships no
 * license file to copy and the package root has none. The CLI never writes
 * it: the license text is the author's to state. Null when nothing is
 * missing.
 * @param {{package: string, version: string, notices: string[]} | null} library
 * @param {string} packageDir
 * @param {string} setDir the set directory, from the package root
 * @returns {{note: string, receipt: {library: string, path: string}} | null}
 */
function noticeToAdd(library, packageDir, setDir) {
  if (!library || library.notices.length > 0) return null;
  if (hasLicenseNotice(packageDir)) return null;
  const named = `${library.package}@${library.version}`;
  return {
    note: `${named} ships no LICENSE or NOTICE file to copy, so the set has no license notice. ${licenseNoticeFix(setDir, named)}`,
    receipt: {library: named, path: `${setDir}/NOTICE`},
  };
}

/**
 * A set descriptor's source with `--display-name` and `--description`
 * written into its fields; the rest as it was.
 * @param {string} source
 * @param {{displayName?: string, description?: string}} describe
 */
function describedDoc(source, describe) {
  let out = source;
  for (const [field, value] of /** @type {const} */ ([
    ['displayName', describe.displayName],
    ['description', describe.description],
  ])) {
    if (!value?.trim()) continue;
    out = out.replace(
      new RegExp(`^(\\s*${field}:\\s*)(['"\`])(?:\\\\.|(?!\\2).)*\\2,?$`, 'mu'),
      (_, lead) => `${lead}${quoteJs(value.trim())},`,
    );
  }
  return out;
}

/**
 * `new-set <name>` without `--from` over an existing set: declare its
 * variants and default variant, and rewrite its display name and
 * description, in place. Its icons, map and generated module stay as they
 * are. A variant an icon still has must stay declared, and the default
 * variant is one no icon lists as an extra look. A set with icons keeps its
 * default variant: only a refresh with `--from` from a library whose names
 * name its looks moves it. With none declared,
 * its default is the look its icons' exports draw.
 * @param {string} name
 * @param {{cwd: string, dryRun: boolean, looks: Looks | null, describe: {displayName?: string, description?: string}, packageDir: string, rootPath: string, manifestPath: string}} options
 */
async function redeclareIconSet(
  name,
  {cwd, dryRun, looks: given, describe, packageDir, rootPath, manifestPath},
) {
  return iconAuthoring(async () => {
    const where = await findLocalIconSet(cwd, name);
    const {set} = where;
    const current = set.data.default?.variant;
    const drawn =
      given && set.data.icons.length > 0
        ? drawnLooks(set, packageDir, module =>
            libraryPositions(module, where, Boolean(set.data.adapter)),
          )
        : null;
    const {looks} = resolveDefaultLook({
      name,
      given,
      current,
      icons: set.data.icons.length,
      drawn,
      library: null,
    });
    if (looks) {
      const declared = new Set(looks.variants);
      const dropped = set.data.icons.flatMap(icon =>
        (icon.variants ?? [])
          .filter(each => !declared.has(each.variant))
          .map(each => `${icon.id} (${each.variant})`),
      );
      if (dropped.length > 0) {
        throw new AstryxError(
          `These icons still have a variant --variants leaves out: ${dropped.slice(0, 8).join(', ')}${dropped.length > 8 ? ', …' : ''}. Keep it in --variants.`,
          [
            {
              name: `--variants ${[...new Set([...looks.variants, ...set.data.icons.flatMap(icon => (icon.variants ?? []).map(each => each.variant))])].join(',')}`,
              reason: 'keep every variant an icon has',
            },
          ],
          ERROR_CODES.ERR_INVALID_ARGUMENT,
        );
      }
      const asExtra = set.data.icons
        .filter(icon =>
          (icon.variants ?? []).some(each => each.variant === looks.default),
        )
        .map(icon => icon.id);
      if (asExtra.length > 0) {
        throw new AstryxError(
          `"${looks.default}" can't be the default variant: ${asExtra.length} icons list it as another look (${asExtra.slice(0, 8).join(', ')}${asExtra.length > 8 ? ', …' : ''}), and each icon's own export draws the default.`,
          undefined,
          ERROR_CODES.ERR_INVALID_ARGUMENT,
        );
      }
    }
    const next = {
      ...set.data,
      ...(looks
        ? {variants: looks.variants, default: {variant: looks.default}}
        : {}),
    };
    const docFile = path.join(set.dir, `${set.name}.doc.mjs`);
    const docBefore = fs.readFileSync(docFile, 'utf-8');
    const docAfter = describedDoc(docBefore, describe);
    const dataChanged =
      iconSetDataText(next) !== fs.readFileSync(set.dataPath, 'utf-8');
    /** @type {string[]} */
    const files = [];
    if (dataChanged) {
      files.push(projectPath(path.relative(packageDir, set.dataPath)));
    }
    if (docAfter !== docBefore) {
      files.push(projectPath(path.relative(packageDir, docFile)));
    }
    if (!dryRun) {
      if (dataChanged) writeIconSetData(set, next);
      if (docAfter !== docBefore) {
        journalFile(docFile);
        fs.writeFileSync(docFile, docAfter);
      }
    }
    const result = receipt(
      'icon-set',
      name,
      {path: rootPath, created: false},
      manifestPath,
      files,
      dryRun,
    );
    result.data.icons = set.data.icons.length;
    result.data.updated = true;
    if (where.moduleUpdate) result.data.moduleUpdate = where.moduleUpdate;
    // A look the icons' own library draws comes from that library, so its
    // command runs as printed; any other look comes from a module the
    // author names.
    /** @param {string} variant */
    const fromFor = variant =>
      drawn != null && drawn.positions.some(each => each.has(variant))
        ? shellArg(drawn.module)
        : '<module>';
    const added = (looks?.variants ?? []).filter(
      variant =>
        variant !== looks?.default &&
        !(set.data.variants ?? []).includes(variant),
    );
    result.data.notes = [
      files.length === 0
        ? `Icon set "${name}" already declares this; nothing changed.`
        : `Updated icon set "${name}" in place; its icons, map and generated module are unchanged.`,
      ...(added.length > 0
        ? [
            `Give each icon its ${added.join(', ')} look: ${added.map(variant => `\`astryx experimental icon add --variant ${variant} --from ${fromFor(variant)} --all --set ${name}\``).join(', ')}, or one icon with \`astryx experimental icon add <Export> --from <module> --id <icon> --variant <name> --set ${name}\`.`,
          ]
        : []),
    ];
    return result;
  });
}

/**
 * The receipt's notes for a library that draws each icon in several looks
 * (a style, a size, a weight): what it found, the look the set took, and
 * how to add another look as a variant.
 * @param {import('../../foundation/discovery/icon-set-writer.mjs').LibraryLookSummary} summary
 * @param {number} count icons in the set
 * @param {string} from
 * @param {{variants: string[], default: string} | null} looks
 * @param {string} name the set's name
 * @returns {string[]}
 */
function lookNotes(summary, count, from, looks, name) {
  const described = describedLooks(summary.positions);
  const taken = [...summary.preferred].reverse().join(' ');
  const styles = new Set(summary.positions.flat());
  const others = (looks?.variants ?? []).filter(
    variant => variant !== looks?.default && styles.has(variant),
  );
  return [
    `Found ${count} icons in ${from}, each drawn in several looks (${described}) by ${summary.exports} exports. The set wraps each icon once, in the ${taken} look, named without the look words (\`x\`, \`XIcon\`).`,
    others.length > 0
      ? `Add the ${others.join(', ')} look${others.length > 1 ? 's' : ''} as variant${others.length > 1 ? 's' : ''}: ${others.map(variant => `\`astryx experimental icon add --variant ${variant} --from ${from} --all --set ${name}\``).join(', ')}.`
      : `To offer another look as a variant, declare it with \`astryx experimental icon new-set ${name} --variants ${[...summary.preferred].reverse()[0]},<look>\` (no --from: the set's icons stay as they are) and run \`astryx experimental icon add --variant <look> --from ${from} --all --set ${name}\`.`,
  ];
}

/**
 * An icon's words from its id: each part, leaving out a bare number
 * (`volume-2` is `volume`) unless the id is only numbers.
 * @param {string} id
 */
function idWords(id) {
  const parts = id.split('-');
  const named = parts.filter(part => !/^[0-9]+$/u.test(part));
  return named.length > 0 ? named : parts;
}

/** @param {string} name a camelCase definition name, as a kebab id */
const definitionId = name =>
  name.replace(/([a-z0-9])([A-Z])/gu, '$1-$2').toLowerCase();

/**
 * The `map` entries an exact name gives: each Astryx definition whose name
 * is an icon's id (`delete` → icon `delete`). A word alone never maps: a
 * library's `trash` may not mean what a template's delete means, so it is a
 * suggestion ({@link definitionSuggestions}). Entries the map already has are
 * kept.
 * @param {Array<{id: string}>} icons
 * @param {Record<string, string>} map
 */
function exactDefinitionMap(icons, map) {
  const ids = new Set(icons.map(icon => icon.id));
  /** @type {Record<string, string>} */
  const next = {...map};
  for (const {doc} of astryxIconDefinitions().definitions) {
    if (next[doc.name]) continue;
    const id = definitionId(doc.name);
    if (ids.has(id)) next[doc.name] = id;
  }
  return next;
}

/**
 * The icons each still-unmapped Astryx definition might map to
 * ({@link suggestedIcons}). Never written; the author chooses with
 * `astryx experimental icon map <definition> <icon>`.
 * @param {Array<{id: string, words: string[]}>} icons
 * @param {Record<string, string>} map
 * @returns {Array<{definition: string, icon: string, word: string}>}
 */
function definitionSuggestions(icons, map) {
  const set = {data: {icons, map}};
  return astryxIconDefinitions()
    .definitions.map(each => each.doc)
    .filter(doc => !map[doc.name])
    .flatMap(doc =>
      suggestedIcons(set, doc).map(each => ({definition: doc.name, ...each})),
    )
    .sort((a, b) =>
      a.definition < b.definition ? -1 : a.definition > b.definition ? 1 : 0,
    );
}

/**
 * The receipt's note for the suggestions, if any.
 * @param {Array<{definition: string, icon: string}>} suggestions
 * @param {string} name the set's name
 */
function suggestionNotes(suggestions, name) {
  if (suggestions.length === 0) return [];
  const count = new Set(suggestions.map(each => each.definition)).size;
  return [
    `${count} unmapped icon definitions have possible icons (listed under Suggestions; nothing was written for them). Check each meaning, then map the ones that fit: \`astryx experimental icon map <definition> <icon> --set ${name}\`.`,
  ];
}

/**
 * The receipt's note for the entries an exact name wrote, if any.
 * @param {Record<string, string>} map
 * @param {string} name the set's name
 */
function mappedNotes(map, name) {
  const count = Object.keys(map).length;
  if (count === 0) return [];
  return [
    `${count} icon definitions were mapped because an icon has their exact name (listed under Mapped by name). A library can draw another meaning under the same name, such as a backspace key named delete: check each, and remap with \`astryx experimental icon map <definition> <icon> --set ${name}\`.`,
  ];
}

/** @typedef {import('./_default-look.mjs').Looks} Looks */

/** A variant name: lower-kebab, such as `outline` or `mini-solid`. */
const VARIANT_NAME_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;

/**
 * The variants and default variant `--variants` and `--default-variant`
 * declare, or null when neither is given. Unless named, `default` is the
 * first variant until {@link resolveDefaultLook} decides it.
 * @param {{variants?: string[] | string, defaultVariant?: string}} options
 * @returns {Looks | null}
 */
function variantOptions(options) {
  const given =
    typeof options.variants === 'string'
      ? options.variants.split(',')
      : options.variants;
  const variants = [
    ...new Set((given ?? []).map(each => each.trim()).filter(Boolean)),
  ];
  const chosen = options.defaultVariant?.trim();
  if (variants.length === 0) {
    if (chosen) {
      throw new AstryxError(
        "--default-variant names one of the set's variants, so it needs --variants.",
        [
          {
            name: `--variants ${chosen},<other>`,
            reason: 'declare the variants',
          },
        ],
        ERROR_CODES.ERR_INVALID_OPTION,
      );
    }
    return null;
  }
  for (const variant of variants) {
    if (!VARIANT_NAME_RE.test(variant)) {
      throw new AstryxError(
        `Invalid variant name "${variant}": use lower-kebab, such as outline or solid.`,
        undefined,
        ERROR_CODES.ERR_INVALID_ARGUMENT,
      );
    }
  }
  if (chosen && !variants.includes(chosen)) {
    throw new AstryxError(
      `--default-variant "${chosen}" is not one of --variants (${variants.join(', ')}).`,
      variants.map(each => ({
        name: `--default-variant ${each}`,
        reason: 'a declared variant',
      })),
      ERROR_CODES.ERR_INVALID_ARGUMENT,
    );
  }
  return {variants, default: chosen || variants[0], named: Boolean(chosen)};
}

/**
 * The look positions of a library the set's generated module names, or
 * null when it can't be read.
 * @param {string} module
 * @param {{packageDir: string, pkg: Record<string, any>}} where
 * @param {boolean} adapter
 * @returns {Array<Set<string>> | null}
 */
function libraryPositions(module, where, adapter) {
  try {
    const source = resolveIconSource(module, where);
    return moduleNaming(source.file, {
      adapter,
      module,
      progress: line => logger.warn(line),
    }).positions;
  } catch {
    return null;
  }
}

/**
 * Run an icon-set authoring step, turning its errors into AstryxErrors.
 * @template T
 * @param {() => T | Promise<T>} step
 * @returns {Promise<T>}
 */
async function iconAuthoring(step) {
  try {
    return await step();
  } catch (error) {
    if (error instanceof IconSetAuthoringError) {
      throw new AstryxError(
        error.message,
        error.suggestions,
        /** @type {any} */ (ERROR_CODES)[error.code] ??
          ERROR_CODES.ERR_INVALID_ARGUMENT,
      );
    }
    if (error instanceof PathSafetyError) {
      throw new AstryxError(
        error.message,
        undefined,
        ERROR_CODES.ERR_PATH_TRAVERSAL,
      );
    }
    throw error;
  }
}

/**
 * Whether an id is one an id rule derives from a library glyph: the glyph id,
 * or its library export, broken into words another way (`squares-2-x2` for
 * `squares-2x2`, `glyph-eye` for `glyphEye`). Any other id is the author's.
 * @param {string} id
 * @param {{id: string, export: string}} glyph
 */
function derivedId(id, glyph) {
  const flat = (/** @type {string} */ text) =>
    text.toLowerCase().replace(/[^a-z0-9]/gu, '');
  return [glyph.id, glyph.export, glyph.export.replace(/Icon$/u, '')]
    .map(flat)
    .includes(flat(id));
}

/**
 * Keep the root moves that give each root export to one export of the set.
 * A root export that an export of the set already reads, or that an earlier
 * move takes, stays where it is. The icon that would move keeps its own file,
 * and its variants stay with it. Returns the kept moves and the ids of the
 * icons that stay (with `(<variant>)` for a variant that stays).
 * @param {{data: {module: string, icons: Array<{id: string, export: string, module?: string, variants?: Array<{variant: string, export: string}>}>}}} set
 * @param {Map<string, {module: string, source: string}>} origins
 * @param {string} root
 * @param {Map<string, {source: string, from: string}>} moves
 */
function claimRootMoves(set, origins, root, moves) {
  /** @type {Map<string, {source: string, from: string}>} */
  const kept = new Map();
  /** @type {string[]} */
  const skipped = [];
  const claimed = new Set(
    [...origins.values()]
      .filter(origin => sameIconModule(origin.module, root))
      .map(origin => origin.source),
  );
  for (const icon of set.data.icons) {
    if ((icon.module ?? set.data.module) !== set.data.module) continue;
    const own = moves.get(icon.export);
    const origin = origins.get(icon.export);
    const readsRoot = origin != null && sameIconModule(origin.module, root);
    if (own) {
      if (claimed.has(own.source)) {
        skipped.push(icon.id);
        continue;
      }
      claimed.add(own.source);
      kept.set(icon.export, own);
    } else if (!readsRoot) continue;
    for (const each of icon.variants ?? []) {
      const move = moves.get(each.export);
      if (!move) continue;
      if (claimed.has(move.source)) {
        skipped.push(`${icon.id} (${each.variant})`);
        continue;
      }
      claimed.add(move.source);
      kept.set(each.export, move);
    }
  }
  skipped.sort();
  return {moves: kept, skipped};
}

/**
 * Wrap a library into an existing set again: its icons are replaced by what
 * the library exports now (an icon whose words the author extended keeps
 * them), the generated module gains the new exports, `map` keeps every entry
 * whose icon still exists, and the receipt names the entries that lost theirs.
 * @param {string} name
 * @param {{cwd: string, dryRun: boolean, from: string, exclude: string[], looks: Looks | null, describe: {displayName?: string, description?: string}, packageDir: string, rootPath: string, manifestPath: string}} options
 */
async function refreshIconSet(
  name,
  {
    cwd,
    dryRun,
    from,
    exclude,
    looks: given,
    describe,
    packageDir,
    rootPath,
    manifestPath,
  },
) {
  return iconAuthoring(async () => {
    const where = await findLocalIconSet(cwd, name);
    const {set} = where;
    const current = set.data.default?.variant;
    const source = resolveIconSource(from, where);
    // Exports left out before stay out; --exclude adds to them.
    const excluded = [
      ...new Set([...(set.data.exclude ?? []), ...exclude]),
    ].sort();
    const everyIcon = everyLibraryIcon(source.file, {
      adapter: Boolean(set.data.adapter),
      exclude: excluded,
      module: source.module,
      progress: line => logger.warn(line),
    });
    const libraryLookPositions = lookPositions(everyIcon.map(icon => icon.id));
    // The look the icons from this library draw now decides whether a named
    // default moves them.
    const {looks, moved} = resolveDefaultLook({
      name,
      given,
      current,
      icons: set.data.icons.length,
      drawn: drawnLooks(set, packageDir, () => libraryLookPositions, {
        module: source.module,
      }),
      library: {module: source.module, positions: libraryLookPositions},
    });
    if (looks) {
      const asExtra = set.data.icons
        .filter(icon =>
          (icon.variants ?? []).some(each => each.variant === looks.default),
        )
        .map(icon => icon.id);
      if (asExtra.length > 0) {
        throw new AstryxError(
          `"${looks.default}" can't be the default variant: ${asExtra.length} icons list it as another look (${asExtra.slice(0, 8).join(', ')}${asExtra.length > 8 ? ', …' : ''}), and each icon's own export draws the default.`,
          undefined,
          ERROR_CODES.ERR_INVALID_ARGUMENT,
        );
      }
    }

    // A refresh changes only the icons the refreshed module supplies: those
    // the generated module re-exports or adapts from it. Every other icon
    // (your own `./` artwork, another library's) is kept as it is, with its
    // map entries and variants.
    const generatedBefore = generatedModulePath(set, packageDir);
    const origins = generatedOrigins(packageDir, generatedBefore);
    // A refresh from a package root also supplies the exports that read one
    // file of that package, when the root exports the same icon. They move to
    // the root import, so the set has one import style.
    const {moves: rootMoves, skipped: skippedMoves} = claimRootMoves(
      set,
      origins,
      source.module,
      packageRootMoves(
        origins,
        source,
        everyIcon.map(icon => icon.export),
        where,
      ),
    );
    /** @param {string} name the set's export */
    const libraryExportOf = name =>
      rootMoves.get(name)?.source ?? origins.get(name)?.source;
    /** @param {{export: string, module?: string}} icon */
    const suppliedHere = icon => {
      if ((icon.module ?? set.data.module) !== set.data.module) return false;
      if (rootMoves.has(icon.export)) return true;
      const origin = origins.get(icon.export);
      return origin != null && sameIconModule(origin.module, source.module);
    };
    const supplied = set.data.icons.filter(suppliedHere);
    const others = set.data.icons.filter(icon => !suppliedHere(icon));
    // An existing icon is the same icon when the library still exports it:
    // its identity is the library export its generated module re-exports
    // (`HiSquares2X2Icon`, or the root export a per-file icon moves to), then
    // its public export, then its id. Ids and public names are derived, and a
    // newer rule may spell them differently (`squares-2-x2` is now
    // `squares-2x2`); an icon matched this way keeps its public export byte
    // for byte, every field it had (its variants, the words the author added,
    // its module), and its map entries. The same rule holds on every refresh,
    // so a second refresh changes nothing the first one wrote.
    const moving = new Set(supplied.filter(icon => rootMoves.has(icon.export)));
    const byId = new Map(supplied.map(icon => [icon.id, icon]));
    const byExport = new Map(supplied.map(icon => [icon.export, icon]));
    const bySource = new Map(
      supplied.map(icon => [libraryExportOf(icon.export), icon]),
    );
    // One icon per glyph. A look the set already wraps keeps its icon and id.
    // A new glyph comes in once, in the preferred look. A new default variant
    // moves each glyph's icon to that look.
    const preferred = looks?.default ?? current;
    const {icons: looksOf} = libraryLooks(
      everyIcon,
      preferred ? [preferred] : [],
    );
    const iconByExport = new Map(everyIcon.map(icon => [icon.export, icon]));
    /** @type {string[]} the set's exports whose statement now names another look */
    const repicked = [];
    /** @type {Map<string, (typeof supplied)[number]>} the new look's export → the icon it now draws */
    const repickedBy = new Map();
    const found = looksOf.flatMap(icon => {
      const wrapped = (icon.looks ?? []).filter(look => bySource.has(look));
      if (wrapped.length === 0) return [icon];
      return wrapped.map(look => {
        const prior = /** @type {(typeof supplied)[number]} */ (
          bySource.get(look)
        );
        // A moved icon is the glyph its root export draws, whatever its id.
        const sameGlyph = moving.has(prior) || prior.id === icon.id;
        if (moved && sameGlyph && !bySource.has(icon.export)) {
          repicked.push(prior.export);
          repickedBy.set(icon.export, prior);
          return icon;
        }
        const own = /** @type {(typeof everyIcon)[number]} */ (
          iconByExport.get(look)
        );
        // Read by the glyph's id when the set already names it so.
        return prior.id === icon.id
          ? {...own, id: icon.id, name: icon.name}
          : own;
      });
    });
    /** @param {{export: string}} glyph */
    const resolvedPrior = glyph =>
      repickedBy.get(glyph.export) ?? bySource.get(glyph.export) ?? null;
    // An icon its library export already gives to one glyph is never given to
    // a second glyph by name or id: that glyph is left out.
    const resolved = new Set(found.map(resolvedPrior).filter(Boolean));
    const takenIds = new Set(others.map(icon => icon.id));
    const takenExports = new Set(others.map(icon => icon.export));
    /** @type {string[]} library icons left out: an icon of the set has the id or name */
    const shadowed = [];
    /** @type {Map<string, string>} old id → new id */
    const renames = new Map();
    /** @type {Map<string, string>} the library export → the set's export */
    const publicName = new Map();
    const fromLibrary = found.flatMap(icon => {
      const byOrigin = resolvedPrior(icon);
      const byName = byOrigin
        ? null
        : (byExport.get(icon.name) ?? byId.get(icon.id) ?? null);
      const prior = byOrigin ?? (resolved.has(byName) ? null : byName);
      const name = prior?.export ?? icon.name;
      if (
        !prior &&
        (byName || takenIds.has(icon.id) || takenExports.has(name))
      ) {
        shadowed.push(icon.id);
        return [];
      }
      publicName.set(icon.export, name);
      if (prior && byOrigin && !derivedId(prior.id, icon)) {
        return [
          {
            ...prior,
            words: [...new Set([...(prior.words ?? []), ...icon.aliases])],
          },
        ];
      }
      if (prior && prior.id !== icon.id) renames.set(prior.id, icon.id);
      // The words its old id gave are the old rule's, not the author's.
      const oldIdWords =
        prior && prior.id !== icon.id ? new Set(idWords(prior.id)) : new Set();
      return [
        {
          ...(prior ?? {}),
          id: icon.id,
          export: name,
          words: [
            ...new Set([
              ...idWords(icon.id),
              ...icon.aliases,
              ...(prior?.words ?? []).filter(word => !oldIdWords.has(word)),
            ]),
          ],
        },
      ];
    });
    const icons = [...fromLibrary, ...others];
    // An icon is listed under `moved` when it or one of its variants moves.
    /** @type {Array<{id: string, from: string, to: string}>} */
    const movedIcons = [];
    /** @type {import('../../foundation/discovery/icon-set-writer.mjs').GeneratedIcon[]} */
    const movedVariants = [];
    for (const icon of fromLibrary) {
      const variantMoves = (icon.variants ?? []).filter(each =>
        rootMoves.has(each.export),
      );
      for (const each of variantMoves) {
        const move = /** @type {{source: string, from: string}} */ (
          rootMoves.get(each.export)
        );
        movedVariants.push({
          name: each.export,
          from: source.module,
          source: move.source,
          adapt: iconByExport.get(move.source)?.adapt ?? false,
        });
      }
      const from = (
        rootMoves.get(icon.export) ?? rootMoves.get(variantMoves[0]?.export)
      )?.from;
      if (from) movedIcons.push({id: icon.id, from, to: source.module});
    }
    movedIcons.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
    // The icons this module supplied that it no longer exports: they leave
    // the set and its generated module, and the receipt names them.
    // Each is named for why it left: `--exclude` (or the data file's
    // `exclude`) names its library export, or the library no longer exports
    // it.
    const excludedNames = new Set(excluded);
    const keptExports = new Set(fromLibrary.map(each => each.export));
    const gone = supplied.filter(icon => !keptExports.has(icon.export));
    const isExcluded = (/** @type {{export: string}} */ icon) =>
      excludedNames.has(libraryExportOf(icon.export) ?? '') ||
      excludedNames.has(icon.export);
    const goneExcluded = gone.filter(isExcluded);
    const goneMissing = gone.filter(icon => !isExcluded(icon));
    const excludedIds = new Set(goneExcluded.map(icon => icon.id));
    const ids = new Set(icons.map(icon => icon.id));
    /** @type {Record<string, string>} */
    const kept = {};
    // The data file's `map` names only icons in the set (its parser refuses
    // anything else), so each lost entry's icon is one of these.
    /** @type {{excluded: string[], missing: string[]}} */
    const lost = {excluded: [], missing: []};
    for (const [definition, id] of Object.entries(set.data.map ?? {})) {
      const now = renames.get(id) ?? id;
      if (ids.has(now)) kept[definition] = now;
      else if (excludedIds.has(id)) {
        lost.excluded.push(`${definition} -> "${id}"`);
      } else lost.missing.push(`${definition} -> "${id}"`);
    }
    const generated = generatedModulePath(set, packageDir);
    const library = librarySource(source.module, packageDir);
    const map = exactDefinitionMap(icons, kept);
    const suggestions = definitionSuggestions(icons, map);
    const next = {
      ...set.data,
      ...(library
        ? {source: {package: library.package, version: library.version}}
        : {}),
      ...(excluded.length > 0 ? {exclude: excluded} : {}),
      generated,
      ...(looks
        ? {variants: looks.variants, default: {variant: looks.default}}
        : {}),
      ...(set.data.themeMap ? {} : {themeMap: THEME_MAP_NAME}),
      map,
      icons,
    };
    /** @type {string[]} */
    const files = [];
    const dataChanged =
      iconSetDataText(next) !== fs.readFileSync(set.dataPath, 'utf-8');
    // --display-name and --description rewrite the descriptor's fields.
    const docFile = path.join(set.dir, `${set.name}.doc.mjs`);
    const docBefore = fs.readFileSync(docFile, 'utf-8');
    let docAfter = describedDoc(docBefore, describe);
    // A refresh that first records the library as the set's source does what
    // `new-set --from` does: the descriptor takes the library's license, but
    // only over the value `new-set` wrote by default (the package's license,
    // or UNLICENSED), never over one the author chose. Either way the
    // receipt names both values.
    /** @type {string | null} */
    let licenseNote = null;
    if (library?.license && !set.data.source) {
      const license = library.license;
      const licenseRe = /^(\s*license:\s*)(['"`])((?:\\.|(?!\2).)*)\2,?$/mu;
      const current = licenseRe.exec(docBefore)?.[3] ?? null;
      const packageLicense =
        typeof where.pkg.license === 'string' && where.pkg.license.trim() !== ''
          ? where.pkg.license
          : 'UNLICENSED';
      const docRel = projectPath(path.relative(packageDir, docFile));
      if (current === license) {
        // Already the library's.
      } else if (current == null || current === packageLicense) {
        docAfter = docAfter.replace(
          licenseRe,
          (_, lead) => `${lead}${quoteJs(license)},`,
        );
        licenseNote = `The set's license in ${docRel} changed from "${current ?? '(none)'}" to "${license}", the license of ${library.package}, whose artwork it now wraps. Edit it if the artwork's license differs.`;
      } else {
        licenseNote = `The set's license in ${docRel} stays "${current}", which you set; ${library.package} is licensed "${license}". Change it if the artwork is the library's.`;
      }
    }
    if (docAfter !== docBefore) {
      files.push(projectPath(path.relative(packageDir, docFile)));
    }
    // The library's license notices travel with its artwork, as new-set
    // copies them: each one the set directory does not have yet.
    const libraryDir = library?.dir ?? '';
    const notices = (library?.notices ?? [])
      .map(notice => ({
        notice,
        target: assertWithin(notice, set.dir, {label: 'license notice'}),
      }))
      .filter(({target}) => !fs.existsSync(target));
    for (const {target} of notices) {
      files.push(projectPath(path.relative(packageDir, target)));
    }
    if (!dryRun) {
      const rewritten = found
        .map(icon => ({
          name: publicName.get(icon.export) ?? icon.name,
          from: source.module,
          source: icon.export,
          adapt: icon.adapt,
        }))
        .filter(icon => publicName.has(icon.source))
        .concat(movedVariants);
      const rewrittenNames = new Set(rewritten.map(icon => icon.name));
      const written = writeGeneratedIcons(
        packageDir,
        generated,
        next,
        rewritten,
        // The icons the library no longer exports leave the module too; a
        // renamed icon keeps its export. An icon moved to the new default
        // look keeps its export, which now names that look. An export moved
        // to the root is written again with the root import. Every other
        // export stays as it is, because the data file still lists it.
        [
          ...gone.map(icon => icon.export),
          ...repicked,
          ...[...rootMoves.keys()].filter(name => rewrittenNames.has(name)),
        ],
      );
      files.push(...written.files);
      try {
        writeIconSetData(set, next);
        // The descriptor last: the command's journal puts it back with the
        // rest if anything after it fails (AST-084 FR13).
        for (const {notice, target} of notices) {
          journalFile(target);
          fs.writeFileSync(
            target,
            fs.readFileSync(path.join(libraryDir, notice)),
          );
        }
        if (docAfter !== docBefore) {
          journalFile(docFile);
          fs.writeFileSync(docFile, docAfter);
        }
      } catch (error) {
        written.undo();
        throw error;
      }
    }
    if (dataChanged) {
      files.push(projectPath(path.relative(packageDir, set.dataPath)));
    }
    const result = receipt(
      'icon-set',
      name,
      {path: rootPath, created: false},
      manifestPath,
      files,
      dryRun,
    );
    result.data.icons = icons.length;
    result.data.refreshed = true;
    if (where.moduleUpdate) result.data.moduleUpdate = where.moduleUpdate;
    // Every entry an exact name gives, kept or new, so a refresh lists
    // them for review again.
    const byName = Object.fromEntries(
      Object.entries(map).filter(
        ([definition, id]) =>
          !(definition in kept) || id === definitionId(definition),
      ),
    );
    result.data.mapped = Object.entries(byName).map(([definition, icon]) => ({
      definition,
      icon,
    }));
    result.data.suggestions = suggestions;
    if (renames.size > 0) {
      result.data.renamed = [...renames].map(([from, to]) => ({from, to}));
    }
    if (movedIcons.length > 0) result.data.moved = movedIcons;
    const missingNotice = hasLicenseNotice(set.dir)
      ? null
      : noticeToAdd(
          library,
          packageDir,
          projectPath(path.relative(packageDir, set.dir)),
        );
    if (missingNotice) {
      result.data.licenseNoticeMissing = missingNotice.receipt;
    }
    result.data.notes = [
      ...(licenseNote ? [licenseNote] : []),
      ...(missingNotice ? [missingNotice.note] : []),
      ...(renames.size > 0
        ? [
            `${renames.size} icons have a new id under this release's id rule, and keep their map entries, variants, and words: ${[...renames].map(([from, to]) => `${from} -> ${to}`).join(', ')}.`,
          ]
        : []),
      ...(movedIcons.length > 0
        ? [
            `${movedIcons.length} icons now import from ${source.module} instead of one file each, and keep their ids, exports, map entries, variants, and words: ${movedIcons.map(each => each.id).join(', ')}.`,
          ]
        : []),
      ...mappedNotes(byName, name),
      ...suggestionNotes(suggestions, name),
      ...(goneMissing.length > 0
        ? [
            `${goneMissing.length} icons the library no longer exports were removed from the set: ${goneMissing.map(icon => icon.id).join(', ')}.`,
          ]
        : []),
      ...(lost.missing.length > 0
        ? [
            `These map entries named those icons and were removed: ${lost.missing.join(', ')}.`,
          ]
        : []),
      ...(goneExcluded.length > 0
        ? [
            `Left out by --exclude, and removed from the set: ${goneExcluded.map(icon => icon.id).join(', ')}.`,
          ]
        : []),
      ...(lost.excluded.length > 0
        ? [
            `These map entries named icons --exclude left out and were removed: ${lost.excluded.join(', ')}.`,
          ]
        : []),
      ...(shadowed.length > 0
        ? [
            `Left out ${shadowed.length} library icons whose id or name an icon of the set already has: ${shadowed.join(', ')}.`,
          ]
        : []),
      ...(skippedMoves.length > 0
        ? [
            `${skippedMoves.length} icons stay on their own file, because another icon of the set already reads the same export of ${source.module}: ${skippedMoves.join(', ')}.`,
          ]
        : []),
      astryxIconDefinitions().definitions.every(({doc}) => map[doc.name])
        ? 'Every Astryx icon definition is mapped.'
        : 'Run `astryx integration check` to see the icon definitions still to map.',
    ];
    return result;
  });
}

// ── Icon definition ─────────────────────────────────────────────────

/**
 * Add one of an icon set's own icon definitions (AST-084):
 * `<set>/definitions/<name>.doc.mjs`, a typed IconDefinitionDoc, and, with
 * `icon`, the set's `map` entry for it. A name Astryx already has is refused:
 * map to Astryx's definition instead.
 * @param {string} name camelCase definition name
 * @param {{cwd?: string, dryRun?: boolean, set?: string, description?: string, words?: string[] | string, icon?: string}} options
 * @returns {Promise<{type: 'integration.add', data: import('./icon.type.mjs').IconNewData}>}
 */
export async function addIconDefinition(name, options) {
  const {
    cwd = process.cwd(),
    dryRun = false,
    set: selector,
    description,
    icon,
  } = options;
  const words =
    typeof options.words === 'string'
      ? options.words.split(',')
      : options.words;
  return iconAuthoring(async () => {
    const where = await findLocalIconSet(cwd, selector);
    const {packageDir, set} = where;
    const doc = checkNewDefinition(set, {name, description, words});
    const file = definitionFile(set, doc.name);
    if (fs.existsSync(file)) {
      throw new AstryxError(
        `Refusing to overwrite existing file ${projectPath(path.relative(packageDir, file))}.`,
        undefined,
        ERROR_CODES.ERR_FILE_EXISTS,
      );
    }
    if (icon != null && !set.data.icons.some(each => each.id === icon)) {
      throw new AstryxError(
        `Icon set "${set.name}" has no icon "${icon}".`,
        set.data.icons
          .map(each => each.id)
          .filter(id => id.includes(icon) || icon.includes(id))
          .slice(0, 5)
          .map(id => ({name: id, reason: 'an icon in this set'})),
        ERROR_CODES.ERR_NOT_FOUND,
      );
    }
    const files = [projectPath(path.relative(packageDir, file))];
    if (icon != null)
      files.push(projectPath(path.relative(packageDir, set.dataPath)));
    if (!dryRun) {
      const undo = writeDefinitionFile(set, doc);
      let undoMap = () => {};
      if (icon != null) {
        try {
          undoMap = writeIconSetData(
            set,
            {...set.data, map: {...(set.data.map ?? {}), [doc.name]: icon}},
            {extraDefinitions: [doc.name]},
          );
        } catch (error) {
          undo();
          throw error;
        }
      }
      // Discovery reads the set, its new definition included, or every
      // write is undone: the data file first, then the definition.
      try {
        await findLocalIconSet(cwd, set.name);
      } catch (error) {
        undoMap();
        undo();
        throw error;
      }
    }
    const result = receipt(
      'icon-definition',
      doc.name,
      {
        path: `./${projectPath(path.relative(packageDir, where.root))}`,
        created: false,
      },
      projectPath(
        path.relative(
          packageDir,
          findLocalIntegrationManifestOrNull(packageDir) ??
            path.join(packageDir, 'astryx.integration.mjs'),
        ),
      ),
      files,
      dryRun,
    );
    // Only a new definition with an icon writes the data file.
    if (icon != null && where.moduleUpdate) {
      result.data.moduleUpdate = where.moduleUpdate;
    }
    return result;
  });
}