appium 3.2.1 → 3.3.0

package/lib/schema/cli-args.js

@@ -1,254 +0,0 @@
-import {ArgumentTypeError} from 'argparse';
-import _ from 'lodash';
-import {formatErrors} from '../config-file';
-import {flattenSchema, validate} from './schema';
-import {transformers, parseCsvLine} from './cli-transformers';
-
-/**
- * This module concerns functions which convert schema definitions to
- * `argparse`-compatible data structures, for deriving CLI arguments from a
- * schema.
- */
-
-/**
- * Lookup of possible values for the `type` field in a JSON schema.
- * @type {Readonly<Record<string, import('json-schema').JSONSchema7TypeName>>}
- */
-const TYPENAMES = Object.freeze({
-  ARRAY: 'array',
-  OBJECT: 'object',
-  BOOLEAN: 'boolean',
-  INTEGER: 'integer',
-  NUMBER: 'number',
-  NULL: 'null',
-  STRING: 'string',
-});
-
-/**
- * Options with alias lengths less than this will be considered "short" flags.
- */
-const SHORT_ARG_CUTOFF = 3;
-
-/**
- * Convert an alias (`foo`) to a flag (`--foo`) or a short flag (`-f`).
- * @param {ArgSpec} argSpec - the argument specification
- * @param {string} [alias] - the alias to convert to a flag
- * @returns {string} the flag
- */
-function aliasToFlag(argSpec, alias) {
-  const {extType, extName, name} = argSpec;
-  const arg = alias ?? name;
-  const isShort = arg.length < SHORT_ARG_CUTOFF;
-  if (extType && extName) {
-    return isShort
-      ? `--${extType}-${_.kebabCase(extName)}-${arg}`
-      : `--${extType}-${_.kebabCase(extName)}-${_.kebabCase(arg)}`;
-  }
-  return isShort ? `-${arg}` : `--${_.kebabCase(arg)}`;
-}
-
-/**
- * Converts a string to SCREAMING_SNAKE_CASE
- */
-const screamingSnakeCase = _.flow(_.snakeCase, _.toUpper);
-
-/**
- * Given unique property name `name`, return a function which validates a value
- * against a property within the schema.
- * @template Coerced
- * @param {ArgSpec} argSpec - Argument name
- * @param {(value: string) => Coerced} [coerce] - Function to coerce to a different
- * primitive
- * @todo See if we can remove `coerce` by allowing Ajv to coerce in its
- * constructor options
- * @returns
- */
-function getSchemaValidator({ref: schemaId}, coerce = _.identity) {
-  /** @param {string} value */
-  return (value) => {
-    const coerced = coerce(value);
-    const errors = validate(coerced, schemaId);
-    if (_.isEmpty(errors)) {
-      return coerced;
-    }
-    throw new ArgumentTypeError('\n\n' + formatErrors(errors, value, {schemaId}));
-  };
-}
-
-/**
- * Determine the description for display on the CLI, given the schema.
- * @param {AppiumJSONSchema} schema
- * @returns {string}
- */
-function makeDescription(schema) {
-  const {appiumCliDescription, description = '', appiumDeprecated} = schema;
-  let desc = appiumCliDescription ?? description;
-  if (appiumDeprecated) {
-    desc = `[DEPRECATED] ${desc}`;
-  }
-  return desc;
-}
-
-/**
- * Given arg `name`, a JSON schema `subSchema`, and options, return an argument definition
- * as understood by `argparse`.
- * @param {AppiumJSONSchema} subSchema - JSON schema for the option
- * @param {ArgSpec} argSpec - Argument spec tuple
- * @returns {[[string]|[string, string], import('argparse').ArgumentOptions]} Tuple of flag and options
- */
-function subSchemaToArgDef(subSchema, argSpec) {
-  let {type, appiumCliAliases, appiumCliTransformer, enum: enumValues} = subSchema;
-
-  const {name, arg} = argSpec;
-
-  const aliases = [
-    aliasToFlag(argSpec),
-    .../** @type {string[]} */ (appiumCliAliases ?? []).map((alias) => aliasToFlag(argSpec, alias)),
-  ];
-
-  /** @type {import('argparse').ArgumentOptions} */
-  let argOpts = {
-    required: false,
-    help: makeDescription(subSchema),
-  };
-
-  // argparse infers dest from the option string (e.g. --log-level → log_level).
-  // We need schema dest (e.g. loglevel) so merged server args and logsink use the right key.
-  if (!argSpec.extType) {
-    argOpts.dest = argSpec.rawDest;
-  }
-
-  /**
-   * Generally we will provide a `type` to `argparse` as a function which
-   * validates using ajv (which is much more full-featured than what `argparse`
-   * can offer). The exception is `boolean`-type options, which have no
-   * `argType`.
-   *
-   * Not sure if this type is correct, but it's not doing what I want.  I want
-   * to say "this is a function which returns something of type `T` where `T` is
-   * never a `Promise`".  This function must be sync.
-   * @type {((value: string) => unknown)|undefined}
-   */
-  let argTypeFunction;
-
-  // handle special cases for various types
-  switch (type) {
-    // booleans do not have a type per `ArgumentOptions`, just an "action"
-    // NOTE: due to limitations of `argparse`, we cannot provide fancy help text, and must rely on its internal error messaging.
-    case TYPENAMES.BOOLEAN: {
-      argOpts.action = 'store_const';
-      argOpts.const = true;
-      break;
-    }
-
-    case TYPENAMES.OBJECT: {
-      argTypeFunction = _.flow(transformers.json, (o) => {
-        // Arrays and plain strings are also valid JSON
-        if (!_.isPlainObject(o)) {
-          throw new ArgumentTypeError(`'${_.truncate(o, {length: 100})}' must be a plain object`);;
-        }
-        return o;
-      });
-      break;
-    }
-
-    // arrays are treated as CSVs, because `argparse` doesn't handle array data.
-    case TYPENAMES.ARRAY: {
-      argTypeFunction = parseCsvLine;
-      break;
-    }
-
-    // "number" type is coerced to float. `argparse` does this for us if we use `float` type, but
-    // we don't.
-    case TYPENAMES.NUMBER: {
-      argTypeFunction = getSchemaValidator(argSpec, parseFloat);
-      break;
-    }
-
-    // "integer" is coerced to an .. integer.  again, `argparse` would do this for us if we used `int`.
-    case TYPENAMES.INTEGER: {
-      argTypeFunction = getSchemaValidator(argSpec, _.parseInt);
-      break;
-    }
-
-    // strings (like number and integer) are subject to further validation
-    // (e.g., must satisfy a mask or regex or even some custom validation
-    // function)
-    case TYPENAMES.STRING: {
-      argTypeFunction = getSchemaValidator(argSpec);
-      break;
-    }
-
-    // TODO: there may be some way to restrict this at the Ajv level --
-    // that may involve patching the metaschema.
-    case TYPENAMES.NULL:
-    // falls through
-    default: {
-      throw new TypeError(`Schema property "${arg}": \`${type}\` type unknown or disallowed`);
-    }
-  }
-
-  // metavar is used in help text. `boolean` cannot have a metavar--it is not
-  // displayed--and `argparse` throws if you give it one.
-  if (type !== TYPENAMES.BOOLEAN) {
-    argOpts.metavar = screamingSnakeCase(name);
-  }
-
-  if (appiumCliTransformer && transformers[appiumCliTransformer]) {
-    if (type === TYPENAMES.ARRAY) {
-      const csvTransformer = /** @type {(x: string) => string[]} */ (argTypeFunction);
-      argTypeFunction = (val) => _.flatMap(csvTransformer(val).map(transformers[appiumCliTransformer]));
-    } else {
-      argTypeFunction = _.flow(argTypeFunction ?? _.identity, transformers[appiumCliTransformer]);
-    }
-  }
-
-  if (argTypeFunction) {
-    argOpts.type = argTypeFunction;
-  }
-
-  // convert JSON schema `enum` to `choices`. `enum` can contain any JSON type, but `argparse`
-  // is limited to a single type per arg (I think).  so let's make everything a string.
-  // and might as well _require_ the `type: string` while we're at it.
-  if (enumValues && !_.isEmpty(enumValues)) {
-    if (type === TYPENAMES.STRING) {
-      argOpts.choices = enumValues.map(String);
-    } else {
-      throw new TypeError(
-        `Problem with schema for ${arg}; \`enum\` is only supported for \`type: 'string'\``
-      );
-    }
-  }
-
-  // TODO: argparse only accepts the command name and a single alias; any extra aliases
-  // will be silently discarded.
-  const finalAliases = /** @type {[string]|[string, string]} */ (aliases);
-  return [finalAliases, argOpts];
-}
-
-/**
- * Converts the finalized, flattened schema representation into
- * ArgumentDefinitions for handoff to `argparse`.
- *
- * @throws If schema has not been added to ajv (via `finalizeSchema()`)
- * @returns {import('../cli/args').ArgumentDefinitions} A map of arrays of
- * aliases to `argparse` arguments; empty if no schema found
- */
-export function toParserArgs() {
-  const flattened = flattenSchema().filter(({schema}) => !schema.appiumCliIgnored);
-  return new Map(_.map(flattened, ({schema, argSpec}) => subSchemaToArgDef(schema, argSpec)));
-}
-
-/**
- * @template {string|number} T
- * @typedef {import('ajv/dist/types').FormatValidator<T>} FormatValidator<T>
- */
-
-/**
- * A JSON 7 schema with our custom keywords.
- * @typedef {import('./keywords').AppiumJSONSchemaKeywords & import('json-schema').JSONSchema7} AppiumJSONSchema
- */
-
-/**
- * @typedef {import('./arg-spec').ArgSpec} ArgSpec
- */

