sandhog/dist/index.d.ts

A virtual Open Source project maintainer

import prettier, { Options } from 'prettier';
import { ElementOf, PartialDeep } from 'helpertypes';
import fs from 'fs';

declare const SECTION_KINDS: readonly ["toc", "logo", "badges", "description_short", "description_long", "features", "feature_image", "usage", "install", "contributing", "maintainers", "faq", "backers", "license"];
type SectionKind = ElementOf<typeof SECTION_KINDS>;

declare const BADGE_KINDS: readonly ["downloads", "dependencies", "npm", "contributors", "license", "patreon", "open_collective_donate", "open_collective_backers", "open_collective_sponsors", "code_style"];
type BadgeKind = ElementOf<typeof BADGE_KINDS>;

type Contributor = Partial<{
    name: string;
    email: string;
    url: string;
    role: string;
    imageUrl: string;
    twitter: string;
    github: string;
}>;

interface PatreonConfig {
    userId?: string;
    username?: string;
}
interface OpenCollectiveConfig {
    project?: string;
}
interface OtherDonorsConfig {
    donors: Contributor[];
    fundingUrl?: string;
}
interface DonateConfig {
    patreon: PatreonConfig;
    openCollective: OpenCollectiveConfig;
    other: OtherDonorsConfig;
}
interface ImageConfig {
    url?: string;
    height: number;
}
interface BadgeConfig {
    exclude: Iterable<BadgeKind>;
}
interface SectionConfig {
    exclude: Iterable<SectionKind>;
}
interface ReadmeConfig {
    sections: SectionConfig;
    badges: BadgeConfig;
}
interface SandhogConfig {
    isDevelopmentPackage: boolean;
    donate: DonateConfig;
    logo: ImageConfig;
    featureImage: ImageConfig;
    readme: ReadmeConfig;
    prettier: Options;
}

interface Author {
    name: string;
    email: string;
    url: string;
}
interface Package {
    name?: string;
    description?: string;
    bin?: Record<string, string>;
    repository?: {
        url?: string;
    };
    funding?: string | Partial<{
        type: string;
        url: string;
    }>;
    license?: string;
    sandhog?: PartialDeep<SandhogConfig>;
    author?: Partial<Author> | string;
    authors?: (Partial<Author> | string)[];
    contributors?: (Partial<Author> | string)[];
    xo?: Record<string, string>;
    devDependencies?: Record<string, string>;
    dependencies?: Record<string, string>;
    peerDependencies?: Record<string, string>;
    peerDependenciesMeta?: Record<string, Partial<{
        optional: boolean;
    }>>;
}

interface ILogger {
    /**
     * Logs info-related messages
     * @param messages
     */
    info(...messages: string[]): void;
    /**
     * Logs verbose-related messages
     * @param messages
     */
    verbose(...messages: string[]): void;
    /**
     * Logs debug-related messages
     * @param messages
     */
    debug(...messages: string[]): void;
    /**
     * Logs warning-related messages
     * @param messages
     */
    warn(...messages: string[]): void;
}

interface FileSystem {
    writeFileSync: typeof fs.writeFileSync;
    readFileSync: typeof fs.readFileSync;
    existsSync: typeof fs.existsSync;
    mkdirSync: typeof fs.mkdirSync;
}

interface GenerateReadmeOptions {
    prettier: typeof prettier;
    pkg: Package;
    logger: ILogger;
    root: string;
    fs: Pick<FileSystem, "existsSync" | "readFileSync">;
    config: SandhogConfig;
    existingReadme?: string;
}

/**
 * Generates the text for a README.md based on the given options
 */
declare function generateReadme(options: GenerateReadmeOptions): Promise<string>;

declare const LICENSE_NAMES: readonly ["APACHE-2.0", "BSD-2-CLAUSE", "BSD-3-CLAUSE", "CC-BY-4.0", "CC-BY-SA-4.0", "EPL-1.0", "GPL-3.0", "GPL-2.0", "AGPL-3.0", "LGPL-3.0", "MIT", "MPL-2.0", "ARTISTIC-2.0", "ZLIB"];
type LicenseName = ElementOf<typeof LICENSE_NAMES>;

interface GenerateLicenseOptions {
    prettier: typeof prettier;
    config: SandhogConfig;
    pkg: Package;
    contributors: Contributor[];
}

/**
 * Generates license text for the given license name
 */
declare function generateLicense(license: LicenseName, options: GenerateLicenseOptions): Promise<string>;

interface GenerateContributingOptions {
    prettier: typeof prettier;
    pkg: Package;
    config: SandhogConfig;
    contributors: Contributor[];
}

/**
 * Generates a CONTRIBUTING.md based on the given options
 */
declare function generateContributing({ contributors, prettier, config, pkg }: GenerateContributingOptions): Promise<string>;

interface GenerateCocOptions {
    prettier: typeof prettier;
    config: SandhogConfig;
    contributors: Contributor[];
}

/**
 * Generates a Code Of Conduct based on the given options
 */
declare function generateCoc({ contributors, prettier, config }: GenerateCocOptions): Promise<string>;

interface GenerateFundingOptions {
    prettier: typeof prettier;
    config: SandhogConfig;
    contributors: Contributor[];
}

/**
 * Generates a FUNDING.yml based on the given options
 */
declare function generateFunding({ contributors, prettier, config }: GenerateFundingOptions): Promise<string>;

declare const enum LogLevelKind {
    NONE = 0,
    INFO = 1,
    VERBOSE = 2,
    DEBUG = 3
}

/**
 * A logger that can print to the console
 */
declare class Logger implements ILogger {
    private readonly logLevel;
    private readonly VERBOSE_COLOR;
    private readonly WARNING_COLOR;
    private readonly DEBUG_COLOR;
    constructor(logLevel: LogLevelKind);
    /**
     * Logs info-related messages
     */
    info(...messages: unknown[]): void;
    /**
     * Logs verbose-related messages
     */
    verbose(...messages: unknown[]): void;
    /**
     * Logs debug-related messages
     */
    debug(...messages: unknown[]): void;
    /**
     * Logs warning-related messages
     */
    warn(...messages: unknown[]): void;
}

interface FindPackageOptions {
    root?: string;
    fs?: Pick<FileSystem, "existsSync" | "readFileSync">;
    logger: ILogger;
}

interface FindConfigOptions extends FindPackageOptions {
    fs?: Pick<FileSystem, "existsSync" | "readFileSync">;
    filename?: string;
    pkg?: Package;
}

/**
 * Finds a sandhog config if possible
 */
declare function findConfig({ filename, logger, root, fs, pkg }: FindConfigOptions): Promise<PartialDeep<SandhogConfig> | undefined>;

/**
 * Gets a SandhogConfig. Will attempt to resolve a config and fall back to defaults
 * if no such config could be found
 */
declare function getConfig(options: FindConfigOptions): Promise<SandhogConfig>;

export { type BadgeKind, type FileSystem, type GenerateCocOptions, type GenerateContributingOptions, type GenerateFundingOptions, type GenerateLicenseOptions, type GenerateReadmeOptions, type ILogger, Logger, type Package, type SandhogConfig, type SectionKind, findConfig, generateCoc, generateContributing, generateFunding, generateLicense, generateReadme, getConfig };