patram 0.1.1 → 0.2.0

package/lib/render-plain-output.js

@@ -2,6 +2,12 @@
  * @import { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView, QueryOutputView, ShowOutputView } from './output-view.types.ts';
  */
 
+import {
+  formatOutputNodeMetadataRows,
+  formatResolvedLinkMetadataRows,
+} from './format-output-metadata.js';
+import { formatNodeHeader } from './format-node-header.js';
+import { formatOutputItemBlock } from './format-output-item-block.js';
 import { layoutStoredQueries } from './layout-stored-queries.js';
 
 /**
@@ -76,12 +82,24 @@ function renderPlainStoredQueries(output_items) {
  */
 function renderPlainShowOutput(output_view) {
   const rendered_source = trimTrailingLineBreaks(output_view.rendered_source);
+  const document_summary = output_view.document
+    ? formatPlainNodeItem(output_view.document)
+    : '';
 
-  if (output_view.items.length === 0) {
+  if (document_summary.length === 0 && output_view.items.length === 0) {
     return `${rendered_source}\n`;
   }
 
-  return `${rendered_source}\n\n----------------\n${output_view.items.map(formatPlainResolvedLinkItem).join('\n\n')}\n`;
+  /** @type {string[]} */
+  const summary_items = [];
+
+  if (document_summary.length > 0) {
+    summary_items.push(document_summary);
+  }
+
+  summary_items.push(...output_view.items.map(formatPlainResolvedLinkItem));
+
+  return `${rendered_source}\n\n----------------\n${summary_items.join('\n\n')}\n`;
 }
 
 /**
@@ -89,17 +107,11 @@ function renderPlainShowOutput(output_view) {
  * @returns {string}
  */
 function formatPlainNodeItem(output_item) {
-  const metadata_row = formatMetadataRow(output_item);
-  /** @type {string[]} */
-  const lines = [formatNodeHeader(output_item)];
-
-  if (metadata_row.length > 0) {
-    lines.push(metadata_row);
-  }
-
-  lines.push('', `    ${output_item.title}`);
-
-  return lines.join('\n');
+  return formatOutputItemBlock({
+    header: formatNodeHeader(output_item),
+    metadata_rows: formatOutputNodeMetadataRows(output_item),
+    title: output_item.title,
+  });
 }
 
 /**
@@ -115,79 +127,12 @@ function formatPlainStoredQueryLine(line_segments) {
  * @returns {string}
  */
 function formatPlainResolvedLinkItem(output_item) {
-  const metadata_row = formatResolvedLinkMetadataRow(output_item.target);
-  /** @type {string[]} */
-  const lines = [
-    `[${output_item.reference}] document ${output_item.target.path}`,
-  ];
-
-  if (metadata_row.length > 0) {
-    lines.push(`    ${metadata_row}`);
-  }
-
-  lines.push('', `    ${output_item.target.title}`);
-
-  return lines.join('\n');
-}
-
-/**
- * @param {OutputNodeItem} output_item
- * @returns {string}
- */
-function formatMetadataRow(output_item) {
-  /** @type {string[]} */
-  const metadata_fields = [];
-
-  if (isDocumentNode(output_item)) {
-    metadata_fields.push(`kind: ${output_item.node_kind}`);
-  } else {
-    metadata_fields.push(`path: ${output_item.path}`);
-  }
-
-  if (output_item.status) {
-    metadata_fields.push(`status: ${output_item.status}`);
-  }
-
-  return metadata_fields.join('  ');
-}
-
-/**
- * @param {OutputNodeItem} output_item
- * @returns {string}
- */
-function formatNodeHeader(output_item) {
-  if (isDocumentNode(output_item)) {
-    return `document ${output_item.path}`;
-  }
-
-  return `${output_item.node_kind} ${output_item.id}`;
-}
-
-/**
- * @param {OutputNodeItem} output_item
- * @returns {boolean}
- */
-function isDocumentNode(output_item) {
-  return output_item.id === `doc:${output_item.path}`;
-}
-
-/**
- * @param {{ kind?: string, status?: string }} target
- * @returns {string}
- */
-function formatResolvedLinkMetadataRow(target) {
-  /** @type {string[]} */
-  const metadata_fields = [];
-
-  if (target.kind) {
-    metadata_fields.push(`kind: ${target.kind}`);
-  }
-
-  if (target.status) {
-    metadata_fields.push(`status: ${target.status}`);
-  }
-
-  return metadata_fields.join('  ');
+  return formatOutputItemBlock({
+    header: `[${output_item.reference}] document ${output_item.target.path}`,
+    metadata_rows: formatResolvedLinkMetadataRows(output_item.target),
+    metadata_indent: '    ',
+    title: output_item.target.title,
+  });
 }
 
 /**

package/lib/render-rich-output.js

@@ -5,6 +5,12 @@
 
 import { Ansis } from 'ansis';
 
+import {
+  formatOutputNodeMetadataRows,
+  formatResolvedLinkMetadataRows,
+} from './format-output-metadata.js';
+import { formatNodeHeader } from './format-node-header.js';
+import { formatOutputItemBlock } from './format-output-item-block.js';
 import { layoutStoredQueries } from './layout-stored-queries.js';
 import { renderRichSource } from './render-rich-source.js';
 
@@ -96,12 +102,26 @@ async function renderRichShowOutput(output_view, render_options, ansi) {
   const rendered_source = trimTrailingLineBreaks(
     await renderRichSource(output_view, render_options),
   );
+  const document_summary = output_view.document
+    ? formatRichNodeItem(output_view.document, ansi)
+    : '';
 
-  if (output_view.items.length === 0) {
+  if (document_summary.length === 0 && output_view.items.length === 0) {
     return `${rendered_source}\n`;
   }
 
-  return `${rendered_source}\n\n${ansi.gray(FULL_WIDTH_DIVIDER)}\n\n${output_view.items.map((item) => formatRichResolvedLinkItem(item, ansi)).join('\n\n')}\n`;
+  /** @type {string[]} */
+  const summary_items = [];
+
+  if (document_summary.length > 0) {
+    summary_items.push(document_summary);
+  }
+
+  summary_items.push(
+    ...output_view.items.map((item) => formatRichResolvedLinkItem(item, ansi)),
+  );
+
+  return `${rendered_source}\n\n${ansi.gray(FULL_WIDTH_DIVIDER)}\n\n${summary_items.join('\n\n')}\n`;
 }
 
 /**
@@ -110,17 +130,11 @@ async function renderRichShowOutput(output_view, render_options, ansi) {
  * @returns {string}
  */
 function formatRichNodeItem(output_item, ansi) {
-  const metadata_row = formatRichMetadataRow(output_item);
-  /** @type {string[]} */
-  const lines = [ansi.green(formatNodeHeader(output_item))];
-
-  if (metadata_row.length > 0) {
-    lines.push(metadata_row);
-  }
-
-  lines.push('', `    ${output_item.title}`);
-
-  return lines.join('\n');
+  return formatOutputItemBlock({
+    header: ansi.green(formatNodeHeader(output_item)),
+    metadata_rows: formatOutputNodeMetadataRows(output_item),
+    title: output_item.title,
+  });
 }
 
 /**
@@ -140,59 +154,12 @@ function formatRichStoredQueryLine(line_segments, ansi) {
  * @returns {string}
  */
 function formatRichResolvedLinkItem(output_item, ansi) {
-  const metadata_row = formatRichResolvedLinkMetadataRow(output_item.target);
-  /** @type {string[]} */
-  const lines = [
-    `${ansi.gray(`[${output_item.reference}]`)} ${ansi.green(`document ${output_item.target.path}`)}`,
-  ];
-
-  if (metadata_row.length > 0) {
-    lines.push(`    ${metadata_row}`);
-  }
-
-  lines.push('', `    ${output_item.target.title}`);
-
-  return lines.join('\n');
-}
-
-/**
- * @param {OutputNodeItem} output_item
- * @returns {string}
- */
-function formatRichMetadataRow(output_item) {
-  /** @type {string[]} */
-  const metadata_fields = [];
-
-  if (isDocumentNode(output_item)) {
-    metadata_fields.push(`kind: ${output_item.node_kind}`);
-  } else {
-    metadata_fields.push(`path: ${output_item.path}`);
-  }
-
-  if (output_item.status) {
-    metadata_fields.push(`status: ${output_item.status}`);
-  }
-
-  return metadata_fields.join('  ');
-}
-
-/**
- * @param {{ kind?: string, status?: string }} target
- * @returns {string}
- */
-function formatRichResolvedLinkMetadataRow(target) {
-  /** @type {string[]} */
-  const metadata_fields = [];
-
-  if (target.kind) {
-    metadata_fields.push(`kind: ${target.kind}`);
-  }
-
-  if (target.status) {
-    metadata_fields.push(`status: ${target.status}`);
-  }
-
-  return metadata_fields.join('  ');
+  return formatOutputItemBlock({
+    header: `${ansi.gray(`[${output_item.reference}]`)} ${ansi.green(`document ${output_item.target.path}`)}`,
+    metadata_rows: formatResolvedLinkMetadataRows(output_item.target),
+    metadata_indent: '    ',
+    title: output_item.target.title,
+  });
 }
 
 /**
@@ -218,32 +185,12 @@ function styleStoredQuerySegment(line_segment, ansi) {
   }
 
   if (line_segment.kind === 'keyword') {
-    return ansi.yellow(line_segment.text);
+    return ansi.gray(line_segment.text);
   }
 
   return line_segment.text;
 }
 
-/**
- * @param {OutputNodeItem} output_item
- * @returns {string}
- */
-function formatNodeHeader(output_item) {
-  if (isDocumentNode(output_item)) {
-    return `document ${output_item.path}`;
-  }
-
-  return `${output_item.node_kind} ${output_item.id}`;
-}
-
-/**
- * @param {OutputNodeItem} output_item
- * @returns {boolean}
- */
-function isDocumentNode(output_item) {
-  return output_item.id === `doc:${output_item.path}`;
-}
-
 /**
  * @param {string} value
  * @returns {string}

package/lib/resolve-where-clause.js

@@ -2,12 +2,16 @@
  * @import { PatramRepoConfig } from './load-patram-config.types.ts';
  */
 
+/**
+ * @typedef {{ kind: 'ad_hoc' } | { kind: 'stored_query', name: string }} QuerySource
+ */
+
 /**
  * Resolve an ad hoc or stored query into a where clause.
  *
  * @param {PatramRepoConfig} repo_config
  * @param {string[]} command_arguments
- * @returns {{ success: true, value: string } | { success: false, message: string }}
+ * @returns {{ success: true, value: { query_source: QuerySource, where_clause: string } } | { success: false, message: string }}
  */
 export function resolveWhereClause(repo_config, command_arguments) {
   if (command_arguments[0] === '--where') {
@@ -22,7 +26,12 @@ export function resolveWhereClause(repo_config, command_arguments) {
 
     return {
       success: true,
-      value: where_clause,
+      value: {
+        query_source: {
+          kind: 'ad_hoc',
+        },
+        where_clause,
+      },
     };
   }
 
@@ -46,6 +55,12 @@ export function resolveWhereClause(repo_config, command_arguments) {
 
   return {
     success: true,
-    value: stored_query.where,
+    value: {
+      query_source: {
+        kind: 'stored_query',
+        name: stored_query_name,
+      },
+      where_clause: stored_query.where,
+    },
   };
 }

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;
+}