@astryxdesign/cli 0.7.2-canary.ebcc404 → 0.7.2-canary.f8f7cf1

package/README.md

@@ -476,10 +476,11 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `doctor`                          | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and an optional fix, always present on warn and fail) plus a `summary` of counts per status.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `integration.add`                 | A contribution-writer receipt: kind, name, optional root {path, created}, integration-manifest path, every affected project-relative path, written, and dryRun.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `integration.pack-check`          | The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}].                                                                                                                                                                                                                                                                    |
-| `integration.validate`            | The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}.                                                                                                                                                                                                                                                                                     |
+| `integration.validate`            | The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}. When the manifest loads, docTypes checks each doc against its published authoring type: status (checked \| skipped), reason, typescript, docs, findings (all warnings, each naming the field and a fix), unchecked, and fixtures (test fixture docs not checked).                   |
 | `integration.template-conflicts`  | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}.                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `integration.component-conflicts` | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command.                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `integration.component-conflicts` | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command. When the manifest loads and declares a components root, propDrift compares documented props with the TypeScript props: status (checked \| skipped), reason, typescript, components, typesCompared, typesSkipped, findings (all warnings), unchecked, typesNotCompared, and propsNotChecked.                                                                                                                                |
 | `integration.doc-conflicts`       | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`).                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `integration.check`               | Every source check of an integration package in one result: validated (false when no integration manifest was found, so nothing was checked), the package name and version, strict, and checks, one entry per check (validate, components, templates, docs), each with check, errors, warnings, skipped, failed, and response, the envelope that check returns on its own. The totals are errors, warnings, and skipped; unchecked counts what the checks could not compare. With --strict, failures lists each warning and each piece of skipped work again as an error, in the issue format the checks use; it is empty without --strict. failed decides the exit code.                                     |
 
 <!-- END GENERATED: response-types -->
 <!-- Generated by scripts/generate-cli-readme.mjs from the response-types EnumDoc. Run `pnpm -F @astryxdesign/cli readme`. -->
@@ -551,12 +552,12 @@ data: { checks, summary } }`) that AI agents and scripts can parse.
 Omit `[package]` to inspect the package at the current directory, or pass an
 installed package name:
 
-| Command                                   | What it checks                                               | Exit `1` when                                           |
-| ----------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------- |
-| `doctor integration validate [package]`   | Manifest shape and every declared contribution               | A structural issue has error severity                   |
-| `doctor integration templates [package]`  | Template IDs shared with Core                                | The integration is invalid; ID conflicts are warnings   |
-| `doctor integration components [package]` | Component names shared with Core                             | The integration is invalid; name conflicts are warnings |
-| `doctor integration docs [package]`       | Core topic replacements, extensions, and same-name conflicts | A Core overlap is accidental or the docs are invalid    |
+| Command                                   | What it checks                                                                      | Exit `1` when                                                                |
+| ----------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `doctor integration validate [package]`   | Manifest shape and every declared contribution                                      | A structural issue has error severity                                        |
+| `doctor integration templates [package]`  | Template IDs shared with Core                                                       | The integration is invalid; ID conflicts are warnings                        |
+| `doctor integration components [package]` | Component names shared with Core, and each props table against the TypeScript props | The integration is invalid; name conflicts and prop differences are warnings |
+| `doctor integration docs [package]`       | Core topic replacements, extensions, and same-name conflicts                        | A Core overlap is accidental or the docs are invalid                         |
 
 Template and component conflicts include the exact `--package` command needed
 to select the integration contribution. Doc replacements and extensions are

package/api/build/help/help.mjs

