Skip to content

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

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

/**
 * @file The `Fix:` advice for contribution metadata that no root reads, or
 * that the wrong root reads.
 *
 * A fix must hold when followed literally. It never names a path outside the
 * package, never makes the package root a root, and names only the offending
 * file plus the same-stem source that moves with it. It offers a folder as a
 * root only when that root would read nothing but this kind of metadata,
 * overlap no other root, and orphan nothing the current root holds. Metadata
 * is read statically: nothing here runs package code.
 *
 * @input a package directory, its resolved roots, and one misplaced file
 * @output the `Fix: ...` sentence for that file
 * @position packages/cli/foundation/integrations — shared by the unreachable
 *   scan in api/integration/validate-integration.mjs and the component checks
 *   in validate-contributions.mjs
 */

import * as fs from 'node:fs';
import * as path from 'node:path';
import {createRequire} from 'node:module';
import {isValidSemver} from '../env/semver.mjs';
import {
  isThemeFolder as readsAsTheme,
  THEME_DOC_SUFFIX,
  THEME_MODULE_EXTENSIONS,
  THEME_SLUG_RE,
} from '../discovery/theme-discovery.mjs';

/** @typedef {'components' | 'templates' | 'docs' | 'themes'} MetadataRoot */

/**
 * @typedef {object} ContributionStamp
 * @property {string} type
 * @property {string | null} name the static `name`, when it has one
 */

/**
 * @typedef {object} FixContext
 * @property {string} packageDir
 * @property {string} manifest file name of the package's manifest
 * @property {Partial<Record<MetadataRoot | 'codemods', string>>} roots
 *   declared roots, absolute
 * @property {Map<string, ContributionStamp | null>} stamps
 * @property {Map<string, string[] | null>} candidates
 */

export const DOC_CANDIDATE_RE = /\.doc\.(?:ts|mjs|js)$/u;
export const TEMPLATE_CANDIDATE_RE = /\.template\.(?:ts|mjs|js)$/u;
const STATIC_DOC_TYPES = new Set([
  'component',
  'generic',
  'page',
  'block',
  'theme',
]);
const STATIC_TEMPLATE_TYPES = new Set(['page', 'block']);
/** Stray-codemod and version-folder rules, shared with the codemod checks. */
export const CODEMOD_FILE_RE = /\.(?:ts|mjs|js)$/u;
export const CODEMOD_TEST_RE = /\.(?:test|spec|fixture)\.(?:ts|mjs|js)$/u;
export const CODEMOD_SKIP_DIRS = new Set([
  'node_modules',
  '.git',
  '__tests__',
  '__fixtures__',
]);
/** @type {MetadataRoot[]} */
const METADATA_ROOTS = ['components', 'templates', 'docs', 'themes'];
/** Past this many entries a folder's contents count as unknown. */
const FOLDER_SCAN_LIMIT = 5_000;

/** The manifest root that reads each kind of contribution metadata. */
export const ROOT_FOR_TYPE = /** @type {Record<string, MetadataRoot>} */ ({
  component: 'components',
  generic: 'docs',
  page: 'templates',
  block: 'templates',
  theme: 'themes',
});

/** What a root holds, as a fix names it. */
const ROOT_HOLDS = /** @type {Record<MetadataRoot, string>} */ ({
  components: 'components',
  docs: 'topics',
  templates: 'templates',
  themes: 'themes',
});

const require = createRequire(import.meta.url);
/** @type {typeof import('jscodeshift').default | undefined} */
let jscodeshiftModule;
/** @type {ReturnType<typeof import('jscodeshift').default['withParser']> | undefined} */
let tsxParser;

/**
 * jscodeshift, loaded at its first use: it is a large module, and a run that
 * checks no contribution file never needs it.
 * @returns {typeof import('jscodeshift').default}
 */
function jscodeshift() {
  jscodeshiftModule ??= require('jscodeshift');
  return /** @type {typeof import('jscodeshift').default} */ (
    jscodeshiftModule
  );
}

/** jscodeshift with the TypeScript parser, made once. */
function tsx() {
  tsxParser ??= jscodeshift().withParser('tsx');
  return tsxParser;
}

/** @param {any} node @returns {any} */
function unwrapStaticExpression(node) {
  let current = node;
  while (
    current &&
    [
      'TSSatisfiesExpression',
      'TSAsExpression',
      'TypeCastExpression',
      'ParenthesizedExpression',
    ].includes(current.type)
  ) {
    current = current.expression;
  }
  if (current?.type === 'CallExpression' && current.arguments.length > 0) {
    current = unwrapStaticExpression(current.arguments[0]);
  }
  return current;
}

/** @param {any} property @param {string} name */
function staticPropertyNamed(property, name) {
  if (
    !property ||
    !['ObjectProperty', 'Property'].includes(property.type) ||
    property.computed
  ) {
    return false;
  }
  return (
    (property.key?.type === 'Identifier' && property.key.name === name) ||
    (['Literal', 'StringLiteral'].includes(property.key?.type) &&
      property.key.value === name)
  );
}

/**
 * Identify contribution metadata without importing it. Doctor scans files that
 * the manifest does not declare, so executing those files would run code the
 * package never asked Astryx to load.
 *
 * @param {string} file
 * @param {boolean} templateOnly
 * @returns {ContributionStamp | null} null when it is not contribution metadata
 */
