forgebook 0.1.3 → 0.1.5

package/dist/src/vite/storyFilesModule.js

@@ -1,6 +1,7 @@
 /**
  * The module that answers a `?forgebook-files` import: every story file a pattern matches, as one module with each
- * file's index (read from its source, never run) and the loaders of its module, its component's docs and its code.
+ * file's index (read from its source, never run), the loaders of its module, its component's docs and its code, and
+ * the group's "Used in" loader.
  *
  * @remarks
  * One module per pattern, instead of an import per file: in development the browser fetched every index module one by
@@ -13,6 +14,21 @@ import { globSync, readFileSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { autoTitle, patternBase } from "./autoTitle.js";
 import { indexStoryFile } from "./indexStoryFile.js";
+/**
+ * The folder and the pattern a `?forgebook-files` import is read from: the pattern's leading `./` and `../` move into
+ * the folder. The catalogue's plugin keys the files this way (its modules' ids hold no `..`, which a URL path would
+ * collapse), and so does the testing package, so both list the same keys (`./src/x.stories.tsx`).
+ *
+ * @param folder - the importing module's folder.
+ * @param pattern - the pattern as the import writes it (`../src/**\/*.stories.tsx`).
+ */
+export const storyFilesGroup = (folder, pattern) => {
+    const segments = pattern.split("/");
+    const firstOwn = segments.findIndex((segment) => segment !== "." && segment !== "..");
+    const climbed = firstOwn === -1 ? segments : segments.slice(0, firstOwn);
+    const own = firstOwn === -1 ? [] : segments.slice(firstOwn);
+    return { root: resolve(folder, ...climbed), pattern: own.join("/") };
+};
 /**
  * The story files patterns match, as paths relative to `root` starting with `./` or `../`, sorted.
  *
@@ -26,6 +42,30 @@ export const storyFileKeys = (root, patterns) => patterns
     return path.startsWith(".") ? path : `./${path}`;
 })
     .sort();
+/**
+ * The id prefix of a group's "Used in" module: the pattern's folder and the pattern follow, as in a `?forgebook-files`
+ * module's id. The plugin answers it (`usageModule.ts`) only when a page asks.
+ */
+export const USAGE_PREFIX = "virtual:forgebook-usage:";
+/** Between the folder and the pattern in a usage module's id: no path or pattern holds it. */
+export const USAGE_SEPARATOR = "::";
+/**
+ * Every story file a pattern matches, indexed.
+ *
+ * @param root - the declaring module's folder.
+ * @param pattern - the pattern.
+ * @param watch - adds a file whose edit renews the module that read it.
+ * @throws when a story file cannot be indexed.
+ */
+export const indexedStoryFiles = (root, pattern, watch) => storyFileKeys(root, [pattern]).map((key) => {
+    const file = resolve(root, key);
+    watch(file);
+    const title = autoTitle(patternBase(pattern), key);
+    const index = indexStoryFile(file, readFileSync(file, "utf8"), title === undefined ? {} : { autoTitle: title });
+    if (typeof index === "string")
+        throw new Error(index);
+    return { key, file, index };
+});
 /** An object literal of a key per file, each value written by `value`. */
 const objectOf = (keys, value) => `{${keys.map((key) => `${JSON.stringify(key)}: ${value(key)}`).join(",\n")}}`;
 /**
@@ -34,20 +74,14 @@ const objectOf = (keys, value) => `{${keys.map((key) => `${JSON.stringify(key)}:
  * @param root - the declaring module's folder.
  * @param pattern - the pattern before `?forgebook-files`.
  * @param watch - adds a file whose edit renews the module (each story file: its index is in the module).
+ * @param hasUsage - whether the group offers its "Used in" loader (the catalogue did not turn it off).
  * @returns the module's code, or a message saying which file cannot be indexed.
  */
