patram 0.0.2 → 0.2.0

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,270 @@
+/**
+ * @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
+ * @param {Set<string>} document_paths
+ * @returns {{ key: string, path?: string }}
+ */
+export function resolveTargetReference(
+  target_kind,
+  target_type,
+  claim,
+  document_entity_keys,
+  document_paths,
+) {
+  if (target_type === 'value') {
+    return resolveValueTargetReference(target_kind, claim);
+  }
+
+  return resolvePathTargetReference(
+    target_kind,
+    claim,
+    document_entity_keys,
+    document_paths,
+  );
+}
+
+/**
+ * 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
+ * @param {Set<string>} document_paths
+ * @returns {{ key: string, path?: string }}
+ */
+function resolvePathTargetReference(
+  target_kind,
+  claim,
+  document_entity_keys,
+  document_paths,
+) {
+  const raw_target = getPathTargetValue(claim);
+  const target_path = resolveDirectiveAwareTargetPath(
+    claim,
+    raw_target,
+    document_paths,
+  );
+
+  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
+ * @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' && document_paths.has(normalized_raw_target)) {
+    return normalized_raw_target;
+  }
+
+  const source_directory = posix.dirname(
+    normalizeRepoRelativePath(claim.origin.path),
+  );
+
+  return normalizeRepoRelativePath(posix.join(source_directory, raw_target));
+}
+
+/**
+ * @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}`;
+}