patram 0.0.2 → 0.1.1

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,
+  };
+}

package/lib/parse-jsdoc-prose.js

@@ -0,0 +1,111 @@
+/**
+ * @import { PatramClaimFields } from './parse-claims.types.ts';
+ */
+
+const JSDOC_SENTENCE_PATTERN = /^(.+?[.!?])(?:\s+|$)([\s\S]*)$/du;
+const JSDOC_TITLE_LENGTH_LIMIT = 120;
+
+/**
+ * @param {Array<Array<{ column: number, content: string, line: number }>>} prose_paragraphs
+ * @param {Array<{ column: number, content: string, line: number }>} paragraph_lines
+ */
+export function pushJsdocParagraph(prose_paragraphs, paragraph_lines) {
+  if (paragraph_lines.length > 0) {
+    prose_paragraphs.push(paragraph_lines);
+  }
+}
+
+/**
+ * @param {string} file_path
+ * @param {Array<Array<{ column: number, content: string, line: number }>>} prose_paragraphs
+ * @returns {Array<{ claim_fields: PatramClaimFields, claim_type: string, order: number }>}
+ */
+export function createJsdocProseClaimEntries(file_path, prose_paragraphs) {
+  if (prose_paragraphs.length === 0) {
+    return [];
+  }
+
+  const first_paragraph = prose_paragraphs[0];
+  const first_origin = {
+    column: first_paragraph[0].column,
+    line: first_paragraph[0].line,
+    path: file_path,
+  };
+  const title_result = splitJsdocParagraphTitle(
+    first_paragraph.map((line) => line.content).join(' '),
+  );
+  /** @type {Array<{ claim_fields: PatramClaimFields, claim_type: string, order: number }>} */
+  const claim_entries = [
+    {
+      claim_fields: {
+        origin: first_origin,
+        value: title_result.title,
+      },
+      claim_type: 'document.title',
+      order: 0,
+    },
+  ];
+  /** @type {string[]} */
+  const description_parts = [];
+  /** @type {{ column: number, line: number, path: string } | null} */
+  let description_origin = null;
+
+  if (title_result.remainder.length > 0) {
+    description_parts.push(title_result.remainder);
+    description_origin = first_origin;
+  }
+
+  for (const paragraph_lines of prose_paragraphs.slice(1)) {
+    if (description_origin === null) {
+      description_origin = {
+        column: paragraph_lines[0].column,
+        line: paragraph_lines[0].line,
+        path: file_path,
+      };
+    }
+
+    description_parts.push(
+      paragraph_lines.map((line) => line.content).join(' '),
+    );
+  }
+
+  if (description_origin && description_parts.length > 0) {
+    claim_entries.push({
+      claim_fields: {
+        origin: description_origin,
+        value: description_parts.join('\n\n'),
+      },
+      claim_type: 'document.description',
+      order: 1,
+    });
+  }
+
+  return claim_entries;
+}
+
+/**
+ * @param {string} paragraph_text
+ * @returns {{ remainder: string, title: string }}
+ */
+function splitJsdocParagraphTitle(paragraph_text) {
+  if (paragraph_text.length <= JSDOC_TITLE_LENGTH_LIMIT) {
+    return {
+      remainder: '',
+      title: paragraph_text,
+    };
+  }
+
+  const sentence_match = paragraph_text.match(JSDOC_SENTENCE_PATTERN);
+
+  if (!sentence_match) {
+    return {
+      remainder: '',
+      title: paragraph_text,
+    };
+  }
+
+  return {
+    remainder: sentence_match[2].trim(),
+    title: sentence_match[1].trim(),
+  };
+}

package/lib/parse-markdown-claims.js

