patram 0.4.0 → 0.6.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';
@@ -39,13 +40,37 @@ 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 MARKDOWN_STYLE_NAMES = [
+  'front_matter',
+  'visible_line',
+  'list_item',
+  'hidden_tag',
+];
+const MARKDOWN_STYLE_NAME_SET = new Set(MARKDOWN_STYLE_NAMES);
+const MIXED_STYLE_VALUES = new Set(['ignore', 'error']);
+
+/**
+ * @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 +78,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 +92,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 +102,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 +149,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 +159,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 +175,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,20 +227,39 @@ const metadata_field_schema = z.discriminatedUnion('type', [
     .strict(),
 ]);
 
+/**
+ * @typedef {z.output<typeof class_field_rule_schema>} ClassFieldRuleConfig
+ */
 const class_field_rule_schema = z
   .object({
+    markdown_styles: z.array(z.string().min(1)).optional(),
     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(),
     fields: z.record(z.string().min(1), class_field_rule_schema).default({}),
+    markdown_styles: z.array(z.string().min(1)).optional(),
+    mixed_styles: z.string().min(1).optional(),
     unknown_fields: z.enum(['ignore', 'error']).optional(),
   })
   .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 +268,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 +284,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 +321,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 +482,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 +510,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 +524,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 +554,8 @@ function validateFieldSchemaConfig(repo_config) {
   collectClassSchemaConfigDiagnostics(
     diagnostics,
     path_classes,
-    classes,
     fields,
-    repo_config.class_schemas,
+    classes,
   );
 
   return diagnostics;
@@ -586,7 +630,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 +640,6 @@ function normalizeRepoConfig(repo_config) {
     queries: { ...repo_config.queries },
   };
 
-  assignOptionalRepoConfigField(
-    normalized_config,
-    'class_schemas',
-    repo_config.class_schemas,
-  );
   assignOptionalRepoConfigField(
     normalized_config,
     'classes',
@@ -635,6 +674,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 +729,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,50 +921,58 @@ 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}".`,
-      ),
+    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 [class_name, schema_definition] of Object.entries(class_schemas)) {
     for (const field_name of Object.keys(schema_definition.fields)) {
       if (fields[field_name]) {
-        continue;
+        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}".`,
+          ),
+        );
       }
-
-      diagnostics.push(
-        createConfigDiagnostic(
-          `class_schemas.${class_name}.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 +982,92 @@ 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 {PatramDiagnostic[]} diagnostics
+ * @param {string} diagnostic_path
+ * @param {string[] | undefined} markdown_styles
+ */
+function collectMarkdownStylesDiagnostic(
+  diagnostics,
+  diagnostic_path,
+  markdown_styles,
+) {
+  if (markdown_styles === undefined) {
+    return;
+  }
+
+  if (markdown_styles.length === 0) {
+    diagnostics.push(
+      createConfigDiagnostic(
+        diagnostic_path,
+        'Markdown styles must contain at least one style.',
+      ),
+    );
+
+    return;
+  }
+
+  for (const markdown_style of markdown_styles) {
+    if (MARKDOWN_STYLE_NAME_SET.has(markdown_style)) {
+      continue;
+    }
+
+    diagnostics.push(
+      createConfigDiagnostic(
+        diagnostic_path,
+        `Unknown markdown style "${markdown_style}".`,
+      ),
+    );
+  }
+}
+
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {string} diagnostic_path
+ * @param {string | undefined} mixed_styles
+ */
+function collectMixedStylesDiagnostic(
+  diagnostics,
+  diagnostic_path,
+  mixed_styles,
+) {
+  if (mixed_styles === undefined || MIXED_STYLE_VALUES.has(mixed_styles)) {
+    return;
+  }
+
+  diagnostics.push(
+    createConfigDiagnostic(
+      diagnostic_path,
+      'Mixed styles must be "ignore" or "error".',
+    ),
+  );
+}
+
+/**
+ * @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