@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

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

@@ -14,6 +14,7 @@ export type LoadedIntegration = {
     codemods?: string | undefined;
     docs?: string | undefined;
     issuesUrl?: string | undefined;
+    __declaredKeys?: string[] | undefined;
     __unknownKeys?: string[] | undefined;
     __spec: string;
     __packageDir: string;
@@ -34,10 +35,114 @@ 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;
+     *   `cli_peer_version`, the running CLI outside the package's
+     *   `@astryxdesign/cli` peer range; and
+     *   the package layout findings added after the last minor release, each with
+     *   its fix in the message: two docs for one component
+     *   (`duplicate_component_doc`), a root reached through a symlink
+     *   (`symlinked_root`), a contribution file that cannot be read
+     *   (`unreadable_file`), a package.json without `name` or `version`
+     *   (`invalid_package_json`), no provider ID (`no_provider_id`), and a doc
+     *   whose file name differs from its source only in letter case where the two
+     *   still pair (`source_without_component_doc`); `doc_name_mismatch` and
+     *   `unknown_block_component` (see `docNames` and `blockComponents`); and
+     *   since 0.7.3 each public-import finding; they become warnings in the next
+     *   minor release; and `runner_command`, an Astryx command a topic writes
+     *   with a package runner
+     */
     data: {
         validated: boolean;
         name: string | null;
         version: string | null;
         issues: import("../../foundation/integrations/issue").AstryxIntegrationIssue[];
+        notes?: Array<{
+            code: string;
+            message: string;
+        }>;
+        docTypes?: DocTypesReport;
+        docNames?: DocNamesReport;
+        blockComponents?: BlockComponentsReport;
+        publicImports?: PublicImportsReport;
     };
 };
+/**
+ * `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;
+};
+/**
+ * Each component doc whose `name` differs from the name it is listed under,
+ * judged against its source. Present when the manifest loads. A name the
+ * module its printed import names provably does not export is a
+ * `doc_name_mismatch` note beside the issues, with its fix in the message
+ * (it becomes a warning in the next minor release), so `findings` is always
+ * empty; `unchecked` lists each doc whose source's
+ * exports could not all be read (a re-export from another package, `export
+ * =`, a destructured binding, a namespace): `file` (the doc, package-relative),
+ * `name` (what the doc says), and `reason`.
+ */
+export type DocNamesReport = {
+    status: "checked";
+    findings: [];
+    unchecked: Array<{
+        file: string;
+        name: string;
+        reason: string;
+    }>;
+};
+/**
+ * Each component name a template gives in `exampleFor` or `componentsUsed`
+ * that could not be judged. Present when the manifest loads. A name neither
+ * the package nor Core has, and the template does not import, is an
+ * `unknown_block_component` note beside the issues, with its fix in the
+ * message (it becomes a warning in the next minor release), so `findings` is
+ * always empty;
+ * `unchecked` lists each name that cannot be judged: one the template may
+ * reach through anything other than named imports and re-exports from
+ * Core, React, StyleX, local helpers or the package's own entry (an import from another
+ * package, a default or namespace import, an alias of or member read off an imported
+ * binding, require(), a dynamic import(), a local module this check cannot
+ * read), or, without Core installed, any name Core would have to resolve: `file` (the template doc, package-relative),
+ * `name`, and `reason`.
+ */
+export type BlockComponentsReport = {
+    status: "checked";
+    findings: [];
+    unchecked: Array<{
+        file: string;
+        name: string;
+        reason: string;
+    }>;
+};
+/**
+ * An import the public-import check could not judge.
+ */
+export type PublicImportUnchecked = {
+    /**
+     * package-relative file that names it
+     */
+    file: string;
+    /**
+     * the import specifier
+     */
+    specifier: string;
+    /**
+     * why it was not checked
+     */
+    reason: string;
+};
+/**
+ * The public-import check's report on validate's result: `unchecked` lists
+ * what it could not judge, never counted or failed on. Its findings are
+ * notes on the result (`data.notes`), so `findings` stays empty.
+ */
+export type PublicImportsReport = {
+    status: "checked";
+    findings: never[];
+    unchecked: PublicImportUnchecked[];
+};

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

@@ -18,6 +18,7 @@
  * @property {string} [codemods]
  * @property {string} [docs]
  * @property {string} [issuesUrl]
