patram 0.2.0 → 0.4.0

package/lib/build-graph-identity.js

@@ -1,53 +1,24 @@
+/** @import * as $k$$l$document$j$node$j$identity$k$js from './document-node-identity.js'; */
 /**
  * @import { GraphNode } from './build-graph.types.ts';
  * @import { PatramClaim } from './parse-claims.types.ts';
- * @import { MappingDefinition } from './patram-config.types.ts';
  */
 
 import { posix } from 'node:path';
 
-/**
- * Collect semantic entity keys defined by canonical documents.
- *
- * @param {Record<string, MappingDefinition>} mappings
- * @param {PatramClaim[]} claims
- * @returns {Map<string, string>}
- */
-export function collectDocumentEntityKeys(mappings, claims) {
-  /** @type {Map<string, string>} */
-  const document_entity_keys = new Map();
-
-  for (const claim of claims) {
-    const mapping_definition = resolveMappingDefinition(mappings, claim);
+import { normalizeRepoRelativePath } from './document-node-identity.js';
 
-    if (mapping_definition?.node?.key !== 'value') {
-      continue;
-    }
-
-    const source_path = normalizeRepoRelativePath(claim.origin.path);
-    const entity_map_key = getDocumentEntityMapKey(
-      source_path,
-      mapping_definition.node.kind,
-    );
-    const entity_key = getStringClaimValue(claim);
-    const existing_entity_key = document_entity_keys.get(entity_map_key);
-
-    if (existing_entity_key && existing_entity_key !== entity_key) {
-      throw new Error(
-        `Document "${source_path}" defines multiple ${mapping_definition.node.kind} ids.`,
-      );
-    }
-
-    document_entity_keys.set(entity_map_key, entity_key);
-  }
-
-  return document_entity_keys;
-}
+export {
+  collectDocumentEntityKeys,
+  collectDocumentNodeReferences,
+  normalizeRepoRelativePath,
+  resolveDocumentNodeId,
+} from './document-node-identity.js';
 
 /**
  * Resolve the node key for one mapped claim.
  *
- * @param {{ field: string, key?: 'path' | 'value', kind: string }} node_mapping
+ * @param {{ field: string, key?: 'path' | 'value', class: string }} node_mapping
  * @param {PatramClaim} claim
  * @param {Map<string, string>} document_entity_keys
  * @returns {string}
@@ -55,7 +26,7 @@ export function collectDocumentEntityKeys(mappings, claims) {
 export function resolveNodeKey(node_mapping, claim, document_entity_keys) {
   const source_key = normalizeRepoRelativePath(claim.origin.path);
 
-  if (node_mapping.kind === 'document') {
+  if (node_mapping.class === 'document') {
     return source_key;
   }
 
@@ -65,7 +36,7 @@ export function resolveNodeKey(node_mapping, claim, document_entity_keys) {
 
   return (
     document_entity_keys.get(
-      getDocumentEntityMapKey(source_key, node_mapping.kind),
+      getDocumentEntityMapKey(source_key, node_mapping.class),
     ) ?? source_key
   );
 }
@@ -73,123 +44,95 @@ export function resolveNodeKey(node_mapping, claim, document_entity_keys) {
 /**
  * Resolve one edge target key and canonical path.
  *
- * @param {string} target_kind
+ * @param {string} target_class
  * @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 {Set<string>} document_paths
- * @returns {{ key: string, path?: string }}
+ * @returns {{ class_name: string, key: string, path?: string }}
  */
 export function resolveTargetReference(
-  target_kind,
+  target_class,
   target_type,
   claim,
   document_entity_keys,
+  document_node_references,
   document_paths,
 ) {
   if (target_type === 'value') {
-    return resolveValueTargetReference(target_kind, claim);
+    return resolveValueTargetReference(target_class, claim);
   }
 
   return resolvePathTargetReference(
-    target_kind,
+    target_class,
     claim,
     document_entity_keys,
+    document_node_references,
     document_paths,
   );
 }
 
 /**
- * Attach one canonical path to a non-document graph node.
+ * Attach one canonical path to a graph node.
  *
  * @param {GraphNode} graph_node
  * @param {string | undefined} source_path
  */
