@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

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

@@ -30,6 +30,7 @@ import {
   COMPONENT_REPLACES_CLI,
   componentReplacesCliProblem,
 } from '../integrations/cli-requirement.mjs';
+import {formatCliCommand} from '../env/package-manager.mjs';
 
 /**
  * @typedef {import('../integrations/integrations.mjs').LoadedIntegration} LoadedIntegration
@@ -161,6 +162,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}>} */
@@ -274,7 +293,7 @@ export async function resolveComponentReplacements(
         'missing_component_replacement_target',
         differentCase
           ? `Component "${name}" replaces "${replaces}", which is not a Core component name. Core names it "${differentCase}".`
-          : `Component "${name}" replaces "${replaces}", which is not a Core component. Run \`astryx component --list\` for Core component names.`,
+          : `Component "${name}" replaces "${replaces}", which is not a Core component. Run \`${formatCliCommand('component --list')}\` for Core component names.`,
       );
       if (declaration.optedIn) {
         const key = differentCase ?? replaces;

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/copied-passages.d.mts

@@ -0,0 +1,216 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The number of distinct content words in a run: words that are not function
+ * words, with surrounding punctuation set aside.
+ *
+ * @param {{word: string}[]} words
+ * @param {number} start
+ * @param {number} length
+ */
+export function contentWords(words: {
+    word: string;
+}[], start: number, length: number): number;
+/**
+ * The words a passage is compared by: lowercase, with links and Markdown
+ * emphasis set aside. A token with no letter or digit (the `.` after a link)
+ * is not a word.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function passageWords(text: string): string[];
+/**
+ * Every word of a doc file, in order, with its 1-based line. Words are runs of
+ * letters and digits, so punctuation, code ticks, quotes and escapes in the
+ * source neither join nor split them.
+ *
+ * @param {string} source
+ * @returns {{word: string, line: number}[]}
+ */
+export function fileWords(source: string): {
+    word: string;
+    line: number;
+}[];
+/**
+ * The words of a string the way {@link fileWords} reads a file, each with its
+ * offset in the string.
+ *
+ * @param {string} text
+ * @returns {{word: string, at: number}[]}
+ */
+export function textWords(text: string): {
+    word: string;
+    at: number;
+}[];
+/**
+ * Where a string's whole run of words starts among a file's words, looking
+ * from `from` on, or -1.
+ *
+ * @param {{word: string}[]} file
+ * @param {{word: string}[]} words
+ * @param {number} [from]
+ * @returns {number}
+ */
+export function locateWords(file: {
+    word: string;
+}[], words: {
+    word: string;
+}[], from?: number): number;
+/**
+ * The file line of the character at offset `at` of a string whose words start
+ * at `index` among the file's words.
+ *
+ * @param {{line: number}[]} file
+ * @param {number} index
+ * @param {{at: number}[]} words the string's words
+ * @param {number} at
+ * @returns {number | null}
+ */
+export function lineAtOffset(file: {
+    line: number;
+}[], index: number, words: {
+    at: number;
+}[], at: number): number | null;
+/**
+ * A shared run with the boilerplate trimmed off its ends, judged window by
+ * window: every word a leading boilerplate window covers, and every word from
+ * the first trailing one on. A lead-in many topics open with thus never hides
+ * the copy after it. Null when less than {@link PASSAGE_WORDS} words are left.
+ *
+ * @param {{start: number, length: number}} run
+ * @param {(at: number) => boolean} boilerplate whether the window of
+ *   {@link PASSAGE_WORDS} words starting at `at` is boilerplate
+ * @returns {{start: number, length: number} | null}
+ */
+export function trimBoilerplate({ start, length }: {
+    start: number;
+    length: number;
+}, boilerplate: (at: number) => boolean): {
+    start: number;
+    length: number;
+} | null;
+/**
+ * The words of one string as passageWords reads them, each with where it sits
+ * in the string as written, so a passage can be quoted with its case,
+ * punctuation and code ticks.
+ *
+ * @param {string} text
+ * @returns {{word: string, start: number, end: number}[]}
+ */
+export function wordSpans(text: string): {
+    word: string;
+    start: number;
+    end: number;
+}[];
+/**
+ * Each prose string of a doc, in order, with the title of the section it is
+ * in (null before the first section). Code, examples, reference blocks, and
+ * identifier fields are left out.
+ *
+ * @param {unknown} doc an authored doc object
+ * @returns {{text: string, section: string | null}[]}
+ */
+export function proseStrings(doc: unknown): {
+    text: string;
+    section: string | null;
+}[];
+/**
+ * Each prose word of a doc, in order, with the title of the section it is in
+ * (null before the first section) and the number of the string it came from.
+ * A passage never runs from one string into the next, so two fields that
+ * happen to sit side by side are not read as one sentence.
+ *
+ * @param {unknown} doc an authored doc object
+ * @returns {{word: string, section: string | null, block: number}[]}
+ */
+export function proseWords(doc: unknown): {
+    word: string;
+    section: string | null;
+    block: number;
+}[];
+/**
+ * The runs of at least `size` words that both docs have, each inside one
+ * string of each doc, longest first, as its start in `mine` and its length.
+ *
+ * @param {{word: string, block?: number}[]} mine
+ * @param {{word: string, block?: number}[]} other
+ * @param {number} [size]
+ * @returns {{start: number, length: number}[]}
+ */
+export function sharedPassages(mine: {
+    word: string;
+    block?: number;
+}[], other: {
+    word: string;
+    block?: number;
+}[], size?: number): {
+    start: number;
+    length: number;
+}[];
+/**
+ * @param {string} file
+ * @returns {Promise<any>} the doc, or null for one that does not load (the
+ *   load problem is reported elsewhere)
+ */
+export function loadQuietly(file: string): Promise<any>;
+/** @returns {Promise<IndexedGuides>} the CLI's own guides, read and indexed once */
+export function loadCoreGuides(): Promise<IndexedGuides>;
+/**
+ * One entry for each pair of topics that repeat a passage word for word: two
+ * of the package's own topics, or one of them and a Core topic, except the
+ * Core topic it replaces (a replacement takes that topic's place, so it may
+ * carry its text).
+ *
+ * @param {{records: {name: string, path: string, replaces?: string | null, extendsTopic?: string | null}[], guides?: {name: string, ref?: {topicFile?: string}}[]}} discovered
+ *   the package's docs, as discoverIntegrationDocs returns them
+ * @returns {Promise<import('../../api/integration/authoring-checks.type.mjs').CopiedPassage[]>}
+ */
+export function findCopiedPassages(discovered: {
+    records: {
+        name: string;
+        path: string;
+        replaces?: string | null;
+        extendsTopic?: string | null;
+    }[];
+    guides?: {
+        name: string;
+        ref?: {
+            topicFile?: string;
+        };
+    }[];
+}): Promise<import("../../api/integration/authoring-checks.type.mjs").CopiedPassage[]>;
+/** The shortest run of identical words reported as a copy. */
+export const PASSAGE_WORDS: 10;
+/**
+ * A copy carries at least this many distinct content words, so a run of
+ * glue words ("and it is in the way that you can…") is a phrase, not a fact.
+ */
+export const MIN_CONTENT_WORDS: 4;
+/**
+ * A run that this many topics share is boilerplate, such as a lead-in every
+ * guide of a series opens with, not a copy of one topic's fact.
+ */
+export const BOILERPLATE_TOPICS: 3;
+export type GuideWords = {
+    name: string;
+    title?: string;
+    file?: string;
+    doc?: unknown;
+    words: {
+        word: string;
+        section: string | null;
+        block: number;
+    }[];
+    replaces: string | null;
+    extendsTopic?: string | null;
+};
+/**
+ * Guides with an index from each run of words to the guides that have it, so
+ * a topic is compared in full only with the guides it shares a run with.
+ */
+export type IndexedGuides = {
+    guides: GuideWords[];
+    index: Map<string, number[]>;
+};