patram 0.10.0 → 0.12.0

package/lib/output/layout-incoming-references.js

@@ -1,22 +1,26 @@
 /**
- * @import { OutputNodeItem } from './output-view.types.ts';
+ * @import { RefsOutputView, OutputNodeItem } from './output-view.types.ts';
  */
 
-import { formatOutputNodeMetadataRows } from './format-output-metadata.js';
+import { formatCompactMetadataLabel } from './compact-layout.js';
 import { formatNodeHeader } from './format-node-header.js';
-import { formatOutputItemBlock } from './format-output-item-block.js';
+import { formatOutputNodeStoredMetadataRow } from './format-output-metadata.js';
+
+const INCOMING_TREE_PREFIX_WIDTH = 5;
 
 /**
  * Layout grouped incoming references as plain text lines.
  *
  * @param {Record<string, OutputNodeItem[]>} incoming
  * @param {{
+ *   format_node_block?: (output_item: OutputNodeItem) => string,
  *   format_node_header?: (output_item: OutputNodeItem) => string,
  *   format_relation_header?: (relation_name: string, relation_count: number) => string,
  * }} layout_options
  * @returns {string[]}
  */
 export function layoutIncomingReferenceLines(incoming, layout_options = {}) {
+  const formatNodeBlock = layout_options.format_node_block;
   const formatNodeHeader =
     layout_options.format_node_header ?? defaultNodeHeaderFormatter;
   const formatRelationHeader =
@@ -35,13 +39,51 @@ export function layoutIncomingReferenceLines(incoming, layout_options = {}) {
       formatRelationHeader(relation_name, relation_sources.length),
     );
     output_lines.push(
-      ...layoutIncomingRelationSources(relation_sources, formatNodeHeader),
+      ...layoutIncomingRelationSources(
+        relation_sources,
+        formatNodeBlock ?? createDefaultNodeBlockFormatter(formatNodeHeader),
+      ),
     );
   }
 
   return output_lines;
 }
 
+/**
+ * @param {RefsOutputView} output_view
+ * @returns {string[]}
+ */
+export function collectIncomingRefHeaders(output_view) {
+  /** @type {string[]} */
+  const headers = [formatNodeHeader(output_view.node)];
+
+  for (const incoming_items of Object.values(output_view.incoming)) {
+    for (const output_item of incoming_items) {
+      headers.push(formatNodeHeader(output_item));
+    }
+  }
+
+  return headers;
+}
+
+/**
+ * @param {{ is_tty?: boolean, terminal_width?: number }} render_options
+ * @returns {{ is_tty?: boolean, terminal_width?: number }}
+ */
+export function createIncomingTreeRenderOptions(render_options) {
+  if (typeof render_options.terminal_width !== 'number') {
+    return render_options;
+  }
+
+  return {
+    ...render_options,
+    terminal_width: Math.max(
+      1,
+      render_options.terminal_width - INCOMING_TREE_PREFIX_WIDTH,
+    ),
+  };
+}
+
 /**
  * @param {OutputNodeItem} output_item
  * @returns {string}
@@ -61,21 +103,18 @@ function defaultRelationHeaderFormatter(relation_name, relation_count) {
 
 /**
  * @param {OutputNodeItem[]} relation_sources
- * @param {(output_item: OutputNodeItem) => string} format_node_header
+ * @param {(output_item: OutputNodeItem) => string} format_node_block
  * @returns {string[]}
  */
