@appium/docutils 0.1.6 → 0.2.0

package/lib/cli/command/init.ts

@@ -0,0 +1,166 @@
+import _ from 'lodash';
+import {CommandModule, InferredOptionTypes, Options} from 'yargs';
+import {init} from '../../init';
+import logger from '../../logger';
+import {stopwatch} from '../../util';
+
+const log = logger.withTag('init');
+
+const NAME_GROUP_INIT_MKDOCS = 'MkDocs Config:';
+const NAME_GROUP_INIT_PATHS = 'Paths:';
+const NAME_GROUP_INIT_BEHAVIOR = 'Initialization Behavior:';
+
+const opts = {
+  copyright: {
+    description: 'Copyright notice',
+    group: NAME_GROUP_INIT_MKDOCS,
+    nargs: 1,
+    requiresArg: true,
+    type: 'string',
+  },
+  dir: {
+    default: '.',
+    defaultDescription: '(current directory)',
+    description: 'Directory of package',
+    group: NAME_GROUP_INIT_PATHS,
+    normalize: true,
+    type: 'string',
+  },
+  'dry-run': {
+    describe: 'Do not write any files; show what would be done',
+    group: NAME_GROUP_INIT_BEHAVIOR,
+    type: 'boolean',
+  },
+  force: {
+    alias: 'f',
+    describe: 'Overwrite existing configurations',
+    group: NAME_GROUP_INIT_BEHAVIOR,
+    type: 'boolean',
+  },
+  include: {
+    alias: 'i',
+    array: true,
+    coerce: (value: string | string[]) => _.castArray(value),
+    description: 'Files to include in compilation (globs OK)',
+    nargs: 1,
+    requiresArg: true,
+    type: 'string',
+  },
+  mkdocs: {
+    default: true,
+    description: 'Create mkdocs.yml if needed',
+    group: NAME_GROUP_INIT_BEHAVIOR,
+    type: 'boolean',
+  },
+  'mkdocs-yml': {
+    defaultDescription: './mkdocs.yml',
+    description: 'Path to mkdocs.yml',
+    group: NAME_GROUP_INIT_PATHS,
+    nargs: 1,
+    normalize: true,
+    requiresArg: true,
+    type: 'string',
+  },
+  'package-json': {
+    defaultDescription: './package.json',
+    describe: 'Path to package.json',
+    group: NAME_GROUP_INIT_PATHS,
+    nargs: 1,
+    normalize: true,
+    requiresArg: true,
+    type: 'string',
+  },
+  python: {
+    default: true,
+    description: 'Install Python dependencies if needed',
+    group: NAME_GROUP_INIT_BEHAVIOR,
+    type: 'boolean',
+  },
+  'python-path': {
+    defaultDescription: '(derived from shell)',
+    description: 'Path to python 3 executable',
+    group: NAME_GROUP_INIT_PATHS,
+    nargs: 1,
+    normalize: true,
+    requiresArg: true,
+    type: 'string',
+  },
+  'repo-name': {
+    defaultDescription: '(derived from --repo-url)',
+    description: 'Name of extension repository',
+    group: NAME_GROUP_INIT_MKDOCS,
+    nargs: 1,
+    requiresArg: true,
+    type: 'string',
+  },
+  'repo-url': {
+    defaultDescription: '(from package.json)',
+    description: 'URL of extension repository',
+    group: NAME_GROUP_INIT_MKDOCS,
+    nargs: 1,
+    requiresArg: true,
+    type: 'string',
+  },
+  'site-description': {
+    defaultDescription: '(from package.json)',
+    description: 'Site description',
+    group: NAME_GROUP_INIT_MKDOCS,
+    nargs: 1,
+    requiresArg: true,
+    type: 'string',
+  },
+  'site-name': {
+    defaultDescription: '(extension package name)',
+    description: 'Name of site',
+    group: NAME_GROUP_INIT_MKDOCS,
+    nargs: 1,
+    requiresArg: true,
+    type: 'string',
+  },
+  'tsconfig-json': {
+    defaultDescription: './tsconfig.json',
+    describe: 'Path to tsconfig.json',
+    group: NAME_GROUP_INIT_PATHS,
+    nargs: 1,
+    normalize: true,
+    requiresArg: true,
+    type: 'string',
+  },
+  typedoc: {
+    default: true,
+    description: 'Create typedoc.json if needed',
+    group: NAME_GROUP_INIT_BEHAVIOR,
+    type: 'boolean',
+  },
+  'typedoc-json': {
+    defaultDescription: './typedoc.json',
+    describe: 'Path to typedoc.json',
+    group: NAME_GROUP_INIT_PATHS,
+    nargs: 1,
+    normalize: true,
+    requiresArg: true,
+    type: 'string',
+  },
+  typescript: {
+    default: true,
+    description: 'Create tsconfig.json if needed',
+    group: NAME_GROUP_INIT_BEHAVIOR,
+    type: 'boolean',
+  },
+} as const;
+opts as Record<string, Options>; // type check
+
+type InitOptions = InferredOptionTypes<typeof opts>;
+
+const initCommand: CommandModule<{}, InitOptions> = {
+  command: 'init',
+  describe: 'Initialize package for doc generation',
+  builder: opts,
+  async handler(args) {
+    const done = stopwatch('init');
+    await init({...args, overwrite: args.force, cwd: args.dir});
+    log.success('Done (%dms)', done());
+  },
+};
+
+export default initCommand;