@@ -63,7 +63,7 @@ export function buildHelp() {
         "Keep the template's page frame, gap, and padding values. Replace its data, copy, and sections.",
         'No <div>/raw HTML for layout — use VStack/HStack/Grid/Stack/Card etc.',
         'No style={{}} — use component props, and design tokens for values.',
-        "Wrap the app in <Theme theme={...}> (import {Theme} from '@astryxdesign/core') and import core reset.css + astryx.css.",
+        "Wrap the app in <Theme theme={...}> (import {Theme} from '@astryxdesign/core/theme') and import core reset.css + astryx.css.",
       ],
       related: [
         {

package/api/component/_adapter.d.mts

@@ -231,6 +231,20 @@ export function scopeSubComponent(docs: LoadedComponentDoc, dirName: string, cor
     };
     matchingComponent: any;
 } | null;
+/**
+ * The doc an integration owner shows for `dirName`: when `dirName` is a member
+ * its family doc lists under its own name (`AcmeSlide` in an `AcmeCarousel`
+ * doc), the doc scoped to that member as {@link scopeSubComponent} scopes
+ * Core's, keeping the import the family doc states; otherwise `docs` itself.
+ * @param {LoadedComponentDoc} docs
+ * @param {OwnershipSubject} owner
+ * @param {string} dirName
+ * @returns {LoadedComponentDoc & {parentDoc?: string, import?: string}}
+ */
+export function scopeIntegrationMember(docs: LoadedComponentDoc, owner: OwnershipSubject, dirName: string): LoadedComponentDoc & {
+    parentDoc?: string;
+    import?: string;
+};
 /**
  * Internal ambiguity marker. Single-component callers still receive the same
  * AstryxError code, message, and suggestions; batch callers can additionally

package/api/component/_adapter.mjs

@@ -33,6 +33,9 @@ import {
   findComponentSource,
   findExternalComponentDoc,
   findIntegrationComponent,
+  integrationMemberEntry,
+  isIntegrationMember,
+  recordedDocName,
   resolveImportPath,
   resolveIntegrationImportPath as resolveIntegrationImport,
   unscopedComponentOwners,
@@ -621,3 +624,48 @@ export function scopeSubComponent(docs, dirName, coreDir) {
 
   return {scoped, matchingComponent};
 }
+
+/**
+ * The doc an integration owner shows for `dirName`: when `dirName` is a member
+ * its family doc lists under its own name (`AcmeSlide` in an `AcmeCarousel`
+ * doc), the doc scoped to that member as {@link scopeSubComponent} scopes
+ * Core's, keeping the import the family doc states; otherwise `docs` itself.
+ * @param {LoadedComponentDoc} docs
+ * @param {OwnershipSubject} owner
+ * @param {string} dirName
+ * @returns {LoadedComponentDoc & {parentDoc?: string, import?: string}}
+ */
+export function scopeIntegrationMember(docs, owner, dirName) {
+  const record = {name: dirName, docPath: owner.docPath ?? null};
+  if (!isIntegrationMember(record)) return docs;
+  const entry = integrationMemberEntry(docs, record);
+  // The files list the member but the doc this process loaded has no entry
+  // for it (the doc changed after it loaded): never answer with the family.
+  if (entry == null) {
+    throw new AstryxError(
+      `No component named "${dirName}": its family doc changed after this process loaded it.`,
+      undefined,
+      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+    );
+  }
+  // Built from the entry, as scopeSubComponent scopes Core's, so a member that
+  // shares the doc's own `name` is scoped too.
+  /** @type {LoadedComponentDoc & {parentDoc?: string, import?: string}} */
+  const scoped = {
+    name: dirName,
+    description: entry.description,
+    props: entry.props,
+    components: [entry],
+    // The name the family doc opens under, for every member.
+    parentDoc:
+      owner.integration && record.docPath
+        ? recordedDocName(owner.integration, record.docPath)
+        : docs.name === dirName && record.docPath
+          ? docStem(record.docPath)
+          : docs.name,
+  };
+  if (docs.usage) scoped.usage = docs.usage;
+  if (docs.theming) scoped.theming = docs.theming;
+  if (docs.import) scoped.import = docs.import;
+  return scoped;
+}

package/api/component/component.mjs

@@ -19,6 +19,7 @@ import {
   requireCoreDir,
   loadIntegrationsSafely,
   resolveOwners,
+  scopeIntegrationMember,
   classifyScope,
   assertUnambiguousOwners,
   resolveLegacyExternalDoc,
@@ -429,7 +430,13 @@ export async function component(name, options = {}) {
       if (blocks) {
         return componentDetailBlocks(dirName, cwd, owner.package);
       }
-      const docs = await loadComponentDoc(owner.docPath, docOpts);
+      const loaded = await loadComponentDoc(owner.docPath, docOpts);
+      // A family member an integration lists under its own name reads as that
+      // member, the way a Core sub-component does below.
+      const docs =
+        scoped.kind === 'integration'
+          ? scopeIntegrationMember(loaded, owner, dirName)
+          : loaded;
       if (props) return componentDetailProps(docs, owner.package);
       return componentDetail(docs, owner, dirName, coreDir);
     }
@@ -525,7 +532,8 @@ export async function component(name, options = {}) {
       // Integration components don't carry showcases — fail without scanning.
       return componentDetailShowcase(dirName, {cwd, name, resolve: false, ownerPackage: owner.package});
     }
-    const docs = await loadComponentDoc(owner.docPath, docOpts);
+    const loaded = await loadComponentDoc(owner.docPath, docOpts);
+    const docs = scopeIntegrationMember(loaded, owner, dirName);
     if (props) return componentDetailProps(docs, owner.package);
     return componentDetail(docs, owner, dirName, coreDir);
   }

package/api/component/integration-export-name.test.mjs

@@ -1,21 +1,25 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Every surface knows an integration component by the name its doc
- * documents. Fixtures live under a repo-local temp dir: Vite refuses to import
- * a module from outside the project root.
+ * @file Every surface knows an integration component, or a family member, by
+ * the name its doc documents. Fixtures live under a repo-local temp dir: Vite
+ * refuses to import a module from outside the project root.
  */
 
 import {afterEach, beforeEach, describe, expect, it} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import {spawnSync} from 'node:child_process';
 import {component} from './component.mjs';
 import {search} from '../search/search.mjs';
 import {validateIntegration} from '../integration/validate-integration.mjs';
 import {integrationComponentConflicts} from '../integration/authoring-checks.mjs';
 import {swizzleCopy} from '../swizzle/copy/copy.mjs';
 import {gapReport} from '../gap-report/gap-report.mjs';
+import {Project} from '../../foundation/config/project.mjs';
+import {collectDocInputs} from '../../foundation/doc-compiler/inputs.mjs';
 import {COMPONENT_REPLACES_CLI} from '../../foundation/integrations/cli-requirement.mjs';
+import {scopeIntegrationMember} from './_adapter.mjs';
 
 const SLOW = 30_000;
 
@@ -76,6 +80,7 @@ beforeEach(() => {
         './gallery/Slides': './src/gallery/Slides.tsx',
         './gallery/Overlays': './src/gallery/Overlays.tsx',
         './AcmeBadge': './src/AcmeBadge.tsx',
+        './tabs': './src/tabs/AcmeTabs.tsx',
       },
     }),
   );
