sveld 0.26.2 → 0.27.0

package/lib/plugin.js

@@ -1,269 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = pluginSveld;
-exports.generateBundle = generateBundle;
-exports.writeOutput = writeOutput;
-const node_fs_1 = require("node:fs");
-const promises_1 = require("node:fs/promises");
-const node_path_1 = require("node:path");
-const compiler_1 = require("svelte/compiler");
-const svelte_preprocess_1 = require("svelte-preprocess");
-const tinyglobby_1 = require("tinyglobby");
-const ComponentParser_1 = __importDefault(require("./ComponentParser"));
-const get_svelte_entry_1 = require("./get-svelte-entry");
-const parse_exports_1 = require("./parse-exports");
-const path_1 = require("./path");
-const writer_json_1 = __importDefault(require("./writer/writer-json"));
-const writer_markdown_1 = __importDefault(require("./writer/writer-markdown"));
-const writer_ts_definitions_1 = __importDefault(require("./writer/writer-ts-definitions"));
-const STYLE_TAG_REGEX = /<style.+?<\/style>/gims;
-const HYPHEN_REGEX = /-/g;
-function pluginSveld(opts) {
-    let result;
-    let input;
-    return {
-        name: "vite-plugin-sveld",
-        apply: "build",
-        enforce: "post",
-        buildStart() {
-            input = (0, get_svelte_entry_1.getSvelteEntry)(opts?.entry);
-        },
-        async generateBundle() {
-            if (input != null) {
-                result = await generateBundle(input, opts?.glob === true);
-            }
-        },
-        writeBundle() {
-            if (input != null)
-                writeOutput(result, opts || {}, input);
-        },
-    };
-}
-/**
- * Generates component documentation bundle from Svelte source files.
- *
- * Parses exports, discovers components (optionally via glob), and processes
- * all Svelte files to extract component metadata. Returns both exported
- * components (for JSON/Markdown) and all components (for TypeScript definitions).
- *
- * @param input - Entry point file or directory containing Svelte components
- * @param glob - Whether to glob for all .svelte files in the directory
- * @returns Bundle result containing exports, components, and allComponentsForTypes
- *
- * @example
- * ```ts
- * // Generate from single file:
- * const result = await generateBundle("./src/App.svelte", false);
- *
- * // Generate from directory with glob:
- * const result = await generateBundle("./src", true);
- * ```
- */
-async function generateBundle(input, glob) {
-    const isFile = (0, node_fs_1.lstatSync)(input).isFile();
-    const dir = isFile ? (0, node_path_1.dirname)(input) : input;
-    /**
-     * Only parse exports if input is a file.
-     * Directory inputs don't have a single entry point to parse exports from.
-     */
-    let exports = {};
-    if (isFile) {
-        const entry = (0, node_fs_1.readFileSync)(input, "utf-8");
-        exports = (0, parse_exports_1.parseExports)(entry, dir);
-    }
-    const allComponents = { ...exports };
-    if (glob) {
-        for (const file of (0, tinyglobby_1.globSync)([`${dir}/**/*.svelte`])) {
-            const moduleName = (0, node_path_1.parse)(file).name.replace(HYPHEN_REGEX, "");
-            const source = (0, path_1.normalizeSeparators)(`./${(0, node_path_1.relative)(dir, file)}`);
-            if (exports[moduleName]) {
-                exports[moduleName].source = source;
-            }
-            if (allComponents[moduleName]) {
-                allComponents[moduleName].source = source;
-            }
-            else {
-                allComponents[moduleName] = { source, default: false };
-            }
-        }
-    }
-    const components = new Map();
-    const allComponentsForTypes = new Map();
-    const exportEntries = Object.entries(exports);
-    const allComponentEntries = Object.entries(allComponents);
-    const uniqueFilePaths = new Set();
-    for (const [, entry] of exportEntries) {
-        const filePath = entry.source;
-        const { ext } = (0, node_path_1.parse)(filePath);
-        if (ext === ".svelte") {
-            uniqueFilePaths.add((0, node_path_1.resolve)(dir, filePath));
-        }
-    }
-    for (const [, entry] of allComponentEntries) {
-        const filePath = entry.source;
-        const { ext } = (0, node_path_1.parse)(filePath);
-        if (ext === ".svelte") {
-            uniqueFilePaths.add((0, node_path_1.resolve)(dir, filePath));
-        }
-    }
-    const fileContents = await Promise.all(Array.from(uniqueFilePaths).map(async (filePath) => {
-        try {
-            const content = await (0, promises_1.readFile)(filePath, "utf-8");
-            return { path: filePath, content };
-        }
-        catch (error) {
-            console.warn(`Warning: Failed to read file ${filePath}:`, error);
-            return { path: filePath, content: null };
-        }
-    }));
-    const fileMap = new Map(fileContents.map(({ path, content }) => [path, content]));
-    /**
-     * Helper function to process a single component.
-     *
-     * Reads the component file, preprocesses it (removes styles, processes TypeScript),
-     * and parses it to extract component metadata. Handles file read errors gracefully.
-     *
-     * @param entry - Export entry tuple [exportName, exportInfo]
-     * @param entries - All export entries for context
-     * @param fileMap - Map of file paths to their contents
-     * @returns Component documentation or null if processing failed
-     *
-     * @example
-     * ```ts
-     * const result = await processComponent(
-     *   ["Button", { source: "./Button.svelte", default: true }],
-     *   allEntries,
-     *   fileMap
-     * );
-     * // Returns: { moduleName: "Button", filePath: "./Button.svelte", props: [...], ... }
-     * ```
-     */
-    const processComponent = async ([exportName, entry], entries, fileMap) => {
-        const filePath = entry.source;
-        const { ext, name } = (0, node_path_1.parse)(filePath);
-        let moduleName = exportName;
-        if (entries.length === 1 && exportName === "default") {
-            moduleName = name;
-        }
-        if (ext === ".svelte") {
-            const resolvedPath = (0, node_path_1.resolve)(dir, filePath);
-            const source = fileMap.get(resolvedPath);
-            if (source === null || source === undefined) {
-                /**
-                 * File was not found or failed to read, skip this component.
-                 * This can happen if the file doesn't exist or if there was an error
-                 * reading it (already logged as a warning).
-                 */
-                return null;
-            }
-            const { code: processed } = await (0, compiler_1.preprocess)(source, [(0, svelte_preprocess_1.typescript)(), (0, svelte_preprocess_1.replace)([[STYLE_TAG_REGEX, ""]])], {
-                filename: (0, node_path_1.basename)(filePath),
-            });
-            const parser = new ComponentParser_1.default();
-            const parsed = parser.parseSvelteComponent(processed, {
-                moduleName,
-                filePath,
-            });
-            return {
-                moduleName,
-                filePath,
-                ...parsed,
-            };
-        }
-        return null;
-    };
-    /**
-     * Process exported components (for metadata/JSON/Markdown).
-     * Only components that are explicitly exported are included in the
-     * components map for JSON and Markdown output.
-     */
-    const componentPromises = exportEntries.map((entry) => processComponent(entry, exportEntries, fileMap));
-    /**
-     * Process all components (for .d.ts generation).
-     * All discovered components are included in allComponentsForTypes
-     * to ensure TypeScript definitions are generated for all components,
-     * even if they're not explicitly exported.
-     */
-    const allComponentPromises = allComponentEntries.map((entry) => processComponent(entry, allComponentEntries, fileMap));
-    const [results, allResults] = await Promise.all([Promise.all(componentPromises), Promise.all(allComponentPromises)]);
-    for (const result of results) {
-        if (result) {
-            components.set(result.moduleName, result);
-        }
-    }
-    for (const result of allResults) {
-        if (result) {
-            allComponentsForTypes.set(result.moduleName, result);
-        }
-    }
-    return {
-        exports,
-        components,
-        allComponentsForTypes,
-    };
-}
-/**
- * Writes output files based on plugin options.
- *
- * Generates TypeScript definitions, JSON metadata, and/or Markdown documentation
- * based on the options provided. Uses different component sets for different
- * output types to match expected behavior.
- *
- * @param result - Bundle result containing exports and component documentation
- * @param opts - Plugin options determining what outputs to generate
- * @param input - Input file path for determining input directory
- *
- * @example
- * ```ts
- * writeOutput(result, {
- *   types: true,
- *   json: true,
- *   markdown: true
- * }, "./src/App.svelte");
- * // Generates: types/*.d.ts, COMPONENT_API.json, COMPONENT_INDEX.md
- * ```
- */
-function writeOutput(result, opts, input) {
-    const inputDir = (0, node_path_1.dirname)(input);
-    if (opts?.types !== false) {
-        /**
-         * Use allComponentsForTypes to generate .d.ts for all discovered components.
-         * This ensures TypeScript definitions are available for all components,
-         * not just exported ones, which is useful for type checking.
-         */
-        (0, writer_ts_definitions_1.default)(result.allComponentsForTypes, {
-            outDir: "types",
-            preamble: "",
-            ...opts?.typesOptions,
-            exports: result.exports,
-            inputDir,
-        });
-    }
-    if (opts?.json) {
-        /**
-         * Use components (exported only) for JSON metadata.
-         * JSON output should only include components that are actually exported,
-         * matching the public API surface.
-         */
-        (0, writer_json_1.default)(result.components, {
-            outFile: "COMPONENT_API.json",
-            ...opts?.jsonOptions,
-            input,
-            inputDir,
-        });
-    }
-    if (opts?.markdown) {
-        /**
-         * Use components (exported only) for Markdown documentation.
-         * Documentation should only include exported components that are
-         * part of the public API.
-         */
-        (0, writer_markdown_1.default)(result.components, {
-            outFile: "COMPONENT_INDEX.md",
-            ...opts?.markdownOptions,
-        });
-    }
-}

