patram 0.2.0 → 0.3.0

package/lib/patram-config.js

@@ -5,13 +5,13 @@
 
 import { z } from 'zod';
 
-const KIND_NAME_SCHEMA = z.string().min(1);
+const CLASS_NAME_SCHEMA = z.string().min(1);
 const RELATION_NAME_SCHEMA = z.string().min(1);
 const CLAIM_TYPE_SCHEMA = z.string().min(1);
 const KEY_SOURCE_SCHEMA = z.enum(['path', 'value']);
 const TARGET_SCHEMA = z.enum(['path', 'value']);
 
-const kind_definition_schema = z
+const class_definition_schema = z
   .object({
     builtin: z.boolean().optional(),
     label: z.string().min(1).optional(),
@@ -21,16 +21,16 @@ const kind_definition_schema = z
 const relation_definition_schema = z
   .object({
     builtin: z.boolean().optional(),
-    from: z.array(KIND_NAME_SCHEMA).min(1),
-    to: z.array(KIND_NAME_SCHEMA).min(1),
+    from: z.array(CLASS_NAME_SCHEMA).min(1),
+    to: z.array(CLASS_NAME_SCHEMA).min(1),
   })
   .strict();
 
 const mapping_node_schema = z
   .object({
+    class: CLASS_NAME_SCHEMA,
     field: z.string().min(1),
     key: KEY_SOURCE_SCHEMA.optional(),
-    kind: KIND_NAME_SCHEMA,
   })
   .strict();
 
@@ -38,7 +38,7 @@ const mapping_emit_schema = z
   .object({
     relation: RELATION_NAME_SCHEMA,
     target: TARGET_SCHEMA,
-    target_kind: KIND_NAME_SCHEMA,
+    target_class: CLASS_NAME_SCHEMA,
   })
   .strict();
 
@@ -53,7 +53,7 @@ const mapping_definition_schema = z
 export const patramConfigSchema = z
   .object({
     $schema: z.url().optional(),
-    kinds: z.record(KIND_NAME_SCHEMA, kind_definition_schema),
+    classes: z.record(CLASS_NAME_SCHEMA, class_definition_schema),
     mappings: z.record(CLAIM_TYPE_SCHEMA, mapping_definition_schema),
     relations: z.record(RELATION_NAME_SCHEMA, relation_definition_schema),
   })
@@ -90,8 +90,8 @@ function validateMappingDefinition(mapping_definition, refinement_context) {
  * @param {RefinementCtx} refinement_context
  */
 function validatePatramConfigReferences(config_json, refinement_context) {
-  validateRelationKinds(config_json, refinement_context);
-  validateMappingKinds(config_json, refinement_context);
+  validateRelationClasses(config_json, refinement_context);
+  validateMappingClasses(config_json, refinement_context);
   validateMappingRelations(config_json, refinement_context);
 }
 
@@ -99,19 +99,19 @@ function validatePatramConfigReferences(config_json, refinement_context) {
  * @param {PatramConfig} config_json
  * @param {RefinementCtx} refinement_context
  */
-function validateRelationKinds(config_json, refinement_context) {
+function validateRelationClasses(config_json, refinement_context) {
   for (const [relation_name, relation_definition] of Object.entries(
     config_json.relations,
   )) {
-    validateReferencedKinds(
+    validateReferencedClasses(
       relation_definition.from,
-      config_json.kinds,
+      config_json.classes,
       ['relations', relation_name, 'from'],
       refinement_context,
     );
-    validateReferencedKinds(
+    validateReferencedClasses(
       relation_definition.to,
-      config_json.kinds,
+      config_json.classes,
       ['relations', relation_name, 'to'],
       refinement_context,
     );
@@ -122,24 +122,24 @@ function validateRelationKinds(config_json, refinement_context) {
  * @param {PatramConfig} config_json
  * @param {RefinementCtx} refinement_context
  */
-function validateMappingKinds(config_json, refinement_context) {
+function validateMappingClasses(config_json, refinement_context) {
   for (const [mapping_name, mapping_definition] of Object.entries(
     config_json.mappings,
   )) {
     if (mapping_definition.emit) {
-      validateReferencedKinds(
-        [mapping_definition.emit.target_kind],
-        config_json.kinds,
-        ['mappings', mapping_name, 'emit', 'target_kind'],
+      validateReferencedClasses(
+        [mapping_definition.emit.target_class],
+        config_json.classes,
+        ['mappings', mapping_name, 'emit', 'target_class'],
         refinement_context,
       );
     }
 
     if (mapping_definition.node) {
-      validateReferencedKinds(
-        [mapping_definition.node.kind],
-        config_json.kinds,
-        ['mappings', mapping_name, 'node', 'kind'],
+      validateReferencedClasses(
+        [mapping_definition.node.class],
+        config_json.classes,
+        ['mappings', mapping_name, 'node', 'class'],
         refinement_context,
       );
     }
@@ -171,25 +171,25 @@ function validateMappingRelations(config_json, refinement_context) {
 }
 
 /**
- * @param {string[]} referenced_kinds
- * @param {Record<string, unknown>} known_kinds
+ * @param {string[]} referenced_classes
+ * @param {Record<string, unknown>} known_classes
  * @param {(string | number)[]} issue_path
  * @param {RefinementCtx} refinement_context
  */
-function validateReferencedKinds(
-  referenced_kinds,
-  known_kinds,
+function validateReferencedClasses(
+  referenced_classes,
+  known_classes,
   issue_path,
   refinement_context,
 ) {
-  for (const referenced_kind of referenced_kinds) {
-    if (known_kinds[referenced_kind]) {
+  for (const referenced_class of referenced_classes) {
+    if (known_classes[referenced_class]) {
       continue;
     }
 
     refinement_context.addIssue({
       code: 'custom',
-      message: `Unknown kind "${referenced_kind}".`,
+      message: `Unknown class "${referenced_class}".`,
       path: issue_path,
     });
   }

package/lib/patram-config.types.ts

@@ -1,4 +1,4 @@
-export interface KindDefinition {
+export interface ClassDefinition {
   builtin?: boolean;
   label?: string;
 }
@@ -10,15 +10,15 @@ export interface RelationDefinition {
 }
 
 export interface MappingNodeDefinition {
+  class: string;
   field: string;
   key?: 'path' | 'value';
-  kind: string;
 }
 
 export interface MappingEmitDefinition {
   relation: string;
   target: 'path' | 'value';
-  target_kind: string;
+  target_class: string;
 }
 
 export interface MappingDefinition {
@@ -28,7 +28,13 @@ export interface MappingDefinition {
 
 export interface PatramConfig {
   $schema?: string;
-  kinds: Record<string, KindDefinition>;
+  classes: Record<string, ClassDefinition>;
+  class_schemas?: Record<string, ClassSchemaConfig>;
+  fields?: Record<string, MetadataFieldConfig>;
   mappings: Record<string, MappingDefinition>;
   relations: Record<string, RelationDefinition>;
 }
+import type {
+  ClassSchemaConfig,
+  MetadataFieldConfig,
+} from './load-patram-config.types.ts';

package/lib/query-graph.js

@@ -1,7 +1,7 @@
 /* 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,
@@ -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,6 +75,25 @@ 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.clauses,
+    );
+
+    if (diagnostics.length > 0) {
+      return {
+        diagnostics,
+        nodes: [],
+        total_count: 0,
+      };
+    }
+  }
+
   const evaluation_context = {
     nodes: graph.nodes,
     relation_indexes: createRelationIndexes(graph.edges),
@@ -76,7 +102,10 @@ export function queryGraph(graph, where_clause, pagination_options = {}) {
   const matching_nodes = graph_nodes.filter((graph_node) =>
     matchesClauses(graph_node, parse_result.clauses, evaluation_context),
   );
-  const paginated_nodes = paginateNodes(matching_nodes, pagination_options);
+  const paginated_nodes = paginateNodes(
+    matching_nodes,
+    resolved_pagination_options,
+  );
 
   return {
     diagnostics: [],
@@ -176,29 +205,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 +258,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 +402,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 +419,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;
+}