mdat
Version:
CLI tool and TypeScript library implementing the Markdown Autophagic Template (MDAT) system. MDAT lets you use comments as dynamic content templates in Markdown files, making it easy to generate and update readme boilerplate.
227 lines • 7.59 kB
TypeScript
import { Rule, Rule as Rule$1 } from "remark-mdat";
import { ILogBasic, ILogLayer } from "lognow";
import { MetadataContext } from "metascope";
import { VFile } from "vfile";
//#region src/lib/config.d.ts
/**
* An mdat configuration is a record of expansion rules. Keys become comment
* keywords, values define the expansion content.
*/
type Config = Record<string, Rule$1>;
/**
* Generously accept either string paths to .ts, .js, or .json config files, or
* inline Config objects.
*/
type ConfigToLoad = Array<Config | string> | Config | string;
/**
* Load and validate mdat configuration. Uses cosmiconfig to search in the usual
* places. Merge precedence: Base Defaults < Defaults < Searched Config <
* Additional Config
*/
declare function loadConfig(options?: {
/**
* Additional Config objects to merge.
*
* Strings are treated as paths to `ts`, `js`, or `json` config files. These
* will be dynamically loaded by Cosmiconfig. Accepts an individual item, or
* an array. Objects in the array will be merged right to left.
*/
additionalConfig?: ConfigToLoad;
/**
* Default rules that have higher priority than base defaults but lower than
* searched config. Defaults to the built-in readme rules. Pass `{}` to
* disable.
*/
defaults?: Config;
/**
* Search for config in specific directories, mainly useful for testing.
* Cosmiconfig default search paths used if unset.
*/
searchFrom?: string;
}): Promise<Config>;
/**
* Convenience function for merging configs. Rightmost config takes precedence.
*/
declare function mergeConfig(a: Config, b: Config): Config;
/**
* Identity function providing type inference for mdat configuration files.
*/
declare function defineConfig(config: Config): Config;
//#endregion
//#region src/lib/readme/create.d.ts
type MdatReadmeCreateOptions = {
compound: boolean;
expand: boolean;
output: string;
overwrite: boolean;
template: string;
};
/**
* Creates a new readme file interactively.
*
* @returns Path to the created readme file.
*/
declare function createReadmeInteractive(): Promise<string>;
/**
* Creates a new readme file with the given options.
*
* @returns Path to the created readme file.
*/
declare function createReadme(options?: Partial<MdatReadmeCreateOptions>): Promise<string>;
//#endregion
//#region src/lib/api.d.ts
/**
* Expand MDAT comments in one or more Markdown files. If no files are provided,
* auto-finds the closest readme.md. Writing is the responsibility of the caller
* (e.g. via `await write(result)`)
*
* @returns An array of VFiles
*/
declare function expand(files?: string | string[], name?: string, output?: string, config?: ConfigToLoad, options?: {
format?: boolean;
}): Promise<VFile[]>;
/**
* Expand MDAT comments in a Markdown string.
*/
declare function expandString(markdown: string, config?: ConfigToLoad, options?: {
format?: boolean;
}): Promise<VFile>;
/**
* Collapse MDAT comments in one or more Markdown files. If no files are
* provided, auto-finds the closest readme.md. Writing is the responsibility of
* the caller (e.g. via `await write(result)`)
*
* @returns An array of VFiles
*/
declare function collapse(files?: string | string[], name?: string, output?: string, config?: ConfigToLoad, options?: {
format?: boolean;
}): Promise<VFile[]>;
/**
* Collapse MDAT comments in a Markdown string.
*/
declare function collapseString(markdown: string, config?: ConfigToLoad, options?: {
format?: boolean;
}): Promise<VFile>;
/**
* Strips MDAT comments in one or more Markdown files without touching other
* content. Does _not_ automatically expand Mdat content before stripping the
* tags. If no files are provided, auto-finds the closest readme.md. Writing is
* the responsibility of the caller (e.g. via `await write(result)`)
*
* @returns An array of VFiles
*/
declare function strip(files?: string | string[], name?: string, output?: string, config?: ConfigToLoad, options?: {
format?: boolean;
}): Promise<VFile[]>;
/**
* Strip MDAT comments from a Markdown string.
*/
declare function stripString(markdown: string, config?: ConfigToLoad, options?: {
format?: boolean;
}): Promise<VFile>;
/**
* Dry-run expand and compare with file on disk. If no files are provided,
* auto-finds the closest readme.md.
*
* @returns Per-file sync status and expanded VFiles
*/
declare function check(files?: string | string[], config?: ConfigToLoad, options?: {
format?: boolean;
}): Promise<Array<{
inSync: boolean;
result: VFile;
}>>;
/**
* Check if MDAT comments in a Markdown string are up to date by expanding and
* comparing per-tag.
*/
declare function checkString(markdown: string, config?: ConfigToLoad, options?: {
format?: boolean;
}): Promise<{
inSync: boolean;
result: VFile;
}>;
//#endregion
//#region src/lib/context.d.ts
/**
* Get a bunch of platform-agnostic local metadata via metascope, exposed
* primarily for plugin developers. Result is memoized the result.
*
* @throws {Error} If no package.json is found
*/
declare function getContextMetadata(): Promise<MetadataContext>;
declare const readmeMetadataTemplate: import("metascope").Template<{
author: string | undefined;
authorUrl: string | undefined;
bin: string[] | undefined;
ciActionFileName: string | undefined;
description: string | undefined;
engines: {
[k: string]: string;
} | undefined;
isPublicNpmPackage: boolean;
issuesUrl: string | undefined;
license: string | undefined;
licenseFilePath: string | undefined;
licenseUrl: string | undefined;
name: string | undefined;
operatingSystem: string[] | undefined;
peerDependencies: {
name: string;
optional: boolean;
version: string;
}[] | undefined;
projectDirectory: string | undefined;
repositoryUrl: string | undefined;
runtimePlatform: string[] | undefined;
usesPnpm: boolean;
}>;
type ReadmeMetadata = ReturnType<typeof readmeMetadataTemplate>;
/**
* Nice data for readme rules
*
* @public
*/
declare function getReadmeMetadata(): Promise<{
author: string | undefined;
authorUrl: string | undefined;
bin: string[] | undefined;
ciActionFileName: string | undefined;
description: string | undefined;
engines: {
[k: string]: string;
} | undefined;
isPublicNpmPackage: boolean;
issuesUrl: string | undefined;
license: string | undefined;
licenseFilePath: string | undefined;
licenseUrl: string | undefined;
name: string | undefined;
operatingSystem: string[] | undefined;
peerDependencies: {
name: string;
optional: boolean;
version: string;
}[] | undefined;
projectDirectory: string | undefined;
repositoryUrl: string | undefined;
runtimePlatform: string[] | undefined;
usesPnpm: boolean;
}>;
/**
* Reset all cached metadata. Call between tests or when the underlying project
* files may have changed on disk.
*/
declare function resetMetadataCaches(): void;
//#endregion
//#region src/lib/log.d.ts
/**
* Set the logger instance for the module. Export this for library consumers to
* inject their own logger.
*
* @param logger - Accepts either a LogLayer instance or a Console- or
* Stream-like log target
*/
declare function setLogger(logger?: ILogBasic | ILogLayer<unknown>): void;
//#endregion
export { type Config, type ReadmeMetadata, type Rule, check, checkString, collapse, collapseString, createReadme as create, createReadmeInteractive as createInteractive, defineConfig, expand, expandString, getContextMetadata, getReadmeMetadata, loadConfig, mergeConfig, resetMetadataCaches, setLogger, strip, stripString };