patram 0.0.2 → 0.2.0

package/lib/write-paged-output.js

@@ -0,0 +1,87 @@
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import process from 'node:process';
+
+/**
+ * @param {string} output_text
+ * @returns {Promise<void>}
+ */
+export async function writePagedOutput(output_text) {
+  const pager_command = process.env.PAGER?.trim();
+
+  if (pager_command) {
+    await writeOutputThroughPager(output_text, pager_command, [], true);
+
+    return;
+  }
+
+  await writeOutputThroughPager(output_text, 'less', ['-FIRXS'], false);
+}
+
+/**
+ * @param {string} output_text
+ * @param {string} pager_command
+ * @param {string[]} pager_arguments
+ * @param {boolean} use_shell
+ * @returns {Promise<void>}
+ */
+async function writeOutputThroughPager(
+  output_text,
+  pager_command,
+  pager_arguments,
+  use_shell,
+) {
+  const pager_process = spawn(pager_command, pager_arguments, {
+    shell: use_shell,
+    stdio: ['pipe', 'inherit', 'inherit'],
+  });
+  const close_promise = once(pager_process, 'close');
+  const error_promise = once(pager_process, 'error').then(([error]) => {
+    throw error;
+  });
+
+  await writeToPagerInput(pager_process.stdin, output_text);
+
+  const [exit_code, signal_code] = await Promise.race([
+    close_promise,
+    error_promise,
+  ]);
+
+  if (exit_code === 0) {
+    return;
+  }
+
+  if (signal_code) {
+    throw new Error(`Pager exited with signal "${signal_code}".`);
+  }
+
+  throw new Error(`Pager exited with code ${exit_code}.`);
+}
+
+/**
+ * @param {NodeJS.WritableStream} pager_input
+ * @param {string} output_text
+ * @returns {Promise<void>}
+ */
+function writeToPagerInput(pager_input, output_text) {
+  return new Promise((resolve, reject) => {
+    pager_input.once('error', (error) => {
+      if (isBrokenPipe(error)) {
+        resolve();
+
+        return;
+      }
+
+      reject(error);
+    });
+    pager_input.end(output_text, 'utf8', resolve);
+  });
+}
+
+/**
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isBrokenPipe(error) {
+  return error instanceof Error && 'code' in error && error.code === 'EPIPE';
+}

package/package.json

@@ -1,13 +1,23 @@
 {
   "name": "patram",
-  "version": "0.0.2",
+  "version": "0.2.0",
   "type": "module",
+  "main": "./lib/patram.js",
+  "exports": {
+    ".": "./lib/patram.js",
+    "./bin/patram.js": "./bin/patram.js"
+  },
   "files": [
-    "bin/",
-    "lib/"
+    "bin/patram.js",
+    "lib/**/*.js",
+    "lib/**/*.ts",
+    "!bin/**/*.test.js",
+    "!bin/**/*.test-helpers.js",
+    "!lib/**/*.test.js",
+    "!lib/**/*.test-helpers.js"
   ],
   "bin": {
-    "patram": "./bin/patram.js"
+    "patram": "bin/patram.js"
   },
   "homepage": "https://github.com/mantoni/patram",
   "repository": {
@@ -19,18 +29,18 @@
   },
   "license": "MIT",
   "scripts": {
-    "all": "npm run check:lint && npm run check:format && npm run check:types && npm run test:unit && npm run test:coverage && npm run check:dupes",
+    "all": "npm run check:lint && npm run check:format && npm run check:types && npm run check:patram && npm run test:coverage && npm run check:dupes",
     "check:dupes": "jscpd --min-tokens 100 --min-lines 6 --mode mild --threshold 0 --reporters console --gitignore .",
     "check:format": "prettier --check .",
     "check:lint": "eslint .",
-    "check:staged": "lint-staged --quiet",
+    "check:patram": "./bin/patram.js check",
+    "check:staged": "lint-staged",
     "check:types": "tsc",
     "postversion": "git push && git push --tags",
     "preversion": "npm run all",
     "prepare": "husky",
-    "test": "npm run test:unit && npm run test:coverage",
+    "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "test:unit": "vitest run",
     "version": "node scripts/update-changelog.js && git add CHANGELOG.md package.json package-lock.json"
   },
   "lint-staged": {
@@ -41,13 +51,21 @@
     ]
   },
   "dependencies": {
+    "@shikijs/cli": "^4.0.2",
+    "@shikijs/vscode-textmate": "^10.0.2",
+    "ansis": "^4.2.0",
+    "beautiful-mermaid": "^1.1.3",
+    "globby": "^16.1.1",
+    "md4x": "^0.0.25",
+    "shiki": "^4.0.2",
+    "string-width": "^8.2.0",
+    "wrap-ansi": "^10.0.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^24.12.0",
     "@vitest/coverage-v8": "^4.1.0",
-    "ansis": "^4.2.0",
     "eslint": "^10.0.3",
     "eslint-plugin-jsdoc": "^62.8.0",
     "globals": "^17.4.0",
@@ -56,9 +74,7 @@
     "lint-staged": "^16.2.6",
     "prettier": "^3.5.3",
     "slice-ansi": "^8.0.0",
-    "string-width": "^8.2.0",
     "typescript": "^5.8.2",
-    "vitest": "^4.1.0",
-    "wrap-ansi": "^10.0.0"
+    "vitest": "^4.1.0"
   }
 }

package/bin/patram.test.js

@@ -1,184 +0,0 @@
-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.test.js

@@ -1,141 +0,0 @@
-/**
- * @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/check-graph.test.js

@@ -1,103 +0,0 @@
-/**
- * @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.test.js

@@ -1,101 +0,0 @@
-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;
-  }
-}