export function readContributionStamp(file, templateOnly) {
  const j = tsx();
  let ast;
  try {
    ast = j(fs.readFileSync(file, 'utf-8'));
  } catch {
    return null;
  }
  /** @type {any[]} */
  const candidates = [];
  ast
    .find(j.ExportDefaultDeclaration)
    .forEach((/** @type {any} */ exportPath) => {
      candidates.push(exportPath.value.declaration);
    });
  ast
    .find(j.ExportNamedDeclaration)
    .forEach((/** @type {any} */ exportPath) => {
      const declaration = exportPath.value.declaration;
      if (declaration?.type !== 'VariableDeclaration') return;
      for (const declarator of declaration.declarations) {
        if (
          declarator.id?.type === 'Identifier' &&
          declarator.id.name === 'docs'
        ) {
          candidates.push(declarator.init);
        }
      }
    });

  const allowedTypes = templateOnly ? STATIC_TEMPLATE_TYPES : STATIC_DOC_TYPES;
  for (const candidate of candidates) {
    const object = unwrapStaticExpression(candidate);
    if (object?.type !== 'ObjectExpression') continue;
    /** @param {string} name @returns {unknown} */
    const field = name =>
      unwrapStaticExpression(
        object.properties.find((/** @type {any} */ property) =>
          staticPropertyNamed(property, name),
        )?.value,
      );
    const type = /** @type {any} */ (field('type'));
    if (
      ['Literal', 'StringLiteral'].includes(type?.type) &&
      allowedTypes.has(type.value)
    ) {
      const name = /** @type {any} */ (field('name'));
      return {
        type: type.value,
        name: typeof name?.value === 'string' ? name.value : null,
      };
    }
  }
  return null;
}

/** @param {string} candidate @param {string} root */
export function pathIsInside(candidate, root) {
  return candidate === root || candidate.startsWith(`${root}${path.sep}`);
}

/**
 * @param {string} packageDir
 * @param {{components?: string, templates?: string, codemods?: string, docs?: string, themes?: string, __manifestFile?: string}} integration
 * @returns {FixContext}
 */
export function createFixContext(packageDir, integration) {
  return {
    packageDir,
    manifest: integration.__manifestFile
      ? path.basename(integration.__manifestFile)
      : 'astryx.integration.mjs',
    roots: {
      components: integration.components,
      templates: integration.templates,
      codemods: integration.codemods,
      docs: integration.docs,
      themes: integration.themes,
    },
    stamps: new Map(),
    candidates: new Map(),
  };
}

/**
 * The static stamp of a candidate metadata file, read once per context.
 * @param {FixContext} context
 * @param {string} file
 * @returns {ContributionStamp | null}
 */
export function stampOf(context, file) {
  if (!context.stamps.has(file)) {
    context.stamps.set(
      file,
      readContributionStamp(file, TEMPLATE_CANDIDATE_RE.test(file)),
    );
  }
  return context.stamps.get(file) ?? null;
}

/** @param {FixContext} context @param {string} file */
function shown(context, file) {
  return path.relative(context.packageDir, file).split(path.sep).join('/');
}

/** @param {FixContext} context */
function declaredRoots(context) {
  return /** @type {string[]} */ (Object.values(context.roots).filter(Boolean));
}

/** @param {string} file */
function isFile(file) {
  try {
    return fs.statSync(file).isFile();
  } catch {
    return false;
  }
}

/**
 * Every doc or template file under `dir`, or null when there are too many
 * entries to know.
 * @param {FixContext} context
 * @param {string} dir
 * @returns {string[] | null}
 */
function candidatesUnder(context, dir) {
  if (context.candidates.has(dir)) {
    return context.candidates.get(dir) ?? null;
  }
  /** @type {string[] | null} */
  let found = [];
  let seen = 0;
  /** @param {string} current */
  const walk = current => {
    let entries;
    try {
      entries = fs.readdirSync(current, {withFileTypes: true});
    } catch {
      return;
    }
    for (const entry of entries) {
      if (found == null) return;
      if (entry.name === '.git') continue;
      seen += 1;
      if (seen > FOLDER_SCAN_LIMIT) {
        found = null;
        return;
      }
      const full = path.join(current, entry.name);
      if (entry.isDirectory()) {
        walk(full);
      } else if (
        entry.isFile() &&
        (DOC_CANDIDATE_RE.test(entry.name) ||
          TEMPLATE_CANDIDATE_RE.test(entry.name))
      ) {
        found.push(full);
      }
    }
  };
  walk(dir);
  context.candidates.set(dir, found);
  return found;
}

/**
 * A folder inside the package, not its root, that neither holds nor sits in a
 * declared root.
 * @param {FixContext} context
 * @param {string} dir
 */
function isFreeFolder(context, dir) {
  return (
    dir !== context.packageDir &&
    pathIsInside(dir, context.packageDir) &&
    !declaredRoots(context).some(
      root => pathIsInside(root, dir) || pathIsInside(dir, root),
    )
  );
}

/**
 * Whether `dir` is one complete theme: a slug folder whose only metadata is
 * its theme descriptor, naming that folder, beside exactly one source that
 * imports nothing outside the folder. The descriptor being fixed may lack its
 * source or import from outside; the fix asks for both.
 * @param {FixContext} context
 * @param {string} dir
 * @param {string} [fixing]
 */
function isCompleteTheme(context, dir, fixing) {
  const found = candidatesUnder(context, dir);
  if (found?.length !== 1) return false;
  const [descriptor] = found;
  const stamp = stampOf(context, descriptor);
  const slug = path.basename(dir);
  return (
    THEME_SLUG_RE.test(slug) &&
    path.dirname(descriptor) === dir &&
    descriptor.endsWith(THEME_DOC_SUFFIX) &&
    stamp?.type === 'theme' &&
    stamp.name === slug &&
    (descriptor === fixing ||
      (sourcesBeside(descriptor, 'theme').length === 1 &&
        importsOutside(descriptor)?.length === 0))
  );
}

/**
 * Whether `dir` reads cleanly as a themes root: every folder in it that
 * discovery reads as a theme is one complete theme, and no metadata sits
 * directly in it.
 * @param {FixContext} context
 * @param {string} dir
 * @param {{except?: string, ignore?: string, fixing?: string}} [options] a
 *   theme folder moving out of `dir`, a descriptor moving away, and the
 *   descriptor being fixed
 */
