@astryxdesign/cli 0.7.2-canary.e26723d → 0.7.2-canary.e4bdd70

package/api/integration/integrationCheck.doc.mjs

@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FunctionDoc for `integrationCheck()` / `astryx integration check`.
+ * Colocated with the API function it documents; the shape source of truth stays
+ * in `integration-check.type.mjs`.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc = {
+  type: 'function',
+  kind: 'api',
+  name: 'integrationCheck',
+  namespace: 'cli/api',
+  displayName: 'integrationCheck()',
+  summary:
+    'Run every source check against the integration package in the current folder, as its build does: validate, components, templates, and docs.',
+  description:
+    'Runs `validateIntegration`, `integrationComponentConflicts`, ' +
+    '`integrationTemplateConflicts`, and `integrationDocConflicts` against the ' +
+    'integration package in `options.cwd`, and counts each result the way that ' +
+    "check's own subcommand exits. The run fails when any of the four would fail on " +
+    'its own. With `strict` it also fails on any warning and on any check that did ' +
+    'not run: a package with no integration manifest, or a comparison a check ' +
+    "carries that was skipped, such as one that needs the project's TypeScript. " +
+    '`strict` adds no check: it reports those warnings and skipped work again, as ' +
+    "errors in the checks' own issue format. " +
+    'A new check, or a new failure code, joins only in a minor release, named in the release notes.',
+  importPath: '@astryxdesign/cli/api',
+  signature:
+    'integrationCheck(options?: IntegrationCheckOptions): Promise<IntegrationCheckCommandResponse>',
+  keywords: ['integration', 'check', 'build', 'strict', 'validate', 'doctor'],
+  params: [
+    {
+      name: 'options.cwd',
+      type: 'string',
+      default: 'process.cwd()',
+      description: 'The integration package folder to check.',
+    },
+    {
+      name: 'options.strict',
+      type: 'boolean',
+      default: 'false',
+      description:
+        'Also fail on any warning and on any check that did not run, not only on errors.',
+    },
+  ],
+  returns: [
+    {
+      type: 'integration.check',
+      description:
+        "`data.validated` (false when no integration manifest was found, so nothing was checked), `data.name` and `data.version` of the package, `data.strict`, and `data.checks`, one entry per check in the order they run (`validate`, `components`, `templates`, `docs`), each with `check`, `errors` (what makes that check's own subcommand exit 1), `warnings`, `skipped` (why work did not run), `failed` (whether that subcommand exits 1), and `response`, the envelope the check returns on its own. The totals are `data.errors`, `data.warnings`, and `data.skipped` (each reason prefixed with its check); an issue every check starts from, such as one about the manifest, counts once, and every other finding counts on its own. `data.unchecked` counts the items the checks list as not compared, which never fail it. With `strict`, `data.failures` lists each warning and each piece of skipped work once again as an error in the checks' own issue format ({check, severity: `error`, code, message, component, prop, fix, file, line}, each where it applies); it is empty without `strict`. `data.failed` decides the exit code.",
+    },
+  ],
+  examples: [
+    {
+      label: 'Check the local package',
+      code: 'const r = await integrationCheck();',
+    },
+    {
+      label: 'Fail on warnings too',
+      code: 'const {data} = await integrationCheck({strict: true});\nif (data.failed) process.exitCode = 1;',
+    },
+  ],
+  command: 'integration check',
+  related: [
+    'validateIntegration',
+    'integrationComponentConflicts',
+    'integrationTemplateConflicts',
+    'integrationDocConflicts',
+    'integrationPackCheck',
+  ],
+};

package/api/integration/integrationComponentConflicts.doc.mjs

