patram 0.4.0 → 0.5.0

package/lib/build-graph-identity.js

@@ -1,5 +1,5 @@
-/** @import * as $k$$l$document$j$node$j$identity$k$js from './document-node-identity.js'; */
 /**
+ * @import { DocumentNodeReference } from './document-node-identity.js';
  * @import { GraphNode } from './build-graph.types.ts';
  * @import { PatramClaim } from './parse-claims.types.ts';
  */
@@ -48,7 +48,7 @@ export function resolveNodeKey(node_mapping, claim, document_entity_keys) {
  * @param {'path' | 'value'} target_type
  * @param {PatramClaim} claim
  * @param {Map<string, string>} document_entity_keys
- * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @param {Map<string, DocumentNodeReference>} document_node_references
  * @param {Set<string>} document_paths
  * @returns {{ class_name: string, key: string, path?: string }}
  */
@@ -124,7 +124,7 @@ function resolveValueTargetReference(target_kind, claim) {
  * @param {string} target_class
  * @param {PatramClaim} claim
  * @param {Map<string, string>} document_entity_keys
- * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @param {Map<string, DocumentNodeReference>} document_node_references
  * @param {Set<string>} document_paths
  * @returns {{ class_name: string, key: string, path?: string }}
  */
@@ -171,7 +171,7 @@ function resolvePathTargetReference(
 
 /**
  * @param {string} target_path
- * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @param {Map<string, DocumentNodeReference>} document_node_references
  * @returns {{ class_name: string, key: string, path?: string }}
  */
 function resolveDocumentTargetReference(target_path, document_node_references) {
@@ -246,8 +246,8 @@ function getDocumentEntityMapKey(document_path, class_name) {
 }
 
 /**
- * @param {import('./document-node-identity.js').DocumentNodeReference | undefined} document_node_reference
- * @returns {document_node_reference is $k$$l$document$j$node$j$identity$k$js.DocumentNodeReference}
+ * @param {DocumentNodeReference | undefined} document_node_reference
+ * @returns {document_node_reference is DocumentNodeReference}
  */
 function documentNodeReferenceIsPromoted(document_node_reference) {
   return (

package/lib/build-graph.js

@@ -771,7 +771,7 @@ function getFieldDefinition(patram_config, field_name) {
  * @returns {{ fields?: Record<string, { presence: 'required' | 'optional' | 'forbidden' }>, unknown_fields?: 'ignore' | 'error' } | undefined}
  */
 function getClassSchema(patram_config, class_name) {
-  return patram_config.class_schemas?.[class_name];
+  return patram_config.classes[class_name]?.schema;
 }
 
 /**

package/lib/check-directive-metadata.js

@@ -47,7 +47,7 @@ export function checkDirectiveMetadata(
   if (
     claims.length === 0 ||
     (repo_config.fields === undefined &&
-      repo_config.class_schemas === undefined)
+      !hasConfiguredClassSchemas(repo_config))
   ) {
     return [];
   }
@@ -143,7 +143,7 @@ function collectDocumentDiagnostics(
   document_paths,
 ) {
   const document_kind = resolveDocumentKind(graph, document_path);
-  const schema_definition = repo_config.class_schemas?.[document_kind];
+  const schema_definition = repo_config.classes?.[document_kind]?.schema;
   /** @type {Map<string, number>} */
   const directive_counts = new Map();
 
@@ -240,6 +240,20 @@ function collectClaimDiagnostics(
   ];
 }
 
+/**
+ * @param {PatramRepoConfig} repo_config
+ * @returns {boolean}
+ */
+function hasConfiguredClassSchemas(repo_config) {
+  for (const class_definition of Object.values(repo_config.classes ?? {})) {
+    if (class_definition.schema) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 /**
  * @param {PatramRepoConfig} repo_config
  * @param {string} document_path

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

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;

package/lib/parse-claims.js

@@ -1,6 +1,5 @@
-/** @import * as $k$$l$parse$j$claims$k$types$k$ts from './parse-claims.types.ts'; */
 /**
- * @import { ParseClaimsInput, ParseSourceFileResult } from './parse-claims.types.ts';
+ * @import { ParseClaimsInput, ParseSourceFileResult, PatramClaim } from './parse-claims.types.ts';
  */
 
 import { getFileExtension } from './claim-helpers.js';
@@ -51,7 +50,7 @@ export function parseSourceFile(parse_input) {
  * Parse a file into neutral Patram claims.
  *
  * @param {ParseClaimsInput} parse_input
- * @returns {$k$$l$parse$j$claims$k$types$k$ts.PatramClaim[]}
+ * @returns {PatramClaim[]}
  */
 export function parseClaims(parse_input) {
   return parseSourceFile(parse_input).claims;

package/lib/parse-jsdoc-claims.js

@@ -1,6 +1,6 @@
-/** @import * as $k$$l$load$j$patram$j$config$k$types$k$ts from './load-patram-config.types.ts'; */
 /**
- * @import { ParseClaimsInput, ParseSourceFileResult, PatramClaim, PatramClaimFields } from './parse-claims.types.ts';
+ * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ * @import { ParseClaimsInput, ParseSourceFileResult, PatramClaimFields } from './parse-claims.types.ts';
  */
 
 import {
@@ -266,7 +266,7 @@ function compareClaimEntries(left_entry, right_entry) {
 /**
  * @param {string} file_path
  * @param {{ activation_column: number | null, activation_line: number | null }} jsdoc_block
- * @returns {$k$$l$load$j$patram$j$config$k$types$k$ts.PatramDiagnostic}
+ * @returns {PatramDiagnostic}
  */
 function createMultiplePatramBlocksDiagnostic(file_path, jsdoc_block) {
   return {

package/lib/patram-config.js

@@ -1,5 +1,4 @@
 /**
- * @import { PatramConfig } from './patram-config.types.ts';
  * @import { RefinementCtx } from 'zod';
  */
 
@@ -11,14 +10,20 @@ const CLAIM_TYPE_SCHEMA = z.string().min(1);
 const KEY_SOURCE_SCHEMA = z.enum(['path', 'value']);
 const TARGET_SCHEMA = z.enum(['path', 'value']);
 
-const class_definition_schema = z
+/**
+ * @typedef {z.output<typeof class_definition_schema>} ClassDefinition
+ */
+export const class_definition_schema = z
   .object({
     builtin: z.boolean().optional(),
     label: z.string().min(1).optional(),
   })
   .strict();
 
-const relation_definition_schema = z
+/**
+ * @typedef {z.output<typeof relation_definition_schema>} RelationDefinition
+ */
+export const relation_definition_schema = z
   .object({
     builtin: z.boolean().optional(),
     from: z.array(CLASS_NAME_SCHEMA).min(1),
@@ -26,6 +31,9 @@ const relation_definition_schema = z
   })
   .strict();
 
+/**
+ * @typedef {z.output<typeof mapping_node_schema>} MappingNodeDefinition
+ */
 const mapping_node_schema = z
   .object({
     class: CLASS_NAME_SCHEMA,
@@ -34,6 +42,9 @@ const mapping_node_schema = z
   })
   .strict();
 
+/**
+ * @typedef {z.output<typeof mapping_emit_schema>} MappingEmitDefinition
+ */
 const mapping_emit_schema = z
   .object({
     relation: RELATION_NAME_SCHEMA,
@@ -42,7 +53,10 @@ const mapping_emit_schema = z
   })
   .strict();
 
-const mapping_definition_schema = z
+/**
+ * @typedef {z.output<typeof mapping_definition_schema>} MappingDefinition
+ */
+export const mapping_definition_schema = z
   .object({
     emit: mapping_emit_schema.optional(),
     node: mapping_node_schema.optional(),
@@ -50,6 +64,9 @@ const mapping_definition_schema = z
   .strict()
   .superRefine(validateMappingDefinition);
 
+/**
+ * @typedef {z.output<typeof patramConfigSchema>} PatramGraphConfig
+ */
 export const patramConfigSchema = z
   .object({
     $schema: z.url().optional(),
@@ -64,7 +81,7 @@ export const patramConfigSchema = z
  * Parse and validate Patram JSON configuration.
  *
  * @param {unknown} config_json
- * @returns {PatramConfig}
+ * @returns {PatramGraphConfig}
  */
 export function parsePatramConfig(config_json) {
   return patramConfigSchema.parse(config_json);
@@ -86,7 +103,7 @@ function validateMappingDefinition(mapping_definition, refinement_context) {
 }
 
 /**
- * @param {PatramConfig} config_json
+ * @param {PatramGraphConfig} config_json
  * @param {RefinementCtx} refinement_context
  */
 function validatePatramConfigReferences(config_json, refinement_context) {
@@ -96,7 +113,7 @@ function validatePatramConfigReferences(config_json, refinement_context) {
 }
 
 /**
- * @param {PatramConfig} config_json
+ * @param {PatramGraphConfig} config_json
  * @param {RefinementCtx} refinement_context
  */
 function validateRelationClasses(config_json, refinement_context) {
@@ -119,7 +136,7 @@ function validateRelationClasses(config_json, refinement_context) {
 }
 
 /**
- * @param {PatramConfig} config_json
+ * @param {PatramGraphConfig} config_json
  * @param {RefinementCtx} refinement_context
  */
 function validateMappingClasses(config_json, refinement_context) {
@@ -147,7 +164,7 @@ function validateMappingClasses(config_json, refinement_context) {
 }
 
 /**
- * @param {PatramConfig} config_json
+ * @param {PatramGraphConfig} config_json
  * @param {RefinementCtx} refinement_context
  */
 function validateMappingRelations(config_json, refinement_context) {

package/lib/patram-config.types.ts

@@ -1,40 +1,22 @@
-export interface ClassDefinition {
-  builtin?: boolean;
-  label?: string;
-}
-
-export interface RelationDefinition {
-  builtin?: boolean;
-  from: string[];
-  to: string[];
-}
-
-export interface MappingNodeDefinition {
-  class: string;
-  field: string;
-  key?: 'path' | 'value';
-}
-
-export interface MappingEmitDefinition {
-  relation: string;
-  target: 'path' | 'value';
-  target_class: string;
-}
-
-export interface MappingDefinition {
-  emit?: MappingEmitDefinition;
-  node?: MappingNodeDefinition;
-}
-
-export interface PatramConfig {
-  $schema?: string;
-  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';
+
+export type ClassDefinition = import('./patram-config.js').ClassDefinition;
+export type RelationDefinition =
+  import('./patram-config.js').RelationDefinition;
+export type MappingNodeDefinition =
+  import('./patram-config.js').MappingNodeDefinition;
+export type MappingEmitDefinition =
+  import('./patram-config.js').MappingEmitDefinition;
+export type MappingDefinition = import('./patram-config.js').MappingDefinition;
+export type PatramGraphConfig = import('./patram-config.js').PatramGraphConfig;
+export type PatramClassConfig = ClassDefinition & {
+  schema?: ClassSchemaConfig;
+};
+
+export type PatramConfig = Omit<PatramGraphConfig, 'classes'> & {
+  classes: Record<string, PatramClassConfig>;
+  fields?: Record<string, MetadataFieldConfig>;
+};

package/lib/render-output-view.js

@@ -1,12 +1,11 @@
-/** @import * as $k$$l$output$j$view$k$types$k$ts from './output-view.types.ts'; */
-/* eslint-disable max-lines */
 /**
  * @import { BuildGraphResult, GraphNode } from './build-graph.types.ts';
  * @import { DerivedSummaryEvaluator } from './derived-summary.js';
  * @import { PatramRepoConfig } from './load-patram-config.types.ts';
  * @import { ParsedCliArguments } from './parse-cli-arguments.types.ts';
- * @import { OutputMetadataField, OutputStoredQueryItem, OutputView, ResolvedOutputMode, ShowOutputView } from './output-view.types.ts';
+ * @import { OutputDerivedSummary, OutputMetadataField, OutputNodeItem, OutputResolvedLinkItem, OutputResolvedLinkTarget, OutputStoredQueryItem, OutputView, ResolvedOutputMode, ShowOutputView } from './output-view.types.ts';
  */
+/* eslint-disable max-lines */
 
 import { renderJsonOutput } from './render-json-output.js';
 import { renderPlainOutput } from './render-plain-output.js';
@@ -171,9 +170,9 @@ function createStoredQueriesOutputView(stored_queries) {
 
 /**
  * @param {GraphNode} graph_node
- * @param {import('./output-view.types.ts').OutputDerivedSummary | null} derived_summary
+ * @param {OutputDerivedSummary | null} derived_summary
  * @param {NonNullable<PatramRepoConfig['fields']>} field_definitions
- * @returns {$k$$l$output$j$view$k$types$k$ts.OutputNodeItem}
+ * @returns {OutputNodeItem}
  */
 function createOutputNodeItem(graph_node, derived_summary, field_definitions) {
   const title = getOutputNodeTitle(graph_node);
@@ -203,9 +202,9 @@ function createOutputNodeItem(graph_node, derived_summary, field_definitions) {
 /**
  * @param {{ kind?: string, path: string, status?: string, title: string }} target
  * @param {NonNullable<PatramRepoConfig['fields']>} field_definitions
- * @param {import('./output-view.types.ts').OutputDerivedSummary | null} derived_summary
+ * @param {OutputDerivedSummary | null} derived_summary
  * @param {GraphNode | undefined} graph_node
- * @returns {$k$$l$output$j$view$k$types$k$ts.OutputResolvedLinkTarget}
+ * @returns {OutputResolvedLinkTarget}
  */
 function createResolvedLinkTarget(
   target,
@@ -220,7 +219,7 @@ function createResolvedLinkTarget(
     fields.status = target.status;
   }
 
-  /** @type {$k$$l$output$j$view$k$types$k$ts.OutputResolvedLinkTarget} */
+  /** @type {OutputResolvedLinkTarget} */
   const resolved_target = {
     derived_summary: derived_summary ?? undefined,
     fields,
@@ -288,7 +287,7 @@ function getOutputNodeId(graph_node) {
 /**
  * @param {{ label: string, reference: number, target: { kind?: string, path: string, status?: string, title: string } }} resolved_link
  * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, document_node_ids?: BuildGraphResult['document_node_ids'], graph_nodes?: BuildGraphResult['nodes'], repo_config?: PatramRepoConfig }} command_options
- * @returns {$k$$l$output$j$view$k$types$k$ts.OutputResolvedLinkItem}
+ * @returns {OutputResolvedLinkItem}
  */
 function createResolvedLinkOutputItem(resolved_link, command_options) {
   const target_graph_node = resolveDocumentGraphNode(

package/lib/resolve-patram-graph-config.js

@@ -1,4 +1,5 @@
 /**
+ * @import { ClassDefinition } from './patram-config.js';
  * @import { PatramRepoConfig } from './load-patram-config.types.ts';
  * @import { PatramConfig } from './patram-config.types.ts';
  */
@@ -74,7 +75,7 @@ export function resolvePatramGraphConfig(repo_config) {
   const graph_config = parsePatramConfig({
     classes: {
       ...BUILT_IN_PATRAM_CONFIG.classes,
-      ...repo_config.classes,
+      ...collectGraphClassDefinitions(repo_config.classes),
     },
     mappings: {
       ...BUILT_IN_PATRAM_CONFIG.mappings,
@@ -88,7 +89,44 @@ export function resolvePatramGraphConfig(repo_config) {
 
   return {
     ...graph_config,
-    class_schemas: repo_config.class_schemas,
+    classes: mergeResolvedClasses(graph_config.classes, repo_config.classes),
     fields: repo_config.fields,
   };
 }
+
+/**
+ * @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 {Record<string, ClassDefinition>} graph_classes
+ * @param {PatramRepoConfig['classes']} repo_classes
+ * @returns {PatramConfig['classes']}
+ */
+function mergeResolvedClasses(graph_classes, repo_classes) {
+  /** @type {PatramConfig['classes']} */
+  const resolved_classes = {};
+
+  for (const [class_name, class_definition] of Object.entries(graph_classes)) {
+    resolved_classes[class_name] = {
+      ...class_definition,
+      schema: repo_classes?.[class_name]?.schema,
+    };
+  }
+
+  return resolved_classes;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patram",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "main": "./lib/patram.js",
   "exports": {