patram 0.0.2

package/lib/build-graph.test.js

@@ -0,0 +1,141 @@
+/**
+ * @import { PatramClaim } from './parse-claims.types.ts';
+ */
+
+import { expect, it } from 'vitest';
+
+import graph_v0_config from '../docs/graph-v0.config.json' with { type: 'json' };
+import { buildGraph } from './build-graph.js';
+import { parseClaims } from './parse-claims.js';
+import { parsePatramConfig } from './patram-config.js';
+
+const patram_config = parsePatramConfig(graph_v0_config);
+
+it('builds document nodes, configured target nodes and edges from claims', () => {
+  const graph = buildGraph(patram_config, createMarkdownClaims());
+
+  expect(graph).toEqual(createExpectedGraph());
+});
+
+it('keeps source document nodes even when a claim has no mapping', () => {
+  const graph = buildGraph(patram_config, [
+    {
+      document_id: 'doc:docs/orphan.md',
+      id: 'claim:doc:docs/orphan.md:1',
+      origin: {
+        column: 1,
+        line: 2,
+        path: 'docs/orphan.md',
+      },
+      type: 'directive',
+      value: 'ignored',
+    },
+  ]);
+
+  expect(graph).toEqual({
+    edges: [],
+    nodes: {
+      'doc:docs/orphan.md': {
+        id: 'doc:docs/orphan.md',
+        kind: 'document',
+        path: 'docs/orphan.md',
+      },
+    },
+  });
+});
+
+/**
+ * Create markdown claims for graph materialization tests.
+ *
+ * @returns {PatramClaim[]}
+ */
+function createMarkdownClaims() {
+  return parseClaims({
+    path: 'docs/patram.md',
+    source: createMarkdownSource(),
+  });
+}
+
+/**
+ * Create markdown input for graph materialization tests.
+ *
+ * @returns {string}
+ */
+function createMarkdownSource() {
+  return [
+    '# Patram',
+    '',
+    'Read the [graph design](./graph-v0.md).',
+    'Defined by: terms/patram.md',
+  ].join('\n');
+}
+
+/**
+ * Create the expected graph for the materialization test.
+ *
+ * @returns {object}
+ */
+function createExpectedGraph() {
+  return {
+    edges: createExpectedEdges(),
+    nodes: createExpectedNodes(),
+  };
+}
+
+/**
+ * Create the expected edges for the materialization test.
+ *
+ * @returns {object[]}
+ */
+function createExpectedEdges() {
+  return [
+    {
+      from: 'doc:docs/patram.md',
+      id: 'edge:1',
+      origin: {
+        column: 10,
+        line: 3,
+        path: 'docs/patram.md',
+      },
+      relation: 'links_to',
+      to: 'doc:docs/graph-v0.md',
+    },
+    {
+      from: 'doc:docs/patram.md',
+      id: 'edge:2',
+      origin: {
+        column: 1,
+        line: 4,
+        path: 'docs/patram.md',
+      },
+      relation: 'defines',
+      to: 'term:docs/terms/patram.md',
+    },
+  ];
+}
+
+/**
+ * Create the expected nodes for the materialization test.
+ *
+ * @returns {object}
+ */
+function createExpectedNodes() {
+  return {
+    'doc:docs/graph-v0.md': {
+      id: 'doc:docs/graph-v0.md',
+      kind: 'document',
+      path: 'docs/graph-v0.md',
+    },
+    'doc:docs/patram.md': {
+      id: 'doc:docs/patram.md',
+      kind: 'document',
+      path: 'docs/patram.md',
+      title: 'Patram',
+    },
+    'term:docs/terms/patram.md': {
+      id: 'term:docs/terms/patram.md',
+      key: 'docs/terms/patram.md',
+      kind: 'term',
+    },
+  };
+}

package/lib/build-graph.types.ts

@@ -0,0 +1,23 @@
+import type { ClaimOrigin } from './parse-claims.types.ts';
+
+export interface GraphNode {
+  id: string;
+  kind: string;
+  key?: string;
+  path?: string;
+  title?: string;
+  [field: string]: string | undefined;
+}
+
+export interface GraphEdge {
+  from: string;
+  id: string;
+  origin: ClaimOrigin;
+  relation: string;
+  to: string;
+}
+
+export interface BuildGraphResult {
+  edges: GraphEdge[];
+  nodes: Record<string, GraphNode>;
+}

package/lib/check-graph.js