function readsAsThemesRoot(context, dir, {except, ignore, fixing} = {}) {
  if (!fs.existsSync(dir)) return true;
  if (fs.existsSync(path.join(dir, 'manifest.json'))) return false;
  let entries;
  try {
    entries = fs.readdirSync(dir, {withFileTypes: true});
  } catch {
    return false;
  }
  return entries.every(entry => {
    const full = path.join(dir, entry.name);
    if (entry.name.startsWith('.')) return true;
    if (entry.isSymbolicLink()) return false;
    if (entry.isDirectory()) {
      return (
        full === except ||
        !readsAsTheme(full) ||
        isCompleteTheme(context, full, fixing)
      );
    }
    return (
      full === ignore ||
      !(
        DOC_CANDIDATE_RE.test(entry.name) ||
        TEMPLATE_CANDIDATE_RE.test(entry.name)
      )
    );
  });
}

/**
 * Whether declaring `dir` as the `key` root reads only complete metadata of
 * that kind, overlaps no root, and stays inside the package below its root.
 * The file being fixed may lack its source; the fix asks for it.
 * @param {FixContext} context
 * @param {string} dir
 * @param {MetadataRoot} key
 * @param {string} fixing
 */
function canBeRoot(context, dir, key, fixing) {
  if (!isFreeFolder(context, dir)) return false;
  if (key === 'themes') return readsAsThemesRoot(context, dir, {fixing});
  const found = candidatesUnder(context, dir);
  if (found == null) return false;
  const complete = found.every(file => {
    const stamp = stampOf(context, file);
    return (
      stamp != null &&
      ROOT_FOR_TYPE[stamp.type] === key &&
      (file === fixing ||
        stamp.type === 'generic' ||
        sourcesBeside(file, stamp.type).length > 0)
    );
  });
  const names = found.map(file => identity(context, file, key));
  const unique = new Set(names).size === names.length;
  return (
    complete &&
    unique &&
    (key !== 'components' || uncoveredSources(dir, found).length === 0)
  );
}

/**
 * The name a root knows a contribution by, and must hold only once: a
 * component's stem, a topic's lower-cased \`name\`, a template's path without
 * its suffix. A file with no static name gets its path, which never repeats.
 * @param {FixContext} context
 * @param {string} file
 * @param {MetadataRoot} key
 */
function identity(context, file, key) {
  if (key === 'components') return docStem(file);
  if (key === 'docs')
    return stampOf(context, file)?.name?.toLowerCase() ?? file;
  return path.join(path.dirname(file), docStem(file).toLowerCase());
}

/**
 * The PascalCase \`.tsx\` files directly in a folder that no doc under it
 * covers. A components root there warns that Astryx ignores each one.
 * @param {string} dir
 * @param {string[]} found the doc and template files under it
 * @returns {string[]} their file names
 */
function uncoveredSources(dir, found) {
  const covered = new Set(
    found.filter(file => DOC_CANDIDATE_RE.test(file)).map(docStem),
  );
  try {
    return fs
      .readdirSync(dir, {withFileTypes: true})
      .filter(entry => entry.isFile() || entry.isSymbolicLink())
      .map(entry => entry.name)
      .filter(name => {
        const match = /^([A-Z][A-Za-z0-9]+)\.tsx$/u.exec(name);
        return match != null && !covered.has(match[1]);
      });
  } catch {
    return [];
  }
}

/**
 * Whether a folder holds an entry by this name, compared the way a
 * case-insensitive file system would.
 * @param {string} dir
 * @param {string} name
 */
function hasEntry(dir, name) {
  const wanted = name.toLowerCase();
  try {
    return fs.readdirSync(dir).some(entry => entry.toLowerCase() === wanted);
  } catch {
    return false;
  }
}

/**
 * What already holds the name \`file\` would take once moved to the top of
 * \`root\`, or null when the name is free.
 * @param {FixContext} context
 * @param {string} file
 * @param {ContributionStamp} stamp
 * @param {string} root
 * @returns {string | null} e.g. \`a topic named "guide" (docs/guide.doc.mjs)\`
 */
function takenIn(context, file, stamp, root) {
  const key = ROOT_FOR_TYPE[stamp.type];
  const stem = docStem(file);
  const name = identity(context, path.join(root, path.basename(file)), key);
  const same = (candidatesUnder(context, root) ?? []).find(
    other =>
      (key === 'templates' || DOC_CANDIDATE_RE.test(other)) &&
      (key === 'docs'
        ? stamp.name != null &&
          stampOf(context, other)?.name?.toLowerCase() ===
            stamp.name.toLowerCase()
        : identity(context, other, key) === name),
  );
  if (same) {
    const kind = {
      components: 'component',
      docs: 'topic',
      templates: 'template',
    }[/** @type {'components' | 'docs' | 'templates'} */ (key)];
    const called = key === 'docs' ? `"${stamp.name}"` : stem;
    return `a ${kind} named ${called} (${shown(context, same)})`;
  }
  const clash = [path.basename(file), ...sourcesBeside(file, stamp.type)].find(
    entry => hasEntry(root, entry),
  );
  return clash ? `a file named ${clash}` : null;
}

/**
 * The local modules a theme source reaches, read statically the way theme
 * discovery reads them. Null when a file in the graph cannot be parsed.
 * @param {string} entry
 * @returns {Array<{importer: string, specifier: string, target: string}> | null}
 */
