@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/api/integration/validate-integration.test.mjs

@@ -80,6 +80,28 @@ describe('validate-integration API', () => {
     expect(errors).toBe(0);
   });
 
+  it('warns, with a fix and the file, on docs no reader can serve', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    writePackage(pkgDir, {
+      manifest: `export default { docs: './docs' };\n`,
+    });
+    fs.mkdirSync(path.join(pkgDir, 'docs'), {recursive: true});
+    fs.writeFileSync(
+      path.join(pkgDir, 'docs', 'ghost.doc.zh.mjs'),
+      "export default {title: 'ghost'};\n",
+    );
+
+    const result = await validateLocalIntegration(pkgDir);
+
+    expect(byCode(result.issues, 'orphan_doc_overlay')).toEqual([
+      expect.objectContaining({
+        severity: 'warning',
+        file: 'docs/ghost.doc.zh.mjs',
+        fix: expect.stringContaining('Delete docs/ghost.doc.zh.mjs'),
+      }),
+    ]);
+  });
+
   it('reports an unknown manifest key as a warning, and still loads the rest', async () => {
     // The manifest used to be parsed with a strict schema, so a single unknown
     // key failed the parse — and an integration whose manifest fails to parse
@@ -321,6 +343,36 @@ export default {type: 'theme', name: 'ocean', displayName: 'Ocean', description:
     );
   });
 
