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

package/clients/cli/commands/init.mjs

@@ -3,8 +3,8 @@
 /**
  * @file init command — thin wrapper around the init API.
  *
- * `astryx init` is non-interactive by default: it installs the AGENTS.md/
- * CLAUDE.md cheat sheet with NO prompts, so it behaves identically for humans,
+ * `astryx init` is non-interactive by default: it installs the agent-docs
+ * cheat sheet with NO prompts, so it behaves identically for humans,
  * AI agents, CI, and piped I/O — it never hangs or errors on a missing TTY.
  * Non-interactive feature install: `astryx init --features agents,theme,template`
  * Re-runnable: safe to run multiple times, idempotent.

package/clients/cli/commands/integration-add.doc.mjs

@@ -113,6 +113,7 @@ export const doc = {
       cli: 'astryx integration add theme ocean --from neutral',
     },
   ],
+  outsideProject: 'refuse',
   exitCodes: [
     {code: 0, when: 'the contribution is written or the dry run succeeds'},
     {
@@ -121,4 +122,10 @@ export const doc = {
     },
   ],
   related: ['integration verify', 'doctor integration validate', 'theme add'],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a package, integration add writes nothing and stops with `ERR_FILE_NOT_FOUND`: \"No package.json found. Run this command inside an integration package.\" In a project, the project's version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:global-integrations}.",
+    },
+  ],
 };

package/clients/cli/commands/integration-authoring.test.mjs

@@ -147,6 +147,52 @@ describe('integration authoring CLI', () => {
     );
   });
 
+  it("verify carries each issue's fix, file, and line in JSON and prints them in text", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'docs'],
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {docs: './docs'};\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, 'docs'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'deploying.doc.mjs'),
+      "export const docs = {type: 'generic', name: 'deploying', title: 'Deploying', description: 'How to deploy.', sections: [{title: 'Overview', content: [{type: 'prose', text: 'Ship it.'}]}]};\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'ghost.doc.zh.mjs'),
+      "export default {title: 'ghost'};\n",
+    );
+
+    const json = parseEnvelope(
+      (await runCli(['integration', 'verify', '--json'], tmpDir)).stdout,
+    );
+    const orphans = json.data.issues.filter(issue =>
+      issue.code.endsWith('orphan_doc_overlay'),
+    );
+    expect(orphans.map(issue => issue.code).sort()).toEqual([
+      'orphan_doc_overlay',
+      'packed_orphan_doc_overlay',
+    ]);
+    for (const issue of orphans) {
+      expect(issue).toMatchObject({
+        file: 'docs/ghost.doc.zh.mjs',
+        line: 1,
+        fix: expect.stringContaining('Delete docs/ghost.doc.zh.mjs'),
+      });
+    }
+
+    const text = (await runCli(['integration', 'verify'], tmpDir)).stdout;
+    expect(text).toContain('file: docs/ghost.doc.zh.mjs:1');
+    expect(text).toContain(`fix: ${orphans[0].fix}`);
+  });
+
   it('keeps `integration pack --check` as a deprecated alias of `integration verify`', async () => {
     // The old spelling runs the same check: the same JSON, the same exit code.
     const verify = await runCli(['integration', 'verify', '--json'], tmpDir);
@@ -173,7 +219,7 @@ describe('integration authoring CLI', () => {
     expect(text.status).toBe(verifyText.status);
     expect(text.stdout).toBe(verifyText.stdout);
     expect(text.stderr).toContain('`integration pack --check` is deprecated');
-    expect(text.stderr).toContain('astryx integration verify');
+    expect(text.stderr).toContain(' integration verify`');
     // Without --check it fails, as it did, and points only at the new name:
     // suggesting `--check` would send people to the deprecated spelling.
     const bare = await runCli(['integration', 'pack'], tmpDir);
@@ -181,13 +227,13 @@ describe('integration authoring CLI', () => {
     expect(bare.stderr).toContain(
       '`integration pack` is now `integration verify`',
     );
-    expect(bare.stderr).toContain('astryx integration verify');
+    expect(bare.stderr).toContain(' integration verify`');
     expect(bare.stderr).toContain('npm pack');
     expect(bare.stderr).not.toContain('--check');
     const bareJson = await runCli(['--json', 'integration', 'pack'], tmpDir);
     expect(parseEnvelope(bareJson.stdout)).toMatchObject({
       code: 'ERR_INVALID_ARGUMENT',
-      error: expect.stringContaining('astryx integration verify'),
+      error: expect.stringContaining(' integration verify`'),
     });
     // Help lists it, marked deprecated: nothing is hidden.
     const help = await runCli(['integration', '--help'], tmpDir);

package/clients/cli/commands/integration-check.doc.mjs

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandDoc for `astryx integration check`.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'integration check',
+  displayName: 'astryx integration check',
+  namespace: 'cli/commands',
+  summary:
+    "The CI check for an integration package's own build: every source check, run in continuous integration or a typecheck script, against the package in the current folder",
+  description:
+    'Takes no package argument: it runs the four `doctor integration` checks, ' +
+    '`validate`, `components`, `templates`, and `docs`, against the integration ' +
+    'package in the current folder, which is where its own build runs it. It prints ' +
+    'each result as that check ' +
+    'prints it, then a summary with the errors, warnings, and skipped work of each, ' +
+    'and exits 1 when any of the four would exit 1 on its own. With `--strict` it ' +
+    'also exits 1 on any warning and on any check, or comparison within a check, ' +
+    'that did not run, such as a package with no `astryx.integration.*` or a ' +
+    'comparison skipped because the project has no TypeScript, or prop types not ' +
+    'judged because its TypeScript is older than 4.8: it adds no check, ' +
+    'and lists each of those again as an error, after the checks, in their own ' +
+    'issue format. That is the line ' +
+    "for the package's own build, so its docs, types, and links stay in sync: run " +
+    'it as a `ci` step, or add ' +
+    '`"typecheck": "tsc --noEmit && astryx integration check --strict"` to the ' +
+    'scripts in package.json. Its exit codes and JSON are 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 in the release notes. A patch can still ship a Core component, ' +
+    'template, or CLI topic whose name conflicts with one of yours. Run ' +
+    '`integration check` on every build; run ' +
+    '`integration verify` before you publish, to check that the packed package ' +
+    'works in an app. To check an installed integration by name, run the ' +
+    '`doctor integration` subcommands with its package name. Outside a package, ' +
+    'it writes nothing, `validate` reports one `no_package` issue, and it exits 1.',
+  fn: 'integrationCheck',
+  options: [
+    {
+      flag: '--strict',
+      param: 'options.strict',
+      description:
+        'Also exit 1 on any warning and on any check that did not run. A new check or failure code joins only in a minor release, named in the release notes; until then, a malformed `cliCommand` is reported as a note (`invalid_cli_command`) that fails nothing.',
+    },
+  ],
+  examples: [
+    {
+      label:
+        'In CI, as the typecheck script: add "typecheck": "tsc --noEmit && astryx integration check --strict" to package.json',
+      cli: 'integration check --strict',
+    },
+    {
+      label: 'Errors only, while you fix the warnings a package already has',
+      cli: 'integration check',
+    },
+    {
+      label: 'Read the result as JSON',
+      cli: 'integration check --strict --json',
+    },
+    {
+      label:
+        'Before you publish: check that the packed package works in an app',
+      cli: 'integration verify',
+    },
+  ],
+  outsideProject: 'own',
+  exitCodes: [
+    {
+      code: 0,
+      when: 'no check fails on its own; with --strict, also no warning, and every check ran',
+    },
+    {
+      code: 1,
+      when: 'a check fails on its own (an error); with --strict, also any warning, or a check that did not run',
+    },
+  ],
+  related: [
+    'integration verify',
+    'doctor integration validate',
+    'doctor integration components',
+    'doctor integration templates',
+    'doctor integration docs',
+  ],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a package, it writes nothing, its `validate` check reports one `no_package` issue, and it exits 1. In a project, the project's version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:global-integrations}.",
+    },
+  ],
+};

package/clients/cli/commands/integration-check.test.mjs

@@ -0,0 +1,489 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx integration check`: every source check in one command, the
+ * summary, exit codes with and without `--strict`, and the `--strict`
+ * failures, in text and JSON alike.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {discoverCoreTemplates} from '../../../foundation/discovery/template-adapter.mjs';
+
+/** @type {string} */
+let tmpDir;
+
+beforeEach(() => {
+  // Under the repository, so the components check resolves Core.
+  tmpDir = fs.mkdtempSync(
+    path.join(process.cwd(), '.astryx-integration-check-cli-'),
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * A package whose one page template takes a Core template's id: one warning
+ * (`templates` conflict). The doc matches TemplateDoc, so no other check
+ * warns about it.
+ * @param {{id: string, replaces?: string, extraManifest?: string, dir?: string}} options
+ */
+function writePackage({id, replaces, extraManifest = '', dir = tmpDir}) {
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+  );
+  fs.writeFileSync(
+    path.join(dir, 'astryx.integration.mjs'),
+    `export default {templates: './templates'${extraManifest}};\n`,
+  );
+  fs.mkdirSync(path.join(dir, 'templates'), {recursive: true});
+  fs.writeFileSync(
+    path.join(dir, 'templates', `${id}.doc.mjs`),
+    `export default {type: 'page', name: 'Integration template', displayName: 'Integration template', description: 'fixture'${replaces == null ? '' : `, replaces: ${JSON.stringify(replaces)}`}};\n`,
+  );
+  fs.writeFileSync(
+    path.join(dir, 'templates', `${id}.tsx`),
+    'export default function Fixture() { return null; }\n',
+  );
+}
+
+async function coreTemplateId() {
+  const core = (await discoverCoreTemplates()).find(
+    template => template.type === 'page',
+  );
+  expect(core).toBeDefined();
+  return /** @type {{dirName: string}} */ (core).dirName;
+}
+
+describe('astryx integration check', () => {
+  it('runs validate, components, templates, and docs in order, then a summary, and exits 0 on a warning', async () => {
+    writePackage({id: await coreTemplateId()});
+
+    const run = await runCli(['integration', 'check'], tmpDir);
+
+    const order = [
+      'Validating integration: @acme/widgets@1.2.3',
+      'Checking integration components: @acme/widgets@1.2.3',
+      'Checking integration templates: @acme/widgets@1.2.3',
+      'Checking integration docs: @acme/widgets@1.2.3',
+      'Integration check: @acme/widgets@1.2.3',
+    ].map(line => run.stdout.indexOf(line));
+    expect(order.every(index => index >= 0)).toBe(true);
+    expect([...order].sort((a, b) => a - b)).toEqual(order);
+    expect(run.stdout).toContain('Consider renaming');
+    expect(run.stdout).not.toContain('Failing under --strict');
+    expect(run.stdout).toContain(
+      '[ok] 0 errors, 1 warning, 0 skipped. No check failed;',
+    );
+    // Each check's output stands apart from the next.
+    const lines = run.stdout.split('\n');
+    for (const header of [
+      'Checking integration components:',
+      'Checking integration templates:',
+      'Checking integration docs:',
+    ]) {
+      expect(lines[lines.findIndex(line => line.includes(header)) - 1]).toBe(
+        '',
+      );
+    }
+    expect(run.status).toBe(0);
+  });
+
+  it('--strict lists the warning again as an error, after the checks, and exits 1', async () => {
+    const id = await coreTemplateId();
+    writePackage({id});
+
+    const run = await runCli(['integration', 'check', '--strict'], tmpDir);
+
+    expect(run.stdout).toContain(
+      'Integration check: @acme/widgets@1.2.3 (strict)',
+    );
+    const block = run.stdout.indexOf('Failing under --strict');
+    expect(block).toBeGreaterThan(
+      run.stdout.indexOf('Checking integration docs:'),
+    );
+    expect(run.stdout.slice(block)).toMatch(
+      /severity: \[fail\]\ncheck: +templates\ncode: +template_id_conflict\n/,
+    );
+    expect(run.stdout).toContain(
+      '[fail] 0 errors, 1 warning, 0 skipped. --strict fails on every warning and on skipped work;',
+    );
+    expect(run.status).toBe(1);
+  });
+
+  it('--strict prints each finding once: its message above, its code in the failing list', async () => {
+    const id = await coreTemplateId();
+    writePackage({id});
+
+    const run = await runCli(['integration', 'check', '--strict'], tmpDir);
+    const json = await runCli(
+      ['integration', 'check', '--strict', '--json'],
+      tmpDir,
+    );
+    const [failure] = JSON.parse(json.stdout.trim()).data.failures;
+
+    expect(run.stdout.split(failure.message).length - 1).toBe(1);
+    expect(
+      run.stdout.slice(run.stdout.indexOf('Failing under --strict')),
+    ).toContain('template_id_conflict');
+  });
+
+  it('--json carries each check with its own envelope, the --strict failures, and exits as the text does', async () => {
+    const id = await coreTemplateId();
+    writePackage({id});
+
+    const run = await runCli(
+      ['integration', 'check', '--strict', '--json'],
+      tmpDir,
+    );
+
+    const parsed = JSON.parse(run.stdout.trim());
+    expect(parsed.type).toBe('integration.check');
+    expect(parsed.data).toMatchObject({
+      validated: true,
+      name: '@acme/widgets',
+      version: '1.2.3',
+      strict: true,
+      errors: 0,
+      warnings: 1,
+      skipped: [],
+      failed: true,
+    });
+    expect(parsed.data.checks.map(check => check.check)).toEqual([
+      'validate',
+      'components',
+      'templates',
+      'docs',
+    ]);
+    const templates = parsed.data.checks[2];
+    expect(templates).toMatchObject({
+      check: 'templates',
+      errors: 0,
+      warnings: 1,
+      skipped: [],
+      failed: false,
+      response: {
+        type: 'integration.template-conflicts',
+        data: {conflicts: [expect.objectContaining({id, severity: 'warning'})]},
+      },
+    });
+    expect(parsed.data.failures).toEqual([
+      {
+        check: 'templates',
+        severity: 'error',
+        code: 'template_id_conflict',
+        message: templates.response.data.conflicts[0].message,
+      },
+    ]);
+    expect(run.status).toBe(1);
+  });
+
+  it('exits 1 without --strict when one check fails on its own, and lists no failures', async () => {
+    writePackage({id: 'acme-app-shell', replaces: 'missing-core-shell'});
+
+    const text = await runCli(['integration', 'check'], tmpDir);
+    const json = await runCli(['integration', 'check', '--json'], tmpDir);
+
+    expect(text.stdout).toContain('missing_template_replacement_target');
+    expect(text.stdout).toMatch(
+      /\[fail\] [1-9]\d* errors?, .*Address the items marked \[fail\] above\./,
+    );
+    expect(text.stdout).not.toContain('Failing under --strict');
+    expect(JSON.parse(json.stdout.trim()).data).toMatchObject({
+      strict: false,
+      failures: [],
+      failed: true,
+    });
+    expect(text.status).toBe(1);
+    expect(json.status).toBe(1);
+  });
+
+  it('counts a package with no manifest as skipped work: exit 0, and 1 with --strict', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/plain', version: '1.0.0'}),
+    );
+
+    const loose = await runCli(['integration', 'check'], tmpDir);
+    expect(loose.stdout).toContain(
+      "Nothing was checked: no astryx.integration.* found next to package.json. Run this command in an integration package's folder.",
+    );
+    // One cause, however many checks it stops: counted once.
+    expect(loose.stdout).toContain('[ok] 0 errors, 0 warnings, 1 skipped.');
+    expect(loose.status).toBe(0);
+
+    const strict = await runCli(
+      ['integration', 'check', '--strict', '--json'],
+      tmpDir,
+    );
+    const {data} = JSON.parse(strict.stdout.trim());
+    expect(data).toMatchObject({validated: false, errors: 0, failed: true});
+    // One cause, however many checks it stops: listed once.
+    expect(data.failures).toEqual([
+      {
+        check: 'validate',
+        severity: 'error',
+        code: 'missing_manifest',
+        message:
+          'No astryx.integration.* found next to package.json, so nothing was checked.',
+      },
+    ]);
+    expect(strict.status).toBe(1);
+  });
+
+  it('exits 1 for no package.json, as validate does', async () => {
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-no-pkg-'));
+    try {
+      const run = await runCli(['integration', 'check'], empty);
+      expect(run.stdout).toContain(
+        'Nothing was checked: no package.json found.',
+      );
+      expect(run.stdout).toContain('Integration check: (no package.json)');
+      expect(run.stdout).toContain(
+        '[fail] 1 error, 0 warnings, 0 skipped. No package.json was found here, so nothing was checked.',
+      );
+      expect(run.stdout).not.toContain('marked [fail] above');
+      expect(run.status).toBe(1);
+    } finally {
+      fs.rmSync(empty, {recursive: true, force: true});
+    }
+  });
+
+  it('states in its help that it is the CI check, the line to add, and what --strict promises', async () => {
+    const run = await runCli(['integration', 'check', '--help'], tmpDir);
+
+    expect(run.stdout).toContain(
+      "The CI check for an integration package's own build",
+    );
+    expect(run.stdout).toContain(
+      '"typecheck": "tsc --noEmit && astryx integration check --strict"',
+    );
+    expect(run.stdout).toContain(
+      'A new check or failure code joins only in a minor release, named in the release notes; until then, a malformed `cliCommand` is reported as a note (`invalid_cli_command`) that fails nothing.',
+    );
+    expect(run.stdout).toContain('integration verify');
+    expect(run.stdout).toContain('against the package in the current folder');
+    expect(run.stdout).not.toContain('[package]');
+  });
+
+  it('reports a malformed cliCommand as a note beside the issues, which --strict does not fail', async () => {
+    // A unique template id, so nothing else warns.
+    writePackage({
+      id: 'acme-notes-only-fixture',
+      extraManifest: ", cliCommand: ' acme astryx\\n'",
+    });
+
+    const json = await runCli(
+      ['--json', 'integration', 'check', '--strict'],
+      tmpDir,
+    );
+    const envelope = JSON.parse(json.stdout);
+    const validate = envelope.data.checks[0].response.data;
+    expect(validate.issues.map((/** @type {any} */ i) => i.code)).not.toContain(
+      'invalid_cli_command',
+    );
+    expect(validate.notes).toEqual([
+      {code: 'invalid_cli_command', message: expect.any(String)},
+    ]);
+    expect(envelope.data.failed).toBe(false);
+    expect(json.status).toBe(0);
+
+    const text = await runCli(['integration', 'check'], tmpDir);
+    expect(
+      text.stdout
+        .split('\n')
+        .filter(line => line.startsWith('note (invalid_cli_command): ')),
+    ).toHaveLength(1);
+  });
+
+  it('takes no package name: one passed is an error, not a check of the current folder', async () => {
+    writePackage({id: 'acme-page'});
+
+    const run = await runCli(['integration', 'check', '@acme/widgets'], tmpDir);
+
+    expect(run.stderr).toContain('too many arguments');
+    expect(run.stdout).not.toContain('Integration check:');
+    expect(run.status).toBe(1);
+  });
+});
+
+describe('a copied passage', () => {
+  const passage =
+    'Themes cannot style the layer that holds a menu or a popover, so a menu ' +
+    'keeps the default surface color until the next release adds a token for it.';
+
+  function writeCopiedDocs() {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      `export default {docs: './docs'};\n`,
+    );
+    fs.mkdirSync(path.join(tmpDir, 'docs'));
+    for (const name of ['acme-setup', 'acme-menus']) {
+      const doc = {
+        type: 'generic',
+        name,
+        title: 'Fixture',
+        description: 'Fixture topic.',
+        sections: [
+          {title: 'Overview', content: [{type: 'prose', text: passage}]},
+        ],
+      };
+      fs.writeFileSync(
+        path.join(tmpDir, 'docs', `${name}.doc.mjs`),
+        `export default ${JSON.stringify(doc)};\n`,
+      );
+    }
+  }
+
+  it('keeps doctor integration docs at exit 0, and fails integration check --strict', async () => {
+    writeCopiedDocs();
+
+    const doctor = await runCli(['doctor', 'integration', 'docs'], tmpDir);
+    expect(doctor.status).toBe(0);
+    expect(doctor.stdout).toContain('1 copied passage(s)');
+
+    const loose = await runCli(['integration', 'check'], tmpDir);
+    expect(loose.status).toBe(0);
+
+    const strict = await runCli(['integration', 'check', '--strict'], tmpDir);
+    expect(strict.status).toBe(1);
+    expect(strict.stdout).toContain('copied_passage');
+  });
+});
+
+describe('a padding phrase', () => {
+  it('keeps doctor integration docs at exit 0, and fails integration check --strict', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      `export default {docs: './docs'};\n`,
+    );
+    fs.mkdirSync(path.join(tmpDir, 'docs'));
+    const doc = {
+      type: 'generic',
+      name: 'acme-setup',
+      title: 'Fixture',
+      description: 'Fixture topic.',
+      sections: [
+        {
+          title: 'Overview',
+          content: [{type: 'prose', text: 'In order to start, run the setup.'}],
+        },
+      ],
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
+      `export default ${JSON.stringify(doc)};\n`,
+    );
+
+    const doctor = await runCli(['doctor', 'integration', 'docs'], tmpDir);
+    expect(doctor.status).toBe(0);
+    expect(doctor.stdout).toContain('1 fluff finding(s)');
+
+    const strict = await runCli(['integration', 'check', '--strict'], tmpDir);
+    expect(strict.status).toBe(1);
+    expect(strict.stdout).toContain('doc_fluff');
+  });
+});
+
+describe('a stray doc pointer', () => {
+  it('keeps doctor integration docs at exit 0, and fails integration check --strict', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      `export default {docs: './docs'};\n`,
+    );
+    fs.mkdirSync(path.join(tmpDir, 'docs'));
+    const doc = {
+      type: 'generic',
+      name: 'acme-setup',
+      title: 'Fixture',
+      description: 'Fixture topic.',
+      sections: [
+        {
+          title: 'Overview',
+          content: [
+            {type: 'prose', text: 'The theme is in `astryx docs theme`.'},
+          ],
+        },
+      ],
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
+      `export default ${JSON.stringify(doc)};\n`,
+    );
+
+    const doctor = await runCli(['doctor', 'integration', 'docs'], tmpDir);
+    expect(doctor.status).toBe(0);
+    expect(doctor.stdout).toContain('1 stray doc pointer(s)');
+    expect(doctor.stdout).toContain('{@link @astryxdesign/cli:generic:theme}');
+
+    const strict = await runCli(['integration', 'check', '--strict'], tmpDir);
+    expect(strict.status).toBe(1);
+    expect(strict.stdout).toContain('stray_doc_pointer');
+  });
+});
+describe('a command written with a runner', () => {
+  it('is a note in doctor integration validate, and integration check --strict still passes', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      `export default {docs: './docs'};\n`,
+    );
+    fs.mkdirSync(path.join(tmpDir, 'docs'));
+    const doc = {
+      type: 'generic',
+      name: 'acme-setup',
+      title: 'Fixture',
+      description: 'Fixture topic.',
+      sections: [
+        {
+          title: 'Overview',
+          content: [{type: 'code', lang: 'bash', code: 'npx astryx doctor'}],
+        },
+      ],
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
+      `export default ${JSON.stringify(doc)};\n`,
+    );
+
+    const doctor = await runCli(['doctor', 'integration', 'validate'], tmpDir);
+    expect(doctor.status).toBe(0);
+    expect(doctor.stdout).toContain(
+      'note (runner_command): docs/acme-setup.doc.mjs:',
+    );
+    expect(doctor.stdout).toContain('Write `astryx doctor`');
+
+    const strict = await runCli(
+      ['--json', 'integration', 'check', '--strict'],
+      tmpDir,
+    );
+    expect(strict.status).toBe(0);
+    const validate = JSON.parse(strict.stdout).data.checks.find(
+      (/** @type {any} */ each) => each.check === 'validate',
+    ).response.data;
+    expect(validate.notes.map((/** @type {any} */ note) => note.code)).toEqual([
+      'runner_command',
+    ]);
+  });
+});