Skip to content

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

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

/**
 * @file Which files a rendered page may carry, for `astryx experimental
 * render`. Rendering embeds only these, and `--reverse` writes only these: a
 * file someone sends can name nothing else. A page is a module; beside it go
 * only the stylesheets, JSON and images it imports. Never a dotfile or a
 * dot-folder (such as `.git/`), never `node_modules`, never a package
 * manifest, lockfile or tool configuration (`package.json`, `tsconfig.json`,
 * `vite.config.ts`, `astryx.config.mjs`, ...), and never a path that climbs
 * (`..`) or starts at the root.
 *
 * @position foundation/render — used by render-page.mjs and the render subject
 */

import {isAssetPath} from './assets.mjs';

/** The file extensions a page module may have. */
export const PAGE_EXTENSIONS = ['.tsx', '.jsx', '.ts', '.js', '.mjs'];

/** JSON files that configure a project or a tool rather than hold page data. */
const CONFIG_JSON =
  /^(package|package-lock|composer|deno|turbo|vercel|nx|lerna|app|bower|now|netlify|firebase|renovate|project|workspace|angular|biome|components)\.jsonc?$|config|(^|[._-])rc\.jsonc?$|(^|[._-])lock\.jsonc?$/i;

/** Tool configuration modules: `vite.config.ts`, `astryx.config.mjs`, `next.config.js`, `.eslintrc.js`, ... */
const CONFIG_MODULE = /(^|\.)config\.[cm]?[jt]sx?$|^[a-z0-9-]+rc\.[cm]?[jt]s$/i;

/** Any script module. */
const SCRIPT = /\.(c|m)?[jt]sx?$/i;
/** Script modules `node --test` and AVA match by a `test-*` name (no JSX). */
const PLAIN_SCRIPT = /\.(c|m)?[jt]s$/i;

/**
 * Whether a test, story or benchmark runner would run the file with nothing
 * importing it, by the union of their default patterns: Jest and Vitest
 * (`*.test.*`, `*.spec.*`, `test.*`, `spec.*`, `__tests__/`), Vitest bench
 * (`*.bench.*`, `*.benchmark.*`), Storybook (`*.stories.*`, `*.story.*`),
 * Cypress (`*.cy.*`), Bun (`*_test.*`, `*_spec.*`), `node --test`
 * (`*-test.*`, `test/`) and AVA (`tests/`), and `test-*` for .js and .ts.
 * @param {string[]} segments the path where the file lands, from the project
 *   root (the folder runners search), `/`-split
 */
export function runnerPicksUp(segments) {
  const base = segments[segments.length - 1];
  if (!SCRIPT.test(base)) return false;
  const stem = base.replace(/\.[^.]+$/, '').toLowerCase();
  const folders = segments.slice(0, -1).map(seg => seg.toLowerCase());
  // Jest's `?(*.)+(spec|test)` repeats: `spectest.js`, `test.spec.js`.
  if (/(^|[._-])(test|spec)+$/.test(stem)) return true;
  if (/\.(bench|benchmark|stories|story|cy)$/.test(stem)) return true;
  if (folders.some(seg => seg === '__tests__' || seg === 'test' || seg === 'tests')) return true;
  // `test-*` only for the .js and .ts families: no default runner picks up
  // `test-results.tsx`.
  if (PLAIN_SCRIPT.test(base) && /^test[-_]/.test(stem)) return true;
  return false;
}

/** @param {string} p */
const extOf = p => {
  const base = p.slice(p.lastIndexOf('/') + 1);
  const dot = base.lastIndexOf('.');
  return dot > 0 ? base.slice(dot).toLowerCase() : '';
};

/**
 * Why a path may not be carried by a rendered page, or null when it may.
 * @param {string} p a `/`-separated path relative to the embedded tree's root
 * @param {{page?: boolean}} [options] `page`: the path is the page itself
 * @returns {{code: 'ERR_PATH_TRAVERSAL' | 'ERR_RENDER_SOURCE_DAMAGED', reason: string} | null}
 */
export function embeddedPathProblem(p, options = {}) {
  if (typeof p !== 'string' || p.length === 0 || p.includes('\0')) {
    return {code: 'ERR_RENDER_SOURCE_DAMAGED', reason: 'an empty or invalid path'};
  }
  if (p.startsWith('/') || /^[a-zA-Z]:/.test(p) || p.includes('\\')) {
    return {code: 'ERR_PATH_TRAVERSAL', reason: `an absolute path (${p})`};
  }
  const segments = p.split('/');
  if (segments.some(s => s === '..' || s === '.' || s === '')) {
    return {code: 'ERR_PATH_TRAVERSAL', reason: `a path outside its own tree (${p})`};
  }
  if (segments.some(s => s.startsWith('.'))) {
    return {code: 'ERR_RENDER_SOURCE_DAMAGED', reason: `a dotfile or dot-folder (${p})`};
  }
  if (segments.includes('node_modules')) {
    return {code: 'ERR_RENDER_SOURCE_DAMAGED', reason: `a file inside node_modules (${p})`};
  }
  const base = segments[segments.length - 1];
  const ext = extOf(p);
  // The page is judged by where it lands (its name in the file is only a
  // default), so only its kind counts here.
  if (options.page) {
    if (!PAGE_EXTENSIONS.includes(ext)) {
      return {code: 'ERR_RENDER_SOURCE_DAMAGED', reason: `a page that is not a page module (${p})`};
    }
    return null;
  }
  // A file a test, story or benchmark runner picks up by its name or folder
  // runs without anyone importing it.
  if (runnerPicksUp(segments)) {
    return {code: 'ERR_RENDER_SOURCE_DAMAGED', reason: `a test, spec, story or benchmark file (${p})`};
  }
  if (((ext === '.json' || ext === '.jsonc') && CONFIG_JSON.test(base)) || CONFIG_MODULE.test(base)) {
    return {code: 'ERR_RENDER_SOURCE_DAMAGED', reason: `a project or tool configuration file (${p})`};
  }
  if (PAGE_EXTENSIONS.includes(ext) || ext === '.css' || ext === '.json' || isAssetPath(p)) return null;
  return {code: 'ERR_RENDER_SOURCE_DAMAGED', reason: `a kind of file a render never embeds (${p})`};
}