package/lib/cli/command/validate.ts

@@ -0,0 +1,122 @@
+import pluralize from 'pluralize';
+import {CommandModule, InferredOptionTypes, Options} from 'yargs';
+import {DocutilsError} from '../../error';
+import {DocutilsValidator, ValidationKind} from '../../validate';
+import logger from '../../logger';
+
+const log = logger.withTag('validate');
+
+const NAME_GROUP_VALIDATE = 'Validation Behavior:';
+const NAME_GROUP_VALIDATE_PATHS = 'Paths:';
+
+const opts = {
+  mkdocs: {
+    default: true,
+    description: 'Validate MkDocs environment',
+    group: NAME_GROUP_VALIDATE,
+    type: 'boolean',
+  },
+  'mkdocs-yml': {
+    defaultDescription: './mkdocs.yml',
+    description: 'Path to mkdocs.yml',
+    group: NAME_GROUP_VALIDATE_PATHS,
+    nargs: 1,
+    normalize: true,
+    requiresArg: true,
+    type: 'string',
+  },
+  'npm-path': {
+    defaultDescription: '(derived from shell)',
+    description: 'Path to npm executable',
+    group: NAME_GROUP_VALIDATE_PATHS,
+    nargs: 1,
+    normalize: true,
+    requiresArg: true,
+    type: 'string',
+  },
+  python: {
+    default: true,
+    description: 'Validate Python 3 environment',
+    group: NAME_GROUP_VALIDATE,
+    type: 'boolean',
+  },
+  'python-path': {
+    defaultDescription: '(derived from shell)',
+    description: 'Path to python 3 executable',
+    group: NAME_GROUP_VALIDATE_PATHS,
+    nargs: 1,
+    normalize: true,
+    requiresArg: true,
+    type: 'string',
+  },
+  'tsconfig-json': {
+    defaultDescription: './tsconfig.json',
+    describe: 'Path to tsconfig.json',
+    group: NAME_GROUP_VALIDATE_PATHS,
+    nargs: 1,
+    normalize: true,
+    requiresArg: true,
+    type: 'string',
+  },
+  typedoc: {
+    default: true,
+    description: 'Validate TypoDoc environment',
+    group: NAME_GROUP_VALIDATE,
+    type: 'boolean',
+  },
+  'typedoc-json': {
+    defaultDescription: './typedoc.json',
+    describe: 'Path to typedoc.json',
+    group: NAME_GROUP_VALIDATE_PATHS,
+    nargs: 1,
+    normalize: true,
+    requiresArg: true,
+    type: 'string',
+  },
+  typescript: {
+    default: true,
+    description: 'Validate TypeScript environment',
+    group: NAME_GROUP_VALIDATE,
+    type: 'boolean',
+  },
+} as const;
+opts as Record<string, Options>;
+type ValidateOptions = InferredOptionTypes<typeof opts>;
+const validateCommand: CommandModule<{}, ValidateOptions> = {
+  command: 'validate',
+  describe: 'Validate Environment',
+  builder: opts,
+  async handler(args) {
+    if (!args.python && !args.typedoc && !args.typescript && !args.mkdocs) {
+      // specifically not a DocutilsError
+      throw new Error(
+        'No validation targets specified; one or more of --python, --typescript, --typedoc or --mkdocs must be provided'
+      );
+    }
+
+    let errorCount = 0;
+    const validator = new DocutilsValidator(args)
+      .once(DocutilsValidator.BEGIN, (kinds: ValidationKind[]) => {
+        log.info(`Validating: ${kinds.join(', ')}`);
+      })
+      .once(DocutilsValidator.END, (errCount: number) => {
+        errorCount = errCount;
+      })
+      .on(DocutilsValidator.FAILURE, (err: DocutilsError) => {
+        log.error(err.message);
+      })
+      .on(DocutilsValidator.SUCCESS, (msg: string) => {
+        log.success(msg);
+      });
+
+    await validator.validate();
+
+    if (errorCount) {
+      throw new DocutilsError(
+        `Validation failed with ${errorCount} ${pluralize('error', errorCount)}`
+      );
+    }
+  },
+};
+
+export default validateCommand;

