patram 0.11.0 → 0.12.0

package/lib/find-close-match.d.ts

@@ -5,4 +5,7 @@
  * @param {readonly string[]} candidates
  * @returns {string | undefined}
  */
-export function findCloseMatch(input_text: string, candidates: readonly string[]): string | undefined;
+export function findCloseMatch(
+  input_text: string,
+  candidates: readonly string[],
+): string | undefined;

package/lib/graph/build-graph-identity.d.ts

@@ -1,32 +1,3 @@
-/**
- * Resolve the node key for one mapped claim.
- *
- * @param {{ field: string, key?: 'path' | 'value', class: string }} node_mapping
- * @param {PatramClaim} claim
- * @param {Map<string, string>} document_entity_keys
- * @returns {string}
- */
-export function resolveNodeKey(node_mapping: {
-    field: string;
-    key?: "path" | "value";
-    class: string;
-}, claim: PatramClaim, document_entity_keys: Map<string, string>): string;
-/**
- * Resolve one edge target key and canonical path.
- *
- * @param {string} target_class
- * @param {'path' | 'value'} target_type
- * @param {PatramClaim} claim
- * @param {Map<string, string>} document_entity_keys
- * @param {Map<string, DocumentNodeReference>} document_node_references
- * @param {Set<string>} document_paths
- * @returns {{ class_name: string, key: string, path?: string }}
- */
-export function resolveTargetReference(target_class: string, target_type: "path" | "value", claim: PatramClaim, document_entity_keys: Map<string, string>, document_node_references: Map<string, DocumentNodeReference>, document_paths: Set<string>): {
-    class_name: string;
-    key: string;
-    path?: string;
-};
 /**
  * Attach one canonical path to a graph node.
  *
@@ -34,7 +5,5 @@ export function resolveTargetReference(target_class: string, target_type: "path"
  * @param {string | undefined} source_path
  */
 export function setCanonicalPath(graph_node: GraphNode, source_path: string | undefined): void;
-import type { PatramClaim } from '../parse/parse-claims.types.d.ts';
-import type { DocumentNodeReference } from './document-node-identity.js';
 import type { GraphNode } from './build-graph.types.d.ts';
-export { collectDocumentEntityKeys, collectDocumentNodeReferences, normalizeRepoRelativePath, resolveDocumentNodeId } from "./document-node-identity.js";
+export { collectDocumentEntityKeys, collectDocumentNodeReferences, normalizeRepoRelativePath, resolveDocumentNodeId, resolveTargetReference } from "./document-node-identity.js";

package/lib/graph/build-graph-identity.js

@@ -1,78 +1,15 @@
 /**
- * @import { DocumentNodeReference } from './document-node-identity.js';
  * @import { GraphNode } from './build-graph.types.ts';
- * @import { PatramClaim } from '../parse/parse-claims.types.ts';
  */
 
-import { posix } from 'node:path';
-
-import { normalizeRepoRelativePath } from './document-node-identity.js';
-
 export {
   collectDocumentEntityKeys,
   collectDocumentNodeReferences,
   normalizeRepoRelativePath,
   resolveDocumentNodeId,
+  resolveTargetReference,
 } from './document-node-identity.js';
 
