patram 0.3.0 → 0.4.0

package/lib/render-rich-source.js

@@ -46,6 +46,16 @@ const SHIKI_LANGUAGE_NAMES = new Set([
   ...Object.keys(bundledLanguagesAlias),
 ]);
 
+/**
+ * @typedef {{
+ *   ansi: Ansis,
+ *   next_reference: number,
+ *   next_top_level_list: number,
+ *   resolved_links: OutputResolvedLinkItem[],
+ *   top_level_list_item_gaps: boolean[][]
+ * }} RichSourceRenderState
+ */
+
 /**
  * @param {ShowOutputView} output_view
  * @param {{ color_mode: CliColorMode, color_enabled: boolean }} render_options
@@ -70,11 +80,13 @@ async function renderRichMarkdownSource(output_view, ansi) {
   const markdown_tree = parseAST(output_view.source);
   /** @type {string[]} */
   const rendered_blocks = [];
-  /** @type {{ ansi: Ansis, next_reference: number, resolved_links: OutputResolvedLinkItem[] }} */
+  /** @type {RichSourceRenderState} */
   const render_state = {
     ansi,
     next_reference: 1,
+    next_top_level_list: 0,
     resolved_links: output_view.items,
+    top_level_list_item_gaps: collectTopLevelListItemGaps(output_view.source),
   };
 
   for (const node of markdown_tree.nodes) {
@@ -107,7 +119,7 @@ async function renderRichSourceFile(source_path, source_text, ansi) {
 
 /**
  * @param {ComarkNode} node
- * @param {{ ansi: Ansis, next_reference: number, resolved_links: OutputResolvedLinkItem[] }} render_state
+ * @param {RichSourceRenderState} render_state
  * @param {number} indent_level
  * @returns {Promise<string>}
  */
@@ -131,8 +143,14 @@ async function renderBlockNode(node, render_state, indent_level) {
     return renderFencedCodeBlock(node, indent_level, render_state.ansi);
   }
 
-  if (node_tag === 'ul' || node_tag === 'ol') {
-    return renderListBlock(node_tag, node_children, render_state, indent_level);
+  if (isListTag(node_tag)) {
+    return renderListBlock(
+      /** @type {'ol' | 'ul'} */ (node_tag),
+      node_children,
+      render_state,
+      indent_level,
+      indent_level === 0 ? getNextTopLevelListItemGaps(render_state) : [],
+    );
   }
 
   if (node_tag === 'blockquote') {
@@ -152,7 +170,7 @@ async function renderBlockNode(node, render_state, indent_level) {
 
 /**
  * @param {ComarkNode[]} nodes
- * @param {{ ansi: Ansis, next_reference: number, resolved_links: OutputResolvedLinkItem[] }} render_state
+ * @param {RichSourceRenderState} render_state
  * @returns {string}
  */
 function renderInlineNodes(nodes, render_state) {
@@ -217,13 +235,23 @@ function renderInlineNodes(nodes, render_state) {
 /**
  * @param {'ol' | 'ul'} nodes_type
  * @param {ComarkNode[]} nodes
- * @param {{ ansi: Ansis, next_reference: number, resolved_links: OutputResolvedLinkItem[] }} render_state
+ * @param {RichSourceRenderState} render_state
  * @param {number} indent_level
+ * @param {boolean[]} list_item_gaps
  * @returns {Promise<string>}
  */
-async function renderListBlock(nodes_type, nodes, render_state, indent_level) {
+async function renderListBlock(
+  nodes_type,
+  nodes,
+  render_state,
+  indent_level,
+  list_item_gaps,
+) {
   /** @type {string[]} */
   const rendered_items = [];
+  /** @type {ComarkElement | null} */
+  let previous_item = null;
+  let rendered_item_count = 0;
 
   for (let item_index = 0; item_index < nodes.length; item_index += 1) {
     const node = nodes[item_index];
@@ -232,6 +260,17 @@ async function renderListBlock(nodes_type, nodes, render_state, indent_level) {
       continue;
     }
 
+    if (
+      previous_item &&
+      shouldRenderListItemGap(
+        previous_item,
+        node,
+        list_item_gaps[rendered_item_count - 1] ?? false,
+      )
+    ) {
+      rendered_items.push('');
+    }
+
     rendered_items.push(
       await renderListItem(
         node,
@@ -241,6 +280,8 @@ async function renderListBlock(nodes_type, nodes, render_state, indent_level) {
         indent_level,
       ),
     );
+    previous_item = node;
+    rendered_item_count += 1;
   }
 
   return rendered_items.join('\n');
@@ -250,7 +291,7 @@ async function renderListBlock(nodes_type, nodes, render_state, indent_level) {
  * @param {ComarkElement} node
  * @param {number} item_number
  * @param {boolean} is_ordered
- * @param {{ ansi: Ansis, next_reference: number, resolved_links: OutputResolvedLinkItem[] }} render_state
+ * @param {RichSourceRenderState} render_state
  * @param {number} indent_level
  * @returns {Promise<string>}
  */
@@ -298,7 +339,7 @@ async function renderListItem(
 
 /**
  * @param {ComarkNode[]} nodes
- * @param {{ ansi: Ansis, next_reference: number, resolved_links: OutputResolvedLinkItem[] }} render_state
+ * @param {RichSourceRenderState} render_state
  * @param {number} indent_level
  * @returns {Promise<string>}
  */
@@ -461,7 +502,7 @@ function renderHeading(tag_name, nodes, ansi) {
 
 /**
  * @param {ComarkElement} node
- * @param {{ ansi: Ansis, next_reference: number, resolved_links: OutputResolvedLinkItem[] }} render_state
+ * @param {RichSourceRenderState} render_state
  * @returns {string}
  */
 function renderLinkNode(node, render_state) {
@@ -618,7 +659,11 @@ function renderCodeBlock(
   content_indent = 0,
 ) {
   const label = formatCodeBlockLabel(language_label, file_name);
-  const content_width = measureCodeBlockWidth(label, source_lines);
+  const content_width = measureCodeBlockWidth(
+    label,
+    source_lines,
+    content_indent,
+  );
   /** @type {string[]} */
   const rendered_lines = [];
 
@@ -777,7 +822,7 @@ function extractTableRowCells(row_node) {
 
 /**
  * @param {ComarkElement} node
- * @param {{ ansi: Ansis, next_reference: number, resolved_links: OutputResolvedLinkItem[] }} render_state
+ * @param {RichSourceRenderState} render_state
  * @returns {{ block_nodes: ComarkElement[], lead_text: string | null }}
  */
 function collectListItemParts(node, render_state) {
@@ -836,6 +881,183 @@ function collectListItemParts(node, render_state) {
   };
 }
 
+/**
+ * @param {{ next_top_level_list: number, top_level_list_item_gaps: boolean[][] }} render_state
+ * @returns {boolean[]}
+ */
+function getNextTopLevelListItemGaps(render_state) {
+  const list_item_gaps =
+    render_state.top_level_list_item_gaps[render_state.next_top_level_list];
+
+  render_state.next_top_level_list += 1;
+
+  return list_item_gaps ?? [];
+}
+
+/**
+ * @param {string} source_text
+ * @returns {boolean[][]}
+ */
+function collectTopLevelListItemGaps(source_text) {
+  const source_lines = source_text.split('\n');
+  /** @type {boolean[][]} */
+  const top_level_list_item_gaps = [];
+  /** @type {boolean[] | null} */
+  let current_list_item_gaps = null;
+  let saw_blank_line = false;
+  /** @type {{ character: '`' | '~', length: number } | null} */
+  let active_fence = null;
+
+  for (const source_line of source_lines) {
+    if (active_fence) {
+      if (isClosingTopLevelFenceLine(source_line, active_fence)) {
+        active_fence = null;
+      }
+
+      continue;
+    }
+
+    const top_level_fence = parseTopLevelFence(source_line);
+
+    if (top_level_fence) {
+      active_fence = top_level_fence;
+      current_list_item_gaps = null;
+      saw_blank_line = false;
+      continue;
+    }
+
+    if (source_line.trim().length === 0) {
+      saw_blank_line = current_list_item_gaps !== null;
+      continue;
+    }
+
+    if (isTopLevelListItemLine(source_line)) {
+      current_list_item_gaps = pushTopLevelListItemGap(
+        current_list_item_gaps,
+        top_level_list_item_gaps,
+        saw_blank_line,
+      );
+      saw_blank_line = false;
+      continue;
+    }
+
+    if (current_list_item_gaps === null) {
+      continue;
+    }
+
+    if (source_line.startsWith(' ') || source_line.startsWith('\t')) {
+      saw_blank_line = false;
+      continue;
+    }
+
+    current_list_item_gaps = null;
+    saw_blank_line = false;
+  }
+
+  return top_level_list_item_gaps;
+}
+
+/**
+ * @param {ComarkElement} previous_item
+ * @param {ComarkElement} next_item
+ * @param {boolean} has_blank_line_gap
+ * @returns {boolean}
+ */
+function shouldRenderListItemGap(previous_item, next_item, has_blank_line_gap) {
+  if (!has_blank_line_gap) {
+    return false;
+  }
+
+  return (
+    isSimpleTopLevelListItem(previous_item) &&
+    isSimpleTopLevelListItem(next_item)
+  );
+}
+
+/**
+ * @param {ComarkElement} item_node
+ * @returns {boolean}
+ */
+function isSimpleTopLevelListItem(item_node) {
+  const item_children = getElementChildren(item_node);
+
+  if (item_children.length !== 1) {
+    return false;
+  }
+
+  const paragraph_node = item_children[0];
+
+  if (
+    typeof paragraph_node === 'string' ||
+    getElementTag(paragraph_node) !== 'p'
+  ) {
+    return false;
+  }
+
+  return !extractInlineText(getElementChildren(paragraph_node)).includes('\n');
+}
+
+/**
+ * @param {string} source_line
+ * @returns {boolean}
+ */
+function isTopLevelListItemLine(source_line) {
+  return /^([*+-]|\d+[.)])(?:\s+|$)/du.test(source_line);
+}
+
+/**
+ * @param {string} source_line
+ * @returns {{ character: '`' | '~', length: number } | null}
+ */
+function parseTopLevelFence(source_line) {
+  const fence_match = /^(?<character>`|~)\k<character>{2,}/du.exec(source_line);
+
+  if (!fence_match?.groups?.character) {
+    return null;
+  }
+
+  return {
+    character: /** @type {'`' | '~'} */ (fence_match.groups.character),
+    length: fence_match[0].length,
+  };
+}
+
+/**
+ * @param {string} source_line
+ * @param {{ character: '`' | '~', length: number }} active_fence
+ * @returns {boolean}
+ */
+function isClosingTopLevelFenceLine(source_line, active_fence) {
+  const closing_pattern = new RegExp(
+    `^${active_fence.character}{${active_fence.length},}\\s*$`,
+    'u',
+  );
+
+  return closing_pattern.test(source_line);
+}
+
+/**
+ * @param {boolean[] | null} current_list_item_gaps
+ * @param {boolean[][]} top_level_list_item_gaps
+ * @param {boolean} saw_blank_line
+ * @returns {boolean[]}
+ */
+function pushTopLevelListItemGap(
+  current_list_item_gaps,
+  top_level_list_item_gaps,
+  saw_blank_line,
+) {
+  if (current_list_item_gaps === null) {
+    current_list_item_gaps = [];
+    top_level_list_item_gaps.push(current_list_item_gaps);
+    return current_list_item_gaps;
+  }
+
+  current_list_item_gaps.push(saw_blank_line);
+
+  return current_list_item_gaps;
+}
+
 /**
  * @param {string} text
  * @param {string} item_prefix
@@ -1001,6 +1223,14 @@ function isHeadingTag(tag_name) {
   return /^h[1-6]$/du.test(tag_name);
 }
 
+/**
+ * @param {string} tag_name
+ * @returns {boolean}
+ */
+function isListTag(tag_name) {
+  return tag_name === 'ol' || tag_name === 'ul';
+}
+
 /**
  * @param {string} tag_name
  * @returns {number}
@@ -1136,13 +1366,14 @@ function renderCodeBlockLine(
 /**
  * @param {string} label
  * @param {string[]} source_lines
+ * @param {number} content_indent
  * @returns {number}
  */
-function measureCodeBlockWidth(label, source_lines) {
+function measureCodeBlockWidth(label, source_lines, content_indent = 0) {
   return Math.max(
     BLOCK_WIDTH - 2,
     stringWidth(label),
-    measureMaxLineWidth(source_lines),
+    measureMaxLineWidth(source_lines) + content_indent,
   );
 }
 

package/lib/show-document.js

@@ -8,6 +8,7 @@
 import { readFile } from 'node:fs/promises';
 import { posix, relative, resolve } from 'node:path';
 
+import { resolveDocumentNodeId } from './build-graph-identity.js';
 import { parseSourceFile } from './parse-claims.js';
 
 /**
@@ -92,6 +93,7 @@ export async function loadShowOutput(
       source_file_path,
       source_text,
       parse_result.claims,
+      graph.document_node_ids,
       graph.nodes,
     ),
   };
@@ -101,10 +103,17 @@ export async function loadShowOutput(
  * @param {string} source_file_path
  * @param {string} source_text
  * @param {PatramClaim[]} claims
+ * @param {import('./build-graph.types.ts').BuildGraphResult['document_node_ids']} document_node_ids
  * @param {Record<string, GraphNode>} graph_nodes
  * @returns {{ path: string, rendered_source: string, resolved_links: Array<{ label: string, reference: number, target: { kind?: string, path: string, status?: string, title: string } }>, source: string }}
  */
-function createShowOutput(source_file_path, source_text, claims, graph_nodes) {
+function createShowOutput(
+  source_file_path,
+  source_text,
+  claims,
+  document_node_ids,
+  graph_nodes,
+) {
   const link_claims = claims.filter(isResolvedLinkClaim);
   const rendered_link_claims = link_claims.filter(isMarkdownLinkClaim);
   const resolved_links = link_claims.map((claim, claim_index) =>
@@ -112,6 +121,7 @@ function createShowOutput(source_file_path, source_text, claims, graph_nodes) {
       source_file_path,
       claim,
       claim_index + 1,
+      document_node_ids,
       graph_nodes,
     ),
   );
@@ -197,6 +207,7 @@ function renderResolvedSourceLine(
  * @param {string} source_file_path
  * @param {PatramClaim} claim
  * @param {number} reference
+ * @param {import('./build-graph.types.ts').BuildGraphResult['document_node_ids']} document_node_ids
  * @param {Record<string, GraphNode>} graph_nodes
  * @returns {{ label: string, reference: number, target: { kind?: string, path: string, status?: string, title: string } }}
  */
@@ -204,6 +215,7 @@ function createResolvedLinkSummary(
   source_file_path,
   claim,
   reference,
+  document_node_ids,
   graph_nodes,
 ) {
   const claim_value = getLinkClaimValue(claim);
@@ -211,7 +223,8 @@ function createResolvedLinkSummary(
     source_file_path,
     claim_value.target,
   );
-  const target_node = graph_nodes[`doc:${target_path}`];
+  const target_node =
+    graph_nodes[resolveDocumentNodeId(document_node_ids, target_path)];
 
   return {
     label: claim_value.text,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patram",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "./lib/patram.js",
   "exports": {