-export function setNonDocumentPath(graph_node, source_path) {
-  if (!source_path || graph_node.kind === 'document') {
+export function setCanonicalPath(graph_node, source_path) {
+  if (!source_path) {
     return;
   }
 
-  if (!graph_node.path) {
+  if (!graph_node.$path) {
+    graph_node.$path = source_path;
     graph_node.path = source_path;
     return;
   }
 
-  if (graph_node.path !== source_path) {
+  if (graph_node.$path !== source_path) {
     throw new Error(
       `Node "${graph_node.id}" maps to multiple canonical paths.`,
     );
   }
 }
 
-/**
- * Normalize one repo-relative source path.
- *
- * @param {string} source_path
- * @returns {string}
- */
-export function normalizeRepoRelativePath(source_path) {
-  return posix.normalize(source_path.replaceAll('\\', '/'));
-}
-
-/**
- * @param {Record<string, MappingDefinition>} mappings
- * @param {PatramClaim} claim
- * @returns {MappingDefinition | null}
- */
-function resolveMappingDefinition(mappings, claim) {
-  if (claim.type === 'directive') {
-    return resolveDirectiveMapping(mappings, claim);
-  }
-
-  return mappings[claim.type] ?? null;
-}
-
-/**
- * @param {Record<string, MappingDefinition>} mappings
- * @param {PatramClaim} claim
- * @returns {MappingDefinition | null}
- */
-function resolveDirectiveMapping(mappings, claim) {
-  if (!claim.parser || !claim.name) {
-    return null;
-  }
-
-  return mappings[`${claim.parser}.directive.${claim.name}`] ?? null;
-}
-
 /**
  * @param {string} target_kind
  * @param {PatramClaim} claim
- * @returns {{ key: string, path?: string }}
+ * @returns {{ class_name: string, key: string, path?: string }}
  */
 function resolveValueTargetReference(target_kind, claim) {
   const target_key = getStringClaimValue(claim);
 
   if (target_kind === 'document') {
     return {
+      class_name: 'document',
       key: target_key,
       path: target_key,
     };
   }
 
   return {
+    class_name: target_kind,
     key: target_key,
     path: normalizeRepoRelativePath(claim.origin.path),
   };
 }
 
 /**
- * @param {string} target_kind
+ * @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 {Set<string>} document_paths
- * @returns {{ key: string, path?: string }}
+ * @returns {{ class_name: string, key: string, path?: string }}
  */
 function resolvePathTargetReference(
-  target_kind,
+  target_class,
   claim,
   document_entity_keys,
+  document_node_references,
   document_paths,
 ) {
   const raw_target = getPathTargetValue(claim);
@@ -199,19 +142,52 @@ function resolvePathTargetReference(
     document_paths,
   );
 
-  if (target_kind === 'document') {
+  if (target_class === 'document') {
+    return resolveDocumentTargetReference(
+      target_path,
+      document_node_references,
+    );
+  }
+
+  const document_node_reference = document_node_references.get(target_path);
+
+  if (documentNodeReferenceIsPromoted(document_node_reference)) {
     return {
-      key: target_path,
+      class_name: document_node_reference.class_name,
+      key: document_node_reference.key,
       path: target_path,
     };
   }
 
-  const semantic_target_key = document_entity_keys.get(
-    getDocumentEntityMapKey(target_path, target_kind),
-  );
+  return {
+    class_name: target_class,
+    key:
+      document_entity_keys.get(
+        getDocumentEntityMapKey(target_path, target_class),
+      ) ?? target_path,
+    path: target_path,
+  };
+}
+
+/**
+ * @param {string} target_path
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @returns {{ class_name: string, key: string, path?: string }}
+ */
+function resolveDocumentTargetReference(target_path, document_node_references) {
+  const document_node_reference = document_node_references.get(target_path);
+
+  if (!document_node_reference) {
+    return {
+      class_name: 'document',
+      key: target_path,
+      path: target_path,
+    };
+  }
 
   return {
-    key: semantic_target_key ?? target_path,
+    class_name: document_node_reference.class_name,
+    key: document_node_reference.key,
     path: target_path,
   };
 }
@@ -262,9 +238,20 @@ function getStringClaimValue(claim) {
 
 /**
  * @param {string} document_path
- * @param {string} kind_name
+ * @param {string} class_name
  * @returns {string}
  */
-function getDocumentEntityMapKey(document_path, kind_name) {
-  return `${kind_name}:${document_path}`;
+function getDocumentEntityMapKey(document_path, class_name) {
+  return `${class_name}:${document_path}`;
+}
+
+/**
+ * @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}
+ */
+function documentNodeReferenceIsPromoted(document_node_reference) {
+  return (
+    document_node_reference !== undefined &&
+    document_node_reference.class_name !== 'document'
+  );
 }