package/lib/cli/config.ts

@@ -0,0 +1,89 @@
+/**
+ * Handles reading of a config file for docutils
+ * @module
+ */
+
+import loadTs from '@sliphua/lilconfig-ts-loader';
+import {LogLevel} from 'consola';
+import {lilconfig, Loader} from 'lilconfig';
+import _ from 'lodash';
+import path from 'node:path';
+import YAML from 'yaml';
+import parser from 'yargs-parser';
+import {hideBin} from 'yargs/helpers';
+import {NAME_BIN} from '../constants';
+import logger from '../logger';
+import {relative} from '../util';
+const log = logger.withTag('config');
+
+/**
+ * `lilconfig` loader for YAML
+ */
+const loadYaml: Loader = _.rearg(YAML.parse, [2, 0, 1]);
+/**
+ * `lilconfig` loader for ESM/CJS
+ */
+const loadEsm: Loader = (filepath: string) => import(filepath);
+
+/**
+ * Controls how we load/find a config file.
+ *
+ * Takes _raw_ args from the CLI, and uses `yargs-parser` to parse them as to not interfere with the
+ * main usage of args.
+ *
+ * We're looking for various things in the CLI args:
+ * - `--no-config` - if this is present, we don't load a config file
+ * - `--log-level` - if this is present, we set the log level
+ * - `--verbose` - same as above
+ * - `--config` - if this is present, we load the config file at the given path
+ * - `--help`, `--version` - do nothing
+ * @param argv Raw CLI args
+ * @returns
+ */
+export async function findConfig(argv: string[] = hideBin(process.argv)) {
+  const preArgs = parser(argv);
+
+  if (preArgs.verbose || preArgs.logLevel === 'debug') {
+    log.level = LogLevel.Debug;
+  }
+
+  return preArgs.noConfig || preArgs.help || preArgs.version
+    ? {}
+    : await loadConfig(preArgs.config as string | undefined);
+}
+
+/**
+ * Loads a config file or finds and loads one if none provided
+ * @param filepath Config file path, if provided
+ * @param cwd Current working directory
+ * @returns A config object or an empty object. Could be anything; `yargs` will validate it.
+ */
+export async function loadConfig(filepath?: string, cwd = process.cwd()): Promise<any> {
+  const relativePath = relative(cwd);
+  const searcher = lilconfig(NAME_BIN, {
+    loaders: {
+      '.yaml': loadYaml,
+      '.yml': loadYaml,
+      '.ts': loadTs,
+      '.js': loadEsm,
+      '.cjs': loadEsm,
+      '.mjs': loadEsm,
+    },
+  });
+
+  const result = filepath
+    ? await searcher.load(path.normalize(filepath))
+    : await searcher.search(cwd);
+  if (result === null) {
+    log.debug('No config found');
+    return {};
+  }
+  if (result.isEmpty) {
+    log.debug('Config loaded at %s but it was empty', result.filepath);
+    return {};
+  }
+  const relFilepath = relativePath(result.filepath);
+  log.success('Loaded config from %s', relFilepath);
+  log.debug('Config contents: %O', result.config);
+  return result.config;
+}

