patram 0.9.0 → 0.11.0

package/lib/config/manage-stored-queries.js

@@ -0,0 +1,294 @@
+/**
+ * @import { CliParseError } from '../cli/arguments.types.ts';
+ * @import {
+ *   PatramDiagnostic,
+ *   PatramRepoConfig,
+ * } from './load-patram-config.types.ts';
+ */
+
+import { resolve } from 'node:path';
+
+import { loadPatramConfig } from './load-patram-config.js';
+import {
+  createStoredQueryDefinition,
+  createUpdatedStoredQueryDefinition,
+  ensureRawQueries,
+  loadRawConfig,
+  persistStoredQueryMutation,
+  rawQueryValueToRecord,
+} from './manage-stored-queries-helpers.js';
+import { CONFIG_FILE_NAME } from './schema.js';
+import { createUnknownStoredQueryError } from '../graph/query/resolve.js';
+
+/**
+ * @typedef {{
+ *   action: 'add',
+ *   description?: string,
+ *   name: string,
+ *   where: string,
+ * } | {
+ *   action: 'remove',
+ *   name: string,
+ * } | {
+ *   action: 'update',
+ *   description?: string,
+ *   name: string,
+ *   next_name?: string,
+ *   where?: string,
+ * }} StoredQueryMutation
+ */
+
+/**
+ * @typedef {{
+ *   action: 'added',
+ *   name: string,
+ * } | {
+ *   action: 'removed',
+ *   name: string,
+ * } | {
+ *   action: 'updated',
+ *   name: string,
+ *   previous_name?: string,
+ * }} StoredQueryMutationResult
+ */
+
+/**
+ * @param {string} project_directory
+ * @param {StoredQueryMutation} stored_query_mutation
+ * @returns {Promise<
+ *   | { success: true, value: StoredQueryMutationResult }
+ *   | { diagnostics: PatramDiagnostic[], success: false }
+ *   | { error: CliParseError, success: false }
+ * >}
+ */
+export async function manageStoredQueries(
+  project_directory,
+  stored_query_mutation,
+) {
+  const load_result = await loadPatramConfig(project_directory);
+
+  if (load_result.diagnostics.length > 0) {
+    return {
+      diagnostics: load_result.diagnostics,
+      success: false,
+    };
+  }
+
+  const repo_config = load_result.config;
+
+  if (!repo_config) {
+    throw new Error('Expected a valid Patram repo config.');
+  }
+
+  const config_file_path = resolve(project_directory, CONFIG_FILE_NAME);
+  const raw_config_result = await loadRawConfig(config_file_path);
+
+  if (!raw_config_result.success) {
+    return {
+      diagnostics: [raw_config_result.diagnostic],
+      success: false,
+    };
+  }
+
+  if (stored_query_mutation.action === 'add') {
+    return applyAddStoredQuery(
+      config_file_path,
+      raw_config_result.value,
+      repo_config,
+      stored_query_mutation,
+    );
+  }
+
+  if (stored_query_mutation.action === 'remove') {
+    return applyRemoveStoredQuery(
+      config_file_path,
+      raw_config_result.value,
+      repo_config,
+      stored_query_mutation,
+    );
+  }
+
+  return applyUpdateStoredQuery(
+    config_file_path,
+    raw_config_result.value,
+    repo_config,
+    stored_query_mutation,
+  );
+}
+
+/**
+ * @param {string} config_file_path
+ * @param {Record<string, unknown>} raw_config
+ * @param {PatramRepoConfig} repo_config
+ * @param {{ description?: string, name: string, where: string }} stored_query_mutation
+ * @returns {Promise<
+ *   | { success: true, value: StoredQueryMutationResult }
+ *   | { diagnostics: PatramDiagnostic[], success: false }
+ *   | { error: CliParseError, success: false }
+ * >}
+ */
+async function applyAddStoredQuery(
+  config_file_path,
+  raw_config,
+  repo_config,
+  stored_query_mutation,
+) {
+  if (repo_config.queries[stored_query_mutation.name]) {
+    return {
+      error: {
+        code: 'message',
+        message: `Stored query already exists: ${stored_query_mutation.name}.`,
+      },
+      success: false,
+    };
+  }
+
+  const raw_queries = ensureRawQueries(raw_config);
+  raw_queries[stored_query_mutation.name] = createStoredQueryDefinition(
+    stored_query_mutation.where,
+    stored_query_mutation.description,
+  );
+
+  return persistStoredQueryMutation(config_file_path, raw_config, {
+    action: 'added',
+    name: stored_query_mutation.name,
+  });
+}
+
+/**
+ * @param {string} config_file_path
+ * @param {Record<string, unknown>} raw_config
+ * @param {PatramRepoConfig} repo_config
+ * @param {{ name: string }} stored_query_mutation
+ * @returns {Promise<
+ *   | { success: true, value: StoredQueryMutationResult }
+ *   | { diagnostics: PatramDiagnostic[], success: false }
+ *   | { error: CliParseError, success: false }
+ * >}
+ */
+async function applyRemoveStoredQuery(
+  config_file_path,
+  raw_config,
+  repo_config,
+  stored_query_mutation,
+) {
+  if (!repo_config.queries[stored_query_mutation.name]) {
+    return {
+      error: createQueryMutationUnknownStoredQueryError(
+        stored_query_mutation.name,
+        Object.keys(repo_config.queries),
+        'remove',
+      ),
+      success: false,
+    };
+  }
+
+  const raw_queries = ensureRawQueries(raw_config);
+  delete raw_queries[stored_query_mutation.name];
+
+  return persistStoredQueryMutation(config_file_path, raw_config, {
+    action: 'removed',
+    name: stored_query_mutation.name,
+  });
+}
+
+/**
+ * @param {string} config_file_path
+ * @param {Record<string, unknown>} raw_config
+ * @param {PatramRepoConfig} repo_config
+ * @param {{ description?: string, name: string, next_name?: string, where?: string }} stored_query_mutation
+ * @returns {Promise<
+ *   | { success: true, value: StoredQueryMutationResult }
+ *   | { diagnostics: PatramDiagnostic[], success: false }
+ *   | { error: CliParseError, success: false }
+ * >}
+ */
+async function applyUpdateStoredQuery(
+  config_file_path,
+  raw_config,
+  repo_config,
+  stored_query_mutation,
+) {
+  const existing_query = repo_config.queries[stored_query_mutation.name];
+
+  if (!existing_query) {
+    return {
+      error: createQueryMutationUnknownStoredQueryError(
+        stored_query_mutation.name,
+        Object.keys(repo_config.queries),
+        'update',
+      ),
+      success: false,
+    };
+  }
+
+  const next_name =
+    stored_query_mutation.next_name ?? stored_query_mutation.name;
+
+  if (
+    next_name !== stored_query_mutation.name &&
+    repo_config.queries[next_name]
+  ) {
+    return {
+      error: {
+        code: 'message',
+        message: `Stored query already exists: ${next_name}.`,
+      },
+      success: false,
+    };
+  }
+
+  const raw_queries = ensureRawQueries(raw_config);
+  const raw_query_value = rawQueryValueToRecord(
+    raw_queries[stored_query_mutation.name],
+  );
+  const next_query = createUpdatedStoredQueryDefinition(
+    raw_query_value,
+    existing_query,
+    stored_query_mutation,
+  );
+
+  if (next_name !== stored_query_mutation.name) {
+    delete raw_queries[stored_query_mutation.name];
+  }
+
+  raw_queries[next_name] = next_query;
+
+  return persistStoredQueryMutation(config_file_path, raw_config, {
+    action: 'updated',
+    name: next_name,
+    previous_name:
+      next_name === stored_query_mutation.name
+        ? undefined
+        : stored_query_mutation.name,
+  });
+}
+
+/**
+ * @param {string} stored_query_name
+ * @param {string[]} stored_query_names
+ * @param {'remove' | 'update'} subcommand_name
+ * @returns {CliParseError}
+ */
+function createQueryMutationUnknownStoredQueryError(
+  stored_query_name,
+  stored_query_names,
+  subcommand_name,
+) {
+  const parse_error = createUnknownStoredQueryError(
+    stored_query_name,
+    stored_query_names,
+  );
+
+  if (
+    parse_error.code !== 'unknown_stored_query' ||
+    parse_error.suggestion === undefined
+  ) {
+    return parse_error;
+  }
+
+  return {
+    ...parse_error,
+    next_path: `patram queries ${subcommand_name} ${parse_error.suggestion}`,
+  };
+}

