Skip to content

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

TypeScript
29.7 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Path resolution utilities for Astryx CLI
 *
 * Finds the Astryx project a folder belongs to and its workspace root, the
 * project's @astryxdesign/core and the other packages it installed, and the
 * CLI package root.
 */

import * as fs from 'node:fs';
import {createRequire} from 'node:module';
import * as os from 'node:os';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
import {
  findEntry,
  listDir,
  listDirEntries,
  listingCacheActive,
  pathExists,
} from './listing-cache.mjs';
import {ERROR_CODES} from '../response/error-codes.mjs';
import {carriedCore, runChoice} from '../release/run-context.mjs';
import {findDeclaringPackage} from '../release/project.mjs';
import {hostedRun, recordResolved} from '../runtime/package-root.mjs';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

/** Root of the @astryxdesign/cli package */
export const CLI_ROOT = path.resolve(__dirname, '..', '..');

/** The package every Core lookup answers for. */
const CORE_PACKAGE = '@astryxdesign/core';

/**
 * The Core a command answers from: the project's (see
 * {@link findProjectCoreDir}), else, when a copy other than the project's own
 * CLI answers, the Core that copy carries (spec AST-081 FR3): the
 * `@astryxdesign/core` of its own release, beside it or in the per-user
 * release cache. Never fetches; {@link requireCoreDir} does.
 *
 * Commands that judge or change a project (`doctor`, `swizzle`, `upgrade`)
 * read {@link findProjectCoreDir} instead, so a carried Core never passes a
 * project check or lands in a folder that installed none.
 *
 * @param {string} [startDir]
 * @returns {string | null}
 */
export function findCoreDir(startDir = process.cwd()) {
  const own = findProjectCoreDir(startDir);
  return own
    ? noteCore(own, 'project')
    : noteCore(carriedCoreFor(startDir).dir);
}

/**
 * Note the Core a hosted run reads, for the record its host entry returns
 * (architecture:cli-surface INV30). Does nothing outside a hosted run.
 * @template {string | null} T
 * @param {T} dir
 * @param {'project'} [source] where it came from, when the caller knows
 * @returns {T}
 */
function noteCore(dir, source) {
  if (dir && hostedRun()) {
    let version;
    try {
      version = JSON.parse(
        fs.readFileSync(path.join(dir, 'package.json'), 'utf8'),
      ).version;
    } catch {
      version = null;
    }
    recordResolved('@astryxdesign/core', version, dir, source);
  }
  return dir;
}

/**
 * Why a command that reads Core cannot run, when the answering release's own
 * Core is needed and cannot be installed: outside a project, or in a project
 * with nothing installed (spec AST-081 FR3).
 * @param {{unavailable: string | null, version?: string, reason?: string}} found
 * @param {boolean} inProject
 * @returns {string}
 */
export function unavailableCoreMessage(found, inProject) {
  const unwritable = /cannot be written/.test(found.unavailable ?? '');
  if (inProject) {
    const core = found.version ? `Core ${found.version}` : 'its Core';
    const why = found.reason ? ` (${found.reason})` : '';
    return `This project has no Core installed, and ${core} could not be downloaded${why}. Install the project's dependencies${unwritable ? ', or make that folder writable' : ''}, then run again.`;
  }
  return `${found.unavailable}. Outside a project, commands that read Core use the Core of the release that answers; ${unwritable ? 'make that folder writable and run again' : 'run again when the package registry can be reached'}.`;
}

/**
 * Like {@link findCoreDir}, but a copy that carries no Core installs its
 * release's Core into the per-user cache first. Throws ERR_CORE_NOT_FOUND
 * when there is no Core to answer from, and ERR_VERSIONS_UNAVAILABLE when the
 * carried Core is needed and cannot be installed.
 *
 * @param {string} [startDir]
 * @returns {string}
 */
export function requireCoreDir(startDir = process.cwd()) {
  const found = findProjectCoreDir(startDir) ?? carriedCoreFor(startDir, true);
  if (typeof found === 'string') return noteCore(found, 'project');
  if (found.unavailable) {
    throw codedError(
      unavailableCoreMessage(found, runChoice(startDir).inProject),
      ERROR_CODES.ERR_VERSIONS_UNAVAILABLE,
    );
  }
  if (found.dir) return noteCore(found.dir);
  throw codedError(
    'Could not find @astryxdesign/core package',
    ERROR_CODES.ERR_CORE_NOT_FOUND,
  );
}

