From 2bd641ee757d2a44b2c5c8d8a5bcba8f75a52c2a Mon Sep 17 00:00:00 2001 From: Bryan MacFarlane Date: Thu, 16 May 2019 18:45:34 -0700 Subject: [PATCH 1/2] Spec for tool config apis (#3) * creating an initial branch for config apis spec * Add package specs * mkdirP should return promise * Which should return a promise * Respond to feedback * export => exportVariable * Respond to feedback on spec * Remove code for now * trailing space * Clarify throwing --- docs/package-specs.md | 200 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 docs/package-specs.md diff --git a/docs/package-specs.md b/docs/package-specs.md new file mode 100644 index 00000000..21861fb0 --- /dev/null +++ b/docs/package-specs.md @@ -0,0 +1,200 @@ +# Package Specs + +In order to support the node-config action, I propose adding the following into 4 libraries (tool-cache, core, io, exec), with tool-cache having dependencies on the other 3 libs: + +### Core spec + +Holds all the functions necessary for interacting with the runner/environment. + +``` +// Logging functions +export function debug(message: string): void +export function warning(message: string): void +export function error(message: string): void + +/** + * Interface for exportVariable options + */ +export interface ExportOptions { + /** Optional. Whether the variable should be marked as secret (will be masked from logs). Defaults to false */ + isSecret?: bool; +} + +/** + * sets env variable for this action and future actions in the job + * + * @param name the name of the variable to set + * @param val the value of the variable + * @param options optional. See ExportOptions. + */ +export function exportVariable(name: string, val: string, options?: ExportOptions): void + +/** + * Interface for getInput options + */ +export interface InputOptions { + /** Optional. Whether the input is required. If required and not present, will throw. Defaults to false */ + required?: bool; +} + +/** + * Gets the value of an input. The value is also trimmed. + * + * @param name name of the input to get + * @param options optional. See InputOptions. + * @returns string + */ +export function getInput(name: string, options?: InputOptions): string | undefined + +/** + * fail the action + * @param message + */ +export function setFailure(message: string): void +``` + +### IO spec + +Holds all the functions necessary for file system manipulation (cli scenarios, not fs replacements): + +``` +/** + * Interface for cp/mv options + */ +export interface CopyOptions { + /** Optional. Whether to recursively copy all subdirectories. Defaults to false */ + recursive?: boolean; + /** Optional. Whether to overwrite existing files in the destination. Defaults to true */ + force?: boolean; +} + +/** + * Copies a file or folder. + * + * @param source source path + * @param dest destination path + * @param options optional. See CopyOptions. + */ +export function cp(source: string, dest: string, options?: CopyOptions): Promise + +/** + * Remove a path recursively with force + * + * @param path path to remove + */ +export function rmRF(path: string): Promise + +/** + * Make a directory. Creates the full path with folders in between + * + * @param p path to create + * @returns Promise + */ +export function mkdirP(p: string): Promise + +/** + * Moves a path. + * + * @param source source path + * @param dest destination path + * @param options optional. See CopyOptions. + */ +export function mv(source: string, dest: string, options?: CopyOptions): Promise + +/** + * Interface for which options + */ +export interface WhichOptions { + /** Optional. Whether to check if tool exists. If true, will throw if it fails. Defaults to false */ + check?: boolean; +} + +/** + * Returns path of a tool had the tool actually been invoked. Resolves via paths. + * + * @param tool name of the tool + * @param options optional. See WhichOptions. + * @returns Promise path to tool + */ +export function which(tool: string, options?: WhichOptions): Promise +``` + +### Exec spec + +Holds all the functions necessary for running the tools node-config depends on (aka 7-zip and tar) + +``` +/** + * Interface for exec options + */ +export interface IExecOptions + +/** +* Exec a command. +* Output will be streamed to the live console. +* Returns promise with return code +* +* @param commandLine command to execute +* @param args optional additional arguments +* @param options optional exec options. See IExecOptions +* @returns Promise return code +*/ +export function exec(commandLine: string, args?: string[], options?: IExecOptions): Promise +``` + +### Tool-Cache spec: + +Holds all the functions necessary for downloading and caching node. + +``` +/** + * Download a tool from an url and stream it into a file + * + * @param url url of tool to download + * @returns path to downloaded tool + */ +export async function downloadTool(url: string): Promise + +/** + * Extract a .7z file + * + * @param file path to the .7z file + * @param dest destination directory. Optional. + * @returns path to the destination directory + */ +export async function extract7z(file: string, dest?: string): Promise + +/** + * Extract a tar + * + * @param file path to the tar + * @param dest destination directory. Optional. + * @returns path to the destination directory + */ +export async function extractTar(file: string, destination?: string): Promise + +/** + * Caches a directory and installs it into the tool cacheDir + * + * @param sourceDir the directory to cache into tools + * @param tool tool name + * @param version version of the tool. semver format + * @param arch architecture of the tool. Optional. Defaults to machine architecture + */ +export async function cacheDir(sourceDir: string, tool: string, version: string, arch?: string): Promise + +/** + * finds the path to a tool in the local installed tool cache + * + * @param toolName name of the tool + * @param versionSpec version of the tool + * @param arch optional arch. defaults to arch of computer + */ +export function find(toolName: string, versionSpec: string, arch?: string): string + +/** + * Prepends inputPath to the PATH + * @param inputPath + */ +export function addPath(inputPath: string): void +``` From 618a7ec0f801a1d02ba720db638a377ae8425546 Mon Sep 17 00:00:00 2001 From: Jonathan Clem Date: Mon, 20 May 2019 11:21:45 -0400 Subject: [PATCH 2/2] Change npm format to format-check and add format command --- .github/main.workflow | 2 +- package.json | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/main.workflow b/.github/main.workflow index 99b3568e..cf141b0f 100644 --- a/.github/main.workflow +++ b/.github/main.workflow @@ -23,7 +23,7 @@ action "Compile" { action "Format" { needs = "Dependencies" uses = "actions/npm@v2.0.0" - args = "run format" + args = "run format-check" } action "Test" { diff --git a/package.json b/package.json index c93a4cda..e4fc977b 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,8 @@ "scripts": { "bootstrap": "lerna bootstrap", "build": "lerna run tsc", - "format": "prettier --check packages/*/src/**/*.ts", + "format": "prettier --write packages/*/src/**/*.ts", + "format-check": "prettier --check packages/*/src/**/*.ts", "new-package": "scripts/create-package", "test": "jest" },