@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

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

@@ -37,6 +37,8 @@ const componentDoc = name =>
   `export default {type: 'component', name: '${name}', displayName: '${name}', usage: {description: '${name}.'}, props: []};\n`;
 /** @param {string} name */
 const componentSource = name => `export function ${name}() { return null; }\n`;
+const templateSource = name =>
+  `export default function ${name}() { return null; }\n`;
 /** @param {string} name */
 const topic = name =>
   `export default ${JSON.stringify({
@@ -1131,6 +1133,71 @@ describe('source_without_component_doc fixes hold when followed', () => {
   });
 });
 
+describe('source_without_template_doc fixes hold when followed', () => {
+  it('adds the named doc, which resolves the warning', async () => {
+    const dir = writePackage({
+      [MANIFEST]: manifest({templates: './templates'}),
+      'templates/hero.tsx': templateSource('Hero'),
+      'templates/hero.test.tsx': templateSource('HeroTest'),
+    });
+
+    const message = only(await issuesOf(dir), 'source_without_template_doc');
+    expect(message).toBe(
+      "Template source \"hero.tsx\" has no same-stem metadata file hero.doc.mjs, so `astryx template` never lists it. Fix: add hero.doc.mjs beside it with type: 'page' or 'block'; `astryx docs authoring integration-template-doc` lists its fields. If it is not a template, move it out of the templates root.",
+    );
+
+    const fixed = follow(dir, {
+      write: {
+        'templates/hero.doc.mjs': `export default {type: 'page', name: 'hero', displayName: 'Hero'};\n`,
+      },
+    });
+    expect(await issuesOf(fixed)).toEqual([]);
+  });
+
+  it('checks a dotted template id, but no test, spec or story file', async () => {
+    const dir = writePackage({
+      [MANIFEST]: manifest({templates: './templates'}),
+      'templates/landing.page.tsx': templateSource('LandingPage'),
+      'templates/hero.test.tsx': templateSource('HeroTest'),
+      'templates/hero.spec.tsx': templateSource('HeroSpec'),
+      'templates/hero.stories.tsx': templateSource('HeroStories'),
+    });
+
+    const message = only(await issuesOf(dir), 'source_without_template_doc');
+    expect(message).toContain(
+      'Template source "landing.page.tsx" has no same-stem metadata file landing.page.doc.mjs',
+    );
+
+    const fixed = follow(dir, {
+      write: {
+        'templates/landing.page.doc.mjs': `export default {type: 'page', name: 'landing.page', displayName: 'Landing'};\n`,
+      },
+    });
+    expect(await issuesOf(fixed)).toEqual([]);
+  });
+
+  it('never flags a helper in a subfolder of the templates root', async () => {
+    const dir = writePackage({
+      [MANIFEST]: manifest({templates: './templates'}),
+      'templates/hero.doc.mjs': `export default {type: 'page', name: 'hero', displayName: 'Hero'};\n`,
+      'templates/hero.tsx': templateSource('Hero'),
+      'templates/hero/HeroCard.tsx': templateSource('HeroCard'),
+    });
+
+    expect(await issuesOf(dir)).toEqual([]);
+  });
+
+  it('accepts a released .template.mjs spec as the metadata', async () => {
+    const dir = writePackage({
+      [MANIFEST]: manifest({templates: './templates'}),
+      'templates/hero.tsx': templateSource('Hero'),
+      'templates/hero.template.mjs': `export default {type: 'page', name: 'hero', displayName: 'Hero'};\n`,
+    });
+
+    expect(await issuesOf(dir)).toEqual([]);
+  });
+});
+
 describe('codemod fixes hold when followed', () => {
   it('moves a stray codemod into a version folder, and renames a mis-named one', async () => {
     const dir = writePackage({

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

@@ -67,6 +67,14 @@ export type ValidateResult = {
      */
     reason?: "no_package_json" | undefined;
     issues: Issue[];
+    /**
+     * Information that
+     * fails nothing, such as `invalid_cli_command` (a malformed `cliCommand`).
+     */
+    notes?: {
+        code: string;
+        message: string;
+    }[] | undefined;
     integration?: import("../../foundation/integrations/integrations.mjs").LoadedIntegration | undefined;
 };
 import { validateLoadedIntegration } from '../../foundation/integrations/validate-contributions.mjs';

package/api/integration/validate-integration.mjs

@@ -34,6 +34,8 @@
 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 {integrationDocConsistency} from '../../foundation/discovery/doc-consistency.mjs';
 import {
   THEME_SLUG_RE,
   unreadThemeFolders,
@@ -54,11 +56,13 @@ import {
 // The on-disk contribution validators live in foundation: Project and
 // integration-warnings need them too, and foundation must not depend on api.
 import {
+  INVALID_CLI_COMMAND,
   validateLoadedIntegration,
   issueError as error,
   issueWarning as warning,
   rootProblem,
 } from '../../foundation/integrations/validate-contributions.mjs';
+import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
 
 export {validateLoadedIntegration};
 
@@ -74,6 +78,8 @@ export {validateLoadedIntegration};
  * @property {string} [manifestFile] Absolute path to the loaded manifest.
  * @property {'no_package_json'} [reason] Why nothing was validated (internal).
  * @property {Issue[]} issues
+ * @property {Array<{code: string, message: string}>} [notes] Information that
+ *   fails nothing, such as `invalid_cli_command` (a malformed `cliCommand`).
  * @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration} [integration]
  */
 
@@ -123,7 +129,7 @@ function unreadThemeFolderIssues(packageDir, loaded) {
     let fix;
     if (THEME_SLUG_RE.test(name)) {
       const stem = `${name.replace(/-([a-z0-9])/gu, (_, character) => character.toUpperCase())}Theme`;
-      fix = `if it is a theme, add ${stem}.ts and ${stem}.doc.mjs to it (\`astryx integration add theme ${name}\` writes both) and move its code into ${stem}.ts; if not, ${hide}.`;
+      fix = `if it is a theme, add ${stem}.ts and ${stem}.doc.mjs to it (\`${formatCliCommand(`integration add theme ${name}`, packageDir)}\` writes both) and move its code into ${stem}.ts; if not, ${hide}.`;
     } else {
       fix = `${hide}; a theme folder needs a lower-kebab name.`;
     }
