@astryxdesign/cli 0.6.3-canary.7ada42e → 0.6.3-canary.7ec7be0

package/api/docs/list/list.mjs

@@ -8,14 +8,14 @@
  *   English `description` is read from its file; a contributed topic already
  *   carries the one discovery read. The listing never applies --dense/--zh
  *   overlays.
- * @output { type: 'docs.list', data: DocsListEntry[] } — one entry per topic in
- *   read order, each naming the package that owns it, matching
- *   `astryx --json docs`.
+ * @output { type: 'docs.list', data: DocsListEntry[] } — one entry per topic
+ *   in read order, then one per top-level docs-tree namespace, each naming the
+ *   package that owns it, matching `astryx --json docs`.
  * @position Leaf under api/docs. Sibling of detail; both share _adapter.mjs.
  */
 
 import {loadTopicFile} from '../../../foundation/doc-compiler/read.mjs';
-import {loadDocsCatalog} from '../_adapter.mjs';
+import {holdsOwnName, loadDocsCatalog, projectTree} from '../_adapter.mjs';
 
 /**
  * @param {object} [options]
@@ -24,9 +24,13 @@ import {loadDocsCatalog} from '../_adapter.mjs';
  */
 export async function list({cwd} = {}) {
   const catalog = await loadDocsCatalog(cwd);
+  const tree = await projectTree(catalog);
   /** @type {Array<import('../docs.type.mjs').DocsListEntry>} */
   const entries = [];
   for (const entry of catalog.entries()) {
+    // A topic whose name opens another doc is not listed (spec:AST-046
+    // FR11); `astryx doctor` names the clash.
+    if (!holdsOwnName(tree, catalog, entry)) continue;
     let description = entry.description ?? '';
     if (entry.description == null) {
       const file = await loadTopicFile(entry.path, null);
@@ -41,5 +45,21 @@ export async function list({cwd} = {}) {
     if (entry.replaces != null) listed.replaces = entry.replaces;
     entries.push(listed);
   }
-  return {type: 'docs.list', data: entries};
+  // The docs tree's top-level namespaces, the CLI's and each integration's,
+  // each the way into a whole branch (spec:AST-046 FR7). They go in `meta`,
+  // so `data` stays the topic list 0.6 returned: every entry reads as a topic.
+  const namespaces = tree.roots().map(root => ({
+    topic: root.route,
+    description: root.summary,
+    package: root.provider,
+  }));
+  /** @type {NonNullable<import('../docs.type.mjs').DocsListResponse['meta']>} */
+  const meta = {};
+  if (namespaces.length > 0) meta.namespaces = namespaces;
+  // A package whose docs did not load is named, so its author knows why its
+  // topics are missing.
+  if (catalog.issues.length > 0) meta.notLoaded = [...catalog.issues];
+  return Object.keys(meta).length === 0
+    ? {type: 'docs.list', data: entries}
+    : {type: 'docs.list', data: entries, meta};
 }

package/api/docs/node/node.d.mts

@@ -0,0 +1,43 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @typedef {import('../../../foundation/doc-compiler/tree.mjs').DocsTree} DocsTree
+ * @typedef {import('../../../foundation/doc-compiler/tree.mjs').TreeNode} TreeNode
+ */
+/**
+ * The docs.node view of one tree node.
+ * @param {import('../../../foundation/discovery/docs-discovery.mjs').DocsCatalog} catalog
+ * @param {DocsTree} tree
+ * @param {TreeNode} node
+ * @returns {Promise<import('../docs.type.mjs').DocsNode>}
+ */
+export function nodeView(catalog: import("../../../foundation/discovery/docs-discovery.mjs").DocsCatalog, tree: DocsTree, node: TreeNode): Promise<import("../docs.type.mjs").DocsNode>;
+/**
+ * The typed edges a doc declares (spec:AST-047 FR5), resolved to routes: a
+ * function doc's `command` and `related`, and a command doc's `fn` and
+ * `related`. A bare name resolves among the kinds its field allows; a name
+ * that matches docs of more than one allowed kind is an error, never a silent
+ * pick. A `command` resolves to the command doc its leading words name, so
+ * `integration add theme` (the `integration add` command with its kind
+ * argument) opens `integration add`. Every name that resolves to no doc, or to
+ * more than one, is returned in `unresolved`; the graph walk test fails on it,
+ * so no edge a doc declares can go stale.
+ * @param {DocsTree} tree
+ * @param {TreeNode} node
+ * @returns {{routes: string[], unresolved: string[]}}
+ */
+export function typedEdges(tree: DocsTree, node: TreeNode): {
+    routes: string[];
+    unresolved: string[];
+};
+/**
+ * @param {string} route
+ * @param {{cwd?: string}} [options]
+ * @returns {Promise<import('../docs.type.mjs').DocsNodeResponse>}
+ */
+export function node(route: string, options?: {
+    cwd?: string;
+}): Promise<import("../docs.type.mjs").DocsNodeResponse>;
+export type DocsTree = import("../../../foundation/doc-compiler/tree.mjs").DocsTree;
+export type TreeNode = import("../../../foundation/doc-compiler/tree.mjs").TreeNode;

package/api/docs/node/node.mjs

@@ -0,0 +1,192 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file docs.node leaf — one namespace or typed doc in the docs tree.
+ *
+ * @input A route the docs tree resolves: a namespace such as `cli/api`, or a
+ *   typed doc such as `cli/api/functions/search`, plus {cwd}.
+ * @output { type: 'docs.node', data: DocsNode } — the node's identity, title
+ *   and summary, the namespaces above it, and either its slots with their
+ *   children (a namespace) or its content (a typed doc). A namespace never
+ *   lists its grandchildren, so a reader goes down one level at a time.
+ *   Matches `astryx --json docs <route>`.
+ * @position Leaf under api/docs, beside the topic leaves. A guide the tree
+ *   places is a topic: the detail leaf reads it by its route.
+ */
+
+import {
+  nodeContent,
+  placeLinks,
+  resolveDocsArgument,
+  unknownTopicError,
+} from '../_adapter.mjs';
+
+/**
+ * @typedef {import('../../../foundation/doc-compiler/tree.mjs').DocsTree} DocsTree
+ * @typedef {import('../../../foundation/doc-compiler/tree.mjs').TreeNode} TreeNode
+ */
+
+/**
+ * The docs.node view of one tree node.
+ * @param {import('../../../foundation/discovery/docs-discovery.mjs').DocsCatalog} catalog
+ * @param {DocsTree} tree
+ * @param {TreeNode} node
+ * @returns {Promise<import('../docs.type.mjs').DocsNode>}
+ */
+export async function nodeView(catalog, tree, node) {
+  const {content} = await nodeContent(catalog, tree, node);
+  return {
+    id: node.id,
+    route: node.route,
+    kind: node.kind,
+    package: node.provider,
+    title: node.title,
+    summary: node.summary,
+    breadcrumb: tree
+      .ancestors(node)
+      .map(ancestor => ({route: ancestor.route, title: ancestor.title})),
+    slots: node.slots
+      .filter(slot => slot.children.length > 0)
+      .map(slot => ({
+        name: slot.name,
+        title: slot.title,
+        children: slot.children.map(route => {
+          const child = /** @type {TreeNode} */ (tree.get(route));
+          return {
+            route: child.route,
+            name: child.route.slice(child.route.lastIndexOf('/') + 1),
+            kind: child.kind,
+            title: child.title,
+            summary: child.summary,
+          };
+        }),
+      })),
+    content,
+    links: nodeLinks(tree, node),
+  };
+}
+
+/**
+ * The moves a node offers (spec:AST-047): up to the level it sits in (the
+ * topic list, for a top-level namespace), and across to the nodes before and
+ * after it in its parent's slot.
+ * @param {DocsTree} tree
+ * @param {TreeNode} node
+ * @returns {import('../docs.type.mjs').DocsLinks}
+ */
+function nodeLinks(tree, node) {
+  const links = placeLinks(tree, node);
+  const related = typedEdges(tree, node).routes;
+  if (related.length > 0) {
+    links.related = related.map(
+      route =>
+        /** @type {import('../docs.type.mjs').DocsCommand} */ (
+          `astryx docs ${route}`
+        ),
+    );
+  }
+  return links;
+}
+
+/** @type {WeakMap<DocsTree, Map<string, string>>} */
+const routeIndexes = new WeakMap();
+
+/**
+ * The route of each node, by its kind and name.
+ * @param {DocsTree} tree
+ * @returns {Map<string, string>}
+ */
+function routeIndex(tree) {
+  let routes = routeIndexes.get(tree);
+  if (!routes) {
+    routes = new Map();
+    for (const each of tree.nodes.values()) {
+      routes.set(`${each.kind}\u0000${each.name}`, each.route);
+    }
+    routeIndexes.set(tree, routes);
+  }
+  return routes;
+}
+
+/**
+ * The kinds of doc each typed field may name. A bare name in one of these
+ * fields names a doc of the same provider and one of these kinds, so it is a
+ * doc identity (spec:AST-047 FR9).
+ */
+const EDGE_KINDS = {
+  function: {command: ['command'], related: ['function']},
+  command: {fn: ['function'], related: ['command']},
+};
+
+/**
+ * The typed edges a doc declares (spec:AST-047 FR5), resolved to routes: a
+ * function doc's `command` and `related`, and a command doc's `fn` and
+ * `related`. A bare name resolves among the kinds its field allows; a name
+ * that matches docs of more than one allowed kind is an error, never a silent
+ * pick. A `command` resolves to the command doc its leading words name, so
+ * `integration add theme` (the `integration add` command with its kind
+ * argument) opens `integration add`. Every name that resolves to no doc, or to
+ * more than one, is returned in `unresolved`; the graph walk test fails on it,
+ * so no edge a doc declares can go stale.
+ * @param {DocsTree} tree
+ * @param {TreeNode} node
+ * @returns {{routes: string[], unresolved: string[]}}
+ */
+export function typedEdges(tree, node) {
+  const doc = /** @type {any} */ (node.ref)?.selfDoc;
+  /** @type {string[]} */
+  const routes = [];
+  /** @type {string[]} */
+  const unresolved = [];
+  const fields = /** @type {Record<string, string[]> | undefined} */ (
+    /** @type {any} */ (EDGE_KINDS)[node.kind]
+  );
+  if (!doc || !fields) return {routes, unresolved};
+  const index = routeIndex(tree);
+  /** @param {string[]} kinds @param {string} name */
+  const among = (kinds, name) =>
+    kinds
+      .map(kind => index.get(`${kind}\u0000${name}`))
+      .filter(route => typeof route === 'string');
+  for (const [field, kinds] of Object.entries(fields)) {
+    const value = doc[field];
+    const names = Array.isArray(value) ? value : value == null ? [] : [value];
+    for (const name of names) {
+      if (typeof name !== 'string' || name.trim() === '') continue;
+      let found = among(kinds, name);
+      if (found.length === 0 && field === 'command') {
+        const words = name.trim().split(/\s+/);
+        for (let n = words.length - 1; n > 0 && found.length === 0; n--) {
+          found = among(kinds, words.slice(0, n).join(' '));
+        }
+      }
+      if (found.length === 1) routes.push(/** @type {string} */ (found[0]));
+      else if (found.length === 0) {
+        unresolved.push(`${field} "${name}" names no ${kinds.join(' or ')} doc`);
+      } else {
+        unresolved.push(
+          `${field} "${name}" names more than one doc (${found.join(', ')})`,
+        );
+      }
+    }
+  }
+  return {
+    routes: [...new Set(routes)].filter(route => route !== node.route),
+    unresolved,
+  };
+}
+
+/**
+ * @param {string} route
+ * @param {{cwd?: string}} [options]
+ * @returns {Promise<import('../docs.type.mjs').DocsNodeResponse>}
+ */
+export async function node(route, options = {}) {
+  const found = await resolveDocsArgument(route, options);
+  if (found.kind !== 'node')
+    throw await unknownTopicError(route, found.catalog);
+  return {
+    type: 'docs.node',
+    data: await nodeView(found.catalog, found.tree, found.node),
+  };
+}

package/api/docs/reference-blocks.test.mjs

@@ -0,0 +1,406 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A topic section's `reference` block (spec:AST-047 FR9). A read
+ * includes the doc it names from that doc's own source, narrowed by its
+ * projection, and still returns only the stable block kinds. A block that
+ * cannot include what it names fails the authoring check.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {docs} from './docs.mjs';
+import {
+  builtinCatalog,
+  docsLinkProblems,
+  linkResolver,
+  loadDocsCatalog,
+  projectTree,
+} from './_adapter.mjs';
+import {integrationDocConflicts} from '../integration/authoring-checks.mjs';
+import {checkDocsTree} from '../doctor/doctor.mjs';
+import {createDocId} from '../../foundation/identity/provider-identity.mjs';
+import {CLI_PROVIDER_ID} from '../../foundation/identity/providers.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
+
+const SLOW = 60_000;
+
+/** The block kinds a read returns: a token reference and a reference block are inlined. */
+const READ_KINDS = new Set(['prose', 'heading', 'code', 'table', 'list']);
+
+/** The primary fixture: two fields of the CLI's integration manifest schema. */
+const MANIFEST_FIELDS = {
+  type: 'reference',
+  target: '@astryxdesign/cli:schema:integration',
+  projection: {fields: ['components', 'docs']},
+};
+
+/** A topic whose sections include canonical CLI docs. */
+const SETUP = {
+  type: 'generic',
+  name: 'acme-setup',
+  title: 'Acme setup',
+  description: 'Set up the Acme kit.',
+  sections: [
+    {
+      id: 'manifest',
+      title: 'Point the manifest at your folders',
+      content: [
+        {type: 'prose', text: 'Add these fields to astryx.integration.mjs.'},
+        MANIFEST_FIELDS,
+      ],
+    },
+    {
+      id: 'check',
+      title: 'Check the docs',
+      content: [
+        {type: 'prose', text: 'Run the check before you publish.'},
+        {
+          type: 'reference',
+          target: '@astryxdesign/cli:command:doctor integration docs',
+          presentation: 'compact',
+        },
+      ],
+    },
+    {
+      id: 'more',
+      title: 'Read more',
+      content: [
+        {
+          type: 'reference',
+          target: '@astryxdesign/cli:function:docs',
+          presentation: 'summary',
+        },
+        {type: 'reference', target: '@astryxdesign/cli:generic:theme'},
+      ],
+    },
+  ],
+};
+
+/** A topic whose reference blocks each name something they cannot include. */
+const BROKEN = {
+  type: 'generic',
+  name: 'acme-broken',
+  title: 'Acme broken',
+  description: 'References that include nothing.',
+  sections: [
+    {
+      id: 'gaps',
+      title: 'Gaps',
+      content: [
+        {
+          type: 'reference',
+          target: '@astryxdesign/cli:schema:integration',
+          projection: {fields: ['components', 'nope']},
+        },
+        {type: 'reference', target: '@astryxdesign/cli:schema:nothing'},
+        {
+          type: 'reference',
+          target: '@astryxdesign/cli:command:doctor',
+          projection: {fields: ['--json']},
+        },
+        {
+          type: 'reference',
+          target: '@astryxdesign/cli:schema:config',
+          projection: {sections: ['fields']},
+        },
+        {
+          type: 'reference',
+          target: '@astryxdesign/cli:generic:theme',
+          presentation: 'full',
+        },
+      ],
+    },
+  ],
+};
+
+/** @type {string} */
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-reference-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * A consumer project that configures `@acme/kit`, which ships these docs.
+ * @param {Record<string, object>} files doc file name -> doc
+ */
+function scaffold(files) {
+  fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name": "consumer"}\n');
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.config.mjs'),
+    "export default {integrations: ['@acme/kit']};\n",
+  );
+  const kit = path.join(tmpDir, 'node_modules', '@acme', 'kit');
+  fs.mkdirSync(path.join(kit, 'docs'), {recursive: true});
+  fs.writeFileSync(
+    path.join(kit, 'package.json'),
+    JSON.stringify({name: '@acme/kit', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(kit, 'astryx.integration.mjs'),
+    "export default {docs: './docs'};\n",
+  );
+  for (const [file, doc] of Object.entries(files)) {
+    fs.writeFileSync(
+      path.join(kit, 'docs', file),
+      `export const docs = ${JSON.stringify(doc, null, 2)};\n`,
+    );
+  }
+}
+
+/**
+ * @param {string} topic
+ * @param {string} [section]
+ */
+async function read(topic, section) {
+  return (await docs(topic, section, {cwd: tmpDir})).data;
+}
+
+describe('a reference block in a topic section', () => {
+  it(
+    'includes the fields a schema reference names, then where they come from',
+    async () => {
+      scaffold({'acme-setup.doc.mjs': SETUP});
+      const section = await read('acme-setup', 'manifest');
+      expect(section.content.map(block => block.type)).toEqual([
+        'prose',
+        'table',
+        'prose',
+      ]);
+      const table = section.content[1];
+      expect(table.headers).toEqual([
+        'Field',
+        'Type',
+        'Required',
+        'Description',
+      ]);
+      // The fields the block names, in the order it names them.
+      expect(table.rows.map(row => row[0])).toEqual(['components', 'docs']);
+      expect(section.content[2]).toEqual({
+        type: 'prose',
+        text: 'From Astryx Integration: `astryx docs authoring integration`',
+      });
+    },
+    SLOW,
+  );
+
+  it(
+    "reads the included fields from the schema's own doc, not a copy",
+    async () => {
+      scaffold({'acme-setup.doc.mjs': SETUP});
+      const included = (await read('acme-setup', 'manifest')).content[1].rows;
+      const schema = (await docs('authoring', 'integration')).data.content.find(
+        block => block.type === 'table',
+      );
+      expect(included).toEqual(
+        MANIFEST_FIELDS.projection.fields.map(name =>
+          schema.rows.find(row => row[0] === name),
+        ),
+      );
+    },
+    SLOW,
+  );
+
+  it(
+    'returns only the stable block kinds in every read, in JSON and in each language',
+    async () => {
+      scaffold({'acme-setup.doc.mjs': SETUP});
+      for (const lang of [null, 'zh']) {
+        const whole = (await docs('acme-setup', undefined, {cwd: tmpDir, lang}))
+          .data;
+        const kinds = new Set(
+          whole.sections.flatMap(section => section.content.map(b => b.type)),
+        );
+        expect([...kinds].filter(kind => !READ_KINDS.has(kind))).toEqual([]);
+        for (const {id} of whole.sections) {
+          const one = (await docs('acme-setup', id, {cwd: tmpDir, lang})).data;
+          expect(one.content.every(block => READ_KINDS.has(block.type))).toBe(
+            true,
+          );
+        }
+      }
+    },
+    SLOW,
+  );
+
+  it(
+    'includes a whole command doc, without code when compact; a summary and a topic show as one line',
+    async () => {
+      scaffold({'acme-setup.doc.mjs': SETUP});
+      const check = (await read('acme-setup', 'check')).content;
+      expect(check.some(block => block.type === 'code')).toBe(false);
+      expect(check.find(block => block.type === 'table')?.headers).toEqual([
+        'Argument',
+        'Description',
+      ]);
+      // The included doc's own links resolve against its own provider.
+      expect(
+        check.some(
+          block =>
+            block.type === 'prose' &&
+            block.text.includes(
+              'Read it with `astryx docs cli/api/functions/integration-doc-conflicts`.',
+            ),
+        ),
+      ).toBe(true);
+      expect(check.at(-1)).toEqual({
+        type: 'prose',
+        text: 'From astryx doctor integration docs: `astryx docs cli/commands/doctor-integration-docs`',
+      });
+      const more = (await read('acme-setup', 'more')).content;
+      expect(more).toHaveLength(2);
+      expect(more[0].text).toMatch(
+        /^docs\(\): Read the reference docs: .* Read it with `astryx docs cli\/api\/functions\/docs`\.$/,
+      );
+      expect(more[1].text).toMatch(
+        /^Theme System: .* Read it with `astryx docs theme`\.$/,
+      );
+    },
+    SLOW,
+  );
+
+  it(
+    'prints the included content in text',
+    async () => {
+      scaffold({'acme-setup.doc.mjs': SETUP});
+      const {status, stdout} = await runCli(
+        ['docs', 'acme-setup', 'manifest'],
+        tmpDir,
+      );
+      expect(status).toBe(0);
+      expect(stdout).toMatch(/^Field +\| Type +\| Required +\| Description/m);
+      expect(stdout).toMatch(/^components +\| string +\| no +\| /m);
+      expect(stdout).toContain(
+        'From Astryx Integration: `astryx docs authoring integration`',
+      );
+    },
+    SLOW,
+  );
+});
+
+describe('a reference block that includes what it names', () => {
+  it(
+    'passes the authoring check',
+    async () => {
+      scaffold({'acme-setup.doc.mjs': SETUP});
+      const {data} = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
+      expect(data.issues).toEqual([]);
+      const cli = await runCli(
+        ['doctor', 'integration', 'docs', '@acme/kit'],
+        tmpDir,
+      );
+      expect(cli.status).toBe(0);
+    },
+    SLOW,
+  );
+});
+
+describe('what a reference block names', () => {
+  it('resolves a CLI authoring schema by identity, to its section of `astryx docs authoring`', async () => {
+    const resolve = await linkResolver(builtinCatalog(), CLI_PROVIDER_ID);
+    expect(await resolve('schema:integration')).toMatchObject({
+      id: createDocId(CLI_PROVIDER_ID, 'schema', 'integration'),
+      route: 'authoring',
+      title: 'Astryx Integration',
+      command: 'astryx docs authoring integration',
+    });
+    const opened = await docs('authoring', 'integration');
+    expect(opened.type).toBe('docs.detail.section');
+    expect(opened.data.id).toBe('integration');
+  });
+
+  it(
+    "leaves no reference in the CLI's own docs that cannot include what it names",
+    async () => {
+      const catalog = builtinCatalog();
+      expect(
+        await docsLinkProblems(catalog, await projectTree(catalog), {
+          references: true,
+        }),
+      ).toEqual([]);
+    },
+    SLOW,
+  );
+});
+
+describe('a reference block that cannot include what it names', () => {
+  it(
+    'fails the authoring check, once for each part it cannot include',
+    async () => {
+      scaffold({'acme-broken.doc.mjs': BROKEN});
+      const {data} = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
+      const errors = data.issues.filter(
+        issue => issue.code === 'invalid_doc_reference',
+      );
+      expect(errors.every(issue => issue.severity === 'error')).toBe(true);
+      const messages = errors.map(issue => issue.message);
+      expect(messages).toHaveLength(5);
+      expect(messages[0]).toMatch(
+        /^acme-broken § gaps: projection\.fields: "nope" is not a field of Astryx Integration/,
+      );
+      expect(messages[1]).toMatch(
+        /"@astryxdesign\/cli:schema:nothing" names no doc/,
+      );
+      expect(messages[2]).toMatch(
+        /projection\.fields: names the fields of a schema doc/,
+      );
+      expect(messages[3]).toMatch(/projection\.sections: /);
+      expect(messages[4]).toMatch(
+        /"@astryxdesign\/cli:generic:theme" is a topic/,
+      );
+      // They are not also reported as links that print as written.
+      expect(
+        data.issues.filter(issue => issue.code === 'invalid_doc_graph'),
+      ).toEqual([]);
+      const cli = await runCli(
+        ['doctor', 'integration', 'docs', '@acme/kit'],
+        tmpDir,
+      );
+      expect(cli.status).toBe(1);
+    },
+    SLOW,
+  );
+
+  it(
+    'marks the missing content where a read would show it',
+    async () => {
+      scaffold({'acme-broken.doc.mjs': BROKEN});
+      const texts = (await read('acme-broken', 'gaps')).content
+        .filter(block => block.type === 'prose')
+        .map(block => block.text);
+      expect(texts).toContain(
+        '[reference: field "nope" not found in "@astryxdesign/cli:schema:integration"]',
+      );
+      expect(texts).toContain(
+        '[reference: "@astryxdesign/cli:schema:nothing" names no doc]',
+      );
+      // The field it could include is still there.
+      const table = (await read('acme-broken', 'gaps')).content.find(
+        block => block.type === 'table',
+      );
+      expect(table.rows.map(row => row[0])).toEqual(['components']);
+    },
+    SLOW,
+  );
+
+  it(
+    "warns in a project's doctor, which an app cannot fix",
+    async () => {
+      scaffold({'acme-broken.doc.mjs': BROKEN});
+      const check = await checkDocsTree({
+        docsCatalog: await loadDocsCatalog(tmpDir),
+      });
+      expect(check.status).toBe('warn');
+      expect(check.message).toContain(
+        '"nope" is not a field of Astryx Integration',
+      );
+    },
+    SLOW,
+  );
+});