patram 0.0.2 → 0.2.0

package/lib/cli-help-metadata.js

@@ -0,0 +1,552 @@
+/* eslint-disable max-lines */
+/**
+ * @import {
+ *   CliCommandName,
+ *   CliHelpTopicName,
+ * } from './parse-cli-arguments.types.ts';
+ */
+
+/**
+ * @typedef {{
+ *   description: string,
+ *   label: string,
+ * }} CliHelpOption
+ */
+
+/**
+ * @typedef {{
+ *   allowed_option_names: Set<string>,
+ *   examples: string[],
+ *   extra_positionals_message: string,
+ *   help_topics: CliHelpTopicName[],
+ *   max_positionals: number,
+ *   min_positionals: number,
+ *   missing_argument_examples: string[],
+ *   missing_argument_label: string | null,
+ *   missing_usage_lines: string[],
+ *   option_column_width: number,
+ *   options: CliHelpOption[],
+ *   related: CliCommandName[],
+ *   root_summary: string,
+ *   summary: string,
+ *   syntax_lines?: string[],
+ *   usage_lines: string[],
+ * }} CliCommandDefinition
+ */
+
+/**
+ * @typedef {{
+ *   examples: string[],
+ *   lead: string,
+ *   operators: CliHelpOption[],
+ *   relation_terms: CliHelpOption[],
+ *   terms: string[],
+ *   usage_lines: string[],
+ * }} CliHelpTopicDefinition
+ */
+
+export const COMMAND_NAMES = /** @type {const} */ ([
+  'check',
+  'query',
+  'queries',
+  'show',
+]);
+
+export const HELP_TOPIC_NAMES = /** @type {const} */ (['query-language']);
+
+export const GLOBAL_OPTION_NAMES = new Set([
+  'help',
+  'plain',
+  'json',
+  'color',
+  'no-color',
+]);
+
+const ROOT_HELP_SUMMARY = 'Patram explores docs and how they link to sources.';
+const ROOT_HELP_USAGE_LINES = [
+  'patram <command> [options]',
+  'patram help [command]',
+];
+const ROOT_HELP_GLOBAL_OPTIONS = [
+  '--help',
+  '--plain',
+  '--json',
+  '--color <auto|always|never>',
+  '--no-color',
+];
+
+/** @type {Record<CliCommandName, CliCommandDefinition>} */
+const COMMAND_DEFINITIONS = {
+  check: {
+    allowed_option_names: new Set(),
+    examples: [
+      'patram check',
+      'patram check docs',
+      'patram check docs/patram.md',
+    ],
+    extra_positionals_message: 'Check accepts at most one path.',
+    help_topics: [],
+    max_positionals: 1,
+    min_positionals: 0,
+    missing_argument_examples: [],
+    missing_argument_label: null,
+    missing_usage_lines: ['patram check [path]'],
+    option_column_width: 10,
+    options: [
+      {
+        description: 'Print plain text output',
+        label: '--plain',
+      },
+      {
+        description: 'Print JSON output',
+        label: '--json',
+      },
+    ],
+    related: ['show', 'query'],
+    root_summary: 'Validate a project, directory, or file',
+    summary:
+      'Validate a project, directory, or file and report graph diagnostics.',
+    usage_lines: ['patram check [path] [options]'],
+  },
+  query: {
+    allowed_option_names: new Set([
+      'explain',
+      'limit',
+      'lint',
+      'offset',
+      'where',
+    ]),
+    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 "kind=plan and none(in:tracked_in, kind=decision)"',
+      'patram query --where "count(in:decided_by, kind=task) = 0"',
+      'patram query ready-tasks --explain',
+      'patram query --where "kind=decision and status=accepted and count(in:decided_by, kind=task) = 0" --lint',
+      'patram query active-plans --limit 10 --offset 20',
+    ],
+    extra_positionals_message:
+      'Query accepts either "--where" or a stored query name.',
+    help_topics: ['query-language'],
+    max_positionals: 1,
+    min_positionals: 0,
+    missing_argument_examples: [
+      'patram query active-plans',
+      'patram query --where "tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md"',
+    ],
+    missing_argument_label: '<name> or --where "<clause>"',
+    missing_usage_lines: [
+      'patram query <name> [options]',
+      'patram query --where "<clause>" [options]',
+    ],
+    option_column_width: 19,
+    options: [
+      {
+        description: 'Run an ad hoc query instead of a stored query',
+        label: '--where <clause>',
+      },
+      {
+        description: 'Skip the first N matches',
+        label: '--offset <number>',
+      },
+      {
+        description: 'Limit the number of matches',
+        label: '--limit <number>',
+      },
+      {
+        description: 'Explain the resolved query without rendering results',
+        label: '--explain',
+      },
+      {
+        description: 'Validate syntax and relation references only',
+        label: '--lint',
+      },
+      {
+        description: 'Print plain text output',
+        label: '--plain',
+      },
+      {
+        description: 'Print JSON output',
+        label: '--json',
+      },
+    ],
+    related: ['queries', 'show'],
+    root_summary: 'Run a stored query or an ad hoc where clause',
+    summary:
+      'Run a stored query or an ad hoc where clause against graph nodes.',
+    syntax_lines: [
+      'id=<value> | kind=<value> | path=<value> | status=<value>',
+      'id^=<prefix> | path^=<prefix> | title~<text>',
+      '<field> in [<value>, ...] | <field> not in [<value>, ...]',
+      '<relation>:* | <relation>=<target-id>',
+      'any(<traversal>, <term> and <term>)',
+      'none(<traversal>, <term> and <term>)',
+      'count(<traversal>, <term> and <term>) <comparison> <number>',
+    ],
+    usage_lines: [
+      'patram query <name> [options]',
+      'patram query --where "<clause>" [options]',
+    ],
+  },
+  queries: {
+    allowed_option_names: new Set(),
+    examples: ['patram queries'],
+    extra_positionals_message: 'Queries does not accept positional arguments.',
+    help_topics: [],
+    max_positionals: 0,
+    min_positionals: 0,
+    missing_argument_examples: [],
+    missing_argument_label: null,
+    missing_usage_lines: ['patram queries'],
+    option_column_width: 10,
+    options: [
+      {
+        description: 'Print plain text output',
+        label: '--plain',
+      },
+      {
+        description: 'Print JSON output',
+        label: '--json',
+      },
+    ],
+    related: ['query'],
+    root_summary: 'List stored queries',
+    summary: 'List the stored queries defined in the project configuration.',
+    usage_lines: ['patram queries [options]'],
+  },
+  show: {
+    allowed_option_names: new Set(),
+    examples: ['patram show docs/patram.md', 'patram show lib/patram-cli.js'],
+    extra_positionals_message: 'Show accepts exactly one file path.',
+    help_topics: [],
+    max_positionals: 1,
+    min_positionals: 1,
+    missing_argument_examples: [
+      'patram show docs/patram.md',
+      'patram show lib/patram-cli.js',
+    ],
+    missing_argument_label: '<file>',
+    missing_usage_lines: ['patram show <file>'],
+    option_column_width: 10,
+    options: [
+      {
+        description: 'Print plain text output',
+        label: '--plain',
+      },
+      {
+        description: 'Print JSON output',
+        label: '--json',
+      },
+    ],
+    related: ['query', 'check'],
+    root_summary: 'Print a file with resolved links',
+    summary:
+      'Print one source file with indexed links resolved against the graph.',
+    usage_lines: ['patram show <file> [options]'],
+  },
+};
+
+/** @type {Record<CliHelpTopicName, CliHelpTopicDefinition>} */
+const HELP_TOPIC_DEFINITIONS = {
+  'query-language': {
+    examples: [
+      'kind=decision and status=accepted',
+      'path^=docs/plans/',
+      'title~query',
+      'tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md',
+      'implements_command=command:query',
+      'status not in [done, dropped, superseded]',
+      'any(in:tracked_in, kind=task and status in [pending, ready, in_progress, blocked])',
+      'none(in:tracked_in, kind=decision)',
+      'count(in:decided_by, kind=task) = 0',
+      'not uses_term=term:graph',
+    ],
+    lead: 'Query language filters graph nodes with field, relation, traversal, and aggregate terms.',
+    operators: [
+      {
+        description: 'Exact field match or exact count comparison',
+        label: '=',
+      },
+      {
+        description: 'Prefix match for id and path',
+        label: '^=',
+      },
+      {
+        description: 'Contains text for title',
+        label: '~',
+      },
+      {
+        description: 'Set membership for supported fields',
+        label: 'in',
+      },
+      {
+        description: 'Set exclusion for supported fields',
+        label: 'not in',
+      },
+      {
+        description: 'Negate one term',
+        label: 'not',
+      },
+      {
+        description: 'Combine terms',
+        label: 'and',
+      },
+      {
+        description: 'Count comparisons',
+        label: '!= < > >= <=',
+      },
+    ],
+    relation_terms: [
+      {
+        description: 'Match nodes with at least one outgoing relation',
+        label: '<relation>:*',
+      },
+      {
+        description: 'Match nodes linked to an exact target id',
+        label: '<relation>=<target-id>',
+      },
+      {
+        description: 'Traverse one incoming relation hop',
+        label: 'in:<relation>',
+      },
+      {
+        description: 'Traverse one outgoing relation hop',
+        label: 'out:<relation>',
+      },
+    ],
+    terms: [
+      'Exact match: id, kind, path, status',
+      'Prefix match: id, path',
+      'Contains text: title',
+      'Set membership: id, kind, path, status, title',
+    ],
+    usage_lines: [
+      '<field>=<value>',
+      'id^=<prefix>',
+      'path^=<prefix>',
+      'title~<text>',
+      '<field> in [<value>, ...]',
+      '<field> not in [<value>, ...]',
+      '<relation>:*',
+      '<relation>=<target-id>',
+      'any(<traversal>, <term> and <term>)',
+      'none(<traversal>, <term> and <term>)',
+      'count(<traversal>, <term> and <term>) <comparison> <number>',
+      'not <term>',
+      '<term> and <term>',
+    ],
+  },
+};
+
+/**
+ * @returns {{ global_options: string[], summary: string, usage_lines: string[] }}
+ */
+export function getRootHelpDefinition() {
+  return {
+    global_options: ROOT_HELP_GLOBAL_OPTIONS,
+    summary: ROOT_HELP_SUMMARY,
+    usage_lines: ROOT_HELP_USAGE_LINES,
+  };
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @returns {CliCommandDefinition}
+ */
+export function getCommandDefinition(command_name) {
+  return COMMAND_DEFINITIONS[command_name];
+}
+
+/**
+ * @param {CliHelpTopicName} help_topic_name
+ * @returns {CliHelpTopicDefinition}
+ */
+export function getHelpTopicDefinition(help_topic_name) {
+  return HELP_TOPIC_DEFINITIONS[help_topic_name];
+}
+
+/**
+ * @param {string | undefined} command_name
+ * @returns {command_name is CliCommandName}
+ */
+export function isCommandName(command_name) {
+  return COMMAND_NAMES.includes(
+    /** @type {CliCommandName} */ (command_name ?? ''),
+  );
+}
+
+/**
+ * @param {string | undefined} help_topic_name
+ * @returns {help_topic_name is CliHelpTopicName}
+ */
+export function isHelpTopicName(help_topic_name) {
+  return HELP_TOPIC_NAMES.includes(
+    /** @type {CliHelpTopicName} */ (help_topic_name ?? ''),
+  );
+}
+
+/**
+ * @param {string} input_text
+ * @returns {CliCommandName | undefined}
+ */
+export function findCommandSuggestion(input_text) {
+  return /** @type {CliCommandName | undefined} */ (
+    findCloseMatch(input_text, COMMAND_NAMES)
+  );
+}
+
+/**
+ * @param {string} input_text
+ * @returns {CliCommandName | CliHelpTopicName | undefined}
+ */
+export function findHelpTargetSuggestion(input_text) {
+  return /** @type {CliCommandName | CliHelpTopicName | undefined} */ (
+    findCloseMatch(input_text, [...COMMAND_NAMES, ...HELP_TOPIC_NAMES])
+  );
+}
+
+/**
+ * @param {string} input_text
+ * @param {CliCommandName | undefined} command_name
+ * @returns {string | undefined}
+ */
+export function findOptionSuggestion(input_text, command_name) {
+  const candidates = listOptionLabels(command_name);
+
+  return findCloseMatch(input_text, candidates);
+}
+
+/**
+ * @returns {CliCommandName[]}
+ */
+export function listCommandNames() {
+  return [...COMMAND_NAMES];
+}
+
+/**
+ * @returns {CliHelpTopicName[]}
+ */
+export function listHelpTopicNames() {
+  return [...HELP_TOPIC_NAMES];
+}
+
+/**
+ * @param {CliCommandName | undefined} command_name
+ * @returns {string[]}
+ */
+function listOptionLabels(command_name) {
+  const option_labels = new Set(
+    [...GLOBAL_OPTION_NAMES].map((option_name) => `--${option_name}`),
+  );
+
+  if (command_name) {
+    for (const option_name of getCommandDefinition(command_name)
+      .allowed_option_names) {
+      option_labels.add(`--${option_name}`);
+    }
+  } else {
+    option_labels.add('--limit');
+    option_labels.add('--offset');
+    option_labels.add('--where');
+  }
+
+  return [...option_labels];
+}
+
+/**
+ * @param {string} input_text
+ * @param {readonly string[]} candidates
+ * @returns {string | undefined}
+ */
+function findCloseMatch(input_text, candidates) {
+  let best_candidate;
+  let best_score = 0;
+
+  for (const candidate of candidates) {
+    const score = scoreCandidate(input_text, candidate);
+
+    if (score > best_score) {
+      best_candidate = candidate;
+      best_score = score;
+    }
+  }
+
+  if (best_score < 0.6) {
+    return undefined;
+  }
+
+  return best_candidate;
+}
+
+/**
+ * @param {string} input_text
+ * @param {string} candidate
+ * @returns {number}
+ */
+function scoreCandidate(input_text, candidate) {
+  const max_length = Math.max(input_text.length, candidate.length);
+
+  if (max_length === 0) {
+    return 1;
+  }
+
+  return (
+    1 - calculateDamerauLevenshteinDistance(input_text, candidate) / max_length
+  );
+}
+
+/**
+ * @param {string} left_text
+ * @param {string} right_text
+ * @returns {number}
+ */
+function calculateDamerauLevenshteinDistance(left_text, right_text) {
+  /** @type {number[][]} */
+  const matrix = Array.from({ length: left_text.length + 1 }, () =>
+    Array(right_text.length + 1).fill(0),
+  );
+
+  for (let left_index = 0; left_index <= left_text.length; left_index += 1) {
+    matrix[left_index][0] = left_index;
+  }
+
+  for (
+    let right_index = 0;
+    right_index <= right_text.length;
+    right_index += 1
+  ) {
+    matrix[0][right_index] = right_index;
+  }
+
+  for (let left_index = 1; left_index <= left_text.length; left_index += 1) {
+    for (
+      let right_index = 1;
+      right_index <= right_text.length;
+      right_index += 1
+    ) {
+      const substitution_cost =
+        left_text[left_index - 1] === right_text[right_index - 1] ? 0 : 1;
+
+      matrix[left_index][right_index] = Math.min(
+        matrix[left_index - 1][right_index] + 1,
+        matrix[left_index][right_index - 1] + 1,
+        matrix[left_index - 1][right_index - 1] + substitution_cost,
+      );
+
+      if (
+        left_index > 1 &&
+        right_index > 1 &&
+        left_text[left_index - 1] === right_text[right_index - 2] &&
+        left_text[left_index - 2] === right_text[right_index - 1]
+      ) {
+        matrix[left_index][right_index] = Math.min(
+          matrix[left_index][right_index],
+          matrix[left_index - 2][right_index - 2] + 1,
+        );
+      }
+    }
+  }
+
+  return matrix[left_text.length][right_text.length];
+}

package/lib/command-output.js

@@ -0,0 +1,83 @@
+/**
+ * @import { ParsedCliArguments } from './parse-cli-arguments.types.ts';
+ * @import { OutputView } from './output-view.types.ts';
+ */
+
+import process from 'node:process';
+
+import { renderOutputView } from './render-output-view.js';
+import { resolveOutputMode } from './resolve-output-mode.js';
+import { writePagedOutput } from './write-paged-output.js';
+
+/**
+ * TTY and pager output control.
+ *
+ * Resolves the final output mode and switches between direct stdout writes and
+ * interactive pager output.
+ *
+ * Kind: output
+ * Status: active
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/tty-pager-output.md
+ * @patram
+ * @see {@link ./render-output-view.js}
+ * @see {@link ../docs/decisions/tty-pager-output.md}
+ */
+
+/**
+ * @param {{ stdout: { isTTY?: boolean, write(chunk: string): boolean }, write_paged_output?: (output_text: string) => Promise<void> }} io_context
+ * @param {ParsedCliArguments} parsed_command
+ * @param {OutputView} output_view
+ * @returns {Promise<void>}
+ */
+export async function writeCommandOutput(
+  io_context,
+  parsed_command,
+  output_view,
+) {
+  const rendered_output = await renderOutputView(
+    output_view,
+    resolveOutputMode(parsed_command, {
+      is_tty: io_context.stdout.isTTY === true,
+      no_color: process.env.NO_COLOR !== undefined,
+      term: process.env.TERM,
+    }),
+    parsed_command,
+  );
+
+  if (shouldPageCommandOutput(parsed_command, io_context.stdout)) {
+    await writeInteractiveOutput(io_context, rendered_output);
+
+    return;
+  }
+
+  io_context.stdout.write(rendered_output);
+}
+
+/**
+ * @param {ParsedCliArguments} parsed_command
+ * @param {{ isTTY?: boolean }} output_stream
+ * @returns {boolean}
+ */
+export function shouldPageCommandOutput(parsed_command, output_stream) {
+  return (
+    output_stream.isTTY === true &&
+    (parsed_command.command_name === 'query' ||
+      parsed_command.command_name === 'show')
+  );
+}
+
+/**
+ * @param {{ write_paged_output?: (output_text: string) => Promise<void> }} io_context
+ * @param {string} rendered_output
+ * @returns {Promise<void>}
+ */
+async function writeInteractiveOutput(io_context, rendered_output) {
+  if (io_context.write_paged_output) {
+    await io_context.write_paged_output(rendered_output);
+
+    return;
+  }
+
+  await writePagedOutput(rendered_output);
+}