@@ -282,11 +288,14 @@ async function validateAtPackageDir(
   let unknownKeys;
   /** @type {string | undefined} */
   let agentDocsError;
+  /** @type {string | undefined} */
+  let cliCommandError;
   try {
-    ({manifest, unknownKeys, agentDocsError} = await loadManifest(
-      manifestFile,
-      `Integration manifest (${path.basename(manifestFile)})`,
-    ));
+    ({manifest, unknownKeys, agentDocsError, cliCommandError} =
+      await loadManifest(
+        manifestFile,
+        `Integration manifest (${path.basename(manifestFile)})`,
+      ));
   } catch (err) {
     issues.push(error('invalid_manifest', /** @type {any} */ (err).message));
     return result;
@@ -318,6 +327,8 @@ async function validateAtPackageDir(
     themes: resolveRoot(manifest.themes),
     issuesUrl: manifest.issuesUrl,
     agentDocs: manifest.agentDocs,
+    cliCommand: manifest.cliCommand,
+    __cliCommandError: cliCommandError,
     __agentDocsError: agentDocsError,
     __unknownKeys: unknownKeys,
     __spec: identity.name,
@@ -328,9 +339,35 @@ async function validateAtPackageDir(
 
   // Roots + contribution checks are shared with validateLoadedIntegration so
   // the everyday-command nudge runs the exact same validators.
-  issues.push(...(await validateLoadedIntegration(loaded)));
+  // A malformed `cliCommand` is an info note beside the issues, not an issue:
+  // `integration check --strict` fails on any warning, and a new failure code
+  // joins only in a minor release (architecture:cli-surface INV35). Doctor's
+  // project check still warns about it.
+  for (const issue of await validateLoadedIntegration(loaded)) {
+    if (issue.code === INVALID_CLI_COMMAND) {
+      (result.notes ??= []).push({code: issue.code, message: issue.message});
+    } else {
+      issues.push(issue);
+    }
+  }
   if (loaded.themes && !rootProblem(loaded.themes))
     issues.push(...unreadThemeFolderIssues(packageDir, loaded));
+  // What the docs say that no reader serves: a prop listed twice, an
+  // overlay's text for a prop the doc lacks, an empty or unreachable section,
+  // and an overlay of no topic.
+  issues.push(
+    ...(await integrationDocConsistency(
+      {
+        components:
+          loaded.components && !rootProblem(loaded.components)
+            ? loaded.components
+            : undefined,
+        docs:
+          loaded.docs && !rootProblem(loaded.docs) ? loaded.docs : undefined,
+      },
+      packageDir,
+    )),
+  );
   if (scanUnreachable) {
     issues.push(
       ...(await findUnreachableContributionIssues(packageDir, loaded)),
@@ -461,6 +498,13 @@ 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;
+  const notes = result.found ? (result.notes ?? []) : [];
   return {
     type: 'integration.validate',
     data: {
@@ -469,9 +513,19 @@ export async function validateIntegration(pkg, options = {}) {
       validated: result.found,
       name: result.found ? (result.name ?? null) : null,
       version: result.found ? (result.version ?? null) : null,
-      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,
+      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,
+      ...(notes.length > 0 ? {notes} : {}),
+      ...(docTypes ? {docTypes} : {}),
     },
   };
 }

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

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

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

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

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

package/api/integration/validateIntegration.doc.mjs

@@ -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, fix?, file?, line?}: `fix` is the change that resolves the issue, and `file` and `line` where it is, relative to the package, when the check knows them; and `data.notes` when there are any: {code, message} information that fails nothing, such as `invalid_cli_command` for a `cliCommand` that was ignored as malformed. When the manifest loads, `data.docTypes` holds the doc type check: `status` (`checked` | `skipped`), `reason` when skipped, `typescript`, `docs` (doc values checked), `findings` ({doc, line, export, type, field, problem: `unknown_field` | `missing_field` | `wrong_type`, severity: `warning`, message, fix}), `unchecked` ({doc, reason}: a doc that could not be fully checked, or a root its reader cannot read), and `fixtures` when the components or docs root holds test fixture docs under `__tests__`: how many, none of them checked.',
     },
   ],
   examples: [

package/api/search/_adapter.d.mts

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

package/api/search/_adapter.mjs

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