patram 0.1.1 → 0.3.0

package/lib/parse-cli-arguments.js

@@ -1,6 +1,8 @@
+/* eslint-disable max-lines-per-function */
 /**
  * @typedef {import('./parse-cli-arguments-helpers.js').CliOptionValues} CliOptionValues
  * @typedef {import('./parse-cli-arguments-helpers.js').ParsedCommandLine} ParsedCommandLine
+ * @typedef {import('./parse-cli-arguments.types.ts').CliParseError} CliParseError
  * @typedef {import('./parse-cli-arguments.types.ts').ParseCliArgumentsResult} ParseCliArgumentsResult
  */
 
@@ -10,11 +12,19 @@ import {
   CLI_OPTIONS,
   buildCommandArguments,
   collectOptionTokens,
-  createParseError,
-  isCommandName,
+  createCommandHelpRequest,
+  createMessageParseError,
+  createNamedHelpRequest,
+  createRootHelpRequest,
+  createUnknownCommandError,
+  createUnknownHelpTargetError,
   resolveOutputMode,
+  validateCommandLineBeforeHelp,
+  validateHelpCommandLine,
   validateParsedCommand,
+  validateRootCommandLine,
 } from './parse-cli-arguments-helpers.js';
+import { isCommandName } from './cli-help-metadata.js';
 import { resolveColorMode } from './parse-cli-color-options.js';
 import { buildQueryPagination } from './parse-cli-query-pagination.js';
 
@@ -46,19 +56,56 @@ export function parseCliArguments(cli_arguments) {
     return command_line;
   }
 
+  const root_request = resolveRootHelpRequest(command_line.value);
+
+  if (root_request) {
+    return root_request;
+  }
+
+  const help_request = resolveNamedHelpRequest(command_line.value);
+
+  if (help_request) {
+    return help_request;
+  }
+
   const command_name = command_line.value.positionals[0];
 
   if (!isCommandName(command_name)) {
-    return createParseError('Unknown command.');
+    return {
+      error: createUnknownCommandError(command_name),
+      success: false,
+    };
+  }
+
+  const pre_help_error = validateCommandLineBeforeHelp(
+    command_name,
+    command_line.value,
+  );
+
+  if (pre_help_error) {
+    return {
+      error: pre_help_error,
+      success: false,
+    };
+  }
+
+  if (command_line.value.values.help) {
+    return {
+      success: true,
+      value: createCommandHelpRequest(command_name),
+    };
   }
 
