@astryxdesign/cli 0.7.12-canary.f543ec7 → 0.7.12

package/foundation/render/page-worker.mjs

@@ -5,17 +5,23 @@
  * the project (TypeScript, JSX and StyleX compiled in memory) and renders its
  * default export to static markup with the project's own React.
  *
- * It runs in a worker thread so a page that never finishes rendering can be
- * stopped, and so nothing the page prints reaches the CLI's own output.
+ * It runs in a worker thread of a small host process (page-host.mjs), so a
+ * page that never finishes rendering can be stopped, nothing the page prints
+ * reaches the CLI's own output, and a crash of Node itself ends only the host,
+ * never the CLI.
  *
  * Outside a project, the Astryx packages the page's folder lacks resolve
  * from the package set the CLI runs from (served-packages.mjs), and React and
  * StyleX always come from that set, so the page loads one copy of each.
  *
- * @input workerData {entry, root, served}
+ * Charts the page imports from recharts draw only after their effects run,
+ * so the server render sets them aside and draws them after it with React
+ * DOM in a small document (charts.mjs).
+ *
+ * @input workerData {entry, root, served, withoutSegmenter}
  * @output one message: {ok: true, markup, css, files, texts, logs} or
  *   {ok: false, error: {code, message, detail?}}
- * @position foundation/render — started by render-page.mjs
+ * @position foundation/render — started by page-host.mjs
  */
 
 import * as fs from 'node:fs';
@@ -25,16 +31,22 @@ import {pathToFileURL} from 'node:url';
 import {format} from 'node:util';
 import {parentPort, workerData} from 'node:worker_threads';
 import {transformSync} from '@babel/core';
+import {matchPath, readPathsIn, resolvePath} from './ts-paths.mjs';
 import {createJiti} from 'jiti';
 import {assetDataUri, isAssetPath} from './assets.mjs';
 import {SINGLE_COPY, isServedPackage, packageOf} from './served-packages.mjs';
 import {findNodeModulesPackage} from '../fs/paths.mjs';
+import {CHART_GLOBAL, CHART_ROOTS, chartDocument, chartSize, markLegends} from './charts.mjs';
 
 /** @typedef {{level: string, text: string}} PageLog */
 
-/** @type {{entry: string, root: string, served: {dir: string, integrations: string[]} | null}} */
+/** @type {{entry: string, root: string, served: {dir: string, integrations: string[]} | null, withoutSegmenter?: boolean}} */
 const {entry, root} = workerData;
 
+// Some Node builds crash in Intl.Segmenter. Without it, Core splits text by
+// code points, so a joined emoji can count as several characters.
+if (workerData.withoutSegmenter) delete (/** @type {any} */ (Intl)).Segmenter;
+
 /** The package set, for a page outside a project whose folder has no Core of its own. */
 const served = workerData.served && findNodeModulesPackage(path.dirname(entry), '@astryxdesign/core') === null ? workerData.served : null;
 const ROOT_PREFIX = root.endsWith(path.sep) ? root : root + path.sep;
@@ -136,6 +148,252 @@ const NODE_MODULES = `${path.sep}node_modules${path.sep}`;
 const isLocal = file =>
   !file.includes(NODE_MODULES) && (file === entry || file.startsWith(ROOT_PREFIX));
 