@@ -0,0 +1,125 @@
+/**
+ * @import { BuildGraphResult, GraphEdge, GraphNode } from './build-graph.types.ts';
+ * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ */
+
+/**
+ * Check a materialized graph for broken document links and missing edge nodes.
+ *
+ * @param {BuildGraphResult} graph
+ * @param {string[]} source_file_paths
+ * @returns {PatramDiagnostic[]}
+ */
+export function checkGraph(graph, source_file_paths) {
+  /** @type {PatramDiagnostic[]} */
+  const diagnostics = [];
+  const source_file_path_set = new Set(source_file_paths);
+
+  for (const graph_edge of graph.edges) {
+    const source_node = graph.nodes[graph_edge.from];
+    const target_node = graph.nodes[graph_edge.to];
+
+    collectMissingNodeDiagnostics(
+      diagnostics,
+      graph_edge,
+      source_node,
+      target_node,
+    );
+
+    if (!target_node) {
+      continue;
+    }
+
+    collectBrokenLinkDiagnostics(
+      diagnostics,
+      graph_edge,
+      target_node,
+      source_file_path_set,
+    );
+  }
+
+  return diagnostics;
+}
+
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {GraphEdge} graph_edge
+ * @param {GraphNode | undefined} source_node
+ * @param {GraphNode | undefined} target_node
+ */
+function collectMissingNodeDiagnostics(
+  diagnostics,
+  graph_edge,
+  source_node,
+  target_node,
+) {
+  if (!source_node) {
+    diagnostics.push(
+      createDiagnostic(
+        graph_edge,
+        'graph.edge_missing_from',
+        `Graph edge "${graph_edge.id}" references missing source node "${graph_edge.from}".`,
+      ),
+    );
+  }
+
+  if (!target_node) {
+    diagnostics.push(
+      createDiagnostic(
+        graph_edge,
+        'graph.edge_missing_to',
+        `Graph edge "${graph_edge.id}" references missing target node "${graph_edge.to}".`,
+      ),
+    );
+  }
+}
+
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {GraphEdge} graph_edge
+ * @param {GraphNode} target_node
+ * @param {Set<string>} source_file_path_set
+ */
+function collectBrokenLinkDiagnostics(
+  diagnostics,
+  graph_edge,
+  target_node,
+  source_file_path_set,
+) {
+  if (graph_edge.relation !== 'links_to') {
+    return;
+  }
+
+  if (target_node.kind !== 'document' || !target_node.path) {
+    return;
+  }
+
+  if (source_file_path_set.has(target_node.path)) {
+    return;
+  }
+
+  diagnostics.push(
+    createDiagnostic(
+      graph_edge,
+      'graph.link_broken',
+      `Document link target "${target_node.path}" was not found.`,
+    ),
+  );
+}
+
+/**
+ * @param {GraphEdge} graph_edge
+ * @param {string} code
+ * @param {string} message
+ * @returns {PatramDiagnostic}
+ */
+function createDiagnostic(graph_edge, code, message) {
+  return {
+    code,
+    column: graph_edge.origin.column,
+    level: 'error',
+    line: graph_edge.origin.line,
+    message,
+    path: graph_edge.origin.path,
+  };
+}

package/lib/check-graph.test.js

@@ -0,0 +1,103 @@
+/**
+ * @import { BuildGraphResult } from './build-graph.types.ts';
+ */
+import { expect, it } from 'vitest';
+
+import { checkGraph } from './check-graph.js';
+
+it('reports broken document links', () => {
+  const diagnostics = checkGraph(createGraphWithBrokenLink(), [
+    'docs/patram.md',
+  ]);
+
+  expect(diagnostics).toEqual([
+    {
+      code: 'graph.link_broken',
+      column: 10,
+      level: 'error',
+      line: 3,
+      message: 'Document link target "docs/missing.md" was not found.',
+      path: 'docs/patram.md',
+    },
+  ]);
+});
+
+it('reports graph edges that reference missing nodes', () => {
+  const diagnostics = checkGraph(createGraphWithMissingTargetNode(), [
+    'docs/patram.md',
+  ]);
+
+  expect(diagnostics).toEqual([
+    {
+      code: 'graph.edge_missing_to',
+      column: 8,
+      level: 'error',
+      line: 6,
+      message:
+        'Graph edge "edge:1" references missing target node "doc:docs/missing.md".',
+      path: 'docs/patram.md',
+    },
+  ]);
+});
+
+/**
+ * @returns {BuildGraphResult}
+ */
+function createGraphWithBrokenLink() {
+  return {
+    edges: [
+      {
+        from: 'doc:docs/patram.md',
+        id: 'edge:1',
+        origin: {
+          column: 10,
+          line: 3,
+          path: 'docs/patram.md',
+        },
+        relation: 'links_to',
+        to: 'doc:docs/missing.md',
+      },
+    ],
+    nodes: {
+      'doc:docs/missing.md': {
+        id: 'doc:docs/missing.md',
+        kind: 'document',
+        path: 'docs/missing.md',
+      },
+      'doc:docs/patram.md': {
+        id: 'doc:docs/patram.md',
+        kind: 'document',
+        path: 'docs/patram.md',
+        title: 'Patram',
+      },
+    },
+  };
+}
+
+/**
+ * @returns {BuildGraphResult}
+ */
+function createGraphWithMissingTargetNode() {
+  return {
+    edges: [
+      {
+        from: 'doc:docs/patram.md',
+        id: 'edge:1',
+        origin: {
+          column: 8,
+          line: 6,
+          path: 'docs/patram.md',
+        },
+        relation: 'links_to',
+        to: 'doc:docs/missing.md',
+      },
+    ],
+    nodes: {
+      'doc:docs/patram.md': {
+        id: 'doc:docs/patram.md',
+        kind: 'document',
+        path: 'docs/patram.md',
+      },
+    },
+  };
+}

