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

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

@@ -0,0 +1,61 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs authoring`: everything for integration authors. The
+ * guides build, ship, and fix an integration package; the field reference
+ * covers every file it holds.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'authoring',
+  title: 'Authoring',
+  summary:
+    'Build an npm package that adds components, templates, themes, docs, and codemods to Astryx apps, and look up every field of every file it holds.',
+  keywords: [
+    'authoring',
+    'integration',
+    'integration package',
+    'make an integration',
+    'publish an integration',
+    'integration authoring',
+    'authoring reference',
+  ],
+  slots: {
+    guides: {
+      title: 'Build an integration',
+      accepts: {kinds: ['generic', 'namespace']},
+    },
+    reference: {
+      title: 'Reference',
+      accepts: {kinds: ['generic']},
+    },
+  },
+  blocks: [
+    {
+      type: 'prose',
+      text: 'In global mode: users can install your integration for their computer, beside the global CLI. It then applies in folders outside any project, and inside a project only if the project installs it. See {@link namespace:global} and {@link generic:global-integrations}.',
+    },
+    {
+      type: 'prose',
+      text: 'An integration is a way to share things with Astryx users: a package you own and maintain, built on a framework Astryx gives you. Publish one, many, or any mix, and people install it in one step. It works with the Astryx CLI alongside Core. See each kind under {@link namespace:building-blocks}.',
+    },
+    {
+      type: 'prose',
+      text: 'For example, ship a carousel as an integration. Any app that installs it can find it with `astryx search carousel`, and the CLI uses it like any Astryx Core component.',
+    },
+    {
+      type: 'prose',
+      text: 'An integration can also replace a built-in template or doc. To start, install `@astryxdesign/cli` and open {@link generic:quick-start}.',
+    },
+    {
+      type: 'prose',
+      text: 'Every field of every file you write for an integration is in {@link generic:field-reference}.',
+    },
+    {
+      type: 'prose',
+      text: "Every integration runs `astryx integration check --strict` in its own build: it is required, not optional, so a doc, prop, or link that stops matching the code fails your build instead of your users' apps. See {@link generic:checks}.",
+    },
+  ],
+};

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 authoring/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 authoring/building-blocks/templates/build-the-template`:
  * author portable template source and every asset that source needs.
  */
 

package/assets/docs/tree/building-blocks.doc.mjs

