tldw/lib.d.ts

Generate README files from package metadata and configurable fragments.

declare const fragments: {
	readonly legal: "Legal";
	readonly warning: "Warning";
	readonly usage: "Usage";
	readonly advancedUsage: "Advanced Usage";
	readonly example: true;
	readonly options: true;
	readonly development: true;
	readonly description: true;
	readonly result: true;
	readonly notes: "Notes";
	readonly related: "Related";
	readonly faq: "Questions & Answers";
};
declare const supportedPackageManagers: readonly [
	"bun",
	"npm",
	"pnpm",
	"yarn",
	"deno"
];
export declare const createReadmeContext: (args: CliArgs) => Promise<Context | null>;
export declare const logWriteReadmeResult: (result: WriteReadmeResult, cwd?: string) => void;
export declare const writeReadme: (args: CliArgs) => Promise<WriteReadmeResult>;
export interface BannerDefinition {
	bottomColor?: string;
	font?: string;
	text?: string;
	topColor?: string;
}
export interface CliArgs {
	configDirectory: string;
	licenseFile: string;
	outputFile: string;
	packageFile: string;
}
export interface Config {
	banner: BannerConfig;
	binExample: string | null;
	binName: boolean | string;
	environmentVariables: Record<string, string>;
	exampleResultMayVary: boolean;
	excludeShields: Arrayable<string>;
	githubActions: boolean;
	githubPackage: boolean;
	installation: InstallationMode;
	link: string | null;
	linkName: string | null;
	maxBlankLines: number;
	needsNodeRuntime: boolean;
	packageManagers: Arrayable<PackageManager>;
	personal: boolean;
	renderComment: boolean;
	shields: ShieldsConfig | null;
	tryInBrowser: boolean | null;
	versionInInstallation: boolean;
}
export interface Context {
	args: CliArgs;
	bannerSvg: string | null;
	binExample: string | null;
	binName: false | string;
	camelCaseName: string;
	config: Config;
	description: string | null;
	developmentScripts: Array<DevelopmentScript>;
	example: string | null;
	exampleResults: Record<string, string>;
	fragments: FragmentContent;
	fundingLink: string | null;
	globalName: string;
	hasDevelopmentSection: boolean;
	hasEnvironmentVariables: boolean;
	hasExampleSection: boolean;
	hasOptionsSection: boolean;
	hasUsageOptions: boolean;
	hasUsageSection: boolean;
	installationCommands: Array<InstallationCommand>;
	isBunProject: boolean;
	isMitLicense: boolean;
	license: string | null;
	pascalCaseName: string;
	pkg: PackageData;
	shieldLines: Array<string>;
	slug: string;
	tag: string;
	title: string;
	tldwVersion: string;
	usage: string | null;
	usageCode: string | null;
	usageCodeLanguage: string;
	usageOptions: UsageOptions | null;
	usageResult: string | null;
	usageResultLanguage: string;
	worksAsScriptTag: boolean;
}
export interface CustomShieldDefinition extends GenerateShieldOptions {
	id?: string;
}
export interface PackageData {
	bin?: Record<string, string> | string;
	description?: string;
	displayName?: string;
	domain?: string;
	funding?: PackageFunding;
	license?: unknown;
	name: string;
	repository?: PackageRepositoryObject | string;
	scripts?: Record<string, string>;
	title?: string;
	type?: string;
	version: string;
	webpackConfigJaid?: string;
}
export interface UsageOptionEntry {
	default?: unknown;
	info?: string;
	name: string;
	required?: boolean;
	type?: string;
}
export interface UsageOptions {
	anyEntryHasDefault: boolean;
	anyEntryHasInfo: boolean;
	anyEntryHasRequired: boolean;
	anyEntryHasType: boolean;
	entries: Array<UsageOptionEntry>;
}
export interface WriteReadmeResult {
	bytes?: number;
	outputFile: string;
	readmeText?: string;
	reason?: string;
	status: WriteReadmeStatus;
}
export type Arrayable<Type> = Array<Type> | Type;
export type BannerConfig = BannerDefinition | boolean | string;
export type ConfiguredShield = CustomShieldDefinition | string;
export type PackageManager = typeof supportedPackageManagers[number];
export type ShieldsConfig = Array<Array<ConfiguredShield> | ConfiguredShield>;
interface DevelopmentScript {
	name: string;
	script: string;
}
interface GenerateShieldOptions {
	altText?: string;
	baseUrl?: string;
	color?: string;
	colorSchemeAware?: boolean;
	label?: string;
	leftText?: string;
	link?: string;
	logo?: string;
	logoColor?: string;
	path?: Array<string> | string;
	query?: Record<string, string>;
	rightText?: string;
	style?: string;
	variant?: string;
}
interface InstallationCommand {
	bonusText?: string;
	command: string;
	header: string;
	headerArgument: string;
}
interface PackageRepositoryObject {
	directory?: string;
	type?: string;
	url?: string;
}
type FragmentContent = Partial<Record<FragmentId, string>>;
type FragmentId = keyof typeof fragments;
type InstallationMode = "dev" | "global" | "prod" | false;
type PackageFunding = Array<{
	type?: string;
	url?: string;
} | string> | {
	type?: string;
	url?: string;
} | string;
type WriteReadmeStatus = "created" | "overwritten" | "skipped" | "unchanged";

export {
	writeReadme as default,
};

export {};