patram 0.7.0 → 0.9.0

package/lib/{layout-stored-queries.js → output/layout-stored-queries.js}

@@ -3,7 +3,7 @@
  * @import { OutputStoredQueryItem } from './output-view.types.ts';
  */
 
-import { parseWhereClause } from './parse-where-clause.js';
+import { parseWhereClause } from '../graph/query/parse.js';
 
 const MAX_STORED_QUERY_WIDTH = 100;
 const MIN_TERM_COLUMN_WIDTH = 20;
@@ -96,7 +96,7 @@ function createStoredQueryPhrases(where_clause) {
 }
 
 /**
- * @param {import('./parse-where-clause.types.ts').ParsedExpression} expression
+ * @param {import('../graph/parse-where-clause.types.ts').ParsedExpression} expression
  * @returns {StoredQuerySegment[][]}
  */
 function createExpressionPhrases(expression) {
@@ -114,7 +114,7 @@ function createExpressionPhrases(expression) {
 }
 
 /**
- * @param {import('./parse-where-clause.types.ts').ParsedExpression} expression
+ * @param {import('../graph/parse-where-clause.types.ts').ParsedExpression} expression
  * @param {'and' | 'or'} operator
  * @param {boolean} should_prefix_operator
  * @returns {StoredQuerySegment[]}
@@ -139,7 +139,7 @@ function createExpressionPhrase(expression, operator, should_prefix_operator) {
 }
 
 /**
- * @param {import('./parse-where-clause.types.ts').ParsedExpression} expression
+ * @param {import('../graph/parse-where-clause.types.ts').ParsedExpression} expression
  * @param {number} parent_precedence
  * @returns {StoredQuerySegment[]}
  */
@@ -159,7 +159,7 @@ function createExpressionSegments(expression, parent_precedence) {
 }
 
 /**
- * @param {import('./parse-where-clause.types.ts').ParsedExpression} expression
+ * @param {import('../graph/parse-where-clause.types.ts').ParsedExpression} expression
  * @returns {StoredQuerySegment[]}
  */
 function createRawExpressionSegments(expression) {
@@ -202,7 +202,7 @@ function createRawExpressionSegments(expression) {
 }
 
 /**
- * @param {import('./parse-where-clause.types.ts').ParsedExpression} expression
+ * @param {import('../graph/parse-where-clause.types.ts').ParsedExpression} expression
  * @returns {number}
  */
 function getExpressionPrecedence(expression) {
@@ -230,7 +230,7 @@ function getBooleanExpressionPrecedence(operator) {
 }
 
 /**
- * @param {import('./parse-where-clause.types.ts').ParsedTerm} term
+ * @param {import('../graph/parse-where-clause.types.ts').ParsedTerm} term
  * @returns {StoredQuerySegment[]}
  */
 function createTermSegments(term) {
@@ -265,7 +265,7 @@ function createTermSegments(term) {
 }
 
 /**
- * @param {import('./parse-where-clause.types.ts').ParsedFieldSetTerm} term
+ * @param {import('../graph/parse-where-clause.types.ts').ParsedFieldSetTerm} term
  * @returns {StoredQuerySegment[]}
  */
 function createFieldSetSegments(term) {
@@ -281,7 +281,7 @@ function createFieldSetSegments(term) {
 }
 
 /**
- * @param {import('./parse-where-clause.types.ts').ParsedAggregateTerm} term
+ * @param {import('../graph/parse-where-clause.types.ts').ParsedAggregateTerm} term
  * @returns {StoredQuerySegment[]}
  */
 function createAggregateSegments(term) {

package/lib/{list-queries.js → output/list-queries.js}

@@ -1,5 +1,5 @@
 /**
- * @import { StoredQueryConfig } from './load-patram-config.types.ts';
+ * @import { StoredQueryConfig } from '../config/load-patram-config.types.ts';
  */
 
 /**

package/lib/{render-check-output.js → output/render-check-output.js}

@@ -1,5 +1,5 @@
 /**
- * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ * @import { PatramDiagnostic } from '../config/load-patram-config.types.ts';
  * @import { ResolvedOutputMode } from './output-view.types.ts';
  */
 

package/lib/{render-field-discovery.js → output/render-field-discovery.js}

@@ -1,6 +1,6 @@
 /**
  * @import { ResolvedOutputMode } from './output-view.types.ts';
- * @import { FieldDiscoveryResult, FieldDiscoverySuggestion } from './discover-fields.types.ts';
+ * @import { FieldDiscoveryResult, FieldDiscoverySuggestion } from '../scan/discover-fields.types.ts';
  */
 
 import { Ansis } from 'ansis';
@@ -135,7 +135,7 @@ function formatTextFieldSuggestion(field_suggestion, render_options) {
 
 /**
  * @param {string} section_title
- * @param {import('./discover-fields.types.ts').FieldDiscoveryEvidenceReference[]} evidence_references
+ * @param {import('../scan/discover-fields.types.ts').FieldDiscoveryEvidenceReference[]} evidence_references
  * @param {{ header: (value: string) => string, label: (value: string) => string }} render_options
  * @returns {string[]}
  */
@@ -168,7 +168,7 @@ function formatTextEvidenceSection(
 }
 
 /**
- * @param {import('./discover-fields.types.ts').FieldDiscoveryEvidenceReference} evidence_reference
+ * @param {import('../scan/discover-fields.types.ts').FieldDiscoveryEvidenceReference} evidence_reference
  * @returns {string}
  */
 function formatEvidenceReference(evidence_reference) {

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

@@ -0,0 +1,56 @@
+/**
+ * @import { ParsedCliArguments } from '../cli/arguments.types.ts';
+ * @import { ResolvedOutputMode, OutputView } from './output-view.types.ts';
+ */
+
+import { renderJsonOutput } from './renderers/json.js';
+import { renderPlainOutput } from './renderers/plain.js';
+import { renderRichOutput } from './renderers/rich.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}
+ */
+
+export {
+  createOutputView,
+  createRefsOutputView,
+  createShowOutputView,
+} from './view-model/index.js';
+
+/**
+ * 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,
+  });
+}

package/lib/{render-json-output.js → output/renderers/json.js}

@@ -1,5 +1,5 @@
 /**
- * @import { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView } from './output-view.types.ts';
+ * @import { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView } from '../output-view.types.ts';
  */
 
 /**
@@ -10,54 +10,113 @@
  */
 export function renderJsonOutput(output_view) {
   if (output_view.command === 'query') {
-    return `${JSON.stringify(
-      {
-        results: output_view.items.map(formatJsonQueryItem),
-        summary: {
-          shown_count: output_view.summary.count,
-          total_count: output_view.summary.total_count,
-          offset: output_view.summary.offset,
-          limit: output_view.summary.limit,
-        },
-        hints: output_view.hints,
-      },
-      null,
-      2,
-    )}\n`;
+    return renderJsonQueryOutput(output_view);
   }
 
   if (output_view.command === 'queries') {
-    return `${JSON.stringify(
-      {
-        queries: output_view.items.map(formatJsonStoredQuery),
-      },
-      null,
-      2,
-    )}\n`;
+    return renderJsonQueriesOutput(output_view.items);
+  }
+
+  if (output_view.command === 'refs') {
+    return renderJsonRefsOutput(output_view);
   }
 
   if (output_view.command === 'show') {
-    return `${JSON.stringify(
-      {
-        document: output_view.document
-          ? formatJsonShowDocument(output_view.document)
-          : undefined,
-        source: output_view.source,
-        resolved_links: output_view.items.map(formatJsonResolvedLink),
-      },
-      null,
-      2,
-    )}\n`;
+    return renderJsonShowOutput(output_view);
   }
 
   throw new Error('Unsupported output view command.');
 }
 
+/**
+ * @param {Extract<OutputView, { command: 'query' }>} output_view
+ * @returns {string}
+ */
+function renderJsonQueryOutput(output_view) {
+  return `${JSON.stringify(
+    {
+      results: output_view.items.map(formatJsonQueryItem),
+      summary: {
+        shown_count: output_view.summary.count,
+        total_count: output_view.summary.total_count,
+        offset: output_view.summary.offset,
+        limit: output_view.summary.limit,
+      },
+      hints: output_view.hints,
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+/**
+ * @param {OutputStoredQueryItem[]} output_items
+ * @returns {string}
+ */
+function renderJsonQueriesOutput(output_items) {
+  return `${JSON.stringify(
+    {
+      queries: output_items.map(formatJsonStoredQuery),
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+/**
+ * @param {Extract<OutputView, { command: 'refs' }>} output_view
+ * @returns {string}
+ */
+function renderJsonRefsOutput(output_view) {
+  return `${JSON.stringify(
+    {
+      node: formatJsonNodeItem(output_view.node),
+      incoming: Object.fromEntries(
+        Object.entries(output_view.incoming).map(
+          ([relation_name, output_items]) => [
+            relation_name,
+            output_items.map(formatJsonNodeItem),
+          ],
+        ),
+      ),
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+/**
+ * @param {Extract<OutputView, { command: 'show' }>} output_view
+ * @returns {string}
+ */
+function renderJsonShowOutput(output_view) {
+  return `${JSON.stringify(
+    {
+      document: output_view.document
+        ? formatJsonNodeItem(output_view.document)
+        : undefined,
+      incoming_summary: output_view.incoming_summary,
+      source: output_view.source,
+      resolved_links: output_view.items.map(formatJsonResolvedLink),
+    },
+    null,
+    2,
+  )}\n`;
+}
+
 /**
  * @param {OutputNodeItem} output_item
  * @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) {
+  return formatJsonNodeItem(output_item);
+}
+
+/**
+ * @param {OutputNodeItem} output_item
+ * @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 formatJsonNodeItem(output_item) {
   /** @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 = {
     $class: output_item.node_kind,
@@ -128,33 +187,3 @@ function formatJsonResolvedLink(output_item) {
 
   return resolved_link;
 }
-
-/**
- * @param {OutputNodeItem} output_item
- * @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 {{ '$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 = {
-    $class: output_item.node_kind,
-    $id: output_item.id,
-    fields: output_item.fields,
-    title: output_item.title,
-  };
-
-  if (output_item.path) {
-    document_summary.$path = output_item.path;
-  }
-
-  if (output_item.derived_summary) {
-    document_summary.derived_summary = output_item.derived_summary.name;
-    document_summary.derived = Object.fromEntries(
-      output_item.derived_summary.fields.map((field) => [
-        field.name,
-        field.value,
-      ]),
-    );
-  }
-
-  return document_summary;
-}

package/lib/{render-plain-output.js → output/renderers/plain.js}

@@ -1,14 +1,16 @@
 /**
- * @import { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView, QueryOutputView, ShowOutputView } from './output-view.types.ts';
+ * @import { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView, QueryOutputView, RefsOutputView, 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';
+} from '../format-output-metadata.js';
+import { formatNodeHeader } from '../format-node-header.js';
+import { formatOutputItemBlock } from '../format-output-item-block.js';
+import { layoutIncomingReferenceLines } from '../layout-incoming-references.js';
+import { layoutIncomingSummaryLines } from '../layout-incoming-summary-lines.js';
+import { layoutStoredQueries } from '../layout-stored-queries.js';
 
 /**
  * Render the canonical plain output for one output view.
@@ -25,6 +27,10 @@ export function renderPlainOutput(output_view) {
     return renderPlainStoredQueries(output_view.items);
   }
 
+  if (output_view.command === 'refs') {
+    return renderPlainRefsOutput(output_view);
+  }
+
   if (output_view.command === 'show') {
     return renderPlainShowOutput(output_view);
   }
@@ -85,8 +91,13 @@ function renderPlainShowOutput(output_view) {
   const document_summary = output_view.document
     ? formatPlainNodeItem(output_view.document)
     : '';
+  const incoming_summary = renderPlainIncomingSummary(output_view);
 
-  if (document_summary.length === 0 && output_view.items.length === 0) {
+  if (
+    document_summary.length === 0 &&
+    output_view.items.length === 0 &&
+    incoming_summary.length === 0
+  ) {
     return `${rendered_source}\n`;
   }
 
@@ -99,7 +110,28 @@ function renderPlainShowOutput(output_view) {
 
   summary_items.push(...output_view.items.map(formatPlainResolvedLinkItem));
 
-  return `${rendered_source}\n\n----------------\n${summary_items.join('\n\n')}\n`;
+  const summary_blocks = summary_items.filter((summary_item) => summary_item);
+
+  if (incoming_summary.length > 0) {
+    summary_blocks.push(incoming_summary);
+  }
+
+  return `${rendered_source}\n\n----------------\n${summary_blocks.join('\n\n')}\n`;
+}
+
+/**
+ * @param {RefsOutputView} output_view
+ * @returns {string}
+ */
+function renderPlainRefsOutput(output_view) {
+  const node_summary = formatPlainNodeItem(output_view.node);
+  const output_lines = layoutIncomingReferenceLines(output_view.incoming);
+
+  if (output_lines.length === 0) {
+    return `${node_summary}\n\nNo incoming references.\n`;
+  }
+
+  return `${node_summary}\n\n${output_lines.join('\n')}\n`;
 }
 
 /**
@@ -135,6 +167,29 @@ function formatPlainResolvedLinkItem(output_item) {
   });
 }
 
+/**
+ * @param {ShowOutputView} output_view
+ * @returns {string}
+ */
+function renderPlainIncomingSummary(output_view) {
+  if (!hasIncomingSummary(output_view.incoming_summary)) {
+    return '';
+  }
+
+  const output_lines = layoutIncomingSummaryLines(output_view.incoming_summary);
+  output_lines.push('', `Hint: patram refs ${output_view.path}`);
+
+  return output_lines.join('\n');
+}
+
+/**
+ * @param {Record<string, number>} incoming_summary
+ * @returns {boolean}
+ */
+function hasIncomingSummary(incoming_summary) {
+  return Object.keys(incoming_summary).length > 0;
+}
+
 /**
  * @param {string} value
  * @returns {string}

package/lib/{render-rich-output.js → output/renderers/rich.js}

@@ -1,6 +1,6 @@
 /**
- * @import { CliColorMode } from './parse-cli-arguments.types.ts';
- * @import { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView, QueryOutputView, ShowOutputView } from './output-view.types.ts';
+ * @import { CliColorMode } from '../../cli/arguments.types.ts';
+ * @import { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView, QueryOutputView, RefsOutputView, ShowOutputView } from '../output-view.types.ts';
  */
 
 import { Ansis } from 'ansis';
@@ -8,11 +8,13 @@ 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';
+} from '../format-output-metadata.js';
+import { formatNodeHeader } from '../format-node-header.js';
+import { formatOutputItemBlock } from '../format-output-item-block.js';
+import { layoutIncomingReferenceLines } from '../layout-incoming-references.js';
+import { layoutIncomingSummaryLines } from '../layout-incoming-summary-lines.js';
+import { layoutStoredQueries } from '../layout-stored-queries.js';
+import { renderRichSource } from '../rich-source/render.js';
 
 const FULL_WIDTH_DIVIDER = ` ${'─'.repeat(78)} `;
 
@@ -34,6 +36,9 @@ export async function renderRichOutput(output_view, render_options) {
     return renderRichStoredQueries(output_view.items, ansi);
   }
 
+  if (output_view.command === 'refs') {
+    return renderRichRefsOutput(output_view, ansi);
+  }
   if (output_view.command === 'show') {
     return renderRichShowOutput(output_view, render_options, ansi);
   }
@@ -105,8 +110,13 @@ async function renderRichShowOutput(output_view, render_options, ansi) {
   const document_summary = output_view.document
     ? formatRichNodeItem(output_view.document, ansi)
     : '';
+  const incoming_summary = renderRichIncomingSummary(output_view, ansi);
 
-  if (document_summary.length === 0 && output_view.items.length === 0) {
+  if (
+    document_summary.length === 0 &&
+    output_view.items.length === 0 &&
+    incoming_summary.length === 0
+  ) {
     return `${rendered_source}\n`;
   }
 
@@ -121,9 +131,34 @@ async function renderRichShowOutput(output_view, render_options, ansi) {
     ...output_view.items.map((item) => formatRichResolvedLinkItem(item, ansi)),
   );
 
+  if (incoming_summary.length > 0) {
+    summary_items.push(incoming_summary);
+  }
+
   return `${rendered_source}\n\n${ansi.gray(FULL_WIDTH_DIVIDER)}\n\n${summary_items.join('\n\n')}\n`;
 }
 
+/**
+ * @param {RefsOutputView} output_view
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function renderRichRefsOutput(output_view, ansi) {
+  const node_summary = formatRichNodeItem(output_view.node, ansi);
+  const output_lines = layoutIncomingReferenceLines(output_view.incoming, {
+    format_node_header(output_item) {
+      return ansi.green(formatNodeHeader(output_item));
+    },
+    format_relation_header(relation_name, relation_count) {
+      return `${ansi.bold(relation_name)} ${ansi.gray(`(${relation_count})`)}`;
+    },
+  });
+
+  return output_lines.length === 0
+    ? `${node_summary}\n\n${ansi.yellow('No incoming references.')}\n`
+    : `${node_summary}\n\n${output_lines.join('\n')}\n`;
+}
+
 /**
  * @param {OutputNodeItem} output_item
  * @param {Ansis} ansi
@@ -162,6 +197,32 @@ function formatRichResolvedLinkItem(output_item, ansi) {
   });
 }
 
+/**
+ * @param {ShowOutputView} output_view
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function renderRichIncomingSummary(output_view, ansi) {
+  if (!hasIncomingSummary(output_view.incoming_summary)) {
+    return '';
+  }
+
+  const output_lines = layoutIncomingSummaryLines(output_view.incoming_summary);
+  output_lines[0] = ansi.bold(output_lines[0]);
+
+  output_lines.push('', ansi.gray(`Hint: patram refs ${output_view.path}`));
+
+  return output_lines.join('\n');
+}
+
+/**
+ * @param {Record<string, number>} incoming_summary
+ * @returns {boolean}
+ */
+function hasIncomingSummary(incoming_summary) {
+  return Object.keys(incoming_summary).length > 0;
+}
+
 /**
  * @param {boolean} color_enabled
  * @returns {Ansis}

package/lib/{resolve-check-target.js → output/resolve-check-target.js}

@@ -1,5 +1,5 @@
 /**
- * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ * @import { PatramDiagnostic } from '../config/load-patram-config.types.ts';
  */
 import { access, stat } from 'node:fs/promises';
 import { dirname, relative, resolve } from 'node:path';

package/lib/{render-rich-source.js → output/rich-source/render.js}

@@ -2,8 +2,8 @@
 /**
  * @import { ComarkElement, ComarkNode } from 'md4x';
  * @import { BundledLanguage } from 'shiki';
- * @import { CliColorMode } from './parse-cli-arguments.types.ts';
- * @import { OutputResolvedLinkItem, ShowOutputView } from './output-view.types.ts';
+ * @import { CliColorMode } from '../../cli/arguments.types.ts';
+ * @import { OutputResolvedLinkItem, ShowOutputView } from '../output-view.types.ts';
  */
 
 import { extname } from 'node:path';
@@ -969,8 +969,8 @@ function shouldRenderListItemGap(previous_item, next_item, has_blank_line_gap) {
   }
 
   return (
-    isSimpleTopLevelListItem(previous_item) &&
-    isSimpleTopLevelListItem(next_item)
+    isSingleParagraphTopLevelListItem(previous_item) &&
+    isSingleParagraphTopLevelListItem(next_item)
   );
 }
 
@@ -978,7 +978,7 @@ function shouldRenderListItemGap(previous_item, next_item, has_blank_line_gap) {
  * @param {ComarkElement} item_node
  * @returns {boolean}
  */
-function isSimpleTopLevelListItem(item_node) {
+function isSingleParagraphTopLevelListItem(item_node) {
   const item_children = getElementChildren(item_node);
 
   if (item_children.length !== 1) {
@@ -994,7 +994,7 @@ function isSimpleTopLevelListItem(item_node) {
     return false;
   }
 
-  return !extractInlineText(getElementChildren(paragraph_node)).includes('\n');
+  return true;
 }
 
 /**