Skip to content

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

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

/**
 * @file The `render` subject's adapter: its only access to the environment.
 * It reads the page or rendered file, runs the renderer, and writes results.
 *
 * @position api/render — adapter for api/render/render.mjs
 */

import * as fs from 'node:fs';
import * as path from 'node:path';
import {createRequire} from 'node:module';
import {AstryxError} from '../error.mjs';
import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
import {
  PAGE_EXTENSIONS,
  RenderError,
  renderPage,
} from '../../foundation/render/render-page.mjs';
import {readSourceBlock} from '../../foundation/render/source-block.mjs';
import {embeddedPathProblem, runnerPicksUp} from '../../foundation/render/embedded-files.mjs';
import {isAssetBytes, isAssetPath} from '../../foundation/render/assets.mjs';
import {createFileProtectionResolver} from '../../foundation/fs/file-protection.mjs';
import {reachableFiles, receivingAliases} from '../../foundation/render/embedded-imports.mjs';
import {isAstryxMarkup} from '../../foundation/render/html-reader.mjs';
import {rebuildPage} from '../../foundation/render/rebuild.mjs';
import {cliVersion} from '../../foundation/integrations/cli-peer-version.mjs';
import {assertWithin, PathSafetyError} from '../../foundation/fs/path-safety.mjs';
import {requireCoreDir} from '../../foundation/fs/paths.mjs';
import {runChoice} from '../../foundation/release/run-context.mjs';
import {isServedPackage} from '../../foundation/render/served-packages.mjs';
import {hostedRun, recordResolved} from '../../foundation/runtime/package-root.mjs';

export {PAGE_EXTENSIONS, embeddedPathProblem};

/** @param {string} cwd @param {string} file */
const shown = (cwd, file) => {
  const rel = path.relative(cwd, file);
  return rel && !rel.startsWith('..') && !path.isAbsolute(rel)
    ? rel.split(path.sep).join('/')
    : file;
};

/**
 * Read a file the caller named, or throw ERR_FILE_NOT_FOUND.
 * @param {string} file absolute
 * @param {string} cwd
 * @returns {Buffer}
 */
function readInput(file, cwd) {
  try {
    if (!fs.statSync(file).isFile()) throw new Error('not a file');
    return fs.readFileSync(file);
  } catch {
    throw new AstryxError(
      `${shown(cwd, file)} does not exist`,
      [],
      ERROR_CODES.ERR_FILE_NOT_FOUND,
    );
  }
}

/**
 * Whether @astryxdesign/core resolves from a folder (or the nearest existing
 * folder above it).
 * @param {string} dir
 */
function resolvesCore(dir) {
  let d = dir;
  while (!fs.existsSync(d) && path.dirname(d) !== d) d = path.dirname(d);
  try {
    createRequire(path.join(d, 'noop.js')).resolve('@astryxdesign/core');
    return true;
  } catch {
    return false;
  }
}

/**
 * Refuse a write outside the current folder, symlinks followed (cli-surface
 * INV10).
 * @param {string} file absolute
 * @param {string} cwd
 * @param {string} what
 * @returns {string}
 */
function confined(file, cwd, what) {
  try {
    return assertWithin(file, cwd, {allowAbsolute: true, label: what});
  } catch (e) {
    if (e instanceof PathSafetyError) {
      throw new AstryxError(
        `${what} ${shown(cwd, file)} is outside the current folder; nothing was written. Write inside the folder you run the command from.`,
        [],
        ERROR_CODES.ERR_PATH_TRAVERSAL,
      );
    }
    throw e;
  }
}

/**
 * Refuse, before anything is written, a write that reaches through a
 * symbolic link, and the replacement of an existing file the project
 * protects (generated, vendored, ignored, a dependency or version-control
 * metadata; spec:AST-040 FR2), even with --overwrite.
 * @param {string[]} files absolute
 * @param {string} cwd
 */