-  const validation_message = validateParsedCommand(
+  const validation_error = validateParsedCommand(
     command_name,
     command_line.value,
   );
 
-  if (validation_message) {
-    return createParseError(validation_message);
+  if (validation_error) {
+    return {
+      error: validation_error,
+      success: false,
+    };
   }
 
   const command_positionals = command_line.value.positionals.slice(1);
@@ -66,6 +113,7 @@ export function parseCliArguments(cli_arguments) {
   return {
     success: true,
     value: {
+      kind: 'command',
       color_mode: resolveColorMode(command_line.value.option_tokens),
       command_arguments: buildCommandArguments(
         command_name,
@@ -74,6 +122,7 @@ export function parseCliArguments(cli_arguments) {
       ),
       command_name,
       output_mode: resolveOutputMode(command_line.value.values),
+      ...buildQueryInspection(command_line.value),
       ...buildQueryPagination(command_line.value.values),
     },
   };
@@ -81,7 +130,7 @@ export function parseCliArguments(cli_arguments) {
 
 /**
  * @param {string[]} cli_arguments
- * @returns {{ success: true, value: ParsedCommandLine } | { message: string, success: false }}
+ * @returns {{ success: true, value: ParsedCommandLine } | { error: CliParseError, success: false }}
  */
 function parseCommandLine(cli_arguments) {
   try {
@@ -106,9 +155,112 @@ function parseCommandLine(cli_arguments) {
     };
   } catch (error) {
     if (error instanceof Error) {
-      return createParseError(error.message);
+      return {
+        error: /** @type {CliParseError} */ (
+          createMessageParseError(error.message)
+        ),
+        success: false,
+      };
     }
 
     throw error;
   }
 }
+
+/**
+ * @param {ParsedCommandLine} command_line
+ * @returns {ParseCliArgumentsResult | null}
+ */
+function resolveNamedHelpRequest(command_line) {
+  if (command_line.positionals[0] !== 'help') {
+    return null;
+  }
+
+  const validation_error = validateHelpCommandLine(command_line);
+
+  if (validation_error) {
+    return {
+      error: validation_error,
+      success: false,
+    };
+  }
+
+  const help_target = command_line.positionals[1];
+
+  if (!help_target) {
+    return {
+      success: true,
+      value: createRootHelpRequest(),
+    };
+  }
+
+  const help_request = createNamedHelpRequest(help_target);
+
+  if (help_request) {
+    return {
+      success: true,
+      value: help_request,
+    };
+  }
+
+  return {
+    error: createUnknownHelpTargetError(help_target),
+    success: false,
+  };
+}
+
+/**
+ * @param {ParsedCommandLine} command_line
+ * @returns {ParseCliArgumentsResult | null}
+ */
+function resolveRootHelpRequest(command_line) {
+  if (command_line.positionals.length > 0) {
+    return null;
+  }
+
+  const validation_error = validateRootCommandLine(command_line);
+
+  if (validation_error) {
+    return {
+      error: validation_error,
+      success: false,
+    };
+  }
+
+  return {
+    success: true,
+    value: createRootHelpRequest(),
+  };
+}
+
+/**
+ * @param {ParsedCommandLine} command_line
+ * @returns {'explain' | 'lint' | undefined}
+ */
+function resolveQueryInspectionMode(command_line) {
+  if (command_line.values.explain) {
+    return 'explain';
+  }
+
+  if (command_line.values.lint) {
+    return 'lint';
+  }
+
+  return undefined;
+}
+
+/**
+ * @param {ParsedCommandLine} command_line
+ * @returns {{ query_inspection_mode?: 'explain' | 'lint' }}
+ */
+function buildQueryInspection(command_line) {
+  const query_inspection_mode = resolveQueryInspectionMode(command_line);
+
+  if (!query_inspection_mode) {
+    return {};
+  }
+
+  return {
+    query_inspection_mode,
+  };
+}

package/lib/parse-cli-arguments.types.ts

@@ -1,24 +1,69 @@
-export type CliCommandName = 'check' | 'query' | 'queries' | 'show';
+export type CliCommandName = 'check' | 'fields' | 'query' | 'queries' | 'show';
+export type CliHelpTopicName = 'query-language';
+export type CliHelpTargetKind = 'root' | 'command' | 'topic';
 
 export type CliOutputMode = 'default' | 'plain' | 'json';
 
 export type CliColorMode = 'auto' | 'always' | 'never';
 
-export interface ParsedCliArguments {
+export interface ParsedCliCommandRequest {
+  kind?: 'command';
   color_mode: CliColorMode;
   command_arguments: string[];
   command_name: CliCommandName;
   output_mode: CliOutputMode;
+  query_inspection_mode?: 'explain' | 'lint';
   query_limit?: number;
   query_offset?: number;
 }
 
+export interface ParsedCliHelpRequest {
+  kind: 'help';
+  target_kind: CliHelpTargetKind;
+  target_name?: CliCommandName | CliHelpTopicName;
+}
+
+export type ParsedCliArguments = ParsedCliCommandRequest;
+export type ParsedCliRequest = ParsedCliCommandRequest | ParsedCliHelpRequest;
+
+export type CliParseError =
+  | {
+      code: 'message';
+      message: string;
+    }
+  | {
+      code: 'missing_required_argument';
+      argument_label: string;
+      command_name: 'query' | 'show';
+    }
+  | {
+      code: 'option_not_valid_for_command';
+      command_name: CliCommandName;
+      token: string;
+    }
+  | {
+      code: 'unknown_command';
+      suggestion?: CliCommandName;
+      token: string;
+    }
+  | {
+      code: 'unknown_help_target';
+      suggestion?: CliCommandName | CliHelpTopicName;
+      token: string;
+    }
+  | {
+      code: 'unknown_option';
+      command_name?: CliCommandName;
+      suggestion?: string;
+      token: string;
+    };
+
 export type ParseCliArgumentsResult =
   | {
       success: true;
-      value: ParsedCliArguments;
+      value: ParsedCliRequest;
     }
   | {
-      message: string;
+      error: CliParseError;
       success: false;
     };