appium 3.2.2 → 3.3.0

package/lib/schema/arg-spec.js

@@ -1,229 +0,0 @@
-import _ from 'lodash';
-
-/**
- * The original ID of the Appium config schema.
- * We use this in the CLI to convert it to `argparse` options.
- */
-export const APPIUM_CONFIG_SCHEMA_ID = 'appium.json';
-
-/**
- * The schema prop containing server-related options. Everything in here
- * is "native" to Appium.
- * Used by {@link flattenSchema} for transforming the schema into CLI args.
- */
-export const SERVER_PROP_NAME = 'server';
-
-/**
- * Used to parse extension info from a schema ID.
- */
-const SCHEMA_ID_REGEXP = /^(?<extType>.+?)-(?<normalizedExtName>.+)\.json$/;
-
-/**
- * Avoid typos by using constants!
- */
-const PROPERTIES = 'properties';
-
-/**
- * An `ArgSpec` is a class representing metadata about an argument (or config
- * option) used for cross-referencing.
- *
- * This class has no instance methods, and is basically just a read-only "struct".
- * @template D
- */
-export class ArgSpec {
-  /**
-   * The canonical name of the argument. Corresponds to key in schema's `properties` prop.
-   * @type {string}
-   */
-  name;
-
-  /**
-   * The `ExtensionType` of the argument. This will be set if the arg came from an extension;
-   * otherwise it will be `undefined`.
-   * @type {ExtensionType|undefined}
-   */
-  extType;
-
-  /**
-   * The name of the extension, if this argument came from an extension.
-   *
-   * Otherwise `undefined`.
-   * @type {string|undefined}
-   */
-  extName;
-
-  /**
-   * The schema ID (`$id`) for the argument.  This is automatically determined, and any user-provided `$id`s will be overwritten.
-   *
-   * @type {string}
-   */
-  ref;
-
-  /**
-   * The CLI argument, sans leading dashes.
-   * @type {string}
-   */
-  arg;
-
-  /**
-   * The desired keypath for the argument after arguments have been parsed.
-   *
-   * Typically this is camelCased.  If the arg came from an extension, it will be prefixed with
-   * `<extType>.<extName>.`
-   * @type {string}
-   */
-  dest;
-
-  /**
-   * The same as {@link ArgSpec.dest} but without the leading `<extType>.<extName>.` prefix.
-   */
-  rawDest;
-
-  /**
-   * Whatever the default value of this argument is, as specified by the
-   * `default` property of the schema.
-   * @type {D|undefined}
-   */
-  defaultValue;
-
-  /**
-   * Builds some computed fields and assigns them to the instance.
-   *
-   * Undefined properties are not assigned.
-   *
-   * The _constructor_ is private. Use {@link ArgSpec.create} instead.
-   * @private
-   * @param {string} name
-   * @param {ArgSpecOptions<D>} opts
-   */
-  constructor(name, {extType, extName, dest, defaultValue} = {}) {
-    // we must normalize the extension name to fit into our convention for CLI
-    // args.
-    const arg = ArgSpec.toArg(name, extType, extName);
-
-    const ref = ArgSpec.toSchemaRef(name, extType, extName);
-
-    // if no explicit `dest` provided, just camelCase the name to avoid needing
-    // to use bracket syntax when accessing props on the parsed args object.
-    const rawDest = _.camelCase(dest ?? name);
-
-    const destKeypath = extType && extName ? [extType, extName, rawDest].join('.') : rawDest;
-
-    this.defaultValue = defaultValue;
-    this.name = name;
-    this.extType = extType;
-    this.extName = extName;
-    this.arg = arg;
-    this.dest = destKeypath;
-    this.ref = ref;
-    this.rawDest = rawDest;
-  }
-
-  /**
-   * Return the schema ID (`$id`) for the **argument** given the parameters.
-   *
-   * If you need the "root" or "base" schema ID, use {@link ArgSpec.toSchemaBaseRef} instead.
-   * @param {string} name - Argument name
-   * @param {ExtensionType} [extType] - Extension type
-   * @param {string} [extName] - Extension name
-   * @returns {string} Schema ID
-   */
-  static toSchemaRef(name, extType, extName) {
-    const baseRef = ArgSpec.toSchemaBaseRef(extType, extName);
-    if (extType && extName) {
-      return [`${baseRef}#`, PROPERTIES, name].join('/');
-    }
-    return [`${baseRef}#`, PROPERTIES, SERVER_PROP_NAME, PROPERTIES, name].join('/');
-  }
-
-  /**
-   * Return the schema ID for an extension or the base schema ID.
-   * @param {ExtensionType} [extType] - Extension type
-   * @param {string} [extName] - Extension name
-   */
-  static toSchemaBaseRef(extType, extName) {
-    if (extType && extName) {
-      return `${extType}-${ArgSpec.toNormalizedExtName(extName)}.json`;
-    }
-    return APPIUM_CONFIG_SCHEMA_ID;
-  }
-
-  /**
-   * Return the unique ID for the argument given the parameters.
-   * @param {string} name - Argument name
-   * @param {ExtensionType} [extType] - Extension type
-   * @param {string} [extName] - Extension name
-   * @returns {string} Unique ID
-   */
-  static toArg(name, extType, extName) {
-    const properName = _.kebabCase(name.replace(/^--?/, ''));
-    if (extType && extName) {
-      return [extType, _.kebabCase(extName), properName].join('-');
-    }
-    return properName;
-  }
-
-  /**
-   * Normalizes a raw extension name (not including the type).
-   * @param {string} extName - Extension name
-   * @returns {string} Normalized extension name
-   */
-  static toNormalizedExtName(extName) {
-    return _.kebabCase(extName);
-  }
-
-  /**
-   * When given the root ID of a schema for an extension (`<extType>-<normalizedExtName>.json`) Returns an object containing the extension type and the _normalized_ extension name.
-   * @param {string} schemaId - Root schema ID
-   * @returns { {extType?: ExtensionType, normalizedExtName?: string} }
-   */
-  static extensionInfoFromRootSchemaId(schemaId) {
-    const matches = schemaId.match(SCHEMA_ID_REGEXP);
-    if (matches?.groups) {
-      const {extType, normalizedExtName} =
-        /** @type { {extType: ExtensionType, normalizedExtName: string} } */ (matches.groups);
-      return {extType, normalizedExtName};
-    }
-    return {};
-  }
-
-  /**
-   * Creates an `ArgSpec`
-   *
-   * @param {string} name - The canonical name of the argument. Corresponds to a key in a schema's
-   * `properties` property.
-   * @template D
-   * @param {ArgSpecOptions<D>} [opts] - Options
-   * @returns {Readonly<ArgSpec>}
-   */
-  static create(name, opts) {
-    return Object.freeze(new ArgSpec(name, opts));
-  }
-
-  /**
-   * String representation, useful for debugging
-   * @returns {string}
-   */
-  /* istanbul ignore next */
-  toString() {
-    let str = `[ArgSpec] ${this.name} (${this.ref})`;
-    if (this.extType && this.extName) {
-      str += ` (ext: ${this.extType}/${this.extName})`;
-    }
-    return str;
-  }
-}
-
-/**
- * Options for {@link ArgSpec.create}
- * @template D
- * @typedef ArgSpecOptions
- * @property {string} [extName]
- * @property {ExtensionType} [extType]
- * @property {string} [dest]
- * @property {D} [defaultValue]
- */
-
-/**
- * @typedef {import('@appium/types').ExtensionType} ExtensionType
- */

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}`);
-    }
-  },
-};