function refuseProtected(files, cwd) {
  for (const file of files) {
    let current = cwd;
    for (const part of path.relative(cwd, file).split(path.sep)) {
      current = path.join(current, part);
      let stat;
      try {
        stat = fs.lstatSync(current);
      } catch {
        break;
      }
      if (stat.isSymbolicLink()) {
        throw new AstryxError(
          `${shown(cwd, file)} is reached through a symbolic link (${shown(cwd, current)}); nothing was written.`,
          [],
          ERROR_CODES.ERR_PATH_TRAVERSAL,
        );
      }
    }
  }
  const existing = files.filter(file => fs.existsSync(file));
  if (existing.length === 0) return;
  /** @type {ReturnType<typeof createFileProtectionResolver>} */
  let resolver;
  try {
    resolver = createFileProtectionResolver(cwd);
  } catch (e) {
    throw new AstryxError(
      `Could not read this project's file protection (${e instanceof Error ? e.message : String(e)}), so no existing file is replaced; nothing was written.`,
      [],
      ERROR_CODES.ERR_FILE_EXISTS,
    );
  }
  const blocked = existing.flatMap(file => {
    const protection = resolver.classify(file)[0];
    return protection ? [`${shown(cwd, file)} (${protection.declaration})`] : [];
  });
  if (blocked.length > 0) {
    throw new AstryxError(
      `${blocked.join(', ')} ${blocked.length === 1 ? 'is' : 'are'} protected, so never replaced, even with --overwrite; nothing was written. Choose another --out.`,
      [],
      ERROR_CODES.ERR_FILE_EXISTS,
    );
  }
}

/**
 * Write several files all or nothing: each goes to a temporary file beside
 * its target first, and only when every one is written are they moved into
 * place. On a failure, the temporary files and the folders this made are
 * removed, so nothing is left behind.
 * @param {{file: string, bytes: Buffer}[]} writes absolute targets
 * @param {string} cwd
 */
function writeAll(writes, cwd) {
  /** @type {string[]} */
  const madeDirs = [];
  /** @type {{temp: string, file: string}[]} */
  const staged = [];
  const undo = () => {
    for (const {temp} of staged) fs.rmSync(temp, {force: true});
    for (const dir of madeDirs.reverse()) {
      try {
        fs.rmdirSync(dir);
      } catch {
        // Not empty or already gone: leave it.
      }
    }
  };
  let current = '';
  try {
    for (const w of writes) {
      current = w.file;
      /** @type {string[]} */
      const missing = [];
      for (let d = path.dirname(w.file); !fs.existsSync(d); d = path.dirname(d)) missing.unshift(d);
      for (const d of missing) {
        fs.mkdirSync(d);
        madeDirs.push(d);
      }
      const temp = `${w.file}.astryx-${process.pid}.tmp`;
      fs.writeFileSync(temp, w.bytes, {flag: 'wx'});
      staged.push({temp, file: w.file});
    }
    for (const {temp, file} of staged) {
      current = file;
      fs.renameSync(temp, file);
    }
  } catch (e) {
    undo();
    throw new AstryxError(
      `Could not write ${shown(cwd, current)}: ${/** @type {Error} */ (e).message}; nothing was written.`,
      [],
      ERROR_CODES.ERR_WRITE_FAILED,
    );
  }
}

/**
 * Write one file, creating its folder.
 * @param {string} file absolute
 * @param {string | Buffer} content
 * @param {string} cwd
 */
function writeOutput(file, content, cwd) {
  try {
    fs.mkdirSync(path.dirname(file), {recursive: true});
    fs.writeFileSync(file, content);
  } catch (e) {
    throw new AstryxError(
      `Could not write ${shown(cwd, file)}: ${/** @type {Error} */ (e).message}`,
      [],
      ERROR_CODES.ERR_WRITE_FAILED,
    );
  }
}

/** @param {unknown} e */
function asAstryxError(e) {
  if (e instanceof RenderError) {
    const code = /** @type {import('../../foundation/response/error-codes.mjs').ErrorCode} */ (e.code);
    /** @type {{name: string, reason: string}[]} */
    const suggestions = [];
    if (e.code === 'ERR_RENDER_MISSING_DEPENDENCY' && typeof e.detail?.package === 'string') {
      suggestions.push({name: `npm install ${e.detail.package}`, reason: 'install the package the page imports'});
    }
    return new AstryxError(e.message, suggestions, code);
  }
  const err = /** @type {any} */ (e);
  if (typeof err?.code === 'string' && err.code.startsWith('ERR_RENDER_')) {
    return new AstryxError(err.message, [], err.code);
  }
  return e;
}