+ * @property {string[]} [__declaredKeys]
  * @property {string[]} [__unknownKeys]
  * @property {string} __spec
  * @property {string} __packageDir
@@ -38,7 +39,84 @@
  * "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, docNames?: DocNamesReport, blockComponents?: BlockComponentsReport, publicImports?: PublicImportsReport}} data
+ *   `notes`: information beside the issues that fails nothing, such as
+ *   `invalid_cli_command`, a `cliCommand` that was ignored as malformed;
+ *   `cli_peer_version`, the running CLI outside the package's
+ *   `@astryxdesign/cli` peer range; and
+ *   the package layout findings added after the last minor release, each with
+ *   its fix in the message: two docs for one component
+ *   (`duplicate_component_doc`), a root reached through a symlink
+ *   (`symlinked_root`), a contribution file that cannot be read
+ *   (`unreadable_file`), a package.json without `name` or `version`
+ *   (`invalid_package_json`), no provider ID (`no_provider_id`), and a doc
+ *   whose file name differs from its source only in letter case where the two
+ *   still pair (`source_without_component_doc`); `doc_name_mismatch` and
+ *   `unknown_block_component` (see `docNames` and `blockComponents`); and
+ *   since 0.7.3 each public-import finding; they become warnings in the next
+ *   minor release; and `runner_command`, an Astryx command a topic writes
+ *   with a package runner
+ */
+
+/**
+ * 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
+ */
+
+/**
+ * Each component doc whose `name` differs from the name it is listed under,
+ * judged against its source. Present when the manifest loads. A name the
+ * module its printed import names provably does not export is a
+ * `doc_name_mismatch` note beside the issues, with its fix in the message
+ * (it becomes a warning in the next minor release), so `findings` is always
+ * empty; `unchecked` lists each doc whose source's
+ * exports could not all be read (a re-export from another package, `export
+ * =`, a destructured binding, a namespace): `file` (the doc, package-relative),
+ * `name` (what the doc says), and `reason`.
+ *
+ * @typedef {{status: 'checked', findings: [], unchecked: Array<{file: string, name: string, reason: string}>}} DocNamesReport
+ */
+
+/**
+ * Each component name a template gives in `exampleFor` or `componentsUsed`
+ * that could not be judged. Present when the manifest loads. A name neither
+ * the package nor Core has, and the template does not import, is an
+ * `unknown_block_component` note beside the issues, with its fix in the
+ * message (it becomes a warning in the next minor release), so `findings` is
+ * always empty;
+ * `unchecked` lists each name that cannot be judged: one the template may
+ * reach through anything other than named imports and re-exports from
+ * Core, React, StyleX, local helpers or the package's own entry (an import from another
+ * package, a default or namespace import, an alias of or member read off an imported
+ * binding, require(), a dynamic import(), a local module this check cannot
+ * read), or, without Core installed, any name Core would have to resolve: `file` (the template doc, package-relative),
+ * `name`, and `reason`.
+ *
+ * @typedef {{status: 'checked', findings: [], unchecked: Array<{file: string, name: string, reason: string}>}} BlockComponentsReport
  */
 
 export {};