-/**
- * Resolve the node key for one mapped claim.
- *
- * @param {{ field: string, key?: 'path' | 'value', class: string }} node_mapping
- * @param {PatramClaim} claim
- * @param {Map<string, string>} document_entity_keys
- * @returns {string}
- */
-export function resolveNodeKey(node_mapping, claim, document_entity_keys) {
-  const source_key = normalizeRepoRelativePath(claim.origin.path);
-
-  if (node_mapping.class === 'document') {
-    return source_key;
-  }
-
-  if (node_mapping.key === 'value') {
-    return getStringClaimValue(claim);
-  }
-
-  return (
-    document_entity_keys.get(
-      getDocumentEntityMapKey(source_key, node_mapping.class),
-    ) ?? source_key
-  );
-}
-
-/**
- * Resolve one edge target key and canonical path.
- *
- * @param {string} target_class
- * @param {'path' | 'value'} target_type
- * @param {PatramClaim} claim
- * @param {Map<string, string>} document_entity_keys
- * @param {Map<string, DocumentNodeReference>} document_node_references
- * @param {Set<string>} document_paths
- * @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') {
-    return resolveValueTargetReference(target_class, claim);
-  }
-
-  return resolvePathTargetReference(
-    target_class,
-    claim,
-    document_entity_keys,
-    document_node_references,
-    document_paths,
-  );
-}
-
 /**
  * Attach one canonical path to a graph node.
  *
@@ -84,215 +21,14 @@ export function setCanonicalPath(graph_node, source_path) {
     return;
   }
 
-  if (!graph_node.$path) {
-    graph_node.$path = source_path;
-    graph_node.path = source_path;
+  if (!graph_node.identity.path) {
+    graph_node.identity.path = source_path;
     return;
   }
 
-  if (graph_node.$path !== source_path) {
+  if (graph_node.identity.path !== source_path) {
     throw new Error(
-      `Node "${graph_node.id}" maps to multiple canonical paths.`,
+      `Node "${graph_node.identity.id}" maps to multiple canonical paths.`,
     );
   }
 }
-
-/**
- * @param {string} target_kind
- * @param {PatramClaim} claim
- * @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_class
- * @param {PatramClaim} claim
- * @param {Map<string, string>} document_entity_keys
- * @param {Map<string, DocumentNodeReference>} document_node_references
- * @param {Set<string>} document_paths
- * @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);
-  const target_path = resolveDirectiveAwareTargetPath(
-    claim,
-    raw_target,
-    document_paths,
-  );
-
-  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 {
-      class_name: document_node_reference.class_name,
-      key: document_node_reference.key,
-      path: target_path,
-    };
-  }
-
-  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, 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 {
-    class_name: document_node_reference.class_name,
-    key: document_node_reference.key,
-    path: target_path,
-  };
-}
-
-/**
- * @param {PatramClaim} claim
- * @param {string} raw_target
- * @param {Set<string>} document_paths
- * @returns {string}
- */
-function resolveDirectiveAwareTargetPath(claim, raw_target, document_paths) {
-  const normalized_raw_target = normalizeRepoRelativePath(raw_target);
-
-  if (
-    claim.type === 'directive' &&
-    shouldKeepDirectiveTargetRepoRelative(
-      raw_target,
-      normalized_raw_target,
-      document_paths,
-    )
-  ) {
-    return normalized_raw_target;
-  }
-
-  const source_directory = posix.dirname(
-    normalizeRepoRelativePath(claim.origin.path),
-  );
-
-  return normalizeRepoRelativePath(posix.join(source_directory, raw_target));
-}
-
-/**
- * @param {string} raw_target
- * @param {string} normalized_raw_target
- * @param {Set<string>} document_paths
- * @returns {boolean}
- */
-function shouldKeepDirectiveTargetRepoRelative(
-  raw_target,
-  normalized_raw_target,
-  document_paths,
-) {
-  if (raw_target.startsWith('./') || raw_target.startsWith('../')) {
-    return false;
-  }
-
-  if (document_paths.has(normalized_raw_target)) {
-    return true;
-  }
-
-  const target_root_segment = normalized_raw_target.split('/')[0];
-
-  if (!target_root_segment) {
-    return false;
-  }
-
-  for (const document_path of document_paths) {
-    if (document_path.split('/')[0] === target_root_segment) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
-/**
- * @param {PatramClaim} claim
- * @returns {string}
- */
-function getPathTargetValue(claim) {
-  if (typeof claim.value === 'string') {
-    return claim.value;
-  }
-
-  return claim.value.target;
-}
-
-/**
- * @param {PatramClaim} claim
- * @returns {string}
- */
-function getStringClaimValue(claim) {
-  if (typeof claim.value === 'string') {
-    return claim.value;
-  }
-
-  throw new Error(`Claim "${claim.id}" does not carry a string value.`);
-}
-
-/**
- * @param {string} document_path
- * @param {string} class_name
- * @returns {string}
- */
-function getDocumentEntityMapKey(document_path, class_name) {
-  return `${class_name}:${document_path}`;
-}
-
-/**
- * @param {DocumentNodeReference | undefined} document_node_reference
- * @returns {document_node_reference is DocumentNodeReference}
- */
-function documentNodeReferenceIsPromoted(document_node_reference) {
-  return (
-    document_node_reference !== undefined &&
-    document_node_reference.class_name !== 'document'
-  );
-}

package/lib/graph/build-graph.d.ts

@@ -1,11 +1,20 @@
 /**
- * Build a Patram graph from semantic config and parsed claims.
+ * Build a Patram graph from repo config and parsed claims.
  *
- * @param {PatramConfig} patram_config
+ * kind: graph
+ * status: active
+ * uses_term: ../../docs/reference/terms/graph.md
+ * tracked_in: ../../docs/plans/v2/types-and-fields-config.md
+ * decided_by: ../../docs/decisions/types-and-fields-config.md
+ * @patram
+ * @see {@link ./build-graph-identity.js}
+ * @see {@link ../../docs/decisions/types-and-fields-config.md}
+ *
+ * @param {PatramRepoConfig} repo_config
  * @param {PatramClaim[]} claims
  * @returns {BuildGraphResult}
  */
-export function buildGraph(patram_config: PatramConfig, claims: PatramClaim[]): BuildGraphResult;
-import type { PatramConfig } from '../config/patram-config.types.d.ts';
+export function buildGraph(repo_config: PatramRepoConfig, claims: PatramClaim[]): BuildGraphResult;
+import type { PatramRepoConfig } from '../config/load-patram-config.types.d.ts';
 import type { PatramClaim } from '../parse/parse-claims.types.d.ts';
 import type { BuildGraphResult } from './build-graph.types.d.ts';