patram 0.3.0 → 0.5.0

package/lib/render-field-discovery.js

@@ -5,6 +5,8 @@
 
 import { Ansis } from 'ansis';
 
+const MAX_TEXT_EVIDENCE_ROWS = 5;
+
 /**
  * Render field discovery output.
  *
@@ -109,21 +111,21 @@ function formatTextFieldSuggestion(field_suggestion, render_options) {
   );
 
   if (field_suggestion.evidence_references.length > 0) {
-    lines.push(render_options.label('  evidence:'));
     lines.push(
-      ...field_suggestion.evidence_references.map(
-        (evidence_reference) =>
-          `${render_options.label('    ')}${formatEvidenceReference(evidence_reference)}`,
+      ...formatTextEvidenceSection(
+        '  evidence:',
+        field_suggestion.evidence_references,
+        render_options,
       ),
     );
   }
 
   if (field_suggestion.conflicting_evidence.length > 0) {
-    lines.push(render_options.label('  conflicting evidence:'));
     lines.push(
-      ...field_suggestion.conflicting_evidence.map(
-        (evidence_reference) =>
-          `${render_options.label('    ')}${formatEvidenceReference(evidence_reference)}`,
+      ...formatTextEvidenceSection(
+        '  conflicting evidence:',
+        field_suggestion.conflicting_evidence,
+        render_options,
       ),
     );
   }
@@ -131,6 +133,40 @@ function formatTextFieldSuggestion(field_suggestion, render_options) {
   return lines;
 }
 
+/**
+ * @param {string} section_title
+ * @param {import('./discover-fields.types.ts').FieldDiscoveryEvidenceReference[]} evidence_references
+ * @param {{ header: (value: string) => string, label: (value: string) => string }} render_options
+ * @returns {string[]}
+ */
+function formatTextEvidenceSection(
+  section_title,
+  evidence_references,
+  render_options,
+) {
+  /** @type {string[]} */
+  const lines = [render_options.label(section_title)];
+  const visible_evidence_references = evidence_references.slice(
+    0,
+    MAX_TEXT_EVIDENCE_ROWS,
+  );
+
+  lines.push(
+    ...visible_evidence_references.map(
+      (evidence_reference) =>
+        `${render_options.label('    ')}${formatEvidenceReference(evidence_reference)}`,
+    ),
+  );
+
+  if (evidence_references.length > MAX_TEXT_EVIDENCE_ROWS) {
+    const remaining_count = evidence_references.length - MAX_TEXT_EVIDENCE_ROWS;
+
+    lines.push(render_options.label(`    ${remaining_count} more ...`));
+  }
+
+  return lines;
+}
+
 /**
  * @param {import('./discover-fields.types.ts').FieldDiscoveryEvidenceReference} evidence_reference
  * @returns {string}

package/lib/render-output-view.js

@@ -1,16 +1,16 @@
-/** @import * as $k$$l$output$j$view$k$types$k$ts from './output-view.types.ts'; */
-/* eslint-disable max-lines */
 /**
  * @import { BuildGraphResult, GraphNode } from './build-graph.types.ts';
  * @import { DerivedSummaryEvaluator } from './derived-summary.js';
  * @import { PatramRepoConfig } from './load-patram-config.types.ts';
  * @import { ParsedCliArguments } from './parse-cli-arguments.types.ts';
- * @import { OutputMetadataField, OutputStoredQueryItem, OutputView, ResolvedOutputMode, ShowOutputView } from './output-view.types.ts';
+ * @import { OutputDerivedSummary, OutputMetadataField, OutputNodeItem, OutputResolvedLinkItem, OutputResolvedLinkTarget, OutputStoredQueryItem, OutputView, ResolvedOutputMode, ShowOutputView } from './output-view.types.ts';
  */
+/* eslint-disable max-lines */
 
 import { renderJsonOutput } from './render-json-output.js';
 import { renderPlainOutput } from './render-plain-output.js';
 import { renderRichOutput } from './render-rich-output.js';
