patram 0.2.0 → 0.4.0

package/lib/query-inspection.js

@@ -3,7 +3,7 @@
  * @import { PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
  * @import { ResolvedOutputMode } from './output-view.types.ts';
  * @import {
- *   ParsedClause,
+ *   ParsedExpression,
  *   ParsedRelationTargetTerm,
  *   ParsedRelationTerm,
  *   ParsedTerm,
@@ -19,6 +19,10 @@ import { parseWhereClause } from './parse-where-clause.js';
  * @typedef {{ kind: 'ad_hoc' } | { kind: 'stored_query', name: string }} QuerySource
  */
 
+/**
+ * @typedef {import('./parse-where-clause.types.ts').ParsedFieldTerm | import('./parse-where-clause.types.ts').ParsedFieldSetTerm} FieldDiagnosticTerm
+ */
+
 /**
  * @typedef {{ query_source: QuerySource, where_clause: string }} ResolvedWhereClause
  */
@@ -33,10 +37,10 @@ import { parseWhereClause } from './parse-where-clause.js';
  *     limit: number | null,
  *     offset: number,
  *   },
+ *   expression?: ParsedExpression,
  *   inspection_mode: 'explain' | 'lint',
  *   query_source: QuerySource,
  *   where_clause: string,
- *   clauses?: ParsedClause[],
  * }} QueryInspectionSuccess
  */
 
@@ -67,10 +71,10 @@ export function inspectQuery(
     };
   }
 