package/lib/resolve-alias.js

@@ -1,198 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.clearConfigCache = clearConfigCache;
-exports.resolvePathAliasAbsolute = resolvePathAliasAbsolute;
-exports.resolvePathAlias = resolvePathAlias;
-const node_fs_1 = require("node:fs");
-const node_path_1 = require("node:path");
-const path_1 = require("./path");
-const configCache = new Map();
-const pathPatternRegexCache = new Map();
-const COMMENT_PATTERN = /\/\*[\s\S]*?\*\/|\/\/.*/g;
-const REGEX_SPECIAL_CHARS = /[.+?^${}()|[\]\\]/g;
-/**
- * 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.
- */
-function clearConfigCache() {
-    configCache.clear();
-}
-/**
- * Finds the nearest tsconfig.json or jsconfig.json starting from a directory.
- *
- * Walks up the directory tree from the start directory until it finds
- * a config file or reaches the filesystem root.
- *
- * @param startDir - The directory to start searching from
- * @returns The path to the config file, or null if not found
- *
- * @example
- * ```ts
- * // From ./src/components/Button.svelte
- * findConfig("./src/components")
- * // Returns: "./tsconfig.json" (if found in project root)
- * ```
- */
-function findConfig(startDir) {
-    let dir = startDir;
-    const root = (0, node_path_1.resolve)(dir, "/");
-    while (dir !== root) {
-        for (const configName of ["tsconfig.json", "jsconfig.json"]) {
-            const configPath = (0, node_path_1.join)(dir, configName);
-            if ((0, node_fs_1.existsSync)(configPath)) {
-                return configPath;
-            }
-        }
-        dir = (0, node_path_1.dirname)(dir);
-    }
-    return null;
-}
-function parseConfig(configPath) {
-    if (configCache.has(configPath)) {
-        return configCache.get(configPath) ?? null;
-    }
-    try {
-        const content = (0, node_fs_1.readFileSync)(configPath, "utf-8");
-        const jsonContent = content.replace(COMMENT_PATTERN, "");
-        const config = JSON.parse(jsonContent);
-        if (config.extends) {
-            const baseConfigPath = (0, node_path_1.isAbsolute)(config.extends) ? config.extends : (0, node_path_1.resolve)((0, node_path_1.dirname)(configPath), config.extends);
-            const fullBaseConfigPath = baseConfigPath.endsWith(".json") ? baseConfigPath : `${baseConfigPath}.json`;
-            if ((0, node_fs_1.existsSync)(fullBaseConfigPath)) {
-                const baseConfig = parseConfig(fullBaseConfigPath);
-                if (baseConfig) {
-                    config.compilerOptions = {
-                        ...baseConfig.compilerOptions,
-                        ...config.compilerOptions,
-                        paths: {
-                            ...baseConfig.compilerOptions?.paths,
-                            ...config.compilerOptions?.paths,
-                        },
-                    };
-                }
-            }
-        }
-        configCache.set(configPath, config);
-        return config;
-    }
-    catch {
-        configCache.set(configPath, null);
-        return null;
-    }
-}
-/**
- * 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
- *
- * @example
- * ```ts
- * // With tsconfig.json: { "paths": { "$lib/*": ["./src/lib/*"] } }
- * resolvePathAliasAbsolute("$lib/utils", "./src")
- * // Returns: "/absolute/path/to/src/lib/utils"
- *
- * resolvePathAliasAbsolute("./relative", "./src")
- * // Returns: "./relative" (unchanged, not an alias)
- * ```
- */
-function resolvePathAliasAbsolute(importPath, fromDir) {
-    if (importPath.startsWith(".") || importPath.startsWith("/")) {
-        return importPath;
-    }
-    const configPath = findConfig(fromDir);
-    if (!configPath) {
-        return importPath;
-    }
-    const config = parseConfig(configPath);
-    if (!config?.compilerOptions?.paths) {
-        return importPath;
-    }
-    const { baseUrl = ".", paths } = config.compilerOptions;
-    const configDir = (0, node_path_1.dirname)(configPath);
-    const resolvedBaseUrl = (0, node_path_1.resolve)(configDir, baseUrl);
-    // Try to match against path patterns
-    for (const [pattern, mappings] of Object.entries(paths)) {
-        /**
-         * Convert TS path pattern to regex.
-         * Examples:
-         * - "$lib/*" -> /^\$lib\/(.*)$/
-         * - "$lib" -> /^\$lib$/
-         * - "@components/*" -> /^@components\/(.*)$/
-         */
-        let regex = pathPatternRegexCache.get(pattern);
-        if (!regex) {
-            /**
-             * Escape special regex chars but keep * for replacement.
-             * The * wildcard is converted to a capture group for substitution.
-             */
-            const escapedPattern = pattern
-                .split("*")
-                .map((part) => part.replace(REGEX_SPECIAL_CHARS, "\\$&"))
-                .join("(.*)");
-            regex = new RegExp(`^${escapedPattern}$`);
-            pathPatternRegexCache.set(pattern, regex);
-        }
-        const match = importPath.match(regex);
-        if (match) {
-            // TypeScript uses the first matching pattern
-            const mapping = mappings[0];
-            if (!mapping)
-                continue;
-            // Replace * in mapping with captured groups (e.g., "$lib/*" matching "$lib/utils" -> "utils")
-            let resolvedPath = mapping;
-            for (let i = 1; i < match.length; i++) {
-                resolvedPath = resolvedPath.replace("*", match[i]);
-            }
-            // Resolve relative to baseUrl from tsconfig
-            const fullPath = (0, node_path_1.resolve)(resolvedBaseUrl, resolvedPath);
-            return fullPath;
-        }
-    }
-    return importPath;
-}
-/**
- * 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
- *
- * @example
- * ```ts
- * // With alias "$lib/utils" -> "./src/lib/utils"
- * resolvePathAlias("$lib/utils", "./src")
- * // Returns: "./lib/utils"
- *
- * resolvePathAlias("./Button.svelte", "./src")
- * // Returns: "./Button.svelte" (unchanged, not an alias)
- * ```
- */
-function resolvePathAlias(importPath, fromDir) {
-    if (importPath.startsWith(".") || importPath.startsWith("/")) {
-        return importPath;
-    }
-    const absolutePath = resolvePathAliasAbsolute(importPath, fromDir);
-    if (absolutePath === importPath) {
-        return importPath;
-    }
-    let relativePath = (0, node_path_1.relative)(fromDir, absolutePath);
-    /**
-     * Normalize path separators to forward slashes for consistency across platforms.
-     * Windows uses backslashes, but we want forward slashes in generated code
-     * for cross-platform compatibility.
-     */
-    relativePath = (0, path_1.normalizeSeparators)(relativePath);
-    return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
-}

