patram 0.3.0 → 0.5.0

package/lib/load-patram-config.js

@@ -1,12 +1,8 @@
+/** @import * as $k$$l$patram$j$config$k$js from './patram-config.js'; */
 /* eslint-disable max-lines */
+
 /**
- * @import {
- *   ClassSchemaConfig,
- *   LoadPatramConfigResult,
- *   MetadataFieldConfig,
- *   PatramDiagnostic,
- *   PatramRepoConfig,
- * } from './load-patram-config.types.ts';
+ * @import { ClassDefinition } from './patram-config.js';
  */
 
 import { readFile } from 'node:fs/promises';
@@ -15,7 +11,12 @@ import process from 'node:process';
 
 import { z } from 'zod';
 
-import { parsePatramConfig } from './patram-config.js';
+import {
+  class_definition_schema,
+  mapping_definition_schema,
+  parsePatramConfig,
+  relation_definition_schema,
+} 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';
@@ -40,12 +41,28 @@ 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']);
 
+/**
+ * @typedef {object} PatramDiagnostic
+ * @property {string} code
+ * @property {number} column
+ * @property {'error'} level
+ * @property {number} line
+ * @property {string} message
+ * @property {string} path
+ */
+
+/**
+ * @typedef {z.output<typeof stored_query_schema>} StoredQueryConfig
+ */
 const stored_query_schema = z
   .object({
     where: z.string().min(1, 'Stored query "where" must not be empty.'),
   })
   .strict();
 