/**
 * An Error carrying a stable error code, which the JSON envelope and every
 * command's error output read the way they read an API error's.
 * @param {string} message
 * @param {string} code
 * @returns {Error & {code: string}}
 */
function codedError(message, code) {
  return Object.assign(new Error(message), {code});
}

/**
 * The carried Core alone, for a caller that already looked for the project's
 * Core its own way: the folder, or null when the copy answering in `startDir`
 * is the project's own CLI or carries none.
 * @param {string} startDir
 * @param {{fetch?: boolean}} [options]
 * @returns {string | null}
 */
export function findCarriedCoreDir(startDir, {fetch = false} = {}) {
  return carriedCoreFor(startDir, fetch).dir;
}

/**
 * The carried Core for a run in `startDir`, when the copy answering there is
 * not the project's own CLI.
 * @param {string} startDir
 * @param {boolean} [fetch]
 * @returns {{dir: string | null, unavailable: string | null, version?: string, reason?: string}}
 */
function carriedCoreFor(startDir, fetch = false) {
  const carried = carriedCore({fetch: false});
  if (!carried.dir && !fetch) return carried;
  if (runChoice(startDir).copy === 'project') {
    return {dir: null, unavailable: null};
  }
  return carried.dir ? carried : carriedCore({fetch: true});
}

/**
 * The project's own @astryxdesign/core, never a carried one: found from the
 * folder (see {@link findNearbyCoreDir}), else from the folder of the
 * package.json that makes the folder part of a project, however deep the
 * folder is.
 *
 * @param {string} [startDir]
 * @returns {string | null}
 */
export function findProjectCoreDir(startDir = process.cwd()) {
  const near = findNearbyCoreDir(startDir);
  if (near) return near;
  // A folder deeper than that reach still belongs to the project the walk to
  // its package.json finds, so its Core is looked up from there too (spec
  // AST-081, a folder's project): never the carried Core in its place.
  const declaring = findDeclaringPackage(startDir);
  return declaring && declaring.dir !== path.resolve(startDir)
    ? findNearbyCoreDir(declaring.dir)
    : null;
}

/**
 * How many folders, counting the start, the read lookups always search: the
 * reach they had in released versions, so nothing they found before goes
 * missing. Past this reach they continue only up to the workspace root of the
 * Astryx project the start folder belongs to.
 */
const CORE_REACH = 5;
const INSTALLED_REACH = 6;

/** Package scopes whose declaration makes a package.json an Astryx project. */
const ASTRYX_SCOPES = ['@astryxdesign/', '@xds/'];

/** package.json fields in which a package declares what it depends on. */
const DEPENDENCY_FIELDS = [
  'dependencies',
  'devDependencies',
  'optionalDependencies',
  'peerDependencies',
];

/** Folders that mark a repository root; the project search stops there. */
const REPOSITORY_MARKERS = ['.git', '.hg', '.sl'];

/**
 * `startDir` and every folder above it, nearest first, up to the filesystem
 * root: the folders Node's resolver searches for `node_modules`.
 *
 * @param {string} startDir
 * @returns {Generator<string>}
 */
function* foldersUpFrom(startDir) {
  let dir = path.resolve(startDir);
  for (;;) {
    yield dir;
    const parent = path.dirname(dir);
    if (parent === dir) return;
    dir = parent;
  }
}

/**
 * `dir/node_modules/<name>` when the package is installed there. Its
 * package.json decides, so a stale empty folder is not an install.
 *
 * @param {string} dir
 * @param {string} name
 * @returns {string|null}
 */
function installedIn(dir, name) {
  const candidate = path.join(dir, 'node_modules', ...name.split('/'));
  return fs.existsSync(path.join(candidate, 'package.json')) ? candidate : null;
}

/**
 * The package.json in `dir`, or null when it is missing or not a JSON object.
 *
 * @param {string} dir
 * @returns {Record<string, any>|null}
 */
function readPackageJson(dir) {
  try {
    const pkg = JSON.parse(
      fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'),
    );
    return pkg && typeof pkg === 'object' ? pkg : null;
  } catch {
    return null;
  }
}

/**
 * Whether `dir` is @astryxdesign/core's own source, by the name in its
 * package.json. The folder name says nothing: many monorepos keep an unrelated
 * package in `packages/core`.
 *
 * @param {string} dir
 * @returns {boolean}
 */
