patram 0.11.0 → 0.12.0

package/lib/graph/query/resolve.js

@@ -17,28 +17,10 @@ import { findCloseMatch } from '../../find-close-match.js';
  * @returns {{ success: true, value: { query_source: QuerySource, where_clause: string } } | { error: CliParseError, success: false }}
  */
 export function resolveWhereClause(repo_config, command_arguments) {
-  if (command_arguments[0] === '--where') {
-    const where_clause = command_arguments.slice(1).join(' ').trim();
-
-    if (where_clause.length === 0) {
-      return {
-        error: {
-          code: 'message',
-          message: 'Query requires a where clause.',
-        },
-        success: false,
-      };
-    }
+  const ad_hoc_result = resolveAdHocWhereClause(command_arguments);
 
-    return {
-      success: true,
-      value: {
-        query_source: {
-          kind: 'ad_hoc',
-        },
-        where_clause,
-      },
-    };
+  if (ad_hoc_result) {
+    return ad_hoc_result;
   }
 
   const stored_query_name = command_arguments[0];
@@ -47,7 +29,7 @@ export function resolveWhereClause(repo_config, command_arguments) {
     return {
       error: {
         code: 'message',
-        message: 'Query requires "--where" or a stored query name.',
+        message: 'Query requires "--cypher" or a stored query name.',
       },
       success: false,
     };
@@ -65,6 +47,18 @@ export function resolveWhereClause(repo_config, command_arguments) {
     };
   }
 
+  const query_text = stored_query.cypher;
+
+  if (!query_text) {
+    return {
+      error: {
+        code: 'message',
+        message: `Stored query "${stored_query_name}" is missing "cypher" query text.`,
+      },
+      success: false,
+    };
+  }
+
   return {
     success: true,
     value: {
@@ -72,7 +66,67 @@ export function resolveWhereClause(repo_config, command_arguments) {
         kind: 'stored_query',
         name: stored_query_name,
       },
-      where_clause: stored_query.where,
+      where_clause: query_text,
+    },
+  };
+}
+
+/**
+ * @param {string[]} command_arguments
+ * @returns {{ success: true, value: { query_source: QuerySource, where_clause: string } } | { error: CliParseError, success: false } | null}
+ */
+function resolveAdHocWhereClause(command_arguments) {
+  if (command_arguments[0] === '--cypher') {
+    return createAdHocWhereClauseResult(
+      command_arguments,
+      '--cypher',
+      'Query requires a Cypher statement.',
+    );
+  }
+
+  if (command_arguments[0] === '--where') {
+    return {
+      error: {
+        code: 'message',
+        message: 'Query requires a Cypher statement.',
+      },
+      success: false,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * @param {string[]} command_arguments
+ * @param {'--cypher'} option_name
+ * @param {string} empty_message
+ * @returns {{ success: true, value: { query_source: QuerySource, where_clause: string } } | { error: CliParseError, success: false }}
+ */
+function createAdHocWhereClauseResult(
+  command_arguments,
+  option_name,
+  empty_message,
+) {
+  const query_text = command_arguments.slice(1).join(' ').trim();
+
+  if (query_text.length === 0) {
+    return {
+      error: {
+        code: 'message',
+        message: empty_message,
+      },
+      success: false,
+    };
+  }
+
+  return {
+    success: true,
+    value: {
+      query_source: {
+        kind: 'ad_hoc',
+      },
+      where_clause: query_text,
     },
   };
 }

package/lib/output/command-output.js

@@ -15,17 +15,17 @@ import { writePagedOutput } from './write-paged-output.js';
  * Resolves the final output mode and switches between direct stdout writes and
  * interactive pager output.
  *
- * Kind: output
- * Status: active
- * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../../docs/decisions/tty-pager-output.md
+ * kind: output
+ * status: active
+ * tracked_in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * decided_by: ../../docs/decisions/tty-pager-output.md
  * @patram
  * @see {@link ./render-output-view.js}
  * @see {@link ../../docs/decisions/tty-pager-output.md}
  */
 
 /**
- * @param {{ stdout: { isTTY?: boolean, write(chunk: string): boolean }, write_paged_output?: (output_text: string) => Promise<void> }} io_context
+ * @param {{ stdout: { columns?: number, isTTY?: boolean, write(chunk: string): boolean }, write_paged_output?: (output_text: string) => Promise<void> }} io_context
  * @param {ParsedCliArguments} parsed_command
  * @param {OutputView} output_view
  * @returns {Promise<void>}
@@ -43,6 +43,13 @@ export async function writeCommandOutput(
       term: process.env.TERM,
     }),
     parsed_command,
+    {
+      is_tty: io_context.stdout.isTTY === true,
+      terminal_width:
+        io_context.stdout.isTTY === true
+          ? io_context.stdout.columns
+          : undefined,
+    },
   );
 
   await writeRenderedCommandOutput(io_context, parsed_command, rendered_output);

package/lib/output/compact-layout.js

@@ -0,0 +1,221 @@
+import wrapAnsi from 'wrap-ansi';
+
+const BODY_INDENT = '  ';
+const TITLE_COLUMN_GAP = '  ';
+
+/**
+ * @param {{ body_indent?: string, is_tty?: boolean, terminal_width?: number }} layout_options
+ * @returns {number}
+ */
+function getCompactBodyWidth(layout_options = {}) {
+  const body_indent = layout_options.body_indent ?? BODY_INDENT;
+
+  if (!hasTtyWidth(layout_options)) {
+    return Number.POSITIVE_INFINITY;
+  }
+
+  const terminal_width = /** @type {number} */ (layout_options.terminal_width);
+
+  return Math.max(1, terminal_width - body_indent.length);
+}
+
+/**
+ * @param {string[]} left_titles
+ * @returns {number}
+ */
+export function getCompactLeftTitleWidth(left_titles) {
+  if (left_titles.length === 0) {
+    return 0;
+  }
+
+  return Math.max(...left_titles.map((left_title) => left_title.length));
+}
+
+/**
+ * @param {string[]} metadata_rows
+ * @returns {string | undefined}
+ */
+export function formatCompactMetadataLabel(metadata_rows) {
+  if (metadata_rows.length === 0) {
+    return undefined;
+  }
+
+  return `(${formatCompactMetadataFields(metadata_rows).join(', ')})`;
+}
+
+/**
+ * @param {{
+ *   format_left?: (text: string) => string,
+ *   format_right?: (text: string) => string,
+ *   is_tty?: boolean,
+ *   left_title: string,
+ *   left_title_width: number,
+ *   right_title?: string,
+ *   terminal_width?: number,
+ * }} options
+ * @returns {string}
+ */
+export function formatCompactTitleRow(options) {
+  const formatLeft = options.format_left ?? identity;
+  const formatRight = options.format_right ?? identity;
+
+  if (!options.right_title) {
+    return formatLeft(options.left_title);
+  }
+
+  if (!hasTtyWidth(options)) {
+    return `${formatLeft(options.left_title)}${TITLE_COLUMN_GAP}${formatRight(options.right_title)}`;
+  }
+
+  const terminal_width = /** @type {number} */ (options.terminal_width);
+  const available_width =
+    terminal_width - options.left_title.length - TITLE_COLUMN_GAP.length;
+
+  if (available_width <= 0) {
+    return formatLeft(options.left_title);
+  }
+
+  return `${formatLeft(options.left_title)}${TITLE_COLUMN_GAP}${formatRight(truncateText(options.right_title, available_width))}`;
+}
+
+/**
+ * @param {string} text
+ * @param {{ body_indent?: string, is_tty?: boolean, terminal_width?: number }} layout_options
+ * @returns {string[]}
+ */
+export function wrapCompactBodyText(text, layout_options = {}) {
+  if (!hasTtyWidth(layout_options)) {
+    return text.split('\n');
+  }
+
+  const body_width = getCompactBodyWidth(layout_options);
+  /** @type {string[]} */
+  const lines = [];
+
+  for (const [line_index, source_line] of text.split('\n').entries()) {
+    if (line_index > 0 && source_line.length === 0) {
+      lines.push('');
+      continue;
+    }
+
+    const wrapped_line = wrapAnsi(source_line, body_width, {
+      hard: false,
+      trim: false,
+      wordWrap: true,
+    });
+
+    lines.push(...wrapped_line.split('\n'));
+  }
+
+  return lines;
+}
+
+/**
+ * @param {{ is_tty?: boolean, terminal_width?: number }} layout_options
+ * @returns {boolean}
+ */
+function hasTtyWidth(layout_options) {
+  return (
+    layout_options.is_tty === true &&
+    typeof layout_options.terminal_width === 'number' &&
+    Number.isFinite(layout_options.terminal_width) &&
+    layout_options.terminal_width > 0
+  );
+}
+
+/**
+ * @param {string} value
+ * @param {number} max_width
+ * @returns {string}
+ */
+function truncateText(value, max_width) {
+  if (value.length <= max_width) {
+    return value;
+  }
+
+  if (max_width <= 1) {
+    return '…';
+  }
+
+  if (hasEnclosingPunctuation(value, '(', ')')) {
+    return truncateEnclosedText(value, max_width, '(', ')');
+  }
+
+  if (hasEnclosingPunctuation(value, '[', ']')) {
+    return truncateEnclosedText(value, max_width, '[', ']');
+  }
+
+  return `${value.slice(0, max_width - 1)}…`;
+}
+
+/**
+ * @param {string} value
+ * @param {number} max_width
+ * @param {string} open_character
+ * @param {string} close_character
+ * @returns {string}
+ */
+function truncateEnclosedText(
+  value,
+  max_width,
+  open_character,
+  close_character,
+) {
+  if (max_width === 2) {
+    return `…${close_character}`;
+  }
+
+  if (max_width === 3) {
+    return `${open_character}…${close_character}`;
+  }
+
+  const inner_value = value.slice(1, -1);
+  const prefix_width = Math.max(0, max_width - 3);
+
+  return `${open_character}${inner_value.slice(0, prefix_width)}…${close_character}`;
+}
+
+/**
+ * @param {string[]} metadata_rows
+ * @returns {string[]}
+ */
+function formatCompactMetadataFields(metadata_rows) {
+  return metadata_rows
+    .flatMap((metadata_row) => metadata_row.split('  '))
+    .map(formatCompactMetadataField);
+}
+
+/**
+ * @param {string} metadata_field
+ * @returns {string}
+ */
+function formatCompactMetadataField(metadata_field) {
+  const separator_index = metadata_field.indexOf(': ');
+
+  if (separator_index === -1) {
+    return metadata_field;
+  }
+
+  const field_name = metadata_field.slice(0, separator_index);
+  const field_value = metadata_field.slice(separator_index + 2);
+
+  return `${field_name}=${field_value}`;
+}
+
+/**
+ * @param {string} value
+ * @param {string} open_character
+ * @param {string} close_character
+ * @returns {boolean}
+ */
+function hasEnclosingPunctuation(value, open_character, close_character) {
+  return value.startsWith(open_character) && value.endsWith(close_character);
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function identity(value) {
+  return value;
+}

package/lib/output/format-output-item-block.js

@@ -1,5 +1,5 @@
 /**
- * @param {{ header: string, metadata_rows: string[], metadata_indent?: string, title: string, title_indent?: string }} options
+ * @param {{ description?: string, header: string, metadata_rows: string[], metadata_indent?: string, title: string, title_indent?: string }} options
  * @returns {string}
  */
 export function formatOutputItemBlock(options) {
@@ -18,5 +18,35 @@ export function formatOutputItemBlock(options) {
 
   lines.push('', `${title_indent}${options.title}`);
 
+  if (options.description) {
+    lines.push(
+      '',
+      ...formatIndentedDescription(options.description, title_indent),
+    );
+  }
+
   return lines.join('\n');
 }
+
+/**
+ * @param {string} description
+ * @param {string} indent
+ * @returns {string[]}
+ */
+function formatIndentedDescription(description, indent) {
+  /** @type {string[]} */
+  const lines = [];
+  const paragraphs = description.split('\n\n');
+
+  for (const [paragraph_index, paragraph] of paragraphs.entries()) {
+    if (paragraph_index > 0) {
+      lines.push('');
+    }
+
+    for (const paragraph_line of paragraph.split('\n')) {
+      lines.push(`${indent}${paragraph_line}`);
+    }
+  }
+
+  return lines;
+}

package/lib/output/format-output-metadata.js

@@ -1,44 +1,31 @@
-import { formatDerivedSummaryRow } from './format-derived-summary-row.js';
-
 /**
  * @param {import('./output-view.types.ts').OutputNodeItem} output_item
- * @returns {string[]}
+ * @returns {string | undefined}
  */
-export function formatOutputNodeMetadataRows(output_item) {
-  /** @type {string[]} */
-  const metadata_rows = [];
-  const stored_metadata_fields =
-    output_item.visible_fields.map(formatMetadataField);
-
-  if (stored_metadata_fields.length > 0) {
-    metadata_rows.push(stored_metadata_fields.join('  '));
-  }
-
-  if (output_item.derived_summary) {
-    metadata_rows.push(formatDerivedSummaryRow(output_item.derived_summary));
-  }
-
-  return metadata_rows;
+export function formatOutputNodeStoredMetadataRow(output_item) {
+  return formatStoredMetadataRow(output_item.visible_fields);
 }
 
 /**
  * @param {import('./output-view.types.ts').OutputResolvedLinkTarget} target
- * @returns {string[]}
+ * @returns {string | undefined}
  */
-export function formatResolvedLinkMetadataRows(target) {
-  /** @type {string[]} */
-  const metadata_rows = [];
-  const stored_metadata_fields = target.visible_fields.map(formatMetadataField);
+export function formatResolvedLinkStoredMetadataRow(target) {
+  return formatStoredMetadataRow(target.visible_fields);
+}
 
-  if (stored_metadata_fields.length > 0) {
-    metadata_rows.push(stored_metadata_fields.join('  '));
-  }
+/**
+ * @param {import('./output-view.types.ts').OutputMetadataField[]} visible_fields
+ * @returns {string | undefined}
+ */
+function formatStoredMetadataRow(visible_fields) {
+  const stored_metadata_fields = visible_fields.map(formatMetadataField);
 
-  if (target.derived_summary) {
-    metadata_rows.push(formatDerivedSummaryRow(target.derived_summary));
+  if (stored_metadata_fields.length === 0) {
+    return undefined;
   }
 
-  return metadata_rows;
+  return stored_metadata_fields.join('  ');
 }
 
 /**

package/lib/output/format-stored-query-block.js

@@ -0,0 +1,95 @@
+/**
+ * @import { OutputStoredQueryItem } from './output-view.types.ts';
+ */
+
+import { wrapCompactBodyText } from './compact-layout.js';
+import { layoutStoredQueryRow } from './layout-stored-queries.js';
+
+/**
+ * @typedef {{
+ *   kind: 'description' | 'field_name' | 'keyword' | 'literal' | 'name' | 'operator' | 'plain',
+ *   text: string,
+ * }} StoredQueryLineSegment
+ */
+
+/**
+ * @param {OutputStoredQueryItem} output_item
+ * @param {{ is_tty?: boolean, terminal_width?: number }} render_options
+ * @param {{
+ *   format_description?: (text: string) => string,
+ *   format_line: (line_segments: StoredQueryLineSegment[]) => string,
+ *   format_name: (text: string) => string,
+ * }} format_options
+ * @returns {string}
+ */
+export function formatStoredQueryBlock(
+  output_item,
+  render_options,
+  format_options,
+) {
+  const row_layout = getStoredQueryRowLayout(output_item.name, render_options);
+  const formatDescription = format_options.format_description ?? identity;
+  const output_lines = layoutStoredQueryRow(
+    output_item.where,
+    row_layout.first_line_width,
+    row_layout.continuation_width,
+  ).map((line_segments, line_index) =>
+    line_index === 0
+      ? `${format_options.format_name(output_item.name)}  ${format_options.format_line(line_segments)}`
+      : `${row_layout.continuation_prefix}${format_options.format_line(line_segments)}`,
+  );
+
+  if (output_item.description) {
+    for (const description_line of wrapCompactBodyText(
+      output_item.description,
+      render_options,
+    )) {
+      output_lines.push(
+        description_line.length > 0
+          ? `  ${formatDescription(description_line)}`
+          : '',
+      );
+    }
+  }
+
+  return output_lines.join('\n');
+}
+
+/**
+ * @param {string} query_name
+ * @param {{ is_tty?: boolean, terminal_width?: number }} render_options
+ * @returns {{ continuation_prefix: string, continuation_width: number, first_line_width: number }}
+ */
+function getStoredQueryRowLayout(query_name, render_options) {
+  const continuation_prefix = ' '.repeat(query_name.length + 2);
+
+  if (
+    render_options.is_tty !== true ||
+    typeof render_options.terminal_width !== 'number'
+  ) {
+    return {
+      continuation_prefix,
+      continuation_width: Number.POSITIVE_INFINITY,
+      first_line_width: Number.POSITIVE_INFINITY,
+    };
+  }
+
+  const available_width = Math.max(
+    1,
+    render_options.terminal_width - continuation_prefix.length,
+  );
+
+  return {
+    continuation_prefix,
+    continuation_width: available_width,
+    first_line_width: available_width,
+  };
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function identity(value) {
+  return value;
+}