package/lib/sveld.js

@@ -1,33 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.sveld = sveld;
-const get_svelte_entry_1 = require("./get-svelte-entry");
-const plugin_1 = require("./plugin");
-/**
- * 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
- *
- * @example
- * ```ts
- * await sveld({
- *   input: "./src",
- *   types: true,
- *   json: true,
- *   markdown: true,
- *   glob: true
- * });
- * ```
- */
-async function sveld(opts) {
-    const input = (0, get_svelte_entry_1.getSvelteEntry)(opts?.input);
-    if (input === null)
-        return;
-    const result = await (0, plugin_1.generateBundle)(input, opts?.glob === true);
-    (0, plugin_1.writeOutput)(result, opts || {}, input);
-}

package/lib/writer/MarkdownWriterBase.js

@@ -1,70 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MarkdownWriterBaseImpl = void 0;
-const markdown_format_utils_1 = require("./markdown-format-utils");
-/**
- * Base class containing shared markdown writing logic.
- * This can be extended or used via composition.
- */
-class MarkdownWriterBaseImpl {
-    sourceParts = [];
-    hasToC = false;
-    toc = [];
-    get source() {
-        return this.sourceParts.join("");
-    }
-    appendLineBreaks() {
-        this.sourceParts.push("\n\n");
-        return this;
-    }
-    append(type, raw) {
-        switch (type) {
-            case "h1":
-            case "h2":
-            case "h3":
-            case "h4":
-            case "h5":
-            case "h6": {
-                const length = Number(type.slice(-1));
-                this.sourceParts.push(`${"#".repeat(length)} ${raw}`);
-                if (this.hasToC && type === "h2") {
-                    this.toc.push({
-                        array: Array.from({ length: (length - 1) * 2 }),
-                        raw: raw ?? "",
-                    });
-                }
-                break;
-            }
-            case "quote":
-                this.sourceParts.push(`> ${raw}`);
-                break;
-            case "p":
-                this.sourceParts.push(raw ?? "");
-                break;
-            case "divider":
-                this.sourceParts.push("---");
-                break;
-            case "raw":
-                this.sourceParts.push(raw ?? "");
-                break;
-        }
-        if (type !== "raw")
-            this.appendLineBreaks();
-        return this;
-    }
-    tableOfContents() {
-        this.sourceParts.push("<!-- __TOC__ -->");
-        this.hasToC = true;
-        this.appendLineBreaks();
-        return this;
-    }
-    end() {
-        const source = this.sourceParts.join("");
-        return source.replace("<!-- __TOC__ -->", this.toc
-            .map(({ array, raw }) => {
-            return `${array.join(" ")} - [${raw}](#${raw.toLowerCase().replace(markdown_format_utils_1.BACKTICK_REGEX, "").replace(markdown_format_utils_1.WHITESPACE_REGEX, "-")})`;
-        })
-            .join("\n"));
-    }
-}
-exports.MarkdownWriterBaseImpl = MarkdownWriterBaseImpl;

