@astryxdesign/cli 0.7.2 → 0.7.3-canary.06872b4

package/foundation/config/project.mjs

@@ -40,7 +40,7 @@ import {parseConfig} from '../../authoring/config/parse.mjs';
 import {
   loadIntegrations,
   loadLocalIntegration,
-  resolvePackageDir,
+  resolveInstalledIntegrationDir,
 } from '../integrations/integrations.mjs';
 import {loadAutolinkCandidates} from '../integrations/autolink.mjs';
 import {
@@ -65,7 +65,7 @@ import {
   discoverValidIntegrationComponents,
 } from '../discovery/component-discovery.mjs';
 import {resolveComponentReplacements} from '../discovery/component-replacement.mjs';
-import {CLI_ROOT, findCoreDir, findProjectCoreDir} from '../fs/paths.mjs';
+import {CLI_ROOT, findCoreDir, findPackageRoot, findProjectCoreDir} from '../fs/paths.mjs';
 import {
   applyTemplateReplacements,
   effectiveTemplateDiscovery,
@@ -89,6 +89,10 @@ import {
 } from '../../assets/codemods/integration-discovery.mjs';
 import {validateLoadedIntegration} from '../integrations/validate-contributions.mjs';
 import {recordDeclaredCliCommands} from '../env/cli-command.mjs';
+import {
+  hostedRun,
+  recordResolvedIntegrations,
+} from '../runtime/package-root.mjs';
 import {
   InMemoryConfigCache,
   cacheKey,
@@ -121,9 +125,16 @@ function errorMessage(err) {
  */
 export function computerIntegrationCandidates(cwd = process.cwd()) {
   try {
-    const cliRoot = isOutsideProject(cwd) ? CLI_ROOT : globalCliRoot(cwd);
+    const outside = isOutsideProject(cwd);
+    const cliRoot = outside ? CLI_ROOT : globalCliRoot(cwd);
     return cliRoot
-      ? scanComputerIntegrations({cliRoot, release: cliVersion()})
+      ? scanComputerIntegrations({
+          cliRoot,
+          release: cliVersion(),
+          // Outside a project, the integrations a host approves load from the
+          // package set that serves the run too (cli-surface INV30).
+          approved: outside ? (hostedRun()?.integrations ?? []) : [],
+        })
       : [];
   } catch {
     return [];
@@ -212,7 +223,7 @@ async function loadConfiguredIntegrations(specs, {cwd, fresh}) {
       /** @type {string|undefined} */
       let packageDir;
       try {
-        packageDir = resolvePackageDir(spec, cwd);
+        packageDir = resolveInstalledIntegrationDir(spec, cwd);
       } catch {
         // Not a bare package name: there is no install location to record.
       }
@@ -315,22 +326,6 @@ export const CONFIG_BASENAMES = [
 export const DEFAULT_ISSUES_URL =
   'https://github.com/facebook/astryx/issues/new';
 
-/**
- * Find the directory of the nearest package.json walking up from startDir.
- * @param {string} startDir
- * @returns {string|null}
- */
-function findPackageRoot(startDir) {
-  let dir = startDir;
-  for (let i = 0; i < 50; i++) {
-    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return null;
-}
-
 /**
  * Whether this project accepts `debug` handlers contributed by the
  * integrations it loads.
@@ -495,7 +490,8 @@ export class Project {
     // The project root: the config's directory when there is one (findConfigPath
     // resolves the config as a sibling of the nearest package.json, so the two
     // agree), otherwise that package.json's directory. Dependencies are declared
-    // there, and node_modules sits there.
+    // there, and installed packages resolve from there up the node_modules
+    // chain.
     const projectDir = configPath
       ? path.dirname(configPath)
       : (findPackageRoot(cwd) ?? cwd);
@@ -580,6 +576,8 @@ export class Project {
         : []),
     ]);
     loadedIntegrations = resolution.integrations;
+    // A hosted run returns each package it resolved (cli-surface INV30).
+    recordResolvedIntegrations(loadedIntegrations);
     // The picker (getCliInvocation) is synchronous, so the commands these
     // integrations declare are recorded here, where they become known.
     recordDeclaredCliCommands(projectDir, loadedIntegrations);

package/foundation/config/project.test.mjs

@@ -291,6 +291,32 @@ describe('Project.load', () => {
   });
 });
 
+describe('Project.issues and a near-miss manifest key', () => {
+  it.each([
+    [
+      'alone, while the loaded integration fills providerId from the package name',
+      {providerID: '@acme/widgets'},
+      'Fix: rename "providerID" to "providerId" in astryx.integration.mjs.',
+    ],
+    [
+      'beside the key it suggests',
+      {providerID: '@acme/widgets', providerId: '@acme/widgets'},
+      'Fix: remove "providerID" from astryx.integration.mjs; it already sets "providerId".',
+    ],
+  ])(
+    'reads the keys the manifest declares: providerID %s',
+    async (_label, unknownKeys, fix) => {
+      scaffold({unknownKeys});
+      const project = await Project.load(tmpDir);
+      const keys = (await project.issues()).filter(
+        issue => issue.code === 'unknown_manifest_key',
+      );
+      expect(keys).toHaveLength(1);
+      expect(keys[0].message).toContain(fix);
+    },
+  );
+});
+
 describe('Project.load and the cliCommand an integration declares', () => {
   it('records it, so the picker prints commands with it', async () => {
     scaffold({cliCommand: 'acme astryx'});
@@ -830,6 +856,36 @@ describe('Project loads each integration in isolation', () => {
   });
 });
 
+describe('Project finds configured integrations a workspace hoists', () => {
+  // npm, Yarn and Bun workspaces install a member's dependencies at the
+  // workspace root, so the member's own node_modules does not hold them.
+  it('loads an integration named in a member config from the workspace root', async () => {
+    scaffold();
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'root', private: true, workspaces: ['apps/*']}),
+    );
+    fs.rmSync(path.join(tmpDir, 'astryx.config.mjs'));
+    const member = path.join(tmpDir, 'apps', 'web');
+    fs.mkdirSync(member, {recursive: true});
+    fs.writeFileSync(path.join(member, 'package.json'), JSON.stringify({name: 'web'}));
+    fs.writeFileSync(
+      path.join(member, 'astryx.config.mjs'),
+      `export default ${JSON.stringify({integrations: ['@acme/widgets']})};\n`,
+    );
+
+    const project = await Project.load(member);
+
+    const widgets = (await project.components()).filter(
+      component => component.package === '@acme/widgets',
+    );
+    expect(widgets.map(component => component.name)).toEqual(['Widget']);
+    expect(await project.issues()).not.toContainEqual(
+      expect.objectContaining({package: '@acme/widgets', code: 'integration_error'}),
+    );
+  });
+});
+
 describe('Project.issuesUrl routing', () => {
   it('routes core to config.issuesUrl, falling back to the default', async () => {
     scaffold({issuesUrl: 'https://example.com/core'});

package/foundation/discovery/component-discovery.d.mts

@@ -1,6 +1,13 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * Whether a component doc is hidden (`hidden: true`), read as discovery
+ * reads it: discovery skips a hidden doc.
+ * @param {string} docPath
+ * @returns {boolean}
+ */
+export function isHiddenComponentDoc(docPath: string): boolean;
 /**
  * The entry a family doc gives `name` in its `components`, when the doc is not
  * the component's own (Stack's doc for VStack); null otherwise.
@@ -117,6 +124,36 @@ export function discoverExternalComponentsGrouped(docsDir: string): Record<strin
 export function findExternalComponentDoc(docsDir: string, name: string): string | null;
 /** @param {string} docPath */
 export function docStem(docPath: string): string;
+/**
+ * The local module a doc's import names: the doc's own `import`, else the
+ * subpath its directory publishes, read through the package's `exports` (its
+ * `main` when it has none). Undefined when the package directory is unknown;
+ * null when the import names another package or resolves to no file.
+ *
+ * @param {{name?: string, __packageDir?: string, __packageExports?: Record<string, unknown>|null}} integration
+ * @param {string} docPath
+ * @param {Record<string, any> | null} doc
+ * @returns {string | null | undefined}
+ */
+export function importedModule(integration: {
+    name?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
+}, docPath: string, doc: Record<string, any> | null): string | null | undefined;
+/**
+ * The file an import of the package's own name resolves to, through its
+ * package.json `exports` (or `main` when it has none): `@acme/kit` or
+ * `@acme/kit/widget`. Null when the specifier names another package, or the
+ * package publishes nothing at it.
+ * @param {{name?: string, __packageDir?: string, __packageExports?: Record<string, unknown> | null}} integration
+ * @param {string} specifier
+ * @returns {string | null}
+ */
+export function ownPackageModule(integration: {
+    name?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
+}, specifier: string): string | null;
 /**
  * The `.tsx` file in `folder`, or below it, that declares `name`, taking files
  * in path order: the source of a member whose import never reaches a `.tsx`

package/foundation/discovery/component-discovery.mjs

@@ -118,6 +118,16 @@ function scanDocText(text) {
   };
 }
 
+/**
+ * Whether a component doc is hidden (`hidden: true`), read as discovery
+ * reads it: discovery skips a hidden doc.
+ * @param {string} docPath
+ * @returns {boolean}
+ */
+export function isHiddenComponentDoc(docPath) {
+  return readDocMeta(docPath).hidden;
+}
+
 /**
  * Read the `group`, `hiddenComponents`, and `hidden` fields from a
  * component's .doc.mjs file (synchronous), with what {@link scanDocText}
@@ -994,7 +1004,7 @@ function packageMain(packageDir) {
  * @param {Record<string, any> | null} doc
  * @returns {string | null | undefined}
  */
-function importedModule(integration, docPath, doc) {
+export function importedModule(integration, docPath, doc) {
   const packageName = integration?.name;
   const packageDir = integration?.__packageDir;
   if (!packageName || !packageDir) return undefined;
@@ -1024,6 +1034,42 @@ function importedModule(integration, docPath, doc) {
   ).target;
 }
 
+/**
+ * The file an import of the package's own name resolves to, through its
+ * package.json `exports` (or `main` when it has none): `@acme/kit` or
+ * `@acme/kit/widget`. Null when the specifier names another package, or the
+ * package publishes nothing at it.
+ * @param {{name?: string, __packageDir?: string, __packageExports?: Record<string, unknown> | null}} integration
+ * @param {string} specifier
+ * @returns {string | null}
+ */
+export function ownPackageModule(integration, specifier) {
+  const packageName = integration?.name;
+  const packageDir = integration?.__packageDir;
+  if (!packageName || !packageDir) return null;
+  if (specifier !== packageName && !specifier.startsWith(`${packageName}/`)) {
+    return null;
+  }
+  const exportsMap =
+    integration.__packageExports === undefined
+      ? readPackageExports(packageDir)
+      : integration.__packageExports;
+  if (specifier === packageName && exportsMap == null) {
+    return packageMain(packageDir) ?? null;
+  }
+  const subpath =
+    specifier === packageName
+      ? '.'
+      : `./${specifier.slice(packageName.length + 1)}`;
+  return (
+    inspectPackageExport(
+      {name: packageName, exports: exportsMap ?? undefined},
+      packageDir,
+      subpath,
+    ).target ?? null
+  );
+}
+
 /**
  * Whether `file` sits in `folder` or below it.
  * @param {string} folder
@@ -1211,6 +1257,19 @@ export function integrationMemberEntry(doc, record) {
   );
 }
 
+/**
+ * Whether `dir` is a folder to list. A declared root that is a file is
+ * reported by the root check; discovery finds nothing in it.
+ * @param {string} dir
+ */
+function isFolder(dir) {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Visit every component doc under an integration's components root, hidden
  * ones included, in discovery order, with its stem.
@@ -1218,10 +1277,26 @@ export function integrationMemberEntry(doc, record) {
  * @param {(docPath: string, stem: string) => void} visit
  */
 export function forEachIntegrationDoc(componentsDir, visit) {
-  if (!componentsDir || !pathExists(componentsDir)) return;
+  if (!componentsDir || !isFolder(componentsDir)) return;
+  /** @param {string} name */
+  const key = name => {
+    const rank = INTEGRATION_DOC_SUFFIXES.findIndex(s => name.endsWith(s));
+    return rank < 0
+      ? {stem: name, rank}
+      : {stem: name.slice(0, -INTEGRATION_DOC_SUFFIXES[rank].length), rank};
+  };
   /** @param {string} dirPath */
   function scanDir(dirPath) {
-    for (const entry of listDirEntries(dirPath)) {
+    // Name order, and for two docs of one stem the suffix precedence, so the
+    // doc a stem records is the one a lookup by name finds, on every disk.
+    const entries = listDirEntries(dirPath).sort((a, b) => {
+      const left = key(a.name);
+      const right = key(b.name);
+      return left.stem === right.stem
+        ? left.rank - right.rank
+        : byCodeUnit(left.stem, right.stem);
+    });
+    for (const entry of entries) {
       if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
       const fullPath = path.join(dirPath, entry.name);
       if (entry.isDirectory()) {
@@ -1270,7 +1345,7 @@ export function discoverIntegrationComponents(
   {documentedNames = true} = {},
 ) {
   const componentsDir = integration?.components;
-  if (!componentsDir || !pathExists(componentsDir)) return [];
+  if (!componentsDir || !isFolder(componentsDir)) return [];
 
   /** @type {Map<string, {name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>} */
   const byName = new Map();
@@ -1485,7 +1560,7 @@ function findDocumentedComponent(integration, componentsDir, name) {
  */
 export function findIntegrationComponent(integration, name) {
   const componentsDir = integration?.components;
-  if (!componentsDir || !pathExists(componentsDir)) return null;
+  if (!componentsDir || !isFolder(componentsDir)) return null;
   const sameStem = findSameStemDoc(componentsDir, name);
   if (sameStem) {
     const exportName = otherExportName({

package/foundation/discovery/component-loader.d.mts

@@ -43,5 +43,5 @@ export type LoadDocOptions = {
      * which root reads the doc
      * (default: components)
      */
-    root?: "hooks" | "components" | undefined;
+    root?: "components" | "hooks" | undefined;
 };

package/foundation/discovery/docs-discovery.mjs

@@ -423,6 +423,19 @@ export function problemsInNamespace(doc) {
   return problems;
 }
 
+/**
+ * Whether `dir` is a folder to list. A declared root that is a file is
+ * reported by the root check; discovery finds nothing in it.
+ * @param {string} dir
+ */
+function isFolder(dir) {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Discover the topics contributed by a single loaded integration. Mirrors
  * `discoverIntegrationComponents`: walk the resolved root, take every
@@ -450,7 +463,7 @@ export async function discoverIntegrationDocs(integration) {
   const namespaces = [];
   /** @type {import('../doc-compiler/tree.mjs').TreeDocInput[]} */
   const guides = [];
-  if (!docsDir || !fs.existsSync(docsDir)) {
+  if (!docsDir || !isFolder(docsDir)) {
     return {records, errors, namespaces, guides};
   }
   const providerId = integration.providerId ?? integration.name;

package/foundation/discovery/module-exports.d.mts

@@ -18,6 +18,39 @@ export function moduleExportsName(file: string, exportName: string, seen?: Set<s
  * @returns {string | null}
  */
 export function moduleExportSource(file: string, exportName: string, seen?: Set<string>): string | null;
+/**
+ * Every runtime name a module exports that this read can see (`default` for
+ * a default export), or null when it cannot see them all: an `export *`, `export =`, CommonJS exports, or a
+ * file that does not parse.
+ * @param {string} file
+ * @returns {string[] | null}
+ */
+export function moduleExportNames(file: string): string[] | null;
+/**
+ * @typedef {{verdict: 'exports'} | {verdict: 'lacks'} | {verdict: 'unknown', reason: string}} ExportVerdict
+ */
+/**
+ * Whether a module exports `exportName` at runtime, read without executing
+ * it: `exports` when a declaration or a followed re-export binds it, `lacks`
+ * only when every export the module writes was read and none binds it, and
+ * `unknown`, with the first reason, when some export could not be read: a
+ * re-export from another package or from a specifier that resolves to no
+ * file, a destructured binding, a namespace, an ambient or const enum
+ * declaration, `export =`, CommonJS exports, or a file that does not parse.
+ * @param {string} file
+ * @param {string} exportName
+ * @param {Set<string>} [seen]
+ * @returns {ExportVerdict}
+ */
+export function moduleExportVerdict(file: string, exportName: string, seen?: Set<string>): ExportVerdict;
+/**
+ * Whether a module provably does not export `exportName` at runtime: see
+ * {@link moduleExportVerdict}.
+ * @param {string} file
+ * @param {string} exportName
+ * @returns {boolean}
+ */
+export function moduleLacksExport(file: string, exportName: string): boolean;
 /**
  * The object a module exports, as plain data, read without running it: the
  * first of `exportNames` it exports, an object literal in place or a top-level
@@ -35,3 +68,11 @@ export function staticExportObject(file: string, exportNames: readonly string[])
  * enumerable, so the object compares and serializes as its literal properties.
  */
 export const HAS_COMPUTED: unique symbol;
+export type ExportVerdict = {
+    verdict: "exports";
+} | {
+    verdict: "lacks";
+} | {
+    verdict: "unknown";
+    reason: string;
+};