/**
 * The package set the CLI runs from, for a page outside a project
 * (architecture:cli-surface INV30): the Core it carries, found by the rule of
 * every command that answers from Core outside a project. Inside a project
 * (spec AST-081: a Core or CLI the folder reads, or a package.json that
 * declares one) the project's packages serve the page alone, so this is
 * null.
 * When the carried Core cannot be had, the reason is kept for the error a
 * page that needs it gets (spec AST-081 FR3).
 * @param {string} input absolute path of the page
 * @returns {{dir: string, integrations: readonly string[]} | {unavailable: Error} | null}
 */
function servedSet(input) {
  const dir = path.dirname(input);
  if (runChoice(dir).inProject) return null;
  try {
    return {dir: requireCoreDir(dir), integrations: hostedRun()?.integrations ?? []};
  } catch (e) {
    const err = /** @type {any} */ (e);
    return err?.code === ERROR_CODES.ERR_VERSIONS_UNAVAILABLE ? {unavailable: err} : null;
  }
}

/**
 * Render a page module to one HTML file and write it.
 * @param {{cwd: string, input: string, output: string, title?: string}} args absolute paths
 * @returns {Promise<import('./render.type.mjs').RenderPageResponse['data']>}
 */
export async function renderToFile({cwd, input, output, title}) {
  readInput(input, cwd);
  confined(output, cwd, 'The output');
  /** @type {import('../../foundation/render/render-page.mjs').RenderedPage} */
  let page;
  try {
    const set = servedSet(input);
    try {
      page = await renderPage(input, {title, version: cliVersion(), served: set && 'dir' in set ? set : null});
    } catch (e) {
      // A page that needs the Core the CLI could not obtain says why.
      const missing = /** @type {any} */ (e)?.code === 'ERR_RENDER_MISSING_DEPENDENCY' ? /** @type {any} */ (e).detail?.package : null;
      if (set && 'unavailable' in set && typeof missing === 'string' && isServedPackage(missing, hostedRun()?.integrations ?? [])) {
        throw new AstryxError(set.unavailable.message, [], ERROR_CODES.ERR_VERSIONS_UNAVAILABLE);
      }
      throw e;
    }
  } catch (e) {
    throw asAstryxError(e);
  }
  for (const {name, dir} of page.fromSet) {
    let version = null;
    try {
      version = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).version;
    } catch {
      // A package without a readable version is still named.
    }
    recordResolved(name, version, dir, 'package-set');
  }
  refuseProtected([output], cwd);
  // An existing file is replaced only when a render wrote it.
  if (
    fs.existsSync(output) &&
    fs.statSync(output).isFile() &&
    !/<meta name="generator" content="Astryx[ "]/.test(fs.readFileSync(output, 'utf8').slice(0, 4096))
  ) {
    throw new AstryxError(
      `${shown(cwd, output)} already exists and was not written by a render, so it is not replaced; nothing was written. Choose another --out.`,
      [],
      ERROR_CODES.ERR_FILE_EXISTS,
    );
  }
  writeOutput(output, page.html, cwd);
  return {
    input: shown(cwd, input),
    output: shown(cwd, output),
    bytes: Buffer.byteLength(page.html),
    files: page.files,
    stylesheets: page.stylesheets,
    classes: page.classes,
    cssBytes: page.cssBytes,
    images: page.images,
    warnings: page.warnings,
  };
}

/**
 * Refuse files a test, story or benchmark runner would run where they land,
 * judged from the repository root (every folder above the file up to it),
 * else the topmost folder with a package.json, else the current folder.
 * @param {string[]} files absolute
 * @param {string} cwd
 * @param {string} input
 */
