patram 0.2.0 → 0.4.0

package/lib/render-field-discovery.js

@@ -0,0 +1,184 @@
+/**
+ * @import { ResolvedOutputMode } from './output-view.types.ts';
+ * @import { FieldDiscoveryResult, FieldDiscoverySuggestion } from './discover-fields.types.ts';
+ */
+
+import { Ansis } from 'ansis';
+
+const MAX_TEXT_EVIDENCE_ROWS = 5;
+
+/**
+ * Render field discovery output.
+ *
+ * @param {FieldDiscoveryResult} discovery_result
+ * @param {ResolvedOutputMode} output_mode
+ * @returns {string}
+ */
+export function renderFieldDiscovery(discovery_result, output_mode) {
+  if (output_mode.renderer_name === 'json') {
+    return `${JSON.stringify(formatJsonFieldDiscovery(discovery_result), null, 2)}\n`;
+  }
+
+  return renderTextFieldDiscovery(discovery_result, output_mode);
+}
+
+/**
+ * @param {FieldDiscoveryResult} discovery_result
+ * @returns {{ fields: Array<Record<string, unknown>>, summary: FieldDiscoveryResult['summary'] }}
+ */
+function formatJsonFieldDiscovery(discovery_result) {
+  return {
+    fields: discovery_result.fields.map(formatJsonFieldSuggestion),
+    summary: discovery_result.summary,
+  };
+}
+
+/**
+ * @param {FieldDiscoverySuggestion} field_suggestion
+ * @returns {Record<string, unknown>}
+ */
+function formatJsonFieldSuggestion(field_suggestion) {
+  return {
+    confidence: field_suggestion.confidence,
+    conflicting_evidence: field_suggestion.conflicting_evidence,
+    evidence_references: field_suggestion.evidence_references,
+    likely_class_usage: field_suggestion.likely_class_usage,
+    likely_multiplicity: field_suggestion.likely_multiplicity,
+    likely_type: field_suggestion.likely_type,
+    name: field_suggestion.name,
+  };
+}
+
+/**
+ * @param {FieldDiscoveryResult} discovery_result
+ * @param {ResolvedOutputMode} output_mode
+ * @returns {string}
+ */
+function renderTextFieldDiscovery(discovery_result, output_mode) {
+  const ansi = new Ansis(
+    output_mode.renderer_name === 'rich' && output_mode.color_enabled ? 3 : 0,
+  );
+  /** @type {string[]} */
+  const output_lines = [];
+
+  output_lines.push(
+    output_mode.renderer_name === 'rich'
+      ? ansi.green('Field discovery')
+      : 'Field discovery',
+  );
+
+  output_lines.push(
+    output_mode.renderer_name === 'rich'
+      ? ansi.gray(
+          `Found ${discovery_result.summary.count} suggested fields from ${discovery_result.summary.source_file_count} source files.`,
+        )
+      : `Found ${discovery_result.summary.count} suggested fields from ${discovery_result.summary.source_file_count} source files.`,
+  );
+
+  for (const field_suggestion of discovery_result.fields) {
+    output_lines.push(
+      '',
+      ...formatTextFieldSuggestion(field_suggestion, {
+        header: (value) =>
+          output_mode.renderer_name === 'rich' ? ansi.green(value) : value,
+        label: (value) =>
+          output_mode.renderer_name === 'rich' ? ansi.gray(value) : value,
+      }),
+    );
+  }
+
+  if (discovery_result.fields.length === 0) {
+    output_lines.push('', 'No field candidates discovered.');
+  }
+
+  return `${output_lines.join('\n')}\n`;
+}
+
+/**
+ * @param {FieldDiscoverySuggestion} field_suggestion
+ * @param {{ header: (value: string) => string, label: (value: string) => string }} render_options
+ * @returns {string[]}
+ */
+function formatTextFieldSuggestion(field_suggestion, render_options) {
+  /** @type {string[]} */
+  const lines = [render_options.header(field_suggestion.name)];
+
+  lines.push(
+    `${render_options.label('  likely type:')} ${field_suggestion.likely_type.name}`,
+    `${render_options.label('  likely multiplicity:')} ${field_suggestion.likely_multiplicity.name}`,
+    `${render_options.label('  likely class usage:')} ${field_suggestion.likely_class_usage.classes.join(', ')}`,
+    `${render_options.label('  confidence:')} ${formatConfidence(field_suggestion.confidence)}`,
+  );
+
+  if (field_suggestion.evidence_references.length > 0) {
+    lines.push(
+      ...formatTextEvidenceSection(
+        '  evidence:',
+        field_suggestion.evidence_references,
+        render_options,
+      ),
+    );
+  }
+
+  if (field_suggestion.conflicting_evidence.length > 0) {
+    lines.push(
+      ...formatTextEvidenceSection(
+        '  conflicting evidence:',
+        field_suggestion.conflicting_evidence,
+        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}
+ */
+function formatEvidenceReference(evidence_reference) {
+  return `${evidence_reference.path}:${evidence_reference.line}:${evidence_reference.column} ${JSON.stringify(evidence_reference.value)}`;
+}
+
+/**
+ * @param {number} confidence
+ * @returns {string}
+ */
+function formatConfidence(confidence) {
+  return confidence.toFixed(2);
+}

package/lib/render-json-output.js

@@ -55,19 +55,19 @@ export function renderJsonOutput(output_view) {
 
 /**
  * @param {OutputNodeItem} output_item
- * @returns {{ derived?: Record<string, boolean | number | string | null>, derived_summary?: string, id: string, kind: string, title: string, path: string, status?: string }}
+ * @returns {{ '$class': string, '$id': string, '$path'?: string, derived?: Record<string, boolean | number | string | null>, derived_summary?: string, fields: Record<string, string | string[]>, title: string }}
  */
 function formatJsonQueryItem(output_item) {
-  /** @type {{ derived?: Record<string, boolean | number | string | null>, derived_summary?: string, id: string, kind: string, title: string, path: string, status?: string }} */
+  /** @type {{ '$class': string, '$id': string, '$path'?: string, derived?: Record<string, boolean | number | string | null>, derived_summary?: string, fields: Record<string, string | string[]>, title: string }} */
   const query_item = {
-    id: output_item.id,
-    kind: output_item.node_kind,
+    $class: output_item.node_kind,
+    $id: output_item.id,
+    fields: output_item.fields,
     title: output_item.title,
-    path: output_item.path,
   };
 
-  if (output_item.status) {
-    query_item.status = output_item.status;
+  if (output_item.path) {
+    query_item.$path = output_item.path;
   }
 
   if (output_item.derived_summary) {
@@ -96,25 +96,23 @@ function formatJsonStoredQuery(output_item) {
 
 /**
  * @param {OutputResolvedLinkItem} output_item
- * @returns {{ label: string, reference: number, target: { derived?: Record<string, boolean | number | string | null>, derived_summary?: string, kind?: string, path: string, status?: string, title: string } }}
+ * @returns {{ label: string, reference: number, target: { '$class': string, '$id': string, '$path'?: string, derived?: Record<string, boolean | number | string | null>, derived_summary?: string, fields: Record<string, string | string[]>, title: string } }}
  */
 function formatJsonResolvedLink(output_item) {
-  /** @type {{ label: string, reference: number, target: { derived?: Record<string, boolean | number | string | null>, derived_summary?: string, kind?: string, path: string, status?: string, title: string } }} */
+  /** @type {{ label: string, reference: number, target: { '$class': string, '$id': string, '$path'?: string, derived?: Record<string, boolean | number | string | null>, derived_summary?: string, fields: Record<string, string | string[]>, title: string } }} */
   const resolved_link = {
     reference: output_item.reference,
     label: output_item.label,
     target: {
+      $class: output_item.target.kind,
+      $id: output_item.target.id,
+      fields: output_item.target.fields,
       title: output_item.target.title,
-      path: output_item.target.path,
     },
   };
 
-  if (output_item.target.kind) {
-    resolved_link.target.kind = output_item.target.kind;
-  }
-
-  if (output_item.target.status) {
-    resolved_link.target.status = output_item.target.status;
+  if (output_item.target.path) {
+    resolved_link.target.$path = output_item.target.path;
   }
 
   if (output_item.target.derived_summary) {
@@ -133,18 +131,19 @@ function formatJsonResolvedLink(output_item) {
 
 /**
  * @param {OutputNodeItem} output_item
- * @returns {{ derived?: Record<string, boolean | number | string | null>, derived_summary?: string, kind: string, title: string, path: string, status?: string }}
+ * @returns {{ '$class': string, '$id': string, '$path'?: string, derived?: Record<string, boolean | number | string | null>, derived_summary?: string, fields: Record<string, string | string[]>, title: string }}
  */
 function formatJsonShowDocument(output_item) {
-  /** @type {{ derived?: Record<string, boolean | number | string | null>, derived_summary?: string, kind: string, title: string, path: string, status?: string }} */
+  /** @type {{ '$class': string, '$id': string, '$path'?: string, derived?: Record<string, boolean | number | string | null>, derived_summary?: string, fields: Record<string, string | string[]>, title: string }} */
   const document_summary = {
-    kind: output_item.node_kind,
-    path: output_item.path,
+    $class: output_item.node_kind,
+    $id: output_item.id,
+    fields: output_item.fields,
     title: output_item.title,
   };
 
-  if (output_item.status) {
-    document_summary.status = output_item.status;
+  if (output_item.path) {
+    document_summary.$path = output_item.path;
   }
 
   if (output_item.derived_summary) {

package/lib/render-output-view.js

@@ -1,14 +1,17 @@
 /** @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 { 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';
 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.
@@ -30,7 +33,7 @@ import { renderRichOutput } from './render-rich-output.js';
  *
  * @param {'query' | 'queries'} command_name
  * @param {GraphNode[] | { name: string, where: string }[]} command_items
- * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, 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) {
@@ -54,12 +57,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'] }=} 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',
@@ -69,22 +75,13 @@ export function createShowOutputView(show_output, command_options = {}) {
           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,
-        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,
@@ -124,7 +121,7 @@ export async function renderOutputView(
 
 /**
  * @param {GraphNode[]} graph_nodes
- * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, 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 = {}) {
@@ -134,11 +131,12 @@ function createQueryOutputView(graph_nodes, command_options = {}) {
     command: 'query',
     hints:
       command_options.hints ??
-      (total_count === 0 ? ['Try: patram query --where "kind=task"'] : []),
+      (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: {
@@ -174,13 +172,17 @@ 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, derived_summary) {
-  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.`,
     );
@@ -188,35 +190,300 @@ function createOutputNodeItem(graph_node, derived_summary) {
 
   return {
     derived_summary: derived_summary ?? undefined,
-    id: graph_node.id,
+    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
+ * @param {GraphNode | undefined} graph_node
  * @returns {$k$$l$output$j$view$k$types$k$ts.OutputResolvedLinkTarget}
  */
-function createResolvedLinkTarget(target, derived_summary) {
+function createResolvedLinkTarget(
+  target,
+  field_definitions,
+  derived_summary,
+  graph_node,
+) {
+  /** @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: graph_node ? getOutputNodeId(graph_node) : `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 {{ 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 {$k$$l$output$j$view$k$types$k$ts.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 resolved_target;
+  return graph_nodes[resolveDocumentNodeId(document_node_ids, document_path)];
+}
+
+/**
+ * @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;
+  }
+
+  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;
 }