patram 0.0.2 → 0.2.0

package/lib/render-output-view.js

@@ -0,0 +1,222 @@
+/** @import * as $k$$l$output$j$view$k$types$k$ts from './output-view.types.ts'; */
+/**
+ * @import { BuildGraphResult, GraphNode } from './build-graph.types.ts';
+ * @import { DerivedSummaryEvaluator } from './derived-summary.js';
+ * @import { ParsedCliArguments } from './parse-cli-arguments.types.ts';
+ * @import { 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';
+
+/**
+ * Shared command output views.
+ *
+ * Normalizes `query`, `queries`, and `show` results into renderer-specific
+ * output models.
+ *
+ * Kind: output
+ * Status: active
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/cli-output-architecture.md
+ * @patram
+ * @see {@link ./show-document.js}
+ * @see {@link ../docs/decisions/cli-output-architecture.md}
+ */
+
+/**
+ * Create a shared output view from one command result.
+ *
+ * @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
+ * @returns {OutputView}
+ */
+export function createOutputView(command_name, command_items, command_options) {
+  if (command_name === 'query') {
+    return createQueryOutputView(
+      /** @type {GraphNode[]} */ (command_items),
+      command_options,
+    );
+  }
+
+  if (command_name === 'queries') {
+    return createStoredQueriesOutputView(
+      /** @type {OutputStoredQueryItem[]} */ (command_items),
+    );
+  }
+
+  throw new Error(`Unsupported output view command "${command_name}".`);
+}
+
+/**
+ * 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
+ * @returns {ShowOutputView}
+ */
+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,
+        )
+      : 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,
+      ),
+    })),
+    path: show_output.path,
+    rendered_source: show_output.rendered_source,
+    source: show_output.source,
+    summary: {
+      count: show_output.resolved_links.length,
+      kind: 'resolved_link_list',
+    },
+  };
+}
+
+/**
+ * Render one shared output view through the resolved renderer.
+ *
+ * @param {OutputView} output_view
+ * @param {ResolvedOutputMode} output_mode
+ * @param {ParsedCliArguments} parsed_arguments
+ * @returns {Promise<string>}
+ */
+export async function renderOutputView(
+  output_view,
+  output_mode,
+  parsed_arguments,
+) {
+  if (output_mode.renderer_name === 'json') {
+    return renderJsonOutput(output_view);
+  }
+
+  if (output_mode.renderer_name === 'plain') {
+    return renderPlainOutput(output_view);
+  }
+
+  return renderRichOutput(output_view, {
+    color_enabled: output_mode.color_enabled,
+    color_mode: parsed_arguments.color_mode,
+  });
+}
+
+/**
+ * @param {GraphNode[]} graph_nodes
+ * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, hints?: string[], limit?: number, offset?: number, total_count?: number }=} command_options
+ * @returns {OutputView}
+ */
+function createQueryOutputView(graph_nodes, command_options = {}) {
+  const total_count = command_options.total_count ?? graph_nodes.length;
+
+  return {
+    command: 'query',
+    hints:
+      command_options.hints ??
+      (total_count === 0 ? ['Try: patram query --where "kind=task"'] : []),
+    items: graph_nodes.map((graph_node) =>
+      createOutputNodeItem(
+        graph_node,
+        command_options.derived_summary_evaluator?.evaluate(graph_node) ?? null,
+      ),
+    ),
+    summary: {
+      count: graph_nodes.length,
+      kind: 'result_list',
+      limit: command_options.limit ?? graph_nodes.length,
+      offset: command_options.offset ?? 0,
+      total_count,
+    },
+  };
+}
+
+/**
+ * @param {{ name: string, where: string }[]} stored_queries
+ * @returns {OutputView}
+ */
+function createStoredQueriesOutputView(stored_queries) {
+  return {
+    command: 'queries',
+    hints: [],
+    items: stored_queries.map((stored_query) => ({
+      kind: 'stored_query',
+      name: stored_query.name,
+      where: stored_query.where,
+    })),
+    summary: {
+      count: stored_queries.length,
+      kind: 'stored_query_list',
+    },
+  };
+}
+
+/**
+ * @param {GraphNode} graph_node
+ * @param {import('./output-view.types.ts').OutputDerivedSummary | null} derived_summary
+ * @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;
+
+  if (!title || !graph_node.path) {
+    throw new Error(
+      `Expected graph node "${graph_node.id}" to have a title and path.`,
+    );
+  }
+
+  return {
+    derived_summary: derived_summary ?? undefined,
+    id: graph_node.id,
+    kind: 'node',
+    node_kind: graph_node.kind,
+    path: graph_node.path,
+    status: graph_node.status,
+    title,
+  };
+}
+
+/**
+ * @param {{ kind?: string, path: string, status?: string, title: string }} target
+ * @param {import('./output-view.types.ts').OutputDerivedSummary | null} derived_summary
+ * @returns {$k$$l$output$j$view$k$types$k$ts.OutputResolvedLinkTarget}
+ */
+function createResolvedLinkTarget(target, derived_summary) {
+  /** @type {$k$$l$output$j$view$k$types$k$ts.OutputResolvedLinkTarget} */
+  const resolved_target = {
+    derived_summary: derived_summary ?? undefined,
+    path: target.path,
+    title: target.title,
+  };
+
+  if (target.kind && target.kind !== 'document') {
+    resolved_target.kind = target.kind;
+  }
+
+  if (target.status) {
+    resolved_target.status = target.status;
+  }
+
+  return resolved_target;
+}

