sveld 0.32.3 → 0.32.5

package/lib/parse-exports.d.ts

@@ -1,18 +1,11 @@
+import { type RelativeSourcePath } from "./brands";
 export type ParsedExports = Record<string, {
-    source: string;
+    source: RelativeSourcePath;
     default: boolean;
     mixed?: boolean;
 }>;
 /**
- * Parses export statements from JavaScript/TypeScript source code.
- *
- * Extracts all exports (default, named, and re-exports) and resolves
- * their source paths, handling path aliases and directory imports.
- * Caches parsed ASTs for performance.
- *
- * @param source - The source code to parse
- * @param dir - The directory context for resolving relative paths and aliases
- * @returns A map of export names to their source paths and metadata
+ * Parses exports from an entry file and resolves aliases against `dir`.
  *
  * @example
  * ```ts

package/lib/path.d.ts

@@ -1,6 +1,3 @@
-/**
- * Normalize directory separators to always use `/`.
- * @param filePath A file path.
- * @returns Path with normalized separators.
- */
-export declare function normalizeSeparators(filePath: string): string;
+import type { NormalizedPath } from "./brands";
+/** Normalize path separators to `/`. */
+export declare function normalizeSeparators(filePath: string): NormalizedPath;

package/lib/plugin.d.ts

@@ -1,3 +1,4 @@
+import { type NormalizedPath } from "./brands";
 import { type ParsedComponent } from "./ComponentParser";
 import { type ParsedExports } from "./parse-exports";
 import { type WriteJsonOptions } from "./writer/writer-json";
@@ -17,12 +18,11 @@ export interface PluginSveldOptions {
     markdown?: boolean;
     markdownOptions?: Partial<WriteMarkdownOptions>;
 }
-type ComponentModuleName = string;
 export interface ComponentDocApi extends ParsedComponent {
-    filePath: string;
+    filePath: NormalizedPath;
     moduleName: string;
 }