-export const storyFilesModule = (root, pattern, watch) => {
-    const keys = storyFileKeys(root, [pattern]);
-    const index = {};
-    for (const key of keys) {
-        const file = resolve(root, key);
-        watch(file);
-        const title = autoTitle(patternBase(pattern), key);
-        const entry = indexStoryFile(file, readFileSync(file, "utf8"), title === undefined ? {} : { autoTitle: title });
-        if (typeof entry === "string")
-            throw new Error(entry);
-        index[key] = entry;
-    }
+export const storyFilesModule = (root, pattern, watch, hasUsage = true) => {
+    const files = indexedStoryFiles(root, pattern, watch);
+    const keys = files.map((file) => file.key);
+    const index = Object.fromEntries(files.map((file) => [file.key, file.index]));
+    const usage = JSON.stringify(`${USAGE_PREFIX}${root}${USAGE_SEPARATOR}${pattern}`);
     // absolute paths: the module has no folder of its own; Vite serves them under /@fs/ in development
     const path = (key) => JSON.stringify(resolve(root, key));
     const query = (key, name) => JSON.stringify(`${resolve(root, key)}?${name}`);
@@ -57,7 +91,8 @@ export const storyFilesModule = (root, pattern, watch) => {
         `stories: ${objectOf(keys, (key) => `() => import(${path(key)})`)},`,
         `docs: ${objectOf(keys, (key) => `() => import(${query(key, "forgebook-docs")}).then((module) => module.default)`)},`,
         `code: ${objectOf(keys, (key) => `() => import(${query(key, "forgebook-code")}).then((module) => module.default)`)},`,
-        `pages: ${objectOf(keys, (key) => `() => import(${query(key, "forgebook-page")}).then((module) => module.default)`)}`,
+        `pages: ${objectOf(keys, (key) => `() => import(${query(key, "forgebook-page")}).then((module) => module.default)`)}${hasUsage ? "," : ""}`,
+        ...(hasUsage ? [`usage: () => import(${usage}).then((module) => module.default)`] : []),
         "};"
     ].join("\n");
 };

package/dist/src/vite/storyFilesModule.js.map

@@ -1 +1 @@
-{"version":3,"file":"storyFilesModule.js","sourceRoot":"","sources":["../../../src/vite/storyFilesModule.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"storyFilesModule.js","sourceRoot":"","sources":["../../../src/vite/storyFilesModule.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,35 @@
+/**
+ * The rewrite that lets a story's CSS answer as a phone's while the catalogue simulates touch: the rules under the
+ * pointer's media features (`hover`, `any-hover`, `pointer`, `any-pointer`) follow `data-forgebook-touch` on the root.
+ *
+ * @remarks
+ * The computer answers `hover: hover` and `pointer: fine`, and a page cannot change that. So each media rule that asks
+ * about the pointer is kept for the computer, its rules scoped to a root without the attribute, and copied once more
+ * as a phone would read it (`hover: none`, `pointer: coarse`, the rest of its query kept), its rules scoped to a root
+ * with the attribute. The scope is written in `:where()`, so no rule's specificity changes; a selector that starts at
+ * the root (`:root`, `html`) takes the condition on the root itself. On a real phone the attribute is never set, so
+ * its own media answer as before. The real mouse's `:hover` stops matching while touch is simulated: a finger does
+ * not hover (`NOT_UNDER_TOUCH`). Runs only in the catalogue's build, as a Lightning CSS visitor.
+ *
+ * @module
+ */
+import type { Rule, SelectorComponent } from "lightningcss";
+/** The root's attribute the catalogue sets while it simulates touch (`touchSwitch` of `switches.ts`). */
+export declare const TOUCH_ATTRIBUTE = "data-forgebook-touch";
+/**
+ * A media rule as the computer and as a simulated phone read it: the rule for the computer, its rules scoped to a
+ * root without the attribute, then, when a phone can match it, its copy with the pointer answered as a phone's, its
+ * rules scoped to a root with the attribute. A media rule that asks nothing of the pointer is left as it is.
+ *
+ * @param rule - a media rule.
+ */
+export declare const touchMediaRules: (rule: Extract<Rule, {
+    type: "media";
+}>) => Rule[] | undefined;
+/**
+ * `:where(:not(:root[data-forgebook-touch] *))`: an element outside a root that simulates touch. Written beside the
+ * real `:hover` (`forcedStates.ts`), so the mouse's hover stops matching while touch is simulated: a finger does not
+ * hover.
+ */
+export declare const NOT_UNDER_TOUCH: SelectorComponent;
+//# sourceMappingURL=touchMedia.d.ts.map

package/dist/src/vite/touchMedia.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"touchMedia.d.ts","sourceRoot":"","sources":["../../../src/vite/touchMedia.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAGV,IAAI,EAEJ,iBAAiB,EAClB,MAAM,cAAc,CAAC;AAEtB,yGAAyG;AACzG,eAAO,MAAM,eAAe,yBAAyB,CAAC;AAsJtD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,OAAO,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,KAAG,IAAI,EAAE,GAAG,SAkBjF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,iBAmB7B,CAAC"}

package/dist/src/vite/touchMedia.js

@@ -0,0 +1,187 @@
+/** The root's attribute the catalogue sets while it simulates touch (`touchSwitch` of `switches.ts`). */
+export const TOUCH_ATTRIBUTE = "data-forgebook-touch";
+/** The pointer's media features, and what a phone answers to each. */
+const PHONE_ANSWERS = {
+    hover: { value: "none", isPresent: false },
+    "any-hover": { value: "none", isPresent: false },
+    pointer: { value: "coarse", isPresent: true },
+    "any-pointer": { value: "coarse", isPresent: true }
+};
+/**
+ * A feature as a phone answers it; another feature stays a condition.
+ *
+ * @param feature - the feature.
+ */
+const phoneFeature = (feature) => {
+    if (feature.type === "range" || feature.type === "interval")
+        return undefined;
+    const answer = PHONE_ANSWERS[feature.name];
+    if (answer === undefined)
+        return undefined;
+    if (feature.type === "boolean")
+        return answer.isPresent;
+    return feature.value.type === "ident" && feature.value.value === answer.value;
+};
+/**
+ * A condition read as a phone would.
+ *
+ * @param condition - the condition.
+ */
+const phoneCondition = (condition) => {
+    if (condition.type === "feature")
+        return phoneFeature(condition.value) ?? condition;
+    if (condition.type === "not") {
+        const inner = phoneCondition(condition.value);
+        return typeof inner === "boolean" ? !inner : { type: "not", value: inner };
+    }
+    if (condition.type !== "operation")
+        return condition;
+    const isAnd = condition.operator === "and";
+    const parts = [];
+    for (const each of condition.conditions.map(phoneCondition)) {
+        // in an "and", false decides and true drops out; in an "or", the other way round
+        if (each === !isAnd)
+            return !isAnd;
+        if (typeof each !== "boolean")
+            parts.push(each);
+    }
+    if (parts.length === 0)
+        return isAnd;
+    return parts.length === 1 && parts[0] !== undefined ? parts[0] : { ...condition, conditions: parts };
+};
+/**
+ * Whether a condition asks about the pointer anywhere.
+ *
+ * @param condition - the condition.
+ */
+const asksPointer = (condition) => {
+    if (condition.type === "feature")
+        return (condition.value.type !== "range" &&
+            condition.value.type !== "interval" &&
+            condition.value.name in PHONE_ANSWERS);
+    if (condition.type === "not")
+        return asksPointer(condition.value);
+    return condition.type === "operation" && condition.conditions.some(asksPointer);
+};
+/**
+ * The queries a phone reads in a list: each query its pointer features answered; one a phone never matches dropped.
+ *
+ * @param queries - the media rule's queries.
+ * @returns the queries; none when a phone matches none of them.
+ */
+const phoneQueries = (queries) => queries.flatMap((query) => {
+    if (query.condition === null || query.condition === undefined)
+        return [query];
+    let reading = phoneCondition(query.condition);
+    if (query.qualifier === "not" && typeof reading === "boolean")
+        reading = !reading;
+    if (reading === false)
+        return [];
+    return [
+        reading === true ? { ...query, qualifier: null, condition: null } : { ...query, condition: reading }
+    ];
+});
+/** `[data-forgebook-touch]`. */
+const TOUCH = { type: "attribute", name: TOUCH_ATTRIBUTE };
+/**
+ * The root's condition: with the attribute, or without it.
+ *
+ * @param isTouch - whether touch is simulated.
+ */
+const rootCondition = (isTouch) => isTouch ? TOUCH : { type: "pseudo-class", kind: "not", selectors: [[TOUCH]] };
+/**
+ * A selector scoped to a root with touch simulated or without: the condition on the root itself when the selector
+ * starts there, a descendant of such a root otherwise, in `:where()` either way.
+ *
+ * @param selector - the selector.
+ * @param isTouch - whether touch is simulated.
+ */
+const scopedSelector = (selector, isTouch) => {
+    const condition = {
+        type: "pseudo-class",
+        kind: "where",
+        selectors: [[rootCondition(isTouch)]]
+    };
+    const firstCombinator = selector.findIndex((component) => component.type === "combinator");
+    const head = firstCombinator === -1 ? selector : selector.slice(0, firstCombinator);
+    const isAtRoot = head.some((component) => (component.type === "pseudo-class" && component.kind === "root") ||
+        (component.type === "type" && component.name === "html"));
+    if (isAtRoot)
+        return [...head, condition, ...selector.slice(head.length)];
+    const root = {
+        type: "pseudo-class",
+        kind: "where",
+        selectors: [[{ type: "pseudo-class", kind: "root" }, rootCondition(isTouch)]]
+    };
+    return [root, { type: "combinator", value: "descendant" }, ...selector];
+};
+/**
+ * Rules scoped to a root with touch simulated or without, inside the rules that group them (`@supports`, `@layer`,
+ * `@container`, another `@media`); a nested rule keeps its own selectors, relative to its scoped parent.
+ *
+ * @param rules - the rules.
+ * @param isTouch - whether touch is simulated.
+ */
+const scopedRules = (rules, isTouch) => rules.map((rule) => {
+    if (rule.type === "style") {
+        return {
+            ...rule,
+            value: { ...rule.value, selectors: rule.value.selectors.map((each) => scopedSelector(each, isTouch)) }
+        };
+    }
+    if (rule.type === "media" ||
+        rule.type === "supports" ||
+        rule.type === "container" ||
+        rule.type === "layer-block")
+        return { ...rule, value: { ...rule.value, rules: scopedRules(rule.value.rules, isTouch) } };
+    return rule;
+});
+/**
+ * A media rule as the computer and as a simulated phone read it: the rule for the computer, its rules scoped to a
+ * root without the attribute, then, when a phone can match it, its copy with the pointer answered as a phone's, its
+ * rules scoped to a root with the attribute. A media rule that asks nothing of the pointer is left as it is.
+ *
+ * @param rule - a media rule.
+ */
+export const touchMediaRules = (rule) => {
+    const queries = rule.value.query.mediaQueries;
+    if (!queries.some((query) => query.condition !== null && query.condition !== undefined && asksPointer(query.condition)))
+        return undefined;
+    const computer = { ...rule, value: { ...rule.value, rules: scopedRules(rule.value.rules, false) } };
+    const phone = phoneQueries(queries);
+    if (phone.length === 0)
+        return [computer];
+    return [
+        computer,
+        {
+            ...rule,
+            value: { ...rule.value, query: { mediaQueries: phone }, rules: scopedRules(rule.value.rules, true) }
+        }
+    ];
+};
+/**
+ * `:where(:not(:root[data-forgebook-touch] *))`: an element outside a root that simulates touch. Written beside the
+ * real `:hover` (`forcedStates.ts`), so the mouse's hover stops matching while touch is simulated: a finger does not
+ * hover.
+ */
+export const NOT_UNDER_TOUCH = {
+    type: "pseudo-class",
+    kind: "where",
+    selectors: [
+        [
+            {
+                type: "pseudo-class",
+                kind: "not",
+                selectors: [
+                    [
+                        { type: "pseudo-class", kind: "root" },
+                        TOUCH,
+                        { type: "combinator", value: "descendant" },
+                        { type: "universal" }
+                    ]
+                ]
+            }
+        ]
+    ]
+};
+//# sourceMappingURL=touchMedia.js.map

package/dist/src/vite/touchMedia.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"touchMedia.js","sourceRoot":"","sources":["../../../src/vite/touchMedia.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,45 @@
+/** A component, by the file that declares it and its name there. */
+export type ComponentRef = {
+    /** The declaring file's absolute path. */
+    readonly file: string;
+    /** Its name in that file (`default` for a default export). */
+    readonly name: string;
+};
+/** What one story renders. */
+export type StoryRenders = {
+    /** The story's export. */
+    readonly exportName: string;
+    /** The components its JSX names, or its meta's component when it has none; each once. */
+    readonly renders: readonly ComponentRef[];
+};
+/** One story file's facts. */
+export type StoryFileUsage = {
+    /** The story file's absolute path. */
+    readonly storyFile: string;
+    /** Its meta's component, when the meta names one the checker resolves. */
+    readonly component?: ComponentRef;
+    /** Its stories. */
+    readonly stories: readonly StoryRenders[];
+};
+/** What the worker answers for a group of story files. */
+export type UsageGraph = {
+    /** Each story file's facts, in the order asked; a file no program holds is left out. */
+    readonly files: readonly StoryFileUsage[];
+    /** Each module the rendered components reach, with the package's own modules it imports. */
+    readonly imports: Readonly<Record<string, readonly string[]>>;
+};
+/** A story file and the exports the index lists as its stories. */
+export type UsageRequestFile = {
+    /** The story file's absolute path. */
+    readonly storyFile: string;
+    /** Its stories' exports. */
+    readonly exports: readonly string[];
+};
+/**
+ * The facts of a group of story files: what each story renders, and the import graph the rendered components reach.
+ *
+ * @param requests - the story files and their stories' exports.
+ * @returns the facts, or why a story file's program could not be read.
+ */
+export declare const usageGraph: (requests: readonly UsageRequestFile[]) => UsageGraph | string;
+//# sourceMappingURL=usageGraph.d.ts.map

package/dist/src/vite/usageGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usageGraph.d.ts","sourceRoot":"","sources":["../../../src/vite/usageGraph.ts"],"names":[],"mappings":"AAoBA,oEAAoE;AACpE,MAAM,MAAM,YAAY,GAAG;IACzB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,8BAA8B;AAC9B,MAAM,MAAM,YAAY,GAAG;IACzB,0BAA0B;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C,CAAC;AAEF,8BAA8B;AAC9B,MAAM,MAAM,cAAc,GAAG;IAC3B,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY,CAAC;IAClC,mBAAmB;IACnB,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,UAAU,GAAG;IACvB,wFAAwF;IACxF,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;CAC/D,CAAC;AAEF,mEAAmE;AACnE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,CAAC;AA0PF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,UAAU,SAAS,gBAAgB,EAAE,KAAG,UAAU,GAAG,MAe/E,CAAC"}

package/dist/src/vite/usageGraph.js

@@ -0,0 +1,246 @@
+/**
+ * What each story renders and what each module imports, read from the TypeScript programs the docs already build:
+ * the facts "Used in" is joined from (`usageModule.ts`).
+ *
+ * @remarks
+ * Runs in the docs worker (`docsWorker.ts`), which holds the programs; a package's first read builds its program,
+ * the API tables reuse it. A story renders the components its JSX names, resolved by the type checker as its types are
+ * (a package-name import, an alias, `<Menu.Item>`); a component declared in the story file itself (a scene) is followed
+ * into its own JSX; a story without JSX renders its meta's component. A component is known by the file that declares
+ * it and its name there, so two imports of one component are one. The import graph holds the modules the rendered
+ * components reach through the package's own imports, never a dependency's (`node_modules`): "used through" follows
+ * those edges. A lowercase tag is an element (`<div>`), not a component. A component reached only through code the
+ * checker cannot follow (a computed lazy import, a component handed in as a prop) is not found.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+import { programFor } from "./docsProgram.js";
+/**
+ * The symbol a name stands for, through its imports and re-exports.
+ *
+ * @param symbol - the symbol at the name.
+ * @param checker - the program's checker.
+ */
+const declared = (symbol, checker) => symbol !== undefined && (symbol.flags & ts.SymbolFlags.Alias) !== 0
+    ? checker.getAliasedSymbol(symbol)
+    : symbol;
+/**
+ * A component's reference from its symbol: the file of its first declaration, and its name.
+ *
+ * @param symbol - the component's symbol.
+ */
+const refOf = (symbol) => {
+    const declaration = symbol?.declarations?.[0];
+    if (symbol === undefined || declaration === undefined)
+        return undefined;
+    return { file: declaration.getSourceFile().fileName, name: symbol.getName() };
+};
+/**
+ * An expression without the wrappers a meta is written with (`satisfies Meta<…>`, `as Meta`, parentheses).
+ *
+ * @param expression - the expression.
+ */
+const unwrap = (expression) => {
+    if (ts.isSatisfiesExpression(expression) ||
+        ts.isAsExpression(expression) ||
+        ts.isParenthesizedExpression(expression))
+        return unwrap(expression.expression);
+    return expression;
+};
+/**
+ * The meta's object: the default export, written inline or as a constant.
+ *
+ * @param source - the story file.
+ * @param checker - the program's checker.
+ */
+const metaObject = (source, checker) => {
+    const assignment = source.statements.find((statement) => ts.isExportAssignment(statement) && !statement.isExportEquals);
+    if (assignment === undefined)
+        return undefined;
+    let value = unwrap(assignment.expression);
+    if (ts.isIdentifier(value)) {
+        const declaration = declared(checker.getSymbolAtLocation(value), checker)?.valueDeclaration;
+        if (declaration !== undefined &&
+            ts.isVariableDeclaration(declaration) &&
+            declaration.initializer !== undefined)
+            value = unwrap(declaration.initializer);
+    }
+    return ts.isObjectLiteralExpression(value) ? value : undefined;
+};
+/**
+ * The meta's component, as the checker resolves its `component` property.
+ *
+ * @param meta - the meta's object.
+ * @param checker - the program's checker.
+ */
+const metaComponent = (meta, checker) => {
+    const property = meta.properties.find((each) => each.name !== undefined && each.name.getText() === "component");
+    if (property === undefined)
+        return undefined;
+    if (ts.isShorthandPropertyAssignment(property))
+        return refOf(declared(checker.getShorthandAssignmentValueSymbol(property), checker));
+    if (ts.isPropertyAssignment(property))
+        return refOf(declared(checker.getSymbolAtLocation(unwrap(property.initializer)), checker));
+    return undefined;
+};
+/**
+ * The symbol a JSX element's tag stands for; none for an element of the page (a lowercase name, `<div>`).
+ *
+ * @param element - the element's opening or self-closing tag.
+ * @param checker - the program's checker.
+ */
+const tagSymbol = (element, checker) => {
+    const tag = element.tagName;
+    if (ts.isIdentifier(tag) && /^[a-z]/.test(tag.text))
+        return undefined;
+    return declared(checker.getSymbolAtLocation(tag), checker);
+};
+/**
+ * The components a node's JSX names: those declared elsewhere as references, those declared in the story file followed
+ * into their own declarations, each declaration once.
+ *
+ * @param node - the story's node.
+ * @param source - the story file.
+ * @param checker - the program's checker.
+ * @param seen - the declarations already followed.
+ */
+const jsxRenders = (node, source, checker, seen) => {
+    const found = [];
+    const named = (symbol) => {
+        const declaration = symbol?.declarations?.[0];
+        const isLocal = declaration !== undefined && declaration.getSourceFile() === source;
+        if (!isLocal) {
+            const ref = refOf(symbol);
+            if (ref !== undefined)
+                found.push(ref);
+            return;
+        }
+        if (seen.has(declaration))
+            return;
+        seen.add(declaration);
+        found.push(...jsxRenders(declaration, source, checker, seen));
+    };
+    const visit = (current) => {
+        if (ts.isJsxOpeningElement(current) || ts.isJsxSelfClosingElement(current))
+            named(tagSymbol(current, checker));
+        ts.forEachChild(current, visit);
+    };
+    visit(node);
+    return found;
+};
+/**
+ * References without repeats, in their first order.
+ *
+ * @param refs - the references.
+ */
+const unique = (refs) => {
+    const keys = new Set();
+    return refs.filter((ref) => {
+        const key = `${ref.file}#${ref.name}`;
+        if (keys.has(key))
+            return false;
+        keys.add(key);
+        return true;
+    });
+};
+/**
+ * One story file's facts, from the program that holds it.
+ *
+ * @param request - the story file and its stories' exports.
+ * @param program - the program.
+ */
+const fileUsage = (request, program) => {
+    const source = program.getSourceFile(request.storyFile);
+    if (source === undefined)
+        return undefined;
+    const checker = program.getTypeChecker();
+    const meta = metaObject(source, checker);
+    const component = meta === undefined ? undefined : metaComponent(meta, checker);
+    const moduleSymbol = checker.getSymbolAtLocation(source);
+    const exported = moduleSymbol === undefined ? [] : checker.getExportsOfModule(moduleSymbol);
+    const stories = request.exports.map((exportName) => {
+        const symbol = declared(exported.find((each) => each.getName() === exportName), checker);
+        const declaration = symbol?.declarations?.[0];
+        const named = declaration === undefined ? [] : jsxRenders(declaration, source, checker, new Set([declaration]));
+        const renders = named.length === 0 && component !== undefined ? [component] : unique(named);
+        return { exportName, renders };
+    });
+    return { storyFile: request.storyFile, ...(component === undefined ? {} : { component }), stories };
+};
+/**
+ * The package's own modules a module imports or re-exports from, resolved as its program resolves them.
+ *
+ * @param source - the module.
+ * @param program - its program.
+ * @param cache - the program's resolution cache.
+ */
+const importsOf = (source, program, cache) => {
+    const targets = [];
+    for (const statement of source.statements) {
+        const specifier = (ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) &&
+            statement.moduleSpecifier !== undefined &&
+            ts.isStringLiteral(statement.moduleSpecifier)
+            ? statement.moduleSpecifier.text
+            : undefined;
+        if (specifier === undefined)
+            continue;
+        const resolved = ts.resolveModuleName(specifier, source.fileName, program.getCompilerOptions(), ts.sys, cache).resolvedModule;
+        if (resolved !== undefined && !resolved.isExternalLibraryImport)
+            targets.push(resolved.resolvedFileName);
+    }
+    return targets;
+};
+/**
+ * The import graph of the modules the given files reach, through the package's own imports.
+ *
+ * @param starts - the files to start from.
+ * @param programs - the programs that may hold them.
+ */
+const reachedImports = (starts, programs) => {
+    const caches = new Map(programs.map((program) => [
+        program,
+        ts.createModuleResolutionCache(program.getCurrentDirectory(), (name) => name, program.getCompilerOptions())
+    ]));
+    const imports = {};
+    const queue = [...starts];
+    while (queue.length > 0) {
+        const file = queue.pop() ?? "";
+        if (file in imports)
+            continue;
+        const program = programs.find((candidate) => candidate.getSourceFile(file) !== undefined);
+        const source = program?.getSourceFile(file);
+        const cache = program === undefined ? undefined : caches.get(program);
+        const targets = program === undefined || source === undefined || cache === undefined
+            ? []
+            : importsOf(source, program, cache);
+        imports[file] = targets;
+        queue.push(...targets);
+    }
+    return imports;
+};
+/**
+ * The facts of a group of story files: what each story renders, and the import graph the rendered components reach.
+ *
+ * @param requests - the story files and their stories' exports.
+ * @returns the facts, or why a story file's program could not be read.
+ */
+export const usageGraph = (requests) => {
+    const files = [];
+    const programs = new Set();
+    for (const request of requests) {
+        const docsProgram = programFor(request.storyFile);
+        if (typeof docsProgram === "string")
+            return docsProgram;
+        programs.add(docsProgram.program);
+        const usage = fileUsage(request, docsProgram.program);
+        if (usage !== undefined)
+            files.push(usage);
+    }
+    const starts = files.flatMap((file) => [
+        ...(file.component === undefined ? [] : [file.component.file]),
+        ...file.stories.flatMap((story) => story.renders.map((ref) => ref.file))
+    ]);
+    return { files, imports: reachedImports([...new Set(starts)], [...programs]) };
+};
+//# sourceMappingURL=usageGraph.js.map