@@ -1,12 +1,12 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @file astryx docs cli/integrations/building-blocks — the kinds you can add. */
+/** @file astryx docs authoring/building-blocks — the kinds you can add. */
 
 /** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
 export const docs = {
   type: 'namespace',
   name: 'building-blocks',
-  placement: {parent: 'namespace:integrations', slot: 'guides', order: 20},
+  placement: {parent: 'namespace:authoring', slot: 'guides', order: 20},
   title: 'Building Blocks',
   summary:
     'Add components, templates, themes, docs, and codemods, and configure how it behaves.',
@@ -23,6 +23,10 @@ export const docs = {
     },
   },
   blocks: [
+    {
+      type: 'prose',
+      text: 'In global mode: every kind your package adds also applies outside projects when users install it for their computer, beside the global CLI; inside a project, only if the project installs it. See {@link namespace:global} and {@link generic:global-integrations}.',
+    },
     {
       type: 'prose',
       text: 'These are everything you can add to an integration. Mix them however you like. You are not limited to any one thing.',

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

@@ -0,0 +1,201 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs authoring/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: '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. It finds TypeScript the way the docs check does, TypeScript 7 included ({@link generic:check-your-docs}). Without a usable one it prints `[skip] Props not compared` and the reason.",
+            'Findings are warnings and leave the exit code at 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',
+            ],
+            [
+              '`default_mismatch`',
+              "The documented `default` differs from the literal default the component writes in its props destructuring, such as `size = 'md'`",
+              'Copy the default from the source, quoted as code: `default: "\'md\'"`. Quotes and spacing are ignored, and a default that is not a literal on either side (a constant, a call, prose) is not compared',
+            ],
+          ],
+        },
+      ],
+    },
+    {
+      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 authoring/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',
@@ -21,17 +22,29 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Run `doctor integration docs` in your package to check the docs tree, every link, and overlaps with Core topics. Pass a package name to check an installed package.',
+          text: 'Run `doctor integration docs` in your package to check the docs tree, every link, and overlaps with Core topics, and to list any passage two topics repeat. Pass a package name to check an installed package.',
         },
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx doctor integration docs\n# In an app, check an installed package\nnpx astryx doctor integration docs @acme/astryx-widgets',
+          code: 'astryx doctor integration docs\n# In an app, check an installed package\nastryx doctor integration docs @acme/astryx-widgets',
         },
         {
           type: 'code',
           lang: 'text',
-          code: 'Checking integration docs: @acme/astryx-widgets@1.0.0\n\n[ok] The docs tree and every link in these docs check out.\n\n[ok] No doc topics overlap with Core.',
+          code: 'Checking integration docs: @acme/astryx-widgets@1.0.0\n\n[ok] The docs tree and every link in these docs check out.\n\n[ok] No doc topics overlap with Core.\n[ok] No topic copies a passage from another.\n[ok] No filler phrases or low-density topics.',
+        },
+        {
+          type: 'prose',
+          text: 'Write each fact in one topic. When two of your topics, or one of yours and a Core topic, repeat 10 or more words of prose word for word, the check lists the pair as a `copied_passage` warning. It names the topic that keeps the text (a Core topic, or of your two the one the passage fits) and the line in the other where to put the link instead ({@link generic:links}). Code and examples are not compared, and a topic may carry the text of the Core topic it replaces. A run with fewer than 4 distinct content words (words other than function words such as \"the\", \"in\" or \"it\"), or one that three or more topics share (a series lead-in), is not listed. Each listed pair is also a warning (`copied_passage`): `doctor integration docs` still exits 0, and `integration check --strict` fails until you fix it.',
+        },
+        {
+          type: 'prose',
+          text: "Keep docs dense. The check lists, as a `doc_fluff` warning, each padding phrase in your prose, with its file line and what to write instead, and each topic of 80 or more prose words in which fewer than half the words carry content (words other than function words such as the, and, in), with its measured share and the floor of 0.5. `doctor integration docs` still exits 0, and `integration check --strict` fails until you cut it. Code, examples, and quoted text are not read. The phrases: `it\'s important to note`, `it is important to note`, `important to note that`, `it\'s worth noting`, `it is worth noting`, `worth noting that`, `it should be noted`, `please note`, `note that` (opening a sentence), `as mentioned above`, `as mentioned earlier`, `as mentioned before`, `as noted above`, `as you can see`, `needless to say`, `in order to`, `due to the fact that`, `for the purpose of`, `at this point in time`, `in other words`, `basically`, `essentially`, `obviously`.",
+        },
+        {
+          type: 'prose',
+          text: "Point at another doc with a link, never by writing `astryx docs <name>` in prose: `{@link generic:<name>}` for one of your package's topics, or `{@link @astryxdesign/cli:generic:<name>}` for a Core doc (`namespace:` for a Core namespace). The CLI prints the link as the command that opens the doc, and doctor checks that the doc exists. The check lists each written pointer to a doc that exists as a `stray_doc_pointer` warning, with the link to write instead. A command with more words, or one in a code block, is a walkthrough and is not listed.",
         },
         {
           type: 'prose',
@@ -45,7 +58,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 +79,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,18 +98,58 @@ 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: '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. Where `typescript` is missing or has no JavaScript compiler API, as TypeScript 7 does, it uses `@typescript/typescript6`, the TypeScript 6 API package, if your package installs it. Without either, it prints `[skip] Docs not type-checked` and the reason.',
+            'Every field of every doc type is in {@link generic:field-reference}.',
+          ],
+        },
+      ],
+    },
     {
       id: 'check-read-size',
       title: 'Check read size',
       content: [
         {
           type: 'prose',
-          text: '`npx astryx doctor` also measures every read and warns on one over 32 KB. Run it in your package or in an app that installs it; `doctor integration docs` does not check size.',
+          text: '`astryx doctor` also measures every read and warns on one over 32 KB. Run it in your package or in an app that installs it; `doctor integration docs` does not check size.',
         },
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx doctor',
+          code: 'astryx doctor',
         },
         {
           type: 'code',
@@ -115,7 +173,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx integration verify',
+          code: 'astryx integration verify',
         },
         {
           type: 'code',