package/lib/config/schema.d.ts

@@ -141,6 +141,7 @@ export const patram_repo_config_schema: z.ZodObject<{
         prefixes: z.ZodArray<z.ZodString>;
     }, z.core.$strict>>>;
     queries: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
         where: z.ZodString;
     }, z.core.$strict>>>;
     relations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -167,6 +168,7 @@ import { z } from 'zod';
  * @typedef {z.output<typeof stored_query_schema>} StoredQueryConfig
  */
 declare const stored_query_schema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
     where: z.ZodString;
 }, z.core.$strict>;
 /**

package/lib/config/schema.js

@@ -27,6 +27,10 @@ const MIXED_STYLE_VALUES = new Set(['ignore', 'error']);
  */
 const stored_query_schema = z
   .object({
+    description: z
+      .string()
+      .min(1, 'Stored query "description" must not be empty.')
+      .optional(),
     where: z.string().min(1, 'Stored query "where" must not be empty.'),
   })
   .strict();

package/lib/config/validate-patram-config-value.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @param {unknown} config_value
+ * @returns {{ config: PatramRepoConfig, success: true } | { diagnostics: PatramDiagnostic[], success: false }}
+ */
+export function validatePatramConfigValue(config_value: unknown): {
+    config: PatramRepoConfig;
+    success: true;
+} | {
+    diagnostics: PatramDiagnostic[];
+    success: false;
+};
+import type { PatramRepoConfig } from './load-patram-config.types.d.ts';
+import type { PatramDiagnostic } from './load-patram-config.types.d.ts';

