patram 0.11.0 → 0.12.0

package/lib/graph/query/cypher-support.js

@@ -0,0 +1,213 @@
+/**
+ * @import { PatramDiagnostic, PatramRepoConfig } from '../../config/load-patram-config.types.ts';
+ * @import {
+ *   ParsedAggregateComparison,
+ *   ParsedExpression,
+ *   ParsedFieldTerm,
+ *   ParsedTerm,
+ * } from '../parse-where-clause.types.ts';
+ * @import { CypherNodePattern } from './cypher.types.ts';
+ */
+
+/**
+ * @param {number} column
+ * @param {string} message
+ * @returns {{ diagnostic: PatramDiagnostic, success: false }}
+ */
+export function fail(column, message) {
+  return {
+    diagnostic: {
+      code: 'query.invalid',
+      column,
+      level: 'error',
+      line: 1,
+      message,
+      path: '<query>',
+    },
+    success: false,
+  };
+}
+
+/**
+ * @param {string} relation_type
+ * @returns {string}
+ */
+export function relationTypeToRelationName(relation_type) {
+  return relation_type.toLowerCase();
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function toPascalCase(value) {
+  return value
+    .split('_')
+    .map((part) => part[0]?.toUpperCase() + part.slice(1))
+    .join('');
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function toLowerSnakeCase(value) {
+  return value
+    .replace(/([a-z0-9])([A-Z])/gu, '$1_$2')
+    .replace(/[\s-]+/gu, '_')
+    .toLowerCase();
+}
+
+/**
+ * @param {string} value
+ * @returns {value is ParsedAggregateComparison}
+ */
+export function isAggregateComparison(value) {
+  return ['<', '<=', '<>', '=', '>', '>='].includes(value);
+}
+
+/**
+ * @param {CypherNodePattern} node_pattern
+ * @param {PatramRepoConfig | null} repo_config
+ * @returns {ParsedExpression | null}
+ */
+export function createNodeLabelExpression(node_pattern, repo_config) {
+  if (!node_pattern.label_name) {
+    return null;
+  }
+
+  return {
+    kind: 'term',
+    term: createFieldTerm(
+      '$class',
+      '=',
+      resolveClassName(node_pattern.label_name, repo_config),
+      node_pattern.column,
+    ),
+  };
+}
+
+/**
+ * @param {string} field_name
+ * @param {ParsedFieldTerm['operator']} operator
+ * @param {string} value
+ * @param {number} column
+ * @returns {{ success: true, expression: ParsedExpression }}
+ */
+export function createFieldExpression(field_name, operator, value, column) {
+  return {
+    expression: {
+      kind: 'term',
+      term: createFieldTerm(field_name, operator, value, column),
+    },
+    success: true,
+  };
+}
+
+/**
+ * @param {string} field_name
+ * @param {'in' | 'not in'} operator
+ * @param {string[]} values
+ * @param {number} column
+ * @returns {{ success: true, expression: ParsedExpression }}
+ */
+export function createFieldSetExpression(field_name, operator, values, column) {
+  return {
+    expression: {
+      kind: 'term',
+      term: {
+        column,
+        field_name,
+        kind: 'field_set',
+        operator,
+        values,
+      },
+    },
+    success: true,
+  };
+}
+
+/**
+ * @param {number} column
+ * @returns {ParsedExpression}
+ */
+export function createAlwaysTrueExpression(column) {
+  return {
+    kind: 'term',
+    term: createFieldTerm('$id', '^=', '', column),
+  };
+}
+
+/**
+ * @param {ParsedExpression[]} expressions
+ * @returns {ParsedExpression}
+ */
+export function collapseAndExpressions(expressions) {
+  return collapseBooleanExpression('and', expressions);
+}
+
+/**
+ * @param {'and' | 'or'} kind
+ * @param {ParsedExpression[]} expressions
+ * @returns {ParsedExpression}
+ */
+export function collapseBooleanExpression(kind, expressions) {
+  if (expressions.length === 0) {
+    return createAlwaysTrueExpression(1);
+  }
+
+  if (expressions.length === 1) {
+    return expressions[0];
+  }
+
+  return {
+    expressions,
+    kind,
+  };
+}
+
+/**
+ * @param {string} label_name
+ * @param {PatramRepoConfig | null} repo_config
+ * @returns {string}
+ */
+function resolveClassName(label_name, repo_config) {
+  if (
+    label_name === 'Document' ||
+    label_name === 'document' ||
+    label_name === toPascalCase('document')
+  ) {
+    return 'document';
+  }
+
+  for (const [class_name, class_definition] of Object.entries(
+    repo_config?.types ?? {},
+  )) {
+    if (
+      class_definition.label === label_name ||
+      class_name === label_name ||
+      toPascalCase(class_name) === label_name
+    ) {
+      return class_name;
+    }
+  }
+
+  return toLowerSnakeCase(label_name);
+}
+
+/**
+ * @param {string} field_name
+ * @param {ParsedFieldTerm['operator']} operator
+ * @param {string} value
+ * @param {number} column
+ * @returns {ParsedTerm}
+ */
+function createFieldTerm(field_name, operator, value, column) {
+  return {
+    column,
+    field_name,
+    kind: 'field',
+    operator,
+    value,
+  };
+}

package/lib/graph/query/cypher-tokenize.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @param {string} query_text
+ * @returns {{ success: true, tokens: CypherToken[] } | { diagnostic: PatramDiagnostic, success: false }}
+ */
+export function tokenizeCypher(query_text: string): {
+    success: true;
+    tokens: CypherToken[];
+} | {
+    diagnostic: PatramDiagnostic;
+    success: false;
+};
+import type { CypherToken } from './cypher.types.d.ts';
+import type { PatramDiagnostic } from '../../config/load-patram-config.types.d.ts';

package/lib/graph/query/cypher-tokenize.js

@@ -0,0 +1,225 @@
+/**
+ * @import { PatramDiagnostic } from '../../config/load-patram-config.types.ts';
+ * @import { CypherToken } from './cypher.types.ts';
+ */
+
+import { fail } from './cypher-support.js';
+
+const DOUBLE_CHAR_SYMBOLS = ['->', '<-', '<=', '>=', '<>'];
+const SINGLE_CHAR_SYMBOLS = '(){}[]:,.=-<>@';
+const IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*/u;
+const NUMBER_PATTERN = /^\d+/u;
+
+/**
+ * @param {string} query_text
+ * @returns {{ success: true, tokens: CypherToken[] } | { diagnostic: PatramDiagnostic, success: false }}
+ */
+export function tokenizeCypher(query_text) {
+  /** @type {CypherToken[]} */
+  const tokens = [];
+  let index = 0;
+
+  while (index < query_text.length) {
+    const char = query_text[index];
+
+    if (/\s/u.test(char)) {
+      index += 1;
+      continue;
+    }
+
+    const column = index + 1;
+    const string_result = readStringToken(query_text, index, column);
+
+    if (string_result) {
+      if (!string_result.success) {
+        return string_result;
+      }
+
+      tokens.push(string_result.token);
+      index = string_result.next_index;
+      continue;
+    }
+
+    const simple_token = readSimpleToken(query_text, index, column);
+
+    if (simple_token) {
+      tokens.push(simple_token.token);
+      index = simple_token.next_index;
+      continue;
+    }
+
+    return fail(column, `Unsupported query token "${char}".`);
+  }
+
+  return {
+    success: true,
+    tokens,
+  };
+}
+
+/**
+ * @param {string} query_text
+ * @param {number} start_index
+ * @param {number} column
+ * @returns {{ success: true, next_index: number, token: CypherToken } | { diagnostic: PatramDiagnostic, success: false } | null}
+ */
+function readStringToken(query_text, start_index, column) {
+  const quote = query_text[start_index];
+
+  if (quote !== "'" && quote !== '"') {
+    return null;
+  }
+
+  const string_result = readQuotedString(query_text, start_index);
+
+  if (!string_result.success) {
+    return string_result;
+  }
+
+  return {
+    next_index: string_result.next_index,
+    success: true,
+    token: {
+      column,
+      index: start_index,
+      kind: 'string',
+      value: string_result.value,
+    },
+  };
+}
+
+/**
+ * @param {string} query_text
+ * @param {number} start_index
+ * @param {number} column
+ * @returns {{ next_index: number, token: CypherToken } | null}
+ */
+function readSimpleToken(query_text, start_index, column) {
+  return (
+    readDoubleCharSymbol(query_text, start_index, column) ??
+    readSingleCharSymbol(query_text, start_index, column) ??
+    readPatternToken(
+      query_text,
+      start_index,
+      column,
+      NUMBER_PATTERN,
+      'number',
+    ) ??
+    readPatternToken(
+      query_text,
+      start_index,
+      column,
+      IDENTIFIER_PATTERN,
+      'identifier',
+    )
+  );
+}
+
+/**
+ * @param {string} query_text
+ * @param {number} start_index
+ * @param {number} column
+ * @returns {{ next_index: number, token: CypherToken } | null}
+ */
+function readDoubleCharSymbol(query_text, start_index, column) {
+  const value = query_text.slice(start_index, start_index + 2);
+
+  if (!DOUBLE_CHAR_SYMBOLS.includes(value)) {
+    return null;
+  }
+
+  return createTokenResult(start_index, column, 'symbol', value);
+}
+
+/**
+ * @param {string} query_text
+ * @param {number} start_index
+ * @param {number} column
+ * @returns {{ next_index: number, token: CypherToken } | null}
+ */
+function readSingleCharSymbol(query_text, start_index, column) {
+  const value = query_text[start_index];
+
+  if (!SINGLE_CHAR_SYMBOLS.includes(value)) {
+    return null;
+  }
+
+  return createTokenResult(start_index, column, 'symbol', value);
+}
+
+/**
+ * @param {string} query_text
+ * @param {number} start_index
+ * @param {number} column
+ * @param {RegExp} pattern
+ * @param {'identifier' | 'number'} kind
+ * @returns {{ next_index: number, token: CypherToken } | null}
+ */
+function readPatternToken(query_text, start_index, column, pattern, kind) {
+  const match = query_text.slice(start_index).match(pattern);
+
+  if (!match) {
+    return null;
+  }
+
+  return createTokenResult(start_index, column, kind, match[0]);
+}
+
+/**
+ * @param {number} index
+ * @param {number} column
+ * @param {CypherToken['kind']} kind
+ * @param {string} value
+ * @returns {{ next_index: number, token: CypherToken }}
+ */
+function createTokenResult(index, column, kind, value) {
+  return {
+    next_index: index + value.length,
+    token: {
+      column,
+      index,
+      kind,
+      value,
+    },
+  };
+}
+
+/**
+ * @param {string} query_text
+ * @param {number} start_index
+ * @returns {{ success: true, next_index: number, value: string } | { diagnostic: PatramDiagnostic, success: false }}
+ */
+function readQuotedString(query_text, start_index) {
+  const quote = query_text[start_index];
+  let index = start_index + 1;
+  let value = '';
+
+  while (index < query_text.length) {
+    const char = query_text[index];
+
+    if (char === '\\') {
+      const escaped_char = query_text[index + 1];
+
+      if (escaped_char === undefined) {
+        break;
+      }
+
+      value += escaped_char;
+      index += 2;
+      continue;
+    }
+
+    if (char === quote) {
+      return {
+        next_index: index + 1,
+        success: true,
+        value,
+      };
+    }
+
+    value += char;
+    index += 1;
+  }
+
+  return fail(start_index + 1, 'Unterminated string literal.');
+}

package/lib/graph/query/cypher.types.d.ts

@@ -0,0 +1,43 @@
+import type { PatramDiagnostic, PatramRepoConfig } from '../../config/load-patram-config.types.d.ts';
+import type { ParsedAggregateTerm, ParsedExpression, ParsedTraversalTerm } from '../parse-where-clause.types.d.ts';
+export interface CypherToken {
+    column: number;
+    index: number;
+    kind: 'identifier' | 'number' | 'string' | 'symbol';
+    value: string;
+}
+export interface CypherParserState {
+    bindings: Record<string, string>;
+    index: number;
+    query_text: string;
+    repo_config: PatramRepoConfig | null;
+    root_variable_name: string | null;
+    tokens: CypherToken[];
+}
+export interface CypherNodePattern {
+    column: number;
+    label_name: string | null;
+    variable_name: string | null;
+}
+export interface CypherRelationPattern {
+    column: number;
+    direction: 'in' | 'out';
+    relation_name: string;
+}
+export type CypherParseFailure = {
+    diagnostic: PatramDiagnostic;
+    success: false;
+};
+export type CypherAggregateResult = {
+    success: true;
+    term: ParsedAggregateTerm;
+} | CypherParseFailure;
+export type CypherSubqueryShapeResult = {
+    success: true;
+    related_node: CypherNodePattern;
+    traversal: ParsedTraversalTerm;
+} | CypherParseFailure;
+export type CypherExpressionResult = {
+    success: true;
+    expression: ParsedExpression;
+} | CypherParseFailure;

package/lib/graph/query/execute.d.ts

@@ -37,13 +37,13 @@ export function queryGraph(graph: BuildGraphResult, where_clause: string, repo_c
  * 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}