patram 0.0.2 → 0.1.1

package/lib/render-check-output.js

@@ -0,0 +1,315 @@
+/**
+ * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ * @import { ResolvedOutputMode } from './output-view.types.ts';
+ */
+
+import { Ansis } from 'ansis';
+import stringWidth from 'string-width';
+
+/**
+ * Render check diagnostics for one output mode.
+ *
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {ResolvedOutputMode} output_mode
+ * @returns {string}
+ */
+export function renderCheckDiagnostics(diagnostics, output_mode) {
+  if (output_mode.renderer_name === 'json') {
+    return `${JSON.stringify(
+      {
+        diagnostics: diagnostics.map(formatJsonDiagnostic),
+      },
+      null,
+      2,
+    )}\n`;
+  }
+
+  if (output_mode.renderer_name === 'plain') {
+    return renderPlainCheckDiagnostics(diagnostics);
+  }
+
+  return renderRichCheckDiagnostics(diagnostics, createAnsi(output_mode));
+}
+
+/**
+ * Render the success summary for one check run.
+ *
+ * @param {number} source_file_count
+ * @param {ResolvedOutputMode} output_mode
+ * @returns {string}
+ */
+export function renderCheckSuccess(source_file_count, output_mode) {
+  if (output_mode.renderer_name === 'json') {
+    return `${JSON.stringify({ diagnostics: [] }, null, 2)}\n`;
+  }
+
+  if (output_mode.renderer_name === 'plain') {
+    return formatCheckSuccess(source_file_count);
+  }
+
+  const ansi = createAnsi(output_mode);
+  return `${ansi.green('Check passed.')}\n${ansi.gray(`Scanned ${source_file_count} ${pluralize('file', source_file_count)}. Found 0 errors.`)}\n`;
+}
+
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @returns {string}
+ */
+function renderPlainCheckDiagnostics(diagnostics) {
+  const grouped_diagnostics = groupDiagnosticsByPath(diagnostics);
+  const diagnostic_prefix_width = measureMaxDiagnosticPrefixWidth(diagnostics);
+  return `${grouped_diagnostics
+    .map((diagnostic_group) =>
+      formatPlainDiagnosticGroup(diagnostic_group, diagnostic_prefix_width),
+    )
+    .join('\n\n')}\n\n${formatPlainSummary(diagnostics)}\n`;
+}
+
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function renderRichCheckDiagnostics(diagnostics, ansi) {
+  const grouped_diagnostics = groupDiagnosticsByPath(diagnostics);
+  const diagnostic_prefix_width = measureMaxDiagnosticPrefixWidth(diagnostics);
+  return `${grouped_diagnostics
+    .map((diagnostic_group) =>
+      formatRichDiagnosticGroup(
+        diagnostic_group,
+        diagnostic_prefix_width,
+        ansi,
+      ),
+    )
+    .join('\n\n')}\n\n${formatRichSummary(diagnostics, ansi)}\n`;
+}
+
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @returns {Array<{ diagnostics: PatramDiagnostic[], path: string }>}
+ */
+function groupDiagnosticsByPath(diagnostics) {
+  /** @type {Array<{ diagnostics: PatramDiagnostic[], path: string }>} */
+  const grouped_diagnostics = [];
+  /** @type {Map<string, { diagnostics: PatramDiagnostic[], path: string }>} */
+  const grouped_diagnostics_by_path = new Map();
+
+  for (const diagnostic of diagnostics) {
+    let diagnostic_group = grouped_diagnostics_by_path.get(diagnostic.path);
+
+    if (!diagnostic_group) {
+      diagnostic_group = {
+        diagnostics: [],
+        path: diagnostic.path,
+      };
+      grouped_diagnostics_by_path.set(diagnostic.path, diagnostic_group);
+      grouped_diagnostics.push(diagnostic_group);
+    }
+
+    diagnostic_group.diagnostics.push(diagnostic);
+  }
+
+  return grouped_diagnostics;
+}
+
+/**
+ * @param {{ diagnostics: PatramDiagnostic[], path: string }} diagnostic_group
+ * @param {number} diagnostic_prefix_width
+ * @returns {string}
+ */
+function formatPlainDiagnosticGroup(diagnostic_group, diagnostic_prefix_width) {
+  return `${formatDiagnosticGroupHeader(diagnostic_group.path)}\n${diagnostic_group.diagnostics
+    .map((diagnostic) =>
+      formatPlainDiagnosticRow(diagnostic, diagnostic_prefix_width),
+    )
+    .join('\n')}`;
+}
+
+/**
+ * @param {PatramDiagnostic} diagnostic
+ * @param {number} diagnostic_prefix_width
+ * @returns {string}
+ */
+function formatPlainDiagnosticRow(diagnostic, diagnostic_prefix_width) {
+  const diagnostic_prefix = formatDiagnosticPrefix(diagnostic);
+  return `${diagnostic_prefix}${createDiagnosticCodePadding(diagnostic_prefix, diagnostic_prefix_width)}  ${diagnostic.code}`;
+}
+
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @returns {string}
+ */
+function formatPlainSummary(diagnostics) {
+  const error_count = countDiagnosticsByLevel(diagnostics, 'error');
+  const warning_count = countDiagnosticsByLevel(diagnostics, 'warning');
+  const problem_count = diagnostics.length;
+
+  return `\u2716 ${problem_count} ${pluralize('problem', problem_count)} (${error_count} ${pluralize('error', error_count)}, ${warning_count} ${pluralize('warning', warning_count)})`;
+}
+
+/**
+ * @param {{ diagnostics: PatramDiagnostic[], path: string }} diagnostic_group
+ * @param {number} diagnostic_prefix_width
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function formatRichDiagnosticGroup(
+  diagnostic_group,
+  diagnostic_prefix_width,
+  ansi,
+) {
+  return `${ansi.green(formatDiagnosticGroupHeader(diagnostic_group.path))}\n${diagnostic_group.diagnostics
+    .map((diagnostic) =>
+      formatRichDiagnosticRow(diagnostic, diagnostic_prefix_width, ansi),
+    )
+    .join('\n')}`;
+}
+
+/**
+ * @param {PatramDiagnostic} diagnostic
+ * @param {number} diagnostic_prefix_width
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function formatRichDiagnosticRow(diagnostic, diagnostic_prefix_width, ansi) {
+  const location = `${diagnostic.line}:${diagnostic.column}`;
+  const diagnostic_prefix = formatDiagnosticPrefix(diagnostic);
+  return `  ${ansi.gray(location)}  ${formatRichDiagnosticLevel(diagnostic.level, ansi)}  ${diagnostic.message}${createDiagnosticCodePadding(diagnostic_prefix, diagnostic_prefix_width)}  ${ansi.gray(diagnostic.code)}`;
+}
+
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function formatRichSummary(diagnostics, ansi) {
+  return ansi.red(formatPlainSummary(diagnostics));
+}
+
+/**
+ * @param {PatramDiagnostic} diagnostic
+ * @returns {{ code: string, column: number, level: 'error', line: number, message: string, path: string }}
+ */
+function formatJsonDiagnostic(diagnostic) {
+  return {
+    path: diagnostic.path,
+    line: diagnostic.line,
+    column: diagnostic.column,
+    level: diagnostic.level,
+    code: diagnostic.code,
+    message: diagnostic.message,
+  };
+}
+
+/**
+ * @param {number} source_file_count
+ * @returns {string}
+ */
+function formatCheckSuccess(source_file_count) {
+  return `Check passed.\nScanned ${source_file_count} ${pluralize('file', source_file_count)}. Found 0 errors.\n`;
+}
+
+/**
+ * @param {PatramDiagnostic} diagnostic
+ */
+function formatDiagnosticPrefix(diagnostic) {
+  return `  ${diagnostic.line}:${diagnostic.column}  ${diagnostic.level}  ${diagnostic.message}`;
+}
+
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ */
+function measureMaxDiagnosticPrefixWidth(diagnostics) {
+  let max_width = 0;
+
+  for (const diagnostic of diagnostics) {
+    const diagnostic_prefix_width = stringWidth(
+      formatDiagnosticPrefix(diagnostic),
+    );
+
+    if (diagnostic_prefix_width > max_width) {
+      max_width = diagnostic_prefix_width;
+    }
+  }
+
+  return max_width;
+}
+
+/**
+ * @param {string} diagnostic_prefix
+ * @param {number} diagnostic_prefix_width
+ */
+function createDiagnosticCodePadding(
+  diagnostic_prefix,
+  diagnostic_prefix_width,
+) {
+  return ' '.repeat(
+    Math.max(0, diagnostic_prefix_width - stringWidth(diagnostic_prefix)),
+  );
+}
+
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {'error' | 'warning'} level
+ */
+function countDiagnosticsByLevel(diagnostics, level) {
+  let count = 0;
+
+  for (const diagnostic of diagnostics) {
+    if (diagnostic.level === level) {
+      count += 1;
+    }
+  }
+
+  return count;
+}
+
+/**
+ * @param {'error' | 'warning'} level
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function formatRichDiagnosticLevel(level, ansi) {
+  if (level === 'warning') {
+    return ansi.yellow(level);
+  }
+
+  return ansi.red(level);
+}
+
+/**
+ * @param {string} noun
+ * @param {number} count
+ */
+function pluralize(noun, count) {
+  if (count === 1) {
+    return noun;
+  }
+
+  return `${noun}s`;
+}
+
+/**
+ * @param {ResolvedOutputMode} output_mode
+ */
+function createAnsi(output_mode) {
+  return new Ansis(output_mode.color_enabled ? 3 : 0);
+}
+
+/**
+ * @param {string} path
+ */
+function formatDiagnosticGroupHeader(path) {
+  return `${resolveDiagnosticPathType(path)} ${path}`;
+}
+
+/**
+ * @param {string} path
+ */
+function resolveDiagnosticPathType(path) {
+  if (path.endsWith('.json')) {
+    return 'file';
+  }
+
+  return 'document';
+}

