forgebook 0.3.3 → 0.4.1

package/dist/src/vite/shapeDocs.js

@@ -0,0 +1,177 @@
+/**
+ * What a prop's value looks like, read from its type: the fields of an object, a list's items, the members of a mixed
+ * union, so the panel can draw them and a link's value can be checked against them.
+ *
+ * @remarks
+ * What JSON cannot hold (a function, a class's instance, a node) is a `named` part, which only the source's named values
+ * can fill: whether it offers some is known in the page. Types can be recursive and very wide (`CSSProperties`,
+ * `HTMLElement`), and every docs answer carries the shape, so a recursive part, a part too deep and a type too wide are
+ * `json`, typed by hand: the answer stays small, and the prop can still be set.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+/** The deepest a shape goes before the rest is typed as JSON. */
+const MOST_DEPTH = 4;
+/** The most fields of one object drawn as fields: a wider one is read as JSON (`CSSProperties`). */
+const MOST_FIELDS = 40;
+/** The most parts of one prop's shape: past it the prop is read as JSON, so one prop cannot swell every answer. */
+const MOST_PARTS = 200;
+/** Whether a type is a reference to a tuple, for its element types. */
+const isTupleReference = (type, checker) => checker.isTupleType(type);
+/** A part JSON cannot hold, under its type's name. */
+const namedPart = (type, text, walk) => ({
+    kind: "named",
+    type: text ?? walk.checker.typeToString(type),
+    ...(walk.checker.isTypeAssignableTo(walk.checker.getStringType(), type) ? { canTakeText: true } : {})
+});
+/** Whether a member's type takes `null`, which a story's own value may hold. */
+const holdsNull = (type) => type.isUnion() && type.types.some((member) => (member.flags & ts.TypeFlags.Null) !== 0);
+/** The fields of an object type, in the order its members are declared. */
+const fieldsOf = (type, walk, depth) => type.getProperties().map((member) => {
+    const written = walk.checker.getTypeOfSymbolAtLocation(member, walk.node);
+    const memberType = walk.checker.getNonNullableType(written);
+    const description = walk.description(member);
+    return {
+        name: member.getName(),
+        shape: shapeOfType(memberType, walk, depth + 1, walk.typeText(member)),
+        isRequired: (member.flags & ts.SymbolFlags.Optional) === 0,
+        ...(holdsNull(written) ? { isNullable: true } : {}),
+        ...(description === "" ? {} : { description })
+    };
+});
+/** A union's shape: its literals as one choice, `true | false` as one toggle, the rest each its own. */
+const unionShape = (type, walk, depth, text) => {
+    const members = type.types.filter((member) => (member.flags & (ts.TypeFlags.Null | ts.TypeFlags.Undefined)) === 0);
+    const literals = members.flatMap((member) => member.isStringLiteral() || member.isNumberLiteral() ? [member.value] : []);
+    const hasBoolean = members.some((member) => (member.flags & ts.TypeFlags.BooleanLiteral) !== 0);
+    // a node, or anything else with a part JSON cannot hold, is one thing to fill, not a choice among its parts: the first
+    // such part ends the reading, and the parts after it are not read for nothing
+    const others = [];
+    for (const member of members) {
+        if (member.isStringLiteral() ||
+            member.isNumberLiteral() ||
+            (member.flags & ts.TypeFlags.BooleanLiteral) !== 0)
+            continue;
+        const shape = shapeOfType(member, walk, depth + 1, undefined);
+        if (shape.kind === "named")
+            return namedPart(type, text, walk);
+        others.push(shape);
+    }
+    const shapes = [
+        ...(literals.length === 0 ? [] : [{ kind: "choice", values: walk.order(literals) }]),
+        ...(hasBoolean ? [{ kind: "boolean" }] : []),
+        ...others
+    ];
+    const [only] = shapes;
+    return only !== undefined && shapes.length === 1 ? only : { kind: "union", of: shapes };
+};
+/** Whether a type holds any JSON, as far as the source says: a generic's parameter says nothing either. */
+const isAnyJson = (type) => (type.flags &
+    (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.NonPrimitive | ts.TypeFlags.TypeParameter)) !==
+    0;
+/** Whether a type is a text of some form: `string`, a template (`${number}px`), a brand (`string & {}`). */
+const isTextType = (type) => (type.flags & (ts.TypeFlags.String | ts.TypeFlags.TemplateLiteral | ts.TypeFlags.StringMapping)) !== 0 ||
+    (type.isIntersection() && type.types.some(isTextType));
+/** Whether a type is the global `Date`, declared by TypeScript's own library, not one of the source's by that name. */
+const isGlobalDate = (type) => {
+    const symbol = type.getSymbol();
+    const file = symbol?.declarations?.[0]?.getSourceFile().fileName ?? "";
+    return symbol?.getName() === "Date" && /[\\/]lib\.[^\\/]*\.d\.ts$/.test(file);
+};
+/** An object type's shape: its fields, or any names, or JSON when it is too wide or already being read. */
+const objectShape = (type, walk, depth, text) => {
+    const { checker } = walk;
+    // the global `Date`: declared by TypeScript's own library, whatever the source names otherwise
+    if (isGlobalDate(type))
+        return { kind: "date" };
+    // a thing with behaviour is not data (`Date`, `Map`, a class's instance): no value of JSON stands for it
+    const hasBehaviour = type
+        .getProperties()
+        .some((member) => (member.flags & ts.SymbolFlags.Method) !== 0 && (member.flags & ts.SymbolFlags.Optional) === 0);
+    if (type.getCallSignatures().length > 0 || type.getConstructSignatures().length > 0 || type.isClass())
+        return namedPart(type, text, walk);
+    if (walk.open.includes(type) || depth >= MOST_DEPTH)
+        return { kind: "json" };
+    const inner = { ...walk, open: [...walk.open, type] };
+    const element = checker.isArrayType(type) ? type.getNumberIndexType() : undefined;
+    if (element !== undefined) {
+        return {
+            kind: "list",
+            of: shapeOfType(checker.getNonNullableType(element), inner, depth + 1, undefined)
+        };
+    }
+    if (isTupleReference(type, checker)) {
+        const isFixed = type.target.elementFlags.every((flag) => flag === ts.ElementFlags.Required);
+        if (!isFixed)
+            return { kind: "json" };
+        return {
+            kind: "tuple",
+            items: checker
+                .getTypeArguments(type)
+                .map((item) => shapeOfType(checker.getNonNullableType(item), inner, depth + 1, undefined))
+        };
+    }
+    if (hasBehaviour)
+        return namedPart(type, text, walk);
+    const index = type.getStringIndexType();
+    const properties = type.getProperties();
+    if (index !== undefined && properties.length === 0) {
+        return {
+            kind: "record",
+            of: shapeOfType(checker.getNonNullableType(index), inner, depth + 1, undefined)
+        };
+    }
+    if (properties.length === 0 || properties.length > MOST_FIELDS)
+        return { kind: "json" };
+    return { kind: "object", fields: fieldsOf(type, inner, depth) };
+};
+/**
+ * A type's shape.
+ *
+ * @param type - the type, without `undefined` and `null`.
+ * @param walk - what the reading carries.
+ * @param depth - how deep this part is.
+ * @param text - the part's type as the source writes it, when it is known.
+ */
+const shapeOfType = (type, walk, depth, text) => {
+    walk.count.parts += 1;
+    if (walk.count.parts > MOST_PARTS)
+        return { kind: "json" };
+    if (isAnyJson(type))
+        return { kind: "json" };
+    if (isTextType(type))
+        return { kind: "text" };
+    if ((type.flags & ts.TypeFlags.Number) !== 0)
+        return { kind: "number" };
+    if ((type.flags & ts.TypeFlags.Boolean) !== 0)
+        return { kind: "boolean" };
+    // one value of a discriminated union (`{ isOk: true; … }`): a toggle would let a reader write the other branch's
+    if ((type.flags & ts.TypeFlags.BooleanLiteral) !== 0)
+        return { kind: "boolean", only: walk.checker.typeToString(type) === "true" };
+    if (type.isStringLiteral() || type.isNumberLiteral())
+        return { kind: "choice", values: [type.value] };
+    if (type.isUnion())
+        return unionShape(type, walk, depth, text);
+    // an intersection reads as the object it makes (`Base & { extra: string }`)
+    if ((type.flags & ts.TypeFlags.Object) !== 0 || type.isIntersection())
+        return objectShape(type, walk, depth, text);
+    return namedPart(type, text, walk);
+};
+/**
+ * A prop's shape, when it says more than the prop's kind does.
+ *
+ * @param type - the prop's type, without `undefined` and `null`.
+ * @param canTakeText - whether it takes a plain text: its text field stays, rather than JSON for a type that says nothing.
+ * @param reading - what reading a shape needs.
+ * @returns the shape; none for a prop no JSON value can fill, whose named values the page looks up by its type.
+ */
+export const shapeOfProp = (type, canTakeText, reading) => {
+    const count = { parts: 0 };
+    const shape = shapeOfType(type, { ...reading, open: [], count }, 0, undefined);
+    if (shape.kind === "named")
+        return undefined;
+    if (count.parts > MOST_PARTS)
+        return { kind: "json" };
+    return shape.kind === "json" && canTakeText ? undefined : shape;
+};

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

