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

package/clients/cli/commands/docs.mjs

@@ -10,6 +10,9 @@
  * contract: a topic returns its whole doc, and `--index` its sections.
  * Supports --detail (full|compact|brief) and --lang (en|zh|dense). A code
  * block's label prints above its fence, and table cells escape their pipes.
+ * Docs write commands as bare `astryx ...`; text output prefixes them with the
+ * project's invocation (prefixCliCommands, in formatBlock and the summaries),
+ * and JSON keeps them bare.
  *
  * Usage:
  *   astryx docs                          List available topics
@@ -25,6 +28,7 @@
 import {
   formatCliCommand,
   getCliInvocation,
+  prefixCliCommands,
 } from '../../../foundation/env/package-manager.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
 import {
@@ -96,12 +100,17 @@ function formatTableCompact(headers, rows) {
  * @returns {string | null}
  */
 export function formatBlock(block, detail) {
+  // Docs write commands as bare `astryx ...`; show them the way this project
+  // runs the CLI.
+  const stem = getCliInvocation();
+  /** @param {string} value */
+  const shown = value => prefixCliCommands(value, stem);
   switch (block.type) {
     case 'prose':
-      return block.text;
+      return shown(block.text);
 
     case 'heading':
-      return `${'#'.repeat(block.level || 3)} ${block.text}`;
+      return `${'#'.repeat(block.level || 3)} ${shown(block.text)}`;
 
     case 'code':
       if (detail === 'compact' || detail === 'brief') return null;
@@ -112,19 +121,29 @@ export function formatBlock(block, detail) {
         const label = block.label
           ? `${block.label.replace(/:\s*$/, '')}:\n`
           : '';
-        return `${label}\`\`\`${block.lang}\n${block.code}\n\`\`\``;
+        const body = prefixCliCommands(block.code, stem, block.lang);
+        return `${label}\`\`\`${block.lang}\n${body}\n\`\`\``;
       }
 
-    case 'table':
+    case 'table': {
+      // A cell that is a whole command, such as `astryx theme add neutral`
+      // written without backticks, is prefixed too.
+      /** @param {string} cell */
+      const shownCell = cell =>
+        /^astryx(\s|$)/.test(cell ?? '')
+          ? `${stem}${cell.slice('astryx'.length)}`
+          : shown(cell ?? '');
+      const rows = block.rows.map(row => row.map(shownCell));
       if (detail === 'brief') {
-        return block.rows
+        return rows
           .map(r => r.slice(0, 2).map(tableCell).join('='))
           .join(' | ');
       }
       if (detail === 'compact') {
-        return formatTableCompact(block.headers, block.rows);
+        return formatTableCompact(block.headers, rows);
       }
-      return formatTable(block.headers, block.rows);
+      return formatTable(block.headers, rows);
+    }
 
     case 'list': {
       const prefix =
@@ -135,7 +154,9 @@ export function formatBlock(block, detail) {
             : block.style === 'do'
               ? () => '+ '
               : () => '- ';
-      return block.items.map((item, i) => `${prefix(i)}${item}`).join('\n');
+      return block.items
+        .map((item, i) => `${prefix(i)}${shown(item)}`)
+        .join('\n');
     }
 
     default:
@@ -289,7 +310,7 @@ function formatTreeChild(child, detail, level, root, run, owner) {
     child.summary &&
     (child.kind === 'namespace' || child.kind === 'generic')
   ) {
-    parts.push(child.summary);
+    parts.push(prefixCliCommands(child.summary, run));
   }
   const content = formatTreeBlocks(child.content ?? [], detail, level - 2);
   if (content.length > 0) parts.push(content.join('\n\n'));
@@ -341,7 +362,7 @@ function emitTree(node, detail, childDetail, run) {
     .every(route => route.startsWith(`${node.route}/`));
   const root = allBelow ? node.route : '';
   emit(
-    section(node.title, wrapText(node.summary)),
+    section(node.title, wrapText(prefixCliCommands(node.summary, run))),
     record({package: node.package}),
     ...(node.content?.length
       ? [
@@ -427,9 +448,12 @@ function emitIndex(index, owner, run) {
     // Summaries wrap rather than being cut: the summary is how a reader picks
     // the one section to open. A section another package wrote says which one.
     records(
-      index.sections.map(s =>
-        s.package === owner ? s : {...s, title: `${s.title} (${s.package})`},
-      ),
+      index.sections.map(s => {
+        const shown = {...s, summary: prefixCliCommands(s.summary ?? '', run)};
+        return s.package === owner
+          ? shown
+          : {...shown, title: `${s.title} (${s.package})`};
+      }),
       {
         fields: ['id', 'title', 'summary'],
         layout: 'inline',
@@ -462,9 +486,10 @@ function childRow(child, owner) {
   return {
     // A child another package owns says which one.
     name: child.package === owner ? child.name : `${child.name} (${child.package})`,
-    summary: titleAddsIdentity
-      ? `${child.title}: ${child.summary}`
-      : child.summary,
+    summary: prefixCliCommands(
+      titleAddsIdentity ? `${child.title}: ${child.summary}` : child.summary,
+      getCliInvocation(),
+    ),
   };
 }
 
@@ -479,14 +504,19 @@ function childRow(child, owner) {
 function emitNode(node, detail, run) {
   if (node.kind === 'namespace') {
     emit(
-      section(node.title, wrapText(node.summary)),
+      section(node.title, wrapText(prefixCliCommands(node.summary, run))),
       record({package: node.package}),
-      // A namespace may author intro `blocks`; they render above its children.
+      // A namespace may author intro `blocks`; they render above its children,
+      // prose wrapped like the summary.
       ...(node.content?.length
         ? [
             text(
               node.content
-                .map(b => formatBlock(b, detail))
+                .map(b =>
+                  b.type === 'prose'
+                    ? wrapText(formatBlock(b, detail) ?? '')
+                    : formatBlock(b, detail),
+                )
                 .filter(Boolean)
                 .join('\n\n'),
             ),
@@ -505,7 +535,7 @@ function emitNode(node, detail, run) {
       text(
         [
           // A child's route is its parent's route and its name, except a flat
-          // topic in the Unorganized level, which keeps its own name.
+          // topic in a topic level, which keeps its own name.
           node.slots.every(slot =>
             slot.children.every(child => child.route.startsWith(`${node.route}/`)),
           )

package/clients/cli/commands/docs.test.mjs

@@ -113,7 +113,7 @@ describe('progressive reads', () => {
     expect(stdout).toMatch(/^principles +\S/m);
     expect(widest(stdout)).toBeLessThanOrEqual(120);
     // The repo root has no `astryx` bin, so the CLI names the scoped package.
-    expect(stdout).toMatch(/Usage: \S+(?: dlx)? (?:astryx|@astryxdesign\/cli) docs <topic>/);
+    expect(stdout).toMatch(/Usage: \S+(?: dlx)? (?:astryx|@astryxdesign\/cli(?:@\S+)?) docs <topic>/);
   }, SLOW);
 
   it("prints a topic's section index with the keys to read by", async () => {
@@ -227,7 +227,7 @@ describe('the docs tree, one level at a time', () => {
   it('wraps namespace summaries without discarding searchable words', async () => {
     const {status, stdout} = await runCli([
       'docs',
-      'cli/integrations/building-blocks/templates',
+      'authoring/building-blocks/templates',
     ]);
     expect(status).toBe(0);
     expect(stdout).toMatch(/^start-a-template +Help others build apps faster/m);
@@ -255,7 +255,7 @@ describe('the docs tree, one level at a time', () => {
     const {status, stdout} = await runCli(['docs', 'cli/api/functions/search']);
     expect(status).toBe(0);
     expect(stdout).toMatch(/^## search\(\)/m);
-    expect(stdout).toContain('Read it with `astryx docs cli/commands/search`.');
+    expect(stdout).toMatch(/Read it with `.+ docs cli\/commands\/search`\./);
     expect(stdout).toMatch(/Up: .*docs cli\/api\/functions$/m);
   }, SLOW);
 
@@ -274,8 +274,8 @@ describe('the docs tree, one level at a time', () => {
   }, SLOW);
 
   it('reads the integration guides by their routes, and not by the old name', async () => {
-    // cli/integrations is a namespace: one level, its guides by slot.
-    const level = await runCli(['docs', 'cli/integrations']);
+    // authoring is a namespace: one level, its guides by slot.
+    const level = await runCli(['docs', 'authoring']);
     expect(level.status).toBe(0);
     expect(level.stdout).toMatch(
       /^quick-start +Create a new integration package/m,
@@ -283,42 +283,42 @@ describe('the docs tree, one level at a time', () => {
     expect(level.stdout).toMatch(/^building-blocks +/m);
     const guide = await runCli([
       'docs',
-      'cli/integrations/building-blocks/codemods',
+      'authoring/building-blocks/codemods',
       '--index',
     ]);
     expect(guide.status).toBe(0);
     expect(guide.stdout).toMatch(
-      /Read one section: .*docs cli\/integrations\/building-blocks\/codemods <section>/,
+      /Read one section: .*docs authoring\/building-blocks\/codemods <section>/,
     );
     // A bare read is one level too: the sections, and how to read it all.
     const bare = await runCli([
       'docs',
-      'cli/integrations/building-blocks/codemods',
+      'authoring/building-blocks/codemods',
     ]);
     expect(bare.status).toBe(0);
     expect(bare.stdout).toBe(guide.stdout);
     expect(bare.stdout).toMatch(
-      /Read everything: +.*docs cli\/integrations\/building-blocks\/codemods --full$/m,
+      /Read everything: +.*docs authoring\/building-blocks\/codemods --full$/m,
     );
     const one = await runCli([
       'docs',
-      'cli/integrations/building-blocks/codemods',
+      'authoring/building-blocks/codemods',
       'which-codemods-run',
     ]);
     expect(one.status).toBe(0);
     expect(one.stdout).toMatch(/^## Choose when a codemod runs$/m);
     expect(one.stdout).toMatch(
-      /^Up: .*docs cli\/integrations\/building-blocks\/codemods --index$/m,
+      /^Up: .*docs authoring\/building-blocks\/codemods --index$/m,
     );
     expect(one.stdout).toMatch(
-      /^Previous: .*docs cli\/integrations\/building-blocks\/codemods write-the-transform$/m,
+      /^Previous: .*docs authoring\/building-blocks\/codemods write-the-transform$/m,
     );
     expect(one.stdout).toMatch(
-      /^Next: .*docs cli\/integrations\/building-blocks\/codemods run-codemods-in-an-app$/m,
+      /^Next: .*docs authoring\/building-blocks\/codemods run-codemods-in-an-app$/m,
     );
     const full = await runCli([
       'docs',
-      'cli/integrations/building-blocks/codemods',
+      'authoring/building-blocks/codemods',
       '--full',
     ]);
     expect(full.status).toBe(0);
@@ -343,11 +343,11 @@ describe('the docs tree, one level at a time', () => {
       type: 'docs.detail.section',
       data: {id: 'side-panels', title: 'Side panels'},
     });
-    const missing = await runCli(['docs', 'cli', 'zzzz-nope', '--json']);
+    const missing = await runCli(['docs', 'authoring', 'zzzz-nope', '--json']);
     expect(missing.status).toBe(1);
     const error = JSON.parse(missing.stdout);
     expect(error).toMatchObject({code: 'ERR_UNKNOWN_SECTION'});
-    expect(error.suggestions.map(s => s.name)).toContain('cli/integrations/quick-start');
+    expect(error.suggestions.map(s => s.name)).toContain('authoring/quick-start');
   }, SLOW);
 });
 

package/clients/cli/commands/doctor-integration-components.doc.mjs

@@ -8,7 +8,8 @@ export const doc = {
   name: 'doctor integration components',
   displayName: 'astryx doctor integration components',
   namespace: 'cli/commands',
-  summary: 'Check integration component names and replacements against Core',
+  summary:
+    'Check integration component names, replacements, and documented props',
   description:
     'Compares one local or installed integration with Core component names. A ' +
     'conflict is allowed and exits successfully, but the report recommends ' +
@@ -17,7 +18,17 @@ export const doc = {
     'range that turns replacement on, a missing Core target, an invalid value, a ' +
     'component named after a different Core component, or two replacements for one ' +
     'Core component is an error. In a package without that range they are warnings, ' +
-    'with a warning for each such component, naming the range to declare.',
+    'with a warning for each such component, naming the range to declare. ' +
+    "Then it compares each component doc's props with the component's TypeScript " +
+    "props, using the project's own `typescript` (or, where `typescript` is missing or " +
+    'has no JavaScript compiler API, as TypeScript 7 does, the `@typescript/typescript6` ' +
+    'it installs), and warns about a documented prop ' +
+    'the code lacks, a prop the package declares that the doc omits, a wrong ' +
+    '`required`, and a type that does not match where both sides read exactly ' +
+    '(it lists every other documented type as not compared, with the reason). ' +
+    'Without TypeScript it prints one ' +
+    'line saying the comparison was skipped. It also warns on each `{@link}` in ' +
+    "a component doc's text that names no doc.",
   fn: 'integrationComponentConflicts',
   args: [
     {
@@ -29,16 +40,20 @@ export const doc = {
     },
   ],
   examples: [
-    {label: 'Check the local integration', cli: 'astryx doctor integration components'},
+    {
+      label: 'Check the local integration',
+      cli: 'astryx doctor integration components',
+    },
     {
       label: 'Check an installed integration',
       cli: 'astryx doctor integration components @acme/widgets --json',
     },
   ],
+  outsideProject: 'same',
   exitCodes: [
     {
       code: 0,
-      when: 'the check completed; component name conflicts, and replaces findings for a package without the CLI range, are warnings',
+      when: 'the check completed; component name conflicts, replaces findings for a package without the CLI range, props that differ from the code, and links that name no doc are warnings',
     },
     {
       code: 1,

package/clients/cli/commands/doctor-integration-docs.doc.mjs

@@ -8,12 +8,17 @@ export const doc = {
   name: 'doctor integration docs',
   displayName: 'astryx doctor integration docs',
   namespace: 'cli/commands',
-  summary: 'Check an integration\'s docs: the docs tree they add, every link, and overlaps with Core topics',
+  summary:
+    "Check an integration's docs: the docs tree they add, every link, and overlaps with Core topics",
   description:
     'Checks the docs tree the package adds, every link in its docs, and overlaps with Core topics. ' +
     'Intentional replacements and extensions are information. ' +
     'A same-name topic without `replaces` or `extends` is an accidental conflict ' +
-    'and fails until the author declares the relationship or renames it. See {@link generic:check-your-docs}.',
+    'and fails until the author declares the relationship or renames it. ' +
+    'It also lists each pair of topics (two of the package, or one of them and a Core topic other than the one it replaces) ' +
+    'that repeat 10 or more words of prose word for word, each padding phrase and low-density topic, ' +
+    'and each written `astryx docs <name>` that should be a link, ' +
+    'each as a warning (`copied_passage`, `doc_fluff`, `stray_doc_pointer`; exit 0, and `integration check --strict` fails on it). See {@link generic:check-your-docs}.',
   fn: 'integrationDocConflicts',
   args: [
     {
@@ -25,15 +30,25 @@ export const doc = {
     },
   ],
   examples: [
-    {label: 'Check the local integration', cli: 'astryx doctor integration docs'},
+    {
+      label: 'Check the local integration',
+      cli: 'astryx doctor integration docs',
+    },
     {
       label: 'Check an installed integration',
       cli: 'astryx doctor integration docs @acme/widgets --json',
     },
   ],
+  outsideProject: 'same',
   exitCodes: [
-    {code: 0, when: 'all Core overlaps are explicitly declared or no overlap exists'},
-    {code: 1, when: 'an overlap is accidental, a doc is invalid, a namespace or placement fails, or a reference block cannot include what it names. A link that names no doc is a warning, and does not change the exit code'},
+    {
+      code: 0,
+      when: 'all Core overlaps are explicitly declared or no overlap exists',
+    },
+    {
+      code: 1,
+      when: 'an overlap is accidental, a doc is invalid, a namespace or placement fails, or a reference block cannot include what it names. A link that names no doc is a warning, and does not change the exit code',
+    },
   ],
   related: ['doctor integration validate', 'docs'],
 };

package/clients/cli/commands/doctor-integration-templates.doc.mjs

@@ -37,6 +37,7 @@ export const doc = {
       cli: 'astryx doctor integration templates @acme/widgets --json',
     },
   ],
+  outsideProject: 'same',
   exitCodes: [
     {
       code: 0,

package/clients/cli/commands/doctor-integration-validate.doc.mjs

@@ -14,7 +14,17 @@ export const doc = {
   description:
     'Validates one integration at a time: the local package rooted at cwd, or an ' +
     'installed package resolved by name. It schema-checks the manifest, verifies ' +
-    'every declared contribution root, and reports every finding. Safe as a CI gate.',
+    'every declared contribution root, and reports every finding. Safe as a CI gate. ' +
+    'It then checks every doc the package ships under its roots against the ' +
+    "published authoring type for its kind, with the project's own `typescript` (or, " +
+    'where `typescript` is missing or has no JavaScript compiler API, as TypeScript 7 ' +
+    'does, the `@typescript/typescript6` it installs), and ' +
+    'warns about each field that does not match, naming the field and a fix. A doc ' +
+    'it cannot fully check is listed with the reason, and test fixtures under ' +
+    '`__tests__` in the components or docs root are counted, not checked. Without ' +
+    'TypeScript it prints one line saying the docs were not type-checked. ' +
+    'Outside a package, with no package name it writes nothing and reports one no_package issue (exit 1); ' +
+    'a package name is looked up as it is in a project.',
   fn: 'validateIntegration',
   args: [
     {
@@ -35,9 +45,19 @@ export const doc = {
       cli: 'astryx doctor integration validate @acme/widgets --json',
     },
   ],
+  outsideProject: 'own',
   exitCodes: [
-    {code: 0, when: 'no error-severity issues (warnings are allowed)'},
+    {
+      code: 0,
+      when: 'no error-severity issues (warnings, including doc type findings, are allowed)',
+    },
     {code: 1, when: 'one or more error-severity issues'},
   ],
   related: ['doctor integration templates', 'template'],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a package, with no package named, it writes nothing, reports one `no_package` issue, and exits 1; a package name is looked up as it is in a project. In a project, the project's version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:global-integrations}.",
+    },
+  ],
 };