@@ -19,9 +19,24 @@ export const doc = {
     'declares the CLI range that turns replacement on and warnings otherwise. ' +
     "Each component doc's props are compared with the component's TypeScript props, " +
     "read with the project's own `typescript`: a documented prop the code lacks, a " +
-    'prop the package declares that the doc omits, or a wrong `required`. Those ' +
-    'findings are warnings ' +
-    'in `propDrift`; without TypeScript it is `skipped` with a reason.',
+    'prop the package declares that the doc omits, a wrong `required`, or a type ' +
+    'that does not match. A type is judged only when it reads exactly: the same ' +
+    'text as the source, once whitespace, quotes and union order are set aside (exactly, if it contains `readonly`), ' +
+    'or primitives, literals, arrays and unions of those, or a name for one, on ' +
+    'both sides, a field such as `status.type` included, and for a union of ' +
+    "props types, the type of any one member. A field the prop's variants give " +
+    "different types is listed when the doc gives only some variants' types. A " +
+    'mutable array type matches a readonly one, because callers can pass it; a ' +
+    'readonly one documented for a mutable array is a mismatch. ' +
+    '`Name = …` with a union after it ' +
+    "must match in both parts; one value after it (`Size = 'md'`) is read as a " +
+    "default. A name only TypeScript's own libraries declare is not resolved, and " +
+    '`React.X` resolves through React where the prop is declared. Every ' +
+    'other type is listed as not compared, never reported, and so is a name an ' +
+    'index signature takes unless exactly one the package declares takes it; ' +
+    'with a TypeScript older than 4.8 no type is judged. ' +
+    'Those findings are warnings in `propDrift`; without TypeScript it is ' +
+    '`skipped` with a reason.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'integrationComponentConflicts(pkg?: string, options?: IntegrationAuthoringOptions): Promise<IntegrationComponentConflictResponse>',
@@ -42,7 +57,7 @@ export const doc = {
     {
       type: 'integration.component-conflicts',
       description:
-        '`validated` (false when no integration manifest was found, so nothing was inspected), integration identity, structural and replaces issues, and Core component-name conflicts with package-qualified commands. An active replacement that keeps the Core name it replaces is not a conflict. When the manifest loads and declares a components root, `propDrift` holds the props comparison: `status` (`checked` | `skipped`), `reason` when skipped, `typescript`, `components` compared, `findings` ({component, prop, kind: `not_in_code` | `not_in_doc` | `required_mismatch`, severity: `warning`, message, doc, source, docType?, codeType?, docRequired?, codeRequired?}), `unchecked` ({component, doc, reason}), and `propsNotChecked` when a mapped type builds props from keys the check cannot trace to the package ({component, doc, reason, props}: no warning is drawn for those props).',
+        '`validated` (false when no integration manifest was found, so nothing was inspected), integration identity, structural and replaces issues, and Core component-name conflicts with package-qualified commands. An active replacement that keeps the Core name it replaces is not a conflict. When the manifest loads and declares a components root, `propDrift` holds the props comparison: `status` (`checked` | `skipped`), `reason` when skipped, `typescript`, `components` compared, `typesCompared` (documented prop types judged), `typesSkipped` (why none was, with a TypeScript older than 4.8), `findings` ({component, prop, kind: `not_in_code` | `not_in_doc` | `required_mismatch` | `type_mismatch`, severity: `warning`, message, doc, source, docType?, codeType?, docRequired?, codeRequired?}), `unchecked` ({component, doc, reason}), `typesNotCompared` ({component, doc, reason, props}: every other documented prop type, grouped by why it was not judged: not a form the check judges exactly (a doc type that does not parse, or a prop a mapped type builds from keys the check cannot trace, included), a field the prop\'s variants give different types, a standard prop such as `className`, or a prop declared outside the package), and `propsNotChecked` when a mapped type builds props from keys the check cannot trace to the package ({component, doc, reason, props}: no warning is drawn for those props).',
     },
   ],
   examples: [

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.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,25 @@ 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`: 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 +60,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

@@ -40,19 +40,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.
  *
@@ -213,6 +214,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.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,46 @@ 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',
+    '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,
   );

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

@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A reader looking for the check a build runs finds
+ * `astryx integration check` first.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {search} from './search.mjs';
+
+describe('search finds integration check for CI', () => {
+  it.each([
+    'ci',
+    'continuous integration',
+    'typecheck integration',
+    'integration check',
+  ])('`%s` ranks it first', async query => {
+    const {results} = (await search(query)).data;
+    expect(results[0], JSON.stringify(results.slice(0, 3))).toMatchObject({
+      domain: 'doc',
+      name: 'cli/commands/integration-check',
+    });
+  });
+});

package/api/search/search.mjs

@@ -57,9 +57,10 @@
  * Between domains, ranking adds one rule ahead of the score: domain priority
  * (see {@link domainPriority}). A component, hook, template, or theme whose
  * name or keyword a query word hits ranks ahead of every doc the reader did not
- * ask for by name or title, so `font size` finds `Text` before a typography
- * topic that declares the phrase. A doc the query names, or whose title the
- * query holds, keeps its place.
+ * ask for by name, title, or a declared phrase, so `font size` finds `Text`
+ * before a token page whose heading holds the phrase. A doc the query names,
+ * whose title the query holds, or that declares the whole query as a keyword
+ * keeps its place.
  *
  * Description and guidance are separate tiers on purpose. A component's own
  * one-line description saying "notification" is a claim about what it IS; the
@@ -138,6 +139,9 @@ import {setResultCoverage} from './coverage.mjs';
  * @property {string[]} [aliases] - Other names the candidate answers to, scored
  *   with the same name signals: a theme's display name.
  * @property {string[]} [keywords]
+ * @property {string[]} [_declared] - A doc's own declared keywords: what its
+ *   author lists in `keywords`, without the code terms and table cells its
+ *   other keywords add.
  * @property {string[]} [weakKeywords]
  * @property {string} [description]
  * @property {string[]} [prose]
@@ -513,19 +517,20 @@ const STRONG_TOKEN_SCORE = 70;
  *   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.
  *
@@ -551,6 +556,20 @@ export function domainPriority(term, tokens, candidate, hit) {
     if (named.some(n => samePhrase(term, n))) {
       return 2;
     }
+    // A query of two or more words that is one of the doc's own declared
+    // keywords, read as words whatever the plural, is the author naming the
+    // doc for that phrase: `code review` on a guide that declares it. Only
+    // what the author declared counts: the code terms and table cells a
+    // doc's other keywords add (`missing_field`) name what it mentions, not
+    // what it is for. One word is left out too, and a section declares
+    // nothing.
+    if (
+      phraseWords(term).length >= 2 &&
+      candidate._section == null &&
+      (candidate._declared ?? []).some(k => samePhrase(term, String(k)))
+    ) {
+      return 1;
+    }
     if (
       words.some(
         w =>
@@ -1508,6 +1527,10 @@ async function gatherDocs(cwd) {
         ...defined,
         ...codeTerms({content}),
       ],
+      _declared: [
+        ...(Array.isArray(selfDoc?.keywords) ? selfDoc.keywords : []),
+        ...(Array.isArray(node.keywords) ? node.keywords : []),
+      ],
       description: node.summary || '',
       prose: sectionProse({title: node.title, content}),
       titles: [node.title],
@@ -1644,6 +1667,7 @@ function topicCandidates(
         ...(doc?.title || title ? [doc?.title || title] : []),
         ...(Array.isArray(doc?.keywords) ? doc.keywords : []),
       ],
+      _declared: Array.isArray(doc?.keywords) ? doc.keywords : [],
       description: doc?.description || summary,
       prose: split
         ? sections.map(section => section.title).filter(Boolean)

package/api/theme/build/build.family.test.mjs

@@ -13,6 +13,7 @@ import {themeBuild, themeBuildFamily} from './build.mjs';
 import {interceptCore} from './core-interception.mjs';
 import {ensureCoreBuilt} from '../../../clients/cli/commands/ensure-core-built.mjs';
 import {runCli} from '../../../test-utils/run-cli.mjs';
+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 vi.setConfig({testTimeout: 120_000});
 const CLI_ROOT = path.resolve(import.meta.dirname, '../../..');
 const FAMILY_KEY = 'ocean-family';
@@ -252,22 +253,69 @@ describe('themeBuildFamily()', () => {
     expect(fs.existsSync(dtsPath)).toBe(false);
   });
 
-  it('refuses family outputs outside cwd before checking or writing', async () => {
+  it('refuses to write family outputs outside cwd, and checks them read-only', async () => {
     const dir = makeDir();
     const files = writeFamily(dir).map(file => path.join(dir, file));
     const app = path.join(dir, 'app');
     fs.mkdirSync(app);
 
-    for (const check of [false, true]) {
-      await expect(
-        themeBuildFamily(files, {familyKey: FAMILY_KEY, check}, {cwd: app}),
-      ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
-    }
+    await expect(
+      themeBuildFamily(files, {familyKey: FAMILY_KEY}, {cwd: app}),
+    ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+    const checked = await themeBuildFamily(
+      files,
+      {familyKey: FAMILY_KEY, check: true},
+      {cwd: app},
+    );
+    expect(checked?.type).toBe('theme.build.check');
+    expect(checked?.data.upToDate).toBe(false);
+    // The `.css.d.ts` import stub may be absent in check mode.
+    expect(checked?.data.stale).toEqual(
+      OUTPUTS.filter(file => !file.endsWith('.css.d.ts')).map(file => ({
+        path: `../themes/${file}`,
+        reason: 'missing',
+      })),
+    );
     for (const output of OUTPUTS) {
       expect(fs.existsSync(path.join(dir, 'themes', output))).toBe(false);
     }
   });
 
+  it('ends a stale family report for outputs outside cwd with a remedy that works', async () => {
+    const dir = makeDir();
+    const files = writeFamily(dir).map(file => path.join(dir, file));
+    const app = path.join(dir, 'app');
+    fs.mkdirSync(app);
+    const family = ['--family', ...files, '--family-key', FAMILY_KEY];
+
+    const stale = await runCli(['theme', 'build', ...family, '--check'], app);
+    expect(stale.code).toBe(1);
+    // The old remedy ran the build from cwd, which refuses these outputs.
+    expect(stale.stderr).not.toContain('Rebuild with:');
+
+    const lines = stale.stderr.split('\n').map(line => line.trim());
+    const runDir = lines.find(line => line.startsWith('cd '))?.slice(3);
+    expect(runDir).toBe(fs.realpathSync(path.join(dir, 'themes')));
+    const stem = `${getCliInvocation(runDir)} theme build `;
+    const [buildArgs, checkArgs] = lines
+      .filter(line => line.startsWith(stem))
+      .map(line => line.slice(stem.length).split(' '));
+    expect(checkArgs).toEqual([...buildArgs, '--check']);
+
+    // Following the remedy builds, and the check from there passes.
+    const built = await runCli(['theme', 'build', ...buildArgs], runDir);
+    expect(built.code).toBe(0);
+    for (const output of OUTPUTS) {
+      expect(fs.existsSync(path.join(dir, 'themes', output))).toBe(true);
+    }
+    const checked = await runCli(
+      ['--json', 'theme', 'build', ...checkArgs],
+      runDir,
+    );
+    expect(checked.code).toBe(0);
+    expect(JSON.parse(checked.stdout).data.upToDate).toBe(true);
+  });
+
   it('fails without publishing a mixed trio when staging a write fails', async () => {
     const dir = makeDir();
     const files = writeFamily(dir);