function isCoreSource(dir) {
  return readPackageJson(dir)?.name === CORE_PACKAGE;
}

/**
 * `p` resolved through symlinks when it exists, so folders compare equal
 * however they were reached.
 *
 * @param {string} p
 * @returns {string}
 */
function realDir(p) {
  try {
    return fs.realpathSync(path.resolve(p));
  } catch {
    return path.resolve(p);
  }
}

/**
 * The home folder, resolved through symlinks, or null when there is none.
 *
 * @returns {string|null}
 */
function homeFolder() {
  try {
    const home = os.homedir();
    return home ? realDir(home) : null;
  } catch {
    return null;
  }
}

/**
 * Whether `child` lies strictly inside `parent`.
 *
 * @param {string} child
 * @param {string} parent
 * @returns {boolean}
 */
function isInside(child, parent) {
  const rel = path.relative(parent, child);
  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
}

/**
 * Whether the package.json in `dir` declares an Astryx package, in any
 * dependency field.
 *
 * @param {string} dir
 * @returns {boolean}
 */
function declaresAstryx(dir) {
  const pkg = readPackageJson(dir);
  if (pkg == null) return false;
  return DEPENDENCY_FIELDS.some(field => {
    const deps = pkg[field];
    return (
      deps != null &&
      typeof deps === 'object' &&
      Object.keys(deps).some(name =>
        ASTRYX_SCOPES.some(scope => name.startsWith(scope)),
      )
    );
  });
}

/**
 * The project root: the directory of the nearest package.json at or above
 * `startDir`, or null when there is none.
 *
 * @param {string} startDir
 * @returns {string|null}
 */
export function findPackageRoot(startDir) {
  for (const dir of foldersUpFrom(startDir)) {
    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
  }
  return null;
}

/**
 * The Astryx project `startDir` belongs to: the nearest folder at or above it
 * whose package.json declares an Astryx package (`@astryxdesign/*`, or the
 * legacy `@xds/*`), or that a workspace whose root declares one lists as a
 * member. The search stops at a repository root, and it ends at the home
 * folder without counting it. Returns null when no folder qualifies.
 *
 * @param {string} startDir
 * @returns {string|null}
 */
export function findAstryxProject(startDir) {
  const start = path.resolve(startDir);
  const home = homeFolder();
  for (const dir of foldersUpFrom(start)) {
    if (home != null && realDir(dir) === home) return null;
    if (declaresAstryx(dir) || isAstryxWorkspaceMember(dir)) return dir;
    if (
      REPOSITORY_MARKERS.some(marker => fs.existsSync(path.join(dir, marker)))
    ) {
      return null;
    }
  }
  return null;
}

/**
 * The workspace root (`spec:AST-048` FR15): the nearest directory at or above
 * `startDir` that declares a workspace, by a `pnpm-workspace.yaml` or a
 * package.json `workspaces` field; outside a workspace, the directory of the
 * nearest package.json; with no package.json, `startDir` itself.
 *
 * @param {string} startDir
 * @returns {string}
 */
export function findWorkspaceRoot(startDir) {
  /** @type {string|null} */
  let nearestPackage = null;
  for (const dir of foldersUpFrom(startDir)) {
    if (
      fs.existsSync(path.join(dir, 'pnpm-workspace.yaml')) ||
      readPackageJson(dir)?.workspaces != null
    ) {
      return dir;
    }
    if (
      nearestPackage == null &&
      fs.existsSync(path.join(dir, 'package.json'))
    ) {
      nearestPackage = dir;
    }
  }
  return nearestPackage ?? path.resolve(startDir);
}

/**
 * The highest folder a lookup for `project`'s packages searches: its
 * workspace root, where a workspace keeps the packages its members share. For
 * a project inside the home folder, never the home folder or above.
 *
 * @param {string} project
 * @returns {string}
 */
function workspaceBound(project) {
  const workspace = findWorkspaceRoot(project);
  const home = homeFolder();
  if (
    home != null &&
    isInside(realDir(project), home) &&
    !isInside(realDir(workspace), home)
  ) {
    return project;
  }
  return workspace;
}

/**
 * Escape `text` for use inside a regular expression.
 * @param {string} text
 * @returns {string}
 */
function escapeRegExp(text) {
  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}

