Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

[feat] Autolink installed integrations (#6202)

Joeycf3ae89e40c8
diff --git a/.changeset/autolink-installed-integrations.md b/.changeset/autolink-installed-integrations.md
new file mode 100644
index 0000000000..ebef586b9f
--- /dev/null
+++ b/.changeset/autolink-installed-integrations.md
@@ -0,0 +1,34 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] Load an installed integration even when no `astryx.config` names it (#6202)
+
+A package the project declares as a dependency, and that ships a root
+`astryx.integration.*` manifest, is now loaded on sight — no config entry
+required. A scaffold that adds the dependency and writes no config used to leave
+the integration invisible: its components, templates, docs and codemods all
+reported as missing, which is indistinguishable from not having installed it at
+all.
+
+Only DECLARED dependencies are probed — `dependencies`, `devDependencies` and
+`optionalDependencies` — and only by key. `node_modules` is never walked, so a
+transitive dependency of a dependency cannot contribute; and because the value
+is never parsed, a dependency that is not a semver range (`npm:` aliases,
+`workspace:`, `file:`, `link:`, `catalog:`) resolves like any other. Identity
+comes from the resolved package's own `name`, so an aliased dependency reports
+the package it actually is, and two dependency keys naming one package load it
+once.
+
+An explicit `astryx.config` entry keeps its precedence and its position, and a
+dependency whose manifest fails to load is dropped quietly rather than reported
+as the consuming project's problem.
+
+`astryx doctor` gains an `implicit-integrations` line naming each integration
+linked this way, the package.json field that declared it, and what it
+contributes — so an author can answer "why can the CLI see this?" without
+reading the CLI's source, and an unused-dependency check has something to read
+that says the dependency is load-bearing. The line is always informational, so
+the doctor CI gate is unaffected.
+
+@josephfarina
diff --git a/docs/architecture/cli-surface.md b/docs/architecture/cli-surface.md
index 66b77be39d..62d4a95a02 100644
--- a/docs/architecture/cli-surface.md
+++ b/docs/architecture/cli-surface.md
@@ -19,6 +19,7 @@ verified_by:
clients/cli/error-envelope-code.test.mjs,
foundation/response/error-codes.test.mjs,
foundation/agent-docs/agent-docs.test.mjs,
+ foundation/integrations/autolink.test.mjs,
clients/cli/commands/upgrade.integration-policy.test.mjs,
clients/cli/formatters/index.test.mjs,
]
@@ -64,9 +65,11 @@ rather than left to the command author.
Discovery of components, templates, codemods and docs is not per-command. It
goes through the `Project` seam in `foundation/config`, which resolves the
-integrations named in `astryx.config`. Each integration is loaded
-independently, so one broken package degrades that package's contribution and
-never fails the run.
+integrations named in `astryx.config` and then autolinks any DECLARED dependency
+that ships a root `astryx.integration.*` manifest — a config entry is how a
+project pins an integration, not how the CLI finds one. Each integration is
+loaded independently, so one broken package degrades that package's
+contribution and never fails the run.
AST-017 DEC-4 owns stable response-entry fields and requires their complete type,
test, applicable text, and consumer-documentation projections.
@@ -116,6 +119,14 @@ test, applicable text, and consumer-documentation projections.
render configured integration `agentDocs` through the existing `Project`
seam. Upgrade compares complete block bytes even when Core is unchanged and,
when codemods or hooks run, writes the prepared block only after they succeed.
+- **INV14 — An installed integration is discoverable without configuration, and
+ autolinking it can only add.** A dependency the project DECLARES in
+ package.json, and that ships a root `astryx.integration.*` manifest, is
+ loaded; `node_modules` is never walked, so nothing the project did not declare
+ can contribute. Only the dependency KEY is read, never its value, so an npm
+ alias or a non-semver protocol resolves like any other. A config entry keeps
+ precedence over the same package autolinked, and a dependency whose manifest
+ fails to load is dropped rather than raised as the consuming project's issue.
## Change coupling
diff --git a/packages/cli/api/doctor/doctor.doc.mjs b/packages/cli/api/doctor/doctor.doc.mjs
index 669264125d..007a973e76 100644
--- a/packages/cli/api/doctor/doctor.doc.mjs
+++ b/packages/cli/api/doctor/doctor.doc.mjs
@@ -16,7 +16,8 @@ export const doc = {
description:
'Runs a series of side-effect-free diagnostics: Node version, ' +
'@astryxdesign/core install and version alignment with the CLI, installed ' +
- 'themes and wiring, astryx.config validity, agent docs, core peer ' +
+ 'themes and wiring, astryx.config validity, integrations linked from ' +
+ 'package.json without a config entry, agent docs, core peer ' +
'dependencies, and the detected package manager, and returns a structured ' +
'report. It only reads (never installs, writes, or mutates), so it is safe ' +
'as a CI gate and for agents to invoke.',
diff --git a/packages/cli/api/doctor/doctor.mjs b/packages/cli/api/doctor/doctor.mjs
index e39263fc1a..31ab67eeb6 100644
--- a/packages/cli/api/doctor/doctor.mjs
+++ b/packages/cli/api/doctor/doctor.mjs
@@ -52,6 +52,9 @@ const _require = createRequire(import.meta.url);
* @property {string|null} coreDir - Resolved core package directory, or null.
* @property {string|null} configPath - Resolved astryx.config.mjs path, or null.
* @property {string|null} configTheme - theme value read from config, or null.
+ * @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]|null} [integrations]
+ * Every integration the project loaded, or null when the project could not be
+ * read at all.
* @property {Error|null} [configError] - Error thrown while resolving the config
* path (e.g. multiple config files present), surfaced by checkConfig as a FAIL.
*/
@@ -354,7 +357,91 @@ export async function checkConfig(ctx) {
}
/**
- * Check 6 — agent docs exist and contain the Astryx section markers.
+ * Check 6 — integrations that are loaded without an astryx.config entry.
+ *
+ * The CLI autolinks an installed dependency that ships an
+ * `astryx.integration.*` manifest, so a project can be getting components,
+ * templates, docs and codemods from a package nothing in the project mentions.
+ * Two questions follow, and this line is the answer to both:
+ *
+ * - "Why can the CLI see this?" — asked by an author who greps the project
+ * for the package name and finds nothing. Reading our source should not be
+ * part of that answer.
+ * - "Can I delete this dependency?" — asked by an unused-dependency sweep,
+ * which decides by looking for source imports. In exactly this population
+ * there are none: the manifest is the whole link. Naming the dependency
+ * here marks it load-bearing.
+ *
+ * Always informational. Doctor is a CI gate, and a project that acquired an
+ * integration correctly has done nothing to warn about — the point is to say
+ * what is loaded, never to push anyone into writing a config entry.
+ *
+ * @param {DoctorContext} ctx
+ * @returns {DoctorCheck}
+ */
+export function checkImplicitIntegrations(ctx) {
+ const id = 'implicit-integrations';
+ const label = 'Implicitly linked integrations';
+
+ if (ctx.integrations == null) {
+ return {
+ id,
+ label,
+ status: 'info',
+ message: 'Skipped — the project configuration could not be read.',
+ };
+ }
+
+ const implicit = ctx.integrations.filter(
+ integration => integration.__autolinked,
+ );
+
+ if (implicit.length === 0) {
+ return {
+ id,
+ label,
+ status: 'info',
+ message:
+ ctx.integrations.length > 0
+ ? 'None — every loaded integration is named in astryx.config.'
+ : 'None — no installed dependency ships an astryx.integration.* manifest.',
+ };
+ }
+
+ const described = implicit.map(integration => {
+ const version = integration.version ? `@${integration.version}` : '';
+ // An npm alias installs a package under a different key. The package's own
+ // name is its identity; the KEY is what package.json says and what a
+ // dependency sweep reads, so when they differ both have to be here.
+ const alias =
+ integration.__spec && integration.__spec !== integration.name
+ ? ` (declared as "${integration.__spec}")`
+ : '';
+ const roots = ['components', 'templates', 'docs', 'codemods'].filter(
+ root => integration[/** @type {'components'} */ (root)],
+ );
+ const contributes = roots.length > 0 ? roots.join(', ') : 'nothing';
+ return `${integration.name}${version}${alias} from ${integration.__dependencyField}, contributing ${contributes}`;
+ });
+
+ const plural = implicit.length === 1 ? '' : 's';
+ return {
+ id,
+ label,
+ status: 'info',
+ message:
+ `${implicit.length} integration${plural} loaded from installed ` +
+ `dependencies with no astryx.config entry: ${described.join('; ')}.`,
+ fix:
+ 'Nothing to fix. Keep these dependencies installed. The CLI links them ' +
+ 'from package.json, so an unused-dependency check that looks only for ' +
+ 'source imports will report them as unused. Add them to `integrations` ' +
+ 'in astryx.config.* to make the link explicit.',
+ };
+}
+
+/**
+ * Check 7 — agent docs exist and contain the Astryx section markers.
* @param {DoctorContext} ctx
* @returns {DoctorCheck}
*/
@@ -408,7 +495,7 @@ export function checkAgentDocs(ctx) {
}
/**
- * Check 7 — @astryxdesign/core peer dependencies are satisfied by installed packages.
+ * Check 8 — @astryxdesign/core peer dependencies are satisfied by installed packages.
* @param {DoctorContext} ctx
* @returns {DoctorCheck}
*/
@@ -495,7 +582,7 @@ export function checkPeerDeps(ctx) {
}
/**
- * Check 8 — report the detected package manager, and say so when the project's
+ * Check 9 — report the detected package manager, and say so when the project's
* own declaration disagrees with what is on disk.
*
* Two states are worth surfacing rather than guessing past, because in both the
@@ -561,6 +648,7 @@ export const SYNC_CHECKS = [
checkCoreInstalled,
checkVersionAlignment,
checkThemes,
+ checkImplicitIntegrations,
checkAgentDocs,
checkPeerDeps,
checkPackageManager,
@@ -587,12 +675,16 @@ export async function runChecks(options = {}) {
configError = /** @type {Error} */ (err);
}
- // Resolve a possible theme key from config (best-effort; never throws).
+ // Resolve a possible theme key from config, and the integrations the project
+ // actually loaded (best-effort; never throws).
let configTheme = null;
+ /** @type {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]|null} */
+ let integrations = null;
try {
const project = await Project.load(cwd);
configTheme =
/** @type {{theme?: string}} */ (project.config ?? {}).theme ?? null;
+ integrations = project.loadedIntegrations;
} catch {
// Best-effort: a missing/invalid config leaves configTheme null.
}
@@ -604,6 +696,7 @@ export async function runChecks(options = {}) {
coreDir,
configPath,
configTheme,
+ integrations,
configError,
};
diff --git a/packages/cli/api/doctor/doctor.test.mjs b/packages/cli/api/doctor/doctor.test.mjs
index c76f5f57d3..f132cc494d 100644
--- a/packages/cli/api/doctor/doctor.test.mjs
+++ b/packages/cli/api/doctor/doctor.test.mjs
@@ -11,7 +11,12 @@ import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
-import {doctor, checkVersionAlignment, checkPackageManager} from './doctor.mjs';
+import {
+ doctor,
+ checkImplicitIntegrations,
+ checkVersionAlignment,
+ checkPackageManager,
+} from './doctor.mjs';
const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
const cwd = REPO;
@@ -208,3 +213,83 @@ describe('checkPackageManager', () => {
expect(c.message).toContain('yarn.lock');
});
});
+
+describe('checkImplicitIntegrations', () => {
+ /** @param {object} [fields] */
+ const autolinked = (fields = {}) => ({
+ name: '@acme/widgets',
+ version: '1.0.0',
+ components: '/abs/components',
+ __spec: '@acme/widgets',
+ __autolinked: true,
+ __dependencyField: 'dependencies',
+ ...fields,
+ });
+
+ it('skips when the project could not be read', () => {
+ const c = checkImplicitIntegrations({integrations: null});
+ expect(c.status).toBe('info');
+ expect(c.message).toContain('Skipped');
+ });
+
+ it('reports none when nothing is installed', () => {
+ const c = checkImplicitIntegrations({integrations: []});
+ expect(c.status).toBe('info');
+ expect(c.message).toContain('no installed dependency');
+ expect(c.fix).toBeUndefined();
+ });
+
+ it('reports none when every loaded integration is configured', () => {
+ const c = checkImplicitIntegrations({
+ integrations: [autolinked({__autolinked: false})],
+ });
+ expect(c.status).toBe('info');
+ expect(c.message).toContain('named in astryx.config');
+ });
+
+ it('names the package, the field, and what it contributes', () => {
+ const c = checkImplicitIntegrations({
+ integrations: [autolinked({templates: '/abs/templates'})],
+ });
+ expect(c.message).toContain('@acme/[email protected]');
+ expect(c.message).toContain('from dependencies');
+ expect(c.message).toContain('contributing components, templates');
+ });
+
+ it('names the declared key too when an npm alias makes them differ', () => {
+ const c = checkImplicitIntegrations({
+ integrations: [
+ autolinked({
+ name: '@acme/ui',
+ version: '0.1.22',
+ __spec: '@acme/legacy-ui',
+ }),
+ ],
+ });
+ expect(c.message).toContain('@acme/[email protected]');
+ expect(c.message).toContain('declared as "@acme/legacy-ui"');
+ });
+
+ it('marks the dependency load-bearing for an unused-dependency check', () => {
+ const c = checkImplicitIntegrations({integrations: [autolinked()]});
+ expect(c.fix).toContain('unused-dependency check');
+ expect(c.fix).toContain('astryx.config');
+ });
+
+ it('is always informational, so the CI gate stays green', () => {
+ for (const integrations of [
+ null,
+ [],
+ [autolinked()],
+ [autolinked({components: undefined})],
+ [autolinked({__autolinked: false})],
+ ]) {
+ expect(checkImplicitIntegrations({integrations}).status).toBe('info');
+ }
+ });
+
+ it('is part of the report doctor returns', async () => {
+ const r = await doctor({cwd});
+ expect(r.data.checks.map(c => c.id)).toContain('implicit-integrations');
+ }, SLOW);
+});
diff --git a/packages/cli/foundation/config/project.mjs b/packages/cli/foundation/config/project.mjs
index 6c6d601d92..56921d231d 100644
--- a/packages/cli/foundation/config/project.mjs
+++ b/packages/cli/foundation/config/project.mjs
@@ -14,7 +14,8 @@
* - `Project.load(cwd, {cache})` is the async factory (constructors can't be
* async). It does what loadConfig did — find the config sibling-of
* package.json, import + validate it, load the configured integrations —
- * and nothing more. Discovery is LAZY.
+ * plus autolink the installed ones no config names, and nothing more.
+ * Discovery is LAZY.
* - Discovery methods (components/templates/codemods/docs) are MEMOIZED per
* instance (via the pluggable cache) and orchestrate the EXISTING discovery
* functions — Project never reimplements discovery.
@@ -35,6 +36,7 @@ import * as path from 'node:path';
import {findPresentFiles, loadModuleWithParser} from '../fs/module-loader.mjs';
import {parseConfig} from '../../authoring/config/parse.mjs';
import {loadIntegrations} from '../integrations/integrations.mjs';
+import {autolinkIntegrations} from '../integrations/autolink.mjs';
import {
setProject as setDebugProject,
setEventHandler as setDebugEventHandler,
@@ -244,6 +246,13 @@ export class Project {
: (cache ?? new InMemoryConfigCache());
const configPath = findConfigPath(cwd);
const hash = configContentHash(configPath);
+ // 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.
+ const projectDir = configPath
+ ? path.dirname(configPath)
+ : (findPackageRoot(cwd) ?? cwd);
/** @type {import('../../authoring/config/type').AstryxConfig} */
let config = {integrations: []};
@@ -257,14 +266,29 @@ export class Project {
label: 'astryx.config',
fresh,
});
- const configDir = path.dirname(configPath);
integrations = config.integrations ?? [];
loadedIntegrations = await loadIntegrations(integrations, {
- cwd: configDir,
+ cwd: projectDir,
fresh,
});
}
+ // An installed integration the config does not name is still installed.
+ // This runs whether or not a config exists, because the projects it reaches
+ // are overwhelmingly the ones with no astryx.config at all: a scaffold adds
+ // the dependency and writes no config, and the integration then contributes
+ // nothing for want of a line nobody knew to write. Appended AFTER the
+ // configured ones so an explicit entry keeps its position and its
+ // precedence in every discovery order.
+ loadedIntegrations = [
+ ...loadedIntegrations,
+ ...(await autolinkIntegrations({
+ projectDir,
+ loaded: loadedIntegrations,
+ fresh,
+ })),
+ ];
+
// The debug recorder resolves its settings synchronously, long before any
// command gets here, so this is where a project's `debug` block gets a
// turn. The event is not written until process exit, so settings applied
@@ -314,12 +338,21 @@ export class Project {
return this.#config;
}
- /** Configured integration package names. @returns {string[]} */
+ /**
+ * Integration package names the config names. NOT the full set that is
+ * loaded — an autolinked integration is absent here by definition. For
+ * everything in play, read {@link Project.loadedIntegrations}.
+ * @returns {string[]}
+ */
get integrations() {
return this.#integrations;
}
- /** Resolved loaded integrations (lib/integrations.mjs shape). @returns {import('../integrations/integrations.mjs').LoadedIntegration[]} */
+ /**
+ * Every resolved integration (lib/integrations.mjs shape), configured ones
+ * first, then the autolinked ones (`__autolinked`).
+ * @returns {import('../integrations/integrations.mjs').LoadedIntegration[]}
+ */
get loadedIntegrations() {
return this.#loadedIntegrations;
}
diff --git a/packages/cli/foundation/integrations/autolink.mjs b/packages/cli/foundation/integrations/autolink.mjs
new file mode 100644
index 0000000000..cd81a722cb
--- /dev/null
+++ b/packages/cli/foundation/integrations/autolink.mjs
@@ -0,0 +1,265 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Autolink — load installed integrations that no astryx.config names.
+ *
+ * An integration used to need two things to be visible: the package installed,
+ * and its name written into `astryx.config.*`. In practice the second half goes
+ * missing. A scaffold adds the dependency and writes no config; the package
+ * ships components, templates, docs and codemods; and the CLI reports that none
+ * of it exists. Nothing is broken, so nobody looks — the integration is simply
+ * never used, because we said it was not there.
+ *
+ * Autolink closes that gap from the side that is always true: a package the
+ * project DECLARED as a dependency and that ships a root
+ * `astryx.integration.*` manifest is an integration, config entry or not.
+ *
+ * Two rules bound it:
+ *
+ * - DECLARED dependencies only. We read the dependency KEYS out of the
+ * project's own package.json and resolve those. We never walk node_modules
+ * looking for manifests: a transitive dependency of a dependency did not
+ * ask to contribute to this project, and a tree walk is unbounded work for
+ * an answer the project already wrote down.
+ * - The KEY, never the VALUE. `"@acme/legacy-ui": "npm:@acme/[email protected]"`
+ * is a real, installed shape; so are `workspace:*`, `file:../lib`, `link:`
+ * and `catalog:`. None of them is a semver range, and none of them has to
+ * be parsed: the key is the directory name under node_modules, which is the
+ * only thing resolution needs. Identity still comes from the resolved
+ * package's own package.json `name` (see loadIntegrations), so an aliased
+ * dependency reports the package it actually is.
+ *
+ * An explicit config entry always wins: candidates already loaded from config
+ * are dropped before anything here is imported.
+ *
+ * @position lib — sits between config/project (the caller) and
+ * integrations/integrations (the loader); contributes no discovery of its own.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {findManifestPaths, loadIntegrations} from './integrations.mjs';
+
+/**
+ * package.json fields whose keys name a dependency this project installs.
+ *
+ * `peerDependencies` is deliberately absent: a peer is a requirement the
+ * CONSUMER must satisfy, not something this project's install brings in, so a
+ * peer that happens to be present is not a declaration that it belongs here.
+ *
+ * @type {readonly string[]}
+ */
+export const DEPENDENCY_FIELDS = Object.freeze([
+ 'dependencies',
+ 'devDependencies',
+ 'optionalDependencies',
+]);
+
+/**
+ * Whether a dependency key is a bare package name safe to resolve.
+ *
+ * Mirrors the guard in {@link import('./integrations.mjs').resolvePackageDir}:
+ * a name is a directory under node_modules, so a path segment (`.`, `..`) or an
+ * absolute spec must never reach the resolver, which goes on to dynamically
+ * import what it finds.
+ *
+ * @param {string} name
+ * @returns {boolean}
+ */
+function isBarePackageName(name) {
+ return (
+ typeof name === 'string' &&
+ name.length > 0 &&
+ !path.isAbsolute(name) &&
+ !name.startsWith('@/') &&
+ !name.split('/').some(segment => segment === '.' || segment === '..')
+ );
+}
+
+/**
+ * The dependency names this project declares, in field then declaration order,
+ * each tagged with the field that declared it. A name declared twice keeps the
+ * first field it appeared in.
+ *
+ * Only keys are read. See the file header for why values are never parsed.
+ *
+ * @param {string} projectDir directory holding the project's package.json
+ * @returns {Array<{name: string, field: string}>}
+ */
+export function readDeclaredDependencies(projectDir) {
+ /** @type {Record<string, unknown>} */
+ let pkg;
+ try {
+ pkg = JSON.parse(
+ fs.readFileSync(path.join(projectDir, 'package.json'), 'utf-8'),
+ );
+ } catch {
+ // No package.json, or unreadable/malformed — nothing is declared.
+ return [];
+ }
+
+ /** @type {Array<{name: string, field: string}>} */
+ const declared = [];
+ const seen = new Set();
+ for (const field of DEPENDENCY_FIELDS) {
+ const entry = pkg?.[field];
+ if (entry == null || typeof entry !== 'object' || Array.isArray(entry)) {
+ continue;
+ }
+ for (const name of Object.keys(entry)) {
+ if (seen.has(name) || !isBarePackageName(name)) continue;
+ seen.add(name);
+ declared.push({name, field});
+ }
+ }
+ return declared;
+}
+
+/**
+ * Resolve an installed package's directory the way Node's resolver finds it:
+ * the nearest `node_modules/<name>` walking up from `fromDir`.
+ *
+ * Walking up matters because hoisting is normal — yarn and npm workspaces lift
+ * a workspace member's dependency to the repo root, so the app's own
+ * node_modules can be empty of a package it genuinely declares.
+ *
+ * Presence is decided by the package's own package.json, not the directory, so
+ * a stale empty directory is not mistaken for an install.
+ *
+ * @param {string} name bare package name
+ * @param {string} fromDir directory to start walking up from
+ * @returns {{packageDir: string, hostDir: string}|null} the resolved package
+ * directory and the directory whose node_modules holds it
+ */
+export function resolveInstalledPackageDir(name, fromDir) {
+ if (!isBarePackageName(name)) return null;
+ const segments = name.split('/');
+ let dir = path.resolve(fromDir);
+ for (let i = 0; i < 50; i++) {
+ const packageDir = path.join(dir, 'node_modules', ...segments);
+ if (fs.existsSync(path.join(packageDir, 'package.json'))) {
+ return {packageDir, hostDir: dir};
+ }
+ const parent = path.dirname(dir);
+ if (parent === dir) break;
+ dir = parent;
+ }
+ return null;
+}
+
+/**
+ * Resolve a path through symlinks for identity comparison. pnpm links every
+ * dependency into node_modules from a single content-addressed store, so two
+ * different dependency keys pointing at one package share a real path and
+ * differ in every other way.
+ * @param {string} target
+ * @returns {string}
+ */
+function realPath(target) {
+ try {
+ return fs.realpathSync(target);
+ } catch {
+ return path.resolve(target);
+ }
+}
+
+/**
+ * Declared dependencies that ship an integration manifest and are not already
+ * loaded, in declaration order.
+ *
+ * A candidate must have EXACTLY ONE root manifest. Zero is the ordinary case
+ * (almost every dependency), and more than one is a packaging mistake the
+ * loader treats as a hard error — an error the project did not ask for and
+ * cannot fix, so an ambiguous package is passed over here rather than allowed
+ * to fail the load of a project that merely depends on it.
+ *
+ * @param {string} projectDir directory holding the project's package.json
+ * @param {{exclude?: Iterable<string>}} [options] `exclude` — package
+ * directories already loaded (from config); matched through symlinks
+ * @returns {Array<{spec: string, field: string, packageDir: string, hostDir: string}>}
+ */
+export function findAutolinkCandidates(projectDir, {exclude = []} = {}) {
+ const taken = new Set([...exclude].map(realPath));
+ /** @type {Array<{spec: string, field: string, packageDir: string, hostDir: string}>} */
+ const candidates = [];
+
+ for (const {name, field} of readDeclaredDependencies(projectDir)) {
+ const resolved = resolveInstalledPackageDir(name, projectDir);
+ if (!resolved) continue;
+
+ // Two dependency keys can name one installed package — an npm alias beside
+ // the package it aliases, or the two spellings of a package mid-rename
+ // resolving through one store entry. Load it once.
+ const identity = realPath(resolved.packageDir);
+ if (taken.has(identity)) continue;
+
+ if (findManifestPaths(resolved.packageDir).length !== 1) continue;
+
+ taken.add(identity);
+ candidates.push({spec: name, field, ...resolved});
+ }
+
+ return candidates;
+}
+
+/**
+ * Load every declared dependency that ships an integration manifest and is not
+ * already loaded from config.
+ *
+ * Each candidate is loaded in isolation. A dependency the project never asked
+ * to be an integration must not be able to take down `Project.load` for the
+ * whole project, so a manifest that throws on import is dropped here with the
+ * rest of that package's contributions — including the load-error marker
+ * `loadIntegrations` returns for it. A CONFIGURED integration is the opposite
+ * case: the project named it, so its failure is an issue the project owns and
+ * can act on. An autolinked one is a dependency's own packaging bug, which the
+ * consuming project can neither fix nor silence, and which
+ * `astryx doctor integration validate <package>` reports on demand.
+ *
+ * @param {object} options
+ * @param {string} options.projectDir directory holding the project's package.json
+ * @param {import('./integrations.mjs').LoadedIntegration[]} [options.loaded]
+ * integrations already loaded from config; these win
+ * @param {boolean} [options.fresh]
+ * @returns {Promise<import('./integrations.mjs').LoadedIntegration[]>}
+ */
+export async function autolinkIntegrations({
+ projectDir,
+ loaded = [],
+ fresh = false,
+}) {
+ const candidates = findAutolinkCandidates(projectDir, {
+ exclude: loaded.map(integration => integration.__packageDir),
+ });
+
+ /** @type {import('./integrations.mjs').LoadedIntegration[]} */
+ const autolinked = [];
+ const names = new Set(loaded.map(integration => integration.name));
+
+ for (const candidate of candidates) {
+ /** @type {import('./integrations.mjs').LoadedIntegration|undefined} */
+ let integration;
+ try {
+ // Resolve from the directory whose node_modules actually holds the
+ // package, so a hoisted dependency resolves the same way Node found it.
+ [integration] = await loadIntegrations([candidate.spec], {
+ cwd: candidate.hostDir,
+ fresh,
+ });
+ } catch {
+ continue;
+ }
+ if (!integration || integration.__loadError) continue;
+ // Identity is the resolved package's own name, so an alias and the package
+ // it aliases collapse here even when they are two directories on disk.
+ if (names.has(integration.name)) continue;
+ names.add(integration.name);
+ autolinked.push({
+ ...integration,
+ __autolinked: true,
+ __dependencyField: candidate.field,
+ });
+ }
+
+ return autolinked;
+}
diff --git a/packages/cli/foundation/integrations/autolink.test.mjs b/packages/cli/foundation/integrations/autolink.test.mjs
new file mode 100644
index 0000000000..d9cc3ee14a
--- /dev/null
+++ b/packages/cli/foundation/integrations/autolink.test.mjs
@@ -0,0 +1,430 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated tests for autolink — loading an installed integration the
+ * config does not name.
+ *
+ * The fixtures are the shapes that actually exist in the projects this
+ * targets: a scaffold that added the dependency and wrote no config, an npm
+ * alias, a package mid-rename declared under both spellings, and a hoisted
+ * install. Temp dirs are repo-local because the loader dynamically imports the
+ * manifest and Vite refuses to import out of the OS temp dir.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+ DEPENDENCY_FIELDS,
+ autolinkIntegrations,
+ findAutolinkCandidates,
+ readDeclaredDependencies,
+ resolveInstalledPackageDir,
+} from './autolink.mjs';
+import {Project} from '../config/project.mjs';
+
+let tmpDir;
+
+beforeEach(() => {
+ tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-autolink-test-'));
+});
+
+afterEach(() => {
+ fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * Write a project package.json.
+ * @param {string} dir
+ * @param {object} fields
+ */
+function writeProject(dir, fields = {}) {
+ fs.mkdirSync(dir, {recursive: true});
+ fs.writeFileSync(
+ path.join(dir, 'package.json'),
+ JSON.stringify({name: 'consumer', ...fields}),
+ );
+}
+
+/**
+ * Install a package under `<hostDir>/node_modules/<installAs>`.
+ *
+ * `installAs` is the directory (what an npm alias controls); `name` is the
+ * package's own identity, which is a different string exactly when the
+ * dependency is aliased.
+ *
+ * @param {string} hostDir
+ * @param {object} options
+ * @returns {string} the installed package directory
+ */
+function installPackage(
+ hostDir,
+ {
+ installAs,
+ name = installAs,
+ version = '1.0.0',
+ manifest = {components: './components'},
+ manifestBasenames = ['astryx.integration.mjs'],
+ componentName = 'Widget',
+ } = {},
+) {
+ const pkgDir = path.join(hostDir, 'node_modules', ...installAs.split('/'));
+ fs.mkdirSync(pkgDir, {recursive: true});
+ fs.writeFileSync(
+ path.join(pkgDir, 'package.json'),
+ JSON.stringify({name, version}),
+ );
+ for (const basename of manifestBasenames) {
+ fs.writeFileSync(
+ path.join(pkgDir, basename),
+ typeof manifest === 'string'
+ ? manifest
+ : `export default ${JSON.stringify(manifest)};\n`,
+ );
+ }
+ if (manifest && typeof manifest === 'object' && manifest.components) {
+ const componentsDir = path.join(pkgDir, 'components');
+ fs.mkdirSync(componentsDir, {recursive: true});
+ fs.writeFileSync(
+ path.join(componentsDir, `${componentName}.doc.mjs`),
+ `export const docs = {name: '${componentName}', usage: {description: 'A widget'}};\n`,
+ );
+ fs.writeFileSync(
+ path.join(componentsDir, `${componentName}.tsx`),
+ `export function ${componentName}() { return null; }\n`,
+ );
+ }
+ return pkgDir;
+}
+
+/** @param {string} dir @param {string[]} integrations */
+function writeConfig(dir, integrations) {
+ fs.writeFileSync(
+ path.join(dir, 'astryx.config.mjs'),
+ `export default ${JSON.stringify({integrations})};\n`,
+ );
+}
+
+describe('readDeclaredDependencies', () => {
+ it('reads dependencies, devDependencies and optionalDependencies — not peerDependencies', () => {
+ writeProject(tmpDir, {
+ dependencies: {a: '1'},
+ devDependencies: {b: '1'},
+ optionalDependencies: {c: '1'},
+ peerDependencies: {d: '1'},
+ });
+ const declared = readDeclaredDependencies(tmpDir);
+ expect(declared.map(entry => entry.name)).toEqual(['a', 'b', 'c']);
+ expect(declared.map(entry => entry.field)).toEqual(DEPENDENCY_FIELDS);
+ });
+
+ it('keeps the first field a name is declared in', () => {
+ writeProject(tmpDir, {
+ dependencies: {a: '1'},
+ devDependencies: {a: '2'},
+ });
+ expect(readDeclaredDependencies(tmpDir)).toEqual([
+ {name: 'a', field: 'dependencies'},
+ ]);
+ });
+
+ it('refuses a key that is not a bare package name', () => {
+ writeProject(tmpDir, {
+ dependencies: {'../evil': '1', '/abs': '1', './rel': '1', ok: '1'},
+ });
+ expect(readDeclaredDependencies(tmpDir).map(e => e.name)).toEqual(['ok']);
+ });
+
+ it('is empty when there is no readable package.json', () => {
+ expect(readDeclaredDependencies(tmpDir)).toEqual([]);
+ fs.writeFileSync(path.join(tmpDir, 'package.json'), '{not json');
+ expect(readDeclaredDependencies(tmpDir)).toEqual([]);
+ });
+});
+
+describe('resolveInstalledPackageDir', () => {
+ it('finds a package hoisted to a parent node_modules', () => {
+ const appDir = path.join(tmpDir, 'apps', 'web');
+ writeProject(appDir);
+ installPackage(tmpDir, {installAs: '@acme/widgets'});
+ const resolved = resolveInstalledPackageDir('@acme/widgets', appDir);
+ expect(resolved?.hostDir).toBe(tmpDir);
+ expect(resolved?.packageDir).toBe(
+ path.join(tmpDir, 'node_modules', '@acme', 'widgets'),
+ );
+ });
+
+ it('prefers the nearest node_modules', () => {
+ const appDir = path.join(tmpDir, 'apps', 'web');
+ writeProject(appDir);
+ installPackage(tmpDir, {installAs: '@acme/widgets'});
+ installPackage(appDir, {installAs: '@acme/widgets'});
+ expect(resolveInstalledPackageDir('@acme/widgets', appDir)?.hostDir).toBe(
+ appDir,
+ );
+ });
+
+ it('is null for a directory with no package.json', () => {
+ writeProject(tmpDir);
+ fs.mkdirSync(path.join(tmpDir, 'node_modules', 'empty'), {recursive: true});
+ expect(resolveInstalledPackageDir('empty', tmpDir)).toBeNull();
+ expect(resolveInstalledPackageDir('../escape', tmpDir)).toBeNull();
+ });
+});
+
+describe('findAutolinkCandidates', () => {
+ it('probes declared dependencies only — never walks node_modules', () => {
+ writeProject(tmpDir, {dependencies: {'@acme/widgets': '^1.0.0'}});
+ installPackage(tmpDir, {installAs: '@acme/widgets'});
+ installPackage(tmpDir, {installAs: '@acme/undeclared'});
+
+ const candidates = findAutolinkCandidates(tmpDir);
+ expect(candidates.map(candidate => candidate.spec)).toEqual([
+ '@acme/widgets',
+ ]);
+ });
+
+ it('ignores a transitive dependency that ships a manifest', () => {
+ writeProject(tmpDir, {dependencies: {'@acme/widgets': '^1.0.0'}});
+ const pkgDir = installPackage(tmpDir, {installAs: '@acme/widgets'});
+ // @acme/widgets depends on @acme/inner; the project does not.
+ fs.writeFileSync(
+ path.join(pkgDir, 'package.json'),
+ JSON.stringify({
+ name: '@acme/widgets',
+ version: '1.0.0',
+ dependencies: {'@acme/inner': '^1.0.0'},
+ }),
+ );
+ installPackage(tmpDir, {installAs: '@acme/inner'});
+
+ expect(findAutolinkCandidates(tmpDir).map(c => c.spec)).toEqual([
+ '@acme/widgets',
+ ]);
+ });
+
+ it('skips a declared dependency with no manifest', () => {
+ writeProject(tmpDir, {dependencies: {react: '^19.0.0'}});
+ installPackage(tmpDir, {installAs: 'react', manifestBasenames: []});
+ expect(findAutolinkCandidates(tmpDir)).toEqual([]);
+ });
+
+ it('skips a package with more than one root manifest instead of failing', () => {
+ writeProject(tmpDir, {dependencies: {'@acme/widgets': '^1.0.0'}});
+ installPackage(tmpDir, {
+ installAs: '@acme/widgets',
+ manifestBasenames: ['astryx.integration.mjs', 'astryx.integration.js'],
+ });
+ expect(findAutolinkCandidates(tmpDir)).toEqual([]);
+ });
+
+ it('collapses two dependency keys that link to one package directory', () => {
+ // pnpm links every dependency from one store entry, so the two spellings of
+ // a package mid-rename share a real path.
+ writeProject(tmpDir, {
+ dependencies: {'@acme/legacy-ui': '^0.5.0', '@acme/ui': '^0.1.0'},
+ });
+ const real = installPackage(tmpDir, {
+ installAs: '@acme/ui',
+ name: '@acme/ui',
+ version: '0.1.22',
+ });
+ const linkDir = path.join(tmpDir, 'node_modules', '@acme');
+ fs.mkdirSync(linkDir, {recursive: true});
+ fs.symlinkSync(real, path.join(linkDir, 'legacy-ui'), 'dir');
+
+ const candidates = findAutolinkCandidates(tmpDir);
+ expect(candidates).toHaveLength(1);
+ expect(candidates[0].spec).toBe('@acme/legacy-ui');
+ });
+
+ it('excludes package directories already loaded', () => {
+ writeProject(tmpDir, {dependencies: {'@acme/widgets': '^1.0.0'}});
+ const pkgDir = installPackage(tmpDir, {installAs: '@acme/widgets'});
+ expect(findAutolinkCandidates(tmpDir, {exclude: [pkgDir]})).toEqual([]);
+ });
+});
+
+describe('autolinkIntegrations', () => {
+ it('loads a declared dependency that ships a manifest, and marks it', async () => {
+ writeProject(tmpDir, {dependencies: {'@acme/widgets': '^1.0.0'}});
+ installPackage(tmpDir, {installAs: '@acme/widgets'});
+
+ const [integration, ...rest] = await autolinkIntegrations({
+ projectDir: tmpDir,
+ });
+ expect(rest).toEqual([]);
+ expect(integration.name).toBe('@acme/widgets');
+ expect(integration.__autolinked).toBe(true);
+ expect(integration.__dependencyField).toBe('dependencies');
+ expect(integration.components).toBe(
+ path.join(tmpDir, 'node_modules', '@acme', 'widgets', 'components'),
+ );
+ });
+
+ it('reads the dependency KEY, never the value', async () => {
+ // Every one of these is a real installed shape and none is a semver range.
+ writeProject(tmpDir, {
+ dependencies: {
+ '@acme/legacy-ui': 'npm:@acme/[email protected]',
+ '@acme/linked': 'link:../linked',
+ '@acme/filed': 'file:../filed',
+ },
+ devDependencies: {
+ '@acme/workspaced': 'workspace:*',
+ '@acme/cataloged': 'catalog:',
+ },
+ });
+ // The aliased key installs a package whose own name is the aliased one.
+ installPackage(tmpDir, {
+ installAs: '@acme/legacy-ui',
+ name: '@acme/ui',
+ version: '0.1.22',
+ });
+ for (const installAs of [
+ '@acme/linked',
+ '@acme/filed',
+ '@acme/workspaced',
+ '@acme/cataloged',
+ ]) {
+ installPackage(tmpDir, {installAs});
+ }
+
+ const loaded = await autolinkIntegrations({projectDir: tmpDir});
+ expect(loaded.map(i => i.name)).toEqual([
+ // Identity is the resolved package's own name, not the key it is under.
+ '@acme/ui',
+ '@acme/linked',
+ '@acme/filed',
+ '@acme/workspaced',
+ '@acme/cataloged',
+ ]);
+ const aliased = loaded[0];
+ expect(aliased.__spec).toBe('@acme/legacy-ui');
+ expect(aliased.version).toBe('0.1.22');
+ });
+
+ it('loads one integration when both spellings of a rename are installed', async () => {
+ // Mid-rename, with two directories on disk rather than one linked store
+ // entry: the package name is the identity that collapses them.
+ writeProject(tmpDir, {
+ dependencies: {'@acme/legacy-ui': '^0.5.0', '@acme/ui': '^0.1.0'},
+ });
+ installPackage(tmpDir, {
+ installAs: '@acme/legacy-ui',
+ name: '@acme/ui',
+ version: '0.1.22',
+ });
+ installPackage(tmpDir, {
+ installAs: '@acme/ui',
+ name: '@acme/ui',
+ version: '0.1.22',
+ });
+
+ const loaded = await autolinkIntegrations({projectDir: tmpDir});
+ expect(loaded).toHaveLength(1);
+ expect(loaded[0].name).toBe('@acme/ui');
+ });
+
+ it('does not load one already loaded from config', async () => {
+ writeProject(tmpDir, {dependencies: {'@acme/widgets': '^1.0.0'}});
+ const pkgDir = installPackage(tmpDir, {installAs: '@acme/widgets'});
+ const loaded = await autolinkIntegrations({
+ projectDir: tmpDir,
+ loaded: [
+ /** @type {any} */ ({name: '@acme/widgets', __packageDir: pkgDir}),
+ ],
+ });
+ expect(loaded).toEqual([]);
+ });
+
+ it('drops a dependency whose manifest is broken, and raises no issue for it', async () => {
+ // The project cannot fix a dependency's packaging bug, so autolink must not
+ // hand it one to look at. Both failure modes: a manifest that throws on
+ // import, and one that loads but fails schema validation.
+ writeProject(tmpDir, {
+ dependencies: {
+ '@acme/throws': '^1.0.0',
+ '@acme/invalid': '^1.0.0',
+ '@acme/widgets': '^1.0.0',
+ },
+ });
+ installPackage(tmpDir, {
+ installAs: '@acme/throws',
+ manifest: 'throw new Error("boom");\n',
+ });
+ installPackage(tmpDir, {
+ installAs: '@acme/invalid',
+ manifest: {components: 42},
+ });
+ installPackage(tmpDir, {installAs: '@acme/widgets'});
+
+ const loaded = await autolinkIntegrations({projectDir: tmpDir});
+ expect(loaded.map(i => i.name)).toEqual(['@acme/widgets']);
+
+ const project = await Project.load(tmpDir);
+ expect(await project.issues()).toEqual([]);
+ });
+});
+
+describe('Project.load with autolink', () => {
+ it('discovers components from an installed integration with no config at all', async () => {
+ // The population this exists for: the scaffold added the dependency and
+ // wrote no astryx.config, so the CLI used to report the component missing.
+ writeProject(tmpDir, {dependencies: {'@acme/widgets': '^1.0.0'}});
+ installPackage(tmpDir, {
+ installAs: '@acme/widgets',
+ componentName: 'MetaOncall',
+ });
+
+ const project = await Project.load(tmpDir);
+ expect(project.configPath).toBeNull();
+ expect(project.integrations).toEqual([]);
+ expect(project.loadedIntegrations.map(i => i.name)).toEqual([
+ '@acme/widgets',
+ ]);
+ const components = await project.components();
+ expect(components.map(component => component.name)).toContain('MetaOncall');
+ });
+
+ it('keeps a configured integration explicit and puts autolinked ones after it', async () => {
+ writeProject(tmpDir, {
+ dependencies: {'@acme/widgets': '^1.0.0', '@acme/extras': '^1.0.0'},
+ });
+ writeConfig(tmpDir, ['@acme/widgets']);
+ installPackage(tmpDir, {installAs: '@acme/widgets'});
+ installPackage(tmpDir, {
+ installAs: '@acme/extras',
+ componentName: 'Extra',
+ });
+
+ const project = await Project.load(tmpDir);
+ expect(project.integrations).toEqual(['@acme/widgets']);
+ expect(
+ project.loadedIntegrations.map(i => [i.name, i.__autolinked ?? false]),
+ ).toEqual([
+ ['@acme/widgets', false],
+ ['@acme/extras', true],
+ ]);
+ });
+
+ it('resolves a dependency hoisted to a workspace root', async () => {
+ const appDir = path.join(tmpDir, 'apps', 'web');
+ writeProject(appDir, {dependencies: {'@acme/widgets': '^1.0.0'}});
+ installPackage(tmpDir, {installAs: '@acme/widgets'});
+
+ const project = await Project.load(appDir);
+ expect(project.loadedIntegrations.map(i => i.name)).toEqual([
+ '@acme/widgets',
+ ]);
+ });
+
+ it('leaves a project with no astryx dependencies untouched', async () => {
+ writeProject(tmpDir, {dependencies: {react: '^19.0.0'}});
+ installPackage(tmpDir, {installAs: 'react', manifestBasenames: []});
+
+ const project = await Project.load(tmpDir);
+ expect(project.loadedIntegrations).toEqual([]);
+ expect(await project.issues()).toEqual([]);
+ });
+});
diff --git a/packages/cli/foundation/integrations/integrations.mjs b/packages/cli/foundation/integrations/integrations.mjs
index a6014a0d8d..d76e7264c3 100644
--- a/packages/cli/foundation/integrations/integrations.mjs
+++ b/packages/cli/foundation/integrations/integrations.mjs
@@ -49,6 +49,12 @@ import {importUserModule, findPresentFiles} from '../fs/module-loader.mjs';
* such an integration contributes nothing and is surfaced via Project.issues()
* @property {string[]} [__unknownKeys] manifest keys this CLI does not know —
* surfaced as a warning; the rest of the manifest still contributes
+ * @property {boolean} [__autolinked] loaded because the project declares the
+ * package as a dependency and it ships a manifest, with no astryx.config
+ * entry naming it — see foundation/integrations/autolink.mjs
+ * @property {string} [__dependencyField] for an autolinked integration, the
+ * package.json field that declared it (`dependencies`, `devDependencies`,
+ * `optionalDependencies`)
* @property {import('../../authoring/debug/type').DebugEventHandler} [__debug]
* the manifest module's `debug` NAMED export, when it exported a function.
* Not a manifest key — see {@link loadManifest}.