package/lib/cli/index.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import logger from '../logger';
+
+import _ from 'lodash';
+import {hideBin} from 'yargs/helpers';
+import yargs from 'yargs/yargs';
+import {DEFAULT_LOG_LEVEL, LogLevelMap, NAME_BIN} from '../constants';
+import {DocutilsError} from '../error';
+import {build, init, validate} from './command';
+import {findConfig} from './config';
+
+const log = logger.withTag('cli');
+export async function main(argv = hideBin(process.argv)) {
+  const config = await findConfig(argv);
+
+  const y = yargs(argv);
+  return await y
+    .scriptName(NAME_BIN)
+    .command(build)
+    .command(init)
+    .command(validate)
+    .options({
+      verbose: {
+        type: 'boolean',
+        describe: 'Alias for --log-level=debug',
+      },
+      'log-level': {
+        alias: 'L',
+        choices: ['debug', 'info', 'warn', 'error', 'silent'],
+        describe: 'Sets the log level',
+        default: DEFAULT_LOG_LEVEL,
+        coerce: _.identity as (x: string) => keyof typeof LogLevelMap,
+      },
+      config: {
+        alias: 'c',
+        type: 'string',
+        describe: 'Path to config file',
+        normalize: true,
+        nargs: 1,
+        requiresArg: true,
+        defaultDescription: '(discovered automatically)',
+      },
+      'no-config': {
+        type: 'boolean',
+        describe: 'Disable config file discovery',
+      },
+    })
+    .middleware(
+      /**
+       * Configures logging; `--verbose` implies `--log-level=debug`
+       */
+      (argv) => {
+        if (argv.verbose) {
+          argv.logLevel = 'debug';
+          log.debug('Debug logging enabled via --verbose');
+        }
+        log.level = LogLevelMap[argv.logLevel];
+      }
+    )
+    .fail(
+      /**
+       * Custom failure handler so we can log nicely.
+       */
+      (msg: string | null, error) => {
+        // if it is a DocutilsError, it has nothing to do with the CLI
+        if (error instanceof DocutilsError) {
+          log.error(error.message);
+        } else {
+          y.showHelp();
+          log.error(msg ?? error.message);
+        }
+        y.exit(1, error);
+      }
+    )
+    .config(config)
+    // at least one command is required (but not for --version or --help)
+    .demandCommand(1)
+    // fail if unknown option or command is provided
+    .strict()
+    .parseAsync();
+}
+
+if (require.main === module) {
+  // eslint-disable-next-line promise/prefer-await-to-then
+  main().catch((err) => {
+    log.error('Caught otherwise-unhandled rejection (this is probably a bug):', err);
+  });
+}

package/lib/constants.ts

