@astryxdesign/cli 0.6.4-canary.ed2e54e → 0.6.4

package/api/discover/search/search.mjs

@@ -1,76 +1,44 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file discover.search leaf — free-text search across installed packages and,
- * when the project has discover sources, everything it could add.
+ * @file discover.search leaf — free-text search across external packages.
  *
- * A free-text query always answers with a list, so its response type depends
- * on the form of the query and never on what the project has:
- *   1. any matches                -> discover.search
- *   2. fuzzy hits (distance <= 3) -> throw ERR_NOT_FOUND with suggestions
- *   3. otherwise                  -> throw ERR_NOT_FOUND
- * Matches are installed components, the project's other installed items,
- * packages, and every item a source lists for a package the project could add.
- * A caller opens one item by its package path, which ../detail answers.
+ * Resolution order (matching the flat command exactly):
+ *   1. exact component name  -> discover.detail.doc
+ *   2. single substring hit  -> discover.detail.doc
+ *   3. multiple substring hits -> discover.search
+ *   4. fuzzy hits (distance <= 3) -> throw ERR_NOT_FOUND with suggestions
+ *   5. otherwise             -> throw ERR_NOT_FOUND
  *
- * @position api/discover/search — pure ranking over the installed component
- *   names and ../_catalog-view's search items.
+ * @position api/discover/search — projection over ../_adapter's resolver;
+ *   delegates the single-component cases to ../detail/doc.
  */
 
+import {findComponent} from '../_adapter.mjs';
+import {docFromResult} from '../detail/doc/doc.mjs';
 import {levenshteinDistance} from '../../../foundation/text/string-utils.mjs';
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
-import {DISCOVER_KINDS} from '../../../authoring/discover/parse.mjs';
 
 /**
  * @typedef {import('../_package-scanner.mjs').ScannedPackage} ScannedPackage
- * @typedef {import('../_catalog-view.mjs').SearchItem} SearchItem
  */
 
-const KIND_ORDER = ['package', ...DISCOVER_KINDS];
-
-/**
- * How well an item matches: 0 exact name, 1 name prefix, 2 name substring,
- * 3 title, summary, keyword, or description; null for no match.
- * @param {SearchItem} item
- * @param {string} lower
- * @returns {number | null}
- */
-function rank(item, lower) {
-  const name = item.name.toLowerCase();
-  if (name === lower) return 0;
-  if (name.startsWith(lower)) return 1;
-  if (name.includes(lower)) return 2;
-  const text = [
-    item.title,
-    item.summary,
-    item.description,
-    ...(item.keywords ?? []),
-  ]
-    .filter(Boolean)
-    .join('\n')
-    .toLowerCase();
-  return text.includes(lower) ? 3 : null;
-}
-
 /**
  * Search all packages for `query` (a free-text term that never starts with
- * `@`). Resolves to a search response when anything matches, even a single
- * item or an exact component name, or throws AstryxError (ERR_NOT_FOUND) —
- * with fuzzy suggestions when any exist.
+ * `@`). Resolves to a single component's docs when unambiguous, a search
+ * response when several match, or throws AstryxError (ERR_NOT_FOUND) — with
+ * fuzzy suggestions when any exist.
  *
- * @param {ScannedPackage[]} packages installed packages
+ * @param {ScannedPackage[]} packages
  * @param {string} query
- * @param {{
- *   items?: SearchItem[],
- *   type?: import('../../../authoring/discover/type').DiscoverKind,
- *   only?: 'installed' | 'available',
- *   limit?: number,
- * }} opts
- * @returns {Promise<import('../discover.type.mjs').DiscoverSearchResponse>}
+ * @param {{lang?: string | null, zh?: boolean}} opts
+ * @returns {Promise<
+ *   import('../discover.type.mjs').DiscoverDetailDocResponse |
+ *   import('../discover.type.mjs').DiscoverSearchResponse
+ * >}
  */
