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.mdnew file mode 100644index 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.++@josephfarinadiff --git a/docs/architecture/cli-surface.md b/docs/architecture/cli-surface.mdindex 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. Itgoes 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 couplingdiff --git a/packages/cli/api/doctor/doctor.doc.mjs b/packages/cli/api/doctor/doctor.doc.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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}.