appium 3.2.2 → 3.3.1

package/lib/schema/cli-args.ts

@@ -0,0 +1,171 @@
+import {ArgumentTypeError, type ArgumentOptions} from 'argparse';
+import _ from 'lodash';
+import type {JSONSchema7, JSONSchema7TypeName} from 'json-schema';
+import {formatErrors} from './format-errors';
+import {flattenSchema, validate} from './schema';
+import {transformers, parseCsvLine} from './cli-transformers';
+import type {ArgSpec} from './arg-spec';
+import type {AppiumJSONSchemaKeywords, AppiumCliTransformerName} from './keywords';
+import type {ArgumentDefinitions} from '../cli/args';
+
+type AppiumJSONSchema = AppiumJSONSchemaKeywords & JSONSchema7;
+type ArgDef = [[string] | [string, string], ArgumentOptions];
+
+const TYPENAMES: Readonly<Record<string, JSONSchema7TypeName>> = Object.freeze({
+  ARRAY: 'array',
+  OBJECT: 'object',
+  BOOLEAN: 'boolean',
+  INTEGER: 'integer',
+  NUMBER: 'number',
+  NULL: 'null',
+  STRING: 'string',
+});
+
+const SHORT_ARG_CUTOFF = 3;
+
+/**
+ * Converts the finalized, flattened schema representation into
+ * `ArgumentDefinitions` for handoff to `argparse`.
+ */
+export function toParserArgs(): ArgumentDefinitions {
+  const flattened = flattenSchema().filter(({schema}) => !schema.appiumCliIgnored);
+  return new Map(
+    _.map(flattened, ({schema, argSpec}) => subSchemaToArgDef(schema as AppiumJSONSchema, argSpec))
+  );
+}
+
+/**
+ * Convert an alias (`foo`) to a flag (`--foo`) or short flag (`-f`).
+ */
+function aliasToFlag(argSpec: ArgSpec, alias?: string): string {
+  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)}`;
+}
+
+const screamingSnakeCase = _.flow(_.snakeCase, _.toUpper);
+
+/**
+ * Given an argument spec, return a validator/coercer function backed by schema validation.
+ */
+function getSchemaValidator<Coerced>(
+  {ref: schemaId}: ArgSpec,
+  coerce: (value: string) => Coerced = _.identity as (value: string) => Coerced
+): (value: string) => Coerced {
+  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}));
+  };
+}
+
+function makeDescription(schema: AppiumJSONSchema): string {
+  const {appiumCliDescription, description = '', appiumDeprecated} = schema;
+  let desc = appiumCliDescription ?? description;
+  if (appiumDeprecated) {
+    desc = `[DEPRECATED] ${desc}`;
+  }
+  return desc;
+}
+
+function subSchemaToArgDef(subSchema: AppiumJSONSchema, argSpec: ArgSpec): ArgDef {
+  const {type, appiumCliAliases, appiumCliTransformer, enum: enumValues} = subSchema;
+  const {name, arg} = argSpec;
+
+  const aliases = [
+    aliasToFlag(argSpec),
+    ...((appiumCliAliases ?? []) as string[]).map((alias) => aliasToFlag(argSpec, alias)),
+  ];
+
+  const argOpts: ArgumentOptions = {
+    required: false,
+    help: makeDescription(subSchema),
+  };
+
+  if (!argSpec.extType) {
+    argOpts.dest = argSpec.rawDest;
+  }
+
+  let argTypeFunction: ((value: string) => unknown) | undefined;
+
+  switch (type) {
+    case TYPENAMES.BOOLEAN: {
+      argOpts.action = 'store_const';
+      argOpts.const = true;
+      break;
+    }
+    case TYPENAMES.OBJECT: {
+      argTypeFunction = _.flow(transformers.json, (o) => {
+        if (!_.isPlainObject(o)) {
+          throw new ArgumentTypeError(`'${_.truncate(String(o), {length: 100})}' must be a plain object`);
+        }
+        return o;
+      });
+      break;
+    }
+    case TYPENAMES.ARRAY: {
+      argTypeFunction = parseCsvLine;
+      break;
+    }
+    case TYPENAMES.NUMBER: {
+      argTypeFunction = getSchemaValidator(argSpec, parseFloat);
+      break;
+    }
+    case TYPENAMES.INTEGER: {
+      argTypeFunction = getSchemaValidator(argSpec, _.parseInt);
+      break;
+    }
+    case TYPENAMES.STRING: {
+      argTypeFunction = getSchemaValidator(argSpec);
+      break;
+    }
+    case TYPENAMES.NULL:
+    default: {
+      throw new TypeError(`Schema property "${arg}": \`${type}\` type unknown or disallowed`);
+    }
+  }
+
+  if (type !== TYPENAMES.BOOLEAN) {
+    argOpts.metavar = screamingSnakeCase(name);
+  }
+
+  if (appiumCliTransformer && transformers[appiumCliTransformer as AppiumCliTransformerName]) {
+    if (type === TYPENAMES.ARRAY) {
+      const csvTransformer = argTypeFunction as (x: string) => string[];
+      argTypeFunction = (val) =>
+        _.flatMap(csvTransformer(val).map(transformers[appiumCliTransformer as AppiumCliTransformerName]));
+    } else {
+      argTypeFunction = _.flow(
+        argTypeFunction ?? _.identity,
+        transformers[appiumCliTransformer as AppiumCliTransformerName]
+      ) as (value: string) => unknown;
+    }
+  }
+
+  if (argTypeFunction) {
+    argOpts.type = argTypeFunction;
+  }
+
+  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'\``
+      );
+    }
+  }
+
+  const finalAliases = aliases as [string] | [string, string];
+  return [finalAliases, argOpts];
+}
+