function refuseRunnable(files, cwd, input) {
  /** @param {string} marker */
  const nearest = marker => {
    for (let d = cwd; ; d = path.dirname(d)) {
      if (fs.existsSync(path.join(d, marker))) return d;
      if (path.dirname(d) === d) return null;
    }
  };
  let topPackage = null;
  for (let d = cwd; ; d = path.dirname(d)) {
    if (fs.existsSync(path.join(d, 'package.json'))) topPackage = d;
    if (path.dirname(d) === d) break;
  }
  const projectRoot = nearest('.git') ?? topPackage ?? cwd;
  const runnable = files
    .map(file => path.relative(projectRoot, file).split(path.sep))
    .filter(segments => runnerPicksUp(segments))
    .map(segments => segments.join('/'));
  if (runnable.length > 0) {
    throw new AstryxError(
      `${shown(cwd, input)} would write ${runnable.join(', ')} (from the project root), where a test, story or benchmark runner would run it; nothing was written. Restore it somewhere else with --out.`,
      [],
      ERROR_CODES.ERR_INVALID_ARGUMENT,
    );
  }
}

/**
 * The new folder a restore without --out writes into: beside the HTML file,
 * named after it (`report.html` gives `report-restored/`, then
 * `report-restored-2/` when that exists).
 * @param {string} input absolute
 */
function restoreFolder(input) {
  const stem = path.basename(input).replace(/\.[^.]+$/, '');
  let folder = path.join(path.dirname(input), `${stem}-restored`);
  for (let n = 2; fs.existsSync(folder); n++) folder = path.join(path.dirname(input), `${stem}-restored-${n}`);
  return folder;
}

/**
 * Turn a rendered HTML file back into a page module.
 * @param {{cwd: string, input: string, output: string | undefined, overwrite: boolean}} args absolute paths
 * @returns {import('./render.type.mjs').RenderReverseResponse['data']}
 */