-export async function search(packages, query, opts) {
-  const {items = [], type, only, limit} = opts;
+export async function search(packages, query, {lang, zh}) {
   // An empty query must error, not match every component via `.includes('')`
   // (parity with the api/search leaf). The discover() dispatcher already routes
   // an empty query to list, but the leaf must be safe on its own.
@@ -83,64 +51,50 @@ export async function search(packages, query, opts) {
   }
   const lower = query.toLowerCase();
 
-  /** @type {SearchItem[]} */
-  const installedComponents = packages.flatMap(pkg =>
-    pkg.components.map(name => ({
-      package: pkg.name,
-      kind: /** @type {const} */ ('component'),
-      name,
-      installed: true,
-    })),
-  );
+  const exact = findComponent(packages, query);
+  if (exact) return await docFromResult(exact, {lang, zh});
 
-  const ranked = [...installedComponents, ...items]
-    .filter(item => (type == null ? true : item.kind === type))
-    .filter(item =>
-      only === 'installed'
-        ? item.installed
-        : only === 'available'
-          ? !item.installed
-          : true,
-    )
-    .map(item => ({item, score: rank(item, lower)}))
-    .filter(
-      /** @returns {m is {item: SearchItem, score: number}} */
-      m => m.score != null,
-    )
-    .sort(
-      (a, b) =>
-        a.score - b.score ||
-        Number(b.item.installed) - Number(a.item.installed) ||
-        KIND_ORDER.indexOf(a.item.kind) - KIND_ORDER.indexOf(b.item.kind) ||
-        a.item.package.localeCompare(b.item.package) ||
-        a.item.name.localeCompare(b.item.name),
-    );
+  const substringMatches =
+    /** @type {Array<{pkg: ScannedPackage, comp: string}>} */ ([]);
+  for (const pkg of packages) {
+    for (const comp of pkg.components) {
+      if (comp.toLowerCase().includes(lower)) {
+        substringMatches.push({pkg, comp});
+      }
+    }
+  }
 
-  if (ranked.length > 0) {
-    const matches = ranked.map(({item}) => ({
-      package: item.package,
-      component: item.name,
-      kind: item.kind,
-      installed: item.installed,
-      ...(item.title ? {title: item.title} : {}),
-      ...(item.summary ? {summary: item.summary} : {}),
-    }));
-    const shown = limit == null ? matches : matches.slice(0, limit);
+  if (substringMatches.length === 1) {
+    const match = substringMatches[0];
+    const result = findComponent([match.pkg], match.comp);
+    if (result) return await docFromResult(result, {lang, zh});
+  }
+
+  if (substringMatches.length > 1) {
     return {
       type: 'discover.search',
       data: {
         query,
-        matches: shown,
-        ...(shown.length < matches.length ? {total: matches.length} : {}),
+        matches: substringMatches.map(m => ({
+          package: m.pkg.name,
+          component: m.comp,
+        })),
       },
     };
   }
 
-  // Fuzzy fallback over installed components.
-  const fuzzyMatches = installedComponents
-    .map(entry => ({
-      ...entry,
-      distance: levenshteinDistance(lower, entry.name.toLowerCase()),
+  // Fuzzy fallback
+  const allComponents =
+    /** @type {Array<{pkg: ScannedPackage, comp: string}>} */ ([]);
+  for (const pkg of packages) {
+    for (const comp of pkg.components) {
+      allComponents.push({pkg, comp});
+    }
+  }
+  const fuzzyMatches = allComponents
+    .map(item => ({
+      ...item,
+      distance: levenshteinDistance(lower, item.comp.toLowerCase()),
     }))
     .filter(m => m.distance <= 3)
     .sort((a, b) => a.distance - b.distance)
@@ -150,7 +104,7 @@ export async function search(packages, query, opts) {
     throw new AstryxError(
       `"${query}" not found`,
       fuzzyMatches.map(m => ({
-        name: m.package + '/' + m.name,
+        name: m.pkg.name + '/' + m.comp,
         reason: 'similar name',
       })),
       ERROR_CODES.ERR_NOT_FOUND,

package/api/discover/search/search.test.mjs

@@ -1,8 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Colocated tests for the discover.search leaf, over a small temp docs
- * directory shaped like a scanned package.
+ * @file Colocated tests for the discover.search leaf. Exact/single matches load
+ * a real `.doc.mjs`, so these drive a small temp docs directory.
  */
 
 import {describe, it, expect, beforeAll, afterAll} from 'vitest';
@@ -47,31 +47,16 @@ afterAll(() => {
 });
 
 describe('discover.search leaf', () => {
-  it('lists an exact component name first, with every other match', async () => {
+  it('an exact component name resolves to its docs', async () => {
     const res = await search(packages, 'Alpha', {});
-    expect(res.type).toBe('discover.search');
-    expect(res.data.matches.map(m => m.component)).toEqual([
-      'Alpha',
-      'AlphaCard',
-    ]);
+    expect(res.type).toBe('discover.detail.doc');
+    expect(res.data.name).toBe('Alpha');
   });
 
-  it('lists a single match too, so the response type never depends on the data', async () => {
+  it('a single substring match resolves to its docs', async () => {
     const res = await search(packages, 'card', {});
-    expect(res).toEqual({
-      type: 'discover.search',
-      data: {
-        query: 'card',
-        matches: [
-          {
-            package: '@acme/widgets',
-            component: 'AlphaCard',
-            kind: 'component',
-            installed: true,
-          },
-        ],
-      },
-    });
+    expect(res.type).toBe('discover.detail.doc');
+    expect(res.data.name).toBe('AlphaCard');
   });
 
   it('multiple substring matches return a search response', async () => {
@@ -81,18 +66,8 @@ describe('discover.search leaf', () => {
       data: {
         query: 'alph',
         matches: [
-          {
-            package: '@acme/widgets',
-            component: 'Alpha',
-            kind: 'component',
-            installed: true,
-          },
-          {
-            package: '@acme/widgets',
-            component: 'AlphaCard',
-            kind: 'component',
-            installed: true,
-          },
+          {package: '@acme/widgets', component: 'Alpha'},
+          {package: '@acme/widgets', component: 'AlphaCard'},
         ],
       },
     });
@@ -141,112 +116,3 @@ describe('discover.search leaf — empty query (parity with api/search)', () =>
     });
   });
 });
-
-describe('discover.search leaf across every kind and source', () => {
-  /** @type {any[]} */
-  const items = [
-    {
-      package: '@acme/widgets',
-      kind: 'template',
-      name: 'pages/AlphaHome',
-      installed: true,
-    },
-    {
-      package: '@acme/charts',
-      kind: 'package',
-      name: '@acme/charts',
-      installed: false,
-      description: 'Charts for alpha dashboards',
-    },
-    {
-      package: '@acme/charts',
-      kind: 'component',
-      name: 'AlphaChart',
-      installed: false,
-    },
-    {
-      package: '@acme/charts',
-      kind: 'doc',
-      name: 'guide',
-      installed: false,
-      summary: 'How to chart',
-    },
-  ];
-
-  it('ranks every match by how closely its name matches, installed first among equals', async () => {
-    const res = await search(packages, 'alph', {items});
-    expect(res.type).toBe('discover.search');
-    expect(
-      res.data.matches.map(m => [m.kind, m.component, m.installed]),
-    ).toEqual([
-      ['component', 'Alpha', true],
-      ['component', 'AlphaCard', true],
-      ['component', 'AlphaChart', false],
-      ['template', 'pages/AlphaHome', true],
-      ['package', '@acme/charts', false],
-    ]);
-  });
-
-  it('lists an exact installed component name with the matches from every source', async () => {
-    const res = await search(packages, 'Alpha', {items});
-    expect(res.type).toBe('discover.search');
-    expect(res.data.matches[0]).toEqual({
-      package: '@acme/widgets',
-      component: 'Alpha',
-      kind: 'component',
-      installed: true,
-    });
-    expect(res.data.matches.map(m => m.component)).toContain('AlphaChart');
-  });
-
-  it('lists a single partial component match when other items match too', async () => {
-    const res = await search(packages, 'card', {
-      items: [
-        ...items,
-        {
-          package: '@acme/charts',
-          kind: 'template',
-          name: 'pages/CardGrid',
-          installed: false,
-        },
-      ],
-    });
-    expect(res.type).toBe('discover.search');
-    expect(res.data.matches.map(m => m.component)).toEqual([
-      'AlphaCard',
-      'pages/CardGrid',
-    ]);
-  });
-
-  it('lists one installed component when nothing else matches', async () => {
-    const res = await search(packages, 'card', {items});
-    expect(res.type).toBe('discover.search');
-    expect(res.data.matches.map(m => m.component)).toEqual(['AlphaCard']);
-  });
-
-  it('keeps one kind with type, and one side with only', async () => {
-    const templates = await search(packages, 'alph', {items, type: 'template'});
-    expect(templates.data.matches.map(m => m.component)).toEqual([
-      'pages/AlphaHome',
-    ]);
-    const available = await search(packages, 'alph', {
-      items,
-      only: 'available',
-    });
-    expect(available.data.matches.map(m => m.component)).toEqual([
-      'AlphaChart',
-      '@acme/charts',
-    ]);
-  });
-
-  it('caps the list at limit and reports the total', async () => {
-    const res = await search(packages, 'alph', {items, limit: 2});
-    expect(res.data.matches).toHaveLength(2);
-    expect(res.data.total).toBe(5);
-  });
-
-  it('matches titles, summaries, keywords, and descriptions too', async () => {
-    const res = await search(packages, 'how to chart', {items});
-    expect(res.data.matches.map(m => m.component)).toEqual(['guide']);
-  });
-});

package/api/docs/docs.test.mjs

@@ -146,7 +146,6 @@ describe('docs() dispatcher routing', () => {
     // A guide moves across its namespace's slot, as any tree node does.
     expect(index.data.links).toEqual({
       up: 'astryx docs cli',
-      previous: 'astryx docs cli/component-lookups',
       next: 'astryx docs cli/writing-docs',
     });
     const first = (await docs('cli/integrations', index.data.sections[0].id)).data;
@@ -210,7 +209,6 @@ describe('docs() dispatcher routing', () => {
     expect(err).toBeInstanceOf(AstryxError);
     expect(err.code).toBe('ERR_UNKNOWN_SECTION');
     expect(err.suggestions.map(s => s.name)).toEqual([
-      'cli/component-lookups',
       'cli/integrations',
       'cli/writing-docs',
       'cli/commands',

package/api/doctor/doctor.d.mts

@@ -257,20 +257,15 @@ export type DoctorContext = {
      * could not be built, when it could not.
      */
     docsCatalogError?: string | null | undefined;
+    /**
+     * Combined project-level integration issues, including cross-package template replacement warnings.
+     */
     integrationIssues?: {
         package: string;
         code: string;
         severity: "warning" | "error";
         message: string;
     }[] | null | undefined;
-    /**
-     * installed dependencies whose integration manifest could not be loaded
-     * Combined project-level integration issues, including cross-package template replacement warnings.
-     */
-    autolinkFailures?: {
-        spec: string;
-        error: string;
-    }[] | null | undefined;
     /**
      * - Error thrown while resolving the config
      * path (e.g. multiple config files present), surfaced by checkConfig as a FAIL.

package/api/doctor/doctor.mjs

@@ -26,11 +26,7 @@ import * as path from 'node:path';
 import {MIN_NODE_VERSION, isNodeVersionSupported} from '../../foundation/env/node-version.mjs';
 import {CLI_ROOT, findCoreDir, findInstalledPackage} from '../../foundation/fs/paths.mjs';
 import {explainPackageManager, getCliInvocation} from '../../foundation/env/package-manager.mjs';
-import {
-  findConfigPath,
-  Project,
-  providerLedgerOf,
-} from '../../foundation/config/project.mjs';
+import {findConfigPath, Project} from '../../foundation/config/project.mjs';
 import {DocsCatalog} from '../../foundation/discovery/docs-discovery.mjs';
 import {buildDocsIndexData} from '../../foundation/discovery/docs-section-key.mjs';
 import {
@@ -80,8 +76,6 @@ import {semverCompare, isValidSemver, satisfiesRange} from '../../foundation/env
  * @property {string|null} [docsCatalogError] - Why the project's docs catalog
  *   could not be built, when it could not.
  * @property {Array<{package: string, code: string, severity: 'warning'|'error', message: string}>|null} [integrationIssues]
- * @property {Array<{spec: string, error: string}>|null} [autolinkFailures]
- *   installed dependencies whose integration manifest could not be loaded
  *   Combined project-level integration issues, including cross-package template replacement warnings.
  * @property {Error|null} [configError] - Error thrown while resolving the config
  *   path (e.g. multiple config files present), surfaced by checkConfig as a FAIL.
@@ -423,9 +417,6 @@ export function checkImplicitIntegrations(ctx) {
   const implicit = ctx.integrations.filter(
     integration => integration.__autolinked,
   );
-  // A dependency whose manifest cannot be loaded leaves no loaded record, so
-  // without this line doctor would say no dependency ships a manifest at all.
-  const unreadable = describeUnreadableManifests(ctx.autolinkFailures ?? []);
 
   if (implicit.length === 0) {
     return {
@@ -433,12 +424,9 @@ export function checkImplicitIntegrations(ctx) {
       label,
       status: 'info',
       message:
-        (ctx.integrations.length > 0
+        ctx.integrations.length > 0
           ? 'None — every loaded integration is named in astryx.config.'
-          : unreadable
-            ? 'None loaded.'
-            : 'None — no installed dependency ships an astryx.integration.* manifest.') +
-        unreadable,
+          : 'None — no installed dependency ships an astryx.integration.* manifest.',
     };
   }
 
@@ -451,25 +439,11 @@ export function checkImplicitIntegrations(ctx) {
       integration.__spec && integration.__spec !== integration.name
         ? ` (declared as "${integration.__spec}")`
         : '';
-    // A declared root counts only when it exists: the manifest's keys are a
-    // claim, and `integration-issues` reports the ones that are not true.
-    const declared = ['components', 'templates', 'themes', 'docs', 'codemods'].filter(
+    const roots = ['components', 'templates', 'themes', 'docs', 'codemods'].filter(
       root => integration[/** @type {'components'} */ (root)],
     );
-    const missing = declared.filter(root => {
-      const dir = integration[/** @type {'components'} */ (root)];
-      if (typeof dir !== 'string') return false;
-      const base =
-        typeof integration.__packageDir === 'string'
-          ? integration.__packageDir
-          : (ctx.cwd ?? process.cwd());
-      return !fs.existsSync(path.isAbsolute(dir) ? dir : path.resolve(base, dir));
-    });
-    const roots = declared.filter(root => !missing.includes(root));
     const contributes = roots.length > 0 ? roots.join(', ') : 'nothing';
-    const absent =
-      missing.length > 0 ? ` (declared ${missing.join(', ')} missing on disk)` : '';
-    return `${integration.name}${version}${alias} from ${integration.__dependencyField}, contributing ${contributes}${absent}`;
+    return `${integration.name}${version}${alias} from ${integration.__dependencyField}, contributing ${contributes}`;
   });
 
   const plural = implicit.length === 1 ? '' : 's';
@@ -479,8 +453,7 @@ export function checkImplicitIntegrations(ctx) {
     status: 'info',
     message:
       `${implicit.length} integration${plural} loaded from installed ` +
-      `dependencies with no astryx.config entry: ${described.join('; ')}.` +
-      unreadable,
+      `dependencies with no astryx.config entry: ${described.join('; ')}.`,
     fix:
       'Nothing to fix. Keep these dependencies installed. The CLI links them ' +
       'from package.json, so an unused-dependency check that looks only for ' +
@@ -489,30 +462,6 @@ export function checkImplicitIntegrations(ctx) {
   };
 }
 
-/**
- * The sentence `implicit-integrations` adds for dependencies whose manifest
- * could not be loaded, or '' when there are none. Still informational: the
- * package is a dependency's own bug, which `doctor integration validate`
- * diagnoses, but doctor must not report it as absent.
- * @param {Array<{spec: string, error: string}>} failures
- * @returns {string}
- */
-function describeUnreadableManifests(failures) {
-  if (failures.length === 0) return '';
-  const one = failures.length === 1;
-  const listed = failures
-    .map(({spec, error}) => {
-      const reason = String(error).split('\n')[0].slice(0, 160);
-      return `${spec} (${reason})`;
-    })
-    .join('; ');
-  return (
-    ` ${failures.length} installed ${one ? 'dependency ships' : 'dependencies ship'} ` +
-    `an astryx.integration.* manifest that could not be loaded, so ${one ? 'it contributes' : 'they contribute'} ` +
-    `nothing: ${listed}. Run \`astryx doctor integration validate <package>\` for details.`
-  );
-}
-
 /**
  * Check 7 — agent docs exist and contain the Astryx section markers.
  * @param {DoctorContext} ctx
@@ -789,26 +738,12 @@ export function checkProviderIdentity(ctx) {
     integration =>
       integration.providerId != null && integration.__loadError == null,
   ).length;
-  // An integration that could not be read has no provider ID to check, so the
-  // count above is not a complete survey. Say so instead of counting silently.
-  const unread = ctx.integrations.filter(
-    integration => integration.__loadError != null,
-  ).length;
-  const unreadNote =
-    unread === 0
-      ? ''
-      : unread === 1
-        ? ' 1 loaded integration could not be read, so its provider ID is unknown.'
-        : ` ${unread} loaded integrations could not be read, so their provider IDs are unknown.`;
   if (count === 0) {
     return {
       id,
       label,
       status: 'info',
-      message:
-        (unread === 0
-          ? 'None — no loaded integration has a provider identity.'
-          : 'No readable integration has a provider identity.') + unreadNote,
+      message: 'None — no loaded integration has a provider identity.',
     };
   }
   return {
@@ -816,10 +751,9 @@ export function checkProviderIdentity(ctx) {
     label,
     status: 'pass',
     message:
-      (count === 1
+      count === 1
         ? '1 loaded integration has its own provider ID.'
-        : `${count} loaded integrations each have their own provider ID.`) +
-      unreadNote,
+        : `${count} loaded integrations each have their own provider ID.`,
   };
 }
 
@@ -1264,25 +1198,11 @@ export async function runChecks(options = {}) {
   let docsCatalogError = null;
   /** @type {Array<{package: string, code: string, severity: 'warning'|'error', message: string}>|null} */
   let integrationIssues = null;
-  /** @type {Array<{spec: string, error: string}>|null} */
-  let autolinkFailures = null;
   try {
     const project = await Project.load(cwd);
     configTheme =
       /** @type {{theme?: string}} */ (project.config ?? {}).theme ?? null;
     integrations = project.loadedIntegrations;
-    // An installed dependency whose manifest cannot be loaded is kept out of
-    // loadedIntegrations on purpose. The provider ledger still records it.
-    autolinkFailures = [...providerLedgerOf(project).values()]
-      .filter(
-        entry =>
-          entry.outcome === 'load-failed' &&
-          entry.candidate.source === 'autolinked',
-      )
-      .map(entry => ({
-        spec: entry.candidate.spec ?? entry.label,
-        error: entry.error ?? 'its manifest could not be loaded',
-      }));
     try {
       docsCatalog = await project.docs();
       docsCatalogIssues = (await project.issues()).filter(
@@ -1309,7 +1229,6 @@ export async function runChecks(options = {}) {
     docsCatalogIssues,
     docsCatalogError,
     integrationIssues,
-    autolinkFailures,
     configError,
   };