+
+/**
+ * An import the public-import check could not judge.
+ * @typedef {object} PublicImportUnchecked
+ * @property {string} file package-relative file that names it
+ * @property {string} specifier the import specifier
+ * @property {string} reason why it was not checked
+ */
+
+/**
+ * The public-import check's report on validate's result: `unchecked` lists
+ * what it could not judge, never counted or failed on. Its findings are
+ * notes on the result (`data.notes`), so `findings` stays empty.
+ * @typedef {object} PublicImportsReport
+ * @property {'checked'} status
+ * @property {never[]} findings
+ * @property {PublicImportUnchecked[]} unchecked
+ */

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 and `cli_peer_version` when the running CLI is outside the `@astryxdesign/cli` peer range of the package, and the package layout findings added after the last minor release, each with its fix in the message: `duplicate_component_doc`, `symlinked_root`, `unreadable_file`, `invalid_package_json` (no `name` or `version`), `no_provider_id`, and `source_without_component_doc` for a doc whose file name differs from its source only in letter case where the two still pair; and `doc_name_mismatch` and `unknown_block_component` (see `docNames` and `blockComponents`); they become warnings in the next minor release. A `runner_command` note lists each Astryx command a topic writes with a package runner, with its file, line and the bare command to write. 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. When the manifest loads, `data.docNames` lists the component doc names it could not judge: `status` (`checked`), `findings` (always empty; a doc name the module its import names provably does not export is a `doc_name_mismatch` note, with its fix in the message) and `unchecked` ({file, name, reason}: a doc whose `name` differs from the name it is listed under and whose source exports cannot all be read, such as a re-export from another package). When the manifest loads, `data.blockComponents` lists the component names templates give in `exampleFor` or `componentsUsed` that could not be judged: `status` (`checked`), `findings` (always empty; a name neither the package nor Core has, and the template does not import, is an `unknown_block_component` note, with its fix in the message) and `unchecked` ({file, name, reason}: a name the template may reach through anything other than named imports and re-exports from Core, React, StyleX, local helpers or the entry of the package itself, such as an import from another package, a default or namespace import, an alias of or member read off an imported binding, require() or a dynamic import(), or a local module that cannot be read, or any name Core would have to resolve when Core is not installed). Since 0.7.3 each import apps cannot use is a note in `data.notes`, its fix inside the message, listed only: it does not fail this command or `integration check --strict`, and fails `--strict` from the next minor release. The codes are `component_import_not_exported`, `component_import_other_package`, `component_import_missing_name`, `example_import_not_exported`, `example_import_missing_name`, `template_import_not_exported`, `template_import_outside_root`, `template_private_import`, `template_import_missing_name` and `template_no_default_export`. When the manifest loads, `data.publicImports` is `{status: 'checked', findings: [], unchecked}`: `unchecked` lists each import the check could not judge, as {file, specifier, reason}, the reason starting `example <label>:` for an import in a component example: an `exports` target not built yet; a module whose export list cannot be read in full (CommonJS, or a declaration file it cannot read); a root import in a package with no `exports` (the root module `main` names is not read); every name an import (other than a component doc's own component) names that its module does not export, while a TypeScript file in the package has a `declare module` block for a relative path or the package's own name or a subpath of it, which can add names to that module (a `declare module` in a comment, `declare global`, a wildcard such as `'*.css'`, and another package's name do not count; a file whose text has `declare module` but that cannot be parsed counts); the same for every such name when the package has more than 5,000 files to search for that block; a deep path into build output not built yet in a package with no `exports`; a template import of Core when `@astryxdesign/core` is not installed beside the package (a `packages/core` of the workspace under another name does not count); every import of the package's own name when package.json has no `name` or a `name` that is not a bare package name; one entry for the whole check when package.json cannot be read; and an import of a subpath whose `exports` entry has only a `types` target, unless it is `import type`, every binding is an inline `type`, or every name it imports is a type its types file declares: a value import of a name that file does not declare as a type, a namespace or side-effect import, or any import when the types file cannot be read (it may be build output). `integration check` counts the unchecked as not compared; they never fail it.",
     },
   ],
   examples: [

package/api/search/ORDERING.md

@@ -0,0 +1,28 @@
+# Search ordering data
+
+`astryx search` decides **what matches**, and each match's score and reason, with the lexical ranker (`_lexical.mjs` and the files it imports). The files in this folder only decide **the order of matches inside one score band**: they never add or drop a match, change a score, or move a match past one of another band or kind (doc or not). The bands are scores 195 and up, 188–194, 170–187, 160–169, 151–159, 100–150, 55–99, and under 55. A band can be wide (55–99 holds keyword matches beside one-word description hits), so inside a band a lower score can lead a higher one.
+
+## Rule
+
+`spec:AST-083` owns search's result order; this file describes the data that implements it. Inside one score band, a searcher's static weights decide the order. Matches with the same score move together as one block, in the lexical ranker's order, placed by the learned position of the block's first match: moving each one on its own breaks search's existing rules for tied matches. Matches never cross bands or kinds. There is no model runtime: every number is a plain static value read at load time.
+
+## Files
+
+| File                                                                                           | What it holds                                                                                                                                                                                                                                 |
+| ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tree.weights.json`                                                                            | The root classifier: for each query word or word pair, one number per class (component, hook, doc, template, theme, none). The query's tokens vote, and a topic searcher takes the query only when its class wins by the floor in `tree.mjs`. |
+| `_main-searcher.weights.json`, `_doc-searcher.weights.json`, `_template-searcher.weights.json` | One weight, mean and spread per signal for each searcher (see `SIGNALS` and `PER_DOMAIN` in `_features.mjs`). A match's place inside its band is the weighted sum of its standardized signals.                                                |
+| `_cards.json`                                                                                  | One card per Core component and hook: what it is, the words people use for it, and its main props, written from the item's own source. Cards feed one signal, word overlap with the card.                                                     |
+
+The signals are counts over the query and each entry's own text: the lexical score and rank, BM25 over the entry's name, docs text and card, how many query words the entry covers, whether the query holds the entry's name, and the classifier's guess of the domain.
+
+## Status
+
+These files are static and reviewed. They are not computed when the CLI runs, and nothing at run time writes them.
+
+## Refreshing
+
+- A Core component or hook without a card is still matched and scored as usual; inside its band it is ordered by its other signals.
+- When Core adds or renames items, a reviewed change adds or updates their cards and, if needed, refreshed weights.
+- Any refresh must keep every test that pins search's behavior passing, including the ordering invariants in `_order.test.mjs`. It must also keep the `astryx search` output's matches, scores and reasons identical to the lexical ranker's.
+- Any refresh must also be measured as `spec:AST-083` FR6 requires: against the held-out, fresh and synthetic evaluation sets, with no row worse than the previous order (a row is worse when the paired 95% confidence interval of its change lies entirely below zero).

package/api/search/_adapter.d.mts

@@ -0,0 +1,91 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/** @typedef {import('./_lexical.mjs').Candidate} Candidate */
+/**
+ * The Core a typed search reads: the project's, else the release's own,
+ * installed into the per-user cache first when needed (a network install and
+ * an npm subprocess; spec AST-081 FR3). Throws as requireCoreDir does.
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function requireSearchCoreDir(cwd: string): string;
+/**
+ * Gathers every candidate the query's domains hold.
+ *
+ * @param {{cwd?: string, type?: string}} options
+ * @returns {Promise<{all: Candidate[], components: Candidate[], searchedComponents: boolean, outside: boolean, coreSkipped: string | null}>}
+ */
+export function gatherCandidates(options: {
+    cwd?: string;
+    type?: string;
+}): Promise<{
+    all: Candidate[];
+    components: Candidate[];
+    searchedComponents: boolean;
+    outside: boolean;
+    coreSkipped: string | null;
+}>;
+/**
+ * gatherCandidates, reused within one process: a later search in the same
+ * folder, for the same `type`, ranks the candidates an earlier search
+ * gathered when none of the files that gather read, and none of the folders
+ * it listed or probed, changed since (each is checked by its change time and
+ * size, so an edited doc in a linked package is seen on the next call). A
+ * long-running caller (a docs site's search, an agent harness) then pays the
+ * gather once. A one-shot `astryx search` gathers once, as before.
+ * @param {{cwd?: string, type?: string}} options
+ * @returns {Promise<Gathered>}
+ */
+export function gatherCandidatesReused(options: {
+    cwd?: string;
+    type?: string;
+}): Promise<Gathered>;
+/**
+ * The search tree's static data, read once: the entry cards and each node's
+ * weights file.
+ *
+ * These files are static, reviewed data that only order matches inside a score
+ * band; ORDERING.md beside them says what each holds and how
+ * they are refreshed.
+ * @returns {SearchData}
+ */
+export function loadSearchData(): SearchData;
+export { componentKeywords } from "./_gather-components.mjs";
+export type Candidate = import("./_lexical.mjs").Candidate;
+export type Gathered = Awaited<ReturnType<typeof gatherCandidates>>;
+export type SearcherWeights = {
+    w: number[];
+    mu: number[];
+    sd: number[];
+};
+export type SearchData = {
+    /**
+     *  Each Core component's and hook's source-built card: what it is, the words
+     *  people type for it, its main props.
+     */
+    cards: Record<string, {
+        what?: string;
+        synonyms?: string[];
+        props?: string[];
+    }>;
+    /**
+     * The root classifier's weights.
+     */
+    router: import("../../foundation/route/route.mjs").ClassifierWeights;
+    /**
+     * The main searcher's weights.
+     */
+    main: SearcherWeights;
+    /**
+     * The doc searcher's weights.
+     */
+    doc: SearcherWeights;
+    /**
+     * The template searcher's weights.
+     */
+    template: SearcherWeights;
+};
+export type SearchCatalog = Awaited<ReturnType<typeof gatherCandidates>> & {
+    data: SearchData;
+};