patram 0.0.2

package/lib/load-patram-config.js

@@ -0,0 +1,244 @@
+/**
+ * @import { LoadPatramConfigResult, PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
+ */
+
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import process from 'node:process';
+
+import { z } from 'zod';
+
+const CONFIG_FILE_NAME = '.patram.json';
+
+const stored_query_schema = z
+  .object({
+    where: z.string().min(1, 'Stored query "where" must not be empty.'),
+  })
+  .strict();
+
+const patram_repo_config_schema = z
+  .object({
+    include: z
+      .array(z.string().min(1, 'Include globs must not be empty.'))
+      .min(1, 'Include must contain at least one glob.'),
+    queries: z.record(z.string().min(1), stored_query_schema),
+  })
+  .strict();
+
+/**
+ * Load and validate the repo Patram config.
+ *
+ * @param {string} [project_directory]
+ * @returns {Promise<LoadPatramConfigResult>}
+ */
+export async function loadPatramConfig(project_directory = process.cwd()) {
+  const config_file_path = resolve(project_directory, CONFIG_FILE_NAME);
+  const config_source = await readConfigSource(config_file_path);
+
+  if (config_source === null) {
+    return createLoadResult(null, [createMissingConfigDiagnostic()]);
+  }
+
+  const parse_result = parseConfigJson(config_source);
+
+  if (!parse_result.success) {
+    return createLoadResult(null, [parse_result.diagnostic]);
+  }
+
+  const config_result = patram_repo_config_schema.safeParse(parse_result.value);
+
+  if (!config_result.success) {
+    return createLoadResult(
+      null,
+      config_result.error.issues.map(createValidationDiagnostic),
+    );
+  }
+
+  return createLoadResult(config_result.data, []);
+}
+
+/**
+ * @param {string} config_file_path
+ * @returns {Promise<string | null>}
+ */
+async function readConfigSource(config_file_path) {
+  try {
+    return await readFile(config_file_path, 'utf8');
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return null;
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * @param {string} config_source
+ * @returns {{ success: true, value: unknown } | { success: false, diagnostic: PatramDiagnostic }}
+ */
+function parseConfigJson(config_source) {
+  try {
+    return {
+      success: true,
+      value: JSON.parse(config_source),
+    };
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      return {
+        diagnostic: createInvalidJsonDiagnostic(config_source, error),
+        success: false,
+      };
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * @param {PatramRepoConfig | null} config
+ * @param {PatramDiagnostic[]} diagnostics
+ * @returns {LoadPatramConfigResult}
+ */
+function createLoadResult(config, diagnostics) {
+  return {
+    config,
+    config_path: CONFIG_FILE_NAME,
+    diagnostics,
+  };
+}
+
+/**
+ * @returns {PatramDiagnostic}
+ */
+function createMissingConfigDiagnostic() {
+  return {
+    code: 'config.not_found',
+    column: 1,
+    level: 'error',
+    line: 1,
+    message: 'Config file ".patram.json" was not found.',
+    path: CONFIG_FILE_NAME,
+  };
+}
+
+/**
+ * @param {string} config_source
+ * @param {SyntaxError} error
+ * @returns {PatramDiagnostic}
+ */
+function createInvalidJsonDiagnostic(config_source, error) {
+  const origin = getJsonSyntaxOrigin(config_source, error.message);
+
+  return {
+    code: 'config.invalid_json',
+    column: origin.column,
+    level: 'error',
+    line: origin.line,
+    message: 'Invalid JSON syntax.',
+    path: CONFIG_FILE_NAME,
+  };
+}
+
+/**
+ * @param {import('zod').core.$ZodIssue} issue
+ * @returns {PatramDiagnostic}
+ */
+function createValidationDiagnostic(issue) {
+  const issue_path = formatIssuePath(issue.path);
+
+  if (issue_path) {
+    return {
+      code: 'config.invalid',
+      column: 1,
+      level: 'error',
+      line: 1,
+      message: `Invalid config at "${issue_path}": ${issue.message}`,
+      path: CONFIG_FILE_NAME,
+    };
+  }
+
+  return {
+    code: 'config.invalid',
+    column: 1,
+    level: 'error',
+    line: 1,
+    message: `Invalid config: ${issue.message}`,
+    path: CONFIG_FILE_NAME,
+  };
+}
+
+/**
+ * @param {unknown} error
+ * @returns {error is NodeJS.ErrnoException}
+ */
+function isMissingFileError(error) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  return 'code' in error && error.code === 'ENOENT';
+}
+
+/**
+ * @param {string} config_source
+ * @param {string} error_message
+ * @returns {{ line: number, column: number }}
+ */
+function getJsonSyntaxOrigin(config_source, error_message) {
+  const position_match = error_message.match(/position (?<offset>\d+)/du);
+
+  if (position_match?.groups?.offset) {
+    const offset = Number.parseInt(position_match.groups.offset, 10);
+
+    return getLineAndColumnFromOffset(config_source, offset);
+  }
+
+  const token_match = error_message.match(/Unexpected token '(?<token>.)'/u);
+
+  if (token_match?.groups?.token) {
+    const offset = config_source.lastIndexOf(token_match.groups.token);
+
+    if (offset >= 0) {
+      return getLineAndColumnFromOffset(config_source, offset);
+    }
+  }
+
+  return {
+    column: 1,
+    line: 1,
+  };
+}
+
+/**
+ * @param {(string | number | symbol | undefined)[]} issue_path
+ * @returns {string}
+ */
+function formatIssuePath(issue_path) {
+  return issue_path.map(String).join('.');
+}
+
+/**
+ * @param {string} source_text
+ * @param {number} offset
+ * @returns {{ line: number, column: number }}
+ */
+function getLineAndColumnFromOffset(source_text, offset) {
+  let line_number = 1;
+  let column_number = 1;
+
+  for (const character of source_text.slice(0, offset)) {
+    if (character === '\n') {
+      line_number += 1;
+      column_number = 1;
+      continue;
+    }
+
+    column_number += 1;
+  }
+
+  return {
+    column: column_number,
+    line: line_number,
+  };
+}

package/lib/load-patram-config.test.js

@@ -0,0 +1,211 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, expect, it } from 'vitest';
+
+import { loadPatramConfig } from './load-patram-config.js';
+
+const test_context = createTestContext();
+
+afterEach(async () => {
+  await cleanupTestContext(test_context);
+});
+
+it('loads and validates .patram.json from a project directory', async () => {
+  test_context.project_directory = await createTempProjectDirectory();
+  await writeProjectConfig(
+    test_context.project_directory,
+    createValidConfigSource(),
+  );
+
+  const load_result = await loadPatramConfig(test_context.project_directory);
+
+  expect(load_result).toEqual({
+    config: {
+      include: ['docs/**/*.md'],
+      queries: {
+        pending: {
+          where: 'kind=task and status=pending',
+        },
+      },
+    },
+    config_path: '.patram.json',
+    diagnostics: [],
+  });
+});
+
+it('defaults to the current working directory', async () => {
+  test_context.project_directory = await createTempProjectDirectory();
+  await writeProjectConfig(
+    test_context.project_directory,
+    createValidConfigSource(),
+  );
+  process.chdir(test_context.project_directory);
+
+  const load_result = await loadPatramConfig();
+
+  expect(load_result.config?.queries.pending.where).toBe(
+    'kind=task and status=pending',
+  );
+  expect(load_result.diagnostics).toEqual([]);
+});
+
+it('reports a missing config file', async () => {
+  test_context.project_directory = await createTempProjectDirectory();
+  const load_result = await loadPatramConfig(test_context.project_directory);
+
+  expect(load_result.config).toBeNull();
+  expect(load_result.diagnostics).toEqual([
+    {
+      code: 'config.not_found',
+      column: 1,
+      level: 'error',
+      line: 1,
+      message: 'Config file ".patram.json" was not found.',
+      path: '.patram.json',
+    },
+  ]);
+});
+
+it('reports invalid JSON syntax', async () => {
+  test_context.project_directory = await createTempProjectDirectory();
+  await writeProjectConfig(test_context.project_directory, createBrokenJson());
+
+  const load_result = await loadPatramConfig(test_context.project_directory);
+
+  expect(load_result.config).toBeNull();
+  expect(load_result.diagnostics).toEqual([
+    {
+      code: 'config.invalid_json',
+      column: 1,
+      level: 'error',
+      line: 3,
+      message: 'Invalid JSON syntax.',
+      path: '.patram.json',
+    },
+  ]);
+});
+
+it('reports config validation diagnostics', async () => {
+  test_context.project_directory = await createTempProjectDirectory();
+  await writeProjectConfig(
+    test_context.project_directory,
+    createInvalidConfigSource(),
+  );
+
+  const load_result = await loadPatramConfig(test_context.project_directory);
+
+  expect(load_result.config).toBeNull();
+  expect(load_result.diagnostics).toEqual([
+    {
+      code: 'config.invalid',
+      column: 1,
+      level: 'error',
+      line: 1,
+      message:
+        'Invalid config at "include": Include must contain at least one glob.',
+      path: '.patram.json',
+    },
+    {
+      code: 'config.invalid',
+      column: 1,
+      level: 'error',
+      line: 1,
+      message:
+        'Invalid config at "queries.pending.where": Stored query "where" must not be empty.',
+      path: '.patram.json',
+    },
+  ]);
+});
+
+/**
+ * Create a temporary project directory.
+ *
+ * @returns {Promise<string>}
+ */
+async function createTempProjectDirectory() {
+  return mkdtemp(join(tmpdir(), 'patram-load-config-'));
+}
+
+/**
+ * Write a project config file.
+ *
+ * @param {string} project_directory
+ * @param {string} config_source
+ */
+async function writeProjectConfig(project_directory, config_source) {
+  await writeFile(join(project_directory, '.patram.json'), config_source);
+}
+
+/**
+ * Remove a temporary directory tree.
+ *
+ * @param {string} project_directory
+ */
+async function removeDirectory(project_directory) {
+  await rm(project_directory, { force: true, recursive: true });
+}
+
+/**
+ * Create invalid JSON for parser tests.
+ *
+ * @returns {string}
+ */
+function createBrokenJson() {
+  return ['{', '  "include": [', '}'].join('\n');
+}
+
+/**
+ * Create invalid config JSON.
+ *
+ * @returns {string}
+ */
+function createInvalidConfigSource() {
+  return JSON.stringify({
+    include: [],
+    queries: {
+      pending: {
+        where: '',
+      },
+    },
+  });
+}
+
+/**
+ * Create valid config JSON.
+ *
+ * @returns {string}
+ */
+function createValidConfigSource() {
+  return JSON.stringify({
+    include: ['docs/**/*.md'],
+    queries: {
+      pending: {
+        where: 'kind=task and status=pending',
+      },
+    },
+  });
+}
+
+/**
+ * @returns {{ original_working_directory: string, project_directory: string | null }}
+ */
+function createTestContext() {
+  return {
+    original_working_directory: process.cwd(),
+    project_directory: null,
+  };
+}
+
+/**
+ * @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 removeDirectory(test_context.project_directory);
+    test_context.project_directory = null;
+  }
+}

package/lib/load-patram-config.types.ts

@@ -0,0 +1,23 @@
+export interface StoredQueryConfig {
+  where: string;
+}
+
+export interface PatramRepoConfig {
+  include: string[];
+  queries: Record<string, StoredQueryConfig>;
+}
+
+export interface PatramDiagnostic {
+  code: string;
+  column: number;
+  level: 'error';
+  line: number;
+  message: string;
+  path: string;
+}
+
+export interface LoadPatramConfigResult {
+  config: PatramRepoConfig | null;
+  config_path: string;
+  diagnostics: PatramDiagnostic[];
+}

package/lib/parse-claims.js

@@ -0,0 +1,178 @@
+/**
+ * @import { PatramClaim, ParseClaimsInput, PatramClaimFields } from './parse-claims.types.ts';
+ */
+
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.markdown']);
+const MARKDOWN_LINK_PATTERN = /\[([^\]]+)\]\(([^)]+)\)/dgu;
+const DIRECTIVE_PATTERN = /^([A-Z][A-Za-z ]+):\s+(.+)$/du;
+const HEADING_PATTERN = /^#\s+(.+)$/du;
+
+/**
+ * Parse a file into neutral Patram claims.
+ *
+ * @param {ParseClaimsInput} parse_input
+ * @returns {PatramClaim[]}
+ */
+export function parseClaims(parse_input) {
+  const file_extension = getFileExtension(parse_input.path);
+
+  if (MARKDOWN_EXTENSIONS.has(file_extension)) {
+    return parseMarkdownClaims(parse_input);
+  }
+
+  return [];
+}
+
+/**
+ * @param {ParseClaimsInput} parse_input
+ * @returns {PatramClaim[]}
+ */
+function parseMarkdownClaims(parse_input) {
+  const lines = parse_input.source.split('\n');
+
+  /** @type {PatramClaim[]} */
+  const claims = [];
+  const title_value = getMarkdownTitle(lines);
+
+  if (title_value) {
+    claims.push(
+      createClaim(parse_input.path, claims.length + 1, 'document.title', {
+        value: title_value,
+      }),
+    );
+  }
+
+  for (const [line_index, line] of lines.entries()) {
+    const line_number = line_index + 1;
+
+    collectMarkdownLinkClaims(parse_input.path, line, line_number, claims);
+    collectDirectiveClaims(parse_input.path, line, line_number, claims);
+  }
+
+  return claims;
+}
+
+/**
+ * @param {string} file_path
+ * @param {string} line
+ * @param {number} line_number
+ * @param {PatramClaim[]} claims
+ */
+function collectMarkdownLinkClaims(file_path, line, line_number, claims) {
+  for (const link_match of line.matchAll(MARKDOWN_LINK_PATTERN)) {
+    const link_text = link_match[1];
+    const target_value = link_match[2];
+    const column_number =
+      link_match.index === undefined ? 1 : link_match.index + 1;
+
+    claims.push(
+      createClaim(file_path, claims.length + 1, 'markdown.link', {
+        origin: {
+          column: column_number,
+          line: line_number,
+          path: file_path,
+        },
+        value: {
+          target: target_value,
+          text: link_text,
+        },
+      }),
+    );
+  }
+}
+
+/**
+ * @param {string} file_path
+ * @param {string} line
+ * @param {number} line_number
+ * @param {PatramClaim[]} claims
+ */
+function collectDirectiveClaims(file_path, line, line_number, claims) {
+  const directive_match = line.match(DIRECTIVE_PATTERN);
+
+  if (!directive_match) {
+    return;
+  }
+
+  const directive_name = normalizeDirectiveName(directive_match[1]);
+  const directive_value = directive_match[2].trim();
+
+  claims.push(
+    createClaim(file_path, claims.length + 1, 'directive', {
+      name: directive_name,
+      origin: {
+        column: 1,
+        line: line_number,
+        path: file_path,
+      },
+      parser: 'markdown',
+      value: directive_value,
+    }),
+  );
+}
+
+/**
+ * @param {string[]} lines
+ * @returns {string | null}
+ */
+function getMarkdownTitle(lines) {
+  const first_line = lines[0].trim();
+
+  if (first_line.length === 0) {
+    return null;
+  }
+
+  const heading_match = first_line.match(HEADING_PATTERN);
+
+  if (heading_match) {
+    return heading_match[1].trim();
+  }
+
+  return first_line;
+}
+
+/**
+ * @param {string} file_path
+ * @param {number} claim_number
+ * @param {string} claim_type
+ * @param {PatramClaimFields} claim_fields
+ * @returns {PatramClaim}
+ */
+function createClaim(file_path, claim_number, claim_type, claim_fields) {
+  const document_id = `doc:${file_path}`;
+  const origin = claim_fields.origin ?? {
+    column: 1,
+    line: 1,
+    path: file_path,
+  };
+
+  return {
+    ...claim_fields,
+    document_id,
+    id: `claim:${document_id}:${claim_number}`,
+    origin,
+    type: claim_type,
+  };
+}
+
+/**
+ * @param {string} directive_label
+ * @returns {string}
+ */
+function normalizeDirectiveName(directive_label) {
+  return directive_label.trim().toLowerCase().replaceAll(/\s+/dgu, '_');
+}
+
+/**
+ * @param {string} file_path
+ * @returns {string}
+ */
+function getFileExtension(file_path) {
+  const last_dot_index = file_path.lastIndexOf('.');
+
+  if (last_dot_index < 0) {
+    return '';
+  }
+
+  return file_path.slice(last_dot_index);
+}