patram 0.0.2 → 0.2.0

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

@@ -0,0 +1,446 @@
+/* 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, 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
+ */
+
+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';
+
+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' },
+});
+
+/**
+ * @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 validateRootCommandLine(command_line) {
+  return (
+    findUnknownOption(undefined, command_line.option_tokens) ??
+    findMissingOptionValue(command_line.option_tokens) ??
+    findOutputModeConflict(command_line.values) ??
+    createMessageParseError(findInvalidColorMode(command_line.option_tokens))
+  );
+}
+
+/**
+ * @param {ParsedCommandLine} command_line
+ * @returns {CliParseError | null}
+ */
+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 {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 (
+    findInvalidCommandOption(command_name, command_line.option_tokens) ??
+    createMessageParseError(
+      findInvalidQueryPagination(command_line.option_tokens),
+    ) ??
+    findInvalidQueryInspection(command_name, command_line.values) ??
+    findInvalidQueryMode(
+      command_name,
+      command_line.values,
+      command_positionals,
+    ) ??
+    validateCommandPositionals(command_name, command_positionals)
+  );
+}
+
+/**
+ * @param {CliOptionValues} parsed_values
+ * @returns {CliOutputMode}
+ */
+export function resolveOutputMode(parsed_values) {
+  if (parsed_values.json) {
+    return 'json';
+  }
+
+  if (parsed_values.plain) {
+    return 'plain';
+  }
+
+  return 'default';
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @param {string[]} command_positionals
+ * @param {CliOptionValues} parsed_values
+ * @returns {string[]}
+ */
+export function buildCommandArguments(
+  command_name,
+  command_positionals,
+  parsed_values,
+) {
+  if (command_name === 'query' && parsed_values.where !== undefined) {
+    return ['--where', parsed_values.where];
+  }
+
+  return command_positionals;
+}
+
+/**
+ * @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 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,
+  };
+}
+
+/**
+ * @param {CliCommandName | undefined} command_name
+ * @param {CliOptionToken[]} option_tokens
+ * @returns {CliParseError | null}
+ */
+function findUnknownOption(command_name, option_tokens) {
+  for (const token of option_tokens) {
+    if (
+      token.name &&
+      token.rawName &&
+      !GLOBAL_OPTION_NAMES.has(token.name) &&
+      !isKnownCommandOptionName(token.name)
+    ) {
+      return {
+        code: 'unknown_option',
+        command_name,
+        suggestion: findOptionSuggestion(token.rawName, command_name),
+        token: token.rawName,
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @param {CliOptionToken[]} option_tokens
+ * @returns {CliParseError | null}
+ */
+function findInvalidCommandOption(command_name, option_tokens) {
+  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_definition.allowed_option_names.has(token.name)) {
+      return {
+        code: 'option_not_valid_for_command',
+        command_name,
+        token: token.rawName,
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * @param {CliOptionToken[]} option_tokens
+ * @returns {CliParseError | null}
+ */
+function findMissingOptionValue(option_tokens) {
+  for (const token of option_tokens) {
+    if (token.name === 'where' && typeof token.value !== 'string') {
+      return {
+        argument_label: '<name> or --where "<clause>"',
+        code: 'missing_required_argument',
+        command_name: 'query',
+      };
+    }
+
+    if (token.name === 'offset' && typeof token.value !== 'string') {
+      return createMessageParseError('Offset requires a value.');
+    }
+
+    if (token.name === 'limit' && typeof token.value !== 'string') {
+      return createMessageParseError('Limit requires a value.');
+    }
+
+    if (token.name === 'color' && typeof token.value !== 'string') {
+      return createMessageParseError('Color requires a value.');
+    }
+  }
+
+  return null;
+}
+
+/**
+ * @param {CliOptionValues} parsed_values
+ * @returns {CliParseError | null}
+ */
+function findOutputModeConflict(parsed_values) {
+  if (parsed_values.plain && parsed_values.json) {
+    return createMessageParseError(
+      'Output mode accepts at most one of "--plain" or "--json".',
+    );
+  }
+
+  return null;
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @param {CliOptionValues} parsed_values
+ * @param {string[]} command_positionals
+ * @returns {CliParseError | null}
+ */
+function findInvalidQueryMode(
+  command_name,
+  parsed_values,
+  command_positionals,
+) {
+  if (
+    command_name === 'query' &&
+    parsed_values.where !== undefined &&
+    command_positionals.length > 0
+  ) {
+    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;
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @param {string[]} command_positionals
+ * @returns {CliParseError | null}
+ */
+function validateCommandPositionals(command_name, command_positionals) {
+  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_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_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 {string} option_name
+ * @returns {boolean}
+ */
+function isKnownCommandOptionName(option_name) {
+  return (
+    option_name === 'explain' ||
+    option_name === 'limit' ||
+    option_name === 'lint' ||
+    option_name === 'offset' ||
+    option_name === 'where'
+  );
+}

package/lib/parse-cli-arguments.js

@@ -0,0 +1,266 @@
+/* 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
+ */
+
+import { parseArgs } from 'node:util';
+
+import {
+  CLI_OPTIONS,
+  buildCommandArguments,
+  collectOptionTokens,
+  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';
+
+/**
+ * CLI argument parsing.
+ *
+ * Normalizes raw argv into one validated Patram command plus shared output and
+ * pagination options.
+ *
+ * Kind: cli
+ * Status: active
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/cli-argument-parser.md
+ * @patram
+ * @see {@link ./patram-cli.js}
+ * @see {@link ../docs/decisions/cli-argument-parser.md}
+ */
+
+/**
+ * Parse the CLI arguments into one validated command result.
+ *
+ * @param {string[]} cli_arguments
+ * @returns {ParseCliArgumentsResult}
+ */
+export function parseCliArguments(cli_arguments) {
+  const command_line = parseCommandLine(cli_arguments);
+
+  if (!command_line.success) {
+    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 {
+      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_error = validateParsedCommand(
+    command_name,
+    command_line.value,
+  );
+
+  if (validation_error) {
+    return {
+      error: validation_error,
+      success: false,
+    };
+  }
+
+  const command_positionals = command_line.value.positionals.slice(1);
+
+  return {
+    success: true,
+    value: {
+      kind: 'command',
+      color_mode: resolveColorMode(command_line.value.option_tokens),
+      command_arguments: buildCommandArguments(
+        command_name,
+        command_positionals,
+        command_line.value.values,
+      ),
+      command_name,
+      output_mode: resolveOutputMode(command_line.value.values),
+      ...buildQueryInspection(command_line.value),
+      ...buildQueryPagination(command_line.value.values),
+    },
+  };
+}
+
+/**
+ * @param {string[]} cli_arguments
+ * @returns {{ success: true, value: ParsedCommandLine } | { error: CliParseError, success: false }}
+ */
+function parseCommandLine(cli_arguments) {
+  try {
+    const parsed_arguments = parseArgs({
+      allowPositionals: true,
+      args: cli_arguments,
+      options: CLI_OPTIONS,
+      strict: false,
+      tokens: true,
+    });
+    const parsed_values = /** @type {CliOptionValues} */ (
+      parsed_arguments.values
+    );
+
+    return {
+      success: true,
+      value: {
+        option_tokens: collectOptionTokens(parsed_arguments.tokens ?? []),
+        positionals: parsed_arguments.positionals,
+        values: parsed_values,
+      },
+    };
+  } catch (error) {
+    if (error instanceof Error) {
+      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,
+  };
+}