patram 0.1.1 → 0.3.0

package/lib/parse-cli-arguments-helpers.js

@@ -1,82 +1,125 @@
+/* eslint-disable max-lines */
 /**
  * @typedef {import('./parse-cli-arguments.types.ts').CliCommandName} CliCommandName
  * @typedef {import('./parse-cli-arguments.types.ts').CliOutputMode} CliOutputMode
+ * @typedef {import('./parse-cli-arguments.types.ts').CliParseError} CliParseError
+ * @typedef {import('./parse-cli-arguments.types.ts').ParsedCliHelpRequest} ParsedCliHelpRequest
  * @typedef {{ kind: string, name?: string, rawName?: string, value?: string | boolean }} CliOptionToken
- * @typedef {{ color?: string, json?: boolean, limit?: string, 'no-color'?: boolean, offset?: string, plain?: boolean, where?: string }} CliOptionValues
+ * @typedef {{ color?: string, explain?: boolean, help?: boolean, json?: boolean, limit?: string, lint?: boolean, 'no-color'?: boolean, offset?: string, plain?: boolean, where?: string }} CliOptionValues
  * @typedef {{ option_tokens: CliOptionToken[], positionals: string[], values: CliOptionValues }} ParsedCommandLine
- * @typedef {{ allowed_option_names: Set<string>, extra_positionals_message: string, max_positionals: number, min_positionals: number, missing_positionals_message: string }} CommandSchema
  */
 
+import {
+  findCommandSuggestion,
+  findHelpTargetSuggestion,
+  findOptionSuggestion,
+  getCommandDefinition,
+  GLOBAL_OPTION_NAMES,
+  isCommandName,
+  isHelpTopicName,
+} from './cli-help-metadata.js';
 import { findInvalidColorMode } from './parse-cli-color-options.js';
 import { findInvalidQueryPagination } from './parse-cli-query-pagination.js';
 
-const GLOBAL_OPTION_NAMES = new Set(['plain', 'json', 'color', 'no-color']);
 export const CLI_OPTIONS = /** @type {const} */ ({
   color: { type: 'string' },
+  explain: { type: 'boolean' },
+  help: { type: 'boolean' },
   json: { type: 'boolean' },
   limit: { type: 'string' },
+  lint: { type: 'boolean' },
   'no-color': { type: 'boolean' },
   offset: { type: 'string' },
   plain: { type: 'boolean' },
   where: { type: 'string' },
 });
-/** @type {Record<CliCommandName, CommandSchema>} */
-const COMMAND_SCHEMAS = {
-  check: createCommandSchema(0, 1, 'Check accepts at most one path.'),
-  queries: createCommandSchema(
-    0,
-    0,
-    'Queries does not accept positional arguments.',
-  ),
-  query: {
-    ...createCommandSchema(
-      0,
-      1,
-      'Query accepts either "--where" or a stored query name.',
-    ),
-    allowed_option_names: new Set(['limit', 'offset', 'where']),
-  },
-  show: createCommandSchema(
-    1,
-    1,
-    'Show accepts exactly one file path.',
-    'Show requires a file path.',
-  ),
-};
+
 /**
- * @param {string | undefined} command_name
- * @returns {command_name is CliCommandName}
+ * @param {CliOptionToken[]} tokens
+ * @returns {CliOptionToken[]}
+ */
+export function collectOptionTokens(tokens) {
+  return tokens.filter((token) => token.kind === 'option');
+}
+
+/**
+ * @param {ParsedCommandLine} command_line
+ * @returns {CliParseError | null}
  */
