patram 0.10.0 → 0.12.0

package/bin/patram.js

@@ -12,10 +12,10 @@ import { main } from '../lib/cli/main.js';
  * Detects direct process execution and forwards command handling to the shared
  * CLI runtime.
  *
- * Kind: entrypoint
- * Status: active
- * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../docs/decisions/cli-entrypoint-symlink.md
+ * kind: entrypoint
+ * status: active
+ * tracked_in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * decided_by: ../docs/decisions/cli-entrypoint-symlink.md
  * @patram
  * @see {@link ../lib/cli/main.js}
  * @see {@link ../docs/patram.md}

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/fields.js

@@ -49,9 +49,5 @@ function collectDefinedDiscoveryNames(repo_config) {
     defined_field_names.add(field_name);
   }
 
-  for (const relation_name of Object.keys(repo_config?.relations ?? {})) {
-    defined_field_names.add(relation_name);
-  }
-
   return defined_field_names;
 }

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,171 @@ 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',
+ *         cypher?: string,
+ *         description?: string,
+ *         name: string,
+ *       }
+ *     | { action: 'remove', name: string }
+ *     | {
+ *         action: 'update',
+ *         cypher?: string,
+ *         description?: string,
+ *         name: string,
+ *         next_name?: 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',
+        cypher: readOptionValue(command_arguments, '--cypher'),
+        description: readOptionValue(command_arguments, '--desc'),
+        name: command_arguments[1],
+      },
+    };
+  }
+
+  if (subcommand_name === 'remove') {
+    return {
+      success: true,
+      value: {
+        action: 'remove',
+        name: command_arguments[1],
+      },
+    };
+  }
+
+  if (subcommand_name === 'update') {
+    return {
+      success: true,
+      value: {
+        action: 'update',
+        cypher: readOptionValue(command_arguments, '--cypher'),
+        description: readOptionValue(command_arguments, '--desc'),
+        name: command_arguments[1],
+        next_name: readOptionValue(command_arguments, '--name'),
+      },
+    };
+  }
+
+  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 {'--cypher' | '--desc' | '--name'} 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

@@ -10,7 +10,6 @@ import {
   shouldPageCommandOutput,
   writeCommandOutput,
 } from '../../output/command-output.js';
-import { createDerivedSummaryEvaluator } from '../../output/derived-summary.js';
 import { renderCheckDiagnostics } from '../../output/render-check-output.js';
 import {
   renderCliParseError,
@@ -83,16 +82,10 @@ export async function runQueryCommand(parsed_command, io_context) {
     return 1;
   }
 
-  const derived_summary_evaluator = createDerivedSummaryEvaluator(
-    project_graph_result.config,
-    project_graph_result.graph,
-  );
-
   await writeCommandOutput(
     io_context,
     parsed_command,
     createOutputView('query', query_result.nodes, {
-      derived_summary_evaluator,
       ...createQueryOutputOptions(parsed_command, query_result, use_pager),
       repo_config: project_graph_result.config,
     }),
@@ -182,7 +175,7 @@ function createQueryOutputOptions(parsed_command, query_result, use_pager) {
   const offset = parsed_command.query_offset ?? 0;
 
   if (query_result.total_count === 0) {
-    hints.push("Try: patram query --where '$class=task'");
+    hints.push('Try: patram query --cypher "MATCH (n:Task) RETURN n"');
   }
 
   if (

package/lib/cli/commands/refs.js

@@ -7,7 +7,6 @@ import process from 'node:process';
 import { loadProjectGraph } from '../../graph/load-project-graph.js';
 import { inspectReverseReferences } from '../../graph/inspect-reverse-references.js';
 import { writeCommandOutput } from '../../output/command-output.js';
-import { createDerivedSummaryEvaluator } from '../../output/derived-summary.js';
 import { createRefsOutputView } from '../../output/render-output-view.js';
 
 import { renderInvalidWhereDiagnostic } from '../render-help.js';
@@ -31,7 +30,7 @@ export async function runRefsCommand(parsed_command, io_context) {
     project_graph_result.graph,
     parsed_command.command_arguments[0],
     project_graph_result.config,
-    resolveRefsWhereClause(parsed_command.command_arguments),
+    resolveRefsCypherQuery(parsed_command.command_arguments),
   );
 
   if (refs_output.diagnostics.length > 0) {
@@ -42,16 +41,10 @@ export async function runRefsCommand(parsed_command, io_context) {
     return 1;
   }
 
-  const derived_summary_evaluator = createDerivedSummaryEvaluator(
-    project_graph_result.config,
-    project_graph_result.graph,
-  );
-
   await writeCommandOutput(
     io_context,
     parsed_command,
     createRefsOutputView(refs_output, {
-      derived_summary_evaluator,
       repo_config: project_graph_result.config,
     }),
   );
@@ -63,8 +56,8 @@ export async function runRefsCommand(parsed_command, io_context) {
  * @param {string[]} command_arguments
  * @returns {string | undefined}
  */
-function resolveRefsWhereClause(command_arguments) {
-  if (command_arguments[1] !== '--where') {
+function resolveRefsCypherQuery(command_arguments) {
+  if (command_arguments[1] !== '--cypher') {
     return undefined;
   }
 

package/lib/cli/commands/show.js

@@ -6,7 +6,6 @@ import process from 'node:process';
 
 import { loadProjectGraph } from '../../graph/load-project-graph.js';
 import { writeCommandOutput } from '../../output/command-output.js';
-import { createDerivedSummaryEvaluator } from '../../output/derived-summary.js';
 import { createShowOutputView } from '../../output/render-output-view.js';
 import { loadShowOutput } from '../../output/show-document.js';
 
@@ -38,17 +37,11 @@ export async function runShowCommand(parsed_command, io_context) {
     return 1;
   }
 
-  const derived_summary_evaluator = createDerivedSummaryEvaluator(
-    project_graph_result.config,
-    project_graph_result.graph,
-  );
-
   await writeCommandOutput(
     io_context,
     parsed_command,
     createShowOutputView(show_output.value, {
-      derived_summary_evaluator,
-      document_node_ids: project_graph_result.graph.document_node_ids,
+      document_path_ids: project_graph_result.graph.document_path_ids,
       graph_nodes: project_graph_result.graph.nodes,
       repo_config: project_graph_result.config,
     }),