@astryxdesign/cli 0.7.11 → 0.7.12-canary.ccb4a6d

package/api/icon/add/add.mjs

@@ -31,6 +31,7 @@ import {
   astryxIconDefinitions,
   authoring,
   checkNewDefinition,
+  definitionNameFromInput,
   closestNames,
   findLocalIconSet,
   iconIdOf,
@@ -40,12 +41,19 @@ import {
   generatedNamesOf,
   generatedOrigins,
   iconModulePackage,
-  iconNaming,
   localSourceNote,
   definitionNameOf,
   libraryIcons,
-  modulePrefix,
+  moduleNaming,
+  iconNamingWithoutLook,
+  iconNaming,
+  iconExportName,
+  sameIconModule,
+  splitLook,
   variantExportName,
+  answeringMatches,
+  checkVariantLook,
+  drawnLooks,
   rankIcons,
   resolveIconSource,
   setModuleNote,
@@ -56,6 +64,8 @@ import {
   refuseOutsideProject,
 } from '../_adapter.mjs';
 import {passed, refuseIgnoredPairs} from '../_options.mjs';
+import {logger} from '../../logger.mjs';
+import {shellArg} from '../../../foundation/text/shell-arg.mjs';
 
 /** The lowest score a definition match needs: an exact word or name. */
 const FIT_FLOOR = 80;
@@ -79,7 +89,7 @@ export async function iconAdd(exportName, options) {
     from,
     set: selector,
     definition: givenDefinition,
-    newDefinition,
+    newDefinition: givenNewDefinition,
     description,
     words,
     useDefault = false,
@@ -88,6 +98,11 @@ export async function iconAdd(exportName, options) {
     all = false,
   } = options ?? {};
   refuseOutsideProject(cwd, 'experimental icon add', 'the icon-set package');
+  // The docs' kebab-case (`ai-helper`) names the same new definition.
+  const newDefinition =
+    givenNewDefinition == null
+      ? undefined
+      : definitionNameFromInput(givenNewDefinition);
   // `--all` adds a declared variant to existing icons, so it names no icon
   // and maps nothing; a description and words describe only a new
   // definition (spec:AST-042 FR5).
@@ -177,14 +192,21 @@ export async function iconAdd(exportName, options) {
     const generated = generatedModulePath(set, packageDir);
     const module = set.data.module;
     // A library prefix every icon export shares (`feather` in `featherEye`)
-    // is left out of the id and the set's export name, as the bulk wrap does.
-    // A ./ path is the author's own files, named as written: never a library
-    // prefix (`CheckDouble` and `CheckDoubleSolid` share `check`).
-    const shared =
+    // is left out of the id and the set's export name, as the bulk wrap does,
+    // and so are the look words a library's names end in (`Outline24WGHT500`
+    // in `XOutline24WGHT500Icon`). A ./ path is the author's own files, named
+    // as written: never a library prefix (`CheckDouble` and
+    // `CheckDoubleSolid` share `check`).
+    const libraryNaming =
       useDefault || source.module.startsWith('./')
-        ? []
-        : modulePrefix(source.file, {adapter: Boolean(set.data.adapter)});
+        ? {prefix: [], positions: []}
+        : moduleNaming(source.file, {
+            adapter: Boolean(set.data.adapter),
+            module: source.module,
+            progress: line => logger.warn(line),
+          });
     const nameWords = iconIdOf(exportName).split('-');
+    const shared = libraryNaming.prefix;
     const prefix =
       shared.length > 0 &&
       nameWords.length > shared.length &&
@@ -199,11 +221,32 @@ export async function iconAdd(exportName, options) {
       sourceExport,
     );
     const known = set.data.icons.find(each => already.includes(each.export));
-    const naming = known
+    const glyph = known
       ? {id: known.id, name: known.export}
-      : iconNaming(exportName, prefix);
-    const id = givenId ?? naming.id;
+      : iconNamingWithoutLook(exportName, {
+          prefix,
+          positions: libraryNaming.positions,
+        });
     const asVariant = variant != null;
+    // The set may already export the glyph's name for another export of the
+    // library (its outline look, when this is the filled one). This export
+    // then keeps its look words in its id and name, or takes its name from
+    // --id, and the listing offers it as a variant of that icon instead.
+    const origin = generatedOrigins(packageDir, generated).get(glyph.name);
+    const glyphTaken =
+      !known &&
+      !asVariant &&
+      origin != null &&
+      !(
+        sameIconModule(origin.module, source.module) &&
+        origin.source === sourceExport
+      );
+    const naming = !glyphTaken
+      ? glyph
+      : givenId != null
+        ? {id: givenId, name: nameFromId(givenId)}
+        : iconNaming(exportName, prefix);
+    const id = givenId ?? naming.id;
     // The name the set exports it as: `<Name>Icon`, or for a variant the
     // icon's name with the variant's name.
     const baseIcon = set.data.icons.find(each => each.id === id);
@@ -219,7 +262,20 @@ export async function iconAdd(exportName, options) {
     }
 
     if (definition == null && newDefinition == null && !asVariant) {
-      return definitionMatches(set, exportName, from, id);
+      return definitionMatches(set, exportName, from, id, {
+        useDefault,
+        id: givenId,
+        look:
+          glyphTaken && origin != null
+            ? lookVariantOf(
+                iconNaming(exportName, prefix).id,
+                iconNaming(origin.source, prefix).id,
+                libraryNaming.positions,
+                set,
+              )
+            : null,
+        glyphId: glyph.id,
+      });
     }
 
     /** @type {{name: string, description: string, words: string[]} | null} */
@@ -250,7 +306,7 @@ export async function iconAdd(exportName, options) {
             }),
           ),
           {
-            name: `--new-definition ${definition} --description '<what it is for>' --words a,b`,
+            name: `--new-definition ${definitionNameFromInput(definition)} --description '<what it is for>' --words a,b`,
             reason: 'add it as your own definition',
           },
         ],
@@ -262,6 +318,15 @@ export async function iconAdd(exportName, options) {
     const icons = set.data.icons.map(each => ({...each}));
     const existing = icons.find(each => each.id === id);
     if (asVariant) {
+      checkVariantLook({
+        set,
+        variant,
+        module: source.module,
+        positions: libraryNaming.positions,
+        drawn: drawnLooks(set, packageDir, each =>
+          sameIconModule(each, source.module) ? libraryNaming.positions : null,
+        ),
+      });
       if (!existing) {
         throw new AstryxError(
           `Icon set "${set.name}" has no icon "${id}" to add a variant to. Add the icon first, or pass --id.`,
@@ -275,6 +340,18 @@ export async function iconAdd(exportName, options) {
           ERROR_CODES.ERR_NOT_FOUND,
         );
       }
+      const own = generatedOrigins(packageDir, generated).get(existing.export);
+      if (
+        own != null &&
+        own.source === sourceExport &&
+        sameIconModule(own.module, source.module)
+      ) {
+        throw new AstryxError(
+          `"${sourceExport}" is icon "${id}"'s own export, which draws its default look, so it can't be its ${variant} variant too.`,
+          undefined,
+          ERROR_CODES.ERR_INVALID_ARGUMENT,
+        );
+      }
       const variants = [...(existing.variants ?? [])];
       const same = variants.find(each => each.export === setName);
       if (!same) {
@@ -394,9 +471,13 @@ export async function iconAdd(exportName, options) {
  * @param {string} exportName
  * @param {string} from
  * @param {string} id
+ * @param {{useDefault?: boolean, id?: string, look?: string | null, glyphId?: string}} passed the
+ *   options the author passed, repeated in each listed command so it runs as
+ *   printed; `look`, when the set already has an icon for the export's
+ *   glyph (`glyphId`): the variant it is of that icon
  * @returns {import('../icon.type.mjs').IconDefinitionMatchesResponse}
  */
-function definitionMatches(set, exportName, from, id) {
+function definitionMatches(set, exportName, from, id, passed = {}) {
   const astryx = astryxIconDefinitions().definitions.map(each => ({
     doc: each.doc,
     source: /** @type {const} */ ('astryx'),
@@ -432,14 +513,19 @@ function definitionMatches(set, exportName, from, id) {
   /** @type {Map<string, {score: number, reason: string}>} */
   const best = new Map();
   for (const query of queries) {
-    for (const match of rankIcons([asSet], query)) {
+    for (const match of answeringMatches(rankIcons([asSet], query))) {
       const prior = best.get(match.export);
       if (!prior || match.score > prior.score) {
         best.set(match.export, {score: match.score, reason: match.reason});
       }
     }
   }
-  const base = `astryx experimental icon add ${exportName} --from ${from}`;
+  const base = [
+    `astryx experimental icon add ${exportName} --from ${shellArg(from)}`,
+    `--set ${shellArg(set.name)}`,
+    ...(passed.useDefault ? ['--default'] : []),
+    ...(passed.id != null ? [`--id ${shellArg(passed.id)}`] : []),
+  ].join(' ');
   const matches = all
     .filter(({doc}) => best.has(doc.name))
     .map(({doc, source}) => {
@@ -463,6 +549,15 @@ function definitionMatches(set, exportName, from, id) {
     )
     .slice(0, MATCH_LIMIT);
   const fits = matches.some(match => match.score >= FIT_FLOOR);
+  const asLook =
+    passed.look && passed.glyphId
+      ? [
+          `astryx experimental icon add ${exportName} --from ${shellArg(from)}`,
+          `--set ${shellArg(set.name)}`,
+          ...(passed.useDefault ? ['--default'] : []),
+          `--id ${passed.glyphId} --variant ${passed.look}`,
+        ].join(' ')
+      : null;
   const name = id.replace(/-([a-z0-9])/gu, (_, c) => c.toUpperCase());
   return {
     type: 'icon.definitionMatches',
@@ -474,6 +569,7 @@ function definitionMatches(set, exportName, from, id) {
       newDefinition: fits
         ? null
         : `${base} --new-definition ${/^[a-z]/u.test(name) ? name : `icon${name}`} --description '<what the icon is for>' --words <word>,<word>`,
+      ...(asLook ? {variant: asLook} : {}),
     },
   };
 }
@@ -502,29 +598,34 @@ async function addVariantForAll({cwd, from, selector, variant}) {
   }
   const where = await findLocalIconSet(cwd, selector);
   const {packageDir, set} = where;
-  const declared = set.data.variants ?? [];
-  if (!declared.includes(variant)) {
-    throw new AstryxError(
-      `Icon set "${set.name}" declares no variant "${variant}"${declared.length > 0 ? ` (it declares ${declared.join(', ')})` : ''}. Declare it first.`,
-      [
-        {
-          name: `astryx experimental icon new-set ${set.name} --from <its library> --variants ${[...new Set([...(declared.length > 0 ? declared : ['<default>']), variant])].join(',')}`,
-          reason: 'declare the variants',
-        },
-      ],
-      ERROR_CODES.ERR_INVALID_ARGUMENT,
-    );
-  }
-  if (set.data.default?.variant === variant) {
-    throw new AstryxError(
-      `"${variant}" is the set's default variant: each icon's own export already draws it.`,
-      undefined,
-      ERROR_CODES.ERR_INVALID_ARGUMENT,
-    );
-  }
   const source = resolveIconSource(from, where);
-  const found = libraryIcons(source.file, {adapter: Boolean(set.data.adapter)});
+  // In a library that draws each icon in several looks, the variant is the
+  // glyph's look the variant's name picks (`filled`), and an icon is known
+  // by any look of its glyph.
+  /** @type {Array<Set<string>>} */
+  let positions = [];
+  const found = libraryIcons(source.file, {
+    adapter: Boolean(set.data.adapter),
+    prefer: [variant],
+    module: source.module,
+    progress: line => logger.warn(line),
+    summary: each => {
+      positions = each.positions.map(words => new Set(words));
+    },
+  });
+  checkVariantLook({
+    set,
+    variant,
+    module: source.module,
+    positions,
+    drawn: drawnLooks(set, packageDir, each =>
+      sameIconModule(each, source.module) ? positions : null,
+    ),
+  });
   const byId = new Map(found.map(each => [each.id, each]));
+  const byLook = new Map(
+    found.flatMap(each => (each.looks ?? []).map(look => [look, each])),
+  );
   // An existing icon is known by the library export it re-exports, then by
   // its own export, then by its id: an icon whose id or name an older rule
   // wrote (`squares-2-x2`, `Squares2X2Icon`) still meets its variant
@@ -548,6 +649,8 @@ async function addVariantForAll({cwd, from, selector, variant}) {
   const already = [];
   /** @type {string[]} */
   const missing = [];
+  /** @type {string[]} icons whose own export is the one the variant picks */
+  const own = [];
   const icons = set.data.icons.map(icon => {
     const origin = origins.get(icon.export);
     if (origin && iconModulePackage(origin.module) !== variantPackage) {
@@ -557,6 +660,7 @@ async function addVariantForAll({cwd, from, selector, variant}) {
       origin && origin.source !== 'default' ? origin.source : undefined;
     const match =
       (librarySource ? byLibraryExport.get(librarySource) : undefined) ??
+      (librarySource ? byLook.get(librarySource) : undefined) ??
       byName.get(icon.export) ??
       byId.get(icon.id);
     if (!match) {
@@ -567,6 +671,21 @@ async function addVariantForAll({cwd, from, selector, variant}) {
       missing.push(icon.id);
       return icon;
     }
+    // A glyph the library draws in no look of that name has no variant,
+    // and neither has one whose own export is the one that look picks.
+    if (match.look && !match.look.includes(variant)) {
+      missing.push(icon.id);
+      return icon;
+    }
+    if (
+      match.export === librarySource &&
+      origin != null &&
+      sameIconModule(origin.module, source.module)
+    ) {
+      own.push(icon.id);
+      missing.push(icon.id);
+      return icon;
+    }
     const name = variantExportName(icon.export, variant);
     const variants = [...(icon.variants ?? [])];
     if (variants.some(each => each.variant === variant)) {
@@ -583,6 +702,29 @@ async function addVariantForAll({cwd, from, selector, variant}) {
     added.push(icon.id);
     return {...icon, variants};
   });
+  if (
+    added.length === 0 &&
+    already.length === 0 &&
+    own.length > 0 &&
+    set.data.default?.variant == null
+  ) {
+    // The module is the one the icons' own exports come from, so the
+    // variant names the look they draw now: the set's undeclared default.
+    const variants = [
+      variant,
+      ...(set.data.variants ?? []).filter(each => each !== variant),
+    ];
+    throw new AstryxError(
+      `"${source.module}" is the module the ${own.length} icons of "${set.name}" come from: its exports are those icons in the look they draw now, so "${variant}" is that look and can't be a variant of them. "${set.name}" declares no default variant; declare "${variant}" as the default first.`,
+      [
+        {
+          name: `astryx experimental icon new-set ${set.name} --variants ${variants.join(',')} --default-variant ${variant}`,
+          reason: `declare ${variant}, the look each icon draws, as the default`,
+        },
+      ],
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
   if (added.length === 0 && already.length === 0) {
     throw new AstryxError(
       `"${source.module}" exports no icon with the id of an icon in "${set.name}". Pass the module that exports the ${variant} variant under the same names.`,
@@ -627,3 +769,47 @@ async function addVariantForAll({cwd, from, selector, variant}) {
     },
   };
 }
+
+/**
+ * The set's export name for an id: `x-filled` is `XFilledIcon`.
+ * @param {string} id
+ */
+function nameFromId(id) {
+  return iconExportName(
+    id
+      .split('-')
+      .map(word => word[0].toUpperCase() + word.slice(1))
+      .join(''),
+  );
+}
+
+/**
+ * The variant an export of a library of looks is of the icon the set
+ * already wraps for its glyph: its word at the first look position, in name
+ * order, where it differs from the wrapped export. That word is a variant
+ * only when the set declares it and it is not the default, which the icon's
+ * own export draws. Otherwise null, so the listing offers no variant
+ * command that the set's data would refuse.
+ * @param {string} id the export's id, look words kept
+ * @param {string} wrappedId the wrapped export's id, look words kept
+ * @param {Array<Set<string>>} positions the library's look positions, the
+ *   last word first
+ * @param {import('../../../foundation/discovery/icon-set-discovery.mjs').DiscoveredIconSet} set
+ * @returns {string | null}
+ */
+function lookVariantOf(id, wrappedId, positions, set) {
+  const {look} = splitLook(id.split('-'), positions);
+  const {look: wrapped} = splitLook(wrappedId.split('-'), positions);
+  let word = null;
+  for (let index = look.length - 1; index >= 0; index--) {
+    if (look[index] !== wrapped[index]) {
+      word = look[index];
+      break;
+    }
+  }
+  return word != null &&
+    (set.data.variants ?? []).includes(word) &&
+    word !== set.data.default?.variant
+    ? word
+    : null;
+}

package/api/icon/icon.type.d.mts

@@ -260,7 +260,7 @@ export type IconAddOptions = {
      */
     definition?: string | undefined;
     /**
-     * - Add the set's own definition with this name and map the icon to it.
+     * - Add the set's own definition with this name (camelCase, or kebab-case written as camelCase) and map the icon to it.
      */
     newDefinition?: string | undefined;
     /**
@@ -354,6 +354,7 @@ export type IconDefinitionMatchesResponse = {
         id: string;
         matches: IconDefinitionMatch[];
         newDefinition: string | null;
+        variant?: string | undefined;
     };
 };
 /**
@@ -438,7 +439,7 @@ export type IconNewSetOptions = {
      */
     variants?: string | string[] | undefined;
     /**
-     * - With `variants`: the variant each icon's own export draws; the first variant when absent.
+     * - With `variants`: the variant each icon's own export draws; when absent, the look the icons' exports draw in a library whose names encode looks; otherwise the set's current default, else, on a set without icons, the first variant. A set with icons changes it only with `from`, and only in a library whose names encode looks.
      */
     defaultVariant?: string | undefined;
     /**
@@ -511,6 +512,25 @@ export type IconNewData = {
      * - With `from` on an existing set: the set was refreshed, not created.
      */
     refreshed?: boolean | undefined;
+    /**
+     * - Without `from` on an existing set: its variants, default variant, display name, or description were updated in place, not created.
+     */
+    updated?: boolean | undefined;
+    /**
+     * - On a refresh from a package root: the icons that read one file of that package (`from`) and now import from the root (`to`); each keeps its id, export, `map` entries, variants, and words.
+     */
+    moved?: {
+        id: string;
+        from: string;
+        to: string;
+    }[] | undefined;
+    /**
+     * - With `from`: the wrapped library (`name@version`) ships no license file to copy and the set has none. `path` is where to add a NOTICE file that names the library and its license; the CLI never writes it.
+     */
+    licenseNoticeMissing?: {
+        library: string;
+        path: string;
+    } | undefined;
     /**
      * - On a refresh: the icons whose id this release's id rule changes, matched by the export the library still has; each keeps its `map` entries, variants, and words.
      */

package/api/icon/icon.type.mjs

@@ -183,7 +183,7 @@
  * @property {string} from - The module the icon is exported from: a package, a package subpath, or a relative path in this package.
  * @property {string} [set] - The set to edit, when the package ships several.
  * @property {string} [definition] - The icon definition to map the icon to.
- * @property {string} [newDefinition] - Add the set's own definition with this name and map the icon to it.
+ * @property {string} [newDefinition] - Add the set's own definition with this name (camelCase, or kebab-case written as camelCase) and map the icon to it.
  * @property {string} [description] - With `newDefinition`: what the icon is for.
  * @property {string[]} [words] - With `newDefinition`: words people search for.
  * @property {boolean} [useDefault] - The module's default export is the icon.
@@ -249,6 +249,7 @@
  * @property {string} data.id - The id the icon would get.
  * @property {IconDefinitionMatch[]} data.matches - At most 10, best first.
  * @property {string | null} data.newDefinition - The command that adds the set's own definition, when no match fits.
+ * @property {string} [data.variant] - When the set already has an icon for the export's glyph from another export of the library: the command that adds this export as that icon's variant.
  */
 
 /**
@@ -293,7 +294,7 @@
  * @property {string} [from] - A module whose every icon component the set wraps: a package, a package subpath, or a ./ path in the package.
  * @property {string[] | string} [exclude] - With `from`: export names that are not icons; a string is split on commas.
  * @property {string[] | string} [variants] - The variants the set supplies, such as `outline,solid`; a string is split on commas.
- * @property {string} [defaultVariant] - With `variants`: the variant each icon's own export draws; the first variant when absent.
+ * @property {string} [defaultVariant] - With `variants`: the variant each icon's own export draws; when absent, the look the icons' exports draw in a library whose names encode looks; otherwise the set's current default, else, on a set without icons, the first variant. A set with icons changes it only with `from`, and only in a library whose names encode looks.
  * @property {string} [displayName] - The descriptor's display name; the set name in title case when absent.
  * @property {string} [description] - The descriptor's one-line description; `<Display name> icons.` when absent.
  */
@@ -324,6 +325,9 @@
  * @property {string} [from]
  * @property {number} [icons] - With `from`: how many icons it wrote.
  * @property {boolean} [refreshed] - With `from` on an existing set: the set was refreshed, not created.
+ * @property {boolean} [updated] - Without `from` on an existing set: its variants, default variant, display name, or description were updated in place, not created.
+ * @property {Array<{id: string, from: string, to: string}>} [moved] - On a refresh from a package root: the icons that read one file of that package (`from`) and now import from the root (`to`); each keeps its id, export, `map` entries, variants, and words.
+ * @property {{library: string, path: string}} [licenseNoticeMissing] - With `from`: the wrapped library (`name@version`) ships no license file to copy and the set has none. `path` is where to add a NOTICE file that names the library and its license; the CLI never writes it.
  * @property {Array<{from: string, to: string}>} [renamed] - On a refresh: the icons whose id this release's id rule changes, matched by the export the library still has; each keeps its `map` entries, variants, and words.
  * @property {Array<{definition: string, icon: string}>} [mapped] - With `from`: the `map` entries an icon with the definition's exact name gives (on a refresh, every such entry, kept or new); check each.
  * @property {Array<{definition: string, icon: string, word: string}>} [suggestions] - With `from`: for each unmapped Astryx definition, up to three icons it might map to, best first: the definition's name in another spelling or as another name of an icon, ids that start with it, an id or another name that is one of its words, then two-word ids that are a one-word word sized, shaped, or numbered (`grid-2x2`); never a negated form, the opposite direction, or an icon already mapped. `word` is the name or word that matched. Never written.

package/api/icon/iconAdd.doc.mjs

@@ -53,7 +53,7 @@ export const doc = {
       name: 'options.newDefinition',
       type: 'string',
       description:
-        "Add the set's own definition with this name, then map the icon to it.",
+        "Add the set's own definition with this name, in camelCase (`aiHelper`) or kebab-case (`ai-helper`), then map the icon to it.",
     },
     {
       name: 'options.description',
@@ -119,7 +119,7 @@ export const doc = {
     },
     {
       code: 'ERR_INVALID_ARGUMENT',
-      when: 'the export is data rather than a component, a new definition is named like an Astryx one, or the variant is not one the set declares',
+      when: "the export is data rather than a component, a new definition is named like an Astryx one, or the variant is not one the set declares, is the look each icon's own export already draws, or is no look word of a library whose export names encode looks",
     },
     {code: 'ERR_FILE_EXISTS', when: 'another icon already has the id'},
     {

package/api/icon/iconNewDefinition.doc.mjs

@@ -19,7 +19,8 @@ export const doc = {
     {
       name: 'name',
       type: 'string',
-      description: 'camelCase definition name.',
+      description:
+        'The definition name, in camelCase (`rocketLaunch`) or kebab-case (`rocket-launch`); it is written in camelCase.',
       required: true,
     },
     {
@@ -66,7 +67,7 @@ export const doc = {
   throws: [
     {
       code: 'ERR_INVALID_ARGUMENT',
-      when: 'the name is not camelCase, or Astryx already has it',
+      when: 'the name is neither camelCase nor kebab-case, or Astryx already has it',
     },
     {
       code: 'ERR_MISSING_ARGUMENT',

package/api/icon/iconNewSet.doc.mjs

@@ -10,7 +10,7 @@ export const doc = {
   displayName: 'iconNewSet()',
   summary: 'Add an icon set to an integration package.',
   description:
-    "Creates an integration manifest when the package has none, writes the set directory with its strongly typed same-stem IconSetDoc and a starter data file (schemaVersion 1, module set to the package name, no icons and an empty map yet), and the set's generated module with its declaration file and an empty themeIcons theme map; with from, it wraps a library's icons into them, records the installed library and version as the data file's source, copies the library's license notices into the set, uses the library's license, maps each Astryx definition whose name is an icon id, and returns up to three likely icons for each other definition as suggestions (by its name, its words, and the other names the library gives an icon; never a part of a word, a negated form, or the opposite direction), never written. It declares the manifest's `experimental.iconSets` root on first use, and includes the manifest and root in package.json files when the package already uses an allowlist. It never writes the package's entry, exports, main, types, files list, peers, or scripts: its notes name each change the package needs as text to copy. Every path is confined to the package and existing files are never overwritten. Experimental: it may change or be removed in a patch release.",
+    "Creates an integration manifest when the package has none, writes the set directory with its strongly typed same-stem IconSetDoc and a starter data file (schemaVersion 1, module set to the package name, no icons and an empty map yet), and the set's generated module with its declaration file and an empty themeIcons theme map; with from, it wraps a library's icons into them, records the installed library and version as the data file's source, copies the library's license notices into the set, uses the library's license, maps each Astryx definition whose name is an icon id, and returns up to three likely icons for each other definition as suggestions (by its name, its words, and the other names the library gives an icon; never a part of a word, a negated form, or the opposite direction), never written. A library whose export names end in style, size and weight words gives one icon per glyph, named without those words, in the look the default variant names, else the library's usual default (outline, regular, the middle weight). Over an existing set, `from` refreshes it; without `from`, `variants`, `defaultVariant`, `displayName` and `description` update it in place and leave its icons, map and generated module unchanged (a variant an icon has must stay declared, and a set with icons keeps its default variant). It declares the manifest's `experimental.iconSets` root on first use, and includes the manifest and root in package.json files when the package already uses an allowlist. It never writes the package's entry, exports, main, types, files list, peers, or scripts: its notes name each change the package needs as text to copy. Every path is confined to the package, and an existing set is changed only as above. Experimental: it may change or be removed in a patch release.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'iconNewSet(name: string, options?: IconNewSetOptions): Promise<IconNewSetResponse>',
@@ -56,7 +56,7 @@ export const doc = {
       name: 'options.defaultVariant',
       type: 'string',
       description:
-        "With variants: the variant each icon's own export draws, written to the data file's default; the first variant when absent.",
+        "With variants: the variant each icon's own export draws, written to the data file's default. In a library whose export names encode looks, it must be one of the library's look words, and when absent it is the look the icons' exports draw (with from and no icons yet, the library's usual default), which variants must list. Otherwise, when absent, an existing set keeps its default while variants declares it; a set without icons takes the first variant, and a set with icons and none declared needs it. Without from, a set with icons refuses a default other than the look they draw; when its icons' export names name no looks, it refuses one other than its declared default with from too.",
     },
     {
       name: 'options.displayName',
@@ -81,11 +81,11 @@ export const doc = {
   throws: [
     {
       code: 'ERR_INVALID_ARGUMENT',
-      when: 'the name is not lowercase kebab-case, package.json has no name, or a variant name or the default variant is invalid',
+      when: 'the name is not lowercase kebab-case, package.json has no name, or a variant name or the default variant is invalid; the default variant is no look word of a library whose export names encode looks; or the default variant would change on a set that has icons: without `from` (wrap the library again with `from` and `defaultVariant`), or with or without it when the export names of its icons name no looks (add the look as a variant instead)',
     },
     {
       code: 'ERR_INVALID_OPTION',
-      when: '`exclude` is given without `from`, or `defaultVariant` without `variants`',
+      when: '`exclude` is given without `from`, or `defaultVariant` without `variants`; `variants` leave out the default variant: the look the icons draw in a library whose export names encode looks, or the declared default of a set with icons whose export names name no looks; or such a set declares no default and `defaultVariant` names none',
     },
     {
       code: 'ERR_FILE_EXISTS',

package/api/icon/search/search.mjs

@@ -12,10 +12,12 @@
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {loadIconSets} from '../_adapter.mjs';
-import {rankIcons, setsNamed, unusableSet} from '../_records.mjs';
-
-/** The lowest score of a whole-word or word-start match. */
-const WORD_SCORE = 60;
+import {
+  answeringMatches,
+  rankIcons,
+  setsNamed,
+  unusableSet,
+} from '../_records.mjs';
 
 /**
  * Every icon of one set, by id: `--set <name> --all-icons`, so an author can read
@@ -75,11 +77,10 @@ export async function iconSearch(query, {cwd, set, limit}) {
     if (searched.length === 0) throw unusableSet(sets, withdrawn, set);
   }
   const ranked = rankIcons(searched, query);
-  // A partial match (`pin` inside `shopping`) answers only when nothing
-  // matches a whole word or a word start.
-  const matches = ranked.some(each => each.score >= WORD_SCORE)
-    ? ranked.filter(each => each.score >= WORD_SCORE)
-    : ranked;
+  // A word start (`start` for `star`) answers only when nothing matches a
+  // whole word, and a partial match (`pin` inside `shopping`) only when
+  // nothing matches a whole word or a word start.
+  const matches = answeringMatches(ranked);
   return {
     type: 'icon.search',
     data: {

package/api/integration/add-helpers.d.mts

@@ -92,7 +92,7 @@ export function loadCurrentManifest(manifestFile: string, manifestExists: boolea
  * @param {string} manifestPath
  * @param {string[]} files
  * @param {boolean} dryRun
- * @returns {{type: 'integration.add', data: Omit<import('./integration-authoring.type.mjs').IntegrationAddData, 'kind'> & {kind: K, icons?: number, refreshed?: boolean, renamed?: Array<{from: string, to: string}>, mapped?: Array<{definition: string, icon: string}>, suggestions?: Array<{definition: string, icon: string, word: string}>, notes?: string[]}}}
+ * @returns {{type: 'integration.add', data: Omit<import('./integration-authoring.type.mjs').IntegrationAddData, 'kind'> & {kind: K, icons?: number, refreshed?: boolean, updated?: boolean, renamed?: Array<{from: string, to: string}>, moved?: Array<{id: string, from: string, to: string}>, licenseNoticeMissing?: {library: string, path: string}, mapped?: Array<{definition: string, icon: string}>, suggestions?: Array<{definition: string, icon: string, word: string}>, notes?: string[]}}}
  */
 export function receipt<K extends import("./integration-authoring.type.mjs").IntegrationAddData["kind"] | import("../icon/icon.type.mjs").IconNewData["kind"]>(kind: K, name: string, root: {
     path: string;
@@ -103,10 +103,20 @@ export function receipt<K extends import("./integration-authoring.type.mjs").Int
         kind: K;
         icons?: number;
         refreshed?: boolean;
+        updated?: boolean;
         renamed?: Array<{
             from: string;
             to: string;
         }>;
+        moved?: Array<{
+            id: string;
+            from: string;
+            to: string;
+        }>;
+        licenseNoticeMissing?: {
+            library: string;
+            path: string;
+        };
         mapped?: Array<{
             definition: string;
             icon: string;