@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

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

@@ -1,137 +0,0 @@
-// 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.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
-  type: 'generic',
-  name: 'check-your-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.',
-  sections: [
-    {
-      id: 'run-the-docs-check',
-      title: 'Run the docs check',
-      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.',
-        },
-        {
-          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',
-        },
-        {
-          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.',
-        },
-        {
-          type: 'prose',
-          text: 'Its arguments and exit codes are in {@link command:doctor integration docs}.',
-        },
-      ],
-    },
-    {
-      id: 'know-what-fails-the-check',
-      title: 'Know what fails the check',
-      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.',
-        },
-        {
-          type: 'table',
-          headers: ['Problem', 'Reported as', 'Exit code'],
-          rows: [
-            [
-              'A doc that does not load, such as an unknown section field or block type',
-              '`[fail]` `invalid_doc`',
-              '1',
-            ],
-            [
-              "A topic with a Core topic's name and no `replaces` or `extends`",
-              '`[fail]` `accidental`',
-              '1',
-            ],
-            [
-              'A placement that fails, which hides the doc',
-              '`[fail]` `invalid_doc_graph`',
-              '1',
-            ],
-            ['A link that names no doc', '`[warn]` `invalid_doc_graph`', '0'],
-            [
-              'A topic that sets `replaces` or `extends`',
-              '`[info]` `replaces` or `extends`',
-              '0',
-            ],
-          ],
-        },
-        {
-          type: 'prose',
-          text: 'Read the warnings before you publish. With `--json`, they are in `data.issues`, with `severity: "warning"`.',
-        },
-      ],
-    },
-    {
-      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.',
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          code: 'npx astryx doctor',
-        },
-        {
-          type: 'code',
-          lang: 'text',
-          code: 'id:      docs-progressive-disclosure\nstatus:  [warn]\nlabel:   Documentation navigation and size\nmessage: acme/deploying build-before-you-ship: 46 KB, over the 32 KB one read may return',
-        },
-        {
-          type: 'prose',
-          text: 'Split a section over the limit into smaller ones, each with its own key. See {@link command:doctor}.',
-        },
-      ],
-    },
-    {
-      id: 'check-the-cli-peer',
-      title: 'Check the CLI peer',
-      content: [
-        {
-          type: 'prose',
-          text: '`integration verify` fails a package that ships a docs section, a placed guide, or a doc section with an `id` without an `@astryxdesign/cli` peer of `>=0.7.0`. It does not run the docs check, so run both.',
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          code: 'npx astryx integration verify',
-        },
-        {
-          type: 'code',
-          lang: 'text',
-          code: '- [fail] The package ships a namespace doc or a placed guide but declares no @astryxdesign/cli peer. A stable CLI before 0.7.0 does not read the docs tree, and can hide every doc topic the package ships. Declare "@astryxdesign/cli": ">=0.7.0" in peerDependencies (optional in peerDependenciesMeta, if the CLI is not required).',
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            '`integration add doc --parent` writes the peer for you.',
-            '`integration verify` passes a hidden guide and an accidental Core overlap; only `doctor integration docs` catches them.',
-            'Everything else it checks is in {@link command:integration verify} and {@link generic:checks}.',
-          ],
-        },
-      ],
-    },
-  ],
-};

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

