patram 0.10.0 → 0.12.0

package/lib/graph/query/execute.js

@@ -13,8 +13,16 @@
  * } from '../parse-where-clause.types.ts';
  */
 
-import { parseWhereClause } from './parse.js';
+import { matchesGlob } from 'node:path';
+
+import {
+  getGraphNodeClassName,
+  getGraphNodeId,
+  getGraphNodeMetadataValue,
+  getGraphNodePath,
+} from '../graph-node.js';
 import { getQuerySemanticDiagnostics } from './inspect.js';
+import { parseQueryExpression } from './parse-query.js';
 
 /**
  * Query graph filtering.
@@ -22,13 +30,13 @@ import { getQuerySemanticDiagnostics } from './inspect.js';
  * Applies the v0 where-clause language to graph nodes and keeps pagination
  * separate from matching.
  *
- * Kind: graph
- * Status: active
- * Uses Term: ../../../docs/reference/terms/graph.md
- * Uses Term: ../../../docs/reference/terms/query.md
- * Tracked in: ../../../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../../../docs/decisions/query-language.md
- * Implements: ../../../docs/tasks/v0/query-command.md
+ * kind: graph
+ * status: active
+ * uses_term: ../../../docs/reference/terms/graph.md
+ * uses_term: ../../../docs/reference/terms/query.md
+ * tracked_in: ../../../docs/plans/v0/source-anchor-dogfooding.md
+ * decided_by: ../../../docs/decisions/query-language.md
+ * implements: ../../../docs/tasks/v0/query-command.md
  * @patram
  * @see {@link ../../../docs/decisions/query-language.md}
  * @see {@link ../load-project-graph.js}
@@ -75,7 +83,7 @@ export function queryGraph(
 ) {
   const { query_options: resolved_query_options, repo_config } =
     resolveQueryGraphOptions(repo_config_or_query_options, query_options);
-  const parse_result = parseWhereClause(where_clause, {
+  const parse_result = parseQueryExpression(where_clause, repo_config, {
     bindings: resolved_query_options.bindings,
   });
 
@@ -107,7 +115,9 @@ export function queryGraph(
     nodes: graph.nodes,
     relation_indexes: createRelationIndexes(graph.edges),
   };
-  const graph_nodes = Object.values(graph.nodes).sort(compareGraphNodes);
+  const graph_nodes = collectCanonicalGraphNodes(graph.nodes).sort(
+    compareGraphNodes,
+  );
   const matching_nodes = graph_nodes.filter((graph_node) =>
     matchesExpression(graph_node, parse_result.expression, evaluation_context),
   );
@@ -175,7 +185,7 @@ function matchesTerm(graph_node, term, evaluation_context) {
 
   if (term.kind === 'relation') {
     return hasOutgoingRelation(
-      graph_node.id,
+      getGraphNodeId(graph_node),
       term.relation_name,
       evaluation_context.relation_indexes,
     );
@@ -192,7 +202,7 @@ function matchesTerm(graph_node, term, evaluation_context) {
  */
 function matchesAggregateTerm(graph_node, term, evaluation_context) {
   const related_nodes = getRelatedNodes(
-    graph_node.id,
+    getGraphNodeId(graph_node),
     term.traversal,
     evaluation_context,
   );
@@ -220,6 +230,7 @@ function matchesAggregateTerm(graph_node, term, evaluation_context) {
  * @param {ParsedFieldTerm} term
  * @returns {boolean}
  */
+// eslint-disable-next-line complexity
 function matchesFieldTerm(graph_node, term) {
   const field_values = getGraphNodeFieldValues(graph_node, term.field_name);
 
@@ -227,7 +238,7 @@ function matchesFieldTerm(graph_node, term) {
     return field_values.some((field_value) => field_value === term.value);
   }
 
-  if (term.operator === '!=') {
+  if (term.operator === '<>') {
     return field_values.every((field_value) => field_value !== term.value);
   }
 
@@ -237,6 +248,16 @@ function matchesFieldTerm(graph_node, term) {
     );
   }
 
+  if (term.operator === '$=') {
+    return field_values.some((field_value) => field_value.endsWith(term.value));
+  }
+
+  if (term.operator === '*=') {
+    return field_values.some((field_value) =>
+      matchesGlob(field_value, term.value),
+    );
+  }
+
   if (term.operator === '~') {
     const term_value = term.value.toLocaleLowerCase('en');
 
@@ -290,7 +311,7 @@ function matchesFieldSetTerm(graph_node, term) {
  */
 function matchesRelationTargetTerm(graph_node, term, evaluation_context) {
   const relation_targets = evaluation_context.relation_indexes.outgoing.get(
-    graph_node.id,
+    getGraphNodeId(graph_node),
   );
   const matching_targets = relation_targets?.get(term.relation_name);
 
@@ -334,14 +355,35 @@ function getRelatedNodes(node_id, traversal, evaluation_context) {
   });
 }
 
+/**
+ * @param {BuildGraphResult['nodes']} graph_nodes
+ * @returns {GraphNode[]}
+ */
+function collectCanonicalGraphNodes(graph_nodes) {
+  /** @type {Map<string, GraphNode>} */
+  const canonical_nodes = new Map();
+
+  for (const graph_node of Object.values(graph_nodes)) {
+    const graph_node_id = getGraphNodeId(graph_node);
+
+    if (!graph_node_id) {
+      continue;
+    }
+
+    canonical_nodes.set(graph_node_id, graph_node);
+  }
+
+  return [...canonical_nodes.values()];
+}
+
 /**
  * @param {number} left_value
- * @param {'!=' | '<' | '<=' | '=' | '>' | '>='} comparison
+ * @param {'<' | '<=' | '<>' | '=' | '>' | '>='} comparison
  * @param {number} right_value
  * @returns {boolean}
  */
 function compareNumbers(left_value, comparison, right_value) {
-  if (comparison === '!=') {
+  if (comparison === '<>') {
     return left_value !== right_value;
   }
 
@@ -418,8 +460,8 @@ function createDirectionalRelationIndex(graph_edges, source_key, target_key) {
  * @returns {number}
  */
 function compareGraphNodes(left_node, right_node) {
-  return (left_node.$id ?? left_node.id).localeCompare(
-    right_node.$id ?? right_node.id,
+  return getGraphNodeId(left_node).localeCompare(
+    getGraphNodeId(right_node),
     'en',
   );
 }
@@ -452,7 +494,9 @@ function getGraphNodeFieldValues(graph_node, field_name) {
     return [];
   }
 
-  return normalizeFieldValues(graph_node[field_name]);
+  return normalizeFieldValues(
+    getGraphNodeMetadataValue(graph_node, field_name),
+  );
 }
 
 /**
@@ -461,21 +505,15 @@ function getGraphNodeFieldValues(graph_node, field_name) {
  * @returns {string | undefined}
  */
 function getStructuralFieldValue(graph_node, field_name) {
-  if (field_name === '$id') {
-    return graph_node.$id ?? graph_node.id;
-  }
+  const node_path = getGraphNodePath(graph_node);
+  const node_title = getGraphNodeMetadataValue(graph_node, 'title');
 
-  if (field_name === '$class') {
-    return graph_node.$class ?? graph_node.kind;
-  }
-
-  if (field_name === '$path') {
-    return graph_node.$path ?? graph_node.path;
-  }
-
-  if (field_name === 'title') {
-    return graph_node.title;
-  }
+  return {
+    $class: getGraphNodeClassName(graph_node),
+    $id: getGraphNodeId(graph_node),
+    $path: node_path,
+    title: Array.isArray(node_title) ? node_title[0] : node_title,
+  }[field_name];
 }
 
 /**

package/lib/graph/query/inspect.js

@@ -1,6 +1,6 @@
 /* eslint-disable max-lines */
 /**
- * @import { PatramDiagnostic, PatramRepoConfig } from '../../config/load-patram-config.types.ts';
+ * @import { MetadataFieldConfig, PatramDiagnostic, PatramRepoConfig } from '../../config/load-patram-config.types.ts';
  * @import {
  *   ParsedExpression,
  *   ParsedRelationTargetTerm,
@@ -12,7 +12,7 @@
 
 import { Ansis } from 'ansis';
 
-import { parseWhereClause } from './parse.js';
+import { parseQueryExpression } from './parse-query.js';
 
 /**
  * @typedef {{ kind: 'ad_hoc' } | { kind: 'stored_query', name: string }} QuerySource
@@ -56,7 +56,10 @@ export function inspectQuery(
   resolved_where_clause,
   inspection_options,
 ) {
-  const parse_result = parseWhereClause(resolved_where_clause.where_clause);
+  const parse_result = parseQueryExpression(
+    resolved_where_clause.where_clause,
+    repo_config,
+  );
 
   if (!parse_result.success) {
     return {
@@ -153,23 +156,57 @@ export function getQuerySemanticDiagnostics(
   query_source,
   expression,
 ) {
-  const known_relation_names = new Set(
-    Object.keys(repo_config.relations ?? {}),
-  );
+  const known_relation_names = new Set(['links_to']);
   /** @type {PatramDiagnostic[]} */
   const diagnostics = [];
 
+  for (const [field_name, field_definition] of Object.entries(
+    repo_config.fields ?? {},
+  )) {
+    if (field_definition.type === 'ref') {
+      known_relation_names.add(field_name);
+    }
+  }
+
   collectExpressionDiagnostics(
     expression,
     diagnostics,
     known_relation_names,
-    repo_config.fields ?? {},
+    createKnownFieldDefinitions(repo_config),
     formatQueryDiagnosticPath(query_source),
   );
 
   return diagnostics;
 }
 
+/**
+ * @param {PatramRepoConfig} repo_config
+ * @returns {Record<string, MetadataFieldConfig | {type: 'string'}>}
+ */
+function createKnownFieldDefinitions(repo_config) {
+  /** @type {Record<string, MetadataFieldConfig | {type: 'string'}>} */
+  const known_field_definitions = {
+    description: {
+      type: 'string',
+    },
+    title: {
+      type: 'string',
+    },
+  };
+
+  for (const [field_name, field_definition] of Object.entries(
+    repo_config.fields ?? {},
+  )) {
+    if (field_definition.type === 'ref') {
+      continue;
+    }
+
+    known_field_definitions[field_name] = field_definition;
+  }
+
+  return known_field_definitions;
+}
+
 /**
  * @param {ParsedExpression} expression
  * @param {PatramDiagnostic[]} diagnostics
@@ -384,7 +421,7 @@ function getFieldDiagnosticsCollector(field_name) {
  */
 function collectTitleFieldDiagnostics(term, diagnostics, diagnostic_path) {
   const operator = term.kind === 'field' ? term.operator : term.operator;
-  const allowed = new Set(['=', '!=', 'in', 'not in', '~']);
+  const allowed = new Set(['=', '<>', 'in', 'not in', '~']);
 
   if (allowed.has(operator)) {
     return;
@@ -408,9 +445,9 @@ function collectTitleFieldDiagnostics(term, diagnostics, diagnostic_path) {
 function collectStructuralFieldDiagnostics(term, diagnostics, diagnostic_path) {
   const operator = term.kind === 'field' ? term.operator : term.operator;
   const allowed_by_field = new Map([
-    ['$class', new Set(['=', '!=', 'in', 'not in'])],
-    ['$id', new Set(['=', '!=', 'in', 'not in', '^='])],
-    ['$path', new Set(['=', '!=', 'in', 'not in', '^='])],
+    ['$class', new Set(['=', '<>', 'in', 'not in'])],
+    ['$id', new Set(['=', '<>', 'in', 'not in', '^='])],
+    ['$path', new Set(['$=', '=', '<>', 'in', 'not in', '*=', '^='])],
   ]);
   const allowed = allowed_by_field.get(term.field_name);
 
@@ -457,7 +494,7 @@ function getMetadataFieldOperatorDiagnostic(
  * @returns {boolean}
  */
 function supportsMetadataFieldOperator(operator, field_definition) {
-  if (operator === '=' || operator === '!=') {
+  if (operator === '=' || operator === '<>') {
     return true;
   }
 
@@ -465,6 +502,10 @@ function supportsMetadataFieldOperator(operator, field_definition) {
     return supportsPrefixOperator(field_definition);
   }
 
+  if (operator === '*=') {
+    return false;
+  }
+
   if (operator === '~') {
     return supportsContainsOperator(field_definition);
   }
@@ -477,14 +518,7 @@ function supportsMetadataFieldOperator(operator, field_definition) {
  * @returns {boolean}
  */
 function supportsPrefixOperator(field_definition) {
-  if (field_definition.type === 'path') {
-    return true;
-  }
-
-  return (
-    field_definition.type === 'string' &&
-    field_definition.query?.prefix === true
-  );
+  return field_definition.type === 'path' || field_definition.type === 'string';
 }
 
 /**
@@ -492,10 +526,7 @@ function supportsPrefixOperator(field_definition) {
  * @returns {boolean}
  */
 function supportsContainsOperator(field_definition) {
-  return (
-    field_definition.type === 'string' &&
-    field_definition.query?.contains === true
-  );
+  return field_definition.type === 'string' || field_definition.type === 'path';
 }
 
 /**
@@ -732,6 +763,7 @@ function formatExpressionSummary(expression) {
     return formatTermSummary(expression.term);
   }
 
+  /* istanbul ignore next -- defensive unreachable */
   throw new Error('Unsupported explain expression.');
 }
 
@@ -763,6 +795,7 @@ function formatExpressionDetailLines(expression, render_options, indentation) {
   }
 
   if (expression.kind !== 'term') {
+    /* istanbul ignore next -- defensive unreachable */
     throw new Error('Unsupported explain expression details.');
   }
 
@@ -818,6 +851,7 @@ function formatTermSummary(term) {
     return `${term.relation_name} = ${term.target_id}`;
   }
 
+  /* istanbul ignore next -- defensive unreachable */
   throw new Error('Expected a parsed query term.');
 }
 

package/lib/graph/query/parse-cypher-patterns.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @param {CypherParserState} parser_state
+ * @param {number} column
+ * @param {'any' | 'count'} aggregate_name
+ * @param {(parser_state: CypherParserState) => CypherExpressionResult} parse_boolean_expression
+ * @returns {CypherAggregateResult}
+ */
+export function parseSubqueryAggregate(parser_state: CypherParserState, column: number, aggregate_name: "any" | "count", parse_boolean_expression: (parser_state: CypherParserState) => CypherExpressionResult): CypherAggregateResult;
+/**
+ * @param {CypherParserState} parser_state
+ * @returns {CypherNodePattern}
+ */
+export function parseNodePattern(parser_state: CypherParserState): CypherNodePattern;
+/**
+ * @param {CypherParserState} parser_state
+ * @returns {string}
+ */
+export function parseCypherScalarValue(parser_state: CypherParserState): string;
+/**
+ * @param {CypherParserState} parser_state
+ * @returns {string[]}
+ */
+export function parseCypherListValue(parser_state: CypherParserState): string[];
+import type { CypherParserState } from './cypher.types.d.ts';
+import type { CypherExpressionResult } from './cypher.types.d.ts';
+import type { CypherAggregateResult } from './cypher.types.d.ts';
+import type { CypherNodePattern } from './cypher.types.d.ts';