package/lib/schema/cli-transformers.ts

@@ -0,0 +1,83 @@
+import {ArgumentTypeError} from 'argparse';
+import {readFileSync, existsSync} from 'node:fs';
+
+/**
+ * This module provides transformer functions for CLI arguments.
+ *
+ * Use case: config schemas can accept richer types (arrays/objects), but CLI
+ * values are strings. Transformers convert string input into those richer types.
+ */
+
+/**
+ * Splits a CSV string into an array
+ */
+export function parseCsvLine(value: string): string[] {
+  return value
+    .split(',')
+    .map((v) => v.trim())
+    .filter(Boolean);
+}
+
+export const transformers = {
+  /**
+   * Given a CSV-style string or pathname, parse it into an array.
+   * The file can also be split on newlines.
+   */
+  csv: (csvOrPath: string): string[] => {
+    let csv = csvOrPath;
+    let loadedFromFile = false;
+    // Value could be a single CSV token or a filepath; attempt file first.
+    if (existsSync(csvOrPath)) {
+      try {
+        csv = readFileSync(csvOrPath, 'utf8');
+      } catch (err) {
+        throw new ArgumentTypeError(`Could not read file '${csvOrPath}': ${(err as Error).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 as Error).message}`);
+    }
+  },
+
+  /**
+   * Parse a string which could be a path to a JSON file or a JSON string.
+   */
+  json: (jsonOrPath: string): Record<string, any> => {
+    let json = jsonOrPath;
+    let loadedFromFile = false;
+    if (existsSync(jsonOrPath)) {
+      try {
+        // Intentionally sync: argparse type hooks are synchronous.
+        json = readFileSync(jsonOrPath, 'utf8');
+      } catch (err) {
+        throw new ArgumentTypeError(`Could not read file '${jsonOrPath}': ${(err as Error).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 as Error).message}`);
+    }
+  },
+} as const;
+
+/**
+ * Split a file by newline then calls {@link parseCsvLine} on each line.
+ */
+function parseCsvFile(value: string): string[] {
+  return value
+    .split(/\r?\n/)
+    .map((v) => v.trim())
+    .filter(Boolean)
+    .flatMap(parseCsvLine);
+}

package/lib/schema/format-errors.ts

@@ -0,0 +1,43 @@
+import betterAjvErrors, {type IOutputError} from '@sidvind/better-ajv-errors';
+import type {ErrorObject} from 'ajv';
+import type {NormalizedAppiumConfig} from '@appium/types';
+import {getSchema} from './schema';
+
+/**
+ * The string should be a raw JSON string.
+ */
+export type RawJson = string;
+
+/**
+ * Options for {@link formatErrors}.
+ */
+export interface FormatConfigErrorsOptions {
+  json?: RawJson;
+  pretty?: boolean;
+  schemaId?: string;
+}
+
+/**
+ * Given an array of errors and the result of loading a config file, generate a
+ * helpful string for the user.
+ *
+ * - If `opts` contains a `json` property, this should be the original JSON
+ *   _string_ of the config file.  This is only applicable if the config file
+ *   was in JSON format. If present, it will associate line numbers with errors.
+ * - If `errors` happens to be empty, this will throw.
+ *
+ * @throws {TypeError} If `errors` is empty
+ */
+export function formatErrors(
+  errors: ErrorObject[] = [],
+  config: NormalizedAppiumConfig | Record<string, unknown> | string | undefined = {},
+  opts: FormatConfigErrorsOptions = {}
+): string | IOutputError[] {
+  if (errors && !errors.length) {
+    throw new TypeError('Array of errors must be non-empty');
+  }
+  return betterAjvErrors(getSchema(opts.schemaId), config, errors, {
+    json: opts.json,
+    format: opts.pretty === false ? 'js' : 'cli',
+  });
+}

package/lib/schema/index.ts

@@ -0,0 +1,4 @@
+export * from './schema';
+export * from './format-errors';
+export * from './cli-args';
+export * from './cli-args-guards';

package/lib/schema/keywords.ts

@@ -0,0 +1,96 @@
+import type {KeywordDefinition} from 'ajv';
+import {transformers} from './cli-transformers';
+
+export type AppiumCliTransformerName = keyof typeof transformers;
+
+export interface AppiumJSONSchemaKeywords {
+  appiumCliDest?: string;
+  appiumCliDescription?: string;
+  appiumCliAliases?: string[];
+  appiumCliIgnored?: boolean;
+  appiumCliTransformer?: AppiumCliTransformerName;
+  appiumDeprecated?: boolean;
+}
+
+/**
+ * Collection of keyword definitions to add to the singleton `Ajv` instance.
+ */
+export const keywords: Record<string, KeywordDefinition> = {
+  /**
+   * List of alias names for a CLI arg.
+   */
+  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).',
+    },
+  },
+  /**
+   * Explicit destination key name in parsed args.
+   */
+  appiumCliDest: {
+    keyword: 'appiumCliDest',
+    metaSchema: {
+      type: 'string',
+      minLength: 1,
+      description: 'Name of the associated property in the parsed CLI arguments object',
+    },
+  },
+  /**
+   * CLI-specific description (overrides generic schema description for help text).
+   */
+  appiumCliDescription: {
+    keyword: 'appiumCliDescription',
+    schemaType: 'string',
+    metaSchema: {
+      type: 'string',
+      minLength: 1,
+      description: 'Description to provide in the --help text of the CLI. Overrides `description`',
+    },
+  },
+  /**
+   * Named transformer to apply to CLI value before validation.
+   */
+  appiumCliTransformer: {
+    keyword: 'appiumCliTransformer',
+    metaSchema: {
+      type: 'string',
+      enum: Object.keys(transformers) as AppiumCliTransformerName[],
+      description:
+        'The name of a custom transformer to run against the value as provided via the CLI.',
+    },
+  },
+  /**
+   * If true, this property is not exposed as a CLI arg.
+   */
+  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],
+    },
+  },
+  /**
+   * Marks property as deprecated for CLI docs/help output.
+   */
+  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!',
+    },
+  },
+};