appium 2.0.0-beta.9 → 2.0.0-rc.2

package/lib/schema/arg-spec.js

@@ -0,0 +1,229 @@
+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

@@ -0,0 +1,241 @@
+import {ArgumentTypeError} from 'argparse';
+import _ from 'lodash';
+import {formatErrors as formatErrors} from '../config-file';
+import {flattenSchema, validate} from './schema';
+import {transformers} 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),
+  };
+
+  /**
+   * 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 = transformers.json;
+      break;
+    }
+
+    // arrays are treated as CSVs, because `argparse` doesn't handle array data.
+    case TYPENAMES.ARRAY: {
+      argTypeFunction = transformers.csv;
+      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);
+  }
+
+  // the validity of "appiumCliTransformer" should already have been determined
+  // by ajv during schema validation in `finalizeSchema()`. the `array` &
+  // `object` types have already added a formatter (see above, so we don't do it
+  // twice).
+  if (type !== TYPENAMES.ARRAY && type !== TYPENAMES.OBJECT && appiumCliTransformer) {
+    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 arryas 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

@@ -0,0 +1,119 @@
+import {ArgumentTypeError} from 'argparse';
+import {readFileSync, existsSync} from 'fs';
+import _ from 'lodash';
+
+/**
+ * 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[]}
+ */
+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 {
+      const result = JSON.parse(json);
+      if (!_.isPlainObject(result)) {
+        throw new Error(`'${_.truncate(result, {length: 100})}' is not an object`);
+      }
+      return result;
+    } catch (e) {
+      const msg = loadedFromFile
+        ? `The provided value of '${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/index.js

@@ -0,0 +1,2 @@
+export * from './schema';
+export * from './cli-args';