@astryxdesign/cli 0.7.2 → 0.7.3-canary.06872b4

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

@@ -10,7 +10,8 @@
  */
 export function validateLocalIntegration(cwd?: string): Promise<ValidateResult>;
 /**
- * Validate an INSTALLED integration package resolved from `cwd`/node_modules.
+ * Validate an INSTALLED integration package: the nearest `node_modules/<spec>`
+ * at or above `cwd`, resolved the way the project loads it.
  * @param {string} spec package name
  * @param {string} [cwd]
  * @returns {Promise<ValidateResult>}
@@ -43,7 +44,6 @@ export function summarizeIssues(issues: Issue[]): {
     errors: number;
     warnings: number;
 };
-export { validateLoadedIntegration };
 export type Issue = import("../../foundation/integrations/issue").AstryxIntegrationIssue;
 export type ValidateResult = {
     /**
@@ -75,6 +75,15 @@ export type ValidateResult = {
         code: string;
         message: string;
     }[] | undefined;
+    /**
+     * Layout findings added after the last minor
+     * release: validate lists them as notes, which count nowhere, since they
+     * may not fail `--strict` until the next (architecture:cli-surface INV35);
+     * `integration verify` still fails on a package.json npm cannot pack.
+     */
+    listed?: import("../../foundation/integrations/issue").AstryxIntegrationIssue[] | undefined;
     integration?: import("../../foundation/integrations/integrations.mjs").LoadedIntegration | undefined;
 };
 import { validateLoadedIntegration } from '../../foundation/integrations/validate-contributions.mjs';
+import { isListedIssue } from '../../foundation/integrations/validate-contributions.mjs';
+export { validateLoadedIntegration, isListedIssue };

package/api/integration/validate-integration.mjs

@@ -12,7 +12,7 @@
  *   - validateLocalIntegration(cwd)  — the package rooted at `cwd` (nearest
  *     package.json + sibling astryx.integration.{ts,mjs,js}).
  *   - validateInstalledIntegration(spec, cwd) — an installed package resolved
