vsix-utils/dist/files-BaC4caRh.d.cts

utilities for working with VSIX packages

import { Buffer } from 'node:buffer';
import { PackageManager, Manifest } from './types.cjs';
import { ManifestAsset } from './manifest.cjs';

interface ExtensionDependenciesOptions {
    /**
     * The package manager to use.
     */
    packageManager: PackageManager;
    /**
     * The current working directory
     * @default process.cwd()
     */
    cwd: string;
}
interface ExtensionDependency {
    /**
     * The name of the dependency.
     */
    name: string;
    /**
     * The version of the dependency.
     */
    version?: string;
    /**
     * The path to the dependency.
     */
    path: string;
}
/**
 * Retrieves all production dependencies for an extension based on the package manager being used.
 *
 * @param {Manifest} manifest - The extension's manifest object containing dependency information
 * @param {ExtensionDependenciesOptions} options - Configuration options for retrieving dependencies
 *
 * @returns {Promise<ExtensionDependenciesResult} Promise resolving to an object containing:
 * - dependencies: Array of extension dependencies with name, version and path
 * - packageManager: The package manager that was used
 *
 * @throws Error if:
 * - Package manager cannot be detected when using 'auto'
 * - Unsupported package manager is detected/specified (e.g. deno, bun)
 * - Unable to parse dependency information from package manager output
 *
 * @remarks
 * Supports npm, yarn, and pnpm package managers.
 * When using npm, parses output of `npm list`
 * When using yarn, parses output of `yarn list`
 * When using pnpm, parses output of `pnpm list`
 */
declare function getExtensionDependencies(manifest: Manifest, options: ExtensionDependenciesOptions): Promise<ExtensionDependency[]>;

interface TransformMarkdownOptions {
    /**
     * The markdown content to transform.
     */
    content: string;
    /**
     * Prepend all relative links in README.md with the specified URL.
     */
    baseContentUrl?: string;
    /**
     * Prepend all relative image links in README.md with the specified URL.
     */
    baseImagesUrl?: string;
    /**
     * Whether to rewrite the markdown content.
     * @default true
     */
    rewrite?: boolean;
    /**
     * The branch to use for the base URLs.
     * @default "HEAD"
     */
    branch?: string;
}
declare function transformMarkdown(manifest: Manifest, options: TransformMarkdownOptions): Promise<string>;
interface InferredBaseUrls {
    contentUrl: string;
    imagesUrl: string;
}
declare function inferBaseUrls(manifest: Manifest, branch?: string): InferredBaseUrls | null;

/**
 * @module files
 *
 * This module contains utility functions for handling files.
 */

interface VsixLocalFile {
    type: "local";
    path: string;
    readonly localPath: string;
}
interface VsixInMemoryFile {
    type: "in-memory";
    path: string;
    readonly contents: Buffer | string;
}
type VsixFile = VsixLocalFile | VsixInMemoryFile;
declare function isLocalFile(file: VsixFile): file is VsixLocalFile;
declare function isInMemoryFile(file: VsixFile): file is VsixInMemoryFile;
interface CollectOptions {
    /**
     * The directory where the extension is located.
     * @default process.cwd()
     */
    cwd?: string;
    /**
     * The file to use for ignoring files.
     */
    ignoreFile?: string;
    /**
     * The dependencies to include in the package.
     */
    dependencies?: ExtensionDependency[];
    /**
     * README file path
     * @default "README.md"
     */
    readme?: string;
}
/**
 * Collects files for a VSIX package based on the provided manifest and options.
 *
 * @param {Manifest} manifest - The VSIX manifest containing package details
 * @param {CollectOptions} options - Configuration options for file collection
 * @param {string?} options.cwd - The current working directory (defaults to process.cwd())
 * @param {string?} options.ignoreFile - The name of the ignore file to use (defaults to ".vscodeignore")
 * @param {ExtensionDependency[]?} options.dependencies - The dependencies to include in the package
 * @param {string?} options.readme - The name of the readme file to include (defaults to "README.md")
 *
 * @returns {Promise<VsixFile[]>} A promise that resolves to an array of VsixFile objects representing the files to be included
 * in the VSIX package. Each file object contains the local path and the target path in the extension.
 *
 * @remarks
 * The function takes into account both .gitignore and .vscodeignore files if they exist.
 * It filters files based on the ignore patterns and includes necessary files like package.json
 * and the readme file.
 */
