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

package/README.md

@@ -476,10 +476,11 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `doctor`                          | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and an optional fix, always present on warn and fail) plus a `summary` of counts per status.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `integration.add`                 | A contribution-writer receipt: kind, name, optional root {path, created}, integration-manifest path, every affected project-relative path, written, and dryRun.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `integration.pack-check`          | The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}].                                                                                                                                                                                                                                                                    |
-| `integration.validate`            | The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}.                                                                                                                                                                                                                                                                                     |
+| `integration.validate`            | The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}. When the manifest loads, docTypes checks each doc against its published authoring type: status (checked \| skipped), reason, typescript, docs, findings (all warnings, each naming the field and a fix), unchecked, and fixtures (test fixture docs not checked).                   |
 | `integration.template-conflicts`  | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}.                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `integration.component-conflicts` | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command. When the manifest loads and declares a components root, propDrift compares documented props with the TypeScript props: status (checked \| skipped), reason, typescript, components, findings (all warnings), unchecked, and propsNotChecked.                                                                                                                                                                               |
+| `integration.component-conflicts` | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command. When the manifest loads and declares a components root, propDrift compares documented props with the TypeScript props: status (checked \| skipped), reason, typescript, components, typesCompared, typesSkipped, findings (all warnings), unchecked, typesNotCompared, and propsNotChecked.                                                                                                                                |
 | `integration.doc-conflicts`       | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`).                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `integration.check`               | Every source check of an integration package in one result: validated (false when no integration manifest was found, so nothing was checked), the package name and version, strict, and checks, one entry per check (validate, components, templates, docs), each with check, errors, warnings, skipped, failed, and response, the envelope that check returns on its own. The totals are errors, warnings, and skipped; unchecked counts what the checks could not compare. With --strict, failures lists each warning and each piece of skipped work again as an error, in the issue format the checks use; it is empty without --strict. failed decides the exit code.                                     |
 
 <!-- END GENERATED: response-types -->
 <!-- Generated by scripts/generate-cli-readme.mjs from the response-types EnumDoc. Run `pnpm -F @astryxdesign/cli readme`. -->
@@ -580,12 +581,12 @@ There is no factory: write a plain object. For editor autocomplete and
 type-checking, annotate it with the `AstryxConfig` type exported from
 `@astryxdesign/cli/authoring`.
 
-| Field                         | Type                           | Purpose                                                                                         |
-| ----------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
-| `integrations`                | `string[]`                     | Integration package names to load (see [Integrations](#integrations)).                          |
-| `issuesUrl`                   | `string`                       | Where "report an issue" links point for your project. Defaults to the core issue tracker.       |
-| `hooks.postCodemod`           | `PostCodemodHook[]`            | Commands to run after `astryx upgrade` applies codemods (e.g. reinstall, rebuild, reformat).    |
-| `experimental.xle.components` | `Record<string, XleComponent>` | Register app-local components so layout (XLE) expressions can reference them by name. Unstable. |
+| Field                         | Type                           | Purpose                                                                                                                                                                                                 |
+| ----------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `integrations`                | `string[]`                     | Integration package names to load (see [Integrations](#integrations)).                                                                                                                                  |
+| `issuesUrl`                   | `string`                       | Where "report an issue" links point for your project. Defaults to the core issue tracker.                                                                                                               |
+| `hooks.postCodemod`           | `PostCodemodHook[]`            | Commands to run after `astryx upgrade` applies codemods (e.g. reinstall, rebuild, reformat).                                                                                                            |
+| `experimental.xle.components` | `Record<string, XleComponent>` | Custom components for the removed layout expander, keyed by component name. The CLI still validates the field, so an entry without a string `from` makes `astryx.config` invalid, but nothing reads it. |
 
 The config is validated against a strict schema when the CLI loads it, so an
 unknown field is a hard error rather than a silent no-op. `astryx doctor`

package/api/docs/_adapter.d.mts

@@ -281,6 +281,17 @@ export function resolveTopicDocs(topic: unknown, options?: {
     lang: string | null;
     entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry;
 }>;
+/**
+ * Each doc one integration package ships, checked against the published
+ * authoring type for its kind with the project's own TypeScript (spec:AST-039
+ * FR13). Without TypeScript the report says nothing was checked.
+ * @param {any} integration a loaded integration
+ * @param {string} cwd
+ * @returns {Promise<import('../../foundation/discovery/doc-types.mjs').DocTypesReport & {fixtures?: number}>}
+ */
+export function integrationDocTypes(integration: any, cwd: string): Promise<import("../../foundation/discovery/doc-types.mjs").DocTypesReport & {
+    fixtures?: number;
+}>;
 /**
  * A doc a link found: what a read shows of the link, and the typed doc behind
  * it when a reference block can include it.

package/api/docs/_adapter.mjs

@@ -17,8 +17,11 @@
  *   foundation/discovery/docs-discovery, which the catalog comes from.
  */
 
+import * as path from 'node:path';
 import {Project} from '../../foundation/config/project.mjs';
 import {DocsCatalog} from '../../foundation/discovery/docs-discovery.mjs';
+import {checkDocTypes} from '../../foundation/discovery/doc-types.mjs';
+import {integrationDocFiles} from '../../foundation/discovery/integration-doc-files.mjs';
 import {
   linkReferenceTopic,
   lowerReferenceTopic,
@@ -1331,3 +1334,37 @@ export async function resolveTopicDocs(topic, options = {}) {
   const node = await lowerTopic(catalog, entry, effectiveLang);
   return {catalog, node, lang: effectiveLang, entry};
 }
+
+/**
+ * Each doc one integration package ships, checked against the published
+ * authoring type for its kind with the project's own TypeScript (spec:AST-039
+ * FR13). Without TypeScript the report says nothing was checked.
+ * @param {any} integration a loaded integration
+ * @param {string} cwd
+ * @returns {Promise<import('../../foundation/discovery/doc-types.mjs').DocTypesReport & {fixtures?: number}>}
+ */
+export async function integrationDocTypes(integration, cwd) {
+  const packageDir = /** @type {{__packageDir?: string}} */ (integration)
+    .__packageDir;
+  const {files, unread, fixtures} = await integrationDocFiles(integration);
+  const checked = await checkDocTypes(files, {
+    packageDir: packageDir ?? cwd,
+    resolveFrom: [cwd, packageDir],
+  });
+  // Test fixtures no reader serves don't ship as docs: only counted.
+  const report =
+    checked.status === 'checked' && fixtures > 0
+      ? {...checked, fixtures}
+      : checked;
+  if (report.status !== 'checked' || unread.length === 0) return report;
+  // A root its reader cannot read serves no doc; say so rather than skip it.
+  const rel = (/** @type {string} */ file) =>
+    path.relative(packageDir ?? cwd, file).split(path.sep).join('/') || '.';
+  return {
+    ...report,
+    unchecked: [
+      ...report.unchecked,
+      ...unread.map(entry => ({doc: rel(entry.path), reason: entry.reason})),
+    ].sort((a, b) => a.doc.localeCompare(b.doc)),
+  };
+}

package/api/index.d.mts

@@ -16,6 +16,7 @@ export { init } from "./init/init.mjs";
 export { doctor } from "./doctor/doctor.mjs";
 export { integrationAddTheme } from "./integration/add-theme.mjs";
 export { integrationPackCheck } from "./integration/pack-check.mjs";
+export { integrationCheck } from "./integration/check/check.mjs";
 export { AstryxError } from "./error.mjs";
 export { logger } from "./logger.mjs";
 export * from "../foundation/response/batch.type.mjs";
@@ -37,6 +38,7 @@ export * from "./integration/integration-authoring.type.mjs";
 export * from "./integration/pack-check.type.mjs";
 export * from "./integration/validate-integration.type.mjs";
 export * from "./integration/authoring-checks.type.mjs";
+export * from "./integration/integration-check.type.mjs";
 export type Logger = import("./logger.mjs").Logger;
 export { themeBuild, themeAdd, themeRemove, themeUse, themeEject, themeTemplate, themeList, themeListAvailable, themeListCopySources, themeTargets, themePaletteGenerate, generateTonalPalette, listThemes } from "./theme/theme.mjs";
 export { integrationAdd, integrationAddAgentDoc, integrationAddCodemod, integrationAddComponent, integrationAddDoc, integrationAddTemplate } from "./integration/add-contribution.mjs";

package/api/index.mjs

@@ -67,6 +67,7 @@ export {
   integrationComponentConflicts,
   integrationDocConflicts,
 } from './integration/authoring-checks.mjs';
+export {integrationCheck} from './integration/check/check.mjs';
 export {AstryxError} from './error.mjs';
 // The one shared logger: the `logger` instance side-effecting commands write
 // through, plus its generated `Logger` type. Part of the public surface so an
@@ -100,3 +101,4 @@ export * from './integration/integration-authoring.type.mjs';
 export * from './integration/pack-check.type.mjs';
 export * from './integration/validate-integration.type.mjs';
 export * from './integration/authoring-checks.type.mjs';
+export * from './integration/integration-check.type.mjs';

package/api/integration/add-contribution.mjs

@@ -695,7 +695,7 @@ async function addTemplate(name, options) {
   const sourcePath = projectPath(path.relative(packageDir, sourceFile));
   const extensionlessPath = sourcePath.replace(/\.tsx?$/u, '');
   const blockFields = templateType === 'block' ? '\n  aspectRatio: 1,' : '';
-  const specContents = `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */\nexport default {\n  type: '${templateType}',\n  name: '${name}',\n  displayName: '${kebabToTitle(name)}',\n  description: '${kebabToTitle(name)} template.',${blockFields}\n};\n`;
+  const specContents = `/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */\nexport default {\n  type: '${templateType}',\n  name: '${name}',\n  displayName: '${kebabToTitle(name)}',\n  description: '${kebabToTitle(name)} template.',${blockFields}\n};\n`;
   const sourceContents = `export default function ${pascalName}() {\n  return <div>${kebabToTitle(name)}</div>;\n}\n`;
 
   /** @type {import('./add-helpers.mjs').WritePlan[]} */

package/api/integration/add-contribution.test.mjs

@@ -536,7 +536,9 @@ describe('integrationAdd template', () => {
       path.join(tmpDir, 'templates/my-widget.doc.mjs'),
       'utf-8',
     );
-    expect(spec).toContain("@astryxdesign/cli/authoring').TemplateDoc");
+    expect(spec).toContain(
+      "@astryxdesign/cli/authoring').IntegrationTemplateDoc",
+    );
     expect(spec).toContain("type: 'page'");
     expect(spec).toContain("name: 'my-widget'");
 
@@ -830,7 +832,7 @@ describe('typed descriptor conformance', () => {
     for (const [relativePath, type] of [
       ['components/MyWidget.doc.mjs', 'ComponentDoc'],
       ['docs/my-guide.doc.mjs', 'ReferenceDoc'],
-      ['templates/my-page.doc.mjs', 'TemplateDoc'],
+      ['templates/my-page.doc.mjs', 'IntegrationTemplateDoc'],
       ['themes/ocean/oceanTheme.doc.mjs', 'ThemeDoc'],
     ]) {
       const source = fs.readFileSync(path.join(tmpDir, relativePath), 'utf-8');

package/api/integration/check/check.d.mts

@@ -0,0 +1,96 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The code a skipped comparison carries under `--strict`: its key in the
+ * check's result, in snake case, then `_skipped` (`propDrift` is
+ * `prop_drift_skipped`).
+ * @param {string} key
+ */
+export function skippedCode(key: string): string;
+/**
+ * Whether a value is a report a check carries beside its issues: a
+ * comparison with a `status` of `checked` or `skipped` and its `findings`.
+ * @param {unknown} value
+ * @returns {value is IntegrationCheckReport}
+ */
+export function isCheckReport(value: unknown): value is IntegrationCheckReport;
+/**
+ * Every warning in one check's result, and every piece of work it skipped,
+ * as issues: what `--strict` reports as errors. The counts come from the
+ * same list, so the default run and the strict run read the same data.
+ * @param {IntegrationCheckName} check
+ * @param {IntegrationCheckResponse} response
+ * @param {{noPackage?: boolean}} [context] `noPackage`: validate found no
+ *   package.json, which only it reports; then no other check names a
+ *   missing manifest as skipped work
+ * @returns {{warnings: Array<Omit<IntegrationCheckFailure, 'check' | 'severity'>>, skipped: Array<Omit<IntegrationCheckFailure, 'check' | 'severity'>>}}
+ */
+export function strictIssues(check: IntegrationCheckName, response: IntegrationCheckResponse, context?: {
+    noPackage?: boolean;
+}): {
+    warnings: Array<Omit<IntegrationCheckFailure, "check" | "severity">>;
+    skipped: Array<Omit<IntegrationCheckFailure, "check" | "severity">>;
+};
+/**
+ * Count one check's result the way its own subcommand exits. Errors are what
+ * make it exit 1: error-severity issues, and for `docs` error findings.
+ * Warnings are warning issues, conflicts and findings, and the findings of
+ * any report the check carries. Skipped names work that did not run: no
+ * integration manifest, or a report that was skipped.
+ * @param {IntegrationCheckResponse} response
+ * @param {{noPackage?: boolean}} [context] as {@link strictIssues} takes it
+ * @returns {Omit<IntegrationCheckResult, 'check' | 'response'>}
+ */
+export function summarizeCheck(response: IntegrationCheckResponse, context?: {
+    noPackage?: boolean;
+}): Omit<IntegrationCheckResult, "check" | "response">;
+/**
+ * Run every `doctor integration` check against the integration package in
+ * `cwd`, as its own build does, and return the `integration.check` envelope.
+ *
+ * @param {IntegrationCheckOptions} [options]
+ * @returns {Promise<IntegrationCheckCommandResponse>}
+ */
+export function integrationCheck(options?: IntegrationCheckOptions): Promise<IntegrationCheckCommandResponse>;
+/**
+ * Count the four checks' results into one summary. Each check's own row
+ * counts as its subcommand exits; the totals and `failures` count validate's
+ * issues once, though the other checks repeat them, and every other finding
+ * on its own, so two findings with one message stay two.
+ * @param {IntegrationCheckResponse[]} responses validate first
+ * @param {boolean} strict
+ */
+export function combineChecks(responses: IntegrationCheckResponse[], strict: boolean): {
+    checks: import("../integration-check.type.mjs").IntegrationCheckResult[];
+    errors: number;
+    warnings: number;
+    skipped: string[];
+    unchecked: number;
+    failures: import("../integration-check.type.mjs").IntegrationCheckFailure[];
+    failed: boolean;
+};
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckName} IntegrationCheckName */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckReport} IntegrationCheckReport */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckResponse} IntegrationCheckResponse */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckResult} IntegrationCheckResult */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckOptions} IntegrationCheckOptions */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckCommandResponse} IntegrationCheckCommandResponse */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckFailure} IntegrationCheckFailure */
+/** The checks `integration check` runs, in the order it runs them. */
+export const INTEGRATION_CHECKS: readonly ["validate", "components", "templates", "docs"];
+/** The skipped-work line for a package with no integration manifest. */
+export const NO_MANIFEST_SKIP: "No astryx.integration.* found next to package.json, so nothing was checked.";
+export namespace CONFLICT_CODES {
+    let components: "component_name_conflict";
+    let templates: "template_id_conflict";
+}
+/** The code a check with no integration manifest carries under `--strict`. */
+export const NO_MANIFEST_CODE: "missing_manifest";
+export type IntegrationCheckName = import("../integration-check.type.mjs").IntegrationCheckName;
+export type IntegrationCheckReport = import("../integration-check.type.mjs").IntegrationCheckReport;
+export type IntegrationCheckResponse = import("../integration-check.type.mjs").IntegrationCheckResponse;
+export type IntegrationCheckResult = import("../integration-check.type.mjs").IntegrationCheckResult;
+export type IntegrationCheckOptions = import("../integration-check.type.mjs").IntegrationCheckOptions;
+export type IntegrationCheckCommandResponse = import("../integration-check.type.mjs").IntegrationCheckCommandResponse;
+export type IntegrationCheckFailure = import("../integration-check.type.mjs").IntegrationCheckFailure;

package/api/integration/check/check.mjs

@@ -0,0 +1,357 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx integration check`: every `doctor integration` check in one
+ * call, for a package's own build.
+ *
+ * Runs `validate`, `components`, `templates` and `docs` against the
+ * integration package in `cwd` and counts each result the way that check's
+ * own subcommand exits, so the
+ * run fails exactly when one of them would. With `strict` it also fails on
+ * any warning and on any check, or comparison a check carries, that did not
+ * run, so a package can gate its build on its docs staying in sync. `--strict`
+ * adds no check: it reports the same warnings and skipped work again, as
+ * errors in the checks' own issue format, and fails on them.
+ *
+ * What fails it is a contract for the builds that run it: a new check, or a
+ * new failure code, joins only in a minor release that names it.
+ * `test/integration-check-failures.test.mjs` lists each one, so adding one
+ * shows up in review.
+ *
+ * @input A local or installed integration package.
+ * @output Each check's own envelope with its errors, warnings and skipped
+ *   work, the totals, and whether the run fails.
+ * @position Backs `astryx integration check`.
+ */
+
+import {
+  integrationComponentConflicts,
+  integrationDocConflicts,
+  integrationTemplateConflicts,
+} from '../authoring-checks.mjs';
+import {
+  summarizeIssues,
+  validateIntegration,
+} from '../validate-integration.mjs';
+
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckName} IntegrationCheckName */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckReport} IntegrationCheckReport */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckResponse} IntegrationCheckResponse */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckResult} IntegrationCheckResult */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckOptions} IntegrationCheckOptions */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckCommandResponse} IntegrationCheckCommandResponse */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckFailure} IntegrationCheckFailure */
+
+/** The checks `integration check` runs, in the order it runs them. */
+export const INTEGRATION_CHECKS = /** @type {const} */ ([
+  'validate',
+  'components',
+  'templates',
+  'docs',
+]);
+
+/** The skipped-work line for a package with no integration manifest. */
+export const NO_MANIFEST_SKIP =
+  'No astryx.integration.* found next to package.json, so nothing was checked.';
+
+/**
+ * The code a conflict carries when `--strict` reports it: conflicts have no
+ * code of their own.
+ */
+export const CONFLICT_CODES = /** @type {const} */ ({
+  components: 'component_name_conflict',
+  templates: 'template_id_conflict',
+});
+
+/** The code a check with no integration manifest carries under `--strict`. */
+export const NO_MANIFEST_CODE = 'missing_manifest';
+
+/**
+ * The code a skipped comparison carries under `--strict`: its key in the
+ * check's result, in snake case, then `_skipped` (`propDrift` is
+ * `prop_drift_skipped`).
+ * @param {string} key
+ */
+export function skippedCode(key) {
+  return `${key.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()}_skipped`;
+}
+
+/** Each check's envelope type, by check. */
+const CHECK_OF_TYPE = /** @type {const} */ ({
+  'integration.validate': 'validate',
+  'integration.component-conflicts': 'components',
+  'integration.template-conflicts': 'templates',
+  'integration.doc-conflicts': 'docs',
+});
+
+/**
+ * Whether a value is a report a check carries beside its issues: a
+ * comparison with a `status` of `checked` or `skipped` and its `findings`.
+ * @param {unknown} value
+ * @returns {value is IntegrationCheckReport}
+ */
+export function isCheckReport(value) {
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const report = /** @type {{status?: unknown, findings?: unknown}} */ (value);
+  return (
+    (report.status === 'checked' || report.status === 'skipped') &&
+    Array.isArray(report.findings)
+  );
+}
+
+/**
+ * One finding as an issue: its own code, message, fix, file, and line where
+ * it has them.
+ * @param {any} finding
+ * @param {string} code
+ * @returns {Omit<IntegrationCheckFailure, 'check' | 'severity'>}
+ */
+function asIssue(finding, code) {
+  const file = finding.file ?? finding.doc ?? finding.source;
+  return {
+    code,
+    message: String(finding.message ?? ''),
+    ...(typeof finding.component === 'string'
+      ? {component: finding.component}
+      : {}),
+    ...(typeof finding.prop === 'string' ? {prop: finding.prop} : {}),
+    ...(typeof finding.fix === 'string' ? {fix: finding.fix} : {}),
+    ...(typeof file === 'string' ? {file} : {}),
+    ...(typeof finding.line === 'number' ? {line: finding.line} : {}),
+  };
+}
+
+/**
+ * Every warning in one check's result, and every piece of work it skipped,
+ * as issues: what `--strict` reports as errors. The counts come from the
+ * same list, so the default run and the strict run read the same data.
+ * @param {IntegrationCheckName} check
+ * @param {IntegrationCheckResponse} response
+ * @param {{noPackage?: boolean}} [context] `noPackage`: validate found no
+ *   package.json, which only it reports; then no other check names a
+ *   missing manifest as skipped work
+ * @returns {{warnings: Array<Omit<IntegrationCheckFailure, 'check' | 'severity'>>, skipped: Array<Omit<IntegrationCheckFailure, 'check' | 'severity'>>}}
+ */
+export function strictIssues(check, response, context = {}) {
+  const data =
+    /** @type {Record<string, unknown> & IntegrationCheckResponse['data']} */ (
+      response.data
+    );
+  const warnings = [];
+  for (const issue of data.issues) {
+    if (issue.severity === 'warning') {
+      warnings.push(asIssue(issue, issue.code));
+    }
+  }
+  const conflictCode = /** @type {Record<string, string>} */ (CONFLICT_CODES)[
+    check
+  ];
+  for (const conflict of /** @type {any[]} */ (
+    Array.isArray(data.conflicts) ? data.conflicts : []
+  )) {
+    if (conflict.severity === 'warning' && conflictCode) {
+      warnings.push(asIssue(conflict, conflictCode));
+    }
+  }
+  for (const finding of /** @type {any[]} */ (
+    Array.isArray(data.findings) ? data.findings : []
+  )) {
+    if (finding.severity === 'warning') {
+      warnings.push(asIssue(finding, finding.code ?? finding.relationship));
+    }
+  }
+  const skipped = [];
+  const noPackage =
+    context.noPackage === true ||
+    data.issues.some(issue => issue.code === 'no_package');
+  if (!data.validated && !noPackage) {
+    skipped.push({code: NO_MANIFEST_CODE, message: NO_MANIFEST_SKIP});
+  }
+  for (const [key, value] of Object.entries(data)) {
+    if (!isCheckReport(value)) continue;
+    if (value.status === 'skipped') {
+      skipped.push({
+        code: skippedCode(key),
+        message: value.reason ?? `${key} did not run`,
+      });
+      continue;
+    }
+    for (const finding of /** @type {any[]} */ (value.findings)) {
+      if ((finding.severity ?? 'warning') !== 'warning') continue;
+      warnings.push(
+        asIssue(finding, finding.code ?? finding.problem ?? finding.kind),
+      );
+    }
+    // A comparison that ran but judged no prop type (a TypeScript older than
+    // the type comparison reads) skipped that work.
+    const typesSkipped = /** @type {{typesSkipped?: unknown}} */ (value)
+      .typesSkipped;
+    if (typeof typesSkipped === 'string') {
+      skipped.push({
+        code: 'prop_types_skipped',
+        message: `prop types not judged: ${typesSkipped}`,
+      });
+    }
+  }
+  return {warnings, skipped};
+}
+
+/**
+ * Count one check's result the way its own subcommand exits. Errors are what
+ * make it exit 1: error-severity issues, and for `docs` error findings.
+ * Warnings are warning issues, conflicts and findings, and the findings of
+ * any report the check carries. Skipped names work that did not run: no
+ * integration manifest, or a report that was skipped.
+ * @param {IntegrationCheckResponse} response
+ * @param {{noPackage?: boolean}} [context] as {@link strictIssues} takes it
+ * @returns {Omit<IntegrationCheckResult, 'check' | 'response'>}
+ */
+export function summarizeCheck(response, context = {}) {
+  const check = /** @type {IntegrationCheckName} */ (
+    CHECK_OF_TYPE[response.type]
+  );
+  let errors = summarizeIssues(response.data.issues).errors;
+  // The docs check is the one whose findings fail it.
+  if (response.type === 'integration.doc-conflicts') {
+    errors += response.data.findings.filter(
+      finding => finding.severity === 'error',
+    ).length;
+  }
+  const {warnings, skipped} = strictIssues(check, response, context);
+  return {
+    errors,
+    warnings: warnings.length,
+    skipped: skipped.map(each => each.message),
+    failed: errors > 0,
+  };
+}
+
+/**
+ * Run every `doctor integration` check against the integration package in
+ * `cwd`, as its own build does, and return the `integration.check` envelope.
+ *
+ * @param {IntegrationCheckOptions} [options]
+ * @returns {Promise<IntegrationCheckCommandResponse>}
+ */
+export async function integrationCheck(options = {}) {
+  const {cwd = process.cwd(), strict = false} = options;
+  // One after another: each loads the package through the same discovery.
+  /** @type {IntegrationCheckResponse[]} */
+  const responses = [];
+  responses.push(await validateIntegration(undefined, {cwd}));
+  responses.push(await integrationComponentConflicts(undefined, {cwd}));
+  responses.push(await integrationTemplateConflicts(undefined, {cwd}));
+  responses.push(await integrationDocConflicts(undefined, {cwd}));
+
+  const [validation] = responses;
+  return {
+    type: 'integration.check',
+    data: {
+      validated: validation.data.validated,
+      name: validation.data.name,
+      version: validation.data.version,
+      strict,
+      ...combineChecks(responses, strict),
+    },
+  };
+}
+
+/**
+ * Count the four checks' results into one summary. Each check's own row
+ * counts as its subcommand exits; the totals and `failures` count validate's
+ * issues once, though the other checks repeat them, and every other finding
+ * on its own, so two findings with one message stay two.
+ * @param {IntegrationCheckResponse[]} responses validate first
+ * @param {boolean} strict
+ */
+export function combineChecks(responses, strict) {
+  const [validation] = responses;
+  // Only validate reports a missing package.json; the other checks read it
+  // from there instead of each naming a missing manifest.
+  const noPackage = validation.data.issues.some(
+    issue => issue.code === 'no_package',
+  );
+  /** @type {IntegrationCheckResult[]} */
+  const checks = responses.map(response => ({
+    check: /** @type {IntegrationCheckName} */ (CHECK_OF_TYPE[response.type]),
+    ...summarizeCheck(response, {noPackage}),
+    response,
+  }));
+  // Later checks repeat validate's issues and its missing manifest: each
+  // match is consumed once per check, as from a multiset. Every other issue
+  // counts, even a repeat within one check.
+  const keyOf = (/** @type {string} */ kind, /** @type {object} */ issue) =>
+    `${kind}\0${JSON.stringify(issue)}`;
+  const validateFound = strictIssues('validate', validation, {noPackage});
+  /** @type {Map<string, number>} */
+  const fromValidate = new Map();
+  for (const key of [
+    ...validation.data.issues
+      .filter(issue => issue.severity === 'error')
+      .map(issue => keyOf('error', asIssue(issue, issue.code))),
+    ...validateFound.warnings.map(issue => keyOf('warning', issue)),
+    ...validateFound.skipped.map(issue => keyOf('skipped', issue)),
+  ]) {
+    fromValidate.set(key, (fromValidate.get(key) ?? 0) + 1);
+  }
+
+  let errors = 0;
+  let warnings = 0;
+  let unchecked = 0;
+  /** @type {string[]} */
+  const skipped = [];
+  // `--strict` adds no check: it reports the same warnings and skipped work
+  // as errors, and they fail the run.
+  /** @type {IntegrationCheckFailure[]} */
+  const failures = [];
+  checks.forEach(({check, response}, index) => {
+    /** @type {Map<string, number>} */
+    const repeats = index === 0 ? new Map() : new Map(fromValidate);
+    const isRepeat = (/** @type {string} */ key) => {
+      const left = repeats.get(key) ?? 0;
+      if (left === 0) return false;
+      repeats.set(key, left - 1);
+      return true;
+    };
+    for (const issue of response.data.issues) {
+      if (
+        issue.severity === 'error' &&
+        !isRepeat(keyOf('error', asIssue(issue, issue.code)))
+      ) {
+        errors++;
+      }
+    }
+    if (response.type === 'integration.doc-conflicts') {
+      errors += response.data.findings.filter(
+        finding => finding.severity === 'error',
+      ).length;
+    }
+    for (const value of Object.values(response.data)) {
+      const list = /** @type {{unchecked?: unknown}} */ (value)?.unchecked;
+      if (isCheckReport(value) && Array.isArray(list)) unchecked += list.length;
+    }
+    const found =
+      index === 0 ? validateFound : strictIssues(check, response, {noPackage});
+    for (const issue of found.warnings) {
+      if (isRepeat(keyOf('warning', issue))) continue;
+      warnings++;
+      if (strict) failures.push({check, severity: 'error', ...issue});
+    }
+    for (const issue of found.skipped) {
+      if (isRepeat(keyOf('skipped', issue))) continue;
+      skipped.push(`${check}: ${issue.message}`);
+      if (strict) failures.push({check, severity: 'error', ...issue});
+    }
+  });
+  return {
+    checks,
+    errors,
+    warnings,
+    skipped,
+    unchecked,
+    failures,
+    failed: checks.some(check => check.failed) || failures.length > 0,
+  };
+}