patram 0.1.1 → 0.3.0

package/lib/render-output-view.js

@@ -1,8 +1,11 @@
 /** @import * as $k$$l$output$j$view$k$types$k$ts from './output-view.types.ts'; */
+/* eslint-disable max-lines */
 /**
- * @import { GraphNode } from './build-graph.types.ts';
+ * @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 { OutputStoredQueryItem, OutputView, ResolvedOutputMode, ShowOutputView } from './output-view.types.ts';
+ * @import { OutputMetadataField, OutputStoredQueryItem, OutputView, ResolvedOutputMode, ShowOutputView } from './output-view.types.ts';
  */
 
 import { renderJsonOutput } from './render-json-output.js';
@@ -29,7 +32,7 @@ import { renderRichOutput } from './render-rich-output.js';
  *
  * @param {'query' | 'queries'} command_name
  * @param {GraphNode[] | { name: string, where: string }[]} command_items
- * @param {{ hints?: string[], limit?: number, offset?: number, total_count?: number }=} command_options
+ * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, hints?: string[], limit?: number, offset?: number, repo_config?: PatramRepoConfig, total_count?: number }=} command_options
  * @returns {OutputView}
  */
 export function createOutputView(command_name, command_items, command_options) {
@@ -53,17 +56,38 @@ 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
  * @returns {ShowOutputView}
  */
-export function createShowOutputView(show_output) {
+export function createShowOutputView(show_output, command_options = {}) {
+  const shown_document_node =
+    command_options.graph_nodes?.[`doc:${show_output.path}`];
+
   return {
     command: 'show',
+    document: shown_document_node
+      ? createOutputNodeItem(
+          shown_document_node,
+          command_options.derived_summary_evaluator?.evaluate(
+            shown_document_node,
+          ) ?? null,
+          command_options.repo_config?.fields ?? {},
+        )
+      : 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),
+      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,
+      ),
     })),
     path: show_output.path,
     rendered_source: show_output.rendered_source,
