patram 0.0.2 → 0.2.0

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

@@ -0,0 +1,69 @@
+export type CliCommandName = 'check' | 'query' | 'queries' | 'show';
+export type CliHelpTopicName = 'query-language';
+export type CliHelpTargetKind = 'root' | 'command' | 'topic';
+
+export type CliOutputMode = 'default' | 'plain' | 'json';
+
+export type CliColorMode = 'auto' | 'always' | 'never';
+
+export interface ParsedCliCommandRequest {
+  kind?: 'command';
+  color_mode: CliColorMode;
+  command_arguments: string[];
+  command_name: CliCommandName;
+  output_mode: CliOutputMode;
+  query_inspection_mode?: 'explain' | 'lint';
+  query_limit?: number;
+  query_offset?: number;
+}
+
+export interface ParsedCliHelpRequest {
+  kind: 'help';
+  target_kind: CliHelpTargetKind;
+  target_name?: CliCommandName | CliHelpTopicName;
+}
+
+export type ParsedCliArguments = ParsedCliCommandRequest;
+export type ParsedCliRequest = ParsedCliCommandRequest | ParsedCliHelpRequest;
+
+export type CliParseError =
+  | {
+      code: 'message';
+      message: string;
+    }
+  | {
+      code: 'missing_required_argument';
+      argument_label: string;
+      command_name: 'query' | 'show';
+    }
+  | {
+      code: 'option_not_valid_for_command';
+      command_name: CliCommandName;
+      token: string;
+    }
+  | {
+      code: 'unknown_command';
+      suggestion?: CliCommandName;
+      token: string;
+    }
+  | {
+      code: 'unknown_help_target';
+      suggestion?: CliCommandName | CliHelpTopicName;
+      token: string;
+    }
+  | {
+      code: 'unknown_option';
+      command_name?: CliCommandName;
+      suggestion?: string;
+      token: string;
+    };
+
+export type ParseCliArgumentsResult =
+  | {
+      success: true;
+      value: ParsedCliRequest;
+    }
+  | {
+      error: CliParseError;
+      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);
+}

package/lib/parse-jsdoc-claims.js