package/lib/config/validate-patram-config-value.js

@@ -0,0 +1,119 @@
+/**
+ * @import {
+ *   PatramDiagnostic,
+ *   PatramRepoConfig,
+ * } from './load-patram-config.types.ts';
+ */
+
+import { patram_repo_config_schema } from './schema.js';
+import { normalizeRepoConfig } from './defaults.js';
+import {
+  validateDerivedSummaries,
+  validateFieldSchemaConfig,
+  validateGraphSchema,
+  validateLegacyConfigShape,
+  validateStoredQueries,
+} from './validation.js';
+
+/**
+ * @param {unknown} config_value
+ * @returns {{ config: PatramRepoConfig, success: true } | { diagnostics: PatramDiagnostic[], success: false }}
+ */
+export function validatePatramConfigValue(config_value) {
+  const legacy_config_diagnostics = validateLegacyConfigShape(config_value);
+
+  if (legacy_config_diagnostics.length > 0) {
+    return {
+      diagnostics: legacy_config_diagnostics,
+      success: false,
+    };
+  }
+
+  const config_result = patram_repo_config_schema.safeParse(config_value);
+
+  if (!config_result.success) {
+    return {
+      diagnostics: config_result.error.issues.map(createValidationDiagnostic),
+      success: false,
+    };
+  }
+
+  const graph_schema_diagnostics = validateGraphSchema(config_result.data);
+
+  if (graph_schema_diagnostics.length > 0) {
+    return {
+      diagnostics: graph_schema_diagnostics,
+      success: false,
+    };
+  }
+
+  const normalized_config = normalizeRepoConfig(config_result.data);
+  const field_schema_diagnostics = validateFieldSchemaConfig(normalized_config);
+
+  if (field_schema_diagnostics.length > 0) {
+    return {
+      diagnostics: field_schema_diagnostics,
+      success: false,
+    };
+  }
+
+  const stored_query_diagnostics = validateStoredQueries(normalized_config);
+
+  if (stored_query_diagnostics.length > 0) {
+    return {
+      diagnostics: stored_query_diagnostics,
+      success: false,
+    };
+  }
+
+  const derived_summary_diagnostics =
+    validateDerivedSummaries(normalized_config);
+
+  if (derived_summary_diagnostics.length > 0) {
+    return {
+      diagnostics: derived_summary_diagnostics,
+      success: false,
+    };
+  }
+
+  return {
+    config: normalized_config,
+    success: true,
+  };
+}
+
+/**
+ * @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: '.patram.json',
+    };
+  }
+
+  return {
+    code: 'config.invalid',
+    column: 1,
+    level: 'error',
+    line: 1,
+    message: `Invalid config: ${issue.message}`,
+    path: '.patram.json',
+  };
+}
+
+/**
+ * @param {(string | number | symbol | undefined)[]} issue_path
+ * @returns {string}
+ */
+function formatIssuePath(issue_path) {
+  return issue_path.map(String).join('.');
+}

