patram 0.0.2 → 0.2.0

package/lib/source-file-defaults.js

@@ -0,0 +1,28 @@
+export const MARKDOWN_SOURCE_FILE_EXTENSIONS = ['.markdown', '.md'];
+
+export const JSDOC_SOURCE_FILE_EXTENSIONS = [
+  '.cjs',
+  '.cts',
+  '.js',
+  '.jsx',
+  '.mjs',
+  '.mts',
+  '.ts',
+  '.tsx',
+];
+
+export const SUPPORTED_SOURCE_FILE_EXTENSIONS = [
+  ...JSDOC_SOURCE_FILE_EXTENSIONS,
+  ...MARKDOWN_SOURCE_FILE_EXTENSIONS,
+];
+
+export const DEFAULT_INCLUDE_PATTERNS =
+  SUPPORTED_SOURCE_FILE_EXTENSIONS.map(createIncludePattern);
+
+/**
+ * @param {string} file_extension
+ * @returns {string}
+ */
+function createIncludePattern(file_extension) {
+  return `**/*${file_extension}`;
+}

package/lib/tagged-fenced-block-error.js

@@ -0,0 +1,17 @@
+/**
+ * @import { TaggedFencedBlockError } from './tagged-fenced-blocks.types.ts';
+ */
+
+/**
+ * @param {string} code
+ * @param {string} message
+ * @returns {TaggedFencedBlockError}
+ */
+export function createTaggedFencedBlockError(code, message) {
+  const error = /** @type {TaggedFencedBlockError} */ (new Error(message));
+
+  error.code = code;
+  error.name = 'TaggedFencedBlockError';
+
+  return error;
+}

package/lib/tagged-fenced-block-markdown.js

