patram 0.0.2 → 0.1.1

package/bin/patram.js

@@ -1,169 +1,47 @@
 #!/usr/bin/env node
 
-/**
- * @import { PatramClaim } from '../lib/parse-claims.types.ts';
- */
-
-import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { realpath } from 'node:fs/promises';
 import process from 'node:process';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 
-import { buildGraph } from '../lib/build-graph.js';
-import { checkGraph } from '../lib/check-graph.js';
-import { listSourceFiles } from '../lib/list-source-files.js';
-import { loadPatramConfig } from '../lib/load-patram-config.js';
-import { parseClaims } from '../lib/parse-claims.js';
-import { parsePatramConfig } from '../lib/patram-config.js';
+import { main } from '../lib/patram-cli.js';
 
-const CHECK_GRAPH_CONFIG = parsePatramConfig({
-  kinds: {
-    document: {
-      builtin: true,
-      label: 'Document',
-    },
-  },
-  mappings: {
-    'document.title': {
-      node: {
-        field: 'title',
-        kind: 'document',
-      },
-    },
-    'markdown.link': {
-      emit: {
-        relation: 'links_to',
-        target: 'path',
-        target_kind: 'document',
-      },
-    },
-  },
-  relations: {
-    links_to: {
-      builtin: true,
-      from: ['document'],
-      to: ['document'],
-    },
-  },
-});
+/**
+ * Patram CLI entrypoint.
+ *
+ * Detects direct process execution and forwards command handling to the shared
+ * CLI runtime.
+ *
+ * Kind: entrypoint
+ * Status: active
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/cli-entrypoint-symlink.md
+ * @patram
+ * @see {@link ../lib/patram-cli.js}
+ * @see {@link ../docs/patram.md}
+ */
 
