patram 0.10.0 → 0.12.0

package/lib/config/manage-stored-queries.js

@@ -0,0 +1,300 @@
+/**
+ * @import { CliParseError } from '../cli/arguments.types.ts';
+ * @import {
+ *   PatramDiagnostic,
+ *   PatramRepoConfig,
+ * } from './load-patram-config.types.ts';
+ */
+
+import { resolve } from 'node:path';
+
+import { loadPatramConfig } from './load-patram-config.js';
+import {
+  createStoredQueryDefinition,
+  createUpdatedStoredQueryDefinition,
+  ensureRawQueries,
+  loadRawConfig,
+  persistStoredQueryMutation,
+  rawQueryValueToRecord,
+} from './manage-stored-queries-helpers.js';
+import { CONFIG_FILE_NAME } from './schema.js';
+import { createUnknownStoredQueryError } from '../graph/query/resolve.js';
+
+/**
+ * @typedef {{
+ *   action: 'add',
+ *   cypher?: string,
+ *   description?: string,
+ *   name: string,
+ * } | {
+ *   action: 'remove',
+ *   name: string,
+ * } | {
+ *   action: 'update',
+ *   cypher?: string,
+ *   description?: string,
+ *   name: string,
+ *   next_name?: string,
+ * }} StoredQueryMutation
+ */
+
+/**
+ * @typedef {{
+ *   action: 'added',
+ *   name: string,
+ * } | {
+ *   action: 'removed',
+ *   name: string,
+ * } | {
+ *   action: 'updated',
+ *   name: string,
+ *   previous_name?: string,
+ * }} StoredQueryMutationResult
+ */
+
+/**
+ * @param {string} project_directory
+ * @param {StoredQueryMutation} stored_query_mutation
+ * @returns {Promise<
+ *   | { success: true, value: StoredQueryMutationResult }
+ *   | { diagnostics: PatramDiagnostic[], success: false }
+ *   | { error: CliParseError, success: false }
+ * >}
+ */
+export async function manageStoredQueries(
+  project_directory,
+  stored_query_mutation,
+) {
+  const load_result = await loadPatramConfig(project_directory);
+
+  if (load_result.diagnostics.length > 0) {
+    return {
+      diagnostics: load_result.diagnostics,
+      success: false,
+    };
+  }
+
+  const repo_config = load_result.config;
+
+  if (!repo_config) {
+    throw new Error('Expected a valid Patram repo config.');
+  }
+
+  const config_file_path = resolve(project_directory, CONFIG_FILE_NAME);
+  const raw_config_result = await loadRawConfig(config_file_path);
+
+  if (!raw_config_result.success) {
+    return {
+      diagnostics: [raw_config_result.diagnostic],
+      success: false,
+    };
+  }
+
+  if (stored_query_mutation.action === 'add') {
+    return applyAddStoredQuery(
+      config_file_path,
+      raw_config_result.value,
+      repo_config,
+      stored_query_mutation,
+    );
+  }
+
+  if (stored_query_mutation.action === 'remove') {
+    return applyRemoveStoredQuery(
+      config_file_path,
+      raw_config_result.value,
+      repo_config,
+      stored_query_mutation,
+    );
+  }
+
+  return applyUpdateStoredQuery(
+    config_file_path,
+    raw_config_result.value,
+    repo_config,
+    stored_query_mutation,
+  );
+}
+
+/**
+ * @param {string} config_file_path
+ * @param {Record<string, unknown>} raw_config
+ * @param {PatramRepoConfig} repo_config
+ * @param {{ cypher?: string, description?: string, name: string }} stored_query_mutation
+ * @returns {Promise<
+ *   | { success: true, value: StoredQueryMutationResult }
+ *   | { diagnostics: PatramDiagnostic[], success: false }
+ *   | { error: CliParseError, success: false }
+ * >}
+ */
+async function applyAddStoredQuery(
+  config_file_path,
+  raw_config,
+  repo_config,
+  stored_query_mutation,
+) {
+  if (repo_config.queries[stored_query_mutation.name]) {
+    return {
+      error: {
+        code: 'message',
+        message: `Stored query already exists: ${stored_query_mutation.name}.`,
+      },
+      success: false,
+    };
+  }
+
+  const raw_queries = ensureRawQueries(raw_config);
+  const query_text = stored_query_mutation.cypher;
+
+  if (!query_text) {
+    throw new Error('Expected add mutations to contain query text.');
+  }
+
+  raw_queries[stored_query_mutation.name] = createStoredQueryDefinition(
+    query_text,
+    stored_query_mutation.description,
+  );
+
+  return persistStoredQueryMutation(config_file_path, raw_config, {
+    action: 'added',
+    name: stored_query_mutation.name,
+  });
+}
+
+/**
+ * @param {string} config_file_path
+ * @param {Record<string, unknown>} raw_config
+ * @param {PatramRepoConfig} repo_config
+ * @param {{ name: string }} stored_query_mutation
+ * @returns {Promise<
+ *   | { success: true, value: StoredQueryMutationResult }
+ *   | { diagnostics: PatramDiagnostic[], success: false }
+ *   | { error: CliParseError, success: false }
+ * >}
+ */
+async function applyRemoveStoredQuery(
+  config_file_path,
+  raw_config,
+  repo_config,
+  stored_query_mutation,
+) {
+  if (!repo_config.queries[stored_query_mutation.name]) {
+    return {
+      error: createQueryMutationUnknownStoredQueryError(
+        stored_query_mutation.name,
+        Object.keys(repo_config.queries),
+        'remove',
+      ),
+      success: false,
+    };
+  }
+
+  const raw_queries = ensureRawQueries(raw_config);
+  delete raw_queries[stored_query_mutation.name];
+
+  return persistStoredQueryMutation(config_file_path, raw_config, {
+    action: 'removed',
+    name: stored_query_mutation.name,
+  });
+}
+
+/**
+ * @param {string} config_file_path
+ * @param {Record<string, unknown>} raw_config
+ * @param {PatramRepoConfig} repo_config
+ * @param {{ cypher?: string, description?: string, name: string, next_name?: string }} stored_query_mutation
+ * @returns {Promise<
+ *   | { success: true, value: StoredQueryMutationResult }
+ *   | { diagnostics: PatramDiagnostic[], success: false }
+ *   | { error: CliParseError, success: false }
+ * >}
+ */
+async function applyUpdateStoredQuery(
+  config_file_path,
+  raw_config,
+  repo_config,
+  stored_query_mutation,
+) {
+  const existing_query = repo_config.queries[stored_query_mutation.name];
+
+  if (!existing_query) {
+    return {
+      error: createQueryMutationUnknownStoredQueryError(
+        stored_query_mutation.name,
+        Object.keys(repo_config.queries),
+        'update',
+      ),
+      success: false,
+    };
+  }
+
+  const next_name =
+    stored_query_mutation.next_name ?? stored_query_mutation.name;
+
+  if (
+    next_name !== stored_query_mutation.name &&
+    repo_config.queries[next_name]
+  ) {
+    return {
+      error: {
+        code: 'message',
+        message: `Stored query already exists: ${next_name}.`,
+      },
+      success: false,
+    };
+  }
+
+  const raw_queries = ensureRawQueries(raw_config);
+  const raw_query_value = rawQueryValueToRecord(
+    raw_queries[stored_query_mutation.name],
+  );
+  const next_query = createUpdatedStoredQueryDefinition(
+    raw_query_value,
+    existing_query,
+    stored_query_mutation,
+  );
+
+  if (next_name !== stored_query_mutation.name) {
+    delete raw_queries[stored_query_mutation.name];
+  }
+
+  raw_queries[next_name] = next_query;
+
+  return persistStoredQueryMutation(config_file_path, raw_config, {
+    action: 'updated',
+    name: next_name,
+    previous_name:
+      next_name === stored_query_mutation.name
+        ? undefined
+        : stored_query_mutation.name,
+  });
+}
+
+/**
+ * @param {string} stored_query_name
+ * @param {string[]} stored_query_names
+ * @param {'remove' | 'update'} subcommand_name
+ * @returns {CliParseError}
+ */
+function createQueryMutationUnknownStoredQueryError(
+  stored_query_name,
+  stored_query_names,
+  subcommand_name,
+) {
+  const parse_error = createUnknownStoredQueryError(
+    stored_query_name,
+    stored_query_names,
+  );
+
+  if (
+    parse_error.code !== 'unknown_stored_query' ||
+    parse_error.suggestion === undefined
+  ) {
+    return parse_error;
+  }
+
+  return {
+    ...parse_error,
+    next_path: `patram queries ${subcommand_name} ${parse_error.suggestion}`,
+  };
+}

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

