patram 0.3.0 → 0.4.0

package/lib/build-graph-identity.js

@@ -1,48 +1,19 @@
+/** @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);
-
-    if (mapping_definition?.node?.key !== 'value') {
-      continue;
-    }
-
-    const source_path = normalizeRepoRelativePath(claim.origin.path);
-    const entity_map_key = getDocumentEntityMapKey(
-      source_path,
-      mapping_definition.node.class,
-    );
-    const entity_key = getStringClaimValue(claim);
-    const existing_entity_key = document_entity_keys.get(entity_map_key);
+import { normalizeRepoRelativePath } from './document-node-identity.js';
 
-    if (existing_entity_key && existing_entity_key !== entity_key) {
-      throw new Error(
-        `Document "${source_path}" defines multiple ${mapping_definition.node.class} 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.
@@ -77,14 +48,16 @@ export function resolveNodeKey(node_mapping, claim, document_entity_keys) {
  * @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_class,
   target_type,
   claim,
   document_entity_keys,
+  document_node_references,
   document_paths,
 ) {
   if (target_type === 'value') {
@@ -95,18 +68,19 @@ export function resolveTargetReference(
     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.$class === 'document') {
+export function setCanonicalPath(graph_node, source_path) {
+  if (!source_path) {
     return;
   }
 
@@ -123,58 +97,24 @@ export function setNonDocumentPath(graph_node, source_path) {
   }
 }
 
-/**
- * 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),
   };
@@ -184,13 +124,15 @@ function resolveValueTargetReference(target_kind, claim) {
  * @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_class,
   claim,
   document_entity_keys,
+  document_node_references,
   document_paths,
 ) {
   const raw_target = getPathTargetValue(claim);
@@ -201,18 +143,51 @@ function resolvePathTargetReference(
   );
 
   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_class),
-  );
+  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,
   };
 }
@@ -269,3 +244,14 @@ function getStringClaimValue(claim) {
 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'
+  );
+}

package/lib/build-graph.js

@@ -10,10 +10,11 @@ import { posix } from 'node:path';
 
 import {
   collectDocumentEntityKeys,
+  collectDocumentNodeReferences,
   normalizeRepoRelativePath,
   resolveNodeKey,
   resolveTargetReference,
-  setNonDocumentPath,
+  setCanonicalPath,
 } from './build-graph-identity.js';
 
 /**
@@ -52,6 +53,10 @@ const EXPLICIT_TITLE_PRIORITY = 2;
 export function buildGraph(patram_config, claims) {
   /** @type {Map<string, GraphNode>} */
   const graph_nodes = new Map();
