@astryxdesign/cli 0.7.12-canary.ccb4a6d → 0.7.12-canary.da3dbdc

package/foundation/render/page-worker.mjs

@@ -12,6 +12,10 @@
  * 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.
  *
+ * 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}
  * @output one message: {ok: true, markup, css, files, texts, logs} or
  *   {ok: false, error: {code, message, detail?}}
@@ -25,10 +29,12 @@ 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 */
 
@@ -136,6 +142,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 +400,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 +432,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 +573,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 +624,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 +700,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 +720,7 @@ const jiti = createJiti(entry, {
         generatorOpts: {retainLines: true},
         compact: false,
         plugins: [
+          aliasPlugin(),
           pagePlugin(filename),
           ...(source.includes('stylex')
             ? [
@@ -495,6 +740,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 +794,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 +852,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 +864,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 +898,8 @@ try {
     packageCss,
     skippedCss,
     fromSet: [...fromSet].map(([name, dir]) => ({name, dir})),
+    chartsFailed,
+    chartsAlone,
     assets: [...assetsInlined],
     files: localFiles,
     texts,

package/foundation/render/render-page.mjs

@@ -25,6 +25,7 @@ import {classesIn, cutCss, layerOrderOf} from './css-cut.mjs';
 import {sourceBlock} from './source-block.mjs';
 import {embeddedPathProblem} from './embedded-files.mjs';
 import {resolveServed} from './served-packages.mjs';
+import {CHART_CSS} from './charts.mjs';
 
 /** How long one page may take to render before it is stopped. */
 export const RENDER_TIMEOUT_MS = 60_000;
@@ -522,15 +523,30 @@ export async function renderPage(entry, options = {}) {
       message: `<${t.component}> on line ${t.line} did not render the text "${t.text.length > 60 ? `${t.text.slice(0, 57)}...` : t.text}" it was given; it takes that text through a prop (often label=), so check its props.`,
     });
   }
-  for (const f of /** @type {string[]} */ (message.files ?? [])) {
-    const src = fs.readFileSync(f, 'utf8');
-    if (/\bResponsiveContainer\b/.test(src)) {
-      warnings.push({
-        code: 'chart-size',
-        message: `${path.basename(f)} sizes a chart with ResponsiveContainer, which has no size until a browser measures it, so the chart is empty here; give the chart a fixed width and height.`,
-      });
-      break;
-    }
+  // A chart the render did not draw is an empty box: a ResponsiveContainer
+  // holds only its sizing box, and a chart of fixed size an empty wrapper.
+  const blankCharts =
+    (markup.match(/<div class="recharts-responsive-container[" ][^>]*><div[^>]*><\/div><\/div>/g) ?? []).length +
+    (markup.match(/<div\b[^>]*\bclass="recharts-wrapper"[^>]*><\/div>/g) ?? []).length +
+    (message.chartsFailed ?? 0);
+  if (blankCharts > 0) {
+    warnings.push({
+      code: 'chart-size',
+      message: `${blankCharts === 1 ? 'A chart' : `${blankCharts} charts`} could not be drawn without a browser, so ${blankCharts === 1 ? 'it is' : 'they are'} empty here: the render draws a chart only when a module of the page (not an installed package) imports the chart, and its ResponsiveContainer, from recharts by name (\`import {LineChart} from 'recharts'\`).`,
+    });
+  }
+  if (message.chartsAlone) {
+    /** @type {Record<string, string>} */
+    const causes = {
+      changed: 'The page changed its charts once its effects ran (their data or props, or which charts it shows)',
+      rerendered: 'A component that makes a chart rendered again once the page\'s effects ran',
+      error: 'The page could not be drawn again without a browser',
+    };
+    const why = causes[message.chartsAlone] ?? causes.error;
+    warnings.push({
+      code: 'chart-size',
+      message: `${why}, so each chart was drawn by itself, as the first render gave it: a custom tick, label or shape in a chart sees React context defaults, not the values the page provides.`,
+    });
   }
   for (const sheet of /** @type {string[]} */ (message.skippedCss ?? [])) {
     warnings.push({
@@ -600,7 +616,7 @@ export async function renderPage(entry, options = {}) {
     '<meta name="color-scheme" content="light dark">' +
     `<meta name="generator" content="Astryx${options.version ? ` ${escapeHtml(options.version)}` : ''}">` +
     `<title>${escapeHtml(title)}</title>` +
-    `<style>${SCHEME_CSS}${css}</style></head><body>${markup}` +
+    `<style>${SCHEME_CSS}${markup.includes('class="recharts-responsive-container"') ? CHART_CSS : ''}${css}</style></head><body>${markup}` +
     `${sourceBlock(path.basename(entry), embedded)}</body></html>\n`;
   return {
     html,

package/foundation/render/ts-paths.d.mts

@@ -0,0 +1,63 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The path patterns of the config in `dir` (tsconfig.json, else
+ * jsconfig.json), or none. Comments and trailing commas are allowed.
+ * @param {string} dir
+ * @returns {PathPattern[] | null} null when neither file is there
+ */
+export function readPathsIn(dir: string): PathPattern[] | null;
+/**
+ * The pattern a specifier matches by TypeScript's rules, and what its `*`
+ * matched: an exact key first, else the wildcard key with the longest prefix.
+ * @param {PathPattern[]} patterns
+ * @param {string} spec
+ * @returns {{pattern: PathPattern, capture: string} | null}
+ */
+export function matchPath(patterns: PathPattern[], spec: string): {
+    pattern: PathPattern;
+    capture: string;
+} | null;
+/**
+ * The file a candidate path stands for: itself, with an extension, or its
+ * folder's index; null when none exists.
+ * @param {string} candidate
+ * @returns {string | null}
+ */
+export function existingFile(candidate: string): string | null;
+/**
+ * Resolve a specifier through path patterns: the first target that names an
+ * existing file wins.
+ * @param {PathPattern[]} patterns
+ * @param {string} spec
+ * @returns {string | null} the file, or null when the specifier matches no
+ *   pattern or no target exists
+ */
+export function resolvePath(patterns: PathPattern[], spec: string): string | null;
+export function candidatesOf(match: {
+    pattern: PathPattern;
+    capture: string;
+}): string[];
+export type PathPattern = {
+    /**
+     * - The key as written.
+     */
+    key: string;
+    /**
+     * - What comes before the key's `*` (all of it, for an exact key).
+     */
+    prefix: string;
+    /**
+     * - What comes after the key's `*`.
+     */
+    suffix: string;
+    /**
+     * - Whether the key holds a `*`.
+     */
+    wildcard: boolean;
+    /**
+     * - Absolute target patterns, in order.
+     */
+    targets: string[];
+};