patram 0.7.0 → 0.9.0

package/lib/config/load-patram-config.js

@@ -0,0 +1,315 @@
+/**
+ * @import {
+ *   ClassFieldRuleConfig,
+ *   ClassSchemaConfig,
+ *   DerivedSummaryConfig,
+ *   DerivedSummaryFieldConfig,
+ *   DerivedSummaryScalar,
+ *   DerivedSummarySelectCaseConfig,
+ *   FieldDisplayConfig,
+ *   FieldQueryConfig,
+ *   MetadataFieldConfig,
+ *   PathClassConfig,
+ *   StoredQueryConfig,
+ * } from './schema.js';
+ */
+
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import process from 'node:process';
+
+import { CONFIG_FILE_NAME, patram_repo_config_schema } from './schema.js';
+import { createDefaultRepoConfig, normalizeRepoConfig } from './defaults.js';
+import {
+  validateDerivedSummaries,
+  validateFieldSchemaConfig,
+  validateGraphSchema,
+  validateLegacyConfigShape,
+  validateStoredQueries,
+} from './validation.js';
+
+/**
+ * Repo config loading.
+ *
+ * Reads `.patram.json`, applies defaults, and validates repo config and graph
+ * schema before command execution.
+ *
+ * Kind: config
+ * Status: active
+ * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../../docs/decisions/single-config-file.md
+ * Decided by: ../../docs/decisions/optional-config-default-scan.md
+ * @patram
+ * @see {@link ./schema.js}
+ * @see {@link ./validation.js}
+ */
+
+/**
+ * @typedef {object} PatramDiagnostic
+ * @property {string} code
+ * @property {number} column
+ * @property {'error'} level
+ * @property {number} line
+ * @property {string} message
+ * @property {string} path
+ */
+
+/**
+ * @typedef {object} LoadPatramConfigResult
+ * @property {import('./schema.js').PatramRepoConfig | null} config
+ * @property {string} config_path
+ * @property {PatramDiagnostic[]} diagnostics
+ */
+
+/**
+ * @typedef {import('./schema.js').StoredQueryConfig} StoredQueryConfig
+ * @typedef {import('./schema.js').FieldDisplayConfig} FieldDisplayConfig
+ * @typedef {import('./schema.js').FieldQueryConfig} FieldQueryConfig
+ * @typedef {import('./schema.js').MetadataFieldConfig} MetadataFieldConfig
+ * @typedef {import('./schema.js').ClassFieldRuleConfig} ClassFieldRuleConfig
+ * @typedef {import('./schema.js').ClassSchemaConfig} ClassSchemaConfig
+ * @typedef {import('./schema.js').PathClassConfig} PathClassConfig
+ * @typedef {import('./schema.js').DerivedSummaryScalar} DerivedSummaryScalar
+ * @typedef {import('./schema.js').DerivedSummarySelectCaseConfig} DerivedSummarySelectCaseConfig
+ * @typedef {import('./schema.js').DerivedSummaryFieldConfig} DerivedSummaryFieldConfig
+ * @typedef {import('./schema.js').DerivedSummaryConfig} DerivedSummaryConfig
+ * @typedef {import('./schema.js').PatramRepoConfig} PatramRepoConfig
+ */
+
+/**
+ * Load and validate the repo Patram config.
+ *
+ * @param {string} [project_directory]
+ * @returns {Promise<LoadPatramConfigResult>}
+ */
+export async function loadPatramConfig(project_directory = process.cwd()) {
+  const config_file_path = resolve(project_directory, CONFIG_FILE_NAME);
+  const config_source = await readConfigSource(config_file_path);
+
+  if (config_source === null) {
+    return createLoadResult(createDefaultRepoConfig(), []);
+  }
+
+  const parse_result = parseConfigJson(config_source);
+
+  if (!parse_result.success) {
+    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) {
+    return createLoadResult(
+      null,
+      config_result.error.issues.map(createValidationDiagnostic),
+    );
+  }
+
+  const graph_schema_diagnostics = validateGraphSchema(config_result.data);
+
+  if (graph_schema_diagnostics.length > 0) {
+    return createLoadResult(null, graph_schema_diagnostics);
+  }
+
+  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);
+
+  if (derived_summary_diagnostics.length > 0) {
+    return createLoadResult(null, derived_summary_diagnostics);
+  }
+
+  return createLoadResult(normalized_config, []);
+}
+
+/**
+ * @param {string} config_file_path
+ * @returns {Promise<string | null>}
+ */
+async function readConfigSource(config_file_path) {
+  try {
+    return await readFile(config_file_path, 'utf8');
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return null;
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * @param {string} config_source
+ * @returns {{ success: true, value: unknown } | { success: false, diagnostic: PatramDiagnostic }}
+ */
+function parseConfigJson(config_source) {
+  try {
+    return {
+      success: true,
+      value: JSON.parse(config_source),
+    };
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      return {
+        diagnostic: createInvalidJsonDiagnostic(config_source, error),
+        success: false,
+      };
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * @param {import('./schema.js').PatramRepoConfig | null} config
+ * @param {PatramDiagnostic[]} diagnostics
+ * @returns {LoadPatramConfigResult}
+ */
+function createLoadResult(config, diagnostics) {
+  return {
+    config,
+    config_path: CONFIG_FILE_NAME,
+    diagnostics,
+  };
+}
+
+/**
+ * @param {string} config_source
+ * @param {SyntaxError} error
+ * @returns {PatramDiagnostic}
+ */
+function createInvalidJsonDiagnostic(config_source, error) {
+  const origin = getJsonSyntaxOrigin(config_source, error.message);
+
+  return {
+    code: 'config.invalid_json',
+    column: origin.column,
+    level: 'error',
+    line: origin.line,
+    message: 'Invalid JSON syntax.',
+    path: CONFIG_FILE_NAME,
+  };
+}
+
+/**
+ * @param {import('zod').core.$ZodIssue} issue
+ * @returns {PatramDiagnostic}
+ */
+function createValidationDiagnostic(issue) {
+  const issue_path = formatIssuePath(issue.path);
+
+  if (issue_path) {
+    return {
+      code: 'config.invalid',
+      column: 1,
+      level: 'error',
+      line: 1,
+      message: `Invalid config at "${issue_path}": ${issue.message}`,
+      path: CONFIG_FILE_NAME,
+    };
+  }
+
+  return {
+    code: 'config.invalid',
+    column: 1,
+    level: 'error',
+    line: 1,
+    message: `Invalid config: ${issue.message}`,
+    path: CONFIG_FILE_NAME,
+  };
+}
+
+/**
+ * @param {unknown} error
+ * @returns {error is NodeJS.ErrnoException}
+ */
+function isMissingFileError(error) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  return 'code' in error && error.code === 'ENOENT';
+}
+
+/**
+ * @param {string} config_source
+ * @param {string} error_message
+ * @returns {{ line: number, column: number }}
+ */
+function getJsonSyntaxOrigin(config_source, error_message) {
+  const position_match = error_message.match(/position (?<offset>\d+)/du);
+
+  if (position_match?.groups?.offset) {
+    const offset = Number.parseInt(position_match.groups.offset, 10);
+
+    return getLineAndColumnFromOffset(config_source, offset);
+  }
+
+  const token_match = error_message.match(/Unexpected token '(?<token>.)'/u);
+
+  if (token_match?.groups?.token) {
+    const offset = config_source.lastIndexOf(token_match.groups.token);
+
+    if (offset >= 0) {
+      return getLineAndColumnFromOffset(config_source, offset);
+    }
+  }
+
+  return {
+    column: 1,
+    line: 1,
+  };
+}
+
+/**
+ * @param {(string | number | symbol | undefined)[]} issue_path
+ * @returns {string}
+ */
+function formatIssuePath(issue_path) {
+  return issue_path.map(String).join('.');
+}
+
+/**
+ * @param {string} source_text
+ * @param {number} offset
+ * @returns {{ line: number, column: number }}
+ */
+function getLineAndColumnFromOffset(source_text, offset) {
+  let line_number = 1;
+  let column_number = 1;
+
+  for (const character of source_text.slice(0, offset)) {
+    if (character === '\n') {
+      line_number += 1;
+      column_number = 1;
+      continue;
+    }
+
+    column_number += 1;
+  }
+
+  return {
+    column: column_number,
+    line: line_number,
+  };
+}

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

@@ -0,0 +1,45 @@
+export type StoredQueryConfig = import('./schema.js').StoredQueryConfig;
+export type FieldDisplayConfig = import('./schema.js').FieldDisplayConfig;
+export type FieldQueryConfig = import('./schema.js').FieldQueryConfig;
+export type FieldValueTypeName = import('./schema.js').MetadataFieldConfig['type'];
+export type MetadataFieldConfig = import('./schema.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('./schema.js').ClassFieldRuleConfig;
+export type DirectiveTypeConfig = MetadataFieldConfig;
+export type MetadataDirectiveRuleConfig = ClassFieldRuleConfig;
+export type ClassSchemaConfig = import('./schema.js').ClassSchemaConfig;
+export type MetadataSchemaConfig = ClassSchemaConfig;
+export type PathClassConfig = import('./schema.js').PathClassConfig;
+export type DerivedSummaryScalar = import('./schema.js').DerivedSummaryScalar;
+export type DerivedSummarySelectCaseConfig = import('./schema.js').DerivedSummarySelectCaseConfig;
+export type DerivedSummaryFieldConfig = import('./schema.js').DerivedSummaryFieldConfig;
+export type DerivedSummaryCountFieldConfig = Extract<DerivedSummaryFieldConfig, {
+    count: unknown;
+}>;
+export type DerivedSummarySelectFieldConfig = Extract<DerivedSummaryFieldConfig, {
+    select: unknown;
+}>;
+export type DerivedSummaryConfig = import('./schema.js').DerivedSummaryConfig;
+export type PatramRepoConfig = import('./schema.js').PatramRepoConfig;
+export type PatramDiagnostic = import('./load-patram-config.js').PatramDiagnostic;
+export type LoadPatramConfigResult = import('./load-patram-config.js').LoadPatramConfigResult;

package/lib/{patram-config.d.ts → config/patram-config.d.ts}

@@ -41,10 +41,39 @@ export const mapping_definition_schema: z.ZodObject<{
         }>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+export type ClassDefinition = z.output<typeof class_definition_schema>;
+export type RelationDefinition = z.output<typeof relation_definition_schema>;
+export type MappingNodeDefinition = z.output<typeof mapping_node_schema>;
+export type MappingEmitDefinition = z.output<typeof mapping_emit_schema>;
+export type MappingDefinition = z.output<typeof mapping_definition_schema>;
+export type PatramGraphConfig = z.output<typeof patram_config_schema>;
+import { z } from 'zod';
+/**
+ * @typedef {z.output<typeof mapping_node_schema>} MappingNodeDefinition
+ */
+declare const mapping_node_schema: z.ZodObject<{
+    class: z.ZodString;
+    field: z.ZodString;
+    key: z.ZodOptional<z.ZodEnum<{
+        path: "path";
+        value: "value";
+    }>>;
+}, z.core.$strict>;
+/**
+ * @typedef {z.output<typeof mapping_emit_schema>} MappingEmitDefinition
+ */
+declare const mapping_emit_schema: z.ZodObject<{
+    relation: z.ZodString;
+    target: z.ZodEnum<{
+        path: "path";
+        value: "value";
+    }>;
+    target_class: z.ZodString;
+}, z.core.$strict>;
 /**
- * @typedef {z.output<typeof patramConfigSchema>} PatramGraphConfig
+ * @typedef {z.output<typeof patram_config_schema>} PatramGraphConfig
  */
-export const patramConfigSchema: z.ZodObject<{
+declare const patram_config_schema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodURL>;
     classes: z.ZodRecord<z.ZodString, z.ZodObject<{
         builtin: z.ZodOptional<z.ZodBoolean>;
@@ -74,33 +103,4 @@ export const patramConfigSchema: z.ZodObject<{
         to: z.ZodArray<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
-export type ClassDefinition = z.output<typeof class_definition_schema>;
-export type RelationDefinition = z.output<typeof relation_definition_schema>;
-export type MappingNodeDefinition = z.output<typeof mapping_node_schema>;
-export type MappingEmitDefinition = z.output<typeof mapping_emit_schema>;
-export type MappingDefinition = z.output<typeof mapping_definition_schema>;
-export type PatramGraphConfig = z.output<typeof patramConfigSchema>;
-import { z } from 'zod';
-/**
- * @typedef {z.output<typeof mapping_node_schema>} MappingNodeDefinition
- */
-declare const mapping_node_schema: z.ZodObject<{
-    class: z.ZodString;
-    field: z.ZodString;
-    key: z.ZodOptional<z.ZodEnum<{
-        path: "path";
-        value: "value";
-    }>>;
-}, z.core.$strict>;
-/**
- * @typedef {z.output<typeof mapping_emit_schema>} MappingEmitDefinition
- */
-declare const mapping_emit_schema: z.ZodObject<{
-    relation: z.ZodString;
-    target: z.ZodEnum<{
-        path: "path";
-        value: "value";
-    }>;
-    target_class: z.ZodString;
-}, z.core.$strict>;
 export {};

package/lib/{patram-config.js → config/patram-config.js}

@@ -65,9 +65,9 @@ export const mapping_definition_schema = z
   .superRefine(validateMappingDefinition);
 
 /**
- * @typedef {z.output<typeof patramConfigSchema>} PatramGraphConfig
+ * @typedef {z.output<typeof patram_config_schema>} PatramGraphConfig
  */
-export const patramConfigSchema = z
+const patram_config_schema = z
   .object({
     $schema: z.url().optional(),
     classes: z.record(CLASS_NAME_SCHEMA, class_definition_schema),
@@ -84,7 +84,7 @@ export const patramConfigSchema = z
  * @returns {PatramGraphConfig}
  */
 export function parsePatramConfig(config_json) {
-  return patramConfigSchema.parse(config_json);
+  return patram_config_schema.parse(config_json);
 }
 
 /**

package/lib/{patram-config.types.d.ts → config/patram-config.types.d.ts}

@@ -1,4 +1,4 @@
-import type { ClassSchemaConfig, MetadataFieldConfig } from './load-patram-config.types.ts';
+import type { ClassSchemaConfig, MetadataFieldConfig } from './load-patram-config.types.d.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;

package/lib/{resolve-patram-graph-config.d.ts → config/resolve-patram-graph-config.d.ts}

@@ -5,5 +5,5 @@
  * @returns {PatramConfig}
  */
 export function resolvePatramGraphConfig(repo_config: PatramRepoConfig): PatramConfig;
-import type { PatramRepoConfig } from './load-patram-config.types.ts';
-import type { PatramConfig } from './patram-config.types.ts';
+import type { PatramRepoConfig } from './load-patram-config.types.d.ts';
+import type { PatramConfig } from './patram-config.types.d.ts';

package/lib/{resolve-patram-graph-config.js → config/resolve-patram-graph-config.js}

@@ -14,11 +14,11 @@ import { parsePatramConfig } from './patram-config.js';
  *
  * Kind: config
  * Status: active
- * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../docs/decisions/graph-materialization.md
+ * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../../docs/decisions/graph-materialization.md
  * @patram
  * @see {@link ./load-patram-config.js}
- * @see {@link ../docs/graph-v0.md}
+ * @see {@link ../../docs/graph-v0.md}
  */
 
 const BUILT_IN_PATRAM_CONFIG = {