-if (isEntrypoint(import.meta.url, process.argv[1])) {
+if (await isEntrypoint(import.meta.url, process.argv[1])) {
   process.exitCode = await main(process.argv.slice(2), {
     stderr: process.stderr,
     stdout: process.stdout,
   });
 }
 
-/**
- * Run the Patram CLI.
- *
- * @param {string[]} cli_arguments
- * @param {{ stderr: { write(chunk: string): boolean }, stdout: { write(chunk: string): boolean } }} io_context
- * @returns {Promise<number>}
- */
-export async function main(cli_arguments, io_context) {
-  const command_name = cli_arguments[0];
-
-  if (command_name === 'check') {
-    return runCheckCommand(cli_arguments.slice(1), io_context);
-  }
-
-  io_context.stderr.write('Unknown command.\n');
-
-  return 1;
-}
-
-/**
- * @param {string[]} command_arguments
- * @param {{ stderr: { write(chunk: string): boolean }, stdout: { write(chunk: string): boolean } }} io_context
- * @returns {Promise<number>}
- */
-async function runCheckCommand(command_arguments, io_context) {
-  const project_directory = command_arguments[0] ?? process.cwd();
-  const load_result = await loadPatramConfig(project_directory);
-
-  if (load_result.diagnostics.length > 0) {
-    writeDiagnostics(io_context.stderr, load_result.diagnostics);
-
-    return 1;
-  }
-
-  const repo_config = load_result.config;
-
-  if (!repo_config) {
-    throw new Error('Expected a valid Patram repo config.');
-  }
-
-  const source_file_paths = await listSourceFiles(
-    repo_config.include,
-    project_directory,
-  );
-  const claims = await collectClaims(source_file_paths, project_directory);
-  const graph = buildGraph(CHECK_GRAPH_CONFIG, claims);
-  const diagnostics = checkGraph(graph, source_file_paths);
-
-  if (diagnostics.length > 0) {
-    writeDiagnostics(io_context.stderr, diagnostics);
-
-    return 1;
-  }
-
-  return 0;
-}
-
-/**
- * @param {string[]} source_file_paths
- * @param {string} project_directory
- * @returns {Promise<PatramClaim[]>}
- */
-async function collectClaims(source_file_paths, project_directory) {
-  /** @type {PatramClaim[]} */
-  const claims = [];
-
-  for (const source_file_path of source_file_paths) {
-    const source_text = await readFile(
-      resolve(project_directory, source_file_path),
-      'utf8',
-    );
-
-    claims.push(
-      ...parseClaims({
-        path: source_file_path,
-        source: source_text,
-      }),
-    );
-  }
-
-  return claims;
-}
-
-/**
- * @param {{ write(chunk: string): boolean }} output_stream
- * @param {import('../lib/load-patram-config.types.ts').PatramDiagnostic[]} diagnostics
- */
-function writeDiagnostics(output_stream, diagnostics) {
-  for (const diagnostic of diagnostics) {
-    output_stream.write(formatDiagnostic(diagnostic));
-  }
-}
-
-/**
- * @param {import('../lib/load-patram-config.types.ts').PatramDiagnostic} diagnostic
- * @returns {string}
- */
-function formatDiagnostic(diagnostic) {
-  return `${diagnostic.path}:${diagnostic.line}:${diagnostic.column} ${diagnostic.level} ${diagnostic.code} ${diagnostic.message}\n`;
-}
+export { main };
 
 /**
  * @param {string} module_url
  * @param {string | undefined} process_entry_path
- * @returns {boolean}
+ * @returns {Promise<boolean>}
  */
-function isEntrypoint(module_url, process_entry_path) {
+async function isEntrypoint(module_url, process_entry_path) {
   if (!process_entry_path) {
     return false;
   }
 
-  return module_url === pathToFileURL(process_entry_path).href;
+  const module_path = await realpath(fileURLToPath(module_url));
+  const entry_path = await realpath(process_entry_path);
+
+  return module_path === entry_path;
 }

package/lib/build-graph-identity.js

@@ -0,0 +1,238 @@
+/**
+ * @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.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;
+}
+
+/**
+ * Resolve the node key for one mapped claim.
+ *
+ * @param {{ field: string, key?: 'path' | 'value', kind: 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.kind === 'document') {
+    return source_key;
+  }
+
+  if (node_mapping.key === 'value') {
+    return getStringClaimValue(claim);
+  }
+
+  return (
+    document_entity_keys.get(
+      getDocumentEntityMapKey(source_key, node_mapping.kind),
+    ) ?? source_key
+  );
+}
+
+/**
+ * Resolve one edge target key and canonical path.
+ *
+ * @param {string} target_kind
+ * @param {'path' | 'value'} target_type
+ * @param {PatramClaim} claim
+ * @param {Map<string, string>} document_entity_keys
+ * @returns {{ key: string, path?: string }}
+ */
+export function resolveTargetReference(
+  target_kind,
+  target_type,
+  claim,
+  document_entity_keys,
+) {
+  if (target_type === 'value') {
+    return resolveValueTargetReference(target_kind, claim);
+  }
+
+  return resolvePathTargetReference(target_kind, claim, document_entity_keys);
+}
+
+/**
+ * Attach one canonical path to a non-document 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') {
+    return;
+  }
+
+  if (!graph_node.path) {
+    graph_node.path = source_path;
+    return;
+  }
+
+  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 }}
+ */
+function resolveValueTargetReference(target_kind, claim) {
+  const target_key = getStringClaimValue(claim);
+
+  if (target_kind === 'document') {
+    return {
+      key: target_key,
+      path: target_key,
+    };
+  }
+
+  return {
+    key: target_key,
+    path: normalizeRepoRelativePath(claim.origin.path),
+  };
+}
+
+/**
+ * @param {string} target_kind
+ * @param {PatramClaim} claim
+ * @param {Map<string, string>} document_entity_keys
+ * @returns {{ key: string, path?: string }}
+ */
+function resolvePathTargetReference(target_kind, claim, document_entity_keys) {
+  const source_directory = posix.dirname(
+    normalizeRepoRelativePath(claim.origin.path),
+  );
+  const raw_target = getPathTargetValue(claim);
+  const target_path = normalizeRepoRelativePath(
+    posix.join(source_directory, raw_target),
+  );
+
+  if (target_kind === 'document') {
+    return {
+      key: target_path,
+      path: target_path,
+    };
+  }
+
+  const semantic_target_key = document_entity_keys.get(
+    getDocumentEntityMapKey(target_path, target_kind),
+  );
+
+  return {
+    key: semantic_target_key ?? target_path,
+    path: target_path,
+  };
+}
+
+/**
+ * @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} kind_name
+ * @returns {string}
+ */
+function getDocumentEntityMapKey(document_path, kind_name) {
+  return `${kind_name}:${document_path}`;
+}

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,24 @@ 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,
+  );
 
-    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,
+  );
 
   return {
     edges: graph_edges,
@@ -96,56 +98,116 @@ 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
+ * @returns {GraphEdge[]}
  */
-function getPathTargetValue(claim) {
-  if (typeof claim.value === 'string') {
-    return claim.value;
+function createGraphEdges(graph_nodes, mappings, claims, document_entity_keys) {
+  /** @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,
+    );
+    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 +267,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.`);
 }
 
 /**