@@ -0,0 +1,17 @@
+/**
+ * The component a `.vue`, `.svelte` or `.astro` file is, read from its text with no framework's compiler.
+ *
+ * @remarks
+ * Every pattern here is bounded or a plain search for a marker: this reads every such file of a repository, any of which
+ * may be crafted to make a pattern take minutes.
+ *
+ * @module
+ */
+import { type ScannedComponent } from "./componentScan.ts";
+/**
+ * The one component of a `.vue`, `.svelte` or `.astro` file, from its text.
+ *
+ * @param file - its path.
+ * @param text - its text.
+ */
+export declare const singleFileComponent: (file: string, text: string) => ScannedComponent;

package/dist/src/vite/singleFileComponent.js

@@ -0,0 +1,83 @@
+/**
+ * The component a `.vue`, `.svelte` or `.astro` file is, read from its text with no framework's compiler.
+ *
+ * @remarks
+ * Every pattern here is bounded or a plain search for a marker: this reads every such file of a repository, any of which
+ * may be crafted to make a pattern take minutes.
+ *
+ * @module
+ */
+import { codeKey, guidanceOfComment, nameOfFile } from "./componentScan.js";
+/**
+ * The comment that documents a single-file component: at the very top, or first thing in its script. A comment further in
+ * is about a prop or a helper.
+ */
+const leadingComment = (text) => {
+    const script = text.indexOf("<script");
+    const opened = script === -1 ? -1 : text.indexOf(">", script);
+    for (const [from, open, close] of [
+        [0, "<!--", "-->"],
+        [opened + 1, "/*", "*/"]
+    ]) {
+        const start = from + (text.slice(from).length - text.slice(from).trimStart().length);
+        if (from >= 0 && text.startsWith(open, start)) {
+            const end = text.indexOf(close, start);
+            if (end !== -1)
+                return text.slice(start + open.length, end);
+        }
+    }
+    return undefined;
+};
+/** A text without what stands between each pair of markers. */
+const without = (text, open, close) => {
+    let out = "";
+    let index = 0;
+    for (let start = text.indexOf(open); start !== -1; start = text.indexOf(open, index)) {
+        const end = text.indexOf(close, start);
+        if (end === -1)
+            break;
+        out += text.slice(index, start);
+        index = end + close.length;
+    }
+    return out + text.slice(index);
+};
+/** The markup of a single-file component: its template's, or what is left without scripts and styles. */
+const markupOf = (text) => {
+    const [open, close] = [text.indexOf("<template"), text.lastIndexOf("</template>")];
+    const opened = open === -1 ? -1 : text.indexOf(">", open);
+    if (opened !== -1 && close > opened)
+        return text.slice(opened + 1, close);
+    const plain = without(without(text, "<script", "</script>"), "<style", "</style>");
+    return plain.startsWith("---") ? plain.slice(plain.indexOf("---", 3) + 3) : plain;
+};
+/**
+ * The one component of a `.vue`, `.svelte` or `.astro` file, from its text.
+ *
+ * @param file - its path.
+ * @param text - its text.
+ */
+export const singleFileComponent = (file, text) => {
+    const markup = markupOf(text);
+    const first = /<([a-zA-Z][\w.-]{0,80})([^<>]{0,2000})>/.exec(markup);
+    const classes = /(?<![:\w-])class="([^"]*)"/.exec(first?.[2] ?? "")?.[1] ?? "";
+    const defined = /defineProps<\{([^}]{0,5000})\}>/.exec(text)?.[1] ?? "";
+    const props = [
+        ...[...defined.matchAll(/(\w+)\??\s*:/g)].flatMap((match) => match[1] ?? []),
+        ...[...text.matchAll(/export let (\w+)/g)].flatMap((match) => match[1] ?? [])
+    ];
+    const renders = [...markup.matchAll(/<([A-Z][\w.]*)/g)].flatMap((match) => match[1] ?? []);
+    const comment = leadingComment(text);
+    return {
+        name: nameOfFile(file),
+        file,
+        line: 1,
+        ...(first?.[1] === undefined ? {} : { root: first[1] }),
+        props,
+        classes: classes.split(/\s+/).filter((each) => each !== ""),
+        renders: [...new Set(renders)],
+        isExported: true,
+        isDefault: true,
+        ...guidanceOfComment(comment),
+        ...codeKey(text, nameOfFile(file))
+    };
+};

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

