balena-cli/automation/capitanodoc/utils.ts

/**
 * @license
 * Copyright 2019 Balena Ltd.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import { OptionDefinition } from 'capitano';
import * as ent from 'ent';
import * as fs from 'fs';
import * as _ from 'lodash';
import * as readline from 'readline';

export function getOptionPrefix(signature: string) {
	if (signature.length > 1) {
		return '--';
	} else {
		return '-';
	}
}

export function getOptionSignature(signature: string) {
	return `${getOptionPrefix(signature)}${signature}`;
}

export function parseCapitanoOption(option: OptionDefinition): string {
	let result = getOptionSignature(option.signature);

	if (_.isArray(option.alias)) {
		for (const alias of option.alias) {
			result += `, ${getOptionSignature(alias)}`;
		}
	} else if (_.isString(option.alias)) {
		result += `, ${getOptionSignature(option.alias)}`;
	}

	if (option.parameter) {
		result += ` <${option.parameter}>`;
	}

	return ent.encode(result);
}

/** Convert e.g. 'env add NAME [VALUE]' to 'env add <name> [value]' */
export function capitanoizeOclifUsage(
	oclifUsage: string | string[] | undefined,
): string {
	return (oclifUsage || '')
		.toString()
		.replace(/(?<=\s)[A-Z]+(?=(\s|$))/g, match => `<${match}>`)
		.toLowerCase();
}

export class MarkdownFileParser {
	constructor(public mdFilePath: string) {}

	/**
	 * Extract the lines of a markdown document section with the given title.
	 * For example, consider this sample markdown document:
	 * ```
	 *     # balena CLI
	 *
	 *     ## Introduction
	 *     Lorem ipsum dolor sit amet, consectetur adipiscing elit,
	 *
	 *     ## Getting Started
	 *     sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
	 *
	 *     ### Prerequisites
	 *     - Foo
	 *     - Bar
	 *
	 *     ## Support
	 *     Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.
	 * ```
	 *
	 * Calling getSectionOfTitle('Getting Started') for the markdown doc above
	 * returns everything from line '## Getting Started' (included) to line
	 * '## Support' (excluded). This method counts the number of '#' characters
	 * to determine that subsections should be included as part of the parent
	 * section.
	 *
	 * @param title The section title without '#' chars, eg. 'Getting Started'
	 */
	public async getSectionOfTitle(
		title: string,
		includeSubsections = true,
	): Promise<string> {
		let foundSectionLines: string[];
		let foundSectionLevel = 0;

		const rl = readline.createInterface({
			input: fs.createReadStream(this.mdFilePath),
			crlfDelay: Infinity,
		});

		rl.on('line', line => {
			// try to match a line like "## Getting Started", where the number
			// of '#' characters is the sectionLevel ('##' -> 2), and the
			// sectionTitle is "Getting Started"
			const match = /^(#+)\s+(.+)/.exec(line);
			if (match) {
				const sectionLevel = match[1].length;
				const sectionTitle = match[2];

				// If the target section had already been found: append a line, or end it
				if (foundSectionLines) {
					if (!includeSubsections || sectionLevel <= foundSectionLevel) {
						// end previously found section
						rl.close();
					}
				} else if (sectionTitle === title) {
					// found the target section
					foundSectionLevel = sectionLevel;
					foundSectionLines = [];
				}
			}
			if (foundSectionLines) {
				foundSectionLines.push(line);
			}
		});

		return await new Promise((resolve, reject) => {
			rl.on('close', () => {
				if (foundSectionLines) {
					resolve(foundSectionLines.join('\n'));
				} else {
					reject(
						new Error(
							`Markdown section not found: title="${title}" file="${
								this.mdFilePath
							}"`,
						),
					);
				}
			});
		});
	}
}