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

package/api/integration/add-contribution.component-names.test.mjs

@@ -98,6 +98,72 @@ describe('integrationAddComponent name collisions', () => {
     expect(snapshot()).toEqual(before);
   });
 
+  it('adds a name a family doc lists but the module it imports does not export', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({name: '@acme/widgets', version: '1.0.0', files: ['dist'], exports: {'./tabs': './components/tabs/index.ts'}}, null, 2)}\n`,
+    );
+    const tabs = path.join(tmpDir, 'components', 'tabs');
+    fs.mkdirSync(tabs, {recursive: true});
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTabs.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeTabs', import: '@acme/widgets/tabs', description: 'x', components: [{name: 'AcmeTabExtra', description: 'x'}]};\n",
+    );
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTabs.tsx'),
+      'export function AcmeTabs() { return null; }\nexport function AcmeTabExtra() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(tabs, 'index.ts'),
+      "export {AcmeTabs} from './AcmeTabs';\n",
+    );
+
+    const result = await integrationAdd('component', 'AcmeTabExtra', {
+      cwd: tmpDir,
+      dryRun: true,
+    });
+    expect(result.data.files).toContain('components/AcmeTabExtra.doc.mjs');
+  });
+
+  it('refuses a member a family exports through built output', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({name: '@acme/widgets', version: '1.0.0', files: ['dist'], exports: {'./tabs': './dist/tabs/index.js'}}, null, 2)}\n`,
+    );
+    const tabs = path.join(tmpDir, 'components', 'tabs');
+    fs.mkdirSync(tabs, {recursive: true});
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTabs.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeTabs', import: '@acme/widgets/tabs', description: 'x', components: [{name: 'AcmeTab', description: 'x'}]};\n",
+    );
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTabs.tsx'),
+      'export function AcmeTabs() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTab.tsx'),
+      'export function AcmeTab() { return null; }\n',
+    );
+    const dist = path.join(tmpDir, 'dist', 'tabs');
+    fs.mkdirSync(dist, {recursive: true});
+    fs.writeFileSync(
+      path.join(dist, 'index.js'),
+      "export {AcmeTabs} from './tabs.js';\nexport {AcmeTab} from './tab.js';\n",
+    );
+    fs.writeFileSync(
+      path.join(dist, 'tabs.js'),
+      'export function AcmeTabs() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(dist, 'tab.js'),
+      'export function AcmeTab() { return null; }\n',
+    );
+
+    await expect(
+      integrationAdd('component', 'AcmeTab', {cwd: tmpDir, dryRun: true}),
+    ).rejects.toThrow('Refusing to add component "AcmeTab"');
+  });
+
   it('still adds a component whose name is free', async () => {
     writeAuthoredComponent('components/AcmeWidget/AcmeWidget.doc.mjs');
 

package/api/integration/add-contribution.mjs

@@ -264,9 +264,13 @@ async function addComponent(name, options) {
       ERROR_CODES.ERR_FILE_EXISTS,
     );
   }
-  // Discovery keys components by doc stem anywhere under the root, so a second
-  // doc with this name would shadow one of the two.
-  const existingDoc = findIntegrationComponentDoc({components: root}, name);
+  // A second doc under a name discovery already records, by a doc's file name
+  // anywhere under the root or by a name a doc documents, would shadow one of
+  // the two.
+  const existingDoc = findIntegrationComponentDoc(
+    {name: owner, components: root, __packageDir: packageDir},
+    name,
+  );
   if (existingDoc != null) {
     throw new AstryxError(
       `Refusing to add component "${name}": ${projectPath(path.relative(packageDir, existingDoc))} already defines it.`,
@@ -691,7 +695,7 @@ async function addTemplate(name, options) {
   const sourcePath = projectPath(path.relative(packageDir, sourceFile));
   const extensionlessPath = sourcePath.replace(/\.tsx?$/u, '');
   const blockFields = templateType === 'block' ? '\n  aspectRatio: 1,' : '';
-  const specContents = `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */\nexport default {\n  type: '${templateType}',\n  name: '${name}',\n  displayName: '${kebabToTitle(name)}',\n  description: '${kebabToTitle(name)} template.',${blockFields}\n};\n`;
+  const specContents = `/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */\nexport default {\n  type: '${templateType}',\n  name: '${name}',\n  displayName: '${kebabToTitle(name)}',\n  description: '${kebabToTitle(name)} template.',${blockFields}\n};\n`;
   const sourceContents = `export default function ${pascalName}() {\n  return <div>${kebabToTitle(name)}</div>;\n}\n`;
 
   /** @type {import('./add-helpers.mjs').WritePlan[]} */

package/api/integration/add-contribution.test.mjs

@@ -536,7 +536,9 @@ describe('integrationAdd template', () => {
       path.join(tmpDir, 'templates/my-widget.doc.mjs'),
       'utf-8',
     );
-    expect(spec).toContain("@astryxdesign/cli/authoring').TemplateDoc");
+    expect(spec).toContain(
+      "@astryxdesign/cli/authoring').IntegrationTemplateDoc",
+    );
     expect(spec).toContain("type: 'page'");
     expect(spec).toContain("name: 'my-widget'");
 
@@ -830,7 +832,7 @@ describe('typed descriptor conformance', () => {
     for (const [relativePath, type] of [
       ['components/MyWidget.doc.mjs', 'ComponentDoc'],
       ['docs/my-guide.doc.mjs', 'ReferenceDoc'],
-      ['templates/my-page.doc.mjs', 'TemplateDoc'],
+      ['templates/my-page.doc.mjs', 'IntegrationTemplateDoc'],
       ['themes/ocean/oceanTheme.doc.mjs', 'ThemeDoc'],
     ]) {
       const source = fs.readFileSync(path.join(tmpDir, relativePath), 'utf-8');

package/api/integration/authoring-checks.mjs

@@ -3,6 +3,10 @@
 /**
  * @file Integration authoring diagnostics against the built-in Core catalog.
  *
+ * The components check also compares each component doc's props with the
+ * component's TypeScript props (foundation/discovery/prop-drift.mjs); those
+ * findings are warnings under `propDrift`.
+ *
  * Templates may intentionally replace Core identities; undeclared same-id
  * overlaps stay fail-closed and require package selection. The CLI package
  * version gates replacement-specific fields so 0.6.x keeps its released shape.
@@ -25,6 +29,7 @@ import {
   discoverOwnedComponents,
 } from '../../foundation/discovery/component-discovery.mjs';
 import {loadComponentReplacements} from '../component/_adapter.mjs';
+import {integrationPropDrift} from './_adapter.mjs';
 import {
   discoverBuiltinTopics,
   discoverIntegrationDocs,
@@ -242,6 +247,10 @@ export async function integrationComponentConflicts(pkg, options = {}) {
     };
   }
 
+  // Each documented prop against the component's TypeScript props, read with
+  // the project's own compiler; without one the report says it was skipped.
+  const propDrift = await integrationPropDrift(resolved.integration, cwd);
+
   const coreDir = findCoreDir(cwd);
   if (!coreDir) {
     issues.push({
@@ -252,7 +261,7 @@ export async function integrationComponentConflicts(pkg, options = {}) {
     });
     return {
       type: 'integration.component-conflicts',
-      data: {validated, name, version, conflicts: [], issues},
+      data: {validated, name, version, conflicts: [], issues, propDrift},
     };
   }
 
@@ -296,7 +305,7 @@ export async function integrationComponentConflicts(pkg, options = {}) {
 
   return {
     type: 'integration.component-conflicts',
-    data: {validated, name, version, conflicts, issues},
+    data: {validated, name, version, conflicts, issues, propDrift},
   };
 }
 

package/api/integration/authoring-checks.test.mjs

@@ -417,6 +417,45 @@ describe('integrationComponentConflicts', () => {
     expect(result.data.conflicts).toEqual([]);
     expect(result.data.issues).toEqual([]);
   });
+
+  it("compares each component doc's props with the component's TypeScript props, as warnings", async () => {
+    writeComponentIntegration('AcmeBadge');
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeBadge.doc.mjs'),
+      `export default {type: 'component', name: 'AcmeBadge', displayName: 'AcmeBadge', description: 'Fixture component.', props: [{name: 'label', type: 'string', description: 'Text.', required: true}, {name: 'size', type: "'sm' | 'md'", description: 'Size.'}]};\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeBadge.tsx'),
+      'export function AcmeBadge(props: {label: string; count?: number}) { return null; }\n',
+    );
+
+    const result = await integrationComponentConflicts(undefined, {
+      cwd: tmpDir,
+    });
+
+    expect(result.data.issues).toEqual([]);
+    expect(result.data.propDrift).toMatchObject({
+      status: 'checked',
+      components: 1,
+      unchecked: [],
+    });
+    expect(
+      result.data.propDrift?.findings.map(f => [f.prop, f.kind, f.severity]),
+    ).toEqual([
+      ['count', 'not_in_doc', 'warning'],
+      ['size', 'not_in_code', 'warning'],
+    ]);
+  });
+
+  it('leaves propDrift out when the package has no components root', async () => {
+    writeDocIntegration({name: 'acme-setup'});
+
+    const result = await integrationComponentConflicts(undefined, {
+      cwd: tmpDir,
+    });
+
+    expect(result.data).not.toHaveProperty('propDrift');
+  });
 });
 
 describe('integrationDocConflicts', () => {

package/api/integration/authoring-checks.type.d.mts

@@ -47,6 +47,14 @@ export type IntegrationTemplateConflictResponse = {
         issues: import("../../foundation/integrations/issue").AstryxIntegrationIssue[];
     };
 };
+/**
+ * Documented props compared with the component's TypeScript props. Present
+ * when the manifest loads and declares a components root. `status: 'skipped'`
+ * means nothing was compared (no TypeScript in the project) and `reason` says
+ * why. Every finding is a warning.
+ */
+export type PropDriftReport = import("../../foundation/discovery/prop-drift.mjs").PropDriftReport;
+export type PropDriftFinding = import("../../foundation/discovery/prop-drift.mjs").PropDriftFinding;
 export type IntegrationComponentConflictResponse = {
     type: "integration.component-conflicts";
     data: {
@@ -55,6 +63,7 @@ export type IntegrationComponentConflictResponse = {
         version: string | null;
         conflicts: IntegrationComponentConflict[];
         issues: import("../../foundation/integrations/issue").AstryxIntegrationIssue[];
+        propDrift?: PropDriftReport;
     };
 };
 export type IntegrationDocConflictResponse = {

package/api/integration/authoring-checks.type.mjs

@@ -58,10 +58,23 @@
  * @property {{validated: boolean, name: string | null, version: string | null, conflicts: IntegrationTemplateConflict[], issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[]}} data
  */
 
+/**
+ * Documented props compared with the component's TypeScript props. Present
+ * when the manifest loads and declares a components root. `status: 'skipped'`
+ * means nothing was compared (no TypeScript in the project) and `reason` says
+ * why. Every finding is a warning.
+ *
+ * @typedef {import('../../foundation/discovery/prop-drift.mjs').PropDriftReport} PropDriftReport
+ */
+
+/**
+ * @typedef {import('../../foundation/discovery/prop-drift.mjs').PropDriftFinding} PropDriftFinding
+ */
+
 /**
  * @typedef {object} IntegrationComponentConflictResponse
  * @property {'integration.component-conflicts'} type
- * @property {{validated: boolean, name: string | null, version: string | null, conflicts: IntegrationComponentConflict[], issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[]}} data
+ * @property {{validated: boolean, name: string | null, version: string | null, conflicts: IntegrationComponentConflict[], issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[], propDrift?: PropDriftReport}} data
  */
 
 /**

package/api/integration/check/check.d.mts

@@ -0,0 +1,96 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The code a skipped comparison carries under `--strict`: its key in the
+ * check's result, in snake case, then `_skipped` (`propDrift` is
+ * `prop_drift_skipped`).
+ * @param {string} key
+ */
+export function skippedCode(key: string): string;
+/**
+ * Whether a value is a report a check carries beside its issues: a
+ * comparison with a `status` of `checked` or `skipped` and its `findings`.
+ * @param {unknown} value
+ * @returns {value is IntegrationCheckReport}
+ */
+export function isCheckReport(value: unknown): value is IntegrationCheckReport;
+/**
+ * Every warning in one check's result, and every piece of work it skipped,
+ * as issues: what `--strict` reports as errors. The counts come from the
+ * same list, so the default run and the strict run read the same data.
+ * @param {IntegrationCheckName} check
+ * @param {IntegrationCheckResponse} response
+ * @param {{noPackage?: boolean}} [context] `noPackage`: validate found no
+ *   package.json, which only it reports; then no other check names a
+ *   missing manifest as skipped work
+ * @returns {{warnings: Array<Omit<IntegrationCheckFailure, 'check' | 'severity'>>, skipped: Array<Omit<IntegrationCheckFailure, 'check' | 'severity'>>}}
+ */
+export function strictIssues(check: IntegrationCheckName, response: IntegrationCheckResponse, context?: {
+    noPackage?: boolean;
+}): {
+    warnings: Array<Omit<IntegrationCheckFailure, "check" | "severity">>;
+    skipped: Array<Omit<IntegrationCheckFailure, "check" | "severity">>;
+};
+/**
+ * Count one check's result the way its own subcommand exits. Errors are what
+ * make it exit 1: error-severity issues, and for `docs` error findings.
+ * Warnings are warning issues, conflicts and findings, and the findings of
+ * any report the check carries. Skipped names work that did not run: no
+ * integration manifest, or a report that was skipped.
+ * @param {IntegrationCheckResponse} response
+ * @param {{noPackage?: boolean}} [context] as {@link strictIssues} takes it
+ * @returns {Omit<IntegrationCheckResult, 'check' | 'response'>}
+ */
+export function summarizeCheck(response: IntegrationCheckResponse, context?: {
+    noPackage?: boolean;
+}): Omit<IntegrationCheckResult, "check" | "response">;
+/**
+ * Run every `doctor integration` check against the integration package in
+ * `cwd`, as its own build does, and return the `integration.check` envelope.
+ *
+ * @param {IntegrationCheckOptions} [options]
+ * @returns {Promise<IntegrationCheckCommandResponse>}
+ */
+export function integrationCheck(options?: IntegrationCheckOptions): Promise<IntegrationCheckCommandResponse>;
+/**
+ * Count the four checks' results into one summary. Each check's own row
+ * counts as its subcommand exits; the totals and `failures` count validate's
+ * issues once, though the other checks repeat them, and every other finding
+ * on its own, so two findings with one message stay two.
+ * @param {IntegrationCheckResponse[]} responses validate first
+ * @param {boolean} strict
+ */
+export function combineChecks(responses: IntegrationCheckResponse[], strict: boolean): {
+    checks: import("../integration-check.type.mjs").IntegrationCheckResult[];
+    errors: number;
+    warnings: number;
+    skipped: string[];
+    unchecked: number;
+    failures: import("../integration-check.type.mjs").IntegrationCheckFailure[];
+    failed: boolean;
+};
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckName} IntegrationCheckName */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckReport} IntegrationCheckReport */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckResponse} IntegrationCheckResponse */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckResult} IntegrationCheckResult */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckOptions} IntegrationCheckOptions */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckCommandResponse} IntegrationCheckCommandResponse */
+/** @typedef {import('../integration-check.type.mjs').IntegrationCheckFailure} IntegrationCheckFailure */
+/** The checks `integration check` runs, in the order it runs them. */
+export const INTEGRATION_CHECKS: readonly ["validate", "components", "templates", "docs"];
+/** The skipped-work line for a package with no integration manifest. */
+export const NO_MANIFEST_SKIP: "No astryx.integration.* found next to package.json, so nothing was checked.";
+export namespace CONFLICT_CODES {
+    let components: "component_name_conflict";
+    let templates: "template_id_conflict";
+}
+/** The code a check with no integration manifest carries under `--strict`. */
+export const NO_MANIFEST_CODE: "missing_manifest";
+export type IntegrationCheckName = import("../integration-check.type.mjs").IntegrationCheckName;
+export type IntegrationCheckReport = import("../integration-check.type.mjs").IntegrationCheckReport;
+export type IntegrationCheckResponse = import("../integration-check.type.mjs").IntegrationCheckResponse;
+export type IntegrationCheckResult = import("../integration-check.type.mjs").IntegrationCheckResult;
+export type IntegrationCheckOptions = import("../integration-check.type.mjs").IntegrationCheckOptions;
+export type IntegrationCheckCommandResponse = import("../integration-check.type.mjs").IntegrationCheckCommandResponse;
+export type IntegrationCheckFailure = import("../integration-check.type.mjs").IntegrationCheckFailure;