@@ -104,7 +128,7 @@ export async function renderOutputView(
 
 /**
  * @param {GraphNode[]} graph_nodes
- * @param {{ hints?: string[], limit?: number, offset?: number, total_count?: number }=} command_options
+ * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, hints?: string[], limit?: number, offset?: number, repo_config?: PatramRepoConfig, total_count?: number }=} command_options
  * @returns {OutputView}
  */
 function createQueryOutputView(graph_nodes, command_options = {}) {
@@ -114,8 +138,14 @@ function createQueryOutputView(graph_nodes, command_options = {}) {
     command: 'query',
     hints:
       command_options.hints ??
-      (total_count === 0 ? ['Try: patram query --where "kind=task"'] : []),
-    items: graph_nodes.map(createOutputNodeItem),
+      (total_count === 0 ? ['Try: patram query --where "$class=task"'] : []),
+    items: graph_nodes.map((graph_node) =>
+      createOutputNodeItem(
+        graph_node,
+        command_options.derived_summary_evaluator?.evaluate(graph_node) ?? null,
+        command_options.repo_config?.fields ?? {},
+      ),
+    ),
     summary: {
       count: graph_nodes.length,
       kind: 'result_list',
@@ -148,46 +178,266 @@ function createStoredQueriesOutputView(stored_queries) {
 
 /**
  * @param {GraphNode} graph_node
+ * @param {import('./output-view.types.ts').OutputDerivedSummary | null} derived_summary
+ * @param {NonNullable<PatramRepoConfig['fields']>} field_definitions
  * @returns {$k$$l$output$j$view$k$types$k$ts.OutputNodeItem}
  */
-function createOutputNodeItem(graph_node) {
-  const title =
-    graph_node.title ?? graph_node.label ?? graph_node.path ?? graph_node.key;
+function createOutputNodeItem(graph_node, derived_summary, field_definitions) {
+  const title = getOutputNodeTitle(graph_node);
+  const path = getOutputNodePath(graph_node);
+  const node_class = getOutputNodeClass(graph_node);
+  const fields = collectOutputFields(graph_node, field_definitions);
+  const visible_fields = createVisibleOutputFields(fields, field_definitions);
 
-  if (!title || !graph_node.path) {
+  if (!title || !node_class) {
     throw new Error(
       `Expected graph node "${graph_node.id}" to have a title and path.`,
     );
   }
 
   return {
-    id: graph_node.id,
+    derived_summary: derived_summary ?? undefined,
+    fields,
+    id: getOutputNodeId(graph_node),
     kind: 'node',
-    node_kind: graph_node.kind,
-    path: graph_node.path,
-    status: graph_node.status,
+    node_kind: node_class,
+    path,
     title,
+    visible_fields,
   };
 }
 
 /**
  * @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}
  */
-function createResolvedLinkTarget(target) {
+function createResolvedLinkTarget(target, field_definitions, derived_summary) {
+  /** @type {Record<string, string | string[]>} */
+  const fields = {};
+
+  if (target.status) {
+    fields.status = target.status;
+  }
+
   /** @type {$k$$l$output$j$view$k$types$k$ts.OutputResolvedLinkTarget} */
   const resolved_target = {
+    derived_summary: derived_summary ?? undefined,
+    fields,
+    id: `doc:${target.path}`,
+    kind: target.kind ?? 'document',
     path: target.path,
     title: target.title,
+    visible_fields: createVisibleOutputFields(fields, field_definitions),
   };
 
-  if (target.kind && target.kind !== 'document') {
-    resolved_target.kind = target.kind;
+  return resolved_target;
+}
+
+/**
+ * @param {string | string[] | undefined} field_value
+ * @returns {string | undefined}
+ */
+function getScalarGraphNodeField(field_value) {
+  if (Array.isArray(field_value)) {
+    return field_value[0];
   }
 
-  if (target.status) {
-    resolved_target.status = target.status;
+  return field_value;
+}
+
+/**
+ * @param {GraphNode} graph_node
+ * @returns {string | undefined}
+ */
+function getOutputNodeTitle(graph_node) {
+  return (
+    getScalarGraphNodeField(graph_node.title) ??
+    getScalarGraphNodeField(graph_node.label) ??
+    getOutputNodePath(graph_node) ??
+    getScalarGraphNodeField(graph_node.key)
+  );
+}
+
+/**
+ * @param {GraphNode} graph_node
+ * @returns {string | undefined}
+ */
+function getOutputNodePath(graph_node) {
+  return getScalarGraphNodeField(graph_node.$path ?? graph_node.path);
+}
+
+/**
+ * @param {GraphNode} graph_node
+ * @returns {string | undefined}
+ */
+function getOutputNodeClass(graph_node) {
+  return getScalarGraphNodeField(graph_node.$class ?? graph_node.kind);
+}
+
+/**
+ * @param {GraphNode} graph_node
+ * @returns {string}
+ */
+function getOutputNodeId(graph_node) {
+  return (
+    getScalarGraphNodeField(graph_node.$id ?? graph_node.id) ?? graph_node.id
+  );
+}
+
+/**
+ * @param {GraphNode} graph_node
+ * @param {NonNullable<PatramRepoConfig['fields']>} field_definitions
+ * @returns {Record<string, string | string[]>}
+ */
+function collectOutputFields(graph_node, field_definitions) {
+  /** @type {Record<string, string | string[]>} */
+  const fields = {};
+
+  for (const [field_name, field_value] of Object.entries(graph_node)) {
+    const normalized_value = getCollectedOutputFieldValue(
+      graph_node,
+      field_name,
+      field_value,
+    );
+
+    if (normalized_value === undefined) {
+      continue;
+    }
+
+    fields[field_name] = normalized_value;
   }
 
-  return resolved_target;
+  for (const field_name of Object.keys(field_definitions)) {
+    if (fields[field_name] !== undefined) {
+      continue;
+    }
+
+    const field_value = normalizeOutputFieldValue(graph_node[field_name]);
+
+    if (field_value !== undefined) {
+      fields[field_name] = field_value;
+    }
+  }
+
+  return fields;
+}
+
+/**
+ * @param {GraphNode} graph_node
+ * @param {string} field_name
+ * @param {unknown} field_value
+ * @returns {string | string[] | undefined}
+ */
+function getCollectedOutputFieldValue(graph_node, field_name, field_value) {
+  if (isInternalOutputField(field_name)) {
+    return undefined;
+  }
+
+  const normalized_value = normalizeOutputFieldValue(field_value);
+
+  if (normalized_value === undefined) {
+    return undefined;
+  }
+
+  if (isLegacyMirrorOutputField(graph_node, field_name, normalized_value)) {
+    return undefined;
+  }
+
+  return normalized_value;
+}
+
+/**
+ * @param {GraphNode} graph_node
+ * @param {string} field_name
+ * @param {string | string[]} normalized_value
+ * @returns {boolean}
+ */
+function isLegacyMirrorOutputField(graph_node, field_name, normalized_value) {
+  if (Array.isArray(normalized_value)) {
+    return false;
+  }
+
+  if (field_name === 'kind') {
+    return normalized_value === graph_node.$class;
+  }
+
+  if (field_name === 'path') {
+    return normalized_value === graph_node.$path;
+  }
+
+  if (field_name === 'id') {
+    return normalized_value === graph_node.$id;
+  }
+
+  return false;
+}
+
+/**
+ * @param {Record<string, string | string[]>} fields
+ * @param {NonNullable<PatramRepoConfig['fields']>} field_definitions
+ * @returns {OutputMetadataField[]}
+ */
+function createVisibleOutputFields(fields, field_definitions) {
+  return Object.entries(fields)
+    .filter(
+      ([field_name]) => field_definitions[field_name]?.display?.hidden !== true,
+    )
+    .sort(([left_name], [right_name]) =>
+      compareOutputFieldNames(left_name, right_name, field_definitions),
+    )
+    .map(([name, value]) => ({ name, value }));
+}
+
+/**
+ * @param {string} field_name
+ * @returns {boolean}
+ */
+function isInternalOutputField(field_name) {
+  return (
+    field_name === '$class' ||
+    field_name === '$id' ||
+    field_name === '$path' ||
+    field_name === 'id' ||
+    field_name === 'key' ||
+    field_name === 'label' ||
+    field_name === 'path' ||
+    field_name === 'title'
+  );
+}
+
+/**
+ * @param {string} left_name
+ * @param {string} right_name
+ * @param {NonNullable<PatramRepoConfig['fields']>} field_definitions
+ * @returns {number}
+ */
+function compareOutputFieldNames(left_name, right_name, field_definitions) {
+  const left_order =
+    field_definitions[left_name]?.display?.order ?? Number.MAX_SAFE_INTEGER;
+  const right_order =
+    field_definitions[right_name]?.display?.order ?? Number.MAX_SAFE_INTEGER;
+
+  if (left_order !== right_order) {
+    return left_order - right_order;
+  }
+
+  return left_name.localeCompare(right_name, 'en');
+}
+
+/**
+ * @param {unknown} field_value
+ * @returns {string | string[] | undefined}
+ */
+function normalizeOutputFieldValue(field_value) {
+  if (Array.isArray(field_value)) {
+    const string_values = field_value.flatMap((value) =>
+      typeof value === 'string' ? [value] : [],
+    );
+
+    return string_values.length > 0 ? string_values : undefined;
+  }
+
+  return typeof field_value === 'string' ? field_value : undefined;
 }

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}] ${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

@@ -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(`${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,
+  });
 }
 
 /**
@@ -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}