patram 0.11.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/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

@@ -101,14 +101,19 @@ async function runQueriesMutationCommand(parsed_command, io_context) {
  * @returns {{
  *   success: true,
  *   value:
- *     | { action: 'add', description?: string, name: string, where: string }
+ *     | {
+ *         action: 'add',
+ *         cypher?: string,
+ *         description?: string,
+ *         name: string,
+ *       }
  *     | { action: 'remove', name: string }
  *     | {
  *         action: 'update',
+ *         cypher?: string,
  *         description?: string,
  *         name: string,
  *         next_name?: string,
- *         where?: string,
  *       },
  * } | { error: import('../arguments.types.ts').CliParseError, success: false }}
  */
@@ -120,9 +125,9 @@ function parseStoredQueryMutation(command_arguments) {
       success: true,
       value: {
         action: 'add',
+        cypher: readOptionValue(command_arguments, '--cypher'),
         description: readOptionValue(command_arguments, '--desc'),
         name: command_arguments[1],
-        where: readRequiredOptionValue(command_arguments, '--query'),
       },
     };
   }
@@ -142,10 +147,10 @@ function parseStoredQueryMutation(command_arguments) {
       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'),
-        where: readOptionValue(command_arguments, '--query'),
       },
     };
   }
@@ -200,22 +205,7 @@ function renderStoredQueryMutationResult(mutation_result, output_mode) {
 
 /**
  * @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
+ * @param {'--cypher' | '--desc' | '--name'} option_name
  * @returns {string | undefined}
  */
 function readOptionValue(command_arguments, option_name) {

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,
     }),

package/lib/cli/help-metadata.js

