patram 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maximilian Antoni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/patram.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+
+/**
+ * @import { PatramClaim } from '../lib/parse-claims.types.ts';
+ */
+
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import process from 'node:process';
+import { pathToFileURL } 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';
+
+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'],
+    },
+  },
+});
+
+if (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`;
+}
+
+/**
+ * @param {string} module_url
+ * @param {string | undefined} process_entry_path
+ * @returns {boolean}
+ */
+function isEntrypoint(module_url, process_entry_path) {
+  if (!process_entry_path) {
+    return false;
+  }
+
+  return module_url === pathToFileURL(process_entry_path).href;
+}

package/bin/patram.test.js

@@ -0,0 +1,184 @@
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, expect, it } from 'vitest';
+
+import { main } from './patram.js';
+
+const test_context = createTestContext();
+
+afterEach(async () => {
+  await cleanupTestContext(test_context);
+});
+
+it('prints config diagnostics for check failures', async () => {
+  test_context.project_directory = await createTempProjectDirectory();
+  const io_context = createIoContext();
+
+  const exit_code = await main(['check', test_context.project_directory], {
+    stderr: io_context.stderr,
+    stdout: io_context.stdout,
+  });
+
+  expect(exit_code).toBe(1);
+  expect(io_context.stderr_chunks).toEqual([
+    '.patram.json:1:1 error config.not_found Config file ".patram.json" was not found.\n',
+  ]);
+  expect(io_context.stdout_chunks).toEqual([]);
+});
+
+it('prints broken link diagnostics for check failures', async () => {
+  test_context.project_directory = await createTempProjectDirectory();
+  const io_context = createIoContext();
+
+  await writeProjectConfig(test_context.project_directory);
+  await writeProjectFile(
+    test_context.project_directory,
+    'docs/patram.md',
+    createBrokenLinkSource(),
+  );
+
+  const exit_code = await main(['check', test_context.project_directory], {
+    stderr: io_context.stderr,
+    stdout: io_context.stdout,
+  });
+
+  expect(exit_code).toBe(1);
+  expect(io_context.stderr_chunks).toEqual([
+    'docs/patram.md:3:5 error graph.link_broken Document link target "docs/missing.md" was not found.\n',
+  ]);
+});
+
+it('defaults check to the current working directory and exits 0 on valid input', async () => {
+  test_context.project_directory = await createTempProjectDirectory();
+  const io_context = createIoContext();
+
+  await writeProjectConfig(test_context.project_directory);
+  await writeProjectFile(
+    test_context.project_directory,
+    'docs/patram.md',
+    createValidLinkSource(),
+  );
+  await writeProjectFile(
+    test_context.project_directory,
+    'docs/guide.md',
+    '# Guide\n',
+  );
+  process.chdir(test_context.project_directory);
+
+  const exit_code = await main(['check'], {
+    stderr: io_context.stderr,
+    stdout: io_context.stdout,
+  });
+
+  expect(exit_code).toBe(0);
+  expect(io_context.stderr_chunks).toEqual([]);
+  expect(io_context.stdout_chunks).toEqual([]);
+});
+
+/**
+ * @returns {string}
+ */
+function createBrokenLinkSource() {
+  return ['# Patram', '', 'See [missing](./missing.md).'].join('\n');
+}
+
+/**
+ * @returns {string}
+ */
+function createValidLinkSource() {
+  return ['# Patram', '', 'See [guide](./guide.md).'].join('\n');
+}
+
+/**
+ * @returns {{ original_working_directory: string, project_directory: string | null }}
+ */
+function createTestContext() {
+  return {
+    original_working_directory: process.cwd(),
+    project_directory: null,
+  };
+}
+
+/**
+ * @returns {{ stderr: { write(chunk: string): boolean }, stderr_chunks: string[], stdout: { write(chunk: string): boolean }, stdout_chunks: string[] }}
+ */
+function createIoContext() {
+  /** @type {string[]} */
+  const stderr_chunks = [];
+  /** @type {string[]} */
+  const stdout_chunks = [];
+
+  return {
+    stderr: {
+      /**
+       * @param {string} chunk
+       * @returns {boolean}
+       */
+      write(chunk) {
+        stderr_chunks.push(chunk);
+
+        return true;
+      },
+    },
+    stderr_chunks,
+    stdout: {
+      /**
+       * @param {string} chunk
+       * @returns {boolean}
+       */
+      write(chunk) {
+        stdout_chunks.push(chunk);
+
+        return true;
+      },
+    },
+    stdout_chunks,
+  };
+}
+
+/**
+ * @returns {Promise<string>}
+ */
+async function createTempProjectDirectory() {
+  return mkdtemp(join(tmpdir(), 'patram-check-command-'));
+}
+
+/**
+ * @param {{ original_working_directory: string, project_directory: string | null }} test_context
+ */
+async function cleanupTestContext(test_context) {
+  process.chdir(test_context.original_working_directory);
+
+  if (test_context.project_directory) {
+    await rm(test_context.project_directory, { force: true, recursive: true });
+    test_context.project_directory = null;
+  }
+}
+
+/**
+ * @param {string} project_directory
+ */
+async function writeProjectConfig(project_directory) {
+  await writeFile(
+    join(project_directory, '.patram.json'),
+    JSON.stringify({
+      include: ['docs/**/*.md'],
+      queries: {},
+    }),
+  );
+}
+
+/**
+ * @param {string} project_directory
+ * @param {string} relative_path
+ * @param {string} source_text
+ */
+async function writeProjectFile(project_directory, relative_path, source_text) {
+  const file_path = join(project_directory, relative_path);
+  const directory_path = file_path.slice(0, file_path.lastIndexOf('/'));
+
+  await mkdir(directory_path, { recursive: true });
+  await writeFile(file_path, source_text);
+}

package/lib/build-graph.js

@@ -0,0 +1,222 @@
+/**
+ * @import { BuildGraphResult, GraphEdge, GraphNode } from './build-graph.types.ts';
+ * @import { PatramClaim } from './parse-claims.types.ts';
+ * @import { MappingDefinition, PatramConfig } from './patram-config.types.ts';
+ */
+
+import { posix } from 'node:path';
+
+/**
+ * Build a Patram graph from semantic config and parsed claims.
+ *
+ * @param {PatramConfig} patram_config
+ * @param {PatramClaim[]} claims
+ * @returns {BuildGraphResult}
+ */
+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,
+    );
+
+    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 {
+    edges: graph_edges,
+    nodes: Object.fromEntries(
+      [...graph_nodes.entries()].sort(compareNodeEntries),
+    ),
+  };
+}
+
+/**
+ * @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 {Map<string, GraphNode>} graph_nodes
+ * @param {{ field: string, kind: string }} node_mapping
+ * @param {PatramClaim} claim
+ */
+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);
+}
+
+/**
+ * @param {'path'} target_type
+ * @param {PatramClaim} claim
+ * @returns {string}
+ */
+function resolveTargetKey(target_type, claim) {
+  if (target_type !== 'path') {
+    throw new Error(`Unsupported target type "${target_type}".`);
+  }
+
+  const source_directory = posix.dirname(
+    normalizeRepoRelativePath(claim.origin.path),
+  );
+  const raw_target = getPathTargetValue(claim);
+
+  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 {Map<string, GraphNode>} graph_nodes
+ * @param {string} kind_name
+ * @param {string} node_key
+ * @returns {GraphNode}
+ */
+function upsertNode(graph_nodes, kind_name, node_key) {
+  const node_id = getNodeId(kind_name, node_key);
+  const existing_node = graph_nodes.get(node_id);
+
+  if (existing_node) {
+    return existing_node;
+  }
+
+  const graph_node = createNode(node_id, kind_name, node_key);
+
+  graph_nodes.set(node_id, graph_node);
+
+  return graph_node;
+}
+
+/**
+ * @param {string} node_id
+ * @param {string} kind_name
+ * @param {string} node_key
+ * @returns {GraphNode}
+ */
+function createNode(node_id, kind_name, node_key) {
+  if (kind_name === 'document') {
+    return {
+      id: node_id,
+      kind: kind_name,
+      path: node_key,
+    };
+  }
+
+  return {
+    id: node_id,
+    key: node_key,
+    kind: kind_name,
+  };
+}
+
+/**
+ * @param {string} kind_name
+ * @param {string} node_key
+ * @returns {string}
+ */
+function getNodeId(kind_name, node_key) {
+  if (kind_name === 'document') {
+    return `doc:${node_key}`;
+  }
+
+  return `${kind_name}:${node_key}`;
+}
+
+/**
+ * @param {string} source_path
+ * @returns {string}
+ */
+function normalizeRepoRelativePath(source_path) {
+  return posix.normalize(source_path.replaceAll('\\', '/'));
+}
+
+/**
+ * @param {[string, GraphNode]} left_entry
+ * @param {[string, GraphNode]} right_entry
+ * @returns {number}
+ */
+function compareNodeEntries(left_entry, right_entry) {
+  return left_entry[0].localeCompare(right_entry[0], 'en');
+}