declare function collect(manifest: Manifest, options: CollectOptions): Promise<VsixFile[]>;
/**
 * Detects and returns the package manager being used in the specified directory.
 *
 * @param {string} cwd - The current working directory path to detect the package manager from
 * @returns {Promise<PackageManager | null>} Promise that resolves with the detected package manager name
 * @throws {Error} If no package manager could be detected
 * @throws {Error} If an unsupported package manager (deno/bun) is detected
 */
declare function getExtensionPackageManager(cwd: string): Promise<PackageManager | null>;
interface ContentTypeResult {
    /**
     * The Content Types as a map of file extensions to content types.
     */
    contentTypes: Record<string, string>;
    /**
     * The Content Types as an XML string.
     *
     * NOTE:
     * Used inside the VSIX package to define the content types of the files.
     */
    xml: string;
}
/**
 * Generates content types mapping and XML representation for VSIX files
 * @param {VsixFile[]} files - Array of VSIX files to process
 * @returns {ContentTypeResult} Object containing:
 *  - xml: XML string representation of content types
 *  - contentTypes: Record mapping file extensions to their content types
 * @throws {Error} When content type cannot be determined for a file
 * @example
 * ```ts
 * import { getContentTypesForFiles } from "vsix-utils/files";
 *
 * const files = [
 *   { type: "local", path: "extension/package.json", localPath: "/path/to/extension/package.json" },
 *   { type: "local", path: "extension/README.md", localPath: "/path/to/extension/README.md" },
 *   { type: "local", path: "extension/LICENSE", localPath: "/path/to/extension/LICENSE" },
 *   { type: "local", path: "extension/dist/extension.js", localPath: "/path/to/extension/dist/extension.js" },
 * ];
 *
 * const { xml, contentTypes } = getContentTypesForFiles(files);
 * ```
 */
declare function getContentTypesForFiles(files: VsixFile[]): ContentTypeResult;
interface TransformedFiles {
    /**
     * The assets to include in the manifest.
     *
     * NOTE:
     * These assets are not the extension file, but other files like changelog, readme, license, etc.
     */
    assets: ManifestAsset[];
    /**
     * The icon file path.
     */
    icon?: string;
    /**
     * The license file path.
     */
    license?: string;
}
interface TransformFilesOptions {
    /**
     * The manifest object containing package details.
     */
    manifest: Manifest;
    /**
     * Files to process.
     */
    files: VsixFile[];
    /**
     * README file path
     */
    readme?: string;
    /**
     * Options to provide to `transformMarkdown`.
     * If nothing is provided, will use default options.
     */
    markdown?: Omit<TransformMarkdownOptions, "content">;
}
/**
 * Transforms files for a VSIX package by identifying and categorizing specific asset files.
 *
 * @remarks
 * This function processes a collection of files to determine which assets should be included in the VSIX manifest.
 * It looks for specific files like license, icon, README, changelog, and translation files.
 *
 * @param {TransformFilesOptions} options - Configuration options for file transformation
 * @param {Manifest} options.manifest - The extension manifest
 * @param {VsixFile[]} options.files - Array of files to process
 * @param {string?} options.readme - Optional README file path
 *
 * @returns {Promise<TransformedFiles>} A promise resolving to transformed files metadata
 *
 * @throws {Error} If a license file is found but cannot be located in the files array
 */
declare function transformFiles(options: TransformFilesOptions): Promise<TransformedFiles>;

export { type CollectOptions as C, type ExtensionDependenciesOptions as E, type InferredBaseUrls as I, type TransformedFiles as T, type VsixFile as V, type ExtensionDependency as a, type ContentTypeResult as b, type TransformFilesOptions as c, type VsixInMemoryFile as d, type VsixLocalFile as e, collect as f, getExtensionDependencies as g, getContentTypesForFiles as h, getExtensionPackageManager as i, isInMemoryFile as j, isLocalFile as k, inferBaseUrls as l, transformMarkdown as m, type TransformMarkdownOptions as n, transformFiles as t };