@astryxdesign/cli 0.7.2-canary.ebcc404 → 0.7.2-canary.f8f7cf1

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

@@ -10,17 +10,45 @@ export const doc = {
   namespace: 'cli/api',
   displayName: 'integrationComponentConflicts()',
   summary:
-    'Check integration component names and replaces declarations against Core.',
+    'Check integration component names, replaces declarations, and documented props.',
   description:
     'Loads one local or installed integration, compares its component names with ' +
     'Core, and returns non-blocking conflicts with the exact package-qualified ' +
     "component command required to keep an intentional overlap. Each component's " +
     'replaces is checked too: its findings are issues, errors for a package that ' +
-    'declares the CLI range that turns replacement on and warnings otherwise.',
+    '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, 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>',
-  keywords: ['integration', 'component', 'conflict', 'authoring', 'doctor'],
+  keywords: [
+    'integration',
+    'component',
+    'conflict',
+    'authoring',
+    'doctor',
+    'props',
+    'drift',
+  ],
   params: [
     {name: 'pkg', type: 'string', description: 'Installed package; omit for the local package.'},
     {name: 'options.cwd', type: 'string', description: 'Resolution directory.'},
@@ -29,11 +57,14 @@ 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.',
+        '`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: [
-    {label: 'Check the local integration', code: 'await integrationComponentConflicts();'},
+    {
+      label: 'Check the local integration',
+      code: 'await integrationComponentConflicts();',
+    },
   ],
   command: 'doctor integration components',
   related: ['integrationTemplateConflicts', 'component'],

package/api/integration/pack-check.mjs

@@ -52,6 +52,8 @@ import {
 import {
   discoverIntegrationComponents,
   docStem,
+  familyImports,
+  isIntegrationMember,
   resolveIntegrationImportPath,
 } from '../../foundation/discovery/component-discovery.mjs';
 import {loadComponentReplacements} from '../component/_adapter.mjs';
@@ -381,11 +383,16 @@ async function validatePackedComponentExports(integration, scratchBase) {
   const issues = [];
   /** @type {Array<{name: string, specifier: string}>} */
   const components = [];
+  // A family doc backs several records: load it, and report it, once.
+  const loads = new Map();
   for (const record of records) {
+    const first = !loads.has(record.docPath);
+    if (first) loads.set(record.docPath, loadComponentDoc(record.docPath));
     let docs;
     try {
-      docs = await loadComponentDoc(record.docPath);
+      docs = await loads.get(record.docPath);
     } catch (err) {
+      if (!first) continue;
       issues.push(
         error(
           'component_doc_unloadable',
@@ -994,6 +1001,24 @@ export async function integrationPackCheck(options = {}) {
   const fileInv = computeRequiredFiles(loaded);
   const {identities: localIdentities, errors: localDiscoveryErrors} =
     await collectIdentities(loaded);
+  // A family lists its members from the module its import names, which the
+  // pack lifecycle may build or rebuild, so they are compared as local
+  // discovery lists them after the pack.
+  const familiesBefore = familyImports(loaded).map(family => family.docPath);
+  /**
+   * @param {Array<{name: string, docPath: string|null}>} records
+   * @param {Set<string>} families
+   */
+  const membersOf = (records, families) =>
+    records
+      .filter(
+        r =>
+          r.docPath != null &&
+          families.has(r.docPath) &&
+          isIntegrationMember(r),
+      )
+      .map(r => r.name);
+  const recordsBefore = discoverIntegrationComponents(loaded);
   for (const discoveryError of localDiscoveryErrors) {
     issues.push(
       error(
@@ -1254,7 +1279,27 @@ export async function integrationPackCheck(options = {}) {
       );
     }
 
-    issues.push(...compareIdentities(localIdentities, packedIdentities));
+    const families = new Set([
+      ...familiesBefore,
+      ...familyImports(loaded).map(family => family.docPath),
+    ]);
+    let localComponents = localIdentities.components;
+    if (families.size > 0) {
+      const stale = new Set(membersOf(recordsBefore, families));
+      const built = new Set(
+        membersOf(discoverIntegrationComponents(loaded), families),
+      );
+      const {identities: afterPack} = await collectIdentities(loaded);
+      localComponents = [
+        ...new Set([
+          ...localComponents.filter(name => !stale.has(name)),
+          ...afterPack.components.filter(name => built.has(name)),
+        ]),
+      ].sort();
+    }
+    // The receipt reports the local inventory that was compared.
+    const comparedLocal = {...localIdentities, components: localComponents};
+    issues.push(...compareIdentities(comparedLocal, packedIdentities));
     issues.push(
       ...(await validatePackedThemeExports(
         loaded,
@@ -1276,7 +1321,7 @@ export async function integrationPackCheck(options = {}) {
       pkgVersion,
       fileInv,
       packResult,
-      localIdentities,
+      comparedLocal,
       packedIdentities,
       issues,
     );

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

@@ -786,6 +786,253 @@ describe('integrationPackCheck', () => {
     ]);
   });
 
+  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'),

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,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.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',
+    });
+  });
+});