@@ -0,0 +1,280 @@
+/** @import * as $k$$l$load$j$patram$j$config$k$types$k$ts from './load-patram-config.types.ts'; */
+/**
+ * @import { ParseClaimsInput, ParseSourceFileResult, PatramClaim, PatramClaimFields } from './parse-claims.types.ts';
+ */
+
+import {
+  createClaim,
+  getFileExtension,
+  isPathLikeTarget,
+} from './claim-helpers.js';
+import { normalizeDirectiveName } from './parse-markdown-directives.js';
+import { collectJsdocBlocks } from './parse-jsdoc-blocks.js';
+import {
+  createJsdocProseClaimEntries,
+  pushJsdocParagraph,
+} from './parse-jsdoc-prose.js';
+import { JSDOC_SOURCE_FILE_EXTENSIONS } from './source-file-defaults.js';
+
+/**
+ * JSDoc @patram claim parsing.
+ *
+ * Activates one source anchor block, extracts directives and links, and
+ * derives title and description claims from prose.
+ *
+ * Kind: parse
+ * Status: active
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/jsdoc-metadata-directive-syntax.md
+ * @patram
+ * @see {@link ./parse-claims.js}
+ * @see {@link ../docs/decisions/jsdoc-metadata-directive-syntax.md}
+ */
+
+const JSDOC_EXTENSIONS = new Set(JSDOC_SOURCE_FILE_EXTENSIONS);
+const JSDOC_LINK_TAG_PATTERN = /^@(link|see)\s+(.+)$/du;
+const JSDOC_TAG_PATTERN = /^@[A-Za-z]+(?:\s|$)/du;
+const JSDOC_VISIBLE_DIRECTIVE_PATTERN = /^([A-Z][A-Za-z _-]*):\s+(.+)$/du;
+
+/**
+ * Parse JSDoc metadata claims from one source file.
+ *
+ * @param {ParseClaimsInput} parse_input
+ * @returns {ParseSourceFileResult}
+ */
+export function parseJsdocClaims(parse_input) {
+  if (!JSDOC_EXTENSIONS.has(getFileExtension(parse_input.path))) {
+    return {
+      claims: [],
+      diagnostics: [],
+    };
+  }
+
+  const jsdoc_blocks = collectJsdocBlocks(parse_input.source);
+  const active_blocks = jsdoc_blocks.filter(
+    (jsdoc_block) => jsdoc_block.activation_line !== null,
+  );
+
+  if (active_blocks.length === 0) {
+    return {
+      claims: [],
+      diagnostics: [],
+    };
+  }
+
+  const claim_entries = collectJsdocClaimEntries(
+    parse_input.path,
+    active_blocks[0],
+  ).sort(compareClaimEntries);
+
+  return {
+    claims: claim_entries.map((claim_entry, claim_index) =>
+      createClaim(
+        parse_input.path,
+        claim_index + 1,
+        claim_entry.claim_type,
+        claim_entry.claim_fields,
+      ),
+    ),
+    diagnostics: active_blocks
+      .slice(1)
+      .map((active_block) =>
+        createMultiplePatramBlocksDiagnostic(parse_input.path, active_block),
+      ),
+  };
+}
+
+/**
+ * @param {string} file_path
+ * @param {{ lines: Array<{ column: number, content: string, line: number }> }} jsdoc_block
+ * @returns {Array<{ claim_fields: PatramClaimFields, claim_type: string, order: number }>}
+ */
+function collectJsdocClaimEntries(file_path, jsdoc_block) {
+  /** @type {Array<{ claim_fields: PatramClaimFields, claim_type: string, order: number }>} */
+  const claim_entries = [];
+  /** @type {Array<Array<{ column: number, content: string, line: number }>>} */
+  const prose_paragraphs = [];
+  /** @type {Array<{ column: number, content: string, line: number }>} */
+  let current_paragraph_lines = [];
+
+  for (const block_line of jsdoc_block.lines) {
+    if (block_line.content.length === 0) {
+      pushJsdocParagraph(prose_paragraphs, current_paragraph_lines);
+      current_paragraph_lines = [];
+      continue;
+    }
+
+    const directive_fields = matchJsdocDirectiveFields(file_path, block_line);
+
+    if (directive_fields) {
+      pushJsdocParagraph(prose_paragraphs, current_paragraph_lines);
+      current_paragraph_lines = [];
+      claim_entries.push({
+        claim_fields: directive_fields,
+        claim_type: 'directive',
+        order: 0,
+      });
+      continue;
+    }
+
+    const jsdoc_link_claim_entry = createJsdocLinkClaimEntry(
+      file_path,
+      block_line,
+    );
+
+    if (jsdoc_link_claim_entry) {
+      pushJsdocParagraph(prose_paragraphs, current_paragraph_lines);
+      current_paragraph_lines = [];
+      claim_entries.push(jsdoc_link_claim_entry);
+      continue;
+    }
+
+    if (JSDOC_TAG_PATTERN.test(block_line.content)) {
+      pushJsdocParagraph(prose_paragraphs, current_paragraph_lines);
+      current_paragraph_lines = [];
+      continue;
+    }
+
+    current_paragraph_lines.push(block_line);
+  }
+
+  pushJsdocParagraph(prose_paragraphs, current_paragraph_lines);
+  claim_entries.push(
+    ...createJsdocProseClaimEntries(file_path, prose_paragraphs),
+  );
+
+  return claim_entries;
+}
+
+/**
+ * @param {string} file_path
+ * @param {{ column: number, content: string, line: number }} block_line
+ * @returns {PatramClaimFields | null}
+ */
+function matchJsdocDirectiveFields(file_path, block_line) {
+  const directive_match = block_line.content.match(
+    JSDOC_VISIBLE_DIRECTIVE_PATTERN,
+  );
+
+  if (!directive_match) {
+    return null;
+  }
+
+  return {
+    name: normalizeDirectiveName(directive_match[1]),
+    origin: {
+      column: block_line.column,
+      line: block_line.line,
+      path: file_path,
+    },
+    parser: 'jsdoc',
+    value: directive_match[2].trim(),
+  };
+}
+
+/**
+ * @param {string} file_path
+ * @param {{ column: number, content: string, line: number }} block_line
+ * @returns {{ claim_fields: PatramClaimFields, claim_type: string, order: number } | null}
+ */
+function createJsdocLinkClaimEntry(file_path, block_line) {
+  const link_match = block_line.content.match(JSDOC_LINK_TAG_PATTERN);
+
+  if (!link_match) {
+    return null;
+  }
+
+  const link_value = parseJsdocLinkValue(link_match[2].trim());
+
+  if (!link_value) {
+    return null;
+  }
+
+  return {
+    claim_fields: {
+      origin: {
+        column: block_line.column,
+        line: block_line.line,
+        path: file_path,
+      },
+      value: link_value,
+    },
+    claim_type: 'jsdoc.link',
+    order: 0,
+  };
+}
+
+/**
+ * @param {string} raw_value
+ * @returns {{ target: string, text: string } | null}
+ */
+function parseJsdocLinkValue(raw_value) {
+  const inline_link_match = raw_value.match(
+    /^\{@link\s+([^}\s]+)(?:\s+([^}]+))?\}$/du,
+  );
+
+  if (inline_link_match) {
+    const target_value = inline_link_match[1];
+    const label_value = inline_link_match[2]?.trim();
+
+    if (!isPathLikeTarget(target_value)) {
+      return null;
+    }
+
+    return {
+      target: target_value,
+      text: label_value && label_value.length > 0 ? label_value : target_value,
+    };
+  }
+
+  const [target_value, ...label_parts] = raw_value.split(/\s+/du);
+
+  if (!target_value || !isPathLikeTarget(target_value)) {
+    return null;
+  }
+
+  return {
+    target: target_value,
+    text: label_parts.length > 0 ? label_parts.join(' ') : target_value,
+  };
+}
+
+/**
+ * @param {{ claim_fields: PatramClaimFields, claim_type: string, order: number }} left_entry
+ * @param {{ claim_fields: PatramClaimFields, claim_type: string, order: number }} right_entry
+ * @returns {number}
+ */
+function compareClaimEntries(left_entry, right_entry) {
+  const left_origin = left_entry.claim_fields.origin;
+  const right_origin = right_entry.claim_fields.origin;
+
+  if (!left_origin || !right_origin) {
+    return left_entry.order - right_entry.order;
+  }
+
+  if (left_origin.line !== right_origin.line) {
+    return left_origin.line - right_origin.line;
+  }
+
+  if (left_origin.column !== right_origin.column) {
+    return left_origin.column - right_origin.column;
+  }
+
+  return left_entry.order - right_entry.order;
+}
+
+/**
+ * @param {string} file_path
+ * @param {{ activation_column: number | null, activation_line: number | null }} jsdoc_block
+ * @returns {$k$$l$load$j$patram$j$config$k$types$k$ts.PatramDiagnostic}
+ */
+function createMultiplePatramBlocksDiagnostic(file_path, jsdoc_block) {
+  return {
+    code: 'jsdoc.multiple_patram_blocks',
+    column: jsdoc_block.activation_column ?? 1,
+    level: 'error',
+    line: jsdoc_block.activation_line ?? 1,
+    message: `File "${file_path}" contains multiple JSDoc blocks with "@patram".`,
+    path: file_path,
+  };
+}