@astryxdesign/cli 0.7.2-canary.e2909cf → 0.7.2-canary.e4bdd70

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]>;
+};