function localImports(entry) {
  /** @type {Array<{importer: string, specifier: string, target: string}>} */
  const edges = [];
  const seen = new Set();
  const queue = [entry];
  while (queue.length > 0) {
    const file = /** @type {string} */ (queue.shift());
    if (seen.has(file)) continue;
    seen.add(file);
    /** @type {string[]} */
    const specifiers = [];
    try {
      const js = jscodeshift().withParser(
        /\.(?:ts|tsx|mts)$/u.test(file) ? 'tsx' : 'babel',
      );
      const ast = js(fs.readFileSync(file, 'utf-8'));
      /** @param {any} node */
      const add = node => {
        if (typeof node?.value === 'string') specifiers.push(node.value);
      };
      for (const type of [
        js.ImportDeclaration,
        js.ExportNamedDeclaration,
        js.ExportAllDeclaration,
        js.ImportExpression,
      ]) {
        ast.find(type).forEach((/** @type {any} */ found) => {
          add(found.node.source);
        });
      }
      ast.find(js.CallExpression).forEach((/** @type {any} */ call) => {
        if (call.node.callee?.type === 'Import') add(call.node.arguments?.[0]);
      });
    } catch {
      return null;
    }
    for (const specifier of specifiers) {
      if (!specifier.startsWith('.')) continue;
      const base = path.resolve(path.dirname(file), specifier);
      const target = [
        base,
        ...THEME_MODULE_EXTENSIONS.map(extension => `${base}${extension}`),
        ...THEME_MODULE_EXTENSIONS.map(extension =>
          path.join(base, `index${extension}`),
        ),
      ].find(isFile);
      if (!target) continue;
      edges.push({importer: file, specifier, target});
      if (THEME_MODULE_EXTENSIONS.includes(path.extname(target))) {
        queue.push(target);
      }
    }
  }
  return edges;
}

/**
 * A theme's imports that reach outside the folder its descriptor is in. Null
 * when unknown.
 * @param {string} file the theme descriptor
 */
function importsOutside(file) {
  const [source] = sourcesBeside(file, 'theme');
  if (!source) return [];
  const home = path.dirname(file);
  const edges = localImports(path.join(home, source));
  return edges && edges.filter(edge => !pathIsInside(edge.target, home));
}

/**
 * The sentence that brings the files a theme imports from outside its folder
 * into the folder: discovery rejects any import that leaves it. Files move
 * with the folder keep their paths; outside files are copied to its top.
 * @param {FixContext} context
 * @param {string} file the theme descriptor
 * @param {string} destination the theme folder, as the fix names it
 * @returns {string} a sentence with a leading space, or ''
 */
function themeImportNote(context, file, destination) {
  const [source] = sourcesBeside(file, 'theme');
  if (!source) return '';
  const home = path.dirname(file);
  const edges = localImports(path.join(home, source));
  if (!edges) return '';
  const copies = [
    ...new Set(
      edges
        .map(edge => edge.target)
        .filter(target => !pathIsInside(target, home)),
    ),
  ];
  if (
    copies.length === 0 ||
    copies.some(target => !pathIsInside(target, context.packageDir))
  ) {
    return '';
  }
  const why = ': a theme can import only files inside its own folder.';
  const listed = copies.map(target => shown(context, target));
  const list =
    listed.length === 1
      ? listed[0]
      : `${listed.slice(0, -1).join(', ')} and ${listed.at(-1)}`;
  const names = copies.map(target => path.basename(target).toLowerCase());
  if (
    new Set(names).size !== names.length ||
    copies.some(target => hasEntry(home, path.basename(target)))
  ) {
    return ` Also copy ${list} into ${destination} and point the imports of ${copies.length === 1 ? 'it at the copy' : 'them at the copies'}${why}`;
  }
  /** @param {string} target where a file ends up, relative to the theme folder */
  const inTheme = target =>
    (pathIsInside(target, home)
      ? path.relative(home, target)
      : path.basename(target)
    )
      .split(path.sep)
      .join('/');
  /** @type {string[]} */
  const changes = [];
  for (const {importer, specifier, target} of edges) {
    const extension = path.extname(specifier);
    let next = inTheme(target);
    if (!(extension && target.endsWith(extension))) {
      next = next.slice(0, next.length - path.extname(next).length);
    }
    next = path.posix.relative(path.posix.dirname(inTheme(importer)), next);
    if (!next.startsWith('.')) next = `./${next}`;
    const change = `of ${specifier} in ${path.basename(importer)} to ${next}`;
    if (next !== specifier && !changes.includes(change)) changes.push(change);
  }
  const changed =
    changes.length === 1
      ? `the import ${changes[0]}`
      : `the imports ${changes.slice(0, -1).join(', ')} and ${changes.at(-1)}`;
  return ` Also copy ${list} into ${destination} and change ${changed}${why}`;
}

/**
 * The same-stem sources beside a doc: a component's or template's `.tsx`, or
 * a theme's entry modules (a theme needs exactly one).
 * @param {string} file
 * @param {string} type
 * @returns {string[]} their file names
 */
function sourcesBeside(file, type) {
  if (type === 'generic') return [];
  const dir = path.dirname(file);
  const stem = docStem(file);
  const names =
    type === 'theme'
      ? THEME_MODULE_EXTENSIONS.map(extension => `${stem}${extension}`)
      : [`${stem}.tsx`];
  return names.filter(name => isFile(path.join(dir, name)));
}

/** @param {string} file */
function docStem(file) {
  return path
    .basename(file)
    .replace(DOC_CANDIDATE_RE, '')
    .replace(TEMPLATE_CANDIDATE_RE, '');
}

/**
 * The sentences asking for what the doc needs wherever it ends up: a missing
 * same-stem source, and for a theme, the descriptor's `.doc.mjs` name.
 * @param {string} file
 * @param {string} type
 * @returns {string} a sentence with a leading space, or ''
 */
function sourceNote(file, type) {
  // Theme discovery reads only `.doc.mjs` descriptors.
  const rename =
    type === 'theme' && !file.endsWith(THEME_DOC_SUFFIX)
      ? ` Also rename ${path.basename(file)} to ${docStem(file)}${THEME_DOC_SUFFIX}: a theme descriptor is a ${THEME_DOC_SUFFIX} file.`
      : '';
  if (type === 'generic' || sourcesBeside(file, type).length > 0) return rename;
  return type === 'theme'
    ? `${rename} Also add its same-stem theme source, such as ${docStem(file)}.ts, beside it.`
    : ` Also add ${docStem(file)}.tsx beside it.`;
}

