@astryxdesign/cli 0.7.2-canary.caec7ca → 0.7.2-canary.caf5673

package/api/integration/pack-check.test.mjs

@@ -754,6 +754,285 @@ describe('integrationPackCheck', () => {
     );
   });
 
+  it('checks the export a component doc names when its file is named otherwise', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'components'],
+        exports: {'./components/Slides': './components/Slides.tsx'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './components'};\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, 'components'));
+    // Slides.tsx exports AcmeCarousel and nothing named Slides.
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'Slides.tsx'),
+      'export function AcmeCarousel() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'Slides.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeCarousel', import: '@acme/widgets/components/Slides', description: 'x', props: []};\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+    expect(result.data.packable).toBe(true);
+    expect(result.data.contributions.packed.components).toEqual([
+      'AcmeCarousel',
+    ]);
+  });
+
+  it('checks each family member against the module its family doc imports', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'components'],
+        exports: {'./tabs': './components/tabs/index.ts'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './components'};\n",
+    );
+    const dir = path.join(tmpDir, 'components', 'tabs');
+    fs.mkdirSync(dir, {recursive: true});
+    fs.writeFileSync(
+      path.join(dir, 'AcmeTabs.tsx'),
+      'export function AcmeTabs() { return null; }\nexport function AcmeTabsLegacy() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(dir, 'tab.tsx'),
+      'export function AcmeTab() { return null; }\n',
+    );
+    // The module apps import exports AcmeTabs and AcmeTab, not AcmeTabsLegacy.
+    fs.writeFileSync(
+      path.join(dir, 'index.ts'),
+      "export {AcmeTabs} from './AcmeTabs';\nexport {AcmeTab} from './tab';\n",
+    );
+    fs.writeFileSync(
+      path.join(dir, 'AcmeTabs.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeTabs', import: '@acme/widgets/tabs', description: 'x', components: [{name: 'AcmeTabs', description: 'x', props: []}, {name: 'AcmeTab', description: 'x', props: []}, {name: 'AcmeTabsLegacy', description: 'x', props: []}]};\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues).toEqual([]);
+    expect(result.data.packable).toBe(true);
+    expect(result.data.contributions.packed.components).toEqual([
+      'AcmeTab',
+      'AcmeTabs',
+    ]);
+  });
+
+  it.each([
+    'a clean checkout',
+    'a stale build',
+    'a stale build that exports more',
+  ])(
+    'reads members a family imports from output its pack lifecycle builds, from %s',
+    async start => {
+      fs.writeFileSync(
+        path.join(tmpDir, 'package.json'),
+        `${JSON.stringify({
+          name: '@acme/widgets',
+          version: '1.0.0',
+          files: ['astryx.integration.mjs', 'components', 'dist'],
+          exports: {'./tabs': './dist/tabs/index.mjs'},
+          scripts: {prepack: 'node build.mjs'},
+        })}\n`,
+      );
+      fs.writeFileSync(
+        path.join(tmpDir, 'astryx.integration.mjs'),
+        "export default {components: './components'};\n",
+      );
+      // The build writes the module the family imports; a clean checkout has none.
+      fs.writeFileSync(
+        path.join(tmpDir, 'build.mjs'),
+        "import fs from 'node:fs';\nfs.mkdirSync('dist/tabs', {recursive: true});\nfs.writeFileSync('dist/tabs/index.mjs', \"export {AcmeTabs, AcmeTab} from '../../components/tabs/AcmeTabs.tsx';\\n\");\n",
+      );
+      const dir = path.join(tmpDir, 'components', 'tabs');
+      fs.mkdirSync(dir, {recursive: true});
+      fs.writeFileSync(
+        path.join(dir, 'AcmeTabs.tsx'),
+        'export function AcmeTabs() { return null; }\nexport function AcmeTab() { return null; }\nexport function AcmeTabLegacy() { return null; }\n',
+      );
+      fs.writeFileSync(
+        path.join(dir, 'AcmeTabs.doc.mjs'),
+        "export default {type: 'component', name: 'AcmeTabs', import: '@acme/widgets/tabs', description: 'x', components: [{name: 'AcmeTabs', description: 'x', props: []}, {name: 'AcmeTab', description: 'x', props: []}, {name: 'AcmeTabLegacy', description: 'x', props: []}]};\n",
+      );
+
+      if (start !== 'a clean checkout') {
+        // An earlier build: before AcmeTab was exported, or while AcmeTabLegacy
+        // still was.
+        const names =
+          start === 'a stale build'
+            ? 'AcmeTabs'
+            : 'AcmeTabs, AcmeTab, AcmeTabLegacy';
+        fs.mkdirSync(path.join(tmpDir, 'dist', 'tabs'), {recursive: true});
+        fs.writeFileSync(
+          path.join(tmpDir, 'dist', 'tabs', 'index.mjs'),
+          `export {${names}} from '../../components/tabs/AcmeTabs.tsx';\n`,
+        );
+      }
+
+      const result = await integrationPackCheck({cwd: tmpDir});
+
+      expect(result.data.issues).toEqual([]);
+      expect(result.data.packable).toBe(true);
+      expect(result.data.contributions.local.components).toEqual(
+        result.data.contributions.packed.components,
+      );
+    },
+  );
+
+  it.each(['a clean checkout', 'an incremental build'])(
+    'reads members built output re-exports from compiled files, from %s',
+    async start => {
+      fs.writeFileSync(
+        path.join(tmpDir, 'package.json'),
+        `${JSON.stringify({
+          name: '@acme/widgets',
+          version: '1.0.0',
+          files: ['astryx.integration.mjs', 'components', 'dist'],
+          exports: {'./tabs': './dist/tabs/index.mjs'},
+          scripts: {prepack: 'node build.mjs'},
+        })}\n`,
+      );
+      fs.writeFileSync(
+        path.join(tmpDir, 'astryx.integration.mjs'),
+        "export default {components: './components'};\n",
+      );
+      // The build compiles each source to its own file and, like an
+      // incremental build, rewrites only the files whose output changed.
+      const output = {
+        'index.mjs':
+          "export {AcmeTabs} from './tabs.mjs';\nexport * from './tab.mjs';\n",
+        'tabs.mjs': 'export function AcmeTabs() { return null; }\n',
+        'tab.mjs': 'export function AcmeTab() { return null; }\n',
+      };
+      fs.writeFileSync(
+        path.join(tmpDir, 'build.mjs'),
+        `import fs from 'node:fs';\nconst output = ${JSON.stringify(output)};\nfs.mkdirSync('dist/tabs', {recursive: true});\nfor (const [file, text] of Object.entries(output)) {\n  const target = 'dist/tabs/' + file;\n  if (!fs.existsSync(target) || fs.readFileSync(target, 'utf-8') !== text) fs.writeFileSync(target, text);\n}\n`,
+      );
+      const dir = path.join(tmpDir, 'components', 'tabs');
+      fs.mkdirSync(dir, {recursive: true});
+      fs.writeFileSync(
+        path.join(dir, 'AcmeTabs.tsx'),
+        'export function AcmeTabs() { return null; }\n',
+      );
+      fs.writeFileSync(
+        path.join(dir, 'AcmeTab.tsx'),
+        'export function AcmeTab() { return null; }\n',
+      );
+      fs.writeFileSync(
+        path.join(dir, 'AcmeTabs.doc.mjs'),
+        "export default {type: 'component', name: 'AcmeTabs', import: '@acme/widgets/tabs', description: 'x', components: [{name: 'AcmeTabs', description: 'x', props: []}, {name: 'AcmeTab', description: 'x', props: []}]};\n",
+      );
+      if (start === 'an incremental build') {
+        // An earlier build from before AcmeTab existed: the file the import
+        // names is already current, so the build leaves it untouched.
+        fs.mkdirSync(path.join(tmpDir, 'dist', 'tabs'), {recursive: true});
+        for (const [file, text] of Object.entries({...output, 'tab.mjs': ''})) {
+          fs.writeFileSync(path.join(tmpDir, 'dist', 'tabs', file), text);
+        }
+      }
+
+      const result = await integrationPackCheck({cwd: tmpDir});
+
+      expect(result.data.issues).toEqual([]);
+      expect(result.data.packable).toBe(true);
+      expect(result.data.contributions.packed.components).toEqual([
+        'AcmeTab',
+        'AcmeTabs',
+      ]);
+      expect(result.data.contributions.local.components).toEqual(
+        result.data.contributions.packed.components,
+      );
+    },
+  );
+
+  it('passes a member another folder declares, which has no source', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'components'],
+        exports: {'./menu': './components/menu/index.ts'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './components'};\n",
+    );
+    const menu = path.join(tmpDir, 'components', 'menu');
+    const shared = path.join(tmpDir, 'components', 'shared');
+    fs.mkdirSync(menu, {recursive: true});
+    fs.mkdirSync(shared, {recursive: true});
+    fs.writeFileSync(
+      path.join(menu, 'AcmeMenu.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeMenu', import: '@acme/widgets/menu', description: 'x', components: [{name: 'AcmeMenuItem', description: 'x', props: []}]};\n",
+    );
+    fs.writeFileSync(
+      path.join(menu, 'AcmeMenu.tsx'),
+      'export function AcmeMenu() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(menu, 'index.ts'),
+      "export {AcmeMenu} from './AcmeMenu';\nexport {AcmeMenuItem} from '../shared/AcmeMenuItem';\n",
+    );
+    fs.writeFileSync(
+      path.join(shared, 'AcmeMenuItem.tsx'),
+      'export function AcmeMenuItem() { return null; }\n',
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues).toEqual([]);
+    expect(result.data.packable).toBe(true);
+    expect(result.data.contributions.packed.components).toEqual([
+      'AcmeMenu',
+      'AcmeMenuItem',
+    ]);
+  });
+
+  it('reports a family doc the loader rejects once, not once per member', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'components'],
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './components'};\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, 'components'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeTabs.tsx'),
+      'export function AcmeTabs() { return null; }\nexport function AcmeTab() { return null; }\nexport function AcmeTabPanel() { return null; }\n',
+    );
+    // A displayName that is not a string makes the loader reject the doc.
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeTabs.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeTabs', displayName: 1, description: 'x', components: [{name: 'AcmeTab', description: 'x', props: []}, {name: 'AcmeTabPanel', description: 'x', props: []}]};\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+    const codes = result.data.issues.map(issue => issue.code);
+
+    expect(codes).toContain('component_doc_unloadable');
+    expect(codes.length).toBe(new Set(codes).size);
+  });
+
   it('passes a generated component through its exact packed export', async () => {
     fs.writeFileSync(
       path.join(tmpDir, 'package.json'),
@@ -811,6 +1090,86 @@ describe('integrationPackCheck', () => {
     );
   });
 
+  it('does not count a type-only re-export as the component', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'src'],
+        exports: {'.': './src/index.ts'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './src'};\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, 'src'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'src', 'index.ts'),
+      "export type {AcmeWidget} from './AcmeWidget';\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'src', 'AcmeWidget.tsx'),
+      'export function AcmeWidget() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'src', 'AcmeWidget.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeWidget', import: '@acme/widgets', description: 'Widget.', props: []};\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues).toContainEqual(
+      expect.objectContaining({code: 'component_export_missing'}),
+    );
+  });
+
+  it('follows a re-export of a folder to its index file', async () => {
+    // `./primitives` names a folder: TypeScript and bundlers load its index file.
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'src'],
+        exports: {'.': './src/index.ts'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './src'};\n",
+    );
+    const primitives = path.join(tmpDir, 'src', 'primitives');
+    fs.mkdirSync(primitives, {recursive: true});
+    fs.writeFileSync(
+      path.join(tmpDir, 'src', 'index.ts'),
+      "export * from './primitives';\n",
+    );
+    fs.writeFileSync(
+      path.join(primitives, 'index.ts'),
+      "export * from './AcmeWidget';\n",
+    );
+    fs.writeFileSync(
+      path.join(primitives, 'AcmeWidget.tsx'),
+      'export function AcmeWidget() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(primitives, 'AcmeWidget.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeWidget', import: '@acme/widgets', description: 'Widget.', props: []};\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues).not.toContainEqual(
+      expect.objectContaining({code: 'component_export_missing'}),
+    );
+    expect(
+      result.data.packable,
+      JSON.stringify(result.data.issues, null, 2),
+    ).toBe(true);
+  });
+
   it('fails when packed template source is hidden by package exports', async () => {
     writePackage({
       manifest: "export default {templates: './templates'};\n",

package/api/integration/validate-integration.mjs

@@ -34,6 +34,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {assertWithin} from '../../foundation/fs/path-safety.mjs';
+import {integrationDocTypes} from '../docs/_adapter.mjs';
 import {
   THEME_SLUG_RE,
   unreadThemeFolders,
@@ -461,6 +462,12 @@ export async function validateIntegration(pkg, options = {}) {
   const result = pkg
     ? await validateInstalledIntegration(pkg, cwd)
     : await validateLocalIntegration(cwd);
+  // Each doc the package ships, against the published authoring type for its
+  // kind, read with the project's own compiler. Findings are warnings only.
+  const integration = result.found ? result.integration : undefined;
+  const docTypes = integration
+    ? await integrationDocTypes(integration, cwd)
+    : undefined;
   return {
     type: 'integration.validate',
     data: {
@@ -472,6 +479,7 @@ export async function validateIntegration(pkg, options = {}) {
       issues: result.reason === 'no_package_json'
         ? [{code: 'no_package', severity: 'error', message: 'No package.json found. Run this command inside a package directory.'}]
         : result.issues,
+      ...(docTypes ? {docTypes} : {}),
     },
   };
 }

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

@@ -176,6 +176,17 @@ describe('validate-integration API', () => {
     expect(agentDocsIssues[0].severity).toBe('error');
   });
 
+  it('reports nothing for a docsiteUrl', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    writePackage(pkgDir, {
+      manifest: `export default {docsiteUrl: 'https://widgets.example.com'};\n`,
+    });
+
+    const result = await validateLocalIntegration(pkgDir);
+
+    expect(result.issues).toEqual([]);
+  });
+
   it('flags a broken codemod as invalid_codemod error', async () => {
     const pkgDir = path.join(tmpDir, 'pkg');
     writePackage(pkgDir, {

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

@@ -39,5 +39,13 @@ export type ValidateIntegrationResponse = {
         name: string | null;
         version: string | null;
         issues: import("../../foundation/integrations/issue").AstryxIntegrationIssue[];
+        docTypes?: DocTypesReport;
     };
 };
+/**
+ * `fixtures`: how many test fixture docs (under `__tests__` in the
+ * components or docs root, which those readers skip) were not checked
+ */
+export type DocTypesReport = import("../../foundation/discovery/doc-types.mjs").DocTypesReport & {
+    fixtures?: number;
+};

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

@@ -38,7 +38,18 @@
  * "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[]}} data
+ * @property {{validated: boolean, name: string | null, version: string | null, issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[], docTypes?: DocTypesReport}} data
+ */
+
+/**
+ * Each doc the package ships, checked against the published authoring type
+ * for its kind. Present when the manifest loads. `status: 'skipped'`
+ * means nothing was checked (no TypeScript in the project) and `reason` says
+ * why. Every finding is a warning.
+ *
+ * @typedef {import('../../foundation/discovery/doc-types.mjs').DocTypesReport & {fixtures?: number}} DocTypesReport
+ *   `fixtures`: how many test fixture docs (under `__tests__` in the
+ *   components or docs root, which those readers skip) were not checked
  */
 
 export {};

package/api/integration/validateIntegration.doc.mjs

@@ -23,11 +23,27 @@ export const doc = {
     'declared contribution root exists, and runs the codemod/template/component/' +
     'docs/theme validators, returning every finding as an AstryxIntegrationIssue. A missing ' +
     'local manifest is guidance (name null, no issues), not an error, so callers ' +
-    'can stay exit-0 in a non-integration directory.',
+    '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` (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.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'validateIntegration(pkg?: string, options?: ValidateIntegrationOptions): Promise<ValidateIntegrationResponse>',
-  keywords: ['integration', 'validate', 'manifest', 'lint', 'check'],
+  keywords: [
+    'integration',
+    'validate',
+    'manifest',
+    'lint',
+    'check',
+    'types',
+    'typecheck',
+  ],
   params: [
     {
       name: 'pkg',
@@ -46,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}.',
+        '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.',
     },
   ],
   examples: [

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
@@ -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;
@@ -252,4 +312,13 @@ export type Candidate = {
     _kind?: "page" | "block" | undefined;
     _resultName?: string | undefined;
     _commandName?: string | undefined;
+    /**
+     * - How an integration component holds its
+     * name, for the owner rule.
+     */
+    _hold?: "file" | "doc" | undefined;
+    /**
+     * - An integration component's doc.
+     */
+    _docPath?: string | undefined;
 };