patram 0.11.0 → 0.12.0

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

@@ -92,15 +92,16 @@ export async function persistStoredQueryMutation(
 }
 
 /**
- * @param {string} where_clause
+ * @param {string} query_text
  * @param {string | undefined} description
  * @returns {StoredQueryConfig}
  */
-export function createStoredQueryDefinition(where_clause, description) {
+export function createStoredQueryDefinition(query_text, description) {
   /** @type {StoredQueryConfig} */
   const stored_query = {
-    where: where_clause,
+    cypher: query_text,
   };
+
   const normalized_description = normalizeDescription(description);
 
   if (normalized_description !== undefined) {
@@ -113,7 +114,7 @@ export function createStoredQueryDefinition(where_clause, description) {
 /**
  * @param {Record<string, unknown> | null} raw_query_value
  * @param {StoredQueryConfig} existing_query
- * @param {{ description?: string, where?: string }} stored_query_mutation
+ * @param {{ cypher?: string, description?: string }} stored_query_mutation
  * @returns {StoredQueryConfig}
  */
 export function createUpdatedStoredQueryDefinition(
@@ -121,36 +122,13 @@ export function createUpdatedStoredQueryDefinition(
   existing_query,
   stored_query_mutation,
 ) {
-  /** @type {StoredQueryConfig} */
-  const next_query = {
-    where: existing_query.where,
-  };
-
-  if (
-    raw_query_value &&
-    Object.hasOwn(raw_query_value, 'description') &&
-    typeof raw_query_value.description === 'string' &&
-    raw_query_value.description.length > 0
-  ) {
-    next_query.description = raw_query_value.description;
-  } else if (
-    typeof existing_query.description === 'string' &&
-    existing_query.description.length > 0
-  ) {
-    next_query.description = existing_query.description;
-  }
-
-  if (stored_query_mutation.where !== undefined) {
-    next_query.where = stored_query_mutation.where;
-  }
+  const next_query = createBaseStoredQueryDefinition(
+    raw_query_value,
+    existing_query,
+  );
 
-  if (stored_query_mutation.description !== undefined) {
-    if (stored_query_mutation.description.length === 0) {
-      delete next_query.description;
-    } else {
-      next_query.description = stored_query_mutation.description;
-    }
-  }
+  applyStoredQueryTextMutation(next_query, stored_query_mutation);
+  applyStoredQueryDescriptionMutation(next_query, stored_query_mutation);
 
   return next_query;
 }
@@ -205,6 +183,86 @@ function normalizeDescription(description) {
   return description;
 }
 
+/**
+ * @param {Record<string, unknown> | null} raw_query_value
+ * @param {StoredQueryConfig} existing_query
+ * @returns {StoredQueryConfig}
+ */
+function createBaseStoredQueryDefinition(raw_query_value, existing_query) {
+  /** @type {StoredQueryConfig} */
+  const next_query = {};
+
+  if (existing_query.cypher !== undefined) {
+    next_query.cypher = existing_query.cypher;
+  }
+
+  const description = resolveExistingDescription(
+    raw_query_value,
+    existing_query,
+  );
+
+  if (description !== undefined) {
+    next_query.description = description;
+  }
+
+  return next_query;
+}
+
+/**
+ * @param {StoredQueryConfig} next_query
+ * @param {{ cypher?: string, description?: string }} stored_query_mutation
+ */
+function applyStoredQueryTextMutation(next_query, stored_query_mutation) {
+  if (stored_query_mutation.cypher !== undefined) {
+    next_query.cypher = stored_query_mutation.cypher;
+  }
+}
+
+/**
+ * @param {StoredQueryConfig} next_query
+ * @param {{ cypher?: string, description?: string }} stored_query_mutation
+ */
+function applyStoredQueryDescriptionMutation(
+  next_query,
+  stored_query_mutation,
+) {
+  if (stored_query_mutation.description === undefined) {
+    return;
+  }
+
+  if (stored_query_mutation.description.length === 0) {
+    delete next_query.description;
+    return;
+  }
+
+  next_query.description = stored_query_mutation.description;
+}
+
+/**
+ * @param {Record<string, unknown> | null} raw_query_value
+ * @param {StoredQueryConfig} existing_query
+ * @returns {string | undefined}
+ */
+function resolveExistingDescription(raw_query_value, existing_query) {
+  if (
+    raw_query_value &&
+    Object.hasOwn(raw_query_value, 'description') &&
+    typeof raw_query_value.description === 'string' &&
+    raw_query_value.description.length > 0
+  ) {
+    return raw_query_value.description;
+  }
+
+  if (
+    typeof existing_query.description === 'string' &&
+    existing_query.description.length > 0
+  ) {
+    return existing_query.description;
+  }
+
+  return undefined;
+}
+
 /**
  * @returns {PatramDiagnostic}
  */

package/lib/config/manage-stored-queries.d.ts

@@ -1,18 +1,18 @@
 /**
  * @typedef {{
  *   action: 'add',
+ *   cypher?: string,
  *   description?: string,
  *   name: string,
- *   where: string,
  * } | {
  *   action: 'remove',
  *   name: string,
  * } | {
  *   action: 'update',
+ *   cypher?: string,
  *   description?: string,
  *   name: string,
  *   next_name?: string,
- *   where?: string,
  * }} StoredQueryMutation
  */
 /**
@@ -49,18 +49,18 @@ export function manageStoredQueries(project_directory: string, stored_query_muta
 }>;
 export type StoredQueryMutation = {
     action: "add";
+    cypher?: string;
     description?: string;
     name: string;
-    where: string;
 } | {
     action: "remove";
     name: string;
 } | {
     action: "update";
+    cypher?: string;
     description?: string;
     name: string;
     next_name?: string;
-    where?: string;
 };
 export type StoredQueryMutationResult = {
     action: "added";

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

@@ -23,18 +23,18 @@ import { createUnknownStoredQueryError } from '../graph/query/resolve.js';
 /**
  * @typedef {{
  *   action: 'add',
+ *   cypher?: string,
  *   description?: string,
  *   name: string,
- *   where: string,
  * } | {
  *   action: 'remove',
  *   name: string,
  * } | {
  *   action: 'update',
+ *   cypher?: string,
  *   description?: string,
  *   name: string,
  *   next_name?: string,
- *   where?: string,
  * }} StoredQueryMutation
  */
 
@@ -120,7 +120,7 @@ export async function manageStoredQueries(
  * @param {string} config_file_path
  * @param {Record<string, unknown>} raw_config
  * @param {PatramRepoConfig} repo_config
- * @param {{ description?: string, name: string, where: string }} stored_query_mutation
+ * @param {{ cypher?: string, description?: string, name: string }} stored_query_mutation
  * @returns {Promise<
  *   | { success: true, value: StoredQueryMutationResult }
  *   | { diagnostics: PatramDiagnostic[], success: false }
@@ -144,8 +144,14 @@ async function applyAddStoredQuery(
   }
 
   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(
-    stored_query_mutation.where,
+    query_text,
     stored_query_mutation.description,
   );
 
@@ -196,7 +202,7 @@ async function applyRemoveStoredQuery(
  * @param {string} config_file_path
  * @param {Record<string, unknown>} raw_config
  * @param {PatramRepoConfig} repo_config
- * @param {{ description?: string, name: string, next_name?: string, where?: string }} stored_query_mutation
+ * @param {{ cypher?: string, description?: string, name: string, next_name?: string }} stored_query_mutation
  * @returns {Promise<
  *   | { success: true, value: StoredQueryMutationResult }
  *   | { diagnostics: PatramDiagnostic[], success: false }

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;
-}