shelving 1.241.0 → 1.242.1

package/extract/DirectoryExtractor.d.ts

@@ -32,10 +32,7 @@ export interface DirectoryExtractorOptions {
  * - This is a pure walker: same-key merging and README absorption are intentionally *not* applied here — wrap with `MergingExtractor`
  *   and/or `IndexExtractor` to opt in to those behaviours.
  *
- * @example
- * ```ts
- * const tree = await new DirectoryExtractor().extract("modules/util");
- * ```
+ * @example const tree = await new DirectoryExtractor().extract("modules/util");
  *
  * @see https://dhoulb.github.io/shelving/extract/DirectoryExtractor
  */
@@ -48,10 +45,7 @@ export declare class DirectoryExtractor extends Extractor<Path, TreeElement> {
      *
      * @param options Options including the `extractors` dispatch table, `base` path, and `ignore` patterns.
      *
-     * @example
-     * ```ts
-     * const extractor = new DirectoryExtractor({ base: "/repo/modules" });
-     * ```
+     * @example const extractor = new DirectoryExtractor({ base: "/repo/modules" });
      */
     constructor({ extractors, base, ignore }?: DirectoryExtractorOptions);
     /**
@@ -60,10 +54,7 @@ export declare class DirectoryExtractor extends Extractor<Path, TreeElement> {
      * @param source Path of the directory to walk — resolved against the configured `base`.
      * @returns Promise of the root `tree-element` for the walked directory.
      *
-     * @example
-     * ```ts
-     * const tree = await new DirectoryExtractor().extract("modules/util");
-     * ```
+     * @example const tree = await new DirectoryExtractor().extract("modules/util");
      *
      * @see https://dhoulb.github.io/shelving/extract/DirectoryExtractor/extract
      */

package/extract/DirectoryExtractor.js

@@ -27,10 +27,7 @@ const DEFAULT_IGNORE = [/\.test\.tsx?$/i, /\.spec\.tsx?$/i, /^node_modules$/i, /
  * - This is a pure walker: same-key merging and README absorption are intentionally *not* applied here — wrap with `MergingExtractor`
  *   and/or `IndexExtractor` to opt in to those behaviours.
  *
- * @example
- * ```ts
- * const tree = await new DirectoryExtractor().extract("modules/util");
- * ```
+ * @example const tree = await new DirectoryExtractor().extract("modules/util");
  *
  * @see https://dhoulb.github.io/shelving/extract/DirectoryExtractor
  */
@@ -43,10 +40,7 @@ export class DirectoryExtractor extends Extractor {
      *
      * @param options Options including the `extractors` dispatch table, `base` path, and `ignore` patterns.
      *
-     * @example
-     * ```ts
-     * const extractor = new DirectoryExtractor({ base: "/repo/modules" });
-     * ```
+     * @example const extractor = new DirectoryExtractor({ base: "/repo/modules" });
      */
     constructor({ extractors = DEFAULT_EXTRACTORS, base, ignore = DEFAULT_IGNORE } = {}) {
         super();
@@ -60,10 +54,7 @@ export class DirectoryExtractor extends Extractor {
      * @param source Path of the directory to walk — resolved against the configured `base`.
      * @returns Promise of the root `tree-element` for the walked directory.
      *
-     * @example
-     * ```ts
-     * const tree = await new DirectoryExtractor().extract("modules/util");
-     * ```
+     * @example const tree = await new DirectoryExtractor().extract("modules/util");
      *
      * @see https://dhoulb.github.io/shelving/extract/DirectoryExtractor/extract
      */

package/extract/IndexExtractor.d.ts

@@ -21,10 +21,7 @@ export interface IndexExtractorOptions {
  * - The matched child is removed from the parent's children list.
  * - Purely name-based: it doesn't care whether an element is a directory or a file — any element with children is processed, deepest level first.
  *
- * @example
- * ```ts
- * const extractor = new IndexExtractor(new DirectoryExtractor());
- * ```
+ * @example const extractor = new IndexExtractor(new DirectoryExtractor());
  *
  * @see https://dhoulb.github.io/shelving/extract/IndexExtractor
  */
@@ -36,10 +33,7 @@ export declare class IndexExtractor<I> extends ThroughExtractor<I, TreeElement>
      * @param source Upstream extractor that produces the `tree-element` tree to process.
      * @param options Options including the `index` filename patterns.
      *
-     * @example
-     * ```ts
-     * const extractor = new IndexExtractor(new DirectoryExtractor());
-     * ```
+     * @example const extractor = new IndexExtractor(new DirectoryExtractor());
      */
     constructor(source: Extractor<I, TreeElement>, { index }?: IndexExtractorOptions);
     /**
@@ -48,10 +42,7 @@ export declare class IndexExtractor<I> extends ThroughExtractor<I, TreeElement>
      * @param input Input forwarded to the wrapped source extractor.
      * @returns The source tree with index children folded into their parents.
      *
-     * @example
-     * ```ts
-     * const tree = await new IndexExtractor(source).extract(input);
-     * ```
+     * @example const tree = await new IndexExtractor(source).extract(input);
      *
      * @see https://dhoulb.github.io/shelving/extract/IndexExtractor/extract
      */

package/extract/IndexExtractor.js

@@ -15,10 +15,7 @@ const DEFAULT_INDEX = [/^readme\.txt$/i, /^readme\.md$/i, /^index\.md$/i, /^inde
  * - The matched child is removed from the parent's children list.
  * - Purely name-based: it doesn't care whether an element is a directory or a file — any element with children is processed, deepest level first.
  *
- * @example
- * ```ts
- * const extractor = new IndexExtractor(new DirectoryExtractor());
- * ```
+ * @example const extractor = new IndexExtractor(new DirectoryExtractor());
  *
  * @see https://dhoulb.github.io/shelving/extract/IndexExtractor
  */
@@ -30,10 +27,7 @@ export class IndexExtractor extends ThroughExtractor {
      * @param source Upstream extractor that produces the `tree-element` tree to process.
      * @param options Options including the `index` filename patterns.
      *
-     * @example
-     * ```ts
-     * const extractor = new IndexExtractor(new DirectoryExtractor());
-     * ```
+     * @example const extractor = new IndexExtractor(new DirectoryExtractor());
      */
     constructor(source, { index = DEFAULT_INDEX } = {}) {
         super(source);
@@ -45,10 +39,7 @@ export class IndexExtractor extends ThroughExtractor {
      * @param input Input forwarded to the wrapped source extractor.
      * @returns The source tree with index children folded into their parents.
      *
-     * @example
-     * ```ts
-     * const tree = await new IndexExtractor(source).extract(input);
-     * ```
+     * @example const tree = await new IndexExtractor(source).extract(input);
      *
      * @see https://dhoulb.github.io/shelving/extract/IndexExtractor/extract
      */

package/extract/MergingExtractor.d.ts

@@ -26,10 +26,7 @@ export interface MergingExtractorOptions {
  *   `content`, and `children` are folded in via `mergeTreeElements()`.
  * - A secondary with no matching token or file is left in place — pure prose files (e.g. `concepts.md` with no `concepts.ts`) stand alone.
  *
- * @example
- * ```ts
- * const extractor = new MergingExtractor(new DirectoryExtractor());
- * ```
+ * @example const extractor = new MergingExtractor(new DirectoryExtractor());
  *
  * @see https://dhoulb.github.io/shelving/extract/MergingExtractor
  */
@@ -41,10 +38,7 @@ export declare class MergingExtractor<I> extends ThroughExtractor<I, TreeElement
      * @param source Upstream extractor that produces the `tree-element` tree to merge.
      * @param options Options including the `merges` template map.
      *
-     * @example
-     * ```ts
-     * const extractor = new MergingExtractor(new DirectoryExtractor());
-     * ```
+     * @example const extractor = new MergingExtractor(new DirectoryExtractor());
      */
     constructor(source: Extractor<I, TreeElement>, { merges }?: MergingExtractorOptions);
     /**
@@ -53,10 +47,7 @@ export declare class MergingExtractor<I> extends ThroughExtractor<I, TreeElement
      * @param input Input forwarded to the wrapped source extractor.
      * @returns The source tree with matching sibling elements merged together.
      *
-     * @example
-     * ```ts
-     * const tree = await new MergingExtractor(source).extract(input);
-     * ```
+     * @example const tree = await new MergingExtractor(source).extract(input);
      *
      * @see https://dhoulb.github.io/shelving/extract/MergingExtractor/extract
      */

package/extract/MergingExtractor.js

@@ -21,10 +21,7 @@ const DEFAULT_MERGES = {
  *   `content`, and `children` are folded in via `mergeTreeElements()`.
  * - A secondary with no matching token or file is left in place — pure prose files (e.g. `concepts.md` with no `concepts.ts`) stand alone.
  *
- * @example
- * ```ts
- * const extractor = new MergingExtractor(new DirectoryExtractor());
- * ```
+ * @example const extractor = new MergingExtractor(new DirectoryExtractor());
  *
  * @see https://dhoulb.github.io/shelving/extract/MergingExtractor
  */
@@ -36,10 +33,7 @@ export class MergingExtractor extends ThroughExtractor {
      * @param source Upstream extractor that produces the `tree-element` tree to merge.
      * @param options Options including the `merges` template map.
      *
-     * @example
-     * ```ts
-     * const extractor = new MergingExtractor(new DirectoryExtractor());
-     * ```
+     * @example const extractor = new MergingExtractor(new DirectoryExtractor());
      */
     constructor(source, { merges = DEFAULT_MERGES } = {}) {
         super(source);
@@ -51,10 +45,7 @@ export class MergingExtractor extends ThroughExtractor {
      * @param input Input forwarded to the wrapped source extractor.
      * @returns The source tree with matching sibling elements merged together.
      *
-     * @example
-     * ```ts
-     * const tree = await new MergingExtractor(source).extract(input);
-     * ```
+     * @example const tree = await new MergingExtractor(source).extract(input);
      *
      * @see https://dhoulb.github.io/shelving/extract/MergingExtractor/extract
      */

package/extract/ModuleExtractor.d.ts

@@ -22,10 +22,7 @@ export interface ModuleExtractorInput {
  * - 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.
  *
- * @example
- * ```ts
- * const module = new ModuleExtractor().extract({ name: "util/string", source });
- * ```
+ * @example const module = new ModuleExtractor().extract({ name: "util/string", source });
  *
  * @see https://dhoulb.github.io/shelving/extract/ModuleExtractor
  */
@@ -36,10 +33,7 @@ export declare class ModuleExtractor extends Extractor<ModuleExtractorInput, Doc
      * @param input Module name and source element to build from.
      * @returns `tree-documentation` element of `kind: "module"` with flattened documented children.
      *
-     * @example
-     * ```ts
-     * const module = new ModuleExtractor().extract({ name: "util/string", source });
-     * ```
+     * @example const module = new ModuleExtractor().extract({ name: "util/string", source });
      *
      * @see https://dhoulb.github.io/shelving/extract/ModuleExtractor/extract
      */

package/extract/ModuleExtractor.js

@@ -8,10 +8,7 @@ import { Extractor } from "./Extractor.js";
  * - 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.
  *
- * @example
- * ```ts
- * const module = new ModuleExtractor().extract({ name: "util/string", source });
- * ```
+ * @example const module = new ModuleExtractor().extract({ name: "util/string", source });
  *
  * @see https://dhoulb.github.io/shelving/extract/ModuleExtractor
  */
@@ -22,10 +19,7 @@ export class ModuleExtractor extends Extractor {
      * @param input Module name and source element to build from.
      * @returns `tree-documentation` element of `kind: "module"` with flattened documented children.
      *
-     * @example
-     * ```ts
-     * const module = new ModuleExtractor().extract({ name: "util/string", source });
-     * ```
+     * @example const module = new ModuleExtractor().extract({ name: "util/string", source });
      *
      * @see https://dhoulb.github.io/shelving/extract/ModuleExtractor/extract
      */

package/extract/PackageExtractor.d.ts

@@ -35,10 +35,7 @@ export interface PackageExtractorOptions {
  * - 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.
  *
- * @example
- * ```ts
- * const tree = await new PackageExtractor({ tree: sourceTree }).extract("package.json");
- * ```
+ * @example const tree = await new PackageExtractor({ tree: sourceTree }).extract("package.json");
  *
  * @see https://dhoulb.github.io/shelving/extract/PackageExtractor
  */
@@ -52,10 +49,7 @@ export declare class PackageExtractor extends Extractor<Path, TreeElement> {
      *
      * @param options Options including the source `tree`, `extensions` mapping, `module` extractor, and `base` path.
      *
-     * @example
-     * ```ts
-     * const extractor = new PackageExtractor({ tree: sourceTree });
-     * ```
+     * @example const extractor = new PackageExtractor({ tree: sourceTree });
      */
     constructor({ tree, extensions, module, base }: PackageExtractorOptions);
     /**
@@ -65,10 +59,7 @@ export declare class PackageExtractor extends Extractor<Path, TreeElement> {
      * @returns Promise of the root `tree-element` whose children are the module elements.
      * @throws Error If a static export key has no matching source element in the tree, or a wildcard export is malformed.
      *
-     * @example
-     * ```ts
-     * const tree = await new PackageExtractor({ tree: sourceTree }).extract("package.json");
-     * ```
+     * @example const tree = await new PackageExtractor({ tree: sourceTree }).extract("package.json");
      *
      * @see https://dhoulb.github.io/shelving/extract/PackageExtractor/extract
      */

package/extract/PackageExtractor.js

@@ -19,10 +19,7 @@ const DEFAULT_EXTENSIONS = {
  * - 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.
  *
- * @example
- * ```ts
- * const tree = await new PackageExtractor({ tree: sourceTree }).extract("package.json");
- * ```
+ * @example const tree = await new PackageExtractor({ tree: sourceTree }).extract("package.json");
  *
  * @see https://dhoulb.github.io/shelving/extract/PackageExtractor
  */
@@ -36,10 +33,7 @@ export class PackageExtractor extends Extractor {
      *
      * @param options Options including the source `tree`, `extensions` mapping, `module` extractor, and `base` path.
      *
-     * @example
-     * ```ts
-     * const extractor = new PackageExtractor({ tree: sourceTree });
-     * ```
+     * @example const extractor = new PackageExtractor({ tree: sourceTree });
      */
     constructor({ tree, extensions = DEFAULT_EXTENSIONS, module = new ModuleExtractor(), base }) {
         super();
@@ -55,10 +49,7 @@ export class PackageExtractor extends Extractor {
      * @returns Promise of the root `tree-element` whose children are the module elements.
      * @throws Error If a static export key has no matching source element in the tree, or a wildcard export is malformed.
      *
-     * @example
-     * ```ts
-     * const tree = await new PackageExtractor({ tree: sourceTree }).extract("package.json");
-     * ```
+     * @example const tree = await new PackageExtractor({ tree: sourceTree }).extract("package.json");
      *
      * @see https://dhoulb.github.io/shelving/extract/PackageExtractor/extract
      */

package/extract/TypescriptExtractor.d.ts

@@ -7,18 +7,14 @@ import { FileExtractor } from "./FileExtractor.js";
  * - Overloaded declarations sharing a name are merged into a single `tree-documentation` with multiple `signatures`.
  * - Class declarations synthesise their `signatures`, `params`, and `returns` from the constructor — `new ClassName<…>(…)` including generics, one signature per constructor overload, with `returns` set to the class type. Param descriptions come from the constructor's `@param` first, then the class's `@param`.
  * - A `@kind` tag in a symbol's JSDoc overrides the inferred kind — e.g. `@kind component` relabels a React component (otherwise a `function`) so the docs site groups and colours it as a component. The override also drops the trailing `()` from the title, since a non-function kind reads as a bare name.
- * - Top-of-file JSDoc comment becomes the file's `content`.
- * - Sets `description` (a plain-text summary from the first JSDoc paragraph) on the file and every `tree-documentation` child.
- * - Sets `title` on every `tree-documentation` child — `name()` for functions and methods, bare `name` for other kinds. Parent class context comes from the `class` prop ("member of …" affordance), never the title.
+ * - Sets `description` (a plain-text summary from the first JSDoc paragraph) on every `tree-documentation` child.
+ * - Sets `title` on every `tree-documentation` child — `name()` for functions, `Class.name()` for methods, `Class.name` for properties, bare `name` for other kinds.
  * - Records relational metadata as raw strings for render-time linking: `class` (owning class), `readonly`, `extends`, `implements`.
  * - Members declared with the `override` or `declare` modifier are skipped — the base class already documents overrides, and `declare` members are ambient type-only re-declarations rather than new API.
  * - Keys are the raw declared `name` (case-preserving) so case-distinct exports like `Collection` and `COLLECTION` stay separate.
  * - The file element itself has no `title` — a TS source file has no confident title source; renderers fall back to `name`.
  *
- * @example
- * ```ts
- * const element = new TypescriptExtractor().extractProps("string.ts", sourceText);
- * ```
+ * @example const element = new TypescriptExtractor().extractProps("string.ts", sourceText);
  *
  * @see https://dhoulb.github.io/shelving/extract/TypescriptExtractor
  */
@@ -30,10 +26,7 @@ export declare class TypescriptExtractor extends FileExtractor {
      * @param text Full TypeScript source text to parse.
      * @returns Partial `tree-element` props with `name`, `description`, `content`, and `children`.
      *
-     * @example
-     * ```ts
-     * const props = new TypescriptExtractor().extractProps("string.ts", sourceText);
-     * ```
+     * @example const props = new TypescriptExtractor().extractProps("string.ts", sourceText);
      *
      * @see https://dhoulb.github.io/shelving/extract/TypescriptExtractor/extractProps
      */