export function reverseToFile({cwd, input, output, overwrite}) {
  const html = readInput(input, cwd).toString('utf8');
  const block = readSourceBlock(html);
  /** @param {string[]} files */
  const refuseExisting = files => {
    if (overwrite) return;
    const existing = files.filter(file => fs.existsSync(file));
    if (existing.length > 0) {
      throw new AstryxError(
        `${existing.map(file => shown(cwd, file)).join(', ')} already exist${existing.length === 1 ? 's' : ''}; nothing was written. Pass --overwrite to replace ${existing.length === 1 ? 'it' : 'them'}.`,
        [],
        ERROR_CODES.ERR_FILE_EXISTS,
      );
    }
  };
  /** A page is never written as a configuration, test, spec or story file. @param {string} file */
  const refuseConfigTarget = file => {
    const rel = path.relative(cwd, file).split(path.sep).join('/');
    const where = rel.startsWith('..') || path.isAbsolute(rel) ? path.basename(file) : rel;
    // Where the page lands must be a page module, and a name no tool takes
    // as its own (configuration, a runner's file): the same rules as any
    // file a restore writes.
    const problem = embeddedPathProblem(where, {page: true}) ?? embeddedPathProblem(where);
    if (problem) {
      throw new AstryxError(
        `${shown(cwd, file)} is not a page module file name a reverse writes (${problem.reason}); nothing was written.`,
        [],
        ERROR_CODES.ERR_INVALID_ARGUMENT,
      );
    }
  };
  if (block.found && 'damaged' in block) {
    throw new AstryxError(
      `${shown(cwd, input)} carries an Astryx page source, but ${block.damaged}, so it cannot be given back exactly.`,
      [],
      ERROR_CODES.ERR_RENDER_SOURCE_DAMAGED,
    );
  }
  if (block.found) {
    const {source} = block;
    // A file someone sends is untrusted: it may carry only what a render
    // embeds (the page, and the stylesheets, JSON and images it imports).
    source.files.forEach((f, i) => {
      const problem = embeddedPathProblem(f.path, {page: i === 0});
      if (problem) {
        throw new AstryxError(
          `${shown(cwd, input)} carries ${problem.reason}, which a render never embeds; nothing was written.`,
          [],
          ERROR_CODES[problem.code],
        );
      }
    });
    // Without --out, the page and the files it imports come back into a new
    // folder beside the HTML file, named after it (`report.html` gives
    // `report-restored/`), with the layout they were rendered in. Nothing in
    // the received file decides where in your project anything goes.
    const requested = output ?? path.join(restoreFolder(input), ...source.files[0].path.split('/'));
    refuseConfigTarget(requested);
    const seen = new Set();
    for (const f of source.files) {
      const key = f.path.toLowerCase();
      if (seen.has(key)) {
        throw new AstryxError(
          `${shown(cwd, input)} lists ${f.path} more than once, which a render never does; nothing was written.`,
          [],
          ERROR_CODES.ERR_RENDER_SOURCE_DAMAGED,
        );
      }
      seen.add(key);
    }
    // Modules, stylesheets and JSON are written only when the page reaches
    // them through its own imports: one it never imports is not part of it,
    // whatever its name.
    const {reached, missing} = reachableFiles(source.files, {aliases: receivingAliases(path.dirname(requested))});
    // A carried image, font or media file needs no import to be part of the
    // page (it may be named in markup, a stylesheet, JSON or a computed
    // path): the render's own list is the authority, so it is kept when its
    // bytes are a known image, font or media format (any, whatever the
    // extension), and goes where the layout puts it.
    for (const f of source.files) {
      if (reached.has(f.path) || !isAssetPath(f.path)) continue;
      if (isAssetBytes(Buffer.from(f.base64, 'base64'))) reached.set(f.path, {relative: true, aliased: new Set()});
    }
    const stray = source.files.filter(f => !reached.has(f.path)).map(f => f.path);
    if (stray.length > 0) {
      throw new AstryxError(
        `${shown(cwd, input)} carries ${stray.length === 1 ? 'a file' : 'files'} the page does not import, or that is not the image, font or media file its name says (${stray.join(', ')}), which a render never embeds; nothing was written. A file reached through a path alias needs the same alias in this project's tsconfig.json or jsconfig.json.`,
        [],
        ERROR_CODES.ERR_RENDER_SOURCE_DAMAGED,
      );
    }
    // Each file the page reaches by a relative import goes where that import
    // finds it from the page's new folder, so every relative import still
    // resolves wherever the page lands; a file reached through an alias goes
    // where this project's alias points. Every file but the page must land
    // in a folder this restore creates: a received file never adds a file to
    // a folder that already exists (a server hook at the project root, a
    // middleware module), so a page with neighbours comes back into a new
    // folder.
    const entryDir = path.posix.dirname(source.files[0].path);
    const anchor = path.dirname(requested);
    /** @param {string} p */
    const placeFrom = p => path.resolve(anchor, path.posix.relative(entryDir, p));
    // A file beside the page or elsewhere goes only into a folder this
    // restore creates: never into a folder that already exists.
    // The one folder every file but the page must land in: the topmost
    // folder on the page's path that this restore creates. When the page's
    // folder already exists there is none, so a page with neighbours comes
    // back only into a new folder.
    /** @type {string | null} */
    let home = null;
    for (let d = anchor; !fs.existsSync(d) && path.dirname(d) !== d; d = path.dirname(d)) home = d;
    const within = (/** @type {string} */ file) => {
      if (!home) return false;
      const rel = path.relative(home, file);
      return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
    };
    const target = path.join(anchor, path.basename(requested));
    /** @type {{file: string, bytes: Buffer}[]} */
    const writes = [];
    const placed = new Set();
    /** @type {string[]} */
    const outside = [];
    /** @type {string[]} */
    const aliasedOutside = [];
    source.files.forEach((f, i) => {
      const reach = /** @type {import('../../foundation/render/embedded-imports.mjs').Reach} */ (reached.get(f.path));
      const relative = i === 0 ? [target] : reach.relative ? [placeFrom(f.path)] : [];
      for (const [file, aliased] of [...relative.map(x => /** @type {[string, boolean]} */ ([x, false])), ...[...reach.aliased].map(x => /** @type {[string, boolean]} */ ([x, true]))]) {
        if (placed.has(file)) continue;
        placed.add(file);
        if (i > 0 && !within(file)) (aliased ? aliasedOutside : outside).push(file);
        writes.push({file, bytes: Buffer.from(f.base64, 'base64')});
      }
    });
    if (aliasedOutside.length > 0) {
      throw new AstryxError(
        `${shown(cwd, input)} imports ${aliasedOutside.map(file => shown(cwd, file)).join(', ')} through a path alias that points outside the folder the restore creates; nothing was written. A received page never adds files to your existing folders: change those imports to relative ones before rendering, or restore it in a project whose alias points somewhere new.`,
        [],
        ERROR_CODES.ERR_PATH_TRAVERSAL,
      );
    }
    if (outside.length > 0) {
      const top = entryDir === '.' ? '' : `${entryDir}/`;
      let fresh = 'restored';
      for (let n = 2; fs.existsSync(path.join(cwd, fresh)); n++) fresh = `restored-${n}`;
      const suggestion = `--out ${fresh}/${top}${path.basename(requested)}`;
      throw new AstryxError(
        `${shown(cwd, input)} would add ${outside.map(file => shown(cwd, file)).join(', ')} outside the folder the restore creates; nothing was written. A received page writes the files it imports only inside one new folder: restore it into one, such as ${suggestion}.`,
        [{name: suggestion, reason: 'restore the page and the files it imports into a new folder, keeping their layout'}],
        ERROR_CODES.ERR_PATH_TRAVERSAL,
      );
    }
    writes.forEach((w, i) => confined(w.file, cwd, i === 0 ? 'The page' : 'The embedded file'));
    refuseRunnable(writes.map(w => w.file), cwd, input);
    refuseExisting(writes.map(w => w.file));
    refuseProtected(writes.map(w => w.file), cwd);
    writeAll(writes, cwd);
    return {
      input: shown(cwd, input),
      mode: 'embedded',
      output: shown(cwd, target),
      files: writes.map(w => shown(cwd, w.file)),
      // The page is byte for byte the one rendered; an import it makes that
      // the file does not carry (a file a render never embeds) is named.
      exact: missing.length === 0,
      ...(missing.length > 0 ? {missing} : {}),
    };
  }
  // A file a render wrote, whose source block was taken out on the way
  // (sanitizers and editors strip <script> elements), says so.
  if (!isAstryxMarkup(html) && /<meta name="generator" content="Astryx[ "]/.test(html)) {
    throw new AstryxError(
      `${shown(cwd, input)} was rendered by Astryx, but its embedded source was removed (a sanitizer or an editor strips <script> blocks) and it has no Astryx components to rebuild from; nothing was written. Render the page again from its source and send the new file as is.`,
      [],
      ERROR_CODES.ERR_RENDER_SOURCE_DAMAGED,
    );
  }
  if (!isAstryxMarkup(html)) {
    throw new AstryxError(
      `${shown(cwd, input)} is not an Astryx page: it has no embedded source and no Astryx components to rebuild from. To start an Astryx page like it, run astryx build "<what the page is>".`,
      [
        {
          name: 'astryx build "<what the page is>"',
          reason: 'start an Astryx page from a description of it instead',
        },
      ],
      ERROR_CODES.ERR_RENDER_NOT_ASTRYX,
    );
  }
  const target = output ?? path.join(restoreFolder(input), 'page.tsx');
  refuseConfigTarget(target);
  confined(target, cwd, 'The page');
  refuseRunnable([target], cwd, input);
  refuseExisting([target]);
  // Components resolve from where the page will live, then from the HTML
  // file's folder, then from the current folder.
  const from =
    [path.dirname(target), path.dirname(input), cwd].find(d => resolvesCore(d)) ?? cwd;
  const rebuilt = rebuildPage(html, from);
  refuseProtected([target], cwd);
  writeOutput(target, rebuilt.source, cwd);
  return {
    input: shown(cwd, input),
    mode: 'rebuilt',
    output: shown(cwd, target),
    files: [shown(cwd, target)],
    exact: false,
    components: rebuilt.components,
    elements: rebuilt.elements,
    unknown: rebuilt.unknown,
    omitted: rebuilt.omitted,
  };
}