-function layoutIncomingRelationSources(relation_sources, format_node_header) {
+function layoutIncomingRelationSources(relation_sources, format_node_block) {
   /** @type {string[]} */
   const output_lines = [];
 
   for (const [item_index, output_item] of relation_sources.entries()) {
-    if (item_index > 0) {
-      output_lines.push('');
-    }
-
     output_lines.push(
-      ...indentIncomingNodeBlock(
-        formatIncomingNodeBlock(output_item, format_node_header),
+      ...layoutIncomingNodeBlock(
+        format_node_block(output_item),
+        item_index === relation_sources.length - 1,
       ),
     );
   }
@@ -89,17 +128,60 @@ function layoutIncomingRelationSources(relation_sources, format_node_header) {
  * @returns {string}
  */
 function formatIncomingNodeBlock(output_item, format_node_header) {
-  return formatOutputItemBlock({
-    header: format_node_header(output_item),
-    metadata_rows: formatOutputNodeMetadataRows(output_item),
-    title: output_item.title,
-  });
+  const stored_metadata_row = formatOutputNodeStoredMetadataRow(output_item);
+  const metadata_label = stored_metadata_row
+    ? formatCompactMetadataLabel([stored_metadata_row])
+    : undefined;
+  const header = metadata_label
+    ? `${format_node_header(output_item)}  ${metadata_label}`
+    : format_node_header(output_item);
+  /** @type {string[]} */
+  const output_lines = [header];
+
+  output_lines.push(output_item.title);
+
+  if (output_item.description) {
+    output_lines.push(...output_item.description.split('\n'));
+  }
+
+  return output_lines.join('\n');
+}
+
+/**
+ * @param {(output_item: OutputNodeItem) => string} format_node_header
+ * @returns {(output_item: OutputNodeItem) => string}
+ */
+function createDefaultNodeBlockFormatter(format_node_header) {
+  return (output_item) =>
+    formatIncomingNodeBlock(output_item, format_node_header);
 }
 
 /**
  * @param {string} block
+ * @param {boolean} is_last_item
  * @returns {string[]}
  */
-function indentIncomingNodeBlock(block) {
-  return block.split('\n').map((line) => (line.length > 0 ? `  ${line}` : ''));
+function layoutIncomingNodeBlock(block, is_last_item) {
+  const header_prefix = is_last_item ? '  └─ ' : '  ├─ ';
+  const continuation_prefix = is_last_item ? '       ' : '  │    ';
+
+  return block.split('\n').map((line, line_index) => {
+    if (line_index === 0) {
+      return `${header_prefix}${line}`;
+    }
+
+    if (line.length === 0) {
+      return '';
+    }
+
+    return `${continuation_prefix}${trimIncomingContinuationIndent(line)}`;
+  });
+}
+
+/**
+ * @param {string} line
+ * @returns {string}
+ */
+function trimIncomingContinuationIndent(line) {
+  return line.startsWith('  ') ? line.slice(2) : line;
 }

package/lib/output/layout-stored-queries.js

@@ -1,14 +1,7 @@
-/* eslint-disable max-lines */
 /**
  * @import { OutputStoredQueryItem } from './output-view.types.ts';
  */
 
-import { parseWhereClause } from '../graph/query/parse.js';
-
-const MAX_STORED_QUERY_WIDTH = 100;
-const MIN_TERM_COLUMN_WIDTH = 20;
-const STORED_QUERY_COLUMN_GAP = 2;
-
 /**
  * @typedef {'description' | 'field_name' | 'keyword' | 'literal' | 'name' | 'operator' | 'plain'} StoredQuerySegmentKind
  */
@@ -18,336 +11,29 @@ const STORED_QUERY_COLUMN_GAP = 2;
  */
 
 /**
- * Layout stored queries into styled lines shared by plain and rich renderers.
- *
- * @param {OutputStoredQueryItem[]} output_items
+ * @param {string} where_clause
+ * @param {number} first_line_width
+ * @param {number} continuation_width
  * @returns {StoredQuerySegment[][]}
  */
-export function layoutStoredQueries(output_items) {
-  if (output_items.length === 0) {
-    return [];
-  }
-
-  const name_column_width = Math.max(
-    ...output_items.map((output_item) => output_item.name.length),
-  );
-  const term_column_width = Math.max(
-    MIN_TERM_COLUMN_WIDTH,
-    MAX_STORED_QUERY_WIDTH - name_column_width - STORED_QUERY_COLUMN_GAP,
-  );
-
-  return output_items.flatMap((output_item) =>
-    layoutStoredQuery(output_item, name_column_width, term_column_width),
+export function layoutStoredQueryRow(
+  where_clause,
+  first_line_width,
+  continuation_width,
+) {
+  return wrapPhrasesWithLineWidths(
+    createStoredQueryPhrases(where_clause),
+    first_line_width,
+    continuation_width,
   );
 }
 
-/**
- * @param {OutputStoredQueryItem} output_item
- * @param {number} name_column_width
- * @param {number} term_column_width
- * @returns {StoredQuerySegment[][]}
- */
-function layoutStoredQuery(output_item, name_column_width, term_column_width) {
-  const term_lines = wrapPhrases(
-    createStoredQueryPhrases(output_item.where),
-    term_column_width,
-  );
-  const continuation_prefix = ' '.repeat(
-    name_column_width + STORED_QUERY_COLUMN_GAP,
-  );
-
-  /** @type {StoredQuerySegment[][]} */
-  const output_lines = term_lines.map((line_segments, line_index) => {
-    if (line_index === 0) {
-      return [
-        {
-          kind: 'name',
-          text: output_item.name.padEnd(name_column_width, ' '),
-        },
-        {
-          kind: 'plain',
-          text: ' '.repeat(STORED_QUERY_COLUMN_GAP),
-        },
-        ...line_segments,
-      ];
-    }
-
-    return [
-      {
-        kind: 'plain',
-        text: continuation_prefix,
-      },
-      ...line_segments,
-    ];
-  });
-
-  if (output_item.description) {
-    for (const description_line of output_item.description.split('\n')) {
-      output_lines.push([
-        {
-          kind: 'description',
-          text: `${' '.repeat(name_column_width + STORED_QUERY_COLUMN_GAP)}${description_line}`,
-        },
-      ]);
-    }
-  }
-
-  output_lines.push([]);
-
-  return output_lines;
-}
-
 /**
  * @param {string} where_clause
  * @returns {StoredQuerySegment[][]}
  */
 function createStoredQueryPhrases(where_clause) {
-  const parse_result = parseWhereClause(where_clause);
-
-  if (!parse_result.success) {
-    return createFallbackPhrases(where_clause);
-  }
-
-  return createExpressionPhrases(parse_result.expression);
-}
-
-/**
- * @param {import('../graph/parse-where-clause.types.ts').ParsedExpression} expression
- * @returns {StoredQuerySegment[][]}
- */
-function createExpressionPhrases(expression) {
-  if (expression.kind !== 'and' && expression.kind !== 'or') {
-    return [[...createExpressionSegments(expression, 0)]];
-  }
-
-  return expression.expressions.map((subexpression, expression_index) =>
-    createExpressionPhrase(
-      subexpression,
-      expression.kind,
-      expression_index > 0,
-    ),
-  );
-}
-
-/**
- * @param {import('../graph/parse-where-clause.types.ts').ParsedExpression} expression
- * @param {'and' | 'or'} operator
- * @param {boolean} should_prefix_operator
- * @returns {StoredQuerySegment[]}
- */
-function createExpressionPhrase(expression, operator, should_prefix_operator) {
-  /** @type {StoredQuerySegment[]} */
-  const phrase = [];
-
-  if (should_prefix_operator) {
-    phrase.push({ kind: 'keyword', text: operator });
-    phrase.push({ kind: 'plain', text: ' ' });
-  }
-
-  phrase.push(
-    ...createExpressionSegments(
-      expression,
-      getBooleanExpressionPrecedence(operator),
-    ),
-  );
-
-  return phrase;
-}
-
-/**
- * @param {import('../graph/parse-where-clause.types.ts').ParsedExpression} expression
- * @param {number} parent_precedence
- * @returns {StoredQuerySegment[]}
- */
-function createExpressionSegments(expression, parent_precedence) {
-  const expression_precedence = getExpressionPrecedence(expression);
-  const expression_segments = createRawExpressionSegments(expression);
-
-  if (expression_precedence >= parent_precedence) {
-    return expression_segments;
-  }
-
-  return [
-    { kind: 'operator', text: '(' },
-    ...expression_segments,
-    { kind: 'operator', text: ')' },
-  ];
-}
-
-/**
- * @param {import('../graph/parse-where-clause.types.ts').ParsedExpression} expression
- * @returns {StoredQuerySegment[]}
- */
-function createRawExpressionSegments(expression) {
-  if (expression.kind === 'and' || expression.kind === 'or') {
-    return expression.expressions.flatMap((subexpression, expression_index) => {
-      const subexpression_segments = createExpressionSegments(
-        subexpression,
-        getExpressionPrecedence(expression),
-      );
-
-      if (expression_index === 0) {
-        return subexpression_segments;
-      }
-
-      return [
-        { kind: 'plain', text: ' ' },
-        { kind: 'keyword', text: expression.kind },
-        { kind: 'plain', text: ' ' },
-        ...subexpression_segments,
-      ];
-    });
-  }
-
-  if (expression.kind === 'not') {
-    return [
-      { kind: 'keyword', text: 'not' },
-      { kind: 'plain', text: ' ' },
-      ...createExpressionSegments(
-        expression.expression,
-        getExpressionPrecedence(expression),
-      ),
-    ];
-  }
-
-  if (expression.kind === 'term') {
-    return createTermSegments(expression.term);
-  }
-
-  throw new Error('Unsupported stored-query expression.');
-}
-
-/**
- * @param {import('../graph/parse-where-clause.types.ts').ParsedExpression} expression
- * @returns {number}
- */
-function getExpressionPrecedence(expression) {
-  if (expression.kind === 'or') {
-    return 1;
-  }
-
-  if (expression.kind === 'and') {
-    return 2;
-  }
-
-  if (expression.kind === 'not') {
-    return 3;
-  }
-
-  return 4;
-}
-
-/**
- * @param {'and' | 'or'} operator
- * @returns {number}
- */
-function getBooleanExpressionPrecedence(operator) {
-  return operator === 'or' ? 1 : 2;
-}
-
-/**
- * @param {import('../graph/parse-where-clause.types.ts').ParsedTerm} term
- * @returns {StoredQuerySegment[]}
- */
-function createTermSegments(term) {
-  if (term.kind === 'aggregate') {
-    return createAggregateSegments(term);
-  }
-
-  if (term.kind === 'field') {
-    return [
-      { kind: 'field_name', text: term.field_name },
-      { kind: 'operator', text: term.operator },
-      { kind: 'literal', text: term.value },
-    ];
-  }
-
-  if (term.kind === 'field_set') {
-    return createFieldSetSegments(term);
-  }
-
-  if (term.kind === 'relation_target') {
-    return [
-      { kind: 'field_name', text: term.relation_name },
-      { kind: 'operator', text: '=' },
-      { kind: 'literal', text: term.target_id },
-    ];
-  }
-
-  return [
-    { kind: 'field_name', text: term.relation_name },
-    { kind: 'operator', text: ':*' },
-  ];
-}
-
-/**
- * @param {import('../graph/parse-where-clause.types.ts').ParsedFieldSetTerm} term
- * @returns {StoredQuerySegment[]}
- */
-function createFieldSetSegments(term) {
-  return [
-    { kind: 'field_name', text: term.field_name },
-    { kind: 'plain', text: ' ' },
-    { kind: 'operator', text: term.operator },
-    { kind: 'plain', text: ' ' },
-    { kind: 'operator', text: '[' },
-    ...createListSegments(term.values),
-    { kind: 'operator', text: ']' },
-  ];
-}
-
-/**
- * @param {import('../graph/parse-where-clause.types.ts').ParsedAggregateTerm} term
- * @returns {StoredQuerySegment[]}
- */
-function createAggregateSegments(term) {
-  /** @type {StoredQuerySegment[]} */
-  const segments = [
-    { kind: 'field_name', text: term.aggregate_name },
-    { kind: 'operator', text: '(' },
-    ...createTraversalSegments(term.traversal),
-    { kind: 'operator', text: ', ' },
-    ...createExpressionSegments(term.expression, 0),
-    { kind: 'operator', text: ')' },
-  ];
-
-  if (term.aggregate_name === 'count') {
-    segments.push({ kind: 'plain', text: ' ' });
-    segments.push({ kind: 'operator', text: term.comparison ?? '=' });
-    segments.push({ kind: 'plain', text: ' ' });
-    segments.push({ kind: 'literal', text: String(term.value ?? 0) });
-  }
-
-  return segments;
-}
-
-/**
- * @param {{ direction: 'in' | 'out', relation_name: string }} traversal
- * @returns {StoredQuerySegment[]}
- */
-function createTraversalSegments(traversal) {
-  return [
-    { kind: 'field_name', text: traversal.direction },
-    { kind: 'operator', text: ':' },
-    { kind: 'field_name', text: traversal.relation_name },
-  ];
-}
-
-/**
- * @param {string[]} values
- * @returns {StoredQuerySegment[]}
- */
-function createListSegments(values) {
-  return values.flatMap((value, value_index) => {
-    if (value_index === 0) {
-      return [{ kind: 'literal', text: value }];
-    }
-
-    return [
-      { kind: 'operator', text: ', ' },
-      { kind: 'literal', text: value },
-    ];
-  });
+  return createFallbackPhrases(where_clause);
 }
 
 /**
@@ -366,15 +52,21 @@ function createFallbackPhrases(where_clause) {
 
 /**
  * @param {StoredQuerySegment[][]} phrases
- * @param {number} term_column_width
+ * @param {number} first_line_width
+ * @param {number} continuation_width
  * @returns {StoredQuerySegment[][]}
  */
-function wrapPhrases(phrases, term_column_width) {
+function wrapPhrasesWithLineWidths(
+  phrases,
+  first_line_width,
+  continuation_width,
+) {
   /** @type {StoredQuerySegment[][]} */
   const lines = [];
   /** @type {StoredQuerySegment[]} */
   let current_line = [];
   let current_width = 0;
+  let current_line_width = first_line_width;
 
   for (const phrase of phrases) {
     const phrase_width = measureSegments(phrase);
@@ -385,10 +77,11 @@ function wrapPhrases(phrases, term_column_width) {
       continue;
     }
 
-    if (current_width + 1 + phrase_width > term_column_width) {
+    if (current_width + 1 + phrase_width > current_line_width) {
       lines.push(current_line);
       current_line = [...phrase];
       current_width = phrase_width;
+      current_line_width = continuation_width;
       continue;
     }
 

package/lib/output/list-queries.js

@@ -14,6 +14,6 @@ export function listQueries(stored_queries) {
     .map(([name, stored_query]) => ({
       description: stored_query.description,
       name,
-      where: stored_query.where,
+      where: stored_query.cypher ?? '',
     }));
 }

package/lib/output/render-field-discovery.js

@@ -42,8 +42,9 @@ function formatJsonFieldSuggestion(field_suggestion) {
     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_on: field_suggestion.likely_on,
+    likely_to: field_suggestion.likely_to,
     likely_type: field_suggestion.likely_type,
     name: field_suggestion.name,
   };
@@ -106,10 +107,18 @@ function formatTextFieldSuggestion(field_suggestion, render_options) {
   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('  likely on:')} ${field_suggestion.likely_on.types.join(', ')}`,
     `${render_options.label('  confidence:')} ${formatConfidence(field_suggestion.confidence)}`,
   );
 
+  if (field_suggestion.likely_to) {
+    lines.splice(
+      3,
+      0,
+      `${render_options.label('  likely to:')} ${field_suggestion.likely_to.type}`,
+    );
+  }
+
   if (field_suggestion.evidence_references.length > 0) {
     lines.push(
       ...formatTextEvidenceSection(

package/lib/output/render-output-view.js

@@ -13,10 +13,10 @@ import { renderRichOutput } from './renderers/rich.js';
  * 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
+ * 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}
@@ -34,23 +34,27 @@ export {
  * @param {OutputView} output_view
  * @param {ResolvedOutputMode} output_mode
  * @param {ParsedCliArguments} parsed_arguments
+ * @param {{ is_tty?: boolean, terminal_width?: number }=} render_options
  * @returns {Promise<string>}
  */
 export async function renderOutputView(
   output_view,
   output_mode,
   parsed_arguments,
+  render_options = {},
 ) {
   if (output_mode.renderer_name === 'json') {
     return renderJsonOutput(output_view);
   }
 
   if (output_mode.renderer_name === 'plain') {
-    return renderPlainOutput(output_view);
+    return renderPlainOutput(output_view, render_options);
   }
 
   return renderRichOutput(output_view, {
     color_enabled: output_mode.color_enabled,
     color_mode: parsed_arguments.color_mode,
+    is_tty: render_options.is_tty,
+    terminal_width: render_options.terminal_width,
   });
 }