package/lib/find-close-match.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Find the closest candidate above the shared suggestion threshold.
+ *
+ * @param {string} input_text
+ * @param {readonly string[]} candidates
+ * @returns {string | undefined}
+ */
+export function findCloseMatch(input_text: string, candidates: readonly string[]): string | undefined;

package/lib/find-close-match.js

@@ -0,0 +1,98 @@
+/**
+ * Find the closest candidate above the shared suggestion threshold.
+ *
+ * @param {string} input_text
+ * @param {readonly string[]} candidates
+ * @returns {string | undefined}
+ */
+export function findCloseMatch(input_text, candidates) {
+  let best_candidate;
+  let best_score = 0;
+
+  for (const candidate of candidates) {
+    const score = scoreCandidate(input_text, candidate);
+
+    if (score > best_score) {
+      best_candidate = candidate;
+      best_score = score;
+    }
+  }
+
+  if (best_score < 0.6) {
+    return undefined;
+  }
+
+  return best_candidate;
+}
+
+/**
+ * @param {string} input_text
+ * @param {string} candidate
+ * @returns {number}
+ */
+function scoreCandidate(input_text, candidate) {
+  const max_length = Math.max(input_text.length, candidate.length);
+
+  if (max_length === 0) {
+    return 1;
+  }
+
+  return (
+    1 - calculateDamerauLevenshteinDistance(input_text, candidate) / max_length
+  );
+}
+
+/**
+ * @param {string} left_text
+ * @param {string} right_text
+ * @returns {number}
+ */
+function calculateDamerauLevenshteinDistance(left_text, right_text) {
+  /** @type {number[][]} */
+  const matrix = Array.from({ length: left_text.length + 1 }, () =>
+    Array.from({ length: right_text.length + 1 }, () => 0),
+  );
+
+  for (let left_index = 0; left_index <= left_text.length; left_index += 1) {
+    matrix[left_index][0] = left_index;
+  }
+
+  for (
+    let right_index = 0;
+    right_index <= right_text.length;
+    right_index += 1
+  ) {
+    matrix[0][right_index] = right_index;
+  }
+
+  for (let left_index = 1; left_index <= left_text.length; left_index += 1) {
+    for (
+      let right_index = 1;
+      right_index <= right_text.length;
+      right_index += 1
+    ) {
+      const substitution_cost =
+        left_text[left_index - 1] === right_text[right_index - 1] ? 0 : 1;
+
+      matrix[left_index][right_index] = Math.min(
+        matrix[left_index - 1][right_index] + 1,
+        matrix[left_index][right_index - 1] + 1,
+        matrix[left_index - 1][right_index - 1] + substitution_cost,
+      );
+
+      if (
+        left_index > 1 &&
+        right_index > 1 &&
+        left_text[left_index - 1] === right_text[right_index - 2] &&
+        left_text[left_index - 2] === right_text[right_index - 1]
+      ) {
+        matrix[left_index][right_index] = Math.min(
+          matrix[left_index][right_index],
+          matrix[left_index - 2][right_index - 2] + substitution_cost,
+        );
+      }
+    }
+  }
+
+  return matrix[left_text.length][right_text.length];
+}

package/lib/graph/query/resolve.d.ts

