@rodavel/vite-plugin-content-tree 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,277 @@
+import { Plugin } from 'vite';
+
+declare const INDEX_SUFFIX = "/index";
+declare const DEFAULT_META_FILE = "_meta.json";
+declare const DEFAULT_PAGE_FILE = "index.mdx";
+declare const DEFAULT_ORDER = 999;
+
+/** Index page associated with a directory node. */
+interface ContentTreeIndexNode {
+    type: "page";
+    name: string;
+    url: string;
+    id: string;
+}
+/** A page node in the content tree. */
+interface ContentTreePageNode {
+    type: "page";
+    name: string;
+    id: string;
+    url: string;
+    order: number;
+}
+/** A directory node in the content tree. */
+interface ContentTreeDirectoryNode {
+    type: "directory";
+    name: string;
+    id: string;
+    children: ContentTreeNode[];
+    index?: ContentTreeIndexNode;
+    order: number;
+}
+/** A node in the content tree — either a page or a directory. */
+type ContentTreeNode = ContentTreePageNode | ContentTreeDirectoryNode;
+/** Recursive type that strips the `order` field from a tree node and its descendants. */
+type WithoutOrder = {
+    type: "page";
+    name: string;
+    id: string;
+    url: string;
+} | {
+    type: "directory";
+    name: string;
+    id: string;
+    children: WithoutOrder[];
+    index?: ContentTreeIndexNode;
+};
+/** Minimal frontmatter fields used by the core scanning logic. */
+interface BaseFrontmatter {
+    title: string;
+    description?: string;
+    order?: number;
+    nav?: string;
+}
+/** What a `mapFrontmatter` callback must return. */
+interface FrontmatterResult {
+    title: string;
+    description?: string;
+    nav?: string;
+    order?: number;
+    /** Arbitrary extra fields that flow into `ScannedPage.extra`. */
+    extra?: Record<string, unknown>;
+}
+/** A parsed content page with extracted metadata. */
+interface ScannedPage {
+    key: string;
+    title: string;
+    description?: string;
+    nav?: string;
+    order: number;
+    file: string;
+    segments: string[];
+    extra?: Record<string, unknown>;
+}
+/** Metadata read from a directory's `_meta.json` file. */
+interface DirectoryMeta {
+    name?: string;
+    order?: number;
+    /** Arbitrary extra fields from the metadata file that aren't part of the base schema. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Resolves the display label for a directory node in the content tree.
+ *
+ * @param dirName - The raw directory name (slug)
+ * @param meta - Parsed metadata from the directory's `_meta.json` file
+ * @param indexPage - The index page for this directory, if one exists
+ * @param acronyms - Set of words to fully uppercase when humanizing
+ * @returns The display label for the directory node
+ */
+type DirectoryLabelResolver = (dirName: string, meta: DirectoryMeta, indexPage: ScannedPage | undefined, acronyms: Set<string>) => string;
+/**
+ * Maps raw frontmatter data to the fields used by the content tree.
+ *
+ * @param raw - The parsed frontmatter object from gray-matter
+ * @param file - The relative file path (for error messages or conditional logic)
+ * @returns The extracted frontmatter fields
+ */
+type FrontmatterMapper = (raw: Record<string, unknown>, file: string) => FrontmatterResult;
+/**
+ * Post-processes scanned pages before tree building.
+ * Use this to enrich pages with computed fields (e.g., resolving module names from ancestors).
+ */
+type PageEnricher = (pages: ScannedPage[], pageByKey: Map<string, ScannedPage>) => void;
+/**
+ * Maps a scanned page to the object shape written to the generated output file.
+ * The returned object is serialized as a value in the `pages` Map.
+ */
+type PageEntryMapper = (page: ScannedPage) => Record<string, unknown>;
+/** Configuration for the content tree generator. */
+interface ContentTreeGeneratorOptions {
+    /** Path to the content directory to scan. */
+    docsDir: string;
+    /** Path where the generated TypeScript file is written. */
+    outFile: string;
+    /** URL prefix prepended to page paths (e.g., `"/docs"`). */
+    urlPrefix: string;
+    /** Display name for the root tree object (e.g., `"Docs"`). */
+    treeName: string;
+    /** If provided, wraps top-level children in a synthetic root directory node. */
+    root?: {
+        name: string;
+        id: string;
+    };
+    /** Type to import in the generated file for the tree variable. */
+    treeType?: {
+        from: string;
+        name: string;
+    };
+    /** Type to import in the generated file for the pages Map values. */
+    pageType?: {
+        from: string;
+        name: string;
+    };
+    /** Export name for the pages Map. @default "pages" */
+    pagesExportName?: string;
+    /** Export name for the tree object. @default "docsTree" */
+    treeExportName?: string;
+    /** Acronyms to uppercase when humanizing directory names. */
+    acronyms?: string[] | Set<string>;
+    /** Filename for directory metadata. @default "_meta.json" */
+    metaFile?: string;
+    /** Filename to match as a page entry. @default "index.mdx" */
+    pageFile?: string;
+    /** Custom frontmatter mapper. The default handles `BaseFrontmatter` fields plus `module` in `extra`. */
+    mapFrontmatter?: FrontmatterMapper;
+    /**
+     * Post-processes pages after scanning.
+     * @default no-op — pass `resolveModules` to enable module resolution from ancestors.
+     */
+    enrichPages?: PageEnricher;
+    /** Customizes the per-page entry shape in the generated output. */
+    mapPageEntry?: PageEntryMapper;
+    /**
+     * Resolves the display label for directory nodes.
+     * @default Falls back to `extra.module` → `meta.name` → `humanize(dirName)`.
+     */
+    resolveDirectoryLabel?: DirectoryLabelResolver;
+}
+
+interface GenerateDataResult {
+    pages: ScannedPage[];
+    tree: WithoutOrder;
+}
+/**
+ * Runs the full scan → enrich → build pipeline and returns the raw data
+ * without writing any files.
+ *
+ * @param opts - Generator configuration
+ * @returns The scanned pages and the built tree (with order fields stripped)
+ */
+declare function generateData(opts: ContentTreeGeneratorOptions): Promise<GenerateDataResult>;
+/**
+ * Writes the generated data to a TypeScript file using the configured template.
+ *
+ * @param opts - Generator configuration (controls export names, type imports, page entry shape)
+ * @param data - The data to serialize (from `generateData`)
+ */
+declare function writeOutput(opts: ContentTreeGeneratorOptions, data: GenerateDataResult): Promise<void>;
+/**
+ * Generates the content tree data and writes it to the configured output file.
+ *
+ * @param opts - Generator configuration
+ */
+declare function generate(opts: ContentTreeGeneratorOptions): Promise<void>;
+
+/**
+ * Vite plugin that scans a content directory, extracts frontmatter,
+ * and generates a typed navigation tree + page index as a TypeScript file.
+ *
+ * Runs at build start and watches for changes during dev.
+ *
+ * @param opts - Generator configuration
+ * @returns A Vite plugin
+ */
+declare function contentTreeGeneratorPlugin(opts: ContentTreeGeneratorOptions): Plugin;
+
+/**
+ * Default frontmatter mapper that extracts base fields and passes
+ * all remaining fields through as `extra`.
+ */
+declare const defaultMapFrontmatter: FrontmatterMapper;
+/**
+ * Reads and parses a directory metadata file (e.g., `_meta.json`).
+ *
+ * @param docsDir - Root content directory path
+ * @param dirPath - Relative path to the directory within docsDir
+ * @param metaFile - Name of the metadata file to look for
+ * @returns Parsed metadata or an empty object if the file doesn't exist
+ */
+declare function readDirectoryMeta(docsDir: string, dirPath: string, metaFile: string): Promise<DirectoryMeta>;
+/**
+ * Recursively scans a content directory for page files, extracts frontmatter,
+ * and returns an array of scanned pages.
+ *
+ * @param docsDir - Root content directory to scan
+ * @param pageFile - Filename to match as a page entry (e.g., `"index.mdx"`)
+ * @param mapFrontmatter - Callback to extract fields from raw frontmatter data
+ * @returns Array of scanned pages with extracted metadata
+ */
+declare function scanPages(docsDir: string, pageFile: string, mapFrontmatter?: FrontmatterMapper): Promise<ScannedPage[]>;
+/**
+ * Resolves the `extra.module` field for each page by looking up its module-root ancestor.
+ * Pages inherit the module from the root page of their first path segment.
+ *
+ * This is the default `enrichPages` implementation.
+ */
+declare function resolveModules(pages: ScannedPage[], pageByKey: Map<string, ScannedPage>): void;
+
+/** Pre-computed index that groups pages by parent path for O(1) lookups during tree building. */
+interface PageIndex {
+    directChildren: Map<string, ScannedPage[]>;
+    subDirNames: Map<string, Set<string>>;
+}
+/** Context threaded through recursive `buildChildren` calls. */
+interface BuildContext {
+    pageIndex: PageIndex;
+    metas: Map<string, DirectoryMeta>;
+    urlPrefix: string;
+    acronyms: Set<string>;
+    resolveDirectoryLabel: DirectoryLabelResolver;
+}
+/**
+ * Pre-groups pages into a lookup index so `buildChildren` can avoid
+ * re-filtering the full page list at every recursion level.
+ *
+ * @param pages - All scanned pages (root page with key="" is excluded from grouping)
+ * @returns A `PageIndex` with O(1) lookups by parent path
+ */
+declare function buildPageIndex(pages: ScannedPage[]): PageIndex;
+/**
+ * Converts a kebab-case slug to Title Case, uppercasing known acronyms.
+ *
+ * @param slug - The slug to humanize (e.g., `"ses-api-reference"`)
+ * @param acronyms - Set of words to fully uppercase (e.g., `"ses"` → `"SES"`)
+ * @returns The humanized string (e.g., `"SES API Reference"`)
+ */
+declare function humanize(slug: string, acronyms: Set<string>): string;
+/**
+ * Default directory label resolver.
+ * Falls back through: `extra.module` → `meta.name` → `humanize(dirName)`.
+ */
+declare const defaultResolveDirectoryLabel: DirectoryLabelResolver;
+/**
+ * Recursively builds a sorted array of child nodes for a given parent path.
+ *
+ * @param parentPath - The key prefix for the parent (empty string for root)
+ * @param ctx - Build context with shared configuration and pre-scanned metadata
+ * @returns Sorted array of tree nodes
+ */
+declare function buildChildren(parentPath: string, ctx: BuildContext): ContentTreeNode[];
+/**
+ * Recursively removes the `order` field from a tree node and all its descendants.
+ * The `order` field is only used for sorting and is not needed in the final output.
+ */
+declare function stripOrder(node: ContentTreeNode): WithoutOrder;
+
+export { type BaseFrontmatter, type BuildContext, type ContentTreeDirectoryNode, type ContentTreeGeneratorOptions, type ContentTreeIndexNode, type ContentTreeNode, type ContentTreePageNode, DEFAULT_META_FILE, DEFAULT_ORDER, DEFAULT_PAGE_FILE, type DirectoryLabelResolver, type DirectoryMeta, type FrontmatterMapper, type FrontmatterResult, type GenerateDataResult, INDEX_SUFFIX, type PageEnricher, type PageEntryMapper, type PageIndex, type ScannedPage, type WithoutOrder, buildChildren, buildPageIndex, contentTreeGeneratorPlugin, defaultMapFrontmatter, defaultResolveDirectoryLabel, generate, generateData, humanize, readDirectoryMeta, resolveModules, scanPages, stripOrder, writeOutput };

package/dist/index.d.ts

@@ -0,0 +1,277 @@
+import { Plugin } from 'vite';
+
+declare const INDEX_SUFFIX = "/index";
+declare const DEFAULT_META_FILE = "_meta.json";
+declare const DEFAULT_PAGE_FILE = "index.mdx";
+declare const DEFAULT_ORDER = 999;
+
+/** Index page associated with a directory node. */
+interface ContentTreeIndexNode {
+    type: "page";
+    name: string;
+    url: string;
+    id: string;
+}
+/** A page node in the content tree. */
+interface ContentTreePageNode {
+    type: "page";
+    name: string;
+    id: string;
+    url: string;
+    order: number;
+}
+/** A directory node in the content tree. */
+interface ContentTreeDirectoryNode {
+    type: "directory";
+    name: string;
+    id: string;
+    children: ContentTreeNode[];
+    index?: ContentTreeIndexNode;
+    order: number;
+}
+/** A node in the content tree — either a page or a directory. */
+type ContentTreeNode = ContentTreePageNode | ContentTreeDirectoryNode;
+/** Recursive type that strips the `order` field from a tree node and its descendants. */
+type WithoutOrder = {
+    type: "page";
+    name: string;
+    id: string;
+    url: string;
+} | {
+    type: "directory";
+    name: string;
+    id: string;
+    children: WithoutOrder[];
+    index?: ContentTreeIndexNode;
+};
+/** Minimal frontmatter fields used by the core scanning logic. */
+interface BaseFrontmatter {
+    title: string;
+    description?: string;
+    order?: number;
+    nav?: string;
+}
+/** What a `mapFrontmatter` callback must return. */
+interface FrontmatterResult {
+    title: string;
+    description?: string;
+    nav?: string;
+    order?: number;
+    /** Arbitrary extra fields that flow into `ScannedPage.extra`. */
+    extra?: Record<string, unknown>;
+}
+/** A parsed content page with extracted metadata. */
+interface ScannedPage {
+    key: string;
+    title: string;
+    description?: string;
+    nav?: string;
+    order: number;
+    file: string;
+    segments: string[];
+    extra?: Record<string, unknown>;
+}
+/** Metadata read from a directory's `_meta.json` file. */
+interface DirectoryMeta {
+    name?: string;
+    order?: number;
+    /** Arbitrary extra fields from the metadata file that aren't part of the base schema. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Resolves the display label for a directory node in the content tree.
+ *
+ * @param dirName - The raw directory name (slug)
+ * @param meta - Parsed metadata from the directory's `_meta.json` file
+ * @param indexPage - The index page for this directory, if one exists
+ * @param acronyms - Set of words to fully uppercase when humanizing
+ * @returns The display label for the directory node
+ */
+type DirectoryLabelResolver = (dirName: string, meta: DirectoryMeta, indexPage: ScannedPage | undefined, acronyms: Set<string>) => string;
+/**
+ * Maps raw frontmatter data to the fields used by the content tree.
+ *
+ * @param raw - The parsed frontmatter object from gray-matter
+ * @param file - The relative file path (for error messages or conditional logic)
+ * @returns The extracted frontmatter fields
+ */
+type FrontmatterMapper = (raw: Record<string, unknown>, file: string) => FrontmatterResult;
+/**
+ * Post-processes scanned pages before tree building.
+ * Use this to enrich pages with computed fields (e.g., resolving module names from ancestors).
+ */
+type PageEnricher = (pages: ScannedPage[], pageByKey: Map<string, ScannedPage>) => void;
+/**
+ * Maps a scanned page to the object shape written to the generated output file.
+ * The returned object is serialized as a value in the `pages` Map.
+ */
+type PageEntryMapper = (page: ScannedPage) => Record<string, unknown>;
+/** Configuration for the content tree generator. */
+interface ContentTreeGeneratorOptions {
+    /** Path to the content directory to scan. */
+    docsDir: string;
+    /** Path where the generated TypeScript file is written. */
+    outFile: string;
+    /** URL prefix prepended to page paths (e.g., `"/docs"`). */
+    urlPrefix: string;
+    /** Display name for the root tree object (e.g., `"Docs"`). */
+    treeName: string;
+    /** If provided, wraps top-level children in a synthetic root directory node. */
+    root?: {
+        name: string;
+        id: string;
+    };
+    /** Type to import in the generated file for the tree variable. */
+    treeType?: {
+        from: string;
+        name: string;
+    };
+    /** Type to import in the generated file for the pages Map values. */
+    pageType?: {
+        from: string;
+        name: string;
+    };
+    /** Export name for the pages Map. @default "pages" */
+    pagesExportName?: string;
+    /** Export name for the tree object. @default "docsTree" */
+    treeExportName?: string;
+    /** Acronyms to uppercase when humanizing directory names. */
+    acronyms?: string[] | Set<string>;
+    /** Filename for directory metadata. @default "_meta.json" */
+    metaFile?: string;
+    /** Filename to match as a page entry. @default "index.mdx" */
+    pageFile?: string;
+    /** Custom frontmatter mapper. The default handles `BaseFrontmatter` fields plus `module` in `extra`. */
+    mapFrontmatter?: FrontmatterMapper;
+    /**
+     * Post-processes pages after scanning.
+     * @default no-op — pass `resolveModules` to enable module resolution from ancestors.
+     */
+    enrichPages?: PageEnricher;
+    /** Customizes the per-page entry shape in the generated output. */
+    mapPageEntry?: PageEntryMapper;
+    /**
+     * Resolves the display label for directory nodes.
+     * @default Falls back to `extra.module` → `meta.name` → `humanize(dirName)`.
+     */
+    resolveDirectoryLabel?: DirectoryLabelResolver;
+}
+
+interface GenerateDataResult {
+    pages: ScannedPage[];
+    tree: WithoutOrder;
+}
+/**
+ * Runs the full scan → enrich → build pipeline and returns the raw data
+ * without writing any files.
+ *
+ * @param opts - Generator configuration
+ * @returns The scanned pages and the built tree (with order fields stripped)
+ */
+declare function generateData(opts: ContentTreeGeneratorOptions): Promise<GenerateDataResult>;
+/**
+ * Writes the generated data to a TypeScript file using the configured template.
+ *
+ * @param opts - Generator configuration (controls export names, type imports, page entry shape)
+ * @param data - The data to serialize (from `generateData`)
+ */
+declare function writeOutput(opts: ContentTreeGeneratorOptions, data: GenerateDataResult): Promise<void>;
+/**
+ * Generates the content tree data and writes it to the configured output file.
+ *
+ * @param opts - Generator configuration
+ */
+declare function generate(opts: ContentTreeGeneratorOptions): Promise<void>;
+
+/**
+ * Vite plugin that scans a content directory, extracts frontmatter,
+ * and generates a typed navigation tree + page index as a TypeScript file.
+ *
+ * Runs at build start and watches for changes during dev.
+ *
+ * @param opts - Generator configuration
+ * @returns A Vite plugin
+ */
+declare function contentTreeGeneratorPlugin(opts: ContentTreeGeneratorOptions): Plugin;
+
+/**
+ * Default frontmatter mapper that extracts base fields and passes
+ * all remaining fields through as `extra`.
+ */
+declare const defaultMapFrontmatter: FrontmatterMapper;
+/**
+ * Reads and parses a directory metadata file (e.g., `_meta.json`).
+ *
+ * @param docsDir - Root content directory path
+ * @param dirPath - Relative path to the directory within docsDir
+ * @param metaFile - Name of the metadata file to look for
+ * @returns Parsed metadata or an empty object if the file doesn't exist
+ */
+declare function readDirectoryMeta(docsDir: string, dirPath: string, metaFile: string): Promise<DirectoryMeta>;
+/**
+ * Recursively scans a content directory for page files, extracts frontmatter,
+ * and returns an array of scanned pages.
+ *
+ * @param docsDir - Root content directory to scan
+ * @param pageFile - Filename to match as a page entry (e.g., `"index.mdx"`)
+ * @param mapFrontmatter - Callback to extract fields from raw frontmatter data
+ * @returns Array of scanned pages with extracted metadata
+ */
+declare function scanPages(docsDir: string, pageFile: string, mapFrontmatter?: FrontmatterMapper): Promise<ScannedPage[]>;
+/**
+ * Resolves the `extra.module` field for each page by looking up its module-root ancestor.
+ * Pages inherit the module from the root page of their first path segment.
+ *
+ * This is the default `enrichPages` implementation.
+ */
+declare function resolveModules(pages: ScannedPage[], pageByKey: Map<string, ScannedPage>): void;
+
+/** Pre-computed index that groups pages by parent path for O(1) lookups during tree building. */
+interface PageIndex {
+    directChildren: Map<string, ScannedPage[]>;
+    subDirNames: Map<string, Set<string>>;
+}
+/** Context threaded through recursive `buildChildren` calls. */
+interface BuildContext {
+    pageIndex: PageIndex;
+    metas: Map<string, DirectoryMeta>;
+    urlPrefix: string;
+    acronyms: Set<string>;
+    resolveDirectoryLabel: DirectoryLabelResolver;
+}
+/**
+ * Pre-groups pages into a lookup index so `buildChildren` can avoid
+ * re-filtering the full page list at every recursion level.
+ *
+ * @param pages - All scanned pages (root page with key="" is excluded from grouping)
+ * @returns A `PageIndex` with O(1) lookups by parent path
+ */
+declare function buildPageIndex(pages: ScannedPage[]): PageIndex;
+/**
+ * Converts a kebab-case slug to Title Case, uppercasing known acronyms.
+ *
+ * @param slug - The slug to humanize (e.g., `"ses-api-reference"`)
+ * @param acronyms - Set of words to fully uppercase (e.g., `"ses"` → `"SES"`)
+ * @returns The humanized string (e.g., `"SES API Reference"`)
+ */
+declare function humanize(slug: string, acronyms: Set<string>): string;
+/**
+ * Default directory label resolver.
+ * Falls back through: `extra.module` → `meta.name` → `humanize(dirName)`.
+ */
+declare const defaultResolveDirectoryLabel: DirectoryLabelResolver;
+/**
+ * Recursively builds a sorted array of child nodes for a given parent path.
+ *
+ * @param parentPath - The key prefix for the parent (empty string for root)
+ * @param ctx - Build context with shared configuration and pre-scanned metadata
+ * @returns Sorted array of tree nodes
+ */
+declare function buildChildren(parentPath: string, ctx: BuildContext): ContentTreeNode[];
+/**
+ * Recursively removes the `order` field from a tree node and all its descendants.
+ * The `order` field is only used for sorting and is not needed in the final output.
+ */
+declare function stripOrder(node: ContentTreeNode): WithoutOrder;
+
+export { type BaseFrontmatter, type BuildContext, type ContentTreeDirectoryNode, type ContentTreeGeneratorOptions, type ContentTreeIndexNode, type ContentTreeNode, type ContentTreePageNode, DEFAULT_META_FILE, DEFAULT_ORDER, DEFAULT_PAGE_FILE, type DirectoryLabelResolver, type DirectoryMeta, type FrontmatterMapper, type FrontmatterResult, type GenerateDataResult, INDEX_SUFFIX, type PageEnricher, type PageEntryMapper, type PageIndex, type ScannedPage, type WithoutOrder, buildChildren, buildPageIndex, contentTreeGeneratorPlugin, defaultMapFrontmatter, defaultResolveDirectoryLabel, generate, generateData, humanize, readDirectoryMeta, resolveModules, scanPages, stripOrder, writeOutput };