/**
 * How a fix names a folder.
 * @param {FixContext} context
 * @param {string} dir
 */
function place(context, dir) {
  return dir === context.packageDir
    ? 'the package root'
    : `${shown(context, dir)}/`;
}

/** @param {string} text */
function capitalize(text) {
  return `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
}

/**
 * Whether codemods can move into `dir`: it is missing, or holds nothing the
 * codemod checks would read as a stray codemod or a mis-named version.
 * @param {string} dir
 */
function holdsOnlyVersions(dir) {
  if (!fs.existsSync(dir)) return true;
  try {
    return fs
      .readdirSync(dir, {withFileTypes: true})
      .every(entry =>
        entry.isDirectory()
          ? isValidSemver(entry.name) || CODEMOD_SKIP_DIRS.has(entry.name)
          : !CODEMOD_FILE_RE.test(entry.name) ||
            CODEMOD_TEST_RE.test(entry.name),
      );
  } catch {
    return false;
  }
}

/**
 * The step that gives codemods a folder of their own, and the folder it names
 * (null when codemods/ is taken and the author picks one).
 * @param {FixContext} context
 * @returns {{step: string, folder: string | null}}
 */
function ownCodemodsFolder(context) {
  const target = path.join(context.packageDir, 'codemods');
  return context.roots.codemods !== target && holdsOnlyVersions(target)
    ? {
        step: `create codemods/, move each version folder into it, and set \`codemods: './codemods'\` in ${context.manifest}`,
        folder: 'codemods',
      }
    : {
        step: `move each version folder into a new folder of their own, and set \`codemods\` to that folder in ${context.manifest}`,
        folder: null,
      };
}

/**
 * Declared roots other than codemods at or inside `dir`.
 * @param {FixContext} context
 * @param {string} dir
 * @returns {Array<{kind: MetadataRoot, root: string}>}
 */
function metadataRootsIn(context, dir) {
  /** @type {Array<{kind: MetadataRoot, root: string}>} */
  const found = [];
  for (const kind of METADATA_ROOTS) {
    const root = context.roots[kind];
    if (root && pathIsInside(root, dir)) found.push({kind, root});
  }
  return found;
}

/**
 * The fix for every codemods entry when the codemods root also holds the rest
 * of the package: it is the package root, or it holds another root. No
 * per-entry move or rename helps then.
 * @param {FixContext} context
 * @param {string} [stray] a stray file's name, which may itself be a codemod
 * @returns {string | null}
 */
export function sharedCodemodsRootFix(context, stray) {
  const root = context.roots.codemods;
  if (!root) return null;
  const {step, folder} = ownCodemodsFolder(context);
  const also =
    stray == null
      ? ''
      : ` If it is a codemod, move it into the folder named for the version it migrates to, for example ${folder ? `${folder}/1.2.0/${stray}` : `1.2.0/${stray} in that folder`}.`;
  if (root === context.packageDir) {
    return `Fix: the codemods root is the package root, so everything in the package is read as a codemod or a version folder. ${capitalize(step)}.${also}`;
  }
  // codemods/ holding another root is fixed by moving that root out.
  if (root === path.join(context.packageDir, 'codemods')) return null;
  const [held] = metadataRootsIn(context, root);
  if (!held) return null;
  const relation =
    held.root === root
      ? `is also the ${held.kind} root`
      : `also holds the ${held.kind} root ${place(context, held.root)}`;
  return `Fix: the codemods root ${place(context, root)} ${relation}. ${capitalize(step)}.${also}`;
}

/**
 * The fix for a codemods folder that holds another root, which a rename would
 * break.
 * @param {FixContext} context
 * @param {string} folder
 * @returns {string | null}
 */
export function heldRootFix(context, folder) {
  const [held] = metadataRootsIn(context, folder);
  const codemods = context.roots.codemods;
  if (!held || !codemods) return null;
  return `Fix: it holds the ${held.kind} root ${place(context, held.root)}; move that root out of ${place(context, codemods)} and update \`${held.kind}\` in ${context.manifest}.`;
}

/**
 * The step that stops another root from also reading `dir`, the folder a fix
 * puts `key` metadata in. `dir` is undefined for a folder the author picks,
 * which only a root at the package root is sure to cover.
 * @param {FixContext} context
 * @param {string | undefined} dir
 * @param {MetadataRoot} key
 * @returns {string} a sentence with a leading space, or ''
 */
function overlapNote(context, dir, key) {
  /** @param {string | undefined} root */
  const covers = root =>
    root != null &&
    (dir === undefined ? root === context.packageDir : pathIsInside(dir, root));
  const at = dir === undefined ? 'that folder' : place(context, dir);
  let note = '';
  const codemods = context.roots.codemods;
  if (covers(codemods)) {
    if (
      dir !== undefined &&
      codemods === path.join(context.packageDir, 'codemods')
    ) {
      return ` The codemods root codemods/ also reads ${at}; move ${at} out of codemods/ and set \`${key}\` to its new path in ${context.manifest}.`;
    }
    const which =
      codemods === context.packageDir
        ? 'is the package root, so it'
        : place(context, /** @type {string} */ (codemods));
    note = ` The codemods root ${which} also reads ${at}; ${ownCodemodsFolder(context).step}.`;
  }
  const own = path.join(context.packageDir, key);
  const free = !fs.existsSync(own) && isFreeFolder(context, own);
  for (const kind of METADATA_ROOTS) {
    const other = context.roots[kind];
    if (kind === key || other == null || !covers(other)) continue;
    if (other === context.packageDir) {
      note += ` The ${kind} root is the package root, so it also reads ${at}; create ${kind}/, move the ${ROOT_HOLDS[kind]} into it, and set \`${kind}: './${kind}'\` in ${context.manifest}.`;
      continue;
    }
    // Moving this root out of the outermost root clears every root around it.
    if (other === dir) {
      return free
        ? `${note} The ${kind} root is also ${at}; move the ${ROOT_HOLDS[key]} there into ${key}/ and set \`${key}: './${key}'\` in ${context.manifest}.`
        : `${note} The ${kind} root is also ${at}; move the ${ROOT_HOLDS[key]} there into a folder of their own and set \`${key}\` to that folder in ${context.manifest}.`;
    }
    return free
      ? `${note} The ${kind} root ${place(context, other)} also reads ${at}; move ${at} to ${key}/ and set \`${key}: './${key}'\` in ${context.manifest}.`
      : `${note} The ${kind} root ${place(context, other)} also reads ${at}; move ${at} out of it and set \`${key}\` to its new path in ${context.manifest}.`;
  }
  return note;
}

