patram 0.0.2 → 0.2.0

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

package/lib/parse-markdown-directives.js

@@ -0,0 +1,136 @@
+/**
+ * @import { PatramClaimFields } from './parse-claims.types.ts';
+ */
+
+const FRONT_MATTER_BOUNDARY_PATTERN = /^---$/du;
+const FRONT_MATTER_DIRECTIVE_PATTERN = /^([A-Za-z][A-Za-z0-9 _-]*):\s+(.+)$/du;
+const MARKDOWN_HIDDEN_DIRECTIVE_PATTERN =
+  /^\[patram\s+([A-Za-z][A-Za-z0-9 _-]*)=(.+)\]:\s*#\s*$/du;
+const VISIBLE_DIRECTIVE_PATTERN = /^(?:-\s+)?([A-Z][A-Za-z _-]*):\s+(.+)$/du;
+
+/**
+ * @param {string} file_path
+ * @param {string[]} lines
+ * @returns {{ body_start: number, directive_fields: PatramClaimFields[] }}
+ */
+export function parseFrontMatterDirectiveFields(file_path, lines) {
+  if (lines[0] !== '---') {
+    return {
+      body_start: 0,
+      directive_fields: [],
+    };
+  }
+
+  const closing_line_index = findFrontMatterClosingLineIndex(lines);
+
+  if (closing_line_index < 0) {
+    return {
+      body_start: 0,
+      directive_fields: [],
+    };
+  }
+
+  /** @type {PatramClaimFields[]} */
+  const directive_fields = [];
+
+  for (let line_index = 1; line_index < closing_line_index; line_index += 1) {
+    const directive_fields_match = matchDirectiveFields(
+      FRONT_MATTER_DIRECTIVE_PATTERN,
+      file_path,
+      lines[line_index],
+      line_index + 1,
+    );
+
+    if (!directive_fields_match) {
+      continue;
+    }
+
+    directive_fields.push(directive_fields_match);
+  }
+
+  return {
+    body_start: closing_line_index + 1,
+    directive_fields,
+  };
+}
+
+/**
+ * @param {string} file_path
+ * @param {string} line
+ * @param {number} line_number
+ * @returns {PatramClaimFields | null}
+ */
+export function matchVisibleDirectiveFields(file_path, line, line_number) {
+  return matchDirectiveFields(
+    VISIBLE_DIRECTIVE_PATTERN,
+    file_path,
+    line,
+    line_number,
+  );
+}
+
+/**
+ * @param {string} file_path
+ * @param {string} line
+ * @param {number} line_number
+ * @returns {PatramClaimFields | null}
+ */
+export function matchHiddenDirectiveFields(file_path, line, line_number) {
+  return matchDirectiveFields(
+    MARKDOWN_HIDDEN_DIRECTIVE_PATTERN,
+    file_path,
+    line,
+    line_number,
+  );
+}
+
+/**
+ * @param {string[]} lines
+ * @returns {number}
+ */
+function findFrontMatterClosingLineIndex(lines) {
+  for (let line_index = 1; line_index < lines.length; line_index += 1) {
+    if (FRONT_MATTER_BOUNDARY_PATTERN.test(lines[line_index])) {
+      return line_index;
+    }
+  }
+
+  return -1;
+}
+
+/**
+ * @param {RegExp} pattern
+ * @param {string} file_path
+ * @param {string} line
+ * @param {number} line_number
+ * @returns {PatramClaimFields | null}
+ */
+function matchDirectiveFields(pattern, file_path, line, line_number) {
+  const directive_match = line.match(pattern);
+
+  if (!directive_match) {
+    return null;
+  }
+
+  return {
+    name: normalizeDirectiveName(directive_match[1]),
+    origin: {
+      column: 1,
+      line: line_number,
+      path: file_path,
+    },
+    parser: 'markdown',
+    value: directive_match[2].trim(),
+  };
+}
+
+/**
+ * @param {string} directive_label
+ * @returns {string}
+ */
+export function normalizeDirectiveName(directive_label) {
+  return directive_label
+    .trim()
+    .toLowerCase()
+    .replaceAll(/[\s-]+/dgu, '_');
+}