Skip to content

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

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

/**
 * @file Which embedded files the page itself reaches, for `astryx
 * experimental render --reverse`. A received file is untrusted, so its list
 * of files is not: a file is written only when the embedded page reaches it
 * through its own imports (static, re-exports, `import()` and `require()` of
 * a string), followed module by module through the embedded tree. Relative
 * imports resolve inside the tree; an alias import resolves through the
 * receiving project's own `tsconfig.json` or `jsconfig.json` paths, never the
 * sender's.
 *
 * @position foundation/render — used by the render subject's adapter
 */

import * as fs from 'node:fs';
import * as path from 'node:path';
import {parse} from '@babel/parser';
import {PAGE_EXTENSIONS} from './embedded-files.mjs';
import postcss from 'postcss';
import {matchPath, readPathsIn} from './ts-paths.mjs';
import {isAssetPath} from './assets.mjs';

/**
 * What a stylesheet's `@import` rules load, read with postcss so comments
 * are ignored.
 * @param {string} css
 * @returns {string[]}
 */
export function cssImports(css) {
  /** @type {string[]} */
  const out = [];
  try {
    postcss.parse(css).walkAtRules(/^import$/i, rule => {
      const m = /^\s*(?:url\(\s*(['"]?)([\s\S]*?)\1\s*\)|(['"])([\s\S]*?)\3)/.exec(rule.params);
      const url = m ? (m[2] ?? m[4]) : '';
      if (url) out.push(url);
    });
  } catch {
    // Not valid CSS: it imports nothing a restore needs.
  }
  return out;
}

/** Extensions an extensionless import may stand for, in resolution order. */
const RESOLVE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.json'];

/**
 * The string specifiers one module imports.
 * @param {string} source
 * @param {string} file for the parser's TypeScript/JSX choice
 * @returns {string[]}
 */
export function importSpecifiers(source, file) {
  return scanModule(source, file).imports;
}

/**
 * Relative asset paths in a piece of text: a `./`/`../` path to an image or
 * font, bare or inside `url(...)`.
 * @param {string} text
 * @returns {string[]}
 */
export function assetRefsIn(text) {
  /** @type {string[]} */
  const out = [];
  for (const m of text.matchAll(/(?:^|url\(\s*['"]?)(\.\.?\/[^'")\s]+)/g)) {
    const ref = m[1].split(/[?#]/)[0];
    if (isAssetPath(ref)) out.push(ref);
  }
  return out;
}

/**
 * One module's imports, and the relative asset paths its strings name
 * (`<img src="./logo.png">`, `url(./bg.png)` in a style).
 * @param {string} source
 * @param {string} file
 * @returns {{imports: string[], assets: string[]}}
 */
function scanModule(source, file) {
  /** @type {string[]} */
  const assets = [];
  /** @type {any} */
  let ast;
  try {
    ast = parse(source, {
      sourceType: 'module',
      allowReturnOutsideFunction: true,
      errorRecovery: true,
      plugins: /\.(tsx?|mts|cts)$/.test(file) ? ['jsx', 'typescript'] : ['jsx'],
    });
  } catch {
    return {imports: [], assets: []};
  }
  /** @type {string[]} */
  const out = [];
  /** @param {any} node */
  const visit = node => {
    if (!node || typeof node.type !== 'string') return;
    if (node.type === 'StringLiteral') assets.push(...assetRefsIn(node.value));
    else if (node.type === 'TemplateElement') assets.push(...assetRefsIn(node.value?.cooked ?? ''));
    if (
      (node.type === 'ImportDeclaration' ||
        node.type === 'ExportNamedDeclaration' ||
        node.type === 'ExportAllDeclaration') &&
      node.source?.type === 'StringLiteral'
    ) {
      out.push(node.source.value);
    } else if (
      node.type === 'ImportExpression' &&
      node.source?.type === 'StringLiteral'
    ) {
      out.push(node.source.value);
    } else if (
      node.type === 'CallExpression' &&
      node.arguments?.[0]?.type === 'StringLiteral' &&
      (node.callee?.type === 'Import' ||
        (node.callee?.type === 'Identifier' && node.callee.name === 'require'))
    ) {
      out.push(node.arguments[0].value);
    }
    for (const key of Object.keys(node)) {
      if (key === 'loc' || key === 'start' || key === 'end' || key === 'extra') continue;
      const value = node[key];
      if (Array.isArray(value)) value.forEach(visit);
      else if (value && typeof value === 'object' && typeof value.type === 'string') visit(value);
    }
  };
  visit(ast.program);
  return {imports: out, assets};
}

/**
 * The path aliases (`compilerOptions.paths`) of the project that holds
 * `dir`, by TypeScript's rules (see ts-paths.mjs).
 * @param {string} dir
 * @returns {import('./ts-paths.mjs').PathPattern[]}
 */
export function receivingAliases(dir) {
  let d = dir;
  while (!fs.existsSync(d) && path.dirname(d) !== d) d = path.dirname(d);
  for (;;) {
    const found = readPathsIn(d);
    if (found) return found;
    if (fs.existsSync(path.join(d, 'package.json'))) return [];
    const up = path.dirname(d);
    if (up === d) return [];
    d = up;
  }
}

/**
 * @typedef {object} Reach
 * @property {boolean} relative - Reached by a relative import (or it is the
 *   page), so it goes where the page's layout puts it.
 * @property {Set<string>} aliased - Absolute paths a receiving-project alias
 *   import names for it, so it also goes there.
 */

/**
 * The embedded files the page reaches through its imports.
 * @param {{path: string, base64: string}[]} files the embedded files, page
 *   first; every path appears once (callers refuse duplicates first)
 * @param {{aliases?: import('./ts-paths.mjs').PathPattern[]}} [options] the
 *   receiving project's path aliases (see receivingAliases)
 * @returns {{reached: Map<string, Reach>, missing: string[]}} the reached
 *   tree paths, and the relative imports the file does not carry
 */
export function reachableFiles(files, {aliases = []} = {}) {
  const byPath = new Map(files.map(f => [f.path, f]));
  /** @type {Map<string, Reach>} */
  const reached = new Map();
  /** @type {Set<string>} */
  const missing = new Set();
  /** @param {string} candidate tree path, `/`-separated */
  const resolveIn = candidate => {
    if (byPath.has(candidate)) return candidate;
    for (const ext of RESOLVE_EXTENSIONS) if (byPath.has(candidate + ext)) return candidate + ext;
    for (const ext of RESOLVE_EXTENSIONS) if (byPath.has(`${candidate}/index${ext}`)) return `${candidate}/index${ext}`;
    return null;
  };
  /**
   * The one tree file an alias import names: the file whose path ends with
   * the import's rest (`@/components/Header` -> `.../components/Header.tsx`).
   * @param {string} rest
   */
  const bySuffix = rest => {
    /** @type {{path: string, tail: string}[]} */
    const hits = [];
    for (const p of byPath.keys()) {
      for (const tail of [rest, ...RESOLVE_EXTENSIONS.map(e => rest + e), ...RESOLVE_EXTENSIONS.map(e => `${rest}/index${e}`)]) {
        if (p === tail || p.endsWith(`/${tail}`)) {
          hits.push({path: p, tail});
          break;
        }
      }
    }
    return hits.length === 1 ? hits[0] : null;
  };
  /** @param {string} p */
  const reach = p => {
    let r = reached.get(p);
    const fresh = !r;
    if (!r) {
      r = {relative: false, aliased: new Set()};
      reached.set(p, r);
    }
    return {r, fresh};
  };
  /** @type {string[]} */
  const queue = [];
  if (files.length > 0) {
    reach(files[0].path).r.relative = true;
    queue.push(files[0].path);
  }
  while (queue.length > 0) {
    const current = /** @type {string} */ (queue.shift());
    const ext = path.posix.extname(current).toLowerCase();
    const isModule = PAGE_EXTENSIONS.includes(ext);
    if (!isModule && ext !== '.css') continue;
    const entry = byPath.get(current);
    if (!entry) continue;
    const source = Buffer.from(entry.base64, 'base64').toString('utf8');
    // Images and fonts a module or stylesheet names by a relative path are
    // part of the page too.
    const scanned = isModule
      ? scanModule(source, current)
      : {
          // A stylesheet's own `@import`s count as imports.
          // A stylesheet's own relative `@import`s count as imports (read
          // with postcss, so a commented-out one does not); a package one
          // (`@scope/pkg/x.css`) or a remote one is not the page's file.
          imports: cssImports(source)
            .filter(ref => !/^([a-z]+:)?\/\//i.test(ref) && !/^[@~]/.test(ref))
            // A bare name (`theme.css`) is the sheet beside it when the file
            // carries one, else a package's.
            .filter(ref => ref.startsWith('.') || byPath.has(path.posix.normalize(path.posix.join(path.posix.dirname(current), ref))))
            .map(ref => (ref.startsWith('.') ? ref : `./${ref}`)),
          assets: assetRefsIn(source),
        };
    for (const ref of scanned.assets) {
      const joined = path.posix.normalize(path.posix.join(path.posix.dirname(current), ref));
      if (joined.startsWith('..')) continue;
      if (!byPath.has(joined)) {
        missing.add(joined);
        continue;
      }
      reach(joined).r.relative = true;
    }
    for (const spec of scanned.imports) {
      const bare = spec.split('?')[0];
      if (bare.startsWith('./') || bare.startsWith('../')) {
        const joined = path.posix.normalize(path.posix.join(path.posix.dirname(current), bare));
        const target = joined.startsWith('..') ? null : resolveIn(joined);
        if (!target) {
          missing.add(joined);
          continue;
        }
        const {r, fresh} = reach(target);
        r.relative = true;
        if (fresh) queue.push(target);
        continue;
      }
      const match = matchPath(aliases, bare);
      if (match) {
        // Each target in order: the file the alias names, matched in the
        // tree by the path's tail, and placed where this project's target
        // puts it (`@/c/Header` -> `<target>/c/Header.tsx`). The target whose
        // folders match the most whole segments of the sent path above the
        // file wins; with no match, the first target does.
        /** @type {{abs: string, hit: {path: string, tail: string}, score: number}[]} */
        const options = [];
        for (const target of match.pattern.targets) {
          const named = target.replace('*', match.capture);
          const ext = path.extname(named);
          const star = target.indexOf('*');
          // The tail starts at the path segment that holds the `*`, so text
          // before it (`icons/icon-*`) is part of the file name.
          const cut = star === -1 ? -1 : target.lastIndexOf(path.sep, star) + 1;
          const rest = (star === -1 ? path.basename(named, ext) : target.slice(cut).replace('*', match.capture))
            .split(path.sep)
            .join('/')
            .replace(/^\/+/, '');
          const hit = rest ? bySuffix(rest) : null;
          if (!hit) continue;
          // The file keeps its own extension or index: `<target>/c/Header` ->
          // `<target>/c/Header.tsx`.
          const abs =
            star !== -1
              ? target.slice(0, cut) + hit.tail
              : ext
                ? named
                : named + hit.tail.slice(rest.length);
          // The folders that hold the target's `*` (or, for a target with
          // none, the target's own folders), against the folders of the sent
          // path above the part the alias named, from the nearest up.
          const targetFolders = (star === -1 ? path.dirname(named) : target.slice(0, cut)).split(path.sep).filter(Boolean);
          const sentTail = hit.tail;
          const sentFolders = hit.path.slice(0, hit.path.length - sentTail.length).split('/').filter(Boolean);
          let score = 0;
          while (
            score < sentFolders.length &&
            score < targetFolders.length &&
            sentFolders[sentFolders.length - 1 - score] === targetFolders[targetFolders.length - 1 - score]
          ) {
            score += 1;
          }
          options.push({abs, hit, score});
        }
        const chosen = options.reduce(
          (/** @type {(typeof options)[number] | undefined} */ best, o) => (!best || o.score > best.score ? o : best),
          undefined,
        );
        if (chosen) {
          const {r, fresh} = reach(chosen.hit.path);
          r.aliased.add(chosen.abs);
          if (fresh) queue.push(chosen.hit.path);
        }
      }
    }
  }
  return {reached, missing: [...missing].sort()};
}