package/lib/list-source-files.js

@@ -0,0 +1,44 @@
+import { glob } from 'node:fs/promises';
+import process from 'node:process';
+
+/**
+ * List source files matched by Patram include globs.
+ *
+ * @param {string[]} include_patterns
+ * @param {string} [project_directory]
+ * @returns {Promise<string[]>}
+ */
+export async function listSourceFiles(
+  include_patterns,
+  project_directory = process.cwd(),
+) {
+  /** @type {Set<string>} */
+  const source_file_paths = new Set();
+
+  for (const include_pattern of include_patterns) {
+    for await (const matched_path of glob(include_pattern, {
+      cwd: project_directory,
+    })) {
+      source_file_paths.add(normalizeRepoRelativePath(matched_path));
+    }
+  }
+
+  return [...source_file_paths].sort(comparePaths);
+}
+
+/**
+ * @param {string} source_path
+ * @returns {string}
+ */
+function normalizeRepoRelativePath(source_path) {
+  return source_path.replaceAll('\\', '/');
+}
+
+/**
+ * @param {string} left_path
+ * @param {string} right_path
+ * @returns {number}
+ */
+function comparePaths(left_path, right_path) {
+  return left_path.localeCompare(right_path, 'en');
+}

package/lib/list-source-files.test.js

@@ -0,0 +1,101 @@
+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 { listSourceFiles } from './list-source-files.js';
+
+const test_context = createTestContext();
+
+afterEach(async () => {
+  await cleanupTestContext(test_context);
+});
+
+it('lists matching source files as sorted repo-relative paths', async () => {
+  test_context.project_directory = await createTempProjectDirectory();
+
+  await writeProjectFile(test_context.project_directory, 'docs/zeta.md');
+  await writeProjectFile(test_context.project_directory, 'docs/alpha.md');
+  await writeProjectFile(
+    test_context.project_directory,
+    'docs/nested/overview.md',
+  );
+  await writeProjectFile(test_context.project_directory, 'docs/notes.txt');
+  await writeProjectFile(test_context.project_directory, 'notes/todo.md');
+
+  const source_files = await listSourceFiles(
+    ['docs/**/*.md'],
+    test_context.project_directory,
+  );
+
+  expect(source_files).toEqual([
+    'docs/alpha.md',
+    'docs/nested/overview.md',
+    'docs/zeta.md',
+  ]);
+});
+
+it('deduplicates paths matched by multiple include globs', async () => {
+  test_context.project_directory = await createTempProjectDirectory();
+
+  await writeProjectFile(test_context.project_directory, 'docs/patram.md');
+
+  const source_files = await listSourceFiles(
+    ['docs/**/*.md', 'docs/patram.md'],
+    test_context.project_directory,
+  );
+
+  expect(source_files).toEqual(['docs/patram.md']);
+});
+
+/**
+ * Create a temporary project directory.
+ *
+ * @returns {Promise<string>}
+ */
+async function createTempProjectDirectory() {
+  return mkdtemp(join(tmpdir(), 'patram-list-source-files-'));
+}
+
+/**
+ * Write a file under the temporary project directory.
+ *
+ * @param {string} project_directory
+ * @param {string} relative_path
+ */
+async function writeProjectFile(project_directory, relative_path) {
+  const file_path = join(project_directory, relative_path);
+  const parent_directory = file_path.slice(0, file_path.lastIndexOf('/'));
+
+  await mkdir(parent_directory, { recursive: true });
+  await writeFile(file_path, `# ${relative_path}\n`);
+}
+
+/**
+ * Remove a temporary directory tree.
+ *
+ * @param {string} project_directory
+ */
+async function removeDirectory(project_directory) {
+  await rm(project_directory, { force: true, recursive: true });
+}
+
+/**
+ * @returns {{ project_directory: string | null }}
+ */
+function createTestContext() {
+  return {
+    project_directory: null,
+  };
+}
+
+/**
+ * @param {{ project_directory: string | null }} test_context
+ */
+async function cleanupTestContext(test_context) {
+  if (test_context.project_directory) {
+    await removeDirectory(test_context.project_directory);
+    test_context.project_directory = null;
+  }
+}