@astryxdesign/cli 0.7.2-canary.e2909cf → 0.7.2-canary.e4bdd70

package/clients/cli/commands/integration.mjs

@@ -3,18 +3,22 @@
 /** @file CLI bindings for integration authoring and package verification. */
 
 import {integrationAdd} from '../../../api/integration/add-contribution.mjs';
+import {integrationCheck} from '../../../api/integration/check/check.mjs';
 import {integrationPackCheck} from '../../../api/integration/pack-check.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {NO_RESULT_SET} from '../../../foundation/debug/index.mjs';
-import {emit, list, section, text} from '../formatters/index.mjs';
+import {emit, list, records, section, text} from '../formatters/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {doc as integrationGroup} from './integration.doc.mjs';
 import {doc as integrationAddCommand} from './integration-add.doc.mjs';
+import {doc as integrationCheckCommand} from './integration-check.doc.mjs';
 import {doc as integrationVerifyCommand} from './integration-verify.doc.mjs';
 import {doc as integrationPackCommand} from './integration-pack.doc.mjs';
 import {doc as integrationAddFn} from '../../../api/integration/integrationAdd.doc.mjs';
+import {doc as integrationCheckFn} from '../../../api/integration/integrationCheck.doc.mjs';
+import {printIntegrationCheckResponse} from './doctor.mjs';
 import {doc as integrationPackCheckFn} from '../../../api/integration/integrationPackCheck.doc.mjs';
 
 /**
@@ -88,6 +92,102 @@ async function verifyPackage(program) {
   return NO_RESULT_SET;
 }
 
+/**
+ * Run `integration check` and print each check as its own subcommand prints
+ * it, then one summary: each check's errors, warnings and skipped work, and
+ * what decided the exit code.
+ * @param {import('commander').Command} program
+ * @param {{strict?: boolean}} options
+ */
+async function checkPackage(program, options) {
+  const result = await integrationCheck({strict: options.strict === true});
+  if (program.opts().json) {
+    jsonOut(result);
+  } else {
+    const {data} = result;
+    const noPackage = data.checks[0]?.response.data.issues.some(
+      issue => issue.code === 'no_package',
+    );
+    if (noPackage) {
+      emit(
+        text(
+          'Nothing was checked: no package.json found. Run this command inside a package directory.',
+        ),
+      );
+    } else if (!data.validated) {
+      emit(
+        text(
+          'Nothing was checked: no astryx.integration.* found next to package.json. ' +
+            "Run this command in an integration package's folder.",
+        ),
+      );
+    } else {
+      data.checks.forEach((check, index) => {
+        // A blank line keeps each check's output apart from the next.
+        if (index > 0) emit(text(''));
+        printIntegrationCheckResponse(check.response);
+      });
+    }
+    const plural = (/** @type {number} */ n, /** @type {string} */ word) =>
+      `${n} ${word}${n === 1 ? '' : 's'}`;
+    const counts =
+      `${plural(data.errors, 'error')}, ${plural(data.warnings, 'warning')}, ` +
+      `${data.skipped.length} skipped`;
+    const notCompared =
+      data.unchecked > 0
+        ? ` ${plural(data.unchecked, 'item')} could not be compared; the checks above list them.`
+        : '';
+    const closing = noPackage
+      ? `[fail] ${counts}. No package.json was found here, so nothing was checked.`
+      : data.checks.some(check => check.failed)
+        ? `[fail] ${counts}. Address the items marked [fail] above.`
+        : data.failed
+          ? `[fail] ${counts}. --strict fails on every warning and on skipped work; fix them, or drop --strict to fail only on errors.`
+          : data.warnings > 0 || data.skipped.length > 0
+            ? `[ok] ${counts}. No check failed; review the warnings and skipped work above (--strict fails on them).${notCompared}`
+            : notCompared
+              ? `[ok] ${counts}. No check failed.${notCompared}`
+              : `[ok] ${counts}. Every check passed.`;
+    const identity = noPackage
+      ? '(no package.json)'
+      : data.version != null
+        ? `${data.name}@${data.version}`
+        : data.name;
+    emit(
+      // --strict lists each warning and each skipped check again, as the
+      // error it now is, in the issue format the checks use.
+      ...(data.failures.length > 0
+        ? [
+            section('Failing under --strict'),
+            records(data.failures, {
+              fields: [
+                'severity',
+                'check',
+                'code',
+                'component',
+                'prop',
+                'message',
+                'fix',
+                'file',
+                'line',
+              ],
+              format: {severity: () => '[fail]'},
+            }),
+          ]
+        : []),
+      section(
+        `Integration check: ${identity ?? '(local package)'}${data.strict ? ' (strict)' : ''}`,
+      ),
+      records(data.checks, {
+        fields: ['check', 'failed', 'errors', 'warnings', 'skipped'],
+      }),
+      text(closing),
+    );
+  }
+  if (result.data.failed) process.exitCode = 1;
+  return NO_RESULT_SET;
+}
+
 /** @param {import('commander').Command} program */
 export function registerIntegration(program) {
   /** @type {import('commander').Command} */
@@ -159,6 +259,12 @@ export function registerIntegration(program) {
   });
   addCmd.allowExcessArguments(false);
 
