patram 0.2.0 → 0.4.0

package/lib/render-plain-output.js

@@ -128,7 +128,7 @@ function formatPlainStoredQueryLine(line_segments) {
  */
 function formatPlainResolvedLinkItem(output_item) {
   return formatOutputItemBlock({
-    header: `[${output_item.reference}] document ${output_item.target.path}`,
+    header: `[${output_item.reference}] ${output_item.target.kind} ${output_item.target.path ?? output_item.target.id}`,
     metadata_rows: formatResolvedLinkMetadataRows(output_item.target),
     metadata_indent: '    ',
     title: output_item.target.title,

package/lib/render-rich-output.js

@@ -155,7 +155,7 @@ function formatRichStoredQueryLine(line_segments, ansi) {
  */
 function formatRichResolvedLinkItem(output_item, ansi) {
   return formatOutputItemBlock({
-    header: `${ansi.gray(`[${output_item.reference}]`)} ${ansi.green(`document ${output_item.target.path}`)}`,
+    header: `${ansi.gray(`[${output_item.reference}]`)} ${ansi.green(`${output_item.target.kind} ${output_item.target.path ?? output_item.target.id}`)}`,
     metadata_rows: formatResolvedLinkMetadataRows(output_item.target),
     metadata_indent: '    ',
     title: output_item.target.title,

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

@@ -21,7 +21,7 @@ import { parsePatramConfig } from './patram-config.js';
  */
 
 const BUILT_IN_PATRAM_CONFIG = {
-  kinds: {
+  classes: {
     document: {
       builtin: true,
       label: 'Document',
@@ -30,28 +30,28 @@ const BUILT_IN_PATRAM_CONFIG = {
   mappings: {
     'document.title': {
       node: {
+        class: 'document',
         field: 'title',
-        kind: 'document',
       },
     },
     'document.description': {
       node: {
+        class: 'document',
         field: 'description',
-        kind: 'document',
       },
     },
     'jsdoc.link': {
       emit: {
         relation: 'links_to',
         target: 'path',
-        target_kind: 'document',
+        target_class: 'document',
       },
     },
     'markdown.link': {
       emit: {
         relation: 'links_to',
         target: 'path',
-        target_kind: 'document',
+        target_class: 'document',
       },
     },
   },
@@ -71,10 +71,10 @@ const BUILT_IN_PATRAM_CONFIG = {
  * @returns {PatramConfig}
  */
 export function resolvePatramGraphConfig(repo_config) {
-  return parsePatramConfig({
-    kinds: {
-      ...BUILT_IN_PATRAM_CONFIG.kinds,
-      ...repo_config.kinds,
+  const graph_config = parsePatramConfig({
+    classes: {
+      ...BUILT_IN_PATRAM_CONFIG.classes,
+      ...repo_config.classes,
     },
     mappings: {
       ...BUILT_IN_PATRAM_CONFIG.mappings,
@@ -85,4 +85,10 @@ export function resolvePatramGraphConfig(repo_config) {
       ...repo_config.relations,
     },
   });
+
+  return {
+    ...graph_config,
+    class_schemas: repo_config.class_schemas,
+    fields: repo_config.fields,
+  };
 }

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,18 +223,17 @@ function createResolvedLinkSummary(
     source_file_path,
     claim_value.target,
   );
-  const target_node = graph_nodes[`doc:${target_path}`];
-  const target_title = target_node?.title ?? claim_value.text;
+  const target_node =
+    graph_nodes[resolveDocumentNodeId(document_node_ids, target_path)];
 
   return {
     label: claim_value.text,
     reference,
-    target: {
-      kind: target_node?.kind,
-      path: target_node?.path ?? target_path,
-      status: target_node?.status,
-      title: target_title,
-    },
+    target: createResolvedLinkTarget(
+      target_node,
+      target_path,
+      claim_value.text,
+    ),
   };
 }
 
@@ -239,6 +250,52 @@ function resolveShowTargetPath(source_file_path, raw_target) {
   return normalizeRepoRelativePath(posix.join(source_directory, raw_target));
 }
 
+/**
+ * @param {string | string[] | undefined} field_value
+ * @returns {string | undefined}
+ */
+function getScalarGraphField(field_value) {
+  if (Array.isArray(field_value)) {
+    return field_value[0];
+  }
+
+  return field_value;
+}
+
+/**
+ * @param {GraphNode | undefined} target_node
+ * @param {string} target_path
+ * @param {string} fallback_title
+ * @returns {{ kind?: string, path: string, status?: string, title: string }}
+ */
+function createResolvedLinkTarget(target_node, target_path, fallback_title) {
+  return {
+    kind: getResolvedLinkTargetKind(target_node),
+    path: getResolvedLinkTargetPath(target_node, target_path),
+    status: getScalarGraphField(target_node?.status),
+    title: getScalarGraphField(target_node?.title) ?? fallback_title,
+  };
+}
+
+/**
+ * @param {GraphNode | undefined} target_node
+ * @returns {string | undefined}
+ */
+function getResolvedLinkTargetKind(target_node) {
+  return getScalarGraphField(target_node?.$class ?? target_node?.kind);
+}
+
+/**
+ * @param {GraphNode | undefined} target_node
+ * @param {string} target_path
+ * @returns {string}
+ */
+function getResolvedLinkTargetPath(target_node, target_path) {
+  return (
+    getScalarGraphField(target_node?.$path ?? target_node?.path) ?? target_path
+  );
+}
+
 /**
  * @param {PatramClaim} claim
  * @returns {claim is PatramClaim & { type: 'markdown.link', value: { target: string, text: string } }}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patram",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "./lib/patram.js",
   "exports": {
@@ -65,8 +65,8 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^24.12.0",
-    "@vitest/coverage-v8": "^4.1.0",
-    "eslint": "^10.0.3",
+    "@vitest/coverage-v8": "^4.1.1",
+    "eslint": "^10.1.0",
     "eslint-plugin-jsdoc": "^62.8.0",
     "globals": "^17.4.0",
     "husky": "^9.1.7",
@@ -74,7 +74,7 @@
     "lint-staged": "^16.2.6",
     "prettier": "^3.5.3",
     "slice-ansi": "^8.0.0",
-    "typescript": "^5.8.2",
-    "vitest": "^4.1.0"
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.1"
   }
 }