patram 0.0.2 → 0.2.0

package/lib/build-graph.js

@@ -4,7 +4,34 @@
  * @import { MappingDefinition, PatramConfig } from './patram-config.types.ts';
  */
 
-import { posix } from 'node:path';
+import {
+  collectDocumentEntityKeys,
+  normalizeRepoRelativePath,
+  resolveNodeKey,
+  resolveTargetReference,
+  setNonDocumentPath,
+} from './build-graph-identity.js';
+
+/**
+ * Claim-to-graph materialization.
+ *
+ * Maps parsed claims into document nodes and relations using the resolved
+ * Patram graph config.
+ *
+ * Kind: graph
+ * Status: active
+ * Uses Term: ../docs/reference/terms/claim.md
+ * Uses Term: ../docs/reference/terms/document.md
+ * Uses Term: ../docs/reference/terms/graph.md
+ * Uses Term: ../docs/reference/terms/mapping.md
+ * Uses Term: ../docs/reference/terms/relation.md
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/graph-materialization.md
+ * Implements: ../docs/tasks/v0/materialize-graph.md
+ * @patram
+ * @see {@link ./load-project-graph.js}
+ * @see {@link ../docs/decisions/graph-materialization.md}
+ */
 
 /**
  * Build a Patram graph from semantic config and parsed claims.
@@ -16,49 +43,29 @@ import { posix } from 'node:path';
 export function buildGraph(patram_config, claims) {
   /** @type {Map<string, GraphNode>} */
   const graph_nodes = new Map();
