@astryxdesign/cli 0.7.12 → 0.7.13-canary.9993f4c

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

@@ -43,6 +43,14 @@ export function hasLicenseNotice(dir: string): boolean;
  *   file is invalid; `unresolved`: its module does not resolve from the project
  * @property {string} reason
  */
+/**
+ * One backup set the project's list names, and what it resolves to.
+ * @typedef {object} IconSetBackup
+ * @property {string} selector the name as the list writes it
+ * @property {'selected' | 'ambiguous' | 'missing' | 'withdrawn'} status
+ * @property {DiscoveredIconSet} [set] the set, when selected
+ * @property {string} reason one sentence saying why
+ */
 /**
  * The project's icon set (FR8).
  * @typedef {object} IconSetChoice
@@ -53,7 +61,13 @@ export function hasLicenseNotice(dir: string): boolean;
  *   `withdrawn`: it names a set that is installed but withdrawn (invalid, or
  *   its module does not resolve), and `reason` says why
  * @property {DiscoveredIconSet} [set] the project's set, when selected
- * @property {string} [configured] the `experimental.iconSet` config value, when set
+ * @property {string} [configured] the main set `experimental.iconSet` names
+ *   (its first entry, when it is a list), when set
+ * @property {IconSetBackup[]} [backups] the backup sets the list names after
+ *   the main set, in order, when it names any
+ * @property {DiscoveredIconSet[]} [order] the sets a template icon is looked
+ *   up in, in order: the main set, then each backup that resolves. Present
+ *   only when the main set is selected
  * @property {string} reason one sentence saying why
  */
 /**
@@ -120,16 +134,39 @@ export function discoverIntegrationIconSets(integration: import("../integrations
  */
 export function withdrawnNamed(withdrawn: WithdrawnIconSet[], selector: string): WithdrawnIconSet[];
 /**
- * Pick the project's icon set (FR8, FR17): the set `experimental.iconSet`
- * names, as `"<set>"` or `"<package>/<set>"`; otherwise the only installed
+ * The entries of an `experimental.iconSet` value, main set first: a string is
+ * a one-entry list.
+ * @param {string | readonly string[] | undefined} configured
+ * @returns {string[]}
+ */
+export function iconSetList(configured: string | readonly string[] | undefined): string[];
+/**
+ * Installed sets the project's list leaves out: the problem, and the fix that
+ * adds them as backups after the list's own. Doctor and `experimental icon
+ * use` print the same words.
+ * @param {number} installed how many sets are installed
+ * @param {string} main the main set as the list writes it
+ * @param {string[]} backups the list's backups, in order
+ * @param {string[]} unlisted the installed sets the list leaves out
+ * @returns {{problem: string, command: string, fix: string}}
+ */
+export function unlistedIconSets(installed: number, main: string, backups: string[], unlisted: string[]): {
+    problem: string;
+    command: string;
+    fix: string;
+};
+/**
+ * Pick the project's icon set (FR8, FR17): the main set `experimental.iconSet`
+ * names, as `"<set>"` or `"<package>/<set>"`, or as the first entry of a list
+ * whose other entries are backup sets in order; otherwise the only installed
  * set; otherwise none. A configured name that matches no valid set but an
  * installed set that was withdrawn says so, with why.
  * @param {DiscoveredIconSet[]} sets installed sets, in integration load order
- * @param {string | undefined} configured the `experimental.iconSet` config value
+ * @param {string | readonly string[] | undefined} configured the `experimental.iconSet` config value
  * @param {WithdrawnIconSet[]} [withdrawn] installed sets that were withdrawn
  * @returns {IconSetChoice}
  */
-export function chooseProjectIconSet(sets: DiscoveredIconSet[], configured: string | undefined, withdrawn?: WithdrawnIconSet[]): IconSetChoice;
+export function chooseProjectIconSet(sets: DiscoveredIconSet[], configured: string | readonly string[] | undefined, withdrawn?: WithdrawnIconSet[]): IconSetChoice;
 /**
  * A set's full name, `<package>/<set>`.
  * @param {{package: string, name: string}} set
@@ -139,7 +176,8 @@ export function iconSetKey(set: {
     name: string;
 }): string;
 /**
- * Sets in tie order (FR6, FR8): the project's set first, then load order.
+ * Sets in tie order (FR6, FR8): the project's set and its backups first, in
+ * list order, then load order.
  * @param {DiscoveredIconSet[]} sets
  * @param {IconSetChoice} choice
  * @returns {DiscoveredIconSet[]}
@@ -147,6 +185,8 @@ export function iconSetKey(set: {
 export function orderIconSets(sets: DiscoveredIconSet[], choice: IconSetChoice): DiscoveredIconSet[];
 /** A license or notice file a set ships beside its data (FR15). */
 export const NOTICE_FILE_RE: RegExp;