@@ -1,6 +1,3 @@
-/**
- * @import { PatramRepoConfig } from '../../config/load-patram-config.types.d.ts';
- */
 /**
  * @typedef {{ kind: 'ad_hoc' } | { kind: 'stored_query', name: string }} QuerySource
  */
@@ -9,7 +6,7 @@
  *
  * @param {PatramRepoConfig} repo_config
  * @param {string[]} command_arguments
- * @returns {{ success: true, value: { query_source: QuerySource, where_clause: string } } | { success: false, message: string }}
+ * @returns {{ success: true, value: { query_source: QuerySource, where_clause: string } } | { error: CliParseError, success: false }}
  */
 export function resolveWhereClause(repo_config: PatramRepoConfig, command_arguments: string[]): {
     success: true;
@@ -18,9 +15,15 @@ export function resolveWhereClause(repo_config: PatramRepoConfig, command_argume
         where_clause: string;
     };
 } | {
+    error: CliParseError;
     success: false;
-    message: string;
 };
+/**
+ * @param {string} stored_query_name
+ * @param {string[]} stored_query_names
+ * @returns {CliParseError}
+ */
+export function createUnknownStoredQueryError(stored_query_name: string, stored_query_names: string[]): CliParseError;
 export type QuerySource = {
     kind: "ad_hoc";
 } | {
@@ -28,3 +31,4 @@ export type QuerySource = {
     name: string;
 };
 import type { PatramRepoConfig } from '../../config/load-patram-config.types.d.ts';
+import type { CliParseError } from '../../cli/arguments.types.d.ts';

package/lib/graph/query/resolve.js

@@ -1,7 +1,10 @@
 /**
+ * @import { CliParseError } from '../../cli/arguments.types.ts';
  * @import { PatramRepoConfig } from '../../config/load-patram-config.types.ts';
  */
 
+import { findCloseMatch } from '../../find-close-match.js';
+
 /**
  * @typedef {{ kind: 'ad_hoc' } | { kind: 'stored_query', name: string }} QuerySource
  */
@@ -11,7 +14,7 @@
  *
  * @param {PatramRepoConfig} repo_config
  * @param {string[]} command_arguments
- * @returns {{ success: true, value: { query_source: QuerySource, where_clause: string } } | { success: false, message: string }}
+ * @returns {{ success: true, value: { query_source: QuerySource, where_clause: string } } | { error: CliParseError, success: false }}
  */
 export function resolveWhereClause(repo_config, command_arguments) {
   if (command_arguments[0] === '--where') {
@@ -19,7 +22,10 @@ export function resolveWhereClause(repo_config, command_arguments) {
 
     if (where_clause.length === 0) {
       return {
-        message: 'Query requires a where clause.',
+        error: {
+          code: 'message',
+          message: 'Query requires a where clause.',
+        },
         success: false,
       };
     }
@@ -39,7 +45,10 @@ export function resolveWhereClause(repo_config, command_arguments) {
 
   if (!stored_query_name) {
     return {
-      message: 'Query requires "--where" or a stored query name.',
+      error: {
+        code: 'message',
+        message: 'Query requires "--where" or a stored query name.',
+      },
       success: false,
     };
   }
@@ -48,7 +57,10 @@ export function resolveWhereClause(repo_config, command_arguments) {
 
   if (!stored_query) {
     return {
-      message: `Stored query "${stored_query_name}" was not found.`,
+      error: createUnknownStoredQueryError(
+        stored_query_name,
+        Object.keys(repo_config.queries),
+      ),
       success: false,
     };
   }
@@ -64,3 +76,28 @@ export function resolveWhereClause(repo_config, command_arguments) {
     },
   };
 }
+
+/**
+ * @param {string} stored_query_name
+ * @param {string[]} stored_query_names
+ * @returns {CliParseError}
+ */
+export function createUnknownStoredQueryError(
+  stored_query_name,
+  stored_query_names,
+) {
+  const suggestion = findCloseMatch(stored_query_name, stored_query_names);
+
+  if (!suggestion) {
+    return {
+      code: 'unknown_stored_query',
+      name: stored_query_name,
+    };
+  }
+
+  return {
+    code: 'unknown_stored_query',
+    name: stored_query_name,
+    suggestion,
+  };
+}