patram 0.9.0 → 0.11.0

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';

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

@@ -0,0 +1,262 @@
+/**
+ * @import {
+ *   PatramDiagnostic,
+ *   StoredQueryConfig,
+ * } from './load-patram-config.types.ts';
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+
+import { parsePatramConfigSource } from './load-patram-config.js';
+import { applyStoredQueryMutationToConfigSource } from './manage-stored-queries-jsonc.js';
+import { CONFIG_FILE_NAME } from './schema.js';
+import { validatePatramConfigValue } from './validate-patram-config-value.js';
+
+/**
+ * @param {string} config_file_path
+ * @returns {Promise<
+ *   | { success: true, value: Record<string, unknown> }
+ *   | { diagnostic: PatramDiagnostic, success: false }
+ * >}
+ */
+export async function loadRawConfig(config_file_path) {
+  const config_source = await readConfigSource(config_file_path);
+
+  if (config_source === null) {
+    return {
+      success: true,
+      value: {},
+    };
+  }
+
+  const parse_result = parsePatramConfigSource(config_source);
+
+  if (!parse_result.success) {
+    return parse_result;
+  }
+
+  if (
+    parse_result.value === null ||
+    typeof parse_result.value !== 'object' ||
+    Array.isArray(parse_result.value)
+  ) {
+    return {
+      diagnostic: createInvalidTopLevelConfigDiagnostic(),
+      success: false,
+    };
+  }
+
+  return {
+    success: true,
+    value: /** @type {Record<string, unknown>} */ (parse_result.value),
+  };
+}
+
+/**
+ * @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 async function persistStoredQueryMutation(
+  config_file_path,
+  raw_config,
+  mutation_result,
+) {
+  const validation_result = validatePatramConfigValue(raw_config);
+
+  if (!validation_result.success) {
+    return {
+      diagnostics: validation_result.diagnostics,
+      success: false,
+    };
+  }
+
+  const config_source = (await readConfigSource(config_file_path)) ?? '{}\n';
+  const raw_queries = ensureRawQueries(raw_config);
+  const next_config_source = applyStoredQueryMutationToConfigSource(
+    config_source,
+    raw_queries,
+    mutation_result,
+  );
+
+  await writeFile(config_file_path, next_config_source);
+
+  return {
+    success: true,
+    value: mutation_result,
+  };
+}
+
+/**
+ * @param {string} where_clause
+ * @param {string | undefined} description
+ * @returns {StoredQueryConfig}
+ */
+export function createStoredQueryDefinition(where_clause, description) {
+  /** @type {StoredQueryConfig} */
+  const stored_query = {
+    where: where_clause,
+  };
+  const normalized_description = normalizeDescription(description);
+
+  if (normalized_description !== undefined) {
+    stored_query.description = normalized_description;
+  }
+
+  return stored_query;
+}
+
+/**
+ * @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,
+  existing_query,
+  stored_query_mutation,
+) {
+  /** @type {StoredQueryConfig} */
+  const next_query = {
+    where: existing_query.where,
+  };
+
+  if (
+    raw_query_value &&
+    Object.hasOwn(raw_query_value, 'description') &&
+    typeof raw_query_value.description === 'string' &&
+    raw_query_value.description.length > 0
+  ) {
+    next_query.description = raw_query_value.description;
+  } else if (
+    typeof existing_query.description === 'string' &&
+    existing_query.description.length > 0
+  ) {
+    next_query.description = existing_query.description;
+  }
+
+  if (stored_query_mutation.where !== undefined) {
+    next_query.where = stored_query_mutation.where;
+  }
+
+  if (stored_query_mutation.description !== undefined) {
+    if (stored_query_mutation.description.length === 0) {
+      delete next_query.description;
+    } else {
+      next_query.description = stored_query_mutation.description;
+    }
+  }
+
+  return next_query;
+}
+
+/**
+ * @param {Record<string, unknown>} raw_config
+ * @returns {Record<string, unknown>}
+ */
+export function ensureRawQueries(raw_config) {
+  const raw_queries_value = raw_config.queries;
+
+  if (
+    raw_queries_value !== null &&
+    typeof raw_queries_value === 'object' &&
+    !Array.isArray(raw_queries_value)
+  ) {
+    return /** @type {Record<string, unknown>} */ (raw_queries_value);
+  }
+
+  /** @type {Record<string, unknown>} */
+  const raw_queries = {};
+  raw_config.queries = raw_queries;
+
+  return raw_queries;
+}
+
+/**
+ * @param {unknown} raw_query_value
+ * @returns {Record<string, unknown> | null}
+ */
+export function rawQueryValueToRecord(raw_query_value) {
+  if (
+    raw_query_value === null ||
+    typeof raw_query_value !== 'object' ||
+    Array.isArray(raw_query_value)
+  ) {
+    return null;
+  }
+
+  return /** @type {Record<string, unknown>} */ (raw_query_value);
+}
+
+/**
+ * @param {string | undefined} description
+ * @returns {string | undefined}
+ */
+function normalizeDescription(description) {
+  if (description === undefined || description.length === 0) {
+    return undefined;
+  }
+
+  return description;
+}
+
+/**
+ * @returns {PatramDiagnostic}
+ */
+function createInvalidTopLevelConfigDiagnostic() {
+  return {
+    code: 'config.invalid',
+    column: 1,
+    level: 'error',
+    line: 1,
+    message: 'Invalid config: Expected a top-level object.',
+    path: CONFIG_FILE_NAME,
+  };
+}
+
+/**
+ * @param {string} config_file_path
+ * @returns {Promise<string | null>}
+ */
+async function readConfigSource(config_file_path) {
+  try {
+    return await readFile(config_file_path, 'utf8');
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return null;
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * @param {unknown} error
+ * @returns {error is NodeJS.ErrnoException}
+ */
+function isMissingFileError(error) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  return 'code' in error && error.code === 'ENOENT';
+}
+
+/**
+ * @typedef {{
+ *   action: 'added',
+ *   name: string,
+ * } | {
+ *   action: 'removed',
+ *   name: string,
+ * } | {
+ *   action: 'updated',
+ *   name: string,
+ *   previous_name?: string,
+ * }} StoredQueryMutationResult
+ */

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

@@ -0,0 +1,31 @@
+/**
+ * @typedef {{
+ *   action: 'added',
+ *   name: string,
+ * } | {
+ *   action: 'removed',
+ *   name: string,
+ * } | {
+ *   action: 'updated',
+ *   name: string,
+ *   previous_name?: string,
+ * }} StoredQueryMutationResult
+ */
+/**
+ * @param {string} config_source
+ * @param {Record<string, unknown>} raw_queries
+ * @param {StoredQueryMutationResult} mutation_result
+ * @returns {string}
+ */
+export function applyStoredQueryMutationToConfigSource(config_source: string, raw_queries: Record<string, unknown>, mutation_result: StoredQueryMutationResult): string;
+export type StoredQueryMutationResult = {
+    action: "added";
+    name: string;
+} | {
+    action: "removed";
+    name: string;
+} | {
+    action: "updated";
+    name: string;
+    previous_name?: string;
+};

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

@@ -0,0 +1,95 @@
+/**
+ * @import { FormattingOptions } from 'jsonc-parser';
+ */
+
+import { applyEdits, modify } from 'jsonc-parser';
+
+/**
+ * @typedef {{
+ *   action: 'added',
+ *   name: string,
+ * } | {
+ *   action: 'removed',
+ *   name: string,
+ * } | {
+ *   action: 'updated',
+ *   name: string,
+ *   previous_name?: string,
+ * }} StoredQueryMutationResult
+ */
+
+/**
+ * @param {string} config_source
+ * @param {Record<string, unknown>} raw_queries
+ * @param {StoredQueryMutationResult} mutation_result
+ * @returns {string}
+ */
+export function applyStoredQueryMutationToConfigSource(
+  config_source,
+  raw_queries,
+  mutation_result,
+) {
+  const formatting_options = inferFormattingOptions(config_source);
+  let next_config_source = config_source;
+
+  if (
+    mutation_result.action === 'updated' &&
+    mutation_result.previous_name !== undefined
+  ) {
+    next_config_source = applyConfigEdit(
+      next_config_source,
+      ['queries', mutation_result.previous_name],
+      undefined,
+      formatting_options,
+    );
+  }
+
+  if (mutation_result.action === 'removed') {
+    return applyConfigEdit(
+      next_config_source,
+      ['queries', mutation_result.name],
+      undefined,
+      formatting_options,
+    );
+  }
+
+  return applyConfigEdit(
+    next_config_source,
+    ['queries', mutation_result.name],
+    raw_queries[mutation_result.name],
+    formatting_options,
+  );
+}
+
+/**
+ * @param {string} config_source
+ * @returns {FormattingOptions}
+ */
+function inferFormattingOptions(config_source) {
+  const indentation_match = config_source.match(/^(?<indentation>[ \t]+)\S/mu);
+  const indentation = indentation_match?.groups?.indentation ?? '  ';
+  const insert_spaces = !indentation.includes('\t');
+
+  return {
+    eol: config_source.includes('\r\n') ? '\r\n' : '\n',
+    insertFinalNewline: config_source.endsWith('\n'),
+    insertSpaces: insert_spaces,
+    tabSize: insert_spaces ? indentation.length : 1,
+  };
+}
+
+/**
+ * @param {string} config_source
+ * @param {(string | number)[]} path
+ * @param {unknown} value
+ * @param {FormattingOptions} formatting_options
+ * @returns {string}
+ */
+function applyConfigEdit(config_source, path, value, formatting_options) {
+  return applyEdits(
+    config_source,
+    modify(config_source, path, value, {
+      formattingOptions: formatting_options,
+    }),
+  );
+}

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

@@ -0,0 +1,77 @@
+/**
+ * @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 function manageStoredQueries(project_directory: string, stored_query_mutation: StoredQueryMutation): Promise<{
+    success: true;
+    value: StoredQueryMutationResult;
+} | {
+    diagnostics: PatramDiagnostic[];
+    success: false;
+} | {
+    error: CliParseError;
+    success: false;
+}>;
+export type StoredQueryMutation = {
+    action: "add";
+    description?: string;
+    name: string;
+    where: string;
+} | {
+    action: "remove";
+    name: string;
+} | {
+    action: "update";
+    description?: string;
+    name: string;
+    next_name?: string;
+    where?: string;
+};
+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 { CliParseError } from '../cli/arguments.types.d.ts';