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

package/api/integration/check/check.test.mjs

@@ -0,0 +1,489 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file integrationCheck(): each check counted the way its own subcommand
+ * exits, the reports a check carries, and what strict adds: the same data,
+ * reported again as errors.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {
+  integrationComponentConflicts,
+  integrationDocConflicts,
+  integrationTemplateConflicts,
+} from '../authoring-checks.mjs';
+import {
+  CONFLICT_CODES,
+  NO_MANIFEST_CODE,
+  NO_MANIFEST_SKIP,
+  combineChecks,
+  integrationCheck,
+  isCheckReport,
+  skippedCode,
+  summarizeCheck,
+} from './check.mjs';
+import {validateIntegration} from '../validate-integration.mjs';
+import {discoverCoreTemplates} from '../../../foundation/discovery/template-adapter.mjs';
+
+const IDENTITY = {validated: true, name: '@acme/widgets', version: '1.2.3'};
+
+describe('summarizeCheck', () => {
+  it('counts error and warning issues, and fails only on errors', () => {
+    expect(
+      summarizeCheck({
+        type: 'integration.validate',
+        data: {
+          ...IDENTITY,
+          issues: [
+            {code: 'missing_root', severity: 'error', message: 'm'},
+            {code: 'unknown_manifest_key', severity: 'warning', message: 'w'},
+          ],
+        },
+      }),
+    ).toEqual({errors: 1, warnings: 1, skipped: [], failed: true});
+  });
+
+  it('counts warning conflicts as warnings and ignores info', () => {
+    const conflict = (/** @type {'warning' | 'info'} */ severity) =>
+      /** @type {any} */ ({severity, id: 'x', message: 'm'});
+    expect(
+      summarizeCheck({
+        type: 'integration.template-conflicts',
+        data: {
+          ...IDENTITY,
+          issues: [],
+          conflicts: [conflict('warning'), conflict('info')],
+        },
+      }),
+    ).toEqual({errors: 0, warnings: 1, skipped: [], failed: false});
+  });
+
+  it('fails the docs check on an error finding, as its subcommand does', () => {
+    const finding = (/** @type {'error' | 'info'} */ severity) =>
+      /** @type {any} */ ({severity, topic: 't', message: 'm'});
+    expect(
+      summarizeCheck({
+        type: 'integration.doc-conflicts',
+        data: {
+          ...IDENTITY,
+          issues: [],
+          findings: [finding('error'), finding('info')],
+        },
+      }),
+    ).toEqual({errors: 1, warnings: 0, skipped: [], failed: true});
+  });
+
+  it('names a package with no manifest as skipped work, but not a missing package.json, which is an error', () => {
+    expect(
+      summarizeCheck({
+        type: 'integration.component-conflicts',
+        data: {
+          validated: false,
+          name: null,
+          version: null,
+          issues: [],
+          conflicts: [],
+        },
+      }).skipped,
+    ).toEqual([NO_MANIFEST_SKIP]);
+    expect(
+      summarizeCheck({
+        type: 'integration.validate',
+        data: {
+          validated: false,
+          name: null,
+          version: null,
+          issues: [{code: 'no_package', severity: 'error', message: 'm'}],
+        },
+      }),
+    ).toEqual({errors: 1, warnings: 0, skipped: [], failed: true});
+  });
+
+  it('counts the findings of a report a check carries as warnings, and a skipped report as skipped work', () => {
+    const data = /** @type {any} */ ({
+      ...IDENTITY,
+      issues: [],
+      conflicts: [],
+      compared: {status: 'checked', findings: [{severity: 'warning'}, {}]},
+      typed: {
+        status: 'skipped',
+        reason: 'TypeScript is not installed',
+        findings: [],
+      },
+      notAReport: {status: 'checked'},
+    });
+    expect(
+      summarizeCheck({type: 'integration.component-conflicts', data}),
+    ).toEqual({
+      errors: 0,
+      warnings: 2,
+      skipped: ['TypeScript is not installed'],
+      failed: false,
+    });
+    expect(isCheckReport(data.compared)).toBe(true);
+    expect(isCheckReport(data.notAReport)).toBe(false);
+  });
+
+  it('names prop types the comparison could not judge as skipped work, which strict fails and the default run shows', () => {
+    const reason =
+      'TypeScript 4.7.4 is older than 4.8, the oldest the type comparison reads';
+    /** @type {any[]} */
+    const responses = [
+      {
+        type: 'integration.validate',
+        data: {...IDENTITY, issues: []},
+      },
+      {
+        type: 'integration.component-conflicts',
+        data: {
+          ...IDENTITY,
+          issues: [],
+          conflicts: [],
+          propDrift: {status: 'checked', findings: [], typesSkipped: reason},
+        },
+      },
+      {
+        type: 'integration.template-conflicts',
+        data: {...IDENTITY, issues: [], conflicts: []},
+      },
+      {
+        type: 'integration.doc-conflicts',
+        data: {...IDENTITY, issues: [], findings: []},
+      },
+    ];
+    const message = `prop types not judged: ${reason}`;
+    const loose = combineChecks(responses, false);
+    expect(loose.skipped).toEqual([`components: ${message}`]);
+    expect(loose.failures).toEqual([]);
+    expect(loose.failed).toBe(false);
+    const strict = combineChecks(responses, true);
+    expect(strict.failures).toEqual([
+      {
+        check: 'components',
+        severity: 'error',
+        code: 'prop_types_skipped',
+        message,
+      },
+    ]);
+    expect(strict.failed).toBe(true);
+  });
+
+  it('names a skipped comparison by its key in snake case', () => {
+    expect(skippedCode('propDrift')).toBe('prop_drift_skipped');
+    expect(skippedCode('docTypes')).toBe('doc_types_skipped');
+  });
+});
+
+/**
+ * What the default run reports as warnings and skipped work, read from each
+ * check's own envelope: what `--strict` must report again as errors. A later
+ * check's repeat of one of validate's items is validate's, counted once.
+ * @param {any} result an `integration.check` envelope
+ */
+function warningsAndSkips(result) {
+  /** @type {Map<string, number>} */
+  const fromValidate = new Map();
+  /** @type {Array<{check: string, code: string, message: string}>} */
+  const found = [];
+  result.data.checks.forEach((/** @type {any} */ {check, response}, i) => {
+    const {data} = response;
+    /** @type {any[]} */
+    const reports = Object.values(data).filter(isCheckReport);
+    const items = [
+      ...data.issues
+        .filter((/** @type {any} */ x) => x.severity === 'warning')
+        .map((/** @type {any} */ x) => [x.code, x.message]),
+      ...(data.conflicts ?? [])
+        .filter((/** @type {any} */ x) => x.severity === 'warning')
+        .map((/** @type {any} */ x) => [CONFLICT_CODES[check], x.message]),
+      ...reports.flatMap(report =>
+        report.findings.map((/** @type {any} */ f) => [
+          f.code ?? f.problem ?? f.kind,
+          f.message,
+        ]),
+      ),
+      ...(data.validated ? [] : [[NO_MANIFEST_CODE, NO_MANIFEST_SKIP]]),
+      ...Object.entries(data)
+        .filter(([, v]) => isCheckReport(v) && v.status === 'skipped')
+        .map(([key, v]) => [skippedCode(key), v.reason]),
+      ...reports
+        .filter(report => typeof report.typesSkipped === 'string')
+        .map(report => [
+          'prop_types_skipped',
+          `prop types not judged: ${report.typesSkipped}`,
+        ]),
+    ];
+    const repeats = new Map(fromValidate);
+    for (const [code, message] of items) {
+      const key = `${code}\0${message}`;
+      const left = repeats.get(key) ?? 0;
+      if (i === 0) fromValidate.set(key, left + 1);
+      else if (left > 0) {
+        repeats.set(key, left - 1);
+        continue;
+      }
+      found.push({check, code, message});
+    }
+  });
+  return found;
+}
+
+describe('combineChecks', () => {
+  const respond = (/** @type {string} */ type, /** @type {object} */ data) =>
+    /** @type {any} */ ({
+      type,
+      data: {...IDENTITY, issues: [], conflicts: [], findings: [], ...data},
+    });
+  const sameMessage = (/** @type {string} */ component) => ({
+    component,
+    prop: 'label',
+    severity: 'warning',
+    kind: 'required_mismatch',
+    message:
+      '"label" is required in the code, but the doc does not mark it required.',
+    doc: 'components/List.doc.mjs',
+  });
+  const responses = [
+    respond('integration.validate', {
+      issues: [
+        {
+          code: 'unknown_manifest_key',
+          severity: 'warning',
+          message: 'Unknown key.',
+        },
+      ],
+    }),
+    respond('integration.component-conflicts', {
+      issues: [
+        {
+          code: 'unknown_manifest_key',
+          severity: 'warning',
+          message: 'Unknown key.',
+        },
+      ],
+      report: {
+        status: 'checked',
+        findings: [sameMessage('List'), sameMessage('ListItem')],
+        unchecked: [
+          {component: 'Ghost', doc: 'components/Ghost.doc.mjs', reason: 'x'},
+        ],
+      },
+    }),
+    respond('integration.template-conflicts', {}),
+    respond('integration.doc-conflicts', {}),
+  ];
+
+  it('counts a package-level issue once, and two findings with one message twice, naming each component', () => {
+    const loose = combineChecks(responses, false);
+    const strict = combineChecks(responses, true);
+
+    expect(loose).toMatchObject({
+      errors: 0,
+      warnings: 3,
+      unchecked: 1,
+      failed: false,
+    });
+    expect(strict.warnings).toBe(3);
+    expect(
+      strict.failures.map(f => [f.check, f.code, f.component ?? null]),
+    ).toEqual([
+      ['validate', 'unknown_manifest_key', null],
+      ['components', 'required_mismatch', 'List'],
+      ['components', 'required_mismatch', 'ListItem'],
+    ]);
+    expect(strict.failures[1]).toMatchObject({
+      prop: 'label',
+      file: 'components/List.doc.mjs',
+    });
+  });
+
+  it('counts each finding a check repeats within itself, and consumes only validate’s own issues as repeats', () => {
+    const issue = (/** @type {string} */ code, severity = 'warning') => ({
+      code,
+      severity,
+      message: code,
+    });
+    const root = issue('invalid_root', 'error');
+    const link = issue('invalid_doc_graph');
+    const broken = issue('bad_link', 'error');
+    const repeated = ['validate', 'component', 'template', 'doc'].map(kind =>
+      respond(
+        `integration.${kind === 'validate' ? kind : `${kind}-conflicts`}`,
+        {
+          issues: kind === 'doc' ? [root, link, link, broken, broken] : [root],
+        },
+      ),
+    );
+
+    const loose = combineChecks(repeated, false);
+    const strict = combineChecks(repeated, true);
+
+    expect(loose.checks.map(c => `${c.errors}/${c.warnings}`)).toEqual([
+      '1/0',
+      '1/0',
+      '1/0',
+      '3/2',
+    ]);
+    expect(loose).toMatchObject({errors: 3, warnings: 2});
+    expect(strict.failures.map(f => [f.check, f.code])).toEqual([
+      ['docs', 'invalid_doc_graph'],
+      ['docs', 'invalid_doc_graph'],
+    ]);
+  });
+
+  it('states each option’s default in its reference doc', async () => {
+    const {doc} = await import('../integrationCheck.doc.mjs');
+    const params = new Map(doc.params?.map(param => [param.name, param]));
+    expect(params.get('options.strict')?.default).toBe('false');
+    expect(params.get('options.cwd')?.default).toBe('process.cwd()');
+  });
+});
+
+describe('integrationCheck', () => {
+  /** @type {string} */
+  let pkg;
+
+  beforeEach(() => {
+    // Under the repository, so the components check resolves Core.
+    pkg = fs.mkdtempSync(
+      path.join(process.cwd(), '.astryx-integration-check-'),
+    );
+    fs.writeFileSync(
+      path.join(pkg, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+    );
+    fs.writeFileSync(
+      path.join(pkg, 'astryx.integration.mjs'),
+      "export default {templates: './templates'};\n",
+    );
+    fs.mkdirSync(path.join(pkg, 'templates'));
+    fs.writeFileSync(
+      path.join(pkg, 'templates', 'acme-page.doc.mjs'),
+      "export default {type: 'page', name: 'Acme page', displayName: 'Acme page', description: 'fixture', replaces: 'missing-core-page'};\n",
+    );
+    fs.writeFileSync(
+      path.join(pkg, 'templates', 'acme-page.tsx'),
+      'export default function Fixture() { return null; }\n',
+    );
+  });
+
+  afterEach(() => {
+    fs.rmSync(pkg, {recursive: true, force: true});
+  });
+
+  it('returns each check’s own envelope, unchanged, in the order the checks run', async () => {
+    const result = await integrationCheck({cwd: pkg});
+
+    expect(result.type).toBe('integration.check');
+    expect(result.data.checks.map(check => check.response)).toEqual([
+      await validateIntegration(undefined, {cwd: pkg}),
+      await integrationComponentConflicts(undefined, {cwd: pkg}),
+      await integrationTemplateConflicts(undefined, {cwd: pkg}),
+      await integrationDocConflicts(undefined, {cwd: pkg}),
+    ]);
+  });
+
+  it('fails when a check fails on its own, with or without strict', async () => {
+    const result = await integrationCheck({cwd: pkg});
+
+    const templates = result.data.checks.find(
+      check => check.check === 'templates',
+    );
+    expect(templates?.failed).toBe(true);
+    expect(result.data).toMatchObject({
+      validated: true,
+      strict: false,
+      failures: [],
+      failed: true,
+    });
+    expect(result.data.errors).toBeGreaterThan(0);
+  });
+
+  it('fails on warnings only with strict, which reports exactly the default run’s warnings and skipped work again, as errors', async () => {
+    const core = (await discoverCoreTemplates()).find(
+      template => template.type === 'page',
+    );
+    fs.writeFileSync(
+      path.join(pkg, 'astryx.integration.mjs'),
+      "export default {templates: './templates', unknownKey: true};\n",
+    );
+    fs.rmSync(path.join(pkg, 'templates', 'acme-page.doc.mjs'));
+    fs.renameSync(
+      path.join(pkg, 'templates', 'acme-page.tsx'),
+      path.join(pkg, 'templates', `${core?.dirName}.tsx`),
+    );
+    fs.writeFileSync(
+      path.join(pkg, 'templates', `${core?.dirName}.doc.mjs`),
+      "export default {type: 'page', name: 'Acme page', displayName: 'Acme page', description: 'fixture'};\n",
+    );
+
+    const loose = await integrationCheck({cwd: pkg});
+    const strict = await integrationCheck({cwd: pkg, strict: true});
+
+    expect(loose.data).toMatchObject({errors: 0, failures: [], failed: false});
+    // The unknown key is validate's, and every check starts from validate's
+    // issues: it counts once.
+    expect(loose.data.warnings).toBe(2);
+    expect(strict.data).toMatchObject({strict: true, errors: 0, failed: true});
+    expect(strict.data.warnings).toBe(loose.data.warnings);
+    // Same data: the same checks, read once each, in both modes.
+    expect(strict.data.checks.map(check => check.response)).toEqual(
+      loose.data.checks.map(check => check.response),
+    );
+    // Only the severity changes.
+    expect(new Set(strict.data.failures.map(f => f.severity))).toEqual(
+      new Set(['error']),
+    );
+    expect(
+      strict.data.failures.map(({check, code, message}) => ({
+        check,
+        code,
+        message,
+      })),
+    ).toEqual(warningsAndSkips(loose));
+    expect(strict.data.failures.map(f => [f.check, f.code])).toEqual([
+      ['validate', 'unknown_manifest_key'],
+      ['templates', 'template_id_conflict'],
+    ]);
+  });
+
+  it('counts a missing root once, though every check reports it', async () => {
+    fs.rmSync(path.join(pkg, 'templates'), {recursive: true, force: true});
+
+    const result = await integrationCheck({cwd: pkg});
+
+    expect(result.data.checks.map(check => check.failed)).toEqual([
+      true,
+      true,
+      true,
+      true,
+    ]);
+    expect(result.data.errors).toBe(1);
+    expect(result.data.failed).toBe(true);
+  });
+
+  it('reads a missing package.json from validate alone', async () => {
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-no-pkg-'));
+    try {
+      const result = await integrationCheck({cwd: empty, strict: true});
+
+      expect(result.data).toMatchObject({
+        errors: 1,
+        skipped: [],
+        failures: [],
+        failed: true,
+      });
+      expect(result.data.checks.map(check => check.skipped)).toEqual([
+        [],
+        [],
+        [],
+        [],
+      ]);
+    } finally {
+      fs.rmSync(empty, {recursive: true, force: true});
+    }
+  });
+});

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

@@ -0,0 +1,118 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Options for `integrationCheck()`.
+ */
+export type IntegrationCheckOptions = {
+    /**
+     * The integration package folder to check; the
+     * current directory by default.
+     */
+    cwd?: string | undefined;
+    /**
+     * Also fail on any warning and on any check that
+     * did not run, not only on errors.
+     */
+    strict?: boolean | undefined;
+};
+/**
+ * The checks `integrationCheck()` runs, in the order it runs them.
+ */
+export type IntegrationCheckName = "validate" | "components" | "templates" | "docs";
+/**
+ * The envelope one check returns on its own, unchanged.
+ */
+export type IntegrationCheckResponse = import("./validate-integration.type.mjs").ValidateIntegrationResponse | import("./authoring-checks.type.mjs").IntegrationComponentConflictResponse | import("./authoring-checks.type.mjs").IntegrationTemplateConflictResponse | import("./authoring-checks.type.mjs").IntegrationDocConflictResponse;
+/**
+ * A comparison a check carries beside its issues, such as one that needs the
+ * project's own TypeScript. `skipped` means it did not run, and `reason` says
+ * why; each of its findings is a warning.
+ */
+export type IntegrationCheckReport = {
+    status: "checked" | "skipped";
+    reason?: string | undefined;
+    findings: Array<{
+        severity?: string;
+    }>;
+};
+/**
+ * One check's result, counted the way its own subcommand exits.
+ */
+export type IntegrationCheckResult = {
+    check: IntegrationCheckName;
+    /**
+     * What makes the check's own subcommand exit 1.
+     */
+    errors: number;
+    /**
+     * Warning issues, conflicts and findings, and the
+     * findings of every report the check carries.
+     */
+    warnings: number;
+    /**
+     * Why work did not run: no integration manifest,
+     * or a report the check carries that was skipped.
+     */
+    skipped: string[];
+    /**
+     * Whether the check's own subcommand exits 1.
+     */
+    failed: boolean;
+    /**
+     * The check's own envelope.
+     */
+    response: IntegrationCheckResponse;
+};
+/**
+ * A warning, or work a check skipped, as `--strict` reports it: an error in
+ * the checks' own issue format, with the finding's own code (a conflict's is
+ * `component_name_conflict` or `template_id_conflict`, a package with no
+ * manifest's is `missing_manifest`, and a skipped comparison's is its key in
+ * snake case with `_skipped`), message, and its fix, file, and line where it
+ * has them.
+ */
+export type IntegrationCheckFailure = {
+    check: IntegrationCheckName;
+    severity: "error";
+    code: string;
+    message: string;
+    /**
+     * the component a finding is about
+     */
+    component?: string | undefined;
+    /**
+     * the prop a finding is about
+     */
+    prop?: string | undefined;
+    fix?: string | undefined;
+    file?: string | undefined;
+    line?: number | undefined;
+};
+/**
+ * `astryx --json integration check [--strict]`.
+ *
+ * `failed` decides the exit code: any check that fails on its own, and with
+ * `strict` also any warning or skipped work, which `failures` then lists as
+ * errors (it is empty without `strict`).
+ */
+export type IntegrationCheckCommandResponse = {
+    /**
+     * `unchecked` counts the items the checks list as not compared, which never
+     * fail it.
+     */
+    type: "integration.check";
+    data: {
+        validated: boolean;
+        name: string | null;
+        version: string | null;
+        strict: boolean;
+        checks: IntegrationCheckResult[];
+        errors: number;
+        warnings: number;
+        skipped: string[];
+        unchecked: number;
+        failures: IntegrationCheckFailure[];
+        failed: boolean;
+    };
+};

package/api/integration/integration-check.type.mjs

@@ -0,0 +1,84 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Typedefs for `integrationCheck()` / `astryx integration check`.
+ */
+
+/**
+ * Options for `integrationCheck()`.
+ * @typedef {object} IntegrationCheckOptions
+ * @property {string} [cwd] The integration package folder to check; the
+ *   current directory by default.
+ * @property {boolean} [strict] Also fail on any warning and on any check that
+ *   did not run, not only on errors.
+ */
+
+/**
+ * The checks `integrationCheck()` runs, in the order it runs them.
+ * @typedef {'validate' | 'components' | 'templates' | 'docs'} IntegrationCheckName
+ */
+
+/**
+ * The envelope one check returns on its own, unchanged.
+ * @typedef {import('./validate-integration.type.mjs').ValidateIntegrationResponse
+ *   | import('./authoring-checks.type.mjs').IntegrationComponentConflictResponse
+ *   | import('./authoring-checks.type.mjs').IntegrationTemplateConflictResponse
+ *   | import('./authoring-checks.type.mjs').IntegrationDocConflictResponse} IntegrationCheckResponse
+ */
+
+/**
+ * A comparison a check carries beside its issues, such as one that needs the
+ * project's own TypeScript. `skipped` means it did not run, and `reason` says
+ * why; each of its findings is a warning.
+ * @typedef {object} IntegrationCheckReport
+ * @property {'checked' | 'skipped'} status
+ * @property {string} [reason]
+ * @property {Array<{severity?: string}>} findings
+ */
+
+/**
+ * One check's result, counted the way its own subcommand exits.
+ * @typedef {object} IntegrationCheckResult
+ * @property {IntegrationCheckName} check
+ * @property {number} errors What makes the check's own subcommand exit 1.
+ * @property {number} warnings Warning issues, conflicts and findings, and the
+ *   findings of every report the check carries.
+ * @property {string[]} skipped Why work did not run: no integration manifest,
+ *   or a report the check carries that was skipped.
+ * @property {boolean} failed Whether the check's own subcommand exits 1.
+ * @property {IntegrationCheckResponse} response The check's own envelope.
+ */
+
+/**
+ * A warning, or work a check skipped, as `--strict` reports it: an error in
+ * the checks' own issue format, with the finding's own code (a conflict's is
+ * `component_name_conflict` or `template_id_conflict`, a package with no
+ * manifest's is `missing_manifest`, and a skipped comparison's is its key in
+ * snake case with `_skipped`), message, and its fix, file, and line where it
+ * has them.
+ * @typedef {object} IntegrationCheckFailure
+ * @property {IntegrationCheckName} check
+ * @property {'error'} severity
+ * @property {string} code
+ * @property {string} message
+ * @property {string} [component] the component a finding is about
+ * @property {string} [prop] the prop a finding is about
+ * @property {string} [fix]
+ * @property {string} [file]
+ * @property {number} [line]
+ */
+
+/**
+ * `astryx --json integration check [--strict]`.
+ *
+ * `failed` decides the exit code: any check that fails on its own, and with
+ * `strict` also any warning or skipped work, which `failures` then lists as
+ * errors (it is empty without `strict`).
+ * @typedef {object} IntegrationCheckCommandResponse
+ * @property {'integration.check'} type
+ * `unchecked` counts the items the checks list as not compared, which never
+ * fail it.
+ * @property {{validated: boolean, name: string | null, version: string | null, strict: boolean, checks: IntegrationCheckResult[], errors: number, warnings: number, skipped: string[], unchecked: number, failures: IntegrationCheckFailure[], failed: boolean}} data
+ */
+
+export {};

package/api/integration/integrationCheck.doc.d.mts

@@ -0,0 +1,10 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file FunctionDoc for `integrationCheck()` / `astryx integration check`.
+ * Colocated with the API function it documents; the shape source of truth stays
+ * in `integration-check.type.mjs`.
+ */
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc: import("@astryxdesign/cli/authoring").FunctionDoc;