+  const document_node_references = collectDocumentNodeReferences(
+    patram_config.mappings,
+    claims,
+  );
   const document_entity_keys = collectDocumentEntityKeys(
     patram_config.mappings,
     claims,
@@ -63,12 +68,13 @@ export function buildGraph(patram_config, claims) {
   /** @type {Map<string, number>} */
   const title_priorities = new Map();
 
-  createDocumentNodes(graph_nodes, claims);
+  createDocumentNodes(graph_nodes, document_node_references);
   applyNodeMappings(
     graph_nodes,
     patram_config,
     claims,
     document_entity_keys,
+    document_node_references,
     title_priorities,
   );
   const graph_edges = createGraphEdges(
@@ -76,16 +82,26 @@ export function buildGraph(patram_config, claims) {
     patram_config.mappings,
     claims,
     document_entity_keys,
+    document_node_references,
     document_paths,
   );
   applyFallbackTitles(graph_nodes, title_priorities);
 
-  return {
+  const graph_result = {
     edges: graph_edges,
     nodes: Object.fromEntries(
       [...graph_nodes.entries()].sort(compareNodeEntries),
     ),
   };
+
+  attachDocumentNodeAliases(graph_result.nodes, document_node_references);
+  Object.defineProperty(
+    graph_result,
+    'document_node_ids',
+    createDocumentNodeIdsProperty(document_node_references),
+  );
+
+  return graph_result;
 }
 
 /**
@@ -116,15 +132,17 @@ function resolveDirectiveMapping(mappings, claim) {
 
 /**
  * @param {Map<string, GraphNode>} graph_nodes
- * @param {PatramClaim[]} claims
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
  */
-function createDocumentNodes(graph_nodes, claims) {
-  for (const claim of claims) {
-    upsertNode(
+function createDocumentNodes(graph_nodes, document_node_references) {
+  for (const document_node_reference of document_node_references.values()) {
+    const graph_node = upsertNode(
       graph_nodes,
-      'document',
-      normalizeRepoRelativePath(claim.origin.path),
+      document_node_reference.class_name,
+      document_node_reference.key,
     );
+
+    setCanonicalPath(graph_node, document_node_reference.path);
   }
 }
 
@@ -133,6 +151,7 @@ function createDocumentNodes(graph_nodes, claims) {
  * @param {PatramConfig} patram_config
  * @param {PatramClaim[]} claims
  * @param {Map<string, string>} document_entity_keys
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
  * @param {Map<string, number>} title_priorities
  */
 function applyNodeMappings(
@@ -140,6 +159,7 @@ function applyNodeMappings(
   patram_config,
   claims,
   document_entity_keys,
+  document_node_references,
   title_priorities,
 ) {
   for (const claim of claims) {
@@ -158,6 +178,7 @@ function applyNodeMappings(
       mapping_definition.node,
       claim,
       document_entity_keys,
+      document_node_references,
       title_priorities,
     );
   }
@@ -168,6 +189,7 @@ function applyNodeMappings(
  * @param {Record<string, MappingDefinition>} mappings
  * @param {PatramClaim[]} claims
  * @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 {GraphEdge[]}
  */
@@ -176,6 +198,7 @@ function createGraphEdges(
   mappings,
   claims,
   document_entity_keys,
+  document_node_references,
   document_paths,
 ) {
   /** @type {GraphEdge[]} */
@@ -189,25 +212,26 @@ function createGraphEdges(
       continue;
     }
 
-    const source_document_node = upsertNode(
+    const source_document_node = getDocumentGraphNode(
       graph_nodes,
-      'document',
-      normalizeRepoRelativePath(claim.origin.path),
+      document_node_references,
+      claim,
     );
     const target_reference = resolveTargetReference(
       mapping_definition.emit.target_class,
       mapping_definition.emit.target,
       claim,
       document_entity_keys,
+      document_node_references,
       document_paths,
     );
     const target_node = upsertNode(
       graph_nodes,
-      mapping_definition.emit.target_class,
+      target_reference.class_name,
       target_reference.key,
     );
 
-    setNonDocumentPath(target_node, target_reference.path);
+    setCanonicalPath(target_node, target_reference.path);
 
     edge_number += 1;
     graph_edges.push({
@@ -228,6 +252,7 @@ function createGraphEdges(
  * @param {{ field: string, key?: 'path' | 'value', class: string }} node_mapping
  * @param {PatramClaim} claim
  * @param {Map<string, string>} document_entity_keys
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
  * @param {Map<string, number>} title_priorities
  */
 function applyNodeMapping(
@@ -236,14 +261,25 @@ function applyNodeMapping(
   node_mapping,
   claim,
   document_entity_keys,
+  document_node_references,
   title_priorities,
 ) {
   const source_key = normalizeRepoRelativePath(claim.origin.path);
-  const node_key = resolveNodeKey(node_mapping, claim, document_entity_keys);
-  const graph_node = upsertNode(graph_nodes, node_mapping.class, node_key);
-  const field_value = getNodeFieldValue(claim);
+  const graph_node = resolveGraphNode(
+    graph_nodes,
+    node_mapping,
+    claim,
+    document_entity_keys,
+    document_node_references,
+  );
+  const field_value = resolveNodeFieldValue(
+    graph_node,
+    node_mapping,
+    claim,
+    source_key,
+  );
 
-  setNonDocumentPath(graph_node, source_key);
+  setCanonicalPath(graph_node, source_key);
   validateNodeFieldMapping(
     patram_config,
     node_mapping.class,
@@ -408,6 +444,122 @@ function getNodeFieldValue(claim) {
   throw new Error(`Claim "${claim.id}" does not carry a string value.`);
 }
 
+/**
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @returns {{ configurable: false, enumerable: false, value: Record<string, string>, writable: false }}
+ */
+function createDocumentNodeIdsProperty(document_node_references) {
+  return {
+    configurable: false,
+    enumerable: false,
+    value: Object.fromEntries(
+      [...document_node_references.entries()].map(
+        ([document_path, document_node_reference]) => [
+          document_path,
+          document_node_reference.id,
+        ],
+      ),
+    ),
+    writable: false,
+  };
+}
+
+/**
+ * @param {Map<string, GraphNode>} graph_nodes
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @param {PatramClaim} claim
+ * @returns {GraphNode}
+ */
+function getDocumentGraphNode(graph_nodes, document_node_references, claim) {
+  const document_path = normalizeRepoRelativePath(claim.origin.path);
+  const document_node_reference = document_node_references.get(document_path);
+
+  if (!document_node_reference) {
+    throw new Error(`Missing document node reference for "${document_path}".`);
+  }
+
+  const graph_node = upsertNode(
+    graph_nodes,
+    document_node_reference.class_name,
+    document_node_reference.key,
+  );
+
+  setCanonicalPath(graph_node, document_node_reference.path);
+
+  return graph_node;
+}
+
+/**
+ * @param {Map<string, GraphNode>} graph_nodes
+ * @param {{ field: string, key?: 'path' | 'value', class: string }} node_mapping
+ * @param {PatramClaim} claim
+ * @param {Map<string, string>} document_entity_keys
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @returns {GraphNode}
+ */
+function resolveGraphNode(
+  graph_nodes,
+  node_mapping,
+  claim,
+  document_entity_keys,
+  document_node_references,
+) {
+  if (node_mapping.class === 'document') {
+    return getDocumentGraphNode(graph_nodes, document_node_references, claim);
+  }
+
+  const node_key = resolveNodeKey(node_mapping, claim, document_entity_keys);
+
+  return upsertNode(graph_nodes, node_mapping.class, node_key);
+}
+
+/**
+ * @param {GraphNode} graph_node
+ * @param {{ field: string, key?: 'path' | 'value', class: string }} node_mapping
+ * @param {PatramClaim} claim
+ * @param {string} source_path
+ * @returns {string}
+ */
+function resolveNodeFieldValue(graph_node, node_mapping, claim, source_path) {
+  if (node_mapping.field === '$id') {
+    return graph_node.id;
+  }
+
+  if (node_mapping.field === '$class') {
+    return graph_node.$class ?? graph_node.kind ?? node_mapping.class;
+  }
+
+  if (node_mapping.field === '$path') {
+    return source_path;
+  }
+
+  return getNodeFieldValue(claim);
+}
+
+/**
+ * @param {Record<string, GraphNode>} graph_nodes
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ */
+function attachDocumentNodeAliases(graph_nodes, document_node_references) {
+  for (const [
+    document_path,
+    document_node_reference,
+  ] of document_node_references) {
+    const document_node_id = `doc:${document_path}`;
+
+    if (document_node_id === document_node_reference.id) {
+      continue;
+    }
+
+    Object.defineProperty(graph_nodes, document_node_id, {
+      configurable: false,
+      enumerable: false,
+      value: graph_nodes[document_node_reference.id],
+      writable: false,
+    });
+  }
+}
+
 /**
  * @param {Map<string, GraphNode>} graph_nodes
  * @param {Map<string, number>} title_priorities

package/lib/build-graph.types.ts

@@ -21,6 +21,7 @@ export interface GraphEdge {
 }
 
 export interface BuildGraphResult {
+  document_node_ids?: Record<string, string>;
   edges: GraphEdge[];
   nodes: Record<string, GraphNode>;
 }

package/lib/check-directive-metadata.js

@@ -8,7 +8,9 @@
 
 import {
   collectDocumentEntityKeys,
+  collectDocumentNodeReferences,
   normalizeRepoRelativePath,
+  resolveDocumentNodeId,
 } from './build-graph-identity.js';
 import { checkDirectiveValue } from './check-directive-value.js';
 import {
@@ -55,6 +57,10 @@ export function checkDirectiveMetadata(
     graph_config.mappings,
     claims,
   );
+  const document_node_references = collectDocumentNodeReferences(
+    graph_config.mappings,
+    claims,
+  );
   const document_paths = new Set(
     existing_file_paths.map((file_path) =>
       normalizeRepoRelativePath(file_path),
@@ -79,6 +85,7 @@ export function checkDirectiveMetadata(
       document_path,
       document_claims,
       document_entity_keys,
+      document_node_references,
       document_paths,
     );
   }
@@ -121,6 +128,7 @@ function groupDirectiveClaimsByDocument(claims) {
  * @param {string} document_path
  * @param {PatramClaim[]} document_claims
  * @param {Map<string, string>} document_entity_keys
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
  * @param {Set<string>} document_paths
  */
 function collectDocumentDiagnostics(
@@ -131,6 +139,7 @@ function collectDocumentDiagnostics(
   document_path,
   document_claims,
   document_entity_keys,
+  document_node_references,
   document_paths,
 ) {
   const document_kind = resolveDocumentKind(graph, document_path);
@@ -152,6 +161,7 @@ function collectDocumentDiagnostics(
         schema_definition,
         directive_counts,
         document_entity_keys,
+        document_node_references,
         document_paths,
       ),
     );
@@ -176,6 +186,7 @@ function collectDocumentDiagnostics(
  * @param {MetadataSchemaConfig | undefined} schema_definition
  * @param {Map<string, number>} directive_counts
  * @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 {PatramDiagnostic[]}
  */
@@ -187,6 +198,7 @@ function collectClaimDiagnostics(
   schema_definition,
   directive_counts,
   document_entity_keys,
+  document_node_references,
   document_paths,
 ) {
   if (!claim.name) {
@@ -222,6 +234,7 @@ function collectClaimDiagnostics(
       repo_config,
       schema_definition?.fields[claim.name],
       document_entity_keys,
+      document_node_references,
       document_paths,
     ),
   ];
@@ -392,9 +405,14 @@ function getDirectiveFieldDefinition(repo_config, validation_field_name) {
  * @returns {string}
  */
 function resolveDocumentKind(graph, document_path) {
+  const document_node_id = resolveDocumentNodeId(
+    graph.document_node_ids,
+    document_path,
+  );
+
   return (
-    graph.nodes[`doc:${document_path}`]?.$class ??
-    graph.nodes[`doc:${document_path}`]?.kind ??
+    graph.nodes[document_node_id]?.$class ??
+    graph.nodes[document_node_id]?.kind ??
     'document'
   );
 }