@@ -0,0 +1,242 @@
+/**
+ * @import { PatramClaim, ParseClaimsInput, PatramClaimFields } from './parse-claims.types.ts';
+ */
+
+import { createClaim, isPathLikeTarget } from './claim-helpers.js';
+import {
+  matchHiddenDirectiveFields,
+  matchVisibleDirectiveFields,
+  parseFrontMatterDirectiveFields,
+} from './parse-markdown-directives.js';
+
+/**
+ * Markdown claim parsing.
+ *
+ * Extracts document titles, directives, and links from markdown source while
+ * ignoring fenced-code link noise.
+ *
+ * Kind: parse
+ * Status: active
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/markdown-metadata-directive-syntax.md
+ * Decided by: ../docs/decisions/markdown-link-claim-scope.md
+ * @patram
+ * @see {@link ./parse-claims.js}
+ * @see {@link ../docs/decisions/markdown-metadata-directive-syntax.md}
+ */
+
+const HEADING_PATTERN = /^#\s+(.+)$/du;
+const MARKDOWN_FENCE_PATTERN = /^([`~]{3,})/du;
+const MARKDOWN_LINK_PATTERN = /\[([^\]]+)\]\(([^)]+)\)/dgu;
+
+/**
+ * @param {ParseClaimsInput} parse_input
+ * @returns {PatramClaim[]}
+ */
+export function parseMarkdownClaims(parse_input) {
+  const lines = parse_input.source.split('\n');
+
+  /** @type {PatramClaim[]} */
+  const claims = [];
+  const front_matter_result = parseFrontMatterDirectiveFields(
+    parse_input.path,
+    lines,
+  );
+  /** @type {{ character: string, length: number } | null} */
+  let open_fence = null;
+  const title_result = getMarkdownTitle(lines, front_matter_result.body_start);
+
+  if (title_result) {
+    claims.push(
+      createClaim(parse_input.path, claims.length + 1, 'document.title', {
+        origin: {
+          column: 1,
+          line: title_result.line,
+          path: parse_input.path,
+        },
+        value: title_result.value,
+      }),
+    );
+  }
+
+  for (const directive_fields of front_matter_result.directive_fields) {
+    claims.push(
+      createClaim(parse_input.path, claims.length + 1, 'directive', {
+        ...directive_fields,
+      }),
+    );
+  }
+
+  for (const [line_index, line] of lines.entries()) {
+    if (line_index < front_matter_result.body_start) {
+      continue;
+    }
+
+    const line_number = line_index + 1;
+
+    if (open_fence) {
+      if (isClosingMarkdownFence(line, open_fence)) {
+        open_fence = null;
+      }
+
+      continue;
+    }
+
+    open_fence = parseOpeningMarkdownFence(line);
+
+    if (open_fence) {
+      continue;
+    }
+
+    collectMarkdownLinkClaims(parse_input.path, line, line_number, claims);
+    collectVisibleDirectiveClaims(parse_input.path, line, line_number, claims);
+    collectHiddenDirectiveClaims(parse_input.path, line, line_number, claims);
+  }
+
+  return claims;
+}
+
+/**
+ * @param {string} file_path
+ * @param {string} line
+ * @param {number} line_number
+ * @param {PatramClaim[]} claims
+ */
+function collectMarkdownLinkClaims(file_path, line, line_number, claims) {
+  for (const link_match of line.matchAll(MARKDOWN_LINK_PATTERN)) {
+    const link_text = link_match[1];
+    const target_value = link_match[2];
+
+    if (!isPathLikeTarget(target_value)) {
+      continue;
+    }
+
+    const column_number =
+      link_match.index === undefined ? 1 : link_match.index + 1;
+
+    claims.push(
+      createClaim(file_path, claims.length + 1, 'markdown.link', {
+        origin: {
+          column: column_number,
+          line: line_number,
+          path: file_path,
+        },
+        value: {
+          target: target_value,
+          text: link_text,
+        },
+      }),
+    );
+  }
+}
+
+/**
+ * @param {string} file_path
+ * @param {string} line
+ * @param {number} line_number
+ * @param {PatramClaim[]} claims
+ */
+function collectVisibleDirectiveClaims(file_path, line, line_number, claims) {
+  const directive_fields = matchVisibleDirectiveFields(
+    file_path,
+    line,
+    line_number,
+  );
+
+  if (directive_fields) {
+    pushDirectiveClaim(file_path, claims, directive_fields);
+  }
+}
+
+/**
+ * @param {string} file_path
+ * @param {string} line
+ * @param {number} line_number
+ * @param {PatramClaim[]} claims
+ */
+function collectHiddenDirectiveClaims(file_path, line, line_number, claims) {
+  const directive_fields = matchHiddenDirectiveFields(
+    file_path,
+    line,
+    line_number,
+  );
+
+  if (directive_fields) {
+    pushDirectiveClaim(file_path, claims, directive_fields);
+  }
+}
+
+/**
+ * @param {string[]} lines
+ * @param {number} start_line_index
+ * @returns {{ line: number, value: string } | null}
+ */
+function getMarkdownTitle(lines, start_line_index) {
+  const first_line = lines[start_line_index];
+
+  if (first_line === undefined) {
+    return null;
+  }
+
+  const trimmed_line = first_line.trim();
+
+  if (trimmed_line.length === 0) {
+    return null;
+  }
+
+  const heading_match = trimmed_line.match(HEADING_PATTERN);
+
+  if (heading_match) {
+    return {
+      line: start_line_index + 1,
+      value: heading_match[1].trim(),
+    };
+  }
+
+  return {
+    line: start_line_index + 1,
+    value: trimmed_line,
+  };
+}
+
+/**
+ * @param {string} line
+ * @returns {{ character: string, length: number } | null}
+ */
+function parseOpeningMarkdownFence(line) {
+  const trimmed_line = line.trimStart();
+  const fence_match = trimmed_line.match(MARKDOWN_FENCE_PATTERN);
+
+  if (!fence_match) {
+    return null;
+  }
+
+  return {
+    character: fence_match[1][0],
+    length: fence_match[1].length,
+  };
+}
+
+/**
+ * @param {string} line
+ * @param {{ character: string, length: number }} open_fence
+ * @returns {boolean}
+ */
+function isClosingMarkdownFence(line, open_fence) {
+  const trimmed_line = line.trimStart();
+
+  return trimmed_line.startsWith(
+    open_fence.character.repeat(open_fence.length),
+  );
+}
+
+/**
+ * @param {string} file_path
+ * @param {PatramClaim[]} claims
+ * @param {PatramClaimFields} directive_fields
+ */
+function pushDirectiveClaim(file_path, claims, directive_fields) {
+  claims.push(
+    createClaim(file_path, claims.length + 1, 'directive', directive_fields),
+  );
+}