///
import { ExecSyncOptions } from 'child_process';
import { Jsdoc } from 'extra-jsdoc-text';
import { Reflection, ProjectReflection, ReflectionFlags } from 'typedoc';
/**
* Get symbol name for file.
* [📘](https://github.com/nodef/extra-build/wiki/symbolname)
* @param pth file path
* @returns symbol name
*/
declare function symbolname(pth: string): string;
/**
* Get keyword name for file.
* [📘](https://github.com/nodef/extra-build/wiki/keywordname)
* @param pth file path
* @returns keyword name
*/
declare function keywordname(pth: string): string;
/**
* Print error message to stderr with newline.
* [📘](https://github.com/nodef/extra-build/wiki/error)
* @param x data
*/
declare function error(x?: any): void;
/**
* Print warning message to stderr with newline.
* [📘](https://github.com/nodef/extra-build/wiki/warn)
* @param x data
*/
declare function warn(x?: any): void;
/**
* Print log message to stdout with newline.
* [📘](https://github.com/nodef/extra-build/wiki/log)
* @param x data
*/
declare function log(x?: any): void;
/**
* Print info message to stdout with newline.
* [📘](https://github.com/nodef/extra-build/wiki/info)
* @param x data
*/
declare function info(x?: any): void;
/**
* Exec options.
* [📘](https://github.com/nodef/extra-build/wiki/ExecOptions)
*/
interface ExecOptions extends ExecSyncOptions {
/** Hide command log. */
commandHide?: boolean;
}
/**
* Execute command with output, and print the command.
* [📘](https://github.com/nodef/extra-build/wiki/exec)
* @param cmd command to execute
* @param options exec options
* @returns command output
*/
declare function exec(cmd: string, options?: ExecOptions): string | Buffer;
/**
* Execute command and get its output as string.
* [📘](https://github.com/nodef/extra-build/wiki/execStr)
* @param cmd command to execute
* @param options exec options
* @returns command output
*/
declare function execStr(cmd: string, options?: ExecOptions): string;
/**
* Read file text with Unix EOL.
* [📘](https://github.com/nodef/extra-build/wiki/readFileText)
* @param pth file path
* @returns file text
*/
declare function readFileText(pth: string): string;
/**
* Write file text with system EOL.
* [📘](https://github.com/nodef/extra-build/wiki/writeFileText)
* @param pth file path
* @param txt file text
*/
declare function writeFileText(pth: string, txt: string): void;
/**
* Read JSON file as object.
* [📘](https://github.com/nodef/extra-build/wiki/readJson)
* @param pth path of JSON file
* @returns object
*/
declare function readJson(pth: string): any;
/**
* Write object to JSON file.
* [📘](https://github.com/nodef/extra-build/wiki/writeJson)
* @param pth path of JSON file
* @param val object
*/
declare function writeJson(pth: string, val: any): void;
/**
* Records file path and data.
* [📘](https://github.com/nodef/extra-build/wiki/Document)
*/
interface Document {
/** File path. */
path: string;
/** File data. */
data: string | Buffer;
}
/**
* Read document.
* [📘](https://github.com/nodef/extra-build/wiki/readDocument)
* @param pth file path
* @returns document \{path, data\}
*/
declare function readDocument(pth: string): Document;
/**
* Write document.
* [📘](https://github.com/nodef/extra-build/wiki/writeDocument)
* @param doc document \{path, data\}
*/
declare function writeDocument(doc: Document): void;
/**
* Git commit push options.
* [📘](https://github.com/nodef/extra-build/wiki/GitCommitPushOptions)
*/
interface GitCommitPushOptions extends ExecOptions {
/** Commit options. */
commit?: string;
/** Push options. */
push?: string;
}
/**
* Commit new changes and push to remote.
* [📘](https://github.com/nodef/extra-build/wiki/gitCommitPush)
* @param msg commit message (amend if empty)
* @param options commit options
*/
declare function gitCommitPush(msg?: string, options?: GitCommitPushOptions): void;
/**
* Git setup branch options.
* [📘](https://github.com/nodef/extra-build/wiki/GitSetupBranchOptions)
*/
interface GitSetupBranchOptions extends ExecOptions {
/** First file [index.html]. */
file?: string;
}
/**
* Setup new branch and push to remote.
* [📘](https://github.com/nodef/extra-build/wiki/gitSetupBranch)
* @param branch branch name
* @param options setup options
*/
declare function gitSetupBranch(branch: string, options?: GitSetupBranchOptions): void;
/**
* Add banner (header comment) to script text.
* [📘](https://github.com/nodef/extra-build/wiki/addBanner)
* @param txt script text
* @returns script text with banner
*/
declare function addBanner(txt: string): string;
/**
* Bundle options.
* [📘](https://github.com/nodef/extra-build/wiki/BundleOptions)
*/
interface BundleOptions {
/** Bundle config script [rollup.config.js]. */
config?: string;
/** Environment variables for bundle config script. */
env?: NodeJS.Dict;
}
/**
* Bundle a script file with config.
* [📘](https://github.com/nodef/extra-build/wiki/bundleScript)
* @param src source file
* @param options bundle options \{config, env\}
*/
declare function bundleScript(src?: string, options?: BundleOptions): void;
/**
* Webify options.
* [📘](https://github.com/nodef/extra-build/wiki/WebifyOptions)
*/
interface WebifyOptions {
/** Source script format (cjs, esm) [cjs]. */
format?: string;
/** Standalone symbol name. */
symbol?: string;
/** Banner text for script. */
banner?: string;
}
/**
* Webify a script file.
* [📘](https://github.com/nodef/extra-build/wiki/webifyScript)
* @param src source script file
* @param dst destination script file
* @param options webify options
*/
declare function webifyScript(src: string, dst: string, options?: WebifyOptions): void;
/**
* JSDoc details with some symbol details.
* [📘](https://github.com/nodef/extra-build/wiki/JsdocToken)
*/
interface JsdocToken extends Jsdoc {
/** Symbol name. */
name: string;
/** Symbol kind. */
kind: string;
/** Symbol is exported? */
isExported: boolean;
/** Symbol is default? */
isDefault: boolean;
}
/**
* Perform operation on jsdoc token.
* [📘](https://github.com/nodef/extra-build/wiki/OnJsdocToken)
* @param j jsdoc token
* @returns resulting jsdoc token; or null to keep as-is
*/
type OnJsdocToken = (j: JsdocToken) => JsdocToken;
/**
* Transform JSDocs in a script file.
* [📘](https://github.com/nodef/extra-build/wiki/jsdocifyScript)
* @param src source script file
* @param dst destination script file
* @param fm jsdoc token transformer (j)
*/
declare function jsdocifyScript(src: string, dst: string, fm: OnJsdocToken): void;
/**
* GitHub URL details.
* [📘](https://github.com/nodef/extra-build/wiki/GithubUrlDetails)
*/
interface GithubUrlDetails {
/** Owner name. */
owner: string;
/** Repository name. */
repo: string;
}
/**
* Get details from GitHub URL.
* [📘](https://github.com/nodef/extra-build/wiki/parseGithubUrl)
* @param url remote url
* @returns url details
*/
declare function parseGithubUrl(url: string): GithubUrlDetails;
/**
* GitHub Repository details.
* [📘](https://github.com/nodef/extra-build/wiki/GithubRepoDetails)
*/
interface GithubRepoDetails {
/** Authorization token [$GITHUB_TOKEN]. */
auth?: string;
/** Owner name. */
owner?: string;
/** Repository name. */
repo?: string;
/** Repository description. */
description?: string;
/** Respoitory homepage URL. */
homepage?: string;
/** Repository topics. */
topics?: string[];
}
/**
* Update GitHub repository details.
* [📘](https://github.com/nodef/extra-build/wiki/updateGithubRepoDetails)
* @param options repository details
*/
declare function updateGithubRepoDetails(options?: GithubRepoDetails): Promise;
/**
* Read package.json data.
* [📘](https://github.com/nodef/extra-build/wiki/readMetadata)
* @param dir package directory
* @returns package.json data
*/
declare function readMetadata(dir?: string): any;
/**
* Write package.json data.
* [📘](https://github.com/nodef/extra-build/wiki/writeMetadata)
* @param dir package directory
* @param val package.json data
*/
declare function writeMetadata(dir: string, val: any): void;
/**
* Get current registry.
* [📘](https://github.com/nodef/extra-build/wiki/registry)
* @param dir package directory
* @returns current registry
*/
declare function registry(dir?: string): string;
/**
* Set current registry.
* [📘](https://github.com/nodef/extra-build/wiki/setRegistry)
* @param dir package directory
* @param url registry url
*/
declare function setRegistry(dir: string, url: string): void;
/**
* Get latest package version.
* [📘](https://github.com/nodef/extra-build/wiki/latestVersion)
* @param name package name
* @returns latest package version
*/
declare function latestVersion(name: string): string;
/**
* Get next unpublished version for package.
* [📘](https://github.com/nodef/extra-build/wiki/nextUnpublishedVersion)
* @param name package name
* @param ver package version
* @returns next unpublished version
*/
declare function nextUnpublishedVersion(name: string, ver: string): string;
/**
* Publish package to NPM.
* [📘](https://github.com/nodef/extra-build/wiki/publish)
* @param dir package directory
*/
declare function publish(dir?: string): void;
/**
* Publish package to GitHub.
* [📘](https://github.com/nodef/extra-build/wiki/publishGithub)
* @param dir package directory
* @param owner owner name
*/
declare function publishGithub(dir: string, owner: string): void;
/**
* Generate docs using typedoc.
* [📘](https://github.com/nodef/extra-build/wiki/generateDocs)
* @param src main source file
* @param out output directory
*/
declare function generateDocs(src: string, out?: string): void;
/**
* Publish docs to gh-pages.
* [📘](https://github.com/nodef/extra-build/wiki/publishDocs)
* @param dir docs directory
*/
declare function publishDocs(dir?: string): void;
/**
* Get the reflection that is referred to.
* [📘](https://github.com/nodef/extra-build/wiki/docsRefer)
* @param docs docs reflection
* @param r reflection
* @returns referred reflection, or the same if nothing is referred
*/
declare function docsRefer(docs: ProjectReflection, r: T): T;
/**
* Get name of a reflection.
* [📘](https://github.com/nodef/extra-build/wiki/docsName)
* @param r reflection
* @returns reflection name
*/
declare function docsName(r: Reflection): string;
/**
* Get location of reflection.
* [📘](https://github.com/nodef/extra-build/wiki/docsLocation)
* @param r reflection
* @returns location of reflection
*/
declare function docsLocation(r: Reflection): string;
/**
* Get flags of a reflection.
* [📘](https://github.com/nodef/extra-build/wiki/docsFlags)
* @param r reflection
* @returns flags
*/
declare function docsFlags(r: Reflection): ReflectionFlags;
/**
* Get kind name of a reflection.
* [📘](https://github.com/nodef/extra-build/wiki/docsKind)
* @param r reflection
* @returns kind name
*/
declare function docsKind(r: Reflection): string;
/**
* Get child count of a reflection.
* [📘](https://github.com/nodef/extra-build/wiki/docsChildCount)
* @param r reflection
* @returns child count
*/
declare function docsChildCount(r: Reflection): number;
/**
* Get parameter count of a reflection (function).
* [📘](https://github.com/nodef/extra-build/wiki/docsParameterCount)
* @param r reflection
* @returns parameter count
*/
declare function docsParameterCount(r: Reflection): number;
/**
* Get signature count of a reflection.
* [📘](https://github.com/nodef/extra-build/wiki/docsSignatureCount)
* @param r reflection
* @returns signature count
*/
declare function docsSignatureCount(r: Reflection): number;
/**
* Get type name of a reflection.
* [📘](https://github.com/nodef/extra-build/wiki/docsType)
* @param r reflection
* @returns type name
*/
declare function docsType(r: Reflection, sig?: number): string;
/**
* Get description of a reflection.
* [📘](https://github.com/nodef/extra-build/wiki/docsDescription)
* @param r reflection
* @param sig signature index
* @returns description/comment
*/
declare function docsDescription(r: Reflection, sig?: number): string;
/**
* Get returns description of a reflection (function).
* [📘](https://github.com/nodef/extra-build/wiki/docsReturns)
* @param r reflection
* @param sig signature index
* @returns returns description/comment
*/
declare function docsReturns(r: Reflection, sig?: number): string;
/**
* Details of a reflection.
* [📘](https://github.com/nodef/extra-build/wiki/DocsDetails)
*/
interface DocsDetails {
/** Name of a reflection. */
name: string;
/** Location of reflection. */
location?: string;
/** Flags of a reflection. */
flags: ReflectionFlags;
/** Kind name of a reflection */
kind: string;
/** Type name of a reflection. */
type: string;
/** Description/comment of a reflection. */
description?: string;
/** Details of children/signatures/parameters of a reflection. */
children?: DocsDetails[];
/** Return details/comment of a reflection (function). */
returns?: string;
}
/**
* Get details of a reflection.
* [📘](https://github.com/nodef/extra-build/wiki/docsDetails)
* @param r reflection
* @returns reflection details \{name, kind, type, description, params, returns\}
*/
declare function docsDetails(r: Reflection): DocsDetails;
/**
* Get details of a reflection, referring the necessary details.
* [📘](https://github.com/nodef/extra-build/wiki/docsReferDetails)
* @param docs docs reflection
* @param r reflection
* @returns reflection details \{name, kind, type, description, params, returns\}
*/
declare function docsReferDetails(docs: ProjectReflection, r: Reflection): DocsDetails;
/**
* Load docs from source file.
* [📘](https://github.com/nodef/extra-build/wiki/loadDocs)
* @param entryPoints entry source files
* @returns docs reflection
*/
declare function loadDocs(entryPoints?: string[]): ProjectReflection;
/**
* Markdown options.
* [📘](https://github.com/nodef/extra-build/wiki/MarkdownOptions)
*/
interface MarkdownOptions {
/** GitHub owner name. [owner] */
owner?: string;
/** GitHub repo name. [repo] */
repo?: string;
/** Use wiki links? [false] */
useWiki?: boolean;
/** Namespace prefix. */
prefix?: string;
/** Wrap comment text after. [0 => unlimited] */
wrapText?: number;
/** Include types? [false] */
withType?: boolean;
/** Include root description? [false] */
withDescription?: boolean;
}
/**
* Generate reference code block for wiki.
* [📘](https://github.com/nodef/extra-build/wiki/wikiCodeReference)
* @param d docs details
* @param o markdown options
* @returns reference code block
*/
declare function wikiCodeReference(d: DocsDetails, o?: MarkdownOptions): string;
/**
* Generate example code block for wiki.
* [📘](https://github.com/nodef/extra-build/wiki/wikiCodeExample)
* @param d docs details
* @param o markdown options
* @returns example code block
*/
declare function wikiCodeExample(d: DocsDetails, o?: MarkdownOptions): string;
/**
* Generate markdown text for wiki.
* [📘](https://github.com/nodef/extra-build/wiki/wikiMarkdown)
* @param d docs details
* @param o markdown options
* @returns markdown text
*/
declare function wikiMarkdown(d: DocsDetails, o?: MarkdownOptions): string;
/**
* Perform operation on docs details.
* [📘](https://github.com/nodef/extra-build/wiki/OnDocsDetails)
* @param d docs details
* @returns resulting value
*/
type OnDocsDetails = (d: DocsDetails) => T;
/**
* Update the "Index" (property, description) table in markdown text.
* [📘](https://github.com/nodef/extra-build/wiki/wikiUpdateIndex)
* @param txt markdown text
* @param dm docs details map
* @returns updated markdown text
*/
declare function wikiUpdateIndex(txt: string, dm: Map, fn?: OnDocsDetails): string;
/**
* Update link references in markdown text.
* [📘](https://github.com/nodef/extra-build/wiki/wikiUpdateLinkReferences)
* @param txt markdown text
* @param dm docs details map
* @param o markdown options
* @returns updated markdown text
*/
declare function wikiUpdateLinkReferences(txt: string, dm: Map, o?: MarkdownOptions): string;
/**
* Update description in markdown text.
* [📘](https://github.com/nodef/extra-build/wiki/wikiUpdateDescription)
* @param txt markdown text
* @param d docs details
* @returns updated markdown text
*/
declare function wikiUpdateDescription(txt: string, d: DocsDetails): string;
/**
* Update code reference in markdown text.
* [📘](https://github.com/nodef/extra-build/wiki/wikiUpdateCodeReference)
* @param txt markdown text
* @param d docs details
* @param o markdown options
* @returns updated markdown text
*/
declare function wikiUpdateCodeReference(txt: string, d: DocsDetails, o?: MarkdownOptions): string;
export { BundleOptions, DocsDetails, Document, ExecOptions, GitCommitPushOptions, GitSetupBranchOptions, GithubRepoDetails, GithubUrlDetails, JsdocToken, MarkdownOptions, OnDocsDetails, OnJsdocToken, WebifyOptions, addBanner, bundleScript, docsChildCount, docsDescription, docsDetails, docsFlags, docsKind, docsLocation, docsName, docsParameterCount, docsRefer, docsReferDetails, docsReturns, docsSignatureCount, docsType, error, exec, execStr, generateDocs, gitCommitPush, gitSetupBranch, info, jsdocifyScript, keywordname, latestVersion, loadDocs, log, nextUnpublishedVersion, parseGithubUrl, publish, publishDocs, publishGithub, readDocument, readFileText, readJson, readMetadata, registry, setRegistry, symbolname, updateGithubRepoDetails, warn, webifyScript, wikiCodeExample, wikiCodeReference, wikiMarkdown, wikiUpdateCodeReference, wikiUpdateDescription, wikiUpdateIndex, wikiUpdateLinkReferences, writeDocument, writeFileText, writeJson, writeMetadata };