@astryxdesign/cli 0.7.2 → 0.7.3-canary.0bf23bd

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,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,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 +87,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 +110,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 +167,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 +329,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 +346,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 +392,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 +417,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 +446,11 @@ async function validateAtPackageDir(
   );
   if (scanUnreachable) {
     issues.push(
-      ...(await findUnreachableContributionIssues(packageDir, loaded)),
+      ...(await findUnreachableContributionIssues(
+        packageDir,
+        loaded,
+        absoluteRoots,
+      )),
     );
   }
 
@@ -397,7 +477,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 +496,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,
@@ -478,6 +648,24 @@ export async function validateInstalledIntegration(spec, cwd = process.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,
+  }));
+}
+
 /**
  * Unified entry: validate the LOCAL integration (no `pkg`) or an INSTALLED one
  * (`pkg` given) and return the `integration.validate` envelope. The no-manifest
@@ -504,7 +692,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 +742,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,18 @@ 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; and `runner_command`, an
+     *   Astryx command a topic writes with a package runner
      */
     data: {
         validated: boolean;
@@ -48,6 +60,8 @@ export type ValidateIntegrationResponse = {
             message: string;
         }>;
         docTypes?: DocTypesReport;
+        docNames?: DocNamesReport;
+        blockComponents?: BlockComponentsReport;
     };
 };
 /**
@@ -57,3 +71,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,20 @@
  * "healthy" — the two are otherwise byte-identical.
  * @typedef {object} ValidateIntegrationResponse
  * @property {'integration.validate'} type
- * @property {{validated: boolean, name: string | null, version: string | null, issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[], 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; and `runner_command`, an
+ *   Astryx command a topic writes with a package runner
  */
 
 /**
@@ -54,4 +66,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. 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).',
     },
   ],
   examples: [