patram 0.9.0 → 0.11.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, desc?: string, explain?: boolean, help?: boolean, json?: boolean, limit?: string, lint?: boolean, name?: string, 'no-color'?: boolean, offset?: string, plain?: boolean, query?: string, where?: string }} CliOptionValues
  * @typedef {{ option_tokens: CliOptionToken[], positionals: string[], values: CliOptionValues }} ParsedCommandLine
  */
 
@@ -23,14 +23,17 @@ import { findInvalidQueryPagination } from './query-pagination.js';
 
 export const CLI_OPTIONS = /** @type {const} */ ({
   color: { 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' },
+  query: { type: 'string' },
   where: { type: 'string' },
 });
 
@@ -67,9 +70,7 @@ export function validateHelpCommandLine(command_line) {
   }
 
   if (command_line.positionals.length > 2) {
-    return createMessageParseError(
-      'Help accepts at most one topic or command.',
-    );
+    return createUnexpectedArgumentError('help', command_line.positionals[2]);
   }
 
   return null;
@@ -125,6 +126,11 @@ export function validateParsedCommand(command_name, command_line) {
       command_line.values,
       command_positionals,
     ) ??
+    findInvalidQueriesMutation(
+      command_name,
+      command_line.values,
+      command_positionals,
+    ) ??
     validateCommandPositionals(command_name, command_positionals)
   );
 }
@@ -164,6 +170,25 @@ export function buildCommandArguments(
     return [command_positionals[0], '--where', parsed_values.where];
   }
 
+  if (command_name === 'queries') {
+    /** @type {string[]} */
+    const command_arguments = [...command_positionals];
+
+    if (parsed_values.name !== undefined) {
+      command_arguments.push('--name', parsed_values.name);
+    }
+
+    if (parsed_values.query !== undefined) {
+      command_arguments.push('--query', parsed_values.query);
+    }
+
+    if (parsed_values.desc !== undefined) {
+      command_arguments.push('--desc', parsed_values.desc);
+    }
+
+    return command_arguments;
+  }
+
   return command_positionals;
 }
 
@@ -307,24 +332,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',
-      };
-    }
-
-    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.');
-    }
+    const missing_value_error = findMissingOptionValueError(token);
 
-    if (token.name === 'color' && typeof token.value !== 'string') {
-      return createMessageParseError('Color requires a value.');
+    if (missing_value_error) {
+      return missing_value_error;
     }
   }
 