/**
 * @param {FixContext} context
 * @param {string} file
 * @param {ContributionStamp} stamp
 */
function themeSlug(context, file, stamp) {
  const themeDir = path.dirname(file);
  if (stamp.name) return stamp.name;
  return themeDir === context.packageDir
    ? docStem(file)
    : path.basename(themeDir);
}

/**
 * What to move for a theme: its whole folder when the folder holds only this
 * theme and does not hold the target, else the descriptor and its source.
 * @param {FixContext} context
 * @param {string} file
 * @param {string} [target] the folder it moves to
 * @returns {{what: string, folder: boolean}}
 */
function themeFiles(context, file, target) {
  const themeDir = path.dirname(file);
  if (
    themeDir !== context.packageDir &&
    (target === undefined || !pathIsInside(target, themeDir)) &&
    !declaredRoots(context).some(root => pathIsInside(root, themeDir))
  ) {
    const found = candidatesUnder(context, themeDir);
    if (found?.length === 1 && found[0] === file) {
      return {what: `${shown(context, themeDir)}/`, folder: true};
    }
  }
  const sources = sourcesBeside(file, 'theme');
  const doc = path.basename(file);
  if (sources.length === 0) return {what: doc, folder: false};
  if (sources.length > 1) {
    return {
      what: `${doc} and its same-stem sources (with any local files they import)`,
      folder: false,
    };
  }
  return {
    what: `${doc} and ${sources[0]} (with any local files it imports)`,
    folder: false,
  };
}

/**
 * @param {FixContext} context
 * @param {string} file
 * @param {ContributionStamp} stamp
 * @param {string} root the themes root the theme moves under
 * @param {string} [slug] the folder it takes there
 */
function moveTheme(
  context,
  file,
  stamp,
  root,
  slug = themeSlug(context, file, stamp),
) {
  const {what, folder} = themeFiles(context, file, path.join(root, slug));
  const target = `${root === context.packageDir ? '' : `${shown(context, root)}/`}${slug}/`;
  return folder ? `move ${what} to ${target}` : `move ${what} into ${target}`;
}

/**
 * Moving metadata under its kind's declared root.
 * @param {FixContext} context
 * @param {string} file
 * @param {ContributionStamp} stamp
 * @param {string} root
 * @param {string} [destination] the theme folder, as the fix names it
 * @returns {{main: string, notes: string}}
 */
function moveUnder(context, file, stamp, root, destination) {
  const key = ROOT_FOR_TYPE[stamp.type];
  const overlap = overlapNote(context, root, key);
  if (key === 'themes') {
    const slugDir = path.join(root, themeSlug(context, file, stamp));
    const taken = hasEntry(root, path.basename(slugDir));
    const imports = themeImportNote(
      context,
      file,
      destination ??
        (taken ? `${place(context, root)}<slug>/` : place(context, slugDir)),
    );
    const notes = sourceNote(file, stamp.type) + imports + overlap;
    if (taken) {
      return {
        main: `${place(context, slugDir)} is taken, so give this theme a new lower-kebab slug: ${moveTheme(context, file, stamp, root, '<slug>')} and set \`name\` in ${path.basename(file)} to <slug>`,
        notes,
      };
    }
    return {main: moveTheme(context, file, stamp, root), notes};
  }
  const [source] = sourcesBeside(file, stamp.type);
  const taken = takenIn(context, file, stamp, root);
  if (taken) {
    const name = key === 'components' ? '<Name>' : '<name>';
    const suffix = path.basename(file).slice(docStem(file).length);
    const renamed = source
      ? `rename it and ${source} to ${name}${suffix} and ${name}.tsx`
      : `rename it to ${name}${suffix}`;
    const missing =
      stamp.type === 'generic' || source
        ? ''
        : ` Also add ${name}.tsx beside it.`;
    return {
      main: `${place(context, root)} already has ${taken}, so give this one a new name: ${renamed}, set its \`name\` to ${name}, and move ${source ? 'them' : 'it'} under ${place(context, root)} (the ${key} root)`,
      notes: missing + overlap,
    };
  }
  return {
    main: `move ${source ? `it and ${source}` : 'it'} under ${place(context, root)} (the ${key} root)`,
    notes: sourceNote(file, stamp.type) + overlap,
  };
}

/**
 * Moving metadata whose kind has no root yet: into the conventional folder,
 * when that folder would read cleanly as the new root.
 * @param {FixContext} context
 * @param {string} file
 * @param {ContributionStamp} stamp
 * @returns {{main: string, notes: string}}
 */