package/lib/schema/cli-transformers.js

@@ -1,113 +0,0 @@
-import {ArgumentTypeError} from 'argparse';
-import {readFileSync, existsSync} from 'node:fs';
-
-/**
- * This module provides custom keywords for Appium schemas, as well as
- * "transformers" (see `argTransformers` below).
- *
- * Custom keywords are just properties that will appear in a schema (e.g.,
- * `appium-config-schema.js`) beyond what the JSON Schema spec offers.  These
- * are usable by extensions, as well.
- */
-
-/**
- * Splits a CSV string into an array
- * @param {string} value
- * @returns {string[]}
- */
-export function parseCsvLine(value) {
-  return value
-    .split(',')
-    .map((v) => v.trim())
-    .filter(Boolean);
-}
-
-/**
- * Split a file by newline then calls {@link parseCsvLine} on each line.
- * @param {string} value
- * @returns {string[]}
- */
-function parseCsvFile(value) {
-  return value
-    .split(/\r?\n/)
-    .map((v) => v.trim())
-    .filter(Boolean)
-    .flatMap(parseCsvLine);
-}
-
-/**
- * Namespace containing _transformers_ for CLI arguments.  "Validators" and
- * "formatters" do not actually modify the value, but these do.
- *
- * Use case is for when the config file can accept e.g., a `string[]`, but the
- * CLI can only take a `string` (as `argparse` seems to be limited in that
- * fashion; it also cannot understand an argument having multiple types).
- *
- * For example, the `csv` transform takes a `string` and returns a `string[]` by
- * splitting it by comma--_or_ if that `string` happens to be a
- * filepath--reading the file as a `.csv`.
- *
- * This contains some copy-pasted code from `lib/cli/parser-helpers.js`, which was
- * obliterated.
- */
-export const transformers = {
-  /**
-   * Given a CSV-style string or pathname, parse it into an array.
-   * The file can also be split on newlines.
-   * @param {string} csvOrPath
-   * @returns {string[]}
-   */
-  csv: (csvOrPath) => {
-    let csv = csvOrPath;
-    let loadedFromFile = false;
-    // since this value could be a single string (no commas) _or_ a pathname, we will need
-    // to attempt to parse it as a file _first_.
-    if (existsSync(csvOrPath)) {
-      try {
-        csv = readFileSync(csvOrPath, 'utf8');
-      } catch (err) {
-        throw new ArgumentTypeError(`Could not read file '${csvOrPath}': ${err.message}`);
-      }
-      loadedFromFile = true;
-    }
-    try {
-      return loadedFromFile ? parseCsvFile(csv) : parseCsvLine(csv);
-    } catch (err) {
-      const msg = loadedFromFile
-        ? `The provided value of '${csvOrPath}' must be a valid CSV`
-        : `Must be a comma-delimited string, e.g., "foo,bar,baz"`;
-      throw new TypeError(`${msg}. Original error: ${err.message}`);
-    }
-  },
-
-  /**
-   * Parse a string which could be a path to a JSON file or a JSON string.
-   * @param {string} jsonOrPath
-   * @returns {object}
-   */
-  json: (jsonOrPath) => {
-    let json = jsonOrPath;
-    let loadedFromFile = false;
-    if (existsSync(jsonOrPath)) {
-      try {
-        // use synchronous file access, as `argparse` provides no way of either
-        // awaiting or using callbacks. This step happens in startup, in what is
-        // effectively command-line code, so nothing is blocked in terms of
-        // sessions, so holding up the event loop does not incur the usual
-        // drawbacks.
-        json = readFileSync(jsonOrPath, 'utf8');
-      } catch (err) {
-        throw new ArgumentTypeError(`Could not read file '${jsonOrPath}': ${err.message}`);
-      }
-      loadedFromFile = true;
-    }
-    try {
-      return JSON.parse(json);
-    } catch (e) {
-      const msg = loadedFromFile
-        ? `'${jsonOrPath}' must be a valid JSON`
-        : `The provided value must be a valid JSON`;
-      throw new TypeError(`${msg}. Original error: ${e.message}`);
-    }
-  },
-};

