patram 0.10.0 → 0.12.0

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

@@ -5,7 +5,7 @@
  * @typedef {import('./arguments.types.ts').CliParseError} CliParseError
  * @typedef {import('./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 {{ color?: string, cypher?: string, desc?: string, explain?: boolean, help?: boolean, json?: boolean, limit?: string, lint?: boolean, name?: string, 'no-color'?: boolean, offset?: string, plain?: boolean, where?: string }} CliOptionValues
  * @typedef {{ option_tokens: CliOptionToken[], positionals: string[], values: CliOptionValues }} ParsedCommandLine
  */
 
@@ -23,11 +23,14 @@ import { findInvalidQueryPagination } from './query-pagination.js';
 
 export const CLI_OPTIONS = /** @type {const} */ ({
   color: { type: 'string' },
+  cypher: { type: 'string' },
+  desc: { type: 'string' },
   explain: { type: 'boolean' },
   help: { type: 'boolean' },
   json: { type: 'boolean' },
   limit: { type: 'string' },
   lint: { type: 'boolean' },
+  name: { type: 'string' },
   'no-color': { type: 'boolean' },
   offset: { type: 'string' },
   plain: { type: 'boolean' },
@@ -96,34 +99,15 @@ 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
+    hasAdHocQueryCommand(command_name, command_line.values, command_positionals)
   ) {
-    return (
-      createMessageParseError(
-        findInvalidQueryPagination(command_line.option_tokens),
-      ) ??
-      findInvalidQueryMode(
-        command_name,
-        command_line.values,
-        command_positionals,
-      )
-    );
+    return validateAdHocQueryCommand(command_line, 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)
+  return validateStandardCommand(
+    command_name,
+    command_line,
+    command_positionals,
   );
 }
 
@@ -154,17 +138,134 @@ export function buildCommandArguments(
   command_positionals,
   parsed_values,
 ) {
-  if (command_name === 'query' && parsed_values.where !== undefined) {
-    return ['--where', parsed_values.where];
+  if (command_name === 'query' || command_name === 'refs') {
+    return buildAdHocQueryArguments(
+      command_name,
+      command_positionals,
+      parsed_values,
+    );
   }
 
-  if (command_name === 'refs' && parsed_values.where !== undefined) {
-    return [command_positionals[0], '--where', parsed_values.where];
+  if (command_name === 'queries') {
+    return buildStoredQueryArguments(command_positionals, parsed_values);
+  }
+
+  return command_positionals;
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @param {CliOptionValues} parsed_values
+ * @param {string[]} command_positionals
+ * @returns {boolean}
+ */
+function hasAdHocQueryCommand(
+  command_name,
+  parsed_values,
+  command_positionals,
+) {
+  return (
+    command_name === 'query' &&
+    parsed_values.cypher !== undefined &&
+    command_positionals.length === 0
+  );
+}
+
+/**
+ * @param {ParsedCommandLine} command_line
+ * @param {string[]} command_positionals
+ * @returns {CliParseError | null}
+ */
+function validateAdHocQueryCommand(command_line, command_positionals) {
+  return (
+    findInvalidCommandOption('query', command_line.option_tokens) ??
+    createMessageParseError(
+      findInvalidQueryPagination(command_line.option_tokens),
+    ) ??
+    findInvalidQueryMode('query', command_line.values, command_positionals)
+  );
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @param {ParsedCommandLine} command_line
+ * @param {string[]} command_positionals
+ * @returns {CliParseError | null}
+ */
+function validateStandardCommand(
+  command_name,
+  command_line,
+  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,
+    ) ??
+    findInvalidQueriesMutation(
+      command_name,
+      command_line.values,
+      command_positionals,
+    ) ??
+    validateCommandPositionals(command_name, command_positionals)
+  );
+}
+
+/**
+ * @param {'query' | 'refs'} command_name
+ * @param {string[]} command_positionals
+ * @param {CliOptionValues} parsed_values
+ * @returns {string[]}
+ */
+function buildAdHocQueryArguments(
+  command_name,
+  command_positionals,
+  parsed_values,
+) {
+  if (parsed_values.cypher !== undefined) {
+    return command_name === 'query'
+      ? ['--cypher', parsed_values.cypher]
+      : [command_positionals[0], '--cypher', parsed_values.cypher];
   }
 
   return command_positionals;
 }
 
+/**
+ * @param {string[]} command_positionals
+ * @param {CliOptionValues} parsed_values
+ * @returns {string[]}
+ */
+function buildStoredQueryArguments(command_positionals, parsed_values) {
+  /** @type {string[]} */
+  const command_arguments = [...command_positionals];
+
+  appendOptionValue(command_arguments, '--name', parsed_values.name);
+  appendOptionValue(command_arguments, '--cypher', parsed_values.cypher);
+  appendOptionValue(command_arguments, '--desc', parsed_values.desc);
+
+  return command_arguments;
+}
+
+/**
+ * @param {string[]} command_arguments
+ * @param {string} option_name
+ * @param {string | undefined} option_value
+ */
+function appendOptionValue(command_arguments, option_name, option_value) {
+  if (option_value === undefined) {
+    return;
+  }
+
+  command_arguments.push(option_name, option_value);
+}
+
 /**
  * @param {string | undefined} help_target
  * @returns {CliParseError}
@@ -305,24 +406,10 @@ function findInvalidCommandOption(command_name, option_tokens) {
  */
 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',
-      };
-    }
+    const missing_value_error = findMissingOptionValueError(token);
 
-    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.');
+    if (missing_value_error) {
+      return missing_value_error;
     }
   }
 
@@ -356,14 +443,38 @@ function findInvalidQueryMode(
 ) {
   if (
     command_name === 'query' &&
-    parsed_values.where !== undefined &&
+    parsed_values.cypher !== undefined &&
     command_positionals.length > 0
   ) {
     return createMessageParseError(
-      'Query accepts either "--where" or a stored query name.',
+      'Query accepts either "--cypher" or a stored query name.',
     );
   }
 
+  if (command_name === 'query' && parsed_values.where !== undefined) {
+    return {
+      code: 'option_not_valid_for_command',
+      command_name: 'query',
+      token: '--where',
+    };
+  }
+
+  if (command_name === 'queries' && parsed_values.where !== undefined) {
+    return {
+      code: 'option_not_valid_for_command',
+      command_name: 'queries',
+      token: '--where',
+    };
+  }
+
+  if (command_name === 'refs' && parsed_values.where !== undefined) {
+    return {
+      code: 'option_not_valid_for_command',
+      command_name: 'refs',
+      token: '--where',
+    };
+  }
+
   return null;
 }
 
@@ -386,6 +497,42 @@ function findInvalidQueryInspection(command_name, parsed_values) {
   return null;
 }
 
+/**
+ * @param {CliCommandName} command_name
+ * @param {CliOptionValues} parsed_values
+ * @param {string[]} command_positionals
+ * @returns {CliParseError | null}
+ */
+function findInvalidQueriesMutation(
+  command_name,
+  parsed_values,
+  command_positionals,
+) {
+  if (command_name !== 'queries' || command_positionals.length === 0) {
+    return null;
+  }
+
+  const subcommand_name = command_positionals[0];
+
+  if (
+    subcommand_name !== 'add' &&
+    subcommand_name !== 'remove' &&
+    subcommand_name !== 'update'
+  ) {
+    return createUnexpectedArgumentError('queries', subcommand_name);
+  }
+
+  if (subcommand_name === 'add') {
+    return validateQueriesAddMutation(parsed_values, command_positionals);
+  }
+
+  if (subcommand_name === 'remove') {
+    return validateQueriesRemoveMutation(parsed_values, command_positionals);
+  }
+
+  return validateQueriesUpdateMutation(parsed_values, command_positionals);
+}
+
 /**
  * @param {CliCommandName} command_name
  * @param {string[]} command_positionals
@@ -394,24 +541,18 @@ function findInvalidQueryInspection(command_name, parsed_values) {
 function validateCommandPositionals(command_name, command_positionals) {
   const command_definition = getCommandDefinition(command_name);
 
+  if (allowsQueriesMutationPositionals(command_name, command_positionals)) {
+    return null;
+  }
+
   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',
-      };
-    }
+    const missing_argument_error = createMissingArgumentError(
+      command_name,
+      command_definition.missing_argument_label,
+    );
 
-    if (
-      (command_name === 'refs' || command_name === 'show') &&
-      command_definition.missing_argument_label
-    ) {
-      return {
-        argument_label: command_definition.missing_argument_label,
-        code: 'missing_required_argument',
-        command_name,
-      };
+    if (missing_argument_error) {
+      return missing_argument_error;
     }
 
     return createMessageParseError(
@@ -428,7 +569,7 @@ function validateCommandPositionals(command_name, command_positionals) {
 
   if (command_name === 'query' && command_positionals.length === 0) {
     return {
-      argument_label: "<name> or --where '<clause>'",
+      argument_label: "<name> or --cypher '<query>'",
       code: 'missing_required_argument',
       command_name: 'query',
     };
@@ -443,14 +584,223 @@ function validateCommandPositionals(command_name, command_positionals) {
  */
 function isKnownCommandOptionName(option_name) {
   return (
+    option_name === 'desc' ||
+    option_name === 'cypher' ||
     option_name === 'explain' ||
     option_name === 'limit' ||
     option_name === 'lint' ||
+    option_name === 'name' ||
     option_name === 'offset' ||
+    option_name === 'query' ||
     option_name === 'where'
   );
 }
 
+/**
+ * @param {CliOptionToken} option_token
+ * @returns {CliParseError | null}
+ */
+function findMissingOptionValueError(option_token) {
+  if (typeof option_token.value === 'string') {
+    return null;
+  }
+
+  if (option_token.name === 'where') {
+    return createMessageParseError('Where requires a value.');
+  }
+
+  if (option_token.name === 'cypher') {
+    return {
+      argument_label: "<name> or --cypher '<query>'",
+      code: 'missing_required_argument',
+      command_name: 'query',
+    };
+  }
+
+  const message = getMissingOptionValueMessage(option_token.name);
+
+  if (!message) {
+    return null;
+  }
+
+  return createMessageParseError(message);
+}
+
+/**
+ * @param {string | undefined} option_name
+ * @returns {string | null}
+ */
+function getMissingOptionValueMessage(option_name) {
+  /** @type {Record<string, string>} */
+  const option_messages = {
+    color: 'Color requires a value.',
+    cypher: 'Cypher requires a value.',
+    desc: 'Desc requires a value.',
+    limit: 'Limit requires a value.',
+    name: 'Name requires a value.',
+    offset: 'Offset requires a value.',
+    query: 'Query requires a value.',
+    where: 'Where requires a value.',
+  };
+
+  if (!option_name || !Object.hasOwn(option_messages, option_name)) {
+    return null;
+  }
+
+  return option_messages[option_name];
+}
+
+/**
+ * @param {CliOptionValues} parsed_values
+ * @param {string[]} command_positionals
+ * @returns {CliParseError | null}
+ */
+function validateQueriesAddMutation(parsed_values, command_positionals) {
+  const positional_error = validateQueriesMutationPositionals(
+    command_positionals,
+    'Queries add requires a stored query name.',
+  );
+
+  if (positional_error) {
+    return positional_error;
+  }
+
+  if (parsed_values.name !== undefined) {
+    return createMessageParseError('Queries add does not accept "--name".');
+  }
+
+  if (parsed_values.cypher === undefined) {
+    return createMessageParseError('Queries add requires "--cypher <query>".');
+  }
+
+  return null;
+}
+
+/**
+ * @param {CliOptionValues} parsed_values
+ * @param {string[]} command_positionals
+ * @returns {CliParseError | null}
+ */
+function validateQueriesRemoveMutation(parsed_values, command_positionals) {
+  const positional_error = validateQueriesMutationPositionals(
+    command_positionals,
+    'Queries remove requires a stored query name.',
+  );
+
+  if (positional_error) {
+    return positional_error;
+  }
+
+  if (
+    parsed_values.desc !== undefined ||
+    parsed_values.cypher !== undefined ||
+    parsed_values.name !== undefined ||
+    parsed_values.where !== undefined
+  ) {
+    return createMessageParseError(
+      'Queries remove does not accept mutation options.',
+    );
+  }
+
+  return null;
+}
+
+/**
+ * @param {CliOptionValues} parsed_values
+ * @param {string[]} command_positionals
+ * @returns {CliParseError | null}
+ */
+function validateQueriesUpdateMutation(parsed_values, command_positionals) {
+  const positional_error = validateQueriesMutationPositionals(
+    command_positionals,
+    'Queries update requires a stored query name.',
+  );
+
+  if (positional_error) {
+    return positional_error;
+  }
+
+  if (
+    parsed_values.desc === undefined &&
+    parsed_values.cypher === undefined &&
+    parsed_values.name === undefined
+  ) {
+    return createMessageParseError(
+      'Queries update requires at least one of "--name", "--cypher", or "--desc".',
+    );
+  }
+
+  return null;
+}
+
+/**
+ * @param {string[]} command_positionals
+ * @param {string} missing_name_message
+ * @returns {CliParseError | null}
+ */
+function validateQueriesMutationPositionals(
+  command_positionals,
+  missing_name_message,
+) {
+  if (command_positionals.length < 2) {
+    return createMessageParseError(missing_name_message);
+  }
+
+  if (command_positionals.length > 2) {
+    return createUnexpectedArgumentError('queries', command_positionals[2]);
+  }
+
+  return null;
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @param {string[]} command_positionals
+ * @returns {boolean}
+ */
+function allowsQueriesMutationPositionals(command_name, command_positionals) {
+  if (command_name !== 'queries' || command_positionals.length === 0) {
+    return false;
+  }
+
+  const subcommand_name = command_positionals[0];
+
+  return (
+    subcommand_name === 'add' ||
+    subcommand_name === 'remove' ||
+    subcommand_name === 'update'
+  );
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @param {string | null} missing_argument_label
+ * @returns {CliParseError | null}
+ */
+function createMissingArgumentError(command_name, missing_argument_label) {
+  if (!missing_argument_label) {
+    return null;
+  }
+
+  if (command_name === 'query') {
+    return {
+      argument_label: missing_argument_label,
+      code: 'missing_required_argument',
+      command_name: 'query',
+    };
+  }
+
+  if (command_name === 'refs' || command_name === 'show') {
+    return {
+      argument_label: missing_argument_label,
+      code: 'missing_required_argument',
+      command_name,
+    };
+  }
+
+  return null;
+}
+
 /**
  * @param {'help' | CliCommandName} command_name
  * @param {string | undefined} token

package/lib/cli/parse-arguments.js

@@ -34,10 +34,10 @@ import { buildQueryPagination } from './query-pagination.js';
  * 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
+ * kind: cli
+ * status: active
+ * tracked_in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * decided_by: ../../docs/decisions/cli-argument-parser.md
  * @patram
  * @see {@link ./main.js}
  * @see {@link ../../docs/decisions/cli-argument-parser.md}

package/lib/cli/render-help.js

@@ -85,6 +85,7 @@ export function renderCliParseError(parse_error) {
   if (parse_error.code === 'unknown_stored_query') {
     return renderUnknownStoredQueryError(
       parse_error.name,
+      parse_error.next_path,
       parse_error.suggestion,
     );
   }
@@ -100,7 +101,7 @@ export function renderInvalidWhereDiagnostic(diagnostic) {
   const diagnostic_line = formatDiagnostic(diagnostic);
 
   return joinOutputLines([
-    'Invalid where clause:',
+    'Invalid query:',
     `  ${diagnostic_line}`,
     '',
     'Next:',
@@ -156,7 +157,7 @@ function renderCommandHelp(command_name) {
   ) {
     output_lines.push(
       '',
-      'Where clause:',
+      'Query syntax:',
       ...indentLines(command_definition.syntax_lines),
     );
   }
@@ -359,10 +360,15 @@ function renderUnexpectedArgumentError(command_name, invalid_token) {
 
 /**
  * @param {string} stored_query_name
+ * @param {string | undefined} next_path
  * @param {string | undefined} suggestion
  * @returns {string}
  */
-function renderUnknownStoredQueryError(stored_query_name, suggestion) {
+function renderUnknownStoredQueryError(
+  stored_query_name,
+  next_path,
+  suggestion,
+) {
   if (suggestion) {
     return joinOutputLines([
       `Unknown stored query: ${stored_query_name}`,
@@ -371,7 +377,7 @@ function renderUnknownStoredQueryError(stored_query_name, suggestion) {
       `  ${suggestion}`,
       '',
       'Next:',
-      `  patram query ${suggestion}`,
+      `  ${next_path ?? `patram query ${suggestion}`}`,
     ]);
   }