@@ -388,6 +399,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
@@ -396,24 +443,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(
@@ -422,8 +463,9 @@ function validateCommandPositionals(command_name, command_positionals) {
   }
 
   if (command_positionals.length > command_definition.max_positionals) {
-    return createMessageParseError(
-      command_definition.extra_positionals_message,
+    return createUnexpectedArgumentError(
+      command_name,
+      command_positionals[command_definition.max_positionals],
     );
   }
 
@@ -444,10 +486,224 @@ function validateCommandPositionals(command_name, command_positionals) {
  */
 function isKnownCommandOptionName(option_name) {
   return (
+    option_name === 'desc' ||
     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 {
+      argument_label: "<name> or --where '<clause>'",
+      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.',
+    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.',
+  };
+
+  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.query === undefined) {
+    return createMessageParseError('Queries add requires "--query <clause>".');
+  }
+
+  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.name !== undefined ||
+    parsed_values.query !== 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.name === undefined &&
+    parsed_values.query === undefined
+  ) {
+    return createMessageParseError(
+      'Queries update requires at least one of "--name", "--query", 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
+ * @returns {CliParseError}
+ */
+function createUnexpectedArgumentError(command_name, token) {
+  return {
+    code: 'unexpected_argument',
+    command_name,
+    token: token ?? '',
+  };
+}

package/lib/cli/render-help.js

@@ -75,6 +75,21 @@ export function renderCliParseError(parse_error) {
     );
   }
 
+  if (parse_error.code === 'unexpected_argument') {
+    return renderUnexpectedArgumentError(
+      parse_error.command_name,
+      parse_error.token,
+    );
+  }
+
+  if (parse_error.code === 'unknown_stored_query') {
+    return renderUnknownStoredQueryError(
+      parse_error.name,
+      parse_error.next_path,
+      parse_error.suggestion,
+    );
+  }
+
   return `${parse_error.message}\n`;
 }
 
@@ -326,6 +341,54 @@ function renderMissingRequiredArgumentError(command_name, argument_label) {
   ]);
 }
 
+/**
+ * @param {'help' | CliCommandName} command_name
+ * @param {string} invalid_token
+ * @returns {string}
+ */
+function renderUnexpectedArgumentError(command_name, invalid_token) {
+  return joinOutputLines([
+    `Unexpected argument: ${invalid_token}`,
+    '',
+    'Usage:',
+    ...indentLines(getUnexpectedArgumentUsageLines(command_name)),
+    '',
+    'Next:',
+    `  ${renderUnexpectedArgumentNext(command_name)}`,
+  ]);
+}
+
+/**
+ * @param {string} stored_query_name
+ * @param {string | undefined} next_path
+ * @param {string | undefined} suggestion
+ * @returns {string}
+ */
+function renderUnknownStoredQueryError(
+  stored_query_name,
+  next_path,
+  suggestion,
+) {
+  if (suggestion) {
+    return joinOutputLines([
+      `Unknown stored query: ${stored_query_name}`,
+      '',
+      'Did you mean:',
+      `  ${suggestion}`,
+      '',
+      'Next:',
+      `  ${next_path ?? `patram query ${suggestion}`}`,
+    ]);
+  }
+
+  return joinOutputLines([
+    `Unknown stored query: ${stored_query_name}`,
+    '',
+    'Next:',
+    '  patram queries',
+  ]);
+}
+
 /**
  * @param {string} invalid_token
  * @param {CliCommandName | CliHelpTopicName | undefined} suggestion
@@ -378,6 +441,30 @@ function renderCommandHelpPath(command_name) {
   return `patram help ${command_name}`;
 }
 
+/**
+ * @param {'help' | CliCommandName} command_name
+ * @returns {string}
+ */
+function renderUnexpectedArgumentNext(command_name) {
+  if (command_name === 'help') {
+    return 'patram --help';
+  }
+
+  return renderCommandHelpPath(command_name);
+}
+
+/**
+ * @param {'help' | CliCommandName} command_name
+ * @returns {string[]}
+ */
+function getUnexpectedArgumentUsageLines(command_name) {
+  if (command_name === 'help') {
+    return ['patram help [command]'];
+  }
+
+  return getCommandDefinition(command_name).usage_lines;
+}
+
 /**
  * @param {string[]} lines
  * @returns {string[]}

package/lib/config/load-patram-config.d.ts

@@ -49,6 +49,17 @@
  * @returns {Promise<LoadPatramConfigResult>}
  */
 export function loadPatramConfig(project_directory?: string): Promise<LoadPatramConfigResult>;
+/**
+ * @param {string} config_source
+ * @returns {{ success: true, value: unknown } | { success: false, diagnostic: PatramDiagnostic }}
+ */
+export function parsePatramConfigSource(config_source: string): {
+    success: true;
+    value: unknown;
+} | {
+    success: false;
+    diagnostic: PatramDiagnostic;
+};
 export type PatramDiagnostic = {
     code: string;
     column: number;

package/lib/config/load-patram-config.js

@@ -18,15 +18,9 @@ import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import process from 'node:process';
 
-import { CONFIG_FILE_NAME, patram_repo_config_schema } from './schema.js';
-import { createDefaultRepoConfig, normalizeRepoConfig } from './defaults.js';
-import {
-  validateDerivedSummaries,
-  validateFieldSchemaConfig,
-  validateGraphSchema,
-  validateLegacyConfigShape,
-  validateStoredQueries,
-} from './validation.js';
+import { CONFIG_FILE_NAME } from './schema.js';
+import { createDefaultRepoConfig } from './defaults.js';
+import { validatePatramConfigValue } from './validate-patram-config-value.js';
 
 /**
  * Repo config loading.
@@ -90,56 +84,19 @@ export async function loadPatramConfig(project_directory = process.cwd()) {
     return createLoadResult(createDefaultRepoConfig(), []);
   }
 
-  const parse_result = parseConfigJson(config_source);
+  const parse_result = parsePatramConfigSource(config_source);
 
   if (!parse_result.success) {
     return createLoadResult(null, [parse_result.diagnostic]);
   }
 
-  const legacy_config_diagnostics = validateLegacyConfigShape(
-    parse_result.value,
-  );
+  const validation_result = validatePatramConfigValue(parse_result.value);
 
-  if (legacy_config_diagnostics.length > 0) {
-    return createLoadResult(null, legacy_config_diagnostics);
+  if (!validation_result.success) {
+    return createLoadResult(null, validation_result.diagnostics);
   }
 
-  const config_result = patram_repo_config_schema.safeParse(parse_result.value);
-
-  if (!config_result.success) {
-    return createLoadResult(
-      null,
-      config_result.error.issues.map(createValidationDiagnostic),
-    );
-  }
-
-  const graph_schema_diagnostics = validateGraphSchema(config_result.data);
-
-  if (graph_schema_diagnostics.length > 0) {
-    return createLoadResult(null, graph_schema_diagnostics);
-  }
-
-  const normalized_config = normalizeRepoConfig(config_result.data);
-  const field_schema_diagnostics = validateFieldSchemaConfig(normalized_config);
-
-  if (field_schema_diagnostics.length > 0) {
-    return createLoadResult(null, field_schema_diagnostics);
-  }
-
-  const stored_query_diagnostics = validateStoredQueries(normalized_config);
-
-  if (stored_query_diagnostics.length > 0) {
-    return createLoadResult(null, stored_query_diagnostics);
-  }
-
-  const derived_summary_diagnostics =
-    validateDerivedSummaries(normalized_config);
-
-  if (derived_summary_diagnostics.length > 0) {
-    return createLoadResult(null, derived_summary_diagnostics);
-  }
-
-  return createLoadResult(normalized_config, []);
+  return createLoadResult(validation_result.config, []);
 }
 
 /**
@@ -162,7 +119,7 @@ async function readConfigSource(config_file_path) {
  * @param {string} config_source
  * @returns {{ success: true, value: unknown } | { success: false, diagnostic: PatramDiagnostic }}
  */
-function parseConfigJson(config_source) {
+export function parsePatramConfigSource(config_source) {
   try {
     return {
       success: true,
@@ -211,34 +168,6 @@ function createInvalidJsonDiagnostic(config_source, error) {
   };
 }
 
-/**
- * @param {import('zod').core.$ZodIssue} issue
- * @returns {PatramDiagnostic}
- */
-function createValidationDiagnostic(issue) {
-  const issue_path = formatIssuePath(issue.path);
-
-  if (issue_path) {
-    return {
-      code: 'config.invalid',
-      column: 1,
-      level: 'error',
-      line: 1,
-      message: `Invalid config at "${issue_path}": ${issue.message}`,
-      path: CONFIG_FILE_NAME,
-    };
-  }
-
-  return {
-    code: 'config.invalid',
-    column: 1,
-    level: 'error',
-    line: 1,
-    message: `Invalid config: ${issue.message}`,
-    path: CONFIG_FILE_NAME,
-  };
-}
-
 /**
  * @param {unknown} error
  * @returns {error is NodeJS.ErrnoException}
@@ -281,14 +210,6 @@ function getJsonSyntaxOrigin(config_source, error_message) {
   };
 }
 
-/**
- * @param {(string | number | symbol | undefined)[]} issue_path
- * @returns {string}
- */
-function formatIssuePath(issue_path) {
-  return issue_path.map(String).join('.');
-}
-
 /**
  * @param {string} source_text
  * @param {number} offset