package/lib/schema/keywords.js

@@ -1,136 +0,0 @@
-import {transformers} from './cli-transformers';
-
-/**
- * Collection of keyword definitions to add to the singleton `Ajv` instance.
- * @type {Record<string,KeywordDefinition>}
- */
-export const keywords = {
-  /**
-   * Keyword to provide a list of command alias names for the CLI.
-   *
-   * If defined, there must be at least one item in the array and it must be non-empty.
-   * All items in the array must be unique.
-   *
-   * @todo Avoid alias collisions!
-   * @type {KeywordDefinition}
-   * @example
-   * {appiumCliAliases: ['B', 'bobby', 'robert']}
-   */
-  appiumCliAliases: {
-    keyword: 'appiumCliAliases',
-    metaSchema: {
-      type: 'array',
-      items: {
-        type: 'string',
-        minLength: 1,
-      },
-      minItems: 1,
-      uniqueItems: true,
-      description:
-        'List of aliases for the argument. Aliases shorter than three (3) characters will be prefixed with a single dash; otherwise two (2).',
-    },
-  },
-  /**
-   * Keyword to provide the name of the property in the destination (parsed
-   * args) object. By default, this value will be whatever the property name is,
-   * but camel-cased. If a flag needs something _other_ than just camel-casing,
-   * use this.
-   * @type {KeywordDefinition}
-   * @example
-   * // for prop 'no-color'
-   * {appiumCliDest: 'NOCOLOR'} // value will be stored as property `NOCOLOR` instead of `noColor`
-   */
-  appiumCliDest: {
-    keyword: 'appiumCliDest',
-    metaSchema: {
-      type: 'string',
-      minLength: 1,
-      description: 'Name of the associated property in the parsed CLI arguments object',
-    },
-  },
-
-  /**
-   * CLI-specific description of the property.  Sometimes the allowed type can
-   * be different enough on the CLI that providing a description written for a
-   * config file context wouldn't make sense.
-   * @type {KeywordDefinition}
-   * @example
-   * {appiumCliDescription: 'This is a comma-delimited string, but in the config file it is an array'}
-   */
-  appiumCliDescription: {
-    keyword: 'appiumCliDescription',
-    schemaType: 'string',
-    metaSchema: {
-      type: 'string',
-      minLength: 1,
-      description: 'Description to provide in the --help text of the CLI. Overrides `description`',
-    },
-  },
-
-  /**
-   * Transformers for CLI args. These usually take strings then do something with them, like
-   * read a file or parse further.
-   * @type {KeywordDefinition}
-   */
-  appiumCliTransformer: {
-    keyword: 'appiumCliTransformer',
-    metaSchema: {
-      type: 'string',
-      enum: Object.keys(transformers),
-      description:
-        'The name of a custom transformer to run against the value as provided via the CLI.',
-    },
-  },
-
-  /**
-   * Flag to tell Appium to _not_ provide this property as a CLI argument.
-   * @type {KeywordDefinition}
-   */
-  appiumCliIgnored: {
-    keyword: 'appiumCliIgnored',
-    metaSchema: {
-      type: 'boolean',
-      description:
-        'If `true`, Appium will not provide this property as a CLI argument. This is NOT the same as a "hidden" argument.',
-      enum: [true],
-    },
-  },
-
-  /**
-   * Mark this property as deprecated.
-   * @type {KeywordDefinition}
-   */
-  appiumDeprecated: {
-    keyword: 'appiumDeprecated',
-    metaSchema: {
-      type: 'boolean',
-      description: 'If `true`, this property will be displayed as "deprecated" to the user',
-      enum: [true],
-      $comment:
-        'JSON schema draft-2019-09 keyword `deprecated` serves the same purpose. This keyword should itself be deprecated if we move to draft-2019-09!',
-    },
-  },
-};
-
-/**
- * These are the valid values for the `appiumCliTransformer` keyword.
- * Unfortunately, TS cannot infer this in a JS context.  In TS, we'd use
- * `as const` when defining `argTransformers`, then get `keyof typeof argTransformers`. alas.
- * @typedef {'csv'|'json'} AppiumCliTransformerName
- */
-
-/**
- * These are the custom keywords that Appium recognizes.
- *
- * @typedef AppiumJSONSchemaKeywords
- * @property {string} [appiumCliDest]
- * @property {string} [appiumCliDescription]
- * @property {string[]} [appiumCliAliases]
- * @property {boolean} [appiumCliIgnored]
- * @property {AppiumCliTransformerName} [appiumCliTransformer]
- * @property {boolean} [appiumDeprecated]
- */
-
-/**
- * @typedef {import('ajv').KeywordDefinition} KeywordDefinition
- */