@@ -95,6 +100,43 @@ beforeEach(() => {
     'export function AcmeBadge() { return null; }\n',
     'A small status label.',
   );
+  // A family doc whose members the module it imports exports.
+  fs.mkdirSync(path.join(pkgDir, 'src', 'tabs'), {recursive: true});
+  fs.writeFileSync(
+    path.join(pkgDir, 'src', 'tabs', 'AcmeTabs.tsx'),
+    'export function AcmeTabs() { return null; }\nexport function AcmeTab() { return null; }\n',
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'src', 'tabs', 'AcmeTabs.doc.mjs'),
+    `export default ${JSON.stringify(
+      {
+        type: 'component',
+        name: 'AcmeTabs',
+        displayName: 'Acme Tabs',
+        import: '@acme/widgets/tabs',
+        keywords: ['tabs', 'navigation'],
+        usage: {description: 'Switches between views.'},
+        components: [
+          {
+            name: 'AcmeTabs',
+            displayName: 'Acme Tabs',
+            description: 'The tab list.',
+            props: [],
+          },
+          {
+            name: 'AcmeTab',
+            displayName: 'Acme Tab',
+            description: 'One labelled tab in the list.',
+            props: [
+              {name: 'label', type: 'string', description: 'The tab label.'},
+            ],
+          },
+        ],
+      },
+      null,
+      2,
+    )};\n`,
+  );
 });
 
 afterEach(() => {
@@ -158,7 +200,7 @@ describe('a component doc that names another export of its file', () => {
     async () => {
       expect(
         listedNames(await component(undefined, {cwd: tmpDir, list: true})),
-      ).toEqual(['AcmeBadge', 'AcmeCarousel']);
+      ).toEqual(['AcmeBadge', 'AcmeCarousel', 'AcmeTab', 'AcmeTabs']);
 
       const detail = await component('AcmeCarousel', {cwd: tmpDir});
       expect(detail.type).toBe('component.detail');
@@ -198,15 +240,18 @@ describe('a component doc that names another export of its file', () => {
     SLOW,
   );
 
-  it(
-    "leaves a Core name to Core unless --package names it, and passes Doctor's package checks",
-    async () => {
+  it.each(['the export its doc names', 'a member its family doc lists'])(
+    "leaves a Core name to Core unless --package names it, when it is %s, and passes Doctor's package checks",
+    async kind => {
       // Overlays.tsx exports Dialog, a Core name, and nothing named Overlays.
+      const members = [{name: 'Dialog', description: 'A dialog.', props: []}];
+      const member = kind === 'a member its family doc lists';
       writeComponent(
         'gallery/Overlays',
-        'Dialog',
+        member ? 'AcmeOverlays' : 'Dialog',
         'export function AcmeOverlays() { return null; }\nexport function Dialog() { return null; }\n',
         'Overlays.',
+        member ? {components: members} : {},
       );
 
       const validation = await validateIntegration(undefined, {cwd: pkgDir});
@@ -416,4 +461,184 @@ describe('a component doc that names another export of its file', () => {
     },
     SLOW,
   );
+
+  it(
+    "opens a member named like its family doc's own name as that member",
+    async () => {
+      // Overlays.tsx exports Overlays, so the doc keeps its file name, and
+      // AcmeChip, the doc's own name, is a member.
+      const label = {name: 'label', type: 'string', description: 'The label.'};
+      writeComponent(
+        'gallery/Overlays',
+        'AcmeChip',
+        'export function Overlays() { return null; }\nexport function AcmeChip() { return null; }\nexport function AcmeChipIcon() { return null; }\n',
+        'Chips.',
+        {
+          components: [
+            {name: 'AcmeChip', description: 'One chip.', props: [label]},
+            {name: 'AcmeChipIcon', description: 'An icon.', props: []},
+          ],
+        },
+      );
+      // Every member names the family by the name it opens under.
+      expect(
+        (await component('AcmeChipIcon', {cwd: tmpDir})).data.parentDoc,
+      ).toBe('Overlays');
+      const detail = await component('AcmeChip', {cwd: tmpDir});
+      expect(detail.data).toMatchObject({
+        name: 'AcmeChip',
+        description: 'One chip.',
+        parentDoc: 'Overlays',
+      });
+      const props = await component('AcmeChip', {cwd: tmpDir, props: true});
+      expect(props.data.map(prop => prop.name)).toEqual(['label']);
+    },
+    SLOW,
+  );
+
+  it(
+    'opens, lists and finds a family member as itself, with the import its family states',
+    async () => {
+      const list = await component(undefined, {cwd: tmpDir, list: true});
+      const entry = Object.values(list.data.components)
+        .flat()
+        .find(item => item.name === 'AcmeTab');
+      expect(entry).toEqual({
+        name: 'AcmeTab',
+        package: '@acme/widgets',
+        import: '@acme/widgets/tabs',
+      });
+
+      const detail = await component('AcmeTab', {cwd: tmpDir});
+      expect(detail.data).toMatchObject({
+        name: 'AcmeTab',
+        description: 'One labelled tab in the list.',
+        parentDoc: 'AcmeTabs',
+        package: '@acme/widgets',
+        import: '@acme/widgets/tabs',
+        sourceAvailable: true,
+      });
+      expect(detail.data.props.map(prop => prop.name)).toEqual(['label']);
+      const props = await component('AcmeTab', {cwd: tmpDir, props: true});
+      expect(props.data.map(prop => prop.name)).toEqual(['label']);
+      // The family's own doc is unchanged.
+      expect((await component('AcmeTabs', {cwd: tmpDir})).data).toMatchObject({
+        name: 'AcmeTabs',
+        import: '@acme/widgets/tabs',
+      });
+
+      const hits = (await search('AcmeTab', {cwd: tmpDir, type: 'component'}))
+        .data.results;
+      expect(hits[0]).toMatchObject({
+        name: 'AcmeTab',
+        description: 'One labelled tab in the list.',
+        import: '@acme/widgets/tabs',
+      });
+      // The member does not carry the family's keywords.
+      const tabs = (
+        await search('navigation', {cwd: tmpDir, type: 'component'})
+      ).data.results;
+      expect(tabs.map(hit => hit.name)).toContain('AcmeTabs');
+      expect(tabs.map(hit => hit.name)).not.toContain('AcmeTab');
+    },
+    SLOW,
+  );
+
+  it(
+    'leaves a member named like a Core sub-component to Core, and swizzle unknown',
+    async () => {
+      const tabs = path.join(pkgDir, 'src', 'tabs');
+      const doc = path.join(tabs, 'AcmeTabs.doc.mjs');
+      fs.writeFileSync(
+        doc,
+        fs
+          .readFileSync(doc, 'utf-8')
+          .replace(
+            '"components": [',
+            '"components": [{"name": "DialogHeader", "description": "x"},',
+          ),
+      );
+      fs.appendFileSync(
+        path.join(tabs, 'AcmeTabs.tsx'),
+        'export function DialogHeader() { return null; }\n',
+      );
+      const cwd = tmpDir;
+      expect(
+        listedNames(await component(undefined, {cwd, list: true})),
+      ).toContain('DialogHeader');
+      expect((await component('DialogHeader', {cwd})).data.package).toBe(
+        '@astryxdesign/core',
+      );
+      await expect(swizzleCopy('DialogHeader', {cwd})).rejects.toMatchObject({
+        code: 'ERR_UNKNOWN_COMPONENT',
+      });
+    },
+    SLOW,
+  );
+
+  it('fails a member its family doc, as this process loaded it, does not list', async () => {
+    const owner = {
+      package: '@acme/widgets',
+      docPath: path.join(pkgDir, 'src', 'tabs', 'AcmeTabs.doc.mjs'),
+      sourcePath: null,
+    };
+    // The doc this process loaded before AcmeTab was added.
+    const stale = {type: 'component', name: 'AcmeTabs', components: []};
+    expect(() =>
+      scopeIntegrationMember(/** @type {any} */ (stale), owner, 'AcmeTab', ''),
+    ).toThrow(expect.objectContaining({code: 'ERR_UNKNOWN_COMPONENT'}));
+  });
+
+  it(
+    'indexes a .doc.ts family member as a member when Node cannot load the doc',
+    () => {
+      const fam = path.join(pkgDir, 'src', 'fam');
+      fs.mkdirSync(fam, {recursive: true});
+      const manifest = path.join(pkgDir, 'package.json');
+      const pkg = JSON.parse(fs.readFileSync(manifest, 'utf-8'));
+      pkg.exports['./fam'] = './src/fam/AcmeFamTs.tsx';
+      fs.writeFileSync(manifest, JSON.stringify(pkg));
+      fs.writeFileSync(
+        path.join(fam, 'AcmeFamTs.doc.ts'),
+        "export default {type: 'component', name: 'AcmeFamTs', import: '@acme/widgets/fam', usage: {description: 'A family.'}, components: [{name: 'AcmeFamTs', description: 'x'}, {name: 'AcmeFamItem', description: 'One item.'}]};\n",
+      );
+      fs.writeFileSync(
+        path.join(fam, 'AcmeFamTs.tsx'),
+        'export function AcmeFamTs() { return null; }\nexport function AcmeFamItem() { return null; }\n',
+      );
+      // The real CLI under Node, which does not strip types in node_modules.
+      const run = spawnSync(
+        process.execPath,
+        [
+          path.join(process.cwd(), 'packages/cli/clients/cli/bin/astryx.mjs'),
+          'search',
+          'AcmeFamTs',
+          '--json',
+        ],
+        {cwd: tmpDir, encoding: 'utf-8'},
+      );
+      const hits = JSON.parse(run.stdout).data.results.filter(
+        (/** @type {any} */ hit) => hit.domain === 'component',
+      );
+      expect(hits.map((/** @type {any} */ hit) => hit.name)).toEqual([
+        'AcmeFamTs',
+      ]);
+    },
+    SLOW,
+  );
+
+  it(
+    'reads a family doc once when the docs compile',
+    async () => {
+      const {inputs, problems} = await collectDocInputs(
+        await Project.load(tmpDir),
+      );
+      expect(problems).toEqual([]);
+      const tabsDoc = path.join(pkgDir, 'src', 'tabs', 'AcmeTabs.doc.mjs');
+      expect(
+        inputs.filter(input => input.file === tabsDoc).map(input => input.name),
+      ).toEqual(['AcmeTabs']);
+    },
+    SLOW,
+  );
 });

package/api/docs/_adapter.d.mts

@@ -281,6 +281,17 @@ export function resolveTopicDocs(topic: unknown, options?: {
     lang: string | null;
     entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry;
 }>;
+/**
+ * Each doc one integration package ships, checked against the published
+ * authoring type for its kind with the project's own TypeScript (spec:AST-039
+ * FR13). Without TypeScript the report says nothing was checked.
+ * @param {any} integration a loaded integration
+ * @param {string} cwd
+ * @returns {Promise<import('../../foundation/discovery/doc-types.mjs').DocTypesReport & {fixtures?: number}>}
+ */
+export function integrationDocTypes(integration: any, cwd: string): Promise<import("../../foundation/discovery/doc-types.mjs").DocTypesReport & {
+    fixtures?: number;
+}>;
 /**
  * A doc a link found: what a read shows of the link, and the typed doc behind
  * it when a reference block can include it.