+/**
+ * @typedef {z.output<typeof derived_summary_scalar_schema>} DerivedSummaryScalar
+ */
 const derived_summary_scalar_schema = z.union([
   z.boolean(),
   z.number(),
@@ -53,6 +70,9 @@ const derived_summary_scalar_schema = z.union([
   z.null(),
 ]);
 
+/**
+ * @typedef {z.output<typeof derived_summary_count_schema>} DerivedSummaryCountConfig
+ */
 const derived_summary_count_schema = z
   .object({
     traversal: z
@@ -64,6 +84,9 @@ const derived_summary_count_schema = z
   })
   .strict();
 
+/**
+ * @typedef {z.output<typeof derived_summary_select_case_schema>} DerivedSummarySelectCaseConfig
+ */
 const derived_summary_select_case_schema = z
   .object({
     value: derived_summary_scalar_schema,
@@ -71,21 +94,41 @@ const derived_summary_select_case_schema = z
   })
   .strict();
 
-const derived_summary_field_schema = z
+const derived_summary_field_name_schema = z
+  .string()
+  .regex(
+    /^[a-z][a-z0-9_]*$/du,
+    'Derived summary field names must use lower_snake_case.',
+  );
+
+/**
+ * @typedef {z.output<typeof derived_summary_field_schema>} DerivedSummaryFieldConfig
+ */
+const derived_summary_count_field_schema = z
   .object({
-    count: derived_summary_count_schema.optional(),
-    default: derived_summary_scalar_schema.optional(),
-    name: z
-      .string()
-      .regex(
-        /^[a-z][a-z0-9_]*$/du,
-        'Derived summary field names must use lower_snake_case.',
-      ),
-    select: z.array(derived_summary_select_case_schema).optional(),
+    count: derived_summary_count_schema,
+    name: derived_summary_field_name_schema,
   })
-  .strict()
-  .superRefine(validateDerivedSummaryFieldDefinition);
+  .strict();
+
+const derived_summary_select_field_schema = z
+  .object({
+    default: derived_summary_scalar_schema,
+    name: derived_summary_field_name_schema,
+    select: z
+      .array(derived_summary_select_case_schema)
+      .min(1, 'Derived summary "select" must contain at least one case.'),
+  })
+  .strict();
+
+const derived_summary_field_schema = z.union([
+  derived_summary_count_field_schema,
+  derived_summary_select_field_schema,
+]);
 
+/**
+ * @typedef {z.output<typeof derived_summary_schema>} DerivedSummaryConfig
+ */
 const derived_summary_schema = z
   .object({
     classes: z
@@ -98,6 +141,9 @@ const derived_summary_schema = z
   .strict()
   .superRefine(validateDerivedSummaryDefinition);
 
+/**
+ * @typedef {z.output<typeof field_display_schema>} FieldDisplayConfig
+ */
 const field_display_schema = z
   .object({
     hidden: z.boolean().optional(),
@@ -105,6 +151,9 @@ const field_display_schema = z
   })
   .strict();
 
+/**
+ * @typedef {z.output<typeof field_query_schema>} FieldQueryConfig
+ */
 const field_query_schema = z
   .object({
     contains: z.boolean().optional(),
@@ -118,6 +167,9 @@ const field_base_shape = {
   path_class: z.string().min(1).optional(),
 };
 
+/**
+ * @typedef {z.output<typeof metadata_field_schema>} MetadataFieldConfig
+ */
 const metadata_field_schema = z.discriminatedUnion('type', [
   z
     .object({
@@ -167,12 +219,18 @@ const metadata_field_schema = z.discriminatedUnion('type', [
     .strict(),
 ]);
 
+/**
+ * @typedef {z.output<typeof class_field_rule_schema>} ClassFieldRuleConfig
+ */
 const class_field_rule_schema = z
   .object({
     presence: z.enum(['required', 'optional', 'forbidden']),
   })
   .strict();
 
+/**
+ * @typedef {z.output<typeof class_schema_schema>} ClassSchemaConfig
+ */
 const class_schema_schema = z
   .object({
     document_path_class: z.string().min(1).optional(),
@@ -181,6 +239,16 @@ const class_schema_schema = z
   })
   .strict();
 
+/**
+ * @typedef {z.output<typeof repo_class_definition_schema>} RepoClassConfig
+ */
+const repo_class_definition_schema = class_definition_schema.extend({
+  schema: class_schema_schema.optional(),
+});
+
+/**
+ * @typedef {z.output<typeof path_class_schema>} PathClassConfig
+ */
 const path_class_schema = z
   .object({
     prefixes: z
@@ -189,10 +257,14 @@ const path_class_schema = z
   })
   .strict();
 
+/**
+ * @typedef {z.output<typeof patram_repo_config_schema>} PatramRepoConfig
+ */
 const patram_repo_config_schema = z
   .object({
-    class_schemas: z.record(z.string().min(1), class_schema_schema).optional(),
-    classes: z.unknown().optional(),
+    classes: z
+      .record(z.string().min(1), repo_class_definition_schema)
+      .optional(),
     derived_summaries: z
       .record(z.string().min(1), derived_summary_schema)
       .optional(),
@@ -201,14 +273,23 @@ const patram_repo_config_schema = 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),
-    mappings: z.unknown().optional(),
+    mappings: z.record(z.string().min(1), mapping_definition_schema).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(),
+    relations: z
+      .record(z.string().min(1), relation_definition_schema)
+      .optional(),
   })
   .strict()
   .superRefine(validateFieldDefinitionKeys);
 
+/**
+ * @typedef {object} LoadPatramConfigResult
+ * @property {PatramRepoConfig | null} config
+ * @property {string} config_path
+ * @property {PatramDiagnostic[]} diagnostics
+ */
+
 /**
  * Load and validate the repo Patram config.
  *
@@ -229,6 +310,14 @@ export async function loadPatramConfig(project_directory = process.cwd()) {
     return createLoadResult(null, [parse_result.diagnostic]);
   }
 
+  const legacy_config_diagnostics = validateLegacyConfigShape(
+    parse_result.value,
+  );
+
+  if (legacy_config_diagnostics.length > 0) {
+    return createLoadResult(null, legacy_config_diagnostics);
+  }
+
   const config_result = patram_repo_config_schema.safeParse(parse_result.value);
 
   if (!config_result.success) {
@@ -382,61 +471,6 @@ function validateFieldDefinitionKeys(repo_config, refinement_context) {
   }
 }
 
-/**
- * @param {{ count?: unknown, default?: unknown, select?: unknown }} field_definition
- * @param {import('zod').RefinementCtx} refinement_context
- */
-function validateDerivedSummaryFieldDefinition(
-  field_definition,
-  refinement_context,
-) {
-  const evaluator_count =
-    Number(field_definition.count !== undefined) +
-    Number(field_definition.select !== undefined);
-
-  if (evaluator_count !== 1) {
-    refinement_context.addIssue({
-      code: 'custom',
-      message:
-        'Derived summary fields must define exactly one of "count" or "select".',
-    });
-  }
-
-  if (
-    field_definition.count !== undefined &&
-    field_definition.default !== undefined
-  ) {
-    refinement_context.addIssue({
-      code: 'custom',
-      message: 'Derived summary count fields must not define "default".',
-      path: ['default'],
-    });
-  }
-
-  if (field_definition.select === undefined) {
-    return;
-  }
-
-  if (
-    Array.isArray(field_definition.select) &&
-    field_definition.select.length === 0
-  ) {
-    refinement_context.addIssue({
-      code: 'custom',
-      message: 'Derived summary "select" must contain at least one case.',
-      path: ['select'],
-    });
-  }
-
-  if (field_definition.default === undefined) {
-    refinement_context.addIssue({
-      code: 'custom',
-      message: 'Derived summary select fields must define "default".',
-      path: ['default'],
-    });
-  }
-}
-
 /**
  * @param {{ fields: Array<{ name: string }> }} summary_definition
  * @param {import('zod').RefinementCtx} refinement_context
@@ -465,7 +499,7 @@ function validateDerivedSummaryDefinition(
 }
 
 /**
- * @param {{ include: string[], queries: Record<string, { where: string }>, classes?: unknown, mappings?: unknown, relations?: unknown }} repo_config
+ * @param {PatramRepoConfig} repo_config
  * @returns {PatramDiagnostic[]}
  */
 function validateGraphSchema(repo_config) {
@@ -479,7 +513,7 @@ function validateGraphSchema(repo_config) {
 
   try {
     parsePatramConfig({
-      classes: repo_config.classes ?? {},
+      classes: collectGraphClassDefinitions(repo_config.classes),
       mappings: repo_config.mappings ?? {},
       relations: repo_config.relations ?? {},
     });
@@ -509,9 +543,8 @@ function validateFieldSchemaConfig(repo_config) {
   collectClassSchemaConfigDiagnostics(
     diagnostics,
     path_classes,
-    classes,
     fields,
-    repo_config.class_schemas,
+    classes,
   );
 
   return diagnostics;
@@ -586,7 +619,7 @@ function createDefaultRepoConfig() {
 }
 
 /**
- * @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
+ * @param {PatramRepoConfig} repo_config
  * @returns {PatramRepoConfig}
  */
 function normalizeRepoConfig(repo_config) {
@@ -596,11 +629,6 @@ function normalizeRepoConfig(repo_config) {
     queries: { ...repo_config.queries },
   };
 
-  assignOptionalRepoConfigField(
-    normalized_config,
-    'class_schemas',
-    repo_config.class_schemas,
-  );
   assignOptionalRepoConfigField(
     normalized_config,
     'classes',
@@ -635,6 +663,27 @@ function normalizeRepoConfig(repo_config) {
   return normalized_config;
 }
 
+/**
+ * @param {unknown} config_value
+ * @returns {PatramDiagnostic[]}
+ */
+function validateLegacyConfigShape(config_value) {
+  if (
+    config_value === null ||
+    typeof config_value !== 'object' ||
+    !Object.hasOwn(config_value, 'class_schemas')
+  ) {
+    return [];
+  }
+
+  return [
+    createConfigDiagnostic(
+      'class_schemas',
+      'Top-level "class_schemas" is not supported. Move entries into classes.<name>.schema.',
+    ),
+  ];
+}
+
 /**
  * @param {PatramDiagnostic[]} diagnostics
  * @param {Map<string, string>} class_coverage
@@ -669,7 +718,7 @@ function collectDuplicateClassDiagnostics(
  * @param {Set<string>} known_relation_names
  * @param {PatramRepoConfig} repo_config
  * @param {string} summary_name
- * @param {import('./load-patram-config.types.ts').DerivedSummaryFieldConfig[]} field_definitions
+ * @param {DerivedSummaryFieldConfig[]} field_definitions
  */
 function collectDerivedSummaryFieldDiagnostics(
   diagnostics,
@@ -861,35 +910,22 @@ function collectFieldPathClassDiagnostic(
 /**
  * @param {PatramDiagnostic[]} diagnostics
  * @param {Record<string, { prefixes: string[] }>} path_classes
- * @param {Record<string, unknown>} classes
  * @param {Record<string, MetadataFieldConfig>} fields
- * @param {PatramRepoConfig['class_schemas']} class_schemas
+ * @param {NonNullable<PatramRepoConfig['classes']>} classes
  */
 function collectClassSchemaConfigDiagnostics(
   diagnostics,
   path_classes,
-  classes,
   fields,
-  class_schemas,
+  classes,
 ) {
-  if (!class_schemas) {
-    return;
-  }
+  for (const [class_name, class_definition] of Object.entries(classes)) {
+    const schema_definition = class_definition.schema;
 
-  for (const class_name of Object.keys(class_schemas)) {
-    if (classes[class_name]) {
+    if (!schema_definition) {
       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;
@@ -897,14 +933,20 @@ function collectClassSchemaConfigDiagnostics(
 
       diagnostics.push(
         createConfigDiagnostic(
-          `class_schemas.${class_name}.fields.${field_name}`,
+          `classes.${class_name}.schema.fields.${field_name}`,
           `Unknown field "${field_name}".`,
         ),
       );
     }
   }
 
-  for (const [class_name, schema_definition] of Object.entries(class_schemas)) {
+  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]
@@ -914,13 +956,31 @@ function collectClassSchemaConfigDiagnostics(
 
     diagnostics.push(
       createConfigDiagnostic(
-        `class_schemas.${class_name}.document_path_class`,
+        `classes.${class_name}.schema.document_path_class`,
         `Unknown path class "${schema_definition.document_path_class}".`,
       ),
     );
   }
 }
 
+/**
+ * @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;
+}
+
 /**
  * @template {Exclude<keyof PatramRepoConfig, 'include' | 'queries'>} TKey
  * @param {PatramRepoConfig} normalized_config
@@ -966,7 +1026,7 @@ function collectWhereClauseDiagnostics(
   const semantic_diagnostics = getQuerySemanticDiagnostics(
     repo_config,
     { kind: 'ad_hoc' },
-    parse_result.clauses,
+    parse_result.expression,
   );
 
   for (const semantic_diagnostic of semantic_diagnostics) {

package/lib/load-patram-config.types.ts

@@ -1,158 +1,56 @@
-import type {
-  ClassDefinition,
-  MappingDefinition,
-  RelationDefinition,
-} from './patram-config.types.ts';
-
-export interface StoredQueryConfig {
-  where: string;
-}
-
+export type StoredQueryConfig =
+  import('./load-patram-config.js').StoredQueryConfig;
+export type FieldDisplayConfig =
+  import('./load-patram-config.js').FieldDisplayConfig;
+export type FieldQueryConfig =
+  import('./load-patram-config.js').FieldQueryConfig;
 export type FieldValueTypeName =
-  | 'string'
-  | 'integer'
-  | 'enum'
-  | 'path'
-  | 'glob'
-  | 'date'
-  | 'date_time';
-
-export interface FieldDisplayConfig {
-  hidden?: boolean;
-  order?: number;
-}
-
-export interface FieldQueryConfig {
-  contains?: boolean;
-  prefix?: boolean;
-}
-
-export interface StringFieldConfig {
-  display?: FieldDisplayConfig;
-  multiple?: boolean;
-  query?: FieldQueryConfig;
-  type: 'string';
-}
-
-export interface IntegerFieldConfig {
-  display?: FieldDisplayConfig;
-  multiple?: boolean;
-  type: 'integer';
-}
-
-export interface EnumFieldConfig {
-  display?: FieldDisplayConfig;
-  multiple?: boolean;
-  type: 'enum';
-  values: string[];
-}
-
-export interface PathFieldConfig {
-  display?: FieldDisplayConfig;
-  multiple?: boolean;
-  path_class?: string;
-  type: 'path';
-}
-
-export interface GlobFieldConfig {
-  display?: FieldDisplayConfig;
-  multiple?: boolean;
-  type: 'glob';
-}
-
-export interface DateFieldConfig {
-  display?: FieldDisplayConfig;
-  multiple?: boolean;
-  type: 'date';
-}
-
-export interface DateTimeFieldConfig {
-  display?: FieldDisplayConfig;
-  multiple?: boolean;
-  type: 'date_time';
-}
-
+  import('./load-patram-config.js').MetadataFieldConfig['type'];
 export type MetadataFieldConfig =
-  | DateFieldConfig
-  | DateTimeFieldConfig
-  | EnumFieldConfig
-  | GlobFieldConfig
-  | IntegerFieldConfig
-  | PathFieldConfig
-  | StringFieldConfig;
-
-export interface ClassFieldRuleConfig {
-  presence: 'required' | 'optional' | 'forbidden';
-}
-
+  import('./load-patram-config.js').MetadataFieldConfig;
+export type StringFieldConfig = Extract<
+  MetadataFieldConfig,
+  { type: 'string' }
+>;
+export type IntegerFieldConfig = Extract<
+  MetadataFieldConfig,
+  { type: 'integer' }
+>;
+export type EnumFieldConfig = Extract<MetadataFieldConfig, { type: 'enum' }>;
+export type PathFieldConfig = Extract<MetadataFieldConfig, { type: 'path' }>;
+export type GlobFieldConfig = Extract<MetadataFieldConfig, { type: 'glob' }>;
+export type DateFieldConfig = Extract<MetadataFieldConfig, { type: 'date' }>;
+export type DateTimeFieldConfig = Extract<
+  MetadataFieldConfig,
+  { type: 'date_time' }
+>;
+export type ClassFieldRuleConfig =
+  import('./load-patram-config.js').ClassFieldRuleConfig;
 export type DirectiveTypeConfig = MetadataFieldConfig;
 export type MetadataDirectiveRuleConfig = ClassFieldRuleConfig;
-
-export interface ClassSchemaConfig {
-  document_path_class?: string;
-  fields: Record<string, ClassFieldRuleConfig>;
-  unknown_fields?: 'ignore' | 'error';
-}
-
+export type ClassSchemaConfig =
+  import('./load-patram-config.js').ClassSchemaConfig;
 export type MetadataSchemaConfig = ClassSchemaConfig;
-
-export interface PathClassConfig {
-  prefixes: string[];
-}
-
-export type DerivedSummaryScalar = boolean | number | string | null;
-
-export interface DerivedSummaryCountFieldConfig {
-  count: {
-    traversal: string;
-    where: string;
-  };
-  name: string;
-}
-
-export interface DerivedSummarySelectCaseConfig {
-  value: DerivedSummaryScalar;
-  when: string;
-}
-
-export interface DerivedSummarySelectFieldConfig {
-  default: DerivedSummaryScalar;
-  name: string;
-  select: DerivedSummarySelectCaseConfig[];
-}
-
+export type PathClassConfig = import('./load-patram-config.js').PathClassConfig;
+export type DerivedSummaryScalar =
+  import('./load-patram-config.js').DerivedSummaryScalar;
+export type DerivedSummarySelectCaseConfig =
+  import('./load-patram-config.js').DerivedSummarySelectCaseConfig;
 export type DerivedSummaryFieldConfig =
-  | DerivedSummaryCountFieldConfig
-  | DerivedSummarySelectFieldConfig;
-
-export interface DerivedSummaryConfig {
-  classes: string[];
-  fields: DerivedSummaryFieldConfig[];
-}
-
-export interface PatramRepoConfig {
-  class_schemas?: Record<string, ClassSchemaConfig>;
-  classes?: Record<string, ClassDefinition>;
-  derived_summaries?: Record<string, DerivedSummaryConfig>;
-  fields?: Record<string, MetadataFieldConfig>;
-  include: string[];
-  mappings?: Record<string, MappingDefinition>;
-  path_classes?: Record<string, PathClassConfig>;
-  queries: Record<string, StoredQueryConfig>;
-  relations?: Record<string, RelationDefinition>;
-}
-
-export interface PatramDiagnostic {
-  code: string;
-  column: number;
-  level: 'error';
-  line: number;
-  message: string;
-  path: string;
-}
-
-export interface LoadPatramConfigResult {
-  config: PatramRepoConfig | null;
-  config_path: string;
-  diagnostics: PatramDiagnostic[];
-}
+  import('./load-patram-config.js').DerivedSummaryFieldConfig;
+export type DerivedSummaryCountFieldConfig = Extract<
+  DerivedSummaryFieldConfig,
+  { count: unknown }
+>;
+export type DerivedSummarySelectFieldConfig = Extract<
+  DerivedSummaryFieldConfig,
+  { select: unknown }
+>;
+export type DerivedSummaryConfig =
+  import('./load-patram-config.js').DerivedSummaryConfig;
+export type PatramRepoConfig =
+  import('./load-patram-config.js').PatramRepoConfig;
+export type PatramDiagnostic =
+  import('./load-patram-config.js').PatramDiagnostic;
+export type LoadPatramConfigResult =
+  import('./load-patram-config.js').LoadPatramConfigResult;