function moveToNewRoot(context, file, stamp) {
  const key = ROOT_FOR_TYPE[stamp.type];
  const target = path.join(context.packageDir, key);
  const declare = `set \`${key}: './${key}'\` in ${context.manifest}`;
  const pointAtIt = `set \`${key}\` to that folder in ${context.manifest}`;
  const notes = sourceNote(file, stamp.type);
  const picked = notes + overlapNote(context, undefined, key);
  if (key === 'themes') {
    const themeDir = path.dirname(file);
    const slug = themeSlug(context, file, stamp);
    const slugDir = path.join(target, slug);
    const clear =
      isFreeFolder(context, target) &&
      readsAsThemesRoot(context, target, {
        except: path.dirname(themeDir) === target ? themeDir : undefined,
        ignore: file,
        fixing: file,
      }) &&
      (slugDir === themeDir || !fs.existsSync(slugDir));
    if (clear && slugDir === themeDir) {
      return {
        main: declare,
        notes: notes + themeImportNote(context, file, place(context, themeDir)),
      };
    }
    if (clear) {
      return {
        main: `${moveTheme(context, file, stamp, target)} and ${declare}`,
        notes: notes + themeImportNote(context, file, place(context, slugDir)),
      };
    }
    const {what, folder} = themeFiles(context, file);
    return {
      main: folder
        ? `move ${what} into a folder that holds only themes, as ${slug}/, and ${pointAtIt}`
        : `move ${what} into a ${slug}/ folder inside a folder that holds only themes, and ${pointAtIt}`,
      notes:
        notes +
        themeImportNote(context, file, 'the theme folder') +
        overlapNote(context, undefined, key),
    };
  }
  const [source] = sourcesBeside(file, stamp.type);
  const what = source ? `it and ${source}` : 'it';
  const clear = fs.existsSync(target)
    ? canBeRoot(context, target, key, file) &&
      takenIn(context, file, stamp, target) == null
    : isFreeFolder(context, target);
  if (clear) return {main: `move ${what} into ${key}/ and ${declare}`, notes};
  return {
    main: `move ${what} into a folder that holds only ${ROOT_HOLDS[key]}, and ${pointAtIt}`,
    notes: picked,
  };
}

/**
 * The fix for contribution metadata that sits outside every declared root.
 * @param {FixContext} context
 * @param {string} file
 * @param {ContributionStamp} stamp
 * @returns {string}
 */
export function unreachableFix(context, file, stamp) {
  const key = ROOT_FOR_TYPE[stamp.type];
  const root = context.roots[key];
  // A theme is a directory under the themes root, so the root is its parent.
  const folder = path.dirname(key === 'themes' ? path.dirname(file) : file);
  const declare = `set \`${key}: './${shown(context, folder)}'\` in ${context.manifest}`;
  const folderCanBeRoot = canBeRoot(context, folder, key, file);
  const stays =
    sourceNote(file, stamp.type) +
    (key === 'themes'
      ? themeImportNote(context, file, place(context, path.dirname(file)))
      : '');
  if (root) {
    // Swapping roots would orphan whatever the declared root already reads.
    const swappable =
      folderCanBeRoot && candidatesUnder(context, root)?.length === 0;
    if (swappable && overlapNote(context, root, key) !== '') {
      return `Fix: ${declare}.${stays}`;
    }
    const {main, notes} = moveUnder(
      context,
      file,
      stamp,
      root,
      swappable ? 'the theme folder' : undefined,
    );
    return `Fix: ${main}${swappable ? `, or ${declare}` : ''}.${notes}`;
  }
  if (folderCanBeRoot) return `Fix: ${declare}.${stays}`;
  const {main, notes} = moveToNewRoot(context, file, stamp);
  return `Fix: ${main}.${notes}`;
}

/**
 * Whether the components can move into `dir` out of a components root at the
 * package root: it is missing, or holds only component docs, a doc for every
 * source, and no other root.
 * @param {FixContext} context
 * @param {string} dir
 */
function holdsOnlyComponents(context, dir) {
  if (!fs.existsSync(dir)) return true;
  const found = candidatesUnder(context, dir);
  return (
    found != null &&
    found.every(file => stampOf(context, file)?.type === 'component') &&
    uncoveredSources(dir, found).length === 0 &&
    !METADATA_ROOTS.some(kind => {
      const root = context.roots[kind];
      return kind !== 'components' && root != null && pathIsInside(root, dir);
    })
  );
}

/**
 * The step a component doc added to the components root also needs when
 * another root reads that folder too, and would read the new doc as its own.
 * @param {FixContext} context
 * @returns {string} a sentence with a leading space, or ''
 */
export function newComponentDocNote(context) {
  const components = context.roots.components;
  return components ? overlapNote(context, components, 'components') : '';
}

/**
 * The theme beside \`file\` whose source imports it, if any: such a file is
 * part of that theme, not a codemod.
 * @param {FixContext} context
 * @param {string} file
 * @returns {{doc: string, stamp: ContributionStamp, source: string} | null}
 */
export function themeImporting(context, file) {
  const dir = path.dirname(file);
  let entries;
  try {
    entries = fs.readdirSync(dir);
  } catch {
    return null;
  }
  for (const name of entries.filter(entry => DOC_CANDIDATE_RE.test(entry))) {
    const doc = path.join(dir, name);
    const stamp = stampOf(context, doc);
    const [source] = stamp?.type === 'theme' ? sourcesBeside(doc, 'theme') : [];
    if (!stamp || !source) continue;
    const edges = localImports(path.join(dir, source));
    if (edges?.some(edge => edge.target === file)) return {doc, stamp, source};
  }
  return null;
}

/**
 * The fix for contribution metadata at the top of the codemods root, which
 * the codemod checks read as a stray codemod. `source` names that doc's theme
 * source when the stray file is the source rather than the doc.
 * @param {FixContext} context
 * @param {string} file the metadata doc
 * @param {ContributionStamp} stamp
 * @param {string} [source]
 * @param {string} [stray] a file that source imports, when the stray file is
 *   that one
 * @returns {string}
 */