@@ -0,0 +1,150 @@
+/**
+ * Constants used across various modules in this package
+ * @module
+ */
+import {LogLevel} from 'consola';
+import {readFileSync} from 'node:fs';
+import {fs} from '@appium/support';
+import path from 'node:path';
+import {PackageJson} from 'type-fest';
+
+/**
+ * CLI executable name
+ */
+export const NAME_BIN = 'appium-docs';
+
+/**
+ * Expected name of the `mkdocs.yml` config file
+ */
+export const NAME_MKDOCS_YML = 'mkdocs.yml';
+
+/**
+ * Default name of the `tsconfig.json` config file
+ */
+export const NAME_TSCONFIG_JSON = 'tsconfig.json';
+/**
+ * `python` executable
+ */
+export const NAME_PYTHON = 'python';
+/**
+ * Default name of the `typedoc.json` config file
+ */
+export const NAME_TYPEDOC_JSON = 'typedoc.json';
+/**
+ * It's `package.json`!
+ */
+export const NAME_PACKAGE_JSON = 'package.json';
+/**
+ * Name of the `requirements.txt` file for `pip`
+ */
+export const NAME_REQUIREMENTS_TXT = 'requirements.txt';
+/**
+ * Name of the `$schema` property which can be present in JSON files; it may need to be removed to
+ * avoid warnings/errors by 3p libs
+ */
+export const NAME_SCHEMA = '$schema';
+/**
+ * Name of the `mkdocs` executable
+ */
+export const NAME_MKDOCS = 'mkdocs';
+
+/**
+ * Name of the `mike` executable
+ */
+export const NAME_MIKE = 'mike';
+
+/**
+ * Name of the `typedoc` executable
+ */
+export const NAME_TYPEDOC = 'typedoc';
+
+/**
+ * Name of the `pip` module.
+ *
+ * @remarks We don't execute the `pip` executable; but rather use `python -m pip` since that seems
+ * to work better ... on my computer.
+ */
+export const NAME_PIP = 'pip';
+
+/**
+ * Name of the `npm` executable, which we use to check for
+ */
+export const NAME_NPM = 'npm';
+
+/**
+ * The name of the `typescript` package (not the `tsc` executable)
+ */
+export const NAME_TYPESCRIPT = 'typescript';
+
+/**
+ * Code for a "file not found" error
+ */
+export const NAME_ERR_ENOENT = 'ENOENT';
+
+/**
+ * Code for a "file already exists" error
+ */
+export const NAME_ERR_EEXIST = 'EEXIST';
+
+/**
+ * Default log level
+ */
+export const DEFAULT_LOG_LEVEL = 'info';
+/**
+ * Blocking I/O
+ */
+export const PKG_ROOT_DIR = fs.findRoot(__dirname);
+/**
+ * Blocking I/O
+ */
+
+export const DOCUTILS_PKG: PackageJson = JSON.parse(
+  readFileSync(path.join(PKG_ROOT_DIR, NAME_PACKAGE_JSON), 'utf8')
+);
+
+/**
+ * Path to the `requirements.txt` file (in this package)
+ */
+
+export const REQUIREMENTS_TXT_PATH = path.join(PKG_ROOT_DIR, NAME_REQUIREMENTS_TXT);
+
+/**
+ * The default output path for Typedoc, computed relative to the consuming package's root
+ */
+export const DEFAULT_REL_TYPEDOC_OUT_PATH = path.join('docs', 'reference');
+
+/**
+ * The default branch to deploy to
+ */
+export const DEFAULT_DEPLOY_BRANCH = 'gh-pages';
+
+/**
+ * The default remote to push the deployed branch to
+ */
+export const DEFAULT_DEPLOY_REMOTE = 'origin';
+
+/**
+ * The default port for serving docs
+ */
+export const DEFAULT_SERVE_PORT = 8000;
+
+/**
+ * The default host for serving docs
+ */
+export const DEFAULT_SERVE_HOST = 'localhost';
+
+/**
+ * Mapping of `@appium/docutils`' log levels to `consola` log levels
+ */
+export const LogLevelMap = {
+  silent: LogLevel.Silent,
+  error: LogLevel.Error,
+  warn: LogLevel.Warn,
+  info: LogLevel.Info,
+  debug: LogLevel.Debug,
+} as const;
+
+/**
+ * Default site nav header text
+ */
+export const DEFAULT_NAV_HEADER = 'Reference';

package/lib/error.ts

@@ -0,0 +1 @@
+export class DocutilsError extends Error {}