+/** The command that chooses a main set and backups, as the CLI prints it. */
+export const ICON_USE_ORDER_COMMAND: "astryx experimental icon use <main> --backup <set>";
 /**
  * One installed icon set: its descriptor, its data, and where it came from.
  */
@@ -213,6 +253,24 @@ export type WithdrawnIconSet = {
     kind: "invalid" | "unresolved";
     reason: string;
 };
+/**
+ * One backup set the project's list names, and what it resolves to.
+ */
+export type IconSetBackup = {
+    /**
+     * the name as the list writes it
+     */
+    selector: string;
+    status: "selected" | "ambiguous" | "missing" | "withdrawn";
+    /**
+     * the set, when selected
+     */
+    set?: DiscoveredIconSet | undefined;
+    /**
+     * one sentence saying why
+     */
+    reason: string;
+};
 /**
  * The project's icon set (FR8).
  */
@@ -230,9 +288,21 @@ export type IconSetChoice = {
      */
     set?: DiscoveredIconSet | undefined;
     /**
-     * the `experimental.iconSet` config value, when set
+     * the main set `experimental.iconSet` names
+     * (its first entry, when it is a list), when set
      */
     configured?: string | undefined;
+    /**
+     * the backup sets the list names after
+     * the main set, in order, when it names any
+     */
+    backups?: IconSetBackup[] | undefined;
+    /**
+     * the sets a template icon is looked
+     * up in, in order: the main set, then each backup that resolves. Present
+     * only when the main set is selected
+     */
+    order?: DiscoveredIconSet[] | undefined;
     /**
      * one sentence saying why
      */

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

@@ -99,6 +99,15 @@ export function hasLicenseNotice(dir) {
  * @property {string} reason
  */
 
+/**
+ * One backup set the project's list names, and what it resolves to.
+ * @typedef {object} IconSetBackup
+ * @property {string} selector the name as the list writes it
+ * @property {'selected' | 'ambiguous' | 'missing' | 'withdrawn'} status
+ * @property {DiscoveredIconSet} [set] the set, when selected
+ * @property {string} reason one sentence saying why
+ */
+
 /**
  * The project's icon set (FR8).
  * @typedef {object} IconSetChoice
@@ -109,7 +118,13 @@ export function hasLicenseNotice(dir) {
  *   `withdrawn`: it names a set that is installed but withdrawn (invalid, or
  *   its module does not resolve), and `reason` says why
  * @property {DiscoveredIconSet} [set] the project's set, when selected
- * @property {string} [configured] the `experimental.iconSet` config value, when set
+ * @property {string} [configured] the main set `experimental.iconSet` names
+ *   (its first entry, when it is a list), when set
+ * @property {IconSetBackup[]} [backups] the backup sets the list names after
+ *   the main set, in order, when it names any
+ * @property {DiscoveredIconSet[]} [order] the sets a template icon is looked
+ *   up in, in order: the main set, then each backup that resolves. Present
+ *   only when the main set is selected
  * @property {string} reason one sentence saying why
  */
 
@@ -407,55 +422,126 @@ export function withdrawnNamed(withdrawn, selector) {
 }
 
 /**
- * Pick the project's icon set (FR8, FR17): the set `experimental.iconSet`
- * names, as `"<set>"` or `"<package>/<set>"`; otherwise the only installed
+ * The entries of an `experimental.iconSet` value, main set first: a string is
+ * a one-entry list.
+ * @param {string | readonly string[] | undefined} configured
+ * @returns {string[]}
+ */
+export function iconSetList(configured) {
+  if (configured == null) return [];
+  return typeof configured === 'string' ? [configured] : [...configured];
+}
+
+/**
+ * What one name in the list resolves to: a set, or why not.
+ * @param {DiscoveredIconSet[]} sets
+ * @param {string} selector `"<set>"` or `"<package>/<set>"`
+ * @param {WithdrawnIconSet[]} withdrawn
+ * @returns {{status: 'selected' | 'ambiguous' | 'missing' | 'withdrawn', set?: DiscoveredIconSet, reason: string}}
+ */
+function resolveSelector(sets, selector, withdrawn) {
+  const exact = sets.filter(set => `${set.package}/${set.name}` === selector);
+  const byName =
+    exact.length > 0 ? exact : sets.filter(set => set.name === selector);
+  if (byName.length === 1) {
+    return {
+      status: 'selected',
+      set: byName[0],
+      reason: `experimental.iconSet names "${selector}".`,
+    };
+  }
+  if (byName.length > 1) {
+    return {
+      status: 'ambiguous',
+      reason: `experimental.iconSet "${selector}" names a set in ${byName.map(set => set.package).join(' and ')}; write it as "<package>/<set>".`,
+    };
+  }
+  const gone = withdrawnNamed(withdrawn, selector);
+  if (gone.length > 0) {
+    return {
+      status: 'withdrawn',
+      reason: `experimental.iconSet names "${selector}", which is installed but withdrawn: ${gone.map(each => each.reason).join(' ')}`,
+    };
+  }
+  return {
+    status: 'missing',
+    reason: `experimental.iconSet names "${selector}", but no installed set has that name${sets.length > 0 ? ` (installed: ${sets.map(iconSetKey).join(', ')})` : ''}.`,
+  };
+}
+
+/** The command that chooses a main set and backups, as the CLI prints it. */
+export const ICON_USE_ORDER_COMMAND =
+  'astryx experimental icon use <main> --backup <set>';
+
+/**
+ * Installed sets the project's list leaves out: the problem, and the fix that
+ * adds them as backups after the list's own. Doctor and `experimental icon
+ * use` print the same words.
+ * @param {number} installed how many sets are installed
+ * @param {string} main the main set as the list writes it
+ * @param {string[]} backups the list's backups, in order
+ * @param {string[]} unlisted the installed sets the list leaves out
+ * @returns {{problem: string, command: string, fix: string}}
+ */
+export function unlistedIconSets(installed, main, backups, unlisted) {
+  const them = unlisted.length === 1 ? 'it' : 'them';
+  const command = `astryx experimental icon use ${main}${[...backups, ...unlisted].map(each => ` --backup ${each}`).join('')}`;
+  return {
+    problem: `${installed} icon sets are installed and ${unlisted.join(', ')} ${unlisted.length === 1 ? 'is' : 'are'} not in your list`,
+    command,
+    fix: `Add ${them} as backup with \`${command}\`, or uninstall ${them}.`,
+  };
+}
+
+/**
+ * Pick the project's icon set (FR8, FR17): the main set `experimental.iconSet`
+ * names, as `"<set>"` or `"<package>/<set>"`, or as the first entry of a list
+ * whose other entries are backup sets in order; otherwise the only installed
  * set; otherwise none. A configured name that matches no valid set but an
  * installed set that was withdrawn says so, with why.
  * @param {DiscoveredIconSet[]} sets installed sets, in integration load order
- * @param {string | undefined} configured the `experimental.iconSet` config value
+ * @param {string | readonly string[] | undefined} configured the `experimental.iconSet` config value
  * @param {WithdrawnIconSet[]} [withdrawn] installed sets that were withdrawn
  * @returns {IconSetChoice}
  */
 export function chooseProjectIconSet(sets, configured, withdrawn = []) {
-  if (configured) {
-    const exact = sets.filter(
-      set => `${set.package}/${set.name}` === configured,
-    );
-    const byName =
-      exact.length > 0 ? exact : sets.filter(set => set.name === configured);
-    if (byName.length === 1) {
-      return {
-        status: 'selected',
-        set: byName[0],
-        configured,
-        reason: `experimental.iconSet names "${configured}".`,
-      };
-    }
-    if (byName.length > 1) {
-      return {
-        status: 'ambiguous',
-        configured,
-        reason: `experimental.iconSet "${configured}" names a set in ${byName.map(set => set.package).join(' and ')}; write it as "<package>/<set>".`,
-      };
-    }
-    const gone = withdrawnNamed(withdrawn, configured);
-    if (gone.length > 0) {
-      return {
-        status: 'withdrawn',
-        configured,
-        reason: `experimental.iconSet names "${configured}", which is installed but withdrawn: ${gone.map(each => each.reason).join(' ')}`,
-      };
-    }
-    return {
-      status: 'missing',
-      configured,
-      reason: `experimental.iconSet names "${configured}", but no installed set has that name${sets.length > 0 ? ` (installed: ${sets.map(iconSetKey).join(', ')})` : ''}.`,
+  const [main, ...rest] = iconSetList(configured);
+  if (main) {
+    const resolved = resolveSelector(sets, main, withdrawn);
+    /** @type {IconSetBackup[]} */
+    const backups = rest.map(selector => ({
+      selector,
+      ...resolveSelector(sets, selector, withdrawn),
+    }));
+    /** @type {IconSetChoice} */
+    const choice = {
+      status: resolved.status,
+      ...(resolved.set ? {set: resolved.set} : {}),
+      configured: main,
+      ...(backups.length > 0 ? {backups} : {}),
+      reason: resolved.reason,
     };
+    if (resolved.set) {
+      /** @type {DiscoveredIconSet[]} */
+      const order = [resolved.set];
+      for (const backup of backups) {
+        if (backup.set && !order.includes(backup.set)) order.push(backup.set);
+      }
+      choice.order = order;
+      if (order.length > 1) {
+        choice.reason = `experimental.iconSet names "${main}", with ${order
+          .slice(1)
+          .map(set => `"${iconSetKey(set)}"`)
+          .join(', then ')} as backup.`;
+      }
+    }
+    return choice;
   }
   if (sets.length === 1) {
     return {
       status: 'selected',
       set: sets[0],
+      order: [sets[0]],
       reason: `"${iconSetKey(sets[0])}" is the only installed icon set.`,
     };
   }
@@ -464,7 +550,7 @@ export function chooseProjectIconSet(sets, configured, withdrawn = []) {
   }
   return {
     status: 'ambiguous',
-    reason: `${sets.length} icon sets are installed (${sets.map(iconSetKey).join(', ')}) and astryx.config sets no experimental.iconSet.`,
+    reason: `${sets.length} icon sets are installed (${sets.map(iconSetKey).join(', ')}) and astryx.config sets no experimental.iconSet, so none is your main set.`,
   };
 }
 
@@ -477,13 +563,13 @@ export function iconSetKey(set) {
 }
 
 /**
- * Sets in tie order (FR6, FR8): the project's set first, then load order.
+ * Sets in tie order (FR6, FR8): the project's set and its backups first, in
+ * list order, then load order.
  * @param {DiscoveredIconSet[]} sets
  * @param {IconSetChoice} choice
  * @returns {DiscoveredIconSet[]}
  */
 export function orderIconSets(sets, choice) {
-  const first = choice.set;
-  if (!first) return [...sets];
-  return [first, ...sets.filter(set => set !== first)];
+  const first = choice.order ?? (choice.set ? [choice.set] : []);
+  return [...first, ...sets.filter(set => !first.includes(set))];
 }

package/foundation/discovery/template-icon-notes.d.mts

@@ -11,5 +11,51 @@ export function templateIconNotes(loaded: any, packageDir: string): Promise<Arra
     code: string;
     message: string;
 }>>;
+/**
+ * One item the undeclared-icon check could not judge.
+ * @typedef {object} TemplateIconUnchecked
+ * @property {string} file the template, relative to the package
+ * @property {string} icon the imported name
+ * @property {string} module the module it is imported from
+ * @property {string} reason why, and what would let the check judge it
+ */
+/**
+ * One note per icon a template imports but does not declare in `icons`, and
+ * each import the check cannot judge. Only a package whose templates declare
+ * `icons` gets either: a package that never labels its icons sees no change.
+ * @param {any} loaded a loaded integration (absolute roots)
+ * @param {string} packageDir
+ * @returns {Promise<{notes: Array<{code: string, message: string}>, unchecked: TemplateIconUnchecked[]}>}
+ */
+export function templateIconUndeclaredNotes(loaded: any, packageDir: string): Promise<{
+    notes: Array<{
+        code: string;
+        message: string;
+    }>;
+    unchecked: TemplateIconUnchecked[];
+}>;
 /** A template `icons` key its source never imports. */
 export const TEMPLATE_ICON_NOT_IMPORTED: "template_icon_not_imported";
+/** An icon a template imports that its `icons` does not declare. */
+export const TEMPLATE_ICON_UNDECLARED: "template_icon_undeclared";
+/**
+ * One item the undeclared-icon check could not judge.
+ */
+export type TemplateIconUnchecked = {
+    /**
+     * the template, relative to the package
+     */
+    file: string;
+    /**
+     * the imported name
+     */
+    icon: string;
+    /**
+     * the module it is imported from
+     */
+    module: string;
+    /**
+     * why, and what would let the check judge it
+     */
+    reason: string;
+};

package/foundation/discovery/template-icon-notes.mjs

@@ -1,18 +1,25 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Template `icons` keys a template's source never imports (spec:AST-084
- * FR10).
+ * @file A template's `icons` checked against the icons its source imports.
  *
  * A template's `icons` names each icon it imports, by the name it imports or,
  * for a default import, its local name. A key that no import or re-export in
  * the template's source binds can never map to a project's icon set, so each
- * one gets a note with its fix.
+ * one gets a note with its fix. An icon the template imports but does not
+ * declare never maps either: in a package whose templates declare `icons`,
+ * each one gets a note too, which `validate` marks `next`. An import counts
+ * only when the template renders it as an element without children or
+ * passes it as a value. Any other import from that module, a generic
+ * renderer, and an import that matches an icon by its name only, are listed
+ * as not checked instead.
  *
  * @input A loaded integration (absolute roots) and its package directory.
- * @output One `template_icon_not_imported` note per such key. A note is not an
- *   issue: it is never an error or a warning, and never fails a check, even
- *   under `--strict` (architecture:cli-surface INV35).
+ * @output One `template_icon_not_imported` note per such key, one
+ *   `template_icon_undeclared` note per undeclared icon, and each import not
+ *   rendered as an icon, generic renderer, or import matched by its name
+ *   only, as not checked. A note is never an error or a warning, even under
+ *   `--strict`.
  * @position foundation/discovery; read by `doctor integration validate` (and
  *   so `integration check`) for the package being authored.
  */
@@ -21,46 +28,117 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {loadTopicModule} from './docs-discovery.mjs';
 import {discoverIntegrationTemplatesForOne} from './template-adapter.mjs';
-import {iconsNotImported} from './template-icons.mjs';
+import {iconsNotImported, undeclaredTemplateIcons} from './template-icons.mjs';
 
 /** A template `icons` key its source never imports. */
 export const TEMPLATE_ICON_NOT_IMPORTED = 'template_icon_not_imported';
 
+/** An icon a template imports that its `icons` does not declare. */
+export const TEMPLATE_ICON_UNDECLARED = 'template_icon_undeclared';
+
 /**
- * One note per template `icons` key the template's source never imports.
+ * Each template in the package, with its source and its doc's `icons`. A
+ * template whose doc or source cannot be read is left out.
  * @param {any} loaded a loaded integration (absolute roots)
  * @param {string} packageDir
- * @returns {Promise<Array<{code: string, message: string}>>}
+ * @returns {Promise<Array<{id: string, docPath: string, source: string, declared: Record<string, string> | null}>>}
  */
-export async function templateIconNotes(loaded, packageDir) {
+async function readTemplates(loaded, packageDir) {
   if (!loaded.templates) return [];
   const {templates} = await discoverIntegrationTemplatesForOne(loaded).catch(
     () => ({templates: []}),
   );
-  /** @type {Array<{code: string, message: string}>} */
-  const notes = [];
   /** @param {string} file */
   const shown = file =>
     path.relative(packageDir, file).split(path.sep).join('/');
+  /** @type {Array<{id: string, docPath: string, source: string, declared: Record<string, string> | null}>} */
+  const read = [];
   for (const template of templates) {
     if (!template.docPath || !template.filePath) continue;
     const doc = /** @type {any} */ (
       await loadTopicModule(template.docPath).catch(() => null)
     );
-    const declared = doc?.icons;
-    if (declared == null || typeof declared !== 'object') continue;
     let source;
     try {
       source = fs.readFileSync(template.filePath, 'utf-8');
     } catch {
       continue;
     }
-    for (const key of iconsNotImported(source, declared) ?? []) {
+    read.push({
+      id: shown(template.filePath),
+      docPath: shown(template.docPath),
+      source,
+      declared:
+        doc?.icons != null && typeof doc.icons === 'object' ? doc.icons : null,
+    });
+  }
+  return read;
+}
+
+/**
+ * One note per template `icons` key the template's source never imports.
+ * @param {any} loaded a loaded integration (absolute roots)
+ * @param {string} packageDir
+ * @returns {Promise<Array<{code: string, message: string}>>}
+ */
+export async function templateIconNotes(loaded, packageDir) {
+  /** @type {Array<{code: string, message: string}>} */
+  const notes = [];
+  for (const template of await readTemplates(loaded, packageDir)) {
+    if (!template.declared) continue;
+    for (const key of iconsNotImported(template.source, template.declared) ??
+      []) {
       notes.push({
         code: TEMPLATE_ICON_NOT_IMPORTED,
-        message: `${shown(template.docPath)} declares icon "${key}" in \`icons\`, which ${shown(template.filePath)} does not import, so it never maps to a project's icon set. Name a named import by the name it imports and a default import by its local name, or remove "${key}" from \`icons\`.`,
+        message: `${template.docPath} declares icon "${key}" in \`icons\`, which ${template.id} does not import, so it never maps to a project's icon set. Name a named import by the name it imports and a default import by its local name, or remove "${key}" from \`icons\`.`,
       });
     }
   }
   return notes;
 }
+
+/**
+ * One item the undeclared-icon check could not judge.
+ * @typedef {object} TemplateIconUnchecked
+ * @property {string} file the template, relative to the package
+ * @property {string} icon the imported name
+ * @property {string} module the module it is imported from
+ * @property {string} reason why, and what would let the check judge it
+ */
+
+/**
+ * One note per icon a template imports but does not declare in `icons`, and
+ * each import the check cannot judge. Only a package whose templates declare
+ * `icons` gets either: a package that never labels its icons sees no change.
+ * @param {any} loaded a loaded integration (absolute roots)
+ * @param {string} packageDir
+ * @returns {Promise<{notes: Array<{code: string, message: string}>, unchecked: TemplateIconUnchecked[]}>}
+ */
+export async function templateIconUndeclaredNotes(loaded, packageDir) {
+  const read = (await readTemplates(loaded, packageDir)).map(each => ({
+    ...each,
+    declared: each.declared ?? {},
+  }));
+  if (!read.some(each => Object.keys(each.declared).length > 0)) {
+    return {notes: [], unchecked: []};
+  }
+  const docOf = new Map(read.map(each => [each.id, each.docPath]));
+  const {undeclared, unchecked} = undeclaredTemplateIcons(read);
+  return {
+    notes: undeclared.map(({id, key, module}) => ({
+      code: TEMPLATE_ICON_UNDECLARED,
+      message: `${id} imports icon "${key}" from ${module}, but ${docOf.get(id)} does not declare it in \`icons\`, so it never follows a project's icon set. Add \`${key}: '<definition>'\` to \`icons\` (\`astryx experimental icon --definitions\` lists the definitions).`,
+    })),
+    unchecked: unchecked.map(({id, key, module, why}) => ({
+      file: id,
+      icon: key,
+      module,
+      reason:
+        why === 'renderer'
+          ? `"${key}" is a generic renderer: it is a bare \`Icon\`, or every use gives it an icon prop, so it draws no one icon definition and needs no \`icons\` key.`
+          : why === 'use'
+            ? `"${key}" is not rendered as an icon: the template never renders it as an element without children or passes it as a value, so it needs no \`icons\` key. Declaring it would make \`astryx template\` swap it for an icon.`
+            : `"${key}" matches an icon by its name only: no template in the package declares an icon from ${module}, so the check cannot tell whether it draws one icon definition. Declare an icon from ${module} in a template's \`icons\` to have its imports checked.`,
+    })),
+  };
+}