patram 0.2.0 → 0.4.0

package/lib/query-graph.js

@@ -1,10 +1,10 @@
 /* eslint-disable max-lines */
 /**
  * @import { BuildGraphResult, GraphNode } from './build-graph.types.ts';
- * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ * @import { PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
  * @import {
  *   ParsedAggregateTerm,
- *   ParsedClause,
+ *   ParsedExpression,
  *   ParsedFieldSetTerm,
  *   ParsedFieldTerm,
  *   ParsedRelationTargetTerm,
@@ -14,6 +14,7 @@
  */
 
 import { parseWhereClause } from './parse-where-clause.js';
+import { getQuerySemanticDiagnostics } from './query-inspection.js';
 
 /**
  * Query graph filtering.
@@ -54,10 +55,16 @@ export const DEFAULT_QUERY_LIMIT = 25;
  *
  * @param {BuildGraphResult} graph
  * @param {string} where_clause
+ * @param {PatramRepoConfig | { limit?: number, offset?: number }=} repo_config_or_pagination
  * @param {{ limit?: number, offset?: number }=} pagination_options
  * @returns {{ diagnostics: PatramDiagnostic[], nodes: GraphNode[], total_count: number }}
  */
-export function queryGraph(graph, where_clause, pagination_options = {}) {
+export function queryGraph(
+  graph,
+  where_clause,
+  repo_config_or_pagination = {},
+  pagination_options = {},
+) {
   const parse_result = parseWhereClause(where_clause);
 
   if (!parse_result.success) {
@@ -68,15 +75,37 @@ export function queryGraph(graph, where_clause, pagination_options = {}) {
     };
   }
 
+  const { pagination_options: resolved_pagination_options, repo_config } =
+    resolveQueryGraphOptions(repo_config_or_pagination, pagination_options);
+
+  if (repo_config) {
+    const diagnostics = getQuerySemanticDiagnostics(
+      repo_config,
+      { kind: 'ad_hoc' },
+      parse_result.expression,
+    );
+
+    if (diagnostics.length > 0) {
+      return {
+        diagnostics,
+        nodes: [],
+        total_count: 0,
+      };
+    }
+  }
+
   const evaluation_context = {
     nodes: graph.nodes,
     relation_indexes: createRelationIndexes(graph.edges),
   };
   const graph_nodes = Object.values(graph.nodes).sort(compareGraphNodes);
   const matching_nodes = graph_nodes.filter((graph_node) =>
-    matchesClauses(graph_node, parse_result.clauses, evaluation_context),
+    matchesExpression(graph_node, parse_result.expression, evaluation_context),
+  );
+  const paginated_nodes = paginateNodes(
+    matching_nodes,
+    resolved_pagination_options,
   );
-  const paginated_nodes = paginateNodes(matching_nodes, pagination_options);
 
   return {
     diagnostics: [],
@@ -87,26 +116,36 @@ export function queryGraph(graph, where_clause, pagination_options = {}) {
 
 /**
  * @param {GraphNode} graph_node
- * @param {ParsedClause[]} clauses
+ * @param {ParsedExpression} expression
  * @param {EvaluationContext} evaluation_context
  * @returns {boolean}
  */
-function matchesClauses(graph_node, clauses, evaluation_context) {
-  return clauses.every((clause) =>
-    matchesClause(graph_node, clause, evaluation_context),
-  );
-}
+function matchesExpression(graph_node, expression, evaluation_context) {
+  if (expression.kind === 'and') {
+    return expression.expressions.every((subexpression) =>
+      matchesExpression(graph_node, subexpression, evaluation_context),
+    );
+  }
 
-/**
- * @param {GraphNode} graph_node
- * @param {ParsedClause} clause
- * @param {EvaluationContext} evaluation_context
- * @returns {boolean}
- */
-function matchesClause(graph_node, clause, evaluation_context) {
-  const is_match = matchesTerm(graph_node, clause.term, evaluation_context);
+  if (expression.kind === 'or') {
+    return expression.expressions.some((subexpression) =>
+      matchesExpression(graph_node, subexpression, evaluation_context),
+    );
+  }
+
+  if (expression.kind === 'not') {
+    return !matchesExpression(
+      graph_node,
+      expression.expression,
+      evaluation_context,
+    );
+  }
+
+  if (expression.kind === 'term') {
+    return matchesTerm(graph_node, expression.term, evaluation_context);
+  }
 
-  return clause.is_negated ? !is_match : is_match;
+  throw new Error('Unsupported parsed boolean expression.');
 }
 
 /**
@@ -152,7 +191,7 @@ function matchesAggregateTerm(graph_node, term, evaluation_context) {
     evaluation_context,
   );
   const matching_count = related_nodes.filter((related_node) =>
-    matchesClauses(related_node, term.clauses, evaluation_context),
+    matchesExpression(related_node, term.expression, evaluation_context),
   ).length;
 
   if (term.aggregate_name === 'any') {
@@ -176,29 +215,48 @@ function matchesAggregateTerm(graph_node, term, evaluation_context) {
  * @returns {boolean}
  */
 function matchesFieldTerm(graph_node, term) {
-  const term_key = `${term.field_name}${term.operator}`;
+  const field_values = getGraphNodeFieldValues(graph_node, term.field_name);
 
-  if (
-    term_key === 'id=' ||
-    term_key === 'kind=' ||
-    term_key === 'path=' ||
-    term_key === 'status='
-  ) {
-    return graph_node[term.field_name] === term.value;
+  if (term.operator === '=') {
+    return field_values.some((field_value) => field_value === term.value);
   }
 
-  if (term_key === 'id^=') {
-    return graph_node.id.startsWith(term.value);
+  if (term.operator === '!=') {
+    return field_values.every((field_value) => field_value !== term.value);
   }
 
-  if (term_key === 'path^=') {
-    return (graph_node.path ?? '').startsWith(term.value);
+  if (term.operator === '^=') {
+    return field_values.some((field_value) =>
+      field_value.startsWith(term.value),
+    );
   }
 
-  if (term_key === 'title~') {
-    return (graph_node.title ?? '')
-      .toLocaleLowerCase('en')
-      .includes(term.value.toLocaleLowerCase('en'));
+  if (term.operator === '~') {
+    const term_value = term.value.toLocaleLowerCase('en');
+
+    return field_values.some((field_value) =>
+      field_value.toLocaleLowerCase('en').includes(term_value),
+    );
+  }
+
+  if (term.operator === '<' || term.operator === '<=') {
+    return field_values.some((field_value) =>
+      compareFieldValues(
+        field_value,
+        /** @type {'<' | '<='} */ (term.operator),
+        term.value,
+      ),
+    );
+  }
+
+  if (term.operator === '>' || term.operator === '>=') {
+    return field_values.some((field_value) =>
+      compareFieldValues(
+        field_value,
+        /** @type {'>' | '>='} */ (term.operator),
+        term.value,
+      ),
+    );
   }
 
   throw new Error('Unsupported parsed where clause.');
@@ -210,8 +268,10 @@ function matchesFieldTerm(graph_node, term) {
  * @returns {boolean}
  */
 function matchesFieldSetTerm(graph_node, term) {
-  const actual_value = graph_node[term.field_name];
-  const is_member = actual_value ? term.values.includes(actual_value) : false;
+  const field_values = getGraphNodeFieldValues(graph_node, term.field_name);
+  const is_member = field_values.some((field_value) =>
+    term.values.includes(field_value),
+  );
 
   return term.operator === 'in' ? is_member : !is_member;
 }
@@ -352,7 +412,10 @@ function createDirectionalRelationIndex(graph_edges, source_key, target_key) {
  * @returns {number}
  */
 function compareGraphNodes(left_node, right_node) {
-  return left_node.id.localeCompare(right_node.id, 'en');
+  return (left_node.$id ?? left_node.id).localeCompare(
+    right_node.$id ?? right_node.id,
+    'en',
+  );
 }
 
 /**
@@ -366,3 +429,169 @@ function paginateNodes(matching_nodes, pagination_options) {
 
   return matching_nodes.slice(offset, offset + limit);
 }
+
+/**
+ * @param {GraphNode} graph_node
+ * @param {string} field_name
+ * @returns {string[]}
+ */
+function getGraphNodeFieldValues(graph_node, field_name) {
+  const structural_value = getStructuralFieldValue(graph_node, field_name);
+
+  if (structural_value !== undefined) {
+    return [structural_value];
+  }
+
+  if (field_name === '$path' || field_name === 'title') {
+    return [];
+  }
+
+  return normalizeFieldValues(graph_node[field_name]);
+}
+
+/**
+ * @param {GraphNode} graph_node
+ * @param {string} field_name
+ * @returns {string | undefined}
+ */
+function getStructuralFieldValue(graph_node, field_name) {
+  if (field_name === '$id') {
+    return graph_node.$id ?? graph_node.id;
+  }
+
+  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;
+  }
+}
+
+/**
+ * @param {unknown} field_value
+ * @returns {string[]}
+ */
+function normalizeFieldValues(field_value) {
+  if (Array.isArray(field_value)) {
+    return field_value.flatMap(getScalarFieldValue);
+  }
+
+  return getScalarFieldValue(field_value);
+}
+
+/**
+ * @param {unknown} field_value
+ * @returns {string[]}
+ */
+function getScalarFieldValue(field_value) {
+  if (
+    typeof field_value === 'string' ||
+    typeof field_value === 'number' ||
+    typeof field_value === 'boolean'
+  ) {
+    return [String(field_value)];
+  }
+
+  return [];
+}
+
+/**
+ * @param {PatramRepoConfig | { limit?: number, offset?: number }} repo_config_or_pagination
+ * @param {{ limit?: number, offset?: number }} pagination_options
+ * @returns {{ pagination_options: { limit?: number, offset?: number }, repo_config: PatramRepoConfig | null }}
+ */
+function resolveQueryGraphOptions(
+  repo_config_or_pagination,
+  pagination_options,
+) {
+  if (isRepoConfig(repo_config_or_pagination)) {
+    return {
+      pagination_options,
+      repo_config: repo_config_or_pagination,
+    };
+  }
+
+  return {
+    pagination_options: repo_config_or_pagination,
+    repo_config: null,
+  };
+}
+
+/**
+ * @param {PatramRepoConfig | { limit?: number, offset?: number }} value
+ * @returns {value is PatramRepoConfig}
+ */
+function isRepoConfig(value) {
+  return 'include' in value || 'queries' in value;
+}
+
+/**
+ * @param {string} left_value
+ * @param {'<' | '<=' | '>' | '>='} comparison
+ * @param {string} right_value
+ * @returns {boolean}
+ */
+function compareFieldValues(left_value, comparison, right_value) {
+  const numeric_comparison = compareNumericFieldValues(
+    left_value,
+    comparison,
+    right_value,
+  );
+
+  if (numeric_comparison !== null) {
+    return numeric_comparison;
+  }
+
+  return compareComparableValues(
+    left_value.localeCompare(right_value, 'en'),
+    comparison,
+  );
+}
+
+/**
+ * @param {string} left_value
+ * @param {'<' | '<=' | '>' | '>='} comparison
+ * @param {string} right_value
+ * @returns {boolean | null}
+ */
+function compareNumericFieldValues(left_value, comparison, right_value) {
+  const left_number = Number(left_value);
+  const right_number = Number(right_value);
+
+  if (
+    !Number.isFinite(left_number) ||
+    !Number.isFinite(right_number) ||
+    left_value.trim().length === 0 ||
+    right_value.trim().length === 0
+  ) {
+    return null;
+  }
+
+  return compareComparableValues(left_number - right_number, comparison);
+}
+
+/**
+ * @param {number} comparison_result
+ * @param {'<' | '<=' | '>' | '>='} comparison
+ * @returns {boolean}
+ */
+function compareComparableValues(comparison_result, comparison) {
+  if (comparison === '<') {
+    return comparison_result < 0;
+  }
+
+  if (comparison === '<=') {
+    return comparison_result <= 0;
+  }
+
+  if (comparison === '>') {
+    return comparison_result > 0;
+  }
+
+  return comparison_result >= 0;
+}