+import { resolveDocumentNodeId } from './build-graph-identity.js';
 
 /**
  * Shared command output views.
@@ -56,12 +56,15 @@ export function createOutputView(command_name, command_items, command_options) {
  * Create a shared output view for the show command.
  *
  * @param {{ path: string, rendered_source: string, resolved_links: Array<{ label: string, reference: number, target: { kind?: string, path: string, status?: string, title: string } }>, source: string }} show_output
- * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, graph_nodes?: BuildGraphResult['nodes'], repo_config?: PatramRepoConfig }=} command_options
+ * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, document_node_ids?: BuildGraphResult['document_node_ids'], graph_nodes?: BuildGraphResult['nodes'], repo_config?: PatramRepoConfig }=} command_options
  * @returns {ShowOutputView}
  */
 export function createShowOutputView(show_output, command_options = {}) {
-  const shown_document_node =
-    command_options.graph_nodes?.[`doc:${show_output.path}`];
+  const shown_document_node = resolveDocumentGraphNode(
+    command_options.graph_nodes,
+    command_options.document_node_ids,
+    show_output.path,
+  );
 
   return {
     command: 'show',
@@ -75,20 +78,9 @@ export function createShowOutputView(show_output, command_options = {}) {
         )
       : undefined,
     hints: [],
-    items: show_output.resolved_links.map((resolved_link) => ({
-      kind: 'resolved_link',
-      label: resolved_link.label,
-      reference: resolved_link.reference,
-      target: createResolvedLinkTarget(
-        resolved_link.target,
-        command_options.repo_config?.fields ?? {},
-        command_options.graph_nodes?.[`doc:${resolved_link.target.path}`]
-          ? (command_options.derived_summary_evaluator?.evaluate(
-              command_options.graph_nodes[`doc:${resolved_link.target.path}`],
-            ) ?? null)
-          : null,
-      ),
-    })),
+    items: show_output.resolved_links.map((resolved_link) =>
+      createResolvedLinkOutputItem(resolved_link, command_options),
+    ),
     path: show_output.path,
     rendered_source: show_output.rendered_source,
     source: show_output.source,
@@ -178,9 +170,9 @@ function createStoredQueriesOutputView(stored_queries) {
 
 /**
  * @param {GraphNode} graph_node
- * @param {import('./output-view.types.ts').OutputDerivedSummary | null} derived_summary
+ * @param {OutputDerivedSummary | null} derived_summary
  * @param {NonNullable<PatramRepoConfig['fields']>} field_definitions
- * @returns {$k$$l$output$j$view$k$types$k$ts.OutputNodeItem}
+ * @returns {OutputNodeItem}
  */
 function createOutputNodeItem(graph_node, derived_summary, field_definitions) {
   const title = getOutputNodeTitle(graph_node);
@@ -210,10 +202,16 @@ function createOutputNodeItem(graph_node, derived_summary, field_definitions) {
 /**
  * @param {{ kind?: string, path: string, status?: string, title: string }} target
  * @param {NonNullable<PatramRepoConfig['fields']>} field_definitions
- * @param {import('./output-view.types.ts').OutputDerivedSummary | null} derived_summary
- * @returns {$k$$l$output$j$view$k$types$k$ts.OutputResolvedLinkTarget}
+ * @param {OutputDerivedSummary | null} derived_summary
+ * @param {GraphNode | undefined} graph_node
+ * @returns {OutputResolvedLinkTarget}
  */
-function createResolvedLinkTarget(target, field_definitions, derived_summary) {
+function createResolvedLinkTarget(
+  target,
+  field_definitions,
+  derived_summary,
+  graph_node,
+) {
   /** @type {Record<string, string | string[]>} */
   const fields = {};
 
@@ -221,11 +219,11 @@ function createResolvedLinkTarget(target, field_definitions, derived_summary) {
     fields.status = target.status;
   }
 
-  /** @type {$k$$l$output$j$view$k$types$k$ts.OutputResolvedLinkTarget} */
+  /** @type {OutputResolvedLinkTarget} */
   const resolved_target = {
     derived_summary: derived_summary ?? undefined,
     fields,
-    id: `doc:${target.path}`,
+    id: graph_node ? getOutputNodeId(graph_node) : `doc:${target.path}`,
     kind: target.kind ?? 'document',
     path: target.path,
     title: target.title,
@@ -286,6 +284,53 @@ function getOutputNodeId(graph_node) {
   );
 }
 
+/**
+ * @param {{ label: string, reference: number, target: { kind?: string, path: string, status?: string, title: string } }} resolved_link
+ * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, document_node_ids?: BuildGraphResult['document_node_ids'], graph_nodes?: BuildGraphResult['nodes'], repo_config?: PatramRepoConfig }} command_options
+ * @returns {OutputResolvedLinkItem}
+ */
+function createResolvedLinkOutputItem(resolved_link, command_options) {
+  const target_graph_node = resolveDocumentGraphNode(
+    command_options.graph_nodes,
+    command_options.document_node_ids,
+    resolved_link.target.path,
+  );
+
+  return {
+    kind: 'resolved_link',
+    label: resolved_link.label,
+    reference: resolved_link.reference,
+    target: createResolvedLinkTarget(
+      resolved_link.target,
+      command_options.repo_config?.fields ?? {},
+      target_graph_node
+        ? (command_options.derived_summary_evaluator?.evaluate(
+            target_graph_node,
+          ) ?? null)
+        : null,
+      target_graph_node,
+    ),
+  };
+}
+
+/**
+ * @param {BuildGraphResult['nodes'] | undefined} graph_nodes
+ * @param {BuildGraphResult['document_node_ids'] | undefined} document_node_ids
+ * @param {string} document_path
+ * @returns {GraphNode | undefined}
+ */
+function resolveDocumentGraphNode(
+  graph_nodes,
+  document_node_ids,
+  document_path,
+) {
+  if (!graph_nodes) {
+    return undefined;
+  }
+
+  return graph_nodes[resolveDocumentNodeId(document_node_ids, document_path)];
+}
+
 /**
  * @param {GraphNode} graph_node
  * @param {NonNullable<PatramRepoConfig['fields']>} field_definitions

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/resolve-patram-graph-config.js

@@ -1,4 +1,5 @@
 /**
+ * @import { ClassDefinition } from './patram-config.js';
  * @import { PatramRepoConfig } from './load-patram-config.types.ts';
  * @import { PatramConfig } from './patram-config.types.ts';
  */
@@ -74,7 +75,7 @@ export function resolvePatramGraphConfig(repo_config) {
   const graph_config = parsePatramConfig({
     classes: {
       ...BUILT_IN_PATRAM_CONFIG.classes,
-      ...repo_config.classes,
+      ...collectGraphClassDefinitions(repo_config.classes),
     },
     mappings: {
       ...BUILT_IN_PATRAM_CONFIG.mappings,
@@ -88,7 +89,44 @@ export function resolvePatramGraphConfig(repo_config) {
 
   return {
     ...graph_config,
-    class_schemas: repo_config.class_schemas,
+    classes: mergeResolvedClasses(graph_config.classes, repo_config.classes),
     fields: repo_config.fields,
   };
 }
+
+/**
+ * @param {PatramRepoConfig['classes']} classes
+ * @returns {Record<string, ClassDefinition>}
+ */
+function collectGraphClassDefinitions(classes) {
+  /** @type {Record<string, ClassDefinition>} */
+  const graph_class_definitions = {};
+
+  for (const [class_name, class_definition] of Object.entries(classes ?? {})) {
+    graph_class_definitions[class_name] = {
+      builtin: class_definition.builtin,
+      label: class_definition.label,
+    };
+  }
+
+  return graph_class_definitions;
+}
+
+/**
+ * @param {Record<string, ClassDefinition>} graph_classes
+ * @param {PatramRepoConfig['classes']} repo_classes
+ * @returns {PatramConfig['classes']}
+ */
+function mergeResolvedClasses(graph_classes, repo_classes) {
+  /** @type {PatramConfig['classes']} */
+  const resolved_classes = {};
+
+  for (const [class_name, class_definition] of Object.entries(graph_classes)) {
+    resolved_classes[class_name] = {
+      ...class_definition,
+      schema: repo_classes?.[class_name]?.schema,
+    };
+  }
+
+  return resolved_classes;
+}