export function notACodemodFix(context, file, stamp, source, stray) {
  const key = ROOT_FOR_TYPE[stamp.type];
  const root = context.roots[key];
  const codemods = context.roots.codemods;
  let lead = `Fix: ${path.basename(file)} has type: '${stamp.type}', so it is not a codemod`;
  if (source && stray) {
    lead = `Fix: ${stray} is imported by ${source}, the source of ${path.basename(file)}, which has type: '${stamp.type}', so none of them is a codemod`;
  } else if (source) {
    lead = `Fix: ${source} is the source of ${path.basename(file)}, which has type: '${stamp.type}', so neither is a codemod`;
  }
  if (root && codemods && pathIsInside(file, root)) {
    // Its own root reads it already; only the codemods root is in the way.
    const [companion] = sourcesBeside(file, stamp.type);
    return `${lead}; move ${path.basename(file)}${companion ? ` and ${companion}` : ''} out of ${place(context, codemods)} to another folder under ${place(context, root)} (the ${key} root).${sourceNote(file, stamp.type)}${overlapNote(context, root, key)}`;
  }
  const {main, notes} = root
    ? moveUnder(context, file, stamp, root)
    : moveToNewRoot(context, file, stamp);
  return `${lead}; ${main}.${notes}`;
}

/**
 * The fix for a doc that the components root reads although its type says it
 * is another kind of metadata.
 * @param {FixContext} context
 * @param {string} file
 * @param {ContributionStamp} stamp a stamp whose type is not `component`
 * @returns {string}
 */
export function notAComponentFix(context, file, stamp) {
  const components = /** @type {string} */ (context.roots.components);
  const key = ROOT_FOR_TYPE[stamp.type];
  const root = context.roots[key];
  const lead = `Fix: ${path.basename(file)} has type: '${stamp.type}', so it is not a component`;
  if (components === context.packageDir) {
    const why = `${lead}, and the components root is the package root, which reads every doc in the package`;
    const target = path.join(context.packageDir, 'components');
    return holdsOnlyComponents(context, target)
      ? `${why}; create components/, move the components into it, and set \`components: './components'\` in ${context.manifest}.${overlapNote(context, target, 'components')}`
      : `${why}; move the components into a folder that holds only components, and set \`components\` to that folder in ${context.manifest}.${overlapNote(context, undefined, 'components')}`;
  }
  if (root && pathIsInside(root, components)) {
    const {main, notes} = separateRoots(context, file, stamp, root);
    return `${lead}, and ${main}.${sourceNote(file, stamp.type)}${notes}`;
  }
  if (root && pathIsInside(file, root)) {
    return `${lead}; move it out of ${place(context, components)} (the components root) to another folder under ${place(context, root)} (the ${key} root).${sourceNote(file, stamp.type)}${overlapNote(context, root, key)}`;
  }
  const {main, notes} = root
    ? moveUnder(context, file, stamp, root)
    : moveToNewRoot(context, file, stamp);
  return `${lead}; ${main}.${notes}`;
}

/**
 * The fix when a kind's root sits inside the components root, so nothing
 * placed in it escapes the components root.
 * @param {FixContext} context
 * @param {string} file
 * @param {ContributionStamp} stamp
 * @param {string} root the declared root for this kind
 * @returns {{main: string, notes: string}}
 */
function separateRoots(context, file, stamp, root) {
  const components = /** @type {string} */ (context.roots.components);
  const key = ROOT_FOR_TYPE[stamp.type];
  const target = path.join(context.packageDir, key);
  const free = !fs.existsSync(target) && isFreeFolder(context, target);
  const picked = overlapNote(context, undefined, key);
  if (root === components) {
    const both = `the ${key} root and the components root are both ${place(context, root)}`;
    return free
      ? {
          main: `${both}; move the ${ROOT_HOLDS[key]} into ${key}/ and set \`${key}: './${key}'\` in ${context.manifest}`,
          notes: '',
        }
      : {
          main: `${both}; move the ${ROOT_HOLDS[key]} into a folder of their own and set \`${key}\` to that folder in ${context.manifest}`,
          notes: picked,
        };
  }
  const overlap = `the components root ${place(context, components)} also reads the ${key} root ${place(context, root)} inside it`;
  const carried = pathIsInside(file, root);
  // The root's contents move with it, so a name it holds is still taken.
  const slug = themeSlug(context, file, stamp);
  const taken =
    !carried &&
    (key === 'themes'
      ? hasEntry(root, slug)
      : takenIn(context, file, stamp, root) != null);
  const [source] = sourcesBeside(file, stamp.type);
  const name = '<name>';
  const suffix = path.basename(file).slice(docStem(file).length);
  const renamed = `give it a new name: ${source ? `rename it and ${source} to ${name}${suffix} and ${name}.tsx` : `rename it to ${name}${suffix}`}, set its \`name\` to ${name}, and move ${source ? 'them' : 'it'}`;
  const newSlug = taken ? '<slug>' : slug;
  const slugNote = taken
    ? ` and set \`name\` in ${path.basename(file)} to <slug>`
    : '';
  if (free) {
    let then = '';
    if (!carried && key === 'themes') {
      then = `, then ${moveTheme(context, file, stamp, target, newSlug)}${slugNote}`;
    } else if (!carried) {
      then = `, then ${taken ? renamed : 'move it'} into ${key}/`;
    }
    return {
      main: `${overlap}; move ${place(context, root)} to ${key}/ and set \`${key}: './${key}'\` in ${context.manifest}${then}`,
      notes: '',
    };
  }
  let then = '';
  if (!carried && key === 'themes') {
    const {what, folder} = themeFiles(context, file, root);
    then = folder
      ? `, then move ${what} into that root as ${newSlug}/${slugNote}`
      : `, then move ${what} into a ${newSlug}/ folder in that root${slugNote}`;
  } else if (!carried) {
    then = `, then ${taken ? renamed : 'move it'} into that root`;
  }
  return {
    main: `${overlap}; move ${place(context, root)} out of ${place(context, components)} and set \`${key}\` to its new path in ${context.manifest}${then}`,
    notes: picked,
  };
}