patram 0.10.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' },
 });
 
@@ -123,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)
   );
 }
@@ -162,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;
 }
 
@@ -305,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.');
-    }
+    const missing_value_error = findMissingOptionValueError(token);
 
-    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;
     }
   }
 
@@ -386,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
@@ -394,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(
@@ -443,14 +486,215 @@ 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

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,
     );
   }
@@ -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}`}`,
     ]);
   }
 

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

package/lib/config/manage-stored-queries-helpers.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @param {string} config_file_path
+ * @returns {Promise<
+ *   | { success: true, value: Record<string, unknown> }
+ *   | { diagnostic: PatramDiagnostic, success: false }
+ * >}
+ */
+export function loadRawConfig(config_file_path: string): Promise<{
+    success: true;
+    value: Record<string, unknown>;
+} | {
+    diagnostic: PatramDiagnostic;
+    success: false;
+}>;
+/**
+ * @param {string} config_file_path
+ * @param {Record<string, unknown>} raw_config
+ * @param {StoredQueryMutationResult} mutation_result
+ * @returns {Promise<
+ *   | { success: true, value: StoredQueryMutationResult }
+ *   | { diagnostics: PatramDiagnostic[], success: false }
+ * >}
+ */
+export function persistStoredQueryMutation(config_file_path: string, raw_config: Record<string, unknown>, mutation_result: StoredQueryMutationResult): Promise<{
+    success: true;
+    value: StoredQueryMutationResult;
+} | {
+    diagnostics: PatramDiagnostic[];
+    success: false;
+}>;
+/**
+ * @param {string} where_clause
+ * @param {string | undefined} description
+ * @returns {StoredQueryConfig}
+ */
+export function createStoredQueryDefinition(where_clause: string, description: string | undefined): StoredQueryConfig;
+/**
+ * @param {Record<string, unknown> | null} raw_query_value
+ * @param {StoredQueryConfig} existing_query
+ * @param {{ description?: string, where?: string }} stored_query_mutation
+ * @returns {StoredQueryConfig}
+ */
+export function createUpdatedStoredQueryDefinition(raw_query_value: Record<string, unknown> | null, existing_query: StoredQueryConfig, stored_query_mutation: {
+    description?: string;
+    where?: string;
+}): StoredQueryConfig;
+/**
+ * @param {Record<string, unknown>} raw_config
+ * @returns {Record<string, unknown>}
+ */
+export function ensureRawQueries(raw_config: Record<string, unknown>): Record<string, unknown>;
+/**
+ * @param {unknown} raw_query_value
+ * @returns {Record<string, unknown> | null}
+ */
+export function rawQueryValueToRecord(raw_query_value: unknown): Record<string, unknown> | null;
+export type StoredQueryMutationResult = {
+    action: "added";
+    name: string;
+} | {
+    action: "removed";
+    name: string;
+} | {
+    action: "updated";
+    name: string;
+    previous_name?: string;
+};
+import type { PatramDiagnostic } from './load-patram-config.types.d.ts';
+import type { StoredQueryConfig } from './load-patram-config.types.d.ts';