package/lib/writer/Writer.js

@@ -1,104 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createJsonWriter = createJsonWriter;
-exports.createTypeScriptWriter = createTypeScriptWriter;
-const promises_1 = require("node:fs/promises");
-const node_path_1 = require("node:path");
-const prettier_1 = require("prettier");
-/**
- * Base writer class for formatting and writing files.
- *
- * Handles file formatting using Prettier and file system operations.
- * Automatically creates directories as needed and formats content
- * before writing.
- *
- * @example
- * ```ts
- * const writer = new Writer({ parser: "typescript", printWidth: 80 });
- * await writer.write("./dist/index.d.ts", "export type Props = {};");
- * ```
- */
-class Writer {
-    options;
-    /**
-     * Creates a new Writer instance.
-     *
-     * @param options - Writer configuration options
-     */
-    constructor(options) {
-        this.options = options;
-    }
-    /**
-     * Formats raw content using Prettier.
-     *
-     * Applies formatting based on the configured parser and print width.
-     * Returns the original content if formatting fails.
-     *
-     * @param raw - The raw content to format
-     * @returns Formatted content, or original content if formatting fails
-     *
-     * @example
-     * ```ts
-     * const formatted = await writer.format("export type Props={}");
-     * // Returns: "export type Props = {};\n"
-     * ```
-     */
-    async format(raw) {
-        try {
-            const result = await (0, prettier_1.format)(raw, this.options);
-            return result;
-        }
-        catch (error) {
-            console.error(error);
-            return raw;
-        }
-    }
-    /**
-     * Writes formatted content to a file.
-     *
-     * Creates the directory structure if needed, formats the content,
-     * and writes it to the specified file path.
-     *
-     * @param filePath - The path where the file should be written
-     * @param raw - The raw content to format and write
-     *
-     * @example
-     * ```ts
-     * await writer.write("./dist/index.d.ts", "export type Props={}");
-     * // Creates ./dist/index.d.ts with formatted content
-     * ```
-     */
-    async write(filePath, raw) {
-        await (0, promises_1.mkdir)((0, node_path_1.parse)(filePath).dir, { recursive: true });
-        await (0, promises_1.writeFile)(filePath, await this.format(raw));
-    }
-}
-exports.default = Writer;
-/**
- * Creates a Writer instance configured for JSON files.
- *
- * @returns A Writer instance with JSON parser and 80 character print width
- *
- * @example
- * ```ts
- * const writer = createJsonWriter();
- * await writer.write("data.json", JSON.stringify({ key: "value" }));
- * ```
- */
-function createJsonWriter() {
-    return new Writer({ parser: "json", printWidth: 80 });
-}
-/**
- * Creates a Writer instance configured for TypeScript files.
- *
- * @returns A Writer instance with TypeScript parser and 80 character print width
- *
- * @example
- * ```ts
- * const writer = createTypeScriptWriter();
- * await writer.write("index.d.ts", "export type Props={};");
- * ```
- */
-function createTypeScriptWriter() {
-    return new Writer({ parser: "typescript", printWidth: 80 });
-}