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

package/assets/docs/tree/check-the-props.doc.mjs

@@ -0,0 +1,196 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/check-the-props`:
+ * compare each component doc's props table with the component's TypeScript
+ * props, read each finding, and fix the doc or the code.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'check-the-props',
+  placement: {
+    parent: 'namespace:describe-the-component',
+    slot: 'guides',
+    order: 50,
+  },
+  title: 'Check the props table',
+  category: 'guide',
+  keywords: [
+    'props table',
+    'documented props',
+    'prop drift',
+    'props not compared',
+  ],
+  description:
+    "Compare each props table with the component's TypeScript props, then fix the doc or the code.",
+  sections: [
+    {
+      id: 'run-the-props-check',
+      title: 'Run the props check',
+      content: [
+        {
+          type: 'prose',
+          text: "`doctor integration components` compares every props table in your component docs, hidden docs and every family entry included, with the props the component's TypeScript declares. Run it in your package after you change a component or its doc.",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx doctor integration components',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: `severity:  [warn]
+component: AcmeCarousel
+prop:      loop
+kind:      not_in_code
+message:   "loop" is documented, but AcmeCarousel's props have no "loop".
+doc:       components/AcmeCarousel.doc.mjs
+source:    components/AcmeCarousel.tsx
+docType:   boolean
+
+1 prop(s) differ between the docs and the code in 1 of 1 component(s) compared (TypeScript 6.0.3). These are warnings: update the doc, or the code if the doc is right.`,
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "A doc's own `props` describe the export its `name` names. In a family doc, each entry describes its own export. A hook entry documents parameters and returns, so it is not compared.",
+            "It reads props with the `typescript` your package installs, and reads your package's `tsconfig.json` the way `tsc -p` does. Without TypeScript it prints `[skip] Props not compared` and the reason.",
+            'Every finding is a warning, so the exit code stays 0. Read them before you publish. With `--json`, they are in `data.propDrift.findings`.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'fix-each-finding',
+      title: 'Fix each finding',
+      content: [
+        {
+          type: 'prose',
+          text: "Each finding's `kind` says what differs. Fix the doc, or the code if the doc is right.",
+        },
+        {
+          type: 'table',
+          headers: ['Kind', 'Means', 'Fix'],
+          rows: [
+            [
+              '`not_in_code`',
+              "The doc lists a prop the component's props do not have",
+              'Remove it from the doc, or add it to the code. A name an index signature takes, such as `data-*`, counts as present',
+            ],
+            [
+              '`not_in_doc`',
+              "Your package declares a prop the doc does not list, or builds one with a mapped type, such as `Partial<Record<'sm' | 'md', string>>`",
+              'Document it. Props from React, the DOM, or another package are never asked for, and neither are props whose keys another package defines (`keyof CSSProperties`, behind an alias or not), `className`, `style`, `xstyle`, `data-testid`, `ref`, `key`, or a prop whose JSDoc has `@internal`. A deprecated prop is still a prop: document it until you remove it. A prop a mapped type builds from keys the check cannot trace (a template literal, say) is listed under `[info] Props not checked for a doc entry` instead',
+            ],
+            [
+              '`required_mismatch`',
+              '`required` disagrees with the code',
+              'Set `required: true` exactly when every caller must pass the prop. One your `defaultProps` fills counts as optional, as it is to JSX callers, and so does one only some members of a union require, since a caller can leave it out: say in its description which variants need it. An entry that names several props (`value / onChange`) makes the same claim about each: give them separate entries when they differ',
+            ],
+            [
+              '`type_mismatch`',
+              "The documented `type` differs from the code's, where both read exactly",
+              'Copy the type from the source, or fix the code. The next section says which types are judged',
+            ],
+          ],
+        },
+      ],
+    },
+    {
+      id: 'write-types-the-check-can-judge',
+      title: 'Write types the check can judge',
+      content: [
+        {
+          type: 'prose',
+          text: 'For a prop your package declares, the check also compares the documented `type`, but only where both sides read exactly. It never guesses, so a type it cannot judge is listed, not reported. It needs TypeScript 4.8 or later: with an older one it prints `[skip] Prop types not judged` and judges none.',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: `severity:  [warn]
+component: AcmeCarousel
+prop:      interval
+kind:      type_mismatch
+message:   "interval" is documented as string, but the code declares number.
+doc:       components/AcmeCarousel.doc.mjs
+source:    components/AcmeCarousel.tsx
+docType:   string
+codeType:  number`,
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "Write the type as the source writes it, such as `ReactNode[]` or `(index: number) => void`. Parameter names, member order, quotes and whitespace may differ. Text that writes `readonly` must match exactly, parameter names included; only whitespace may differ. `React.X` names React's own `X` where the prop is declared, so it matches a bare `X` only where that name is React's: `React.KeyboardEvent` is not the DOM's `KeyboardEvent`.",
+            "Name a type as the file that declares the prop names it, so an import renamed there (`Item as BaseItem`) is written as that file writes it. A field (`cfg.level`) takes its prop's file, even when the field's own type is declared in another file.",
+            'A type written another way is judged only when both sides are built from exact parts: primitives such as `string` and `number`, string, number and boolean literals, string enum members, arrays and unions of these, and type names that stand for them. Union members may come in any order, and a member another covers adds nothing, as TypeScript passes it there: `undefined` beside `void`, or `string[]` beside `(string | number)[]`.',
+            'A mutable array type matches a readonly one, because callers can pass it. A readonly one documented for a mutable array is a mismatch.',
+            "When a prop's variants give a field different types, as `{value: string} | {value: number}` does, document every variant's type (`string | number`). The types of only some variants are listed: the prop's variants give this field different types. With more than six variant types, any other type is listed too.",
+            "To name an alias and show its values, write `AcmeSize = 'sm' | 'md'` or `AcmeSize ('sm' | 'md')`. Both parts must match.",
+            "An optional prop's `undefined` is set aside on both sides. With `exactOptionalPropertyTypes`, the doc shows `undefined` exactly when the code declares it.",
+            'Anything else, such as an object, a tuple, a generic with arguments, `keyof`, an intersection, or a mapped or conditional type written another way, is not compared.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: "The check prints how many documented types it judged, then lists the rest by reason: not a form the check judges exactly, a field the prop's variants give different types, a standard prop, or a prop declared outside the package. With `--json`, they are in `data.propDrift.typesNotCompared`.",
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: '[info] Documented prop types judged: 2; not compared: 0. A type is judged when the doc writes it the same as the source (exactly, if it contains `readonly`), or when both are primitives, literals, arrays and unions of those, or names for them.',
+        },
+      ],
+    },
+    {
+      id: 'when-a-component-is-not-compared',
+      title: 'When a component is not compared',
+      content: [
+        {
+          type: 'prose',
+          text: "When the check cannot read a component's props exactly, it lists the component under `[info] Props not compared`, with the reason, instead of reporting findings that might be wrong.",
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: `[info] Props not compared for 1 documented component(s):
+
+component: AcmeCarousel
+doc:       components/AcmeCarousel.doc.mjs
+reason:    AcmeCarousel depends on \`@acme/motion\` (imported in AcmeCarousel.tsx), which the compiler could not resolve, usually a dependency that is not installed. Install the package's dependencies and run this check again`,
+        },
+        {
+          type: 'table',
+          headers: ['Reason', 'Fix'],
+          rows: [
+            [
+              'It depends on a package or file the compiler could not resolve',
+              "Install the package's dependencies, then run the check again",
+            ],
+            [
+              "It depends on a type the compiler can't work out",
+              'Make the types compile with `npx tsc --noEmit`, then run the check again',
+            ],
+            [
+              "The package's TypeScript config has an error",
+              'Fix `tsconfig.json` until `npx tsc -p .` reads it',
+            ],
+            ['Its props are typed `any`', 'Give the component a props type'],
+            [
+              'Some prop names come from a type parameter',
+              'Nothing to fix: a component that renders an element the caller picks takes props known only where it is used',
+            ],
+            [
+              "The file has no export named by the doc's `name`",
+              'Change `name` or the export so they agree',
+            ],
+          ],
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/check-your-docs.doc.mjs

@@ -1,9 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/docs/check-your-docs`: what each check
- * proves about an integration's docs: the docs check, the read size, and the
- * CLI peer.
+ * @file `astryx docs cli/integrations/building-blocks/docs/check-your-docs`:
+ * what each check proves about an integration's docs: the docs check, each
+ * doc's fields, the read size, and the CLI peer.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -13,7 +13,8 @@ export const docs = {
   placement: {parent: 'namespace:docs', slot: 'guides', order: 60},
   title: 'Check your docs',
   category: 'guide',
-  description: 'Check the docs tree, links, overlaps, read size, and CLI peer.',
+  description:
+    'Check the docs tree, links, overlaps, doc fields, read size, and CLI peer.',
   sections: [
     {
       id: 'run-the-docs-check',
@@ -45,7 +46,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'A doc that does not load, an accidental Core overlap, or a failed namespace or placement fails the check with exit code 1. A link that names no doc only warns, and the exit code stays 0.',
+          text: 'A doc that does not load, an accidental Core overlap, a `reference` block that names no doc, or a failed namespace or placement fails the check with exit code 1. A link that names no doc only warns, and the exit code stays 0.',
         },
         {
           type: 'table',
@@ -66,6 +67,11 @@ export const docs = {
               '`[fail]` `invalid_doc_graph`',
               '1',
             ],
+            [
+              'A `reference` block whose target names no doc',
+              '`[fail]` `invalid_doc_reference`',
+              '1',
+            ],
             ['A link that names no doc', '`[warn]` `invalid_doc_graph`', '0'],
             [
               'A topic that sets `replaces` or `extends`',
@@ -80,6 +86,46 @@ export const docs = {
         },
       ],
     },
+    {
+      id: 'check-each-doc-against-its-type',
+      title: 'Check each doc against its type',
+      content: [
+        {
+          type: 'prose',
+          text: "`doctor integration validate` reads every doc your package ships against the type `@astryxdesign/cli/authoring` publishes for its kind, the way `tsc` would: a `hidden` doc and a second doc for one name too. Test fixtures under `__tests__` in the components or docs root, which those readers skip, are counted, not checked. It reports a field the type does not have (`unknown_field`), a missing required field (`missing_field`), and a value outside the field's type (`wrong_type`).",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx doctor integration validate',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: `Checking 1 doc(s) against the authoring types (TypeScript 6.0.3)
+
+severity: [warn]
+doc:      components/AcmeCarousel.doc.mjs
+line:     7
+export:   default
+type:     ComponentDoc
+field:    summary
+problem:  unknown_field
+message:  Object literal may only specify known properties, and 'summary' does not exist in type 'SingleComponentDoc'.
+fix:      Remove \`summary\`: SingleComponentDoc has no field \`summary\`.`,
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "The folder decides the type: `ComponentDoc` in your components root, `IntegrationTemplateDoc` in your templates root, `ThemeDoc` in your themes root, and in your docs root the type the doc's `type` names. Keep the `@type` comment above each doc's export too, so your editor shows the same problems as you type.",
+            'Every finding is a warning, so the exit code stays 0. With `--json`, they are in `data.docTypes.findings`.',
+            'It uses the `typescript` your package installs. Without it, it prints `[skip] Docs not type-checked` and the reason.',
+            'Every field of every doc type is in `astryx docs authoring`.',
+          ],
+        },
+      ],
+    },
     {
       id: 'check-read-size',
       title: 'Check read size',

package/assets/docs/tree/checks.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/checks`: what each package check
+ * @file `astryx docs cli/integrations/ship/checks`: what each package check
  * proves, what fails and what only warns, and one command to run them all.
  */
 
@@ -12,7 +12,7 @@ export const docs = {
   placement: {parent: 'namespace:ship', slot: 'guides', order: 20},
   title: 'Check an integration',
   category: 'guide',
-  keywords: ['check before publishing', 'validate an integration', 'ci'],
+  keywords: ['check before publishing', 'validate an integration'],
   description:
     'Pick the check for each problem, learn what fails and what only warns, and run every check in CI.',
   sections: [
@@ -22,7 +22,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Run these in the package folder. The four `doctor integration` checks read your source; `integration verify` checks the package npm would publish.',
+          text: 'Run these in the package folder. The four `doctor integration` checks read your source, and `integration check` runs all four; `integration verify` checks the package npm would publish.',
         },
         {
           type: 'table',
@@ -30,15 +30,15 @@ export const docs = {
           rows: [
             [
               '`npx astryx doctor integration validate`',
-              'The manifest loads, and each root holds contributions the CLI can read',
+              'The manifest loads, each root holds contributions the CLI can read, and each doc matches its authoring type',
               'A declared root is missing (`missing_root`), a contribution does not load (`invalid_doc`, `invalid_component`, `invalid_theme`), or two templates in the package replace one Core id (`ambiguous_template_replacement`)',
-              'The manifest has a key this CLI does not know (`unknown_manifest_key`). With no `astryx.integration.mjs` it prints a hint and exits 0',
+              "The manifest has a key this CLI does not know (`unknown_manifest_key`), or a doc field does not match the doc's authoring type: a field the type does not have, a missing required field, or a value outside the field's type. It checks docs with your installed `typescript`; without it, it prints `[skip] Docs not type-checked`. With no `astryx.integration.mjs` it prints a hint and exits 0",
             ],
             [
               '`npx astryx doctor integration components`',
-              'No component name clashes with a Core component, and each `replaces` names one Core component',
+              "No component name clashes with a Core component, each `replaces` names one Core component, and each component doc's props match the component's TypeScript props",
               'Core is not installed (`core_not_found`). In a package that declares the CLI range that turns replacement on, a `replaces` target is missing (`missing_component_replacement_target`) or invalid (`invalid_component_replacement`), or two components replace one Core component (`ambiguous_component_replacement`)',
-              'A name clashes with Core, or a component sets `replaces` in a package without that range (`inactive_component_replacement`, plus any missing, invalid, or duplicate `replaces` reported as a warning)',
+              'A name clashes with Core, a component sets `replaces` in a package without that range (`inactive_component_replacement`, plus any missing, invalid, or duplicate `replaces` reported as a warning), or a documented prop differs from the code: it is missing there (`not_in_code`), the doc omits a prop the package declares (`not_in_doc`), or its `required` (`required_mismatch`) or type (`type_mismatch`) disagrees. It reads props with your installed `typescript`; without it, it prints `[skip] Props not compared`',
             ],
             [
               '`npx astryx doctor integration templates`',
@@ -52,6 +52,12 @@ export const docs = {
               'A topic takes a Core topic name without `replaces` or `extends`, a doc is invalid (`invalid_doc`), or a namespace or placement fails, which hides the doc (`invalid_doc_graph`)',
               'A link names no doc (`invalid_doc_graph`)',
             ],
+            [
+              '`npx astryx integration check`',
+              'Everything the four `doctor integration` checks prove, in one command, for your build',
+              'Any of the four would exit 1 on its own. With `--strict`, also any warning, and any check that did not run, such as a package with no `astryx.integration.*`',
+              'Anything the four warn about, unless you pass `--strict`',
+            ],
             [
               '`npx astryx integration verify`',
               'The packed package holds every file, shows the same contributions, resolves every public import, and declares the CLI it needs',
@@ -62,29 +68,31 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'Pass a package name, such as `npx astryx doctor integration validate @acme/astryx-widgets`, to check an installed copy from an app instead.',
+          text: 'Pass a package name, such as `npx astryx doctor integration validate @acme/astryx-widgets`, to check an installed copy from an app instead. To fix a props finding, see {@link generic:check-the-props}.',
         },
       ],
     },
     {
       id: 'run-every-check-in-ci',
-      title: 'Run every check in CI',
+      title: 'Run every check in every build (required)',
       content: [
         {
           type: 'prose',
-          text: 'Chain the five checks so the first failure stops the run. Install devDependencies first, because the components check needs Core.',
+          text: 'Every integration runs `integration check --strict` in its own build, so every build keeps your docs, types, and links in sync; this is required, not optional. Run `integration verify` before you publish. Install devDependencies first, because the components check needs Core, and `tsc --noEmit` needs `typescript` and a `tsconfig.json`. In package.json:',
         },
         {
           type: 'code',
-          lang: 'bash',
-          code: 'npx astryx doctor integration validate && npx astryx doctor integration components && npx astryx doctor integration templates && npx astryx doctor integration docs && npx astryx integration verify',
+          lang: 'json',
+          code: '"typecheck": "tsc --noEmit && astryx integration check --strict"',
         },
         {
           type: 'list',
           style: 'unordered',
           items: [
-            '`integration verify` runs `validate` but none of the other three: a Core name clash, a `replaces` that names no Core template, a topic that takes a Core name, or a hidden guide still passes it.',
-            'Warnings keep exit code 0, so read them before you publish.',
+            '`integration check` runs `validate`, `components`, `templates`, and `docs` in that order, prints each result, then a summary, and exits 1 when any of them would.',
+            '`--strict` also exits 1 on any warning and on any check that did not run. Without it, warnings keep exit code 0: use that while you fix the warnings a package already has.',
+            'Its exit codes and JSON are a contract for your build: 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.',
+            '`integration verify` runs `validate` but none of the other three: a Core name clash, a `replaces` that names no Core template, a topic that takes a Core name, or a hidden guide still passes it. Run both before you publish: `npx astryx integration check --strict && npx astryx integration verify`.',
             'Bare `npx astryx doctor` in the package also warns about a doc section over 32 KB, which no check above measures.',
           ],
         },
@@ -105,14 +113,14 @@ export const docs = {
             'It runs `npm pack` the way `npm publish` would, including your `prepack` script.',
             'It checks that every contribution file is in the `.tgz` file. A root missing from `files` fails with `Add "templates" to "files" in package.json.`',
             'It lists the components, templates, themes, docs, and codemods the temporary app sees, and compares them with your source.',
-            "It resolves each component's `import`, and each template's public import, the way Node does, and checks that the module exports the component, or a default export for a template.",
+            "It resolves each component's `import`, and each template's public import, the way Node does, and checks that the module exports the component under the name its doc documents, or a default export for a template. A type-only export does not count.",
             'For each theme, it rebuilds the source, compares the built module and production CSS with the authored outputs, and proves the module, CSS, and optional font CSS exports resolve from the packed package.',
             'It fails a package that needs an `@astryxdesign/cli` peer and lacks it: `>=0.6.6` for a template that sets `keywords`, and `>=0.6.4` for a template that sets `replaces`, a docs section, a placed guide, a doc section with an `id`, or a theme.',
           ],
         },
         {
           type: 'prose',
-          text: '`integration pack --check`, the name this check had in 0.6, still runs it and prints a note; it will be removed in a later release. The options and exit codes are in {@link command:integration verify}.',
+          text: '`integration pack --check`, the name this check had before published 0.6.5, still runs it and prints a note; it will be removed in a later release. The options and exit codes are in {@link command:integration verify}.',
         },
       ],
     },

package/assets/docs/tree/codemods.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/codemods`: add codemods to an
+ * @file `astryx docs cli/integrations/building-blocks/codemods`: add codemods to an
  * integration package, and know which of them `astryx upgrade` runs in an app.
  */
 
@@ -82,7 +82,7 @@ export default {
         },
         {
           type: 'prose',
-          text: "`type: 'code'` rewrites the app's source files that match `fileExtensions`. `type: 'config'` rewrites the app's `astryx.config` file instead, and runs before code codemods. `title` shows in the upgrade output, and `api.jscodeshift` is a jscodeshift instance for the file. Every field is in {@link generic:authoring}.",
+          text: "`type: 'code'` rewrites the app's source files that match `fileExtensions`. `type: 'config'` rewrites the app's `astryx.config` file instead, and runs before code codemods. `title` shows in the upgrade output, and `api.jscodeshift` is a jscodeshift instance for the file. Every field is in {@link schema:codemod}.",
         },
       ],
     },