/**
 * The alternatives of the brace list that opens at `glob[start]`, split at
 * its own commas, and the index of its closing brace; null when it is never
 * closed.
 *
 * @param {string} glob
 * @param {number} start
 * @returns {{alternatives: string[], end: number} | null}
 */
function braceList(glob, start) {
  const alternatives = [];
  let depth = 0;
  let from = start + 1;
  for (let i = start; i < glob.length; i++) {
    if (glob[i] === '{') {
      depth++;
    } else if (glob[i] === '}' && --depth === 0) {
      alternatives.push(glob.slice(from, i));
      return {alternatives, end: i};
    } else if (glob[i] === ',' && depth === 1) {
      alternatives.push(glob.slice(from, i));
      from = i + 1;
    }
  }
  return null;
}

/**
 * The regular-expression source for a workspace glob: `*` and `?` stay
 * within one folder name, `**` spans any number of folders, and `{a,b}`
 * matches either alternative, each a glob of its own.
 *
 * @param {string} glob
 * @returns {string}
 */
function globSource(glob) {
  let source = '';
  for (let i = 0; i < glob.length; i++) {
    const char = glob[i];
    const list = char === '{' ? braceList(glob, i) : null;
    if (char === '*' && glob[i + 1] === '*') {
      // `**/` also matches no folder at all.
      source += glob[i + 2] === '/' ? '(?:.*/)?' : '.*';
      i += glob[i + 2] === '/' ? 2 : 1;
    } else if (char === '*') {
      source += '[^/]*';
    } else if (char === '?') {
      source += '[^/]';
    } else if (list) {
      source += `(?:${list.alternatives.map(globSource).join('|')})`;
      i = list.end;
    } else {
      source += escapeRegExp(char);
    }
  }
  return source;
}

/**
 * A regular expression for a workspace pattern, tested against a member's
 * path relative to the workspace root (see `globSource`).
 *
 * @param {string} pattern
 * @returns {RegExp}
 */
function workspacePatternRegExp(pattern) {
  const glob = pattern
    .trim()
    .replace(/^(?:\.\/)+/, '')
    .replace(/\/+$/, '');
  return new RegExp(`^${globSource(glob)}$`);
}

/**
 * The `packages` list in the pnpm-workspace.yaml in `dir`, as block or flow
 * YAML; empty when there is none.
 *
 * @param {string} dir
 * @returns {string[]}
 */