-export function isCommandName(command_name) {
+export function validateRootCommandLine(command_line) {
   return (
-    command_name === 'check' ||
-    command_name === 'query' ||
-    command_name === 'queries' ||
-    command_name === 'show'
+    findUnknownOption(undefined, command_line.option_tokens) ??
+    findMissingOptionValue(command_line.option_tokens) ??
+    findOutputModeConflict(command_line.values) ??
+    createMessageParseError(findInvalidColorMode(command_line.option_tokens))
   );
 }
+
 /**
- * @param {CliOptionToken[]} tokens
- * @returns {CliOptionToken[]}
+ * @param {ParsedCommandLine} command_line
+ * @returns {CliParseError | null}
  */
-export function collectOptionTokens(tokens) {
-  return tokens.filter((token) => token.kind === 'option');
+export function validateHelpCommandLine(command_line) {
+  const help_validation_error = validateRootCommandLine(command_line);
+
+  if (help_validation_error) {
+    return help_validation_error;
+  }
+
+  if (command_line.positionals.length > 2) {
+    return createMessageParseError(
+      'Help accepts at most one topic or command.',
+    );
+  }
+
+  return null;
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @param {ParsedCommandLine} command_line
+ * @returns {CliParseError | null}
+ */
+export function validateCommandLineBeforeHelp(command_name, command_line) {
+  return (
+    findUnknownOption(command_name, command_line.option_tokens) ??
+    findMissingOptionValue(command_line.option_tokens) ??
+    findOutputModeConflict(command_line.values) ??
+    createMessageParseError(findInvalidColorMode(command_line.option_tokens))
+  );
 }
+
 /**
  * @param {CliCommandName} command_name
  * @param {ParsedCommandLine} command_line
- * @returns {string | null}
+ * @returns {CliParseError | null}
  */
 export function validateParsedCommand(command_name, command_line) {
   const command_positionals = command_line.positionals.slice(1);
 
+  if (
+    command_name === 'query' &&
+    command_line.values.where !== undefined &&
+    command_positionals.length === 0
+  ) {
+    return (
+      createMessageParseError(
+        findInvalidQueryPagination(command_line.option_tokens),
+      ) ??
+      findInvalidQueryMode(
+        command_name,
+        command_line.values,
+        command_positionals,
+      )
+    );
+  }
+
   return (
-    findUnknownOption(command_line.option_tokens) ??
     findInvalidCommandOption(command_name, command_line.option_tokens) ??
-    findMissingOptionValue(command_line.option_tokens) ??
-    findOutputModeConflict(command_line.values) ??
-    findInvalidColorMode(command_line.option_tokens) ??
-    findInvalidQueryPagination(command_line.option_tokens) ??
+    createMessageParseError(
+      findInvalidQueryPagination(command_line.option_tokens),
+    ) ??
+    findInvalidQueryInspection(command_name, command_line.values) ??
     findInvalidQueryMode(
       command_name,
       command_line.values,
@@ -85,6 +128,7 @@ export function validateParsedCommand(command_name, command_line) {
     validateCommandPositionals(command_name, command_positionals)
   );
 }
+
 /**
  * @param {CliOptionValues} parsed_values
  * @returns {CliOutputMode}
@@ -100,6 +144,7 @@ export function resolveOutputMode(parsed_values) {
 
   return 'default';
 }
+
 /**
  * @param {CliCommandName} command_name
  * @param {string[]} command_positionals
@@ -119,31 +164,108 @@ export function buildCommandArguments(
 }
 
 /**
- * @param {string} message
- * @returns {{ message: string, success: false }}
+ * @param {string | undefined} help_target
+ * @returns {CliParseError}
+ */
+export function createUnknownHelpTargetError(help_target) {
+  return {
+    code: 'unknown_help_target',
+    suggestion: help_target ? findHelpTargetSuggestion(help_target) : undefined,
+    token: help_target ?? '',
+  };
+}
+
+/**
+ * @param {string | undefined} command_name
+ * @returns {CliParseError}
  */
-export function createParseError(message) {
+export function createUnknownCommandError(command_name) {
   return {
+    code: 'unknown_command',
+    suggestion:
+      command_name && command_name.length > 0
+        ? findCommandSuggestion(command_name)
+        : undefined,
+    token: command_name ?? '',
+  };
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @returns {ParsedCliHelpRequest}
+ */
+export function createCommandHelpRequest(command_name) {
+  return {
+    kind: 'help',
+    target_kind: 'command',
+    target_name: command_name,
+  };
+}
+
+/**
+ * @param {string | undefined} help_target
+ * @returns {ParsedCliHelpRequest | null}
+ */
+export function createNamedHelpRequest(help_target) {
+  if (isCommandName(help_target)) {
+    return createCommandHelpRequest(help_target);
+  }
+
+  if (isHelpTopicName(help_target)) {
+    return {
+      kind: 'help',
+      target_kind: 'topic',
+      target_name: help_target,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * @returns {ParsedCliHelpRequest}
+ */
+export function createRootHelpRequest() {
+  return {
+    kind: 'help',
+    target_kind: 'root',
+  };
+}
+
+/**
+ * @param {string | null} message
+ * @returns {CliParseError | null}
+ */
+export function createMessageParseError(message) {
+  if (!message) {
+    return null;
+  }
+
+  return {
+    code: 'message',
     message,
-    success: false,
   };
 }
 
 /**
+ * @param {CliCommandName | undefined} command_name
  * @param {CliOptionToken[]} option_tokens
- * @returns {string | null}
+ * @returns {CliParseError | null}
  */
-function findUnknownOption(option_tokens) {
+function findUnknownOption(command_name, option_tokens) {
   for (const token of option_tokens) {
     if (
       token.name &&
       token.rawName &&
       !GLOBAL_OPTION_NAMES.has(token.name) &&
-      token.name !== 'limit' &&
-      token.name !== 'offset' &&
-      token.name !== 'where'
+      !isKnownCommandOptionName(token.name)
     ) {
-      return `Unknown option "${token.rawName}".`;
+      return {
+        code: 'unknown_option',
+        command_name,
+        suggestion: findOptionSuggestion(token.rawName, command_name),
+        token: token.rawName,
+      };
     }
   }
 
@@ -153,18 +275,22 @@ function findUnknownOption(option_tokens) {
 /**
  * @param {CliCommandName} command_name
  * @param {CliOptionToken[]} option_tokens
- * @returns {string | null}
+ * @returns {CliParseError | null}
  */
 function findInvalidCommandOption(command_name, option_tokens) {
-  const command_schema = COMMAND_SCHEMAS[command_name];
+  const command_definition = getCommandDefinition(command_name);
 
   for (const token of option_tokens) {
     if (!token.name || !token.rawName || GLOBAL_OPTION_NAMES.has(token.name)) {
       continue;
     }
 
-    if (!command_schema.allowed_option_names.has(token.name)) {
-      return `Option "${token.rawName}" is not valid for "${command_name}".`;
+    if (!command_definition.allowed_option_names.has(token.name)) {
+      return {
+        code: 'option_not_valid_for_command',
+        command_name,
+        token: token.rawName,
+      };
     }
   }
 
@@ -173,24 +299,28 @@ function findInvalidCommandOption(command_name, option_tokens) {
 
 /**
  * @param {CliOptionToken[]} option_tokens
- * @returns {string | null}
+ * @returns {CliParseError | null}
  */
 function findMissingOptionValue(option_tokens) {
   for (const token of option_tokens) {
     if (token.name === 'where' && typeof token.value !== 'string') {
-      return 'Query requires a where clause.';
+      return {
+        argument_label: '<name> or --where "<clause>"',
+        code: 'missing_required_argument',
+        command_name: 'query',
+      };
     }
 
     if (token.name === 'offset' && typeof token.value !== 'string') {
-      return 'Offset requires a value.';
+      return createMessageParseError('Offset requires a value.');
     }
 
     if (token.name === 'limit' && typeof token.value !== 'string') {
-      return 'Limit requires a value.';
+      return createMessageParseError('Limit requires a value.');
     }
 
     if (token.name === 'color' && typeof token.value !== 'string') {
-      return 'Color requires a value.';
+      return createMessageParseError('Color requires a value.');
     }
   }
 
@@ -199,11 +329,13 @@ function findMissingOptionValue(option_tokens) {
 
 /**
  * @param {CliOptionValues} parsed_values
- * @returns {string | null}
+ * @returns {CliParseError | null}
  */
 function findOutputModeConflict(parsed_values) {
   if (parsed_values.plain && parsed_values.json) {
-    return 'Output mode accepts at most one of "--plain" or "--json".';
+    return createMessageParseError(
+      'Output mode accepts at most one of "--plain" or "--json".',
+    );
   }
 
   return null;
@@ -213,7 +345,7 @@ function findOutputModeConflict(parsed_values) {
  * @param {CliCommandName} command_name
  * @param {CliOptionValues} parsed_values
  * @param {string[]} command_positionals
- * @returns {string | null}
+ * @returns {CliParseError | null}
  */
 function findInvalidQueryMode(
   command_name,
@@ -225,7 +357,28 @@ function findInvalidQueryMode(
     parsed_values.where !== undefined &&
     command_positionals.length > 0
   ) {
-    return 'Query accepts either "--where" or a stored query name.';
+    return createMessageParseError(
+      'Query accepts either "--where" or a stored query name.',
+    );
+  }
+
+  return null;
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @param {CliOptionValues} parsed_values
+ * @returns {CliParseError | null}
+ */
+function findInvalidQueryInspection(command_name, parsed_values) {
+  if (command_name !== 'query') {
+    return null;
+  }
+
+  if (parsed_values.explain && parsed_values.lint) {
+    return createMessageParseError(
+      'Query accepts at most one of "--explain" or "--lint".',
+    );
   }
 
   return null;
@@ -234,40 +387,60 @@ function findInvalidQueryMode(
 /**
  * @param {CliCommandName} command_name
  * @param {string[]} command_positionals
- * @returns {string | null}
+ * @returns {CliParseError | null}
  */
 function validateCommandPositionals(command_name, command_positionals) {
-  const command_schema = COMMAND_SCHEMAS[command_name];
+  const command_definition = getCommandDefinition(command_name);
+
+  if (command_positionals.length < command_definition.min_positionals) {
+    if (command_name === 'query' && command_definition.missing_argument_label) {
+      return {
+        argument_label: command_definition.missing_argument_label,
+        code: 'missing_required_argument',
+        command_name: 'query',
+      };
+    }
 
-  if (command_positionals.length < command_schema.min_positionals) {
-    return command_schema.missing_positionals_message;
+    if (command_name === 'show' && command_definition.missing_argument_label) {
+      return {
+        argument_label: command_definition.missing_argument_label,
+        code: 'missing_required_argument',
+        command_name: 'show',
+      };
+    }
+
+    return createMessageParseError(
+      command_definition.extra_positionals_message,
+    );
   }
 
-  if (command_positionals.length > command_schema.max_positionals) {
-    return command_schema.extra_positionals_message;
+  if (command_positionals.length > command_definition.max_positionals) {
+    return createMessageParseError(
+      command_definition.extra_positionals_message,
+    );
+  }
+
+  if (command_name === 'query' && command_positionals.length === 0) {
+    return {
+      argument_label: '<name> or --where "<clause>"',
+      code: 'missing_required_argument',
+      command_name: 'query',
+    };
   }
 
   return null;
 }
 
 /**
- * @param {number} min_positionals
- * @param {number} max_positionals
- * @param {string} extra_positionals_message
- * @param {string} missing_positionals_message
- * @returns {CommandSchema}
+ * @param {string} option_name
+ * @returns {boolean}
  */
-function createCommandSchema(
-  min_positionals,
-  max_positionals,
-  extra_positionals_message,
-  missing_positionals_message = '',
-) {
-  return {
-    allowed_option_names: new Set(),
-    extra_positionals_message,
-    max_positionals,
-    min_positionals,
-    missing_positionals_message,
-  };
+function isKnownCommandOptionName(option_name) {
+  return (
+    option_name === 'explain' ||
+    option_name === 'limit' ||
+    option_name === 'lint' ||
+    option_name === 'offset' ||
+    option_name === 'where'
+  );
 }