- *     from `cwd`/node_modules.
+ *     from the node_modules chain at or above `cwd`.
  *
  * Both return a { found, name, version, manifestFile, issues } result. `found`
  * is false only for the no-manifest local case, which is guidance (not an
@@ -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 {normalizeProviderId} from '../../foundation/identity/provider-identity.mjs';
 import {integrationDocTypes} from '../docs/_adapter.mjs';
 import {integrationDocConsistency} from '../../foundation/discovery/doc-consistency.mjs';
 import {
@@ -51,20 +52,25 @@ import {
 import {
   findManifestPaths,
   loadManifest,
-  resolvePackageDir,
+  resolveInstalledIntegrationDir,
 } from '../../foundation/integrations/integrations.mjs';
 // The on-disk contribution validators live in foundation: Project and
 // integration-warnings need them too, and foundation must not depend on api.
 import {
+  blockComponentsCheck,
+  componentDocNamesCheck,
   INVALID_CLI_COMMAND,
+  isListedIssue,
+  issueListed as listed,
   validateLoadedIntegration,
+  validateLoadedIntegrationListed,
   issueError as error,
   issueWarning as warning,
   rootProblem,
 } from '../../foundation/integrations/validate-contributions.mjs';
 import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
 
-export {validateLoadedIntegration};
+export {validateLoadedIntegration, isListedIssue};
 
 /**
  * @typedef {import('../../foundation/integrations/issue').AstryxIntegrationIssue} Issue
@@ -80,6 +86,10 @@ export {validateLoadedIntegration};
  * @property {Issue[]} issues
  * @property {Array<{code: string, message: string}>} [notes] Information that
  *   fails nothing, such as `invalid_cli_command` (a malformed `cliCommand`).
+ * @property {Issue[]} [listed] Layout findings added after the last minor
+ *   release: validate lists them as notes, which count nowhere, since they
+ *   may not fail `--strict` until the next (architecture:cli-surface INV35);
+ *   `integration verify` still fails on a package.json npm cannot pack.
  * @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration} [integration]
  */
 
@@ -99,6 +109,14 @@ function findNearestPackageJson(cwd) {
   }
 }
 
+const ROOT_KINDS = /** @type {const} */ ([
+  'components',
+  'templates',
+  'codemods',
+  'docs',
+  'themes',
+]);
+
 const UNREACHABLE_SCAN_LIMIT = 5_000;
 const UNREACHABLE_SKIP_DIRS = new Set([
   'node_modules',
@@ -148,27 +166,51 @@ function unreadThemeFolderIssues(packageDir, loaded) {
  *
  * @param {string} packageDir
  * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration} loaded
+ * @param {string[]} [reported] folders whose files another issue already covers
  * @returns {Promise<Issue[]>}
  */
-async function findUnreachableContributionIssues(packageDir, loaded) {
+async function findUnreachableContributionIssues(
+  packageDir,
+  loaded,
+  reported = [],
+) {
+  // A root that is not a readable folder holds nothing: a fix must never
+  // send a file into it.
+  const usable = {...loaded};
+  for (const kind of ROOT_KINDS) {
+    const root = usable[kind];
+    if (root != null && rootProblem(root)) usable[kind] = undefined;
+  }
+  // Every declared root is skipped, readable or not: one that cannot be read
+  // has its own issue.
   const roots = /** @type {string[]} */ (
-    [
-      loaded.components,
-      loaded.templates,
-      loaded.codemods,
-      loaded.docs,
-      loaded.themes,
-    ].filter(Boolean)
+    ROOT_KINDS.map(kind => loaded[kind]).filter(Boolean)
   );
+  // A folder a symlinked root points at is read through that root.
+  const realRoots = roots.map(root => {
+    try {
+      return fs.realpathSync(root);
+    } catch {
+      return root;
+    }
+  });
   /** @type {Issue[]} */
   const issues = [];
-  const context = createFixContext(packageDir, loaded);
+  const context = createFixContext(packageDir, usable);
   let scanned = 0;
   let truncated = false;
 
   /** @param {string} dir */
   async function walk(dir) {
     if (roots.some(root => pathIsInside(dir, root))) return;
+    if (reported.some(folder => pathIsInside(dir, folder))) return;
+    let realDir = dir;
+    try {
+      realDir = fs.realpathSync(dir);
+    } catch {
+      // Unreadable: reported below.
+    }
+    if (realRoots.some(root => pathIsInside(realDir, root))) return;
     let entries;
     try {
       entries = fs
@@ -286,12 +328,14 @@ async function validateAtPackageDir(
   let manifest;
   /** @type {string[]} */
   let unknownKeys;
+  /** @type {string[]} */
+  let declaredKeys;
   /** @type {string | undefined} */
   let agentDocsError;
   /** @type {string | undefined} */
   let cliCommandError;
   try {
-    ({manifest, unknownKeys, agentDocsError, cliCommandError} =
+    ({manifest, unknownKeys, declaredKeys, agentDocsError, cliCommandError} =
       await loadManifest(
         manifestFile,
         `Integration manifest (${path.basename(manifestFile)})`,
@@ -301,9 +345,36 @@ async function validateAtPackageDir(
     return result;
   }
 
-  /** @param {string | null | undefined} value */
-  const resolveRoot = (value, kind = 'contribution root') => {
+  /** @type {string[]} absolute roots inside the package */
+  const absoluteRoots = [];
+  /**
+   * @param {string | null | undefined} value
+   * @param {string} key the manifest key that declares it
+   */
+  const resolveRoot = (value, key, kind = 'contribution root') => {
     if (value == null) return undefined;
+    if (path.isAbsolute(value)) {
+      // An absolute root names this machine's disk, which no install shares,
+      // even when it happens to point inside the package.
+      const inside = path.relative(packageDir, value);
+      const relative =
+        inside === '' || (!inside.startsWith('..') && !path.isAbsolute(inside))
+          ? `./${inside.split(path.sep).join('/')}`.replace(/\/$/u, '')
+          : null;
+      // The code an absolute root has always carried, reworded.
+      result.issues.push(
+        error(
+          'root_outside_package',
+          `The ${key} root "${value}" is an absolute path, so Astryx reads nothing from it: a root is relative to the package, so it resolves the same wherever the package is installed.` +
+            (relative
+              ? ` Fix: set \`${key}: '${relative === './' ? '.' : relative}'\` in ${path.basename(manifestFile)}.`
+              : ` It also points outside the package. Fix: move the files into the package and set \`${key}\` to their folder relative to package.json, such as './${key}'.`),
+        ),
+      );
+      // Its files are reported through this issue, not one by one.
+      if (relative) absoluteRoots.push(path.resolve(value));
+      return undefined;
+    }
     try {
       return assertWithin(value, packageDir, {label: kind});
     } catch {
@@ -320,18 +391,20 @@ async function validateAtPackageDir(
   const loaded = {
     name: identity.name,
     version: identity.version,
-    components: resolveRoot(manifest.components),
-    templates: resolveRoot(manifest.templates),
-    codemods: resolveRoot(manifest.codemods),
-    docs: resolveRoot(manifest.docs),
-    themes: resolveRoot(manifest.themes),
+    components: resolveRoot(manifest.components, 'components'),
+    templates: resolveRoot(manifest.templates, 'templates'),
+    codemods: resolveRoot(manifest.codemods, 'codemods'),
+    docs: resolveRoot(manifest.docs, 'docs'),
+    themes: resolveRoot(manifest.themes, 'themes'),
     issuesUrl: manifest.issuesUrl,
     agentDocs: manifest.agentDocs,
     cliCommand: manifest.cliCommand,
     __cliCommandError: cliCommandError,
     __agentDocsError: agentDocsError,
     __unknownKeys: unknownKeys,
+    __declaredKeys: declaredKeys,
     __spec: identity.name,
+    __declaredProviderId: manifest.providerId,
     __packageDir: packageDir,
     __manifestFile: manifestFile,
   };
@@ -343,7 +416,9 @@ async function validateAtPackageDir(
   // `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)) {
+  const contribution = await validateLoadedIntegrationListed(loaded);
+  (result.listed ??= []).push(...contribution.listed);
+  for (const issue of contribution.issues) {
     if (issue.code === INVALID_CLI_COMMAND) {
       (result.notes ??= []).push({code: issue.code, message: issue.message});
     } else {
@@ -370,7 +445,11 @@ async function validateAtPackageDir(
   );
   if (scanUnreachable) {
     issues.push(
-      ...(await findUnreachableContributionIssues(packageDir, loaded)),
+      ...(await findUnreachableContributionIssues(
+        packageDir,
+        loaded,
+        absoluteRoots,
+      )),
     );
   }
 
@@ -397,7 +476,7 @@ export async function validateLocalIntegration(cwd = process.cwd()) {
     return {found: false, issues: []};
   }
 
-  /** @type {{name?: string, version?: string}} */
+  /** @type {{name?: string, version?: string, private?: boolean}} */
   let pkg;
   try {
     pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
@@ -416,31 +495,121 @@ export async function validateLocalIntegration(cwd = process.cwd()) {
     };
   }
 
-  return validateAtPackageDir(
+  // npm publishes nothing without a name and a version, and the name is the
+  // provider ID every reader keys the package's contributions on.
+  // A package without one is still checked, under a placeholder name.
+  const fields = packageJsonFieldIssues(pkg, pkgJsonPath);
+  const name =
+    typeof pkg.name === 'string' && pkg.name !== ''
+      ? pkg.name
+      : '(local package)';
+  const result = await validateAtPackageDir(
     packageDir,
-    {
-      name: pkg.name ?? '(local package)',
-      version: pkg.version,
-    },
+    {name, version: pkg.version},
     {scanUnreachable: true},
   );
+  (result.listed ??= []).unshift(
+    ...fields,
+    // Only a manifest that loaded says whether it declares a providerId; one
+    // that did not is reported as invalid_manifest.
+    ...(result.integration
+      ? providerIdIssues(
+          pkg.name,
+          result.integration.__declaredProviderId,
+          result.integration.__manifestFile,
+        )
+      : []),
+  );
+  return result;
+}
+
+/**
+ * Whether `name` is a bare npm package name, the form a provider ID takes.
+ * @param {string} name
+ */
+function isPackageName(name) {
+  try {
+    normalizeProviderId(name);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 /**
- * Validate an INSTALLED integration package resolved from `cwd`/node_modules.
+ * A warning when no provider ID can be derived for the package: its
+ * package.json `name` is not a bare package name and its manifest declares
+ * no `providerId` that is one. Readers key the package's contributions on
+ * that ID; a missing name is its own warning.
+ * @param {unknown} name package.json `name`
+ * @param {unknown} declared the manifest's `providerId`
+ * @param {string} manifestFile
+ * @returns {Issue[]}
+ */
+function providerIdIssues(name, declared, manifestFile) {
+  if (typeof name !== 'string' || name === '') return [];
+  if (isPackageName(name)) return [];
+  if (typeof declared === 'string' && isPackageName(declared)) return [];
+  const manifest = path.basename(manifestFile);
+  return [
+    listed(
+      'no_provider_id',
+      `No provider ID can be derived for this package: package.json "name" ${JSON.stringify(name)} is not a bare package name (an optional @scope/ and a name, each starting with a lowercase letter or digit and holding only lowercase letters, digits, "-", ".", "_" and "~"), and ${manifest} declares no providerId that is one. Astryx files the package's components, templates and docs under that ID, so links to them and selecting the package cannot work. Fix: rename the package, such as "@your-scope/your-package", or set \`providerId: '@your-scope/your-package'\` in ${manifest}.`,
+    ),
+  ];
+}
+
+/**
+ * A warning for each field npm needs that package.json lacks.
+ * @param {{name?: unknown, version?: unknown, private?: unknown}} pkg
+ * @param {string} pkgJsonPath
+ * @returns {Issue[]}
+ */
+function packageJsonFieldIssues(pkg, pkgJsonPath) {
+  /** @type {Issue[]} */
+  const issues = [];
+  const shown = path.basename(pkgJsonPath);
+  // Listed, so validate and `--strict` keep the result they had for these
+  // packages; `integration verify`, which packs, reports them as errors.
+  if (typeof pkg.name !== 'string' || pkg.name === '') {
+    issues.push(
+      listed(
+        'invalid_package_json',
+        `${shown} has no "name", so npm cannot pack or publish the package, and a project that installs it has no name to select it by. Fix: add "name": "@your-scope/your-package" to ${shown}.`,
+      ),
+    );
+  }
+  // A private package is never published, so it needs no version.
+  if (
+    pkg.private !== true &&
+    (typeof pkg.version !== 'string' || pkg.version === '')
+  ) {
+    issues.push(
+      listed(
+        'invalid_package_json',
+        `${shown} has no "version", so npm cannot pack or publish the package. Fix: add "version": "0.1.0" to ${shown}.`,
+      ),
+    );
+  }
+  return issues;
+}
+
+/**
+ * Validate an INSTALLED integration package: the nearest `node_modules/<spec>`
+ * at or above `cwd`, resolved the way the project loads it.
  * @param {string} spec package name
  * @param {string} [cwd]
  * @returns {Promise<ValidateResult>}
  */
 export async function validateInstalledIntegration(spec, cwd = process.cwd()) {
-  // resolvePackageDir throws (path-safety guard) on a spec with path segments,
+  // The resolver throws (path-safety guard) on a spec with path segments,
   // `..`, or an absolute path. Every other malformed input to this command
   // degrades into a diagnostic — so catch it here and return an issue instead
   // of letting the throw escape to a raw stack (human) / generic ERR_UNKNOWN
   // (--json).
   let packageDir;
   try {
-    packageDir = resolvePackageDir(spec, cwd);
+    packageDir = resolveInstalledIntegrationDir(spec, cwd);
   } catch (err) {
     return {
       found: true,
@@ -504,7 +673,30 @@ export async function validateIntegration(pkg, options = {}) {
   const docTypes = integration
     ? await integrationDocTypes(integration, cwd)
     : undefined;
-  const notes = result.found ? (result.notes ?? []) : [];
+  // The component names docs and blocks give: those that cannot be judged
+  // are listed in their reports, and those judged wrong are notes.
+  const names = integration
+    ? [
+        await componentDocNamesCheck(integration),
+        await blockComponentsCheck(integration),
+      ]
+    : undefined;
+  const docNames = names?.[0].report;
+  const blockComponents = names?.[1].report;
+  // Notes fail nothing: a malformed `cliCommand`, and the findings added
+  // after the last minor release, each with its fix in the message, which
+  // may not fail `--strict` until the next (architecture:cli-surface INV35):
+  // the layout findings and the component names judged wrong.
+  const notes = result.found
+    ? [
+        ...(result.notes ?? []),
+        ...(result.listed ?? []).map(issue => ({
+          code: issue.code,
+          message: issue.message,
+        })),
+        ...(names ?? []).flatMap(each => each.notes),
+      ]
+    : [];
   return {
     type: 'integration.validate',
     data: {
@@ -526,6 +718,8 @@ export async function validateIntegration(pkg, options = {}) {
           : result.issues,
       ...(notes.length > 0 ? {notes} : {}),
       ...(docTypes ? {docTypes} : {}),
+      ...(docNames ? {docNames} : {}),
+      ...(blockComponents ? {blockComponents} : {}),
     },
   };
 }

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;
@@ -36,7 +37,17 @@ 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
+     *   `invalid_cli_command`, a `cliCommand` that was ignored as malformed, 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`); and `doc_name_mismatch` and
+     *   `unknown_block_component` (see `docNames` and `blockComponents`); they
+     *   become warnings in the next minor release
      */
     data: {
         validated: boolean;
@@ -48,6 +59,8 @@ export type ValidateIntegrationResponse = {
             message: string;
         }>;
         docTypes?: DocTypesReport;
+        docNames?: DocNamesReport;
+        blockComponents?: BlockComponentsReport;
     };
 };
 /**
@@ -57,3 +70,47 @@ export type ValidateIntegrationResponse = {
 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;
+    }>;
+};

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,9 +39,19 @@
  * "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[], notes?: Array<{code: string, message: string}>, docTypes?: DocTypesReport}} 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}} data
  *   `notes`: information beside the issues that fails nothing, such as
- *   `invalid_cli_command`, a `cliCommand` that was ignored as malformed
+ *   `invalid_cli_command`, a `cliCommand` that was ignored as malformed, 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`); and `doc_name_mismatch` and
+ *   `unknown_block_component` (see `docNames` and `blockComponents`); they
+ *   become warnings in the next minor release
  */
 
 /**
@@ -54,4 +65,36 @@
  *   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 {};

package/api/integration/validateIntegration.doc.mjs

@@ -62,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, 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.',
+        '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 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. 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).',
     },
   ],
   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).