patram 0.0.2 → 0.1.1

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

@@ -0,0 +1,273 @@
+/**
+ * @typedef {import('./parse-cli-arguments.types.ts').CliCommandName} CliCommandName
+ * @typedef {import('./parse-cli-arguments.types.ts').CliOutputMode} CliOutputMode
+ * @typedef {{ kind: string, name?: string, rawName?: string, value?: string | boolean }} CliOptionToken
+ * @typedef {{ color?: string, json?: boolean, limit?: string, 'no-color'?: boolean, offset?: string, plain?: boolean, where?: string }} CliOptionValues
+ * @typedef {{ option_tokens: CliOptionToken[], positionals: string[], values: CliOptionValues }} ParsedCommandLine
+ * @typedef {{ allowed_option_names: Set<string>, extra_positionals_message: string, max_positionals: number, min_positionals: number, missing_positionals_message: string }} CommandSchema
+ */
+
+import { findInvalidColorMode } from './parse-cli-color-options.js';
+import { findInvalidQueryPagination } from './parse-cli-query-pagination.js';
+
+const GLOBAL_OPTION_NAMES = new Set(['plain', 'json', 'color', 'no-color']);
+export const CLI_OPTIONS = /** @type {const} */ ({
+  color: { type: 'string' },
+  json: { type: 'boolean' },
+  limit: { type: 'string' },
+  'no-color': { type: 'boolean' },
+  offset: { type: 'string' },
+  plain: { type: 'boolean' },
+  where: { type: 'string' },
+});
+/** @type {Record<CliCommandName, CommandSchema>} */
+const COMMAND_SCHEMAS = {
+  check: createCommandSchema(0, 1, 'Check accepts at most one path.'),
+  queries: createCommandSchema(
+    0,
+    0,
+    'Queries does not accept positional arguments.',
+  ),
+  query: {
+    ...createCommandSchema(
+      0,
+      1,
+      'Query accepts either "--where" or a stored query name.',
+    ),
+    allowed_option_names: new Set(['limit', 'offset', 'where']),
+  },
+  show: createCommandSchema(
+    1,
+    1,
+    'Show accepts exactly one file path.',
+    'Show requires a file path.',
+  ),
+};
+/**
+ * @param {string | undefined} command_name
+ * @returns {command_name is CliCommandName}
+ */
+export function isCommandName(command_name) {
+  return (
+    command_name === 'check' ||
+    command_name === 'query' ||
+    command_name === 'queries' ||
+    command_name === 'show'
+  );
+}
+/**
+ * @param {CliOptionToken[]} tokens
+ * @returns {CliOptionToken[]}
+ */
+export function collectOptionTokens(tokens) {
+  return tokens.filter((token) => token.kind === 'option');
+}
+/**
+ * @param {CliCommandName} command_name
+ * @param {ParsedCommandLine} command_line
+ * @returns {string | null}
+ */
+export function validateParsedCommand(command_name, command_line) {
+  const command_positionals = command_line.positionals.slice(1);
+
+  return (
+    findUnknownOption(command_line.option_tokens) ??
+    findInvalidCommandOption(command_name, command_line.option_tokens) ??
+    findMissingOptionValue(command_line.option_tokens) ??
+    findOutputModeConflict(command_line.values) ??
+    findInvalidColorMode(command_line.option_tokens) ??
+    findInvalidQueryPagination(command_line.option_tokens) ??
+    findInvalidQueryMode(
+      command_name,
+      command_line.values,
+      command_positionals,
+    ) ??
+    validateCommandPositionals(command_name, command_positionals)
+  );
+}
+/**
+ * @param {CliOptionValues} parsed_values
+ * @returns {CliOutputMode}
+ */
+export function resolveOutputMode(parsed_values) {
+  if (parsed_values.json) {
+    return 'json';
+  }
+
+  if (parsed_values.plain) {
+    return 'plain';
+  }
+
+  return 'default';
+}
+/**
+ * @param {CliCommandName} command_name
+ * @param {string[]} command_positionals
+ * @param {CliOptionValues} parsed_values
+ * @returns {string[]}
+ */
+export function buildCommandArguments(
+  command_name,
+  command_positionals,
+  parsed_values,
+) {
+  if (command_name === 'query' && parsed_values.where !== undefined) {
+    return ['--where', parsed_values.where];
+  }
+
+  return command_positionals;
+}
+
+/**
+ * @param {string} message
+ * @returns {{ message: string, success: false }}
+ */
+export function createParseError(message) {
+  return {
+    message,
+    success: false,
+  };
+}
+
+/**
+ * @param {CliOptionToken[]} option_tokens
+ * @returns {string | null}
+ */
+function findUnknownOption(option_tokens) {
+  for (const token of option_tokens) {
+    if (
+      token.name &&
+      token.rawName &&
+      !GLOBAL_OPTION_NAMES.has(token.name) &&
+      token.name !== 'limit' &&
+      token.name !== 'offset' &&
+      token.name !== 'where'
+    ) {
+      return `Unknown option "${token.rawName}".`;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @param {CliOptionToken[]} option_tokens
+ * @returns {string | null}
+ */
+function findInvalidCommandOption(command_name, option_tokens) {
+  const command_schema = COMMAND_SCHEMAS[command_name];
+
+  for (const token of option_tokens) {
+    if (!token.name || !token.rawName || GLOBAL_OPTION_NAMES.has(token.name)) {
+      continue;
+    }
+
+    if (!command_schema.allowed_option_names.has(token.name)) {
+      return `Option "${token.rawName}" is not valid for "${command_name}".`;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * @param {CliOptionToken[]} option_tokens
+ * @returns {string | null}
+ */
+function findMissingOptionValue(option_tokens) {
+  for (const token of option_tokens) {
+    if (token.name === 'where' && typeof token.value !== 'string') {
+      return 'Query requires a where clause.';
+    }
+
+    if (token.name === 'offset' && typeof token.value !== 'string') {
+      return 'Offset requires a value.';
+    }
+
+    if (token.name === 'limit' && typeof token.value !== 'string') {
+      return 'Limit requires a value.';
+    }
+
+    if (token.name === 'color' && typeof token.value !== 'string') {
+      return 'Color requires a value.';
+    }
+  }
+
+  return null;
+}
+
+/**
+ * @param {CliOptionValues} parsed_values
+ * @returns {string | null}
+ */
+function findOutputModeConflict(parsed_values) {
+  if (parsed_values.plain && parsed_values.json) {
+    return 'Output mode accepts at most one of "--plain" or "--json".';
+  }
+
+  return null;
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @param {CliOptionValues} parsed_values
+ * @param {string[]} command_positionals
+ * @returns {string | null}
+ */
+function findInvalidQueryMode(
+  command_name,
+  parsed_values,
+  command_positionals,
+) {
+  if (
+    command_name === 'query' &&
+    parsed_values.where !== undefined &&
+    command_positionals.length > 0
+  ) {
+    return 'Query accepts either "--where" or a stored query name.';
+  }
+
+  return null;
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @param {string[]} command_positionals
+ * @returns {string | null}
+ */
+function validateCommandPositionals(command_name, command_positionals) {
+  const command_schema = COMMAND_SCHEMAS[command_name];
+
+  if (command_positionals.length < command_schema.min_positionals) {
+    return command_schema.missing_positionals_message;
+  }
+
+  if (command_positionals.length > command_schema.max_positionals) {
+    return command_schema.extra_positionals_message;
+  }
+
+  return null;
+}
+
+/**
+ * @param {number} min_positionals
+ * @param {number} max_positionals
+ * @param {string} extra_positionals_message
+ * @param {string} missing_positionals_message
+ * @returns {CommandSchema}
+ */
+function createCommandSchema(
+  min_positionals,
+  max_positionals,
+  extra_positionals_message,
+  missing_positionals_message = '',
+) {
+  return {
+    allowed_option_names: new Set(),
+    extra_positionals_message,
+    max_positionals,
+    min_positionals,
+    missing_positionals_message,
+  };
+}

package/lib/parse-cli-arguments.js

@@ -0,0 +1,114 @@
+/**
+ * @typedef {import('./parse-cli-arguments-helpers.js').CliOptionValues} CliOptionValues
+ * @typedef {import('./parse-cli-arguments-helpers.js').ParsedCommandLine} ParsedCommandLine
+ * @typedef {import('./parse-cli-arguments.types.ts').ParseCliArgumentsResult} ParseCliArgumentsResult
+ */
+
+import { parseArgs } from 'node:util';
+
+import {
+  CLI_OPTIONS,
+  buildCommandArguments,
+  collectOptionTokens,
+  createParseError,
+  isCommandName,
+  resolveOutputMode,
+  validateParsedCommand,
+} from './parse-cli-arguments-helpers.js';
+import { resolveColorMode } from './parse-cli-color-options.js';
+import { buildQueryPagination } from './parse-cli-query-pagination.js';
+
+/**
+ * CLI argument parsing.
+ *
+ * Normalizes raw argv into one validated Patram command plus shared output and
+ * pagination options.
+ *
+ * Kind: cli
+ * Status: active
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/cli-argument-parser.md
+ * @patram
+ * @see {@link ./patram-cli.js}
+ * @see {@link ../docs/decisions/cli-argument-parser.md}
+ */
+
+/**
+ * Parse the CLI arguments into one validated command result.
+ *
+ * @param {string[]} cli_arguments
+ * @returns {ParseCliArgumentsResult}
+ */
+export function parseCliArguments(cli_arguments) {
+  const command_line = parseCommandLine(cli_arguments);
+
+  if (!command_line.success) {
+    return command_line;
+  }
+
+  const command_name = command_line.value.positionals[0];
+
+  if (!isCommandName(command_name)) {
+    return createParseError('Unknown command.');
+  }
+
+  const validation_message = validateParsedCommand(
+    command_name,
+    command_line.value,
+  );
+
+  if (validation_message) {
+    return createParseError(validation_message);
+  }
+
+  const command_positionals = command_line.value.positionals.slice(1);
+
+  return {
+    success: true,
+    value: {
+      color_mode: resolveColorMode(command_line.value.option_tokens),
+      command_arguments: buildCommandArguments(
+        command_name,
+        command_positionals,
+        command_line.value.values,
+      ),
+      command_name,
+      output_mode: resolveOutputMode(command_line.value.values),
+      ...buildQueryPagination(command_line.value.values),
+    },
+  };
+}
+
+/**
+ * @param {string[]} cli_arguments
+ * @returns {{ success: true, value: ParsedCommandLine } | { message: string, success: false }}
+ */
+function parseCommandLine(cli_arguments) {
+  try {
+    const parsed_arguments = parseArgs({
+      allowPositionals: true,
+      args: cli_arguments,
+      options: CLI_OPTIONS,
+      strict: false,
+      tokens: true,
+    });
+    const parsed_values = /** @type {CliOptionValues} */ (
+      parsed_arguments.values
+    );
+
+    return {
+      success: true,
+      value: {
+        option_tokens: collectOptionTokens(parsed_arguments.tokens ?? []),
+        positionals: parsed_arguments.positionals,
+        values: parsed_values,
+      },
+    };
+  } catch (error) {
+    if (error instanceof Error) {
+      return createParseError(error.message);
+    }
+
+    throw error;
+  }
+}

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

@@ -0,0 +1,24 @@
+export type CliCommandName = 'check' | 'query' | 'queries' | 'show';
+
+export type CliOutputMode = 'default' | 'plain' | 'json';
+
+export type CliColorMode = 'auto' | 'always' | 'never';
+
+export interface ParsedCliArguments {
+  color_mode: CliColorMode;
+  command_arguments: string[];
+  command_name: CliCommandName;
+  output_mode: CliOutputMode;
+  query_limit?: number;
+  query_offset?: number;
+}
+
+export type ParseCliArgumentsResult =
+  | {
+      success: true;
+      value: ParsedCliArguments;
+    }
+  | {
+      message: string;
+      success: false;
+    };

package/lib/parse-cli-color-options.js

@@ -0,0 +1,44 @@
+/**
+ * @typedef {import('./parse-cli-arguments-helpers.js').CliOptionToken} CliOptionToken
+ * @typedef {import('./parse-cli-arguments.types.ts').CliColorMode} CliColorMode
+ */
+
+const VALID_COLOR_MODES = new Set(['auto', 'always', 'never']);
+
+/**
+ * @param {CliOptionToken[]} option_tokens
+ * @returns {CliColorMode}
+ */
+export function resolveColorMode(option_tokens) {
+  let color_mode = 'auto';
+
+  for (const token of option_tokens) {
+    if (token.name === 'no-color') {
+      color_mode = 'never';
+    }
+
+    if (token.name === 'color' && typeof token.value === 'string') {
+      color_mode = token.value;
+    }
+  }
+
+  return /** @type {CliColorMode} */ (color_mode);
+}
+
+/**
+ * @param {CliOptionToken[]} option_tokens
+ * @returns {string | null}
+ */
+export function findInvalidColorMode(option_tokens) {
+  for (const token of option_tokens) {
+    if (
+      token.name === 'color' &&
+      typeof token.value === 'string' &&
+      !VALID_COLOR_MODES.has(token.value)
+    ) {
+      return 'Color must be one of "auto", "always", or "never".';
+    }
+  }
+
+  return null;
+}

package/lib/parse-cli-query-pagination.js

@@ -0,0 +1,49 @@
+/**
+ * @typedef {import('./parse-cli-arguments-helpers.js').CliOptionToken} CliOptionToken
+ * @typedef {import('./parse-cli-arguments-helpers.js').CliOptionValues} CliOptionValues
+ */
+
+/**
+ * @param {CliOptionValues} parsed_values
+ * @returns {{ query_limit?: number, query_offset?: number }}
+ */
+export function buildQueryPagination(parsed_values) {
+  /** @type {{ query_limit?: number, query_offset?: number }} */
+  const query_pagination = {};
+
+  if (parsed_values.limit !== undefined) {
+    query_pagination.query_limit = Number(parsed_values.limit);
+  }
+
+  if (parsed_values.offset !== undefined) {
+    query_pagination.query_offset = Number(parsed_values.offset);
+  }
+
+  return query_pagination;
+}
+
+/**
+ * @param {CliOptionToken[]} option_tokens
+ * @returns {string | null}
+ */
+export function findInvalidQueryPagination(option_tokens) {
+  for (const token of option_tokens) {
+    if (
+      token.name === 'offset' &&
+      typeof token.value === 'string' &&
+      !/^\d+$/du.test(token.value)
+    ) {
+      return 'Offset must be a non-negative integer.';
+    }
+
+    if (
+      token.name === 'limit' &&
+      typeof token.value === 'string' &&
+      !/^\d+$/du.test(token.value)
+    ) {
+      return 'Limit must be a non-negative integer.';
+    }
+  }
+
+  return null;
+}

package/lib/parse-jsdoc-blocks.js

@@ -0,0 +1,184 @@
+/**
+ * Collect JSDoc blocks and their activated `@patram` markers.
+ *
+ * @param {string} source_text
+ * @returns {Array<{ activation_column: number | null, activation_line: number | null, lines: Array<{ column: number, content: string, line: number }> }>}
+ */
+export function collectJsdocBlocks(source_text) {
+  const source_lines = source_text.split('\n');
+  /** @type {Array<{ activation_column: number | null, activation_line: number | null, lines: Array<{ column: number, content: string, line: number }> }>} */
+  const jsdoc_blocks = [];
+
+  for (let line_index = 0; line_index < source_lines.length; line_index += 1) {
+    if (!source_lines[line_index].includes('/**')) {
+      continue;
+    }
+
+    const closing_line_index = findJsdocClosingLineIndex(
+      source_lines,
+      line_index,
+    );
+
+    if (closing_line_index < 0) {
+      break;
+    }
+
+    const block_lines = source_lines
+      .slice(line_index, closing_line_index + 1)
+      .map((raw_line, block_line_index) =>
+        createJsdocBlockLine(
+          raw_line,
+          line_index + block_line_index + 1,
+          block_line_index === 0,
+          line_index + block_line_index === closing_line_index,
+        ),
+      );
+    const activation_line = block_lines.find((block_line) =>
+      /^@patram(?:\s|$)/du.test(block_line.content),
+    );
+
+    jsdoc_blocks.push({
+      activation_column: activation_line?.column ?? null,
+      activation_line: activation_line?.line ?? null,
+      lines: block_lines,
+    });
+    line_index = closing_line_index;
+  }
+
+  return jsdoc_blocks;
+}
+
+/**
+ * @param {string[]} source_lines
+ * @param {number} start_line_index
+ * @returns {number}
+ */
+function findJsdocClosingLineIndex(source_lines, start_line_index) {
+  for (
+    let line_index = start_line_index;
+    line_index < source_lines.length;
+    line_index += 1
+  ) {
+    const source_line = source_lines[line_index];
+    const search_start =
+      line_index === start_line_index ? source_line.indexOf('/**') + 3 : 0;
+
+    if (source_line.indexOf('*/', search_start) >= 0) {
+      return line_index;
+    }
+  }
+
+  return -1;
+}
+
+/**
+ * @param {string} raw_line
+ * @param {number} line_number
+ * @param {boolean} is_first_line
+ * @param {boolean} is_last_line
+ * @returns {{ column: number, content: string, line: number }}
+ */
+function createJsdocBlockLine(
+  raw_line,
+  line_number,
+  is_first_line,
+  is_last_line,
+) {
+  if (isLastClosingLine(raw_line, is_first_line, is_last_line)) {
+    return {
+      column: raw_line.indexOf('*/') + 1,
+      content: '',
+      line: line_number,
+    };
+  }
+
+  const line_parts = is_first_line
+    ? extractFirstJsdocLineContent(raw_line, is_last_line)
+    : extractFollowingJsdocLineContent(raw_line, is_last_line);
+
+  return {
+    column: line_parts.column,
+    content: line_parts.content.trim(),
+    line: line_number,
+  };
+}
+
+/**
+ * @param {string} raw_line
+ * @param {boolean} is_first_line
+ * @param {boolean} is_last_line
+ * @returns {boolean}
+ */
+function isLastClosingLine(raw_line, is_first_line, is_last_line) {
+  return is_last_line && !is_first_line && /^\s*\*\/\s*$/du.test(raw_line);
+}
+
+/**
+ * @param {string} raw_line
+ * @param {boolean} is_last_line
+ * @returns {{ column: number, content: string }}
+ */
+function extractFirstJsdocLineContent(raw_line, is_last_line) {
+  const start_index = raw_line.indexOf('/**');
+  let line_content = raw_line.slice(start_index + 3);
+  let column = start_index + 4;
+
+  if (line_content.startsWith(' ')) {
+    line_content = line_content.slice(1);
+    column += 1;
+  }
+
+  return finalizeJsdocLineContent(line_content, column, is_last_line);
+}
+
+/**
+ * @param {string} raw_line
+ * @param {boolean} is_last_line
+ * @returns {{ column: number, content: string }}
+ */
+function extractFollowingJsdocLineContent(raw_line, is_last_line) {
+  const prefix_match = raw_line.match(/^\s*\*\s?/du);
+  const prefix_length = prefix_match ? prefix_match[0].length : 0;
+  const line_content = raw_line.slice(prefix_length);
+
+  return finalizeJsdocLineContent(
+    line_content,
+    prefix_length + 1,
+    is_last_line,
+  );
+}
+
+/**
+ * @param {string} line_content
+ * @param {number} column
+ * @param {boolean} is_last_line
+ * @returns {{ column: number, content: string }}
+ */
+function finalizeJsdocLineContent(line_content, column, is_last_line) {
+  const trimmed_line_content = is_last_line
+    ? removeJsdocClosingDelimiter(line_content)
+    : line_content;
+  const leading_whitespace_match = trimmed_line_content.match(/^\s*/du);
+  const leading_whitespace_length = leading_whitespace_match
+    ? leading_whitespace_match[0].length
+    : 0;
+
+  return {
+    column: column + leading_whitespace_length,
+    content: trimmed_line_content,
+  };
+}
+
+/**
+ * @param {string} line_content
+ * @returns {string}
+ */
+function removeJsdocClosingDelimiter(line_content) {
+  const closing_index = line_content.indexOf('*/');
+
+  if (closing_index < 0) {
+    return line_content;
+  }
+
+  return line_content.slice(0, closing_index);
+}