+/** Charts the server render set aside, drawn after it. @type {any[]} */
+const charts = [];
+/** The props each chart was last drawn with in the page-wide draw. @type {any[]} */
+const pageCharts = [];
+/**
+ * Whether a chart rendered again after the page-wide draw first committed. A
+ * chart renders again only when the component that made it renders again:
+ * its effects changed its state, which a closure in the chart may read, so
+ * the props alone cannot say the chart is the same. React's development
+ * double render under StrictMode runs before the commit, so it does not
+ * count.
+ */
+let renderedAfterCommit = false;
+
+/**
+ * A chart's props as a string that two renders of the same chart share:
+ * data by value, functions by name, elements by type and props.
+ * @param {unknown} value
+ * @param {number} [depth]
+ * @returns {string}
+ */
+function sameKey(value, depth = 0) {
+  if (depth > 8) return '…';
+  if (typeof value === 'function') return `fn:${value.name}`;
+  if (typeof value === 'symbol') return String(value);
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'undefined';
+  if (Array.isArray(value)) return `[${value.map(v => sameKey(v, depth + 1)).join(',')}]`;
+  const record = /** @type {Record<string, unknown>} */ (value);
+  if ('$$typeof' in record && 'props' in record) {
+    const type = /** @type {any} */ (record.type);
+    return `<${typeof type === 'string' ? type : (type?.displayName ?? type?.name ?? '?')} ${sameKey(record.props, depth + 1)}>`;
+  }
+  return `{${Object.keys(record)
+    .filter(key => !key.startsWith('_'))
+    .sort()
+    .map(key => `${key}:${sameKey(record[key], depth + 1)}`)
+    .join(',')}}`;
+}
+/** React's createElement, once the page's React has loaded. @type {any} */
+let createElement = null;
+/** React's useContext and useRef. @type {any} */
+let useContext = null;
+/** @type {any} */
+let useRef = null;
+/** @type {any} */
+let useLayoutEffect = null;
+/** Set inside a drawn chart, so a chart inside it is not wrapped again. @type {any} */
+let InChart = null;
+/**
+ * `aside` while the server render sets charts aside; `page` while the whole
+ * page is drawn again, so each chart sees the context it was rendered in;
+ * `alone` while each chart is drawn by itself, when the page cannot be.
+ * @type {'aside' | 'page' | 'alone'}
+ */
+let mode = 'aside';
+
+/**
+ * Wrap a recharts chart, or a ResponsiveContainer, so the server render sets
+ * it aside and the drawing pass draws it: a container at the size it starts
+ * at, in a box that lets the drawing fit the page's width.
+ * @param {any} Chart
+ * @param {boolean} container
+ */
+/** @type {any} */ (globalThis).__astryxRenderChart = (/** @type {any} */ Chart, /** @type {boolean} */ container) => {
+  function RenderedChart(/** @type {any} */ props) {
+    if (mode === 'aside') {
+      charts.push(createElement(RenderedChart, props));
+      return createElement('astryx-chart', {'data-chart': charts.length - 1});
+    }
+    const inside = useContext(InChart);
+    // Each chart drawn in the page notes the props it was last drawn with,
+    // by its place in the page, to compare with the first render's.
+    const place = useRef(/** @type {number | null} */ (null));
+    const committed = useRef(false);
+    useLayoutEffect(() => {
+      committed.current = true;
+    });
+    if (mode === 'page' && !inside) {
+      place.current ??= pageCharts.length;
+      pageCharts[place.current] = props;
+      if (committed.current) renderedAfterCommit = true;
+    }
+    const drawn = container
+      ? createElement('div', {className: 'recharts-responsive-container'}, createElement(Chart, {...props, ...chartSize(props)}))
+      : createElement(Chart, props);
+    if (mode === 'alone' || inside) return drawn;
+    return createElement('astryx-chart', null, createElement(InChart.Provider, {value: true}, drawn));
+  }
+  return RenderedChart;
+};
+
+/**
+ * Point the page's recharts charts, and its ResponsiveContainer, at the
+ * wrapper the worker installs.
+ * @param {any} p the import of 'recharts'
+ * @param {any} t Babel's types
+ */
+function setChartsAside(p, t) {
+  for (const s of p.node.specifiers) {
+    if (s.type !== 'ImportSpecifier') continue;
+    const name = s.imported.name ?? s.imported.value;
+    const container = name === 'ResponsiveContainer';
+    if (!container && !CHART_ROOTS.has(name)) continue;
+    const original = p.scope.generateUidIdentifier(name);
+    const local = s.local.name;
+    s.local = original;
+    p.insertAfter(
+      t.variableDeclaration('const', [
+        t.variableDeclarator(
+          t.identifier(local),
+          t.callExpression(t.memberExpression(t.identifier('globalThis'), t.identifier(CHART_GLOBAL)), [
+            original,
+            t.booleanLiteral(container),
+          ]),
+        ),
+      ]),
+    );
+  }
+}
+
+/**
+ * Draw the charts the server render set aside, and put each drawing where
+ * its placeholder is.
+ *
+ * Draw the whole page first. A chart's own parts then see the React context
+ * the page gives them. If that draw throws, or the page's effects change a
+ * chart (its props, or which charts there are), draw each chart alone, from
+ * the props of the first render. A chart that fails stays empty and is
+ * counted.
+ * @param {string} markup
+ * @param {any} Page
+ * @returns {Promise<{markup: string, failed: number, alone: false | 'error' | 'changed' | 'rerendered'}>}
+ */
+async function drawCharts(markup, Page) {
+  const placeholder = /<astryx-chart data-chart="(\d+)"><\/astryx-chart>/g;
+  /** @type {any} */
+  let client;
+  /** @type {any} */
+  let flushSync;
+  try {
+    await chartDocument();
+    client = await jiti.import('react-dom/client');
+    ({flushSync} = /** @type {any} */ (await jiti.import('react-dom')));
+    // recharts decided it runs on a server when it loaded for the server
+    // render. Now there is a document, so it measures text and lays out
+    // axis labels as in a browser.
+    const recharts = /** @type {any} */ (await jiti.import('recharts'));
+    if (recharts?.Global) recharts.Global.isSsr = false;
+  } catch {
+    // Without a document to draw in, every chart stays empty and is counted.
+    return {markup: markup.replace(placeholder, ''), failed: charts.length, alone: /** @type {false} */ (false)};
+  }
+  /**
+   * Render one element in its own root and hand its host to `read`.
+   * @param {unknown} element
+   * @param {(host: any) => string[]} read
+   * @returns {string[] | null} null when the render failed
+   */
+  const drawIn = (element, read) => {
+    /** @type {unknown} */
+    let error = null;
+    const host = /** @type {any} */ (globalThis).document.createElement('div');
+    const root = client.createRoot(host, {
+      onUncaughtError: (/** @type {unknown} */ e) => {
+        error = e;
+      },
+      onRecoverableError: () => {},
+    });
+    try {
+      flushSync(() => root.render(element));
+    } catch (e) {
+      error = e;
+    }
+    if (!error) markLegends(host);
+    const out = error ? null : read(host);
+    root.unmount();
+    return out;
+  };
+  mode = 'page';
+  let drawn = drawIn(createElement(Page), host => [...host.querySelectorAll('astryx-chart')].map(el => el.innerHTML));
+  /** @type {false | 'error' | 'changed' | 'rerendered'} */
+  let alone = false;
+  if (!drawn) alone = 'error';
+  // The page's effects changed a chart: its props, which charts there are,
+  // or the state of the component that made it, which a closure or context
+  // in the chart may read.
+  else if (
+    drawn.length !== charts.length ||
+    pageCharts.length !== charts.length ||
+    charts.some((chart, i) => sameKey(chart.props) !== sameKey(pageCharts[i]))
+  ) {
+    alone = 'changed';
+  } else if (renderedAfterCommit) {
+    alone = 'rerendered';
+  }
+  if (alone) {
+    mode = 'alone';
+    drawn = charts.map(chart => drawIn(chart, host => [host.innerHTML])?.[0] ?? '');
+  }
+  let failed = 0;
+  // A chart that drew no picture counts as failed, once.
+  const pictures = /** @type {string[]} */ (drawn).map(html => {
+    if (html.includes('<svg')) return html;
+    failed += 1;
+    return '';
+  });
+  return {
+    markup: markup.replace(placeholder, (_, i) => pictures[Number(i)] ?? ''),
+    failed,
+    alone,
+  };
+}
+
+/**
+ * Babel plugin: a bare import that a path alias places loads from that file,
+ * as in TypeScript, before any installed copy. An import the aliases do not
+ * place is left alone, so an installed package loads. It runs on the page's
+ * own files, before {@link pagePlugin}, and on every module the page loads
+ * from outside them and outside `node_modules` (a sibling package's source,
+ * say).
+ */
+function aliasPlugin() {
+  return () => {
+    /** @param {any} node a string literal to point at the file an alias places */
+    const point = node => {
+      if (node?.type !== 'StringLiteral') return;
+      const file = resolvePath(PATHS, node.value);
+      if (file) node.value = file;
+    };
+    return {
+      visitor: {
+        'ImportDeclaration|ExportNamedDeclaration|ExportAllDeclaration'(/** @type {any} */ p) {
+          point(p.node.source);
+        },
+        CallExpression(/** @type {any} */ p) {
+          const callee = p.node.callee;
+          if (callee?.type === 'Import' || (callee?.type === 'Identifier' && callee.name === 'require')) point(p.node.arguments?.[0]);
+        },
+        ImportExpression(/** @type {any} */ p) {
+          point(p.node.source);
+        },
+      },
+    };
+  };
+}
+
 /**
  * Babel plugin: replace asset imports with data: URIs and stylesheet imports
  * with nothing (their CSS is inlined into the page), and record static text
@@ -148,6 +406,7 @@ function pagePlugin(filename) {
     visitor: {
       ImportDeclaration(/** @type {any} */ p) {
         const spec = /** @type {string} */ (p.node.source.value);
+        if (spec === 'recharts') setChartsAside(p, t);
         const raw = spec.split('?')[0];
         // A stylesheet, image or JSON file imported through a project alias
         // (`@/styles/site.css`) resolves the way modules do.
@@ -179,6 +438,23 @@ function pagePlugin(filename) {
           p.remove();
           return;
         }
+        if (/\.css$/i.test(bare) && bare === raw && namesAlias(raw)) {
+          // An aliased stylesheet with no target falls back to a package, as in
+          // TypeScript; when there is none either, the alias is wrong.
+          let found = true;
+          try {
+            createRequire(filename).resolve(raw);
+          } catch {
+            found = false;
+          }
+          if (!found) {
+            const err = new Error(
+              `${path.basename(filename)} imports ${spec} through a path alias that does not lead to a file.`,
+            );
+            /** @type {any} */ (err).renderCode = 'ERR_FILE_NOT_FOUND';
+            throw err;
+          }
+        }
         if (/\.css$/i.test(bare)) {
           if (bare.startsWith('.') || path.isAbsolute(bare)) {
             const file = path.resolve(dir, bare);
@@ -303,61 +579,34 @@ function pagePlugin(filename) {
 }
 
 /**
- * Path aliases from the project's tsconfig.json or jsconfig.json
- * (`compilerOptions.paths`), as jiti aliases: `"@/*": ["./src/*"]` becomes
- * `{"@/": "<root>/src/"}`.
- * @returns {Record<string, string>}
+ * The project's path aliases (`compilerOptions.paths` in tsconfig.json or
+ * jsconfig.json), matched by TypeScript's rules (see ts-paths.mjs).
  */
-function projectAliases() {
-  /** @type {Record<string, string>} */
-  const alias = {};
-  for (const name of ['tsconfig.json', 'jsconfig.json']) {
-    const file = path.join(root, name);
-    if (!fs.existsSync(file)) continue;
-    /** @type {any} */
-    let config;
-    try {
-      // Allow the comments and trailing commas these files often carry.
-      const text = fs
-        .readFileSync(file, 'utf8')
-        .replace(/("(?:[^"\\]|\\.)*")|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (_, str) => str ?? '')
-        .replace(/,(\s*[}\]])/g, '$1');
-      config = JSON.parse(text);
-    } catch {
-      continue;
-    }
-    const options = config?.compilerOptions ?? {};
-    const baseDir = path.resolve(root, typeof options.baseUrl === 'string' ? options.baseUrl : '.');
-    for (const [key, targets] of Object.entries(options.paths ?? {})) {
-      const target = Array.isArray(targets) ? targets[0] : undefined;
-      if (typeof target !== 'string') continue;
-      if (key.endsWith('/*') && target.endsWith('/*')) {
-        alias[key.slice(0, -1)] = `${path.resolve(baseDir, target.slice(0, -2))}/`;
-      } else if (!key.includes('*') && !target.includes('*')) {
-        alias[key] = path.resolve(baseDir, target);
-      }
-    }
-    break;
-  }
-  return alias;
-}
-
-const ALIASES = projectAliases();
+const PATHS = readPathsIn(root) ?? [];
 
 /** @param {string} spec whether a specifier goes through a project alias */
-const isAliased = spec =>
-  Object.keys(ALIASES).some(key => (key.endsWith('/') ? spec.startsWith(key) : spec === key));
-
-/** @param {string} spec a specifier through a project alias, as an absolute path */
-const resolveAlias = spec => {
-  for (const [key, target] of Object.entries(ALIASES)) {
-    if (key.endsWith('/') ? spec.startsWith(key) : spec === key) {
-      return key.endsWith('/') ? target + spec.slice(key.length) : target;
-    }
-  }
-  return spec;
+const isAliased = spec => resolvePath(PATHS, spec) !== null;
+
+/**
+ * Whether a specifier that resolves to no file was meant for an alias: it
+ * matches a key with a literal prefix. A catch-all key (`"*"`) matches every
+ * package name too, so an import it cannot place is a package that is not
+ * installed.
+ * @param {string} spec
+ */
+const namesAlias = spec => {
+  const match = matchPath(PATHS, spec);
+  return match !== null && match.pattern.prefix !== '';
 };
 
+/**
+ * A specifier through a project alias, as the absolute path of the first
+ * target that exists; the specifier itself when none does, so it resolves as
+ * a package.
+ * @param {string} spec
+ */
+const resolveAlias = spec => resolvePath(PATHS, spec) ?? spec;
+
 /** Packages the page took from the package set, by name: their folders. */
 /** @type {Map<string, string>} */
 const fromSet = new Map();
@@ -381,6 +630,7 @@ function packageDirOf(file, name) {
 
 const moduleApi = /** @type {any} */ (Module);
 
+
 /** A module at the served Core's folder: what resolves as the Core would. */
 const servedParent = served ? new moduleApi(path.join(served.dir, 'package.json')) : null;
 if (servedParent && served) {
@@ -456,7 +706,7 @@ const jiti = createJiti(entry, {
   extensions: ['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '.mts', '.cts', '.json'],
   moduleCache: true,
   interopDefault: true,
-  alias: {...SINGLE_COPY_ALIASES, ...ALIASES},
+  alias: SINGLE_COPY_ALIASES,
   jsx: {runtime: 'automatic'},
   transform(opts) {
     const filename = opts.filename ?? '';
@@ -476,6 +726,7 @@ const jiti = createJiti(entry, {
         generatorOpts: {retainLines: true},
         compact: false,
         plugins: [
+          aliasPlugin(),
           pagePlugin(filename),
           ...(source.includes('stylex')
             ? [
@@ -495,6 +746,31 @@ const jiti = createJiti(entry, {
       const rules = /** @type {any} */ (result?.metadata)?.stylex;
       if (Array.isArray(rules)) stylexRules.push(...rules);
       source = result?.code ?? source;
+    } else if (
+      PATHS.length > 0 &&
+      filename &&
+      !filename.includes(NODE_MODULES) &&
+      /\.(tsx?|jsx?|mjs|cjs|mts|cts)$/.test(filename)
+    ) {
+      const ts = /\.(tsx?|mts|cts)$/.test(filename);
+      const result = transformSync(source, {
+        filename,
+        babelrc: false,
+        configFile: false,
+        sourceType: 'unambiguous',
+        // The options jiti compiles these files with: JSX only in .jsx and
+        // .tsx files (so `<string>value` stays a type assertion), and legacy
+        // decorators.
+        parserOpts: {
+          plugins: /** @type {import('@babel/core').ParserOptions['plugins']} */ (
+            ts ? [...(/\.[cm]?tsx$/.test(filename) ? ['jsx'] : []), 'typescript', 'decorators-legacy'] : ['jsx']
+          ),
+        },
+        generatorOpts: {retainLines: true},
+        compact: false,
+        plugins: [aliasPlugin()],
+      });
+      source = result?.code ?? source;
     }
     return {code: plain.transform({...opts, source, babel: {...opts.babel, compact: false}})};
   },
@@ -524,7 +800,7 @@ function classify(e) {
   const missing =
     /Cannot find (?:module|package) ['"]([^'"]+)['"]/.exec(message) ??
     /Failed to resolve import ['"]([^'"]+)['"]/.exec(message);
-  if (missing && (isAliased(missing[1]) || /^[@~#]\/|^#/.test(missing[1]))) {
+  if (missing && (namesAlias(missing[1]) || /^[@~#]\/|^#/.test(missing[1]))) {
     return fail(
       'ERR_FILE_NOT_FOUND',
       `The page imports ${missing[1]} through a path alias that does not lead to a file. Check \`compilerOptions.paths\` in the project's tsconfig.json, or import it by a relative path.`,
@@ -582,6 +858,11 @@ try {
   let server;
   try {
     React = await jiti.import('react');
+    createElement = React.createElement;
+    useContext = React.useContext;
+    useRef = React.useRef;
+    useLayoutEffect = React.useLayoutEffect;
+    InChart = React.createContext(false);
     server = await jiti.import('react-dom/server');
   } catch (e) {
     classify(e);
@@ -589,8 +870,18 @@ try {
   }
   /** @type {string} */
   let markup;
+  let chartsFailed = 0;
+  /** @type {false | 'error' | 'changed' | 'rerendered'} */
+  let chartsAlone = false;
   try {
     markup = server.renderToStaticMarkup(React.createElement(Page));
+    if (charts.length > 0) {
+      // Drawing the page again re-runs its code: what it prints then was
+      // already reported by the server render.
+      const printed = logs.length;
+      ({markup, failed: chartsFailed, alone: chartsAlone} = await drawCharts(markup, Page));
+      logs.length = printed;
+    }
   } catch (e) {
     classify(e);
     throw null;
@@ -613,6 +904,8 @@ try {
     packageCss,
     skippedCss,
     fromSet: [...fromSet].map(([name, dir]) => ({name, dir})),
+    chartsFailed,
+    chartsAlone,
     assets: [...assetsInlined],
     files: localFiles,
     texts,

package/foundation/render/render-page.d.mts

@@ -1,6 +1,11 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * The warning for a page rendered without Intl.Segmenter.
+ * @returns {RenderWarning}
+ */
+export function segmenterWarning(): RenderWarning;
 /**
  * Render a page module to one self-contained HTML file.
  * @param {string} entry absolute path of the page module
@@ -20,7 +25,7 @@ export const RENDER_TIMEOUT_MS: 60000;
 export { PAGE_EXTENSIONS } from "./embedded-files.mjs";
 /**
  * @typedef {object} RenderWarning
- * @property {'dropped-children' | 'remote-asset' | 'missing-asset' | 'page-output' | 'page-script' | 'no-astryx-styles' | 'chart-size' | 'not-embedded'} code - What kind of problem.
+ * @property {'dropped-children' | 'remote-asset' | 'missing-asset' | 'page-output' | 'page-script' | 'no-astryx-styles' | 'chart-size' | 'not-embedded' | 'node-crash'} code - What kind of problem.
  * @property {string} message - What happened and what to do, in one sentence.
  */
 /**
@@ -46,15 +51,11 @@ export class RenderError extends Error {
     code: string;
     detail: Record<string, unknown> | undefined;
 }
-export type ServedSet = {
-    dir: string;
-    integrations: readonly string[];
-};
 export type RenderWarning = {
     /**
      * - What kind of problem.
      */
-    code: "dropped-children" | "remote-asset" | "missing-asset" | "page-output" | "page-script" | "no-astryx-styles" | "chart-size" | "not-embedded";
+    code: "dropped-children" | "remote-asset" | "missing-asset" | "page-output" | "page-script" | "no-astryx-styles" | "chart-size" | "not-embedded" | "node-crash";
     /**
      * - What happened and what to do, in one sentence.
      */
@@ -98,3 +99,7 @@ export type RenderedPage = {
         dir: string;
     }[];
 };
+export type ServedSet = {
+    dir: string;
+    integrations: readonly string[];
+};