patram 0.10.0 → 0.11.0

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

@@ -47,6 +47,7 @@ export type CliParseError = {
 } | {
     code: 'unknown_stored_query';
     name: string;
+    next_path?: string;
     suggestion?: string;
 } | {
     code: 'unknown_option';

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/help-metadata.js

@@ -87,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: [
       {
@@ -110,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(),
@@ -221,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',
@@ -242,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']),