package/lib/render-json-output.js

@@ -0,0 +1,108 @@
+/**
+ * @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(
+      {
+        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 {{ 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 }} */
+  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;
+  }
+
+  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: { 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 } }} */
+  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;
+  }
+
+  return resolved_link;
+}

package/lib/render-output-view.js

@@ -0,0 +1,193 @@
+/** @import * as $k$$l$output$j$view$k$types$k$ts from './output-view.types.ts'; */
+/**
+ * @import { GraphNode } from './build-graph.types.ts';
+ * @import { ParsedCliArguments } from './parse-cli-arguments.types.ts';
+ * @import { OutputStoredQueryItem, OutputView, ResolvedOutputMode, ShowOutputView } from './output-view.types.ts';
+ */
+
+import { renderJsonOutput } from './render-json-output.js';
+import { renderPlainOutput } from './render-plain-output.js';
+import { renderRichOutput } from './render-rich-output.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}
+ */
+
+/**
+ * Create a shared output view from one command result.
+ *
+ * @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
+ * @returns {OutputView}
+ */
+export function createOutputView(command_name, command_items, command_options) {
+  if (command_name === 'query') {
+    return createQueryOutputView(
+      /** @type {GraphNode[]} */ (command_items),
+      command_options,
+    );
+  }
+
+  if (command_name === 'queries') {
+    return createStoredQueriesOutputView(
+      /** @type {OutputStoredQueryItem[]} */ (command_items),
+    );
+  }
+
+  throw new Error(`Unsupported output view command "${command_name}".`);
+}
+
+/**
+ * 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
+ * @returns {ShowOutputView}
+ */
+export function createShowOutputView(show_output) {
+  return {
+    command: 'show',
+    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),
+    })),
+    path: show_output.path,
+    rendered_source: show_output.rendered_source,
+    source: show_output.source,
+    summary: {
+      count: show_output.resolved_links.length,
+      kind: 'resolved_link_list',
+    },
+  };
+}
+
+/**
+ * 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,
+  });
+}
+
+/**
+ * @param {GraphNode[]} graph_nodes
+ * @param {{ hints?: string[], limit?: number, offset?: number, total_count?: number }=} command_options
+ * @returns {OutputView}
+ */
+function createQueryOutputView(graph_nodes, command_options = {}) {
+  const total_count = command_options.total_count ?? graph_nodes.length;
+
+  return {
+    command: 'query',
+    hints:
+      command_options.hints ??
+      (total_count === 0 ? ['Try: patram query --where "kind=task"'] : []),
+    items: graph_nodes.map(createOutputNodeItem),
+    summary: {
+      count: graph_nodes.length,
+      kind: 'result_list',
+      limit: command_options.limit ?? graph_nodes.length,
+      offset: command_options.offset ?? 0,
+      total_count,
+    },
+  };
+}
+
+/**
+ * @param {{ name: string, where: string }[]} stored_queries
+ * @returns {OutputView}
+ */
+function createStoredQueriesOutputView(stored_queries) {
+  return {
+    command: 'queries',
+    hints: [],
+    items: stored_queries.map((stored_query) => ({
+      kind: 'stored_query',
+      name: stored_query.name,
+      where: stored_query.where,
+    })),
+    summary: {
+      count: stored_queries.length,
+      kind: 'stored_query_list',
+    },
+  };
+}
+
+/**
+ * @param {GraphNode} graph_node
+ * @returns {$k$$l$output$j$view$k$types$k$ts.OutputNodeItem}
+ */
+function createOutputNodeItem(graph_node) {
+  const title =
+    graph_node.title ?? graph_node.label ?? graph_node.path ?? graph_node.key;
+
+  if (!title || !graph_node.path) {
+    throw new Error(
+      `Expected graph node "${graph_node.id}" to have a title and path.`,
+    );
+  }
+
+  return {
+    id: graph_node.id,
+    kind: 'node',
+    node_kind: graph_node.kind,
+    path: graph_node.path,
+    status: graph_node.status,
+    title,
+  };
+}
+
+/**
+ * @param {{ kind?: string, path: string, status?: string, title: string }} target
+ * @returns {$k$$l$output$j$view$k$types$k$ts.OutputResolvedLinkTarget}
+ */
+function createResolvedLinkTarget(target) {
+  /** @type {$k$$l$output$j$view$k$types$k$ts.OutputResolvedLinkTarget} */
+  const resolved_target = {
+    path: target.path,
+    title: target.title,
+  };
+
+  if (target.kind && target.kind !== 'document') {
+    resolved_target.kind = target.kind;
+  }
+
+  if (target.status) {
+    resolved_target.status = target.status;
+  }
+
+  return resolved_target;
+}