patram 0.1.1 → 0.2.0

package/lib/render-cli-help.js

@@ -0,0 +1,419 @@
+/* eslint-disable max-lines */
+/**
+ * @import {
+ *   CliCommandName,
+ *   CliHelpTopicName,
+ *   CliParseError,
+ *   ParsedCliHelpRequest,
+ * } from './parse-cli-arguments.types.ts';
+ * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ */
+
+import {
+  getCommandDefinition,
+  getHelpTopicDefinition,
+  getRootHelpDefinition,
+  listCommandNames,
+  listHelpTopicNames,
+} from './cli-help-metadata.js';
+
+/**
+ * @param {ParsedCliHelpRequest} help_request
+ * @returns {string}
+ */
+export function renderHelpRequest(help_request) {
+  if (help_request.target_kind === 'root') {
+    return renderRootHelp();
+  }
+
+  if (help_request.target_kind === 'command') {
+    return renderCommandHelp(
+      /** @type {CliCommandName} */ (help_request.target_name),
+    );
+  }
+
+  return renderHelpTopic(
+    /** @type {CliHelpTopicName} */ (help_request.target_name),
+  );
+}
+
+/**
+ * @param {CliParseError} parse_error
+ * @returns {string}
+ */
+export function renderCliParseError(parse_error) {
+  if (parse_error.code === 'unknown_command') {
+    return renderUnknownCommandError(parse_error.token, parse_error.suggestion);
+  }
+
+  if (parse_error.code === 'unknown_help_target') {
+    return renderUnknownHelpTargetError(
+      parse_error.token,
+      parse_error.suggestion,
+    );
+  }
+
+  if (parse_error.code === 'unknown_option') {
+    return renderUnknownOptionError(
+      parse_error.token,
+      parse_error.command_name,
+      parse_error.suggestion,
+    );
+  }
+
+  if (parse_error.code === 'option_not_valid_for_command') {
+    return renderInvalidCommandOptionError(
+      parse_error.command_name,
+      parse_error.token,
+    );
+  }
+
+  if (parse_error.code === 'missing_required_argument') {
+    return renderMissingRequiredArgumentError(
+      parse_error.command_name,
+      parse_error.argument_label,
+    );
+  }
+
+  return `${parse_error.message}\n`;
+}
+
+/**
+ * @param {PatramDiagnostic} diagnostic
+ * @returns {string}
+ */
+export function renderInvalidWhereDiagnostic(diagnostic) {
+  const diagnostic_line = formatDiagnostic(diagnostic);
+
+  return joinOutputLines([
+    'Invalid where clause:',
+    `  ${diagnostic_line}`,
+    '',
+    'Next:',
+    '  patram help query-language',
+  ]);
+}
+
+/**
+ * @returns {string}
+ */
+function renderRootHelp() {
+  const root_help = getRootHelpDefinition();
+
+  return joinOutputLines([
+    'Usage:',
+    ...indentLines(root_help.usage_lines),
+    '',
+    root_help.summary,
+    '',
+    'Commands:',
+    ...listCommandNames().map((command_name) =>
+      formatSummaryLine(
+        command_name,
+        getCommandDefinition(command_name).root_summary,
+      ),
+    ),
+    '',
+    'Global options:',
+    ...indentLines(root_help.global_options),
+    '',
+    'Next:',
+    '  patram help <command>',
+  ]);
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @returns {string}
+ */
+function renderCommandHelp(command_name) {
+  const command_definition = getCommandDefinition(command_name);
+  /** @type {string[]} */
+  const output_lines = [
+    'Usage:',
+    ...indentLines(command_definition.usage_lines),
+    '',
+    command_definition.summary,
+  ];
+
+  if (
+    command_definition.syntax_lines &&
+    command_definition.syntax_lines.length
+  ) {
+    output_lines.push(
+      '',
+      'Where clause:',
+      ...indentLines(command_definition.syntax_lines),
+    );
+  }
+
+  output_lines.push(
+    '',
+    'Options:',
+    ...command_definition.options.map((option) =>
+      formatSummaryLine(
+        option.label,
+        option.description,
+        command_definition.option_column_width,
+      ),
+    ),
+    '',
+    'Examples:',
+    ...indentLines(command_definition.examples),
+    '',
+    'Related:',
+    ...indentLines(
+      command_definition.related.map(
+        (related_name) => `patram ${related_name}`,
+      ),
+    ),
+  );
+
+  if (command_definition.help_topics.length > 0) {
+    output_lines.push(
+      '',
+      'Help topics:',
+      ...indentLines(
+        command_definition.help_topics.map(
+          (help_topic_name) => `patram help ${help_topic_name}`,
+        ),
+      ),
+    );
+  }
+
+  return joinOutputLines(output_lines);
+}
+
+/**
+ * @param {CliHelpTopicName} help_topic_name
+ * @returns {string}
+ */
+function renderHelpTopic(help_topic_name) {
+  const help_topic = getHelpTopicDefinition(help_topic_name);
+
+  return joinOutputLines([
+    help_topic.lead,
+    '',
+    'Usage:',
+    ...indentLines(help_topic.usage_lines),
+    '',
+    'Fields:',
+    ...indentLines(help_topic.terms),
+    '',
+    'Relations:',
+    ...help_topic.relation_terms.map((relation_term) =>
+      formatSummaryLine(
+        relation_term.label,
+        relation_term.description,
+        getSummaryColumnWidth(help_topic.relation_terms, 23),
+      ),
+    ),
+    '',
+    'Operators:',
+    ...help_topic.operators.map((operator) =>
+      formatSummaryLine(
+        operator.label,
+        operator.description,
+        getSummaryColumnWidth(help_topic.operators, 7),
+      ),
+    ),
+    '',
+    'Examples:',
+    ...indentLines(help_topic.examples),
+  ]);
+}
+
+/**
+ * @param {string} invalid_token
+ * @param {CliCommandName | undefined} suggestion
+ * @returns {string}
+ */
+function renderUnknownCommandError(invalid_token, suggestion) {
+  if (suggestion) {
+    return joinOutputLines([
+      `Unknown command: ${invalid_token}`,
+      '',
+      'Did you mean:',
+      `  ${suggestion}`,
+      '',
+      'Next:',
+      `  patram help ${suggestion}`,
+    ]);
+  }
+
+  return joinOutputLines([
+    `Unknown command: ${invalid_token}`,
+    '',
+    'Commands:',
+    ...indentLines(listCommandNames()),
+    '',
+    'Next:',
+    '  patram --help',
+  ]);
+}
+
+/**
+ * @param {string} invalid_token
+ * @param {CliCommandName | undefined} command_name
+ * @param {string | undefined} suggestion
+ * @returns {string}
+ */
+function renderUnknownOptionError(invalid_token, command_name, suggestion) {
+  if (suggestion) {
+    return joinOutputLines([
+      `Unknown option: ${invalid_token}`,
+      '',
+      'Did you mean:',
+      `  ${suggestion}`,
+      '',
+      'Next:',
+      `  ${renderCommandHelpPath(command_name)}`,
+    ]);
+  }
+
+  /** @type {string[]} */
+  const output_lines = [`Unknown option: ${invalid_token}`];
+
+  if (command_name) {
+    output_lines.push(
+      '',
+      'Usage:',
+      ...indentLines(getCommandDefinition(command_name).usage_lines),
+      '',
+      'Next:',
+      `  ${renderCommandHelpPath(command_name)}`,
+    );
+  } else {
+    output_lines.push('', 'Next:', '  patram --help');
+  }
+
+  return joinOutputLines(output_lines);
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @param {string} invalid_token
+ * @returns {string}
+ */
+function renderInvalidCommandOptionError(command_name, invalid_token) {
+  return joinOutputLines([
+    `Option not valid for command: ${invalid_token}`,
+    '',
+    'Usage:',
+    ...indentLines(getCommandDefinition(command_name).usage_lines),
+    '',
+    'Next:',
+    `  ${renderCommandHelpPath(command_name)}`,
+  ]);
+}
+
+/**
+ * @param {'query' | 'show'} command_name
+ * @param {string} argument_label
+ * @returns {string}
+ */
+function renderMissingRequiredArgumentError(command_name, argument_label) {
+  const command_definition = getCommandDefinition(command_name);
+
+  return joinOutputLines([
+    `Missing required argument: ${argument_label}`,
+    '',
+    'Usage:',
+    ...indentLines(command_definition.missing_usage_lines),
+    '',
+    'Examples:',
+    ...indentLines(command_definition.missing_argument_examples),
+  ]);
+}
+
+/**
+ * @param {string} invalid_token
+ * @param {CliCommandName | CliHelpTopicName | undefined} suggestion
+ * @returns {string}
+ */
+function renderUnknownHelpTargetError(invalid_token, suggestion) {
+  if (suggestion) {
+    return joinOutputLines([
+      `Unknown help topic or command: ${invalid_token}`,
+      '',
+      'Did you mean:',
+      `  ${suggestion}`,
+      '',
+      'Next:',
+      `  patram help ${suggestion}`,
+    ]);
+  }
+
+  return joinOutputLines([
+    `Unknown help topic or command: ${invalid_token}`,
+    '',
+    'Help topics:',
+    ...indentLines(listHelpTopicNames()),
+    '',
+    'Commands:',
+    ...indentLines(listCommandNames()),
+    '',
+    'Next:',
+    '  patram help query',
+  ]);
+}
+
+/**
+ * @param {PatramDiagnostic} diagnostic
+ * @returns {string}
+ */
+function formatDiagnostic(diagnostic) {
+  return `${diagnostic.path}:${diagnostic.line}:${diagnostic.column} ${diagnostic.level} ${diagnostic.code} ${diagnostic.message}`;
+}
+
+/**
+ * @param {string | undefined} command_name
+ * @returns {string}
+ */
+function renderCommandHelpPath(command_name) {
+  if (!command_name) {
+    return 'patram --help';
+  }
+
+  return `patram help ${command_name}`;
+}
+
+/**
+ * @param {string[]} lines
+ * @returns {string[]}
+ */
+function indentLines(lines) {
+  return lines.map((line) => `  ${line}`);
+}
+
+/**
+ * @param {string} label
+ * @param {string} description
+ * @param {number} width
+ * @returns {string}
+ */
+function formatSummaryLine(label, description, width = 9) {
+  return `  ${label.padEnd(width)}${description}`;
+}
+
+/**
+ * @param {{ label: string }[]} items
+ * @param {number} minimum_width
+ * @returns {number}
+ */
+function getSummaryColumnWidth(items, minimum_width) {
+  const longest_label = items.reduce(
+    (current_width, item) => Math.max(current_width, item.label.length),
+    0,
+  );
+
+  return Math.max(minimum_width, longest_label + 2);
+}
+
+/**
+ * @param {string[]} output_lines
+ * @returns {string}
+ */
+function joinOutputLines(output_lines) {
+  return `${output_lines.join('\n')}\n`;
+}

package/lib/render-json-output.js

@@ -39,6 +39,9 @@ export function renderJsonOutput(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),
       },
@@ -52,10 +55,10 @@ export function renderJsonOutput(output_view) {
 
 /**
  * @param {OutputNodeItem} output_item
- * @returns {{ id: string, kind: string, title: string, path: string, status?: string }}
+ * @returns {{ derived?: Record<string, boolean | number | string | null>, derived_summary?: string, id: string, kind: string, title: string, path: string, status?: string }}
  */
 function formatJsonQueryItem(output_item) {
-  /** @type {{ id: string, kind: string, title: string, path: string, status?: string }} */
+  /** @type {{ derived?: Record<string, boolean | number | string | null>, derived_summary?: string, id: string, kind: string, title: string, path: string, status?: string }} */
   const query_item = {
     id: output_item.id,
     kind: output_item.node_kind,
@@ -67,6 +70,16 @@ function formatJsonQueryItem(output_item) {
     query_item.status = output_item.status;
   }
 
+  if (output_item.derived_summary) {
+    query_item.derived_summary = output_item.derived_summary.name;
+    query_item.derived = Object.fromEntries(
+      output_item.derived_summary.fields.map((field) => [
+        field.name,
+        field.value,
+      ]),
+    );
+  }
+
   return query_item;
 }
 
@@ -83,10 +96,10 @@ function formatJsonStoredQuery(output_item) {
 
 /**
  * @param {OutputResolvedLinkItem} output_item
- * @returns {{ label: string, reference: number, target: { kind?: string, path: string, status?: string, title: string } }}
+ * @returns {{ label: string, reference: number, target: { derived?: Record<string, boolean | number | string | null>, derived_summary?: string, kind?: string, path: string, status?: string, title: string } }}
  */
 function formatJsonResolvedLink(output_item) {
-  /** @type {{ label: string, reference: number, target: { kind?: string, path: string, status?: string, title: string } }} */
+  /** @type {{ label: string, reference: number, target: { derived?: Record<string, boolean | number | string | null>, derived_summary?: string, kind?: string, path: string, status?: string, title: string } }} */
   const resolved_link = {
     reference: output_item.reference,
     label: output_item.label,
@@ -104,5 +117,45 @@ function formatJsonResolvedLink(output_item) {
     resolved_link.target.status = output_item.target.status;
   }
 
+  if (output_item.target.derived_summary) {
+    resolved_link.target.derived_summary =
+      output_item.target.derived_summary.name;
+    resolved_link.target.derived = Object.fromEntries(
+      output_item.target.derived_summary.fields.map((field) => [
+        field.name,
+        field.value,
+      ]),
+    );
+  }
+
   return resolved_link;
 }
+
+/**
+ * @param {OutputNodeItem} output_item
+ * @returns {{ derived?: Record<string, boolean | number | string | null>, derived_summary?: string, kind: string, title: string, path: string, status?: string }}
+ */
+function formatJsonShowDocument(output_item) {
+  /** @type {{ derived?: Record<string, boolean | number | string | null>, derived_summary?: string, kind: string, title: string, path: string, status?: string }} */
+  const document_summary = {
+    kind: output_item.node_kind,
+    path: output_item.path,
+    title: output_item.title,
+  };
+
+  if (output_item.status) {
+    document_summary.status = output_item.status;
+  }
+
+  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

@@ -1,6 +1,7 @@
 /** @import * as $k$$l$output$j$view$k$types$k$ts from './output-view.types.ts'; */
 /**
- * @import { GraphNode } from './build-graph.types.ts';
+ * @import { BuildGraphResult, GraphNode } from './build-graph.types.ts';
+ * @import { DerivedSummaryEvaluator } from './derived-summary.js';
  * @import { ParsedCliArguments } from './parse-cli-arguments.types.ts';
  * @import { OutputStoredQueryItem, OutputView, ResolvedOutputMode, ShowOutputView } from './output-view.types.ts';
  */
@@ -29,7 +30,7 @@ import { renderRichOutput } from './render-rich-output.js';
  *
  * @param {'query' | 'queries'} command_name
  * @param {GraphNode[] | { name: string, where: string }[]} command_items
- * @param {{ hints?: string[], limit?: number, offset?: number, total_count?: number }=} command_options
+ * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, hints?: string[], limit?: number, offset?: number, total_count?: number }=} command_options
  * @returns {OutputView}
  */
 export function createOutputView(command_name, command_items, command_options) {
@@ -53,17 +54,36 @@ 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 {{ derived_summary_evaluator?: DerivedSummaryEvaluator, graph_nodes?: BuildGraphResult['nodes'] }=} command_options
  * @returns {ShowOutputView}
  */
-export function createShowOutputView(show_output) {
+export function createShowOutputView(show_output, command_options = {}) {
+  const shown_document_node =
+    command_options.graph_nodes?.[`doc:${show_output.path}`];
+
   return {
     command: 'show',
+    document: shown_document_node
+      ? createOutputNodeItem(
+          shown_document_node,
+          command_options.derived_summary_evaluator?.evaluate(
+            shown_document_node,
+          ) ?? null,
+        )
+      : undefined,
     hints: [],
     items: show_output.resolved_links.map((resolved_link) => ({
       kind: 'resolved_link',
       label: resolved_link.label,
       reference: resolved_link.reference,
-      target: createResolvedLinkTarget(resolved_link.target),
+      target: createResolvedLinkTarget(
+        resolved_link.target,
+        command_options.graph_nodes?.[`doc:${resolved_link.target.path}`]
+          ? (command_options.derived_summary_evaluator?.evaluate(
+              command_options.graph_nodes[`doc:${resolved_link.target.path}`],
+            ) ?? null)
+          : null,
+      ),
     })),
     path: show_output.path,
     rendered_source: show_output.rendered_source,
@@ -104,7 +124,7 @@ export async function renderOutputView(
 
 /**
  * @param {GraphNode[]} graph_nodes
- * @param {{ hints?: string[], limit?: number, offset?: number, total_count?: number }=} command_options
+ * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, hints?: string[], limit?: number, offset?: number, total_count?: number }=} command_options
  * @returns {OutputView}
  */
 function createQueryOutputView(graph_nodes, command_options = {}) {
@@ -115,7 +135,12 @@ function createQueryOutputView(graph_nodes, command_options = {}) {
     hints:
       command_options.hints ??
       (total_count === 0 ? ['Try: patram query --where "kind=task"'] : []),
-    items: graph_nodes.map(createOutputNodeItem),
+    items: graph_nodes.map((graph_node) =>
+      createOutputNodeItem(
+        graph_node,
+        command_options.derived_summary_evaluator?.evaluate(graph_node) ?? null,
+      ),
+    ),
     summary: {
       count: graph_nodes.length,
       kind: 'result_list',
@@ -148,9 +173,10 @@ function createStoredQueriesOutputView(stored_queries) {
 
 /**
  * @param {GraphNode} graph_node
+ * @param {import('./output-view.types.ts').OutputDerivedSummary | null} derived_summary
  * @returns {$k$$l$output$j$view$k$types$k$ts.OutputNodeItem}
  */
-function createOutputNodeItem(graph_node) {
+function createOutputNodeItem(graph_node, derived_summary) {
   const title =
     graph_node.title ?? graph_node.label ?? graph_node.path ?? graph_node.key;
 
@@ -161,6 +187,7 @@ function createOutputNodeItem(graph_node) {
   }
 
   return {
+    derived_summary: derived_summary ?? undefined,
     id: graph_node.id,
     kind: 'node',
     node_kind: graph_node.kind,
@@ -172,11 +199,13 @@ function createOutputNodeItem(graph_node) {
 
 /**
  * @param {{ kind?: string, path: string, status?: string, title: string }} target
+ * @param {import('./output-view.types.ts').OutputDerivedSummary | null} derived_summary
  * @returns {$k$$l$output$j$view$k$types$k$ts.OutputResolvedLinkTarget}
  */
-function createResolvedLinkTarget(target) {
+function createResolvedLinkTarget(target, derived_summary) {
   /** @type {$k$$l$output$j$view$k$types$k$ts.OutputResolvedLinkTarget} */
   const resolved_target = {
+    derived_summary: derived_summary ?? undefined,
     path: target.path,
     title: target.title,
   };