forgebook 0.3.2 → 0.4.0

package/dist/src/vite/jsxCallSites.js

@@ -0,0 +1,200 @@
+/**
+ * Where an application draws a JSX component, read from its program with the TypeScript checker (no code runs): each
+ * element whose tag is the component, with the props it gives a literal value. `forgebook new` takes its values from
+ * them, so a first story shows the component as the application uses it rather than with a prop's name for its text.
+ *
+ * @remarks
+ * Shared by the frameworks whose components are functions of their props (React, Preact, Solid). The program is the
+ * component's configuration's, read whole. Story files, tests and declaration files are left out: they are not the
+ * application. A value is kept only when it is a literal (a string, a number, `true`, `false`, `null`, a list or an
+ * object of them); one that depends on the caller's state would not mean anything in a story. A child that is plain text
+ * is `children`.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+import { programFor } from "./docsProgram.js";
+import { VITE_PATHS } from "./vitePaths.js";
+/** A file that is not the application: a story, a test, a declaration. */
+const NOT_APPLICATION = /\.(?:stories|story|test|spec)\.[cm]?[jt]sx?$|\.d\.[cm]?ts$|[\\/]node_modules[\\/]/;
+/** How deep a list or an object is followed: past it, a value is not kept. */
+const MAX_DEPTH = 4;
+/**
+ * An expression as code a story can hold, when it is a literal: shared with the frameworks that read their templates'
+ * bindings as expressions (Vue's `:size="3"`).
+ *
+ * @param node - the expression.
+ * @param depth - how deep in a list or an object it is.
+ * @returns the code; none when it is not a literal.
+ */
+export const literalExpressionCode = (node, depth = 0) => {
+    if (depth > MAX_DEPTH)
+        return undefined;
+    if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node))
+        return literalExpressionCode(node.expression, depth);
+    if (ts.isArrayLiteralExpression(node))
+        return listCode(node, depth);
+    if (ts.isObjectLiteralExpression(node))
+        return objectCode(node, depth);
+    return scalarCode(node);
+};
+/** A string, a number (a negative one too), `true`, `false` or `null` as code; none for anything else. */
+const scalarCode = (node) => {
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+        return JSON.stringify(node.text);
+    if (ts.isNumericLiteral(node))
+        return node.text;
+    const isNegative = ts.isPrefixUnaryExpression(node) &&
+        node.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(node.operand);
+    if (isNegative)
+        return `-${node.operand.text}`;
+    return KEYWORD_CODE.get(node.kind);
+};
+/** The keywords that are literals, as code. */
+const KEYWORD_CODE = new Map([
+    [ts.SyntaxKind.TrueKeyword, "true"],
+    [ts.SyntaxKind.FalseKeyword, "false"],
+    [ts.SyntaxKind.NullKeyword, "null"]
+]);
+/** A list of literals as code. */
+const listCode = (node, depth) => {
+    const items = node.elements.map((item) => ts.isSpreadElement(item) ? undefined : literalExpressionCode(item, depth + 1));
+    return items.some((item) => item === undefined) ? undefined : `[${items.join(", ")}]`;
+};
+/** A property's name as code: a name as it is, a string quoted; none for a computed one. */
+const keyCode = (name) => {
+    if (ts.isIdentifier(name))
+        return name.text;
+    if (ts.isStringLiteral(name))
+        return JSON.stringify(name.text);
+    return undefined;
+};
+/** An object of literals as code. */
+const objectCode = (node, depth) => {
+    const pairs = [];
+    for (const property of node.properties) {
+        if (!ts.isPropertyAssignment(property))
+            return undefined;
+        const key = keyCode(property.name);
+        const value = literalExpressionCode(property.initializer, depth + 1);
+        if (key === undefined || value === undefined)
+            return undefined;
+        pairs.push(`${key}: ${value}`);
+    }
+    return `{ ${pairs.join(", ")} }`;
+};
+/** The character references JSX text and attributes most often hold, as the characters they stand for. */
+const ENTITIES = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    nbsp: "\u00a0"
+};
+/** JSX text with its common character references read (`a &amp; b` is `a & b`), as React reads them. */
+const decoded = (text) => text.replace(/&(amp|lt|gt|quot|apos|nbsp);/g, (_, name) => ENTITIES[name] ?? "");
+/** An attribute's value as code: a bare attribute is `true`, a string as written, an expression when a literal. */
+const initializerCode = (initializer) => {
+    if (initializer === undefined)
+        return "true";
+    if (ts.isStringLiteral(initializer))
+        return JSON.stringify(decoded(initializer.text));
+    if (ts.isJsxExpression(initializer) && initializer.expression !== undefined)
+        return literalExpressionCode(initializer.expression);
+    return undefined;
+};
+/** The props an element gives a literal value, and its text child as `children`. */
+const argsOf = (element) => {
+    const opening = ts.isJsxElement(element) ? element.openingElement : element;
+    const args = {};
+    for (const attribute of opening.attributes.properties) {
+        if (!ts.isJsxAttribute(attribute) || !ts.isIdentifier(attribute.name))
+            continue;
+        const name = attribute.name.text;
+        if (name === "key" || name === "ref")
+            continue;
+        const { initializer } = attribute;
+        const code = initializerCode(initializer);
+        if (code !== undefined)
+            args[name] = code;
+    }
+    const texts = ts.isJsxElement(element) ? element.children.filter(ts.isJsxText) : [];
+    if (ts.isJsxElement(element) && texts.length > 0 && texts.length === element.children.length) {
+        const text = texts
+            .map((child) => decoded(child.text))
+            .join("")
+            .replace(/\s+/g, " ")
+            .trim();
+        if (text !== "")
+            args["children"] = JSON.stringify(text);
+    }
+    return args;
+};
+/**
+ * The symbol a name stands for, through its imports and re-exports.
+ *
+ * @param symbol - the symbol at the name.
+ * @param checker - the checker.
+ */
+const declared = (symbol, checker) => symbol !== undefined && (symbol.flags & ts.SymbolFlags.Alias) !== 0
+    ? checker.getAliasedSymbol(symbol)
+    : symbol;
+/** The component's export, by its name or by its declaration's (`const TagImpl = …; export { TagImpl as Tag }`). */
+const exportedSymbol = (source, name, checker) => {
+    const moduleSymbol = checker.getSymbolAtLocation(source);
+    const exports = moduleSymbol === undefined ? [] : checker.getExportsOfModule(moduleSymbol);
+    const exported = exports.find((each) => each.getName() === name) ??
+        exports.find((each) => declared(each, checker)?.getName() === name);
+    const target = declared(exported, checker);
+    return exported === undefined || target === undefined ? undefined : { exported, target };
+};
+/** The names a file that draws the component must hold: its export's, its declaration's, its file's. */
+const searchedNames = (file, exported, target) => {
+    const stem = (VITE_PATHS.normalize(file).split("/").pop() ?? "").replace(/\.[^.]+$/, "");
+    return [exported.getName(), target.getName(), stem].filter((each) => each !== "default" && each !== "index");
+};
+/** The elements of a file whose tag is the component, with their literal props. */
+const sitesIn = (file, target, checker) => {
+    const sites = [];
+    const visit = (node) => {
+        if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+            const tag = ts.isJsxElement(node) ? node.openingElement.tagName : node.tagName;
+            if (declared(checker.getSymbolAtLocation(tag), checker) === target)
+                sites.push({ file: file.fileName, args: argsOf(node) });
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(file);
+    return sites;
+};
+/**
+ * Where the application draws a component a file exports.
+ *
+ * @param file - the component's file, absolute.
+ * @param name - the export's name (`default` for a default export).
+ * @returns the call sites; a message when the file or the export cannot be read.
+ */
+export const jsxCallSites = (file, name) => {
+    const program = programFor(file, { reach: "whole" });
+    if (typeof program === "string")
+        return program;
+    const { checker } = program;
+    const source = program.program.getSourceFile(file);
+    if (source === undefined)
+        return `${file} is not in its program`;
+    const found = exportedSymbol(source, name, checker);
+    if (found === undefined)
+        return `${file} exports no ${name}`;
+    // a file that names neither the component nor its file cannot draw it: the checker is not asked about its tags
+    const names = searchedNames(file, found.exported, found.target);
+    const component = VITE_PATHS.normalize(file);
+    return program.program
+        .getSourceFiles()
+        .filter((each) => !NOT_APPLICATION.test(each.fileName) &&
+        !program.program.isSourceFileFromExternalLibrary(each) &&
+        VITE_PATHS.normalize(each.fileName) !== component &&
+        (names.length === 0 || names.some((searched) => each.text.includes(searched))))
+        .flatMap((each) => sitesIn(each, found.target, checker));
+};

package/dist/src/vite/jsxInScripts.d.ts

@@ -0,0 +1,67 @@
+import { type ResolvedConfig, type Rollup } from "vite";
+import type { FrameworkAdapter } from "./adapter.ts";
+import { type VitePaths } from "./vitePaths.ts";
+/** A `.js` file compiled: its JavaScript and the source map back to its JSX. */
+export type CompiledScript = {
+    /** The JavaScript. */
+    readonly code: string;
+    /** Its source map, back to the file's own text. */
+    readonly map: Rollup.SourceMapInput;
+};
+/**
+ * The folder of the package a file belongs to: the nearest folder with a `package.json`; none outside any.
+ *
+ * @param file - the file, absolute in Vite's form.
+ */
+export type PackageOf = (file: string) => string | undefined;
+/** Finds a file's package on disk, each folder looked at once. */
+export declare const packageFinder: () => PackageOf;
+/**
+ * The file of one of the catalogue's own `.js` files asked for as a module, from its id; none for any other id: an
+ * installed package's, another package's, one outside the catalogue's folder, a virtual module's, or one whose query
+ * asks for something else than the module (`?raw`).
+ *
+ * @param id - the module's id, with any query Vite gave it.
+ * @param root - the catalogue's folder, in Vite's form.
+ * @param packageOf - finds a file's package.
+ * @param paths - the path functions, the running system's by default.
+ */
+export declare const ownScriptOf: (id: string, root: string, packageOf: PackageOf, paths?: Pick<VitePaths, "normalize">) => string | undefined;
+/**
+ * Whether a file's text may hold JSX: it has a closing tag.
+ *
+ * @param code - the text.
+ */
+export declare const mayHoldJsx: (code: string) => boolean;
+/**
+ * Compiles a `.js` file's JSX, with the code the project's `jsxInject` puts first (a classic runtime's `React` import),
+ * as Vite does for its `.jsx` files; leaves a file with no closing tag, and any file of a project that turns `oxc` off,
+ * to Vite.
+ *
+ * @param config - Vite's resolved configuration, for the project's JSX options.
+ * @param code - the file's text.
+ * @param file - the file, absolute.
+ * @returns the compiled module, or none when it is not compiled.
+ */
+export declare const jsxInScript: (config: ResolvedConfig, code: string, file: string) => Promise<CompiledScript | null>;
+/** The plugin's hooks for JSX in the project's `.js` files. */
+export type JsxInScripts = {
+    /** Keeps Vite's resolved configuration, for the project's JSX options and folder. */
+    readonly remember: (config: ResolvedConfig) => void;
+    /**
+     * Loads one of the catalogue's own `.js` files that holds JSX, compiled; none for any other module, and for all
+     * before `remember`, which Vite then loads itself.
+     */
+    readonly load: (id: string) => Promise<CompiledScript | null>;
+};
+/**
+ * The plugin's hooks for JSX in the project's `.js` files.
+ *
+ * @remarks
+ * The file is compiled as it is loaded, not in a `transform` hook, so the plugin's other transforms (a story file's
+ * hot code, `hotSnippets.ts`) read JavaScript and stay the plugin's one `transform`.
+ *
+ * @param frameworkOf - the catalogue's framework, whose adapter asks for it (`compilesJsxInScripts`); read on each module
+ * since the catalogue's configuration is read once Vite starts.
+ */
+export declare const jsxInScripts: (frameworkOf: () => Pick<FrameworkAdapter, "compilesJsxInScripts"> | undefined) => JsxInScripts;

package/dist/src/vite/jsxInScripts.js

@@ -0,0 +1,138 @@
+/**
+ * JSX in a project's `.js` files, compiled as Vite compiles it in `.jsx` ones, so a library that writes its components
+ * and stories in JavaScript with JSX (as Storybook's webpack builder lets it) draws with no configuration.
+ *
+ * @remarks
+ * Vite compiles JSX only in `.jsx` and `.tsx` files, and its `oxc` option takes one language for every file it
+ * includes, so a configuration cannot add `.js` without breaking TypeScript. Forgebook's plugin compiles such a file
+ * itself as it loads it, with the project's own JSX options (`oxc.jsx`: the runtime and the import
+ * source, `jsxInject`), before Vite's plugins read it. Only the catalogue's own files that hold a closing tag (`</`
+ * or `/>`) are compiled: every JSX element has one, and a plain `.js` file costs one search of its text. Its own: in
+ * its folder and in its package, so an installed package, or another package of a workspace (whose built files keep
+ * their own source maps), is never touched. A module asked for with a query that wants something else of the file
+ * (`?raw`, `?url`, `?worker`) is left to Vite. JSX is a superset of what a `.js` module may hold, so a file the search
+ * takes wrongly compiles to the same program. A
+ * project that turns `oxc` off compiles its scripts its own way, and none is compiled here; neither is any for a
+ * framework whose adapter does not ask for it (`compilesJsxInScripts`). Vite's dependency scan
+ * reads `.js` files as JSX too (`prebundled.ts`).
+ *
+ * @module
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { transformWithOxc } from "vite";
+import { VITE_PATHS } from "./vitePaths.js";
+/** A script whose extension says nothing about JSX, as a browser loads it. */
+const PLAIN_SCRIPT = /\.m?js$/;
+/** A file of an installed package. */
+const INSTALLED = /[\\/]node_modules[\\/]/;
+/** What every JSX element holds: a closing tag, or the end of one that closes itself. */
+const TAG_END = /<\/|\/>/;
+/** The queries that still ask for the module itself: Vite's version stamp, its edit stamp, an import's mark. */
+const MODULE_QUERIES = new Set(["v", "t", "import"]);
+/** Finds a file's package on disk, each folder looked at once. */
+export const packageFinder = () => {
+    const known = new Map();
+    const packageOf = (folder) => {
+        if (known.has(folder))
+            return known.get(folder);
+        const parent = VITE_PATHS.dirname(folder);
+        let found;
+        if (existsSync(`${folder}/package.json`))
+            found = folder;
+        // the system's root has no parent
+        else if (parent !== folder)
+            found = packageOf(parent);
+        known.set(folder, found);
+        return found;
+    };
+    return (file) => packageOf(VITE_PATHS.dirname(file));
+};
+/**
+ * The file of one of the catalogue's own `.js` files asked for as a module, from its id; none for any other id: an
+ * installed package's, another package's, one outside the catalogue's folder, a virtual module's, or one whose query
+ * asks for something else than the module (`?raw`).
+ *
+ * @param id - the module's id, with any query Vite gave it.
+ * @param root - the catalogue's folder, in Vite's form.
+ * @param packageOf - finds a file's package.
+ * @param paths - the path functions, the running system's by default.
+ */
+export const ownScriptOf = (id, root, packageOf, paths = VITE_PATHS) => {
+    if (id.startsWith("\0"))
+        return undefined;
+    const [path = id, query = ""] = id.split("?");
+    if ([...new URLSearchParams(query).keys()].some((key) => !MODULE_QUERIES.has(key)))
+        return undefined;
+    const file = paths.normalize(path);
+    if (!PLAIN_SCRIPT.test(file) || INSTALLED.test(file) || !file.startsWith(`${root}/`))
+        return undefined;
+    return packageOf(file) === packageOf(`${root}/package.json`) ? file : undefined;
+};
+/**
+ * Whether a file's text may hold JSX: it has a closing tag.
+ *
+ * @param code - the text.
+ */
+export const mayHoldJsx = (code) => TAG_END.test(code);
+/**
+ * The compiler's options for a `.js` file read as JSX: the project's own, without what only chooses Vite's files, and
+ * without React's Fast Refresh, which Vite's own plugin adds to the compiled module as it does to any `.js` file the
+ * project's refresh options include. Added here too, every component would be registered twice.
+ *
+ * @param oxc - the project's resolved `oxc` options.
+ */
+const jsxOptions = (oxc) => {
+    const { include, exclude, jsxInject, jsxRefreshInclude, jsxRefreshExclude, ...rest } = oxc;
+    const jsx = typeof rest.jsx === "object" ? { ...rest.jsx, refresh: false } : rest.jsx;
+    return { ...rest, ...(jsx === undefined ? {} : { jsx }), lang: "jsx", sourcemap: true };
+};
+/**
+ * Compiles a `.js` file's JSX, with the code the project's `jsxInject` puts first (a classic runtime's `React` import),
+ * as Vite does for its `.jsx` files; leaves a file with no closing tag, and any file of a project that turns `oxc` off,
+ * to Vite.
+ *
+ * @param config - Vite's resolved configuration, for the project's JSX options.
+ * @param code - the file's text.
+ * @param file - the file, absolute.
+ * @returns the compiled module, or none when it is not compiled.
+ */
+export const jsxInScript = async (config, code, file) => {
+    if (config.oxc === false || !mayHoldJsx(code))
+        return null;
+    const result = await transformWithOxc(code, file, jsxOptions(config.oxc), undefined, config);
+    const inject = config.oxc.jsxInject;
+    // on the compiled code's first line, so the source map's lines stay where they were
+    return { code: inject === undefined ? result.code : `${inject};${result.code}`, map: result.map ?? null };
+};
+/**
+ * The plugin's hooks for JSX in the project's `.js` files.
+ *
+ * @remarks
+ * The file is compiled as it is loaded, not in a `transform` hook, so the plugin's other transforms (a story file's
+ * hot code, `hotSnippets.ts`) read JavaScript and stay the plugin's one `transform`.
+ *
+ * @param frameworkOf - the catalogue's framework, whose adapter asks for it (`compilesJsxInScripts`); read on each module
+ * since the catalogue's configuration is read once Vite starts.
+ */
+export const jsxInScripts = (frameworkOf) => {
+    let viteConfig;
+    const packageOf = packageFinder();
+    return {
+        remember: (config) => {
+            viteConfig = config;
+        },
+        load: async (id) => {
+            if (viteConfig === undefined || viteConfig.oxc === false)
+                return null;
+            if (frameworkOf()?.compilesJsxInScripts !== true)
+                return null;
+            const file = ownScriptOf(id, VITE_PATHS.normalize(viteConfig.root), packageOf);
+            if (file === undefined)
+                return null;
+            // a file that cannot be read is Vite's to report
+            const code = await readFile(file, "utf8").catch(() => undefined);
+            return code === undefined ? null : jsxInScript(viteConfig, code, file);
+        }
+    };
+};

package/dist/src/vite/jsxTree.d.ts

@@ -0,0 +1,20 @@
+/** A JSX element, as this walks it. */
+export type Element = {
+    /** Its name. */
+    readonly name: string;
+    /** Its line. */
+    readonly line: number;
+    /** The elements directly inside it, through fragments. */
+    readonly children: readonly Element[];
+    /** Whether nothing of it shows, or what it is cannot be told: no system's component stands in for that. */
+    readonly isOutOfSight: boolean;
+    /** Whether it is one branch of a condition, so what stands in the other is no sibling of it. */
+    readonly isAlternative: boolean;
+};
+/**
+ * The roots of a file: each outermost piece of markup, whose elements stand together with nothing known above them.
+ *
+ * @param node - the file's tree.
+ * @param starts - where its lines start.
+ */
+export declare const rootsOf: (node: unknown, starts: readonly number[]) => (readonly Element[])[];

package/dist/src/vite/jsxTree.js

@@ -0,0 +1,163 @@
+/**
+ * The JSX of a script as what stands where: which elements are directly inside which, and what is written in a place that
+ * says nothing of where it will be drawn (a prop, a value kept for later).
+ *
+ * @module
+ */
+import { lineAt } from "./sourceText.js";
+/** Elements that stand for what is inside them and say nothing of what a component stands in. */
+const TRANSPARENT = /^(?:React\.)?(?:Fragment|Suspense|StrictMode|Profiler)$|(?:Provider|Consumer|Boundary)$/;
+/** Whether a value is a node of the tree. */
+const isNode = (value) => typeof value === "object" && value !== null && "type" in value && typeof value.type === "string";
+/** A JSX name as text. */
+const nameOf = (node) => {
+    if (!isNode(node))
+        return undefined;
+    if (node.type === "JSXIdentifier" && typeof node["name"] === "string")
+        return node["name"];
+    if (node.type !== "JSXMemberExpression")
+        return undefined;
+    const [object, property] = [nameOf(node["object"]), nameOf(node["property"])];
+    return object === undefined || property === undefined ? undefined : `${object}.${property}`;
+};
+/** A plain attribute's text; none when it is absent, empty when written by code. */
+const attributeText = (attributes, name) => {
+    for (const each of attributes) {
+        if (!isNode(each) || !isNode(each["name"]) || each["name"]["name"] !== name)
+            continue;
+        const value = each["value"];
+        return isNode(value) && typeof value["value"] === "string" ? value["value"] : "";
+    }
+    return undefined;
+};
+/** Whether an element's attributes say nothing of it shows, or hand what it is to code (`{...getInputProps()}`). */
+const isOutOfSight = (attributes) => {
+    const list = Array.isArray(attributes) ? attributes : [];
+    if (list.some((each) => isNode(each) && each.type === "JSXSpreadAttribute"))
+        return true;
+    const type = attributeText(list, "type");
+    if (type === "hidden" || type === "file" || attributeText(list, "hidden") !== undefined)
+        return true;
+    return /(?:^|\s)(?:sr-only|hidden)(?:\s|$)/.test(attributeText(list, "className") ?? "");
+};
+/** Two readings or more as one. */
+const joined = (readings) => ({
+    direct: readings.flatMap((each) => each.direct),
+    detached: readings.flatMap((each) => each.detached)
+});
+/** Every outermost element under a node, standing nowhere known. */
+const anyElements = (node, starts) => {
+    if (Array.isArray(node))
+        return node.flatMap((each) => anyElements(each, starts));
+    if (typeof node !== "object" || node === null)
+        return [];
+    if (isNode(node) && (node.type === "JSXElement" || node.type === "JSXFragment")) {
+        const { direct, detached } = readValue(node, starts);
+        return [...direct, ...detached];
+    }
+    return Object.values(node).flatMap((value) => typeof value === "object" ? anyElements(value, starts) : []);
+};
+/** What stands under a part of the tree. */
+const childrenOfNode = (node) => {
+    if (Array.isArray(node))
+        return node;
+    return typeof node === "object" && node !== null
+        ? Object.values(node).filter((value) => typeof value === "object")
+        : [];
+};
+/** What a function gives back, as elements: its expression, or its own returns. */
+const readReturns = (body, starts) => {
+    if (!isNode(body) || body.type !== "BlockStatement")
+        return readValue(body, starts);
+    const returned = [];
+    const others = [];
+    const visit = (node) => {
+        if (isNode(node) && node.type === "ReturnStatement")
+            returned.push(node["argument"]);
+        else if (isNode(node) && (node.type === "JSXElement" || node.type === "JSXFragment"))
+            others.push(node);
+        else
+            childrenOfNode(node).forEach(visit);
+    };
+    visit(body["body"]);
+    const given = joined(returned.map((each) => readValue(each, starts)));
+    return { direct: given.direct, detached: [...given.detached, ...anyElements(others, starts)] };
+};
+/** A call's elements: `items.map((item) => <Option />)` stands where it is written; another's argument may go anywhere. */
+const readCall = (node, starts) => {
+    const callee = node["callee"];
+    const method = isNode(callee) && isNode(callee["property"]) ? callee["property"]["name"] : undefined;
+    const parts = Array.isArray(node["arguments"]) ? node["arguments"] : [];
+    return method === "map" || method === "flatMap"
+        ? readValue(parts, starts)
+        : { direct: [], detached: anyElements(parts, starts) };
+};
+/** An element and what it holds. What its props hold (`icon={<X />}`, `render={() => …}`) may be drawn anywhere. */
+const readElement = (node, starts) => {
+    const opening = node["openingElement"];
+    const name = isNode(opening) ? nameOf(opening["name"]) : undefined;
+    const inner = readValue(node["children"], starts);
+    const held = isNode(opening) ? anyElements(opening["attributes"], starts) : [];
+    if (name === undefined || !isNode(opening) || TRANSPARENT.test(name)) {
+        return { direct: inner.direct, detached: [...inner.detached, ...held] };
+    }
+    const element = {
+        name,
+        line: lineAt(starts, Number(opening["start"])),
+        children: inner.direct,
+        isOutOfSight: isOutOfSight(opening["attributes"]),
+        isAlternative: false
+    };
+    return { direct: [element], detached: [...inner.detached, ...held] };
+};
+/** The elements an expression comes to, through what JSX writes around them. */
+const readValue = (node, starts) => {
+    if (Array.isArray(node))
+        return joined(node.map((each) => readValue(each, starts)));
+    if (!isNode(node))
+        return { direct: [], detached: [] };
+    switch (node.type) {
+        case "JSXElement":
+            return readElement(node, starts);
+        case "JSXFragment":
+            return readValue(node["children"], starts);
+        case "JSXExpressionContainer":
+        case "ParenthesizedExpression":
+        case "TSAsExpression":
+        case "TSNonNullExpression":
+            return readValue(node["expression"], starts);
+        case "ConditionalExpression": {
+            const branches = joined([readValue(node["consequent"], starts), readValue(node["alternate"], starts)]);
+            return {
+                direct: branches.direct.map((each) => ({ ...each, isAlternative: true })),
+                detached: branches.detached
+            };
+        }
+        case "LogicalExpression":
+            return readValue(node["right"], starts);
+        case "ArrowFunctionExpression":
+        case "FunctionExpression":
+            return readReturns(node["body"], starts);
+        case "CallExpression":
+            return readCall(node, starts);
+        default:
+            return { direct: [], detached: anyElements(node, starts) };
+    }
+};
+/**
+ * The roots of a file: each outermost piece of markup, whose elements stand together with nothing known above them.
+ *
+ * @param node - the file's tree.
+ * @param starts - where its lines start.
+ */
+export const rootsOf = (node, starts) => {
+    if (Array.isArray(node))
+        return node.flatMap((each) => rootsOf(each, starts));
+    if (typeof node !== "object" || node === null)
+        return [];
+    if (isNode(node) && (node.type === "JSXElement" || node.type === "JSXFragment")) {
+        const { direct, detached } = readValue(node, starts);
+        return [direct, ...detached.map((each) => [each])];
+    }
+    return Object.values(node).flatMap((value) => (typeof value === "object" ? rootsOf(value, starts) : []));
+};

package/dist/src/vite/lineAndColumn.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Where an offset of a parser's error falls in a file, as an editor counts, for the messages that name a place.
+ *
+ * @module
+ */
+/**
+ * Where an offset falls in a text, as an editor counts: both from 1.
+ *
+ * @param text - the text.
+ * @param offset - the offset, in UTF-16 code units, as the parser gives it.
+ * @returns `line:column`.
+ */
+export declare const lineAndColumn: (text: string, offset: number) => string;

package/dist/src/vite/lineAndColumn.js

@@ -0,0 +1,18 @@
+/**
+ * Where an offset of a parser's error falls in a file, as an editor counts, for the messages that name a place.
+ *
+ * @module
+ */
+/** What ends a line, for an editor as for JavaScript. */
+const LINE_END = /\r\n|[\n\r\u2028\u2029]/g;
+/**
+ * Where an offset falls in a text, as an editor counts: both from 1.
+ *
+ * @param text - the text.
+ * @param offset - the offset, in UTF-16 code units, as the parser gives it.
+ * @returns `line:column`.
+ */
+export const lineAndColumn = (text, offset) => {
+    const lines = text.slice(0, offset).split(LINE_END);
+    return `${lines.length}:${(lines.at(-1)?.length ?? 0) + 1}`;
+};