@@ -124,14 +124,14 @@ npx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets --apply`,
           type: 'code',
           lang: 'text',
           code: `Integrations: @acme/astryx-widgets
-1 codemod to run (dry run)
+<n> codemods to run (dry run)
 Applying integration codemods...
   Rename AcmeCarousel delay to interval (v0.7.0, @acme/astryx-widgets)
 !     ~ src/Hero.tsx (would change)`,
         },
         {
           type: 'prose',
-          text: "The count includes Core's codemods for the same versions, which run first and print above `Integrations:`. To run only yours, as when you test it, add `--codemod rename-delay`.",
+          text: "`<n>` counts Core's codemods for the same versions too: they run first and print above `Integrations:`. To run only yours, as when you test it, add `--codemod rename-delay`.",
         },
         {
           type: 'prose',

package/assets/docs/tree/component-family.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/describe-the-component/component-family`:
+ * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/component-family`:
  * author one ComponentDoc for several public exports in a component family.
  */
 
@@ -38,10 +38,8 @@ export const docs = {
           ],
         },
         {
-          type: 'reference',
-          target: 'schema:component-doc',
-          projection: {fields: ['components']},
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:component-doc}.',
         },
       ],
     },
@@ -95,7 +93,11 @@ export default {
         },
         {
           type: 'prose',
-          text: 'The public module named by `import` must export every component or hook named by a full entry.',
+          text: "The public module named by `import` must export every component or hook named by a full entry. Apps then list, search and open each component in the family by its own name. A full entry the module does not export is not listed, and `integration verify` does not report it: check the family with `astryx component --list`. When `import` names output your pack lifecycle builds (such as `dist`), the members are listed once that output exists, and `integration verify` compares them as they are listed after the pack builds it.",
+        },
+        {
+          type: 'prose',
+          text: "A member's source is the `.tsx` file in the family doc's folder, or below it, that declares it: the one the family's own file or the module `import` names reaches, else the one in that folder that declares the name, as when `import` names built output. A member that only a bundle or a file outside that folder declares is still listed, with no source for `--source` or `swizzle`. A member is not listed when a doc's file or a Core name your package replaces already has its name. A member that shares a name with Core opens with `--package`.",
         },
       ],
     },

package/assets/docs/tree/component-imports.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/component-imports`: make an
+ * @file `astryx docs cli/integrations/building-blocks/components/component-imports`: make an
  * integration component's documented import resolve from the packed package.
  */
 