-  const diagnostics = collectRelationDiagnostics(
+  const diagnostics = getQuerySemanticDiagnostics(
     repo_config,
     resolved_where_clause.query_source,
-    parse_result.clauses,
+    parse_result.expression,
   );
 
   if (diagnostics.length > 0) {
@@ -94,11 +98,11 @@ export function inspectQuery(
   return {
     success: true,
     value: {
-      clauses: parse_result.clauses,
       execution: {
         limit: inspection_options.limit,
         offset: inspection_options.offset,
       },
+      expression: parse_result.expression,
       inspection_mode: 'explain',
       query_source: resolved_where_clause.query_source,
       where_clause: resolved_where_clause.where_clause,
@@ -138,24 +142,29 @@ export function renderQueryInspection(query_inspection, output_mode) {
 }
 
 /**
+ * Collect schema-aware diagnostics for one parsed where clause.
+ *
  * @param {PatramRepoConfig} repo_config
  * @param {QuerySource} query_source
- * @param {ParsedClause[]} clauses
+ * @param {ParsedExpression} expression
  * @returns {PatramDiagnostic[]}
  */
-function collectRelationDiagnostics(repo_config, query_source, clauses) {
-  if (!repo_config.relations) {
-    return [];
-  }
-
-  const known_relation_names = new Set(Object.keys(repo_config.relations));
+export function getQuerySemanticDiagnostics(
+  repo_config,
+  query_source,
+  expression,
+) {
+  const known_relation_names = new Set(
+    Object.keys(repo_config.relations ?? {}),
+  );
   /** @type {PatramDiagnostic[]} */
   const diagnostics = [];
 
-  collectClauseDiagnostics(
-    clauses,
+  collectExpressionDiagnostics(
+    expression,
     diagnostics,
     known_relation_names,
+    repo_config.fields ?? {},
     formatQueryDiagnosticPath(query_source),
   );
 
@@ -163,37 +172,72 @@ function collectRelationDiagnostics(repo_config, query_source, clauses) {
 }
 
 /**
- * @param {ParsedClause[]} clauses
+ * @param {ParsedExpression} expression
  * @param {PatramDiagnostic[]} diagnostics
  * @param {Set<string>} known_relation_names
+ * @param {Record<string, import('./load-patram-config.types.ts').MetadataFieldConfig>} known_field_definitions
  * @param {string} diagnostic_path
  */
-function collectClauseDiagnostics(
-  clauses,
+function collectExpressionDiagnostics(
+  expression,
   diagnostics,
   known_relation_names,
+  known_field_definitions,
   diagnostic_path,
 ) {
-  for (const clause of clauses) {
+  if (expression.kind === 'and' || expression.kind === 'or') {
+    for (const subexpression of expression.expressions) {
+      collectExpressionDiagnostics(
+        subexpression,
+        diagnostics,
+        known_relation_names,
+        known_field_definitions,
+        diagnostic_path,
+      );
+    }
+
+    return;
+  }
+
+  if (expression.kind === 'not') {
+    collectExpressionDiagnostics(
+      expression.expression,
+      diagnostics,
+      known_relation_names,
+      known_field_definitions,
+      diagnostic_path,
+    );
+
+    return;
+  }
+
+  if (expression.kind === 'term') {
     collectTermDiagnostics(
-      clause.term,
+      expression.term,
       diagnostics,
       known_relation_names,
+      known_field_definitions,
       diagnostic_path,
     );
+
+    return;
   }
+
+  throw new Error('Unsupported query inspection expression.');
 }
 
 /**
  * @param {ParsedTerm} term
  * @param {PatramDiagnostic[]} diagnostics
  * @param {Set<string>} known_relation_names
+ * @param {Record<string, import('./load-patram-config.types.ts').MetadataFieldConfig>} known_field_definitions
  * @param {string} diagnostic_path
  */
 function collectTermDiagnostics(
   term,
   diagnostics,
   known_relation_names,
+  known_field_definitions,
   diagnostic_path,
 ) {
   if (term.kind === 'aggregate') {
@@ -203,10 +247,11 @@ function collectTermDiagnostics(
       known_relation_names,
       diagnostic_path,
     );
-    collectClauseDiagnostics(
-      term.clauses,
+    collectExpressionDiagnostics(
+      term.expression,
       diagnostics,
       known_relation_names,
+      known_field_definitions,
       diagnostic_path,
     );
 
@@ -233,7 +278,256 @@ function collectTermDiagnostics(
       diagnostic_path,
       'relation clause',
     );
+
+    return;
   }
+
+  collectFieldDiagnostics(
+    /** @type {FieldDiagnosticTerm} */ (term),
+    diagnostics,
+    known_field_definitions,
+    diagnostic_path,
+  );
+}
+
+/**
+ * @param {FieldDiagnosticTerm} term
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {Record<string, import('./load-patram-config.types.ts').MetadataFieldConfig>} known_field_definitions
+ * @param {string} diagnostic_path
+ */
+function collectFieldDiagnostics(
+  term,
+  diagnostics,
+  known_field_definitions,
+  diagnostic_path,
+) {
+  const field_diagnostics_collector = getFieldDiagnosticsCollector(
+    term.field_name,
+  );
+
+  if (field_diagnostics_collector) {
+    field_diagnostics_collector(term, diagnostics, diagnostic_path);
+    return;
+  }
+
+  if (term.field_name.startsWith('$')) {
+    diagnostics.push(
+      createQueryDiagnostic(
+        diagnostic_path,
+        term.column,
+        `Reserved field "${term.field_name}" is not available.`,
+        'query.reserved_field',
+      ),
+    );
+
+    return;
+  }
+
+  const field_definition = known_field_definitions[term.field_name];
+
+  if (!field_definition) {
+    diagnostics.push(
+      createQueryDiagnostic(
+        diagnostic_path,
+        term.column,
+        `Unknown field "${term.field_name}".`,
+        'query.unknown_field',
+      ),
+    );
+
+    return;
+  }
+
+  if (term.kind === 'field_set') {
+    if (term.operator === 'in' || term.operator === 'not in') {
+      return;
+    }
+  }
+
+  if (term.kind === 'field') {
+    const operator_diagnostic = getMetadataFieldOperatorDiagnostic(
+      term,
+      field_definition,
+      diagnostic_path,
+    );
+
+    if (operator_diagnostic) {
+      diagnostics.push(operator_diagnostic);
+    }
+  }
+}
+
+/**
+ * @param {string} field_name
+ * @returns {((term: FieldDiagnosticTerm, diagnostics: PatramDiagnostic[], diagnostic_path: string) => void) | null}
+ */
+function getFieldDiagnosticsCollector(field_name) {
+  if (field_name === 'title') {
+    return collectTitleFieldDiagnostics;
+  }
+
+  if (
+    field_name === '$id' ||
+    field_name === '$class' ||
+    field_name === '$path'
+  ) {
+    return collectStructuralFieldDiagnostics;
+  }
+
+  return null;
+}
+
+/**
+ * @param {FieldDiagnosticTerm} term
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {string} diagnostic_path
+ */
+function collectTitleFieldDiagnostics(term, diagnostics, diagnostic_path) {
+  const operator = term.kind === 'field' ? term.operator : term.operator;
+  const allowed = new Set(['=', '!=', 'in', 'not in', '~']);
+
+  if (allowed.has(operator)) {
+    return;
+  }
+
+  diagnostics.push(
+    createQueryDiagnostic(
+      diagnostic_path,
+      term.column,
+      `Field "title" does not support the "${operator}" operator.`,
+      'query.invalid_operator',
+    ),
+  );
+}
+
+/**
+ * @param {FieldDiagnosticTerm} term
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {string} 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', '^='])],
+  ]);
+  const allowed = allowed_by_field.get(term.field_name);
+
+  if (!allowed || allowed.has(operator)) {
+    return;
+  }
+
+  diagnostics.push(
+    createQueryDiagnostic(
+      diagnostic_path,
+      term.column,
+      `Field "${term.field_name}" does not support the "${operator}" operator.`,
+      'query.invalid_operator',
+    ),
+  );
+}
+
+/**
+ * @param {import('./parse-where-clause.types.ts').ParsedFieldTerm} term
+ * @param {import('./load-patram-config.types.ts').MetadataFieldConfig} field_definition
+ * @param {string} diagnostic_path
+ * @returns {PatramDiagnostic | null}
+ */
+function getMetadataFieldOperatorDiagnostic(
+  term,
+  field_definition,
+  diagnostic_path,
+) {
+  if (supportsMetadataFieldOperator(term.operator, field_definition)) {
+    return null;
+  }
+
+  return createQueryDiagnostic(
+    diagnostic_path,
+    term.column,
+    getUnsupportedOperatorMessage(term.field_name, term.operator),
+    'query.invalid_operator',
+  );
+}
+
+/**
+ * @param {string} operator
+ * @param {import('./load-patram-config.types.ts').MetadataFieldConfig} field_definition
+ * @returns {boolean}
+ */
+function supportsMetadataFieldOperator(operator, field_definition) {
+  if (operator === '=' || operator === '!=') {
+    return true;
+  }
+
+  if (operator === '^=') {
+    return supportsPrefixOperator(field_definition);
+  }
+
+  if (operator === '~') {
+    return supportsContainsOperator(field_definition);
+  }
+
+  return supportsOrderedComparison(operator, field_definition.type);
+}
+
+/**
+ * @param {import('./load-patram-config.types.ts').MetadataFieldConfig} 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
+  );
+}
+
+/**
+ * @param {import('./load-patram-config.types.ts').MetadataFieldConfig} field_definition
+ * @returns {boolean}
+ */
+function supportsContainsOperator(field_definition) {
+  return (
+    field_definition.type === 'string' &&
+    field_definition.query?.contains === true
+  );
+}
+
+/**
+ * @param {string} operator
+ * @param {string} field_type
+ * @returns {boolean}
+ */
+function supportsOrderedComparison(operator, field_type) {
+  if (
+    operator !== '<' &&
+    operator !== '<=' &&
+    operator !== '>' &&
+    operator !== '>='
+  ) {
+    return false;
+  }
+
+  return (
+    field_type === 'integer' ||
+    field_type === 'date' ||
+    field_type === 'date_time'
+  );
+}
+
+/**
+ * @param {string} field_name
+ * @param {string} operator
+ * @returns {string}
+ */
+function getUnsupportedOperatorMessage(field_name, operator) {
+  return `Field "${field_name}" does not support the "${operator}" operator.`;
 }
 
 /**
@@ -290,7 +584,6 @@ function collectTraversalDiagnostic(
 
 /**
  * @param {QueryInspectionSuccess} query_inspection
- * @returns {object}
  */
 function formatJsonQueryInspection(query_inspection) {
   if (query_inspection.inspection_mode === 'lint') {
@@ -303,9 +596,9 @@ function formatJsonQueryInspection(query_inspection) {
   }
 
   return {
-    clauses: query_inspection.clauses,
     diagnostics: [],
     execution: query_inspection.execution,
+    expression: query_inspection.expression,
     mode: 'explain',
     source: query_inspection.query_source,
     where: query_inspection.where_clause,
@@ -351,9 +644,12 @@ function renderTextQueryInspection(query_inspection, render_options) {
         : String(query_inspection.execution?.limit ?? ''),
     ),
     '',
-    `${render_options.label('clauses:')}`,
-    ...formatExplainClauseBlock(
-      query_inspection.clauses ?? [],
+    `${render_options.label('expression:')}`,
+    ...formatExplainExpressionBlock(
+      query_inspection.expression ?? {
+        expressions: [],
+        kind: 'and',
+      },
       render_options,
       '',
     ),
@@ -363,42 +659,49 @@ function renderTextQueryInspection(query_inspection, render_options) {
 }
 
 /**
- * @param {ParsedClause[]} clauses
+ * @param {ParsedExpression} expression
  * @param {{ header: (value: string) => string, label: (value: string) => string }} render_options
  * @param {string} indentation
  * @returns {string[]}
  */
-function formatExplainClauseBlock(clauses, render_options, indentation) {
-  /** @type {string[]} */
-  const output_lines = [];
+function formatExplainExpressionBlock(expression, render_options, indentation) {
+  if (expression.kind === 'and') {
+    return formatExplainExpressionItems(
+      expression.expressions,
+      render_options,
+      indentation,
+    );
+  }
 
-  clauses.forEach((clause, clause_index) => {
-    const clause_number = clause_index + 1;
-    const clause_text = formatClauseSummary(clause);
+  return formatExplainExpressionItems(
+    [expression],
+    render_options,
+    indentation,
+  );
+}
 
-    output_lines.push(`${indentation}${clause_number}. ${clause_text}`);
+/**
+ * @param {ParsedExpression[]} expressions
+ * @param {{ header: (value: string) => string, label: (value: string) => string }} render_options
+ * @param {string} indentation
+ * @returns {string[]}
+ */
+function formatExplainExpressionItems(
+  expressions,
+  render_options,
+  indentation,
+) {
+  /** @type {string[]} */
+  const output_lines = [];
 
-    if (clause.term.kind !== 'aggregate') {
-      return;
-    }
+  expressions.forEach((expression, expression_index) => {
+    const expression_number = expression_index + 1;
 
     output_lines.push(
-      `${indentation}   ${render_options.label('traversal:')} ${formatTraversal(clause.term.traversal)}`,
+      `${indentation}${expression_number}. ${formatExpressionSummary(expression)}`,
     );
-
-    if (clause.term.aggregate_name === 'count') {
-      output_lines.push(
-        `${indentation}   ${render_options.label('comparison:')} ${clause.term.comparison} ${clause.term.value}`,
-      );
-    }
-
     output_lines.push(
-      `${indentation}   ${render_options.label('nested clauses:')}`,
-      ...formatExplainClauseBlock(
-        clause.term.clauses,
-        render_options,
-        `${indentation}     `,
-      ),
+      ...formatExpressionDetailLines(expression, render_options, indentation),
     );
   });
 
@@ -406,17 +709,89 @@ function formatExplainClauseBlock(clauses, render_options, indentation) {
 }
 
 /**
- * @param {ParsedClause} clause
+ * @param {ParsedExpression} expression
  * @returns {string}
  */
-function formatClauseSummary(clause) {
-  const clause_prefix = clause.is_negated ? 'not ' : '';
+function formatExpressionSummary(expression) {
+  if (expression.kind === 'and') {
+    return 'all of';
+  }
+
+  if (expression.kind === 'or') {
+    return 'any of';
+  }
+
+  if (expression.kind === 'not') {
+    if (expression.expression.kind === 'term') {
+      return `not ${formatTermSummary(expression.expression.term)}`;
+    }
+
+    return 'not';
+  }
+
+  if (expression.kind === 'term') {
+    return formatTermSummary(expression.term);
+  }
+
+  throw new Error('Unsupported explain expression.');
+}
+
+/**
+ * @param {ParsedExpression} expression
+ * @param {{ header: (value: string) => string, label: (value: string) => string }} render_options
+ * @param {string} indentation
+ * @returns {string[]}
+ */
+function formatExpressionDetailLines(expression, render_options, indentation) {
+  if (expression.kind === 'and' || expression.kind === 'or') {
+    return formatExplainExpressionItems(
+      expression.expressions,
+      render_options,
+      `${indentation}   `,
+    );
+  }
+
+  if (expression.kind === 'not') {
+    if (expression.expression.kind === 'term') {
+      return [];
+    }
+
+    return formatExplainExpressionBlock(
+      expression.expression,
+      render_options,
+      `${indentation}   `,
+    );
+  }
+
+  if (expression.kind !== 'term') {
+    throw new Error('Unsupported explain expression details.');
+  }
+
+  if (expression.term.kind !== 'aggregate') {
+    return [];
+  }
+
+  /** @type {string[]} */
+  const output_lines = [
+    `${indentation}   ${render_options.label('traversal:')} ${formatTraversal(expression.term.traversal)}`,
+  ];
 
-  if (clause.term.kind === 'aggregate') {
-    return `${clause_prefix}aggregate ${clause.term.aggregate_name}`;
+  if (expression.term.aggregate_name === 'count') {
+    output_lines.push(
+      `${indentation}   ${render_options.label('comparison:')} ${expression.term.comparison} ${expression.term.value}`,
+    );
   }
 
-  return `${clause_prefix}${formatTermSummary(clause.term)}`;
+  output_lines.push(
+    `${indentation}   ${render_options.label('nested expression:')}`,
+    ...formatExplainExpressionBlock(
+      expression.term.expression,
+      render_options,
+      `${indentation}     `,
+    ),
+  );
+
+  return output_lines;
 }
 
 /**
@@ -424,6 +799,10 @@ function formatClauseSummary(clause) {
  * @returns {string}
  */
 function formatTermSummary(term) {
+  if (term.kind === 'aggregate') {
+    return `aggregate ${term.aggregate_name}`;
+  }
+
   if (term.kind === 'field') {
     return `${term.field_name} ${term.operator} ${term.value}`;
   }
@@ -440,7 +819,7 @@ function formatTermSummary(term) {
     return `${term.relation_name} = ${term.target_id}`;
   }
 
-  throw new Error('Expected a non-aggregate query term.');
+  throw new Error('Expected a parsed query term.');
 }
 
 /**
@@ -489,11 +868,12 @@ function formatQueryDiagnosticPath(query_source) {
  * @param {string} diagnostic_path
  * @param {number} column
  * @param {string} message
+ * @param {PatramDiagnostic['code']} [code]
  * @returns {PatramDiagnostic}
  */
-function createQueryDiagnostic(diagnostic_path, column, message) {
+function createQueryDiagnostic(diagnostic_path, column, message, code) {
   return {
-    code: 'query.unknown_relation',
+    code: code ?? 'query.unknown_relation',
     column,
     level: 'error',
     line: 1,