-  /** @type {GraphEdge[]} */
-  const graph_edges = [];
-  let edge_number = 0;
-
-  for (const claim of claims) {
-    const source_document_node = upsertNode(
-      graph_nodes,
-      'document',
-      normalizeRepoRelativePath(claim.origin.path),
-    );
-    const mapping_definition = resolveMappingDefinition(
-      patram_config.mappings,
-      claim,
-    );
-
-    if (!mapping_definition) {
-      continue;
-    }
-
-    if (mapping_definition.node) {
-      applyNodeMapping(graph_nodes, mapping_definition.node, claim);
-    }
-
-    if (!mapping_definition.emit) {
-      continue;
-    }
-
-    const target_key = resolveTargetKey(mapping_definition.emit.target, claim);
-    const target_node = upsertNode(
-      graph_nodes,
-      mapping_definition.emit.target_kind,
-      target_key,
-    );
+  const document_entity_keys = collectDocumentEntityKeys(
+    patram_config.mappings,
+    claims,
+  );
+  /** @type {Set<string>} */
+  const document_paths = new Set(
+    claims.map((claim) => normalizeRepoRelativePath(claim.origin.path)),
+  );
 
-    edge_number += 1;
-    graph_edges.push({
-      from: source_document_node.id,
-      id: `edge:${edge_number}`,
-      origin: claim.origin,
-      relation: mapping_definition.emit.relation,
-      to: target_node.id,
-    });
-  }
+  createDocumentNodes(graph_nodes, claims);
+  applyNodeMappings(
+    graph_nodes,
+    patram_config.mappings,
+    claims,
+    document_entity_keys,
+  );
+  const graph_edges = createGraphEdges(
+    graph_nodes,
+    patram_config.mappings,
+    claims,
+    document_entity_keys,
+    document_paths,
+  );
 
   return {
     edges: graph_edges,
@@ -96,56 +103,124 @@ function resolveDirectiveMapping(mappings, claim) {
 
 /**
  * @param {Map<string, GraphNode>} graph_nodes
- * @param {{ field: string, kind: string }} node_mapping
- * @param {PatramClaim} claim
+ * @param {PatramClaim[]} claims
  */
-function applyNodeMapping(graph_nodes, node_mapping, claim) {
-  const source_key = normalizeRepoRelativePath(claim.origin.path);
-  const graph_node = upsertNode(graph_nodes, node_mapping.kind, source_key);
-
-  graph_node[node_mapping.field] = getStringClaimValue(claim);
+function createDocumentNodes(graph_nodes, claims) {
+  for (const claim of claims) {
+    upsertNode(
+      graph_nodes,
+      'document',
+      normalizeRepoRelativePath(claim.origin.path),
+    );
+  }
 }
 
 /**
- * @param {'path'} target_type
- * @param {PatramClaim} claim
- * @returns {string}
+ * @param {Map<string, GraphNode>} graph_nodes
+ * @param {Record<string, MappingDefinition>} mappings
+ * @param {PatramClaim[]} claims
+ * @param {Map<string, string>} document_entity_keys
  */
-function resolveTargetKey(target_type, claim) {
-  if (target_type !== 'path') {
-    throw new Error(`Unsupported target type "${target_type}".`);
-  }
+function applyNodeMappings(
+  graph_nodes,
+  mappings,
+  claims,
+  document_entity_keys,
+) {
+  for (const claim of claims) {
+    const mapping_definition = resolveMappingDefinition(mappings, claim);
 
-  const source_directory = posix.dirname(
-    normalizeRepoRelativePath(claim.origin.path),
-  );
-  const raw_target = getPathTargetValue(claim);
+    if (!mapping_definition?.node) {
+      continue;
+    }
 
-  return normalizeRepoRelativePath(posix.join(source_directory, raw_target));
+    applyNodeMapping(
+      graph_nodes,
+      mapping_definition.node,
+      claim,
+      document_entity_keys,
+    );
+  }
 }
 
 /**
- * @param {PatramClaim} claim
- * @returns {string}
+ * @param {Map<string, GraphNode>} graph_nodes
+ * @param {Record<string, MappingDefinition>} mappings
+ * @param {PatramClaim[]} claims
+ * @param {Map<string, string>} document_entity_keys
+ * @param {Set<string>} document_paths
+ * @returns {GraphEdge[]}
  */
-function getPathTargetValue(claim) {
-  if (typeof claim.value === 'string') {
-    return claim.value;
+function createGraphEdges(
+  graph_nodes,
+  mappings,
+  claims,
+  document_entity_keys,
+  document_paths,
+) {
+  /** @type {GraphEdge[]} */
+  const graph_edges = [];
+  let edge_number = 0;
+
+  for (const claim of claims) {
+    const mapping_definition = resolveMappingDefinition(mappings, claim);
+
+    if (!mapping_definition?.emit) {
+      continue;
+    }
+
+    const source_document_node = upsertNode(
+      graph_nodes,
+      'document',
+      normalizeRepoRelativePath(claim.origin.path),
+    );
+    const target_reference = resolveTargetReference(
+      mapping_definition.emit.target_kind,
+      mapping_definition.emit.target,
+      claim,
+      document_entity_keys,
+      document_paths,
+    );
+    const target_node = upsertNode(
+      graph_nodes,
+      mapping_definition.emit.target_kind,
+      target_reference.key,
+    );
+
+    setNonDocumentPath(target_node, target_reference.path);
+
+    edge_number += 1;
+    graph_edges.push({
+      from: source_document_node.id,
+      id: `edge:${edge_number}`,
+      origin: claim.origin,
+      relation: mapping_definition.emit.relation,
+      to: target_node.id,
+    });
   }
 
-  return claim.value.target;
+  return graph_edges;
 }
 
 /**
+ * @param {Map<string, GraphNode>} graph_nodes
+ * @param {{ field: string, key?: 'path' | 'value', kind: string }} node_mapping
  * @param {PatramClaim} claim
- * @returns {string}
+ * @param {Map<string, string>} document_entity_keys
  */
-function getStringClaimValue(claim) {
-  if (typeof claim.value === 'string') {
-    return claim.value;
-  }
+function applyNodeMapping(
+  graph_nodes,
+  node_mapping,
+  claim,
+  document_entity_keys,
+) {
+  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.kind, node_key);
 
-  throw new Error(`Claim "${claim.id}" does not carry a string value.`);
+  setNonDocumentPath(graph_node, source_key);
+
+  graph_node[node_mapping.field] = getNodeFieldValue(claim);
 }
 
 /**
@@ -205,11 +280,15 @@ function getNodeId(kind_name, node_key) {
 }
 
 /**
- * @param {string} source_path
+ * @param {PatramClaim} claim
  * @returns {string}
  */
-function normalizeRepoRelativePath(source_path) {
-  return posix.normalize(source_path.replaceAll('\\', '/'));
+function getNodeFieldValue(claim) {
+  if (typeof claim.value === 'string') {
+    return claim.value;
+  }
+
+  throw new Error(`Claim "${claim.id}" does not carry a string value.`);
 }
 
 /**

package/lib/check-graph.js

@@ -3,17 +3,33 @@
  * @import { PatramDiagnostic } from './load-patram-config.types.ts';
  */
 
+/**
+ * Graph validation.
+ *
+ * Reports broken document links and missing edge nodes after graph
+ * materialization.
+ *
+ * Kind: graph
+ * Status: active
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/check-link-target-existence.md
+ * Implements: ../docs/tasks/v0/check-command.md
+ * @patram
+ * @see {@link ./build-graph.js}
+ * @see {@link ../docs/decisions/check-link-target-existence.md}
+ */
+
 /**
  * Check a materialized graph for broken document links and missing edge nodes.
  *
  * @param {BuildGraphResult} graph
- * @param {string[]} source_file_paths
+ * @param {string[]} existing_file_paths
  * @returns {PatramDiagnostic[]}
  */
-export function checkGraph(graph, source_file_paths) {
+export function checkGraph(graph, existing_file_paths) {
   /** @type {PatramDiagnostic[]} */
   const diagnostics = [];
-  const source_file_path_set = new Set(source_file_paths);
+  const existing_file_path_set = new Set(existing_file_paths);
 
   for (const graph_edge of graph.edges) {
     const source_node = graph.nodes[graph_edge.from];
@@ -34,7 +50,7 @@ export function checkGraph(graph, source_file_paths) {
       diagnostics,
       graph_edge,
       target_node,
-      source_file_path_set,
+      existing_file_path_set,
     );
   }
 
@@ -78,13 +94,13 @@ function collectMissingNodeDiagnostics(
  * @param {PatramDiagnostic[]} diagnostics
  * @param {GraphEdge} graph_edge
  * @param {GraphNode} target_node
- * @param {Set<string>} source_file_path_set
+ * @param {Set<string>} existing_file_path_set
  */
 function collectBrokenLinkDiagnostics(
   diagnostics,
   graph_edge,
   target_node,
-  source_file_path_set,
+  existing_file_path_set,
 ) {
   if (graph_edge.relation !== 'links_to') {
     return;
@@ -94,7 +110,7 @@ function collectBrokenLinkDiagnostics(
     return;
   }
 
-  if (source_file_path_set.has(target_node.path)) {
+  if (existing_file_path_set.has(target_node.path)) {
     return;
   }
 

package/lib/claim-helpers.js

@@ -0,0 +1,55 @@
+/**
+ * @import { PatramClaim, PatramClaimFields } from './parse-claims.types.ts';
+ */
+
+const URI_SCHEME_PATTERN = /^[A-Za-z][A-Za-z0-9+.-]*:/du;
+
+/**
+ * @param {string} target_value
+ * @returns {boolean}
+ */
+export function isPathLikeTarget(target_value) {
+  if (target_value.startsWith('#')) {
+    return false;
+  }
+
+  return !URI_SCHEME_PATTERN.test(target_value);
+}
+
+/**
+ * @param {string} file_path
+ * @param {number} claim_number
+ * @param {string} claim_type
+ * @param {PatramClaimFields} claim_fields
+ * @returns {PatramClaim}
+ */
+export function createClaim(file_path, claim_number, claim_type, claim_fields) {
+  const document_id = `doc:${file_path}`;
+  const origin = claim_fields.origin ?? {
+    column: 1,
+    line: 1,
+    path: file_path,
+  };
+
+  return {
+    ...claim_fields,
+    document_id,
+    id: `claim:${document_id}:${claim_number}`,
+    origin,
+    type: claim_type,
+  };
+}
+
+/**
+ * @param {string} file_path
+ * @returns {string}
+ */
+export function getFileExtension(file_path) {
+  const last_dot_index = file_path.lastIndexOf('.');
+
+  if (last_dot_index < 0) {
+    return '';
+  }
+
+  return file_path.slice(last_dot_index);
+}