@@ -35,6 +35,14 @@ export const docs = {
           type: 'prose',
           text: 'Add writes the entry only when package.json already has an `exports` map, so start every package with `"exports": {}`.',
         },
+        {
+          type: 'prose',
+          text: 'A file does not have to be named after its component. When `Slides.tsx` exports `AcmeCarousel` and nothing named `Slides`, keep the doc beside it as `Slides.doc.mjs` and set its `name` to `AcmeCarousel`: apps list, search and open the component by that name, and `integration verify` checks that its import exports `AcmeCarousel`. A file that exports its own name keeps that name. A package that names its files in kebab case works the same way: `acme-gallery.doc.mjs` beside `acme-gallery.tsx` sets `name: \'AcmeGallery\'`.',
+        },
+        {
+          type: 'prose',
+          text: "The file name still opens the doc. A name that Core or another doc's file already has stays theirs, and so does a Core name your package replaces: with `Badge.doc.mjs` naming `AcmeBadge`, `astryx component Badge` opens Core's `Badge`, and `--package` with your package name reaches yours.",
+        },
       ],
     },
     {
@@ -43,7 +51,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: '`integration verify` installs the packed package in a temporary app, resolves each documented import, and checks that the module exports the documented component name.',
+          text: '`integration verify` unpacks the packed package into a temporary app, resolves each documented import, and checks that the module exports the documented component name. Its `--json` output names each failure by code.',
         },
         {
           type: 'code',

package/assets/docs/tree/components.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components`: guides for adding and
+ * @file `astryx docs cli/integrations/building-blocks/components`: guides for adding and
  * documenting components in an integration package.
  */
 

package/assets/docs/tree/debug-and-gap-reports.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/debug-and-gap-reports`: receive a record
+ * @file `astryx docs cli/integrations/building-blocks/configuration/debug-and-gap-reports`: receive a record
  * of each CLI run with `debug`, and handle `astryx gap-report` with
  * `gapReport`, both named exports of the integration manifest.
  */
@@ -44,7 +44,7 @@ export default {
         },
         {
           type: 'prose',
-          text: 'The event is a `DebugEvent` with `command`, `outcome`, `exitCode`, `durationMs`, `error`, and more, its values scrubbed (`redacted: true`). Every field is in {@link generic:authoring}.',
+          text: 'The event is a `DebugEvent` with `command`, `outcome`, `exitCode`, `durationMs`, `error`, and more, its values scrubbed (`redacted: true`). Every field is in {@link schema:debug-event}.',
         },
         {
           type: 'prose',
@@ -104,22 +104,11 @@ export const gapReport = {
         },
         {
           type: 'prose',
-          text: 'Every handler in the app gets every report, so check `report.target.package` and skip reports about other packages. The receipt `status` is one of:',
-        },
-        {
-          type: 'table',
-          headers: ['`status`', 'Meaning'],
-          rows: [
-            [
-              '`filed`',
-              'You created or queued the report. Return `url` or `message`.',
-            ],
-            [
-              '`routed_only`',
-              'You point the caller to where to file it. `url` is required.',
-            ],
-            ['`skipped`', 'You chose not to act, for example on a duplicate.'],
-          ],
+          text: 'Every handler in the app gets every report, so check `report.target.package` and skip reports about other packages.',
+        },
+        {
+          type: 'prose',
+          text: 'Every field is in {@link schema:gap-report-handler}.',
         },
         {
           type: 'prose',

package/assets/docs/tree/define-the-theme.doc.mjs

@@ -45,7 +45,7 @@ export const oceanTheme = defineTheme({
         },
         {
           type: 'prose',
-          text: 'Local imports must stay inside the theme folder. One that leaves it, such as `../../shared/colors`, fails with `invalid_theme`, and the theme disappears from `theme list`. `npx astryx theme template` writes a file that explains every `defineTheme` field. For the full token set, scope selectors, and component theming, read {@link generic:author-a-theme}.',
+          text: 'Local imports must stay inside the theme folder. One that leaves it, such as `../../shared/colors`, fails with `invalid_theme`, and every theme in the package disappears from `theme list`. `npx astryx theme template` writes a file that explains every `defineTheme` field. For the full token set and component theming, read {@link generic:author-a-theme}.',
         },
       ],
     },
@@ -55,13 +55,14 @@ export const oceanTheme = defineTheme({
       content: [
         {
           type: 'prose',
-          text: 'To base a theme on an existing one, `extends` it: import the base theme and override only the tokens you change. The derived theme keeps a live link to the base and inherits its later changes — unlike `--from`, which forks a copy ({@link generic:add-a-theme}).',
+          text: 'To base a theme on an existing one, `extends` it: import the base theme and override only the tokens you change. Add the derived theme with `integration add theme ocean-contrast`, and import the base from its built package export, since local imports cannot leave the theme folder. The derived theme keeps a live link to the base and picks up its later changes when you rebuild it — unlike `--from`, which forks a copy ({@link generic:add-a-theme}).',
         },
         {
           type: 'code',
           lang: 'ts',
-          code: `import {defineTheme} from '@astryxdesign/core/theme';
-import {oceanTheme} from './oceanTheme';
+          code: `// themes/ocean-contrast/oceanContrastTheme.ts
+import {defineTheme} from '@astryxdesign/core/theme';
+import {oceanTheme} from '@acme/astryx-widgets/themes/ocean';
 
 export const oceanContrastTheme = defineTheme({
   name: 'ocean-contrast',
@@ -79,7 +80,7 @@ export const oceanContrastTheme = defineTheme({
       content: [
         {
           type: 'prose',
-          text: 'Each `[light, dark]` pair compiles to a `light-dark()` value, which switches only colors. Give it colors. For a value that is not a plain color — a gradient — put `light-dark()` on each color stop, not around the whole value: a browser without `light-dark()` drops the declaration, and the stop form is the one that degrades safely.',
+          text: 'Each `[light, dark]` pair compiles to a `light-dark()` value, which switches only colors. Give it colors. For a value that is not a plain color — a gradient — put `light-dark()` on each color stop, not around the whole value: `light-dark()` takes two colors, so wrapping whole gradients makes the value invalid where the token is used, and `theme build` does not warn.',
         },
       ],
     },

package/assets/docs/tree/describe-the-component.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/describe-the-component`:
+ * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component`:
  * choose and maintain the ComponentDoc shape that matches a component's public
  * source.
  */
@@ -37,7 +37,7 @@ export const docs = {
       items: [
         'Change the source and its `.doc.mjs` together.',
         'Update the doc whenever the public name, import, behavior, props, defaults, examples, or accessibility requirements change.',
-        '`integration verify` checks the doc shape and packed import, but it cannot prove the prose still matches the component.',
+        '`integration verify` checks the doc shape and packed import, and `doctor integration components` compares each props table with the component\'s TypeScript props ({@link generic:check-the-props}). Neither can prove the prose still matches the component.',
       ],
     },
     {

package/assets/docs/tree/docs.doc.mjs

@@ -1,9 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/docs`: the guides to writing docs for an
- * integration package, which join the same docs tree as the CLI's own
- * (spec:AST-046, spec:AST-047).
+ * @file `astryx docs cli/integrations/building-blocks/docs`: the guides to
+ * writing docs for an integration package, which join the same docs tree as
+ * the CLI's own (spec:AST-046, spec:AST-047).
  */
 
 /** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */