patram 0.11.0 → 0.12.0

package/lib/config/validation.js

@@ -1,26 +1,19 @@
 /**
- * @import { ClassDefinition } from './patram-config.js';
- * @import {
- *   DerivedSummaryFieldConfig,
- *   MetadataFieldConfig,
- *   PatramRepoConfig,
- * } from './schema.js';
- * @import { PatramDiagnostic } from './load-patram-config.js';
+ * @import { MetadataFieldConfig, PatramRepoConfig, PatramDiagnostic } from './load-patram-config.types.ts';
  */
-/* eslint-disable max-lines */
 
-import { z } from 'zod';
-
-import { parsePatramConfig } from './patram-config.js';
+import { CONFIG_FILE_NAME, isReservedStructuralFieldName } from './schema.js';
 import { getQuerySemanticDiagnostics } from '../graph/query/inspect.js';
-import { parseWhereClause } from '../graph/query/parse.js';
-import { resolvePatramGraphConfig } from './resolve-patram-graph-config.js';
-import {
-  CONFIG_FILE_NAME,
-  isKnownMarkdownStyle,
-  isMixedStyleValue,
-  isReservedStructuralFieldName,
-} from './schema.js';
+import { parseQueryExpression } from '../graph/query/parse-query.js';
+
+const LEGACY_TOP_LEVEL_KEYS = {
+  class_schemas:
+    'Top-level "class_schemas" is not supported. Use "types" and field rules.',
+  classes: 'Top-level "classes" is not supported. Use "types".',
+  mappings: 'Top-level "mappings" is not supported.',
+  path_classes: 'Top-level "path_classes" is not supported.',
+  relations: 'Top-level "relations" is not supported. Use ref fields.',
+};
 
 /**
  * @param {unknown} config_value
@@ -30,47 +23,23 @@ export function validateLegacyConfigShape(config_value) {
   if (
     config_value === null ||
     typeof config_value !== 'object' ||
-    !Object.hasOwn(config_value, 'class_schemas')
+    Array.isArray(config_value)
   ) {
     return [];
   }
 
-  return [
-    createConfigDiagnostic(
-      'class_schemas',
-      'Top-level "class_schemas" is not supported. Move entries into classes.<name>.schema.',
-    ),
-  ];
-}
-
-/**
- * @param {PatramRepoConfig} repo_config
- * @returns {PatramDiagnostic[]}
- */
-export function validateGraphSchema(repo_config) {
-  if (
-    repo_config.classes === undefined &&
-    repo_config.mappings === undefined &&
-    repo_config.relations === undefined
-  ) {
-    return [];
-  }
+  /** @type {PatramDiagnostic[]} */
+  const diagnostics = [];
 
-  try {
-    parsePatramConfig({
-      classes: collectGraphClassDefinitions(repo_config.classes),
-      mappings: repo_config.mappings ?? {},
-      relations: repo_config.relations ?? {},
-    });
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      return error.issues.map(createValidationDiagnostic);
+  for (const [legacy_key, message] of Object.entries(LEGACY_TOP_LEVEL_KEYS)) {
+    if (!Object.hasOwn(config_value, legacy_key)) {
+      continue;
     }
 
-    throw error;
+    diagnostics.push(createConfigDiagnostic(legacy_key, message));
   }
 
-  return [];
+  return diagnostics;
 }
 
 /**
@@ -78,19 +47,22 @@ export function validateGraphSchema(repo_config) {
  * @returns {PatramDiagnostic[]}
  */
 export function validateFieldSchemaConfig(repo_config) {
-  const path_classes = repo_config.path_classes ?? {};
-  const classes = repo_config.classes ?? {};
   const fields = repo_config.fields ?? {};
+  const types = repo_config.types ?? {};
   /** @type {PatramDiagnostic[]} */
   const diagnostics = [];
 
-  collectFieldConfigDiagnostics(diagnostics, path_classes, fields);
-  collectClassSchemaConfigDiagnostics(
-    diagnostics,
-    path_classes,
-    fields,
-    classes,
-  );
+  for (const [field_name, field_definition] of Object.entries(fields)) {
+    diagnostics.push(
+      ...validateFieldDefinition(field_name, field_definition, types),
+    );
+  }
+
+  for (const [type_name, type_definition] of Object.entries(types)) {
+    diagnostics.push(
+      ...validateTypeDefinition(type_name, type_definition, fields),
+    );
+  }
 
   return diagnostics;
 }
@@ -106,510 +78,180 @@ export function validateStoredQueries(repo_config) {
   for (const [query_name, stored_query] of Object.entries(
     repo_config.queries,
   )) {
-    collectWhereClauseDiagnostics(
-      diagnostics,
-      repo_config,
-      stored_query.where,
-      `queries.${query_name}.where`,
-    );
-  }
+    const query_text = stored_query.cypher;
 
-  return diagnostics;
-}
-
-/**
- * @param {PatramRepoConfig} repo_config
- * @returns {PatramDiagnostic[]}
- */
-export function validateDerivedSummaries(repo_config) {
-  if (!repo_config.derived_summaries) {
-    return [];
-  }
-
-  const graph_config = resolvePatramGraphConfig(repo_config);
-  const known_relation_names = new Set(Object.keys(graph_config.relations));
-  /** @type {PatramDiagnostic[]} */
-  const diagnostics = [];
-  /** @type {Map<string, string>} */
-  const class_coverage = new Map();
+    if (!query_text) {
+      continue;
+    }
 
-  for (const [summary_name, summary_definition] of Object.entries(
-    repo_config.derived_summaries,
-  )) {
-    collectDuplicateClassDiagnostics(
-      diagnostics,
-      class_coverage,
-      summary_definition.classes,
-      summary_name,
-    );
-    collectDerivedSummaryFieldDiagnostics(
+    collectWhereClauseDiagnostics(
       diagnostics,
-      known_relation_names,
       repo_config,
-      summary_name,
-      summary_definition.fields,
+      query_text,
+      `queries.${query_name}.cypher`,
     );
   }
 
   return diagnostics;
 }
 
-/**
- * @param {import('zod').core.$ZodIssue} issue
- * @returns {PatramDiagnostic}
- */
-function createValidationDiagnostic(issue) {
-  const issue_path = formatIssuePath(issue.path);
-
-  if (issue_path) {
-    return {
-      code: 'config.invalid',
-      column: 1,
-      level: 'error',
-      line: 1,
-      message: `Invalid config at "${issue_path}": ${issue.message}`,
-      path: CONFIG_FILE_NAME,
-    };
-  }
-
-  return {
-    code: 'config.invalid',
-    column: 1,
-    level: 'error',
-    line: 1,
-    message: `Invalid config: ${issue.message}`,
-    path: CONFIG_FILE_NAME,
-  };
-}
-
 /**
  * @param {PatramDiagnostic[]} diagnostics
- * @param {Map<string, string>} class_coverage
- * @param {string[]} class_names
- * @param {string} summary_name
+ * @param {string} field_path
+ * @param {string[] | undefined} referenced_types
+ * @param {NonNullable<PatramRepoConfig['types']>} types
  */
-function collectDuplicateClassDiagnostics(
+function collectTypeReferenceDiagnostics(
   diagnostics,
-  class_coverage,
-  class_names,
-  summary_name,
+  field_path,
+  referenced_types,
+  types,
 ) {
-  for (const class_name of class_names) {
-    const existing_summary_name = class_coverage.get(class_name);
-
-    if (!existing_summary_name) {
-      class_coverage.set(class_name, summary_name);
+  for (const referenced_type of referenced_types ?? []) {
+    if (types[referenced_type] !== undefined) {
       continue;
     }
 
     diagnostics.push(
-      createConfigDiagnostic(
-        `derived_summaries.${summary_name}.classes`,
-        `Class "${class_name}" is already covered by derived summary "${existing_summary_name}".`,
-      ),
+      createConfigDiagnostic(field_path, `Unknown type "${referenced_type}".`),
     );
   }
 }
 
 /**
  * @param {PatramDiagnostic[]} diagnostics
- * @param {Set<string>} known_relation_names
  * @param {PatramRepoConfig} repo_config
- * @param {string} summary_name
- * @param {DerivedSummaryFieldConfig[]} field_definitions
- */
-function collectDerivedSummaryFieldDiagnostics(
-  diagnostics,
-  known_relation_names,
-  repo_config,
-  summary_name,
-  field_definitions,
-) {
-  for (const [field_index, field_definition] of field_definitions.entries()) {
-    if ('count' in field_definition) {
-      collectTraversalDiagnostic(
-        diagnostics,
-        field_definition.count.traversal,
-        known_relation_names,
-        `derived_summaries.${summary_name}.fields.${field_index}.count.traversal`,
-      );
-      collectWhereClauseDiagnostics(
-        diagnostics,
-        repo_config,
-        field_definition.count.where,
-        `derived_summaries.${summary_name}.fields.${field_index}.count.where`,
-      );
-      continue;
-    }
-
-    for (const [case_index, select_case] of field_definition.select.entries()) {
-      collectWhereClauseDiagnostics(
-        diagnostics,
-        repo_config,
-        select_case.when,
-        `derived_summaries.${summary_name}.fields.${field_index}.select.${case_index}.when`,
-      );
-    }
-  }
-}
-
-/**
- * @param {PatramDiagnostic[]} diagnostics
- * @param {string} traversal_text
- * @param {Set<string>} known_relation_names
+ * @param {string} where_clause
  * @param {string} diagnostic_path
  */
-function collectTraversalDiagnostic(
+function collectWhereClauseDiagnostics(
   diagnostics,
-  traversal_text,
-  known_relation_names,
+  repo_config,
+  where_clause,
   diagnostic_path,
 ) {
-  const traversal_match =
-    /^(?<direction>in|out):(?<relation_name>[a-zA-Z0-9_]+)$/du.exec(
-      traversal_text,
-    );
+  const parse_result = parseQueryExpression(where_clause, repo_config);
 
-  if (!traversal_match?.groups?.relation_name) {
-    diagnostics.push(
-      createConfigDiagnostic(
-        diagnostic_path,
-        'Derived summary traversal must use "in:<relation>" or "out:<relation>".',
-      ),
-    );
-
-    return;
-  }
-
-  if (known_relation_names.has(traversal_match.groups.relation_name)) {
+  if (!parse_result.success) {
+    diagnostics.push(replaceDiagnosticPath(parse_result.diagnostic));
     return;
   }
 
   diagnostics.push(
-    createConfigDiagnostic(
-      diagnostic_path,
-      `Unknown relation "${traversal_match.groups.relation_name}" in derived summary traversal.`,
-    ),
-  );
-}
-
-/**
- * @param {PatramDiagnostic[]} diagnostics
- * @param {Record<string, { prefixes: string[] }>} path_classes
- * @param {Record<string, MetadataFieldConfig>} fields
- */
-function collectFieldConfigDiagnostics(diagnostics, path_classes, fields) {
-  for (const [field_name, field_definition] of Object.entries(fields)) {
-    if (collectReservedFieldDiagnostic(diagnostics, field_name)) {
-      continue;
-    }
-
-    collectDisplayOrderDiagnostic(diagnostics, field_name, field_definition);
-    collectFieldPathClassDiagnostic(
-      diagnostics,
-      path_classes,
-      field_name,
-      field_definition,
-    );
-  }
-}
-
-/**
- * @param {PatramDiagnostic[]} diagnostics
- * @param {string} field_name
- * @returns {boolean}
- */
-function collectReservedFieldDiagnostic(diagnostics, field_name) {
-  if (
-    !field_name.startsWith('$') ||
-    !isReservedStructuralFieldName(field_name)
-  ) {
-    return false;
-  }
-
-  diagnostics.push(
-    createConfigDiagnostic(
-      `fields.${field_name}`,
-      'Metadata field names must not start with "$".',
+    ...getQuerySemanticDiagnostics(
+      repo_config,
+      { kind: 'stored_query', name: diagnostic_path.split('.')[1] ?? '' },
+      parse_result.expression,
     ),
   );
-
-  return true;
 }
 
 /**
- * @param {PatramDiagnostic[]} diagnostics
- * @param {string} field_name
- * @param {MetadataFieldConfig} field_definition
+ * @param {string} path
+ * @param {string} message
+ * @returns {PatramDiagnostic}
  */
-function collectDisplayOrderDiagnostic(
-  diagnostics,
-  field_name,
-  field_definition,
-) {
-  if (
-    field_definition.display?.order === undefined ||
-    (Number.isInteger(field_definition.display.order) &&
-      field_definition.display.order >= 0)
-  ) {
-    return;
-  }
-
-  diagnostics.push(
-    createConfigDiagnostic(
-      `fields.${field_name}.display.order`,
-      'Display order must be a non-negative integer.',
-    ),
-  );
+function createConfigDiagnostic(path, message) {
+  return {
+    code: 'config.invalid',
+    column: 1,
+    level: 'error',
+    line: 1,
+    message: `Invalid config at "${path}": ${message}`,
+    path: CONFIG_FILE_NAME,
+  };
 }
 
 /**
- * @param {PatramDiagnostic[]} diagnostics
- * @param {Record<string, { prefixes: string[] }>} path_classes
  * @param {string} field_name
  * @param {MetadataFieldConfig} field_definition
+ * @param {NonNullable<PatramRepoConfig['types']>} types
+ * @returns {PatramDiagnostic[]}
  */
-function collectFieldPathClassDiagnostic(
-  diagnostics,
-  path_classes,
-  field_name,
-  field_definition,
-) {
-  if (
-    !('path_class' in field_definition) ||
-    field_definition.path_class === undefined
-  ) {
-    return;
-  }
+function validateFieldDefinition(field_name, field_definition, types) {
+  /** @type {PatramDiagnostic[]} */
+  const diagnostics = [];
 
-  if (field_definition.type !== 'path') {
+  if (isReservedStructuralFieldName(field_name)) {
     diagnostics.push(
       createConfigDiagnostic(
-        `fields.${field_name}.path_class`,
-        'Path classes are only valid for path fields.',
+        `fields.${field_name}`,
+        'Metadata field names must not start with "$".',
       ),
     );
-
-    return;
   }
 
-  if (path_classes[field_definition.path_class]) {
-    return;
-  }
-
-  diagnostics.push(
-    createConfigDiagnostic(
-      `fields.${field_name}.path_class`,
-      `Unknown path class "${field_definition.path_class}".`,
-    ),
+  collectTypeReferenceDiagnostics(
+    diagnostics,
+    `fields.${field_name}.on`,
+    field_definition.on,
+    types,
+  );
+  collectTypeReferenceDiagnostics(
+    diagnostics,
+    `fields.${field_name}.required_on`,
+    field_definition.required_on,
+    types,
   );
-}
-
-/**
- * @param {PatramDiagnostic[]} diagnostics
- * @param {Record<string, { prefixes: string[] }>} path_classes
- * @param {Record<string, MetadataFieldConfig>} fields
- * @param {NonNullable<PatramRepoConfig['classes']>} classes
- */
-function collectClassSchemaConfigDiagnostics(
-  diagnostics,
-  path_classes,
-  fields,
-  classes,
-) {
-  for (const [class_name, class_definition] of Object.entries(classes)) {
-    const schema_definition = class_definition.schema;
-
-    if (!schema_definition) {
-      continue;
-    }
-
-    collectMarkdownStylesDiagnostic(
-      diagnostics,
-      `classes.${class_name}.schema.markdown_styles`,
-      schema_definition.markdown_styles,
-    );
-    collectMixedStylesDiagnostic(
-      diagnostics,
-      `classes.${class_name}.schema.mixed_styles`,
-      schema_definition.mixed_styles,
-    );
-
-    for (const field_name of Object.keys(schema_definition.fields)) {
-      if (fields[field_name]) {
-        collectMarkdownStylesDiagnostic(
-          diagnostics,
-          `classes.${class_name}.schema.fields.${field_name}.markdown_styles`,
-          schema_definition.fields[field_name].markdown_styles,
-        );
-      } else {
-        diagnostics.push(
-          createConfigDiagnostic(
-            `classes.${class_name}.schema.fields.${field_name}`,
-            `Unknown field "${field_name}".`,
-          ),
-        );
-      }
-    }
-  }
-
-  for (const [class_name, class_definition] of Object.entries(classes)) {
-    const schema_definition = class_definition.schema;
-
-    if (!schema_definition) {
-      continue;
-    }
-
-    if (
-      schema_definition.document_path_class === undefined ||
-      path_classes[schema_definition.document_path_class]
-    ) {
-      continue;
-    }
 
+  if (
+    field_definition.type === 'ref' &&
+    field_definition.to !== 'document' &&
+    types[field_definition.to] === undefined
+  ) {
     diagnostics.push(
       createConfigDiagnostic(
-        `classes.${class_name}.schema.document_path_class`,
-        `Unknown path class "${schema_definition.document_path_class}".`,
+        `fields.${field_name}.to`,
+        `Unknown target type "${field_definition.to}".`,
       ),
     );
   }
+
+  return diagnostics;
 }
 
 /**
- * @param {PatramDiagnostic[]} diagnostics
- * @param {string} diagnostic_path
- * @param {string[] | undefined} markdown_styles
+ * @param {string} type_name
+ * @param {NonNullable<PatramRepoConfig['types']>[string]} type_definition
+ * @param {NonNullable<PatramRepoConfig['fields']>} fields
+ * @returns {PatramDiagnostic[]}
  */
-function collectMarkdownStylesDiagnostic(
-  diagnostics,
-  diagnostic_path,
-  markdown_styles,
-) {
-  if (markdown_styles === undefined) {
-    return;
-  }
-
-  if (markdown_styles.length === 0) {
-    diagnostics.push(
+function validateTypeDefinition(type_name, type_definition, fields) {
+  if (
+    type_definition.defined_by !== undefined &&
+    fields[type_definition.defined_by] === undefined
+  ) {
+    return [
       createConfigDiagnostic(
-        diagnostic_path,
-        'Markdown styles must contain at least one style.',
+        `types.${type_name}.defined_by`,
+        `Unknown field "${type_definition.defined_by}".`,
       ),
-    );
-
-    return;
+    ];
   }
 
-  for (const markdown_style of markdown_styles) {
-    if (isKnownMarkdownStyle(markdown_style)) {
-      continue;
-    }
-
-    diagnostics.push(
-      createConfigDiagnostic(
-        diagnostic_path,
-        `Unknown markdown style "${markdown_style}".`,
-      ),
-    );
-  }
-}
+  const defined_by_field = type_definition.defined_by
+    ? fields[type_definition.defined_by]
+    : undefined;
 
-/**
- * @param {PatramDiagnostic[]} diagnostics
- * @param {string} diagnostic_path
- * @param {string | undefined} mixed_styles
- */
-function collectMixedStylesDiagnostic(
-  diagnostics,
-  diagnostic_path,
-  mixed_styles,
-) {
-  if (mixed_styles === undefined || isMixedStyleValue(mixed_styles)) {
-    return;
+  if (defined_by_field?.type !== 'ref') {
+    return [];
   }
 
-  diagnostics.push(
+  return [
     createConfigDiagnostic(
-      diagnostic_path,
-      'Mixed styles must be "ignore" or "error".',
+      `types.${type_name}.defined_by`,
+      'Type identity fields must use a scalar field type.',
     ),
-  );
-}
-
-/**
- * @param {PatramRepoConfig['classes']} classes
- * @returns {Record<string, ClassDefinition>}
- */
-function collectGraphClassDefinitions(classes) {
-  /** @type {Record<string, ClassDefinition>} */
-  const graph_class_definitions = {};
-
-  for (const [class_name, class_definition] of Object.entries(classes ?? {})) {
-    graph_class_definitions[class_name] = {
-      builtin: class_definition.builtin,
-      label: class_definition.label,
-    };
-  }
-
-  return graph_class_definitions;
-}
-
-/**
- * @param {PatramDiagnostic[]} diagnostics
- * @param {PatramRepoConfig} repo_config
- * @param {string} where_clause
- * @param {string} diagnostic_path
- */
-function collectWhereClauseDiagnostics(
-  diagnostics,
-  repo_config,
-  where_clause,
-  diagnostic_path,
-) {
-  const parse_result = parseWhereClause(where_clause);
-
-  if (!parse_result.success) {
-    diagnostics.push(
-      createConfigDiagnostic(diagnostic_path, parse_result.diagnostic.message),
-    );
-
-    return;
-  }
-
-  const semantic_diagnostics = getQuerySemanticDiagnostics(
-    repo_config,
-    { kind: 'ad_hoc' },
-    parse_result.expression,
-  );
-
-  for (const semantic_diagnostic of semantic_diagnostics) {
-    diagnostics.push(
-      createConfigDiagnostic(diagnostic_path, semantic_diagnostic.message),
-    );
-  }
+  ];
 }
 
 /**
- * @param {string} issue_path
- * @param {string} message
+ * @param {PatramDiagnostic} diagnostic
  * @returns {PatramDiagnostic}
  */
-function createConfigDiagnostic(issue_path, message) {
+function replaceDiagnosticPath(diagnostic) {
   return {
-    code: 'config.invalid',
-    column: 1,
-    level: 'error',
-    line: 1,
-    message: `Invalid config at "${issue_path}": ${message}`,
+    ...diagnostic,
     path: CONFIG_FILE_NAME,
   };
 }
-
-/**
- * @param {(string | number | symbol | undefined)[]} issue_path
- * @returns {string}
- */
-function formatIssuePath(issue_path) {
-  return issue_path.map(String).join('.');
-}