@@ -1,119 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/integrations/checks`: what each package check
- * proves, what fails and what only warns, and one command to run them all.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
-  type: 'generic',
-  name: 'checks',
-  placement: {parent: 'namespace:ship', slot: 'guides', order: 20},
-  title: 'Check an integration',
-  category: 'guide',
-  keywords: ['check before publishing', 'validate an integration', 'ci'],
-  description:
-    'Pick the check for each problem, learn what fails and what only warns, and run every check in CI.',
-  sections: [
-    {
-      id: 'pick-a-check',
-      title: 'Pick a check',
-      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.',
-        },
-        {
-          type: 'table',
-          headers: ['Command', 'Proves', 'Exits 1 when', 'Only warns when'],
-          rows: [
-            [
-              '`npx astryx doctor integration validate`',
-              'The manifest loads, and each root holds contributions the CLI can read',
-              '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',
-            ],
-            [
-              '`npx astryx doctor integration components`',
-              'No component name clashes with a Core component',
-              'Core is not installed (`core_not_found`)',
-              'A name clashes with Core',
-            ],
-            [
-              '`npx astryx doctor integration templates`',
-              'Each `replaces` names a Core template of the same type',
-              'A `replaces` target is missing (`missing_template_replacement_target`) or of the other type (`invalid_template_replacement`), or two templates replace one id (`ambiguous_template_replacement`)',
-              'A template id matches a Core id without `replaces`',
-            ],
-            [
-              '`npx astryx doctor integration docs`',
-              'Your docs tree, every link, and topic names against Core',
-              '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 verify`',
-              'The packed package holds every file, shows the same contributions, resolves every public import, and declares the CLI it needs',
-              'Anything `validate` fails on, no manifest, a file left out of the `.tgz` file, an import that does not resolve, or a missing CLI peer',
-              'Anything `validate` warns about',
-            ],
-          ],
-        },
-        {
-          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.',
-        },
-      ],
-    },
-    {
-      id: 'run-every-check-in-ci',
-      title: 'Run every check in CI',
-      content: [
-        {
-          type: 'prose',
-          text: 'Chain the five checks so the first failure stops the run. Install devDependencies first, because the components check needs Core.',
-        },
-        {
-          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',
-        },
-        {
-          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.',
-            'Bare `npx astryx doctor` in the package also warns about a doc section over 32 KB, which no check above measures.',
-          ],
-        },
-      ],
-    },
-    {
-      id: 'what-integration-verify-does',
-      title: 'Verify the packed package',
-      content: [
-        {
-          type: 'prose',
-          text: '`integration verify` packs your package with npm, unpacks it into a temporary app, and checks that the app sees everything your source has. It publishes nothing and leaves no `.tgz` file or temporary folder behind.',
-        },
-        {
-          type: 'list',
-          style: 'ordered',
-          items: [
-            '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 fails a package that ships a docs section, a placed guide, a template `replaces`, a doc section with an `id`, or a theme without an `@astryxdesign/cli` peer of `>=0.7.0`.',
-          ],
-        },
-        {
-          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}.',
-        },
-      ],
-    },
-  ],
-};

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

