@astryxdesign/cli 0.7.11 → 0.7.12-canary.ccb4a6d

package/foundation/discovery/icon-set-checks.mjs

@@ -44,8 +44,9 @@ import * as path from 'node:path';
 import {findInstalledPackage} from '../fs/paths.mjs';
 import {satisfiesRange} from '../env/semver.mjs';
 import {
-  NOTICE_FILE_RE,
   discoverIconSetDirectory,
+  hasLicenseNotice,
+  licenseNoticeFix,
   resolveIconModule,
   splitSpecifier,
 } from './icon-set-discovery.mjs';
@@ -57,6 +58,7 @@ import {
   otherNamesOf,
   generatedTypesText,
   readGeneratedStatements,
+  generatedTypesMatch,
 } from './icon-set-writer.mjs';
 import {
   exportValueKind,
@@ -67,6 +69,7 @@ import {
 } from './module-exports.mjs';
 import {astryxIconDefinitions} from './icon-definition-discovery.mjs';
 import {rankIcons} from './icon-ranking.mjs';
+import {shellArg} from '../text/shell-arg.mjs';
 import {
   issueError,
   issueWarning,
@@ -276,16 +279,17 @@ function checkContract(set, packageName, pkg, unchecked) {
       const actual = fs.existsSync(typesFile)
         ? fs.readFileSync(typesFile, 'utf-8')
         : null;
-      // The header comment is the writer's, and changes between releases;
-      // the declarations are what must match.
-      const code = (/** @type {string} */ text) =>
-        text
-          .split('\n')
-          .filter(line => !line.startsWith('//'))
-          .join('\n');
+      // The declarations must match, statement by statement, however a
+      // formatter left the file; the header comment is the writer's and
+      // changes between releases.
       if (
         expected != null &&
-        (actual == null || code(actual) !== code(expected))
+        (actual == null ||
+          !generatedTypesMatch(
+            actual,
+            expected,
+            /** @type {string} */ (typesRel),
+          ))
       ) {
         issues.push(
           issueError(
@@ -359,12 +363,12 @@ function checkDefinitions(set) {
     if (mapped.has(doc.name) || !doc.builtIn) continue;
     const suggestion = suggestIcon(set, doc);
     const hint = suggestion
-      ? ` Suggested: astryx experimental icon map ${doc.name} ${suggestion.icon}.`
+      ? ` Suggested: astryx experimental icon map ${doc.name} ${suggestion.icon} --set ${set.name}.`
       : '';
     issues.push(
       issueError(
         ICON_BUILTIN_DEFINITION_MISSING,
-        `${label} maps no icon to the built-in icon definition "${doc.name}" (${doc.description} Words: ${doc.words.join(', ')}.). Every set maps every built-in definition: run \`astryx experimental icon map ${doc.name} <icon id>\` with the icon that draws it${findHint(set, doc)}.${hint}`,
+        `${label} maps no icon to the built-in icon definition "${doc.name}" (${doc.description} Words: ${doc.words.join(', ')}.). Every set maps every built-in definition: run \`astryx experimental icon map ${doc.name} <icon id> --set ${set.name}\` with the icon that draws it${findHint(set, doc)}.${hint}`,
       ),
     );
   }
@@ -382,7 +386,7 @@ function checkDefinitions(set) {
       issues.push(
         issueWarning(
           ICON_DEFINITION_UNUSED,
-          `${label} declares the icon definition "${doc.name}", but "map" names no icon for it. Map it with \`astryx experimental icon map ${doc.name} <icon id>\`, or remove definitions/${doc.name}.doc.mjs.${suggestion ? ` Suggested: astryx experimental icon map ${doc.name} ${suggestion.icon}.` : ''}`,
+          `${label} declares the icon definition "${doc.name}", but "map" names no icon for it. Map it with \`astryx experimental icon map ${doc.name} <icon id> --set ${set.name}\`, or remove definitions/${doc.name}.doc.mjs.${suggestion ? ` Suggested: astryx experimental icon map ${doc.name} ${suggestion.icon} --set ${set.name}.` : ''}`,
         ),
       );
     }
@@ -538,13 +542,7 @@ export function suggestedIcons(set, doc) {
     ...nameWords,
     ...wordIds.flatMap(id => id.split('-')).map(stem),
   ]);
-  const icons = set.data.icons.map(icon => ({
-    id: icon.id,
-    words: icon.id.split('-').map(stem),
-    raw: icon.id.split('-'),
-    // The library's other names for it, the same ones `map` accepts.
-    other: otherNamesOf(icon),
-  }));
+  const icons = suggestionIndex(set.data.icons);
   /** How many of the definition's words an id has: more is a better fit. */
   const fit = (/** @type {string[]} */ words) =>
     words.filter(word => meaning.has(word)).length;
@@ -636,6 +634,29 @@ export function suggestedIcons(set, doc) {
   return found.slice(0, SUGGESTIONS_PER_DEFINITION);
 }
 
+/**
+ * Each icon as the suggestion rules read it: its id's words as written and
+ * in singular form, and the library's other names for it (the same ones
+ * `map` accepts). Built once per list of icons, so suggesting for every
+ * definition of a large library reads each icon once.
+ * @type {WeakMap<object, Array<{id: string, words: string[], raw: string[], other: string[]}>>}
+ */
+const suggestionIndexes = new WeakMap();
+
+/** @param {Array<{id: string, words?: string[]}>} list */
+function suggestionIndex(list) {
+  const cached = suggestionIndexes.get(list);
+  if (cached) return cached;
+  const index = list.map(icon => ({
+    id: icon.id,
+    words: icon.id.split('-').map(stem),
+    raw: icon.id.split('-'),
+    other: otherNamesOf(icon),
+  }));
+  suggestionIndexes.set(list, index);
+  return index;
+}
+
 /**
  * A word in its singular form, so a plural meets its singular and nothing
  * else: `languages` meets `language`, `arrows` meets `arrow`. Only a
@@ -934,10 +955,10 @@ function findHint(set, doc) {
       each => each.score >= FIND_FLOOR,
     );
     if (found.length > 0) {
-      return ` (icons matching "${query}": \`astryx experimental icon ${query} --set ${set.name}\`)`;
+      return ` (icons matching "${query}": \`astryx experimental icon ${shellArg(query)} --set ${set.name}\`)`;
     }
   }
-  return ' (no icon in the set has its name or words: pick the library icon that draws it; if the library has none, map the closest, or add your own artwork with `astryx experimental icon add <Name> --from ./src/icons/<name>.js --definition <definition>`)';
+  return ` (no icon in the set has its name or words: pick the library icon that draws it; if the library has none, map the closest, or add your own artwork with \`astryx experimental icon add <Name> --from ./src/icons/<name>.js --definition ${doc.name} --set ${set.name}\`)`;
 }
 
 /**
@@ -983,14 +1004,11 @@ function checkUpstream(set, packageDir, pkg) {
       ),
     );
   }
-  const rootNotices = safeList(packageDir).filter(name =>
-    NOTICE_FILE_RE.test(name),
-  );
-  if (set.notices.length === 0 && rootNotices.length === 0) {
+  if (!hasLicenseNotice(set.dir) && !hasLicenseNotice(packageDir)) {
     issues.push(
       issueWarning(
         ICON_LICENSE_NOTICE_MISSING,
-        `${label} is generated from ${source.package} but ships no license notice. Copy the library's LICENSE (and NOTICE, if any) into the set directory or the package root.`,
+        `${label} is generated from ${source.package}@${source.version} but ships no license notice. ${licenseNoticeFix(path.relative(packageDir, set.dir).split(path.sep).join('/'), `${source.package}@${source.version}`)} If the library ships a LICENSE or NOTICE file, copy that file there instead.`,
       ),
     );
   }
@@ -1006,12 +1024,3 @@ function safeSatisfies(version, range) {
     return true;
   }
 }
-
-/** @param {string} dir */
-function safeList(dir) {
-  try {
-    return fs.readdirSync(dir);
-  } catch {
-    return [];
-  }
-}

package/foundation/discovery/icon-set-discovery.d.mts

@@ -1,6 +1,19 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * What to add when a set wraps a library and has no license notice: a
+ * NOTICE file in the set directory, with the file names that count. The
+ * CLI never writes it, because the license text is the author's to state.
+ * @param {string} setDir the set directory, from the package root
+ * @param {string} library the library as `name@version`
+ */
+export function licenseNoticeFix(setDir: string, library: string): string;
+/**
+ * Whether a directory has a license or notice file ({@link NOTICE_FILE_RE}).
+ * @param {string} dir
+ */
+export function hasLicenseNotice(dir: string): boolean;
 /**
  * One installed icon set: its descriptor, its data, and where it came from.
  * @typedef {object} DiscoveredIconSet

package/foundation/discovery/icon-set-discovery.mjs

@@ -43,6 +43,31 @@ const SET_NAME_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
 /** A license or notice file a set ships beside its data (FR15). */
 export const NOTICE_FILE_RE = /^(?:licen[cs]e|notice|copying)(?:[.-].*)?$/iu;
 
+/**
+ * What to add when a set wraps a library and has no license notice: a
+ * NOTICE file in the set directory, with the file names that count. The
+ * CLI never writes it, because the license text is the author's to state.
+ * @param {string} setDir the set directory, from the package root
+ * @param {string} library the library as `name@version`
+ */
+export function licenseNoticeFix(setDir, library) {
+  return `Add a NOTICE (or LICENSE) file to ${setDir} that names ${library} and its license: \`${setDir}/NOTICE\`. A file named LICENSE, LICENCE, NOTICE, or COPYING, in any case and with an optional suffix such as NOTICE.md or LICENSE-MIT, counts in the set directory or the package root.`;
+}
+
+/**
+ * Whether a directory has a license or notice file ({@link NOTICE_FILE_RE}).
+ * @param {string} dir
+ */
+export function hasLicenseNotice(dir) {
+  try {
+    return fs
+      .readdirSync(dir, {withFileTypes: true})
+      .some(file => file.isFile() && NOTICE_FILE_RE.test(file.name));
+  } catch {
+    return false;
+  }
+}
+
 /**
  * One installed icon set: its descriptor, its data, and where it came from.
  * @typedef {object} DiscoveredIconSet

package/foundation/discovery/icon-set-writer.d.mts

@@ -166,29 +166,158 @@ export function modulePrefix(file: string, options?: {
     adapter?: boolean;
     exclude?: string[];
 }): string[];
+/**
+ * How a module names its icons: the library prefix every icon export shares
+ * ({@link modulePrefix}) and the look words its names end in
+ * ({@link lookPositions}), read from its icon exports once. A large module
+ * reports its reading, as {@link libraryIcons} does.
+ * @param {string} file
+ * @param {{adapter?: boolean, module?: string, progress?: (line: string) => void}} [options]
+ *   `module`: the module as the author named it, for progress; `progress`:
+ *   hears the reading of a large module
+ * @returns {{prefix: string[], positions: Array<Set<string>>}}
+ */
+export function moduleNaming(file: string, options?: {
+    adapter?: boolean;
+    module?: string;
+    progress?: (line: string) => void;
+}): {
+    prefix: string[];
+    positions: Array<Set<string>>;
+};
+/**
+ * An export's id and set name ({@link iconNaming}) without the look words
+ * its library's names end in ({@link lookPositions}):
+ * `XOutline24WGHT500Icon` is `x`, `XIcon`.
+ * @param {string} name
+ * @param {{prefix: string[], positions: Array<Set<string>>}} naming
+ * @returns {{id: string, name: string}}
+ */
+export function iconNamingWithoutLook(name: string, { prefix, positions }: {
+    prefix: string[];
+    positions: Array<Set<string>>;
+}): {
+    id: string;
+    name: string;
+};
+/**
+ * The trailing words a library encodes its looks with: a style, a size, a
+ * weight (`XOutline24WGHT500Icon` is `x` in the `outline`, `24`, `wght500`
+ * look). A trailing position is a look position when, across at least
+ * {@link LOOK_MIN_ICONS} icons, at most {@link LOOK_MAX_VALUES} words fill
+ * it, each on at least 5% of the icons and together on at least 90%, and
+ * those words name a look ({@link namesLook}); the positions are read from
+ * the end while they hold. Glyph names never meet that bar (`trash-2` and
+ * `clock-10` are a few icons each, and `up` and `down` are directions), so
+ * a library that encodes no looks has none. Reads each id once per
+ * position and keeps only counts.
+ * @param {string[]} ids every icon's id
+ * @returns {Array<Set<string>>} the look positions, the last word first
+ */
+export function lookPositions(ids: string[]): Array<Set<string>>;
+/**
+ * An id's glyph words and its look words, by {@link lookPositions}:
+ * `x-outline-24-wght500` is `x` with `[wght500, 24, outline]`, null where
+ * the id has no look word.
+ * @param {string[]} words
+ * @param {Array<Set<string>>} positions
+ * @returns {{base: string[], look: Array<string | null>}}
+ */
+export function splitLook(words: string[], positions: Array<Set<string>>): {
+    base: string[];
+    look: Array<string | null>;
+};
+/**
+ * The word each look position prefers: a word of `prefer` it has (the set's
+ * default variant), else a usual default style word, else the middle of a
+ * series of numbered words (`wght300` … `wght700` gives `wght500`), else
+ * its first word in order.
+ * @param {Array<Set<string>>} positions
+ * @param {string[]} [prefer]
+ * @returns {string[]}
+ */
+export function preferredLook(positions: Array<Set<string>>, prefer?: string[]): string[];
+/**
+ * One icon a library gives.
+ * @typedef {object} LibraryIcon
+ * @property {string} export the library export it reads
+ * @property {string} id
+ * @property {string} name the name the set exports it as
+ * @property {boolean} adapt
+ * @property {string[]} aliases the ids of the other names the library
+ *   exports the icon as, leaving out the library's own name (`lucide-trash`)
+ * @property {Array<string | null>} [look] in a library that encodes looks:
+ *   this export's look words by position, the last word first
+ * @property {string[]} [looks] in a library that encodes looks: every
+ *   export that draws the glyph, this one included
+ */
+/**
+ * The words a library's looks are named by, and the look a set takes from
+ * it: what {@link libraryIcons} found, for the receipt.
+ * @typedef {object} LibraryLookSummary
+ * @property {string[][]} positions each position's words, sorted, the last
+ *   word of a name first
+ * @property {string[]} preferred the word taken in each position
+ * @property {number} exports how many exports draw the icons
+ */
 /**
  * Every icon a whole library exports, for wrapping it at once: one entry per
  * component (and, with an adapter, per data export), read by its `…Icon`
  * export when it has one (an alias of the same value is recorded once), with
  * its id and the name the set exports it as from the name, the library
  * prefix left out ({@link libraryPrefix}).
+ *
+ * A library that encodes looks in its export names ({@link lookPositions})
+ * gives one icon per glyph: the look {@link preferredLook} prefers, its id
+ * and name without the look words (`XOutline24WGHT500Icon` is `x`,
+ * `XIcon`), and its `looks`, every export that draws the glyph.
  * @param {string} file
- * @param {{adapter?: boolean, exclude?: string[]}} [options] `adapter`:
- *   whether the set declares one; `exclude`: export names that are not icons
- * @returns {Array<{export: string, id: string, name: string, adapt: boolean, aliases: string[]}>}
- *   `aliases`: the ids of the other names the library exports the icon as,
- *   leaving out the library's own name (`lucide-trash`)
+ * @param {{adapter?: boolean, exclude?: string[], prefer?: string[] | ((positions: Array<Set<string>>) => string[]), module?: string, progress?: (line: string) => void, summary?: (summary: LibraryLookSummary) => void}} [options]
+ *   `adapter`: whether the set declares one; `exclude`: export names that
+ *   are not icons; `prefer`: look words to prefer (the set's default
+ *   variant), or a function that gives them from the library's look
+ *   positions before any glyph is picked; `module`: the module as the author named it, for progress;
+ *   `progress`: hears the reading of a large module;
+ *   `summary`: hears the looks found, when the library has any
+ * @returns {LibraryIcon[]}
  */
 export function libraryIcons(file: string, options?: {
     adapter?: boolean;
     exclude?: string[];
-}): Array<{
-    export: string;
-    id: string;
-    name: string;
-    adapt: boolean;
-    aliases: string[];
-}>;
+    prefer?: string[] | ((positions: Array<Set<string>>) => string[]);
+    module?: string;
+    progress?: (line: string) => void;
+    summary?: (summary: LibraryLookSummary) => void;
+}): LibraryIcon[];
+/**
+ * The library's icons grouped by glyph when its export names encode looks
+ * ({@link libraryIcons}), with the look positions and the words preferred.
+ * Without look positions the icons are returned as they are.
+ * @param {LibraryIcon[]} all every icon, one per export
+ * @param {string[]} [prefer]
+ * @returns {{icons: LibraryIcon[], positions: Array<Set<string>>, preferred: string[]}}
+ */
+export function libraryLooks(all: LibraryIcon[], prefer?: string[]): {
+    icons: LibraryIcon[];
+    positions: Array<Set<string>>;
+    preferred: string[];
+};
+/**
+ * Every icon a library exports, one per export: {@link libraryIcons} before
+ * looks are grouped. A large module reports its reading, as
+ * {@link libraryIcons} does.
+ * @param {string} file
+ * @param {{adapter?: boolean, exclude?: string[], module?: string, progress?: (line: string) => void}} [options]
+ *   `module`: the module as the author named it, for progress; `progress`:
+ *   hears the reading of a large module
+ * @returns {LibraryIcon[]}
+ */
+export function everyLibraryIcon(file: string, options?: {
+    adapter?: boolean;
+    exclude?: string[];
+    module?: string;
+    progress?: (line: string) => void;
+}): LibraryIcon[];
 /**
  * The source of one icon definition file, typed IconDefinitionDoc.
  * @param {{name: string, description: string, words: string[]}} doc
@@ -199,13 +328,20 @@ export function iconDefinitionSource(doc: {
     words: string[];
 }): string;
 /**
- * Check a new icon definition for a set: a camelCase name no Astryx
- * definition has, a description, and at least one lower-case word.
+ * A new definition's name as written in a command: camelCase as given, or
+ * kebab-case as the docs list definitions (`ai-helper` is `aiHelper`).
+ * @param {string} name
+ */
+export function definitionNameFromInput(name: string): string;
+/**
+ * Check a new icon definition for a set: a camelCase name (or its kebab-case
+ * form, {@link definitionNameFromInput}) no Astryx definition has, a
+ * description, and at least one lower-case word.
  * @param {DiscoveredIconSet} set
- * @param {{name: string, description?: string, words?: string[]}} doc
+ * @param {{name: string, description?: string, words?: string[]}} given
  * @returns {{name: string, description: string, words: string[]}}
  */
-export function checkNewDefinition(set: DiscoveredIconSet, doc: {
+export function checkNewDefinition(set: DiscoveredIconSet, given: {
     name: string;
     description?: string;
     words?: string[];
@@ -232,6 +368,15 @@ export function writeDefinitionFile(set: DiscoveredIconSet, doc: {
     description: string;
     words: string[];
 }): () => void;
+/**
+ * Whether a generated declaration file declares what its generated module
+ * gives, statement by statement however a formatter left either file
+ * ({@link generatedStatements}); the header comment is ignored.
+ * @param {string} actual the declaration file as it is
+ * @param {string} expected {@link generatedTypesText} for the module
+ * @param {string} label the declaration file's path, for a parse error
+ */
+export function generatedTypesMatch(actual: string, expected: string, label: string): boolean;
 /**
  * The generated icons module of a set, from the package root: `generated`
  * in its data file, else `<set directory>/<set>.generated.js`.
@@ -316,6 +461,34 @@ export function sameIconModule(a: string, b: string): boolean;
  * @param {string} specifier
  */
 export function iconModulePackage(specifier: string): string;
+/**
+ * The set's exports that read one file of a package, where a refresh from
+ * that package's root can read them from the root instead. An export moves
+ * when the root exports the same icon: an export that resolves to the same
+ * file and binding. When the subpath export cannot be resolved, a root
+ * export of the same name counts. Each maps to the root's
+ * export and the module it reads now. Empty unless `root` is a package
+ * root, not a subpath or a ./ path.
+ * @param {Map<string, {module: string, source: string}>} origins the
+ *   set's exports ({@link generatedOrigins})
+ * @param {{file: string, module: string}} root the refreshed module
+ * @param {string[]} rootExports the root's icon exports
+ * @param {{packageDir: string, pkg: Record<string, any>}} where
+ * @returns {Map<string, {source: string, from: string}>}
+ */
+export function packageRootMoves(origins: Map<string, {
+    module: string;
+    source: string;
+}>, root: {
+    file: string;
+    module: string;
+}, rootExports: string[], where: {
+    packageDir: string;
+    pkg: Record<string, any>;
+}): Map<string, {
+    source: string;
+    from: string;
+}>;
 /**
  * Write the set's generated module and its declaration file
  * ({@link generatedModuleText}). Returns whether either changed, and a
@@ -469,6 +642,55 @@ export class IconSetAuthoringError extends Error {
 }
 /** The theme map the generated module writes. */
 export const THEME_MAP_NAME: "themeIcons";
+/**
+ * One icon a library gives.
+ */
+export type LibraryIcon = {
+    /**
+     * the library export it reads
+     */
+    export: string;
+    id: string;
+    /**
+     * the name the set exports it as
+     */
+    name: string;
+    adapt: boolean;
+    /**
+     * the ids of the other names the library
+     * exports the icon as, leaving out the library's own name (`lucide-trash`)
+     */
+    aliases: string[];
+    /**
+     * in a library that encodes looks:
+     * this export's look words by position, the last word first
+     */
+    look?: (string | null)[] | undefined;
+    /**
+     * in a library that encodes looks: every
+     * export that draws the glyph, this one included
+     */
+    looks?: string[] | undefined;
+};
+/**
+ * The words a library's looks are named by, and the look a set takes from
+ * it: what {@link libraryIcons} found, for the receipt.
+ */
+export type LibraryLookSummary = {
+    /**
+     * each position's words, sorted, the last
+     * word of a name first
+     */
+    positions: string[][];
+    /**
+     * the word taken in each position
+     */
+    preferred: string[];
+    /**
+     * how many exports draw the icons
+     */
+    exports: number;
+};
 export type DiscoveredIconSet = import("./icon-set-discovery.mjs").DiscoveredIconSet;
 export type IconSetData = import("../../authoring/doctypes/icon-set/type").IconSetData;
 /**