@@ -0,0 +1,111 @@
+const FRONT_MATTER_BOUNDARY_PATTERN = /^---$/du;
+const HEADING_PATTERN = /^(#{1,6})\s+(.+?)(?:\s+#+\s*)?$/du;
+const MARKDOWN_FENCE_PATTERN = /^([`~]{3,})(.*)$/du;
+
+/**
+ * @param {string[]} lines
+ * @returns {number}
+ */
+export function findMarkdownBodyStartLineIndex(lines) {
+  if (lines[0] !== '---') {
+    return 0;
+  }
+
+  for (let line_index = 1; line_index < lines.length; line_index += 1) {
+    if (FRONT_MATTER_BOUNDARY_PATTERN.test(lines[line_index])) {
+      return line_index + 1;
+    }
+  }
+
+  return 0;
+}
+
+/**
+ * @param {string[]} lines
+ * @param {number} body_start
+ * @returns {string}
+ */
+export function getMarkdownTitle(lines, body_start) {
+  const title_line = lines[body_start];
+
+  if (title_line === undefined) {
+    return '';
+  }
+
+  const trimmed_line = title_line.trim();
+
+  if (trimmed_line.length === 0) {
+    return '';
+  }
+
+  return parseHeading(trimmed_line)?.text ?? trimmed_line;
+}
+
+/**
+ * @param {string} line
+ * @returns {{ level: number, text: string } | null}
+ */
+export function parseHeading(line) {
+  const heading_match = line.trim().match(HEADING_PATTERN);
+
+  if (!heading_match) {
+    return null;
+  }
+
+  return {
+    level: heading_match[1].length,
+    text: heading_match[2].trim(),
+  };
+}
+
+/**
+ * @param {string[]} heading_path
+ * @param {string} title
+ * @param {{ level: number, text: string }} heading
+ * @returns {string[]}
+ */
+export function updateHeadingPath(heading_path, title, heading) {
+  if (heading.level === 1) {
+    return [heading.text];
+  }
+
+  const next_heading_path = heading_path.slice(0, heading.level - 1);
+
+  if (next_heading_path.length === 0 && title.length > 0) {
+    next_heading_path.push(title);
+  }
+
+  next_heading_path.push(heading.text);
+
+  return next_heading_path;
+}
+
+/**
+ * @param {string} line
+ * @returns {{ character: string, lang: string, length: number } | null}
+ */
+export function parseOpeningMarkdownFence(line) {
+  const trimmed_line = line.trimStart();
+  const fence_match = trimmed_line.match(MARKDOWN_FENCE_PATTERN);
+
+  if (!fence_match) {
+    return null;
+  }
+
+  return {
+    character: fence_match[1][0],
+    lang: fence_match[2].trim(),
+    length: fence_match[1].length,
+  };
+}
+
+/**
+ * @param {string} line
+ * @param {{ character: string, length: number }} open_fence
+ * @returns {boolean}
+ */
+export function isClosingMarkdownFence(line, open_fence) {
+  return line
+    .trimStart()
+    .startsWith(open_fence.character.repeat(open_fence.length));
+}

package/lib/tagged-fenced-block-metadata.js

@@ -0,0 +1,97 @@
+import { createTaggedFencedBlockError } from './tagged-fenced-block-error.js';
+
+const TAGGED_METADATA_LINE_PATTERN = /^\[patram\s+(.+)\]:\s*#\s*$/du;
+const TAGGED_METADATA_PAIR_PATTERN = /^([a-z][a-z0-9_]*)=([^\s]+)$/du;
+
+/**
+ * @param {string} file_path
+ * @param {{ metadata: Record<string, string>, tag_lines: number[] }} pending_tag_set
+ * @param {{ metadata: Record<string, string>, tag_lines: number[] }} next_tag_set
+ * @returns {{ metadata: Record<string, string>, tag_lines: number[] }}
+ */
+export function mergePendingTagSets(file_path, pending_tag_set, next_tag_set) {
+  /** @type {Record<string, string>} */
+  const metadata = { ...pending_tag_set.metadata };
+
+  for (const [key, value] of Object.entries(next_tag_set.metadata)) {
+    if (metadata[key] !== undefined) {
+      throw createTaggedFencedBlockError(
+        'tagged_fenced_blocks.duplicate_metadata_key',
+        `Duplicate tagged metadata key "${key}" in "${file_path}" at line ${next_tag_set.tag_lines[0]}.`,
+      );
+    }
+
+    metadata[key] = value;
+  }
+
+  return {
+    metadata,
+    tag_lines: [...pending_tag_set.tag_lines, ...next_tag_set.tag_lines],
+  };
+}
+
+/**
+ * @param {string} file_path
+ * @param {string} line
+ * @param {number} line_number
+ * @returns {{ metadata: Record<string, string>, tag_lines: number[] } | null}
+ */
+export function parseTaggedMetadataLine(file_path, line, line_number) {
+  const trimmed_line = line.trim();
+
+  if (!trimmed_line.startsWith('[patram')) {
+    return null;
+  }
+
+  const metadata_match = trimmed_line.match(TAGGED_METADATA_LINE_PATTERN);
+
+  if (!metadata_match) {
+    throw createTaggedFencedBlockError(
+      'tagged_fenced_blocks.invalid_tag_line',
+      `Invalid tagged metadata line in "${file_path}" at line ${line_number}.`,
+    );
+  }
+
+  return {
+    metadata: parseTaggedMetadataPairs(
+      file_path,
+      metadata_match[1],
+      line_number,
+    ),
+    tag_lines: [line_number],
+  };
+}
+
+/**
+ * @param {string} file_path
+ * @param {string} pair_text
+ * @param {number} line_number
+ * @returns {Record<string, string>}
+ */
+function parseTaggedMetadataPairs(file_path, pair_text, line_number) {
+  const tokens = pair_text.split(/\s+/du);
+  /** @type {Record<string, string>} */
+  const metadata = {};
+
+  for (const token of tokens) {
+    const pair_match = token.match(TAGGED_METADATA_PAIR_PATTERN);
+
+    if (!pair_match) {
+      throw createTaggedFencedBlockError(
+        'tagged_fenced_blocks.invalid_tag_line',
+        `Invalid tagged metadata line in "${file_path}" at line ${line_number}.`,
+      );
+    }
+
+    if (metadata[pair_match[1]] !== undefined) {
+      throw createTaggedFencedBlockError(
+        'tagged_fenced_blocks.duplicate_metadata_key',
+        `Duplicate tagged metadata key "${pair_match[1]}" in "${file_path}" at line ${line_number}.`,
+      );
+    }
+
+    metadata[pair_match[1]] = pair_match[2];
+  }
+
+  return metadata;
+}

package/lib/tagged-fenced-block-parser.js

@@ -0,0 +1,292 @@
+/**
+ * @import {
+ *   TaggedFencedBlock,
+ *   TaggedFencedBlockFile,
+ *   TaggedFencedBlocksInput,
+ * } from './tagged-fenced-blocks.types.ts';
+ */
+
+import {
+  findMarkdownBodyStartLineIndex,
+  getMarkdownTitle,
+  isClosingMarkdownFence,
+  parseHeading,
+  parseOpeningMarkdownFence,
+  updateHeadingPath,
+} from './tagged-fenced-block-markdown.js';
+import {
+  mergePendingTagSets,
+  parseTaggedMetadataLine,
+} from './tagged-fenced-block-metadata.js';
+import { createTaggedFencedBlockError } from './tagged-fenced-block-error.js';
+
+const BLANK_LINE_PATTERN = /^\s*$/du;
+
+/**
+ * @typedef {{ metadata: Record<string, string>, tag_lines: number[] }} PendingTagSet
+ */
+
+/**
+ * @typedef {{
+ *   heading_path: string[];
+ *   lang: string;
+ *   line_start: number;
+ *   metadata: Record<string, string>;
+ *   tag_lines: number[];
+ *   value_lines: string[];
+ * }} OpenTaggedBlock
+ */
+
+/**
+ * @typedef {{ character: string, lang: string, length: number }} OpenFence
+ */
+
+/**
+ * @typedef {{
+ *   blocks: TaggedFencedBlock[];
+ *   body_start: number;
+ *   heading_path: string[];
+ *   open_fence: OpenFence | null;
+ *   open_tagged_block: OpenTaggedBlock | null;
+ *   pending_tag_set: PendingTagSet | null;
+ *   title: string;
+ * }} TaggedBlockScannerState
+ */
+
+/**
+ * @param {TaggedFencedBlocksInput} input
+ * @returns {TaggedFencedBlockFile}
+ */
+export function extractTaggedFencedBlocksFromSource(input) {
+  const lines = input.source_text.split('\n');
+  const state = createScannerState(lines);
+
+  for (const [line_index, line] of lines.entries()) {
+    if (line_index < state.body_start) {
+      continue;
+    }
+
+    scanMarkdownLine(input.file_path, state, line, line_index + 1);
+  }
+
+  finalizeScannerState(input.file_path, state);
+
+  return {
+    blocks: state.blocks,
+    path: input.file_path,
+    title: state.title,
+  };
+}
+
+/**
+ * @param {string} file_path
+ * @param {TaggedBlockScannerState} state
+ * @param {string} line
+ * @param {number} line_number
+ */
+function scanMarkdownLine(file_path, state, line, line_number) {
+  if (state.open_fence) {
+    scanOpenFenceLine(file_path, state, line, line_number);
+    return;
+  }
+
+  if (tryOpenFence(state, line, line_number)) {
+    return;
+  }
+
+  if (state.pending_tag_set) {
+    scanPendingTagSetLine(file_path, state, line, line_number);
+    return;
+  }
+
+  const next_tag_set = parseTaggedMetadataLine(file_path, line, line_number);
+
+  if (next_tag_set) {
+    state.pending_tag_set = next_tag_set;
+    return;
+  }
+
+  const heading = parseHeading(line);
+
+  if (heading) {
+    state.heading_path = updateHeadingPath(
+      state.heading_path,
+      state.title,
+      heading,
+    );
+  }
+}
+
+/**
+ * @param {string} file_path
+ * @param {TaggedBlockScannerState} state
+ * @param {string} line
+ * @param {number} line_number
+ */
+function scanOpenFenceLine(file_path, state, line, line_number) {
+  if (!state.open_fence) {
+    return;
+  }
+
+  if (isClosingMarkdownFence(line, state.open_fence)) {
+    if (state.open_tagged_block) {
+      state.blocks.push(
+        createTaggedBlock(file_path, line_number, state.open_tagged_block),
+      );
+    }
+
+    state.open_fence = null;
+    state.open_tagged_block = null;
+    return;
+  }
+
+  if (state.open_tagged_block) {
+    state.open_tagged_block.value_lines.push(line);
+  }
+}
+
+/**
+ * @param {TaggedBlockScannerState} state
+ * @param {string} line
+ * @param {number} line_number
+ * @returns {boolean}
+ */
+function tryOpenFence(state, line, line_number) {
+  const open_fence = parseOpeningMarkdownFence(line);
+
+  if (!open_fence) {
+    return false;
+  }
+
+  state.open_fence = open_fence;
+  state.open_tagged_block = createOpenTaggedBlock(
+    line_number,
+    open_fence.lang,
+    state.pending_tag_set,
+    state.heading_path,
+  );
+  state.pending_tag_set = null;
+
+  return true;
+}
+
+/**
+ * @param {string} file_path
+ * @param {TaggedBlockScannerState} state
+ * @param {string} line
+ * @param {number} line_number
+ */
+function scanPendingTagSetLine(file_path, state, line, line_number) {
+  if (!state.pending_tag_set) {
+    return;
+  }
+
+  if (BLANK_LINE_PATTERN.test(line)) {
+    return;
+  }
+
+  const next_tag_set = parseTaggedMetadataLine(file_path, line, line_number);
+
+  if (!next_tag_set) {
+    throw createTaggedFencedBlockError(
+      'tagged_fenced_blocks.unattached_tag_set',
+      `Tagged metadata in "${file_path}" at lines ${state.pending_tag_set.tag_lines.join(', ')} must attach directly to the next fenced block.`,
+    );
+  }
+
+  state.pending_tag_set = mergePendingTagSets(
+    file_path,
+    state.pending_tag_set,
+    next_tag_set,
+  );
+}
+
+/**
+ * @param {string[]} lines
+ * @returns {TaggedBlockScannerState}
+ */
+function createScannerState(lines) {
+  const body_start = findMarkdownBodyStartLineIndex(lines);
+  const title = getMarkdownTitle(lines, body_start);
+
+  return {
+    blocks: [],
+    body_start,
+    heading_path: title.length > 0 ? [title] : [],
+    open_fence: null,
+    open_tagged_block: null,
+    pending_tag_set: null,
+    title,
+  };
+}
+
+/**
+ * @param {string} file_path
+ * @param {TaggedBlockScannerState} state
+ */
+function finalizeScannerState(file_path, state) {
+  if (state.open_tagged_block) {
+    throw createTaggedFencedBlockError(
+      'tagged_fenced_blocks.unclosed_fence',
+      `Unclosed tagged fenced block in "${file_path}" starting at line ${state.open_tagged_block.line_start}.`,
+    );
+  }
+
+  if (state.pending_tag_set) {
+    throw createTaggedFencedBlockError(
+      'tagged_fenced_blocks.dangling_tag_set',
+      `Dangling tagged metadata in "${file_path}" at lines ${state.pending_tag_set.tag_lines.join(', ')}.`,
+    );
+  }
+}
+
+/**
+ * @param {number} line_number
+ * @param {string} lang
+ * @param {PendingTagSet | null} pending_tag_set
+ * @param {string[]} heading_path
+ * @returns {OpenTaggedBlock | null}
+ */
+function createOpenTaggedBlock(
+  line_number,
+  lang,
+  pending_tag_set,
+  heading_path,
+) {
+  if (!pending_tag_set) {
+    return null;
+  }
+
+  return {
+    heading_path: [...heading_path],
+    lang,
+    line_start: line_number,
+    metadata: { ...pending_tag_set.metadata },
+    tag_lines: [...pending_tag_set.tag_lines],
+    value_lines: [],
+  };
+}
+
+/**
+ * @param {string} file_path
+ * @param {number} line_end
+ * @param {OpenTaggedBlock} open_tagged_block
+ * @returns {TaggedFencedBlock}
+ */
+function createTaggedBlock(file_path, line_end, open_tagged_block) {
+  return {
+    context: {
+      heading_path: [...open_tagged_block.heading_path],
+    },
+    id: `block:${file_path}:${open_tagged_block.line_start}`,
+    lang: open_tagged_block.lang,
+    metadata: { ...open_tagged_block.metadata },
+    origin: {
+      line_end,
+      line_start: open_tagged_block.line_start,
+      path: file_path,
+      tag_lines: [...open_tagged_block.tag_lines],
+    },
+    value: open_tagged_block.value_lines.join('\n'),
+  };
+}

package/lib/tagged-fenced-blocks.js

@@ -0,0 +1,100 @@
+/**
+ * @import {
+ *   TaggedFencedBlock,
+ *   TaggedFencedBlockCriteria,
+ *   TaggedFencedBlockFile,
+ *   TaggedFencedBlocksInput,
+ * } from './tagged-fenced-blocks.types.ts';
+ */
+
+import { readFile } from 'node:fs/promises';
+
+import { createTaggedFencedBlockError } from './tagged-fenced-block-error.js';
+import { extractTaggedFencedBlocksFromSource } from './tagged-fenced-block-parser.js';
+
+/**
+ * Tagged fenced block public API.
+ *
+ * Loads or extracts one markdown file worth of tagged fenced blocks and
+ * provides exact-match selection helpers.
+ *
+ * Kind: parse
+ * Status: active
+ * Tracked in: ../docs/plans/v0/tagged-fenced-block-extraction.md
+ * Decided by: ../docs/decisions/tagged-fenced-block-extraction.md
+ * @patram
+ * @see {@link ../docs/decisions/tagged-fenced-block-extraction.md}
+ */
+
+/**
+ * @param {TaggedFencedBlocksInput} input
+ * @returns {TaggedFencedBlockFile}
+ */
+export function extractTaggedFencedBlocks(input) {
+  return extractTaggedFencedBlocksFromSource(input);
+}
+
+/**
+ * @param {string} file_path
+ * @returns {Promise<TaggedFencedBlockFile>}
+ */
+export async function loadTaggedFencedBlocks(file_path) {
+  const source_text = await readFile(file_path, 'utf8');
+
+  return extractTaggedFencedBlocks({
+    file_path,
+    source_text,
+  });
+}
+
+/**
+ * @param {TaggedFencedBlock[]} blocks
+ * @param {TaggedFencedBlockCriteria} criteria
+ * @returns {TaggedFencedBlock[]}
+ */
+export function selectTaggedBlocks(blocks, criteria) {
+  const criteria_entries = Object.entries(criteria);
+
+  return blocks.filter((block) =>
+    criteria_entries.every(
+      ([key, value]) =>
+        block.metadata[key] !== undefined && block.metadata[key] === value,
+    ),
+  );
+}
+
+/**
+ * @param {TaggedFencedBlock[]} blocks
+ * @param {TaggedFencedBlockCriteria} criteria
+ * @returns {TaggedFencedBlock}
+ */
+export function selectTaggedBlock(blocks, criteria) {
+  const matches = selectTaggedBlocks(blocks, criteria);
+
+  if (matches.length === 1) {
+    return matches[0];
+  }
+
+  if (matches.length === 0) {
+    throw createTaggedFencedBlockError(
+      'tagged_fenced_blocks.not_found',
+      `No tagged fenced block matches ${formatSelectionCriteria(criteria)}.`,
+    );
+  }
+
+  throw createTaggedFencedBlockError(
+    'tagged_fenced_blocks.not_unique',
+    `Multiple tagged fenced blocks match ${formatSelectionCriteria(criteria)}.`,
+  );
+}
+
+/**
+ * @param {TaggedFencedBlockCriteria} criteria
+ * @returns {string}
+ */
+function formatSelectionCriteria(criteria) {
+  return Object.entries(criteria)
+    .sort(([left_key], [right_key]) => left_key.localeCompare(right_key))
+    .map(([key, value]) => `${key}=${value}`)
+    .join(', ');
+}

package/lib/tagged-fenced-blocks.types.ts

@@ -0,0 +1,38 @@
+export interface TaggedFencedBlocksInput {
+  file_path: string;
+  source_text: string;
+}
+
+export interface TaggedFencedBlockCriteria {
+  [key: string]: string;
+}
+
+export interface TaggedFencedBlockOrigin {
+  path: string;
+  line_start: number;
+  line_end: number;
+  tag_lines: number[];
+}
+
+export interface TaggedFencedBlockContext {
+  heading_path: string[];
+}
+
+export interface TaggedFencedBlock {
+  id: string;
+  lang: string;
+  value: string;
+  metadata: Record<string, string>;
+  origin: TaggedFencedBlockOrigin;
+  context: TaggedFencedBlockContext;
+}
+
+export interface TaggedFencedBlockFile {
+  path: string;
+  title: string;
+  blocks: TaggedFencedBlock[];
+}
+
+export interface TaggedFencedBlockError extends Error {
+  code: string;
+}