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

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,19 @@ 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;
+    /**
+     * what the public-import check could not judge
+     */
+    publicImports?: import("./validate-integration.type.mjs").PublicImportsReport | 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,8 +34,10 @@
 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 {integrationRunnerCommands} from './_adapter.mjs';
 import {
   THEME_SLUG_RE,
   unreadThemeFolders,
@@ -51,20 +53,31 @@ 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';
+import {cliPeerVersionProblem} from '../../foundation/integrations/cli-peer-version.mjs';
+import {publicImportIssues} from '../../foundation/integrations/public-imports.mjs';
+import {runChoice} from '../../foundation/release/run-context.mjs';
 
-export {validateLoadedIntegration};
+/** The running CLI is outside the package's `@astryxdesign/cli` peer range. */
+const CLI_PEER_VERSION = 'cli_peer_version';
+
+export {validateLoadedIntegration, isListedIssue};
 
 /**
  * @typedef {import('../../foundation/integrations/issue').AstryxIntegrationIssue} Issue
@@ -80,7 +93,13 @@ 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]
+ * @property {import('./validate-integration.type.mjs').PublicImportsReport} [publicImports]
+ *   what the public-import check could not judge
  */
 
 /**
@@ -99,6 +118,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 +175,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
@@ -235,13 +286,15 @@ async function findUnreachableContributionIssues(packageDir, loaded) {
  * Shared core for the local and installed entry points.
  * @param {string} packageDir
  * @param {{name: string, version?: string}} identity
- * @param {{scanUnreachable?: boolean}} [options]
+ * @param {{scanUnreachable?: boolean, own?: boolean, cwd?: string}} [options]
+ *   `own`: the package is the one being authored in the current folder;
+ *   `cwd`: the folder whose package manager an install command names
  * @returns {Promise<ValidateResult>}
  */
 async function validateAtPackageDir(
   packageDir,
   identity,
-  {scanUnreachable = false} = {},
+  {scanUnreachable = false, own = false, cwd = packageDir} = {},
 ) {
   /** @type {Issue[]} */
   const issues = [];
@@ -286,12 +339,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 +356,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 +402,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,13 +427,33 @@ 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 {
       issues.push(issue);
     }
   }
+  // The running CLI outside the package's `@astryxdesign/cli` peer range is a
+  // note for the same reason. It is built here, not among the contribution
+  // checks, so `integration verify` (which reports their layout findings)
+  // does not see it.
+  // The version an upgrade starts from is the project's: its own CLI's, or,
+  // with none, its Core's, as the project-upgrade notice takes it.
+  const choice = runChoice(cwd);
+  const from =
+    choice.inProject && choice.copy === 'starting' && choice.coreVersion
+      ? choice.coreVersion
+      : undefined;
+  const peerProblem = cliPeerVersionProblem(loaded, undefined, cwd, {
+    own,
+    from,
+  });
+  if (peerProblem) {
+    (result.notes ??= []).push({code: CLI_PEER_VERSION, message: peerProblem});
+  }
   if (loaded.themes && !rootProblem(loaded.themes))
     issues.push(...unreadThemeFolderIssues(packageDir, loaded));
   // What the docs say that no reader serves: a prop listed twice, an
@@ -368,9 +472,21 @@ async function validateAtPackageDir(
       packageDir,
     )),
   );
+  // What the package tells apps to import, read from source: package.json
+  // `exports`, docs, examples and template imports.
+  const publicImports = await publicImportIssues(packageDir, loaded);
+  issues.push(...publicImports.issues);
+  // Each finding is a note until the next minor makes it a warning.
+  if (publicImports.notes.length > 0)
+    (result.notes ??= []).push(...publicImports.notes);
+  result.publicImports = publicImports.report;
   if (scanUnreachable) {
     issues.push(
-      ...(await findUnreachableContributionIssues(packageDir, loaded)),
+      ...(await findUnreachableContributionIssues(
+        packageDir,
+        loaded,
+        absoluteRoots,
+      )),
     );
   }
 
@@ -397,7 +513,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 +532,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,
-    },
-    {scanUnreachable: true},
+    {name, version: pkg.version},
+    {scanUnreachable: true, own: 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,
@@ -472,10 +678,29 @@ export async function validateInstalledIntegration(spec, cwd = process.cwd()) {
     };
   }
 
-  return validateAtPackageDir(packageDir, {
-    name: pkg.name ?? spec,
-    version: pkg.version,
-  });
+  return validateAtPackageDir(
+    packageDir,
+    {name: pkg.name ?? spec, version: pkg.version},
+    {cwd},
+  );
+}
+
+/**
+ * The runner-command notes for a package's topics: each Astryx command a topic
+ * writes with a package runner, where the doc file is, and the bare command to
+ * write.
+ * @param {any} integration a loaded integration
+ * @returns {Promise<Array<{code: string, message: string}>>}
+ */
+async function runnerCommandNotes(integration) {
+  const packageDir = integration.__packageDir;
+  return (await integrationRunnerCommands(integration)).map(each => ({
+    code: 'runner_command',
+    message:
+      typeof packageDir === 'string'
+        ? `${path.relative(packageDir, each.file).split(path.sep).join('/')}: ${each.message}`
+        : each.message,
+  }));
 }
 
 /**
@@ -504,7 +729,35 @@ 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),
+      ]
+    : [];
+  // Each Astryx command a topic writes with a package runner, as a
+  // `runner_command` note with its fix, the same way.
+  if (integration?.docs) {
+    notes.push(...(await runnerCommandNotes(integration)));
+  }
   return {
     type: 'integration.validate',
     data: {
@@ -526,6 +779,12 @@ export async function validateIntegration(pkg, options = {}) {
           : result.issues,
       ...(notes.length > 0 ? {notes} : {}),
       ...(docTypes ? {docTypes} : {}),
+      ...(docNames ? {docNames} : {}),
+      ...(blockComponents ? {blockComponents} : {}),
+      // What the public-import check could not judge: listed, never failed on.
+      ...(result.found && result.publicImports
+        ? {publicImports: result.publicImports}
+        : {}),
     },
   };
 }

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,21 @@ 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;
+     *   `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;
@@ -48,6 +63,9 @@ export type ValidateIntegrationResponse = {
             message: string;
         }>;
         docTypes?: DocTypesReport;
+        docNames?: DocNamesReport;
+        blockComponents?: BlockComponentsReport;
+        publicImports?: PublicImportsReport;
     };
 };
 /**
@@ -57,3 +75,74 @@ 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;
+    }>;
+};
+/**
+ * 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[];
+};