@@ -1,147 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/integrations/codemods`: add codemods to an
- * integration package, and know which of them `astryx upgrade` runs in an app.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
-  type: 'generic',
-  name: 'codemods',
-  placement: {parent: 'namespace:building-blocks', slot: 'guides', order: 50},
-  title: 'Codemods',
-  category: 'guide',
-  keywords: ['breaking change', 'migrate apps', 'integration codemod'],
-  description:
-    'Ship codemods that `astryx upgrade` runs to migrate app code, and know which of them an app runs.',
-  sections: [
-    {
-      id: 'add-a-codemod',
-      title: 'Add a codemod',
-      content: [
-        {
-          type: 'prose',
-          text: '`integration add codemod` writes a codemod into a folder named after a version. Apps run it with `astryx upgrade` to migrate their code.',
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          code: 'npx astryx integration add codemod rename-delay --to 0.7.0',
-        },
-        {
-          type: 'code',
-          lang: 'text',
-          code: `codemods/
-  0.7.0/
-    rename-delay.mjs         # the codemod
-    rename-delay.test.mjs    # skipped: a test file
-    __tests__/               # skipped: a test folder`,
-        },
-        {
-          type: 'prose',
-          text: "The first add declares `codemods: './codemods'` in `astryx.integration.mjs`. The codemod's id is its path inside the version folder, without the extension: `rename-delay`. An id must be unique across all version folders in the package.",
-        },
-        {
-          type: 'prose',
-          text: 'The loader skips `*.test.*`, `*.spec.*`, and `*.fixture.*` files and everything under `__tests__/` or `__fixtures__/`, so tests can sit beside the codemod. The folder name decides when an app runs the codemod; see "Choose when a codemod runs".',
-        },
-      ],
-    },
-    {
-      id: 'write-the-transform',
-      title: 'Write the transform',
-      content: [
-        {
-          type: 'prose',
-          text: 'A codemod default-exports a plain object with a `type`, a `title`, and a `transform` function. `transform` returns the new source, or `null` to leave the file as it is.',
-        },
-        {
-          type: 'code',
-          lang: 'js',
-          code: `// codemods/0.7.0/rename-delay.mjs
-/** @type {import('@astryxdesign/cli/authoring').AstryxCodemod} */
-export default {
-  type: 'code',
-  title: 'Rename AcmeCarousel delay to interval',
-  description: 'Renames the delay prop on AcmeCarousel.',
-  fileExtensions: ['.tsx', '.jsx'],
-  transform(file, api) {
-    const j = api.jscodeshift;
-    const root = j(file.source);
-    const props = root
-      .find(j.JSXOpeningElement, {name: {name: 'AcmeCarousel'}})
-      .find(j.JSXAttribute, {name: {name: 'delay'}});
-    if (props.size() === 0) return null;
-    props.forEach(path => {
-      path.node.name.name = 'interval';
-    });
-    return root.toSource();
-  },
-};`,
-        },
-        {
-          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}.",
-        },
-      ],
-    },
-    {
-      id: 'which-codemods-run',
-      title: 'Choose when a codemod runs',
-      content: [
-        {
-          type: 'prose',
-          text: "Two rules decide whether an app's `astryx upgrade` runs your codemods: the app's Core versions, and whether the app names your package.",
-        },
-        {
-          type: 'list',
-          style: 'ordered',
-          items: [
-            "Version folders are matched against the app's `@astryxdesign/core` versions, not your package's version. `upgrade --from <version>` runs each folder above `--from`, up to and including the Core version installed in the app. With Core 0.7.0 installed, `--from 0.6.3` runs `0.7.0/`, and `--from 0.7.0` runs nothing. A folder named after your own release, such as `1.0.0/`, waits until the app has Core 1.0.0.",
-            '`upgrade` runs your codemods only when the app lists your package in `integrations` in its `astryx.config`, or passes `--integration @acme/astryx-widgets`. Having your package installed is not enough: the run then skips your codemods with no warning.',
-          ],
-        },
-      ],
-    },
-    {
-      id: 'run-codemods-in-an-app',
-      title: 'Run codemods in an app',
-      content: [
-        {
-          type: 'prose',
-          text: 'An app previews codemods with `astryx upgrade` and writes the changes with `--apply`. Without `--apply`, nothing on disk changes.',
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          code: `# Preview each codemod and the files it would change
-npx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets
-# Write the changes
-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)
-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`.",
-        },
-        {
-          type: 'prose',
-          text: '`--from` is the Core version the app had before it upgraded. The run scans `./src` unless the app passes `--path`, and it never writes a file the app marks as generated, vendored, or ignored; see {@link command:upgrade}. `upgrade --list` shows only Core codemods.',
-        },
-        {
-          type: 'prose',
-          text: "An integration manifest has no `hooks` field. Commands that run after codemods, such as a formatter, are the app's to set, in `hooks.postCodemod` in its `astryx.config`.",
-        },
-      ],
-    },
-  ],
-};

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