+  it('warns when a template source has no same-stem metadata, skipping test files', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    writePackage(pkgDir, {
+      manifest: `export default { templates: './templates' };\n`,
+    });
+    fs.mkdirSync(path.join(pkgDir, 'templates'));
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', 'stray.tsx'),
+      'export default function Stray() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', 'stray.test.tsx'),
+      "import {it} from 'vitest';\nit('renders', () => {});\n",
+    );
+
+    const result = await validateLocalIntegration(pkgDir);
+
+    const warnings = byCode(result.issues, 'source_without_template_doc');
+    expect(warnings).toEqual([
+      expect.objectContaining({
+        severity: 'warning',
+        message: expect.stringContaining('"stray.tsx"'),
+      }),
+    ]);
+    expect(warnings[0].message).not.toContain('stray.test.tsx');
+    expect(warnings[0].message).toContain(
+      "Fix: add stray.doc.mjs beside it with type: 'page' or 'block'",
+    );
+  });
+
   it('reports codemods outside semver folders and invalid folder names', async () => {
     const pkgDir = path.join(tmpDir, 'pkg');
     writePackage(pkgDir, {
@@ -593,7 +645,10 @@ describe('integration diagnostics are read-only', () => {
       'components/Orphan.doc.mjs',
       "export default {type: 'component', name: 'Orphan', props: []};\n",
     );
-    write('templates/dash.doc.mjs', "export default {type: 'page', name: 'Dash'};\n");
+    write(
+      'templates/dash.doc.mjs',
+      "export default {type: 'page', name: 'Dash'};\n",
+    );
     write(
       'docs/theme.doc.mjs',
       "export default {type: 'generic', name: 'theme', title: 'Theme', description: 'x', sections: [{title: 'A', content: [{type: 'prose', text: 'x'}]}]};\n",
@@ -614,7 +669,9 @@ describe('integration diagnostics are read-only', () => {
       path.join(consumer, 'package.json'),
       JSON.stringify({name: 'consumer'}),
     );
-    writeDiagnosedPackage(path.join(consumer, 'node_modules', '@acme', 'widgets'));
+    writeDiagnosedPackage(
+      path.join(consumer, 'node_modules', '@acme', 'widgets'),
+    );
     const before = {pkg: snapshot(pkgDir), consumer: snapshot(consumer)};
 
     const local = await validateIntegration(undefined, {cwd: pkgDir});
@@ -631,9 +688,13 @@ describe('integration diagnostics are read-only', () => {
     }
 
     expect(summarizeIssues(local.data.issues).errors).toBeGreaterThan(0);
-    expect(byCode(local.data.issues, 'unreachable_contribution')).toHaveLength(1);
+    expect(byCode(local.data.issues, 'unreachable_contribution')).toHaveLength(
+      1,
+    );
     expect(summarizeIssues(installed.data.issues).errors).toBeGreaterThan(0);
-    expect({pkg: snapshot(pkgDir), consumer: snapshot(consumer)}).toEqual(before);
+    expect({pkg: snapshot(pkgDir), consumer: snapshot(consumer)}).toEqual(
+      before,
+    );
   });
 });
 
@@ -655,7 +716,9 @@ describe('validated separates "checked and clean" from "never checked"', () => {
     expect(validate.data.issues).toEqual([]);
 
     const templates = await integrationTemplateConflicts(undefined, {cwd: dir});
-    const components = await integrationComponentConflicts(undefined, {cwd: dir});
+    const components = await integrationComponentConflicts(undefined, {
+      cwd: dir,
+    });
     const docs = await integrationDocConflicts(undefined, {cwd: dir});
     expect(templates.data.validated).toBe(false);
     expect(components.data.validated).toBe(false);
@@ -671,7 +734,9 @@ describe('validated separates "checked and clean" from "never checked"', () => {
     expect(validate.data.name).toBe('@acme/widgets');
 
     const templates = await integrationTemplateConflicts(undefined, {cwd: dir});
-    const components = await integrationComponentConflicts(undefined, {cwd: dir});
+    const components = await integrationComponentConflicts(undefined, {
+      cwd: dir,
+    });
     const docs = await integrationDocConflicts(undefined, {cwd: dir});
     expect(templates.data.validated).toBe(true);
     expect(components.data.validated).toBe(true);
@@ -743,8 +808,12 @@ describe('unreadable folders are reported, never fatal', () => {
       expect(
         byCode(result.issues, 'unreadable_root').map(issue => issue.message),
       ).toEqual([
-        expect.stringMatching(/^Declared codemods root cannot be read \(EACCES\)/),
-        expect.stringMatching(/^Declared themes root cannot be read \(EACCES\)/),
+        expect.stringMatching(
+          /^Declared codemods root cannot be read \(EACCES\)/,
+        ),
+        expect.stringMatching(
+          /^Declared themes root cannot be read \(EACCES\)/,
+        ),
       ]);
     },
   );

package/api/integration/validate-integration.type.d.mts

@@ -34,11 +34,19 @@ export type ValidateIntegrationOptions = {
  */
 export type ValidateIntegrationResponse = {
     type: "integration.validate";
+    /**
+     *   `notes`: information beside the issues that fails nothing, such as
+     *   `invalid_cli_command`, a `cliCommand` that was ignored as malformed
+     */
     data: {
         validated: boolean;
         name: string | null;
         version: string | null;
         issues: import("../../foundation/integrations/issue").AstryxIntegrationIssue[];
+        notes?: Array<{
+            code: string;
+            message: string;
+        }>;
         docTypes?: DocTypesReport;
     };
 };

package/api/integration/validate-integration.type.mjs

@@ -38,7 +38,9 @@
  * "healthy" — the two are otherwise byte-identical.
  * @typedef {object} ValidateIntegrationResponse
  * @property {'integration.validate'} type
- * @property {{validated: boolean, name: string | null, version: string | null, issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[], docTypes?: DocTypesReport}} data
+ * @property {{validated: boolean, name: string | null, version: string | null, issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[], notes?: Array<{code: string, message: string}>, docTypes?: DocTypesReport}} data
+ *   `notes`: information beside the issues that fails nothing, such as
+ *   `invalid_cli_command`, a `cliCommand` that was ignored as malformed
  */
 
 /**

package/api/integration/validate-unread-theme-folders.test.mjs

@@ -15,6 +15,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {validateLocalIntegration} from './validate-integration.mjs';
 import {integrationAddTheme} from './add-theme.mjs';
+import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
 
 let tmpDir;
 
@@ -76,8 +77,8 @@ describe('unread theme folders', () => {
     ]);
     expect(issues.map(issue => issue.message)).toEqual([
       'Folder "themes/Tide_Pool/" holds modules but no <name>Theme source or .doc.mjs descriptor, so Astryx does not read it as a theme. Fix: rename it to .Tide_Pool so Astryx skips it; a theme folder needs a lower-kebab name.',
-      'Folder "themes/reef/" holds modules but no <name>Theme source or .doc.mjs descriptor, so Astryx does not read it as a theme. Fix: if it is a theme, add reefTheme.ts and reefTheme.doc.mjs to it (`astryx integration add theme reef` writes both) and move its code into reefTheme.ts; if not, rename it to .reef so Astryx skips it.',
-      'Folder "themes/sand/" holds modules but no <name>Theme source or .doc.mjs descriptor, so Astryx does not read it as a theme. Fix: if it is a theme, add sandTheme.ts and sandTheme.doc.mjs to it (`astryx integration add theme sand` writes both) and move its code into sandTheme.ts; if not, rename it to .sand so Astryx skips it.',
+      `Folder "themes/reef/" holds modules but no <name>Theme source or .doc.mjs descriptor, so Astryx does not read it as a theme. Fix: if it is a theme, add reefTheme.ts and reefTheme.doc.mjs to it (\`${formatCliCommand('integration add theme reef', tmpDir)}\` writes both) and move its code into reefTheme.ts; if not, rename it to .reef so Astryx skips it.`,
+      `Folder "themes/sand/" holds modules but no <name>Theme source or .doc.mjs descriptor, so Astryx does not read it as a theme. Fix: if it is a theme, add sandTheme.ts and sandTheme.doc.mjs to it (\`${formatCliCommand('integration add theme sand', tmpDir)}\` writes both) and move its code into sandTheme.ts; if not, rename it to .sand so Astryx skips it.`,
     ]);
   });
 

package/api/integration/validateIntegration.doc.mjs

@@ -26,7 +26,9 @@ export const doc = {
     'can stay exit-0 in a non-integration directory. It also checks every doc the ' +
     'package ships under its roots (component, template, docs topic, theme, and translation, served or not) against ' +
     "the published authoring type for its kind, as `tsc` would, with the project's " +
-    'own `typescript`: an unknown field, a missing required field, or a value outside ' +
+    'own `typescript` (or, where `typescript` is missing or has no JavaScript compiler ' +
+    'API, as TypeScript 7 does, the `@typescript/typescript6` it installs): an unknown ' +
+    'field, a missing required field, or a value outside ' +
     "a field's type is a warning in `docTypes` naming the field and a fix. A test " +
     'fixture under `__tests__` in the components or docs root is counted, not checked. ' +
     'Without TypeScript, `docTypes` is `skipped` with a reason.',
@@ -60,7 +62,7 @@ export const doc = {
     {
       type: 'integration.validate',
       description:
-        'The result envelope: `data.validated`, false when nothing was validated — with no `package.json` at all, `data.issues` carries one `no_package` error-severity issue so the command exits 1; with a `package.json` but no integration manifest, `data.issues` is empty, which means "not looked at", not "healthy"; `data.name` and `data.version` of the validated package (both null when `data.validated` is false; `data.name` is `(local package)` when the local package.json has no readable name), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}. When the manifest loads, `data.docTypes` holds the doc type check: `status` (`checked` | `skipped`), `reason` when skipped, `typescript`, `docs` (doc values checked), `findings` ({doc, line, export, type, field, problem: `unknown_field` | `missing_field` | `wrong_type`, severity: `warning`, message, fix}), `unchecked` ({doc, reason}: a doc that could not be fully checked, or a root its reader cannot read), and `fixtures` when the components or docs root holds test fixture docs under `__tests__`: how many, none of them checked.',
+        'The result envelope: `data.validated`, false when nothing was validated — with no `package.json` at all, `data.issues` carries one `no_package` error-severity issue so the command exits 1; with a `package.json` but no integration manifest, `data.issues` is empty, which means "not looked at", not "healthy"; `data.name` and `data.version` of the validated package (both null when `data.validated` is false; `data.name` is `(local package)` when the local package.json has no readable name), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message, fix?, file?, line?}: `fix` is the change that resolves the issue, and `file` and `line` where it is, relative to the package, when the check knows them; and `data.notes` when there are any: {code, message} information that fails nothing, such as `invalid_cli_command` for a `cliCommand` that was ignored as malformed. When the manifest loads, `data.docTypes` holds the doc type check: `status` (`checked` | `skipped`), `reason` when skipped, `typescript`, `docs` (doc values checked), `findings` ({doc, line, export, type, field, problem: `unknown_field` | `missing_field` | `wrong_type`, severity: `warning`, message, fix}), `unchecked` ({doc, reason}: a doc that could not be fully checked, or a root its reader cannot read), and `fixtures` when the components or docs root holds test fixture docs under `__tests__`: how many, none of them checked.',
     },
   ],
   examples: [

package/api/search/_adapter.d.mts

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The Core a typed search reads: the project's, else the release's own,
+ * installed into the per-user cache first when needed. Throws as
+ * requireCoreDir does.
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function requireSearchCoreDir(cwd: string): string;

package/api/search/_adapter.mjs

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Environment adapter for search: locating the Core a search reads,
+ * including the network install and npm subprocess that fetch a release's
+ * own Core outside a project (spec AST-081 FR3; architecture:cli-surface
+ * INV21).
+ *
+ * @input  the folder a search runs in
+ * @output the Core folder a search reads
+ * @position packages/cli/api/search — imported by search.mjs only
+ */
+
+import {requireCoreDir} from '../../foundation/fs/paths.mjs';
+
+/**
+ * The Core a typed search reads: the project's, else the release's own,
+ * installed into the per-user cache first when needed. Throws as
+ * requireCoreDir does.
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function requireSearchCoreDir(cwd) {
+  return requireCoreDir(cwd);
+}

package/api/search/search.d.mts

@@ -16,6 +16,48 @@ export function stem(w: string): string;
  * @returns {boolean}
  */
 export function sameWord(a: string, b: string): boolean;
+/**
+ * A query with its camelCase and PascalCase identifiers spelled as words, so
+ * `SidebarToggle` reads "sidebar toggle" and `useTablePaginationState` "use
+ * table pagination state". Plain words, and identifiers joined with `_` or `-`, are
+ * unchanged: a joined token that matches nothing stays unmatched.
+ * @param {string} query - The query as typed, before lowercasing.
+ * @returns {string} Lowercased.
+ */
+export function spellIdentifiers(query: string): string;
+/**
+ * The strongest hit a run of two or more adjacent query words has when it is
+ * read as one joined word, and the query words it covers. Readers type a
+ * compound name as separate words (`table header cell` is TableHeaderCell,
+ * `number field` the keyword `numberfield`), and no single word of the run
+ * matches on its own.
+ *
+ * - 100: the run joins to a component, hook, or template name, or its plural
+ *   (`table header cells` is TableHeaderCell), or a hook name without its
+ *   `use` prefix (`table sticky columns` is useTableStickyColumns).
+ * - 90: the run joins to a one-word keyword (`number field` is
+ *   `numberfield`).
+ * - 95: the run joins to most of a name, cut short (`dropdown menu radio` is
+ *   DropdownMenuRadioItem); 92: it is a name's leading words, covering at least half
+ *   of it (`top nav mega` is TopNavMegaMenu); 70: it is two or more adjacent
+ *   words of a name that cover at least half of it (`header cell` in
+ *   TableHeaderCell), the same coverage a word prefix needs. These three
+ *   are for components and hooks only.
+ *
+ * A doc's name is a route or key, so docs are left out.
+ * @param {string[]} words - The query's words, stopwords included.
+ * @param {Candidate} candidate
+ * @returns {{score: number, reason: string, covered: Set<string>, alias?: 'partial' | 'keyword', aliasWords?: number} | null}
+ *   `covered` holds the run's words and every stretch of them joined. `alias`
+ *   marks a hit on part of a name or on a keyword, not on the whole name.
+ */
+export function compoundHit(words: string[], candidate: Candidate): {
+    score: number;
+    reason: string;
+    covered: Set<string>;
+    alias?: "partial" | "keyword";
+    aliasWords?: number;
+} | null;
 /**
  * Split a query into meaningful content tokens (lowercased, stopwords + very
  * short words removed). Empty for single-word queries (callers fall back to
@@ -40,19 +82,20 @@ export function tokenizeQuery(term: string): string[];
  *   typography/font-setup, `side panel` is "Side panels");
  * - 1: a word of the query is the topic's name (`illustration` in a longer
  *   question is the illustrations guide);
+ * - 1: a query of two or more words is one of the topic's own declared
+ *   keywords, whatever the plural (`code review` on a guide that declares it);
  * - 1: the query holds one of the doc's titles whole (`resizable side panels`
  *   names "Side panels"; `light dark mode button` names "Light/Dark Mode");
  * - 1: the doc matches every word of the query and one of them is a word of
  *   its title (`switch to a dark theme` and "Use a theme").
  * A section answers to its topic's name.
  *
- * A doc that matched only by keyword, by a heading holding the query, or by
+ * A doc that matched only by a heading holding the query, by one word, or by
  * words spread through its text has no priority. Docs are split into many
- * small topics, and each declares its own keywords and headings, so a common
- * phrase such as `font size` hits a guide's keyword or heading exactly
- * (170-190) while the component the reader is after matches one word by
- * keyword (`Text`, 98). Ranked on text alone, every split adds another doc
- * above the component. Broad reference pages match every word of many queries
+ * small topics, each with its own headings, so a common phrase such as
+ * `font size` hits a heading exactly (170) while the component the reader is
+ * after matches one word by keyword (`Text`, 98). Ranked on text alone, every
+ * split adds another doc above the component. Broad reference pages match every word of many queries
  * in their text the same way. The score stays the text-match strength the
  * result reports, so callers that gate on it (`build`) see the same numbers.
  *
@@ -67,7 +110,7 @@ export function domainPriority(term: string, tokens: string[], candidate: Candid
     score: number;
     matched: number;
     total: number;
-}): 0 | 1 | 2;
+}, queryWords?: string[]): 0 | 1 | 2;
 /**
  * The first title or heading that holds every word of the query, in order and
  * side by side, or null.
@@ -89,18 +132,26 @@ export function titleInQuery(term: string, titles: string[] | undefined): string
  * @param {string} term - Lowercased full query.
  * @param {string[]} tokens - Content tokens from tokenizeQuery(term).
  * @param {Candidate} candidate
- * @returns {{score: number, reason: string, matched: number, total: number} | null}
+ * @param {string[]} [words] - The query's words for compound names (see
+ *   compoundHit); empty when the query names an entry outright.
+ * @param {{plain?: boolean}} [opts] - `plain`: score without matches on part
+ *   of a name or a joined keyword.
+ * @returns {{score: number, reason: string, matched: number, total: number, alias?: 'partial' | 'keyword', aliasWords?: number} | null}
  *   `matched`/`total` are the query concepts this candidate answered, out of
  *   the concepts the query had. Callers that must distinguish "matched one word
  *   of three" from "matched all three" — `build`, which gates its pages group
  *   on coverage — cannot recover that from the score, because a single strong
  *   hit and a broad weak one land on the same number.
  */
-export function scoreQuery(term: string, tokens: string[], candidate: Candidate): {
+export function scoreQuery(term: string, tokens: string[], candidate: Candidate, words?: string[], { plain }?: {
+    plain?: boolean;
+}): {
     score: number;
     reason: string;
     matched: number;
     total: number;
+    alias?: "partial" | "keyword";
+    aliasWords?: number;
 } | null;
 /**
  * Score a single candidate against the search term across name, keywords,
@@ -118,8 +169,9 @@ export function scoreQuery(term: string, tokens: string[], candidate: Candidate)
  * @param {string} [candidate.description]
  * @param {string[]} [candidate.prose] - Extra free-text blobs (doc section text, best practices).
  * @param {string[]} [candidate.guidance] - Usage guidance (features, best practices) — scored a tier below description.
- * @param {{fuzzy?: boolean}} [opts] - `fuzzy`: allow edit-distance (typo) matches. Default true; multi-word queries pass false.
- * @returns {{score: number, reason: string} | null}
+ * @param {{fuzzy?: boolean, joins?: boolean}} [opts] - `fuzzy`: allow edit-distance (typo) matches. Default true; multi-word queries pass false. `joins`: read a spaced query joined into a name or keyword (default true); off when the query names an entry outright.
+ * @returns {{score: number, reason: string, alias?: 'partial' | 'keyword'} | null}
+ *   `alias` marks a hit that read the query's words joined.
  */
 export function scoreCandidate(term: string, { name, aliases, domain, keywords, weakKeywords, description, prose, guidance, }: {
     name: string;
@@ -130,11 +182,13 @@ export function scoreCandidate(term: string, { name, aliases, domain, keywords,
     description?: string | undefined;
     prose?: string[] | undefined;
     guidance?: string[] | undefined;
-}, { fuzzy }?: {
+}, { fuzzy, joins }?: {
     fuzzy?: boolean;
+    joins?: boolean;
 }): {
     score: number;
     reason: string;
+    alias?: "partial" | "keyword";
 } | null;
 /**
  * The components (name and keywords) a search response was scored against, or
@@ -172,7 +226,7 @@ export function componentKeywords(coreDir: string, cwd: string): Promise<{
  */
 export function search(query: string, options?: {
     cwd?: string | undefined;
-    type?: "theme" | "component" | "hook" | "template" | "doc" | undefined;
+    type?: "component" | "hook" | "doc" | "template" | "theme" | undefined;
     limit?: number | undefined;
 }): Promise<import("./search.type.mjs").SearchResponse>;
 export namespace SYNONYMS {
@@ -213,6 +267,12 @@ export type Candidate = {
      */
     aliases?: string[] | undefined;
     keywords?: string[] | undefined;
+    /**
+     * - A doc's own declared keywords: what its
+     * author lists in `keywords`, without the code terms and table cells its
+     * other keywords add.
+     */
+    _declared?: string[] | undefined;
     weakKeywords?: string[] | undefined;
     description?: string | undefined;
     prose?: string[] | undefined;

package/api/search/search.doc.mjs

@@ -21,7 +21,8 @@ export const doc = {
     'incidental prose mentions, so an exact match always sorts first. A component\'s ' +
     'usage guidance (its best practices) is indexed one tier below its description, ' +
     'so the words a reader types still find it — but a component that IS the answer ' +
-    'always outranks one whose advice merely mentions the term.',
+    'always outranks one whose advice merely mentions the term.' +
+    " In global mode: with `cwd` outside a project, items from integrations installed next to this CLI package globally are searched too, and theme results name no step that adds a theme to an app; inside a project, only the project's own integrations count. See {@link namespace:global} and {@link generic:computer-integrations}.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'search(query: string, options?: SearchOptions): Promise<SearchResponse>',
@@ -48,14 +49,14 @@ export const doc = {
       name: 'options.cwd',
       type: 'string',
       description:
-        "Directory to resolve @astryxdesign/core from. A docs-only or themes-only search (`type: 'doc'` or `type: 'theme'`) does not need it, and a search with no `type` covers the docs and themes alone when core is missing.",
+        "Directory to resolve @astryxdesign/core from: the project's installed Core, else, outside a project or in a project with nothing installed, the Core of the release that answers, installed into the per-user cache first when needed. A docs-only or themes-only search (`type: 'doc'` or `type: 'theme'`) does not need it. A search with no `type` covers the docs and themes alone only when that Core cannot be obtained, and then says so in `meta.partial`.",
     },
   ],
   returns: [
     {
       type: 'search',
       description:
-        'The query echoed back, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit`: each has domain, name, score, reason, description, and follow-up command, plus `import` for components and hooks, `title` for docs, `displayName` and `kind` for templates, and `displayName` for themes. A doc result is the smallest part that answers: one section (with `section`, and a command that reads only it), one docs-tree route, or a topic, whose command lists its sections. `parent` is the command that opens the level above it: the section list of its topic, the namespace a tree node sits in, the Unorganized level for a flat topic, or the topic list for a top-level namespace. Every doc result also carries `package`, the npm package that authored it (for a section, the package its file came from). A theme result is one theme you can import: `name` is its slug, its command is `astryx theme add <slug>`, and `package` is the npm package that ships it (`@astryxdesign/cli` for the CLI\'s own themes).',
+        'The query echoed back, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit`: each has domain, name, score, reason, description, and follow-up command, plus `import` for components and hooks, `title` for docs, `displayName` and `kind` for templates, and `displayName` for themes. A doc result is the smallest part that answers: one section (with `section`, and a command that reads only it), one docs-tree route, or a topic, whose command lists its sections. `parent` is the command that opens the level above it: the section list of its topic, the namespace a tree node sits in, the Unorganized level for a flat topic, or the topic list for a top-level namespace. Every doc result also carries `package`, the npm package that authored it (for a section, the package its file came from). A theme result is one theme you can import: `name` is its slug, its command is `astryx theme add <slug>` (outside a project, where there is no app to add it to, `astryx theme eject <slug>`), and `package` is the npm package that ships it (`@astryxdesign/cli` for the CLI\'s own themes). When a search with no `type` could not obtain @astryxdesign/core, `meta.partial` is `{skipped, reason}`: the domains it skipped (`component`, `hook`, `template`) and why; the results are the docs and themes, and text mode prints one line on standard error.',
     },
   ],
   throws: [
@@ -67,6 +68,10 @@ export const doc = {
       code: 'ERR_CORE_NOT_FOUND',
       when: '@astryxdesign/core cannot be found from the cwd, and `type` names a domain that reads it: `component`, `hook`, or `template`',
     },
+    {
+      code: 'ERR_VERSIONS_UNAVAILABLE',
+      when: "`type` names a domain that reads @astryxdesign/core, and outside a project, or in a project with nothing installed, the Core of the release that answers cannot be installed into the per-user cache; a search with no `type` answers with `meta.partial` instead",
+    },
   ],
   examples: [
     {label: 'Find a component', code: "const r = await search('button');"},

package/api/search/search.domain-priority.test.mjs

@@ -75,14 +75,75 @@ async function placedGuides(route, seen = new Set()) {
 }
 
 describe('search domain priority — the rule', () => {
-  it('gives a doc no priority for a keyword or heading match', () => {
+  it('gives a doc no priority for a heading match or a one-word keyword', () => {
     const topic = {
       domain: 'doc',
       name: 'typography/font-setup',
-      keywords: ['font size'],
+      keywords: ['size'],
       titles: ['Font Setup', 'Font Sizes'],
     };
     expect(priority('font size', topic)).toBe(0);
+    expect(priority('size', topic)).toBe(0);
+  });
+
+  it('gives a doc priority when the query is one of its declared keywords', () => {
+    const guide = {
+      domain: 'doc',
+      name: 'guides/quality',
+      titles: ['Is my code good?'],
+      keywords: ['code review', 'review my code'],
+      _declared: ['code review', 'review my code'],
+    };
+    expect(priority('code review', guide)).toBe(1);
+    expect(priority('Code Reviews', guide)).toBe(1);
+    expect(priority('review my code', guide)).toBe(1);
+    // A section's keywords are its headings and code terms.
+    const section = {
+      ...guide,
+      name: 'before-you-ship',
+      _topic: 'guides/quality',
+      _section: 'before-you-ship',
+    };
+    expect(priority('code review', section)).toBe(0);
+  });
+
+  it("gives a doc no priority for a code term or table cell it didn't declare", () => {
+    // A typed doc's keywords hold the first column of its tables and the code
+    // terms its text mentions; `missing_field` reads as two words.
+    const reference = {
+      domain: 'doc',
+      name: 'cli/api/functions/validate-integration',
+      titles: ['validateIntegration'],
+      keywords: ['validate-integration', 'missing_field', 'file required'],
+      _declared: [],
+      _topic: 'cli/api/functions/validate-integration',
+    };
+    expect(priority('missing field', reference)).toBe(0);
+    expect(priority('file required', reference)).toBe(0);
+    expect(
+      priority('missing field', {...reference, _declared: ['missing field']}),
+    ).toBe(1);
+  });
+
+  it('keeps a component the query names exactly above a doc that declares it', async () => {
+    const tokens = tokenizeQuery('empty state');
+    const component = {domain: 'component', name: 'EmptyState'};
+    const doc = {
+      domain: 'doc',
+      name: 'illustrations',
+      keywords: ['empty state'],
+      _declared: ['empty state'],
+    };
+    const c = scoreQuery('empty state', tokens, component);
+    const d = scoreQuery('empty state', tokens, doc);
+    expect(
+      domainPriority('empty state', tokens, /** @type {any} */ (component), c),
+    ).toBe(1);
+    expect(
+      domainPriority('empty state', tokens, /** @type {any} */ (doc), d),
+    ).toBe(1);
+    // Both have priority, so the stronger match wins: the exact name.
+    expect(c?.score).toBeGreaterThan(d?.score ?? 0);
   });
 
   it('gives a doc priority when the query names it', () => {
@@ -190,32 +251,61 @@ describe('search domain priority — the rule', () => {
 
 describe('search domain priority — real docs and components', () => {
   it(
-    'finds the Text component before the typography guides for `font size`',
+    'finds a guide that declares the whole phrase above a component that matches one word',
     async () => {
-      for (const q of ['font size', 'font weight']) {
-        const results = (await search(q, {cwd})).data.results;
-        expect(results[0], q).toMatchObject({
-          domain: 'component',
-          name: 'Text',
-        });
-        const guide = results.findIndex(
-          r => r.domain === 'doc' && /^typography(?:\/|$)/.test(r.name),
-        );
-        // The guide still matches, below the component.
-        expect(guide, q).toBeGreaterThan(0);
+      const results = (await search('font size', {cwd})).data.results;
+      expect(results[0]).toMatchObject({domain: 'doc'});
+      expect(results[0].name).toMatch(/^typography(?:\/|$)/);
+      // The component the phrase points to stays near the top.
+      expect(
+        results
+          .slice(0, 3)
+          .some(r => r.domain === 'component' && r.name === 'Text'),
+      ).toBe(true);
+    },
+    SLOW,
+  );
+
+  it(
+    'keeps a component above a reference doc whose table or code terms hold the phrase',
+    async () => {
+      for (const q of ['missing field', 'file required']) {
+        const [top] = (await search(q, {cwd})).data.results;
+        expect(top, q).toMatchObject({domain: 'component', name: 'Field'});
       }
     },
     SLOW,
   );
 
   it(
-    'reports the text-match score unchanged',
+    'opens the guide that answers a declared phrase, not one that only mentions it',
+    async () => {
+      const [layers] = (await search('cascade layers', {cwd})).data.results;
+      expect(layers).toMatchObject({
+        domain: 'doc',
+        name: 'migration/migration-setup',
+      });
+      const [keyboard] = (await search('keyboard navigation', {cwd})).data
+        .results;
+      expect(keyboard?.name).not.toBe('migration/migration-verification');
+    },
+    SLOW,
+  );
+
+  it(
+    'keeps a component above docs that match only by a heading, with scores unchanged',
     async () => {
       const results = (await search('font size', {cwd})).data.results;
-      const guide = results.find(
-        r => r.domain === 'doc' && /^typography(?:\/|$)/.test(r.name),
+      const text = results.findIndex(
+        r => r.domain === 'component' && r.name === 'Text',
       );
-      expect(guide?.score).toBeGreaterThan(results[0].score);
+      expect(text).toBeGreaterThanOrEqual(0);
+      // A doc below Text outscores it on text alone: priority moved it, not the score.
+      expect(
+        results
+          .slice(text + 1)
+          .some(r => r.domain === 'doc' && r.score > results[text].score),
+      ).toBe(true);
     },
     SLOW,
   );