@@ -0,0 +1,34 @@
+/**
+ * What several readers of source text need: lines by offset, and whether a text is safe to parse.
+ *
+ * @module
+ */
+/**
+ * Where each line of a text starts, to find a line by offset without reading from the start each time.
+ *
+ * @param text - the text.
+ */
+export declare const lineStarts: (text: string) => readonly number[];
+/**
+ * The line of an offset, from 1.
+ *
+ * @param starts - where each line starts.
+ * @param offset - the offset.
+ */
+export declare const lineAt: (starts: readonly number[], offset: number) => number;
+/**
+ * Whether a text nests past what a parser and a walk over its tree can take: a crafted file must cost that file, and past
+ * this depth the parser itself overflows, which no `catch` can answer. Each kind of bracket counts on its own and never
+ * below zero, so closers of another kind or before their openers cancel nothing.
+ *
+ * @param text - a script.
+ */
+export declare const isTooDeep: (text: string) => boolean;
+/**
+ * A file's words as an answer may repeat them: what reaches an agent as data, with what can hide text or redraw a terminal
+ * taken out, and short.
+ *
+ * @param text - the words.
+ * @param longest - how many characters to keep.
+ */
+export declare const plainWords: (text: string, longest: number) => string;

package/dist/src/vite/sourceText.js

