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

package/foundation/discovery/component-discovery.test.mjs

@@ -16,6 +16,7 @@ import {fileURLToPath} from 'node:url';
 import {
   CORE_PACKAGE,
   discoverComponents,
+  familyMember,
   findComponentReadme,
   findComponentSource,
   resolveImportPath,
@@ -121,6 +122,91 @@ describe('discoverComponents (real core)', () => {
     expect(discoverComponents(core)).toEqual({});
   });
 
+  it('lists HStack, VStack and Heading, whose docs live in their family folders', () => {
+    // Each has its own folder and import path; Stack's doc documents HStack and
+    // VStack as members, and Heading's own doc sits in the Text folder.
+    const comps = discoverComponents(CORE);
+    expect(comps.Layout).toEqual(expect.arrayContaining(['HStack', 'Stack', 'VStack']));
+    expect(comps.Heading).toEqual(['Heading']);
+    expect(findComponentReadme(CORE, 'VStack')).toMatch(/[\\/]Stack[\\/]Stack\.doc\.mjs$/);
+    expect(findComponentReadme(CORE, 'HStack')).toMatch(/[\\/]Stack[\\/]Stack\.doc\.mjs$/);
+    expect(findComponentReadme(CORE, 'Heading')).toMatch(/[\\/]Text[\\/]Heading\.doc\.mjs$/);
+    expect(resolveImportPath(CORE, 'VStack')).toBe('@astryxdesign/core/VStack');
+    expect(resolveImportPath(CORE, 'Heading')).toBe('@astryxdesign/core/Heading');
+  }, SLOW);
+
+  it('lists a component folder with no doc when its family doc lists it as a member', () => {
+    const core = mkTmp('as-cd-family-');
+    const write = (rel, text) => {
+      fs.mkdirSync(path.dirname(path.join(core, 'src', rel)), {recursive: true});
+      fs.writeFileSync(path.join(core, 'src', rel), text);
+    };
+    write('Stack/Stack.tsx', 'x');
+    write('VStack/VStack.tsx', "import {Stack} from '../Stack/Stack';\n");
+    write('Prose/Prose.tsx', "import {Stack} from '../Stack/Stack';\n");
+    // Listed by Stack's doc, but builds on nothing in Stack's folder.
+    write('Orphan/Orphan.tsx', "import {x} from '../utils';\n");
+    write(
+      'Stack/Stack.doc.mjs',
+      'export const docs = {\n' +
+        "  name: 'Stack',\n" +
+        "  group: 'Layout',\n" +
+        "  relatedComponents: ['Prose'],\n" +
+        "  usage: {description: 'Pair with Prose.', examples: [{code: \"<Prose label='Prose' />\"}]},\n" +
+        "  components: [{name: 'Stack'}, {name: 'VStack', description: 'Vertical.'}, {name: 'Orphan'}],\n" +
+        '};\n',
+    );
+    expect(discoverComponents(core)).toEqual({Layout: ['Stack', 'VStack']});
+    expect(findComponentReadme(core, 'VStack')).toBe(
+      path.join(core, 'src', 'Stack', 'Stack.doc.mjs'),
+    );
+    // Named only in relatedComponents, prose, and an example: not documented.
+    expect(findComponentReadme(core, 'Prose')).toBeNull();
+    // A family doc is read only from the folders the component imports.
+    expect(findComponentReadme(core, 'Orphan')).toBeNull();
+  });
+
+  it('lists a component folder with no doc when its own doc sits in a family folder', () => {
+    const core = mkTmp('as-cd-sibling-');
+    for (const dir of ['Text', 'Heading']) {
+      fs.mkdirSync(path.join(core, 'src', dir), {recursive: true});
+    }
+    fs.writeFileSync(path.join(core, 'src', 'Text', 'Text.tsx'), 'x');
+    fs.writeFileSync(path.join(core, 'src', 'Heading', 'Heading.tsx'), 'x');
+    fs.writeFileSync(
+      path.join(core, 'src', 'Text', 'Text.doc.mjs'),
+      "export const docs = {name: 'Text', components: [{name: 'Heading'}]};\n",
+    );
+    fs.writeFileSync(
+      path.join(core, 'src', 'Text', 'Heading.doc.mjs'),
+      "export const docs = {name: 'Heading'};\n",
+    );
+    expect(discoverComponents(core)).toEqual({Heading: ['Heading'], Text: ['Text']});
+    expect(findComponentReadme(core, 'Heading')).toBe(
+      path.join(core, 'src', 'Text', 'Heading.doc.mjs'),
+    );
+  });
+
+  it('keeps a member its family hides, and a context folder, unlisted', () => {
+    const core = mkTmp('as-cd-family-hidden-');
+    for (const dir of ['Stack', 'VStack', 'SizeContext']) {
+      fs.mkdirSync(path.join(core, 'src', dir), {recursive: true});
+      fs.writeFileSync(
+        path.join(core, 'src', dir, `${dir}.tsx`),
+        "import {Stack} from '../Stack/Stack';\n",
+      );
+    }
+    fs.writeFileSync(
+      path.join(core, 'src', 'Stack', 'Stack.doc.mjs'),
+      'export const docs = {\n' +
+        "  name: 'Stack',\n" +
+        "  hiddenComponents: ['VStack'],\n" +
+        "  components: [{name: 'Stack'}, {name: 'VStack'}, {name: 'SizeContext'}],\n" +
+        '};\n',
+    );
+    expect(discoverComponents(core)).toEqual({Stack: ['Stack']});
+  });
+
   it('returns {} for an empty src/ dir', () => {
     const core = mkTmp('as-cd-emptysrc-');
     fs.mkdirSync(path.join(core, 'src'));
@@ -133,6 +219,16 @@ describe('discoverComponents (real core)', () => {
   });
 });
 
+describe('familyMember', () => {
+  it("returns a family doc's entry for a member, and null for a component's own doc", () => {
+    const stack = {name: 'Stack', components: [{name: 'Stack'}, {name: 'VStack', description: 'v'}]};
+    expect(familyMember(stack, 'VStack')).toEqual({name: 'VStack', description: 'v'});
+    expect(familyMember(stack, 'Stack')).toBeNull();
+    expect(familyMember({name: 'Button'}, 'Button')).toBeNull();
+    expect(familyMember(stack, 'HStack')).toBeNull();
+  });
+});
+
 describe('findComponentReadme / findComponentSource / resolveImportPath', () => {
   it('finds the doc + source for a top-level component', () => {
     expect(findComponentReadme(CORE, 'Button')).toMatch(/Button\.doc\.mjs$/);

package/foundation/discovery/component-replacement.mjs

@@ -161,6 +161,24 @@ export async function resolveComponentReplacements(
       typeof name === 'string' ? byTarget.get(name) : undefined,
   };
 
+  // A first read under file names alone settles the common case, no
+  // declaration anywhere, without reading the names docs document.
+  let declares = false;
+  for (const integration of loadedIntegrations) {
+    if (declares || !integration?.components || integration.__loadError)
+      continue;
+    try {
+      const {components} = await discoverValidIntegrationComponents(
+        integration,
+        {documentedNames: false},
+      );
+      declares = components.some(record => record.replaces !== undefined);
+    } catch {
+      // Read again below, where a root that cannot be read is skipped.
+    }
+  }
+  if (!declares) return result;
+
   /** @type {Declaration[]} */
   const declarations = [];
   /** @type {Array<{name: string, package: string}>} */

package/foundation/discovery/component-replacement.test.mjs

@@ -259,6 +259,46 @@ describe('resolveComponentReplacements', () => {
     ]);
   });
 
+  it('applies a replacement under the export a doc names when its file is named otherwise', async () => {
+    // Nav.doc.mjs documents AcmeSideNav, the export of a Nav.tsx that exports
+    // nothing named Nav.
+    const acme = integrationWithDocSource(
+      '@acme/nav',
+      'Nav',
+      BASE_DOC.replace("name: 'AcmeNav'", "name: 'AcmeSideNav'"),
+    );
+    fs.writeFileSync(
+      path.join(acme.components, 'Nav.tsx'),
+      'export function AcmeSideNav() { return null; }\n',
+    );
+    const result = await resolveComponentReplacements(CORE_DIR, [acme]);
+    expect(result.findings).toEqual([]);
+    expect(result.forTarget('SideNav')).toMatchObject({
+      name: 'AcmeSideNav',
+      package: '@acme/nav',
+    });
+  });
+
+  it("counts a doc's replaces once when the doc lists its own name as a member", async () => {
+    // Chip.doc.mjs documents AcmeChip beside a Chip.tsx that exports both, and
+    // lists itself first, as the component-family guide asks.
+    const acme = integrationWithDocSource(
+      '@acme/chips',
+      'Chip',
+      `export default {type: 'component', name: 'AcmeChip', replaces: 'Badge', usage: {description: 'Acme chip.'}, components: [{name: 'AcmeChip', description: 'A chip.', props: []}]};\n`,
+    );
+    fs.writeFileSync(
+      path.join(acme.components, 'Chip.tsx'),
+      'export function Chip() { return null; }\nexport function AcmeChip() { return null; }\n',
+    );
+    const result = await resolveComponentReplacements(CORE_DIR, [acme]);
+    expect(result.findings).toEqual([]);
+    expect(result.forTarget('Badge')).toMatchObject({
+      name: 'Chip',
+      package: '@acme/chips',
+    });
+  });
+
   it('lets a replacement keep the Core name it replaces', async () => {
     const acme = integration(
       '@acme/nav',

package/foundation/discovery/doc-types.d.mts

@@ -0,0 +1,157 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Check each doc file's values against the published authoring types.
+ * @param {DocFile[]} files
+ * @param {{packageDir: string, resolveFrom: Array<string | null | undefined>, core?: boolean}} options
+ *   `core`: the docs are Core's own, so templates are held to TemplateDoc
+ * @returns {Promise<DocTypesReport>}
+ */
+export function checkDocTypes(files: DocFile[], options: {
+    packageDir: string;
+    resolveFrom: Array<string | null | undefined>;
+    core?: boolean;
+}): Promise<DocTypesReport>;
+/**
+ * @typedef {'components' | 'hooks' | 'templates' | 'docs' | 'docs-overlay' | 'themes'} DocRoot
+ */
+/**
+ * @typedef {object} DocFile
+ * @property {string} path absolute path to the doc file
+ * @property {DocRoot} root the contribution root it was found in
+ */
+/**
+ * @typedef {'unknown_field' | 'missing_field' | 'wrong_type'} DocTypeProblem
+ */
+/**
+ * @typedef {object} DocTypeFinding
+ * @property {string} doc the doc file, relative to the package root
+ * @property {number} line 1-based line of the field (or of the doc value)
+ * @property {string} export the export checked (`default`, `docs`, `docsZh`, …)
+ * @property {string} type the authoring type it was checked against
+ * @property {string} field the field's path in the doc, such as
+ *   `usage.bestPractices[2].guidance`; empty for the doc value as a whole
+ * @property {DocTypeProblem} problem
+ * @property {'warning'} severity
+ * @property {string} message what TypeScript reports, shortened
+ * @property {string} fix what to change
+ */
+/**
+ * @typedef {object} DocTypesUnchecked
+ * @property {string} doc the doc file, relative to the package root
+ * @property {string} reason why it was not checked
+ */
+/**
+ * @typedef {object} DocTypesReport
+ * @property {'checked' | 'skipped'} status `skipped` means nothing was checked,
+ *   and `reason` says why
+ * @property {string} [reason]
+ * @property {string} [typescript] the version of the compiler that checked
+ * @property {number} docs how many doc values were checked
+ * @property {DocTypeFinding[]} findings
+ * @property {DocTypesUnchecked[]} unchecked doc files with nothing to check,
+ *   or not fully checked
+ */
+/** The line both surfaces print when the compiler is missing. */
+export const DOC_TYPES_TYPESCRIPT_MISSING_REASON: "TypeScript is not installed in this project, so docs were not checked against the authoring types. Install typescript and run this check again.";
+export type DocRoot = "components" | "hooks" | "templates" | "docs" | "docs-overlay" | "themes";
+export type DocFile = {
+    /**
+     * absolute path to the doc file
+     */
+    path: string;
+    /**
+     * the contribution root it was found in
+     */
+    root: DocRoot;
+};
+export type DocTypeProblem = "unknown_field" | "missing_field" | "wrong_type";
+export type DocTypeFinding = {
+    /**
+     * the doc file, relative to the package root
+     */
+    doc: string;
+    /**
+     * 1-based line of the field (or of the doc value)
+     */
+    line: number;
+    /**
+     * the export checked (`default`, `docs`, `docsZh`, …)
+     */
+    export: string;
+    /**
+     * the authoring type it was checked against
+     */
+    type: string;
+    /**
+     * the field's path in the doc, such as
+     * `usage.bestPractices[2].guidance`; empty for the doc value as a whole
+     */
+    field: string;
+    problem: DocTypeProblem;
+    severity: "warning";
+    /**
+     * what TypeScript reports, shortened
+     */
+    message: string;
+    /**
+     * what to change
+     */
+    fix: string;
+};
+export type DocTypesUnchecked = {
+    /**
+     * the doc file, relative to the package root
+     */
+    doc: string;
+    /**
+     * why it was not checked
+     */
+    reason: string;
+};
+export type DocTypesReport = {
+    /**
+     * `skipped` means nothing was checked,
+     * and `reason` says why
+     */
+    status: "checked" | "skipped";
+    reason?: string | undefined;
+    /**
+     * the version of the compiler that checked
+     */
+    typescript?: string | undefined;
+    /**
+     * how many doc values were checked
+     */
+    docs: number;
+    findings: DocTypeFinding[];
+    /**
+     * doc files with nothing to check,
+     * or not fully checked
+     */
+    unchecked: DocTypesUnchecked[];
+};
+export type Target = {
+    exportName: string;
+    /**
+     * the doc value's expression
+     */
+    node: any;
+    /**
+     * the authoring type, as a type expression
+     */
+    typeExpr: string;
+    /**
+     * how findings name that type
+     */
+    typeName: string;
+    /**
+     * nodes whose leading JSDoc annotations are blanked
+     */
+    blank: any[];
+    /**
+     * source ranges to blank
+     */
+    blankRanges: Array<[number, number]>;
+};