patram 0.7.0 → 0.8.0

package/lib/cli-help-metadata.js

@@ -50,6 +50,7 @@ export const COMMAND_NAMES = /** @type {const} */ ([
   'fields',
   'query',
   'queries',
+  'refs',
   'show',
 ]);
 
@@ -146,12 +147,12 @@ const COMMAND_DEFINITIONS = {
     ]),
     examples: [
       'patram query active-plans',
-      'patram query --where "tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md"',
-      'patram query --where "status not in [done, dropped, superseded]"',
-      'patram query --where "$class=plan and none(in:tracked_in, $class=decision)"',
-      'patram query --where "count(in:decided_by, $class=task) = 0"',
+      "patram query --where 'tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md'",
+      "patram query --where 'status not in [done, dropped, superseded]'",
+      "patram query --where '$class=plan and none(in:tracked_in, $class=decision)'",
+      "patram query --where 'count(in:decided_by, $class=task) = 0'",
       'patram query ready-tasks --explain',
-      'patram query --where "$class=decision and status=accepted and count(in:decided_by, $class=task) = 0" --lint',
+      "patram query --where '$class=decision and status=accepted and count(in:decided_by, $class=task) = 0' --lint",
       'patram query active-plans --limit 10 --offset 20',
     ],
     extra_positionals_message:
@@ -161,12 +162,12 @@ const COMMAND_DEFINITIONS = {
     min_positionals: 0,
     missing_argument_examples: [
       'patram query active-plans',
-      'patram query --where "tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md"',
+      "patram query --where 'tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md'",
     ],
-    missing_argument_label: '<name> or --where "<clause>"',
+    missing_argument_label: "<name> or --where '<clause>'",
     missing_usage_lines: [
       'patram query <name> [options]',
-      'patram query --where "<clause>" [options]',
+      "patram query --where '<clause>' [options]",
     ],
     option_column_width: 19,
     options: [
@@ -214,7 +215,7 @@ const COMMAND_DEFINITIONS = {
     ],
     usage_lines: [
       'patram query <name> [options]',
-      'patram query --where "<clause>" [options]',
+      "patram query --where '<clause>' [options]",
     ],
   },
   queries: {
@@ -243,6 +244,44 @@ const COMMAND_DEFINITIONS = {
     summary: 'List the stored queries defined in the project configuration.',
     usage_lines: ['patram queries [options]'],
   },
+  refs: {
+    allowed_option_names: new Set(['where']),
+    examples: [
+      'patram refs docs/decisions/query-language.md',
+      "patram refs docs/decisions/query-language.md --where '$class=document'",
+      'patram refs docs/decisions/query-language.md --json',
+    ],
+    extra_positionals_message: 'Refs accepts exactly one file path.',
+    help_topics: ['query-language'],
+    max_positionals: 1,
+    min_positionals: 1,
+    missing_argument_examples: [
+      'patram refs docs/decisions/query-language.md',
+      "patram refs docs/patram.md --where '$class=document'",
+    ],
+    missing_argument_label: '<file>',
+    missing_usage_lines: ['patram refs <file>'],
+    option_column_width: 19,
+    options: [
+      {
+        description: 'Filter incoming source nodes with a where clause',
+        label: '--where <clause>',
+      },
+      {
+        description: 'Print plain text output',
+        label: '--plain',
+      },
+      {
+        description: 'Print JSON output',
+        label: '--json',
+      },
+    ],
+    related: ['show', 'query'],
+    root_summary: 'Inspect incoming graph references for one file',
+    summary:
+      'Inspect incoming graph references for one file, grouped by relation.',
+    usage_lines: ['patram refs <file> [options]'],
+  },
   show: {
     allowed_option_names: new Set(),
     examples: ['patram show docs/patram.md', 'patram show lib/patram-cli.js'],

package/lib/command-output.js

@@ -78,6 +78,7 @@ export function shouldPageCommandOutput(parsed_command, output_stream) {
     output_stream.isTTY === true &&
     (parsed_command.command_name === 'fields' ||
       parsed_command.command_name === 'query' ||
+      parsed_command.command_name === 'refs' ||
       parsed_command.command_name === 'show')
   );
 }

package/lib/inspect-reverse-references.js

@@ -0,0 +1,184 @@
+/**
+ * @import { BuildGraphResult, GraphNode } from './build-graph.types.ts';
+ * @import { PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
+ */
+
+import {
+  normalizeRepoRelativePath,
+  resolveDocumentNodeId,
+} from './document-node-identity.js';
+import { queryGraph } from './query-graph.js';
+
+/**
+ * Inspect incoming graph edges for one canonical target file.
+ *
+ * @param {BuildGraphResult} graph
+ * @param {string} target_file_path
+ * @param {PatramRepoConfig | undefined} repo_config
+ * @param {string | undefined} where_clause
+ * @returns {{
+ *   diagnostics: PatramDiagnostic[],
+ *   incoming: Record<string, GraphNode[]>,
+ *   node: GraphNode,
+ * }}
+ */
+export function inspectReverseReferences(
+  graph,
+  target_file_path,
+  repo_config,
+  where_clause,
+) {
+  const normalized_target_path = normalizeRepoRelativePath(target_file_path);
+  const target_node_id = resolveDocumentNodeId(
+    graph.document_node_ids,
+    normalized_target_path,
+  );
+  const target_node =
+    graph.nodes[target_node_id] ??
+    createFallbackTargetNode(target_node_id, normalized_target_path);
+  const allowed_source_node_ids = where_clause
+    ? resolveAllowedSourceNodeIds(graph, where_clause, repo_config)
+    : null;
+
+  if (allowed_source_node_ids && 'diagnostics' in allowed_source_node_ids) {
+    return {
+      diagnostics: allowed_source_node_ids.diagnostics,
+      incoming: {},
+      node: target_node,
+    };
+  }
+
+  return {
+    diagnostics: [],
+    incoming: collectIncomingGroups(
+      graph,
+      target_node.id,
+      allowed_source_node_ids,
+    ),
+    node: target_node,
+  };
+}
+
+/**
+ * @param {BuildGraphResult} graph
+ * @param {string} target_node_id
+ * @param {Set<string> | null} allowed_source_node_ids
+ * @returns {Record<string, GraphNode[]>}
+ */
+function collectIncomingGroups(graph, target_node_id, allowed_source_node_ids) {
+  /** @type {Map<string, Map<string, GraphNode>>} */
+  const grouped_incoming = new Map();
+
+  for (const graph_edge of graph.edges) {
+    if (graph_edge.to !== target_node_id) {
+      continue;
+    }
+
+    if (
+      allowed_source_node_ids &&
+      !allowed_source_node_ids.has(graph_edge.from)
+    ) {
+      continue;
+    }
+
+    const source_node = graph.nodes[graph_edge.from];
+
+    if (!source_node) {
+      continue;
+    }
+
+    let relation_sources = grouped_incoming.get(graph_edge.relation);
+
+    if (!relation_sources) {
+      relation_sources = new Map();
+      grouped_incoming.set(graph_edge.relation, relation_sources);
+    }
+
+    relation_sources.set(source_node.id, source_node);
+  }
+
+  return formatIncomingGroups(grouped_incoming);
+}
+
+/**
+ * @param {BuildGraphResult} graph
+ * @param {string} where_clause
+ * @param {PatramRepoConfig | undefined} repo_config
+ * @returns {{ diagnostics: PatramDiagnostic[] } | Set<string>}
+ */
+function resolveAllowedSourceNodeIds(graph, where_clause, repo_config) {
+  const query_result = queryGraph(
+    graph,
+    where_clause,
+    repo_config ?? {
+      fields: {},
+      include: [],
+      queries: {},
+    },
+  );
+
+  if (query_result.diagnostics.length > 0) {
+    return {
+      diagnostics: query_result.diagnostics,
+    };
+  }
+
+  return new Set(query_result.nodes.map((graph_node) => graph_node.id));
+}
+
+/**
+ * @param {Map<string, Map<string, GraphNode>>} grouped_incoming
+ * @returns {Record<string, GraphNode[]>}
+ */
+function formatIncomingGroups(grouped_incoming) {
+  /** @type {Record<string, GraphNode[]>} */
+  const incoming = {};
+
+  for (const relation_name of [...grouped_incoming.keys()].sort(
+    compareStrings,
+  )) {
+    const relation_sources = /** @type {Map<string, GraphNode>} */ (
+      grouped_incoming.get(relation_name)
+    );
+
+    incoming[relation_name] = [...relation_sources.values()].sort(
+      compareGraphNodes,
+    );
+  }
+
+  return incoming;
+}
+
+/**
+ * @param {string} node_id
+ * @param {string} target_path
+ * @returns {GraphNode}
+ */
+function createFallbackTargetNode(node_id, target_path) {
+  return {
+    $class: 'document',
+    $id: node_id,
+    $path: target_path,
+    id: node_id,
+    path: target_path,
+    title: target_path,
+  };
+}
+
+/**
+ * @param {GraphNode} left_node
+ * @param {GraphNode} right_node
+ * @returns {number}
+ */
+function compareGraphNodes(left_node, right_node) {
+  return compareStrings(left_node.id, right_node.id);
+}
+
+/**
+ * @param {string} left_value
+ * @param {string} right_value
+ * @returns {number}
+ */
+function compareStrings(left_value, right_value) {
+  return left_value.localeCompare(right_value, 'en');
+}

package/lib/layout-incoming-references.js

@@ -0,0 +1,105 @@
+/**
+ * @import { OutputNodeItem } from './output-view.types.ts';
+ */
+
+import { formatOutputNodeMetadataRows } from './format-output-metadata.js';
+import { formatNodeHeader } from './format-node-header.js';
+import { formatOutputItemBlock } from './format-output-item-block.js';
+
+/**
+ * Layout grouped incoming references as plain text lines.
+ *
+ * @param {Record<string, OutputNodeItem[]>} incoming
+ * @param {{
+ *   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 format_node_header =
+    layout_options.format_node_header ?? defaultNodeHeaderFormatter;
+  const format_relation_header =
+    layout_options.format_relation_header ?? defaultRelationHeaderFormatter;
+  /** @type {string[]} */
+  const output_lines = [];
+
+  for (const relation_name of Object.keys(incoming)) {
+    if (output_lines.length > 0) {
+      output_lines.push('');
+    }
+
+    const relation_sources = incoming[relation_name];
+
+    output_lines.push(
+      format_relation_header(relation_name, relation_sources.length),
+    );
+    output_lines.push(
+      ...layoutIncomingRelationSources(relation_sources, format_node_header),
+    );
+  }
+
+  return output_lines;
+}
+
+/**
+ * @param {OutputNodeItem} output_item
+ * @returns {string}
+ */
+function defaultNodeHeaderFormatter(output_item) {
+  return formatNodeHeader(output_item);
+}
+
+/**
+ * @param {string} relation_name
+ * @param {number} relation_count
+ * @returns {string}
+ */
+function defaultRelationHeaderFormatter(relation_name, relation_count) {
+  return `${relation_name} (${relation_count})`;
+}
+
+/**
+ * @param {OutputNodeItem[]} relation_sources
+ * @param {(output_item: OutputNodeItem) => string} format_node_header
+ * @returns {string[]}
+ */
+function layoutIncomingRelationSources(relation_sources, format_node_header) {
+  /** @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),
+      ),
+    );
+  }
+
+  return output_lines;
+}
+
+/**
+ * @param {OutputNodeItem} output_item
+ * @param {(output_item: OutputNodeItem) => string} 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,
+  });
+}
+
+/**
+ * @param {string} block
+ * @returns {string[]}
+ */
+function indentIncomingNodeBlock(block) {
+  return block.split('\n').map((line) => (line.length > 0 ? `  ${line}` : ''));
+}

package/lib/layout-incoming-summary-lines.js

@@ -0,0 +1,21 @@
+/**
+ * Layout compact incoming-summary lines for `show`.
+ *
+ * @param {Record<string, number>} incoming_summary
+ * @returns {string[]}
+ */
+export function layoutIncomingSummaryLines(incoming_summary) {
+  const relation_names = Object.keys(incoming_summary);
+  const output_lines = ['incoming refs:'];
+
+  if (relation_names.length === 0) {
+    output_lines.push('  none');
+    return output_lines;
+  }
+
+  for (const relation_name of relation_names) {
+    output_lines.push(`  ${relation_name}: ${incoming_summary[relation_name]}`);
+  }
+
+  return output_lines;
+}

package/lib/output-view.types.d.ts

@@ -13,7 +13,7 @@ export interface OutputMetadataField {
 }
 export interface OutputViewSummary {
     count: number;
-    kind: 'resolved_link_list' | 'result_list' | 'stored_query_list';
+    kind: 'incoming_reference_list' | 'resolved_link_list' | 'result_list' | 'stored_query_list';
 }
 export interface QueryOutputViewSummary extends OutputViewSummary {
     kind: 'result_list';
@@ -67,13 +67,21 @@ export interface ShowOutputView {
     command: 'show';
     document?: OutputNodeItem;
     hints: string[];
+    incoming_summary: Record<string, number>;
     items: OutputResolvedLinkItem[];
     path: string;
     rendered_source: string;
     source: string;
     summary: OutputViewSummary;
 }
-export type OutputView = QueryOutputView | QueriesOutputView | ShowOutputView;
+export interface RefsOutputView {
+    command: 'refs';
+    hints: string[];
+    incoming: Record<string, OutputNodeItem[]>;
+    node: OutputNodeItem;
+    summary: OutputViewSummary;
+}
+export type OutputView = QueryOutputView | QueriesOutputView | RefsOutputView | ShowOutputView;
 export interface ResolvedOutputMode {
     color_enabled: boolean;
     renderer_name: 'json' | 'plain' | 'rich';

package/lib/output-view.types.ts

@@ -19,7 +19,11 @@ export interface OutputMetadataField {
 
 export interface OutputViewSummary {
   count: number;
-  kind: 'resolved_link_list' | 'result_list' | 'stored_query_list';
+  kind:
+    | 'incoming_reference_list'
+    | 'resolved_link_list'
+    | 'result_list'
+    | 'stored_query_list';
 }
 
 export interface QueryOutputViewSummary extends OutputViewSummary {
@@ -81,6 +85,7 @@ export interface ShowOutputView {
   command: 'show';
   document?: OutputNodeItem;
   hints: string[];
+  incoming_summary: Record<string, number>;
   items: OutputResolvedLinkItem[];
   path: string;
   rendered_source: string;
@@ -88,7 +93,19 @@ export interface ShowOutputView {
   summary: OutputViewSummary;
 }
 
-export type OutputView = QueryOutputView | QueriesOutputView | ShowOutputView;
+export interface RefsOutputView {
+  command: 'refs';
+  hints: string[];
+  incoming: Record<string, OutputNodeItem[]>;
+  node: OutputNodeItem;
+  summary: OutputViewSummary;
+}
+
+export type OutputView =
+  | QueryOutputView
+  | QueriesOutputView
+  | RefsOutputView
+  | ShowOutputView;
 
 export interface ResolvedOutputMode {
   color_enabled: boolean;

package/lib/parse-cli-arguments-helpers.js

@@ -160,6 +160,10 @@ export function buildCommandArguments(
     return ['--where', parsed_values.where];
   }
 
+  if (command_name === 'refs' && parsed_values.where !== undefined) {
+    return [command_positionals[0], '--where', parsed_values.where];
+  }
+
   return command_positionals;
 }
 
@@ -305,7 +309,7 @@ function findMissingOptionValue(option_tokens) {
   for (const token of option_tokens) {
     if (token.name === 'where' && typeof token.value !== 'string') {
       return {
-        argument_label: '<name> or --where "<clause>"',
+        argument_label: "<name> or --where '<clause>'",
         code: 'missing_required_argument',
         command_name: 'query',
       };
@@ -401,11 +405,14 @@ function validateCommandPositionals(command_name, command_positionals) {
       };
     }
 
-    if (command_name === 'show' && command_definition.missing_argument_label) {
+    if (
+      (command_name === 'refs' || command_name === 'show') &&
+      command_definition.missing_argument_label
+    ) {
       return {
         argument_label: command_definition.missing_argument_label,
         code: 'missing_required_argument',
-        command_name: 'show',
+        command_name,
       };
     }
 
@@ -422,7 +429,7 @@ function validateCommandPositionals(command_name, command_positionals) {
 
   if (command_name === 'query' && command_positionals.length === 0) {
     return {
-      argument_label: '<name> or --where "<clause>"',
+      argument_label: "<name> or --where '<clause>'",
       code: 'missing_required_argument',
       command_name: 'query',
     };

package/lib/parse-cli-arguments.types.ts

@@ -1,4 +1,10 @@
-export type CliCommandName = 'check' | 'fields' | 'query' | 'queries' | 'show';
+export type CliCommandName =
+  | 'check'
+  | 'fields'
+  | 'query'
+  | 'queries'
+  | 'refs'
+  | 'show';
 export type CliHelpTopicName = 'query-language';
 export type CliHelpTargetKind = 'root' | 'command' | 'topic';
 
@@ -34,7 +40,7 @@ export type CliParseError =
   | {
       code: 'missing_required_argument';
       argument_label: string;
-      command_name: 'query' | 'show';
+      command_name: 'query' | 'refs' | 'show';
     }
   | {
       code: 'option_not_valid_for_command';

package/lib/patram-cli.js

@@ -12,6 +12,7 @@ import {
   writeRenderedCommandOutput,
 } from './command-output.js';
 import { discoverFields } from './discover-fields.js';
+import { inspectReverseReferences } from './inspect-reverse-references.js';
 import { listRepoFiles } from './list-source-files.js';
 import { listQueries } from './list-queries.js';
 import { loadPatramConfig } from './load-patram-config.js';
@@ -36,6 +37,7 @@ import {
 } from './resolve-check-target.js';
 import {
   createOutputView,
+  createRefsOutputView,
   createShowOutputView,
 } from './render-output-view.js';
 import { renderFieldDiscovery } from './render-field-discovery.js';
@@ -54,6 +56,7 @@ import { loadShowOutput } from './show-document.js';
  * Implements Command: ../docs/reference/commands/check.md
  * Implements Command: ../docs/reference/commands/query.md
  * Implements Command: ../docs/reference/commands/queries.md
+ * Implements Command: ../docs/reference/commands/refs.md
  * Implements Command: ../docs/reference/commands/show.md
  * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
  * Decided by: ../docs/decisions/cli-output-architecture.md
@@ -105,6 +108,10 @@ export async function main(cli_arguments, io_context) {
     return runQueriesCommand(parsed_command, io_context);
   }
 
+  if (parsed_command.command_name === 'refs') {
+    return runRefsCommand(parsed_command, io_context);
+  }
+
   if (parsed_command.command_name === 'show') {
     return runShowCommand(parsed_command, io_context);
   }
@@ -371,6 +378,52 @@ async function runQueriesCommand(parsed_command, io_context) {
   return 0;
 }
 
+/**
+ * @param {ParsedCliCommandRequest} parsed_command
+ * @param {{ stderr: { write(chunk: string): boolean }, stdout: { isTTY?: boolean, write(chunk: string): boolean }, write_paged_output?: (output_text: string) => Promise<void> }} io_context
+ * @returns {Promise<number>}
+ */
+async function runRefsCommand(parsed_command, io_context) {
+  const project_graph_result = await loadProjectGraph(process.cwd());
+
+  if (project_graph_result.diagnostics.length > 0) {
+    writeDiagnostics(io_context.stderr, project_graph_result.diagnostics);
+
+    return 1;
+  }
+
+  const refs_output = inspectReverseReferences(
+    project_graph_result.graph,
+    parsed_command.command_arguments[0],
+    project_graph_result.config,
+    resolveRefsWhereClause(parsed_command.command_arguments),
+  );
+
+  if (refs_output.diagnostics.length > 0) {
+    io_context.stderr.write(
+      renderInvalidWhereDiagnostic(refs_output.diagnostics[0]),
+    );
+
+    return 1;
+  }
+
+  const derived_summary_evaluator = createDerivedSummaryEvaluator(
+    project_graph_result.config,
+    project_graph_result.graph,
+  );
+
+  await writeCommandOutput(
+    io_context,
+    parsed_command,
+    createRefsOutputView(refs_output, {
+      derived_summary_evaluator,
+      repo_config: project_graph_result.config,
+    }),
+  );
+
+  return 0;
+}
+
 /**
  * @param {ParsedCliCommandRequest} parsed_command
  * @param {{ stderr: { write(chunk: string): boolean }, stdout: { isTTY?: boolean, write(chunk: string): boolean }, write_paged_output?: (output_text: string) => Promise<void> }} io_context
@@ -441,7 +494,7 @@ function createQueryOutputOptions(parsed_command, query_result, use_pager) {
   const offset = parsed_command.query_offset ?? 0;
 
   if (query_result.total_count === 0) {
-    hints.push('Try: patram query --where "$class=task"');
+    hints.push("Try: patram query --where '$class=task'");
   }
 
   if (
@@ -500,6 +553,18 @@ function createQueryExecutionOptions(parsed_command, use_pager) {
   };
 }
 
+/**
+ * @param {string[]} command_arguments
+ * @returns {string | undefined}
+ */
+function resolveRefsWhereClause(command_arguments) {
+  if (command_arguments[1] !== '--where') {
+    return undefined;
+  }
+
+  return command_arguments.slice(2).join(' ').trim();
+}
+
 /**
  * @param {import('./load-patram-config.types.ts').PatramDiagnostic} diagnostic
  * @returns {string}

package/lib/render-cli-help.js

@@ -308,7 +308,7 @@ function renderInvalidCommandOptionError(command_name, invalid_token) {
 }
 
 /**
- * @param {'query' | 'show'} command_name
+ * @param {'query' | 'refs' | 'show'} command_name
  * @param {string} argument_label
  * @returns {string}
  */

package/lib/render-json-output.js

@@ -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-output-view.js

@@ -3,7 +3,7 @@
  * @import { DerivedSummaryEvaluator } from './derived-summary.js';
  * @import { PatramRepoConfig } from './load-patram-config.types.ts';
  * @import { ParsedCliArguments } from './parse-cli-arguments.types.ts';
- * @import { OutputDerivedSummary, OutputMetadataField, OutputNodeItem, OutputResolvedLinkItem, OutputResolvedLinkTarget, OutputStoredQueryItem, OutputView, ResolvedOutputMode, ShowOutputView } from './output-view.types.ts';
+ * @import { OutputDerivedSummary, OutputMetadataField, OutputNodeItem, OutputResolvedLinkItem, OutputResolvedLinkTarget, OutputStoredQueryItem, OutputView, RefsOutputView, ResolvedOutputMode, ShowOutputView } from './output-view.types.ts';
  */
 /* eslint-disable max-lines */
 
@@ -55,7 +55,7 @@ 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 {{ incoming_summary: Record<string, number>, 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, document_node_ids?: BuildGraphResult['document_node_ids'], graph_nodes?: BuildGraphResult['nodes'], repo_config?: PatramRepoConfig }=} command_options
  * @returns {ShowOutputView}
  */
@@ -78,6 +78,7 @@ export function createShowOutputView(show_output, command_options = {}) {
         )
       : undefined,
     hints: [],
+    incoming_summary: show_output.incoming_summary,
     items: show_output.resolved_links.map((resolved_link) =>
       createResolvedLinkOutputItem(resolved_link, command_options),
     ),
@@ -91,6 +92,46 @@ export function createShowOutputView(show_output, command_options = {}) {
   };
 }
 
+/**
+ * Create a shared output view for the refs command.
+ *
+ * @param {{ incoming: Record<string, GraphNode[]>, node: GraphNode }} refs_output
+ * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, repo_config?: PatramRepoConfig }=} command_options
+ * @returns {RefsOutputView}
+ */
+export function createRefsOutputView(refs_output, command_options = {}) {
+  /** @type {Record<string, OutputNodeItem[]>} */
+  const incoming = {};
+
+  for (const relation_name of Object.keys(refs_output.incoming)) {
+    incoming[relation_name] = refs_output.incoming[relation_name].map(
+      (graph_node) =>
+        createOutputNodeItem(
+          graph_node,
+          command_options.derived_summary_evaluator?.evaluate(graph_node) ??
+            null,
+          command_options.repo_config?.fields ?? {},
+        ),
+    );
+  }
+
+  return {
+    command: 'refs',
+    hints: [],
+    incoming,
+    node: createOutputNodeItem(
+      refs_output.node,
+      command_options.derived_summary_evaluator?.evaluate(refs_output.node) ??
+        null,
+      command_options.repo_config?.fields ?? {},
+    ),
+    summary: {
+      count: countIncomingReferenceItems(incoming),
+      kind: 'incoming_reference_list',
+    },
+  };
+}
+
 /**
  * Render one shared output view through the resolved renderer.
  *
@@ -130,7 +171,7 @@ function createQueryOutputView(graph_nodes, command_options = {}) {
     command: 'query',
     hints:
       command_options.hints ??
-      (total_count === 0 ? ['Try: patram query --where "$class=task"'] : []),
+      (total_count === 0 ? ["Try: patram query --where '$class=task'"] : []),
     items: graph_nodes.map((graph_node) =>
       createOutputNodeItem(
         graph_node,
@@ -168,6 +209,20 @@ function createStoredQueriesOutputView(stored_queries) {
   };
 }
 
+/**
+ * @param {Record<string, OutputNodeItem[]>} incoming
+ * @returns {number}
+ */
+function countIncomingReferenceItems(incoming) {
+  let count = 0;
+
+  for (const output_items of Object.values(incoming)) {
+    count += output_items.length;
+  }
+
+  return count;
+}
+
 /**
  * @param {GraphNode} graph_node
  * @param {OutputDerivedSummary | null} derived_summary

package/lib/render-plain-output.js

@@ -1,5 +1,5 @@
 /**
- * @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 {
@@ -8,6 +8,8 @@ import {
 } 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';
 
 /**
@@ -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,17 @@ function formatPlainResolvedLinkItem(output_item) {
   });
 }
 
+/**
+ * @param {ShowOutputView} output_view
+ * @returns {string}
+ */
+function renderPlainIncomingSummary(output_view) {
+  const output_lines = layoutIncomingSummaryLines(output_view.incoming_summary);
+  output_lines.push('', `Hint: patram refs ${output_view.path}`);
+
+  return output_lines.join('\n');
+}
+
 /**
  * @param {string} value
  * @returns {string}

package/lib/render-rich-output.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 { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView, QueryOutputView, RefsOutputView, ShowOutputView } from './output-view.types.ts';
  */
 
 import { Ansis } from 'ansis';
@@ -11,6 +11,8 @@ import {
 } 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 './render-rich-source.js';
 
@@ -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,10 +110,7 @@ async function renderRichShowOutput(output_view, render_options, ansi) {
   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`;
-  }
+  const incoming_summary = renderRichIncomingSummary(output_view, ansi);
 
   /** @type {string[]} */
   const summary_items = [];
@@ -121,9 +123,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 +189,24 @@ function formatRichResolvedLinkItem(output_item, ansi) {
   });
 }
 
+/**
+ * @param {ShowOutputView} output_view
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function renderRichIncomingSummary(output_view, ansi) {
+  const output_lines = layoutIncomingSummaryLines(output_view.incoming_summary);
+  output_lines[0] = ansi.bold(output_lines[0]);
+
+  if (Object.keys(output_view.incoming_summary).length === 0) {
+    output_lines[1] = `  ${ansi.gray('none')}`;
+  }
+
+  output_lines.push('', ansi.gray(`Hint: patram refs ${output_view.path}`));
+
+  return output_lines.join('\n');
+}
+
 /**
  * @param {boolean} color_enabled
  * @returns {Ansis}

package/lib/reverse-reference-test-helpers.js

@@ -0,0 +1,76 @@
+/**
+ * Shared reverse-reference graph fixtures for tests.
+ */
+
+export function createDecisionNode() {
+  return {
+    $class: 'decision',
+    $id: 'decision:query-language',
+    $path: 'docs/decisions/query-language.md',
+    id: 'decision:query-language',
+    path: 'docs/decisions/query-language.md',
+    status: 'accepted',
+    title: 'Query Language',
+  };
+}
+
+export function createReconcileNode() {
+  return {
+    $class: 'document',
+    $id: 'doc:lib/reconcile.js',
+    $path: 'lib/reconcile.js',
+    id: 'doc:lib/reconcile.js',
+    path: 'lib/reconcile.js',
+    title: 'Reconciler entrypoint.',
+  };
+}
+
+export function createResumeNode() {
+  return {
+    $class: 'document',
+    $id: 'doc:lib/resume.js',
+    $path: 'lib/resume.js',
+    id: 'doc:lib/resume.js',
+    path: 'lib/resume.js',
+    title: 'Resume entrypoint.',
+  };
+}
+
+export function createTaskNode() {
+  return {
+    $class: 'task',
+    $id: 'task:reverse-reference-inspection',
+    $path: 'docs/tasks/v0/reverse-reference-inspection.md',
+    id: 'task:reverse-reference-inspection',
+    path: 'docs/tasks/v0/reverse-reference-inspection.md',
+    status: 'ready',
+    title: 'Implement reverse reference inspection',
+  };
+}
+
+/**
+ * @param {string} edge_id
+ * @param {string} from_id
+ * @param {string} origin_path
+ * @param {string} relation_name
+ * @param {string} to_id
+ */
+export function createGraphEdge(
+  edge_id,
+  from_id,
+  origin_path,
+  relation_name,
+  to_id,
+) {
+  return {
+    from: from_id,
+    id: edge_id,
+    origin: {
+      column: 1,
+      line: 1,
+      path: origin_path,
+    },
+    relation: relation_name,
+    to: to_id,
+  };
+}

package/lib/show-document.js

@@ -1,6 +1,6 @@
 /* eslint-disable max-lines */
 /**
- * @import { GraphNode } from './build-graph.types.ts';
+ * @import { BuildGraphResult, GraphNode } from './build-graph.types.ts';
  * @import { PatramClaim } from './parse-claims.types.ts';
  * @import { PatramDiagnostic } from './load-patram-config.types.ts';
  */
@@ -9,6 +9,7 @@ import { readFile } from 'node:fs/promises';
 import { posix, relative, resolve } from 'node:path';
 
 import { resolveDocumentNodeId } from './build-graph-identity.js';
+import { inspectReverseReferences } from './inspect-reverse-references.js';
 import { parseSourceFile } from './parse-claims.js';
 
 /**
@@ -30,11 +31,12 @@ import { parseSourceFile } from './parse-claims.js';
 /**
  * @param {string} requested_file_path
  * @param {string} project_directory
- * @param {import('./build-graph.types.ts').BuildGraphResult} graph
+ * @param {BuildGraphResult} graph
  * @returns {Promise<
  *   | {
  *       success: true;
  *       value: {
+ *         incoming_summary: Record<string, number>;
  *         path: string;
  *         rendered_source: string;
  *         resolved_links: Array<{
@@ -93,6 +95,7 @@ export async function loadShowOutput(
       source_file_path,
       source_text,
       parse_result.claims,
+      graph,
       graph.document_node_ids,
       graph.nodes,
     ),
@@ -103,14 +106,16 @@ export async function loadShowOutput(
  * @param {string} source_file_path
  * @param {string} source_text
  * @param {PatramClaim[]} claims
+ * @param {BuildGraphResult} graph
  * @param {import('./build-graph.types.ts').BuildGraphResult['document_node_ids']} document_node_ids
  * @param {Record<string, GraphNode>} graph_nodes
- * @returns {{ path: string, rendered_source: string, resolved_links: Array<{ label: string, reference: number, target: { kind?: string, path: string, status?: string, title: string } }>, source: string }}
+ * @returns {{ incoming_summary: Record<string, number>, path: string, rendered_source: string, resolved_links: Array<{ label: string, reference: number, target: { kind?: string, path: string, status?: string, title: string } }>, source: string }}
  */
 function createShowOutput(
   source_file_path,
   source_text,
   claims,
+  graph,
   document_node_ids,
   graph_nodes,
 ) {
@@ -125,8 +130,15 @@ function createShowOutput(
       graph_nodes,
     ),
   );
+  const reverse_references = inspectReverseReferences(
+    graph,
+    source_file_path,
+    undefined,
+    undefined,
+  );
 
   return {
+    incoming_summary: summarizeIncomingReferences(reverse_references.incoming),
     path: source_file_path,
     rendered_source: renderResolvedSource(
       source_text,
@@ -269,12 +281,23 @@ function getScalarGraphField(field_value) {
  * @returns {{ kind?: string, path: string, status?: string, title: string }}
  */
 function createResolvedLinkTarget(target_node, target_path, fallback_title) {
-  return {
-    kind: getResolvedLinkTargetKind(target_node),
+  /** @type {{ kind?: string, path: string, status?: string, title: string }} */
+  const resolved_target = {
     path: getResolvedLinkTargetPath(target_node, target_path),
-    status: getScalarGraphField(target_node?.status),
     title: getScalarGraphField(target_node?.title) ?? fallback_title,
   };
+  const target_kind = getResolvedLinkTargetKind(target_node);
+  const target_status = getScalarGraphField(target_node?.status);
+
+  if (target_kind) {
+    resolved_target.kind = target_kind;
+  }
+
+  if (target_status) {
+    resolved_target.status = target_status;
+  }
+
+  return resolved_target;
 }
 
 /**
@@ -355,6 +378,21 @@ function trimTrailingLineBreaks(value) {
   return value.replace(/\n+$/du, '');
 }
 
+/**
+ * @param {Record<string, GraphNode[]>} incoming
+ * @returns {Record<string, number>}
+ */
+function summarizeIncomingReferences(incoming) {
+  /** @type {Record<string, number>} */
+  const incoming_summary = {};
+
+  for (const relation_name of Object.keys(incoming)) {
+    incoming_summary[relation_name] = incoming[relation_name].length;
+  }
+
+  return incoming_summary;
+}
+
 /**
  * @param {unknown} error
  * @returns {error is NodeJS.ErrnoException}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patram",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "main": "./lib/patram.js",
   "types": "./lib/patram.d.ts",