@@ -0,0 +1,72 @@
+/**
+ * What several readers of source text need: lines by offset, and whether a text is safe to parse.
+ *
+ * @module
+ */
+/** What opens or closes a level of a script. */
+const NESTING = /<\/|\/>|<[A-Za-z]|[([{)\]}]/g;
+/** What each closer closes. */
+const CLOSES = { ")": "(", "]": "[", "}": "{", "</": "<", "/>": "<" };
+/** How deep a script may nest before it is left out. */
+const MOST_NESTED = 400;
+/**
+ * Where each line of a text starts, to find a line by offset without reading from the start each time.
+ *
+ * @param text - the text.
+ */
+export const lineStarts = (text) => {
+    const starts = [0];
+    for (let at = text.indexOf("\n"); at !== -1; at = text.indexOf("\n", at + 1))
+        starts.push(at + 1);
+    return starts;
+};
+/**
+ * The line of an offset, from 1.
+ *
+ * @param starts - where each line starts.
+ * @param offset - the offset.
+ */
+export const lineAt = (starts, offset) => {
+    let [low, high] = [0, starts.length - 1];
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if ((starts[middle] ?? 0) <= offset)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    return low + 1;
+};
+/** Comments and strings, whose brackets are no nesting. */
+const NOT_CODE = /\/\*[^*]*(?:\*(?!\/)[^*]*)*\*\/|\/\/[^\n]*|"[^"\n]*"|'[^'\n]*'/g;
+/**
+ * Whether a text nests past what a parser and a walk over its tree can take: a crafted file must cost that file, and past
+ * this depth the parser itself overflows, which no `catch` can answer. Each kind of bracket counts on its own and never
+ * below zero, so closers of another kind or before their openers cancel nothing.
+ *
+ * @param text - a script.
+ */
+export const isTooDeep = (text) => {
+    const depths = new Map();
+    for (const match of text.replace(NOT_CODE, " ").matchAll(NESTING)) {
+        const [token = ""] = match;
+        const closes = CLOSES[token];
+        const kind = closes ?? (token.startsWith("<") ? "<" : token);
+        const depth = Math.max(0, (depths.get(kind) ?? 0) + (closes === undefined ? 1 : -1));
+        depths.set(kind, depth);
+        if (depth > MOST_NESTED)
+            return true;
+    }
+    return false;
+};
+/**
+ * A file's words as an answer may repeat them: what reaches an agent as data, with what can hide text or redraw a terminal
+ * taken out, and short.
+ *
+ * @param text - the words.
+ * @param longest - how many characters to keep.
+ */
+export const plainWords = (text, longest) => {
+    const plain = text.replaceAll(/[\p{Cc}\p{Cf}]/gu, " ");
+    return plain.length > longest ? `${plain.slice(0, longest)}…` : plain;
+};

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

