patram 0.2.0 → 0.3.0

package/lib/load-patram-config.js

@@ -1,6 +1,12 @@
 /* eslint-disable max-lines */
 /**
- * @import { LoadPatramConfigResult, PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
+ * @import {
+ *   ClassSchemaConfig,
+ *   LoadPatramConfigResult,
+ *   MetadataFieldConfig,
+ *   PatramDiagnostic,
+ *   PatramRepoConfig,
+ * } from './load-patram-config.types.ts';
  */
 
 import { readFile } from 'node:fs/promises';
@@ -11,6 +17,7 @@ import { z } from 'zod';
 
 import { parsePatramConfig } from './patram-config.js';
 import { parseWhereClause } from './parse-where-clause.js';
+import { getQuerySemanticDiagnostics } from './query-inspection.js';
 import { resolvePatramGraphConfig } from './resolve-patram-graph-config.js';
 import { DEFAULT_INCLUDE_PATTERNS } from './source-file-defaults.js';
 
@@ -31,6 +38,7 @@ import { DEFAULT_INCLUDE_PATTERNS } from './source-file-defaults.js';
  */
 
 const CONFIG_FILE_NAME = '.patram.json';
+const RESERVED_STRUCTURAL_FIELD_NAMES = new Set(['$class', '$id', '$path']);
 
 const stored_query_schema = z
   .object({
@@ -80,31 +88,126 @@ const derived_summary_field_schema = z
 
 const derived_summary_schema = z
   .object({
+    classes: z
+      .array(z.string().min(1))
+      .min(1, 'Derived summary "classes" must contain at least one class.'),
     fields: z
       .array(derived_summary_field_schema)
       .min(1, 'Derived summary "fields" must contain at least one field.'),
-    kinds: z
-      .array(z.string().min(1))
-      .min(1, 'Derived summary "kinds" must contain at least one kind.'),
   })
   .strict()
   .superRefine(validateDerivedSummaryDefinition);
 
+const field_display_schema = z
+  .object({
+    hidden: z.boolean().optional(),
+    order: z.number().optional(),
+  })
+  .strict();
+
+const field_query_schema = z
+  .object({
+    contains: z.boolean().optional(),
+    prefix: z.boolean().optional(),
+  })
+  .strict();
+
+const field_base_shape = {
+  display: field_display_schema.optional(),
+  multiple: z.boolean().optional(),
+  path_class: z.string().min(1).optional(),
+};
+
+const metadata_field_schema = z.discriminatedUnion('type', [
+  z
+    .object({
+      ...field_base_shape,
+      query: field_query_schema.optional(),
+      type: z.literal('string'),
+    })
+    .strict(),
+  z
+    .object({
+      ...field_base_shape,
+      type: z.literal('integer'),
+    })
+    .strict(),
+  z
+    .object({
+      ...field_base_shape,
+      type: z.literal('enum'),
+      values: z
+        .array(z.string().min(1, 'Field enum values must not be empty.'))
+        .min(1, 'Field enum values must contain at least one value.'),
+    })
+    .strict(),
+  z
+    .object({
+      ...field_base_shape,
+      type: z.literal('path'),
+    })
+    .strict(),
+  z
+    .object({
+      ...field_base_shape,
+      type: z.literal('glob'),
+    })
+    .strict(),
+  z
+    .object({
+      ...field_base_shape,
+      type: z.literal('date'),
+    })
+    .strict(),
+  z
+    .object({
+      ...field_base_shape,
+      type: z.literal('date_time'),
+    })
+    .strict(),
+]);
+
+const class_field_rule_schema = z
+  .object({
+    presence: z.enum(['required', 'optional', 'forbidden']),
+  })
+  .strict();
+
+const class_schema_schema = z
+  .object({
+    document_path_class: z.string().min(1).optional(),
+    fields: z.record(z.string().min(1), class_field_rule_schema).default({}),
+    unknown_fields: z.enum(['ignore', 'error']).optional(),
+  })
+  .strict();
+
+const path_class_schema = z
+  .object({
+    prefixes: z
+      .array(z.string().min(1, 'Path class prefixes must not be empty.'))
+      .min(1, 'Path classes must contain at least one prefix.'),
+  })
+  .strict();
+
 const patram_repo_config_schema = z
   .object({
+    class_schemas: z.record(z.string().min(1), class_schema_schema).optional(),
+    classes: z.unknown().optional(),
     derived_summaries: z
       .record(z.string().min(1), derived_summary_schema)
       .optional(),
+    fields: z.record(z.string().min(1), metadata_field_schema).optional(),
     include: z
       .array(z.string().min(1, 'Include globs must not be empty.'))
       .min(1, 'Include must contain at least one glob.')
       .default(DEFAULT_INCLUDE_PATTERNS),
-    kinds: z.unknown().optional(),
     mappings: z.unknown().optional(),
+    path_classes: z.record(z.string().min(1), path_class_schema).optional(),
     queries: z.record(z.string().min(1), stored_query_schema).default({}),
     relations: z.unknown().optional(),
   })
-  .strict();
+  .strict()
+  .superRefine(validateFieldDefinitionKeys);
 
 /**
  * Load and validate the repo Patram config.
@@ -142,6 +245,18 @@ export async function loadPatramConfig(project_directory = process.cwd()) {
   }
 
   const normalized_config = normalizeRepoConfig(config_result.data);
+  const field_schema_diagnostics = validateFieldSchemaConfig(normalized_config);
+
+  if (field_schema_diagnostics.length > 0) {
+    return createLoadResult(null, field_schema_diagnostics);
+  }
+
+  const stored_query_diagnostics = validateStoredQueries(normalized_config);
+
+  if (stored_query_diagnostics.length > 0) {
+    return createLoadResult(null, stored_query_diagnostics);
+  }
+
   const derived_summary_diagnostics =
     validateDerivedSummaries(normalized_config);
 
@@ -249,6 +364,24 @@ function createValidationDiagnostic(issue) {
   };
 }
 
+/**
+ * @param {{ fields?: Record<string, MetadataFieldConfig> }} repo_config
+ * @param {import('zod').RefinementCtx} refinement_context
+ */
+function validateFieldDefinitionKeys(repo_config, refinement_context) {
+  for (const field_name of Object.keys(repo_config.fields ?? {})) {
+    if (!field_name.startsWith('$')) {
+      continue;
+    }
+
+    refinement_context.addIssue({
+      code: 'custom',
+      message: 'Metadata field names must not start with "$".',
+      path: ['fields', field_name],
+    });
+  }
+}
+
 /**
  * @param {{ count?: unknown, default?: unknown, select?: unknown }} field_definition
  * @param {import('zod').RefinementCtx} refinement_context
@@ -332,12 +465,12 @@ function validateDerivedSummaryDefinition(
 }
 
 /**
- * @param {{ include: string[], queries: Record<string, { where: string }>, kinds?: unknown, mappings?: unknown, relations?: unknown }} repo_config
+ * @param {{ include: string[], queries: Record<string, { where: string }>, classes?: unknown, mappings?: unknown, relations?: unknown }} repo_config
  * @returns {PatramDiagnostic[]}
  */
 function validateGraphSchema(repo_config) {
   if (
-    repo_config.kinds === undefined &&
+    repo_config.classes === undefined &&
     repo_config.mappings === undefined &&
     repo_config.relations === undefined
   ) {
@@ -346,7 +479,7 @@ function validateGraphSchema(repo_config) {
 
   try {
     parsePatramConfig({
-      kinds: repo_config.kinds ?? {},
+      classes: repo_config.classes ?? {},
       mappings: repo_config.mappings ?? {},
       relations: repo_config.relations ?? {},
     });
@@ -361,6 +494,51 @@ function validateGraphSchema(repo_config) {
   return [];
 }
 
+/**
+ * @param {PatramRepoConfig} repo_config
+ * @returns {PatramDiagnostic[]}
+ */
+function validateFieldSchemaConfig(repo_config) {
+  const path_classes = repo_config.path_classes ?? {};
+  const classes = repo_config.classes ?? {};
+  const fields = repo_config.fields ?? {};
+  /** @type {PatramDiagnostic[]} */
+  const diagnostics = [];
+
+  collectFieldConfigDiagnostics(diagnostics, path_classes, fields);
+  collectClassSchemaConfigDiagnostics(
+    diagnostics,
+    path_classes,
+    classes,
+    fields,
+    repo_config.class_schemas,
+  );
+
+  return diagnostics;
+}
+
+/**
+ * @param {PatramRepoConfig} repo_config
+ * @returns {PatramDiagnostic[]}
+ */
+function validateStoredQueries(repo_config) {
+  /** @type {PatramDiagnostic[]} */
+  const diagnostics = [];
+
+  for (const [query_name, stored_query] of Object.entries(
+    repo_config.queries,
+  )) {
+    collectWhereClauseDiagnostics(
+      diagnostics,
+      repo_config,
+      stored_query.where,
+      `queries.${query_name}.where`,
+    );
+  }
+
+  return diagnostics;
+}
+
 /**
  * @param {PatramRepoConfig} repo_config
  * @returns {PatramDiagnostic[]}
@@ -374,20 +552,21 @@ function validateDerivedSummaries(repo_config) {
   const known_relation_names = new Set(Object.keys(graph_config.relations));
   /** @type {PatramDiagnostic[]} */
   const diagnostics = [];
-  const kind_coverage = new Map();
+  const class_coverage = new Map();
 
   for (const [summary_name, summary_definition] of Object.entries(
     repo_config.derived_summaries,
   )) {
-    collectDuplicateKindDiagnostics(
+    collectDuplicateClassDiagnostics(
       diagnostics,
-      kind_coverage,
-      summary_definition.kinds,
+      class_coverage,
+      summary_definition.classes,
       summary_name,
     );
     collectDerivedSummaryFieldDiagnostics(
       diagnostics,
       known_relation_names,
+      repo_config,
       summary_name,
       summary_definition.fields,
     );
@@ -407,7 +586,7 @@ function createDefaultRepoConfig() {
 }
 
 /**
- * @param {{ derived_summaries?: unknown, include: string[], queries: Record<string, { where: string }>, kinds?: unknown, mappings?: unknown, relations?: unknown }} repo_config
+ * @param {{ class_schemas?: unknown, classes?: unknown, derived_summaries?: unknown, fields?: unknown, include: string[], mappings?: unknown, path_classes?: unknown, queries: Record<string, { where: string }>, relations?: unknown }} repo_config
  * @returns {PatramRepoConfig}
  */
 function normalizeRepoConfig(repo_config) {
@@ -417,61 +596,69 @@ function normalizeRepoConfig(repo_config) {
     queries: { ...repo_config.queries },
   };
 
-  if (
-    repo_config.derived_summaries !== undefined &&
-    repo_config.derived_summaries !== null
-  ) {
-    normalized_config.derived_summaries =
-      /** @type {PatramRepoConfig['derived_summaries']} */ (
-        repo_config.derived_summaries
-      );
-  }
-
-  if (repo_config.kinds !== undefined && repo_config.kinds !== null) {
-    normalized_config.kinds = /** @type {PatramRepoConfig['kinds']} */ (
-      repo_config.kinds
-    );
-  }
-
-  if (repo_config.mappings !== undefined && repo_config.mappings !== null) {
-    normalized_config.mappings = /** @type {PatramRepoConfig['mappings']} */ (
-      repo_config.mappings
-    );
-  }
-
-  if (repo_config.relations !== undefined && repo_config.relations !== null) {
-    normalized_config.relations = /** @type {PatramRepoConfig['relations']} */ (
-      repo_config.relations
-    );
-  }
+  assignOptionalRepoConfigField(
+    normalized_config,
+    'class_schemas',
+    repo_config.class_schemas,
+  );
+  assignOptionalRepoConfigField(
+    normalized_config,
+    'classes',
+    repo_config.classes,
+  );
+  assignOptionalRepoConfigField(
+    normalized_config,
+    'derived_summaries',
+    repo_config.derived_summaries,
+  );
+  assignOptionalRepoConfigField(
+    normalized_config,
+    'fields',
+    repo_config.fields,
+  );
+  assignOptionalRepoConfigField(
+    normalized_config,
+    'mappings',
+    repo_config.mappings,
+  );
+  assignOptionalRepoConfigField(
+    normalized_config,
+    'path_classes',
+    repo_config.path_classes,
+  );
+  assignOptionalRepoConfigField(
+    normalized_config,
+    'relations',
+    repo_config.relations,
+  );
 
   return normalized_config;
 }
 
 /**
  * @param {PatramDiagnostic[]} diagnostics
- * @param {Map<string, string>} kind_coverage
- * @param {string[]} kind_names
+ * @param {Map<string, string>} class_coverage
+ * @param {string[]} class_names
  * @param {string} summary_name
  */
-function collectDuplicateKindDiagnostics(
+function collectDuplicateClassDiagnostics(
   diagnostics,
-  kind_coverage,
-  kind_names,
+  class_coverage,
+  class_names,
   summary_name,
 ) {
-  for (const kind_name of kind_names) {
-    const existing_summary_name = kind_coverage.get(kind_name);
+  for (const class_name of class_names) {
+    const existing_summary_name = class_coverage.get(class_name);
 
     if (!existing_summary_name) {
-      kind_coverage.set(kind_name, summary_name);
+      class_coverage.set(class_name, summary_name);
       continue;
     }
 
     diagnostics.push(
       createConfigDiagnostic(
-        `derived_summaries.${summary_name}.kinds`,
-        `Kind "${kind_name}" is already covered by derived summary "${existing_summary_name}".`,
+        `derived_summaries.${summary_name}.classes`,
+        `Class "${class_name}" is already covered by derived summary "${existing_summary_name}".`,
       ),
     );
   }
@@ -480,12 +667,14 @@ function collectDuplicateKindDiagnostics(
 /**
  * @param {PatramDiagnostic[]} diagnostics
  * @param {Set<string>} known_relation_names
+ * @param {PatramRepoConfig} repo_config
  * @param {string} summary_name
  * @param {import('./load-patram-config.types.ts').DerivedSummaryFieldConfig[]} field_definitions
  */
 function collectDerivedSummaryFieldDiagnostics(
   diagnostics,
   known_relation_names,
+  repo_config,
   summary_name,
   field_definitions,
 ) {
@@ -499,8 +688,8 @@ function collectDerivedSummaryFieldDiagnostics(
       );
       collectWhereClauseDiagnostics(
         diagnostics,
+        repo_config,
         field_definition.count.where,
-        known_relation_names,
         `derived_summaries.${summary_name}.fields.${field_index}.count.where`,
       );
       continue;
@@ -509,8 +698,8 @@ function collectDerivedSummaryFieldDiagnostics(
     for (const [case_index, select_case] of field_definition.select.entries()) {
       collectWhereClauseDiagnostics(
         diagnostics,
+        repo_config,
         select_case.when,
-        known_relation_names,
         `derived_summaries.${summary_name}.fields.${field_index}.select.${case_index}.when`,
       );
     }
@@ -559,84 +748,232 @@ function collectTraversalDiagnostic(
 
 /**
  * @param {PatramDiagnostic[]} diagnostics
- * @param {string} where_clause
- * @param {Set<string>} known_relation_names
- * @param {string} diagnostic_path
+ * @param {Record<string, { prefixes: string[] }>} path_classes
+ * @param {Record<string, MetadataFieldConfig>} fields
  */
-function collectWhereClauseDiagnostics(
+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('$') ||
+    !RESERVED_STRUCTURAL_FIELD_NAMES.has(field_name)
+  ) {
+    return false;
+  }
+
+  diagnostics.push(
+    createConfigDiagnostic(
+      `fields.${field_name}`,
+      'Metadata field names must not start with "$".',
+    ),
+  );
+
+  return true;
+}
+
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {string} field_name
+ * @param {MetadataFieldConfig} field_definition
+ */
+function collectDisplayOrderDiagnostic(
   diagnostics,
-  where_clause,
-  known_relation_names,
-  diagnostic_path,
+  field_name,
+  field_definition,
 ) {
-  const parse_result = parseWhereClause(where_clause);
+  if (
+    field_definition.display?.order === undefined ||
+    (Number.isInteger(field_definition.display.order) &&
+      field_definition.display.order >= 0)
+  ) {
+    return;
+  }
 
-  if (!parse_result.success) {
+  diagnostics.push(
+    createConfigDiagnostic(
+      `fields.${field_name}.display.order`,
+      'Display order must be a non-negative integer.',
+    ),
+  );
+}
+
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {Record<string, { prefixes: string[] }>} path_classes
+ * @param {string} field_name
+ * @param {MetadataFieldConfig} field_definition
+ */
+function collectFieldPathClassDiagnostic(
+  diagnostics,
+  path_classes,
+  field_name,
+  field_definition,
+) {
+  if (
+    !('path_class' in field_definition) ||
+    field_definition.path_class === undefined
+  ) {
+    return;
+  }
+
+  if (field_definition.type !== 'path') {
     diagnostics.push(
-      createConfigDiagnostic(diagnostic_path, parse_result.diagnostic.message),
+      createConfigDiagnostic(
+        `fields.${field_name}.path_class`,
+        'Path classes are only valid for path fields.',
+      ),
     );
 
     return;
   }
 
-  for (const clause of parse_result.clauses) {
-    collectClauseRelationDiagnostics(
-      diagnostics,
-      clause.term,
-      known_relation_names,
-      diagnostic_path,
-    );
+  if (path_classes[field_definition.path_class]) {
+    return;
   }
+
+  diagnostics.push(
+    createConfigDiagnostic(
+      `fields.${field_name}.path_class`,
+      `Unknown path class "${field_definition.path_class}".`,
+    ),
+  );
 }
 
 /**
  * @param {PatramDiagnostic[]} diagnostics
- * @param {import('./parse-where-clause.types.ts').ParsedTerm} term
- * @param {Set<string>} known_relation_names
- * @param {string} diagnostic_path
+ * @param {Record<string, { prefixes: string[] }>} path_classes
+ * @param {Record<string, unknown>} classes
+ * @param {Record<string, MetadataFieldConfig>} fields
+ * @param {PatramRepoConfig['class_schemas']} class_schemas
  */
-function collectClauseRelationDiagnostics(
+function collectClassSchemaConfigDiagnostics(
   diagnostics,
-  term,
-  known_relation_names,
-  diagnostic_path,
+  path_classes,
+  classes,
+  fields,
+  class_schemas,
 ) {
-  if (term.kind === 'aggregate') {
-    if (!known_relation_names.has(term.traversal.relation_name)) {
+  if (!class_schemas) {
+    return;
+  }
+
+  for (const class_name of Object.keys(class_schemas)) {
+    if (classes[class_name]) {
+      continue;
+    }
+
+    diagnostics.push(
+      createConfigDiagnostic(
+        `class_schemas.${class_name}`,
+        `Unknown class "${class_name}".`,
+      ),
+    );
+  }
+
+  for (const [class_name, schema_definition] of Object.entries(class_schemas)) {
+    for (const field_name of Object.keys(schema_definition.fields)) {
+      if (fields[field_name]) {
+        continue;
+      }
+
       diagnostics.push(
         createConfigDiagnostic(
-          diagnostic_path,
-          `Unknown relation "${term.traversal.relation_name}" in traversal clause.`,
+          `class_schemas.${class_name}.fields.${field_name}`,
+          `Unknown field "${field_name}".`,
         ),
       );
     }
+  }
 
-    for (const nested_clause of term.clauses) {
-      collectClauseRelationDiagnostics(
-        diagnostics,
-        nested_clause.term,
-        known_relation_names,
-        diagnostic_path,
-      );
+  for (const [class_name, schema_definition] of Object.entries(class_schemas)) {
+    if (
+      schema_definition.document_path_class === undefined ||
+      path_classes[schema_definition.document_path_class]
+    ) {
+      continue;
     }
 
-    return;
+    diagnostics.push(
+      createConfigDiagnostic(
+        `class_schemas.${class_name}.document_path_class`,
+        `Unknown path class "${schema_definition.document_path_class}".`,
+      ),
+    );
   }
+}
 
-  if (term.kind !== 'relation' && term.kind !== 'relation_target') {
+/**
+ * @template {Exclude<keyof PatramRepoConfig, 'include' | 'queries'>} TKey
+ * @param {PatramRepoConfig} normalized_config
+ * @param {TKey} field_name
+ * @param {unknown} field_value
+ */
+function assignOptionalRepoConfigField(
+  normalized_config,
+  field_name,
+  field_value,
+) {
+  if (field_value === undefined || field_value === null) {
     return;
   }
 
-  if (known_relation_names.has(term.relation_name)) {
+  normalized_config[field_name] = /** @type {PatramRepoConfig[TKey]} */ (
+    field_value
+  );
+}
+
+/**
+ * @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;
   }
 
-  diagnostics.push(
-    createConfigDiagnostic(
-      diagnostic_path,
-      `Unknown relation "${term.relation_name}" in relation clause.`,
-    ),
+  const semantic_diagnostics = getQuerySemanticDiagnostics(
+    repo_config,
+    { kind: 'ad_hoc' },
+    parse_result.clauses,
   );
+
+  for (const semantic_diagnostic of semantic_diagnostics) {
+    diagnostics.push(
+      createConfigDiagnostic(diagnostic_path, semantic_diagnostic.message),
+    );
+  }
 }
 
 /**