-export type ComponentDocs = Map<ComponentModuleName, ComponentDocApi>;
+export type ComponentDocs = Map<string, ComponentDocApi>;
 interface SveldPlugin {
     name: string;
     apply?: "build" | "serve";

package/lib/resolve-alias.d.ts

@@ -1,20 +1,7 @@
-/**
- * Clears the TypeScript/JavaScript config cache.
- *
- * Useful for testing or when config files are modified during runtime.
- * Forces re-reading of config files on next resolution.
- */
+/** Clears cached tsconfig/jsconfig reads (tests and hot reload). */
 export declare function clearConfigCache(): void;
 /**
- * Resolves a path alias to an absolute file system path for reading files.
- *
- * Uses TypeScript/JavaScript config path mappings to resolve aliases like
- * `$lib/components` to actual file system paths. Handles wildcard patterns
- * and baseUrl resolution.
- *
- * @param importPath - The import path that may contain an alias
- * @param fromDir - The directory to resolve relative to (for finding config)
- * @returns The absolute resolved path, or original path if resolution fails
+ * Resolve a tsconfig/jsconfig path alias to an absolute filesystem path.
  *
  * @example
  * ```ts
@@ -28,15 +15,7 @@ export declare function clearConfigCache(): void;
  */
 export declare function resolvePathAliasAbsolute(importPath: string, fromDir: string): string;
 /**
- * Resolves a path alias and converts it to a relative path from fromDir.
- *
- * This is used for storing paths in the exports object for output generation.
- * Unlike `resolvePathAliasAbsolute`, this returns a relative path suitable
- * for use in generated export statements.
- *
- * @param importPath - The import path that may contain an alias
- * @param fromDir - The directory to resolve relative to
- * @returns A relative path (prefixed with ./ if needed), or original path if resolution fails
+ * Resolve a path alias to a path relative to `fromDir` for generated exports.
  *
  * @example
  * ```ts

package/lib/sveld.d.ts

@@ -1,5 +1,5 @@
 import { type PluginSveldOptions } from "./plugin";
-interface SveldOptions extends PluginSveldOptions {
+interface SveldOptions extends Omit<PluginSveldOptions, "entry"> {
     /**
      * Specify the input to the uncompiled Svelte source.
      * If no value is provided, `sveld` will attempt to infer
@@ -8,14 +8,7 @@ interface SveldOptions extends PluginSveldOptions {
     input?: string;
 }
 /**
- * Main entry point for programmatic sveld usage.
- *
- * Generates component documentation from Svelte source files and writes
- * output files based on the provided options. Can be used as a library
- * in addition to the CLI interface.
- *
- * @param opts - Options for generating documentation
- * @returns A promise that resolves when documentation generation is complete
+ * Programmatic entry point for sveld.
  *
  * @example
  * ```ts

package/lib/validate.d.ts

@@ -0,0 +1,13 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export interface ParsedPackageJson {
+    svelte?: string;
+}
+export declare function parsePackageJson(value: unknown): ParsedPackageJson;
+export interface ParsedTsConfig {
+    compilerOptions?: {
+        baseUrl?: string;
+        paths?: Record<string, string[]>;
+    };
+    extends?: string;
+}
+export declare function parseTsConfig(value: unknown): ParsedTsConfig;

package/lib/writer/MarkdownWriterBase.d.ts

@@ -13,10 +13,6 @@ export interface MarkdownWriterBase {
     end(): string;
     get source(): string;
 }
-/**
- * Base class containing shared markdown writing logic.
- * This can be extended or used via composition.
- */
 export declare class MarkdownWriterBaseImpl implements MarkdownWriterBase {
     sourceParts: string[];
     hasToC: boolean;

package/lib/writer/WriterMarkdown.d.ts

@@ -6,11 +6,7 @@ interface MarkdownOptions {
 }
 export type { AppendType };
 /**
- * Markdown writer that extends Writer for file operations.
- *
- * Combines file writing capabilities from Writer with markdown
- * generation capabilities from MarkdownWriterBaseImpl. Supports
- * callbacks for monitoring document construction.
+ * Markdown writer with Prettier formatting and optional append callbacks.
  *
  * @example
  * ```ts
@@ -26,11 +22,6 @@ export type { AppendType };
 export default class WriterMarkdown extends Writer {
     onAppend?: OnAppend;
     private markdownBase;
-    /**
-     * Creates a new WriterMarkdown instance.
-     *
-     * @param options - Markdown writer options including append callback
-     */
     constructor(options: MarkdownOptions);
     get source(): string;
     get hasToC(): boolean;

package/lib/writer/markdown-format-utils.d.ts

@@ -5,13 +5,7 @@ export declare const PROP_TABLE_HEADER = "| Prop name | Required | Kind | Reacti
 export declare const SLOT_TABLE_HEADER = "| Slot name | Default | Props | Fallback |\n| :- | :- | :- | :- |\n";
 export declare const EVENT_TABLE_HEADER = "| Event name | Type | Detail | Description |\n| :- | :- | :- | :- |\n";
 /**
- * Formats a prop type for display in markdown tables.
- *
- * Escapes pipe characters to prevent breaking markdown table syntax
- * and wraps the type in a code block.
- *
- * @param type - The type string to format
- * @returns Formatted type string or MD_TYPE_UNDEFINED if type is undefined
+ * Escape `|` and wrap a prop type for markdown table cells.
  *
  * @example
  * ```ts
@@ -21,13 +15,7 @@ export declare const EVENT_TABLE_HEADER = "| Event name | Type | Detail | Descri
  */
 export declare function formatPropType(type?: string): string;
 /**
- * Escapes HTML special characters in text.
- *
- * Converts `<` to `&lt;` and `>` to `&gt;` to prevent HTML injection
- * and ensure proper rendering in markdown.
- *
- * @param text - The text to escape
- * @returns The escaped text
+ * Escape `<` and `>` for markdown output.
  *
  * @example
  * ```ts
@@ -36,12 +24,7 @@ export declare function formatPropType(type?: string): string;
  */
 export declare function escapeHtml(text: string): string;
 /**
- * Formats a prop default value for display in markdown tables.
- *
- * Escapes backticks and pipe characters, and wraps the value in a code block.
- *
- * @param value - The default value string to format
- * @returns Formatted value string or MD_TYPE_UNDEFINED if value is undefined
+ * Format a default value for markdown table cells.
  *
  * @example
  * ```ts
@@ -51,13 +34,7 @@ export declare function escapeHtml(text: string): string;
  */
 export declare function formatPropValue(value: string | undefined): string;
 /**
- * Formats a prop description for display in markdown tables.
- *
- * Escapes HTML characters and converts newlines to `<br />` tags
- * for proper rendering in markdown tables.
- *
- * @param description - The description string to format
- * @returns Formatted description or MD_TYPE_UNDEFINED if description is empty
+ * Format a prop description; newlines become `<br />`.
  *
  * @example
  * ```ts
@@ -67,14 +44,7 @@ export declare function formatPropValue(value: string | undefined): string;
  */
 export declare function formatPropDescription(description: string | undefined): string;
 /**
- * Formats slot props for display in markdown tables.
- *
- * Converts TypeScript type definitions to a single-line format
- * and wraps them in a code block. Returns MD_TYPE_UNDEFINED for
- * empty or undefined props.
- *
- * @param props - The slot props type string
- * @returns Formatted props string or MD_TYPE_UNDEFINED
+ * Format slot props for markdown table cells.
  *
  * @example
  * ```ts
@@ -84,13 +54,7 @@ export declare function formatPropDescription(description: string | undefined):
  */
 export declare function formatSlotProps(props?: string): string;
 /**
- * Formats slot fallback content for display in markdown tables.
- *
- * Escapes HTML and converts newlines to `<br />` tags, then wraps
- * in a code block.
- *
- * @param fallback - The fallback content string
- * @returns Formatted fallback string or MD_TYPE_UNDEFINED if undefined
+ * Format slot fallback content for markdown table cells.
  *
  * @example
  * ```ts
@@ -100,13 +64,7 @@ export declare function formatSlotProps(props?: string): string;
  */
 export declare function formatSlotFallback(fallback?: string): string;
 /**
- * Formats event detail type for display in markdown tables.
- *
- * Converts the detail type to a single-line format and wraps it
- * in a code block.
- *
- * @param detail - The event detail type string
- * @returns Formatted detail string or MD_TYPE_UNDEFINED if undefined
+ * Format event detail types for markdown table cells.
  *
  * @example
  * ```ts

package/lib/writer/markdown-render-utils.d.ts

@@ -1,16 +1,9 @@
 import type { ComponentDocs } from "../plugin";
 import type { AppendType } from "./MarkdownWriterBase";
-/**
- * Interface for markdown documents that can be used for rendering.
- * Only requires the methods we actually use, not the full implementation.
- */
+/** Minimal markdown writer surface used by JSON and browser renderers. */
 interface MarkdownDocument {
     append(type: AppendType, raw?: string): MarkdownDocument;
     tableOfContents(): MarkdownDocument;
 }
-/**
- * Renders component documentation to a markdown document.
- * This shared function is used by both writeMarkdown and writeMarkdownCore.
- */
 export declare function renderComponentsToMarkdown(document: MarkdownDocument, components: ComponentDocs): void;
 export {};

package/lib/writer/writer-markdown.d.ts

@@ -6,15 +6,7 @@ export interface WriteMarkdownOptions {
     onAppend?: (type: AppendType, document: WriterMarkdown, components: ComponentDocs) => void;
 }
 /**
- * Writes component documentation to a markdown file.
- *
- * Renders all components to markdown format and optionally writes
- * the result to a file. Returns the markdown string regardless of
- * whether it was written to disk.
- *
- * @param components - Map of component documentation to render
- * @param options - Write options including output file and callbacks
- * @returns A promise that resolves to the generated markdown string
+ * Renders component docs to markdown and optionally writes `outFile`.
  *
  * @example
  * ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sveld",
-  "version": "0.32.3",
+  "version": "0.32.5",
   "license": "Apache-2.0",
   "description": "Generate TypeScript definitions and component documentation for your Svelte components.",
   "type": "module",