@@ -142,41 +142,42 @@ const COMMAND_DEFINITIONS = {
   },
   query: {
     allowed_option_names: new Set([
+      'cypher',
       'explain',
       'limit',
       'lint',
       'offset',
-      'where',
     ]),
     examples: [
       'patram query active-plans',
-      "patram query --where 'tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md'",
-      "patram query --where 'status not in [done, dropped, superseded]'",
-      "patram query --where '$class=plan and none(in:tracked_in, $class=decision)'",
-      "patram query --where 'count(in:decided_by, $class=task) = 0'",
+      'patram query --cypher "MATCH (n:Plan) WHERE n.status = \'active\' RETURN n"',
+      'patram query --cypher "MATCH (n) WHERE id(n) = \'plan:v0/worktracking-agent-guidance\' RETURN n"',
+      "patram query --cypher \"MATCH (n) WHERE n.status NOT IN ['done', 'dropped', 'superseded'] RETURN n\"",
+      'patram query --cypher "MATCH (n:Plan) WHERE NOT EXISTS { MATCH (decision:Decision)-[:TRACKED_IN]->(n) } RETURN n"',
+      'patram query --cypher "MATCH (n:Decision) WHERE COUNT { MATCH (task:Task)-[:DECIDED_BY]->(n) } = 0 RETURN n"',
       'patram query ready-tasks --explain',
-      "patram query --where '$class=decision and status=accepted and count(in:decided_by, $class=task) = 0' --lint",
+      'patram query --cypher "MATCH (n:Decision) WHERE n.status = \'accepted\' AND COUNT { MATCH (task:Task)-[:DECIDED_BY]->(n) } = 0 RETURN n" --lint',
       'patram query active-plans --limit 10 --offset 20',
     ],
     extra_positionals_message:
-      'Query accepts either "--where" or a stored query name.',
+      'Query accepts "--cypher" or a stored query name.',
     help_topics: ['query-language'],
     max_positionals: 1,
     min_positionals: 0,
     missing_argument_examples: [
       'patram query active-plans',
-      "patram query --where 'tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md'",
+      'patram query --cypher "MATCH (n:Plan) WHERE n.status = \'active\' RETURN n"',
     ],
-    missing_argument_label: "<name> or --where '<clause>'",
+    missing_argument_label: "<name> or --cypher '<query>'",
     missing_usage_lines: [
       'patram query <name> [options]',
-      "patram query --where '<clause>' [options]",
+      `patram query --cypher '<query>' [options]`,
     ],
     option_column_width: 19,
     options: [
       {
-        description: 'Run an ad hoc query instead of a stored query',
-        label: '--where <clause>',
+        description: 'Run an ad hoc Cypher query instead of a stored query',
+        label: '--cypher <query>',
       },
       {
         description: 'Skip the first N matches',
@@ -204,29 +205,28 @@ const COMMAND_DEFINITIONS = {
       },
     ],
     related: ['queries', 'show'],
-    root_summary: 'Run a stored query or an ad hoc where clause',
+    root_summary: 'Run a stored query or an ad hoc Cypher query',
     summary:
-      'Run a stored query or an ad hoc where clause against graph nodes.',
+      'Run a stored query or an ad hoc Cypher query against graph nodes.',
     syntax_lines: [
-      '$id=<value> | $class=<value> | $path=<value> | status=<value>',
-      '$id^=<prefix> | $path^=<prefix> | title~<text>',
-      '<field> in [<value>, ...] | <field> not in [<value>, ...]',
-      '<relation>:* | <relation>=<target-id>',
-      'any(<traversal>, <term> and <term>)',
-      'none(<traversal>, <term> and <term>)',
-      'count(<traversal>, <term> and <term>) <comparison> <number>',
+      'MATCH (n) RETURN n',
+      "MATCH (n:Label) WHERE n.status = 'active' RETURN n",
+      "MATCH (n) WHERE id(n) = 'command:query' RETURN n",
+      'MATCH (n) WHERE EXISTS { MATCH ... } RETURN n',
+      'MATCH (n) WHERE COUNT { MATCH ... } = 0 RETURN n',
     ],
     usage_lines: [
       'patram query <name> [options]',
-      "patram query --where '<clause>' [options]",
+      `patram query --cypher '<query>' [options]`,
     ],
   },
   queries: {
-    allowed_option_names: new Set(['desc', 'name', 'query']),
+    allowed_option_names: new Set(['cypher', 'desc', 'name']),
     examples: [
       'patram queries',
-      "patram queries add ready-tasks --query '$class=task and status=ready'",
+      `patram queries add active-plans --cypher "MATCH (n:Plan) WHERE n.status = 'active' RETURN n"`,
       "patram queries update ready-tasks --desc 'Show tasks that are ready.'",
+      `patram queries update ready-tasks --cypher "MATCH (n:Task) WHERE n.status = 'ready' RETURN n"`,
       'patram queries remove ready-tasks',
     ],
     extra_positionals_message:
@@ -238,15 +238,15 @@ const COMMAND_DEFINITIONS = {
     missing_argument_label: null,
     missing_usage_lines: [
       'patram queries',
-      'patram queries add <name> --query <clause>',
-      'patram queries update <name> [--name <new_name>] [--query <clause>] [--desc <text>]',
+      'patram queries add <name> --cypher <query>',
+      'patram queries update <name> [--name <new_name>] [--cypher <query>] [--desc <text>]',
       'patram queries remove <name>',
     ],
     option_column_width: 19,
     options: [
       {
-        description: 'Persist a new stored query',
-        label: '--query <clause>',
+        description: 'Persist a new stored Cypher query',
+        label: '--cypher <query>',
       },
       {
         description: 'Set or rename the stored query name for update',
@@ -271,16 +271,16 @@ const COMMAND_DEFINITIONS = {
       '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 add <name> --cypher <query> [--desc <text>] [options]`,
+      'patram queries update <name> [--name <new_name>] [--cypher <query>] [--desc <text>] [options]',
       'patram queries remove <name> [options]',
     ],
   },
   refs: {
-    allowed_option_names: new Set(['where']),
+    allowed_option_names: new Set(['cypher']),
     examples: [
       'patram refs docs/decisions/query-language.md',
-      "patram refs docs/decisions/query-language.md --where '$class=document'",
+      'patram refs docs/decisions/query-language.md --cypher "MATCH (n:Document) RETURN n"',
       'patram refs docs/decisions/query-language.md --json',
     ],
     extra_positionals_message: 'Refs accepts exactly one file path.',
@@ -289,15 +289,15 @@ const COMMAND_DEFINITIONS = {
     min_positionals: 1,
     missing_argument_examples: [
       'patram refs docs/decisions/query-language.md',
-      "patram refs docs/patram.md --where '$class=document'",
+      'patram refs docs/patram.md --cypher "MATCH (n:Document) RETURN n"',
     ],
     missing_argument_label: '<file>',
     missing_usage_lines: ['patram refs <file>'],
     option_column_width: 19,
     options: [
       {
-        description: 'Filter incoming source nodes with a where clause',
-        label: '--where <clause>',
+        description: 'Filter incoming source nodes with a Cypher query',
+        label: '--cypher <query>',
       },
       {
         description: 'Print plain text output',
@@ -350,102 +350,67 @@ const COMMAND_DEFINITIONS = {
 const HELP_TOPIC_DEFINITIONS = {
   'query-language': {
     examples: [
-      '$class=decision and status=accepted',
-      '$class=task or status=done',
-      '($class=task or status=blocked) and title~Show',
-      '$path^=docs/plans/',
-      'title~query',
-      'tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md',
-      'implements_command=command:query',
-      'status not in [done, dropped, superseded]',
-      'any(in:tracked_in, $class=task and status in [pending, ready, in_progress, blocked])',
-      'none(in:tracked_in, $class=decision)',
-      'count(in:decided_by, $class=task) = 0',
-      'not uses_term=term:graph',
+      "MATCH (n:Decision) WHERE n.status = 'accepted' RETURN n",
+      "MATCH (n:Task) WHERE n.status IN ['pending', 'ready'] RETURN n",
+      "MATCH (n) WHERE path(n) ENDS WITH '/README.md' RETURN n",
+      'MATCH (n:Plan) WHERE NOT EXISTS { MATCH (decision:Decision)-[:TRACKED_IN]->(n) } RETURN n',
+      'MATCH (n:Decision) WHERE COUNT { MATCH (task:Task)-[:DECIDED_BY]->(n) } = 0 RETURN n',
+      "MATCH (n) WHERE EXISTS { MATCH (n)-[:IMPLEMENTS_COMMAND]->(command:Command) WHERE id(command) = 'command:query' } RETURN n",
     ],
-    lead: 'Query language filters graph nodes with field, relation, traversal, and aggregate terms.',
+    lead: 'Query language uses a constrained Cypher subset for graph node selection.',
     operators: [
       {
-        description: 'Exact field match or exact count comparison',
-        label: '=',
+        description: 'Equality and exact value comparison',
+        label: '= | <>',
       },
       {
-        description: 'Prefix match for structural id and path',
-        label: '^=',
+        description: 'String prefix, suffix, and contains checks',
+        label: 'STARTS WITH | ENDS WITH | CONTAINS',
       },
       {
-        description: 'Contains text for title',
-        label: '~',
+        description: 'Set membership checks',
+        label: 'IN | NOT IN',
       },
       {
-        description: 'Set membership for supported fields',
-        label: 'in',
+        description: 'Boolean composition',
+        label: 'AND | OR | NOT',
       },
       {
-        description: 'Set exclusion for supported fields',
-        label: 'not in',
+        description: 'Relation existence subqueries',
+        label: 'EXISTS { ... }',
       },
       {
-        description: 'Negate one term',
-        label: 'not',
-      },
-      {
-        description: 'Combine terms',
-        label: 'and',
-      },
-      {
-        description: 'Match either side',
-        label: 'or',
-      },
-      {
-        description: 'Group boolean expressions',
-        label: '( )',
-      },
-      {
-        description: 'Count comparisons',
-        label: '!= < > >= <=',
+        description: 'Related-node count comparisons',
+        label: 'COUNT { ... }',
       },
     ],
     relation_terms: [
       {
-        description: 'Match nodes with at least one outgoing relation',
-        label: '<relation>:*',
-      },
-      {
-        description: 'Match nodes linked to an exact target id',
-        label: '<relation>=<target-id>',
+        description: 'Outgoing relation match',
+        label: '(n)-[:RELATION]->(target)',
       },
       {
-        description: 'Traverse one incoming relation hop',
-        label: 'in:<relation>',
+        description: 'Incoming relation match',
+        label: '(source)-[:RELATION]->(n)',
       },
       {
-        description: 'Traverse one outgoing relation hop',
-        label: 'out:<relation>',
+        description: 'Label-qualified related node pattern',
+        label: '(n)-[:RELATION]->(target:Label)',
       },
     ],
     terms: [
-      'Exact match: $id, $class, $path, status',
-      'Prefix match: $id, $path',
-      'Contains text: title',
-      'Set membership: $id, $class, $path, status, title',
+      'Root match: MATCH (n) or MATCH (n:Label)',
+      'Return shape: RETURN n',
+      'Structural functions: id(n), path(n)',
+      'Labels select class membership: MATCH (n:Label)',
+      'Common fields: n.title, n.status, n.kind',
+      'Subqueries: EXISTS { MATCH ... WHERE ... } and COUNT { MATCH ... WHERE ... }',
     ],
     usage_lines: [
-      '<field>=<value>',
-      '$id^=<prefix>',
-      '$path^=<prefix>',
-      'title~<text>',
-      '<field> in [<value>, ...]',
-      '<field> not in [<value>, ...]',
-      '<relation>:*',
-      '<relation>=<target-id>',
-      'any(<traversal>, <term> and <term>)',
-      'none(<traversal>, <term> and <term>)',
-      'count(<traversal>, <term> and <term>) <comparison> <number>',
-      'not <term>',
-      '<term> and <term>',
-      '<term> or <term>',
-      '(<expression>)',
+      'MATCH (n) RETURN n',
+      'MATCH (n:Label) WHERE <predicate> RETURN n',
+      'MATCH (n) WHERE EXISTS { MATCH ... } RETURN n',
+      'MATCH (n) WHERE COUNT { MATCH ... } <comparison> <number> RETURN n',
     ],
   },
 };
@@ -559,7 +524,7 @@ function listOptionLabels(command_name) {
   } else {
     option_labels.add('--limit');
     option_labels.add('--offset');
-    option_labels.add('--where');
+    option_labels.add('--cypher');
   }
 
   return [...option_labels];

package/lib/cli/main.js

@@ -16,16 +16,16 @@ import { runShowCommand } from './commands/show.js';
  * Loads repo state and routes `check`, `fields`, `query`, `queries`, and
  * `show` through the shared output pipeline.
  *
- * Kind: cli
- * Status: active
- * Implements Command: ../../docs/reference/commands/check.md
- * Implements Command: ../../docs/reference/commands/query.md
- * Implements Command: ../../docs/reference/commands/queries.md
- * Implements Command: ../../docs/reference/commands/refs.md
- * Implements Command: ../../docs/reference/commands/show.md
- * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../../docs/decisions/cli-output-architecture.md
- * Decided by: ../../docs/decisions/cli-argument-parser.md
+ * kind: cli
+ * status: active
+ * implements_command: ../../docs/reference/commands/check.md
+ * implements_command: ../../docs/reference/commands/query.md
+ * implements_command: ../../docs/reference/commands/queries.md
+ * implements_command: ../../docs/reference/commands/refs.md
+ * implements_command: ../../docs/reference/commands/show.md
+ * tracked_in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * decided_by: ../../docs/decisions/cli-output-architecture.md
+ * decided_by: ../../docs/decisions/cli-argument-parser.md
  * @patram
  * @see {@link ./parse-arguments.js}
  * @see {@link ./commands/query.js}