patram 0.9.0 → 0.11.0

package/lib/cli/arguments.types.d.ts

@@ -0,0 +1,64 @@
+export type CliCommandName = 'check' | 'fields' | 'query' | 'queries' | 'refs' | 'show';
+export type CliHelpTopicName = 'query-language';
+export type CliHelpTargetKind = 'root' | 'command' | 'topic';
+export type CliUnexpectedArgumentCommandName = CliCommandName | 'help';
+export type CliOutputMode = 'default' | 'plain' | 'json';
+export type CliColorMode = 'auto' | 'always' | 'never';
+export interface ParsedCliCommandRequest {
+    kind?: 'command';
+    color_mode: CliColorMode;
+    command_arguments: string[];
+    command_name: CliCommandName;
+    output_mode: CliOutputMode;
+    query_inspection_mode?: 'explain' | 'lint';
+    query_limit?: number;
+    query_offset?: number;
+}
+export interface ParsedCliHelpRequest {
+    kind: 'help';
+    target_kind: CliHelpTargetKind;
+    target_name?: CliCommandName | CliHelpTopicName;
+}
+export type ParsedCliArguments = ParsedCliCommandRequest;
+export type ParsedCliRequest = ParsedCliCommandRequest | ParsedCliHelpRequest;
+export type CliParseError = {
+    code: 'message';
+    message: string;
+} | {
+    code: 'missing_required_argument';
+    argument_label: string;
+    command_name: 'query' | 'refs' | 'show';
+} | {
+    code: 'unexpected_argument';
+    command_name: CliUnexpectedArgumentCommandName;
+    token: string;
+} | {
+    code: 'option_not_valid_for_command';
+    command_name: CliCommandName;
+    token: string;
+} | {
+    code: 'unknown_command';
+    suggestion?: CliCommandName;
+    token: string;
+} | {
+    code: 'unknown_help_target';
+    suggestion?: CliCommandName | CliHelpTopicName;
+    token: string;
+} | {
+    code: 'unknown_stored_query';
+    name: string;
+    next_path?: string;
+    suggestion?: string;
+} | {
+    code: 'unknown_option';
+    command_name?: CliCommandName;
+    suggestion?: string;
+    token: string;
+};
+export type ParseCliArgumentsResult = {
+    success: true;
+    value: ParsedCliRequest;
+} | {
+    error: CliParseError;
+    success: false;
+};

package/lib/cli/commands/check.js

@@ -9,13 +9,15 @@ import {
   renderCheckSuccess,
 } from '../../output/render-check-output.js';
 import {
-  resolveCheckTarget,
-  selectCheckTargetDiagnostics,
-  selectCheckTargetSourceFiles,
+  resolveCheckTargetProjectDirectory,
+  resolveCheckTargets,
+  selectCheckTargetsDiagnostics,
+  selectCheckTargetsSourceFiles,
 } from '../../output/resolve-check-target.js';
 import { listRepoFiles } from '../../scan/list-repo-files.js';
 
 import { resolveCommandOutputMode } from '../command-helpers.js';
