Skip to content

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

TypeScript
11.6 KB
Raw Blame
// 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: a dependency whose directory is
 * already loaded from config is never imported again, and comes back as a
 * repeat so the provider ledger still records it.
 *
 * @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';
import {resolveProviders} from './provider-resolution.mjs';
import {
  isBarePackageName,
  resolveInstalledPackageDir,
} from './installed-package.mjs';

export {resolveInstalledPackageDir};

/**
 * 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',
]);


/**
 * 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 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);
  }
}

/**
 * @typedef {object} AutolinkCandidate
 * @property {string} spec
 * @property {string} field
 * @property {string} packageDir
 * @property {string} hostDir
 * @property {boolean} [repeat] the directory is already loaded or already a
 *   candidate under another dependency key; it is not loaded again
 */

/**
 * Every declared dependency that ships exactly one root manifest, in
 * declaration order, including the ones whose directory is already loaded or
 * already a candidate (`repeat`), so a caller can account for each of them.
 *
 * @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 {AutolinkCandidate[]}
 */
export function scanAutolinkCandidates(projectDir, {exclude = []} = {}) {
  const taken = new Set([...exclude].map(realPath));
  /** @type {AutolinkCandidate[]} */
  const candidates = [];

  for (const {name, field} of readDeclaredDependencies(projectDir)) {
    const resolved = resolveInstalledPackageDir(name, projectDir);
    if (!resolved) continue;

    if (findManifestPaths(resolved.packageDir).length !== 1) 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)) {
      candidates.push({spec: name, field, ...resolved, repeat: true});
      continue;
    }

    taken.add(identity);
    candidates.push({spec: name, field, ...resolved});
  }

  return candidates;
}

/**
 * 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, options) {
  return scanAutolinkCandidates(projectDir, options)
    .filter(candidate => !candidate.repeat)
    .map(({spec, field, packageDir, hostDir}) => ({
      spec,
      field,
      packageDir,
      hostDir,
    }));
}

/**
 * Load every autolink candidate, each in isolation, as provider candidates for
 * {@link resolveProviders}. Nothing is filtered here: a candidate whose load
 * throws or whose manifest fails comes back with its error, and a repeated
 * directory comes back unloaded, so the resolver records each one.
 *
 * @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
 * @param {boolean} [options.fresh]
 * @returns {Promise<import('./provider-resolution.mjs').ProviderCandidate[]>}
 */
export async function loadAutolinkCandidates({
  projectDir,
  loaded = [],
  fresh = false,
}) {
  const scanned = scanAutolinkCandidates(projectDir, {
    // A configured entry that never resolved to a directory has none to exclude.
    exclude: loaded.flatMap(integration =>
      typeof integration.__packageDir === 'string'
        ? [integration.__packageDir]
        : [],
    ),
  });

  /** @type {import('./provider-resolution.mjs').ProviderCandidate[]} */
  const candidates = [];
  for (const candidate of scanned) {
    const {spec, packageDir} = candidate;
    if (candidate.repeat) {
      candidates.push({source: 'autolinked', spec, packageDir, repeat: true});
      continue;
    }
    try {
      // Resolve from the directory whose node_modules actually holds the
      // package, so a hoisted dependency resolves the same way Node found it.
      const [integration] = await loadIntegrations([spec], {
        cwd: candidate.hostDir,
        fresh,
      });
      candidates.push({
        source: 'autolinked',
        spec,
        packageDir,
        ...(integration == null
          ? {}
          : {
              integration: {
                ...integration,
                __autolinked: true,
                __dependencyField: candidate.field,
              },
            }),
      });
    } catch (error) {
      candidates.push({
        source: 'autolinked',
        spec,
        packageDir,
        error: error instanceof Error ? error.message : String(error),
      });
    }
  }
  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.
 *
 * One package reached twice (an alias beside the package it aliases, at the
 * same version) loads once. The same name at another version is kept, so the
 * provider pass reports it instead of dropping it. Project.load does not call
 * this; it hands {@link loadAutolinkCandidates} to the resolver, whose ledger
 * records every candidate dropped here.
 *
 * @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 = await loadAutolinkCandidates({projectDir, loaded, fresh});
  const {ledger} = resolveProviders([
    ...loaded.map(integration => ({
      source: /** @type {const} */ ('configured'),
      integration,
      spec: integration.__spec,
    })),
    ...candidates,
  ]);
  /** @type {import('./integrations.mjs').LoadedIntegration[]} */
  const autolinked = [];
  for (const entry of ledger.values()) {
    const {candidate} = entry;
    if (
      candidate.source === 'autolinked' &&
      candidate.integration != null &&
      (entry.outcome === 'contributes' || entry.outcome === 'set-aside')
    ) {
      autolinked.push(candidate.integration);
    }
  }
  return autolinked;
}