shelving 1.227.0 → 1.229.0

package/extract/DirectoryExtractor.d.ts

@@ -1,16 +1,14 @@
 import type { ImmutableDictionary } from "../util/dictionary.js";
-import { type DirectoryElement } from "../util/element.js";
+import type { DirectoryElement } from "../util/element.js";
 import { type AbsolutePath, type Matchables, type Path } from "../util/index.js";
 import { Extractor } from "./Extractor.js";
 import { FileExtractor } from "./FileExtractor.js";
 /** Options for a directory extractor. */
 export interface DirectoryExtractorOptions {
-    /** Filenames to treat as the directory's index file. Matched case-insensitively. */
-    readonly index?: Matchables;
     /**
-     * Extractor dispatch table keyed by file extension (with leading dot, e.g. `".md"`).
+     * Extractor dispatch table keyed by file extension (without the leading dot, e.g. `"md"`).
      * - Files with no matching extractor are silently skipped.
-     * - Defaults to `.md` (markdown), `.ts` (TypeScript), and `.txt` (plain text).
+     * - Defaults to `.md` (markdown), `.ts` / `.tsx` (TypeScript), and `.txt` (plain text).
      */
     readonly extractors?: ImmutableDictionary<FileExtractor>;
     /** Absolute base path used to resolve relative paths passed to `extract()`. */
@@ -25,17 +23,16 @@ export interface DirectoryExtractorOptions {
 /**
  * Extractor that walks a directory on disk and produces a `DirectoryElement` tree.
  * - Recursively descends into subdirectories.
- * - Detects an index file (e.g. `README.md`) and absorbs its content/description/title as the directory's own.
- * - Dispatches non-index files to a matching `FileExtractor` based on extension; files with no matching extractor are silently skipped.
- * - Merges file elements that share the same `key` (e.g. `TEMPLATE.md` and `template.ts`) using each extractor's `priority`.
- * - Throws if a directory and a file (or two directories) share the same `key`.
+ * - Dispatches non-ignored files to a matching `FileExtractor` based on extension; files with no matching extractor are silently skipped.
+ * - Keys on the produced elements are the verbatim filenames (e.g. `"string.ts"`, `"README.md"`) and directory names (e.g. `"util"`).
+ * - This is a pure walker: same-key merging and README absorption are intentionally *not* applied here — wrap with `MergingExtractor`
+ *   and/or `IndexFileExtractor` to opt in to those behaviours.
  */
 export declare class DirectoryExtractor extends Extractor<Path, DirectoryElement> {
-    private readonly _indexes;
     private readonly _extractors;
     private readonly _base;
     private readonly _ignore;
-    constructor({ index, extractors, base, ignore }?: DirectoryExtractorOptions);
+    constructor({ extractors, base, ignore }?: DirectoryExtractorOptions);
     extract(source: Path): Promise<DirectoryElement>;
     private _extractDirectory;
     private _extractChild;

package/extract/DirectoryExtractor.js

@@ -1,18 +1,10 @@
 import { readdir } from "node:fs/promises";
-import { mergeElements } from "../util/element.js";
 import { splitFileExtension } from "../util/file.js";
 import { anyMatch, requirePath, splitPath } from "../util/index.js";
-import { requireSlug } from "../util/string.js";
-import { Extractor, mergeTreeElements } from "./Extractor.js";
+import { Extractor } from "./Extractor.js";
 import { FileExtractor } from "./FileExtractor.js";
 import { MarkupExtractor } from "./MarkupExtractor.js";
 import { TypescriptExtractor } from "./TypescriptExtractor.js";
-/**
- * Default list of filenames patterns treated as the directory's index file.
- * - Matched case-insensitively (all entries stored lowercase).
- * - If matched but no extractor is registered for the file's extension, the index is silently skipped.
- */
-const DEFAULT_INDEX = [/^readme\.txt$/i, /^readme\.md$/i, /^index\.md$/i, /^index\.ts$/i, /^index\.tsx$/i];
 /** Default file extractor dispatch by extension. */
 const DEFAULT_EXTRACTORS = {
     md: new MarkupExtractor(),
@@ -27,35 +19,20 @@ const DEFAULT_EXTRACTORS = {
  * - Skip hidden `.` prefixed and underscore-prefixed files and directories.
  */
 const DEFAULT_IGNORE = [/\.test\.tsx?$/i, /\.spec\.tsx?$/i, /^node_modules$/i, /^[_.]/i];
-/**
- * Merge two tree elements, favouring the one with the highest priority.
- * - We merge together elements with the same `key:` (e.g. `TEMPLATE.md` and `template.ts`).
- * - `title` and `description` are taken from the higher-priority element.
- * - `content` and `children` of both elements are merged (with the higher-priority element's content/children first).
- */
-function _mergeChild(existing, next) {
-    if (!existing)
-        return next;
-    return next.priority > existing.priority
-        ? { element: mergeTreeElements(next.element, existing.element), priority: next.priority }
-        : { element: mergeTreeElements(existing.element, next.element), priority: existing.priority };
-}
 /**
  * Extractor that walks a directory on disk and produces a `DirectoryElement` tree.
  * - Recursively descends into subdirectories.
- * - Detects an index file (e.g. `README.md`) and absorbs its content/description/title as the directory's own.
- * - Dispatches non-index files to a matching `FileExtractor` based on extension; files with no matching extractor are silently skipped.
- * - Merges file elements that share the same `key` (e.g. `TEMPLATE.md` and `template.ts`) using each extractor's `priority`.
- * - Throws if a directory and a file (or two directories) share the same `key`.
+ * - Dispatches non-ignored files to a matching `FileExtractor` based on extension; files with no matching extractor are silently skipped.
+ * - Keys on the produced elements are the verbatim filenames (e.g. `"string.ts"`, `"README.md"`) and directory names (e.g. `"util"`).
+ * - This is a pure walker: same-key merging and README absorption are intentionally *not* applied here — wrap with `MergingExtractor`
+ *   and/or `IndexFileExtractor` to opt in to those behaviours.
  */
 export class DirectoryExtractor extends Extractor {
-    _indexes;
     _extractors;
     _base;
     _ignore;
-    constructor({ index = DEFAULT_INDEX, extractors = DEFAULT_EXTRACTORS, base, ignore = DEFAULT_IGNORE } = {}) {
+    constructor({ extractors = DEFAULT_EXTRACTORS, base, ignore = DEFAULT_IGNORE } = {}) {
         super();
-        this._indexes = index;
         this._extractors = extractors;
         this._base = base;
         this._ignore = ignore;
@@ -66,62 +43,37 @@ export class DirectoryExtractor extends Extractor {
     async _extractDirectory(source) {
         const name = splitPath(source).at(-1) ?? "";
         const entries = await readdir(source, { withFileTypes: true });
-        // Keep track of the current index entry and children by key, so we can merge same-key elements.
-        let index;
-        const items = {};
+        const children = [];
         for (const entry of entries) {
-            // Should we ignore this entry?
             if (anyMatch(entry.name, ...this._ignore))
                 continue;
-            // Extract the child element and possibly merge it.
             const child = await this._extractChild(source, entry);
-            if (child) {
-                // Is this entry an index? If so, we'll treat it as the directory itself and merge it with any existing index entry if needed.
-                if (anyMatch(entry.name, ...this._indexes)) {
-                    index = _mergeChild(index, child);
-                }
-                else {
-                    const key = child.element.key;
-                    items[key] = _mergeChild(items[key], child);
-                }
-            }
+            if (child)
+                children.push(child);
         }
-        const children = Object.values(items).map(({ element }) => element);
         return {
             type: "tree-directory",
-            key: requireSlug(name),
+            key: name,
             props: {
                 source,
                 name,
-                // `title` is only set when the absorbed index file has a confident one (e.g. README H1).
-                // Renderers fall back to `name` otherwise.
-                title: index?.element.props.title,
-                description: index?.element.props.description,
-                content: index?.element.props.content,
-                children: mergeElements(index?.element.props.children, children),
+                children,
             },
         };
     }
     async _extractChild(base, entry) {
         const name = entry.name;
         const path = requirePath(name, base);
-        if (entry.isDirectory()) {
-            return {
-                element: await this._extractDirectory(path),
-                priority: this.priority,
-            };
-        }
-        else if (entry.isFile()) {
-            const [base, extension] = splitFileExtension(name);
-            if (!base || !extension)
-                return; // Skip files with no base name or extension.
+        if (entry.isDirectory())
+            return this._extractDirectory(path);
+        if (entry.isFile()) {
+            const [stem, extension] = splitFileExtension(name);
+            if (!stem || !extension)
+                return;
             const extractor = this._extractors[extension];
             if (!extractor)
-                return; // Skip files with no registered extractor (including non-matching index files).
-            return {
-                element: await extractor.extract(Bun.file(path)),
-                priority: extractor.priority,
-            };
+                return;
+            return extractor.extract(Bun.file(path));
         }
     }
 }

package/extract/Extractor.d.ts

@@ -2,23 +2,17 @@ import { type TreeElement } from "../util/element.js";
 /**
  * Base class for an extractor that converts input into a tree element.
  * - Extractors are composable: outer extractors delegate to inner extractors.
- * - The output type is always a `TreeElement` (or a more specific subtype like `TreeElement`).
+ * - The output type is always a `TreeElement` (or a more specific subtype).
  */
 export declare abstract class Extractor<I, O extends TreeElement = TreeElement> {
     /** Extract a tree element from the given input. */
-    abstract extract(input: I): Partial<O> | Promise<Partial<O>>;
-    /**
-     * Priority used to resolve same-key collisions when merging elements.
-     * - Higher-priority elements contribute their `title`, `description`, `path` to the merged result.
-     * - Higher-priority elements a prefixed (rather than suffixed) in `children` and `content` when merged.
-     * - Defaults to `0`; subclasses override (e.g. `MarkupExtractor` is `10`).
-     */
-    readonly priority: number;
+    abstract extract(input: I): O | Promise<O>;
 }
 /**
- * Merge two file elements with the same `key`.
- * - `title` and `source` are taken from `primary` (the higher-priority element).
- * - `description` is taken from `primary` if set, otherwise from `secondary`.
+ * Merge two tree elements — `primary` keeps its identity (`type`, `key`, `source`); `secondary` contributes any
+ * metadata `primary` does not already have.
+ * - `title` and `description` are taken from `primary` when set, otherwise from `secondary` — primary stays canonical
+ *   but a missing field falls back rather than disappearing.
  * - `content` and `children` from both are concatenated (primary first).
  */
 export declare function mergeTreeElements<T extends TreeElement>(primary: T, secondary: TreeElement): T;

package/extract/Extractor.js

@@ -2,16 +2,9 @@ import { mergeElements } from "../util/element.js";
 /**
  * Base class for an extractor that converts input into a tree element.
  * - Extractors are composable: outer extractors delegate to inner extractors.
- * - The output type is always a `TreeElement` (or a more specific subtype like `TreeElement`).
+ * - The output type is always a `TreeElement` (or a more specific subtype).
  */
 export class Extractor {
-    /**
-     * Priority used to resolve same-key collisions when merging elements.
-     * - Higher-priority elements contribute their `title`, `description`, `path` to the merged result.
-     * - Higher-priority elements a prefixed (rather than suffixed) in `children` and `content` when merged.
-     * - Defaults to `0`; subclasses override (e.g. `MarkupExtractor` is `10`).
-     */
-    priority = 0;
 }
 export function mergeTreeElements(primary, secondary) {
     return {
@@ -20,6 +13,7 @@ export function mergeTreeElements(primary, secondary) {
         key: primary.key,
         props: {
             ...primary.props,
+            title: primary.props.title ?? secondary.props.title,
             description: primary.props.description ?? secondary.props.description,
             content: _mergeContent(primary.props.content, secondary.props.content),
             children: mergeElements(primary.props.children, secondary.props.children),

package/extract/FileExtractor.d.ts

@@ -6,7 +6,8 @@ import { Extractor } from "./Extractor.js";
  * - Reads the file's content as text and stores it in `content`.
  * - Sets `source` to the file's absolute path (`BunFile.name`); throws `RequiredError` if missing or non-absolute.
  * - Sets `name` to the basename without extension, preserving case (e.g. `"OptionalSchema"` from `"OptionalSchema.ts"`); URL paths use `name`.
- * - Sets `key` to the slugified `name` (e.g. `"optionalschema"`) — only used by React for reconciliation and by `DirectoryExtractor` to merge same-key siblings (e.g. `TEMPLATE.md` + `template.ts`).
+ * - Sets `key` to the verbatim filename including extension (e.g. `"OptionalSchema.ts"`). Keys are unique within a directory
+ *   and used by `MergingExtractor` to pair siblings (`{base}.md` + `{base}.ts`) and by `PackageExtractor` to look up sources.
  * - Does NOT set `title` — `title` is only set by subclasses that have a confident source for one (e.g. `MarkupExtractor` uses the first `<h1>`). Renderers fall back to `name` when missing.
  * - Subclasses (e.g. `MarkupExtractor`, `TypescriptExtractor`) override `extractProps()` to parse the content into richer elements.
  */

package/extract/FileExtractor.js

@@ -1,14 +1,14 @@
 import { RequiredError } from "../error/RequiredError.js";
 import { splitFileExtension } from "../util/file.js";
 import { isAbsolutePath, splitPath } from "../util/index.js";
-import { requireSlug } from "../util/string.js";
 import { Extractor } from "./Extractor.js";
 /**
  * Base extractor for a file in a tree.
  * - Reads the file's content as text and stores it in `content`.
  * - Sets `source` to the file's absolute path (`BunFile.name`); throws `RequiredError` if missing or non-absolute.
  * - Sets `name` to the basename without extension, preserving case (e.g. `"OptionalSchema"` from `"OptionalSchema.ts"`); URL paths use `name`.
- * - Sets `key` to the slugified `name` (e.g. `"optionalschema"`) — only used by React for reconciliation and by `DirectoryExtractor` to merge same-key siblings (e.g. `TEMPLATE.md` + `template.ts`).
+ * - Sets `key` to the verbatim filename including extension (e.g. `"OptionalSchema.ts"`). Keys are unique within a directory
+ *   and used by `MergingExtractor` to pair siblings (`{base}.md` + `{base}.ts`) and by `PackageExtractor` to look up sources.
  * - Does NOT set `title` — `title` is only set by subclasses that have a confident source for one (e.g. `MarkupExtractor` uses the first `<h1>`). Renderers fall back to `name` when missing.
  * - Subclasses (e.g. `MarkupExtractor`, `TypescriptExtractor`) override `extractProps()` to parse the content into richer elements.
  */
@@ -23,7 +23,7 @@ export class FileExtractor extends Extractor {
         const props = { ...this.extractProps(base, text), source };
         return {
             type: "tree-file",
-            key: requireSlug(base),
+            key: filename,
             props,
         };
     }

package/extract/IndexFileExtractor.d.ts

@@ -0,0 +1,24 @@
+import { type DirectoryElement } from "../util/element.js";
+import { type Matchables } from "../util/regexp.js";
+import type { Extractor } from "./Extractor.js";
+import { ThroughExtractor } from "./ThroughExtractor.js";
+/** Options for an `IndexFileExtractor`. */
+export interface IndexFileExtractorOptions {
+    /**
+     * Filename patterns treated as the directory's index file. Matched case-insensitively against each child element's `key`.
+     * - Defaults to README and index files: `["readme.txt", "readme.md", "index.md", "index.ts", "index.tsx"]`.
+     */
+    readonly index?: Matchables;
+}
+/**
+ * Through extractor that walks a `DirectoryElement` tree and absorbs each directory's index file into the directory itself.
+ * - For each directory: finds the first child whose `key` matches any `index` pattern.
+ * - The matched child's `title`, `description`, `content`, and `children` are folded into the parent directory.
+ * - The matched child is removed from the parent's children list.
+ * - Recurses into subdirectories before absorbing — the deepest level happens first.
+ */
+export declare class IndexFileExtractor<I> extends ThroughExtractor<I, DirectoryElement> {
+    private readonly _index;
+    constructor(source: Extractor<I, DirectoryElement>, { index }?: IndexFileExtractorOptions);
+    extract(input: I): Promise<DirectoryElement>;
+}

package/extract/IndexFileExtractor.js

@@ -0,0 +1,48 @@
+import { mergeElements, walkElements } from "../util/element.js";
+import { anyMatch } from "../util/regexp.js";
+import { ThroughExtractor } from "./ThroughExtractor.js";
+/**
+ * Default index file patterns.
+ * - Matched case-insensitively (all entries stored lowercase).
+ * - The first child of a directory that matches any pattern is absorbed.
+ */
+const DEFAULT_INDEX = [/^readme\.txt$/i, /^readme\.md$/i, /^index\.md$/i, /^index\.ts$/i, /^index\.tsx$/i];
+/**
+ * Through extractor that walks a `DirectoryElement` tree and absorbs each directory's index file into the directory itself.
+ * - For each directory: finds the first child whose `key` matches any `index` pattern.
+ * - The matched child's `title`, `description`, `content`, and `children` are folded into the parent directory.
+ * - The matched child is removed from the parent's children list.
+ * - Recurses into subdirectories before absorbing — the deepest level happens first.
+ */
+export class IndexFileExtractor extends ThroughExtractor {
+    _index;
+    constructor(source, { index = DEFAULT_INDEX } = {}) {
+        super(source);
+        this._index = index;
+    }
+    async extract(input) {
+        const root = await this.source.extract(input);
+        return _absorbIndex(root, this._index);
+    }
+}
+/** Recursively absorb the index file in `dir` and all nested directories. */
+function _absorbIndex(dir, index) {
+    // Recurse first so nested directories absorb their own indexes before we look at this level.
+    const recursed = Array.from(walkElements(dir.props.children)).map(child => child.type === "tree-directory" ? _absorbIndex(child, index) : child);
+    // Find the index child by key.
+    const indexChild = recursed.find(child => anyMatch(child.key, ...index));
+    if (!indexChild)
+        return { ...dir, props: { ...dir.props, children: recursed } };
+    // Fold the index child into the directory, and drop it from children.
+    const remaining = recursed.filter(child => child !== indexChild);
+    return {
+        ...dir,
+        props: {
+            ...dir.props,
+            title: dir.props.title ?? indexChild.props.title,
+            description: dir.props.description ?? indexChild.props.description,
+            content: dir.props.content ?? indexChild.props.content,
+            children: mergeElements(indexChild.props.children, remaining),
+        },
+    };
+}

package/extract/MarkupExtractor.d.ts

@@ -10,8 +10,6 @@ import { FileExtractor } from "./FileExtractor.js";
  * - Sets `description` to the first prose paragraph as a plain-text summary (used for card listings and `<meta>`).
  */
 export declare class MarkupExtractor extends FileExtractor {
-    /** Markdown contributes the canonical title/path when merging same-key elements. */
-    readonly priority = 10;
     extractProps(name: string, text: string): Partial<FileElementProps> & {
         name: string;
     };

package/extract/MarkupExtractor.js

@@ -11,8 +11,6 @@ import { FileExtractor } from "./FileExtractor.js";
  * - Sets `description` to the first prose paragraph as a plain-text summary (used for card listings and `<meta>`).
  */
 export class MarkupExtractor extends FileExtractor {
-    /** Markdown contributes the canonical title/path when merging same-key elements. */
-    priority = 10;
     extractProps(name, text) {
         const { title, description } = extractMarkdownProps(text);
         // The title `# h1` is surfaced separately as `title`, so strip it from the body to avoid rendering it twice.

package/extract/MergingExtractor.d.ts

@@ -0,0 +1,27 @@
+import type { ImmutableDictionary } from "../util/dictionary.js";
+import { type DirectoryElement } from "../util/element.js";
+import type { Extractor } from "./Extractor.js";
+import { ThroughExtractor } from "./ThroughExtractor.js";
+/** Options for a `MergingExtractor`. */
+export interface MergingExtractorOptions {
+    /**
+     * Templated key pairs that should merge. Each key is a `{base}` template matched against the secondary element's key;
+     * each value is an ordered list of `{base}` templates for the primary candidates to merge into.
+     * - The first primary candidate that exists in the same directory wins; remaining candidates are ignored.
+     * - If no candidate exists the secondary is left in place as its own tree-file element.
+     * - Defaults to `{ "{base}.md": ["{base}.ts", "{base}.tsx", "{base}.js", "{base}.jsx"] }`.
+     */
+    readonly merges?: ImmutableDictionary<readonly string[]>;
+}
+/**
+ * Through extractor that walks a `DirectoryElement` tree and merges sibling tree elements whose keys match a `merges` template pair.
+ * - Walks every directory recursively, applying the merge at each level.
+ * - The primary (winning) element keeps its `key`, `source`, and `type`; the secondary's `title`, `description`,
+ *   `content`, and `children` are folded in via `mergeTreeElements()`.
+ * - A secondary with no matching primary is left in place — pure prose files (e.g. `concepts.md` with no `concepts.ts`) stand alone.
+ */
+export declare class MergingExtractor<I> extends ThroughExtractor<I, DirectoryElement> {
+    private readonly _merges;
+    constructor(source: Extractor<I, DirectoryElement>, { merges }?: MergingExtractorOptions);
+    extract(input: I): Promise<DirectoryElement>;
+}

package/extract/MergingExtractor.js

@@ -0,0 +1,65 @@
+import { walkElements } from "../util/element.js";
+import { matchTemplate, renderTemplate } from "../util/template.js";
+import { mergeTreeElements } from "./Extractor.js";
+import { ThroughExtractor } from "./ThroughExtractor.js";
+/**
+ * Default merges map: a markdown file is absorbed into its same-base TypeScript counterpart.
+ * - Key (secondary) and values (primary candidates) are `{base}`-templated key strings.
+ * - Candidates are checked in order — the first one that exists in the tree wins.
+ * - A secondary with no matching primary is left in place as its own element.
+ */
+const DEFAULT_MERGES = {
+    "{base}.md": ["{base}.ts", "{base}.tsx", "{base}.js", "{base}.jsx"],
+};
+/**
+ * Through extractor that walks a `DirectoryElement` tree and merges sibling tree elements whose keys match a `merges` template pair.
+ * - Walks every directory recursively, applying the merge at each level.
+ * - The primary (winning) element keeps its `key`, `source`, and `type`; the secondary's `title`, `description`,
+ *   `content`, and `children` are folded in via `mergeTreeElements()`.
+ * - A secondary with no matching primary is left in place — pure prose files (e.g. `concepts.md` with no `concepts.ts`) stand alone.
+ */
+export class MergingExtractor extends ThroughExtractor {
+    _merges;
+    constructor(source, { merges = DEFAULT_MERGES } = {}) {
+        super(source);
+        this._merges = merges;
+    }
+    async extract(input) {
+        const root = await this.source.extract(input);
+        return _mergeDirectory(root, this._merges);
+    }
+}
+/** Recursively merge same-template siblings inside `dir` and all nested directories. */
+function _mergeDirectory(dir, merges) {
+    const children = Array.from(walkElements(dir.props.children));
+    const merged = _mergeChildren(children, merges).map(child => child.type === "tree-directory" ? _mergeDirectory(child, merges) : child);
+    return { ...dir, props: { ...dir.props, children: merged } };
+}
+/** Merge same-template siblings at one directory level. */
+function _mergeChildren(children, merges) {
+    // Index children by key so we can look up primary candidates quickly.
+    const byKey = new Map();
+    for (const child of children)
+        byKey.set(child.key, child);
+    // Walk in original order, deciding for each whether it's a secondary that should fold into a primary.
+    const skip = new Set();
+    for (const secondary of children) {
+        for (const [lhs, candidates] of Object.entries(merges)) {
+            const matches = matchTemplate(lhs, secondary.key);
+            if (!matches)
+                continue;
+            for (const rhs of candidates) {
+                const primaryKey = renderTemplate(rhs, matches);
+                const primary = byKey.get(primaryKey);
+                if (!primary || primary === secondary)
+                    continue;
+                byKey.set(primaryKey, mergeTreeElements(primary, secondary));
+                skip.add(secondary);
+                break;
+            }
+            if (skip.has(secondary))
+                break;
+        }
+    }
+    return children.filter(c => !skip.has(c)).map(c => byKey.get(c.key) ?? c);
+}

package/extract/ModuleExtractor.d.ts

@@ -0,0 +1,23 @@
+import { type DirectoryElement, type DocumentationElement, type FileElement } from "../util/element.js";
+import { Extractor } from "./Extractor.js";
+/** Input for a `ModuleExtractor`. */
+export interface ModuleExtractorInput {
+    /** Display name for the module, derived from the package.json export key (e.g. `"util/string"`, `"firestore/client"`). */
+    readonly name: string;
+    /**
+     * The source element this module is built from.
+     * - `FileElement` — the module is backed by a single source file (with its `.md` sibling already merged in by `MergingExtractor`).
+     * - `DirectoryElement` — the module is backed by a directory; its absorbed index file provides the content.
+     */
+    readonly source: FileElement | DirectoryElement;
+}
+/**
+ * Extractor that builds a `kind: "module"` `DocumentationElement` from a source file or directory.
+ * - The module's `content`, `description`, and `title` are taken from the source element (`MergingExtractor` and
+ *   `IndexFileExtractor` are expected to have run upstream so `.md` siblings and `README.md` are already folded in).
+ * - The module's `children` are every `tree-documentation` element found by deep-walking the source — flattened across
+ *   files and subdirectories, but never descending into a `tree-documentation`'s own members.
+ */
+export declare class ModuleExtractor extends Extractor<ModuleExtractorInput, DocumentationElement> {
+    extract({ name, source }: ModuleExtractorInput): DocumentationElement;
+}

package/extract/ModuleExtractor.js

@@ -0,0 +1,41 @@
+import { walkElements } from "../util/element.js";
+import { requireSlug } from "../util/string.js";
+import { Extractor } from "./Extractor.js";
+/**
+ * Extractor that builds a `kind: "module"` `DocumentationElement` from a source file or directory.
+ * - The module's `content`, `description`, and `title` are taken from the source element (`MergingExtractor` and
+ *   `IndexFileExtractor` are expected to have run upstream so `.md` siblings and `README.md` are already folded in).
+ * - The module's `children` are every `tree-documentation` element found by deep-walking the source — flattened across
+ *   files and subdirectories, but never descending into a `tree-documentation`'s own members.
+ */
+export class ModuleExtractor extends Extractor {
+    extract({ name, source }) {
+        const children = _collectChildren(source);
+        return {
+            type: "tree-documentation",
+            key: requireSlug(name),
+            props: {
+                name,
+                title: name,
+                kind: "module",
+                description: source.props.description,
+                content: source.props.content,
+                children: children.length ? children : undefined,
+            },
+        };
+    }
+}
+/** Collect every `tree-documentation` element reachable inside `element`, descending through directories and files but not through documented symbols. */
+function _collectChildren(element) {
+    const result = [];
+    for (const child of walkElements(element.props.children)) {
+        const treeChild = child;
+        if (treeChild.type === "tree-documentation") {
+            result.push(treeChild);
+        }
+        else if (treeChild.type === "tree-directory" || treeChild.type === "tree-file") {
+            result.push(..._collectChildren(treeChild));
+        }
+    }
+    return result;
+}

package/extract/PackageExtractor.d.ts

@@ -0,0 +1,43 @@
+import { type DirectoryElement } from "../util/element.js";
+import { type AbsolutePath, type Path } from "../util/path.js";
+import { Extractor } from "./Extractor.js";
+import { ModuleExtractor } from "./ModuleExtractor.js";
+/** Options for a `PackageExtractor`. */
+export interface PackageExtractorOptions {
+    /**
+     * Pre-extracted source tree the `package.json` exports resolve against — typically the result of
+     * `IndexFileExtractor(MergingExtractor(DirectoryExtractor()))` over the source root.
+     */
+    readonly tree: DirectoryElement;
+    /**
+     * Source-file extensions tried when resolving an export's last segment to a source file (e.g. `./util/string` → `string.ts`, `string.tsx`, …).
+     * - Checked in declaration order; first match wins.
+     * - Defaults to `["ts", "tsx", "js", "jsx"]`.
+     */
+    readonly extensions?: readonly string[];
+    /** `ModuleExtractor` used to build each module element. Defaults to a fresh `new ModuleExtractor()`. */
+    readonly module?: ModuleExtractor;
+    /** Absolute base path used to resolve a relative `package.json` path passed to `extract()`. */
+    readonly base?: AbsolutePath;
+}
+/**
+ * Extractor that reads a `package.json` and produces a flat tree of modules — one `kind: "module"`
+ * `DocumentationElement` per export entry, in declaration order.
+ * - Static export keys (e.g. `"./api"`, `"./firestore/client"`) become one module each.
+ * - Wildcard export keys (e.g. `"./util/*"`) expand against the source tree — one module per matching child file (with
+ *   an extension in `extensions`) or subdirectory.
+ * - The `"."` root export is skipped — its content is the root tree element itself.
+ * - Throws if a static export key has no matching source element in the tree.
+ */
+export declare class PackageExtractor extends Extractor<Path, DirectoryElement> {
+    private readonly _tree;
+    private readonly _extensions;
+    private readonly _module;
+    private readonly _base;
+    constructor({ tree, extensions, module, base }: PackageExtractorOptions);
+    extract(packageJson: Path): Promise<DirectoryElement>;
+    /** Resolve a static export subpath (e.g. `"firestore/client"`) to a file or directory element in the tree. */
+    private _resolve;
+    /** Expand a wildcard export subpath (e.g. `"util/*"`) into one module per matching child. */
+    private _expandWildcard;
+}