@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/api/component/list/list.mjs

@@ -16,6 +16,7 @@ import {
   discoverComponents,
   discoverExternalComponentsGrouped,
   discoverValidIntegrationComponents,
+  familyMember,
   findComponentReadme,
   findExternalComponentDoc,
   resolveImportPath,
@@ -66,6 +67,33 @@ async function legacyImport(ext, name, coreDir, docOpts) {
  */
 const coreEntry = doc => ({name: doc.name, package: CORE_PACKAGE, ...doc});
 
+/**
+ * The full-level entry for a component documented as a member of its family's
+ * doc (VStack in Stack's doc): a component doc built from the member's own
+ * entry, under its own name, display name and import, shaped like every other
+ * full entry. Null when the doc is the component's own.
+ * @param {any} docs
+ * @param {string} name
+ * @param {string} coreDir
+ * @returns {any}
+ */
+function memberEntry(docs, name, coreDir) {
+  const member = familyMember(docs, name);
+  if (!member) return null;
+  return {
+    name,
+    package: CORE_PACKAGE,
+    displayName: member.displayName ?? name,
+    ...(docs.group ? {group: docs.group} : {}),
+    ...(docs.category ? {category: docs.category} : {}),
+    usage: member.usage ?? {description: member.description ?? ''},
+    props: member.props ?? [],
+    ...(member.examples ? {examples: member.examples} : {}),
+    ...(docs.theming ? {theming: docs.theming} : {}),
+    import: resolveImportPath(coreDir, name),
+  };
+}
+
 /**
  * The entry for a Core slot an integration component replaces
  * (spec:AST-035 FR11), at the list's detail level: the replacement's own name,
@@ -177,7 +205,11 @@ export async function componentList(
             entries.push({
               name: comp,
               package: CORE_PACKAGE,
-              description: docs.usage?.description || docs.description || '',
+              description:
+                familyMember(docs, comp)?.description ||
+                docs.usage?.description ||
+                docs.description ||
+                '',
               import: resolveImportPath(coreDir, comp),
             });
           } catch {
@@ -215,7 +247,8 @@ export async function componentList(
         const readme = findComponentReadme(coreDir, comp);
         if (readme && readme.endsWith('.doc.mjs')) {
           try {
-            entries.push(coreEntry(await loadComponentDoc(readme, {zh, lang, dense})));
+            const docs = await loadComponentDoc(readme, {zh, lang, dense});
+            entries.push(memberEntry(docs, comp, coreDir) ?? coreEntry(docs));
           } catch {
             entries.push({name: `XDS${comp}`, package: CORE_PACKAGE, description: ''});
           }
@@ -269,7 +302,11 @@ export async function componentList(
             result[cat].push({
               name: comp,
               package: CORE_PACKAGE,
-              description: docs.usage?.description || docs.description || '',
+              description:
+                familyMember(docs, comp)?.description ||
+                docs.usage?.description ||
+                docs.description ||
+                '',
               import: resolveImportPath(coreDir, comp),
             });
           } catch {
@@ -310,7 +347,8 @@ export async function componentList(
         const readme = findComponentReadme(coreDir, comp);
         if (readme && readme.endsWith('.doc.mjs')) {
           try {
-            result[cat].push(coreEntry(await loadComponentDoc(readme, {zh, lang, dense})));
+            const docs = await loadComponentDoc(readme, {zh, lang, dense});
+            result[cat].push(memberEntry(docs, comp, coreDir) ?? coreEntry(docs));
           } catch {
             result[cat].push({name: `XDS${comp}`, package: CORE_PACKAGE, description: ''});
           }

package/api/discover/_adapter.d.mts

@@ -36,19 +36,47 @@ export function describeInstalled(project: Project | undefined, scanned: Scanned
  * @returns {boolean}
  */
 export function hasSources(project: Project | undefined): boolean;
+/**
+ * The integrations installed for the computer that a project could add, as
+ * available entries with the project's install command (spec AST-081 FR12).
+ * Empty outside a project, where they load instead.
+ * @param {Project | undefined} project
+ * @param {Array<{name: string}>} installed
+ * @param {Set<string>} declared
+ * @param {(name: string, version?: string) => string} add
+ * @returns {Promise<import('./discover.type.mjs').DiscoverAvailableEntry[]>}
+ */
+export function computerAvailableEntries(project: Project | undefined, installed: Array<{
+    name: string;
+}>, declared: Set<string>, add: (name: string, version?: string) => string): Promise<import("./discover.type.mjs").DiscoverAvailableEntry[]>;
 /**
  * Package names the project's package.json declares in any dependency field.
  * @param {Project | undefined} project
  * @returns {Set<string>}
  */
 export function declaredDependencies(project: Project | undefined): Set<string>;
+/**
+ * What the project's own package.json, the nearest one above the folder
+ * discover runs in, declares among the official packages.
+ * @param {Project | undefined} project
+ * @param {OfficialPackage[]} official
+ * @returns {OfficialDeclarations}
+ */
+export function officialDeclarations(project: Project | undefined, official: OfficialPackage[]): OfficialDeclarations;
 /**
  * The command that adds a package with the project's package manager. Discover
- * only prints it; it never runs it.
+ * only prints it; it never runs it. Asked for one version, it adds that
+ * version. Given the official list, it otherwise pins an official package to
+ * what its entry names (spec:AST-051 FR2): the project's Core version or
+ * declared Core range, else the latest release. A range is quoted, because
+ * `^`, `<`, `>`, `|` and spaces mean something to a shell.
  * @param {Project | undefined} project
+ * @param {{official?: OfficialPackage[]}} [options]
  * @returns {(name: string, version?: string) => string}
  */
-export function addCommand(project: Project | undefined): (name: string, version?: string) => string;
+export function addCommand(project: Project | undefined, { official }?: {
+    official?: OfficialPackage[];
+}): (name: string, version?: string) => string;
 /**
  * The per-user cache directory the saved copies live in, never inside a
  * project. Standard platform locations only.
@@ -56,15 +84,17 @@ export function addCommand(project: Project | undefined): (name: string, version
  */
 export function defaultCacheDir(): string;
 /**
- * Call every discover source — the project's `discover` first, then each
- * integration's in load order — once per distinct function. A source that
- * throws, times out, or returns an invalid catalog falls back to its saved copy;
- * with none, it is reported and adds nothing. The others always count.
+ * Call every discover source (see {@link callOwnSources}), then read the
+ * official list (spec:AST-051 FR11). The list comes last, so a source keeps
+ * its entry for an official package, or for any package of the same
+ * integration (FR7); the list adds the official packages no source covers.
+ * The result stays in source order; discover puts official packages first
+ * only where it shows them ({@link officialFirst}).
  *
  * @param {Project | undefined} project
- * @param {{package?: string, version?: string}} [request] ask for one package,
- *   and optionally one version's contributions
- * @param {{cacheDir?: string, timeoutMs?: number}} [options]
+ * @param {{package?: string, version?: string}} [request]
+ * @param {{cacheDir?: string, timeoutMs?: number, official?: OfficialList}} [options]
+ *   `official`: the list {@link officialList} read; read here when absent
  * @returns {Promise<CatalogResult>}
  */
 export function callSources(project: Project | undefined, request?: {
@@ -73,7 +103,62 @@ export function callSources(project: Project | undefined, request?: {
 }, options?: {
     cacheDir?: string;
     timeoutMs?: number;
+    official?: OfficialList;
 }): Promise<CatalogResult>;
+/**
+ * Official packages first, in the official list's order; the rest keep theirs.
+ * @template T
+ * @param {T[]} items
+ * @param {OfficialPackage[]} official
+ * @param {(item: T) => string} nameOf
+ * @returns {T[]}
+ */
+export function officialFirst<T>(items: T[], official: OfficialPackage[], nameOf: (item: T) => string): T[];
+/**
+ * The official list this CLI carries (spec:AST-051 FR11). The file holds no
+ * versions; each entry takes them from this CLI and the project:
+ *
+ * - Its latest release is the newest release this CLI knows: its own version
+ *   on a release CLI, or the project's Core version when that is a newer
+ *   release.
+ * - A package released with Core lists a release CLI's own version and the
+ *   project's Core version (installed, else declared exactly), so each,
+ *   the latest release included, can be looked up. Its add command pins the project's Core version, else the Core range
+ *   the project declares, else the latest release; nothing on a canary CLI in
+ *   a project with no Core, which may have been published without it.
+ * - A canary-only package is listed only by a canary CLI, as a prerelease at
+ *   the project's Core version when that is a prerelease, else at the CLI's
+ *   own version when the project has no Core. It is not listed beside a
+ *   released or declared Core, which it cannot be installed with.
+ *
+ * @param {{file?: string, version?: string, project?: Project}} [options] the
+ *   list file and the CLI version to read it for, both defaulting to this
+ *   CLI's own, and the project whose Core decides the versions
+ * @returns {OfficialList}
+ */
+export function officialList({ file, version, project, }?: {
+    file?: string;
+    version?: string;
+    project?: Project;
+}): OfficialList;
+/**
+ * What the project has: its installed integrations plus each official package
+ * its own package.json declares as a dependency whose entry the official list
+ * supplied, official packages first. A declared official package that a source
+ * lists stays as that source shows it (FR7). One that failed to load as an
+ * integration stays out. A declared one takes what it adds from the list and
+ * its version from the copy the project installed, under an npm alias too.
+ *
+ * @param {Project | undefined} project
+ * @param {InstalledPackage[]} installed from {@link describeInstalled}
+ * @param {CatalogResult} catalog
+ * @param {OfficialDeclarations} declared from {@link officialDeclarations}
+ * @param {OfficialPackage[]} official the official list, for the order
+ * @returns {Array<InstalledPackage & {declaredOfficial?: true}>}
+ */
+export function withDeclaredOfficial(project: Project | undefined, installed: InstalledPackage[], catalog: CatalogResult, declared: OfficialDeclarations, official: OfficialPackage[]): Array<InstalledPackage & {
+    declaredOfficial?: true;
+}>;
 /**
  * Project a scanned or installed package into the discover list/detail entry
  * shape. Shared by the list and detail leaves so the entry keys (and their
@@ -104,11 +189,43 @@ export function loadValidatedDoc(result: ComponentResolution, { lang, zh }: {
     lang?: string | null;
     zh?: boolean;
 }): Promise<import("./discover.type.mjs").DiscoverDetailDocResponse["data"]>;
+/** The name the official list goes by, as a source and on each of its entries. */
+export const OFFICIAL_SOURCE_NAME: "Astryx";
+/** The official list, generated from the repository when the CLI is built. */
+export const OFFICIAL_LIST_FILE: string;
 /** The list and detail entry fields for each item kind, in display order. */
 export const KIND_FIELDS: readonly [readonly ["component", "components"], readonly ["template", "templates"], readonly ["doc", "docs"], readonly ["theme", "themes"], readonly ["codemod", "codemods"], readonly ["agent-doc", "agentDocs"]];
 export type ScannedPackage = import("./_package-scanner.mjs").ScannedPackage;
 export type DiscoverPackage = import("../../authoring/discover/type").DiscoverPackage;
 export type DiscoverSource = import("../../authoring/discover/type").DiscoverSource;
+/**
+ * An official package as this CLI lists it (spec:AST-051 FR11), with what its
+ * add command pins (FR2): the project's Core version, the Core range the
+ * project declares, or the latest release; with none, it pins nothing.
+ */
+export type OfficialPackage = DiscoverPackage & {
+    pin?: string;
+};
+/**
+ * The official packages the project's package.json declares: the real package
+ * name of each, mapped to the name it is installed under (an npm alias such as
+ * `"my-theme": "npm:@astryxdesign/theme-gothic@0.7.0"` installs under
+ * `my-theme`). `dependency` holds those declared in dependencies,
+ * devDependencies or optionalDependencies, which make a package the project's
+ * own; `any` adds peerDependencies, which only keep it from being offered.
+ */
+export type OfficialDeclarations = {
+    dependency: Map<string, string>;
+    any: Set<string>;
+};
+/**
+ * The official list as this CLI reads it. `error` says why the file could not
+ * be read; the list is then empty and discover reports it like a failed source.
+ */
+export type OfficialList = {
+    packages: OfficialPackage[];
+    error?: string;
+};
 /**
  * An installed integration with what it adds, per kind. `components` is the
  * scanned component list the discover leaves have always used.
@@ -129,7 +246,8 @@ export type SourceState = {
      */
     name: string;
     /**
-     * `astryx.config`, or the integration that exports it
+     * `astryx.config`, the integration that exports it, or
+     * `@astryxdesign/cli` for the official list
      */
     from: string;
     status: "fresh" | "saved" | "failed";
@@ -145,13 +263,15 @@ export type SourceState = {
     error?: string | undefined;
 };
 /**
- * Everything every source returned, merged. When two sources list the same
- * package, the earlier source's entry is kept.
+ * Everything every source returned, merged, the official list last. When two
+ * sources list the same package, the earlier source's entry is kept. `official`
+ * marks an entry the official list supplied.
  */
 export type CatalogResult = {
     sources: SourceState[];
     packages: Array<DiscoverPackage & {
         source: string;
+        official?: true;
     }>;
 };
 /**