function pnpmWorkspacePatterns(dir) {
  let text;
  try {
    text = fs.readFileSync(path.join(dir, 'pnpm-workspace.yaml'), 'utf-8');
  } catch {
    return [];
  }
  const lines = text.split(/\r?\n/);
  const start = lines.findIndex(line => /^packages\s*:/.test(line));
  if (start === -1) return [];
  /** @param {string} item */
  const unquote = item => item.trim().replace(/^(['"])(.*)\1$/, '$2');
  const inline = lines[start]
    .replace(/^packages\s*:/, '')
    .replace(/\s#.*$/, '')
    .trim();
  if (inline.startsWith('[')) {
    return inline
      .replace(/^\[|\]$/g, '')
      .split(',')
      .map(unquote)
      .filter(Boolean);
  }
  /** @type {string[]} */
  const patterns = [];
  for (const line of lines.slice(start + 1)) {
    if (line.trim() === '' || line.trim().startsWith('#')) continue;
    const item = /^\s*-\s*(.+?)\s*(?:\s#.*)?$/.exec(line);
    if (!item) break;
    patterns.push(unquote(item[1]));
  }
  return patterns;
}

/**
 * Whether the workspace rooted at `root` lists `dir` as a member: a pattern
 * in its package.json `workspaces` (an array, or `{packages: [...]}`) or its
 * pnpm-workspace.yaml `packages` matches `dir`, and no `!` pattern excludes
 * it.
 *
 * @param {string} dir
 * @param {string} root
 * @returns {boolean}
 */
function isWorkspaceMember(dir, root) {
  const rel = path.relative(root, dir).split(path.sep).join('/');
  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return false;
  const workspaces = readPackageJson(root)?.workspaces;
  const patterns = [
    ...(Array.isArray(workspaces) ? workspaces : (workspaces?.packages ?? [])),
    ...pnpmWorkspacePatterns(root),
  ].filter(pattern => typeof pattern === 'string');
  const matches = (/** @type {string} */ pattern) =>
    workspacePatternRegExp(pattern).test(rel);
  return (
    patterns.some(pattern => !pattern.startsWith('!') && matches(pattern)) &&
    !patterns.some(
      pattern => pattern.startsWith('!') && matches(pattern.slice(1)),
    )
  );
}

/**
 * Whether `dir` is a member its workspace lists, where the workspace root
 * declares an Astryx package. Such a member uses the Astryx its workspace
 * installs, so it is an Astryx project of its own.
 *
 * @param {string} dir
 * @returns {boolean}
 */
function isAstryxWorkspaceMember(dir) {
  if (!fs.existsSync(path.join(dir, 'package.json'))) return false;
  const root = workspaceBound(dir);
  return root !== dir && declaresAstryx(root) && isWorkspaceMember(dir, root);
}

/**
 * The folders a read lookup searches, nearest first: `startDir` and the
 * `reach - 1` folders above it, as released versions did; then the root of
 * the Astryx project `startDir` belongs to, if any, and the folders from it up
 * to its workspace root. Past the reach the search starts at the project root,
 * so a folder between the two that installs packages but declares no Astryx
 * package (a tool inside the project) never answers for the project.
 *
 * @param {string} startDir
 * @param {number} reach
 * @returns {Generator<string>}
 */
function* readFolders(startDir, reach) {
  /** @type {Set<string>} */
  const searched = new Set();
  for (const dir of foldersUpFrom(startDir)) {
    if (searched.size >= reach) break;
    searched.add(dir);
    yield dir;
  }
  const project = findAstryxProject(startDir);
  if (project == null) return;
  const bound = workspaceBound(project);
  for (const dir of foldersUpFrom(project)) {
    if (!searched.has(dir)) yield dir;
    if (dir === bound) return;
  }
}

/**
 * The @astryxdesign/core installed for `startDir`.
 *
 * Searches `startDir` and the four folders above it, as released versions
 * did, then on up to the workspace root of the Astryx project it belongs to.
 * In each folder a `packages/core` whose package.json names
 * @astryxdesign/core (the Astryx repository's own source) comes first, then
 * an installed `node_modules/@astryxdesign/core`. It takes the first it finds,
 * whatever version the project declares: that is the copy Node loads. When no
 * folder holds one, it asks Yarn Plug'n'Play, which keeps no node_modules.
 *
 * @param {string} startDir
 * @returns {string|null} the Core package directory, or null when there is none
 */
function findNearbyCoreDir(startDir) {
  for (const dir of readFolders(startDir, CORE_REACH)) {
    const source = path.join(dir, 'packages', 'core');
    if (isCoreSource(source)) return source;
    const installed = installedIn(dir, CORE_PACKAGE);
    if (installed) return installed;
  }
  return findPnpPackage(startDir, CORE_PACKAGE);
}

/**
 * Where Yarn's Plug'n'Play runtime says a package lives.
 *
 * A PnP project has no node_modules for the walks in this file to find. PnP
 * answers from the project's own dependency graph and ignores NODE_PATH, so
 * asking it keeps the lookup project-local. Outside a PnP process there is
 * nothing to ask.
 *
 * @param {string} startDir
 * @param {string} name
 * @returns {string|null}
 */
function findPnpPackage(startDir, name) {
  if (!process.versions.pnp) return null;
  try {
    const from = path.resolve(startDir);
    const api = createRequire(path.join(from, 'noop.js'))('pnpapi');
    const dir = api.resolveToUnqualified(name, path.join(from, '/'));
    return dir && fs.existsSync(path.join(dir, 'package.json')) ? dir : null;
  } catch {
    // The project does not declare it, or this is not a PnP process after all.
    return null;
  }
}

/**
 * The nearest `node_modules/<name>` at or above `startDir`, found the way
 * Node's resolver finds a package, and the folder whose node_modules holds it.
 * It searches every folder up to the filesystem root and does not ask
 * Plug'n'Play.
 *
 * @param {string} startDir
 * @param {string} name bare package name; callers reject path segments first
 * @returns {{packageDir: string, hostDir: string}|null}
 */
export function findNodeModulesPackage(startDir, name) {
  for (const dir of foldersUpFrom(startDir)) {
    const packageDir = installedIn(dir, name);
    if (packageDir) return {packageDir, hostDir: dir};
  }
  return null;
}

/**
 * Locate a package the project at `startDir` actually installed.
 *
 * Deliberately not `require.resolve`: Node folds NODE_PATH and the global
 * folders into resolution even when `paths` is given, so a package merely
 * reachable from the ambient environment reads as installed here. pnpm's
 * isolated layout puts every package in `node_modules/.pnpm/node_modules`,
 * and Vitest puts that directory on NODE_PATH, so the gap is not theoretical.
 * Reading package.json off disk also sidesteps packages that don't export it,
 * so the version is always available to range-check.
 *
 * Searches the node_modules of `startDir` and the five folders above it, as
 * released versions did, then on up to the workspace root of the Astryx
 * project it belongs to. Then it asks PnP, which covers the Yarn default
 * layout where that chain does not exist.
 *
 * @param {string} startDir
 * @param {string} name
 * @param {number} [maxDepth] how many folders to walk up; `Infinity` walks
 *   every ancestor, as Node's own resolution does
 * @returns {string|null} the package directory, or null when not installed
 */
export function findInstalledPackage(
  startDir,
  name,
  maxDepth = INSTALLED_REACH,
) {
  for (const dir of readFolders(startDir, maxDepth)) {
    const packageDir = installedIn(dir, name);
    if (packageDir) return packageDir;
  }
  return findPnpPackage(startDir, name);
}

/**
 * The first of `names` the Astryx project of `startDir` installed, for a
 * command that writes to the project (`upgrade`).
 *
 * It searches the node_modules of the project root, nearest name first. For
 * a member its workspace lists, it then searches each folder above the
 * project up to the workspace root, where the workspace installs the packages
 * its members share; otherwise the search stops at the project root. Then it
 * asks Plug'n'Play, in name order. With no Astryx project it looks only in the
 * node_modules of `startDir` itself, as released versions did.
 *
 * @param {string} startDir
 * @param {readonly string[]} names in order of preference
 * @returns {{name: string, packageDir: string}|null}
 */
export function findProjectPackageOf(startDir, names) {
  const project = findAstryxProject(startDir);
  if (project == null) {
    const dir = path.resolve(startDir);
    for (const name of names) {
      const packageDir = installedIn(dir, name);
      if (packageDir) return {name, packageDir};
    }
    return null;
  }
  const workspace = workspaceBound(project);
  const top =
    workspace !== project && isWorkspaceMember(project, workspace)
      ? workspace
      : project;
  for (const dir of foldersUpFrom(project)) {
    for (const name of names) {
      const packageDir = installedIn(dir, name);
      if (packageDir) return {name, packageDir};
    }
    if (dir === top) break;
  }
  for (const name of names) {
    const packageDir = findPnpPackage(project, name);
    if (packageDir) return {name, packageDir};
  }
  return null;
}

/**
 * Find the monorepo root by looking for the root package.json
 * that has workspaces defined.
 */
export function findProjectRoot(startDir = process.cwd()) {
  let dir = startDir;

  for (let i = 0; i < 5; i++) {
    const pkgPath = path.join(dir, 'package.json');
    if (fs.existsSync(pkgPath)) {
      try {
        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
        if (pkg.workspaces) {
          return dir;
        }
      } catch {
        // skip invalid JSON
      }
    }

    const parent = path.dirname(dir);
    if (parent === dir) break;
    dir = parent;
  }

  return null;
}

/**
 * Discover external Astryx-compatible packages from node_modules.
 * Scans for packages with an "astryx" field in their package.json:
 *
 *   { "astryx": { "docs": "./src", "category": "Common", "blocks": "./blocks/components" } }
 *
 * Returns array of { name, category, docsDir, blocksDir }.
 */
export function discoverExternalPackages(startDir = process.cwd()) {
  /** @type {Array<{name: string, category: string, docsDir: string, blocksDir: string | null}>} */
  const externals = [];
  let dir = startDir;

  // Walk up to find node_modules
  let nodeModulesDir = null;
  for (let i = 0; i < 5; i++) {
    const candidate = path.join(dir, 'node_modules');
    if (fs.existsSync(candidate)) {
      nodeModulesDir = candidate;
      break;
    }
    const parent = path.dirname(dir);
    if (parent === dir) break;
    dir = parent;
  }

  if (!nodeModulesDir) return externals;

  /** @param {string} searchDir */
  const scanDir = searchDir => {
    if (!fs.existsSync(searchDir)) return;
    const entries = listDirEntries(searchDir);

    for (const entry of entries) {
      if (!entry.isDirectory()) continue;
      if (entry.name.startsWith('.') || entry.name === '.bin') continue;

      const fullPath = path.join(searchDir, entry.name);

      // Recurse into scoped packages (@org/*)
      if (entry.name.startsWith('@')) {
        scanDir(fullPath);
        continue;
      }

      const pkgJsonPath = path.join(fullPath, 'package.json');
      if (!fs.existsSync(pkgJsonPath)) continue;

      try {
        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
        if (pkg.name === '@astryxdesign/core') continue;
        if (pkg.astryx && pkg.astryx.docs) {
          externals.push({
            name: pkg.name,
            category: pkg.astryx.category || pkg.name,
            docsDir: path.resolve(fullPath, pkg.astryx.docs),
            blocksDir: pkg.astryx.blocks
              ? path.resolve(fullPath, pkg.astryx.blocks)
              : null,
          });
        }
      } catch {
        // skip invalid JSON
      }
    }
  };

  scanDir(nodeModulesDir);
  return externals;
}

/**
 * List available component directories in packages/core/src.
 * Component directories are capitalized (`Button`, `Dialog`); lowercase
 * directories hold shared infrastructure and are never listed.
 * @param {string} coreDir
 */
export function listComponents(coreDir) {
  const srcDir = path.join(coreDir, 'src');
  if (!fs.existsSync(srcDir)) return [];

  const entries = fs.readdirSync(srcDir, {withFileTypes: true});
  return entries
    .filter(e => {
      if (!e.isDirectory()) return false;
      return /^[A-Z]/.test(e.name);
    })
    .map(e => e.name)
    .sort();
}

/**
 * `path.relative(root, target)`, read straight off the string when `target`
 * is a plain path under `root`. A resolver probes tens of thousands of such
 * paths, and `path.relative` normalizes both on every call.
 * @param {string} root
 * @param {string} target
 * @returns {string}
 */
function relativeInside(root, target) {
  const prefix = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
  if (path.isAbsolute(root) && target.startsWith(prefix)) {
    const rest = target.slice(prefix.length);
    const plain =
      rest !== '' &&
      !(path.sep === '\\' && rest.includes('/')) &&
      rest
        .split(path.sep)
        .every(
          segment => segment !== '' && segment !== '.' && segment !== '..',
        );
    if (plain) return rest;
  }
  return path.relative(root, target);
}

/**
 * Does `targetPath` exist with EXACTLY this spelling?
 *
 * `fs.existsSync` answers through the filesystem's own case folding, so on
 * macOS and Windows a probe for `src/button/Button.doc.mjs` succeeds against
 * the real `src/Button/Button.doc.mjs`. Name resolvers built on that probe
 * then resolve a component or hook the caller never named, and hand back a
 * path spelled the way the caller typed it — a path that does not exist on
 * Linux, where the same lookup correctly misses. Every segment below
 * `rootDir` is checked against its parent's real directory listing.
 *
 * @param {string} targetPath - Path to probe; must be inside `rootDir`.
 * @param {string} rootDir - Already-real path; it and its parents are not checked.
 * @returns {boolean}
 */
export function existsCaseExact(targetPath, rootDir) {
  const rel = relativeInside(rootDir, targetPath);
  if (rel === '') return pathExists(targetPath);
  if (path.isAbsolute(rel) || rel === '..' || rel.startsWith(`..${path.sep}`))
    return false;

  if (listingCacheActive()) {
    // Inside an operation the folders' listings answer, so a name that a
    // listing lacks costs no probe of the disk. A symbolic link still needs
    // its target.
    let folder = rootDir;
    let entry = null;
    for (const segment of rel.split(path.sep)) {
      entry = findEntry(folder, segment);
      if (!entry) return false;
      folder = folder.endsWith(path.sep)
        ? `${folder}${segment}`
        : `${folder}${path.sep}${segment}`;
    }
    return !entry?.isSymbolicLink() || pathExists(targetPath);
  }

  if (!pathExists(targetPath)) return false;
  let dir = rootDir;
  for (const segment of rel.split(path.sep)) {
    let entries;
    try {
      entries = listDir(dir);
    } catch {
      return false;
    }
    if (!entries.includes(segment)) return false;
    dir = path.join(dir, segment);
  }
  return true;
}