+import { renderCliParseError } from '../render-help.js';
 
 /**
  * @param {ParsedCliCommandRequest} parsed_command
@@ -24,18 +26,28 @@ import { resolveCommandOutputMode } from '../command-helpers.js';
  */
 export async function runCheckCommand(parsed_command, io_context) {
   const output_mode = resolveCommandOutputMode(parsed_command, io_context);
-  const resolved_target = await resolveCheckTarget(
-    parsed_command.command_arguments[0],
+  const resolved_targets = await resolveCheckTargets(
+    parsed_command.command_arguments,
   );
-  const project_graph_result = await loadProjectGraph(
-    resolved_target.project_directory,
-  );
-  const repo_file_paths = await listRepoFiles(
-    resolved_target.project_directory,
-  );
-  const selected_source_file_paths = selectCheckTargetSourceFiles(
+  const project_directory =
+    resolveCheckTargetProjectDirectory(resolved_targets);
+
+  if (!project_directory) {
+    io_context.stderr.write(
+      renderCliParseError({
+        code: 'message',
+        message: 'Check paths must resolve to the same project root.',
+      }),
+    );
+
+    return 1;
+  }
+
+  const project_graph_result = await loadProjectGraph(project_directory);
+  const repo_file_paths = await listRepoFiles(project_directory);
+  const selected_source_file_paths = selectCheckTargetsSourceFiles(
     project_graph_result.source_file_paths,
-    resolved_target,
+    resolved_targets,
   );
 
   if (project_graph_result.diagnostics.length > 0) {
@@ -52,9 +64,9 @@ export async function runCheckCommand(parsed_command, io_context) {
     project_graph_result.config,
     project_graph_result.claims,
   );
-  const selected_diagnostics = selectCheckTargetDiagnostics(
+  const selected_diagnostics = selectCheckTargetsDiagnostics(
     diagnostics,
-    resolved_target,
+    resolved_targets,
   );
 
   if (selected_diagnostics.length > 0) {

package/lib/cli/commands/queries.js

@@ -4,12 +4,18 @@
 
 import process from 'node:process';
 
+import { manageStoredQueries } from '../../config/manage-stored-queries.js';
 import { loadPatramConfig } from '../../config/load-patram-config.js';
+import { renderCheckDiagnostics } from '../../output/render-check-output.js';
 import { writeCommandOutput } from '../../output/command-output.js';
 import { listQueries } from '../../output/list-queries.js';
 import { createOutputView } from '../../output/render-output-view.js';
+import { renderCliParseError } from '../render-help.js';
 
-import { writeDiagnostics } from '../command-helpers.js';
+import {
+  resolveCommandOutputMode,
+  writeDiagnostics,
+} from '../command-helpers.js';
 
 /**
  * @param {ParsedCliCommandRequest} parsed_command
@@ -17,6 +23,10 @@ import { writeDiagnostics } from '../command-helpers.js';
  * @returns {Promise<number>}
  */
 export async function runQueriesCommand(parsed_command, io_context) {
+  if (parsed_command.command_arguments.length > 0) {
+    return runQueriesMutationCommand(parsed_command, io_context);
+  }
+
   const load_result = await loadPatramConfig(process.cwd());
 
   if (load_result.diagnostics.length > 0) {
@@ -39,3 +49,181 @@ export async function runQueriesCommand(parsed_command, io_context) {
 
   return 0;
 }
+
+/**
+ * @param {ParsedCliCommandRequest} parsed_command
+ * @param {{ stderr: { write(chunk: string): boolean }, stdout: { isTTY?: boolean, write(chunk: string): boolean } }} io_context
+ * @returns {Promise<number>}
+ */
+async function runQueriesMutationCommand(parsed_command, io_context) {
+  const mutation_request = parseStoredQueryMutation(
+    parsed_command.command_arguments,
+  );
+  const output_mode = resolveCommandOutputMode(parsed_command, io_context);
+
+  if (!mutation_request.success) {
+    io_context.stderr.write(renderCliParseError(mutation_request.error));
+
+    return 1;
+  }
+
+  const mutation_result = await manageStoredQueries(
+    process.cwd(),
+    mutation_request.value,
+  );
+
+  if (!mutation_result.success) {
+    if ('error' in mutation_result) {
+      io_context.stderr.write(renderCliParseError(mutation_result.error));
+
+      return 1;
+    }
+
+    io_context.stderr.write(
+      renderCheckDiagnostics(mutation_result.diagnostics, output_mode),
+    );
+
+    return 1;
+  }
+
+  io_context.stdout.write(
+    renderStoredQueryMutationResult(
+      mutation_result.value,
+      parsed_command.output_mode,
+    ),
+  );
+
+  return 0;
+}
+
+/**
+ * @param {string[]} command_arguments
+ * @returns {{
+ *   success: true,
+ *   value:
+ *     | { action: 'add', description?: string, name: string, where: string }
+ *     | { action: 'remove', name: string }
+ *     | {
+ *         action: 'update',
+ *         description?: string,
+ *         name: string,
+ *         next_name?: string,
+ *         where?: string,
+ *       },
+ * } | { error: import('../arguments.types.ts').CliParseError, success: false }}
+ */
+function parseStoredQueryMutation(command_arguments) {
+  const subcommand_name = command_arguments[0];
+
+  if (subcommand_name === 'add') {
+    return {
+      success: true,
+      value: {
+        action: 'add',
+        description: readOptionValue(command_arguments, '--desc'),
+        name: command_arguments[1],
+        where: readRequiredOptionValue(command_arguments, '--query'),
+      },
+    };
+  }
+
+  if (subcommand_name === 'remove') {
+    return {
+      success: true,
+      value: {
+        action: 'remove',
+        name: command_arguments[1],
+      },
+    };
+  }
+
+  if (subcommand_name === 'update') {
+    return {
+      success: true,
+      value: {
+        action: 'update',
+        description: readOptionValue(command_arguments, '--desc'),
+        name: command_arguments[1],
+        next_name: readOptionValue(command_arguments, '--name'),
+        where: readOptionValue(command_arguments, '--query'),
+      },
+    };
+  }
+
+  return {
+    error: {
+      code: 'unexpected_argument',
+      command_name: 'queries',
+      token: subcommand_name ?? '',
+    },
+    success: false,
+  };
+}
+
+/**
+ * @param {{
+ *   action: 'added',
+ *   name: string,
+ * } | {
+ *   action: 'removed',
+ *   name: string,
+ * } | {
+ *   action: 'updated',
+ *   name: string,
+ *   previous_name?: string,
+ * }} mutation_result
+ * @param {ParsedCliCommandRequest['output_mode']} output_mode
+ * @returns {string}
+ */
+function renderStoredQueryMutationResult(mutation_result, output_mode) {
+  if (output_mode === 'json') {
+    return `${JSON.stringify(mutation_result, null, 2)}\n`;
+  }
+
+  if (
+    mutation_result.action === 'updated' &&
+    mutation_result.previous_name !== undefined
+  ) {
+    return `Updated stored query: ${mutation_result.previous_name} -> ${mutation_result.name}\n`;
+  }
+
+  if (mutation_result.action === 'updated') {
+    return `Updated stored query: ${mutation_result.name}\n`;
+  }
+
+  if (mutation_result.action === 'added') {
+    return `Added stored query: ${mutation_result.name}\n`;
+  }
+
+  return `Removed stored query: ${mutation_result.name}\n`;
+}
+
+/**
+ * @param {string[]} command_arguments
+ * @param {'--desc' | '--name' | '--query'} option_name
+ * @returns {string}
+ */
+function readRequiredOptionValue(command_arguments, option_name) {
+  const option_value = readOptionValue(command_arguments, option_name);
+
+  if (option_value === undefined) {
+    throw new Error(`Expected ${option_name} to be present.`);
+  }
+
+  return option_value;
+}
+
+/**
+ * @param {string[]} command_arguments
+ * @param {'--desc' | '--name' | '--query'} option_name
+ * @returns {string | undefined}
+ */
+function readOptionValue(command_arguments, option_name) {
+  const option_index = command_arguments.indexOf(option_name);
+
+  if (option_index < 0) {
+    return undefined;
+  }
+
+  return command_arguments[option_index + 1];
+}

package/lib/cli/commands/query.js

@@ -12,7 +12,10 @@ import {
 } from '../../output/command-output.js';
 import { createDerivedSummaryEvaluator } from '../../output/derived-summary.js';
 import { renderCheckDiagnostics } from '../../output/render-check-output.js';
-import { renderInvalidWhereDiagnostic } from '../render-help.js';
+import {
+  renderCliParseError,
+  renderInvalidWhereDiagnostic,
+} from '../render-help.js';
 import { createOutputView } from '../../output/render-output-view.js';
 import { loadPatramConfig } from '../../config/load-patram-config.js';
 import { loadProjectGraph } from '../../graph/load-project-graph.js';
@@ -60,7 +63,7 @@ export async function runQueryCommand(parsed_command, io_context) {
   );
 
   if (!where_clause.success) {
-    io_context.stderr.write(`${where_clause.message}\n`);
+    io_context.stderr.write(renderCliParseError(where_clause.error));
 
     return 1;
   }
@@ -139,7 +142,7 @@ async function runQueryInspectionCommand(
   );
 
   if (!where_clause.success) {
-    io_context.stderr.write(`${where_clause.message}\n`);
+    io_context.stderr.write(renderCliParseError(where_clause.error));
 
     return 1;
   }

package/lib/cli/help-metadata.js

@@ -6,6 +6,8 @@
  * } from './arguments.types.ts';
  */
 
+import { findCloseMatch } from '../find-close-match.js';
+
 /**
  * @typedef {{
  *   description: string,
@@ -85,14 +87,15 @@ const COMMAND_DEFINITIONS = {
       'patram check',
       'patram check docs',
       'patram check docs/patram.md',
+      'patram check docs docs/patram.md',
     ],
-    extra_positionals_message: 'Check accepts at most one path.',
+    extra_positionals_message: 'Check accepts zero or more paths.',
     help_topics: [],
-    max_positionals: 1,
+    max_positionals: Number.POSITIVE_INFINITY,
     min_positionals: 0,
     missing_argument_examples: [],
     missing_argument_label: null,
-    missing_usage_lines: ['patram check [path]'],
+    missing_usage_lines: ['patram check [path ...]'],
     option_column_width: 10,
     options: [
       {
@@ -108,7 +111,7 @@ const COMMAND_DEFINITIONS = {
     root_summary: 'Validate a project, directory, or file',
     summary:
       'Validate a project, directory, or file and report graph diagnostics.',
-    usage_lines: ['patram check [path] [options]'],
+    usage_lines: ['patram check [path ...] [options]'],
   },
   fields: {
     allowed_option_names: new Set(),
@@ -219,17 +222,40 @@ const COMMAND_DEFINITIONS = {
     ],
   },
   queries: {
-    allowed_option_names: new Set(),
-    examples: ['patram queries'],
-    extra_positionals_message: 'Queries does not accept positional arguments.',
+    allowed_option_names: new Set(['desc', 'name', 'query']),
+    examples: [
+      'patram queries',
+      "patram queries add ready-tasks --query '$class=task and status=ready'",
+      "patram queries update ready-tasks --desc 'Show tasks that are ready.'",
+      'patram queries remove ready-tasks',
+    ],
+    extra_positionals_message:
+      'Queries accepts no positionals unless using add, update, or remove.',
     help_topics: [],
-    max_positionals: 0,
+    max_positionals: 2,
     min_positionals: 0,
     missing_argument_examples: [],
     missing_argument_label: null,
-    missing_usage_lines: ['patram queries'],
-    option_column_width: 10,
+    missing_usage_lines: [
+      'patram queries',
+      'patram queries add <name> --query <clause>',
+      'patram queries update <name> [--name <new_name>] [--query <clause>] [--desc <text>]',
+      'patram queries remove <name>',
+    ],
+    option_column_width: 19,
     options: [
+      {
+        description: 'Persist a new stored query',
+        label: '--query <clause>',
+      },
+      {
+        description: 'Set or rename the stored query name for update',
+        label: '--name <new_name>',
+      },
+      {
+        description: 'Set or clear the stored query description',
+        label: '--desc <text>',
+      },
       {
         description: 'Print plain text output',
         label: '--plain',
@@ -240,9 +266,15 @@ const COMMAND_DEFINITIONS = {
       },
     ],
     related: ['query'],
-    root_summary: 'List stored queries',
-    summary: 'List the stored queries defined in the project configuration.',
-    usage_lines: ['patram queries [options]'],
+    root_summary: 'List and manage stored queries',
+    summary:
+      'List stored queries or mutate them through add, update, and remove.',
+    usage_lines: [
+      'patram queries [options]',
+      'patram queries add <name> --query <clause> [--desc <text>] [options]',
+      'patram queries update <name> [--name <new_name>] [--query <clause>] [--desc <text>] [options]',
+      'patram queries remove <name> [options]',
+    ],
   },
   refs: {
     allowed_option_names: new Set(['where']),
@@ -532,100 +564,3 @@ function listOptionLabels(command_name) {
 
   return [...option_labels];
 }
-
-/**
- * @param {string} input_text
- * @param {readonly string[]} candidates
- * @returns {string | undefined}
- */
-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] + 1,
-        );
-      }
-    }
-  }
-
-  return matrix[left_text.length][right_text.length];
-}