patram 0.0.2 → 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

@@ -0,0 +1,161 @@
+/**
+ * @import { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView } from './output-view.types.ts';
+ */
+
+/**
+ * Render structured JSON output for one output view.
+ *
+ * @param {OutputView} output_view
+ * @returns {string}
+ */
+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`;
+  }
+
+  if (output_view.command === 'queries') {
+    return `${JSON.stringify(
+      {
+        queries: output_view.items.map(formatJsonStoredQuery),
+      },
+      null,
+      2,
+    )}\n`;
+  }
+
+  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`;
+  }
+
+  throw new Error('Unsupported output view command.');
+}
+
+/**
+ * @param {OutputNodeItem} output_item
+ * @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 {{ 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,
+    title: output_item.title,
+    path: output_item.path,
+  };
+
+  if (output_item.status) {
+    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;
+}
+
+/**
+ * @param {OutputStoredQueryItem} output_item
+ * @returns {{ name: string, where: string }}
+ */
+function formatJsonStoredQuery(output_item) {
+  return {
+    name: output_item.name,
+    where: output_item.where,
+  };
+}
+
+/**
+ * @param {OutputResolvedLinkItem} output_item
+ * @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: { 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,
+    target: {
+      title: output_item.target.title,
+      path: output_item.target.path,
+    },
+  };
+
+  if (output_item.target.kind) {
+    resolved_link.target.kind = output_item.target.kind;
+  }
+
+  if (output_item.target.status) {
+    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;
+}