+  // It takes no package name, so a name passed by mistake is an error, not a
+  // silent check of the current folder.
+  defineCommand(integration, integrationCheckCommand, {
+    fn: integrationCheckFn,
+    action: async options => checkPackage(program, options),
+  }).allowExcessArguments(false);
   defineCommand(integration, integrationVerifyCommand, {
     fn: integrationPackCheckFn,
     action: async () => verifyPackage(program),

package/clients/cli/commands/text-json-parity.test.mjs

@@ -341,6 +341,11 @@ const CASES = [
     args: ['doctor', 'integration', 'validate'],
     skipFieldChecks: true,
   },
+  {
+    name: 'integration check',
+    args: ['integration', 'check'],
+    skipFieldChecks: true,
+  },
   {
     name: 'doctor integration components',
     args: ['doctor', 'integration', 'components'],

package/clients/cli/commands/theme-build.doc.mjs

@@ -30,7 +30,7 @@ export const doc = {
     {
       flag: '--family',
       description:
-        'Build the selected extension family into one keyed CSS, JS, and declaration set, written beside the family root theme file, which must be inside the working directory (ERR_PATH_TRAVERSAL). Requires --family-key; refused with --out or --watch (ERR_THEME_INVALID)',
+        'Build the selected extension family into one keyed CSS, JS, and declaration set, written beside the family root theme file, which must be inside the working directory to build (ERR_PATH_TRAVERSAL); --check only reads, so it compares outputs anywhere. Requires --family-key; refused with --out or --watch (ERR_THEME_INVALID)',
     },
     {
       flag: '--family-key <key>',
@@ -41,7 +41,7 @@ export const doc = {
       flag: '-o, --out <path>',
       param: 'options.out',
       description:
-        'Output CSS file path, relative or absolute; the .js and .d.ts are written beside it (default: <theme name>.css next to the source). Every output must resolve inside the working directory, the defaults beside the source too (ERR_PATH_TRAVERSAL). Single theme only: refused with more than one file or with --family (ERR_THEME_INVALID)',
+        'Output CSS file path, relative or absolute; the .js and .d.ts are written beside it (default: <theme name>.css next to the source). A build writes only inside the working directory, the defaults beside the source too (ERR_PATH_TRAVERSAL); --check writes nothing, so it compares outputs anywhere and refuses only a relative path that escapes the working directory. Single theme only: refused with more than one file or with --family (ERR_THEME_INVALID)',
     },
     {
       flag: '--icons-specifier <specifier>',

package/clients/cli/index.mjs

@@ -98,6 +98,7 @@ export const JSON_SUPPORTED = new Set([
   'theme targets',
   'theme palette generate',
   'integration add',
+  'integration check',
   'integration verify',
   'integration pack',
   'upgrade',

package/foundation/config/project.mjs

@@ -60,6 +60,7 @@ import {
   applyTemplateReplacements,
   effectiveTemplateDiscovery,
   discoverAllUnresolved as discoverTemplates,
+  discoverCoreTemplates,
   discoverIntegrationTemplatesForOne,
 } from '../discovery/template-adapter.mjs';
 import {
@@ -821,6 +822,85 @@ export class Project {
     });
   }
 
+  /**
+   * The components and templates this project reads, as links name them: by
+   * owner provider id, kind, and name (a template by its id).
+   * @returns {Promise<import('../discovery/docs-discovery.mjs').LinkableContributions>}
+   */
+  async #linkableContributions() {
+    /** @type {Map<string, string>} */
+    const providers = new Map([[CORE_PACKAGE, CORE_PACKAGE]]);
+    for (const integration of this.#loadedIntegrations) {
+      if (integration?.name) {
+        providers.set(
+          integration.name,
+          integration.providerId ?? integration.name,
+        );
+      }
+    }
+    const providerOf = (/** @type {string | undefined} */ pkg) =>
+      providers.get(pkg ?? CORE_PACKAGE) ?? pkg ?? CORE_PACKAGE;
+    // An active replacement answers to the Core name it replaces, so a link
+    // to that Core component has to select Core (spec:AST-035 FR11).
+    /** @type {Map<string, string>} */
+    const replacing = new Map();
+    if (this.#loadedIntegrations.length > 0) {
+      const {active} = await resolveComponentReplacements(
+        findCoreDir(this.#cwd),
+        this.#loadedIntegrations,
+      );
+      for (const each of active) {
+        replacing.set(`${each.package}\0${each.name}`, each.target);
+      }
+    }
+    const components = (await this.components()).map(record => {
+      const replaces = replacing.get(`${record.package}\0${record.name}`);
+      return {
+        providerId: providerOf(record.package),
+        package: record.package,
+        name: record.name,
+        docPath: record.docPath,
+        ...(replaces == null ? {} : {replaces}),
+      };
+    });
+    /** @param {any} template @param {string} pkg */
+    const linkable = (template, pkg) => ({
+      providerId: providerOf(pkg),
+      package: pkg,
+      type: template.type,
+      id: template.dirName,
+      name: template.name,
+      ...(template.displayName == null
+        ? {}
+        : {displayName: template.displayName}),
+      ...(template.description == null
+        ? {}
+        : {description: template.description}),
+      ...(typeof template.replaces === 'string'
+        ? {replaces: template.replaces}
+        : {}),
+    });
+    /** @param {any} template */
+    const isPageOrBlock = template =>
+      template.type === 'page' || template.type === 'block';
+    // Every Core template, a replaced one too, since `--package
+    // @astryxdesign/core` still opens it; everyone else's as unqualified
+    // lookups see them, an active replacement with the id it takes over.
+    const templates = [
+      ...(await discoverCoreTemplates())
+        .filter(isPageOrBlock)
+        .map(template => linkable(template, CORE_PACKAGE)),
+      .../** @type {any[]} */ (await this.templates())
+        .filter(
+          template =>
+            isPageOrBlock(template) &&
+            (template.package ?? CORE_PACKAGE) !== CORE_PACKAGE,
+        )
+        .map(template => linkable(template, template.package)),
+    ];
+    return {components, templates};
+  }
+
   /**
    * The CLI's own doc topics plus the ones the configured integrations
    * contribute, resolved into one catalog: additions, replacements (with the
@@ -838,6 +918,8 @@ export class Project {
   async docs() {
     return this.#memo('docs', async () => {
       const catalog = DocsCatalog.fromBuiltins();
+      // Links name component, page, and block docs too (spec:AST-047 FR9).
+      catalog.setContributions(() => this.#linkableContributions());
       let rank = 0;
 
       for (const integration of this.#loadedIntegrations) {

package/foundation/discovery/authoring-self-docs.mjs

@@ -46,6 +46,7 @@ export const AUTHORING_SELF_DOCS = [
   'doctypes/reference/reference.doc.mjs',
   'doctypes/schema/schema.doc.mjs',
   'doctypes/template/template.doc.mjs',
+  'doctypes/template/integration-template.doc.mjs',
   'doctypes/theme/theme.doc.mjs',
 ];
 
@@ -192,7 +193,7 @@ export function buildAuthoringReferenceDoc(docs) {
     title: 'Authoring Reference',
     category: 'guide',
     description:
-      'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type.',
+      'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type. The step-by-step guides are under `astryx docs cli/integrations`.',
     sections: docs.map(selfDocSection),
   });
 }

package/foundation/discovery/component-discovery.d.mts

@@ -115,19 +115,99 @@ export function discoverExternalComponentsGrouped(docsDir: string): Record<strin
  * @returns {string | null}
  */
 export function findExternalComponentDoc(docsDir: string, name: string): string | null;
+/** @param {string} docPath */
+export function docStem(docPath: string): string;
+/**
+ * The `.tsx` file in `folder`, or below it, that declares `name`, taking files
+ * in path order: the source of a member whose import never reaches a `.tsx`
+ * file, as when the import names built output.
+ *
+ * @param {string} folder
+ * @param {string} name
+ * @returns {string | null}
+ */
+export function folderSourceFor(folder: string, name: string): string | null;
+/**
+ * Each family doc under an integration's components root that names an
+ * import, with the file the import resolves to: null when it resolves to none,
+ * such as build output that does not exist yet.
+ *
+ * @param {{name: string, components?: string, issuesUrl?: string, __packageDir?: string, __packageExports?: Record<string, unknown>|null}} integration
+ * @returns {Array<{docPath: string, module: string | null}>}
+ */
+export function familyImports(integration: {
+    name: string;
+    components?: string;
+    issuesUrl?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
+}): Array<{
+    docPath: string;
+    module: string | null;
+}>;
+/**
+ * Whether a discovered integration record is a member its family doc lists,
+ * decided from the files, not from whether the doc loads.
+ *
+ * @param {{name: string, docPath: string|null}} record
+ * @returns {boolean}
+ */
+export function isIntegrationMember(record: {
+    name: string;
+    docPath: string | null;
+}): boolean;
+/**
+ * The entry a family doc gives a member that discovery lists under its own
+ * name, or null when the record is the doc's own component or the loaded doc
+ * has no entry for it.
+ *
+ * @param {any} doc the doc loaded from `record.docPath`
+ * @param {{name: string, docPath: string|null}} record
+ * @returns {any}
+ */
+export function integrationMemberEntry(doc: any, record: {
+    name: string;
+    docPath: string | null;
+}): any;
+/**
+ * Visit every component doc under an integration's components root, hidden
+ * ones included, in discovery order, with its stem.
+ * @param {string | undefined} componentsDir
+ * @param {(docPath: string, stem: string) => void} visit
+ */
+export function forEachIntegrationDoc(componentsDir: string | undefined, visit: (docPath: string, stem: string) => void): void;
+/**
+ * Given an integration component doc path, return the sibling component source
+ * (`{Name}.tsx`) if one exists, else null.
+ *
+ * @param {string} docPath absolute path to a `{Name}.doc.{ts,mjs,js}` file
+ * @returns {string|null}
+ */
+export function integrationSourceForDoc(docPath: string): string | null;
 /**
  * Discover ownership records for the components contributed by a single loaded
  * integration. Scans the integration's resolved `components` dir for same-stem
- * doc files and records each with owner package + issuesUrl + sourcePath.
+ * doc files and records each with owner package + issuesUrl + sourcePath. A doc
+ * that names a differently named export of its file is recorded under that
+ * export, and each family member it lists, under the member's name, unless the
+ * name is taken: every doc's file name (a hidden doc's too), a Core name a doc
+ * in the package replaces, and a name an earlier doc records.
  *
- * @param {{name: string, components?: string, issuesUrl?: string}} integration
+ * @param {{name: string, components?: string, issuesUrl?: string, __packageDir?: string, __packageExports?: Record<string, unknown>|null}} integration
  *   a single entry from `loadedIntegrations` (lib/integrations.mjs)
+ * @param {{documentedNames?: boolean}} [options] `documentedNames: false`
+ *   records each doc under its file name alone, without reading the names
+ *   docs document: for a caller that needs only what each doc says
  * @returns {Array<{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>}
  */
 export function discoverIntegrationComponents(integration: {
     name: string;
     components?: string;
     issuesUrl?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
+}, { documentedNames }?: {
+    documentedNames?: boolean;
 }): Array<{
     name: string;
     package: string;
@@ -141,11 +221,16 @@ export function discoverIntegrationComponents(integration: {
  * Invalid metadata or a missing same-stem source removes only that component;
  * callers can report the returned errors while retaining valid siblings. A
  * component whose doc sets `replaces` carries the value as written; the
- * component replacement resolver decides what it means.
+ * component replacement resolver decides what it means. A family member is
+ * read through its family's doc: it never carries the family's `replaces`, and
+ * a family doc that fails to load is reported once. A doc that fails to load
+ * is reported under its file name: what it says cannot be trusted.
  *
  * @param {{name: string, components?: string, issuesUrl?: string}} integration
+ * @param {{documentedNames?: boolean}} [options] as for
+ *   {@link discoverIntegrationComponents}
  * @returns {Promise<{
- *   components: Array<{name: string, package: string, docPath: string, sourcePath: string, issuesUrl: string|undefined, group: string|null, replaces?: unknown}>,
+ *   components: Array<{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null, replaces?: unknown}>,
  *   discovered: Array<{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>,
  *   errors: Array<{name: string, message: string}>,
  * }>}
@@ -154,12 +239,14 @@ export function discoverValidIntegrationComponents(integration: {
     name: string;
     components?: string;
     issuesUrl?: string;
+}, options?: {
+    documentedNames?: boolean;
 }): Promise<{
     components: Array<{
         name: string;
         package: string;
         docPath: string;
-        sourcePath: string;
+        sourcePath: string | null;
         issuesUrl: string | undefined;
         group: string | null;
         replaces?: unknown;
@@ -177,30 +264,103 @@ export function discoverValidIntegrationComponents(integration: {
         message: string;
     }>;
 }>;
+/**
+ * How an owner holds a component name, which the owner rule
+ * ({@link unscopedComponentOwners}) reads: `core` when Core documents it;
+ * `file` when an integration doc named after its file is recorded under it;
+ * `doc` when only a doc records it: an export name, a member, or the file name
+ * of a doc recorded under another export.
+ * @typedef {'core' | 'file' | 'doc'} NameHold
+ */
+/**
+ * How a discovered integration record holds its name.
+ * @param {{name: string, docPath: string|null}} record
+ * @returns {'file' | 'doc'}
+ */
+export function integrationRecordHold(record: {
+    name: string;
+    docPath: string | null;
+}): "file" | "doc";
+/**
+ * The integration component a name finds, as discovery records it, and its
+ * hold: the same-stem doc first, then a doc that records the name as an export
+ * or a member.
+ *
+ * @param {{name?: string, components?: string, __packageDir?: string, __packageExports?: Record<string, unknown>|null}} integration
+ * @param {string} name
+ * @returns {{docPath: string, sourcePath: string|null, hold: 'file' | 'doc'} | null}
+ */
+export function findIntegrationComponent(integration: {
+    name?: string;
+    components?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
+}, name: string): {
+    docPath: string;
+    sourcePath: string | null;
+    hold: "file" | "doc";
+} | null;
+/**
+ * The name discovery records a component doc under: the export its `name`
+ * documents when the doc is recorded under it, else the doc's file name.
+ *
+ * @param {{name?: string, components?: string, __packageDir?: string, __packageExports?: Record<string, unknown>|null}} integration
+ * @param {string} docPath
+ * @returns {string}
+ */
+export function recordedDocName(integration: {
+    name?: string;
+    components?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
+}, docPath: string): string;
 /**
  * Find an integration component's doc file by name within a loaded
  * integration's resolved `components` dir. Honors the same-stem convention
- * (`{Name}.doc.{ts,mjs,js}`), preferring `.ts` → `.mjs` → `.js`.
+ * (`{Name}.doc.{ts,mjs,js}`), preferring `.ts` → `.mjs` → `.js`, and finds a
+ * doc that records the component under another name: a differently named
+ * export of its file, or a member its family doc lists.
  *
- * @param {{components?: string}} integration
+ * @param {{name?: string, components?: string, __packageDir?: string, __packageExports?: Record<string, unknown>|null}} integration
  * @param {string} name bare component name (no `XDS`/`Astryx` prefix)
  * @returns {string|null}
  */
 export function findIntegrationComponentDoc(integration: {
+    name?: string;
     components?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
 }, name: string): string | null;
 /**
- * Find an integration component's swizzleable source file (`{Name}.tsx`) by
- * name within a loaded integration's resolved `components` dir. Returns null
+ * Find an integration component's swizzleable source file by name within a
+ * loaded integration's resolved `components` dir: the same-stem `{Name}.tsx`
+ * of its doc, or, for a family member, the file that declares it. Returns null
  * when the integration ships docs without source.
  *
- * @param {{components?: string}} integration
+ * @param {{name?: string, components?: string, __packageDir?: string, __packageExports?: Record<string, unknown>|null}} integration
  * @param {string} name bare component name
  * @returns {string|null}
  */
 export function findIntegrationComponentSource(integration: {
+    name?: string;
     components?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
 }, name: string): string | null;
+/**
+ * The owner rule: an owner that holds a name only because a doc records it
+ * (`hold: 'doc'`) yields to Core and to every file-named owner; `--package`
+ * still reaches it. Surfaces resolve a replacement first, then this rule, then
+ * which docs load.
+ *
+ * @template {{hold?: string}} T
+ * @param {T[]} owners each with its {@link NameHold}; an owner without one
+ *   counts as Core's or file-named
+ * @returns {T[]}
+ */
+export function unscopedComponentOwners<T extends {
+    hold?: string;
+}>(owners: T[]): T[];
 /**
  * Build a flat list of ownership records for ALL discoverable components —
  * core (built-in) plus every loaded integration. This is the authoritative
@@ -229,3 +389,11 @@ export function discoverOwnedComponents(coreDir: string, loadedIntegrations?: Ar
 }>;
 /** The owner package name for built-in (core) components. */
 export const CORE_PACKAGE: import("../../authoring/index.js").ProviderId;
+/**
+ * How an owner holds a component name, which the owner rule
+ * ({@link unscopedComponentOwners}) reads: `core` when Core documents it;
+ * `file` when an integration doc named after its file is recorded under it;
+ * `doc` when only a doc records it: an export name, a member, or the file name
+ * of a doc recorded under another export.
+ */
+export type NameHold = "core" | "file" | "doc";