package/lib/render-plain-output.js

@@ -0,0 +1,182 @@
+/**
+ * @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';
+
+/**
+ * Render the canonical plain output for one output view.
+ *
+ * @param {OutputView} output_view
+ * @returns {string}
+ */
+export function renderPlainOutput(output_view) {
+  if (output_view.command === 'query') {
+    return renderPlainQueryOutput(output_view);
+  }
+
+  if (output_view.command === 'queries') {
+    return renderPlainStoredQueries(output_view.items);
+  }
+
+  if (output_view.command === 'show') {
+    return renderPlainShowOutput(output_view);
+  }
+
+  throw new Error('Unsupported output view command.');
+}
+
+/**
+ * @param {QueryOutputView} output_view
+ * @returns {string}
+ */
+function renderPlainQueryOutput(output_view) {
+  const footer = renderPlainQueryFooter(output_view.summary, output_view.hints);
+
+  if (output_view.items.length === 0) {
+    return renderPlainEmptyQuery(footer);
+  }
+
+  if (footer.length === 0) {
+    return `${output_view.items.map(formatPlainNodeItem).join('\n\n')}\n`;
+  }
+
+  return `${output_view.items.map(formatPlainNodeItem).join('\n\n')}\n\n${footer}\n`;
+}
+
+/**
+ * @param {string} footer
+ * @returns {string}
+ */
+function renderPlainEmptyQuery(footer) {
+  if (footer.length === 0) {
+    return 'No matches.\n';
+  }
+
+  return `No matches.\n${footer}\n`;
+}
+
+/**
+ * @param {OutputStoredQueryItem[]} output_items
+ * @returns {string}
+ */
+function renderPlainStoredQueries(output_items) {
+  if (output_items.length === 0) {
+    return '';
+  }
+
+  return `${layoutStoredQueries(output_items)
+    .map(formatPlainStoredQueryLine)
+    .join('\n')}\n`;
+}
+
+/**
+ * @param {ShowOutputView} output_view
+ * @returns {string}
+ */
+function renderPlainShowOutput(output_view) {
+  const rendered_source = trimTrailingLineBreaks(output_view.rendered_source);
+  const document_summary = output_view.document
+    ? formatPlainNodeItem(output_view.document)
+    : '';
+
+  if (document_summary.length === 0 && output_view.items.length === 0) {
+    return `${rendered_source}\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`;
+}
+
+/**
+ * @param {OutputNodeItem} output_item
+ * @returns {string}
+ */
+function formatPlainNodeItem(output_item) {
+  return formatOutputItemBlock({
+    header: formatNodeHeader(output_item),
+    metadata_rows: formatOutputNodeMetadataRows(output_item),
+    title: output_item.title,
+  });
+}
+
+/**
+ * @param {{ text: string }[]} line_segments
+ * @returns {string}
+ */
+function formatPlainStoredQueryLine(line_segments) {
+  return line_segments.map((segment) => segment.text).join('');
+}
+
+/**
+ * @param {OutputResolvedLinkItem} output_item
+ * @returns {string}
+ */
+function formatPlainResolvedLinkItem(output_item) {
+  return formatOutputItemBlock({
+    header: `[${output_item.reference}] document ${output_item.target.path}`,
+    metadata_rows: formatResolvedLinkMetadataRows(output_item.target),
+    metadata_indent: '    ',
+    title: output_item.target.title,
+  });
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function trimTrailingLineBreaks(value) {
+  return value.replace(/\n+$/du, '');
+}
+
+/**
+ * @param {{ count: number, limit: number, offset: number, total_count: number }} summary
+ * @returns {string}
+ */
+function formatQuerySummary(summary) {
+  if (!shouldRenderQuerySummary(summary)) {
+    return '';
+  }
+
+  return `Showing ${summary.count} of ${summary.total_count} matches.`;
+}
+
+/**
+ * @param {{ count: number, limit: number, offset: number, total_count: number }} summary
+ * @param {string[]} hints
+ * @returns {string}
+ */
+function renderPlainQueryFooter(summary, hints) {
+  const summary_line = formatQuerySummary(summary);
+  const footer_lines = [];
+
+  if (summary_line.length > 0) {
+    footer_lines.push(summary_line);
+  }
+
+  footer_lines.push(...hints);
+
+  return footer_lines.join('\n');
+}
+
+/**
+ * @param {{ limit: number, offset: number, total_count: number }} summary
+ * @returns {boolean}
+ */
+function shouldRenderQuerySummary(summary) {
+  return summary.offset > 0 || summary.total_count > summary.limit;
+}

package/lib/render-rich-output.js

@@ -0,0 +1,240 @@
+/**
+ * @import { CliColorMode } from './parse-cli-arguments.types.ts';
+ * @import { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView, QueryOutputView, ShowOutputView } from './output-view.types.ts';
+ */
+
+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';
+
+const FULL_WIDTH_DIVIDER = ` ${'─'.repeat(78)} `;
+
+/**
+ * Render styled rich output while preserving the plain layout.
+ *
+ * @param {OutputView} output_view
+ * @param {{ color_mode: CliColorMode, color_enabled: boolean }} render_options
+ * @returns {Promise<string>}
+ */
+export async function renderRichOutput(output_view, render_options) {
+  const ansi = createAnsi(render_options.color_enabled);
+
+  if (output_view.command === 'query') {
+    return renderRichQueryOutput(output_view, ansi);
+  }
+
+  if (output_view.command === 'queries') {
+    return renderRichStoredQueries(output_view.items, ansi);
+  }
+
+  if (output_view.command === 'show') {
+    return renderRichShowOutput(output_view, render_options, ansi);
+  }
+
+  throw new Error('Unsupported output view command.');
+}
+
+/**
+ * @param {QueryOutputView} output_view
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function renderRichQueryOutput(output_view, ansi) {
+  const footer = renderRichQueryFooter(
+    output_view.summary,
+    output_view.hints,
+    ansi,
+  );
+
+  if (output_view.items.length === 0) {
+    return renderRichEmptyQuery(footer, ansi);
+  }
+
+  if (footer.length === 0) {
+    return `${output_view.items.map((item) => formatRichNodeItem(item, ansi)).join('\n\n')}\n`;
+  }
+
+  return `${output_view.items.map((item) => formatRichNodeItem(item, ansi)).join('\n\n')}\n\n${footer}\n`;
+}
+
+/**
+ * @param {string} footer
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function renderRichEmptyQuery(footer, ansi) {
+  if (footer.length === 0) {
+    return `${ansi.yellow('No matches.')}\n`;
+  }
+
+  return `${ansi.yellow('No matches.')}\n${footer}\n`;
+}
+
+/**
+ * @param {OutputStoredQueryItem[]} output_items
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function renderRichStoredQueries(output_items, ansi) {
+  if (output_items.length === 0) {
+    return '';
+  }
+
+  return `${layoutStoredQueries(output_items)
+    .map((line_segments) => formatRichStoredQueryLine(line_segments, ansi))
+    .join('\n')}\n`;
+}
+
+/**
+ * @param {ShowOutputView} output_view
+ * @param {{ color_mode: CliColorMode, color_enabled: boolean }} render_options
+ * @param {Ansis} ansi
+ * @returns {Promise<string>}
+ */
+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 (document_summary.length === 0 && output_view.items.length === 0) {
+    return `${rendered_source}\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`;
+}
+
+/**
+ * @param {OutputNodeItem} output_item
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function formatRichNodeItem(output_item, ansi) {
+  return formatOutputItemBlock({
+    header: ansi.green(formatNodeHeader(output_item)),
+    metadata_rows: formatOutputNodeMetadataRows(output_item),
+    title: output_item.title,
+  });
+}
+
+/**
+ * @param {{ kind: 'field_name' | 'keyword' | 'literal' | 'name' | 'operator' | 'plain', text: string }[]} line_segments
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function formatRichStoredQueryLine(line_segments, ansi) {
+  return line_segments
+    .map((line_segment) => styleStoredQuerySegment(line_segment, ansi))
+    .join('');
+}
+
+/**
+ * @param {OutputResolvedLinkItem} output_item
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function formatRichResolvedLinkItem(output_item, ansi) {
+  return formatOutputItemBlock({
+    header: `${ansi.gray(`[${output_item.reference}]`)} ${ansi.green(`document ${output_item.target.path}`)}`,
+    metadata_rows: formatResolvedLinkMetadataRows(output_item.target),
+    metadata_indent: '    ',
+    title: output_item.target.title,
+  });
+}
+
+/**
+ * @param {boolean} color_enabled
+ * @returns {Ansis}
+ */
+function createAnsi(color_enabled) {
+  return new Ansis(color_enabled ? 3 : 0);
+}
+
+/**
+ * @param {{ kind: 'field_name' | 'keyword' | 'literal' | 'name' | 'operator' | 'plain', text: string }} line_segment
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function styleStoredQuerySegment(line_segment, ansi) {
+  if (line_segment.kind === 'name') {
+    return ansi.green(line_segment.text);
+  }
+
+  if (line_segment.kind === 'operator') {
+    return ansi.gray(line_segment.text);
+  }
+
+  if (line_segment.kind === 'keyword') {
+    return ansi.gray(line_segment.text);
+  }
+
+  return line_segment.text;
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function trimTrailingLineBreaks(value) {
+  return value.replace(/\n+$/du, '');
+}
+
+/**
+ * @param {{ count: number, limit: number, offset: number, total_count: number }} summary
+ * @returns {string}
+ */
+function formatQuerySummary(summary) {
+  if (!shouldRenderQuerySummary(summary)) {
+    return '';
+  }
+
+  return `Showing ${summary.count} of ${summary.total_count} matches.`;
+}
+
+/**
+ * @param {{ count: number, limit: number, offset: number, total_count: number }} summary
+ * @param {string[]} hints
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function renderRichQueryFooter(summary, hints, ansi) {
+  const summary_line = formatQuerySummary(summary);
+  /** @type {string[]} */
+  const footer_lines = [];
+
+  if (summary_line.length > 0) {
+    footer_lines.push(summary_line);
+  }
+
+  footer_lines.push(...hints.map((hint) => ansi.gray(hint)));
+
+  return footer_lines.join('\n');
+}
+
+/**
+ * @param {{ limit: number, offset: number, total_count: number }} summary
+ * @returns {boolean}
+ */
+function shouldRenderQuerySummary(summary) {
+  return summary.offset > 0 || summary.total_count > summary.limit;
+}