@@ -42,6 +42,13 @@ export type SourceTokens = {
  * @param text - the module's text.
  */
 export declare const declaredSource: (file: string, text: string) => DeclaredSource;
+/**
+ * Whether a path, its links followed where it exists, is inside a folder.
+ *
+ * @param root - the folder.
+ * @param path - the path.
+ */
+export declare const isInside: (root: string, path: string) => boolean;
 /**
  * What the source in a module gives, its paths absolute.
  *

package/dist/src/vite/sourceTokens.js

@@ -104,8 +104,13 @@ const packageRoot = (file) => {
     }
     return start;
 };
-/** Whether a path, its links followed where it exists, is inside a folder. */
-const isInside = (root, path) => {
+/**
+ * Whether a path, its links followed where it exists, is inside a folder.
+ *
+ * @param root - the folder.
+ * @param path - the path.
+ */
+export const isInside = (root, path) => {
     const real = (each) => (existsSync(each) ? realpathSync(each) : each);
     const fromRoot = relative(real(root), real(path));
     return fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot);

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

@@ -0,0 +1,49 @@
+/**
+ * A story error's stack with the lines of the files as written: the dev server maps each place the browser names
+ * through the source map of the module it served there.
+ *
+ * @remarks
+ * A browser writes a stack in the lines of the code it ran, which Vite transformed (types taken out, JSX turned into
+ * calls, imports rewritten), so a throw on line 3 of a story file reads as line 19. Devtools map them; the text of
+ * `error.stack` a frame shows does not. The dev server already holds each module's map, so the frame sends the stack
+ * and gets it back mapped: no decoder or map is loaded in the frame. Only places in a module the server served and
+ * whose map points back to that module's own file are rewritten; the rest (a prebundled dependency, the browser's own
+ * code) stay as they were. Used by the plugin for a frame's live error (`liveErrors.ts`).
+ *
+ * @module
+ */
+/** A module the dev server served, as the mapping needs it. */
+export type ServedModule = {
+    /** Its file, as Vite writes ids. */
+    readonly file: string;
+    /** The map from the code served to its file. */
+    readonly map: {
+        readonly version: number;
+        readonly sources: readonly string[];
+        readonly names: readonly string[];
+        readonly mappings: string;
+    };
+};
+/** Finds the module served at an address: none when the server served nothing there, or keeps no map of it. */
+export type ModuleLookup = (url: string) => Promise<ServedModule | undefined>;
+/** A stack with its places mapped. */
+export type MappedStack = {
+    /** The stack, each place it could map in the lines of the file as written. */
+    readonly stack: string;
+    /**
+     * The first mapped place outside `node_modules`, as `file:line:column` with the file relative to the project:
+     * most often the line of the story or component that threw. None when no place could be mapped.
+     */
+    readonly place?: string;
+};
+/** The longest stack mapped, in characters: a frame reports its own errors, yet the connection takes any text. */
+export declare const MAX_STACK_LENGTH = 16000;
+/**
+ * Maps a stack's places to the lines of their files as written.
+ *
+ * @param stack - the stack, as the browser wrote it.
+ * @param lookup - finds the module served at an address.
+ * @param root - the project's folder, which `place` is written relative to.
+ * @returns the stack mapped, and its first place in the project; the stack as it was past `MAX_STACK_LENGTH`.
+ */
+export declare const mappedStack: (stack: string, lookup: ModuleLookup, root: string) => Promise<MappedStack>;

package/dist/src/vite/stackLines.js

@@ -0,0 +1,96 @@
+/**
+ * A story error's stack with the lines of the files as written: the dev server maps each place the browser names
+ * through the source map of the module it served there.
+ *
+ * @remarks
+ * A browser writes a stack in the lines of the code it ran, which Vite transformed (types taken out, JSX turned into
+ * calls, imports rewritten), so a throw on line 3 of a story file reads as line 19. Devtools map them; the text of
+ * `error.stack` a frame shows does not. The dev server already holds each module's map, so the frame sends the stack
+ * and gets it back mapped: no decoder or map is loaded in the frame. Only places in a module the server served and
+ * whose map points back to that module's own file are rewritten; the rest (a prebundled dependency, the browser's own
+ * code) stay as they were. Used by the plugin for a frame's live error (`liveErrors.ts`).
+ *
+ * @module
+ */
+import { SourceMap } from "node:module";
+import { fileURLToPath } from "node:url";
+import { VITE_PATHS } from "./vitePaths.js";
+/** The longest stack mapped, in characters: a frame reports its own errors, yet the connection takes any text. */
+export const MAX_STACK_LENGTH = 16_000;
+/** The most places of one stack looked up. */
+const MAX_PLACES = 50;
+/**
+ * A place in a stack: an address, then its line and column, in Chrome's (`(http://…:19:9)`), Firefox's and Safari's
+ * (`render@http://…:19:9`) forms.
+ */
+const PLACE = /(https?:\/\/[^\s()]+?):(\d+):(\d+)(?=\)|\s|$)/g;
+/**
+ * A source of a map as a path Vite writes: a map may name it absolute, as a `file:` address, or relative to the file.
+ *
+ * @param source - the source as the map names it.
+ * @param file - the module's file.
+ */
+const sourcePath = (source, file) => {
+    if (source.startsWith("file:"))
+        return VITE_PATHS.normalize(fileURLToPath(source));
+    // an absolute source is taken as written: resolving it would give a path with no drive one on Windows
+    if (VITE_PATHS.isAbsolute(source))
+        return VITE_PATHS.normalize(source);
+    return VITE_PATHS.resolve(VITE_PATHS.dirname(file), source);
+};
+/**
+ * Where a place of the served code was written, in its module's own file: none when the map does not lead there.
+ *
+ * @param module - the module served at the place's address.
+ * @param line - the line in the code served, from 1.
+ * @param column - the column in the code served, from 1.
+ */
+const originOf = (module, line, column) => {
+    const map = new SourceMap({
+        file: module.file,
+        version: module.map.version,
+        sources: [...module.map.sources],
+        sourcesContent: [],
+        names: [...module.map.names],
+        mappings: module.map.mappings,
+        sourceRoot: ""
+    });
+    const origin = map.findOrigin(line, column);
+    if (!("lineNumber" in origin))
+        return undefined;
+    if (sourcePath(origin.fileName, module.file) !== module.file)
+        return undefined;
+    return { line: origin.lineNumber, column: origin.columnNumber };
+};
+/**
+ * Maps a stack's places to the lines of their files as written.
+ *
+ * @param stack - the stack, as the browser wrote it.
+ * @param lookup - finds the module served at an address.
+ * @param root - the project's folder, which `place` is written relative to.
+ * @returns the stack mapped, and its first place in the project; the stack as it was past `MAX_STACK_LENGTH`.
+ */
+export const mappedStack = async (stack, lookup, root) => {
+    if (stack.length > MAX_STACK_LENGTH)
+        return { stack };
+    const places = [...stack.matchAll(PLACE)].slice(0, MAX_PLACES);
+    const urls = [...new Set(places.map((match) => match[1] ?? ""))];
+    const found = await Promise.all(urls.map(async (url) => [url, await lookup(url)]));
+    const modules = new Map(found);
+    let place;
+    let mapped = "";
+    let from = 0;
+    for (const match of places) {
+        const [whole, url = "", line = "", column = ""] = match;
+        const module = modules.get(url);
+        const origin = module === undefined ? undefined : originOf(module, Number(line), Number(column));
+        if (module === undefined || origin === undefined)
+            continue;
+        mapped += `${stack.slice(from, match.index)}${url}:${origin.line}:${origin.column}`;
+        from = match.index + whole.length;
+        if (place === undefined && !module.file.includes("/node_modules/"))
+            place = `${VITE_PATHS.relative(root, module.file)}:${origin.line}:${origin.column}`;
+    }
+    mapped += stack.slice(from);
+    return place === undefined ? { stack: mapped } : { stack: mapped, place };
+};

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

@@ -1,14 +1,29 @@
 /**
- * The code a story shows in the catalogue's Code card: each story's `render` as written in its file, read with Vite's
- * parser, never run.
+ * The code a story shows in the catalogue's Code card, read from its file with Vite's parser, never run: each story's
+ * `render` as written, and for a story drawn from its args, each arg the file writes as code.
  *
  * @remarks
- * A story without a `render` draws the meta's component with its args: the shell writes that JSX itself from the args
- * of the moment, so only the stories with a `render` need their text. A `render` written elsewhere (a helper the
- * story points to) shows as the name it is given, which is what the file says.
+ * A story's render is its own, else the meta's; a story written as a function (CSF 2), or bound from one
+ * (`Template.bind({})`), is its render. A render kept in a constant or a function of the file shows as that code; one
+ * imported from another file shows as its name, which is what the file says.
+ *
+ * A story without a render draws the meta's component with its args, and the shell writes that component in the
+ * framework's code from the args of the moment. Only plain data crosses from the frame, so a function, an element or
+ * any other code would be missing: this module gives the text of each such arg as written (`icon: <IconStar />`,
+ * `onClick: fn()`), the meta's args under the story's, following spreads of the file's constants and of another
+ * story's args. A plain literal is left to the value the frame reports, which is the same; a constant of the file is
+ * written by its value, an import by its name. What a spread or a value it cannot read may replace is forgotten, so
+ * the shell writes it from the value, never from a text the story does not draw. Pure: text in, texts out.
  *
  * @module
  */
+/** A story file's code: each story's render, and each args story's args written as code. */
+export type StoryFileCodeRead = {
+    /** Each story's render as written, by export name. */
+    readonly renders: Readonly<Record<string, string>>;
+    /** Each args story's args written as code, by export name then arg; a story with none is left out. */
+    readonly args: Readonly<Record<string, Readonly<Record<string, string>>>>;
+};
 /**
  * Removes from every line past the first the indentation of the line the code starts on, so a `render` reads as if
  * written at the left edge.
@@ -18,10 +33,10 @@
  */
 export declare const dedented: (text: string, indent: number) => string;
 /**
- * Each story's `render` text in a story file.
+ * Each story's code in a story file: its render as written, or its args written as code.
  *
  * @param file - the file's path, for the parser (its extension decides TypeScript and JSX) and the messages.
  * @param text - the file's source.
  * @returns the texts by export name, or a message saying why the file cannot be read.
  */
-export declare const storyCode: (file: string, text: string) => Readonly<Record<string, string>> | string;
+export declare const storyCode: (file: string, text: string) => StoryFileCodeRead | string;