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

package/api/theme/build/build.mjs

@@ -27,8 +27,10 @@
  * files; an internal callback lets the CLI make only the process status fail.
  * Human progress is emitted through the shared `logger` (silent by default), so
  * the CLI keeps its exact output while a programmatic caller stays quiet.
- * Every output, explicit or beside the theme file, stays inside `cwd`
- * (`ERR_PATH_TRAVERSAL` otherwise), in check mode too.
+ * Every output a build writes, explicit or beside the theme file, stays inside
+ * `cwd` (`ERR_PATH_TRAVERSAL` otherwise). Check mode writes nothing, so it
+ * compares outputs outside `cwd` read-only; only a relative `out` path that
+ * escapes `cwd` is refused there too.
  *
  * The installed `@astryxdesign/core` is an independently versioned optional
  * peer, so it can be older than the CLI. A theme that uses only baseline
@@ -60,7 +62,10 @@ import {isBuiltin} from 'node:module';
 import {fileURLToPath, pathToFileURL} from 'node:url';
 import {parse} from '@babel/parser';
 import {createJiti} from 'jiti';
-import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {
+  formatCliCommand,
+  getCliInvocation,
+} from '../../../foundation/env/package-manager.mjs';
 import {
   CLI_ROOT,
   findCoreDir,
@@ -568,6 +573,86 @@ function confineOutputs(writes, root, remedy) {
   for (const write of writes) confineOutput(write.dest, root, remedy);
 }
 
+/** @param {string} dest absolute output path @param {string} root @returns {boolean} whether a build at `root` refuses to write `dest` */
+function refusedOutput(dest, root) {
+  try {
+    confineOutput(dest, root, '');
+    return false;
+  } catch (err) {
+    if (
+      err instanceof AstryxError &&
+      err.code === ERROR_CODES.ERR_PATH_TRAVERSAL
+    )
+      return true;
+    throw err;
+  }
+}
+
+/** @param {string[]} dirs absolute directories @returns {string | null} the deepest directory containing all of them, or null across roots */
+function commonDirectory(dirs) {
+  let common = dirs[0];
+  for (const dir of dirs.slice(1)) {
+    while (
+      path.relative(common, dir).startsWith('..') ||
+      path.isAbsolute(path.relative(common, dir))
+    ) {
+      const parent = path.dirname(common);
+      if (parent === common) return null;
+      common = parent;
+    }
+  }
+  return common;
+}
+
+/** @param {string} value @returns {string} `value` as one shell word */
+function shellWord(value) {
+  if (/^[A-Za-z0-9@%+=:,./_-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * How a stale check report ends when outputs sit outside the write root. A
+ * build there refuses them, and each output's `Source:` header records the
+ * directory its build ran from, so the build and the check both run from the
+ * nearest directory that contains every theme file and output.
+ * @param {Array<{dest: string}>} writes
+ * @param {string[]} sources absolute theme files the build reads
+ * @param {string} root the directory a build here keeps its writes inside
+ * @param {(relative: (file: string) => string) => string[]} args the arguments after `theme build`, given each path relative to the directory to run from
+ * @returns {string[] | null} report lines, or null when every output is inside `root`
+ */
+function outsideCheckRemedy(writes, sources, root, args) {
+  if (!writes.some(write => refusedOutput(write.dest, root))) return null;
+  const real = (/** @type {string} */ file) => realLocation(path.resolve(file));
+  const dir = commonDirectory([
+    ...sources.map(file => path.dirname(real(file))),
+    ...writes.map(write => path.dirname(real(write.dest))),
+  ]);
+  if (!dir) {
+    return [
+      'These outputs are outside the working directory, so a build here refuses them. Build and check them from one directory that contains the theme files and the outputs.',
+    ];
+  }
+  const command = (/** @type {string[]} */ extra) =>
+    formatCliCommand(
+      [
+        'theme',
+        'build',
+        ...args(file => path.relative(dir, real(file))),
+        ...extra,
+      ]
+        .map(shellWord)
+        .join(' '),
+      dir,
+    );
+  return [
+    'These outputs are outside the working directory, so a build here refuses them, and each output records the directory it was built from. Build and check them from a directory that contains them:',
+    `  cd ${shellWord(dir)}`,
+    `  ${command([])}`,
+    `  ${command(['--check'])}`,
+  ];
+}
+
 /** @param {Array<{dest: string, content: string}>} writes */
 function writeBuildOutputs(writes) {
   if (writes.length === 0) return;
@@ -2859,9 +2944,13 @@ async function themeBuildInternal(
   const writeRoot = options.__writeRoot ?? cwd;
   let outPath;
   if (options.out) {
-    // Relative or absolute, the explicit output stays inside the write root.
     outPath = path.resolve(cwd, options.out);
-    confineOutput(outPath, writeRoot, OUT_REMEDY, options.out);
+    // A build keeps the explicit output inside the write root, relative or
+    // absolute. Check mode writes nothing, so it refuses only a relative path
+    // that escapes cwd.
+    if (!options.check || !path.isAbsolute(options.out)) {
+      confineOutput(outPath, writeRoot, OUT_REMEDY, options.out);
+    }
   } else {
     outPath = path.join(path.dirname(filePath), `${baseName}.css`);
   }
@@ -2957,10 +3046,12 @@ async function themeBuildInternal(
     writes.push({dest: variantDtsPath, content: variantContent});
   }
 
-  // Every output stays inside cwd, including the defaults beside the theme
-  // file. Check mode refuses the same paths, so it never passes outputs that a
-  // build would refuse to write.
-  confineOutputs(writes, writeRoot, options.out ? OUT_REMEDY : SOURCE_REMEDY);
+  // Every output a build writes stays inside cwd, including the defaults
+  // beside the theme file. Check mode writes nothing, so it compares outputs
+  // outside cwd read-only.
+  if (!options.check) {
+    confineOutputs(writes, writeRoot, options.out ? OUT_REMEDY : SOURCE_REMEDY);
+  }
 
   // Check mode: compare generated content against what's on disk instead of
   // writing. A file is "stale" if it's missing or its content differs once the
@@ -2980,7 +3071,10 @@ async function themeBuildInternal(
           `  ${s.reason === 'missing' ? 'missing' : 'stale'}: ${s.path}`,
         );
       }
-      logger.error(`\n  Rebuild with: ${buildCommand}`);
+      // prettier-ignore
+      const remedy = outsideCheckRemedy(writes, [filePath], writeRoot, relative => [relative(filePath), ...(options.out ? ['--out', relative(outPath)] : []), ...(options.iconsSpecifier ? ['--icons-specifier', options.iconsSpecifier] : [])]);
+      if (remedy) logger.error(`\n  ${remedy.join('\n  ')}`);
+      else logger.error(`\n  Rebuild with: ${buildCommand}`);
     }
     return {
       type: 'theme.build.check',
@@ -3506,8 +3600,8 @@ export async function themeBuildFamily(
     js: path.relative(cwd, jsPath),
     dts: path.relative(cwd, dtsPath),
   };
-  // The family's outputs stay inside cwd too, in check mode as well.
-  confineOutputs(writes, cwd, FAMILY_REMEDY);
+  // A family build's outputs stay inside cwd too; check mode only reads them.
+  if (!options.check) confineOutputs(writes, cwd, FAMILY_REMEDY);
   if (options.check) {
     const stale = staleBuildOutputs(writes, cwd);
     const upToDate = stale.length === 0;
@@ -3524,7 +3618,10 @@ export async function themeBuildFamily(
           `  ${entry.reason === 'missing' ? 'missing' : 'stale'}: ${entry.path}`,
         );
       }
-      logger.error(`\n  Rebuild with: ${buildCommand}`);
+      // prettier-ignore
+      const remedy = outsideCheckRemedy(writes, members.map(member => member.filePath), cwd, relative => ['--family', ...members.map(member => relative(member.filePath)), '--family-key', baseName, ...(options.iconsSpecifier ? ['--icons-specifier', options.iconsSpecifier] : [])]);
+      if (remedy) logger.error(`\n  ${remedy.join('\n  ')}`);
+      else logger.error(`\n  Rebuild with: ${buildCommand}`);
     }
     return {
       type: 'theme.build.check',

package/api/theme/themeBuild.doc.mjs

@@ -58,13 +58,13 @@ export const doc = {
       name: 'options.out',
       type: 'string',
       description:
-        'Override the output CSS path, relative or absolute; it must resolve inside cwd. The .js, .d.ts and any .variants.d.ts are written in the same directory, named after the theme (<name>.js), not after the CSS file.',
+        'Override the output CSS path, relative or absolute; a build refuses a path outside cwd, and check mode refuses only a relative path that escapes cwd. The .js, .d.ts and any .variants.d.ts are written in the same directory, named after the theme (<name>.js), not after the CSS file.',
     },
     {
       name: 'options.check',
       type: 'boolean',
       description:
-        'Compile in memory and compare each output against what is on disk instead of writing: the CI drift guard.',
+        'Compile in memory and compare each output against what is on disk instead of writing: the CI drift guard. Because it writes nothing, it also compares outputs outside cwd; when those are stale, the report names the directory that contains them and the build and check commands to run from there, since a build refuses them and each output records the directory it was built from.',
       default: 'false',
     },
     {
@@ -77,7 +77,7 @@ export const doc = {
       name: 'ctx.cwd',
       type: 'string',
       description:
-        'Directory the theme file, a relative out path, and the returned output paths resolve against. Every output is written inside it, including the default outputs beside the theme file.',
+        'Directory the theme file, a relative out path, and the returned output paths resolve against. Every output a build writes is inside it, including the default outputs beside the theme file.',
       default: 'process.cwd()',
     },
   ],
@@ -105,7 +105,7 @@ export const doc = {
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
-      when: 'the theme name contains a path separator or traversal marker, or an output resolves outside cwd (including through a symlink): an `out` path, relative or absolute, or the default outputs beside a theme file outside cwd (also rejected in check mode)',
+      when: 'the theme name contains a path separator or traversal marker, or a written output resolves outside cwd (including through a symlink): an `out` path, relative or absolute, or the default outputs beside a theme file outside cwd. Check mode writes nothing, so it refuses only a relative `out` path that escapes cwd',
     },
     {
       code: 'ERR_CORE_NOT_FOUND',

package/assets/docs/styling-overview.doc.mjs

@@ -158,7 +158,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'If a swizzled component renders with no styles and no error, a missing compiler is almost always why. See the StyleX Build Setup section of {@link generic:tokens-and-setup} for bundler config examples.',
+          text: "If importing a swizzled component throws an error that starts `Unexpected 'stylex.create' call at runtime` and the page does not render, the app is missing a StyleX compiler. See the StyleX Build Setup section of {@link generic:tokens-and-setup} for bundler config examples.",
         },
       ],
     },

package/assets/docs/tree/add-a-component.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/add-a-component`: choose a
+ * @file `astryx docs cli/integrations/building-blocks/components/add-a-component`: choose a
  * component name and generate its first source and doc files.
  */
 

package/assets/docs/tree/add-a-theme.doc.mjs

@@ -44,7 +44,7 @@ Declare theme root ./themes in astryx.integration.mjs.
         },
         {
           type: 'prose',
-          text: "`oceanTheme.ts` exports `oceanTheme`, a `defineTheme` source. `oceanTheme.doc.mjs` describes it with `type: 'theme'`, `name`, `displayName`, `description`, and `maintained`; `theme list` shows its `name`, `description`, and `maintained`. The command also declares `./themes/ocean` and `./themes/ocean.css` package exports. Every descriptor field is in {@link generic:authoring}.",
+          text: '`oceanTheme.ts` exports `oceanTheme`, a `defineTheme` source, and `oceanTheme.doc.mjs` is the descriptor that `theme list` reads. The command also declares `./themes/ocean` and `./themes/ocean.css` package exports. Every field is in {@link schema:theme-doc}.',
         },
         {
           type: 'prose',

package/assets/docs/tree/add-a-topic.doc.mjs

@@ -1,9 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/docs/add-a-topic`: add a doc topic to an
- * integration package, write its sections, and pick the doc kind for each
- * thing the package ships.
+ * @file `astryx docs cli/integrations/building-blocks/docs/add-a-topic`: add a
+ * doc topic to an integration package, write its sections, and pick the doc
+ * kind for each thing the package ships.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -40,7 +40,7 @@ export const docs = {
           items: [
             'Name the topic in lowercase kebab-case, such as `deploying`. Readers type the name as a command argument, so it holds only letters, digits, `_`, and `-`.',
             'Keep the name stable: readers and links find the topic by it.',
-            'Pick a name no Core topic uses. To take over or add to a Core topic, see {@link generic:extend-or-replace}.',
+            'Pick a name that `astryx docs` does not already list: no Core topic, and no section such as `tokens` or `layout`. To take over or add to a Core topic, see {@link generic:extend-or-replace}.',
           ],
         },
       ],
@@ -59,13 +59,16 @@ export const docs = {
           label: 'docs/deploying.doc.mjs',
           code: "/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */\nexport default {\n  type: 'generic',\n  name: 'deploying',\n  title: 'Deploying',\n  description: 'Ship an app built with Acme widgets.',\n  sections: [{\n    id: 'build-before-you-ship',\n    title: 'Build before you ship',\n    content: [\n      {type: 'prose', text: 'Build the app, then upload the `dist` folder.'},\n      {type: 'code', lang: 'bash', code: 'npm run build'},\n      {type: 'list', style: 'unordered', items: ['Keep `dist` out of git.']},\n      {type: 'table', headers: ['Variable', 'Value'], rows: [['`NODE_ENV`', '`production`']]},\n    ],\n  }],\n};",
         },
+        {
+          type: 'prose',
+          text: 'The sample sets a section `id`, so `package.json` needs the CLI peer `"@astryxdesign/cli": ">=0.6.4"`. Published 0.6.3 and earlier reject `id` and hide every doc topic your package ships, and `integration verify` fails without that peer; see {@link generic:versioning}.',
+        },
         {
           type: 'list',
           style: 'unordered',
           items: [
-            'Content blocks are `prose`, `code`, `list`, and `table`, as shown; `heading`, with a `level` from 3 to 6 and a `text`; and `token-ref`, which inlines a token table from another topic.',
-            '`id` is optional: a stable key for the section. Without it, the key comes from the title. A stable CLI before 0.6.4 cannot read `id`; see {@link generic:versioning}.',
-            'Replace the `Overview` placeholder that `integration add` writes. Every field is in {@link generic:authoring}.',
+            'Replace the `Overview` placeholder that `integration add` writes.',
+            'Every field is in {@link schema:reference-doc}.',
           ],
         },
       ],

package/assets/docs/tree/agent-guidance.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/agent-guidance`: add short lines of
+ * @file `astryx docs cli/integrations/building-blocks/configuration/agent-guidance`: add short lines of
  * guidance that apps put in front of their AI agents, within the limits.
  */
 
@@ -121,7 +121,7 @@ export default {
           lang: 'bash',
           code: `npx astryx init --features agents
 # Or: --from takes the Core version the app had before
-npx astryx upgrade --from 0.7.0 --apply`,
+npx astryx upgrade --from <version> --apply`,
         },
         {
           type: 'code',

package/assets/docs/tree/block-template.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/document-the-template/block-template`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template/block-template`:
  * the block-only fields: component relationships and the preview shape.
  */
 
@@ -31,7 +31,7 @@ export const docs = {
           type: 'code',
           lang: 'javascript',
           label: 'templates/acme-stat-card.doc.mjs',
-          code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+          code: `/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */
 export default {
   type: 'block',
   name: 'acme-stat-card',
@@ -54,18 +54,8 @@ export default {
       title: 'Choose the component relationship',
       content: [
         {
-          type: 'reference',
-          target: 'schema:template-doc',
-          projection: {
-            fields: [
-              'exampleFor',
-              'alsoExampleFor',
-              'alsoShowcaseFor',
-              'componentsUsed',
-              'isShowcase',
-            ],
-          },
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:template-doc}.',
         },
         {
           type: 'prose',
@@ -75,7 +65,7 @@ export default {
           type: 'code',
           lang: 'javascript',
           label: 'templates/acme-status-card-showcase.doc.mjs',
-          code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+          code: `/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */
 export default {
   type: 'block',
   name: 'acme-status-card-showcase',
@@ -101,14 +91,12 @@ export default {
       title: 'Choose a useful preview',
       content: [
         {
-          type: 'reference',
-          target: 'schema:template-doc',
-          projection: {fields: ['aspectRatio']},
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:template-doc}.',
         },
         {
           type: 'prose',
-          text: 'Start from the value for the closest shape below, render the block at that ratio, and adjust it until it neither clips nor leaves large empty space. These are starting points, not contract defaults.',
+          text: 'Set `aspectRatio` from the value for the closest shape below, render the block at that ratio, and adjust it until it neither clips nor leaves large empty space. These are starting points, not contract defaults.',
         },
         {
           type: 'table',

package/assets/docs/tree/build-the-template.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/build-the-template`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template`:
  * author portable template source and every asset that source needs.
  */
 

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

@@ -91,8 +91,59 @@ docType:   boolean
               '`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.',
+        },
       ],
     },
     {

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, 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, 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` disagrees (`required_mismatch`). It reads props with your installed `typescript`; without it, it prints `[skip] Props not compared`',
+              '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',
@@ -68,23 +74,25 @@ export const docs = {
     },
     {
       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.',
           ],
         },
@@ -112,7 +120,7 @@ export const docs = {
         },
         {
           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}.',
         },
       ],
     },