@@ -5,49 +5,28 @@
  * @returns {PatramGraphConfig}
  */
 export function parsePatramConfig(config_json: unknown): PatramGraphConfig;
+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 class_definition_schema>} ClassDefinition
  */
-export const class_definition_schema: z.ZodObject<{
+declare const class_definition_schema: z.ZodObject<{
     builtin: z.ZodOptional<z.ZodBoolean>;
     label: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 /**
  * @typedef {z.output<typeof relation_definition_schema>} RelationDefinition
  */
-export const relation_definition_schema: z.ZodObject<{
+declare const relation_definition_schema: z.ZodObject<{
     builtin: z.ZodOptional<z.ZodBoolean>;
     from: z.ZodArray<z.ZodString>;
     to: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
-/**
- * @typedef {z.output<typeof mapping_definition_schema>} MappingDefinition
- */
-export const mapping_definition_schema: z.ZodObject<{
-    emit: z.ZodOptional<z.ZodObject<{
-        relation: z.ZodString;
-        target: z.ZodEnum<{
-            path: "path";
-            value: "value";
-        }>;
-        target_class: z.ZodString;
-    }, z.core.$strict>>;
-    node: z.ZodOptional<z.ZodObject<{
-        class: z.ZodString;
-        field: z.ZodString;
-        key: z.ZodOptional<z.ZodEnum<{
-            path: "path";
-            value: "value";
-        }>>;
-    }, 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
  */
@@ -55,8 +34,8 @@ declare const mapping_node_schema: z.ZodObject<{
     class: z.ZodString;
     field: z.ZodString;
     key: z.ZodOptional<z.ZodEnum<{
-        path: "path";
         value: "value";
+        path: "path";
     }>>;
 }, z.core.$strict>;
 /**
@@ -65,11 +44,32 @@ declare const mapping_node_schema: z.ZodObject<{
 declare const mapping_emit_schema: z.ZodObject<{
     relation: z.ZodString;
     target: z.ZodEnum<{
-        path: "path";
         value: "value";
+        path: "path";
     }>;
     target_class: z.ZodString;
 }, z.core.$strict>;
+/**
+ * @typedef {z.output<typeof mapping_definition_schema>} MappingDefinition
+ */
+declare const mapping_definition_schema: z.ZodObject<{
+    emit: z.ZodOptional<z.ZodObject<{
+        relation: z.ZodString;
+        target: z.ZodEnum<{
+            value: "value";
+            path: "path";
+        }>;
+        target_class: z.ZodString;
+    }, z.core.$strict>>;
+    node: z.ZodOptional<z.ZodObject<{
+        class: z.ZodString;
+        field: z.ZodString;
+        key: z.ZodOptional<z.ZodEnum<{
+            value: "value";
+            path: "path";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 /**
  * @typedef {z.output<typeof patram_config_schema>} PatramGraphConfig
  */
@@ -83,8 +83,8 @@ declare const patram_config_schema: z.ZodObject<{
         emit: z.ZodOptional<z.ZodObject<{
             relation: z.ZodString;
             target: z.ZodEnum<{
-                path: "path";
                 value: "value";
+                path: "path";
             }>;
             target_class: z.ZodString;
         }, z.core.$strict>>;
@@ -92,8 +92,8 @@ declare const patram_config_schema: z.ZodObject<{
             class: z.ZodString;
             field: z.ZodString;
             key: z.ZodOptional<z.ZodEnum<{
-                path: "path";
                 value: "value";
+                path: "path";
             }>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;

package/lib/config/patram-config.js

@@ -13,7 +13,7 @@ const TARGET_SCHEMA = z.enum(['path', 'value']);
 /**
  * @typedef {z.output<typeof class_definition_schema>} ClassDefinition
  */
-export const class_definition_schema = z
+const class_definition_schema = z
   .object({
     builtin: z.boolean().optional(),
     label: z.string().min(1).optional(),
@@ -23,7 +23,7 @@ export const class_definition_schema = z
 /**
  * @typedef {z.output<typeof relation_definition_schema>} RelationDefinition
  */
-export const relation_definition_schema = z
+const relation_definition_schema = z
   .object({
     builtin: z.boolean().optional(),
     from: z.array(CLASS_NAME_SCHEMA).min(1),
@@ -56,7 +56,7 @@ const mapping_emit_schema = z
 /**
  * @typedef {z.output<typeof mapping_definition_schema>} MappingDefinition
  */
-export const mapping_definition_schema = z
+const mapping_definition_schema = z
   .object({
     emit: mapping_emit_schema.optional(),
     node: mapping_node_schema.optional(),

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

@@ -1,14 +1,8 @@
-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;
-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;
+import type { MetadataFieldConfig, PatramRepoConfig, TypeDefinitionConfig } from './load-patram-config.types.d.ts';
+export type PatramTypeConfig = TypeDefinitionConfig & {
+    label?: string;
 };
-export type PatramConfig = Omit<PatramGraphConfig, 'classes'> & {
-    classes: Record<string, PatramClassConfig>;
+export type PatramConfig = PatramRepoConfig & {
     fields?: Record<string, MetadataFieldConfig>;
+    types?: Record<string, PatramTypeConfig>;
 };

package/lib/config/resolve-patram-graph-config.d.ts

@@ -1,5 +1,9 @@
 /**
- * Merge built-in Patram graph semantics with repo-defined schema.
+ * @import { PatramConfig } from './patram-config.types.d.ts';
+ * @import { PatramRepoConfig } from './load-patram-config.types.d.ts';
+ */
+/**
+ * Normalize the loaded repo config for graph materialization.
  *
  * @param {PatramRepoConfig} repo_config
  * @returns {PatramConfig}

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

@@ -1,132 +1,16 @@
 /**
- * @import { ClassDefinition } from './patram-config.js';
- * @import { PatramRepoConfig } from './load-patram-config.types.ts';
  * @import { PatramConfig } from './patram-config.types.ts';
+ * @import { PatramRepoConfig } from './load-patram-config.types.ts';
  */
 
-import { parsePatramConfig } from './patram-config.js';
-
-/**
- * Built-in graph semantics.
- *
- * Merges repo-defined graph config with Patram's built-in document and link
- * semantics before graph materialization.
- *
- * Kind: config
- * Status: active
- * 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}
- */
-
-const BUILT_IN_PATRAM_CONFIG = {
-  classes: {
-    document: {
-      builtin: true,
-      label: 'Document',
-    },
-  },
-  mappings: {
-    'document.title': {
-      node: {
-        class: 'document',
-        field: 'title',
-      },
-    },
-    'document.description': {
-      node: {
-        class: 'document',
-        field: 'description',
-      },
-    },
-    'jsdoc.link': {
-      emit: {
-        relation: 'links_to',
-        target: 'path',
-        target_class: 'document',
-      },
-    },
-    'markdown.link': {
-      emit: {
-        relation: 'links_to',
-        target: 'path',
-        target_class: 'document',
-      },
-    },
-  },
-  relations: {
-    links_to: {
-      builtin: true,
-      from: ['document'],
-      to: ['document'],
-    },
-  },
-};
-
 /**
- * Merge built-in Patram graph semantics with repo-defined schema.
+ * Normalize the loaded repo config for graph materialization.
  *
  * @param {PatramRepoConfig} repo_config
  * @returns {PatramConfig}
  */
 export function resolvePatramGraphConfig(repo_config) {
-  const graph_config = parsePatramConfig({
-    classes: {
-      ...BUILT_IN_PATRAM_CONFIG.classes,
-      ...collectGraphClassDefinitions(repo_config.classes),
-    },
-    mappings: {
-      ...BUILT_IN_PATRAM_CONFIG.mappings,
-      ...repo_config.mappings,
-    },
-    relations: {
-      ...BUILT_IN_PATRAM_CONFIG.relations,
-      ...repo_config.relations,
-    },
-  });
-
   return {
-    ...graph_config,
-    classes: mergeResolvedClasses(graph_config.classes, repo_config.classes),
-    fields: repo_config.fields,
+    ...repo_config,
   };
 }
-
-/**
- * @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;
-}