@@ -1,113 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/integrations/components/describe-the-component/component-family`:
- * author one ComponentDoc for several public exports in a component family.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
-  type: 'generic',
-  name: 'component-family',
-  placement: {
-    parent: 'namespace:describe-the-component',
-    slot: 'guides',
-    order: 30,
-  },
-  title: 'Component family',
-  category: 'guide',
-  description:
-    'Adapt a single-component doc when one module exposes several public components or hooks that belong to one family.',
-  sections: [
-    {
-      id: 'choose-the-family-shape',
-      title: 'Choose the family shape',
-      content: [
-        {
-          type: 'prose',
-          text: 'Start with a complete single-component doc. Convert its top-level `props` into a `components` array only when one source module or component directory exposes several public components or hooks as one family. The family doc keeps the shared usage guidance; each array entry owns one public export.',
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            'Put the primary or most-used export first.',
-            'Use a full entry when this file owns that export\'s description and signature.',
-            'Use `props` for a component entry. Use `params` and `returns` for a hook entry.',
-            'Do not add private implementation helpers or exports that people should not use directly.',
-          ],
-        },
-        {
-          type: 'reference',
-          target: 'schema:component-doc',
-          projection: {fields: ['components']},
-          presentation: 'full',
-        },
-      ],
-    },
-    {
-      id: 'document-the-family-inline',
-      title: 'Document the family inline',
-      content: [
-        {
-          type: 'code',
-          lang: 'javascript',
-          label: 'components/AcmeTabs.doc.mjs',
-          code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
-export default {
-  type: 'component',
-  name: 'AcmeTabs',
-  displayName: 'Acme Tabs',
-  import: '@acme/astryx-widgets/components/AcmeTabs',
-  usage: {
-    description:
-      'Switches between related views without leaving the page.',
-  },
-  components: [
-    {
-      name: 'AcmeTabs',
-      displayName: 'Acme Tabs',
-      description: 'Owns selection and lays out the tab list and panels.',
-      props: [
-        {
-          name: 'value',
-          type: 'string',
-          description: 'The selected tab value.',
-          required: true,
-        },
-      ],
-    },
-    {
-      name: 'AcmeTab',
-      displayName: 'Acme Tab',
-      description: 'Selects one view in Acme Tabs.',
-      props: [
-        {
-          name: 'value',
-          type: 'string',
-          description: 'The value this tab selects.',
-          required: true,
-        },
-      ],
-    },
-  ],
-};`,
-        },
-        {
-          type: 'prose',
-          text: 'The public module named by `import` must export every component or hook named by a full entry.',
-        },
-      ],
-    },
-    {
-      id: 'give-a-member-its-own-file',
-      title: 'Give a member its own file',
-      content: [
-        {
-          type: 'prose',
-          text: 'When one family member needs its own doc, replace its full entry with `{name: \'MemberName\'}` and move the details into a sibling doc. The parent keeps the family relationship without copying the child\'s content. Continue with {@link generic:subcomponent}.',
-        },
-      ],
-    },
-  ],
-};

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

@@ -1,69 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/integrations/components/component-imports`: make an
- * integration component's documented import resolve from the packed package.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
-  type: 'generic',
-  name: 'component-imports',
-  placement: {parent: 'namespace:components', slot: 'guides', order: 30},
-  title: 'Resolve the import',
-  category: 'guide',
-  description:
-    'Keep the component doc import and package exports map aligned, then verify the packed package.',
-  sections: [
-    {
-      id: 'export-the-component',
-      title: 'Export the component',
-      content: [
-        {
-          type: 'prose',
-          text: 'Apps copy the component doc\'s `import` field into their code, so that exact specifier must resolve from your packed package. `integration add` writes it together with an `exports` entry in package.json.',
-        },
-        {
-          type: 'code',
-          lang: 'json',
-          label: 'package.json',
-          code: `"exports": {
-  "./components/AcmeCarousel": "./components/AcmeCarousel.tsx"
-}`,
-        },
-        {
-          type: 'prose',
-          text: 'Add writes the entry only when package.json already has an `exports` map, so start every package with `"exports": {}`.',
-        },
-      ],
-    },
-    {
-      id: 'verify-the-packed-import',
-      title: 'Verify the packed import',
-      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.',
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          code: 'npx astryx integration verify',
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            '`component_import_unresolvable` means the exports map has no entry for the documented import.',
-            '`component_export_missing` means the module does not export the documented name, or package.json has no exports map.',
-            '`typescript_extension_in_specifier` means the public import ends in `.ts` or `.tsx`.',
-          ],
-        },
-        {
-          type: 'prose',
-          text: 'To import from the package root, set `import: \'@acme/astryx-widgets\'` and re-export the component from the file that `exports["."]` points to. See {@link command:integration verify}.',
-        },
-      ],
-    },
-  ],
-};